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. The private main deletes the upstream's demo corpus once; every later git merge upstream/main sees deleted-in-ours, unmodified-in-theirs and resolves without asking. Stack changes land as real merges, with real conflicts where they conflict.

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.

Taking a stack update

git fetch upstream
git merge upstream/main

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.

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/ or raw/? Something changed the upstream's corpus after you cut it. Resolve as "keep deleted" - your instance's content is yours, and the upstream's demo corpus has no business in it.
• Conflict in tools/, types/ or instructions/? You changed the stack locally, which step "Where stack development happens" says not to do. Take the upstream side and re-file the change as an issue there.

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.