chemenu/instructions/private-instance.md

type, name, description

type	name	description
types/instruction.md	private-instance	Set up a private working instance as a clone of a public upstream, so stack updates arrive by merge instead of by copying a tarball over the tree.

Set up a private instance against a public upstream

The distribution path in setup-instance.md builds an instance from a dist export tarball, with no git ancestry in common with the repo it came from. That is the right shape for someone who only ever consumes the stack.

This is the other shape: a private instance that keeps taking stack changes from a public upstream, and whose own content must never travel back. It costs one safeguard to set up and saves the whole update procedure afterwards.

Read this before, not after, the first publish. The gate in step 4 is the thing that makes the arrangement safe, and adding it later means the window it closes was open in between.

Why a clone rather than a tarball

INSTALL.md's "Eine Instanz aktualisieren" is cp -r as an upgrade strategy: copy tools/, types/, instructions/, AGENTS.md, VERSION over the existing tree. It has no three-way merge, so it cannot notice that the receiving instance changed a file, and it has no conflict surface, so nobody learns when upstream and local both touched the same one. It overwrites silently.

A clone gets all of that from git. Stack changes land as real merges, with real conflicts where they conflict.

What a plain git merge does not give you is protection from the upstream's content. The private main deletes the demo corpus once, but that deletion does not make later upstream changes to those paths go away. Measured, not assumed:

Upstream does	git merge upstream/main does
modifies a page you deleted	CONFLICT (modify/delete) - and leaves the upstream version in your working tree. Resolve it with git add -A and the demo page is back.
adds a new page	stages it silently. No conflict, no prompt, no mention.
deletes a page you also deleted	nothing. The only harmless case.

The middle row is the one that matters, because nothing announces it. An upstream that ships a demo corpus and uses it as a test bed will add pages, and each one arrives in your instance and starts showing up in your lint, your index, your search and your confidence decay.

So the merge has to be scoped. That is the procedure below, and it is not optional.

Steps

1. Clone, and name the two remotes for what they are.

   git clone <private-repo-url> my-wiki
   cd my-wiki
   git remote add upstream <public-repo-url>
   

   origin is yours and is the only thing you ever push to. upstream is where stack updates come from and is fetch-only.

2. Make the fetch-only half fetch-only in git, too.

   git remote set-url --push upstream no_push
   

   git refuses to push to a URL it cannot resolve. This is a convenience, not the safeguard - step 4 is the safeguard.

3. Delete the upstream's demo corpus once, on your own main.

   Everything under kb/ and raw/ that came with the clone is the upstream's content, not yours. Remove it with wikitool rm --page (never rm -rf: rm de-links each page from the rest of the wiki, and a plain delete leaves dead wikilinks and broken citations behind), then index rebuild, sources rebuild-index, lint.

   This is a one-time cut. Afterwards the upstream corpus is frozen from your side, which is what makes later merges content-free.

4. Arm the Publish-Remote Gate — before the first publish.

   cat > .wikitool-remotes.json <<'EOF'
   { "schema": 1, "allowed_push_urls": ["<your-private-push-url>"] }
   EOF
   

   Use the URL git remote get-url --push origin prints, exactly. publish refuses with exit 42 for anything else, and there is no flag that opens it - see gates.md.

   The file is gitignored, so it stays with this checkout and never travels to the upstream. wikitool doctor reports whether the gate is armed, and WARNs at more than one remote without it.

5. Take away the write credential, if you can. A token or deploy key for origin only, with no write access to the upstream, is the one control that holds even if everything above is misconfigured. Belt and braces.

6. Personalize and bootstrap. USER.md, SOUL.md and optionally ENVIRONMENT.md are yours and unrelated to the upstream's - see the Personalization step of setup-instance.md, then bootstrap.md for the venv and the skills.

   A clone inherits the upstream's kb/CONVENTIONS.md and kb/*/COLLECTION.md rather than templates, because it inherits the upstream's whole tree. They are yours from this point on: rewrite them if this instance writes its pages differently - the update procedure below restores them on every merge, so the change sticks. kb-profiles.md has the alternatives.

Taking a stack update

tools/wikitool upstream merge --remote upstream --branch main

Take the machinery, never the content. This is the command form of the same idea a hand-rolled merge would need: hold the merge open, force the content stages back to your own state, restore only the paths that are machinery, and only then let it close. Which paths those are is not a short literal list any more (see below) - it is chemenu.ownership.is_stack_owned, the same predicate dist_cmd.py's export reads, so a stack change that adds a new machinery path under a content stage is recognised automatically rather than needing this document edited first.

