triss-coworker 0.43.0 → 0.44.0

package/ARCHITECTURE.md

@@ -36,3 +36,8 @@ behavior change. Priority candidates are coder orchestration, model management,
 updater installation, MCP installation, and MCP handlers.
 
 Architecture decisions that change trust boundaries belong in `docs/adr/`.
+
+The accepted owner decision on
+[user choice, best-effort execution, and easy setup](docs/adr/2026-09-05-user-choice-and-easy-setup.md)
+governs provider/engine availability and wizard design. Existing runtime gates
+are not product requirements when they conflict with that decision.

package/CHANGELOG.md

@@ -7,6 +7,133 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- All execution engines now run non-coder model projections (`ask`, `review`,
+  `chat`, `write`, `commit-msg`): `opencode` keeps its verified read-only
+  projection; `opencode2`, `omp`, and `crush` execute best-effort and attach a
+  warning naming the concrete limitation that is not verified, instead of
+  rejecting the run before launch.
+- `triss config wizard` now opens the Easy path directly (provider + key,
+  assistant hosts, summary, first command) and preserves existing explicit
+  choices on rerun. `--advanced` exposes the full sections; an optional target
+  argument accepts a canonical provider id, `coder`, or an integration name;
+  `--yes`, `--agent`, and `--install` support headless apply; `triss init
+  --setup` delegates to the same wizard after writing agent rules.
+- New persisted fields: `TRISS_CODER_PROVIDER`, `TRISS_DEFAULT_EFFORT`,
+  `TRISS_CODER_EFFORT`, `TRISS_PROTECT_CREDENTIALS`, and
+  `TRISS_CODER_PROTECT_CREDENTIALS` (credential protection is a tri-state:
+  absent, true, or false — the string `"false"` is never a truthy opt-in) and
+  `TRISS_MODEL_TRANSPORTS` (exact-model direct transport override map).
+- The `direct` engine now serves `opencode-zen` and `opencode-go` models
+  through audited per-model transports (OpenAI Chat, OpenAI Responses,
+  Anthropic Messages); a model without resolvable direct metadata fails with
+  the stable `TRISS_DIRECT_ENGINE_REQUIRED` code and an actionable
+  `TRISS_MODEL_TRANSPORTS` remedy instead of a generic registry error.
+- `--protect-credentials` / `--no-protect-credentials` on model-backed
+  commands: the former requests the parent-owned proxy and falls back to a
+  warned best-effort raw run when a protected route is unavailable; the latter
+  overrides a persisted protection choice for one run. MCP forwards
+  `protect_credentials` as the same tri-state.
+
+### Changed
+
+- Crush is provider-neutral: any canonical provider projects onto a run-scoped
+  config with `$ENV` credential references. Protected mode remains the crush
+  default; an explicit `--no-protect-credentials` runs crush raw through the
+  same run-scoped config as a disclosed best-effort choice. Responses-protocol
+  models ride a bounded chat→responses bridge in the credential proxy
+  (message-only; tool rounds are refused with a precise error).
+- `triss ask`, `triss review`, and other model-backed commands no longer
+  require engine-specific provider restrictions: provider and engine are
+  independent choices, honored as selected with truthful warnings for
+  best-effort routes.
+- The setup wizard no longer resets an existing provider/engine selection or
+  installs a Claude MCP server implicitly; Easy and Advanced share one setup
+  and resolution path.
+
+## [0.44.0] — 2026-09-08
+
+### Added
+
+- `triss config wizard` opens the Easy path directly: pick any canonical
+  provider, paste its key, choose which assistant host to connect (Claude
+  Code, Codex, both, or skip host wiring), review the summary before apply,
+  and finish with a first command to try. Reruns reuse the existing
+  configuration instead of resetting it.
+- `triss config wizard --advanced` exposes the full tuning sections —
+  providers, execution (engine, effort, tri-state credential protection),
+  connections (MCP and agent rules selectable independently), integrations
+  (keep/unset with effective-source display), runtime (including pricing),
+  and in-place engine version pins.
+- Targeted wizard setups configure one piece:
+  `triss config wizard <provider-id>`, `triss config wizard coder` (with
+  `--coder-provider`, `--coder-engine`, `--coder-protect-credentials`), or an
+  integration name.
+- Headless apply: `triss config wizard --yes --agent none [--install]`
+  assembles a complete configuration from existing files, the environment,
+  and explicit flags; missing requirements exit non-zero before writing.
+  `triss init --setup` delegates to the same wizard after writing agent
+  rules.
+- Every execution engine now serves every canonical provider: crush runs any
+  provider through a run-scoped config with `$ENV` credential references
+  (provider block seeded before `crush models use`), and opencode2, omp, and
+  crush execute non-coder projections (`ask`, `review`, `chat`, `write`,
+  `commit-msg`) best-effort with structured warnings naming the unverified
+  limitation.
+- `--protect-credentials` / `--no-protect-credentials` on model-backed
+  commands; MCP forwards `protect_credentials` as the same tri-state and
+  carries credential mode and disclosures in the run envelope.
+- `TRISS_CODER_EFFORT` and `TRISS_DEFAULT_EFFORT` knobs, honored by every
+  engine (crush discloses when a provider declares no effort support).
+
+### Changed
+
+- Credential protection is a verbatim tri-state (absent/true/false) across
+  the CLI, MCP, and persisted configuration: `TRISS_PROTECT_CREDENTIALS` and
+  `TRISS_CODER_PROTECT_CREDENTIALS` persist explicit choices, and an explicit
+  false overrides a persisted true.
+- The setup wizard no longer resets an existing provider/engine selection or
+  installs a Claude MCP server implicitly; Easy and Advanced share one setup
+  and resolution path, integrations gate readiness only when selected, and
+  readiness is re-derived from post-apply state.
+- Engine installers run with a minimal environment allowlist (provider and
+  integration tokens never reach npm lifecycle scripts or downloaded
+  installers), curl|sh installers run as two argv spawns instead of a shell
+  string, and the exact install command is shown before Apply.
+- Env-file writes are atomic (0600 temp file + rename after the CAS check);
+  host-plan status is tracked per concrete target; `config set` validates
+  provider and engine values; `triss status` reads `TRISS_CODER_ENGINE`
+  through the layered setup state.
+- Migration gates the wizard on a `blocked` preflight state instead of
+  writing schema-2 over a conflict.
+
+### Fixed
+
+- A debug path in the wizard's readiness diagnostics could print full
+  credentials to stderr; it is removed and privacy tests now guard the
+  route, the preserved value, and both former exposure points.
+- MCP `protect_credentials: false` was indistinguishable from absent and
+  could not override a persisted true.
+- OMP runs discarded usage/cost records; the coder transport protocol now
+  resolves from the same captured snapshot as the model, and child stderr
+  echoed in errors is masked.
+- `triss init --setup` works in non-TTY shells (`--yes` registered).
+- Root-endpoint provider URLs no longer gain a silent `/v1` in protected
+  runs; unverified cleanup no longer fails closed on a recycled pgid.
+
+
+### Artifact integrity (0.44.0)
+
+- `triss-dsh-provider-bundle-0.44.0.tgz` — sha256
+  `c2e8ce70bb5964cdbcc16a42c574b6f85c142c36d905d066e042c0150f50b935`
+  — `sha512-l8rIL6i7vgukA7efR8Q2PvG8YBnAVRdnlWL338FgZmNt9r+/Efz8OgujnkFb39KLK1qe/sdHY+HntvcLZ9GrQw==`
+  (computed with npm pack; the output is byte-deterministic).
+- Root `triss-coworker-0.44.0.tgz` sha256 is reproducible via `npm pack` at
+  tag `v0.44.0`; the root tarball ships `CHANGELOG.md`, so its hash cannot be
+  recorded inside this file. Registry verification compares the packed
+  artifact with the published tarball byte-for-byte.
+
 ## [0.43.0] — 2026-09-05
 
 ### Changed
