# Documentation Map

Authoritative inventory of this repository's documentation surface: every doc that must be kept in sync, what each contains, and the stable anchors to grep for when placing an edit. Section line numbers drift — grep the anchor strings, don't trust line numbers.

## Tier 1 — primary, always consider

### `README.md` (English, canonical)
The source of truth most other docs mirror. Key sections:
- **Feature table** — rows like `**Kanban Board**`, `**Transcript Cache**`, `**Pre-Existing Session Detection**`, `**Continuous Project Sync**`. Grep a neighboring row label.
- **Data-flow numbered list** — bullets describing hook ingestion, the watchdog, periodic sweep, continuous sync. Grep `Error detection watchdog` / `periodic server sweep`.
- **Agent State Machine** + **Session State Machine** — two `mermaid stateDiagram-v2` blocks. Grep `stateDiagram-v2`.
- **Hook Events table** — `| Hook Type | Trigger | Dashboard Action |`. Lists `SessionStart`…`SessionEnd`, plus synthetic `Compaction`, `APIError`, `TurnDuration`, `ToolError`, `Interrupted`. Grep `## Hook Events`.
- **Configuration / Environment Variables table** — `| Environment Variable | Default | Description |`. Grep `DASHBOARD_PORT` or `DASHBOARD_HOST`.

### `README-CN.md` / `README-VN.md` / `README-KO.md` / `README-ES.md` (full translations)
Standalone full translations of `README.md` — zh, vi, ko, es. **Every** README change must be mirrored into **all four** at the corresponding section. Terminology, glossary, and the never-translate list live in [`.claude/skills/i18n-parity/references/translation-style.md`](../../i18n-parity/references/translation-style.md); verify with `bash .claude/skills/i18n-parity/scripts/i18n-audit.sh`. Conventions:
- Keep in English/code: identifiers, env-var names, event-type names, `awaiting_input_since`, `pendingInterrupt`, "watchdog", `fs.watch`, model IDs, mermaid transition labels.
- Translate prose. "Waiting" → **等待中** (zh) / **Đang chờ** (vi) / **대기 중** (ko) / **En espera** (es). "watchdog" often kept; in zh sometimes 看门狗.
- The second (update-checker) env table exists in EN but may be absent in VN/CN — don't invent rows that aren't there.

### `ARCHITECTURE.md`
- **Module responsibility table** — one row per source file (`scripts/import-history.js`, `lib/transcript-cache.js`, `routes/hooks.js`, `server/index.js`, …). Update the row whose file you changed. Grep the file path.
- **Data-flow + sequence diagrams**, **state machines**, **Continuous background sync** prose block (grep `Continuous background sync`).
- **Event types line** — grep `| Event types |`.
- **ERD / schema** mermaid + `event_type "PreToolUse|PostToolUse|Stop|etc"`.

### `index.html` (root landing / marketing)
Feature cards (`<div class="feature-card">`) with concise marketing copy. Light touch only — one sentence in the most relevant existing card. Grep an existing feature headline (e.g. `History import`, `Kanban`).

### `wiki/index.html` + `wiki/i18n-content.js` + `wiki/sw.js`
Detailed wiki. Governed by `.claude/rules/wiki-i18n.md`:
- Add prose/tables/diagrams in `wiki/index.html` (Hook table `<th>Hook Type</th>`, Environment Variables `<th>Variable</th>`, mermaid `stateDiagram-v2` blocks).
- For **every new English string**, add a `zh`, `vi`, `ko`, and `es` entry in `wiki/i18n-content.js` (keyed by the exact English text). See `.claude/skills/i18n-parity/` for the full wiki mechanism.
- **Bump the cache**: increment `CACHE_NAME` in `wiki/sw.js` (e.g. `wiki-v24` → `wiki-v25`) AND the `i18n-content.js?v=N` query in `wiki/index.html`. Without this, returning visitors get stale cached content.

## Tier 2 — area-specific

### `server/README.md`
Backend reference: routes table, **Error Detection Watchdog** / **User-Interrupt (Esc) Recovery** / **Continuous Project Sync** sections, Agent/Session lifecycle mermaid diagrams, Environment Variables bash block under `## Deployment`. Update for any backend behavior, route, state, env var, or background service.

