agentflight 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,140 @@
+# Changelog
+
+All notable AgentFlight changes are documented here.
+
+## [0.3.1] - 2026-06-13
+
+### Changed
+
+- Reworked the README around a clearer 60-second AgentFlight workflow.
+- Added sample CLI output for status, report, replay, and resume.
+- Added a replay timeline screenshot to make the v0.3.0 experience easier to understand.
+- Added a basic example session walkthrough and v0.3.0 launch-note drafts.
+- Improved npm keywords and package metadata.
+- Narrowed packaged files to include useful README-linked docs/assets without shipping marketing drafts.
+
+### Documentation
+
+- Added launch notes draft for v0.3.0 public/demo positioning.
+- Updated development log with post-v0.3.0 polish verification.
+
+### Verification
+
+- `npm run verify` passed.
+- `npm run format:check` passed.
+- `npm pack --dry-run` passed.
+- `npm audit --audit-level=moderate` found `0 vulnerabilities`.
+- ProjScan preflight passed.
+- AgentLoopKit verification passed.
+
+## [0.3.0] - 2026-06-13
+
+AgentFlight now records session events and snapshots so reports and replays show how a coding session evolved.
+
+### Added
+
+- Added `agentflight snapshot --note "..."` to record a local checkpoint for the active session.
+- Added session-level `events` with backward compatibility for older sessions.
+- Added event recording for session start, verification attempts, snapshots, report generation, replay generation, resume prompt generation, and doctor runs.
+- Added timeline sections to Markdown reports and HTML replays.
+- Added latest snapshot context to status and resume prompts.
+- Added changed-file groups to replay output.
+- Added tests for session events, snapshot creation, missing active sessions, timeline rendering, older session compatibility, and verification events.
+
+### Changed
+
+- Replays now feel more like flight recorder timelines instead of final-state summaries.
+- Reports now include a concise event timeline before changed files and proof evidence.
+- Resume prompts now include latest snapshot notes and current verification state.
+
+### Verification
+
+- `npm run verify` passed.
+- `npm run format:check` passed.
+- `npm pack --dry-run` passed for `agentflight@0.3.0`.
+- `npm audit --audit-level=moderate` found `0 vulnerabilities`.
+- ProjScan preflight passed with health `100/100`.
+- AgentLoopKit verification passed.
+
+## [0.2.1] - 2026-06-13
+
+Patch release candidate focused on friction found while dogfooding the v0.2.0 core workflow.
+
+### Changed
+
+- `agentflight verify` now prints the stdout and stderr evidence paths immediately after each recorded run.
+- Failed verification output and downstream next actions now include the exact command to rerun.
+- `agentflight report`, `agentflight replay`, and `agentflight resume` now avoid stale "generate a report" next actions once proof is ready.
+- HTML replays now include a compact summary strip for risk, changed files, proof counts, and review readiness.
+- AgentLoopKit workflow files under `.agentloop/` are treated as low-risk dogfooding artifacts instead of unknown code changes.
+
+### Fixed
+
+- ProjScan and AgentLoopKit adapters now prefer repo-local `node_modules/.bin` binaries before PATH-global commands, preventing stale global versions from appearing in reports.
+- Tool adapter version output is normalized when CLIs include decorated version text.
+
+### Verification
+
+- Targeted v0.2.1 regression tests passed.
+- `npm run verify` passed.
+- `npm run format:check` passed.
+- `npm pack --dry-run` passed for `agentflight@0.2.1`.
+- `npm audit --audit-level=moderate` found `0 vulnerabilities`.
+- ProjScan preflight passed with health `100/100`.
+- AgentLoopKit verification passed.
+
+## [0.2.0] - 2026-06-13
+
+AgentFlight now captures real verification evidence and uses it across status, report, replay, and resume.
+
+### Added
+
+- Added `agentflight verify` to run verification commands and capture local evidence.
+- Added verification run persistence in session records, including command, timestamps, duration, exit code, status, stdout path, and stderr path.
+- Added `.agentflight/evidence/` for local stdout/stderr artifacts.
+- Added evidence-aware status, report, replay, and resume outputs.
+- Added tests for verification success, failure, persistence, evidence-aware outputs, and v0.1 session compatibility.
+
+### Changed
+
+- `agentflight status` now reports changed areas, proof gaps, review readiness, and a next action based on captured evidence.
+- `agentflight report` now includes verification evidence and honest review recommendations.
+- `agentflight replay` now renders verification cards in the local HTML artifact.
+- `agentflight resume` now includes verification gaps, the exact next command, and stronger continuation guardrails.
+
+### Fixed
+
+- `agentflight doctor` now checks write permission for `.agentflight/`, not just path existence.
+- `agentflight --version` now reports the package version instead of the stale `0.1.0` value.
+
+### Verification
+
+- `npm run verify` passed.
+- `npm run format:check` passed.
+- `npm pack --dry-run` passed.
+- `npm audit --audit-level=moderate` found 0 vulnerabilities.
+- ProjScan preflight passed.
+- AgentLoopKit verification passed.
+
+## [0.1.1] - 2026-06-13
+
+### Fixed
+
+- Fixed npm `.bin` symlink invocation so `npx agentflight --help` runs the CLI instead of exiting silently.
+
+### Added
+
+- Added CI verification on pushes and pull requests.
+- Added tag-based npm publishing through GitHub Actions Trusted Publishing.
+- Added release process documentation.
+
+## [0.1.0] - 2026-06-13
+
+### Added
+
+- First AgentFlight MVP CLI.
+- Added `init`, `start`, `status`, `report`, `replay`, `resume`, and `doctor` commands.
+- Added local `.agentflight/` config, session, report, replay, and resume prompt artifacts.
+- Added ProjScan and AgentLoopKit adapters with graceful fallbacks.
+- Added TypeScript, Vitest, ESLint, Prettier, and npm package setup.
+- Added README, architecture docs, dogfooding docs, verification docs, roadmap, and monetisation notes.

