conexus 2.3.4__tar.gz → 2.3.6__tar.gz

{conexus-2.3.4 → conexus-2.3.6}/.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.4"
+      "version": "2.3.6"
     }
   ]
 }

{conexus-2.3.4 → conexus-2.3.6}/CHANGELOG.md

@@ -6,6 +6,34 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.3.6] - 2026-03-23
+
+### Fixed
+- **Restore voyageai as required dependency** — the `conexus[cloud]` optional extra
+  was an unnecessary workaround. Since `requires-python < 3.14` blocks the only
+  incompatible Python version, voyageai always works on supported Pythons. Reverted
+  to direct `import voyageai` with no guards. Removed the `cloud` extra.
+
+## [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

{conexus-2.3.4 → conexus-2.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conexus
-Version: 2.3.4
+Version: 2.3.6
 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
@@ -33,8 +33,7 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: structlog>=24.0
 Requires-Dist: tqdm>=4.65
 Requires-Dist: tree-sitter-language-pack==0.7.1
-Provides-Extra: cloud
-Requires-Dist: voyageai>=0.2; extra == 'cloud'
+Requires-Dist: voyageai>=0.2
 Provides-Extra: local
 Requires-Dist: fastembed>=0.7.0; extra == 'local'
 Description-Content-Type: text/markdown
@@ -72,22 +71,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
 
@@ -111,7 +115,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.
 
@@ -172,12 +176,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): [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.4 → conexus-2.3.6}/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): [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.4 → conexus-2.3.6}/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.4 → conexus-2.3.6}/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.4 → conexus-2.3.6}/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.6/docs/getting-started.md

@@ -0,0 +1,166 @@
+# 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. 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.
+
+### 2. 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-...
+```
+
+### 3. Verify
+
+```bash
+nx doctor
+```
+
+All items should show `✓`. Fix anything marked `✗` before proceeding.
+
+### 4. 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** — Reinstall: `uv tool install conexus --force`. If on Python 3.14, downgrade to 3.13: `uv python install 3.13` then reinstall.
+
+**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

{conexus-2.3.4 → conexus-2.3.6}/docs/memory-and-tasks.md

@@ -22,7 +22,7 @@ active decisions, working state — and retrieve it by project and title.
 The plugin's SessionStart hooks automatically surface T2 memory context so
 agents know where a project stands without being told. Two hooks contribute:
 
-1. `nx hook session-start` lists recent T2 entries for the current repo.
+1. `nx hook session-start` (internal, invoked by plugin hooks) lists recent T2 entries for the current repo.
 
 2. The plugin's `session_start_hook.py` scans all T2 namespaces for the
    project (bare, `_rdr`, etc.) and injects a summary, along with ready beads.

{conexus-2.3.4 → conexus-2.3.6}/docs/rdr/rdr-007-claude-adoption-session-context-and-search-guidance.md

@@ -94,7 +94,7 @@ The following was tested in a single session against the arcaneum project:
 --show-toplevel` → `Path(toplevel).name`. For repo `arcaneum`, this produces
 `arcaneum`. The hook then calls `nx memory list --project arcaneum`.
 
-The RDR workflow (via `/rdr-create` and the `rdr_hook.py`) populates T2 under
+The RDR workflow (via `/nx:rdr-create` and the `rdr_hook.py`) populates T2 under
 `{repo_name}_rdr` (e.g., `arcaneum_rdr`). These are different keys in the T2
 store.
 