@@ -39,7 +166,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   effort, but help prose is not a compatibility gate. Capability errors now
   name missing options separately from below-minimum versions. Pre-suffixed
   public/configured OpenCode 2 models are rejected before engine side effects.
-- Added `TRISS_DEFAULT_ENGINE` so model-backed commands can persist a direct or verified OpenCode route. OpenCode projections install and verify an active primary agent pinned as `default_agent`; its deny-by-default context-only policy provides no ambient file, delegation, skill, or executable tools, and the final merged agent state is audited before credentials are forwarded. Engine warnings remain structured across MCP model tools, explicit credential protection is available, and unverified OpenCode 2, OMP, and Crush projections are rejected before launch.
+- Added `TRISS_DEFAULT_ENGINE` so model-backed commands can persist a direct or verified OpenCode route. OpenCode projections install and verify an active primary agent pinned as `default_agent`; its deny-by-default context-only policy provides no ambient file, delegation, skill, or executable tools, and the final merged agent state is audited before credentials are forwarded. Engine warnings remain structured across MCP model tools, and explicit credential protection is available on every engine.
 - `triss_coder_run` retains the documented `protectCredentials` MCP spelling
   as a deprecated compatibility alias. It is OR-merged with
   `protect_credentials`, so either truthy spelling selects protected

package/README.md

