@procrastivity/clast 0.0.1 → 0.0.3

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

@@ -13,23 +13,76 @@ 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
+
+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:
+
+```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"
+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"
+  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."
+
+Use `$CLAST_BIN` in place of bare `clast` for all commands in this skill.
+
 ## Step 1: Ensure fresh data
 
-Run `clast snapshot` (idempotent; silent on no-op). This guarantees we're not missing anything that ran since the last hook fire.
+Run `$CLAST_BIN snapshot` (idempotent; silent on no-op). This guarantees we're not missing anything that ran since the last hook fire.
 
 ```bash
-clast snapshot
+$CLAST_BIN snapshot
 ```
 
 Errors here are non-fatal — proceed even if it fails, just warn the user.
 
-## Step 2: Enumerate uncurated sessions from yesterday
+## Step 2: Enumerate uncurated sessions
+
+Query all recent sessions (last 30 days) and filter to uncurated:
 
 ```bash
-clast --json sessions --day yesterday
+$CLAST_BIN --json sessions --since -30d
 ```
 
-Filter to sessions with `curated: false`. If everything from yesterday is already curated, print "Nothing to curate from yesterday — already done." and stop.
+Filter to sessions with `curated: false` or `stale: true` (stale sessions were curated but their transcript was updated since). If none remain, print "Nothing to curate — all sessions are curated or dismissed." and stop.
+
+### Triage when multiple days have uncurated sessions
+
+If uncurated sessions span more than one day (e.g., after a weekend or break), present a triage step before processing. Show a per-day breakdown:
+
+```
+Found 45 uncurated sessions across 5 days (2026-05-26 to 2026-05-30).
+
+    2026-05-26  8 session(s)
+    2026-05-27  12 session(s)
+    2026-05-28  15 session(s)
+    2026-05-29  7 session(s)
+    2026-05-30  3 session(s)
+```
+
+Then present via AskUserQuestion:
+
+- **question**: "How would you like to handle these?"
+- **header**: "Backlog"
+- **options**:
+  - `Process all` — curate everything
+  - `Yesterday only` — only process yesterday's sessions
+  - `Choose days back` — prompt for a number, process only that many days back
+  - `Dismiss older, process recent` — prompt for how many days to keep, dismiss the rest via `$CLAST_BIN sessions dismiss`, then process what remains
+
+If only one day has uncurated sessions, skip triage and process directly.
+
+### Ordering
 
 Group sessions by project for presentation. Order: most recent project first, sessions chronological within each project.
 
@@ -39,13 +92,13 @@ For each session in the list:
 
 1. Read session details:
    ```bash
-   clast --json show <session-id> --full --turns 8
+   $CLAST_BIN --json show <session-id> --full --turns 8
    ```
    This returns metadata + first 8 and last 8 turns of the transcript (text only, no tool calls — kept compact).
 
 2. Read breadcrumbs for this project from yesterday:
    ```bash
