@aquex/cmos-mcp 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+All notable changes to cmos-mcp are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 1.0.0 — 2026-05-08
+
+First public release. Published to npm as [`@aquex/cmos-mcp`](https://www.npmjs.com/package/@aquex/cmos-mcp). Local-first by default; the hosted dashboard at [cmos.aquex.ai](https://cmos.aquex.ai) is optional.
+
+cmos-mcp has been in continuous internal development since November 2025. v1.0 marks the point where the protocol surface, auth model, attribution boundary, and context layer are stable enough to draw a line and version against.
+
+### Highlights
+
+- 14 consolidated MCP tools with action parameters, structured error envelopes, and a uniform cold-start payload.
+- Device-code auth (RFC 8628) with a per-machine credential store. No shared secrets, no env-var token paste.
+- Sender attribution rebuilt around an explicit boundary module — the previous implementation could mis-attribute messages between sibling projects.
+- Context v2: project identity at Layer 0, FTS5 retrieval, and a versioned blob migration system. Master context typically sits under 20KB instead of 80KB+.
+- Staleness signal hygiene: auto-reaffirm-on-cite, evergreen flag, and a saner threshold default.
+- Hosted dashboard is opt-in. Set `CMOS_DASHBOARD_URL` to connect; leave it unset to stay fully local.
+
+### Auth (originally shipped Sprints 57–59)
+
+- **`cmos_auth` tool** with `login_init`, `login_complete`, `logout`, `rotate`, `revoke`, `list`, `reissue`. Agents can run the full credential lifecycle without leaving the conversation.
+- **Two-call device-code login** (`login_init` + `login_complete`) for IDE MCP hosts where stderr prompts are invisible. The legacy single-call `login` action is kept for terminal callers.
+- **Per-machine credential store** at `~/.config/cmos-mcp/credentials.json`. Atomic writes, mode 0600, two trees (`userScopedKeys` and `projectKeys`) with `parentKeyId` linkage. Honors `CMOS_CONFIG_DIR`.
+- **Auto-issue capture on register** — `POST /api/projects/register` returns `{key, keyId, label}` on first registration; cmos-mcp persists it transparently. Lost project keys recover on next startup via `runStartupProjectKeyRecovery()`.
+- **Symmetric logout** — revokes the current user-scoped key on the dashboard and clears the local row in one atomic operation. Project-scoped child keys are deliberately not cascade-revoked.
+- **Scope-aware unified revoke** — `POST /api/keys/:keyId/revoke` covers both user-scoped and project-scoped rows; the MCP determines scope locally before calling so cleanup routes correctly.
+- **`whoami` + `authState` on onboard** — every cold-start payload reports `identitySource`, `authTier`, project/user keys, and last delivery observed. Surfaces `cmos_auth` suggestedActions when credentials drift.
+- **Legacy-auth WARN** on stderr when falling back to `CMOS_DASHBOARD_API_KEY` or password auth, with a one-line migration pointer.
+
+### Attribution (originally shipped Sprints 53–54)
+
+- **Sender-context boundary module** at `src/tools/cmos/sender-identity.ts`. Single source of truth for sender attribution: matches `metadata.dashboard_project_id` first, then the local `cmos_address` against `/api/projects/me`, then fail-closed (`undefined`) — never picks a sibling.
+- **Dispatcher refactor.** `CMOS_PROJECT_ROOT` no longer leaks into the tool-dispatch chain. Sender resolution is independent of working directory.
+- **Self-send probe.** Sending `cmos://derek/<own>` to itself is rejected with HTTP 400. The MCP uses this as a runtime sanity check.
+- **Sibling hardening.** Verified across 12 active projects post-rebuild — no cross-project mis-attribution observed.
+
+### Context v2 (originally shipped Sprints 49–51)
+
+- **Project identity (Layer 0)** as a first-class context type. `cmos_context(action="view", contextType="project_identity")` reads/writes the canonical identity payload — `project_id`, `cmos_address`, `platform`, `tier`, `objectives`, etc. Consumed by every onboard.
+- **FTS5 retrieval** for decisions, learnings, missions, and sessions. `cmos_context(action="search")` runs relevance-scored queries with optional recency boost; the same retriever powers `cmos_decisions(action="search")` and the supersession detector.
+- **Onboard v2.** `cmos_agent_onboard` returns a curated <4KB payload optimized for cold-start, with explicit warnings for staleness, sync drift, orphans, and credential issues.
+- **Blob reduction.** `master_context` blobs that previously ran 86KB+ now typically sit under 20KB. Versioned blob migration system (`schema-migrations.ts` + lazy migration on read/write) lets the schema evolve without breaking existing databases.
+- **Last-reviewed tracking.** Decisions and learnings carry `last_reviewed_at`; cited items get bumped automatically (see staleness hygiene below).
+
+### Staleness hygiene (originally shipped Sprint 61)
+
+- **Auto-reaffirm-on-cite.** Decisions and learnings cited via `citesLearningIds[]` (explicit) or detected via JS keyword overlap (implicit, floor 15) get their `last_reviewed_at` bumped automatically. Citing a learning in a session capture or mission completion treats it as fresh.
+- **Threshold default 10 → 20 sprints.** `DEFAULT_STALENESS_THRESHOLD` is exported from the staleness module so downstream tools share the value.
+- **Evergreen flag.** `cmos_learnings(action="update", evergreen=true)` marks an institutional rule excluded from the staleness signal. Lazy migration on first read/write of the learnings table.
+
+### Tool-surface changes
+
+This is the section to read carefully if you've been tracking pre-1.0 internal builds.
+
+- **`cmos_learnings(action="update")` now requires `status` OR `evergreen`** (decision #634). Previously `status` was the only mutation field; the evergreen flag is now a peer. At least one of the two must be set per update call. Impact: any caller passing only `learningId` with no other fields will now error — pass at least `status` or `evergreen=...`.
+- **14 consolidated tools.** `cmos_status` is the newest, added in v1.0 for cross-side parity with `cmos_agent_onboard.authState`. It returns five fields: `cmos_address`, `dashboard_url`, `auth_tier`, `last_sync_at`, `last_delivery_observed_at`.
+- **`cmos_auth(action="logout")` is symmetric with `login`.** Logout revokes the user-scoped key on the dashboard and clears the local row atomically. Project-scoped child keys are not cascade-revoked.
+- **Dashboard-not-configured is now actionable.** Tools that relay to the dashboard (sync, messaging, registry) return a structured `DASHBOARD_NOT_CONFIGURED` error with a sign-up pointer when `CMOS_DASHBOARD_URL` is unset, instead of a generic network error.
+- **HTTP 402 = `DASHBOARD_UPGRADE_REQUIRED`.** Paid-tier denial (e.g., cross-user messaging from a free account) returns a typed error code with the dashboard's detail message and a sign-up URL.
+- **Content-field sanitizer.** Free-text fields on write paths (`cmos_session(capture|complete)`, `cmos_mission(add|update)`, `cmos_mission_transition(complete|block|defer)`, `cmos_context(update)`) strip XML-marshalling fingerprints (`<content …>`, `<parameter …>`, `<invoke …>`, `<function_calls …>` outside code fences). The write succeeds but `sanitizedFields[]` surfaces what was trimmed — re-emit cleanly to store the full content.
+- **`agentFeedback` field.** `cmos_agent_onboard`, `cmos_session(complete)`, and `cmos_mission_transition(complete)` accept an optional `agentFeedback` (≤2000 chars) to log UX rough edges. Reviewable via `cmos_feedback(action="list")`.
+- **Test isolation.** Jest provisions a per-run `CMOS_CONFIG_DIR` tmpdir so the test suite never touches `~/.config/cmos-mcp/`. Set `CMOS_CONFIG_DIR` outside tests to override the default config directory.
+
+### Packaging
+
+- **Package name: `@aquex/cmos-mcp`** (scoped). v1.0.0 is the first public version.
+- **`bin` field exposes `cmos-mcp` and `cmos-mcp-http`.**
+- **`files` allowlist** ships only `dist/`, `cmos-seed/`, `LICENSE`, `README.md`. Working DB, planning docs, internal docs, and test fixtures are excluded — verified by `npm pack --dry-run`.
+- **Default `CMOS_DASHBOARD_URL=https://cmos.aquex.ai`** baked at the dashboard-client level. Empty-string env values are treated as unset (avoids the IDE-spawn empty-env trap).
+- **Bundled-env safety guard.** `runStartupBundledEnvCheck` warns on stderr if the server starts from `node_modules/` and finds a stray `.env` adjacent — protects against accidental secret publish.
+- **`engines.node >= 18`.** No preinstall/postinstall scripts.
+
+### URL cutover
+
+- **`https://cmos.aquex.ai`** is the canonical dashboard URL going forward (per decision #620).
+- **`https://cmos-mcp.com`** is soft-deprecated. The dashboard team's allowlist keeps it accepting in-flight clients during the transition; new installs default to the aquex.ai URL.
+- The cutover is env-only — no code-level URL hardcoding survives in `src/`.
+
+### Known issues at v1.0
+
+- **Sync is checkpoint-driven, not continuous.** Sprint 41 replaced the continuous sync pipeline with explicit `cmos_db(action="backfill")` operations. This is the intended model — there's no plan to restore continuous sync.
+- **One-way mirror.** SQLite is source of truth; Postgres is a read replica. Restoring state from a different machine requires a fresh login plus a backfill flow.
+- **Cross-user messaging is paid-tier.** Same-user multi-device messaging and receive-from-paid are free. Paid-tier denial returns HTTP 402 with the structured `DASHBOARD_UPGRADE_REQUIRED` error.
+- **28 evergreen-candidate learnings** flagged in the staleness audit are pending an institutional-rule sweep — operator-driven, not blocking.
+- **Historical corrupted rows.** Sprint 60 surfaced 26 historical rows with XML-marshalling artifacts; the sanitizer prevents new corruption but the existing rows are report-only (run `npm run detect:corrupted` to audit).
+
+### Migration notes
+
+- **Coming from `cmos-mcp` (unscoped)?** The package was never publicly published under that name — internal builds installed from a tarball or git URL. Switch your MCP client config to `@aquex/cmos-mcp`:
+
+  ```json
+  { "command": "npx", "args": ["-y", "@aquex/cmos-mcp"] }
+  ```
+
+- **Existing CMOS databases are forward-compatible.** Lazy schema migrations run on first read/write. No manual migration step.
+- **Custom `cmos_learnings(action="update")` callers** should pass at least one of `status` or `evergreen` per call (see Tool-surface changes above).
+
+[1.0.0]: https://github.com/kneelinghorse/cmos-mcp/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 CMOS-MCP contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# cmos-mcp
+
+[![npm version](https://img.shields.io/npm/v/@aquex/cmos-mcp)](https://www.npmjs.com/package/@aquex/cmos-mcp)
+[![License: ISC](https://img.shields.io/badge/license-ISC-blue.svg)](LICENSE)
+
+A local-first Model Context Protocol server for CMOS — Context, Missions, Operations, Sessions. Gives AI agents typed, SQLite-backed project operations without fragile CLI parsing.
+
+## What it is
+
+cmos-mcp is the protocol + client. It runs locally on your machine, owns a SQLite database under `cmos/db/cmos.sqlite`, and exposes 14 typed tools to any MCP-capable agent (Claude Code, Claude Desktop, Cursor, Zed, VS Code, Windsurf).
+
+Out of the box you get:
+
+- Sprint and mission state machines with auditable transitions
+- Session capture for decisions, learnings, constraints, next-steps
+- Strategic context that condenses across sprints, with FTS5 retrieval
+- Full-text search across decisions, learnings, missions, sessions
+- Snapshot-backed safety on destructive operations
+- Per-project credential store and device-code auth (RFC 8628)
+
+The dashboard at [cmos.aquex.ai](https://cmos.aquex.ai) is **optional**. You can run cmos-mcp standalone forever — sign-up unlocks sync (SQLite ↔ Postgres mirror), the project registry (`cmos://you/*` addresses), and cross-project messaging. Without it, every other tool still works locally.
+
+## Install
+
+```bash
+npm install -g @aquex/cmos-mcp
+```
+
+Or run on demand without a global install:
+
+```bash
+npx -y @aquex/cmos-mcp
+```
+
+Requires Node.js 18+.
+
+## Configure your MCP client
+
+### Claude Code
+
+```bash
+claude mcp add-json cmos-mcp '{"command":"npx","args":["-y","@aquex/cmos-mcp"]}'
+```
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent on Windows/Linux:
+
+```json
+{
+  "mcpServers": {
+    "cmos-mcp": {
+      "command": "npx",
+      "args": ["-y", "@aquex/cmos-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cmos-mcp": {
+      "command": "npx",
+      "args": ["-y", "@aquex/cmos-mcp"]
+    }
+  }
+}
+```
+
+### Zed
+
+```json
+{
+  "context_servers": {
+    "cmos-mcp": {
+      "command": "npx",
+      "args": ["-y", "@aquex/cmos-mcp"]
+    }
+  }
+}
+```
+
+### VS Code (Claude extension)
+
+```json
+{
+  "mcp.servers": {
+    "cmos-mcp": {
+      "command": "npx",
+      "args": ["-y", "@aquex/cmos-mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+```json
+{
+  "mcpServers": {
+    "cmos-mcp": {
+      "command": "npx",
+      "args": ["-y", "@aquex/cmos-mcp"]
+    }
+  }
+}
+```
+
+## First call
+
+In your MCP client, ask the agent to onboard:
+
+```
+Run cmos_agent_onboard to see the project state.
+```
+
+If you're in a directory with no CMOS database yet, the agent will surface a fresh-project pathway. Otherwise it returns the active sprint, pending missions, recent decisions, context freshness, and suggested actions in a single payload optimized for cold-start (<4KB).
+
+The full walkthrough — install → config → init → first sprint/mission/session loop — lives in [docs/getting-started.md](docs/getting-started.md).
+
+## Tool surface
+
+cmos-mcp exposes 14 consolidated tools. Most use an `action` parameter to select the operation; `cmos_agent_onboard` and `cmos_status` take only `projectRoot`.
+
+| Tool                      | Purpose                                                                         |
+| ------------------------- | ------------------------------------------------------------------------------- |
+| `cmos_agent_onboard`      | Cold-start payload: identity, active sprint, missions, decisions, suggestions   |
+| `cmos_status`             | Diagnostic snapshot: cmos_address, dashboard_url, auth_tier, sync timestamps    |
+| `cmos_mission`            | `list \| show \| status \| add \| update \| depends`                            |
+| `cmos_mission_transition` | `start \| complete \| block \| unblock \| drop \| defer`                        |
+| `cmos_sprint`             | `list \| show \| add \| update \| complete \| retro \| analytics`               |
+| `cmos_session`            | `list \| start \| capture \| complete`                                          |
+| `cmos_context`            | `view \| update \| condense \| snapshot \| history \| next_steps \| search`     |
+| `cmos_decisions`          | `list \| search \| update \| review \| batch_update`                            |
+| `cmos_learnings`          | `list \| search \| update \| reaffirm`                                          |
+| `cmos_db`                 | `health \| snapshot \| restore \| backfill \| reconcile \| purge`               |
+| `cmos_project`            | `init \| register \| list \| unregister \| validate \| prune \| update`         |
+| `cmos_auth`               | `login_init \| login_complete \| logout \| rotate \| revoke \| list \| reissue` |
+| `cmos_message`            | `send \| list \| respond \| directory \| whoami` (requires dashboard)           |
+| `cmos_feedback`           | `list \| triage \| resolve \| archive`                                          |
+
+See [agents.md](agents.md) for the full per-action reference and behavioral notes.
+
+## Optional: hosted dashboard
+
+The dashboard is a separate service. Sign up at [cmos.aquex.ai](https://cmos.aquex.ai) to unlock:
+
+- **Sync** — your local SQLite mirrors to a Postgres replica; survives machine swaps and IDE reinstalls.
+- **Project registry** — addressable `cmos://you/project-name` URIs across machines.
+- **Messaging** — `cmos_message(action="send")` to your own projects (free) or, on the paid tier, to other users.
+
+To connect:
+
+```bash
+export CMOS_DASHBOARD_URL=https://cmos.aquex.ai
+```
+
+Then run `cmos_auth(action="login_init")` from your agent. It returns a one-time `userCode` and `verificationUri` — paste the code at the URL in your browser, then run `cmos_auth(action="login_complete", deviceCode=...)` to finish. Credentials persist atomically to `~/.config/cmos-mcp/credentials.json` (mode 0600).
+
+If `CMOS_DASHBOARD_URL` is unset or unreachable, the dashboard-relay tools (`cmos_message`, sync, registry) return a structured `DASHBOARD_NOT_CONFIGURED` or `DASHBOARD_UPGRADE_REQUIRED` error pointing at the sign-up URL. Local tools never depend on the dashboard.
+
+## Project resolution
+
+When an MCP tool is called, cmos-mcp resolves the target project root in this order:
+
+1. Explicit `projectRoot` parameter on the tool call (highest trust).
+2. `CMOS_PROJECT_ROOT` environment variable (CI/CD).
+3. Auto-discovery from the current working directory (looks for `cmos/db/cmos.sqlite`).
+4. Default project from the registry at `~/.config/cmos-mcp/project-registry.json`.
+5. Structured error pointing at `cmos_project(action="register")`.
+
+This is what makes Claude Code "just work" from a workspace, while Claude Desktop (no CWD context) needs an explicit `cmos_project(action="register", setAsDefault=true)` once.
+
+## Environment variables
+
+```bash
+# Optional — connects to the hosted dashboard. Defaults to https://cmos.aquex.ai
+# when unset; treat empty string as unset.
+CMOS_DASHBOARD_URL=https://cmos.aquex.ai
+
+# Optional — explicit project root (CI/CD). Otherwise auto-discovered.
+CMOS_PROJECT_ROOT=/path/to/your/project
+
+# Optional — override the credential + registry directory. Default: ~/.config/cmos-mcp
+CMOS_CONFIG_DIR=/custom/path
+
+# Snapshot retention (defaults shown)
+CMOS_AUTO_SNAPSHOT=1
+CMOS_SNAPSHOT_RETENTION_DAYS=7
+CMOS_MAX_SNAPSHOTS=50
+```
+
+## Error response shape
+
+Every tool returns a uniform envelope:
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "MISSION_NOT_FOUND",
+    "message": "Mission 's99-m01' not found",
+    "suggestion": "Use cmos_mission(action=\"list\") to see available missions"
+  }
+}
+```
+
+`code` is machine-readable, `message` is human-readable, `suggestion` is a concrete next step. Validation errors carry `valid_values`; state errors carry `current_state`.
+
+## Safety
+
+- **Soft deletes.** Records keep `deleted_at` timestamps; nothing is physically removed.
+- **Auto-snapshots.** Destructive ops snapshot first to `cmos.sqlite.bak-{timestamp}`.
+- **Append-only audit.** Session events, context snapshots, and mission history are immutable rows.
+- **Dry-run.** Mutating tools accept `dry_run: true` to preview without committing.
+- **Atomic credential writes.** `credentials.json` is written via temp-file + rename with 0600 permissions.
+
+## Known limits at v1.0
+
+- Sync is checkpoint-driven, not continuous — manual `cmos_db(action="backfill")` flushes pending events to the dashboard.
+- Postgres mirror is one-way (SQLite is source of truth); pulling state down from a different machine requires a fresh sign-in plus a backfill.
+- Cross-user messaging on the dashboard is paid-tier; same-user (multi-device) messaging is free.
+- 28 evergreen learnings flagged in the staleness audit are scheduled for an institutional-rule sweep — they don't affect tool behavior.
+
+## Documentation
+
+- [Getting started](docs/getting-started.md) — install through first onboard, no dashboard required.
+- [Agent playbook (agents.md)](agents.md) — full tool reference, conventions, architecture deep-dive.
+- [Changelog](CHANGELOG.md) — release notes and tool-surface changes.
+
+## Development
+
+```bash
+git clone https://github.com/kneelinghorse/cmos-mcp
+cd cmos-mcp
+npm install
+npm run build
+npm test
+```
+
+Pre-commit hooks run lint + format via husky/lint-staged. CI enforces lint + tests + snapshots.
+
+## License
+
+ISC. See [LICENSE](LICENSE).

package/cmos-seed/README.md

@@ -0,0 +1,153 @@
+# CMOS Seed
+
+**Minimal seed for CMOS (Context + Mission Orchestration System) projects.**
+
+CMOS is a project management layer for AI-assisted development. This seed provides the minimal structure for MCP-based project initialization.
+
+---
+
+## What's Included
+
+```
+cmos-seed/
+├── db/
+│   └── schema.sql      # Full CMOS SQLite schema
+├── tiers/
+│   ├── build.md        # Build tier behavioral guide
+│   ├── general.md      # General tier behavioral guide
+│   └── managed.md      # Managed tier behavioral guide
+└── docs/
+    ├── README.md                  # Documentation index
+    ├── getting-started.md         # Quick setup guide
+    ├── build-session-prompt.md    # Build session template
+    ├── session-management-guide.md # Session workflows
+    └── sqlite-schema-reference.md # Database schema docs
+```
+
+---
+
+## Quick Start
+
+### Option 1: Use cmos_project_init (Recommended)
+
+The `cmos_project_init` MCP tool creates CMOS structure directly:
+
+```
+cmos_project_init({
+  projectRoot: "/path/to/your/project",
+  projectName: "My Project",
+  projectId: "my-project-id",  // optional, auto-generated if omitted
+  createDocs: true,            // optional, creates docs/ directory
+  initialSprint: {             // optional
+    id: "sprint-01",
+    title: "Initial Sprint"
+  }
+})
+```
+
+This creates:
+
+- `cmos/db/cmos.sqlite` - Initialized database with full schema
+- `cmos/tiers/build.md` - Build tier behavioral guide
+- `cmos/docs/` - Documentation (if createDocs=true)
+
+### Option 2: Manual Setup
+
+1. Copy this seed into your project:
+
+   ```bash
+   cp -r cmos-seed/ yourproject/cmos/
+   ```
+
+2. Initialize the database:
+
+   ```bash
+   sqlite3 yourproject/cmos/db/cmos.sqlite < yourproject/cmos/db/schema.sql
+   ```
+
+3. Use MCP tools to manage the project.
+
+---
+
+## Using CMOS
+
+All operations are performed via MCP tools. No Python CLI required.
+
+### Core Workflow
+
+```
+# 1. Get project state
+cmos_agent_onboard()
+
+# 2. Check work queue
+cmos_mission_status()
+
+# 3. Start mission
+cmos_mission_start(missionId="s01-m01")
+
+# 4. Execute work
+# (actually implement the mission)
+
+# 5. Complete mission
+cmos_mission_complete(missionId="s01-m01", notes="What was done")
+```
+
+### Available MCP Tools
+
+| Category      | Tools                                                                                                                                                                                                                           |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Setup**     | `cmos_project_init`, `cmos_db_health`, `cmos_agent_onboard`                                                                                                                                                                     |
+| **Missions**  | `cmos_mission_status`, `cmos_mission_list`, `cmos_mission_show`, `cmos_mission_start`, `cmos_mission_complete`, `cmos_mission_block`, `cmos_mission_unblock`, `cmos_mission_update`, `cmos_mission_add`, `cmos_mission_depends` |
+| **Sprints**   | `cmos_sprint_list`, `cmos_sprint_show`, `cmos_sprint_add`, `cmos_sprint_update`                                                                                                                                                 |
+| **Sessions**  | `cmos_session_start`, `cmos_session_capture`, `cmos_session_complete`, `cmos_session_list`                                                                                                                                      |
+| **Context**   | `cmos_context_view`, `cmos_context_snapshot`, `cmos_context_history`                                                                                                                                                            |
+| **Decisions** | `cmos_decisions_list`, `cmos_decisions_search`                                                                                                                                                                                  |
+
+---
+
+## Key Concepts
+
+### Mission Lifecycle
+
+```
+Queued → Current → In Progress → Completed
+                 ↘ Blocked ↗
+```
+
+### Two Contexts
+
+- **project_context**: Current session state, working memory
+- **master_context**: Project history, strategic decisions, constraints
+
+### Sessions
+
+Non-build work (planning, research, reviews) captured via session tools:
+
+- Types: planning, onboarding, review, research, check-in, custom
+- Lifecycle: start → capture → complete
+
+---
+
+## Documentation
+
+See `docs/` for complete documentation:
+
+- [Getting Started](docs/getting-started.md) - Quick setup guide
+- [Build Session Prompt](docs/build-session-prompt.md) - Template for build sessions
+- [Session Management Guide](docs/session-management-guide.md) - Planning, reviews, research
+- [SQLite Schema Reference](docs/sqlite-schema-reference.md) - Database structure
+
+---
+
+## Key Principles
+
+1. **MCP-first**: All operations via MCP tools, no CLI required
+2. **Database is source of truth**: SQLite at `cmos/db/cmos.sqlite`
+3. **Session captures**: Record decisions and learnings during work
+4. **Context snapshots**: Preserve strategic milestones
+5. **Clear boundaries**: CMOS manages work, not application code
+
+---
+
+**Schema Version**: 2.0
+**Last Updated**: 2025-12-28

package/cmos-seed/context/master_context.json

@@ -0,0 +1,27 @@
+{
+  "project_identity": {},
+  "technical_foundation": {},
+  "roadmap": [],
+  "decisions_made": [],
+  "constraints": [],
+  "learnings": [],
+  "context_notes": [],
+  "next_session_context": {},
+  "recent_sessions": [],
+  "sprint_completions": [],
+  "working_memory": {
+    "session_history": [],
+    "last_session": null,
+    "session_count": 0,
+    "active_mission": null,
+    "blocked_missions": [],
+    "last_completed_mission": null
+  },
+  "context_health": {
+    "last_update": null,
+    "sessions_since_reset": 0,
+    "size_kb": 0,
+    "size_limit_kb": 100
+  },
+  "quality_standards": {}
+}

package/cmos-seed/context/project_context.json

@@ -0,0 +1,12 @@
+{
+  "working_memory": {
+    "active_mission": null,
+    "session_count": 0,
+    "last_completed_mission": null,
+    "session_history": []
+  },
+  "context_health": {
+    "last_updated": null,
+    "stale_threshold_hours": 24
+  }
+}