doco-cli 0.1.0

package/templates/agent-bootstrap/.claude/post-tool-use-check.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+# PostToolUse hook: after Edit/Write tool calls, cross-reference the
+# touched file against the prompt's pre-fetched /search.json hits. If a
+# Decision with vector_score > 0.45 names this file's basename or
+# relative path inside its body, inject an additionalContext block
+# nudging the agent to PATCH that Decision rather than skip-and-rationalize.
+#
+# Wired from `.claude/settings.json`. Hook input (JSON on stdin) carries:
+#   .hook_event_name = "PostToolUse"
+#   .tool_name       = "Edit" | "Write" | "MultiEdit" | "Bash" | ...
+#   .tool_input      = { file_path: "...", ... } for Edit/Write
+#   .tool_response   = { content, isError }
+#
+# Hook output is the JSON envelope:
+#   { "hookSpecificOutput": { "hookEventName": "PostToolUse",
+#                             "additionalContext": "<nudge text>" } }
+#
+# Soft nudge — never blocks the tool call. Silent exit 0 on every
+# failure path (no hits cached, no jq, no Decision body matches, etc).
+#
+# Per ADR-141 (decision_01KRK9P1FPF5ZAPJ4DXAKPXYFJ), item 8: catch
+# context-scrolled drift the moment an Edit lands, while the relevant
+# governing Decision is still surfaceable.
+
+set -u
+
+# 1. Read hook input.
+INPUT=$(cat 2>/dev/null || true)
+if [ -z "$INPUT" ] || ! command -v jq >/dev/null 2>&1; then
+  exit 0
+fi
+
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null || true)
+case "$TOOL_NAME" in
+  Edit|Write|MultiEdit|NotebookEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null || true)
+[ -z "$FILE_PATH" ] && exit 0
+
+# 2. Load .env so we have $PWD-ish context and DOCO_TOKEN. DOCO_ID
+#    lives in AGENTS.md (committed, non-secret) and is used to build
+#    the nudge URL — fall back to grepping AGENTS.md when it's not in
+#    env. Legacy repos with DOCO_ID still in .env keep working: env wins.
+if [ -f "$PWD/.env" ]; then
+  set -a
+  # shellcheck disable=SC1091
+  source "$PWD/.env"
+  set +a
+fi
+DOCO_BASE_URL="https://doco.to"
+DOCO_ID="${DOCO_ID:-}"
+if [ -z "$DOCO_ID" ]; then
+  for f in "$PWD/AGENTS.md" "$PWD/CLAUDE.md"; do
+    if [ -f "$f" ]; then
+      DOCO_ID=$(grep -oE 'doco_[A-Za-z0-9]+' "$f" | head -1)
+      [ -n "$DOCO_ID" ] && break
+    fi
+  done
+fi
+
+# 3. Locate the pre-fetched hits file written by user-prompt-fetch.sh.
+HITS_KEY=$(printf '%s' "$PWD" | shasum 2>/dev/null | awk '{print $1}' || printf 'default')
+HITS_FILE="${TMPDIR:-/tmp}/doco-last-hits-${HITS_KEY}.json"
+[ -f "$HITS_FILE" ] || exit 0
+[ -s "$HITS_FILE" ] || exit 0
+
+# 4. Compute substrings to search Decision bodies for.
+#    Conservative match: basename + repo-relative path (slashes stripped of
+#    leading $PWD). Decisions cite files in many shapes — basename catches
+#    the most, relative path narrows for ambiguous basenames like "index.ts".
+BASENAME=$(basename -- "$FILE_PATH")
+RELPATH="$FILE_PATH"
+case "$FILE_PATH" in
+  "$PWD"/*) RELPATH="${FILE_PATH#$PWD/}" ;;
+esac
+
+# 5. Find Decisions with vector_score > 0.45 whose body mentions either
+#    substring. We need the body, which /search.json hits DON'T carry —
+#    they expose summary + file_path. Match against summary first; if no
+#    summary hit, optionally fall back to reading the file_path (it's
+#    local: docos/<owner>/<doco>/decisions/<id>.md).
+MATCH_JSON=$(jq -c --arg b "$BASENAME" --arg r "$RELPATH" '
+  [ .hits[]?
+    | select(.node_type == "decision")
+    | select((.vector_score // 0) > 0.45)
+    | select(
+        ((.summary // "") | contains($b))
+        or ((.summary // "") | contains($r))
+        or ((.file_path // "") | contains("/decisions/"))
+      )
+  ]
+' "$HITS_FILE" 2>/dev/null || printf '[]')
+
+# Stage 2: for high-score Decisions whose summary didn't mention the path,
+# grep their on-disk body. Keep this bounded — top 5 by vector_score only.
+DEEP_MATCH=$(jq -c --arg b "$BASENAME" --arg r "$RELPATH" '
+  [ .hits[]?
+    | select(.node_type == "decision")
+    | select((.vector_score // 0) > 0.45)
+    | { id, summary, file_path, vector_score, slug: (.slug // .seq_id // .id) }
+  ] | sort_by(-.vector_score) | .[0:5]
+' "$HITS_FILE" 2>/dev/null || printf '[]')
+
+FINAL_MATCHES="[]"
+if [ "$DEEP_MATCH" != "[]" ] && [ -n "$DEEP_MATCH" ]; then
+  # Read each candidate's file_path, grep for basename/relpath, keep matches.
+  COUNT=$(printf '%s' "$DEEP_MATCH" | jq 'length' 2>/dev/null || echo 0)
+  i=0
+  ACC="[]"
+  while [ "$i" -lt "$COUNT" ]; do
+    CAND=$(printf '%s' "$DEEP_MATCH" | jq -c ".[$i]" 2>/dev/null)
+    CFP=$(printf '%s' "$CAND" | jq -r '.file_path // ""' 2>/dev/null)
+    if [ -n "$CFP" ] && [ -f "$CFP" ]; then
+      if grep -qF -- "$BASENAME" "$CFP" 2>/dev/null \
+         || grep -qF -- "$RELPATH" "$CFP" 2>/dev/null; then
+        ACC=$(printf '%s' "$ACC" | jq -c --argjson c "$CAND" '. + [$c]' 2>/dev/null || printf '%s' "$ACC")
+      fi
+    fi
+    i=$((i+1))
+  done
+  FINAL_MATCHES="$ACC"
+fi
+
+MATCH_COUNT=$(printf '%s' "$FINAL_MATCHES" | jq 'length' 2>/dev/null || echo 0)
+[ "$MATCH_COUNT" = "0" ] && exit 0
+
+# 6. Build the nudge text. List up to 3 matches with URLs.
+NUDGE_BODY=$(printf '%s' "$FINAL_MATCHES" | jq -r --arg host "$DOCO_BASE_URL" --arg doco_id "$DOCO_ID" --arg fp "$RELPATH" '
+  .[0:3] | map(
+    "- [" + (.slug // .id) + "](" + ($host) + "/by-id/" + ($doco_id) + "/decision/" + .id + ") (vector_score " + ((.vector_score // 0) | tostring) + "): " +
+      (if (.summary | length) > 200 then (.summary[:197] + "...") else .summary end)
+  ) | join("\n")
+' 2>/dev/null)
+
+[ -z "$NUDGE_BODY" ] && exit 0
+
+NUDGE=$(printf '🔮 Doco PostToolUse — file just edited (%s) is referenced in an existing Decision\n\nThis edit touched **%s**. The following Decision(s) from this prompt'\''s search hits cite this path in their body (vector_score > 0.45):\n\n%s\n\n**Consider PATCHing one of these Decisions** instead of opening a sibling. Per ADR-141: if a high-vector_score hit already governs the change, PATCH it (`doco patch decision <id> --append-body "..."`) rather than skipping the capture or creating a near-duplicate. Two overlapping nodes are strictly worse than one stale one.' \
+  "$RELPATH" "$RELPATH" "$NUDGE_BODY")
+
+# 7. Emit the JSON envelope.
+jq -nc --arg c "$NUDGE" \
+  '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $c}}'

package/templates/agent-bootstrap/.claude/settings.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://claude.com/schemas/settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(doco:*)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/bootstrap-fetch.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/user-prompt-fetch.sh",
+            "timeout": 8
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/post-tool-use-check.sh",
+            "timeout": 6
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/stop-check.sh",
+            "timeout": 6
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/agent-bootstrap/.claude/stop-check.sh

@@ -0,0 +1,206 @@
+#!/usr/bin/env bash
+# Stop hook: fires when the assistant finishes a turn. Parses the
+# session transcript to count Edit/Write tool calls, Doco write commands,
+# and user-facing Doco operation footers. It injects a final nudge for
+# either of the two common drift cases:
+#
+# - edits happened but no Doco capture/patch/write was attempted;
+# - Doco writes returned footer_lines, but the agent never pasted every
+#   footer line into user-facing text.
+#
+# Wired from `.claude/settings.json`. Hook input (JSON on stdin) carries:
+#   .hook_event_name = "Stop"
+#   .transcript_path = "/Users/.../.claude/projects/.../<session-id>.jsonl"
+#   .session_id, .cwd, .permission_mode, .effort
+#
+# Hook output is the JSON envelope:
+#   { "hookSpecificOutput": { "hookEventName": "Stop",
+#                             "additionalContext": "<nudge text>" } }
+#
+# Per ADR-141 (decision_01KRK9P1FPF5ZAPJ4DXAKPXYFJ), item 9: catch the
+# agent who edited code, drifted from canonical, and was about to
+# declare done without any capture.
+#
+# Soft nudge — never blocks the response. The agent already finished;
+# this just prepends one more reminder before the user sees the reply.
+# Silent exit 0 on every failure path.
+
+set -u
+
+# 1. Read hook input.
+INPUT=$(cat 2>/dev/null || true)
+if [ -z "$INPUT" ] || ! command -v jq >/dev/null 2>&1; then
+  exit 0
+fi
+
+TRANSCRIPT=$(printf '%s' "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null || true)
+[ -z "$TRANSCRIPT" ] && exit 0
+[ -f "$TRANSCRIPT" ] || exit 0
+
+# Loop-guard: when the Stop hook fires and emits additionalContext, the
+# agent may choose to continue (e.g. to capture or paste footers). If our last nudge is
+# still the latest user-message-shaped entry in the transcript, we've
+# already nudged this stretch — bail out to avoid double-nudging.
+if grep -q "Doco Stop nudge —" "$TRANSCRIPT" 2>/dev/null; then
+  # Already nudged. Only nudge again if a new Edit/Write/Bash came AFTER the
+  # nudge line. Cheap check: look at the last 100 lines of the transcript.
+  LAST_CHUNK=$(tail -c 200000 "$TRANSCRIPT" 2>/dev/null || true)
+  NUDGE_LINE=$(printf '%s\n' "$LAST_CHUNK" | grep -n "Doco Stop nudge —" | tail -1 | cut -d: -f1)
+  if [ -n "$NUDGE_LINE" ]; then
+    AFTER_NUDGE=$(printf '%s\n' "$LAST_CHUNK" | tail -n "+$NUDGE_LINE")
+    if ! printf '%s' "$AFTER_NUDGE" | grep -qE '"name":"(Edit|Write|MultiEdit|NotebookEdit|Bash)"'; then
+      exit 0
+    fi
+  fi
+fi
+
+# 2. Parse the current turn's tool-use events. "Current turn" = since
+#    the LAST user message in the transcript. Walk back from EOF until
+#    we hit a user role; everything after is this turn.
+#
+#    Transcript is JSONL — one event per line. Assistant tool calls
+#    appear as type=assistant with message.content[].type=tool_use
+#    objects carrying .name and .input.
+#
+#    We count Edit/Write/MultiEdit/NotebookEdit calls in tool_name, Doco
+#    write commands in Bash tool calls, footer lines printed by tools,
+#    and footer lines pasted into assistant text. The critical check is
+#    tool footer_lines > assistant footer_lines: the write succeeded, but
+#    the client never got the per-operation update.
+
+# Use python3 — it's preinstalled on macOS / most Linux and avoids the
+# multi-line jq+awk gymnastics. Falls back silently if python3 missing.
+if ! command -v python3 >/dev/null 2>&1; then
+  exit 0
+fi
+
+COUNTS=$(python3 - "$TRANSCRIPT" <<'PYEOF' 2>/dev/null || true
+import json, sys, re
+
+path = sys.argv[1]
+edits = 0
+doco_writes = 0
+assistant_footer_lines = 0
+tool_footer_lines = 0
+
+FOOTER_RE = re.compile(
+    r'\[(?:🔮|✅) Doco\]\s*(?:✍️|📝|🧹|➕|➖|🔁|🏷️|🗑️)\s+'
+)
+
+def text_from(value):
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        parts = []
+        for item in value:
+            if isinstance(item, str):
+                parts.append(item)
+            elif isinstance(item, dict):
+                parts.append(text_from(item.get('text') or item.get('content') or ''))
+        return '\n'.join(parts)
+    return ''
+
+def count_footer_lines(text):
+    return len(FOOTER_RE.findall(text or ''))
+
+with open(path, 'r', encoding='utf-8', errors='replace') as f:
+    lines = f.readlines()
+
+# Find index of the most recent user-message event. Skip queue-operation
+# entries (which are just transcript bookkeeping).
+last_user_idx = -1
+for i, line in enumerate(lines):
+    try:
+        d = json.loads(line)
+    except Exception:
+        continue
+    if d.get('type') == 'user' and d.get('message', {}).get('role') == 'user':
+        # Skip tool_result-shaped user messages (those are assistant's
+        # tool outputs being fed back, not a fresh user prompt).
+        content = d.get('message', {}).get('content')
+        if isinstance(content, str):
+            last_user_idx = i
+        elif isinstance(content, list):
+            has_text = any(
+                isinstance(c, dict) and c.get('type') == 'text'
+                for c in content
+            )
+            has_only_tool_results = all(
+                isinstance(c, dict) and c.get('type') == 'tool_result'
+                for c in content
+            ) if content else False
+            if has_text or not has_only_tool_results:
+                last_user_idx = i
+
+# Scan events AFTER the last user message.
+for line in lines[last_user_idx + 1:]:
+    try:
+        d = json.loads(line)
+    except Exception:
+        continue
+    content = d.get('message', {}).get('content', [])
+    if isinstance(content, str):
+        if d.get('type') == 'assistant':
+            assistant_footer_lines += count_footer_lines(content)
+        continue
+    if not isinstance(content, list):
+        continue
+    for c in content:
+        if not isinstance(c, dict):
+            continue
+        if d.get('type') == 'assistant' and c.get('type') == 'tool_use':
+            name = c.get('name', '')
+            inp = c.get('input', {}) or {}
+            if name in ('Edit', 'Write', 'MultiEdit', 'NotebookEdit'):
+                edits += 1
+            elif name == 'Bash':
+                cmd = inp.get('command', '') or ''
+                # Match CLI write surfaces and raw HTTP writes to capture
+                # endpoints. `doco scope add-rule` writes Rule nodes.
+                if re.search(r'\bdoco\s+(capture|patch|supersede)\b', cmd):
+                    doco_writes += 1
+                elif re.search(r'\bdoco\s+scope\s+add-rule\b', cmd):
+                    doco_writes += 1
+                elif re.search(r'curl[^|;&]*-X\s*(POST|PATCH|DELETE)[^|;&]*/api/[a-z]+(?:/\S*)?\.json', cmd, re.IGNORECASE):
+                    doco_writes += 1
+                elif re.search(r'curl[^|;&]*/api/[a-z]+(?:/\S*)?\.json[^|;&]*-X\s*(POST|PATCH|DELETE)', cmd, re.IGNORECASE):
+                    doco_writes += 1
+        elif d.get('type') == 'assistant' and c.get('type') == 'text':
+            assistant_footer_lines += count_footer_lines(c.get('text', '') or '')
+        elif d.get('type') == 'user' and c.get('type') == 'tool_result':
+            tool_footer_lines += count_footer_lines(text_from(c.get('content', '')))
+
+print(f"{edits} {doco_writes} {assistant_footer_lines} {tool_footer_lines}")
+PYEOF
+)
+
+EDITS=$(printf '%s' "$COUNTS" | awk '{print $1}')
+DOCO_WRITES=$(printf '%s' "$COUNTS" | awk '{print $2}')
+ASSISTANT_FOOTERS=$(printf '%s' "$COUNTS" | awk '{print $3}')
+TOOL_FOOTERS=$(printf '%s' "$COUNTS" | awk '{print $4}')
+EDITS="${EDITS:-0}"
+DOCO_WRITES="${DOCO_WRITES:-0}"
+ASSISTANT_FOOTERS="${ASSISTANT_FOOTERS:-0}"
+TOOL_FOOTERS="${TOOL_FOOTERS:-0}"
+
+# 3a. Doco wrote nodes, but the assistant didn't paste every returned
+#     footer line into user-facing text.
+if [ "$TOOL_FOOTERS" -gt "$ASSISTANT_FOOTERS" ] 2>/dev/null; then
+  NUDGE=$(printf '🔮 Doco Stop nudge — Doco write footer_lines not shown to user\n\nThis turn'\''s Doco write tool output contained %s footer line(s), but assistant text emitted %s. The closing tally is not a substitute for per-operation updates.\n\nBefore declaring done, paste every returned `footer_lines` entry verbatim, one per line, above the final tally. If multiple nodes were added or updated, the user should see one Doco operation line for each returned footer line.' \
+    "$TOOL_FOOTERS" "$ASSISTANT_FOOTERS")
+
+  jq -nc --arg c "$NUDGE" \
+    '{hookSpecificOutput: {hookEventName: "Stop", additionalContext: $c}}'
+  exit 0
+fi
+
+# 3b. Existing ADR-141 nudge: edits happened, but no Doco write signal.
+if [ "$EDITS" = "0" ] || [ "$DOCO_WRITES" != "0" ] || [ "$ASSISTANT_FOOTERS" != "0" ]; then
+  exit 0
+fi
+
+NUDGE=$(printf '🔮 Doco Stop nudge — turn had edits but no captures\n\nThis turn made %s Edit/Write tool call(s) but no `doco capture` / `doco patch` invocation and no footer-line was emitted. Before declaring done:\n\n1. **Name the existing node you'\''re relying on.** If a Decision, Rule, or Action already covers what you changed, the capture obligation is satisfied — but say *which* node. "CLI can'\''t capture Actions" or "too small for a Decision" are not naming a node.\n2. **If no node fits**, capture one now (`doco capture decision …`, `doco capture action …`, or `doco patch <type> <id> --append-body …` per ADR-141). One short Decision beats a months-from-now archaeology dig through `git log`.\n3. The Stop hook reminded you. Suppress this nudge by either capturing or by stating the node-name you'\''re relying on in your final summary.' \
+  "$EDITS")
+
+jq -nc --arg c "$NUDGE" \
+  '{hookSpecificOutput: {hookEventName: "Stop", additionalContext: $c}}'

package/templates/agent-bootstrap/.claude/user-prompt-fetch.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook: keep the Doco protocol fresh in the agent's
+# context on every turn, AND pre-fetch the /search.json result for the
+# user's prompt so the top-of-reply query indicator is pre-built.
+#
+# Wired from `.claude/settings.json`. Hook input (JSON on stdin) carries
+# `.prompt`. Hook output is the JSON envelope Claude Code's hook runner
+# expects: { hookSpecificOutput: { hookEventName: "UserPromptSubmit",
+# additionalContext: "<text>" } }.
+#
+# Why this exists: SessionStart loads the 24KB canonical_instructions
+# ONCE per session. As the context scrolls, the agent drifts — forgets
+# to render the query indicator, forgets footer lines, forgets capture
+# triggers. UserPromptSubmit fires on every message, so we re-push a
+# tight protocol checklist AND a fresh search result. Cost: ~1-4KB of
+# additionalContext per turn; benefit: structural compliance.
+#
+# Env vars consumed (sourced from $PWD/.env if not in shell):
+#   DOCO_TOKEN  optional bearer token (gates per-Doco context)
+#   DOCO_ID     "doco_..." — which Doco to query
+#
+# Per the `claude-md-strong-bootstrap-and-session-start-hook` Decision +
+# the `user-prompt-submit-hook-keeps-protocol-fresh` Decision (this
+# commit's iteration).
+
+set -u
+
+# 1. Read hook input from stdin.
+INPUT=$(cat 2>/dev/null || true)
+PROMPT=""
+if [ -n "$INPUT" ] && command -v jq >/dev/null 2>&1; then
+  PROMPT=$(printf '%s' "$INPUT" | jq -r '.prompt // ""' 2>/dev/null || true)
+fi
+
+# 2. Load .env if present. The production host is fixed at doco.to; env
+#    only carries the DOCO_TOKEN secret. DOCO_ID lives in AGENTS.md
+#    (committed, non-secret) — read it from there if it's not in env.
+#    Legacy repos with DOCO_ID still in .env keep working: env wins.
+if [ -f "$PWD/.env" ]; then
+  set -a
+  # shellcheck disable=SC1091
+  source "$PWD/.env"
+  set +a
+fi
+DOCO_BASE_URL="https://doco.to"
+DOCO_ID="${DOCO_ID:-}"
+if [ -z "$DOCO_ID" ]; then
+  for f in "$PWD/AGENTS.md" "$PWD/CLAUDE.md"; do
+    if [ -f "$f" ]; then
+      DOCO_ID=$(grep -oE 'doco_[A-Za-z0-9]+' "$f" | head -1)
+      [ -n "$DOCO_ID" ] && break
+    fi
+  done
+fi
+
+# 3. Build the protocol reminder — short, deterministic, every turn.
+#    Kept under 800 chars so the per-turn token cost stays bounded.
+read -r -d '' PROTOCOL_REMINDER <<'EOF' || true
+## Doco protocol — apply this in your reply
+
+1. TOP OF THE TURN'S FIRST TEXT OUTPUT (once per turn, NOT on intermediate progress updates between tool calls): paste the pre-fetched Doco block FIRST.
+
+   If the pre-fetched block says "[🔮 Doco] Not connected yet: <reason>", paste that exact line instead of any connected indicator. Do not render query/count/tally/footer lines while disconnected. Ask the project owner to authorize with `doco login --host https://doco.to`.
+
+   If connected and queried, render the two-line query indicator:
+   [🔮 Doco] <querying-verb>
+   [🔮 Doco] <N> relevant nodes found (<X.X>s)
+   If you didn't query (greeting, one-word ack), emit nothing at the top — no "Not querying" placeholder, no fallback line. Absence is the signal.
+   The pre-fetched connected block below has the verbs already picked at random plus real <N>/<X.Xs> — paste it verbatim.
+
+2. AFTER EVERY WRITE (POST/PATCH/DELETE on /api/*.json), only when connected: render every returned footer_lines entry verbatim, one per line, before the closing tally. Running `doco capture` / `doco patch` is not enough; the user-facing reply must contain the operation lines. Shape:
+   [🔮 Doco] <op-icon> <Type> <verb>: [<summary>](<url>) — <icon> <scope1>, <icon> <scope2>
+   The summary is the markdown link to the entity. Never show the raw ULID. Scope tail omitted when no scopes. Last line in a batch carries (X.Xs) timing AFTER the scope tail — already there.
+
+3. BEFORE DECLARING DONE: scan capture triggers. Scope names are BARE (no scope_ prefix) and match templates: user-flow changed → `user-flows` Decision. Bug fixed → `bugs` Decision + `bugs` Rule (`born_from: <decision_id>`). Framework touched (CLI / hooks / canonical) → add `framework`. ADR-shaped → `adrs`. POST to /api/decisions.json etc. via the host's capture endpoints. **If instinct says skip, name the existing node you're relying on — "CLI can't capture X" or "too small for a Decision" aren't naming a node. If a high-vector_score hit already governs the change, PATCH it instead of skipping.**
+
+4. CLOSING LINE OF THE TURN (once per turn, on the LAST text output only — NOT on intermediate progress updates between tool calls; even when 0 writes):
+   [🔮 Doco] <doco_id>: **<N>** node(s) added/updated
+   <N> = count of distinct entities you added/updated this turn (PATCH-3-fields-of-1-Decision = 1, not 3). The number MUST be wrapped in markdown bold (`**N**`). Singular when N == 1, plural otherwise (0 is plural). A "turn" is one user prompt → your complete answer, even when threaded through many tool calls; the tally bookends the turn, not each chunk.
+
+The full canonical_instructions was loaded at session start. Re-fetch via `doco bootstrap` if you've lost track and are connected.
+EOF
+
+# 4. Pre-fetch /search.json for the user's prompt so the agent doesn't
+#    have to. If anything needed for access is missing, pre-build the
+#    disconnected indicator so the agent never presents as connected.
+QUERY_BLOCK=""
+DISCONNECTED_REASON=""
+if [ -z "${DOCO_ID:-}" ]; then
+  DISCONNECTED_REASON="missing DOCO_ID"
+elif [ -z "${DOCO_TOKEN:-}" ]; then
+  DISCONNECTED_REASON="missing DOCO_TOKEN; ask the project owner to authorize with doco login --host https://doco.to"
+elif ! command -v curl >/dev/null 2>&1; then
+  DISCONNECTED_REASON="curl is not installed"
+elif ! command -v jq >/dev/null 2>&1; then
+  DISCONNECTED_REASON="jq is not installed"
+fi
+
+if [ -n "$DISCONNECTED_REASON" ]; then
+  QUERY_BLOCK=$(printf '\n\n## Doco connection for THIS prompt — paste as your top-of-reply indicator\n\n[🔮 Doco] Not connected yet: %s\n\nDo not render any other Doco indicator, footer, or tally lines until the connection is fixed.\n' "$DISCONNECTED_REASON")
+elif [ -n "$PROMPT" ]; then
+  ENC=$(printf '%s' "$PROMPT" | jq -sRr @uri 2>/dev/null || true)
+  TMP_RESP="${TMPDIR:-/tmp}/doco-search-$$.json"
+  HTTP_STATUS=$(curl -sS --max-time 5 -w '%{http_code}' -o "$TMP_RESP" \
+    -H "Authorization: Bearer ${DOCO_TOKEN}" \
+    "${DOCO_BASE_URL}/by-id/${DOCO_ID}/search.json?q=${ENC}&limit=10" 2>/dev/null || true)
+  RESP=$(cat "$TMP_RESP" 2>/dev/null || true)
+  rm -f "$TMP_RESP" 2>/dev/null || true
+  if [ "$HTTP_STATUS" = "200" ] && [ -n "$RESP" ]; then
+    COUNT=$(printf '%s' "$RESP" | jq -r '.count // 0' 2>/dev/null || echo 0)
+    MS=$(printf '%s' "$RESP" | jq -r '.duration_ms // 0' 2>/dev/null || echo 0)
+    SECS=$(awk -v ms="$MS" 'BEGIN { printf "%.1f", ms/1000 }')
+    HITS=$(printf '%s' "$RESP" | jq -r '
+      .hits[]? |
+      "- " + .node_type + " [" + (.slug // .seq_id // .id) + "]: " +
+        (if (.summary | length) > 120 then (.summary[:117] + "...") else .summary end)
+    ' 2>/dev/null | head -10)
+    # Random verbs — pick one at random. The variety is the point;
+    # the structured fields (slug, count, timing) stay identical.
+    LOADING_VERBS=("Connected to" "Tuned into" "Listening to" "Wired up to" "Synced with" "Plugged into" "Online with" "Reading" "Hooked into" "Eyes on" "Riding shotgun on" "Pinned to" "Threaded into" "Locked onto" "Channel open:" "Live on" "Mind-melded with" "Pulled up" "Holding the file on")
+    QUERYING_VERBS=("Querying..." "Looking it up..." "Asking around..." "Reading the room..." "Sniffing for hits..." "Flipping through notes..." "Scanning the graph..." "Searching the lore..." "Peering into the orb..." "Combing the archive..." "Hunting for prior art..." "Pinging the memory..." "Cross-referencing..." "Checking what's known..." "Tracing the trail..." "Diving in..." "Polling the Doco..." "Skimming the index..." "Asking the oracle..." "Searching...")
+    LOADING_VERB="${LOADING_VERBS[$RANDOM % ${#LOADING_VERBS[@]}]}"
+    QUERYING_VERB="${QUERYING_VERBS[$RANDOM % ${#QUERYING_VERBS[@]}]}"
+    QUERY_BLOCK=$(printf '\n\n## Pre-fetched query for THIS prompt — paste as your top-of-reply indicator\n\n[🔮 Doco] %s\n[🔮 Doco] %s %s. %s relevant nodes found (%ss)\n\nTop hits:\n%s\n' \
+      "$QUERYING_VERB" "$LOADING_VERB" "$DOCO_ID" "$COUNT" "$SECS" "$HITS")
+    # Persist the full hits JSON for cross-hook reads (PostToolUse path-match).
+    # Namespace by $PWD hash so concurrent worktrees don't stomp each other.
+    # The PostToolUse hook reads this on every Edit/Write tool call.
+    HITS_KEY=$(printf '%s' "$PWD" | shasum 2>/dev/null | awk '{print $1}' || printf 'default')
+    HITS_FILE="${TMPDIR:-/tmp}/doco-last-hits-${HITS_KEY}.json"
+    printf '%s' "$RESP" > "$HITS_FILE" 2>/dev/null || true
+  else
+    # For 403 (no_access) and 404 (not_found) the host returns rich
+    # recovery guidance in the response body (see
+    # packages/web/app/lib/missing-doco-guidance.server.ts). Prefer
+    # that body verbatim — it tells the user how to recover instead
+    # of just naming the failure. Fall back to a short reason string
+    # when the body is missing (host down, unauthorized token, etc.).
+    REASON=""
+    case "$HTTP_STATUS" in
+      000) REASON="doco.to unreachable" ;;
+      401) REASON="DOCO_TOKEN is missing or expired; ask the project owner to authorize with doco login --host https://doco.to" ;;
+      *) REASON="search failed with HTTP ${HTTP_STATUS}" ;;
+    esac
+    GUIDANCE=""
+    if [ -n "$RESP" ] && { [ "$HTTP_STATUS" = "403" ] || [ "$HTTP_STATUS" = "404" ]; }; then
+      GUIDANCE="$RESP"
+    fi
+    if [ -n "$GUIDANCE" ]; then
+      # First line of the body is the title — use it for the indicator
+      # so the [🔮 Doco] Not connected yet: line stays single-logical-line.
+      # Show the rest below as the recovery section.
+      FIRST_LINE=$(printf '%s' "$GUIDANCE" | head -n 1)
+      REST=$(printf '%s' "$GUIDANCE" | tail -n +2)
+      QUERY_BLOCK=$(printf '\n\n## Doco connection for THIS prompt — paste as your top-of-reply indicator\n\n[🔮 Doco] Not connected yet: %s\n\nThen show the project owner this recovery guidance from the host (do not render any other Doco indicator, footer, or tally lines until the connection is fixed):\n\n%s\n' \
+        "$FIRST_LINE" "$REST")
+    else
+      QUERY_BLOCK=$(printf '\n\n## Doco connection for THIS prompt — paste as your top-of-reply indicator\n\n[🔮 Doco] Not connected yet: %s\n\nDo not render any other Doco indicator, footer, or tally lines until the connection is fixed.\n' "$REASON")
+    fi
+  fi
+fi
+
+# 5. Emit the JSON envelope. additionalContext = reminder + pre-fetch.
+FULL="${PROTOCOL_REMINDER}${QUERY_BLOCK}"
+if command -v jq >/dev/null 2>&1; then
+  jq -nc --arg c "$FULL" \
+    '{hookSpecificOutput: {hookEventName: "UserPromptSubmit", additionalContext: $c}}'
+else
+  # jq missing — degrade. Output a minimal envelope referring the agent
+  # to the manual reminder.
+  printf '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"Doco protocol reminder unavailable (jq missing). Render the query indicator at top + footer_lines after writes manually; see CANONICAL_INSTRUCTIONS."}}\n'
+fi

package/templates/agent-bootstrap/.env.example

@@ -0,0 +1,21 @@
+# Doco agent-bootstrap env. Copy to .env and fill in. .env is gitignored
+# by `doco init`; never commit secrets.
+#
+# Easiest path: don't fill this in by hand — run
+#   doco login --host https://doco.to --create <slug>
+# from the repo root. The CLI opens a browser tab where the project
+# owner approves the session and (optionally) creates a new Doco, then
+# the CLI writes DOCO_TOKEN below to ./.env automatically and stamps
+# DOCO_ID into the AGENTS.md header. See the "Where DOCO_ID and
+# DOCO_TOKEN live" section of AGENTS.md for the full flow.
+#
+# Read by .claude/bootstrap-fetch.sh (SessionStart hook) and
+# .claude/user-prompt-fetch.sh (UserPromptSubmit hook). DOCO_ID is NOT
+# here — it lives in AGENTS.md (committed, non-secret coordinator); the
+# hooks fall back to reading it from there.
+
+# Bearer token for write capture (POST/PATCH on /api/*.json) + per-Doco
+# context on the bootstrap response. Minted by `doco login` (recommended)
+# or via /by-id/<doco_id>/settings → "Issue token". Treat as
+# secret.
+DOCO_TOKEN=