@procrastivity/clast 0.0.3 → 0.0.4

package/.claude-plugin/skills/day-wakeup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: day-wakeup
-description: 'Generate curated journal entries from yesterday''s Claude Code sessions across all projects. Use when the user says "/day-wakeup", "day wakeup", "morning briefing", "catch me up on yesterday", "what did I work on yesterday", "review my day", "process yesterday''s sessions", or otherwise signals they want to curate prior work across projects at the start of a new day. Runs `clast snapshot` to ensure fresh data, then walks through each uncurated session from yesterday and proposes a draft entry the user can accept, edit, or skip. Prompts for promotion of decisions, common-issues, and workflows per accepted session. This is the once-per-day curation flow; for per-project briefings use /wakeup; for mid-session pivots use session-brief.'
+description: 'Generate curated journal entries from yesterday''s Claude Code sessions across all projects. Use when the user says "/day-wakeup", "day wakeup", "morning briefing", "catch me up on yesterday", "what did I work on yesterday", "review my day", "process yesterday''s sessions", or otherwise signals they want to curate prior work across projects at the start of a new day. Runs `clast-plumbing snapshot` to ensure fresh data, then walks through each uncurated session from yesterday and proposes a draft entry the user can accept, edit, or skip. Prompts for promotion of decisions, common-issues, and workflows per accepted session. This is the once-per-day curation flow; for per-project briefings use /wakeup; for mid-session pivots use session-brief.'
 ---
 
 # Day Wakeup
