soturail 1.2.0 → 1.4.0

package/dist/core/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/sync-version.mjs from package.json. Do not edit manually.
-export const SOTURAIL_VERSION = "1.2.0";
+export const SOTURAIL_VERSION = "1.4.0";
 //# sourceMappingURL=version.js.map

package/docs/README.md

@@ -0,0 +1,53 @@
+# SotuRail Documentation
+
+SotuRail documentation is organized by task and rail. Start with the [Quickstart](getting-started/quickstart.md), then open only the sections relevant to the current work.
+
+## Getting Started
+
+- [All Getting Started Docs](getting-started/)
+- [Quickstart](getting-started/quickstart.md)
+- [Usage](getting-started/usage.md)
+- [First Real Workflow](getting-started/first-real-workflow.md)
+- [Windows](getting-started/windows.md)
+- [Migration To v1](getting-started/migration-v1.md)
+
+## Stable Rails
+
+- [Context And Memory](rails/context/)
+- [Harness And Workflow](rails/harness/)
+- [Knowledge](rails/knowledge/)
+- [Evidence And Reports](rails/evidence/)
+- [Evaluation And Agent QA](rails/evaluation/)
+- [Skills](rails/skills/)
+- [Tasklets](rails/tasklets/)
+- [Agent Hosts And MCP](rails/hosts/)
+- [Governance And Policy](rails/governance/)
+- [Spec, Design And Diagram](rails/design/)
+
+## Reference
+
+- [All Reference Docs](reference/)
+- [Stable Command Surface](reference/commands/stable-command-surface.md)
+- [v1.4 Commands](reference/commands/v1.4-commands.md)
+- [Schema Contracts](reference/schemas/schema-contracts.md)
+- [v1 Contract](reference/contracts/v1-contract.md)
+- [Architecture](architecture/)
+- [Security](security/)
+
+## Planning And Ecosystem
+
+- [All Roadmap Docs](roadmap/)
+- [Roadmap Index](roadmap/future-rails-index.md)
+- [Ecosystem Influences](ecosystem/ecosystem-influences.md)
+- [Agent And Harness Synthesis](ecosystem/agent-harness-synthesis-2026.md)
+- [Release Notes](releases/)
+
+## Additional Material
+
+- [Tutorials](tutorials/)
+- [Examples](examples/)
+- [Hook Examples](hooks/)
+- [Portuguese Docs](pt-BR/)
+- [Documentation Assets](assets/)
+
+SotuRail documentation describes implemented and planned surfaces explicitly. Proposed commands are not stable contracts until implemented and tested.

package/docs/{observability-rail.md → architecture/observability-rail.md}

@@ -57,10 +57,10 @@ The first implementation can remain local artifacts and dashboard cards. A live
 
 Observability Rail is the local timeline layer that feeds several planned rails:
 
-- [`agent-qa-rail.md`](agent-qa-rail.md) defines eval runs, scores and regression artifacts that can become observability events.
-- [`evidence-provenance-rail.md`](evidence-provenance-rail.md) defines verification status and provenance sidecars that reports and timelines should surface.
-- [`agent-governance-rail.md`](agent-governance-rail.md) extends observability into trace, ledger, experiment and approval records.
-- [`resilience-rail.md`](resilience-rail.md) adds rate-limit/fallback/provider-risk warnings as local events, not cloud telemetry.
+- [`agent-qa-rail.md`](../rails/evaluation/agent-qa-rail.md) defines eval runs, scores and regression artifacts that can become observability events.
+- [`evidence-provenance-rail.md`](../rails/evidence/evidence-provenance-rail.md) defines verification status and provenance sidecars that reports and timelines should surface.
+- [`agent-governance-rail.md`](../rails/governance/agent-governance-rail.md) extends observability into trace, ledger, experiment and approval records.
+- [`resilience-rail.md`](../rails/governance/resilience-rail.md) adds rate-limit/fallback/provider-risk warnings as local events, not cloud telemetry.
 
 This keeps the boundary clear: SotuRail observes local artifacts and user-approved records; it does not upload traces or become a hosted LangFuse/OpenTelemetry replacement by default.
 
@@ -71,4 +71,4 @@ Hermes-style trajectory compression and Odysseus-style visual workspaces reinfor
 - keep observability as local, recoverable evidence rather than uploaded telemetry;
 - present Context Packs, Memory, Reports, Evidence, Workflows, Host Compatibility, Skills, lifecycle state and Handoffs as bounded dashboard/report sections.
 