-   clast breadcrumb --read --project <slug> --day yesterday
+   $CLAST_BIN breadcrumb --read --project <slug> --day yesterday
    ```
 
 3. Generate a draft entry using the **draft generation prompt** (see below).
@@ -80,56 +133,12 @@ Run `/wakeup <project>` to start working on a specific project today.
 
 ## Draft generation prompt
 
-When generating each draft, use this prompt internally (with the placeholders filled in):
-
-````markdown
-You are drafting a journal entry for a Claude Code session that the user just reviewed. The entry will be written to the user's journal and may be read days or weeks later to refresh context on what was happening.
-
-Session metadata:
-- Project: {project}
-- Branch: {branch}
-- Start: {start}
-- End: {end}
-- Approximate messages: {msg_count}
-
-First 8 turns of the session:
-{first_turns}
-
-Last 8 turns of the session:
-{last_turns}
-
-Breadcrumbs the user left during this session's day:
-{breadcrumbs}
-
-Draft a journal entry in this exact markdown structure. Omit any section that has no content (don't write "N/A"):
-
-```
-# Session: <short human-readable title>
-
-## Goal
-One sentence describing what this session was trying to accomplish.
-
-## What shipped
-- Bullet list of what actually got done (files written, features built, fixes landed). Extract from the transcript.
-
-## Issues + fixes
-- **Issue:** what broke. **Fix:** what resolved it.
-
-## Dead ends touched
-- **Tried:** approach. (You can usually see this in the transcript as "tried X then switched to Y".)
-  - Note: if you can't tell *why* an approach was abandoned from the transcript, leave that for the user to fill in. Don't speculate.
-
-## Open threads
-- Anything still unfinished or deferred. Use the breadcrumbs and the last turns of the session as signal.
-
-## Notes
-- Anything else useful for the next session in this project.
-```
+The prompt templates live in `lib/clast/prompts/` so they are shared with the standalone `clast-wake` script:
 
-Be concise. Prefer bullets over paragraphs. Use the user's terminology (project-specific names, file paths). Don't invent details. If you're uncertain about something, omit it rather than guess.
+- **System prompt:** `lib/clast/prompts/day-wakeup-draft-system.md`
+- **User prompt template:** `lib/clast/prompts/day-wakeup-draft-user.md` (uses `{{placeholder}}` syntax)
 
-Suggest tags after the entry, separated by a blank line, prefixed with "Suggested tags:". The user will confirm.
-````
+When generating each draft, read those files and substitute the placeholders with session data. The user prompt template uses these placeholders: `{{project}}`, `{{branch}}`, `{{start}}`, `{{end}}`, `{{msg_count}}`, `{{first_turns}}`, `{{last_turns}}`, `{{breadcrumbs}}`.
 
 ## AskUserQuestion: promotion options per session
 
@@ -169,7 +178,7 @@ When the user accepts:
 2. Pipe the entry body (without the suggested-tags trailer) to `clast entries write`:
 
 ```bash
-clast entries write \
+$CLAST_BIN entries write \
   --session <session-id> \
   --slug <session-slug> \
   --tags <tag1>,<tag2>,<tag3> \
@@ -187,8 +196,8 @@ For promoted items (decisions, common-issues, workflows): currently these are tr
 
 ## Edge cases
 
-- **No sessions from yesterday**: print "No sessions from yesterday." and stop.
-- **All sessions already curated**: print "All sessions from yesterday already curated." and stop.
+- **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.
 - **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,12 +12,35 @@ 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
+
+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:
+
+```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"
+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"
+  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."
+
+Use `$CLAST_BIN` in place of bare `clast` for all commands in this skill.
+
 ## Step 1: Resolve the project
 
 If the user passed a slug as an argument (`/wakeup xesapps`), use it directly. Otherwise resolve from current working directory:
 
 ```bash
-clast registry resolve "$(pwd)"
+$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.
@@ -28,19 +51,19 @@ In parallel:
 
 ```bash
 # Recent curated entries for this project (newest first)
-clast --json entries --project <slug> --limit 5
+$CLAST_BIN --json entries --project <slug> --limit 5
 
 # Today's breadcrumbs for this project
-clast breadcrumb --read --project <slug> --day today
+$CLAST_BIN breadcrumb --read --project <slug> --day today
 
 # Today's session activity (if any — user might have started already)
-clast --json sessions --day today --project <slug>
+$CLAST_BIN --json sessions --day today --project <slug>
 ```
 
 For each entry returned, also read the body if it'll fit (file sizes are typically 1–5KB each):
 
 ```bash
-clast entries read <entry-path>
+$CLAST_BIN entries read <entry-path>
 ```
 
 ## Step 3: Synthesize the briefing

package/README.md

