seikaikyo/tgd-wiki-generation

tGD Wiki Generation (Single-File HTML, Multi-Repo)

Overview

Compile the outputs of CodeGraph (.codegraph/codegraph.db) and Understand-Anything (.understand-anything/knowledge-graph.json) for every repo scanned in $TGD_DIR/.scans/ into two coordinated outputs under $TGD_DIR/wiki/:

1. wiki.html — one self-contained HTML file for humans. DeepWiki-style SPA with sidebar navigation, repo switcher, KPI cards, module/flow pages, Mermaid diagrams (renderer inlined), an offline source browser with line anchors, and client-side search. Open it by double-clicking — no server, no build, no node/npm, works offline, and can be shared by sending a single file.

2. docs/ — plain GitHub-flavored Markdown mirroring the same structure, for agents (via manifest.json) and for hosting on GitHub, which renders the Markdown and Mermaid blocks natively.

Design guarantee — uniform structure: every project gets the SAME page skeleton (home → overview / architecture / onboarding / modules / flows / source / search) because the layout lives in the skill's assets/wiki-template.html and the page set is fixed by scripts/generate-wiki.py. Only the data varies. Users have no artifact-side knob that can change the structure; customization means patching the skill's assets.

When to Use

• Invoked manually / on demand to build a project wiki from a knowledge graph that /tgd-map already produced under $TGD_DIR/.scans/. This skill is not wired into the /tgd-map pipeline — run it yourself when you want the wiki.
• Called again to regenerate the wiki after code changes (re-run /tgd-map first to refresh the knowledge graph)

Inputs

Required:

• $TGD_DIR — resolved by /tgd-map Step 0
• $TGD_DIR/.scans/<repo>/.understand-anything/knowledge-graph.json for each repo

Optional:

• $TGD_DIR/.scans/<repo>/.codegraph/ (used if codegraph CLI is available)
• $TGD_DIR/wiki/wiki-prose.json — LLM-authored prose sidecar (see below). Absent or unreadable → the generator derives descriptions from graph structure instead. It never hard-depends on this file, so it still runs standalone, in CI, and offline.
• --primary <slug> (defaults to first scan), --dashboard-url URL, --max-source-lines N (default 1500; caps per-file source embedding)

Outputs

