soturail 1.0.1 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/README.md +60 -13
  2. package/dist/cli.js +6 -0
  3. package/dist/cli.js.map +1 -1
  4. package/dist/commands/agents.js +37 -7
  5. package/dist/commands/agents.js.map +1 -1
  6. package/dist/commands/feature.d.ts +2 -0
  7. package/dist/commands/feature.js +28 -0
  8. package/dist/commands/feature.js.map +1 -0
  9. package/dist/commands/handoff.d.ts +2 -0
  10. package/dist/commands/handoff.js +14 -0
  11. package/dist/commands/handoff.js.map +1 -0
  12. package/dist/commands/harness.js +20 -0
  13. package/dist/commands/harness.js.map +1 -1
  14. package/dist/commands/mcp.js +10 -1
  15. package/dist/commands/mcp.js.map +1 -1
  16. package/dist/commands/report.js +14 -3
  17. package/dist/commands/report.js.map +1 -1
  18. package/dist/commands/session.d.ts +2 -0
  19. package/dist/commands/session.js +17 -0
  20. package/dist/commands/session.js.map +1 -0
  21. package/dist/core/agent-exporter.d.ts +39 -2
  22. package/dist/core/agent-exporter.js +290 -24
  23. package/dist/core/agent-exporter.js.map +1 -1
  24. package/dist/core/agent-profile.d.ts +1 -1
  25. package/dist/core/agent-registry.js +12 -0
  26. package/dist/core/agent-registry.js.map +1 -1
  27. package/dist/core/agent-runtime.d.ts +15 -1
  28. package/dist/core/agent-runtime.js +120 -14
  29. package/dist/core/agent-runtime.js.map +1 -1
  30. package/dist/core/code-health.js +3 -0
  31. package/dist/core/code-health.js.map +1 -1
  32. package/dist/core/config.d.ts +7 -0
  33. package/dist/core/config.js +8 -0
  34. package/dist/core/config.js.map +1 -1
  35. package/dist/core/harness-lifecycle.d.ts +63 -0
  36. package/dist/core/harness-lifecycle.js +397 -0
  37. package/dist/core/harness-lifecycle.js.map +1 -0
  38. package/dist/core/harness-rail.js +1 -0
  39. package/dist/core/harness-rail.js.map +1 -1
  40. package/dist/core/mcp-resources.d.ts +27 -0
  41. package/dist/core/mcp-resources.js +104 -1
  42. package/dist/core/mcp-resources.js.map +1 -1
  43. package/dist/core/release-preflight.js +3 -0
  44. package/dist/core/release-preflight.js.map +1 -1
  45. package/dist/core/report-rail.d.ts +1 -1
  46. package/dist/core/report-rail.js +33 -8
  47. package/dist/core/report-rail.js.map +1 -1
  48. package/dist/core/schema-readiness.js +12 -1
  49. package/dist/core/schema-readiness.js.map +1 -1
  50. package/dist/core/skill-schema.d.ts +2 -2
  51. package/dist/core/version.d.ts +1 -1
  52. package/dist/core/version.js +1 -1
  53. package/docs/agent-export-contract.md +42 -0
  54. package/docs/agent-governance-rail.md +89 -0
  55. package/docs/agent-harness-synthesis-2026.md +101 -0
  56. package/docs/agent-hosts.md +24 -5
  57. package/docs/agent-qa-rail.md +92 -0
  58. package/docs/agents.md +31 -12
  59. package/docs/assets/demos/README.md +3 -0
  60. package/docs/assets/screenshots/agents-matrix.svg +35 -0
  61. package/docs/assets/screenshots/host-doctor.svg +21 -0
  62. package/docs/assets/screenshots/status-json.svg +30 -0
  63. package/docs/benchmarking.md +2 -2
  64. package/docs/conductor-mode.md +44 -0
  65. package/docs/context-packs.md +18 -0
  66. package/docs/dashboard-rail.md +6 -0
  67. package/docs/ecosystem-influences.md +65 -0
  68. package/docs/eval-datasets.md +40 -0
  69. package/docs/evaluation-suite.md +6 -0
  70. package/docs/evidence-provenance-rail.md +70 -0
  71. package/docs/external-projects-audit.md +29 -0
  72. package/docs/future-rails-index.md +75 -17
  73. package/docs/golden-agent-tests.md +44 -0
  74. package/docs/governance-cost-rail.md +10 -0
  75. package/docs/harness-lifecycle-rail.md +95 -0
  76. package/docs/harness-rail.md +27 -0
  77. package/docs/host-compatibility-rail.md +30 -6
  78. package/docs/host-matrix-schema.md +43 -0
  79. package/docs/host-router-rail.md +73 -0
  80. package/docs/knowledge-rail.md +76 -0
  81. package/docs/llm-as-judge-policy.md +45 -0
  82. package/docs/mcp-host-manifest.md +33 -0
  83. package/docs/mcp-report-resources.md +9 -0
  84. package/docs/mcp.md +4 -0
  85. package/docs/media-guide.md +27 -0
  86. package/docs/multi-agent-workflow-templates.md +63 -0
  87. package/docs/observability-rail.md +36 -0
  88. package/docs/quickstart.md +1 -1
  89. package/docs/rate-limit-and-fallback-policy.md +45 -0
  90. package/docs/release-workflow.md +12 -1
  91. package/docs/releases/README.md +3 -0
  92. package/docs/releases/RELEASE_NOTES_v1.1.0.md +55 -0
  93. package/docs/releases/RELEASE_NOTES_v1.2.0.md +43 -0
  94. package/docs/repo-docs-audit-2026-06-05.md +55 -0
  95. package/docs/report-rail.md +12 -0
  96. package/docs/resilience-rail.md +48 -0
  97. package/docs/schema-contracts.md +20 -0
  98. package/docs/security-boundaries.md +34 -0
  99. package/docs/skill-rail-2.md +11 -0
  100. package/docs/stable-command-surface.md +16 -1
  101. package/docs/tasklet-rail.md +62 -0
  102. package/docs/tutorial-antigravity.md +7 -2
  103. package/docs/tutorial-deep-agents-role-packs.md +4 -0
  104. package/docs/tutorial-gemini-cli.md +4 -0
  105. package/docs/tutorial-opencode.md +37 -0
  106. package/docs/v1-contract.md +5 -3
  107. package/docs/workflow-rail.md +12 -0
  108. package/examples/agents/README.md +6 -1
  109. package/examples/agents/opencode.md +26 -0
  110. package/package.json +2 -2