@@ -13,28 +13,30 @@ Curation at end-of-session has high friction (the user wants to stop, not summar
 
 The transcripts themselves are captured automatically by the SessionStart hook + cron — the user never has to remember to log anything. What `/day-wakeup` does is **curate the captured transcripts into durable entries the user controls**, and prompt for promotion of decisions, common-issues, and workflows along the way.
 
-## Step 0: Resolve the clast binary
+## Step 0: Resolve the clast-plumbing binary
 
-Before running any `clast` command, determine which binary to use. Run this
-once at the start and reuse the result for all commands in this skill:
+This skill calls the deterministic core (`clast-plumbing`), not the
+LLM-aware porcelain (`clast`). Determine the binary to use once at the
+start and reuse the result for all commands in this skill:
 
 ```bash
-if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" && -x "$CLAUDE_PLUGIN_ROOT/bin/clast" ]]; then
-  CLAST_BIN="$CLAUDE_PLUGIN_ROOT/bin/clast"
-elif command -v clast >/dev/null 2>&1; then
-  CLAST_BIN="clast"
+if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" && -x "$CLAUDE_PLUGIN_ROOT/bin/clast-plumbing" ]]; then
+  CLAST_BIN="$CLAUDE_PLUGIN_ROOT/bin/clast-plumbing"
+elif command -v clast-plumbing >/dev/null 2>&1; then
+  CLAST_BIN="clast-plumbing"
 else
   _pdir="$(find ~/.claude -maxdepth 5 -name plugin.json -path '*/clast/.claude-plugin/*' -print -quit 2>/dev/null)"
   if [[ -n "$_pdir" ]]; then
-    CLAST_BIN="$(cd "$(dirname "$_pdir")/../.." && pwd)/bin/clast"
+    CLAST_BIN="$(cd "$(dirname "$_pdir")/../.." && pwd)/bin/clast-plumbing"
   fi
 fi
 ```
 
-If `CLAST_BIN` is still empty, tell the user: "clast CLI not found. Install it
-with `npm i -g @procrastivity/clast` or see the README for other options."
+If `CLAST_BIN` is still empty, tell the user: "clast-plumbing CLI not found.
+Install it with `npm i -g @procrastivity/clast` or see the README for other
+options."
 
-Use `$CLAST_BIN` in place of bare `clast` for all commands in this skill.
+Use `$CLAST_BIN` in place of bare `clast-plumbing` for all commands in this skill.
 
 ## Step 1: Ensure fresh data
 
@@ -108,7 +110,7 @@ For each session in the list:
 5. Present the **promotion question** (see below) via AskUserQuestion.
 
 6. Handle the response:
-   - **Accept** (any combination of accept-flavored options): pipe the draft to `clast entries write` via stdin.
+   - **Accept** (any combination of accept-flavored options): pipe the draft to `clast-plumbing entries write` via stdin.
    - **Edit**: prompt the user for what to change, regenerate the draft incorporating their feedback, loop.
    - **Skip**: do not write.
    - **Stop here**: end the entire `/day-wakeup` flow, leaving remaining sessions uncurated (user can resume tomorrow).
@@ -133,7 +135,7 @@ Run `/wakeup <project>` to start working on a specific project today.
 
 ## Draft generation prompt
 
-The prompt templates live in `lib/clast/prompts/` so they are shared with the standalone `clast-wake` script:
+The prompt templates live in `lib/clast/prompts/` so they are shared with the porcelain `clast wake` subcommand:
 
 - **System prompt:** `lib/clast/prompts/day-wakeup-draft-system.md`
 - **User prompt template:** `lib/clast/prompts/day-wakeup-draft-user.md` (uses `{{placeholder}}` syntax)
@@ -175,7 +177,7 @@ If the user selects `Edit`:
 When the user accepts:
 
 1. Extract the suggested tags from the draft (the user may have edited them).
-2. Pipe the entry body (without the suggested-tags trailer) to `clast entries write`:
+2. Pipe the entry body (without the suggested-tags trailer) to `clast-plumbing entries write`:
 
 ```bash
 $CLAST_BIN entries write \
@@ -190,14 +192,14 @@ $CLAST_BIN entries write \
 
 3. If the write succeeds, append a one-line confirmation to the running summary.
 
-For promoted items (decisions, common-issues, workflows): currently these are tracked inside the entry's body for v1. **TODO for v1.1: separate `clast decisions write` / `clast common-issues write` / `clast workflows write` subcommands and a directory structure to match.** Note this in the user-facing summary so the user knows they're folded into the entry for now.
+For promoted items (decisions, common-issues, workflows): currently these are tracked inside the entry's body for v1. **TODO for v1.1: separate `clast-plumbing decisions write` / `clast-plumbing common-issues write` / `clast-plumbing workflows write` subcommands and a directory structure to match.** Note this in the user-facing summary so the user knows they're folded into the entry for now.
 
-<!-- step-12 addition: v1 promotion section convention --> When folding promoted items into the accepted entry body, append `## Decision`, `## Common issue`, or `## Workflow` (h2, singular, capitalized), each followed by the prompted-for title (h3) and body before invoking `clast entries write`.
+<!-- step-12 addition: v1 promotion section convention --> When folding promoted items into the accepted entry body, append `## Decision`, `## Common issue`, or `## Workflow` (h2, singular, capitalized), each followed by the prompted-for title (h3) and body before invoking `clast-plumbing entries write`.
 
 ## Edge cases
 
 - **No uncurated sessions**: print "Nothing to curate — all sessions are curated or dismissed." and stop.
 - **Multi-day backlog**: present the triage step (Step 2) so the user can choose scope before processing.
-- **`clast snapshot` fails**: warn the user, then attempt to proceed with whatever's already in the manifest.
-- **`clast show` fails for a specific session**: skip that session, note it in the final summary, continue with the rest.
+- **`clast-plumbing snapshot` fails**: warn the user, then attempt to proceed with whatever's already in the manifest.
+- **`clast-plumbing show` fails for a specific session**: skip that session, note it in the final summary, continue with the rest.
 - **User says "do them all without prompting"**: not a v1 feature. Each session gets its own AskUserQuestion. The friction is intentional — it's where curation happens.

package/.claude-plugin/skills/wakeup/SKILL.md

@@ -12,28 +12,30 @@ Synthesize a briefing for the current (or named) project so the user can resume
 
 `/day-wakeup` curates yesterday's work into entries. `/wakeup` reads those entries back when starting work in a specific repo. The two are complementary: one writes, one reads.
 
-## Step 0: Resolve the clast binary
+## Step 0: Resolve the clast-plumbing binary
 
-Before running any `clast` command, determine which binary to use. Run this
-once at the start and reuse the result for all commands in this skill:
+This skill calls the deterministic core (`clast-plumbing`), not the
+LLM-aware porcelain (`clast`). Determine the binary to use once at the
+start and reuse the result for all commands in this skill:
 
 ```bash
-if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" && -x "$CLAUDE_PLUGIN_ROOT/bin/clast" ]]; then
-  CLAST_BIN="$CLAUDE_PLUGIN_ROOT/bin/clast"
-elif command -v clast >/dev/null 2>&1; then
-  CLAST_BIN="clast"
+if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" && -x "$CLAUDE_PLUGIN_ROOT/bin/clast-plumbing" ]]; then
+  CLAST_BIN="$CLAUDE_PLUGIN_ROOT/bin/clast-plumbing"
+elif command -v clast-plumbing >/dev/null 2>&1; then
+  CLAST_BIN="clast-plumbing"
 else
   _pdir="$(find ~/.claude -maxdepth 5 -name plugin.json -path '*/clast/.claude-plugin/*' -print -quit 2>/dev/null)"
   if [[ -n "$_pdir" ]]; then
-    CLAST_BIN="$(cd "$(dirname "$_pdir")/../.." && pwd)/bin/clast"
+    CLAST_BIN="$(cd "$(dirname "$_pdir")/../.." && pwd)/bin/clast-plumbing"
   fi
 fi
 ```
 
-If `CLAST_BIN` is still empty, tell the user: "clast CLI not found. Install it
-with `npm i -g @procrastivity/clast` or see the README for other options."
+If `CLAST_BIN` is still empty, tell the user: "clast-plumbing CLI not found.
+Install it with `npm i -g @procrastivity/clast` or see the README for other
+options."
 
-Use `$CLAST_BIN` in place of bare `clast` for all commands in this skill.
+Use `$CLAST_BIN` in place of bare `clast-plumbing` for all commands in this skill.
 
 ## Step 1: Resolve the project
 
@@ -43,7 +45,7 @@ If the user passed a slug as an argument (`/wakeup xesapps`), use it directly. O
 $CLAST_BIN registry resolve "$(pwd)"
 ```
 
-If `pwd` doesn't resolve and no slug was given: print "Not in a registered project. Run `clast registry add .` first, or invoke as `/wakeup <slug>`." and stop.
+If `pwd` doesn't resolve and no slug was given: print "Not in a registered project. Run `clast-plumbing registry add .` first, or invoke as `/wakeup <slug>`." and stop.
 
 ## Step 2: Gather data
 
@@ -103,7 +105,7 @@ Wakeup is read-only. Never invoke write-form subcommands (`entries write`, `brea
 
 ## Edge cases
 
-- **No entries for project**: print "No curated entries for `<slug>` yet. Run `/day-wakeup` to process recent sessions, or run `clast sessions --project <slug>` to see what's available." and stop.
+- **No entries for project**: print "No curated entries for `<slug>` yet. Run `/day-wakeup` to process recent sessions, or run `clast-plumbing sessions --project <slug>` to see what's available." and stop.
 - **Slug resolves but no entries and no sessions**: print "Project `<slug>` registered but has no journal activity yet."
 - **Today's session count > 5**: summarize ("worked 12 sessions today, most recent 16:22 on branch `loop-guard-ngram`") rather than listing all.
 

package/README.md

@@ -6,27 +6,30 @@ Capture, curate, and surface Claude Code session history across all your project
 
 ## What it does
 
-- **CLI** (`clast`) — snapshot, browse, and query your Claude Code session JSONL history.
+- **CLI** — two binaries, porcelain over plumbing:
+  - `clast` — porcelain (LLM-aware): `clast wake`, `clast brief`. See [run without Claude Code](./docs/guides/run-without-claude-code.md).
+  - `clast-plumbing` — deterministic core: snapshot, browse, and query your Claude Code session JSONL history.
 - **Plugin** — installs skills (`/day-wakeup`, `/wakeup`) that surface recent session context.
 - **SessionStart hook** — quietly snapshots active sessions in the background each time Claude Code starts.
 
 ## Capture your sessions
 
 ```sh
-clast snapshot                       # copy any new sessions into the journal
-clast snapshot --dry-run --json | jq # preview what would be captured
+clast-plumbing snapshot                       # copy any new sessions into the journal
+clast-plumbing snapshot --dry-run --json | jq # preview what would be captured
 ```
 
-`clast snapshot` is idempotent and silent on no-op, safe to run from cron or
-a SessionStart hook. See [`docs/reference/cli.md#clast-snapshot`](./docs/reference/cli.md#clast-snapshot)
+`clast-plumbing snapshot` is idempotent and silent on no-op, safe to run from
+cron or a SessionStart hook. See
+[`docs/reference/cli.md#clast-snapshot`](./docs/reference/cli.md#clast-snapshot)
 for the full flag reference.
 
 ## Read your sessions
 
 ```sh
-clast projects                        # which projects had activity today
-clast sessions --since -7d            # sessions captured in the last week
-clast show <session-uuid> --full      # metadata + first/last turns
+clast-plumbing projects                        # which projects had activity today
+clast-plumbing sessions --since -7d            # sessions captured in the last week
+clast-plumbing show <session-uuid> --full      # metadata + first/last turns
 ```
 
 Window flags (`--day`, `--since`, `--until`) accept ISO dates and
@@ -39,14 +42,14 @@ for the full flag and output schemas.
 ## Curate an entry
 
 ```sh
-clast entries                                            # list curated entries
-clast entries read 2026-05-30-1430-xesapps-foo.md        # cat a single entry
-printf 'Notes...\n' | clast entries write \
-  --session <session-uuid> --slug short-slug --body-stdin # write a new entry
+clast-plumbing entries                                            # list curated entries
+clast-plumbing entries read 2026-05-30-1430-xesapps-foo.md        # cat a single entry
+printf 'Notes...\n' | clast-plumbing entries write \
+  --session <session-uuid> --slug short-slug --body-stdin          # write a new entry
 ```
 
-`clast entries write` looks up the session in the manifest, composes the
-documented frontmatter from the captured snapshot + registry, and writes
+`clast-plumbing entries write` looks up the session in the manifest, composes
+the documented frontmatter from the captured snapshot + registry, and writes
 `entries/YYYY-MM-DD-HHMM-<project-slug>-<session-slug>.md` atomically. See
 [`docs/reference/cli.md#entry-frontmatter`](./docs/reference/cli.md#entry-frontmatter)
 for the full frontmatter schema and
@@ -56,11 +59,11 @@ for the flag reference.
 ## Leave a breadcrumb
 
 ```sh
-clast breadcrumb --project xesapps 'check migration before deploy'
-clast breadcrumb --global 'remember to bump the cache version'
+clast-plumbing breadcrumb --project xesapps 'check migration before deploy'
+clast-plumbing breadcrumb --global 'remember to bump the cache version'
 
-clast breadcrumb --read --project xesapps
-clast breadcrumb --read --global
+clast-plumbing breadcrumb --read --project xesapps
+clast-plumbing breadcrumb --read --global
 ```
 
 Breadcrumbs are append-only one-line notes for `/wakeup` and `/day-wakeup`.
@@ -70,17 +73,17 @@ for the full command contract.
 ## Inspect and audit the journal
 
 ```sh
-clast stats                          # one-line activity summary for today
-clast stats --since -7d              # rollup over the last week
+clast-plumbing stats                          # one-line activity summary for today
+clast-plumbing stats --since -7d              # rollup over the last week
 
-clast doctor                         # check manifest, registry, snapshots
-clast doctor --fix                   # rebuild a broken manifest, prune orphans
+clast-plumbing doctor                         # check manifest, registry, snapshots
+clast-plumbing doctor --fix                   # rebuild a broken manifest, prune orphans
 ```
 
 See [`docs/reference/cli.md#clast-stats`](./docs/reference/cli.md#clast-stats)
 and [`docs/reference/cli.md#clast-doctor`](./docs/reference/cli.md#clast-doctor)
-for the contract reference, and `clast stats --help` / `clast doctor --help`
-for the current set of flags.
+for the contract reference, and `clast-plumbing stats --help` /
+`clast-plumbing doctor --help` for the current set of flags.
 
 ## Install to a prefix
 
@@ -102,9 +105,9 @@ for the rationale.
 With Nix flakes enabled, you can use `clast` directly from the public flake:
 
 ```sh
-nix run github:procrastivity/clast -- whereami
 nix profile install github:procrastivity/clast
-nix build .#default && ./result/bin/clast --version
+nix build .#default && ./result/bin/clast --version       # porcelain
+nix build .#default && ./result/bin/clast-plumbing --help # plumbing
 ```
 
 For Home Manager or nix-darwin users, `overlays.default` exposes `pkgs.clast`.
@@ -135,9 +138,9 @@ The plugin can be installed from any local checkout, or via `npm install -g`
 (which puts `.claude-plugin/` under `npm root -g`); a centralized marketplace
 listing is a separate distribution channel deliberately not pursued for v1.
 Today the plugin ships a single `SessionStart` hook: every time a Claude Code
-session starts it backgrounds `clast snapshot`, so your journal stays current
-with zero manual effort. The hook is best-effort and silent: if the `clast` CLI
-isn't on your `PATH` yet, sessions still start cleanly. See
+session starts it backgrounds `clast-plumbing snapshot`, so your journal stays
+current with zero manual effort. The hook is best-effort and silent: if the
+`clast-plumbing` CLI isn't on your `PATH` yet, sessions still start cleanly. See
 [`docs/reference/plugin.md#hook-sessionstart`](./docs/reference/plugin.md#hook-sessionstart)
 for the hook's design rationale.
 

package/bin/clast

@@ -1,93 +1,41 @@
 #!/usr/bin/env bash
-# clast — main dispatcher.
+# clast — porcelain over clast-plumbing, with an OpenAI-compatible LLM
+# provider. Owns the `wake` and `brief` subcommands. Every other verb is a
+# clean error — the porcelain does not proxy to plumbing.
 #
-# Parses global flags, sources libs, dispatches to a subcommand.
-# Subcommand files live in $CLAST_LIB/clast-subcommands/<name>.bash and
-# each defines a single function `clast_cmd_<name>`.
+# Subcommand files live in $CLAST_LIB/clast-porcelain-subcommands/<name>.bash
+# and each defines a single function `clast_cmd_<name>`.
 set -euo pipefail
 
 CLAST_LIB="${CLAST_LIB:-$(dirname "$(realpath "$0")")/../lib/clast}"
 export CLAST_LIB
 
-# shellcheck source=lib/clast/clast-lib.bash
-source "$CLAST_LIB/clast-lib.bash"
-# shellcheck source=lib/clast/clast-decode-lib.bash
-source "$CLAST_LIB/clast-decode-lib.bash"
-# shellcheck source=lib/clast/clast-registry-lib.bash
-source "$CLAST_LIB/clast-registry-lib.bash"
-# shellcheck source=lib/clast/clast-manifest-lib.bash
-source "$CLAST_LIB/clast-manifest-lib.bash"
-
-# --- Global flag parsing -------------------------------------------------
-#
-# Walk argv before the subcommand name, peeling off any recognized global
-# flag and setting the corresponding env var. Stop at the first non-flag
-# arg (the subcommand) or at `--`. Remaining argv is passed to the
-# subcommand untouched.
-#
-# `--json` and `--journal-dir`/`--projects-dir` are forwarded to the lib
-# via env so subcommands can also accept them locally without re-parsing.
+# shellcheck source=lib/clast/clast-porcelain-lib.bash
+source "$CLAST_LIB/clast-porcelain-lib.bash"
 
 declare -a _CLAST_REMAINING=()
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
     -h|--help|help)
-      clast_usage
+      clast_porcelain_usage
       exit 0
       ;;
     --version)
-      echo "clast $(clast_version)"
+      echo "clast $(clast_porcelain_version)"
       exit 0
       ;;
-    --json)
-      export CLAST_JSON=1
-      shift
-      ;;
-    -v|--verbose)
-      export CLAST_VERBOSE=1
-      shift
-      ;;
-    -q|--quiet)
-      export CLAST_QUIET=1
-      shift
-      ;;
-    --journal-dir)
-      if [[ $# -lt 2 ]]; then
-        clast_log_error "--journal-dir requires a value"
-        exit 2
-      fi
-      export CLAST_JOURNAL_DIR="$2"
-      shift 2
-      ;;
-    --journal-dir=*)
-      export CLAST_JOURNAL_DIR="${1#*=}"
-      shift
-      ;;
-    --projects-dir)
-      if [[ $# -lt 2 ]]; then
-        clast_log_error "--projects-dir requires a value"
-        exit 2
-      fi
-      export CLAST_PROJECTS_DIR="$2"
-      shift 2
-      ;;
-    --projects-dir=*)
-      export CLAST_PROJECTS_DIR="${1#*=}"
-      shift
-      ;;
     --)
       shift
       _CLAST_REMAINING+=("$@")
       break
       ;;
     -*)
