@hasna/todos 0.11.43 → 0.11.45

package/README.md

@@ -33,6 +33,25 @@ MCP clients can use `bootstrap_project` for the same local-only workflow. The
 command is idempotent, so running it again refreshes machine-local paths without
 duplicating projects, task lists, or source records.
 
+## Local Machine Topology
+
+Machine registry state stays in local SQLite. Machines can record identity,
+last-seen heartbeats, workspace paths, git roots, and user-provided Tailscale
+or LAN addresses without probing the network:
+
+```bash
+todos machines register spark01 --ssh hasna@spark01 --tailscale-name spark01.tailnet --tailscale-ip 100.64.0.10 --lan-address 192.168.8.10 --workspace ~/workspace
+todos machines heartbeat spark01 --workspace ~/workspace
+todos machines topology --json
+todos projects-path set <project-id> ~/workspace/my-project
+```
+
+`todos machines topology` reports stale machines, missing local path overrides,
+missing local paths, and projects whose machine-local paths differ across
+registered machines. MCP clients can use `machines_register`,
+`machines_heartbeat`, `machines_topology`, and `machines_list` for the same
+offline diagnostics.
+
 ## Local Workspace Trust
 
 Workspace trust profiles live in `~/.hasna/todos/config.json` and keep agent
@@ -53,6 +72,28 @@ MCP clients can use `set_workspace_trust`, `get_workspace_trust`,
 return deterministic JSON showing whether an action is allowed, why it needs a
 prompt, and which environment keys should be redacted.
 
+Secret safety uses the same local config. Add project-specific regexes and
+metadata keys with `todos redaction add --pattern <regex> --key <name>`, then
+scan text or files with `todos redaction scan` without printing matched values.
+Comments, local run evidence, and bridge exports are redacted before storage or
+sharing. MCP clients can use `get_secret_safety`, `set_secret_safety`, and
+`scan_secret_text`.
+
+Retention cleanup is also local and dry-run-first. Use it to prune old comments,
+run ledgers, verification evidence, and expired stored artifact files by age,
+project, task status, and run status. Reports return counts, IDs, and
+content-addressed artifact paths only; they do not include raw comments,
+commands, output summaries, artifact source paths, or secret-like values.
+Destructive cleanup requires the exact confirmation string shown by the preview:
+
+```bash
+todos retention cleanup --older-than-days 30 --project <project-id> --task-status completed --json
+todos retention cleanup --older-than-days 30 --project <project-id> --task-status completed --apply --confirm delete-local-retention-data --json
+```
+
+MCP clients can use `preview_retention_cleanup` and
+`apply_retention_cleanup` for the same offline workflow.
+
 ## Local Runner Sandboxes
 
 Runner sandbox profiles also live in local config. They declare the commands a
@@ -73,6 +114,74 @@ MCP clients can use `set_runner_sandbox_profile`,
 are local-only and compose with workspace trust checks, so command and write
 decisions stay auditable before an agent records run evidence.
 
