Demo Kingdoms — design

A curated portfolio of demo "kingdoms" (sample Markdown corpora) for Kingdom.md marketing, co-authored incrementally and paced by enjoyment. The set showcases the viewer across four jobs at once — feature showcase · aesthetic/vibe · relatable templates · delight-through-close-reading — and one of its kingdoms (the Kingdom.md Wiki) is promoted to the project's continuous documentation spine.

Status: design validated through brainstorming 2026-06-16/17. Pairs with a future demo-kingdoms-plan.md. Lives in the Kingdom.md project layer (not Yggdrasil).

Firmness tiers (how to read this doc):

1. Conventions = the contract (the "Shared conventions" section) — held steady; changing one ripples across every kingdom.
2. Blueprints = committed-but-loose direction (per-kingdom) — firm enough to start; real flavor is discovered live at author time.
3. Content = examples — every roster, filename, gag, and frontmatter value shown here is illustrative, decided in the authoring sessions, not binding.

Understanding summary

• What: a curated portfolio of demo kingdoms for Kingdom.md marketing, co-authored with the user, not bulk-generated.
• Why: demonstrate the viewer across feature showcase, aesthetic/vibe, relatable templates, and delight-through-close-reading (a cheeky payload that rewards attentive readers).
• Who: prospective Kingdom.md users skimming marketing; secondarily anyone who reads closely and catches the jokes.
• Depth: sized to what it is — uneven by design, realism over uniformity, deep enough that the inline-subnav depth-valve trips where natural.
• Process: co-authored, fun-paced, /clear-safe and resumable via a progress doc; the user picks whichever kingdom/branch sounds fun next.
• Non-goals: not the full Kingdom.md manual (deferred to its own treatment); not bulk generation; no features the viewer doesn't yet have (dotfiles, non-.md rendering, wikilinks are all deferred showcases).

Assumptions

1. Public-facing marketing artifacts — no real private data; the romantasy reading content is transformative parody (no real titles), so no copyright/real-author exposure.
2. Each kingdom is a folder of .md files with a landing file so /{kingdom} opens gracefully (the app renders the landing in place at the clean URL).
3. Shared conventions established up front; a progress doc carries resumability.
4. The viewer renders .md files only — non-.md artifacts (yaml/json/db) and dotfiles simply don't appear yet; we lean into the markdown layer and add the rest as future viewer features land.

Strategy layer — two categories of kingdom

The portfolio has a deliberate strategy, not just a list. Each kingdom's landing filename signals its category.

The app's findLanding already accepts all these candidates (kingdom.md is the #1 priority, matched case-insensitively), so the convention is built in, not bolted on.

Shared conventions (the contract)

1. Layout. Each kingdom is a top-level dir under demo-kingdoms/ (inside the kingdom-md repo); config/kingdom.php registers name→path for the live/marketing instance.

demo-kingdoms/
  kingdom.md/     KINGDOM.md + wiki pages           (the Wiki — native, the spine)
  agent-memory/   README.md + memory/skills tree    (Hermes migration)
  dnd-vault/      index.md, world/, npcs/, sessions/ (Obsidian migration)
  blog/           KINGDOM.md + YYYY/MM/<post>.md     (native — date depth-valve)
  recipes/        KINGDOM.md + <course>/…            (native — deferred slot)

2. Landing files — category-dependent (see strategy table): KINGDOM.md for native kingdoms, the emulated tool's idiom for migration ones.

3. Frontmatter — coherent core + per-kingdom keys. A small shared core (title, tags, and where it fits type) keeps the frontmatter card consistent across kingdoms; each kingdom adds domain keys. This is deliberate: switching kingdoms shows the card carrying varied, believable metadata.

4. Cross-kingdom linking + fill-later. Relative links within a kingdom; root-absolute /{kingdom}/path across kingdoms. Links whose targets don't exist yet (e.g. blog→recipe) are written to their intended path, tagged with a greppable marker (e.g. a trailing <!-- TODO:link -->), and tracked in the progress doc's cross-link ledger for verification when the target kingdom lands.

5. Cheek principle. Cheeky throughout (each kingdom a distinct voice discovered at author time; the wink rewards close reading), with one exception: the Wiki is real documentation and runs a lighter, lighthearted touch — not parody. Delight-through-close-reading is a design constraint, not just flavor.

6. The .md-only constraint is load-bearing for content design: build from the markdown layer; treat hidden/dot and non-.md artifacts as future showcases, not current content.

Per-kingdom blueprints (directional)

kingdom.md/ — the Kingdom.md Wiki (native · the continuous spine)

