player-docs

name	player-docs
description	Generates and refreshes docs/player/ — sixteen self-contained HTML pages that project the code-grounded wiki (docs/wiki/), README.md, docs/llm-providers.md, and (for the curriculum-ladder quickstarts) the spec 046 spec/contracts into plain-language documentation for players (non-engineers). Runs standalone; the recommended follow-on after /grounding-wiki:wiki-update re-pins wiki notes. Check freshness first: node .claude/skills/player-docs/scripts/check-freshness.mjs --check
metadata	{"author":"promptworld"}
user-invocable	true
disable-model-invocation	false

player-docs

Regenerates docs/player/ — the player-facing (non-engineer) HTML documentation set — from the grounded corpus: docs/wiki/ notes, README.md, and docs/llm-providers.md. Distinct from docs/wiki/ (developer-grounded) and docs/course/ (interactive codebase course). This skill is standalone: nothing else invokes it, and it invokes nothing else — the human loop is "after wiki-update re-pins notes, run player-docs".

When to run this

Run after /grounding-wiki:wiki-update re-pins any wiki note. More generally, run it any time you want to know whether the player docs are current, or to bring them current when they aren't.

Procedure (check-first, mandatory order)

This is a check-first regeneration procedure. Never open a page for writing before the check has run and named it stale or missing.

1. Run the check.

   node .claude/skills/player-docs/scripts/check-freshness.mjs --check
   

   • Exit 0 → every page is fresh. Stop here. Do not open, touch, or rewrite any file under docs/player/. This is the no-op path — regenerating when nothing is stale must change nothing (byte-identical no-op).
   • Exit 1 → at least one page is stale, missing, or broken-ref. Continue to step 2.
   • Exit 2 → usage/environment error (not a git repo, docs/player unreadable, bad flag). Fix the environment, not the pages, and re-run step 1.

2. For each stale or missing page ONLY (leave every fresh page untouched — do not open it, do not re-save it even byte-identically): a. Re-read the page's declared sources (see the mapping table below) at their current pins — wiki notes at their current verified_against: frontmatter value, README.md/docs/llm-providers.md at git log -1 --format=%H -- <path>. b. Rewrite the page's prose as a plain-language projection of those sources — no independently asserted facts, nothing a player would need engineering vocabulary to parse. Preserve the page's slug, its links (to index.html and, for index.html, to every topic page), and the shared CSS block below. c. Update every promptworld-docs:source meta tag to the source's current pin. Add a tag for any newly-drawn-on source; remove one for a source no longer used. index.html never carries source tags — nav only, no factual claims.

3. Re-run the check. It must exit 0. If it doesn't, the regeneration is incomplete — go back to step 2 for whatever it still reports. Fresh pages from before this run must be byte-identical to what they were (nothing legitimately touched them).

The expected page set

index.html (nav hub, no sources) plus fifteen topic pages:

• getting-started.html
• playing-via-metatron.html
• time-and-speed.html
• reading-the-story.html
• the-ai-behind-the-village.html
• llm-setup-basics.html
• understanding-the-screen.html
• keys-reference.html
• stage-1-the-voice.html
• stage-2-the-written-word.html
• stage-3-the-craft.html
• stage-4-the-stewardship.html
• command-reference.html
• world-files-reference.html
• troubleshooting.html

Page → source mapping

The starting, editorial contract (research.md D5). If a page genuinely draws on a source not listed here, add it — and add the matching meta tag in the same change.