package/README.md

@@ -2,23 +2,163 @@
 
 See what your coding agent did. Prove it works. Know what to do next.
 
-AgentFlight is a local-first flight recorder for AI coding agents from Baseframe Labs. It records AI-assisted coding sessions, explains what changed, highlights risk, captures proof gaps, generates replay artifacts, and produces a clean handoff for the next agent or human reviewer.
+AgentFlight is a local-first flight recorder for AI coding agents from Baseframe Labs. It sits around Codex, Claude Code, Cursor, Windsurf, Gemini CLI, Aider, OpenCode, and similar tools so you can review the session instead of guessing what happened.
 
-AgentFlight is not another coding agent. It is the trust, observability, replay, and proof layer around tools like Codex, Claude Code, Cursor, Windsurf, Gemini CLI, Aider, OpenCode, and similar coding agents.
+AgentFlight helps you:
 
-## Why AgentFlight Exists
+- start an AI coding session
+- capture verification evidence
+- see changed files and risk
+- create snapshots during the session
+- generate a proof report
+- generate a local replay timeline
+- create a resume prompt for the next agent or reviewer
 
-AI coding agents can move quickly, but developers still need to answer practical review questions:
+![AgentFlight replay timeline](docs/assets/agentflight-replay-timeline.png)
 
-- What changed?
-- Which files are risky?
-- What proof exists?
-- What proof is missing?
-- What should the next agent or reviewer do?
+## 60-Second Workflow
 
