@ctxr/skill-llm-wiki 1.0.1

package/guide/history/hidden-git.md

@@ -0,0 +1,130 @@
+---
+id: hidden-git
+type: primary
+depth_role: leaf
+focus: "how Claude leverages the wiki's private git repo for history, blame, diff, and rollback"
+parents:
+  - index.md
+covers:
+  - "every wiki has a private git repo at <wiki>/.llmwiki/git/ with the full isolation env"
+  - "per-phase commits give granular history (snapshot, ingest, draft-frontmatter, ..., commit-finalize)"
+  - "tags: op/<id> marks the finalised operation, pre-op/<id> marks the rollback anchor"
+  - "skill-llm-wiki log/show/diff/blame/reflog/history all pass through to git safely"
+  - "diff --op <id> expands to pre-op/<id>..op/<id> with --find-renames --find-copies"
+  - "history <entry-id> walks op-log.yaml plus git log --follow for a single entry"
+  - "use these tools to answer 'why was this split?', 'when did this break?', 'what changed in op X?'"
+tags:
+  - history
+  - git
+activation:
+  keyword_matches:
+    - history
+    - what changed
+    - previous state
+    - why was this split
+    - diff
+    - log
+    - blame
+    - bisect
+    - reflog
+    - prior op
+    - show
+  tag_matches:
+    - history
+  escalation_from:
+    - build
+    - rebuild
+    - fix
+    - diff
+source:
+  origin: file
+  path: hidden-git.md
+  hash: "sha256:5e1bfab79abdff4dd883cb5ec5107367061feb426774e8b288069e146750666d"
+---
+
+# The hidden git repo is a first-class tool
+
+<!--
+  NOTE on the `bisect` activation keyword: the skill does NOT ship a
+  `skill-llm-wiki bisect` subcommand. The keyword is retained so that
+  a user asking "can I bisect my wiki history?" routes into this leaf,
+  where Claude can explain how to use `log` / `diff` / `history` to
+  achieve the same result, or (if the user is comfortable) how to
+  drive `git bisect` directly against the isolated `<wiki>/.llmwiki/git/`
+  repo with the skill's isolation env exported. Removing the keyword
+  would route such questions nowhere.
+-->
+
+Every skill-managed wiki owns a private git repository at
+`<wiki>/.llmwiki/git/`. It is NOT the user's project git repo — it is
+strictly ours, hosted inside the wiki, reachable only through the
+`scripts/lib/git.mjs` isolation env. Claude should treat it as a
+first-class reasoning tool, not an implementation detail.
+
+## Tag layout
+
+Two namespaces, intentionally split to avoid git ref hierarchy
+collisions:
+
+- `refs/tags/pre-op/<op-id>` — the snapshot taken immediately before
+  the operation started. Rollback anchor. Guaranteed to exist for every
+  op the orchestrator ever ran, including interrupted and failed ones.
+- `refs/tags/op/<op-id>` — the final commit of a successful operation.
+  Absent when the operation failed mid-flight (use the reflog instead).
+- `op/genesis` — the empty initial tree, created on first `gitInit`.
+
+## The subcommands
+
+Every subcommand takes `<wiki>` as its first positional and passes the
+rest through to git under the isolation env.
+
+| Subcommand | Default behaviour | Typical use |
+|------------|-------------------|-------------|
+| `log <wiki>` | `git log --oneline --decorate --all` | "Show me the operation history" |
+| `show <wiki> <ref>` | `git show <ref>` | "What did op X look like?" |
+| `diff <wiki>` | `git diff --find-renames --find-copies` | "What changed since the last commit?" |
+| `diff <wiki> --op <id>` | Expands to `pre-op/<id>..op/<id>` | "What did operation X do?" |
+| `blame <wiki> <path>` | `git blame <path>` | "Who introduced this line?" |
+| `reflog <wiki>` | `git reflog` | "What happened during that crashed build?" |
+| `history <wiki> <entry-id>` | op-log + `git log --follow` | "When was this entry last changed, and why?" |
+
+## Example: answering "why was this entry merged?"
+
+1. `history <wiki> entry-a` — see which ops touched it.
+2. `log <wiki> --follow -- <path/to/entry-a.md>` — see the git commits.
+3. `show <wiki> <commit>` — read the diff of the specific commit.
+4. If the decision came from an operator application (Phase 6 lands
+   this), `<wiki>/.llmwiki/decisions.yaml` records tier/confidence.
+
+## Example: answering "what did the last rebuild do?"
+
+```
+skill-llm-wiki log <wiki> --oneline | head
+skill-llm-wiki diff <wiki> --op <rebuild-op-id> --stat
+```
+
+The first shows the commit graph; the second shows the file-level
+changes with rename detection.
+
+## Rollback
+
+Rollback is a separate subcommand (`skill-llm-wiki rollback <wiki>
+--to <ref>`) that runs `git reset --hard` + `git clean -fd` in the
+private repo. It accepts:
+
+- `genesis` — the original empty tree
+- `<op-id>` — the state right after op X finished
+- `pre-<op-id>` — the state right before op X started
+- `HEAD`, `HEAD~N` — direct git refs
+
+Validation failure already triggers automatic rollback to
+`pre-op/<failed-op-id>`, so manual rollback is for the "I changed my
+mind" case, not the crash-recovery case.
+
+## What the skill never does
+
+- Touch the user's own `.git/`
+- Run any git command outside the isolation env in `scripts/lib/git.mjs`
+- Push, fetch, or otherwise talk to a remote (Phase 7 adds optional
+  remote mirroring under explicit user control)
+- Run hooks — `core.hooksPath=/dev/null` disables every hook source

