# Scubiee — end-user documentation

Machine-readable guide for AI assistants. Human UI: `/docs`. Product: local code context engine for Cursor, Claude Code, Kiro, Copilot, and more.

---

## Facts any assistant needs

- Product CLI + MCP server key: `scubiee` (not "context-engine").
- Data lives under `~/.scubiee` and `<repo>/.scubiee`.
- Correct order: `setup --repair` → `cd repo` → `init .` → `connect --…` → reload MCP.
- `init` indexes the repo; it does **not** write MCP or agent rules. `connect` does.
- `setup` alone does not make a repo managed. You still need `init` inside the project.
- Continue after pause/stop with `scubiee resume` — there is **no** `wake` command.
- Windows Access denied on upgrade → `scubiee unlock-tool`, then reinstall — not Admin/reboot.
- `machine_not_setup` / missing FastEmbed → `scubiee setup --repair`.
- Share diagnostics: `scubiee diagnose --no-tests --desktop` → `Desktop/scubiee-diagnose.json` (not source code).
- Python 3.10+. Install from PyPI with `uv tool install scubiee`. No need to clone GitHub.

---

## How it works

Scubiee indexes your repository locally, embeds code with CodeRank (GPU when available), and exposes search/map/focus over MCP. Only the embedding model (~270 MB) downloads during setup.

```
Your AI tool (Cursor / Kiro / Claude Code / …)
  ↓ MCP (stdio) — server name: scubiee
Scubiee MCP — status, map, focus, grep, glob, workspace
  ↓ HTTP localhost (default :8765)
Scubiee Engine — daemon + live re-indexing
  ↓
Your code index — vectors + graph + chunks under ~/.scubiee
```

| Step | Command | What it does |
|------|---------|--------------|
| 1 | `uv tool install scubiee` | Install the CLI |
| 2 | `scubiee setup --repair` | Machine setup — GPU/CPU/MLX, model, accel.json |
| 3 | `scubiee init .` | Enroll + index this repo — does not write MCP |
| 4 | `scubiee connect --…` | Write MCP + agent rules for your IDE |
| 5 | Reload MCP in the IDE | Agent `status()` → `managed: true` |

Adding a second repo only needs `init` (and Special-4 `connect` inside that project for Kiro/Copilot/Cline/Roo).

### The four layers

Most problems mean one layer is missing or stale. Why agents say `managed: false`: layer 3 or 4 is missing.

| Layer | Question | Command | Marker |
|-------|----------|---------|--------|
| 1. Install | Is scubiee installed? | `uv tool install scubiee` | `scubiee --version` |
| 2. Machine setup | GPU/CPU + model ready? | `scubiee setup --repair` | `~/.scubiee/accel.json` |
| 3. Repo enrollment | Is this folder indexed? | `scubiee init .` | `<repo>/.scubiee/id.json` |
| 4. IDE wiring | Does agent call MCP? | `scubiee connect --cursor` | MCP config + rules |

---

## Quick start

### macOS / Linux

```bash
uv tool install --force scubiee --index-url https://pypi.org/simple --refresh
uv tool update-shell
# open a new terminal
scubiee setup --repair
cd your-repo
scubiee init .
scubiee connect --cursor
# reload MCP in your IDE
```

### Windows (PowerShell)

```powershell
uv tool install --force scubiee --index-url https://pypi.org/simple --refresh
uv tool update-shell
# open a NEW PowerShell window
scubiee setup --repair
cd C:\path\to\your\repo
scubiee init .
scubiee connect --cursor
# Cursor → Settings → MCP → refresh
```

Prefer **uv tool install** over pip on Windows. Always pin `--index-url https://pypi.org/simple` on Windows. Shims usually live in `%USERPROFILE%\.local\bin`.

**What setup does:** detects hardware (CUDA, DirectML for discrete AMD/NVIDIA, MLX on Apple Silicon, or CPU); installs ONNX Runtime + FastEmbed; downloads CodeRank FP16 model; saves `~/.scubiee/accel.json`.