-      clast_log_error "unknown global flag: $1"
-      clast_usage >&2
+      clast_porcelain_log_error "unknown global flag: $1"
+      clast_porcelain_usage >&2
       exit 2
       ;;
     *)
-      # First non-flag arg is the subcommand; stop parsing.
       _CLAST_REMAINING+=("$@")
       break
       ;;
@@ -95,7 +43,7 @@ while [[ $# -gt 0 ]]; do
 done
 
 if [[ ${#_CLAST_REMAINING[@]} -eq 0 ]]; then
-  clast_usage
+  clast_porcelain_usage
   exit 0
 fi
 
@@ -103,70 +51,20 @@ set -- "${_CLAST_REMAINING[@]}"
 
 cmd="$1"; shift
 
-# --- Subcommand dispatch -------------------------------------------------
-
-# Map of stubbed subcommands → step number that will implement them.
-# Future steps replace each stub with a real `source` + dispatch below.
-_clast_stub() {
-  local name="$1" step="$2"
-  clast_log_error "$name is not yet implemented (planned for step $step)"
-  exit 2
-}
-
 case "$cmd" in
-  whereami)
-    # shellcheck source=lib/clast/clast-subcommands/whereami.bash
-    source "$CLAST_LIB/clast-subcommands/whereami.bash"
-    clast_cmd_whereami "$@"
-    ;;
-  snapshot)
-    # shellcheck source=lib/clast/clast-subcommands/snapshot.bash
-    source "$CLAST_LIB/clast-subcommands/snapshot.bash"
-    clast_cmd_snapshot "$@"
-    ;;
-  projects)
-    # shellcheck source=lib/clast/clast-subcommands/projects.bash
-    source "$CLAST_LIB/clast-subcommands/projects.bash"
-    clast_cmd_projects "$@"
-    ;;
-  sessions)
-    # shellcheck source=lib/clast/clast-subcommands/sessions.bash
-    source "$CLAST_LIB/clast-subcommands/sessions.bash"
-    clast_cmd_sessions "$@"
-    ;;
-  show)
-    # shellcheck source=lib/clast/clast-subcommands/show.bash
-    source "$CLAST_LIB/clast-subcommands/show.bash"
-    clast_cmd_show "$@"
-    ;;
-  entries)
-    # shellcheck source=lib/clast/clast-subcommands/entries.bash
-    source "$CLAST_LIB/clast-subcommands/entries.bash"
-    clast_cmd_entries "$@"
-    ;;
-  breadcrumb)
-    # shellcheck source=lib/clast/clast-subcommands/breadcrumb.bash
-    source "$CLAST_LIB/clast-subcommands/breadcrumb.bash"
-    clast_cmd_breadcrumb "$@"
-    ;;
-  registry)
-    # shellcheck source=lib/clast/clast-subcommands/registry.bash
-    source "$CLAST_LIB/clast-subcommands/registry.bash"
-    clast_cmd_registry "$@"
-    ;;
-  stats)
-    # shellcheck source=lib/clast/clast-subcommands/stats.bash
-    source "$CLAST_LIB/clast-subcommands/stats.bash"
-    clast_cmd_stats "$@"
+  wake)
+    # shellcheck source=lib/clast/clast-porcelain-subcommands/wake.bash
+    source "$CLAST_LIB/clast-porcelain-subcommands/wake.bash"
+    clast_cmd_wake "$@"
     ;;
