Kingdom.md landing page (KINGDOM.md) — design

The design for the standalone overview essay that lives at demo-kingdoms/kingdom.md/KINGDOM.md, is served at the clean URL kingdom.md/kingdom.md, and acts as the project's de-facto homepage while it's the only real document.

Status: validated via brainstorming 2026-06-17. A sub-design under demo-kingdoms-design.md (the kingdom.md/ Wiki kingdom). Lives in the Kingdom.md project layer. Pairs with a future landing-page-plan.md — though for a single file, building directly may be simpler than a formal plan.

Understanding summary

  • What: the content of demo-kingdoms/kingdom.md/KINGDOM.md — a single, standalone overview essay introducing Kingdom.md to someone who's never heard of it. The only real document for a while, so it must stand entirely on its own.
  • Why: one good, self-contained read covering what it is · why I built it · how it could be used · where it's headed. Not a get-started guide (app too minimal), not a docs index (no other docs to point at yet).
  • Who: a first-time reader. Broad and welcoming, not reference-grade.
  • Voice: first-person, my own voice; earnest with a light wink; deliberately not grandiose.
  • Through-line: FOSS — free, open-source, self-hosted, yours — emphasized across the doc rather than boxed into one section.
  • Honesty constraint: RBAC and agent-memory are where it's headed, not shipped; never implied as present. The reader is literally inside the minimal current version.
  • Medium constraint: pure Markdown through the existing viewer. No raw HTML (it's escaped). Expressiveness comes from frontmatter + Markdown structure + voice. That this page is a Kingdom.md document is itself the strongest argument it can make.

Assumptions

  1. Single self-contained file — no required links to pages that don't exist yet. No GitHub link yet (no public repo).
  2. Not final — a strong foundation to iterate on, not carved in stone.
  3. Wire it up to view live — register the kingdom.md kingdom in config/kingdom.php when done so it serves from the running app.

The arc

Approach B (inverted pyramid) with a touch of C (thesis): orient a stranger in the first breath, then earn depth — what → why → concrete → could-be → where-headed → is — with a light "readable / governable / agent-usable" frame as connective tissue for the forward-looking section.

  1. The lede — what it is + the dogfood hook. One tight paragraph: Kingdom.md turns a folder of Markdown files into a clean, self-hosted, open-source website you own. Then the wink, landed immediately as a blockquote pull: you're reading this right now inside the thing it describes — this page is just a Markdown file Kingdom.md is rendering. (The blockquote gives the eye a beat and quietly shows the viewer rendering one.)

  2. Why I built it. Two concrete first-person itches, each seeding a later pillar:

    • I wanted real authentication / access control for my documentation — not docs flung open to anyone with the URL, but a viewer where I decide who sees which kingdom. → seeds governable (RBAC).
    • I wanted to de-black-box AI agents — if an agent keeps its memory and reasoning as Markdown, a viewer like this lets you literally read its mind in plain prose, instead of trusting an opaque system. → seeds agent-usable (agent-memory). The warm heart of the doc — the "why I" specifically.

  3. What a "kingdom" actually is. The core mental model, concretely: point it at a folder (a kingdom), it serves the file tree and renders each page. Read-only, login-less, fast, free, self-hosted. Grounds the reader in the real thing before the could-be's.

  4. Ideas for how it could be used. The could-be, as an evocative list: personal knowledge base, team docs, a D&D campaign vault, a project wiki, a window into an agent's memory… Concrete and a little playful — the wink lives most comfortably here.

  5. Where it's headed. The two founding itches grown up, held together by the borrowed frame: Markdown that's readable (today), governable (the RBAC idea — multi-user, per-kingdom roles), and agent-usable (the agent-memory idea — Markdown as the substrate an agent thinks in, and Kingdom.md as the human-readable window into its mind). Explicitly future-tense and deliberately modest — "what's next," not "my grand vision."

  6. Where it actually is today. Short and candid: right now it's deliberately minimal — read-only, login-less, no RBAC, no agents yet — and this very page is proof it already nails the core job. It's open and yours. Honest close, with the dogfood echoed once more ("this page is the proof").

Honesty is structural: §1–4 describe what is or could trivially be, §5 is explicitly future-tense, §6 names the present plainly.

Dogfood named exactly twice — the hook up top, a quiet echo at the close — so it stays a wink, not a gimmick.

Voice & tone

  • First-person, earnest with a light wink — the vision lands before any joke does.
  • Avoid grandiosity. No "I have a vision"; prefer "what's next," "where it's headed," "ideas I'm building toward."
  • This Wiki kingdom is the low-cheek, real-docs one (per the demo-kingdoms design). It showcases the viewer by being a genuinely good read at the sacred measure — not by parading features. A blockquote and a list or two, used because they belong, not to demo them.
  • FOSS / self-hosted / "you own it" as a quiet through-line.

Frontmatter (the card above the article)

title: Kingdom.md
type: overview
tags: [kingdom.md, self-hosted, markdown, open-source]
updated: 2026-06-17

title + tags are the shared core from the demo-kingdoms contract; type: overview signals the kind of page; updated makes the spine feel maintained. Not using the release-register keys (release / codename / released) — those belong on per-release Wiki entries, not this landing.

Medium constraints (what actually renders)

  • Renders: CommonMark core (headings, lists, blockquotes, links, inline + fenced code, emphasis, rules) + GFM tables, task lists, strikethrough, autolinks.
  • Does not: syntax highlighting (roadmap), raw HTML (html_input => 'escape' — typed HTML shows literally), so pure Markdown only.
  • No images: the viewer serves .md only and there's no asset route in a kingdom, so an ![](…) would 404. Text carries the whole page for now.
  • Prose held to the ~66ch sacred measure in the Warm Editorial chrome (Newsreader/Spectral, warm paper, quiet frontmatter card).

Success criteria

  • A stranger finishes knowing what it is, why it exists, how it might be used, and where it's headed.
  • Never misled about what's built — roadmap reads clearly as future.
  • Reads cleanly in the viewer; the dogfood lands as a wink (named twice, top + close), not a gimmick.
  • The FOSS / self-hosted character comes through without a sales pitch.

Decision log

  1. Standalone overview essay — not a marketing billboard or a docs index. It's the only document for a while, so it must stand alone. (Rejected: get-started guide — app too minimal; docs index — no other docs to point at.)
  2. Arc = inverted pyramid (B) with a light thesis frame (C) for the forward section. (Rejected: origin-first A — risks burying what-it-is for a stranger; full manifesto C — risks grandiosity.)
  3. Voice = first-person, earnest, light wink, deliberately non-grandiose. (Rejected: witty-forward; plain-technical.)
  4. The two founding motivations are the two forward pillars — auth-for-docs → RBAC, de-black-box-agents → agent-memory. The "why" (§2) and "where it's headed" (§5) are one spine.
  5. FOSS / self-hosted emphasized as a through-line, not its own section.
  6. Honesty is structural — §1–4 present/near, §5 future-tense, §6 candid current state.
  7. Dogfood named exactly twice — lede hook + closing echo.
  8. Frontmatter = title / type / tags / updated; no release-register keys; the "vision" tag was dropped as too grandiose.
  9. Pure Markdown only (HTML escaped); no images (no asset route) — text carries it.
  10. Wire kingdom.md into config/kingdom.php at build time so it serves live.

Handoff

Design validated and documented. Next step is to build the page — it's a single Markdown file, so running /planning for a formal plan is likely overkill; authoring it directly and wiring the kingdom into config/kingdom.php is probably the lighter path. (/planning remains available if a checkpoint-able plan is wanted.)