Folio About Is Schema-Bound YAML

Note — 2026-09-22: an About tab is not the About face (GB-310)

The Control Panel's About fold-out became an About tab beside Ask Goldie (see the shell's amendment). It shows the same name, guide and tags the fold-out showed, as plain fields writing the same typed members. It is not the YAML face this record retired: no YAML is drawn, typed or edited on it.

Amendment — 2026-09-10: the format survives without a face (GB-221)

The About face is retired. The schema-bound YAML declaration survives as the language Goldie reads and writes, and as a file a person can download; it is no longer a side of the card. Owner ruling 2026-09-10, after the Folio concertina (GB-220): a folio's name is edited on its header and its Guide and Tags in the fold beneath the title row, so the face's only remaining editable value was the handle — a display hint, since references bind to stable ids — and access and classification were shown there read-only. A form that repeats what the card now shows on its lid earns nothing.

In plain terms: the record card on the back of every folder is gone. What it said is now on the folder's label and inside its lid, and the file format it was written in is still what the assistant speaks and what you get when you download the folder's details.

What goes and what stays:

The rest of this record stands as the history of the face's grammar, and as the contract for the format: locked keys, typed values, canonical order, atomic writes. Where it says "About renders" or "the About face", read "the declaration, as Goldie and the download see it".

Decision (2026-08-20, face retired 2026-09-10)

Every Folio has a reading face and a schema-bound YAML declaration. The declaration looks like YAML but behaves like a schema-bound contract: keys and punctuation are locked, while each authored value keeps its type. Until 2026-09-10 the declaration was also a second face of the card; see the amendment above.

The two answer different questions:

Module, Document, and later Project are structural Folios. Their reading faces exist for builders, but the Folios themselves remain hidden in the read-only document view. Guide is the readable structural note that always occupies that face. Module Contains remains derived from the blocks pinned to the module; it is not a second authored list.

A Folio header discloses only that Folio's own fold. Closing a Document hides its fold but never its Module Substacks. Closing a Module hides its fold but never its Block Substacks. The Substack Portal remains rendered in either state; structural containment is not subordinate-content disclosure.

cks. The Substack Portal remains rendered in either state; structural containment is not subordinate-content disclosure.

One Guide, two projections

Guide is one authored fact. The fold renders it as readable editable text; the declaration renders the same value beneath the locked guide: | key. Editing the fold, or Goldie writing the declaration, writes the same typed value. Neither projection stores a copy of the other, so an accepted user or agent edit cannot leave them disagreeing.

This applies at Block, Module, and Document tier. A future Project guide follows the same rule if Project adopts that field.

YAML is the visual grammar, not a text-editing permission

About exposes the relevant authored schema in canonical YAML order. It keeps YAML's indentation, keys, colons, sequence marks, and block-scalar markers so a person or agent can read the declaration in the same language used at the authoring boundary. That resemblance does not make the document a freeform code editor.

• Keys are locked at every depth. They name stable schema fields and cannot be inserted, renamed, reordered, or deleted by editing text.

• Authored values are editable according to their schema. Text, multiline text, enums, booleans, numbers, optional values, maps, and sequences receive controls that preserve their type and constraints.

• Read-only or derived values remain visibly read-only when a Folio chooses to expose them. Mutability is declared by the schema, not inferred from the fact that a value is visible.

• Copy YAML serializes the current typed declaration canonically. Whitespace and comments are not separate stored facts.

• An edit is atomic. Validation succeeds for the complete proposed declaration before any underlying columns change.

• An accepted edit is durable and immediately becomes the displayed declaration. It survives a face switch, component remount, refreshed snapshot, and page reload. This includes the complete data-block fields: payload; parsing a value without writing its canonical storage column is not an accepted edit.

• Container keys fold. A key holding other things — a map, or a block scalar — carries a disclosure chevron after the key, and folding it hides its contents. A collapsed key shows nothing beside the chevron: no count, no summary, no preview of what is hidden. Scalar keys have nothing to fold and carry no chevron. The block-scalar indicator (|) appears only while the block is open, so a folded row carries one mark rather than two.

  In plain terms: the sections of the declaration collapse like schedules in a document, and a closed section says only its own name.

The existing Block About ConstrainedValues prototype is the visual precedent: quiet locked keys, values beginning directly after their YAML punctuation, typed menus for closed values, multiline block scalars, inline validation, and canonical Copy YAML. Its interaction grammar is promoted; its Block-specific, hand-written story implementation is not.

Agent edits use the same schema

An agent may propose changes only to schema paths admitted for that Folio and the current authority. It cannot gain permission to create or rename keys by returning YAML text. The proposal is validated against the same typed contract as a direct edit, then projected into About as value-level differences. Accept applies the complete validated change atomically; reject applies nothing.

Canonical YAML remains useful as agent context and as the portable authored representation. The mutation boundary nevertheless receives typed values or a canonical source that is parsed into the same typed model before it can write.

Composition boundary

Stack remains neutral visual furniture. It owns rows, sizing, palette, selection, the Control Panel slot, and the Substack Portal; it knows nothing about YAML, Folio schemas, agents, or persistence.

The Folio family owns the reusable About rendering grammar. Each Folio kind adapts its domain schema, current values, permissions, canonical serializer, write operation, and proposal operation to that grammar. Adding Project should therefore add another adapter, not a Project branch inside Stack and not a copy of the Block editor.

Every Folio uses the same Control Panel composition and G trigger. Block and Module may mount their scoped conversation in the agent region. Document keeps the same region and geometry but displays a permanent notice directing the person to the Inspector for work across the full document; it never mounts a second document conversation.