-  doctor)
-    # shellcheck source=lib/clast/clast-subcommands/doctor.bash
-    source "$CLAST_LIB/clast-subcommands/doctor.bash"
-    clast_cmd_doctor "$@"
+  brief)
+    # shellcheck source=lib/clast/clast-porcelain-subcommands/brief.bash
+    source "$CLAST_LIB/clast-porcelain-subcommands/brief.bash"
+    clast_cmd_brief "$@"
     ;;
   *)
-    clast_log_error "unknown subcommand '$cmd'"
-    clast_usage >&2
+    clast_porcelain_log_error "unknown subcommand '$cmd'"
+    clast_porcelain_usage >&2
     exit 2
     ;;
 esac

package/bin/clast-plumbing

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+# clast-plumbing — main dispatcher (the deterministic, LLM-free core).
+#
+# Parses global flags, sources libs, dispatches to a subcommand.
+# Subcommand files live in $CLAST_LIB/clast-subcommands/<name>.bash and
+# each defines a single function `clast_cmd_<name>`. The user-facing
+# porcelain is `bin/clast` (see `clast --help` for that surface).
+set -euo pipefail
+
+CLAST_LIB="${CLAST_LIB:-$(dirname "$(realpath "$0")")/../lib/clast}"
+export CLAST_LIB
+
+# shellcheck source=lib/clast/clast-lib.bash
+source "$CLAST_LIB/clast-lib.bash"
+# shellcheck source=lib/clast/clast-decode-lib.bash
+source "$CLAST_LIB/clast-decode-lib.bash"
+# shellcheck source=lib/clast/clast-registry-lib.bash
+source "$CLAST_LIB/clast-registry-lib.bash"
+# shellcheck source=lib/clast/clast-manifest-lib.bash
+source "$CLAST_LIB/clast-manifest-lib.bash"
+
+# --- Global flag parsing -------------------------------------------------
+#
+# Walk argv before the subcommand name, peeling off any recognized global
+# flag and setting the corresponding env var. Stop at the first non-flag
+# arg (the subcommand) or at `--`. Remaining argv is passed to the
+# subcommand untouched.
+#
+# `--json` and `--journal-dir`/`--projects-dir` are forwarded to the lib
+# via env so subcommands can also accept them locally without re-parsing.
+
+declare -a _CLAST_REMAINING=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help|help)
+      clast_usage
+      exit 0
+      ;;
+    --version)
+      echo "clast-plumbing $(clast_version)"
+      exit 0
+      ;;
+    --json)
+      export CLAST_JSON=1
+      shift
+      ;;
+    -v|--verbose)
+      export CLAST_VERBOSE=1
+      shift
+      ;;
+    -q|--quiet)
+      export CLAST_QUIET=1
+      shift
+      ;;
+    --journal-dir)
+      if [[ $# -lt 2 ]]; then
+        clast_log_error "--journal-dir requires a value"
+        exit 2
+      fi
+      export CLAST_JOURNAL_DIR="$2"
+      shift 2
+      ;;
+    --journal-dir=*)
+      export CLAST_JOURNAL_DIR="${1#*=}"
+      shift
+      ;;
+    --projects-dir)
+      if [[ $# -lt 2 ]]; then
+        clast_log_error "--projects-dir requires a value"
+        exit 2
+      fi
+      export CLAST_PROJECTS_DIR="$2"
+      shift 2
+      ;;
+    --projects-dir=*)
+      export CLAST_PROJECTS_DIR="${1#*=}"
+      shift
+      ;;
+    --)
+      shift
+      _CLAST_REMAINING+=("$@")
+      break
+      ;;
+    -*)
+      clast_log_error "unknown global flag: $1"
+      clast_usage >&2
+      exit 2
+      ;;
+    *)
+      # First non-flag arg is the subcommand; stop parsing.
+      _CLAST_REMAINING+=("$@")
+      break
+      ;;
+  esac
+done
+
+if [[ ${#_CLAST_REMAINING[@]} -eq 0 ]]; then
+  clast_usage
+  exit 0
+fi
+
+set -- "${_CLAST_REMAINING[@]}"
+
+cmd="$1"; shift
+
+# --- Subcommand dispatch -------------------------------------------------
+
+# Map of stubbed subcommands → step number that will implement them.
+# Future steps replace each stub with a real `source` + dispatch below.
+_clast_stub() {
+  local name="$1" step="$2"
+  clast_log_error "$name is not yet implemented (planned for step $step)"
+  exit 2
+}
+
+case "$cmd" in
+  whereami)
+    # shellcheck source=lib/clast/clast-subcommands/whereami.bash
+    source "$CLAST_LIB/clast-subcommands/whereami.bash"
+    clast_cmd_whereami "$@"
+    ;;
+  snapshot)
+    # shellcheck source=lib/clast/clast-subcommands/snapshot.bash
+    source "$CLAST_LIB/clast-subcommands/snapshot.bash"
+    clast_cmd_snapshot "$@"
+    ;;
+  projects)
+    # shellcheck source=lib/clast/clast-subcommands/projects.bash
+    source "$CLAST_LIB/clast-subcommands/projects.bash"
+    clast_cmd_projects "$@"
+    ;;
+  sessions)
+    # shellcheck source=lib/clast/clast-subcommands/sessions.bash
+    source "$CLAST_LIB/clast-subcommands/sessions.bash"
+    clast_cmd_sessions "$@"
+    ;;
+  show)
+    # shellcheck source=lib/clast/clast-subcommands/show.bash
+    source "$CLAST_LIB/clast-subcommands/show.bash"
+    clast_cmd_show "$@"
+    ;;
+  entries)
+    # shellcheck source=lib/clast/clast-subcommands/entries.bash
+    source "$CLAST_LIB/clast-subcommands/entries.bash"
+    clast_cmd_entries "$@"
+    ;;
+  breadcrumb)
+    # shellcheck source=lib/clast/clast-subcommands/breadcrumb.bash
+    source "$CLAST_LIB/clast-subcommands/breadcrumb.bash"
+    clast_cmd_breadcrumb "$@"
+    ;;
+  registry)
+    # shellcheck source=lib/clast/clast-subcommands/registry.bash
+    source "$CLAST_LIB/clast-subcommands/registry.bash"
+    clast_cmd_registry "$@"
+    ;;
+  stats)
+    # shellcheck source=lib/clast/clast-subcommands/stats.bash
+    source "$CLAST_LIB/clast-subcommands/stats.bash"
+    clast_cmd_stats "$@"
+    ;;
+  doctor)
+    # shellcheck source=lib/clast/clast-subcommands/doctor.bash
+    source "$CLAST_LIB/clast-subcommands/doctor.bash"
+    clast_cmd_doctor "$@"
+    ;;
+  *)
+    clast_log_error "unknown subcommand '$cmd'"
+    clast_usage >&2
+    exit 2
+    ;;
+esac

package/examples/cron/clast-snapshot.service

@@ -3,8 +3,8 @@
 # then enable the timer with: systemctl --user enable --now clast-snapshot.timer
 
 [Unit]
-Description=Capture Claude Code transcripts with clast
+Description=Capture Claude Code transcripts with clast-plumbing
 
 [Service]
 Type=oneshot
-ExecStart=/usr/local/bin/clast snapshot
+ExecStart=/usr/local/bin/clast-plumbing snapshot

package/examples/cron/clast-snapshot.timer

@@ -3,7 +3,7 @@
 # systemctl --user enable --now clast-snapshot.timer
 
 [Unit]
-Description=Run clast snapshot hourly
+Description=Run clast-plumbing snapshot hourly
 
 [Timer]
 OnBootSec=5min