-AgentFlight makes those answers local, inspectable, and repeatable without uploading source code or adding cloud infrastructure.
+```bash
+npx agentflight@latest init
+npx agentflight@latest start --task "Add password reset flow"
+
+# Run Codex, Claude Code, Cursor, or your coding agent normally
+
+npx agentflight@latest verify -- npm test
+npx agentflight@latest snapshot --note "Initial implementation verified"
+npx agentflight@latest status
+npx agentflight@latest report
+npx agentflight@latest replay
+npx agentflight@latest resume
+```
+
+What you get:
+
+- `init` creates local `.agentflight/` project files.
+- `start` records the task, git branch, commit, dirty state, package manager, and tool availability.
+- `verify -- npm test` runs the command and stores stdout, stderr, exit code, timing, and pass/fail status.
+- `snapshot --note "..."` records the current git, risk, and proof state as a timeline event.
+- `status` answers what changed, how risky it is, what proof exists, what proof is missing, and what to do next.
+- `report` writes a Markdown proof report for review.
+- `replay` writes a local HTML timeline you can open in a browser.
+- `resume` writes a Codex/Claude-ready prompt for the next safe step.
+
+## Why This Exists
+
+AI coding agents move fast. After a few prompts, you can lose track of:
+
+- what changed
+- whether the agent drifted from the task
+- what was verified
+- what failed
+- what is safe to review
+- how to resume the work later
+
+AgentFlight gives you a local control room for that work. It records the session, captures proof, shows risk, and creates handoff artifacts without uploading source code.
+
+## Sample Outputs
+
+`agentflight status`:
+
+```text
+AgentFlight status
+
+Task:
+Add password reset flow
+
+Changed files:
+3
+
+Risk: medium
+- Dependency, backend, or unknown files changed.
+
+Verification Evidence:
+1 passed, 0 failed
+
+Latest snapshot:
+- Note: Initial implementation verified
+- Risk: medium
+- Changed files: 3
+
+Review readiness: Ready for review
+
+Next action:
+Generate a proof report with agentflight report
+```
+
+`agentflight report`:
+
+```text
+# AgentFlight Proof Report
+
+## Recommendation
+Ready for review
+
+## Verification Evidence
+- passed: npm test
+- stdout: .agentflight/evidence/.../verification-1.stdout.txt
+- stderr: .agentflight/evidence/.../verification-1.stderr.txt
+```
+
+`agentflight replay`:
+
+```text
+Replay saved:
+.agentflight/reports/af-...-replay.html
+
+Timeline:
+session_started -> verification_passed -> snapshot_created -> replay_generated
+```
+
+`agentflight resume`:
+
+```text
+Continue the AgentFlight session for: Add password reset flow
+
+Latest snapshot:
+Initial implementation verified
+
+Verification state:
+1 passed, 0 failed
+
+Guardrails:
+- Stay scoped to the current task.
+- Do not claim completion without proof.
+- Run relevant verification before declaring success.
+```
 
-## How It Works
+## Current Capabilities
+
+The current AgentFlight release supports:
+
+- local session setup
+- active session tracking
+- git branch, commit, dirty state, and changed file detection
+- changed file risk categorisation
+- verification evidence capture with `agentflight verify`
+- session events
+- snapshots with `agentflight snapshot --note "..."`
+- Markdown proof reports
+- self-contained HTML replay timelines
+- resume prompts for Codex, Claude Code, or a human reviewer
+- doctor checks for local setup
+- defensive ProjScan and AgentLoopKit adapters
+- no telemetry, cloud sync, or source upload
+
+## What AgentFlight Is Not
+
+AgentFlight is:
+
+- not a coding agent
+- not a cloud service
+- not a replacement for tests
+- not a security scanner
+- not a CI platform
+- not a code review replacement
+
+Use your coding agent to make changes. Use AgentFlight to understand, verify, replay, and hand off the work.
+
+## How It Works Locally
 
 AgentFlight creates a local `.agentflight/` directory in your repo:
 
@@ -28,65 +168,32 @@ AgentFlight creates a local `.agentflight/` directory in your repo:
 - `reports/` stores Markdown proof reports and HTML replays.
 - `evidence/` stores stdout and stderr from captured verification runs.
 
-Sessions also store an `events` timeline with meaningful moments such as session start, verification attempts, snapshots, and generated artifacts. Reports include filenames and summaries by default, not full source diffs. AgentFlight does not collect telemetry and does not upload source code.
-
-## Quick Start
+Sessions store an `events` timeline with meaningful moments such as session start, verification attempts, snapshots, and generated artifacts. Reports include filenames and summaries by default, not full source diffs.
 
