ai-spector 0.9.21 → 0.9.24

package/contracts/bootstrap/docs/guides/COMMENTS_ENTITY_MIGRATION.md

@@ -0,0 +1,195 @@
+# Comment storage — legacy path → entity ID migration
+
+> **Audience:** Teams with comment threads under path-keyed folders who want stable **entityId** / **screenId** storage.  
+> **Full registry migration:** [ENTITY_REGISTRY_MIGRATION.md](../ENTITY_REGISTRY_MIGRATION.md) (comments are step 2b in that runbook).
+
+---
+
+## Layout comparison
+
+### Legacy (path-keyed)
+
+Threads are stored by **logical document path** (no `docs/` prefix, `.md` stripped):
+
+```text
+.docops/comments/
+├── srs/01-overview/
+│   └── {thread_id}/
+│       ├── meta_data.json
+│       ├── events.jsonl
+│       └── {comment_id}
+└── prototype/
+    └── src/login.html/
+        └── {thread_id}/
+            └── …
+```
+
+`meta_data.json` uses `filePath` as the primary key. Renaming or moving a doc in git breaks the folder path unless you manually move threads.
+
+### Entity registry (recommended)
+
+Threads are stored by **stable IDs** from `.docops/registry/`:
+
+```text
+.docops/comments/
+├── documents/
+│   └── {entityId}/          # UUID from registry/documents/{entityId}.json
+│       └── {thread_id}/
+│           └── …
+└── screens/
+    └── {screenId}/          # from registry/screens/{screenId}.json
+        └── {thread_id}/
+            └── …
+```
+
+After migration, `meta_data.json` includes:
+
+| Field | Purpose |
+|-------|---------|
+| `targetId` | `entityId` (documents) or `screenId` (prototype) |
+| `commentType` | `"document"` or `"prototype"` |
+| `filePath` | Human-readable path label (anchor + display; not the storage key) |
+
+Renaming `docs/srs/01-overview.md` only updates registry JSON — comment threads stay under the same `entityId`.
+
+---
+
+## Prerequisites
+
+| Check | Command / path |
+|-------|----------------|
+| Docops contract | `.docops/docops.config.json` with `capabilities.comments: true` |
+| Registry path | `"paths": { "registry": ".docops/registry", "comments": ".docops/comments" }` |
+| Design docs indexed | `docs/` contains SRS/BD/DD markdown |
+| Registry populated | `npx ai-spector docops registry sync` (creates `registry/documents/*.json`) |
+
+If `registry/documents/` is empty, **comments migrate will skip every thread** with a warning.
+
+---
+
+## Migration steps
+
+Run on **each git branch** that should use entity-keyed comment folders (e.g. `main`, active release branches).
+
+### 1. Preview
+
+```bash
+npx ai-spector docops registry sync --dry-run
+npx ai-spector docops comments migrate --dry-run
+```
+
+Review output:
+
+- **registry sync** — which document entities will be created/updated
+- **comments migrate** — lines like `move srs/01-overview/{threadId} → documents/{entityId}/{threadId}`
+
+### 2. Apply registry sync first
+
+```bash
+npx ai-spector docops registry sync
+```
+
+This must run **before** comment migration so each legacy `filePath` resolves to an `entityId`.
+
+### 3. Migrate comment folders
+
+```bash
+npx ai-spector docops comments migrate
+```
+
+For each legacy thread:
+
+1. Resolves `entityId` (documents) or `screenId` (prototype) from registry + `meta_data.json`
+2. Copies thread folder to `comments/documents/{entityId}/` or `comments/screens/{screenId}/`
+3. Updates `meta_data.json` with `targetId` and `commentType`
+4. Removes the legacy folder
+
+Safe to re-run: already-migrated threads (under `documents/` or `screens/`) are skipped.
+
+### 4. Verify
+
+```bash
+# List by entity (preferred)
+npx ai-spector comments list --entity <entityId> --json
+
+# Prototype
+npx ai-spector comments list --screen-id <screenId> --type prototype --json
+
+# Legacy path still works as a filter during deprecation window
+npx ai-spector comments list --file srs/01-overview --json
+```
+
+Confirm in git:
+
+```bash
+ls .docops/comments/documents/
+test ! -d .docops/comments/srs || echo "WARN: legacy srs/ comment tree still present"
+```
+
+### 5. Commit
+
+```bash
+git add .docops/registry .docops/comments
+git commit -m "chore: migrate comment threads to entityId layout"
+```
+
+---
+
+## One-shot script
+
+From repo root (after `.docops/guide/scripts/` is scaffolded):
+
+```bash
+bash .docops/guide/scripts/migrate-entity-registry.sh --dry-run
+bash .docops/guide/scripts/migrate-entity-registry.sh
+```
+
+Or skip non-comment steps:
+
+```bash
+bash .docops/guide/scripts/migrate-entity-registry.sh --skip-review
+```
+
+---
+
+## CLI after migration
+
+| Action | Legacy filter | Preferred filter |
+|--------|---------------|------------------|
+| List | `--file srs/01-overview` | `--entity <uuid>` |
+| Show | `--file …` | `--entity …` |
+| Create | `--file srs/01-overview` | `--entity <uuid>` |
+| Reply | `--file …` | `--entity …` |
+| Resolve | `--file …` | `--entity …` |
+
+Create/reply resolve storage location via registry: when `entityId` is known, threads are written under `comments/documents/{entityId}/` automatically.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `comments migrate` skips all threads | Registry empty or path mismatch | Run `registry sync`; check `logicalPath` in `registry/documents/*.json` matches thread `filePath` |
+| Warning: `No registry target for thread …` | Doc not in registry (wrong path, missing file) | Add/fix markdown under `docs/`; re-run `registry sync` |
+| Destination exists, thread skipped | Duplicate thread id under target | Inspect both folders; merge manually or remove duplicate |
+| Comments visible in CLI but not Writer | Writer `storage_layout` still `legacy` | Project Settings → Docops → `storage_layout: docops` |
+| Thread not found on reply with `--file` | Entity-layout storage (`documents/{entityId}/`) | Use `comments reply <threadId> --body "..."` only, or `--entity <targetId>` from show/list |
+
+---
+
+## Rollback (before push)
+
+```bash
+git checkout -- .docops/comments .docops/registry
+```
+
+Keep a backup branch before migrating production release branches.
+
+---
+
+## Related
+
+- [ENTITY_REGISTRY_MIGRATION.md](../ENTITY_REGISTRY_MIGRATION.md) — full registry + review queue migration
+- [modules/comments.md](../modules/comments.md) — comment module overview and CLI create/reply
+- [MIGRATION.md](../MIGRATION.md) — legacy repo-root → `.docops/` contract paths

