okstra 0.179.2 → 0.183.2

package/docs/container.md

@@ -21,14 +21,14 @@
 ## Command format
 
 ```
-okstra container <up|status|logs|stop-watcher|down> --project-root <PATH> --task-key <KEY> [options]
+okstra container <up|status|logs|stop-watcher|down> --project-root <PATH> --task-key <KEY> [--text] [options]
 ```
 
 | sub-command | Behavior | Additional options |
 |---|---|---|
 | `up` | Verify stage integration → validate `docker-compose.yml` → compose env override → `docker compose -p <project> up -d` → poll health checks → start a tail/watcher pane for each container | — |
 | `status` | Show the live container group status by querying Docker labels | — |
-| `logs` | Report `watchersDir` and registered watcher entries as JSON; it does not stream Docker container logs | `--service <NAME>` (filters watcher metadata; all registered watchers when omitted) |
+| `logs` | Report the watcher directory and registered watcher entries; it does not stream Docker container logs | `--service <NAME>` (filters watcher metadata; all registered watchers when omitted) |
 | `stop-watcher` | Stop the watcher panes for the task (containers remain running) | — |
 | `down` | Tear down the container group and stop attached watchers | `--all` |
 
@@ -45,6 +45,8 @@ Identifier of the task to deploy, in the form `<project-id>:<task-group>:<task-i
 
 The actual `logs` output from `logs_container_group()` contains `watchersDir` and registered watcher entries in `watchers`. It does not run `docker compose logs` and does not stream Docker container logs. Inspect each watcher's `findings_path` and the files beneath `watchersDir` for monitoring results.
 
+`--text` emits command-specific fixed labels for model-facing skills. Without it, the command preserves the full machine JSON bytes and exit codes.
+
 ### `--all` (`down` only)
 Clean up **all** task container groups and watchers within the current project root's `.okstra/` scope. The boundary is limited to the `<project-root>/.okstra/` prefix, so panes belonging to **other projects** in concurrent sessions are never touched. Without `--all`, a single `down` cleans up exactly the panes for the specified task.
 
@@ -99,13 +101,13 @@ container/
 
 ## Exit behavior/output
 
-Each sub-command writes its result to stdout as JSON and returns exit code 0. Validation failures (missing configuration files, merge conflicts, health check timeouts, and so on) terminate abnormally with a `PrepareError` that identifies what went wrong.
+Each sub-command returns exit code 0 on success. `--text` writes its command-specific fixed labels for model callers; the default writes the full machine JSON contract. Validation failures (missing configuration files, merge conflicts, health check timeouts, and so on) terminate abnormally with a `PrepareError` that identifies what went wrong.
 
 ## Usage examples
 
 ```bash
 # Deploy and start monitoring
-okstra container up --project-root /path/to/proj --task-key proj:auth:login-fix
+okstra container up --project-root /path/to/proj --task-key proj:auth:login-fix --text
 
 # Status
 okstra container status --project-root /path/to/proj --task-key proj:auth:login-fix

package/docs/contributor-change-matrix.md

@@ -11,6 +11,6 @@ Use this matrix before changing high-risk repo contracts. Update the source file
 | Add phase | `scripts/okstra_ctl/workflow.py`, `prompts/profiles/`, `validators/`, `tests/` | workflow and validation contract tests |
 | Change worker roster | `prompts/profiles/*.md`, `scripts/okstra_ctl/workers.py`, `tests/contract/test_repo_contracts.py` | worker roster contract tests |
 | Change report section | `schemas/final-report-v2.0.schema.json`, `templates/reports/final-report-v2.template.md`, `scripts/okstra_ctl/render_final_report.py`, `validators/validate-run.py` | final-report schema, renderer, and validator tests |
-| Maintain Korean review mirrors | `config/korean-sources.json`, `tools/korean-sources/` (`lifecycle.mjs` plus its `lifecycle-*.mjs` support modules, CLI/hooks adapters, and shared workflow), `.agents/skills/sync-korean-sources/`, `.claude/skills/sync-korean-sources/` | `tests-js/korean-sources-*.test.mjs` (`lifecycle`, `cli`, `hooks`, and `skill`) |
+| Maintain Korean review mirrors | `config/korean-sources.json`, `tools/korean-sources/` (`cli.mjs`, `baseline.mjs`, `config.mjs`, `markdown.mjs`, and the shared workflow), `.agents/skills/sync-korean-sources/`, `.claude/skills/sync-korean-sources/` | `tests-js/korean-sources-*.test.mjs` (`cli`, `config`, `markdown`, and `skill`) |
 
 `runtime/` is build output. Never edit it directly; change source files and rebuild the runtime payload instead.

package/docs/for-ai/README.md

@@ -32,13 +32,13 @@ This directory is a compressed manual for an AI to quickly select and precisely
 
 ## Shared Execution Rules
 
