@chorus-aidlc/chorus 0.16.4 → 0.17.1

package/.next/standalone/public/chorus-plugin/bin/tests/test-mcp-cli-delegation.sh

@@ -0,0 +1,244 @@
+#!/usr/bin/env bash
+# test-mcp-cli-delegation.sh — prove the prefer-CLI / curl-fallback delegation
+# added to every bash MCP wrapper (Decision 1 of the "retire bootstrap + migrate
+# MCP path" tech design). One shared harness covers all four bash surfaces:
+#
+#   Claude Code : public/chorus-plugin/bin/chorus-api.sh   (mcp-tool)
+#   Kiro        : public/kiro-plugin/bin/chorus-api.sh      (mcp-tool)
+#   Codex       : plugins/chorus/hooks/chorus-mcp-call.sh
+#   Pi          : packages/chorus-pi/bin/chorus-mcp-call.sh
+#
+# (The dsh wrapper is a Node script — covered by tests/mcp-call-delegation.test.ts.)
+#
+# Contract asserted per surface:
+#   A. `chorus` on PATH (>= 0.17.0) -> delegates `chorus mcp call <tool> <json> --url … --api-key …`,
+#      propagating its stdout verbatim and exit 0.
+#   B. `chorus` present but FAILING -> propagates its non-zero exit (7) and stderr;
+#      NEVER falls back to curl (no double request / masked failure).
+#   C. CHORUS_MCP_NO_CLI=1 (escape hatch) -> ignores the CLI, takes the curl path.
+#   D. `chorus` absent -> takes the curl path.
+#   E. `chorus` present at a higher version (1.2.0, major>0) -> still delegates.
+#   F. `chorus` present but TOO OLD (0.16.4) -> version-gate error naming
+#      `npm install -g @chorus-aidlc/chorus` + the >= 0.17.0 floor; non-zero exit;
+#      NO `chorus mcp call` delegation and NO curl fallback.
+#   G. `chorus` present but version UNPARSEABLE -> same upgrade error, no delegation.
+#
+# Bash 3.2 compatible. No `set -e`: several scenarios intentionally run commands
+# that exit non-zero, and we assert on the captured exit code.
+
+set -uo pipefail
+
+ROOT=$(cd "$(dirname "$0")/../../../.." && pwd)
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+
+ORIG_PATH="$PATH"
+
+# ---- shared credentials + throwaway state locations -----------------------
+export CHORUS_URL="http://127.0.0.1:1"     # guaranteed-unreachable -> curl fails fast
+export CHORUS_API_KEY="cho_testkey"
+export CHORUS_PLUGIN_STATE_ROOT="$TMP/global"   # CC state (via chorus-paths.sh)
+export CHORUS_STATE_DIR="$TMP/state"            # Kiro state (direct)
+export CLAUDE_PROJECT_DIR="$TMP/proj"
+export CHORUS_SESSION_ID="testsess"
+export CHORUS_FAKE_ARGS="$TMP/fake-args"
+export CHORUS_FAKE_MARKER="$TMP/fake-marker"
+mkdir -p "$CLAUDE_PROJECT_DIR"
+
+TOOL="chorus_checkin"
+JSON='{"foo":"bar"}'   # no spaces -> deterministic "$*" comparison in the fake
+EXPECTED_ARGS="mcp call $TOOL $JSON --url $CHORUS_URL --api-key $CHORUS_API_KEY"
+# Profile-path (CHORUS_AGENT_PROFILE) expectations. A real agentName with a space
+# proves the wrapper quotes it as a single argv element (the fake joins argv with
+# spaces, so a broken quote would show up as extra tokens here).
+PROFILE="Admin Claude"
+EXPECTED_PROFILE_ARGS="mcp call $TOOL $JSON --agent $PROFILE"
+
+# ---- fake `chorus` binary -------------------------------------------------
+# `chorus --version` prints $CHORUS_FAKE_VERSION (a chosen X.Y.Z, or garbage to
+# exercise the unparseable branch) and exits 0 WITHOUT touching the marker/args —
+# so the marker proves a real `chorus mcp call` delegation, never a version probe.
+# For any other argv it records its argv (joined) + a marker proving it ran, then
+# succeeds with a sentinel on stdout or fails (exit 7) with a sentinel on stderr.
+FAKEBIN="$TMP/fakebin"
+mkdir -p "$FAKEBIN"
+cat > "$FAKEBIN/chorus" <<'FAKE'
+#!/usr/bin/env bash
+if [ "$1" = "--version" ]; then
+  printf '%s\n' "${CHORUS_FAKE_VERSION:-0.17.0}"
+  exit 0
+fi
+printf '%s\n' "$*" > "$CHORUS_FAKE_ARGS"
+: > "$CHORUS_FAKE_MARKER"
+if [ "${CHORUS_FAKE_MODE:-ok}" = "fail" ]; then
+  printf 'CHORUS_CLI_SENTINEL_FAIL\n' >&2
+  exit 7
+fi
+printf 'CHORUS_CLI_SENTINEL_OK\n'
+exit 0
+FAKE
+chmod +x "$FAKEBIN/chorus"
+
+# ---- a sanitized PATH with every real tool EXCEPT `chorus` ----------------
+# Guarantees `command -v chorus` is false for scenario D even if a real chorus
+# happens to be installed on the host, while keeping curl/sed/mkdir/etc. available.
+CLEANBIN="$TMP/cleanbin"
+mkdir -p "$CLEANBIN"
+_oifs="$IFS"; IFS=:
+for _d in $ORIG_PATH; do
+  [ -d "$_d" ] || continue
+  for _f in "$_d"/*; do
+    [ -e "$_f" ] || continue
+    _b="${_f##*/}"
+    [ "$_b" = "chorus" ] && continue
+    [ -e "$CLEANBIN/$_b" ] || ln -s "$_f" "$CLEANBIN/$_b" 2>/dev/null || true
+  done
+done
+IFS="$_oifs"
+
+# ---- assertion helpers ----------------------------------------------------
+FAILS=0
+ok()  { printf '    ok   %s\n' "$1"; }
+bad() { printf '    FAIL %s\n' "$1"; FAILS=$((FAILS + 1)); }
+contains() { case "$1" in *"$2"*) return 0 ;; *) return 1 ;; esac; }
+
+# run_case <PATHVAL> <hatch:0|1> <fmode:ok|fail> [version]  -> stdout on fd1, stderr to $TMP/err
+# [version] is what the fake `chorus --version` prints (default 0.17.0 = delegates).
+run_case() {
+  (
+    export PATH="$1"
+    export CHORUS_FAKE_MODE="$3"
+    export CHORUS_FAKE_VERSION="${4:-0.17.0}"
+    if [ "$2" = "1" ]; then export CHORUS_MCP_NO_CLI=1; else unset CHORUS_MCP_NO_CLI; fi
+    if [ "$MODE" = "mcp-tool" ]; then
+      exec bash "$WRAPPER" mcp-tool "$TOOL" "$JSON"
+    else
+      exec bash "$WRAPPER" "$TOOL" "$JSON"
+    fi
+  )
+}
+
+# run_profile_case <PATHVAL> <unset_urlkey:0|1> -> exercises CHORUS_AGENT_PROFILE
+# with a usable CLI (0.17.0). unset_urlkey=1 proves profile mode needs no url/key;
+# =0 proves the profile is PREFERRED even when url/key are also present.
+run_profile_case() {
+  (
+    export PATH="$1"
+    export CHORUS_FAKE_MODE="ok"
+    export CHORUS_FAKE_VERSION="0.17.0"
+    unset CHORUS_MCP_NO_CLI
+    export CHORUS_AGENT_PROFILE="$PROFILE"
+    if [ "$2" = "1" ]; then unset CHORUS_URL CHORUS_API_KEY; fi
+    if [ "$MODE" = "mcp-tool" ]; then
+      exec bash "$WRAPPER" mcp-tool "$TOOL" "$JSON"
+    else
+      exec bash "$WRAPPER" "$TOOL" "$JSON"
+    fi
+  )
+}
+
+# ---- per-surface scenarios ------------------------------------------------
+while read -r NAME MODE REL; do
+  [ -n "${NAME:-}" ] || continue
+  case "$NAME" in \#*) continue ;; esac
+  WRAPPER="$ROOT/$REL"
+  if [ ! -f "$WRAPPER" ]; then bad "$NAME: wrapper not found: $REL"; continue; fi
+  printf '  %s (%s)\n' "$NAME" "$REL"
+
+  # A. present + ok -> delegates, verbatim stdout, verbatim args, exit 0
+  rm -f "$CHORUS_FAKE_MARKER" "$CHORUS_FAKE_ARGS"
+  OUT=$(run_case "$FAKEBIN:$ORIG_PATH" 0 ok 2>"$TMP/err"); RC=$?
+  contains "$OUT" "CHORUS_CLI_SENTINEL_OK" && ok "A: delegates stdout verbatim" \
+    || bad "A: stdout missing CLI sentinel (got: $OUT)"
+  GOTARGS=$(head -1 "$CHORUS_FAKE_ARGS" 2>/dev/null || true)
+  [ "$GOTARGS" = "$EXPECTED_ARGS" ] && ok "A: forwards args + explicit creds" \
+    || bad "A: arg mismatch (want [$EXPECTED_ARGS] got [$GOTARGS])"
+  [ "$RC" = "0" ] && ok "A: exit 0 propagated" || bad "A: exit $RC != 0"
+
+  # B. present + fail -> propagate exit 7 and stderr, NO curl fallback
+  rm -f "$CHORUS_FAKE_MARKER" "$CHORUS_FAKE_ARGS"
+  OUT=$(run_case "$FAKEBIN:$ORIG_PATH" 0 fail 2>"$TMP/err"); RC=$?
+  [ "$RC" = "7" ] && ok "B: propagates failing exit 7 (no curl retry)" \
+    || bad "B: exit $RC != 7 (fallback masked the failure?)"
+  [ -e "$CHORUS_FAKE_MARKER" ] && ok "B: CLI was invoked" || bad "B: CLI not invoked"
+  contains "$(cat "$TMP/err" 2>/dev/null)" "CHORUS_CLI_SENTINEL_FAIL" \
+    && ok "B: CLI stderr propagated" || bad "B: CLI stderr not propagated"
+
+  # C. escape hatch -> skip CLI, take curl path
+  rm -f "$CHORUS_FAKE_MARKER" "$CHORUS_FAKE_ARGS"
+  OUT=$(run_case "$FAKEBIN:$ORIG_PATH" 1 ok 2>"$TMP/err"); RC=$?
+  [ ! -e "$CHORUS_FAKE_MARKER" ] && ok "C: CHORUS_MCP_NO_CLI skips the CLI" \
+    || bad "C: CLI invoked despite escape hatch"
+  contains "$OUT" "CHORUS_CLI_SENTINEL_OK" && bad "C: delegated despite escape hatch" \
+    || ok "C: no delegation (curl path)"
+
+  # D. absent -> take curl path
+  rm -f "$CHORUS_FAKE_MARKER" "$CHORUS_FAKE_ARGS"
+  OUT=$(run_case "$CLEANBIN" 0 ok 2>"$TMP/err"); RC=$?
+  [ ! -e "$CHORUS_FAKE_MARKER" ] && ok "D: absent chorus -> no delegation" \
+    || bad "D: CLI invoked when absent"
+  contains "$OUT" "CHORUS_CLI_SENTINEL_OK" && bad "D: delegated when absent" \
+    || ok "D: fell back to curl path"
+
+  # E. present at a higher version (1.2.0, major>0) -> still delegates
+  rm -f "$CHORUS_FAKE_MARKER" "$CHORUS_FAKE_ARGS"
+  OUT=$(run_case "$FAKEBIN:$ORIG_PATH" 0 ok 1.2.0 2>"$TMP/err"); RC=$?
+  contains "$OUT" "CHORUS_CLI_SENTINEL_OK" && ok "E: v1.2.0 delegates" \
+    || bad "E: v1.2.0 did not delegate (got: $OUT)"
+  [ -e "$CHORUS_FAKE_MARKER" ] && ok "E: CLI mcp-call invoked" || bad "E: CLI not invoked"
+  [ "$RC" = "0" ] && ok "E: exit 0 propagated" || bad "E: exit $RC != 0"
+
+  # F. present but too old (0.16.4) -> upgrade error, non-zero, NO delegation, NO curl
+  rm -f "$CHORUS_FAKE_MARKER" "$CHORUS_FAKE_ARGS"
+  OUT=$(run_case "$FAKEBIN:$ORIG_PATH" 0 ok 0.16.4 2>"$TMP/err"); RC=$?
+  ERR=$(cat "$TMP/err" 2>/dev/null || true)
+  [ "$RC" != "0" ] && ok "F: too-old exits non-zero" || bad "F: too-old exited 0"
+  [ ! -e "$CHORUS_FAKE_MARKER" ] && ok "F: no mcp-call delegation" || bad "F: delegated to an old CLI"
+  contains "$OUT" "CHORUS_CLI_SENTINEL_OK" && bad "F: delegated stdout leaked" \
+    || ok "F: no delegated stdout"
+  contains "$ERR" "npm install -g @chorus-aidlc/chorus" \
+    && ok "F: error names npm upgrade command" || bad "F: error missing npm upgrade command"
+  contains "$ERR" "0.17.0" && ok "F: error names >= 0.17.0 floor" || bad "F: error missing floor"
+  contains "$ERR" "MCP initialize failed" && bad "F: fell back to curl (gate leaked)" \
+    || ok "F: no curl fallback"
+
+  # G. present but version unparseable -> same upgrade error, non-zero, NO delegation
+  rm -f "$CHORUS_FAKE_MARKER" "$CHORUS_FAKE_ARGS"
+  OUT=$(run_case "$FAKEBIN:$ORIG_PATH" 0 ok "not-a-version" 2>"$TMP/err"); RC=$?
+  ERR=$(cat "$TMP/err" 2>/dev/null || true)
+  [ "$RC" != "0" ] && ok "G: garbage version exits non-zero" || bad "G: garbage version exited 0"
+  [ ! -e "$CHORUS_FAKE_MARKER" ] && ok "G: no delegation on garbage version" \
+    || bad "G: delegated on garbage version"
+  contains "$ERR" "npm install -g @chorus-aidlc/chorus" \
+    && ok "G: garbage error names npm upgrade command" || bad "G: garbage error missing npm upgrade"
+
+  # H. CHORUS_AGENT_PROFILE + usable CLI, NO url/key -> delegates by profile,
+  #    forwarding `--agent <profile>` (and NOT --url/--api-key), exit 0.
+  rm -f "$CHORUS_FAKE_MARKER" "$CHORUS_FAKE_ARGS"
+  OUT=$(run_profile_case "$FAKEBIN:$ORIG_PATH" 1 2>"$TMP/err"); RC=$?
+  contains "$OUT" "CHORUS_CLI_SENTINEL_OK" && ok "H: profile-only delegates (no url/key)" \
+    || bad "H: profile-only did not delegate (out: $OUT; err: $(cat "$TMP/err" 2>/dev/null))"
+  GOTARGS=$(head -1 "$CHORUS_FAKE_ARGS" 2>/dev/null || true)
+  [ "$GOTARGS" = "$EXPECTED_PROFILE_ARGS" ] && ok "H: forwards --agent <profile>" \
+    || bad "H: profile arg mismatch (want [$EXPECTED_PROFILE_ARGS] got [$GOTARGS])"
+  [ "$RC" = "0" ] && ok "H: exit 0 propagated" || bad "H: exit $RC != 0"
+
+  # I. CHORUS_AGENT_PROFILE is PREFERRED over url+key when both are set.
+  rm -f "$CHORUS_FAKE_MARKER" "$CHORUS_FAKE_ARGS"
+  OUT=$(run_profile_case "$FAKEBIN:$ORIG_PATH" 0 2>"$TMP/err"); RC=$?
+  GOTARGS=$(head -1 "$CHORUS_FAKE_ARGS" 2>/dev/null || true)
+  [ "$GOTARGS" = "$EXPECTED_PROFILE_ARGS" ] && ok "I: profile preferred over url+key" \
+    || bad "I: expected --agent delegation, got [$GOTARGS]"
+done <<EOF
+CC     mcp-tool  public/chorus-plugin/bin/chorus-api.sh
+KIRO   mcp-tool  public/kiro-plugin/bin/chorus-api.sh
+CODEX  direct    plugins/chorus/hooks/chorus-mcp-call.sh
+PI     direct    packages/chorus-pi/bin/chorus-mcp-call.sh
+EOF
+
+echo ""
+if [ "$FAILS" -gt 0 ]; then
+  echo "mcp-cli-delegation: $FAILS check(s) FAILED"
+  exit 1
+fi
+echo "mcp-cli-delegation: all bash-wrapper delegation checks PASS"

