@onlooker-community/ecosystem 0.16.0 → 0.17.0

package/plugins/governor/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/governor-v0.1.0...governor-v0.2.0) (2026-05-26)
+
+
+### Features
+
+* **governor:** resource governance and budget enforcement plugin :rocket: ([#43](https://github.com/onlooker-community/ecosystem/issues/43)) ([04e6d70](https://github.com/onlooker-community/ecosystem/commit/04e6d7051f27db752bb121d389d65b4d8ade04ad))
+
 ## [0.1.0] - 2026-05-25
 
 ### Added

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

@@ -0,0 +1,12 @@
+{
+  "name": "scribe",
+  "version": "0.2.0",
+  "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",
+    "email": "community@onlooker.dev"
+  },
+  "homepage": "https://onlooker.dev",
+  "license": "MIT",
+  "requires": ["ecosystem"]
+}

package/plugins/scribe/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/scribe-v0.1.0...scribe-v0.2.0) (2026-06-01)
+
+
+### Features
+
+* **scribe:** intent documentation from agent activity :pencil2: ([#50](https://github.com/onlooker-community/ecosystem/issues/50)) ([f0a95d1](https://github.com/onlooker-community/ecosystem/commit/f0a95d1058e36d1bb5f0f645964d9e88e8f98b66))

package/plugins/scribe/config.json

@@ -0,0 +1,20 @@
+{
+  "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"
+    }
+  }
+}

package/plugins/scribe/hooks/hooks.json

@@ -0,0 +1,37 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/scribe-session-start.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/scribe-capture.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/scribe-stop.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/scribe/scripts/hooks/scribe-capture.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Scribe UserPromptSubmit hook — initial intent capture.
+#
+# Fires on every user prompt. On the FIRST turn of a session (captured_prompt
+# is null in state), extracts and stores the prompt text as the problem
+# statement seed for later distillation.
+#
+# Subsequent turns are ignored — the full transcript is available at Stop
+# time, so there is no need to accumulate per-turn captures.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks a user prompt.
+#   - Errors are written to stderr only; stdout is kept clean.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/scribe-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/scribe-config.sh"
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+PROMPT=$(printf '%s' "$INPUT" | jq -r '.prompt // ""' 2>/dev/null) || PROMPT=""
+
+_done() { exit 0; }
+
+[[ -z "$SESSION_ID" || -z "$PROMPT" ]] && _done
+
+scribe_config_load "$CWD"
+
+if ! scribe_config_enabled; then
+	_done
+fi
+
+ONLOOKER_DIR="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+STATE_FILE="${ONLOOKER_DIR}/scribe/sessions/${SESSION_ID}.json"
+
+# Only capture if no prompt has been stored yet for this session.
+if [[ -f "$STATE_FILE" ]]; then
+	existing=$(jq -r '.captured_prompt // "null"' "$STATE_FILE" 2>/dev/null) || existing="null"
+	[[ "$existing" != "null" && -n "$existing" ]] && _done
+fi
+
+# Truncate prompt to configured max chars.
+max_chars=$(scribe_config_get '.scribe.capture.prompt_max_chars')
+[[ -z "$max_chars" || "$max_chars" == "null" ]] && max_chars="1000"
+
+truncated="${PROMPT:0:$max_chars}"
+timestamp=$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) || timestamp=""
+
+# Upsert state — preserve existing keys, update captured_prompt + captured_at.
+if [[ -f "$STATE_FILE" ]]; then
+	updated=$(jq \
+		--arg p "$truncated" \
+		--arg ts "$timestamp" \
+		'.captured_prompt = $p | .captured_at = $ts' \
+		"$STATE_FILE" 2>/dev/null) || updated=""
+	if [[ -n "$updated" ]]; then
+		printf '%s\n' "$updated" > "$STATE_FILE" || true
+	fi
+else
+	mkdir -p "$(dirname "$STATE_FILE")" 2>/dev/null || true
+	jq -n \
+		--arg sid "$SESSION_ID" \
+		--arg p "$truncated" \
+		--arg ts "$timestamp" \
+		'{session_id: $sid, captured_prompt: $p, captured_at: $ts}' \
+		2>/dev/null > "$STATE_FILE" || true
+fi
+
+_done

