soturail 1.0.1 → 1.2.0

package/docs/agent-governance-rail.md

@@ -0,0 +1,89 @@
+# Agent Governance And Evolution Rail
+
+Agent Governance And Evolution Rail is a later-stage direction for controlled improvement loops around SotuRail artifacts and agent-facing harnesses.
+
+It absorbs ideas from self-improving harness systems while keeping SotuRail conservative:
+
+```txt
+propose -> eval -> approve -> apply
+```
+
+No future loop should silently edit projects or bypass human approval.
+
+## Planned Concepts
+
+### Agent Boundary
+
+A future policy can define what an agent may change, read or append:
+
+```yaml
+mutable:
+  - src/**
+  - tests/**
+  - docs/**
+read_only:
+  - package.json
+  - package-lock.json
+  - .github/**
+  - .env*
+append_only:
+  - .soturail/logs/**
+  - .soturail/ledger/**
+  - .soturail/reports/**
+rules:
+  require_tests_before_apply: true
+  require_no_context_regression: true
+  one_patch_per_run: true
+```
+
+### Ledger
+
+Append-only records can explain decisions:
+
+```json
+{
+  "run_id": "run_2026_06_05_001",
+  "agent": "claude-code",
+  "action": "proposed_patch",
+  "files_touched": ["src/context.ts"],
+  "approved": false,
+  "tests_passed": true
+}
+```
+
+### Experiments
+
+```txt
+.soturail/experiments/
+  candidates/
+  results/
+  accepted/
+  rejected/
+```
+
+Candidate changes should be compared through deterministic evals before approval.
+
+## Proposed Commands
+
+```bash
+soturail trace start
+soturail trace stop
+soturail trace list
+soturail trace show <id>
+soturail ledger list
+soturail experiment create "improve context ranking"
+soturail experiment run
+soturail experiment compare
+soturail improve propose
+soturail improve eval
+soturail improve approve
+soturail improve apply
+```
+
+## Non-Goals
+
+- no autonomous self-modifying runtime by default;
+- no hosted multi-tenant control plane;
+- no required Anthropic/OpenAI/Groq provider;
+- no destructive MCP tools;
+- no applying patches without reviewable diff and approval.

package/docs/agent-harness-synthesis-2026.md

