From d59d39d8bc93a48c9a2c36d2ce7ef65d97f03e90 Mon Sep 17 00:00:00 2001
From: Akash-N- Pai <akashvn.pai@gmail.com>
Date: Sun, 1 Feb 2026 21:49:17 -0600
Subject: [PATCH] Add AGENTS.md validator feature

Implements a web-based validator at /validator that provides real-time,
non-blocking suggestions to help users write better AGENTS.md files.

Features:
- Real-time validation with helpful suggestions (not strict rules)
- Quality scoring (0-100) with visual feedback
- Live markdown preview with syntax highlighting
- Expandable suggestion cards with copy-to-clipboard examples
- Checks for length, common sections, command formatting, version specificity
- Responsive design with dark mode support
- Integration with homepage (validator CTA button) and footer navigation

Co-Authored-By: Akash Pai <akashvn.pai@gmail.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 components/Footer.tsx           |  18 +++
 components/Hero.tsx             |  13 +-
 components/ValidatorInput.tsx   |  33 ++++
 components/ValidatorPreview.tsx |  90 +++++++++++
 components/ValidatorResults.tsx | 219 ++++++++++++++++++++++++++
 lib/markdownParser.ts           | 172 ++++++++++++++++++++
 lib/validationRules.ts          | 271 ++++++++++++++++++++++++++++++++
 lib/validator.ts                | 164 +++++++++++++++++++
 pages/validator.tsx             | 177 +++++++++++++++++++++
 9 files changed, 1154 insertions(+), 3 deletions(-)
 create mode 100644 components/ValidatorInput.tsx
 create mode 100644 components/ValidatorPreview.tsx
 create mode 100644 components/ValidatorResults.tsx
 create mode 100644 lib/markdownParser.ts
 create mode 100644 lib/validationRules.ts
 create mode 100644 lib/validator.ts
 create mode 100644 pages/validator.tsx