package/.next/standalone/public/chorus-plugin/skills/brainstorm/SKILL.md

@@ -4,7 +4,7 @@ description: Optional divergent-then-convergent dialogue for fuzzy ideas. Invoke
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.16.4"
+  version: "0.17.0"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/chorus-plugin/skills/chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus AI Agent collaboration platform — overview, common tools,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.16.4"
+  version: "0.17.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -359,6 +359,24 @@ openspec init --tools claude        # 2. scaffold openspec/ + wire up Claude Cod
 
 To turn it off, flip `enableOpenSpec` to `false` or set `CHORUS_OPENSPEC_MODE=off` — the banner then reads a neutral `(OpenSpec off)`.
 
+### 7. Daemon auto-start via `chorus agents add`
+
+`chorus agents add` runs an ordered set of steps to wire this machine to Chorus. Its final step — **daemon-setup** — configures the local Chorus daemon and, opt-in, installs it as a boot-autostart service.
+
+- **What it configures.** Reusing the same preflight as `chorus daemon install`, it persists the served working directories (`cwds`) and the default backend agent into `~/.chorus/daemon.json`. Credentials are the **connection credentials only** — the Chorus URL + API key (`cho_…`) seeded earlier in the run. `chorus agents add` never collects or stores model-provider secrets (see the limitation below).
+- **Opt-in auto-start.**
+  - Interactive (TTY): it asks *"Install & enable the Chorus daemon to auto-start on boot?"* — **default No**. Answer yes to install.
+  - Non-interactive (non-TTY, or `--yes`): it installs the boot service **only** when you pass `--daemon-autostart`; otherwise it writes `~/.chorus/daemon.json` and leaves starting the daemon to you (`chorus daemon`).
+- **Platform support.** Auto-start is a *real* boot service on **Linux (systemd `--user`)** and **macOS (launchd LaunchAgent)** — both start now and at every login. On other platforms (e.g. Windows) it writes the config and prints the manual start steps instead of installing anything.
+- **Idempotent.** Re-running when the service is already installed reports it as already configured and changes nothing.
+- **Manage it.** `chorus daemon status | stop | restart | logs` transparently delegate to the installed supervisor (`systemctl --user` on Linux, `launchctl` on macOS); with no service installed they operate on the `chorus daemon -d` pidfile/log as before.
+
+> **⚠️ Provider credentials on a boot service (important).** A boot-launched daemon (systemd `--user` or launchd) starts in a **clean environment** and does **not** inherit your shell-exported model-provider secrets (`ANTHROPIC_API_KEY`, `AWS_*` / `CLAUDE_CODE_USE_BEDROCK`, etc.). Chorus keeps `daemon.json` to the Chorus connection credentials only, so you must supply provider credentials to the service's environment yourself:
+> - **Linux (systemd):** add a drop-in `~/.config/systemd/user/chorus-daemon.service.d/env.conf` containing `[Service]` + `Environment=ANTHROPIC_API_KEY=…` then `systemctl --user daemon-reload && systemctl --user restart chorus-daemon.service`; or place the vars in `~/.config/environment.d/*.conf`.
+> - **macOS (launchd):** `launchctl setenv ANTHROPIC_API_KEY …` (before load), or add an `EnvironmentVariables` dict to `~/Library/LaunchAgents/com.chorus.daemon.plist`.
+>
+> Without this, a boot-started daemon reaches Chorus fine but its spawned agents may fail to reach the model provider.
+
 ---
 
 ## Execution Rules

