triss-coworker 0.37.1 → 0.37.2

package/CHANGELOG.md

@@ -7,8 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.37.2] — 2026-08-20
+
+### Added
+
+- **Host-agent delegation workflow guidance** — a single documented
+  one-host/one-coder workflow: the host plans and decides, sends one complete
+  task packet to one `triss coder run`, the coder investigates, implements,
+  tests, debugs, and self-verifies, and the host inspects the actual diff and
+  makes the final decision. Taught consistently in `README.md`, the full
+  cookbooks (`templates/codex-full.md`, `templates/claude-full.md`), the nano
+  templates (`templates/codex.md`, `templates/claude.md`), and the
+  authoritative `docs/reliable-delegation-contract.md`.
+
+### Changed
+
+- Coder and researcher agent templates now state the approval boundary
+  explicitly: the coder never commits, pushes, deploys, or touches anything
+  outside its checkout and reports truthfully; the researcher is a
+  research-only specialist and not a mandatory precursor to coder work.
+
+### Documentation
+
+- Scope the constant `expectation: "either"` output field and the
+  `run_files_changed` change-evidence field to the `opencode`/`crush`
+  engines in `docs/reliable-delegation-contract.md` and `docs/mcp.md`; the
+  `opencode2` beta envelope reports neither and uses `files_changed`
+  instead.
+
+### Artifact integrity (0.37.2)
+
+- `triss-dsh-provider-bundle-0.37.2.tgz` — sha256
+  `0327051792f0fe0d5431619aee7e2dee120fbbdb744b3e7f9afdd0eb958740b9`,
+  integrity
+  `sha512-BBZlA9OiA8pIp+n+GJ9RBX4+yPQpRoKjQLx8KY/5ZIlqRCMUJ5SResBEuVpPiMI9UDTnWq2rQp5JI/6TVh0Y7w==`
+  (computed with the pinned release npm 11.6.2 via `npm pack`; `npm pack`
+  output is byte-deterministic).
+- Root `triss-coworker-0.37.2.tgz` sha256 is reproducible via `npm pack` at
+  tag `v0.37.2` (the root tarball ships `CHANGELOG.md`, so its hash cannot be
+  recorded inside this file); registry verification compares the packed
+  artifact against the published tarball byte-for-byte.
+
 ## [0.37.1] — 2026-08-19
 
+
 ### Fixed
 
 - Propagate cancellation through the main MCP review path and fail closed
@@ -35,8 +77,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Reliable delegation (Release C)** — sequential sharding per
-  `docs/reliable-delegation-contract-plan.md`:
+- **Reliable delegation (sharding acceptance)** — sequential sharding per the
+  public `docs/reliable-delegation-contract.md`:
   - `--payload-mode shard` CLI + MCP shard parity: source-ordered
     whole-file shards (a file is never split across shards);
   - sequential executor with first-failure stop, cancellation
@@ -49,13 +91,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     never completed prose or raw diff content;
   - `evidence + shard` and `shard + --stream` rejected before any model
     call;