@@ -1,6 +1,12 @@
1
1
  # Host Compatibility Rail
2
2
 
3
- Host Compatibility Rail is the planned v1.1.x direction for making SotuRail outputs useful across coding-agent hosts without becoming an agent host itself.
3
+ Host Compatibility Rail is the v1.1.0 direction for making SotuRail outputs useful across coding-agent hosts without becoming an agent host itself.
4
+
5
+ ## Host Fit
6
+
7
+ `soturail agents matrix`, `agents doctor --host <host>` and `agents doctor --all` form the current Host Fit Doctor surface. They report compatibility, export support, limitations and safe next commands without model serving or runtime installation.
8
+
9
+ Hermes and Odysseus are ecosystem influences, not direct stable host integrations. Hermes is an agent runtime and Odysseus is a broader workspace/runtime stack. Generic-compatible exports remain the safe fallback until a host-specific path is implemented and tested.
4
10
 
5
11
  ## Goal
6
12
 
@@ -17,22 +23,25 @@ Supported host families should be treated as runtime surfaces with different cap
17
23
  | --- | --- |
18
24
  | Claude / Claude Code-style | short `CLAUDE.md`, referenced docs, MCP/resource notes, report agent brief |
19
25
  | Codex-style | `AGENTS.md`-friendly Markdown, safe commands, report/status summaries |
20
- | OpenCode | OpenCode-friendly instructions, roles, skills, context packs and report briefs |
26
+ | OpenCode | generic-compatible `AGENTS.md`, context packs and report briefs |
21
27
  | Cursor | rules/context docs, dashboard/report references and safe workflow notes |
22
- | Antigravity-style | host-aware context packs, prompt-only fallback and migration notes from Gemini CLI-style usage |
23
- | Deep Agents-style | role packs, filesystem evidence, memory summaries and human approval notes |
24
- | Generic MCP host | read-only report/status/brain/bench/baseline manifests and exposure reports |
28
+ | Antigravity-style | high-priority experimental `AGENTS.md`, context pack and Gemini-to-Antigravity migration notes |
29
+ | Gemini legacy/compatible | AGENTS/GEMINI Markdown handoff for mixed host behavior |
30
+ | Deep Agents-style | role packs, subagent notes, filesystem evidence and human approval notes |
31
+ | Generic MCP host | read-only report/status/brain/bench/baseline/host manifests and exposure reports |
25
32
 
26
33
  ## Planned Commands
27
34
 
