{
  "product": "Scubiee",
  "version": 1,
  "format": "markdown-sections",
  "source": "https://scubiee.com/docs.md",
  "humanDocs": "https://scubiee.com/docs",
  "installGuide": "https://scubiee.com/install",
  "github": "https://github.com/usmansayed/scubiee",
  "connectTools": [
    {
      "name": "Cursor",
      "flag": "cursor",
      "projectLocal": false
    },
    {
      "name": "Claude Code",
      "flag": "claude-code",
      "projectLocal": false
    },
    {
      "name": "Codex",
      "flag": "codex",
      "projectLocal": false
    },
    {
      "name": "Kiro",
      "flag": "kiro",
      "projectLocal": true
    },
    {
      "name": "Windsurf",
      "flag": "windsurf",
      "projectLocal": false
    },
    {
      "name": "GitHub Copilot",
      "flag": "copilot",
      "projectLocal": true
    },
    {
      "name": "Cline",
      "flag": "cline",
      "projectLocal": true
    },
    {
      "name": "Roo Code",
      "flag": "roo-code",
      "projectLocal": true
    },
    {
      "name": "Continue",
      "flag": "continue",
      "projectLocal": false
    },
    {
      "name": "Zed",
      "flag": "zed",
      "projectLocal": false
    },
    {
      "name": "OpenCode",
      "flag": "opencode",
      "projectLocal": false
    },
    {
      "name": "Amp",
      "flag": "amp",
      "projectLocal": false
    },
    {
      "name": "Pi",
      "flag": "pi",
      "projectLocal": false
    }
  ],
  "sections": [
    {
      "id": "facts-any-assistant-needs",
      "title": "Facts any assistant needs",
      "body": "- Product CLI + MCP server key: `scubiee` (not \"context-engine\").\n- Data lives under `~/.scubiee` and `<repo>/.scubiee`.\n- Correct order: `setup --repair` → `cd repo` → `init .` → `connect --…` → reload MCP.\n- `init` indexes the repo; it does **not** write MCP or agent rules. `connect` does.\n- `setup` alone does not make a repo managed. You still need `init` inside the project.\n- Continue after pause/stop with `scubiee resume` — there is **no** `wake` command.\n- Windows Access denied on upgrade → `scubiee unlock-tool`, then reinstall — not Admin/reboot.\n- `machine_not_setup` / missing FastEmbed → `scubiee setup --repair`.\n- Share diagnostics: `scubiee diagnose --no-tests --desktop` → `Desktop/scubiee-diagnose.json` (not source code).\n- Python 3.10+. Install from PyPI with `uv tool install scubiee`. No need to clone GitHub.\n\n---"
    },
    {
      "id": "how-it-works",
      "title": "How it works",
      "body": "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.\n\n```\nYour AI tool (Cursor / Kiro / Claude Code / …)\n  ↓ MCP (stdio) — server name: scubiee\nScubiee MCP — status, map, focus, grep, glob, workspace\n  ↓ HTTP localhost (default :8765)\nScubiee Engine — daemon + live re-indexing\n  ↓\nYour code index — vectors + graph + chunks under ~/.scubiee\n```\n\n| Step | Command | What it does |\n|------|---------|--------------|\n| 1 | `uv tool install scubiee` | Install the CLI |\n| 2 | `scubiee setup --repair` | Machine setup — GPU/CPU/MLX, model, accel.json |\n| 3 | `scubiee init .` | Enroll + index this repo — does not write MCP |\n| 4 | `scubiee connect --…` | Write MCP + agent rules for your IDE |\n| 5 | Reload MCP in the IDE | Agent `status()` → `managed: true` |\n\nAdding a second repo only needs `init` (and Special-4 `connect` inside that project for Kiro/Copilot/Cline/Roo).\n\n### The four layers\n\nMost problems mean one layer is missing or stale. Why agents say `managed: false`: layer 3 or 4 is missing.\n\n| Layer | Question | Command | Marker |\n|-------|----------|---------|--------|\n| 1. Install | Is scubiee installed? | `uv tool install scubiee` | `scubiee --version` |\n| 2. Machine setup | GPU/CPU + model ready? | `scubiee setup --repair` | `~/.scubiee/accel.json` |\n| 3. Repo enrollment | Is this folder indexed? | `scubiee init .` | `<repo>/.scubiee/id.json` |\n| 4. IDE wiring | Does agent call MCP? | `scubiee connect --cursor` | MCP config + rules |\n\n---"
    },
    {
      "id": "quick-start",
      "title": "Quick start",
      "body": "### macOS / Linux\n\n```bash\nuv tool install --force scubiee --index-url https://pypi.org/simple --refresh\nuv tool update-shell\n# open a new terminal\nscubiee setup --repair\ncd your-repo\nscubiee init .\nscubiee connect --cursor\n# reload MCP in your IDE\n```\n\n### Windows (PowerShell)\n\n```powershell\nuv tool install --force scubiee --index-url https://pypi.org/simple --refresh\nuv tool update-shell\n# open a NEW PowerShell window\nscubiee setup --repair\ncd C:\\path\\to\\your\\repo\nscubiee init .\nscubiee connect --cursor\n# Cursor → Settings → MCP → refresh\n```\n\nPrefer **uv tool install** over pip on Windows. Always pin `--index-url https://pypi.org/simple` on Windows. Shims usually live in `%USERPROFILE%\\.local\\bin`.\n\n**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`.\n\nAfter broken reinstall: always `scubiee setup --repair` before `init`.\n\n**Verify:**\n\n```bash\nscubiee --version\nscubiee setup --status\nscubiee doctor .\nscubiee search \"a symbol in your repo\" .\nscubiee diagnose --no-tests --desktop\n```\n\nIn the agent, call MCP `status()` once. Expect `managed: true`, `ok: true` after init + connect + reload.\n\n---"
    },
    {
      "id": "daily-use",
      "title": "Daily use",
      "body": "```bash\ncd your-project\nscubiee status .          # index health + sync state\nscubiee sync .            # after git pull / large edits\nscubiee search \"AuthService\" .\n```\n\n| Command | When |\n|---------|------|\n| `scubiee sync .` | After pulling changes or large local edits |\n| `scubiee sync . --confirm` | When sync refuses with >400 file count |\n| `scubiee rebuild .` | Full re-index (slow; fixes corruption) |\n| `scubiee search \"query\" .` | CLI search — query first, path second |\n| `scubiee search \"query\" . --local` | In-process search, no HTTP daemon |\n\n**Multiple repos:**\n\n```bash\nscubiee list\nscubiee activate /path/to/repo\nscubiee pause /path/to/repo --reason \"maintenance\"\nscubiee remove /path/to/other --delete-store\n```\n\n**Stop / resume (machine-wide):**\n\n```bash\nscubiee stop      # stop engine, free GPU / file locks\nscubiee resume    # bring Scubiee back — NOT \"wake\"\n```\n\n**Settings:** `scubiee settings --show` · prefs at `~/.scubiee/prefs.json`\n\n**Engine & dashboard:**\n\n```bash\nscubiee engine status .\nscubiee engine ensure . --wait 45\nscubiee dashboard --status\nscubiee resources\n```\n\nLogs: `~/.scubiee/engine.log`, `~/.scubiee/watchdog.log`\n\n**Environment variables:**\n\n| Variable | Effect |\n|----------|--------|\n| `CTX_INCREMENTAL_MAX_TOUCH` | File-count cap before `--confirm` (default 400) |\n| `CTX_FAST_ROOTS` | Comma roots for `--fast` indexing |\n| `CTX_RM_DISABLE=1` | Disable RAM admission pauses |\n| `CTX_MLX=0` | Force non-MLX path on Mac |\n\n---"
    },
    {
      "id": "connect-agents",
      "title": "Connect agents",
      "body": "| Command | Writes |\n|---------|--------|\n| `scubiee setup --repair` | Machine GPU/CPU/MLX profile, model cache |\n| `scubiee init .` | Repo enrollment + index. **Not** MCP or rules |\n| `scubiee connect --cursor` | Global `~/.cursor/mcp.json` + rules AND project `.cursor/mcp.json` (absolute CTX_REPO) |\n\n```bash\nscubiee connect --cursor\nscubiee connect --claude-code\nscubiee connect --codex\nscubiee connect --cursor --dry-run\nscubiee disconnect --cursor\n```\n\n### Cursor workspace pin (critical)\n\nCursor does **not** expand `${workspaceFolder}` in global `~/.cursor/mcp.json`. A literal token makes MCP resolve to your home folder → `managed: false`.\n\n- Always run `scubiee connect --cursor` **from the project** you want managed.\n- That writes project `.cursor/mcp.json` with an absolute `CTX_REPO` pin.\n- After connect: Cursor → Settings → MCP → refresh until `scubiee` shows green.\n- On Windows, MCP should use the uv tool shim (`%APPDATA%\\uv\\tools\\scubiee\\Scripts\\…`).\n\n### Multiple repos in one Cursor app\n\nOne MCP process is shared across chats.\n\n- On `status()`, pass `root` = that chat's Workspace Path.\n- `managed: true` only if that folder (walking up) has `.scubiee/id.json` and is in the registry.\n- Other chats: `managed: false` after one `status()` — use native tools.\n- After successful `status()`, you may pass `project_id` (`ce_…`) instead of full path.\n\n### Special-4 (per-repo connect)\n\nRun connect **inside each project**:\n\n| Tool | Command | Typical file |\n|------|---------|--------------|\n| Kiro | `scubiee connect --kiro` | `.kiro/settings/mcp.json` |\n| GitHub Copilot / VS Code | `scubiee connect --copilot` | `.vscode/mcp.json` |\n| Cline | `scubiee connect --cline` | `.cline/mcp.json` |\n| Roo Code | `scubiee connect --roo-code` | `.roo/mcp.json` |\n\n**All connect flags:** `--cursor`, `--claude-code`, `--codex`, `--kiro`, `--windsurf`, `--copilot`, `--cline`, `--roo-code`, `--continue`, `--zed`, `--opencode`, `--amp`, `--pi`\n\nMCP cannot start or wrong Python? Re-run `connect` for that tool, or `setup --repair`, then reload MCP.\n\n---"
    },
    {
      "id": "mcp-tools",
      "title": "MCP tools",
      "body": "MCP server key: `scubiee`. Talks to local daemon (default `http://127.0.0.1:8765`).\n\n**Agent rule policy:**\n\n1. Call `status()` once at session start (pass `root` = workspace path when several repos share MCP).\n2. If `managed` + `ok` → use Scubiee tools for discovery (map/grep/focus), not native Grep by default.\n3. If `warming` → use tools; wait ~5s and retry the **tool** once; do not busy-loop on `status()`.\n4. If unmanaged → native tools; retry `status()` only after user runs init/connect.\n5. If paused/stopped → `scubiee resume` (not wake).\n\n**status() fields:**\n\n| Field | Meaning |\n|-------|---------|\n| `managed: true` | Workspace enrolled (after init) |\n| `ok: true` | Daemon healthy — use Scubiee tools |\n| `warming: true` | Managed but not ready — retry tool once; do not poll status() |\n| `managed: false` | Use native tools; retry after init/connect |\n| `should_retry_status: true` | User likely just ran init/connect — call status() once more |\n\n**Tool catalog:**\n\n| Tool | Purpose | Typical args |\n|------|---------|--------------|\n| `status` | Health + managed flag | `root=` or `project_id=` |\n| `gate` | Tiny is-this-repo-ready check | automatic at chat start |\n| `map` | Ranked overview of relevant chunks/symbols | query + root/project_id |\n| `focus` | Deepen context around a hit | handle from map |\n| `grep` | Exact/regex search of indexed content | pattern, optional glob= |\n| `glob` | Find files by path pattern | pattern + root |\n| `workspace` | Session context | root/project_id |\n| `expand` | Re-open a previous code span | follow-up without re-searching |\n| `register_project` | Explicit consent registration | path when prompted |\n\n**Recommended flow:**\n\n```\n1. status(root=<workspace path>)     # once\n2. map(query=\"auth middleware\")\n3. focus(...)\n4. grep(pattern=\"AuthService\")\n5. Read/Edit only the lines you need\n```\n\n- Empty grep/glob with `truncated: false` = no match in **indexed** scope, not \"file missing on disk\".\n- Stale results after edits: `scubiee sync .` then search again.\n- Agent ignores MCP: MCP green? → `scubiee connect --cursor` → reload MCP → call `status()` once.\n\n`connect` installs Cursor rule at `~/.cursor/rules/scubiee.mdc`. Re-run connect after upgrades.\n\n---"
    },
    {
      "id": "windows",
      "title": "Windows",
      "body": "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.\n\n**Access denied on upgrade:**\n\n```powershell\nscubiee unlock-tool\nuv tool install --force scubiee --index-url https://pypi.org/simple --refresh\nscubiee setup --repair\nscubiee connect --cursor\n```\n\n**CLI already broken:**\n\n```powershell\npowershell -ExecutionPolicy Bypass -File scripts/uninstall-uv-scubiee.ps1\n# or repair:\npowershell -ExecutionPolicy Bypass -File scripts/repair-uv-scubiee.ps1\nuv tool install --force scubiee --index-url https://pypi.org/simple --refresh\nscubiee setup --repair\n```\n\n**GPU on Windows:** integrated Intel UHD / AMD APU → profile `cpu`. Discrete AMD/NVIDIA → `dml`. Verify with `scubiee setup --status`.\n\n---"
    },
    {
      "id": "gpu-and-profiles",
      "title": "GPU and profiles",
      "body": "| Profile | When |\n|---------|------|\n| `cpu` | No GPU, or integrated-only laptop |\n| `dml` | Windows discrete AMD/NVIDIA (DirectML) |\n| `cuda` | Linux NVIDIA |\n| `mlx` | Apple Silicon (Metal) |\n\n```bash\nscubiee setup --status\nscubiee setup --profile cpu --repair\nscubiee setup --profile dml --repair\nscubiee setup --profile mlx --repair\nscubiee setup --profile cuda --repair\n```\n\nApple Silicon should not stay on CPU after `--repair`. Force MLX with `--profile mlx --repair`.\n\n---"
    },
    {
      "id": "indexing-and-projects",
      "title": "Indexing and projects",
      "body": "Always `cd` into project root before `init`. Do not run init from home folder. Indexes stay local under `~/.scubiee`.\n\n**Where data lives:**\n\n| Path | Role |\n|------|------|\n| `<repo>/.scubiee/id.json` | Binds folder to project_id (often gitignored) |\n| `<repo>/.cursor/mcp.json` | Cursor project MCP pin (absolute CTX_REPO) |\n| `~/.scubiee/registry.json` | All managed roots + lifecycle state |\n| `~/.scubiee/projects/<id>/` | Index store (chunks, graph, vectors) |\n| `~/.scubiee/accel.json` | GPU/CPU profile from setup |\n| `~/.scubiee/engine.log` | Engine / daemon logs |\n| `~/.cursor/mcp.json` | Cursor global MCP entry |\n| `~/.cursor/rules/scubiee.mdc` | Cursor agent rule |\n| `%APPDATA%\\uv\\tools\\scubiee\\` | Windows uv tool env |\n\nFresh installs do not use `.context-engine`. Daemon HTTP is localhost-only; MCP is stdio to IDE.\n\n```bash\ncd your-repo\nscubiee init .\nscubiee init . --fast\nscubiee init . --fast --roots packages,src\nscubiee init . --confirm                     # when >400 files\nscubiee init . --no-index                    # register only\nscubiee sync .\nscubiee never-index . --reason \"…\"           # block path intentionally\n```\n\n**Fast mode** indexes `.py` under common roots (`packages`, `src`, `lib`, `app`, …) or your `--roots` list.\n\n**Common issues:**\n\n- **Refusing to index home/drive root:** Safety gate. `cd` into project, then `init .`.\n- **>400 files need indexing:** Re-run with `--confirm`, or `--fast --roots …`.\n- **never_index error:** Path was blocked. Clear via dashboard or lifecycle remove.\n- **project_id_mismatch / stale home registration:** `scubiee list` then `scubiee remove C:\\Users\\YOUR_USER --delete-store`.\n\n---"
    },
    {
      "id": "troubleshooting",
      "title": "Troubleshooting",
      "body": "**Run this triage first:**\n\n```bash\nscubiee --version\nscubiee setup --status\nscubiee preflight .\nscubiee doctor .\nscubiee list\nscubiee diagnose --no-tests --desktop\n```\n\nIf semantic preflight fails: `scubiee setup --repair`. If daemon cold: `scubiee engine ensure . --wait 45`.\n\n| Command | When |\n|---------|------|\n| `unlock-tool` | Windows Access denied / free uv tool locks |\n| `upgrade` | Upgrade with unlock/stop path |\n| `setup --repair` | After broken reinstall or missing FastEmbed |\n| `stop / resume` | Pause globally / continue (not wake) |\n| `connect --…` | After install, upgrade, or unmanaged agent |\n| `engine ensure . --wait 45` | Daemon not warm |\n| `wipe --all --confirm --package` | Nuclear uninstall |\n\n### Install sequence mistakes\n\n- **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`.\n- **Index exists but MCP missing** — Ran init only. Fix: `connect --…` then reload MCP.\n- **Kiro/Copilot/Cline/Roo MCP empty** — Connected only globally. Fix: `cd` into that project → `connect --kiro` (or --copilot / --cline / --roo-code).\n- **Agent polls status() every turn** — Old rule. Fix: re-run `connect`.\n- **Hint says scubiee wake** — No wake command. Fix: `scubiee resume`. Upgrade + reconnect.\n\n### machine_not_setup on init\n\nSymptom: `{\"ok\": false, \"error\": \"machine_not_setup\"}` — no profile in `~/.scubiee/accel.json`.\n\n```bash\nscubiee setup --repair\nscubiee setup --status\nscubiee init .\n```\n\n### Diagnose healthy but init fails\n\nStale `accel.json` while FastEmbed/ORT packages were wiped:\n\n```bash\nscubiee setup --repair\nscubiee diagnose --no-tests --desktop\nscubiee init .\n```\n\n### Setup and dependencies\n\n- **No module named fastembed / missing onnxruntime** → `setup --repair`, `preflight .`\n- **Stuck on DirectML with Intel UHD / AMD APU** → `setup --profile cpu --repair`\n- **Apple Silicon stuck on cpu** → `setup --profile mlx --repair`\n- **Two Pythons on PATH** → use Python from `scubiee --version`, not conda\n\n### MCP and agent status\n\n- **MCP red / not connecting:**\n\n```bash\nscubiee engine ensure . --wait 45\nscubiee connect --cursor\n# reload MCP\nscubiee stop   # if zombies remain\n```\n\n- **status(): warming: true** — Wait ~5s, retry the **tool** once. Do not poll status() every turn.\n- **Agent fell back to native Grep** — MCP green? → reconnect → reload → status() once.\n- **Paused / stopped** → Global: `scubiee resume`. Per-repo pause: `scubiee activate .` (not `resume .`).\n\n### Windows install & upgrade\n\n- **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.\n- **No module named pipeline** — Half-deleted uv env. Fix: `repair-uv-scubiee.ps1` or `unlock-tool` → reinstall → `setup --repair`.\n\n### Enrollment & indexing\n\n- **Refusing to index home** — Safety gate. `cd` into project → `init .`.\n- **confirm_required / >400 files** — `init . --confirm` or `--fast --roots packages,src`.\n- **project_id_mismatch** — `list` → `wipe . --confirm` → `init .`.\n- **Search misses fresh edits** — `sync .`; test with unique token in indexed `.py`.\n\n### Lifecycle & wipe\n\n- **Wipe exit 2** — Add `--confirm` in scripts.\n- **Full uninstall leftovers (Windows)** — `stop` → quit Cursor → `wipe --all --confirm --package` → re-run until `audit.remaining` empty → `unlock-tool`.\n- **Dashboard failed to start** — Upgrade to 0.3.14; `dashboard --no-open`; `dashboard --status`.\n\n### Upgrade\n\n```bash\nscubiee upgrade\nscubiee setup --repair\nscubiee connect --cursor\nscubiee migrate --check-all\n```\n\n---"
    },
    {
      "id": "faq",
      "title": "FAQ",
      "body": "**What is Scubiee?** A local code context engine — indexes repos on your machine, connects to AI tools via MCP.\n\n**Do I need to clone GitHub?** No. `uv tool install scubiee`.\n\n**What's MCP?** Model Context Protocol — standard for AI assistants to call tools like semantic search. Server name: `scubiee`.\n\n**Which AI tools work?** Cursor, Claude Code, Copilot, Kiro, Cline, Roo Code, Continue, Zed, OpenCode, Amp, Pi, Windsurf, Devin Desktop, and more.\n\n**What Python version?** 3.10+.\n\n**Does init connect Cursor?** No. `connect` writes MCP + rules.\n\n**uv or pip?** Prefer uv tool install.\n\n**Why setup --repair?** Safest after fresh install, upgrade, or broken reinstall.\n\n**Where is the embedding model?** Downloaded during setup (~270 MB). Cached under FastEmbed dirs.\n\n**Does my code leave the machine?** No. Only model download during setup.\n\n**Does MCP work offline?** Yes after setup.\n\n**MCP server name?** `scubiee`. Data under `~/.scubiee` and `<repo>/.scubiee`.\n\n**How to remove a repo?** `scubiee wipe . --confirm` — deletes Scubiee data, not source files.\n\n**How to uninstall completely?** `stop` → quit IDE → `unlock-tool` (Windows) → `wipe --all --confirm --package`.\n\n**Why managed: false?** `init .` + `connect --cursor` from project, reload MCP.\n\n**How to share diagnostics?** `scubiee diagnose --no-tests --desktop`.\n\n**Agent still uses native Grep?** MCP green, re-run connect, status() once.\n\n**Access denied on Windows upgrade?** `unlock-tool` → reinstall → setup --repair. Not Admin/reboot.\n\n**No module named pipeline?** Half-deleted uv env — unlock-tool or repair script, reinstall + setup --repair.\n\n**Windows laptop Intel UHD / AMD APU?** Use cpu profile. Discrete AMD/NVIDIA → dml.\n\n**status() shows warming?** Daemon starting. Retry MCP tool once after a few seconds.\n\n**What does --fast / --confirm do?** --fast indexes .py under common roots. --confirm required when >400 files touched.\n\n---"
    },
    {
      "id": "cli-reference",
      "title": "CLI reference",
      "body": "Run `scubiee <subcommand> --help` for flags.\n\n**Setup and indexing:**\n\n```\nscubiee setup\nscubiee setup --repair\nscubiee setup --status\nscubiee setup --profile cpu --repair\nscubiee init <path>\nscubiee init . --fast --roots packages,src\nscubiee init . --confirm\nscubiee init . --no-index\nscubiee search \"query\" <path>\nscubiee sync <path>\nscubiee sync . --confirm\nscubiee rebuild .\nscubiee status <path>\nscubiee list\n```\n\n**Connect and lifecycle:**\n\n```\nscubiee connect --cursor\nscubiee connect --all --dry-run\nscubiee disconnect --cursor\nscubiee stop\nscubiee resume\nscubiee pause .\nscubiee activate .\nscubiee upgrade\nscubiee unlock-tool\nscubiee remove <path> --delete-store\nscubiee never-index . --reason \"…\"\n```\n\n**Diagnostics and engine:**\n\n```\nscubiee doctor <path>\nscubiee doctor . --fix\nscubiee doctor --all\nscubiee preflight .\nscubiee preflight . --lexical-only\nscubiee diagnose --no-tests --desktop\nscubiee engine ensure . --wait 45\nscubiee engine status .\nscubiee dashboard --status\nscubiee resources\nscubiee migrate --check-all\n```\n\n---"
    },
    {
      "id": "uninstall",
      "title": "Uninstall",
      "body": "Full machine cleanup. On Windows, free locks first.\n\n**What wipe removes:**\n\n- Machine home `~/.scubiee` (registry, indexes, accel, logs)\n- Per-repo `<repo>/.scubiee/` markers\n- Cursor MCP + rules\n- With `--package`: the scubiee install\n- With `--keep-models`: keep CodeRank / FastEmbed cache\n\n**Recommended:**\n\n```bash\nscubiee stop\n# quit Cursor / disable MCP\nscubiee unlock-tool          # Windows\nscubiee wipe --all --confirm --package\n```\n\nRead JSON `audit.remaining`. Re-run until clean. Reload Cursor.\n\n| Flag | Meaning |\n|------|---------|\n| `--all --confirm` | Delete all Scubiee state |\n| `--package` | Also uninstall scubiee package |\n| `--keep-package` | Wipe state but keep CLI |\n| `--keep-models` | Keep model download cache |\n\n**Repo-only:**\n\n```bash\ncd /path/to/repo\nscubiee wipe .\n# or\nscubiee remove . --delete-store\n```\n\n**Mac/Linux if CLI is gone:**\n\n```bash\nrm -rf ~/.scubiee\n# edit ~/.cursor/mcp.json — remove \"scubiee\"\nuv tool uninstall scubiee\n```\n\n---"
    },
    {
      "id": "still-stuck",
      "title": "Still stuck",
      "body": "Collect: `scubiee --version`, `setup --status`, `doctor .`, `diagnose --no-tests --desktop`.\n\nAttach `Desktop/scubiee-diagnose.json` and description of failing command. Optional tail of `~/.scubiee/engine.log`.\n\nGitHub issues: https://github.com/usmansayed/scubiee/issues\n\n---"
    },
    {
      "id": "architecture",
      "title": "Architecture",
      "body": "Scubiee **0.3.14** has three faces: **CLI**, **daemon**, and **MCP adapter**. Code never leaves your machine for search.\n\n```\nYour AI IDE (Cursor / Copilot / Kiro / Claude Code / …)\n  ↓ MCP stdio — server key: scubiee\nscubiee-mcp — map · focus · grep · glob · workspace · status\n  ↓ HTTP localhost (default :8765)\nScubiee Engine — IndexManager · ResourceManager · RuntimeManager\n  ↓\nVectors (FAISS) + Graph/chunks + Merkle — ~/.scubiee/ + <repo>/.scubiee/\n```\n\n**Indexing pipeline:** scan → parse (Tree-sitter) → Graphify → chunk → CodeRankEmbed → FAISS → publish generation.\n\n**Retrieval:** BM25 + FAISS + graph affinity → RRF fusion → expansion.\n\n**Product identity:** Scubiee · CLI/MCP key `scubiee` · model `nomic-ai/CodeRankEmbed` · do not use `context-engine` in user docs.\n\n---"
    },
    {
      "id": "features-in-depth",
      "title": "Features in depth",
      "body": "- **Semantic search** — meaning, not just text (`map`, `focus`, `scubiee search`)\n- **Graph-aware** — imports, callers, callees (`focus(mode=neighbors|call_sites)`)\n- **Live sync** — Merkle incremental re-index (`scubiee sync .`)\n- **Hybrid retrieval** — dense + lexical + graph\n- **Multi-tool MCP** — `scubiee connect --<tool>` for 12+ tools\n- **GPU-aware** — cuda / dml / mlx / cpu auto-detected\n- **Multi-repo** — stable `ce_…` project id across moves\n- **Diagnostics** — doctor, diagnose --desktop, setup --repair, unlock-tool\n\n**Agent flow:** `status()` → `map(query)` → `focus(target)` → edit → `scubiee sync` if needed.\n\n**Anti-patterns:** polling status when warming; using Scubiee when unmanaged; grep-before-map.\n\n---"
    },
    {
      "id": "core-concepts",
      "title": "Core concepts",
      "body": "| Operation | Scope | When |\n|-----------|-------|------|\n| `scubiee setup --repair` | Machine: GPU/CPU/MLX, model, accel.json | Once per machine; after upgrade |\n| `scubiee init <path>` | Per-repo enroll + index | Each searchable repo |\n| `scubiee connect --<tool>` | MCP + agent rules | Each IDE; Special-4 inside each project |\n| Reload MCP | IDE session | After connect/upgrade |\n\n**Managed states:** Unmanaged (no init) · Managed/active · Paused (`scubiee activate .` to resume) · Wiped.\n\n**Time expectations:** Install 1–3 min · Setup 3–10 min · Init small repo 1–5 min · Connect seconds.\n\n---"
    },
    {
      "id": "all-integrations",
      "title": "All integrations",
      "body": "`scubiee connect --cursor` · `--claude-code` · `--codex` · `--kiro` · `--copilot` · `--cline` · `--roo-code` · `--continue` · `--zed` · `--opencode` · `--amp` · `--pi` · `--windsurf` · `--devin-desktop`\n\n**Special-4:** Kiro, Copilot, Cline, Roo Code — run `connect` **inside each project**.\n\n`scubiee connect --all` · `--all --dry-run` · `scubiee disconnect --<tool>`\n\n---"
    },
    {
      "id": "repo-lifecycle",
      "title": "Repo lifecycle",
      "body": "| Intent | Command | Deletes index? | Deletes source? |\n|--------|---------|----------------|-----------------|\n| Pause | `scubiee pause .` | No | No |\n| Resume paused | `scubiee activate .` | No | No |\n| Machine stop | `scubiee stop` / `resume` | No | No |\n| Unmanage | `scubiee wipe . --confirm` | Yes | **No** |\n| Remove registry | `scubiee remove .` | Optional `--delete-store` | No |\n| Full machine | `scubiee wipe --all --confirm` | Yes (all) | No |\n\n`scubiee resume` = machine-wide. `scubiee activate .` = per-repo unpause. No `wake` command.\n\n---"
    },
    {
      "id": "privacy-security",
      "title": "Privacy & security",
      "body": "1. Code stays local — no Scubiee cloud upload service.\n2. Model download only during setup (~270 MB FP16 / ~132 MB INT8 CPU).\n3. You control deletion — wipe + honest audit.\n4. Your AI tool may still send code to its own provider — separate from Scubiee.\n5. MCP/rule files contain paths, not source code.\n6. Review `diagnose` output before sharing.\n\n---"
    },
    {
      "id": "data-storage",
      "title": "Data & storage",
      "body": "| Path | What it holds |\n|------|---------------|\n| `<repo>/.scubiee/id.json` | Repository identity (ce_…) |\n| `~/.scubiee/prefs.json` | Preferences and consent |\n| `~/.scubiee/registry.json` | Managed-project registry |\n| `~/.scubiee/accel.json` | GPU/CPU/MLX profile |\n| `~/.scubiee/projects/<id>/` | Index store, chunks, Merkle, manifest |\n| `~/.scubiee/vectordb/` | FAISS / TurboQuant catalog |\n| `~/.scubiee/engine.log` | Daemon log |\n\n**Invariants:** identity/registry agree for routing; denied repos never auto-index; retrieval uses published generation only.\n\n---"
    },
    {
      "id": "supported-platforms",
      "title": "Supported platforms",
      "body": "| OS / hardware | Profile | Status |\n|---------------|---------|--------|\n| Windows discrete AMD/NVIDIA | dml | Production |\n| Windows Intel iGPU / no dGPU | cpu | Production |\n| macOS Apple Silicon | mlx | Production |\n| macOS Intel | coreml / cpu | Supported |\n| Linux NVIDIA | cuda | Production |\n| Linux no GPU | cpu | Supported |\n\nRequirements: Python 3.10+ · ~500 MB–1 GB disk · network only for install + model download.\n\n---"
    },
    {
      "id": "product-transparency",
      "title": "Product transparency",
      "body": "**Version:** scubiee **0.3.14** on PyPI.\n\n### Setup & indexing commands\n\n| Command | What it does |\n|---------|-------------|\n| `scubiee setup --repair` | Machine install: GPU/CPU/MLX, ORT, model |\n| `scubiee init <path>` | Enroll + index (requires setup) |\n| `scubiee init . --fast --roots packages` | Fast scoped index |\n| `scubiee init . --confirm` | Bypass >400 file gate |\n| `scubiee status <path>` | Health + daemon state |\n| `scubiee search \"q\" <path>` | CLI search |\n| `scubiee sync <path>` | Incremental re-index |\n\n### Diagnostics & lifecycle\n\n| Command | What it does |\n|---------|-------------|\n| `scubiee diagnose --no-tests --desktop` | Shareable JSON on Desktop |\n| `scubiee unlock-tool` | Windows file-lock recovery |\n| `scubiee upgrade` | Stop, upgrade, migrate, restart |\n| `scubiee stop` / `resume` | Machine-wide (no `wake`) |\n| `scubiee pause .` / `activate .` | Per-repo pause/unpause |\n| `scubiee wipe --all --confirm --package` | Full cleanup + uninstall |\n\n### Issue cheatsheet\n\n| Issue | Fix |\n|-------|-----|\n| Agent unmanaged | init + connect + reload MCP |\n| Special-4 broken | connect inside that repo |\n| Access denied Windows | unlock-tool → reinstall → setup --repair |\n| No module named pipeline | unlock-tool → reinstall → setup --repair |\n| Warming forever | engine ensure . --wait 45 |\n\n### Terminology\n\nUse: Scubiee, `scubiee`, `~/.scubiee`, init + connect, `resume` (machine), `activate` (per-repo), managed/unmanaged.\n\nAvoid: context-engine, `.context-engine`, wake, \"setup does everything\".\n\n---"
    },
    {
      "id": "engineering-internals",
      "title": "Engineering internals",
      "body": "**Contract:** use Scubiee when repo is managed + healthy; else native tools.\n\n**Components:** CLI → mcp_locate → daemon/RuntimeManager → IndexManager → scan/graph/chunk/embed/vector/retrieve.\n\n**MCP surfaces (CTX_MCP_SURFACE):** phase (default: map, focus, grep, glob, workspace, status) · read · nav · graph · rich · search · grep.\n\n**Model precision:** dml/cuda/mlx/coreml → model_fp16.onnx (~260 MB) · cpu → model_int8.onnx (~132 MB).\n\n**Incremental defaults:** CTX_LIVE_MAX_FILES=200 · CTX_SYNC_INTERVAL_MS=300000 · CTX_BULK_REINDEX_THRESHOLD=300.\n\n**Operator runbook:**\n\n```bash\nscubiee preflight .\nscubiee doctor . --all\nscubiee sync . && scubiee sync-now .\nscubiee rebuild .\nscubiee setup --repair\nscubiee migrate . --check-all\n```"
    }
  ]
}