package/.next/standalone/public/chorus-plugin/skills/chorus-cli/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: chorus-cli
+description: How to install, configure, and use the `chorus` CLI — install it, manage agents with `chorus agents` (add/remove/list), the connection environment variables, and MCP operations via `chorus mcp`. A concise shared reference for any flow that drives Chorus from the shell.
+license: AGPL-3.0
+metadata:
+  author: chorus
+  version: "0.17.0"
+  category: project-management
+  mcp_server: chorus
+---
+
+# chorus-cli — using the `chorus` CLI
+
+`chorus` (published as `@chorus-aidlc/chorus`) is the one command that configures this
+machine's coding agents for Chorus and talks to the Chorus MCP endpoint from the shell.
+This is a concise reference — run `chorus --help` and `chorus <command> --help` for the
+full flag surface.
+
+## 1. Install
+
+```bash
+npm install -g @chorus-aidlc/chorus       # unpinned — always installs the latest
+chorus --version                          # must be >= 0.17.0 (provides `chorus agents` + `chorus mcp`)
+```
+
+## 2. Configure agents — `chorus agents`
+
+Agent configuration lives in `~/.chorus/daemon.json`; `chorus agents` is the CRUD group:
+
+- `chorus agents` (or `chorus agents list`) — list configured agents (name, UUID, backend).
+  The API key is never printed; the agent named by `CHORUS_AGENT_PROFILE` is marked.
+- `chorus agents add [--agents <ids>] [--all] [--url <u>] [--api-key <cho_…>] [--yes] [--dsh-profile <name>]`
+  — detect installed coding agents, install each one's Chorus plugin, and seed credentials
+  (this is the former `chorus init`). Idempotent; safe to re-run. `--help` lists every flag.
+- `chorus agents remove <name|uuid>` — remove a configured agent from `~/.chorus/daemon.json`
+  (matched by UUID or name; an ambiguous name → use the UUID).
+
+## 3. Connection environment variables
+
+- `CHORUS_URL` — the Chorus instance URL.
+- `CHORUS_API_KEY` — an agent API key (`cho_…`).
+- `CHORUS_AGENT_PROFILE` — optional name or UUID of the agent to act as. When set, `chorus mcp`
+  resolves that agent's key from `~/.chorus/daemon.json`, so you need not export
+  `CHORUS_API_KEY` for the CLI path. Daemon-woken sessions receive it automatically.
+
+## 4. MCP operations — `chorus mcp`
+
+Call any Chorus MCP tool from the shell — a byte-exact, token-free path for large content:
+
+- `chorus mcp call <tool> ['<json>'] [--arg-file key=<file>] [--agent <name|uuid>]` — call a tool.
+  `--arg-file content=<file>` streams a file's raw bytes into the JSON `content` string (no
+  re-typing through the model). Identity resolves from `--agent` → `CHORUS_AGENT_PROFILE` →
+  `CHORUS_URL`+`CHORUS_API_KEY` → a single configured agent.
+- `chorus mcp whoami` — print this agent's own UUID.
+- `chorus mcp list` — list the tools this agent may call.
+
+Requires `chorus >= 0.17.0` (the `chorus mcp` subcommand). See `chorus mcp --help`.