@@ -39,9 +39,30 @@ Delegation can reduce primary-agent context and inference costs, but savings dep
 npm install -g triss-coworker
 ```
 
-**Claude Code or Codex:** run `triss config wizard --standard`. The current Standard path configures the `openai-compatible` API key, main model, and small model, then asks whether to connect Claude Code, Codex, or both. It installs MCP and agent rules for your selection; this version has no Skip option in Standard. Use `triss config wizard --advanced` for another provider or granular setup.
+`triss config wizard` opens the Easy path directly: pick a provider, paste its
+key, choose the assistant hosts to register, and run your first command. It
+reuses existing configuration instead of resetting it. `--advanced` exposes the
+full sections (providers, execution, connections, integrations, runtime), and a
+target argument (`triss config wizard opencode-go`, `triss config wizard coder`,
+`triss config wizard jira`) sets up just that piece. Non-interactive shells add
+`--yes` to apply a complete configuration assembled from existing files, the
+environment, and explicit flags:
 
-**Terminal only:** configure the same profile without installing host integration. Omit values to enter them interactively; secret input is masked:
+```bash
+triss config wizard --yes --agent none
+```
+
+Connect Claude Code, Codex, or both:
+
+```bash
+triss init --target claude --global --setup   # writes rules, then runs the wizard
+triss init --target codex --global
+triss mcp install --target claude --global
+triss mcp install --target codex --global
+```
+
+**Terminal only:** configure the same profile without installing host
+integration. Omit values to enter them interactively; secret input is masked:
 
 ```bash
 triss config set -g TRISS_OPENAI_COMPATIBLE_API_KEY
@@ -102,12 +123,12 @@ Every provider has an endpoint, credential, `model` role, and `smallModel` role.
 4. global `~/.config/triss/.env`;
 5. registry defaults.
 
-`TRISS_DEFAULT_PROVIDER` selects the provider when a request omits one; `TRISS_DEFAULT_ENGINE` selects `direct`, `opencode`, `opencode2`, `omp`, or `crush` when it omits an engine. Direct CLI and MCP commands accept a native model id. Coder model options use `<provider>/<model-id>`. Read-only non-coder projection is currently verified only for `opencode`; `opencode2`, `omp`, and `crush` fail before launch instead of running a write-capable agent.
+`TRISS_DEFAULT_PROVIDER` selects the provider when a request omits one; `TRISS_DEFAULT_ENGINE` selects `direct`, `opencode`, `opencode2`, `omp`, or `crush` when it omits an engine. Direct CLI and MCP commands accept a native model id. Coder model options use `<provider>/<model-id>`. Every engine can execute non-coder model projections (`ask`, `review`, `chat`, …); what differs per engine is the available protection, not permission to run. `opencode` and `direct` have a verified read-only projection; `opencode2` runs the same deny-everything projection agent through its run-scoped config surface, `omp` uses its run-private policy overlay, and `crush` runs single-agent with the restrict allowlist. Engines without a verified projection report their concrete limitation as a warning on the result — never as a refusal.
 
 Shared reasoning effort values:
 
 ```text
-minimal | low | medium | high | max
+low | medium | high | xhigh | max
 ```
 
 Examples:
@@ -127,8 +148,11 @@ Omit `--model` to use the command's provider role. There are no public model pre
 ## Configuration
 
 ```bash
-triss config wizard
-triss config wizard --local
+triss config wizard                    # Easy setup (provider + key + hosts)
+triss config wizard --advanced         # full sections
+triss config wizard opencode-go        # targeted provider setup
+triss config wizard coder --coder-engine omp --coder-provider moonshot
+triss config wizard coder --coder-protect-credentials   # persist TRISS_CODER_PROTECT_CREDENTIALS=true (proxy mode instead of default best-effort raw)
 triss config set TRISS_DEFAULT_PROVIDER zai
 triss config set TRISS_DEFAULT_ENGINE direct
 triss config get TRISS_ZAI_MODEL
@@ -152,16 +176,24 @@ triss ask --paths 'src/**/*.js' --question "Find correctness defects"
 triss review
 ```
 