@@ -0,0 +1,101 @@
+# Agent And Harness Synthesis 2026
+
+This document merges the latest external-repository review into one SotuRail planning note. It distinguishes agent runtimes from harness/context infrastructure so SotuRail can absorb useful ecosystem patterns without losing its product boundary. It is not a dependency list and it is not a claim that SotuRail vendors, wraps or outperforms those projects.
+
+SotuRail remains:
+
+```txt
+Local-first Context OS for AI coding agents.
+It prepares context, memory, policies, skills, workflows, evidence, reports and host exports.
+It is not the model, not the coding agent, not a proxy, not a cloud gateway and not a trading/finance agent.
+```
+
+## Classification
+
+```txt
+Agent = objective + model + tools + state/memory + decision/execution loop.
+Non-agent = skill, toolkit, toolset, compressor, router, runtime helper, context, prompt, rule or adapter.
+```
+
+Hermes Agent is a self-improving agent runtime with a model, tools, memory, execution loop, skills, routines, subagents and multiple interfaces.
+
+Odysseus is broader: a self-hosted AI workspace combining an agent runtime, chat UI, local services, model management, memory, skills, research and personal workspace features.
+
+SotuRail is different:
+
+```txt
+Hermes = self-improving personal agent runtime
+Odysseus = workspace + runtime + agent + UI + local services
+SotuRail = local-first context/harness OS for preparing and governing agents
+```
+
+Toolkits, compressors and routers should not be described as agents unless they own a model-plus-tool execution loop.
+
+## Projects Reviewed In This Wave
+
+| Project or product | Useful pattern | SotuRail direction |
+| --- | --- | --- |
+| Hermes Agent | self-improving runtime, trajectory compression, routines and role packs | context optimization, bounded sessions and safe tool profiles |
+| Odysseus | workspace, runtime, UI and local-service integration | local workspace organization without a required server |
+| `ijmf/qa-ai-agent` | agent QA with tests, datasets, observability and CI | Agent QA Rail, golden checks, deterministic evals |
+| `duckdogersxd/Orquestrando-Agents-CrewAI` | multi-agent roles, fallback, retry and throttling lessons | role-pack templates and Resilience Rail docs |
+| `CaioTakedaIA/agentesdeIA` | validate -> fix -> revalidate -> analyze pipeline with visible events | pipeline recorder, evidence per stage and dashboard timeline |
+| `OpenTracy/OpenTracy` | propose -> eval -> approve -> apply loop, traces, ledger, candidates | Agent Governance / Evolution Rail |
+| `walkinglabs/learn-harness-engineering` | instructions, state, verification, scope and session lifecycle | Harness Lifecycle Rail and feature/session handoff commands |
+| `affaan-m/ECC` | install profiles, doctor/repair/uninstall, skills/rules/hooks, multi-host packaging | install state, harness audit, skills/rules profiles and host exports |
+| `companion-inc/feynman` | provenance sidecars, verified/unverified/blocked/inferred status, file-based handoff | Evidence and Provenance Rail |
+| `virgiliojr94/book-to-skill` | document/book -> skill, on-demand chapters, glossary, patterns and cheatsheet | Knowledge Rail and skill build/fold-in |
+| Tasklet.ai | limited public information; reusable small tasks as a concept | Tasklet Rail as local task templates only |
+| 9Router | multi-host routing metaphor, token/context optimization, local dashboard | Host Router Rail for context exports; no proxy/MITM |
+
+## Patterns To Absorb
+
+- Context and trajectory compression with recoverable evidence.
+- Session search and bounded handoffs.
+- Toolset profiles and role packs.
+- Tasklet/workflow templates.
+- Host Fit Doctor and compatibility notes.
+- Dashboard cards for Context Packs, Memory, Reports, Evidence, Workflows, Skills, Tasklets and Handoffs.
+- Local-first privacy and explicit security boundaries.
+- Doctor/audit/repair/uninstall paths for generated artifacts.
+- Provenance, evidence and verification status for reports.
+
+## Patterns To Avoid
+
+- Mandatory web servers or hosted workspaces.
+- Model serving and GPU management.
+- Central shell execution or destructive MCP tools.
+- Provider-specific dependencies and hidden external services.
+- Unreviewed autonomous edit loops.
+- Proxy, MITM, billing, unlimited-free or cloud telemetry claims.
+- Interception of IDE traffic, browser sessions, cookies or provider credentials.
+
+## Rail Map
+
+| New or expanded rail | Main purpose | Inspired by |
+| --- | --- | --- |
+| Agent QA Rail | datasets, golden checks, regression reports and optional judges | `qa-ai-agent` |
+| Resilience Rail | rate-limit, retry, fallback and provider-risk policy docs | CrewAI/LiteLLM-style repo, 9Router concept |
+| Pipeline Recorder | record agent-stage events and evidence packs | `agentesdeIA` |
+| Agent Governance Rail | trace, ledger, candidates, approval gate and improve loop | OpenTracy |
+| Harness Lifecycle Rail | init, audit, feature list, session start/end and handoff | learn-harness-engineering, Hermes, Odysseus |
+| Install/Profile Rail | profile-based install state, doctor, repair and uninstall | ECC |
+| Evidence/Provenance Rail | provenance sidecars and verification status | Feynman |
+| Knowledge Rail | document ingestion into on-demand skills | book-to-skill |
+| Host Router Rail | one context source exported to many hosts with fallback formats | 9Router metaphor |
+| Tasklet Rail | small reusable local task templates | Tasklet concept |
+
+## SotuRail Direction
+
+v1.2.0 implements Harness Lifecycle Rail for local state, audits, feature tracking, sessions and handoffs. The optional [Conductor Mode](conductor-mode.md) remains proposed future work behind approval gates.
+
+```txt
+v1.1.1  Host Compatibility Polish, docs synthesis, golden export checks
+v1.2.0  Harness Lifecycle Rail plus staged Spec, Design and Diagram work
+v1.3.0  Knowledge, Evidence and Evaluation Rail
+v1.4.0  Skill Rail 2.0, Knowledge-to-Skill and Tasklet Packs
+v1.5.0  Governance, Cost, Resilience and Host Router Rail
+v1.6.0  Agent Governance / Evolution Rail
+```
+
+The exact future command names are not frozen. Related: [Ecosystem Influences](ecosystem-influences.md), [External Projects Audit](external-projects-audit.md), [Harness Lifecycle Rail](harness-lifecycle-rail.md), [Security Boundaries](security-boundaries.md).

