The 3-way merge auto-applied both Claude's and Codex's MCP-config intros
without flagging a conflict, leaving two paragraphs that both say "smriti
init prints the config." Collapse them into one — keeping the quickstart-first
onboarding wording and folding in Codex's `which smriti-mcp` manual-config tip.
An external-machine validation pass confirmed setup, local-first, doctor,
quickstart, and init all work — but the README still routed a new user
straight to `smriti init`, which opens an empty space where Smriti's value
is not yet visible.
Restructure the "Getting started" flow: a new step 3 runs `smriti doctor`
then `smriti quickstart` so the first thing a user sees is a populated demo
space. The init step now says to cd into your own project first; the MCP
guidance defers to the resolved config `smriti init` prints rather than a
bare `smriti-mcp`; mock-mode limits and "Try the demo" are clarified to match.
Packaging/readiness pass — documentation only, no feature or behavior change.
- REPO_STRUCTURE.md, CONTRIBUTING.md: corrected test counts (156 integration,
133 unit, 151 CLI), local-first setup flow (make setup-local / dev-local),
command count, new routes/types/test files.
- README.md: refreshed dogfood metrics, added Project Current State and
smriti doctor to the surfaces, SQLite to the tech stack.
- cli/README.md: MCP tool count 17 -> 21 (added the four worktree tools),
documented the smriti worktree commands.
- ARCHITECTURE.md: API table now lists the Project Current State and metrics
endpoints; new Database modes section (local SQLite / Postgres).
- DECISIONS.md: recorded the local-first SQLite mode and Project Current
State surface decisions.
- AGENTS.md: regenerated from skill pack template v2.3 (was a stale v1.5
render); the .claude/ claude-code render was likewise refreshed locally.
.env.example, docs/DEMO_SCRIPT.md, and CLAUDE.md were reviewed and left as-is.
V1 mentioned that claim binding and state-brief enrichment would land
in V2. V2 is now on main (39003a8), so update the bullet to describe
the actual current behavior: bind a claim to a worktree, see drift
in state brief, skill pack v2.0 teaches the reflex. Tool count
unchanged at 21 (V2 added params to existing tools, not new ones).
- README: 17 → 21 MCP tools, add worktrees bullet to coordination
primitives (notes V1 = CRUD primitive only; binding + state-brief
enrichment deferred to V2)
- CONTRIBUTING: 17 → 21 MCP tools
DECISIONS.md and skill pack template are intentionally not touched —
the V1 prompt explicitly deferred those to V2 so the rationale and
skill pack reflexes can be written together with the actual usage
patterns we'll learn from V2 (claim binding + state brief).
Captured three screenshots for the README using playwright against
the live local environment:
- lineage-dashboard.png — real LineagePage showing 56 checkpoints,
summary panel, needs-attention signal, author badges
- checkpoint-detail.png — the autonomy milestone checkpoint with
structured tasks (intent badges), entities, and founder notes
- cli-state-and-metrics.png — terminal-styled render of real CLI
output from smriti state --compact and smriti metrics
Fixed a crash in CommitDetailPage exposed by the screenshot attempt:
diffList was typed list[str] but tasks are now structured objects
after the task IDs feature landed. React threw "Objects are not
valid as a React child" when trying to render the diff result.
Fix normalizes tasks to their text field before diffing.
README now references real images instead of inline code blocks.
TypeScript clean, 331 tests pass.
The 3 screenshot placeholders pointed at files that don't exist yet,
which would render as broken images on GitHub. Replaced with inline
code blocks showing real CLI output (smriti state --compact and
smriti metrics) — these render cleanly now and can be swapped for
actual screenshots later when captured.
Removed stale Loom link and old checkpoint-diff screenshot reference.
README now references 3 new screenshots matching the current product:
LineagePage dashboard, CLI state+metrics, checkpoint detail with
structured tasks and notes. Screenshots are placeholders until
captured from the live environment.
Added docs/DEMO_SCRIPT.md: 3-act, 4-5 minute recording script
covering the state surface, coordination proof (metrics + autonomy
milestone), and developer experience. Includes exact commands,
highlight points, and a screenshot capture checklist.
Restructured from single-user chat-drift framing to multi-agent
coordination as the primary story. Leads with the problem (agents
have no shared state), the solution (structured reasoning-state
backend), and the proof (56 checkpoints, 30 cross-agent handoffs,
autonomous complementary task selection). Single-user value prop
preserved as a secondary section. All claims grounded in current
reality — no future hype, no unqualified comparisons.
cli/README.md:
- Add an "Installing the Smriti skill pack" subsection between the MCP
server section and the Commands reference. Walks through the target
list (claude-code, codex), the CLI install flow, the MCP-tool flow
(read the returned markdown, write via host file tools), and the
verification criterion ("agent calls state unprompted, never writes
HANDOFF.md").
- Update the MCP tools table to 13 entries (add smriti_install_skill).
- Update the Commands reference to include smriti skills list/show/
install and the new --main-only flag on smriti state.
- Update the "Using Smriti from a coding agent" walkthrough to note
multi-branch state as the default, with caps and the --main-only
escape hatch.
README.md (root):
- Expand the agent-facing surfaces section to list four surfaces, not
three: chat UI, CLI, MCP server, agent skill pack. Explain what the
skill pack does in one paragraph.
- Update the "Where this is going" outlook to acknowledge that the
transport gap is closed, the fluency gap is what the skill pack
addresses, and the open questions are now shape questions.
DECISIONS.md:
- Add "Why skill packs are a first-class surface, not documentation" —
records the reasoning for shipping versioned instruction files into
agent host project directories rather than a docs site, and explains
why Section 5 ("When NOT to checkpoint") gets equal weight to "When
to checkpoint."
- Add "Why smriti state is multi-branch by default" — records why the
default was flipped, what the hard caps are, that divergence
detection reuses the compare normalization, and that --main-only /
main_only=True preserves the legacy path for scripts.
ARCHITECTURE.md:
- Split the agent-facing backend section into runtime surfaces (CLI,
MCP, chat UI) and the onboarding surface (skill pack) to make the
distinction between how agents call Smriti and how they learn to
call Smriti explicit.
- Expand the CLI + MCP surface descriptions to reference the new V4
state endpoint and the new smriti_install_skill MCP tool (13 tools
now).
- Add a "Multi-branch state" subsection documenting the new endpoint,
the hard caps, the reuse of _diff_lists from lineage, and the
backward-compat story via --main-only / main_only=True.
- Update the API versioning table to note /api/v4/chat/spaces/{id}/state
as the agent-facing default alongside /head.
Five rounds of dogfood testing closed the basic agent handoff loop and MCP
shipped as the second transport. Update the docs to match:
- cli/README.md: replace the brief "Typical agent workflow" + "Multi-branch
workflow" sections with a transport-agnostic "Using Smriti from a coding
agent" walkthrough. CLI commands and their MCP tool equivalents are shown
side by side. Covers orient → work → checkpoint → hand off, the extractor
path (no hand-written JSON anymore), and the branching/compare/restore
flow.
- README.md (root): list MCP as a third surface alongside the chat UI and
CLI. Update the "Where this is going" outlook to acknowledge that the
handoff loop is proven and the open questions are now shape questions,
not transport questions.
- ARCHITECTURE.md: add MCP server as a third entry in the agent-facing
backend section, with the deliberate differences from the CLI (no cwd
auto-capture, no per-tool confirmation) spelled out.
- DECISIONS.md: keep the original "why CLI first, not MCP" entry as
historical context and add a "Shipping MCP as the second transport"
entry recording the design decisions made at ship time (same package,
FastMCP, stdio only, 12 tools, extract-only create_checkpoint, empty
project_root default, MagicMock unit tests).
Introduce a thin Python CLI that wraps the backend REST API. Seven
commands: space list, space create, state, checkpoint create,
checkpoint show, checkpoint list, checkpoint review. Reads piped
JSON on stdin for checkpoint create, prints a continuation-oriented
markdown brief for state. Supports --json on every command for
structured output.
Fixes a V2 schema drift where the commit response omitted
assumptions and artifacts, so the CLI can read full checkpoints
via the cleaner V2 single-resource endpoints. Updates README,
ARCHITECTURE, and DECISIONS to frame Smriti as a reasoning-state
backend with the chat UI and CLI as two clients of the same core.
Update README with restore UX, checkpoint review, assumptions,
and artifacts. Add when-to-use guidance. Sharpen problem statement
around drift and recovery. Update ARCHITECTURE with new checkpoint
fields and restore terminology. Add three new decisions to
DECISIONS.md. Document review endpoint and new fields in API docs.
