@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/operator-digest/scripts/provision-operator-digest-repo.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# Idempotent bootstrap for the operator weekly comprehension digest (#5085).
+#
+# Run ONCE post-merge on the operator's gh-authenticated machine. It:
+#   1. reads ANTHROPIC_API_KEY from Doppler (soleur/prd) and fails loud if empty;
+#   2. creates the PRIVATE jikig-ai/operator-digest repo (no-op if it already exists);
+#   3. sets ANTHROPIC_API_KEY as an Actions secret via STDIN (never argv);
+#   4. installs the committed workflow asset into the repo's default branch;
+#   5. enables the workflow so the weekly `schedule:` fires.
+#
+# Idempotent: re-running re-installs the workflow (create-or-update) and re-sets the secret.
+# Every step is `gh`/`doppler` CLI automation — no manual dashboard step (hr-all-infrastructure-
+# provisioning-servers + hr-multi-step-post-merge-bootstrap-script).
+#
+# After it completes: gh workflow run operator-digest.yml -R jikig-ai/operator-digest
+set -uo pipefail
+
+# REPO is a hardcoded constant — it MUST stay in lockstep with the `gh issue create -R <repo>`
+# post target in assets/operator-digest.workflow.yml. Making it env-overridable would let
+# provisioning create/secret/install into repo X while the installed workflow still posts to
+# jikig-ai/operator-digest (a silent misroute). If the target ever changes, change both together.
+REPO="jikig-ai/operator-digest"
+DOPPLER_PROJECT="${OPERATOR_DIGEST_DOPPLER_PROJECT:-soleur}"
+DOPPLER_CONFIG="${OPERATOR_DIGEST_DOPPLER_CONFIG:-prd}"
+SECRET_NAME="ANTHROPIC_API_KEY"
+WORKFLOW_PATH=".github/workflows/operator-digest.yml"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORKFLOW_ASSET="${SCRIPT_DIR}/../assets/operator-digest.workflow.yml"
+
+SECRET_VALUE=""  # populated by fetch_secret
+
+log() { printf '[provision] %s\n' "$*" >&2; }
+die() { printf '[provision] ERROR: %s\n' "$*" >&2; exit 1; }
+
+require_tools() {
+  command -v gh >/dev/null 2>&1      || die "gh CLI not found on PATH"
+  command -v doppler >/dev/null 2>&1 || die "doppler CLI not found on PATH"
+  gh auth status >/dev/null 2>&1     || die "gh is not authenticated — run 'gh auth login'"
+}
+
+# fetch_secret — read ANTHROPIC_API_KEY from Doppler; fail loud (die) if missing/empty.
+# Sets the global SECRET_VALUE. NOTE: split declaration from assignment so the command
+# substitution's exit code is observable (a `local x=$(...)` masks it and always returns 0).
+fetch_secret() {
+  local value
+  value="$(doppler secrets get "$SECRET_NAME" -p "$DOPPLER_PROJECT" -c "$DOPPLER_CONFIG" --plain)" \
+    || die "doppler secrets get ${SECRET_NAME} failed (project=${DOPPLER_PROJECT} config=${DOPPLER_CONFIG})"
+  [[ -n "$value" ]] || die "Doppler returned an EMPTY ${SECRET_NAME} (project=${DOPPLER_PROJECT} config=${DOPPLER_CONFIG}) — refusing to set an empty Actions secret"
+  SECRET_VALUE="$value"
+  log "read ${SECRET_NAME} from Doppler ${DOPPLER_PROJECT}/${DOPPLER_CONFIG}"
+}
+
+ensure_repo() {
+  if gh repo view "$REPO" >/dev/null 2>&1; then
+    log "repo ${REPO} already exists — skipping create"
+  else
+    log "creating private repo ${REPO}"
+    # --add-readme is load-bearing, not cosmetic: install_workflow uses the contents API
+    # (PUT repos/.../contents/...), which requires a default branch to already exist. A repo
+    # created with zero commits has no default-branch ref and the PUT 404s. The README is the
+    # initial commit that creates `main`. Do not drop --add-readme.
+    gh repo create "$REPO" --private --add-readme \
+      --description "Operator weekly comprehension digest — private (provisioned from soleur #5085)" \
+      || die "gh repo create ${REPO} failed (needs org-owner scope)"
+  fi
+}
+
+# set_secret — deliver the value to gh via STDIN; never pass it on argv.
+set_secret() {
+  local value="$1"
+  printf '%s' "$value" | gh secret set "$SECRET_NAME" -R "$REPO" \
+    || die "gh secret set ${SECRET_NAME} on ${REPO} failed"
+  log "set Actions secret ${SECRET_NAME} on ${REPO} (via stdin)"
+}
+
+# set_operator_login — the digest posts to a PRIVATE repo, and a `gh issue
+# create` into a repo with zero subscribers notifies nobody. That is not
+# hypothetical: the digest ran correctly for months while 130 days of
+# action-required backlog accumulated unseen, because the delivery channel was
+# dead. The workflow assigns each digest to this login so it notifies
+# unconditionally, independent of watch state.
+#
+# Repo VARIABLE, not a secret: a GitHub login is not confidential, and secrets
+# are masked in logs — masking the assignee would make a delivery failure
+# harder to diagnose, which is the failure mode being repaired.
+set_operator_login() {
+  local login="${OPERATOR_GH_LOGIN:-}"
+  if [[ -z "$login" ]]; then
+    login="$(gh api user --jq .login 2>/dev/null || true)"
+  fi
+  [[ -n "$login" ]] || die "could not resolve operator login; set OPERATOR_GH_LOGIN explicitly"
+  gh variable set OPERATOR_GH_LOGIN -R "$REPO" --body "$login" \
+    || die "gh variable set OPERATOR_GH_LOGIN on ${REPO} failed"
+  log "set Actions variable OPERATOR_GH_LOGIN=${login} on ${REPO} (digest assignee)"
+}
+
+# install_workflow — create-or-update the workflow on the default branch via the contents API.
+install_workflow() {
+  [[ -r "$WORKFLOW_ASSET" ]] || die "workflow asset not readable at ${WORKFLOW_ASSET}"
+  local b64 existing_sha
+  b64="$(base64 -w0 "$WORKFLOW_ASSET" 2>/dev/null || base64 "$WORKFLOW_ASSET" | tr -d '\n')"
+  existing_sha="$(gh api "repos/${REPO}/contents/${WORKFLOW_PATH}" --jq '.sha' 2>/dev/null || true)"
+  local args=(--method PUT "repos/${REPO}/contents/${WORKFLOW_PATH}"
+    -f "message=chore: install operator-digest workflow (#5085)"
+    -f "content=${b64}")
+  [[ -n "$existing_sha" ]] && args+=(-f "sha=${existing_sha}")
+  gh api "${args[@]}" >/dev/null || die "failed to install ${WORKFLOW_PATH} into ${REPO}"
+  log "installed ${WORKFLOW_PATH} into ${REPO}"
+}
+
+# enable_workflow — newly-added workflows may need a moment to register before `gh workflow enable`
+# can find them. Soft-retry the enable, then POSITIVELY verify the workflow state is `active`. This
+# is the terminal step of a fire-and-forget bootstrap whose operator is non-technical: a silently-
+# not-enabled workflow means the digest never fires, and a WARN buried in stderr of a "done" run is
+# effectively invisible. Fail loud (die) if it is not active — the script is idempotent, so the
+# operator can simply re-run. NOTE: `gh workflow view` has no --json; state lives on `gh workflow list`.
+enable_workflow() {
+  local state="" _
+  for _ in 1 2 3 4 5; do
+    gh workflow enable operator-digest.yml -R "$REPO" >/dev/null 2>&1 || true
+    state="$(gh workflow list -R "$REPO" --json path,state \
+      -q '.[] | select(.path==".github/workflows/operator-digest.yml") | .state' 2>/dev/null || true)"
+    if [[ "$state" == "active" ]]; then
+      log "operator-digest.yml is active on ${REPO}"
+      return 0
+    fi
+    sleep 3
+  done
+  die "operator-digest.yml is not active on ${REPO} (last state: '${state:-unknown}') — the digest will NOT fire. Re-run this script, or check 'gh workflow list -R ${REPO}'."
+}
+
+main() {
+  require_tools
+  fetch_secret          # fail-fast before creating anything
+  ensure_repo
+  set_secret "$SECRET_VALUE"
+  set_operator_login    # must precede install_workflow: the workflow fails loud without it
+  install_workflow
+  enable_workflow
+  log "done. Trigger a run with: gh workflow run operator-digest.yml -R ${REPO}"
+}
+
+# Only run main when executed directly — sourcing (e.g. from the test) is side-effect-free.
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  main "$@"
+fi

