@onlooker-community/ecosystem 0.23.0 → 0.24.0

package/plugins/librarian/scripts/lib/librarian-cli.sh

@@ -0,0 +1,339 @@
+#!/usr/bin/env bash
+# Interactive control surface for the /librarian review skill.
+#
+# Exposes:
+#   librarian_cli list                         # one-line summary + table of pending proposals
+#   librarian_cli show <proposal_id>           # full proposal body + provenance + conflict state
+#   librarian_cli accept <proposal_id>         # write to typed memory store, mark accepted
+#   librarian_cli reject <proposal_id> [reason]  # tombstone + mark rejected
+#   librarian_cli defer  <proposal_id>         # mark as deferred=true while keeping status pending
+#   librarian_cli status                       # one-line counts (pending / accepted / rejected)
+#
+# Memory store writes go to:
+#   ${HOME}/.claude/projects/${CLAUDE_PROJECT_ENCODED}/memory/<filename>
+#
+# When CLAUDE_PROJECT_ENCODED is unset, the CLI derives the encoded form
+# from the current working directory (replace `/` with `-`). The MEMORY.md
+# index is updated in-place — the accepted memory is appended as a new
+# bullet line, and the file is created if it doesn't exist.
+#
+# Depends on (sourced by the caller): librarian-config.sh,
+# librarian-project-key.sh, librarian-storage.sh, librarian-emit.sh
+
+# ----------------------------------------------------------------------------
+# Project key + memory store path resolution
+# ----------------------------------------------------------------------------
+
+_librarian_cli_project_key() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" ]] && cwd="$(pwd)"
+	librarian_project_key "$cwd"
+}
+
+_librarian_cli_memory_dir() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" ]] && cwd="$(pwd)"
+
+	local encoded="${CLAUDE_PROJECT_ENCODED:-}"
+	if [[ -z "$encoded" ]]; then
+		local abs
+		abs=$(cd "$cwd" 2>/dev/null && pwd -P) || abs=""
+		[[ -n "$abs" ]] && encoded=$(printf '%s' "$abs" | sed -E 's#/#-#g')
+	fi
+	[[ -z "$encoded" ]] && return 0
+
+	printf '%s/.claude/projects/%s/memory' "${HOME:-}" "$encoded"
+}
+
+# ----------------------------------------------------------------------------
+# Helpers for the typed memory store
+# ----------------------------------------------------------------------------
+
+# Write a single memory file with provenance frontmatter and update
+# MEMORY.md to reference it. Returns 0 on success.
+#
+# Usage: _librarian_cli_write_memory <memory_dir> <proposal_json>
+_librarian_cli_write_memory() {
+	local mem_dir="$1"
+	local proposal="$2"
+	[[ -z "$mem_dir" || -z "$proposal" ]] && return 1
+	mkdir -p "$mem_dir" 2>/dev/null || return 1
+
+	local id type title body filename confidence src_session_ids src_artifact_ids now
+	id=$(printf '%s' "$proposal" | jq -r '.id // ""')
+	type=$(printf '%s' "$proposal" | jq -r '.proposed.type // ""')
+	title=$(printf '%s' "$proposal" | jq -r '.proposed.title // ""')
+	body=$(printf '%s' "$proposal" | jq -r '.proposed.body // ""')
+	filename=$(printf '%s' "$proposal" | jq -r '.proposed.filename // ""')
+	confidence=$(printf '%s' "$proposal" | jq -r '.proposed.classifier_confidence // 0')
+	src_session_ids=$(printf '%s' "$proposal" | jq -c '.source_session_ids // []')
+	src_artifact_ids=$(printf '%s' "$proposal" | jq -c '.source_artifact_ids // []')
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+	[[ -z "$type" || -z "$title" || -z "$body" || -z "$filename" ]] && return 1
+
+	# Strip any `/` or `..` from the filename — proposals come from a
+	# trusted source, but the safety check costs nothing.
+	case "$filename" in
+		*/*|*..*|.*) return 1 ;;
+	esac
+	[[ "$filename" == *.md ]] || return 1
+
+	local out_path="${mem_dir}/${filename}"
+
+	# Build the provenance YAML frontmatter. Single-line description and
+	# title come from the classifier; the source* arrays carry traceability.
+	{
+		printf -- '---\n'
+		printf 'name: %s\n' "$title"
+		printf 'description: librarian-promoted from proposal %s\n' "$id"
+		printf 'type: %s\n' "$type"
+		printf 'source: librarian\n'
+		printf 'classifier_confidence: %s\n' "$confidence"
+		printf 'promoted_at: %s\n' "$now"
+		printf 'source_session_ids: %s\n' "$src_session_ids"
+		printf 'source_artifact_ids: %s\n' "$src_artifact_ids"
+		printf -- '---\n\n'
+		printf '%s\n' "$body"
+	} > "$out_path" || return 1
+
+	# Update MEMORY.md: append a one-line entry referencing the new file.
+	local index_path="${mem_dir}/MEMORY.md"
+	if [[ ! -f "$index_path" ]]; then
+		printf '# Memory index\n\n' > "$index_path" || return 1
+	fi
+	# Avoid duplicate entries on repeated accepts of the same id (shouldn't
+	# happen but is cheap to guard against).
+	if ! grep -F -q "(${filename})" "$index_path"; then
+		printf -- '- [%s](%s) — %s\n' "$title" "$filename" "$type" >> "$index_path"
+	fi
+
+	printf '%s' "$out_path"
+}
+
+# Update a proposal's status field (pending → accepted | rejected | deferred).
+# Returns 0 on success.
+_librarian_cli_set_proposal_status() {
+	local key="$1"
+	local proposal_id="$2"
+	local new_status="$3"
+	local extra_json="${4:-{\}}"
+	[[ -z "$key" || -z "$proposal_id" || -z "$new_status" ]] && return 1
+
+	local path
+	path="$(librarian_proposals_dir "$key")/${proposal_id}.json"
+	[[ -f "$path" ]] || return 1
+
+	local now updated
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+	updated=$(jq --arg status "$new_status" --arg t "$now" --argjson extra "$extra_json" \
+		'. * { status: $status, updated_at: $t } * $extra' "$path" 2>/dev/null) || return 1
+	[[ -z "$updated" || "$updated" == "null" ]] && return 1
+	printf '%s\n' "$updated" > "$path"
+}
+
+# ----------------------------------------------------------------------------
+# Public surface
+# ----------------------------------------------------------------------------
+
+librarian_cli_list() {
+	local cwd="${1:-}"
+	local key
+	key=$(_librarian_cli_project_key "$cwd")
+	[[ -z "$key" ]] && { printf 'No project key resolvable from this directory.\n'; return 0; }
+
+	local pending
+	pending=$(librarian_storage_load_proposals "$key" \
+		| jq '[.[] | select((.status // "pending") == "pending")]')
+	local count
+	count=$(printf '%s' "$pending" | jq 'length' 2>/dev/null) || count=0
+
+	if [[ "$count" -eq 0 ]]; then
+		printf 'No pending proposals.\n'
+		return 0
+	fi
+
+	printf '%s pending proposal%s:\n\n' "$count" "$([ "$count" -eq 1 ] && echo "" || echo "s")"
+	# Print header + rows together so `column -t` (BSD-portable) aligns both.
+	# We can't use util-linux's `column -N` here — macOS ships BSD column,
+	# which only supports `-t` and `-s`.
+	{
+		printf 'ID\tTYPE\tCONFIDENCE\tCONFLICT\tTITLE\n'
+		printf '%s' "$pending" | jq -r '
+			.[] | [
+				(.id // ""),
+				(.proposed.type // "?"),
+				((.proposed.classifier_confidence // 0) | tostring),
+				(.conflict_state // "none"),
+				(.proposed.title // "")
+			] | @tsv
+		'
+	} | column -t -s $'\t'
+}
+
+librarian_cli_show() {
+	local proposal_id="${1:-}"
+	local cwd="${2:-}"
+	[[ -z "$proposal_id" ]] && { printf 'usage: librarian_cli show <proposal_id>\n'; return 1; }
+
+	local key
+	key=$(_librarian_cli_project_key "$cwd")
+	[[ -z "$key" ]] && { printf 'No project key resolvable from this directory.\n'; return 1; }
+
+	local path
+	path="$(librarian_proposals_dir "$key")/${proposal_id}.json"
+	if [[ ! -f "$path" ]]; then
+		printf 'Proposal %s not found.\n' "$proposal_id"
+		return 1
+	fi
+
+	jq -r '
+		"--- proposal " + .id + " (" + (.status // "pending") + ") ---",
+		"created_at:           " + (.created_at // ""),
+		"type:                 " + (.proposed.type // ""),
+		"title:                " + (.proposed.title // ""),
+		"filename:             " + (.proposed.filename // ""),
+		"classifier_confidence: " + ((.proposed.classifier_confidence // 0) | tostring),
+		"conflict_state:       " + (.conflict_state // "none"),
+		"source_session_ids:   " + ((.source_session_ids // []) | join(", ")),
+		"source_artifact_ids:  " + ((.source_artifact_ids // []) | join(", ")),
+		"",
+		"body:",
+		(.proposed.body // "")
+	' "$path"
+}
+
+librarian_cli_accept() {
+	local proposal_id="${1:-}"
+	local cwd="${2:-}"
+	[[ -z "$proposal_id" ]] && { printf 'usage: librarian_cli accept <proposal_id>\n'; return 1; }
+
+	local key session_id
+	key=$(_librarian_cli_project_key "$cwd")
+	[[ -z "$key" ]] && { printf 'No project key resolvable from this directory.\n'; return 1; }
+	session_id="${CLAUDE_SESSION_ID:-cli}"
+
+	local path proposal
+	path="$(librarian_proposals_dir "$key")/${proposal_id}.json"
+	[[ -f "$path" ]] || { printf 'Proposal %s not found.\n' "$proposal_id"; return 1; }
+	proposal=$(jq '.' "$path") || { printf 'Could not parse proposal.\n'; return 1; }
+
+	local mem_dir
+	mem_dir=$(_librarian_cli_memory_dir "$cwd")
+	[[ -z "$mem_dir" ]] && { printf 'Could not resolve typed memory store path. Set CLAUDE_PROJECT_ENCODED or run from inside the project.\n'; return 1; }
+
+	local out_path
+	out_path=$(_librarian_cli_write_memory "$mem_dir" "$proposal") || {
+		printf 'Failed to write memory file.\n'
+		return 1
+	}
+
+	local filename
+	filename=$(printf '%s' "$proposal" | jq -r '.proposed.filename')
+	_librarian_cli_set_proposal_status "$key" "$proposal_id" "accepted" \
+		"$(jq -cn --arg final_filename "$filename" '{accepted_via: "manual", final_filename: $final_filename}')" \
+		|| { printf 'Wrote memory file at %s but failed to update proposal status.\n' "$out_path"; return 1; }
+
+	librarian_emit "librarian.proposal.accepted" "$session_id" "$(jq -cn \
+		--arg proposal_id "$proposal_id" \
+		--arg final_filename "$filename" \
+		--arg accepted_via "manual" \
+		'{proposal_id: $proposal_id, final_filename: $final_filename, accepted_via: $accepted_via}')"
+
+	printf 'Accepted. Wrote %s\n' "$out_path"
+}
+
+librarian_cli_reject() {
+	local proposal_id="${1:-}"
+	local reason="${2:-}"
+	local cwd="${3:-}"
+	[[ -z "$proposal_id" ]] && { printf 'usage: librarian_cli reject <proposal_id> [reason]\n'; return 1; }
+
+	local key session_id
+	key=$(_librarian_cli_project_key "$cwd")
+	[[ -z "$key" ]] && { printf 'No project key resolvable from this directory.\n'; return 1; }
+	session_id="${CLAUDE_SESSION_ID:-cli}"
+
+	local path proposal body original_filename body_hash
+	path="$(librarian_proposals_dir "$key")/${proposal_id}.json"
+	[[ -f "$path" ]] || { printf 'Proposal %s not found.\n' "$proposal_id"; return 1; }
+	proposal=$(jq '.' "$path") || { printf 'Could not parse proposal.\n'; return 1; }
+	body=$(printf '%s' "$proposal" | jq -r '.proposed.body // ""')
+	original_filename=$(printf '%s' "$proposal" | jq -r '.proposed.filename // ""')
+
+	# Tombstone keyed on body hash so the same content does not re-propose.
+	body_hash=$(librarian_body_hash "$body")
+	if [[ -n "$body_hash" ]]; then
+		if librarian_storage_write_tombstone "$key" "$body_hash" "$original_filename"; then
+			librarian_emit "librarian.tombstone.created" "$session_id" "$(jq -cn \
+				--arg body_hash "$body_hash" \
+				--arg original_filename "$original_filename" \
+				'{body_hash: $body_hash, original_filename: (if $original_filename == "" then null else $original_filename end)}
+				 | with_entries(select(.value != null))')"
+		else
+			printf 'Failed to write tombstone for proposal %s.\n' "$proposal_id"
+			return 1
+		fi
+	fi
+
+	_librarian_cli_set_proposal_status "$key" "$proposal_id" "rejected" \
+		"$(jq -cn --arg reason "$reason" '{reason: (if $reason == "" then null else $reason end)}')" \
+		|| return 1
+
+	librarian_emit "librarian.proposal.rejected" "$session_id" "$(jq -cn \
+		--arg proposal_id "$proposal_id" \
+		--arg reason "$reason" \
+		'{proposal_id: $proposal_id, reason: (if $reason == "" then null else $reason end)}
+		 | with_entries(select(.value != null))')"
+
+	printf 'Rejected proposal %s%s\n' "$proposal_id" "$([ -n "$reason" ] && echo " (reason: $reason)" || echo "")"
+}
+
+librarian_cli_defer() {
+	local proposal_id="${1:-}"
+	local cwd="${2:-}"
+	[[ -z "$proposal_id" ]] && { printf 'usage: librarian_cli defer <proposal_id>\n'; return 1; }
+
+	local key
+	key=$(_librarian_cli_project_key "$cwd")
+	[[ -z "$key" ]] && { printf 'No project key resolvable from this directory.\n'; return 1; }
+
+	local path
+	path="$(librarian_proposals_dir "$key")/${proposal_id}.json"
+	[[ -f "$path" ]] || { printf 'Proposal %s not found.\n' "$proposal_id"; return 1; }
+
+	# Deferred proposals remain pending — we just stamp the proposal with
+	# an updated_at so a reviewer can tell it was visited.
+	_librarian_cli_set_proposal_status "$key" "$proposal_id" "pending" \
+		'{"deferred": true}' || return 1
+	printf 'Deferred proposal %s — still in the queue for next session.\n' "$proposal_id"
+}
+
+librarian_cli_status() {
+	local cwd="${1:-}"
+	local key
+	key=$(_librarian_cli_project_key "$cwd")
+	[[ -z "$key" ]] && { printf 'No project key resolvable from this directory.\n'; return 0; }
+
+	local all
+	all=$(librarian_storage_load_proposals "$key")
+	local pending accepted rejected
+	pending=$(printf '%s' "$all" | jq '[.[] | select((.status // "pending") == "pending")] | length')
+	accepted=$(printf '%s' "$all" | jq '[.[] | select(.status == "accepted")] | length')
+	rejected=$(printf '%s' "$all" | jq '[.[] | select(.status == "rejected")] | length')
+	printf 'pending: %s, accepted: %s, rejected: %s\n' "$pending" "$accepted" "$rejected"
+}
+
+librarian_cli() {
+	local action="${1:-list}"
+	shift || true
+	case "$action" in
+		list) librarian_cli_list "$@" ;;
+		show) librarian_cli_show "$@" ;;
+		accept) librarian_cli_accept "$@" ;;
+		reject) librarian_cli_reject "$@" ;;
+		defer) librarian_cli_defer "$@" ;;
+		status) librarian_cli_status "$@" ;;
+		*) printf 'unknown action: %s\n' "$action"; return 2 ;;
+	esac
+}

package/plugins/librarian/skills/librarian/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: librarian
+description: Review the librarian's pending memory promotion proposals queued from past sessions. Walk pending entries with the user one at a time, surfacing provenance and conflict state, and route each to accept (writes the typed memory file and updates MEMORY.md), reject (writes a body-hash tombstone so the same content won't re-propose), or defer (leave in the queue). Use when the user types `/librarian`, `/librarian review`, `/librarian triage`, `/librarian status`, or `/librarian list`, or asks to review librarian proposals.
+---
+
+# Librarian: Promotion Queue Review
+
+You are operating the **Librarian** review surface — the user-facing control for promoting per-session artifacts (decisions, dead-ends, open questions captured by Archivist) into the user's durable typed memory store.
+
+Auto-promotion is intentionally off. Librarian queues proposals; the user (with your help) confirms each one. Every accept writes a real file into `~/.claude/projects/<encoded>/memory/`, so every accept matters.
+
+## Parse the request
+
+Read the user's argument after `/librarian`:
+
+- no argument, or `review`, `triage`, `walk` → **walk the queue** (default)
+- `list` → print the pending table and stop
+- `status` → print one-line counts and stop
+- a proposal id (starts with a ULID-shaped string) → jump straight to **show** for that id
+
+If the user passes a free-form intent ("clear out the queue", "what's pending?"), map it to `review` or `list` as appropriate.
+
+## Run the control surface
+
+Source the plugin helpers and invoke `librarian_cli`. Run this in a single bash call when you need state:
+
+```bash
+set -uo pipefail
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/librarian-config.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/librarian-project-key.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/librarian-storage.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/librarian-emit.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/librarian-cli.sh"
+
+# action is one of: list | show <id> | accept <id> | reject <id> [reason] | defer <id> | status
+librarian_cli "<action>" "<args...>"
+```
+
+`librarian_cli` resolves the project key from the current working directory automatically and routes writes to the typed memory store under `${HOME}/.claude/projects/${CLAUDE_PROJECT_ENCODED}/memory/` (deriving the encoded path from `cwd` when the env var is unset).
+
+## The review walkthrough
+
+For `review` (the default), loop:
+
+1. Call `librarian_cli list`. If the output says `No pending proposals.`, tell the user the queue is clear and stop.
+2. Take the first pending id from the table. Call `librarian_cli show <id>` to render the proposal's provenance, classifier confidence, conflict state, and full body.
+3. Present the proposal to the user in plain English. Lead with the title and the proposed memory **type** (user / feedback / project / reference) — those determine where it lands in the user's memory store. If the **conflict_state** is anything other than `none` (typically `near_duplicate` or `contradicts_existing`), call this out explicitly and recommend a careful read before accepting.
+4. Ask the user how to route it: **accept**, **reject** (optionally with a reason), **defer** (revisit next session), or **skip** (move on without recording a decision).
+5. Route the answer:
+   - **accept** → `librarian_cli accept <id>`. Confirm the resulting path Librarian printed and move to the next proposal.
+   - **reject** → `librarian_cli reject <id> "<reason>"`. The reason is optional but valuable — it's recorded on the proposal and the tombstone is keyed on body hash so the same content won't be re-proposed.
+   - **defer** → `librarian_cli defer <id>`. The proposal stays pending; mention it'll resurface next session.
+   - **skip** → don't call the CLI for this id, move to the next proposal.
+6. After each routed decision, fetch the next pending id (the previous one will have flipped status, so `list` reorders naturally) and repeat. When `list` returns no rows, finish with `librarian_cli status` so the user sees the final counts.
+
+For `list` and `status`, just call `librarian_cli <action>` once and render the output.
+
+## Safety rules
+
+- **Never accept a proposal on the user's behalf without explicit confirmation.** Accepting writes a file to the user's typed memory store and that memory will be loaded into every future session in this project. Treat each accept like editing a CLAUDE.md.
+- **Do not edit MEMORY.md directly.** `accept` updates the index for you; hand-editing risks duplicate entries or stale links.
+- **Do not delete proposal files manually.** Reject (with a tombstone) is the cleanup path. Direct deletion would let the same body re-propose on the next scan.
+- **Conflict-state proposals deserve a careful read.** When `conflict_state` is `near_duplicate` or `contradicts_existing`, surface the conflict to the user before they decide. Often the right answer is reject (the existing memory is better) or accept-and-then-prune (you can mention that follow-up).

package/plugins/scribe/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "scribe",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Intent documentation from agent activity. Captures why changes were made — problem context, decisions, tradeoffs — and distills them into readable artifacts at session end.",
   "author": {
     "name": "Onlooker Community",

package/plugins/scribe/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.2.1](https://github.com/onlooker-community/ecosystem/compare/scribe-v0.2.0...scribe-v0.2.1) (2026-06-04)
+
+
+### Bug Fixes
+
+* **scribe:** mark hook scripts executable :relieved: ([#64](https://github.com/onlooker-community/ecosystem/issues/64)) ([05603e5](https://github.com/onlooker-community/ecosystem/commit/05603e56895c009c1435d1712592adbbc4c15e61))
+
 ## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/scribe-v0.1.0...scribe-v0.2.0) (2026-06-01)
 
 

package/plugins/scribe/README.md

@@ -0,0 +1,118 @@
+# Scribe
+
+Intent documentation from agent activity.
+
+Scribe captures *why* changes were made — the problem context, the decisions and their reasons, the tradeoffs accepted, and the constraints that shaped the work — and distills them into a readable Markdown artifact at session end. Git logs and code comments record *what* changed; Scribe records the intent behind it.
+
+Scribe is a sibling plugin to [`ecosystem`](../../) and assumes the Onlooker observability substrate (`~/.onlooker/`) is present.
+
+## How it works
+
+| Hook | What Scribe does |
+|------|------------------|
+| `SessionStart` | Creates storage directories and initializes a per-session state file with `captured_prompt` and `captured_at` set to null. |
+| `UserPromptSubmit` | On the first turn of a session (when `captured_prompt` is still null), stores the prompt text — truncated to `capture.prompt_max_chars` — as the problem-statement seed. Subsequent turns are ignored, since the full transcript is available at Stop time. |
+| `Stop` | Reads the full session transcript, runs a single Haiku extraction pass via `claude -p` to identify the problem, decisions, tradeoffs, constraints, and out-of-scope items, formats the result as a Markdown intent document, and writes it under `~/.onlooker/scribe/<project-key>/`. Emits `scribe.distill.complete`. |
+
+The Stop hook silently skips when the session has fewer than `capture.min_turns` user turns, when `scribe.enabled` is false, or when no readable `transcript_path` is present in the hook input. Every hook always exits 0 — Scribe never blocks a session.
+
+## Activation
+
+Scribe is **on by default**. Disable it per-project in `.claude/settings.json`:
+
+```json
+{
+  "scribe": {
+    "enabled": false
+  }
+}
+```
+
+Or globally in `~/.claude/settings.json`.
+
+## Configuration
+
+All keys are optional. Unset keys fall back to the plugin's `config.json` defaults.
+
+```json
+{
+  "scribe": {
+    "enabled": true,
+    "evaluator": {
+      "model": "claude-haiku-4-5-20251001",
+      "timeout": 60,
+      "max_tokens": 2048,
+      "temperature": 0.3
+    },
+    "capture": {
+      "min_turns": 3,
+      "prompt_max_chars": 1000,
+      "transcript_chars_max": 40000
+    },
+    "output": {
+      "mirror_to_project": false,
+      "project_dir": "docs/decisions"
+    }
+  }
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `enabled` | `true` | Must be `true` for any capture or distillation to run. |
+| `evaluator.model` | `claude-haiku-4-5-20251001` | Model used for the intent-extraction pass. Haiku is fast and cheap; the extraction prompt is structured and does not require deep reasoning. |
+| `evaluator.timeout` | `60` | Wall-clock timeout in seconds passed to the `timeout` command around the `claude -p` call. |
+| `evaluator.max_tokens` | `2048` | Token ceiling for the extraction response. |
+| `evaluator.temperature` | `0.3` | Sampling temperature for the extraction pass. |
+| `capture.min_turns` | `3` | Minimum number of user turns in the transcript before a session is distilled. Shorter sessions are skipped silently. |
+| `capture.prompt_max_chars` | `1000` | Maximum number of characters of the first prompt stored as the problem-statement seed. |
+| `capture.transcript_chars_max` | `40000` | Maximum number of characters of the rendered transcript fed into extraction. Larger values capture more context at higher cost. |
+| `output.mirror_to_project` | `false` | When `true`, also copies the generated document into the repo tree under `output.project_dir`. |
+| `output.project_dir` | `docs/decisions` | Directory (relative to the repo root) the intent document is mirrored into when `output.mirror_to_project` is `true`. |
+
+## Storage layout
+
+```text
+~/.onlooker/scribe/
+├── sessions/
+│   └── <session-id>.json              # per-session state: captured_prompt, captured_at
+└── <project-key>/
+    └── <date>-<session-short>.md       # intent document, e.g. 2026-06-04-01j8x9ab.md
+```
+
+When the project key cannot be resolved, the document is written under `~/.onlooker/scribe/unknown/` instead. With `output.mirror_to_project` enabled, the same Markdown file is also copied to `<repo-root>/<project_dir>/<date>-<session-short>.md`.
+
+Project key: first 12 hex chars of SHA256 of `git remote get-url origin` (prefixed `remote:`), falling back to a SHA256 of the repo root realpath (prefixed `root:`). The scheme mirrors `tribunal` and is worktree-aware — a worktree shares its parent repo's key.
+
+The intent document is a Markdown file with the following sections:
+
+```markdown
+# Session Intent: <date>
+
+> <executive summary>
+
+## Problem
+## Decisions
+## Tradeoffs
+## Constraints
+## Out of Scope
+## Initial Prompt    # only when a prompt was captured
+```
+
+Each decision is rendered as a headline, its reason, and any considered-but-rejected alternatives. A footer records the short session ID, the generation timestamp, and the project root.
+
+## Events emitted
+
+Scribe emits the canonical `scribe.*` event surface from [`@onlooker-community/schema`](https://github.com/onlooker-community/schema). All events land in `~/.onlooker/logs/onlooker-events.jsonl` and are validated against the schema before write.
+
+| Event | When |
+|-------|------|
+| `scribe.distill.complete` | After an intent document is written at session end. Includes `session_id`, `captures_processed`, and `artifacts_produced` (`2` when mirrored to the project tree, otherwise `1`). |
+
+## Requirements
+
+- The `ecosystem` plugin installed (for the `~/.onlooker/` substrate and canonical event emission). Scribe declares `"requires": ["ecosystem"]`.
+- `claude` CLI on `PATH` (the Stop hook shells out to `claude -p` for the extraction pass).
+- `jq` for JSON manipulation.
+- `node` for canonical-event emission.
+- `shasum` or `sha256sum` for project-key derivation (standard on macOS and most Linux distributions).