torben/chemenu

1 Fork 0

Files

T

torben a6d07f97c4

CI / verify (push) Successful in 5m19s

Details

CI / pwsh (push) Successful in 1m55s

Details

Release / release (push) Successful in 36s

Details

feat!: installation only from a release, into an empty folder; upstream merge/verify and private-instance.md removed, dist adopt, shell-neutral instructions (#153 )

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

2026-10-01 22:12:09 +02:00

4.5 KiB

Raw Blame History

type, name, description

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

Run the preflight (once per clone, and again after moving it) - see preflight.md. It records the tool paths in .wikitool-tools.json and creates tools/.venv; until it exits 0, tools/wikitool refuses to start:
```
tools/preflight.sh
```
From PowerShell 7 on Windows, run the twin instead - same questions, same file:
```
pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1
```
On exit 42, show its output to the user verbatim and wait.
Publish the skills:
```
tools/wikitool instructions sync
```
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.
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, 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.
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.
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.
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 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, a longer procedure this one is a single step of.

4.5 KiB Raw Blame History

Bootstrap a fresh clone

When to run

Steps

Scope

4.5 KiB

Raw Blame History