### `client/README.md`
Frontend reference: component list, **Event Types** table (WebSocket broadcast message types like `session_created`, `agent_updated`), session/agent status TypeScript unions. Update for new WS message types or client-facing behavior. NOT needed for server-only changes the UI already renders generically.

### `docs/HOOKS.md`
Per-hook deep reference (`### 1. SessionStart` … `### 8. SessionEnd`), the `awaiting_input_since` overlay rules, the "User interrupts (Esc) — no hook fires" section, transcript-derived sync. Update for any hook semantics or state behavior.

### `docs/DATABASE.md`
Schema reference: `sessions` / `agents` / `events` tables, column docs, status CHECK constraints, lifecycle mermaid diagrams. Update for schema or state-machine changes.

### `docs/API.md`
REST API reference (endpoints, params, example responses). Update for route/response changes. Pair with `server/openapi*.js` (code, not docs).

### `docs/PLUGINS.md`
Plugin/marketplace docs incl. an **Event Types** enumeration line — keep it in sync with the canonical event-type list.

### `docs/MCP.md` + `mcp/README.md`
MCP server + tool reference. Update for new/changed MCP tools.

### `docs/I18N.md`
i18n architecture: **Supported languages** list, `supportedLngs`, the 15 namespaces. Update when adding a language or namespace. Client UI strings live in `client/src/i18n/locales/{en,zh,vi,ko,es}/*.json` (code).

## Tier 3 — situational

- `.env.example` — every env var belongs here with a sane default + comment.
- `INSTALL.md`, `SETUP.md`, `DEPLOYMENT.md`, `docs/DEPLOYMENT.md` — install/run/deploy commands.
- `CLAUDE.md`, `AGENTS.md` — agent working guides; update when commands, file locations, or workflows change.
- `docs/README.md` — docs index; add a link when a new `docs/*.md` is created.
- `desktop/README.md`, `vscode-extension/README.md`, `statusline/README.md` — surface-specific; update only when that surface changes.

## Consistency invariants

- The **event-type set** must match across: `README` hook table (+CN/VN/KO/ES), `ARCHITECTURE` Event types line, `docs/PLUGINS.md`, `wiki`. When adding one, grep the existing set (e.g. `TurnDuration`) across all and add everywhere it appears.
- **Env-var set** must match across: README (+CN/VN/KO/ES) tables, `server/README.md`, `wiki`, `.env.example`, and any inline `ARCHITECTURE` mention.
- **State-machine diagrams** are duplicated across README (+CN/VN/KO/ES), `server/README.md`, `docs/DATABASE.md`, `wiki`. A transition change touches all of them.
- Run `scripts/doc-coverage.sh <term>` to confirm a new identifier/var/event reached every doc that should mention it.

#!/usr/bin/env bash
# doc-coverage.sh — verify that one or more terms (a new env var, event type,
# route, identifier, feature name, …) are documented across this repo's
# canonical doc surface. Prints a HIT/miss matrix so a docs update can be
# checked for "full coverage" before finishing.
#
# Usage:
#   .claude/skills/update-project-docs/scripts/doc-coverage.sh DASHBOARD_SESSION_SYNC_MS
#   .claude/skills/update-project-docs/scripts/doc-coverage.sh Interrupted pendingInterrupt
#
# Run from the repo root. Exit code is non-zero if any term is missing from a
# doc that the change-type mapping (see references/doc-map.md) says it belongs
# in — but treat the matrix as advisory: not every term belongs in every file.
# @author Son Nguyen <hoangson091104@gmail.com>

set -u

# The canonical doc set kept in sync. Translations + HTML + per-area READMEs.
DOCS=(
  "README.md"
  "README-VN.md"
  "README-CN.md"
  "README-KO.md"
  "README-ES.md"
  "ARCHITECTURE.md"
  "index.html"
  "wiki/index.html"
  "wiki/i18n-content.js"
  "server/README.md"
  "client/README.md"
  "docs/HOOKS.md"
  "docs/DATABASE.md"
  "docs/API.md"
  "docs/PLUGINS.md"
  "docs/MCP.md"
  "mcp/README.md"
  "docs/I18N.md"
  ".env.example"
)

if [ "$#" -eq 0 ]; then
  echo "usage: $0 <term> [term2 ...]" >&2
  exit 2
fi

