docs: align with 0.6.10 CLI and headless changes

Remove memtrace service/daemon install guidance, document --headless
and MEMTRACE_HEADLESS, fix hook health URL, add Claude Code hook JSON
troubleshooting, and mark legacy daemon.log / daemon env vars obsolete.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Alex Holmberg

docs/README.md

@@ -46,6 +46,8 @@ look up later":
 | [`privacy-and-telemetry.md`](privacy-and-telemetry.md) | What stays on your machine, what's optionally sent to us, how to turn telemetry off. |
 | [`v0.4.60-release-notes.md`](v0.4.60-release-notes.md) | The memory-footprint round: −15% RSS, 35× tighter variance, −41% binary, no behaviour change. Two new env knobs (`MEMTRACE_UNIFIED_CACHE_MB`, `MEMTRACE_ORT_LOW_RSS`); both have sensible defaults. |
 
+**0.6.10 highlights** (see also [`cli-reference.md`](cli-reference.md) and [`environment-variables.md`](environment-variables.md)): fixes for GitHub issues #7–#17 (Claude Code hook JSON, graph/stats/temporal accuracy), unified `--headless` / `MEMTRACE_HEADLESS`, and removal of `memtrace service` / OS login autostart.
+
 ## The 90-second tour
 
 ```bash

docs/architecture.md

@@ -107,13 +107,17 @@ On a fresh repo, run `memtrace index .`, run `memtrace start` and let
 auto-index finish, or let an MCP-enabled agent call `index_directory`
 before expecting graph-backed answers.
 
-### Headless service mode
+### Headless / background runtime
 
-When you want Memtrace to stay available without an open terminal, use
-the daemon service commands (`memtrace daemon install`, then
-`memtrace daemon start`) where supported. That gives the machine a
-background workspace owner. Later `memtrace mcp` processes attach to
-it instead of opening their own embedded MemDB.
+`memtrace start --headless` (or `MEMTRACE_HEADLESS=1`) keeps the HTTP
+API on `:3030` without auto-opening a browser tab. For a persistent
+owner without a visible terminal, run that command under tmux, screen,
+or your own supervisor.
+
+OS login autostart (`memtrace service install` / `memtrace daemon`)
+was removed in **0.6.10**. Agent-only workflows can rely on
+`memtrace mcp`, which attaches to an existing owner or becomes the
+owner for that session.
 
 ## How duplicate owners are avoided
 

docs/cli-reference.md

@@ -18,11 +18,10 @@ memtrace --help
 | Command | Purpose |
 |---|---|
 | `memtrace start` | Start the local UI/API server, file watcher, PR command loop, and workspace owner against MemDB. This is also the default command when you run `memtrace` with no subcommand. |
-| `memtrace stop` | Stop the running Memtrace daemon. |
+| `memtrace stop` | Stop the running `memtrace start` workspace runtime (and unload any legacy OS service registrations from older installs). |
 | `memtrace status` | Show backend, index, and runtime status. |
 | `memtrace mcp` | Run the MCP server for Claude, Cursor, Codex, and other MCP-compatible agents. It attaches to an existing workspace owner or becomes the owner if none is running. |
 | `memtrace index <path>` | Index a repository or workspace into MemDB, then exit. |
-| `memtrace daemon install/start/status/stop` | Install or control the optional background service where supported. |
 | `memtrace code-review setup` | Choose the default headless agent for `@memtrace fix this`. |
 | `memtrace code-review --pr <url>` | Review a GitHub pull request using local Memtrace context. |
 | `memtrace pr status` | Show local PR watches registered by `memtrace code-review --post --watch`. |
@@ -65,8 +64,10 @@ owners for the same workspace.
 | `--clear`, `--fresh` | `start`, `index` | Wipe the resolved local MemDB data directory before connecting. |
 | `--workspace <path>` | `start`, `index`, `mcp` workspace resolution | Treat `path` as a multi-repo workspace root and write a `.memtrace-workspace` marker there. |
 | `--no-workspace` | `start` | Disable the auto-workspace behavior when the current directory looks like a parent folder containing multiple git repos. |
-| `--no-ui`, `--headless` | `start` | Skip the HTTP UI/API server entirely (no bind on `MEMTRACE_UI_PORT`). Use when you truly do not need health, search, or the value ledger. |
-| `--no-browser` | `start` | Keep the HTTP UI/API server on `MEMTRACE_UI_PORT` but do not auto-open a browser tab on startup. Prefer this for Orbit, CI, and headless hosts that still need `:3030`. |
+| `--headless` | `start` | Keep the HTTP API on `MEMTRACE_UI_PORT` (default `3030`) but do not auto-open a browser tab. Use for Orbit, CI, and agent hosts. |
+| `--no-ui`, `--no-browser` | `start` | **Deprecated aliases** for `--headless` (one-time note on first use). Prefer `--headless` or `MEMTRACE_HEADLESS=1`. |
+
+> **Removed in 0.6.10:** `memtrace service` / `memtrace daemon` (OS login autostart install) was removed. Use `memtrace start` (optionally `--headless`) or `memtrace mcp`. `memtrace stop` still tears down legacy launchd/systemd/Windows service registrations if an older install left them behind.
 
 ## Code review
 
@@ -174,9 +175,10 @@ MEMTRACE_UI_PORT=3030
 
 | Variable | Purpose |
 |---|---|
-| `MEMTRACE_UI_PORT` | Local UI port. Default: `3030`. |
-| `MEMTRACE_NO_UI` | Skip HTTP UI/API server (`1`, `true`, `yes`, or `on`). |
-| `MEMTRACE_NO_BROWSER` | Keep UI server; skip auto-open browser on start. |
+| `MEMTRACE_UI_PORT` | Local HTTP API + dashboard port. Default: `3030`. |
+| `MEMTRACE_UI_HOST` | Bind address for the HTTP API. Default: `127.0.0.1`. Set only when you intentionally need remote/VM/container exposure. |
+| `MEMTRACE_HEADLESS` | Skip browser auto-open on `memtrace start` (`1`, `true`, `yes`, or `on`). API stays up. |
+| `MEMTRACE_NO_UI`, `MEMTRACE_NO_BROWSER` | Deprecated aliases for `MEMTRACE_HEADLESS`. |
 | `MEMTRACE_TRANSPORT` | MCP transport: `stdio`, `streamable-http`, `sse`, or `http`. |
 | `MEMTRACE_PORT` | MCP HTTP port when transport is not stdio. |
 | `MEMTRACE_DATA_DIR` | Job state directory. |
@@ -185,7 +187,8 @@ MEMTRACE_UI_PORT=3030
 | `MEMTRACE_MEMDB_ENDPOINT` | Remote-mode MemDB gRPC endpoint. |
 | `MEMTRACE_EMBED_MODEL` | Local embedding preset when using local embeddings. |
 | `MEMTRACE_VECTOR_DIMS` | Explicit vector dimension override. Prefer `memtrace embed set` for normal use. |
-| `MEMTRACE_SKIP_EMBED` | Skip embedding work. Structural graph remains usable. |
+| `MEMTRACE_SKIP_EMBED` | Skip all embedding (index, watcher, search). Structural graph remains usable. |
+| `MEMTRACE_SKIP_WATCHER_EMBED` | Skip per-save watcher embedding only; keep index-time embed. |
 | `MEMTRACE_NO_REPLAY` | Skip git-history replay. HEAD graph remains usable. |
 | `MEMTRACE_OWNER_ATTACH` | Set to `0` to force legacy direct embedded open for debugging. |
 | `MEMTRACE_START_PHASE2` | Set to `foreground` to run embedding/replay in the foreground instead of background phase 2. |

docs/data-directories.md

@@ -22,7 +22,7 @@ when (if ever) to delete it.
    ├── auth/                ← session tokens (one file)
    ├── config.toml          ← persistent embedder choice — see embedding-providers.md
    ├── last_health.json     ← last `memtrace embed test` probe result
-   ├── logs/                ← daemon.log + rotated history (v0.3.89)
+   ├── logs/                ← legacy daemon.log from pre-0.6.10 OS service installs (if any)
    ├── session-ledger.jsonl ← user-global MCP tool-call ledger (v0.3.89)
    ├── watches.json         ← persistent watch_directory registrations (v0.3.89)
    └── telemetry/           ← buffered events (only if telemetry is ON)
@@ -263,25 +263,17 @@ crashes (useful for your own debugging), but the flusher never
 ships it. If you've never run `memtrace start`, the directory
 doesn't exist yet.
 
-## `~/.memtrace/logs/daemon.log` (v0.3.89)
+## `~/.memtrace/logs/` (legacy)
 
-Daemon startup + error log. Rolling file appender:
+Versions before **0.6.10** that used `memtrace daemon install` may
+have left rolling logs here (`daemon.log` + dated rotations). Current
+binaries do not write this file — runtime diagnostics go to stderr;
+use `RUST_LOG=info memtrace start` or `MEMTRACE_DEBUG=1` when
+debugging startup failures.
 
-```
-~/.memtrace/logs/
-├── daemon.log         # current
-├── daemon.2026-05-10.log
-├── daemon.2026-05-09.log
-└── …                  # up to 5 files retained, rotated at 10 MB each
-```
-
-Populated from the first daemon-startup tick, so even an
-"exits-immediately" failure leaves a breadcrumb. Created on first
-`memtrace daemon start` after upgrading to v0.3.89.
-
-Override the location with `MEMTRACE_LOGS_DIR=<absolute path>` if
-you want logs somewhere else. Safe to delete the directory at any
-time — it'll be recreated on the next daemon start.
+Safe to delete the directory at any time. It is not recreated unless
+you still have a legacy OS service registration from an older install
+(in which case `memtrace stop` unloads it).
 
 ## `~/.memtrace/session-ledger.jsonl` (v0.3.89)
 

docs/environment-variables.md

@@ -14,7 +14,8 @@ the defaults auto-tune to your machine.
 - [Resource caps](#resource-caps)
 - [Install / uninstall lifecycle (v0.3.89)](#install--uninstall-lifecycle-v0389)
 - [Watch persistence (v0.3.89)](#watch-persistence-v0389)
-- [Daemon lifecycle (v0.3.89)](#daemon-lifecycle-v0389)
+- [Headless / browser (v0.6.10)](#headless--browser-v0610)
+- [Legacy daemon lifecycle (removed v0.6.10)](#legacy-daemon-lifecycle-removed-v0610)
 - [MemDB connection (advanced)](#memdb-connection-advanced)
 - [Telemetry + auth](#telemetry--auth)
 
@@ -24,9 +25,11 @@ the defaults auto-tune to your machine.
 |---|---|---|
 | `MEMTRACE_TRANSPORT` | `stdio` | How `memtrace mcp` talks to its agent. See [`mcp-and-transports.md`](mcp-and-transports.md). Values: `stdio`, `streamable-http`, `sse` (alias for streamable-http), `http` (alias for streamable-http). Anything else is rejected with a clear error since v0.3.32. |
 | `MEMTRACE_PORT` | `3000` | When transport is HTTP, the port `memtrace mcp` binds. |
-| `MEMTRACE_UI_PORT` | `3030` | The local dashboard. Always-on while the daemon is running (unless `MEMTRACE_NO_UI` / `--no-ui`). |
-| `MEMTRACE_NO_UI` | (unset) | Set to `1` to skip the HTTP UI/API server entirely. Alias: `MEMTRACE_HEADLESS`. |
-| `MEMTRACE_NO_BROWSER` | (unset) | Set to `1` to keep the UI server on `MEMTRACE_UI_PORT` but skip auto-opening a browser tab on `memtrace start`. Same as `--no-browser`. |
+| `MEMTRACE_UI_PORT` | `3030` | Local HTTP API + dashboard port while `memtrace start` (or an attached owner) is running. |
+| `MEMTRACE_UI_HOST` | `127.0.0.1` | Bind address for the HTTP API. Set to `0.0.0.0` only when you intentionally need remote/VM/container exposure. |
+| `MEMTRACE_HEADLESS` | (unset) | Set to `1` to skip auto-opening a browser tab on `memtrace start`. The API stays bound on `MEMTRACE_UI_PORT`. Same as `--headless`. |
+| `MEMTRACE_NO_UI` | (unset) | **Deprecated alias** for `MEMTRACE_HEADLESS` (skips browser only — does not disable the HTTP API). |
+| `MEMTRACE_NO_BROWSER` | (unset) | **Deprecated alias** for `MEMTRACE_HEADLESS`. Prefer `MEMTRACE_HEADLESS=1` or `memtrace start --headless`. |
 | `MEMTRACE_WS_PORT` | `3031` | Internal WebSocket bus that pushes index events to the UI. Don't change unless 3031 is taken. |
 
 ## On-disk locations
@@ -68,6 +71,8 @@ the defaults auto-tune to your machine.
 | `MEMTRACE_FIELD_BOOST_BODY_STRINGS` | `0.5` | **(v0.3.82)** BM25 weight on the new `body_strings` field (function-body string literals extracted at index time). Improves recall on natural-language → log-line queries. |
 | `MEMTRACE_DISABLE_COREML` | (unset) | Set to `1` on Apple Silicon to force CPU execution provider instead of CoreML / ANE. Useful if CoreML's first-run graph compile hangs on your machine. |
 | `MEMTRACE_TIER` | auto-detected (`light` / `standard` / `heavy`) | Force the host tier instead of letting Memtrace pick from RAM + CPU + accelerator signals. |
+| `MEMTRACE_SKIP_EMBED` | (unset) | Set to `1` to disable **all** embedding (index, watcher, semantic search). Structural graph tools still work. |
+| `MEMTRACE_SKIP_WATCHER_EMBED` | (unset) | Set to `1` to disable per-save watcher embedding only; index-time embedding still runs. |
 
 ## Reranker
 
@@ -126,7 +131,7 @@ Branch switch (`git checkout other-branch`) re-targets the watcher to the new ac
 |---|---|---|
 | `MEMTRACE_HOOK_MODE` | `advisory` | Set to `off` for unconditional no-op of the UserPromptSubmit hook. |
 | `MEMTRACE_HOOK_DEBOUNCE_SECS` | `120` | Per-session debounce window. After the hook fires once for a session, suppresses further fires within this window. Set to `0` to disable debounce (every message fires). |
-| `MEMTRACE_HEALTH_URL` | `http://localhost:3030/health` | Where the hook probes daemon liveness. Override for non-default UI ports. |
+| `MEMTRACE_HEALTH_URL` | `http://localhost:3030/api/health` | Where the Claude Code `UserPromptSubmit` hook probes runtime liveness. Override for non-default UI ports. |
 
 Session ID resolution (used to key the lock file at `~/.memtrace/hook-debounce/<session_id>.lock`):
 1. `CLAUDE_SESSION_ID` env (if Claude Code sets it)
