syntaur 0.2.0 → 0.3.3

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

@@ -1,10 +1,10 @@
 ---
 name: "Keep Records Updated"
 slug: keep-records-updated
-description: "Agents must keep assignment.md progress, sessions, and criteria current in real-time"
+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-02T00:00:00Z"
+updated: "2026-04-20T00:00:00Z"
 tags:
   - protocol
   - recordkeeping
@@ -13,18 +13,24 @@ tags:
 # Keep Records Updated
 
 ## After every meaningful action:
-- Update the `## Progress` section in assignment.md with what you did
-- Use reverse-chronological order (newest first)
-- Include timestamps
+- 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.
 
 ## When you complete an acceptance criterion:
-- Check it off in the `## Acceptance Criteria` section immediately
+- Check it off in the `## Acceptance Criteria` section of `assignment.md` immediately
 - Do not batch these up -- mark them as you go
 
+## When you have a question, note, or piece of feedback:
+- Run `syntaur comment <slug-or-uuid> "body" --type question|note|feedback [--reply-to <id>]`
+- Never edit `comments.md` directly — all writes are CLI-mediated
+- Questions carry a `resolved` flag that can be toggled from the dashboard
+
 ## When starting work:
-- Add a progress entry noting you've begun and what your approach is
+- Append an entry to `progress.md` noting you've begun and what your approach is
 - If any plan files exist (plan.md, plan-v2.md, ...), update their task checkboxes as you complete steps
 
 ## When stopping or handing off:
-- Write a final progress entry summarizing current state
+- Append a final entry to `progress.md` summarizing current state
+- Write a structured handoff entry in `handoff.md`
 - Note anything the next agent needs to know

package/examples/playbooks/read-before-plan.md

@@ -4,7 +4,7 @@ slug: read-before-plan
 description: "Agents must read all project context files before creating or modifying a plan"
 when_to_use: "Before creating or modifying any plan file (plan.md, plan-v2.md, ...)"
 created: "2026-04-02T00:00:00Z"
-updated: "2026-04-02T00:00:00Z"
+updated: "2026-04-20T00:00:00Z"
 tags:
   - protocol
   - planning
@@ -14,14 +14,17 @@ tags:
 
 Before creating or modifying any plan file (plan.md, plan-v2.md, ...), read these files in order:
 
+For project-nested assignments:
 1. `manifest.md` -- understand the project structure
 2. `project.md` -- understand the goal and scope
-3. `agent.md` -- understand conventions and constraints
-4. `claude.md` (if exists) -- Claude-specific instructions
-5. `assignment.md` -- understand your specific task, acceptance criteria, and dependencies
+3. `assignment.md` -- understand your specific task, acceptance criteria, and dependencies. Frontmatter includes `project: <slug> | null` and `type: <classification> | null`.
+4. `progress.md` (if exists) -- reverse-chron log of what has been done on this assignment
+5. `comments.md` (if exists) -- open questions, notes, and feedback
 6. `handoff.md` (if exists) -- understand what previous agents did and learned
 7. `decision-record.md` (if exists) -- understand past decisions and their rationale
 
+For standalone assignments (at `~/.syntaur/assignments/<uuid>/`), skip `manifest.md` and `project.md` — those only exist for project-nested assignments.
+
 Do NOT skip files because you think you know what's in them. Context from prior agents is often critical.
 
-If the assignment has `dependsOn` entries, read those assignments too -- understand what they produced and any interfaces you need to conform to.
+If the assignment has `dependsOn` entries, read those assignments too -- and read **their** `decision-record.md` first. Upstream decisions are binding constraints you must not silently contradict. (The grab-assignment skill auto-loads these.)

package/examples/sample-project/_status.md

@@ -44,4 +44,4 @@ graph TD
 
 - **0 blocked** assignments
 - **0 failed** assignments
-- **1 unanswered** question in [implement-jwt-middleware](./assignments/implement-jwt-middleware/assignment.md)
+- **1 open** question in [implement-jwt-middleware/comments.md](./assignments/implement-jwt-middleware/comments.md)

package/examples/sample-project/assignments/design-auth-schema/assignment.md

