wiki-update-library

name

wiki-update-library

description

Update the wiki LIBRARY (the framework — scripts, skills, templates, operating manual) from upstream, leaving your vault/ content and repos.yml untouched. Use when the user runs /wiki-update-library, asks to "update the wiki framework", "pull library updates", "upgrade the wiki", "get the latest scripts/skills", or "update the wiki itself" (NOT the content — that's /wiki-sync). Commits the user's work first, pulls only library paths, handles conflicts, and shows a changelog of what improved.

/wiki-update-library — pull the framework upstream, keep your content

The wiki repo is two halves (see CLAUDE.md §3): the library at the repo root (scripts, skills, templates, the vendored Quartz site builder under site/, Makefile, CLAUDE.md, README.md) and your content under vault/ (plus repos.yml). This skill updates the library only from upstream — your content is never touched, because the deterministic helper (scripts/update-library.sh) only ever checks out library paths.

This skill owns the judgment: confirm before changing anything, protect uncommitted work, explain conflicts in plain language, and end with a beautiful "what's new" report from the changelog. The git plumbing is in scripts/update-library.sh.

Upstream: https://github.com/m98/codebase-wiki (ref main). Override per-run with the env vars UPSTREAM_URL / UPSTREAM_REF. The helper adds a dedicated wiki-upstream git remote — it NEVER touches the user's origin, and it never pushes.

Arguments

• --dry-run — do everything read-only: show what would change, then stop before applying.
• --ref <branch|tag|sha> — update to a specific upstream ref instead of main (sets UPSTREAM_REF).

Hard rules (do not break)

1. Never touch vault/, repos.yml, or .state/. The helper only names library paths; do not hand-run git checkout/merge of anything else.
2. Never push, and never modify the user's origin remote. Update is local; the user decides when to push their own repo.
3. Refuse to apply with a dirty working tree. Get everything committed first (step 2).
4. Confirm before applying (AskUserQuestion) — this overwrites framework files on disk.

Procedure

1. Check upstream is reachable

Run the helper's status (this fetches the dedicated wiki-upstream remote, read-only):

scripts/update-library.sh status

• If it errors with "could not fetch …" the upstream may not be published yet, or there's no network. Tell the user plainly: "Upstream m98/codebase-wiki isn't reachable yet — it may not be published. Nothing was changed." Then stop. Do not retry in a loop.
• On success you get JSON: upstream_sha, local_sha, commits_behind, working_tree_dirty, changed_paths (library paths that differ from upstream).
• If commits_behind is 0 and changed_paths is empty → already up to date. Say so with a ✅ and stop.

2. Protect uncommitted work — commit first

If working_tree_dirty is 1 (or git status --porcelain is non-empty):

• Show the user a short summary of what's uncommitted (git status --short).
• Ask (AskUserQuestion) how to proceed:
  • Commit everything now (recommended) — you stage all and commit with a clear message (ask for / propose one, e.g. chore: snapshot before library update). This keeps their content + any local library tweaks safely versioned, so the update is a clean, revertable diff.
  • Stash it — git stash push -u and restore after (warn: a stash can conflict with incoming library changes; commit is safer).
  • Cancel — stop, change nothing.
• Do not proceed to apply until the tree is clean.

3. Preview what will change

From changed_paths, show the user the library files that will be updated, grouped readably (e.g. "scripts: 4 files", "skills: wiki-sync, wiki-ask", "CLAUDE.md"). If --dry-run, stop here with that preview and the changelog from step 5 (read-only).

4. Confirm, then apply

Ask once (AskUserQuestion): Apply the library update? (Apply / Cancel). On Apply:

scripts/update-library.sh apply

This checks out only library paths from upstream and pins the new version in .library-version. It refuses if the tree is dirty (belt-and-suspenders).

• The skill files update too (including this one). That's fine — the change lands on disk for next time; the currently-running instructions stay in memory for this run.
• If apply reports a problem, surface the exact error. Common causes + fixes:
  • dirty tree → go back to step 2.
  • path missing upstream → harmless; the helper skips paths the upstream ref doesn't have.

5. Commit the update + show "what's new"

• Commit the applied changes so the update is one clean, revertable commit:

  git add -A
  git commit -m "chore: update wiki library to <short-sha>"
  

  (Use the applied_sha from step 4, shortened. End the commit body with the standard Co-Authored-By trailer.)
• Build the report. Show the user, in a nice Markdown block:
  • the version jump: local_sha → applied_sha (short), and commits_behind.
  • What's new from the changelog — the entries added upstream. Get them by diffing CHANGELOG.md across the range, newest first:

    git diff <local_sha>..<applied_sha> -- CHANGELOG.md
    

    Render the added (+) lines as a clean changelog (drop the +). If there is no CHANGELOG.md or no new entries, fall back to a commit log over library paths only:

    git log --oneline <local_sha>..<applied_sha> -- scripts .templates .claude/skills Makefile CLAUDE.md README.md
    

• End with a short, friendly summary: what improved, and a reminder that their vault/ content and repos.yml were untouched, and that pushing their own repo is up to them.

Notes

• First run ever (local_sha empty / no .library-version): treat as "update available", apply normally, and pin the version. The "what's new" will be the full changelog.
• Reverting an update: it's a single commit — git revert <that-commit> or git checkout <prev> -- <library paths>. Mention this if the user is nervous.
• This skill is the counterpart to /wiki-sync (updates content from your repos). They never overlap: sync writes vault/, this writes the library.