@procrastivity/clast 0.0.3 → 0.0.4

package/examples/cron/crontab.sample

@@ -1,16 +1,16 @@
 # clast cron sample for unattended transcript capture.
 # Install with: crontab -l | { cat; cat examples/cron/crontab.sample; } | crontab -
-# Edit the clast path if you installed somewhere other than /usr/local/bin.
+# Edit the clast-plumbing path if you installed somewhere other than /usr/local/bin.
 
 # Every hour at :05, capture any new transcripts.
 # Idempotent and silent on no-op, so safe to run frequently.
-5 * * * * /usr/local/bin/clast snapshot >/dev/null 2>&1
+5 * * * * /usr/local/bin/clast-plumbing snapshot >/dev/null 2>&1
 
 # Alternative: every 15 minutes for active users moving between many sessions.
-# */15 * * * * /usr/local/bin/clast snapshot >/dev/null 2>&1
+# */15 * * * * /usr/local/bin/clast-plumbing snapshot >/dev/null 2>&1
 
 # Alternative: once daily for hands-off archival.
-# 10 4 * * * /usr/local/bin/clast snapshot >/dev/null 2>&1
+# 10 4 * * * /usr/local/bin/clast-plumbing snapshot >/dev/null 2>&1
 
 # Alternative: no cron. Rely on the SessionStart hook installed with the plugin.
 # The hook covers most use cases already; cron is only useful when you want capture without ever opening Claude.

package/examples/workflows/morning-briefing.md

@@ -6,8 +6,8 @@ and `infra-tools` checked a flaky shell lint issue.
 
 ```bash
 # User: /day-wakeup
-clast snapshot
-clast --json sessions --day yesterday
+clast-plumbing snapshot
+clast-plumbing --json sessions --day yesterday
 ```
 
 It filters to `curated: false`, groups by project, and shows:
@@ -23,8 +23,8 @@ xesapps      09:12  feature/field-normalize  58 messages
 The skill reads session details and breadcrumbs:
 
 ```bash
-clast --json show 33333333-3333-4333-8333-333333333333 --full --turns 8
-clast breadcrumb --read --project infra-tools --day yesterday
+clast-plumbing --json show 33333333-3333-4333-8333-333333333333 --full --turns 8
+clast-plumbing breadcrumb --read --project infra-tools --day yesterday
 ```
 
 It drafts a short entry:
@@ -50,8 +50,8 @@ uncurated and can be revisited in a later `/day-wakeup`.
 The skill reads the next transcript:
 
 ```bash
-clast --json show 22222222-2222-4222-8222-222222222222 --full --turns 8
-clast breadcrumb --read --project notes --day yesterday
+clast-plumbing --json show 22222222-2222-4222-8222-222222222222 --full --turns 8
+clast-plumbing breadcrumb --read --project notes --day yesterday
 ```
 
 The user asks for a revision:
@@ -76,7 +76,7 @@ Tighten the note-entry template before using it for project briefings.
 The skill writes through stdin:
 
 ```bash
-clast entries write \
+clast-plumbing entries write \
   --session 22222222-2222-4222-8222-222222222222 \
   --slug entry-template-cleanup \
   --tags notes,template \
@@ -89,8 +89,8 @@ clast entries write \
 The skill reads the session and breadcrumbs:
 
 ```bash
-clast --json show 11111111-1111-4111-8111-111111111111 --full --turns 8
-clast breadcrumb --read --project xesapps --day yesterday
+clast-plumbing --json show 11111111-1111-4111-8111-111111111111 --full --turns 8
+clast-plumbing breadcrumb --read --project xesapps --day yesterday
 ```
 
 The user chooses `Accept + promote decision` for this draft:
@@ -112,7 +112,7 @@ items are folded into the entry body rather than written to separate decision,
 common-issue, or workflow files.
 
 ```bash
-clast entries write \
+clast-plumbing entries write \
   --session 11111111-1111-4111-8111-111111111111 \
   --slug field-normalization-fix \
   --tags xesapps,fields,regression \
