DOCS-TODO — `/doc` documentation overhaul

Briefing for the doc-system overhaul. Read this fully before touching anything. The approved design and the two locked decisions are: (1) examples are LIVE and SELF-VERIFYING — real UCE code executed at render time, showing source + actual captured output, gated by the test suite; (2) FULL SWEEP of all 257 pages.

The docs live under site/doc/:

index.uce — the renderer (index + per-page detail view).
lib/doc_page.h — page parsing (load_doc_page) + label/kind helpers.
style.css — theme + layout.
pages/*.txt — 257 page source files (the corpus).
areas/*.txt — area groupings; first line is the area title, following lines are page slugs (or >area references) that populate the index sidebar.
search.uce, singlepage.uce — search + single-page render.

Why this work exists (the problems)

Title bug: 15 pages carry a :title that literally repeats the raw filename, so 0_StringList renders as "0_StringList" instead of "StringList". The :title override defeats the prefix-stripping label logic already in doc_page.h (doc_default_title / doc_index_label / doc_method_label).
31 slop/stub pages: the newest APIs (file_*, crypto_equal, sha256*, hmac*, random_bytes, http_request*, job_*, shell_spawn) are throwaway # name + one-line markdown with NO :sig/:params/:see/:content.
134 of 257 pages have no code example. We want PHP-manual-style code-to-output examples on EVERY page.
Sidebar overflow: long monospace identifiers in the 280px index sidebar and 220px detail sidebar have no wrapping → they spill.
Relevancy: pages lead with cross-membrane mechanics and "Related Concepts" PHP/JS filler instead of usage; cross-references between related pages are missing.

Principles for every page

Usage first. The opening :content sentence says what the function does and when you'd reach for it — in plain terms. No membrane/ABI talk up top.
A real example, always. Every page has at least one :example whose output is produced by actually running it. Examples are the primary teaching tool.
Cross-link. Every page's :see references its area (>area) and its closest sibling APIs, so the reader is never left to search alone.
Demote the drivel. Cross-membrane behavior, lock semantics, and PHP/JS equivalents are at most a short trailing note — never the body. Delete filler that teaches nothing.

Phase 1 — Infrastructure (do this FIRST, verify on host before any content)

1a. Title bug

In lib/doc_page.h load_doc_page: when a :title value, trimmed, equals the page slug, ignore it (leave result.title empty) so the renderer falls through to doc_default_title, which already strips 0_/1_/2_/3_ prefixes and renders Class::method for 2_*.
Strip the 15 redundant :title blocks from their pages (0_StringList, cli_arg, cli_input, list_filter, list_map, map, request_base_url, request_query_path, request_query_route, request_script_url, route_path_is_safe, route_path_normalize, route_path_sanitize, ucb_encode, ucb_decode).
Fix garbage :sig lines on struct pages (e.g. 0_StringList's sig is literally 0_StringList): give struct pages a real one-line type summary or drop the sig box.

1b. Live example mechanism — EXACT SPEC

Primitives (already confirmed to exist): unit_compile(path), unit_render(path), ob_start(), ob_get_close(). Relative paths in the doc unit resolve against site/doc/.

Parse: add :example handling to load_doc_page → DocPage.examples (a list; multiple :example blocks per page allowed). Capture the raw body lines verbatim (this is both the displayed source AND the executed code).
Materialize: for each example, write the body wrapped in a minimal unit to a stable path examples/_gen/<slug>_<n>.uce:
```
RENDER(Request& context)
{
    <example body>
}
```
Write only if the content changed (compare to existing file) so the runtime's compiled-unit cache stays warm. The _gen dir must be writable by the worker (www-data) — created/chowned once on the host (see Setup below).
Execute + capture: unit_compile("examples/_gen/<slug>_<n>.uce"); then ob_start(); unit_render("examples/_gen/<slug>_<n>.uce"); String out = ob_get_close();
Render: an "Example" doc-section showing the source block, then the captured output beneath it under an "Output" label (PHP-manual style). If the example traps or output is empty, surface that visibly (do not swallow it) — a broken example must be obvious so the gate catches it.
Examples must be self-contained and deterministic — no wall-clock/random output shown as canonical (if a function is inherently non-deterministic, show a representative call and describe the shape, or seed it). The gate asserts presence of an output block + absence of an error marker, not an exact value, EXCEPT where the value is deterministic.

1c. Sidebar + example CSS (`style.css`)

Add overflow-wrap: anywhere; word-break: break-word; to .category li a, .func-item a, and .sidebar-card div.
Style the example Output block so it's visually distinct from the source (subtle border + an "Output" label), reusing existing --bg-code/--border tokens.

1d. Format spec page

Create pages/3_Documentation format.txt (an info page) documenting the canonical page template below, so the format is self-describing inside the docs.

Canonical page template

:sig
<one or more real C++ signatures, exactly as declared>

:params
<name> : <what it is>
return value : <what comes back>

:content
<Usage-first prose. What it does, when to use it. 2–5 tight sentences.>

:example
<runnable UCE code that print()s something illustrative>

:see
><area>
<closest sibling API slugs>

Optional short trailing note in :content for membrane/PHP-JS equivalence — one line, not a section. No :title unless it differs from the derived label.

Setup (host, one-time, before content work)

ssh root@10.4.2.110 'cd /Code/uce.openfu.com/uce && mkdir -p site/doc/examples/_gen && chown -R www-data:www-data site/doc/examples/_gen && chmod 775 site/doc/examples/_gen'

Phase 2 — Content sweep (batched by area; one area = one reviewable batch)

For each area file in site/doc/areas/ (string, sys, types, sqlite, mysql, memcache, session, websocket, task, time, uri, regex, ob, markup, socket, noise, runtime), bring every listed page to the canonical template:

Convert the 31 stubs to full structured pages.
Add a live :example to every page missing one (≈134), each verified to render real output.
Repair :see — area link + sibling links on every page; demote membrane / PHP-JS filler to a one-line note.
Cull dead pages — remove concat.txt ("Removed. Not a current API") and audit internal-only helpers (e.g. json_consume_space) for removal; also remove culled slugs from the relevant areas/*.txt.

Per-batch bar: every touched page renders cleanly, its example produces real output, and the suite stays green.

Phase 3 — Gate

Add a site/tests/cli_runner.uce regression test that renders every ?p= page and asserts HTTP 200, no error/trap marker, and (for pages with :example) presence of a non-error Output block.

Full host gate (this is the ONLY place builds/tests run — the sshfs mount is edit-only, no WASI SDK on the client):

ssh root@10.4.2.110 'cd /Code/uce.openfu.com/uce && bash scripts/build_core_wasm.sh && bash scripts/build_linux.sh && systemctl restart uce.service && sleep 3 && bash scripts/run_cli_tests.sh --include-wasm-kill'

Expect the current 91 to grow by the new doc gate(s), 0 failed.

Hard rules (non-negotiable)

NEVER git commit/push/tag. Not pi, not its subagents, not anyone. Leave a clean working tree and report.
Always run the real host gate (bash scripts/build_core_wasm.sh && bash scripts/build_linux.sh && systemctl restart uce.service && ...) and trust only its output. g++ -fsyntax-only / client-side builds do NOT count — there is no WASI SDK on the client and the doc unit must actually render.
Sub-delegation model is exactly gpt-5.3-codex-spark.
Verify the example mechanism end-to-end on the host BEFORE authoring content against it — content written against an unproven mechanism is wasted.

8.4 KiB Raw Blame History Unescape Escape

DOCS-TODO — /doc documentation overhaul