$TGD_DIR/
├── CONTEXT.md                    ← tGD core (untouched)
├── .scans/                       ← tGD core (untouched)
└── wiki/
    ├── wiki.html                 ← THE human-facing wiki: a CURATED overview
    │                               (system/module/flow prose + diagrams + search)
    ├── wiki-prose.json           ← LLM prose sidecar (input; see below)
    └── docs/
        ├── index.md              ← home: repo table
        ├── sources.md            ← source inventory
        ├── manifest.json         ← top-level manifest (all repos)
        └── repos/<slug>/         ← SAME tree for every repo:
            ├── index.md          ← repo home (KPIs, module/flow tables)
            ├── overview.md
            ├── architecture.md   ← Mermaid fenced blocks (GitHub renders)
            ├── onboarding.md
            ├── files.md          ← COMPREHENSIVE index: every source file, explained
            ├── files/*.md        ← one page PER FILE: explanation + symbols + source
            ├── modules/*.md      ← one per architectural layer
            ├── flows/*.md        ← one per tour step
            ├── diagrams/
            │   ├── index.md
            │   ├── architecture.mmd
            │   └── dependencies.mmd
            └── manifest.json     ← per-repo manifest

Division of labor (deliberate): wiki.html is the light, shareable, single-file overview — you open it, land on home, navigate. The docs/ Markdown tree is the complete reference — the files/ sub-tree has one explained page per source file, so "all of the code, explained" lives there (multi-file, GitHub-rendered, scales to any repo size) rather than bloating the single HTML file.

Prose sidecar (wiki-prose.json)

Every page's prose resolves in this precedence: Understand-Anything field → wiki-prose.json → deterministic derivation from graph structure. So a description is never blank: if UA left it empty and no sidecar entry exists, the generator writes a true sentence computed from counts and edges (e.g. "2 files; depends on Data; used by Routes.").

The invoking agent synthesizes the sidecar (read the knowledge graph + source, write explanatory prose) before running the generator. Schema:

{
  "version": 1,
  "repos": {
    "<repo-slug>": {
      "overview": "1-2 paragraph: what this repo does and how the layers fit",
      "architecture": "paragraph: the layering and dominant dependency direction",
      "onboarding": "narrative: where a new engineer should start",
      "layers":  { "<layer-name>": "what this layer is responsible for" },
      "modules": { "<module-slug>": "responsibility prose" },
      "flows":   { "<flow-slug>": "narrative of the sequence" },
      "files": {
        "<file-path>": {
          "summary": "1-2 sentences: what this file is for",
          "hash": "<content-hash>",
          "symbols": { "<symbol-name>": "purpose + gotchas" }
        }
      }
    }
  }
}

Every key is optional — supply what you have, the rest derives. The hash per file lets a re-run skip re-synthesizing unchanged files (incremental). Keep it out of the code repo; it lives under $TGD_DIR/wiki/.

All prose values are Markdown. wiki.html renders them with a small vendored renderer (paragraphs, ##→### headings, bold/italic, inline + fenced code, lists, blockquotes, and links restricted to # anchors and http(s)); the docs/ tree emits them verbatim, where GitHub renders the same Markdown natively. Multi-paragraph prose with subheadings is expected on overview/architecture pages. Per-page content bar: overview 2-4 paragraphs (what it does, how the layers/data-path fit, what to know before touching it); architecture 1-3 paragraphs (the layering and why); onboarding a narrated reading path; layers/modules 2-4 sentences each (responsibility, key files, gotcha); flows narrate the sequence; files a 1-2 sentence summary per source file with public-symbol notes. If a page's prose would read the same for any project, it's filler — ground every claim in the graph or the source you read. Raw HTML in prose is NOT rendered (it is escaped) — the renderer is escape-first by design.

The generator prints a coverage line per repo so the sidecar's effect is never silent — e.g. [tGD] prose: 8 slot(s) authored; 3/12 files summarized; rest derived from graph. A repo key in the sidecar that matches no scanned repo (a typo) is reported as ignored rather than swallowed. If prose was written but the line says "no prose sidecar", the file is in the wrong place or the JSON is malformed.

Entry points:

| Audience | Entry point | Purpose | |---|---|---| | Human | $TGD_DIR/wiki/wiki.html (double-click) | Browse the interactive wiki | | Agent | $TGD_DIR/wiki/docs/manifest.json | Top-level index of every scanned repo | | Agent (per-repo) | $TGD_DIR/wiki/docs/repos/<slug>/manifest.json | Deep dive into one repo | | tGD stages | $TGD_DIR/CONTEXT.md | Top-level summary (unchanged) |

Execution

python3 <SKILL_DIR>/scripts/generate-wiki.py "$TGD_DIR"

<SKILL_DIR> resolves to the directory containing this SKILL.md. One command, ~1 second, hard-fails only when $TGD_DIR or every knowledge graph is missing.

Dependencies

| Tool | Purpose | Required? | |---|---|---| | Python 3.8+ | Run the generator (stdlib only) | Required — already a tGD prerequisite | | codegraph CLI | Symbol-level enrichment | Optional |

There are no other dependencies. The Mermaid renderer is vendored at assets/vendor/mermaid.min.js and inlined into wiki.html at generation time; if the vendored file is ever missing, diagrams degrade to readable Mermaid source text instead of failing.

Regeneration

Re-running the skill on the same $TGD_DIR overwrites wiki.html and docs/ in place. manifest.json is regenerated fresh — do not hand-edit; edits will be lost. Re-running on the same input produces the same structure (timestamps aside).

Related Skills

• tgd-router — Meta-skill entry point
• understand — Upstream: produces the knowledge graph consumed here
• tgd-map — Produces the $TGD_DIR/.scans/<repo>/ knowledge graph this skill reads (this skill is standalone and no longer auto-invoked by it)

Pitfalls

• ❌ Do not write into the code repo. All outputs go under $TGD_DIR/.
• ❌ Do not hand-edit manifest.json or wiki.html — regenerated on every run.
• ❌ Do not add external requests to the template — wiki.html must stay fully offline: no CDN scripts, fonts, or fetches. Everything is inlined.
• ❌ Do not emit raw </script> inside the embedded JSON — the generator escapes </ as <\/; keep that invariant if you touch the embedding code.
• ❌ Unbounded source embedding — huge repos would bloat wiki.html; the --max-source-lines cap (with a visible "truncated" marker) is mandatory.

Common Rationalizations

| Rationalization | Reality | |---|---| | "A static site generator would look nicer." | The template already gives dark mode, Mermaid, search, and a uniform layout — with zero dependencies. An SSG re-adds node/npm, a build step, and version drift for no structural gain. | | "Users should be able to customize the theme." | Uniform layout is the design guarantee. Users who want a custom theme fork the skill and patch assets/wiki-template.html. | | "Embed all source, caps are annoying." | A monorepo with thousands of files would produce a wiki too large to open. Caps with explicit truncation markers keep the single-file promise honest. | | "Skip the Markdown tree, HTML is enough." | Agents consume manifest.json + docs/*.md; GitHub renders them for free. The two outputs share one data model — emitting both is nearly free. |

Red Flags

• Emitting pages that reference nodes not present in the knowledge graph
• Writing anywhere outside $TGD_DIR/ (code repo, $HOME, /tmp beyond scratch)
• wiki.html making any network request when opened
• Generating manifest.json without listing every page written to disk
• Leaving stale files behind on regeneration
• Structure varying between projects — the page set is fixed; only data varies

Verification

After running this skill:

• [ ] $TGD_DIR/wiki/wiki.html exists and opens in a browser with no console errors
• [ ] wiki.html renders: home (repo grid or repo home), overview, architecture with Mermaid SVGs, module pages with symbol tables, source browser with line highlight (?L=<n>), and search returning results
• [ ] $TGD_DIR/wiki/docs/index.md exists (home: repo table)
• [ ] $TGD_DIR/wiki/docs/manifest.json exists with a repos array (one entry per scan) and wikiHtml key
• [ ] For each repo scanned:
  • [ ] docs/repos/<slug>/index.md, overview.md, architecture.md, onboarding.md exist
  • [ ] docs/repos/<slug>/files.md exists and files/ has one page per source file
  • [ ] No description cell is blank — prose came from the sidecar or was derived
  • [ ] docs/repos/<slug>/modules/ contains one page per layer
  • [ ] docs/repos/<slug>/flows/ contains one page per tour step (or is empty if no tour)
  • [ ] docs/repos/<slug>/diagrams/architecture.mmd and dependencies.mmd exist
  • [ ] docs/repos/<slug>/manifest.json exists
• [ ] No files were written outside $TGD_DIR/
• [ ] Re-running the skill on the same input produces the same structure (idempotent)