From 80b2e1cc36e8c6b27ade7af0f8946f403a8166fb Mon Sep 17 00:00:00 2001
From: Andy Pai <andy@r2pi.co>
Date: Fri, 20 Mar 2026 18:36:56 -0400
Subject: [PATCH 1/9] feat: add activity log command

---
 README.md                          |  51 +++++-
 SKILL.md                           | 114 ++++++++++---
 specs/001-log-command/tasks.md     | 157 ++++++++++++++++++
 src/commands/activity-log.test.ts  | 150 +++++++++++++++++
 src/commands/activity-log.ts       | 192 ++++++++++++++++++++++
 src/commands/activity-show.ts      |  24 +--
 src/commands/activity.ts           |   1 +
 src/commands/formatters.ts         |  20 ++-
 src/commands/index.ts              |   3 +-
 src/commands/types.ts              |   5 +
 src/session/index.ts               |   3 +
 src/session/time-bucketing.test.ts | 256 +++++++++++++++++++++++++++++
 src/session/time-bucketing.ts      | 149 +++++++++++++++++
 src/session/types.ts               |   9 +
 src/utils/time.ts                  |   4 +-
 src/wildcard.ts                    |  15 ++
 16 files changed, 1111 insertions(+), 42 deletions(-)
 create mode 100644 specs/001-log-command/tasks.md
 create mode 100644 src/commands/activity-log.test.ts
 create mode 100644 src/commands/activity-log.ts
 create mode 100644 src/session/time-bucketing.test.ts
 create mode 100644 src/session/time-bucketing.ts

diff --git a/README.md b/README.md
index 41b694e..fc481e8 100644
--- a/README.md
+++ b/README.md
@@ -6,11 +6,13 @@ The built-in `watch` pipeline captures file changes as `edit` events. The event
 
 Status: early alpha. Expect breaking changes while the data model and UX settle.
 
+For implementation details, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). For the operator-focused reporting workflow used by AI agents, see [SKILL.md](SKILL.md).
+
 ## Requirements
 
 - Bun 1.3.8
 - macOS or Linux (Windows is not supported; use WSL2 if needed)
-- Optional: Ollama or OpenAI-compatible API for AI summaries
+- Optional: Ollama, OpenAI, or Gemini for AI summaries
 
 ## Install / Run From Source
 
@@ -36,21 +38,29 @@ wildcard watch --roots ~/Projects --daemon
 # Show today's sessions
 wildcard show today
 
+# Show chronological activity log (today by default)
+wildcard log
+wildcard log week
+
 # Generate a weekly report
 wildcard report week
 
+# Push pending local data to a central ingest server
+wildcard sync push
+
 # Search the timeline
 wildcard search "config" --from 2025-01-01 --to 2025-01-31 --types edit,ocr
 
 # Check daemon status
 wildcard status
+wildcard status --json
 
 # macOS: install/uninstall launchd service
 wildcard install-launchd --roots ~/Projects
 wildcard uninstall-launchd
 wildcard restart
 
-# Prune cached summaries
+# Prune old local data
 wildcard prune --older-than 30
 ```
 
@@ -71,13 +81,17 @@ Event types:
 
 Useful flags:
 
-- `show` / `report`: `--force-refresh` to bypass summary cache
+- `show`, `log`, `report`, `search`: `--device <ids>` to filter multi-device data
+- `report`: `--force-refresh` to bypass summary cache
 - `report`: `--no-ai` to force heuristic summaries
+- `report`: `--no-progress` to keep stdout clean for piping or file capture
+- `log`: `--json` for machine-readable output
+- `status`: `--json` for machine-readable output
 - `watch`: `--memlog`, `--mem-warn-mb`, `--mem-limit-mb` for memory logging/guards
 
 ## Configuration
 
-Default config path: `~/.wildcard/config.yaml`. Data lives under `~/.wildcard/` by default.
+Default config path: `~/.wildcard/config.yaml`. Data lives under `~/.wildcard/` by default. Defaults come from `src/config/config-store.ts`; the example below shows the most relevant fields rather than every compatibility knob.
 
 ```yaml
 store_dir: ~/.wildcard
@@ -98,14 +112,26 @@ watch:
   checkpoint_interval_s: 60
 
 session:
-  idle_threshold_s: 20
-  activity_window_s: 20
+  idle_threshold_s: 300
+  activity_window_s: 120
 
 ai:
   enabled: false
   provider: ollama
   model: llama3.2
   base_url: http://localhost:11434
+
+identity:
+  device_id: laptop
+
+sync:
+  enabled: false
+  server_url: http://localhost:3000
+  batch_size: 500
+  max_payload_bytes: 2097152
+  interval_s: 300
+  max_retries: 8
+  batch_delay_ms: 0
 ```
 
 Environment variables:
@@ -118,8 +144,19 @@ Environment variables:
 - `WILDCARD_AI_MODEL`
 - `WILDCARD_AI_BASE_URL`
 - `WILDCARD_AI_API_KEY` (fallbacks: `OPENAI_API_KEY` for OpenAI, `GEMINI_API_KEY` for Gemini)
+- `WILDCARD_DEVICE_ID`
+- `WILDCARD_SYNC_ENABLED`
+- `WILDCARD_SYNC_SERVER_URL`
+- `WILDCARD_SYNC_API_KEY`
+- `WILDCARD_SYNC_BATCH_SIZE`
+- `WILDCARD_SYNC_MAX_PAYLOAD_BYTES`
+- `WILDCARD_SYNC_INTERVAL_S`
+- `WILDCARD_SYNC_MAX_RETRIES`
+- `WILDCARD_SYNC_BATCH_DELAY_MS`
 - `WILDCARD_DEBUG_OSASCRIPT` (`1` to log frontmost-app AppleScript stderr/debug details)
 
+AI summary prompt templates live in `src/summary/prompts/*.md`. The markdown files hold the stable system instructions, while runtime session/project data is still assembled in code.
+
 ## Data Locations
 
 - `~/.wildcard/timeline.db` (SQLite timeline)
@@ -152,7 +189,7 @@ bun run sync-shutdown-test
 
 ## Security and Privacy
 
-Wildcard stores activity data locally by default. If you enable AI providers, data may be sent to those services depending on your config. Review `SECURITY.md` for reporting vulnerabilities.
+Wildcard stores activity data locally by default. If you enable AI providers or remote sync, data may be sent to those services depending on your config. Review [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
 
 ## License
 
diff --git a/SKILL.md b/SKILL.md
index 92791e6..9881f13 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -10,16 +10,19 @@ Wildcard is a local-first CLI that captures file activity into a SQLite timeline
 
 The tool is designed for personal developer workflows: start a watcher, work normally, then review what you did with `show`, `report`, or `search`.
 
+For general installation and operator-facing usage, see [README.md](README.md). For implementation details and source-of-truth architecture notes, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
 ## When to Use This Skill
 
 Use this skill when the user wants to:
 
 - **Start watching** file activity (`watch`)
 - **Check daemon status** (`status`)
-- **View sessions** for a time period (`show`)
+- **View sessions** for a time period (`show`, `log`)
 - **Generate reports** with optional AI summaries (`report`)
 - **Search the timeline** for past activity (`search`)
 - **Configure** wildcard (config.yaml, env vars)
+- **Push local data upstream** (`sync push`)
 - **Manage the macOS daemon** (install/uninstall launchd, restart)
 - **Maintain data** (prune old data, archive to another DB)
 - **Troubleshoot** issues (daemon not running, stale PID, AI not working)
@@ -85,6 +88,28 @@ wildcard show week
 
 The period can also be passed as a flag: `wildcard show --today`, `--yesterday`, or `--week`.
 
+### log — View chronological activity log
+
+Display activity broken down by time slot — hourly for today/yesterday, daily for week.
+
+```bash
+wildcard log
+wildcard log today
+wildcard log yesterday
+wildcard log week
+```
+
+The period can also be passed as a flag: `wildcard log --today`, `--yesterday`, or `--week`.
+
+**Difference from `show`**: `log` is time-first (each time slot lists the projects active in it), while `show` is project-first (each project shows its total time). Use `log` to answer "what was I doing at 2pm?"; use `show` to answer "how much time did I spend on each project?"
+
+**Flags:**
+
+| Flag             | Description                             |
+| ---------------- | --------------------------------------- |
+| `--device <ids>` | Filter by device ID(s), comma-separated |
+| `--json`         | Output machine-readable JSON            |
+
 ### report — Generate summary reports
 
 Generate heuristic or AI-powered reports for a time period.
@@ -109,10 +134,12 @@ wildcard report yesterday --no-progress
 
 **Flags:**
 
-| Flag              | Description                         |
-| ----------------- | ----------------------------------- |
-| `--no-ai`         | Force heuristic summaries           |
-| `--force-refresh` | Bypass summary cache and regenerate |
+| Flag              | Description                             |
+| ----------------- | --------------------------------------- |
+| `--no-ai`         | Force heuristic summaries               |
+| `--force-refresh` | Bypass summary cache and regenerate     |
+| `--device <ids>`  | Filter by device ID(s), comma-separated |
+| `--no-progress`   | Disable progress output on stderr       |
 
 ## Context-Enriched Reporting Workflow
 
@@ -171,6 +198,7 @@ Use this structure for each major project in enriched reports:
 
 ```md
 ### <project> - <time> - <edits/files>
+
 - What this project is: ...
 - What changed (key files only): ...
 - Likely impact: ...
@@ -218,6 +246,7 @@ wildcard search "meeting" --types audio,ocr
 
 ```bash
 wildcard status
+wildcard status --json
 ```
 
 Shows whether the daemon is running, its PID, and the last event timestamp.
@@ -230,6 +259,14 @@ wildcard setup
 
 Walks through initial configuration interactively.
 
+### sync push — Upload pending local data
+
+```bash
+wildcard sync push
+```
+
+Use this when `sync.server_url` is configured and you want to push local `events` plus `app_usage` rows to a central ingest server. For reliable multi-device sync, set `identity.device_id` explicitly.
+
 ## macOS Daemon Management
 
 ### Install LaunchAgent
@@ -271,7 +308,7 @@ tail -f ~/.wildcard/launchd.err.log   # stderr
 
 ## Configuration
 
-Default config path: `~/.wildcard/config.yaml`
+Default config path: `~/.wildcard/config.yaml`. Defaults come from `src/config/config-store.ts`; the example below focuses on the fields users most commonly change.
 
 ```yaml
 store_dir: ~/.wildcard
@@ -292,29 +329,50 @@ watch:
   checkpoint_interval_s: 60
 
 session:
-  idle_threshold_s: 20
-  activity_window_s: 20
+  idle_threshold_s: 300
+  activity_window_s: 120
 
 ai:
   enabled: false
   provider: ollama
   model: llama3.2
   base_url: http://localhost:11434
+
+identity:
+  device_id: laptop
+
+sync:
+  enabled: false
+  server_url: http://localhost:3000
+  batch_size: 500
+  max_payload_bytes: 2097152
+  interval_s: 300
+  max_retries: 8
+  batch_delay_ms: 0
 ```
 
 ### Environment variable overrides
 
-| Variable                   | Description                            |
-| -------------------------- | -------------------------------------- |
-| `WILDCARD_STORE_DIR`       | Override data directory                |
-| `WILDCARD_CONFIG_PATH`     | Override config file path              |
-| `WILDCARD_WATCH_ROOTS`     | Comma-separated watch roots            |
-| `WILDCARD_AI_ENABLED`      | Enable/disable AI (`true`/`false`)     |
-| `WILDCARD_AI_PROVIDER`     | `ollama` or `openai`                   |
-| `WILDCARD_AI_MODEL`        | Model name                             |
-| `WILDCARD_AI_BASE_URL`     | Provider base URL                      |
-| `WILDCARD_AI_API_KEY`      | API key (also reads `OPENAI_API_KEY`)  |
-| `WILDCARD_DEBUG_OSASCRIPT` | `1` to log frontmost-app debug details |
+| Variable                          | Description                                               |
+| --------------------------------- | --------------------------------------------------------- |
+| `WILDCARD_STORE_DIR`              | Override data directory                                   |
+| `WILDCARD_CONFIG_PATH`            | Override config file path                                 |
+| `WILDCARD_WATCH_ROOTS`            | Comma-separated watch roots                               |
+| `WILDCARD_AI_ENABLED`             | Enable/disable AI (`true`/`false`)                        |
+| `WILDCARD_AI_PROVIDER`            | `ollama`, `openai`, or `gemini`                           |
+| `WILDCARD_AI_MODEL`               | Model name                                                |
+| `WILDCARD_AI_BASE_URL`            | Provider base URL                                         |
+| `WILDCARD_AI_API_KEY`             | API key (also reads `OPENAI_API_KEY` or `GEMINI_API_KEY`) |
+| `WILDCARD_DEVICE_ID`              | Override `identity.device_id`                             |
+| `WILDCARD_SYNC_ENABLED`           | Enable/disable sync                                       |
+| `WILDCARD_SYNC_SERVER_URL`        | Sync server base URL                                      |
+| `WILDCARD_SYNC_API_KEY`           | Sync bearer token                                         |
+| `WILDCARD_SYNC_BATCH_SIZE`        | Max rows per sync batch                                   |
+| `WILDCARD_SYNC_MAX_PAYLOAD_BYTES` | Max sync payload size in bytes                            |
+| `WILDCARD_SYNC_INTERVAL_S`        | Periodic sync interval in seconds                         |
+| `WILDCARD_SYNC_MAX_RETRIES`       | Max upload retries                                        |
+| `WILDCARD_SYNC_BATCH_DELAY_MS`    | Delay between sync batches in ms                          |
+| `WILDCARD_DEBUG_OSASCRIPT`        | `1` to log frontmost-app debug details                    |
 
 ## Data Management
 
@@ -367,12 +425,24 @@ Requires Ollama running locally: `ollama pull llama3.2`
 ai:
   enabled: true
   provider: openai
-  model: gpt-4o-mini
+  model: gpt-5.4-mini
   api_key: sk-your-key-here
 ```
 
 Or via environment: `export OPENAI_API_KEY=sk-...`
 
+### Gemini
+
+```yaml
+ai:
+  enabled: true
+  provider: gemini
+  model: gemini-3.1-flash-lite-preview
+  api_key: AI...
+```
+
+Or via environment: `export GEMINI_API_KEY=AI...`
+
 ## Troubleshooting
 
 ### "No sessions" when running show/report
@@ -428,14 +498,18 @@ wildcard install-launchd --roots ~/Projects
 | `wildcard watch --roots <paths>`                   | Start file watcher (foreground)      |
 | `wildcard watch --daemon`                          | Start as background daemon           |
 | `wildcard status`                                  | Show daemon status                   |
+| `wildcard status --json`                           | Show machine-readable status         |
 | `wildcard show today\|yesterday\|week`             | List sessions for a period           |
+| `wildcard log today\|yesterday\|week`              | Show chronological activity log      |
 | `wildcard report today\|yesterday\|week`           | Generate summary report              |
 | `wildcard report --no-ai`                          | Report with heuristic summaries only |
 | `wildcard report --force-refresh`                  | Regenerate summaries (bypass cache)  |
+| `wildcard report --no-progress`                    | Suppress progress output on stderr   |
 | `wildcard search "query"`                          | Full-text search                     |
 | `wildcard search "q" --from <iso> --to <iso>`      | Search with time range               |
 | `wildcard search "q" --types edit,ocr`             | Search by event type                 |
 | `wildcard setup`                                   | Interactive first-time setup         |
+| `wildcard sync push`                               | Push pending local data upstream     |
 | `wildcard install-launchd --roots <paths>`         | Install macOS LaunchAgent            |
 | `wildcard uninstall-launchd`                       | Remove macOS LaunchAgent             |
 | `wildcard restart`                                 | Restart LaunchAgent service          |
diff --git a/specs/001-log-command/tasks.md b/specs/001-log-command/tasks.md
new file mode 100644
index 0000000..a1d5076
--- /dev/null
+++ b/specs/001-log-command/tasks.md
@@ -0,0 +1,157 @@
+# Tasks: Log Command
+
+**Input**: Design documents from `/specs/001-log-command/`
+**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/
+
+**Tests**: Included — plan.md and quickstart.md specify `time-bucketing.test.ts`.
+
+**Organization**: Tasks grouped by user story for independent implementation and testing.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Phase 1: Setup
+
+**Purpose**: No new project initialization — the project already exists. This phase adds shared types needed across all stories.
+
+- [x] T001 Add `LogOptions` type to `src/commands/types.ts` — define `PeriodFlags & { device?: string; json?: boolean }`
+- [x] T002 [P] Add `SessionFragment` and `SlotProjectEntry` types to `src/session/time-bucketing.ts` — per data-model.md entity definitions
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: The time-bucketing utility is required by ALL user stories. Must complete before any story begins.
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+### Tests
+
+- [x] T003 Write unit tests for `bucketSessionsByTime()` and `groupFragmentsByProject()` in `src/session/time-bucketing.test.ts` — cover: single session in one bucket, session spanning hour boundary (proportional split, edits assigned to start slot), zero-duration session, multiple sessions across multiple buckets, session exactly at bucket boundary, daily bucket size. For `groupFragmentsByProject()`: correct project keying with fallback chain (`root ?? name ?? 'unknown'`), multi-branch accumulation within a slot, duration-descending sort order
+
+### Implementation
+
+- [x] T004 Implement `bucketSessionsByTime(sessions, bucketSizeMs, range)` in `src/session/time-bucketing.ts` — returns `Map<number, SessionFragment[]>` per research.md R-002. Generate bucket boundaries from range, split sessions crossing boundaries proportionally, assign edits to start-slot fragment per research.md R-001
+- [x] T005 Implement `groupFragmentsByProject(fragments)` helper in `src/session/time-bucketing.ts` — takes `SessionFragment[]` for a single bucket, groups by project key using the same logic as `projectKey()` in `src/summary/summary-builder.ts` (i.e., `{kind}:{context.root ?? context.name ?? 'unknown'}`), returns `SlotProjectEntry[]` sorted by duration descending
+- [x] T006 Re-export `bucketSessionsByTime`, `groupFragmentsByProject`, `SessionFragment`, and `SlotProjectEntry` from `src/session/index.ts`
+- [x] T007 Run `bun test src/session/time-bucketing.test.ts` — all tests must pass
+
+**Checkpoint**: Time-bucketing utility complete and tested. User story implementation can begin.
+
+---
+
+## Phase 3: User Story 1 — Today's Hourly Activity Log (Priority: P1) 🎯 MVP
+
+**Goal**: `wildcard log` shows today's activity in hourly time slots with projects, durations, edit counts, and file counts per slot.
+
+**Independent Test**: Run `wildcard log` with activity data. Verify hourly slots from first to last active hour, projects ordered by duration descending per slot, empty hours skipped, summary header with total projects and active time, app usage footer, and empty-state message when no activity.
+
+### Implementation
+
+- [x] T008 [US1] Create `cmdLog()` in `src/commands/activity-log.ts` — follow `activity-show.ts` pattern: `createActivityContext()`, `parsePeriod()`, `periodRange()`, `qs.sessions()`, `db.getAppUsageSummary()`. Handle empty-activity via `printEmptyActivity()`. For today: use `bucketSessionsByTime(sessions, 3600000, range)`, then `groupFragmentsByProject()` per bucket. Render summary header with `periodLabel()`, total projects (deduplicated across slots), and total active time via `fmtDurationMs()`. Render each non-empty slot: time label (`HH:MM–HH:MM`) on first project row, indented alignment for subsequent projects, duration/edits/files per project. Call `printAppUsage()` for footer. Close context in `finally` block.
+- [x] T009 [US1] Write unit tests for slot rendering in `src/commands/activity-log.test.ts` — given pre-bucketed `SlotProjectEntry[]` data, verify: hourly label format (`HH:MM–HH:MM`), first-project gets slot label / subsequent indented, projects sorted by duration descending, empty slots omitted, summary header format, multi-branch display uses `join(', ')`
+- [x] T010 [US1] Add `cmdLog` export to `src/commands/activity.ts` barrel file
+- [x] T011 [US1] Add `cmdLog` and `LogOptions` re-exports to `src/commands/index.ts`
+- [x] T012 [US1] Register `log` command in `src/wildcard.ts` — `.command('log')`, `.description('Show chronological activity log')`, `.argument('[period]', 'today|yesterday|week')`, `.option('--today')`, `.option('--yesterday')`, `.option('--week')`, `.option('--device <ids>')`, `.option('--json')`, `.action(cmdLog)`. Follow `show` command pattern exactly.
+
+**Checkpoint**: `wildcard log` works for today's data. Verify with `bun src/wildcard.ts log`.
+
+---
+
+## Phase 4: User Story 2 — Period Arguments and Device Filtering (Priority: P2)
+
+**Goal**: `wildcard log yesterday` shows hourly slots for yesterday. `wildcard log --week` shows day-level slots. `--device` filters by device.
+
+**Independent Test**: Run `wildcard log yesterday` — verify hourly slots. Run `wildcard log --week` — verify day-level slots with `{Day, Mon DD}` labels, empty days skipped. Run `wildcard log --device <name>` — verify filtered output.
+
+### Implementation
+
+- [x] T013 [US2] Add day-level slot rendering to `cmdLog()` in `src/commands/activity-log.ts` — when period is `'week'`, use `bucketSessionsByTime(sessions, 86400000, range)` instead of hourly. Format slot label as `{Day, Mon DD}` (e.g., "Mon, Mar 16") instead of `{HH:MM}–{HH:MM}`. All other rendering logic (project ordering, summary header, app usage footer) stays the same. The `--device` and `yesterday` support already works via existing `parsePeriod()` and `parseDeviceFilter()` reuse from T008.
+
+**Checkpoint**: All three period modes work. Verify: `bun src/wildcard.ts log yesterday`, `bun src/wildcard.ts log --week`.
+
+---
+
+## Phase 5: User Story 3 — JSON Output (Priority: P3)
+
+**Goal**: `wildcard log --json` outputs structured JSON per cli-contract.md schema.
+
+**Independent Test**: Run `wildcard log --json | jq .` — verify valid JSON with `period`, `summary`, `slots`, and `app_usage` fields. All durations in milliseconds. Slots ordered chronologically, projects within slots ordered by duration descending.
+
+### Implementation
+
+- [x] T014 [US3] Add JSON output branch to `cmdLog()` in `src/commands/activity-log.ts` — when `flags.json` is true, build JSON object per cli-contract.md schema: `{ period: { type, label, start_ts, end_ts }, summary: { total_projects, total_duration_ms, total_edits }, slots: [{ start_ts, end_ts, label, projects: [{ name, branches, duration_ms, edit_count, file_count }] }], app_usage: [{ app_name, bundle_id, duration_ms, segments }] }`. Output via `console.log(JSON.stringify(result, null, 2))`. Skip human-readable rendering and `printAppUsage()` when in JSON mode.
+
+**Checkpoint**: JSON output works for all periods. Verify: `bun src/wildcard.ts log --json | jq .slots[0].projects`.
+
+---
+
+## Phase 6: Polish & Cross-Cutting Concerns
+
+**Purpose**: Final validation across all stories
+
+- [x] T015 Run full test suite via `bun test` — ensure no regressions
+- [x] T016 Run `bun run check` (lint + typecheck) — fix any issues
+- [x] T017 Smoke test all combinations: `log`, `log yesterday`, `log --week`, `log --json`, `log --json --week`, `log --device <id>`, `log` with no activity
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies — start immediately
+- **Foundational (Phase 2)**: Depends on T002 (types) from Setup
+- **US1 (Phase 3)**: Depends on Phase 2 completion (T007 tests passing)
+- **US2 (Phase 4)**: Depends on US1 (T008 — extends the same `cmdLog()` function)
+- **US3 (Phase 5)**: Depends on US2 (T013 — needs both hourly and daily rendering before adding JSON serialization)
+- **Polish (Phase 6)**: Depends on all stories complete
+
+### Within-Phase Parallelism
+
+- **Phase 1**: T001 and T002 are parallel [P] — different files
+- **Phase 2**: T003 (tests) should be written before T004 (implementation). T004→T005 sequential (same file). T006 after T005.
+- **Phase 3**: T008 first (core logic), then T009 (renderer tests), then T010/T011/T012 can be parallel [P] (different files, wiring only)
+- **Phase 4–5**: Sequential — each modifies `activity-log.ts`
+
+### Parallel Example: Phase 3 Wiring
+
+```text
+# After T008 and T009 complete, launch wiring tasks in parallel:
+Task T010: "Add cmdLog export to src/commands/activity.ts"
+Task T011: "Add cmdLog and LogOptions re-exports to src/commands/index.ts"
+Task T012: "Register log command in src/wildcard.ts"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup (T001–T002)
+2. Complete Phase 2: Foundational (T003–T007)
+3. Complete Phase 3: User Story 1 (T008–T012)
+4. **STOP and VALIDATE**: Run `bun src/wildcard.ts log` with real data
+5. Deployable MVP — the core value proposition works
+
+### Incremental Delivery
+
+1. Setup + Foundational → Time-bucketing utility tested and ready
+2. Add US1 → `wildcard log` works for today → MVP!
+3. Add US2 → `wildcard log yesterday` and `wildcard log --week` work
+4. Add US3 → `wildcard log --json` works → Full feature complete
+5. Polish → All tests pass, lint clean, smoke tested
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies
+- [Story] label maps task to specific user story
+- US2 and US3 modify the same file (`activity-log.ts`) — must be sequential
+- All Commander flags registered in T012 upfront (Commander handles missing handler logic gracefully)
+- No database schema changes — purely additive feature
diff --git a/src/commands/activity-log.test.ts b/src/commands/activity-log.test.ts
new file mode 100644
index 0000000..d803043
--- /dev/null
+++ b/src/commands/activity-log.test.ts
@@ -0,0 +1,150 @@
+import { describe, expect, it } from 'bun:test'
+
+import { bucketSessionsByTime, groupFragmentsByProject } from '../session/index.js'
+import { summarizeSlotEntries } from './activity-log.js'
+
+const HOUR_MS = 3_600_000
+
+describe('slot rendering format', () => {
+  it('formats hourly labels as HH:MM–HH:MM', () => {
+    // The formatSlotLabel is internal, so we test via the output format expectation.
+    // For hourly buckets, the label should be e.g. "09:00–10:00"
+    const base = new Date('2026-03-20T09:00:00').getTime()
+    const endTs = base + 20 * 60_000 // 9:20
+
+    const session = {
+      id: 's1',
+      start_ts: base + 5 * 60_000, // 9:05
+      end_ts: endTs,
+      context: { kind: 'git' as const, root: '/p/wildcard', name: 'wildcard', branch: 'main' },
+      events: [],
+      edit_count: 3,
+      file_paths: ['a.ts'],
+    }
+
+    const buckets = bucketSessionsByTime([session], HOUR_MS, [base, base + HOUR_MS])
+    const fragments = buckets.get(base)!
+    expect(fragments).toHaveLength(1)
+
+    const entries = groupFragmentsByProject(fragments)
+    expect(entries).toHaveLength(1)
+    expect(entries[0].display_name).toBe('wildcard')
+    expect(entries[0].branches).toContain('main')
+    expect(entries[0].edit_count).toBe(3)
+    expect(entries[0].file_count).toBe(1)
+  })
+
+  it('sorts projects by duration descending within a slot', () => {
+    const base = new Date('2026-03-20T10:00:00').getTime()
+
+    const s1 = {
+      id: 's1',
+      start_ts: base,
+      end_ts: base + 10 * 60_000, // 10 min
+      context: { kind: 'git' as const, root: '/p/short', name: 'short', branch: 'main' },
+      events: [],
+      edit_count: 1,
+      file_paths: [],
+    }
+    const s2 = {
+      id: 's2',
+      start_ts: base,
+      end_ts: base + 45 * 60_000, // 45 min
+      context: { kind: 'git' as const, root: '/p/long', name: 'long', branch: 'dev' },
+      events: [],
+      edit_count: 5,
+      file_paths: ['x.ts'],
+    }
+
+    const buckets = bucketSessionsByTime([s1, s2], HOUR_MS, [base, base + HOUR_MS])
+    const entries = groupFragmentsByProject(buckets.get(base)!)
+
+    expect(entries[0].display_name).toBe('long')
+    expect(entries[1].display_name).toBe('short')
+  })
+
+  it('omits empty slots', () => {
+    const base = new Date('2026-03-20T08:00:00').getTime()
+
+    // Only one session in 10:00 hour, nothing in 08:00 or 09:00
+    const session = {
+      id: 's1',
+      start_ts: base + 2 * HOUR_MS + 5 * 60_000, // 10:05
+      end_ts: base + 2 * HOUR_MS + 20 * 60_000, // 10:20
+      context: { kind: 'git' as const, root: '/p/wildcard', name: 'wildcard', branch: 'main' },
+      events: [],
+      edit_count: 2,
+      file_paths: ['b.ts'],
+    }
+
+    const buckets = bucketSessionsByTime([session], HOUR_MS, [base, base + 4 * HOUR_MS])
+
+    // 08:00 and 09:00 buckets should be empty
+    expect(buckets.get(base)!).toHaveLength(0)
+    expect(buckets.get(base + HOUR_MS)!).toHaveLength(0)
+    // 10:00 bucket should have our session
+    expect(buckets.get(base + 2 * HOUR_MS)!).toHaveLength(1)
+  })
+
+  it('joins multiple branches with comma in display', () => {
+    const base = new Date('2026-03-20T14:00:00').getTime()
+
+    const s1 = {
+      id: 's1',
+      start_ts: base,
+      end_ts: base + 30 * 60_000,
+      context: { kind: 'git' as const, root: '/p/wc', name: 'wildcard', branch: 'main' },
+      events: [],
+      edit_count: 2,
+      file_paths: ['a.ts'],
+    }
+    const s2 = {
+      id: 's2',
+      start_ts: base + 30 * 60_000,
+      end_ts: base + 50 * 60_000,
+      context: { kind: 'git' as const, root: '/p/wc', name: 'wildcard', branch: 'feature' },
+      events: [],
+      edit_count: 1,
+      file_paths: ['b.ts'],
+    }
+
+    const buckets = bucketSessionsByTime([s1, s2], HOUR_MS, [base, base + HOUR_MS])
+    const entries = groupFragmentsByProject(buckets.get(base)!)
+
+    expect(entries).toHaveLength(1)
+    expect(entries[0].branches).toContain('main')
+    expect(entries[0].branches).toContain('feature')
+  })
+
+  it('counts distinct projects by project key, not display name', () => {
+    const slotEntries = new Map([
+      [
+        0,
+        [
+          {
+            project_key: 'git:/projects/shared-name',
+            display_name: 'shared-name',
+            branches: ['main'],
+            duration_ms: 1_800_000,
+            edit_count: 2,
+            file_count: 1,
+          },
+          {
+            project_key: 'folder:/notes/shared-name',
+            display_name: 'shared-name',
+            branches: [],
+            duration_ms: 600_000,
+            edit_count: 1,
+            file_count: 1,
+          },
+        ],
+      ],
+    ])
+
+    expect(summarizeSlotEntries(slotEntries)).toEqual({
+      total_projects: 2,
+      total_duration_ms: 2_400_000,
+      total_edits: 3,
+    })
+  })
+})
diff --git a/src/commands/activity-log.ts b/src/commands/activity-log.ts
new file mode 100644
index 0000000..2ea7b5c
--- /dev/null
+++ b/src/commands/activity-log.ts
@@ -0,0 +1,192 @@
+import { bucketSessionsByTime, groupFragmentsByProject } from '../session/index.js'
+import type { SlotProjectEntry } from '../session/index.js'
+import { fmtDurationMs } from '../utils/format'
+
+import {
+  formatProjectLabel,
+  formatStatsLine,
+  labelColumnWidth,
+  printAppUsage,
+  printEmptyActivity,
+} from './formatters.js'
+import { parsePeriod, periodLabel, periodRange } from './period.js'
+import type { LogOptions, Period } from './types.js'
+import { createActivityContext, parseDeviceFilter } from './activity-common'
+
+const HOUR_MS = 3_600_000
+const DAY_MS = 86_400_000
+
+function formatHourLabel(ts: number): string {
+  const d = new Date(ts)
+  const hh = String(d.getHours()).padStart(2, '0')
+  const mm = String(d.getMinutes()).padStart(2, '0')
+  return `${hh}:${mm}`
+}
+
+function formatSlotLabel(startTs: number, bucketSizeMs: number): string {
+  if (bucketSizeMs === DAY_MS) {
+    const d = new Date(startTs)
+    const day = d.toLocaleDateString([], { weekday: 'short' })
+    const monthDay = d.toLocaleDateString([], { month: 'short', day: 'numeric' })
+    return `${day}, ${monthDay}`
+  }
+  return `${formatHourLabel(startTs)}\u2013${formatHourLabel(startTs + bucketSizeMs)}`
+}
+
+export function summarizeSlotEntries(
+  slotEntries: Map<number, SlotProjectEntry[]>,
+): {
+  total_projects: number
+  total_duration_ms: number
+  total_edits: number
+} {
+  const projectKeys = new Set<string>()
+  let totalDurationMs = 0
+  let totalEdits = 0
+
+  for (const entries of slotEntries.values()) {
+    for (const entry of entries) {
+      projectKeys.add(entry.project_key)
+      totalDurationMs += entry.duration_ms
+      totalEdits += entry.edit_count
+    }
+  }
+
+  return {
+    total_projects: projectKeys.size,
+    total_duration_ms: totalDurationMs,
+    total_edits: totalEdits,
+  }
+}
+
+function renderSlots(
+  buckets: Map<number, SlotProjectEntry[]>,
+  bucketSizeMs: number,
+): void {
+  const sortedKeys = [...buckets.keys()].sort((a, b) => a - b)
+
+  for (const key of sortedKeys) {
+    const entries = buckets.get(key)!
+    if (!entries.length) continue
+
+    const slotLabel = formatSlotLabel(key, bucketSizeMs)
+    const labelWidth = bucketSizeMs === DAY_MS ? 16 : 14
+    const projectLabels = entries.map((entry) => formatProjectLabel(entry.display_name, entry.branches))
+    const projectWidth = labelColumnWidth(projectLabels, 26)
+
+    for (let i = 0; i < entries.length; i++) {
+      const entry = entries[i]
+      const prefix = i === 0 ? `  ${slotLabel.padEnd(labelWidth)}` : `  ${' '.padEnd(labelWidth)}`
+      const name = projectLabels[i]
+      const stats = formatStatsLine(entry.duration_ms, entry.edit_count, entry.file_count)
+      console.log(`${prefix}${name.padEnd(projectWidth)}${stats}`)
+    }
+  }
+}
+
+export async function cmdLog(
+  periodArg: string | undefined,
+  flags: LogOptions,
+): Promise<void> {
+  const ctx = await createActivityContext()
+  try {
+    const { db, qs } = ctx
+    const period = parsePeriod(periodArg, flags)
+    const range = periodRange(period)
+    const deviceIds = parseDeviceFilter(flags.device)
+
+    const sessions = await qs.sessions({ time_range: range, device_ids: deviceIds })
+    const appUsage = db.getAppUsageSummary(range, 8, deviceIds)
+    const bucketSizeMs = period === 'week' ? DAY_MS : HOUR_MS
+
+    if (!sessions.length) {
+      if (flags.json) {
+        renderJson(period, range, new Map(), bucketSizeMs, appUsage)
+        return
+      }
+      printEmptyActivity(appUsage)
+      return
+    }
+
+    const sessionBuckets = bucketSessionsByTime(sessions, bucketSizeMs, range)
+
+    // Group fragments by project within each bucket
+    const slotEntries = new Map<number, SlotProjectEntry[]>()
+    for (const [key, fragments] of sessionBuckets) {
+      const grouped = groupFragmentsByProject(fragments)
+      if (grouped.length) slotEntries.set(key, grouped)
+    }
+
+    if (flags.json) {
+      renderJson(period, range, slotEntries, bucketSizeMs, appUsage)
+      return
+    }
+
+    const summary = summarizeSlotEntries(slotEntries)
+
+    const label = periodLabel(period, range)
+    console.log(
+      `${label} \u00b7 ${summary.total_projects} project${summary.total_projects === 1 ? '' : 's'} \u00b7 ${fmtDurationMs(summary.total_duration_ms)} active`,
+    )
+    console.log('')
+
+    renderSlots(slotEntries, bucketSizeMs)
+    printAppUsage(appUsage)
+  } finally {
+    ctx.close()
+  }
+}
+
+function renderJson(
+  period: Period,
+  range: [number, number],
+  slotEntries: Map<number, SlotProjectEntry[]>,
+  bucketSizeMs: number,
+  appUsage: { app_name: string; bundle_id: string | null; duration_ms: number; segments: number }[],
+): void {
+  const slots: {
+    start_ts: number
+    end_ts: number
+    label: string
+    projects: { name: string; branches: string[]; duration_ms: number; edit_count: number; file_count: number }[]
+  }[] = []
+
+  const sortedKeys = [...slotEntries.keys()].sort((a, b) => a - b)
+  for (const key of sortedKeys) {
+    const entries = slotEntries.get(key)!
+    const slotLabel = formatSlotLabel(key, bucketSizeMs)
+
+    slots.push({
+      start_ts: key,
+      end_ts: Math.min(key + bucketSizeMs, range[1]),
+      label: slotLabel,
+      projects: entries.map((e) => ({
+        name: e.display_name,
+        branches: e.branches,
+        duration_ms: e.duration_ms,
+        edit_count: e.edit_count,
+        file_count: e.file_count,
+      })),
+    })
+  }
+
+  const summary = summarizeSlotEntries(slotEntries)
+
+  const result = {
+    period: {
+      type: period,
+      label: periodLabel(period, range),
+      start_ts: range[0],
+      end_ts: range[1],
+    },
+    summary: {
+      total_projects: summary.total_projects,
+      total_duration_ms: summary.total_duration_ms,
+      total_edits: summary.total_edits,
+    },
+    slots,
+    app_usage: appUsage,
+  }
+
+  console.log(JSON.stringify(result, null, 2))
+}
diff --git a/src/commands/activity-show.ts b/src/commands/activity-show.ts
index 4c212a7..dc39d27 100644
--- a/src/commands/activity-show.ts
+++ b/src/commands/activity-show.ts
@@ -1,7 +1,13 @@
 import { groupSessionsByProject } from '../summary/index.js'
 import { fmtDurationMs, shortFile } from '../utils/format'
 
-import { printAppUsage, printEmptyActivity } from './formatters.js'
+import {
+  formatProjectLabel,
+  formatStatsLine,
+  labelColumnWidth,
+  printAppUsage,
+  printEmptyActivity,
+} from './formatters.js'
 import { parsePeriod, periodLabel, periodRange } from './period.js'
 import type { PeriodFlags } from './types.js'
 import { createActivityContext, parseDeviceFilter } from './activity-common'
@@ -33,17 +39,13 @@ export async function cmdShow(
     )
     console.log('')
 
+    const labels = groups.map((g) => formatProjectLabel(g.display_name, g.branches))
+    const labelWidth = labelColumnWidth(labels, 26)
+
     for (const g of groups) {
-      const namePart = g.branches.length
-        ? `${g.display_name} (${g.branches.join(', ')})`
-        : g.display_name
-      const dur = fmtDurationMs(g.total_duration_ms).padStart(5)
-      const editsPart = g.total_edits ? `${String(g.total_edits).padStart(4)} edits` : ''
-      const filesPart = g.all_file_paths.length
-        ? `${String(g.all_file_paths.length).padStart(4)} files`
-        : ''
-      const stats = [dur, editsPart, filesPart].filter(Boolean).join('   ')
-      console.log(`  ${namePart.padEnd(26)}${stats}`)
+      const namePart = formatProjectLabel(g.display_name, g.branches)
+      const stats = formatStatsLine(g.total_duration_ms, g.total_edits, g.all_file_paths.length)
+      console.log(`  ${namePart.padEnd(labelWidth)}${stats}`)
 
       if (g.all_file_paths.length) {
         const maxShown = 6
diff --git a/src/commands/activity.ts b/src/commands/activity.ts
index fcc8709..9e4e5fc 100644
--- a/src/commands/activity.ts
+++ b/src/commands/activity.ts
@@ -1,3 +1,4 @@
 export { cmdShow } from './activity-show'
 export { cmdReport } from './activity-report'
 export { cmdSearch } from './activity-search'
+export { cmdLog } from './activity-log'
diff --git a/src/commands/formatters.ts b/src/commands/formatters.ts
index e0c5a07..5c499a6 100644
--- a/src/commands/formatters.ts
+++ b/src/commands/formatters.ts
@@ -1,6 +1,22 @@
 import type { AppUsageSummary } from '../storage/index.js'
 import { fmtDurationMs } from '../utils/format'
 
+export function formatProjectLabel(display_name: string, branches: string[]): string {
+  if (branches.length) return `${display_name} (${branches.join(', ')})`
+  return display_name
+}
+
+export function labelColumnWidth(labels: string[], minWidth: number): number {
+  return labels.reduce((width, label) => Math.max(width, label.length + 2), minWidth)
+}
+
+export function formatStatsLine(duration_ms: number, edit_count: number, file_count: number): string {
+  const dur = fmtDurationMs(duration_ms).padStart(5)
+  const editsPart = edit_count ? `${String(edit_count).padStart(4)} edits` : ''
+  const filesPart = file_count ? `${String(file_count).padStart(4)} files` : ''
+  return [dur, editsPart, filesPart].filter(Boolean).join('   ')
+}
+
 function appUsageLabel(r: Pick<AppUsageSummary, 'app_name' | 'bundle_id'>): string {
   return r.bundle_id ? `${r.app_name} (${r.bundle_id})` : r.app_name
 }
@@ -27,9 +43,11 @@ export function printAppUsage(rows: AppUsageSummary[], opts: { markdown?: boolea
 
   console.log('')
   console.log('Top apps:')
+  const labels = rows.map(appUsageLabel)
+  const labelWidth = labelColumnWidth(labels, 30)
   for (const r of rows) {
     const dur = fmtDurationMs(r.duration_ms).padStart(5)
-    console.log(`  ${appUsageLabel(r).padEnd(30)}${dur}   ${r.segments} segments`)
+    console.log(`  ${appUsageLabel(r).padEnd(labelWidth)}${dur}   ${r.segments} segments`)
   }
 }
 
diff --git a/src/commands/index.ts b/src/commands/index.ts
index 26ff8f2..486b642 100644
--- a/src/commands/index.ts
+++ b/src/commands/index.ts
@@ -1,12 +1,13 @@
 export { cmdWatch } from './watch'
 export { cmdStatus } from './status'
-export { cmdShow, cmdReport, cmdSearch } from './activity'
+export { cmdShow, cmdReport, cmdSearch, cmdLog } from './activity'
 export { cmdInstallLaunchd, cmdUninstallLaunchd, cmdRestart } from './launchd'
 export { cmdPrune, cmdArchive } from './retention'
 export { cmdSetup } from './setup'
 export { cmdSyncPush } from './cmd-sync'
 
 export type {
+  LogOptions,
   PeriodFlags,
   ReportOptions,
   SearchOptions,
diff --git a/src/commands/types.ts b/src/commands/types.ts
index 0f7906b..e4dabd0 100644
--- a/src/commands/types.ts
+++ b/src/commands/types.ts
@@ -33,3 +33,8 @@ export type SearchOptions = {
   to?: string
   types?: string
 }
+
+export type LogOptions = PeriodFlags & {
+  device?: string
+  json?: boolean
+}
diff --git a/src/session/index.ts b/src/session/index.ts
index 9819d9c..cf7f3d5 100644
--- a/src/session/index.ts
+++ b/src/session/index.ts
@@ -5,4 +5,7 @@ export { IdleBoundaryDetector } from './idle-boundary-detector'
 export { QueryService } from './query-service'
 export type { AppUsageTrackerOptions } from './app-usage-tracker'
 export type { SessionQuery } from './query-service'
+export { projectKey, projectDisplayName } from './types'
 export type { Session, SessionBoundaryDetector } from './types'
+export { bucketSessionsByTime, groupFragmentsByProject } from './time-bucketing'
+export type { SessionFragment, SlotProjectEntry } from './time-bucketing'
diff --git a/src/session/time-bucketing.test.ts b/src/session/time-bucketing.test.ts
new file mode 100644
index 0000000..d89064a
--- /dev/null
+++ b/src/session/time-bucketing.test.ts
@@ -0,0 +1,256 @@
+import { describe, expect, it } from 'bun:test'
+
+import type { Session } from './types'
+import { bucketSessionsByTime, groupFragmentsByProject } from './time-bucketing'
+
+const HOUR = 3_600_000
+const DAY = 86_400_000
+
+// Helper: create a minimal session for testing
+function makeSession(overrides: Partial<Session> & { start_ts: number; end_ts: number }): Session {
+  return {
+    id: `session-${overrides.start_ts}`,
+    device_id: undefined,
+    context: { kind: 'git', root: '/projects/wildcard', name: 'wildcard', branch: 'main' },
+    events: [],
+    edit_count: 0,
+    file_paths: [],
+    ...overrides,
+  }
+}
+
+describe('bucketSessionsByTime', () => {
+  it('places a single session entirely within one bucket', () => {
+    const base = HOUR * 10 // 10:00
+    const session = makeSession({
+      start_ts: base + 600_000, // 10:10
+      end_ts: base + 1_800_000, // 10:30
+      edit_count: 5,
+      file_paths: ['a.ts'],
+    })
+
+    const result = bucketSessionsByTime([session], HOUR, [base, base + HOUR])
+    const fragments = result.get(base)!
+    expect(fragments).toHaveLength(1)
+    expect(fragments[0].duration_ms).toBe(1_200_000) // 20 minutes
+    expect(fragments[0].edit_count).toBe(5)
+  })
+
+  it('splits a session spanning an hour boundary proportionally', () => {
+    const base = HOUR * 9 // 09:00
+    // Session from 9:45 to 10:30 (45 minutes total)
+    const session = makeSession({
+      start_ts: base + 2_700_000, // 9:45
+      end_ts: base + HOUR + 1_800_000, // 10:30
+      edit_count: 6,
+      file_paths: ['a.ts', 'b.ts'],
+    })
+
+    const result = bucketSessionsByTime([session], HOUR, [base, base + 2 * HOUR])
+
+    // 09:00 bucket: 15 minutes (9:45–10:00)
+    const slot9 = result.get(base)!
+    expect(slot9).toHaveLength(1)
+    expect(slot9[0].duration_ms).toBe(900_000) // 15 min
+    expect(slot9[0].edit_count).toBe(6) // edits go to start slot
+
+    // 10:00 bucket: 30 minutes (10:00–10:30)
+    const slot10 = result.get(base + HOUR)!
+    expect(slot10).toHaveLength(1)
+    expect(slot10[0].duration_ms).toBe(1_800_000) // 30 min
+    expect(slot10[0].edit_count).toBe(0) // no edits in non-start slot
+  })
+
+  it('handles a zero-duration session', () => {
+    const base = HOUR * 10
+    const session = makeSession({
+      start_ts: base + 500_000,
+      end_ts: base + 500_000, // same as start
+      edit_count: 1,
+    })
+
+    const result = bucketSessionsByTime([session], HOUR, [base, base + HOUR])
+    const fragments = result.get(base)!
+    expect(fragments).toHaveLength(1)
+    expect(fragments[0].duration_ms).toBe(0)
+    expect(fragments[0].edit_count).toBe(1)
+  })
+
+  it('distributes multiple sessions across multiple buckets', () => {
+    const base = HOUR * 8 // 08:00
+    const s1 = makeSession({
+      id: 's1',
+      start_ts: base + 600_000, // 8:10
+      end_ts: base + 1_200_000, // 8:20
+    })
+    const s2 = makeSession({
+      id: 's2',
+      start_ts: base + HOUR + 600_000, // 9:10
+      end_ts: base + HOUR + 1_200_000, // 9:20
+    })
+
+    const result = bucketSessionsByTime([s1, s2], HOUR, [base, base + 2 * HOUR])
+    expect(result.get(base)!).toHaveLength(1)
+    expect(result.get(base + HOUR)!).toHaveLength(1)
+  })
+
+  it('handles a session exactly at bucket boundary', () => {
+    const base = HOUR * 10 // exactly 10:00
+    const session = makeSession({
+      start_ts: base, // exactly at boundary
+      end_ts: base + 1_800_000, // 10:30
+      edit_count: 3,
+    })
+
+    const result = bucketSessionsByTime([session], HOUR, [base, base + HOUR])
+    const fragments = result.get(base)!
+    expect(fragments).toHaveLength(1)
+    expect(fragments[0].duration_ms).toBe(1_800_000)
+    expect(fragments[0].edit_count).toBe(3)
+  })
+
+  it('uses daily bucket size correctly', () => {
+    const dayStart = new Date('2026-03-16T00:00:00').getTime() // Monday
+    const session = makeSession({
+      start_ts: dayStart + 9 * HOUR, // 9 AM Monday
+      end_ts: dayStart + 10 * HOUR, // 10 AM Monday
+      edit_count: 4,
+    })
+
+    const weekEnd = dayStart + 7 * DAY
+    const result = bucketSessionsByTime([session], DAY, [dayStart, weekEnd])
+    const mondayFragments = result.get(dayStart)!
+    expect(mondayFragments).toHaveLength(1)
+    expect(mondayFragments[0].duration_ms).toBe(HOUR)
+    expect(mondayFragments[0].edit_count).toBe(4)
+  })
+
+  it('anchors day buckets to the requested range start instead of UTC midnight', () => {
+    const dayStart = new Date('2026-03-16T00:00:00-04:00').getTime() // Monday local midnight
+    const session = makeSession({
+      start_ts: dayStart + HOUR, // 1 AM Monday local
+      end_ts: dayStart + 2 * HOUR,
+      edit_count: 2,
+    })
+
+    const result = bucketSessionsByTime([session], DAY, [dayStart, dayStart + 7 * DAY])
+
+    expect(result.get(dayStart)!).toHaveLength(1)
+    expect(result.has(dayStart - DAY)).toBe(false)
+  })
+})
+
+describe('groupFragmentsByProject', () => {
+  it('groups fragments by project key using fallback chain', () => {
+    const frag1 = {
+      session: makeSession({
+        start_ts: 0,
+        end_ts: HOUR,
+        context: { kind: 'git' as const, root: '/projects/wildcard', name: 'wildcard', branch: 'main' },
+      }),
+      start_ts: 0,
+      end_ts: HOUR,
+      duration_ms: HOUR,
+      edit_count: 5,
+      file_paths: ['a.ts'],
+    }
+    const frag2 = {
+      session: makeSession({
+        start_ts: 0,
+        end_ts: HOUR,
+        context: { kind: 'folder' as const, name: 'notes' },
+      }),
+      start_ts: 0,
+      end_ts: HOUR,
+      duration_ms: 1_800_000,
+      edit_count: 2,
+      file_paths: ['b.md'],
+    }
+
+    const entries = groupFragmentsByProject([frag1, frag2])
+    expect(entries).toHaveLength(2)
+    expect(entries[0].display_name).toBe('wildcard') // higher duration first
+    expect(entries[1].display_name).toBe('notes')
+  })
+
+  it('accumulates multi-branch contributions within a slot', () => {
+    const base = makeSession({
+      start_ts: 0,
+      end_ts: HOUR,
+      context: { kind: 'git' as const, root: '/projects/wildcard', name: 'wildcard', branch: 'main' },
+      file_paths: ['a.ts'],
+    })
+    const frag1 = {
+      session: { ...base, id: 'f1' },
+      start_ts: 0,
+      end_ts: HOUR / 2,
+      duration_ms: HOUR / 2,
+      edit_count: 3,
+      file_paths: ['a.ts'],
+    }
+    const frag2 = {
+      session: {
+        ...base,
+        id: 'f2',
+        context: { kind: 'git' as const, root: '/projects/wildcard', name: 'wildcard', branch: 'feature' },
+      },
+      start_ts: HOUR / 2,
+      end_ts: HOUR,
+      duration_ms: HOUR / 2,
+      edit_count: 2,
+      file_paths: ['b.ts'],
+    }
+
+    const entries = groupFragmentsByProject([frag1, frag2])
+    expect(entries).toHaveLength(1)
+    expect(entries[0].branches).toContain('main')
+    expect(entries[0].branches).toContain('feature')
+    expect(entries[0].duration_ms).toBe(HOUR)
+    expect(entries[0].edit_count).toBe(5)
+    expect(entries[0].file_count).toBe(2)
+  })
+
+  it('sorts entries by duration descending', () => {
+    const makeFrag = (name: string, durationMs: number) => ({
+      session: makeSession({
+        start_ts: 0,
+        end_ts: durationMs,
+        context: { kind: 'git' as const, root: `/projects/${name}`, name },
+      }),
+      start_ts: 0,
+      end_ts: durationMs,
+      duration_ms: durationMs,
+      edit_count: 0,
+      file_paths: [],
+    })
+
+    const entries = groupFragmentsByProject([
+      makeFrag('short', 600_000),
+      makeFrag('long', 3_000_000),
+      makeFrag('medium', 1_800_000),
+    ])
+
+    expect(entries[0].display_name).toBe('long')
+    expect(entries[1].display_name).toBe('medium')
+    expect(entries[2].display_name).toBe('short')
+  })
+
+  it('uses name fallback when root is absent', () => {
+    const frag = {
+      session: makeSession({
+        start_ts: 0,
+        end_ts: HOUR,
+        context: { kind: 'app' as const, name: 'Slack' },
+      }),
+      start_ts: 0,
+      end_ts: HOUR,
+      duration_ms: HOUR,
+      edit_count: 0,
+      file_paths: [],
+    }
+
+    const entries = groupFragmentsByProject([frag])
+    expect(entries).toHaveLength(1)
+    expect(entries[0].display_name).toBe('Slack')
+  })
+})
diff --git a/src/session/time-bucketing.ts b/src/session/time-bucketing.ts
new file mode 100644
index 0000000..e430633
--- /dev/null
+++ b/src/session/time-bucketing.ts
@@ -0,0 +1,149 @@
+import { projectKey, projectDisplayName } from './types'
+import type { Session } from './types'
+
+export type SessionFragment = {
+  session: Session
+  start_ts: number
+  end_ts: number
+  duration_ms: number
+  edit_count: number
+  file_paths: string[]
+}
+
+export type SlotProjectEntry = {
+  project_key: string
+  display_name: string
+  branches: string[]
+  duration_ms: number
+  edit_count: number
+  file_count: number
+}
+
+/**
+ * Split sessions into fixed-size time buckets. Sessions spanning bucket
+ * boundaries are split proportionally. Edits are assigned to the fragment
+ * whose bucket contains the session's start_ts.
+ */
+export function bucketSessionsByTime(
+  sessions: Session[],
+  bucketSizeMs: number,
+  range: [number, number],
+): Map<number, SessionFragment[]> {
+  const [rangeStart, rangeEnd] = range
+  const buckets = new Map<number, SessionFragment[]>()
+
+  // Anchor buckets to the requested range so local day/week boundaries stay intact.
+  for (let ts = rangeStart; ts < rangeEnd; ts += bucketSizeMs) {
+    buckets.set(ts, [])
+  }
+
+  for (const session of sessions) {
+    const sessionStart = Math.max(session.start_ts, rangeStart)
+    const sessionEnd = Math.min(session.end_ts, rangeEnd)
+    const sessionDuration = sessionEnd - sessionStart
+    if (sessionDuration < 0) continue
+
+    const sessionBucketStart =
+      rangeStart + Math.floor((sessionStart - rangeStart) / bucketSizeMs) * bucketSizeMs
+    const startSlotKey = sessionBucketStart
+
+    // Zero-duration session: place entirely in start bucket
+    if (sessionDuration === 0) {
+      let fragments = buckets.get(startSlotKey)
+      if (!fragments) {
+        fragments = []
+        buckets.set(startSlotKey, fragments)
+      }
+      fragments.push({
+        session,
+        start_ts: sessionStart,
+        end_ts: sessionEnd,
+        duration_ms: 0,
+        edit_count: session.edit_count,
+        file_paths: session.file_paths,
+      })
+      continue
+    }
+
+    // Find all buckets this session spans
+    let bucketStart = sessionBucketStart
+    while (bucketStart < sessionEnd) {
+      const bucketEnd = bucketStart + bucketSizeMs
+      const fragStart = Math.max(sessionStart, bucketStart)
+      const fragEnd = Math.min(sessionEnd, bucketEnd)
+      const overlap = fragEnd - fragStart
+
+      if (overlap > 0) {
+        const isStartSlot = bucketStart === startSlotKey
+
+        let fragments = buckets.get(bucketStart)
+        if (!fragments) {
+          fragments = []
+          buckets.set(bucketStart, fragments)
+        }
+
+        fragments.push({
+          session,
+          start_ts: fragStart,
+          end_ts: fragEnd,
+          duration_ms: overlap,
+          edit_count: isStartSlot ? session.edit_count : 0,
+          file_paths: session.file_paths,
+        })
+      }
+
+      bucketStart += bucketSizeMs
+    }
+  }
+
+  return buckets
+}
+
+/**
+ * Group session fragments within a single bucket by project key.
+ * Returns entries sorted by duration descending.
+ */
+export function groupFragmentsByProject(fragments: SessionFragment[]): SlotProjectEntry[] {
+  const map = new Map<
+    string,
+    {
+      display_name: string
+      branchSet: Set<string>
+      duration_ms: number
+      edit_count: number
+      fileSet: Set<string>
+    }
+  >()
+
+  for (const frag of fragments) {
+    const key = projectKey(frag.session.context)
+
+    let acc = map.get(key)
+    if (!acc) {
+      acc = {
+        display_name: projectDisplayName(frag.session.context),
+        branchSet: new Set(),
+        duration_ms: 0,
+        edit_count: 0,
+        fileSet: new Set(),
+      }
+      map.set(key, acc)
+    }
+
+    acc.duration_ms += frag.duration_ms
+    acc.edit_count += frag.edit_count
+    for (const fp of frag.file_paths) acc.fileSet.add(fp)
+    if (frag.session.context.branch) acc.branchSet.add(frag.session.context.branch)
+  }
+
+  return [...map.entries()]
+    .map(([project_key, acc]) => ({
+      project_key,
+      display_name: acc.display_name,
+      branches: [...acc.branchSet],
+      duration_ms: acc.duration_ms,
+      edit_count: acc.edit_count,
+      file_count: acc.fileSet.size,
+    }))
+    .sort((a, b) => b.duration_ms - a.duration_ms)
+}
diff --git a/src/session/types.ts b/src/session/types.ts
index 8407337..abadb45 100644
--- a/src/session/types.ts
+++ b/src/session/types.ts
@@ -16,6 +16,15 @@ export type Session = {
   file_paths: string[]
 }
 