package/skills/operator-rephrase/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: operator-rephrase
+description: "This skill should be used when the last message did not land: say it again in short plain sentences, with no jargon, file paths or issue numbers."
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+<!-- Inspired by mattpocock/skills/skills/productivity/wait-what/SKILL.md (MIT, Copyright (c) 2026 Matt Pocock). -->
+
+# Operator Rephrase
+
+The previous message did not land. Say the **same thing** again, in a register the operator can act
+on. This is a restatement, not an escalation: no new facts, no extra detail, no lecture. If the
+content was wrong, fix the content — that is a different job than this one.
+
+## Register
+
+As defined in [operator-digest](../operator-digest/SKILL.md) §Register. Read it there; it is not
+restated here, because a second copy drifts from the first.
+
+### Delta from `operator-digest`
+
+Three differences, and only these:
+
+- **One message, not a document.** The output is the immediately preceding message said again — not
+  a section, not a report, not a digest.
+- **Synchronous.** Emit the rephrasing in the current turn. The digest is a scheduled headless
+  artifact; this is a reply.
+- **The business-consequence rule does not apply.** The digest cuts every line that does not state a
+  business consequence or an owner action. That rule would mangle an in-the-moment restatement of a
+  technical fact the operator asked about. Keep the fact; change only how it reads.
+
+## How to write the restatement
+
+The discipline is **influenced by ASD-STE100 Simplified Technical English**. This skill does not
+claim conformance to that standard — there is no controlled vocabulary in this repository to bind it
+to, and no gate that could check the claim. What is adopted is the checkable part:
+
+1. Write short sentences. One idea per sentence.
+2. Give one instruction per sentence. Do not chain two actions with "and then".
+3. Use each word in one sense. Pick the everyday sense and keep it for the whole message.
+4. Write in the active voice. Name who does the thing.
+5. Remove jargon, file paths, issue numbers, PR numbers, and command names. Name the effect instead
+   of the artifact that produces it. **Exception: keep any literal the operator must type, click or
+   paste** — a command to run, a button label, a value to enter. Put it alone on its own line,
+   unchanged; the sentences around it say what it does. A restatement that deletes the one string
+   the operator needs has removed the action along with the jargon.
+6. Open with the outcome. Put the reason after it, if the reason is still needed.
+
+## Vocabulary
+
+**The glossary is a stop-list, not a source of approved terms.** Rule 3 above is still satisfied by
+choosing plain everyday words, not by looking a term up — there is no controlled vocabulary of
+approved founder words here and there is not meant to be one.
+
+What `knowledge-base/project/glossary.md` gives this skill is the inverse, and it serves **rule 5**:
+it is the list of internal words that **must** be translated before the operator sees them. Each
+entry — or each sense of a multi-sense entry — opens with a plain clause saying what the thing is,
+and that clause is what you translate *into*. The repo-relative path in the entry body is for the
+agent; it is one of the things rule 5 strips, so it never appears in the restatement.
+
+Use it as a check, not as a lookup table: if a word you are about to say has an entry, say the plain
+clause instead of the word. A word with no entry is not thereby approved — plain language is still
+your own judgment.
+
+Do not point at `plugins/soleur/docs/pages/glossary.njk` — that is marketing surface, its entries are
+category terms rather than operational ones, and it is a Nunjucks template rather than readable plain
+text. `knowledge-base/marketing/brand-guide.md` is the founder-facing lexicon and is the right place
+for a word the operator *should* see.
+
+## When to self-invoke
+
+Invoke this skill in the same turn, without being asked by name, when the operator's reply is one
+of these shapes — each is "that did not land", not a new question:
+
+- "what?", "huh?", "sorry?"
+- "in plain English", "in normal words", "without the jargon"
+- "I don't follow", "I don't understand", "lost me"
+- "say that again", "come again", "one more time"
+- "what does that mean for me?", "so what do I do?"
+
+Do **not** invoke it when the operator asks for *more* detail, disputes a fact, or asks a follow-up
+question — those are new answers, not restatements.
+
+## Stop conditions
+
+- Stop after one restatement. If that one also does not land, ask which part did not land rather
+  than rephrasing a third time.
+- Do not apologise at length. One short acknowledgement at most, then the restatement.
+- Do not change the decision, the recommendation, or the facts while rephrasing them. A restatement
+  that says something different is a new answer wearing a rephrasing's clothes.
+
+## Siblings
+
+`soleur:operator-digest` is the scheduled weekly counterpart: same register, batched, written to a
+file rather than said in a turn.