After broken reinstall: always `scubiee setup --repair` before `init`.

**Verify:**

```bash
scubiee --version
scubiee setup --status
scubiee doctor .
scubiee search "a symbol in your repo" .
scubiee diagnose --no-tests --desktop
```

In the agent, call MCP `status()` once. Expect `managed: true`, `ok: true` after init + connect + reload.

---

## Daily use

```bash
cd your-project
scubiee status .          # index health + sync state
scubiee sync .            # after git pull / large edits
scubiee search "AuthService" .
```

| Command | When |
|---------|------|
| `scubiee sync .` | After pulling changes or large local edits |
| `scubiee sync . --confirm` | When sync refuses with >400 file count |
| `scubiee rebuild .` | Full re-index (slow; fixes corruption) |
| `scubiee search "query" .` | CLI search — query first, path second |
| `scubiee search "query" . --local` | In-process search, no HTTP daemon |

**Multiple repos:**

```bash
scubiee list
scubiee activate /path/to/repo
scubiee pause /path/to/repo --reason "maintenance"
scubiee remove /path/to/other --delete-store
```

**Stop / resume (machine-wide):**

```bash
scubiee stop      # stop engine, free GPU / file locks
scubiee resume    # bring Scubiee back — NOT "wake"
```

**Settings:** `scubiee settings --show` · prefs at `~/.scubiee/prefs.json`

**Engine & dashboard:**

```bash
scubiee engine status .
scubiee engine ensure . --wait 45
scubiee dashboard --status
scubiee resources
```

Logs: `~/.scubiee/engine.log`, `~/.scubiee/watchdog.log`

**Environment variables:**

| Variable | Effect |
|----------|--------|
| `CTX_INCREMENTAL_MAX_TOUCH` | File-count cap before `--confirm` (default 400) |
| `CTX_FAST_ROOTS` | Comma roots for `--fast` indexing |
| `CTX_RM_DISABLE=1` | Disable RAM admission pauses |
| `CTX_MLX=0` | Force non-MLX path on Mac |

---

## Connect agents

| Command | Writes |
|---------|--------|
| `scubiee setup --repair` | Machine GPU/CPU/MLX profile, model cache |
| `scubiee init .` | Repo enrollment + index. **Not** MCP or rules |
| `scubiee connect --cursor` | Global `~/.cursor/mcp.json` + rules AND project `.cursor/mcp.json` (absolute CTX_REPO) |

```bash
scubiee connect --cursor
scubiee connect --claude-code
scubiee connect --codex
scubiee connect --cursor --dry-run
scubiee disconnect --cursor
```

### Cursor workspace pin (critical)

Cursor does **not** expand `${workspaceFolder}` in global `~/.cursor/mcp.json`. A literal token makes MCP resolve to your home folder → `managed: false`.

- Always run `scubiee connect --cursor` **from the project** you want managed.
- That writes project `.cursor/mcp.json` with an absolute `CTX_REPO` pin.
- After connect: Cursor → Settings → MCP → refresh until `scubiee` shows green.
- On Windows, MCP should use the uv tool shim (`%APPDATA%\uv\tools\scubiee\Scripts\…`).

### Multiple repos in one Cursor app

One MCP process is shared across chats.

- On `status()`, pass `root` = that chat's Workspace Path.
- `managed: true` only if that folder (walking up) has `.scubiee/id.json` and is in the registry.
- Other chats: `managed: false` after one `status()` — use native tools.
- After successful `status()`, you may pass `project_id` (`ce_…`) instead of full path.

### Special-4 (per-repo connect)

Run connect **inside each project**:

