Skip to content

t1k:wiki

FieldValue
Modulet1k-base
Version5.15.36
Effortmedium
Tools—

Keywords: beautify wiki, create wiki, diataxis, github wiki, mermaid contrast, publish wiki, sidebar, update wiki, wiki, wiki frontmatter, wiki home, wiki page, wiki sidebar, wiki sync, wiki validate

/t1k:wiki
init|pull|status|list|add|update|validate|fix|beautify|publish|audit

Create, update, and publish GitHub wiki pages with built-in validation. Prevents the recurring classes of wiki breakage: unreadable mermaid text on dark themes, broken internal links, stale sidebars, filenames that drift from the page title, and untracked images.

MANDATORY WORKFLOW — Beautify Is Not Optional

Section titled “MANDATORY WORKFLOW — Beautify Is Not Optional”

Every wiki edit MUST follow this pipeline:

edit page(s) → beautify → validate → publish
^^^^^^^^
REQUIRED STEP

beautify is not a polish step — it is a load-bearing correctness step. Skipping it produces:

  • Invisible readers: missing/out-of-date TOCs, stale breadcrumbs, unaligned tables, mixed-case headings → humans bounce off the page
  • Invisible retrieval: orphan H2 chunks, stale anchors, unlinked related pages → RAG misses the content
  • Invisible contrast bugs: newly added mermaid styles without explicit color: → unreadable on dark theme
  • Silent drift: sidebar/frontmatter/links get out of sync between edits

Rule of thumb: if you wrote or edited a wiki page in this session and did not run beautify before publish, the task is NOT done. publish does NOT auto-beautify — it only validates. Running only validate without beautify first catches errors but does not prevent the drift that causes them in the next session.

When a user asks to “update the wiki”, “add a page”, or “publish wiki changes”, the agent MUST explicitly run beautify in sequence, not skip to publish.

OperationWhat it does
initClone the <repo>.wiki.git sibling to the local path (default .wiki/) and scaffold Home.md + _Sidebar.md if empty
pullgit pull the local wiki clone; report conflicts with uncommitted local edits
statusShow uncommitted diff + unpushed commits in the wiki clone
listList wiki pages grouped by section (from _Sidebar.md)
add <PageName>Create a new page with boilerplate + add to _Sidebar.md
update <PageName>Open-the-file affordance (the agent does the actual edit); auto-runs validate after
validateRun ALL checks: mermaid contrast, wiki links, page names, sidebar sync, images, frontmatter (Diátaxis + RAG), Diátaxis section headers, chunk-size (RAG), prose anti-patterns. Non-zero exit on any FAIL.
fixAuto-apply safe fixes: inject color: into mermaid styles missing it; normalize page filenames; regenerate _Sidebar.md from discovered pages
beautify [--dry-run]MANDATORY after any edit. Full format pass — frontmatter, headings, code fences, callouts, tables, mermaid, TOC, breadcrumbs, links. Structure + visuals for dual AI + human audience. publish does NOT auto-beautify; you must run this explicitly.
publish [-m msg]Run validate → git add -A → commit → push. BLOCKS on validation errors. Run beautify before this — publish validates, it does not beautify.
auditvalidate --verbose — full report even when checks pass

All operations dispatch through scripts/wiki-helper.cjs <op> [args...]. The script auto-detects:

  • The current project’s git remote → wiki URL (<repo>.wiki.git)
  • Local wiki clone path (.wiki/ by default, override with T1K_WIKI_DIR)
  • GitHub default branch for the wiki (usually master for wiki repos)

Every mermaid style X fill:<color> line MUST include an explicit color:#... field. GitHub renders mermaid on both light and dark themes; pale fills without an explicit text color produce unreadable labels on dark theme.

The validator enforces this. The fixer auto-injects color:#0d1117 (GitHub’s primary text color, dark enough to contrast with any pastel fill on either theme) into every style line missing the field. See references/mermaid-guidelines.md for the full color palette and the edge cases (classDef, theme directives, init-block).

Wiki page filenames follow GitHub conventions:

  • Hyphen-separated words: Mechanic-Registry.md, not Mechanic Registry.md or mechanic_registry.md
  • PascalCase per word segment
  • Reserved pages: Home.md, _Sidebar.md, _Footer.md (leading underscore for sidebar/footer)
  • One page per file — do not nest pages in subdirectories (GitHub flattens)