package/plugins/scribe/scripts/hooks/scribe-session-start.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Scribe SessionStart hook.
+#
+# Fires at every session start. Responsibilities:
+#   1. Skip silently when scribe.enabled is false.
+#   2. Create storage directories.
+#   3. Initialize session state file:
+#      - captured_prompt: null (populated by scribe-capture.sh on first turn)
+#      - captured_at: null
+#
+# Hook contract:
+#   - Always exits 0. Never blocks SessionStart.
+#   - Errors are written to stderr only; stdout is kept clean.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/scribe-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/scribe-config.sh"
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+
+_done() { exit 0; }
+
+scribe_config_load "$CWD"
+
+if ! scribe_config_enabled; then
+	_done
+fi
+
+export _HOOK_SESSION_ID="$SESSION_ID"
+
+ONLOOKER_DIR="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+SCRIBE_SESSION_DIR="${ONLOOKER_DIR}/scribe/sessions"
+mkdir -p "$SCRIBE_SESSION_DIR" 2>/dev/null || true
+
+[[ -z "$SESSION_ID" ]] && _done
+
+STATE_FILE="${SCRIBE_SESSION_DIR}/${SESSION_ID}.json"
+
+jq -n \
+	--arg sid "$SESSION_ID" \
+	'{
+		session_id: $sid,
+		captured_prompt: null,
+		captured_at: null
+	}' 2>/dev/null > "$STATE_FILE" || {
+	printf 'scribe-session-start: failed to write state file %s\n' "$STATE_FILE" >&2
+	_done
+}
+
+_done

package/plugins/scribe/scripts/hooks/scribe-stop.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# Scribe Stop hook — intent distillation.
+#
+# Fires when the agent session ends. Reads the full session transcript,
+# runs a Haiku extraction pass to identify the problem context, decisions,
+# tradeoffs, and constraints, then writes a Markdown intent document to
+# ~/.onlooker/scribe/<project_key>/<date>-<session>.md.
+#
+# Skip conditions (all silent):
+#   - scribe.enabled is false
+#   - no transcript_path in hook input, or file is unreadable
+#   - session has fewer turns than scribe.capture.min_turns
+#
+# Hook contract:
+#   - Always exits 0. Never blocks Stop.
+#   - Errors are written to stderr only; stdout is kept clean.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/scribe-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/scribe-config.sh"
+# shellcheck source=../lib/scribe-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/scribe-events.sh"
+# shellcheck source=../lib/scribe-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/scribe-project-key.sh"
+# shellcheck source=../lib/scribe-extract.sh
+source "${PLUGIN_ROOT}/scripts/lib/scribe-extract.sh"
+# shellcheck source=../lib/scribe-distill.sh
+source "${PLUGIN_ROOT}/scripts/lib/scribe-distill.sh"
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null) || TRANSCRIPT_PATH=""
+
+export _HOOK_SESSION_ID="$SESSION_ID"
+
+_done() { exit 0; }
+
+[[ -z "$SESSION_ID" ]] && _done
+
+scribe_config_load "$CWD"
+
+if ! scribe_config_enabled; then
+	_done
+fi
+
+if [[ -z "$TRANSCRIPT_PATH" || ! -f "$TRANSCRIPT_PATH" ]]; then
+	_done
+fi
+
+_distill_rc=0
+output_path=$(scribe_distill "$SESSION_ID" "$CWD" "$TRANSCRIPT_PATH") || _distill_rc=$?
+if [[ $_distill_rc -ne 0 ]]; then
+	# rc=2 means below min_turns — silent skip, not an error.
+	[[ $_distill_rc -ne 2 ]] && printf 'scribe-stop: distillation failed for session %s\n' "$SESSION_ID" >&2
+	_done
+fi
+
+[[ -n "$output_path" ]] && printf 'scribe: intent document written → %s\n' "$output_path" >&2
+
+_done

