repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs(the-system): design rich markdown bundles

4b05f5a9d7a89bcb29fe521ad4a29f3ae3338d24

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (2)

docs/super/specs/2026-07-15-the-system-rich-markdown-design-mockup-compact-details-themed.html

Added
new file mode 100644
1 +<!doctype html>
2 +<html lang="en">
3 +<head>
4 +<meta charset="utf-8">
5 +<meta name="viewport" content="width=device-width, initial-scale=1">
6 +<title>Compact ledger · automatic system theme</title>
7 +</head>
8 +<body>
9 +<style>.fm{--ink:#121212;--paper:#ededed;--surface:#dbdbdb;--line:#8b8b8b;--muted:#565656;--accent:#922792;--link:#184e5b;color-scheme:light dark;max-width:820px;margin:auto;padding:28px 34px;color:var(--ink);background:var(--paper);font:14px/1.45 system-ui,sans-serif}@media(prefers-color-scheme:dark){.fm{--ink:#ededed;--paper:#242424;--surface:#303030;--line:#565656;--muted:#b8b8b8;--accent:#d86dd8;--link:#7ba1aa}}.fm .eyebrow{margin:0;color:var(--muted);font:800 10px ui-monospace,monospace;letter-spacing:.12em;text-transform:uppercase}.fm h1{max-width:16ch;margin:8px 0 16px;font:900 40px/.98 system-ui,sans-serif;letter-spacing:-.04em}.fm .summary{display:flex;flex-wrap:wrap;gap:12px;margin-bottom:14px;color:var(--muted);font:800 10px ui-monospace,monospace}.fm .summary b{color:var(--ink)}.fm details{border-top:1px solid var(--line);border-bottom:1px solid var(--line)}.fm summary{padding:8px 0;color:var(--muted);font:800 10px ui-monospace,monospace;letter-spacing:.06em;cursor:pointer}.fm summary::marker{color:var(--accent)}.fm dl{display:grid;grid-template-columns:125px 1fr;margin:0 0 8px}.fm dt,.fm dd{margin:0;padding:6px 8px;border-top:1px solid color-mix(in srgb,var(--line) 45%,transparent)}.fm dt{color:var(--muted);font:800 10px ui-monospace,monospace}.fm dd{overflow-wrap:anywhere}.fm a{color:var(--link)}@media(max-width:560px){.fm dl{grid-template-columns:1fr}.fm dt{padding-bottom:0}.fm dd{padding-top:2px;border-top:0}}</style><article class="fm"><p class="eyebrow">Spec</p><h1>Rich document bundles</h1><div class="summary"><span><b>SYS-SPEC-001</b></span><span>ACCEPTED</span><span>2 REFERENCES</span><span>8 FIELDS</span></div><details><summary>SHOW ALL FRONTMATTER</summary><dl><dt>id</dt><dd>SYS-SPEC-001</dd><dt>kind</dt><dd>spec</dd><dt>status</dt><dd>accepted</dd><dt>title</dt><dd>Rich document bundles</dd><dt>references</dt><dd><a href="#">SYS-SPEC-002</a>, <a href="#">SYS-PLAN-001</a></dd><dt>owners</dt><dd>human, the-system</dd><dt>review</dt><dd>approved: 2026-07-15; mode: browser</dd></dl></details></article>
10 +</body>
11 +</html>

docs/super/specs/2026-07-15-the-system-rich-markdown-design.md

Added
new file mode 100644
1 +# The System Rich Markdown Design
3 +## Goal
5 +Replace authored HTML specs, roadmaps, plans, issues, and research with human-editable rich Markdown document bundles.
7 +Preserve rich browser communication through one bundled renderer that can show either one document or the complete project dossier without mutating project files or requiring project tooling.
9 +## Decision Summary
11 +- Core laws remain Markdown files at `.system/SYSTEM.md`, `.system/MISSION.md`, and `.system/RULES.md`.
12 +- Every authored governance document becomes a directory containing canonical `index.md` and document-owned assets.
13 +- The supported Markdown profile includes GFM, YAML frontmatter, footnotes, definition lists, GitHub alerts, Mermaid, TeX math, syntax highlighting, heading anchors, generated tables of contents, local assets, and raw HTML.
14 +- Accepted mockups remain free-form standalone HTML inside their owning spec bundle.
15 +- A bundled Node renderer and skill provide single-document and full-book browser views.
16 +- Single-document and book views use the exact same Markdown parser, article renderer, theme, and metadata renderer.
17 +- Rendered HTML is ephemeral and never becomes canonical project state.
18 +- HonKit is not used.
20 +## Problem
22 +Authored HTML communicates visually but makes routine human editing unpleasant.
24 +Markdown is easy to edit but becomes difficult to scan when diagrams, structured metadata, callouts, equations, or visual assets collapse into prose.
26 +AsciiDoc offers stronger native structure but imposes an unsuitable tooling and runtime burden.
28 +The System needs Markdown source ergonomics without surrendering deliberate browser presentation.
30 +## Canonical Project Structure
32 +```text
33 +.system/
34 +├── config.json
35 +├── SYSTEM.md
36 +├── MISSION.md
37 +├── RULES.md
38 +├── specs/
39 +│ └── SYS-SPEC-001-rich-documents/
40 +│ ├── index.md
41 +│ ├── mockup-document-viewer.html
42 +│ ├── bundle-topology.svg
43 +│ └── evidence.csv
44 +├── roadmaps/
45 +│ └── SYS-ROADMAP-001-document-system/
46 +│ └── index.md
47 +├── plans/
48 +│ └── SYS-PLAN-001-renderer/
49 +│ └── index.md
50 +├── issues/
51 +│ └── SYS-ISSUE-001-rendering-gap/
52 +│ └── index.md
53 +└── research/
54 + └── SYS-RESEARCH-001-renderers/
55 + └── index.md
56 +```
58 +Each typed directory contains only document bundles.
60 +A bundle name remains `<ID>-<slug>`.
62 +Every bundle contains exactly one canonical `index.md`.
64 +Every other file in the bundle is owned by that document.
66 +Simple documents remain visually simple because their bundle contains only `index.md`.
68 +Moving or deleting a document moves or deletes its complete asset boundary.
70 +## Ownership And Mutation
72 +Existing core-law files remain human-owned and runtime-protected.
74 +A new spec bundle may be created directly after candidate validation.
76 +Every existing file inside a spec bundle is human-owned, including `index.md`, mockups, images, datasets, and other assets.
78 +Editing or replacing any existing spec-bundle file requires one interactive approval.
80 +Creating a missing asset inside an existing spec bundle does not require approval, matching the existing new-asset contract.
82 +Recognizable shell mutation of any spec-bundle path remains advisory-blocked because it bypasses candidate validation and interactive approval.
84 +Roadmaps and plans remain agent-authored with human review.
86 +Issues and research remain agent-authored.
88 +All authored `index.md` candidates receive shared metadata, reference, Markdown, and path validation regardless of ownership.
90 +## Rich Markdown Profile
92 +The renderer supports one explicit source profile:
94 +- GitHub Flavored Markdown tables, task lists, autolinks, and strikethrough;
95 +- YAML frontmatter;
96 +- footnotes;
97 +- PHP Markdown-style definition lists;
98 +- GitHub blockquote alerts;
99 +- fenced Mermaid diagrams;
100 +- inline and display TeX math;
101 +- fenced-code syntax highlighting;
102 +- deterministic heading IDs and anchor links;
103 +- a compact collapsed `On this page` table of contents after the metadata ledger;
104 +- relative local images, media, downloadable files, and HTML assets;
105 +- normal remote references;
106 +- raw HTML.
108 +The profile is owned by The System renderer rather than the project.
110 +Projects do not install packages, define scripts, or provide build configuration.
112 +## Trust Model
114 +Governed documents are trusted repository content.
116 +The renderer does not sanitize useful document syntax, block remote references, forbid cross-bundle links, or weaken Mermaid features under a false security boundary.
118 +Filesystem operations still resolve below the project root and temporary output root because path containment protects project data rather than policing document expression.
120 +Accepted mockups render in iframes to isolate their free-form layout and CSS from the document shell.
122 +Iframe isolation is a presentation boundary, not a claim that project-authored content is hostile.
124 +## Frontmatter Rendering
126 +Frontmatter semantics belong to the broader System core model and require a separate design discussion.
128 +This design fixes the rendering contract without prematurely freezing that schema.
130 +The renderer parses every frontmatter field and preserves source order.
132 +The document mast shows a compact summary from available identity, type, state, and reference information.
134 +A collapsed metadata ledger renders every field, including unknown fields, nested maps, arrays, booleans, numbers, and nulls.
136 +Recognized document references become links when the graph can resolve them.
138 +No field disappears merely because the renderer does not understand its semantics.
140 +Single-document and book views render the same mast, summary, and complete ledger.
142 +## Renderer Architecture
144 +The extension ships the renderer and all npm dependencies.
146 +The project supplies only `.system` source files.
148 +A unified/remark/rehype pipeline performs parsing and transformation.
150 +Representative package responsibilities are:
152 +- `remark-parse` and `remark-gfm` for Markdown and GFM;
153 +- `remark-frontmatter` or equivalent YAML extraction for metadata;
154 +- `remark-rehype` with dangerous HTML enabled followed by `rehype-raw` for authored raw HTML;
155 +- `remark-math` and `rehype-mathjax` for TeX;
156 +- `remark-definition-list` for definition lists;
157 +- `remark-github-blockquote-alert` for alerts;
158 +- `rehype-highlight` or a Shiki integration for code;
159 +- Mermaid's browser bundle for diagrams;
160 +- `minisearch` for generated full-text search.
162 +Exact dependency selection remains an implementation-plan decision, but one parser pipeline must own both viewing modes.
164 +The renderer has four internal stages:
166 +1. Discover and validate document bundles.
167 +2. Parse frontmatter and Markdown into one document model.
168 +3. Render reusable article HTML with Nugu styling.
169 +4. Wrap that article in either a single-document shell or the full-book shell.
171 +The article renderer is singular.
173 +No mode-specific Markdown parsing or metadata formatting is allowed.
175 +## Single-Document View
177 +`/system-view [path-or-id]` delegates to a rendering skill.
179 +The skill resolves one bundle, invokes the bundled cross-platform renderer CLI, opens the temporary result in the browser, and exits.
181 +Authoring workflows offer the same view after writing or materially editing a document.
183 +Single-document output includes:
185 +- the complete document mast and frontmatter ledger;
186 +- the same collapsed in-document table of contents used by book pages;
187 +- rendered rich Markdown;
188 +- resolved local assets;
189 +- inline isolated previews for accepted mockups;
190 +- source-located diagnostics;
191 +- no book navigation or global search.
193 +No Pi tool is registered because viewing has no browser-to-agent event round-trip.
195 +A tool becomes justified only if a future design makes the rendered document editable or returns browser events to Pi.
197 +## Full-Book View
199 +`/system-book` delegates to the same rendering skill and pipeline.
201 +The book includes:
203 +- navigation grouped by project law, specs, roadmaps, plans, issues, and research;
204 +- stable previous and next document movement;
205 +- complete frontmatter rendering;
206 +- graph-derived references and backlinks;
207 +- generated full-text search across titles, IDs, frontmatter, and body content;
208 +- ranked results with document identity, type, and bounded context;
209 +- the same inline mockup previews and rich Markdown features as single-document view;
210 +- the same automatic light and dark Nugu theme.
212 +Search is generated from canonical source during ephemeral rendering.
214 +It is not limited to titles or navigation labels.
216 +## Asset Handling
218 +Both viewing modes render every governed document and copy every governed bundle into temporary output while preserving relative paths.
220 +Single-document mode opens the selected page in its minimal shell but keeps the other generated pages available as cross-document link targets.
222 +Book mode opens the same generated page set through the navigation and search shell.
224 +Markdown links continue to resolve against their source document location.
226 +The renderer rewrites canonical Markdown document links to their existing rendered HTML targets while leaving ordinary asset and remote links intact.
228 +No project file is generated, renamed, edited, or deleted.
230 +Temporary output may be discarded after browser use.
232 +## Mockup Integration
234 +Accepted mockups move from adjacent authored HTML filenames into their owning spec bundle.
236 +Example:
238 +```text
239 +.system/specs/SYS-SPEC-001-rich-documents/
240 +├── index.md
241 +└── mockup-document-viewer.html
242 +```
244 +The spec links the mockup relatively:
246 +```markdown
247 +[Document viewer mockup](./mockup-document-viewer.html)
248 +```
250 +The source remains a normal link.
252 +The renderer recognizes bundle-owned mockup HTML and upgrades that link into an isolated inline preview with an explicit full-size action.
254 +The generic `mockup` tool remains unchanged because its free-form HTML and interactive browser feedback are intentional.
256 +## Visual Language
258 +The renderer uses the shared Nugu palette with automatic light and dark modes.
260 +The book must remain calm rather than turning every semantic distinction into a color.
262 +Color usage follows these rules:
264 +- neutral surfaces carry hierarchy;
265 +- body text remains high contrast;
266 +- muted text identifies secondary metadata and navigation groups;
267 +- magenta is a sparse identity and active-state accent;
268 +- cyan identifies links and informational states;
269 +- warning and error colors appear only for corresponding diagnostics;
270 +- Mermaid, MathJax, syntax highlighting, alerts, navigation, and generated controls inherit the same theme tokens.
272 +The content surface uses the Nugu panel tone rather than a full black field in dark mode.
274 +Spacing, type weight, borders, and proximity do most grouping work.
276 +## Diagnostics And Partial Rendering
278 +Renderer failures never mutate canonical source.
280 +A malformed extension reports its source path and location when available.
282 +The renderer preserves useful partial output instead of rejecting the complete document for one broken diagram, equation, link, or asset.
284 +Book mode reports document-specific failures without hiding healthy documents.
286 +Broken references and assets remain visible diagnostics.
288 +## HonKit Experiment
290 +A temporary experiment tested HonKit 6.2.2 against eleven representative document bundles containing core laws, specs, a roadmap, plans, an issue, research, cross-document links, owned HTML mockups, SVG assets, frontmatter, tables, tasks, footnotes, definition lists, alerts, Mermaid, TeX, and code.
292 +Direct HonKit input failed because it requires `README.md`.
294 +An ephemeral staging copy with generated `README.md` and `SUMMARY.md` successfully preserved the proposed canonical bundle structure.
296 +It produced grouped navigation, previous and next links, search, valid cross-document links, and copied assets without changing source hashes.
298 +Its GitBook-legacy Markdown pipeline left Mermaid and TeX literal, rendered GitHub alerts as ordinary blockquotes, and failed to render definition lists.
300 +The built-in highlight plugin also reported Mermaid as an unknown language while still exiting successfully.
302 +HonKit-specific Mermaid and math plugins add a second plugin ecosystem with legacy GitBook assumptions and inconsistent dependency age.
304 +HonKit is actively maintained, but its parser architecture conflicts with the required rich Markdown contract.
306 +A second temporary prototype using unified rendered Mermaid, MathJax SVG, alerts, definition lists, footnotes, highlighted code, bundle assets, inline mockups, automatic Nugu theming, and full-text search while preserving source hashes.
308 +Therefore The System keeps HonKit's useful book interaction shape but does not use HonKit.
310 +## Migration
312 +This design replaces the authored-HTML document model before Phase 6 implements spec authoring.
314 +Phase 6 must be rewritten around rich Markdown bundles, rendering, and spec authoring rather than implementing HTML workflows that would immediately be deleted.
316 +The implementation must revise completed kernel and runtime assumptions where they currently require authored `.html` files.
318 +New project-local authored documents use bundle `index.md` paths only.
320 +Accepted mockups remain HTML assets and move inside spec bundles.
322 +Historical `docs/super/**` artifacts remain untouched unless a later explicit migration names them.
324 +The extension owns and versions the renderer theme as a bundled asset.
326 +Initialization stops creating `.system/system.css`, and the approved schema upgrade removes that obsolete machine-owned file.
328 +## Verification
330 +Automated checks must prove:
332 +- every authored type discovers bundle `index.md` files deterministically;
333 +- malformed bundle names, missing `index.md`, duplicate IDs, and invalid references produce diagnostics;
334 +- new spec files pass while every existing spec-bundle file requires approval before replacement;
335 +- single mode preserves working cross-document links without exposing book navigation;
336 +- single-document and book modes produce identical article HTML for the same source;
337 +- every frontmatter field renders in source order in both modes;
338 +- nested frontmatter values remain readable;
339 +- GFM, footnotes, definition lists, alerts, Mermaid, TeX, code highlighting, anchors, and raw HTML render;
340 +- local, cross-bundle, and remote references remain useful;
341 +- accepted mockups preview inline and open separately;
342 +- full-text search finds body and frontmatter terms absent from titles;
343 +- generated links and copied assets resolve;
344 +- light and dark themes meet contrast expectations and theme every generated component;
345 +- rendering leaves all project source hashes unchanged;
346 +- browser opening works on Windows, macOS, and Linux;
347 +- existing task branching and generic mockup behavior remain unchanged.
349 +Browser E2E covers Chromium and Firefox.
351 +## Non-Goals
353 +- No in-browser document editing.
354 +- No persistent generated site.
355 +- No deployment or publishing workflow.
356 +- No project-owned renderer config, dependencies, or build tasks.
357 +- No AsciiDoc support.
358 +- No HonKit integration.
359 +- No automatic historical `docs/super/**` conversion.
360 +- No final frontmatter schema or lifecycle semantics in this design.
362 +## Mockups
364 +- [Compact frontmatter summary and ledger](./2026-07-15-the-system-rich-markdown-design-mockup-compact-details-themed.html)