-```bash
-npm install
-npm run build
-npx agentflight init
-npx agentflight start --task "Add example feature"
-npx agentflight status
-npx agentflight verify -- npm test
-npx agentflight snapshot --note "Tests passing locally"
-npx agentflight report
-npx agentflight replay
-npx agentflight resume
-npx agentflight doctor
-```
+Runtime session data is ignored by git by default in this repo:
 
-During local development of this repo, use:
+- `.agentflight/sessions/`
+- `.agentflight/reports/`
+- `.agentflight/evidence/`
+- `.agentflight/current/`
 
-```bash
-npm run agentflight -- init
-npm run agentflight -- start --task "Add example feature"
-```
+`.agentflight/config.json` is intentionally not ignored, so a project can commit its local AgentFlight defaults when useful.
 
 ## Commands
 
 - `agentflight init` initializes `.agentflight/` with safe writes.
 - `agentflight start --task "..."` starts a session and writes the current handoff.
-- `agentflight status` summarizes changed files, risk, verification status, and next action.
+- `agentflight status` summarizes changed files, risk, verification status, snapshots, and next action.
 - `agentflight verify -- <command>` runs a proof command and records stdout/stderr evidence.
 - `agentflight verify` runs commands from `.agentflight/config.json`.
 - `agentflight snapshot --note "..."` records current git, risk, and verification state as a timeline event.
 - `agentflight report` generates a Markdown proof report.
 - `agentflight replay` generates a local self-contained HTML replay.
-- `agentflight resume` prints and saves a Codex/Claude-ready continuation prompt.
+- `agentflight resume` prints and saves a continuation prompt.
 - `agentflight doctor` checks local setup, scripts, tools, config, and current session state.
 
 Future placeholders exist for `upgrade`, `license`, and `login`; AgentFlight Pro/Team is not available yet.
 
-## Example Workflow With Codex Or Claude Code
-
-```bash
-agentflight init
-agentflight start --task "Add password reset flow"
-
-# Run Codex, Claude Code, Cursor, or another coding agent normally.
-
-agentflight status
-agentflight verify -- npm run typecheck
-agentflight verify -- npm test
-agentflight snapshot --note "Implementation and proof complete"
-agentflight report
-agentflight replay
-agentflight resume
-```
-
-Use `agentflight verify -- <command>` when you want AgentFlight to capture proof. The command records exit code, timing, stdout path, and stderr path in the current session, then prints the evidence paths. Use `agentflight snapshot --note "..."` at meaningful milestones so replay and report artifacts show the session timeline. Use the generated report for review and the resume prompt when handing the work to another agent or human.
-
 ## Powered By ProjScan And AgentLoopKit
 
 AgentFlight is powered by two open engines from Baseframe Labs:
@@ -94,7 +201,7 @@ AgentFlight is powered by two open engines from Baseframe Labs:
 - ProjScan provides repo intelligence, risk analysis, codebase understanding, and preflight signals.
 - AgentLoopKit provides task discipline, verification evidence, policies, and handoffs.
 
-This repository dogfoods both tools from day one. See [docs/development/dogfooding.md](docs/development/dogfooding.md).
+This repository dogfoods both tools. See [docs/development/dogfooding.md](docs/development/dogfooding.md).
 
 Strategic architecture:
 
@@ -102,50 +209,22 @@ Strategic architecture:
 - AgentLoopKit: agent workflow discipline engine
 - AgentFlight: commercial and user-facing experience layer
 
-## Local-First And Privacy
-
-AgentFlight runs locally. It does not add telemetry, login, billing, cloud sync, or source upload. The MVP reads git status and package metadata, writes human-readable local artifacts, and calls local or `npx` ProjScan/AgentLoopKit commands with graceful fallbacks.
-
-Runtime session data is ignored by git by default:
-
-- `.agentflight/sessions/`
-- `.agentflight/reports/`
-- `.agentflight/evidence/`
-- `.agentflight/current/`
+## Example Session
 