@@ -2,6 +2,8 @@
 id: d1e2f3a4-b5c6-7890-abcd-111111111111
 slug: design-auth-schema
 title: Design Auth Database Schema
+project: build-auth-system
+type: feature
 status: completed
 priority: high
 created: "2026-03-15T09:30:00Z"
@@ -40,25 +42,10 @@ Design the PostgreSQL database schema for the authentication system. This includ
 
 This is the foundational data layer for the auth system. The schema must support the JWT middleware (implement-jwt-middleware) and be testable (write-auth-tests). See [Auth Requirements](../../resources/auth-requirements.md) for functional specs.
 
-## Questions & Answers
-
-### Q: Should we use UUIDs or auto-incrementing integers for user IDs?
-**Asked:** 2026-03-16T10:00:00Z
-**A:** Use UUIDs (v4). They avoid enumeration attacks and simplify future sharding. Generate them in the application layer, not the database.
-
-## Progress
-
-### 2026-03-17T10:00:00Z
-Completed all migration scripts and schema design. Final schema includes three tables: `users`, `sessions`, and `refresh_tokens`. Added composite index on `sessions(user_id, revoked_at)` for the active-session lookup query. All migrations tested against a clean database. Ready for handoff to JWT middleware implementation.
-
-### 2026-03-16T14:00:00Z
-Draft schema complete for users and sessions tables. Working on refresh token rotation tracking. Decided to add a `token_family` column to detect reuse of old refresh tokens.
-
-### 2026-03-16T09:30:00Z
-Started schema design. Reviewed auth requirements document. Planning three tables: users, sessions, refresh_tokens.
-
 ## Links
 
+- [Progress](./progress.md)
+- [Comments](./comments.md)
 - [Scratchpad](./scratchpad.md)
 - [Handoff](./handoff.md)
 - [Decision Record](./decision-record.md)

package/examples/sample-project/assignments/design-auth-schema/comments.md

@@ -0,0 +1,26 @@
+---
+assignment: design-auth-schema
+entryCount: 2
+generated: "2026-03-17T10:00:00Z"
+updated: "2026-03-16T10:05:00Z"
+---
+
+# Comments
+
+## c-1
+
+**Recorded:** 2026-03-16T10:00:00Z
+**Author:** claude-2
+**Type:** question
+**Resolved:** true
+
+Should we use UUIDs or auto-incrementing integers for user IDs?
+
+## c-2
+
+**Recorded:** 2026-03-16T10:05:00Z
+**Author:** human
+**Type:** note
+**Reply to:** c-1
+
+Use UUIDs (v4). They avoid enumeration attacks and simplify future sharding. Generate them in the application layer, not the database.

package/examples/sample-project/assignments/design-auth-schema/progress.md

@@ -0,0 +1,20 @@
+---
+assignment: design-auth-schema
+entryCount: 3
+generated: "2026-03-16T09:30:00Z"
+updated: "2026-03-17T10:00:00Z"
+---
+
+# Progress
+
+## 2026-03-17T10:00:00Z
+
+Completed all migration scripts and schema design. Final schema includes three tables: `users`, `sessions`, and `refresh_tokens`. Added composite index on `sessions(user_id, revoked_at)` for the active-session lookup query. All migrations tested against a clean database. Ready for handoff to JWT middleware implementation.
+
+## 2026-03-16T14:00:00Z
+
+Draft schema complete for users and sessions tables. Working on refresh token rotation tracking. Decided to add a `token_family` column to detect reuse of old refresh tokens.
+
+## 2026-03-16T09:30:00Z
+
+Started schema design. Reviewed auth requirements document. Planning three tables: users, sessions, refresh_tokens.

package/examples/sample-project/assignments/implement-jwt-middleware/assignment.md

@@ -2,6 +2,8 @@
 id: d1e2f3a4-b5c6-7890-abcd-222222222222
 slug: implement-jwt-middleware
 title: Implement JWT Authentication Middleware
+project: build-auth-system
+type: feature
 status: in_progress
 priority: high
 created: "2026-03-15T09:30:00Z"
