@cairnkeep/cli 1.0.2

package/claude/hooks/context-explore-pretask.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# context-explore-pretask.sh — UserPromptSubmit hook (fires when the user
+# submits a prompt, before the model responds).
+#
+# Auto-invokes context_explore for the submitted prompt so exploration runs
+# for a task with no manual /context-explore call (CTX-09). Double opt-in
+# (D-07): inert unless CAIRN_EXPLORE_BINARY is set AND
+# CAIRN_EXPLORE_AUTOINVOKE=1. High-signal gated: skips short prompts, slash
+# commands, and bare acknowledgements. Shells out to the shared `explore` CLI
+# subcommand (D-06) with an explicit short timeout (Pitfall 1) so cache
+# (CTX-10) and cross-refs (CTX-08) apply identically to hook and MCP-tool
+# invocations. Fail-open: any error injects nothing, exit 0 always.
+#
+# Protocol: JSON on stdin { prompt, ... }. Output: JSON
+# { hookSpecificOutput: { hookEventName, additionalContext } } only when the
+# explore result is ok:true with non-empty citations; empty output otherwise.
+set -euo pipefail
+
+# Double opt-in (D-07): inert unless both are set.
+[ -n "${CAIRN_EXPLORE_BINARY:-}" ] || exit 0
+[ "${CAIRN_EXPLORE_AUTOINVOKE:-}" = "1" ] || exit 0
+
+INFRA_ROOT="@@INFRA_ROOT@@"
+SERVER_ENTRY="$INFRA_ROOT/mcp-memory-server/dist/index.js"
+[ -f "$SERVER_ENTRY" ] || exit 0
+
+input="$(cat)"
+
+# Extract the submitted prompt text.
+prompt="$(printf '%s' "$input" | python3 -c 'import sys,json
+try:
+    d=json.load(sys.stdin)
+    print(d.get("prompt") or "")
+except Exception: print("")' 2>/dev/null || true)"
+[ -n "$prompt" ] || exit 0
+
+# Low-signal skip (Open Question 2 -- ponytail: first-pass heuristic, not a
+# rigorously derived one; revisit thresholds if noise/misses show up live).
+# Skips: too short, a slash command, or a bare acknowledgement.
+[ "${#prompt}" -ge 10 ] || exit 0
+case "$prompt" in
+  /*) exit 0 ;;
+esac
+if printf '%s' "$prompt" | grep -Eqi '^[[:space:]]*(ok|yes|no|thanks?)\.?[[:space:]]*$'; then
+  exit 0
+fi
+
+# Explicit short timeout (Pitfall 1) -- never the tool's own 120s default.
+# `|| true` so a timeout/failure never aborts the hook (fail-open).
+result="$(timeout 20 node "$SERVER_ENTRY" explore "$prompt" 2>/dev/null || true)"
+[ -n "$result" ] || exit 0
+
+# Inject only on ok:true + non-empty citations (D-07); compact citations +
+# cross-ref flags only, never expanded_snippets (D-14).
+context="$(printf '%s' "$result" | python3 -c 'import sys,json
+try:
+    d=json.load(sys.stdin)
+    if d.get("ok") is not True:
+        sys.exit(0)
+    citations = d.get("citations") or []
+    if not citations:
+        sys.exit(0)
+    lines=[]
+    for c in citations:
+        line = str(c.get("path")) + ":" + str(c.get("start_line")) + "-" + str(c.get("end_line"))
+        parts=[]
+        if c.get("memory_refs"):
+            parts.append("memory: " + ", ".join(c["memory_refs"]))
+        if c.get("wiki_refs"):
+            parts.append("wiki: " + ", ".join(c["wiki_refs"]))
+        if parts:
+            line += " <- " + " - ".join(parts)
+        lines.append(line)
+    print("\n".join(lines))
+except Exception:
+    pass' 2>/dev/null || true)"
+[ -n "$context" ] || exit 0
+
+context="$(printf '%s\n' "$context" | head -40)"
+
+# Emit the hook output JSON that injects additionalContext for this prompt.
+# The prefix identifies the block as auto-invoked exploration context so the
+# model knows its provenance (D-14).
+python3 -c 'import sys,json
+ctx = sys.stdin.read()
+print(json.dumps({
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "Auto-invoked exploration context (context_explore, no manual /context-explore call):\n\n" + ctx
+  }
+}))' <<<"$context" 2>/dev/null || true
+
+exit 0

package/claude/hooks/memory-capture.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# memory-capture.sh — SessionEnd hook (Claude Code + OpenCode share this protocol).
+#
+# At session end, extract durable memory candidates from the session transcript
+# using the configured extraction model, and stage them for review — NOT write
+# them directly. The next session's memory-wakeup.sh surfaces staged candidates;
+# /memory-review is the accept gate that writes accepted ones to AgentFS via the
+# cairn-memory MCP. This keeps writes agent-gated (no premature/auto writes, no
+# AgentFS lock contention) while making extraction fully automatic.
+#
+# Protocol: JSON on stdin with { transcript_path, cwd, hook_event_name, ... }.
+# ponytail: no-op outside a bootstrapped repo or when the extraction config is
+# absent, so it is safe as a global hook.
+set -euo pipefail
+
+repo="$(pwd)"
+[ -f "$repo/.agentfs/project.db" ] || exit 0
+
+INFRA_ROOT="@@INFRA_ROOT@@"
+SERVER_ENTRY="$INFRA_ROOT/mcp-memory-server/dist/index.js"
+TEXT_HELPER="$INFRA_ROOT/scripts/transcript-to-text.mjs"
+[ -f "$SERVER_ENTRY" ] || exit 0
+[ -z "${CAIRN_LLM_API_KEY:-}" ] && exit 0
+EXTRACT_MODEL="${CAIRN_LLM_EXTRACTION_MODEL:-}"
+[ -z "$EXTRACT_MODEL" ] && exit 0
+
+# Read hook JSON from stdin; pull transcript_path (fail-open if absent/malformed).
+input="$(cat)"
+transcript_path="$(printf '%s' "$input" | python3 -c 'import sys,json
+try:
+    d=json.load(sys.stdin); print(d.get("transcript_path",""))
+except Exception: print("")' 2>/dev/null || true)"
+[ -n "$transcript_path" ] && [ -f "$transcript_path" ] || exit 0
+
+# Convert transcript JSONL → readable text, then extract candidates.
+text="$(node "$TEXT_HELPER" "$transcript_path" 2>/dev/null || true)"
+[ -n "$text" ] || exit 0
+
+candidates_json="$(printf '%s' "$text" | node "$SERVER_ENTRY" extract "$EXTRACT_MODEL" 2>/dev/null || true)"
+[ -n "$candidates_json" ] || exit 0
+
+count="$(printf '%s' "$candidates_json" | python3 -c 'import sys,json
+try:
+    d=json.load(sys.stdin); print(len(d.get("candidates",[])))
+except Exception: print(0)' 2>/dev/null || echo 0)"
+[ "$count" -gt 0 ] || exit 0
+
+# Stage for the next session's accept gate. One file per session.
+mkdir -p "$repo/.planning/memory-staging"
+ts="$(date -u +%Y%m%dT%H%M%SZ)"
+stage_file="$repo/.planning/memory-staging/$ts.json"
+printf '%s\n' "$candidates_json" > "$stage_file"
+
+# Keep the staging dir bounded — drop the oldest beyond 5 sessions.
+ls -1t "$repo/.planning/memory-staging/"*.json 2>/dev/null | tail -n +6 | while read -r old; do
+  rm -f "$old"
+done
+
+exit 0

package/claude/hooks/memory-recall.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# memory-recall.sh — PreToolUse hook (fires before Edit/Write/MultiEdit).
+#
+# When the model is about to edit a file, surface AgentFS facts and wiki pages
+# that specifically mention that file. This turns "the model might search memory"
+# into "the model always sees relevant pitfalls/decisions for the exact file."
+#
+# High-signal / low-noise design: injects context ONLY when there is a specific
+# match (memory preview or wiki page mentioning the file path or basename). If
+# nothing specific matches, it injects nothing — no noise on routine edits.
+#
+# Protocol: JSON on stdin { tool_name, tool_input: { file_path, ... }, cwd, ... }.
+# Output: JSON { hookSpecificOutput: { hookEventName, additionalContext } } when
+# there is a match; empty output otherwise. Fail-open: any error exits 0.
+set -euo pipefail
+
+repo="$(pwd)"
+[ -f "$repo/.agentfs/project.db" ] || [ -d "$repo/.planning/wiki/sources" ] || exit 0
+
+INFRA_ROOT="@@INFRA_ROOT@@"
+SERVER_ENTRY="$INFRA_ROOT/mcp-memory-server/dist/index.js"
+
+input="$(cat)"
+
+# Extract the target file path from the tool input.
+file_path="$(printf '%s' "$input" | python3 -c 'import sys,json
+try:
+    d=json.load(sys.stdin); ti=d.get("tool_input",{})
+    print(ti.get("file_path") or ti.get("path") or "")
+except Exception: print("")' 2>/dev/null || true)"
+[ -n "$file_path" ] || exit 0
+
+# Derive search tokens: basename and the repo-relative stem.
+base="$(basename "$file_path")"
+stem="${base%.*}"
+# Avoid matching on tiny/generic stems that would noise up results.
+[ "${#stem}" -lt 4 ] && exit 0
+
+matches=()
+
+# 1. AgentFS project memory: filter the compact wakeup index by the stem.
+if [ -f "$repo/.agentfs/project.db" ] && [ -f "$SERVER_ENTRY" ]; then
+  idx="$(node "$SERVER_ENTRY" wakeup 2>/dev/null || true)"
+  if [ -n "$idx" ]; then
+    hit_lines="$(printf '%s' "$idx" | grep -iF "$stem" 2>/dev/null | head -8 || true)"
+    if [ -n "$hit_lines" ]; then
+      matches+=("## Relevant project memory for $base" "" "$hit_lines" "")
+    fi
+  fi
+fi
+
+# 2. Wiki source pages whose name or content mentions the path/basename.
+if [ -d "$repo/.planning/wiki/sources" ]; then
+  wiki_hits=""
+  while IFS= read -r page; do
+    [[ -n "$page" ]] || continue
+    if grep -qiF "$stem" "$page" 2>/dev/null; then
+      # Pull the first stable-fact bullet as a teaser.
+      teaser="$(grep -m1 -E '^- \*\*' "$page" 2>/dev/null | cut -c1-160 || true)"
+      wiki_hits+="- [$(basename "$page")] ${teaser}"$'\n'
+    fi
+  done < <(find "$repo/.planning/wiki/sources" -maxdepth 1 -name '*.md' -type f 2>/dev/null)
+  if [ -n "$wiki_hits" ]; then
+    matches+=("## Relevant wiki pages for $base" "" "${wiki_hits}" "")
+  fi
+fi
+
+# Inject only when there is something specific.
+if [ "${#matches[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+context="$(printf '%s\n' "${matches[@]}" | head -40)"
+# Emit the hook output JSON that injects additionalContext before the tool runs.
+python3 -c 'import sys,json
+ctx = sys.stdin.read()
+print(json.dumps({
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "additionalContext": "Memory recall (auto-injected for this file edit):\n\n" + ctx
+  }
+}))' <<<"$context" 2>/dev/null || true
+
+exit 0

package/claude/hooks/memory-wakeup.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# SessionStart hook: surface the memory layers that are otherwise invisible at
+# session start (AgentFS project scope + wiki index). File-memory (MEMORY.md)
+# already auto-loads, so it is not duplicated here.
+# ponytail: no-op outside a managed repo, so it is safe as a global hook.
+set -euo pipefail
+
+repo="$(pwd)"
+[ -f "$repo/.agentfs/project.db" ] || [ -f "$repo/.planning/wiki/index.md" ] || exit 0
+
+if [ -f "$repo/.agentfs/project.db" ]; then
+  echo "## Project memory (AgentFS)"
+  node "@@INFRA_ROOT@@/mcp-memory-server/dist/index.js" wakeup 2>/dev/null || true
+fi
+
+if [ -f "$repo/.planning/wiki/index.md" ]; then
+  echo
+  echo "## Wiki index"
+  cat "$repo/.planning/wiki/index.md"
+fi
+
+# Surface open HARD wiki contradictions so the agent (and user) see them at
+# session start without anyone having to remember to scan the register. Hard
+# entries cannot both be correct and must be resolved before dependent work.
+contradictions="$repo/.planning/wiki/CONTRADICTIONS.md"
+if [ -f "$contradictions" ]; then
+  open_hard="$(awk '/<!-- wiki:contradictions:open:start -->/{f=1;next} /<!-- wiki:contradictions:open:end -->/{f=0} f' "$contradictions" | grep -iE 'severity:[[:space:]]*hard')"
+  if [ -n "$open_hard" ]; then
+    echo
+    echo "## Open HARD contradictions — resolve before dependent work"
+    echo "$open_hard"
+  fi
+fi
+
+# Surface staged memory candidates captured by the SessionEnd hook
+# (memory-capture.sh). These are extracted automatically from the last session
+# but NOT yet written to AgentFS — /memory-review is the accept gate.
+if [ -d "$repo/.planning/memory-staging" ]; then
+  staged="$(ls -1 "$repo/.planning/memory-staging/"*.json 2>/dev/null | wc -l)"
+  if [ "$staged" -gt 0 ]; then
+    echo
+    echo "## Staged memory candidates ($staged session(s)) — UNREVIEWED"
+    echo "Run /memory-review to accept (→ AgentFS) or discard these before doing other work."
+  fi
+fi

package/docs/building-an-overlay.md

@@ -0,0 +1,117 @@
+# Building a private overlay
+
+Cairnkeep is deliberately provider-neutral: it hardcodes no endpoints, no
+credentials, and no organization-specific launchers. Everything specific to
+*your* environment — internal LLM endpoints, proxies, credentials, corporate
+launchers, policy — belongs in a small private **overlay** that wraps cairnkeep.
+This guide shows the pattern.
+
+## Principles
+
+1. **Consume, don't fork.** Treat cairnkeep as an upstream dependency: install it
+   from npm (`npm i -g @cairnkeep/cli`) or clone it at a **pinned tag**. Never copy or
+   patch core files — if core behaviour must change, request it upstream. That way
+   you pick up fixes by bumping one version.
+2. **One-way references.** Your overlay may reference cairnkeep freely. Nothing
+   private — internal hosts, IPs, tokens, employer/vendor names — should ever end
+   up *in cairnkeep* (in code, docs, or commit messages). Keep those in your
+   overlay only, and keep secrets in untracked `.env` files or a secret store,
+   never committed.
+3. **Wrap at the seams, don't reimplement.** Cairnkeep's launchers and tools
+   expose extension points (below). Use them instead of replacing core behaviour.
+
+## The launcher seams
+
+The generic launchers (`.ai/start-claude.sh`, `.ai/start-opencode.sh`, scaffolded
+by `cairn bootstrap`) run three optional hooks, each a no-op when absent:
+
+| Seam | When | Use it for |
+|---|---|---|
+| `.ai/pre-launch.sh` | sourced after `.env`, before launch | export a provider base URL / credentials, refresh a token, run a connectivity check, or **abort** the launch by returning non-zero |
+| `CAIRN_EXTRA_SETTINGS` | read just before launch | path to a settings file layered onto the harness (`--settings` for Claude Code, `--config` for OpenCode); process env still wins, so an inline value beats the file |
+| `.ai/post-exit.sh` | sourced after the harness exits | teardown; `CAIRN_EXIT_STATUS` holds the exit code |
+
+**Typical overlay launcher** — a corporate wrapper needs a non-default provider
+plus a credential refresh. Instead of forking the launcher, drop a
+`.ai/pre-launch.sh`:
+
+```bash
+# .ai/pre-launch.sh  (sourced by the generic launcher)
+# 1. refresh whatever credential your provider needs
+./.ai/refresh-credentials.sh || return 1        # non-zero aborts the launch
+# 2. render your provider settings and hand them to the harness
+envsubst < ./.ai/provider-settings.json.template > /tmp/provider.$$.json
+export CAIRN_EXTRA_SETTINGS=/tmp/provider.$$.json
+export ANTHROPIC_BASE_URL="$MY_INTERNAL_GATEWAY"
+```
+
+The user still runs the standard `./.ai/start-claude.sh`; the overlay's behaviour
+is injected by the file's presence.
+
+## An overlay install script
+
+Make it one idempotent command from a fresh machine:
+
+```bash
+# 1. Get cairnkeep at a pinned version (npm or a pinned clone)
+npm i -g @cairnkeep/cli@1.0.2      # or: git clone … && git checkout v1.0.2
+
+# 2. Register the memory server with your harness
+claude mcp add cairn-memory -s user -- cairn memory-server
+
+# 3. Scaffold the target project (contributor mode if you don't own the repo)
+cairn bootstrap --untracked /path/to/project
+
+# 4. Install the operating layer — GLOBAL or PROJECT-SCOPED (below)
+sync-claude-assets.sh --apply                      # global ~/.claude
+# or keep it to one project:
+sync-claude-assets.sh --apply --live-root /path/to/project/.claude
+
+# 5. Drop your corporate launcher/helpers/.env template into /path/to/project/.ai/
+```
+
+### Global vs project-scoped operating layer
+
+`sync-claude-assets.sh` installs commands/agents/hooks into `~/.claude` by default
+(global — affects every project). To onboard a single project **without** touching
+global config or other projects, install into that project's `.claude/` with
+`--live-root <project>/.claude`; the project's local assets take precedence there
+while the rest of the machine is untouched.
+
+### Contributor mode
+
+If you don't own the target repo, `cairn bootstrap --untracked` writes the
+scaffold paths into the repo's `.git/info/exclude` — nothing to commit, invisible
+to other contributors, no edit to the shared `.gitignore`. To move the durable
+memory itself between machines, use `cairn memory export` / `cairn memory import`.
+
+## Isolating your memory server
+
+If your overlay runs its own memory server and you don't want a globally-registered
+one bleeding in, launch the harness with `--strict-mcp-config --mcp-config
+.ai/mcp.json`, listing only the servers you want. A launcher that adds these flags
+when `.ai/mcp.json` is present gives you per-project MCP isolation.
+
+## Wiring the optional integrations
+
+All optional, all env-gated — a wrapper turns them on by setting the env:
+
+| Integration | Turn on with | See |
+|---|---|---|
+| Memory extraction / semantic search | `CAIRN_LLM_API_KEY` + `CAIRN_LLM_API_URL` (+ embedding vars) | [operating.md](operating.md) |
+| Document RAG (`domain_knowledge_*`) | `ANYTHINGLLM_API_KEY` (+ `ANYTHINGLLM_BASE_URL`, `CAIRN_ANYTHINGLLM_SYNC_SCRIPT`) | [domain-knowledge.md](domain-knowledge.md) |
+| Routing seam (`route_check`) | `CAIRN_ROUTE_ENDPOINT` | [operating.md](operating.md) |
+| Context exploration (`context_explore`) | `CAIRN_EXPLORE_BINARY` (+ `CAIRN_EXPLORE_REPO_ROOT`) | [operating.md](operating.md) |
+| Networked memory (HTTP transport) | `MCP_HTTP_PORT` + `CAIRN_MEMORY_HTTP_TOKEN` | [operating.md](operating.md) |
+
+Point the RAG sync script at your own copy (`CAIRN_ANYTHINGLLM_SYNC_SCRIPT`) so the
+integration scripts live in your overlay, not the core.
+
+## Checklist
+
+- [ ] cairnkeep pinned to a version; no core files copied or patched
+- [ ] All internal hosts/tokens in untracked `.env` / secret store, never committed
+- [ ] Provider/credential setup in `.ai/pre-launch.sh`, not a forked launcher
+- [ ] Operating layer scoped as intended (global vs `--live-root`)
+- [ ] Optional integrations wired only where wanted
+- [ ] A single documented command takes a fresh machine to a working setup

package/docs/domain-knowledge.md

@@ -0,0 +1,86 @@
+# Domain knowledge (RAG) — optional
+
+Cairnkeep's memory server exposes two **optional** document-RAG tools alongside
+the `memory_*` tools:
+
+- **`domain_knowledge_query`** — ask a question against a document workspace and
+  get a grounded answer with citations.
+- **`domain_knowledge_sync`** — (re)embed a project's documentation into a
+  workspace.
+
+These are a thin bridge to a running **[AnythingLLM](https://anythingllm.com/)**
+instance (a generic, self-hostable document-RAG product). They are **off unless
+you configure them** — cairnkeep hosts no RAG engine, ships no documents, and
+hardcodes no endpoint. If you never set `ANYTHINGLLM_API_KEY`, the tools simply
+error at call time and nothing else is affected; `memory_*` and the wiki layer
+work exactly the same without them.
+
+## What you need
+
+1. A running AnythingLLM instance with at least one **workspace** that has your
+   documents embedded. (Local via podman/docker, or any reachable instance.)
+2. An AnythingLLM **API key**.
+3. cairnkeep pointed at it (below).
+
+## Configuration
+
+| Variable | Purpose |
+|---|---|
+| `ANYTHINGLLM_API_KEY` | **Required** for the domain-knowledge tools. Unset → the tools error at call time (everything else works). |
+| `ANYTHINGLLM_BASE_URL` | AnythingLLM base URL. Default `http://localhost:3001`. |
+| `CAIRN_ANYTHINGLLM_SYNC_SCRIPT` | Path to the document-sync script used by `domain_knowledge_sync`. The core does not bundle one — point this at your own (see below). Unset → `domain_knowledge_sync` uses the in-repo default path. |
+
+The workspaces the tools target come from the project's **memory config** — the
+first of `.agent/memory.json`, `.opencode/memory.json`, `.claude/memory.json`, or
+`memory.json` that exists:
+
+```json
+{
+  "scopes": ["identity"],
+  "anythingllm_workspaces": ["engineering-patterns", "my-project-docs"]
+}
+```
+
+`domain_knowledge_query` takes an explicit `workspace`, or falls back to the first
+configured workspace that is not `engineering-patterns` (the conventional shared
+workspace). With no workspace given and none configured, it errors.
+
+## Setup (query)
+
+```bash
+# 1. Start AnythingLLM (example: local podman on :3001) and create/populate a
+#    workspace with your docs (via the AnythingLLM UI or its API).
+# 2. Point cairnkeep at it, in the project's .ai/.env:
+ANYTHINGLLM_BASE_URL=http://localhost:3001
+ANYTHINGLLM_API_KEY=<your AnythingLLM API key>
+# 3. List the workspace(s) in the project's memory config (see JSON above).
+```
+
+Then `domain_knowledge_query { "workspace": "my-project-docs", "query": "..." }`
+returns a grounded answer.
+
+## Setup (sync / embedding)
+
+`domain_knowledge_sync` shells out to a document-upload/embed script. Because the
+scripts that talk to your AnythingLLM (and any include/exclude rules) are
+deployment-specific, they live in **your** wrapper, not the core — point cairnkeep
+at yours:
+
+```bash
+CAIRN_ANYTHINGLLM_SYNC_SCRIPT=/abs/path/to/your/sync_to_anythingllm.py
+```
+
+The script receives the workspace slug and is expected to upload + embed the
+project's documents into that AnythingLLM workspace. See
+[building-an-overlay.md](building-an-overlay.md) for the wrapper pattern.
+
+A working, deployment-agnostic starting point lives in
+[`examples/anythingllm/`](../examples/anythingllm/): an incremental
+(sha256-tracked) multi-project sync script plus a config schema. Copy it, adapt
+`anythingllm-projects.json`, and point `CAIRN_ANYTHINGLLM_SYNC_SCRIPT` at your
+copy.
+
+## Not using RAG?
+
+Do nothing. The tools stay inert, cost nothing, and the rest of cairnkeep is
+fully functional without an AnythingLLM instance.

package/docs/git-providers.md

@@ -0,0 +1,36 @@
+# Git provider configuration
+
+Cairnkeep's collaboration commands — `memory-sync`, `repo-review` / `code-review`,
+and `security-audit` — talk to your git host through whatever git-provider MCP
+server you have registered. The host is selected per project by one setting, so
+the same commands work on GitHub, GitLab, Codeberg/Forgejo, and anything else
+that has an MCP server.
+
+## Configure
+
+Set the provider in the project's `.ai/.env`:
+
+```bash
+CAIRN_GIT_PROVIDER=github   # github | gitlab | codeberg | forgejo | none
+```
+
+`none` disables the provider steps — the commands run locally only (still write
+memory, still produce local review/audit reports).
+
+## Operations the commands use
+
+The commands need a small, stable set of operations. Map each to the tool your
+provider's MCP server exposes:
+
+| Operation | Purpose | GitHub (example) | GitLab (example) |
+|---|---|---|---|
+| list open changes | find tracked PRs/MRs | `list_pull_requests` | `list_merge_requests` |
+| get change diff | review a PR/MR diff | `get_pull_request_diff` | `get_merge_request_diffs` |
+| post inline comment | post review findings | `create_review_comment` | `create_merge_request_discussion` |
+| get change state | sync memory with PR/MR status | `get_pull_request` | `get_merge_request` |
+| create issue | file an accepted finding | `create_issue` | `create_issue` |
+
+Exact tool names depend on the specific MCP server you install; the table shows
+the common shape. Codeberg/Forgejo and other hosts follow the same operations
+with their own tool names. If no git-provider MCP is registered (or
+`CAIRN_GIT_PROVIDER=none`), the commands skip the provider steps and keep working.