-`.agentflight/config.json` is intentionally not ignored, so a project can commit its local AgentFlight defaults if that is useful.
+Read [docs/examples/basic-agentflight-session.md](docs/examples/basic-agentflight-session.md) for a short password-reset walkthrough with status, report, replay, and resume artifacts.
 
-## Current Status
+## Roadmap
 
-AgentFlight current package version is `0.3.0`, centered on local session timelines, snapshots, and verification evidence.
+See [docs/roadmap.md](docs/roadmap.md).
 
-Implemented:
+Not built yet:
 
-- TypeScript ESM npm CLI package
-- Safe local initialization
-- Session start and current handoff
-- Status risk summary
-- Markdown proof reports
-- Self-contained HTML replay
-- Resume prompt generation
-- Doctor checks
-- Verification evidence capture with `agentflight verify`
-- Session events and snapshots with `agentflight snapshot`
-- Defensive ProjScan and AgentLoopKit adapters
-- Vitest coverage for core behavior, renderers, adapters, and command workflow
-
-Not implemented:
-
-- Cloud sync
-- Login
-- Billing
+- cloud sync
+- login
+- billing
 - GitHub App
 - Team dashboards
-- Paid feature gates
-
-## Roadmap
-
-See [docs/roadmap.md](docs/roadmap.md).
+- paid feature gates
 
 ## Releases
 

package/docs/development/dogfooding.md