@@ -44,25 +46,10 @@ Implement Express.js middleware that validates JWT access tokens on protected ro
 
 Depends on the database schema from [design-auth-schema](../design-auth-schema/assignment.md). The schema is complete — see the [handoff notes](../design-auth-schema/handoff.md) for integration details. Key table: `sessions` with `jti` column for token validation. See [Auth Requirements](../../resources/auth-requirements.md) for full specs.
 
-## Questions & Answers
-
-### Q: Should the refresh token endpoint require the old access token or just the refresh token?
-**Asked:** 2026-03-18T11:00:00Z
-**A:** pending
-
-## Progress
-
-### 2026-03-18T14:30:00Z
-Implemented role-based route guard middleware (`requireRole`). Working on the refresh token endpoint next. The token generation and basic validation middleware are working and passing manual tests. Need to wire up the refresh token rotation logic using the `token_family` pattern from the schema design.
-
-### 2026-03-18T10:00:00Z
-JWT validation middleware is functional. It extracts the token from the Authorization header, verifies the RS256 signature, checks expiry, and looks up the `jti` in the sessions table to confirm the session is not revoked. Added proper error responses for expired, invalid, and revoked tokens.
-
-### 2026-03-17T10:30:00Z
-Started implementation. Set up RS256 key pair loading from environment variables. Implemented `generateAccessToken` and `generateRefreshToken` functions. Created the login endpoint that authenticates with bcrypt and returns both tokens.
-
 ## Links
 
+- [Progress](./progress.md)
+- [Comments](./comments.md)
 - [Scratchpad](./scratchpad.md)
 - [Handoff](./handoff.md)
 - [Decision Record](./decision-record.md)

package/examples/sample-project/assignments/implement-jwt-middleware/comments.md

@@ -0,0 +1,17 @@
+---
+assignment: implement-jwt-middleware
+entryCount: 1
+generated: "2026-03-18T11:00:00Z"
+updated: "2026-03-18T11:00:00Z"
+---
+
+# Comments
+
+## c-1
+
+**Recorded:** 2026-03-18T11:00:00Z
+**Author:** claude-1
+**Type:** question
+**Resolved:** false
+
+Should the refresh token endpoint require the old access token or just the refresh token?

package/examples/sample-project/assignments/implement-jwt-middleware/progress.md

@@ -0,0 +1,20 @@
+---
+assignment: implement-jwt-middleware
+entryCount: 3
+generated: "2026-03-17T10:30:00Z"
+updated: "2026-03-18T14:30:00Z"
+---
+
+# Progress
+
+## 2026-03-18T14:30:00Z
+
+Implemented role-based route guard middleware (`requireRole`). Working on the refresh token endpoint next. The token generation and basic validation middleware are working and passing manual tests. Need to wire up the refresh token rotation logic using the `token_family` pattern from the schema design.
+
+## 2026-03-18T10:00:00Z
+
+JWT validation middleware is functional. It extracts the token from the Authorization header, verifies the RS256 signature, checks expiry, and looks up the `jti` in the sessions table to confirm the session is not revoked. Added proper error responses for expired, invalid, and revoked tokens.
+
+## 2026-03-17T10:30:00Z
+
+Started implementation. Set up RS256 key pair loading from environment variables. Implemented `generateAccessToken` and `generateRefreshToken` functions. Created the login endpoint that authenticates with bcrypt and returns both tokens.

package/examples/sample-project/assignments/write-auth-tests/assignment.md

@@ -2,6 +2,8 @@
 id: d1e2f3a4-b5c6-7890-abcd-333333333333
 slug: write-auth-tests
 title: Write Auth System Tests
+project: build-auth-system
+type: feature
 status: pending
 priority: medium
 created: "2026-03-15T09:30:00Z"
@@ -42,16 +44,10 @@ Write comprehensive unit and integration tests for the authentication system, co
 
 This assignment depends on [implement-jwt-middleware](../implement-jwt-middleware/assignment.md) being completed. Tests will cover both the schema layer (from design-auth-schema) and the middleware/endpoint layer (from implement-jwt-middleware). Use Jest as the test framework with `supertest` for HTTP integration tests.
 
-## Questions & Answers
-
-No questions yet.
-
-## Progress
-
-No progress yet.
-
 ## Links
 