missing_any=0
for term in "$@"; do
  echo "── coverage for: $term ──────────────────────────────"
  for doc in "${DOCS[@]}"; do
    if [ ! -f "$doc" ]; then
      printf "  %-26s (absent)\n" "$doc"
      continue
    fi
    n=$(grep -Fc -- "$term" "$doc" 2>/dev/null || true)
    n=${n:-0}
    if [ "$n" -gt 0 ]; then
      printf "  ✅ %-26s %s\n" "$doc" "$n"
    else
      printf "  ·  %-26s 0\n" "$doc"
    fi
  done
  echo
done

exit $missing_any

#!/usr/bin/env bash
# wiki-block-lengths.sh — measure the length of the wiki's fixed-size prose
# blocks so a new entry matches the ones already there instead of blowing up
# the layout. The feature carousel gives every card the same box: a card that
# is far longer than its neighbours overflows or squashes the whole carousel.
#
# Usage (from the repo root):
#   .claude/skills/update-project-docs/scripts/wiki-block-lengths.sh          # both groups
#   .claude/skills/update-project-docs/scripts/wiki-block-lengths.sh cards
#   .claude/skills/update-project-docs/scripts/wiki-block-lengths.sh captions
#
# Prints one line per block (character count of the tag-stripped text) plus the
# min/median/max of the group and flags any block outside the existing range.
# @author Son Nguyen <hoangson091104@gmail.com>

set -u
cd "$(git rev-parse --show-toplevel 2>/dev/null || echo .)" || exit 1
WHICH="${1:-all}"

python3 - "$WHICH" <<'PY'
import re, statistics, sys
from html import unescape

which = sys.argv[1]
html = open("wiki/index.html", encoding="utf-8").read()
strip = lambda s: unescape(" ".join(re.sub(r"<[^>]+>", "", s).split()))
status = 0


def report(title, items, tolerance):
    """tolerance is the multiple of the group median a block may not exceed.
    Carousel cards share one fixed-height box, so they get the tighter bound."""
    global status
    if not items:
        return
    lengths = [n for _, n in items]
    lo, hi = min(lengths), max(lengths)
    # Keep this arithmetic identical to the gate in client/tests/wiki-i18n.test.ts:
    # statistics median (mean of the two middles when the group is even), then
    # truncate both it and the budget, so the two never disagree on a block.
    med = int(statistics.median(lengths))
    budget = int(med * tolerance)
    print(
        f"\n{title} — {len(items)} blocks | min {lo} · median {med} · max {hi} chars"
        f" | budget {budget}"
    )
    for name, n in items:
        flag = ""
        if n > budget:
            flag = "  <-- TOO LONG: trim toward the median"
            status = 1
        print(f"  {n:5d}  {name}{flag}")


if which in ("all", "cards"):
    # The carousel runs to the end of its section; `.feature-card` is also used
    # in grids elsewhere on the page, so bound the slice instead of scanning all.
    start = html.index('<div class="carousel" id="feature-carousel">')
    seg = html[start : html.index("</section>", start)]
    # Most cards carry an `id` on their <h3> (they are cross-referenced from the
    # nav and from other docs), but plenty do not — match the card container and
    # fall back to the heading text so no card escapes the budget.
    card_re = re.compile(
        r'<div\b[^>]*\bclass="[^"]*\bfeature-card\b[^"]*"[^>]*>'
        r'.*?<h3(?:[^>]*\bid="([^"]+)")?[^>]*>(.*?)</h3>\s*<p>(.*?)</p>',
        re.S,
    )
    cards = [
        (m.group(1) or strip(m.group(2)), len(strip(m.group(3))))
        for m in card_re.finditer(seg)
    ]
    report("Feature carousel cards", cards, 1.5)

if which in ("all", "captions"):
    # Same class-token match as the cards: one caption carries an inline style,
    # and an exact-tag pattern would skip it.
    caption_re = re.compile(
        r'<div\b[^>]*\bclass="[^"]*\bscreenshot-caption\b[^"]*"[^>]*>(.*?)</div>', re.S
    )
    caps = [
        (strip(m.group(1))[:48], len(strip(m.group(1)))) for m in caption_re.finditer(html)
    ]
    report("Screenshot captions", caps, 2.0)

print()
sys.exit(status)
PY