-1. Run commands as separate Bash calls whenever the source skill requires it. In particular, do not wrap `okstra preflight --runtime claude-code --json`, `okstra wizard ...`, or `okstra container ...` calls in `&&`, `||`, `$(...)`, a leading variable assignment, `eval`, or `export`.
+1. Run commands as separate Bash calls whenever the source skill requires it. In particular, do not wrap `okstra preflight --runtime claude-code`, `okstra wizard ...`, or `okstra container ...` calls in `&&`, `||`, `$(...)`, a leading variable assignment, `eval`, or `export`.
 2. An `okstra <subcmd>` call bootstraps its own Python path. Unless a skill states otherwise, do not build `okstra paths --shell` or `export PYTHONPATH=...`.
 3. Most skills except `okstra-setup` do not use an `npx` fallback. If the runtime is missing, tell the user to run `/okstra-setup` and stop. But if it fails with `unknown command: <cmd>`, the `okstra` binary on PATH is older than the skill — point the user to `npm i -g okstra@latest` rather than `/okstra-setup`, and stop.
 4. Project artifacts go under `<PROJECT_ROOT>/.okstra/` by default. The exception is `okstra-memory`, which uses the global user memory `~/.okstra/memory-book/`.
 5. `runtime/` is build output. When fixing a source skill or template, edit the source under `skills/`, `templates/`, `validators/`, `scripts/`, `src/` and apply it via a build.
 6. Do not guess the contents of a tracker, URL, file, report, log, zip, template, or validator. Use only what you have confirmed by reading or running with a tool.
-7. Read-side skills also produce some artifacts. `okstra-inspect errors` produces an error report Markdown and `okstra-inspect error-zip` produces an anonymized zip. Even in these cases, keep the CLI stdout JSON as the source of truth.
+7. Read-side skills also produce some artifacts. `okstra-inspect errors` produces an error report Markdown and `okstra-inspect error-zip` produces an anonymized zip. Even in these cases, keep the purpose-specific fixed CLI fields as the source of truth.
 
 ## The Order the AI Reads In
 

package/docs/for-ai/skills/okstra-brief-gen.md

@@ -43,10 +43,12 @@ Output location:
 Run as a single call.
 
 ```bash
-okstra preflight --runtime claude-code --json
+okstra preflight --runtime claude-code
 ```
 
-If runtime or project setup is missing, guide the user to `/okstra-setup` and stop. This skill does not use an `npx` fallback.
+On `Okstra preflight: ready`, carry the fixed `Project root` line. On
+`Okstra preflight: failed`, show `Reason` and `Recovery`, then stop. This skill
+does not use an `npx` fallback.
 
 ## Input collection
 
@@ -107,7 +109,7 @@ Processing:
 
 ## task-group and filename
 
-For task-group, show existing-group recommendations first. Call `okstra task-list`, extract the distinct `taskGroup` values from `tasks[]` in most-recent order, and offer the 2 most recent + enter-directly. In tracker recursion, task-group must be obtained before building any child path.
+For task-group, show existing-group recommendations first. Call `okstra task-list --text`, read the distinct fixed `Task group` values in `Updated at` order, and offer the 2 most recent + enter-directly. If `Status` is `error`, report `Failure stage` and `Failure reason`, then stop. If `Task count` is `0`, ask for free text. In tracker recursion, task-group must be obtained before building any child path.
 
 File path rule:
 

package/docs/for-ai/skills/okstra-code-review.md

@@ -34,15 +34,15 @@ The branch-mode result path is the one deliberate exception to the `.okstra/`-on
 A single Bash call with the literal `okstra` token (not wrapped in `if` / `eval` / `export` / `$(...)` / `VAR=` / `||` / `&&` / `npx`):
 
 ```bash
-okstra preflight --runtime claude-code --json
+okstra preflight --runtime claude-code
 ```
 
-`ok:true` → carry `projectRoot` as a literal. `ok:false` → retry the intended directory with `--cwd <dir>`; if that also fails, point at `/okstra-setup` and stop. `unknown command: preflight` or `unknown command: code-review` means the `okstra` binary predates the skill — `npm i -g okstra@latest`, then stop.
+`Okstra preflight: ready` → carry `Project root` as a literal. `Okstra preflight: failed` → retry the intended directory with `--cwd <dir>`; if that also fails, show `Reason` and `Recovery`, then stop. `unknown command: preflight` or `unknown command: code-review` means the `okstra` binary predates the skill — `npm i -g okstra@latest`, then stop.
 
 ## Flow
 