+## Local Project Knowledge
+
+Project knowledge records keep agent decisions, architecture notes, tradeoffs,
+and task-linked context snapshots in local SQLite. They are searchable,
+exportable, redacted on output, and available to MCP clients without hosted
+services:
+
+```bash
+todos knowledge add decision "Use local SQLite" --decision "Keep OSS knowledge local" --rationale "Agents need offline project memory" --task <task-id> --tag architecture --json
+todos knowledge snapshot --summary "Parser fix is ready for verification" --task <task-id> --agent codex --file src/parser.ts --json
+todos knowledge search "offline project memory" --json
+todos knowledge export --format markdown
+```
+
+MCP clients can use `create_knowledge_record`, `create_knowledge_snapshot`,
+`list_knowledge_records`, `search_knowledge_records`, and
+`export_knowledge_records`. The MCP server also publishes `todos://knowledge`
+and `todos://knowledge/decisions` resources for agent context refreshes.
+
+## Local Extension Registry
+
+Extensions are installed from local manifests, directories with
+`todos.extension.json`, or offline JSON bundles. The registry validates the
+manifest shape, checks `@hasna/todos` compatibility ranges, records requested
+permissions, runs CLI/MCP compatibility checks, dry-runs declared commands
+through the local runner sandbox, verifies optional source checksums or detached
+signatures, and stores trust state in local config only:
+
+```bash
+todos extensions inspect ./todos.extension.json --json
+todos extensions compat ./todos.extension.json --json
+todos extensions install ./todos.extension.json --checksum sha256:... --trust --json
+todos extensions verify ./bundle.todos-extension.json --signature <signature> --public-key "$PUBLIC_KEY"
+todos extensions list
+todos extensions remove my-extension
+```
+
+Unsigned extensions are allowed but installed as local records with warnings.
+Without `--trust`, installs remain in `needs_review` so agents can discover
+custom commands, MCP tools, hooks, and permissions without treating them as
+approved. MCP clients can use `inspect_local_extension`,
+`test_local_extension_compatibility`, `install_local_extension`,
+`list_local_extensions`, and `remove_local_extension` for the same offline
+workflow.
+
+## Local Workflow Prompts
+
+The package includes bundled MCP prompts for common agent workflows:
+`goal_planning`, `task_claiming`, `review`, `verification`, `handoff`,
+`release_prep`, `import_triage`, and `incident_response`. They are static,
+local-only prompt resources that can be listed or rendered without a model call:
+
+```bash
+todos workflows list
+todos workflows show goal_planning --objective "Ship release" --task 1234abcd --json
+todos workflows export --format markdown
+```
+
+MCP clients can discover the same catalog at `todos://workflow-prompts` and call
+the matching prompt by ID. Prompt output is deterministic and is intended for
+Codex, Claude Code, Takumi, and other agent-native clients that need reusable
+local guidance for planning, claiming, review, verification, handoff, release,
+triage, and incident workflows.
+
+Agent setup recipes for MCP registration, `/goal` planning, task
+claim/update/complete loops, evidence comments, and no-cloud verification live
+in [docs/agent-adapters.md](docs/agent-adapters.md).
+
 ## Local Policy Packs
 
 Policy packs are project-local done gates for agents. They validate task status,
@@ -99,6 +208,32 @@ MCP clients can use `set_policy_pack`, `list_policy_packs`,
 Validation is a dry local read of recorded task evidence; it never calls a
 hosted enforcement service.
 
+## Local Source TODO Index
+
+Source extraction scans local code for `TODO`, `FIXME`, `HACK`, `BUG`, `XXX`,
+and `NOTE` comments, respects `.gitignore` plus explicit excludes, records
+source files, line anchors, nearby symbols, and stable dedupe fingerprints, and
+can run as a finite local watcher:
+
+```bash
+todos extract . --dry-run --index --json
+todos extract . --exclude fixtures/** --tags tech-debt
+todos extract-watch . --dry-run --max-runs 1 --json
+```
+
+Created tasks are tagged with `extracted` and linked back to the source file.
+MCP clients can call `extract_todos` and `watch_source_todos` for the same
+offline workflow; no hosted code search, cloud sync, or telemetry is used.
+
+## Local Editor Integrations
+
+Editor recipes live in `docs/editor-integrations.md` and
+`examples/editor-integrations/`. They include VS Code task definitions,
+JetBrains external tool recipes, Neovim Lua helpers, a shell statusline snippet,
+and a Bun task picker. Every example uses only `todos` CLI JSON output or MCP
+tool names, so editors can claim tasks, inspect local queues, build context
+packs, and link source files without importing private modules or hosted code.
+
 ## Task Contracts and Reviews
 
 Task contracts make acceptance criteria, required verification, expected
@@ -144,6 +279,50 @@ MCP clients can use `require_approval_gate`, `approve_approval_gate`,
 `list_approval_gates`. Gate events are written to task audit history and, when
 a run is linked, to the local run ledger.
 
