opi-document

name	opi-document
disable-model-invocation	true
description	Update opi documentation so shipped claims remain truthful and English and Chinese counterparts stay synchronized. Use for README/doc refreshes, documentation drift, localized mirrors, or the documentation phase before a release.

Opi Document

Maintain current product documentation from authoritative source. Historical plans and snapshots remain historical evidence; they are not current-product truth and are not rewritten merely to make a check pass.

Inputs

scope=<full | targeted | version-bump>   # default: targeted
files=<path,...>                         # optional exact paths
version=<X.Y.Z>                          # required for version-bump

When scope=targeted omits files, use the shared change-scope reference for candidate discovery only. It may locate outgoing documentation surfaces, but source ownership and this skill's inputs retain documentation authority; the diff does not expand the requested scope or authorize a repository-wide rewrite.

1. Establish the documentation delta

Read the affected source, [Unreleased] plus the latest release in CHANGELOG.md, the workspace version, and the relevant current docs. Classify candidate edits as:

• drift: a current claim is false, stale, or unverifiable;
• noise: internal milestone language that a user cannot act on;
• gap: an install, usage, safety, compatibility, or extension fact needed to use the shipped product.

Every drift item cites its source of truth. Do not infer shipped behavior from a design plan or test name.

When the requested scope contains human-facing prose, read the affected passage as a complete proposition before editing it. Preserve its actor, behavior, conditions, timing, modality, negative guarantees, exceptions, ownership, failure behavior, and consequences. Classify the candidate as keep, add, trim, restore, restructure, or defer; a smaller word count is not evidence of a better contract.

2. Load only applicable constraints

Read references/documentation-checks.md. Use source code, Cargo metadata, behavior tests, and the normative spec as authority. Do not preserve narrative wording solely because an obsolete prose test once matched it.

For human-facing prose or agent-facing instructions, also read references/prose-contract.md. It owns semantic judgment, owner-first editing, current-state wording, and the exclusions for frozen or derivative material. Load it only for the targeted scope; a targeted scope never expands into an automatic repository-wide prose audit.

For agent-facing instructions, also apply the project-local contract: keep the repository as source of truth, expose completion criteria near the action, and remove duplicated or no-op instructions. For net-new Chinese prose, use baoyu-translate; edit existing Chinese mirrors surgically rather than regenerating whole files.

3. Edit in mirrored units

Update each English file and its *.zh.md counterpart together. Preserve identifiers, CLI flags, provider IDs, schema constants, file paths, and version numbers exactly. Translate explanations, not code vocabulary.

CLAUDE.md is a symlink to AGENTS.md: edit AGENTS.md only and never CLAUDE.md directly. A version bump changes documentation only after opi-release has changed the workspace version.

If docs/opi-spec.md changes, also update docs/opi-spec.zh.md and route the live .opi-impl-state.json hash through the guarded opi-implement plan/reinit flow. Never hand-edit the canonical ledger or rewrite phase snapshots.

4. Verify once

Run:

python scripts/opi-doc-check.py
git diff --check

The Python check validates current workspace/crate versions, source-derived wire-schema versions, EN/ZH counterpart presence for the root/spec and every Cargo package under crates/, project-local skill frontmatter, Codex sidecars, EN/ZH skill-index membership, local links, root-guidance lockstep, UTF-8, and selected stale-current-claim exclusions. It does not compile Rust.

Run extra verification only when the edited surface requires it:

• Rust API/rustdoc changed: cargo test -p <crate> --doc and RUSTDOCFLAGS="-D warnings" cargo doc -p <crate> --no-deps.
• Generated reference changed: run its generator/check mode.
• CLI output changed: run the owning focused CLI snapshot/subprocess test.
• Normative spec changed: run the live spec-ledger guard after guarded reconciliation.

Do not run the workspace test suite for a prose-only edit.

Boundaries

• No runtime source, manifest, version, commit, push, PR, or release mutation.
• No weakening behavior tests to accommodate documentation.
• No resurrection of phase-numbered prose guards.
• No full-file Chinese regeneration.
• No claim that a mechanical prose or documentation check proves semantic quality.
• Report exact checks run and any platform/runtime evidence not exercised.