-Explicit request flags still win. OpenCode-backed non-coder calls install and
-verify a run-scoped active primary `triss-readonly-projection` agent and pin
-`default_agent` to it before forwarding the selected credential. Its permission
-contract denies every tool by default because the complete request context is
-already supplied in the prompt; it never gains ambient file, shell, edit,
-skill, or delegation access. The process still runs as the current OS user and
-is not a filesystem sandbox. Add `--protect-credentials` to a model command
-when the selected credential can be kept behind the parent-owned proxy;
-raw-mode warnings are preserved in MCP structured results for every
-model-backed tool.
+Explicit request flags still win. Engine-backed non-coder calls receive the
+complete request context in the prompt. OpenCode installs and verifies a
+run-scoped active primary `triss-readonly-projection` agent pinned as
+`default_agent`; its permission contract denies every tool by default, so it
+never gains ambient file, shell, edit, skill, or delegation access. The other
+engines apply their best-effort equivalents (run-scoped config surface,
+run-private policy overlay, or the restrict allowlist) and attach a warning
+that names exactly what is not verified. The process still runs as the current
+OS user and is not a filesystem sandbox. Add `--protect-credentials` to a model
+command when the selected credential can be kept behind the parent-owned proxy
+(it falls back to a best-effort raw run with a warning when a protected route
+is unavailable); `--no-protect-credentials` overrides a persisted
+`TRISS_PROTECT_CREDENTIALS=true` choice for one run. For coder runs configured
+through the wizard, `--coder-protect-credentials` / `--coder-no-protect-credentials`
+persist `TRISS_CODER_PROTECT_CREDENTIALS=true` / `=false` (cannot be combined);
+the coder-specific value takes precedence over the shared
+`TRISS_PROTECT_CREDENTIALS`. Raw-mode and engine
+warnings are preserved in MCP structured results for every model-backed tool.
 
 Provider fields:
 
@@ -206,7 +238,7 @@ Supported engines:
 
 - `opencode` — default OpenCode engine
 - `opencode2` — OpenCode 2 beta, current-or-newer compatibility
-- `crush` — Z.A.I-only engine
+- `crush` — provider-neutral single-envelope engine (any canonical provider)
 - `omp` — native Oh My Pi adapter
 
 OpenCode 2 has a supported floor of `0.0.0-beta-19059` and accepts every newer
@@ -219,8 +251,8 @@ Setup examples:
 ```bash
 triss coder init --engine opencode --provider openai-compatible
 triss coder init --engine opencode2 --provider opencode-zen
-triss coder init --engine crush --provider zai
-triss coder init --engine omp --provider opencode-go
+triss coder init --engine crush --provider opencode-go
+triss coder init --engine omp --provider moonshot
 ```
 
 Run examples:
