chemenu/instructions/bootstrap.md

type, name, description

type	name	description
types/instruction.md	bootstrap	Prepare a fresh clone for work - create the tools venv and publish the skills into the harness directories, which are generated and not committed.

Bootstrap a fresh clone

.agents/skills/ and .claude/skills/ are generated copies of the skill directories under instructions/, and both are gitignored. A fresh clone therefore has no skills at all until they are published: the agent harness will not offer wiki-ingest, wiki-query, wiki-manage, wiki-lint or wiki-status before this runs.

When to run

• After cloning the repository.
• After instructions/<name>/SKILL.md is added, renamed, or edited.
• Whenever tools/wikitool instructions verify reports a missing or drifted copy.

Steps

1. Create the tool environment (once per clone):

   cd tools
   python3 -m venv .venv
   .venv/bin/pip install -r requirements.txt
   cd ..
   

2. Create the ingest inbox. incoming/ (raw/CONTRACT.md "Getting a file in") is gitignored, so a fresh clone has none of its type subdirectories - unlike raw/ itself, which is committed and present immediately:

   mkdir -p incoming/{articles,documents,notes,assets}
   

   tools/wikitool doctor only reports a missing one; it never creates it, so this is a one-off catch-up here the same way step 5 below is for personalization.

3. Publish the skills:

   tools/wikitool instructions sync
   

4. Verify:

   tools/wikitool instructions verify
   

   Expected: OK. If it reports drift, re-run sync - the source under instructions/ always wins, and a copy is never edited directly.

5. Check for personalization. A clone predating the personalization files has no USER.md/SOUL.md, and tools/wikitool doctor reports personalization: FAIL for it. That is a one-off catch-up, not a bootstrap step that repeats: run only the Personalization step (6) of setup-instance.md, not the whole procedure - this clone already has its git repo, author identity and content. A clone that already carries both files needs nothing here.

6. Offer to record the environment. ENVIRONMENT.md is gitignored, so a fresh clone never has one, and every session in it re-asks which harness is in use, which MCP servers are reachable, and which remote publish talks to. Copy ENVIRONMENT.md.template to ENVIRONMENT.md, fill in what is already known from this clone (git remote -v, the harness you are running in, tools/wikitool instructions list), ask the user for the rest, and drop the wikitool:template-unfilled line.

   Optional, and it stays optional. Skip it and everything still works - doctor reports environment: absent (optional), not a failure. Skip it silently, though, and the next session pays for it again. Never guess an entry: a wrong remote or an MCP server that is not there is worse than the empty section it replaced, because it gets believed.

7. Restart the agent session if it was already running. Harnesses read the skill directories at startup, so skills published mid-session are not picked up.

8. Expect a lingering session-id WARN. A tools/wikitool doctor run at this point reports OK throughout except session-id: WARN - that check is scoped to the working session, not the clone, so a freshly bootstrapped checkout with no WIKITOOL_SESSION_ID exported yet always shows it. This is expected, not a Bootstrap gap: exporting it here would only be true for this one-off setup run, not for whichever session picks up the actual work next, in a new shell after step 7's restart. Run session-setup.md at the start of that session instead.

Scope

This does not apply to anything under kb/, raw/ or reports/; those are committed and present immediately after a clone. If the wiki content looks wrong after cloning, that is a lint question, not a bootstrap one.

This also does not apply to a fresh instance created via tools/wikitool dist export - it has no git history, no author identity, and no generated indexes yet. That is setup-instance.md, a longer procedure this one is a single step of.