| Tool | Command | Typical file |
|------|---------|--------------|
| Kiro | `scubiee connect --kiro` | `.kiro/settings/mcp.json` |
| GitHub Copilot / VS Code | `scubiee connect --copilot` | `.vscode/mcp.json` |
| Cline | `scubiee connect --cline` | `.cline/mcp.json` |
| Roo Code | `scubiee connect --roo-code` | `.roo/mcp.json` |

**All connect flags:** `--cursor`, `--claude-code`, `--codex`, `--kiro`, `--windsurf`, `--copilot`, `--cline`, `--roo-code`, `--continue`, `--zed`, `--opencode`, `--amp`, `--pi`

MCP cannot start or wrong Python? Re-run `connect` for that tool, or `setup --repair`, then reload MCP.

---

## MCP tools

MCP server key: `scubiee`. Talks to local daemon (default `http://127.0.0.1:8765`).

**Agent rule policy:**

1. Call `status()` once at session start (pass `root` = workspace path when several repos share MCP).
2. If `managed` + `ok` → use Scubiee tools for discovery (map/grep/focus), not native Grep by default.
3. If `warming` → use tools; wait ~5s and retry the **tool** once; do not busy-loop on `status()`.
4. If unmanaged → native tools; retry `status()` only after user runs init/connect.
5. If paused/stopped → `scubiee resume` (not wake).

**status() fields:**

| Field | Meaning |
|-------|---------|
| `managed: true` | Workspace enrolled (after init) |
| `ok: true` | Daemon healthy — use Scubiee tools |
| `warming: true` | Managed but not ready — retry tool once; do not poll status() |
| `managed: false` | Use native tools; retry after init/connect |
| `should_retry_status: true` | User likely just ran init/connect — call status() once more |

**Tool catalog:**

| Tool | Purpose | Typical args |
|------|---------|--------------|
| `status` | Health + managed flag | `root=` or `project_id=` |
| `gate` | Tiny is-this-repo-ready check | automatic at chat start |
| `map` | Ranked overview of relevant chunks/symbols | query + root/project_id |
| `focus` | Deepen context around a hit | handle from map |
| `grep` | Exact/regex search of indexed content | pattern, optional glob= |
| `glob` | Find files by path pattern | pattern + root |
| `workspace` | Session context | root/project_id |
| `expand` | Re-open a previous code span | follow-up without re-searching |
| `register_project` | Explicit consent registration | path when prompted |

**Recommended flow:**

```
1. status(root=<workspace path>)     # once
2. map(query="auth middleware")
3. focus(...)
4. grep(pattern="AuthService")
5. Read/Edit only the lines you need
```

- Empty grep/glob with `truncated: false` = no match in **indexed** scope, not "file missing on disk".
- Stale results after edits: `scubiee sync .` then search again.
- Agent ignores MCP: MCP green? → `scubiee connect --cursor` → reload MCP → call `status()` once.

`connect` installs Cursor rule at `~/.cursor/rules/scubiee.mdc`. Re-run connect after upgrades.

---

## Windows

Most failures are **file locks** from Cursor MCP / daemon holding `%APPDATA%\uv\tools\scubiee` — not ACL permissions. Admin PowerShell does not help. Use `unlock-tool` instead of reboot.

**Access denied on upgrade:**

```powershell
scubiee unlock-tool
uv tool install --force scubiee --index-url https://pypi.org/simple --refresh
scubiee setup --repair
scubiee connect --cursor
```

**CLI already broken:**

```powershell
powershell -ExecutionPolicy Bypass -File scripts/uninstall-uv-scubiee.ps1
# or repair:
powershell -ExecutionPolicy Bypass -File scripts/repair-uv-scubiee.ps1
uv tool install --force scubiee --index-url https://pypi.org/simple --refresh
scubiee setup --repair
```

**GPU on Windows:** integrated Intel UHD / AMD APU → profile `cpu`. Discrete AMD/NVIDIA → `dml`. Verify with `scubiee setup --status`.

---

## GPU and profiles