+## Local Review Queues
+
+Review queues turn local task review into an explicit agent workflow: request a
+review, route it to a queue, claim it, return it with changes, reopen it, or
+approve it. Routing rules live in local config and can match tags, priorities,
+and projects without hosted users, orgs, or cloud services:
+
+```bash
+todos reviews rules set security --queue security-review --reviewers reviewer --tags security --priorities high
+todos reviews request <task-id> --requester codex --reason "security-sensitive change"
+todos reviews claim <task-id> --reviewer reviewer
+todos reviews return <task-id> --reviewer reviewer --changes "Add tests;Record verification"
+todos reviews approve <task-id> --reviewer reviewer
+todos reviews list --queue security-review --json
+```
+
+MCP clients can use `list_review_queue`, `request_review_queue`,
+`claim_review_item`, `return_review_item`, `approve_review_item`,
+`reopen_review_item`, `set_review_routing_rule`, `list_review_routing_rules`,
+and `remove_review_routing_rule`. Queue transitions are written to audit
+history and emitted to local event hooks as `review.requested`,
+`review.claimed`, `review.returned`, `review.approved`, and `review.reopened`.
+
+## Local Roadmaps
+
+Roadmaps group local tasks, plans, runs, milestones, and release labels into a
+portable planning view. They live in local config, summarize dependency
+readiness from the task graph, and export deterministic JSON or Markdown
+bundles:
+
+```bash
+todos roadmaps create "Public package launch" --release v1 --json
+todos roadmaps milestones add <roadmap-id> "Docs and examples" --tasks <task-id> --due 2026-06-01 --release v1 --json
+todos roadmaps releases set <roadmap-id> v1 --milestones <milestone-id> --release-version 1.0.0 --json
+todos roadmaps show <roadmap-id> --format markdown
+todos roadmaps export <roadmap-id> --out roadmap.json
+todos roadmaps import roadmap.json --apply --json
+```
+
+MCP clients can use `create_roadmap`, `list_roadmaps`,
+`get_roadmap_summary`, `update_roadmap`, `delete_roadmap`,
+`create_milestone`, `update_milestone`, `delete_milestone`,
+`set_release_group`, `export_roadmap`, and `import_roadmap`.
+
 ## Local Event Hooks
 
 Event hooks are local subscriptions for task, plan, run, approval, import, and
@@ -162,6 +341,28 @@ MCP clients can use `set_local_event_hook`, `list_local_event_hooks`,
 `test_local_event_hook`, and `remove_local_event_hook`. Hook delivery is
 local-only; it does not call hosted webhooks or cloud automation services.
 
+## Local Terminal Notifications
+
+Terminal notification rules are local watch rules for agents that want concise
+event signals in a shell, tmux pane, or editor terminal. Rules match task, run,
+plan, approval, import, and export events by severity, agent, project, priority,
+status, and payload text, then render deterministic line or JSON notifications:
+
+```bash
+todos terminal-notifications set blocked --event task.blocked,task.failed --min-severity warning --agent codex --priority high --contains deploy --bell
+todos terminal-notifications set due --event task.due,task.sla_breached --min-severity warning --quiet-hours 22:00-07:00
+todos notifications check --emit-hooks --terminal --quiet-hours 22:00-07:00 --json
+todos terminal-notifications test blocked --event task.failed --payload '{"id":"demo","title":"Deploy failed","agent_id":"codex","priority":"high"}' --json
+todos terminal-notifications list --json
+```
+
+MCP clients can use `set_terminal_notification_rule`,
+`list_terminal_notification_rules`, `test_terminal_notification_rule`,
+`evaluate_terminal_watch_rules`, `check_local_notifications`, and
+`remove_terminal_notification_rule`. Notifications are evaluated from local
+event payloads, can respect quiet hours, and do not require a desktop
+notification daemon, hosted queue, or cloud webhook service.
+
 ## Local Encryption Profiles
 
 Encryption profiles are optional local config entries for sensitive fields and
@@ -207,6 +408,24 @@ MCP clients can use `set_agent_run_adapter`, `queue_agent_run`,
 `cancel_agent_run_dispatch`, and `retry_agent_run_dispatch`. These commands
 launch only local processes and do not call hosted runners.
 