@@ -237,7 +269,7 @@ triss coder run --isolate --session auth-fix \
   "Fix the authentication bug and run focused checks"
 ```
 
-Each run forwards only the selected provider credential. Protected routes use parent-owned loopback credential mediation and fail closed when an engine projection or endpoint cannot be audited. `--isolate` uses `.triss/wt/<slug>` for a reviewable worktree.
+Each run forwards only the selected provider credential. Protected routes use parent-owned loopback credential mediation and fail closed when a protected route cannot actually contain the real key; an explicit `--no-protect-credentials` runs crush raw through the same run-scoped config with the selected credential (best-effort, warned). `--isolate` uses `.triss/wt/<slug>` for a reviewable worktree.
 
 The `opencode` V1 engine preserves native OpenCode routing for Zen and Go. In
 protected mode, only `User-Agent` plus session, request, and client identity

package/bin/triss.js

@@ -107,21 +107,23 @@ function addModelSelectionOptions(command) {
     .option('-m, --model <id>', 'provider-qualified model id, or a bare id with --provider')
     .option('--engine <id>', 'execution engine (direct, opencode, opencode2, omp, or crush)')
     .option('--protect-credentials', MODEL_PROTECT_HELP)
+    .option('--no-protect-credentials', 'override a persisted TRISS_PROTECT_CREDENTIALS=true choice for this run')
     .option('-e, --effort <level>', 'reasoning effort: low, medium, high, xhigh, or max', parseEffort);
 }
 
 // Shared help text for model-backed credential protection.
 const MODEL_PROTECT_HELP =
-  'Use the parent-owned credential proxy for the OpenCode model projection.\n' +
-  'Fails closed when protected credential isolation cannot be enforced.\n' +
-  'OpenCode2, OMP, and Crush are rejected for model-backed commands.';
+  'Use the parent-owned credential proxy for the model projection.\n' +
+  'Falls back to a best-effort raw run with a warning when a verified\n' +
+  'protected route is unavailable for the selected engine.';
 
 // Shared help text for the credential-mode flag (`coder init` and `coder run`;
 // `triss exec --code` forwards it under its own shorter description).
 const PROTECT_HELP =
-  'Use the parent-owned credential proxy and strict executable-surface gates.\n' +
-  'Fails closed when protected credential isolation cannot be enforced.\n' +
-  'OpenCode, OpenCode2, and OMP support this option; Crush is always protected.';
+  'Use the parent-owned credential proxy and strict executable-surface gates\n' +
+  'where the selected engine supports them; otherwise run best-effort with a\n' +
+  'warning. An explicit --no-protect-credentials overrides a persisted\n' +
+  'TRISS_*_PROTECT_CREDENTIALS=true choice for this run.';
 
 const program = new Command();
 program
@@ -149,6 +151,7 @@ program
   .option('-t, --target <agent>', 'target agent (claude | codex | both); omit for an interactive prompt')
   .option('-f, --force', 'force-replace an existing triss block without diffing')
   .option('-s, --setup', 'after writing CLAUDE.md, run `triss config wizard` to fill in credentials')
+  .option('--yes', 'with --setup: non-interactive apply of a complete headless configuration (required outside a TTY)')
   .action(wrap(runInit));
 
 addModelSelectionOptions(
@@ -240,6 +243,7 @@ program
   .option('--no-isolate', 'disable coder isolation')
   .option('--allow-best-effort-caller-worktree', 'forward coder isolation downgrade')
   .option('--protect-credentials', 'forward protected credential mode for model-backed and coder routes')
+  .option('--no-protect-credentials', 'override a persisted TRISS_PROTECT_CREDENTIALS=true choice for this run')
   .option('--restrict', 'forward coder restriction')
   .option('--no-restrict', 'disable coder restriction')
   .option('--cwd <path>', 'forward coder working directory')
@@ -329,15 +333,19 @@ const config = program
 
 config
   .command('wizard [target]')
-  .description('Interactive setup. Optional target: deepseek | jira | linear | …')
+  .description('Interactive setup (Easy by default, Advanced by choice). Optional target: a canonical provider id, coder, or an integration name (jira | linear | …)')
   .option('-g, --global', 'save to ~/.config/triss/.env (default if not asked)')
   .option('-l, --local', 'save to ./.triss.env (project-local override)')
-  .option('-f, --force', 're-prompt for keys that are already set')
-  .option('--standard', 'API key + one model only — skip the standard/advanced prompt')
-  .option('--advanced', 'full wizard with presets, base URL, integrations — skip the prompt')
+  .option('-f, --force', 're-prompt for values that are already set')
+  .option('--standard', 'explicit Easy path (same as the default interactive flow)')
+  .option('--advanced', 'full Advanced wizard — providers, execution, connections, integrations, runtime')
+  .option('--yes', 'non-interactive apply of a complete configuration assembled from existing files, the environment, and explicit flags')
+  .option('--agent <agent>', 'headless host intent: claude | codex | both | none (non-TTY default: none)')
+  .option('--install', 'allow installing missing engines in a headless run (without it, missing dependencies are reported)')
   .option('--coder-engine <name>', 'coder target only: coding engine to configure (opencode default, opencode2 beta, crush, or omp — see docs/engines/omp.md). `coder init` uses --engine')
   .option('--coder-provider <name>', 'coder target only: canonical provider id. `coder init` uses --provider')
   .option('--coder-protect-credentials', 'coder target only: configure the parent-owned credential proxy mode instead of the default best_effort_raw. `coder init` uses --protect-credentials')
+  .option('--coder-no-protect-credentials', 'coder target only: persist/forward an explicit unprotected choice that overrides TRISS_PROTECT_CREDENTIALS=true')
   .action(wrap(runWizard));
 
 config
@@ -393,9 +401,8 @@ coder
   .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/engines/opencode2.md), crush, or omp (see docs/engines/omp.md)')
   .option('--provider <name>', 'canonical model provider id')
-  .option('--allow-unverified', 'requires explicit --provider opencode-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)')
   .option('--protect-credentials', PROTECT_HELP)
+  .option('--no-protect-credentials', 'override a persisted TRISS_PROTECT_CREDENTIALS=true choice for this setup/run')
   .action(wrap(runCoderInit));
 
 coder
@@ -416,6 +423,7 @@ coder
   .option('--timeout <sec>', 'kill the engine after this many seconds', parsePositiveNumber, 900)
   .option('--allow-best-effort-caller-worktree', 'allow downgrade to caller worktree when isolated isolation cannot be enforced (default off — fails before spawn without it)')
   .option('--protect-credentials', PROTECT_HELP)
+  .option('--no-protect-credentials', 'override a persisted TRISS_PROTECT_CREDENTIALS=true choice for this run')
   .option('--stdin', 'read the prompt from piped stdin instead of the [prompt] argument')
   .option('--json', 'no-op — the envelope is always JSON; kept for symmetry with other commands')
   .action((prompt, opts) => wrap(runCoderRun)(prompt, opts));

package/docs/adr/2026-09-05-user-choice-and-easy-setup.md

@@ -0,0 +1,98 @@
+# User choice, best-effort execution, and easy setup
+
+- Status: Accepted; binding owner decision.
+- Date: 2026-09-05.
+- Scope: CLI, MCP, provider runtime, coding engines, config wizard, tests, and documentation.
+
+## Context
+
+Triss has a shared provider runtime, but some execution paths reject engines
+because a verified read-only projection or isolation guarantee is unavailable.
+The wizard redesign initially treated those existing gates as product requirements
+and proposed a large first-run settings menu. The owner explicitly rejected both.
+Existing implementation restrictions are not evidence that users should lose a
+choice. Ordinary users should be able to install Triss and start using it without
+understanding its internal architecture.
+
+## Decision
+
+### Users choose providers, models, and engines
+
+- All Triss providers and execution engines must be available for coding and
+  non-coding tasks. Do not create task-specific allowlists merely because a
+  route lacks a verified read-only projection or complete safety guarantees.
+- Provider and engine are separate choices. Implement the adapters and transport
+  mappings needed to support those choices; a missing adapter is implementation
+  work, not a permanent product prohibition.
+- Do not silently substitute a different provider, model, or engine. Recommended
+  defaults help users start; they do not remove alternatives or override an
+  existing selection.
+- Distinguish actual inability to execute from incomplete safety guarantees.
+  Missing credentials, an unavailable executable, or an API that cannot perform
+  the requested operation must be reported accurately with an actionable remedy.
+  Do not invent support, fabricate success, or label a policy preference as a
+  technical impossibility.
+
+### Incomplete guarantees mean best effort and disclosure, not a ban
+
+- When execution is possible but full safety or isolation cannot be guaranteed,
+  use the available best-effort path and explain the concrete limitation. The
+  user decides whether to use it; do not impose a blanket prohibition.
+- Keep working protections enabled. Best effort is not a reason to discard
+  protections that are available or to expose unrelated credentials.
+- Warnings must identify what is not guaranteed and its practical consequence,
+  without claiming verified isolation or read-only enforcement that is absent.
+  Keep them concise and actionable; expose them in CLI output and structured
+  MCP results, not only in hidden logs.
+- Honor explicit user choices about execution and protection. Never silently
+  downgrade a guarantee the user specifically required. Offer the best-effort
+  alternative with its limitations instead of choosing on the user's behalf.
+- Do not introduce extra mandatory confirmation loops or an opt-in flag solely
+  because a route is best effort. Surface the limitation without turning normal
+  setup into a sequence of alarming security prompts.
+- This decision supersedes older documentation and tests that require rejecting
+  a provider or engine solely for incomplete safety guarantees. It does not
+  authorize secret disclosure, disregard of user intent, or unrelated removal
+  of input validation and release-integrity checks.
+
+### Easy by default; Advanced by choice
+
+- The default wizard path is Easy: minimal choices, sensible recommendations,
+  reuse of existing configuration, and a direct path to the first usable setup.
+- Do not open first-run setup with a large settings dashboard, an exhaustive
+  provider/engine matrix, or a list of environment variables.
+- Ask only for information needed to complete the user's selected setup. Infer
+  what can be established reliably; do not require users to understand model
+  roles, execution projections, endpoints, or isolation internals just to start.
+- Offer Advanced as an optional path for complete supported configuration,
+  including providers, models, engines, scopes, integrations, and operational
+  settings. Users can enter it immediately or revisit it after Easy setup.
+- Easy and Advanced must share resolution, setup, persistence, and verification
+  logic. They differ in the detail exposed, not in correctness or user choice.
+- Explain consequential actions and concrete execution limitations briefly when
+  relevant. Keep technical detail available without overwhelming the main flow.
+- Re-running Easy must preserve explicit existing choices unless the user asks
+  to change them. Report incomplete setup honestly rather than printing a
+  misleading success message.
+
+## Consequences and implementation status
+
+This is the required direction for implementation and review, not a claim that
+all routes already work. At acceptance, non-coder projections still reject
+OpenCode 2, OMP, and Crush; registry providers lack a direct transport; and the
+wizard retains its existing Standard/Advanced behavior. Those limitations must
+be addressed as implementation gaps, not carried forward as product policy.
+This documentation change does not itself remove runtime gates.
+
+Changes must be judged against user-observable behavior: selected routes are
+honored, executable best-effort paths remain available with truthful warnings,
+and Easy reaches a usable setup without an administration menu. Tests that
+encode arbitrary bans must change with the implementation, not preserve the bans.
+
+## Alternatives rejected
+
+- Treating current engine allowlists as immutable security requirements.
+- Blocking executable routes until every safety property can be verified.
+- Hiding unsupported guarantees behind a silent fallback or a false success.
+- Making a comprehensive settings dashboard the default first-run experience.
+- Maintaining separate setup implementations for Easy and Advanced.

package/docs/adr/README.md

@@ -0,0 +1,5 @@
+# Architecture decision records
+
+Record decisions that change public contracts, trust boundaries, persistence,
+or release architecture. Each ADR should state context, decision,
+consequences, alternatives, and status.

package/docs/cli-reference.md

@@ -8,3 +8,66 @@ 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.
+
+## `triss config wizard`
+
+Interactive setup, Easy by default; Advanced is an explicit choice. Both paths
+share the same resolution, persistence, and verification logic.
+
+```bash
+triss config wizard                      # Easy: provider + key, assistant hosts, summary, first command
+triss config wizard --advanced           # full sections: providers, execution, connections, integrations, runtime
+triss config wizard --standard           # explicit Easy path (alias of the default interactive flow)
+triss config wizard <target>             # a canonical provider id, `coder`, or an integration name (jira | linear | …)
+triss config wizard --local|--global     # project ./.triss.env or global ~/.config/triss/.env
+triss config wizard --yes                # non-interactive apply of a complete configuration from files + env + flags
+triss config wizard --agent <agent>      # headless host intent: claude | codex | both | none (non-TTY default: none)
+triss config wizard --install            # allow installing missing engines in a headless run
+triss config wizard coder --coder-protect-credentials    # persist TRISS_CODER_PROTECT_CREDENTIALS=true: proxy mode instead of the default best-effort raw
+triss config wizard coder --coder-no-protect-credentials # persist TRISS_CODER_PROTECT_CREDENTIALS=false: explicit raw; overrides TRISS_PROTECT_CREDENTIALS=true
+```
+
+Headless notes: `--yes` never turns a missing required key into a fake
+success — required keys are validated before anything is written, so a run
+that is incomplete at that point exits non-zero without writing. A run can
+still end incomplete after writing: engine setup runs after the env file and
+host configuration have been applied, so a skipped (no `--install`) or failed
+engine install is reported on top of the already-written configuration, and
+the run exits non-zero with that configuration preserved for a rerun. Engines
+are installed in a headless run only with `--install`; otherwise missing
+dependencies are reported. Reruns preserve existing explicit choices instead
+of resetting them. The wizard's coder-target flags are `--coder-engine <name>`,
+`--coder-provider <name>`, `--coder-protect-credentials`, and
+`--coder-no-protect-credentials` (the last two cannot be combined).
+
+## `triss init --setup`
+
+`triss init` writes the delegation block into agent rule files. With
+`-s, --setup` it hands control to `triss config wizard` BEFORE any rules
+write: the wizard owns which host files change, and its host actions invoke
+the rules pass with the agent/scope intent resolved during setup, so one
+command still produces a working setup. The wizard asks its own scope (or
+defaults silently to global in non-TTY).
+
+## Credential protection flags
+
+Model-backed commands (`ask`, `chat`, `write`, `review`, `fetch`,
+`commit-msg`) and coder commands accept:
+
+- `--protect-credentials` — request the parent-owned credential proxy. When a
+  verified protected route is unavailable for the selected engine, the run
+  falls back to best-effort raw execution with a warning (MCP results carry it
+  in structured `warnings`).
+- `--no-protect-credentials` — override a persisted
+  `TRISS_PROTECT_CREDENTIALS=true` (or `TRISS_CODER_PROTECT_CREDENTIALS=true`)
+  choice for one run. For crush this is the explicit raw exit from its
+  protected default.
+
+`triss config wizard` accepts the coder-target pair
+`--coder-protect-credentials` / `--coder-no-protect-credentials`. They persist
+`TRISS_CODER_PROTECT_CREDENTIALS=true` (configure the parent-owned credential
+proxy mode instead of the default best-effort raw) or `=false` (persist an
+explicit unprotected choice; the coder-specific value takes precedence over a
+persisted `TRISS_PROTECT_CREDENTIALS=true`). The two flags cannot be combined.
+
+See [configuration.md](configuration.md) for the persisted tri-state semantics.

package/docs/configuration.md

@@ -26,8 +26,10 @@ Configuration is read once per command or MCP request into an immutable snapshot
 `process.env` always wins. Project configuration overrides global configuration. Provider selection, model roles, endpoint, credential, and provenance are resolved together.
 
 ```bash