28
35
  ```bash
29
36
  soturail agents matrix
37
+ soturail agents matrix --json
30
38
  soturail agents doctor --host opencode
39
+ soturail agents doctor --all --json
31
40
  soturail agents export --agent opencode
32
41
  soturail agents export --agent antigravity
33
42
  soturail agents export --agent deepagents
34
43
  soturail agents export --agent generic
35
- soturail mcp resources host-manifest
44
+ soturail mcp resources host-manifest --host opencode
36
45
  ```
37
46
 
38
47
  ## Capability Matrix Fields
@@ -49,6 +58,7 @@ Each host entry should eventually report:
49
58
  - report/status format preference;
50
59
  - known limitations;
51
60
  - required human review.
61
+ - mutation allowed by default, which must remain `false`.
52
62
 
53
63
  ## Safety Defaults
54
64
 
@@ -58,6 +68,8 @@ Each host entry should eventually report:
58
68
  - Do not expose destructive MCP tools by default.
59
69
  - Do not claim first-class support until the export path has tests and docs.
60
70
  - Always keep a generic Markdown fallback.
71
+ - Keep `.soturail/raw` out of agent handoff files.
72
+ - Use `soturail agents doctor --host <host>` before copying exports into host-visible locations.
61
73
 
62
74
  ## Relationship To Existing Rails
63
75
 
@@ -70,3 +82,15 @@ Each host entry should eventually report:
70
82
  | Policy Rail | config write, hook and tool exposure checks |
71
83
  | Skill Rail | host-aware skill export without always loading every skill |
72
84
  | Workflow Rail | phase-specific host handoff |