+## Local Agent Replay Simulation
+
+Replay simulation turns a recorded context pack or run fixture into a
+deterministic dry-run snapshot without opening the project database or mutating
+tasks. Use it to debug agent plans, verification commands, task transitions,
+failures, touched files, artifacts, and approval decisions offline:
+
+```bash
+todos context-pack <task-id> --format json > replay.json
+todos runs simulate replay.json --agent codex --scenario parser-failure --json
+todos runs simulate replay.json --format markdown
+```
+
+MCP clients can use `simulate_agent_replay` with a fixture object and optional
+`agent_id` or `scenario`. The simulator redacts fixture values before hashing
+or rendering, reports `mutates_database: false`, and emits stable command,
+approval, failure, file, artifact, and warning summaries for local debugging.
+
 ## Local Dependency Workflows
 
 Dependencies are stored in the local SQLite database and never require hosted
@@ -225,6 +444,56 @@ The same workflow is available to MCP clients through
 blocked pending tasks, and startup schema repair recreates the local dependency
 table for older databases.
 
+## Local Risk Register And Health
+
+Risks are stored in local SQLite and can be linked to projects, plans, or tasks
+with an owner, mitigation, due date, severity, probability, tags, and metadata:
+
+```bash
+todos risks add "Release blocker" --plan 1234abcd --severity high --owner codex --mitigation "Ship fallback" --json
+todos risks list --plan 1234abcd --json
+todos risks score --plan 1234abcd --json
+todos risks export --project my-project --json
+```
+
+Health reports score a plan or project from local evidence only: blocked tasks,
+overdue open work, failed verification records, failed run ledgers, dependency
+depth, and open risks. MCP clients get the same surface through `create_risk`,
+`list_risks`, `update_risk`, `close_risk`, `score_plan_health`,
+`score_project_health`, and `export_risk_register`.
+
+## Local Retrospectives
+
+Retrospectives summarize a project or plan using local evidence: completed
+plans, missed estimates, repeated blockers, failed verification records,
+lessons learned, and suggested follow-up tasks.
+
+```bash
+todos retrospectives create --plan 1234abcd --json
+todos retrospectives list --project my-project --json
+todos retrospectives export --plan 1234abcd --format markdown
+```
+
+Use `--create-followups` to create the suggested follow-up tasks locally. MCP
+clients get the same reports through `create_retrospective`,
+`list_retrospectives`, and `export_retrospectives`.
+
+## Local Agent Reliability Scorecards
+
+Reliability scorecards summarize each agent from local evidence only: completed
+and failed tasks, passed and failed verification records, failed run ledgers,
+stale task/resource locks, retry history, and handoff quality.
+
+```bash
+todos reliability show codex --json
+todos reliability list --project my-project --json
+todos reliability export --format markdown
+```
+
+MCP clients get the same summaries through `get_agent_reliability_scorecard`,
+`export_agent_reliability_scorecards`, and the `todos://agents/reliability`
+resource.
+
 ## Local Agent Locking
 
 Task claims and locks are local SQLite leases. Agents can claim the next ready
@@ -293,6 +562,56 @@ MCP clients get the same local data through `link_task_to_commit`,
 `add_task_verification`, and `get_task_traceability`, so agents can explain
 which task changed a commit, branch, PR, file, or verification command.
 
+## Local Mention Resolution
+
+Agents can resolve task references before adding them to descriptions, plans, or
+handoffs. The resolver validates local files and line anchors, scans local source
+declarations for symbols, checks local git commits, branches, and fetched pull
+request refs, and resolves plans, runs, tasks, and agents from the local SQLite
+state:
+
+```bash
+todos references resolve file:src/index.ts:12 symbol:createTask branch:main --json
+todos refs resolve plan:release run:abc123 agent:marcus --workspace .
+```
+
+The JSON output includes canonical reference keys and validated backlinks such
+as `file:src/index.ts:12`, `symbol:createTask@src/index.ts:40`, `commit:<sha>`,
+`plan:<id>`, and `run:<id>`. MCP clients can call `resolve_mentions` for the
+same local-only report; pull request refs are validated only when present in
+local git refs, and the resolver never calls hosted code search.
+
+## Local Branch-Safe Work Plans
+
+Before an agent starts a branch, it can ask for a local branch work plan that
+checks the task or plan scope, planned files, active file conflicts, local git
+status, and suggested branch/traceability commands:
+
+```bash
+todos branch-plan 1234abcd --branch task/parser-fix --path src/parser.ts --json
+todos branch-plan --plan <plan-id> --branch task/release-plan --no-git-status --json
+```
+
+MCP clients can call `create_branch_work_plan` with `task_id` or `plan_id`.
+The result is local-only: it does not create a branch, fetch from a remote, or
+contact hosted code review services. Agents can inspect `safe_to_start`,
+`conflicts`, `reasons`, and `commands` before running any git operation.
+
+## Local Release Notes
+
+Generate changelogs from completed local tasks and their linked plans, commits,
+verification records, breaking-change notes, and migration notes:
+
+```bash
+todos release-notes --project . --format markdown
+todos release-notes --tag release --since 2026-01-01T00:00:00.000Z --json
+```
+
+Tasks can add release metadata through `metadata.breaking_change`,
+`metadata.breaking_changes`, `metadata.migration_note`, or
+`metadata.migration_notes`. MCP clients use `generate_release_notes` for the
+same deterministic JSON or Markdown output without hosted release tooling.
+
 ## Local Verification Providers
 
 Optional provider adapters let agents standardize local verification without a