+- [Progress](./progress.md)
+- [Comments](./comments.md)
 - [Scratchpad](./scratchpad.md)
 - [Handoff](./handoff.md)
 - [Decision Record](./decision-record.md)

package/examples/sample-project/assignments/write-auth-tests/comments.md

@@ -0,0 +1,10 @@
+---
+assignment: write-auth-tests
+entryCount: 0
+generated: "2026-03-15T09:30:00Z"
+updated: "2026-03-15T09:30:00Z"
+---
+
+# Comments
+
+No comments yet.

package/examples/sample-project/assignments/write-auth-tests/progress.md

@@ -0,0 +1,10 @@
+---
+assignment: write-auth-tests
+entryCount: 0
+generated: "2026-03-15T09:30:00Z"
+updated: "2026-03-15T09:30:00Z"
+---
+
+# Progress
+
+No progress yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntaur",
-  "version": "0.2.0",
+  "version": "0.3.3",
   "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

@@ -5,5 +5,9 @@
     "name": "Brennen",
     "email": ""
   },
-  "version": "0.1.7"
+  "version": "0.1.8",
+  "statusLine": {
+    "type": "command",
+    "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/statusline.sh"
+  }
 }

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

@@ -46,8 +46,6 @@ Syntaur is a **markdown-based, filesystem-hosted protocol** that coordinates wor
     <project-slug>/
       manifest.md                    # Derived: root navigation
       project.md                     # Human-authored: goal, context, success criteria
-      agent.md                       # Human-authored: universal agent instructions
-      claude.md                      # Human-authored: Claude Code-specific instructions
       _index-assignments.md          # Derived: assignment summary table
       _index-plans.md                # Derived: plan status summary
       _index-decisions.md            # Derived: decision record summary
@@ -56,6 +54,8 @@ Syntaur is a **markdown-based, filesystem-hosted protocol** that coordinates wor
         <assignment-slug>/
           assignment.md              # Agent-writable: source of truth for state (includes ## Todos)
           plan*.md                   # Agent-writable: versioned implementation plans (0+, optional)
+          progress.md                # Agent-writable, append-only: timestamped progress log
+          comments.md                # CLI-mediated: threaded questions/notes/feedback (via `syntaur comment`)
           scratchpad.md              # Agent-writable: working notes
           handoff.md                 # Agent-writable: append-only handoff log
           decision-record.md         # Agent-writable: append-only decision log
@@ -65,6 +65,15 @@ Syntaur is a **markdown-based, filesystem-hosted protocol** that coordinates wor
       memories/
         _index.md                    # Derived
         <memory-slug>.md             # Shared-writable
+  assignments/
+    <assignment-id>/                 # Standalone assignments — folder = UUID, project: null, slug display-only
+      assignment.md
+      plan*.md
+      progress.md
+      comments.md
+      scratchpad.md
+      handoff.md
+      decision-record.md
 ```
 
 ---
@@ -73,18 +82,21 @@ Syntaur is a **markdown-based, filesystem-hosted protocol** that coordinates wor
 
 ### Human-Authored (READ-ONLY for agents)
 - `project.md` — project overview, goal, context, success criteria
-- `agent.md` — universal agent instructions
-- `claude.md` — Claude Code-specific instructions
 
 ### Agent-Writable (single-writer per assignment)
-- `assignment.md` — source of truth for assignment state (includes `## Todos` checklist)
+- `assignment.md` — source of truth for assignment state (includes `## Todos` checklist). `## Todos` is also the landing spot for cross-assignment requests.
 - `plan*.md` — versioned implementation plans (optional, one per `## Todos` entry: `plan.md`, `plan-v2.md`, ...)
+- `progress.md` — append-only timestamped progress log (newest first). Replaces the old `## Progress` body section.
 - `scratchpad.md` — unstructured working notes
 - `handoff.md` — append-only handoff log
 - `decision-record.md` — append-only decision log
 
 Only the assigned agent may write to its own assignment folder.
 
