@procrastivity/clast 0.0.3 → 0.0.5

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-classify-lib.bash

@@ -0,0 +1,68 @@
+# clast-classify-lib.bash — deterministic session classification
+#
+# A "no-op" session is one Claude Code captured but that holds no real work:
+# the user opened a session and only ran slash commands (`/clear`, `/model`,
+# `/config`, …) then quit, or typed a prompt and quit before Claude replied.
+# These are worthless to curate, so `wake` auto-dismisses them without ever
+# calling the LLM (see docs/reference/plugin.md + the wake flows).
+#
+# The classification is two counts computed from the transcript JSONL:
+#   user_msg_count      real user prompts — user-role messages that are not
+#                       meta, are non-empty, and are NOT slash-command wrappers.
+#   assistant_msg_count assistant-role messages (presence only; a tool-only
+#                       reply with no text still counts as real work).
+#
+# A session is *substantive* iff assistant_msg_count > 0 — i.e. Claude actually
+# replied. That single test captures both no-op shapes: empty / slash-command-
+# only sessions (/clear, /model, /config) and sessions where the user typed but
+# quit before any response — both have assistant_msg_count == 0. It is
+# deliberately NOT gated on user_msg_count: a custom slash command (e.g.
+# /review) leaves zero prose prompts yet drives real assistant work, and must
+# be kept. user_msg_count is still cached for diagnostics (show, sessions).
+#
+# Counts are computed once at snapshot time and cached on the manifest line
+# (clast-manifest-lib.bash), mirroring msg_count/first_ts/last_ts, so readers
+# never re-open the transcript.
+# shellcheck shell=bash
+
+if [[ -n "${_CLAST_CLASSIFY_LIB_SOURCED:-}" ]]; then
+  return 0
+fi
+_CLAST_CLASSIFY_LIB_SOURCED=1
+
+# Slash-command / local-command marker set. A user-role message whose text
+# contains any of these is Claude Code bookkeeping (e.g. `/clear`, `/model`),
+# not a real prompt. Centralized here so the classifier and show.bash's
+# first_prompt/last_prompt extraction share one definition.
+CLAST_COMMAND_MARKER_RE='<command-name>|<command-message>|<command-args>|<local-command-stdout>|<local-command-stderr>|<local-command-caveat>'
+export CLAST_COMMAND_MARKER_RE
+
+# clast_session_msg_counts <transcript-path>
+#   Print "<user_msg_count>\t<assistant_msg_count>" (tab-separated) for the
+#   given JSONL transcript. Missing/unreadable file prints "0\t0".
+#
+#   Streaming (`reduce inputs`), not slurp: a multi-megabyte transcript is
+#   read one line at a time, O(1) memory. `fromjson?` silently drops malformed
+#   lines, matching the tolerance in clast_manifest_iterate.
+clast_session_msg_counts() {
+  local path="$1"
+  if [[ -z "$path" || ! -r "$path" ]]; then
+    printf '0\t0\n'
+    return 0
+  fi
+  jq -n -R -r --arg cmd_re "$CLAST_COMMAND_MARKER_RE" '
+    def role: (.message.role // .role // .type);
+    def text_str:
+      (.message.content // .content // "")
+      | if type == "array" then (map(.text? // "") | join(" ")) else (. | tostring) end;
+    reduce (inputs | fromjson?) as $l ({u: 0, a: 0};
+      if ($l.isMeta // false) == true then .
+      elif ($l | role) == "user" then
+        ( ($l | text_str) as $t
+          | if ($t | gsub("\\s"; "")) != "" and ($t | test($cmd_re) | not)
+            then .u += 1 else . end )
+      elif ($l | role) == "assistant" then .a += 1
+      else . end
+    ) | "\(.u)\t\(.a)"
+  ' "$path" 2>/dev/null || printf '0\t0\n'
+}

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.
@@ -71,3 +72,73 @@ clast_dismissed_check() {
 
   grep -q "\"session_id\":\"$session_id\"" "$dismissed_file" 2>/dev/null
 }
+
+# clast_dismissed_remove <session-id> — drop all records for a session,
+# reversing a dismissal. Prints the number of records removed to stdout.
+# Returns 0 if anything was removed, 1 if the session was not dismissed.
+clast_dismissed_remove() {
+  local session_id="$1"
+  if [[ -z "$session_id" ]]; then
+    clast_log_error "clast_dismissed_remove: empty session_id"
+    return 2
+  fi
+
+  local dismissed_file
+  dismissed_file="$(clast_dismissed_path)"
+
+  if [[ ! -f "$dismissed_file" ]]; then
+    printf '0\n'
+    return 1
+  fi
+
+  # Count matches, then rewrite the log without them. A match is a
+  # well-formed JSON *object* whose session_id equals the target;
+  # `try fromjson catch null` turns unparseable lines into null so they
+  # never match, and the `type == "object"` guard keeps non-object JSON
+  # (numbers, strings) from erroring on `.session_id`. This mirrors the
+  # tolerant read in clast_dismissed_set.
+  local removed
+  removed="$(jq -rRn --arg sid "$session_id" '
+    [ inputs
+      | (try fromjson catch null) as $obj
+      | select(($obj | type) == "object" and $obj.session_id == $sid)
+    ] | length
+  ' "$dismissed_file" 2>/dev/null)" || removed=0
+  [[ -z "$removed" ]] && removed=0
+
+  if (( removed == 0 )); then
+    printf '0\n'
+    return 1
+  fi
+
+  local tmp
+  tmp="$(mktemp "${dismissed_file}.XXXXXX")" || {
+    clast_log_error "clast_dismissed_remove: failed to create temp file"
+    return 2
+  }
+  # Emit every line except well-formed objects matching the target id.
+  # Malformed lines parse to null (type != "object") and so are preserved
+  # verbatim rather than silently dropped. Rewrite goes through a temp file
+  # + mv so a crash mid-write can't truncate the log.
+  if jq -Rr --arg sid "$session_id" '
+    . as $line
+    | (try ($line | fromjson) catch null) as $obj
+    | if ($obj | type) == "object" and $obj.session_id == $sid
+      then empty
+      else $line
+      end
+  ' "$dismissed_file" >"$tmp" 2>/dev/null; then
+    if ! mv "$tmp" "$dismissed_file"; then
+      rm -f "$tmp"
+      clast_log_error "clast_dismissed_remove: failed to replace log"
+      return 2
+    fi
+  else
+    rm -f "$tmp"
+    clast_log_error "clast_dismissed_remove: rewrite failed"
+    return 2
+  fi
+
+  printf '%s\n' "$removed"
+  return 0
+}

package/lib/clast/clast-lib.bash

@@ -55,6 +55,78 @@ clast_json_get() {
   jq -r "$expr" <<<"$input"
 }
 
+# --- Front-matter / YAML -------------------------------------------------
+#
+# Curated journal entries are Markdown with a leading YAML front-matter block
+# fenced by `---`. These two primitives are the single source of truth for
+# reading that block; `entries.bash` and `clast-retro-lib.bash` both build on
+# them.
+
+# clast_read_frontmatter <path>
+#   Emit the raw front-matter lines (between the first two `---` fences) to
+#   stdout. Nothing is emitted for a file without a front-matter block.
+clast_read_frontmatter() {
+  local path="$1"
+  awk '
+    BEGIN { in_fm = 0; seen = 0 }
+    /^---[[:space:]]*$/ {
+      if (!seen) { in_fm = 1; seen = 1; next }
+      if (in_fm) { exit }
+    }
+    in_fm { print }
+  ' "$path"
+}
+
+# clast_yaml_unquote <string>
+#   Strip surrounding double quotes and unescape \", \\, \n on a YAML scalar.
+#   A bare (unquoted) value is returned unchanged.
+clast_yaml_unquote() {
+  local v="$1"
+  if [[ "${v:0:1}" == '"' && "${v: -1}" == '"' && ${#v} -ge 2 ]]; then
+    v="${v:1:${#v}-2}"
+    # Process escapes in order: \\ → placeholder, \" → ", \n → LF, placeholder → \
+    v="${v//\\\\/$'\x01'}"
+    v="${v//\\\"/\"}"
+    v="${v//\\n/$'\n'}"
+    v="${v//$'\x01'/\\}"
+  fi
+  printf '%s' "$v"
+}
+
+# clast_entry_body <path>
+#   Emit the entry body — everything after the closing `---` of the
+#   front-matter block. A file with no front-matter is emitted whole.
+clast_entry_body() {
+  awk '
+    BEGIN { in_fm = 0; seen = 0; past = 0 }
+    !past && /^---[[:space:]]*$/ {
+      if (!seen) { in_fm = 1; seen = 1; next }
+      if (in_fm) { in_fm = 0; past = 1; next }
+    }
+    past { print; next }
+    !seen { print }   # no front-matter fence yet seen → plain file, echo through
+  ' "$1"
+}
+
+# clast_entry_title <path>
+#   The session title from `# Session: <title>` (first non-blank body line).
+#   Empty if absent.
+clast_entry_title() {
+  awk '
+    BEGIN { in_fm = 0; seen = 0; past = 0 }
+    /^---[[:space:]]*$/ {
+      if (!seen) { in_fm = 1; seen = 1; next }
+      if (in_fm) { in_fm = 0; past = 1; next }
+    }
+    in_fm { next }
+    past {
+      if ($0 ~ /^[[:space:]]*$/) next
+      if (sub(/^# Session: /, "")) { print; exit }
+      exit
+    }
+  ' "$1"
+}
+
 # --- Date math -----------------------------------------------------------
 #
 # Uses GNU `date -d` for relative-date math. The nix dev shell pulls in
@@ -71,22 +143,31 @@ _clast_now_epoch() {
   fi
 }
 
-# clast_today — local YYYY-MM-DD, adjusted by CLAST_DAY_CUTOFF (HH:MM, default 04:00).
-# A session starting before today's cutoff belongs to yesterday's bucket.
-clast_today() {
+# clast_day_bucket_for_epoch <epoch> — local YYYY-MM-DD for an epoch, adjusted
+# by CLAST_DAY_CUTOFF (HH:MM, default 04:00). Work before the cutoff belongs to
+# the previous day's bucket. Single source of truth for the day-bucket rule;
+# clast_today, `clast snapshot`, and `clast retro` all build on it.
+clast_day_bucket_for_epoch() {
+  local epoch="$1"
   local cutoff="${CLAST_DAY_CUTOFF:-04:00}"
-  local cutoff_hours cutoff_mins cutoff_secs now adjusted
+  local cutoff_hours cutoff_mins cutoff_secs adjusted
   cutoff_hours="${cutoff%%:*}"
   cutoff_mins="${cutoff##*:}"
   # Strip leading zeros so bash arithmetic doesn't treat them as octal.
   cutoff_hours=$((10#$cutoff_hours))
   cutoff_mins=$((10#$cutoff_mins))
   cutoff_secs=$((cutoff_hours * 3600 + cutoff_mins * 60))
-  now="$(_clast_now_epoch)"
-  adjusted=$((now - cutoff_secs))
+  adjusted=$((epoch - cutoff_secs))
+  # GNU `date -d` — BSD date not supported, per overview.md.
   date -d "@$adjusted" +%Y-%m-%d
 }
 
+# clast_today — local YYYY-MM-DD, adjusted by CLAST_DAY_CUTOFF (HH:MM, default 04:00).
+# A session starting before today's cutoff belongs to yesterday's bucket.
+clast_today() {
+  clast_day_bucket_for_epoch "$(_clast_now_epoch)"
+}
+
 # clast_parse_date <input> — print YYYY-MM-DD on stdout, exit non-zero on bad input.
 # Accepts:
 #   - ISO date: 2026-05-30
@@ -204,10 +285,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
@@ -219,6 +300,7 @@ Subcommands:
   breadcrumb    Append a one-line in-flight hint
   registry      Manage the project registry
   stats         Token/duration/session-count stats
+  retro         Work summary grouped by actual work day → project
   doctor        Sanity-check the journal
 
 Global flags:
@@ -229,5 +311,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

@@ -13,6 +13,13 @@ if [[ -n "${_CLAST_MANIFEST_LIB_SOURCED:-}" ]]; then
 fi
 _CLAST_MANIFEST_LIB_SOURCED=1
 
+# clast_manifest_rebuild_from_disk backfills the session-classification counts
+# via clast_session_msg_counts. Source the classify lib relative to this file
+# (not via CLAST_LIB) so callers that source manifest-lib directly — e.g. the
+# test suite — get the dependency without extra setup.
+# shellcheck source=lib/clast/clast-classify-lib.bash
+source "${BASH_SOURCE[0]%/*}/clast-classify-lib.bash"
+
 # clast_manifest_path — single chokepoint so CLAST_JOURNAL_DIR override
 # (via clast_journal_dir) redirects every read/write in this file.
 clast_manifest_path() {
@@ -26,13 +33,23 @@ _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> <user-msg-count> <assistant-msg-count>
 clast_manifest_append() {
-  if [[ $# -ne 6 ]]; then
-    clast_log_error "clast_manifest_append: expected 6 args, got $#"
+  if [[ $# -ne 11 ]]; then
+    clast_log_error "clast_manifest_append: expected 11 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"
+  # Session classification (clast-classify-lib.bash): counts of real user
+  # prompts and assistant replies. A session is a no-op (auto-dismissed by
+  # wake) when either is 0. Cached here so readers never re-open the
+  # transcript; legacy lines lack them and readers recompute on demand.
+  local user_msg_count="${10}" assistant_msg_count="${11}"
   local field
   for field in session_id source snapshot source_mtime source_size day_bucket; do
     if [[ -z "${!field}" ]]; then
@@ -44,6 +61,18 @@ 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
+  if ! [[ "$user_msg_count" =~ ^[0-9]+$ ]]; then
+    clast_log_error "clast_manifest_append: user_msg_count must be a non-negative integer, got '$user_msg_count'"
+    return 2
+  fi
+  if ! [[ "$assistant_msg_count" =~ ^[0-9]+$ ]]; then
+    clast_log_error "clast_manifest_append: assistant_msg_count must be a non-negative integer, got '$assistant_msg_count'"
+    return 2
+  fi
 
   local journal_dir
   journal_dir="$(clast_journal_dir)"
@@ -62,7 +91,12 @@ 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" \
+    --argjson user_msg_count "$user_msg_count" \
+    --argjson assistant_msg_count "$assistant_msg_count" \
+    '{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), user_msg_count: $user_msg_count, assistant_msg_count: $assistant_msg_count}')" || {
     clast_log_error "clast_manifest_append: jq failed to build manifest line"
     return 1
   }
@@ -168,6 +202,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 +220,31 @@ 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
+      # Session classification counts are equally recoverable from the copy.
+      local user_msg_count assistant_msg_count
+      IFS=$'\t' read -r user_msg_count assistant_msg_count \
+        < <(clast_session_msg_counts "$snapshot")
+      [[ "$user_msg_count" =~ ^[0-9]+$ ]] || user_msg_count=0
+      [[ "$assistant_msg_count" =~ ^[0-9]+$ ]] || assistant_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" \
+        --argjson user_msg_count "$user_msg_count" \
+        --argjson assistant_msg_count "$assistant_msg_count" \
+        '{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), user_msg_count: $user_msg_count, assistant_msg_count: $assistant_msg_count}')" || {
         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,230 @@
+# 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 /wake)
+  brief         Project briefing (standalone equivalent of /brief)
+  retro         Model-condensed work retrospective by work day → project
+  undismiss     Restore session(s) dismissed in wake (by session id)
+
+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"
+
+  # Build and send the request without ever passing the (possibly hundreds of
+  # KB) prompt through argv: a single argument above MAX_ARG_STRLEN (128KB on
+  # Linux) fails with "Argument list too long", even well under total ARG_MAX.
+  # jq reads the strings via --rawfile (process substitution; printf is a
+  # builtin with no argv limit) and curl reads the body from a file with @.
+  local payload_file
+  payload_file="$(mktemp)" || { clast_porcelain_warn "failed to create temp file"; return 1; }
+  if ! jq -cn \
+      --arg model "$CLAST_LLM_MODEL" \
+      --rawfile system <(printf '%s' "$system_msg") \
+      --rawfile user <(printf '%s' "$user_msg") \
+      '{
+        model: $model,
+        messages: [
+          {role: "system", content: $system},
+          {role: "user", content: $user}
+        ],
+        temperature: 0.3
+      }' >"$payload_file"; then
+    rm -f "$payload_file"
+    clast_porcelain_warn "failed to build LLM request payload"
+    return 1
+  fi
+
+  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" \
+    --data-binary @"$payload_file" 2>&1)" || true
+  rm -f "$payload_file"
+
+  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
+}