85
+
86
+ ## Host Router Expansion
87
+
88
+ Future host work is tracked in [`host-router-rail.md`](host-router-rail.md).
89
+
90
+ The host-router idea means context-format routing, not model-request routing:
91
+
92
+ ```txt
93
+ one SotuRail context source -> Claude/Codex/Cursor/OpenCode/Gemini/generic exports
94
+ ```
95
+
96
+ SotuRail must not intercept IDE traffic, proxy provider requests, manage browser tokens or bypass quotas.
@@ -0,0 +1,43 @@
1
+ # Host Matrix Schema
2
+
3
+ SotuRail v1.1.0 keeps the v1 matrix artifact compatible with `soturail.agents.matrix.v1` and adds the v1.1 contract id:
4
+
5
+ ```json
6
+ {
7
+ "schemaVersion": "soturail.agents.matrix.v1",
8
+ "contractId": "soturail.agent-host-matrix.v1",
9
+ "createdAt": "ISO-8601",
10
+ "version": "1.1.0",
11
+ "status": "passed|warning|failed|unknown",
12
+ "hosts": []
13
+ }
14
+ ```
15
+
16
+ Each host row preserves the v1 fields (`host`, `id`, `status`, `exportSupport`, `reportAgentSupport`, `contextPackSupport`, `mcpResourcesSupport`, `installDryRunSupport`, `knownLimitations`, `recommendedCommand`) and adds host-compatibility fields:
17
+
18
+ - `displayName`
19
+ - `priority`
20
+ - `instructionFiles`
21
+ - `contextFormats`
22
+ - `reportFormats`
23
+ - `mcpSupport`
24
+ - `skillsSupport`
25
+ - `hooksSupport`
26
+ - `installSupport`
27
+ - `mutationAllowedByDefault`
28
+ - `recommendedCommands`
29
+ - `limitations`
30
+ - `policyNotes`
31
+
32
+ ## Statuses
33
+
34
+ - `stable`: covered by the local v1/v1.1 surface.
35
+ - `generic-compatible`: safe generic Markdown/context handoff, but not host-native integration.
36
+ - `legacy`: prompt/context compatibility for older or mixed host behavior.
37
+ - `experimental`: prompt-only, docs-only or role-pack-only until promoted.
38
+ - `planned`: documented future surface.
39
+ - `unknown`: not enough evidence.
40
+
41
+ ## Safety
42
+
43
+ `mutationAllowedByDefault` must be `false` for every host. The matrix must not claim destructive MCP tools, shell execution through MCP, cloud telemetry or autonomous editing behavior.
@@ -0,0 +1,73 @@
1
+ # Host Router Rail
2
+
3
+ Host Router Rail is a planned host/export layer inspired by router products, but it routes context formats, not model traffic.
4
+
5
+ ```txt
6
+ One SotuRail context source -> many host-specific exports.
7
+ ```
8
+
9
+ ## Goal
10
+
11
+ Generate the best safe local artifact for each host:
12
+
13
+ | Host | Example export |
14
+ | --- | --- |
15
+ | Claude Code | `CLAUDE.md`, skills guidance, MCP read-only manifest |
16
+ | Codex | `AGENTS.md`, instructions and safe command handoff |
17
+ | Cursor | `.cursor/rules` style prompt/rule files |
18
+ | OpenCode | OpenCode-compatible instructions and role packs |
19
+ | Gemini | `GEMINI.md` style guidance |
20
+ | generic | Markdown context pack and report bundle |
21
+
22
+ ## Proposed Commands
23
+
24
+ ```bash
25
+ soturail export all
26
+ soturail translate --to claude
27
+ soturail translate --to codex
28
+ soturail translate --to cursor
29
+ soturail hosts status
30
+ soturail doctor --hosts
31
+ soturail export --fallback
32
+ ```
33
+
34
+ ## Context Optimization
35
+
36
+ Host Router Rail should connect to context budgeting:
37
+
38
+ ```bash
39
+ soturail context optimize
40
+ soturail context budget
41
+ soturail context compact
42
+ ```
43
+
44
+ Potential outputs:
45
+
46
+ ```txt
47
+ .soturail/context/full.md
48
+ .soturail/context/compact.md
49
+ .soturail/context/ultra.md
50
+ .soturail/exports/claude/
51
+ .soturail/exports/codex/
52
+ .soturail/exports/cursor/
53
+ ```
54
+
55
+ ## Fallbacks
56
+
57
+ Fallback should mean safe format fallback, not provider or quota bypass:
58
+
59
+ - MCP unsupported -> static Markdown/resources;
60
+ - skills unsupported -> prompt-only instructions;
61
+ - huge context -> compact role pack;
62
+ - host unknown -> generic export.
63
+
64
+ ## Hard Boundary
65
+
66
+ SotuRail must not:
67
+
68
+ - intercept IDE traffic;
69
+ - proxy model requests;
70
+ - manage or rotate provider accounts;
71
+ - use browser cookies or session tokens;
72
+ - bypass quotas;
73
+ - promise unlimited free model access.
@@ -0,0 +1,76 @@
1
+ # Knowledge Rail
2
+
3
+ Knowledge Rail is a planned future surface for compiling project documentation into small, on-demand knowledge packs for coding agents.
4
+
5
+ It is inspired by document-to-skill workflows: extract structure, not a giant summary.
6
+
7
+ ## Goal
8
+
9
+ Turn docs, specs, READMEs, ADRs, notes and technical references into local agent-usable knowledge:
10
+
11
+ ```txt
12
+ source docs -> topic index -> SKILL.md -> topics -> glossary -> patterns -> cheatsheet -> provenance
13
+ ```
14
+
15
+ ## Proposed Commands
16
+
17
+ ```bash
18
+ soturail knowledge ingest ./docs ./README.md ./architecture.md
19
+ soturail knowledge estimate ./docs
20
+ soturail knowledge compile --mode on-demand
21
+ soturail knowledge update project-brain ./new-docs
22
+ soturail knowledge verify
23
+ soturail skill build ./docs --name project-architecture
24
+ soturail skill fold-in project-architecture ./ADR-004.md
25
+ soturail skill export --target claude
26
+ ```
27
+
28
+ ## Local Layout
29
+
30
+ ```txt
31
+ .soturail/knowledge/<name>/
32
+ SKILL.md
33
+ topics/
34
+ architecture.md
35
+ testing.md
36
+ release.md
37
+ glossary.md
38
+ patterns.md
39
+ cheatsheet.md
40
+ source-map.json
41
+ metadata.json
42
+ ```
43
+
44
+ ## On-Demand Context
45
+
46
+ Instead of loading all docs into every prompt, an export can say:
47
+
48
+ ```txt
49
+ Read .soturail/knowledge/project/SKILL.md first.
50
+ For release tasks, read topics/release.md.
51
+ For testing tasks, read topics/testing.md.
52
+ Do not load unrelated topics unless needed.
53
+ ```
54
+
55
+ ## Metadata
56
+
57
+ A knowledge pack should record:
58
+
59
+ - source paths;
60
+ - extraction date;
61
+ - token estimate;
62
+ - topic list;
63
+ - source map;
64
+ - verification status;
65
+ - update/fold-in history.
66
+
67
+ ## Copyright And Sharing Boundary
68
+
69
+ Knowledge packs generated from private or copyrighted material should stay local unless the user has rights to redistribute them. SotuRail should prefer synthesized structure and references over copying large source text.
70
+
71
+ ## Non-Goals
72
+
73
+ - no vector database required;
74
+ - no cloud embeddings required;
75
+ - no publishing third-party book content by default;
76
+ - no replacing Project Brain or Knowledge Graph Rail. Knowledge Rail feeds them with organized source material.
@@ -0,0 +1,45 @@
1
+ # LLM-As-Judge Policy
2
+
3
+ SotuRail may eventually support optional LLM-as-judge evaluations for hallucination, clarity and evidence quality. This document defines the boundary before that feature exists.
4
+
5
+ ## Default Policy
6
+
7
+ ```txt
8
+ No LLM-as-judge call is required for normal SotuRail development, testing or release.
9
+ ```
10
+
11
+ Default gates should be deterministic:
12
+
13
+ - schema validation;
14
+ - JSON parsing;
15
+ - keyword and section checks;
16
+ - file existence checks;
17
+ - redaction checks;
18
+ - golden output checks;
19
+ - snapshot diff checks;
20
+ - link/path checks where local.
21
+
22
+ ## Optional Judge Mode
23
+
24
+ A future optional command could look like:
25
+
26
+ ```bash
27
+ soturail eval judge --provider openai
28
+ soturail eval judge --provider groq
29
+ soturail eval judge --provider local
30
+ ```
31
+
32
+ Required behavior:
33
+
34
+ - opt-in only;
35
+ - never uploads repo data without clear user action;
36
+ - stores provider, model, prompt hash, timestamp and result;
37
+ - separates judge results from deterministic release evidence;
38
+ - marks results as subjective/heuristic, not proof.
39
+
40
+ ## Non-Goals
41
+
42
+ - no mandatory provider keys;
43
+ - no hidden telemetry;
44
+ - no judge score as the only release gate;
45
+ - no claim that a judge result proves correctness.
@@ -0,0 +1,33 @@
1
+ # MCP Host Manifest
2
+
3
+ SotuRail v1.1.0 adds a read-only host manifest for agent hosts that can inspect local MCP-style resources.
4
+
5
+ ```bash
6
+ soturail mcp resources host-manifest --host codex
7
+ soturail mcp resources host-manifest --host codex --json
8
+ ```
9
+
10
+ Generated files:
11
+
12
+ ```txt
13
+ .soturail/mcp/host-manifest.json
14
+ .soturail/mcp/host-manifests/<host>.json
15
+ ```
16
+
17
+ Schema:
18
+
19
+ ```json
20
+ {
21
+ "schemaVersion": "soturail.mcp.host-manifest.v1",
22
+ "version": "1.1.0",
23
+ "host": "codex",
24
+ "mode": "read-only",
25
+ "mutationAllowed": false,
26
+ "arbitraryShellExecutionExposed": false,
27
+ "resources": []
28
+ }
29
+ ```
30
+
31
+ Resources include status, report, agent report, Project Brain brief, schema check, v1 readiness, benchmark, native candidates, baseline, dashboard, host export and host doctor artifacts when present.
32
+
33
+ The manifest does not expose `.soturail/raw`, shell execution, write tools or destructive MCP tools. Missing artifacts are warnings with next commands, not crashes.
@@ -4,6 +4,8 @@ v0.10.0 exposes report artifacts as read-only MCP resource metadata.
4
4
 
