docs

# Documentation system ## Layout and sources of truth - `docs/en/` — English pages. Handwritten pages (design/, guide/, dev/, index.md) are edited directly; feature pages (features/\*.md) contain GENERATED regions listing the documented cases (`tests/README.md`, "Docs"), and guide/configuration.md is rendered from the config schema. **Never edit inside a `<!-- BEGIN GENERATED ... -->` region** — edit the case's `README.md` or the config annotations instead. - `docs/cards/` — one card per documented case, written by the cases run (`UPDATE_SNAPSHOTS=1`); never edit by hand. - `docs/zh/` — Chinese pages, equally real and equally hand-edited (by a person or a model). Each zh page must stay **segment-isomorphic** to its en counterpart: same sequence of markdown blocks, translated text in the translatable blocks, code blocks and HTML comments byte-identical. - `docs/meta/translations/` — the hash pairs attesting each translated segment. Maintained exclusively by `record`; never edit by hand. - Each tree has its own hand-maintained `sidebar.yaml`. - `docs/public/clice-config.schema.json` — committed output of `clice inspect --config-schema`; CI checks freshness. ## Commands (pixi) | command | what it does | | ---------------------------------- | -------------------------------------------------- | | `pixi run check-feature-docs` | feature pages and cards match the cases (CI) | | `pixi run update-feature-docs` | rewrite feature GENERATED regions | | `pixi run check-config-docs` | configuration page matches the schema (CI) | | `pixi run update-config-docs` | rewrite the configuration page | | `pixi run check-doc-translations` | hard gate: zh isomorphic to en, all pairs attested | | `pixi run report-doc-translations` | translator worklist: drifted segments with texts | | `pixi run record-doc-translations` | re-attest hash pairs after deliberate edits | | `pixi run review-doc-translations` | model review of zh pages, segment by segment | ## Translation contract The checker is `@clice-io/translate` from the clice-io/docs repository, shared by every clice-io project with a Chinese tree. Its **RULES.md at v1.0.0** states the contract, the commands and the editing workflow — read it before any edit touching translated pages: gh api 'repos/clice-io/docs/contents/tools/translations/RULES.md?ref=v1.0.0' -H 'Accept: application/vnd.github.raw' CI runs `clice-io/docs/check-translations` in the lint workflow's docs job, pinned to an exact release; the pixi tasks above run that same release locally (`tools/docs/translations.ts` reads the pin, until the package is on npm and the tasks call `npx @clice-io/translate@1`). A new release is adopted by bumping the pin in lint.yml and the RULES.md references here and in the translate-docs skill. What clice adds on top: - In clice the frontmatter that translates is index.md's (the VitePress home page), and the bold paragraph whose shape must survive is a capability card's name; a table row paired with a later heading is a capability's status row and its section. - The formatter of step 4 in RULES.md's workflow is `pixi run format` (it canonicalizes table padding, emphasis style and CJK spacing). - The workflow applies to generated regions too: after `update-feature-docs` changes an en feature page, the zh page must receive the translated equivalent in the same PR — batched at the end of the branch, see below. - The wording — clice's page conventions and glossary — is the translate-docs skill. `review-doc-translations [page...]` passes that skill to the model as the glossary; review its diff, then `format` and `record`. Prefer it over handing a model whole pages: the code blocks would only burn its context. ## Syncing docs at the end of a branch Generated regions and translations are synced **once per branch, right before the checks** of the pr skill — not after every case or page edit, and not in the main conversation: delegate it to an Opus subagent so the report output and page texts never enter the main context. Give the subagent this skill and `git diff --name-only origin/main...HEAD`; its brief is: 1. If documented cases or config annotations changed: `pixi run update-feature-docs` and `pixi run update-config-docs` rewrite the en GENERATED regions. 2. `pixi run report-doc-translations` lists every broken pair with both texts. Translate each new or drifted en segment into the zh page, keeping the skeleton (same block kind, list marker, heading depth, nested code byte-identical) and the terminology of the surrounding page; delete zh segments whose en segment is gone. For whole new pages, or dozens of drifted pages, copy the en page over the zh one and run `review` on it (machine drafting, RULES.md). 3. `pixi run format`, then `pixi run record-doc-translations`, then `pixi run check-doc-translations`, `check-feature-docs` and `check-config-docs` — all green. 4. Report back: pages touched, how many segments were translated, and anything deliberately left as is. **docs/ contains no changelog content** — neither per-page "Changelog" sections nor changelog pages. Feature history lives in git and PRs; LLVM upgrade notes live in the upgrade-llvm skill's `llvm-changelog.md`. ## What belongs in a "Known Limitations" section Design-level, user-visible trade-offs that are stable on a months timescale, written in behavior terms — they answer the reader's "why does it work this way". Bugs never go there: they live in the internal bug inventory and simply disappear when fixed; putting them in docs creates staleness debt. Feature coverage gaps are already expressed by the generated status tables. The flow is one-way: an internal item graduates into a doc limitation only once it is decided to be design (or long-term deferral), and a doc limitation is removed only when the design changes. Never reference internal IDs, file paths, or timelines in docs.