package/guide/history/index.md

@@ -0,0 +1,52 @@
+---
+id: history
+type: index
+depth_role: subcategory
+depth: 1
+focus: Hidden private git repo backing history, diff, and remote mirroring.
+parents:
+  - "../index.md"
+shared_covers: []
+entries:
+  - id: diff
+    file: diff.md
+    type: primary
+    focus: the diff subcommand — git-style file-level changes for any operation
+    tags:
+      - history
+      - diff
+  - id: hidden-git
+    file: hidden-git.md
+    type: primary
+    focus: "how Claude leverages the wiki's private git repo for history, blame, diff, and rollback"
+    tags:
+      - history
+      - git
+  - id: remote-sync
+    file: remote-sync.md
+    type: primary
+    focus: remote mirroring — sharing the private wiki git history across machines
+    tags:
+      - remote
+      - collaboration
+      - sync
+children: []
+---
+<!-- BEGIN AUTO-GENERATED NAVIGATION -->
+
+# History
+
+**Focus:** Hidden private git repo backing history, diff, and remote mirroring.
+
+## Children
+
+| File | Type | Focus |
+|------|------|-------|
+| [diff.md](diff.md) | 📄 primary | the diff subcommand — git-style file-level changes for any operation |
+| [hidden-git.md](hidden-git.md) | 📄 primary | how Claude leverages the wiki's private git repo for history, blame, diff, and rollback |
+| [remote-sync.md](remote-sync.md) | 📄 primary | remote mirroring — sharing the private wiki git history across machines |
+
+<!-- END AUTO-GENERATED NAVIGATION -->
+
+<!-- BEGIN AUTHORED ORIENTATION -->
+<!-- END AUTHORED ORIENTATION -->

package/guide/history/remote-sync.md

