--- title: ContextDock Integration (link bundles and lists to project knowledge) (part 3) --- # ContextDock Integration (link bundles and lists to project knowledge) (part 3) ## What it is This is part 3 of the [ContextDock Integration (link bundles and lists to project knowledge)](contextdock.md) page. It covers the machinery underneath the integration: where a linked bundle, list or doc is written, what the sentinel header at the top of that file carries, how the picker cache stays warm without a visible delay, how a snapshot reaches a session, and the full set of IPC channels an agent can drive. ## Where to find it Nothing in this part has a screen of its own. Everything here happens behind the surfaces described on the [parent page](contextdock.md): the picker in the Add Project Doc dialog is what the cache warms, and a project's docs section is where the written files show up as rows. The one place you can see part of it is the footer of the ContextDock card in Settings, which names the bundled CLI version. ## How it behaves ### Cache and startup preload The picker reads from a SQLite cache so opening the Add Project Doc → ContextDock tab renders instantly, no waiting on a CLI subprocess. The cache is populated by a startup **preload** that fires once, 5 seconds after the main window opens (past first paint and most critical-path hydration), and kept lightly topped-up by an **hourly** background refresh task (top-level rosters only) — a low-frequency backstop, since the renderer's on-open stale-while-revalidate is what actually keeps the picker fresh. Both write into three v162 SQLite tables (`contextdock_bundles_cache`, `contextdock_lists_cache`, `contextdock_list_detail_cache`). The docs (library roster) leg was designed to use a **delta-sync watermark** via the CLI's `--since` flag once warm, so steady-state refresh would cost a tiny round-trip rather than a full re-fetch. In practice the deployed ContextDock server currently **ignores `?since=` and returns the full docs roster** (the delta-envelope endpoint was never shipped server-side), so the docs leg applies that full roster every tick — Omniscio detects the shape and handles it cleanly, and will automatically switch back to true incremental sync if/when the server starts returning a `{ changed, deleted, serverTime }` delta. Either way the docs cache stays current; the preload leg also re-fetches the docs roster every tick. User-visible behaviour: - **Picker open with warm cache** → instant render from cache, no network call. The `Updated Xm ago` caption tells you how stale the snapshot is. - **Picker open with cold cache** → instant render from whatever's in cache (possibly empty), then a silent background refresh kicks in. If the cache was empty the picker briefly shows a loading state until the foreground refresh completes. - **Steady state** → with **Settings → ContextDock → Background refresh** on (the default), Omniscio quietly tops the cache up **hourly** in the background. You should rarely see "stale cache" because the renderer revalidates on every picker open (stale-while-revalidate) — that on-open refresh, not the hourly backstop, is what keeps the picker fresh. - **Manual refresh** → the 🔄 button next to the caption forces a foreground refresh at any time. Success toast on done; "Refresh failed — check connection and try again" toast on failure. The button disables and shows a spinning icon while in flight. - **No API key configured** → both the startup preload and the periodic refresh are no-ops (skipped silently). Connecting a key later seeds the cache on the next picker open (foreground refresh) or the next hourly tick. Background refresh task (the hourly backstop): - **Cadence.** First tick fires 60 seconds after app start (after the one-shot preload has had a chance to land), then every hour thereafter. - **Two legs per tick.** First docs (the library roster — a `?since=` "delta" call that the current server answers with the full roster, so Omniscio applies it as a full-roster refresh; a real `{ changed, deleted, serverTime }` envelope would be applied incrementally instead). Then bundles, lists, and tags **rosters** via `runContextDockTopLevelPreload()`. **Per-list-detail is not refreshed on the tick** — that pass (the expensive one-CLI-spawn-per-list leg) runs only on the manual 🔄 button and the picker's on-open refresh, which use the full `runContextDockPreload()`. Each leg is independent — a failure in docs doesn't skip the preload, and vice versa. - **User-controlled.** Toggle off at **Settings → Tools & Maintenance → ContextDock → Background refresh**. The setting is checked on every tick, so flipping it mid-session takes effect immediately (no restart, no waiting for the next interval boundary). - **Push events.** Omniscio emits a `CONTEXTDOCK_LIBRARY_CHANGED` push so any open Library / Picker view re-reads and re-renders. The docs leg emits a **scoped** `{ resource: 'docs' }` push only when it applies a genuine _incremental_ delta (so a full-roster refresh every tick doesn't trigger a needless Library refetch); the preload leg emits a **generic** push (no resource) after its full bundles/lists/tags refresh. Both shapes are valid — the push payload's `resource` field is optional. - **Telemetry.** Each tick records one `feature_events` row — `bg_refresh_ok` on success (with `durationMs`, `docsChanged`, `bundleCount`, etc.) or `bg_refresh_failed` on a runtime error. Programmer errors (`ReferenceError`, `TypeError`) surface loud rather than being swallowed. - **Env-var kill switch.** Set `AMC_DISABLE_CONTEXTDOCK_BG_REFRESH=1` before launching Omniscio to disable the task entirely for that process. Cached on first read — restart Omniscio to flip it. Behaviour guarantees: - **Best-effort.** Any CLI / network failure during preload is logged but never thrown — a cold cache is fine, the picker falls back to a foreground refresh on open. The same applies to per-list-detail fetches: one stale list id doesn't poison the whole pass. The hourly background timer follows the same contract — one failed tick is logged + telemetry-recorded but does not cancel the next tick. - **Atomic.** Bundles and lists are each wiped + re-inserted inside a single SQLite transaction, so a partial fetch can never half-update the cache (a bundle deleted upstream really disappears; a re-ordered list really re-orders). - **Per-list-detail is independent.** List-detail rows are upserted one-at-a-time keyed by `list_id`. A `pruneContextDockListDetailCache()` pass after the lists upsert drops any list-detail rows whose `list_id` is no longer in the lists cache, so the detail cache doesn't grow unbounded across refresh cycles. - **Concurrency bounded.** Per-list-detail fetches inside a preload run run at most **4 in flight**. A user with 50 lists doesn't spawn 50 simultaneous CLI subprocesses (each is a fresh Node process, expensive to start). - **Top-level warm is time-boxed.** The four top-level fetches (bundles + lists + tags + docs) race a **30-second wall-clock ceiling** (`TOP_LEVEL_PRELOAD_DEADLINE_MS`). Normally they finish in ~1–2s, but if they overrun — e.g. the CLI subprocesses are CPU-starved by a startup squeeze (a 20-session crash-recovery storm sharing Omniscio's capped Job Object once stretched this to ~186s) — the preload aborts the in-flight children (freeing CPU for the storm) and returns `{ timedOut: true }` with the cache left as-is; the hourly background refresh retries once the machine is idle. The per-process spawn `timeout` (30s) is deliberately NOT relied on for this — its kill timer is itself starved under CPU contention — so the ceiling is enforced by the preload's own deadline plus an `AbortController` threaded through the client onto `spawn({ signal })`. - **List drill-in is cache-first too.** Opening Browse on a list reads `contextdock_list_detail_cache` first and renders instantly when warm; misses fall back to a live `contextdock:list-detail` fetch. ### First-message injection ContextDock files are picked up by Omniscio's first-message injection. When you spawn a new session, Omniscio scans `/.claude/docs/`, classifies text files (no per-file cap; **500 KB total / ~125K tokens** across all files), and inlines the contents into the first user message via `buildProjectDocsContext()`. ContextDock files are regular `.md` files in this directory, so they go through this same flow with no special-casing. Injection is **first-message-only and Omniscio-native** — there is no shell hook, no ``, and nothing written to `CLAUDE.md`. The global `sync-claude-docs.sh` hook was removed 2026-05-28; injection now happens once, in Omniscio's TypeScript, with no per-turn overhead. See [project-docs-auto-injection.md](project-docs-auto-injection.md) for the full injection flow. ## For agents The map underneath the integration: where the files land, what the sentinel header carries, what the filename guard rejects, which binary performs the fetching, and every IPC channel with its payload shape. The user-facing behaviour these implement is on the [parent page](contextdock.md); the limits and error codes are on [part 2](contextdock-part-2.md). ### File naming Linked items are stored at `/.claude/docs/contextdock-.md`. The `` is the ContextDock ID — an opaque alphanumeric string matching `^[A-Za-z0-9_-]{1,128}$` (e.g. `k7zztXzJyp8v9wjiKkwu`). Bundle and list IDs share the same shape — there is no `b_`/`l_` prefix on real upstream IDs; the `kind` field on the sentinel header is what distinguishes them. Filenames use the ID only, never the display name, so renaming a bundle or list on ContextDock does not orphan the local file. ### Sentinel header Every Omniscio-linked file starts with an HTML-comment sentinel header: ```markdown # Q2 Initiative ...bundle markdown... ``` For a list, `kind: bundle` is replaced by `kind: list`; the `contextdockId` shape is identical (no prefix distinguishes bundles from lists — only the `kind` field does). Everything else in the header is the same. The sentinel marks Omniscio ownership. Omniscio will **never** delete or modify a file in `.claude/docs/` that doesn't have this header — even if the filename matches the `contextdock-.md` pattern. Files without the header are user files and are left alone. The `BEGIN/END ContextDock content` block is a soft prompt-injection mitigation. It frames the snapshot markdown as data, not as instructions for the agent. This is **not foolproof** — a determined adversary writing a doc on ContextDock can still try to coerce the agent — but it raises the bar. ### Filename collision guard When you upload, paste, or import a Google Doc into a project's docs section, Omniscio rejects any filename matching the regex `^contextdock-[A-Za-z0-9_-]+\.md$` (filename body capped at 128 chars to mirror the IPC schema). This is defense in depth — the sentinel header is the structural marker, but blocking Omniscio-pattern filenames at the upload surface prevents an impersonating user file from ever landing on disk. The regex is filesystem-safe (`[A-Za-z0-9_-]`) rather than the stricter `[bl]_[A-Za-z0-9]{8,40}` shape that bundle-only ids took, because ContextDock's server emits arbitrary ids up to 128 chars for lists (firestore-style unprefixed, hyphenated UUIDs, short test ids) — locking the filename guard to the bundle-only shape was the root cause of the "Invalid ContextDock id" toast when clicking lists. ### CLI binary ContextDock fetches go through a vendored CLI bundle at `resources/contextdock-cli/index.js`, spawned under `ELECTRON_RUN_AS_NODE=1` (matching the MemPalace pattern). The CLI talks HTTPS to `contextdock.web.app`. Omniscio never makes its own HTTPS requests to ContextDock — every request goes through the vendored CLI. Every CLI call also funnels through one governed chokepoint (`runCliRaw` in [spawn.ts](../../src/main/services/contextdock/spawn.ts)) that keeps Omniscio under the server's **per-key rate limit (120 requests/min)** — which matters because Omniscio shares ONE key across every session, window, the startup preload, and the hourly background refresh. The chokepoint (1) **paces** calls to a sliding ~100/min window (awaiting a free slot rather than erroring), (2) **merges** identical concurrent reads into a single spawn, and (3) briefly **auto-retries** a rate-limited call before surfacing it. The net effect: a `rate_limit` error is rare, and when it does surface it's a momentary "try again in a minute," never a permanent state. The classifier reads the CLI's stable **exit code** (not the English message) to label each failure, so a per-minute rate limit is never mislabeled as a token-`budget` error. Kill switch for the pacing only: `AMC_DISABLE_CONTEXTDOCK_THROTTLE=1` (coalescing and the retry stay on). The bundled version is shown in the footer of Settings → ContextDock and updates with each Omniscio release. To check what version is running, look at the footer line: `ContextDock CLI v0.2.0 (vendored 2026-05-07)`. ### IPC surfaces The renderer talks to the main process over typed Zod-validated IPC. Surfaces relevant to ContextDock: - `contextdock:get-cached` — the picker's instant-render path. Returns `{ bundles, lists, refreshedAt }` where `refreshedAt` is the older of the two table-level `MAX(refreshed_at)` timestamps (or `null` when both tables are empty). Drives the `Updated Xm ago` caption and the "is the cache stale?" check that decides whether to auto-fire a background refresh on dialog open. - `contextdock:get-cached-list-detail` — drill-in's instant-render path. Body: `{ listId }`. Returns the cached `ListDetail` for that list or `null` when there's no cached row. The drill-in falls back to `contextdock:list-detail` on a miss. - `contextdock:refresh-cache` — manual refresh button + auto-fired stale refresh. Runs the full `runContextDockPreload()` pipeline (bundles → lists → per-list-detail at concurrency 4) and writes the v162 cache tables. Returns `PreloadResult` (`{ bundleCount, listCount, listDetailCount, listDetailErrors, durationMs, skippedNoKey?, timedOut? }`). - `contextdock:list-bundles` / `contextdock:list-lists` — the underlying live-fetch channels used by the preload pipeline (and exposed for diagnostics). Each returns a `BundleSummary[]` / `ListSummary[]` with `id`, `name`, optional `description`, `docCount`, and a per-level `tokens` object (`{ original?, keyPoints?, summary? }`). The renderer-facing picker now reads through the cache, not these channels. - `contextdock:list-detail` — fired by the drill-in's cache-miss fallback and as the live pull inside `runContextDockPreload`. Returns a `ListDetail` with the list's display name plus a `docs[]` array of `{ id, title, tokens?: { original?, keyPoints?, summary? } }` rows. - `contextdock:link` — links an entire bundle or list. Body: `{ projectId, kind: 'bundle' | 'list', contextdockId, displayName, preferLevel }`. Writes one `contextdock-.md` file. Returns `{ tokens, cap?: { willClipTotal, totalAfter, totalAfterTokens, maxTokens } }` so the renderer can raise the ~125K-token total-cap clip toast. Also the undo path for middle-click deletes of bundle/list rows — the sentinel snapshot carries every field the handler needs. - `contextdock:link-doc` — links a single doc from a list's drill-in. Body: `{ projectId, docId, displayName, preferLevel }`. Writes one `contextdock-.md` file. Called once per selected doc by the drill-in's `Add (N)` button — the drill-in awaits each call sequentially so a failure on one doc doesn't abort the rest. Also the undo path for middle-click deletes of individual doc rows. - `contextdock:refresh` — re-fetches an existing link by `(projectId, contextdockId)` and rewrites the file atomically. In-flight refreshes for the same pair are deduplicated. - `contextdock:change-level` — atomic level swap for a per-doc row. Body: `{ projectId, filename, newLevel }`. Reads the existing sentinel, asserts `kind === 'doc'` (else `validation` error code), fetches the doc at `newLevel`, writes the new `contextdock-doc--.md` file, then best-effort unlinks the old file at the old level (tolerates `ENOENT`). Same-level requests short-circuit as no-op success. Returns `{ filename, tokens, cap? }` shaped like `contextdock:link` so the renderer can raise the ~125K-token total-cap clip toast. In-flight calls are deduplicated by `(projectId, filename, newLevel)`. - `contextdock:track-drill-in-commit` — thin telemetry shuttle. Body: `{ docCount, levelMix: { original, keyPoints, summary }, errorCount }`. Emits one `feature_events` row under `(feature='contextdock', action='drill_in_commit')`. Fire-and-forget from the drill-in's commit path; never blocks the user-visible flow. Every channel is wrapped in `wrapHandler` and validates input with Zod before doing any work; the renderer reads typed responses via `IpcResponseMap`. Failure responses follow the standard `{ success: false, error: '[contextdock:] ' }` envelope so the renderer can route on the `` prefix without parsing free text. ## Related The [parent page](contextdock.md) covers turning the integration on and using it day to day, and [part 2](contextdock-part-2.md) covers its limits and its error codes. The shared injection flow this page refers to is described on the [project docs auto-injection](project-docs-auto-injection.md) page, and the in-development local-first ContextDock library is on the [ContextDock (Native)](contextdock-native.md) page.