Skip to content

Deduplicate agent docs and READMEs, fix stale docs - #323

Merged
kaareal merged 1 commit into
masterfrom
feature/align-claude-agent-docs-2d7b1d
Sep 24, 2026
Merged

kaareal merged 1 commit into
masterfrom
feature/align-claude-agent-docs-2d7b1d

Conversation

@kaareal

@kaareal kaareal commented Sep 24, 2026

Copy link
Copy Markdown
Collaborator

What

  • No duplication: root and web AGENTS.md now route to README.md / PRODUCT.md / DESIGN.md / THEME.md instead of restating toolchain, stack, commands, design rules or product description. Service READMEs link to the root README for Volta/pnpm setup.
  • Generator removed: the generator directory hasn't existed since 2020. Dropped it from AGENTS.md, PRODUCT.md, DESIGN.md (Parity Rule), the API README (bedrock generate docs) and the broken generate script in services/web/package.json.
  • Stale docs fixed:
    • web SERVER_PORT default is 2200, not 2300
    • config is injected as window.__ENV__, not window.__env_conf
    • index.html is the entry point (not src/index.html); serve/dev.js doesn't exist
    • API docs flow is openapi.json + pnpm docs:generate + MDX pages (not src/routes/__openapi__)
    • THEME.md and PRODUCT.md now include the Bricolage Grotesque heading font and Indigo default

Reviewer notes

  • Docs only, plus one removed npm script. No runtime code changed.
  • The rewritten docs sections (API docs portal, env injection) were checked against the source, not by running pnpm docs:generate or the app.
  • Every relative link and file path in tracked markdown resolves, except credentials.conf, which Git ignores on purpose.

Each fact now lives in one place: AGENTS.md files route to README,
PRODUCT, DESIGN and THEME instead of restating them. Removes references
to the generator (deleted in 2020) and its broken `generate` script, and
corrects docs that drifted from the code (web port, env injection,
OpenAPI docs flow, fonts, brand defaults, missing file paths).
@github-actions

Copy link
Copy Markdown

API Changes

No changes.

@kaareal
kaareal merged commit 9c91ae1 into master Sep 24, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant