torben/chemenu
1
1 Fork 0
Code Issues 35 Pull Requests Actions Packages Releases 37 Activity

feat: INSTALL.md held to the installation instructions - prerequisites lists generated from the manifest, setup questions checked by docs verify (#154)
CI / verify (push) Successful in 5m20s
Details
CI / pwsh (push) Successful in 1m53s
Details
Release / release (push) Successful in 37s
Details

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2

Files changed:
- CHANGES.md
- INSTALL.md
- VERSION
- instructions/dev/doc-pull-through.md
- instructions/dev/stack-close/SKILL.md
- instructions/setup-instance.md
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/cli_contract.py
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/install_doc.py
- tools/chemenu/tests/test_install_doc.py
This commit is contained in:
torben committed 2026-10-02 07:47:39 +02:00
1 parent b33088f64e
commit c77bda2004
12 files changed
+633 -69
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

instructions/setup-instance.md
+37 -35
View File
@@ -102,9 +102,9 @@ one it needs before that.
checked-out branch matches the target branch (default `main`) and refuses otherwise, so that
the wrong branch is never published.
2. **Decision point - identity.** Ask the user for their name and email address; never guess
them, and never quietly carry them over from another repository (that is a different person
and a different project):
2. <!-- setup-question: identity --> **Decision point - identity.** Ask the user for their name and
email address; never guess them, and never quietly carry them over from another repository (that
is a different person and a different project):
```bash
git config user.name "<name>"
@@ -115,9 +115,9 @@ one it needs before that.
resolves `author:` from `$WIKI_AUTHOR` (an override) or else from `git config user.name`, and
aborts with `ERROR` when both are missing - there is no silent placeholder.
3. **Decision point - remote.** An empty clone already has one: show the user `git remote -v`
and confirm that `origin` is where this instance is to be published. Otherwise ask for a
remote URL; a purely local repo is a valid end state:
3. <!-- setup-question: remote --> **Decision point - remote.** An empty clone already has one:
show the user `git remote -v` and confirm that `origin` is where this instance is to be
published. Otherwise ask for a remote URL; a purely local repo is a valid end state:
- Given: `git remote add origin <url>`
- Not given: stay local - then **every** later `tools/wikitool publish` needs a `--no-push`
(which also drops its branch check, see step 1). Without it, `publish` ends with exit 1
@@ -153,10 +153,11 @@ one it needs before that.
`dist upgrade` improves it directly, without the type-spec that links it needing to be
touched. `types/type-spec.md` § "Anatomy of a type" has the shape.
2. Ask the user for the KB language. `kb/CONVENTIONS.md.template` defaults to **English**;
[kb-profiles.md](kb-profiles.md) additionally holds a complete German profile. The
profile catalogue is a **palette, not an enum**: what gets adopted is the text *into* the
instance file, not a reference to the catalogue.
2. <!-- setup-question: kb-language --> Ask the user for the KB language.
`kb/CONVENTIONS.md.template` defaults to **English**; [kb-profiles.md](kb-profiles.md)
additionally holds a complete German profile. The profile catalogue is a **palette, not an
enum**: what gets adopted is the text *into* the instance file, not a reference to the
catalogue.
3. Write `kb/CONVENTIONS.md` from `kb/CONVENTIONS.md.template`, filled in along the chosen
profile - language, section names, naming forms, tone, relationship labels, hedging rule -
@@ -166,13 +167,13 @@ one it needs before that.
4. For a language other than German: delete `german-terminology.md` or replace it with your
own vocabulary - it is material belonging to the German profile, not to the stack.
5. Ask the user about the subject area and derive a `source_type` proposal from it.
[kb-profiles.md](kb-profiles.md) holds two worked domain profiles as illustration. The
proposal is a **starting point, not a commitment** - at setup time the operator has zero
sources and is guessing a taxonomy before having seen a single file, which is the worst
possible moment to pin an enum down. Carrying out the proposal means setting the enum in
`types/source.schema.yaml` **and** the matching `layout:` line per value in
`types/source.md` in the same edit - one without the other leaves a value with no target
5. <!-- setup-question: domain --> Ask the user about the subject area and derive a
`source_type` proposal from it. [kb-profiles.md](kb-profiles.md) holds two worked domain
profiles as illustration. The proposal is a **starting point, not a commitment** - at setup
time the operator has zero sources and is guessing a taxonomy before having seen a single
file, which is the worst possible moment to pin an enum down. Carrying out the proposal means
setting the enum in `types/source.schema.yaml` **and** the matching `layout:` line per value
in `types/source.md` in the same edit - one without the other leaves a value with no target
directory. The visible catch-all (`unclassified`) survives every proposal; it is not a
dumping ground but the slot for a source whose category is not settled yet. Extending the
list later, or emptying that slot: [evolve-subtypes.md](evolve-subtypes.md) - not part of
@@ -207,11 +208,11 @@ one it needs before that.
`docs verify` additionally checks `profile:` and `required_by_stack:` on every
`COLLECTION.md`.
5. **Decision point - personalization.** The release ships `USER.md.template` and
`SOUL.md.template`, but no filled-in versions: who operates this instance and how it sounds
is the property of this instance alone and is never carried over from anywhere else. Both
files are read in **every** session from now on, so they come into being here - not later,
when the occasion arises.
5. <!-- setup-question: personalization --> **Decision point - personalization.** The release ships
`USER.md.template` and `SOUL.md.template`, but no filled-in versions: who operates this instance
and how it sounds is the property of this instance alone and is never carried over from anywhere
else. Both files are read in **every** session from now on, so they come into being here - not
later, when the occasion arises.
Procedure, once each for `USER.md` and `SOUL.md`:
@@ -248,9 +249,9 @@ one it needs before that.
tools/wikitool instructions sync
```
7. **Decision point - record the environment.** The release ships `ENVIRONMENT.md.template`:
harness, published skills, reachable MCP servers, connectors, git remotes, where CI runs.
Constants a session would otherwise ask about every time.
7. <!-- setup-question: environment --> **Decision point - record the environment.** The release
ships `ENVIRONMENT.md.template`: harness, published skills, reachable MCP servers, connectors,
git remotes, where CI runs. Constants a session would otherwise ask about every time.
Unlike step 5, this step is **optional** and not an interview. Whatever can be read off the
checkout itself (`git remote -v`, the running harness, the skills just published) the agent
@@ -262,10 +263,10 @@ one it needs before that.
`environment: absent (optional)` in step 12, not a `FAIL`. The file is gitignored and enters
no commit - it describes this checkout, not the repo.
8. **Decision point - telemetry.** Every instance installed from a release carries a
`.wikitool-release.json` and starts with telemetry **off**; nobody asked for it, and nobody
reads `EVALS.md` before the first file is written anyway. This step only asks whether the
operator wants to reverse that.
8. <!-- setup-question: telemetry --> **Decision point - telemetry.** Every instance installed from
a release carries a `.wikitool-release.json` and starts with telemetry **off**; nobody asked for
it, and nobody reads `EVALS.md` before the first file is written anyway. This step only asks
whether the operator wants to reverse that.
Ask the user once: telemetry on? If yes, create `.wikitool-telemetry.json` in the repo root
(per checkout, gitignored, no `.template` - like `.wikitool-remotes.json`):
@@ -284,12 +285,13 @@ one it needs before that.
never a `FAIL`, since both directions are a valid state. More on this:
[EVALS.md](../EVALS.md) § "Whether it runs at all".
9. **Decision point - task tracker.** The instance ships the `project` type and the collection
its type-spec's `base_dir:` names (`kb/gtd/` here), so committed initiatives have a page from
the start. What they do *not* have until this step is the other half of the weekly review:
the tracker that owns the open items, which `tools/wikitool review` joins those pages against
over the project name. No tracker configured is a legitimate end state - the pages work
alone, `review` simply says so and refuses - so ask rather than assume.
9. <!-- setup-question: task-tracker --> **Decision point - task tracker.** The instance ships the
`project` type and the collection its type-spec's `base_dir:` names (`kb/gtd/` here), so
committed initiatives have a page from the start. What they do *not* have until this step is the
other half of the weekly review: the tracker that owns the open items, which `tools/wikitool
review` joins those pages against over the project name. No tracker configured is a legitimate
end state - the pages work alone, `review` simply says so and refuses - so ask rather than
assume.
Ask the user once: is there a task tracker to connect? If yes, create `.wikitool-tasks.json`
in the repo root (per checkout, no `.template`, **gitignored once it holds a token** - like