@@ -0,0 +1,113 @@
+---
+id: remote-sync
+type: primary
+depth_role: leaf
+focus: remote mirroring — sharing the private wiki git history across machines
+parents:
+  - index.md
+covers:
+  - "remote add registers a URL in the private repo's config — no fetch, no auth"
+  - sync is the only path that exchanges objects with a remote and is always user-invoked
+  - "push refspec defaults to refs/tags/op/* and refs/tags/pre-op/* — history mirror only"
+  - branch heads are never pushed unless --push-branch is passed explicitly
+  - "--skip-fetch and --skip-push narrow the sync to a single direction"
+  - "regular operations (build, rebuild, fix, join) never auto-push"
+  - the isolation env block applies to remote subprocess calls too
+tags:
+  - remote
+  - collaboration
+  - sync
+activation:
+  keyword_matches:
+    - remote
+    - sync
+    - share
+    - push history
+    - backup
+    - mirror
+    - across machines
+  tag_matches:
+    - remote
+    - collaboration
+  escalation_from:
+    - build
+    - rebuild
+    - diff
+source:
+  origin: file
+  path: remote-sync.md
+  hash: "sha256:521fe2e5863df144746d2397fe1988c6b4769658de066a3e7eee19459abbf88c"
+---
+
+# Remote mirroring
+
+Phase 7 adds a narrow remote-sharing capability so the private wiki
+git history can be mirrored across machines. Two subcommands:
+
+```text
+skill-llm-wiki remote <wiki> add <name> <url>
+skill-llm-wiki remote <wiki> remove <name>
+skill-llm-wiki remote <wiki> list
+
+skill-llm-wiki sync <wiki> [--remote <name>]
+                           [--push-branch <ref>]
+                           [--skip-fetch] [--skip-push]
+```
+
+Both commands run through the same isolation env block as every
+other git operation — the user's `~/.gitconfig`, signing keys,
+hooks, and push templates are NOT consulted. Authentication must
+flow via the URL itself (`https://token@host/...`) or via an
+out-of-band credential helper the user configures explicitly.
+
+## Never auto-push
+
+The skill never pushes to a remote on its own. `remote add` only
+records the URL in the private repo's config — nothing is fetched,
+pushed, or authenticated at registration time. `sync` is the ONLY
+path that exchanges objects with a remote, and it is always a
+user-invoked action. Regular operations (`build`, `rebuild`,
+`fix`, `join`) never trigger a sync.
+
+## Default push is a history mirror
+
+`sync` pushes the refspecs `refs/tags/op/*` and `refs/tags/pre-op/*`
+by default. A shared remote becomes a **read-only history mirror**
+— every op's pre- and final tags are visible for post-mortem
+inspection, but there's no competing `main` branch head that a
+second user could push to and diverge.
+
+If the user genuinely wants a branch pushed (e.g., to share the
+working tree between machines), they pass `--push-branch <name>`
+and the sync adds `refs/heads/<name>` to the refspec list. This is
+an explicit opt-in; the skill never advertises it as normal usage.
+
+## Common sessions
+
+```text
+# First time: register the remote, then push.
+skill-llm-wiki remote ./docs.wiki add origin /srv/wikis/docs.git
+skill-llm-wiki sync ./docs.wiki
+
+# Later: pull history from a teammate's push.
+skill-llm-wiki sync ./docs.wiki --skip-push
+
+# Fetch-only variant that never modifies the remote.
+skill-llm-wiki sync ./docs.wiki --remote teammate --skip-push
+```
+
+## What this does NOT do
+
+- Discover remotes automatically. Every remote is registered
+  explicitly via `remote add`.
+- Prompt for credentials. `GIT_TERMINAL_PROMPT=0` is set at the
+  base-isolation layer; any remote that needs credentials must
+  supply them via URL or an existing git credential helper.
+- Merge divergent histories. `sync` uses tag-only refspecs by
+  default; a tag that already exists on the remote with a
+  different sha is a push rejection, not a silent overwrite. The
+  user fixes it manually.
+- Rewrite history. Force-push is not exposed via the CLI. A user
+  who needs it invokes `git push --force` directly with the
+  explicit `GIT_DIR`/`GIT_WORK_TREE` env vars.
+- Auto-sync on a schedule. Every sync is a conscious action.

package/guide/index.md

