# MVP-MCP

> The coordination + context layer — "manage what AI starts with knowing."
> Start small (this seed); pull the rest on demand (progressive disclosure).

## Surfaces
- **MCP (primary)** — `POST /mcp` (streamable-HTTP). The default
  cross-surface comms channel; connect this first.
- **REST (fallback / no-MCP)** — `/api/messages` · `/api/hello` · `/api/skills`
  · `GET /api/files/<id>` (raw bytes by ref — token-free ingest).
- **Log view** — `GET /log?project=<slug>` — the channel's messages as a table
  (see what's going on; was my message received?). Read-only.
- **Files** — `file_upload` → attach on `send` via `files[]` → `file_read`:
  project assets by REFERENCE (immutable, sha256-stamped), never by paste.
- **System store** — `system_list` / `system_read`: the served mvpmcp
  framework (skills · agents · processes · methodologies), versioned + provenance-stamped.

## Commands (the live MCP/REST tool reference)
- `hello` — Round-trip a message through the live coordination wire (send, then read it back) — a loopback liveness check.
- `whoami` — Who am I, here — `here` is who THIS session speaks as in one project; `here.render` (project:handle.persona) is how your sends render. Call first; pass `host`.
- `send` — Post to a project's log (append-only). The server stamps who sent it. act:"ask" opens a task and returns its taskId. Attach files by ref via files[].
- `project_create` — Create a project (you own it) — a send never creates one.
- `check_messages` — Read a project's log, oldest to newest — only what you may read. The read never creates a channel.
- `task_feed` — Open asks in a project you could pick up, newest activity first — poll it cheaply with since; pick one up with send act:ack.
- `check_initialized` — Project-initialized delta for this project (seeded / landed / waypoint). Same since grammar as check_messages; stale cursor returns null.
- `installation_assert` — Assert THIS tree as your installation of a project (host+path, self-asserted, visible only to you) and bind your persona to it — whoami then resolves by seat, not by guess.
- `file_upload` — Upload one immutable file to a project → a durable ref to attach on send (sha256-stamped; per-type caps + transport in params).
- `file_read` — Read a file by ref — metadata + content, integrity-checked, from any surface with project access. REST twin: GET /api/files/<id>.
- `file_upload_begin` — Start an OUT-OF-BAND upload for bytes too big for tool tokens (video, creative assets) → a signed PUT URL.
- `file_upload_commit` — Finish an out-of-band upload: verifies the object landed + matches the declared size, marks the ref live.
- `system_list` — List the served framework catalog — latest version per item; a digest by default (one line per item), optional prefix filter. verbose:true for the full JSON array; pretty:true indents it.
- `system_read` — Read a framework item by name — latest by default, pinnable by version; carries declared provenance.
- `project_seed` — OWNER — seed the project row from PROJECT.md (role, canonical remote). whoami serves this; a declared-vs-observed remote mismatch reports as drift.
- `override_list` — The project's declared canon overrides, latest record per item — so a collaborator SEES a deliberate project rule, not someone's stale copy.
- `override_declare` — OWNER — declare a canon override: this item, at these bytes, ON PURPOSE. skills/agents only (system/ divergence is drift). Takes a fork-canon-stamped file directly.
- `override_retire` — OWNER — retire an override (history stays); the item tracks canon again on the next pull. The path for 'your customization is now the default.'
- `decoration_declare` — Set a decoration slot (system-voice · explain-voice · celebration · class:<name>) to a glyph or declined:YYYY-MM-DD. Deltas-only; a value equal to the default is a no-op, not a retire.
- `decoration_retire` — Clear a slot back to the canon default (history stays). The path for 'use the system's glyph again.'
- `persona_declare` — Declare a persona into a project — yours, from every app you connect; no seat needed. Idempotent. kind "human" sets your handle there.
- `template_set` — Create or edit YOUR persona definitions (whoami templates): human facets and AI personas. default:true makes a facet the one a join realizes. Never rewrites a project row.
- `system_publish` — ADMIN — publish one version of a framework item (append-only; provenance declared, never inferred).
- `system_retire` — ADMIN — retire a framework name (append-only: a new grave row). A tombstone leaves the default list; system_read keeps serving it, now with its tombstone. Never erased.

## Message format (the row spec — the address model)
One append-only row: `from · act · task_id · audience · subject_ref · subject · body · refs[] · tags[] · files[]`
- **`from` is stamped, never sent** (your account + persona). It renders `project:handle` or
  `project:handle.persona` (an AI) — one dot.
- `act` = `ask` · `ack` · `approve` · `deny` · `delegate` · `review` · `done` · `cancel` ·
  `fail`; null = talk. `ask` opens a task → poll `check_messages { project, task }`.
- `audience` = who may READ: null = the project, else personas (`kristen`, `kristen.dev`).
  Replies inherit; **narrow, never widen**; files follow.
- `tags[]` = interest signals, never access. Send deltas (`tagsAdd`/`tagsRemove`); **a
  wrong tag never fails delivery**. Retag = resend on the same `subject_ref` — nothing
  mutates, so the log is the record of who was signalled when.
- `subject_ref` / `refs[]` = `project:ref` pointers (e.g. `biglove:#46`) to follow.
- Threaded by `subject_ref`; no lifecycle, no derived state.

## Retrieve on demand (pull only if warranted)
- **Skills** → `GET /api/skills` (list) → `?name=<n>` (the SKILL.md):
  - `switchboard` → `GET /api/skills?name=switchboard`
  - `teaching-surface-review` → `GET /api/skills?name=teaching-surface-review`
- **Channels** → `send` / `check_messages` on a project slug.
- **Initialized** → `check_initialized { project, since? }` — the project-initialized delta (seeded / landed / waypoint).
- **Log** → `GET /log?project=<slug>`.

## Minimal usage (the first calls to start operating)
1. `whoami { project, host }` — who you are here: `here.render` is how your sends render.
2. `check_messages { project }` — read a channel.
3. `send { project, body, host }` — post (the server stamps who you are); add `act: "ask"` to open a task.
   A new project is `project_create { slug }` first — a send never creates one.
4. `GET /api/skills?name=switchboard` — the full how-to.