@@ -159,16 +164,23 @@ After @Magalz's report that `watch_directory` registrations vanished on MCP disc
 
 The watch file is a JSON array of `{ path, repo_id, registered_at, origin }` objects; `origin` is `"manual"` for entries you registered explicitly via `watch_directory` and `"restored"` for entries that were re-armed from a prior session.
 
-## Daemon lifecycle (v0.3.89)
+## Headless / browser (v0.6.10)
 
-After @Magalz's report that `memtrace daemon start` was reporting "started" while the daemon silently exited 2-3 s later on Windows, the launcher now health-checks before declaring success.
+`memtrace start --headless` (or `MEMTRACE_HEADLESS=1`) keeps the HTTP API on `:3030` but skips auto-opening a browser tab. This is the recommended mode for Orbit, CI, and agent hosts that need health/search endpoints without a GUI session.
 
-| Var | Default | Purpose |
-|---|---|---|
-| `MEMTRACE_DAEMON_HEALTH_TIMEOUT_MS` | `10000` | How long `memtrace daemon start` polls `/api/health` before giving up and printing the "did not bind within Ns" warning. Increase on slow / cold-cache Windows hosts. |
-| `MEMTRACE_DAEMON_HEALTH_INTERVAL_MS` | `500` | Polling interval. |
+Legacy names `--no-ui`, `--no-browser`, `MEMTRACE_NO_UI`, and `MEMTRACE_NO_BROWSER` still work as aliases and print a one-time deprecation note.
+
+## Legacy daemon lifecycle (removed v0.6.10)
+
+`memtrace service` / `memtrace daemon install|start|status|stop` was removed in **0.6.10**. Use `memtrace start` (foreground or `--headless` in tmux/screen/nohup) or `memtrace mcp` for agent workflows. `memtrace stop` still unloads legacy launchd/systemd/Windows service registrations if an older install left them behind.
+
+The following env vars are **obsolete** and ignored by current binaries:
 