@@ -327,13 +646,19 @@ todos handoff --unread-for claude --json
 todos handoff --read <handoff-id> --json
 todos handoff --ack <handoff-id> --agent claude --json
 todos handoff --recover --agent codex --session codex-42 --json
+todos handoff --export <handoff-id> --output handoff.json --json
+todos handoff --import handoff.json --json
+todos handoff --import handoff.json --apply --json
 ```
 
 MCP clients can use `create_handoff`, `list_handoffs`, `read_handoff`,
-`acknowledge_handoff`, `recover_stale_session_handoff`, and
-`get_latest_handoff`. Recovery handoffs inspect local in-progress tasks, file
-links, and run evidence for the agent/session and create a deterministic
-continuation packet; no hosted queue or cloud service is involved.
+`export_handoff`, `import_handoff`, `acknowledge_handoff`,
+`recover_stale_session_handoff`, and `get_latest_handoff`. Recovery handoffs
+inspect local in-progress tasks, file links, and run evidence for the
+agent/session and create a deterministic continuation packet; no hosted queue
+or cloud service is involved. Handoff imports default to a dry-run preview;
+`--apply` writes the local handoff and preserves per-agent acknowledgement
+state.
 
 ## Local Run Ledger
 
@@ -360,6 +685,81 @@ metadata, redaction status, retention metadata, and metadata-only fallback when
 the original path is unavailable. Use `--no-store` to record only artifact
 metadata.
 
+## Local Time Tracking
+
+Manual time logs and focus sessions stay in the local SQLite database and roll
+up into `task.actual_minutes` for planning and retrospectives:
+
+```bash
+todos time log <task-id> 25 --agent codex --notes "reviewed parser"
+SESSION=$(todos time start <task-id> --agent codex --idle-after 30 --json | jq -r .id)
+todos time pause "$SESSION"
+todos time resume "$SESSION"
+todos time stop "$SESSION" --notes "implemented and tested"
+todos time report --include-open --json
+```
+
+Focus sessions can be linked to tasks, plans, or run ledgers. Stopping a
+completed task-linked session writes a time log with the session id and run id,
+then recalculates actual minutes from all local logs. `todos time idle` and the
+`get_idle_focus_prompts` MCP tool report active sessions that exceeded their
+local idle threshold; no desktop notification service or hosted telemetry is
+required.
+
+## Local Capacity Forecasts
+
+Capacity profiles give agents a local way to forecast whether a project or plan
+is realistic from task estimates, actual minutes, due dates, and available
+minutes per day:
+
+```bash
+todos capacity set codex --minutes-per-day 240 --days 1,2,3,4,5 --json
+todos capacity forecast --plan <plan-id> --agent codex --start-date 2026-06-01 --json
+todos capacity forecast --project <project-id> --format markdown
+todos capacity list --json
+```
+
+Forecasts report remaining estimated minutes, logged actual minutes, forecast
+work days, projected completion date, missing estimates, overdue open tasks,
+and risk flags. MCP clients use `set_capacity_profile`,
+`list_capacity_profiles`, `remove_capacity_profile`, and
+`get_planning_forecast`.
+
+## Local Audit Ledger
+
+Audit ledger checkpoints hash local evidence into a deterministic chain so an
+agent can seal task, run, verification, approval, and handoff records and verify
+later that the local evidence still matches:
+
+```bash
+todos audit-ledger show --task <task-id> --entries --json
+todos audit-ledger seal release-checkpoint --task <task-id> --json
+todos audit-ledger verify release-checkpoint --json
+todos audit-ledger list --json
+```
+
+The ledger stores only local checkpoint metadata in config. It does not call a
+hosted service and it does not claim to prevent local deletion; it detects
+changes against a previously sealed root hash. MCP clients use
+`get_audit_ledger`, `seal_audit_ledger`, `list_audit_ledger_checkpoints`, and
+`verify_audit_ledger`.
+
+## Release Compatibility
+
+Release compatibility checks give agents a local dry-run report before publish
+or update work. They verify the package stays `@hasna/todos`, public, pointed at
+`hasna/todos`, export-stable, migration-compatible from recent local schema
+levels, and ready for Bun global install smoke tests:
+
+```bash
+todos release-compat check --json
+todos release-compat check --format markdown
+```
+
+The report also includes changelog surfaces and rollback commands. MCP clients
+use `check_release_compatibility` for the same `release_compatibility_report`
+JSON contract.
+
 ## Local Activity Timeline
 
 The timeline command gives agents one ordered, redacted view of local comments,
@@ -377,6 +777,31 @@ local SQLite store and local bridge exports already include the underlying
 comments, runs, run evidence, files, commits, and verification records needed to
 rebuild the same timeline after import.
 
+## Local Scheduling and SLA Escalation
+
+Tasks can carry local due dates, recurrence rules, and SLA thresholds without a
+hosted scheduler. Recurring tasks spawn their next local task from the previous
+scheduled due date, preserving cadence even when completion happens late:
+
+```bash
+todos add "Weekly review" --due 2026-06-01 --recurrence "every week" --sla-minutes 120 --json
+todos update <task-id> --due 2026-06-08 --recurrence "every monday" --sla 90 --json
+todos overdue --json
+todos sla --json
+todos notifications check --due-within-minutes 60 --stale-minutes 30 --terminal --json
+```
+
+`todos overdue` returns unfinished tasks past `due_at`. `todos sla` returns
+unfinished tasks that are past `due_at` or whose `sla_minutes` threshold has
+elapsed from `started_at` when present, otherwise `created_at`. MCP clients use
+`create_task` and `update_task` with `deadline`, `recurrence_rule`, and
+`sla_minutes`, and can call `get_sla_breaches` for the same local escalation
+view. `todos notifications check` turns due, due-soon, SLA, stale task,
+completed run, and local reminder records into redacted local alerts; it can
+emit configured file/socket/script/stdout event hooks, evaluate terminal watch
+rules, and suppress delivery during quiet hours without contacting an external
+notification service.
+
 ## Local Task Fields
 
 Tasks can carry local labels, severity, owner, area, and custom metadata while
@@ -393,6 +818,24 @@ for existing filters, and the metadata is included in local bridge exports.
 MCP clients use `get_task_fields`, `set_task_fields`, and
 `query_tasks_by_fields` for the same local-only workflow.
 
+## Local Calendar And ICS
+
+Calendar events are derived from local tasks, SLA thresholds, run ledgers, and
+authored local reminders, milestones, or work blocks. Exported ICS files are
+deterministic and can be redacted before sharing:
+
+```bash
+todos calendar list --from 2026-06-01T00:00:00.000Z --json
+todos calendar add "Release milestone" --kind milestone --start 2026-06-01T09:00:00.000Z --json
+todos calendar export --redact --out todos.ics
+todos calendar import team.ics --json
+```
+
+Recurring task rules are mapped into ICS `RRULE` values when possible, and task
+SLA thresholds appear as local calendar events without any Google Calendar,
+hosted API, or cloud sync dependency. MCP clients use `create_calendar_item`,
+`list_calendar_events`, `export_calendar_ics`, and `import_calendar_ics`.
+
 ## Local Saved Search Views
 
 Saved views are local SQLite records for repeatable task, project, plan, run,
@@ -413,6 +856,26 @@ preserve the filters without any hosted service. MCP clients use
 `save_search_view`, `list_search_views`, `run_search_view`, and
 `delete_search_view`.
 
+## Local Kanban Boards
+
+Boards are local SQLite records for task and plan workflow views. Lanes map to
+workflow statuses, can carry WIP limits, and render blocked/ready badges for
+agent planning:
+
+```bash
+todos board create local-flow --lane "Ready=pending" "Doing=in_progress:3" --json
+todos board show local-flow
+todos board tui local-flow --json
+todos board move local-flow <task-id> --lane Doing --json
+todos board export local-flow --json
+```
+
+Task boards render tasks; plan boards use `--scope plans` and render plans by
+plan status. Board snapshots include terminal key bindings for keyboard/TUI
+clients, but the state is still just local data and can be exported or imported
+without a hosted web UI. MCP clients use `create_board`, `list_boards`,
+`get_board_snapshot`, and `move_board_card`.
+
 ## Local Duplicate Detection
 
 Agents can scan local tasks for likely duplicates from imported issue URLs,
@@ -441,11 +904,43 @@ traceability, and run-ledger evidence from the local SQLite database only:
 todos context-pack <task-id> --profile codex --format markdown
 todos context-pack <task-id> --profile claude --format json
 todos context-pack <task-id> --profile takumi --run <run-id> --comments 12 --files 40
+todos context-pack <task-id> --profile codex --token-budget 1800 --exclude runs --compact
 ```
 
 MCP clients can call `build_agent_context_pack` with the same limits and choose
