# ckb-index-external — edge cases Reference material for the `ckb-index-external` skill. Read when a run hits an unusual situation the main steps don't cover. - **No connector-backed `libs//` exists** — report that and explain how to add one; don't touch anything. - **`source.local.yaml` doesn't exist yet for a source** — treat as read-only; this is the correct default, not a misconfiguration worth flagging loudly. Mention once, briefly, how to become the admin (`access: write` in that file) if the user seems to expect a rebuild. - **Everyone is read-only and nothing has ever been published** — report that clearly rather than silently doing nothing; this is the one case worth flagging as a real gap (nobody can currently index this source). - **Connector not authorized this session** — report which one and how to authorize it (claude.ai connector settings / `claude mcp` / `/mcp`), skip that source, keep going with the rest. Never ask the user for tokens or callback URLs. - **Fetching a published index (Step 3) fails or the remote is unreachable** — report it and fall back to whatever's already cached locally in `libs//` from a previous fetch, rather than blocking the whole run; don't let a transient network issue block a read-only user from seeing the last-known index. - **Re-running against an already-indexed source** — refresh existing document *and* entity/process pages in place (update `tldr`/`last_updated`/`confidence`/`source_fingerprint`/`source_checked`, add newly-seen `mentioned_in` edges); never duplicate a document's or entity's page, and carry every `## Notes` section across untouched. - **A document's fingerprint is unchanged since the last run** — don't re-summarize it. Advance `source_checked` to today, leave `last_updated`, `tldr`, and `confidence` exactly as they were, and spend the run's budget on the documents that did change. On a large source this is most of them, and it is the difference between a re-index that costs a full pass and one that costs a listing. - **A document's fingerprint changed** — re-fetch and re-summarize it, and say so in the report. A changed fingerprint on a document some wiki page cites is worth calling out by name: that wiki page was built from a version of this document that no longer exists. - **A previously-indexed document is no longer found at the source** — don't delete its page. Update its `tldr` with a note ("No longer found at source as of YYYY-MM-DD") and set `retention: low`, so the existing `ckb-lint` retention sweep archives it naturally on a later pass — no new archival mechanism needed. Leave any entity pages that cite it alone; the citation is still historically accurate even if the document itself is gone. - **An extracted entity already has a full page in `wiki/entities/`** — keep this connector-side page thin (evidence/`mentioned_in` pointers only, `resource:` set to the wiki page) rather than re-deriving everything the wiki page already says; that duplication is exactly what the cascade design is meant to avoid. - **A document is dense with names/topics and extracting every one would produce dozens of near-duplicate pages** — extract what's clearly named and substantively discussed (not every passing mention), and prefer updating an existing entity page's "Mentioned in" list over creating a marginal new one. Don't force artificial granularity just to maximize page count. - **A document yields no extractable entity beyond itself** — that's fine; its Step 5 document page is the only page it produces. Not every document needs to feed Step 6. - **A source is very large** — cap what gets fully fetched/summarized in one run and explicitly report what was skipped (e.g. "42 of ~300 documents summarized this pass — re-run to continue"). Never silently truncate while implying full coverage. - **Write access but publishing (Step 8) conflicts with a newer version someone else already pushed** — this is why Step 3 (fetch) always runs first, even for write-access users: rebuild on top of the latest fetched state rather than blindly overwriting it. If a real conflict still shows up at publish time, report it rather than force-pushing over it. - **`libs//` has both real content files and a `source.yaml`** — ambiguous and out of scope for this skill to resolve; report it and stop for that folder (this is the same case `ckb-lint`'s external-source config check flags). - **`source.yaml` is missing `connector` or `location`** — report it as malformed and skip that source; don't guess at intent. --- *Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE) at the repository root, or .*