-SotuRail does not add a required server, chat workspace or central shell interface. See [Security Boundaries](security-boundaries.md).
+SotuRail does not add a required server, chat workspace or central shell interface. See [Security Boundaries](../security/security-boundaries.md).

package/docs/{agent-harness-synthesis-2026.md → ecosystem/agent-harness-synthesis-2026.md}

@@ -92,10 +92,10 @@ v1.2.0 implements Harness Lifecycle Rail for local state, audits, feature tracki
 ```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.3.0  Absorbed into v1.4.0
+v1.4.0  Knowledge, Evidence, Evaluation, Skills and Tasklets
 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).
+v1.4.0 implements the local Knowledge, Evidence, Agent QA, Skill Rail 2.0 and dry-run Tasklet surfaces. The exact command names for later governance and Conductor work are not frozen. Related: [Ecosystem Influences](ecosystem-influences.md), [External Projects Audit](external-projects-audit.md), [Harness Lifecycle Rail](../rails/harness/harness-lifecycle-rail.md), [Security Boundaries](../security/security-boundaries.md).

package/docs/{conductor-mode.md → ecosystem/conductor-mode.md}

@@ -1,6 +1,6 @@
 # SotuRail Conductor Mode
 
-Status: **Proposed future optional mode. Not implemented in v1.2.0.**
+Status: **Proposed future optional mode. Not implemented in v1.4.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.
 
@@ -37,8 +37,8 @@ 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.
+A future Conductor may read a repository, create plans and use the implemented dry-run tasklet templates, 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).
+See [Security Boundaries](../security/security-boundaries.md), [Harness Lifecycle Rail](../rails/harness/harness-lifecycle-rail.md) and [Future Rails Index](../roadmap/future-rails-index.md).

package/docs/{ecosystem-influences.md → ecosystem/ecosystem-influences.md}

@@ -70,7 +70,7 @@ SotuRail = local context, harness, evidence, policy and host handoff layer.
 
 Hermes contributes useful inspiration for trajectory compression, session search, toolset profiles, skills and subagent role packs. Odysseus contributes useful inspiration for local dashboard cards, host fit checks, visual evidence reports and privacy/security documentation.
 
-SotuRail does not copy their runtime, chat UI, model serving, local-service stack or central shell behavior. See [`agent-harness-synthesis-2026.md`](agent-harness-synthesis-2026.md), [`security-boundaries.md`](security-boundaries.md) and [`conductor-mode.md`](conductor-mode.md).
+SotuRail does not copy their runtime, chat UI, model serving, local-service stack or central shell behavior. See [`agent-harness-synthesis-2026.md`](agent-harness-synthesis-2026.md), [`security-boundaries.md`](../security/security-boundaries.md) and [`conductor-mode.md`](conductor-mode.md).
 
 ## 2026 Agent Runtime Update
 
@@ -83,7 +83,7 @@ agent host = model + planning loop + editing/runtime surface
 SotuRail = local context + rules + budget + skills + workspace + harness evidence + safety reports
 ```
 
-See [`roadmap-agent-runtime-addendum.md`](roadmap-agent-runtime-addendum.md) for the updated rail plan.
+See [`roadmap-agent-runtime-addendum.md`](../roadmap/roadmap-agent-runtime-addendum.md) for the updated rail plan.
 
 ### Host-Aware Agent Runtime Patterns
 
@@ -308,7 +308,7 @@ Where it maps:
 - `trace`
 - `report`
 
-See [deep-agents-patterns.md](deep-agents-patterns.md).
+See [deep-agents-patterns.md](../rails/hosts/deep-agents-patterns.md).
 
 ## Claude Code, AGENTS.md And Minimal Context Hygiene
 
@@ -525,15 +525,15 @@ The reviewed materials are now mapped into SotuRail planning as follows:
 
 | Source idea | SotuRail docs now covering it |
 | --- | --- |