package/contracts/bootstrap/docs/guides/DOCOPS_MANUAL_FALLBACK.md

@@ -0,0 +1,177 @@
+# Docops manual fallback — for agents
+
+Use this guide when **`npx ai-spector docops init`**, **`docops migrate`**, or **`docops migrate --repair`** fails (or is unavailable) and the user approves a **bounded workaround** (cli-failures option **2 Workaround** — pause, report, manual gap-fill, verify).
+
+**First:** run **`npx ai-spector docops guide --prompt`** — it prints **wrong vs correct** for this repo, a tailored `docops.config.json` example, expected document paths, scaffold checklist, and **bundled bootstrap paths** inside the installed ai-spector package.
+
+**Goal:** finish the same work the CLI would do — patch `.docops/docops.config.json`, fill missing scaffold files, copy templates — **without overwriting** anything that already exists.
+
+**Related:** [MIGRATION.md](../MIGRATION.md) · [examples/full-docops.config.json](../../../examples/full-docops.config.json)
+
+---
+
+## When to use
+
+| Situation | Action |
+|-----------|--------|
+| `command not found` | `npm install ai-spector` then use `npx ai-spector` |
+| `docops bootstrap bundle not found` | Reinstall ai-spector — bundle ships at `node_modules/ai-spector/contracts/bootstrap` |
+| `migrate --repair` exits non-zero mid-run | Fix reported path, then **resume manual steps** for remaining gaps only |
+| Writer **Set up repository** returns 409 (config exists) | Manual gap-fill (this guide), not full init |
+
+## Hard rules (same as MIGRATION)
+
+| Rule | Detail |
+|------|--------|
+| **Do not overwrite** | Skip any destination file that already exists |
+| **Repo-root-relative `path`** | `docs/srs`, `docs/basic-design`, `docs/detail-design`, `docs/other` — not bare `srs` |
+| **Optional layers default off** | `detailDesign` and `otherDocument` must appear in config with `"enabled": false` unless the project already enables them |
+| **DD templates always scaffold** | Copy `.docops/templates/detail-design/*.md` even when `detailDesign.enabled` is `false` |
+
+---
+
+## 1. Locate the bootstrap bundle (bundled in ai-spector CLI)
+
+The ai-spector npm package is **standalone** — it ships everything under:
+
+```text
+node_modules/ai-spector/contracts/bootstrap/     # templates, config stubs, docs
+node_modules/ai-spector/contracts/schemas/         # JSON schemas
+node_modules/ai-spector/contracts/examples/        # reference configs
+```
+
+`npx ai-spector docops guide --json` prints resolved `targetState.examples.bundle.bootstrapRoot` and `bootstrapCopyMap` for your install.
+
+Optional override (rare):
+
+```bash
+export DOCOPS_BOOTSTRAP_ROOT=/path/to/custom/bootstrap
+```
+
+---
+
+## 2. Patch `.docops/docops.config.json`
+
+Read the existing file. **Merge** missing keys only — do not change `enabled` or `path` on layers the project already configured.
+
+Prefer the **example from `docops guide --prompt`** for this repo. Reference shape: [examples/full-docops.config.json](../../../examples/full-docops.config.json).
+
+### Required optional doc types (if missing)
+
+Add both blocks when absent:
+
+```json
+"detailDesign": {
+  "enabled": false,
+  "path": "docs/detail-design",
+  "label": "Detail Design",
+  "templatesPath": ".docops/templates/detail-design"
+},
+"otherDocument": {
+  "enabled": false,
+  "path": "docs/other",
+  "label": "Other Document"
+}
+```
+
+`otherDocument` has **no** `templatesPath` (no cloud generation).
+
+### Path sanity
+
+| Key | Default `path` |
+|-----|----------------|
+| `srs` | `docs/srs` |
+| `basicDesign` | `docs/basic-design` |
+| `detailDesign` | `docs/detail-design` |
+| `otherDocument` | `docs/other` |
+
+If `docs/other/` or `docs/detail-design/` already exists on disk, keep `enabled: false` in config unless the user explicitly asks to enable the layer.
+
+---
+
+## 3. Copy scaffold files (gap-fill only)
+
+Let `BUNDLE` = bootstrap root from §1 (or `docops guide --json` → `bundle.bootstrapRoot`). For each row: **copy only if destination does not exist**.
+
+| Source (`BUNDLE/…`) | Destination |
+|---------------------|-------------|
+| `docs/**` | `.docops/guide/**` (prefix: replace `docs/` with `.docops/guide/`) |
+| `../schemas/**` | `.docops/guide/schemas/**` |
+| `../examples/**` | `.docops/guide/examples/**` |
+| `config/review.config.json` | `.docops/review.config.json` |
+| `config/review-queue-registry.json` | `.docops/review-queue/registry.json` |
+| `config/review-queue-pending.json` | `.docops/review-queue/pending.json` |
+| `config/prototype.config.json` | `.docops/prototype/config.json` |
+| `config/prototype-screen-map.json` | `.docops/prototype/screen-map.json` |
+
+Create empty dirs when needed: `.docops/comments/`, `.docops/registry/`, `.docops/prototype/`.
+
+---
+
+## 4. Copy templates
+
+| Source | Destination | When |
+|--------|-------------|------|
+| `templates/srs/**` | `.docops/templates/srs/` | Layer enabled **and** dest has no `*.md` |
+| `templates/basic-design/**` | `.docops/templates/basic-design/` | Layer enabled **and** dest has no `*.md` |
+| `templates/detail-design/**` | `.docops/templates/detail-design/` | **Always** if dest has no `*.md` (even when `detailDesign.enabled` is `false`) |
+
+Example (from repo root; `BUNDLE` from `docops guide --json`):
+
+```bash
+BUNDLE="$(node -e "const r=require('child_process').execSync('npx ai-spector docops guide --json',{encoding:'utf8'}); console.log(JSON.parse(r).targetState.examples.bundle.bootstrapRoot)")"
+DEST=.docops/templates/detail-design
+test -d "$DEST" && [ "$(find "$DEST" -name '*.md' | wc -l)" -eq 0 ] \
+  && mkdir -p "$DEST" && cp -R "$BUNDLE/templates/detail-design/." "$DEST/"
+```
+
+Do **not** copy templates for `otherDocument`.
+
+---
+
+## 5. Language placeholders (optional)
+
+For each **enabled** `docTypes` layer and each `languages[].path`:
+
+```text
+{docTypes.<key>.path}/{lang}/.gitkeep
+```
+
+Example: `docs/srs/en/.gitkeep`. Skip disabled layers (`detailDesign`, `otherDocument` when `enabled: false`).
+
+---
+
+## 6. Verify and report
+
+1. JSON-parse `.docops/docops.config.json`
+2. Confirm `detailDesign` + `otherDocument` keys exist
+3. Confirm `.docops/templates/detail-design/` has at least one `*.md`
+4. Re-run CLI when available: `npx ai-spector docops status --json` → `writerReady: true`, no blocking gaps
+5. Or walk [MIGRATION.md §5 checklist](../MIGRATION.md#5-post-migration-checklist)
+
+Tell the user which files were **written** vs **skipped (already existed)**.
+
+---
+
+## 7. Writer project settings (remind user)
+
+After git commit + push:
+
+- Set **storage layout** to `docops` when `.docops/` paths are live on the working branch
+- Enable **Detail Design** / **Other Documents** tabs in Project Settings only when the team wants those layers (separate from `docTypes.enabled`)
+
+---
+
+## Agent quick checklist
+
+```text
+[ ] npx ai-spector docops guide --prompt (wrong vs correct + example config)
+[ ] Read existing .docops/docops.config.json
+[ ] Merge detailDesign + otherDocument (enabled: false) if missing
+[ ] Copy BUNDLE → .docops/guide/, review/prototype stubs (skip existing)
+[ ] Copy detail-design templates if .docops/templates/detail-design/ empty
+[ ] Copy srs/basic-design templates only if layer enabled and dest empty
+[ ] gitkeep for enabled layers × languages
+[ ] Verify JSON + template counts; report written/skipped paths
+[ ] Retry npx ai-spector docops status when CLI works again
+```

package/contracts/bootstrap/docs/guides/PROJECT_LAYOUT.md

@@ -0,0 +1,84 @@
+# Project layout — configure paths (self-service)
+
+This guide helps you **point Writer at your existing docs** without automated file moves.
+
+**Related:** [MIGRATION.md](../MIGRATION.md) (contract migration) · run `npx ai-spector docops layout --prompt`
+
+---
+
+## Principles
+
+1. **Do not move markdown unless you choose to** — set `docTypes.*.path` in `.docops/docops.config.json` to folders that already contain your files.
+2. **Repo-root-relative paths** — use `docs/srs`, not `srs`.
+3. **Languages** — recommended layout is per-language subfolders: `docs/srs/en/…`, `docs/srs/vi/…`. Flat layouts (`docs/srs/1-intro.md`) work if you set `primaryLanguage` and accept single-language generation.
+4. **Templates** — customize files under `.docops/templates/{srs,basic-design,detail-design}/`; repair copies builtins only when folders are empty.
+
+---
+
+## Recommended folder map
+
+| Layer | Config key | Typical path | Notes |
+|-------|------------|--------------|-------|
+| SRS | `docTypes.srs` | `docs/srs` | Per-lang: `docs/srs/{en,vi,jp}/` |
+| Basic design | `docTypes.basicDesign` | `docs/basic-design` | Same pattern |
+| Detail design | `docTypes.detailDesign` | `docs/detail-design` | Often `enabled: false` until needed |
+| Other | `docTypes.otherDocument` | `docs/other` | Optional catch-all, usually disabled |
+| Data source | (convention) | `docs/data-source/` | Context for agents, not a docType |
+
+**Legacy aliases** (point config here if your repo uses them):
+
+- `docs/dd/`, `docs/detail_design/` → set `detailDesign.path` accordingly
+- `docs/bd/` → set `basicDesign.path` to `docs/bd`
+
+---
+
+## Workflow
+
+```bash
+# 1. See disk vs config (read-only)
+npx ai-spector docops layout --prompt
+
+# 1b. CLI migrate/repair failed — agent fallback
+npx ai-spector docops guide --prompt
+
+# 2. Edit .docops/docops.config.json (paths, languages, templatesPath)
+
+# 3. Fill contract gaps
+npx ai-spector docops migrate --repair
+
+# 4. Index + registry
+npx ai-spector index
+npx ai-spector docops registry sync
+
+# 5. Verify
+npx ai-spector docops check --prompt
+```
+
+---
+
+## Common patterns
+
+### Already on `docs/srs/en/` (canonical)
+
+Set paths to defaults; run `docops migrate --repair` for optional layers (`detailDesign`, `otherDocument`).
+
+### Flat SRS (`docs/srs/*.md`)
+
+Either:
+
+- **A (preferred):** Keep files in place, set `primaryLanguage: "en"` (or your lang), flat is OK for single-language projects.
+- **B:** Manually move to `docs/srs/en/` when you want multi-language folders.
+
+### Docs live outside `docs/`
+
+Set `docTypes.srs.path` (and others) to the real folder, e.g. `specs/srs` or `documentation/requirements`.
+
+### Custom template packs
+
+Copy/edit templates under `.docops/templates/…` before generate. For wholly custom packs, use **template-import** workflow first.
+
+---
+
+## Writer UI
+
+After git push, set **Project Settings → storage layout** to `docops` when `.docops/docops.config.json` is on your branch. See MIGRATION.md §2.1.

package/contracts/bootstrap/docs/modules/comments.md

@@ -0,0 +1,77 @@
+# Comments — Docops Module Guide
+
+## Native config (Writer)
+
+Enable with `capabilities.comments: true` in `.docops/docops.config.json`.
+
+Comments live under `paths.comments` (default `.docops/comments/`).
+
+### Entity registry layout (recommended)
+
+```text
+.docops/comments/documents/{entityId}/{thread_id}/
+├── meta_data.json
+├── events.jsonl
+└── {comment_id}          # one JSON file per comment
+
+.docops/comments/screens/{screenId}/{thread_id}/
+└── …                     # prototype threads
+```
+
+`entityId` / `screenId` come from `.docops/registry/`. Threads survive document renames.
+
+### Legacy layout (deprecated)
+
+```text
+.docops/comments/{logical_path}/{thread_id}/
+├── meta_data.json
+├── events.jsonl
+└── {comment_id}
+```
+
+`logical_path` matches the document path without `docs/` prefix (e.g. `srs/en/1-introduction`).
+
+**Migrate to entity layout:** [guides/COMMENTS_ENTITY_MIGRATION.md](../guides/COMMENTS_ENTITY_MIGRATION.md)
+
+Schema: `kari-writer/contracts/schemas/comments/`. Example: `contracts/examples/minimal-comment-thread/`.
+
+`meta_data.json` carries `version` for optimistic concurrency. Writer increments version on each write.
+
+## Local CLI (AI Spector)
+
+```bash
+# List / triage
+npx ai-spector comments inbox --json
+npx ai-spector comments list --entity <uuid> --json
+
+# Create and reply (document comments)
+npx ai-spector comments create --file srs/01-overview --body "Please clarify" --start-line 12 --end-line 14
+npx ai-spector comments create --entity <uuid> --body "Please clarify" --start-line 12 --end-line 14
+npx ai-spector comments reply <threadId> --body "Updated in next revision"
+npx ai-spector comments reply <threadId> --entity <uuid> --body "Updated in next revision"
+
+# Resolve
+npx ai-spector comments resolve <threadId> --entity <uuid>
+```
+
+**Reply scope:** `threadId` alone is enough when the thread is unique under `.docops/comments/`. For entity-layout storage (`comments/documents/{entityId}/`), `--file` resolves to the legacy path and may fail — prefer `threadId` only, or pass `--entity <targetId>` from `comments show` / `comments list` (`targetId` field).
+
+**MCP:** `contract_comments({ action: "create" | "reply" | "list" | "inbox" | "show" | "resolve", ... })`
+
+| Action | Required fields | Notes |
+|--------|-----------------|-------|
+| `reply` | `threadId`, `body` | Pass `entityId` from show/list when scope is ambiguous |
+| `create` | `body`, plus `entityId` or `filePath` | Document anchor: `startLine` / `endLine` |
+| `show` | `threadId` | Optional `entityId` / `filePath`; returns `targetId` for reply |
+
+## Custom adapter
+
+A CI bot or local tool may create comment threads by:
+
+1. Creating the thread folder with valid `meta_data.json` and at least one comment file
+2. Appending events to `events.jsonl` for audit trail
+3. Re-reading `meta_data.json` before updates; retry on version mismatch
+
+Prefer writing under `comments/documents/{entityId}/` when the registry is available.
+
+Set `capabilities.comments: false` when comments are managed entirely outside Writer.

package/contracts/bootstrap/docs/modules/generate.md

@@ -0,0 +1,25 @@
+# Generate — Docops Module Guide
+
+## Native config (Writer)
+
+Enable with `capabilities.generate: true` and a non-empty `templatesPath` per enabled doc layer.
+
+| Config | Purpose |
+|--------|---------|
+| `docTypes.<layer>.templatesPath` | Folder of `*.md` template files (e.g. `.docops/templates/srs`) |
+| `docTypes.<layer>.enabled` | Layer must be `true` for generation |
+| `capabilities.generate` | Master switch for cloud generation UI |
+
+Generated **output** lives under `docs/{layer}/{lang}/` — separate from templates.
+
+Writer lists templates from git; cloud generation runs when templates exist and capability is on.
+
+## Custom adapter
+
+ai-spector or a custom script may own generation:
+
+1. Copy or author templates into `templatesPath`
+2. Write generated markdown to `docs/{layer}/{lang}/`
+3. Commit both template and output to git
+
+To use only your pipeline (hide Writer cloud generation), set `capabilities.generate: false`. Templates may still exist for local tooling.

package/contracts/bootstrap/docs/modules/graph.md

@@ -0,0 +1,31 @@
+# Graph — Docops Module Guide
+
+## Native config (Writer)
+
+Enable with `capabilities.graph: true` in `.docops/docops.config.json`.
+
+Writer reads `.docops/adapters/graph.json` when present:
+
+```json
+{
+  "schemaVersion": "1.0",
+  "artifacts": {
+    "nodes": ".ai-spector/graph/nodes.json",
+    "edges": ".ai-spector/graph/edges.json"
+  }
+}
+```
+
+Paths in `artifacts` are repo-relative. Writer does not compute the graph — it displays pre-built artifacts.
+
+If `graph` is `true` but adapter file or artifacts are missing, Writer hides the graph UI and logs a warning.
+
+## Custom adapter
+
+ai-spector graph plugin or a custom tool:
+
+1. Writes `nodes.json` / `edges.json` (or paths declared in adapter config)
+2. Updates `.docops/adapters/graph.json` to point at artifacts
+3. Sets `capabilities.graph: true`
+
+Set `capabilities.graph: false` when traceability graph is not used.

package/contracts/bootstrap/docs/modules/prototype.md

@@ -0,0 +1,26 @@
+# Prototype — Docops Module Guide
+
+## Native config (Writer)
+
+Enable with `capabilities.prototype: true` in `.docops/docops.config.json`.
+
+| File | Purpose |
+|------|---------|
+| `.docops/prototype/screen-map.json` | Maps screens ↔ docs ↔ prototype URLs |
+| `.docops/prototype/config.json` | Deploy/review settings (no HTML source) |
+
+Prototype **HTML/SPA source** lives at repo root `prototype/` — optional and not part of the docops schema.
+
+Schema: `kari-writer/contracts/schemas/prototype/`. Example: `contracts/examples/minimal-screen-map.json`.
+
+Writer reads `screen-map.json` to link design docs to prototype previews. Missing screen-map hides prototype features without error.
+
+## Custom adapter
+
+A deploy pipeline may update `screen-map.json` when screens change:
+
+1. Preserve `schemaVersion` and existing screen IDs where possible
+2. Set `reviewUrl` after deploy completes
+3. Commit to the same branch users review in Writer
+
+Set `capabilities.prototype: false` when prototype mapping is not used.

package/contracts/bootstrap/docs/modules/review.md

@@ -0,0 +1,25 @@
+# Review — Docops Module Guide
+
+## Native config (Writer)
+
+Enable with `capabilities.review: true` in `.docops/docops.config.json`.
+
+| File | Purpose |
+|------|---------|
+| `.docops/review.config.json` | Sign-off preset (`extends: kaopiz-default`) |
+| `.docops/review-queue/registry.json` | Per-document review state (v3) |
+| `.docops/review-queue/pending.json` | Pending queue array |
+
+Schema: `kari-writer/contracts/schemas/review/`. Example: `contracts/examples/review/minimal-registry.json`.
+
+Writer web UI writes `overallStatus`, track `votes[]`, closure fields. **Do not** write `contentHash` or `docPath` — pipeline-owned.
+
+## Custom adapter
+
+An external sign-off tool may update `registry.json` if it:
+
+1. Re-reads the file (and git SHA when available) before write
+2. Retries on conflict
+3. Leaves `contentHash` / `docPath` unchanged
+
+Set `capabilities.review: false` to hide Writer review UI when your adapter owns the workflow entirely.

package/contracts/bootstrap/docs/modules/translate.md

@@ -0,0 +1,26 @@
+# Translate — Docops Module Guide
+
+## Native config (Writer)
+
+Enable with `capabilities.translate: true` in `.docops/docops.config.json`.
+
+| Field | Purpose |
+|-------|---------|
+| `languages[]` | All supported language codes and folder paths |
+| `primaryLanguage` | Authoring language (e.g. `en`) |
+| `internalLanguage` | Language for internal review (e.g. `vi`) |
+| `clientLanguage` | Language for client-facing release (e.g. `jp`) |
+
+Translated documents live at `docs/{layer}/{language.path}/*.md` for each entry in `languages`.
+
+Writer shows translation workflow UI when `translate` is enabled. Missing target-language files are not errors.
+
+## Custom adapter
+
+A local translate workflow (ai-spector, CI, or agent) may:
+
+1. Read source docs from `primaryLanguage` path
+2. Write translations to other `languages[].path` folders
+3. Commit per language on the same branch
+
+Set `capabilities.translate: false` when translation is handled entirely outside Writer.