The validator rejects filenames that violate these rules. The fixer renames offenders and updates links across other pages.

_Sidebar.md is a GitHub-wiki-special page that renders as the right-hand nav. The validator compares _Sidebar.md links against the actual page list and reports:

  • Orphan pages (on disk, not in sidebar)
  • Broken sidebar links (in sidebar, no such file)

fix regenerates the sidebar by grouping pages via their section hints in frontmatter (wikiSection: ...) or falling back to alphabetical.

Follow protocol: skills/t1k-cook/references/routing-protocol.md This skill typically runs inline (no agent delegation) because each operation is deterministic. For multi-page rewrites, route to role: t1k-docs-manager.

Every page serves BOTH AI retrieval systems AND human readers. The skill enforces patterns that help both:

  • Diátaxis IA — every page is exactly one of tutorial/how-to/reference/explanation; mixed types break chunk coherence and reader intent.
  • Semantic frontmatter — page-type, summary, audiences, keywords, related let RAG pre-filter before embedding and let sidebar group meaningfully.
  • Self-contained H2 chunks — each section is understandable standalone (no pronoun refs to prior sections, no “as mentioned above”). An H2 retrieved by RAG must carry its own context.
  • RAG-optimal chunk size — H2 sections target 100–800 tokens; too-thin sections merge, too-fat sections split.
  • Visual hierarchy for humans — TOC on pages with ≥6 sections, breadcrumb at top, GFM callouts, aligned tables, language-tagged code fences.
  • Icons for scannability — MANDATORY for sidebar + key headings. Every _Sidebar.md section header MUST lead with a domain emoji. The canonical sidebar style uses <details open><summary>⚔️ <b>Core Mechanics · 3</b></summary> collapsibles — see references/sidebar-style.md for the full spec (10 elements, two structural patterns, status/priority vocabulary, URL encoding, AskUserQuestion decision-flow). Every Home/Index hub page H1 should also lead with an emoji. Page-level H2 callouts (Pillars served, Roadmap, Status, Source attribution) should pair with a consistent icon set. Icons act as visual anchors — readers scan icons before text on long pages, sidebars become navigable at a glance, and AI retrieval gets an extra semantic signal in section headers. Pick one emoji per domain and apply it consistently across sidebar + page H1 + cross-references. Avoid emoji-soup (one icon per heading, not three).

See references/diataxis-guide.md, references/frontmatter-schema.md, and references/anti-patterns.md for the reasoning.

  • references/operations.md — full operation semantics + examples
  • references/wiki-conventions.md — filename, structure, link, frontmatter rules
  • references/diataxis-guide.md — four page types (tutorial/how-to/reference/explanation) with canonical sections
  • references/frontmatter-schema.md — complete field reference for validator + beautifier
  • references/anti-patterns.md — retrieval-harmful patterns the validator flags
  • references/mermaid-guidelines.md — contrast rule, color palette, classDef pattern, init directive
  • references/hard-rules.md — image paths, _Sidebar.md/Home.md specials, anchor drift, TOC behavior, default branch (master not main)
  • references/icon-convention.md — MANDATORY icon rules for sidebar + hub-page H1s + recurring H2 callouts; canonical icon set (~40 emoji) by domain; consistency + anti-patterns
  • references/sidebar-style.md — CANONICAL _Sidebar.md style: <details open> collapsibles + count suffix + status/priority labels + URL encoding + AskUserQuestion decision-flow for proposing styles
  • references/sidebar-example-iconified.md — working iconified _Sidebar.md from a real consumer wiki, with adapt-to-your-project notes; copy-paste-then-edit starter for the icon convention
  • references/engineering-page-conventions.md — engineering-page sections F–H (H1 emoji, required sections, owner placeholders).

Patterns that 5-round adversarial reviews on engineering / architecture wiki pages consistently flag. These are kit-agnostic and apply to every TheOneKit-managed GitHub Wiki — they belong here (t1k-wiki) rather than in a game-specific overlay. Originating evidence: StickManForge plans/reports/asset-pipeline-review/ (2026-05-27, 89 findings across 5 rounds).