@@ -0,0 +1,173 @@
+# Dogfooding
+
+AgentFlight dogfoods Baseframe Labs tooling from day one.
+
+## ProjScan
+
+Version used during setup: `4.3.1`.
+
+Commands discovered and used:
+
+```bash
+npx projscan@latest --help
+npx projscan@latest --version
+npx projscan@latest init
+npx projscan@latest start --intent "Build AgentFlight, a local-first flight recorder for AI coding agents"
+npx projscan@latest coordinate --format json
+npx projscan@latest preflight --mode before_edit --format json
+npx projscan@latest privacy-check --offline
+npx projscan@latest doctor
+npx projscan@latest start --mode before_commit --intent "Review AgentFlight MVP core commands after package and build setup"
+```
+
+Evidence:
+
+- `projscan init` created `.projscanrc.json`.
+- Initial health was `68/100`, reflecting the fresh repository state.
+- Pre-edit preflight verdict was `proceed`.
+- Offline privacy check confirmed telemetry disabled for the run.
+- Post-core health improved to `94/100` before README completion.
+
+## AgentLoopKit
+
+Version used during setup: `0.28.7`.
+
+Commands discovered and used:
+
+```bash
+npx agentloopkit@latest --help
+npx agentloopkit@latest --version
+npx agentloopkit@latest init
+npx agentloopkit@latest doctor
+npx agentloopkit@latest create-task --title "Build AgentFlight MVP" --type feature ...
+npx agentloopkit@latest task status .agentloop/tasks/2026-06-13-build-agentflight-mvp.md in-progress
+npx agentloopkit@latest status
+```
+
+Evidence:
+
+- AgentLoopKit initialized `.agentloop/`, `AGENTS.md`, `AGENTLOOP.md`, and `agentloop.config.json`.
+- Active task: `.agentloop/tasks/2026-06-13-build-agentflight-mvp.md`.
+- The task is marked `in-progress`.
+- `agentloop.config.json` now maps test, lint, typecheck, build, and format checks to npm scripts.
+
+## AgentFlight Self-Dogfooding
+
+The AgentFlight self-dogfood run was performed after `npm run build` produced `dist/cli.js`.
+
+Commands run:
+
+```bash
+npm run build
+node dist/cli.js init
+node dist/cli.js start --task "Dogfood AgentFlight MVP"
+node dist/cli.js status
+node dist/cli.js report
+node dist/cli.js replay
+node dist/cli.js resume
+node dist/cli.js doctor
+```
+
+Evidence:
+
+- `node dist/cli.js init` initialized `.agentflight/` and detected ProjScan and AgentLoopKit.
+- `node dist/cli.js start --task "Dogfood AgentFlight MVP"` created session `af-20260613-123923-dogfood-agentflight-mvp`.
+- `status` reported `114` changed files and `high` risk because package/dependency and config files changed.
+- `status` was honest that verification evidence was not recorded in the AgentFlight session.
+- `report` wrote `.agentflight/reports/af-20260613-123923-dogfood-agentflight-mvp-proof.md`.
+- `replay` wrote `.agentflight/reports/af-20260613-123923-dogfood-agentflight-mvp-replay.html`.
+- `resume` wrote `.agentflight/current/resume-prompt.md`.
+- `doctor` reported overall `OK`.
+
+Self-dogfooding fixes made:
+
+- Fixed ESM CLI entrypoint detection for repository paths with spaces.
+- Fixed git porcelain parsing so untracked filenames are not truncated.
+- Tuned risk categorisation so Markdown policy docs are not flagged as secret material solely because their filenames mention secrets.
+
+## Final Tooling Evidence
+
+Final commands:
+
+```bash
+npm run verify
+npm run format:check
+npx projscan@latest doctor
+npx projscan@latest preflight --mode before_commit --format json
+npx agentloopkit@latest doctor
+npx agentloopkit@latest verify --task .agentloop/tasks/2026-06-13-build-agentflight-mvp.md
+```
+
+Final results:
+
+- npm verification passed with `14` test files and `36` tests.
+- Formatting check passed.
+- ProjScan reported health `100/100`.
+- ProjScan preflight returned verdict `proceed`.
+- AgentLoopKit verification passed and wrote a local report.
+- AgentLoopKit doctor remained `warn` because the worktree is intentionally dirty during MVP construction and generated runtime artifacts exist locally.
+
+## v0.2.0 In-Progress Dogfooding
+
+The v0.2.0 work uses AgentLoopKit task discipline and ProjScan checkpoints before final release preparation.
+
+Commands run so far:
+
+```bash
+npx agentloopkit@latest create-task --title "Prepare AgentFlight v0.2.0 verification evidence" --type feature ...
+npx projscan@latest start --mode before_edit --intent "Prepare AgentFlight v0.2.0 verification evidence capture"
+npm test -- tests/core/session.test.ts tests/core/verification.test.ts tests/commands/verify.test.ts
+npm test -- tests/commands/evidence-output.test.ts
+npm test -- tests/core/fs-safe.test.ts
+npm run typecheck
+```
+
+Evidence so far:
+
+- AgentLoopKit created `.agentloop/tasks/2026-06-13-prepare-agentflight-v0-2-0-verification-evidence.md`.
+- ProjScan reported health `100/100` before the implementation pass.
+- Red tests captured the missing verification evidence model, missing `verify` command, evidence-blind outputs, and doctor writable-check bug.
+- Targeted implementation tests now pass for verification capture and evidence-aware outputs.
+
+Built CLI self-dogfood commands:
+
+```bash
+npm run build
+node dist/cli.js start --task "Dogfood AgentFlight v0.2.0 verification evidence"
+node dist/cli.js verify -- npm run typecheck
+node dist/cli.js verify -- npm run lint
+node dist/cli.js verify -- npm test
+node dist/cli.js verify -- npm run build
+node dist/cli.js status
+node dist/cli.js report
+node dist/cli.js replay
+node dist/cli.js resume
+node dist/cli.js doctor
+```
+
+Built CLI evidence:
+
+- Session: `af-20260613-132334-dogfood-agentflight-v0-2-0-verification-evidence`.
+- Verification evidence captured: `npm run typecheck`, `npm run lint`, `npm test`, and `npm run build`.
+- `npm test` passed with `16` test files and `49` tests.
+- `status` reported `4 passed, 0 failed`, no configured verification gaps, and `Ready for review`.
+- `report` and `replay` were generated under `.agentflight/reports/`.
+- `resume` included no configured verification gaps and the scoped-work guardrails.
+- `doctor` reported overall `OK`.
+- No v0.2.0 release, tag, or npm publish was performed.
+
+Post-implementation tool checks:
+
+```bash
+npx projscan@latest preflight --mode before_commit --format json
+npx projscan@latest start --mode hardening --intent "Review AgentFlight v0.2.0 verification evidence implementation"
+npx agentloopkit@latest status
+npx agentloopkit@latest verify
+```
+
+Tool evidence:
+
+- ProjScan preflight returned `proceed` with health `100/100`.
+- ProjScan hardening returned health `100/100` with attention requested for the dirty worktree and hotspot review suggestions.
+- AgentLoopKit status found all configured commands and requested verification.
+- AgentLoopKit verification passed and wrote `.agentloop/reports/2026-06-13-15-25-verification-report.md`.