diff --git a/components/Footer.tsx b/components/Footer.tsx
index 056fd4a..9eb582f 100644
--- a/components/Footer.tsx
+++ b/components/Footer.tsx
@@ -3,6 +3,24 @@ import React from "react";
 export default function Footer() {
   return (
     <footer className="px-6 py-12 text-center text-sm text-gray-600 dark:text-gray-400 mt-24 bg-gray-50 dark:bg-gray-900/40 border-t border-gray-100 dark:border-gray-800">
+      <div className="max-w-4xl mx-auto mb-6">
+        <nav className="flex justify-center gap-6 flex-wrap">
+          <a href="/" className="hover:text-gray-900 dark:hover:text-gray-200 transition-colors">
+            Home
+          </a>
+          <a href="/validator" className="hover:text-gray-900 dark:hover:text-gray-200 transition-colors">
+            Validator
+          </a>
+          <a
+            href="https://github.com/agentsmd/agents.md"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="hover:text-gray-900 dark:hover:text-gray-200 transition-colors"
+          >
+            GitHub
+          </a>
+        </nav>
+      </div>
       <p>
         Copyright © AGENTS.md a Series of LF Projects, LLC
         <br />
diff --git a/components/Hero.tsx b/components/Hero.tsx
index fe07675..eb8d43e 100644
--- a/components/Hero.tsx
+++ b/components/Hero.tsx
@@ -38,14 +38,21 @@ export default function Hero() {
           </p>
 
         <div className="mt-6 flex gap-4 flex-col sm:flex-row w-full sm:w-auto justify-center sm:justify-start">
-          {/* Primary CTA — scroll to the Examples section */}
+          {/* Primary CTA — validator */}
           <a
-            href="#examples"
+            href="/validator"
             className="inline-block px-5 py-3 rounded-full bg-black text-white dark:bg-white dark:text-black text-sm font-medium text-center hover:opacity-80"
+          >
+            Validate Your AGENTS.md
+          </a>
+          {/* Secondary CTA — scroll to the Examples section */}
+          <a
+            href="#examples"
+            className="inline-flex items-center justify-center gap-2 px-5 py-3 rounded-full border border-gray-300 dark:border-gray-600 text-sm font-medium text-gray-900 dark:text-gray-100 hover:bg-gray-100 dark:hover:bg-gray-800"
           >
             Explore Examples
           </a>
-          {/* Secondary CTA — view on GitHub */}
+          {/* Tertiary CTA — view on GitHub */}
           <a
             href="https://github.com/agentsmd/agents.md"
             target="_blank"
diff --git a/components/ValidatorInput.tsx b/components/ValidatorInput.tsx
new file mode 100644
index 0000000..3c72502
--- /dev/null
+++ b/components/ValidatorInput.tsx
@@ -0,0 +1,33 @@
+import React from 'react';
+
+interface ValidatorInputProps {
+  value: string;
+  onChange: (value: string) => void;
+  placeholder?: string;
+}
+
+/**
+ * Textarea component for AGENTS.md input
+ */
+export default function ValidatorInput({ value, onChange, placeholder }: ValidatorInputProps) {
+  const lineCount = value.split('\n').length;
+  const charCount = value.length;
+
+  return (
+    <div className="flex flex-col h-full">
+      <div className="flex justify-between items-center mb-2 text-sm text-gray-600 dark:text-gray-400">
+        <label className="font-medium">Your AGENTS.md content</label>
+        <div className="text-xs">
+          {lineCount} lines · {charCount} characters
+        </div>
+      </div>
+      <textarea
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={placeholder}
+        className="flex-1 w-full p-4 rounded-lg bg-white dark:bg-black text-gray-800 dark:text-gray-100 text-sm font-mono leading-6 border border-gray-200 dark:border-gray-700 focus:outline-none focus:ring-2 focus:ring-gray-400 dark:focus:ring-gray-600 resize-none shadow-sm"
+        spellCheck={false}
+      />
+    </div>
+  );
+}
diff --git a/components/ValidatorPreview.tsx b/components/ValidatorPreview.tsx
new file mode 100644
index 0000000..c3f041b
--- /dev/null
+++ b/components/ValidatorPreview.tsx
@@ -0,0 +1,90 @@
+import React from 'react';
+
+interface ValidatorPreviewProps {
+  content: string;
+}
+
+/**
+ * Live preview of AGENTS.md content with syntax highlighting
+ */
+export default function ValidatorPreview({ content }: ValidatorPreviewProps) {
+  /**
+   * Very lightly highlight the Markdown without fully parsing it.
+   */
+  function parseMarkdown(md: string): React.ReactNode[] {
+    const lines = md.split('\n');
+    const elements: React.ReactNode[] = [];
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // Handle headers
+      if (line.startsWith('# ') || line.startsWith('## ') || line.startsWith('### ')) {
+        elements.push(
+          <div key={i} className="font-bold">
+            {line}
+          </div>
+        );
+      } else if (line.startsWith('- ')) {
+        // Handle list items with inline code
+        elements.push(<div key={i}>{renderLineWithInlineCode(line)}</div>);
+      } else if (line.trim() === '') {
+        // Handle empty lines
+        elements.push(<div key={i}>&nbsp;</div>);
+      } else {
+        // Handle regular lines with inline code
+        elements.push(<div key={i}>{renderLineWithInlineCode(line)}</div>);
+      }
+    }
+
+    return elements;
+  }
+
+  /**
+   * Render a line with inline code highlighting
+   */
+  function renderLineWithInlineCode(line: string): React.ReactNode {
+    const parts = line.split(/(`[^`]+`)/g);
+
+    return parts.map((part, index) => {
+      if (part.startsWith('`') && part.endsWith('`')) {
+        // This is inline code
+        return (
+          <span key={index} className="bg-gray-200 dark:bg-gray-800 px-1 rounded">
+            {part}
+          </span>
+        );
+      }
+      // Regular text
+      return part;
+    });
+  }
+
+  if (!content || content.trim().length === 0) {
+    return (
+      <div className="flex flex-col h-full">
+        <div className="mb-2 text-sm text-gray-600 dark:text-gray-400 font-medium">
+          Preview
+        </div>
+        <div className="flex-1 rounded-lg bg-white dark:bg-black border border-gray-200 dark:border-gray-700 p-4 flex items-center justify-center shadow-sm">
+          <p className="text-gray-400 dark:text-gray-600 text-sm">
+            Your preview will appear here
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex flex-col h-full">
+      <div className="mb-2 text-sm text-gray-600 dark:text-gray-400 font-medium">
+        Preview
+      </div>
+      <div className="flex-1 overflow-y-auto rounded-lg bg-white dark:bg-black border border-gray-200 dark:border-gray-700 shadow-sm">
+        <pre className="p-4 text-xs leading-6 text-gray-800 dark:text-gray-100">
+          <code>{parseMarkdown(content)}</code>
+        </pre>
+      </div>
+    </div>
+  );
+}
diff --git a/components/ValidatorResults.tsx b/components/ValidatorResults.tsx
new file mode 100644
index 0000000..0087a15
--- /dev/null
+++ b/components/ValidatorResults.tsx
@@ -0,0 +1,219 @@
+import React from 'react';
+import { ValidationSuggestion } from '@/lib/validationRules';
+import CopyIcon from './icons/CopyIcon';
+
+interface ValidatorResultsProps {
+  suggestions: ValidationSuggestion[];
+  score: number;
+  summary: string;
+}
+
+/**
+ * Display validation results with suggestions
+ */
+export default function ValidatorResults({ suggestions, score, summary }: ValidatorResultsProps) {
+  const [expandedIndex, setExpandedIndex] = React.useState<number | null>(null);
+  const [copiedIndex, setCopiedIndex] = React.useState<number | null>(null);
+
+  const toggleExpand = (index: number) => {
+    setExpandedIndex(expandedIndex === index ? null : index);
+  };
+
+  const copyExample = async (example: string, index: number) => {
+    try {
+      await navigator.clipboard.writeText(example);
+      setCopiedIndex(index);
+      setTimeout(() => setCopiedIndex(null), 2000);
+    } catch (err) {
+      console.error('Failed to copy:', err);
+    }
+  };
+
+  // Determine score color
+  const getScoreColor = (score: number) => {
+    if (score >= 80) return 'text-green-600 dark:text-green-400';
+    if (score >= 60) return 'text-yellow-600 dark:text-yellow-400';
+    return 'text-orange-600 dark:text-orange-400';
+  };
+
+  // Determine score background
+  const getScoreBg = (score: number) => {
+    if (score >= 80) return 'bg-green-50 dark:bg-green-900/20';
+    if (score >= 60) return 'bg-yellow-50 dark:bg-yellow-900/20';
+    return 'bg-orange-50 dark:bg-orange-900/20';
+  };
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Score and summary */}
+      <div className={`p-4 rounded-lg mb-4 ${getScoreBg(score)}`}>
+        <div className="flex items-center justify-between mb-2">
+          <h3 className="text-sm font-semibold text-gray-900 dark:text-gray-100">
+            Validation Results
+          </h3>
+          <div className={`text-2xl font-bold ${getScoreColor(score)}`}>
+            {score}/100
+          </div>
+        </div>
+        <p className="text-sm text-gray-700 dark:text-gray-300">{summary}</p>
+      </div>
+
+      {/* Suggestions list */}
+      <div className="flex-1 overflow-y-auto space-y-3">
+        {suggestions.length === 0 ? (
+          <div className="text-center py-8 text-gray-500 dark:text-gray-400">
+            <p>Paste your AGENTS.md content to see suggestions.</p>
+          </div>
+        ) : (
+          suggestions.map((suggestion, index) => (
+            <div
+              key={index}
+              className="border border-gray-200 dark:border-gray-700 rounded-lg overflow-hidden bg-white dark:bg-gray-900"
+            >
+              <button
+                onClick={() => toggleExpand(index)}
+                className="w-full p-4 text-left hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors"
+              >
+                <div className="flex items-start gap-3">
+                  {/* Icon based on type */}
+                  <div className="flex-shrink-0 mt-0.5">
+                    {suggestion.type === 'success' ? (
+                      <svg
+                        className="w-5 h-5 text-green-500"
+                        fill="none"
+                        stroke="currentColor"
+                        viewBox="0 0 24 24"
+                      >
+                        <path
+                          strokeLinecap="round"
+                          strokeLinejoin="round"
+                          strokeWidth={2}
+                          d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z"
+                        />
+                      </svg>
+                    ) : suggestion.type === 'info' ? (
+                      <svg
+                        className="w-5 h-5 text-blue-500"
+                        fill="none"
+                        stroke="currentColor"
+                        viewBox="0 0 24 24"
+                      >
+                        <path
+                          strokeLinecap="round"
+                          strokeLinejoin="round"
+                          strokeWidth={2}
+                          d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
+                        />
+                      </svg>
+                    ) : (
+                      <svg
+                        className="w-5 h-5 text-yellow-500"
+                        fill="none"
+                        stroke="currentColor"
+                        viewBox="0 0 24 24"
+                      >
+                        <path
+                          strokeLinecap="round"
+                          strokeLinejoin="round"
+                          strokeWidth={2}
+                          d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z"
+                        />
+                      </svg>
+                    )}
+                  </div>
+                  <div className="flex-1 min-w-0">
+                    <div className="flex items-center gap-2">
+                      <h4 className="text-sm font-semibold text-gray-900 dark:text-gray-100">
+                        {suggestion.title}
+                      </h4>
+                      <span
+                        className={`text-xs px-2 py-0.5 rounded ${
+                          suggestion.priority === 'high'
+                            ? 'bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400'
+                            : suggestion.priority === 'medium'
+                            ? 'bg-yellow-100 text-yellow-700 dark:bg-yellow-900/30 dark:text-yellow-400'
+                            : 'bg-gray-100 text-gray-600 dark:bg-gray-800 dark:text-gray-400'
+                        }`}
+                      >
+                        {suggestion.priority}
+                      </span>
+                    </div>
+                    <p className="text-sm text-gray-600 dark:text-gray-400 mt-1">
+                      {suggestion.message}
+                    </p>
+                  </div>
+                  <div className="flex-shrink-0">
+                    <svg
+                      className={`w-5 h-5 text-gray-400 transition-transform ${
+                        expandedIndex === index ? 'rotate-180' : ''
+                      }`}
+                      fill="none"
+                      stroke="currentColor"
+                      viewBox="0 0 24 24"
+                    >
+                      <path
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        strokeWidth={2}
+                        d="M19 9l-7 7-7-7"
+                      />
+                    </svg>
+                  </div>
+                </div>
+              </button>
+
+              {/* Expanded content */}
+              {expandedIndex === index && (suggestion.suggestion || suggestion.example) && (
+                <div className="px-4 pb-4 pt-0 border-t border-gray-100 dark:border-gray-800">
+                  {suggestion.suggestion && (
+                    <div className="mt-3">
+                      <p className="text-sm text-gray-700 dark:text-gray-300">
+                        <strong className="text-gray-900 dark:text-gray-100">Suggestion:</strong>{' '}
+                        {suggestion.suggestion}
+                      </p>
+                    </div>
+                  )}
+                  {suggestion.example && (
+                    <div className="mt-3">
+                      <div className="flex items-center justify-between mb-2">
+                        <span className="text-xs font-semibold text-gray-700 dark:text-gray-300">
+                          Example:
+                        </span>
+                        <button
+                          onClick={() => copyExample(suggestion.example!, index)}
+                          className="p-1.5 rounded hover:bg-gray-100 dark:hover:bg-gray-800 transition-colors"
+                          aria-label="Copy example"
+                        >
+                          {copiedIndex === index ? (
+                            <svg
+                              className="w-4 h-4 text-green-500"
+                              fill="none"
+                              stroke="currentColor"
+                              viewBox="0 0 24 24"
+                            >
+                              <path
+                                strokeLinecap="round"
+                                strokeLinejoin="round"
+                                strokeWidth={2}
+                                d="M5 13l4 4L19 7"
+                              />
+                            </svg>
+                          ) : (
+                            <CopyIcon className="w-4 h-4 text-gray-500" />
+                          )}
+                        </button>
+                      </div>
+                      <pre className="text-xs bg-gray-50 dark:bg-black p-3 rounded border border-gray-200 dark:border-gray-700 overflow-x-auto">
+                        <code className="text-gray-800 dark:text-gray-200">{suggestion.example}</code>
+                      </pre>
+                    </div>
+                  )}
+                </div>
+              )}
+            </div>
+          ))
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/lib/markdownParser.ts b/lib/markdownParser.ts
new file mode 100644
index 0000000..d64aa37
--- /dev/null
+++ b/lib/markdownParser.ts
@@ -0,0 +1,172 @@
+/**
+ * Markdown parser utilities for AGENTS.md validation
+ */
+
+export interface ParsedMarkdown {
+  sections: Section[];
+  lineCount: number;
+  characterCount: number;
+  codeBlocks: CodeBlock[];
+  headings: Heading[];
+}
+
+export interface Section {
+  title: string;
+  level: number;
+  lineNumber: number;
+  content: string;
+}
+
+export interface CodeBlock {
+  language: string;
+  code: string;
+  lineNumber: number;
+}
+
+export interface Heading {
+  text: string;
+  level: number;
+  lineNumber: number;
+}
+
+/**
+ * Parse AGENTS.md content into structured data
+ */
+export function parseMarkdown(content: string): ParsedMarkdown {
+  const lines = content.split('\n');
+  const sections: Section[] = [];
+  const codeBlocks: CodeBlock[] = [];
+  const headings: Heading[] = [];
+
+  let currentSection: Section | null = null;
+  let inCodeBlock = false;
+  let currentCodeBlock: { language: string; code: string; lineNumber: number } | null = null;
+
+  lines.forEach((line, index) => {
+    const lineNumber = index + 1;
+
+    // Detect code blocks
+    if (line.trim().startsWith('```')) {
+      if (!inCodeBlock) {
+        // Start of code block
+        const language = line.trim().slice(3).trim() || 'text';
+        currentCodeBlock = { language, code: '', lineNumber };
+        inCodeBlock = true;
+      } else {
+        // End of code block
+        if (currentCodeBlock) {
+          codeBlocks.push(currentCodeBlock);
+          currentCodeBlock = null;
+        }
+        inCodeBlock = false;
+      }
+      return;
+    }
+
+    // Accumulate code block content
+    if (inCodeBlock && currentCodeBlock) {
+      currentCodeBlock.code += line + '\n';
+      return;
+    }
+
+    // Detect headings
+    const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+    if (headingMatch) {
+      const level = headingMatch[1].length;
+      const text = headingMatch[2].trim();
+
+      headings.push({ text, level, lineNumber });
+
+      // Start a new section
+      if (currentSection) {
+        sections.push(currentSection);
+      }
+      currentSection = { title: text, level, lineNumber, content: '' };
+    } else if (currentSection) {
+      // Add content to current section
+      currentSection.content += line + '\n';
+    }
+  });
+
+  // Add the last section
+  if (currentSection) {
+    sections.push(currentSection);
+  }
+
+  return {
+    sections,
+    lineCount: lines.length,
+    characterCount: content.length,
+    codeBlocks,
+    headings,
+  };
+}
+
+/**
+ * Extract commands from markdown content
+ * Looks for inline code (backticks) that appear to be commands
+ */
+export function extractCommands(content: string): string[] {
+  const commands: string[] = [];
+  const inlineCodeRegex = /`([^`]+)`/g;
+
+  let match;
+  while ((match = inlineCodeRegex.exec(content)) !== null) {
+    const code = match[1];
+    // Check if it looks like a command (contains common command patterns)
+    if (
+      code.includes(' ') ||
+      code.startsWith('npm ') ||
+      code.startsWith('pnpm ') ||
+      code.startsWith('yarn ') ||
+      code.startsWith('bun ') ||
+      code.startsWith('git ') ||
+      code.startsWith('docker ') ||
+      code.startsWith('make ') ||
+      code.includes('test') ||
+      code.includes('build') ||
+      code.includes('dev') ||
+      code.includes('start')
+    ) {
+      commands.push(code);
+    }
+  }
+
+  return commands;
+}
+
+/**
+ * Check if content mentions specific versions
+ */
+export function hasVersionSpecificity(content: string): boolean {
+  // Look for version patterns like "React 18", "Node.js 20", "Python 3.11"
+  const versionPatterns = [
+    /\b\w+\s+\d+(\.\d+)?(\.\d+)?\b/g, // "React 18.2.0" or "Node 20"
+    /\b\w+\s+v\d+(\.\d+)?(\.\d+)?\b/g, // "Node v20.0.0"
+  ];
+
+  return versionPatterns.some(pattern => pattern.test(content));
+}
+
+/**
+ * Detect common section keywords
+ */
+export function detectSectionKeywords(text: string): {
+  hasSetup: boolean;
+  hasTesting: boolean;
+  hasCodeStyle: boolean;
+  hasArchitecture: boolean;
+  hasSecurity: boolean;
+  hasGitWorkflow: boolean;
+} {
+  const lower = text.toLowerCase();
+
+  return {
+    hasSetup: /\b(setup|install|dependencies|requirements|getting started|dev environment)\b/.test(lower),
+    hasTesting: /\b(test|testing|qa|quality)\b/.test(lower),
+    hasCodeStyle: /\b(style|lint|format|convention|standards)\b/.test(lower),
+    hasArchitecture: /\b(architecture|structure|design|organization|overview)\b/.test(lower),
+    hasSecurity: /\b(security|auth|authentication|secrets|credentials)\b/.test(lower),
+    hasGitWorkflow: /\b(git|commit|pr|pull request|branch|workflow)\b/.test(lower),
+  };
+}
diff --git a/lib/validationRules.ts b/lib/validationRules.ts
new file mode 100644
index 0000000..ae00469
--- /dev/null
+++ b/lib/validationRules.ts
@@ -0,0 +1,271 @@
+/**
+ * Validation rules for AGENTS.md files
+ */
+
+import { ParsedMarkdown, detectSectionKeywords, extractCommands, hasVersionSpecificity } from './markdownParser';
+
+export type SuggestionPriority = 'low' | 'medium' | 'high';
+export type SuggestionType = 'tip' | 'info' | 'success';
+
+export interface ValidationSuggestion {
+  type: SuggestionType;
+  title: string;
+  message: string;
+  suggestion?: string;
+  example?: string;
+  priority: SuggestionPriority;
+}
+
+/**
+ * Check if the file is too long
+ */
+export function checkLength(parsed: ParsedMarkdown): ValidationSuggestion | null {
+  const { lineCount } = parsed;
+
+  if (lineCount > 200) {
+    return {
+      type: 'tip',
+      title: 'Consider keeping it concise',
+      message: `Your AGENTS.md is ${lineCount} lines. Best practice is ≤150 lines for readability.`,
+      suggestion: 'Try focusing on the most critical information agents need. Remove outdated or overly detailed sections.',
+      priority: 'medium',
+    };
+  }
+
+  if (lineCount > 150) {
+    return {
+      type: 'tip',
+      title: 'File is getting long',
+      message: `Your AGENTS.md is ${lineCount} lines. Consider trimming to ≤150 lines.`,
+      suggestion: 'Focus on essential commands, conventions, and agent-specific context.',
+      priority: 'low',
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Check if the file is too short
+ */
+export function checkMinimumContent(parsed: ParsedMarkdown): ValidationSuggestion | null {
+  const { lineCount, sections } = parsed;
+
+  if (lineCount < 5) {
+    return {
+      type: 'tip',
+      title: 'Add more context',
+      message: 'Your AGENTS.md is quite short. Adding more details will help agents work more effectively.',
+      suggestion: 'Consider adding setup commands, testing instructions, and code style guidelines.',
+      example: `# AGENTS.md
+
+## Setup
+- Install: \`npm install\`
+- Start dev: \`npm run dev\`
+
+## Testing
+- Run tests: \`npm test\`
+
+## Code style
+- Use TypeScript strict mode
+- Prefer functional components`,
+      priority: 'medium',
+    };
+  }
+
+  if (sections.length === 0) {
+    return {
+      type: 'tip',
+      title: 'Add section headings',
+      message: 'No section headings found. Organize your content with clear headings.',
+      suggestion: 'Use ## for main sections like "Setup", "Testing", "Code Style".',
+      priority: 'high',
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Detect missing common sections
+ */
+export function checkCommonSections(parsed: ParsedMarkdown): ValidationSuggestion[] {
+  const suggestions: ValidationSuggestion[] = [];
+  const allText = parsed.sections.map(s => s.title + ' ' + s.content).join(' ');
+  const keywords = detectSectionKeywords(allText);
+
+  if (!keywords.hasSetup) {
+    suggestions.push({
+      type: 'tip',
+      title: 'Consider adding setup instructions',
+      message: 'No setup or installation section found. Agents work better with clear setup commands.',
+      suggestion: 'Add a section with installation and development environment setup.',
+      example: `## Setup
+- Install dependencies: \`pnpm install\`
+- Start dev server: \`pnpm dev\`
+- Build: \`pnpm build\``,
+      priority: 'high',
+    });
+  }
+
+  if (!keywords.hasTesting) {
+    suggestions.push({
+      type: 'tip',
+      title: 'Consider adding testing instructions',
+      message: 'No testing section found. Test commands help agents verify their changes.',
+      suggestion: 'Add a section describing how to run tests and what to check.',
+      example: `## Testing
+- Run all tests: \`pnpm test\`
+- Run specific test: \`pnpm test -- <pattern>\`
+- Lint code: \`pnpm lint\``,
+      priority: 'medium',
+    });
+  }
+
+  if (!keywords.hasCodeStyle) {
+    suggestions.push({
+      type: 'tip',
+      title: 'Consider documenting code style',
+      message: 'No code style section found. Style guidelines help agents write consistent code.',
+      suggestion: 'Add a section with formatting rules, naming conventions, and patterns to follow.',
+      example: `## Code style
+- TypeScript strict mode enabled
+- Use functional components with hooks
+- Single quotes, no semicolons
+- Prefer named exports`,
+      priority: 'low',
+    });
+  }
+
+  return suggestions;
+}
+
+/**
+ * Check for command formatting
+ */
+export function checkCommandFormatting(parsed: ParsedMarkdown, content: string): ValidationSuggestion | null {
+  const commands = extractCommands(content);
+  const { codeBlocks } = parsed;
+
+  // Check if there are commands in inline code but few code blocks
+  if (commands.length > 5 && codeBlocks.length === 0) {
+    return {
+      type: 'tip',
+      title: 'Consider using code blocks',
+      message: `Found ${commands.length} commands in inline code. Multi-line commands are easier to read in code blocks.`,
+      suggestion: 'Use triple backticks (```) for multi-line commands or command lists.',
+      example: `\`\`\`bash
+npm install
+npm run dev
+npm test
+\`\`\``,
+      priority: 'low',
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Check for version specificity
+ */
+export function checkVersionSpecificity(content: string): ValidationSuggestion | null {
+  // Check for common tool names without versions
+  const toolPatterns = [
+    { name: 'React', pattern: /\bReact\b(?!\s+\d)/ },
+    { name: 'Node', pattern: /\bNode(?:\.js)?\b(?!\s+v?\d)/ },
+    { name: 'Python', pattern: /\bPython\b(?!\s+\d)/ },
+    { name: 'TypeScript', pattern: /\bTypeScript\b(?!\s+\d)/ },
+    { name: 'Next.js', pattern: /\bNext(?:\.js)?\b(?!\s+\d)/ },
+  ];
+
+  const foundTools = toolPatterns
+    .filter(({ pattern }) => pattern.test(content))
+    .map(({ name }) => name);
+
+  if (foundTools.length > 0 && !hasVersionSpecificity(content)) {
+    return {
+      type: 'tip',
+      title: 'Be more specific about versions',
+      message: `Found ${foundTools.join(', ')} mentioned without version numbers.`,
+      suggestion: 'Specify versions to help agents use the right APIs and patterns.',
+      example: 'Use "React 18" or "Node.js 20" instead of just "React" or "Node".',
+      priority: 'low',
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Check markdown structure and readability
+ */
+export function checkReadability(parsed: ParsedMarkdown): ValidationSuggestion[] {
+  const suggestions: ValidationSuggestion[] = [];
+  const { headings, sections } = parsed;
+
+  // Check heading hierarchy
+  const topLevelHeadings = headings.filter(h => h.level === 1);
+  if (topLevelHeadings.length > 1) {
+    suggestions.push({
+      type: 'info',
+      title: 'Multiple top-level headings',
+      message: `Found ${topLevelHeadings.length} # headings. AGENTS.md typically uses one # heading as the title.`,
+      suggestion: 'Use ## for main sections instead of # to maintain clear hierarchy.',
+      priority: 'low',
+    });
+  }
+
+  // Check for very long sections
+  const longSections = sections.filter(s => s.content.split('\n').length > 50);
+  if (longSections.length > 0) {
+    suggestions.push({
+      type: 'tip',
+      title: 'Some sections are very long',
+      message: `${longSections.length} section(s) have more than 50 lines.`,
+      suggestion: 'Consider breaking long sections into subsections or removing verbose details.',
+      priority: 'low',
+    });
+  }
+
+  // Check for sections with no content
+  const emptySections = sections.filter(s => s.content.trim().length < 10);
+  if (emptySections.length > 0) {
+    suggestions.push({
+      type: 'tip',
+      title: 'Empty sections detected',
+      message: `${emptySections.length} section(s) have little or no content.`,
+      suggestion: 'Remove empty section headings or add content to make them useful.',
+      priority: 'medium',
+    });
+  }
+
+  return suggestions;
+}
+
+/**
+ * Provide positive feedback for well-formed files
+ */
+export function checkWellFormed(parsed: ParsedMarkdown, content: string): ValidationSuggestion | null {
+  const { lineCount, sections, codeBlocks } = parsed;
+  const allText = sections.map(s => s.title + ' ' + s.content).join(' ');
+  const keywords = detectSectionKeywords(allText);
+
+  // Check if file meets good standards
+  const hasGoodLength = lineCount >= 10 && lineCount <= 150;
+  const hasSections = sections.length >= 3;
+  const hasCommands = extractCommands(content).length > 0 || codeBlocks.length > 0;
+  const hasKeyTopics = [keywords.hasSetup, keywords.hasTesting, keywords.hasCodeStyle].filter(Boolean).length >= 2;
+
+  if (hasGoodLength && hasSections && hasCommands && hasKeyTopics) {
+    return {
+      type: 'success',
+      title: 'Well-structured AGENTS.md',
+      message: 'Your AGENTS.md looks great! It has good structure, clear sections, and helpful commands.',
+      suggestion: 'Agents should be able to work effectively with this file.',
+      priority: 'high',
+    };
+  }
+
+  return null;
+}
diff --git a/lib/validator.ts b/lib/validator.ts
new file mode 100644
index 0000000..5405d16
--- /dev/null
+++ b/lib/validator.ts
@@ -0,0 +1,164 @@
+/**
+ * Core validation engine for AGENTS.md files
+ */
+
+import { parseMarkdown } from './markdownParser';
+import {
+  ValidationSuggestion,
+  checkLength,
+  checkMinimumContent,
+  checkCommonSections,
+  checkCommandFormatting,
+  checkVersionSpecificity,
+  checkReadability,
+  checkWellFormed,
+} from './validationRules';
+
+export interface ValidationResult {
+  suggestions: ValidationSuggestion[];
+  score: number; // 0-100
+  summary: string;
+}
+
+/**
+ * Main validation function
+ */
+export function validateAgentsMd(content: string): ValidationResult {
+  // Handle empty content
+  if (!content || content.trim().length === 0) {
+    return {
+      suggestions: [
+        {
+          type: 'tip',
+          title: 'Get started with AGENTS.md',
+          message: 'Your file is empty. Start by adding a title and basic sections.',
+          suggestion: 'Add setup commands, testing instructions, and code style guidelines.',
+          example: `# AGENTS.md
+
+## Setup
+- Install dependencies: \`npm install\`
+- Start dev server: \`npm run dev\`
+
+## Testing
+- Run tests: \`npm test\`
+
+## Code style
+- Use TypeScript strict mode
+- Prefer functional components`,
+          priority: 'high',
+        },
+      ],
+      score: 0,
+      summary: 'Empty file - add content to get started',
+    };
+  }
+
+  const parsed = parseMarkdown(content);
+  const suggestions: ValidationSuggestion[] = [];
+
+  // Run all validation rules
+  const lengthCheck = checkLength(parsed);
+  if (lengthCheck) suggestions.push(lengthCheck);
+
+  const minimumContentCheck = checkMinimumContent(parsed);
+  if (minimumContentCheck) suggestions.push(minimumContentCheck);
+
+  suggestions.push(...checkCommonSections(parsed));
+
+  const commandCheck = checkCommandFormatting(parsed, content);
+  if (commandCheck) suggestions.push(commandCheck);
+
+  const versionCheck = checkVersionSpecificity(content);
+  if (versionCheck) suggestions.push(versionCheck);
+
+  suggestions.push(...checkReadability(parsed));
+
+  // Check for well-formed file (positive feedback)
+  const wellFormedCheck = checkWellFormed(parsed, content);
+  if (wellFormedCheck) suggestions.push(wellFormedCheck);
+
+  // Sort suggestions by priority
+  const priorityOrder = { high: 0, medium: 1, low: 2 };
+  suggestions.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority]);
+
+  // Calculate score
+  const score = calculateScore(parsed, suggestions);
+
+  // Generate summary
+  const summary = generateSummary(suggestions, score);
+
+  return {
+    suggestions,
+    score,
+    summary,
+  };
+}
+
+/**
+ * Calculate a quality score (0-100)
+ */
+function calculateScore(parsed: any, suggestions: ValidationSuggestion[]): number {
+  let score = 100;
+
+  // Deduct points for issues
+  suggestions.forEach((suggestion) => {
+    if (suggestion.type === 'success') {
+      // Don't deduct for success messages
+      return;
+    }
+
+    switch (suggestion.priority) {
+      case 'high':
+        score -= 15;
+        break;
+      case 'medium':
+        score -= 8;
+        break;
+      case 'low':
+        score -= 3;
+        break;
+    }
+  });
+
+  // Minimum score is 0
+  score = Math.max(0, score);
+
+  // Bonus points for good structure
+  if (parsed.sections.length >= 3) score += 5;
+  if (parsed.codeBlocks.length > 0) score += 5;
+  if (parsed.lineCount >= 10 && parsed.lineCount <= 150) score += 5;
+
+  // Cap at 100
+  return Math.min(100, score);
+}
+
+/**
+ * Generate a human-readable summary
+ */
+function generateSummary(suggestions: ValidationSuggestion[], score: number): string {
+  const successSuggestions = suggestions.filter(s => s.type === 'success');
+  const tipSuggestions = suggestions.filter(s => s.type === 'tip');
+  const highPrioritySuggestions = suggestions.filter(s => s.priority === 'high' && s.type !== 'success');
+
+  if (successSuggestions.length > 0) {
+    return 'Your AGENTS.md is well-structured and ready to help agents work effectively!';
+  }
+
+  if (score >= 80) {
+    return 'Your AGENTS.md looks good with just a few suggestions for improvement.';
+  }
+
+  if (score >= 60) {
+    return 'Your AGENTS.md has good basics but could be improved in a few areas.';
+  }
+
+  if (score >= 40) {
+    return 'Your AGENTS.md needs some work. Focus on the high-priority suggestions first.';
+  }
+
+  if (highPrioritySuggestions.length > 0) {
+    return 'Start by addressing the high-priority suggestions to improve your AGENTS.md.';
+  }
+
+  return 'Add more content and structure to help agents understand your project.';
+}
diff --git a/pages/validator.tsx b/pages/validator.tsx
new file mode 100644
index 0000000..6e87067
--- /dev/null
+++ b/pages/validator.tsx
@@ -0,0 +1,177 @@
+import React, { useState, useEffect, useMemo } from 'react';
+import Head from 'next/head';
+import Link from 'next/link';
+import Footer from '@/components/Footer';
+import ValidatorInput from '@/components/ValidatorInput';
+import ValidatorResults from '@/components/ValidatorResults';
+import ValidatorPreview from '@/components/ValidatorPreview';
+import { validateAgentsMd } from '@/lib/validator';
+
+const EXAMPLE_CONTENT = `# AGENTS.md
+
+## Setup
+- Install dependencies: \`pnpm install\`
+- Start dev server: \`pnpm dev\`
+- Build for production: \`pnpm build\`
+
+## Testing
+- Run all tests: \`pnpm test\`
+- Run specific test: \`pnpm test -- <pattern>\`
+- Lint code: \`pnpm lint\`
+
+## Code style
+- TypeScript strict mode enabled
+- Use functional components with hooks
+- Single quotes, no semicolons
+- Prefer named exports over default exports
+
+## Architecture
+- Next.js 16 with Pages Router
+- React 19 for UI components
+- Tailwind CSS 4 for styling
+- TypeScript 5 for type safety
+
+## Git workflow
+- Create feature branches from main
+- Run tests before committing
+- Write clear commit messages
+- Open PR for review before merging`;
+
+const DEBOUNCE_MS = 300;
+
+export default function ValidatorPage() {
+  const [content, setContent] = useState('');
+  const [debouncedContent, setDebouncedContent] = useState('');
+
+  // Debounce content changes
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      setDebouncedContent(content);
+    }, DEBOUNCE_MS);
+
+    return () => clearTimeout(timer);
+  }, [content]);
+
+  // Validate content
+  const validationResult = useMemo(() => {
+    return validateAgentsMd(debouncedContent);
+  }, [debouncedContent]);
+
+  const loadExample = () => {
+    setContent(EXAMPLE_CONTENT);
+  };
+
+  const clearContent = () => {
+    setContent('');
+  };
+
+  return (
+    <>
+      <Head>
+        <title>AGENTS.md Validator - Validate Your AGENTS.md File</title>
+        <meta
+          name="description"
+          content="Validate your AGENTS.md file with helpful suggestions to improve clarity and usefulness for AI coding agents."
+        />
+      </Head>
+
+      <div className="flex flex-col min-h-screen">
+        {/* Header */}
+        <header className="px-6 py-6 bg-gray-50 dark:bg-gray-900/40 border-b border-gray-100 dark:border-gray-800">
+          <div className="max-w-7xl mx-auto">
+            <div className="flex items-center justify-between mb-4">
+              <Link
+                href="/"
+                className="text-2xl font-bold tracking-tight hover:opacity-80 transition-opacity"
+              >
+                AGENTS.md
+              </Link>
+              <Link
+                href="/"
+                className="text-sm text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100"
+              >
+                ← Back to home
+              </Link>
+            </div>
+            <div>
+              <h1 className="text-3xl md:text-4xl font-bold tracking-tight mb-2">
+                AGENTS.md Validator
+              </h1>
+              <p className="text-gray-700 dark:text-gray-300 max-w-2xl">
+                Get helpful suggestions to improve your AGENTS.md file. All feedback is
+                non-blocking - use what helps your project.
+              </p>
+            </div>
+          </div>
+        </header>
+
+        {/* Main content */}
+        <main className="flex-1 px-6 py-8 bg-white dark:bg-gray-950">
+          <div className="max-w-7xl mx-auto">
+            {/* Action buttons */}
+            <div className="flex gap-3 mb-6 flex-wrap">
+              <button
+                onClick={loadExample}
+                className="px-4 py-2 rounded-lg bg-gray-100 dark:bg-gray-800 text-gray-900 dark:text-gray-100 text-sm font-medium hover:bg-gray-200 dark:hover:bg-gray-700 transition-colors"
+              >
+                Load Example
+              </button>
+              <button
+                onClick={clearContent}
+                className="px-4 py-2 rounded-lg border border-gray-300 dark:border-gray-600 text-gray-700 dark:text-gray-300 text-sm font-medium hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors"
+              >
+                Clear
+              </button>
+            </div>
+
+            {/* Two-column layout: Input + Preview on left, Results on right */}
+            <div className="grid grid-cols-1 lg:grid-cols-3 gap-6 h-[calc(100vh-280px)] min-h-[600px]">
+              {/* Left column: Input and Preview */}
+              <div className="lg:col-span-2 flex flex-col gap-6 h-full">
+                {/* Input */}
+                <div className="flex-1 min-h-0">
+                  <ValidatorInput
+                    value={content}
+                    onChange={setContent}
+                    placeholder="Paste your AGENTS.md content here..."
+                  />
+                </div>
+
+                {/* Preview */}
+                <div className="flex-1 min-h-0">
+                  <ValidatorPreview content={content} />
+                </div>
+              </div>
+
+              {/* Right column: Results */}
+              <div className="h-full">
+                <ValidatorResults
+                  suggestions={validationResult.suggestions}
+                  score={validationResult.score}
+                  summary={validationResult.summary}
+                />
+              </div>
+            </div>
+
+            {/* Info section */}
+            <div className="mt-12 max-w-3xl">
+              <h2 className="text-xl font-semibold mb-3">About the Validator</h2>
+              <div className="text-sm text-gray-700 dark:text-gray-300 space-y-2">
+                <p>
+                  This validator provides <strong>suggestions, not rules</strong>. AGENTS.md is
+                  intentionally flexible - there are no required fields or strict schemas.
+                </p>
+                <p>
+                  Use the suggestions that make sense for your project and ignore the rest. The
+                  goal is to help you create a clear, useful guide for AI coding agents.
+                </p>
+              </div>
+            </div>
+          </div>
+        </main>
+
+        <Footer />
+      </div>
+    </>
+  );
+}