conexus 2.3.3__tar.gz → 2.3.5__tar.gz

{conexus-2.3.3 → conexus-2.3.5}/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "nx",
       "source": "./nx",
       "description": "Self-hosted three-tier knowledge management with 15 specialized agents, semantic search, and RDR decision tracking for Claude Code.",
-      "version": "2.3.3"
+      "version": "2.3.5"
     }
   ]
 }

{conexus-2.3.3 → conexus-2.3.5}/CHANGELOG.md

@@ -6,13 +6,42 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.3.5] - 2026-03-23
+
+### Docs
+- **Streamlined getting-started guide** — linear flow from prerequisites through
+  install, verify, use, plugin, cloud. Added `nx doctor` verify step, Python 3.14
+  workaround, `uv tool update` instructions, and `conexus[cloud]`/`conexus[local]`
+  extras documentation.
+- **Three-pass substantive critique** — fixed query model docs (CCE collections use
+  voyage-context-3 for both index and query), removed "T3 cloud" mislabeling from
+  CLI reference, corrected tuning YAML structure (nested subsections, not flat keys),
+  fixed local-mode auto-detection docs (either key absent, not both), added missing
+  `--on-locked` flag and `NX_VOYAGEAI_READ_TIMEOUT_SECONDS` env var, corrected
+  minified code detection description, and replaced all `pip install` with `uv` syntax.
+- **Unprefixed skill references** — corrected `/rdr-create` → `/nx:rdr-create` etc.
+  across all documentation and RDR files.
+
+### Fixed
+- **`is_local_mode()` docstring** — corrected to match implementation (either key
+  absent triggers local mode, not both).
+
+## [2.3.4] - 2026-03-23
+
+### Fixed
+- **Python 3.14 compatibility** — `voyageai` uses Pydantic v1 compat layer which
+  is broken on Python ≥ 3.14. Moved `voyageai` from required to optional dependency
+  (`pip install conexus[cloud]`). Capped `requires-python` to `<3.14` so uv/pip
+  auto-select Python 3.13. All `import voyageai` sites guarded with clear error
+  messages pointing to `conexus[cloud]`.
+- **Unprefixed skill references in docs** — all `/rdr-create`, `/rdr-close`, etc.
+  corrected to `/nx:rdr-create`, `/nx:rdr-close` across 11 documentation files.
+
 ## [2.3.3] - 2026-03-23
 
 ### Fixed
-- **Python 3.14 compatibility** — `import voyageai` at module level in `t3.py`
-  crashed on Python 3.14 due to Pydantic v1 incompatibility in the voyageai SDK.
-  Import is now guarded with `try/except`; cloud mode raises a clear error, local
-  mode works without voyageai.
+- **Python 3.14 compatibility** (partial) — guarded `import voyageai` in `t3.py`
+  but missed `retry.py` and other import sites. Superseded by 2.3.4.
 
 ## [2.3.2] - 2026-03-22
 