-triss config wizard                 # guided global setup
+triss config wizard                 # Easy setup: provider + key, assistant hosts, first command
+triss config wizard --advanced      # full Advanced sections (providers, execution, connections, integrations, runtime)
 triss config wizard --local         # guided project setup
+triss config wizard <target>        # canonical provider id, coder, or integration name
 triss config set KEY [value]        # global by default
 triss config set KEY [value] --local
 triss config get KEY
@@ -68,8 +70,46 @@ Global runtime fields:
 | `TRISS_CONFIG_SCHEMA` | `2` | Persisted configuration schema |
 | `TRISS_DEFAULT_PROVIDER` | `openai-compatible` | Provider selected when a request omits `provider` |
 | `TRISS_DEFAULT_ENGINE` | `direct` | Execution engine selected when a model request omits `engine` |
+| `TRISS_DEFAULT_EFFORT` | unset | Effort for model tasks when a request omits `effort`; absence keeps the provider default |
+| `TRISS_CODER_PROVIDER` | unset | Coding provider default; when absent it inherits `TRISS_DEFAULT_PROVIDER` |
+| `TRISS_CODER_EFFORT` | unset | Coding effort override; when absent it inherits `TRISS_DEFAULT_EFFORT` |
+| `TRISS_PROTECT_CREDENTIALS` | unset (tri-state) | Persisted credential-protection choice for model-backed and coder routes |
+| `TRISS_CODER_PROTECT_CREDENTIALS` | unset (tri-state) | Coding-only override of `TRISS_PROTECT_CREDENTIALS` |
+| `TRISS_MODEL_TRANSPORTS` | unset | Exact-model direct transport override map |
 | `TRISS_REQUEST_TIMEOUT_MS` | SDK default | Model request timeout |
 
