Add AEO

[humandebri]

Summary

This PR adds documentation for the next AEO Publish direction: turning the user-visible frontend surface of a GitHub repo into AI-search-ready wiki and answer pages.

The product direction is not to wiki an entire repository. It is to read the frontend surface users can actually see, generate product-facing wiki content with Kinic-side LLMs, and publish /answers, sitemap.xml, and llms.txt automatically after main-branch pushes.

Product Direction

Developer connects a GitHub repo -> developer pushes to main -> Kinic receives the webhook -> Kinic analyzes the frontend surface -> Kinic-side LLM generates public wiki and AEO answers -> Kinic validates the output -> Kinic publishes automatically -> /answers, sitemap.xml, and llms.txt update.

The developer experience should feel like Vercel: connect a repo, push to main, and let Kinic generate the AI-search-ready public knowledge layer.

Future product command: kinic aeo generate --repo .

Current dry-run command: vfs-cli aeo-generate --repo <path> --out <path> --project-name <name>

Scope

Generate from user-visible frontend sources:

• routes and pages
• layouts and metadata
• UI copy
• public docs and README content
• visible product flows and feature descriptions
• public APIs only when surfaced through the frontend or public docs

Exclude implementation-only sources:

• database schemas
• backend-only helpers
• internal API clients
• secrets and environment values
• tests and fixtures
• build scripts
• hidden admin surfaces
• claims about pricing, security, compliance, performance, competitors, or roadmap unless explicitly present in user-visible sources

Proposed Skill

Add a frontend-aeo-wiki skill.

The skill should:

• detect the frontend framework, starting with Next.js App Router
• extract the product surface visible to end users
• build a safe source pack for LLM generation
• generate public wiki Markdown and /answers Markdown
• attach source paths to every generated answer
• reject unsupported product claims that are not present in UI copy, metadata, README, or public docs

Initial framework support can be limited to Next.js App Router. Other frameworks can follow later: Next.js Pages Router, Vite React, Astro, SvelteKit, Nuxt, and Remix.

Generated Content Shape

Example wiki output:

• /Wiki/product/overview.md
• /Wiki/product/screens.md
• /Wiki/product/features.md
• /Wiki/product/faq.md

Example AEO answer output:

• /Wiki/aeo/what-is-product.md
• /Wiki/aeo/how-does-product-work.md
• /Wiki/aeo/product-features.md
• /Wiki/aeo/product-pricing.md, only when pricing exists in UI or public docs

Publish Rules

The target flow does not require human approval. Instead, publish must be gated by mechanical validation:

• required frontmatter exists
• slugs are unique
• source paths are present for generated answers
• Markdown parses successfully
• no secret patterns are present
• generated claims are grounded in visible UI, metadata, README, or public docs
• /w/* remains noindex
• only /answers/* appears in sitemap and llms.txt

If validation fails, Kinic should keep the previous published version and store the failed generation report.

MVP Build Order

1. Create the frontend-aeo-wiki skill.
2. Add the current local dry-run command: vfs-cli aeo-generate --repo <path> --out <path> --project-name <name>.
3. Run it against this wikibrowser app first.
4. Feed the generated wiki and answer pages into the existing /answers pipeline.
5. Later expose the product command: kinic aeo generate --repo ..
6. Later add GitHub webhook support for main-branch automatic generation.

Investor Story

Kinic turns a frontend repo into an AI-search-ready public knowledge layer. Developers only push to main; Kinic reads the user-visible product surface, generates the public wiki and AEO answers with Kinic-side LLMs, validates the output, and publishes answer pages that AI search engines can cite.

1. Search behavior shift

2. sitemap.xml / llms.txt / answers distinction

3. AEO publish flow

Implemented in This PR

• Added the frontend-aeo-wiki skill under .agents/skills.
• Added vfs-cli aeo-generate --repo <path> --out <path> --project-name <name> as the current local dry-run generator.
• Added deterministic output for wiki pages, answer pages, manifest.json, and validation.json.
• Added sources parsing support to the AEO frontmatter parser while preserving compatibility with existing Markdown that lacks sources.
• Added docs/internal/FRONTEND_AEO_WIKI.md for the GitHub push -> Kinic-side generation -> validation -> publish direction.

Validation

• Confirmed all three assets are PNG images at 1672x941.
• cd wikibrowser && pnpm test passed.
• cd wikibrowser && pnpm typecheck passed.
• cargo test -p vfs-cli aeo_generate passed.
• cargo test -p vfs-cli passed.