package/docs/development/release.md

@@ -0,0 +1,66 @@
+# Release Process
+
+AgentFlight releases use npm Trusted Publishing from GitHub Actions.
+
+## Why Tags, Not Every Push
+
+npm versions are immutable. Publishing on every push would either fail whenever the version is unchanged or force noisy version churn. AgentFlight verifies every push, but publishes only from version tags.
+
+## npm Trusted Publisher Settings
+
+Configure these values on npmjs.com for the `agentflight` package:
+
+- Publisher: `GitHub Actions`
+- Organization or user: `abhiyoheswaran1`
+- Repository: `AgentFlight`
+- Workflow filename: `release.yml`
+- Environment name: `npm`
+- Allowed actions: `Allow npm publish`
+
+Do not enable `Allow npm stage publish` unless AgentFlight intentionally adopts npm staged releases later.
+
+## Release Checklist
+
+1. Update `package.json` and `package-lock.json` to the new version.
+2. Update `CHANGELOG.md`.
+3. Run verification:
+
+   ```bash
+   npm run verify
+   npm run format:check
+   npm pack --dry-run
+   ```
+
+4. Commit the release:
+
+   ```bash
+   git add .
+   git commit -m "chore: release v0.1.1"
+   ```
+
+5. Tag and push:
+
+   ```bash
+   git tag v0.1.1
+   git push origin main --tags
+   ```
+
+6. Confirm:
+
+   ```bash
+   npm view agentflight version
+   npx --yes agentflight@latest --help
+   ```
+
+## Manual Emergency Publish
+
+Manual publishing is allowed for emergencies while the package is young:
+
+```bash
+npm run verify
+npm run format:check
+npm pack --dry-run
+npm publish --access public
+```
+
+Record any manual publish in `CHANGELOG.md` and `AGENTFLIGHT_DEVLOG.md`.

package/docs/examples/basic-agentflight-session.md