package/skills/pencil-setup/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: pencil-setup
+description: "This skill should be used when Pencil MCP tools are unavailable. Detects Pencil Desktop or a Pencil-extension IDE and registers the MCP server with Claude Code CLI."
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Pencil Setup
+
+Auto-detect, install, and register the Pencil MCP server with Claude Code CLI.
+
+**Prerequisite:** One of: (1) the headless CLI (no GUI required, recommended for agents), (2) Pencil Desktop, or (3) an IDE (Cursor/VS Code) with the Pencil extension.
+
+**Known limitation:** macOS detection uses unverified bundle ID `dev.pencil.desktop` -- falls back to PATH-based detection if incorrect.
+
+## Phase 0: Dependency Check
+
+Run [check_deps.sh](./scripts/check_deps.sh) before proceeding. When invoked
+from a pipeline (e.g., one-shot), pass `--auto` to skip interactive prompts,
+auto-install the IDE extension, and auto-launch Pencil Desktop.
+
+For interactive use:
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/pencil-setup/scripts/check_deps.sh"
+```
+
+For pipeline/automated use:
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/pencil-setup/scripts/check_deps.sh" --auto
+```
+
+If the script exits non-zero, no Pencil MCP source is available. Stop and
+inform the user with the printed instructions (both Desktop and IDE options).
+
+If all checks pass, capture these values from the script output:
+
+- `PREFERRED_MODE` -- `headless_cli`, `cli`, `desktop_binary`, or `ide`
+- `PREFERRED_BINARY` -- path to binary (adapter for headless, `pencil` for CLI mode)
+- `PREFERRED_APP` -- `--app` flag value (empty for CLI and headless modes)
+- `PREFERRED_NODE` -- (headless_cli only) path to Node >= 22.9.0 binary
+
+Proceed to Step 1.
+
+## Step 1: Check if Already Registered
+
+<!-- verified: 2026-04-19 source: claude mcp list --help (the `-s` flag was dropped from `list`; plain `claude mcp list` now includes user-scoped entries) -->
+
+```bash
+claude mcp list 2>&1 | grep -q "pencil" && echo "REGISTERED" || echo "NOT_REGISTERED"
+```
+
+If REGISTERED, classify the existing registration mode by inspecting the binary path printed by `claude mcp list`:
+
+```bash
+existing=$(claude mcp list 2>&1 | grep pencil)
+case "$existing" in
+  *pencil-mcp-adapter*|*@pencil.dev/cli*|*pencil-cli*) existing_mode=headless_cli ;;
+  *visual_studio_code*|*cursor*)                       existing_mode=ide ;;
+  *--app\ pencil*|*mcp-server-*-x64*)                   existing_mode=desktop ;;
+  *)                                                   existing_mode=unknown ;;
+esac
+```
+
+**Auto-upgrade rule (when `--auto` is set):** if `existing_mode` is `ide` or `desktop` AND Phase 0 set `PREFERRED_MODE=headless_cli`, the existing registration is unsuitable for agent-driven flows (no programmatic save — see Sharp Edges §"No programmatic save"). Remove and re-register as headless instead of stopping:
+
+```bash
+if [[ "$AUTO_INSTALL" == "true" && "$existing_mode" != "headless_cli" && "$PREFERRED_MODE" == "headless_cli" ]]; then
+  echo "Upgrading Pencil MCP from $existing_mode → headless_cli (agent-driven flows require programmatic save)"
+  claude mcp remove pencil -s user 2>/dev/null || true
+  # Fall through to Step 2 to register fresh
+else
+  # Verify the registered binary path still exists on disk before declaring "ready".
+  # Extract the path from `claude mcp list` output, then `test -f <path>`.
+  case "$existing_mode" in
+    headless_cli) echo "Pencil MCP is already configured via headless CLI adapter. Restart Claude Code for tools to become available." ;;
+    desktop)      echo "Pencil MCP is already configured. Make sure Pencil Desktop is running, then restart Claude Code." ;;
+    ide)          echo "Pencil MCP is already configured. Make sure your IDE is running with Pencil active, then restart Claude Code. NOTE: IDE mode does not auto-save .pen edits — use --auto to upgrade to headless if running agent-driven flows." ;;
+    *)            echo "Pencil MCP is registered but mode could not be classified. Re-run with --auto to refresh registration." ;;
+  esac
+  # Stop here unless --auto-upgrading.
+fi
+```
+
+If the path does not exist, NOT_REGISTERED, or the auto-upgrade path was taken, continue to Step 2.
+
+## Step 2: Register MCP Server
+
+Registration varies by `PREFERRED_MODE` from Phase 0:
+
+Remove any existing registration first:
+
+```bash
+claude mcp remove pencil -s user 2>/dev/null
+```
+
+### Headless CLI mode (`PREFERRED_MODE=headless_cli`)
+
+**First**, sync the repo adapter into the user's install location so stale installed copies don't mask repo-level fixes (see #2630):
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/pencil-setup/scripts/copy_adapter.sh"
+```
+
+The adapter requires `PENCIL_CLI_KEY` in the MCP environment. Retrieve the key, then register with `-e` **before** the `--` separator:
+
+```bash
+# Retrieve the key (Doppler, or use pencil login token)
+PENCIL_KEY=$(doppler secrets get PENCIL_CLI_KEY -p soleur -c dev --plain 2>/dev/null)
+# If Doppler is not available, check for a stored login token:
+# PENCIL_KEY=$(cat ~/.config/pencil/auth.json 2>/dev/null | grep -o '"token":"[^"]*"' | cut -d'"' -f4)
+
+claude mcp add pencil -s user -e PENCIL_CLI_KEY="$PENCIL_KEY" -- <PREFERRED_NODE> <PREFERRED_BINARY>
+```
+
+Replace `<PREFERRED_NODE>` with the Node 22+ binary path and `<PREFERRED_BINARY>` with the adapter path from Phase 0.
+
+**Critical:** The `-e` flag must appear before `--`. Placing it after `--` passes it as a CLI arg to the adapter instead of setting an environment variable, causing silent auth failures.
+
+**Drift check.** If the adapter ever appears to "silently drop" operations, verify the installed copy is in sync with the repo:
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/pencil-setup/scripts/check_deps.sh" --check-adapter-drift
+# On DRIFT, re-sync: add --auto, or re-run copy_adapter.sh
+```
+
+### CLI mode (`PREFERRED_MODE=cli`)
+
+```bash
+claude mcp add -s user pencil -- pencil mcp-server
+```
+
+No `--app` flag needed -- the CLI handles connection internally.
+
+### Desktop binary mode (`PREFERRED_MODE=desktop_binary`)
+
+```bash
+claude mcp add -s user pencil -- <PREFERRED_BINARY> --app <PREFERRED_APP>
+```
+
+Replace `<PREFERRED_BINARY>` and `<PREFERRED_APP>` with values from Phase 0.
+
+### IDE mode (`PREFERRED_MODE=ide`)
+
+```bash
+claude mcp add -s user pencil -- <PREFERRED_BINARY> --app <PREFERRED_APP>
+```
+
+Replace `<PREFERRED_BINARY>` with the extension binary path and `<PREFERRED_APP>` with `cursor` or `visual_studio_code`.
+
+## Step 3: Verify
+
+```bash
+claude mcp list 2>&1 | grep pencil
+```
+
+If the `pencil` entry appears, tell the user:
+
+- **Headless CLI mode:** "Pencil MCP registered via headless adapter. Restart Claude Code for tools to become available. No GUI required."
+- **CLI/Desktop mode:** "Pencil MCP registered. Restart Claude Code for tools to become available. Make sure Pencil Desktop is running."
+- **IDE mode:** "Pencil MCP registered. Restart Claude Code for tools to become available. Make sure your IDE is open with Pencil active."
+
+If it does not appear, tell the user the registration failed and suggest running the commands manually.
+
+## Untracked .pen safety
+
+Rule `cq-before-calling-mcp-pencil-open-document` is canonical in `.claude/hooks/pencil-open-guard.sh` header (see that file for the full body and rationale). The hook is a PreToolUse deny on untracked `.pen` files; pre-flight to avoid the deny:
+
+```bash
+git -C <repo> ls-files --error-unmatch <path>   # exit 0 = tracked, exit 1 = untracked
+```
+
+For freshly-created `.pen` files, commit an empty or scaffold placeholder before the first `open_document` call.
+
+## Tracked .pen collapse recovery
+
+Rule `cq-pencil-collapse-auto-recover` is canonical in the `.claude/hooks/pencil-collapse-guard.sh` header `[hook-enforced: pencil-collapse-guard.sh]`. It is the deterministic backstop for the `open_document` truncation bug (#3274 / upstream #4859): the PreToolUse `pencil-open-guard.sh` only denies *untracked* `.pen`, and the soleur:product:design:ux-design-lead / brand-workshop prose HARD-GATEs (PR #4855) rely on agent discipline.
+
+The hook fires **PostToolUse** on `mcp__pencil__open_document`. When the on-disk `.pen` has collapsed to the unambiguous empty-document shape (`{"version":"...","children":[]}` or a 0-byte/whitespace truncation) while its committed `HEAD` blob is non-empty, it restores the file byte-identical from `git show HEAD:<path>` (written via a temp file + atomic `mv`) and emits a loud `additionalContext` system message. It is fail-open and non-destructive on every error path (`set -uo pipefail`, no `-e`; conservative collapse detection limited to the exact empty shape; symlinks are refused) — a guard that clobbers good work is strictly worse than the bug. It cannot *prevent* the truncation (PostToolUse runs after the write); the root-cause fix is upstream (#4859 Part B).
+
+**Caveat:** because PostToolUse cannot see the pre-call state, an *intentional* empty (you cleared all frames then reopened without committing) is indistinguishable from a truncation and will be reverted to `HEAD`. Commit the deliberate empty state first if you want it preserved.
+
+## Sharp Edges
+
+- **IDE mode -- WebSocket requires visible editor**: In IDE mode (`PREFERRED_MODE=ide`), the MCP server connects via WebSocket to the IDE's editor webview. `batch_design`/`batch_get`/`open_document` calls fail with `WebSocket not connected to app` unless the .pen file tab is open and visible in the IDE. Opening via `cursor <path>` CLI is not sufficient -- the user must click the tab to activate the webview.
+- **Desktop mode -- app must be running**: In CLI or Desktop binary mode, Pencil Desktop must be running. The MCP server connects to the Desktop app directly. If Desktop is not running, tools fail silently. Use `--auto` to auto-launch Desktop before registration.
+- **No programmatic save (Desktop/IDE only)**: In Desktop or IDE mode, after `batch_design` operations, changes exist in editor memory only. The user must Ctrl+S (IDE) or Cmd+S/Ctrl+S (Desktop) to flush to disk. In headless CLI mode, the adapter auto-calls `save()` after mutating operations — no manual save needed.
+- **Read before write**: Mockup property values (padding, colors, fonts) may diverge from live CSS. Always `batch_get` the current value before `batch_design` updates to avoid incorrect assumptions.
+- **pencil CLI collision**: The `pencil` binary name collides with evolus/pencil. The check_deps.sh script guards against this by verifying the version string contains "pencil.dev" or checking for the `mcp-server` subcommand.
+- **Headless CLI interactive mode is not MCP**: The Pencil npm headless CLI's `pencil interactive` command speaks a custom REPL format (`tool_name({ key: value })`), not MCP protocol. An adapter wrapper is needed to bridge it to Claude Code's MCP framework. The headless CLI also lacks the `mcp-server` subcommand that the Desktop-installed CLI exposes, and its version string (`pencil 0.2.3`) doesn't match existing detection patterns.
+- **Headless CLI has programmatic save**: Unlike Desktop/IDE modes, `pencil interactive --out` supports a `save()` command that writes to disk without manual Ctrl+S.
+- **Adapter child process Node version**: The pencil CLI uses `#!/usr/bin/env node`, so the resolved Node depends on PATH, not on the binary that launched the adapter. The adapter's `buildPencilEnv()` must prepend `dirname(process.execPath)` to PATH to ensure child processes inherit the correct Node version (22+).
+- **Text nodes do not support `padding`**: Passing `padding` to a `batch_design` operation on a text node produces "Invalid properties: /padding unexpected property". The adapter enriches this error with a hint, but the fix is to wrap the text in a frame and apply padding to the frame instead (see #1107 workaround).
+- **Silent-drop diagnosis**: When a Pencil MCP op appears to "silently drop" or produces a 0-byte `.pen`, verify in order: (a) `claude mcp get pencil` env has `PENCIL_CLI_KEY` matching Doppler `soleur/dev`, (b) `bash "${CLAUDE_PLUGIN_ROOT}/skills/pencil-setup/scripts/check_deps.sh" --check-adapter-drift` prints `OK`, (c) saved file `stat -c %s` > 0. "Headless stub" is NOT a known failure mode — the adapter has no stub code path. (`ex-cq-pencil-mcp-silent-drop-diagnosis-checklist`; #2630; `knowledge-base/project/learnings/bug-fixes/2026-04-19-ux-design-lead-headless-stub-fabrication.md`)