t1k:wiki

Auto-generated

🔒 Auto-generated from The1Studio/[email protected] — edit the source kit, not this page.

Field	Value
Module	t1k-base
Version	2.17.3
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

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

---

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

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.

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

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)

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

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 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

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

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

• 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/github-wiki-gotchas.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

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

• 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)

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

• 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

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

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. H1 emoji uniqueness per sidebar bucket

Within a sidebar bucket (e.g., ⚙️ Engineering), each page’s H1 emoji MUST be unique to avoid sidebar-glance ambiguity (F4.10).

Recommended swap-emojis when two engineering pages collide:

Emoji	Use for
🧩	Integration / pipeline / “fitting pieces together”
🔌	Wiring / library mapping / dependency injection
🗂️	Organization / taxonomy / catalogs
📦	Packaging / Addressables / build output (check existing usage first)
🏗️	Architecture / structural design
🔧	Tooling / scripts / DevOps

Check existing usage across the bucket before assigning — collision-avoidance is the goal.

G. Required sections for engineering pages

Any page in the Engineering / Architecture sidebar bucket MUST include the following sections. Bake into the page template at add time.

Section	Format	Purpose	Finding refs
Source: attribution	line near top (per §E)	trace to upstream GDD or declare SSOT	F4.9
## Decision Register	table: Decision | Status | Owner | Decided-by date | Reversal cost	record locked design decisions	F5.1, F1.14
## Risk Register	table: ID | Risk | Likelihood | Impact | Mitigation | Owner | Trigger SLA	track production risks	F1.7, F5.2
## Ship Gates / ## Acceptance Criteria	entry-gate + exit-gate checklists	define done	F1.2, F5.3
## Action Items	table: ID | Item | Section ref | Owner | By-date | Status | Issue link	track open work	F5.5
## Implementation Notes with ### Milestone gates	per-release deliverables (v1.0, v1.1, v1.2)	sequence work against shipping	F1.1, F1.2

Justification: every engineering page consumed by a 5-round review will be flagged for missing these. Including them in the scaffold (via t1k:wiki add on engineering-bucket pages) costs nothing and saves 6+ findings per page.

H. Owner placeholder convention — role-based, not name-based

In Decision Registers, Risk Registers, and Action Items, use role-based placeholders — NOT person names — until engineering fills them in one pass.

Canonical role tokens:

Token	Role
<audio-lead>	Audio direction + mixer + FMOD/Wwise call
<tech-art-lead>	Shader contracts, asset prefix scheme, validators
<DOTS-lead>	ECS systems, baking, subscenes (Unity DOTS kit only)
<UI-lead>	uGUI / UI Toolkit / Canvas / DOTS-UI bridge
<infra-lead>	CDN, Addressables hosting, cloud build
<CI-lead>	GitHub Actions, validators, release pipeline
<producer>	Milestone scheduling, playtest coordination, ship gates
<data-lead>	CSV / JSON SSOT, data validators, balance pipeline

Why role-based: wiki authors who guess names risk drift (engineer leaves, role re-assigned, name typo’d). One sweep by the producer/lead replaces every <role> placeholder in one PR. The placeholder is intentionally <bracketed> so a regex sweep finds them all.

Gotchas

• Wiki default branch is master, not main — GitHub provisions every <repo>.wiki.git with master. Hard-coding main in scripts/publish commands will push to a branch the server ignores. The helper auto-detects; if you script anything outside it, use git symbolic-ref refs/remotes/origin/HEAD to resolve.
• Mermaid contrast lives on style lines AND classDef — a validator that only checks style lines misses classDef foo fill:#ccc patterns. The bundled validate-mermaid-contrast.cjs covers both; don’t replace it with a single-regex check.
• Sidebar drift is silent — GitHub renders _Sidebar.md regardless of broken links. Orphan pages (on disk, not in sidebar) are invisible to readers. Always run validate after add.
• Source-repo asset paths fail in wiki — ./data/foo.csv, ../../plans/foo.md, ../../Assets/foo.cs, and ./images/foo.png (when the image lives only in the source repo) all resolve correctly when viewing the markdown on github.com//blob/master/docs/wiki/ but break instantly on publish — validate-wiki-links.cjs rejects them. The wiki is a separate flat git repo with no data/, plans/, or Assets/ subdir. Fix: rewrite to absolute GitHub blob URLs (https://github.com/<owner>/<repo>/blob/<branch>/<path>). Templates in references/wiki-conventions.md → “Linking to non-page assets”. Use absolute URLs from authoring time to avoid bulk-rewriting at publish time.
• Phantom page references — sidebar/page-body links like [X](Domain-Persistence) that point to a target file that was planned but never authored fail validate-wiki-links.cjs as broken internal refs. This is the inverse of orphan drift: orphan = page exists, no nav link; phantom = nav link exists, no page. Fix: either create the target page (a stub with page-type: stub is fine) or remove the link. Common cause: copy-pasting nav blocks across demos and forgetting to delete refs that don’t apply.
• Helper CWD requirement — scripts/wiki-helper.cjs resolves the wiki dir from process.cwd() only. Every bash invocation must run from the project root (where .wiki/ lives) OR with T1K_WIKI_DIR set absolutely. A prior cd into a subdirectory in the same shell breaks detection with [wiki-helper] no wiki clone found. The helper does NOT walk up the tree. If chaining commands, use absolute paths or re-cd to root.
• Image paths are wiki-relative, not repo-relative — ![x](./images/foo.png) only works if images/ exists inside the wiki clone. images/ in the source repo is NOT automatically synced — wiki is a separate repo.
• Anchor links drift when headings change — [See here](#mechanic-registry) breaks when ## Mechanic Registry is renamed. validate-wiki-links.cjs catches this; fix will NOT rewrite anchors automatically (semantic risk).
• update is an affordance, not an action — the skill exposes the file; the AI agent (or user) does the edit. The skill does NOT hand-edit content because wiki content is semantic.
• 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.