---
name: unikit-gd-docs
description: >-
  Render the GAME-DESIGN document (the GDD) into a human-readable form — read-only
  Markdown chapters under docs/design/ (index, systems, flows, content, economy, glossary),
  with facts resolved inline from GD-IDS.yaml and drafts flagged 🚧. Optional --web also
  renders an HTML site from the unikit-docs template (falls back to Markdown-only if the
  template is absent). Use to export or publish the design for people to read, e.g. "render
  the GDD", "export the game design to docs", "generate readable design docs", "publish
  the GDD", "make a design doc site". Read-only — it never edits the GDD or registry, only
  renders it. This renders the game DESIGN — for the project's CODE documentation (README,
  docs/*, modules, architecture) use /unikit-docs.
argument-hint: "[--web]  (renders docs/design/*.md from the GDD workspace; --web also emits HTML)"
allowed-tools:
  - Read
  - Glob
  - Grep
  - Write
  - Edit
  - Bash(mkdir *)
  - Bash(ls *)
  - Bash(date *)
  - AskUserQuestion
disable-model-invocation: false
user-invocable: true
metadata:
  author: unikit
  version: "1.0"
  category: game-design
---

# Game Design — Human-Readable GDD Renderer (workspace → docs/design/)

Render the design workspace (`.unikit/gamedesign/`) into a **human-readable GDD** under
`docs/design/` — the export end of the module, the conceptual mirror of `unikit-gd-recon`:
where recon turns *code → readable design facts*, this turns *design → a readable GDD*.
Both are **read-only at the edge**.

This skill is a **leaf renderer**: it **reads** the GDD (the authored docs + the `GD-IDS`
registry), **resolves the facts inline**, and **writes** only into `docs/design/`. It has
**no `Skill` tool** — it renders, it never authors and never dispatches. The source of
truth stays the workspace; `docs/design/` is a generated, throwaway view (re-render any
time).

## Language Awareness — BLOCKING PRE-REQUISITE

**BEFORE producing ANY output**, silently read `.unikit/system/LANGUAGE_RULES.md` and apply
it (fall back to English if missing). The rendered chapters are **prose for humans** — write
them in the project's artifact language (`gd-principles` → "Language": GDD prose is `ru` by
default). **IDs, keywords, canonical terms, and formulas stay English** verbatim — they are
the registry's vocabulary, never translated. Do not announce the language setting.

## Phase 0 — Bootstrap

Silently load — do not narrate:

1. **`.unikit/system/gamedesign/gd-principles.md`** (the core) — for the **ID conventions**
   (so resolved facts print with correct ids), the facts-registry model, and the one-way
   boundary (this renderer reads design, never code).
2. **`.unikit/gamedesign/GAME.md`** + **`GD-IDS.yaml`** — the render source. **Schema
   guard:** `GD-IDS.yaml` MUST be `version: 2`; on `version: 1` **STOP** with the upgrade
   message (the pre-v2 layout renders differently — do not silently misrender).
3. The per-artifact docs under `.unikit/gamedesign/`: `systems/SYS-*.md`, `flows/FLOW-*.md`,
   `content-types/CT-*.md`. Read each at render time for its prose; take **numbers, ids,
   status, and relationships from `GD-IDS` (the truth)**, not the doc body, when they differ.

**No GDD yet** — if `GAME.md` does not exist, there is nothing to render: **STOP** and route
to `/unikit-gd-spec` (author the master GDD) or `/unikit-gd-recon` (reconstruct one from
code first). Never invent content to fill a chapter.

**One-way boundary:** this skill reads only the design workspace — **never** `.unikit/code/`,
project source, or build artifacts. It is a render of the *design*, not of the code.

## Pipeline — RESOLVE → RENDER → (optional) WEB

### Step 1 — Ensure the output directory

```
Bash: mkdir -p docs/design
```

`docs/design/` is this skill's **owned subtree** (the ownership split with `unikit-docs`,
which owns the non-design `docs/*.md`, is below). Never write a design chapter outside it.

### Step 2 — Resolve the facts

Read `GD-IDS.yaml` once and build the resolution maps the chapters need: `systems` (by
`category`), `flows` (by `mode`), `content_types` (+ their `content` units), `events`,
`resources` / `tracks` / `knobs`, `entities` / `formulas` / `terms`, plus the `depends_on`
/ `belongs_to` / `goals.targets` edges. **Resolve inline** — a chapter prints the actual
name, number, status, and relationship, not a bare id with a "see the registry" pointer (a
reader of `docs/design/` never opens `GD-IDS`). A `deprecated` entry is rendered struck or
under a "Deprecated" subhead, never silently dropped (the registry never deletes).

### Step 3 — Render the chapters (Variant B — by axis)

Write these six Markdown chapters into `docs/design/`. Every chapter opens with a **nav
header** (links to the other chapters) and closes with a **"См. также / See also"** block
(artifact-language label) cross-linking the related chapters. **Drafts are included, never
hidden:** a `not-started` / `skeleton` artifact is rendered with a **🚧 draft banner** so a
reader knows it is provisional — a half-finished GDD honestly shown beats a polished one
that silently omits the unfinished half.

| Chapter | Renders |
|---------|---------|
| `index.md` | The cover: premise/theme, core fantasy, pillars + anti-pillars, loop stack, player needs (SDT), win/lose intent, monetization stance, non-goals, reference games — from `GAME.md`'s authored sections. Plus a **status overview** (counts by `doc_status`) and a **clickable TOC** built from the `## System Map [gen]` / `## Flow Map [gen]` / `## Funnel [gen]` / `## Content Map [gen]` rows, each linking into the chapter below. |
| `systems.md` | **All** systems grouped by `category` (Core / Gameplay / Progression / Economy / UI / Narrative / Meta). Per system: name, tier, `doc_status`, `implemented_version` (if set), `implements` pillars, `depends_on`, and the fantasy + core-rules summary from its `SYS-*.md`. 🚧 on drafts. |
| `flows.md` | **All** flows grouped by wiring `mode` (linear / conditional / emergent). Per flow: the `GOAL` steps + their `targets`, pacing summary, `depends_on` systems, and the **derived "realized"** state (from the depended systems' `implemented_version` — never a written field). 🚧 on drafts. |
| `content.md` | **All** content types. Per type: the typed `CT.fields` schema (name : type, with `ref<>` links resolved to the target's name), the `scale` (`bulk` → count+spec; `curated` → the unit rows), and `belongs_to` system. 🚧 on drafts. |
| `economy.md` | The cross-boundary facts: `resources` (RES, by `kind`), `tracks` (TRACK), `knobs` (KNOB, with current/range), and `formulas` (FORM, with expression + range) — as tables. |
| `glossary.md` | The canonical vocabulary (`terms`: canonical → translation, forbidden aliases) and a **master ID index** (every PIL / SYS / FLOW / CT / CU / RES / TRACK / KNOB / ENT / FORM id → its name + owning doc), so any id seen anywhere resolves. |

### Step 4 — `--web` (optional; default is Markdown-only)

The MVP is Markdown chapters; **`--web` is opt-in**. When `--web` is passed:

1. Read the template at **`{{skills_dir}}/unikit-docs/templates/html-template.html`** (a
   non-`.md` asset, used verbatim — the same template `unikit-docs` renders its site with).
2. **Template missing or unreadable** → skip HTML, keep the Markdown chapters, and emit
   exactly: `WARN [--web] unikit-docs html-template not found; rendered Markdown only.`
   (`/unikit-docs` may not be installed — degrade gracefully, never fail).
3. Template present → render each chapter to `docs/design/<chapter>.html` using the
   template, fix `.md` links to `.html` **within `docs/design/`**, and build a sidebar with
   `class="active"` on the current page. The HTML lands **inside `docs/design/`** (this
   skill's owned subtree) — it never writes into `unikit-docs`'s top-level `docs-html/`.

### Step 5 — Report

List the chapters written (and the `--web` outcome). Note that `docs/design/` is a
generated view — re-run after any authoring change to refresh it. **Do not** offer to edit
the GDD here (route authoring to the owner skills).

**Next steps** (do not auto-invoke):

- 🌐 Render the HTML site — /unikit-gd-docs --web

## Ownership Boundaries

- **Owns:** `docs/design/**` — the rendered design chapters (and their `.html` under
  `--web`). Nothing else.
- **Reads (read-only):** `.unikit/gamedesign/` (`GAME.md`, `GD-IDS.yaml`, systems, flows,
  content types), the gd-principles core, and `unikit-docs`'s html-template (for `--web`).
- **The `docs/` split with `unikit-docs`.** `unikit-docs` owns the **non-design**
  `docs/*.md` (top-level) + `README.md` + `docs-html/`; this skill owns **`docs/design/**`**.
  The two never relink each other's pages: `unikit-docs`'s `--web` glob is top-level
  (`docs/*.md`) and does not descend into `docs/design/`. Keep this boundary — never write a
  non-design page, never touch `README.md` or `docs/*.md`.
- **Never:** edit the GDD or `GD-IDS.yaml` (read-only render); call any skill (no `Skill`
  tool — it is a leaf); read the code workspace or project source; invent content to fill a
  chapter; drop a draft or a `deprecated` entry to look more complete.

## Quick Reference

```
/unikit-gd-docs            → render docs/design/{index,systems,flows,content,economy,glossary}.md from the GDD
/unikit-gd-docs --web      → the same, plus an HTML site from the unikit-docs template (MD-only + WARN if absent)
/unikit-gd-docs  (no GDD)  → STOP → route to /unikit-gd-spec (author) or /unikit-gd-recon (reconstruct from code)
```