syntaur 0.8.0 → 0.12.0

package/examples/playbooks/keep-records-updated.md

@@ -4,7 +4,7 @@ slug: keep-records-updated
 description: "Agents must keep assignment.md criteria, progress.md, and related records current in real-time"
 when_to_use: "After every meaningful action, when completing acceptance criteria, when starting or stopping work"
 created: "2026-04-02T00:00:00Z"
-updated: "2026-04-20T00:00:00Z"
+updated: "2026-05-08T00:00:00Z"
 tags:
   - protocol
   - recordkeeping
@@ -16,6 +16,7 @@ tags:
 - Append a new entry to `progress.md` with what you did
 - Progress entries live in `progress.md` (reverse-chronological order, newest first with a `## <ISO 8601 timestamp>` heading). Do NOT add a `## Progress` section to `assignment.md` — that section is removed as of protocol v2.0.
 - Bump `entryCount` and `updated` in `progress.md`'s frontmatter.
+- If the change is visually or behaviorally observable, run `syntaur capture --kind <screenshot|video|asciinema|http|text> [--file <path>] [--criterion <index>] [--note <text>]` to attach a proof artifact. Linkage to a specific criterion is optional.
 
 ## When you complete an acceptance criterion:
 - Check it off in the `## Acceptance Criteria` section of `assignment.md` immediately

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntaur",
-  "version": "0.8.0",
+  "version": "0.12.0",
   "description": "Project workflow CLI with dashboard, Claude Code plugin, and Codex plugin",
   "homepage": "https://github.com/prong-horn/syntaur#readme",
   "repository": {

package/platforms/claude-code/.claude-plugin/plugin.json

@@ -17,6 +17,14 @@
     "./skills/clear-assignment",
     "./skills/save-session-summary",
     "./skills/track-session",
-    "./skills/track-server"
+    "./skills/track-server",
+    "./skills/replan",
+    "./skills/resume-session",
+    "./skills/syntaur-worktree",
+    "./skills/add-resource",
+    "./skills/add-memory",
+    "./skills/list-assignments",
+    "./skills/log-progress",
+    "./skills/set-workspace"
   ]
 }

package/platforms/claude-code/agents/syntaur-expert.md

@@ -15,7 +15,7 @@ When answering questions, read the actual source files rather than relying solel
 - **Protocol summary:** `${CLAUDE_PLUGIN_ROOT}/references/protocol-summary.md` (or `~/.claude/skills/syntaur-protocol/references/protocol-summary.md` for the installed skill version)
 - **File ownership:** `${CLAUDE_PLUGIN_ROOT}/references/file-ownership.md`
 - **Plugin manifest:** `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json`
-- **Protocol skills (installed by `syntaur install-plugin`):** `~/.claude/skills/{syntaur-protocol,grab-assignment,plan-assignment,complete-assignment,create-assignment,create-project}/`
+- **Protocol skills (installed by `syntaur install-plugin`):** `~/.claude/skills/{syntaur-protocol,grab-assignment,plan-assignment,complete-assignment,create-assignment,create-project,manage-statuses,clear-assignment,save-session-summary,track-session,track-server,replan,resume-session,syntaur-worktree,add-resource,add-memory,list-assignments,log-progress,set-workspace}/`
 - **Protocol skills source (vendored via submodule):** `<syntaur-repo>/vendor/syntaur-skills/skills/` — standalone repo at https://github.com/prong-horn/syntaur-skills
 - **Slash commands (ship in plugin):** `${CLAUDE_PLUGIN_ROOT}/commands/` — thin wrappers that invoke the corresponding installed skill
 - **Hooks:** `${CLAUDE_PLUGIN_ROOT}/hooks/`

package/platforms/claude-code/commands/add-memory/add-memory.md

