Close the skill-pack and API docs staleness before the website sprint

Skill pack (template.md -> AGENTS.md, .claude/skills/smriti/SKILL.md):
- §3.2 Repo reconciliation: lead with `## Repo state`'s automated drift
  signals; keep the manual git log checks as the documented fallback
  for checkpoints without recorded git state.
- §3.5 Backend reachability: lead with `smriti doctor` as the
  structured health check; keep `curl /health` as the raw fallback.
- Bump skill pack version 2.4 -> 2.5; re-render AGENTS.md (the
  .claude/skills/smriti/SKILL.md install is local-only and untracked).
- test_skill_pack: bump the expected version; add four single-line
  required phrases proving the new content shipped (`Repo state`,
  `smriti doctor`, "ahead of the last checkpoint", "checkpoint taken
  on a different branch").

docs/API.md:
- POST /api/v4/chat/commit: add `repo_state` to the request body
  example and a paragraph explaining its purpose (drift detection),
  persistence (`context_blob`), and read-back path (V4 state endpoint).
- DELETE /api/v2/repos/{repo_id}: add the missing section with the
  `force` query param, 204/404/409 responses, and the structured
  detail shape for the 409 refusal.

CLI suite: 253 passed. AGENTS.md and SKILL.md verified byte-identical
to fresh render(target) output.

AGENTS.md

@@ -1,5 +1,5 @@
 ---
-smriti_skill_pack_version: 2.4
+smriti_skill_pack_version: 2.5
 title: Smriti — how to use it well
 target: Codex
 ---
@@ -127,7 +127,28 @@ The state brief tells you what was decided and what tasks were
 flagged. It does NOT tell you whether those tasks have already been
 completed in the codebase. Another agent may have finished the work
 and committed it after the checkpoint was written. Before you start
-implementing anything from the state brief's tasks, reconcile:
+implementing anything from the state brief's tasks, reconcile.
+
+**Start with `## Repo state` in the state brief.** When you run
+`smriti state` inside a git repo, the brief
+appends a `## Repo state` section that compares the working repo
+against the git HEAD and branch the latest checkpoint recorded. The
+signals to look for inline:
+
+- *"repo is N commit(s) ahead of the last checkpoint — recorded state
+  may be stale"* — the repo has moved past the checkpoint; the manual
+  checks below tell you what to do next.
+- *"checkpoint taken on a different branch (`X`)"* — the brief was
+  recorded on a different git branch than you're on now.
+- *"repo history has diverged from the last checkpoint"* — the recorded
+  HEAD is no longer an ancestor of the current repo HEAD.
+- *"repo unchanged since the last checkpoint"* — no drift; the recorded
+  state still matches the repo.
+
+If `## Repo state` is silent (older checkpoint with no recorded git
+state, MCP-created checkpoint, or you're not inside a git repo) or its
+signals suggest the repo has moved past the checkpoint, fall back to
+the manual checks:
 
 1. **Check recent commits.** Run `git log --oneline -10` (or your
    host's equivalent). Do any of them address the task you are about
@@ -243,9 +264,13 @@ findings, branch is [disposition]."**
 The Smriti backend is a shared service started by the human. You
 are a client of it. You do not own it.
 
-- Your first `smriti state` call will
-  fail with a clear connection error if the backend is not running.
-  That is your reachability check — no separate health probe needed.
+- **Use `smriti doctor` for a structured
+  health check.** It diagnoses backend reachability, CLI/backend version
+  alignment, capability presence, and provider status — and tells you
+  what to do if anything is off. If you only need to know whether the
+  backend is up, your first `smriti state`
+  call is also enough — it fails with a clear connection error when the
+  backend is unreachable.
 - **If the backend is unreachable, stop and tell the human.** Say:
   "The Smriti backend is not reachable at http://localhost:8000.
   Please start it with `make dev-local` for solo/local mode, or
@@ -255,11 +280,12 @@ are a client of it. You do not own it.
   tool loop creates environment-variable inheritance issues that
   cause silent mock fallback on all LLM-backed endpoints. The
   human starts the backend; you use it.
-- **Check capabilities before using advanced features.** After
-  reading state, before creating claims or using features like
-  structured tasks, probe the backend:
+- **Check capabilities before using advanced features.** `smriti doctor`
+  surfaces the backend's capability manifest (the `capabilities` list
+  from `/health`) and flags missing entries. For a one-off raw check,
   `curl -s http://localhost:8000/health`
-  The response includes `git_sha` and a `capabilities` list. If
+  returns the same data. The response includes `git_sha` and a
+  `capabilities` list. If
   you need `claims` but the capabilities list does not include it,
   the backend is running stale code. Tell the human: "The backend
   at localhost:8000 does not support [feature]. Its git_sha is

cli/smriti_cli/skill_pack/template.md

@@ -1,5 +1,5 @@
 ---
-smriti_skill_pack_version: 2.4
+smriti_skill_pack_version: 2.5
 title: Smriti — how to use it well
 target: {{display_name}}
 ---
@@ -130,7 +130,28 @@ The state brief tells you what was decided and what tasks were
 flagged. It does NOT tell you whether those tasks have already been
 completed in the codebase. Another agent may have finished the work
 and committed it after the checkpoint was written. Before you start
-implementing anything from the state brief's tasks, reconcile:
+implementing anything from the state brief's tasks, reconcile.
+
+**Start with `## Repo state` in the state brief.** When you run
+`{{mcp:smriti_state}}{{cli:smriti state}}` inside a git repo, the brief
+appends a `## Repo state` section that compares the working repo
+against the git HEAD and branch the latest checkpoint recorded. The
+signals to look for inline:
+
+- *"repo is N commit(s) ahead of the last checkpoint — recorded state
+  may be stale"* — the repo has moved past the checkpoint; the manual
+  checks below tell you what to do next.
+- *"checkpoint taken on a different branch (`X`)"* — the brief was
+  recorded on a different git branch than you're on now.
+- *"repo history has diverged from the last checkpoint"* — the recorded
+  HEAD is no longer an ancestor of the current repo HEAD.
+- *"repo unchanged since the last checkpoint"* — no drift; the recorded
+  state still matches the repo.
+
+If `## Repo state` is silent (older checkpoint with no recorded git
+state, MCP-created checkpoint, or you're not inside a git repo) or its
+signals suggest the repo has moved past the checkpoint, fall back to
+the manual checks:
 
 1. **Check recent commits.** Run `git log --oneline -10` (or your
    host's equivalent). Do any of them address the task you are about
@@ -246,9 +267,13 @@ findings, branch is [disposition]."**
 The Smriti backend is a shared service started by the human. You
 are a client of it. You do not own it.
 
-- Your first `{{mcp:smriti_state}}{{cli:smriti state}}` call will
-  fail with a clear connection error if the backend is not running.
-  That is your reachability check — no separate health probe needed.
+- **Use `{{mcp:smriti doctor}}{{cli:smriti doctor}}` for a structured
+  health check.** It diagnoses backend reachability, CLI/backend version
+  alignment, capability presence, and provider status — and tells you
+  what to do if anything is off. If you only need to know whether the
+  backend is up, your first `{{mcp:smriti_state}}{{cli:smriti state}}`
+  call is also enough — it fails with a clear connection error when the
+  backend is unreachable.
 - **If the backend is unreachable, stop and tell the human.** Say:
   "The Smriti backend is not reachable at http://localhost:8000.
   Please start it with `make dev-local` for solo/local mode, or
@@ -258,11 +283,12 @@ are a client of it. You do not own it.
   tool loop creates environment-variable inheritance issues that
   cause silent mock fallback on all LLM-backed endpoints. The
   human starts the backend; you use it.
-- **Check capabilities before using advanced features.** After
-  reading state, before creating claims or using features like
-  structured tasks, probe the backend:
+- **Check capabilities before using advanced features.** `smriti doctor`
+  surfaces the backend's capability manifest (the `capabilities` list
+  from `/health`) and flags missing entries. For a one-off raw check,
   {{mcp:`curl -s http://localhost:8000/health`}}{{cli:`curl -s http://localhost:8000/health`}}
-  The response includes `git_sha` and a `capabilities` list. If
+  returns the same data. The response includes `git_sha` and a
+  `capabilities` list. If
   you need `claims` but the capabilities list does not include it,
   the backend is running stale code. Tell the human: "The backend
   at localhost:8000 does not support [feature]. Its git_sha is

cli/tests/test_skill_pack.py

@@ -43,7 +43,7 @@ def test_load_template_nonempty():
 
 def test_get_version_parses_frontmatter():
     version = get_version()
-    assert version == "2.4"
+    assert version == "2.5"
 
 
 def test_get_version_raises_when_frontmatter_missing():
@@ -189,6 +189,12 @@ _REQUIRED_PHRASES = [
     "reuse the same id",
     # Section 14 — two-sentence summary
     "session start",
+    # Section 3.2 — repo-state drift detection (v2.5)
+    "Repo state",
+    "ahead of the last checkpoint",
+    "checkpoint taken on a different branch",
+    # Section 3.5 — smriti doctor (v2.5)
+    "smriti doctor",
 ]
 
 

docs/API.md

@@ -273,6 +273,36 @@ GET /api/v2/repos/{repo_id}
 
 **Response:** Space object
 
+#### Delete a space
+
+```
+DELETE /api/v2/repos/{repo_id}
+```
+
+Deletes a Space and cascades to every Checkpoint, Session, and Turn under it. Irreversible.
+
+**Query parameters:**
+
+- `force` (boolean, default `false`) — required to delete a Space that still holds checkpoints.
+
+**Responses:**
+
+- `204 No Content` — Space deleted (empty Space, or `force=true` on a populated Space).
+- `404 Not Found` — Space does not exist (or belongs to a different user).
+- `409 Conflict` — Space holds checkpoints and `force=true` was not passed. The response body carries a structured detail explaining the refusal:
+
+  ```json
+  {
+    "detail": {
+      "message": "Cannot delete space 'Australia Trip': it still holds 12 checkpoint(s). Deletion cascades to every checkpoint, session, and turn under it and cannot be undone. Re-send with ?force=true to delete the space and all its contents.",
+      "checkpoint_count": 12,
+      "requires_force": true
+    }
+  }
+  ```
+
+The 409 guard is one of three deletion-safety layers — the CLI's `--force` flag and the MCP `smriti_delete_space` tool's `confirm_space` argument are the other two. Every client (direct `curl`, the web UI, a future client) goes through this server-side rule.
+
 #### Get space head state (main-only)
 
 ```
@@ -565,7 +595,12 @@ POST /api/v4/chat/commit
       "label": "Draft itinerary",
       "content": "Day 1: Arrive in Sydney..."
     }
-  ]
+  ],
+  "repo_state": {
+    "head": "abc123def456...",
+    "head_short": "abc123d",
+    "branch": "main"
+  }
 }
 ```
 
@@ -580,6 +615,17 @@ POST /api/v4/chat/commit
 }
 ```
 
+**Repo-state drift detection (`repo_state`).** The optional `repo_state` field
+records the git HEAD and branch of the repo the checkpoint was created from.
+It is persisted under the commit's `context_blob` and returned by `GET
+/api/v4/chat/spaces/{repo_id}/state` as `commit.context_blob.repo_state`. The
+CLI uses it on subsequent `smriti state` calls to detect drift — N commits
+ahead of the recorded checkpoint, a different branch, or diverged history —
+and surfaces those signals in the rendered state brief's `## Repo state`
+section. The field is optional: clients that cannot inspect a repo (e.g. the
+MCP server, which runs in the host's arbitrary working directory) may omit
+it, and the backend stores an empty `context_blob`.
+
 ---
 
 ### Checkpoint history