+### CLI-Mediated Shared-Writable
+- `comments.md` — threaded questions/notes/feedback. Writes via `syntaur comment <slug-or-uuid> "body" --type question|note|feedback [--reply-to <id>]`. Never edit directly.
+- Another assignment's `## Todos` — writes via `syntaur request <source> <target> "text"`. Appends annotated `(from: <source>)`.
+
 ### Shared-Writable (any agent or human)
 - `resources/<slug>.md` — reference material
 - `memories/<slug>.md` — learnings discovered
@@ -155,8 +167,14 @@ Only the assigned agent may write to its own assignment folder.
 | Command | Description |
 |---------|-------------|
 | `syntaur create-project <title> [--slug S] [--dir D]` | Create new project with full scaffolding |
-| `syntaur create-assignment <title> --project M [--priority P] [--depends-on D] [--slug S]` | Create assignment in a project |
-| `syntaur create-assignment <title> --one-off` | Create standalone one-off assignment |
+| `syntaur create-assignment <title> --project M [--priority P] [--depends-on D] [--slug S] [--type T]` | Create assignment in a project |
+| `syntaur create-assignment <title> --one-off [--type T]` | Create standalone assignment at `~/.syntaur/assignments/<uuid>/` (project: null, slug display-only) |
+
+### Coordination (CLI-mediated writes)
+| Command | Description |
+|---------|-------------|
+| `syntaur comment <slug-or-uuid> "body" --type question\|note\|feedback [--reply-to <id>] [--project <slug>]` | Append to `comments.md`. Questions carry a resolve flag toggleable in the dashboard. |
+| `syntaur request <target> "text" [--from <source>] [--project <slug>]` | Append a todo to another assignment's `## Todos`, annotated `(from: <source>)`. |
 
 ### State Transitions
 | Command | Description |
@@ -173,7 +191,7 @@ Only the assigned agent may write to its own assignment folder.
 ### Session Tracking
 | Command | Description |
 |---------|-------------|
-| `syntaur track-session --project M --assignment A --agent N` | Register agent session |
+| `syntaur track-session --project M --assignment A --agent N --session-id <real-id> --transcript-path <path>` | Register agent session. `--session-id` is required and must be the agent runtime's real id (Claude: `~/.claude/sessions/<pid>.json` or SessionStart hook payload; Codex: `payload.id` from `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`). Do not synthesize. |
 
 All commands support `--dir <path>` to override the default `~/.syntaur/projects/` directory.
 
@@ -200,6 +218,7 @@ plugin/
     track-session/track-session.md  # Register tmux sessions
   hooks/
     hooks.json                   # Hook definitions
+    session-start.sh             # Merge real session_id + transcript_path into existing .syntaur/context.json
     session-cleanup.sh           # Mark sessions stopped on exit
     enforce-boundaries.sh        # Write boundary enforcement
   references/
@@ -223,6 +242,7 @@ plugin/
 | Hook | Event | Behavior |
 |------|-------|----------|
 | PostToolUse: ExitPlanMode | User exits plan mode | Prompts to write the plan to the next unused `plan-v<N>.md` (or `plan.md` if none exists) and append a linked todo in the `## Todos` section of `assignment.md` |
+| SessionStart | Claude Code session starts | Runs session-start.sh to merge the real `session_id` + `transcript_path` into an EXISTING `.syntaur/context.json`. Does nothing if context.json is absent (no active assignment). |
 | SessionEnd | Claude Code session exits | Runs session-cleanup.sh to mark session as stopped |
 | PreToolUse: enforce-boundaries | Edit/Write/MultiEdit | Validates target path is within assignment boundaries |
 