-1. **Resolve the target.** Stage mode: `okstra resolve-task-key <token> --project-root <projectRoot> --json`, then `okstra stage-map <taskKey> --project <projectRoot> --json`, and pick the stage with a 3-option picker (recommendations first, `Enter directly` last). Branch mode: pick the branch the same way; a detached HEAD is refused.
-2. **Call the target CLI**: `okstra code-review target --task-key <k> --stage <N> --project-root <dir> --json`, or `okstra code-review target --branch <name> [--base <ref>] --project-root <dir> --json`. It returns `{ok, projectRoot, mode, worktreePath, branch, baseCommit, headCommit, reviewPath, round}` (stage mode adds `taskKey`, `taskRoot`, `stage`). **Never derive the base** — the CLI owns it, and `baseCommit` may be a ref rather than a commit id, so pass it through verbatim. Run git in `worktreePath` when non-empty, otherwise in `projectRoot` against `branch`.
+1. **Resolve the target.** A full `project-id:task-group:task-id` token is already the key. For a bare token, run `okstra model-io task-selection-input --project-root <projectRoot> --task-ref <token>` and use the fixed `Match count`, `Task`, and `Updated at` rows. Then run `okstra stage-map <taskKey> --project <projectRoot> --text` and pick from the fixed `Stages` and `Done stages` rows with a 3-option picker (recommendations first, `Enter directly` last). Branch mode picks the branch the same way; a detached HEAD is refused.
+2. **Call the target CLI**: `okstra code-review target --task-key <k> --stage <N> --project-root <dir> --text`, or `okstra code-review target --branch <name> [--base <ref>] --project-root <dir> --text`. Carry the returned `Project root`, `Mode`, `Worktree path`, `Branch`, `Base commit`, `Head commit`, `Review path`, and `Round` values; stage mode also carries `Task key`, `Task root`, and `Stage`. Then run `okstra model-io code-review-input --project-root <projectRoot> --base <baseCommit> --head <headCommit>` and pass only that fixed Markdown view to model prompts. **Never derive the base** — the CLI owns it, and `Base commit` may be a ref rather than a commit id, so pass it through verbatim. Run git in `Worktree path` when non-empty, otherwise in `Project root` against `Branch`.
 3. **Show the base and confirm it** with a 3-option picker before censusing anything — the returned `baseCommit` plus `git log -1 --oneline <baseCommit>` first, `Enter directly` last. Only an override calls the target CLI a second time, with `--base <ref>`.
 4. **Census the diff** per `census-rules.md`: four axes (`structural`, `semantic`, `state-and-tests`, `general`), one cell per target per axis — the axis **is** the rule group, never one cell per individual rule. Membership is mechanical; judgment only ever decides a verdict. Route the coding-preflight packs exactly once here (`okstra paths --field home` → `<okstraHome>/prompts/coding-preflight/overview.md`), and fix the calibration path the briefs carry (`~/.claude/skills/okstra-code-review/references/review-calibration.md`). Print every cell table, every exclusion with its reason, the applied packs, and both completion criteria. Never truncate a large census — report the cell count and confirm.
 5. **Materialize and dispatch four reviewers in parallel.** Each reviewer is a separate standalone invocation under `.okstra/agent-invocations/code-review/`. Write `<invocation-id>.instructions.md`, run `okstra agent-prompt materialize --purpose code-review --audience code-reviewer ...`, and verify the returned `metadataPath` before dispatch. A native host call receives the verified prompt body and `hostModelValue`; a deterministic provider process receives the prompt path and `modelExecutionValue` through `okstra worker-dispatch`. Each brief carries the diff, the work directory, its own axis's cell list verbatim, its packs' absolute paths, and the absolute calibration path.

package/docs/for-ai/skills/okstra-container-build.md

@@ -27,10 +27,13 @@
 Single call:
 
 ```bash
-okstra preflight --runtime claude-code --json
+okstra preflight --runtime claude-code
 ```
 
-If the project is not set up, point to `/okstra-setup` and stop. A Docker daemon is required. On a Docker connection error, tell the user to start Docker Desktop/daemon; do not start Docker yourself.
+On `Okstra preflight: ready`, carry the fixed `Project root` line. On
+`Okstra preflight: failed`, show `Reason` and `Recovery`, then stop. A Docker
+daemon is required. On a Docker connection error, tell the user to start Docker
+Desktop/daemon; do not start Docker yourself.
 
 ## task-key resolution
 
@@ -40,7 +43,7 @@ Most sub-commands need a full task-key.
 2. For a bare task-id, use the resolver:
 
 ```bash
-okstra resolve-task-key <task-id> --project-root <projectRoot> --json
+okstra model-io task-selection-input --project-root <projectRoot> --task-ref <task-id>
 ```
 
 3. On multiple matches, show the candidates and let the user pick.
@@ -63,7 +66,7 @@ If ambiguous, show the full facet list and offer an Enter directly option. When
 Run:
 
 ```bash
-okstra container up --project-root <projectRoot> --task-key <task-key>
+okstra container up --project-root <projectRoot> --task-key <task-key> --text
 ```
 
 Preconditions:
@@ -79,17 +82,17 @@ Handling failure messages:
 - `final-verification(whole-task): stage N not done`: tell the user to finish that stage via implementation.
 - healthcheck failure: relay the failing service and the `docker compose ... logs` line the CLI provides, verbatim.
 
-On success, parse the stdout JSON and summarize services, watcher pane, and published ports. Tell the user that management from here is via `okstra container status <task-key>` and `down <task-key>`. For *what to verify* once it is up, point to the implementation report's §5.7.9 Manual User Test (Draft) — those steps and expected results are the manual test script for this build.
+On success, read the fixed `Service` and `Watcher` rows, then run the `status --text` command below and read its numbered container `ports` fields. Tell the user that management from here is via `okstra container status <task-key>` and `down <task-key>`. For *what to verify* once it is up, point to the implementation report's §5.7.9 Manual User Test (Draft) — those steps and expected results are the manual test script for this build.
 
 ## status
 
 Run:
 
 ```bash
-okstra container status --project-root <projectRoot> --task-key <task-key>
+okstra container status --project-root <projectRoot> --task-key <task-key> --text
 ```
 