package/.next/standalone/public/chorus-plugin/skills/develop/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Development workflow — claim tasks, report work, manage se
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.16.4"
+  version: "0.17.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -134,7 +134,7 @@ Each task and proposal includes a `commentCount` field — use it to decide whic
    chorus_get_documents({ projectUuid: "<project-uuid>" })
    ```
 
-> **Document update flow (OpenSpec mode):** if the originating proposal `description` contains a line `OpenSpec change slug: <slug>`, the project's PRD / tech_design / spec Documents are **mirrors** of files under `openspec/changes/<slug>/`. To update such a Document (e.g. clarify an AC, fix a spec scenario before resubmitting), load the `openspec-aware` skill at `.claude/skills/openspec-aware/SKILL.md` and follow §3.8: edit the local `.md` file first, then mirror through the `chorus-api.sh` wrapper with `json_encode_file` and `chorus_check_response`.
+> **Document update flow (OpenSpec mode):** if the originating proposal `description` contains a line `OpenSpec change slug: <slug>`, the project's PRD / tech_design / spec Documents are **mirrors** of files under `openspec/changes/<slug>/`. To update such a Document (e.g. clarify an AC, fix a spec scenario before resubmitting), load the `openspec-aware` skill at `.claude/skills/openspec-aware/SKILL.md` and follow §3.8: edit the local `.md` file first, then mirror it — prefer `chorus mcp call … --arg-file content=<file>`, falling back to the `chorus-api.sh` wrapper with `json_encode_file` when `chorus` is not on `PATH` — with `chorus_check_response` halting on error.
 >
 > **⛔ Do not** call `chorus_pm_update_document` directly from the MCP harness with a hand-typed `content` field in OpenSpec mode. The local file is the source of truth; agent-typed content drifts and burns tokens (`openspec-aware` §2 Rule 1).
 >

package/.next/standalone/public/chorus-plugin/skills/docs/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus documentation router — consult the live Chorus docs site t
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.16.4"
+  version: "0.17.0"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/chorus-plugin/skills/idea/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Idea workflow — claim ideas, run elaboration rounds, and p
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.16.4"
+  version: "0.17.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -39,7 +39,7 @@ All post-elaboration progress (planning, building, verifying, done) is **derived
 | `chorus_edit_idea` | Edit an existing idea's title, description, and/or lineage parent. `parentUuid`: another same-project idea to reparent under, `null` to detach to top-level, omit to leave unchanged (cycle-checked + same-project). Single-parent **weak** lineage — a parent shows a read-only `+N derived` rollup but never blocks either idea's flow. Records an "edited" activity and signals presence. |
 | `chorus_claim_idea` | Claim an open idea (open -> elaborating) |
 | `chorus_release_idea` | Release a claimed idea (elaborating -> open) |
-| `chorus_pm_assign_idea` | Assign an idea to an agent (must hold `idea:write`) or a user, on a human's behalf — the counterpart to `chorus_claim_idea` (self-claim). Silently takes over any existing assignee; an `open` idea moves to `elaborating`, any other status is preserved. Optional `instanceUuid` pins an **agent** assignment to a specific AgentInstance (agent-only). Assigning to an agent wakes it best-effort (offline still persists the assignment); assigning to a user notifies them with no daemon wake. Requires `idea:admin`. |
+| `chorus_pm_assign_idea` | Assign an idea to an agent (must hold `idea:write`) or a user, on a human's behalf — the counterpart to `chorus_claim_idea` (self-claim). Silently takes over any existing assignee; an `open` idea moves to `elaborating`, any other status is preserved. Optional `instanceUuid` pins an **agent** assignment to a specific AgentInstance (agent-only) — but a project-fixed cwd target configured for the owner takes precedence and supplies the instance automatically, overriding `instanceUuid`. Assigning a **new** owner wakes it best-effort (offline still persists the assignment); re-assigning the same owner may update its pin/cwd but is wake-deduplicated. Assigning to a user notifies them with no daemon wake. Requires `idea:admin`. |
 | `chorus_move_idea` | Move an Idea to a different Project. Cascade-migrates the Idea **and its full lineage subtree** (all descendant Ideas; the moved root is detached from any parent left behind), all linked Proposals (any status), all materialized Documents and Tasks, and all related Activities atomically. Comments, TaskDependency, AcceptanceCriterion, AgentSession, SessionTaskCheckin, Notification history, and Task assignees are NOT modified. Returns `moved: { ideas, proposals, documents, tasks, activities }` counts. Requires `idea:write` only — no project-level checks. |
 
 **Requirements Elaboration:**

package/.next/standalone/public/chorus-plugin/skills/openspec-aware/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: openspec-aware
-description: Opt-in OpenSpec-mode authoring for Chorus PM workflows in Claude Code. Detects the local `openspec` CLI, scaffolds `openspec/changes/<slug>/` on disk, and mirrors Markdown files into Chorus document drafts via the `chorus-api.sh` wrapper. Required reading for the proposal, develop, and yolo skills whenever the user has the `openspec` CLI installed.
+description: Opt-in OpenSpec-mode authoring for Chorus PM workflows in Claude Code. Detects the local `openspec` CLI, scaffolds `openspec/changes/<slug>/` on disk, and mirrors Markdown files into Chorus document drafts via `chorus mcp call --arg-file` (bash `chorus-api.sh` wrapper as fallback). Required reading for the proposal, develop, and yolo skills whenever the user has the `openspec` CLI installed.
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.16.4"
+  version: "0.17.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -77,21 +77,22 @@ Use this only when SessionStart context is genuinely unavailable — duplicating
 
 Both are enforced at review time. Both have caused incidents in past releases.
 
-### Rule 1 — Mirror via the wrapper, never re-type document content from agent output
+### Rule 1 — Fill `content` from the file (CLI preferred, bash-wrapper fallback); never re-type document content from agent output
 
-Document/draft mirror calls (`chorus_pm_add_document_draft`, `chorus_pm_update_document_draft`, `chorus_pm_update_document`) **MUST** go through:
+Document/draft mirror calls (`chorus_pm_add_document_draft`, `chorus_pm_update_document_draft`, `chorus_pm_update_document`) **MUST** fill the `content` field from the local file's bytes, never from a hand-typed body. Calling these tools directly from the agent's MCP harness with a hand-typed `content` field is a **protocol violation** for OpenSpec mode and will fail review. Use whichever transport is available, preferred first:
 
-```
-chorus-api.sh mcp-tool <tool_name> "$PAYLOAD"
-```
+- **Primary — the `chorus` CLI:** `chorus mcp call <tool_name> '<json-without-content>' --arg-file content=<file>`. `--arg-file content=<path>` reads the file's raw bytes and injects them as the JSON `content` string, byte-exact — the CLI's built-in replacement for `json_encode_file`, so no helper is needed. See §3.6. **Requires chorus >= 0.17.0** (the `chorus mcp` subcommand was added then; an older CLI errors with "unknown command"); on any version or unknown-command failure, upgrade with `npm install -g @chorus-aidlc/chorus`.
+- **Fallback — the `chorus-api.sh` wrapper, when `chorus` is not on `PATH`:** build `$PAYLOAD` with the `json_encode_file` helper and call `chorus-api.sh mcp-tool <tool_name> "$PAYLOAD"` (`chorus-api.sh` is on `PATH` — call it by name). Defined in the §3.6 fallback block.
 
-`chorus-api.sh` is on `PATH` — call it by name.
+> **New to the `chorus` CLI?** See the **`chorus-cli`** skill for install, configuring agents (`chorus agents add|remove|list`), the connection env vars, and `chorus mcp` basics.
 
-with `$PAYLOAD` built using `json_encode_file` (defined in §3.4). Calling these tools directly from the agent's MCP harness with a hand-typed `content` field is a **protocol violation** for OpenSpec mode and will fail review. Reasons:
+> **Acting identity — which agent the call acts as.** `chorus mcp call` resolves the agent from, in order: `CHORUS_AGENT_PROFILE` (a name or UUID) → `CHORUS_URL` + `CHORUS_API_KEY` in the environment → the single agent configured in `~/.chorus/daemon.json`. A daemon-woken session already has `CHORUS_AGENT_PROFILE` set. If a mirror call fails with `Multiple agents … specify --agent` (several agents configured and no profile/creds in the env), pass your own identity explicitly: `chorus mcp call <tool> … --agent <your-agentUuid>` — your UUID is in your `chorus_checkin` result, and `chorus agents` lists every configured name/UUID.
 
-1. **Token cost.** Re-typing a multi-thousand-line markdown body through the LLM burns input + output tokens for every draft. The wrapper streams bytes through `jq -Rs '.'` — content never enters LLM context. A typical 3-doc proposal mirror via the script costs roughly zero content-tokens; via direct MCP it routinely costs 20k+.
-2. **Byte-equality.** `jq -Rs '.'` is a byte-faithful encoder: backslashes, quotes, newlines, code-fence content, zero-width chars all survive. LLM re-emission has a non-zero failure rate on long markdown — table alignment drifts, fence escapes get "fixed", long URLs wrap. The exact byte-equality guarantee holds **only** on the wrapper path.
-3. **Single source of truth.** With the wrapper, the local `openspec/changes/<slug>/*.md` is authoritative and Chorus is a mirror. With agent re-typing, authority splits between local file and whatever the LLM happened to output — a future diff cannot tell which one is correct.
+Reasons (they apply to both paths):
+
+1. **Token cost.** Re-typing a multi-thousand-line markdown body through the LLM burns input + output tokens for every draft. Both the CLI's `--arg-file` and the fallback's `json_encode_file` stream the file's bytes into the JSON string — content never enters LLM context. A typical 3-doc proposal mirror costs roughly zero content-tokens this way; via direct MCP with a re-typed body it routinely costs 20k+.
+2. **Byte-equality.** A file-fill path (CLI `--arg-file`, or the fallback's `jq -Rs '.'`) is a byte-faithful encoder: backslashes, quotes, newlines, code-fence content, zero-width chars all survive. LLM re-emission has a non-zero failure rate on long markdown — table alignment drifts, fence escapes get "fixed", long URLs wrap. The exact byte-equality guarantee holds **only** on a file-fill path, never on LLM re-emission.
+3. **Single source of truth.** With a file-fill mirror, the local `openspec/changes/<slug>/*.md` is authoritative and Chorus is a mirror. With agent re-typing, authority splits between local file and whatever the LLM happened to output — a future diff cannot tell which one is correct.
 
 ### Rule 2 — Halt on error via `chorus_check_response`
 
@@ -206,25 +207,12 @@ Optional:
 openspec validate "$SLUG"
 ```
 
-### 3.4 Helper: `json_encode_file`
+### 3.4 Filling the `content` field byte-exact
 
-Define once at the top of the authoring session. With `jq` available it streams the file into a JSON string; the fallback matches `chorus-api.sh`'s own escaping when `jq` is missing.
+The document `content` must be inserted **byte-for-byte** from the local file — never re-typed by the LLM. Two mechanisms, preferred first:
 
-```bash
-json_encode_file() {
-  local _path="$1"
-  if command -v jq >/dev/null 2>&1; then
-    jq -Rs '.' < "$_path"
-  else
-    local _content
-    _content=$(cat "$_path")
-    _content=${_content//\\/\\\\}
-    _content=${_content//\"/\\\"}
-    _content=${_content//$'\n'/\\n}
-    printf '"%s"' "$_content"
-  fi
-}
-```
+- **Primary — `chorus mcp call … --arg-file content=<path>`** (§3.6). The CLI reads the file's raw bytes and injects them as the JSON `content` string. This is the byte-faithful replacement for `json_encode_file`, so on the CLI path **no helper is needed** — pass the base JSON without a `content` field and let `--arg-file` fill it.
+- **Fallback — `json_encode_file`** (defined in the §3.6 fallback block, used only when `chorus` is not on `PATH`). With `jq` available it streams the file through `jq -Rs '.'`; the pure-shell branch matches `chorus-api.sh`'s own escaping when `jq` is missing.
 
 Round-trip verification is exact: a trailing newline difference is real drift and MUST NOT be normalized or ignored.
 
@@ -243,13 +231,46 @@ OpenSpec change slug: <slug>
 
 This line is machine-grep-able by future runs of this skill and by the §3.9 archive trigger.
 
-### 3.6 Mirror each document draft via the wrapper
+### 3.6 Mirror each document draft (CLI primary, wrapper fallback)
 
-> **Rule 1 reminder:** these calls go through `chorus-api.sh`, not direct MCP. The agent must not retype the document body.
+> **Rule 1 reminder:** `content` comes from the file's bytes, never a hand-typed body. The agent must not retype the document body.
 
-Define the halt-on-error helper from §6 once at the top, then run one call per file:
+Define the halt-on-error helper from §6 once at the top. **Primary path — the `chorus` CLI:** pass the base JSON *without* a `content` field and let `--arg-file content=<file>` fill it byte-exact. One call per file:
 
 ```bash
+# PRD draft — --arg-file fills content byte-exact from the file; no json_encode_file needed.
+RESULT=$(chorus mcp call chorus_pm_add_document_draft \
+  "{\"proposalUuid\":\"$PROPOSAL_UUID\",\"type\":\"prd\",\"title\":\"PRD: $HUMAN_TITLE\"}" \
+  --arg-file content="openspec/changes/$SLUG/proposal.md")
+RC=$?
+chorus_check_response "chorus_pm_add_document_draft (prd)" "$RC" "$RESULT"
+PRD_DRAFT_UUID=$(printf '%s' "$RESULT" | grep -o '"draftUuid"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+```
+
+Repeat with `type: "tech_design"` for `design.md`, and one call per capability with `type: "spec"` for each `specs/<capability>/spec.md`. Do **not** mirror `tasks.md` — Chorus task drafts (created via the `chorus_pm_add_task_draft` MCP tool, no wrapper needed) are the source of truth for tasks.
+
+> Why parsing uses `printf '%s' "$RESULT" | grep` not `echo "$RESULT" | jq`: `echo` interprets backslash sequences inside the captured JSON, turning embedded `\n` into a real newline. `jq` then aborts with `Invalid string: control characters from U+0000 through U+001F must be escaped`. `printf '%s'` emits the captured bytes verbatim. Same pattern applies to all wrapper-result parsing in this skill.
+
+#### Fallback — when the `chorus` CLI is not on `PATH`
+
+If `command -v chorus` fails, mirror through the bundled `chorus-api.sh` wrapper instead. Define `json_encode_file` here (it is used **only** on this fallback path), then build `$PAYLOAD` with an embedded `content` and call the wrapper. The `chorus_check_response` halt-on-error check applies exactly as on the primary path.
+
+```bash
+# Define once, fallback-only: byte-faithful file → JSON string.
+json_encode_file() {
+  local _path="$1"
+  if command -v jq >/dev/null 2>&1; then
+    jq -Rs '.' < "$_path"
+  else
+    local _content
+    _content=$(cat "$_path")
+    _content=${_content//\\/\\\\}
+    _content=${_content//\"/\\\"}
+    _content=${_content//$'\n'/\\n}
+    printf '"%s"' "$_content"
+  fi
+}
+
 # chorus-api.sh is on PATH — no absolute path needed.
 # PRD draft
 CONTENT=$(json_encode_file "openspec/changes/$SLUG/proposal.md")
@@ -268,13 +289,19 @@ chorus_check_response "chorus_pm_add_document_draft (prd)" "$RC" "$RESULT"
 PRD_DRAFT_UUID=$(printf '%s' "$RESULT" | grep -o '"draftUuid"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
 ```
 
-Repeat with `type: "tech_design"` for `design.md`, and one call per capability with `type: "spec"` for each `specs/<capability>/spec.md`. Do **not** mirror `tasks.md` — Chorus task drafts (created via the `chorus_pm_add_task_draft` MCP tool, no wrapper needed) are the source of truth for tasks.
+### 3.7 Editing a draft after the first mirror
 
-> Why parsing uses `printf '%s' "$RESULT" | grep` not `echo "$RESULT" | jq`: `echo` interprets backslash sequences inside the captured JSON, turning embedded `\n` into a real newline. `jq` then aborts with `Invalid string: control characters from U+0000 through U+001F must be escaped`. `printf '%s'` emits the captured bytes verbatim. Same pattern applies to all wrapper-result parsing in this skill.
+Local file changes propagate via `chorus_pm_update_document_draft` — same primary/fallback split as §3.6, same halt check. Primary (CLI):
 
-### 3.7 Editing a draft after the first mirror
+```bash
+RESULT=$(chorus mcp call chorus_pm_update_document_draft \
+  "{\"proposalUuid\":\"$PROPOSAL_UUID\",\"draftUuid\":\"$PRD_DRAFT_UUID\"}" \
+  --arg-file content="openspec/changes/$SLUG/proposal.md")
+RC=$?
+chorus_check_response "chorus_pm_update_document_draft" "$RC" "$RESULT"
+```
 
-Local file changes propagate via `chorus_pm_update_document_draft` — same wrapper, same `json_encode_file`, same halt check.
+Fallback (no `chorus` on `PATH`) — `json_encode_file` from the §3.6 fallback block:
 
 ```bash
 CONTENT=$(json_encode_file "openspec/changes/$SLUG/proposal.md")
@@ -293,7 +320,17 @@ chorus_check_response "chorus_pm_update_document_draft" "$RC" "$RESULT"
 
 ### 3.8 Editing a Document after proposal approval
 
-Once the proposal is approved, drafts materialize into Documents with their own UUIDs. To keep `openspec/changes/$SLUG/` and the Chorus Document in sync, mirror file edits via `chorus_pm_update_document`:
+Once the proposal is approved, drafts materialize into Documents with their own UUIDs. To keep `openspec/changes/$SLUG/` and the Chorus Document in sync, mirror file edits via `chorus_pm_update_document`. Primary (CLI):
+
+```bash
+RESULT=$(chorus mcp call chorus_pm_update_document \
+  "{\"documentUuid\":\"$SPEC_DOCUMENT_UUID\"}" \
+  --arg-file content="openspec/changes/$SLUG/specs/<capability>/spec.md")
+RC=$?
+chorus_check_response "chorus_pm_update_document" "$RC" "$RESULT"
+```
+
+Fallback (no `chorus` on `PATH`) — `json_encode_file` from the §3.6 fallback block:
 
 ```bash
 CONTENT=$(json_encode_file "openspec/changes/$SLUG/specs/<capability>/spec.md")
@@ -366,9 +403,9 @@ When detection puts the agent in fallback mode (`CHORUS_OPENSPEC_ACTIVE=0`), thi
 
 ## §6. Failure visibility — the `chorus_check_response` helper
 
-There is a known wrapper edge case: when the server returns HTTP 4xx (e.g. 401 from a bad `CHORUS_API_KEY`), `chorus-api.sh mcp-tool` captures the JSON-RPC error body internally, pipes it through a `.result.content[]?` jq filter that produces no output when `.result` is absent, and exits 0 with empty stdout. A bare `RC=$?` check would not halt on this — the most common runtime failure mode would be invisible.
+This helper guards **both** the primary CLI path and the fallback wrapper path. On the fallback path there is a known wrapper edge case: when the server returns HTTP 4xx (e.g. 401 from a bad `CHORUS_API_KEY`), `chorus-api.sh mcp-tool` captures the JSON-RPC error body internally, pipes it through a `.result.content[]?` jq filter that produces no output when `.result` is absent, and exits 0 with empty stdout. A bare `RC=$?` check would not halt on this — the most common runtime failure mode would be invisible. (`chorus mcp call` exits non-zero on tool/transport errors, so `RC` is reliable on the primary path — but run the same three-signal check on both, as defense in depth.)
 
-Define this helper **once** at the top of the authoring session and use it after every wrapper call:
+Define this helper **once** at the top of the authoring session and use it after every mirror call (CLI or wrapper):
 
 ```bash
 chorus_check_response() {
@@ -408,9 +445,15 @@ chorus_check_response() {
 - Skip capturing `$RESULT` into a variable; the helper needs the body.
 - Use only `if [ "$RC" -ne 0 ]; then ...` — that misses the HTTP-error path.
 
-**Minimal call site shape:**
+**Minimal call site shape (both paths):**
 
 ```bash
+# Primary — chorus CLI:
+RESULT=$(chorus mcp call <tool_name> '<json-without-content>' --arg-file content=<file>)
+RC=$?
+chorus_check_response "<tool_name>" "$RC" "$RESULT"
+
+# Fallback — chorus-api.sh wrapper (chorus not on PATH):
 RESULT=$(chorus-api.sh mcp-tool <tool_name> "$PAYLOAD")
 RC=$?
 chorus_check_response "<tool_name>" "$RC" "$RESULT"
@@ -433,8 +476,8 @@ When invoked from a stage skill (proposal / develop / yolo):
    c. Author `proposal.md`, `design.md`, `specs/<capability>/spec.md` (§3.2–§3.3). Mix `ADDED` / `MODIFIED` / `REMOVED` / `RENAMED` blocks as needed; remember `MODIFIED` overwrites the whole Requirement.
    d. Optional: `openspec validate "$SLUG"`.
    e. `chorus_pm_create_proposal` (direct MCP) with the `OpenSpec change slug: $SLUG` line in description (§3.5).
-   f. Define `json_encode_file`, `chorus_check_response` helpers. (`chorus-api.sh` is on PATH — no `$API` variable needed.)
-   g. For each row in §5 with "yes" — mirror via `chorus-api.sh mcp-tool chorus_pm_add_document_draft` (§3.6). Record each `$DRAFT_UUID`.
+   f. Define the `chorus_check_response` helper. Prefer `chorus mcp call … --arg-file content=<file>` for mirrors (§3.6) — no `json_encode_file` needed on that path; define `json_encode_file` only when falling back to the wrapper because `chorus` is not on `PATH`. (`chorus-api.sh` is on PATH — no `$API` variable needed.)
+   g. For each row in §5 with "yes" — mirror via `chorus mcp call chorus_pm_add_document_draft … --arg-file content=<file>` (§3.6; fallback = `chorus-api.sh mcp-tool`). Record each `$DRAFT_UUID`.
    h. On any failed `chorus_check_response` — halt, surface the error, do NOT proceed.
 4. Edits before approval → §3.7. Edits after approval → §3.8.
 5. Last task verified → hook fires → run §3.9 archive flow.

package/.next/standalone/public/chorus-plugin/skills/orchestrate/SKILL.md

@@ -4,7 +4,7 @@ description: Multi-agent orchestration playbook — coordinate OTHER agents and
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.16.4"
+  version: "0.17.0"
   category: project-management
   mcp_server: chorus
 ---