Docs - Project Documentation Generator

Generate, maintain, and improve project documentation following a landing-page README + detailed docs/ structure.

Core Principles

1. •README is a landing page, not a manual. ~80-120 lines. First impression, install, quick example, links to details.
2. •Details go to docs/. Each file is self-contained — one topic, one page. A user should be able to read a single doc file and get the full picture on that topic.
3. •No duplication. If information lives in docs/, README links to it — does not repeat it. Exception: installation command can appear in both (users expect it in README).
4. •Navigation. Every docs/ file has a header line with prev/next links following the Documentation table order: [← Previous Page](prev.md) · [Back to README](../README.md) · [Next Page →](next.md). First page has no prev link; last page has no next link. Every page ends with a "See Also" section linking to 2-3 related pages.
5. •Cross-links use relative paths. From README: docs/workflow.md. Between docs: workflow.md (same directory).
6. •Scannable. Use tables, bullet lists, and code blocks. Avoid long paragraphs. Users scan, they don't read.

Workflow

Step 0: Load Project Context

Read .ai-factory/DESCRIPTION.md if it exists to understand:

• •Tech stack (language, framework, database)
• •Project purpose and architecture
• •Key features and conventions

Explore the codebase:

• •Read package.json, composer.json, requirements.txt, go.mod, Cargo.toml, etc.
• •Scan src/ structure to understand architecture
• •Look for existing docs, comments, API endpoints, CLI commands
• •Check for existing README.md and docs/ directory

Scan for scattered markdown files in project root:

Use Glob to find all *.md files in the project root (exclude node_modules/, .ai-factory/, agent dirs):

CHANGELOG.md, CONTRIBUTING.md, ARCHITECTURE.md, DEPLOYMENT.md,
SECURITY.md, API.md, SETUP.md, DEVELOPMENT.md, TESTING.md, etc.

Record each file, its size, and a brief summary of its content. This list is used in Step 1.1.

Step 0.1: Parse Flags

--web  → Generate HTML version of documentation

Step 1: Determine Current State

Check what documentation already exists:

State A: No README.md                → Full generation (README + docs/)
State B: README.md exists, no docs/  → Analyze README, propose split into docs/
State C: README.md + docs/ exist     → Depends on flags (see below)

State C with --web flag — ask the user:

Documentation already exists (README.md + docs/).

What would you like to do?
- [ ] Generate HTML only — build site from current docs as-is
- [ ] Audit & improve first — check for issues, then generate HTML
- [ ] Audit only — check for issues without generating HTML

• •"Generate HTML only" → skip Step 1.1, Step 2, Step 4 — go directly to Step 3 (HTML generation), then done
• •"Audit & improve first" → run Step 1.1 → Step 2 (State C) → Step 3 → Step 4 → Step 4.1
• •"Audit only" → run Step 1.1 → Step 2 (State C) → Step 4 → Step 4.1 (skip Step 3)

State C without --web flag → run Step 2 (State C) as usual.

Step 1.1: Check for Scattered Markdown Files

If scattered .md files were found in the project root (from Step 0), propose consolidating them into the docs/ directory.

Common files that should move to docs/:

Files that stay in root (standard convention):

• •README.md — always stays
• •CHANGELOG.md — standard root-level file, keep as-is
• •LICENSE / LICENSE.md — standard root-level file, keep as-is
• •CODE_OF_CONDUCT.md — standard root-level file, keep as-is

If scattered files found, ask the user:

Found [N] markdown files in the project root:

  CONTRIBUTING.md (45 lines) — contribution guidelines
  ARCHITECTURE.md (120 lines) — system architecture overview
  DEPLOYMENT.md (80 lines) — deployment instructions
  SETUP.md (30 lines) — setup guide (overlaps with getting-started)

Suggested actions:
  → Move CONTRIBUTING.md → docs/contributing.md
  → Move ARCHITECTURE.md → docs/architecture.md
  → Move DEPLOYMENT.md → docs/deployment.md
  → Merge SETUP.md into docs/getting-started.md

Would you like to:
- [ ] Apply all suggestions
- [ ] Let me pick which ones
- [ ] Skip — keep files where they are

When moving/merging:

