Files

T

nntrivi2001 9a4ed54cf7 perf: lighter, louder local install — vendored ReDoc, bootstrap failures shown in the session

- 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.

2026-10-16 10:16:54 +07:00

6.3 KiB

Raw Blame History

name, description

name	description
update-project-docs	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.

name

description

update-project-docs

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 — read it when deciding where a specific change lands. The repo rule .claude/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

Classify the change against the table above. A change can hit multiple rows (a new feature with a new env var hits both).
Write the canonical version first — usually docs/OVERVIEW.md and/or ARCHITECTURE.md. Get the wording right there; it anchors everything else.
Area READMEs / docs/: update server/README.md, client/README.md, and the relevant docs/*.md per the mapping.
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.

6.3 KiB Raw Blame History