package/docs/agent-hosts.md

@@ -1,15 +1,19 @@
 # Agent Hosts
 
-SotuRail v1.0.0 includes a conservative host compatibility matrix. It reports what SotuRail can export safely without claiming direct runtime control over every host.
+SotuRail v1.1.0 includes Host Compatibility Rail 1.0. It reports what SotuRail can export safely without claiming direct runtime control over every host.
 
 ```bash
 soturail agents matrix
 soturail agents matrix --json
+soturail agents doctor --host codex
+soturail agents doctor --all --json
+soturail mcp resources host-manifest --host codex
 ```
 
 ## Host Status Model
 
 - `stable`: covered by the v1 local export/report surface.
+- `generic-compatible`: safe generic Markdown/context handoff, but not host-native integration.
 - `legacy`: supported through compatible prompt/context artifacts, but host behavior may vary.
 - `experimental`: prompt-only or docs-only until host-specific surfaces are verified.
 - `planned`: not promoted yet.
@@ -20,12 +24,27 @@ soturail agents matrix --json
 - Codex: stable prompt/context/report handoff through AGENTS-style Markdown.
 - Claude: stable local docs and dry-run-first install/export guidance.
 - Cursor: stable local rules/export guidance, with MCP treated conservatively.
-- Gemini compatible hosts: legacy/prompt-compatible Markdown and JSON summaries.
-- OpenCode-style hosts: experimental prompt-only export.
-- Antigravity-style hosts: experimental prompt-only export.
+- Gemini: legacy/prompt-compatible Markdown and JSON summaries.
+- Gemini legacy/compatible hosts: legacy AGENTS/GEMINI Markdown export.
+- OpenCode-style hosts: generic-compatible `AGENTS.md` and context-pack export.
+- Antigravity-style hosts: high-priority experimental `AGENTS.md` and context-pack export.
 - DeepAgents-style targets: experimental role-pack and Markdown exports only.
 - Generic: stable portable Markdown, JSON reports and read-only MCP report resources.
 
 ## Safety
 
-No host row enables destructive MCP tools or arbitrary shell execution. Config writes remain dry-run or review-first. Use `soturail report agent --agent <host>` and review the output before agent handoff.
+No host row enables destructive MCP tools or arbitrary shell execution. Config writes remain dry-run or review-first. Use `soturail report agent --agent <host>`, `soturail agents doctor --host <host>` and review the output before agent handoff.
+
+See [host-matrix-schema.md](host-matrix-schema.md), [agent-export-contract.md](agent-export-contract.md) and [mcp-host-manifest.md](mcp-host-manifest.md).
+
+## Related Host Router And Resilience Docs
+
+Host docs are connected to several planned rails:
+
+- [`host-router-rail.md`](host-router-rail.md): one local context source exported into host-specific formats with safe fallback.
+- [`host-compatibility-rail.md`](host-compatibility-rail.md): current host matrix, schema and export contracts.
+- [`rate-limit-and-fallback-policy.md`](rate-limit-and-fallback-policy.md): local documentation shape for retry/fallback/rate-limit expectations.
+- [`resilience-rail.md`](resilience-rail.md): provider and workflow-risk warnings without proxying model traffic.
+- [`agent-qa-rail.md`](agent-qa-rail.md): golden checks for host exports.
+
+SotuRail host support means context, instruction, report, skill and MCP-resource packaging. It does not mean intercepting IDE traffic, reusing browser tokens, routing model requests or bypassing provider quotas.

package/docs/agent-qa-rail.md

@@ -0,0 +1,92 @@
+# Agent QA Rail
+
+Agent QA Rail is a proposed future rail for testing SotuRail-generated agent artifacts like software outputs, not magic prompts.
+
+It is inspired by small QA-agent repos that combine automated tests, fixed datasets, scoring, observability and CI. SotuRail should keep the useful discipline while staying local-first, host-independent and deterministic by default.
+
+## Goals
+
+- Test host exports, context packs, skills, rules, workflows, evidence packs and reports.
+- Catch regressions in agent-facing files before release.
+- Keep default evals offline and cheap.
+- Allow optional provider-backed judging only when explicitly requested.
+- Generate JSON and Markdown reports that can be attached to release evidence.
+
+## Proposed Commands
+
+```bash
+soturail eval dataset init
+soturail eval dataset run
+soturail eval golden
+soturail eval regression
+soturail eval report
+soturail eval doctor
+soturail eval judge --optional
+```
+
+These commands can begin as report-only or fixture-only surfaces before becoming full command implementations.
+
+## Local Artifact Layout
+
+```txt
+.soturail/evals/
+  datasets/
+    host-compatibility.json
+    context-quality.json
+    skill-routing.json
+  golden/
+    claude-export.md
+    codex-export.md
+    cursor-rules.md
+  runs/
+    latest.json
+  reports/
+    latest.md
+```
+
+## Deterministic Checks First
+
+Default checks should not call real LLMs or external services.
+
+Examples:
+
+- export is not empty;
+- export contains safe next commands;
+- export includes required policy warnings;
+- export does not contain secrets;
+- export does not contain unrelated project names such as SoturAI when the target is SotuRail;
+- JSON artifacts parse successfully;
+- duplicate JSON keys are detected where relevant;
+- host matrix fields are present;
+- MCP exports keep read-only mutation boundaries;
+- reports include evidence paths and verification status;
+- generated docs keep local-first and no-cloud-by-default claims honest.
+
+## Optional LLM-As-Judge
+
+Provider-backed judges can be useful for hallucination or answer-quality review, but they must not be the default release gate.
+
+Policy:
+
+```txt
+Offline fixtures are release-blocking.
+LLM-as-judge is optional, explicit and non-blocking unless a project opts in.
+Provider outputs must be stored as separate integration evidence.
+```
+
+## CI Split
+
+Recommended tiers:
+
+| Tier | Network | Release blocking | Purpose |
+| --- | --- | --- | --- |
+| unit/offline | no | yes | deterministic docs, schemas, exports and fixtures |
+| integration | optional | no by default | provider/API behavior, external host smoke |
+| nightly | optional | no by default | long-running or flaky judge/eval experiments |
+
+## Non-Goals
+
+- no required Groq, OpenAI, Anthropic, LangFuse or other provider;
+- no real model calls in default tests;
+- no scoring metric based only on marketing-friendly numbers;
+- no claim that passing evals proves a real agent will always behave well.

package/docs/agents.md

@@ -12,7 +12,11 @@ soturail agents status
 soturail agents status --json
 soturail agents doctor
 soturail agents doctor --verbose
+soturail agents doctor --host codex
+soturail agents doctor --all --json
 soturail agents export --agent all
+soturail agents export --agent opencode --out .soturail/agents/opencode
+soturail agents export --agent deepagents --role reviewer
 soturail brain export --agent codex
 soturail agents export --agent deepagents
 soturail agents export --agent deepagents-js
@@ -26,7 +30,7 @@ soturail agents install --agent cursor --mode rules --dry-run
 soturail agents uninstall --agent claude --dry-run
 ```
 
-Exports are written under `.soturail/exports/agents/<agent>/`. They are meant to be reviewed before use.
+Default exports are written under both `.soturail/agents/<agent>/` and `.soturail/exports/agents/<agent>/`. The older exports path remains for compatibility; the `.soturail/agents/` path is the v1.1 host workspace. They are meant to be reviewed before use.
 
 Project Brain exports are written under `.soturail/brain/exports/`. They provide verified claims, rules, gaps, stale warnings and source references for agent handoff.
 
@@ -45,12 +49,14 @@ Project Brain exports are written under `.soturail/brain/exports/`. They provide
 
 `soturail agents capabilities` prints the host capability matrix. Use `--json` for a stable machine-readable shape.
 
-`soturail agents matrix` prints the v1 host compatibility matrix with stable, legacy, experimental and planned status labels. It does not claim full OpenCode, Antigravity-style or DeepAgents-style runtime support unless the row says so.
+`soturail agents matrix` prints the v1/v1.1 host compatibility matrix with stable, generic-compatible, legacy, experimental and planned status labels. It does not claim full OpenCode, Antigravity-style or DeepAgents-style runtime support unless the row says so.
 
 `soturail agents status` inspects local files such as `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/`, `.claude/settings.json`, `.soturail/exports/agents/`, role packs, skills, MCP exports, policy queues and run workspaces.
 
 `soturail agents doctor --verbose` combines readiness checks with host capability, payload, policy and dry-run install guidance.
 
+`soturail agents doctor --host <host>` generates `.soturail/agents/<host>/doctor.json` and `.md`. `--all --json` writes `.soturail/agents/doctor-summary.json` and checks every host export for obvious secret patterns, unsafe MCP claims, raw evidence references and SotuRail scope contamination.
+
 ## v0.6.1 UX Flow
 
 Start with status, budget and one role pack, then preview the host install or export.
@@ -116,12 +122,14 @@ If context packs or exports already exist, the doctor omits those setup steps an
 
 - Claude: `CLAUDE.md`, `mcp-config.json`, `safe-hooks.md`, `context-pack.md`.
 - Codex: `AGENTS.md`, `context-pack.md`, `prompt-only.md`.
-- Gemini: `GEMINI.md`, `context-pack.md`, `prompt-only.md`.
-- Cursor: `cursor-rules.md`, `context-pack.md`, `prompt-only.md`.
-- Antigravity: `context-pack.md`, `prompt-only.md`.
-- Generic: `context-pack.md`, `prompt-only.md`.
-- OpenCode/Amp/Kiro-style hosts: `context-pack.md`, `prompt-only.md`.
-- Deep Agents/deepagents-js: `<agent>.md`, `runtime-config.json`, `context-pack.md`.
+- Gemini: `AGENTS.md`, `GEMINI.md`, `context-pack.md`, `prompt-only.md`.
+- Gemini legacy-compatible: `AGENTS.md`, `GEMINI.md`, `context-pack.md`, `prompt-only.md`.
+- Cursor: `rules.md`, `cursor-rules.md`, `context-pack.md`, `prompt-only.md`.
+- Antigravity: `AGENTS.md`, `context-pack.md`, `prompt-only.md`.
+- Generic: `AGENT_CONTEXT.md`, `context-pack.md`, `prompt-only.md`.
+- OpenCode-style hosts: `AGENTS.md`, `context-pack.md`, `prompt-only.md`.
+- Amp/Kiro-style hosts: `context-pack.md`, `prompt-only.md`.
+- Deep Agents/deepagents-js: `role-pack.md`, `subagents.md`, `<agent>.md`, `runtime-config.json`, `context-pack.md`.
 
 ## Host Capability Matrix
 
@@ -136,7 +144,8 @@ SotuRail encodes host capabilities instead of assuming every agent supports the
 | Antigravity | prompt-only Markdown/tagged fallback | prompt-only/context-pack | unknown/experimental | no deep integration until stable official surfaces are verified | do not invent config paths |
 | Deep Agents / deepagents-js | role packs, context offload notes, skills routing | export-only | future resource/config export only | no runtime coupling by default | human approval and filesystem evidence required for risky flows |
 | Claude Code Harness-style workflows | workflow/evidence docs, guardrail policy, review perspectives | docs/export only | no special MCP assumption | compatibility notes only | keep SotuRail independent from Claude-only flows |
-| OpenCode/Amp/Kiro-style hosts | Markdown/context packs/specs | prompt/context export first | optional read-only if supported | deeper integrations only after official surfaces are clear | host docs must remain conservative |
+| OpenCode-style hosts | AGENTS.md/context packs/specs | prompt/context export first | optional read-only if supported | deeper integrations only after official surfaces are clear | generic-compatible, not full host-native support |
+| Amp/Kiro-style hosts | Markdown/context packs/specs | prompt/context export first | optional read-only if supported | deeper integrations only after official surfaces are clear | host docs must remain conservative |
 | Generic agents | Markdown/context packs | file export | MCP read-only resources | none | safest fallback for unknown hosts |
 
 ## Host-Aware Payload Formats
@@ -254,11 +263,19 @@ Those exports should explain:
 - which payload format was chosen;
 - whether any long context was offloaded.
 
-## Future Harness And Handoff Support
+## Harness And Handoff Support
 
-SotuRail can support disciplined handoffs without becoming the agent runtime.
+SotuRail supports disciplined local handoffs without becoming the agent runtime:
 
-Possible future commands:
+```bash
+soturail harness init
+soturail harness audit
+soturail session start "objective"
+soturail handoff generate
+soturail feature list
+```
+
+Additional role-to-role host handoff aliases remain future possibilities:
 
 ```bash
 soturail agents handoff --from planner --to executor