5
5
  ```bash
6
6
  soturail mcp resources report
7
+ soturail mcp resources host-manifest --host codex
8
+ soturail mcp resources host-manifest --host codex --json
7
9
  soturail mcp exposure
8
10
  ```
9
11
 
@@ -11,6 +13,8 @@ Generated manifest:
11
13
 
12
14
  ```txt
13
15
  .soturail/mcp/report-resources.json
16
+ .soturail/mcp/host-manifest.json
17
+ .soturail/mcp/host-manifests/<host>.json
14
18
  ```
15
19
 
16
20
  Seed resource URIs:
@@ -24,8 +28,13 @@ soturail://bench/latest
24
28
  soturail://native/candidates
25
29
  soturail://baseline/latest
26
30
  soturail://observability/timeline
31
+ soturail://agents/host-manifest
27
32
  ```
28
33
 
29
34
  These resources are read-only. They do not expose destructive tools, shell execution or report mutation. Content is sanitized and redaction-aware where possible.
30
35
 
31
36
  If a host does not consume MCP resources directly, the manifest still documents the safe local report artifacts an agent can inspect.
37
+
38
+ Host manifests use `soturail.mcp.host-manifest.v1` and include `mutationAllowed: false` and `arbitraryShellExecutionExposed: false`. They reference status, reports, agent reports, Project Brain exports, schemas, readiness, benchmarks, native candidates, baselines, dashboard, host export and host doctor artifacts when available.
39
+
40
+ See [mcp-host-manifest.md](mcp-host-manifest.md).
package/docs/mcp.md CHANGED
@@ -9,6 +9,8 @@ soturail mcp config --agent generic
9
9
  soturail mcp smoke
10
10
  soturail mcp exposure
11
11
  soturail mcp exposure --json
12
+ soturail mcp resources report
13
+ soturail mcp resources host-manifest --host codex
12
14
  soturail mcp serve --transport stdio
13
15
  ```
