/llmdoc:init
Use this command only when the repository does not already have valid V3 llmdoc/.
Load the llmdoc skill before broad exploration. CLI commands below run as npx -y @tokenroll/llmdoc <cmd>.
Authorization
An explicit /llmdoc:init invocation authorizes this run to:
- create
llmdoc/, .llmdoc-tmp/, and llmdoc/meta.json
- write stable docs only through
recorder
- write temporary investigation reports under
.llmdoc-tmp/investigations/
Stop instead of improvising when:
- V3
llmdoc/ already exists: tell the user to run /llmdoc:update
- a legacy layout already exists: stop and require the dedicated legacy-migration command
Preconditions
git status -- llmdoc/ must be clean before the first formal write.
- Rollback for init means deleting the newly created
llmdoc/ surface (it did not exist before this run); never leave a half-bootstrapped tree behind.
- If
validate fails after writes, revert the init write-set before reporting failure.
Workflow
Inventory the repository surface.
- Before choosing boundaries, read Knowledge Topology and Context Floor. Use its domain/topic tests and Context Floor acceptance contract.
- Read top-level manifests, README files, entrypoints, test surfaces, and release/config files.
- Use one or more
investigator subagents for complementary evidence scopes when the repository is large enough to benefit; keep their write ownership in .llmdoc-tmp/.
- Build the reference's scratch domain/owner matrix. Give every first-class subsystem an expected owner document or an explicit no-doc reason; resolve conflicting evidence before handing the result to
recorder.
Build the first V3 knowledge surface with recorder.
- Define topic boundaries before drafting leaf docs.
- Prefer the smallest sufficient set of high-value owner docs over broad shallow inventory. Depth never excuses a first-class subsystem with neither an owner nor an intentional no-doc decision.
- Keep stable knowledge in
llmdoc/ and validity state in llmdoc/meta.json.
- Create root singleton docs only for genuinely cross-topic contracts; otherwise create only the necessary one-level topic directories. Topics are plain directories with no
index.mdx entry node.
- If the user wants non-default SessionStart guidance or deliberate document preload, read Startup Configuration and create
llmdoc.config.json; otherwise do not add optional startup config during bootstrap.
Validate before reporting success.
- Seed the ledger with
init-state (writes meta.json with null revisions), then run validate and fix all schema, routing, and reference failures.
- Treat
validate as structural only. After it passes, run the reference's Context Floor acceptance: natural-query searches, per-boundary context --files probes, broad-glob precision probes, and tree --docs plus index/context relation review.
- Repair missing or imprecise routes before success. An intended owner must be reached directly; a generic root document alone is not sufficient.
- Docs added after
init-state already seeded the ledger get their entries via adopt <path...>; never hand-edit meta.json or recreate existing files through new.
- Finalize with
commit --all -m "docs: bootstrap llmdoc" — it commits the surface, brands fingerprints, and lands the meta follow-up commit in one step.
- On a validation failure that cannot be repaired in-run, roll back the init write-set.
State Invariants
- Init seeds the baseline only for a successful full bootstrap.
- Per-document fingerprint updates happen only after successful writes and validation.
- A successful bootstrap seeds the initial convergence snapshot with
source: init; failed, incomplete, and dry-run paths never change it.
Result Contract
success: V3 surface created, validated, and baseline initialized.
no_change: the declared scope was fully checked and no write was needed.
dry_run: investigation or planning completed without writing llmdoc/; do not advance state.
incomplete: init was refused (valid V3 already exists, legacy migration is required) or evidence/user input was insufficient; roll back writes and do not advance state.
failed: bootstrap failed and writes were rolled back.
Always report:
- whether init ran or was refused
- the investigation report path or paths used
- the topics and stable docs created
- the domain/owner matrix outcome, including concept routes, representative file routes, and intentional no-doc decisions
- the
validate and commit results
- any intentionally reconstructable areas or non-blocking follow-ups; an unresolved first-class gap makes init
incomplete, not success
1---2name: init3description: "Explicit V3 bootstrap for repositories that do not already have valid llmdoc knowledge."4metadata:5 source: https://skillmd.com/skills/tokenrollai/init6---78# /llmdoc:init910Use this command only when the repository does not already have valid V3 `llmdoc/`.1112Load the `llmdoc` skill before broad exploration. CLI commands below run as `npx -y @tokenroll/llmdoc <cmd>`.1314## Authorization1516An explicit `/llmdoc:init` invocation authorizes this run to:1718- create `llmdoc/`, `.llmdoc-tmp/`, and `llmdoc/meta.json`19- write stable docs only through `recorder`20- write temporary investigation reports under `.llmdoc-tmp/investigations/`2122Stop instead of improvising when:2324- V3 `llmdoc/` already exists: tell the user to run `/llmdoc:update`25- a legacy layout already exists: stop and require the dedicated legacy-migration command2627## Preconditions2829- `git status -- llmdoc/` must be clean before the first formal write.30- Rollback for init means deleting the newly created `llmdoc/` surface (it did not exist before this run); never leave a half-bootstrapped tree behind.31- If `validate` fails after writes, revert the init write-set before reporting failure.3233## Workflow34351. Inventory the repository surface.36 - Before choosing boundaries, read [Knowledge Topology and Context Floor](../llmdoc/references/knowledge-topology.md). Use its domain/topic tests and Context Floor acceptance contract.37 - Read top-level manifests, README files, entrypoints, test surfaces, and release/config files.38 - Use one or more `investigator` subagents for complementary evidence scopes when the repository is large enough to benefit; keep their write ownership in `.llmdoc-tmp/`.39 - Build the reference's scratch domain/owner matrix. Give every first-class subsystem an expected owner document or an explicit no-doc reason; resolve conflicting evidence before handing the result to `recorder`.40412. Build the first V3 knowledge surface with `recorder`.42 - Define topic boundaries before drafting leaf docs.43 - Prefer the smallest sufficient set of high-value owner docs over broad shallow inventory. Depth never excuses a first-class subsystem with neither an owner nor an intentional no-doc decision.44 - Keep stable knowledge in `llmdoc/` and validity state in `llmdoc/meta.json`.45 - Create root singleton docs only for genuinely cross-topic contracts; otherwise create only the necessary one-level topic directories. Topics are plain directories with no `index.mdx` entry node.46 - If the user wants non-default SessionStart guidance or deliberate document preload, read [Startup Configuration](../llmdoc/references/startup-config.md) and create `llmdoc.config.json`; otherwise do not add optional startup config during bootstrap.47483. Validate before reporting success.49 - Seed the ledger with `init-state` (writes meta.json with null revisions), then run `validate` and fix all schema, routing, and reference failures.50 - Treat `validate` as structural only. After it passes, run the reference's Context Floor acceptance: natural-query searches, per-boundary `context --files` probes, broad-glob precision probes, and `tree --docs` plus `index`/`context` relation review.51 - Repair missing or imprecise routes before success. An intended owner must be reached directly; a generic root document alone is not sufficient.52 - Docs added after `init-state` already seeded the ledger get their entries via `adopt <path...>`; never hand-edit `meta.json` or recreate existing files through `new`.53 - Finalize with `commit --all -m "docs: bootstrap llmdoc"` — it commits the surface, brands fingerprints, and lands the meta follow-up commit in one step.54 - On a validation failure that cannot be repaired in-run, roll back the init write-set.5556## State Invariants5758- Init seeds the baseline only for a successful full bootstrap.59- Per-document fingerprint updates happen only after successful writes and validation.60- A successful bootstrap seeds the initial convergence snapshot with `source: init`; failed, incomplete, and dry-run paths never change it.6162## Result Contract6364- `success`: V3 surface created, validated, and baseline initialized.65- `no_change`: the declared scope was fully checked and no write was needed.66- `dry_run`: investigation or planning completed without writing `llmdoc/`; do not advance state.67- `incomplete`: init was refused (valid V3 already exists, legacy migration is required) or evidence/user input was insufficient; roll back writes and do not advance state.68- `failed`: bootstrap failed and writes were rolled back.6970Always report:7172- whether init ran or was refused73- the investigation report path or paths used74- the topics and stable docs created75- the domain/owner matrix outcome, including concept routes, representative file routes, and intentional no-doc decisions76- the `validate` and `commit` results77- any intentionally reconstructable areas or non-blocking follow-ups; an unresolved first-class gap makes init `incomplete`, not `success`