1. •Create the target file in docs/ with prev/next navigation header (following Documentation table order) and "See Also" footer
2. •If merging into an existing doc — append content under a new section header, avoid duplicating info that's already there
3. •Do NOT delete originals yet — keep them until the review step confirms everything is in place
4. •Add the new docs/ page to README's Documentation table
5. •Update any links in other files that pointed to the old root-level file
6. •Record which files were moved/merged — this list is used in Step 4.1

IMPORTANT: Never force-move files. Always show the plan and get user approval first.

Step 2 (State A): Generate from Scratch

When no README.md exists, generate the full documentation set.

2.1: Analyze project for documentation topics

Explore the codebase and identify documentation topics:

Always include:
- getting-started.md    (installation, setup, quick start)

Include if relevant:
- architecture.md       (if project has clear architecture: services, modules, layers)
- api.md                (if project exposes API endpoints)
- configuration.md      (if project has config files, env vars, feature flags)
- deployment.md         (if Dockerfile, CI/CD, deploy scripts exist)
- contributing.md       (if open-source or team project)
- security.md           (if auth, permissions, or security patterns exist)
- testing.md            (if test suite exists)
- cli.md                (if project has CLI commands)

Ask the user:

I've analyzed your project and suggest these documentation pages:

1. getting-started.md — Installation, setup, quick start
2. architecture.md — Project structure and patterns
3. api.md — API endpoints reference
4. configuration.md — Environment variables and config

Would you like to:
- [ ] Generate all of these
- [ ] Let me pick which ones
- [ ] Add more topics

2.2: Generate README.md

Structure (aim for ~80-120 lines):

# Project Name

> One-line tagline describing the project.

Brief 2-3 sentence description of what this project does and why it exists.

## Quick Start