14
16
 
@@ -75,6 +77,8 @@ soturail mcp serve --transport stdio
75
77
 
76
78
  It does not assume a global application config path. Review it before adding it to an agent host.
77
79
 
80
+ `soturail mcp resources host-manifest --host <host>` writes `.soturail/mcp/host-manifest.json` and `.soturail/mcp/host-manifests/<host>.json`. The manifest lists local status, report, brain, schema, readiness, benchmark, native, baseline, dashboard, host export and host doctor artifacts. It sets `mutationAllowed: false` and `arbitraryShellExecutionExposed: false`.
81
+
78
82
  For v0.6.0 agent-runtime setup, prefer host-aware dry-runs before copying MCP snippets into a host:
79
83
 
80
84
  ```bash
@@ -0,0 +1,27 @@
1
+ # Media Guide
2
+
3
+ SotuRail media assets are local documentation artifacts. They should show the CLI, reports, dashboard and host exports without exposing private paths, secrets or live tokens.
4
+
5
+ ## Folders
6
+
7
+ ```txt
8
+ docs/assets/screenshots/
9
+ docs/assets/demos/
10
+ ```
11
+
12
+ ## Rules
13
+
14
+ - Use generated or sanitized screenshots.
15
+ - Do not include real tokens, emails, private paths or `.env` data.
16
+ - Do not show `.soturail/raw` evidence.
17
+ - Prefer small SVG or PNG assets that can be committed safely.
18
+ - Keep animated demos short and local; do not rely on external CDNs.
19
+
20
+ ## Suggested Shots
21
+
22
+ - `status-json.svg`: valid JSON status output.
23
+ - `agents-matrix.svg`: host compatibility matrix summary.
24
+ - `host-doctor.svg`: per-host doctor result.
25
+ - `dashboard.svg`: static dashboard overview.
26
+
27
+ Media is illustrative evidence, not a replacement for tests or release checks.
@@ -0,0 +1,63 @@
1
+ # Multi-Agent Workflow Templates
2
+
3
+ SotuRail should support multi-agent ideas as templates and context packs, not as a required CrewAI/LangGraph runtime.
4
+
5
+ ## Purpose
6
+
7
+ A multi-agent workflow template defines roles, inputs, outputs, evidence and verification criteria for external agents.
8
+
9
+ SotuRail can generate:
10
+
11
+ - role-specific context packs;
12
+ - role boundaries;
13
+ - definition of done per role;
14
+ - handoff files between roles;
15
+ - evidence requirements;
16
+ - a final report skeleton.
17
+
18
+ ## Example Roles
19
+
20
+ ```txt
21
+ Lead Agent
22
+ ├── Researcher: collects local evidence and docs
23
+ ├── Analyst: compares options and risks
24
+ ├── Writer: produces user-facing docs/reports
25
+ └── Verifier: checks claims, tests, links and provenance
26
+ ```
27
+
28
+ ## Proposed Commands
29
+
30
+ ```bash
31
+ soturail workflow template research-report
32
+ soturail workflow template validate-fix-verify-report
33
+ soturail context pack --role researcher
34
+ soturail context pack --role analyst
35
+ soturail context pack --role verifier
36
+ soturail agents export --role reviewer
37
+ ```
38
+
39
+ ## Template: Validate -> Fix -> Verify -> Report
40
+
41
+ Inspired by agent pipelines that validate input, repair issues, revalidate and then produce a report.
42
+
43
+ ```txt
44
+ validate
45
+ input: selected files, schema, policy
46
+ output: findings.json
47
+ fix
48
+ input: findings.json and allowed files
49
+ output: patch proposal or instructions
50
+ verify
51
+ input: patch proposal and test/report commands
52
+ output: verification.md
53
+ report
54
+ input: all prior artifacts
55
+ output: report.md + provenance.md
56
+ ```
57
+
58
+ ## Non-Goals
59
+
60
+ - no mandatory CrewAI, LangGraph or LangChain dependency;
61
+ - no hidden subagent execution;
62
+ - no external web search by default;
63
+ - no autonomous edits without host/human approval.
@@ -36,3 +36,39 @@ The timeline is sorted deterministically, and the summary includes:
36
36
  - safe next commands.
37
37
 
38
38
  Observability still does not collect private shell history and does not upload telemetry.
39
+
40
+ ## Pipeline Recorder Expansion
41
+
42
+ Future observability work can add a pipeline recorder inspired by validate/fix/verify/report agent flows:
43
+
44
+ ```txt
45
+ agent_started
46
+ agent_finished
47
+ agent_failed
48
+ file_read
49
+ schema_validated
50
+ repair_applied
51
+ report_generated
52
+ ```
53
+
54
+ The first implementation can remain local artifacts and dashboard cards. A live SSE/server mode is optional and should not become required.
55
+
56
+ ## Related 2026 Harness Rails
57
+
58
+ Observability Rail is the local timeline layer that feeds several planned rails:
59
+
60
+ - [`agent-qa-rail.md`](agent-qa-rail.md) defines eval runs, scores and regression artifacts that can become observability events.
61
+ - [`evidence-provenance-rail.md`](evidence-provenance-rail.md) defines verification status and provenance sidecars that reports and timelines should surface.
62
+ - [`agent-governance-rail.md`](agent-governance-rail.md) extends observability into trace, ledger, experiment and approval records.
63
+ - [`resilience-rail.md`](resilience-rail.md) adds rate-limit/fallback/provider-risk warnings as local events, not cloud telemetry.
64
+
65
+ 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.
66
+
67
+ ## Ecosystem Direction
68
+
69
+ Hermes-style trajectory compression and Odysseus-style visual workspaces reinforce two SotuRail rules:
70
+
71
+ - keep observability as local, recoverable evidence rather than uploaded telemetry;
72
+ - present Context Packs, Memory, Reports, Evidence, Workflows, Host Compatibility, Skills, lifecycle state and Handoffs as bounded dashboard/report sections.
73
+
74
+ SotuRail does not add a required server, chat workspace or central shell interface. See [Security Boundaries](security-boundaries.md).
@@ -1,6 +1,6 @@
1
1
  # Quickstart
2
2
 
3
- SotuRail is a local-first Context OS for AI coding agents. v1.0.0 freezes the first stable command surface for local status, reports, dashboard artifacts, Project Brain checks, benchmarks, release readiness and agent handoff.
3
+ SotuRail is a local-first Context OS for AI coding agents. v1.0.0 froze the first stable command surface for local status, reports, dashboard artifacts, Project Brain checks, benchmarks, release readiness and agent handoff. v1.1.0 adds host-compatible exports, host doctors and read-only MCP host manifests.
4
4
 
5
5
  ## Install
6
6
 
@@ -0,0 +1,45 @@
1
+ # Rate Limit And Fallback Policy
2
+
3
+ This document describes the future SotuRail policy model for rate-limit and fallback guidance. It is documentation-first and local-first.
4
+
5
+ ## Policy Fields
6
+
7
+ A future policy file could live at:
8
+
9
+ ```txt
10
+ .soturail/policies/rate-limit-and-fallback.yaml
11
+ ```
12
+
13
+ Example:
14
+
15
+ ```yaml
16
+ hosts:
17
+ claude:
18
+ fallback: codex
19
+ contextFallback: markdown
20
+ cursor:
21
+ fallback: generic
22
+ contextFallback: cursor-rules-lite
23
+ workflows:
24
+ default:
25
+ maxAgentTurns: 20
26
+ requireHandoffAfterMinutes: 30
27
+ requireApprovalForExternalCalls: true
28
+ ```
29
+
30
+ ## Fallback Types
31
+
32
+ | Fallback | Meaning |
33
+ | --- | --- |
34
+ | host fallback | export the same SotuRail context to a different agent host |
35
+ | format fallback | use Markdown/static files when MCP or skills are unsupported |
36
+ | role fallback | reduce full workflow context to planner/executor/reviewer packs |
37
+ | offline fallback | keep local docs/reports usable when no provider is available |
38
+
39
+ ## Non-Goals
40
+
41
+ - no live billing control;
42
+ - no provider account automation;
43
+ - no quota bypass;
44
+ - no traffic interception;
45
+ - no promise that fallback preserves model behavior.
@@ -1,6 +1,6 @@
1
1
  # Release Workflow
2
2
 
3
- v1.0.0 adds strict local release gates:
3
+ v1.x uses strict local release gates:
4
4
 
5
5
  ```bash