@@ -133,5 +133,5 @@ Run `/wakeup <project>` to start working on a specific project today.
 
 What this changes on disk:
 `entries/2026-05-31-1340-notes-entry-template-cleanup.md` and `entries/2026-05-31-0912-xesapps-field-normalization-fix.md` were written.
-`.manifest.jsonl` was already current from `clast snapshot`; curation does not append to it.
+`.manifest.jsonl` was already current from `clast-plumbing snapshot`; curation does not append to it.
 The skipped `infra-tools` session stays uncurated and remains eligible for a later `/day-wakeup`.

package/hooks/snapshot.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# hooks/snapshot.sh — SessionStart hook. Backgrounds `clast snapshot`.
+# hooks/snapshot.sh — SessionStart hook. Backgrounds `clast-plumbing snapshot`.
 # Idempotent. Best-effort: never propagates a non-zero exit.
 # shellcheck shell=bash
 
@@ -11,10 +11,10 @@ _plugin_root="$(cd "$_snap_dir/.." && pwd)"
 # Prefer the bundled binary (version-matched to this plugin).
 # Fall back to a system-level install on PATH.
 _clast=""
-if [[ -x "$_plugin_root/bin/clast" ]]; then
-  _clast="$_plugin_root/bin/clast"
-elif command -v clast >/dev/null 2>&1; then
-  _clast="clast"
+if [[ -x "$_plugin_root/bin/clast-plumbing" ]]; then
+  _clast="$_plugin_root/bin/clast-plumbing"
+elif command -v clast-plumbing >/dev/null 2>&1; then
+  _clast="clast-plumbing"
 fi
 
 if [[ -n "$_clast" ]]; then

package/lib/clast/clast-dismissed-lib.bash

@@ -51,12 +51,13 @@ clast_dismissed_set() {
     return 0
   fi
 
-  local line sid
-  while IFS= read -r line; do
-    [[ -z "$line" ]] && continue
-    sid="$(jq -r '.session_id // empty' <<<"$line" 2>/dev/null)" || continue
+  # Single jq pass over the whole file. Previously this forked one jq per
+  # line, which dominated when the dismissed log grew large. `fromjson?`
+  # silently drops malformed lines, matching the old per-line tolerance.
+  local sid
+  while IFS= read -r sid; do
     [[ -n "$sid" ]] && _ref["$sid"]=1
-  done < "$dismissed_file"
+  done < <(jq -rR 'fromjson? | .session_id // empty' "$dismissed_file" 2>/dev/null)
 }
 
 # clast_dismissed_check <session-id> — exit 0 if dismissed, 1 if not.

package/lib/clast/clast-lib.bash