\`\`\`bash
# Installation steps (1-3 commands)
\`\`\`

## Key Features

- **Feature 1** — brief description
- **Feature 2** — brief description
- **Feature 3** — brief description

## Example

\`\`\`
# Show a real usage example — this is where users decide "I want this"
\`\`\`

---

## Documentation

| Guide | Description |
|-------|-------------|
| [Getting Started](docs/getting-started.md) | Installation, setup, first steps |
| [Architecture](docs/architecture.md) | Project structure and patterns |
| [API Reference](docs/api.md) | Endpoints, request/response formats |
| [Configuration](docs/configuration.md) | Environment variables, config files |

## License

MIT (or whatever is in the project)

Key rules for README:

• •Logo/badge line at the top (if project has one)
• •Tagline as blockquote
• •Quick Start with real installation commands (detect from package manager)
• •Key Features as bullet list (3-6 items, scannable)
• •Real usage example that shows the "wow factor"
• •Documentation table with links to docs/
• •License at the bottom
• •NO long descriptions, NO full API reference, NO configuration details

2.3: Generate docs/ files

For each approved topic, create a doc file:

[← Previous Topic](previous-topic.md) · [Back to README](../README.md) · [Next Topic →](next-topic.md)

# Topic Title

Content organized by subtopic with headers, code examples, and tables.
Keep each section self-contained.

## See Also

- [Related Topic 1](related-topic.md) — brief description
- [Related Topic 2](other-topic.md) — brief description

Navigation link order follows the Documentation table in README.md (top to bottom). The first doc page omits the "← Previous" link; the last page omits the "Next →" link. Example for 4 pages:

getting-started.md:  [Back to README](../README.md) · [Architecture →](architecture.md)
architecture.md:     [← Getting Started](getting-started.md) · [Back to README](../README.md) · [API Reference →](api.md)
api.md:              [← Architecture](architecture.md) · [Back to README](../README.md) · [Configuration →](configuration.md)
configuration.md:    [← API Reference](api.md) · [Back to README](../README.md)

Content guidelines per topic:

getting-started.md:

• •Prerequisites (runtime versions, tools needed)
• •Step-by-step installation
• •First run / quick start
• •Verify it works (expected output)
• •Next steps links

architecture.md:

• •High-level overview (diagram if useful)
• •Directory structure with explanations
• •Key patterns (naming, imports, error handling)
• •Data flow

api.md:

• •Base URL / configuration
• •Authentication
• •Endpoints grouped by resource
• •Request/response examples
• •Error codes

configuration.md:

• •All environment variables with descriptions and defaults
• •Config files and their purpose
• •Feature flags

deployment.md:

• •Build steps
• •Environment setup
• •CI/CD pipeline description
• •Monitoring / health checks

Step 2 (State B): Split Existing README into docs/

When README.md exists but is long (150+ lines) and there's no docs/ directory.

2.1: Analyze README structure

Read README.md and identify:

• •Which sections should stay (landing page content)
• •Which sections should move to docs/ (detailed content)

Stays in README:

• •Title, tagline, badges
• •"Why?" / key features bullet list
• •Quick install (1-3 commands)
• •Brief example
• •Documentation links table
• •External links, license

Moves to docs/:

• •Detailed setup instructions → getting-started.md
• •Architecture / project structure → architecture.md
• •Full API reference → api.md
• •Configuration details → configuration.md
• •Contributing guidelines → contributing.md
• •Any section longer than ~30 lines that covers a single topic

2.2: Propose changes to user

Your README.md is [N] lines. I suggest splitting it:

README.md (~100 lines) — keep as landing page:
  ✓ Title + tagline
  ✓ Key features
  ✓ Quick install
  ✓ Example
  ✓ Documentation links table

Move to docs/:
  → "Installation" section → docs/getting-started.md
  → "Configuration" section → docs/configuration.md
  → "API Reference" section → docs/api.md
  → "Architecture" section → docs/architecture.md

Proceed?

2.3: Execute the split

1. •Create docs/ directory
2. •Create each doc file with content from README + prev/next navigation header (following Documentation table order) + "See Also" footer
3. •Rewrite README as landing page with Documentation links table
4. •Verify no content was lost — every section from old README must exist somewhere

Step 2 (State C): Improve Existing Docs

When both README.md and docs/ exist.

2.1: Audit current documentation

Check for:

• •README length — is it still a landing page (<150 lines)?
• •Missing topics — are there aspects of the project not documented?
• •Stale content — do docs reference files/APIs that no longer exist?
• •Navigation — do all docs have prev/next header links and "See Also"?
• •Broken links — verify all internal links point to existing files/anchors
• •Consistency — same formatting style across all docs
• •Standards compliance — does existing documentation match the current skill standards? (see 2.1.1)

2.1.1: Standards compliance check

Docs may have been generated by an older version of this skill. Compare existing docs against current Core Principles and templates. Common gaps to detect:

When gaps are found, include them in the audit report alongside content issues (Step 2.2). Treat them as regular improvements — show the plan and get user approval before applying.

Do NOT ask "was this generated by an older version?" — just silently detect what's missing and fix it. The user doesn't need to know about skill versioning; they just see their docs getting better.

2.2: Propose improvements

Documentation audit results:

✅ README is lean (105 lines)
⚠️  docs/ pages missing prev/next navigation — will add
⚠️  docs/api.md is missing — project has 12 API endpoints
⚠️  docs/configuration.md references old env var DB_HOST (now DATABASE_URL)
❌ docs/getting-started.md links to docs/setup.md which doesn't exist

Proposed fixes:
1. Add prev/next navigation to all docs/ pages
2. Create docs/api.md with endpoint reference
3. Update DATABASE_URL in docs/configuration.md
4. Fix broken link in docs/getting-started.md

Apply fixes?

Step 3: Generate HTML Version (--web flag)

When --web flag is passed, generate a static HTML site from the markdown docs.

3.1: Create docs-html/ directory

mkdir -p docs-html

3.2: Generate HTML files

For each markdown file (README.md + docs/*.md), generate an HTML version:

HTML template:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{page_title} — {project_name}</title>
  <style>
    :root {
      --bg: #ffffff;
      --text: #1a1a2e;
      --text-secondary: #555;
      --accent: #0066cc;
      --border: #e2e8f0;
      --code-bg: #f6f8fa;
      --nav-bg: #f8fafc;
    }
    @media (prefers-color-scheme: dark) {
      :root {
        --bg: #0d1117;
        --text: #e6edf3;
        --text-secondary: #8b949e;
        --accent: #58a6ff;
        --border: #30363d;
        --code-bg: #161b22;
        --nav-bg: #161b22;
      }
    }
    * { margin: 0; padding: 0; box-sizing: border-box; }
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
      line-height: 1.6;
      color: var(--text);
      background: var(--bg);
      max-width: 900px;
      margin: 0 auto;
      padding: 2rem 1.5rem;
    }
    nav {
      background: var(--nav-bg);
      border: 1px solid var(--border);
      border-radius: 8px;
      padding: 1rem 1.5rem;
      margin-bottom: 2rem;
    }
    nav a {
      color: var(--accent);
      text-decoration: none;
      margin-right: 1.5rem;
    }
    nav a:hover { text-decoration: underline; }
    nav a.active { font-weight: 600; }
    h1 { font-size: 2rem; margin: 1.5rem 0 1rem; border-bottom: 2px solid var(--border); padding-bottom: 0.5rem; }
    h2 { font-size: 1.5rem; margin: 2rem 0 0.75rem; }
    h3 { font-size: 1.2rem; margin: 1.5rem 0 0.5rem; }
    p { margin: 0.75rem 0; }
    a { color: var(--accent); }
    code {
      background: var(--code-bg);
      padding: 0.15em 0.4em;
      border-radius: 4px;
      font-size: 0.9em;
    }
    pre {
      background: var(--code-bg);
      border: 1px solid var(--border);
      border-radius: 8px;
      padding: 1rem;
      overflow-x: auto;
      margin: 1rem 0;
    }
    pre code { background: none; padding: 0; }
    table {
      width: 100%;
      border-collapse: collapse;
      margin: 1rem 0;
    }
    th, td {
      border: 1px solid var(--border);
      padding: 0.5rem 0.75rem;
      text-align: left;
    }
    th { background: var(--code-bg); font-weight: 600; }
    ul, ol { padding-left: 1.5rem; margin: 0.75rem 0; }
    li { margin: 0.25rem 0; }
    blockquote {
      border-left: 4px solid var(--accent);
      padding-left: 1rem;
      color: var(--text-secondary);
      margin: 1rem 0;
    }
    hr { border: none; border-top: 1px solid var(--border); margin: 2rem 0; }
    img { max-width: 100%; border-radius: 8px; }
  </style>
</head>
<body>
  <nav>
    {nav_links}
  </nav>
  <main>
    {content}
  </main>
</body>
</html>

3.3: Convert markdown to HTML

For each doc file:

1. •Parse markdown content (headers, code blocks, tables, links, lists, blockquotes, images)
2. •Convert to HTML elements
3. •Fix links: change .md references to .html (e.g., docs/getting-started.md → getting-started.html)
4. •Generate navigation bar with links to all pages
5. •Write to docs-html/ directory

File mapping:

README.md          → docs-html/index.html
docs/getting-started.md → docs-html/getting-started.html
docs/api.md        → docs-html/api.html
docs/configuration.md → docs-html/configuration.html

3.4: Output result

✅ HTML documentation generated in docs-html/

  docs-html/
  ├── index.html            (from README.md)
  ├── getting-started.html  (from docs/getting-started.md)
  ├── api.html              (from docs/api.md)
  └── configuration.html    (from docs/configuration.md)

Open in browser:
  open docs-html/index.html

Step 4: Documentation Review

MANDATORY after any content change (generation, split, improvement, file consolidation). Do NOT skip this step.

Skip this step only when "Generate HTML only" was chosen — no content was modified, nothing to review.

Read every generated/modified file and evaluate it against both checklists below. Fix any issues found before presenting the result to the user.

Technical Checklist

Verify structure, links, and completeness:

• • README.md is under 150 lines
• • README has: title, tagline, quick start, example, documentation table, license
• • Each docs/ file has prev/next navigation header following the Documentation table order
• • First doc page has no "← Previous" link; last page has no "Next →" link
• • Each docs/ file has "See Also" section at bottom with 2-3 related links
• • No content was lost during split/reorganization
• • All internal links work (no broken references, no dead anchors)
• • Code examples use the project's actual commands/syntax
• • Installation instructions are real and work (verified from package manager files)
• • No duplicate content between README and docs/
• • No scattered root-level .md files that should be in docs/

Readability Checklist — "New User Eyes"

Read every page as if you are a developer who has never seen this project before. For each page, verify:

First 10 seconds (above the fold):

• • Can I understand what this project does within 10 seconds of reading README?
• • Is the tagline clear and specific — not vague marketing ("next-gen solution")?
• • Is there a real install command I can copy-paste right now?

"Show, don't tell":

• • Does README have a concrete usage example (not just "install and run")?
• • Do code blocks show real commands with real output, not abstract placeholders?
• • Are examples copy-pasteable — no <placeholder> that the user must replace?

Scannability:

• • Can I find any specific topic in under 5 seconds by scanning headers?
• • Are paragraphs short (max 3-4 lines)? Long paragraphs get skipped
• • Are lists used instead of comma-separated inline enumerations?
• • Are tables used for structured data instead of nested bullet lists?

Jargon and assumptions:

• • Does the docs page explain acronyms on first use (or link to explanation)?
• • Are there no assumptions about internal knowledge? ("as described in the RFC" — which RFC?)
• • Would a junior developer understand each page without asking a colleague?

Navigation and flow:

• • After reading README, is it clear where to go next?
• • After finishing any docs/ page, do prev/next links and "See Also" guide me logically forward?
• • Is the Documentation table in README ordered by the path a new user would follow? (getting started → workflow → details)

Motivation:

• • Does the README answer "why should I care?" before "how does it work?"
• • Is there a "wow moment" — a feature or example that makes me want to try it?
• • Does the docs structure feel inviting, not overwhelming? (max 6-8 doc pages)

Presenting the Review

After running both checklists, present a summary:

📋 Documentation Review

Technical:
  ✅ All links verified (14 internal links, 0 broken)
  ✅ README is 108 lines
  ✅ All pages have navigation
  ⚠️  docs/api.md has a placeholder example — needs real endpoint

Readability:
  ✅ README explains purpose in first 10 seconds
  ✅ All code examples are copy-pasteable
  ⚠️  docs/architecture.md has a 12-line paragraph — should be split
  ⚠️  "CQRS" used without explanation in docs/architecture.md

Fixes applied:
  → Split long paragraph in docs/architecture.md into 3 shorter ones
  → Added "(Command Query Responsibility Segregation)" after first mention of CQRS
  → Replaced placeholder in docs/api.md with real endpoint example

All checks passed ✅

Step 4.1: Clean Up Moved Files

Only if files were moved/merged from root into docs/ during Step 1.1.

After the review confirms all content is correctly placed in docs/, offer to delete the original root-level files:

The following root files have been incorporated into docs/:

  CONTRIBUTING.md → now in docs/contributing.md
  ARCHITECTURE.md → now in docs/architecture.md
  DEPLOYMENT.md → now in docs/deployment.md
  SETUP.md → merged into docs/getting-started.md

These originals are no longer needed. Delete them?
- [ ] Yes, delete all originals
- [ ] Let me pick which ones to delete
- [ ] No, keep them (I'll clean up later)

When deleting:

1. •Verify one more time that the target docs/ file contains all content from the original
2. •Delete the root file
3. •Run git status to show what was deleted — user can restore with git checkout if needed

Do NOT auto-delete. Always ask. The user may want to keep originals temporarily for reference or diff comparison.

Step 5: Update AGENTS.md

After any documentation changes, update the Documentation section in AGENTS.md (if the file exists).

Read AGENTS.md and find the ## Documentation section. Update it to reflect the current state of all documentation files:

## Documentation
| Document | Path | Description |
|----------|------|-------------|
| README | README.md | Project landing page |
| Getting Started | docs/getting-started.md | Installation, setup, first steps |
| Architecture | docs/architecture.md | Project structure and patterns |
| API Reference | docs/api.md | Endpoints, request/response formats |
| Configuration | docs/configuration.md | Environment variables, config files |

Rules:

• •List README.md first, then all docs/ files in the same order as the README Documentation table
• •If files were moved/merged from root during Step 1.1, reflect the new locations
• •If new doc pages were created, add them
• •If doc pages were removed, remove them
• •Keep descriptions concise (under 10 words)
• •If AGENTS.md doesn't exist, skip this step silently

Context Cleanup

Context is heavy after codebase scanning and documentation generation. All docs are saved — suggest freeing space:

AskUserQuestion: Free up context before continuing?

Options:
1. /clear — Full reset (recommended)
2. /compact — Compress history
3. Continue as is

Important Rules

1. •Always ask before making changes to existing documentation — show the plan first
2. •Never delete content without moving it somewhere else
3. •Detect real project info — don't invent features, read package.json/config files
4. •Use the project's language — if project README is in Russian, write docs in Russian
5. •Preserve existing badges/logos — don't remove them during restructuring
6. •Add to .gitignore if generating HTML: add docs-html/ to .gitignore