{conexus-2.3.3 → conexus-2.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conexus
-Version: 2.3.3
+Version: 2.3.5
 Summary: Self-hosted semantic search and knowledge management for LLM-driven development
 Project-URL: Homepage, https://github.com/Hellblazer/nexus
 Project-URL: Repository, https://github.com/Hellblazer/nexus
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
-Requires-Python: >=3.12
+Requires-Python: <3.14,>=3.12
 Requires-Dist: chromadb>=0.6
 Requires-Dist: click>=8.1
 Requires-Dist: docling>=2.76.0
@@ -33,7 +33,8 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: structlog>=24.0
 Requires-Dist: tqdm>=4.65
 Requires-Dist: tree-sitter-language-pack==0.7.1
-Requires-Dist: voyageai>=0.2
+Provides-Extra: cloud
+Requires-Dist: voyageai>=0.2; extra == 'cloud'
 Provides-Extra: local
 Requires-Dist: fastembed>=0.7.0; extra == 'local'
 Description-Content-Type: text/markdown
@@ -71,22 +72,27 @@ nx store put --collection knowledge__myapp "API rate limit is 10k/min per the ve
 
 ## Quick Start
 
+Requires Python 3.12–3.13 and [uv](https://docs.astral.sh/uv/).
+
 ```bash
 uv tool install conexus          # install the nx CLI
-nx index repo .                  # index your repo (works immediately — no API keys needed)
+nx doctor                        # verify installation
+nx index repo .                  # index your repo (no API keys needed)
 nx search "what does X do"       # semantic search, fully local
 ```
 
-Local mode uses bundled ONNX embeddings — zero configuration required. For higher-quality cloud embeddings, run `nx config init` to set up API keys. See [Getting Started](https://github.com/Hellblazer/nexus/blob/main/docs/getting-started.md) for the full walkthrough.
+Update: `uv tool update conexus`
+
+Works immediately with local ONNX embeddings — no accounts, no API keys. For higher-quality cloud embeddings (Voyage AI), see the [cloud setup instructions](https://github.com/Hellblazer/nexus/blob/main/docs/getting-started.md#cloud-mode-optional).
 
-For Claude Code, also install the plugin (see [plugin documentation](https://github.com/Hellblazer/nexus/blob/main/nx/README.md)):
+For Claude Code, install the plugin:
 
 ```bash
 /plugin marketplace add Hellblazer/nexus
 /plugin install nx@nexus-plugins
 ```
 
-All three tiers work with **zero API keys** — including semantic search, which uses local ONNX embeddings by default. For higher-quality embeddings, optionally configure [ChromaDB Cloud](https://www.trychroma.com/) and [Voyage AI](https://www.voyageai.com/) (free tiers available). See [Getting Started](https://github.com/Hellblazer/nexus/blob/main/docs/getting-started.md) for the full walkthrough.
+See [Getting Started](https://github.com/Hellblazer/nexus/blob/main/docs/getting-started.md) for the full walkthrough.
 
 ## Three tiers, one lifecycle
 
@@ -110,7 +116,7 @@ nx index pdf paper.pdf --collection knowledge__ml  # reference papers
 nx store put --collection knowledge__ops "Redis maxmemory-policy: allkeys-lru for cache, noeviction for queues"
 ```
 
-Repository indexing (`nx index repo`) is the most automated path. It classifies git-tracked files, chunks code into logical pieces via tree-sitter AST parsing across 31 languages, and embeds each chunk with purpose-matched Voyage AI models. Recently-touched files rank higher via git frecency scoring.
+Repository indexing (`nx index repo`) is the most automated path. It classifies git-tracked files, chunks code into logical pieces via tree-sitter AST parsing across 31 languages, and embeds each chunk using local ONNX models by default, or Voyage AI models in cloud mode. Recently-touched files rank higher via git frecency scoring.
 
 See [Repo Indexing](https://github.com/Hellblazer/nexus/blob/main/docs/repo-indexing.md) for details and `.nexus.yml` configuration.
 
@@ -171,12 +177,12 @@ Full details: [CLI Reference](https://github.com/Hellblazer/nexus/blob/main/docs
 2. [Workflow](https://github.com/Hellblazer/nexus/blob/main/docs/rdr-workflow.md) — Create → Research → Gate → Accept → Close
 3. [Nexus Integration](https://github.com/Hellblazer/nexus/blob/main/docs/rdr-nexus-integration.md) — How storage tiers and agents amplify RDRs
 4. [Templates](https://github.com/Hellblazer/nexus/blob/main/docs/rdr-templates.md) — Minimal and full examples, post-mortem template
-5. [Project RDR Index](https://github.com/Hellblazer/nexus/blob/main/docs/rdr/README.md) — All 36 project RDRs with status
+5. [Project RDR Index](https://github.com/Hellblazer/nexus/blob/main/docs/rdr/README.md) — All project RDRs with status
 
 ## Prerequisites
 
-- Python 3.12+, [`uv`](https://docs.astral.sh/uv/), `git`
-- For semantic search: [ChromaDB cloud](https://www.trychroma.com/) + [Voyage AI](https://www.voyageai.com/) (free tiers available)
+- Python 3.12–3.13, [`uv`](https://docs.astral.sh/uv/), `git`
+- For cloud embeddings (optional): `uv tool install conexus --with "conexus[cloud]" --force` + [ChromaDB Cloud](https://www.trychroma.com/) + [Voyage AI](https://www.voyageai.com/) accounts (free tiers available)
 - For hybrid search: [`ripgrep`](https://github.com/BurntSushi/ripgrep)
 
 ## License

{conexus-2.3.3 → conexus-2.3.5}/README.md

@@ -31,22 +31,27 @@ nx store put --collection knowledge__myapp "API rate limit is 10k/min per the ve
 
 ## Quick Start
 
+Requires Python 3.12–3.13 and [uv](https://docs.astral.sh/uv/).
+
 ```bash
 uv tool install conexus          # install the nx CLI
-nx index repo .                  # index your repo (works immediately — no API keys needed)
+nx doctor                        # verify installation
+nx index repo .                  # index your repo (no API keys needed)
 nx search "what does X do"       # semantic search, fully local
 ```
 
-Local mode uses bundled ONNX embeddings — zero configuration required. For higher-quality cloud embeddings, run `nx config init` to set up API keys. See [Getting Started](https://github.com/Hellblazer/nexus/blob/main/docs/getting-started.md) for the full walkthrough.
+Update: `uv tool update conexus`
+
+Works immediately with local ONNX embeddings — no accounts, no API keys. For higher-quality cloud embeddings (Voyage AI), see the [cloud setup instructions](https://github.com/Hellblazer/nexus/blob/main/docs/getting-started.md#cloud-mode-optional).
 
-For Claude Code, also install the plugin (see [plugin documentation](https://github.com/Hellblazer/nexus/blob/main/nx/README.md)):
+For Claude Code, install the plugin:
 
 ```bash
 /plugin marketplace add Hellblazer/nexus
 /plugin install nx@nexus-plugins
 ```
 
-All three tiers work with **zero API keys** — including semantic search, which uses local ONNX embeddings by default. For higher-quality embeddings, optionally configure [ChromaDB Cloud](https://www.trychroma.com/) and [Voyage AI](https://www.voyageai.com/) (free tiers available). See [Getting Started](https://github.com/Hellblazer/nexus/blob/main/docs/getting-started.md) for the full walkthrough.
+See [Getting Started](https://github.com/Hellblazer/nexus/blob/main/docs/getting-started.md) for the full walkthrough.
 
 ## Three tiers, one lifecycle
 
@@ -70,7 +75,7 @@ nx index pdf paper.pdf --collection knowledge__ml  # reference papers
 nx store put --collection knowledge__ops "Redis maxmemory-policy: allkeys-lru for cache, noeviction for queues"
 ```
 
-Repository indexing (`nx index repo`) is the most automated path. It classifies git-tracked files, chunks code into logical pieces via tree-sitter AST parsing across 31 languages, and embeds each chunk with purpose-matched Voyage AI models. Recently-touched files rank higher via git frecency scoring.
+Repository indexing (`nx index repo`) is the most automated path. It classifies git-tracked files, chunks code into logical pieces via tree-sitter AST parsing across 31 languages, and embeds each chunk using local ONNX models by default, or Voyage AI models in cloud mode. Recently-touched files rank higher via git frecency scoring.
 
 See [Repo Indexing](https://github.com/Hellblazer/nexus/blob/main/docs/repo-indexing.md) for details and `.nexus.yml` configuration.
 
@@ -131,12 +136,12 @@ Full details: [CLI Reference](https://github.com/Hellblazer/nexus/blob/main/docs
 2. [Workflow](https://github.com/Hellblazer/nexus/blob/main/docs/rdr-workflow.md) — Create → Research → Gate → Accept → Close
 3. [Nexus Integration](https://github.com/Hellblazer/nexus/blob/main/docs/rdr-nexus-integration.md) — How storage tiers and agents amplify RDRs
 4. [Templates](https://github.com/Hellblazer/nexus/blob/main/docs/rdr-templates.md) — Minimal and full examples, post-mortem template
-5. [Project RDR Index](https://github.com/Hellblazer/nexus/blob/main/docs/rdr/README.md) — All 36 project RDRs with status
+5. [Project RDR Index](https://github.com/Hellblazer/nexus/blob/main/docs/rdr/README.md) — All project RDRs with status
 
 ## Prerequisites
 
-- Python 3.12+, [`uv`](https://docs.astral.sh/uv/), `git`
-- For semantic search: [ChromaDB cloud](https://www.trychroma.com/) + [Voyage AI](https://www.voyageai.com/) (free tiers available)
+- Python 3.12–3.13, [`uv`](https://docs.astral.sh/uv/), `git`
+- For cloud embeddings (optional): `uv tool install conexus --with "conexus[cloud]" --force` + [ChromaDB Cloud](https://www.trychroma.com/) + [Voyage AI](https://www.voyageai.com/) accounts (free tiers available)
 - For hybrid search: [`ripgrep`](https://github.com/BurntSushi/ripgrep)
 
 ## License

{conexus-2.3.3 → conexus-2.3.5}/docs/cli-reference.md

@@ -17,7 +17,7 @@ nx search "authentication middleware" --corpus code --hybrid --n 20
 | `QUERY` (positional) | Search query text |
 | `PATH` (positional, optional) | Scope search to files under that directory |
 | `--corpus NAME` | Collection prefix or full name (repeatable; default: `knowledge`, `code`, `docs`) |
-| `--hybrid` | Merge semantic + ripgrep results for code (0.7*vector + 0.3*frecency) |
+| `--hybrid` | Augment semantic results with frecency-weighted ranking and ripgrep keyword matches (0.7*vector + 0.3*frecency). Requires ripgrep |
 | `--no-rerank` | Disable cross-corpus reranking (use round-robin instead) |
 | `--where KEY=VALUE` | Metadata filter (repeatable; multiple flags are ANDed) |
 | `--max-file-chunks N` | Exclude chunks from files larger than N chunks (code corpora only; ANDs with `--where`) |
@@ -38,7 +38,7 @@ nx search "authentication middleware" --corpus code --hybrid --n 20
 
 ## nx index
 
-Index content into T3 cloud collections.
+Index content into T3 collections.
 
 ```
 nx index repo ./my-project
@@ -64,6 +64,7 @@ nx index repo ./my-project
 |------|-------------|
 | `--frecency-only` | Update frecency scores only; skip re-embedding (faster, for re-ranking refresh). Mutually exclusive with `--force` |
 | `--force-stale` | Re-index only if collection pipeline version is outdated (smart force — skips current collections) |
+| `--on-locked {skip,wait}` | Behavior when another process holds the repo lock: `skip` exits immediately, `wait` blocks (default: `wait`) |
 
 **`pdf` and `md` flags:**
 
@@ -82,7 +83,7 @@ nx index repo ./my-project
 
 ## nx store
 
-Manage T3 cloud knowledge entries.
+Manage T3 knowledge entries.
 
 ```
 echo "# Cache Strategy" | nx store put - --collection knowledge --title "decision-cache" --tags "decision,arch"
@@ -220,7 +221,7 @@ nx scratch put "hypothesis: cache invalidation is stale"
 
 ## nx collection
 
-Manage T3 cloud collections.
+Manage T3 collections (local or cloud).
 
 ```
 nx collection list
@@ -228,7 +229,7 @@ nx collection list
 
 | Subcommand | Description |
 |------------|-------------|
-| `list` | All cloud collections with document counts |
+| `list` | All T3 collections with document counts |
 | `info NAME` | Details for one collection |
 | `verify NAME` | Existence check + document count |
 | `delete NAME` | Delete collection (irreversible) |

{conexus-2.3.3 → conexus-2.3.5}/docs/configuration.md

@@ -13,7 +13,7 @@ Each level is deep-merged, with higher-priority values winning.
 
 ## Local Mode
 
-Nexus auto-detects local mode when cloud credentials are absent. No configuration needed — just `pip install conexus && nx index repo .`.
+Nexus auto-detects local mode when cloud credentials are absent. No configuration needed — just `uv tool install conexus && nx index repo .`.
 
 | Env var | Default | Description |
 |---|---|---|
@@ -21,9 +21,9 @@ Nexus auto-detects local mode when cloud credentials are absent. No configuratio
 | `NX_LOCAL_CHROMA_PATH` | `~/.local/share/nexus/chroma` | Override local ChromaDB storage path |
 | `NX_LOCAL_EMBED_MODEL` | (auto) | Force a specific local embedding model name |
 
-**Auto-detection**: When both `CHROMA_API_KEY` and `VOYAGE_API_KEY` are absent, local mode activates. Set `NX_LOCAL=1` to force local mode even with cloud credentials.
+**Auto-detection**: When either `CHROMA_API_KEY` or `VOYAGE_API_KEY` is absent, local mode activates — both are required for cloud mode. Set `NX_LOCAL=1` to force local mode even with cloud credentials.
 
-**Embedding tiers**: Tier 0 (bundled MiniLM-L6-v2, 384d) is always available. Install `pip install conexus[local]` for tier 1 (bge-base-en-v1.5, 768d, better quality).
+**Embedding tiers**: Tier 0 (bundled MiniLM-L6-v2, 384d) is always available. Install with `uv tool install conexus --with "conexus[local]" --force` for tier 1 (bge-base-en-v1.5, 768d, better quality).
 
 **Storage path**: Defaults to `$XDG_DATA_HOME/nexus/chroma` or `~/.local/share/nexus/chroma`. Override with `NX_LOCAL_CHROMA_PATH`.
 
@@ -54,8 +54,9 @@ Set via `nx config init` (wizard) or `nx config set KEY VALUE`. Stored in `~/.co
 |---|---|---|---|
 | `embeddings.rerankerModel` | `NX_EMBEDDINGS_RERANKER_MODEL` | `rerank-2.5` | Voyage reranker for multi-corpus merge |
 | `client.host` | `NX_CLIENT_HOST` | `localhost` | Override ChromaDB host URL |
+| `voyageai.read_timeout_seconds` | `NX_VOYAGEAI_READ_TIMEOUT_SECONDS` | `120` | Request timeout (seconds) for Voyage AI API calls. Increase for large PDF indexing |
 
-Embedding models are selected automatically based on collection type (see [Storage Tiers](storage-tiers.md)): `voyage-code-3` for code, `voyage-context-3` for docs/knowledge at index time, `voyage-4` for all queries.
+Embedding models are selected automatically based on collection type (see [Storage Tiers](storage-tiers.md)): `voyage-code-3` for code, `voyage-context-3` (CCE) for docs/rdr/knowledge at both index and query time, `voyage-4` for code queries only.
 
 ## Per-Repo Overrides (.nexus.yml)
 
@@ -77,26 +78,30 @@ The `[tuning]` section in `~/.config/nexus/config.yml` controls search scoring,
 
 ```yaml
 tuning:
-  vector_weight: 0.7              # weight for vector similarity in hybrid scoring
-  frecency_weight: 0.3            # weight for git frecency in hybrid scoring
-  file_size_threshold: 30         # chunks — files larger than this are down-ranked
-  decay_rate: 0.01                # frecency decay rate (higher = faster decay)
-  code_chunk_lines: 150           # target lines per code chunk (fallback splitter)
-  pdf_chunk_chars: 1500           # target chars per PDF chunk
-  git_log_timeout: 30             # seconds — timeout for git log subprocess
-  ripgrep_timeout: 10             # seconds — timeout for ripgrep subprocess in hybrid search
+  scoring:
+    vector_weight: 0.7            # weight for vector similarity in hybrid scoring
+    frecency_weight: 0.3          # weight for git frecency in hybrid scoring
+    file_size_threshold: 30       # chunks — files larger than this are down-ranked
+  frecency:
+    decay_rate: 0.01              # frecency decay rate (higher = faster decay)
+  chunking:
+    code_chunk_lines: 150         # target lines per code chunk (fallback splitter)
+    pdf_chunk_chars: 1500         # target chars per PDF chunk
+  timeouts:
+    git_log: 30                   # seconds — timeout for git log subprocess
+    ripgrep: 10                   # seconds — timeout for ripgrep subprocess in hybrid search
 ```
 
-| Key | Default | Description |
+| YAML path | Default | Description |
 |-----|---------|-------------|
-| `vector_weight` | `0.7` | Vector similarity weight in hybrid scoring formula |
-| `frecency_weight` | `0.3` | Git frecency weight in hybrid scoring formula |
-| `file_size_threshold` | `30` | Chunk count above which code files are down-ranked |
-| `decay_rate` | `0.01` | Exponential decay rate for frecency scoring |
-| `code_chunk_lines` | `150` | Target lines per code chunk (line-based fallback) |
-| `pdf_chunk_chars` | `1500` | Target characters per PDF chunk |
-| `git_log_timeout` | `30` | Timeout (seconds) for `git log` subprocess |
-| `ripgrep_timeout` | `10` | Timeout (seconds) for `rg` subprocess in hybrid search |
+| `tuning.scoring.vector_weight` | `0.7` | Vector similarity weight in hybrid scoring formula |
+| `tuning.scoring.frecency_weight` | `0.3` | Git frecency weight in hybrid scoring formula |
+| `tuning.scoring.file_size_threshold` | `30` | Chunk count above which code files are down-ranked |
+| `tuning.frecency.decay_rate` | `0.01` | Exponential decay rate for frecency scoring |
+| `tuning.chunking.code_chunk_lines` | `150` | Target lines per code chunk (line-based fallback) |
+| `tuning.chunking.pdf_chunk_chars` | `1500` | Target characters per PDF chunk |
+| `tuning.timeouts.git_log` | `30` | Timeout (seconds) for `git log` subprocess |
+| `tuning.timeouts.ripgrep` | `10` | Timeout (seconds) for `rg` subprocess in hybrid search |
 
 These values are exposed as a `TuningConfig` dataclass in `nexus.config`. The search command, indexer, and scoring modules all read from this config — changes take effect on the next invocation without restarting anything.
 

{conexus-2.3.3 → conexus-2.3.5}/docs/contributing.md

@@ -31,7 +31,7 @@ uv run pytest -m integration
 
 ## Code Conventions
 
-- **Python 3.12+**: use `match/case`, `tomllib`, `typing.Protocol`, walrus operator
+- **Python 3.12–3.13**: use `match/case`, `tomllib`, `typing.Protocol`, walrus operator
 - **Type hints everywhere**: all public functions, methods, module-level variables
 - **No ORM**: raw `sqlite3` for T2
 - **Logging**: `structlog` — never `print()` in library code
@@ -76,7 +76,7 @@ Do not bump these without testing the full chunking pipeline.
 ## Git Workflow
 
 - Branch naming: `feature/<bead-id>-<short-description>`
-- Never push directly to `main` — all changes via PR
+- Never push directly to `main` — all changes via PR (exception: version-bump release commits, see Release Process below)
 - Use `bd` (beads) for task tracking
 
 The `main` branch requires CI to pass before merging. Configure branch protection at
@@ -176,7 +176,7 @@ Every step below is **required**. Missing any one of them has caused problems in
     ```bash
     gh run watch   # watch CI until green
     gh release view vX.Y.Z
-    pip index versions conexus   # confirm new version appears on PyPI
+    uv pip compile --no-deps conexus==X.Y.Z  # confirm version resolves on PyPI
     ```
 
 11. **Yank pre-release versions** (if applicable)

conexus-2.3.5/docs/getting-started.md

@@ -0,0 +1,174 @@
+# Getting Started with Nexus
+
+## Prerequisites
+
+- **Python 3.12 or 3.13** (3.14 is not yet supported — [upstream dependency issue](https://github.com/pydantic/pydantic/issues))
+- **[uv](https://docs.astral.sh/uv/)** — Python package manager
+- **git**
+
+Check your Python version:
+
+```bash
+python3 --version
+```
+
+If you're on 3.14+, install 3.13 with `uv python install 3.13` — uv will use it automatically.
+
+## Install
+
+```bash
+uv tool install conexus
+```
+
+Verify:
+
+```bash
+nx --version
+nx doctor
+```
+
+`nx doctor` checks dependencies, credentials, and connectivity. Everything should show `✓` except cloud credentials (which are optional).
+
+## Update
+
+```bash
+uv tool update conexus
+```
+
+## Use it (no API keys needed)
+
+Everything below works immediately — no accounts, no network.
+
+### Index and search a repo
+
+```bash
+cd your-project
+nx index repo .              # index with local ONNX embeddings
+nx search "retry logic"      # semantic search, fully local
+```
+
+### Scratch — ephemeral inter-agent context (T1)
+
+```bash
+nx scratch put "working hypothesis: the cache TTL is too short"
+nx scratch list
+nx scratch search "cache"
+```
+
+### Memory — persistent project notes (T2)
+
+```bash
+nx memory put "auth uses JWT with 24h expiry" -p myproject -t auth-notes
+nx memory search "JWT" -p myproject
+nx memory get -p myproject -t auth-notes
+```
+
+## Claude Code plugin (optional)
+
+The `nx` plugin gives Claude Code agents access to all three storage tiers, 15 specialized agents, and 28 development workflow skills.
+
+```bash
+/plugin marketplace add Hellblazer/nexus
+/plugin install nx@nexus-plugins
+```
+
+After installing, run `/nx:nx-preflight` to verify all plugin dependencies (nx CLI, beads, superpowers plugin) are present.
+
+See [plugin documentation](https://github.com/Hellblazer/nexus/blob/main/nx/README.md) for the full agent/skill reference. For local development from a repo checkout:
+
+```bash
+claude --plugin-dir ./nx
+```
+
+## Cloud mode (optional)
+
+Local mode uses bundled ONNX embeddings (384d MiniLM). Cloud mode upgrades to Voyage AI (1024d), cross-chunk context (CCE), and reranking.
+
+### 1. Install the cloud extra
+
+```bash
+uv tool install conexus --with "conexus[cloud]" --force
+```
+
+The same command works for both first install and updates.
+
+### 2. Create accounts
+
+| Service | Purpose | Free tier |
+|---------|---------|-----------|
+| [ChromaDB Cloud](https://trychroma.com) | Vector storage | Generous for individual use |
+| [Voyage AI](https://voyageai.com) | Embeddings | 200M tokens/month |
+
+Both free tiers cover typical usage at no cost.
+
+### 3. Configure credentials
+
+Interactive wizard:
+
+```bash
+nx config init
+```
+
+Or set individually:
+
+```bash
+nx config set chroma_api_key sk-...
+nx config set chroma_database nexus
+nx config set voyage_api_key pa-...
+```
+
+### 4. Verify
+
+```bash
+nx doctor
+```
+
+All items should show `✓`. Fix anything marked `✗` before proceeding.
+
+### 5. Index and search
+
+```bash
+nx index repo .
+nx search "how does authentication work"
+nx search "retry logic" --corpus code
+nx search "API changelog" --corpus docs
+nx search "database pool" --hybrid       # semantic + keyword matching
+```
+
+Common flags: `-n 20` (result count), `--json`, `--files` (paths only), `-c` (show matched text). `--hybrid` requires [ripgrep](https://github.com/BurntSushi/ripgrep).
+
+### Upgrade local embedding quality (optional)
+
+For better local-only embeddings (768d bge-base) without cloud:
+
+```bash
+uv tool install conexus --with "conexus[local]" --force
+```
+
+To force local mode even when cloud credentials exist: `NX_LOCAL=1`.
+
+## Troubleshooting
+
+**`nx` command not found** — Make sure `~/.local/bin` is on your PATH. Run `uv tool install conexus` again and check the output for the install location.
+
+**Crash on startup (Python 3.14)** — Nexus requires Python 3.12–3.13. If `python3 --version` shows 3.14, install 3.13: `uv python install 3.13`, then reinstall: `uv tool install conexus --force`.
+
+**`nx doctor` reports credentials not set** — Expected for local mode. Only needed if you want cloud embeddings — run `nx config init`.
+
+**Provisioning failed during `nx config init`** — If your ChromaDB plan restricts automatic database creation, create the database manually in the [dashboard](https://trychroma.com) using your `chroma_database` value as the name.
+
+**`nx index repo .` fails with "credentials not set"** — In cloud mode, indexing requires T3 credentials. Run `nx config init` first, or use local mode (no credentials needed).
+
+**`import voyageai` error when using cloud features** — Install the cloud extra: `uv tool install conexus --with "conexus[cloud]" --force`
+
+**First index is slow or hits a rate limit** — Large repos may take a few minutes. Add `--monitor` for per-file progress. Re-running is safe — unchanged files are skipped.
+
+**`nx search` returns no results** — Run `nx doctor` to verify connectivity. If indexing was interrupted, re-run `nx index repo .` to resume.
+
+## Next steps
+
+- [CLI Reference](https://github.com/Hellblazer/nexus/blob/main/docs/cli-reference.md) — every command, every flag
+- [Storage Tiers](https://github.com/Hellblazer/nexus/blob/main/docs/storage-tiers.md) — T1, T2, T3 architecture
+- [Repo Indexing](https://github.com/Hellblazer/nexus/blob/main/docs/repo-indexing.md) — file classification, chunking, frecency
+- [Configuration](https://github.com/Hellblazer/nexus/blob/main/docs/configuration.md) — config keys, environment variables, tuning
+- [RDR Overview](https://github.com/Hellblazer/nexus/blob/main/docs/rdr-overview.md) — decision tracking with Research-Design-Review