feat(phase-57): shop window, positioning, and supported-surface trim

[RichardHightower]

Closes the v3.1 GSD work: Phase 57 Shop Window & Positioning. Phase 58 is a launch side quest, not a GSD phase.

57-01 Repo hygiene

• Root README.md — the repo had no landing page. Local-first pitch, ASCII architecture diagram, a quickstart that was actually executed, an honest status table, the supported-surface tiers, and a docs index.
• LICENSE (MIT), matching workspace.package.license.
• workspace.package.repository was spillwave/agent-memory; now matches the real remote.

57-02 Positioning

docs/positioning/agent-memory-vs-competition.md — head-to-head vs Mem0 / Zep / MemMachine / Letta across memory model, capture cost, locality, reach, provenance and evolution; leads with the three structural differences (passive zero-token capture, local-first, cross-CLI). Includes:

• a "where they are ahead of us" section (Zep's fact-validity intervals, Letta's paging, everyone else's SDK story)
• the platform-risk answer stated before a commenter can state it
• a claims ledger with sources and check dates

The Phase 56 gate is honored. MemMachine publishes 0.9169 on LoCoMo. Our only committed artifacts are a mock-backend custom harness and a 4-question mock-judge smoke run. The doc says so and makes no comparative accuracy claim anywhere.

57-03 Scope trim

Tier	Runtimes	CI
Tier 1 — supported	Claude Code, Codex CLI	gates every PR (e2e-cli.yml)
Tier 2 — best effort	Gemini CLI, Copilot CLI	weekly + dispatch (e2e-cli-tier2.yml)
Removed	OpenCode	—

OpenCode was removed, not archived. Every method of OpenCodeConverter returned empty, so memory-installer --agent opencode --project exited 0 and wrote no files. Deleted: the converter, the Runtime::OpenCode variant, its tool mappings, its 25-test bats suite, and the archived plugins/memory-opencode-plugin/ stub. In its place, every_offered_runtime_converts_something iterates Runtime::value_variants() and fails if any offered runtime produces nothing.

$ memory-installer install --agent opencode --project
error: invalid value 'opencode' for '--agent <AGENT>'
  [possible values: claude, gemini, codex, copilot, skills]
$ echo $?
2

Defects the quickstart found — and what changed

The README was written first, then run verbatim on a wiped store. Three defects surfaced, all in the "documented happy path silently does nothing" family this milestone exists to kill:

1. Search returned nothing for content just added. A fresh store has no db/search or db/vector, and both the outbox indexing job and the prune jobs only register when their directory already exists — so a first-run daemon accepted events forever and answered every query with results: [], confidence 0.0, and no error. start_daemon now creates both directories.
2. The remedy the daemon itself printed didn't work. admin rebuild-indexes failed on the RocksDB lock while the daemon ran, and reported "No documents found" when stopped — it indexes TOC nodes and grips, not raw events. Moot after fix 1.
3. admin rebuild-toc printed a TODO and exited 0, and its --dry-run advertised "To actually rebuild, run without --dry-run", which was false. It now fails with guidance and exits 1 — the same treatment Phase 54 gave --background.

Two retrieval truths were written into the README rather than left for a user to trip over: indexing is a ~1 minute scheduled outbox drain, not synchronous with ingest; and BM25 does not stem (jwt does not match JWTs), so the second example was changed to a query BM25 can answer.

Execution evidence

docs/verification/57-quickstart-transcript.md — the quickstart run start to finish on a container with no Rust toolchain, no protoc, no libclang, and no store, including the failures above and the passing re-run:

$ memory search "which JWT signing algorithm did we pick" --top 5
{"results":[{"doc_id":"01M1AC7CSHMS9XN65TPACNBHDF","doc_type":"event","score":0.0127,
"source_layer":"bm25","text_preview":"We chose RS256 over HS256 for the auth service JWTs"}],...}

text_preview populated on an event hit is the Phase 54.5 TEXT | STORED fix visible end-to-end.

The transcript also states what it does not establish: vector search was not exercised (this container's proxy blocks the Hugging Face model download — the daemon warned and ran BM25-only, as documented), no hooks were installed into a live agent, it is not a performance measurement, and macOS was not tested.

Not done, stated rather than waved through

• GitHub repo description, topics and Discussions — repository settings, cannot be changed from a PR. Maintainer action before launch.
• asciinema/GIF demo — not recorded; the executed transcript is committed instead.

Validation

cargo fmt --all -- --check, cargo clippy --workspace --all-targets --all-features -- -D warnings, cargo test --workspace --all-features --exclude e2e-tests, cargo test -p e2e-tests --all-features, and RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --workspace --all-features all green locally.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_014nSJ2c7F9mpmRCxfTAi214

---

Generated by Claude Code