| Profile | When |
|---------|------|
| `cpu` | No GPU, or integrated-only laptop |
| `dml` | Windows discrete AMD/NVIDIA (DirectML) |
| `cuda` | Linux NVIDIA |
| `mlx` | Apple Silicon (Metal) |

```bash
scubiee setup --status
scubiee setup --profile cpu --repair
scubiee setup --profile dml --repair
scubiee setup --profile mlx --repair
scubiee setup --profile cuda --repair
```

Apple Silicon should not stay on CPU after `--repair`. Force MLX with `--profile mlx --repair`.

---

## Indexing and projects

Always `cd` into project root before `init`. Do not run init from home folder. Indexes stay local under `~/.scubiee`.

**Where data lives:**

| Path | Role |
|------|------|
| `<repo>/.scubiee/id.json` | Binds folder to project_id (often gitignored) |
| `<repo>/.cursor/mcp.json` | Cursor project MCP pin (absolute CTX_REPO) |
| `~/.scubiee/registry.json` | All managed roots + lifecycle state |
| `~/.scubiee/projects/<id>/` | Index store (chunks, graph, vectors) |
| `~/.scubiee/accel.json` | GPU/CPU profile from setup |
| `~/.scubiee/engine.log` | Engine / daemon logs |
| `~/.cursor/mcp.json` | Cursor global MCP entry |
| `~/.cursor/rules/scubiee.mdc` | Cursor agent rule |
| `%APPDATA%\uv\tools\scubiee\` | Windows uv tool env |

Fresh installs do not use `.context-engine`. Daemon HTTP is localhost-only; MCP is stdio to IDE.

```bash
cd your-repo
scubiee init .
scubiee init . --fast
scubiee init . --fast --roots packages,src
scubiee init . --confirm                     # when >400 files
scubiee init . --no-index                    # register only
scubiee sync .
scubiee never-index . --reason "…"           # block path intentionally
```

**Fast mode** indexes `.py` under common roots (`packages`, `src`, `lib`, `app`, …) or your `--roots` list.

**Common issues:**

- **Refusing to index home/drive root:** Safety gate. `cd` into project, then `init .`.
- **>400 files need indexing:** Re-run with `--confirm`, or `--fast --roots …`.
- **never_index error:** Path was blocked. Clear via dashboard or lifecycle remove.
- **project_id_mismatch / stale home registration:** `scubiee list` then `scubiee remove C:\Users\YOUR_USER --delete-store`.

---

## Troubleshooting

**Run this triage first:**

```bash
scubiee --version
scubiee setup --status
scubiee preflight .
scubiee doctor .
scubiee list
scubiee diagnose --no-tests --desktop
```

If semantic preflight fails: `scubiee setup --repair`. If daemon cold: `scubiee engine ensure . --wait 45`.

| Command | When |
|---------|------|
| `unlock-tool` | Windows Access denied / free uv tool locks |
| `upgrade` | Upgrade with unlock/stop path |
| `setup --repair` | After broken reinstall or missing FastEmbed |
| `stop / resume` | Pause globally / continue (not wake) |
| `connect --…` | After install, upgrade, or unmanaged agent |
| `engine ensure . --wait 45` | Daemon not warm |
| `wipe --all --confirm --package` | Nuclear uninstall |

### Install sequence mistakes

- **Agent status() → managed: false** — Cause: never ran init/connect or wrong folder. Fix: `cd` project → `init .` → `connect --cursor` → reload MCP → `status()` once. Confirm project `.cursor/mcp.json` has absolute `CTX_REPO`.
- **Index exists but MCP missing** — Ran init only. Fix: `connect --…` then reload MCP.
- **Kiro/Copilot/Cline/Roo MCP empty** — Connected only globally. Fix: `cd` into that project → `connect --kiro` (or --copilot / --cline / --roo-code).
- **Agent polls status() every turn** — Old rule. Fix: re-run `connect`.
- **Hint says scubiee wake** — No wake command. Fix: `scubiee resume`. Upgrade + reconnect.

### machine_not_setup on init

Symptom: `{"ok": false, "error": "machine_not_setup"}` — no profile in `~/.scubiee/accel.json`.

```bash
scubiee setup --repair
scubiee setup --status
scubiee init .
```

### Diagnose healthy but init fails

Stale `accel.json` while FastEmbed/ORT packages were wiped:

```bash
scubiee setup --repair
scubiee diagnose --no-tests --desktop
scubiee init .
```

### Setup and dependencies

- **No module named fastembed / missing onnxruntime** → `setup --repair`, `preflight .`
- **Stuck on DirectML with Intel UHD / AMD APU** → `setup --profile cpu --repair`
- **Apple Silicon stuck on cpu** → `setup --profile mlx --repair`
- **Two Pythons on PATH** → use Python from `scubiee --version`, not conda

### MCP and agent status

- **MCP red / not connecting:**

```bash
scubiee engine ensure . --wait 45
scubiee connect --cursor
# reload MCP
scubiee stop   # if zombies remain
```

- **status(): warming: true** — Wait ~5s, retry the **tool** once. Do not poll status() every turn.
- **Agent fell back to native Grep** — MCP green? → reconnect → reload → status() once.
- **Paused / stopped** → Global: `scubiee resume`. Per-repo pause: `scubiee activate .` (not `resume .`).

### Windows install & upgrade

- **Access denied on uv tool install (os error 5)** — Cursor keeps scubiee-mcp alive, locking `%APPDATA%\uv\tools\scubiee\`. Fix: `unlock-tool` → reinstall → `setup --repair` → `connect --cursor`. Not Admin/reboot. Do not delete Scripts manually while Cursor is open.
- **No module named pipeline** — Half-deleted uv env. Fix: `repair-uv-scubiee.ps1` or `unlock-tool` → reinstall → `setup --repair`.

### Enrollment & indexing

- **Refusing to index home** — Safety gate. `cd` into project → `init .`.
- **confirm_required / >400 files** — `init . --confirm` or `--fast --roots packages,src`.
- **project_id_mismatch** — `list` → `wipe . --confirm` → `init .`.
- **Search misses fresh edits** — `sync .`; test with unique token in indexed `.py`.

### Lifecycle & wipe

- **Wipe exit 2** — Add `--confirm` in scripts.
- **Full uninstall leftovers (Windows)** — `stop` → quit Cursor → `wipe --all --confirm --package` → re-run until `audit.remaining` empty → `unlock-tool`.
- **Dashboard failed to start** — Upgrade to 0.3.14; `dashboard --no-open`; `dashboard --status`.

### Upgrade

```bash
scubiee upgrade
scubiee setup --repair
scubiee connect --cursor
scubiee migrate --check-all
```

---

## FAQ

**What is Scubiee?** A local code context engine — indexes repos on your machine, connects to AI tools via MCP.

**Do I need to clone GitHub?** No. `uv tool install scubiee`.

**What's MCP?** Model Context Protocol — standard for AI assistants to call tools like semantic search. Server name: `scubiee`.

**Which AI tools work?** Cursor, Claude Code, Copilot, Kiro, Cline, Roo Code, Continue, Zed, OpenCode, Amp, Pi, Windsurf, Devin Desktop, and more.

**What Python version?** 3.10+.

**Does init connect Cursor?** No. `connect` writes MCP + rules.

**uv or pip?** Prefer uv tool install.

**Why setup --repair?** Safest after fresh install, upgrade, or broken reinstall.

**Where is the embedding model?** Downloaded during setup (~270 MB). Cached under FastEmbed dirs.

**Does my code leave the machine?** No. Only model download during setup.

**Does MCP work offline?** Yes after setup.

**MCP server name?** `scubiee`. Data under `~/.scubiee` and `<repo>/.scubiee`.

**How to remove a repo?** `scubiee wipe . --confirm` — deletes Scubiee data, not source files.

**How to uninstall completely?** `stop` → quit IDE → `unlock-tool` (Windows) → `wipe --all --confirm --package`.

**Why managed: false?** `init .` + `connect --cursor` from project, reload MCP.

**How to share diagnostics?** `scubiee diagnose --no-tests --desktop`.

**Agent still uses native Grep?** MCP green, re-run connect, status() once.

**Access denied on Windows upgrade?** `unlock-tool` → reinstall → setup --repair. Not Admin/reboot.

**No module named pipeline?** Half-deleted uv env — unlock-tool or repair script, reinstall + setup --repair.

**Windows laptop Intel UHD / AMD APU?** Use cpu profile. Discrete AMD/NVIDIA → dml.

**status() shows warming?** Daemon starting. Retry MCP tool once after a few seconds.

**What does --fast / --confirm do?** --fast indexes .py under common roots. --confirm required when >400 files touched.

---

## CLI reference

Run `scubiee <subcommand> --help` for flags.

**Setup and indexing:**

```
scubiee setup
scubiee setup --repair
scubiee setup --status
scubiee setup --profile cpu --repair
scubiee init <path>
scubiee init . --fast --roots packages,src
scubiee init . --confirm
scubiee init . --no-index
scubiee search "query" <path>
scubiee sync <path>
scubiee sync . --confirm
scubiee rebuild .
scubiee status <path>
scubiee list
```

**Connect and lifecycle:**

```
scubiee connect --cursor
scubiee connect --all --dry-run
scubiee disconnect --cursor
scubiee stop
scubiee resume
scubiee pause .
scubiee activate .
scubiee upgrade
scubiee unlock-tool
scubiee remove <path> --delete-store
scubiee never-index . --reason "…"
```

**Diagnostics and engine:**

```
scubiee doctor <path>
scubiee doctor . --fix
scubiee doctor --all
scubiee preflight .
scubiee preflight . --lexical-only
scubiee diagnose --no-tests --desktop
scubiee engine ensure . --wait 45
scubiee engine status .
scubiee dashboard --status
scubiee resources
scubiee migrate --check-all
```

---

## Uninstall

Full machine cleanup. On Windows, free locks first.

**What wipe removes:**

- Machine home `~/.scubiee` (registry, indexes, accel, logs)
- Per-repo `<repo>/.scubiee/` markers
- Cursor MCP + rules
- With `--package`: the scubiee install
- With `--keep-models`: keep CodeRank / FastEmbed cache

**Recommended:**

```bash
scubiee stop
# quit Cursor / disable MCP
scubiee unlock-tool          # Windows
scubiee wipe --all --confirm --package
```

Read JSON `audit.remaining`. Re-run until clean. Reload Cursor.

| Flag | Meaning |
|------|---------|
| `--all --confirm` | Delete all Scubiee state |
| `--package` | Also uninstall scubiee package |
| `--keep-package` | Wipe state but keep CLI |
| `--keep-models` | Keep model download cache |

**Repo-only:**

```bash
cd /path/to/repo
scubiee wipe .
# or
scubiee remove . --delete-store
```

**Mac/Linux if CLI is gone:**

```bash
rm -rf ~/.scubiee
# edit ~/.cursor/mcp.json — remove "scubiee"
uv tool uninstall scubiee
```

---

## Still stuck

Collect: `scubiee --version`, `setup --status`, `doctor .`, `diagnose --no-tests --desktop`.

Attach `Desktop/scubiee-diagnose.json` and description of failing command. Optional tail of `~/.scubiee/engine.log`.

GitHub issues: https://github.com/usmansayed/scubiee/issues

---

## Architecture

Scubiee **0.3.14** has three faces: **CLI**, **daemon**, and **MCP adapter**. Code never leaves your machine for search.

```
Your AI IDE (Cursor / Copilot / Kiro / Claude Code / …)
  ↓ MCP stdio — server key: scubiee
