From 8f0ba43728dc52f5e7dc04d6de19bc21dbc26fc4 Mon Sep 17 00:00:00 2001
From: OpenClaw Bot <openclaw-bot@friborg.uk>
Date: Wed, 6 May 2026 23:59:31 +0200
Subject: [PATCH] chore: seed BuildPulse v0.1 documentation package

---
 AGENTS.md                    |  82 +++++++++
 CLAUDE.md                    | 132 ++++++++++++++
 README.md                    |  95 ++++++++++
 docs/AI_DEVELOPER_HANDOFF.md | 324 +++++++++++++++++++++++++++++++++++
 docs/ARCHITECTURE.md         | 211 +++++++++++++++++++++++
 docs/DATA_SCHEMA.md          | 226 ++++++++++++++++++++++++
 docs/DECISIONS.md            | 127 ++++++++++++++
 docs/EXPORT_FORMATS.md       | 158 +++++++++++++++++
 docs/PARKING_LOT.md          | 222 ++++++++++++++++++++++++
 docs/PRODUCT_BRIEF.md        | 100 +++++++++++
 docs/ROADMAP.md              | 135 +++++++++++++++
 docs/SCOPE.md                | 171 ++++++++++++++++++
 docs/TEST_PLAN.md            | 233 +++++++++++++++++++++++++
 docs/UI_SPEC.md              | 211 +++++++++++++++++++++++
 14 files changed, 2427 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md
 create mode 100644 README.md
 create mode 100644 docs/AI_DEVELOPER_HANDOFF.md
 create mode 100644 docs/ARCHITECTURE.md
 create mode 100644 docs/DATA_SCHEMA.md
 create mode 100644 docs/DECISIONS.md
 create mode 100644 docs/EXPORT_FORMATS.md
 create mode 100644 docs/PARKING_LOT.md
 create mode 100644 docs/PRODUCT_BRIEF.md
 create mode 100644 docs/ROADMAP.md
 create mode 100644 docs/SCOPE.md
 create mode 100644 docs/TEST_PLAN.md
 create mode 100644 docs/UI_SPEC.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..d42cb09
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,82 @@
+# BuildPulse Agent Roles
+
+This file describes suggested AI agent roles for building and maintaining BuildPulse.
+Do not implement agent automation in v0.1. These roles are for human-orchestrated AI development.
+
+## 1. Builder Agent
+
+Primary responsibility:
+- Implement features from `docs/SCOPE.md`.
+
+Rules:
+- Must not add features outside v0.1 scope.
+- Must update or respect data schemas.
+- Must keep the app running.
+- Must provide test steps after implementation.
+
+Good tools:
+- Claude Code
+- Codex
+- OpenCode
+- OpenClaw/Hermes later
+
+## 2. Scope Guardian Agent
+
+Primary responsibility:
+- Review proposed changes for scope creep.
+
+Checks:
+- Is this required for v0.1?
+- Does it introduce phases, releases, AI triage, multi-project, or real agent integration?
+- Can this be parked?
+
+Output:
+- Required now
+- Useful later
+- Dangerous scope expansion
+- Reject
+
+## 3. QA Reviewer Agent
+
+Primary responsibility:
+- Review implemented behavior against `docs/TEST_PLAN.md`.
+
+Checks:
+- Main happy paths
+- Empty states
+- Import/export errors
+- Data persistence
+- Pulse event consistency
+- Mobile usability
+- Markdown output usefulness
+
+## 4. UX Simplifier Agent
+
+Primary responsibility:
+- Reduce clutter and make the UI easier to use.
+
+Checks:
+- Can the user understand what to do in 5 seconds?
+- Is the current feature obvious?
+- Is Parking Lot easy to access?
+- Is Pulse Log readable?
+- Does it avoid Jira-like complexity?
+
+## 5. Export Context Agent
+
+Primary responsibility:
+- Ensure exports are useful to coding agents.
+
+Checks:
+- Does `CLAUDE_CONTEXT.md` include the current project summary?
+- Does it list current features?
+- Does it list Now/Next/Later/Done?
+- Does it include Parking Lot?
+- Does it include recent Pulse events?
+- Is it concise enough for AI context?
+
+## Agent Collaboration Rule
+
+Only one agent should make code changes at a time in v0.1.
+Other agents may review, critique, or create suggestions.
+Avoid parallel coding until BuildPulse has stronger structure and tests.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..8d2dc0c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,132 @@
+# BuildPulse — AI Agent Instructions
+
+## Product Goal
+
+BuildPulse is an ADHD-safe planning cockpit for AI-assisted product development.
+It helps the user capture features, park distracting ideas, log progress as Pulse events, and export clean context for AI coding agents.
+
+## Current Release
+
+v0.1: Single-project, local-first, pulse-compatible feature cockpit.
+
+## Current v0.1 Scope
+
+Build only these core views:
+1. Feature Plan
+2. Parking Lot
+3. Pulse Log
+4. Export
+
+## Hard v0.1 Constraints
+
+Do not add:
+- Multiple projects
+- Phases
+- Releases
+- AI triage
+- LLM provider configuration
+- Local/cloud model routing
+- Real agent integration
+- WebSockets
+- Authentication
+- Database
+- GitHub/Gitea integration
+- OpenClaw integration
+- Multi-user support
+- Notification system
+- Advanced analytics
+- Mobile native app
+
+If a useful idea appears, add it to `docs/PARKING_LOT.md` or the app's Parking Lot data instead of implementing it.
+
+## Core Data Concepts
+
+BuildPulse v0.1 has:
+- One Project
+- Many Features
+- Many Parking Lot Items
+- Many Pulse Events
+
+Sessions are not a separate entity in v0.1.
+Sessions are represented using Pulse events with a shared `trace_id`.
+
+## Pulse Types
+
+Support at minimum:
+- INTENT
+- ACTION
+- RESULT
+- BLOCKER
+- DECISION
+- PARKED_IDEA
+- TEST_RESULT
+- SESSION_START
+- SESSION_END
+- REFLECTION
+
+## UX Principles
+
+The UI must be:
+- Calm
+- Minimal
+- Clear
+- Mobile-friendly
+- Not enterprise-heavy
+- Not Jira-like
+- Easy to understand quickly
+- Designed for one person building with AI help
+
+## Code Principles
+
+- Prefer simple, readable code.
+- Prefer boring architecture.
+- Keep the app working after every change.
+- Use clear names.
+- Add comments where helpful.
+- Keep state structure close to the documented data schema.
+- Validate required fields.
+- Handle empty states.
+- Handle import errors gracefully.
+- Keep export output human-readable.
+
+## Storage Rule
+
+Use local-first storage.
+Preferred v0.1 options:
+1. Browser local storage or IndexedDB for fastest implementation.
+2. Optional tiny file-backed Node backend only if explicitly requested.
+
+Do not introduce a database in v0.1.
+
+## Scope Guardrail
+
+When asked to add functionality, classify it first:
+1. Required for v0.1
+2. Useful later
+3. Dangerous scope expansion
+
+Only implement category 1 unless explicitly told otherwise.
+
+## End-of-Task Report
+
+After every coding task, report:
+- What changed
+- What files changed
+- How to run/test
+- What remains rough
+- What ideas were parked
+- Whether v0.1 definition of done is closer
+
+## Definition of Done for v0.1
+
+BuildPulse v0.1 is done when the user can:
+1. Edit the single project summary.
+2. Add/edit/delete/reorder feature cards.
+3. Place features in Now, Next, Later, or Done.
+4. Add/edit/delete Parking Lot items.
+5. Add manual Pulse events.
+6. Link Pulse events to features where relevant.
+7. View Pulse events chronologically.
+8. Export project data as JSON/JSONL.
+9. Export project context as Markdown.
+10. Use the exported context with Claude Code/Codex/OpenCode.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1ef4e73
--- /dev/null
+++ b/README.md
@@ -0,0 +1,95 @@
+# BuildPulse
+
+BuildPulse is a local-first planning cockpit for AI-assisted product building.
+It helps capture features, park distracting ideas, log progress as Pulse events, and export clean project context for AI coding agents such as Claude Code, Codex, OpenCode, OpenClaw, or future autonomous agents.
+
+## Core Idea
+
+BuildPulse v0.1 is intentionally small.
+
+It is not a full task manager.
+It is not Jira.
+It is not an autonomous agent framework yet.
+It is not a SaaS platform.
+
+It is a single-project, pulse-compatible feature cockpit.
+
+## v0.1 Purpose
+
+BuildPulse v0.1 should answer:
+- What are we building?
+- What features are active now?
+- What comes next?
+- What ideas are safely parked?
+- What has happened so far?
+- Can I export a clean context package for an AI developer/agent?
+
+## v0.1 Scope
+
+BuildPulse v0.1 includes:
+- Single active project
+- Feature Plan screen
+- Parking Lot screen
+- Pulse Log screen
+- Export screen
+- Local-first data storage
+- Pulse-shaped event records
+- Markdown and JSON/JSONL export
+
+## v0.1 Non-Goals
+
+BuildPulse v0.1 does not include:
+- Multiple projects
+- Phases
+- Releases
+- AI triage
+- Local/cloud model router
+- Real agent integration
+- WebSockets
+- Backend authentication
+- Database
+- GitHub/Gitea integration
+- OpenClaw integration
+- Multi-user collaboration
+
+Those belong in later versions.
+
+## Design Philosophy
+
+BuildPulse should feel:
+- Calm
+- Simple
+- Practical
+- Mobile-friendly
+- Low-clutter
+- Useful after a stressful day
+- Friendly to ADHD-style idea capture without allowing scope chaos
+
+## Key Concept: Pulse-Compatible, Not Pulse-Dependent
+
+BuildPulse v0.1 manually creates Pulse events.
+Later, autonomous agents may emit those same Pulse events automatically.
+This means the data shape should be future-compatible from day one.
+
+## Main Views
+
+1. Feature Plan
+2. Parking Lot
+3. Pulse Log
+4. Export
+
+## Intended First Use
+
+The first project tracked inside BuildPulse should be BuildPulse itself.
+After that, BuildPulse should be used to plan and manage projects such as:
+- Crimson Drive
+- FamilyCore
+- ConceptCatalyst
+- Local LLM experiments
+- OpenClaw/Hermes workflows
+
+## Development Priority
+
+Ship the smallest useful version first.
+Do not build the full Agent Pulse framework yet.
+Do not add AI automation until manual workflows are proven useful.
diff --git a/docs/AI_DEVELOPER_HANDOFF.md b/docs/AI_DEVELOPER_HANDOFF.md
new file mode 100644
index 0000000..9ed5a9a
--- /dev/null
+++ b/docs/AI_DEVELOPER_HANDOFF.md
@@ -0,0 +1,324 @@
+# AI Developer Handoff — BuildPulse v0.1
+
+## Mission
+
+Build a tiny local-first app called BuildPulse.
+BuildPulse v0.1 is a single-project planning cockpit for AI-assisted development.
+It must allow the user to:
+1. Manage a simple feature plan.
+2. Park distracting ideas.
+3. Manually log progress as Pulse events.
+4. Export clean project context for AI coding agents.
+
+## Do Not Overbuild
+
+This is not a full project management platform.
+This is not an autonomous agent system.
+This is not the full Agent Pulse framework.
+Build only the v0.1 scope.
+
+## Required Views
+
+### 1. Feature Plan
+
+Columns:
+- Now
+- Next
+- Later
+- Done
+
+Feature fields:
+- Title
+- Description
+- Column
+- Priority
+- Status
+- Acceptance criteria
+- Scope notes
+
+Required actions:
+- Add feature
+- Edit feature
+- Delete feature
+- Move feature between columns
+
+### 2. Parking Lot
+
+Parking item fields:
+- Title
+- Description
+- Reason parked
+- Possible future placement
+- Risk level
+
+Required actions:
+- Add item
+- Edit item
+- Delete item
+
+### 3. Pulse Log
+
+Pulse event fields:
+- Timestamp
+- Project ID
+- Feature ID, optional
+- Source
+- Agent ID
+- Pulse type
+- Message
+- Structured payload
+- Confidence score
+- Evidence refs
+- Trace ID, optional
+
+Pulse types:
+- INTENT
+- ACTION
+- RESULT
+- BLOCKER
+- DECISION
+- PARKED_IDEA
+- TEST_RESULT
+- SESSION_START
+- SESSION_END
+- REFLECTION
+
+Required actions:
+- Add pulse
+- View pulses chronologically
+- Link pulse to feature, optional
+
+### 4. Export
+
+Required exports:
+- Full JSON export
+- Pulse JSONL export
+- Markdown package export
+
+Markdown package:
+- `PROJECT_SUMMARY.md`
+- `FEATURE_PLAN.md`
+- `PARKING_LOT.md`
+- `PULSE_LOG.md`
+- `CLAUDE_CONTEXT.md`
+
+## Storage
+
+Use local-first browser persistence unless explicitly told otherwise.
+Preferred:
+- LocalStorage or IndexedDB
+
+Do not add:
+- Database
+- Auth
+- Backend
+
+## Initial Seed Data
+
+The app may seed itself with this project:
+
+Project name:
+BuildPulse
+
+One-line pitch:
+A local-first planning cockpit for AI-assisted product building.
+
+Current goal:
+Ship v0.1 with Feature Plan, Parking Lot, Pulse Log, and Export.
+
+Initial features:
+
+Now:
+- Feature Plan screen
+- Parking Lot screen
+- Pulse Log screen
+- Export screen
+
+Parking Lot:
+- AI idea triage
+- Phases and releases
+- Multi-project support
+- Local/cloud AI router
+- Real Agent Pulse ingestion
+- Git integration
+- OpenClaw/Hermes integration
+
+## UX Requirements
+
+The app should be:
+- Calm
+- Minimal
+- Mobile-friendly
+- Easy to use
+- Not Jira-like
+- Not cluttered
+
+Important quick actions:
+- Add feature
+- Park idea
+- Add pulse
+- Export context
+
+## v0.1 Definition of Done
+
+The app is done when:
+1. The user can edit the project summary.
+2. The user can create/edit/delete features.
+3. The user can move features between Now, Next, Later, Done.
+4. The user can add acceptance criteria to features.
+5. The user can create/edit/delete Parking Lot items.
+6. The user can manually add Pulse events.
+7. Pulse events can link to features.
+8. Pulse events display chronologically.
+9. Data persists after refresh.
+10. Full JSON export works.
+11. Pulse JSONL export works.
+12. Markdown context export works.
+13. `CLAUDE_CONTEXT.md` is useful for AI coding handoff.
+14. The app can manage its own BuildPulse development work.
+
+## Forbidden v0.1 Features
+
+Do not implement:
+- Multiple projects
+- Phases
+- Releases
+- AI triage
+- AI provider settings
+- Local/cloud router
+- Real agent event ingestion
+- OpenClaw integration
+- Claude Code integration
+- GitHub/Gitea integration
+- WebSockets
+- Database
+- Authentication
+- Multi-user support
+- Notifications
+- Advanced analytics
+
+If tempted, add the idea to Parking Lot instead.
+
+## Suggested Implementation Plan
+
+1. Create React/Vite app.
+2. Define TypeScript types matching `docs/DATA_SCHEMA.md`.
+3. Implement local storage.
+4. Implement project summary.
+5. Implement Feature Plan.
+6. Implement Parking Lot.
+7. Implement Pulse Log.
+8. Implement Export functions.
+9. Add seed data.
+10. Test manually using `docs/TEST_PLAN.md`.
+
+## Suggested Components
+
+```text
+AppShell
+Navigation
+ProjectSummary
+FeatureBoard
+FeatureCard
+FeatureEditor
+ParkingLotView
+ParkingLotItemCard
+ParkingLotItemEditor
+PulseLogView
+PulseEventForm
+PulseEventItem
+ExportView
+```
+
+## End-of-Task Report Required
+
+After implementation, report:
+- What was built
+- Files created/changed
+- How to run locally
+- How to test manually
+- Which v0.1 acceptance criteria are met
+- Which rough edges remain
+- Which ideas were parked
+
+---
+
+## One-shot prompt to give an AI developer/orchestrator
+
+Use this after creating the docs above.
+
+```text
+You are the AI developer/orchestrator for BuildPulse.
+Read these files before doing anything:
+- README.md
+- CLAUDE.md
+- AGENTS.md
+- docs/PRODUCT_BRIEF.md
+- docs/SCOPE.md
+- docs/ARCHITECTURE.md
+- docs/DATA_SCHEMA.md
+- docs/UI_SPEC.md
+- docs/TEST_PLAN.md
+- docs/DECISIONS.md
+- docs/PARKING_LOT.md
+- docs/EXPORT_FORMATS.md
+- docs/AI_DEVELOPER_HANDOFF.md
+
+Your task:
+Build BuildPulse v0.1 exactly as scoped.
+BuildPulse v0.1 is a local-first, single-project planning cockpit for AI-assisted development.
+
+Required v0.1 views:
+1. Feature Plan
+2. Parking Lot
+3. Pulse Log
+4. Export
+
+Required behavior:
+- One active project only
+- Feature cards in Now / Next / Later / Done
+- Parking Lot for distracting ideas
+- Manual Pulse Log with future-compatible Pulse event schema
+- Local persistence
+- JSON export/import
+- Pulse JSONL export
+- Markdown export including CLAUDE_CONTEXT.md
+
+Hard constraints:
+- Do not add multiple projects
+- Do not add phases
+- Do not add releases
+- Do not add AI triage
+- Do not add local/cloud router
+- Do not add real agent integration
+- Do not add backend auth
+- Do not add database
+- Do not add WebSockets
+- Do not add GitHub/OpenClaw/Hermes integration
+
+If you think of useful extra features, add them to Parking Lot or docs/PARKING_LOT.md. Do not implement them.
+
+Before coding:
+1. Summarize your understanding of v0.1.
+2. Propose the simplest architecture.
+3. List files/components you will create.
+4. Restate the v0.1 definition of done.
+
+Then implement.
+
+After coding:
+1. Run available checks.
+2. Provide exact run instructions.
+3. Provide manual test steps.
+4. List completed acceptance criteria.
+5. List rough edges.
+6. List parked ideas.
+```
+
+## The shortest version of the project direction
+
+BuildPulse v0.1 is a single-project, local-first feature cockpit with Parking Lot, manual Pulse Log, and AI-context export.
+It must help me see what I am building, what is active now, what is parked, what happened, and what to hand off to an AI coder next.
+Do not build the full Agent Pulse framework yet.
+
+This package is ready to hand to Claude Code, Codex, OpenCode, OpenClaw, Hermes, or another AI orchestrator.
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..b6bc5ce
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,211 @@
+# BuildPulse Architecture
+
+## Architecture Goal
+
+Keep v0.1 boring, local-first, and easy to understand.
+BuildPulse should be simple enough for AI coding agents to modify safely without losing context.
+
+## Recommended v0.1 Stack
+
+Preferred simple stack:
+- React
+- Vite
+- TypeScript if practical
+- LocalStorage or IndexedDB
+- Markdown/JSON export
+
+Optional if file-backed storage is explicitly wanted:
+- Tiny Node/Express backend
+- Files:
+  - `data/project.json`
+  - `data/features/*.json`
+  - `data/parking_lot/*.json`
+  - `data/pulses.jsonl`
+
+Do not add a database in v0.1.
+
+## Design Principle
+
+BuildPulse is pulse-compatible, not pulse-dependent.
+That means:
+- Pulse event shape exists from day one.
+- Events can be manual in v0.1.
+- Future agents can emit the same event shape later.
+- No full event bus is required in v0.1.
+
+## High-Level Modules
+
+### App Shell
+
+Responsible for:
+- Navigation
+- Layout
+- Active view
+- Global app state loading/saving
+
+Views:
+- Feature Plan
+- Parking Lot
+- Pulse Log
+- Export
+
+### Project Store
+
+Responsible for:
+- Single project data
+- Feature cards
+- Parking Lot items
+- Pulse events
+- Import/export
+
+### Feature Plan Module
+
+Responsible for:
+- Feature CRUD
+- Column movement
+- Feature detail editing
+- Acceptance criteria
+
+### Parking Lot Module
+
+Responsible for:
+- Parked idea CRUD
+- Reason parked
+- Future placement
+- Risk
+
+### Pulse Log Module
+
+Responsible for:
+- Manual Pulse event creation
+- Chronological event display
+- Feature-linked filtering
+- Trace ID grouping later
+
+### Export Module
+
+Responsible for:
+- Full JSON export/import
+- JSONL Pulse export
+- Markdown context export
+- `CLAUDE_CONTEXT.md` generation
+
+## Suggested Source Structure
+
+```text
+src/
+  main.tsx
+  App.tsx
+  components/
+    AppShell.tsx
+    Navigation.tsx
+    EmptyState.tsx
+    Modal.tsx
+    TextInput.tsx
+    TextArea.tsx
+    Select.tsx
+  features/
+    feature-plan/
+      FeatureBoard.tsx
+      FeatureCard.tsx
+      FeatureDetail.tsx
+      featureUtils.ts
+    parking-lot/
+      ParkingLotView.tsx
+      ParkingLotItemCard.tsx
+      ParkingLotItemDetail.tsx
+    pulse-log/
+      PulseLogView.tsx
+      PulseEventForm.tsx
+      PulseEventItem.tsx
+      pulseUtils.ts
+    export/
+      ExportView.tsx
+      exportMarkdown.ts
+      exportJson.ts
+    project/
+      ProjectSummary.tsx
+      projectDefaults.ts
+  store/
+    types.ts
+    appStore.ts
+    storage.ts
+    migrations.ts
+  utils/
+    ids.ts
+    dates.ts
+    validation.ts
+```
+
+## Storage Strategy
+
+### Fastest v0.1
+
+Use browser storage.
+- Store one serialized app state object.
+- Include a schema version.
+- Support export/import to avoid lock-in.
+
+Example key:
+
+```text
+buildpulse.appState.v1
+```
+
+### Future File-Backed Mode
+
+Later, the same data can be saved as:
+
+```text
+data/
+  project.json
+  features/
+  parking_lot/
+  pulses.jsonl
+```
+
+Do not build this unless explicitly requested for v0.1.
+
+## Migration Strategy
+
+Every stored state must include:
+
+```json
+{
+  "schema_version": "0.1.0"
+}
+```
+
+Add migrations later if needed.
+
+## Future Agent Pulse Compatibility
+
+v0.1 Pulse events should already include:
+- `id`
+- `timestamp`
+- `project_id`
+- `feature_id`
+- `source`
+- `agent_id`
+- `pulse_type`
+- `message`
+- `structured_payload`
+- `confidence_score`
+- `evidence_refs`
+- `trace_id`
+
+Even if many fields are optional or manually filled.
+
+## Explicit Non-Architecture
+
+Do not introduce:
+- Redux unless needed
+- Complex state machines
+- Backend services
+- Event buses
+- WebSockets
+- Plugins
+- Agent daemons
+- Multi-user permissions
+
+Keep it simple.
diff --git a/docs/DATA_SCHEMA.md b/docs/DATA_SCHEMA.md
new file mode 100644
index 0000000..25b166a
--- /dev/null
+++ b/docs/DATA_SCHEMA.md
@@ -0,0 +1,226 @@
+# BuildPulse Data Schema
+
+## Schema Version
+
+Current schema version:
+
+```text
+0.1.0
+```
+
+## App State
+
+```json
+{
+  "schema_version": "0.1.0",
+  "project": {},
+  "features": [],
+  "parking_lot": [],
+  "pulses": [],
+  "settings": {}
+}
+```
+
+## Project
+
+```json
+{
+  "id": "project_buildpulse",
+  "name": "BuildPulse",
+  "one_line_pitch": "A local-first planning cockpit for AI-assisted product building.",
+  "description": "BuildPulse helps capture features, park distracting ideas, log progress as Pulse events, and export clean context for AI coding agents.",
+  "current_goal": "Ship v0.1 with Feature Plan, Parking Lot, Pulse Log, and Export.",
+  "notes": "",
+  "created_at": "2026-05-06T00:00:00+02:00",
+  "updated_at": "2026-05-06T00:00:00+02:00"
+}
+```
+
+## Feature
+
+```json
+{
+  "id": "feature_plan_screen",
+  "title": "Feature Plan screen",
+  "description": "Create and manage feature cards in Now, Next, Later, and Done.",
+  "column": "now",
+  "priority": "must",
+  "status": "ready",
+  "acceptance_criteria": [
+    "User can create a feature card.",
+    "User can edit feature title and description.",
+    "User can move feature between columns."
+  ],
+  "scope_notes": "No phases or releases in v0.1.",
+  "created_at": "2026-05-06T00:00:00+02:00",
+  "updated_at": "2026-05-06T00:00:00+02:00"
+}
+```
+
+## Feature Columns
+
+Allowed column values:
+- `now`
+- `next`
+- `later`
+- `done`
+
+## Feature Priority
+
+Allowed priority values:
+- `must`
+- `should`
+- `could`
+- `later`
+
+## Feature Status
+
+Allowed status values:
+- `idea`
+- `shaping`
+- `ready`
+- `building`
+- `testing`
+- `done`
+- `parked`
+- `rejected`
+
+In v0.1, column is more important than status.
+
+## Parking Lot Item
+
+```json
+{
+  "id": "parked_ai_triage",
+  "title": "AI idea triage",
+  "description": "Use AI to classify new ideas into Now, Next, Later, Parking Lot, or Reject.",
+  "reason_parked": "Useful, but v0.1 must prove the manual workflow first.",
+  "possible_future_placement": "v0.2",
+  "risk_level": "medium",
+  "created_at": "2026-05-06T00:00:00+02:00",
+  "updated_at": "2026-05-06T00:00:00+02:00"
+}
+```
+
+## Parking Lot Risk Level
+
+Allowed `risk_level` values:
+- `low`
+- `medium`
+- `high`
+- `dangerous`
+
+## Pulse Event
+
+Pulse events are append-friendly and future-compatible with Agent Pulse.
+
+```json
+{
+  "id": "pulse_001",
+  "timestamp": "2026-05-06T00:00:00+02:00",
+  "project_id": "project_buildpulse",
+  "feature_id": "feature_plan_screen",
+  "source": "manual",
+  "agent_id": "jimmi",
+  "pulse_type": "INTENT",
+  "message": "Start implementing the Feature Plan screen.",
+  "structured_payload": {},
+  "confidence_score": 0.9,
+  "evidence_refs": [],
+  "trace_id": "session_001"
+}
+```
+
+## Pulse Types
+
+Allowed `pulse_type` values:
+- `INTENT`
+- `ACTION`
+- `RESULT`
+- `BLOCKER`
+- `DECISION`
+- `PARKED_IDEA`
+- `TEST_RESULT`
+- `SESSION_START`
+- `SESSION_END`
+- `REFLECTION`
+
+## Pulse Source
+
+Suggested `source` values:
+- `manual`
+- `user`
+- `claude_code`
+- `codex`
+- `opencode`
+- `openclaw`
+- `hermes`
+- `local_llm`
+- `system`
+
+v0.1 should not require strict enforcement beyond basic string handling.
+
+## Evidence Refs
+
+Evidence refs are references to outputs, tests, commits, screenshots, files, or notes.
+
+Simple v0.1 form:
+
+```json
+[
+  "Manual test passed",
+  "Exported CLAUDE_CONTEXT.md",
+  "Commit abc123"
+]
+```
+
+Later form may become:
+
+```json
+[
+  {
+    "type": "file",
+    "label": "FEATURE_PLAN.md",
+    "url": ""
+  }
+]
+```
+
+## Settings
+
+Minimal v0.1 settings:
+
+```json
+{
+  "theme": "light",
+  "default_agent_id": "jimmi"
+}
+```
+
+## Validation Rules
+
+Required project fields:
+- `id`
+- `name`
+
+Required feature fields:
+- `id`
+- `title`
+- `column`
+
+Required parking lot fields:
+- `id`
+- `title`
+
+Required pulse fields:
+- `id`
+- `timestamp`
+- `project_id`
+- `pulse_type`
+- `message`
+
+## Export Rule
+
+Exports should preserve IDs exactly.
+
+Do not regenerate IDs during export/import unless resolving duplicates is required.
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
new file mode 100644
index 0000000..8dcd2fe
--- /dev/null
+++ b/docs/DECISIONS.md
@@ -0,0 +1,127 @@
+# BuildPulse Decisions
+
+## Decision 001 — BuildPulse Starts as Planning Cockpit, Not Agent Framework
+
+Date:
+2026-05-06
+
+Decision:
+BuildPulse v0.1 will be a planning cockpit, not a full Agent Pulse event framework.
+
+Reason:
+The full Agent Pulse concept is powerful but too large for v0.1. The user needs a practical planning and scope-control system first.
+
+Consequences:
+- No WebSockets.
+- No real agent ingestion.
+- No event bus.
+- Manual Pulse entries only.
+- Pulse-compatible schema from day one.
+
+## Decision 002 — Pulse-Compatible From Day One
+
+Date:
+2026-05-06
+
+Decision:
+BuildPulse v0.1 will store progress as Pulse-shaped events even when events are manually created.
+
+Reason:
+This allows future autonomous agents to emit the same event shape without a major data model rewrite.
+
+Consequences:
+- Pulse schema includes future-friendly fields such as `agent_id`, `trace_id`, `confidence_score`, `structured_payload`, and `evidence_refs`.
+- v0.1 UI may not use all fields deeply.
+
+## Decision 003 — Single Project in v0.1
+
+Date:
+2026-05-06
+
+Decision:
+BuildPulse v0.1 supports one active project only.
+
+Reason:
+Multiple projects add navigation, filtering, data complexity, and scope risk. The first version should prove the core workflow.
+
+Consequences:
+- Project data exists, but only one project is active.
+- Multi-project support is parked for later.
+
+## Decision 004 — No Phases or Releases in v0.1
+
+Date:
+2026-05-06
+
+Decision:
+Phases and releases are not part of v0.1.
+
+Reason:
+The first version only needs to manage features and parked ideas. Phases/releases become useful after the core feature cockpit works.
+
+Consequences:
+- Features are grouped by Now, Next, Later, Done.
+- Phases/releases are parked for v0.3.
+
+## Decision 005 — Sessions Are Pulse Events in v0.1
+
+Date:
+2026-05-06
+
+Decision:
+Build sessions are represented as Pulse events with shared `trace_id`.
+
+Reason:
+A separate session model adds complexity. Pulse events can already represent session starts, actions, results, and endings.
+
+Consequences:
+- Pulse types include SESSION_START and SESSION_END.
+- Session view may come later.
+- Trace IDs allow grouping session-related pulses later.
+
+## Decision 006 — Local-First Storage
+
+Date:
+2026-05-06
+
+Decision:
+BuildPulse v0.1 uses local-first storage.
+
+Reason:
+This keeps the first version simple, fast, private, and easy to run.
+
+Consequences:
+- No database.
+- No auth.
+- Export/import is important to avoid lock-in.
+
+## Decision 007 — Export Is a Core Feature
+
+Date:
+2026-05-06
+
+Decision:
+Markdown/JSON export is required in v0.1.
+
+Reason:
+BuildPulse must produce useful handoff context for AI coding agents.
+
+Consequences:
+- `CLAUDE_CONTEXT.md` is a primary output.
+- JSON and JSONL exports preserve future compatibility.
+
+## Decision 008 — Local LLM Is Not a v0.1 Blocker
+
+Date:
+2026-05-06
+
+Decision:
+Local LLMs may assist development but are not required to build or run v0.1.
+
+Reason:
+The project must not become blocked by local model setup, GPU issues, inference tooling, or model comparisons.
+
+Consequences:
+- Claude Code/Codex/cloud tools may build v0.1.
+- Local models can be tested as reviewers or for isolated tasks.
+- Local/cloud router is parked for later.
diff --git a/docs/EXPORT_FORMATS.md b/docs/EXPORT_FORMATS.md
new file mode 100644
index 0000000..82cd320
--- /dev/null
+++ b/docs/EXPORT_FORMATS.md
@@ -0,0 +1,158 @@
+# BuildPulse Export Formats
+
+## Export Goals
+
+Exports must support:
+1. Backup/restore
+2. AI coding agent handoff
+3. Future Agent Pulse compatibility
+4. Human-readable project review
+
+## Export Types
+
+v0.1 supports:
+- Full JSON export
+- Pulse JSONL export
+- Markdown context package
+
+## Full JSON Export
+
+File name:
+
+```text
+buildpulse-export.json
+```
+
+Shape:
+
+```json
+{
+  "schema_version": "0.1.0",
+  "exported_at": "2026-05-06T00:00:00+02:00",
+  "project": {},
+  "features": [],
+  "parking_lot": [],
+  "pulses": [],
+  "settings": {}
+}
+```
+
+## Pulse JSONL Export
+
+File name:
+
+```text
+pulses.jsonl
+```
+
+Rules:
+- One JSON object per line.
+- Each line is one Pulse event.
+- Preserve event IDs.
+- Preserve timestamps.
+- Do not wrap in an array.
+
+Example:
+
+```jsonl
+{"id":"pulse_001","timestamp":"2026-05-06T00:00:00+02:00","project_id":"project_buildpulse","feature_id":"feature_plan_screen","source":"manual","agent_id":"jimmi","pulse_type":"INTENT","message":"Start implementing Feature Plan.","structured_payload":{},"confidence_score":0.9,"evidence_refs":[],"trace_id":"session_001"}
+{"id":"pulse_002","timestamp":"2026-05-06T00:30:00+02:00","project_id":"project_buildpulse","feature_id":"feature_plan_screen","source":"claude_code","agent_id":"claude_code","pulse_type":"RESULT","message":"Feature card creation implemented.","structured_payload":{},"confidence_score":0.8,"evidence_refs":["Manual test passed"],"trace_id":"session_001"}
+```
+
+## Markdown Package
+
+The Markdown export should generate these files:
+- `PROJECT_SUMMARY.md`
+- `FEATURE_PLAN.md`
+- `PARKING_LOT.md`
+- `PULSE_LOG.md`
+- `CLAUDE_CONTEXT.md`
+
+## PROJECT_SUMMARY.md
+
+Must include:
+- Project name
+- One-line pitch
+- Description
+- Current goal
+- Notes
+
+## FEATURE_PLAN.md
+
+Must include features grouped by:
+- Now
+- Next
+- Later
+- Done
+
+Each feature should include:
+- Title
+- Description
+- Priority
+- Acceptance criteria
+- Scope notes
+
+## PARKING_LOT.md
+
+Must include:
+- Title
+- Description
+- Reason parked
+- Possible future placement
+- Risk level
+
+## PULSE_LOG.md
+
+Must include recent Pulse events, newest first or chronological.
+
+Each pulse should include:
+- Timestamp
+- Pulse type
+- Feature
+- Source/agent
+- Message
+- Confidence
+- Evidence refs
+
+## CLAUDE_CONTEXT.md
+
+This is the most important AI handoff file.
+
+It should include:
+
+# AI Coding Context
+## Project
+<Project summary>
+## Current Goal
+<Current project goal>
+## Active Features
+<Now features>
+## Next Features
+<Next features>
+## Done Features
+<Done features>
+## Parking Lot / Do Not Implement Yet
+<Parking lot items>
+## Recent Pulse Events
+<Recent important pulses>
+## Instructions for AI Developer
+- Only work on the selected feature.
+- Do not implement Parking Lot items.
+- Preserve working behavior.
+- Report changes and test steps.
+
+## Import Rules
+
+When importing JSON:
+- Validate schema version.
+- Validate required fields.
+- Show useful error if invalid.
+- Preserve IDs.
+- Avoid silent data loss.
+- If schema version differs, warn user.
+
+## Copy-to-Clipboard
+
+If downloading multiple files is complex in v0.1, support copying each Markdown output to clipboard.
+
+Download can be added later.
diff --git a/docs/PARKING_LOT.md b/docs/PARKING_LOT.md
new file mode 100644
index 0000000..ebdfff1
--- /dev/null
+++ b/docs/PARKING_LOT.md
@@ -0,0 +1,222 @@
+# BuildPulse Parking Lot
+
+This file contains useful ideas that are intentionally not part of v0.1.
+Parking ideas is a success behavior, not a failure.
+
+## AI Idea Triage
+
+Description:
+Use AI to classify new ideas into Now, Next, Later, Parking Lot, or Reject.
+
+Reason parked:
+Manual workflow should be proven first.
+
+Possible version:
+v0.2
+
+Risk:
+Medium
+
+## AI Scope Creep Detection
+
+Description:
+AI reviews a proposed feature and warns if it violates current scope.
+
+Reason parked:
+Requires AI integration and context handling.
+
+Possible version:
+v0.2
+
+Risk:
+Medium
+
+## Acceptance Criteria Generator
+
+Description:
+AI generates testable acceptance criteria for a feature card.
+
+Reason parked:
+Useful but not needed for manual v0.1.
+
+Possible version:
+v0.2
+
+Risk:
+Low
+
+## Phases and Releases
+
+Description:
+Add formal project phases and release planning.
+
+Reason parked:
+v0.1 only needs Now/Next/Later/Done.
+
+Possible version:
+v0.3
+
+Risk:
+Medium
+
+## Session View
+
+Description:
+Add a dedicated session timer and session dashboard.
+
+Reason parked:
+In v0.1, sessions are represented as Pulse events.
+
+Possible version:
+v0.4
+
+Risk:
+Medium
+
+## Claude/Codex Prompt Generator
+
+Description:
+Generate ready-to-paste prompts for Claude Code, Codex, OpenCode, or OpenClaw based on selected feature.
+
+Reason parked:
+Requires feature plan and export to work first.
+
+Possible version:
+v0.4
+
+Risk:
+Low
+
+## Local/Cloud AI Router
+
+Description:
+Track which AI tasks should use local LLMs vs cloud providers.
+
+Reason parked:
+Important later, but not required for planning cockpit v0.1.
+
+Possible version:
+v0.5
+
+Risk:
+High
+
+## Local Model Capability Lab
+
+Description:
+Track local models, hardware, use cases, speed, quality, and recommended tasks.
+
+Reason parked:
+Useful but could become a distraction before BuildPulse is useful.
+
+Possible version:
+v0.5
+
+Risk:
+High
+
+## File-Backed Storage
+
+Description:
+Store features as JSON files and pulses as JSONL on disk.
+
+Reason parked:
+More future-compatible with agents, but browser local storage is faster for v0.1.
+
+Possible version:
+v0.6 or earlier if explicitly chosen.
+
+Risk:
+Medium
+
+## Real Agent Pulse Ingestion
+
+Description:
+Allow external agents/tools to submit Pulse events via API.
+
+Reason parked:
+This is the beginning of the actual Agent Pulse framework and should not be built before manual pulse workflows are proven.
+
+Possible version:
+v1.0
+
+Risk:
+High
+
+## WebSocket Timeline
+
+Description:
+Show live agent activity in real time.
+
+Reason parked:
+Requires backend/event infrastructure.
+
+Possible version:
+v1.0+
+
+Risk:
+High
+
+## GitHub/Gitea Integration
+
+Description:
+Link pulses/features to commits, branches, issues, and PRs.
+
+Reason parked:
+Useful later but not needed for v0.1.
+
+Possible version:
+v1.0+
+
+Risk:
+Medium
+
+## OpenClaw/Hermes Integration
+
+Description:
+Read OpenClaw/Hermes heartbeats, agent status, and task outputs into BuildPulse.
+
+Reason parked:
+Important long-term, but too complex for v0.1.
+
+Possible version:
+v1.0+
+
+Risk:
+High
+
+## Multi-Project Support
+
+Description:
+Allow multiple projects in the same BuildPulse instance.
+
+Reason parked:
+Single-project workflow should be proven first.
+
+Possible version:
+v0.6+
+
+Risk:
+Medium
+
+## Full Agent Pulse Framework
+
+Description:
+Event-driven autonomous agent observability and coordination layer.
+Includes:
+- Append-only event log
+- Agent ownership
+- Handoff protocol
+- Progress engine
+- Safety gates
+- WebSockets
+- Plugin system
+
+Reason parked:
+This is the end-state architecture, not the first build.
+
+Possible version:
+v2.0
+
+Risk:
+Dangerous
diff --git a/docs/PRODUCT_BRIEF.md b/docs/PRODUCT_BRIEF.md
new file mode 100644
index 0000000..b4469f7
--- /dev/null
+++ b/docs/PRODUCT_BRIEF.md
@@ -0,0 +1,100 @@
+# Product Brief — BuildPulse
+
+## Product Name
+
+BuildPulse
+
+## One-Line Description
+
+BuildPulse is a local-first planning cockpit that helps a solo builder capture features, park distracting ideas, log progress as Pulse events, and export clean context for AI coding agents.
+
+## Problem
+
+The user has many ideas and several AI coding tools, but lacks a stable system for:
+- Capturing new ideas without derailing active work
+- Deciding what belongs now vs later
+- Following a clear feature plan
+- Keeping context visible across AI coding sessions
+- Preventing working builds from being broken by random new features
+- Seeing progress based on evidence instead of vague task status
+- Preparing clean handoff context for Claude Code, Codex, OpenCode, OpenClaw, or other agents
+
+## Target User
+
+Primary target user:
+- A solo builder using AI coding tools to create apps, games, and tools.
+- The user is technically curious but does not want to manually manage complex development workflows.
+- The user benefits from ADHD-friendly guardrails, visible plans, parking lots, and short work sessions.
+
+Secondary future users:
+- Indie hackers
+- AI-assisted builders
+- Small teams working with autonomous coding agents
+- Users who want a lightweight alternative to Jira/task boards for AI-assisted work
+
+## Core User Need
+
+The user needs one trusted place to answer:
+- What am I building?
+- What is currently in scope?
+- What should I work on next?
+- Where should this new idea go?
+- What has changed?
+- What can I safely hand off to an AI coding agent?
+
+## v0.1 Product Promise
+
+BuildPulse v0.1 lets the user manage one active project with:
+- A simple feature plan
+- A parking lot for distracting ideas
+- A manual Pulse log
+- Exportable project context
+
+## Core Workflow
+
+1. User opens BuildPulse.
+2. User sees the current project and active feature plan.
+3. User adds or edits feature cards.
+4. User parks distracting ideas instead of adding them to active scope.
+5. User logs progress using Pulse events.
+6. User exports clean Markdown context for an AI coder.
+7. AI coder works from exported context.
+8. User logs results back into BuildPulse.
+
+## Product Positioning
+
+BuildPulse is not:
+- Jira
+- Trello clone
+- Full agent framework
+- Full project management suite
+- Autonomous AI orchestration system
+- Multi-user SaaS platform
+
+BuildPulse is:
+- A calm cockpit for solo AI-assisted building
+- A pulse-compatible planning layer
+- A scope guardrail
+- A structured bridge between human ideas and AI coding agents
+
+## Success Criteria for v0.1
+
+v0.1 succeeds if the user can use it to plan and manage BuildPulse itself, then use it to plan another project such as Crimson Drive.
+
+## First Dogfood Project
+
+BuildPulse should track itself as the first project.
+
+Initial feature groups:
+
+Now:
+- Feature Plan
+- Parking Lot
+- Pulse Log
+- Export
+
+Later:
+- AI triage
+- Phases/releases
+- Local/cloud router
+- Real Agent Pulse ingestion
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
new file mode 100644
index 0000000..73f0f8c
--- /dev/null
+++ b/docs/ROADMAP.md
@@ -0,0 +1,135 @@
+# BuildPulse Roadmap
+
+## Philosophy
+
+Each version must be useful on its own.
+Do not build future architecture before the current manual workflow is proven.
+
+## v0.1 — Single-Project Planning Cockpit
+
+Goal:
+Create the smallest useful cockpit for one project.
+
+Includes:
+- Single project summary
+- Feature Plan
+- Parking Lot
+- Manual Pulse Log
+- Markdown/JSON/JSONL export
+- Local persistence
+
+Does not include:
+- AI
+- Phases
+- Releases
+- Multiple projects
+- Real agent integration
+
+## v0.2 — AI Idea Placement
+
+Goal:
+Use AI to help classify new ideas.
+
+Potential features:
+- AI classify idea as Now / Next / Later / Parking Lot / Reject
+- AI suggest reason for placement
+- AI suggest smallest safe version
+- AI detect scope creep
+- AI generate acceptance criteria draft
+
+Build only one or two AI actions first.
+
+Highest-value first AI action:
+
+```text
+Classify new idea and suggest placement.
+```
+
+## v0.3 — Phases and Releases
+
+Goal:
+Add structured implementation planning.
+
+Potential features:
+- Phases
+- Releases
+- Definition of done
+- Forbidden features per release
+- Required vs optional features
+- Release readiness view
+
+## v0.4 — Session Prompt Generator
+
+Goal:
+Generate clean prompts for AI coding agents.
+
+Potential features:
+- Start 30-minute session from feature
+- Generate Claude Code/Codex prompt
+- Include do-not-touch list
+- Include acceptance criteria
+- Include recent pulse context
+- End-session summary template
+
+## v0.5 — Local/Cloud AI Assistant
+
+Goal:
+Start learning where local LLMs are good enough.
+
+Potential features:
+- Configure local endpoint manually
+- Use local LLM for summaries
+- Use local LLM for feature classification
+- Track model usefulness
+- Manual cloud fallback
+
+## v1.0 — Agent Pulse Ingestion MVP
+
+Goal:
+Allow real agents/tools to submit Pulse events.
+
+Potential features:
+- Simple HTTP API for Pulse events
+- Append-only pulse event store
+- Real-time or refresh-based timeline
+- Feature state updated from events
+- Basic progress computation
+- Safety/event validation
+
+## v1.5 — Agent Observability
+
+Goal:
+Show real live-ish agent activity.
+
+Potential features:
+- Agent activity view
+- Blocker/risk view
+- Handoff events
+- Evidence refs
+- Test result parsing
+- Git commit refs
+
+## v2.0 — Agent Pulse Framework
+
+Goal:
+Become a real event-driven nervous system for autonomous agents.
+
+Potential features:
+- WebSocket stream
+- Event subscriptions
+- Agent coordination protocol
+- Ownership claims
+- Handoff handling
+- Progress engine
+- Constraints and approval gates
+- Plugin system
+
+## Long-Term Vision
+
+BuildPulse becomes the human cockpit for:
+- Feature planning
+- Idea maturation
+- Scope control
+- AI agent work visibility
+- Local/cloud AI routing
+- Autonomous agent observability
diff --git a/docs/SCOPE.md b/docs/SCOPE.md
new file mode 100644
index 0000000..08c3857
--- /dev/null
+++ b/docs/SCOPE.md
@@ -0,0 +1,171 @@
+# BuildPulse v0.1 Scope
+
+## Release Goal
+
+Build a tiny, useful, single-project planning cockpit with pulse-compatible progress logging and exportable AI handoff context.
+
+## v0.1 Core Question
+
+Can BuildPulse help the user keep one project scoped, visible, and handoff-ready for AI-assisted development?
+
+## In Scope
+
+### 1. Single Project
+
+The app supports one active project.
+The project has:
+- Name
+- One-line pitch
+- Description
+- Current goal
+- Notes
+
+No multiple projects in v0.1.
+
+### 2. Feature Plan
+
+The user can create, edit, delete, and organize features.
+
+Feature columns:
+- Now
+- Next
+- Later
+- Done
+
+Feature fields:
+- Title
+- Description
+- Status/column
+- Priority
+- Acceptance criteria
+- Scope notes
+- Created date
+- Updated date
+
+### 3. Parking Lot
+
+The user can add, edit, delete, and review parked ideas.
+
+Parking Lot item fields:
+- Title
+- Description
+- Reason parked
+- Possible future placement
+- Risk level
+- Created date
+
+### 4. Pulse Log
+
+The user can manually add Pulse events.
+
+Pulse event fields:
+- Timestamp
+- Feature link, optional
+- Source/agent
+- Pulse type
+- Message
+- Confidence score
+- Evidence refs
+- Trace ID, optional
+
+Pulse types:
+- INTENT
+- ACTION
+- RESULT
+- BLOCKER
+- DECISION
+- PARKED_IDEA
+- TEST_RESULT
+- SESSION_START
+- SESSION_END
+- REFLECTION
+
+### 5. Export
+
+The user can export:
+- Full project JSON
+- Pulse log as JSONL
+- Markdown context package
+
+Markdown exports:
+- PROJECT_SUMMARY.md
+- FEATURE_PLAN.md
+- PARKING_LOT.md
+- PULSE_LOG.md
+- CLAUDE_CONTEXT.md
+
+### 6. Local Persistence
+
+The app persists data locally.
+Acceptable v0.1 storage:
+- LocalStorage
+- IndexedDB
+- JSON file export/import
+
+No database required.
+
+## Out of Scope for v0.1
+
+Do not implement:
+- Multiple projects
+- Phases
+- Releases
+- AI triage
+- AI model provider settings
+- Local/cloud model routing
+- Real agent integration
+- OpenClaw integration
+- Claude Code direct integration
+- GitHub/Gitea integration
+- WebSockets
+- Backend authentication
+- Database
+- Multi-user collaboration
+- Notifications
+- Advanced analytics
+- Dependency graph
+- Calendar planning
+- Native mobile app
+- Automated progress computation
+
+## Scope Guardrail
+
+Any idea not required for v0.1 must be placed in Parking Lot.
+
+## v0.1 Definition of Done
+
+BuildPulse v0.1 is done when:
+1. The user can edit the single project summary.
+2. The user can add feature cards.
+3. The user can move features between Now, Next, Later, and Done.
+4. The user can add acceptance criteria to a feature.
+5. The user can add Parking Lot items.
+6. The user can manually add Pulse events.
+7. Pulse events can be linked to features.
+8. Pulse events display in chronological order.
+9. The app persists data locally after refresh.
+10. The user can export JSON.
+11. The user can export Pulse events as JSONL.
+12. The user can export Markdown context.
+13. The exported `CLAUDE_CONTEXT.md` is useful as an AI coding handoff.
+14. The app can be used to manage BuildPulse itself.
+
+## v0.1 First Data Seed
+
+On first run, optionally seed the app with BuildPulse as the active project.
+
+Suggested starter features:
+
+Now:
+- Feature Plan screen
+- Parking Lot screen
+- Pulse Log screen
+- Export screen
+
+Parking Lot:
+- AI triage
+- Phases/releases
+- Multi-project support
+- Local/cloud model router
+- Real Agent Pulse event ingestion
+- Git integration
diff --git a/docs/TEST_PLAN.md b/docs/TEST_PLAN.md
new file mode 100644
index 0000000..f0ec112
--- /dev/null
+++ b/docs/TEST_PLAN.md
@@ -0,0 +1,233 @@
+# BuildPulse v0.1 Test Plan
+
+## Test Goal
+
+Verify that BuildPulse v0.1 can manage one project, protect scope, log progress, and export useful AI handoff context.
+
+## Manual Test Group 1 — Project Summary
+
+### Test 1.1: Edit project summary
+
+Steps:
+1. Open app.
+2. Edit project name.
+3. Edit one-line pitch.
+4. Edit current goal.
+5. Refresh page.
+
+Expected:
+- Edited values persist after refresh.
+
+### Test 1.2: Empty project fields
+
+Steps:
+1. Clear optional project fields.
+2. Save.
+3. Refresh.
+
+Expected:
+- App does not crash.
+- Empty states are readable.
+
+## Manual Test Group 2 — Feature Plan
+
+### Test 2.1: Add feature
+
+Steps:
+1. Open Feature Plan.
+2. Add new feature.
+3. Enter title and description.
+4. Save.
+
+Expected:
+- Feature appears in default column.
+- Feature persists after refresh.
+
+### Test 2.2: Move feature
+
+Steps:
+1. Move a feature from Now to Next.
+2. Move it to Later.
+3. Move it to Done.
+
+Expected:
+- Feature appears in the correct column each time.
+- State persists after refresh.
+
+### Test 2.3: Edit acceptance criteria
+
+Steps:
+1. Open feature detail.
+2. Add acceptance criteria.
+3. Save and close.
+4. Reopen feature.
+
+Expected:
+- Acceptance criteria are saved and visible.
+
+### Test 2.4: Delete feature
+
+Steps:
+1. Create a test feature.
+2. Delete it.
+
+Expected:
+- Feature is removed.
+- App remains stable.
+- Related pulse events are either preserved with missing feature label or handled gracefully.
+
+## Manual Test Group 3 — Parking Lot
+
+### Test 3.1: Add parked idea
+
+Steps:
+1. Open Parking Lot.
+2. Add an idea.
+3. Add reason parked and risk level.
+
+Expected:
+- Item appears in Parking Lot.
+- Item persists after refresh.
+
+### Test 3.2: Convert parked idea to feature
+
+If implemented in v0.1:
+
+Steps:
+1. Select Parking Lot item.
+2. Convert to feature.
+
+Expected:
+- New feature is created.
+- Original item is either removed or marked converted.
+
+If not implemented:
+- This test is skipped.
+
+## Manual Test Group 4 — Pulse Log
+
+### Test 4.1: Add INTENT pulse
+
+Steps:
+1. Open Pulse Log.
+2. Add pulse type INTENT.
+3. Link to a feature.
+4. Add message and confidence.
+
+Expected:
+- Pulse appears in log.
+- Feature name is shown.
+- Pulse persists after refresh.
+
+### Test 4.2: Add BLOCKER pulse without feature
+
+Steps:
+1. Add pulse type BLOCKER.
+2. Do not link feature.
+3. Save.
+
+Expected:
+- Pulse appears in log.
+- App does not require feature link.
+
+### Test 4.3: Filter pulses
+
+If filtering is implemented:
+
+Steps:
+1. Add multiple pulse types.
+2. Filter by RESULT.
+3. Filter by feature.
+
+Expected:
+- Correct pulses are shown.
+
+## Manual Test Group 5 — Export
+
+### Test 5.1: Export full JSON
+
+Steps:
+1. Add project summary, features, parking items, and pulses.
+2. Export full JSON.
+3. Inspect file/content.
+
+Expected:
+- JSON contains schema version.
+- JSON contains project.
+- JSON contains features.
+- JSON contains parking_lot.
+- JSON contains pulses.
+
+### Test 5.2: Import JSON
+
+Steps:
+1. Export JSON.
+2. Clear app or use different browser.
+3. Import JSON.
+
+Expected:
+- Data is restored.
+- App does not duplicate IDs unexpectedly.
+
+### Test 5.3: Export Pulse JSONL
+
+Steps:
+1. Add several pulses.
+2. Export JSONL.
+
+Expected:
+- Each line is valid JSON.
+- Each line represents one pulse event.
+
+### Test 5.4: Export Markdown
+
+Steps:
+1. Export Markdown package.
+2. Open `CLAUDE_CONTEXT.md`.
+
+Expected:
+- Contains project summary.
+- Contains Now/Next/Later/Done features.
+- Contains Parking Lot.
+- Contains recent pulses.
+- Is useful as an AI coder handoff.
+
+## Manual Test Group 6 — Mobile Usability
+
+### Test 6.1: Phone layout
+
+Steps:
+1. Open app in mobile-width browser.
+2. Navigate all views.
+3. Add feature.
+4. Add parked idea.
+5. Add pulse.
+
+Expected:
+- UI is usable on phone.
+- No critical controls are inaccessible.
+
+## Manual Test Group 7 — Scope Guard
+
+### Test 7.1: Parking distracting idea
+
+Scenario:
+User thinks of “real-time OpenClaw integration.”
+
+Steps:
+1. Add it to Parking Lot.
+2. Mark risk as high/dangerous.
+3. Do not add it as active feature.
+
+Expected:
+- Idea is captured.
+- Active v0.1 scope remains clean.
+
+## Release Decision
+
+v0.1 can ship when:
+- All required happy paths pass.
+- Data persists.
+- Export works.
+- App can manage BuildPulse itself.
+- No forbidden v0.1 scope items have been implemented.
diff --git a/docs/UI_SPEC.md b/docs/UI_SPEC.md
new file mode 100644
index 0000000..9451647
--- /dev/null
+++ b/docs/UI_SPEC.md
@@ -0,0 +1,211 @@
+# BuildPulse UI Specification
+
+## Design Goal
+
+BuildPulse should feel like a calm cockpit, not an enterprise task manager.
+The user should quickly understand:
+- What is active now
+- What comes next
+- What has been parked
+- What happened recently
+- How to export context for AI work
+
+## Main Navigation
+
+v0.1 has four main views:
+1. Feature Plan
+2. Parking Lot
+3. Pulse Log
+4. Export
+
+Optional small project summary area can appear in the header or dashboard area.
+
+## Global Layout
+
+Suggested layout:
+
+```text
+------------------------------------------------
+BuildPulse Active Project: BuildPulse
+------------------------------------------------
+Feature Plan | Parking Lot | Pulse Log | Export
+------------------------------------------------
+Main content
+------------------------------------------------
+```
+
+Mobile:
+- Navigation collapses into bottom tabs or simple top tabs.
+- Cards should stack vertically.
+- Editing can happen in modal, drawer, or full-screen panel.
+
+## View 1: Feature Plan
+
+Purpose:
+Show all feature cards grouped by current placement.
+
+Columns:
+- Now
+- Next
+- Later
+- Done
+
+Each card displays:
+- Title
+- Short description
+- Priority
+- Acceptance criteria count
+- Recent pulse indicator, optional
+
+Actions:
+- Add feature
+- Edit feature
+- Delete feature
+- Move feature to another column
+- Add acceptance criteria
+- Add pulse for this feature
+
+Feature detail panel fields:
+- Title
+- Description
+- Column
+- Priority
+- Status
+- Acceptance criteria
+- Scope notes
+
+Empty state:
+No features yet. Add the first feature to define what you are building.
+
+## View 2: Parking Lot
+
+Purpose:
+Capture distracting ideas safely.
+
+Each item displays:
+- Title
+- Description
+- Reason parked
+- Possible future placement
+- Risk level
+
+Actions:
+- Add parked idea
+- Edit parked idea
+- Delete parked idea
+- Convert to feature
+- Add pulse event: `PARKED_IDEA`
+
+Empty state:
+No parked ideas yet. This is where useful distractions go so they do not hijack the current build.
+
+## View 3: Pulse Log
+
+Purpose:
+Show what has happened over time.
+
+Display:
+- Chronological event list, newest first by default
+- Filters:
+  - Pulse type
+  - Feature
+  - Source/agent
+
+Each pulse displays:
+- Timestamp
+- Pulse type
+- Feature title, if linked
+- Source/agent
+- Message
+- Confidence score
+- Evidence refs
+
+Actions:
+- Add Pulse event
+- Edit Pulse event, optional
+- Delete Pulse event, optional for v0.1
+- Filter by feature
+- Filter by type
+
+Add Pulse form fields:
+- Pulse type
+- Feature link, optional
+- Source/agent
+- Message
+- Confidence score
+- Evidence refs
+- Trace ID, optional
+
+Empty state:
+No Pulse events yet. Add an `INTENT` or `DECISION` to start the project log.
+
+## View 4: Export
+
+Purpose:
+Create useful handoff context for AI coding agents.
+
+Export options:
+1. Full JSON export
+2. Pulse JSONL export
+3. Markdown package export
+
+Markdown package includes:
+- `PROJECT_SUMMARY.md`
+- `FEATURE_PLAN.md`
+- `PARKING_LOT.md`
+- `PULSE_LOG.md`
+- `CLAUDE_CONTEXT.md`
+
+Actions:
+- Copy Markdown to clipboard
+- Download Markdown files, if practical
+- Download JSON
+- Download JSONL
+- Import JSON
+
+Import behavior:
+- Validate schema
+- Show preview/confirmation, if practical
+- Handle invalid JSON gracefully
+- Avoid data loss where possible
+
+## Project Summary Area
+
+Project summary can be a compact editable panel.
+
+Fields:
+- Project name
+- One-line pitch
+- Description
+- Current goal
+- Notes
+
+This should not become a full project management screen in v0.1.
+
+## Visual Style
+
+Use:
+- Simple typography
+- Plenty of whitespace
+- Calm colors
+- Clear hierarchy
+- Rounded cards if desired
+- Low visual noise
+
+Avoid:
+- Dense tables everywhere
+- Enterprise dashboards
+- Too many badges
+- Too many settings
+- Gamification
+- Overly flashy UI
+
+## UX Priority
+
+Most important UX actions:
+1. Add feature quickly.
+2. Park idea quickly.
+3. Add pulse quickly.
+4. Export context quickly.
+
+The app should support quick capture without forcing perfect data entry.