• Identity: the product's real wiki — genuine, maintained documentation, not a fictional encyclopedia. It is Kingdom.md's continuous documentation spine (see "Docs-as-driver" below).
• Content: a release register / living changelog (each major release is codenamed after a king; the entry carries the release notes + light trivia) plus product info/lore pages. Kings are incidental — they survive only as codenames with a little trivia, not as the subject.
• Showcases: real-docs long-form reading, tables, the native KINGDOM.md convention (served at the clean https://kingdom.md/kingdom.md), and the dogfooding/transparency story (our wiki, in our viewer).
• Voice: lighthearted, lightly witty — real documentation with a wink, less cheeky than the others.
• Frontmatter: title · tags · release · codename · released.
• Lifecycle: continuously maintained; gains a crowned entry per release. 1.0 codename = "King" (The Owl House) — bookmarked (see Release hooks).
• Verified: the kingdom.md/ dir name is safe end-to-end (dir classified by is_dir before the .md check; route param allows dots; KINGDOM.md is the #1 landing candidate; path-safety clears it).

agent-memory/ — "Apollo," a self-improving agent's mind (migration · Hermes)

• Premise: emulate the on-disk markdown structure of Hermes Agent (Nous Research) — researched and banked in 2026-06-16-hermes-agent-research.md — reflavored as a tongue-in-cheek mythological foil to Hermes (working name Apollo, the canonical mythic rival who had his cattle stolen by infant Hermes). Borrow open-standard conventions; author original content; reflavor every hermes-named key, including the frontmatter namespace → metadata.apollo.*.
• Showcases: the set's depth demo (the skills/<category>/<skill>/ tree trips the subnav), code blocks, task lists, a frontmatter trio (rich SKILL.md / frontmatter-only DESCRIPTION.md / no-frontmatter MEMORY.md+USER.md), and the transparency hook (reading an AI's mind as prose).
• Structure (markdown layer only for now): README.md landing · SOUL.md · AGENTS.md · memories/{MEMORY,USER}.md (§-delimited, plain) · skills/<category>/<skill>/SKILL.md (+ references/ templates/) · skills/<category>/DESCRIPTION.md · plans/<dated>.md · logs/curator/<ts>/REPORT.md (the visible self-improving narrative).
• Deferred: the dot-prefixed curator sidecars (.usage.json, .archive/…) and non-.md artifacts (config.yaml, state.db) join later, as showcases for the future dotfile-toggle / non-.md rendering features.
• Voice: Apollo — lofty, orderly, faintly pompous sun-god; earnest self-improvement; the foil-to-Hermes rivalry surfaces in asides (e.g. a cheeky migrate-from-hermes skill).

dnd-vault/ — a D&D campaign as an Obsidian vault (migration · Obsidian)

• Fidelity call: built structurally as a vault (index.md home, aliases/tags frontmatter, folder taxonomy, daily-note-style session logs, an .obsidian/ dir that correctly stays hidden) but with clean-rendering standard-markdown links — not [[wikilinks]]/embeds/callouts (those render literally today; Obsidian feature parity is a bookmarked roadmap item).
• Showcases: deep nesting (world/<region>/<location> trips the subnav), structured frontmatter (NPC/location/session stat-block cards), tables (stat blocks, loot, encounter tables), wiki-style cross-links, strong in-world voice.
• Frontmatter: Obsidian core (aliases, tags) + domain keys (NPC race/class/alignment/ location/status; location region/type/population; session date/session/players).
• Voice / premise: a DM's living campaign vault; cheek lives in DM-vs-party session-log comedy. Author-time premise: caricatured versions of three player-characters (PCs) once played in the user's real-life campaign (+ occasional side characters) as the in-world cast — the primary cheek vector. (These are the fictional characters, not the real players — so no real-person likeness/consent concern.)
• Research dependency (planning-time): a pass on Obsidian-specific D&D campaign-organization best practices.

blog/ — the blog-of-reviews (native · date depth-valve)

• Showcases: the canonical date depth-valve (YYYY/MM/<post>.md), long-form reading, strikethrough (DNFs / redacted asides), review-metadata cards, and cross-kingdom links (blog → recipe, fill-later).
• Voice: the ambiguously-self-aware romantasy caricature — a loving send-up of the dark-fantasy- romance-fan stereotype (wine, pumpkin spice, ex-emo "villain era"), leaning into every trope, never quite letting you tell if it's a bit. Treats absurd fictional books with breathless earnestness. Tone ceiling: frank/suggestive, not graphically explicit; the spice frontmatter carries the wink.
• Material (author-time workflow): (1) find genuinely popular dark-fantasy/romantasy books and condense their real review sentiment; (2) subtly rename every proper noun to believable-but- faintly-funny substitutes (Damien → Michael, Julia → Karen) — tuned for the "wait… is this…? no… is it?" near-recognition that only fires for readers intimate with the source; (3) original parody prose on real-review DNA. (Supersedes the earlier "real titles" idea; this is safer and funnier.)
• Frontmatter: title · date · tags · book · author · series · rating · status · spice (all the proper-noun values are the renamed absurd-but-believable ones).
• Cross-links: within-blog (post→post); the recipe bridge ("I recreated the honey cake from the feast scene") written now, fill-later-marked until recipes exist.

recipes/ — the deferred slot (native · scaffold only)

• Role: scaffold now, fill later — ideally the user's grandmother's real recipe book, otherwise generated dummy recipes. Exists so the blog's cross-links have a real target.
• Showcases (when filled): tables (ingredients) + task lists (steps) + tight frontmatter (servings/time/difficulty/course).
• Now: a KINGDOM.md landing + a sketched course taxonomy; the specific recipe paths the blog links to stay fill-later-marked.
• Voice/source (TBD by origin): Grandma's book → a warm heirloom voice with headnotes; dummy → a fictional-cook persona.

Authoring rhythm & the progress doc

• Co-authored, fun-paced, save-and-resume. Pick a kingdom (or a branch within one), build together, park anytime. No bulk generation.
• First kingdom = the exemplar that proves the conventions before replicating. Likely the Wiki (it's the spine, and a gentle low-cheek start) or agent-memory (most scaffold ready) — chosen at planning.
• The progress doc (demo-kingdoms-plan.md, from /planning) is the /clear-safe resume point. Per kingdom it tracks: status · structure sketch · voice seed · showcase targets · research dependencies · and the shared cross-link ledger.
• Per-kingdom "done": enough depth to showcase its target features, trip the depth-valve where intended, carry its voice, and render cleanly — sized to what it is, not exhaustive.
• Config integration (planning-stage): register the demo kingdoms in config/kingdom.php so the live instance serves them.

Docs-as-driver — the continuous spine (project-wide working principle)

Adopted as a continuous-documentation discipline (not full doc-driven-development): the kingdom.md/ Wiki is the project's living spine, kept current in lockstep with every feature and release from now through 1.0 and beyond. Design still happens in brainstorms/design docs; the Wiki always reflects current reality. This is the purest expression of the dogfooding ethos — a doc-viewer developed through the very docs it renders, served at its own name. To be recorded as a working principle in the project's CLAUDE.md/AGENTS.md (separate from this design doc, since it governs the whole project).

Decision log

1. Portfolio, not separate projects — one cohesive design; kingdoms divide the feature showcase rather than each repeating it.
2. All four marketing jobs at once, with a cheeky payload for close readers (the kings list tipped this).
3. Roster: Wiki (ex-kings) · agent-memory · dnd-vault · blog · recipes. The full how-to manual is dropped from this effort (proper treatment later) — distinct from the Wiki's release-lore/product-info spine in #10, which is real docs; reading-journal merged into the blog.
4. Depth = sized to what it is; co-authored, not bulk-generated, paced by enjoyment.
5. Two strategic categories (migration-appeal vs. Kingdom.md-native); landing filename signals category (KINGDOM.md vs. tool idiom).
6. Conventions tier is the contract; blueprints are loose direction; content is examples.
7. D&D = Obsidian vault, structural-only fidelity; Obsidian feature parity bookmarked as a product roadmap item.
8. agent-memory = Hermes structure, researched from source, reflavored as a mythological foil (Apollo); even the metadata.hermes namespace → metadata.apollo.
9. Blog: subtle-rename parody (believable near-recognition) over absurdist swaps; caricature voice; real-review-DNA sourcing.
10. Kings → the Kingdom.md Wiki: real documentation, kings incidental as release codenames; lighter humor; promoted to the continuous documentation spine; dir named kingdom.md/ (verified safe).
11. Cross-kingdom links via root-absolute URIs, with a fill-later ledger.
12. .md-only / dotfiles / non-.md artifacts deferred as future feature showcases, not current content.
13. Docs-as-driver = continuous spine (not full doc-driven development).
14. Recipes deferred to a scaffold slot; content source TBD (Grandma's book vs. dummy).

Deferred / roadmap hooks

• Obsidian feature parity ([[wikilinks]]/embeds/callouts) → Kingdom.md product roadmap; revisit after building some of those features. (Lands in working/DESIGN.md Roadmap, or formal bookmark store if asked.)
• Dotfile show/hide config → product feature; then enrich agent-memory with the curator sidecars.
• Non-.md file rendering (yaml/json/db) → product feature; then enrich agent-memory's config/state.
• Recipe content source → Grandma's real book vs. generated dummy.
• 1.0 release codename = "King" (The Owl House) → release hook; the Wiki crowns it at 1.0.
• Cross-link fill-later ledger → lives in the plan; verified as target kingdoms land.

Open author-time / planning items

• Research (planning): Obsidian D&D campaign-org best practices; blog real-popular-romantasy + condensed-reviews sourcing. (Hermes research already done.)
• Flavor (author-time): final deity name (Apollo front-runner); the blog's subtle-rename palette; the D&D world/setting + caricatured-players consent/anonymization; the recipe voice/source; per-release king picks (roster doubles as the release-name pool).

Handoff

The design is validated and documented. The next step is /planning — turn this into an executable, checkpoint-able demo-kingdoms-plan.md (sequencing the kingdoms, threading the per-kingdom research dependencies and the cross-link ledger, and wiring config/kingdom.php). Not begun here.