@overdeck/desktop 0.45.23 → 0.46.0

package/sync-sources/dev-skills/pan-dashboard-restart/SKILL.md

@@ -16,10 +16,12 @@ allowed-tools:
   - Read
 ---
 
-# Overdeck Dashboard Restart (production-safe, detached)
+# Overdeck Dashboard Restart (production-safe)
 
 The dashboard the browser talks to is the **pre-built `dist/dashboard/server.js` running under Node 22**, started from the **primary repo checkout** (NOT a `workspaces/feature-*` copy). It serves both the built frontend and the API on one port. **Never** run the production server via `npm run dev`, `tsx`, `vite`, or Bun — that violates the dashboard-node22-only rule (node-pty native addon + circular ESM). `pan dev` is the *development* path (vite HMR for the frontend + Node server); `pan up` is the *production* path.
 
+The **supervisor sidecar** (`overdeck-supervisor.service`, port 3012) owns the dashboard lifecycle: it health-checks the server and respawns it as a systemd unit with the full env from `config.yaml`. Restart **through** it (`POST :3012/restart-dashboard`) — a manually spawned server is a duplicate it will replace, and racing it costs minutes of churn. The manual detached start below is the fallback for when the supervisor itself is down, and it must carry the Traefik env block (gotcha 7).
+
 ## When to use this skill
 
 `pan up` / `pan restart` is the normal path. Reach for this manual procedure **only** when:
@@ -35,33 +37,53 @@ The dashboard the browser talks to is the **pre-built `dist/dashboard/server.js`
 3. **Exactly ONE server.** Two servers = two deacons racing the same `~/.overdeck` state (the duel), and the PAN-1625 janitor reaps/churns extras. A single port-owner is left alone.
 4. **Work-agent tmux sessions survive a dashboard restart** — they are separate processes on the `overdeck` socket. Restarting the dashboard does NOT kill agents; the new deacon reconciles them as running.
 5. **Run from the primary repo**, not a workspace. If `readlink /proc/<pid>/cwd` is a `workspaces/feature-*` path, a workspace dashboard hijacked the port — kill it and restart from the primary checkout.