-The daemon now also writes `~/.memtrace/logs/daemon.log` (rotated at 10 MB, max 5 files) from its first startup tick, so even an "exits immediately" failure leaves a breadcrumb. Run `memtrace daemon start --foreground` (alias `--verbose`) to skip the detach and see stderr directly in your shell.
+| Var | Was used for |
+|---|---|
+| `MEMTRACE_DAEMON_HEALTH_TIMEOUT_MS` | `memtrace daemon start` health poll (removed) |
+| `MEMTRACE_DAEMON_HEALTH_INTERVAL_MS` | `memtrace daemon start` health poll interval (removed) |
+| `MEMTRACE_LOGS_DIR` | Override for `~/.memtrace/logs/daemon.log` (file logging removed with OS service install) |
 
 ## MemDB connection (advanced)
 

docs/getting-started.md

@@ -134,17 +134,22 @@ tools will have little or no project context until you run
 `memtrace index .`, run `memtrace start` and let auto-index finish,
 or ask an MCP-enabled agent to call `index_directory`.
 
-If you want Memtrace available without an open terminal, use the
-daemon service commands where supported:
+If you want Memtrace available without an open browser tab (Orbit,
+CI, headless servers), start the workspace runtime in headless mode:
 
 ```bash
-memtrace daemon install
-memtrace daemon start
+memtrace start --headless
+# or: MEMTRACE_HEADLESS=1 memtrace start
 ```
 
