--- title: ContextDock Integration (link bundles and lists to project knowledge) (part 2) --- # ContextDock Integration (link bundles and lists to project knowledge) (part 2) ## What it is This is part 2 of the [ContextDock Integration (link bundles and lists to project knowledge)](contextdock.md) page. It covers the edges rather than the happy path: what the integration intentionally does not do, what every error code means and how to recover from it, the size caps on how much linked content can be injected into a session, and what to collect before reporting a problem. ## Where to find it Everything in this part is a consequence of the three surfaces named on the [parent page](contextdock.md): the ContextDock card in Settings, the ContextDock tab of the Add Project Doc dialog, and the rows a project shows in its docs section. The limits and the errors here appear as toasts, as a marker on a row, or as a panel in the picker, in those same places. ## How it behaves ### What it does not do - **No snapshot auto-refresh.** A linked `contextdock-.md` file in a project's docs section is only re-fetched when you right-click → Refresh. Omniscio does not poll, watch, or schedule background refreshes of linked snapshots. If you want the latest content on every session, you have to refresh manually — this matters more for lists, since their tag-matching docs can change without anyone "editing" the list itself. (The picker's bundles/lists roster _does_ refresh in the background every 5 minutes — that's a different cache; see "Cache + startup preload" below — but a linked snapshot in your project is a separate on-disk file and stays exactly as you linked it.) - **No MCP wiring.** ContextDock content is inlined into the agent's first user message by Omniscio. There is no MCP server, no tool the agent can call to query ContextDock at runtime — what's in the snapshot is what the agent sees. - **No write-back.** The agent cannot create, update, or comment on ContextDock bundles or lists. The integration is read-only. - **No composer slash command.** No `/contextdock` keyword. Linking is a project-level action, not a per-message action. - **No recipe step.** ContextDock is not a recipe step type. If you want a recipe to fetch content, run the link IPC out-of-band first. ### Errors and recovery | Scenario | Error code | What you see | What to do | | ----------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | API key is wrong (typo, never existed at server) | `auth` | Toast: "ContextDock key invalid — check Settings" | Re-paste the key in Settings → ContextDock | | Key was valid, but you revoked it on contextdock.web.app | `auth_revoked` | Toast: "ContextDock key revoked — rotate at contextdock.web.app" | **Re-login does NOT help.** Mint a brand-new key on contextdock.web.app, then update Settings | | Bundle or list was deleted server-side after linking | `not_found` | Refresh fails. Yellow dot ⚠ appears on the row | The local snapshot still works. Decide whether to keep it or unlink | | Hit the per-key rate limit (120 req/min) | `rate_limit` | Toast: "ContextDock is rate-limiting. Try again in a minute." Omniscio paces all CLI calls under the cap and briefly auto-retries a rate limit, so this is rarely seen | Usually nothing — Omniscio auto-retries and the pacing keeps you under the cap. If it persists, wait a minute and retry | | Network failure / timeout (30s spawn timeout) | `network` | Toast: "Network error reaching ContextDock. Check your connection and retry" | Local file is untouched (atomic rename never happened). Retry when network is back | | Assembled context exceeds the chosen token budget | `budget` | Toast: "That context is too large for the selected token budget. Lower the budget or include fewer documents, then try again." | Lower the budget level or include fewer docs, then retry. This is a **per-assembly size limit** (the `--budget` you picked), NOT a monthly/account cap | | Empty bundle / list (no docs in it / no docs match tags) | n/a | Toast: "Bundle has no docs — agent will see no content" | Add docs (or re-tag docs for a list) on contextdock.web.app, then refresh | | Total `.claude/docs/` exceeds the ~125K-token injection cap | n/a | Toast: ".claude/docs/ now ~NNK tokens — exceeds 125K token cap" | Split the bundle, drop docs from it, narrow a list's tag query, or accept the clip | | Vendored CLI bundle missing or corrupt | `vendor_broken` | Picker / drill-in shows red "ContextDock install needs repair" panel with the install command (no Retry button) | Run `npm run vendor:contextdock` from the Omniscio repo, then restart Omniscio | **`vendor_broken` is a development/install error**, not a runtime user-action error — it surfaces when the vendored CLI bundle at `resources/contextdock-cli/index.js` is missing or its dependencies didn't unpack correctly (most commonly after pulling a branch that bumped the CLI version without re-running the vendor script). Recovery is the same shape every time: re-run `npm run vendor:contextdock` from the Omniscio repo, then restart Omniscio. The picker and the list drill-in both replace their normal error panel with a red `ContextDock install needs repair` block that prints the exact command to run rather than offering a Retry button — Retry can't unbreak the install. The error code is emitted by `mapStderrToError` in [src/main/services/contextdock/spawn.ts](../../src/main/services/contextdock/spawn.ts) when the CLI process fails to load its own dependencies. The **`auth` vs `auth_revoked` distinction** is the most important error-code split. They look similar but recover differently: - **`auth` (KEY_INVALID)** — the key string is wrong. Re-typing it fixes it. The key may have a typo, may have been re-pasted with leading/trailing whitespace (use the input's paste handler — it auto-trims), or may have never existed. - **`auth_revoked` (KEY_REVOKED)** — the key was valid at one point but you (or someone in your workspace) explicitly revoked it. Re-pasting the same string will not help. You must mint a new key. ### Injection caps First-message injection has a single hard cap — a total budget across all `.claude/docs/` text files: | Cap | Limit | What "clipped" means | | ----- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Total | 500 KB / ~125K tokens | Once cumulative bytes across all `.claude/docs/` files exceed the budget, Omniscio stops adding more files to the injection. Files later in the doc order may be omitted entirely. There is **no** per-file cap (it was removed in the 2026-05-07 cap-raise) | When you link or refresh content that pushes the total over, Omniscio raises a toast at write time so you know it is being clipped before you hit it mid-session. Your options if you're clipped: - Split the bundle into smaller bundles on contextdock.web.app, link only the part you need; or narrow a list's tag query so it resolves to fewer docs - Drop other docs from `.claude/docs/` to free up the total budget - Use ContextDock's `version` feature to fetch a summary instead of full markdown (the Omniscio default is `keyPoints`, which is already smaller than `original`) ### Where to file bugs When reporting a ContextDock-related issue: 1. The **identity label** from the Settings → ContextDock green-check status line (the email / keyName / userId Omniscio shows next to the green check) so we can tell which key + account you're hitting. 2. The **kind** of the affected row — bundle (📦) or list (🏷️) — and whether the bug is in linking, refreshing, or unlinking. Lists run a tag query at fetch time, so reproduction steps need to call out which tags / match mode the list uses on contextdock.web.app. 3. The **CLI version** from the Settings → ContextDock footer (`ContextDock CLI v (vendored )`) — this tells us exactly which CLI bundle Omniscio is shipping. 4. The **error code** from the toast or row tooltip (`auth_revoked`, `not_found`, `rate_limit`, etc.) — distinguishes the recovery path. 5. Omniscio's `main.log` (Settings → Logs & Debugging → Open log folder) contains `[ContextDock]`-tagged lines. The vendored CLI never logs the API key — `cdk_live_*` prefixes are redacted at the spawn helper. ## Related The rest of the story is on the [parent page](contextdock.md), which covers setup and everyday use, and [part 3](contextdock-part-3.md), which covers what happens under the hood: the on-disk layout, the sentinel header, the picker cache and the IPC surface. How a linked file ends up in that first message is the shared mechanism on the [project docs auto-injection](project-docs-auto-injection.md) page.