@@ -0,0 +1,164 @@
+# Basic AgentFlight Session
+
+This example shows a fictional local session for adding a password reset flow.
+
+## 1. Start The Flight
+
+```bash
+npx agentflight@latest init
+npx agentflight@latest start --task "Add password reset flow"
+```
+
+AgentFlight records the task, current branch, commit, dirty state, package manager, and available tools. It also writes `.agentflight/current/handoff.md` so the coding agent or human reviewer has a starting point.
+
+## 2. Run The Coding Agent
+
+Run Codex, Claude Code, Cursor, or another coding agent normally.
+
+In this example the agent changes:
+
+```text
+src/password-reset.ts
+tests/password-reset.test.ts
+docs/password-reset.md
+```
+
+## 3. Capture Proof
+
+```bash
+npx agentflight@latest verify -- npm test
+```
+
+AgentFlight runs the command and stores local evidence:
+
+```text
+Verification recorded
+
+Command:
+npm test
+
+Status:
+passed
+
+Evidence:
+stdout: .agentflight/evidence/.../verification-1.stdout.txt
+stderr: .agentflight/evidence/.../verification-1.stderr.txt
+```
+
+If the command fails, AgentFlight records it as failed. It does not turn failed proof into success.
+
+## 4. Create A Snapshot
+
+```bash
+npx agentflight@latest snapshot --note "Initial implementation verified"
+```
+
+The snapshot records:
+
+- branch
+- commit
+- dirty state
+- changed files
+- risk level
+- verification summary
+- note
+
+AgentFlight stores this as a session event. It does not store full code diffs by default.
+
+## 5. Check Status
+
+```bash
+npx agentflight@latest status
+```
+
+Example:
+
+```text
+AgentFlight status
+
+Task:
+Add password reset flow
+
+Changed files:
+3
+
+Changed areas:
+- docs: docs/password-reset.md
+- tests: tests/password-reset.test.ts
+- unknown: src/password-reset.ts
+
+Risk: medium
+- Dependency, backend, or unknown files changed.
+
+Verification Evidence:
+1 passed, 0 failed
+
+Latest snapshot:
+- Note: Initial implementation verified
+- Risk: medium
+- Changed files: 3
+
+Review readiness: Ready for review
+
+Next action:
+Generate a proof report with agentflight report
+```
+
+## 6. Generate Review Artifacts
+
+```bash
+npx agentflight@latest report
+npx agentflight@latest replay
+```
+
+The Markdown report gives a reviewer the task, session metadata, changed files, risk summary, timeline, verification evidence, and recommendation.
+
+The HTML replay gives a browser-friendly timeline:
+
+```text
+session_started
+verification_started
+verification_passed
+snapshot_created
+report_generated
+replay_generated
+```
+
+Both artifacts stay local under `.agentflight/reports/`.
+
+## 7. Resume Safely
+
+```bash
+npx agentflight@latest resume
+```
+
+The resume prompt includes:
+
+- original task
+- current state
+- changed files
+- risk
+- latest snapshot note
+- verification state
+- next recommended action
+- guardrails for the next agent
+
+Example guardrails:
+
+```text
+- Stay scoped to the current task.
+- Do not start unrelated work.
+- Do not claim completion without proof.
+- Run relevant verification before declaring success.
+```
+
+## What This Gives You
+
+By the end of the session, you know:
+
+- what changed
+- how risky it looks
+- what proof exists
+- what proof is missing
+- whether the work is ready for review
+- how to hand it off without losing context

package/docs/roadmap.md

@@ -0,0 +1,49 @@
+# Roadmap
+
+## MVP
+
+- Local CLI package.
+- Safe `.agentflight/` initialization.
+- Session start and current handoff.
+- Changed-file risk summary.
+- Markdown proof report.
+- Self-contained HTML replay.
+- Resume prompt.
+- Doctor checks.
+- Defensive ProjScan and AgentLoopKit adapters.
+- Verification evidence capture.
+- Session events and snapshots.
+
+## Future Free/Open-Core
+
+- Basic local session history.
+- Structured `--json` output.
+- Richer configurable verification command profiles.
+- More precise git diff stats without including full code by default.
+- Timeline filtering and richer local replay navigation.
+
+## Future Pro
+
+- Searchable local session history.
+- Advanced replay exports.
+- Multi-repo workspace.
+- Custom report themes.
+- Advanced policy packs.
+- Agent mistake analytics.
+
+## Future Team
+
+- GitHub PR comments.
+- Shared policies.
+- Team dashboard.
+- Audit trail.
+- Required verification gates.
+- Slack, Linear, and Jira integrations.
+
+## Future Enterprise
+
+- Self-hosted deployment.
+- SSO.
+- Compliance exports.
+- Custom risk rules.
+- Support.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentflight",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Local-first flight recorder for AI coding agents.",
   "type": "module",
   "main": "./dist/cli.js",
@@ -11,6 +11,12 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
+    "docs/assets/agentflight-replay-timeline.png",
+    "docs/development/dogfooding.md",
+    "docs/development/release.md",
+    "docs/examples/basic-agentflight-session.md",
+    "docs/roadmap.md",
     "LICENSE"
   ],
   "scripts": {
@@ -34,8 +40,13 @@
   "keywords": [
     "ai",
     "coding-agents",
+    "codex",
+    "claude-code",
     "cli",
     "developer-tools",
+    "agentic-coding",
+    "verification",
+    "code-review",
     "local-first",
     "observability"
   ],