-JSON or Markdown output. Long text and evidence are redacted and size-limited,
-and stale or omitted local data is surfaced as warnings in the pack.
+JSON, Markdown, compact JSON, or compact Markdown output. Long text and evidence
+are redacted and size-limited, and stale or omitted local data is surfaced as
+warnings in the pack.
+
+Budget-aware context packing is local and deterministic. Use `--token-budget`
+for an approximate character-based token budget, `--include` or `--exclude` to
+shape sections, and `--summary-chars` to cap the redacted summaries generated
+for omitted evidence. When the pack is too large, lower-priority evidence such
+as runs, traceability, comments, files, dependencies, and plan context is
+summarized in a stable `context_budget` block so agents still know what was left
+out.
+
+## Local External Issue Imports
+
+Import issue records from pasted JSON, files, stdin, or explicit URLs without
+depending on any hosted Hasna service. Imports default to a dry-run preview;
+`--apply` creates local tasks, stores redacted source metadata, creates linked
+inbox evidence, and skips existing tasks that already have the same source URL,
+GitHub owner/repo/number, or external issue key:
+
+```bash
+todos issues import --file issues.json --provider github --json
+todos issues import --file issues.json --provider github --apply --json
+todos issues import --provider linear --apply < linear-export.json
+todos issues import "Title: Fix parser\nURL: https://tracker.example/BUG-42" --apply --json
+```
+
+GitHub, Linear, Jira, and plain URL records are normalized into local task
+metadata and tags. Network access is off unless `--allow-network` is passed; for
+GitHub that explicitly shells out through the authenticated `gh` CLI, while
+offline files and pasted exports work without tokens. MCP clients use
+`import_external_issues` with the same dry-run, apply, inbox, and dedupe
+controls.
 
 ## Local Inbox Intake
 