@@ -0,0 +1,18 @@
+---
+name: add-memory
+description: Capture a project-level Syntaur memory under <projectDir>/memories/ via the CLI (distinct from Claude auto-memory)
+arguments:
+  - name: args
+    description: "--project <slug> --name <name> --source <text> [--scope <scope>] [--source-assignment <slug>] [--related-assignments <slug,slug>]"
+    required: false
+---
+
+# /add-memory
+
+Thin wrapper that invokes the `add-memory` skill via the Skill tool. The skill calls `syntaur memory add` and the CLI regenerates `_index.md` server-side.
+
+Distinct from the user-global Claude Code auto-memory at `~/.claude/projects/<...>/memory/MEMORY.md`. This is project-scoped Syntaur memory.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin`.

package/platforms/claude-code/commands/add-resource/add-resource.md

@@ -0,0 +1,16 @@
+---
+name: add-resource
+description: Register a project-level resource (link to dashboard, doc, ticket) under a Syntaur project
+arguments:
+  - name: args
+    description: "--project <slug> --name <name> --source <url-or-path> [--category <name>] [--related-assignments <slug,slug>] [--slug <slug>]"
+    required: false
+---
+
+# /add-resource
+
+Thin wrapper that invokes the `add-resource` skill via the Skill tool. The skill calls `syntaur resource add` and lets the CLI regenerate `_index.md`.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin`.

package/platforms/claude-code/commands/list-assignments/list-assignments.md

@@ -0,0 +1,16 @@
+---
+name: list-assignments
+description: List Syntaur assignments across projects with filters by status, project, tag, age (scriptable; not the interactive browse TUI)
+arguments:
+  - name: args
+    description: "[--status <list>] [--project <slug>] [--tag <list>] [--age <duration>] [--json]"
+    required: false
+---
+
+# /list-assignments
+
+Thin wrapper that invokes the `list-assignments` skill via the Skill tool. The skill maps user prose to `syntaur ls` flags and presents the table or JSON output.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin`.

package/platforms/claude-code/commands/log-progress/log-progress.md

@@ -0,0 +1,16 @@
+---
+name: log-progress
+description: Append a timestamped entry to the active assignment's progress.md and bump frontmatter (Keep Records Updated playbook)
+arguments:
+  - name: args
+    description: "Optional one-line summary. The skill prompts for a body if no args given."
+    required: false
+---
+
+# /log-progress
+
+Thin wrapper that invokes the `log-progress` skill via the Skill tool. Markdown-only — no CLI verb. Appends a structured timestamped entry to `<assignmentDir>/progress.md` and bumps `entryCount` + `updated`.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin`.

package/platforms/claude-code/commands/replan/replan.md

@@ -0,0 +1,16 @@
+---
+name: replan
+description: Bump the active Syntaur assignment to a new plan version (plan-vN.md) per the Plan Versioning playbook
+arguments:
+  - name: args
+    description: "Optional --assignment <slug> --project <slug>. Defaults to active assignment."
+    required: false
+---
+
+# /replan
+
+Thin wrapper that invokes the `replan` skill via the Skill tool. The skill drives `syntaur plan version` (deterministic file ops) and writes the new plan body.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin`.

package/platforms/claude-code/commands/resume-session/resume-session.md

@@ -0,0 +1,16 @@
+---
+name: resume-session
+description: Re-orient a fresh Claude Code session on the active Syntaur assignment without re-reading the full transcript
+arguments:
+  - name: args
+    description: "No arguments. Reads .syntaur/context.json and the latest sessions/<sid>/summary.md."
+    required: false
+---
+
+# /resume-session
+
+Thin wrapper that invokes the `resume-session` skill via the Skill tool. The skill calls `syntaur session resume`, reads the latest session summary and any open handoff, and reports the active context. Idempotent.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin`.

package/platforms/claude-code/commands/set-workspace/set-workspace.md

@@ -0,0 +1,16 @@
+---
+name: set-workspace
+description: Populate the four workspace.* fields in the active assignment.md per the Workspace Before Code playbook (validates via doctor first)
+arguments:
+  - name: args
+    description: "[--repository <path>] [--worktree-path <path>] [--branch <name>] [--parent-branch <name>] — auto-detects defaults from git when omitted"
+    required: false
+---
+
+# /set-workspace
+
+Thin wrapper that invokes the `set-workspace` skill via the Skill tool. The skill validates the assignment.md via `syntaur doctor --assignment <path> --json` first; refuses to write on errors. Auto-detects `repository` and `branch` from `git rev-parse` when not supplied.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin`.

package/platforms/claude-code/commands/syntaur-worktree/syntaur-worktree.md

@@ -0,0 +1,16 @@
+---
+name: syntaur-worktree
+description: Create a repo-local worktree for the active Syntaur assignment and bind the session to it (atomic create + grab)
+arguments:
+  - name: args
+    description: "--branch <name> [--repository <path>] [--parent-branch <name>] [--project <slug>] [--assignment <slug>]"
+    required: false
+---
+
+# /syntaur-worktree
+
+Thin wrapper that invokes the `syntaur-worktree` skill via the Skill tool. The skill composes `syntaur worktree create` + `syntaur assign` + `syntaur start` + writes `.syntaur/context.json`. Worktree path is always `<repository>/.worktrees/<branch>`.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin`.