@@ -18,7 +18,7 @@ clast 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/cli-contract.md#clast-snapshot`](./docs/cli-contract.md#clast-snapshot)
+a SessionStart hook. See [`docs/reference/cli.md#clast-snapshot`](./docs/reference/cli.md#clast-snapshot)
 for the full flag reference.
 
 ## Read your sessions
@@ -31,9 +31,9 @@ clast show <session-uuid> --full      # metadata + first/last turns
 
 Window flags (`--day`, `--since`, `--until`) accept ISO dates and
 relative keywords. See
-[`docs/cli-contract.md#clast-projects`](./docs/cli-contract.md#clast-projects),
-[`docs/cli-contract.md#clast-sessions`](./docs/cli-contract.md#clast-sessions),
-and [`docs/cli-contract.md#clast-show`](./docs/cli-contract.md#clast-show)
+[`docs/reference/cli.md#clast-projects`](./docs/reference/cli.md#clast-projects),
+[`docs/reference/cli.md#clast-sessions`](./docs/reference/cli.md#clast-sessions),
+and [`docs/reference/cli.md#clast-show`](./docs/reference/cli.md#clast-show)
 for the full flag and output schemas.
 
 ## Curate an entry
@@ -48,9 +48,9 @@ printf 'Notes...\n' | clast entries write \
 `clast 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/cli-contract.md#entry-frontmatter`](./docs/cli-contract.md#entry-frontmatter)
+[`docs/reference/cli.md#entry-frontmatter`](./docs/reference/cli.md#entry-frontmatter)
 for the full frontmatter schema and
-[`docs/cli-contract.md#clast-entries`](./docs/cli-contract.md#clast-entries)
+[`docs/reference/cli.md#clast-entries`](./docs/reference/cli.md#clast-entries)
 for the flag reference.
 
 ## Leave a breadcrumb
@@ -64,7 +64,7 @@ clast breadcrumb --read --global
 ```
 
 Breadcrumbs are append-only one-line notes for `/wakeup` and `/day-wakeup`.
-See [`docs/cli-contract.md#clast-breadcrumb`](./docs/cli-contract.md#clast-breadcrumb)
+See [`docs/reference/cli.md#clast-breadcrumb`](./docs/reference/cli.md#clast-breadcrumb)
 for the full command contract.
 
 ## Inspect and audit the journal
@@ -77,8 +77,8 @@ clast doctor                         # check manifest, registry, snapshots
 clast doctor --fix                   # rebuild a broken manifest, prune orphans
 ```
 
-See [`docs/cli-contract.md#clast-stats`](./docs/cli-contract.md#clast-stats)
-and [`docs/cli-contract.md#clast-doctor`](./docs/cli-contract.md#clast-doctor)
+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.
 
@@ -90,9 +90,11 @@ for the current set of flags.
 ./install.sh ~/.local
 ```
 
-`make install` wraps the same script. Use `./uninstall.sh ~/.local` (or
-`make uninstall` for the default prefix) to remove the installed files. See
-[`docs/repo-bootstrap.md#installsh--uninstallsh`](./docs/repo-bootstrap.md#installsh--uninstallsh)
+`make install` wraps the same script; `make install-local` installs the working
+tree to `~/.local` with no sudo (and `make uninstall-local` removes it). Use
+`./uninstall.sh ~/.local` (or `make uninstall` for the default prefix) to remove
+the installed files. See
+[`docs/reference/repo-bootstrap.md#installsh--uninstallsh`](./docs/reference/repo-bootstrap.md#installsh--uninstallsh)
 for the rationale.
 
 ## Install with Nix
@@ -106,7 +108,7 @@ nix build .#default && ./result/bin/clast --version
 ```
 
 For Home Manager or nix-darwin users, `overlays.default` exposes `pkgs.clast`.
-See [`docs/repo-bootstrap.md#nix-flake`](./docs/repo-bootstrap.md#nix-flake)
+See [`docs/reference/repo-bootstrap.md#nix-flake`](./docs/reference/repo-bootstrap.md#nix-flake)
 for the full overlay wiring.
 
 ## Install via npm
@@ -136,7 +138,7 @@ 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
-[`docs/skill-prompts.md#hook-sessionstart`](./docs/skill-prompts.md#hook-sessionstart)
+[`docs/reference/plugin.md#hook-sessionstart`](./docs/reference/plugin.md#hook-sessionstart)
 for the hook's design rationale.
 
 ### `/day-wakeup`
@@ -145,7 +147,7 @@ At the start of each day, run `/day-wakeup` inside any Claude Code session after
 the plugin is installed. It performs once-per-day cross-project curation of
 yesterday's sessions into durable journal entries, walking each uncurated session
 through a draft you can accept, edit, skip, or mark for in-entry promotion. See
-[`docs/skill-prompts.md#skill-1-day-wakeup`](./docs/skill-prompts.md#skill-1-day-wakeup).
+[`docs/reference/plugin.md#skill-1-day-wakeup`](./docs/reference/plugin.md#skill-1-day-wakeup).
 
 ### `/wakeup`
 
@@ -153,7 +155,7 @@ When starting work on a specific project, run `/wakeup` (or `/wakeup <slug>` fro
 anywhere) to get a per-project read-only briefing synthesized from recent curated entries,
 today's breadcrumbs, and any sessions already started today. `/wakeup` never writes — it
 only reads. See
-[`docs/skill-prompts.md#skill-2-wakeup`](./docs/skill-prompts.md#skill-2-wakeup).
+[`docs/reference/plugin.md#skill-2-wakeup`](./docs/reference/plugin.md#skill-2-wakeup).
 
 ## Development
 
@@ -166,15 +168,16 @@ only reads. See
 Pull requests run lint, tests, version sync, npm pack shape, Nix smoke, flake check, and Nix build automatically.
 Releases trigger on `v*` tags, and the tag version must match `package.json` exactly.
 The release workflow publishes to npm with provenance and creates a GitHub Release with the npm tarball attached.
-Configure the `NPM_TOKEN` repo secret before the first release tag.
+Publishing to npm uses Trusted Publishing (OIDC) — no `NPM_TOKEN` secret. Configure the trusted publisher for `@procrastivity/clast` on npmjs.com before the first release tag; see [`docs/reference/releasing.md`](./docs/reference/releasing.md#trusted-publishing-setup).
 
 ## Documentation
 
-- [`docs/overview.md`](./docs/overview.md) — project overview and design.
-- [`docs/cli-contract.md`](./docs/cli-contract.md) — CLI reference.
-- [`docs/skill-prompts.md`](./docs/skill-prompts.md) — plugin reference.
-- [`docs/repo-bootstrap.md`](./docs/repo-bootstrap.md) — repo layout and packaging.
-- [`docs/releasing.md`](./docs/releasing.md) — release runbook.
+Start at [`docs/README.md`](./docs/README.md) for the full index. Highlights:
+
+- **Explanation** — [What is clast?](./docs/explanation/what-is-clast.md) · [Architecture](./docs/explanation/architecture.md) · [Data model](./docs/explanation/data-model.md) · [Conventions](./docs/explanation/conventions.md)
+- **Getting started** — [Install](./docs/getting-started/install.md) · [First snapshot](./docs/getting-started/first-snapshot.md) · [Install the plugin](./docs/getting-started/install-the-plugin.md)
+- **Guides** — [curate an entry](./docs/guides/curate-an-entry.md), [use breadcrumbs](./docs/guides/use-breadcrumbs.md), [automate with cron](./docs/guides/automate-with-cron.md) or [systemd](./docs/guides/automate-with-systemd.md), [repair the journal](./docs/guides/repair-the-journal.md), [query recipes](./docs/guides/query-recipes.md), [run without Claude Code](./docs/guides/run-without-claude-code.md), [morning briefing](./examples/workflows/morning-briefing.md)
+- **Reference** — [CLI](./docs/reference/cli.md) · [Plugin](./docs/reference/plugin.md) · [Entry frontmatter](./docs/reference/entry-frontmatter.md) · [Config](./docs/reference/config.md) · [Repo bootstrap](./docs/reference/repo-bootstrap.md) · [Releasing](./docs/reference/releasing.md)
 - [`examples/`](./examples/) — cron, systemd-timer, and workflow samples.
 
 ## License

package/bin/clast-brief

@@ -0,0 +1,305 @@
+#!/usr/bin/env bash
+# clast-brief — LLM-powered project briefing without Claude Code.
+#
+# Replicates the /wakeup plugin skill using an OpenAI-compatible
+# chat completions endpoint. Reads curated entries, breadcrumbs,
+# and today's sessions for a project, then synthesizes a briefing.
+#
+# Usage: clast-brief [<project-slug>]
+#
+# If no slug is given, resolves from the current working directory.
+#
+# Required env vars:
+#   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
+set -euo pipefail
+
+CLAST_BRIEF_DIR="$(cd "$(dirname "$(realpath "$0")")/.." && pwd)"
+
+# ── Helpers ──────────────────────────────────────────────────────────
+
+die() { printf 'clast-brief: %s\n' "$1" >&2; exit "${2:-1}"; }
+warn() { printf 'clast-brief: warning: %s\n' "$1" >&2; }
+info() { printf '%s\n' "$1"; }
+
+# ── Preflight ────────────────────────────────────────────────────────
+
+preflight() {
+  for tool in clast curl jq; do
+    if ! command -v "$tool" >/dev/null 2>&1; then
+      die "required tool not found: $tool"
+    fi
+  done
+
+  local missing=0
+  if [[ -z "${CLAST_LLM_BASE_URL:-}" ]]; then
+    warn "CLAST_LLM_BASE_URL not set"; missing=1
+  fi
+  if [[ -z "${CLAST_LLM_API_KEY:-}" ]]; then
+    warn "CLAST_LLM_API_KEY not set"; missing=1
+  fi
+  if [[ -z "${CLAST_LLM_MODEL:-}" ]]; then
+    warn "CLAST_LLM_MODEL not set"; missing=1
+  fi
+
+  if (( missing )); then
+    cat >&2 <<'EOF'
+
+Set these env vars before running 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 ─────────────────────────────────────────────────────────
+
+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
+    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")"
+      warn "$err_msg"
+    fi
+    return 1
+  fi
+
+  local content
+  content="$(jq -r '.choices[0].message.content // empty' <<<"$body" 2>/dev/null)" || {
+    warn "failed to parse LLM response"
+    return 1
+  }
+
+  if [[ -z "$content" ]]; then
+    warn "LLM returned empty content"
+    return 1
+  fi
+
+  printf '%s' "$content"
+}
+
+# ── Prompt template ──────────────────────────────────────────────────
+
+resolve_prompt_dir() {
+  local dir="$CLAST_BRIEF_DIR/lib/clast/prompts"
+  if [[ -d "$dir" ]]; then
+    printf '%s' "$dir"
+    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
+  die "cannot find prompts directory (checked $dir and install paths)"
+}
+
+load_system_prompt() {
+  local prompt_dir
+  prompt_dir="$(resolve_prompt_dir)"
+  local file="$prompt_dir/brief-system.md"
+  if [[ ! -r "$file" ]]; then
+    die "system prompt not found: $file"
+  fi
+  cat "$file"
+}
+
+build_user_prompt() {
+  local project="$1" entries="$2" breadcrumbs="$3" sessions="$4"
+
+  local prompt_dir
+  prompt_dir="$(resolve_prompt_dir)"
+  local template_file="$prompt_dir/brief-user.md"
+
+  if [[ -r "$template_file" ]]; then
+    local template
+    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
+    warn "user prompt template not found: $template_file — 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
+}
+
+# ── Resolve project ──────────────────────────────────────────────────
+
+resolve_project() {
+  local slug="${1:-}"
+
+  if [[ -n "$slug" ]]; then
+    printf '%s' "$slug"
+    return
+  fi
+
+  local resolved
+  resolved="$(clast registry resolve "$(pwd)" 2>/dev/null)" || true
+  if [[ -n "$resolved" ]]; then
+    printf '%s' "$resolved"
+    return
+  fi
+
+  die "Not in a registered project. Run \`clast registry add .\` first, or invoke as \`clast-brief <slug>\`."
+}
+
+# ── Gather data ──────────────────────────────────────────────────────
+
+gather_entries() {
+  local project="$1"
+  local entries_json
+  entries_json="$(clast --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 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"
+}
+
+gather_breadcrumbs() {
+  local project="$1"
+  clast breadcrumb --read --project "$project" --day today 2>/dev/null || true
+}
+
+gather_sessions() {
+  local project="$1"
+  local sessions_json
+  sessions_json="$(clast --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
+}
+
+# ── Main ─────────────────────────────────────────────────────────────
+
+main() {
+  preflight
+
+  local project
+  project="$(resolve_project "${1:-}")"
+  info "Briefing for project: $project"
+
+  info "Gathering context..."
+
+  local entries breadcrumbs sessions
+  entries="$(gather_entries "$project")"
+  breadcrumbs="$(gather_breadcrumbs "$project")"
+  sessions="$(gather_sessions "$project")"
+
+  if [[ -z "$entries" && -z "$breadcrumbs" && -z "$sessions" ]]; then
+    info "No curated entries, breadcrumbs, or sessions for \`$project\`."
+    info "Run \`clast-wake\` to curate recent sessions first, or run \`clast sessions --project $project\` to see what's available."
+    exit 0
+  fi
+
+  local system_prompt user_prompt
+  system_prompt="$(load_system_prompt)"
+  user_prompt="$(build_user_prompt "$project" "$entries" "$breadcrumbs" "$sessions")"
+
+  info "Synthesizing briefing..."
+  printf '\n'
+
+  local briefing
+  if ! briefing="$(llm_chat "$system_prompt" "$user_prompt")"; then
+    die "LLM call failed"
+  fi
+
+  printf '%s\n' "$briefing"
+}
+
+main "$@"