@@ -348,7 +348,7 @@ contradicts the actual namespace conventions in use (`{repo}_rdr`,
 **Project naming**: Use purpose-specific suffixes for different memory domains:
 
 - bare `{repo}` — general project memory and notes
-- `{repo}_rdr` — RDR documents and gate results (populated by `/rdr-create`)
+- `{repo}_rdr` — RDR documents and gate results (populated by `/nx:rdr-create`)
 - `{repo}_pm` — project management context (populated by `nx pm`)
 
 The session hook discovers all populated namespaces by prefix scan; content

{conexus-2.3.4 → conexus-2.3.6}/docs/rdr-overview.md

@@ -56,7 +56,7 @@ Flag assumptions that your design depends on. Low-stakes assumptions need no ver
 
 RDRs are not waterfall documents written once before implementation. They're iterative — write one, build, learn from what you find, write the next one. Each RDR builds on what earlier ones established, and sometimes an implementation reveals that a prior decision needs revisiting.
 
-The Nexus project has produced 36 RDRs across its development. The corpus is searchable, so when starting a new design, prior decisions surface automatically — preventing contradictions and avoiding redundant investigation.
+The Nexus project has produced over 35 RDRs across its development. The corpus is searchable, so when starting a new design, prior decisions surface automatically — preventing contradictions and avoiding redundant investigation.
 
 ## Statuses and types
 

{conexus-2.3.4 → conexus-2.3.6}/docs/repo-indexing.md

@@ -41,12 +41,12 @@ Classification is overridable via `.nexus.yml` (see [Per-Repo Configuration](#ne
 
 ## Dual-Collection Architecture
 
-Each indexed repository produces two T3 (ChromaDB Cloud) collections:
+Each indexed repository produces two T3 collections (local ONNX or cloud Voyage AI):
 
-| Collection | Embedding Model (Index) | Embedding Model (Query) | Contents |
+| Collection | Cloud Index Model | Cloud Query Model | Contents |
 |---|---|---|---|
 | `code__<name>-<hash8>` | `voyage-code-3` | `voyage-4` | Code files |
-| `docs__<name>-<hash8>` | `voyage-context-3` (CCE) | `voyage-4` | Prose + PDF files |
+| `docs__<name>-<hash8>` | `voyage-context-3` (CCE) | `voyage-context-3` | Prose + PDF files |
 
 `<name>` is the repository basename; `<hash8>` is the first 8 hex characters of the
 SHA-256 digest of the main repository path. Long basenames are truncated to stay within
@@ -107,10 +107,7 @@ line-based splitting: 150-line chunks with 15% overlap.
 
 ### Minified Code Handling
 
-The AST chunker detects minified files (average line length > 500 characters) and falls
-back to byte-based splitting instead of producing single oversized chunks. This prevents
-minified JavaScript, CSS, and similar files from consuming disproportionate storage and
-degrading search quality.
+Individual lines exceeding the byte limit (12 KB) are pre-split at natural code delimiters (`;`, `,`, `}`) before chunking. AST-produced chunks that individually exceed the byte limit are post-processed by the same line-level splitting. This prevents minified JavaScript, CSS, and similar files from producing single oversized chunks that consume disproportionate storage and degrade search quality.
 
 ### Context Prefix Injection (Embed-Only)
 
@@ -229,7 +226,7 @@ version is bumped. This enables targeted re-indexing:
   checks, so only changed files are re-embedded. This is the recommended flag after upgrading
   Nexus to a version with pipeline changes.
 
-`nx doctor` reports the pipeline version status of each collection:
+In cloud mode, `nx doctor` reports the pipeline version status of each collection. In local mode, pipeline version is not checked — run `nx index repo --force-stale` after an upgrade to refresh any outdated collections.
 
 ```
 ✓ pipeline (code__nexus-571b8edd): v4
@@ -268,5 +265,4 @@ nx search "query" --corpus code --hybrid --no-rerank  # hybrid without cross-cor
 `--corpus` resolves as a prefix: `code` matches all `code__*` collections, `docs` matches
 all `docs__*` collections. A fully-qualified name (containing `__`) matches exactly.
 
-All collections are queried with `voyage-4` at query time regardless of the index-time
-model.
+`code__*` collections are queried with `voyage-4`. CCE collections (`docs__*`, `rdr__*`, `knowledge__*`) are queried with `voyage-context-3` — the same model used at index time. Mixing models across CCE vector spaces produces near-random similarity scores.

{conexus-2.3.4 → conexus-2.3.6}/docs/storage-tiers.md

@@ -8,7 +8,7 @@ Nexus organizes data across three tiers with increasing durability. Data flows u
 |------|---------|---------|------------|-----|
 | T1 -- scratch | ChromaDB HTTP server (per-session) | Localhost only | Session only | Working notes, hypotheses |
 | T2 -- memory | SQLite + FTS5 (WAL) | None | Survives restarts | Per-project notes, session context |
-| T3 -- knowledge | ChromaDB cloud + Voyage AI | Required | Permanent | Semantic search, indexed code/docs |
+| T3 -- knowledge | Local ChromaDB (default) or ChromaDB Cloud + Voyage AI | Local: none / Cloud: required | Permanent | Semantic search, indexed code/docs |
 
 ## T1 -- Session Scratch
 
@@ -44,12 +44,12 @@ T3 has two backends: **local** (zero-config) and **cloud** (higher quality).
 
 Backed by `chromadb.PersistentClient` with local ONNX embeddings. No API keys or network required. Data stored at `~/.local/share/nexus/chroma`.
 
-| | Tier 0 (bundled) | Tier 1 (`pip install conexus[local]`) |
+| | Tier 0 (bundled) | Tier 1 (`uv tool install conexus --with "conexus[local]" --force`) |
 |---|---|---|
 | Model | all-MiniLM-L6-v2 | bge-base-en-v1.5 |
 | Dimensions | 384 | 768 |
 | Quality | Basic semantic matching | Better code & prose retrieval |
-| Install | Included | `pip install conexus[local]` |
+| Install | Included | `uv tool install conexus --with "conexus[local]" --force` |
 
 All collection types use the same local model (no per-prefix splitting). Reranking is unavailable in local mode.
 
@@ -66,10 +66,12 @@ Collections are namespaced by corpus type using `__` (double underscore) as sepa
 | Pattern | Contents | Cloud index model | Cloud query model |
 |---------|----------|-------------------|-------------------|
 | `code__<repo>-<hash>` | Indexed source code | voyage-code-3 | voyage-4 |
-| `docs__<repo>-<hash>` | Indexed prose files | voyage-context-3 (CCE) | voyage-4 |
-| `rdr__<repo>-<hash>` | Indexed RDR documents | voyage-context-3 (CCE) | voyage-4 |
-| `docs__<corpus>` | Indexed PDFs and markdown | voyage-context-3 (CCE) | voyage-4 |
-| `knowledge__<topic>` | Stored agent outputs and notes | voyage-context-3 | voyage-4 |
+| `docs__<repo>-<hash>` | Indexed prose files | voyage-context-3 (CCE) | voyage-context-3 |
+| `rdr__<repo>-<hash>` | Indexed RDR documents | voyage-context-3 (CCE) | voyage-context-3 |
+| `docs__<corpus>` | Indexed PDFs and markdown | voyage-context-3 (CCE) | voyage-context-3 |
+| `knowledge__<topic>` | Stored agent outputs and notes | voyage-context-3 (CCE) | voyage-context-3 |
+
+CCE collections must be queried with `voyage-context-3` to stay in the same vector space — `voyage-4` is not compatible. Only `code__*` collections use `voyage-4` for queries.
 
 In local mode, all collections use the active local model for both index and query.
 
@@ -120,7 +122,7 @@ T3 (knowledge)
 ### Promotion methods
 
 - **T1 -> T2**: `nx scratch promote ID --project NAME --title NAME`, or auto-flush of flagged items at session end.
-- **T2 -> T3**: `nx memory promote TITLE --collection NAME`.
+- **T2 -> T3**: `nx memory promote ID --collection NAME` (by numeric row ID from `nx memory list`).
 
 ### TTL translation on promote