@@ -295,10 +315,14 @@ Adapters embed protocol knowledge (write boundaries, lifecycle states, CLI comma
 
 ### Frontmatter Fields by File Type
 
-**assignment.md:** id, slug, title, status, priority, created, updated, assignee, externalIds, dependsOn, blockedReason, workspace (repository, worktreePath, branch, parentBranch), tags
+**assignment.md:** id, slug, title, **project (slug or null)**, **type (string or null)**, status, priority, created, updated, assignee, externalIds, dependsOn, blockedReason, workspace (repository, worktreePath, branch, parentBranch), tags
 
 **plan files (plan.md, plan-v2.md, ...):** assignment, status (draft/approved/in_progress/completed), created, updated — zero or more per assignment, each linked from a todo in `assignment.md`'s `## Todos` section
 
+**progress.md:** assignment, entryCount, generated, updated — body is reverse-chron `## <timestamp>` entries
+
+**comments.md:** assignment, entryCount, generated, updated — body entries are `## <id>` with structured metadata lines (Recorded, Author, Type, optional Reply to, optional Resolved)
+
 **handoff.md:** assignment, updated, handoffCount
 
 **decision-record.md:** assignment, updated, decisionCount
@@ -307,13 +331,13 @@ Adapters embed protocol knowledge (write boundaries, lifecycle states, CLI comma
 
 **manifest.md:** version, project, generated
 
-**_status.md:** project, generated, status, progress (total/completed/in_progress/blocked/pending/review/failed), needsAttention (blockedCount/failedCount/unansweredQuestions)
+**_status.md:** project, generated, status, progress (total/completed/in_progress/blocked/pending/review/failed), needsAttention (blockedCount/failedCount/**openQuestions**). `openQuestions` is counted from every assignment's `comments.md` (entries where `Type: question` and `Resolved: false` or absent).
 
 ### Conventions
 - **Timestamps:** RFC 3339 / ISO 8601 with UTC: `2026-03-18T14:30:00Z`
 - **Paths:** Absolute expanded form in YAML (never `~`), relative in markdown links
-- **Slugs:** Lowercase, hyphen-separated, match folder names
-- **Protocol version:** `"1.0"` (string, not number)
+- **Slugs:** Lowercase, hyphen-separated, match folder names (project-nested). For standalone assignments, the folder is named by UUID and `slug` is display-only.
+- **Protocol version:** `"2.0"` (string, not number)
 
 ---
 
@@ -348,7 +372,7 @@ syntaur dashboard
 
 ## Context File (.syntaur/context.json)
 
-Created by `/grab-assignment` in the current working directory. Contains:
+Created by `/grab-assignment` in the current working directory. The SessionStart hook merges `sessionId` / `transcriptPath` into this file on each Claude Code session start — it never creates the file, only enriches an existing one. Contents:
 ```json
 {
   "projectSlug": "my-first-project",
@@ -359,7 +383,8 @@ Created by `/grab-assignment` in the current working directory. Contains:
   "title": "Design the schema",
   "branch": "feature/design-the-schema",
   "grabbedAt": "2026-03-18T14:30:00Z",
-  "sessionId": "uuid-v4"
+  "sessionId": "<real-claude-session-id>",
+  "transcriptPath": "/Users/you/.claude/projects/<encoded-cwd>/<session-id>.jsonl"
 }
 ```
 
@@ -376,7 +401,13 @@ A: Use `/grab-assignment <project-slug>` — it lists pending assignments. Or ch
 A: No. Single-writer guarantee — one agent per assignment folder. Use separate assignments for parallel work.
 
 **Q: What if I need to ask the human a question?**
-A: Add it to the Q&A section of assignment.md. Do NOT set status to `blocked` for questions — `blocked` is for runtime obstacles only.
+A: Run `syntaur comment <slug> "question text" --type question`. It appends to `comments.md`, which replaces the old `## Questions & Answers` body section. The question rolls up into `_status.md`'s `openQuestions` counter and shows on the dashboard. Do NOT set status to `blocked` for questions — `blocked` is for runtime obstacles only.
+
+**Q: What goes in `progress.md` vs `handoff.md`?**
+A: `progress.md` is a continuous reverse-chron log of what you've done — append an entry per meaningful work unit. `handoff.md` is only written when you hand off work (to another agent or human), and summarizes the state at that transition.
+
+**Q: How do I route work to another assignment without breaking the single-writer rule?**
+A: Run `syntaur request <target> "text"` — it appends a todo to the target's `## Todos` annotated `(from: <source>)`. This is a CLI-mediated exception to the single-writer rule.
 
 **Q: How do indexes get updated?**
 A: Derived files are rebuilt by tooling. They are projections of assignment frontmatter. When divergence occurs, re-run rebuild.

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

@@ -11,6 +11,8 @@ arguments:
 
 Register the current Claude Code session as an agent session in the Syntaur dashboard. Works standalone or linked to a project/assignment.
 
+Only real Claude Code session IDs are accepted — no synthesis. The real id is written to `.syntaur/context.json` by the SessionStart hook, with `~/.claude/sessions/<pid>.json` as the fallback source.
+
 ## Usage
 
 - `/track-session` — register a standalone session
@@ -29,37 +31,60 @@ Extract optional flags from the argument string:
 - `--project <slug>` — project to link to
 - `--assignment <slug>` — assignment to link to
 
-### Step 2: Run the CLI command
+### Step 2: Source the real session id + transcript path
+
+In priority order:
+
+1. Read `.syntaur/context.json` if present. If it contains `sessionId`, use it. Also pick up `transcriptPath` if present.
+2. Otherwise, read the most-recently-modified file under `~/.claude/sessions/*.json` whose `cwd` matches `$(pwd)` and use its `sessionId` field. The transcript path is conventionally `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`; include it if the file exists, otherwise omit.
+3. If neither source yields an id, abort with: "Could not resolve a real Claude Code session id. Restart the Claude session so the SessionStart hook can populate `.syntaur/context.json`, or run `/rename <slug>` then try again."
+
+DO NOT generate a UUID. `syntaur track-session` rejects missing session IDs.
 
-Run the track-session CLI command via Bash (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`):
+### Step 3: Run the CLI command
+
+Run the track-session CLI via Bash (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`):
 
 ```bash
-syntaur track-session --agent claude --path $(pwd) [--description "<text>"] [--project <slug>] [--assignment <slug>]
+syntaur track-session \
+  --agent claude \
+  --session-id "$SESSION_ID" \
+  --transcript-path "$TRANSCRIPT_PATH" \
+  --path "$(pwd)" \
+  [--description "<text>"] \
+  [--project <slug>] \
+  [--assignment <slug>]
 ```
 
-### Step 3: Parse the session ID
+Omit `--transcript-path` entirely (don't pass an empty string) if no transcript path could be resolved.
 
-The CLI output will be one of:
+The CLI prints one of:
 - `Registered standalone agent session <sessionId>.`
 - `Registered agent session <sessionId> for <assignment> in <project>.`
 
-Extract the session ID from the output.
+Registration is idempotent — re-running the command with the same session id safely upserts project/assignment/description onto the existing row.
 
-### Step 4: Write context file
+### Step 4: Merge context.json
 
-Write the session ID to `.syntaur/context.json` so the SessionEnd hook can mark it stopped when this conversation ends:
+Ensure `.syntaur/context.json` has the session fields (so SessionEnd and future `/track-session` runs find them). Merge, don't overwrite:
 
-- If `.syntaur/context.json` already exists, read it and add `"sessionId": "<id>"` to the existing JSON
-- If it doesn't exist, create the `.syntaur/` directory and write:
-  ```json
-  {
-    "sessionId": "<id>"
-  }
-  ```
+```bash
+mkdir -p .syntaur
+if [ -f .syntaur/context.json ]; then
+  jq --arg sid "$SESSION_ID" --arg tp "$TRANSCRIPT_PATH" \
+    '. + {sessionId: $sid} + (if ($tp | length) > 0 then {transcriptPath: $tp} else {} end)' \
+    .syntaur/context.json > .syntaur/context.json.tmp \
+    && mv .syntaur/context.json.tmp .syntaur/context.json
+else
+  jq -n --arg sid "$SESSION_ID" --arg tp "$TRANSCRIPT_PATH" \
+    '{sessionId: $sid} + (if ($tp | length) > 0 then {transcriptPath: $tp} else {} end)' \
+    > .syntaur/context.json
+fi
+```
 
 ### Step 5: Confirm
 
 Tell the user:
-- The session was registered (include the short session ID)
-- It will be auto-stopped when this conversation ends
-- If linked to a project, mention which project/assignment
+- The session was registered (include the short session id).
+- It will be auto-stopped when this conversation ends via the SessionEnd hook.
+- If linked to a project, mention which project/assignment.

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

@@ -12,6 +12,17 @@
         ]
       }
     ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [