doc-gen

name: doc-gen description: > Generate and maintain project documentation — README files, CLAUDE.md guides, docs/ architecture guides, Playwright screenshots, and ASCII/Mermaid diagrams for the AllOnFire monorepo. Use when asked to "generate docs", "create README", "update documentation", "refresh screenshots", "audit docs", "document this feature", "add docs", or "doc-gen".

Doc-Gen Skill

Generate and maintain documentation for the AllOnFire monorepo. Read references/doc-standards.md before generating any documentation — it contains all visual rules, templates, and preferences learned from past sessions.

Prerequisites

• Target app running for screenshot capture: Social on :3100, Laura on :3200
• Playwright MCP tools available for browser automation
• Read references/doc-standards.md for visual formatting rules
• Read references/doc-map.md for the full inventory of documentation targets

Scope Argument

If no scope is provided, default to audit.

Critical Style Rules

These were learned from user feedback and MUST be followed:

Structure

1. <h1 align="center"> for all README page titles — NOT <h3>, NOT markdown #
2. Exception: root README uses <h3> to avoid GitHub h1 underline
3. Centered header block — title + badges + description all in <p align="center">
4. Left-aligned section headings — standard markdown ## with emoji prefix
5. Consistent layout — every README follows the same header → screenshots → sections pattern

Badges

6. Always HTML <img> tags inside <p align="center"> — NEVER markdown ![]()
7. Default flat style — never flat-square
8. Root badges = monorepo stack only — pnpm, Turborepo, TypeScript, Biome, Node
9. App/feature/package badges = their specific stack

Screenshots

10. 2-column grid — desktop + mobile side by side in ONE <p>, never separate blocks
11. Feature READMEs: desktop 600, mobile 200
12. App README gallery: desktop 550, mobile 180
13. Hide Next.js dev tools before every screenshot capture (see doc-standards.md for the JS snippet)
14. Path depth matters — features are 5 levels deep (../../../../../docs/screenshots/)

Content

15. No box-drawing characters — use plain ──>, +--, | only
16. Plain indentation for directory trees — NOT ├── and └──
17. Actual Unicode emoji — 📸 not :camera_flash:, 📁 not :file_folder:
18. Brief descriptions between heading and content
19. Root README is generic — describes monorepo, NOT specific apps

Files & Assets

20. .png for logos in READMEs (better preview than .svg)
21. docs/assets/ for logos/icons copied from app public/ folders
22. /screenshots/ in gitignore (root-only slash) — NOT screenshots/ which blocks docs/screenshots/
23. No sensitive infra details — no machine types, IPs, SSH info
24. LICENSE (MIT) at repo root

Workflow

Phase 0: Consistency Audit (Regression Detection)

Always run this before any generation. Detects drift between docs and code.

1. Route drift — Glob all page.tsx files under each app's app/ directory. Compare against routes listed in the app's README. Flag: added routes not in README, removed routes still in README.

2. Environment variable drift — Parse env.ts files (app-level + package-level extends). Compare against env vars table in README. Flag: new vars not documented, removed vars still listed.

3. Screenshot path validation — Parse every <img src="..." in all READMEs. Verify the referenced file exists on disk. Flag: broken image references.

4. Feature directory sync — List actual feature directories under each app's src/features/. Compare against documented features in doc-map. Flag: new features without docs, removed features with stale docs.

5. Package export audit — Read each package's src/index.ts exports. Compare against API Reference table in package README. Flag: new exports not documented, removed exports still listed.

6. Badge version check — Parse package.json for each app/package. Compare major versions against badge values in README. Flag: version mismatches (e.g., badge says React 18 but package.json has React 19).

Output: Status table with pass/warn/fail for each check, grouped by app/package.

Phase 1: Audit Existing Documentation

Always run this first, regardless of scope.

1. Scan for all README.md, CLAUDE.md, and docs/ directories
2. Compare against references/doc-map.md
3. Report a status table
4. If scope is audit, stop here

Phase 2: Screenshots (scope: screenshots)

Save to docs/screenshots/ (NOT /screenshots/ which is gitignored).

For each page: browser_resize → browser_navigate → hide dev tools (see snippet in doc-standards.md) → browser_take_screenshot.

Social App (port 3100)

Desktop (1440x900): dashboard, discover, generate, publish-compose, admin-users, admin-providers, settings. Mobile (390x844): mobile-dashboard, mobile-discover, mobile-generate, mobile-publish, mobile-admin, mobile-settings.

Laura App (port 3200)

Desktop (1440x900): laura-gallery, laura-upload, laura-games, laura-memory, laura-quiz, laura-settings. Mobile (390x844): mobile-laura-gallery, mobile-laura-upload, mobile-laura-games, mobile-laura-memory, mobile-laura-quiz, mobile-laura-settings.

Laura-specific: Wait for Framer Motion animations to settle (2s delay) before capture. Laura uses Italian locale by default — screenshots show /en routes for English.

Phase 3: Root README (scope: root)

Follow the structure in references/doc-standards.md Section 6 exactly:

1. Logo (centered, 80px) from docs/assets/
2. Title as <h3 align="center"> — no tagline
3. <br /> spacer
4. Root badges (monorepo stack only)
5. --- divider
6. About section (1-2 generic sentences about the monorepo)
7. Apps section — each app vertical: logo → title → app-specific badges → description → docs link
8. --- divider
9. Packages — emoji table with brief description above
10. Project Structure — badges for infra tech + description + plain-indentation folder tree
11. Infrastructure — emoji table with brief description above. No sensitive details.
12. --- divider
13. Footer — centered casual sign-off

Phase 4: Package READMEs (scope: packages)

Use the template in references/doc-standards.md Section 8.

Read the package's src/index.ts to discover the API surface. Read consuming files in apps/social/ for usage examples.

Phase 5: Feature Documentation (scope: features)

Use sidebar-layout/ as the template — read both its README.md and CLAUDE.md, then replicate that structure.

Templates in references/doc-standards.md Sections 9 and 10.

Important: Read every file in the feature directory before writing. Document what actually exists.

Phase 6: Docs Guides (scope: diagrams)

Create numbered guides in docs/:

Phase 7: Memory Update (scope: memory)

1. Update project_structure.md if feature names have changed
2. Add project_documentation.md describing where docs live
3. Update MEMORY.md index

Phase 8: Full Run (scope: all)

Execute phases 1-7 in priority order. Present audit first, ask for confirmation.

Rules

• Read before writing — always read actual source code before generating docs
• Conservative updates — only modify sections with actual discrepancies
• No bloat — no extra comments or explanations beyond the template
• Match style — follow references/doc-standards.md exactly
• No speculation — do not document planned features
• sidebar-layout is the template — all feature docs match its structure