Page	Sources
index.html	none (nav only)
getting-started.html	README.md, docs/wiki/cli-promptworld.md, docs/wiki/daemon-lifecycle.md, docs/wiki/tui-client.md, docs/wiki/llm-provider-health.md, docs/wiki/chronicle.md, docs/wiki/morgue.md, docs/wiki/gru.md, docs/wiki/curriculum-ladder.md, docs/wiki/takeover-surfaces.md, docs/wiki/grounded-feedback.md, docs/wiki/village-lens.md, docs/wiki/skin.md
playing-via-metatron.html	docs/wiki/guardian.md, docs/wiki/guardian-faith.md, docs/wiki/bundle-tools.md, docs/wiki/guardian-miracles.md, docs/wiki/guardian-miracle-mechanics.md, docs/wiki/guardian-orders.md, docs/wiki/guardian-missions.md, docs/wiki/curriculum-ladder.md, docs/wiki/governance.md, docs/wiki/tui-client.md, docs/wiki/grounded-feedback.md, docs/wiki/takeover-surfaces.md
time-and-speed.html	docs/wiki/game-clock.md, docs/wiki/sim-loop.md, docs/wiki/cli-promptworld.md
reading-the-story.html	docs/wiki/chronicle.md, docs/wiki/tui-client.md, docs/wiki/event-log.md
the-ai-behind-the-village.html	docs/wiki/agent-mind.md, docs/wiki/cognition.md, docs/wiki/llm-orchestrator.md, docs/wiki/nightly-consolidation.md, docs/wiki/social-fabric.md
llm-setup-basics.html	docs/llm-providers.md, docs/wiki/llm-orchestrator.md,

llm-setup-basics.html stays at "get it working" depth (the minimum llm.json a non-engineer needs) and defers registry-reference/migration depth to docs/llm-providers.md by link/mention rather than duplicating it.

