task: UX, install, watcher, docs & small features (15 issues)

[DeusData]

Scope

Umbrella tracker for UX, install ergonomics, watcher behavior, docs, error messaging, and small feature requests. Lower individual severity, high collective impact on first-impressions and day-to-day use.

Sub-issues

Search/regex UX

• search_code rejects paths containing & (ampersand) #272 — search_code rejects paths containing & (ampersand)
• search_code: default regex=false treats | as literal pipe, not alternation (silent 0-match trap) #282 — search_code: default regex=false treats | as literal pipe, not alternation (silent 0-match trap)
• search_code: invalid regex under regex: true silently returns empty instead of erroring #283 — search_code: invalid regex under regex: true silently returns empty instead of erroring

Install / watcher

• Watcher does not auto-reindex git-visible untracked file on Linux stdio MCP session (v0.6.0) #285 — Watcher does not auto-reindex git-visible untracked file on Linux stdio MCP session
• install.sh adds sh-style PATH manipulation to fish config #319 — install.sh adds sh-style PATH manipulation to fish config
• Add config key to disable file watcher #335 — Add config key to disable file watcher

UI / server

• Add a --host parameter for UI #229 — Add a --host parameter for UI
• v0.6.1 macOS arm64: --ui=true persists config but HTTP server never starts #350 — v0.6.1 macOS arm64: --ui=true persists config but HTTP server never starts

MCP / CLI behavior & messaging

• vendor/ directory indexed despite being excluded in root .gitignore #234 — vendor/ directory indexed despite being excluded in root .gitignore
• manage_adr (MCP/CLI) and the UI /api/adr endpoints use separate storage backends #256 — manage_adr (MCP/CLI) and the UI /api/adr endpoints use separate storage backends
• index_status returns project-not-found for project returned by list_projects #349 — index_status returns project-not-found for project returned by list_projects
• Add markdown memory.md #346 — Add markdown memory.md (session state file)

Docs

• Website outdated (agent support) #275 — Website outdated (agent support)
• Where can I find docs for configuration files? #359 — Where can I find docs for configuration files?
• [Question] How to measure gain/savings? #361 — [Question] How to measure gain/savings?

Acceptance

1. Each linked issue is either fixed, documented as intended behavior, or closed as out of scope with rationale.
2. Configuration file reference is fully documented (closes Where can I find docs for configuration files? #359).
3. Error messages are actionable — e.g. index_status and list_projects accept the same project selectors (closes index_status returns project-not-found for project returned by list_projects #349).

Why one task

These are individually low-severity but collectively erode confidence on first use. Treating them as one focused UX pass produces a coherent improvement instead of scattered drive-by fixes.

[DeusData]

Bug-tagged progress (2026-05-31) — the defect subset of this umbrella has been worked:

Fixed + closed:

• install.sh adds sh-style PATH manipulation to fish config #319 — installer wrote sh-syntax PATH into fish config → now emits fish_add_path
• index_status returns project-not-found for project returned by list_projects #349 — index_status not-found for a listed project → project names now always validator-safe
• v0.6.1 macOS arm64: --ui=true persists config but HTTP server never starts #350 — macOS --ui=true silent no-op → clear stderr message when binary lacks the embedded UI
• manage_adr (MCP/CLI) and the UI /api/adr endpoints use separate storage backends #256 — manage_adr (file) vs UI /api/adr (SQLite) split → unified on the store, with file→SQLite migration
• Watcher does not auto-reindex git-visible untracked file on Linux stdio MCP session (v0.6.0) #285 — watcher not auto-reindexing untracked files → verified fixed by the C watcher rewrite (regression test watcher_detects_new_file)
• search_code: invalid regex under regex: true silently returns empty instead of erroring #283 — search_code invalid regex silently empty → now returns an explicit error
• vendor/ directory indexed despite being excluded in root .gitignore #234 — vendor/ indexed despite root .gitignore → verified fixed + regression guard

Still open (tracked, not silently dropped):

• search_code: default regex=false treats | as literal pipe, not alternation (silent 0-match trap) #282 — regex=false treats | literally — by-design default; the "silent" half is addressed by search_code: invalid regex under regex: true silently returns empty instead of erroring #283, a 0-match metachar hint is a tracked enhancement
• search_code rejects paths containing & (ampersand) #272 — search_code rejects & in paths — security-sensitive (shared shell-arg validator); needs an audited fix or argv-exec rework, tracked

The remaining children (#229, #275, #335, #346, #359, #361) are UX/feature enhancements rather than defects.