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) 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: 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-<id>.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
Import takes longer than expected (large Google Doc, slow API)	timeout	Toast: "Import is taking longer than expected. Try again; larger documents need more time." Retry button appears	Retry. Imports get 120s (vs 30s for other ops). If it keeps timing out, the doc may be too large for the remote API to process in one request
Network failure (connection refused, DNS, etc.)	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 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<version> (vendored <date>)) — 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, which covers setup and everyday use, and part 3, 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 page.