Document the full usage surface (browser, agent-via-HTTP, MCP App, demo, dev loops) #65

New issue

Closed

opened 2026-05-23 20:55:29 +00:00 by coilysiren · 1 comment

coilysiren commented

2026-05-23 20:55:29 +00:00

Owner

Originally filed by @coilysiren on 2026-05-03T06:36:49Z - https://github.com/coilysiren/repo-recall/issues/45

Context

The original scope here was a single dev-loop note for the MCP App path (Claude Desktop + cargo watch, no cargo pmcp preview). That's still in scope, but it's one corner of a bigger gap: repo-recall has grown five distinct usage surfaces and the docs are split across README sections, AGENTS.md, and tribal knowledge. A user (or a future-Kai) showing up cold has to reverse-engineer which surface fits their case.

The five surfaces

Browser dashboard - cargo run / brew service / make run, point a browser at http://127.0.0.1:7777.
Agent-via-HTTP - same server, Accept: application/json or ?format=json, /api/* endpoints, ETag/If-None-Match polling, the auto-mode prompt starters in the README.
MCP App - stdio MCP server exposed to Claude Desktop / ChatGPT / mcp-preview. Six tools, dashboard widget, fallback-to-MCP-only when port is taken.
Demo image - ghcr.io/coilysiren/repo-recall-demo:latest, synthetic fixtures, mutating endpoints 403, banner.
Push notifications - opt-in FCM-backed Web Push, signed deliveries, only outbound network call besides gh.

Each of those has its own dev loop, its own config knobs, and its own failure modes. The docs currently only walk through (1) and (2) cleanly.

Action

Reorganize so each surface has a self-contained section. Two-tier: a quick-reference table at the top mapping intent ('I want X') to surface, and a full subsection per surface covering boot, config, dev loop, and known gotchas.

Per-surface checklist:

Browser dashboard: existing README content is fine, just promote the env-var table out of the dev-loop section so it's findable from the user-facing path too.
Agent-via-HTTP: keep the prompt starters, add the ETag polling pattern as a code example (not just prose), document the data-* HTML attributes for parsing without JSON.
MCP App: claude_desktop_config.json snippet (already in README), the six tools enumerated with one-line descriptions each, the auto-fallback behavior when the HTTP port is taken, and the dev-loop notes from this issue's original body (three-port layout, cargo watch, DevTools-on-iframe).
Demo image: how to run it, what the synthetic dataset contains, what's gated (mutating endpoints, network), and the rebuild path for fixture changes.
Push notifications: what signs the deliveries, where the keypair lives, opt-in flow, what gets sent (action-required deltas only? full signal? worth being explicit), and how to revoke.

MCP App dev loop (the original scope, preserved)

While testing #36 locally, the obvious-looking dev loop (cargo pmcp preview from paiml/cargo-pmcp) does not apply: it only drives HTTP MCP servers, and repo-recall is stdio-only.

Live widget render + protocol inspection: wire a dev instance into Claude Desktop's claude_desktop_config.json on a non-conflicting port (7778), then right-click the rendered widget -> Inspect to get DevTools on the iframe.
Iterative widget edits: src/widgets/dashboard.html is include_str!'d at compile time, so every edit needs a rebuild. cargo watch (or make watch port=7779 cwd=<scan-target>) handles that. Claude Desktop picks up the new bytes on the next tools/call.
Three-port layout so brew-services, Claude Desktop, and cargo watch can all run simultaneously without DB cross-contamination (db path is per-port already, see src/main.rs:60):
- 7777 brew services (untouched, prod default)
- 7778 Claude Desktop MCP-spawned instance
- 7779 cargo watch manual dev
Optional: make watch-mcp target with the dev port pre-set.

Out of scope

A from-scratch user manual or website. The home for this is README.md + AGENTS.md, kept short.
Tutorials or video content (those are #32 and #43).
Per-MCP-host troubleshooting beyond Claude Desktop. ChatGPT and mcp-preview get a sentence each, not a guide.

_Originally filed by @coilysiren on 2026-05-03T06:36:49Z - [https://github.com/coilysiren/repo-recall/issues/45](https://github.com/coilysiren/repo-recall/issues/45)_ ## Context The original scope here was a single dev-loop note for the MCP App path (Claude Desktop + cargo watch, no `cargo pmcp preview`). That's still in scope, but it's one corner of a bigger gap: repo-recall has grown five distinct usage surfaces and the docs are split across README sections, AGENTS.md, and tribal knowledge. A user (or a future-Kai) showing up cold has to reverse-engineer which surface fits their case. ## The five surfaces 1. **Browser dashboard** - `cargo run` / brew service / `make run`, point a browser at `http://127.0.0.1:7777`. 2. **Agent-via-HTTP** - same server, `Accept: application/json` or `?format=json`, `/api/*` endpoints, ETag/`If-None-Match` polling, the auto-mode prompt starters in the README. 3. **MCP App** - stdio MCP server exposed to Claude Desktop / ChatGPT / mcp-preview. Six tools, dashboard widget, fallback-to-MCP-only when port is taken. 4. **Demo image** - `ghcr.io/coilysiren/repo-recall-demo:latest`, synthetic fixtures, mutating endpoints 403, banner. 5. **Push notifications** - opt-in FCM-backed Web Push, signed deliveries, only outbound network call besides `gh`. Each of those has its own dev loop, its own config knobs, and its own failure modes. The docs currently only walk through (1) and (2) cleanly. ## Action Reorganize so each surface has a self-contained section. Two-tier: a quick-reference table at the top mapping intent ('I want X') to surface, and a full subsection per surface covering boot, config, dev loop, and known gotchas. Per-surface checklist: - [ ] **Browser dashboard**: existing README content is fine, just promote the env-var table out of the dev-loop section so it's findable from the user-facing path too. - [ ] **Agent-via-HTTP**: keep the prompt starters, add the ETag polling pattern as a code example (not just prose), document the `data-*` HTML attributes for parsing without JSON. - [ ] **MCP App**: claude_desktop_config.json snippet (already in README), the six tools enumerated with one-line descriptions each, the auto-fallback behavior when the HTTP port is taken, and the dev-loop notes from this issue's original body (three-port layout, cargo watch, DevTools-on-iframe). - [ ] **Demo image**: how to run it, what the synthetic dataset contains, what's gated (mutating endpoints, network), and the rebuild path for fixture changes. - [ ] **Push notifications**: what signs the deliveries, where the keypair lives, opt-in flow, what gets sent (action-required deltas only? full signal? worth being explicit), and how to revoke. ## MCP App dev loop (the original scope, preserved) While testing #36 locally, the obvious-looking dev loop (`cargo pmcp preview` from paiml/cargo-pmcp) does not apply: it only drives HTTP MCP servers, and `repo-recall` is stdio-only. - **Live widget render + protocol inspection**: wire a dev instance into Claude Desktop's `claude_desktop_config.json` on a non-conflicting port (7778), then right-click the rendered widget -> Inspect to get DevTools on the iframe. - **Iterative widget edits**: `src/widgets/dashboard.html` is `include_str!`'d at compile time, so every edit needs a rebuild. `cargo watch` (or `make watch port=7779 cwd=<scan-target>`) handles that. Claude Desktop picks up the new bytes on the next `tools/call`. - **Three-port layout** so brew-services, Claude Desktop, and `cargo watch` can all run simultaneously without DB cross-contamination (db path is per-port already, see `src/main.rs:60`): - 7777 brew services (untouched, prod default) - 7778 Claude Desktop MCP-spawned instance - 7779 `cargo watch` manual dev - Optional: `make watch-mcp` target with the dev port pre-set. ## Out of scope - A from-scratch user manual or website. The home for this is README.md + AGENTS.md, kept short. - Tutorials or video content (those are #32 and #43). - Per-MCP-host troubleshooting beyond Claude Desktop. ChatGPT and mcp-preview get a sentence each, not a guide.

coilysiren added the

label

2026-05-31 01:54:59 +00:00

coilysiren added

and removed

labels

2026-06-04 08:16:38 +00:00

coilysiren commented

2026-06-17 08:24:25 +00:00

Author

Owner

Backlog burndown 2026-06-17: closing low-priority (P3/P4) to bring the open count to a manageable level. Nothing lost — reopen if this resurfaces. Batch tag: burndown-2026-06.

Backlog burndown 2026-06-17: closing low-priority (P3/P4) to bring the open count to a manageable level. Nothing lost — reopen if this resurfaces. Batch tag: `burndown-2026-06`.

coilysiren

2026-06-17 08:24:25 +00:00