package/platforms/claude-code/references/protocol-summary.md

@@ -88,3 +88,11 @@ Protocol version: **2.0**
 10. **Comments** are appended to `comments.md` via `syntaur comment <slug> "body" [--type question|note|feedback] [--reply-to <id>]`. Never edit `comments.md` directly. Questions carry a `resolved` flag.
 11. **Cross-assignment work** is requested via `syntaur request <source> <target> "text"` — appends to the target's `## Todos` annotated `(from: <source>)`.
 12. **Session continuity** (mid-assignment) lives at `sessions/<session-id>/summary.md` inside the assignment dir — one document per session id, overwritten on every save (via `/save-session-summary`). On resume, pick the latest by `summary.md` file mtime; the Claude Code SessionStart hook also stashes the absolute path in `.syntaur/context.json` as `latestSessionSummaryPath`. Older summaries accumulate as immutable history; never delete them. Distinct from `handoff.md`, which is the assignment-level cross-ticket outbound at completion. `syntaur doctor` intentionally ignores `sessions/`. The Claude Code `PreCompact` hook reminds the agent to invoke `/save-session-summary` before context is compacted.
+
+## Proof artifacts (opt-in)
+
+Agents can attach typed evidence to an assignment so a human reviewer can verify the work in seconds without re-running it.
+
+- `syntaur capture --kind <screenshot|video|asciinema|http|text> [--file <path>] [--criterion <index>] [--note <text>] [target]` — record an artifact for the active assignment. Criterion linkage is optional (0-based index into the `## Acceptance Criteria` checklist). For `--kind=text`, supply `--note` and omit `--file`.
+- `syntaur proof build [target]` — render `proof.html` and `proof.md` at the assignment dir, walking the `## Acceptance Criteria` list and embedding tagged artifacts inline beneath each criterion. Untagged or stale (out-of-range) captures land in a final "Other artifacts" section. Atomic overwrite — safe to re-run.
+- Artifacts are stored under `<assignmentDir>/proof/<criterion|untagged>/<id>.<ext>`. The DB row lives in `~/.syntaur/syntaur.db` alongside session tracking. No completion gate — proof is purely opt-in for v1.