+export function projectKey(ctx: Session['context']): string {
+  const root = ctx.root ?? ctx.name ?? 'unknown'
+  return `${ctx.kind}:${root}`
+}
+
+export function projectDisplayName(ctx: Session['context']): string {
+  return ctx.name ?? ctx.kind
+}
+
 export interface SessionBoundaryDetector {
   shouldStartNewSession(prev: UnifiedEvent, current: UnifiedEvent): boolean
 }
diff --git a/src/utils/time.ts b/src/utils/time.ts
index f4b2ae1..949610b 100644
--- a/src/utils/time.ts
+++ b/src/utils/time.ts
@@ -1,10 +1,10 @@
-export function startOfDay(d: Date): Date {
+function startOfDay(d: Date): Date {
   const out = new Date(d)
   out.setHours(0, 0, 0, 0)
   return out
 }
 
-export function endOfDay(d: Date): Date {
+function endOfDay(d: Date): Date {
   const out = startOfDay(d)
   out.setDate(out.getDate() + 1)
   return out
diff --git a/src/wildcard.ts b/src/wildcard.ts
index 4432a5b..7e67a5b 100755
--- a/src/wildcard.ts
+++ b/src/wildcard.ts
@@ -7,6 +7,7 @@ import { Command, CommanderError, Option } from 'commander'
 import {
   cmdArchive,
   cmdInstallLaunchd,
+  cmdLog,
   cmdPrune,
   cmdReport,
   cmdRestart,
@@ -19,6 +20,7 @@ import {
   cmdWatch,
 } from './commands/index.js'
 import type {
+  LogOptions,
   PeriodFlags,
   ReportOptions,
   SearchOptions,
@@ -64,6 +66,19 @@ function buildProgram(): Command {
       cmdShow(periodArg, flags),
     )
 
+  program
+    .command('log')
+    .description('Show chronological activity log')
+    .argument('[period]', 'today|yesterday|week')
+    .option('--today', 'Show today')
+    .option('--yesterday', 'Show yesterday')
+    .option('--week', 'Show this week')
+    .option('--device <ids>', 'Filter by device ID(s), comma-separated')
+    .option('--json', 'Output machine-readable JSON')
+    .action(async (periodArg: string | undefined, flags: LogOptions) =>
+      cmdLog(periodArg, flags),
+    )
+
   program
     .command('report')
     .description('Generate a report for a period')

From 9877152a9bd562590f0277512237c11cca1da313 Mon Sep 17 00:00:00 2001
From: Andy Pai <andy@r2pi.co>
Date: Fri, 20 Mar 2026 18:37:10 -0400
Subject: [PATCH 2/9] refactor: load summary prompts from markdown

---
 src/summary/prompt-templates.test.ts   | 45 ++++++++++++++++++++++++++
 src/summary/prompt-templates.ts        | 43 ++++++++++++++++++++++++
 src/summary/prompts/daily-synthesis.md |  2 ++
 src/summary/prompts/project-summary.md |  2 ++
 src/summary/prompts/session-summary.md |  2 ++
 src/summary/summary-builder.ts         | 23 ++++---------
 tutorials/06-ai.md                     |  4 ++-
 7 files changed, 104 insertions(+), 17 deletions(-)
 create mode 100644 src/summary/prompt-templates.test.ts
 create mode 100644 src/summary/prompt-templates.ts
 create mode 100644 src/summary/prompts/daily-synthesis.md
 create mode 100644 src/summary/prompts/project-summary.md
 create mode 100644 src/summary/prompts/session-summary.md

diff --git a/src/summary/prompt-templates.test.ts b/src/summary/prompt-templates.test.ts
new file mode 100644
index 0000000..1067b21
--- /dev/null
+++ b/src/summary/prompt-templates.test.ts
@@ -0,0 +1,45 @@
+import os from 'node:os'
+import path from 'node:path'
+
+import { describe, expect, it } from 'bun:test'
+
+import {
+  clearPromptTemplateCache,
+  getPromptTemplate,
+  readPromptTemplateFile,
+} from './prompt-templates'
+
+describe('prompt templates', () => {
+  it('loads all built-in summary prompt templates', async () => {
+    clearPromptTemplateCache()
+
+    await expect(getPromptTemplate('session-summary')).resolves.toContain(
+      'Summarize this work session',
+    )
+    await expect(getPromptTemplate('project-summary')).resolves.toContain(
+      'Summarize work on this project',
+    )
+    await expect(getPromptTemplate('daily-synthesis')).resolves.toContain(
+      "Write a 2-3 sentence summary of the day's work.",
+    )
+  })
+
+  it('returns the same cached promise for repeated loads', () => {
+    clearPromptTemplateCache()
+
+    const first = getPromptTemplate('session-summary')
+    const second = getPromptTemplate('session-summary')
+
+    expect(second).toBe(first)
+  })
+
+  it('throws a clear error when a prompt file is missing', async () => {
+    const missingUrl = new URL(
+      `file://${path.join(os.tmpdir(), `wildcard-missing-${Date.now()}.md`)}`,
+    )
+
+    await expect(readPromptTemplateFile(missingUrl, 'missing-template')).rejects.toThrow(
+      'Prompt template "missing-template" not found',
+    )
+  })
+})
diff --git a/src/summary/prompt-templates.ts b/src/summary/prompt-templates.ts
new file mode 100644
index 0000000..b44bfec
--- /dev/null
+++ b/src/summary/prompt-templates.ts
@@ -0,0 +1,43 @@
+type PromptTemplateName = 'session-summary' | 'project-summary' | 'daily-synthesis'
+
+const PROMPT_TEMPLATE_URLS: Record<PromptTemplateName, URL> = {
+  'session-summary': new URL('./prompts/session-summary.md', import.meta.url),
+  'project-summary': new URL('./prompts/project-summary.md', import.meta.url),
+  'daily-synthesis': new URL('./prompts/daily-synthesis.md', import.meta.url),
+}
+
+const promptTemplateCache = new Map<PromptTemplateName, Promise<string>>()
+
+export async function readPromptTemplateFile(
+  fileUrl: URL,
+  templateName: string,
+): Promise<string> {
+  const file = Bun.file(fileUrl)
+  if (!(await file.exists())) {
+    throw new Error(`Prompt template "${templateName}" not found at ${fileUrl.pathname}`)
+  }
+
+  const text = (await file.text()).trim()
+  if (!text) {
+    throw new Error(`Prompt template "${templateName}" is empty`)
+  }
+
+  return text
+}
+
+export function getPromptTemplate(name: PromptTemplateName): Promise<string> {
+  let cached = promptTemplateCache.get(name)
+  if (!cached) {
+    cached = readPromptTemplateFile(PROMPT_TEMPLATE_URLS[name], name).catch((error) => {
+      promptTemplateCache.delete(name)
+      throw error
+    })
+    promptTemplateCache.set(name, cached)
+  }
+
+  return cached
+}
+
+export function clearPromptTemplateCache(): void {
+  promptTemplateCache.clear()
+}
diff --git a/src/summary/prompts/daily-synthesis.md b/src/summary/prompts/daily-synthesis.md
new file mode 100644
index 0000000..c40d3cb
--- /dev/null
+++ b/src/summary/prompts/daily-synthesis.md
@@ -0,0 +1,2 @@
+Write a 2-3 sentence summary of the day's work.
+Focus on themes and accomplishments. No fluff.
diff --git a/src/summary/prompts/project-summary.md b/src/summary/prompts/project-summary.md
new file mode 100644
index 0000000..98b6444
--- /dev/null
+++ b/src/summary/prompts/project-summary.md
@@ -0,0 +1,2 @@
+Summarize work on this project in 2-4 bullet points.
+Merge overlapping activities. Be concrete and specific.
diff --git a/src/summary/prompts/session-summary.md b/src/summary/prompts/session-summary.md
new file mode 100644
index 0000000..19a5653
--- /dev/null
+++ b/src/summary/prompts/session-summary.md
@@ -0,0 +1,2 @@
+Summarize this work session in 2-4 bullet points.
+Keep it concrete. Avoid fluff.
diff --git a/src/summary/summary-builder.ts b/src/summary/summary-builder.ts
index 9fab756..f8419a6 100644
--- a/src/summary/summary-builder.ts
+++ b/src/summary/summary-builder.ts
@@ -1,11 +1,13 @@
 import path from 'node:path'
 
 import type { AiProvider, ChatMessage } from '../ai/index.js'
+import { projectKey as sessionProjectKey, projectDisplayName } from '../session/index.js'
 import type { Session } from '../session/index.js'
 import type { DailySummary, SessionSummary } from '../storage/index.js'
 import { fmtDurationMs } from '../utils/format.js'
 
 import type { SummaryCache } from './summary-cache'
+import { getPromptTemplate } from './prompt-templates'
 
 export type SummaryBuilderOptions = {
   ai?: AiProvider
@@ -45,9 +47,7 @@ export type ProjectGroup = {
 }
 
 function projectKey(session: Session): string {
-  const kind = session.context.kind
-  const root = session.context.root ?? session.context.name ?? 'unknown'
-  return `${kind}:${root}`
+  return sessionProjectKey(session.context)
 }
 
 type ProjectAccumulator = {
@@ -66,7 +66,7 @@ export function groupSessionsByProject(sessions: Session[]): ProjectGroup[] {
       acc = {
         group: {
           project_key: key,
-          display_name: s.context.name ?? s.context.kind,
+          display_name: projectDisplayName(s.context),
           context_kind: s.context.kind,
           branches: [],
           sessions: [],
@@ -349,10 +349,7 @@ export class SummaryBuilder {
     )
     const insights = appInsightsFromEvents(session.events, 5)
     const duration = fmtDurationMs(session.end_ts - session.start_ts)
-    const prompt = [
-      `Summarize this work session in 2-4 bullet points.`,
-      `Keep it concrete. Avoid fluff.`,
-    ].join('\n')
+    const prompt = await getPromptTemplate('session-summary')
 
     const user = [
       `Context: ${contextLabel(session)}`,
@@ -401,10 +398,7 @@ export class SummaryBuilder {
     const cappedSummaries = sessionSummaries.slice(0, 10).map((s) => s.slice(0, 300))
     const fileBasenames = group.all_file_paths.slice(0, 20).map((p) => path.basename(p))
 
-    const prompt = [
-      'Summarize work on this project in 2-4 bullet points.',
-      'Merge overlapping activities. Be concrete and specific.',
-    ].join('\n')
+    const prompt = await getPromptTemplate('project-summary')
 
     const user = [
       `Project: ${group.display_name}`,
@@ -436,10 +430,7 @@ export class SummaryBuilder {
   ): Promise<string> {
     if (!this.options.ai) return ''
 
-    const prompt = [
-      "Write a 2-3 sentence summary of the day's work.",
-      'Focus on themes and accomplishments. No fluff.',
-    ].join('\n')
+    const prompt = await getPromptTemplate('daily-synthesis')
 
     const user = [
       `Total active time: ${fmtDurationMs(totalMs)}`,
diff --git a/tutorials/06-ai.md b/tutorials/06-ai.md
index bbde878..a35b9ae 100644
--- a/tutorials/06-ai.md
+++ b/tutorials/06-ai.md
@@ -36,6 +36,8 @@ Important methods:
 - `summarizeSessionWithMeta(session)`
 - `summarizeReportWithMeta(sessions, title, day, period)`
 
+Prompt wording lives in `src/summary/prompts/*.md`. Those markdown files contain the stable system instructions, and `src/summary/summary-builder.ts` still builds the dynamic user payload from session and project data.
+
 ### Step 3: CLI report command
 
 File: `src/commands/activity-report.ts`
@@ -50,7 +52,7 @@ Example config in `~/.wildcard/config.yaml`:
 ai:
   enabled: true
   provider: openai
-  model: gpt-4o-mini
+  model: gpt-5.4-mini
   api_key: YOUR_KEY
 ```
 

From 27640bc84922dc7b50d76b59508680b61056d248 Mon Sep 17 00:00:00 2001
From: Andy Pai <andy@r2pi.co>
Date: Fri, 20 Mar 2026 18:37:17 -0400
Subject: [PATCH 3/9] chore: refresh ai defaults

---
 WORKFLOW.md                | 6 +++---
 src/commands/setup.ts      | 6 +++---
 src/config/config-store.ts | 2 +-
 tutorials/10-config.md     | 2 +-
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/WORKFLOW.md b/WORKFLOW.md
index 04f1b99..0f511b3 100644
--- a/WORKFLOW.md
+++ b/WORKFLOW.md
@@ -253,7 +253,7 @@ bun run wildcard show today
 2. Pull a model:
 
 ```bash
-ollama pull llama3.2
+ollama pull qwen3:8b
 ```
 
 3. Update config:
@@ -262,7 +262,7 @@ ollama pull llama3.2
 ai:
   enabled: true
   provider: ollama
-  model: llama3.2
+  model: qwen3:8b
 ```
 
 #### Option B: OpenAI
@@ -271,7 +271,7 @@ ai:
 ai:
   enabled: true
   provider: openai
-  model: gpt-4o-mini
+  model: gpt-5.4-mini
   api_key: sk-your-key-here
 ```
 
diff --git a/src/commands/setup.ts b/src/commands/setup.ts
index bb39cd4..3f82761 100644
--- a/src/commands/setup.ts
+++ b/src/commands/setup.ts
@@ -87,9 +87,9 @@ export async function cmdSetup(): Promise<void> {
       }),
     )
 
-    let defaultModel = 'llama3.2'
-    if (aiProvider === 'gemini') defaultModel = 'gemini-2.5-flash'
-    if (aiProvider === 'openai') defaultModel = 'gpt-4o-mini'
+    let defaultModel = 'qwen3:8b'
+    if (aiProvider === 'gemini') defaultModel = 'gemini-2.5-flash-lite'
+    if (aiProvider === 'openai') defaultModel = 'gpt-5-mini'
 
     aiModel = exitIfCancelled(
       await text({
diff --git a/src/config/config-store.ts b/src/config/config-store.ts
index e07a148..44882b1 100644
--- a/src/config/config-store.ts
+++ b/src/config/config-store.ts
@@ -181,7 +181,7 @@ export function defaultConfig(): WildcardConfig {
     ai: {
       enabled: false,
       provider: 'ollama',
-      model: 'llama3.2',
+      model: 'qwen3:8b',
     },
     identity: {
       device_id: undefined,
diff --git a/tutorials/10-config.md b/tutorials/10-config.md
index 46a50e4..56b0b39 100644
--- a/tutorials/10-config.md
+++ b/tutorials/10-config.md
@@ -55,7 +55,7 @@ session:
 ai:
   enabled: false
   provider: ollama
-  model: llama3.2
+  model: qwen3:8b
 ```
 
 ### Step 3: Useful env overrides

From 2780c6aee50221f3de5e21ae3b258b3c6bce33ea Mon Sep 17 00:00:00 2001
From: Andy Pai <andy@r2pi.co>
Date: Fri, 20 Mar 2026 18:37:24 -0400
Subject: [PATCH 4/9] refactor: clean constructor setup

---
 src/capture/platform/darwin-watcher.ts  |  7 ++++---
 src/capture/platform/polling-watcher.ts |  9 +++++----
 src/session/session-manager.ts          | 13 ++++++-------
 src/storage/timeline-db.ts              |  2 +-
 src/utils/format.ts                     | 10 ----------
 5 files changed, 16 insertions(+), 25 deletions(-)

diff --git a/src/capture/platform/darwin-watcher.ts b/src/capture/platform/darwin-watcher.ts
index b3915a1..348ef7a 100644
--- a/src/capture/platform/darwin-watcher.ts
+++ b/src/capture/platform/darwin-watcher.ts
@@ -35,10 +35,11 @@ export class DarwinWatcher extends EventEmitter implements PlatformWatcher {
   private roots: string[]
   private ignoreFn?: (path: string) => boolean
 
-  constructor(private options: PlatformWatcherOptions) {
+  constructor(options: PlatformWatcherOptions) {
     super()
-    this.roots = options.roots.map((r) => path.resolve(r))
-    this.ignoreFn = options.ignore_fn
+    const { roots, ignore_fn } = options
+    this.roots = roots.map((root) => path.resolve(root))
+    this.ignoreFn = ignore_fn
   }
 
   async start(): Promise<void> {
diff --git a/src/capture/platform/polling-watcher.ts b/src/capture/platform/polling-watcher.ts
index c058752..ccef21a 100644
--- a/src/capture/platform/polling-watcher.ts
+++ b/src/capture/platform/polling-watcher.ts
@@ -26,11 +26,12 @@ export class PollingWatcher extends EventEmitter implements PlatformWatcher {
   private intervalMs: number
   private pid: number
 
-  constructor(private options: PlatformWatcherOptions) {
+  constructor(options: PlatformWatcherOptions) {
     super()
-    this.roots = options.roots.map((r) => path.resolve(r))
-    this.ignoreFn = options.ignore_fn
-    this.intervalMs = options.poll_interval_ms ?? 300_000
+    const { roots, ignore_fn, poll_interval_ms } = options
+    this.roots = roots.map((root) => path.resolve(root))
+    this.ignoreFn = ignore_fn
+    this.intervalMs = poll_interval_ms ?? 300_000
     this.pid = process.pid
   }
 
diff --git a/src/session/session-manager.ts b/src/session/session-manager.ts
index 8c7df03..7c80bdc 100644
--- a/src/session/session-manager.ts
+++ b/src/session/session-manager.ts
@@ -14,16 +14,15 @@ export class SessionManager {
   private detector: SessionBoundaryDetector
   private activityWindowMs: number
 
-  constructor(private options: SessionManagerOptions) {
-    if (!Number.isFinite(options.idleThresholdMs) || options.idleThresholdMs <= 0) {
+  constructor(options: SessionManagerOptions) {
+    const { idleThresholdMs, activityWindowMs, boundaryDetector } = options
+
+    if (!Number.isFinite(idleThresholdMs) || idleThresholdMs <= 0) {
       throw new Error('idleThresholdMs must be positive')
     }
-    this.detector = options.boundaryDetector ?? new IdleBoundaryDetector(options.idleThresholdMs)
+    this.detector = boundaryDetector ?? new IdleBoundaryDetector(idleThresholdMs)
     // Clamp activityWindowMs to idleThresholdMs to prevent session overlap
-    this.activityWindowMs = Math.min(
-      options.activityWindowMs ?? options.idleThresholdMs,
-      options.idleThresholdMs,
-    )
+    this.activityWindowMs = Math.min(activityWindowMs ?? idleThresholdMs, idleThresholdMs)
   }
 
   groupEvents(events: UnifiedEvent[]): Session[] {
diff --git a/src/storage/timeline-db.ts b/src/storage/timeline-db.ts
index 7b11e23..4a9e874 100644
--- a/src/storage/timeline-db.ts
+++ b/src/storage/timeline-db.ts
@@ -33,7 +33,7 @@ export class TimelineDb implements DbContext {
   private summaries: SummaryRepository
   private stateRepo: StateRepository
 
-  constructor(private dbPath: string) {
+  constructor(dbPath: string) {
     fs.mkdirSync(path.dirname(dbPath), { recursive: true })
     this.db = new Database(dbPath, { create: true, strict: true })
     this.applyPragmas()
diff --git a/src/utils/format.ts b/src/utils/format.ts
index 0bc2c76..e51354b 100644
--- a/src/utils/format.ts
+++ b/src/utils/format.ts
@@ -1,7 +1,5 @@
 import path from 'node:path'
 
-import type { Session } from '../session/index.js'
-
 export function fmtTime(ms: number): string {
   const d = new Date(ms)
   return d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
@@ -20,14 +18,6 @@ export function fmtDurationMs(ms: number): string {
   return m ? `${h}h${m}m` : `${h}h`
 }
 
-export function sessionTitle(s: Session): string {
-  const c = s.context
-  if (c.kind === 'git') return `${c.name} (${c.branch || 'unknown'})`
-  if (c.kind === 'folder') return c.name || 'folder'
-  if (c.kind === 'app') return c.name || 'app'
-  return 'unknown'
-}
-
 export function shortFile(p: string): string {
   return path.basename(p)
 }

From 84f6648379c206f77f07590fffb91cd039ab8c36 Mon Sep 17 00:00:00 2001
From: Andy Pai <andy@r2pi.co>
Date: Fri, 20 Mar 2026 18:37:30 -0400
Subject: [PATCH 5/9] docs: move architecture docs under docs

---
 ARCHITECTURE.md => docs/ARCHITECTURE.md | 130 ++++--
 docs/wildcard-ai-usage.html             | 548 ++++++++++++++++++++++++
 docs/wildcard-event-pipeline.html       | 285 ++++++++++++
 3 files changed, 934 insertions(+), 29 deletions(-)
 rename ARCHITECTURE.md => docs/ARCHITECTURE.md (67%)
 create mode 100644 docs/wildcard-ai-usage.html
 create mode 100644 docs/wildcard-event-pipeline.html

diff --git a/ARCHITECTURE.md b/docs/ARCHITECTURE.md
similarity index 67%
rename from ARCHITECTURE.md
rename to docs/ARCHITECTURE.md
index 583dcc2..58c3ecb 100644
--- a/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1,10 +1,12 @@
 # Wildcard Architecture
 
+This document explains the current runtime layout in `src/`. For installation and day-to-day usage, see [README.md](../README.md). For the reporting workflow used by AI agents, see [SKILL.md](../SKILL.md).
+
 ## Overview
 
 Wildcard is a local-first CLI that captures file activity into a unified SQLite timeline. The built-in watch capture path emits `edit` file events; non-filesystem events (`ocr`, `audio`, `ui`) can be ingested via the bulk upload server.
 
-It groups events into sessions, generates cached heuristic/AI summaries, and supports external ingestion.
+It groups events into sessions, generates cached heuristic/AI summaries, supports device-aware queries, and can push pending local data to a central ingest server.
 
 ## System Diagram
 
@@ -18,7 +20,10 @@ It groups events into sessions, generates cached heuristic/AI summaries, and sup
   WatchRuntime orchestrates the full pipeline lifecycle
 
 [External Ingest Path (server)]
-  External producer -> bulk-upload-server (POST /bulk-upload) -> TimelineDb
+  External producer -> bulk-upload-server (POST /bulk-upload/v1) -> TimelineDb
+
+[Optional Sync Push Path]
+  TimelineDb -> BatchExtractor -> SyncClient -> POST /bulk-upload/v1
 
 [Local Storage]
   TimelineDb facade -> EventRepository, FileStateRepository, AppUsageRepository, SummaryRepository, StateRepository
@@ -27,6 +32,7 @@ It groups events into sessions, generates cached heuristic/AI summaries, and sup
 
 [Read / Report Path]
   TimelineDb -> QueryService -> SessionManager -> groupSessionsByProject -> SummaryBuilder -> wildcard CLI output
+  TimelineDb -> QueryService -> SessionManager -> bucketSessionsByTime -> groupFragmentsByProject -> wildcard log output
   SummaryBuilder <-> SummaryCache
   TimelineDb -> wildcard CLI output (direct app usage queries)
 ```
@@ -42,39 +48,43 @@ It groups events into sessions, generates cached heuristic/AI summaries, and sup
 7. Frontmost-app usage capture into `app_usage` time segments
 8. Data maintenance via `prune` and copy-only `archive`
 9. Optional HTTP bulk ingest (`src/server/bulk-upload-server.ts`)
-10. macOS launchd install/uninstall/restart helpers
+10. Optional one-shot sync push via `wildcard sync push`
+11. macOS launchd install/uninstall/restart helpers
+12. Chronological activity log via `wildcard log` with hourly/daily time-slot bucketing
 
 ## Module Layout (src/)
 
-| Module                  | Responsibility                                           | Key Exports                                                                        |
-| ----------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `src/wildcard.ts`       | CLI entrypoint (commander-based)                         | Registers all commands via `src/commands/`                                         |
-| `src/commands/`         | Command handlers and CLI helpers                         | `cmdWatch`, `cmdShow`, `cmdReport`, `cmdSearch`, `cmdStatus`, `cmdSetup`, etc.     |
-| `src/config/`           | Config loading, defaults, env overrides                  | `ConfigStore`, `WildcardConfig`, `default_config`                                  |
-| `src/capture/`          | Raw watcher events and normalization                     | `FileWatcher`, `Debouncer`, `FileNormalizer`, `IgnorePatterns`                     |
-| `src/capture/platform/` | Platform-specific watcher implementations                | `DarwinWatcher`, `PollingWatcher`, `createPlatformWatcher`                         |
-| `src/context/`          | Context resolution, frontmost app, primary context       | `ContextResolver`, `FrontmostAppCache`, `PrimaryContext`                           |
-| `src/runtime/`          | Watch pipeline orchestration and lifecycle               | `runWatchRuntime`, `WatchPipeline`, `WatchRuntimeOptions`                          |
-| `src/session/`          | Change tracking, app usage tracking, session/query logic | `ChangeTracker`, `AppUsageTracker`, `SessionManager`, `QueryService`               |
-| `src/storage/`          | SQLite repositories, FTS, state, blob integration        | `TimelineDb`, `EventRepository`, `FileStateRepository`, `AppUsageRepository`, etc. |
-| `src/summary/`          | Project grouping and summary generation/cache            | `SummaryBuilder`, `SummaryCache`, `groupSessionsByProject`                         |
-| `src/ai/`               | AI provider abstraction (AI SDK v6)                      | `createAiProvider`, `AiSdkProvider`                                                |
-| `src/server/`           | External bulk ingestion HTTP server                      | `bulk-upload-server.ts`                                                            |
-| `src/utils/`            | Time, formatting, store paths, process, AI factory       | `fmtTime`, `dayRange`, `storePaths`, `process.ts`, `ai-factory.ts`                 |
+| Module                  | Responsibility                                           | Key Exports                                                                                                                 |
+| ----------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `src/wildcard.ts`       | CLI entrypoint (commander-based)                         | Registers all commands via `src/commands/`                                                                                  |
+| `src/commands/`         | Command handlers and CLI helpers                         | `cmdWatch`, `cmdShow`, `cmdLog`, `cmdReport`, `cmdSearch`, `cmdStatus`, `cmdSetup`, `cmdArchive`, `cmdPrune`, `cmdSyncPush` |
+| `src/config/`           | Config loading, defaults, env overrides                  | `ConfigStore`, `WildcardConfig`, `defaultConfig`                                                                            |
+| `src/capture/`          | Raw watcher events and normalization                     | `FileWatcher`, `Debouncer`, `FileNormalizer`, `IgnorePatterns`                                                              |
+| `src/capture/platform/` | Platform-specific watcher implementations                | `DarwinWatcher`, `PollingWatcher`, `createPlatformWatcher`                                                                  |
+| `src/context/`          | Context resolution, frontmost app, primary context       | `ContextResolver`, `FrontmostAppCache`, `PrimaryContext`                                                                    |
+| `src/runtime/`          | Watch pipeline orchestration and lifecycle               | `runWatchRuntime`, `WatchPipeline`, `WatchRuntimeOptions`                                                                   |
+| `src/session/`          | Change tracking, app usage tracking, session/query logic | `ChangeTracker`, `AppUsageTracker`, `SessionManager`, `QueryService`, `bucketSessionsByTime`, `groupFragmentsByProject`     |
+| `src/storage/`          | SQLite repositories, FTS, state, blob integration        | `TimelineDb`, `EventRepository`, `FileStateRepository`, `AppUsageRepository`, etc.                                          |
+| `src/summary/`          | Project grouping and summary generation/cache            | `SummaryBuilder`, `SummaryCache`, `groupSessionsByProject`                                                                  |
+| `src/ai/`               | AI provider abstraction (AI SDK v6)                      | `createAiProvider`, `AiSdkProvider`                                                                                         |
+| `src/sync/`             | Batch extraction and remote upload                       | `SyncEngine`, `BatchExtractor`, `SyncClient`                                                                                |
+| `src/server/`           | External bulk ingestion HTTP server                      | `bulk-upload-server.ts`                                                                                                     |
+| `src/utils/`            | Time, formatting, store paths, process, AI factory       | `fmtTime`, `dayRange`, `storePaths`, `process.ts`, `ai-factory.ts`                                                          |
 
 ### `src/commands/` breakdown
 
 The former `shared.ts` has been split into focused modules:
 
-| File                 | Contents                                   |
-| -------------------- | ------------------------------------------ |
-| `types.ts`           | Shared option types (`PeriodFlags`, etc.)  |
-| `period.ts`          | Period parsing and date range logic        |
-| `formatters.ts`      | Output formatting helpers                  |
-| `cli-helpers.ts`     | Common CLI plumbing (db init, config load) |
-| `launchd-helpers.ts` | macOS launchd plist helpers                |
+| File                 | Contents                                           |
+| -------------------- | -------------------------------------------------- |
+| `types.ts`           | Shared option types (`PeriodFlags`, etc.)          |
+| `period.ts`          | Period parsing and date range logic                |
+| `formatters.ts`      | Output formatting helpers                          |
+| `cli-helpers.ts`     | Common CLI plumbing (db init, config load)         |
+| `launchd-helpers.ts` | macOS launchd plist helpers                        |
+| `activity-log.ts`    | `log` command: time-slot rendering and JSON output |
 
-Note: `src/screenpipe/` is not part of the active runtime architecture.
+Note: legacy references to Screenpipe still exist in older notes, but the active runtime architecture lives under `src/`.
 
 ## Data Model
 
@@ -95,6 +105,7 @@ interface UnifiedEvent {
   sourceId: string
   eventType: EventType
   eventSubtype?: string
+  deviceId?: string
   context: EventContext
   data: Record<string, any>
   metadata?: Record<string, any>
@@ -120,6 +131,36 @@ type Session = {
 }
 ```
 
+### SessionFragment
+
+```ts
+type SessionFragment = {
+  session: Session
+  start_ts: number
+  end_ts: number
+  duration_ms: number
+  edit_count: number
+  file_paths: string[]
+}
+```
+
+A slice of a `Session` clipped to a single time bucket. Sessions spanning bucket boundaries produce one fragment per bucket; `edit_count` is assigned to the fragment whose bucket contains the session's `start_ts`.
+
+### SlotProjectEntry
+
+```ts
+type SlotProjectEntry = {
+  project_key: string
+  display_name: string
+  branches: string[]
+  duration_ms: number
+  edit_count: number
+  file_count: number
+}
+```
+
+Aggregated view of all fragments for one project within a single time slot. Produced by `groupFragmentsByProject`.
+
 ## Pipelines
 
 ### Watch Capture Pipeline
@@ -140,12 +181,22 @@ WatchRuntime (src/runtime/) -> WatchPipeline:
 ### External Bulk Ingest Pipeline
 
 ```text
-External Producer -> bulk-upload-server(/bulk-upload) -> TimelineDb
+External Producer -> bulk-upload-server(/bulk-upload/v1) -> TimelineDb
 ```
 
-- `src/server/bulk-upload-server.ts` accepts JSON arrays of `UnifiedEvent`.
+- `src/server/bulk-upload-server.ts` accepts a JSON object with `device_id`, `events`, `app_usage`, and optional `client_checkpoint`.
 - Default server DB path is `~/.wildcard/archive.db` unless `WILDCARD_DB_PATH` is set.
-- This path can insert `ocr` / `audio` / `ui` events even though local file watching emits `edit` events.
+- This path can insert `ocr` / `audio` / `ui` events and frontmost-app usage segments, even though local file watching emits `edit` events.
+
+### Sync Push Pipeline
+
+```text
+TimelineDb -> BatchExtractor -> SyncClient -> POST /bulk-upload/v1
+```
+
+- `wildcard sync push` uploads pending local `events` and `app_usage` rows.
+- Progress is tracked with rowid cursors in the `state` table (`sync.events.cursor_rowid`, `sync.app_usage.cursor_rowid`).
+- Device identity comes from `identity.device_id` (or defaults to `local` if unset).
 
 ### Query + Reporting Pipeline
 
@@ -157,6 +208,17 @@ TimelineDb -> QueryService -> SessionManager -> groupSessionsByProject -> Summar
 - `report` uses `SummaryBuilder.summarizeReportWithMeta`, optionally with AI.
 - `SummaryCache` stores session one-liners and daily report markdown.
 
+### Log (Time-Bucketing) Pipeline
+
+```text
+TimelineDb -> QueryService -> SessionManager -> bucketSessionsByTime -> groupFragmentsByProject -> Output
+```
+
+- `log` splits sessions into 1-hour buckets (today/yesterday) or 1-day buckets (week).
+- Sessions spanning a bucket boundary are split proportionally; `edit_count` stays with the start bucket.
+- `groupFragmentsByProject` merges fragments within each slot by project key, deduplicating files and branches.
+- Output is formatted text or JSON (`--json`).
+
 ### Frontmost App Usage Pipeline
 
 ```text
@@ -262,12 +324,22 @@ CLI/runtime environment variable overrides:
 - `WILDCARD_AI_MODEL`
 - `WILDCARD_AI_BASE_URL`
 - `WILDCARD_AI_API_KEY` (fallbacks: `OPENAI_API_KEY` for OpenAI, `GEMINI_API_KEY` for Gemini)
+- `WILDCARD_DEVICE_ID`
+- `WILDCARD_SYNC_ENABLED`
+- `WILDCARD_SYNC_SERVER_URL`
+- `WILDCARD_SYNC_API_KEY`
+- `WILDCARD_SYNC_BATCH_SIZE`
+- `WILDCARD_SYNC_MAX_PAYLOAD_BYTES`
+- `WILDCARD_SYNC_INTERVAL_S`
+- `WILDCARD_SYNC_MAX_RETRIES`
+- `WILDCARD_SYNC_BATCH_DELAY_MS`
 
 Bulk upload server environment variables:
 
 - `PORT`
 - `MAX_BODY_SIZE`
 - `WILDCARD_API_KEY`
+- `WILDCARD_ALLOWED_DEVICES`
 - `WILDCARD_DB_PATH`
 
 Notes:
diff --git a/docs/wildcard-ai-usage.html b/docs/wildcard-ai-usage.html
new file mode 100644
index 0000000..339d0f2
--- /dev/null
+++ b/docs/wildcard-ai-usage.html
@@ -0,0 +1,548 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>AI in Wildcard — Usage &amp; Architecture</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=Merriweather:wght@400;700&display=swap" rel="stylesheet">
+<script>
+  (function() {
+    var stored = localStorage.getItem('theme');
+    if (stored === 'dark') document.documentElement.classList.add('dark');
+  })();
+</script>
+<script src="https://cdn.tailwindcss.com"></script>
+<script>
+tailwind.config = {
+  darkMode: 'class',
+  theme: {
+    extend: {
+      fontFamily: {
+        serif: ['Merriweather', 'Georgia', 'serif'],
+        sans: ['Inter', 'system-ui', 'sans-serif'],
+      },
+      colors: {
+        accent: { DEFAULT: '#b45309', light: '#fef3c7' },
+      },
+      animation: {
+        'fade-in': 'fadeIn 0.4s ease forwards',
+        'fade-in-soft': 'fadeInSoft 0.6s ease forwards',
+      },
+      keyframes: {
+        fadeIn: {
+          from: { opacity: '0', transform: 'translateY(4px)' },
+          to: { opacity: '1', transform: 'translateY(0)' },
+        },
+        fadeInSoft: {
+          from: { opacity: '0' },
+          to: { opacity: '1' },
+        },
+      },
+    },
+  },
+}
+</script>
+<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+<style>
+  ::-webkit-scrollbar { width: 6px; }
+  ::-webkit-scrollbar-track { background: transparent; }
+  ::-webkit-scrollbar-thumb { background: #cbd5e1; border-radius: 3px; }
+  .dark ::-webkit-scrollbar-thumb { background: #334155; }
+  ::selection { background: #fef3c7; color: #78350f; }
+  .dark ::selection { background: #78350f; color: #fef3c7; }
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after {
+      animation-duration: 0.01ms !important;
+      transition-duration: 0.01ms !important;
+    }
+  }
+  .mermaid-out svg { max-width: 100%; height: auto; }
+</style>
+</head>
+<body class="bg-white dark:bg-slate-950 text-slate-900 dark:text-slate-100 min-h-screen">
+<div id="app"></div>
+<script type="module">
+import { h, render } from 'https://esm.sh/preact@10';
+import { useState, useEffect, useRef } from 'https://esm.sh/preact@10/hooks';
+import htm from 'https://esm.sh/htm@3';
+
+const html = htm.bind(h);
+
+// ─── Mermaid init ──────────────────────────────────────────────────────────────
+mermaid.initialize({
+  startOnLoad: false,
+  theme: 'base',
+  themeVariables: {
+    primaryColor: '#f1f5f9',
+    primaryTextColor: '#0f172a',
+    primaryBorderColor: '#cbd5e1',
+    lineColor: '#94a3b8',
+    background: '#ffffff',
+    mainBkg: '#f1f5f9',
+    nodeBorder: '#cbd5e1',
+    clusterBkg: '#f8fafc',
+    titleColor: '#0f172a',
+    edgeLabelBackground: '#ffffff',
+    fontFamily: 'Inter, system-ui, sans-serif',
+  },
+});
+
+// ─── Mermaid diagram definition ────────────────────────────────────────────────
+const archLines = [
+  'flowchart TD',
+  '  cli["activity-report CLI\\n--no-ai flag"] --> factory["tryCreateAiProvider()"]',
+  '  factory --> prov{"Provider?"}',
+  '  prov -->|ollama| ol["Ollama\\nqwen3:8b"]',
+  '  prov -->|openai| oa["OpenAI\\ngpt-5.4-mini"]',
+  '  prov -->|gemini| gm["Gemini\\ngemini-3.1-flash-lite-preview"]',
+  '  ol --> sdk["AiSdkProvider\\n.complete(messages)"]',
+  '  oa --> sdk',
+  '  gm --> sdk',
+  '  sdk --> sb["SummaryBuilder"]',
+  '  sb --> l1["Session Summaries\\n2-4 bullets · 200 tok"]',
+  '  sb --> l2["Project Summaries\\nmerge sessions · 200 tok"]',
+  '  sb --> l3["Daily Synthesis\\n2-3 sentences · 150 tok"]',
+  '  l1 --> sc["SummaryCache\\nSHA-256 hash"]',
+  '  l2 --> sc',
+  '  l3 --> sc',
+  '  sc --> rpt["Markdown Report"]',
+];
+const ARCH_DIAGRAM = archLines.join('\n');
+
+// ─── Visual component data ─────────────────────────────────────────────────────
+const PROVIDERS = [
+  {
+    name: 'Ollama',
+    model: 'qwen3:8b',
+    tag: 'Local · Free',
+    border: 'border-emerald-200 dark:border-emerald-800',
+    bg: 'bg-emerald-50 dark:bg-emerald-900/20',
+    badge: 'bg-emerald-100 text-emerald-700 dark:bg-emerald-900/50 dark:text-emerald-300',
+    default: true,
+  },
+  {
+    name: 'OpenAI',
+    model: 'gpt-5.4-mini',
+    tag: 'Cloud · API key',
+    border: 'border-blue-200 dark:border-blue-800',
+    bg: 'bg-blue-50 dark:bg-blue-900/20',
+    badge: 'bg-blue-100 text-blue-700 dark:bg-blue-900/50 dark:text-blue-300',
+    default: false,
+  },
+  {
+    name: 'Gemini',
+    model: 'gemini-3.1-flash-lite-preview',
+    tag: 'Cloud · API key',
+    border: 'border-purple-200 dark:border-purple-800',
+    bg: 'bg-purple-50 dark:bg-purple-900/20',
+    badge: 'bg-purple-100 text-purple-700 dark:bg-purple-900/50 dark:text-purple-300',
+    default: false,
+  },
+];
+
+const SDK_LABEL = 'Vercel AI SDK abstraction';
+const SDK_WRAPPER = 'AiSdkProvider · .complete(messages, options)';
+const SDK_PARAMS = 'max_tokens · temperature · timeout: 60s';
+
+const FUNNEL_LEVELS = [
+  {
+    num: 1,
+    label: 'Session Summaries',
+    desc: '2-4 bullet points per session',
+    tokens: '200 tok',
+    temp: '0.2',
+    width: 'w-full',
+    bg: 'bg-slate-100 dark:bg-slate-800',
+    border: 'border-slate-300 dark:border-slate-600',
+    many: 'many',
+  },
+  {
+    num: 2,
+    label: 'Project Summaries',
+    desc: 'merge overlapping sessions by project',
+    tokens: '200 tok',
+    temp: '0.2',
+    width: 'w-4/5',
+    bg: 'bg-blue-50 dark:bg-blue-900/30',
+    border: 'border-blue-200 dark:border-blue-700',
+    many: 'fewer',
+  },
+  {
+    num: 3,
+    label: 'Daily Synthesis',
+    desc: '2-3 sentences across all projects',
+    tokens: '150 tok',
+    temp: '0.2',
+    width: 'w-3/5',
+    bg: 'bg-violet-50 dark:bg-violet-900/30',
+    border: 'border-violet-200 dark:border-violet-700',
+    many: 'one',
+  },
+];
+
+const PROMPTS = [
+  {
+    level: 'Session',
+    system: 'Summarize this work session in 2-4 bullet points. Keep it concrete. Avoid fluff.',
+    context: 'duration · edit count · active apps · window titles · up to 30 files · OCR snippets · audio transcripts',
+    border: 'border-slate-200 dark:border-slate-700',
+    tag: 'bg-slate-100 text-slate-600 dark:bg-slate-800 dark:text-slate-400',
+  },
+  {
+    level: 'Project',
+    system: 'Summarize work on this project in 2-4 bullet points. Merge overlapping activities. Be concrete and specific.',
+    context: 'project name · duration · edit count · file basenames · up to 10 session summaries',
+    border: 'border-blue-200 dark:border-blue-700',
+    tag: 'bg-blue-100 text-blue-600 dark:bg-blue-900/30 dark:text-blue-400',
+  },
+  {
+    level: 'Daily',
+    system: "Write a 2-3 sentence summary of the day's work. Focus on themes and accomplishments. No fluff.",
+    context: 'total active time · project count · all per-project summaries',
+    border: 'border-violet-200 dark:border-violet-700',
+    tag: 'bg-violet-100 text-violet-600 dark:bg-violet-900/30 dark:text-violet-400',
+  },
+];
+
+const HIT_STEPS = [
+  'Request daily report',
+  'Check SummaryCache by session_id',
+  'event_count matches',
+  'events_hash (SHA-256) matches',
+  'Return cached summary ✓',
+];
+
+const MISS_STEPS = [
+  'Request daily report',
+  'Check SummaryCache by session_id',
+  'Hash mismatch — session changed',
+  'Call AI provider',
+  'Store result, return fresh summary',
+];
+
+const AI_PATH = [
+  'CLI: activity-report',
+  'tryCreateAiProvider(config)',
+  'Provider initialized OK',
+  'SummaryBuilder with AI',
+  'Call LLM for each level',
+  'Rich, synthesized summaries',
+];
+
+const HEU_PATH = [
+  'CLI: activity-report --no-ai',
+  'tryCreateAiProvider(config)',
+  'Disabled or API error → null',
+  'SummaryBuilder without AI',
+  'Rule-based heuristics',
+  'Deterministic text summaries',
+];
+
+// ─── Step metadata ─────────────────────────────────────────────────────────────
+const TITLES = [
+  'System Architecture',
+  'Provider Layer',
+  'Summarization Funnel',
+  'Prompt Design',
+  'Cache Strategy',
+  'Graceful Degradation',
+];
+
+const BODIES = [
+  'AI is used exclusively at report time — never during data capture. Raw events are always stored heuristically; the LLM only runs when generating the markdown activity report.',
+  'Three AI backends unify behind a Vercel AI SDK adapter. The rest of the codebase calls .complete() on AiSdkProvider and never knows which backend it is talking to.',
+  'Summarization flows through three levels: individual sessions are summarized first (many), then grouped and re-summarized by project (fewer), then synthesized into a single daily overview. Each level consumes the level below as context.',
+  'Each of the three levels has a focused system prompt that forbids fluff and caps the output. Low temperature (0.2) across all calls keeps output factual and consistent.',
+  'Every session summary is cached using a SHA-256 hash of its event IDs, timestamps, and data. A daily cache wraps the full report. Only changed sessions regenerate — unchanged sessions are served from cache.',
+  'If AI is disabled via --no-ai, missing from config, or throws at runtime, the system silently falls back to deterministic heuristic summaries. The report works without AI — AI is purely additive.',
+];
+
+// ─── Visual Components ─────────────────────────────────────────────────────────
+function MermaidChart() {
+  const ref = useRef(null);
+  useEffect(() => {
+    if (!ref.current) return;
+    const uid = 'mch-' + Math.random().toString(36).slice(2, 8);
+    setTimeout(function() {
+      mermaid.render(uid, ARCH_DIAGRAM)
+        .then(function(result) {
+          if (ref.current) ref.current.innerHTML = result.svg;
+        })
+        .catch(function(err) {
+          if (ref.current) ref.current.textContent = 'Diagram unavailable';
+        });
+    }, 80);
+  }, []);
+  return html`<div ref=${ref} class="mermaid-out w-full px-6 text-center text-slate-400 text-xs font-mono">Loading…</div>`;
+}
+
+function ProviderCards() {
+  return html`
+    <div class="flex flex-col items-center gap-3 w-full px-5">
+      <div class="flex gap-2 w-full">
+        ${PROVIDERS.map(p => html`
+          <div key=${p.name} class=${'flex-1 rounded-xl border p-3 text-center ' + p.bg + ' ' + p.border}>
+            <div class="font-semibold text-sm">${p.name}</div>
+            <div class="font-mono text-xs text-slate-500 dark:text-slate-400 mt-0.5">${p.model}</div>
+            <span class=${'inline-block mt-2 text-xs px-2 py-0.5 rounded-full font-medium ' + p.badge}>${p.tag}</span>
+            ${p.default ? html`<div class="text-xs text-slate-400 mt-1">default</div>` : html`<div class="text-xs text-transparent mt-1">-</div>`}
+          </div>
+        `)}
+      </div>
+      <div class="text-slate-400 text-xs font-mono">↓ unified via</div>
+      <div class="rounded-xl border border-amber-300 dark:border-amber-700 bg-amber-50 dark:bg-amber-900/20 px-5 py-3 text-center w-full">
+        <div class="text-xs text-amber-600 dark:text-amber-400 font-mono uppercase tracking-wider mb-1">${SDK_LABEL}</div>
+        <div class="font-semibold text-sm">${SDK_WRAPPER}</div>
+        <div class="text-xs text-slate-400 font-mono mt-1">${SDK_PARAMS}</div>
+      </div>
+    </div>`;
+}
+
+function SummarizationFunnel() {
+  return html`
+    <div class="flex flex-col items-center gap-2 w-full px-5">
+      ${FUNNEL_LEVELS.map((l, i) => html`
+        <div key=${l.num} class="flex flex-col items-center w-full">
+          <div class=${'flex items-center justify-between rounded-xl border px-4 py-3 ' + l.width + ' ' + l.bg + ' ' + l.border}>
+            <div>
+              <div class="flex items-center gap-2 mb-0.5">
+                <span class="font-mono text-xs text-slate-400">L${l.num}</span>
+                <span class="font-semibold text-sm">${l.label}</span>
+              </div>
+              <div class="text-xs text-slate-500 dark:text-slate-400">${l.desc}</div>
+            </div>
+            <div class="text-right shrink-0 ml-3 space-y-1">
+              <div class="font-mono text-xs bg-white/70 dark:bg-slate-900/70 rounded px-1.5 py-0.5 border border-slate-200/60 dark:border-slate-700/60">${l.tokens}</div>
+              <div class="font-mono text-xs text-slate-400">temp ${l.temp}</div>
+              <div class="text-xs text-slate-400 italic">${l.many}</div>
+            </div>
+          </div>
+          ${i < FUNNEL_LEVELS.length - 1 ? html`<div class="text-slate-300 dark:text-slate-600 text-xs font-mono mt-1">↓ feeds into</div>` : null}
+        </div>
+      `)}
+    </div>`;
+}
+
+function PromptCards() {
+  return html`
+    <div class="flex flex-col gap-2 w-full px-5">
+      ${PROMPTS.map(p => html`
+        <div key=${p.level} class=${'rounded-xl border p-3 ' + p.border}>
+          <div class="flex items-center gap-2 mb-1.5">
+            <span class=${'font-mono text-xs px-2 py-0.5 rounded font-medium ' + p.tag}>${p.level}</span>
+            <span class="text-xs text-slate-400">system prompt</span>
+          </div>
+          <p class="text-xs font-mono text-slate-700 dark:text-slate-300 italic leading-relaxed">"${p.system}"</p>
+          <div class="mt-1.5 text-xs text-slate-400 font-mono leading-snug">context: ${p.context}</div>
+        </div>
+      `)}
+    </div>`;
+}
+
+function stepClass(i, kind) {
+  if (kind === 'hit') {
+    if (i === 0) return 'bg-slate-100 dark:bg-slate-800 text-slate-500';
+    if (i < 3) return 'bg-emerald-100 dark:bg-emerald-900/40 text-emerald-600 dark:text-emerald-400';
+    return 'bg-emerald-500 text-white';
+  }
+  if (i === 0) return 'bg-slate-100 dark:bg-slate-800 text-slate-500';
+  if (i === 2) return 'bg-orange-100 dark:bg-orange-900/40 text-orange-600 dark:text-orange-400';
+  if (i === 3) return 'bg-blue-100 dark:bg-blue-900/40 text-blue-600 dark:text-blue-400';
+  if (i === 4) return 'bg-emerald-500 text-white';
+  return 'bg-slate-100 dark:bg-slate-800 text-slate-500';
+}
+
+function CachingDiagram() {
+  return html`
+    <div class="flex gap-4 w-full px-5">
+      <div class="flex-1">
+        <div class="text-xs font-mono text-emerald-600 dark:text-emerald-400 mb-2.5 text-center font-medium">Cache HIT</div>
+        ${HIT_STEPS.map((s, i) => html`
+          <div key=${s} class="flex items-start gap-2 mb-2">
+            <div class=${'w-5 h-5 rounded-full flex items-center justify-center shrink-0 text-xs font-mono font-medium ' + stepClass(i, 'hit')}>${i+1}</div>
+            <div class="text-xs text-slate-600 dark:text-slate-400 leading-tight pt-0.5">${s}</div>
+          </div>
+        `)}
+      </div>
+      <div class="w-px bg-slate-200 dark:bg-slate-700 self-stretch"></div>
+      <div class="flex-1">
+        <div class="text-xs font-mono text-orange-600 dark:text-orange-400 mb-2.5 text-center font-medium">Cache MISS</div>
+        ${MISS_STEPS.map((s, i) => html`
+          <div key=${s} class="flex items-start gap-2 mb-2">
+            <div class=${'w-5 h-5 rounded-full flex items-center justify-center shrink-0 text-xs font-mono font-medium ' + stepClass(i, 'miss')}>${i+1}</div>
+            <div class="text-xs text-slate-600 dark:text-slate-400 leading-tight pt-0.5">${s}</div>
+          </div>
+        `)}
+      </div>
+    </div>`;
+}
+
+function fallbackStepClass(i, kind) {
+  if (kind === 'ai') {
+    if (i === 0) return 'bg-slate-100 dark:bg-slate-800 text-slate-500';
+    if (i < 4) return 'bg-blue-100 dark:bg-blue-900/40 text-blue-600 dark:text-blue-400';
+    return 'bg-blue-500 text-white';
+  }
+  if (i === 0) return 'bg-slate-100 dark:bg-slate-800 text-slate-500';
+  if (i === 2) return 'bg-orange-100 dark:bg-orange-900/40 text-orange-600 dark:text-orange-400';
+  if (i === 3) return 'bg-slate-200 dark:bg-slate-700 text-slate-600 dark:text-slate-400';
+  if (i === 4) return 'bg-slate-400 dark:bg-slate-600 text-white';
+  if (i === 5) return 'bg-slate-400 dark:bg-slate-600 text-white';
+  return 'bg-slate-100 dark:bg-slate-800 text-slate-500';
+}
+
+function FallbackDiagram() {
+  return html`
+    <div class="flex gap-4 w-full px-5">
+      <div class="flex-1">
+        <div class="text-xs font-mono text-blue-600 dark:text-blue-400 mb-2.5 text-center font-medium">AI Path</div>
+        ${AI_PATH.map((s, i) => html`
+          <div key=${s} class="flex items-start gap-2 mb-2">
+            <div class=${'w-5 h-5 rounded-full flex items-center justify-center shrink-0 text-xs font-mono font-medium ' + fallbackStepClass(i, 'ai')}>${i+1}</div>
+            <div class="text-xs text-slate-600 dark:text-slate-400 leading-tight pt-0.5">${s}</div>
+          </div>
+        `)}
+      </div>
+      <div class="w-px bg-slate-200 dark:bg-slate-700 self-stretch"></div>
+      <div class="flex-1">
+        <div class="text-xs font-mono text-slate-500 mb-2.5 text-center font-medium">Heuristic Fallback</div>
+        ${HEU_PATH.map((s, i) => html`
+          <div key=${s} class="flex items-start gap-2 mb-2">
+            <div class=${'w-5 h-5 rounded-full flex items-center justify-center shrink-0 text-xs font-mono font-medium ' + fallbackStepClass(i, 'heu')}>${i+1}</div>
+            <div class="text-xs text-slate-600 dark:text-slate-400 leading-tight pt-0.5">${s}</div>
+          </div>
+        `)}
+      </div>
+    </div>`;
+}
+
+function VisualPanel({ step }) {
+  if (step === 0) return html`<${MermaidChart} />`;
+  if (step === 1) return html`<${ProviderCards} />`;
+  if (step === 2) return html`<${SummarizationFunnel} />`;
+  if (step === 3) return html`<${PromptCards} />`;
+  if (step === 4) return html`<${CachingDiagram} />`;
+  return html`<${FallbackDiagram} />`;
+}
+
+// ─── Nav components ────────────────────────────────────────────────────────────
+function StepDots({ current, total, onSelect }) {
+  return html`
+    <div class="flex gap-1.5">
+      ${Array.from({ length: total }, (_, i) => html`
+        <button
+          key=${i}
+          onClick=${() => onSelect(i)}
+          aria-label=${'Step ' + (i + 1)}
+          class="h-6 flex items-center justify-center"
+        >
+          <span class=${'block h-1.5 rounded-full transition-all duration-300 ' + (i === current ? 'w-6 bg-amber-600' : 'w-1.5 bg-slate-300 dark:bg-slate-600')} />
+        </button>
+      `)}
+    </div>`;
+}
+
+function StepControls({ current, total, onPrev, onNext }) {
+  return html`
+    <div class="flex gap-2">
+      <button
+        onClick=${onPrev}
+        disabled=${current === 0}
+        class="w-8 h-8 rounded-lg border border-slate-200 dark:border-slate-700 flex items-center justify-center text-slate-500 hover:bg-slate-50 dark:hover:bg-slate-800 disabled:opacity-25 transition-colors"
+        aria-label="Previous"
+      >
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m15 18-6-6 6-6"/></svg>
+      </button>
+      <button
+        onClick=${onNext}
+        disabled=${current === total - 1}
+        class="h-8 px-3 rounded-lg bg-slate-900 dark:bg-slate-100 text-white dark:text-slate-900 text-sm font-semibold flex items-center gap-1.5 disabled:opacity-25 transition-colors"
+        aria-label="Next"
+      >
+        Next
+        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m9 18 6-6-6-6"/></svg>
+      </button>
+    </div>`;
+}
+
+function ThemeToggle() {
+  const [dark, setDark] = useState(document.documentElement.classList.contains('dark'));
+  const toggle = () => {
+    const next = !dark;
+    document.documentElement.classList.toggle('dark', next);
+    localStorage.setItem('theme', next ? 'dark' : 'light');
+    setDark(next);
+  };
+  return html`
+    <button onClick=${toggle} aria-label=${dark ? 'Switch to light mode' : 'Switch to dark mode'}
+      class="w-8 h-8 rounded-lg border border-slate-200 dark:border-slate-700 flex items-center justify-center text-slate-400 hover:text-slate-600 dark:hover:text-slate-300 hover:bg-slate-50 dark:hover:bg-slate-800 transition-colors">
+      ${dark
+        ? html`<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/><line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/></svg>`
+        : html`<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>`
+      }
+    </button>`;
+}
+
+// ─── App ────────────────────────────────────────────────────────────────────────
+function App() {
+  const [step, setStep] = useState(0);
+  const total = TITLES.length;
+  const pad = n => String(n).padStart(2, '0');
+  const go = i => setStep(Math.max(0, Math.min(i, total - 1)));
+  const title = TITLES[step];
+  const body = BODIES[step];
+
+  return html`
+    <div class="max-w-2xl mx-auto px-6 py-16">
+
+      <div class="flex items-center justify-between mb-6">
+        <p class="font-mono text-xs uppercase tracking-widest text-slate-400 dark:text-slate-500">
+          Wildcard <span class="mx-1.5 text-slate-300 dark:text-slate-600">/</span> AI Usage
+        </p>
+        <${ThemeToggle} />
+      </div>
+
+      <div class="bg-white dark:bg-slate-900 rounded-2xl border border-slate-200 dark:border-slate-800 shadow-sm overflow-hidden">
+
+        <div class="relative bg-slate-50 dark:bg-slate-800/50 min-h-72 flex items-center justify-center border-b border-slate-200 dark:border-slate-800 py-7">
+          <div key=${step} class="animate-fade-in-soft w-full">
+            <${VisualPanel} step=${step} />
+          </div>
+          <span class="absolute bottom-3 left-3 font-mono text-[10px] text-slate-400 dark:text-slate-500 bg-slate-100 dark:bg-slate-800 px-2 py-0.5 rounded">
+            ${pad(step + 1)} / ${pad(total)}
+          </span>
+        </div>
+
+        <div class="p-8" key=${step}>
+          <h2 class="font-serif text-2xl font-bold text-slate-900 dark:text-slate-100 mb-2 animate-fade-in">
+            ${title}
+          </h2>
+          <p class="font-serif text-lg leading-relaxed text-slate-600 dark:text-slate-400 animate-fade-in" style="animation-delay: 80ms; opacity: 0;">
+            ${body}
+          </p>
+        </div>
+
+        <div class="flex items-center justify-between px-8 pb-8">
+          <${StepDots} current=${step} total=${total} onSelect=${go} />
+          <${StepControls} current=${step} total=${total} onPrev=${() => go(step - 1)} onNext=${() => go(step + 1)} />
+        </div>
+
+      </div>
+    </div>`;
+}
+
+// ─── Keyboard nav ───────────────────────────────────────────────────────────────
+document.addEventListener('keydown', e => {
+  if (e.metaKey || e.ctrlKey || e.altKey) return;
+  const tag = (e.target.tagName || '').toLowerCase();
+  if (tag === 'input' || tag === 'textarea' || tag === 'select' || e.target.isContentEditable) return;
+  if (e.key === 'ArrowRight') document.querySelector('[aria-label="Next"]')?.click();
+  if (e.key === 'ArrowLeft') document.querySelector('[aria-label="Previous"]')?.click();
+});
+
+render(html`<${App} />`, document.getElementById('app'));
+</script>
+</body>
+</html>
diff --git a/docs/wildcard-event-pipeline.html b/docs/wildcard-event-pipeline.html
new file mode 100644
index 0000000..93c60cf
--- /dev/null
+++ b/docs/wildcard-event-pipeline.html
@@ -0,0 +1,285 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Wildcard — Event Pipeline</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=Merriweather:wght@400;700&display=swap" rel="stylesheet">
+<script>
+  (function() {
+    var stored = localStorage.getItem('theme');
+    if (stored === 'dark') document.documentElement.classList.add('dark');
+  })();
+</script>
+<script src="https://cdn.tailwindcss.com"></script>
+<script>
+tailwind.config = {
+  darkMode: 'class',
+  theme: {
+    extend: {
+      fontFamily: {
+        serif: ['Merriweather', 'Georgia', 'serif'],
+        sans: ['Inter', 'system-ui', 'sans-serif'],
+      },
+      colors: {
+        accent: { DEFAULT: '#b45309', light: '#fef3c7' },
+      },
+      animation: {
+        'fade-in': 'fadeIn 0.4s ease forwards',
+      },
+      keyframes: {
+        fadeIn: {
+          from: { opacity: '0', transform: 'translateY(4px)' },
+          to: { opacity: '1', transform: 'translateY(0)' },
+        },
+      },
+    },
+  },
+}
+</script>
+<style>
+  :root { --bg: #fff; --text: #0f172a; --text-dim: #64748b; }
+  .dark { --bg: #020617; --text: #f1f5f9; --text-dim: #94a3b8; }
+  ::-webkit-scrollbar { width: 6px; }
+  ::-webkit-scrollbar-track { background: transparent; }
+  ::-webkit-scrollbar-thumb { background: #cbd5e1; border-radius: 3px; }
+  .dark ::-webkit-scrollbar-thumb { background: #334155; }
+  ::selection { background: #fef3c7; color: #78350f; }
+  .dark ::selection { background: #78350f; color: #fef3c7; }
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after { animation-duration: 0.01ms !important; }
+  }
+  #mermaid-chart svg { max-width: 100%; height: auto; }
+  #mermaid-chart .nodeLabel { color: var(--text) !important; }
+  #mermaid-chart .edgeLabel { color: var(--text-dim) !important; background-color: var(--bg) !important; }
+  #mermaid-chart .edgeLabel rect { fill: var(--bg) !important; }
+</style>
+</head>
+<body class="bg-white dark:bg-slate-950 text-slate-900 dark:text-slate-100 min-h-screen">
+<div id="app"></div>
+<script type="module">
+import { h, render } from 'https://esm.sh/preact@10';
+import { useState, useEffect } from 'https://esm.sh/preact@10/hooks';
+import htm from 'https://esm.sh/htm@3';
+import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+
+const html = htm.bind(h);
+
+// ─── Mermaid chart definition ─────────────────────────
+const CHART_LINES = [
+  'flowchart TD',
+  '  subgraph cap["Capture"]',
+  '    fw["FileWatcher"] --> deb["Debouncer"]',
+  '    aat["AppUsageTracker"]',
+  '  end',
+  '  subgraph proc["Pipeline"]',
+  '    norm["FileNormalizer"] --> ct["ChangeTracker"]',
+  '  end',
+  '  subgraph stor["Storage"]',
+  '    tdb["TimelineDb"]',
+  '    bs["BlobStore"]',
+  '  end',
+  '  subgraph rep["Reports"]',
+  '    qs["QueryService"] --> sm["SessionManager"]',
+  '    sm --> cmds["log / show / report"]',
+  '    tdb --> srch["search"]',
+  '  end',
+  '  deb --> norm',
+  '  ct -->|event| tdb',
+  '  ct -->|blob| bs',
+  '  aat -->|segment| tdb',
+  '  tdb --> qs',
+];
+const CHART_DEF = CHART_LINES.join('\n');
+
+// ─── Phase detail data ────────────────────────────────
+const PHASES = [
+  {
+    id: 'capture',
+    label: '01 Capture',
+    color: 'blue',
+    file: 'runtime/watch-pipeline-ingest.ts',
+    title: 'File System Capture',
+    points: [
+      'FileWatcher uses native macOS FSEvents to watch configured root directories for create, modify, and delete events. A checkpoint timestamp is saved to SQLite so backfill can catch any edits made while the daemon was offline.',
+      'Debouncer merges rapid-fire events for the same file path using a configurable window (debounce_ms). The last event wins for most cases, but delete always wins if it appears anywhere in the merge chain — preventing phantom edits on files that were actually removed.',
+      'AppUsageTracker runs in parallel and independently — it polls the frontmost application every 5 seconds (app_usage_poll_ms) and writes time segments directly to the DB, bypassing the file pipeline entirely.',
+    ],
+  },
+  {
+    id: 'process',
+    label: '02 Process',
+    color: 'amber',
+    file: 'runtime/watch-pipeline-processor.ts',
+    title: 'Event Processing Pipeline',
+    points: [
+      'FileNormalizer.normalize() resolves the project context for each event: git repository root, active branch, and display name via ContextResolver. It also queries FrontmostAppCache (TTL 1.5s) for the currently active application so the event carries rich context.',
+      'ChangeTracker.apply() reads the file bytes, computes SHA-256, and compares against the previous hash stored in file_state. Unchanged files are dropped as duplicates. Every event passing through gets device_id stamped on it from config.',
+      'Text files under 256 KB are stored as content blobs in BlobStore (content-addressed by hash). Binary or oversized files get metadata-only tracking — hash and byte size are recorded but raw content is not stored.',
+    ],
+  },
+  {
+    id: 'store',
+    label: '03 Store',
+    color: 'green',
+    file: 'storage/timeline-db.ts + event-repository.ts',
+    title: 'SQLite Storage',
+    points: [
+      'TimelineDb.insert() writes to the events table (id, timestamp, device_id, event_type, context_kind/root/name, data_json) and simultaneously to the events_fts FTS5 virtual table for full-text search over file content.',
+      'file_state tracks per-file last_hash + last_seen_ts to power the next dedup check. A delete event calls deleteFileState() to remove the row entirely.',
+      'Database runs in WAL mode with NORMAL synchronous writes. Auto-batching commits every 200 ops or 1 second (whichever comes first) — keeping throughput high while bounding potential data loss to under a second.',
+      'Schema v2 migration added device_id on both events and app_usage tables plus a unique segment_id on app_usage for sync deduplication. Both tables are backfilled automatically on first run with a real device_id.',
+    ],
+  },
+  {
+    id: 'query',
+    label: '04 Query',
+    color: 'purple',
+    file: 'session/query-service.ts + session-manager.ts',
+    title: 'Session Grouping',
+    points: [
+      'All reporting commands call createActivityContext() which opens the SQLite db, creates a SessionManager configured with idle_threshold_s (default: 5 min) and activity_window_s, and wraps them in a QueryService.',
+      'QueryService.sessions() fetches raw events for the requested time range via db.query(), then passes the array to SessionManager.groupEvents(). Events are first partitioned by device_id to prevent cross-device interleaving from incorrectly splitting sessions.',
+      'IdleBoundaryDetector splits each device partition into sessions wherever the gap between consecutive events exceeds the idle threshold. Session IDs are deterministic: {start_ts}-{device_id}-{context.kind}-{name}, so the same session always has the same ID even if re-derived.',
+    ],
+  },
+  {
+    id: 'report',
+    label: '05 Report',
+    color: 'rose',
+    file: 'commands/activity-log.ts + activity-show.ts + activity-report.ts',
+    title: 'Report Commands',
+    points: [
+      'wildcard log: buckets sessions into hourly slots (or daily for --week) via bucketSessionsByTime, then groups session fragments by project within each slot via groupFragmentsByProject, printing a columnar timeline with per-project duration and edit counts.',
+      'wildcard show: same session bucketing but renders a project-focused summary with app usage breakdown from the app_usage table. The --json flag on either command emits machine-readable JSON with the same shape.',
+      'wildcard report: uses getSessionSummariesInRange() to fetch cached summaries, falls back to generating new ones via AI (Claude API) or heuristic summarizer, then assembles a full markdown daily report. Results cached in session_summaries and daily_summaries to avoid regeneration.',
+      'wildcard search: bypasses the session layer entirely and queries the FTS5 virtual table via db.search(), supporting full-text queries across all stored event text content with optional time range and event-type filters.',
+    ],
+  },
+];
+
+const COLORS = {
+  blue:   { badge: 'bg-blue-100 text-blue-700 dark:bg-blue-950 dark:text-blue-300',     dot: 'bg-blue-500'    },
+  amber:  { badge: 'bg-amber-100 text-amber-700 dark:bg-amber-950 dark:text-amber-300', dot: 'bg-amber-500'   },
+  green:  { badge: 'bg-emerald-100 text-emerald-700 dark:bg-emerald-950 dark:text-emerald-300', dot: 'bg-emerald-500' },
+  purple: { badge: 'bg-purple-100 text-purple-700 dark:bg-purple-950 dark:text-purple-300', dot: 'bg-purple-500'  },
+  rose:   { badge: 'bg-rose-100 text-rose-700 dark:bg-rose-950 dark:text-rose-300',     dot: 'bg-rose-500'    },
+};
+
+// ─── Mermaid render ────────────────────────────────────
+let renderCount = 0;
+
+function doRenderMermaid(dark) {
+  mermaid.initialize({
+    startOnLoad: false,
+    theme: 'base',
+    look: 'classic',
+    themeVariables: {
+      primaryColor:       dark ? '#1e293b' : '#f1f5f9',
+      primaryBorderColor: dark ? '#f59e0b' : '#b45309',
+      primaryTextColor:   dark ? '#f1f5f9' : '#0f172a',
+      lineColor:          dark ? '#475569' : '#94a3b8',
+      clusterBkg:         dark ? '#0f172a' : '#ffffff',
+      clusterBorder:      dark ? '#334155' : '#e2e8f0',
+      fontSize: '14px',
+      fontFamily: "'Inter', system-ui, sans-serif",
+    },
+  });
+  renderCount++;
+  const svgId = 'mmaid-' + renderCount;
+  mermaid.render(svgId, CHART_DEF).then(function(result) {
+    const el = document.getElementById('mermaid-chart');
+    if (el) el.innerHTML = result.svg;
+  }).catch(console.error);
+}
+
+// ─── Components ────────────────────────────────────────
+
+function ThemeToggle({ dark, onToggle }) {
+  const sunIcon = html`<svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/><line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/></svg>`;
+  const moonIcon = html`<svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>`;
+  return html`
+    <button
+      onClick=${onToggle}
+      aria-label=${dark ? 'Switch to light mode' : 'Switch to dark mode'}
+      class="w-8 h-8 rounded-lg border border-slate-200 dark:border-slate-700 flex items-center justify-center text-slate-400 hover:text-slate-700 dark:hover:text-slate-200 hover:bg-slate-50 dark:hover:bg-slate-800 transition-colors"
+    >
+      ${dark ? sunIcon : moonIcon}
+    </button>`;
+}
+
+function DiagramSection({ dark }) {
+  useEffect(function() {
+    doRenderMermaid(dark);
+  }, [dark]);
+
+  return html`
+    <div class="bg-slate-50 dark:bg-slate-900 rounded-2xl border border-slate-200 dark:border-slate-800 p-6 mb-10 overflow-x-auto">
+      <p class="font-mono text-xs uppercase tracking-widest text-slate-400 dark:text-slate-500 mb-4 text-center">Architecture Overview</p>
+      <div id="mermaid-chart" class="flex justify-center items-center min-h-72"></div>
+    </div>`;
+}
+
+function PhaseCard({ phase }) {
+  const c = COLORS[phase.color];
+  const badgeClass = 'px-2.5 py-0.5 rounded-full text-xs font-bold tracking-wide ' + c.badge;
+  const dotClass = 'mt-2 flex-shrink-0 w-1.5 h-1.5 rounded-full ' + c.dot;
+  return html`
+    <div class="bg-white dark:bg-slate-900 rounded-xl border border-slate-200 dark:border-slate-800 p-6">
+      <div class="flex items-center gap-3 mb-3 flex-wrap">
+        <span class=${badgeClass}>${phase.label}</span>
+        <code class="text-xs text-slate-400 dark:text-slate-500">${phase.file}</code>
+      </div>
+      <h3 class="font-serif text-xl font-bold text-slate-900 dark:text-slate-100 mb-4">${phase.title}</h3>
+      <ul class="space-y-3">
+        ${phase.points.map(function(pt) {
+          return html`
+            <li class="flex gap-3 text-sm text-slate-600 dark:text-slate-400 leading-relaxed">
+              <span class=${dotClass}></span>
+              <span>${pt}</span>
+            </li>`;
+        })}
+      </ul>
+    </div>`;
+}
+
+function App() {
+  const [dark, setDark] = useState(document.documentElement.classList.contains('dark'));
+
+  const toggleDark = function() {
+    const next = !dark;
+    document.documentElement.classList.toggle('dark', next);
+    localStorage.setItem('theme', next ? 'dark' : 'light');
+    setDark(next);
+  };
+
+  return html`
+    <div class="max-w-3xl mx-auto px-6 py-16">
+
+      <div class="flex items-start justify-between mb-10">
+        <div>
+          <p class="font-mono text-xs uppercase tracking-widest text-slate-400 dark:text-slate-500 mb-1.5">wildcard / internals</p>
+          <h1 class="font-serif text-3xl font-bold text-slate-900 dark:text-slate-100">Event Pipeline</h1>
+          <p class="text-sm text-slate-500 dark:text-slate-400 mt-1.5">From file save to report — how every edit gets tracked, stored, and surfaced.</p>
+        </div>
+        <${ThemeToggle} dark=${dark} onToggle=${toggleDark} />
+      </div>
+
+      <${DiagramSection} dark=${dark} />
+
+      <div class="grid gap-4">
+        ${PHASES.map(function(phase) {
+          return html`<${PhaseCard} key=${phase.id} phase=${phase} />`;
+        })}
+      </div>
+
+      <p class="mt-10 text-xs text-slate-400 dark:text-slate-600 text-center font-mono">wildcard · 2026-03-20</p>
+    </div>`;
+}
+
+render(html`<${App} />`, document.getElementById('app'));
+</script>
+</body>
+</html>

From 197bb4f2c8a28f13b0125af730d881a021b04b3c Mon Sep 17 00:00:00 2001
From: Andy Pai <andy@r2pi.co>
Date: Fri, 20 Mar 2026 18:37:46 -0400
Subject: [PATCH 6/9] chore: add specify workflow scaffolding

---
 .specify/init-options.json                    |   9 +
 .specify/scripts/bash/check-prerequisites.sh  | 190 ++++
 .specify/scripts/bash/common.sh               | 275 ++++++
 .specify/scripts/bash/create-new-feature.sh   | 327 +++++++
 .specify/scripts/bash/setup-plan.sh           |  73 ++
 .specify/scripts/bash/update-agent-context.sh | 832 ++++++++++++++++++
 .specify/templates/agent-file-template.md     |  28 +
 .specify/templates/checklist-template.md      |  40 +
 .specify/templates/constitution-template.md   |  50 ++
 .specify/templates/plan-template.md           | 104 +++
 .specify/templates/spec-template.md           | 115 +++
 .specify/templates/tasks-template.md          | 251 ++++++
 CLAUDE.md                                     |  29 +
 .../checklists/requirements.md                |  67 ++
 .../001-log-command/contracts/cli-contract.md | 136 +++
 specs/001-log-command/data-model.md           | 113 +++
 specs/001-log-command/plan.md                 |  82 ++
 specs/001-log-command/quickstart.md           |  52 ++
 specs/001-log-command/research.md             |  71 ++
 specs/001-log-command/spec.md                 | 139 +++
 20 files changed, 2983 insertions(+)
 create mode 100644 .specify/init-options.json
 create mode 100755 .specify/scripts/bash/check-prerequisites.sh
 create mode 100755 .specify/scripts/bash/common.sh
 create mode 100755 .specify/scripts/bash/create-new-feature.sh
 create mode 100755 .specify/scripts/bash/setup-plan.sh
 create mode 100755 .specify/scripts/bash/update-agent-context.sh
 create mode 100644 .specify/templates/agent-file-template.md
 create mode 100644 .specify/templates/checklist-template.md
 create mode 100644 .specify/templates/constitution-template.md
 create mode 100644 .specify/templates/plan-template.md
 create mode 100644 .specify/templates/spec-template.md
 create mode 100644 .specify/templates/tasks-template.md
 create mode 100644 CLAUDE.md
 create mode 100644 specs/001-log-command/checklists/requirements.md
 create mode 100644 specs/001-log-command/contracts/cli-contract.md
 create mode 100644 specs/001-log-command/data-model.md
 create mode 100644 specs/001-log-command/plan.md
 create mode 100644 specs/001-log-command/quickstart.md
 create mode 100644 specs/001-log-command/research.md
 create mode 100644 specs/001-log-command/spec.md

diff --git a/.specify/init-options.json b/.specify/init-options.json
new file mode 100644
index 0000000..041f293
--- /dev/null
+++ b/.specify/init-options.json
@@ -0,0 +1,9 @@
+{
+  "ai": "claude",
+  "ai_commands_dir": null,
+  "ai_skills": false,
+  "here": true,
+  "preset": null,
+  "script": "sh",
+  "speckit_version": "0.3.1"
+}
\ No newline at end of file
diff --git a/.specify/scripts/bash/check-prerequisites.sh b/.specify/scripts/bash/check-prerequisites.sh
new file mode 100755
index 0000000..88a5559
--- /dev/null
+++ b/.specify/scripts/bash/check-prerequisites.sh
@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+
+# Consolidated prerequisite checking script
+#
+# This script provides unified prerequisite checking for Spec-Driven Development workflow.
+# It replaces the functionality previously spread across multiple scripts.
+#
+# Usage: ./check-prerequisites.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json              Output in JSON format
+#   --require-tasks     Require tasks.md to exist (for implementation phase)
+#   --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+#   --paths-only        Only output path variables (no validation)
+#   --help, -h          Show help message
+#
+# OUTPUTS:
+#   JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
+#   Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
+#   Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+REQUIRE_TASKS=false
+INCLUDE_TASKS=false
+PATHS_ONLY=false
+
+for arg in "$@"; do
+    case "$arg" in
+        --json)
+            JSON_MODE=true
+            ;;
+        --require-tasks)
+            REQUIRE_TASKS=true
+            ;;
+        --include-tasks)
+            INCLUDE_TASKS=true
+            ;;
+        --paths-only)
+            PATHS_ONLY=true
+            ;;
+        --help|-h)
+            cat << 'EOF'
+Usage: check-prerequisites.sh [OPTIONS]
+
+Consolidated prerequisite checking for Spec-Driven Development workflow.
+
+OPTIONS:
+  --json              Output in JSON format
+  --require-tasks     Require tasks.md to exist (for implementation phase)
+  --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+  --paths-only        Only output path variables (no prerequisite validation)
+  --help, -h          Show this help message
+
+EXAMPLES:
+  # Check task prerequisites (plan.md required)
+  ./check-prerequisites.sh --json
+  
+  # Check implementation prerequisites (plan.md + tasks.md required)
+  ./check-prerequisites.sh --json --require-tasks --include-tasks
+  
+  # Get feature paths only (no validation)
+  ./check-prerequisites.sh --paths-only
+  
+EOF
+            exit 0
+            ;;
+        *)
+            echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Source common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get feature paths and validate branch
+_paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
+eval "$_paths_output"
+unset _paths_output
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# If paths-only mode, output paths and exit (support JSON + paths-only combined)
+if $PATHS_ONLY; then
+    if $JSON_MODE; then
+        # Minimal JSON paths payload (no validation performed)
+        if has_jq; then
+            jq -cn \
+                --arg repo_root "$REPO_ROOT" \
+                --arg branch "$CURRENT_BRANCH" \
+                --arg feature_dir "$FEATURE_DIR" \
+                --arg feature_spec "$FEATURE_SPEC" \
+                --arg impl_plan "$IMPL_PLAN" \
+                --arg tasks "$TASKS" \
+                '{REPO_ROOT:$repo_root,BRANCH:$branch,FEATURE_DIR:$feature_dir,FEATURE_SPEC:$feature_spec,IMPL_PLAN:$impl_plan,TASKS:$tasks}'
+        else
+            printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
+                "$(json_escape "$REPO_ROOT")" "$(json_escape "$CURRENT_BRANCH")" "$(json_escape "$FEATURE_DIR")" "$(json_escape "$FEATURE_SPEC")" "$(json_escape "$IMPL_PLAN")" "$(json_escape "$TASKS")"
+        fi
+    else
+        echo "REPO_ROOT: $REPO_ROOT"
+        echo "BRANCH: $CURRENT_BRANCH"
+        echo "FEATURE_DIR: $FEATURE_DIR"
+        echo "FEATURE_SPEC: $FEATURE_SPEC"
+        echo "IMPL_PLAN: $IMPL_PLAN"
+        echo "TASKS: $TASKS"
+    fi
+    exit 0
+fi
+
+# Validate required directories and files
+if [[ ! -d "$FEATURE_DIR" ]]; then
+    echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
+    echo "Run /speckit.specify first to create the feature structure." >&2
+    exit 1
+fi
+
+if [[ ! -f "$IMPL_PLAN" ]]; then
+    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.plan first to create the implementation plan." >&2
+    exit 1
+fi
+
+# Check for tasks.md if required
+if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
+    echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.tasks first to create the task list." >&2
+    exit 1
+fi
+
+# Build list of available documents
+docs=()
+
+# Always check these optional docs
+[[ -f "$RESEARCH" ]] && docs+=("research.md")
+[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
+
+# Check contracts directory (only if it exists and has files)
+if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
+    docs+=("contracts/")
+fi
+
+[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
+
+# Include tasks.md if requested and it exists
+if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
+    docs+=("tasks.md")
+fi
+
+# Output results
+if $JSON_MODE; then
+    # Build JSON array of documents
+    if has_jq; then
+        if [[ ${#docs[@]} -eq 0 ]]; then
+            json_docs="[]"
+        else
+            json_docs=$(printf '%s\n' "${docs[@]}" | jq -R . | jq -s .)
+        fi
+        jq -cn \
+            --arg feature_dir "$FEATURE_DIR" \
+            --argjson docs "$json_docs" \
+            '{FEATURE_DIR:$feature_dir,AVAILABLE_DOCS:$docs}'
+    else
+        if [[ ${#docs[@]} -eq 0 ]]; then
+            json_docs="[]"
+        else
+            json_docs=$(for d in "${docs[@]}"; do printf '"%s",' "$(json_escape "$d")"; done)
+            json_docs="[${json_docs%,}]"
+        fi
+        printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$(json_escape "$FEATURE_DIR")" "$json_docs"
+    fi
+else
+    # Text output
+    echo "FEATURE_DIR:$FEATURE_DIR"
+    echo "AVAILABLE_DOCS:"
+    
+    # Show status of each potential document
+    check_file "$RESEARCH" "research.md"
+    check_file "$DATA_MODEL" "data-model.md"
+    check_dir "$CONTRACTS_DIR" "contracts/"
+    check_file "$QUICKSTART" "quickstart.md"
+    
+    if $INCLUDE_TASKS; then
+        check_file "$TASKS" "tasks.md"
+    fi
+fi
diff --git a/.specify/scripts/bash/common.sh b/.specify/scripts/bash/common.sh
new file mode 100755
index 0000000..40f1c96
--- /dev/null
+++ b/.specify/scripts/bash/common.sh
@@ -0,0 +1,275 @@
+#!/usr/bin/env bash
+# Common functions and variables for all scripts
+
+# Get repository root, with fallback for non-git repositories
+get_repo_root() {
+    if git rev-parse --show-toplevel >/dev/null 2>&1; then
+        git rev-parse --show-toplevel
+    else
+        # Fall back to script location for non-git repos
+        local script_dir="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+        (cd "$script_dir/../../.." && pwd)
+    fi
+}
+
+# Get current branch, with fallback for non-git repositories
+get_current_branch() {
+    # First check if SPECIFY_FEATURE environment variable is set
+    if [[ -n "${SPECIFY_FEATURE:-}" ]]; then
+        echo "$SPECIFY_FEATURE"
+        return
+    fi
+
+    # Then check git if available
+    if git rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then
+        git rev-parse --abbrev-ref HEAD
+        return
+    fi
+
+    # For non-git repos, try to find the latest feature directory
+    local repo_root=$(get_repo_root)
+    local specs_dir="$repo_root/specs"
+
+    if [[ -d "$specs_dir" ]]; then
+        local latest_feature=""
+        local highest=0
+
+        for dir in "$specs_dir"/*; do
+            if [[ -d "$dir" ]]; then
+                local dirname=$(basename "$dir")
+                if [[ "$dirname" =~ ^([0-9]{3})- ]]; then
+                    local number=${BASH_REMATCH[1]}
+                    number=$((10#$number))
+                    if [[ "$number" -gt "$highest" ]]; then
+                        highest=$number
+                        latest_feature=$dirname
+                    fi
+                fi
+            fi
+        done
+
+        if [[ -n "$latest_feature" ]]; then
+            echo "$latest_feature"
+            return
+        fi
+    fi
+
+    echo "main"  # Final fallback
+}
+
+# Check if we have git available
+has_git() {
+    git rev-parse --show-toplevel >/dev/null 2>&1
+}
+
+check_feature_branch() {
+    local branch="$1"
+    local has_git_repo="$2"
+
+    # For non-git repos, we can't enforce branch naming but still provide output
+    if [[ "$has_git_repo" != "true" ]]; then
+        echo "[specify] Warning: Git repository not detected; skipped branch validation" >&2
+        return 0
+    fi
+
+    if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
+        echo "ERROR: Not on a feature branch. Current branch: $branch" >&2
+        echo "Feature branches should be named like: 001-feature-name" >&2
+        return 1
+    fi
+
+    return 0
+}
+
+get_feature_dir() { echo "$1/specs/$2"; }
+
+# Find feature directory by numeric prefix instead of exact branch match
+# This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature)
+find_feature_dir_by_prefix() {
+    local repo_root="$1"
+    local branch_name="$2"
+    local specs_dir="$repo_root/specs"
+
+    # Extract numeric prefix from branch (e.g., "004" from "004-whatever")
+    if [[ ! "$branch_name" =~ ^([0-9]{3})- ]]; then
+        # If branch doesn't have numeric prefix, fall back to exact match
+        echo "$specs_dir/$branch_name"
+        return
+    fi
+
+    local prefix="${BASH_REMATCH[1]}"
+
+    # Search for directories in specs/ that start with this prefix
+    local matches=()
+    if [[ -d "$specs_dir" ]]; then
+        for dir in "$specs_dir"/"$prefix"-*; do
+            if [[ -d "$dir" ]]; then
+                matches+=("$(basename "$dir")")
+            fi
+        done
+    fi
+
+    # Handle results
+    if [[ ${#matches[@]} -eq 0 ]]; then
+        # No match found - return the branch name path (will fail later with clear error)
+        echo "$specs_dir/$branch_name"
+    elif [[ ${#matches[@]} -eq 1 ]]; then
+        # Exactly one match - perfect!
+        echo "$specs_dir/${matches[0]}"
+    else
+        # Multiple matches - this shouldn't happen with proper naming convention
+        echo "ERROR: Multiple spec directories found with prefix '$prefix': ${matches[*]}" >&2
+        echo "Please ensure only one spec directory exists per numeric prefix." >&2
+        return 1
+    fi
+}
+
+get_feature_paths() {
+    local repo_root=$(get_repo_root)
+    local current_branch=$(get_current_branch)
+    local has_git_repo="false"
+
+    if has_git; then
+        has_git_repo="true"
+    fi
+
+    # Use prefix-based lookup to support multiple branches per spec
+    local feature_dir
+    if ! feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch"); then
+        echo "ERROR: Failed to resolve feature directory" >&2
+        return 1
+    fi
+
+    # Use printf '%q' to safely quote values, preventing shell injection
+    # via crafted branch names or paths containing special characters
+    printf 'REPO_ROOT=%q\n' "$repo_root"
+    printf 'CURRENT_BRANCH=%q\n' "$current_branch"
+    printf 'HAS_GIT=%q\n' "$has_git_repo"
+    printf 'FEATURE_DIR=%q\n' "$feature_dir"
+    printf 'FEATURE_SPEC=%q\n' "$feature_dir/spec.md"
+    printf 'IMPL_PLAN=%q\n' "$feature_dir/plan.md"
+    printf 'TASKS=%q\n' "$feature_dir/tasks.md"
+    printf 'RESEARCH=%q\n' "$feature_dir/research.md"
+    printf 'DATA_MODEL=%q\n' "$feature_dir/data-model.md"
+    printf 'QUICKSTART=%q\n' "$feature_dir/quickstart.md"
+    printf 'CONTRACTS_DIR=%q\n' "$feature_dir/contracts"
+}
+
+# Check if jq is available for safe JSON construction
+has_jq() {
+    command -v jq >/dev/null 2>&1
+}
+
+# Escape a string for safe embedding in a JSON value (fallback when jq is unavailable).
+# Handles backslash, double-quote, and JSON-required control character escapes (RFC 8259).
+json_escape() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\t'/\\t}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\b'/\\b}"
+    s="${s//$'\f'/\\f}"
+    # Escape any remaining U+0001-U+001F control characters as \uXXXX.
+    # (U+0000/NUL cannot appear in bash strings and is excluded.)
+    # LC_ALL=C ensures ${#s} counts bytes and ${s:$i:1} yields single bytes,
+    # so multi-byte UTF-8 sequences (first byte >= 0xC0) pass through intact.
+    local LC_ALL=C
+    local i char code
+    for (( i=0; i<${#s}; i++ )); do
+        char="${s:$i:1}"
+        printf -v code '%d' "'$char" 2>/dev/null || code=256
+        if (( code >= 1 && code <= 31 )); then
+            printf '\\u%04x' "$code"
+        else
+            printf '%s' "$char"
+        fi
+    done
+}
+
+check_file() { [[ -f "$1" ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+
+# Resolve a template name to a file path using the priority stack:
+#   1. .specify/templates/overrides/
+#   2. .specify/presets/<preset-id>/templates/ (sorted by priority from .registry)
+#   3. .specify/extensions/<ext-id>/templates/
+#   4. .specify/templates/ (core)
+resolve_template() {
+    local template_name="$1"
+    local repo_root="$2"
+    local base="$repo_root/.specify/templates"
+
+    # Priority 1: Project overrides
+    local override="$base/overrides/${template_name}.md"
+    [ -f "$override" ] && echo "$override" && return 0
+
+    # Priority 2: Installed presets (sorted by priority from .registry)
+    local presets_dir="$repo_root/.specify/presets"
+    if [ -d "$presets_dir" ]; then
+        local registry_file="$presets_dir/.registry"
+        if [ -f "$registry_file" ] && command -v python3 >/dev/null 2>&1; then
+            # Read preset IDs sorted by priority (lower number = higher precedence).
+            # The python3 call is wrapped in an if-condition so that set -e does not
+            # abort the function when python3 exits non-zero (e.g. invalid JSON).
+            local sorted_presets=""
+            if sorted_presets=$(SPECKIT_REGISTRY="$registry_file" python3 -c "
+import json, sys, os
+try:
+    with open(os.environ['SPECKIT_REGISTRY']) as f:
+        data = json.load(f)
+    presets = data.get('presets', {})
+    for pid, meta in sorted(presets.items(), key=lambda x: x[1].get('priority', 10)):
+        print(pid)
+except Exception:
+    sys.exit(1)
+" 2>/dev/null); then
+                if [ -n "$sorted_presets" ]; then
+                    # python3 succeeded and returned preset IDs — search in priority order
+                    while IFS= read -r preset_id; do
+                        local candidate="$presets_dir/$preset_id/templates/${template_name}.md"
+                        [ -f "$candidate" ] && echo "$candidate" && return 0
+                    done <<< "$sorted_presets"
+                fi
+                # python3 succeeded but registry has no presets — nothing to search
+            else
+                # python3 failed (missing, or registry parse error) — fall back to unordered directory scan
+                for preset in "$presets_dir"/*/; do
+                    [ -d "$preset" ] || continue
+                    local candidate="$preset/templates/${template_name}.md"
+                    [ -f "$candidate" ] && echo "$candidate" && return 0
+                done
+            fi
+        else
+            # Fallback: alphabetical directory order (no python3 available)
+            for preset in "$presets_dir"/*/; do
+                [ -d "$preset" ] || continue
+                local candidate="$preset/templates/${template_name}.md"
+                [ -f "$candidate" ] && echo "$candidate" && return 0
+            done
+        fi
+    fi
+
+    # Priority 3: Extension-provided templates
+    local ext_dir="$repo_root/.specify/extensions"
+    if [ -d "$ext_dir" ]; then
+        for ext in "$ext_dir"/*/; do
+            [ -d "$ext" ] || continue
+            # Skip hidden directories (e.g. .backup, .cache)
+            case "$(basename "$ext")" in .*) continue;; esac
+            local candidate="$ext/templates/${template_name}.md"
+            [ -f "$candidate" ] && echo "$candidate" && return 0
+        done
+    fi
+
+    # Priority 4: Core templates
+    local core="$base/${template_name}.md"
+    [ -f "$core" ] && echo "$core" && return 0
+
+    # Template not found in any location.
+    # Return 1 so callers can distinguish "not found" from "found".
+    # Callers running under set -e should use: TEMPLATE=$(resolve_template ...) || true
+    return 1
+}
+
diff --git a/.specify/scripts/bash/create-new-feature.sh b/.specify/scripts/bash/create-new-feature.sh
new file mode 100755
index 0000000..58c5c86
--- /dev/null
+++ b/.specify/scripts/bash/create-new-feature.sh
@@ -0,0 +1,327 @@
+#!/usr/bin/env bash
+
+set -e
+
+JSON_MODE=false
+SHORT_NAME=""
+BRANCH_NUMBER=""
+ARGS=()
+i=1
+while [ $i -le $# ]; do
+    arg="${!i}"
+    case "$arg" in
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --short-name)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            # Check if the next argument is another option (starts with --)
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            SHORT_NAME="$next_arg"
+            ;;
+        --number)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --number requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --number requires a value' >&2
+                exit 1
+            fi
+            BRANCH_NUMBER="$next_arg"
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>"
+            echo ""
+            echo "Options:"
+            echo "  --json              Output in JSON format"
+            echo "  --short-name <name> Provide a custom short name (2-4 words) for the branch"
+            echo "  --number N          Specify branch number manually (overrides auto-detection)"
+            echo "  --help, -h          Show this help message"
+            echo ""
+            echo "Examples:"
+            echo "  $0 'Add user authentication system' --short-name 'user-auth'"
+            echo "  $0 'Implement OAuth2 integration for API' --number 5"
+            exit 0
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
+    esac
+    i=$((i + 1))
+done
+
+FEATURE_DESCRIPTION="${ARGS[*]}"
+if [ -z "$FEATURE_DESCRIPTION" ]; then
+    echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>" >&2
+    exit 1
+fi
+
+# Trim whitespace and validate description is not empty (e.g., user passed only whitespace)
+FEATURE_DESCRIPTION=$(echo "$FEATURE_DESCRIPTION" | xargs)
+if [ -z "$FEATURE_DESCRIPTION" ]; then
+    echo "Error: Feature description cannot be empty or contain only whitespace" >&2
+    exit 1
+fi
+
+# Function to find the repository root by searching for existing project markers
+find_repo_root() {
+    local dir="$1"
+    while [ "$dir" != "/" ]; do
+        if [ -d "$dir/.git" ] || [ -d "$dir/.specify" ]; then
+            echo "$dir"
+            return 0
+        fi
+        dir="$(dirname "$dir")"
+    done
+    return 1
+}
+
+# Function to get highest number from specs directory
+get_highest_from_specs() {
+    local specs_dir="$1"
+    local highest=0
+    
+    if [ -d "$specs_dir" ]; then
+        for dir in "$specs_dir"/*; do
+            [ -d "$dir" ] || continue
+            dirname=$(basename "$dir")
+            number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
+            number=$((10#$number))
+            if [ "$number" -gt "$highest" ]; then
+                highest=$number
+            fi
+        done
+    fi
+    
+    echo "$highest"
+}
+
+# Function to get highest number from git branches
+get_highest_from_branches() {
+    local highest=0
+    
+    # Get all branches (local and remote)
+    branches=$(git branch -a 2>/dev/null || echo "")
+    
+    if [ -n "$branches" ]; then
+        while IFS= read -r branch; do
+            # Clean branch name: remove leading markers and remote prefixes
+            clean_branch=$(echo "$branch" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')
+            
+            # Extract feature number if branch matches pattern ###-*
+            if echo "$clean_branch" | grep -q '^[0-9]\{3\}-'; then
+                number=$(echo "$clean_branch" | grep -o '^[0-9]\{3\}' || echo "0")
+                number=$((10#$number))
+                if [ "$number" -gt "$highest" ]; then
+                    highest=$number
+                fi
+            fi
+        done <<< "$branches"
+    fi
+    
+    echo "$highest"
+}
+
+# Function to check existing branches (local and remote) and return next available number
+check_existing_branches() {
+    local specs_dir="$1"
+
+    # Fetch all remotes to get latest branch info (suppress errors if no remotes)
+    git fetch --all --prune >/dev/null 2>&1 || true
+
+    # Get highest number from ALL branches (not just matching short name)
+    local highest_branch=$(get_highest_from_branches)
+
+    # Get highest number from ALL specs (not just matching short name)
+    local highest_spec=$(get_highest_from_specs "$specs_dir")
+
+    # Take the maximum of both
+    local max_num=$highest_branch
+    if [ "$highest_spec" -gt "$max_num" ]; then
+        max_num=$highest_spec
+    fi
+
+    # Return next number
+    echo $((max_num + 1))
+}
+
+# Function to clean and format a branch name
+clean_branch_name() {
+    local name="$1"
+    echo "$name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//'
+}
+
+# Resolve repository root. Prefer git information when available, but fall back
+# to searching for repository markers so the workflow still functions in repositories that
+# were initialised with --no-git.
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+if git rev-parse --show-toplevel >/dev/null 2>&1; then
+    REPO_ROOT=$(git rev-parse --show-toplevel)
+    HAS_GIT=true
+else
+    REPO_ROOT="$(find_repo_root "$SCRIPT_DIR")"
+    if [ -z "$REPO_ROOT" ]; then
+        echo "Error: Could not determine repository root. Please run this script from within the repository." >&2
+        exit 1
+    fi
+    HAS_GIT=false
+fi
+
+cd "$REPO_ROOT"
+
+SPECS_DIR="$REPO_ROOT/specs"
+mkdir -p "$SPECS_DIR"
+
+# Function to generate branch name with stop word filtering and length filtering
+generate_branch_name() {
+    local description="$1"
+    
+    # Common stop words to filter out
+    local stop_words="^(i|a|an|the|to|for|of|in|on|at|by|with|from|is|are|was|were|be|been|being|have|has|had|do|does|did|will|would|should|could|can|may|might|must|shall|this|that|these|those|my|your|our|their|want|need|add|get|set)$"
+    
+    # Convert to lowercase and split into words
+    local clean_name=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g')
+    
+    # Filter words: remove stop words and words shorter than 3 chars (unless they're uppercase acronyms in original)
+    local meaningful_words=()
+    for word in $clean_name; do
+        # Skip empty words
+        [ -z "$word" ] && continue
+        
+        # Keep words that are NOT stop words AND (length >= 3 OR are potential acronyms)
+        if ! echo "$word" | grep -qiE "$stop_words"; then
+            if [ ${#word} -ge 3 ]; then
+                meaningful_words+=("$word")
+            elif echo "$description" | grep -q "\b${word^^}\b"; then
+                # Keep short words if they appear as uppercase in original (likely acronyms)
+                meaningful_words+=("$word")
+            fi
+        fi
+    done
+    
+    # If we have meaningful words, use first 3-4 of them
+    if [ ${#meaningful_words[@]} -gt 0 ]; then
+        local max_words=3
+        if [ ${#meaningful_words[@]} -eq 4 ]; then max_words=4; fi
+        
+        local result=""
+        local count=0
+        for word in "${meaningful_words[@]}"; do
+            if [ $count -ge $max_words ]; then break; fi
+            if [ -n "$result" ]; then result="$result-"; fi
+            result="$result$word"
+            count=$((count + 1))
+        done
+        echo "$result"
+    else
+        # Fallback to original logic if no meaningful words found
+        local cleaned=$(clean_branch_name "$description")
+        echo "$cleaned" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//'
+    fi
+}
+
+# Generate branch name
+if [ -n "$SHORT_NAME" ]; then
+    # Use provided short name, just clean it up
+    BRANCH_SUFFIX=$(clean_branch_name "$SHORT_NAME")
+else
+    # Generate from description with smart filtering
+    BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION")
+fi
+
+# Determine branch number
+if [ -z "$BRANCH_NUMBER" ]; then
+    if [ "$HAS_GIT" = true ]; then
+        # Check existing branches on remotes
+        BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
+    else
+        # Fall back to local directory check
+        HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
+        BRANCH_NUMBER=$((HIGHEST + 1))
+    fi
+fi
+
+# Force base-10 interpretation to prevent octal conversion (e.g., 010 → 8 in octal, but should be 10 in decimal)
+FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
+BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
+
+# GitHub enforces a 244-byte limit on branch names
+# Validate and truncate if necessary
+MAX_BRANCH_LENGTH=244
+if [ ${#BRANCH_NAME} -gt $MAX_BRANCH_LENGTH ]; then
+    # Calculate how much we need to trim from suffix
+    # Account for: feature number (3) + hyphen (1) = 4 chars
+    MAX_SUFFIX_LENGTH=$((MAX_BRANCH_LENGTH - 4))
+    
+    # Truncate suffix at word boundary if possible
+    TRUNCATED_SUFFIX=$(echo "$BRANCH_SUFFIX" | cut -c1-$MAX_SUFFIX_LENGTH)
+    # Remove trailing hyphen if truncation created one
+    TRUNCATED_SUFFIX=$(echo "$TRUNCATED_SUFFIX" | sed 's/-$//')
+    
+    ORIGINAL_BRANCH_NAME="$BRANCH_NAME"
+    BRANCH_NAME="${FEATURE_NUM}-${TRUNCATED_SUFFIX}"
+    
+    >&2 echo "[specify] Warning: Branch name exceeded GitHub's 244-byte limit"
+    >&2 echo "[specify] Original: $ORIGINAL_BRANCH_NAME (${#ORIGINAL_BRANCH_NAME} bytes)"
+    >&2 echo "[specify] Truncated to: $BRANCH_NAME (${#BRANCH_NAME} bytes)"
+fi
+
+if [ "$HAS_GIT" = true ]; then
+    if ! git checkout -b "$BRANCH_NAME" 2>/dev/null; then
+        # Check if branch already exists
+        if git branch --list "$BRANCH_NAME" | grep -q .; then
+            >&2 echo "Error: Branch '$BRANCH_NAME' already exists. Please use a different feature name or specify a different number with --number."
+            exit 1
+        else
+            >&2 echo "Error: Failed to create git branch '$BRANCH_NAME'. Please check your git configuration and try again."
+            exit 1
+        fi
+    fi
+else
+    >&2 echo "[specify] Warning: Git repository not detected; skipped branch creation for $BRANCH_NAME"
+fi
+
+FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
+mkdir -p "$FEATURE_DIR"
+
+TEMPLATE=$(resolve_template "spec-template" "$REPO_ROOT") || true
+SPEC_FILE="$FEATURE_DIR/spec.md"
+if [ -n "$TEMPLATE" ] && [ -f "$TEMPLATE" ]; then
+    cp "$TEMPLATE" "$SPEC_FILE"
+else
+    echo "Warning: Spec template not found; created empty spec file" >&2
+    touch "$SPEC_FILE"
+fi
+
+# Inform the user how to persist the feature variable in their own shell
+printf '# To persist: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME" >&2
+
+if $JSON_MODE; then
+    if command -v jq >/dev/null 2>&1; then
+        jq -cn \
+            --arg branch_name "$BRANCH_NAME" \
+            --arg spec_file "$SPEC_FILE" \
+            --arg feature_num "$FEATURE_NUM" \
+            '{BRANCH_NAME:$branch_name,SPEC_FILE:$spec_file,FEATURE_NUM:$feature_num}'
+    else
+        printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$(json_escape "$BRANCH_NAME")" "$(json_escape "$SPEC_FILE")" "$(json_escape "$FEATURE_NUM")"
+    fi
+else
+    echo "BRANCH_NAME: $BRANCH_NAME"
+    echo "SPEC_FILE: $SPEC_FILE"
+    echo "FEATURE_NUM: $FEATURE_NUM"
+    printf '# To persist in your shell: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME"
+fi
diff --git a/.specify/scripts/bash/setup-plan.sh b/.specify/scripts/bash/setup-plan.sh
new file mode 100755
index 0000000..9f55231
--- /dev/null
+++ b/.specify/scripts/bash/setup-plan.sh
@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+ARGS=()
+
+for arg in "$@"; do
+    case "$arg" in
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json]"
+            echo "  --json    Output results in JSON format"
+            echo "  --help    Show this help message"
+            exit 0 
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
+    esac
+done
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+_paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
+eval "$_paths_output"
+unset _paths_output
+
+# Check if we're on a proper feature branch (only for git repos)
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# Ensure the feature directory exists
+mkdir -p "$FEATURE_DIR"
+
+# Copy plan template if it exists
+TEMPLATE=$(resolve_template "plan-template" "$REPO_ROOT") || true
+if [[ -n "$TEMPLATE" ]] && [[ -f "$TEMPLATE" ]]; then
+    cp "$TEMPLATE" "$IMPL_PLAN"
+    echo "Copied plan template to $IMPL_PLAN"
+else
+    echo "Warning: Plan template not found"
+    # Create a basic plan file if template doesn't exist
+    touch "$IMPL_PLAN"
+fi
+
+# Output results
+if $JSON_MODE; then
+    if has_jq; then
+        jq -cn \
+            --arg feature_spec "$FEATURE_SPEC" \
+            --arg impl_plan "$IMPL_PLAN" \
+            --arg specs_dir "$FEATURE_DIR" \
+            --arg branch "$CURRENT_BRANCH" \
+            --arg has_git "$HAS_GIT" \
+            '{FEATURE_SPEC:$feature_spec,IMPL_PLAN:$impl_plan,SPECS_DIR:$specs_dir,BRANCH:$branch,HAS_GIT:$has_git}'
+    else
+        printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s"}\n' \
+            "$(json_escape "$FEATURE_SPEC")" "$(json_escape "$IMPL_PLAN")" "$(json_escape "$FEATURE_DIR")" "$(json_escape "$CURRENT_BRANCH")" "$(json_escape "$HAS_GIT")"
+    fi
+else
+    echo "FEATURE_SPEC: $FEATURE_SPEC"
+    echo "IMPL_PLAN: $IMPL_PLAN" 
+    echo "SPECS_DIR: $FEATURE_DIR"
+    echo "BRANCH: $CURRENT_BRANCH"
+    echo "HAS_GIT: $HAS_GIT"
+fi
+
diff --git a/.specify/scripts/bash/update-agent-context.sh b/.specify/scripts/bash/update-agent-context.sh
new file mode 100755
index 0000000..74a9866
--- /dev/null
+++ b/.specify/scripts/bash/update-agent-context.sh
@@ -0,0 +1,832 @@
+#!/usr/bin/env bash
+
+# Update agent context files with information from plan.md
+#
+# This script maintains AI agent context files by parsing feature specifications 
+# and updating agent-specific configuration files with project information.
+#
+# MAIN FUNCTIONS:
+# 1. Environment Validation
+#    - Verifies git repository structure and branch information
+#    - Checks for required plan.md files and templates
+#    - Validates file permissions and accessibility
+#
+# 2. Plan Data Extraction
+#    - Parses plan.md files to extract project metadata
+#    - Identifies language/version, frameworks, databases, and project types
+#    - Handles missing or incomplete specification data gracefully
+#
+# 3. Agent File Management
+#    - Creates new agent context files from templates when needed
+#    - Updates existing agent files with new project information
+#    - Preserves manual additions and custom configurations
+#    - Supports multiple AI agent formats and directory structures
+#
+# 4. Content Generation
+#    - Generates language-specific build/test commands
+#    - Creates appropriate project directory structures
+#    - Updates technology stacks and recent changes sections
+#    - Maintains consistent formatting and timestamps
+#
+# 5. Multi-Agent Support
+#    - Handles agent-specific file paths and naming conventions
+#    - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy CLI, Qoder CLI, Amp, SHAI, Tabnine CLI, Kiro CLI, Mistral Vibe, Kimi Code, Pi Coding Agent, iFlow CLI, Antigravity or Generic
+#    - Can update single agents or all existing agent files
+#    - Creates default Claude file if no agent files exist
+#
+# Usage: ./update-agent-context.sh [agent_type]
+# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|pi|iflow|generic
+# Leave empty to update all existing agent files
+
+set -e
+
+# Enable strict error handling
+set -u
+set -o pipefail
+
+#==============================================================================
+# Configuration and Global Variables
+#==============================================================================
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+_paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
+eval "$_paths_output"
+unset _paths_output
+
+NEW_PLAN="$IMPL_PLAN"  # Alias for compatibility with existing code
+AGENT_TYPE="${1:-}"
+
+# Agent-specific file paths  
+CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
+GEMINI_FILE="$REPO_ROOT/GEMINI.md"
+COPILOT_FILE="$REPO_ROOT/.github/agents/copilot-instructions.md"
+CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"
+QWEN_FILE="$REPO_ROOT/QWEN.md"
+AGENTS_FILE="$REPO_ROOT/AGENTS.md"
+WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
+KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
+AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
+ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
+CODEBUDDY_FILE="$REPO_ROOT/CODEBUDDY.md"
+QODER_FILE="$REPO_ROOT/QODER.md"
+# Amp, Kiro CLI, IBM Bob, and Pi all share AGENTS.md — use AGENTS_FILE to avoid
+# updating the same file multiple times.
+AMP_FILE="$AGENTS_FILE"
+SHAI_FILE="$REPO_ROOT/SHAI.md"
+TABNINE_FILE="$REPO_ROOT/TABNINE.md"
+KIRO_FILE="$AGENTS_FILE"
+AGY_FILE="$REPO_ROOT/.agent/rules/specify-rules.md"
+BOB_FILE="$AGENTS_FILE"
+VIBE_FILE="$REPO_ROOT/.vibe/agents/specify-agents.md"
+KIMI_FILE="$REPO_ROOT/KIMI.md"
+TRAE_FILE="$REPO_ROOT/.trae/rules/AGENTS.md"
+IFLOW_FILE="$REPO_ROOT/IFLOW.md"
+
+# Template file
+TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md"
+
+# Global variables for parsed plan data
+NEW_LANG=""
+NEW_FRAMEWORK=""
+NEW_DB=""
+NEW_PROJECT_TYPE=""
+
+#==============================================================================
+# Utility Functions
+#==============================================================================
+
+log_info() {
+    echo "INFO: $1"
+}
+
+log_success() {
+    echo "✓ $1"
+}
+
+log_error() {
+    echo "ERROR: $1" >&2
+}
+
+log_warning() {
+    echo "WARNING: $1" >&2
+}
+
+# Cleanup function for temporary files
+cleanup() {
+    local exit_code=$?
+    # Disarm traps to prevent re-entrant loop
+    trap - EXIT INT TERM
+    rm -f /tmp/agent_update_*_$$
+    rm -f /tmp/manual_additions_$$
+    exit $exit_code
+}
+
+# Set up cleanup trap
+trap cleanup EXIT INT TERM
+
+#==============================================================================
+# Validation Functions
+#==============================================================================
+
+validate_environment() {
+    # Check if we have a current branch/feature (git or non-git)
+    if [[ -z "$CURRENT_BRANCH" ]]; then
+        log_error "Unable to determine current feature"
+        if [[ "$HAS_GIT" == "true" ]]; then
+            log_info "Make sure you're on a feature branch"
+        else
+            log_info "Set SPECIFY_FEATURE environment variable or create a feature first"
+        fi
+        exit 1
+    fi
+    
+    # Check if plan.md exists
+    if [[ ! -f "$NEW_PLAN" ]]; then
+        log_error "No plan.md found at $NEW_PLAN"
+        log_info "Make sure you're working on a feature with a corresponding spec directory"
+        if [[ "$HAS_GIT" != "true" ]]; then
+            log_info "Use: export SPECIFY_FEATURE=your-feature-name or create a new feature first"
+        fi
+        exit 1
+    fi
+    
+    # Check if template exists (needed for new files)
+    if [[ ! -f "$TEMPLATE_FILE" ]]; then
+        log_warning "Template file not found at $TEMPLATE_FILE"
+        log_warning "Creating new agent files will fail"
+    fi
+}
+
+#==============================================================================
+# Plan Parsing Functions
+#==============================================================================
+
+extract_plan_field() {
+    local field_pattern="$1"
+    local plan_file="$2"
+    
+    grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null | \
+        head -1 | \
+        sed "s|^\*\*${field_pattern}\*\*: ||" | \
+        sed 's/^[ \t]*//;s/[ \t]*$//' | \
+        grep -v "NEEDS CLARIFICATION" | \
+        grep -v "^N/A$" || echo ""
+}
+
+parse_plan_data() {
+    local plan_file="$1"
+    
+    if [[ ! -f "$plan_file" ]]; then
+        log_error "Plan file not found: $plan_file"
+        return 1
+    fi
+    
+    if [[ ! -r "$plan_file" ]]; then
+        log_error "Plan file is not readable: $plan_file"
+        return 1
+    fi
+    
+    log_info "Parsing plan data from $plan_file"
+    
+    NEW_LANG=$(extract_plan_field "Language/Version" "$plan_file")
+    NEW_FRAMEWORK=$(extract_plan_field "Primary Dependencies" "$plan_file")
+    NEW_DB=$(extract_plan_field "Storage" "$plan_file")
+    NEW_PROJECT_TYPE=$(extract_plan_field "Project Type" "$plan_file")
+    
+    # Log what we found
+    if [[ -n "$NEW_LANG" ]]; then
+        log_info "Found language: $NEW_LANG"
+    else
+        log_warning "No language information found in plan"
+    fi
+    
+    if [[ -n "$NEW_FRAMEWORK" ]]; then
+        log_info "Found framework: $NEW_FRAMEWORK"
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
+        log_info "Found database: $NEW_DB"
+    fi
+    
+    if [[ -n "$NEW_PROJECT_TYPE" ]]; then
+        log_info "Found project type: $NEW_PROJECT_TYPE"
+    fi
+}
+
+format_technology_stack() {
+    local lang="$1"
+    local framework="$2"
+    local parts=()
+    
+    # Add non-empty parts
+    [[ -n "$lang" && "$lang" != "NEEDS CLARIFICATION" ]] && parts+=("$lang")
+    [[ -n "$framework" && "$framework" != "NEEDS CLARIFICATION" && "$framework" != "N/A" ]] && parts+=("$framework")
+    
+    # Join with proper formatting
+    if [[ ${#parts[@]} -eq 0 ]]; then
+        echo ""
+    elif [[ ${#parts[@]} -eq 1 ]]; then
+        echo "${parts[0]}"
+    else
+        # Join multiple parts with " + "
+        local result="${parts[0]}"
+        for ((i=1; i<${#parts[@]}; i++)); do
+            result="$result + ${parts[i]}"
+        done
+        echo "$result"
+    fi
+}
+
+#==============================================================================
+# Template and Content Generation Functions
+#==============================================================================
+
+get_project_structure() {
+    local project_type="$1"
+    
+    if [[ "$project_type" == *"web"* ]]; then
+        echo "backend/\\nfrontend/\\ntests/"
+    else
+        echo "src/\\ntests/"
+    fi
+}
+
+get_commands_for_language() {
+    local lang="$1"
+    
+    case "$lang" in
+        *"Python"*)
+            echo "cd src && pytest && ruff check ."
+            ;;
+        *"Rust"*)
+            echo "cargo test && cargo clippy"
+            ;;
+        *"JavaScript"*|*"TypeScript"*)
+            echo "npm test \\&\\& npm run lint"
+            ;;
+        *)
+            echo "# Add commands for $lang"
+            ;;
+    esac
+}
+
+get_language_conventions() {
+    local lang="$1"
+    echo "$lang: Follow standard conventions"
+}
+
+create_new_agent_file() {
+    local target_file="$1"
+    local temp_file="$2"
+    local project_name="$3"
+    local current_date="$4"
+    
+    if [[ ! -f "$TEMPLATE_FILE" ]]; then
+        log_error "Template not found at $TEMPLATE_FILE"
+        return 1
+    fi
+    
+    if [[ ! -r "$TEMPLATE_FILE" ]]; then
+        log_error "Template file is not readable: $TEMPLATE_FILE"
+        return 1
+    fi
+    
+    log_info "Creating new agent context file from template..."
+    
+    if ! cp "$TEMPLATE_FILE" "$temp_file"; then
+        log_error "Failed to copy template file"
+        return 1
+    fi
+    
+    # Replace template placeholders
+    local project_structure
+    project_structure=$(get_project_structure "$NEW_PROJECT_TYPE")
+    
+    local commands
+    commands=$(get_commands_for_language "$NEW_LANG")
+    
+    local language_conventions
+    language_conventions=$(get_language_conventions "$NEW_LANG")
+    
+    # Perform substitutions with error checking using safer approach
+    # Escape special characters for sed by using a different delimiter or escaping
+    local escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    local escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    local escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    
+    # Build technology stack and recent change strings conditionally
+    local tech_stack
+    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
+        tech_stack="- $escaped_lang + $escaped_framework ($escaped_branch)"
+    elif [[ -n "$escaped_lang" ]]; then
+        tech_stack="- $escaped_lang ($escaped_branch)"
+    elif [[ -n "$escaped_framework" ]]; then
+        tech_stack="- $escaped_framework ($escaped_branch)"
+    else
+        tech_stack="- ($escaped_branch)"
+    fi
+
+    local recent_change
+    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_lang + $escaped_framework"
+    elif [[ -n "$escaped_lang" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_lang"
+    elif [[ -n "$escaped_framework" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_framework"
+    else
+        recent_change="- $escaped_branch: Added"
+    fi
+
+    local substitutions=(
+        "s|\[PROJECT NAME\]|$project_name|"
+        "s|\[DATE\]|$current_date|"
+        "s|\[EXTRACTED FROM ALL PLAN.MD FILES\]|$tech_stack|"
+        "s|\[ACTUAL STRUCTURE FROM PLANS\]|$project_structure|g"
+        "s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$commands|"
+        "s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$language_conventions|"
+        "s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|$recent_change|"
+    )
+    
+    for substitution in "${substitutions[@]}"; do
+        if ! sed -i.bak -e "$substitution" "$temp_file"; then
+            log_error "Failed to perform substitution: $substitution"
+            rm -f "$temp_file" "$temp_file.bak"
+            return 1
+        fi
+    done
+    
+    # Convert \n sequences to actual newlines
+    newline=$(printf '\n')
+    sed -i.bak2 "s/\\\\n/${newline}/g" "$temp_file"
+
+    # Clean up backup files
+    rm -f "$temp_file.bak" "$temp_file.bak2"
+
+    # Prepend Cursor frontmatter for .mdc files so rules are auto-included
+    if [[ "$target_file" == *.mdc ]]; then
+        local frontmatter_file
+        frontmatter_file=$(mktemp) || return 1
+        printf '%s\n' "---" "description: Project Development Guidelines" "globs: [\"**/*\"]" "alwaysApply: true" "---" "" > "$frontmatter_file"
+        cat "$temp_file" >> "$frontmatter_file"
+        mv "$frontmatter_file" "$temp_file"
+    fi
+
+    return 0
+}
+
+
+
+
+update_existing_agent_file() {
+    local target_file="$1"
+    local current_date="$2"
+    
+    log_info "Updating existing agent context file..."
+    
+    # Use a single temporary file for atomic update
+    local temp_file
+    temp_file=$(mktemp) || {
+        log_error "Failed to create temporary file"
+        return 1
+    }
+    
+    # Process the file in one pass
+    local tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK")
+    local new_tech_entries=()
+    local new_change_entry=""
+    
+    # Prepare new technology entries
+    if [[ -n "$tech_stack" ]] && ! grep -q "$tech_stack" "$target_file"; then
+        new_tech_entries+=("- $tech_stack ($CURRENT_BRANCH)")
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]] && ! grep -q "$NEW_DB" "$target_file"; then
+        new_tech_entries+=("- $NEW_DB ($CURRENT_BRANCH)")
+    fi
+    
+    # Prepare new change entry
+    if [[ -n "$tech_stack" ]]; then
+        new_change_entry="- $CURRENT_BRANCH: Added $tech_stack"
+    elif [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]]; then
+        new_change_entry="- $CURRENT_BRANCH: Added $NEW_DB"
+    fi
+    
+    # Check if sections exist in the file
+    local has_active_technologies=0
+    local has_recent_changes=0
+    
+    if grep -q "^## Active Technologies" "$target_file" 2>/dev/null; then
+        has_active_technologies=1
+    fi
+    
+    if grep -q "^## Recent Changes" "$target_file" 2>/dev/null; then
+        has_recent_changes=1
+    fi
+    
+    # Process file line by line
+    local in_tech_section=false
+    local in_changes_section=false
+    local tech_entries_added=false
+    local changes_entries_added=false
+    local existing_changes_count=0
+    local file_ended=false
+    
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        # Handle Active Technologies section
+        if [[ "$line" == "## Active Technologies" ]]; then
+            echo "$line" >> "$temp_file"
+            in_tech_section=true
+            continue
+        elif [[ $in_tech_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            # Add new tech entries before closing the section
+            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+                tech_entries_added=true
+            fi
+            echo "$line" >> "$temp_file"
+            in_tech_section=false
+            continue
+        elif [[ $in_tech_section == true ]] && [[ -z "$line" ]]; then
+            # Add new tech entries before empty line in tech section
+            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+                tech_entries_added=true
+            fi
+            echo "$line" >> "$temp_file"
+            continue
+        fi
+        
+        # Handle Recent Changes section
+        if [[ "$line" == "## Recent Changes" ]]; then
+            echo "$line" >> "$temp_file"
+            # Add new change entry right after the heading
+            if [[ -n "$new_change_entry" ]]; then
+                echo "$new_change_entry" >> "$temp_file"
+            fi
+            in_changes_section=true
+            changes_entries_added=true
+            continue
+        elif [[ $in_changes_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            echo "$line" >> "$temp_file"
+            in_changes_section=false
+            continue
+        elif [[ $in_changes_section == true ]] && [[ "$line" == "- "* ]]; then
+            # Keep only first 2 existing changes
+            if [[ $existing_changes_count -lt 2 ]]; then
+                echo "$line" >> "$temp_file"
+                ((existing_changes_count++))
+            fi
+            continue
+        fi
+        
+        # Update timestamp
+        if [[ "$line" =~ (\*\*)?Last\ updated(\*\*)?:.*[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] ]]; then
+            echo "$line" | sed "s/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/$current_date/" >> "$temp_file"
+        else
+            echo "$line" >> "$temp_file"
+        fi
+    done < "$target_file"
+    
+    # Post-loop check: if we're still in the Active Technologies section and haven't added new entries
+    if [[ $in_tech_section == true ]] && [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+        tech_entries_added=true
+    fi
+    
+    # If sections don't exist, add them at the end of the file
+    if [[ $has_active_technologies -eq 0 ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+        echo "" >> "$temp_file"
+        echo "## Active Technologies" >> "$temp_file"
+        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+        tech_entries_added=true
+    fi
+    
+    if [[ $has_recent_changes -eq 0 ]] && [[ -n "$new_change_entry" ]]; then
+        echo "" >> "$temp_file"
+        echo "## Recent Changes" >> "$temp_file"
+        echo "$new_change_entry" >> "$temp_file"
+        changes_entries_added=true
+    fi
+    
+    # Ensure Cursor .mdc files have YAML frontmatter for auto-inclusion
+    if [[ "$target_file" == *.mdc ]]; then
+        if ! head -1 "$temp_file" | grep -q '^---'; then
+            local frontmatter_file
+            frontmatter_file=$(mktemp) || { rm -f "$temp_file"; return 1; }
+            printf '%s\n' "---" "description: Project Development Guidelines" "globs: [\"**/*\"]" "alwaysApply: true" "---" "" > "$frontmatter_file"
+            cat "$temp_file" >> "$frontmatter_file"
+            mv "$frontmatter_file" "$temp_file"
+        fi
+    fi
+
+    # Move temp file to target atomically
+    if ! mv "$temp_file" "$target_file"; then
+        log_error "Failed to update target file"
+        rm -f "$temp_file"
+        return 1
+    fi
+
+    return 0
+}
+#==============================================================================
+# Main Agent File Update Function
+#==============================================================================
+
+update_agent_file() {
+    local target_file="$1"
+    local agent_name="$2"
+    
+    if [[ -z "$target_file" ]] || [[ -z "$agent_name" ]]; then
+        log_error "update_agent_file requires target_file and agent_name parameters"
+        return 1
+    fi
+    
+    log_info "Updating $agent_name context file: $target_file"
+    
+    local project_name
+    project_name=$(basename "$REPO_ROOT")
+    local current_date
+    current_date=$(date +%Y-%m-%d)
+    
+    # Create directory if it doesn't exist
+    local target_dir
+    target_dir=$(dirname "$target_file")
+    if [[ ! -d "$target_dir" ]]; then
+        if ! mkdir -p "$target_dir"; then
+            log_error "Failed to create directory: $target_dir"
+            return 1
+        fi
+    fi
+    
+    if [[ ! -f "$target_file" ]]; then
+        # Create new file from template
+        local temp_file
+        temp_file=$(mktemp) || {
+            log_error "Failed to create temporary file"
+            return 1
+        }
+        
+        if create_new_agent_file "$target_file" "$temp_file" "$project_name" "$current_date"; then
+            if mv "$temp_file" "$target_file"; then
+                log_success "Created new $agent_name context file"
+            else
+                log_error "Failed to move temporary file to $target_file"
+                rm -f "$temp_file"
+                return 1
+            fi
+        else
+            log_error "Failed to create new agent file"
+            rm -f "$temp_file"
+            return 1
+        fi
+    else
+        # Update existing file
+        if [[ ! -r "$target_file" ]]; then
+            log_error "Cannot read existing file: $target_file"
+            return 1
+        fi
+        
+        if [[ ! -w "$target_file" ]]; then
+            log_error "Cannot write to existing file: $target_file"
+            return 1
+        fi
+        
+        if update_existing_agent_file "$target_file" "$current_date"; then
+            log_success "Updated existing $agent_name context file"
+        else
+            log_error "Failed to update existing agent file"
+            return 1
+        fi
+    fi
+    
+    return 0
+}
+
+#==============================================================================
+# Agent Selection and Processing
+#==============================================================================
+
+update_specific_agent() {
+    local agent_type="$1"
+    
+    case "$agent_type" in
+        claude)
+            update_agent_file "$CLAUDE_FILE" "Claude Code" || return 1
+            ;;
+        gemini)
+            update_agent_file "$GEMINI_FILE" "Gemini CLI" || return 1
+            ;;
+        copilot)
+            update_agent_file "$COPILOT_FILE" "GitHub Copilot" || return 1
+            ;;
+        cursor-agent)
+            update_agent_file "$CURSOR_FILE" "Cursor IDE" || return 1
+            ;;
+        qwen)
+            update_agent_file "$QWEN_FILE" "Qwen Code" || return 1
+            ;;
+        opencode)
+            update_agent_file "$AGENTS_FILE" "opencode" || return 1
+            ;;
+        codex)
+            update_agent_file "$AGENTS_FILE" "Codex CLI" || return 1
+            ;;
+        windsurf)
+            update_agent_file "$WINDSURF_FILE" "Windsurf" || return 1
+            ;;
+        kilocode)
+            update_agent_file "$KILOCODE_FILE" "Kilo Code" || return 1
+            ;;
+        auggie)
+            update_agent_file "$AUGGIE_FILE" "Auggie CLI" || return 1
+            ;;
+        roo)
+            update_agent_file "$ROO_FILE" "Roo Code" || return 1
+            ;;
+        codebuddy)
+            update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI" || return 1
+            ;;
+        qodercli)
+            update_agent_file "$QODER_FILE" "Qoder CLI" || return 1
+            ;;
+        amp)
+            update_agent_file "$AMP_FILE" "Amp" || return 1
+            ;;
+        shai)
+            update_agent_file "$SHAI_FILE" "SHAI" || return 1
+            ;;
+        tabnine)
+            update_agent_file "$TABNINE_FILE" "Tabnine CLI" || return 1
+            ;;
+        kiro-cli)
+            update_agent_file "$KIRO_FILE" "Kiro CLI" || return 1
+            ;;
+        agy)
+            update_agent_file "$AGY_FILE" "Antigravity" || return 1
+            ;;
+        bob)
+            update_agent_file "$BOB_FILE" "IBM Bob" || return 1
+            ;;
+        vibe)
+            update_agent_file "$VIBE_FILE" "Mistral Vibe" || return 1
+            ;;
+        kimi)
+            update_agent_file "$KIMI_FILE" "Kimi Code" || return 1
+            ;;
+        trae)
+            update_agent_file "$TRAE_FILE" "Trae" || return 1
+            ;;
+        pi)
+            update_agent_file "$AGENTS_FILE" "Pi Coding Agent" || return 1
+            ;;
+        iflow)
+            update_agent_file "$IFLOW_FILE" "iFlow CLI" || return 1
+            ;;
+        generic)
+            log_info "Generic agent: no predefined context file. Use the agent-specific update script for your agent."
+            ;;
+        *)
+            log_error "Unknown agent type '$agent_type'"
+            log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|pi|iflow|generic"
+            exit 1
+            ;;
+    esac
+}
+
+# Helper: skip non-existent files and files already updated (dedup by
+# realpath so that variables pointing to the same file — e.g. AMP_FILE,
+# KIRO_FILE, BOB_FILE all resolving to AGENTS_FILE — are only written once).
+# Uses a linear array instead of associative array for bash 3.2 compatibility.
+# Note: defined at top level because bash 3.2 does not support true
+# nested/local functions. _updated_paths, _found_agent, and _all_ok are
+# initialised exclusively inside update_all_existing_agents so that
+# sourcing this script has no side effects on the caller's environment.
+
+_update_if_new() {
+    local file="$1" name="$2"
+    [[ -f "$file" ]] || return 0
+    local real_path
+    real_path=$(realpath "$file" 2>/dev/null || echo "$file")
+    local p
+    if [[ ${#_updated_paths[@]} -gt 0 ]]; then
+        for p in "${_updated_paths[@]}"; do
+            [[ "$p" == "$real_path" ]] && return 0
+        done
+    fi
+    # Record the file as seen before attempting the update so that:
+    # (a) aliases pointing to the same path are not retried on failure
+    # (b) _found_agent reflects file existence, not update success
+    _updated_paths+=("$real_path")
+    _found_agent=true
+    update_agent_file "$file" "$name"
+}
+
+update_all_existing_agents() {
+    _found_agent=false
+    _updated_paths=()
+    local _all_ok=true
+
+    _update_if_new "$CLAUDE_FILE" "Claude Code"           || _all_ok=false
+    _update_if_new "$GEMINI_FILE" "Gemini CLI"             || _all_ok=false
+    _update_if_new "$COPILOT_FILE" "GitHub Copilot"        || _all_ok=false
+    _update_if_new "$CURSOR_FILE" "Cursor IDE"             || _all_ok=false
+    _update_if_new "$QWEN_FILE" "Qwen Code"                || _all_ok=false
+    _update_if_new "$AGENTS_FILE" "Codex/opencode"         || _all_ok=false
+    _update_if_new "$AMP_FILE" "Amp"                       || _all_ok=false
+    _update_if_new "$KIRO_FILE" "Kiro CLI"                 || _all_ok=false
+    _update_if_new "$BOB_FILE" "IBM Bob"                   || _all_ok=false
+    _update_if_new "$WINDSURF_FILE" "Windsurf"             || _all_ok=false
+    _update_if_new "$KILOCODE_FILE" "Kilo Code"            || _all_ok=false
+    _update_if_new "$AUGGIE_FILE" "Auggie CLI"             || _all_ok=false
+    _update_if_new "$ROO_FILE" "Roo Code"                  || _all_ok=false
+    _update_if_new "$CODEBUDDY_FILE" "CodeBuddy CLI"       || _all_ok=false
+    _update_if_new "$SHAI_FILE" "SHAI"                     || _all_ok=false
+    _update_if_new "$TABNINE_FILE" "Tabnine CLI"           || _all_ok=false
+    _update_if_new "$QODER_FILE" "Qoder CLI"               || _all_ok=false
+    _update_if_new "$AGY_FILE" "Antigravity"               || _all_ok=false
+    _update_if_new "$VIBE_FILE" "Mistral Vibe"             || _all_ok=false
+    _update_if_new "$KIMI_FILE" "Kimi Code"                || _all_ok=false
+    _update_if_new "$TRAE_FILE" "Trae"                     || _all_ok=false
+    _update_if_new "$IFLOW_FILE" "iFlow CLI"               || _all_ok=false
+
+    # If no agent files exist, create a default Claude file
+    if [[ "$_found_agent" == false ]]; then
+        log_info "No existing agent files found, creating default Claude file..."
+        update_agent_file "$CLAUDE_FILE" "Claude Code" || return 1
+    fi
+
+    [[ "$_all_ok" == true ]]
+}
+print_summary() {
+    echo
+    log_info "Summary of changes:"
+    
+    if [[ -n "$NEW_LANG" ]]; then
+        echo "  - Added language: $NEW_LANG"
+    fi
+    
+    if [[ -n "$NEW_FRAMEWORK" ]]; then
+        echo "  - Added framework: $NEW_FRAMEWORK"
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
+        echo "  - Added database: $NEW_DB"
+    fi
+    
+    echo
+    log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|pi|iflow|generic]"
+}
+
+#==============================================================================
+# Main Execution
+#==============================================================================
+
+main() {
+    # Validate environment before proceeding
+    validate_environment
+    
+    log_info "=== Updating agent context files for feature $CURRENT_BRANCH ==="
+    
+    # Parse the plan file to extract project information
+    if ! parse_plan_data "$NEW_PLAN"; then
+        log_error "Failed to parse plan data"
+        exit 1
+    fi
+    
+    # Process based on agent type argument
+    local success=true
+    
+    if [[ -z "$AGENT_TYPE" ]]; then
+        # No specific agent provided - update all existing agent files
+        log_info "No agent specified, updating all existing agent files..."
+        if ! update_all_existing_agents; then
+            success=false
+        fi
+    else
+        # Specific agent provided - update only that agent
+        log_info "Updating specific agent: $AGENT_TYPE"
+        if ! update_specific_agent "$AGENT_TYPE"; then
+            success=false
+        fi
+    fi
+    
+    # Print summary
+    print_summary
+    
+    if [[ "$success" == true ]]; then
+        log_success "Agent context update completed successfully"
+        exit 0
+    else
+        log_error "Agent context update completed with errors"
+        exit 1
+    fi
+}
+
+# Execute main function if script is run directly
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi
diff --git a/.specify/templates/agent-file-template.md b/.specify/templates/agent-file-template.md
new file mode 100644
index 0000000..4cc7fd6
--- /dev/null
+++ b/.specify/templates/agent-file-template.md
@@ -0,0 +1,28 @@
+# [PROJECT NAME] Development Guidelines
+
+Auto-generated from all feature plans. Last updated: [DATE]
+
+## Active Technologies
+
+[EXTRACTED FROM ALL PLAN.MD FILES]
+
+## Project Structure
+
+```text
+[ACTUAL STRUCTURE FROM PLANS]
+```
+
+## Commands
+
+[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
+
+## Code Style
+
+[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
+
+## Recent Changes
+
+[LAST 3 FEATURES AND WHAT THEY ADDED]
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->
diff --git a/.specify/templates/checklist-template.md b/.specify/templates/checklist-template.md
new file mode 100644
index 0000000..806657d
--- /dev/null
+++ b/.specify/templates/checklist-template.md
@@ -0,0 +1,40 @@
+# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
+
+**Purpose**: [Brief description of what this checklist covers]
+**Created**: [DATE]
+**Feature**: [Link to spec.md or relevant documentation]
+
+**Note**: This checklist is generated by the `/speckit.checklist` command based on feature context and requirements.
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
+  
+  The /speckit.checklist command MUST replace these with actual items based on:
+  - User's specific checklist request
+  - Feature requirements from spec.md
+  - Technical context from plan.md
+  - Implementation details from tasks.md
+  
+  DO NOT keep these sample items in the generated checklist file.
+  ============================================================================
+-->
+
+## [Category 1]
+
+- [ ] CHK001 First checklist item with clear action
+- [ ] CHK002 Second checklist item
+- [ ] CHK003 Third checklist item
+
+## [Category 2]
+
+- [ ] CHK004 Another category item
+- [ ] CHK005 Item with specific criteria
+- [ ] CHK006 Final item in this category
+
+## Notes
+
+- Check items off as completed: `[x]`
+- Add comments or findings inline
+- Link to relevant resources or documentation
+- Items are numbered sequentially for easy reference
diff --git a/.specify/templates/constitution-template.md b/.specify/templates/constitution-template.md
new file mode 100644
index 0000000..a4670ff
--- /dev/null
+++ b/.specify/templates/constitution-template.md
@@ -0,0 +1,50 @@
+# [PROJECT_NAME] Constitution
+<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
+
+## Core Principles
+
+### [PRINCIPLE_1_NAME]
+<!-- Example: I. Library-First -->
+[PRINCIPLE_1_DESCRIPTION]
+<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
+
+### [PRINCIPLE_2_NAME]
+<!-- Example: II. CLI Interface -->
+[PRINCIPLE_2_DESCRIPTION]
+<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
+
+### [PRINCIPLE_3_NAME]
+<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
+[PRINCIPLE_3_DESCRIPTION]
+<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
+
+### [PRINCIPLE_4_NAME]
+<!-- Example: IV. Integration Testing -->
+[PRINCIPLE_4_DESCRIPTION]
+<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
+
+### [PRINCIPLE_5_NAME]
+<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
+[PRINCIPLE_5_DESCRIPTION]
+<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
+
+## [SECTION_2_NAME]
+<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
+
+[SECTION_2_CONTENT]
+<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
+
+## [SECTION_3_NAME]
+<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
+
+[SECTION_3_CONTENT]
+<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
+
+## Governance
+<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
+
+[GOVERNANCE_RULES]
+<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
+
+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
+<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md
new file mode 100644
index 0000000..5a2fafe
--- /dev/null
+++ b/.specify/templates/plan-template.md
@@ -0,0 +1,104 @@
+# Implementation Plan: [FEATURE]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+
+**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow.
+
+## Summary
+
+[Extract from feature spec: primary requirement + technical approach from research]
+
+## Technical Context
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
+**Project Type**: [e.g., library/cli/web-service/mobile-app/compiler/desktop-app or NEEDS CLARIFICATION]  
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+[Gates determined based on constitution file]
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Phase 1 output (/speckit.plan command)
+├── quickstart.md        # Phase 1 output (/speckit.plan command)
+├── contracts/           # Phase 1 output (/speckit.plan command)
+└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
+```
+
+### Source Code (repository root)
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```text
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
+```
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
diff --git a/.specify/templates/spec-template.md b/.specify/templates/spec-template.md
new file mode 100644
index 0000000..c67d914
--- /dev/null
+++ b/.specify/templates/spec-template.md
@@ -0,0 +1,115 @@
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`  
+**Created**: [DATE]  
+**Status**: Draft  
+**Input**: User description: "$ARGUMENTS"
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+  
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
+-->
+
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Requirements *(mandatory)*
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+*Example of marking unclear requirements:*
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Key Entities *(include if feature involves data)*
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]
diff --git a/.specify/templates/tasks-template.md b/.specify/templates/tasks-template.md
new file mode 100644
index 0000000..60f9be4
--- /dev/null
+++ b/.specify/templates/tasks-template.md
@@ -0,0 +1,251 @@
+---
+
+description: "Task list template for feature implementation"
+---
+
+# Tasks: [FEATURE NAME]
+
+**Input**: Design documents from `/specs/[###-feature-name]/`
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Single project**: `src/`, `tests/` at repository root
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
+- Paths shown below assume single project - adjust based on plan.md structure
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
+  
+  The /speckit.tasks command MUST replace these with actual tasks based on:
+  - User stories from spec.md (with their priorities P1, P2, P3...)
+  - Feature requirements from plan.md
+  - Entities from data-model.md
+  - Endpoints from contracts/
+  
+  Tasks MUST be organized by user story so each story can be:
+  - Implemented independently
+  - Tested independently
+  - Delivered as an MVP increment
+  
+  DO NOT keep these sample tasks in the generated tasks.md file.
+  ============================================================================
+-->
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and basic structure
+
+- [ ] T001 Create project structure per implementation plan
+- [ ] T002 Initialize [language] project with [framework] dependencies
+- [ ] T003 [P] Configure linting and formatting tools
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+Examples of foundational tasks (adjust based on your project):
+
+- [ ] T004 Setup database schema and migrations framework
+- [ ] T005 [P] Implement authentication/authorization framework
+- [ ] T006 [P] Setup API routing and middleware structure
+- [ ] T007 Create base models/entities that all stories depend on
+- [ ] T008 Configure error handling and logging infrastructure
+- [ ] T009 Setup environment configuration management
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
+
+---
+
+## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 1
+
+- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
+- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
+- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
+- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T016 [US1] Add validation and error handling
+- [ ] T017 [US1] Add logging for user story 1 operations
+
+**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
+
+---
+
+## Phase 4: User Story 2 - [Title] (Priority: P2)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 2
+
+- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
+- [ ] T021 [US2] Implement [Service] in src/services/[service].py
+- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
+
+**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - [Title] (Priority: P3)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 3
+
+- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
+- [ ] T027 [US3] Implement [Service] in src/services/[service].py
+- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+[Add more user story phases as needed, following the same pattern]
+
+---
+
+## Phase N: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories
+
+- [ ] TXXX [P] Documentation updates in docs/
+- [ ] TXXX Code cleanup and refactoring
+- [ ] TXXX Performance optimization across all stories
+- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
+- [ ] TXXX Security hardening
+- [ ] TXXX Run quickstart.md validation
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: All depend on Foundational phase completion
+  - User stories can then proceed in parallel (if staffed)
+  - Or sequentially in priority order (P1 → P2 → P3)
+- **Polish (Final Phase)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
+
+### Within Each User Story
+
+- Tests (if included) MUST be written and FAIL before implementation
+- Models before services
+- Services before endpoints
+- Core implementation before integration
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- All Setup tasks marked [P] can run in parallel
+- All Foundational tasks marked [P] can run in parallel (within Phase 2)
+- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
+- All tests for a user story marked [P] can run in parallel
+- Models within a story marked [P] can run in parallel
+- Different user stories can be worked on in parallel by different team members
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Launch all tests for User Story 1 together (if tests requested):
+Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
+Task: "Integration test for [user journey] in tests/integration/test_[name].py"
+
+# Launch all models for User Story 1 together:
+Task: "Create [Entity1] model in src/models/[entity1].py"
+Task: "Create [Entity2] model in src/models/[entity2].py"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+3. Complete Phase 3: User Story 1
+4. **STOP and VALIDATE**: Test User Story 1 independently
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
+3. Add User Story 2 → Test independently → Deploy/Demo
+4. Add User Story 3 → Test independently → Deploy/Demo
+5. Each story adds value without breaking previous stories
+
+### Parallel Team Strategy
+
+With multiple developers:
+
+1. Team completes Setup + Foundational together
+2. Once Foundational is done:
+   - Developer A: User Story 1
+   - Developer B: User Story 2
+   - Developer C: User Story 3
+3. Stories complete and integrate independently
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies
+- [Story] label maps task to specific user story for traceability
+- Each user story should be independently completable and testable
+- Verify tests fail before implementing
+- Commit after each task or logical group
+- Stop at any checkpoint to validate story independently
+- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..754b7d5
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,29 @@
+# wildcard Development Guidelines
+
+Auto-generated from all feature plans. Last updated: 2026-03-20
+
+## Active Technologies
+
+- TypeScript, Bun ≥ 1.3.8 + Commander v14 (CLI), bun:sqlite (storage) (001-log-command)
+
+## Project Structure
+
+```text
+src/
+tests/
+```
+
+## Commands
+
+bun test && bun run lint
+
+## Code Style
+
+TypeScript, Bun ≥ 1.3.8: Follow standard conventions
+
+## Recent Changes
+
+- 001-log-command: Added TypeScript, Bun ≥ 1.3.8 + Commander v14 (CLI), bun:sqlite (storage)
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->
diff --git a/specs/001-log-command/checklists/requirements.md b/specs/001-log-command/checklists/requirements.md
new file mode 100644
index 0000000..600ca99
--- /dev/null
+++ b/specs/001-log-command/checklists/requirements.md
@@ -0,0 +1,67 @@
+# Requirements Checklist: Log Command
+
+**Purpose**: Validate that the spec for the `log` command is complete, consistent, and implementation-ready
+**Created**: 2026-03-20
+**Feature**: [spec.md](../spec.md)
+
+## Spec Completeness
+
+- [x] CHK001 All mandatory sections present (User Scenarios, Requirements, Success Criteria)
+- [x] CHK002 User stories have priorities assigned (P1, P2, P3)
+- [x] CHK003 Each user story has acceptance scenarios in Given/When/Then format
+- [x] CHK004 Each user story has an independent test description
+- [x] CHK005 Edge cases section is populated with specific scenarios (not placeholders)
+- [x] CHK006 Functional requirements use MUST/SHOULD/MAY language correctly
+- [x] CHK007 Key entities are defined with clear descriptions
+
+## User Story Quality
+
+- [x] CHK008 P1 story is independently viable as an MVP
+- [x] CHK009 Each story delivers standalone user value
+- [x] CHK010 Example output is provided for primary use cases
+- [x] CHK011 Stories cover the full scope: core view (P1), period/filter (P2), machine output (P3)
+
+## Requirements Traceability
+
+- [x] CHK012 Every user story maps to at least one functional requirement
+- [x] CHK013 Every functional requirement maps to at least one acceptance scenario
+- [x] CHK014 No orphan requirements (requirements without a user story)
+- [x] CHK015 No contradicting requirements
+
+## Edge Case Coverage
+
+- [x] CHK016 Session boundary splitting is specified (proportional duration, edit assignment)
+- [x] CHK017 Empty state handling is specified
+- [x] CHK018 Cross-midnight sessions are addressed
+- [x] CHK019 Mid-week behavior for week view is specified
+- [x] CHK020 Multi-project same-slot ordering is specified
+
+## Design Decision Validation
+
+- [x] CHK021 Command is a top-level command (not a flag on existing command) — per expert review
+- [x] CHK022 Command name is `log` (not `timeline`) — per expert review to avoid brand-noun overload
+- [x] CHK023 Automatic granularity (hourly/daily) — no `--granularity` flag per expert review
+- [x] CHK024 Empty hours skipped (not shown as placeholders) — per expert review
+- [x] CHK025 `--json` included from day one — per expert review
+
+## Implementation Readiness
+
+- [x] CHK026 Critical files section identifies both existing files to modify and new files to create
+- [x] CHK027 Data flow approach is specified (sessions → split → bucket → group)
+- [x] CHK028 Reusable utility identified (`time-bucketing.ts`)
+- [x] CHK029 Spec contains no implementation details (no language, framework, or API specifics)
+- [x] CHK030 Success criteria are measurable and technology-agnostic
+
+## Consistency with Existing System
+
+- [x] CHK031 `--device` filter matches existing command patterns
+- [x] CHK032 `--json` matches existing `status --json` pattern
+- [x] CHK033 Period arguments reuse existing period parsing infrastructure
+- [x] CHK034 Empty-state messaging reuses existing pattern
+- [x] CHK035 App usage summary matches existing `show` command pattern
+
+## Notes
+
+- Check items off as completed: `[x]`
+- All items passed validation against the spec content
+- CHK029 verified: spec uses no language names, framework references, or API calls — only behavioral requirements
diff --git a/specs/001-log-command/contracts/cli-contract.md b/specs/001-log-command/contracts/cli-contract.md
new file mode 100644
index 0000000..3d7452d
--- /dev/null
+++ b/specs/001-log-command/contracts/cli-contract.md
@@ -0,0 +1,136 @@
+# CLI Contract: `wildcard log`
+
+**Branch**: `001-log-command` | **Date**: 2026-03-20
+
+## Command Signature
+
+```
+wildcard log [period] [options]
+```
+
+### Arguments
+
+| Argument | Required | Values | Default | Description |
+|----------|----------|--------|---------|-------------|
+| period | No | `today`, `yesterday`, `week` | `today` | Time period to display |
+
+### Options
+
+| Flag | Argument | Description |
+|------|----------|-------------|
+| `--today` | none | Show today (same as `wildcard log` or `wildcard log today`) |
+| `--yesterday` | none | Show yesterday |
+| `--week` | none | Show this week |
+| `--device <ids>` | comma-separated device IDs | Filter by device(s) |
+| `--json` | none | Output machine-readable JSON |
+
+Period resolution precedence (matches existing `parsePeriod`):
+1. `--yesterday` flag → yesterday
+2. `--week` flag → week
+3. `--today` flag → today
+4. Positional `period` argument (`yesterday`, `week`) → that period
+5. Default → today
+
+## Human-Readable Output
+
+### Today / Yesterday (hourly slots)
+
+```
+{periodLabel}  ·  {N} project{s}  ·  {totalDuration} active
+
+  {HH:MM}–{HH:MM}  {projectName} ({branch})          {duration}   {N} edits   {N} files
+                    {projectName2} ({branch})         {duration}   {N} edits   {N} files
+  {HH:MM}–{HH:MM}  {projectName} ({branch})          {duration}   {N} edits   {N} files
+
+Top apps:
+  {appName} ({bundleId})          {duration}   {N} segments
+```
+
+Rules:
+- Time slot label shown only for the first project in a slot; subsequent projects in the same slot are indented to align
+- Projects within a slot ordered by duration descending
+- Empty hours omitted (no "(no activity)" rows)
+- Hour range: first active hour to last active hour
+- Footer: app usage section (via existing `printAppUsage`)
+- Empty state: via existing `printEmptyActivity`
+
+### Week (daily slots)
+
+```
+This Week
+
+  {Day, Mon DD}   {projectName} ({branch})          {duration}   {N} edits   {N} files
+                  {projectName2} ({branch})         {duration}   {N} edits   {N} files
+  {Day, Mon DD}   {projectName} ({branch})          {duration}   {N} edits   {N} files
+
+Top apps:
+  {appName} ({bundleId})          {duration}   {N} segments
+```
+
+Rules:
+- Day label shown only for the first project in a day; subsequent projects indented
+- Only days up to "now" shown (no future days)
+- Empty days omitted
+
+## JSON Output
+
+### Schema
+
+```json
+{
+  "period": {
+    "type": "today" | "yesterday" | "week",
+    "label": "Today (Mar 20, 2026)",
+    "start_ts": 1710892800000,
+    "end_ts": 1710979200000
+  },
+  "summary": {
+    "total_projects": 3,
+    "total_duration_ms": 15120000,
+    "total_edits": 37
+  },
+  "slots": [
+    {
+      "start_ts": 1710925200000,
+      "end_ts": 1710928800000,
+      "label": "09:00–10:00",
+      "projects": [
+        {
+          "name": "wildcard",
+          "branches": ["main"],
+          "duration_ms": 2880000,
+          "edit_count": 12,
+          "file_count": 5
+        }
+      ]
+    }
+  ],
+  "app_usage": [
+    {
+      "app_name": "Code",
+      "bundle_id": "com.microsoft.VSCode",
+      "duration_ms": 10800000,
+      "segments": 15
+    }
+  ]
+}
+```
+
+### JSON field notes
+- All durations in milliseconds (integer)
+- All timestamps in milliseconds since epoch (integer)
+- `slots` array is ordered chronologically
+- `projects` within each slot ordered by `duration_ms` descending
+- `app_usage` matches existing `AppUsageSummary` structure
+- Empty slots are omitted from the array
+
+## Exit Codes
+
+| Code | Condition |
+|------|-----------|
+| 0 | Success (including empty activity) |
+| 1 | Unhandled error (database not found, etc.) |
+
+## stderr
+
+No output to stderr under normal operation. Errors follow existing `wildcard: {message}` pattern via the Commander error handler in `wildcard.ts`.
diff --git a/specs/001-log-command/data-model.md b/specs/001-log-command/data-model.md
new file mode 100644
index 0000000..478d069
--- /dev/null
+++ b/specs/001-log-command/data-model.md
@@ -0,0 +1,113 @@
+# Data Model: Log Command
+
+**Branch**: `001-log-command` | **Date**: 2026-03-20
+
+## Existing Entities (no changes)
+
+### Session
+The fundamental unit of continuous work. Already defined in `src/session/types.ts`.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Unique session identifier |
+| start_ts | number | Start timestamp (ms since epoch) |
+| end_ts | number | End timestamp (ms since epoch) |
+| device_id | string? | Device that recorded this session |
+| context | object | Project/app context (kind, root, name, branch) |
+| events | UnifiedEvent[] | Raw events in this session |
+| edit_count | number | Total file edits in this session |
+| file_paths | string[] | All file paths touched |
+
+### ProjectGroup
+Aggregation of sessions by project. Already defined in `src/summary/summary-builder.ts`.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| project_key | string | `{kind}:{root ?? name ?? 'unknown'}` composite key (see `projectKey()` in summary-builder.ts) |
+| display_name | string | Human-readable project name |
+| context_kind | 'git' \| 'folder' \| 'app' \| 'none' | Context type |
+| branches | string[] | Active branches |
+| sessions | Session[] | Sessions in this group |
+| total_duration_ms | number | Sum of session durations |
+| total_edits | number | Sum of edit counts |
+| all_file_paths | string[] | Deduplicated file paths |
+| start_ts | number | Earliest session start |
+| end_ts | number | Latest session end |
+
+## New Entities
+
+### TimeBucket
+A fixed-duration window that collects session fragments for display. This is a display/presentation entity — it does not persist to the database.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| start_ts | number | Bucket start timestamp (ms), inclusive |
+| end_ts | number | Bucket end timestamp (ms), exclusive |
+| sessions | SessionFragment[] | Session fragments falling in this bucket |
+
+### SessionFragment
+A portion of a session that falls within a single time bucket. Created when a session spans a bucket boundary.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| session | Session | Reference to the original session |
+| start_ts | number | Fragment start (may differ from session start) |
+| end_ts | number | Fragment end (may differ from session end) |
+| duration_ms | number | Fragment duration (end_ts - start_ts) |
+| edit_count | number | Edits assigned to this fragment |
+| file_paths | string[] | Files from the original session |
+
+**Splitting rules**:
+- Duration is split proportionally: `fragment_duration = session_duration × (overlap / total_session_duration)`
+- Edits are assigned entirely to the fragment whose bucket contains `session.start_ts`
+- File paths are copied to all fragments (a file touched in the session was potentially active in any fragment)
+
+### SlotProjectEntry
+A project's aggregated contribution within a single time slot. Created by grouping SessionFragments by project within a TimeBucket.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| display_name | string | Project name |
+| branches | string[] | Active branches |
+| duration_ms | number | Total duration in this slot |
+| edit_count | number | Total edits in this slot |
+| file_count | number | Unique files in this slot |
+
+## Data Flow
+
+```
+Input:  Session[] (from QueryService.sessions())
+          │
+          ▼
+  ┌─────────────────────┐
+  │ bucketSessionsByTime │ Split sessions at bucket boundaries
+  │ (time-bucketing.ts) │ into SessionFragment[]
+  └─────────┬───────────┘
+            │
+            ▼
+  Map<number, SessionFragment[]>   (key = bucket start_ts)
+            │
+            ▼
+  ┌─────────────────────┐
+  │ Group by project    │ Within each bucket, group fragments
+  │ per bucket          │ by project_key, sum durations/edits
+  └─────────┬───────────┘
+            │
+            ▼
+  Map<number, SlotProjectEntry[]>  (sorted by duration desc)
+            │
+            ▼
+  ┌─────────────────────┐
+  │ Render or serialize │ Human-readable table or JSON
+  └─────────────────────┘
+```
+
+## State Transitions
+
+No state transitions — all entities are read-only, computed from the existing session data. No database writes.
+
+## Validation Rules
+
+- `bucketSizeMs` must be a positive integer (enforced at call site: 3600000 for hourly, 86400000 for daily)
+- `range[0] < range[1]` (start before end, guaranteed by existing `periodRange()`)
+- Sessions with `start_ts === end_ts` (zero-duration) are placed in their start bucket with 0ms duration
diff --git a/specs/001-log-command/plan.md b/specs/001-log-command/plan.md
new file mode 100644
index 0000000..28cbaa7
--- /dev/null
+++ b/specs/001-log-command/plan.md
@@ -0,0 +1,82 @@
+# Implementation Plan: Log Command
+
+**Branch**: `001-log-command` | **Date**: 2026-03-20 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `/specs/001-log-command/spec.md`
+
+## Summary
+
+Add a `wildcard log` command that provides a chronological, time-slot-based view of activity. Today/yesterday use 1-hour slots; week uses day-level slots. Sessions spanning boundaries are split proportionally. The command reuses existing infrastructure (period parsing, session querying, project grouping, app usage display) and adds one new utility (`bucketSessionsByTime`) plus one new command handler (`cmdLog`).
+
+## Technical Context
+
+**Language/Version**: TypeScript, Bun ≥ 1.3.8
+**Primary Dependencies**: Commander v14 (CLI), bun:sqlite (storage)
+**Storage**: SQLite via `TimelineDb` — read-only for this feature (no schema changes)
+**Testing**: `bun test` (Bun's built-in test runner)
+**Target Platform**: macOS (primary), Linux
+**Project Type**: CLI tool
+**Performance Goals**: <1s response for a typical day's activity (~50 sessions)
+**Constraints**: Pure local computation, no network calls, no AI dependencies
+**Scale/Scope**: Single new command, 2 new files, 5 files modified
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+The project constitution is a blank template (no principles have been ratified). **No gates to evaluate.** Proceeding without constraints.
+
+**Post-Phase 1 re-check**: Still no constitution gates. Design is consistent with existing codebase patterns (verified by code review of `activity-show.ts`, `activity-common.ts`, `formatters.ts`, and `period.ts`).
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/001-log-command/
+├── plan.md              # This file
+├── research.md          # Phase 0: design decisions and alternatives
+├── data-model.md        # Phase 1: entity definitions and data flow
+├── quickstart.md        # Phase 1: build/run/test instructions
+├── contracts/
+│   └── cli-contract.md  # Phase 1: CLI interface specification
+├── checklists/
+│   └── requirements.md  # Quality checklist
+└── tasks.md             # Phase 2 output (created by /speckit.tasks)
+```
+
+### Source Code (repository root)
+
+```text
+src/
+├── wildcard.ts                        # MODIFY: register `log` command
+├── commands/
+│   ├── index.ts                       # MODIFY: re-export cmdLog, LogOptions
+│   ├── types.ts                       # MODIFY: add LogOptions type
+│   ├── activity.ts                    # MODIFY: add cmdLog to barrel
+│   ├── activity-log.ts                # CREATE: cmdLog handler
+│   ├── activity-common.ts             # REUSE: createActivityContext, parseDeviceFilter
+│   ├── activity-show.ts               # REFERENCE: pattern to follow
+│   ├── period.ts                      # REUSE: parsePeriod, periodRange, periodLabel
+│   └── formatters.ts                  # REUSE: printAppUsage, printEmptyActivity
+├── session/
+│   ├── index.ts                       # MODIFY: re-export time-bucketing
+│   ├── time-bucketing.ts              # CREATE: bucketSessionsByTime utility
+│   ├── time-bucketing.test.ts         # CREATE: unit tests
+│   ├── query-service.ts               # REUSE: sessions() query
+│   └── types.ts                       # REUSE: Session type
+└── summary/
+    └── summary-builder.ts             # REUSE: groupSessionsByProject
+```
+
+**Structure Decision**: This feature follows the existing flat-module structure. New files are placed alongside their related files — `time-bucketing.ts` next to `session-manager.ts`, `activity-log.ts` next to `activity-show.ts`. No new directories needed.
+
+## Complexity Tracking
+
+No constitution violations. No complexity justifications needed.
+
+The feature adds:
+- 1 pure utility function (time-bucketing)
+- 1 command handler (following the exact pattern of `activity-show.ts`)
+- 5 wiring changes (barrel exports + command registration)
+
+Total new code estimated at ~150-200 lines (excluding tests).
diff --git a/specs/001-log-command/quickstart.md b/specs/001-log-command/quickstart.md
new file mode 100644
index 0000000..fadb6a2
--- /dev/null
+++ b/specs/001-log-command/quickstart.md
@@ -0,0 +1,52 @@
+# Quickstart: Log Command
+
+**Branch**: `001-log-command` | **Date**: 2026-03-20
+
+## Prerequisites
+
+- Bun ≥ 1.3.8
+- Wildcard installed and configured (`wildcard setup`)
+- Activity data in the timeline database (run `wildcard watch` for a while first)
+
+## Build & Run
+
+```bash
+# No build step — Bun runs TypeScript directly
+bun src/wildcard.ts log
+bun src/wildcard.ts log yesterday
+bun src/wildcard.ts log --week
+bun src/wildcard.ts log --json
+bun src/wildcard.ts log --device mac
+```
+
+## Test
+
+```bash
+bun test                                      # Run all tests
+bun test src/session/time-bucketing.test.ts   # Run time-bucketing unit tests
+```
+
+## Files to Create
+
+| File | Purpose |
+|------|---------|
+| `src/session/time-bucketing.ts` | `bucketSessionsByTime()` utility — splits sessions at bucket boundaries |
+| `src/commands/activity-log.ts` | `cmdLog()` handler — the command implementation |
+| `src/session/time-bucketing.test.ts` | Unit tests for time-bucketing logic |
+
+## Files to Modify
+
+| File | Change |
+|------|--------|
+| `src/wildcard.ts` | Register `log` command with Commander |
+| `src/commands/activity.ts` | Add `cmdLog` to activity barrel export |
+| `src/commands/index.ts` | Re-export `cmdLog` and `LogOptions` type |
+| `src/commands/types.ts` | Add `LogOptions` type definition |
+| `src/session/index.ts` | Re-export `bucketSessionsByTime` and types |
+
+## Implementation Order
+
+1. `time-bucketing.ts` + tests (pure function, no dependencies beyond Session type)
+2. `activity-log.ts` (uses time-bucketing + existing infrastructure)
+3. Wire up exports and register command in `wildcard.ts`
+4. Manual smoke test with real data
diff --git a/specs/001-log-command/research.md b/specs/001-log-command/research.md
new file mode 100644
index 0000000..c881b72
--- /dev/null
+++ b/specs/001-log-command/research.md
@@ -0,0 +1,71 @@
+# Research: Log Command
+
+**Branch**: `001-log-command` | **Date**: 2026-03-20
+
+## R-001: Session Boundary Splitting Strategy
+
+**Decision**: Split sessions proportionally at hour/day boundaries. Edits assigned to the slot where the session started.
+
+**Rationale**: Sessions are the fundamental unit of meaningful work in the system (events → SessionManager.groupEvents → Session[]). A session like 9:45–10:30 represents 45 minutes of continuous work. Splitting proportionally (15min to 09:00 slot, 30min to 10:00 slot) preserves duration accuracy — the sum across slots equals the original duration. Assigning edits to the start slot avoids fractional edit counts and matches the intuition that "I was editing X at 9:45."
+
+**Alternatives considered**:
+- **Assign entire session to dominant slot**: Simpler, but a 55-minute session from 9:05–10:00 would all go to 09:00, misrepresenting the 10:00 hour entirely. Rejected.
+- **Duplicate session into both slots**: Double-counts duration, inflating total active time. Rejected.
+- **Split edits proportionally too**: Creates fractional edits (2.7 edits), requires rounding, and the rounding errors across slots may not sum to the original count. Rejected for complexity.
+
+## R-002: Time-Bucketing Utility Design
+
+**Decision**: Create `bucketSessionsByTime(sessions, bucketSizeMs, range)` in `src/session/time-bucketing.ts`. Returns `Map<number, SessionFragment[]>` where key is bucket start timestamp.
+
+**Rationale**: The same bucketing logic handles both hourly (3600000ms) and daily (86400000ms) views. Using millisecond bucket size makes it generic. The function generates bucket boundaries from the range, then for each session either places it wholly in one bucket or splits it. The map key is the bucket start timestamp (e.g., 1710921600000 for "09:00 Mar 20").
+
+**Alternatives considered**:
+- **Bucket by formatted string key (e.g., "09:00")**: Loses timezone context and makes day-level bucketing awkward ("Mon" vs timestamp). Rejected.
+- **Return array of bucket objects**: Maps provide O(1) lookup and natural iteration in insertion order. Array alternative offers no advantage.
+- **Integrate bucketing into QueryService**: QueryService is a thin query layer over TimelineDb. Bucketing is a presentation concern, not a query concern. Keep separation of concerns.
+
+## R-003: Command Registration Pattern
+
+**Decision**: Register `log` in `src/wildcard.ts` following the exact same pattern as `show`. Export `cmdLog` from `src/commands/activity-log.ts` via the activity barrel (`src/commands/activity.ts`) and commands index (`src/commands/index.ts`).
+
+**Rationale**: Existing commands use Commander.js with `.command()`, `.description()`, `.argument()`, `.option()`, and `.action()`. The `show` command is the closest pattern match — same argument structure (`[period]`), same flags (`--device`), same data flow (`createActivityContext → parsePeriod → periodRange → qs.sessions`). Following this pattern exactly ensures consistency.
+
+**Alternatives considered**:
+- **Use a different CLI framework**: The project is already on Commander v14. No reason to introduce alternatives for one command.
+- **Register inside activity barrel**: Commander registration must happen in `wildcard.ts` where the program object lives. The barrel only exports the handler function.
+
+## R-004: Granularity Selection Logic
+
+**Decision**: Automatic granularity based on period — hourly for today/yesterday, daily for week. No `--granularity` flag.
+
+**Rationale**: Every calendar and time-tracking tool uses this convention. Users asking "what did I do today" want hourly resolution. Users asking "what did I do this week" want daily resolution. Adding a flag creates a choice that 99% of users never change, and the remaining 1% can use `--json` + jq for custom slicing.
+
+**Alternatives considered**:
+- **Always hourly**: Week view at hourly granularity produces up to 168 rows (7 days × 24 hours). Unreadable.
+- **User-selectable**: Adds flag complexity for minimal benefit. Can always add later if demand exists.
+
+## R-005: Reuse of Existing Infrastructure
+
+**Decision**: Reuse `createActivityContext`, `parseDeviceFilter`, `parsePeriod`, `periodRange`, `periodLabel`, `groupSessionsByProject`, `printAppUsage`, `printEmptyActivity`, and `fmtDurationMs` as-is. No modifications to existing code needed for P1.
+
+**Rationale**: Reading the source confirms these functions are already well-factored:
+- `createActivityContext()` handles config→db→session-manager→query-service setup and teardown.
+- `parseDeviceFilter()` parses comma-separated device IDs with dedup and sort.
+- `parsePeriod()` / `periodRange()` / `periodLabel()` handle all three periods.
+- `groupSessionsByProject()` groups sessions and computes totals (duration, edits, files, branches).
+- `printAppUsage()` / `printEmptyActivity()` handle the footer and empty state.
+
+The only new logic is: (1) time-bucketing, (2) rendering the time-slot view.
+
+**Alternatives considered**:
+- **Extract `fetchActivityData()` helper from `activity-common.ts`**: The spec mentions this, but reading `activity-show.ts` shows the data-fetching is only 3 lines (parsePeriod, periodRange, qs.sessions). Extracting a helper for 3 lines is premature abstraction. The log command can call the same 3 lines directly.
+
+## R-006: JSON Output Structure
+
+**Decision**: JSON output mirrors the visual structure — a top-level object with `period`, `summary`, and `slots` array. Each slot has `start`, `end`, `label`, and `projects` array. Each project has `name`, `branch`, `duration_ms`, `edit_count`, `file_count`.
+
+**Rationale**: Following the `status --json` precedent. The structure should enable `jq '.slots[] | .projects[]'` style queries. Using milliseconds for duration (matching internal representation) avoids formatting ambiguity.
+
+**Alternatives considered**:
+- **Flat array of project-per-slot entries**: Loses the grouping structure that makes the output useful. Rejected.
+- **Formatted duration strings in JSON**: JSON consumers need numbers, not "48m". Keep durations as milliseconds.
diff --git a/specs/001-log-command/spec.md b/specs/001-log-command/spec.md
new file mode 100644
index 0000000..cd091b3
--- /dev/null
+++ b/specs/001-log-command/spec.md
@@ -0,0 +1,139 @@
+# Feature Specification: Log Command
+
+**Feature Branch**: `001-log-command`
+**Created**: 2026-03-20
+**Status**: Draft
+**Input**: User description: "Chronological activity log command showing hour-by-hour breakdown of what was done today"
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Today's Hourly Activity Log (Priority: P1)
+
+As a user, I want to run `wildcard log` and see today's activity broken down into hourly time slots, so I can answer "what was I doing at 2pm?" Each slot shows the projects worked on, their active duration, and edit counts.
+
+Example output:
+```
+Today (Mar 20, 2026)  ·  3 projects  ·  4h12m active
+
+  09:00–10:00  wildcard (main)                 48m   12 edits
+  10:00–11:00  wildcard (main)                 35m    8 edits
+               client-portal (feature/auth)    18m    3 edits
+  13:00–14:00  client-portal (feature/auth)    52m   14 edits
+```
+
+**Why this priority**: This is the core value proposition — a chronological view that no existing command provides. Without this, the feature has no reason to exist.
+
+**Independent Test**: Run `wildcard log` with activity data present. Verify output shows hourly slots from first to last active hour, each listing projects with duration and edit counts. Verify empty hours are skipped. Verify a summary header appears with total project count and active time.
+
+**Acceptance Scenarios**:
+
+1. **Given** today has recorded activity in multiple hours, **When** I run `wildcard log`, **Then** I see hourly time slots from first active hour to last, each listing projects ordered by duration descending, with active duration and edit count per project.
+2. **Given** today has no recorded activity, **When** I run `wildcard log`, **Then** I see a friendly empty-state message (consistent with existing empty-activity behavior).
+3. **Given** a session spans an hour boundary (e.g., 9:45–10:30), **When** I run `wildcard log`, **Then** the session's duration is split proportionally across both hours, and edits are assigned to the slot where the session started.
+4. **Given** multiple projects have activity in the same hour, **When** I run `wildcard log`, **Then** projects within that slot are ordered by duration descending.
+5. **Given** there are gaps with no activity (e.g., 10:00–13:00), **When** I run `wildcard log`, **Then** the empty hours are omitted entirely — the view jumps from 10:00–11:00 to 13:00–14:00.
+
+---
+
+### User Story 2 - Period Arguments and Device Filtering (Priority: P2)
+
+As a user, I want to run `wildcard log yesterday` or `wildcard log --week` to see activity for other time periods. Yesterday shows hourly slots (same as today). Week shows day-level slots. I can also filter by device with `--device`.
+
+Example week output:
+```
+This Week
+
+  Mon, Mar 16   wildcard (main)                2h15m   34 edits
+                client-portal (feature/auth)   1h02m   18 edits
+  Tue, Mar 17   wildcard (main)                3h41m   52 edits
+  Fri, Mar 20   wildcard (main)                1h22m   19 edits
+```
+
+**Why this priority**: Period arguments and device filtering extend the command's utility beyond "right now" while reusing infrastructure already built for P1 and existing in other commands.
+
+**Independent Test**: Run `wildcard log yesterday` — verify hourly slots for yesterday's date. Run `wildcard log --week` — verify day-level slots for the current week. Run `wildcard log --device <name>` — verify only activity from that device appears.
+
+**Acceptance Scenarios**:
+
+1. **Given** yesterday has recorded activity, **When** I run `wildcard log yesterday`, **Then** I see hourly time slots for yesterday's date with the same formatting as today.
+2. **Given** this week has activity on multiple days, **When** I run `wildcard log --week`, **Then** I see day-level slots showing each active day with projects, durations, and edit counts. Empty days are skipped.
+3. **Given** I have activity from multiple devices, **When** I run `wildcard log --device laptop`, **Then** only activity from the "laptop" device is included.
+4. **Given** it is Wednesday, **When** I run `wildcard log --week`, **Then** only Mon–Wed are eligible for display (future days are not shown).
+
+---
+
+### User Story 3 - JSON Output (Priority: P3)
+
+As a user or script author, I want to run `wildcard log --json` and get structured JSON output that represents the same data as the human-readable view, enabling composability with jq and other tools.
+
+**Why this priority**: Machine-readable output is near-zero marginal cost given the data is already structured internally. Establishes composability from day one, consistent with existing `status --json` pattern.
+
+**Independent Test**: Run `wildcard log --json` and pipe to `jq`. Verify the output is valid JSON, contains the same time slots and project data as the human-readable view, and includes all numeric fields (duration, edit count, file count).
+
+**Acceptance Scenarios**:
+
+1. **Given** today has activity, **When** I run `wildcard log --json`, **Then** I receive valid JSON with a structure containing period metadata, summary, and an array of time slots, each containing an array of project entries with duration, edit count, and file count.
+2. **Given** I run `wildcard log --json --week`, **When** I pipe the output to `jq`, **Then** I can extract and filter data programmatically.
+
+---
+
+### Edge Cases
+
+- **Session spanning hour boundary**: A session from 9:45–10:30 is split proportionally — 15 minutes to the 09:00 slot, 30 minutes to the 10:00 slot. Edits are assigned to the slot where the session started (09:00).
+- **Multiple projects in one hour**: Projects are ordered by duration descending within each time slot.
+- **Late-night work**: Activity at 2am shows a 02:00 slot — the view starts at whatever the first active hour is.
+- **Week view mid-week**: Running on Wednesday shows only Mon–Wed; Thu–Sun are not displayed.
+- **Cross-midnight session**: Clipped to the requested day's range by existing query infrastructure; only the portion within the requested day appears.
+- **No activity**: Handled via existing empty-activity messaging for a consistent empty-state.
+- **Single session shorter than a minute**: Still displayed in its time slot with duration shown consistently with existing formatting conventions.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST display activity in 1-hour time slots when viewing today or yesterday
+- **FR-002**: System MUST display activity in day-level time slots when viewing a week
+- **FR-003**: Within each time slot, system MUST list projects ordered by duration descending
+- **FR-004**: System MUST show active duration, edit count, and file count per project per time slot
+- **FR-005**: System MUST skip empty hours/days entirely (no placeholder or "no activity" rows)
+- **FR-006**: System MUST start display at first active time slot and end at last active time slot
+- **FR-007**: System MUST split sessions spanning time boundaries proportionally; edits are assigned to the slot where the session started
+- **FR-008**: System MUST support `--device` filter consistent with existing commands
+- **FR-009**: System MUST support `--json` flag for structured machine-readable output
+- **FR-010**: System MUST show a summary header with date/period label, total project count, and total active time
+- **FR-011**: System MUST show an app usage summary section (matching the pattern established by `show`)
+- **FR-012**: System MUST handle no-activity case using the existing empty-activity pattern
+- **FR-013**: `log` MUST be a top-level command (not a flag on `show` or other existing command)
+
+### Key Entities
+
+- **Time Slot**: A fixed-duration bucket (1 hour or 1 day) that aggregates session data for display. Contains a start time, end time, and a list of project entries.
+- **Project Entry**: A row within a time slot representing one project's contribution. Contains project name, branch, active duration, edit count, and file count.
+- **Session Split**: The result of dividing a session that crosses a time boundary into proportional segments, preserving total duration accuracy.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: Running `wildcard log` produces a time-ordered view within 1 second for a typical day's activity
+- **SC-002**: Session duration is accurately preserved — the sum of split durations across slots equals the original session duration (no double-counting, no loss)
+- **SC-003**: All period arguments (`yesterday`, `--week`) produce correctly scoped output with appropriate granularity (hourly vs. daily)
+- **SC-004**: `wildcard log --json` produces valid JSON that can be parsed by standard tools (jq)
+- **SC-005**: The command integrates naturally with existing CLI patterns — help text, error messages, and flags are consistent with `show`, `status`, and `report`
+
+### Critical Files
+
+These existing files are relevant to the implementation:
+
+- `src/wildcard.ts` — command registration
+- `src/commands/activity-show.ts` — reference pattern for activity commands
+- `src/commands/activity-common.ts` — reusable context and data-fetching helpers
+- `src/commands/period.ts` — period parsing and range calculation
+- `src/commands/formatters.ts` — shared formatting utilities
+- `src/session/query-service.ts` — session querying
+- `src/summary/summary-builder.ts` — project grouping
+
+New files anticipated:
+
+- `src/session/time-bucketing.ts` — reusable time-bucketing utility
+- `src/commands/activity-log.ts` — log command implementation

From e19ded9c8f2d93de6bab4370ac44c05cd36a9088 Mon Sep 17 00:00:00 2001
From: Andy Pai <andy@r2pi.co>
Date: Fri, 20 Mar 2026 18:41:47 -0400
Subject: [PATCH 7/9] chore: upgrade ai sdk dependencies

---
 bun.lock     | 22 +++++++++++-----------
 package.json |  8 ++++----
 2 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/bun.lock b/bun.lock
index 22c883a..23ccc49 100644
--- a/bun.lock
+++ b/bun.lock
@@ -5,11 +5,11 @@
     "": {
       "name": "wildcard",
       "dependencies": {
-        "@ai-sdk/google": "^3.0.30",
-        "@ai-sdk/openai": "^3.0.30",
+        "@ai-sdk/google": "^3.0.52",
+        "@ai-sdk/openai": "^3.0.47",
         "@clack/prompts": "^0.7.0",
-        "ai": "^6.0.97",
-        "ai-sdk-ollama": "^3.7.1",
+        "ai": "^6.0.134",
+        "ai-sdk-ollama": "^3.8.1",
         "commander": "^14.0.3",
         "picomatch": "^4.0.2",
         "yaml": "^2.8.1",
@@ -29,15 +29,15 @@
     },
   },
   "packages": {
-    "@ai-sdk/gateway": ["@ai-sdk/gateway@3.0.53", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.15", "@vercel/oidc": "3.1.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-QT3FEoNARMRlk8JJVR7L98exiK9C8AGfrEJVbRxBT1yIXKs/N19o/+PsjTRVsARgDJNcy9JbJp1FspKucEat0Q=="],
+    "@ai-sdk/gateway": ["@ai-sdk/gateway@3.0.77", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.21", "@vercel/oidc": "3.1.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-UdwIG2H2YMuntJQ5L+EmED5XiwnlvDT3HOmKfVFxR4Nq/RSLFA/HcchhwfNXHZ5UJjyuL2VO0huLbWSZ9ijemQ=="],
 
-    "@ai-sdk/google": ["@ai-sdk/google@3.0.30", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.15" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-ZzG6dU0XUSSXbxQJJTQUFpWeKkfzdpR7IykEZwaiaW5d+3u3RZ/zkRiGwAOcUpLp6k0eMd+IJF4looJv21ecxw=="],
+    "@ai-sdk/google": ["@ai-sdk/google@3.0.52", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.21" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-HiFB4VlHnv55k9xIbgQW9tHw5OsLXzbAghnDUqrnk/S94QpQuyrDwLSDsk/tUkxJeT00B+wvhL1y6/SARdLeXw=="],
 
-    "@ai-sdk/openai": ["@ai-sdk/openai@3.0.30", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.15" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-YDht3t7TDyWKP+JYZp20VuYqSjyF2brHYh47GGFDUPf2wZiqNQ263ecL+quar2bP3GZ3BeQA8f0m2B7UwLPR+g=="],
+    "@ai-sdk/openai": ["@ai-sdk/openai@3.0.47", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.21" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-bRsb2sDN5u+pKO3Kdr0flpxtL+cPwQ2uCo/pVyzIbj2I4AkKAokJHhw5JWLVOeEwdlYzWfmv+hzaiGarzUcTFQ=="],
 
     "@ai-sdk/provider": ["@ai-sdk/provider@3.0.8", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-oGMAgGoQdBXbZqNG0Ze56CHjDZ1IDYOwGYxYjO5KLSlz5HiNQ9udIXsPZ61VWaHGZ5XW/jyjmr6t2xz2jGVwbQ=="],
 
-    "@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.15", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.6" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-8XiKWbemmCbvNN0CLR9u3PQiet4gtEVIrX4zzLxnCj06AwsEDJwJVBbKrEI4t6qE8XRSIvU2irka0dcpziKW6w=="],
+    "@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.21", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.6" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-MtFUYI1/8mgDvRmaBDjbLJPFFrMG777AvSgyIFQtZHIMzm88R/12vYBBpnk7pfiWLFE1DSZzY4WDYzGbKAcmiw=="],
 
     "@clack/core": ["@clack/core@0.3.5", "", { "dependencies": { "picocolors": "^1.0.0", "sisteransi": "^1.0.5" } }, "sha512-5cfhQNH+1VQ2xLQlmzXMqUoiaH0lRBq9/CLW9lTyMbuKLC3+xEK01tHVvyut++mLOn5urSHmkm6I0Lg9MaJSTQ=="],
 
@@ -109,9 +109,9 @@
 
     "acorn-jsx": ["acorn-jsx@5.3.2", "", { "peerDependencies": { "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ=="],
 
-    "ai": ["ai@6.0.97", "", { "dependencies": { "@ai-sdk/gateway": "3.0.53", "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.15", "@opentelemetry/api": "1.9.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-eZIAcBymwGhBwncRH/v9pillZNMeRCDkc4BwcvwXerXd7sxjVxRis3ZNCNCpP02pVH4NLs81ljm4cElC4vbNcQ=="],
+    "ai": ["ai@6.0.134", "", { "dependencies": { "@ai-sdk/gateway": "3.0.77", "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.21", "@opentelemetry/api": "1.9.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-YalNEaavld/kE444gOcsMKXdVVRGEe0SK77fAFcWYcqLg+a7xKnEet8bdfrEAJTfnMjj01rhgrIL10903w1a5Q=="],
 
-    "ai-sdk-ollama": ["ai-sdk-ollama@3.7.1", "", { "dependencies": { "@ai-sdk/provider": "^3.0.8", "@ai-sdk/provider-utils": "^4.0.15", "jsonrepair": "^3.13.2", "ollama": "^0.6.3" }, "peerDependencies": { "ai": "^6.0.89" } }, "sha512-2G7lYQsojnCjqnNEcVHErus2CFDuEkns8+NtIe9a0+cOVJw1ioMCusRFjknVEGRs4HrtJSNV2qk5pq+6tPAvTQ=="],
+    "ai-sdk-ollama": ["ai-sdk-ollama@3.8.1", "", { "dependencies": { "@ai-sdk/provider": "^3.0.8", "@ai-sdk/provider-utils": "^4.0.19", "jsonrepair": "^3.13.3", "ollama": "^0.6.3" }, "peerDependencies": { "ai": "^6.0.116" } }, "sha512-DeNG88t3Knsu0AFNU8qe20tp82W+9yczgjduSltIEFWvo2mKuR3MeUNjg5/iGz2IBOkYKnni8pDoI19OxOCN/Q=="],
 
     "ajv": ["ajv@6.12.6", "", { "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", "json-schema-traverse": "^0.4.1", "uri-js": "^4.2.2" } }, "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g=="],
 
@@ -209,7 +209,7 @@
 
     "json-stable-stringify-without-jsonify": ["json-stable-stringify-without-jsonify@1.0.1", "", {}, "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw=="],
 
-    "jsonrepair": ["jsonrepair@3.13.2", "", { "bin": { "jsonrepair": "bin/cli.js" } }, "sha512-Leuly0nbM4R+S5SVJk3VHfw1oxnlEK9KygdZvfUtEtTawNDyzB4qa1xWTmFt1aeoA7sXZkVTRuIixJ8bAvqVUg=="],
+    "jsonrepair": ["jsonrepair@3.13.3", "", { "bin": { "jsonrepair": "bin/cli.js" } }, "sha512-BTznj0owIt2CBAH/LTo7+1I5pMvl1e1033LRl/HUowlZmJOIhzC0zbX5bxMngLkfT4WnzPP26QnW5wMr2g9tsQ=="],
 
     "keyv": ["keyv@4.5.4", "", { "dependencies": { "json-buffer": "3.0.1" } }, "sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw=="],
 
diff --git a/package.json b/package.json
index 7f84415..1475847 100644
--- a/package.json
+++ b/package.json
@@ -41,11 +41,11 @@
     "bun": "1.3.8"
   },
   "dependencies": {
-    "@ai-sdk/google": "^3.0.30",
-    "@ai-sdk/openai": "^3.0.30",
+    "@ai-sdk/google": "^3.0.52",
+    "@ai-sdk/openai": "^3.0.47",
     "@clack/prompts": "^0.7.0",
-    "ai": "^6.0.97",
-    "ai-sdk-ollama": "^3.7.1",
+    "ai": "^6.0.134",
+    "ai-sdk-ollama": "^3.8.1",
     "commander": "^14.0.3",
     "picomatch": "^4.0.2",
     "yaml": "^2.8.1"

From b7eb06f07f19eedddcbdfe7f170ab7e6d3e60d69 Mon Sep 17 00:00:00 2001
From: Andy Pai <andy@r2pi.co>
Date: Fri, 20 Mar 2026 18:41:54 -0400
Subject: [PATCH 8/9] chore: finalize validation metadata

---
 .agents/LEARNINGS.md             |  5 +++++
 .specify/memory/constitution.md  | 37 ++++++++++++++++++++++++++++++++
 scratch/03-fsevents-overflow.ts  |  4 ++--
 specs/001-log-command/plan.md    | 14 +++++++++---
 src/capture/file-watcher.test.ts |  2 ++
 5 files changed, 57 insertions(+), 5 deletions(-)
 create mode 100644 .specify/memory/constitution.md

diff --git a/.agents/LEARNINGS.md b/.agents/LEARNINGS.md
index 4cfa982..af4a3bf 100644
--- a/.agents/LEARNINGS.md
+++ b/.agents/LEARNINGS.md
@@ -10,6 +10,7 @@
 
 ## Patterns That Work
 
+- For any new project-grouping logic, mirror `summary-builder`'s key derivation: use `context.root ?? context.name ?? 'unknown'`, not just `context.root`, or app/non-root sessions will collapse incorrectly.
 - For branch PR workflow, `gh pr list --head <branch>` quickly confirms whether a PR already exists before running `gh pr create --base main --head <branch> --fill`.
 - Use `summarize_report_with_meta`; `summarize_day_with_meta` is legacy.
 - Import `fmt_duration_ms` from `src/utils/format.ts` (avoid local copies with divergent behavior).
@@ -38,10 +39,13 @@
 - When refreshing docs/tutorials, treat `src/wildcard.ts` and `ARCHITECTURE.md` as source of truth first; old `apps/*`, `packages/*`, and Screenpipe references can linger after architecture consolidation.
 - During snake_case -> kebab-case migrations, sweep architecture/docs tables and diagrams for stale underscore filenames to keep docs executable.
 - For report-style commands with human output on `stdout`, send progress/status lines to `stderr` to keep markdown/JSON pipe-safe.
+- For table-like CLI output with variable project/branch labels, compute the label column width from the current rows instead of hard-coding `padEnd(...)`; fixed widths break quickly on long branch names.
 - AI provider env var fallbacks should be provider-specific: only use `OPENAI_API_KEY` when provider is `openai`, not `ollama`.
 - For architecture-probe workflows, prefer creating `scratch/` scripts that favor read-only real module imports and print resolved module/config boundaries before performing any writes.
 - `ConfigStore` + `wildcard` CLI outputs show that command behavior is mostly orchestrator-based and storage-driven; this helps in architecture mapping.
 - `SyncEngine.syncOnce()` behavior is visible with a temp local `/bulk-upload/v1` server, but empty app_usage streams can leave corresponding cursor keys unset until data arrives.
+- For time-bucketing utilities, anchor bucket boundaries to the requested range start instead of epoch multiples so local day/week labels do not drift in non-UTC timezones.
+- For prompt readability in summary/report flows, keep stable system instructions in feature-local markdown files (`src/summary/prompts/*.md`) and keep dynamic session/project payload assembly in code.
 
 ## Patterns That Don't Work
 
@@ -75,3 +79,4 @@
 - 2026-02-23: Ignore pattern updates should be mirrored in both `src/config/config-store.ts` (default config ignores) and `src/capture/ignore-patterns.ts` (defensive fallback) to keep watch filtering consistent when config is unavailable.
 - 2026-02-24: In `SKILL.md` report guidance, require a two-pass "timeline + project enrichment" workflow: run `show/report`, then inspect top projects' README/manifests and changed high-signal files to produce impact-oriented summaries with confidence and explicit unknowns.
 - 2026-03-03: For `scratch/` architecture probes, combine source parsing with real `wildcard --help`/`status --json` execution; parser-only command-dispatch checks can miss multiline `.action(...)` wiring.
+- 2026-03-20: When refreshing Wildcard docs, verify `README.md`, `docs/ARCHITECTURE.md`, and `SKILL.md` against `src/wildcard.ts`, `src/config/config-store.ts`, and `src/server/bulk-upload-server.ts`; command flags, config defaults, and ingest routes drift independently.
diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md
new file mode 100644
index 0000000..c2ba454
--- /dev/null
+++ b/.specify/memory/constitution.md
@@ -0,0 +1,37 @@
+# Wildcard Constitution
+
+## Core Principles
+
+### I. Local-First, Minimal Permissions
+Wildcard must stay local-first. Core capture, search, sessionization, and reporting flows must work without network dependencies, and new features must preserve the project's lightweight, minimal-permission posture by default.
+
+### II. CLI-First, Pipe-Safe Interfaces
+Every user-facing workflow must be operable from the CLI. Human-readable output goes to `stdout`, progress and diagnostics go to `stderr`, and machine-readable modes must remain stable enough for automation.
+
+### III. Small, Typed Changes
+Changes should follow the existing Bun + TypeScript patterns: strict typing, focused modules, 2-space indentation, single quotes, and small helpers over sprawling abstractions. Prefer extending current command/session/storage flows before introducing new layers.
+
+### IV. Validation Before Commit
+Behavior changes must be backed by the smallest validation that proves them safe: focused tests for new logic, full `bun test` and `bun run check` before marking cross-cutting work complete, and CLI smoke checks for user-facing commands.
+
+### V. Honest Specs and Docs
+Specs, task lists, README/tutorial content, and architecture docs must reflect the code that actually ships. Tasks may only be marked done after the corresponding implementation and validation have really happened.
+
+## Additional Constraints
+
+- Runtime stack is Bun + TypeScript with SQLite-backed local storage.
+- Core features must not assume cloud connectivity or AI availability.
+- Existing command semantics and config defaults should be preserved unless a change is explicitly intentional and documented.
+
+## Development Workflow
+
+- Start from a spec or a clear implementation goal, then keep commits atomic and independently reversible.
+- Reuse existing modules and patterns before adding new files or abstractions.
+- For user-facing changes, update the relevant docs in the same unit of work.
+- Treat project-memory notes in `.agents/LEARNINGS.md` as helpful local context, not a substitute for repo docs or tests.
+
+## Governance
+
+This constitution governs new plans, reviews, and implementation work in this repository. Any exception must be called out explicitly in the relevant plan or commit, along with why the deviation is necessary.
+
+**Version**: 1.0.0 | **Ratified**: 2026-03-20 | **Last Amended**: 2026-03-20
diff --git a/scratch/03-fsevents-overflow.ts b/scratch/03-fsevents-overflow.ts
index 380093f..9420d5d 100644
--- a/scratch/03-fsevents-overflow.ts
+++ b/scratch/03-fsevents-overflow.ts
@@ -116,7 +116,7 @@ class OverflowSimulator {
     this.backfillRunning = true
     this.emit(`drainOverflow()`)
     this.emit(`  → snapshot: roots=[${roots.join(',')}]`)
-    this.emit(`  → backfill window: checkpointTs to now`)
+    this.emit(`  → backfill window: ${sinceTs - this.startTs}ms to ${untilTs - this.startTs}ms`)
     this.emit(`  → backfillRunning = true`)
 
     // Simulate backfill duration
@@ -153,7 +153,7 @@ class OverflowSimulator {
   ): Promise<void> {
     sub(name)
     this.overflowRoots.clear()
-    this.overflowTimer && clearTimeout(this.overflowTimer)
+    if (this.overflowTimer) clearTimeout(this.overflowTimer)
     this.overflowTimer = null
     this.overflowSinceTs = null
     this.backfillRunning = false
diff --git a/specs/001-log-command/plan.md b/specs/001-log-command/plan.md
index 28cbaa7..f637c7f 100644
--- a/specs/001-log-command/plan.md
+++ b/specs/001-log-command/plan.md
@@ -23,9 +23,17 @@ Add a `wildcard log` command that provides a chronological, time-slot-based view
 
 *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
 
-The project constitution is a blank template (no principles have been ratified). **No gates to evaluate.** Proceeding without constraints.
+The project constitution now defines five active gates:
 
-**Post-Phase 1 re-check**: Still no constitution gates. Design is consistent with existing codebase patterns (verified by code review of `activity-show.ts`, `activity-common.ts`, `formatters.ts`, and `period.ts`).
+1. Local-first, minimal-permission behavior
+2. CLI-first, pipe-safe interfaces
+3. Small, typed changes that extend existing patterns
+4. Validation before commit
+5. Honest specs and docs
+
+**Initial check**: Pass. The feature is local-only, adds a CLI command on top of existing session/query infrastructure, and does not introduce new permissions, storage, or network requirements.
+
+**Post-Phase 1 re-check**: Pass. The design reuses `activity-*` command helpers, session querying, and app-usage rendering rather than adding parallel architecture.
 
 ## Project Structure
 
@@ -72,7 +80,7 @@ src/
 
 ## Complexity Tracking
 
-No constitution violations. No complexity justifications needed.
+No constitution violations. Validation gates are satisfied with `bun test`, `bun run check`, and CLI smoke tests for `wildcard log`.
 
 The feature adds:
 - 1 pure utility function (time-bucketing)
diff --git a/src/capture/file-watcher.test.ts b/src/capture/file-watcher.test.ts
index c17c950..bba5e9c 100644
--- a/src/capture/file-watcher.test.ts
+++ b/src/capture/file-watcher.test.ts
@@ -38,6 +38,8 @@ class MockPlatformWatcher extends EventEmitter implements PlatformWatcher {
       this.backfillShouldFail = false
       throw new Error('backfill I/O error')
     }
+
+    yield* []
   }
 
   resolveBackfill() {

From 335b63a95563c371d581a1f5e9512d1f677b180e Mon Sep 17 00:00:00 2001
From: Andy Pai <andy@r2pi.co>
Date: Sat, 21 Mar 2026 00:09:07 -0400
Subject: [PATCH 9/9] docs: add performance optimization TODOs

---
 TODO.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 TODO.md

diff --git a/TODO.md b/TODO.md
new file mode 100644
index 0000000..2f30c9d
--- /dev/null
+++ b/TODO.md
@@ -0,0 +1,33 @@
+# TODO
+
+## Performance optimizations
+
+### High priority
+
+- **Metadata skip before `readFile`** (`src/session/change-tracker.ts`)
+  Check `fs.stat` for mtime + size before calling `fs.readFile`. If both match a
+  cached value for the path, skip the read entirely. Biggest win for save storms
+  where an editor writes the same content repeatedly.
+
+- **In-memory file hash cache** (`src/session/change-tracker.ts`)
+  Keep a `Map<path, { mtime, size, hash }>` in `ChangeTracker`. On each edit
+  event, check the cache before hitting the DB (`getFileHash`) or reading the
+  file. Invalidate on any real content change. Eliminates both the DB round-trip
+  and the `readFile` for paths that provably haven't changed.
+
+- **Memoize `context_provider.resolve()`** (`src/capture/file-normalizer.ts`)
+  `resolve()` is called per file event (line 28). Cache results keyed by
+  directory with a short TTL (e.g. 5 s). Git root / branch lookups inside the
+  resolver are the likely cost; they rarely change within a session.
+
+### Medium priority
+
+- **Batch / cache DB writes** (`src/session/change-tracker.ts`)
+  `getFileHash` / `setFileHash` / `deleteFileState` run synchronously per event.
+  Under high event volume, maintain a write-through in-memory cache and flush to
+  SQLite periodically rather than on every event.
+
+- **Defer blob writes off the hot path** (`src/session/change-tracker.ts`)
+  Blob storage writes (lines 76–77) add disk I/O inline with event processing.
+  Consider queuing them into a background microtask or limiting capture to
+  specific event kinds / smaller size thresholds.