-| QA agent with tests, datasets, CI and traces | [`agent-qa-rail.md`](agent-qa-rail.md), [`eval-datasets.md`](eval-datasets.md), [`golden-agent-tests.md`](golden-agent-tests.md), [`llm-as-judge-policy.md`](llm-as-judge-policy.md) |
-| CrewAI/LiteLLM-style roles, fallback and rate limits | [`multi-agent-workflow-templates.md`](multi-agent-workflow-templates.md), [`resilience-rail.md`](resilience-rail.md), [`rate-limit-and-fallback-policy.md`](rate-limit-and-fallback-policy.md) |
-| Validate -> fix -> verify -> report agent pipeline | [`observability-rail.md`](observability-rail.md), [`workflow-rail.md`](workflow-rail.md), [`examples/workflows/agent-pipeline-workflow.md`](../examples/workflows/agent-pipeline-workflow.md) |
-| OpenTracy-style trace, ledger, approval and experiments | [`agent-governance-rail.md`](agent-governance-rail.md), [`evidence-provenance-rail.md`](evidence-provenance-rail.md) |
-| Harness engineering lifecycle | [`harness-lifecycle-rail.md`](harness-lifecycle-rail.md), [`harness-rail.md`](harness-rail.md), [`workflow-rail.md`](workflow-rail.md) |
-| ECC-style cross-host harness, doctor, audit and skills | [`host-compatibility-rail.md`](host-compatibility-rail.md), [`agent-hosts.md`](agent-hosts.md), [`skill-rail-2.md`](skill-rail-2.md), [`future-rails-index.md`](future-rails-index.md) |
-| Feynman-style provenance and verifier status | [`evidence-provenance-rail.md`](evidence-provenance-rail.md), [`report-rail.md`](report-rail.md) |
-| book-to-skill-style document-to-skill packs | [`knowledge-rail.md`](knowledge-rail.md), [`skill-rail-2.md`](skill-rail-2.md), [`context-packs.md`](context-packs.md) |
-| Tasklet-style small reusable task blocks | [`tasklet-rail.md`](tasklet-rail.md), [`workflow-rail.md`](workflow-rail.md) |
-| 9Router-style router metaphor and token/context savings | [`host-router-rail.md`](host-router-rail.md), [`context-packs.md`](context-packs.md), [`governance-cost-rail.md`](governance-cost-rail.md) |
+| QA agent with tests, datasets, CI and traces | [`agent-qa-rail.md`](../rails/evaluation/agent-qa-rail.md), [`eval-datasets.md`](../rails/evaluation/eval-datasets.md), [`golden-agent-tests.md`](../rails/evaluation/golden-agent-tests.md), [`llm-as-judge-policy.md`](../rails/evaluation/llm-as-judge-policy.md) |
+| CrewAI/LiteLLM-style roles, fallback and rate limits | [`multi-agent-workflow-templates.md`](../rails/tasklets/multi-agent-workflow-templates.md), [`resilience-rail.md`](../rails/governance/resilience-rail.md), [`rate-limit-and-fallback-policy.md`](../rails/governance/rate-limit-and-fallback-policy.md) |
+| Validate -> fix -> verify -> report agent pipeline | [`observability-rail.md`](../architecture/observability-rail.md), [`workflow-rail.md`](../rails/harness/workflow-rail.md), [`examples/workflows/agent-pipeline-workflow.md`](../../examples/workflows/agent-pipeline-workflow.md) |
+| OpenTracy-style trace, ledger, approval and experiments | [`agent-governance-rail.md`](../rails/governance/agent-governance-rail.md), [`evidence-provenance-rail.md`](../rails/evidence/evidence-provenance-rail.md) |
+| Harness engineering lifecycle | [`harness-lifecycle-rail.md`](../rails/harness/harness-lifecycle-rail.md), [`harness-rail.md`](../rails/harness/harness-rail.md), [`workflow-rail.md`](../rails/harness/workflow-rail.md) |
+| ECC-style cross-host harness, doctor, audit and skills | [`host-compatibility-rail.md`](../rails/hosts/host-compatibility-rail.md), [`agent-hosts.md`](../rails/hosts/agent-hosts.md), [`skill-rail-2.md`](../rails/skills/skill-rail-2.md), [`future-rails-index.md`](../roadmap/future-rails-index.md) |
+| Feynman-style provenance and verifier status | [`evidence-provenance-rail.md`](../rails/evidence/evidence-provenance-rail.md), [`report-rail.md`](../rails/evidence/report-rail.md) |
+| book-to-skill-style document-to-skill packs | [`knowledge-rail.md`](../rails/knowledge/knowledge-rail.md), [`skill-rail-2.md`](../rails/skills/skill-rail-2.md), [`context-packs.md`](../rails/context/context-packs.md) |
+| Tasklet-style small reusable task blocks | [`tasklet-rail.md`](../rails/tasklets/tasklet-rail.md), [`workflow-rail.md`](../rails/harness/workflow-rail.md) |
+| 9Router-style router metaphor and token/context savings | [`host-router-rail.md`](../rails/hosts/host-router-rail.md), [`context-packs.md`](../rails/context/context-packs.md), [`governance-cost-rail.md`](../rails/governance/governance-cost-rail.md) |
 
 This checklist is intentionally documentation-only. Runtime implementation should happen gradually through roadmap milestones and tests.

package/docs/{external-projects-audit.md → ecosystem/external-projects-audit.md}

@@ -38,7 +38,7 @@ Hermes is an agent runtime. Odysseus is a workspace plus runtime and local-servi
 
 Useful patterns include trajectory compression, session search, toolset profiles, role packs, local dashboard cards, visual evidence and explicit privacy boundaries. Model serving, mandatory web UI, central shell access and bundled personal productivity services remain outside SotuRail scope.
 
-See [Agent And Harness Synthesis 2026](agent-harness-synthesis-2026.md) and [Security Boundaries](security-boundaries.md).
+See [Agent And Harness Synthesis 2026](agent-harness-synthesis-2026.md) and [Security Boundaries](../security/security-boundaries.md).
 
 ### 1. Host compatibility without becoming a host
 

package/docs/{migration-v1.md → getting-started/migration-v1.md}

@@ -29,7 +29,7 @@ This guide prepares SotuRail users and agents for the v1.0 stable local Context
 
 ## Stable Surface
 
-See [stable-command-surface.md](stable-command-surface.md). v1.0 freezes the documented stable surface, not every experimental seed.
+See [stable-command-surface.md](../reference/commands/stable-command-surface.md). v1.0 freezes the documented stable surface, not every experimental seed.
 
 ## Experimental Commands
 

package/docs/{context-intelligence.md → rails/context/context-intelligence.md}

@@ -62,23 +62,23 @@ SotuRail context select
 query: release checklist
 items_count: 4
 
-- file: docs/release-workflow.md
+- file: docs/reference/commands/release-workflow.md
   Score: 10
   Reason: keyword overlap, release path
   Estimated tokens: 520
   Summary: Release verification and publish ordering.
-  Recovery: open docs/release-workflow.md
+  Recovery: open docs/reference/commands/release-workflow.md
 ```
 
 `context prune` separates what fits from what was omitted:
 
 ```txt
 Included context:
-- file: docs/memory-rail.md (440 tokens)
+- file: docs/rails/context/memory-rail.md (440 tokens)
   Reason: keyword overlap
 
 Omitted context:
-- file: docs/evaluation-suite.md (1600 tokens)
+- file: docs/rails/evaluation/evaluation-suite.md (1600 tokens)
   Recovery: rerun with a larger --budget or offload the file.
 ```
 

package/docs/{context-packs.md → rails/context/context-packs.md}

@@ -177,7 +177,7 @@ v0.5.1 includes a light local seed:
 
 ```bash
 soturail validate json config.json --strict
