oficina / docs Public

Write the class vocabulary, and record the release gap

Reversing what r2 said about markup, after checking origin/main rather than
a local checkout. Three corrections, one of which was mine twice.

I reported that ui.ThemeCSS did not exist. It does -- main:ui/ui.go:309. I
was reading a vault-client checkout sitting at v0.19.0-3-gae9a1c0 and
reported the past as the present. The Fable review made the same mistake
and I repeated its conclusion without checking the tree either of us was
on.

The review also said the attribute grammar lives on unmerged
design-system-v2 branches. It lives nowhere: not in the release, not on
main, not on that branch. It is a ruling with no code and no date.

So r2's instruction -- write attributes, carry interim styling until they
ship -- was waiting on something unstarted. Docs writes class="rst-*"
instead, which is what ui styles and what ~585 call sites use, and
migrates mechanically alongside the framework when the grammar lands. A
parallel styling implementation held indefinitely against an unstarted
target is the worse trade.

Underneath all three is one gap: a spec ruling, code on main, and code in
the latest release are three different things, and reading one tells you
nothing about the other two. v0.19.0 was tagged 2026-08-24 and main is 17
commits ahead of it, so `go get` today gives an app none of the themes,
shells or locales the design-system spec spends its length describing.
§10.1 is now a table of what is released, what is on main, and what is
ruled only. Docs pins a main pseudo-version until a release exists, and
§15 tracks that.

Two traps recorded for whoever checks next: this repo squash-merges, so
git branch --merged says nothing useful about whether work landed --
compare content, not ancestry. And cite origin/main explicitly, because a
local checkout may be sitting on a feature branch at a tag.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011F5CivVm4CmL9ByfSSAaXA

Paul Campbell pushed by paul@keymail.dev 1 month ago 82961a2768521ab9493d7bdf446f3d20164a443a parent 14a3c11

2 files changed, +59 −20

AGENTS.md +15 −3
docs/superpowers/specs/2026-08-30-docs-design.md +44 −17

Intent

full ledger: agents-md-and-cadence

diff --git a/AGENTS.md b/AGENTS.md

index 91cc34f..bd04f1d 100644

--- a/AGENTS.md

+++ b/AGENTS.md

@@ -154,9 +154,21 @@ one session's question exposing another's bug.

## Conventions that are already settled

-- **Markup uses the bare `rst-*` attribute grammar**, not the `class="rst-*"`

- vocabulary — the latter is mid-migration and writing it now means writing

- the losing spelling.

+- **Markup uses the `class="rst-*"` vocabulary.** Reversed 2026-08-30 after

+ checking source. The bare-attribute grammar (`<div rst-inspector>`) is a

+ ruled future direction that exists in **no tree** — not in the release, not

+ on `main`, not on any branch — and it has no date. The class vocabulary is

+ what ships, what `ui` styles, and what ~585 call sites in rastrillo use.

+ Writing attributes now would mean maintaining a parallel styling

+ implementation indefinitely; writing classes means one mechanical migration

+ alongside the framework's own.

+- **Check `origin/main`, not your checkout, before citing rastrillo.** A

+ spec ruling, code on `main`, and code in the latest release are three

+ different things. `v0.19.0` (2026-08-24) is 17 commits behind `main` and

+ lacks the themes, shells and locales the design-system spec describes, so

+ `go get` alone will not give you them. Note also that this project

+ squash-merges, so `git branch --merged` reports nothing useful about

+ whether work has landed — compare content, not ancestry.

- **Re-copy `tokens.css` deliberately on every rastrillo upgrade.** It is

frozen into `static/` at scaffold time while the partials upgrade with the

module. `rastrillo doctor` will make this mechanical; until it lands it is

diff --git a/docs/superpowers/specs/2026-08-30-docs-design.md b/docs/superpowers/specs/2026-08-30-docs-design.md

index b12eba2..b25a060 100644

--- a/docs/superpowers/specs/2026-08-30-docs-design.md

+++ b/docs/superpowers/specs/2026-08-30-docs-design.md

@@ -61,6 +61,7 @@ in exchange for a purity the spec was congratulating itself on.

| 2 | **Sealed at rest**; the running instance holds the DEK, so the server can compute. | 08-30 |

| 3 | **Yjs.** JS `yjs` in the browser, Rust `y-crdt` on the server, fixtures as the contract. | 08-30 r2 |

| 4 | **ProseMirror**, vendored as a prebuilt bundle. Re-examined against Lexical after review and kept — see §6.5. | 08-30 |

+| 16 | **Markup uses `class="rst-*"`**, not the bare-attribute grammar, which exists in no tree. | 08-30 r2 |