6
6
  soturail self schemas --check --strict
@@ -86,6 +86,17 @@ soturail release check
86
86
 
87
87
  `report_safety` is a release gate. If report artifacts contain obvious tokens or private keys, run `soturail report redact` and inspect the source artifact before publishing.
88
88
 
89
+ For v1.1.0 host compatibility evidence, run:
90
+
91
+ ```bash
92
+ soturail agents matrix --json
93
+ soturail agents doctor --all --json
94
+ soturail mcp resources host-manifest --host codex
95
+ soturail report agent --agent opencode
96
+ ```
97
+
98
+ Host evidence must stay local, read-only and redaction-aware. It must not claim destructive MCP, shell execution through MCP, cloud telemetry or full host-native runtime support for experimental targets.
99
+
89
100
  You can run only the package verification gate with:
90
101
 
91
102
  ```bash
@@ -31,3 +31,6 @@ docs/releases/RELEASE_NOTES_vX.Y.Z.md
31
31
  - [v0.10.0](RELEASE_NOTES_v0.10.0.md)
32
32
  - [v0.10.1](RELEASE_NOTES_v0.10.1.md)
33
33
  - [v1.0.0](RELEASE_NOTES_v1.0.0.md)
34
+ - [v1.0.1](RELEASE_NOTES_v1.0.1.md)
35
+ - [v1.1.0](RELEASE_NOTES_v1.1.0.md)
36
+ - [v1.2.0](RELEASE_NOTES_v1.2.0.md)
@@ -0,0 +1,55 @@
1
+ # SotuRail v1.1.0
2
+
3
+ SotuRail v1.1.0 adds Host Compatibility Rail 1.0: host-aware exports, a richer compatibility matrix, per-host doctor reports, read-only MCP host manifests and practical docs for OpenCode, Antigravity, Gemini-compatible and DeepAgents-style handoffs.
4
+
5
+ ## Added
6
+
7
+ - `soturail agents matrix --json` now preserves `soturail.agents.matrix.v1` and adds `contractId: soturail.agent-host-matrix.v1`.
8
+ - `soturail agents doctor --host <host>` writes `.soturail/agents/<host>/doctor.json` and `.md`.
9
+ - `soturail agents doctor --all --json` writes `.soturail/agents/doctor-summary.json` and `.md`.
10
+ - `soturail mcp resources host-manifest --host <host> [--json]` writes read-only host manifests.
11
+ - `soturail agents export --agent gemini-legacy` supports Gemini legacy/compatible handoffs.
12
+ - OpenCode exports include `AGENTS.md` and context packs.
13
+ - Antigravity exports include high-priority experimental transition guidance.
14
+ - DeepAgents/deepagents-js exports include `role-pack.md` and `subagents.md`.
15
+
16
+ ## Changed
17
+
18
+ - Default agent exports are mirrored to `.soturail/agents/<host>/` and `.soturail/exports/agents/<host>/`.
19
+ - Agent reports support OpenCode, Antigravity, Cursor, Gemini legacy and DeepAgents-style targets.
20
+ - Docs now include host matrix schema, export contract, MCP host manifest, OpenCode tutorial and media guidance.
21
+ - README and ROADMAP now mark v1.1.0 Host Compatibility Rail as delivered.
22
+
23
+ ## Safety
24
+
25
+ - No cloud telemetry.
26
+ - No server requirement.
27
+ - No destructive MCP tools.
28
+ - No shell execution through MCP.
29
+ - No provider lock-in.
30
+ - TypeScript fallback remains mandatory.
31
+ - Experimental hosts are labeled honestly; OpenCode is generic-compatible, Antigravity is experimental, and DeepAgents exports are role/context artifacts only.
32
+
33
+ ## Verification
34
+
35
+ Run before publishing:
36
+
37
+ ```bash
38
+ npm run typecheck
39
+ npm run build
40
+ npx vitest run tests/v110.test.ts
41
+ npx vitest run tests/v100.test.ts
42
+ npm test
43
+ npm run release:check
44
+ node dist/cli.js agents matrix --json
45
+ node dist/cli.js agents doctor --all --json
46
+ node dist/cli.js mcp resources host-manifest --host codex --json
47
+ node dist/cli.js report agent --agent opencode
48
+ ```
49
+
50
+ ## Known Limitations
51
+
52
+ - Host compatibility remains export/report/manifest oriented; SotuRail does not become a host runtime.
53
+ - Antigravity support remains prompt/context only until a stable Google-local project config surface is documented.
54
+ - OpenCode support is generic-compatible and does not claim full host-native integration.
55
+ - DeepAgents exports are role packs and subagent notes only; no runtime dependency is installed.