-stdout JSON:
+Fixed fields:
 
 - `projectName`: compose project name
 - `containers`: running containers found by run-trace label
@@ -102,52 +105,52 @@ The `containers` label query is authoritative for whether it is alive. The watch
 Run:
 
 ```bash
-okstra container logs --project-root <projectRoot> --task-key <task-key>
+okstra container logs --project-root <projectRoot> --task-key <task-key> --text
 ```
 
 service scope:
 
 ```bash
-okstra container logs --project-root <projectRoot> --task-key <task-key> --service <service>
+okstra container logs --project-root <projectRoot> --task-key <task-key> --service <service> --text
 ```
 
-Show the stdout JSON's `watchersDir` and `watchers`. The live stream is in the tmux watcher pane, not a file. If raw compose logs are needed, get `projectName` from `status`, then tell the user they can run `docker compose -p <projectName> logs -f <service>`.
+Show the fixed `Watchers dir` and numbered `Watchers` rows. The live stream is in the tmux watcher pane, not a file. If raw compose logs are needed, get `Project name` from `status`, then tell the user they can run `docker compose -p <projectName> logs -f <service>`.
 
 ## stop-watcher
 
 Run:
 
 ```bash
-okstra container stop-watcher --project-root <projectRoot> --task-key <task-key>
+okstra container stop-watcher --project-root <projectRoot> --task-key <task-key> --text
 ```
 
-Remove only the watcher/tail panes and keep the containers. Summarize the stdout JSON's `reapedPanes` and `note`. If the user actually intends to bring the containers down, route to `down`.
+Remove only the watcher/tail panes and keep the containers. Summarize the fixed `Reaped panes` and `Note` rows. If the user actually intends to bring the containers down, route to `down`.
 
 ## down
 
 Single task:
 
 ```bash
-okstra container down --project-root <projectRoot> --task-key <task-key>
+okstra container down --project-root <projectRoot> --task-key <task-key> --text
 ```
 
 Whole project:
 
 ```bash
-okstra container down --project-root <projectRoot> --all
+okstra container down --project-root <projectRoot> --all --text
 ```
 
 A single-task down is fine to run after resolving the task-key. `--all` takes down every okstra container group in the project, so confirm with the user before running it.
 
-Report the stdout JSON's `downed` and `orphanPanesReaped`. Show each `projectName` and the reaped panes.
+Report the fixed `Downed` and `Orphan panes reaped` rows. Show each project name and the reaped panes.
 
 ## Output rules
 
-- The stdout JSON is the source of truth.
+- The fixed text fields are the source of truth.
 - Do not second-guess it with raw `docker` commands. The only exception is when the CLI failed and the user asked for a manual fallback.
 - Show the resolved task-key in the heading or on the first line.
 - Show CLI failure messages verbatim, including the remediation line.
-- Show container/service state as the JSON values, without normalizing.
+- Show container/service state as the fixed values, without normalizing.
 
 ## Forbidden patterns
 

package/docs/for-ai/skills/okstra-inspect.md

@@ -40,10 +40,10 @@ No sub-command writes outside this machine.
 Run once before any sub-command.
 
 ```bash
-okstra preflight --runtime claude-code --json
+okstra preflight --runtime claude-code
 ```
 
-The project check only sees the cwd of the Bash call. For a project that is not the cwd (a sibling repo, a monorepo subdir, or a project named in the request), `ok:false` is a false negative, not a missing setup — do not stop immediately; retry with `okstra preflight --runtime claude-code --cwd <that-dir> --json` (`--cwd` is the sanctioned way to target a project without a leading `cd`). Only when that also returns `ok:false` do you guide the user to `/okstra-setup` and stop. Then use `projectRoot` as a literal value, and pass it to the sub-command CLIs that accept it (`recap`, `context-cost`, etc.) via `--cwd`/`--project-root <projectRoot>`.
+The project check only sees the cwd of the Bash call. For a project that is not the cwd (a sibling repo, a monorepo subdir, or a project named in the request), `Okstra preflight: failed` can be a false negative rather than missing setup. Retry with `okstra preflight --runtime claude-code --cwd <that-dir>` (`--cwd` is the sanctioned way to target a project without a leading `cd`). Only when that also reports `Okstra preflight: failed` do you show `Reason` and `Recovery`, then stop. On `Okstra preflight: ready`, carry `Project root` as a literal value and pass it to the sub-command CLIs that accept it (`recap`, `context-cost`, etc.) via `--cwd`/`--project-root <projectRoot>`.
 
 ## intent routing
 
@@ -62,10 +62,10 @@ Many facets accept the following target forms.
 A bare task-id uses the shared resolver.
 
 ```bash
-okstra resolve-task-key <task-id> --project-root <projectRoot> --json
+okstra model-io task-selection-input --project-root <projectRoot> --task-ref <task-id>
 ```
 
-Handling `matches[]`:
+Handling the fixed text projection's `Match count` and repeated task lines:
 
 - 0: say it cannot be found; do not guess.
 - 1: use that `taskKey`.
@@ -75,7 +75,7 @@ Handling `matches[]`:
 
 ### Project overview
 