@@ -276,3 +293,5 @@ A handoff should include:
 - evidence pack pointers;
 - raw/offload recovery IDs;
 - next safe command suggestions.
+
+Current handoffs are written to `.soturail/state/session-handoff.md`. They include bounded local state and changed-file names, do not read private shell history and do not run verification commands.

package/docs/assets/demos/README.md

@@ -0,0 +1,3 @@
+# Demo Assets
+
+This folder is reserved for short local demo captures. Do not add files that include real tokens, private paths, `.env` contents or raw evidence.

package/docs/assets/screenshots/agents-matrix.svg

@@ -0,0 +1,35 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="520" viewBox="0 0 960 520" role="img" aria-labelledby="title desc">
+  <title id="title">SotuRail agent matrix screenshot</title>
+  <desc id="desc">Illustrative host compatibility matrix with stable, legacy and experimental rows.</desc>
+  <rect width="960" height="520" fill="#f8fafc"/>
+  <text x="48" y="64" font-family="Segoe UI, Arial, sans-serif" font-size="30" font-weight="700" fill="#172033">Agent Host Compatibility Matrix</text>
+  <rect x="48" y="100" width="864" height="336" rx="8" fill="#ffffff" stroke="#d7dee8"/>
+  <g font-family="Segoe UI, Arial, sans-serif" font-size="18" fill="#172033">
+    <text x="72" y="142" font-weight="700">Host</text>
+    <text x="284" y="142" font-weight="700">Status</text>
+    <text x="468" y="142" font-weight="700">MCP</text>
+    <text x="650" y="142" font-weight="700">Command</text>
+    <line x1="72" y1="160" x2="880" y2="160" stroke="#d7dee8"/>
+    <text x="72" y="198">Codex</text>
+    <text x="284" y="198" fill="#15803d">stable</text>
+    <text x="468" y="198">prompt-only</text>
+    <text x="650" y="198" font-family="Consolas, monospace" font-size="15">agents export --agent codex</text>
+    <text x="72" y="244">OpenCode</text>
+    <text x="284" y="244" fill="#0369a1">generic-compatible</text>
+    <text x="468" y="244">planned</text>
+    <text x="650" y="244" font-family="Consolas, monospace" font-size="15">agents export --agent opencode</text>
+    <text x="72" y="290">Antigravity</text>
+    <text x="284" y="290" fill="#b45309">experimental</text>
+    <text x="468" y="290">planned</text>
+    <text x="650" y="290" font-family="Consolas, monospace" font-size="15">agents doctor --host antigravity</text>
+    <text x="72" y="336">Gemini Legacy</text>
+    <text x="284" y="336" fill="#6d28d9">legacy</text>
+    <text x="468" y="336">planned</text>
+    <text x="650" y="336" font-family="Consolas, monospace" font-size="15">agents export --agent gemini-legacy</text>
+    <text x="72" y="382">DeepAgents</text>
+    <text x="284" y="382" fill="#b45309">experimental</text>
+    <text x="468" y="382">docs-only</text>
+    <text x="650" y="382" font-family="Consolas, monospace" font-size="15">agents export --agent deepagents</text>
+  </g>
+  <text x="48" y="472" font-family="Segoe UI, Arial, sans-serif" font-size="18" fill="#475569">All rows keep mutationAllowedByDefault=false.</text>
+</svg>

package/docs/assets/screenshots/host-doctor.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="520" viewBox="0 0 960 520" role="img" aria-labelledby="title desc">
+  <title id="title">SotuRail host doctor screenshot</title>
+  <desc id="desc">Illustrative per-host doctor output.</desc>
+  <rect width="960" height="520" fill="#f8fafc"/>
+  <rect x="56" y="48" width="852" height="424" rx="8" fill="#0f172a"/>
+  <text x="88" y="94" font-family="Consolas, monospace" font-size="22" fill="#d1fae5">$ soturail agents doctor --host codex</text>
+  <g font-family="Consolas, monospace" font-size="18">
+    <text x="88" y="142" fill="#e5e7eb">SotuRail agent host doctor</text>
+    <text x="88" y="176" fill="#93c5fd">schemaVersion:</text>
+    <text x="246" y="176" fill="#fde68a">soturail.agent-host-doctor.v1</text>
+    <text x="88" y="210" fill="#93c5fd">host:</text>
+    <text x="160" y="210" fill="#fde68a">codex</text>
+    <text x="88" y="244" fill="#93c5fd">status:</text>
+    <text x="176" y="244" fill="#86efac">passed</text>
+    <text x="88" y="292" fill="#e5e7eb">Checks:</text>
+    <text x="112" y="326" fill="#86efac">- matrix-row: passed</text>
+    <text x="112" y="360" fill="#86efac">- export-generated: passed</text>
+    <text x="112" y="394" fill="#86efac">- mcp-read-only: passed</text>
+    <text x="112" y="428" fill="#86efac">- scope-contamination: passed</text>
+  </g>
+</svg>

