From 36591d9375e2ca359594bc98cb58d218426ff54e Mon Sep 17 00:00:00 2001 From: Himanshu Dongre Date: Sat, 11 Apr 2026 13:18:49 +0530 Subject: [PATCH] Update REPO_STRUCTURE and API docs for the CLI REPO_STRUCTURE now lists the cli/ directory and refreshes the API version map to reflect that V2 is current and serves the CLI's read path (with the full checkpoint schema). docs/API.md replaces the "do not build against V2" guidance with a clear description of which prefix is used for what. --- REPO_STRUCTURE.md | 23 ++++++++++++++++------- docs/API.md | 21 +++++++++++++++------ 2 files changed, 31 insertions(+), 13 deletions(-) diff --git a/REPO_STRUCTURE.md b/REPO_STRUCTURE.md index 045e981..296a6ab 100644 --- a/REPO_STRUCTURE.md +++ b/REPO_STRUCTURE.md @@ -50,9 +50,10 @@ smriti/ ├── frontend/ │ ├── src/ │ │ ├── pages/ -│ │ │ ├── ChatWorkspacePage.tsx Primary UI: chat, sidebar, checkpoint -│ │ │ │ modal, history panel, context indicators -│ │ │ └── LineagePage.tsx Branch tree, checkpoint compare +│ │ │ ├── WorkspaceOverviewPage.tsx Resume-focused landing page +│ │ │ ├── ChatWorkspacePage.tsx Primary chat UI: sidebar, checkpoint +│ │ │ │ modal, history panel, context indicators +│ │ │ └── LineagePage.tsx Branch tree, checkpoint compare │ │ ├── api/ │ │ │ └── client.ts API client functions (V4, V5, V2) │ │ ├── types/ @@ -60,8 +61,16 @@ smriti/ │ │ └── main.tsx App entry point, router │ └── package.json │ +├── cli/ Programmatic CLI for agents and scripts +│ ├── README.md Command reference and agent handoff workflow +│ ├── pyproject.toml Installable as `pip install -e ./cli` → `smriti` +│ └── smriti_cli/ +│ ├── main.py argparse dispatcher, seven commands +│ ├── client.py thin HTTP wrapper over the REST API +│ └── formatters.py continuation-oriented markdown renderers +│ ├── docs/ -│ └── API.md V4 and V5 endpoint reference +│ └── API.md V2, V4, and V5 endpoint reference │ └── demos/ └── branching-reasoning-demo/ Complete demo scenario with runbook, @@ -75,9 +84,9 @@ smriti/ | Prefix | Module | Status | Notes | |---|---|---|---| | `/api/v1` | `sessions.py` | Legacy | Transcript paste ingestion | -| `/api/v2` | `repos.py` | Partially current | Space and Checkpoint CRUD used by UI; agent-push workflow is legacy | -| `/api/v4` | `chat.py` | Current | Primary chat and session API | -| `/api/v5` | `checkpoint.py`, `lineage.py` | Current | Checkpoint draft, fork, lineage | +| `/api/v2` | `repos.py`, `commits.py` | Current | Space CRUD, checkpoint read by id, checkpoint list by space. `CommitResponse` includes `assumptions` and `artifacts` so the CLI can read full checkpoints via the V2 single-resource endpoints. | +| `/api/v4` | `chat.py` | Current | Chat sessions, send_message, the canonical checkpoint write path (`POST /chat/commit`) which accepts the full schema. | +| `/api/v5` | `checkpoint.py`, `lineage.py` | Current | Checkpoint draft, review, fork, lineage, compare. | --- diff --git a/docs/API.md b/docs/API.md index dd2b4ce..bfab238 100644 --- a/docs/API.md +++ b/docs/API.md @@ -742,13 +742,22 @@ All endpoints return errors in this format: --- -## Notes on legacy endpoints +## Notes on V1, V2, V4, V5 `/api/v1` — Transcript paste ingestion. Accepts raw text, extracts memories, -generates context packs. Not used by the current UI. Retained for compatibility. +generates context packs. Not used by the current UI or CLI. Retained for +compatibility but no new development happens here. Do not build new integrations +against V1. -`/api/v2` — Agent-push model (repos, commits, context packs). Partially reused by -the current UI for Space CRUD and Checkpoint retrieval, but the agent-push workflow -it was designed for is no longer the primary interaction model. +`/api/v2` — Space CRUD and Checkpoint read endpoints. The CLI reads full +checkpoints via `GET /api/v2/commits/{commit_id}` and lists per-space checkpoints +via `GET /api/v2/repos/{repo_id}/commits`. The `CommitResponse` schema returns +the complete checkpoint shape including `assumptions` and `artifacts`. New +programmatic clients are welcome to use V2 read endpoints; for writes, use V4 +(`POST /api/v4/chat/commit`) which accepts the full schema. -Do not build new integrations against V1 or V2. +`/api/v4` — Chat sessions, message sending, and the canonical checkpoint write +path. The chat UI's primary interaction surface and the CLI's write surface. + +`/api/v5` — Checkpoint drafting, review, fork, compare, lineage. Used by both +the chat UI and the CLI.