t1k:lib-enroll
| Field | Value |
|---|---|
| Module | t1k-studio-library |
| Version | 2.8.52 |
| Effort | high |
| Tools | Agent, Bash, Edit, Glob, Grep, Read, Skill, Write |
Keywords: add theone-docs topic, bulk enrollment, corpus enrollment, corpus verification, enroll knowledge retrieval, index a library, library enrollment, plan-only
How to invoke
Section titled “How to invoke”/t1k:lib-enrollEnroll a Library in Knowledge Retrieval
Section titled “Enroll a Library in Knowledge Retrieval”Makes a library repo discoverable by the studio corpus. One topic change per repo, but the blast radius is the whole indexer: a bad batch writes rows that other repos’ rows collide with. This skill is PLAN-ONLY — it produces a reviewed plan for the main session to run step by step, never a write itself.
Refusal rules — these BLOCK planning, they do not warn
Section titled “Refusal rules — these BLOCK planning, they do not warn”| # | Condition | Why it blocks |
|---|---|---|
| 1 | No deployed evidence of the indexer paging fix | a pagingFixEvidence {prNumber, mergedSha, deployedListingSnippet} object is required and shape-validated; a bare --facts claim is advisory only and never satisfies this. The snippet must be output from the deployed paged org-repo listing (AIPGDS discovery.ts) showing it pages past the first ~100 repos — a page indicator (pages=N / page=N / per_page) a repo total ≥ 100, or the indexer’s [sync] discovery: N repo(s) with topic '<t>' across <orgs> line. The paging fix is that listing; the sync.ts --check-access per-repo probe never lists, so it can never attest this. Above ~100 repos the unpaged listing silently drops repositories, so an unverified fix produces a corpus that looks complete and is not. Bulk enrollment planning is refused until this evidence is supplied. |
| 2 | Assembly name collides with another repo’s | the store is keyed assembly#member (ON CONFLICT (id)); enrolling overwrites the other repo’s rows. Live today between the two GameFoundation repos. |
| 3 | Repo name not final | the indexer has no rename path; a rename orphans every row. |
| 4 | Engine not supported | read ENGINES from AIPGDS sync.ts via gh api — never hardcoded. An unsupported engine cannot be parsed (Q5). |
| 5 | Doc coverage < 50% (Q10) | a repo whose public members are undocumented enrolls as empty rows. Carve-out: a registry-canonical destination always enrolls — a doc pass follows. |
Preflight emits every blocker at once, with the reason and the fix. It is read-only and, itself, never plans anything — it only decides whether a batch MAY be planned:
bun .claude/skills/t1k-lib-enroll/scripts/t1k-lib-enroll-preflight.cjs --facts facts.json--live refuses outright (exit 2) — it cannot compute nameFinal /
assemblyNames / corpusAssemblies / tokenAccess for real without the
knowledge-retrieval MCP, and refuses rather than hardcoding a pass. Gather
those facts via t1k-lib-steward’s MCP tools and pass them through --facts.
Exit 0 ready (a plan MAY be written), exit 1 blocked, exit 2 usage/refused.
Batch protocol
Section titled “Batch protocol”- Smoke N=3. Three repos, planned as their own plan document.
- Relay the plan and STOP. The main session reviews it and runs the approved steps itself.
- Wait ≥ 1 sync cycle. The indexer is not instant.
- Verify each with
doc_list_indexed_repos --query <repo>— the only repo-scopable check; it returns members/assemblies/status for THIS repo, for unity AND cocos. (doc_searchis a Unity/.NET symbol spot-check only, anddoc_list_assembliescannot be scoped to a repo.) A topic is not evidence; a corpus row is. AskUserQuestion— the main session asks (proceed / investigate / re-smoke / abort) before the next batch is even planned. Sub-agents have noAskUserQuestion; the steward relays the plan and stops.- Batches of 20, verified per batch. Never one plan document of 72.
- Rollback —
remove-topicsis the documented rollback for the repos enrolled in this run; it is never run automatically. See the irreversible caveat below.
Full procedure and the verification queries: references/batch-protocol.md.
Each batch spends REST quota (gh api per repo): run bun <claudeDir>/scripts/gh-budget.cjs --need core=<n> before it, size it from the remaining budget, and stop on exit 3 or 4 (skills/t1k-git/references/github-api-limits.md).
Ordering
Section titled “Ordering”Canonical destinations first, then by consumer count. audit supplies the facts
(t1k-lib-registry). Excluded by decision: per-game *Core/*Base/*Module
repos (Q4), the GDK-org duplicates until the cluster decision (Q9), and the
RN/other-engine libraries until typescript lands (Q5).
Rollback — read this before the first batch
Section titled “Rollback — read this before the first batch”remove-topics, run by hand, reverts the GitHub side, but the indexer has no
deletion path until phase 05.2 deploys its prune. Without it a rollback
leaves stale corpus rows for a repo that no longer claims enrollment, so
add-topics’ rollback is marked rollbackIrreversible: true in the plan
document. references/rollback.md.
Topics are not added at repo-creation time
Section titled “Topics are not added at repo-creation time”t1k-lib-create deliberately does not add topics. Enrollment follows the doc
pass, because a topic on an undocumented repo enrolls an empty corpus entry. The
name must already be final (blocker 3).
Detail
Section titled “Detail”references/preflight.md— each fact, its source, and the fixreferences/batch-protocol.md— smoke → verify → confirm → batchesreferences/rollback.md— the stale-rows caveat and the prune
Executed by
Section titled “Executed by”Runs in t1k-lib-steward (or inline). The preflight script is deterministic; batch and ordering decisions stay reasoning-tier.
| Step | Agent |
|---|---|
Run scripts/t1k-lib-enroll-preflight.cjs --facts facts.json | t1k-lib-steward |