t1k:wiki
| Field | Value |
|---|---|
| Module | t1k-base |
| Version | 5.15.36 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/t1k:wikiinit|pull|status|list|add|update|validate|fix|beautify|publish|auditTheOneKit Wiki — GitHub Wiki Management
Section titled “TheOneKit Wiki — GitHub Wiki Management”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 STEPbeautify 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.
Operations
Section titled “Operations”| Operation | What it does |
|---|---|
init | Clone the <repo>.wiki.git sibling to the local path (default .wiki/) and scaffold Home.md + _Sidebar.md if empty |
pull | git pull the local wiki clone; report conflicts with uncommitted local edits |
status | Show uncommitted diff + unpushed commits in the wiki clone |
list | List 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 |
validate | Run 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. |
fix | Auto-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. |
audit | validate --verbose — full report even when checks pass |
Entry point
Section titled “Entry point”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 withT1K_WIKI_DIR) - GitHub default branch for the wiki (usually
masterfor wiki repos)
Contrast rule (why this skill exists)
Section titled “Contrast rule (why this skill exists)”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).
Name format
Section titled “Name format”Wiki page filenames follow GitHub conventions:
- Hyphen-separated words:
Mechanic-Registry.md, notMechanic Registry.mdormechanic_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 sync
Section titled “Sidebar sync”_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.
Agent routing
Section titled “Agent routing”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.
Dual-audience principle
Section titled “Dual-audience principle”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,relatedlet 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.mdsection header MUST lead with a domain emoji. The canonical sidebar style uses<details open><summary>⚔️ <b>Core Mechanics · 3</b></summary>collapsibles — seereferences/sidebar-style.mdfor 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
Section titled “References”references/operations.md— full operation semantics + examplesreferences/wiki-conventions.md— filename, structure, link, frontmatter rulesreferences/diataxis-guide.md— four page types (tutorial/how-to/reference/explanation) with canonical sectionsreferences/frontmatter-schema.md— complete field reference for validator + beautifierreferences/anti-patterns.md— retrieval-harmful patterns the validator flagsreferences/mermaid-guidelines.md— contrast rule, color palette, classDef pattern, init directivereferences/hard-rules.md— image paths,_Sidebar.md/Home.mdspecials, anchor drift, TOC behavior, default branch (masternotmain)references/icon-convention.md— MANDATORY icon rules for sidebar + hub-page H1s + recurring H2 callouts; canonical icon set (~40 emoji) by domain; consistency + anti-patternsreferences/sidebar-style.md— CANONICAL_Sidebar.mdstyle:<details open>collapsibles + count suffix + status/priority labels + URL encoding + AskUserQuestion decision-flow for proposing stylesreferences/sidebar-example-iconified.md— working iconified_Sidebar.mdfrom a real consumer wiki, with adapt-to-your-project notes; copy-paste-then-edit starter for the icon conventionreferences/engineering-page-conventions.md— engineering-page sections F–H (H1 emoji, required sections, owner placeholders).
Engineering-Page Conventions (kit-wide)
Section titled “Engineering-Page Conventions (kit-wide)”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.
A. Callout density cap
Section titled “A. Callout density cap”- 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 reviewmay enforce mechanically; for now this is an authoring rule surfaced duringbeautify.
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> equivalentcallouts → consolidate. - Where: ONE appendix section at the bottom of the page, between
## Toolingand## 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>.mdpage carries the full spec — link to it from here. - Body: flat translation table —
| Topic (Primary) | <SecondaryStack> equivalent |. - Why: 5 inline
> [!NOTE] Cocos equivalentcallouts inStickManForge-Asset-Pipeline.mdmade 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
MUSTONLY for cross-system contracts — shader contracts, validator gates, key-naming contracts, address-stability contracts, anything another team or another binary depends on. - DROP
MUSTfor 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
MUSTfor 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.
| Pattern | Example | Use when |
|---|---|---|
| Bare noun | ### Textures, ### Materials, ### Meshes | Sub-sections are parallel categories of the same thing |
<thing> <noun> | ### Asset prefix table, ### Asset import settings | Sub-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.
E. Source: attribution line
Section titled “E. Source: attribution line”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.
Hard rules
Section titled “Hard rules”- Never
push --force— wikis are collaborative; force-push wipes others’ work.publishuses plain push; if a conflict occurs, the operator mustpull+ resolve manually. - Do not commit secrets —
publishscans staged content forsk-*,ghp_*,AKIA*, and env-var assignments. Hits abort the publish with a report.
Executed by
Section titled “Executed by”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.
| Step | Agent |
|---|---|
Run scripts/wiki-helper.cjs <op> and the scripts/beautify-*.cjs passes | t1k-docs-manager |