What counts as machinery under a content stage, for readers who want the shape rather than the code:

Path	Why it takes the upstream side
<stage>/CONTRACT.md (kb/CONTRACT.md, raw/CONTRACT.md, work/CONTRACT.md, reports/CONTRACT.md)	The stack's own stage contract. Every rule in it is enforced by wikitool; an instance never edits it
any *.template under a content stage (kb/CONVENTIONS.md.template, each kb/<name>/COLLECTION.md.template, and any later one)	The template your filled file was adopted from. The filled file is yours; the template is the stack's

Everything else under kb/, raw/, work/ and reports/ is yours, kb/CONVENTIONS.md and each kb/<name>/COLLECTION.md included - they bind your corpus, and they are exactly what upstream merge protects.

Your local, uncommitted-by-design files under those stages survive. Forcing a content stage back to your own state removes only what git tracks, never the directory wholesale - which matters because reports/ is gitignored apart from its contract, so it holds data that is in no commit and cannot be recomputed: the telemetry traces eval score reads, saved eval reports, past lint reports. A merge has no business touching any of it, and does not.

The command itself checks its own result the same way upstream verify would, immediately after committing, and refuses loudly - without rolling the commit back - if anything landed outside a stack-owned path. A refusal there is a bug report, not something to work around by hand; see tools/CONTRACT.md for the full error contract, including what a real conflict in tools//types//instructions/ leaves behind.

Then, as after any stack change: doctor, docs verify, instructions verify, migrate status, lint. A migrate status with outstanding links means the update crossed a compatibility boundary - follow migrate-corpus.md before doing anything else.

Why not just git merge upstream/main? A page the upstream adds arrives with no conflict and no message under a plain merge - measured in the table further up this document. You would find out when lint starts reporting pages you never wrote, if you noticed at all. upstream merge closes exactly that gap: the content stages never see the upstream's version at all.

Checking a merge you resolved by hand instead (or auditing a past one): tools/wikitool upstream verify --since <rev-before> --until <rev-after> runs the same check upstream merge runs on itself, without doing the merge.

Where stack development happens

In the public repo, not here. That is not a preference; the stack is built that way. The development-only half of the instruction layer is pruned from a distribution one-way, with no command that reconstructs it, so an instance built this way has no tool-development mode to switch into in the first place.

When a tool bug blocks real content work here - and it will - file the issue against the public repo (an MCP server or the web UI reaches it from any session; no shared history needed), fix it there where the tests, docs verify and CI's version gate live, and take the fix back with the merge above. Nothing is lost by the detour: the fix has to pass that CI either way.

Decision points

• Merge conflict in kb/, raw/, work/ or reports/? Expected, and already handled: upstream merge overwrites those stages with your own afterwards, so the conflict resolves itself. Never resolve one by hand with git add -A in a merge you are running yourself instead - that is exactly how the upstream version, which git left sitting in your working tree, gets committed into your instance.
• upstream merge exits 1 after committing? Read the message: its own postcheck found content outside a stack-owned path in the commit it just made. The commit is not rolled back - inspect it (git show, or tools/wikitool upstream verify --since <before> --until HEAD) and decide by hand whether to revert it, fix forward, or report it as a stack bug. This should not happen; if it does, chemenu.ownership.is_stack_owned disagreed with itself between the restore and the check, which is exactly what the shared predicate is meant to prevent.
• Conflict in tools/, types/ or instructions/? You changed the stack locally, which step "Where stack development happens" says not to do. upstream merge leaves the merge open rather than guessing - take the upstream side for the named paths and re-file the change as an issue there, or resolve deliberately and finish the commit yourself.
• ...but you changed how your pages are written? That is not a stack change and the rule above does not apply to it. Language, section headings, naming forms, tone, relationship labels and the confidence rubric live in kb/CONVENTIONS.md, and each collection's authoring rules in kb/<name>/COLLECTION.md - all under kb/, all yours, all restored by the merge procedure rather than overwritten by it. If you find yourself editing tools/ or types/ to change an authoring convention, that is a stack bug: file it, because the split exists precisely so you do not have to.

Scope

Not for a first instance with no upstream - that is setup-instance.md. Not for a fresh clone of a repo you already own and develop in - that is bootstrap.md. This is specifically the two-remote case, where the cost of a mistaken push is disclosure rather than inconvenience.