/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: init-23description: >-4 Explicit V3 bootstrap for repositories that do not already have valid llmdoc5 knowledge.6metadata:7 source: https://skillmd.com/skills/tokenrollai/init-28---910# /llmdoc:init1112Use this command only when the repository does not already have valid V3 `llmdoc/`.1314Load the `llmdoc` skill before broad exploration. CLI commands below run as `npx -y @tokenroll/llmdoc <cmd>`.1516## Authorization1718An explicit `/llmdoc:init` invocation authorizes this run to:1920- create `llmdoc/`, `.llmdoc-tmp/`, and `llmdoc/meta.json`21- write stable docs only through `recorder`22- write temporary investigation reports under `.llmdoc-tmp/investigations/`2324Stop instead of improvising when:2526- V3 `llmdoc/` already exists: tell the user to run `/llmdoc:update`27- a legacy layout already exists: stop and require the dedicated legacy-migration command2829## Preconditions3031- `git status -- llmdoc/` must be clean before the first formal write.32- Rollback for init means deleting the newly created `llmdoc/` surface (it did not exist before this run); never leave a half-bootstrapped tree behind.33- If `validate` fails after writes, revert the init write-set before reporting failure.3435## Workflow36371. Inventory the repository surface.38 - Before choosing boundaries, read [Knowledge Topology and Context Floor](../llmdoc/references/knowledge-topology.md). Use its domain/topic tests and Context Floor acceptance contract.39 - Read top-level manifests, README files, entrypoints, test surfaces, and release/config files.40 - 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/`.41 - 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`.42432. Build the first V3 knowledge surface with `recorder`.44 - Define topic boundaries before drafting leaf docs.45 - 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.46 - Keep stable knowledge in `llmdoc/` and validity state in `llmdoc/meta.json`.47 - 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.48 - 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.49503. Validate before reporting success.51 - Seed the ledger with `init-state` (writes meta.json with null revisions), then run `validate` and fix all schema, routing, and reference failures.52 - 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.53 - Repair missing or imprecise routes before success. An intended owner must be reached directly; a generic root document alone is not sufficient.54 - 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`.55 - Finalize with `commit --all -m "docs: bootstrap llmdoc"` — it commits the surface, brands fingerprints, and lands the meta follow-up commit in one step.56 - On a validation failure that cannot be repaired in-run, roll back the init write-set.5758## State Invariants5960- Init seeds the baseline only for a successful full bootstrap.61- Per-document fingerprint updates happen only after successful writes and validation.62- A successful bootstrap seeds the initial convergence snapshot with `source: init`; failed, incomplete, and dry-run paths never change it.6364## Result Contract6566- `success`: V3 surface created, validated, and baseline initialized.67- `no_change`: the declared scope was fully checked and no write was needed.68- `dry_run`: investigation or planning completed without writing `llmdoc/`; do not advance state.69- `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.70- `failed`: bootstrap failed and writes were rolled back.7172Always report:7374- whether init ran or was refused75- the investigation report path or paths used76- the topics and stable docs created77- the domain/owner matrix outcome, including concept routes, representative file routes, and intentional no-doc decisions78- the `validate` and `commit` results79- any intentionally reconstructable areas or non-blocking follow-ups; an unresolved first-class gap makes init `incomplete`, not `success`