@@ -0,0 +1,134 @@
+---
+id: guide
+type: index
+depth_role: category
+depth: 0
+focus: skill-llm-wiki operational reference routed by activation signals
+parents: []
+shared_covers:
+  - "every operation must run the Node.js preflight before invoking scripts/cli.mjs"
+  - every operation is explicit-invocation only and has no automatic triggers
+  - "every operation runs a phase pipeline under the private git at <wiki>/.llmwiki/git/ with per-phase commits and an atomic op/<id> tag at commit-finalize"
+  - "sibling (default) and hosted modes keep the source immutable; in-place mode anchors reversibility on the pre-op/<id> snapshot"
+orientation: |
+  This is a real LLM wiki. Claude routes into it semantically: read each
+  entry's one-line `focus` in `entries[]` below and decide whether the
+  branch is relevant to the current task. No AND-filter and no activation
+  aggregation at this level — parent indices carry only id, file, type,
+  focus, and tags per entry. Descend into relevant branches, stopping at
+  the narrowest leaf whose focus covers the task. Per-leaf `activation`
+  blocks (when present in a loaded leaf) are advisory disambiguation
+  hints, not routing gates. Informational queries with no operation
+  keyword usually activate nothing here and are answered from SKILL.md
+  alone. Note: `bisect` is retained as a hint keyword on the leaf that
+  handles git-history questions, even though there is no
+  `skill-llm-wiki bisect` subcommand — a user asking "can I bisect the
+  wiki history?" should still route there so Claude can explain the
+  `log`/`diff`/`history` path (or drive `git bisect` directly against
+  the private repo).
+
+generator: "skill-llm-wiki/v1"
+rebuild_needed: false
+rebuild_reasons: []
+rebuild_command: "skill-llm-wiki rebuild <wiki> --plan"
+entries:
+  - id: cli
+    file: cli.md
+    type: primary
+    focus: "complete CLI subcommand reference for scripts/cli.mjs"
+    tags:
+      - cli
+      - commands
+      - reference
+  - id: basics
+    file: "basics/index.md"
+    type: index
+    focus: "Core vocabulary, structure rules, and frontmatter/index schema fundamentals."
+  - id: correctness
+    file: "correctness/index.md"
+    type: index
+    focus: Hard invariants, validation, and the safety envelope around every mutation.
+  - id: history
+    file: "history/index.md"
+    type: index
+    focus: Hidden private git repo backing history, diff, and remote mirroring.
+  - id: isolation
+    file: "isolation/index.md"
+    type: index
+    focus: "Coexistence with the user's own git repo and bounded-memory scaling for large corpora."
+  - id: layout
+    file: "layout/index.md"
+    type: index
+    focus: Layout modes, hosted-mode contract, and in-place conversion of source folders.
+  - id: operations
+    file: "operations/index.md"
+    type: index
+    focus: per-operation phase pipelines for Build, Extend, Validate, Rebuild, Fix, and Join
+  - id: substrate
+    file: "substrate/index.md"
+    type: index
+    focus: Decision machinery — rewrite operators and the tiered AI ladder driving them.
+    tags:
+      - operators
+  - id: ux
+    file: "ux/index.md"
+    type: index
+    focus: User-facing intent resolution and preflight failure messaging.
+children:
+  - "basics/index.md"
+  - "correctness/index.md"
+  - "history/index.md"
+  - "isolation/index.md"
+  - "layout/index.md"
+  - "operations/index.md"
+  - "substrate/index.md"
+  - "ux/index.md"
+---
+<!-- BEGIN AUTO-GENERATED NAVIGATION -->
+
+# Guide.wiki
+
+**Focus:** skill-llm-wiki operational reference routed by activation signals
+
+**Shared across all children:**
+
+- every operation must run the Node.js preflight before invoking scripts/cli.mjs
+- every operation is explicit-invocation only and has no automatic triggers
+- every operation runs a phase pipeline under the private git at <wiki>/.llmwiki/git/ with per-phase commits and an atomic op/<id> tag at commit-finalize
+- sibling (default) and hosted modes keep the source immutable; in-place mode anchors reversibility on the pre-op/<id> snapshot
+
+## Children
+
+| File | Type | Focus |
+|------|------|-------|
+| [cli.md](cli.md) | 📄 primary | complete CLI subcommand reference for scripts/cli.mjs |
+| [basics/index.md](basics/index.md) | 📁 index | Core vocabulary, structure rules, and frontmatter/index schema fundamentals. |
+| [correctness/index.md](correctness/index.md) | 📁 index | Hard invariants, validation, and the safety envelope around every mutation. |
+| [history/index.md](history/index.md) | 📁 index | Hidden private git repo backing history, diff, and remote mirroring. |
+| [isolation/index.md](isolation/index.md) | 📁 index | Coexistence with the user's own git repo and bounded-memory scaling for large corpora. |
+| [layout/index.md](layout/index.md) | 📁 index | Layout modes, hosted-mode contract, and in-place conversion of source folders. |
+| [operations/index.md](operations/index.md) | 📁 index | per-operation phase pipelines for Build, Extend, Validate, Rebuild, Fix, and Join |
+| [substrate/index.md](substrate/index.md) | 📁 index | Decision machinery — rewrite operators and the tiered AI ladder driving them. |
+| [ux/index.md](ux/index.md) | 📁 index | User-facing intent resolution and preflight failure messaging. |
+
+<!-- END AUTO-GENERATED NAVIGATION -->
+
+<!-- BEGIN AUTHORED ORIENTATION -->
+This wiki holds the skill-llm-wiki operational reference. It is not meant to
+be read top-to-bottom. It is loaded slice-by-slice by SKILL.md's routing
+table at the skill root — each top-level operation lists the exact set of
+leaves to read for that operation. Do not browse this wiki outside the
+routing discipline; Claude should only open leaves its current operation
+explicitly names.
+
+**Note on `bisect` as a routing keyword.** `guide/hidden-git.md` lists
+`bisect` in its `activation.keyword_matches` block even though the skill
+does **not** ship a `skill-llm-wiki bisect` subcommand. The keyword is
+retained deliberately so that a user asking "can I bisect my wiki
+history?" routes into `hidden-git.md`, where Claude can explain how to
+use `log` / `diff` / `history` to achieve the same result (or, for
+advanced users, how to drive `git bisect` directly against
+`<wiki>/.llmwiki/git/` with the skill's isolation env). Removing the
+keyword would route such questions nowhere. See the inline note at the
+top of `hidden-git.md`'s body.
+<!-- END AUTHORED ORIENTATION -->

package/guide/isolation/coexistence.md

@@ -0,0 +1,134 @@
+---
+id: coexistence
+type: primary
+depth_role: leaf
+focus: "coexistence with the user's own git repository — private git stays isolated"
+parents:
+  - index.md
+covers:
+  - "the skill spawns git only from scripts/lib/git.mjs with a fixed isolation env"
+  - "wiki-local .gitignore hides .llmwiki/ .work/ .shape/history/*/work/ from ancestor user git"
+  - "operations inside a hostile user repo (hooks, signing, custom hooksPath) are unaffected"
+  - "user can still commit wiki content (index.md, leaves, prose) into their own project"
+  - "tests/e2e/git-isolation.test.mjs is the load-bearing proof"
+  - "user's .git HEAD, reflog, and on-disk metadata must be byte-identical after every operation"
+tags:
+  - coexistence
+  - isolation
+  - user-repo
+activation:
+  keyword_matches:
+    - my repo
+    - user repo
+    - gitignore
+    - project git
+    - already in git
+    - my git
+    - inside a git repository
+  tag_matches:
+    - coexistence
+    - layout
+  escalation_from:
+    - build
+    - extend
+    - rebuild
+    - fix
+source:
+  origin: file
+  path: coexistence.md
+  hash: "sha256:a74c6ee019b1c66c446d58c9b93060250db683c01c19eeca9d3254ad447e586e"
+---
+
+# Coexistence with the user's git repository
+
+Users will run this skill against folders that already live inside their own
+git repositories. The skill's private git repo at `<wiki>/.llmwiki/git/` must
+never leak into the user's repo, and the user's repo must never leak into
+ours. Both are invariants enforced at the single `scripts/lib/git.mjs` choke
+point.
+
+## The isolation env
+
+Every git subprocess spawns with a fixed environment block that overrides
+every possible leak surface:
+
+```text
+GIT_DIR              = <wiki>/.llmwiki/git
+GIT_WORK_TREE        = <wiki>
+GIT_CONFIG_NOSYSTEM  = 1                 (ignore /etc/gitconfig)
+GIT_CONFIG_GLOBAL    = /dev/null (or NUL on Windows)
+HOME                 = os.tmpdir()       (ignore ~/.gitconfig hooks/keys)
+GIT_TERMINAL_PROMPT  = 0                 (never prompt for creds)
+GIT_OPTIONAL_LOCKS   = 0                 (don't race background index)
+GIT_AUTHOR_NAME      = skill-llm-wiki
+GIT_AUTHOR_EMAIL     = noreply@skill-llm-wiki.invalid
+GIT_COMMITTER_NAME   = skill-llm-wiki
+GIT_COMMITTER_EMAIL  = noreply@skill-llm-wiki.invalid
+```
+
+Plus these per-invocation `-c` flags on every command:
+
+```text
+commit.gpgsign=false
+tag.gpgsign=false
+core.hooksPath=/dev/null
+core.autocrlf=false
+core.fileMode=false
+core.longpaths=true
+```
+
+These values are set per-subprocess only; `process.env` is never mutated, and
+nothing about the user's shell changes.
+
+## The wiki-local `.gitignore`
+
+On the first operation against any wiki, the skill writes `<wiki>/.gitignore`
+containing:
+
+```gitignore
+# skill-llm-wiki internal metadata — safe to gitignore in your own project
+.llmwiki/
+.work/
+.shape/history/*/work/
+```
+
+This file is itself a normal wiki file — the user can commit it to their own
+git repository. Its purpose is to make any ancestor git repo treat the
+private metadata as ignored without requiring the user to edit their own
+`.gitignore`. `ensureWikiGitignore` is idempotent and will only append
+missing entries to a pre-existing `.gitignore`, never duplicate.
+
+## What the user can commit to their own repo
+
+- Every plain text file the wiki produces (`index.md`, leaves, prose,
+  `.gitignore`). These are normal source files.
+- Not: `.llmwiki/`, `.work/`, `.shape/history/*/work/`. The wiki-local
+  `.gitignore` hides them by default.
+
+## Hostile user config does not break us
+
+The isolation env block neutralises every form of user-side customisation
+we might trip over:
+
+- Pre-commit hooks under `.git/hooks/` or a custom `core.hooksPath` — disabled
+  by `core.hooksPath=/dev/null`.
+- Required signing (`commit.gpgsign`, `tag.gpgsign`, `user.signingkey`) —
+  disabled by our own `-c` flags.
+- Hostile `~/.gitconfig` — ignored by `GIT_CONFIG_GLOBAL=/dev/null` plus
+  `HOME=tmpdir()`.
+- `/etc/gitconfig` — ignored by `GIT_CONFIG_NOSYSTEM=1`.
+
+The load-bearing proof is `tests/e2e/git-isolation.test.mjs`. It runs the
+skill inside three synthetic user repos (plain, hostile-hook + required
+signing, hostile-`HOME`) and asserts after every operation:
+
+- `.git/` is byte-identical
+- `git rev-parse HEAD` is unchanged
+- `git reflog` is unchanged
+- Any sentinel file the hostile hook would write does not exist
+
+## Asking before writing inside a user repo
+
+When the user invokes `build` on a folder that is inside their own git repo
+and has uncommitted changes, the skill refuses (**INT-08**) and asks whether
+to `--accept-dirty`, commit/stash first, or abort. Never guess.

package/guide/isolation/index.md

@@ -0,0 +1,44 @@
+---
+id: isolation
+type: index
+depth_role: subcategory
+depth: 1
+focus: "Coexistence with the user's own git repo and bounded-memory scaling for large corpora."
+parents:
+  - "../index.md"
+shared_covers: []
+entries:
+  - id: coexistence
+    file: coexistence.md
+    type: primary
+    focus: "coexistence with the user's own git repository — private git stays isolated"
+    tags:
+      - coexistence
+      - isolation
+      - user-repo
+  - id: scale
+    file: scale.md
+    type: primary
+    focus: chunked iteration, bounded memory, context-window hygiene, and how the skill handles multi-megabyte corpora
+    tags:
+      - scale
+      - performance
+children: []
+---
+<!-- BEGIN AUTO-GENERATED NAVIGATION -->
+
+# Isolation
+
+**Focus:** Coexistence with the user's own git repo and bounded-memory scaling for large corpora.
+
+## Children
+
+| File | Type | Focus |
+|------|------|-------|
+| [coexistence.md](coexistence.md) | 📄 primary | coexistence with the user's own git repository — private git stays isolated |
+| [scale.md](scale.md) | 📄 primary | chunked iteration, bounded memory, context-window hygiene, and how the skill handles multi-megabyte corpora |
+
+<!-- END AUTO-GENERATED NAVIGATION -->
+
+<!-- BEGIN AUTHORED ORIENTATION -->
+<!-- END AUTHORED ORIENTATION -->