package/platforms/claude-code/skills/add-memory/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: add-memory
+description: >-
+  Capture a project-level Syntaur memory (durable context like a convention,
+  decision rationale, or constraint) under a project's `memories/` directory.
+  Use when the user wants to "save this to memory", "remember for the project",
+  "capture this decision", "add a project memory", or pin reusable context that
+  should outlive any single assignment. Writes via the CLI so the
+  CLI-managed `_index.md` is never touched directly.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Add Memory
+
+Add a memory entry to a Syntaur project. Writes
+`<projectDir>/memories/<slug>.md` and regenerates `_index.md` server-side via
+`syntaur memory add` — the agent never edits `_index.md` directly per the
+file-ownership protocol.
+
+## When NOT to use this skill
+
+- The information is a **pointer to an external system** (URL, dashboard,
+  ticket) — use `add-resource` instead.
+- The information is the user-global Claude Code memory at
+  `~/.claude/projects/<...>/memory/MEMORY.md` — that's a different system
+  managed by the auto-memory feature, NOT Syntaur project memories.
+- The information is single-assignment scratch — put it in the assignment's
+  `scratchpad.md`.
+
+## Step 1: Resolve project
+
+If `.syntaur/context.json` is present and has `projectSlug`, default to that.
+Otherwise ask the user which project to add the memory to.
+
+## Step 2: Gather inputs
+
+Required:
+
+- `--name <human readable>` — display name for the memory.
+- `--source <text>` — where this memory came from (e.g. "conversation
+  2026-05-08", a decision-record reference, a doc URL).
+
+Optional:
+
+- `--scope <scope>` — defaults to `project`. Common values: `project`,
+  `architecture`, `policy`.
+- `--source-assignment <slug>` — assignment slug this memory was captured
+  during (helps trace the origin).
+- `--related-assignments <slug,slug,...>` — comma-separated assignment slugs
+  this memory is relevant to.
+- `--slug <slug>` — override the auto-generated kebab-case slug.
+
+## Step 3: Run `syntaur memory add`
+
+```bash
+syntaur memory add \
+  --project <project-slug> \
+  --name "<name>" \
+  --source "<text>" \
+  [--scope <scope>] \
+  [--source-assignment <slug>] \
+  [--related-assignments <slug,slug>] \
+  [--slug <slug>] \
+  [--force]
+```
+
+The CLI:
+
+1. Validates the project exists.
+2. Writes `<projectDir>/memories/<slug>.md` with the canonical frontmatter
+   (`name`, `source`, `scope`, `sourceAssignment`, `relatedAssignments`,
+   `created`, `updated`).
+3. Regenerates `<projectDir>/memories/_index.md` from the directory contents.
+4. Refuses to overwrite an existing memory without `--force`.
+
+**Do not write to `_index.md` directly under any circumstances** — that file
+is owned by the CLI per the file-ownership protocol.
+
+## Step 4: Open the new memory file (optional)
+
+If the user wants to flesh out the body content beyond the placeholder, open
+`<projectDir>/memories/<slug>.md` and edit the body. The frontmatter is
+already correct; only edit content below the second `---`.
+
+## Step 5: Report to User
+
+Summarize:
+
+- Memory slug and absolute path.
+- Project that received the memory.
+- Index regenerated (with the new total).
+- Suggested next step: edit the body to capture load-bearing context, or
+  open the dashboard to see the new entry.

package/platforms/claude-code/skills/add-resource/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: add-resource
+description: >-
+  Register a project-level resource (link to a dashboard, doc, ticket, or
+  external system) under a Syntaur project. Use when the user wants to "add a
+  resource", "save this link to the project", "track this dashboard", "add a
+  reference doc", or otherwise capture a pointer to an external system the
+  project depends on.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Add Resource
+
+Add a resource entry to a Syntaur project. Writes
+`<projectDir>/resources/<slug>.md` and regenerates `<projectDir>/resources/_index.md`
+via the CLI — the agent never edits `_index.md` directly (it is a
+CLI-managed file per the file-ownership protocol).
+
+## When NOT to use this skill
+
+- The information is **session-scoped knowledge**, not a pointer to an
+  external system — use `add-memory` instead.
+- The link is specific to a single assignment (assignment-level scratch) —
+  put it in that assignment's `scratchpad.md`.
+- The resource already exists. Read `<projectDir>/resources/_index.md` first
+  to check; pass `--force` only if you intend to overwrite.
+
+## Step 1: Resolve project
+
+If `.syntaur/context.json` is present and has `projectSlug`, default to that.
+Otherwise ask the user which project to add the resource to.
+
+## Step 2: Gather inputs
+
+Required:
+
+- `--name <human readable>` — display name for the resource.
+- `--source <url-or-path>` — the link or path to the resource itself.
+
+Optional:
+
+- `--category <name>` — short category tag (e.g. `dashboard`, `doc`,
+  `ticket`, `runbook`, `repo`).
+- `--related-assignments <slug,slug,...>` — comma-separated assignment slugs
+  this resource is relevant to.
+- `--slug <slug>` — override the auto-generated kebab-case slug.
+
+## Step 3: Run `syntaur resource add`
+
+```bash
+syntaur resource add \
+  --project <project-slug> \
+  --name "<name>" \
+  --source <url-or-path> \
+  [--category <name>] \
+  [--related-assignments <slug,slug>] \
+  [--slug <slug>] \
+  [--force]
+```
+
+The CLI:
+
+1. Validates the project exists.
+2. Writes `<projectDir>/resources/<slug>.md` with the canonical frontmatter
+   (`name`, `category`, `source`, `relatedAssignments`, `created`,
+   `updated`).
+3. Regenerates `<projectDir>/resources/_index.md` from the directory contents.
+4. Refuses to overwrite an existing resource without `--force`.
+
+## Step 4: Verify
+
+The CLI prints the slug file path and the new index size. Read both back if
+the user asked for confirmation.
+
+## Step 5: Report to User
+
+Summarize:
+
+- Resource slug and absolute path.
+- Project that received the resource.
+- Index regenerated (with the new total).
+- Suggested next step: open the dashboard or `_index.md` to see the new entry.

package/platforms/claude-code/skills/capture-artifacts/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: capture-artifacts
+description: >-
+  Capture typed proof artifacts (screenshot, video, asciinema, http transcript,
+  text note) for the active Syntaur assignment so a human reviewer can verify
+  the work in seconds without re-running it. Use after a meaningful change is
+  verified, especially when an acceptance criterion is now demonstrably met.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "0.1.0"
+---
+
+# Capture Artifacts
+
+Attach proof to your work. Reviewers should be able to scroll a single page (`proof.html`) and judge "yep that's what I wanted" or "nope that's not right" — without re-executing anything.
+
+## Input
+
+No arguments. Reads `.syntaur/context.json` from the current working directory to identify the active assignment.
+
+## Step 1: Decide whether to capture
+
+Capture an artifact when **any** of these is true:
+- An acceptance criterion is now demonstrably met (most common trigger).
+- A user-facing behavior changed in a way a screenshot, video, transcript, or short text note can show.
+- A bug fix produces a before/after worth showing (capture the after; the diff is the before).
+
+Skip when:
+- The change is purely internal (refactor, type tightening) with no observable effect.
+- The change is already covered by a passing automated test that the reviewer can run trivially.
+
+Linkage to a specific criterion is **optional**. Untagged artifacts are fine — they land in a "Other artifacts" section on the proof page.
+
+## Step 2: Pick the kind by work type
+
+| Work type | Preferred kind | Notes |
+|-----------|---------------|-------|
+| Web UI change | `screenshot` (single state) or `video` (interaction) | Use the smallest medium that conveys the proof. Screenshots beat videos when one frame suffices. |
+| CLI command output | `asciinema` (preferred) or `text` | Asciinema records the actual session; text is fine when output is short and static. |
+| Backend API change | `http` (request/response transcript) | Capture the curl invocation + response body. |
+| Migration / schema / config | `text` with a `--note` describing the before/after | Or `http` for an API verification call. |
+| Anything ambiguous | `text` with `--note` | Always available. Written notes are better than skipped captures. |
+
+## Step 3: Run `syntaur capture`
+
+```bash
+# File-based (screenshot, video, asciinema, http transcript)
+syntaur capture --kind <type> --file <path> [--criterion <index>] [--note <text>] \
+  [--project <slug> <assignment-slug>]
+
+# Text-only (no --file)
+syntaur capture --kind text --note "<what you verified>" [--criterion <index>] \
+  [--project <slug> <assignment-slug>]
+```
+
+Rules:
+- `--kind=text` requires `--note` and forbids `--file`.
+- `--kind=http` accepts either `--file` (a transcript) or `--note` (an inline summary). At least one is required.
+- All other kinds (`screenshot`, `video`, `asciinema`) require `--file`. The CLI rejects nonexistent / non-file paths.
+- `--criterion <index>` is optional — pass the **0-based** index into the `## Acceptance Criteria` checklist when you want to anchor the artifact to a specific criterion.
+- If you have a `.syntaur/context.json` in the cwd, the positional target argument is unnecessary; otherwise pass `--project <slug> <assignment-slug>` or a bare assignment UUID.
+
+The CLI copies the file (if any) under `<assignmentDir>/proof/<criterion|untagged>/<id>.<ext>` and inserts a row in `~/.syntaur/syntaur.db`. Output prints the artifact id and absolute path.
+
+## Step 4: Optional — refresh the proof page
+
+```bash
+syntaur proof build [--project <slug> <assignment-slug>]
+```
+
+This walks `## Acceptance Criteria` and renders `proof.html` + `proof.md` at the assignment dir, embedding tagged artifacts inline beneath their criteria and untagged/stale ones in a final "Other artifacts" section. Atomic overwrite — safe to re-run after every capture, or once at completion. The rendered page works in any browser; no desktop-app dependency.
+
+The `complete-assignment` skill mentions the proof page path in its final report so the reviewer can open it.
+
+## Step 5: Record the capture (per `keep-records-updated` playbook)
+
+The `keep-records-updated` playbook recommends running `syntaur capture` whenever the change is visually or behaviorally observable. Append a brief mention to `progress.md` if it adds context (e.g. "captured login-flow video against criterion 2"). Skipping a capture is fine — proof is opt-in for v1; there is no completion gate.
+
+## Notes
+
+- Artifacts are local-only in v1. Cloud upload is not available.
+- Stale `criterion_index` (e.g. when a criterion is later deleted or reordered) renders under "Other artifacts" with a "(was tagged criterion N — no longer present)" annotation. The artifact is not lost.
+- Storage stays out of git by default — `~/.syntaur/` is outside any tracked tree.

package/platforms/claude-code/skills/complete-assignment/SKILL.md

@@ -6,7 +6,7 @@ description: >-
 license: MIT
 metadata:
   author: prong-horn
-  version: "1.1.0"
+  version: "1.2.0"
 ---
 
 # Complete Assignment
@@ -143,4 +143,5 @@ Summarize:
 - Assignment slug and title
 - New status (review or completed)
 - Number of acceptance criteria met vs total
+- If `<assignmentDir>/proof.html` exists, include its absolute path so the reviewer can open it directly in a browser. Mention briefly which criteria have artifacts attached. (Proof is opt-in — its absence is not a blocker.)
 - If transitioned to `review`, a human reviewer will check the work. If any criteria were unmet, they may send it back to `in_progress`.

package/platforms/claude-code/skills/list-assignments/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: list-assignments
+description: >-
+  List Syntaur assignments across all projects with filters by status,
+  project, tag, and age. Use when the user wants to "see all assignments",
+  "list pending work", "show in_progress assignments", "what's open",
+  "find assignments tagged X", or otherwise query the cross-project board
+  non-interactively. Different from the interactive `browse` TUI — emits
+  scriptable output (table or JSON).
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# List Assignments
+
+Cross-project assignment listing using `syntaur ls`. Supports filters by
+status, project, tag, and age. Emits a compact aligned table by default;
+`--json` produces machine-readable output suitable for piping into other
+tools.
+
+## When NOT to use this skill
+
+- The user wants to interactively browse and act on assignments — use
+  `syntaur browse` (the Ink TUI) instead.
+- The user wants details for a single assignment they already know — open
+  its `assignment.md` directly.
+- The user wants project-level rollups (totals, blocked counts) — that's the
+  dashboard, not `ls`.
+
+## Step 1: Map user prose to filters
+
+Common requests → flags:
+
+- "pending assignments" → `--status pending`
+- "in-progress" / "active" → `--status in_progress`
+- "stuff blocked" → `--status blocked`
+- "everything in <project>" → `--project <slug>`
+- "tagged with X" / "labeled X" → `--tag X`
+- "must have all of X and Y" → `--tag X,Y` (AND semantics)
+- "from this week" → `--age 7d`
+- "last 24 hours" → `--age 24h`
+- "this month" → `--age 30d` (or `1m`)
+- "as JSON" / "for piping" → `--json`
+
+Multiple filters compose (intersected).
+
+## Step 2: Run `syntaur ls`
+
+```bash
+syntaur ls [--status <list>] [--project <slug>] [--tag <list>] [--age <duration>] [--json]
+```
+
+Supported `--age` units: `h` (hours), `d` (days), `w` (weeks), `m` (~30 days).
+
+## Step 3: Present results
+
+Default output is a table with columns: PROJECT, SLUG, STATUS, PRIORITY,
+ASSIGNEE, UPDATED, TITLE. If the user asked for a count or a follow-up
+action ("which one is highest priority?"), parse the table or re-run with
+`--json` and pick programmatically.
+
+## Step 4: Report to User
+
+If interactive:
+
+- Summarize the count and any obvious patterns (e.g. "5 pending in
+  syntaur-meta, 3 blocked across other projects").
+- Suggest a next action when applicable (e.g. "want to grab the top-priority
+  pending one?").
+
+If scripted (`--json`), pass the parsed JSON downstream without re-rendering.