uce/DOCS-TODO.md

Completed /doc documentation overhaul (historical plan)

This June 2026 plan is complete and is retained only as implementation history. It is not the current task queue and its one-off execution rules do not govern new UCE work. Current documentation has 269 rendered pages and is covered by the sharded doc gate in scripts/run_cli_tests.sh.

The original briefing follows. 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

1. 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.
2. 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.
3. Cross-link. Every page's :see references its area (>area) and its closest sibling APIs, so the reader is never left to search alone.
4. 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:

1. Convert the 31 stubs to full structured pages.
2. Add a live :example to every page missing one (≈134), each verified to render real output.
3. Repair :see — area link + sibling links on every page; demote membrane / PHP-JS filler to a one-line note.
4. 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.

Historical execution rules (no longer active)

These rules applied only while the overhaul was being carried out in June 2026. They are preserved to explain that work and must not override current repository or operator instructions.

• 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.