package/docs/assets/screenshots/status-json.svg

@@ -0,0 +1,30 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="520" viewBox="0 0 960 520" role="img" aria-labelledby="title desc">
+  <title id="title">SotuRail status JSON screenshot</title>
+  <desc id="desc">Illustrative terminal screenshot showing valid JSON status output.</desc>
+  <rect width="960" height="520" fill="#f7fafc"/>
+  <rect x="48" y="48" width="864" height="424" rx="8" fill="#111827"/>
+  <rect x="48" y="48" width="864" height="40" rx="8" fill="#243044"/>
+  <circle cx="72" cy="68" r="6" fill="#ef4444"/>
+  <circle cx="92" cy="68" r="6" fill="#f59e0b"/>
+  <circle cx="112" cy="68" r="6" fill="#22c55e"/>
+  <text x="72" y="126" font-family="Consolas, monospace" font-size="22" fill="#d1fae5">$ soturail status --json</text>
+  <text x="72" y="166" font-family="Consolas, monospace" font-size="18" fill="#e5e7eb">{</text>
+  <text x="96" y="198" font-family="Consolas, monospace" font-size="18" fill="#93c5fd">"schemaVersion"</text>
+  <text x="256" y="198" font-family="Consolas, monospace" font-size="18" fill="#e5e7eb">: </text>
+  <text x="282" y="198" font-family="Consolas, monospace" font-size="18" fill="#fde68a">"soturail.status.v1"</text>
+  <text x="96" y="230" font-family="Consolas, monospace" font-size="18" fill="#93c5fd">"version"</text>
+  <text x="196" y="230" font-family="Consolas, monospace" font-size="18" fill="#e5e7eb">: </text>
+  <text x="222" y="230" font-family="Consolas, monospace" font-size="18" fill="#fde68a">"1.1.0"</text>
+  <text x="96" y="262" font-family="Consolas, monospace" font-size="18" fill="#93c5fd">"brain"</text>
+  <text x="174" y="262" font-family="Consolas, monospace" font-size="18" fill="#e5e7eb">: { </text>
+  <text x="230" y="262" font-family="Consolas, monospace" font-size="18" fill="#93c5fd">"brainStatus"</text>
+  <text x="374" y="262" font-family="Consolas, monospace" font-size="18" fill="#e5e7eb">: </text>
+  <text x="400" y="262" font-family="Consolas, monospace" font-size="18" fill="#fde68a">"warning"</text>
+  <text x="496" y="262" font-family="Consolas, monospace" font-size="18" fill="#e5e7eb"> },</text>
+  <text x="96" y="294" font-family="Consolas, monospace" font-size="18" fill="#93c5fd">"nextCommands"</text>
+  <text x="248" y="294" font-family="Consolas, monospace" font-size="18" fill="#e5e7eb">: [</text>
+  <text x="128" y="326" font-family="Consolas, monospace" font-size="18" fill="#fde68a">"soturail report build"</text>
+  <text x="128" y="358" font-family="Consolas, monospace" font-size="18" fill="#fde68a">"soturail self readiness --v1 --strict"</text>
+  <text x="96" y="390" font-family="Consolas, monospace" font-size="18" fill="#e5e7eb">]</text>
+  <text x="72" y="422" font-family="Consolas, monospace" font-size="18" fill="#e5e7eb">}</text>
+</svg>

package/docs/benchmarking.md

@@ -18,8 +18,8 @@ Outputs:
 - `benchmarks/reports/latest.md`
 - `.soturail/bench/latest.json`
 - `.soturail/bench/latest.md`
-- versioned reports such as `benchmarks/reports/bench-v1.0.0.json`
-- versioned reports such as `benchmarks/reports/bench-v1.0.0.md`
+- versioned reports such as `benchmarks/reports/bench-v<version>.json`
+- versioned reports such as `benchmarks/reports/bench-v<version>.md`
 
 The suite currently groups results as:
 