| 5 | **Engine owns page geometry; the browser owns lines.** | 08-30 r2 |

| 6 | **Go + rastrillo for the app; one Rust crate** (layout + server-side CRDT) via wazero. | 08-30 r2 |

| 7 | **DOCX: model a real feature set, degrade loudly.** | 08-30 |

@@ -491,23 +492,47 @@ a page has different requirements from an admin screen. **The thing to watch

is drift in the chrome**: if you find yourself copying a partial and editing

three lines, propose it upstream instead.

-### 10.1 What is shipped, and what is not — a correction

+### 10.1 Three states, not two — and the release gap

-Revision 1 treated the design-system spec as a shipped dependency. Verified:

-`ui.TokensCSS()` exists (`ui/ui.go:192`). **`ui.ThemeCSS(name)`, `Pair` and

-the allocation entry point do not exist in shipped code** — they are in the

-design-system spec, on unmerged branches. The shipped `ui` documents and

-styles the `class="rst-*"` vocabulary.

+Revision 1 treated the design-system spec as shipped code. Revision 2 first

+corrected that against the wrong tree. Both errors have the same root: **a

+spec ruling, code on `main`, and code in the latest release are three

+different things**, and reading any one of them tells you nothing about the

+other two.

-So revision 1's instruction — "never the `class="rst-*"` vocabulary, writing

-classes now means writing the losing spelling" — is inverted *today*: the

-bare-attribute grammar is currently the unstyled one.

+Verified against `origin/main` and `v0.19.0`:

-**The position: build against the attribute grammar, and treat the

-design-system v2 merge as a dependency with a date, not an assumption.**

-Until it lands, Docs carries its own minimal styling for the attribute

-spelling and deletes it on merge. This is recorded as an open dependency in

-§15 rather than buried.

+| Symbol | State |

+|---|---|

+| `ui.TokensCSS()` | Released (`v0.19.0`) |

+| `ui.ThemeCSS(name)`, `ThemeNames()`, `Layout(name)`, `LayoutNames()` | **On `main` only** — `main:ui/ui.go:309` etc.; absent from `v0.19.0` |

+| `Pair`, the allocation entry point | **Ruled only.** In no tree |

+| The bare-attribute grammar (`<div rst-inspector>`) | **Ruled only.** In no tree, no branch, unstarted |

+**`main` is 17 commits ahead of `v0.19.0`, which was tagged 2026-08-24.** An

+app that runs `go get` today gets a rastrillo with none of the themes, none

+of the shells and none of the twelve locales — most of what the

+design-system spec describes. Docs therefore pins a `main` pseudo-version

+until a release carries them, and §15 tracks that as a dependency on

+somebody cutting one.

+*(Two traps for whoever checks this next. The repo squash-merges, so `git

+branch --merged` reports nothing useful about whether work has landed —

+compare content, not ancestry. And a local checkout may sit on a feature

+branch at a tag; cite `origin/main` explicitly or you will report the past.)*

+### 10.1.1 Markup uses the class vocabulary — reversed

+Revision 2 said to write the bare-attribute grammar and carry interim

+styling until it shipped. **Reversed**, because the thing being waited for is

+unstarted rather than in flight and carries no date.

+Docs writes `class="rst-*"`. That is what `ui` styles today and what ~585

+call sites in rastrillo use. When the attribute grammar ships, Docs migrates

+mechanically alongside the framework's own call sites — the same change,

+done once, by whoever automates it. The alternative was a parallel styling

+implementation maintained for an unbounded period against a target nobody

+has started.

`tokens.css` is frozen into `static/` at scaffold time while partials upgrade

with the module, so re-copy it deliberately on every rastrillo upgrade until

@@ -691,9 +716,11 @@ thumbnails all fall out of it.

and would fail our own gate (§12); decrypting the corpus per query is

O(corpus). Title and metadata search ships; full text waits for a design,

not for a decision.

-3. **Design-system v2 is a dated dependency, not an assumption** (§10.1).

- Docs carries interim styling for the attribute grammar and deletes it on

- merge.

+3. **rastrillo needs a release** (§10.1). `main` is 17 commits ahead of

+ `v0.19.0` and carries the themes, shells and locales Docs depends on.

+ Until one is cut, Docs pins a `main` pseudo-version — workable, but a

+ pinned pseudo-version is not a dependency anyone should ship on.

+ `ui-guidelines-52` is raising it; two apps hit it in one afternoon.

4. **The identity-assertion helper** — filed jointly with Sheets, pending

Paul's go-ahead to open it on the rastrillo GitHub repo.

5. **`.amadan/ci.d/10-gate`** arrives with the first code branch.