---
type: types/instruction.md
name: bootstrap
description: 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):

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

2. **Publish the skills:**

   ```bash
   tools/wikitool instructions sync
   ```

3. **Verify:**

   ```bash
   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.

4. **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](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.

5. **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.

6. **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.

7. **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 6's restart. Run [session-setup.md](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](setup-instance.md), a longer procedure this one is a single step of.