package/docs/conductor-mode.md

@@ -0,0 +1,44 @@
+# SotuRail Conductor Mode
+
+Status: **Proposed future optional mode. Not implemented in v1.2.0.**
+
+SotuRail Core remains the CLI-first, npm-first, local-first Context OS and harness layer. A future optional mode called **SotuRail Conductor** may coordinate planning, verification and documentation workflows without replacing agent hosts.
+
+```txt
+SotuRail
+|-- Core
+|   |-- context
+|   |-- memory
+|   |-- reports
+|   |-- workflows
+|   |-- evidence
+|   |-- host exports
+|   `-- dashboard
+`-- Future optional Conductor mode
+    |-- planner
+    |-- verifier
+    |-- reviewer
+    |-- tasklet runner
+    |-- evidence collector
+    `-- approval gate
+```
+
+## Proposed Commands
+
+These commands are documentation-only and do not currently exist:
+
+```bash
+soturail conductor plan
+soturail conductor audit
+soturail conductor propose
+soturail conductor verify
+soturail conductor apply --approved
+```
+
+## Safe Capability Boundary
+
+A future Conductor may read a repository, create plans and tasklets, generate reports, validate links, compare host exports and propose patches. Applying a patch must require explicit approval.
+
+It must not become a chat product, unbounded fix-everything loop, central shell agent, browser agent, cloud agent or provider-specific runtime.
+
+See [Security Boundaries](security-boundaries.md), [Harness Lifecycle Rail](harness-lifecycle-rail.md) and [Future Rails Index](future-rails-index.md).

package/docs/context-packs.md

@@ -266,6 +266,12 @@ Possible future diagram context:
 
 See [diagram-rail.md](diagram-rail.md).
 
+## Lifecycle And Context Budget
+
+Harness Lifecycle handoffs should stay bounded. Prefer the active objective, feature state, changed-file names, verification status, blockers and next commands over copying full session history.
+
+Hermes-style trajectory compression is useful inspiration only when raw evidence remains recoverable. Odysseus-style workspace breadth should not cause every local artifact to enter every context pack. Use `context budget`, role packs, offload pointers and host-specific exports to keep handoffs focused.
+
 ## Quality Rules
 
 Context selection, formatting and role packs should preserve:
@@ -280,3 +286,15 @@ Context selection, formatting and role packs should preserve:
 - raw recovery hints.
 
 If pruning or formatting would remove required evidence, SotuRail should report that pruning was not effective rather than pretending the context is sufficient.
+
+## Related Context Routing And Knowledge Docs
+
+Context Packs connect directly to the newer knowledge and host-routing plans:
+
+- [`knowledge-rail.md`](knowledge-rail.md): compile docs/specs/notes into on-demand topic packs instead of loading everything into one prompt.
+- [`host-router-rail.md`](host-router-rail.md): translate one local context source into host-specific exports for Claude, Codex, Cursor, OpenCode, Gemini and generic Markdown.
+- [`tasklet-rail.md`](tasklet-rail.md): attach a small task template to a minimal context pack.
+- [`resilience-rail.md`](resilience-rail.md): warn when a context pack implies expensive, provider-dependent or long-running workflows.
+- [`agent-qa-rail.md`](agent-qa-rail.md): test whether compact/role-specific context packs preserve required facts.
+
+The key rule is progressive disclosure: SotuRail should send the smallest useful context first and keep large raw evidence recoverable by path, id or offload pointer.

package/docs/dashboard-rail.md

@@ -4,6 +4,12 @@ v1.0.0 keeps the dashboard static and local. There is no server requirement, no
 
 Dashboard Rail builds a static local HTML dashboard from report and status artifacts.
 
+## Lifecycle Cards
+
+Odysseus-style local workspace organization is useful dashboard inspiration, but SotuRail remains static and server-free by default. Future dashboard polish may surface bounded cards for Context Packs, Memory, Reports, Evidence, Workflows, Host Compatibility, Skills, Tasklets and Handoffs from existing local artifacts.
+
+Harness Lifecycle state is currently available under `.soturail/state/`; dedicated dashboard cards remain planned.
+
 ```bash
 soturail dashboard build
 soturail dashboard open