+6. **The supervisor sidecar owns the dashboard lifecycle.** `overdeck-supervisor.service` (port 3012) health-checks the dashboard and respawns it as a systemd unit with the full env from `config.yaml`. A manual server you spawn yourself is a duplicate it will replace — so restart THROUGH the supervisor (below) instead of racing it, and never kill a systemd-parented server that carries `OVERDECK_TRAEFIK_*` env: that is the supervisor's correctly-configured replacement, not a stray.
+7. **A bare `node dist/dashboard/server.js` launch 403s the domain on dists without the config fallback.** `getTrustedOrigins()` reads the launch env; no `OVERDECK_TRAEFIK_*` → only loopback is trusted → `/ws/*` 403s `https://overdeck.localhost` → the dashboard hangs on "Reconnecting to the dashboard…" while `localhost:3011` works. `/api/health` returns 200 the whole time because it does no origin validation. Newer dists fall back to `config.yaml` (commit `e86d125071`), but always launch WITH the env block below — it costs nothing and works on every dist.
 
 ## Procedure
 
 ```bash
 cd ~/Projects/overdeck   # the PRIMARY checkout
 
+# 0. Domain comes from config.yaml — the same source pan up / the supervisor use
+DOMAIN=$(awk '/^traefik:/{f=1} f && /^  domain:/{print $2; exit}' ~/.overdeck/config.yaml)
+DOMAIN=${DOMAIN:-overdeck.localhost}
+
 # 1. Rebuild ONLY if you changed server/lib source (the Node 22 dist is what runs)
 npm run build
 
-# 2. Find the live dashboard port + PID, kill by EXPLICIT PID (never pkill -f self-matching)
-PORT_LINE=$(ss -ltnp 2>/dev/null | grep -E ':(3010|3011|3012)\b' | grep node | head -1)
-OLD=$(echo "$PORT_LINE" | grep -oE 'pid=[0-9]+' | head -1 | cut -d= -f2)
-echo "current server: pid=$OLD"
+# 2. PREFERRED: restart through the supervisor (it owns the lifecycle, sets the
+#    correct env from config.yaml, and systemd-manages the result). Skip to step 3
+#    only when port 3012 refuses connections.
+curl -s -X POST http://127.0.0.1:3012/restart-dashboard   # → 202 Accepted
+
+# 3. Supervisor down? Manual detached start — WITH the Traefik env block (gotcha 7).
+#    Kill the old server by EXPLICIT PID (never pkill -f self-matching).
+OLD=$(ss -ltnp 2>/dev/null | grep -E ':3011\b' | grep node | grep -oE 'pid=[0-9]+' | head -1 | cut -d= -f2)
 [ -n "$OLD" ] && kill -TERM "$OLD"
 for i in $(seq 1 15); do { [ -n "$OLD" ] && kill -0 "$OLD" 2>/dev/null; } && sleep 1 || break; done
 { [ -n "$OLD" ] && kill -0 "$OLD" 2>/dev/null; } && kill -9 "$OLD"
 
-# 3. Start ONE fully-detached server (survives the shell; not a child of any wrapper).
-#    PORT is inherited from the environment; set it explicitly if you need a specific port.
-setsid bash -c 'exec node dist/dashboard/server.js' > /tmp/pan-dash.log 2>&1 < /dev/null &
+setsid env \
+  DASHBOARD_URL="https://${DOMAIN}" OVERDECK_TRAEFIK_ENABLED=1 \
+  OVERDECK_TRAEFIK_DOMAIN="${DOMAIN}" OVERDECK_TRUSTED_ORIGINS="https://${DOMAIN}" \
+  DASHBOARD_PORT=3010 API_PORT=3011 PORT=3011 OVERDECK_MODE=production \
+  bash -c 'exec node dist/dashboard/server.js' > /tmp/pan-dash.log 2>&1 < /dev/null &
 
-# 4. Verify health (Traefik routes overdeck.localhost -> the API port)
+# 4. Verify health AND the WebSocket origin path. /api/health does no origin
+#    validation — it returns 200 even while /ws/* 403s the domain (gotcha 7).
+#    The WS check is the only one that proves the browser can actually connect.
 for i in $(seq 1 40); do
-  code=$(curl -sk -o /dev/null -w '%{http_code}' --max-time 3 https://overdeck.localhost/api/health 2>/dev/null)
+  code=$(curl -sk -o /dev/null -w '%{http_code}' --max-time 3 "https://${DOMAIN}/api/health" 2>/dev/null)
   [ "$code" = 200 ] && { echo "healthy after ${i}s"; break; }
   sleep 1
 done
+ws=$(curl -sk -o /dev/null -w '%{http_code}' --http1.1 --max-time 5 \
+  -H "Origin: https://${DOMAIN}" -H "Connection: Upgrade" -H "Upgrade: websocket" \
+  -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
+  "https://${DOMAIN}/ws/rpc")
+[ "$ws" = 101 ] && echo "WS origin OK" \
+  || echo "WS origin FAILED (got $ws) — server does not trust the domain; relaunch with the env block (or a dist with the config fallback)"
 
 # 5. Confirm SINGLE instance, correct dist path (primary repo, not a workspace)
 ss -ltnp 2>/dev/null | grep -E ':(3010|3011)\b'
@@ -79,6 +101,7 @@ readlink -f /proc/$NEW/cwd      # must be the primary repo path
 ## Verify success
 
 - `overdeck.localhost/api/health` returns `{"status":"ok"}` and `curl http://localhost:<port>/api/health` returns 200.