-Read `.okstra/discovery/task-catalog.json`. Do not re-open individual manifests for the overview. The catalog is the projected source.
+Run `okstra model-io status-input --project-root <projectRoot>`. Its fixed text task blocks are the projected source.
 
 Sort: `updatedAt` desc, then `taskKey`.
 
@@ -91,7 +91,7 @@ Keep the table narrow.
 
 ### Specific task
 
-For a single task's detail, check the catalog first, then if needed read `.okstra/tasks/<group>/<id>/task-manifest.json`, `history/timeline.json`, and the latest run manifest.
+For a single task's detail, run `okstra model-io status-input --project-root <projectRoot> --task-ref <task-key>` and use its named lines.
 
 Information to show:
 
@@ -117,7 +117,7 @@ Allowed values:
 - `blocked`
 - `done`
 
-Procedure: update via a single `okstra set-work-status <token> <status> [--note <text>] --project-root <projectRoot> --json` call — do not edit the manifest by hand. On `stage:"ambiguous"`, re-ask with `matches[]`; on `stage:"not-found"`, answer that it cannot be found.
+Procedure: update via a single `okstra set-work-status <token> <status> [--note <text>] --project-root <projectRoot> --text` call — do not edit the manifest by hand. On `Stage: ambiguous`, re-ask with the listed `Match` values; on `Stage: not-found`, answer that it cannot be found.
 
 When `workStatus` is absent in a read display, infer it from the lifecycle state, but do not back-fill on read alone.
 
@@ -128,20 +128,15 @@ First branch: distinguish re-run from resume.
 - Re-run: create a new run from previous run parameters. A new run-seq is created.
 - Resume: continue an interrupted existing run. No new run-seq is created.
 
-If the catalog is absent, fall back to the `.okstra/tasks/*/*/task-manifest.json` glob. The disk manifest is the source of truth.
+Run `okstra model-io history-input --project-root <projectRoot>` for project history, or add `--task-ref <task-key>` for one task.
 
-Re-run extracts `projectId`, `taskGroup`, `taskId`, `taskType`, `taskBriefPath`, workers, relatedTasks, model overrides, and so on from the source run-manifest to assemble the command. `implementation`'s `--base-ref` is not in the run-manifest but in the worktree registry, so ask for it as the situation requires.
+Re-run obtains `projectId`, `taskGroup`, `taskId`, `taskType`, `taskBriefPath`, workers, related tasks, model overrides, and executor provider through `okstra model-io rerun-input --run-manifest <runManifestPath>`. Omit `implementation`'s `--base-ref` to reuse a registration; if launch reports that a base is required, ask the user.
 
 Resume checks `latestResumeCommandPath` or the timeline entry's `resumeCommandPath`, and if the file exists, guides/runs `bash <resume-command-path>`. If the path is empty or the file is missing, declare "no resume" and guide to history.3 (re-run).
 
 ## report
 
-report path resolution priority:
-
-1. `latestReportRecordPath` in `.okstra/discovery/task-catalog.json`
-2. `latestReportRecordPath` in the direct `task-manifest.json`
-3. a specific run's `reportPath` in `history/timeline.json`
-4. specific task-type fallback: `runs/<task-type>/reports/final-report-*.data.json`, including stage-isolated paths. Render a full reading copy on demand with `okstra render-final-report <that data.json>`.
+Run `okstra model-io report-input --project-root <projectRoot> --task-ref <task-key>` for the latest report. For a specific run, use the `Report` line from `okstra model-io history-input --project-root <projectRoot> --task-ref <task-key>`. Render a full reading copy on demand with `okstra render-final-report <that data.json>`.
 
 Match read depth to the request (a final report is 300+ lines / 50K+ tokens). For summary/conclusion/pass questions ("summary", "just the key points", "conclusion", "did it pass?"), do not read the whole thing — read only the verdict in the `runs/<task-type-segment>/status/final-<task-type-segment>-<NNN>.status` (stage-isolated: `runs/<task-type-segment>/stage-<N>/status/`) sidecar plus the report's leading summary block. Ingest the whole file only for "the whole thing / read it all / full body". If a completion signal exists but the file does not, report it as a missing report; if it is not yet complete, show the current status and workStatus.
 
@@ -150,7 +145,7 @@ Match read depth to the request (a final report is 300+ lines / 50K+ tokens). Fo
 The CLI does the time computation. The AI does not recompute duration by hand.
 
 ```bash
-okstra time-report <task-key> --project-root <projectRoot> --json
+okstra time-report <task-key> --project-root <projectRoot> --text
 ```
 
 Convert every `*Ms` to `HH:MM:SS` for display. `CPU sum` is the overlapping cost of lead and workers time combined, not wall-clock. Show wall-clock from `perRunWallClock` only when the user explicitly asks. For `by stage`/`per stage`/`which stage took longest`, the task-type view (the By task type table) is the default answer — do not treat it as 'not measurable'. Render the intra-run `phaseTimelines` only on an explicit request like 'Phase 1–7' / 'which phase', and when it is empty, mention it only as a footnote rather than a headline.