@@ -204,10 +204,10 @@ clast_version() {
 # to stderr for usage errors.
 clast_usage() {
   cat <<'EOF'
-clast — Claude Code session journal
+clast-plumbing — Claude Code session journal (deterministic core)
 
 Usage:
-  clast [GLOBAL FLAGS] <subcommand> [ARGS...]
+  clast-plumbing [GLOBAL FLAGS] <subcommand> [ARGS...]
 
 Subcommands:
   whereami      Show current path, registry, and journal state
@@ -229,5 +229,8 @@ Global flags:
   -q, --quiet           Suppress informational stdout output
       --journal-dir P   Override ~/.claude/journal/ (env: CLAST_JOURNAL_DIR)
       --projects-dir P  Override ~/.claude/projects/ (env: CLAST_PROJECTS_DIR)
+
+The user-facing porcelain (LLM-aware) is `clast`. Run `clast --help` for
+the `wake` and `brief` subcommands.
 EOF
 }

package/lib/clast/clast-manifest-lib.bash

@@ -26,13 +26,18 @@ _clast_manifest_now_iso() {
   date -u -d "@$epoch" +%Y-%m-%dT%H:%M:%SZ
 }
 
-# clast_manifest_append <session-id> <source> <snapshot> <source-mtime> <source-size> <day-bucket>
+# clast_manifest_append <session-id> <source> <snapshot> <source-mtime> <source-size> <day-bucket> <msg-count> <first-ts> <last-ts>
 clast_manifest_append() {
-  if [[ $# -ne 6 ]]; then
-    clast_log_error "clast_manifest_append: expected 6 args, got $#"
+  if [[ $# -ne 9 ]]; then
+    clast_log_error "clast_manifest_append: expected 9 args, got $#"
     return 2
   fi
   local session_id="$1" source="$2" snapshot="$3" source_mtime="$4" source_size="$5" day_bucket="$6"
+  # Cached per-session metadata (step 21): msg_count is an integer line
+  # count; first_ts/last_ts are the transcript's first/last line timestamps
+  # ("" → stored as JSON null). Readers prefer these over re-reading the
+  # snapshot file, falling back to the file when a line predates the cache.
+  local msg_count="$7" first_ts="$8" last_ts="$9"
   local field
   for field in session_id source snapshot source_mtime source_size day_bucket; do
     if [[ -z "${!field}" ]]; then
@@ -44,6 +49,10 @@ clast_manifest_append() {
     clast_log_error "clast_manifest_append: source_size must be a non-negative integer, got '$source_size'"
     return 2
   fi
+  if ! [[ "$msg_count" =~ ^[0-9]+$ ]]; then
+    clast_log_error "clast_manifest_append: msg_count must be a non-negative integer, got '$msg_count'"
+    return 2
+  fi
 
   local journal_dir
   journal_dir="$(clast_journal_dir)"
@@ -62,7 +71,10 @@ clast_manifest_append() {
     --arg source_mtime "$source_mtime" \
     --argjson source_size "$source_size" \
     --arg day_bucket "$day_bucket" \
-    '{session_id: $session_id, source: $source, snapshot: $snapshot, captured_at: $captured_at, source_mtime: $source_mtime, source_size: $source_size, day_bucket: $day_bucket}')" || {
+    --argjson msg_count "$msg_count" \
+    --arg first_ts "$first_ts" \
+    --arg last_ts "$last_ts" \
+    '{session_id: $session_id, source: $source, snapshot: $snapshot, captured_at: $captured_at, source_mtime: $source_mtime, source_size: $source_size, day_bucket: $day_bucket, msg_count: $msg_count, first_ts: (if $first_ts == "" then null else $first_ts end), last_ts: (if $last_ts == "" then null else $last_ts end)}')" || {
     clast_log_error "clast_manifest_append: jq failed to build manifest line"
     return 1
   }
@@ -168,6 +180,7 @@ clast_manifest_rebuild_from_disk() {
   local count=0
   if [[ -d "$transcripts_root" ]]; then
     local snapshot day session_id mtime_epoch mtime_iso line
+    local msg_count first_ts last_ts
     # source / source_size are unrecoverable: the snapshot file's size is
     # the captured copy's size, not the original source's size at capture
     # time, and the source path is not encoded in the snapshot itself.
@@ -185,13 +198,23 @@ clast_manifest_rebuild_from_disk() {
         rm -f "$tmp_file"
         return 1
       fi
+      # source / source_size are unrecoverable, but the cached metadata
+      # (step 21) IS recoverable from the snapshot copy — compute it so
+      # doctor --fix backfills rather than emitting legacy-shaped lines.
+      first_ts="$(head -n1 "$snapshot" 2>/dev/null | jq -r '.timestamp // empty' 2>/dev/null || true)"
+      last_ts="$(tail -n1 "$snapshot" 2>/dev/null | jq -r '.timestamp // empty' 2>/dev/null || true)"
+      msg_count="$(wc -l <"$snapshot" 2>/dev/null | tr -d ' ')"
+      [[ "$msg_count" =~ ^[0-9]+$ ]] || msg_count=0
       line="$(jq -c -n \
         --arg session_id "$session_id" \
         --arg snapshot "${snapshot#"$journal_dir/"}" \
         --arg captured_at "$mtime_iso" \
         --arg source_mtime "$mtime_iso" \
         --arg day_bucket "$day" \
-        '{session_id: $session_id, source: null, snapshot: $snapshot, captured_at: $captured_at, source_mtime: $source_mtime, source_size: 0, day_bucket: $day_bucket}')" || {
+        --argjson msg_count "$msg_count" \
+        --arg first_ts "$first_ts" \
+        --arg last_ts "$last_ts" \
+        '{session_id: $session_id, source: null, snapshot: $snapshot, captured_at: $captured_at, source_mtime: $source_mtime, source_size: 0, day_bucket: $day_bucket, msg_count: $msg_count, first_ts: (if $first_ts == "" then null else $first_ts end), last_ts: (if $last_ts == "" then null else $last_ts end)}')" || {
         clast_log_error "clast_manifest_rebuild_from_disk: jq failed for '$snapshot'"
         rm -f "$tmp_file"
         return 1

package/lib/clast/clast-porcelain-lib.bash

@@ -0,0 +1,217 @@
+# clast-porcelain-lib.bash — shared helpers for the `clast` porcelain.
+#
+# The porcelain is the LLM-aware, user-facing layer that sits on top of
+# `clast-plumbing`. This file holds helpers reused by every porcelain
+# subcommand: error/info plumbing, an OpenAI-compatible chat call, and the
+# prompt-template loader. Pure bash + jq + curl.
+#
+# Subcommand files live in $CLAST_LIB/clast-porcelain-subcommands/<name>.bash
+# and each defines a single function `clast_cmd_<name>`.
+# shellcheck shell=bash
+
+# --- Helpers -----------------------------------------------------------------
+
+clast_porcelain_die() {
+  printf 'clast: %s\n' "$1" >&2
+  exit "${2:-1}"
+}
+
+clast_porcelain_warn() { printf 'clast: warning: %s\n' "$1" >&2; }
+clast_porcelain_info() { printf '%s\n' "$1"; }
+
+clast_porcelain_log_error() { printf 'clast: error: %s\n' "$1" >&2; }
+
+# --- Version / usage ---------------------------------------------------------
+
+# Reuses the plumbing's clast_version helper if available (loaded by sourcing
+# clast-lib.bash). When the porcelain is invoked stand-alone we still want a
+# version string, so fall back to reading package.json directly.
+clast_porcelain_version() {
+  if declare -F clast_version >/dev/null 2>&1; then
+    clast_version
+    return
+  fi
+  local pkg_root pkg
+  pkg_root="${CLAST_LIB:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+  if [[ -f "$pkg_root/package.json" ]]; then
+    pkg="$pkg_root/package.json"
+  elif [[ -f "$pkg_root/../../package.json" ]]; then
+    pkg="$pkg_root/../../package.json"
+  else
+    clast_porcelain_log_error "clast_porcelain_version: package.json not found"
+    return 1
+  fi
+  jq -r '.version' "$pkg"
+}
+
+clast_porcelain_usage() {
+  cat <<'EOF'
+clast — Claude Code session porcelain (LLM-aware)
+
+Usage:
+  clast [GLOBAL FLAGS] <subcommand> [ARGS...]
+
+Subcommands:
+  wake          Interactive day curation (standalone equivalent of /day-wakeup)
+  brief         Project briefing (standalone equivalent of /wakeup)
+
+Global flags:
+  -h, --help    Print this usage and exit
+      --version Print version and exit
+
+Env (required by `wake` and `brief`):
+  CLAST_LLM_BASE_URL  e.g. https://api.openai.com/v1
+  CLAST_LLM_API_KEY   bearer token
+  CLAST_LLM_MODEL     e.g. gpt-4o, llama3
+
+The deterministic core (whereami / snapshot / sessions / entries / …)
+lives in `clast-plumbing`. Run `clast-plumbing --help` for that surface.
+EOF
+}
+
+# --- Preflight ---------------------------------------------------------------
+
+# clast_porcelain_preflight_llm — verify curl, jq, and the LLM env vars exist.
+# Subcommands that don't call the LLM (none right now) can skip this.
+clast_porcelain_preflight_llm() {
+  for tool in clast-plumbing curl jq; do
+    if ! command -v "$tool" >/dev/null 2>&1; then
+      clast_porcelain_die "required tool not found: $tool"
+    fi
+  done
+
+  local missing=0
+  if [[ -z "${CLAST_LLM_BASE_URL:-}" ]]; then
+    clast_porcelain_warn "CLAST_LLM_BASE_URL not set"; missing=1
+  fi
+  if [[ -z "${CLAST_LLM_API_KEY:-}" ]]; then
+    clast_porcelain_warn "CLAST_LLM_API_KEY not set"; missing=1
+  fi
+  if [[ -z "${CLAST_LLM_MODEL:-}" ]]; then
+    clast_porcelain_warn "CLAST_LLM_MODEL not set"; missing=1
+  fi
+
+  if (( missing )); then
+    cat >&2 <<'EOF'
+
+Set these env vars before running clast wake / clast brief:
+
+  export CLAST_LLM_BASE_URL="https://api.openai.com/v1"
+  export CLAST_LLM_API_KEY="sk-..."
+  export CLAST_LLM_MODEL="gpt-4o"
+
+Or for a local model (ollama, vllm, etc.):
+
+  export CLAST_LLM_BASE_URL="http://localhost:11434/v1"
+  export CLAST_LLM_API_KEY="unused"
+  export CLAST_LLM_MODEL="llama3"
+EOF
+    exit 1
+  fi
+}
+
+# --- LLM call ----------------------------------------------------------------
+
+# clast_porcelain_llm_chat <system-msg> <user-msg>
+#   POST a chat-completions request to $CLAST_LLM_BASE_URL/chat/completions
+#   and echo the assistant's text on stdout. Returns nonzero on HTTP error or
+#   empty response.
+clast_porcelain_llm_chat() {
+  local system_msg="$1"
+  local user_msg="$2"
+
+  local payload
+  payload="$(jq -cn \
+    --arg model "$CLAST_LLM_MODEL" \
+    --arg system "$system_msg" \
+    --arg user "$user_msg" \
+    '{
+      model: $model,
+      messages: [
+        {role: "system", content: $system},
+        {role: "user", content: $user}
+      ],
+      temperature: 0.3
+    }')"
+
+  local response http_code body
+  response="$(curl -s -w '\n%{http_code}' \
+    "${CLAST_LLM_BASE_URL}/chat/completions" \
+    -H "Authorization: Bearer $CLAST_LLM_API_KEY" \
+    -H "Content-Type: application/json" \
+    -d "$payload" 2>&1)" || true
+
+  http_code="$(tail -n1 <<<"$response")"
+  body="$(sed '$d' <<<"$response")"
+
+  if [[ "$http_code" != "200" ]]; then
+    clast_porcelain_warn "LLM API returned HTTP $http_code"
+    if [[ -n "$body" ]]; then
+      local err_msg
+      err_msg="$(jq -r '.error.message // .error // .' <<<"$body" 2>/dev/null || echo "$body")"
+      clast_porcelain_warn "$err_msg"
+    fi
+    return 1
+  fi
+
+  local content
+  content="$(jq -r '.choices[0].message.content // empty' <<<"$body" 2>/dev/null)" || {
+    clast_porcelain_warn "failed to parse LLM response"
+    return 1
+  }
+
+  if [[ -z "$content" ]]; then
+    clast_porcelain_warn "LLM returned empty content"
+    return 1
+  fi
+
+  printf '%s' "$content"
+}
+
+# --- Prompt templates --------------------------------------------------------
+
+# clast_porcelain_resolve_prompt_dir — echo the prompts dir, search order:
+#   1. $CLAST_LIB/prompts  (in-repo or installed alongside the lib)
+#   2. /usr/local/lib/clast/prompts
+#   3. $HOME/.local/lib/clast/prompts
+clast_porcelain_resolve_prompt_dir() {
+  if [[ -n "${CLAST_LIB:-}" && -d "$CLAST_LIB/prompts" ]]; then
+    printf '%s' "$CLAST_LIB/prompts"
+    return
+  fi
+  local installed
+  for installed in /usr/local/lib/clast/prompts "$HOME/.local/lib/clast/prompts"; do
+    if [[ -d "$installed" ]]; then
+      printf '%s' "$installed"
+      return
+    fi
+  done
+  clast_porcelain_die "cannot find prompts directory (checked \$CLAST_LIB/prompts and install paths)"
+}
+
+# clast_porcelain_load_system_prompt <basename>
+#   Read the named system prompt (without extension) from the resolved
+#   prompts dir, e.g. clast_porcelain_load_system_prompt brief-system.
+clast_porcelain_load_system_prompt() {
+  local name="$1"
+  local prompt_dir file
+  prompt_dir="$(clast_porcelain_resolve_prompt_dir)"
+  file="$prompt_dir/${name}.md"
+  if [[ ! -r "$file" ]]; then
+    clast_porcelain_die "system prompt not found: $file"
+  fi
+  cat "$file"
+}
+
+# clast_porcelain_user_prompt_file <basename>
+#   Echo the absolute path to the named user-prompt template, or empty string
+#   if missing. Callers do their own placeholder substitution.
+clast_porcelain_user_prompt_file() {
+  local name="$1"
+  local prompt_dir file
+  prompt_dir="$(clast_porcelain_resolve_prompt_dir)"
+  file="$prompt_dir/${name}.md"
+  if [[ -r "$file" ]]; then
+    printf '%s' "$file"
+  fi
+}

package/lib/clast/clast-porcelain-subcommands/brief.bash

@@ -0,0 +1,167 @@
+# clast brief — LLM-powered project briefing.
+#
+# Replicates the /wakeup plugin skill using an OpenAI-compatible chat
+# completions endpoint. Reads curated entries, breadcrumbs, and today's
+# sessions for a project (via clast-plumbing), then synthesizes a briefing.
+#
+# Usage: clast brief [<project-slug>]
+#   If no slug is given, resolves from the current working directory.
+# shellcheck shell=bash
+
+# --- Resolve project ---------------------------------------------------------
+
+_clast_brief_resolve_project() {
+  local slug="${1:-}"
+
+  if [[ -n "$slug" ]]; then
+    printf '%s' "$slug"
+    return
+  fi
+
+  local resolved
+  resolved="$(clast-plumbing registry resolve "$(pwd)" 2>/dev/null)" || true
+  if [[ -n "$resolved" ]]; then
+    printf '%s' "$resolved"
+    return
+  fi
+
+  clast_porcelain_die "Not in a registered project. Run \`clast-plumbing registry add .\` first, or invoke as \`clast brief <slug>\`."
+}
+
+# --- Gather data -------------------------------------------------------------
+
+_clast_brief_gather_entries() {
+  local project="$1"
+  local entries_json
+  entries_json="$(clast-plumbing --json entries --project "$project" --limit 5 2>/dev/null)" || true
+
+  if [[ -z "$entries_json" ]] || [[ "$(jq 'length' <<<"$entries_json" 2>/dev/null)" == "0" ]]; then
+    return
+  fi
+
+  local n i entry_meta entry_path entry_body result=""
+  n="$(jq 'length' <<<"$entries_json")"
+
+  for (( i = 0; i < n; i++ )); do
+    entry_meta="$(jq -c ".[$i]" <<<"$entries_json")"
+    entry_path="$(jq -r '.path' <<<"$entry_meta")"
+
+    entry_body="$(clast-plumbing entries read "$entry_path" 2>/dev/null)" || true
+    if [[ -z "$entry_body" ]]; then
+      local title date
+      title="$(jq -r '.title // "untitled"' <<<"$entry_meta")"
+      date="$(jq -r '.date' <<<"$entry_meta")"
+      entry_body="# $date — $title (body not available)"
+    fi
+
+    if [[ -n "$result" ]]; then
+      result="${result}
+
+---
+
+"
+    fi
+    result="${result}${entry_body}"
+  done
+
+  printf '%s' "$result"
+}
+
+_clast_brief_gather_breadcrumbs() {
+  local project="$1"
+  clast-plumbing breadcrumb --read --project "$project" --day today 2>/dev/null || true
+}
+
+_clast_brief_gather_sessions() {
+  local project="$1"
+  local sessions_json
+  sessions_json="$(clast-plumbing --json sessions --day today --project "$project" 2>/dev/null)" || true
+
+  if [[ -z "$sessions_json" ]] || [[ "$(jq 'length' <<<"$sessions_json" 2>/dev/null)" == "0" ]]; then
+    return
+  fi
+
+  local n
+  n="$(jq 'length' <<<"$sessions_json")"
+
+  if (( n > 5 )); then
+    local latest_start
+    latest_start="$(jq -r 'sort_by(.start) | last | .start // ""' <<<"$sessions_json")"
+    printf 'Worked %d sessions today, most recent at %s.' "$n" "${latest_start:11:5}"
+    return
+  fi
+
+  jq -r '
+    sort_by(.start) | .[] |
+    "\(.start[11:16]) start: \(if .branch and .branch != "null" then .branch else "no branch" end), \(.msg_count_approx) messages"
+  ' <<<"$sessions_json" 2>/dev/null || true
+}
+
+# --- User prompt -------------------------------------------------------------
+
+_clast_brief_build_user_prompt() {
+  local project="$1" entries="$2" breadcrumbs="$3" sessions="$4"
+
+  local template_file template
+  template_file="$(clast_porcelain_user_prompt_file brief-user)"
+
+  if [[ -n "$template_file" ]]; then
+    template="$(cat "$template_file")"
+    template="${template//\{\{project\}\}/${project}}"
+    template="${template//\{\{entries\}\}/${entries:-None.}}"
+    template="${template//\{\{breadcrumbs\}\}/${breadcrumbs:-None.}}"
+    template="${template//\{\{sessions\}\}/${sessions:-None.}}"
+    printf '%s' "$template"
+  else
+    clast_porcelain_warn "user prompt template not found: brief-user.md — using inline fallback"
+    cat <<EOF
+Project: ${project}
+
+Recent curated entries (newest first):
+${entries:-None.}
+
+Today's breadcrumbs for this project:
+${breadcrumbs:-None.}
+
+Today's session activity for this project:
+${sessions:-None.}
+EOF
+  fi
+}
+
+# --- Main --------------------------------------------------------------------
+
+clast_cmd_brief() {
+  clast_porcelain_preflight_llm
+
+  local project
+  project="$(_clast_brief_resolve_project "${1:-}")"
+  clast_porcelain_info "Briefing for project: $project"
+
+  clast_porcelain_info "Gathering context..."
+
+  local entries breadcrumbs sessions
+  entries="$(_clast_brief_gather_entries "$project")"
+  breadcrumbs="$(_clast_brief_gather_breadcrumbs "$project")"
+  sessions="$(_clast_brief_gather_sessions "$project")"
+
+  if [[ -z "$entries" && -z "$breadcrumbs" && -z "$sessions" ]]; then
+    clast_porcelain_info "No curated entries, breadcrumbs, or sessions for \`$project\`."
+    clast_porcelain_info "Run \`clast wake\` to curate recent sessions first, or run \`clast-plumbing sessions --project $project\` to see what's available."
+    return 0
+  fi
+
+  local system_prompt user_prompt
+  system_prompt="$(clast_porcelain_load_system_prompt brief-system)"
+  user_prompt="$(_clast_brief_build_user_prompt "$project" "$entries" "$breadcrumbs" "$sessions")"
+
+  clast_porcelain_info "Synthesizing briefing..."
+  printf '\n'
+
+  local briefing
+  if ! briefing="$(clast_porcelain_llm_chat "$system_prompt" "$user_prompt")"; then
+    clast_porcelain_die "LLM call failed"
+  fi
+
+  printf '%s\n' "$briefing"
+}