package/plugins/scribe/scripts/lib/scribe-config.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Config resolution for Scribe.
+#
+# Reads three layers, latest wins:
+#   1. plugins/scribe/config.json (defaults shipped with the plugin)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   scribe_config_load <repo_root>     # populates _SCRIBE_CONFIG (JSON)
+#   scribe_config_get <jq-path>        # echoes string value (empty if unset)
+#   scribe_config_get_json <jq-path>   # echoes JSON value (null if unset)
+#   scribe_config_enabled              # 0 if scribe.enabled is true
+
+_SCRIBE_CONFIG="{}"
+
+scribe_config_load() {
+	local repo_root="${1:-}"
+	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
+	local home_dir="${HOME:-}"
+
+	local merged="{}"
+	local file
+
+	file="${plugin_root}/config.json"
+	if [[ -f "$file" ]]; then
+		local defaults
+		defaults=$(jq '.' "$file" 2>/dev/null) || defaults="{}"
+		merged=$(jq -n --argjson a "$merged" --argjson b "$defaults" '$a * $b' 2>/dev/null) \
+			|| merged="$defaults"
+	fi
+
+	local repo_settings=""
+	[[ -n "$repo_root" ]] && repo_settings="${repo_root}/.claude/settings.json"
+
+	for file in "${home_dir}/.claude/settings.json" "$repo_settings"; do
+		[[ -n "$file" && -f "$file" ]] || continue
+		local overlay
+		overlay=$(jq '{ scribe: (.scribe // {}) }' "$file" 2>/dev/null) || continue
+		[[ -z "$overlay" ]] && continue
+		local attempt
+		if attempt=$(jq -n --argjson a "$merged" --argjson b "$overlay" '
+			def deepmerge($a; $b):
+				if ($a|type) == "object" and ($b|type) == "object" then
+					reduce (($a|keys) + ($b|keys) | unique)[] as $k
+						({}; .[$k] = deepmerge($a[$k]; $b[$k]))
+				elif $b == null then $a
+				else $b end;
+			deepmerge($a; $b)
+		' 2>/dev/null) && [[ -n "$attempt" ]]; then
+			merged="$attempt"
+		fi
+	done
+
+	_SCRIBE_CONFIG="$merged"
+}
+
+scribe_config_get() {
+	local path="$1"
+	printf '%s' "$_SCRIBE_CONFIG" | jq -r "${path} // empty" 2>/dev/null
+}
+
+scribe_config_get_json() {
+	local path="$1"
+	printf '%s' "$_SCRIBE_CONFIG" | jq -c "${path}" 2>/dev/null
+}
+
+scribe_config_enabled() {
+	local v
+	v=$(scribe_config_get '.scribe.enabled')
+	[[ "$v" == "true" ]]
+}

package/plugins/scribe/scripts/lib/scribe-distill.sh

@@ -0,0 +1,239 @@
+#!/usr/bin/env bash
+# Distillation pipeline for Scribe.
+#
+# Orchestrates the full Stop-time flow:
+#   1. Load session state (captured initial prompt)
+#   2. Count transcript turns — skip if below min_turns
+#   3. Call scribe_extract_intent (Haiku pass)
+#   4. Format output as a readable Markdown document
+#   5. Write to ~/.onlooker/scribe/<project_key>/
+#   6. Optionally mirror to <repo_root>/<project_dir>/
+#   7. Emit scribe.distill.complete
+#
+# Exposes:
+#   scribe_distill <session_id> <cwd> <transcript_path>
+
+# shellcheck source=./scribe-extract.sh
+# (caller must source scribe-extract.sh before scribe-distill.sh)
+
+_scribe_format_document() {
+	local intent_json="${1:-}"
+	local session_id="${2:-unknown}"
+	local project_root="${3:-}"
+	local captured_prompt="${4:-}"
+	local date_str
+	date_str=$(date '+%Y-%m-%d' 2>/dev/null) || date_str="unknown"
+	local timestamp
+	timestamp=$(date '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) || timestamp="unknown"
+
+	local summary problem decisions_json tradeoffs_json constraints_json out_of_scope_json
+	summary=$(printf '%s' "$intent_json" | jq -r '.summary // ""' 2>/dev/null) || summary=""
+	problem=$(printf '%s' "$intent_json" | jq -r '.problem // ""' 2>/dev/null) || problem=""
+	decisions_json=$(printf '%s' "$intent_json" | jq -c '.decisions // []' 2>/dev/null) || decisions_json="[]"
+	tradeoffs_json=$(printf '%s' "$intent_json" | jq -c '.tradeoffs // []' 2>/dev/null) || tradeoffs_json="[]"
+	constraints_json=$(printf '%s' "$intent_json" | jq -c '.constraints // []' 2>/dev/null) || constraints_json="[]"
+	out_of_scope_json=$(printf '%s' "$intent_json" | jq -c '.out_of_scope // []' 2>/dev/null) || out_of_scope_json="[]"
+
+	local session_short="${session_id:0:8}"
+
+	{
+		printf '# Session Intent: %s\n\n' "$date_str"
+		[[ -n "$summary" ]] && printf '> %s\n\n' "$summary"
+
+		printf '## Problem\n\n'
+		if [[ -n "$problem" ]]; then
+			printf '%s\n\n' "$problem"
+		else
+			printf '*No problem statement extracted.*\n\n'
+		fi
+
+		printf '## Decisions\n\n'
+		local decision_count
+		decision_count=$(printf '%s' "$decisions_json" | jq 'length' 2>/dev/null) || decision_count=0
+		if [[ "$decision_count" -gt 0 ]]; then
+			local i
+			for ((i = 0; i < decision_count; i++)); do
+				local d r alts
+				d=$(printf '%s' "$decisions_json" | jq -r ".[$i].decision // \"\"" 2>/dev/null) || d=""
+				r=$(printf '%s' "$decisions_json" | jq -r ".[$i].reason // \"\"" 2>/dev/null) || r=""
+				alts=$(printf '%s' "$decisions_json" | jq -r ".[$i].alternatives // [] | .[]" 2>/dev/null) || alts=""
+				[[ -z "$d" ]] && continue
+				printf '- **%s** — %s\n' "$d" "$r"
+				if [[ -n "$alts" ]]; then
+					printf '  - *Considered:* '
+					local first=1
+					while IFS= read -r alt; do
+						[[ -z "$alt" ]] && continue
+						[[ "$first" -eq 0 ]] && printf ', '
+						printf '%s' "$alt"
+						first=0
+					done <<< "$alts"
+					printf '\n'
+				fi
+			done
+			printf '\n'
+		else
+			printf '*None noted.*\n\n'
+		fi
+
+		printf '## Tradeoffs\n\n'
+		local tradeoff_count
+		tradeoff_count=$(printf '%s' "$tradeoffs_json" | jq 'length' 2>/dev/null) || tradeoff_count=0
+		if [[ "$tradeoff_count" -gt 0 ]]; then
+			printf '%s' "$tradeoffs_json" | jq -r '.[]' 2>/dev/null | while IFS= read -r item; do
+				[[ -n "$item" ]] && printf '- %s\n' "$item"
+			done
+			printf '\n'
+		else
+			printf '*None noted.*\n\n'
+		fi
+
+		printf '## Constraints\n\n'
+		local constraint_count
+		constraint_count=$(printf '%s' "$constraints_json" | jq 'length' 2>/dev/null) || constraint_count=0
+		if [[ "$constraint_count" -gt 0 ]]; then
+			printf '%s' "$constraints_json" | jq -r '.[]' 2>/dev/null | while IFS= read -r item; do
+				[[ -n "$item" ]] && printf '- %s\n' "$item"
+			done
+			printf '\n'
+		else
+			printf '*None noted.*\n\n'
+		fi
+
+		printf '## Out of Scope\n\n'
+		local oos_count
+		oos_count=$(printf '%s' "$out_of_scope_json" | jq 'length' 2>/dev/null) || oos_count=0
+		if [[ "$oos_count" -gt 0 ]]; then
+			printf '%s' "$out_of_scope_json" | jq -r '.[]' 2>/dev/null | while IFS= read -r item; do
+				[[ -n "$item" ]] && printf '- %s\n' "$item"
+			done
+			printf '\n'
+		else
+			printf '*None noted.*\n\n'
+		fi
+
+		if [[ -n "$captured_prompt" ]]; then
+			printf '## Initial Prompt\n\n'
+			printf '```\n%s\n```\n\n' "$captured_prompt"
+		fi
+
+		printf '---\n'
+		printf '*Generated by scribe · session `%s` · %s*\n' "$session_short" "$timestamp"
+		[[ -n "$project_root" ]] && printf '*Project: `%s`*\n' "$project_root"
+	}
+}
+
+scribe_distill() {
+	local session_id="${1:-}"
+	local cwd="${2:-}"
+	local transcript_path="${3:-}"
+
+	[[ -z "$session_id" ]] && return 1
+
+	local onlooker_dir="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+	local state_file="${onlooker_dir}/scribe/sessions/${session_id}.json"
+
+	# Load captured prompt from session state (best-effort).
+	local captured_prompt=""
+	if [[ -f "$state_file" ]]; then
+		captured_prompt=$(jq -r '.captured_prompt // ""' "$state_file" 2>/dev/null) || captured_prompt=""
+	fi
+
+	# Transcript is required for extraction.
+	if [[ -z "$transcript_path" || ! -f "$transcript_path" ]]; then
+		printf 'scribe_distill: no transcript available for session %s\n' "$session_id" >&2
+		return 1
+	fi
+
+	# Count turns; skip trivial sessions.
+	local min_turns
+	min_turns=$(scribe_config_get '.scribe.capture.min_turns') || min_turns="3"
+	[[ -z "$min_turns" || "$min_turns" == "null" ]] && min_turns="3"
+
+	local turn_count
+	turn_count=$(scribe_count_turns "$transcript_path")
+
+	if [[ "$turn_count" -lt "$min_turns" ]]; then
+		return 2
+	fi
+
+	# Resolve config.
+	local model timeout_s max_tokens temperature transcript_chars_max
+	model=$(scribe_config_get '.scribe.evaluator.model')
+	[[ -z "$model" || "$model" == "null" ]] && model="claude-haiku-4-5-20251001"
+	timeout_s=$(scribe_config_get '.scribe.evaluator.timeout')
+	[[ -z "$timeout_s" || "$timeout_s" == "null" ]] && timeout_s="60"
+	max_tokens=$(scribe_config_get '.scribe.evaluator.max_tokens')
+	[[ -z "$max_tokens" || "$max_tokens" == "null" ]] && max_tokens="2048"
+	temperature=$(scribe_config_get '.scribe.evaluator.temperature')
+	[[ -z "$temperature" || "$temperature" == "null" ]] && temperature="0.3"
+	transcript_chars_max=$(scribe_config_get '.scribe.capture.transcript_chars_max')
+	[[ -z "$transcript_chars_max" || "$transcript_chars_max" == "null" ]] && transcript_chars_max="40000"
+
+	# Run extraction.
+	local intent_json
+	intent_json=$(scribe_extract_intent \
+		"$transcript_path" "$model" "$timeout_s" "$max_tokens" "$temperature" "$transcript_chars_max") || {
+		printf 'scribe_distill: extraction failed for session %s\n' "$session_id" >&2
+		return 1
+	}
+
+	# Resolve project key and output paths.
+	local project_key project_root output_dir
+	project_key=$(scribe_project_key "$cwd")
+	project_root=$(scribe_project_repo_root "$cwd")
+
+	if [[ -n "$project_key" ]]; then
+		output_dir=$(scribe_project_dir "$project_key")
+	else
+		output_dir="${onlooker_dir}/scribe/unknown"
+	fi
+
+	mkdir -p "$output_dir" 2>/dev/null || {
+		printf 'scribe_distill: cannot create output dir %s\n' "$output_dir" >&2
+		return 1
+	}
+
+	local date_str
+	date_str=$(date '+%Y-%m-%d' 2>/dev/null) || date_str="unknown"
+	local session_short="${session_id:0:8}"
+	local filename="${date_str}-${session_short}.md"
+	local output_path="${output_dir}/${filename}"
+
+	# Format and write the document.
+	local doc
+	doc=$(_scribe_format_document \
+		"$intent_json" "$session_id" "$project_root" "$captured_prompt")
+
+	printf '%s\n' "$doc" > "$output_path" 2>/dev/null || {
+		printf 'scribe_distill: failed to write %s\n' "$output_path" >&2
+		return 1
+	}
+
+	# Mirror to project tree if configured.
+	local mirror artifacts=1
+	mirror=$(scribe_config_get '.scribe.output.mirror_to_project')
+	if [[ "$mirror" == "true" && -n "$project_root" ]]; then
+		local project_dir
+		project_dir=$(scribe_config_get '.scribe.output.project_dir')
+		[[ -z "$project_dir" || "$project_dir" == "null" ]] && project_dir="docs/decisions"
+		local mirror_dir="${project_root}/${project_dir}"
+		if mkdir -p "$mirror_dir" 2>/dev/null; then
+			if cp "$output_path" "${mirror_dir}/${filename}" 2>/dev/null; then
+				artifacts=2
+			fi
+		fi
+	fi
+
+	# Emit scribe.distill.complete.
+	local payload
+	payload=$(jq -n \
+		--arg sid "$session_id" \
+		--argjson cap 1 \
+		--argjson art "$artifacts" \
+		'{session_id: $sid, captures_processed: $cap, artifacts_produced: $art}') || payload=""
+
+	[[ -n "$payload" ]] && scribe_emit_event "scribe.distill.complete" "$payload" || true
+
+	printf '%s' "$output_path"
+}