understanding-the-screen.html (NetHack chapter-3-shaped: the player's question as the heading, organized by screen region, a complete map glyph table prefaced with reassurance) and keys-reference.html (pure controls, unmixed with lore — the Analog Game Studies reference-card pattern) are a paired addition (TASK-114): the first explains what's on screen, the second is purely which key does what: they cross-link each other rather than duplicating content. keys-reference.html sources a non-docs/wiki/ design doc — its source pin is a plain-file git log pin (same mechanism as README.md/docs/llm-providers.md), not a verified_against frontmatter pin.

The four stage-N-*.html quickstarts (spec 046, TASK-68) are a quartet addition: one page per curriculum-ladder stage, projecting what each stage teaches, grants, and requires to unlock the next — cross-linked to each other in ladder order and to promptworld stages/new --stage in prose. They draw on specs/ files rather than docs/wiki/ notes (the spec is the source of truth for the ladder's client-approved names/table), so — the keys-reference.html precedent above — their source pins are plain-file git log pins, not verified_against frontmatter pins.

command-reference.html, world-files-reference.html, and troubleshooting.html (spec 108, TASK-182) are a reference trio, distinct in kind from every page above: where the teaching pages narrate a first session, these three are pure lookup — tables and terse symptom rows, cross-linked to each other and to the teaching pages they complement (command-reference ↔ getting-started; world-files-reference ↔ llm-setup-basics; troubleshooting ↔ the-ai-behind-the-village and time-and-speed), never the reverse — the teaching pages stay byte-identical, this addition is additive nav only (index.html's Reference section). Reference density (tables, terse rows) is licensed here in a way it isn't on the teaching pages, but the vocabulary rule doesn't relax: plain language for a non-engineer throughout, no identifier or package path, only what the player types or opens. world-files-reference.html follows the standing llm-setup-basics.html precedent (D4): it states what llm.json/bundles/ are and what a player touches, then defers registry-reference and bundle-authoring depth to docs/llm-providers.md/docs/bundles.md by link rather than duplicating that depth here — a future regeneration keeps deferring rather than absorbing that content inline. troubleshooting.html's rows never name a diagnostic surface that isn't real and observable in a declared source (a promptworld status field, a ps STATE value, a daemon-log WARNING line, a TUI badge) — a future regeneration that can no longer ground a row's "what to check" step drops or rewrites that row rather than keeping an invented one. command-reference.html documents metatron/miracle as retired-but-working aliases for guardian/work (spec 052 FR-008) without un-hiding them from the built-in usage text — a future regeneration keeps naming them, since a player can still meet one in an old script.

getting-started.html carries a first-prompt step (spec 079, TASK-153): a numbered "Ask your guardian one thing" section, positioned after the watch-it-live step and before the stopping step, whose sample ask is a byte-verbatim value from the skin.guardian.example_ask.* family as documented in docs/wiki/skin.md (the declared source — never quote internal/skin/skin.go directly, and never paraphrase: a paraphrase is an independently asserted fact and does not survive regeneration), with the verb held to the pinned stage-1 tool ceiling (send_vision, send_omen, monitor_and_act, cancel_order — specs/046-curriculum-ladder/contracts/stage-gating.md; recommended exemplar: send_vision → "show Ash a vision of the fire dying"). The step must say what to expect back (the guardian replies or acts; the charge line above the message box is where the cost shows), must work on any world with no --scenario needed, must name the in-game ? overlay's guardian section as the live, per-world list of one example ask per granted verb, and must carry the skin honesty note: the phrasing printed on the page is the default Guardian skin's, a custom skin re-voices it, and the ? overlay always shows the world's own. A future regeneration reproduces this step rather than reverting to a watch-only walkthrough.

Each stage-N-*.html page (spec 079, TASK-153) opens with a short "Your first session" do-this-then-this block (3-5 ordered steps) — create a world at that stage with no --scenario, the stage-appropriate first acts, then a when-you're-ready pointer to that stage's exercise (stage-4 states plainly that no exercise gates the stage itself — an ambient stage-4 world is unscored by design, per its own declared spec.md row, even though optional stage-4 scenario worlds exist per spec 077). Every claim in a block projects from that page's already-declared sources above — no stage page gains or loses a source tag for this addition. Only stage-1's block links to getting-started.html's first-prompt step for the ask itself; a future regeneration reproduces every stage page's block rather than dropping back to a grants-only description.

Provenance meta-tag format

Contract: specs/026-player-docs/contracts/provenance-and-check.md. In every page's <head>, each tag on its own line (line-oriented parsing depends on this):

<meta name="promptworld-docs:generated-by" content="player-docs">
<meta name="promptworld-docs:source" content="docs/wiki/metatron.md@8ada1050cc5b108790d0e48640dba0b985632e25">
<meta name="promptworld-docs:source" content="README.md@8fa82e1a4deefb4f7d3923b334ef85f25cf2c298">

• generated-by is required on every page, including index.html.
• source is required on every topic page (one or more); forbidden (absent) on index.html.
• content grammar: <repo-relative-path>@<40-hex-lowercase-commit>.

Canonical page skeleton + shared CSS

Every page inlines this exact <style> block (system font stack, ~70ch measure, CSS custom properties, prefers-color-scheme: dark override, no external assets, no JS). Copy it verbatim into every page — do not factor it into a shared file; self-containment per page is the point (FR-004).

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="promptworld-docs:generated-by" content="player-docs">
<meta name="promptworld-docs:source" content="<repo-relative-path>@<40-hex-commit>">
<!-- one promptworld-docs:source tag per source, each on its own line -->
<title>&lt;Page title&gt; — promptworld player docs</title>
<style>
  :root {
    --bg: #ffffff;
    --fg: #1a1a1a;
    --muted: #55606a;
    --accent: #0b5fff;
    --border: #d8dee4;
    --code-bg: #f3f5f7;
    --card-bg: #f8f9fb;
  }
  @media (prefers-color-scheme: dark) {
     {
      : ;
      : ;
      : ;
      : ;
      : ;
      : ;
      : ;
    }
  }
  * { : border-box; }
  ,  { : ; : ; : (--bg); : (--fg); }
   {
    : -apple-system, BlinkMacSystemFont, , Roboto, Helvetica,
      Arial, sans-serif;
    : ;
    : ;
    :  auto;
    :   ;
  }
  , ,  { : ; }
   { : ; : ; }
   { : ; : ; :  solid (--border);
    : .; }
   { : ; : ; }
  , ,  { : . ; }
   { : (--accent); }
  , pre { : ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
   { : (--code-bg); : . .; : .;
    : .; }
  pre { : (--code-bg); : ; : .;
    : auto; }
  pre  { : none; : ; }
   { :  solid (--accent); :  ; : . ;
    : (--muted); }
   { : (--muted); : ; }
   { : (--card-bg); :  solid (--border);
    : .; :  ; :  ; }
   { : block; : ; : ; : none; }
    { : . ; }
   { : collapse; : ; :  ; }
  ,  { :  solid (--border); : . .; : left; }
   { : ; : ; :  solid (--border);
    : (--muted); : .; }



Page title
one-line framing

... content ...

 Back to player docs index

index.html follows the same skeleton minus the source meta tags, and its body is a nav hub linking every topic page with a one-line blurb rather than factual content.