nntrivi2001
9a4ed54cf7
- Plugin bootstrap: a failed npm install, a Node older than 22.5 or a failed UI build is recorded in runtime/last-failure.json; the next SessionStart prints it once as a systemMessage naming the log and /agenthub-doctor (a different failure is reported again; a successful bootstrap clears it). The foreground pass checks the Node version itself and spawns no worker on an old Node. - ReDoc: the standalone bundle (redoc 2.5.4, MIT, licence files kept) is vendored under server/vendor/redoc/ and the `redoc` dependency dropped — a runtime install (npm ci --omit=dev --ignore-scripts) goes 126 MB -> 45 MB. vendor/ is excluded from the header audit and prettier. - git missing from PATH: lane git actions answer 503 EGITMISSING with the install command instead of a bare ENOENT. - package.json engines: node >=22.5.0 (node:sqlite), matching MIN_NODE. - Docs: INSTALL.md is the one install/setup guide (SETUP.md merged in and now a pointer); no VS Code extension claim, one client-install hint, no windows-build-tools, better-sqlite3 notes scoped to checkouts, new "Plugin bootstrap never comes up" troubleshooting entry.
63 lines
6.3 KiB
Markdown
63 lines
6.3 KiB
Markdown
---
|
|
name: update-project-docs
|
|
description: MANDATORY for every coding agent (Claude Code, Codex, or any other) — keep this repository's documentation in sync after any change to behavior, configuration, interfaces, events, schema, or features. Use automatically (without being asked) at the end of ANY change-set that adds or alters an env var, event type, hook behavior, session/agent state transition, API route or response shape, DB schema, WebSocket message, MCP tool, CLI command, or user-facing feature — and whenever the user asks to "update the docs / README / architecture". Knows the full doc surface (README, ARCHITECTURE, server/client READMEs, docs/*) and which docs each kind of change touches.
|
|
---
|
|
|
|
# Update Project Docs
|
|
|
|
This repository keeps a large doc set and docs drift silently, because one change often belongs in several files at once. This skill encodes **which docs exist, which change-types touch which docs, and how to propagate consistently**. The root `README.md` is a short Vietnamese install page only (requirements + the two install paths) — never grow it back; the full feature reference is `docs/OVERVIEW.md` (English, canonical) mirrored by `docs/OVERVIEW.vi.md`. The wiki and the root landing page were removed; do not recreate them.
|
|
|
|
Authoritative inventory with exact section anchors lives in [`references/doc-map.md`](references/doc-map.md) — read it when deciding where a specific change lands. The repo rule [`.claude/rules/docs-markdown.md`](../../rules/docs-markdown.md) ("update all affected docs together") is binding.
|
|
|
|
## When to update (including without being asked)
|
|
|
|
Update docs **in the same change-set (PR/commit) as the code**, before claiming done — do not wait for the user to ask — whenever the change is observable from outside the module:
|
|
|
|
- **New/changed env var** → every env-var table + `.env.example`.
|
|
- **New event type** (e.g. an `events.event_type` value) → every event-type list/table.
|
|
- **New/changed hook behavior or session/agent state transition** → hook docs + every state-machine diagram.
|
|
- **New/changed API route or response shape** → API docs + route tables + OpenAPI.
|
|
- **DB schema change** (table/column/index) → database docs + ERD.
|
|
- **New WebSocket message type** → client/server WS docs.
|
|
- **New MCP tool** → MCP docs.
|
|
- **New CLI command / script / renamed file referenced in docs** → command lists + onboarding guides.
|
|
- **New user-facing feature / page / background service** → feature tables + architecture.
|
|
|
|
**Do NOT** auto-update for: pure internal refactors with no observable/interface/config change, test-only changes, comment/typo fixes, or work the user explicitly scoped as "no docs". When unsure whether a change is observable, check the mapping below; if it touches any row, update.
|
|
|
|
## Change → docs mapping
|
|
|
|
| Change type | Docs to update |
|
|
|---|---|
|
|
| **Env var** | `docs/OVERVIEW.md` (env table), `ARCHITECTURE.md` (inline), `server/README.md`, `.env.example` |
|
|
| **Event type** | `docs/OVERVIEW.md` (hook-event table), `ARCHITECTURE.md` (Event types line), `docs/PLUGINS.md`, `docs/DATABASE.md` (if it enumerates types), plus the `en`/`vi` strings under `client/src/i18n/locales/` if the type is rendered |
|
|
| **Hook behavior / state transition** | `docs/HOOKS.md`, the state-machine **mermaid** diagrams in `docs/OVERVIEW.md`, `server/README.md` and `docs/DATABASE.md`, `ARCHITECTURE.md` (hooks.js row) |
|
|
| **API route / response** | `docs/API.md`, `server/README.md` (routes), `ARCHITECTURE.md` (routes row), `server/openapi.js` + `server/openapi-extra/*.js` (code), then regenerate `openapi.yaml` with `npm run openapi:yaml` |
|
|
| **DB schema** | `docs/DATABASE.md`, `ARCHITECTURE.md` (ERD/schema) |
|
|
| **WebSocket message** | `client/README.md` (Event Types), `server/README.md` |
|
|
| **Feature / page / background service** | `docs/OVERVIEW.md` (feature table + data-flow list), `ARCHITECTURE.md` (module table), `server/README.md` or `client/README.md` |
|
|
| **CLI command / script** | `docs/OVERVIEW.md` commands, `CLAUDE.md` / `AGENTS.md`, `INSTALL.md` |
|
|
| **New language** | `docs/I18N.md`, `client/src/i18n/locales/<xx>/*`, `client/src/i18n/index.ts` (add to `supportedLngs` AND the `resources` map) |
|
|
|
|
## Procedure
|
|
|
|
1. **Classify** the change against the table above. A change can hit multiple rows (a new feature with a new env var hits both).
|
|
2. **Write the canonical version first** — usually `docs/OVERVIEW.md` and/or `ARCHITECTURE.md`. Get the wording right there; it anchors everything else.
|
|
3. **Area READMEs / docs/**: update `server/README.md`, `client/README.md`, and the relevant `docs/*.md` per the mapping.
|
|
4. **Diagrams**: when a state transition changes, edit every mermaid `stateDiagram-v2` block that models it (they are duplicated across README, server/README and docs/DATABASE). Keep transition labels consistent.
|
|
|
|
## Verify (do not skip)
|
|
|
|
- **Coverage**: grep the new term (env var / event type / identifier) across the docs the mapping flags — `grep -rn "<new-term>" README.md ARCHITECTURE.md server/README.md client/README.md docs/` — and confirm each flagged doc actually shows a hit. Advisory, not mechanical: not every term belongs in every file, but a flagged doc with zero hits is a miss to fix.
|
|
- **Tables**: markdown tables stay pipe-balanced (header column count == every row).
|
|
- **Mermaid**: each edited block still parses (valid `source --> target: label`).
|
|
- **i18n**: every new English string has a `vi` entry in `client/src/i18n/locales/vi/`.
|
|
- **Format/tests**: run `npm run format` (or `prettier --check` on touched files); for any code touched, run only the related tests per `CLAUDE.md` (`npm run test:server -- <test file>` / `npx vitest related <files> --run`); a full suite only when `CLAUDE.md` says it is needed.
|
|
- State exactly which docs were updated and which were intentionally skipped (with reason), mirroring the repo's verification policy.
|
|
|
|
## Tips
|
|
|
|
- The fastest way to find where something already lives: `grep -n "<existing-neighbor-term>" <doc>` (e.g. grep an adjacent env var to find the env table). `references/doc-map.md` lists the stable anchors per file.
|
|
- Parallelize independent doc edits across subagents when the change is large, but write the canonical `README.md`/`ARCHITECTURE.md` edit yourself first so every other file has a faithful source.
|
|
- One language/area per subagent keeps edits reviewable and tables un-corrupted.
|