+`TRISS_CODER_PROVIDER` selects the provider profile for coding runs only; it
+never rewrites `TRISS_DEFAULT_PROVIDER`, so `triss ask` / `triss review`
+defaults are unaffected by coder configuration.
+
+### Credential protection tri-state
+
+`TRISS_PROTECT_CREDENTIALS` and `TRISS_CODER_PROTECT_CREDENTIALS` accept three
+meaningful states — absent, `true`, or `false` — and the string `"false"` is
+never treated as a truthy opt-in. Resolution order: an explicit per-run flag
+(`--protect-credentials` / `--no-protect-credentials`) wins; otherwise
+`TRISS_CODER_PROTECT_CREDENTIALS` (coder runs) or `TRISS_PROTECT_CREDENTIALS`
+applies. `true` selects the parent-owned credential proxy; `false` explicitly
+selects a best-effort raw run (warned). When no choice is expressed, each route
+uses its recommended default — `crush` defaults to the protected proxy; the
+other engines default to best-effort raw handling — so an explicit `false`
+means something different from an unset value.
+
+### Model transport overrides
+
+`TRISS_MODEL_TRANSPORTS` is a JSON map of exact `"canonical-provider/native-model"`
+selectors to direct transport ids (`openai-chat`, `openai-responses`,
+`anthropic-messages`):
+
+```bash
+triss config set TRISS_MODEL_TRANSPORTS '{"opencode-go/muse-spark-1.3-contributor": "openai-responses"}'
+```
+
+It is an expert protocol clarification for specific models — never an allowlist
+of permitted models. OpenCode Zen and Go models resolve through their audited
+per-model transport catalogue first; the override pins the transport for an
+exact model when the catalogue cannot.
+
 ## Model roles and request selection
 
 Model-backed commands declare either the `model` role or the `smallModel` role. Each provider owns both native model ids.