-  - Release C synthetic acceptance (`--synthetic --release C`) and live
-    acceptance (`--live --release C`; PASS / SKIPPED_NO_CREDENTIALS /
+  - sharding synthetic acceptance (`--synthetic --suite sharding`) and live
+    acceptance (`--live --suite sharding`; PASS / SKIPPED_NO_CREDENTIALS /
     BLOCKED_ENVIRONMENT recorded separately, never upgraded to success).
 
-- **Reliable delegation (Release B)** — bounded single review, exact PR
-  diff acquisition, and the issue trust boundary per
-  `docs/reliable-delegation-contract-plan.md`:
+- **Reliable delegation (review acceptance)** — bounded single review, exact PR
+  diff acquisition, and the issue trust boundary per the public
+  `docs/reliable-delegation-contract.md`:
   - reloadable review limits (`TRISS_REVIEW_SINGLE_MAX_BYTES`,
     `TRISS_REVIEW_SHARD_MAX_BYTES`, `TRISS_REVIEW_TOTAL_MAX_BYTES`,
     `TRISS_REVIEW_MAX_SHARDS`) with atomic validation and full-default
@@ -122,7 +164,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   (`usage_source: "opencode2"`, terminal-error precedence, no fabricated
   zeros), namespaces sessions per engine, and rides the shared opencode-v1
   configuration backend for `coder model set` / rollback. See
-  docs/opencode2.md and docs/opencode2-engine-plan.md.
+  docs/engines/opencode2.md and docs/opencode2-engine-plan.md.
 
 ### Security (opencode2 engine beta)
 
@@ -150,7 +192,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   canonical parser (comments and trailing commas no longer abort the run),
   and `parseOpenCodeDocument` drops trailing commas followed by comments.
 
-### Fixed (review rounds 4–6)
+### Fixed
 
 - Dual legacy/native config forms (`provider`+`providers`,
   `plugin`+`plugins`, `permission`+`permissions`) reject — the pinned build
@@ -176,7 +218,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   rejects BEFORE any credential/config write with actionable guidance; a
   fresh V2 init warns that the shared deny-everything policy removes the
   allowlisted commands from plain V1 runs (documented in
-  docs/opencode2.md, including two new troubleshooting rows).
+  docs/engines/opencode2.md, including two new troubleshooting rows).
 - Model inspection tolerates unrelated hostile config shapes (a non-string
   plugin reference, unreadable directories) — the post-commit audit of a
   successful `coder model set` no longer rolls back over them; `coder
@@ -209,12 +251,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Reliable delegation (Release A)** — coder envelope v2 orchestration per
-  `docs/reliable-delegation-contract-plan.md`:
+- **Reliable delegation (session acceptance)** — coder envelope v2 orchestration
+  per the public `docs/reliable-delegation-contract.md`:
   - envelope fields `session_slug`, `result_retention`, `result_id`, and
     `execution_capabilities` (eight honest `enforced|best_effort|unavailable`
     values + `effective_isolation`) on every safe envelope
-    (`docs/reliable-delegation-release-a.md`);
+    (`docs/reliable-delegation-contract.md`);
   - v2 session CLI: `triss coder session list`, `triss coder session clean
     <slug> --engine <opencode|crush>` (per-engine store only, legacy
     `.triss/sessions.json` never touched);
@@ -229,7 +271,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     phase-aware manifest machine, completion-marker hashing);
   - credential proxy (loopback one-run token) on both engines — the real
     provider key never reaches the engine environment; every run requires
-    the proxy (Release A rejects runs when it is unavailable);
+    the proxy (session acceptance rejects runs when it is unavailable);
   - pure provider error classifier with stable public codes
     (`TRISS_PROVIDER_AUTH/POLICY/RATE/TIMEOUT/NOT_FOUND/CONNECTION/UNKNOWN/
     CONFLICT/EMPTY`);
@@ -762,7 +804,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   tools (which now light up on `ZHIPU_API_KEY` **or** `OPENCODE_API_KEY`). (#12)
 - `--allow-unsafe-bash` on `triss coder init` — explicit opt-in to proceed when
   an existing `opencode.json` has no deny-first bash policy. (#12)
-- New `docs/opencode-zen.md` deep-dive (auth, live catalogue, precedence, setup
+- New `docs/engines/opencode-zen.md` deep-dive (auth, live catalogue, precedence, setup
   gates, privacy, MCP, verification). (#12)
 
 ### Changed
@@ -805,9 +847,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   npm version. (#10)
 - New `docs/glm-clients.md` — a single reference for how Triss talks to
   GLM (both engines, key/endpoint routing, model selection, usage modes,
-  and the safety model), and `docs/crush-issues.md` /
-  `docs/crush-restrict-issues.md` capturing the crush maintainer bug
-  reports. (#10)
+  and the safety model), plus two Crush maintainer bug reports. (#10)
 
 ### Changed
 
@@ -1226,7 +1266,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- Documentation-audit fixes (P0 + P1 from `triss` self-audit).
+- Documentation-audit security and correctness fixes from a `triss` self-audit.
 
 ## [0.12.0] — 2026-05-07
 

package/README.md

@@ -24,7 +24,7 @@ GitHub Issues, and GitLab Issues, so your agent can search, read, create,
 update, comment on, and transition work items without pulling thousands of
 tokens of tracker chatter into its own context. Adding a new provider
 (Notion, Asana, Sentry, ...) takes one folder — see
-[docs/extending.md](docs/extending.md).
+[extension guide](https://github.com/ayleen/triss-coworker/blob/main/docs/extending.md).
 
 ---
 
@@ -56,7 +56,8 @@ tokens of tracker chatter into its own context. Adding a new provider
   yarn, git, tar, unzip, or a checksum utility once a standalone Release exists.
 - A **DeepSeek API key** (free tier works) for the worker model: <https://platform.deepseek.com/>.
 
-Triss has no other runtime dependencies.
+No external service or system-wide binary is required for the core CLI. npm
+dependencies are installed with the package.
 
 ## Install
 
@@ -305,7 +306,7 @@ The exposed tool set is **filtered by configured credentials**:
   `MOONSHOT_API_KEY` (Moonshot Kimi), or `KIMI_API_KEY` (Kimi for Coding)
   (setup: `triss coder init`). `triss_coder_run` takes an optional `engine`
   (`opencode` V1 default; `--engine opencode2` beta — see
-  [opencode2.md](docs/opencode2.md) — or `crush`); its timeout defaults to
+  [opencode2.md](docs/engines/opencode2.md) — or `crush`); its timeout defaults to
   1500s (25 min) over MCP, above the CLI's 900s, since coding runs are
   expected to be long; override per call via the `timeout` arg. For
   runs that may exceed it, use `triss coder run` on the CLI instead.
@@ -314,9 +315,8 @@ Add credentials later → restart session → new tools appear automatically.
 
 Full reference: [docs/mcp.md](docs/mcp.md).
 
-The root `CLAUDE.md` and `AGENTS.md` in this repository are contributor
-instructions for working on Triss itself. The files under `templates/` are
-what `triss init` and `triss agent-help` render into other projects:
+The files under `templates/` are what `triss init` and `triss agent-help`
+render into other projects:
 `claude.md` / `codex.md` are the nano variants written by `init`, and
 `claude-full.md` / `codex-full.md` are the long cookbook served by
 `agent-help`.
@@ -326,6 +326,70 @@ what `triss init` and `triss agent-help` render into other projects:
 The expensive primary agent decides **what** to do. Triss does the **reading
 and writing**.
 
+### Recommended host-agent workflow
+
+Keep one primary agent and one coder per implementation stream. You (the
+expensive primary agent) understand the request, decide the plan, and own
+architecture, authorization, and final acceptance; the coder owns the
+repository investigation, implementation, tests, debugging, and
+self-verification; you then inspect the actual diff and evidence and make
+the final decision. Do not default to a researcher -> planner -> coder ->
+verifier -> reviewer chain — use `triss ask` / `triss fetch` for
+research-only work and `triss review` only when complexity, security
+sensitivity, or regression risk materially improves confidence. Split work
+across coders only when the streams are independently executable with
+explicit merge or handoff boundaries. Prefer a fresh run without intentional
+session reuse: pass the complete task packet to every run and rely on
+`--session` / `--continue` only for deliberate continuation.
+
+Pass the whole plan as one task packet — Goal, Plan, Constraints, Relevant
+context, Success criteria, Validation, Return — via `triss coder run --stdin`
+for long prompts or as the MCP `prompt` string:
+
+```bash
+triss coder run --stdin --isolate <<'TASK'
+Goal
+- Add the requested behavior.
+
+Plan
+- Follow the host-approved implementation steps.
+
+Constraints
+- Preserve existing public behavior outside the requested scope.
+- Do not commit, push, deploy, or modify files outside this checkout.
+
+Relevant context
+- Known entry points, related files, prior findings, errors, or reference behavior.
+- Include only context needed for this task; let the coder inspect the repository for the rest.
+
+Success criteria
+- Focused regression tests pass.
+- The final diff contains only the requested change.
+
+Validation
+- Run the relevant repository-native focused tests.
+
+Return
+- Outcome, files changed, checks, and unresolved blockers.
+TASK
+```
+
+`triss agent-help` prints the generated host-agent cookbook and the final
+acceptance checklist.
+
+Existing `triss coder init` installations keep their generated agent files
+(`init` never overwrites them, so re-running it alone will not refresh
+them). To adopt the stronger coder/researcher roles:
+
+- local scope: merge or replace `./.opencode/agents/coder.md` /
+  `./.opencode/agents/researcher.md`;
+- global scope (the `triss coder init` default): merge or replace
+  `~/.config/opencode/agents/coder.md` /
+  `~/.config/opencode/agents/researcher.md`;
+- to regenerate them, back up or remove the generated files first, then
+  re-run `triss coder init` with the matching explicit `--local` / `--global`
+  scope.
+
 | Command         | Does                                                  | Replaces                            |
 | --------------- | ----------------------------------------------------- | ----------------------------------- |
 | `triss ask`        | Reads files, URLs, and/or piped stdin — returns a summary | The agent reading the source itself |
@@ -337,8 +401,8 @@ and writing**.
 | `triss review`     | Code review on a branch, PR, or explicitly piped diff (linked ticket only for branch/PR) | The agent reading the whole diff |
 | `triss commit-msg` | Generates a commit message from staged diff           | Hand-writing or copy-pasting from web LLMs |
 | `triss usage`      | Cumulative cost / token usage with per-project breakdown | Squinting at stderr after each call |
-| `triss coder init` | Sets up a coding agent (default `opencode` V1 engine; `--engine opencode2` for the V2 beta — shares the `opencode.json` config, see [docs/opencode2.md](docs/opencode2.md); `--engine crush` for crush): provider key/profile (`--provider worker` reuses `TRISS_WORKER_*`; Z.AI GLM default; Zen, Go, and Kimi are also supported), config, permission policy, and agent templates. Blocks (non-zero) on an unsafe existing `opencode.json` — missing deny-first bash policy (override with `--allow-unsafe-bash`) or a stale/cross-provider `small_model`. | Manually installing/configuring opencode |
-| `triss coder run` | Spawns the coding agent (the OpenAI-compatible Triss worker, GLM, Kimi, OpenCode Zen, or OpenCode Go) and prints one JSON envelope (`--engine opencode|opencode2|crush` — opencode V1 default, opencode2 beta per [docs/opencode2.md](docs/opencode2.md); `--isolate` for a disposable worktree — opencode defaults to isolate-OFF, crush defaults to isolate-ON; crush adds opt-in `--restrict`/`--no-restrict` for its CLI allowlist). **POSIX only** (macOS/Linux) — refuses to run on Windows. | Manually driving `opencode run` and parsing its ndjson stream |
+| `triss coder init` | Sets up a coding agent (default `opencode` V1 engine; `--engine opencode2` for the V2 beta — shares the `opencode.json` config, see [docs/engines/opencode2.md](docs/engines/opencode2.md); `--engine crush` for crush): provider key/profile (`--provider worker` reuses `TRISS_WORKER_*`; Z.AI GLM default; Zen, Go, and Kimi are also supported), config, permission policy, and agent templates. Blocks (non-zero) on an unsafe existing `opencode.json` — missing deny-first bash policy (override with `--allow-unsafe-bash`) or a stale/cross-provider `small_model`. | Manually installing/configuring opencode |
+| `triss coder run` | Spawns the coding agent (the OpenAI-compatible Triss worker, GLM, Kimi, OpenCode Zen, or OpenCode Go) and prints one JSON envelope (`--engine opencode|opencode2|crush` — opencode V1 default, opencode2 beta per [docs/engines/opencode2.md](docs/engines/opencode2.md); `--isolate` for a disposable worktree — opencode defaults to isolate-OFF, crush defaults to isolate-ON; crush adds opt-in `--restrict`/`--no-restrict` for its CLI allowlist). **POSIX only** (macOS/Linux) — refuses to run on Windows. | Manually driving `opencode run` and parsing its ndjson stream |
 | `triss coder clean` | Removes finished `.triss/wt` isolation worktrees (`--all` forces all) | Manually finding and deleting stale git worktrees |
 | `triss coder session` | Lists / cleans inactive v2 sessions per engine (`--engine opencode|crush`) | Hand-patching the session store |
 | `triss coder result` | Lists / cleans retained result artifacts (enforced result-store quota) | Finding result-store files by hand |
@@ -569,10 +633,10 @@ triss review --files src/a.js test/b.test.js  # literal file selection (after --
 triss review --issue ENG-42  # explicit tracker issue (never inferred from prose)
 ```
 
