feat(docs): maximize SEO discoverability

docs/astro.config.mjs

@@ -79,10 +79,24 @@ export default defineConfig({
           href: "https://github.com/archgate/cli",
         },
       ],
+      components: {
+        Head: "./src/components/HeadSEO.astro",
+      },
       editLink: {
         baseUrl: "https://github.com/archgate/cli/edit/main/docs/",
       },
+      favicon: "/favicon.svg",
       head: [
+        // ── Favicon ───────────────────────────────────────────────
+        {
+          tag: "link",
+          attrs: {
+            rel: "icon",
+            type: "image/svg+xml",
+            href: "/favicon.svg",
+          },
+        },
+        // ── Analytics ─────────────────────────────────────────────
         {
           tag: "script",
           attrs: {
@@ -91,6 +105,91 @@ export default defineConfig({
             "data-cf-beacon": '{"token": "cee359c05ecc496aabc4f40f05302a03"}',
           },
         },
+        // ── Open Graph image ──────────────────────────────────────
+        {
+          tag: "meta",
+          attrs: {
+            property: "og:image",
+            content: "https://cli.archgate.dev/og-image.png",
+          },
+        },
+        {
+          tag: "meta",
+          attrs: { property: "og:image:width", content: "1200" },
+        },
+        {
+          tag: "meta",
+          attrs: { property: "og:image:height", content: "630" },
+        },
+        {
+          tag: "meta",
+          attrs: {
+            property: "og:image:alt",
+            content:
+              "Archgate — Architecture Decision Records as Executable Rules",
+          },
+        },
+        // ── Twitter / X card ──────────────────────────────────────
+        {
+          tag: "meta",
+          attrs: {
+            name: "twitter:image",
+            content: "https://cli.archgate.dev/og-image.png",
+          },
+        },
+        // ── Additional meta ───────────────────────────────────────
+        {
+          tag: "meta",
+          attrs: { name: "author", content: "Archgate" },
+        },
+        {
+          tag: "meta",
+          attrs: { name: "theme-color", content: "#6366f1" },
+        },
+        {
+          tag: "meta",
+          attrs: {
+            name: "keywords",
+            content:
+              "archgate, architecture decision records, ADR, executable rules, code governance, AI governance, TypeScript rules, CLI, compliance automation, MCP server",
+          },
+        },
+        // ── JSON-LD: WebSite ──────────────────────────────────────
+        {
+          tag: "script",
+          attrs: { type: "application/ld+json" },
+          content: JSON.stringify({
+            "@context": "https://schema.org",
+            "@type": "WebSite",
+            name: "Archgate CLI Documentation",
+            url: "https://cli.archgate.dev",
+            description:
+              "Documentation for Archgate — enforce Architecture Decision Records as executable TypeScript rules for automated code governance.",
+            inLanguage: ["en", "pt-BR"],
+          }),
+        },
+        // ── JSON-LD: SoftwareApplication ──────────────────────────
+        {
+          tag: "script",
+          attrs: { type: "application/ld+json" },
+          content: JSON.stringify({
+            "@context": "https://schema.org",
+            "@type": "SoftwareApplication",
+            name: "Archgate CLI",
+            applicationCategory: "DeveloperApplication",
+            operatingSystem: "macOS, Linux, Windows",
+            offers: { "@type": "Offer", price: "0", priceCurrency: "USD" },
+            url: "https://cli.archgate.dev",
+            downloadUrl: "https://www.npmjs.com/package/archgate",
+            description:
+              "CLI tool that enforces Architecture Decision Records (ADRs) as executable TypeScript rules for automated code governance.",
+            author: {
+              "@type": "Organization",
+              name: "Archgate",
+              url: "https://archgate.dev",
+            },
+          }),
+        },
       ],
       sidebar: [
         {

docs/public/llms.txt

@@ -0,0 +1,45 @@
+# Archgate CLI
+
+> Archgate is a CLI tool for AI governance via Architecture Decision Records (ADRs). It combines human-readable documentation with machine-checkable TypeScript rules to enforce architectural decisions across codebases — for both humans and AI agents.
+
+Archgate lets teams write an ADR once and enforce it everywhere. ADRs are Markdown files with YAML frontmatter that describe architectural decisions. Companion `.rules.ts` files contain automated TypeScript checks that run against the codebase and report violations with file paths and line numbers.
+
+## Key capabilities
+
+- **Executable rules**: Write compliance rules in TypeScript. Archgate runs them against your codebase and reports violations with file paths and line numbers.
+- **CI integration**: Wire `archgate check` into any CI/CD pipeline. Exit code 1 blocks merges when rules are violated.
+- **AI-aware governance**: The MCP server gives AI agents (Claude, Cursor, Copilot) live access to ADRs. Agents read decisions before writing code and validate after.
+- **Editor plugins**: Claude Code, VS Code, Cursor, and Copilot CLI plugins give AI agents role-based governance skills.
+- **Self-governance**: Archgate governs its own development using the same tool.
+
+## Installation
+
+Available via npm (`npm install -g archgate`), Homebrew, or standalone binary for macOS, Linux, and Windows.
+
+## Documentation
+
+- [Getting Started — Installation](https://cli.archgate.dev/getting-started/installation/): Install on macOS, Linux, or Windows via npm, Homebrew, or standalone binary.
+- [Getting Started — Quick Start](https://cli.archgate.dev/getting-started/quick-start/): Set up Archgate in under 5 minutes with your first ADR and rule.
+- [Core Concepts — ADRs](https://cli.archgate.dev/concepts/adrs/): How Architecture Decision Records work as both documentation and executable rules.
+- [Core Concepts — Rules](https://cli.archgate.dev/concepts/rules/): The TypeScript rule system that turns ADR decisions into automated compliance checks.
+- [Core Concepts — Domains](https://cli.archgate.dev/concepts/domains/): Organize ADRs by domain for targeted governance.
+- [Guide — Writing ADRs](https://cli.archgate.dev/guides/writing-adrs/): Complete guide to writing effective ADRs with YAML frontmatter and markdown structure.
+- [Guide — Writing Rules](https://cli.archgate.dev/guides/writing-rules/): Write TypeScript rules using the defineRules API with file matching and violation reporting.
+- [Guide — CI Integration](https://cli.archgate.dev/guides/ci-integration/): Add Archgate checks to GitHub Actions, GitLab CI, or any pipeline.
+- [Guide — Claude Code Plugin](https://cli.archgate.dev/guides/claude-code-plugin/): Give AI agents a governance workflow that reads ADRs, validates code, and captures patterns.
+- [Guide — VS Code Plugin](https://cli.archgate.dev/guides/vscode-plugin/): Real-time ADR compliance in VS Code.
+- [Guide — Copilot CLI Plugin](https://cli.archgate.dev/guides/copilot-cli-plugin/): Add architecture governance to GitHub Copilot CLI.
+- [Guide — Cursor Integration](https://cli.archgate.dev/guides/cursor-integration/): Configure Cursor IDE with Archgate agent rules and skills.
+- [Guide — MCP Server](https://cli.archgate.dev/guides/mcp-server/): Give AI agents live access to ADRs via the Model Context Protocol.
+- [Guide — Pre-commit Hooks](https://cli.archgate.dev/guides/pre-commit-hooks/): Automatically check ADR compliance before every commit.
+- [Reference — CLI Commands](https://cli.archgate.dev/reference/cli-commands/): Complete reference for init, check, adr create/list/show, login, and more.
+- [Reference — MCP Tools](https://cli.archgate.dev/reference/mcp-tools/): API reference for adr_list, adr_read, check_compliance, and review_context.
+- [Reference — Rule API](https://cli.archgate.dev/reference/rule-api/): TypeScript API reference for defineRules, RuleContext, and violation reporting.
+- [Reference — ADR Schema](https://cli.archgate.dev/reference/adr-schema/): YAML frontmatter schema and markdown structure reference for ADRs.
+- [Examples — Common Rule Patterns](https://cli.archgate.dev/examples/common-rule-patterns/): Ready-to-use rule patterns for naming conventions, import restrictions, and more.
+
+## Optional
+
+- [GitHub Repository](https://github.com/archgate/cli)
+- [Editor Plugin Beta](https://plugins.archgate.dev)
+- [npm Package](https://www.npmjs.com/package/archgate)

docs/public/robots.txt

@@ -0,0 +1,8 @@
+# Archgate CLI Documentation — https://cli.archgate.dev
+# Allow all search engines and AI crawlers full access
+
+User-agent: *
+Allow: /
+
+# Sitemap location
+Sitemap: https://cli.archgate.dev/sitemap-index.xml

docs/scripts/generate-og-image.ts

@@ -0,0 +1,21 @@
+/**
+ * Generates the default Open Graph image (1200x630 PNG) for social sharing.
+ * Reads the branded SVG from the website repo and converts it to PNG via sharp.
+ *
+ * Run: bun run docs/scripts/generate-og-image.ts
+ */
+import sharp from "sharp";
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+
+const svgPath = join(import.meta.dirname, "..", "public", "og-image.svg");
+const outputPath = join(import.meta.dirname, "..", "public", "og-image.png");
+
+const svg = readFileSync(svgPath, "utf-8");
+
+await sharp(Buffer.from(svg))
+  .resize(1200, 630)
+  .png({ quality: 90 })
+  .toFile(outputPath);
+
+console.log(`Generated OG image: ${outputPath}`);