Consequences

• The unrestricted editable textarea in the current shared YAML projection is temporary presentation infrastructure, not the target About editor.
• Block, Module, and Document codecs must expose their complete relevant authored schemas rather than three unrelated YAML-shaped projections.
• Opening a Document Control Panel must join the same one-open-Folio-panel state used by Block and Module; adding a third independent state cell would restate one rule again.
• Document and Module disclosure state cannot gate their Substack Portals. Tests must distinguish hiding the Folio's own face from hiding descendants.
• Ordering remains structural where the authoring grammar already defines it by sequence position. An About editor does not invent a second editable ordering field.
• Project joins only when its real schema and containment behavior are settled. The family composition is ready for it without speculative Project fields.

Settled by the owner on 2026-08-20 after review of the unified Stack commits and the surviving schema-aware Block About prototype.

Amendment — 2026-08-25: About's grouping is a reading, not the storage shape

About may gather stored facts under a display key that no column shares. Grouping on the About face never propagates into the storage columns, and columns are never renamed to match a grouping.

The occasion was the owner's ruling that About should read as a small set of foldable objects — identity, display, flow, tags — rather than one flat run of keys, and the follow-up question it prompted (verbatim): "Longer term, should fields be named eg identity.label so yaml display matches the data structure? I assume a field name change is required?"

No rename is required, and none is permitted by this decision. The facts grouped under identity: deliberately do not share storage and must not be forced to:

• label and handle sit on the blocks row — permanent, one per Folio, unchanged across every version.
• guide sits on the blockVersions row — rewritten with each new version.

identity: is therefore a reading that gathers facts of different lifetimes onto one page, which is exactly what a declaration face is for. A literal stored identity.guide column would force the guide to stop being versioned — a behaviour change wearing a cosmetic rename. This restates, one level up, what the top of this record already says: About looks like YAML but is a schema-bound interface over typed columns spanning more than one table.

In plain terms: the matter number and title are printed on the file cover and never change; the instructions memo is filed inside the current brief and is replaced each redraft. A cover sheet printing all three under one "Identity" heading is a sensible cover sheet — but you would not therefore glue the memo to the cardboard.

What guarantees the face and the data agree

Not matching names — one facts-builder per Folio tier that both the rendered rows and Copy YAML read. That is the existing mechanism (blockAboutFields, moduleAboutFacts, documentAboutFacts), and any new grouping goes inside it. Two builders for one face, or a display shape assembled separately from the copied source, is the drift this guards against — the same one-source-of-truth rule that forbids a second stored copy of a projected name.

Where the permission stops: re-parent, never dissolve or rename

Grouping may re-parent a stored fact — show order beneath flow: though the columns are siblings. It may not dissolve that fact's own container, nor rename its keys for readability.

Settled by the owner on 2026-08-25 against a live example. Showing the module's ordering under flow: puts position three levels deep (flow.order.position), and two flatter shapes were on the table: flow: { condition, position, sibling_max }, dropping the order container the columns have; and flow: { condition, position: 2, of: 5 }, which reads the way a person actually says it. Both were refused in favour of keeping order as the container.

The reason is where the line falls, not how deep the nesting gets. A re-parented fact is still recognisably the stored fact, so a reader can carry what they see back to the data. Dissolve its container and the pair stops declaring itself a pair; rename sibling_max to of and the face is using a word the data has never heard. Each step is defensible alone, and together they turn About from a view of the record into a paraphrase of it — and a paraphrase is the second copy this codebase spends its rules preventing.

In plain terms: a summary sheet may group the clauses under headings of its own. It may not merge two clauses into one, or restate them in words the deed does not use — at that point the reader is no longer looking at the deed.

And the depth costs nothing, because it is already the established shape (owner, 2026-08-25). display has rendered three keys deep since it was written — display › numbering › headings — so flow › order › position matches the face's existing pattern rather than setting a new precedent. The argument for flattening rested on an exceptionalism that does not survive looking at the neighbouring key.

(As argued on 2026-08-25 this cited a second three-deep example, display › surfaces › form. That key retired the same day — see One venue — and the argument stands on numbering alone.)

The one real cost that remains is the occasional key reading like storage rather than English — sibling_max over of. That is the cheaper mistake: a clumsy name can be fixed in the column, where fixing it is one change and stays true everywhere, while a display-only alias is a second name from the day it ships.

Consequences

• A grouping key on the About face needs no column, no validator, and no migration. Adding or resequencing one is presentation work.
• Depth is not a reason to flatten. Three keys deep is the face's normal register, not its limit — display › numbering › headings has been there from the start. If a group nests uncomfortably deep, that is evidence about the grouping choice or the stored shape, not licence to drop a level from the display.
• The reverse does not follow: a stored fact still may not be invented to serve a grouping.
• Empty is not the same as absent, and only absent is omitted (owner, 2026-08-25). A group whose column exists but currently holds nothing is shown, empty — that is the same rule display has always followed by writing start_level: unset and every unset numbering flag, because "a record of only the set values shows what is on but never what could be". A group with no column behind it at any tier is omitted, because rendering it tells the reader the Folio has a field it does not have. The first is an empty drawer; the second is a label on a drawer that was never built.
• A proposed column rename justified by "the YAML shows it nested" is refused under this record. If storage genuinely should change shape, that is a schema decision argued on storage grounds — lifetimes, atomicity, query paths — and carries its own migration.

Settled by the owner on 2026-08-25, in the session that raised GB-139.