Future /t1k:wiki create and /t1k:wiki update operations enforce these; /t1k:wiki review (if added) gates on them.

  • Engineering pages: ≤ 1 GFM callout per 100 lines (averaged across sibling pages in the same sidebar bucket).
  • Keep: > [!WARNING] for real footguns, > [!IMPORTANT] for cross-system contracts, > [!NOTE] for SSOT linkage.
  • Avoid: callouts that duplicate the content of the section immediately below; callouts that restate the H2 directly under them; callouts used as decorative emphasis.
  • Validator note: future /t1k:wiki review may enforce mechanically; for now this is an authoring rule surfaced during beautify.

B. Secondary-stack callout consolidation (appendix pattern)

Section titled “B. Secondary-stack callout consolidation (appendix pattern)”

When a page primarily documents a primary stack (e.g., Unity) but carries inline equivalence callouts for a secondary stack (e.g., Cocos):

  • Threshold: > 3 inline > [!NOTE] <SecondaryStack> equivalent callouts → consolidate.
  • Where: ONE appendix section at the bottom of the page, between ## Tooling and ## Cross-references.
  • Title pattern: ## <SecondaryStack> Equivalents (secondary reference)
  • Lead paragraph: declare the secondary stack is fallback / future option. If a port is greenlit, a sibling <page>-<SecondaryStack>.md page carries the full spec — link to it from here.
  • Body: flat translation table — | Topic (Primary) | <SecondaryStack> equivalent |.
  • Why: 5 inline > [!NOTE] Cocos equivalent callouts in StickManForge-Asset-Pipeline.md made Unity-only readers pause 5× to skip past secondary content (F4.2). Consolidating to one appendix preserves the information without breaking primary-stack flow.

C. MUST capitalization — RFC-2119 discipline

Section titled “C. MUST capitalization — RFC-2119 discipline”
  • Use MUST ONLY for cross-system contracts — shader contracts, validator gates, key-naming contracts, address-stability contracts, anything another team or another binary depends on.
  • DROP MUST for self-contained local rules — use bold-imperative instead.
    • Bad: “Particles MUST be pool-friendly.”
    • Good: “Pool-friendly is required.”
  • Apply consistently within a page — pick one approach page-wide. A page that uses MUST for both a shader contract and a local style preference flattens the signal (F4.6).

D. H3 sub-section naming — uniform within a section

Section titled “D. H3 sub-section naming — uniform within a section”

Within a single H2 section, pick ONE H3 naming pattern and apply it uniformly. Do not mix.

PatternExampleUse when
Bare noun### Textures, ### Materials, ### MeshesSub-sections are parallel categories of the same thing
<thing> <noun>### Asset prefix table, ### Asset import settingsSub-sections describe distinct artifacts about the parent topic

Mixing the two within one parent section (F4.7) breaks scannability. The reviewer flagged ### Asset prefix table next to ### Textures and ### Materials as the canonical violation.

Every Tier-A and Tier-B engineering page MUST carry a Source: line near the top (after the H1, before the first H2). Two forms:

Source: `docs/StickManForge-Technical.md` § "Asset Pipeline"

or, when the wiki page IS the canonical SSOT (no upstream GDD file):

Source: this page IS the SSOT (no upstream GDD file). Consumed by: tech-art, DOTS engineering, content pipeline CI.

The second form (F4.9) prevents the reviewer-fatigue of “where does this canon live?” — answering it inline is cheaper than having every consumer trace it.

F–H. H1 emoji, required sections and owner placeholders

Section titled “F–H. H1 emoji, required sections and owner placeholders”

Sections F–H (sidebar-bucket H1 emoji uniqueness, the required sections table for engineering pages, and role-based owner placeholders) are in references/engineering-page-conventions.md; add bakes the required sections into the scaffold.

  • Never push --force — wikis are collaborative; force-push wipes others’ work. publish uses plain push; if a conflict occurs, the operator must pull + resolve manually.
  • Do not commit secrets — publish scans staged content for sk-*, ghp_*, AKIA*, and env-var assignments. Hits abort the publish with a report.

Runs in t1k-docs-manager (or inline). See § Agent routing: operations are deterministic via scripts/wiki-helper.cjs; multi-page rewrites go to the docs manager.

StepAgent
Run scripts/wiki-helper.cjs <op> and the scripts/beautify-*.cjs passest1k-docs-manager