wiki-publish

name	wiki-publish
description	Shared GitHub-Wiki publishing substrate: generic `<!--PREFIX:NAME-->` marker stamping and the wiki clone/guard/commit/push plumbing. The common layer beneath /code-readability (doc pages, `cr:` markers) and /code-health (dashboard, `ch:` markers) so neither reimplements it. Use when publishing or stamping wiki pages.

Wiki Publish Skill

The publishing substrate shared by the documentation producers. It owns how content reaches the GitHub Wiki and stays current — not what the content is. Producers generate pages + a facts JSON; this skill stamps and publishes them.

Separation of concerns

Concern	Owner
What to document — TSDoc → Reference pages, team pages, Page-Anatomy	code-readability
What to measure — the CodeHealth roll-up + dashboard facts	code-health
How it's stamped + pushed to the wiki (markers, SSH clone/commit/push, guard)	wiki-publish (this)

The quality-butler agent composes all three in its "document" step: producers write pages + facts, then wiki-publish stamps and pushes them.

The marker convention

Hand-authored prose stays curated; only the facts are regenerated, inside <!--PREFIX:NAME-->…<!--/PREFIX:NAME--> regions. Each producer owns a prefix:

• ch: — CodeHealth (badge, chart, pie, MI counts, hotspots…) — from /code-health
• cr: — code-readability team pages (prereqs, scripts, env, stack)

A new producer just picks a prefix and emits a facts JSON; stamp.mjs is generic.

Scripts

• stamp.mjs <facts.json> <prefix> <file.md>... — fill every <!--prefix:NAME--> region from the facts JSON. Block values (charts/tables/mermaid) are padded onto their own lines. Idempotent. (Generalizes the old stamp-codehealth.mjs and the team-page stamping.)
• wiki-repo.mjs — git plumbing:
  • url <repo> → derive the git@…/<repo>.wiki.git SSH URL
  • clone <wiki-url> <dest> → clone the wiki
  • guard <marker> <page.md>... → fail if a page to be written lacks the marker (i.e. it's hand-authored — never clobber it)
  • push <wiki-dir> "<msg>" → add/commit/push (no-op if clean; clear SSH-auth error)

Publish protocol (what the butler / producers follow)

1. wiki-repo.mjs url → clone the wiki to a scratch dir.
2. Producers write/refresh their pages into it and emit a facts JSON.
3. wiki-repo.mjs guard "<!-- generated by … -->" <pages> before overwriting any generated page — protects hand-authored pages.
4. stamp.mjs <facts.json> <prefix> <pages> to fill the marker regions.
5. (code-readability's linkify-wiki.mjs if wiring source links.)
6. wiki-repo.mjs push <wiki-dir> "<message>".

Don'ts

• Don't put content generation here — that's code-readability / code-health.
• Don't overwrite a page that lacks the generated marker (use guard).
• Don't assume HTTPS/PAT can push a wiki — it's SSH only.

Files

• scripts/stamp.mjs — generic marker stamper
• scripts/wiki-repo.mjs — url / clone / guard / push