torben
a6d07f97c4
Files changed: - .gitea/workflows/ci.yml - .gitea/workflows/release.yml - AGENTS.md - CHANGES.md - DEVELOPMENT.md - EVALS.md - INSTALL.md - README.md - VERSION - docs/ownership-and-templates.md - instructions/CONTRACT.md - instructions/bootstrap.md - instructions/dev/dev-setup.md - instructions/dev/stack-dev/SKILL.md - instructions/gates.md - instructions/ingest-large-tree.md - instructions/kb-profiles.md - instructions/mcp-read-server.md - instructions/migrations/3.0.0-authoring-conventions.md - instructions/preflight.md - instructions/private-instance.md - instructions/session-setup.md - instructions/setup-instance.md - instructions/upgrade-instance.md - tools/CONTRACT.md - tools/README.md - tools/chemenu/cli.py - tools/chemenu/cli_contract.py - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/git_publish.py - tools/chemenu/commands/upstream_cmd.py - tools/chemenu/commands/work_cmd.py - tools/chemenu/config.py - tools/chemenu/ownership.py - tools/chemenu/tests/test_cli.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_instructions_shell.py - tools/chemenu/tests/test_preflight.py - tools/chemenu/tests/test_preflight_pwsh.py - tools/chemenu/tests/test_run_budget.py - tools/chemenu/tests/test_upstream_cmd.py - tools/chemenu/toc.py - tools/preflight.ps1 - tools/preflight.sh
96 lines
4.5 KiB
Markdown
96 lines
4.5 KiB
Markdown
---
|
|
type: types/instruction.md
|
|
name: bootstrap
|
|
description: Prepare a fresh clone of an existing instance (a second machine, a new checkout) for work - run the preflight (tool paths and the tools venv) and publish the skills into the harness directories, which are generated and not committed.
|
|
---
|
|
|
|
# Bootstrap a fresh clone
|
|
|
|
An instance lives in its own git repository, so a second machine - or a new checkout on the same
|
|
one - gets it with `git clone`. What the clone does not carry is everything that describes one
|
|
machine rather than the instance: the tool paths and the tools venv, and the published skills.
|
|
|
|
`.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`, `wiki-status` or `gtd-weekly-review` before this runs.
|
|
|
|
## When to run
|
|
|
|
- After cloning the instance's repository.
|
|
- After `instructions/<name>/SKILL.md` is added, renamed, or edited.
|
|
- Whenever `tools/wikitool instructions verify` reports a missing or drifted copy.
|
|
|
|
## Steps
|
|
|
|
1. **Run the preflight** (once per clone, and again after moving it) - see
|
|
[preflight.md](preflight.md). It records the tool paths in `.wikitool-tools.json` and
|
|
creates `tools/.venv`; until it exits 0, `tools/wikitool` refuses to start:
|
|
|
|
```bash
|
|
tools/preflight.sh
|
|
```
|
|
|
|
From PowerShell 7 on Windows, run the twin instead - same questions, same file:
|
|
|
|
```powershell
|
|
pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1
|
|
```
|
|
|
|
On exit 42, show its output to the user verbatim and wait.
|
|
|
|
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 (5) 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 new instance installed from a release - 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.
|