+- **The WebSocket origin check returns 101** (procedure step 4). Health alone is not success — a server missing its Traefik env is healthy on `/api/health` and dead to the browser at the same time.
 - Exactly one **host-level** `node dist/dashboard/server.js` process; its `/proc/<pid>/cwd` is the primary repo.
   **Do not count workspace-container servers.** Each running workspace devcontainer has its own `server` service whose `dist/dashboard/server.js` process is visible in host `ps` — those are legitimate read/UI peers (cwd `/workspaces/overdeck`, parent `containerd-shim`, `OVERDECK_DISABLE_DEACON=1`), NOT duplicate dashboards and NOT a single-deacon hazard. Seeing N+1 server processes with N containers up is the healthy state. Container-aware census:
   ```bash
@@ -89,6 +112,7 @@ readlink -f /proc/$NEW/cwd      # must be the primary repo path
   done
   ```
   Exactly one `HOST` line, with cwd = the primary repo, is success. Multiple `HOST` lines = a real orphan (the deacon's orphan-server reaper, PAN-1625, will also catch it).
+- **Do not kill the supervisor's server.** If a HOST server is parented to systemd and its env contains `OVERDECK_TRAEFIK_DOMAIN`, it is the supervisor's correctly-configured managed instance (gotcha 6). If you spawned a manual server and then see a second one appear, kill YOURS (the one without the Traefik env), never the supervisor's.
 - Agent tmux sessions (`tmux -L overdeck list-sessions`) are intact.
 - The deacon log (`/tmp/pan-dash.log` or the dashboard log) shows a single `Deacon started` and patrols advancing — no `received SIGTERM` loop.
 

package/sync-sources/hooks/linear-mcp-auth-hook

@@ -0,0 +1,97 @@
+#!/bin/bash
+# PostToolUse + PostToolUseFailure hook for structured Linear MCP OAuth
+# intervention events (PAN-2997). Registered with matcher mcp__linear__.* for
+# both hook events: PostToolUse fires after a tool call SUCCEEDS, while a
+# failed MCP call — the motivating OAuth-expired case — fires
+# PostToolUseFailure with a top-level `error` field and no tool_response.
+#
+# Never breaks Claude Code: every failure exits 0 silently.
+
+set +e
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+command -v jq >/dev/null 2>&1 || exit 0
+
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+[[ "$TOOL_NAME" == mcp__linear__* ]] || exit 0
+
+EVENT_NAME=$(printf '%s' "$INPUT" | jq -r '.hook_event_name // "PostToolUse"' 2>/dev/null)
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=pan-hook-lib.sh
+. "$SCRIPT_DIR/pan-hook-lib.sh" 2>/dev/null || exit 0
+declare -f pan_resolve_agent_id >/dev/null 2>&1 || exit 0
+pan_resolve_agent_id || exit 0
+declare -f pan_emit_event >/dev/null 2>&1 || exit 0
+
+MARKER_DIR="${OVERDECK_HOME:-$HOME/.overdeck}/agents/$AGENT_ID"
+MARKER="$MARKER_DIR/linear-mcp-auth-pending"
+
+# Auth-failure classifier. The 401 alternative requires a non-identifier
+# boundary on both sides so ordinary Linear data (MIN-401, "AUR-4015") can
+# never match; prose phrases are matched as words.
+is_auth_error_text() {
+  printf '%s' "$1" | grep -Eiq 'requires authentication|not authenticated|unauthorized|(^|[^0-9A-Za-z-])401([^0-9]|$)'
+}
+
+emit_required() {
+  local auth_url="$1"
+  local body
+  body=$(jq -n --arg authUrl "$auth_url" '{
+    kind: "linear_mcp_auth_required",
+    authUrl: (if $authUrl == "" then null else $authUrl end)
+  }' 2>/dev/null) || return 0
+  pan_emit_event "$AGENT_ID" "$body" >/dev/null 2>&1 || true
+  mkdir -p "$MARKER_DIR" 2>/dev/null || true
+  : > "$MARKER" 2>/dev/null || true
+}
+
+emit_healthy_if_pending() {
+  [ -f "$MARKER" ] || return 0
+  local body
+  body=$(jq -n '{kind: "linear_mcp_auth_healthy"}' 2>/dev/null) || return 0
+  pan_emit_event "$AGENT_ID" "$body" >/dev/null 2>&1 || true
+  rm -f "$MARKER" 2>/dev/null || true
+}
+
+if [ "$EVENT_NAME" = "PostToolUseFailure" ]; then
+  # Documented failure-event shape: top-level `error`, no tool_response.
+  ERROR_TEXT=$(printf '%s' "$INPUT" | jq -r '.error // ""' 2>/dev/null)
+  if is_auth_error_text "$ERROR_TEXT"; then
+    emit_required ''
+  fi
+  exit 0
+fi
+
+# PostToolUse — successful tool call.
+RESPONSE=$(printf '%s' "$INPUT" | jq -r '
+  (.tool_response // .tool_result // "")
+  | if type == "string" then . else tojson end
+' 2>/dev/null)
+[ -n "$RESPONSE" ] || RESPONSE=''
+
+if [ "$TOOL_NAME" = 'mcp__linear__authenticate' ]; then
+  AUTH_URL=$(printf '%s\n' "$RESPONSE" \
+    | grep -Eo 'https://linear\.app/oauth/authorize[^"[:space:]<>]*' 2>/dev/null \
+    | sed -n '1p')
+  emit_required "$AUTH_URL"
+  exit 0
+fi
+
+# An MCP server can report a failure inside a successful hook event as an
+# error-shaped payload (isError: true, or an `error` member). Only those
+# payloads are auth-classified — ordinary successful result data (issue
+# identifiers like MIN-401, titles mentioning 401s or "unauthorized") never
+# reaches this check and simply clears any pending intervention below.
+ERROR_SHAPED=$(printf '%s' "$INPUT" | jq -r '
+  (.tool_response // .tool_result // {})
+  | if type == "object" and ((.isError == true) or (.error != null)) then "yes" else "" end
+' 2>/dev/null)
+
+if [ -n "$ERROR_SHAPED" ] && is_auth_error_text "$RESPONSE"; then
+  emit_required ''
+  exit 0
+fi
+
+emit_healthy_if_pending
+exit 0

package/sync-sources/hooks/record-cost-event.js

@@ -28121,7 +28121,8 @@ function validateRoleFields(role, roleConfig) {
 			if (!Number.isInteger(entry.weight) || entry.weight <= 0) throw new Error(`config.yaml: roles.${role}.model[${i}].weight must be a positive integer`);
 		}
 	}
-	if (roleConfig.harness !== void 0 && roleConfig.harness !== "claude-code" && roleConfig.harness !== "ohmypi" && roleConfig.harness !== "codex") throw new Error(`config.yaml: roles.${role}.harness must be claude-code, ohmypi, or codex`);
+	if (roleConfig.autonomousModel !== void 0 && typeof roleConfig.autonomousModel !== "string") throw new Error(`config.yaml: roles.${role}.autonomousModel must be a scalar model reference`);
+	if (roleConfig.harness !== void 0 && roleConfig.harness !== "claude-code" && roleConfig.harness !== "ohmypi" && roleConfig.harness !== "codex" && roleConfig.harness !== "acp") throw new Error(`config.yaml: roles.${role}.harness must be claude-code, ohmypi, codex, or acp`);
 	if (roleConfig.effort !== void 0 && !ROLE_EFFORTS.includes(roleConfig.effort)) throw new Error(`config.yaml: roles.${role}.effort must be one of ${ROLE_EFFORTS.join(", ")}`);
 	if (roleConfig.mode !== void 0 && roleConfig.mode !== "quick" && roleConfig.mode !== "full" && roleConfig.mode !== "none") throw new Error(`config.yaml: roles.${role}.mode must be quick, full, or none`);
 	if (roleConfig.reReviewScope !== void 0 && roleConfig.reReviewScope !== "all" && roleConfig.reReviewScope !== "changed" && roleConfig.reReviewScope !== "blockers") throw new Error(`config.yaml: roles.${role}.reReviewScope must be all, changed, or blockers`);
@@ -28138,6 +28139,7 @@ function validateRoleModelRefs(config) {
 	}
 	for (const [role, roleConfig] of Object.entries(config.roles ?? {})) {
 		validateRoleFields(role, roleConfig);
+		if (typeof roleConfig.autonomousModel === "string") derefWorkhorse(roleConfig.autonomousModel, config, `roles.${role}.autonomousModel`);
 		if (Array.isArray(roleConfig.model)) for (let i = 0; i < roleConfig.model.length; i++) derefWorkhorse(roleConfig.model[i].model, config, `roles.${role}.model[${i}].model`);
 		else if (roleConfig.model) {
 			const resolvedModel = derefWorkhorse(roleConfig.model, config, `roles.${role}.model`);
@@ -28734,7 +28736,7 @@ const DEFAULT_TIERED_EXECUTION_CONFIG = {
 	difficultyToTier: {}
 };
 function isRuntimeName(value) {
-	return value === "claude-code" || value === "ohmypi" || value === "codex";
+	return value === "claude-code" || value === "ohmypi" || value === "codex" || value === "acp";
 }
 function isDifficulty(value) {
 	return TIERED_EXECUTION_DIFFICULTIES.includes(value);
@@ -28757,7 +28759,7 @@ function knownModelIds() {
 	return ids;
 }
 function validateHarness(harness, path) {
-	if (!isRuntimeName(harness)) throw new TieredExecutionConfigError(`${path}.harness '${harness}' is unknown; expected claude-code, ohmypi, or codex`);
+	if (!isRuntimeName(harness)) throw new TieredExecutionConfigError(`${path}.harness '${harness}' is unknown; expected claude-code, ohmypi, codex, or acp`);
 }
 function validateModel(model, path) {
 	const resolved = resolveModelIdSync(model);
@@ -29288,7 +29290,7 @@ function normalizeProviderConfig(providerConfig, fallbackKey) {
 	};
 }
 function validateProviderHarness(provider, harness) {
-	if (harness !== void 0 && harness !== "claude-code" && harness !== "ohmypi" && harness !== "codex") throw new Error(`config.yaml: models.providers.${provider}.harness must be claude-code, ohmypi, or codex`);
+	if (harness !== void 0 && harness !== "claude-code" && harness !== "ohmypi" && harness !== "codex" && harness !== "acp") throw new Error(`config.yaml: models.providers.${provider}.harness must be claude-code, ohmypi, codex, or acp`);
 }
 function applyProviderHarness(result, provider, harness) {
 	validateProviderHarness(provider, harness);

package/sync-sources/rules/ask-user-question-self-contained.md

@@ -0,0 +1,9 @@
+---
+scope: universal
+---
+### Make every AskUserQuestion prompt self-contained
+
+Every AskUserQuestion must stand alone because the operator may answer from a
+dashboard dialog without the preceding transcript. State the situation in one
+or two sentences, ask for the decision in plain language, and describe each
+option by the consequence of choosing it rather than by a label alone.

package/sync-sources/skills/okf/README.md

@@ -15,14 +15,21 @@ Embedding commands also need Ollama or an API key for the selected provider.
 
 Overdeck users receive this skill through `pan sync`.
 
-Standalone Claude Code users can copy-install it:
+Standalone Claude Code users install it from the mirror repo, [eltmon/okf](https://github.com/eltmon/okf) — symlink so `git pull` updates it in place:
 
 ```bash
+git clone https://github.com/eltmon/okf.git ~/Projects/okf
 mkdir -p ~/.claude/skills
-cp -R sync-sources/skills/okf ~/.claude/skills/okf
+ln -s ~/Projects/okf ~/.claude/skills/okf
 ```
 
-The copied skill remains portable. Its core scripts do not import Overdeck and require only git, gh, Python 3, and PyYAML for non-embedding workflows.
+Or copy-install instead of symlinking:
+
+```bash
+cp -R ~/Projects/okf ~/.claude/skills/okf
+```
+
+The skill remains portable. Its core scripts do not import Overdeck and require only git, gh, Python 3, and PyYAML for non-embedding workflows.
 
 ## 5-Minute Quickstart
 
@@ -61,6 +68,7 @@ The copied skill remains portable. Its core scripts do not import Overdeck and r
 | Command | Summary |
 | --- | --- |
 | `/okf init` | Create or connect the knowledge bundle and pointer file. |
+| `/okf open [--no-install] [--no-browser]` | Open the configured bundle in the local visual knowledge viewer. |
 | `/okf author "<topic>"` | Write or update one concept for one idea. |
 | `/okf convert <path>` | Convert existing docs into OKF without destructive edits. |
 | `/okf sync [--topic "<focus>"]` | Update concepts from code or documentation diffs. |

package/sync-sources/skills/okf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: okf
-description: Maintain a project knowledge wiki in Open Knowledge Format with /okf init, author, convert, sync, study, retro, extract, validate, lint, and embed.
+description: Maintain a project knowledge wiki in Open Knowledge Format with /okf init, open, author, convert, sync, study, retro, extract, validate, lint, and embed.
 triggers:
   - /okf
   - okf
@@ -26,6 +26,7 @@ The bundle is the source of truth. Keep changes small, cited, and PR-gated. Dete
 | Command | Purpose | Primary references |
 | --- | --- | --- |
 | `/okf init` | Create or connect a project knowledge bundle. | `references/workflow.md`, `references/spec.md` |
+| `/okf open [--no-install] [--no-browser]` | Open the configured bundle in the local visual knowledge viewer. | `references/overdeck.md` |
 | `/okf author "<topic>"` | Write or refresh one focused concept. | `templates/concept.md`, `references/taxonomy.md`, `references/model-bridges.md` |
 | `/okf convert <path>` | Convert existing docs into OKF concepts without deleting originals. | `references/conversion.md` |
 | `/okf sync [--topic "<focus>"]` | Update concepts from code or documentation changes. | `references/workflow.md`, `references/model-bridges.md` |
@@ -80,6 +81,16 @@ Create a knowledge bundle and pointer file.
 - Add exactly one discovery line to `CLAUDE.md` or `AGENTS.md`, preserving it without duplication on repeated init.
 - Future resolution order is host project config `knowledge_repo`, then `.okf.yml`, then a clear error telling the user to run `/okf init`.
 
+## `/okf open [--no-install] [--no-browser]`
+
+Open the configured bundle in the local visual knowledge viewer.
+
+- Resolve the bundle from `.okf.yml`; under Overdeck, the canonical resolver also honors the project's `knowledge_repo` setting.
+- When `pan` is available, delegate to `pan knowledge open` and pass through `--no-install` and `--no-browser`.
+- By default, an explicit open request progressively installs the separately licensed GPL-3.0 `@inkeep/open-knowledge` program. `--no-install` requires an existing `ok` binary instead.
+- The viewer is an arm's-length subprocess served over HTTP. Overdeck launches it against a disposable snapshot, reuses healthy lock-reported processes, and never lets viewer edits touch the canonical PR-gated bundle.
+- Never import, require, or bundle `@inkeep/open-knowledge` into the portable OKF scripts or Overdeck packages.
+
 ## `/okf author "<topic>"`
 
 Write or update one concept for one idea.

package/sync-sources/skills/okf/docs/USAGE.md

@@ -16,6 +16,21 @@ Create a knowledge bundle.
 - `--dir <path>`: use any external directory.
 - `--local <subdir>`: create an in-repo bundle.
 
+## `/okf open [--no-install] [--no-browser]`
+
+Open the configured bundle in the local visual viewer.
+
+```bash
+/okf open
+/okf open --no-install
+/okf open --no-browser
+```
+
+- Resolves the bundle from `.okf.yml` (or Overdeck's `knowledge_repo` setting).
+- Delegates to `pan knowledge open` when Overdeck is available.
+- Progressively installs the separate GPL-3.0 `ok` program only after the explicit open request; `--no-install` opts out.
+- `--no-browser` starts or reuses the viewer and prints its URL without launching a browser.
+
 ## `/okf author "<topic>"`
 
 Write or update one concept.

package/sync-sources/skills/okf/references/overdeck.md

@@ -11,6 +11,34 @@ Overdeck is available only when:
 
 Detection is by command execution, never by Python or TypeScript imports.
 
+## OpenKnowledge Viewer Runtime
+
+`pan knowledge open` and the dashboard Knowledge page use an assisted Node.js 24 resolution flow for the OpenKnowledge viewer. Overdeck first reuses a working `ok`, then checks `OVERDECK_OPEN_KNOWLEDGE_NODE`, then searches installed runtimes under nvm, fnm, Volta, mise, and asdf. If a download is required, the operator sees the exact setup steps and must consent before they run; shell profiles and the ambient/default Node.js version remain unchanged. A fresh nvm bootstrap suppresses profile edits and restores or removes the `default` alias to match its pre-setup state.
+
+Set `OVERDECK_OPEN_KNOWLEDGE_NODE=/absolute/path/to/node` to pin the viewer to a specific Node.js 24+ binary. Overdeck rejects relative overrides and resolves the absolute path before writing the shim, so the override affects only the separate `ok` subprocess and cannot drift with `PATH`.
+
+## Optional OpenKnowledge MCP Registration
+
+The dashboard viewer and `pan knowledge open` never register an MCP server. Their unattended initialization always uses `ok init --no-mcp --no-skills`, so opening the viewer cannot change an editor or agent configuration.
+
+MCP registration is a separate, explicit operator action. From the resolved knowledge-bundle root, run:
+
+```bash
+ok init --mcp --no-skills --scope user
+```
+
+Use `--scope project` for repository-local configuration, or `--scope both` for both locations. OpenKnowledge v0.34 writes the supported native formats:
+
+| Client | User scope | Project scope |
+| --- | --- | --- |
+| Claude Code | `~/.claude.json` | `.mcp.json` |
+| Codex | `~/.codex/config.toml` | `.codex/config.toml` |
+| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` |
+
+OpenKnowledge registers only clients it detects. Start or install the intended client, then rerun the explicit command if its config root was previously absent. Review the reported paths before restarting the client; registration is opt-in and Overdeck never performs it automatically.
+
+`/okf init` and `ok init` are different commands: `/okf init` creates or connects an OKF knowledge bundle, while the upstream `ok init` command scaffolds OpenKnowledge's local `.ok/` runtime files and optionally registers MCP clients.
+
 ## Retro Feedstock
 
 When Overdeck is detected, `/okf retro` may mine observations for the issue:

package/sync-sources/skills/pan-close/SKILL.md

@@ -35,15 +35,17 @@ Each overridable row has one explicit acceptance flag:
 ```text
 --accept-review       Row 1: review passed
 --accept-tests        Row 2: tests passed
---accept-verification Row 3: branch verification passed at lastVerifiedCommit
+--accept-verification Row 3: branch verification passed
 --accept-merged       Row 4: PR merged on the forge
 --accept-post-merge   Row 5: post-merge lifecycle completed
 --accept-main-verify  Row 6: merge commit verified on main
 --accept-deploy       Row 7: live dashboard build includes the merge
 ```
 
-An acceptance records the flag, operator/agent identity, and timestamp in the
-issue close-out record. Use it only when the missing evidence is understood:
+An acceptance records the flag, operator identity, and timestamp in the issue
+close-out record. The autonomous flywheel may run a clean close-out, but it cannot
+use `--accept-*`; an operator must apply every override after reviewing the miss.
+Use an override only when the missing evidence is understood:
 
 ```bash
 pan close PAN-1234 --force

package/sync-sources/skills/pan-flywheel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pan-flywheel
-description: "pan flywheel — start, pause, resume, stop, inspect, emit, and report on the singleton Fix-All Flywheel orchestrator"
+description: "pan flywheel — start, pause, resume, complete, stop, inspect, emit, and report on the singleton Fix-All Flywheel orchestrator"
 triggers:
   - pan flywheel
   - flywheel orchestrator
@@ -24,6 +24,7 @@ The Flywheel is not an issue-scoped work agent. It runs as `flywheel-orchestrato
 ```bash
 pan flywheel start
 pan flywheel start --brief docs/flywheel-brief.md
+pan flywheel start --orders <book-id>
 pan flywheel config --get
 pan flywheel config --get flywheel.require_uat_before_merge
 pan flywheel config --set flywheel.auto_pickup_backlog=true
@@ -32,6 +33,8 @@ pan flywheel status
 pan flywheel status --json
 pan flywheel pause
 pan flywheel resume
+pan flywheel complete
+pan flywheel complete --force
 pan flywheel stop
 pan flywheel abort
 pan flywheel emit-status --file latest.json
@@ -45,12 +48,15 @@ pan flywheel report
 ```bash
 pan flywheel start
 pan flywheel start --brief docs/flywheel-brief.md
+pan flywheel start --orders <book-id>
 ```
 
 Starts `flywheel-orchestrator` and opens a new run under `~/.overdeck/flywheel/runs/<runId>/`.
 
 Use the default brief unless the user gives a specific markdown brief. The default is `docs/flywheel-brief.md`. The command validates that the brief path stays inside the project root.
 
+`--orders <book-id>` validates a ready order book, stamps the book binding into the run launch metadata, and marks the book running only after the Flywheel start gate succeeds. Validation or gate failures leave the book ready.
+
 ### Config
 
 ```bash
@@ -84,6 +90,17 @@ pan flywheel resume
 
 If the Flywheel is already paused or already running, these commands report the current gate state and exit successfully.
 
+### Complete
+
+```bash
+pan flywheel complete
+pan flywheel complete --force
+```
+
+Completes an orders-bound run after every book item is closed or parked. The command refuses a non-drained book and names each remaining issue unless `--force` is passed. It writes `report.md`, adds `## Retrospective` from the run's `retro.md` when present or the exact no-findings line otherwise, commits any `docs/FLYWHEEL-STATE.md` change, clears the active-run gate, and marks the book complete.
+
+Continuation is mechanical: the next ready book in queue order starts in-process; when no book is ready and `flywheel.auto_pickup_backlog=true`, a bookless backlog run starts; otherwise the command stays stopped and emits `needs-you: pipeline idle — no order book queued and auto-pickup is off`.
+
 ### Stop
 
 ```bash

package/sync-sources/skills/pan-knowledge/SKILL.md

@@ -9,6 +9,7 @@ triggers:
   - knowledge sync
   - knowledge study
   - knowledge retro
+  - knowledge open
 allowed-tools:
   - Bash
   - Read
@@ -30,6 +31,8 @@ pan knowledge PAN-123 --focus "auth flow"    # Study a topic, then sync
 pan knowledge PAN-123 --retro                # Capture retro knowledge, then sync
 pan knowledge PAN-123 --model claude-sonnet-5  # Override the knowledge role model
 pan knowledge PAN-123 --effort high          # Raise reasoning effort for the agent
+pan knowledge open                           # Open this project's OKF bundle in the viewer
+pan knowledge open --no-install --no-browser # Never install or launch a browser
 ```
 
 ## What It Does
@@ -51,6 +54,13 @@ The command first tries to ensure `mnemos` is available on `PATH` (installing it
 on demand if necessary) and ingest the resolved bundle. If mnemos is unavailable,
 it resolves the installed `okf` skill and falls back to its bundled `scripts/` directory.
 
+`pan knowledge open` resolves the current project's bundle through
+`projects.yaml` or `.okf.yml`, progressively installs the separately licensed
+`@inkeep/open-knowledge` program when needed, starts or reuses a verified viewer
+against a disposable snapshot, and opens the URL. Viewer edits never touch the
+canonical PR-gated bundle. Use `--no-install` to require a preinstalled `ok` binary and
+`--no-browser` to print the URL without launching a browser.
+
 ## When to Use
 
 - After merging a feature to capture knowledge that would have helped the work

package/sync-sources/skills/pan-orders/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: pan-orders
+description: "pan orders — create, inspect, edit, and start Flywheel order books"
+triggers:
+  - pan orders
+  - order book
+  - special orders
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# pan orders
+
+Use `pan orders` to manage the operator-owned order book that scopes a Flywheel campaign.
+
+```bash
+pan orders create "Campaign name"
+pan orders list
+pan orders show <id>
+pan orders add <id> <issue...>
+pan orders add <id> <issue...> --lane B --after <issue> --reverify
+pan orders remove <id> <issue>
+pan orders move <id> <issue> --lane A --order 2
+pan orders start <id>
+```
+
+- `create` makes a draft book with a date-and-name id.
+- `add` defaults to Lane A. `--after` must name an item already in the target lane. `--reverify` requires PRD re-verification before pickup.
+- `move` accepts `--lane <A|B>`, `--order <n>`, or both.
+- `start` validates and starts the same orders-bound path as Flywheel start; validation blocks leave the book unchanged.
+
+Order-book reads and mutations go through the canonical resolver and writer. Do not edit `orders/*.json` directly.