@@ -456,12 +951,76 @@ deduped inbox and create a linked task:
 todos inbox add "bun test failed: parser regression" --source-type ci_log
 todos inbox add --file /tmp/ci.log --source-name "local CI"
 todos inbox add https://github.com/hasna/todos/issues/42 --source-url https://github.com/hasna/todos/issues/42
+todos inbox parse "Add task fix parser priority high @codex #cli due tomorrow" --json
+todos inbox parse --file plan-notes.txt --apply --json
 todos inbox git --diff
 todos inbox list
 ```
 
 Inbox bodies and metadata are redacted before storage. Repeated input resolves
-to the existing inbox item instead of creating duplicate tasks.
+to the existing inbox item instead of creating duplicate tasks. Natural-language
+intake parsing is deterministic and local-only; it defaults to a dry-run preview
+and creates projects, plans, tasks, dependencies, and acceptance criteria only
+with `--apply`.
+
+## Bundled Onboarding Fixtures
+
+The package ships deterministic local demo fixtures for first-run onboarding and
+agent integration tests. The default `agent-project-demo` fixture shows the
+simple flow used by the public demo: create a project, add todos, generate a
+plan, run an agent, record command/artifact/verification evidence, review the
+remaining task, and prove export/import with the local bridge bundle.
+
+```bash
+todos onboarding --json
+todos onboarding --show agent-project-demo > agent-project-demo.bridge.json
+todos onboarding --import agent-project-demo --json
+todos onboarding --import agent-project-demo --apply
+```
+
+Fixtures are bundled with `@hasna/todos`, redacted, offline, and local-only.
+Imports default to dry-run mode and use the same bridge importer as normal
+exports, so CLI, MCP, and SDK consumers can test against the exact project,
+tasks, plan, run ledger, evidence, saved view, and board records.
+
+MCP clients can read `todos://onboarding/fixtures` or
+`todos://onboarding/demo`, then use `list_onboarding_fixtures`,
+`get_onboarding_fixture`, and `import_onboarding_fixture`.
+
+## Local Agent Snapshots
+
+Agents can refresh context through stable local snapshots for projects, tasks,
+plans, runs, dependencies, activity events, and evidence. Snapshots are
+redacted, deterministic, and include cursors plus fingerprints so MCP clients
+can poll for changes without a hosted event stream.
+
+```bash
+todos snapshots --json
+todos snapshots --show tasks --json
+todos snapshots --show evidence --markdown
+todos snapshots --poll --types tasks,evidence --since 2026-05-22T00:00:00.000Z --json
+```
+
+MCP clients can read `todos://snapshots/catalog` and
+`todos://snapshots/tasks` through `todos://snapshots/evidence`, or use
+`list_local_snapshots`, `get_local_snapshot`, and `poll_local_snapshots` for
+JSON or Markdown payloads.
+
+## SDK Integration Fixtures
+
+Downstream SDK, CLI JSON, MCP, and agent-adapter tests can generate a complete
+local fixture pack from the bundled demo project:
+
+```bash
+todos sdk-fixtures --json
+todos sdk-fixtures --show > sdk-fixture-pack.json
+todos sdk-fixtures --write .todos/sdk-integrations --json
+```
+
+The pack includes a local bridge fixture, stable JSON contract snapshots,
+project/task/plan/run/evidence snapshots, and a context pack. Copy-pasteable
+examples live in `examples/sdk-integrations/`, and the full guide is in
+`docs/sdk-integrations.md`.
 
 ## Local Bridge Import/Export
 