-soturail format compare docs/usage.md
+soturail format compare docs/getting-started/usage.md
 ```
 
 The validator should warn about:
@@ -264,7 +264,7 @@ Possible future diagram context:
 - context router diagram;
 - feature `.spec.md` Mermaid diagram.
 
-See [diagram-rail.md](diagram-rail.md).
+See [diagram-rail.md](../design/diagram-rail.md).
 
 ## Lifecycle And Context Budget
 
@@ -291,10 +291,10 @@ If pruning or formatting would remove required evidence, SotuRail should report
 
 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.
+- [`knowledge-rail.md`](../knowledge/knowledge-rail.md): compile docs/specs/notes into on-demand topic packs instead of loading everything into one prompt.
+- [`host-router-rail.md`](../hosts/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`](../tasklets/tasklet-rail.md): attach a small task template to a minimal context pack.
+- [`resilience-rail.md`](../governance/resilience-rail.md): warn when a context pack implies expensive, provider-dependent or long-running workflows.
+- [`agent-qa-rail.md`](../evaluation/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/{memory-rail.md → rails/context/memory-rail.md}

@@ -28,7 +28,7 @@ Default principles:
 ```bash
 soturail memory remember "Decision: keep MCP read-only by default" --tag architecture --source manual
 soturail memory recall "npm release policy" --limit 5
-soturail memory capture --from-file docs/release-workflow.md
+soturail memory capture --from-file docs/reference/commands/release-workflow.md
 soturail memory consolidate
 soturail memory doctor
 soturail memory approve <id>
@@ -68,7 +68,7 @@ Matches:
 - mem_001 [score 8.00]
   Text: Never create GitHub release before npm publish succeeds.
   Reason: exact text match, keyword overlap
-  Source: docs/release-workflow.md
+  Source: docs/reference/commands/release-workflow.md
   Tags: release
   Confidence/privacy: medium / normal
 ```

package/docs/{structured-payload-rail.md → rails/context/structured-payload-rail.md}

@@ -41,7 +41,7 @@ v0.5.1 adds a light local validator and a format comparison seed:
 
 ```bash
 soturail validate json config.json --strict
-soturail format compare docs/usage.md
+soturail format compare docs/getting-started/usage.md
 ```
 
 The strict JSON validator warns about:
@@ -132,7 +132,7 @@ Call this `tagged context` or `XML-like tagged context`, not mandatory XML.
 Tagged blocks are useful when an LLM needs long prompt context with clear boundaries:
 
 ```xml
-<release_evidence source="docs/release-workflow.md">
+<release_evidence source="docs/reference/commands/release-workflow.md">
   npm publish must finish before the GitHub release is created.
 </release_evidence>
 ```
@@ -209,7 +209,7 @@ Additional host guidance:
 `soturail format compare <file>` gives a local, approximate first pass:
 
 ```bash
-soturail format compare docs/usage.md
+soturail format compare docs/getting-started/usage.md
 ```
 
 The report includes:

package/docs/{spec-driven-workflow.md → rails/design/spec-driven-workflow.md}

@@ -59,4 +59,4 @@ A diagram should not replace tests or reviews. It should make the intended behav
 
 The validator is intentionally lightweight. It is useful as a local rail, not as a full Mermaid parser.
 
-See [diagram-rail.md](diagram-rail.md) and [workflow-rail.md](workflow-rail.md).
+See [diagram-rail.md](diagram-rail.md) and [workflow-rail.md](../harness/workflow-rail.md).

package/docs/rails/evaluation/agent-qa-rail.md

@@ -0,0 +1,34 @@
+# Agent QA Rail
+
+Agent QA Rail tests SotuRail-generated agent artifacts with deterministic local fixtures.
+
+## Commands
+
+```bash
+soturail eval dataset init
+soturail eval dataset run
+soturail eval golden
+soturail eval regression
+soturail eval report
+```
+
+Artifacts are written under `.soturail/evals/`.
+
+## Golden Checks
+
+The default checks verify that:
+
+- host exports are non-empty and preserve SotuRail identity;
+- exports avoid unrelated product or autonomous-runtime claims;
+- knowledge packs include metadata and source maps;
+- evidence reports do not claim unsupported verification;
+- skills expose reviewed safety information;
+- tasklets remain dry-run templates.
+
+## Policy
+
+Default Agent QA is offline, deterministic, provider-agnostic and safe for CI. Provider-backed LLM-as-judge evaluation remains optional and documentation-only; it is not a default release gate.
+
+Passing these checks proves the local contracts were met. It does not prove every external agent will behave correctly.
+
+Related: [Evaluation Suite](evaluation-suite.md), [Golden Agent Tests](golden-agent-tests.md), [Evidence Provenance Rail](../evidence/evidence-provenance-rail.md).

package/docs/{benchmarking.md → rails/evaluation/benchmarking.md}

@@ -118,7 +118,7 @@ workflow-evidence
 
 Candidate native hot paths may include large JSONL scans, rangeHash computation, source-range relocation and duplicate claim clustering. Agent brief rendering and release preflight are not native candidates until local evidence proves a bottleneck.
 
-See [native-performance-policy.md](native-performance-policy.md).
+See [native-performance-policy.md](../governance/native-performance-policy.md).
 
 ## Evaluation Suite
 

package/docs/rails/evidence/evidence-provenance-rail.md

@@ -0,0 +1,41 @@
+# Evidence And Provenance Rail
+
+Evidence And Provenance Rail records what local artifacts support a report and what remains uncertain.
+
+## Commands
+
+```bash
+soturail evidence collect
+soturail evidence verify
+soturail evidence report
+```
+
+Each run writes:
+
+```txt
+.soturail/evidence/<run-id>/
+  evidence.json
+  report.md
+  provenance.md
+```
+
+## Status Model
+
+| Status | Meaning |
+| --- | --- |
+| `verified` | Backed by a locally recorded check or direct local evidence |
+| `unverified` | No sufficient proof is available |
+| `blocked` | Verification cannot proceed because evidence is missing or failed |
+| `inferred` | Derived from local artifacts but not directly proven |
+
+Collection reads knowledge source maps, local report artifacts and read-only `git status --short`. Verification checks recorded source paths without executing commands. Reports explicitly state that unsupported verification is not claimed.
+
+## Safety Boundary
+
+- No private shell history is collected.
+- No verification command is silently executed.
+- No cloud evidence store or telemetry upload.
+- Missing proof remains unverified, inferred or blocked.
+- Provenance files must not expose secrets.
+
+Related: [Report Rail](report-rail.md), [Knowledge Rail](../knowledge/knowledge-rail.md), [Security Boundaries](../../security/security-boundaries.md).

package/docs/{report-rail.md → rails/evidence/report-rail.md}

@@ -60,9 +60,9 @@ soturail brain consolidate --dry-run
 Report Rail is the parent surface where several future rails should become visible:
 
 - [`evidence-provenance-rail.md`](evidence-provenance-rail.md): report sidecars, source paths and `verified` / `unverified` / `blocked` / `inferred` statuses.
-- [`agent-qa-rail.md`](agent-qa-rail.md): dataset runs, golden export checks and regression summaries.
-- [`golden-agent-tests.md`](golden-agent-tests.md): deterministic host-export checks that can be summarized in reports.
-- [`agent-governance-rail.md`](agent-governance-rail.md): trace, ledger, approval and experiment status.
-- [`host-router-rail.md`](host-router-rail.md): context-format fallback decisions per host.
+- [`agent-qa-rail.md`](../evaluation/agent-qa-rail.md): dataset runs, golden export checks and regression summaries.
+- [`golden-agent-tests.md`](../evaluation/golden-agent-tests.md): deterministic host-export checks that can be summarized in reports.
+- [`agent-governance-rail.md`](../governance/agent-governance-rail.md): trace, ledger, approval and experiment status.
+- [`host-router-rail.md`](../hosts/host-router-rail.md): context-format fallback decisions per host.
 
 A future report should not simply say an agent task is complete. It should say what evidence exists, what was checked, what is still inferred or blocked and which safe next command can improve confidence.

package/docs/{governance-cost-rail.md → rails/governance/governance-cost-rail.md}

@@ -86,6 +86,6 @@ Future v1.5 planning now includes Resilience Rail and Host Router Rail:
 
 - [`resilience-rail.md`](resilience-rail.md) for retry/fallback/rate-limit documentation and risk reports;
 - [`rate-limit-and-fallback-policy.md`](rate-limit-and-fallback-policy.md) for local policy shape;
-- [`host-router-rail.md`](host-router-rail.md) for context-format routing across hosts.
+- [`host-router-rail.md`](../hosts/host-router-rail.md) for context-format routing across hosts.
 
 This does not turn SotuRail into a model proxy, account manager, MITM bridge or billing gateway.

package/docs/{rules.md → rails/governance/rules.md}

@@ -81,7 +81,7 @@ Examples:
 - missing tests before release becomes an evidence-pack requirement;
 - repeated agent misunderstanding becomes a workflow or agent-doc lint rule.
 
-See [harness-rail.md](harness-rail.md).
+See [harness-rail.md](../harness/harness-rail.md).
 
 ## Planned Structured Payload Rules
 
@@ -97,4 +97,4 @@ Possible future checks:
 - malformed tagged context block;
 - invalid Mermaid block in a `.spec.md` file.
 
-See [structured-payload-rail.md](structured-payload-rail.md) and [diagram-rail.md](diagram-rail.md).
+See [structured-payload-rail.md](../context/structured-payload-rail.md) and [diagram-rail.md](../design/diagram-rail.md).

package/docs/{harness-lifecycle-rail.md → rails/harness/harness-lifecycle-rail.md}

@@ -79,7 +79,7 @@ Root agent docs should stay short and point to specialized docs.
 Read first: .soturail/harness/AGENTS.md
 If editing tests: .soturail/harness/verification.md
 If continuing work: .soturail/state/session-handoff.md
-If preparing release: docs/release-workflow.md
+If preparing release: docs/reference/commands/release-workflow.md
 ```
 
 ## Planned Extensions
@@ -92,4 +92,4 @@ Commands such as `harness benchmark`, `session verify` and a dedicated `session
 - No cloud telemetry, mandatory server or LLM API key is required.
 - No destructive MCP tool or arbitrary MCP shell execution is added.
 - No Claude-only harness, giant root instruction file or acceptance without evidence.
-- See [Security Boundaries](security-boundaries.md), [Harness Rail](harness-rail.md), [Conductor Mode](conductor-mode.md) and [Agent Harness Synthesis](agent-harness-synthesis-2026.md).
+- See [Security Boundaries](../../security/security-boundaries.md), [Harness Rail](harness-rail.md), [Conductor Mode](../../ecosystem/conductor-mode.md) and [Agent Harness Synthesis](../../ecosystem/agent-harness-synthesis-2026.md).

package/docs/{harness-rail.md → rails/harness/harness-rail.md}

@@ -34,7 +34,7 @@ soturail workflow evidence <id>
 
 Harness Lifecycle Rail adds safe project-local state for instructions, scope, verification, sessions, handoffs and features. `harness init` preserves existing files by default, and `harness audit` scores lifecycle readiness without executing verification commands.
 
-See [Harness Lifecycle Rail](harness-lifecycle-rail.md) and [Security Boundaries](security-boundaries.md).
+See [Harness Lifecycle Rail](harness-lifecycle-rail.md) and [Security Boundaries](../../security/security-boundaries.md).
 
 ## v0.7.0 Workflow Connection
 

package/docs/{workflow-rail.md → rails/harness/workflow-rail.md}

@@ -201,9 +201,9 @@ These are still local artifacts. Workflow evidence does not upload telemetry and
 Workflow Rail is the natural parent for the newer harness/session/task planning docs:
 
 - [`harness-lifecycle-rail.md`](harness-lifecycle-rail.md): instructions, state, verification, scope and session handoff.
-- [`multi-agent-workflow-templates.md`](multi-agent-workflow-templates.md): researcher, analyst, writer, verifier and reviewer role-pack templates.
-- [`evidence-provenance-rail.md`](evidence-provenance-rail.md): workflow evidence sidecars and verification status.
-- [`agent-governance-rail.md`](agent-governance-rail.md): trace, ledger and approval records for long-running workflows.
-- [`resilience-rail.md`](resilience-rail.md): retry/fallback/rate-limit policy notes for workflows that depend on external agent/model providers.
+- [`multi-agent-workflow-templates.md`](../tasklets/multi-agent-workflow-templates.md): researcher, analyst, writer, verifier and reviewer role-pack templates.
+- [`evidence-provenance-rail.md`](../evidence/evidence-provenance-rail.md): workflow evidence sidecars and verification status.
+- [`agent-governance-rail.md`](../governance/agent-governance-rail.md): trace, ledger and approval records for long-running workflows.
+- [`resilience-rail.md`](../governance/resilience-rail.md): retry/fallback/rate-limit policy notes for workflows that depend on external agent/model providers.
 
 These docs should keep SotuRail as the workflow/handoff/evidence layer. They should not turn it into a CrewAI, LangGraph or autonomous agent runtime.

package/docs/{agent-docs-hygiene.md → rails/hosts/agent-docs-hygiene.md}

@@ -115,7 +115,7 @@ Use safe local commands:
 - npm run build
 - npx vitest run tests/v050.test.ts
 
-For richer context, run `soturail context select --query "<task>"` or read `docs/context-intelligence.md`.
+For richer context, run `soturail context select --query "<task>"` or read `docs/rails/context/context-intelligence.md`.
 Do not expose secrets, publish packages or create GitHub releases without explicit human approval.
 ```
 

package/docs/{agent-hosts.md → rails/hosts/agent-hosts.md}

@@ -35,7 +35,7 @@ soturail mcp resources host-manifest --host codex
 
 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).
+See [host-matrix-schema.md](../../reference/schemas/host-matrix-schema.md), [agent-export-contract.md](../../reference/contracts/agent-export-contract.md) and [mcp-host-manifest.md](mcp-host-manifest.md).
 
 ## Related Host Router And Resilience Docs
 
@@ -43,8 +43,8 @@ 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.
+- [`rate-limit-and-fallback-policy.md`](../governance/rate-limit-and-fallback-policy.md): local documentation shape for retry/fallback/rate-limit expectations.
+- [`resilience-rail.md`](../governance/resilience-rail.md): provider and workflow-risk warnings without proxying model traffic.
+- [`agent-qa-rail.md`](../evaluation/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/{agents.md → rails/hosts/agents.md}

@@ -162,7 +162,7 @@ MCP -> JSON only
 Generic -> Markdown
 ```
 
-See [structured-payload-rail.md](structured-payload-rail.md).
+See [structured-payload-rail.md](../context/structured-payload-rail.md).
 
 ## Project Brain Briefs
 
@@ -189,15 +189,15 @@ v0.8.1 briefs are cleaner and safer:
 
 ## Tutorials
 
-- [SotuRail with Claude Code](tutorial-claude-code.md)
-- [SotuRail with Codex](tutorial-codex.md)
-- [SotuRail with Gemini CLI](tutorial-gemini-cli.md)
-- [SotuRail with Cursor](tutorial-cursor.md)
-- [SotuRail with Antigravity prompt-only workflow](tutorial-antigravity.md)
-- [Deep Agents-style role packs](tutorial-deep-agents-role-packs.md)
-- [Harness-style setup/plan/work/review/release](tutorial-harness-workflow.md)
-- [Diagram Rail and `.spec.md` visual contracts](tutorial-diagram-spec.md)
-- [Choosing context formats by host](tutorial-context-formats.md)
+- [SotuRail with Claude Code](../../tutorials/tutorial-claude-code.md)
+- [SotuRail with Codex](../../tutorials/tutorial-codex.md)
+- [SotuRail with Gemini CLI](../../tutorials/tutorial-gemini-cli.md)
+- [SotuRail with Cursor](../../tutorials/tutorial-cursor.md)
+- [SotuRail with Antigravity prompt-only workflow](../../tutorials/tutorial-antigravity.md)
+- [Deep Agents-style role packs](../../tutorials/tutorial-deep-agents-role-packs.md)
+- [Harness-style setup/plan/work/review/release](../../tutorials/tutorial-harness-workflow.md)
+- [Diagram Rail and `.spec.md` visual contracts](../../tutorials/tutorial-diagram-spec.md)
+- [Choosing context formats by host](../../tutorials/tutorial-context-formats.md)
 
 ## Agent Docs Hygiene
 

package/docs/rails/knowledge/knowledge-rail.md

@@ -0,0 +1,49 @@
+# Knowledge Rail
+
+Knowledge Rail compiles local project sources into concise, source-backed knowledge packs for coding agents. It is deterministic, offline and does not require embeddings or an LLM.
+
+## Commands
+
+```bash
+soturail knowledge estimate README.md docs
+soturail knowledge compile README.md docs --name project-guide
+soturail knowledge update project-guide docs/new-guide.md
+soturail knowledge verify project-guide
+soturail knowledge list
+```
+
+## Local Layout
+
+```txt
+.soturail/knowledge/<name>/
+  SKILL.md
+  topics/
+  glossary.md
+  patterns.md
+  cheatsheet.md
+  metadata.json
+  source-map.json
+  verify.json
+```
+
+Compilation extracts headings, commands, terms, concise local summaries, file paths and source hashes. It does not copy large source bodies into generated files.
+
+## Verification
+
+`knowledge verify` compares current source hashes with `source-map.json`.
+
+- `verified`: required artifacts and source hashes match.
+- `stale`: a source changed or disappeared.
+- `unverified`: the pack or required artifacts are missing.
+
+`knowledge update` recompiles the pack while preserving its original creation date.
+
+## Safety And Limits
+
+- Sources must remain inside the project root.
+- Binary, generated and oversized files are skipped.
+- No cloud calls, embeddings, model calls or mandatory database.
+- Generated summaries are source signals, not stronger claims than the original files.
+- Knowledge Rail organizes source material; it does not replace Project Brain or a full static analyzer.
+
+Related: [Evidence Provenance Rail](../evidence/evidence-provenance-rail.md), [Skill Rail 2.0](../skills/skill-rail-2.md), [Security Boundaries](../../security/security-boundaries.md).