@@ -178,7 +173,7 @@ Interpretation points:
 wrapper sidecar log inventory:
 
 ```bash
-okstra log-report --project-root <projectRoot> --json
+okstra log-report --project-root <projectRoot> --text
 ```
 
 Scans `.okstra/tasks/**/runs/*/prompts/*.log`. Does not delete. The cleanup command merely presents a dry-run and `-delete` pair as fenced bash.
@@ -190,21 +185,21 @@ Deleting an active run's log loses the live trace, so recommend checking `status
 Aggregate task error logs into a markdown report.
 
 ```bash
-okstra error-report <task-key> --project-root <projectRoot>
+okstra error-report <task-key> --project-root <projectRoot> --text
 ```
 
-Read `reportPath`, totals, byPhase, byAgent, parseSkipped from the stdout JSON and summarize. If `reportPath` is absent and errorCount is 0, say there are no recorded error logs. Do not hide `parseSkipped > 0`.
+Read the fixed `Report path`, total, phase, agent, and parse-skipped labels and summarize. If the report path is `-` and total errors is 0, say there are no recorded error logs. Do not hide a nonzero parse-skipped count.
 
 ## error-zip
 
 Bundle the machine's cross-project okstra errors into an anonymized zip.
 
-For the output path, recommend `lastOutputPath` from `~/.okstra/error-zip.json` first, and if absent, propose `~/okstra-error-feedback-<YYYY-MM-DD>.zip`.
+Run `okstra model-io error-zip-input`. Recommend its `Previous output path` first when present; otherwise propose `~/okstra-error-feedback-<YYYY-MM-DD>.zip`.
 
 Run:
 
 ```bash
-okstra error-zip --out <path>
+okstra error-zip --out <path> --text
 ```
 
 Summary fields:
@@ -222,12 +217,14 @@ At the end, guide the user to build a brief with the error-feedback variant of `
 
 The default is artifact mode. It builds the before/after summary and answers questions using only `.okstra/` artifacts.
 
-assemble:
+Read the fixed recap projection:
 
 ```bash
-okstra recap assemble <task-key> --project-root <projectRoot>
+okstra model-io recap-input --project-root <projectRoot> --task-ref <task-key>
 ```
 
+Use the emitted `Run count` and repeated `Transition` fields in order. Do not parse recap JSON or open recap state files directly.
+
 record:
 
 ```bash

package/docs/for-ai/skills/okstra-manager.md

@@ -13,7 +13,8 @@ Use this to bundle okstra tasks across multiple projects into a single manager-o
 ## Execution Rules
 
 1. Every command starts with the literal `okstra`. Do not wrap it in shell variables, `$(...)`, `&&`, `eval`, or a leading env assignment.
-2. JSON stdout is the source of truth. Do not reconstruct manager state or child launch args from docs/memory.
+2. The fixed CLI fields are the source of truth. Do not reconstruct manager state or child launch args from docs/memory.
+   Nested project, manifest, child, snapshot, and directive values use numbered count/name/value rows; carry every returned row.
 3. `--workspace-root` is owned by the Node wrapper. The CLI rejects it if the user passes it.
 4. `new project`'s `--project-root` must be an already-existing directory. It performs setup-equivalent registration only when there is no `.okstra/project.json` inside it.
 5. The public child task identity is `project-id:task-group:task-id`. The `new task --task` example shows the full key form first.
@@ -22,16 +23,16 @@ Use this to bundle okstra tasks across multiple projects into a single manager-o
 ## Command Surface
 
 ```bash
-okstra manager init --manager-id <manager-id> --json
-okstra manager discover-projects --json
-okstra manager new project --manager-id <manager-id> --project-id <project-id> --project-root <abs-path> [--role <role>] [--tag <tag>] --json
-okstra manager new task-group --manager-id <manager-id> --task-group <task-group> --json
-okstra manager new task --manager-id <manager-id> --task-group <task-group> --task-id <task-id> [--task <project-id:task-group:task-id> ...] [--objective <text>] [--common-brief <path>] [--progress-mode <manual|auto>] --json
-okstra manager task assign --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <child-task-id>] [--role <role>] [--tag <tag>] [--assignment <text>] --json
-okstra manager task note --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --scope <shared|project> [--project-id <project-id>] --body <text> --json
-okstra manager task sync --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --json
-okstra manager task status --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --json
-okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>] --json
+okstra manager init --manager-id <manager-id>
+okstra manager discover-projects
+okstra manager new project --manager-id <manager-id> --project-id <project-id> --project-root <abs-path> [--role <role>] [--tag <tag>]
+okstra manager new task-group --manager-id <manager-id> --task-group <task-group>
+okstra manager new task --manager-id <manager-id> --task-group <task-group> --task-id <task-id> [--task <project-id:task-group:task-id> ...] [--objective <text>] [--common-brief <path>] [--progress-mode <manual|auto>]
+okstra manager task assign --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <child-task-id>] [--role <role>] [--tag <tag>] [--assignment <text>]
+okstra manager task note --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --scope <shared|project> [--project-id <project-id>] --body <text>
+okstra manager task sync --manager-id <manager-id> --task-group <task-group> --task-id <task-id>
+okstra manager task status --manager-id <manager-id> --task-group <task-group> --task-id <task-id>
+okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>]
 ```
 
 ## Storage Model