@@ -78,15 +118,23 @@ Model-backed commands declare either the `model` role or the `smallModel` role.
 - `model` is a native model id for direct CLI/MCP commands.
 - `engine` selects `direct`, `opencode`, `opencode2`, `omp`, or `crush`; when omitted, `TRISS_DEFAULT_ENGINE` applies.
 - coder `--model` accepts a canonical `<provider>/<model-id>` selector; the small role comes from that provider's `*_SMALL_MODEL` field.
-- `effort` accepts `minimal`, `low`, `medium`, `high`, or `max`.
+- `effort` accepts `low`, `medium`, `high`, `xhigh`, or `max`.
 - `max_tokens` remains a separate output cap.
 
 There are no public model presets. Omit `model` to use the selected provider role.
 
-Provider and engine defaults resolve independently. Registry-backed providers
-such as `opencode-go` require an engine-backed default instead of `direct`.
-Read-only model projection is currently verified only for `opencode`;
-`opencode2`, `omp`, and `crush` are rejected before launch for non-coder tasks.
+Provider and engine defaults resolve independently. The `direct` engine serves
+providers with native HTTP transport metadata: `openai-compatible`, `zai`,
+`moonshot`, and `kimi-for-coding` natively, and `opencode-zen` / `opencode-go`
+models through audited per-model transports (OpenAI Chat, OpenAI Responses, or
+Anthropic Messages). A model without resolvable direct metadata fails with the
+stable `TRISS_DIRECT_ENGINE_REQUIRED` error and an actionable remedy: set a
+`TRISS_MODEL_TRANSPORTS` entry for that exact model or run it on a native
+engine (`opencode`, `opencode2`, `omp`, or `crush`).
+
+Every engine can execute non-coder model projections (`ask`, `review`, `chat`,
+…); engines without a verified read-only projection report their concrete
+limitation as a warning on the execution result, never as a refusal.
 
 Examples:
 
@@ -123,7 +171,7 @@ retained in the execution result and MCP structured output.
 ```bash
 triss coder init --engine opencode --provider zai
 triss coder init --engine opencode2 --provider opencode-zen
-triss coder init --engine crush --provider zai
+triss coder init --engine crush --provider moonshot
 triss coder init --engine omp --provider opencode-go
 ```