@@ -478,10 +1037,10 @@ todos bridge-import todos-bridge.json --apply --resolve-conflicts
 
 Bridge bundles include local projects, task lists, plans, tasks, dependencies,
 comments, run ledgers, command evidence, file evidence, artifacts, stored
-artifact contents, commits, refs, and verification records. Imports default to
-dry-run mode and report conflicts before writing. The package does not upload
-bundles or call hosted services; any hosted sync must consume the exported JSON
-explicitly.
+artifact contents, commits, refs, verification records, saved views, local board
+definitions, and local calendar items. Imports default to dry-run mode and
+report conflicts before writing. The package does not upload bundles or call
+hosted services; any hosted sync must consume the exported JSON explicitly.
 
 For multi-machine local work, `--resolve-conflicts` performs a safe task merge
 instead of overwriting local edits. It fills blank local fields from the
@@ -595,6 +1154,9 @@ Release checks enforce that boundary before publishing:
 - local runtime tests use a no-network fixture for local-only workflows
 - `bun run verify:release` builds, packs, validates provenance, and runs a clean
   Bun global install smoke test from the candidate tarball
+- the install smoke plan itself is covered by tests: it installs only with Bun,
+  verifies `todos`, `todos-mcp`, and `todos-serve`, and rejects private or
+  hosted endpoint references
 
 ## License