@@ -56,13 +57,13 @@ A segment whose slug is empty (e.g. a non-ASCII task-group/task-id) uses a `u-<s
 
 ## Child launch
 
-`task run` does not run the child work directly; it prepares a launch packet. The key fields of the returned packet:
+`task run` does not run the child work directly; it prepares a launch packet. The key fixed fields of the returned packet:
 
-- `taskKey`: the child's `project-id:task-group:task-id` (the public child-identity key — also recorded on the `child-launch-prepared` event)
-- `backend`: `tmux-child-lead` if `$TMUX` is present, otherwise `subagent-child-lead`
-- `workerDispatchBackend`: always `subagent` in v1
-- `projectRoot`: the child project root
-- `contextPath`: the manager child context markdown
-- `runArgs`: the `okstra run ... --directive "Read manager child context: ..."` args for the host launcher to use
+- `Task key`: the child's `project-id:task-group:task-id` (the public child-identity key — also recorded on the `child-launch-prepared` event)
+- `Backend`: `tmux-child-lead` if `$TMUX` is present, otherwise `subagent-child-lead`
+- `Worker dispatch backend`: always `subagent` in v1
+- `Project root`: the child project root
+- `Context path`: the manager child context markdown
+- every numbered `Run arg N`: the ordered `okstra run ... --directive "Read manager child context: ..."` arguments for the host launcher to use
 
 When packet creation succeeds, that child launch's status in `children.json` is updated to `prepared`, and a `child-launch-prepared` is appended to `events.jsonl`. On failure it does not modify the project-local task state.

package/docs/for-ai/skills/okstra-memory.md

@@ -51,7 +51,7 @@ Every memory entry belongs to a project-group. Pick the group before storing or
 Enumerate existing groups:
 
 ```bash
-okstra memory groups --json
+okstra memory groups
 ```
 
 Recommendations:
@@ -108,7 +108,7 @@ okstra memory show "<memory-id>"
 okstra memory archive "<memory-id>"
 ```
 
-Prefer `--json` when you need to parse IDs. Show the user only a short summary plus the entry id/path.
+Read IDs from the fixed text rows. Show the user only a short summary plus the entry id/path.
 
 ## Output rules
 

package/docs/for-ai/skills/okstra-pr-gen.md

@@ -31,9 +31,9 @@ A 3-option picker via `AskUserQuestion`:
 
 ## Mode A — Generate PR
 
-1. Pick a template: `okstra pr template list --json`. If empty, use the bundled default. Carry the chosen name as `<template>` (`default` for the bundled one).
-2. Pick the base branch: `okstra pr branches --json`. 3-option from the top `recommended` entries plus `Enter directly`. Carry the choice as `<base>`.
-3. Generation bundle: `okstra pr gen --base <base> --template <template> --json` → `{base, currentBranch, templateName, template, commits, diffStat}`. Then **read the real diff honestly** (SSOT): `git diff <base>...HEAD` (large diffs section by section). Fill the placeholders from the diff and commits, describing **only actual changes**. Mark a checklist box `[x]` only when the diff supports it (tests touched → tests box, docs touched → docs box). If `commits`/`diffStat` are empty, say there is nothing to describe and stop. **Never append AI trailers/footers.**
+1. Pick a template: `okstra pr template list`. If the numbered `Templates` rows are empty, use the bundled default. Carry the chosen name as `<template>` (`default` for the bundled one).
+2. Pick the base branch: `okstra pr branches`. Build a 3-option picker from the numbered `Recommended` rows plus `Enter directly`. Carry the choice as `<base>`.
+3. Generation bundle: `okstra pr gen --base <base> --template <template>`. Read the fixed `Base`, `Current branch`, `Template name`, `Commits`, `Diff stat`, and `Template` sections. Then **read the real diff honestly** (SSOT): `git diff <base>...HEAD` (large diffs section by section). Fill the placeholders from the diff and commits, describing **only actual changes**. Mark a checklist box `[x]` only when the diff supports it (tests touched → tests box, docs touched → docs box). If `Commits` or `Diff stat` is empty, say there is nothing to describe and stop. **Never append AI trailers/footers.**
 4. Identifier allowlist for the title and body: only repo-relative source paths (optionally `path:line`), symbol names present in the diff, branch names / commit subjects / SHAs, and issue-tracker ticket ids the reviewer can open. okstra's own artifact identifiers are out of the allowlist — report item ids (`F-001`, `C-001`, `R-001`, `D-0001`, `PREP-001`), run artifact names and their `<task-type>-<seq>` suffixes, phase/stage/worker labels (`final-verification`, `stage-2`, `codex-worker`), and any path under `.okstra/`. They resolve to nothing for a reviewer; restate the substance in code terms instead of citing the id.
 5. Output and offer to create the PR: print the filled PR body as a single fenced markdown block. Ask whether to open a PR. **Only on an explicit yes**: write the body to a temp file and run `gh pr create --base <base> --title "<title>" --body-file <path>`. If `gh` is missing or unauthenticated (`gh auth status` fails), leave the text in chat and give manual-creation guidance. **No push/PR creation without the user's confirmation.**
 

package/docs/for-ai/skills/okstra-rollup.md