-### Reliable delegation — review safety (Release B)
+### Reliable delegation — review safety (review acceptance)
 
-Review runs are bounded and fail closed (see
-[`docs/reliable-delegation-release-a.md`](docs/reliable-delegation-release-a.md)):
+Review runs are bounded and fail closed (see the
+[`docs/reliable-delegation-contract.md`](docs/reliable-delegation-contract.md)):
 
 - **Limits**: single request (256 KiB default / 1 MiB hard max), shard
   (96 KiB / 256 KiB), total corpus (4 MiB / 16 MiB), shard count (64 /
@@ -593,7 +657,7 @@ Review runs are bounded and fail closed (see
 - **Empty responses** fail with `TRISS_PROVIDER_EMPTY` instead of
   producing a clean verdict; usable non-empty text is never trimmed.
 
-### Sharding (Release C)
+### Sequential review sharding
 
 `triss review --payload-mode shard` runs source-ordered whole-file shards
 sequentially. A file is never split across shards; the first failure or
@@ -659,7 +723,7 @@ default timeout, configurable via `--timeout <ms>`.
 Delegates an implementation task to a cheap coding agent — the existing
 OpenAI-compatible Triss worker, GLM, Kimi,
 OpenCode Zen, or OpenCode Go models (the `opencode` V1 engine by default;
-`opencode2` beta — see [docs/opencode2.md](docs/opencode2.md) — or `crush`; see
+`opencode2` beta — see [docs/engines/opencode2.md](docs/engines/opencode2.md) — or `crush`; see
 **Engines** below) instead of the primary model writing
 the code itself.
 
@@ -676,16 +740,26 @@ triss coder state backup --project <path>         # Section 15 rollback backup
 triss coder state validate --project <path> --backup <dir>
 ```
 
-Every `triss coder run` envelope (and the matching MCP tool) carries the
-Release A contract fields: `session_slug` (explicit slug or an anonymous
-generated one — never an implicit persistent conversation), `result_retention`
+Every `triss coder run` envelope on the `opencode` and `crush` engines
+(and the matching MCP tool) carries the session acceptance contract fields:
+`session_slug` (explicit slug or a generated per-run slug — never an
+implicit persistent conversation), `result_retention`
 / `result_id` (`retained` only for isolated changed runs with enforced
 result-store quota and a successful reservation), and `execution_capabilities`
 (eight honest `enforced|best_effort|unavailable` values plus
-`effective_isolation`). Non-isolated `files_changed` is `null`; the only
-changes-expectation evidence is `run_files_changed`. Process completion is not
-task satisfaction — use `--expect changes --isolate` and inspect `git status`
-yourself. Unavailable OS sandbox/cleanup/lock/quota does not block a
+`effective_isolation`). The `opencode2` beta engine still returns the older
+envelope shape (`session_id`, `exit_reason`, `final_text`, `files_changed`,
+`diff_stat`, `worktree`, `usage`, `warnings`) without these fields — use its
+`files_changed` / `diff_stat` / `worktree` as evidence there. Non-isolated `files_changed` is `null`; the only
+changes-expectation evidence is `run_files_changed`. Process completion and a
+non-empty final text are not task satisfaction — use `--isolate`, check
+`run_files_changed` in the envelope, and verify the retained worktree/diff
+directly when the envelope returns one (a run with `worktree: null` and an
+empty `run_files_changed` — or empty `files_changed` on the `opencode2` beta
+— produced no retained deliverable): `git status --short`,
+then review the staged patch with `git diff --cached` and any unstaged
+changes with `git diff` (Triss stages the deliverable changes before
+returning the envelope). Unavailable OS sandbox/cleanup/lock/quota does not block a
 non-isolated/best-effort run but provides none of those guarantees; explicit
 or default isolation needs `--allow-best-effort-caller-worktree` (default
 off) or fails before spawn with `TRISS_CODER_ISOLATION_ENFORCEMENT_REQUIRED`
@@ -697,8 +771,8 @@ repository or worktree creation failure — slug/branch conflicts like
 `best_effort_caller_worktree`: stderr and envelope `warnings` carry
 `TRISS_CODER_ISOLATION_DOWNGRADED` and `effective_isolation` becomes
 `best_effort_caller_worktree` (advisory-only, `files_changed` is `null`,
-edits may reach the caller worktree). Full details:
-`docs/reliable-delegation-release-a.md`.
+edits may reach the caller worktree). Full details are in the
+[`docs/reliable-delegation-contract.md`](docs/reliable-delegation-contract.md).
 
 `triss coder init` first asks which provider to configure — **Z.AI GLM**
 (default), the existing **Triss worker** (`--provider worker`, aliases
@@ -715,8 +789,8 @@ providers need no probe at all — their plans use different keys
 (`MOONSHOT_API_KEY` vs `KIMI_API_KEY`), so the choice already names the
 endpoint. Either way it lets you pick the model interactively. See the
 **Providers** section below and
-[docs/opencode-zen.md](docs/opencode-zen.md) and
-[docs/opencode-go.md](docs/opencode-go.md) for the OpenCode provider deep-dives.
+[docs/engines/opencode-zen.md](docs/engines/opencode-zen.md) and
+[docs/engines/opencode-go.md](docs/engines/opencode-go.md) for the OpenCode provider deep-dives.
 
 Prints one JSON envelope to stdout — `files_changed`, `diff_stat`, and
 `worktree` tell you what to review; `--isolate` runs the agent in a
@@ -726,7 +800,8 @@ waits for any residual process in the selected engine's process group, so tests
 clients cannot keep locks or write files after completion. MCP cancellation is
 forwarded to the same cleanup path. `--session <slug>` continues the same opencode
 conversation across calls. **POSIX only** (macOS/Linux) for now. See
-`docs/glm-clients.md` for the full picture of how Triss talks to GLM
+the [GLM client guide](https://github.com/ayleen/triss-coworker/blob/main/docs/glm-clients.md)
+for the full picture of how Triss talks to GLM
 (all engines, key/endpoint routing, models, and every usage mode),
 `docs/configuration.md` for the coder env vars, and `docs/mcp.md` for the
 MCP tool equivalents.
@@ -748,8 +823,9 @@ CLI flag > env > crush.json `permissions.run.restrict` > default OFF). For
 Z.AI GLM, the opencode engines and crush all use the single `ZHIPU_API_KEY`
 (crush ≥0.1.1 reads it natively; triss also forwards it as `ZAI_API_KEY`
 for older binaries; see
-**Providers** below for the opencode-only OpenCode alternatives). See
-`docs/crush-restrict-issues.md` for the live-verified bug facts.
+**Providers** below for the opencode-only OpenCode alternatives). See the
+[Crush engine guide](docs/engines/crush.md) for the supported configuration,
+safety boundaries, and current upstream limitations.
 
 **Providers** — the `opencode` engine isn't limited to Z.AI. The required
 API key follows the model's `<provider>/` prefix: `triss-worker/*` reuses
@@ -858,7 +934,7 @@ override within the current provider; use `--provider` + `--model` and optional
 `--small-model` to switch the complete pair for one run. The deny-first
 `opencode.json` bash policy applies to every provider.
 Full details, the model catalogue, and every configuration path are in
-[docs/opencode-zen.md](docs/opencode-zen.md) and [docs/opencode-go.md](docs/opencode-go.md).
+[docs/engines/opencode-zen.md](docs/engines/opencode-zen.md) and [docs/engines/opencode-go.md](docs/engines/opencode-go.md).
 
 If your Z.AI plan hits its usage limit, `triss coder run` fails fast with
 the reset time converted to your local timezone (Z.AI reports it in
@@ -883,7 +959,7 @@ Not every engine speaks every provider:
 | Engine     | Providers served                                  |
 | ---------- | ------------------------------------------------- |
 | `opencode` | Triss worker, Z.AI GLM, OpenCode Zen, OpenCode Go, Moonshot, Kimi for Coding |
-| `opencode2` | Same provider routing as V1 (shares `opencode.json`; one-shot `--provider` / `--small-model` overlays rejected — see [docs/opencode2.md](docs/opencode2.md)) |
+| `opencode2` | Same provider routing as V1 (shares `opencode.json`; one-shot `--provider` / `--small-model` overlays rejected — see [docs/engines/opencode2.md](docs/engines/opencode2.md)) |
 | `crush`    | Z.AI GLM (coding-plan only)                       |
 
 `triss coder init` drives setup in that order — **engine, then provider,
@@ -935,8 +1011,9 @@ Triss surfaces that replacement command rather than auto-switching you
 to GLM.
 
 Full flag reference, the model catalogues, key/endpoint routing, and
-the stale-model recovery flow are in [docs/glm-clients.md](docs/glm-clients.md),
-[docs/opencode-zen.md](docs/opencode-zen.md), [docs/opencode-go.md](docs/opencode-go.md), and
+the stale-model recovery flow are in the
+[GLM client guide](https://github.com/ayleen/triss-coworker/blob/main/docs/glm-clients.md),
+[docs/engines/opencode-zen.md](docs/engines/opencode-zen.md), [docs/engines/opencode-go.md](docs/engines/opencode-go.md), and
 [docs/configuration.md](docs/configuration.md).
 
 ## Integrations
@@ -975,7 +1052,8 @@ hints live in the on-demand cookbook, not in the always-loaded block.)
 
 The plugin contract is one folder + one file. A working **GitHub Issues**
 integration in ~80 lines is documented end-to-end in
-[**docs/extending.md**](docs/extending.md). High-level recipe:
+[**extension guide**](https://github.com/ayleen/triss-coworker/blob/main/docs/extending.md).
+High-level recipe:
 
 1. Create `src/integrations/<name>/index.js`.
 2. `export default { name, description, envVars, register(program, { wrap }) {}, agentInstructions: { claude, codex } }`.
@@ -1190,15 +1268,17 @@ rules of thumb.
 ## Security & privacy
 
 The short version for a vendor security review — full details in
-[SECURITY.md](SECURITY.md):
+[SECURITY.md](https://github.com/ayleen/triss-coworker/blob/main/SECURITY.md):
 
 - **Local-first.** Triss is a CLI/MCP server on your machine, not a hosted
   service. It stores nothing server-side and has **no telemetry** — zero
   data goes to the Triss developers.
-- **Two outbound flows, both yours to configure.** Prompts and selected
-  context go to the model endpoint you set (`TRISS_WORKER_BASE_URL`,
-  DeepSeek by default); tracker commands talk to the Jira/Linear/GitHub/…
-  instances you configured. Nothing else leaves the machine.
+- **Outbound data is explicit and documented.** Model commands and coder
+  engines may send selected repository content to the configured provider;
+  integrations call their configured services; a credential-free GitHub
+  Releases check runs when the update cache is due. The complete recipient,
+  payload, trigger, and opt-out table is in
+  [docs/data-flows.md](docs/data-flows.md).
 - **Data residency is a config option.** Need an EU processor, a DPA, or
   zero retention? Point the worker at Azure OpenAI, Bedrock, Mistral, or a
   self-hosted model — see [provider recipes](#provider-recipes).
@@ -1208,11 +1288,12 @@ The short version for a vendor security review — full details in
 - **Guardrails.** SSRF guard on all agent-controlled fetches, path sandbox
   in MCP mode, response-size caps, secret masking in output. Residual risks
   are documented, not hidden.
-- **Auditable supply chain.** Plain ESM, no build step, seven direct
-  dependencies, committed lockfile, `npm audit` kept clean.
+- **Auditable supply chain.** npm contents are allowlisted and smoke-tested;
+  the standalone artifact has a deterministic source-to-artifact pipeline.
+  Direct and transitive npm dependencies remain part of the installed code.
 
 Report vulnerabilities via GitHub Security Advisories
-([SECURITY.md](SECURITY.md#reporting-vulnerabilities)).
+([SECURITY.md](https://github.com/ayleen/triss-coworker/blob/main/SECURITY.md#reporting-vulnerabilities)).
 
 ## Roadmap
 
@@ -1223,9 +1304,8 @@ wizard · bash + zsh completions · `--stdin` · `triss review [PR]` ·
 `triss chat` · MCP server · Cost tracking · `triss commit-msg` · GitHub /
 Confluence / GitLab integrations · Streaming output for `ask`/`chat`/
 `review` · Codex `AGENTS.md` rules · Path-safety sandbox in MCP mode ·
-test suite · Reliable delegation, Release A — coder envelope v2,
-session/result stores, credential proxy, and Section 15 rollback ·
-Reliable delegation, Releases B/C — bounded review corpus limits, exact
+test suite · Reliable delegation — coder envelope v2, session/result stores,
+credential proxy, bounded review corpus limits, exact
 merge-base diff identity, disposable PR bare repos, and sequential
 whole-file review sharding · `triss exec` deterministic routing ·
 `triss coder` (opencode V1 default, opencode2 beta, crush) with worktree
@@ -1237,16 +1317,18 @@ provider recipe blocks for Kimi, Ollama, and OpenRouter.
 - [ ] Crush upstream `permissions.run` enforcement (currently inert —
       the working allowlist is the CLI `--restrict` flags).
 - [ ] opencode2 beta graduation: real credential isolation and
-      fixture-verified subagent support (see [docs/opencode2.md](docs/opencode2.md)).
+      fixture-verified subagent support (see [docs/engines/opencode2.md](docs/engines/opencode2.md)).
 
 ## Contributing and security
 
-Contributions are welcome; start with [CONTRIBUTING.md](CONTRIBUTING.md)
+Contributions are welcome; start with
+[CONTRIBUTING.md](https://github.com/ayleen/triss-coworker/blob/main/CONTRIBUTING.md)
 for local setup, test commands, and the project conventions.
 
 Security-sensitive changes deserve extra care because Triss sits between an
 agent, your filesystem, web URLs, and tracker credentials. See
-[SECURITY.md](SECURITY.md) for the reporting path and the current trust
+[SECURITY.md](https://github.com/ayleen/triss-coworker/blob/main/SECURITY.md)
+for the reporting path and the current trust
 boundaries.
 
 ## Changelog

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,26 @@
+Triss Coworker third-party notices
+==================================
+
+The npm package installs the following direct runtime dependencies. Their
+license texts and transitive notices are distributed with those packages:
+
+- @modelcontextprotocol/sdk — MIT
+- commander — MIT
+- dotenv — BSD-2-Clause
+- linkedom — ISC
+- openai — Apache-2.0
+- picocolors — ISC
+- turndown — MIT
+
+The project concept acknowledges `imkunal007219/claude-coworker-model`, an
+MIT-licensed project, in README.md:
+
+  Copyright (c) 2026 Kunal Bhardwaj
+  https://github.com/imkunal007219/claude-coworker-model
+
+This notice records attribution and does not assert that its source code is
+bundled in Triss.
+
+The complete resolved dependency graph is recorded in package-lock.json. The
+standalone artifact bundles production npm dependencies and includes this
+notice alongside their package license files.

package/bin/triss.js

@@ -346,7 +346,7 @@ coder
   .description('Install/configure a coding engine (opencode default, opencode2 beta, or crush), provider key, permission policy, and agent templates')
   .option('-g, --global', 'save to the global scope (~/.config/triss/.env, ~/.config/opencode/)')
   .option('-l, --local', 'save to the project scope (./.triss.env, ./opencode.json)')
-  .option('--engine <name>', 'coding engine to configure: opencode (default), opencode2 (beta — shares the opencode.json config; see docs/opencode2.md), or crush')
+  .option('--engine <name>', 'coding engine to configure: opencode (default), opencode2 (beta — shares the opencode.json config; see docs/engines/opencode2.md), or crush')
   .option('--provider <name>', 'opencode engine model provider: zai, worker (existing OpenAI-compatible TRISS_WORKER_* profile), opencode-zen, opencode-go, moonshot, or kimi-for-coding')
   .option('--allow-unverified', 'requires explicit --provider opencode-go (alias: go): allow the built-in fallback only after a temporary network or HTTP 408/429/500/502/503/504 catalogue failure (never bypasses 401/403, empty, or invalid responses)')
   .option('--allow-unsafe-bash', 'proceed even if an existing opencode.json has no deny-first bash policy (the agent runs with --auto)')
@@ -355,7 +355,7 @@ coder
 coder
   .command('run [prompt]')
   .description('Spawn a coding agent — GLM, the OpenAI-compatible Triss worker, Kimi, OpenCode Zen, or OpenCode Go (opencode default; opencode2 beta or --engine crush) — and print a JSON envelope to stdout')
-  .option('--engine <name>', 'coding engine: opencode (default), opencode2 (beta — see docs/opencode2.md), or crush')
+  .option('--engine <name>', 'coding engine: opencode (default), opencode2 (beta — see docs/engines/opencode2.md), or crush')
   .option('--session <id>', 'triss-side session slug, mapped to a real opencode session id in .triss/sessions.json')
   .option('--continue', 'continue the most recent opencode session (maps to opencode --continue)')
   .option('--agent <name>', 'agent template to use (V1 default: coder; opencode2 beta uses its built-in primary agent unless set)')
@@ -458,7 +458,7 @@ coderState
   .requiredOption('--project <absolute-path>', 'absolute path of the validated project root')
   .action((opts) => wrap(runCoderStateReset)(opts));
 
-// `coder session` group (v2 session CLI contract, Atomic 23).
+// `coder session` group (v2 session CLI contract).
 const coderSession = coder
   .command('session')
   .description('List or clean v2 isolated sessions (per-engine store; legacy .triss/sessions.json is never touched)');
@@ -475,7 +475,7 @@ coderSession
   .requiredOption('--engine <name>', 'coding engine: opencode or crush (MANDATORY)')
   .action((slug, opts) => wrap(runCoderSessionClean)(slug, opts));
 
-// `coder result` group (retained-result CLI, Atomic 23).
+// `coder result` group (retained-result CLI contract).
 const coderResult = coder
   .command('result')
   .description('List or clean retained result artifacts (never persistent sessions)');

package/docs/cli-reference.md

@@ -0,0 +1,10 @@
+# CLI reference
+
+The executable reference is `triss --help` and each command's `--help` output.
+The main command groups are model delegation (`ask`, `chat`, `write`, `fetch`,
+`review`, `commit-msg`), coder engines (`coder`), MCP setup (`mcp`), tracker
+integrations, configuration, usage accounting, and updates.
+
+Machine consumers should prefer documented JSON modes and treat their schema
+version as part of the contract. Human-readable output may evolve without a
+schema migration.

package/docs/compatibility.md

@@ -0,0 +1,16 @@
+# Compatibility and stability
+
+| Component | Status |
+| --- | --- |
+| Core `ask` and `review` CLI | stable |
+| MCP protocol surface | beta |
+| JSON envelopes | versioned contract |
+| OpenCode 1 engine | stable |
+| OpenCode 2 engine | beta |
+| Crush engine | experimental |
+| Best-effort isolation | limited security boundary |
+| Update system | stable |
+| Individual integrations | stable or beta as documented by each integration |
+
+Node.js 22 and 24 are tested. Provider availability, model identifiers, and
+third-party CLI behavior can change independently of Triss.