scubiee-mcp — map · focus · grep · glob · workspace · status
  ↓ HTTP localhost (default :8765)
Scubiee Engine — IndexManager · ResourceManager · RuntimeManager
  ↓
Vectors (FAISS) + Graph/chunks + Merkle — ~/.scubiee/ + <repo>/.scubiee/
```

**Indexing pipeline:** scan → parse (Tree-sitter) → Graphify → chunk → CodeRankEmbed → FAISS → publish generation.

**Retrieval:** BM25 + FAISS + graph affinity → RRF fusion → expansion.

**Product identity:** Scubiee · CLI/MCP key `scubiee` · model `nomic-ai/CodeRankEmbed` · do not use `context-engine` in user docs.

---

## Features in depth

- **Semantic search** — meaning, not just text (`map`, `focus`, `scubiee search`)
- **Graph-aware** — imports, callers, callees (`focus(mode=neighbors|call_sites)`)
- **Live sync** — Merkle incremental re-index (`scubiee sync .`)
- **Hybrid retrieval** — dense + lexical + graph
- **Multi-tool MCP** — `scubiee connect --<tool>` for 12+ tools
- **GPU-aware** — cuda / dml / mlx / cpu auto-detected
- **Multi-repo** — stable `ce_…` project id across moves
- **Diagnostics** — doctor, diagnose --desktop, setup --repair, unlock-tool

**Agent flow:** `status()` → `map(query)` → `focus(target)` → edit → `scubiee sync` if needed.

**Anti-patterns:** polling status when warming; using Scubiee when unmanaged; grep-before-map.

---

## Core concepts

| Operation | Scope | When |
|-----------|-------|------|
| `scubiee setup --repair` | Machine: GPU/CPU/MLX, model, accel.json | Once per machine; after upgrade |
| `scubiee init <path>` | Per-repo enroll + index | Each searchable repo |
| `scubiee connect --<tool>` | MCP + agent rules | Each IDE; Special-4 inside each project |
| Reload MCP | IDE session | After connect/upgrade |

**Managed states:** Unmanaged (no init) · Managed/active · Paused (`scubiee activate .` to resume) · Wiped.

**Time expectations:** Install 1–3 min · Setup 3–10 min · Init small repo 1–5 min · Connect seconds.

---

## All integrations

`scubiee connect --cursor` · `--claude-code` · `--codex` · `--kiro` · `--copilot` · `--cline` · `--roo-code` · `--continue` · `--zed` · `--opencode` · `--amp` · `--pi` · `--windsurf` · `--devin-desktop`

**Special-4:** Kiro, Copilot, Cline, Roo Code — run `connect` **inside each project**.

`scubiee connect --all` · `--all --dry-run` · `scubiee disconnect --<tool>`

---

## Repo lifecycle

| Intent | Command | Deletes index? | Deletes source? |
|--------|---------|----------------|-----------------|
| Pause | `scubiee pause .` | No | No |
| Resume paused | `scubiee activate .` | No | No |
| Machine stop | `scubiee stop` / `resume` | No | No |
| Unmanage | `scubiee wipe . --confirm` | Yes | **No** |
| Remove registry | `scubiee remove .` | Optional `--delete-store` | No |
| Full machine | `scubiee wipe --all --confirm` | Yes (all) | No |

`scubiee resume` = machine-wide. `scubiee activate .` = per-repo unpause. No `wake` command.

---

## Privacy & security

1. Code stays local — no Scubiee cloud upload service.
2. Model download only during setup (~270 MB FP16 / ~132 MB INT8 CPU).
3. You control deletion — wipe + honest audit.
4. Your AI tool may still send code to its own provider — separate from Scubiee.
5. MCP/rule files contain paths, not source code.
6. Review `diagnose` output before sharing.

---

## Data & storage

| Path | What it holds |
|------|---------------|
| `<repo>/.scubiee/id.json` | Repository identity (ce_…) |
| `~/.scubiee/prefs.json` | Preferences and consent |
| `~/.scubiee/registry.json` | Managed-project registry |
| `~/.scubiee/accel.json` | GPU/CPU/MLX profile |
| `~/.scubiee/projects/<id>/` | Index store, chunks, Merkle, manifest |
| `~/.scubiee/vectordb/` | FAISS / TurboQuant catalog |
| `~/.scubiee/engine.log` | Daemon log |

**Invariants:** identity/registry agree for routing; denied repos never auto-index; retrieval uses published generation only.

---

## Supported platforms

| OS / hardware | Profile | Status |
|---------------|---------|--------|
| Windows discrete AMD/NVIDIA | dml | Production |
| Windows Intel iGPU / no dGPU | cpu | Production |
| macOS Apple Silicon | mlx | Production |
| macOS Intel | coreml / cpu | Supported |
| Linux NVIDIA | cuda | Production |
| Linux no GPU | cpu | Supported |

Requirements: Python 3.10+ · ~500 MB–1 GB disk · network only for install + model download.

---

## Product transparency

**Version:** scubiee **0.3.14** on PyPI.

### Setup & indexing commands

| Command | What it does |
|---------|-------------|
| `scubiee setup --repair` | Machine install: GPU/CPU/MLX, ORT, model |
| `scubiee init <path>` | Enroll + index (requires setup) |
| `scubiee init . --fast --roots packages` | Fast scoped index |
| `scubiee init . --confirm` | Bypass >400 file gate |
| `scubiee status <path>` | Health + daemon state |
| `scubiee search "q" <path>` | CLI search |
| `scubiee sync <path>` | Incremental re-index |

### Diagnostics & lifecycle

| Command | What it does |
|---------|-------------|
| `scubiee diagnose --no-tests --desktop` | Shareable JSON on Desktop |
| `scubiee unlock-tool` | Windows file-lock recovery |
| `scubiee upgrade` | Stop, upgrade, migrate, restart |
| `scubiee stop` / `resume` | Machine-wide (no `wake`) |
| `scubiee pause .` / `activate .` | Per-repo pause/unpause |
| `scubiee wipe --all --confirm --package` | Full cleanup + uninstall |

### Issue cheatsheet

| Issue | Fix |
|-------|-----|
| Agent unmanaged | init + connect + reload MCP |
| Special-4 broken | connect inside that repo |
| Access denied Windows | unlock-tool → reinstall → setup --repair |
| No module named pipeline | unlock-tool → reinstall → setup --repair |
| Warming forever | engine ensure . --wait 45 |

### Terminology

Use: Scubiee, `scubiee`, `~/.scubiee`, init + connect, `resume` (machine), `activate` (per-repo), managed/unmanaged.

Avoid: context-engine, `.context-engine`, wake, "setup does everything".

---

## Engineering internals

**Contract:** use Scubiee when repo is managed + healthy; else native tools.

**Components:** CLI → mcp_locate → daemon/RuntimeManager → IndexManager → scan/graph/chunk/embed/vector/retrieve.

**MCP surfaces (CTX_MCP_SURFACE):** phase (default: map, focus, grep, glob, workspace, status) · read · nav · graph · rich · search · grep.

**Model precision:** dml/cuda/mlx/coreml → model_fp16.onnx (~260 MB) · cpu → model_int8.onnx (~132 MB).

**Incremental defaults:** CTX_LIVE_MAX_FILES=200 · CTX_SYNC_INTERVAL_MS=300000 · CTX_BULK_REINDEX_THRESHOLD=300.

**Operator runbook:**

```bash
scubiee preflight .
scubiee doctor . --all
scubiee sync . && scubiee sync-now .
scubiee rebuild .
scubiee setup --repair
scubiee migrate . --check-all
```