@@ -37,10 +37,11 @@ Do not use it when:
 A single Bash call starting with the literal `okstra` token (not wrapped in `if`/`eval`/`$(...)`/`VAR=`/`||`/`&&`/`npx` fallback):
 
 ```bash
-okstra preflight --runtime claude-code --json
+okstra preflight --runtime claude-code
 ```
 
-`ok:false` → point to `/okstra-setup` and stop. If `ok:true`, carry `projectRoot` as a literal string and proceed.
+On `Okstra preflight: ready`, carry `Project root` as a literal string. On
+`Okstra preflight: failed`, show `Reason` and `Recovery`, then stop.
 
 ## scope resolution
 
@@ -51,26 +52,26 @@ okstra preflight --runtime claude-code --json
 ## CLI call
 
 ```bash
-okstra rollup --task-group <group> --project-root <projectRoot> --json
+okstra rollup --task-group <group> --project-root <projectRoot> --text
 ```
 
-For the whole project, drop `--task-group`. The output is always JSON, and **all times are raw milliseconds**.
+For the whole project, drop `--task-group`. The output is fixed, ordered label/value rows, and **all times are raw milliseconds**.
 
 ## Interpreting the output
 
-Top level:
+Fixed fields:
 
-- `taskGroup` — the scope (`null` = whole project), `taskCount` — number of tasks.
-- `tasks[]` — per task: `taskKey, taskGroup, taskId, taskType, workCategory, workStatus, currentPhase, currentPhaseState, nextRecommendedPhase, latestRunStatus, updatedAt, reportPath, runCount, cpuSumMs, wallClockMs, errorCount`.
-  - `nextRecommendedPhase` is an object `{phase, status, rationale}`, not a string. Print `phase`, or `--` when it is empty. Never interpolate the object itself.
-- `totals` — `runs, cpuSumMs, wallClockMs, errors`, plus `byWorkStatus` / `byWorkCategory` / `byCurrentPhase` / `byTaskType` (each a `{value: count}` map).
+- `Task group` and `Task count` identify the scope.
+- Numbered `Tasks` rows carry task identity, status, phase, next phase, report path, run count, CPU, wall-clock, and error count.
+- `Totals runs`, `Totals CPU sum ms`, `Totals wall clock ms`, and `Totals errors` are the aggregate values.
+- Numbered `Work status`, `Work category`, `Current phase`, and `Task type` rows carry the aggregate distributions.
 
 Numeric meanings (must observe):
 
-- `runCount` is the **total number of runs** in the timeline. `cpuSumMs`/`wallClockMs` reflect only runs that reached Phase 7 usage, so they can be `0` even when `runCount > 0`.
-- `cpuSumMs` is the **CPU sum** of the overlapping lead + workers, not wall-clock. Label it "CPU", and show wall-clock as `wallClockMs` only when the user explicitly asks.
-- `reportPath` is project-relative and may be empty (a task with no report yet).
-- If `taskCount` is `0`, say there are no okstra tasks in that scope and stop.
+- `Run count` is the **total number of runs** in the timeline. CPU and wall-clock rows reflect only runs that reached Phase 7 usage, so they can be `0` even when run count is positive.
+- `CPU sum ms` is the **CPU sum** of the overlapping lead + workers, not wall-clock.
+- `Report path` is project-relative and may be `-` for a task with no report yet.
+- If `Task count` is `0`, say there are no okstra tasks in that scope and stop.
 
 ## Render
 

package/docs/for-ai/skills/okstra-run.md

@@ -37,10 +37,14 @@ Do not use it when:
 Resolve `<host-runtime>` from the executing harness: Claude Code → `claude-code`, Codex → `codex`, Antigravity CLI → `antigravity`, and another adapter host → `external`. This is a host capability, not a `PATH` inference or worker-provider choice. The lead provider is derived from this value and cannot be selected independently. Then make one Bash call:
 
 ```bash
-okstra preflight --runtime <host-runtime> --json
+okstra preflight --runtime <host-runtime>
 ```
 
-If there is no runtime or project setup (`ok:false`), point the user to `/okstra-setup` and stop. Do not create an `export PYTHONPATH`.
+On `Okstra preflight: failed`, show `Reason`, `Recovery`, `Runtime readiness`,
+and every repeated `Readiness check` line, then stop. On
+`Okstra preflight: ready`, require `Runtime readiness: ready`, carry the fixed
+`Project root` line, and read the `Relay contract` path. Do not create an
+`export PYTHONPATH`.
 
 ## Bash invocation rule
 
@@ -187,7 +191,7 @@ This picker is authored by the skill, so it is separate from the wizard-option-a
 
 When a `PrepareError` such as `Recorded stage SHAs no longer match the git history` appears, do not fix the registry/consumers by hand.
 
-1. Run the `okstra git-reconcile ... --check --json` printed in the error message verbatim.
+1. Run the `okstra git-reconcile ... --check --text` printed in the error message verbatim.
 2. For each confirm item, ask the user for the current branch tip, a different ref, or abort.
 3. Run `okstra git-reconcile ... --apply --stage <N> --use-ref <ref>` with the chosen ref.
 4. Retry the failed render-bundle with the same arguments.