CLI-only local sync is a dead end: docs reference removed 'basic-memory sync', status --wait can never finish, bm reindex is the undiscoverable answer

[phernandez]

Summary

For CLI-only usage (no running MCP/API server), there is no discoverable way to index externally-created files, and the existing signposts actively mislead:

1. README.md:593 and the repo CLAUDE.md still reference basic-memory sync — the command no longer exists (No such command 'sync')
2. bm status correctly reports pending changes (notes/ +1 new)
3. bm status --wait claims to "block until indexing is complete" — but in CLI-only contexts it always times out: the SyncCoordinator that does the indexing starts in the API app lifespan (api/app.py:71), and the CLI's httpx ASGITransport never runs the lifespan, so no indexer is running and none will come
4. The actual answer is bm reindex (incremental filesystem scan by default) — verified working — but nothing points to it, and its name suggests rebuilding rather than picking up new files

Reproduction (v0.21.6 / main @ 650f88a)

mkdir -p ~/scratch/notes && echo "..." > ~/scratch/notes/note.md
bm project add scratch ~/scratch --local
bm status --project scratch              # → "notes/ +1 new"  ✓
bm sync                                  # → Error: No such command 'sync'
bm status --project scratch --wait --timeout 60
# → "Error: Timed out after 60s ... (1 pending change(s) remaining)"
bm tool read-note "notes/note" --project scratch --local   # → all-null payload
bm reindex --project scratch             # → indexes + embeds the file  ✓
bm tool read-note "notes/note" --project scratch --local   # → works  ✓

Suggested fixes (any subset)

• Update README/CLAUDE.md to stop referencing basic-memory sync
• Make bm status --wait fail fast (or warn) when no sync coordinator can run, pointing at bm reindex
• Consider a bm sync alias for bm reindex's incremental scan — it's what users coming from the documented workflow will type

Context

Found during #952 manual verification (section 1 CLI page sweep). Same session as #954–#958.

[claude]

Claude finished @phernandez's task in 1m 39s —— View job

---

Issue Triage

• Gather context and read relevant files
• Classify issue type, priority, component, and complexity
• Check for duplicate issues
• Add appropriate labels
• Provide triage summary

---

Analysis

No duplicates found. This is a unique issue combining a stale docs reference, a misleading CLI flag, and a discoverability gap.

Type: Bug + Documentation

This issue bundles three distinct problems:

1. Stale docs reference (documentation bug): README.md:593 contains a debugging code block referencing basic-memory sync, a command that no longer exists. The block appears orphaned after the environment variables table (likely a leftover from a previous version). Running it gives No such command 'sync'.

2. Misleading --wait flag (bug): bm status --wait is documented as "Block until indexing is complete" but in CLI-only contexts it will always time out. The SyncCoordinator that performs background indexing starts only in the API app lifespan (api/app.py:71); the CLI's httpx ASGITransport never runs the lifespan. The status command just polls get_status() in a loop (status.py:188-197) with no way to detect that no indexer will ever run.

3. Discoverability gap (enhancement): bm reindex is the correct CLI-only solution — it directly calls sync_service.sync() without needing a running API server (db.py:262-311). But its name suggests rebuilding rather than picking up new files, and nothing in the --wait timeout error or docs points users toward it.

Priority: Medium

• Affects all CLI-only users (no running MCP/API server) who follow the documented workflow
• A working workaround (bm reindex) exists but is undiscoverable
• The stale basic-memory sync reference is an active wrong turn in the docs

Component: cli, docs

Complexity: Simple to Medium

• Fixing the stale README reference: simple (remove/replace the orphaned code block)
• Making bm status --wait fail fast or warn in CLI-only context: medium (requires detecting that no watcher/coordinator is running — could check for a live MCP process or a coordinator signal file, or simply add a note to the --wait docstring and timeout error message pointing at bm reindex)
• Adding a bm sync alias for bm reindex's incremental scan: simple (a one-line Typer alias; lower priority but improves UX for users from the documented workflow)

Suggested implementation order:

1. Remove/replace the basic-memory sync reference in README.md:592-595
2. Update the StatusTimeout error message to suggest bm reindex as the fix
3. Update --wait help text to note it requires a running server
4. Optionally add a bm sync alias

[phernandez]

Additional data point: the import workflow hits the same dead end. bm import memory-json writes the markdown files but the entities are unreadable until a manual bm reindex — and status --wait's own help text ("e.g. after a bulk import") sends users straight into the never-completing wait. Verified: import → read returns null payload → bm reindex --project X → read works. Also noted while testing: the import commands have no --project flag, so imports land in whatever the default project is — switching the default and back (bm project default X --local) is the only targeting mechanism.

[phernandez]

Fixed in #981 (commit 1ad3a35, on main). bm status --wait timing out in a CLI-only session now says the wait can never finish (no sync coordinator runs on the ASGI path) and points at bm reindex --project <name> as the command that indexes. The stale basic-memory sync references are gone from README.md and CLAUDE.md. Regression test in tests/cli/test_status_wait_timeout.py.

The bm sync alias idea and the import-workflow gaps from the comment thread (bm import needing a manual reindex, no --project flag on import commands) were not part of #981 — worth a separate enhancement issue if they still sting. The PR body's comma-separated "Fixes" list only auto-closed the first issue (#954) — closing manually.