-That gives the machine a background workspace owner. Later
-`memtrace mcp` processes attach to it instead of opening another
-embedded MemDB.
+The HTTP API stays on `http://localhost:3030`; only the browser
+auto-open is skipped. For a long-lived background owner without a
+visible terminal, run `memtrace start --headless` inside tmux,
+screen, or your process supervisor of choice.
+
+> **Note (0.6.10):** `memtrace service` / `memtrace daemon install`
+> was removed. Most agent workflows only need `memtrace mcp`, which
+> attaches to an existing owner or becomes the owner for that session.
 
 Working across several related repos (frontend + backend, a monorepo,
 a service mesh)? Index them under one **workspace** so they share a
@@ -208,7 +213,7 @@ After your first index:
 ## Stopping and resetting
 
 ```bash
-memtrace stop                  # stop the running daemon
+memtrace stop                  # stop the running workspace runtime
 memtrace reset                 # wipe the local MemDB (ALL repos)
 memtrace reset <repoId>        # wipe one repo's data only
 memtrace start --clear         # wipe and re-index in one go

docs/mcp-and-transports.md

@@ -231,9 +231,10 @@ your AI tool's MCP setup guide for the current shape.
 
 ### Operational notes
 
-- **Bind address is `0.0.0.0` by default.** If you need to restrict
-  to localhost only, run Memtrace inside a container or reverse-proxy
-  it. There's no built-in `bind=127.0.0.1` flag yet.
+- **HTTP API binds `127.0.0.1` by default** (since 0.6.0). Set
+  `MEMTRACE_UI_HOST=0.0.0.0` only when you intentionally need
+  remote/VM/container exposure. MCP HTTP transport (`MEMTRACE_PORT`)
+  bind behaviour is separate — see your orchestrator setup.
 - **Port collisions.** If `MEMTRACE_PORT` is already in use, you'll
   get a clear error pointing at the env var. Pick a free port.
 - **Auth.** The HTTP transport doesn't enforce auth at the MCP layer —

docs/performance-tuning.md

@@ -171,7 +171,7 @@ memtrace start
 ```
 
 For multi-tenant (orchestrator) deployments, bind streamable-HTTP
-and let many agents share one daemon — see
+and let many agents share one workspace runtime — see
 [`mcp-and-transports.md`](mcp-and-transports.md).
 
 ### "Indexing Django takes 14s — I want it faster"

docs/telemetry-compliance-datasheet.md

@@ -28,7 +28,7 @@ For a regulated environment, the recommendation is: keep product telemetry enabl
 ```
 Customer machine                                 Memtrace infrastructure
 ┌──────────────────────────┐                     ┌──────────────────────────┐
-│  memtrace daemon         │                     │                          │
+│  memtrace start runtime  │                     │                          │
 │  ┌────────────────────┐  │   HTTPS (TLS 1.3)   │  api.memtrace.io         │
 │  │ AST parser         │  │ ──────────────────▶ │  /api/device/auth        │
 │  │ MemDB (local)      │  │   License + heart-  │  /api/device/heartbeat   │