doc-update

name: doc-update description: Run a documentation audit for MonorepoOnFire. Verifies all READMEs and doc/ guides against the actual codebase — scripts, routes, schemas, exports, env vars, middleware, CI workflows. Use after code changes or when running /doc-update.

MonorepoOnFire Documentation Update

Audit and fix all documentation files so they match the current codebase state.

File Inventory

READMEs (7 files)

Doc Guides (7 files)

Other

Verification Checks

Run each check against the actual codebase. Report discrepancies as a table.

A. Scripts vs package.json

Compare every pnpm <script> mentioned in docs against actual scripts in the relevant package.json. Flag missing, renamed, or removed scripts.

B. File Structure vs Filesystem

Compare directory tables (e.g., "Project Structure") in READMEs against ls output. Flag missing or renamed directories.

C. Routes vs Route Modules

Compare API routes listed in docs against src/routes/ files in app/hono. Flag undocumented or removed routes.

D. Package Exports vs package.json

Compare exported modules listed in package READMEs against exports field in each package/*/package.json. Flag mismatches.

E. Environment Variables vs env.ts

Compare env vars documented in READMEs and guides against the Zod schema in src/environment/env.ts for both app/hono and app/portfolio. Flag undocumented or removed variables.

F. Database Schemas vs Schema Files

Compare database tables/columns described in docs against Drizzle schema files in app/hono/src/database/schema/. Ensure all docs reference PostgreSQL (never SQLite, Turso, or LibSQL).

G. Middleware Stack vs create-app.ts

Compare middleware listed in docs against the actual middleware chain in app/hono/src/library/create-app.ts.

H. CI Workflows vs CLAUDE.md

Compare CI commands and workflow descriptions against .github/workflows/ YAML files and CLAUDE.md entries.

I. Mermaid Diagrams vs Actual Relationships

Verify Mermaid diagrams in doc/architecture-overview.md reflect current package dependencies and data flow.

J. Screenshots vs Filesystem

Verify screenshot references in doc/screenshots.md and README.md point to files that exist in doc/screenshots/.

Style Conventions

Follow these rules when writing or fixing documentation:

Headers

• No emoji in headers — use plain text
• Use ## for major sections, ### for subsections
• Keep headers short and scannable

Code Blocks

• Always use language tags: ```bash, ```typescript, ```env
• Show realistic examples, not placeholders

Tables

• Use tables for structured data (directory listings, env vars, features)
• Align columns with pipes

Mermaid Diagrams

• Vertical layout only: graph TD or flowchart TB
• Never use graph LR or horizontal layouts
• Keep node labels concise

Database References

• Always say PostgreSQL — never SQLite, Turso, LibSQL, or "the database" ambiguously
• Connection strings use postgresql:// URI format
• ORM is always "Drizzle ORM with PostgreSQL"

Tone

• Professional, concise, visual
• Primary audience: recruiters and portfolio visitors
• Secondary audience: developers evaluating the codebase
• Show don't tell — prefer tables, diagrams, and code over paragraphs

Badges

• Use shields.io badges in root README only
• Keep badge row clean — no redundant or broken badges

Workflow

When running this skill:

1. Read all files from the inventory above
2. Run each verification check (A through J)
3. Report findings as a discrepancy table:

4. Apply fixes to all discrepancies found
5. Verify — re-run the grep checks:
   • grep -ri "sqlite\|turso\|libsql" across all doc files — expect 0 matches
   • Confirm all script references resolve
   • Confirm all file paths exist

Post-Code-Change Checklist

After modifying code, check which docs need updates: