// The WeaveLang reference, authored as a weave.
// Each unit is a complete account of everything below it at its own resolution:
// complete at the level of fact, and deliberately silent at the level of mechanism,
// because that silence is what the reader descends for.

weave "weavelang" kind document {
  title "WeaveLang — meaning at any resolution"

  meta theme.mode "dark"
  meta theme.bg "#0f131b"
  meta theme.paper "#171c26"
  meta theme.ink "#dee5f0"
  meta theme.accent "#d9a441"
  meta theme.muted "#8b94a6"
  meta theme.frame "hairline"
  meta theme.shadow "soft"
  version "0.3"

  summary "The WeaveLang 0.3 reference, expressed as a weave. Its reader is someone who
           will implement or author WeaveLang — a parser, a renderer, a generator, or a
           person writing a weave by hand. Its purpose is to state what the language is,
           what each construct means, and what makes one unit a complete and true account
           of everything below it. That reader and that purpose are the relevance
           criterion every summary in this file was written against (§13 E3)."

  source weavelang kind document.spec {
    uri      "https://weavelang.org/reference.md"
    title    "WeaveLang Reference"
    revision "0.3"
  }

  unit wl kind document.language "The WeaveLang language" {
    ref "WeaveLang"
    name "WeaveLang"
    meta icon "🧵"

    summary "One file, one bounded subject, answered at the resolution a reader asks for.
             Five constructs declare everything the language declares — and depth is only
             nesting, material is only its parts in order, and a part is written,
             described, or named where it lives. Everything the core refuses to decide
             rides a `kind` string, props, meta and a convention nothing enforces.
             Nothing in the file says how to read it: the notation normalises spelling and
             never saying, a view is a tool's query, and what makes a level true of what
             is below is law."

    collapsed_summary "One bounded subject as nested units whose material is written out
                       verbatim or described in a sentence, in the same tree — so one file
                       answers at whatever resolution a reader asks for, and what makes a
                       unit true of everything below it is law."

    preview_summary "Inside, ten parts: the compressed-corpus thesis; the five constructs;
                     depth; material, written or described; material named and pinned
                     elsewhere; the razor and two open mechanisms; conventions; the
                     notation and its canonical JSON; what a parser, validator, renderer
                     and generator each promise; and the authoring law."

    content face.bullets
      - One bounded subject, answered where the reader stops — and nothing skipped was load-bearing ([the thesis](#wl.subject)).
      - [Five constructs](#wl.constructs) carry everything; every domain word is a `kind` string on top of them.
      - [Depth](#wl.depth) is nesting, and [material](#wl.material) is a unit's parts in order — written, described, or [named elsewhere](#wl.named).
      - What the core declines to decide rides [props and meta](#wl.weakness), under [a convention nothing enforces](#wl.conventions).
      - The file holds no view: [tools](#wl.tools) compute one, over [one notation](#wl.notation), against [one authoring law](#wl.authoring).
    end content

    content markdown
      | construct | what it is for |
      | --- | --- |
      | [`weave`](#wl.constructs.weave) | the file, and the one bounded subject it is about |
      | [`unit`](#wl.constructs.unit) | any meaningful thing; it nests to any depth, and may hold material |
      | [`content`](#wl.material.literal) | a literal part of a unit's material — or [a pinned name for material kept elsewhere](#wl.named.naming) |
      | [`relation`](#wl.constructs.relation) | a connection between two units that containment cannot express |
      | [`source`](#wl.constructs.source) | the origin named material was read from, pinned once per origin |

      Nothing else is declared. Every domain distinction — a Kubernetes pod, a character
      arc, a normative MUST, a Go struct field — is a [`kind` string](#wl.conventions.open_kinds)
      on a unit or a relation, and the core never learns what any of them mean.
    end content

    unit wl.subject kind document.thesis "One subject, any resolution" {
      ref "1, 1.1, 1.2, 16"
      name "The subject"
      meta icon "🔭"

      summary "WeaveLang exists to express meaning at any degree of nuance: one weave is
               one bounded subject, nested so that a reader stops at the depth they asked
               for and loses nuance rather than a fact. One decision about objects buys
               that — a part whose material is present and a part given only a sentence
               are the same kind of thing in the same tree. Because the two mix freely,
               compression costs the reader nothing, self-containment follows rather than
               being arranged for, and five statements are the whole language."

      collapsed_summary "A weave is one subject held at every resolution at once: written
                         parts and described parts sit in the same tree, so a single file
                         answers a reader at the depth that reader asked for, and every
                         other mechanism in the language serves that."

      preview_summary "Inside: the nested world and the promise that makes stopping safe;
                       the one property that lets a written part and a described part share
                       a tree; what self-containment means and the single trade that gives
                       it up; and the five-line creed."

      content face.bullets
        - A reader stops where they asked and loses nuance, never a fact — [the nested world](#wl.subject.resolution).
        - Written and described parts are one kind of object in one tree — [the central property](#wl.subject.compression).
        - Write every part out and the file IS its subject — [self-containment](#wl.subject.self_contained).
        - Five constructs · seven symbols · no enums in the middle — [the creed](#wl.subject.creed).
      end content

      content diagram
        presence of material is the ONLY difference between two parts
              │
              ├──► a corpus compressed exactly where it costs nothing
              │
              ├──► an unfinished weave is already a working plan —
              │    every described part is a brief, and the depths
              │    standing above it are what that brief must satisfy
              │
              └──► write every part and the file IS its subject
                         │
                         └─ name the material instead: same meaning,
                            different storage, and the file alone
                            no longer reads

        five statements · seven symbols · no enums in the middle
      end content

      unit wl.subject.resolution kind document.claim "The nested world" {
        ref "1"
        name "Resolution"
        meta icon "🔍"

        summary "WeaveLang's stated purpose is one thing: expressing meaning at any degree
                 of nuance. A weave is a nested world of meanings, and each depth is
                 complete enough to explore on its own — an account, never a table of
                 contents for the depth beneath it. The descent ends in the material
                 itself. The reader asks for a resolution, the weave answers there and
                 stops, and the guarantee that makes stopping safe is stated negatively:
                 nothing that was skipped was load-bearing."

        collapsed_summary "A weave is meaning nested in depths, each complete on its
                           own and ending in the material itself; the reader asks for a
                           resolution, the weave stops there, and nothing skipped was
                           load-bearing."

        preview_summary "Inside: §1 verbatim — the purpose sentence, the nested worlds and
                         the negative guarantee — beside a drawing of worlds inside worlds
                         ending at the verbatim paragraph, where a reader may stop at any
                         border and hold no false belief."

        content face.diagram
          a world ─▶ a world inside it ─▶ the material itself
             each one complete enough to explore on its own
          the reader names the depth; the weave answers and STOPS
          stopping costs nuance · it never costs a fact
        end content

        content markdown
          WeaveLang is a human-authorable and machine-readable language for expressing
          meaning at any degree of nuance.

          A weave is a nested world of meanings. Each depth is complete enough to explore
          on its own. Going deeper reveals worlds inside worlds, and the deepest depth is
          the material itself — the verbatim paragraph, the exact clause, the working code.

          The reader asks for a resolution; the weave answers at that resolution and stops.
          Nothing that was skipped was load-bearing.
        end content

        content diagram
          ╭─ a world ────────────────────────────────────────────╮
          │  complete enough to explore on its own               │
          │                                                      │
          │  ╭─ a world inside it ─────────────────────────────╮ │
          │  │  complete enough to explore on its own          │ │
          │  │                                                 │ │
          │  │  ╭─ the deepest depth ────────────────────────╮ │ │
          │  │  │  the material itself: the verbatim         │ │ │
          │  │  │  paragraph, the exact clause, the code     │ │ │
          │  │  ╰────────────────────────────────────────────╯ │ │
          │  ╰─────────────────────────────────────────────────╯ │
          ╰──────────────────────────────────────────────────────╯

          a reader may stop at any border and hold no false belief
          what stopping costs is nuance · what it never costs is a fact
        end content
      }

      unit wl.subject.compression kind document.property "The central property" {
        ref "1.1"
        name "Compression"
        meta icon "🗜"

        summary "This is the central property of the language: a weave may be written out
                 in some places and described in others, and the two live in the same
                 structure. Nothing marks the difference except whether material is
                 present — no flag, no second object, no separate region of the file — so
                 a reader moving down the tree crosses no seam. Two consequences run the
                 same way: bytes are dropped only where dropping them costs the reader
                 nothing, and every described part is a brief the depths above it already
                 specify."

        collapsed_summary "Written parts and described parts are the same kind of unit
                           in one tree, told apart only by whether material is present,
                           which is what makes a weave compressible where compression is
                           harmless and makes an unfinished weave a set of briefs."

        preview_summary "Inside: §1.1 verbatim on the central property, a table of the
                         mixture at four scales — a file, a struct, a function, a book —
                         and a drawing of a described part holding its exact place between
                         two written ones, with its own spec standing above it."

        content face.bullets
          - Nothing marks written from described except whether the bytes are present.
          - The mixture is chosen **part by part**, not file by file: three fields exactly, the rest described.
          - Compression is harmless by construction — bytes go only where losing them costs the reader nothing.
          - A described part is a **brief**, and the depths above it are the constraints it must satisfy.
        end content

        content markdown
          The central property: **a weave may be written out in some places and described in
          others, and the two live in the same structure.**

          A file can be spelled out line by line, except for the part that is conventional,
          which is one sentence instead. A struct can name three fields exactly and describe
          the rest. A function can have its hard branch written and its error path
          described. A book can carry three chapters verbatim and summarise the other
          thirty.

          Nothing marks the difference except whether material is present. A unit whose
          material is written is written; a unit whose material is only described is
          described. Both are units, both sit in the same tree, and a reader moving down
          the tree passes from one to the other without noticing a seam.

          That is what makes a weave a **corpus compressed where compression is harmless**.
          It is also what makes an unfinished weave buildable: everything described rather
          than written is a brief, and the depths above it are the constraints that brief
          must satisfy.
        end content

        content markdown
          The mixture is chosen part by part, not file by file, and it holds at every
          scale of material:

          | material | the part written | the part described |
          | --- | --- | --- |
          | a file | line by line | the part that is conventional, in one sentence |
          | a struct | three fields, exactly | the rest of them |
          | a function | its hard branch | its error path |
          | a book | three chapters, verbatim | the other thirty, summarised |

          A described part is a brief, and a brief is what [a writer fills](#wl.tools.fill)
          from the [literal parts on either side of it](#wl.material.composed).
        end content

        content diagram
          what is described is a brief · what stands over it is its spec

            unit  "what the whole subject is"      ─┐
              unit  "what this part has to do"      │  the constraints
                content  "…written…"                │  the brief has
                unit  "the error path"  ◄ BRIEF     │  to satisfy
                content  "…written…"               ─┘

          the brief is not a gap: it keeps its exact place among the
          parts around it, so the job arrives already specified
        end content
      }

      unit wl.subject.self_contained kind document.property "Self-contained by default" {
        ref "1.2"
        name "Self-contained"
        meta icon "📦"

        summary "When each part is written out, the file holds everything: a weave is not
                 an index of a subject stored elsewhere, it is the subject. The top and the
                 bottom hold different things — a claim above, and below it the author's
                 own paragraphs, or source that compiles, or the normative text. Because
                 the ends differ, the file reads two ways: downward it explains, upward it
                 justifies. A tool that already stores the material may name it instead,
                 giving up exactly one thing — the file alone no longer reads."

        collapsed_summary "With every part written out the file holds its whole subject
                           — the book, the compiling source, the normative text — so it
                           explains read downward and justifies read upward; a tool that
                           already stores the material may name it instead, with
                           identical semantics and different storage."

        preview_summary "Inside: §1.2 verbatim on the book, the software and the
                         specification weave; a drawing of one file read downward and
                         upward at once; and the comparison of holding the bytes against
                         holding a pointer to them."

        content face.table
          | a weave of | its top | its bottom |
          | --- | --- | --- |
          | a book | one sentence on what the book is finally about | the author's own paragraphs, in order |
          | software | what the system does | source that compiles |
          | a specification | the contract | the normative text |
        end content

        content markdown
          When each part is written out, the file holds everything:

          - A book weave contains the book. The top is one sentence about what the book is
            finally about; the bottom is the author's own paragraphs, in order.
          - A software weave contains the software. The top is what the system does; the
            bottom is source that compiles.
          - A specification weave contains the specification. The top is the contract; the
            bottom is the normative text.

          Read downward and a weave explains. Read upward from the material and it
          justifies.

          A tool that already stores the material — a code host, an archive, a corpus — may
          name it instead of embedding it (§4.5). The semantics are identical; only the
          storage differs.
        end content

        content diagram
          EXPLAINS                                          JUSTIFIES
             │  unit  "Freedom requires self-knowledge"         ▲
             │    unit  "Part One"                              │
             │      unit  "Chapter I"                           │
             ▼        content  "On an exceptionally hot         │
                                evening early in July…"         │

          downward · each depth says what its own parts amount to
          upward   · each line of material answers a claim that says
                     why it is there
        end content

        content markdown
          Self-containment is the one guarantee no reference can restore, which is why
          [naming material](#wl.named.naming) is a trade a tool may make and never a
          default the language prefers.

          | | the bytes are here | the bytes are named |
          | --- | --- | --- |
          | what a reader needs | this file | this file **and** its source |
          | reach | one file's worth of subject | a repository, a book, a recording |
          | semantics | identical | identical |
        end content
      }

      unit wl.subject.creed kind document.creed "The five-line creed" {
        ref "16"
        name "The creed"
        meta icon "📜"

        summary "The language reduces to five statements, and each is a ruling about what
                 may exist rather than a description of a feature: anything meaningful is a
                 unit, every non-containment connection is a relation, any nesting is a
                 depth, a unit's material is its parts in order between what is written and
                 what is described, and any domain is a string. Counted up that is five
                 constructs, seven symbols and no enums in the middle — a count kept low as
                 a bet, so that material nobody has woven yet still fits."

        collapsed_summary "Five statements are the entire language — unit, relation,
                           depth, material as ordered parts, domain as a string —
                           carried by seven symbols with no enums in the middle, kept
                           that small so that material nobody has woven yet still fits."

        preview_summary "Inside: the five lines verbatim, the sentence that gives the count
                         and the bet behind it, and a table pairing each ruling with the one
                         thing it rules out."

        content face.bullets
          - Five statements are the whole language: [unit](#wl.constructs.unit), [relation](#wl.constructs.relation), [depth](#wl.depth), [ordered parts](#wl.material.parts), domain as a string.
          - Each line is a ruling about what may EXIST, so each one rules something out.
          - Five constructs · seven symbols · no enums in the middle.
          - The count is a bet, not a taste: a small core is what lets unwoven material still fit.
        end content

        content txt
          Anything meaningful is a unit.
          Any connection that is not containment is a relation.
          Any nesting is a depth.
          A unit's material is its parts, in order: what is written, and what is described.
          Any domain is a string.
        end content

        content markdown
          Five constructs, seven symbols, no enums in the middle. The core stays small so
          that the unseen case — the material nobody has woven yet — still fits.
        end content

        content markdown
          Each line is a ruling about what may exist, so each one rules something out:

          | the ruling | what it rules out |
          | --- | --- |
          | anything meaningful is a [**unit**](#wl.constructs.unit) | a second object type for a chapter, a struct field, a normative clause, a running service |
          | every non-containment link is a [**relation**](#wl.constructs.relation) | a cause, a dependency or a contradiction smuggled into nesting |
          | any nesting is a [**depth**](#wl.depth.nesting) | a depth number an author has to declare and maintain |
          | material is [**parts, in order**](#wl.material.parts) | a described part that reads as a hole rather than a place |
          | any domain is a [**string**](#wl.conventions.open_kinds) | a domain distinction the core has to learn |
        end content
      }
    }

    unit wl.constructs kind document.model "The five constructs" {
      ref "2"
      name "Five constructs"
      meta icon "🧱"
      summary "The whole language declares five things and stops: `weave` the file,
               `unit` anything meaningful, `content` a literal part of material,
               `relation` what nesting cannot express, `source` a pinned origin. Every
               domain distinction — a pod, a MUST, a struct field — is a `kind` string a
               convention gives meaning, never a sixth construct. Four of the five open
               below as units of their own; `content` is treated with material instead.
               Three more open there too, and none is a construct: they are fields of
               `unit` whose reasons need their own account."
      collapsed_summary "Five declarable things — weave, unit, content, relation,
                         source — carry every subject, because every domain
                         distinction rides on a free `kind` string instead of on a new
                         construct."
      preview_summary "Inside: the `weave` header's seven fields; `unit`'s declaration
                       and eleven-field table; the handle a renderer falls back to; the
                       rule that its three summaries are three separate claims; `ref`,
                       the source name no tool parses; `relation`'s fields and `edge`
                       shorthand; and `source` pinning one origin."

      content face.bullets
        - `weave` opens the file, one bounded subject — [the header](#wl.constructs.weave).
        - `unit` names anything meaningful, in an eleven-field table — [the declaration](#wl.constructs.unit).
        - Three of those fields need their own account: [the handle](#wl.constructs.name), [why three summaries](#wl.constructs.summaries), and [`ref`](#wl.constructs.ref) — the one string a weave copies instead of interpreting.
        - `relation` carries what nesting cannot, from one unit to another — [the connection](#wl.constructs.relation).
        - `source` pins an origin once, inherited by everything under it — [the pin](#wl.constructs.source).
      end content

      content
        weave     the file: one bounded subject
        unit      any meaningful thing; nests to any depth; may hold material
        content   a literal part of a unit's material
        relation  a connection between units that is not containment
        source    a pinned origin, for material that is named rather than embedded
      end content

      content markdown
        | construct | what it declares | where it is treated |
        | --- | --- | --- |
        | `weave` | the file, and its one bounded subject | §2.1, below |
        | `unit` | any meaningful thing, at any depth | §2.2, below |
        | `content` | a literal part of a unit's material | §4, with material |
        | `relation` | a connection that containment cannot carry | §2.4, below |
        | `source` | a pinned origin, for material that is named | §2.5, below |

        Everything domain-specific — a Kubernetes pod, a character arc, a normative
        MUST, a Go struct field — is a `kind` string on a unit or relation, given
        meaning by a convention (§6). The core never learns what any of them are.
      end content

      content diagram
        weave ─────────────────────────────────────────────────┐
          unit ──────────────────┐  unit ───────────┐          │
            content  "bytes"     │    content       │          │
            unit ─────────┐      │    unit ─────┐   │          │
              content     ┘      ┘      …       ┘   ┘          │
                ▲                          ▲                   │
                └───── relation:  from ──▶ to ─────┘           │
                       the connection nesting cannot express   │
          source ── one per origin, pinned near the top ───────┘

        Down the page is depth, and it is nothing but nesting.
        Across the page is a relation, and it is every other connection.
      end content

      unit wl.constructs.weave kind document.construct "The weave construct" {
        ref "2.1"
        name "weave"
        meta icon "📄"
        summary "A weave is one file and one bounded subject. It opens with `weave`,
                 an id or title, an optional `kind`, and a brace; everything else —
                 one or more root units, since a single root is never forced, plus
                 any relations and sources — sits inside. The header's seven fields
                 are recommended, never required: they name the subject, its
                 provenance, its revision, and its terms of reuse. `model` earns a
                 field of its own because a reader who knows which model wrote the
                 summaries reads them differently."
        collapsed_summary "The outermost block — one file, one bounded subject —
                           holding root units, relations and sources, with seven
                           recommended provenance fields and none of them required."
        preview_summary "Inside: the declaration line, the sentence naming what a
                         weave holds, and a table of the seven recommended fields
                         with what each one fixes for a reader arriving cold."

        content face.bullets
          - One file is one bounded subject, holding root units plus any relations and sources.
          - Seven fields are recommended on the header; the core requires none of them.
          - `model` matters because a reader who knows which model wrote the summaries reads them differently.
        end content

        content
          weave <id-or-title> [kind <kind>] {
            ...
          }
        end content

        content
          Recommended fields: `title`, `summary`, `created_by`, `created_at`, `model`,
          `version`, `license`. A weave holds one or more root units, plus any relations and
          sources.
        end content

        content markdown
          The seven, and what each one fixes for a reader who arrives cold:

          | field | what it fixes |
          | --- | --- |
          | `title` | what this subject is called |
          | `summary` | what this subject is |
          | `created_by` | who or what produced this weave |
          | `created_at` | when they produced it |
          | `model` | which model wrote it, when a machine did |
          | `version` | which revision of the weave a reader is holding |
          | `license` | on what terms it may be reused |

          The core requires none of them. Provenance is a habit the header makes easy,
          not a rule it enforces.
        end content
      }

      unit wl.constructs.unit kind document.construct "The unit construct" {
        ref "2.2"
        name "unit"
        meta icon "🧩"
        summary "A unit is any meaningful thing — the language's one noun, with `kind`
                 naming what sort. It stands alone at its own resolution, sits in
                 parent context, and holds more units, material, or both. Declared as an
                 id, an optional kind, a title and a brace, it carries up to eleven
                 fields in five jobs. Two of the eleven argue for themselves
                 elsewhere: why three summaries rather than one shortened twice, and what
                 a `name` is for. Beyond the eleven, a domain need is a kind, a prop, or
                 a meta — never a twelfth."
        collapsed_summary "The language's one noun: whatever the subject is, it is
                           declared as a unit, so the shape defined here is the shape
                           every other block in a weave repeats."
        preview_summary "Inside: the declaration line, the eleven-field table naming
                         each field's job, and a diagram grouping the eleven into the
                         five jobs they divide into."

        content face.bullets
          - Eleven fields divide into five jobs: four display rungs, the source name, standing, the open remainder.
          - The declaration is an id, an optional kind, a title, and a brace — nothing more.
          - Anything a domain needs beyond the eleven is a `kind`, a `prop`, or a `meta` — never a twelfth field.
          - Two fields argue for themselves next door: [three summaries](#wl.constructs.summaries), and [the `name`](#wl.constructs.name).
        end content

        content
          A unit is any meaningful thing: a capability, a chapter, a requirement, an actor,
          a function, a struct field, a paragraph. It stands alone at its own resolution,
          sits inside parent context, and holds either more units, material, or both.
        end content

        content
          unit <id> [kind <kind>] "Title" {
            summary "What it means at this depth."
            ...
          }
        end content

        content markdown
          | Field | Job |
          | --- | --- |
          | `summary` | What the unit means when it is the active world. |
          | `collapsed_summary` | What neighbours need to know when it is only context. |
          | `preview_summary` | What the inside promises before it is entered. |
          | `name` | The unit's handle: one to three words, for when space cannot carry the title (§2.2.1). |
          | `ref` | The unit's own name in its source's numbering. Verbatim, opaque (§2.3). |
          | `content` | A literal part of its material (§4). |
          | `reveals` | Children that are not lexically nested (§3.2). |
          | `cites` | Other units whose material supports this one. |
          | `confidence` | 0–1. Low confidence must not render as fact. |
          | `props` | Typed scalar attributes (§5). |
          | `meta` | Repeatable free-kind annotations (§5). |
        end content

        content diagram
          unit <id> kind <kind> "Title" {
            summary  collapsed_summary  preview_summary  ┐ four authored rungs,
            name                                         ┘ longest to shortest
            ref                                          ── the source's own name
            cites  confidence                            ── standing of the claim
            props  meta                                  ── the open remainder
            reveals                                      ── children declared elsewhere
            content  "bytes"    ┐ material: the parts,
            unit  … { … }       ┘ in the order written
          }

          Eleven fields, five jobs. Only the last group is ordered: content blocks
          and child units interleave exactly as they are written.
        end content

      }

      unit wl.constructs.name kind document.rule "The display ladder" {
        ref "2.2.1"
        name "The handle"
        meta icon "🏷"
        summary "A title addresses the unit's subject directly, in two to five words,
                 never a sentence; the claim lives in the summary, because a claim cut
                 mid-way is garbage. `name` is what the unit is *called* — one to
                 three words, never one the unit's own vocabulary does not need;
                 one or two carry best. Both sit on a ladder of authored rungs that
                 text descends by substitution: a child's box carries the title, a
                 grandchild the name, below that the icon. `name` is optional; without
                 it a renderer truncates the title at a word boundary."
        collapsed_summary "A title addresses the subject in two to five words and the
                           claim lives in the summary; `name` is the one-to-three-word
                           handle below it, so a renderer that runs out of room
                           substitutes a shorter authored rung instead of truncating."
        preview_summary "Inside: the six-rung display ladder from `summary` down to a
                         mark, §2.2.1 verbatim with the `wl.depth` unit wearing its own
                         name, and the truncating fallback that `name` exists to
                         prevent."

        content face.bullets
          - A **title** addresses the subject in two to five words, never a sentence — the claim lives in the summary.
          - A **name** is what the unit is *called* — one or two words, three the ceiling, never the target.
          - It never spends a word the unit's own vocabulary does not need: "The broom", not "The broom anecdote".
          - Text descends by substitution — a child's box carries the title, a grandchild the name, below that the icon.
          - `name` is optional; without it a renderer truncates the title — the exact degradation it exists to prevent.
        end content

        content markdown
          A `title` addresses the unit's subject directly, in two to five words —
          "Getting Into Production", "The five-dollar day" — never a sentence. The CLAIM
          lives in the summary; a sentence-title makes every box, crumb, and menu pay
          for a clause its space cannot carry, and a claim cut mid-way is garbage. The
          title is the unit at its longest text rung, and it descends by substitution: a
          direct child's box carries the title where it fits whole; a grandchild carries
          the 1–2 word `name`; below that, the icon (§6.5). Every rung is authored; no
          rung is a truncation of the one above.

          `name` is the handle: what the unit is *called*, in one to three words — and the
          fewer the better. One or two words carry best: a name earns its keep in the
          smallest boxes a renderer draws, where a third word is usually the first thing
          that wraps. Three is the ceiling, not the target, and a name never spends a word
          the unit's own vocabulary does not need ("The broom", not "The broom anecdote").
        end content

        content weave
          unit wl.depth kind document.mechanism "Depth and its invariants" {
            name "Depth"
            meta icon "🪆"
            ...
          }
        end content

        content markdown
          It completes the display ladder. Each rung is a shorter **authored** field, so a
          renderer demotes by substitution and never by shrinking or truncating:
        end content

        content txt
          summary → collapsed_summary → preview_summary → title → name → a mark
        end content

        content markdown
          `name` is optional. Where it is absent a renderer falls back to `title` and may
          truncate it at a word boundary — the fallback is legal, and it is exactly the
          degradation `name` exists to prevent.
        end content

        content markdown
          The four authored rungs share one head noun phrase, which is
          [rule 7 of the generation contract](#wl.tools.write); a wordy name defeats the
          smallest boxes it exists for, which is rule 9. The three longer rungs are
          [three different claims](#wl.constructs.summaries), not one claim at three
          lengths, and `name` is the last of the four rather than a fifth summary.
        end content

        content diagram
          the ladder, longest to shortest — every rung AUTHORED

            summary            the account, once the reader is inside
            collapsed_summary  what a neighbour needs to ignore it
            preview_summary    what the inside promises
            title              the subject, in 2–5 words
            name               the handle          ◄ 1–2 words
            a mark             a dot, a glyph

          a renderer walks DOWN this ladder when space runs out:
          a child's box carries the title where it fits whole, a
          grandchild the name, below that the icon — substitution,
          never shrinking, except at `title`, where a missing `name`
          forces a cut at a word boundary
        end content
      }

      unit wl.constructs.summaries kind document.rule "The three summaries" {
        ref "2.2"
        name "Three summaries"
        meta icon "📝"
        summary "A unit carries three summaries because a reader meets it at three
                 different moments, and each wants a different true answer.
                 `preview_summary` is read from outside, deciding whether to enter,
                 and must say what the inside promises. `collapsed_summary` is read
                 by someone elsewhere holding this unit only as context, and says
                 what a neighbour needs to ignore it safely. `summary` is read by
                 someone already here, with this unit as the active world, and says
                 what it means at this depth. None is an abbreviation of another:
                 shortening one twice answers questions nobody asked."
        collapsed_summary "Three fields for three reading moments — preview_summary
                           decides whether to enter, collapsed_summary decides whether
                           to ignore, summary says what the unit means once inside —
                           and none of them is an abbreviation of another."
        preview_summary "Inside: the rule verbatim, a table pairing each field with
                         the reader's position and the decision it serves, and a
                         diagram placing the three summaries at three positions
                         around one unit in a tree."

        content face.bullets
          - Three summaries answer three different questions, not one question at three lengths.
          - Entering, ignoring, and reading in place are three separate decisions, each with its own claim.
          - None substitutes for another: shortening `summary` twice does not produce the other two.
        end content

        content
          The three summaries do three different jobs and are not abbreviations of each
          other. A reader uses them at three different moments: `preview_summary` decides
          whether to enter, `collapsed_summary` decides whether to ignore, and `summary` is
          what the unit means once inside it.
        end content

        content markdown
          | field | where the reader is standing | the decision it serves |
          | --- | --- | --- |
          | `preview_summary` | outside, looking in | whether to **enter** |
          | `collapsed_summary` | somewhere else, holding this as context | whether to **ignore** |
          | `summary` | here, with this unit as the active world | what it **means** at this depth |
        end content

        content diagram
               ancestor        collapsed_summary  ── safe to leave folded
                  │
              ▶ THIS UNIT      summary            ── the active world
                ╱      ╲
          child        child   preview_summary    ── the promise of the inside

          One unit, three readers, three positions. The same unit supplies a
          different line to each of them, and the lines are not the same claim
          at three lengths.
        end content
      }

      unit wl.constructs.ref kind document.construct "The ref field" {
        ref "2.3"
        name "ref"
        meta icon "§"
        summary "`ref` is the name material already carries in its own world, copied
                 unchanged. It is opaque to every tool — displayed, matched whole,
                 cited — but never parsed, sorted, or validated. That opacity lets
                 one field hold six numbering schemes without the core learning any
                 of them. Two arguments earn it a place: it is the only string that
                 cannot be wrong, since a misleading summary still leaves the copy to
                 check against, and it preserves a reader's habit of navigating a
                 genre by prediction. It is optional; material with no native
                 numbering has none."
        collapsed_summary "An optional verbatim copy of the material's own name — a
                           section number, a path and symbol, an act and scene —
                           displayed and matched whole but never parsed or sorted, and
                           the one string in a weave that cannot be wrong."
        preview_summary "Inside: the RFC example placing `ref` inside a real unit,
                         six numbering schemes side by side in one table, and a
                         second table fixing exactly what a tool may and may never do
                         with the string."

        content face.bullets
          - `ref` copies the material's own name — a section, a path, a clause — unchanged.
          - It is the only string in a weave that cannot be wrong: a copy, never an interpretation.
          - A tool may display it, match it, and cite it — never parse it, sort it, or validate its shape.
          - It is optional: material with no native numbering simply has none.
        end content

        content weave
          unit req.idempotency kind document.requirement "Idempotent methods" {
            ref "9.2.2"
            summary "A client may repeat GET, PUT, or DELETE without additional effect."
          }
        end content

        content
          ref "9.2.2"          ref "§5.3(b)(ii)"    ref "src/retry.go:RequestDirectives"
          ref "Act II, sc. 3"  ref "Art. 6(1)(f)"   ref "Table 4"
        end content

        content markdown
          One field, six numbering schemes the core has never heard of:

          | the string | the world it was copied out of |
          | --- | --- |
          | `9.2.2` | a standard's section numbering |
          | `§5.3(b)(ii)` | a statute's clause numbering |
          | `src/retry.go:RequestDirectives` | a codebase's path and symbol |
          | `Act II, sc. 3` | a play's act and scene |
          | `Art. 6(1)(f)` | a regulation's article |
          | `Table 4` | a document's own table numbering |

          The opacity is the whole mechanism. What a tool may and may not do with the
          string is fixed, and it is fixed the same way for all six:

          | a tool may | a tool may never |
          | --- | --- |
          | display it | parse it |
          | match it as a whole string | sort by it |
          | embed it in permalinks and citations | validate its shape |
        end content
      }

      unit wl.constructs.relation kind document.construct "The relation construct" {
        ref "2.4"
        name "relation"
        meta icon "↔"
        summary "A relation carries what containment cannot: causation, dependency,
                 support, rebuttal, sequence, a call across a boundary. It declares
                 like a unit — an id, an optional kind, a body — but its two required
                 fields are endpoints: direction runs `from` to `to`, and nothing else
                 encodes it, so swapping the fields reverses the claim. `kind` types
                 the connection, `label` is the edge's phrase; `summary` through
                 `meta` carry the rest. Exactly two endpoints, always; a further
                 participant rides `props`, never a third field. An `edge` line is the
                 same construct with no id and no body."
        collapsed_summary "A directed, kind-tagged, labelled connection between exactly
                           two units — from to `to`, and nothing else encodes
                           direction — with a one-line `edge` shorthand, extra
                           participants riding props, and no picture-drawing anywhere
                           in it."
        preview_summary "Inside: the field table, a diagram of the two endpoints and
                         why swapping them reverses the claim, the `edge` shorthand
                         and a props example, and a table fixing which of three
                         shapes fits which case."

        content face.bullets
          - `from` and `to` are the only required fields; direction runs one way, and nothing else encodes it.
          - `kind` types the connection; `label` is the short phrase a reader sees on the edge.
          - A relation always has exactly two endpoints; a third participant rides `props`, never a third field.
          - The `edge` line is the same construct with no id and no body.
        end content

        content
          A connection that nesting cannot express: causation, dependency, support,
          rebuttal, sequence, a call across a boundary.

          relation <id> [kind <kind>] {
            from  <unit-id>
            to    <unit-id>
            label "short phrase at this depth"
          }
        end content

        content markdown
          | Field | Job |
          | --- | --- |
          | `from`, `to` | The endpoints. Direction is `from` → `to`; nothing else encodes direction. |
          | `kind` | What sort of connection. Convention vocabulary. |
          | `label` | The short phrase a reader sees on the edge. |
          | `summary` | The complete meaning of the connection at its own depth. |
          | `preview_summary` | What the deeper explanation promises. |
          | `reveals` | A unit that explains this relation in more detail. |
          | `cites` | Units whose material supports the connection. |
          | `confidence` | 0–1. |
          | `props`, `meta` | Everything else. |
        end content

        content diagram
          from ─────────────── label ──────────────▶ to
            │                                        │
            └─ the end the claim starts at           └─ the end it lands on

          Swap the two fields and the claim reverses. kind, label, summary,
          confidence, props: none of them can put it back.
        end content

        content
          Shorthand, when a relation needs no id and no body:

            edge api -> db kind software.reads "reads user records"

          More than two participants ride `props`:

            relation incident_cause kind causal {
              from  event.deploy
              to    incident.invoice_delay
              label "a halved fleet could not drain the backlog"
              confidence 0.64
              cites [sig.queue]
              props { through "service.billing"  condition "backlog exceeded 10 minutes" }
            }

          Arrow shapes, endpoint markers, and layout are renderer concerns fed by `kind`
          (§6.4). The core does not describe pictures.
        end content

        content markdown
          Three shapes, one construct — and the arity never grows:

          | shape | when it is the right one |
          | --- | --- |
          | the `relation` block | the connection needs an id, a body, or a summary of its own |
          | the `edge` line | it needs neither an id nor a body |
          | a third participant in `props` | the connection really has more than two ends |

          A relation always has exactly two endpoints. The service a cause ran through
          and the condition it held under are attributes of the connection, not further
          ends of it.
        end content
      }

      unit wl.constructs.source kind document.construct "The source construct" {
        ref "2.5, 14.4"
        name "source"
        meta icon "📚"
        summary "A `source` is a pinned origin, needed only when a weave names
                 material instead of embedding it. It gives the origin an id, an
                 optional kind, and five fields: `uri`, `title`, `author`,
                 `revision`, `captured_at` — where it lives, what it is called, who
                 made it, which revision, and when it was read. One source per
                 origin, pinned once near the top, inherited by everything below it —
                 a rule about disagreement, not tidiness, since a revision repeated
                 on every leaf lets leaves drift and disagree."
        collapsed_summary "One block per origin — uri, title, author, revision,
                           captured_at — declared once at the top of a weave, because a
                           revision repeated on every leaf invites leaves that disagree
                           about which revision they read."
        preview_summary "Inside: a table of the five fields, a diagram contrasting
                         one pin against a repeated revision that drifts, and a
                         partial RFC 9110 weave narrated construct by construct —
                         including the one relation the example leaves dangling on
                         purpose."

        content face.bullets
          - Five fields pin one origin: `uri`, `title`, `author`, `revision`, `captured_at`.
          - One source per origin, pinned once near the top, inherited by everything below it.
          - Repeating a revision on every leaf invites leaves that disagree about which revision they read.
          - The RFC 9110 weave below pins one source and places four other constructs around it.
        end content

        content
          A pinned origin, needed only when material is named rather than embedded.

          source <id> [kind <kind>] {
            uri         "https://github.com/acme/app"
            title       "Original item"
            author      "Author"
            revision    "abc123def"
            captured_at "2026-06-25T10:00:00Z"
          }

          One source per origin, pinned once. Repeating a revision on every leaf invites
          leaves that disagree about which revision they read.
        end content

        content markdown
          | field | what it pins |
          | --- | --- |
          | `uri` | where the material lives |
          | `title` | what it is called |
          | `author` | who made it |
          | `revision` | which exact revision was read |
          | `captured_at` | when it was read |
        end content

        content diagram
          pinned once                        repeated on every leaf
          ┌─────────────────────────┐        ┌─────────────────────────┐
          │ source rfc              │        │ unit a  rev "abc123"    │
          │   revision "abc123"     │        │ unit b  rev "abc123"    │
          └──────────┬──────────────┘        │ unit c  rev "9f10e2" ◀──┼ drift
                     │ inherited             └─────────────────────────┘
                     ▼                         two answers to "which
          unit a   unit b   unit c              revision did we read?"
                                                — and nothing in the
          one answer, one place to edit         weave can be checked
        end content

        content weave
          weave "RFC 9110 — HTTP Semantics" kind document {
            source rfc kind document.spec {
              uri   "https://www.rfc-editor.org/rfc/rfc9110"
              title "HTTP Semantics"
            }

            unit contract kind document.spec "One shared meaning for HTTP messages" {
              summary "Defines methods, status codes, and header semantics shared by all
                       HTTP versions."

              unit req.idempotency kind document.requirement "Idempotent methods" {
                ref     "9.2.2"
                summary "A client may repeat GET, PUT, or DELETE without additional effect,
                         which is what makes automatic retry safe."
                content
                  A client MUST be able to repeat an idempotent request without additional
                  effect beyond that of the first request.
                end content
              }

              unit req.conditional kind document.mechanism "Conditional requests" {
                ref     "13"
                summary "A validator turns a request into a question about what changed."

                unit q.weak_etag kind document.ambiguity "Do weak validators satisfy range requests?" {
                  ref        "13.1.3"
                  summary    "The section constrains this; implementations disagree."
                  confidence 0.4
                }
              }
            }

            relation cond_needs_validator kind document.depends_on {
              from  req.conditional
              to    field.etag
              label "conditional requests are meaningless without a validator"
            }
          }
        end content

        content markdown
          What that example does show, construct by construct:

          - one `source`, pinned at the top and inherited by everything under it
          - `ref` numbers copied from the standard's own section numbering
          - a `content` block holding the normative sentence verbatim
          - `confidence 0.4` on the one unit where the standard is genuinely ambiguous
          - a `relation` reaching across the nesting, which containment could not carry

          What it does not show: `props`, `meta`, `reveals`, named material, and
          `outline` are all absent. And its one relation points `to field.etag`, a unit
          the example never declares. Under §9 that is an unresolved reference at the
          core level — the endpoint is dangling, and it is reproduced here exactly as
          the specification prints it rather than quietly repaired.
        end content
      }
    }

    unit wl.depth kind document.mechanism "Depth and its invariants" {
      ref "3"
      name "Depth"
      meta icon "🪆"
      summary "A unit's depth is the number of units it sits inside, plus one; nothing else
               records it, and nesting is the whole of depth. So depth is unbounded, local
               to a branch, and relative, and no depth is ever named. A child may also be
               reached by id rather than by its place in the tree. Because the language
               declares nothing beyond that count, only the author can make a level real,
               and the whole cost lands on two invariants: each depth must be useful by
               itself, and true of what sits below it."
      collapsed_summary "Depth is nothing but nesting — a count of enclosing units, uncapped
                         and unnamed — so two invariants the author must hold, useful-by-itself
                         and true-of-what-is-below, are the only things that make a level real."
      preview_summary "Inside: how a unit's depth is counted, unbounded, local and relative,
                       and why no depth is named; reveals, for a child declared elsewhere or
                       shared; and the two invariants — a whole answer at each depth, and a
                       summary true of what sits below it."

      content face.bullets
        - Depth is read off the braces, uncapped and unbounded — no field records it: [nesting](#wl.depth.nesting).
        - A child can be reached by id instead of by its place in the tree — [reveals](#wl.depth.reveals).
        - Each depth must be a whole answer the next depth refines, never rescues — [useful by itself](#wl.depth.useful).
        - Each summary must be true of the subtree beneath it, and a validator can check it — [true of below](#wl.depth.true).
      end content

      content diagram
        ┌──────────────────────────────────────────────┐
        │ depth n    summary "…"                       │  useful by
        └──────────────────────────────────────────────┘  itself
                              │
          must be TRUE of ────┤  what the next depth actually holds
                              ▼
        ┌──────────────────────────────────────────────┐
        │ depth n+1  child units, and bytes            │  useful by
        └──────────────────────────────────────────────┘  itself

        Nothing but the braces puts a unit at depth n, and nothing in
        the grammar checks either invariant. Both are the author's.
      end content

      unit wl.depth.nesting kind document.mechanism "The depth count" {
        ref "3.1, 14.3"
        name "Nesting"
        meta icon "⧉"
        summary "A unit's depth is the number of units it sits inside, plus one; nothing
                 stores that number. Depth is unbounded — one branch may run nine deep while
                 another stops at two; local — completeness belongs to a branch, not the
                 document; and relative — a subtree lifted out and read alone stays true. The
                 same locality is why no depth is named; kind says what a level is. Crime and
                 Punishment shows all three in one file: read closely in one place, loosely
                 everywhere else."
        collapsed_summary "A unit's depth is the count of units enclosing it, plus one — never
                           declared, never capped, and never named, so a subtree stays true
                           wherever it is read and kind carries whatever a level means."
        preview_summary "Inside: §3.1 verbatim on how a unit's depth is counted off the
                         braces; the three properties — unbounded, local, relative; why no
                         depth is named; and Crime and Punishment worked in one file, at
                         depth four in one place and depth three elsewhere."

        content face.bullets
          - Depth = units enclosing it, plus one — read off the braces, stored nowhere.
          - Unbounded: one branch runs nine deep while another stops at two.
          - Local: completeness belongs to a branch, never to the whole document.
          - Relative: lift a subtree out and read it alone — every claim still holds.
          - No depth is named; `kind` says what a level is.
        end content

        content markdown
          A unit declares its children inside its own block. Its depth is the number of
          units it sits inside, plus one. There is no layer index and no annotation to keep
          in sync.
        end content

        content weave
          unit thesis kind book.theme "Freedom requires self-knowledge" {
            summary "The novel ties freedom to painful self-recognition."

            unit part.one kind book.part "Part One" {
              summary "Raskolnikov reasons his way to the murder."

              unit ch.one kind book.chapter "Chapter I" {
                summary "The rehearsal walk. He tests the route, the bell, and himself."
              }
            }
          }
        end content

        content diagram
          depth   the text that states it
          ─────   ──────────────────────
            1     unit thesis {                       nothing
            2       unit part.one {                   nothing
            3         unit ch.one {                   nothing
            4           content  "On an evening …"    nothing

          Depth is read off the braces. Because no field carries it,
          moving a unit cannot leave a stale number behind.
        end content

        content markdown
          Three properties follow:

          - **Depth is unbounded.** Nothing caps the structure. A dense chapter may run nine
            deep while the acknowledgements stop at two, and a single function may nest as
            deeply as a whole repository.
          - **Depth is local.** Completeness belongs to a branch, not to the document. A
            weave is not incomplete because one branch is shallower than another; it is
            incomplete when a depth is not a whole world.
          - **Depth is relative.** Lift a subtree out, embed it elsewhere, render it alone —
            every statement inside stays true, because nothing in a unit refers to its
            absolute position.
        end content

        content markdown
          There is no naming of depths. A global depth-to-name table would assert that
          depth 3 means the same thing in every branch, which is the uniformity local depth
          exists to remove. Each unit's `kind` says what it is, and a renderer that wants to
          label a level reads the kinds it finds there.

          Crime and Punishment, read closely in exactly one place and loosely everywhere
          else, in one file:
        end content

        content weave
          weave "Crime and Punishment" kind book {
            unit thesis kind book.theme "Freedom requires self-knowledge" {
              summary "The novel ties freedom to painful self-recognition, and refuses to let
                       its protagonist reason his way around it."

              unit part.one kind book.part "Part One" {
                summary "Raskolnikov reasons his way to the murder, and the reasoning is
                         presented as sound until the act makes it absurd."

                unit ch.one kind book.chapter "Chapter I" {
                  summary "The rehearsal walk. He tests the route, the bell, and himself."

                  unit passage.opening kind book.paragraph "The opening" {
                    summary "The narrator withholds the destination for a full paragraph, so
                             the reader arrives at the door as unprepared as the protagonist
                             pretends to be."
                    content
                      On an exceptionally hot evening early in July a young man came out of
                      the garret in which he lodged in S. Place and walked slowly, as though
                      in hesitation, towards K. bridge.
                    end content
                  }

                  unit rest kind book.scenes "The pawnbroker's flat" {
                    summary "He climbs, rings, is admitted, and conducts a transaction whose
                             ordinariness is the point."
                  }
                }

                unit ch.rest kind book.chapters "Chapters II to VII" {
                  summary "Marmeladov's confession, the letter from his mother, and the
                           dream of the horse — each supplying a reason he will later claim
                           was the reason."
                }
              }
            }

            relation m1 kind book.foreshadows {
              from ch.rest
              to   thesis
              label "Marmeladov confesses what Raskolnikov will not"
            }
          }
        end content

        content markdown
          | what the file holds | depth reached | how it is carried |
          | --- | --- | --- |
          | the opening paragraph of Chapter I | 4 | written out, verbatim |
          | the pawnbroker's flat, beside it | 4 | described, one summary |
          | Chapters II to VII | 3 | described, one summary |

          None of the three is less finished than the others.
        end content
      }

      unit wl.depth.reveals kind document.mechanism "The reveals field" {
        ref "3.2"
        name "reveals"
        meta icon "↗"
        summary "reveals names children that are not lexically nested — declared elsewhere,
                 or shared by more than one parent — written on the parent as a list of ids.
                 A renderer treats a lexical child and a revealed child identically: both
                 preview, both become the next active world, and reveals buys no new
                 behaviour, only skips duplicating a shared child. It works because ids are
                 unique within a weave and independent of nesting — nesting is structure, not
                 a namespace — so two units in unrelated branches may never share one id."
        collapsed_summary "reveals lists the ids of children that live elsewhere or belong to
                           several parents, and renderers treat them exactly like nested
                           children, because ids are unique across the whole weave and carry no
                           trace of where they are nested."
        preview_summary "Inside: §3.2 verbatim on reveals and the mirror motif; a diagram
                         tracing two scenes back to their real parents in the plot tree; and
                         a table comparing a lexical child against a revealed child, plus the
                         id-uniqueness rule that makes it work."

        content face.diagram
          scene.stairs already lives under ch.one — declared once, in its own parent
          motif.mirror reveals [scene.stairs] ──▶ the same unit, reached by id
          lexical: declared inside this parent · revealed: only named here
          both preview the same way · both become the next active world
        end content

        content markdown
          `reveals` names children that are **not** lexically nested: a child declared
          elsewhere, or one shared by more than one parent.
        end content

        content weave
          unit motif.mirror kind book.motif "The mirror motif" {
            summary "Mirror scenes mark each failure of self-deception."
            reveals [scene.stairs, scene.ch34]   // both already have parents in the plot tree
          }
        end content

        content diagram
          the plot tree                    the motifs
          ─────────────                    ──────────
          part.one                         motif.mirror
            └ ch.one                         reveals [ ─────────┐
                ├ scene.stairs ◀─── revealed ───────────────────┤
                └ …                                             │
          part.four                                             │
            └ ch.34                                             │
                └ scene.ch34 ◀─── revealed ─────────────────────┘

          Each scene is declared once, under its own parent in the plot
          tree, and motif.mirror reaches it by id. No copy is made, and
          no second kind of edge exists.
        end content

        content markdown
          | | a lexical child | a revealed child |
          | --- | --- | --- |
          | declared inside this parent's block | yes | no |
          | may belong to another parent too | no | yes |
          | shown as a preview | yes | yes |
          | becomes the next active world | yes | yes |

          A renderer treats lexical and revealed children identically: both are previews,
          and both become the next active world. The distinction exists only so a shared
          child need not be duplicated.

          Ids are globally unique within a weave and independent of nesting. Nesting is
          structure, not a namespace: a deeply nested `fn.mint` is addressable by that id
          from anywhere. The same rule sets the price: two units in unrelated branches may
          not share one id.
        end content
      }

      unit wl.depth.useful kind document.invariant "Useful by itself" {
        ref "3.3"
        name "Useful"
        meta icon "🧭"
        summary "The first invariant asks each depth to be a whole answer at its own
                 resolution, never a topic label like 'Auth module.' The test is not length
                 or detail, but direction of work. The next depth must refine the answer,
                 never rescue it — a summary that only announces a topic pushes its own work
                 downward, and the reader pays that debt with a descent they never chose.
                 Nothing in the grammar can tell a topic label from an account, so this
                 invariant stays the author's to hold, at every depth."
        collapsed_summary "A summary that only names a topic turns its level into a table of
                           contents; each depth must give a whole answer that the next depth
                           refines rather than rescues."
        preview_summary "Inside: §3.3 verbatim — the Bad 'Auth module' and the Good
                         whole-answer version — beside a diagram of the same test: does the
                         next depth refine the level, or rescue one that was never whole?"

        content face.table
          | | a topic label | a whole answer |
          | --- | --- | --- |
          | example | "Auth module." | "Auth module: issues signed JWTs, guards tenant routes." |
          | next depth must | rescue it | refine it |
          | reader pays | an unchosen descent | nothing |
        end content

        content txt
          Bad:  "Auth module."
                Semantically empty. The reader must go deeper to learn anything, so this
                depth was never a world — only a table of contents.

          Good: "Auth module: email/password login issues signed JWTs and protects
                 tenant-scoped API routes."
                A whole answer at this resolution. The next depth refines; it does not rescue.
        end content

        content diagram
          depth n    a topic label          a whole answer
                          │                      │
                          │ the answer is        │ the answer is
                          │ not here yet         │ already here
                          ▼                      ▼
          depth n+1  RESCUES the level      REFINES the level
                          │                      │
                          ▼                      ▼
                  the reader pays a        the reader who stopped
                  descent nobody chose     one depth up was right

          The test is neither length nor detail. It is which way the
          work runs between one depth and the next.
        end content

        content markdown
          Nothing in the grammar can prove a topic label is not a whole answer.
          [Validation](#wl.tools.validate)'s depth level checks a mechanical proxy instead —
          that no summary depends on its children — and the rest stays the author's
          judgment.
        end content
      }

      unit wl.depth.true kind document.invariant "True of its subtree" {
        ref "3.3"
        name "True"
        meta icon "⊨"
        summary "The second invariant asks a summary to describe what its own subtree
                 contains. A summary that fails this is a different claim wearing a
                 summary's clothes — worse than none, since a trusting reader carries away
                 an account of material the weave does not hold. Unlike the first invariant,
                 a machine can help: a validator holds a summary against its subtree and
                 asks whether one describes the other. The two invariants are independent —
                 a whole answer can be about the wrong material, or true of its subtree and
                 still say nothing."
        collapsed_summary "A unit's summary must describe its own subtree, and because the
                           material sits underneath it, a validator can hold the summary against
                           that subtree and ask whether one describes the other."
        preview_summary "Inside: §3.3 verbatim on truth and checkability; a diagram of a
                         validator holding a summary against its own subtree and nothing
                         else; and a table showing the two invariants are independent — a
                         whole answer can still be about the wrong material."

        content face.diagram
          unit  summary "…" ────────────▶ does this describe what sits below?
            └ content, child summaries ◀── the whole input; nothing else is consulted
          true of its subtree · a whole answer about the wrong material still fails
        end content

        content markdown
          A summary that does not describe what its subtree contains is not a summary; it is
          a different claim wearing a summary's clothes. Material makes this checkable: a
          validator can hold a unit's summary against its own subtree and ask whether one
          describes the other.
        end content

        content diagram
          everything else in the document — never consulted
          ┌────────────────────────────────────────────────────┐
          │  unit   summary "…"  ──────────┐                   │
          │                                │ does one          │
          │    ├ content  bytes  ◀─────────┤ describe the      │
          │    ├ unit     summary "…" ◀────┤ other?            │
          │    └ unit     summary "…" ◀────┘                   │
          └────────────────────────────────────────────────────┘

          One unit and what sits under it is the whole input, so truth
          is decidable branch by branch.
        end content

        content markdown
          | | true of its subtree | not true of its subtree |
          | --- | --- | --- |
          | **a whole answer** | what a unit owes a reader | a whole answer about the wrong material |
          | **only a topic label** | true, and says nothing | fails both invariants |

          The two invariants are independent, and both are required.
          [Validation](#wl.tools.validate)'s truth level runs this exact check, and the same
          entailment logic anchors [how a parent is derived from its children](#wl.authoring.parent).
        end content
      }
    }

    unit wl.material kind document.mechanism "A unit's material" {
      ref     "4"
      name "Material"
      meta icon "📦"
      summary "A unit's material is its parts in written order: a literal `content` block
               of verbatim bytes, dedented per unit, or a child unit contributing its own
               material the same way, recursively. The word after `content` is free; three
               conventions ride it unseen by the core. A unit may write some parts and
               delegate the rest; written and described differ only in whether bytes are
               present, never in position, address, or citability. Because detail is a
               depth over one sequence, not a second copy, the same file answers at every
               resolution."
      collapsed_summary "A unit's material is its parts in written order — literal blocks
                         and child units — and a part is written when its bytes are present
                         and described when only its summary is."
      preview_summary   "Inside: the order-of-parts diagram; the verbatim rules for a
                         literal block and its form word; the RequestDirectives struct and
                         the allow function, written and described side by side; the
                         written-versus-described cases; and the four-depth resolution
                         ladder — one file, never a second copy."

      content face.diagram
        a unit's material, in the order the parts are written:

            written      written     written    described    written
          ┌─────────┬─────────────┬─────────┬─────────────┬─────────┐
          │ content │ child unit  │ content │ child unit  │ content │
          └─────────┴──────┬──────┴─────────┴─────────────┴─────────┘
                           └─▶ its own parts, by this same rule, down
      end content

      content markdown
        | the part | what it settles |
        | --- | --- |
        | [order](#wl.material.parts) | a child stands exactly where its own bytes would sit |
        | [a literal block](#wl.material.literal) | verbatim bytes, no escapes, dedented per unit |
        | [the form word](#wl.material.form) | free text after `content`; shape, the `face` role and doors ride it |
        | [composed material](#wl.material.composed) | some parts written, the rest delegated to children |
        | [written vs. described](#wl.material.described) | the only difference is whether bytes are present |
        | [one file](#wl.material.resolution) | the same parts, read at any depth, never a second copy |
      end content

      unit wl.material.parts kind document.rule "Parts in order" {
        ref     "4"
        name "Part order"
        meta icon "≡"
        summary "Material is what a unit is finally about: its parts, in the order they are
                 written. A part is a literal content block, or a child unit contributing
                 its own material the same way, recursively — each child standing exactly
                 where its own bytes would have stood. Nothing else composes material: no
                 body field, no ordering rule, and no rule that blocks come before or after
                 children. That single rule lets one file, class, or function carry layers
                 inside it."
        collapsed_summary "A unit's material is its parts in written order — literal content
                           blocks and child units — with each child contributing its own
                           material recursively."
        preview_summary "Inside: §4's opening paragraph verbatim, naming a content block and
                         a child unit as the only two parts; the table of what each
                         contributes; and a diagram of a child taking the exact position its
                         own bytes would have occupied inside a struct."

        content face.diagram
          a child stands where its own bytes would have stood:

            unit ─┬─ content   "type Invoice struct {"
                  ├─ unit      ← here, not before the blocks or after them
                  ├─ content   "  total Money"
                  ├─ unit      ← and here
                  └─ content   "}"

          full material = these parts, with each child expanded in place
        end content

        content markdown
          A unit's **material** is what it is finally about. Material is built from
          **parts**, in the order they are written: literal `content` blocks, and child
          units. A child contributes its own material, recursively.

          This one rule is what lets a single file, a single class, or a single function
          carry layers inside it.
        end content

        content markdown
          | a part | what it contributes |
          | --- | --- |
          | a [literal `content` block](#wl.material.literal) | its bytes, exactly as written |
          | a child `unit` | its own material, by this same rule, all the way down |

          Nothing else composes material:

          - no separate body field;
          - no ordering annotation;
          - no rule that blocks come before children, or after them — the order is
            whatever the author wrote.
        end content
      }

      unit wl.material.literal kind document.rule "The literal block" {
        ref     "4.1"
        name "Literal blocks"
        meta icon "❝"
        summary "A content keyword alone on its line opens a literal block: it starts on the
                 next line and ends at the first line whose trimmed text is exactly end
                 content, at the opening indentation. Every line between is taken exactly as
                 written — no escapes, no delimiters — so a block may hold quotes, braces,
                 or this language's syntax, quoting itself one indentation deeper.
                 Indentation is stripped per unit, not per block, so a struct or function
                 reassembles indented. A tool must never tidy, reflow, or rewrap what sits
                 inside."
        collapsed_summary "content and end content delimit bytes taken exactly as written,
                           with no escapes, dedent computed per unit rather than per block,
                           and a standing ban on reformatting."
        preview_summary "Inside: the content/end content rule verbatim; the scene.opening
                         passage; a block that quotes this language at itself by sitting
                         deeper; and the per-unit dedent, worked in a three-block example."

        content face.diagram
          content <form>                     ┐  everything between these two
            verbatim bytes — no escapes,     │  lines is taken exactly as
            no delimiters, no tidying        │  written, dedented per UNIT
          end content                        ┘  not per block
        end content

        content markdown
          A `content` keyword alone on its line opens a verbatim block ending at a line
          whose only text is `end content`, at the same indentation as the opening keyword.
        end content

        content weave
          unit scene.opening kind book.scene "The opening walk" {
            summary "He leaves the garret and rehearses the route."
            content
              On an exceptionally hot evening early in July a young man came out of the
              garret in which he lodged in S. Place and walked slowly, as though in
              hesitation, towards K. bridge.
            end content
          }
        end content

        content markdown
          An optional word may follow `content` to name the material's form — see
          [form words](#wl.material.form) for what rides on it.
        end content

        content markdown
          Block rules, in full:

          - The block starts on the line after the `content` line and ends at the first line
            whose trimmed text is exactly `end content` **at the opening indentation**.
          - Every line between is verbatim. There are no escapes and no delimiters, so a
            block can contain quotes, braces, backticks, or any other syntax without
            collision — including this language's own. Matching the indentation is what lets
            a block contain an example of itself.
          - Indentation is removed **per unit, not per block**: all of a unit's literal
            blocks are dedented together, by the smallest indentation any of them used. That
            is what lets the parts of a struct or a function body keep their indentation
            relative to each other when they are reassembled.
        end content

        content markdown
          The end marker is a position, not a token, so a block quotes this language at
          itself by sitting deeper:
        end content

        content weave
          content markdown
            A block that contains a block:

              content go
                fmt.Println("}")
              end content

            The inner `end content` is indented deeper than the outer `content`, so it
            never ends anything. It is text.
          end content
        end content

        content diagram
          indentation is stripped per UNIT, over all of its blocks at once
          (· marks a leading space)

            as written                    as material
            ┌──────────────────────┐      ┌────────────────────┐
            │ ····content go       │      │ func f() {         │
            │ ······func f() {     │      │ ··guard()          │
            │ ····end content      │      │ }                  │
            │ ····content go       │      └────────────────────┘
            │ ········guard()      │
            │ ····end content      │      smallest indent used by
            │ ····content go       │      ANY of the three blocks
            │ ······}              │      is 6, so 6 comes off all
            │ ····end content      │      three — and the body keeps
            └──────────────────────┘      the 2 spaces that are its own

          per block, each would dedent to 0 on its own and the body would
          lose its indentation relative to the signature
        end content

        content markdown
          Material is never a summary, a paraphrase, or a quotation *about* the thing. It is
          the thing. A tool must never tidy, reflow, or rewrap it.
        end content
      }

      unit wl.material.form kind document.rule "The form word" {
        ref     "4.1"
        name "Form words"
        meta icon "🏷"
        summary "One optional word after `content` names the material's form. The word is
                 free: conventions give it meaning, renderers style by it, and the core
                 keeps no list of valid values, so an unknown form still parses, still
                 validates, and still renders verbatim. Published shape names are one
                 convention on that word, and a `face` role written in front of a shape is
                 the second. A third rides the block's prose rather than its word — inside
                 a prose form, a markdown link to a unit id is a door to that unit."
        collapsed_summary "The word after `content` is free and checked against no list,
                           and three conventions ride on it invisibly to the core: the
                           published shape names, a `face` role in front of a shape, and a
                           markdown link to a unit id."
        preview_summary "Inside: §4.1's form-word paragraph and its three conventions
                         verbatim — the five published shape names, the five spellings of
                         the `face` role, and the two limits that keep a unit link honest."

        content face.bullets
          - The word is **free**: an unknown form parses, validates, and renders verbatim.
          - **Shape names** — `markdown`, `txt`, `diagram`, `svg`, `timeline` — are what a renderer styles by.
          - A **`face` role** in front of a shape marks [the unit's collapsed reading](#wl.authoring.face).
          - A markdown link to `#<unit-id>` in prose is a **door**; it never appears in [verbatim material](#wl.material.literal).
        end content

        content markdown
          An optional word after `content` names the material's form. The word is free —
          conventions give it meaning, renderers use it for styling, and the core has no
          list of valid values.

          Two conventions ride on the form word, both invisible to the core:

          - **Shape names.** Published conventions name common shapes so tools can render
            them expressively: `markdown` (prose, bullets, tables), `txt` (verbatim text),
            `diagram` (monospace drawing), `svg` (an inline picture), `timeline` (rows of
            `<when> — <what>`, one per line). An unknown form still parses, validates, and
            renders verbatim.
          - **The `face` role.** A form may carry a role before its shape, dotted like a
            sub-symbol word: `face`, `face.bullets`, `face.table`, `face.diagram`,
            `face.timeline`. A face block is the unit's **collapsed reading** — what a tool
            may show when the unit is seen from outside, in place of prose summaries — and
            it is not part of the page the unit shows when it is open (the open page's
            account is the summary and the ordinary material; showing the face there too
            would render one statement twice). A tool that knows nothing about roles
            renders a face block as ordinary material, which degrades to honest.
          - **Unit links.** In a prose-form block, a standard markdown link whose target
            is `#` followed by a unit id — `[the moving line](#ch5)` — names that unit. A
            tool that can navigate treats it as a door: activating it goes there, and it
            may show the unit's collapsed reading as a preview on approach. Two limits
            keep the device honest. It appears only in AUTHORED blocks — gists, bullets,
            faces — never in verbatim material, because material is never edited. And a
            link whose id does not resolve renders as its plain text: a door that opens
            nowhere is not drawn as a door.
        end content

        content diagram
          content  face.table  in pr.head
          ───────  ────┬─────  ──────────
                       │
                  ┌────┴────┐
                  │         │
               role       shape        the core reads NEITHER: it reads
             optional     free word    one word and stops. A tool that
             (face)       (table)      knows no roles renders the block
                                       as ordinary material

          the door is not on the word at all — it is inside the prose:

            [the razor](#wl.weakness.razor)   resolves   ─► a door
            [the razor](#no.such.unit)        does not   ─► plain text
        end content
      }

      unit wl.material.composed kind document.example "Composed material" {
        ref     "4.2, 14.1"
        name "Composed material"
        meta icon "🧩"
        summary "A unit may write some material and delegate the rest to children, in
                 written order. The RequestDirectives struct writes its declaration,
                 timeouts and closing brace as literal blocks, and delegates its retry and
                 integrity knobs to children carrying only a summary; the allow function
                 shows the same shape one scale down, wrapping a described counting body
                 between a written signature and return line. A described child is not a
                 gap: it occupies a position, and is addressable, citable, and relatable
                 like a written one — what it lacks is bytes."
        collapsed_summary "A unit can write some parts as literal blocks and delegate the
                           rest to children, and the interleaved sequence still reads as one
                           continuous piece of material."
        preview_summary "Inside: the RequestDirectives struct verbatim, writing its
                         declaration and timeouts while describing its retry and integrity
                         knobs; the allow function doing the same around a described
                         counting body; and two diagrams tracing how the written bytes still
                         close around each gap."

        content face.diagram
          written ─ written ─ described ─ written ─ described ─ written

          a struct or a function: some parts are bytes, some are children —
          the written bytes still close correctly around every gap
        end content

        content markdown
          A unit may write some of its material and delegate the rest to children. Parts
          compose **in the order they appear**:
        end content

        content weave
          unit directives kind go.struct "RequestDirectives" {
            ref     "common/request.go:RequestDirectives"
            summary "Every knob a caller may set for one request. The zero value is the
                     service default, so an unset field is never an error."

            content go
              type RequestDirectives struct {
            end content

            unit d.retry kind go.fields "Retry knobs" {
              summary "Attempt count, backoff base, and whether jitter is applied. Json tags
                       match the config file's naming so a directive can be set either way."
            }

            content go
                ReadTimeout  time.Duration `json:"readTimeout"`
                WriteTimeout time.Duration `json:"writeTimeout"`
            end content

            unit d.integrity kind go.fields "Integrity knobs" {
              summary "The checksum algorithm to verify with, and whether a mismatch fails
                       the request or only records a warning."
            }

            content go
              }
            end content
          }
        end content

        content diagram
          unit directives
            ├ content   "type RequestDirectives struct {"      written
            ├ unit      "Retry knobs"                          described
            ├ content   "  ReadTimeout  time.Duration ..."     written
            ├ unit      "Integrity knobs"                      described
            └ content   "}"                                    written

          material = the parts, in the order they are written
        end content

        content markdown
          Read at the top, this is one sentence about what the struct is for. Read one level
          down, it is four ideas: the declaration, the retry knobs, the timeouts, the
          integrity knobs. Read fully, it is the struct — except that two of its four parts
          are described rather than written.

          `d.retry` and `d.integrity` are **described**: they have a summary and no material
          of their own. They occupy a real position in the struct, they are addressable,
          they can carry relations and citations, and a reader can see exactly where they
          belong. What they do not have is bytes.
        end content

        content markdown
          The same shape holds one scale down, inside a single function — see
          [written and described](#wl.material.described) for what a described child
          promises:
        end content

        content weave
          weave "rate-limit" kind software.capability {
            unit allow kind software.function "allow" {
              ref     "src/limit.ts:allow"
              summary "Return false once the tenant's window is full. Never block on Redis:
                       a limiter that fails closed takes the service down with it."

              content typescript
                export async function allow(tenantId: string): Promise<boolean> {
                  const key = `rl:${tenantId}:${Math.floor(Date.now() / 1000)}`
              end content

              unit count kind software.body "Counting the request" {
                summary "Increment the key and set a 60-second expiry on first use. Any
                         Redis error counts as zero, so an outage lets traffic through."
              }

              content typescript
                  return count <= 1000
                }
              end content
            }
          }
        end content

        content diagram
          export async function allow(...): Promise<boolean> {   ┐ written
            const key = `rl:...`                                 ┘
            ┌────────────────────────────┐
            │ unit count                 │   described: a real position
            │ "Counting the request"     │   between the two runs of
            │ summary only, no bytes     │   bytes, and no bytes
            └────────────────────────────┘
            return count <= 1000                                 ┐ written
          }                                                      ┘

          the written bytes close correctly around a part nobody has written
        end content

        content markdown
          `allow`'s signature and its return line are written; the counting body between
          them is a described child, so the written bytes still close correctly around a
          part nobody has written yet.
        end content
      }

      unit wl.material.described kind document.rule "Written and described" {
        ref     "4.3, 14.2"
        name "Described parts"
        meta icon "💬"
        summary "A written part and a described part differ only in whether material is
                 present; both occupy a position, are addressable, citable and relatable,
                 and usually carry a summary — mandatory on the described one. A renderer
                 shows a written part's material, and a described part's summary in its
                 place; a generator may render one or write the other from its summary and
                 surroundings. A described unit is not an omission: the material is
                 conventional, uninteresting here, not yet written, or left to the reader —
                 four reasons, one identical object."
        collapsed_summary "Written and described parts differ only in whether bytes are
                           present; a described part keeps its position, its address and its
                           citations, and asserts that the material is conventional, dull at
                           this depth, unwritten, or left to the reader."
        preview_summary "Inside: the written-versus-described table verbatim; the
                         four-reasons diagram; the Go imports, the expiry branch and Chapter
                         XXX side by side; and the Invoice class that writes one method for
                         its rounding behaviour and describes the rest."

        content face.diagram
          conventional ───────────┐
          uninteresting here ─────┤        unit <id> "Title" {
          not yet written ────────┼──────▶    summary "…"
          left to the reader ─────┘        }

          four different reasons, one identical object
        end content

        content markdown
          The only difference between a written part and a described part is whether
          material is present.

          | | written | described |
          | --- | --- | --- |
          | has `summary` | usually | always |
          | has material | yes | no |
          | occupies a position | yes | yes |
          | addressable, citable, relatable | yes | yes |
          | a renderer shows | the material | the summary, in its place |
          | a generator may | render it | write it, from the summary and its surroundings |

          A described unit is not an omission and not an error. It is a statement that this
          part of the material is conventional, uninteresting at this depth, not yet
          written, or deliberately left to the reader.
        end content

        content markdown
          The same mechanism covers cases that look unrelated:
        end content

        content weave
          // A file whose imports are not worth reading
          unit imports kind go.imports "The usual imports" {
            summary "Standard library time and errors, the project's config package, and
                     the vendored json library."
          }

          // A function with one interesting branch and one boring one
          unit fn.verify kind software.function "verifyMagicLink" {
            summary "Check the signature, reject an expired link, then start a session."

            content typescript
              export async function verifyMagicLink(token: string): Promise<Session> {
                const claims = verifySignature(token, MAGIC_LINK_SECRET)
            end content

            unit expiry kind software.branch "The expiry check" {
              summary "Reject when issuedAt is more than ten minutes old, measured against
                       the server clock, and consume the token so it cannot be replayed."
            }

            content typescript
                return startSession(claims.subject)
              }
            end content
          }

          // A book read closely in one chapter and loosely everywhere else
          unit ch.thirty kind book.chapter "Chapter XXX" {
            summary "The confession, delivered flatly and immediately retracted."
          }
        end content

        content markdown
          The import block is described because nobody needs to read it. The expiry check
          is described while the two halves of the function around it are written. The
          chapter is described because the close reading is elsewhere — three different
          reasons, the same kind of object each time.
        end content

        content weave
          weave "invoice" kind software.module {
            unit invoice kind java.class "Invoice" {
              ref     "src/main/java/billing/Invoice.java"
              summary "An immutable invoice. Totals are computed once at construction, so a
                       line item cannot be added after a total has been read."

              content java
                public final class Invoice {
              end content

              unit fields kind java.fields "State" {
                summary "The tenant id, an immutable list of line items, the currency, and
                         the computed total, all final."
              }

              unit ctor kind java.constructor "Constructor" {
                summary "Takes tenant, items and currency; copies the item list defensively
                         and computes the total before returning."
              }

              unit total kind java.method "getTotal" {
                summary "Returns the precomputed total. No rounding happens here — rounding
                         is applied per line item at construction, so the sum is exact."
                content java
                  public Money getTotal() {
                    return total
                  }
                end content
              }

              content java
                }
              end content
            }
          }
        end content

        content markdown
          One method is written because its rounding behaviour is the thing a reader gets
          wrong. The rest is described, because it is what anyone would expect.
        end content
      }

      unit wl.material.resolution kind document.consequence "One file, every resolution" {
        ref     "4.4"
        name "One file"
        meta icon "📄"
        summary "Because material composes from parts, the same weave answers every
                 resolution without storing itself twice: depth 1 is the summary, depth 2
                 the children's summaries in order, depth n literal parts verbatim with
                 described parts as summaries, and full literal parts verbatim with
                 described parts still described, with no fallback copy. A renderer picks a
                 depth; a generator picks a depth and writes what is still described;
                 neither needs a mode. This ladder is structural, distinct from the
                 renderer's shallow-to-deepest one (§11); the two compose, not compete."
        collapsed_summary "A ladder from summary to full bytes is a reading over one
                           sequence of parts, so a renderer picks a depth, a generator picks
                           a depth and writes what is still described, and the file never
                           changes; the renderer's shallow-to-deepest ladder is a different
                           thing."
        preview_summary "Inside: the four-depth ladder verbatim — summary, children's
                         summaries, literal-with-described-as-summary, and full; a diagram
                         of the same parts read at each depth; and the table separating this
                         structural ladder from the renderer's shallow-to-deepest one."

        content face.diagram
          one sequence of parts, read at four depths — nothing stored twice

            depth 1   [ the unit's summary      ]
            depth 2   [ child ][ child ][ child ]
            depth n   [ bytes ][ summ. ][ bytes ]
            full      [ bytes ][ summ. ][ bytes ]   ← still a summary: no hidden copy
        end content

        content markdown
          Because material composes from parts, the same weave answers at every resolution
          without storing several versions of itself:
        end content

        content txt
          depth 1   the unit's summary
          depth 2   its children's summaries, in order
          depth n   literal parts verbatim, described parts as their summaries
          full      literal parts verbatim; described parts still described
        end content

        content markdown
          A renderer chooses a depth. A generator chooses a depth and then writes what is
          still described. Neither needs a mode, and the file does not change.
        end content

        content markdown
          Two ladders in this specification are called resolution, and they vary different
          things: this one is a reading over a unit's own **parts**, while
          [the renderer's](#wl.tools.render) (§11) is a recommended **grain** for the
          material shown at a rung.

          | | this ladder (§4.4) | the renderer's (§11) |
          | --- | --- | --- |
          | what varies | how far down the parts a reading goes | how fine the shown material is |
          | rungs | `depth 1`, `depth 2`, `depth n`, `full` | shallow, middle, deepest |
          | status | what the parts are, so the file settles it | a recommendation, not a fixed scale |
          | never does | store a second copy of the material | remove a part |

          A reading picks one rung on each. Neither ladder may drop a part.
        end content
      }
    }

    unit wl.named kind document.mechanism "Named material" {
      ref "4.5, 4.6"
      name "Named material"
      meta icon "📍"
      summary "A content block can name material instead of holding it: `in` pins a
               source once, `at` locates a part inside it, `region` narrows with a free
               selector word, `sha256` pins the bytes read, and `outline` carries the
               source's region tree, kept honest by law. Naming buys reach — a weave can
               be about a repository, a book, or a recording it does not contain. It
               costs self-containment, because the weave then needs its source to be
               readable. Everything below pays that price back by reference;
               self-containment alone never returns."
      collapsed_summary "A content block may name material that lives elsewhere —
                         source, locator, region, checksum, and a distilled outline of
                         the source's real structure — at the price of a weave that no
                         longer contains what it is about."
      preview_summary "Inside: what naming trades for reach, the region selector's open
                       word, the outline that lets a renderer fold without holding the
                       bytes, and the four laws that keep that outline honest."

      content face.table
        | naming buys | naming costs |
        | --- | --- |
        | reach — a repo, a book, a recording | the file no longer holds its subject |
        | drift caught by `sha256` | its source must stay readable |
        | folds that land right, from `outline` | nothing else; the rest is paid back |
      end content

      content diagram
        EMBEDDED                      NAMED
        ────────────────────────      ────────────────────────────────
        content go                    content go in pr.head {
          …the real bytes…            at     "common/request.go"
        end content                   region lines 109..140
                                      sha256 "9f2c1a…"
                                      outline { … }
                                    }

        the bytes are HERE            the bytes are THERE
        · self-contained              · needs its source readable
        · reach = this one file       · reach = a repo, a book, a tape
      end content

      content markdown
        Everything below is that same trade, priced out:

        | what embedding gave away for free | what naming buys it back with |
        | --- | --- |
        | the material is right here | [`at`](#wl.named.naming) — a locator inside a pinned source |
        | the bytes are the ones that were read | [`sha256`](#wl.named.naming) — a checksum, so drift is caught |
        | the renderer can see the structure | [`outline`](#wl.named.outline) — a distilled tree of real ranges |
        | the weave is self-contained | *nothing.* [This is the one that cannot come back](#wl.subject.self_contained). |

        The [region selector](#wl.named.selectors) that narrows to a part is a free
        word, and the outline itself answers to [four laws](#wl.named.laws) that keep
        its claims honest and separate from what a renderer decides.
      end content

      unit wl.named.naming kind document.mechanism "Naming instead of embedding" {
        ref "4.5"
        name "Naming"
        meta icon "🔖"
        summary "When material already lives somewhere, the same content keyword names
                 it instead of embedding it: an optional form word, then `in <source>`,
                 then a brace body in place of a verbatim block. `in` points at a source
                 pinned once, shared by every leaf that reads it. `at` gives the stable
                 locator inside it; `region` narrows with a free selector word; `sha256`
                 pins the bytes read, so a later read detects drift. A named part holds
                 the same place in the material as a literal block, at the cost of
                 self-containment."
        collapsed_summary "`content <form> in <source> { at, region, sha256, outline }`
                           names material where it lives instead of holding it, pinning
                           the bytes with a checksum and giving up self-containment."
        preview_summary "Inside: the verifyMagicLink function citing a pinned
                         pull-request head, the six-field naming table, a diagram of one
                         source shared by three leaves, and the sentence stating exactly
                         what naming costs."

        content face.bullets
          - `in <source>` names [a source](#wl.constructs.source) pinned once, shared by every leaf that reads it.
          - `at` then `region` locate the part: a stable locator, then a free selector word.
          - `sha256` pins the exact bytes read, so a later read of the same locator can be checked for drift.
          - `outline` carries the material's structural region tree — see [the outline](#wl.named.outline).
        end content

        content weave
          unit fn.verify kind software.function "verifyMagicLink" {
            summary "Check the signature, reject an expired link, then start a session."
            content typescript in pr.head {
              at     "auth/magic.ts"
              region lines 42..78
              sha256 "9f2c1a…"
            }
          }
        end content

        content markdown
          | Field | Job |
          | --- | --- |
          | `in <source>` | Which source (§2.5). |
          | `at "<path>"` | Path, fragment, chapter, or other stable locator. |
          | `region <selector> <value>` | Which part. The selector word is free. |
          | `sha256` | Pins the exact bytes, so a later read detects drift. |
          | `outline { … }` | The structural region tree of the material (§4.6). |
          | `props`, `meta` | Rendering and folding preferences. |
        end content

        content diagram
          source pr.head {          ← the revision, pinned ONCE
            uri      "github.com/acme/app"
            revision "abc123def"
          }
               ▲               ▲               ▲
               │ in            │ in            │ in
          content ts      content ts      content go
           at "auth/…"     at "auth/…"     at "common/…"
           (unit A)        (unit B)        (unit C)

          Every leaf names the origin; not one of them names a revision.
        end content

        content markdown
          A weave with named material is not self-contained: it needs its source to be
          readable. That is a trade a tool may make, never a default the language prefers.
        end content
      }

      unit wl.named.selectors kind document.rule "Region selectors" {
        ref "4.5"
        name "Region selectors"
        meta icon "📏"
        summary "A region line is a selector word followed by a value; the core checks
                 that word against nothing. Four value shapes appear here — `lines` as
                 two dotted integers, `page` as a bare number, `section` as a quoted
                 label, `time` as two quoted timestamps — because each origin addresses
                 its parts its own way. They are examples, not an enumeration: an
                 uncited form brings its own selector word, unchanged grammar and all,
                 since the parser only reads one word and one value. Resolving it is the
                 source-reading tool's job, never the language's."
        collapsed_summary "The word after `region` is free — lines, page, section, time,
                           or whatever a new material form needs — and its value shape
                           follows the origin's own way of addressing its parts."
        preview_summary "Inside: the annotated selector-value grammar, the four worked
                         examples — lines, page, section, time — and a table pairing
                         each selector with the value shape its own origin demands."

        content face.diagram
          region    lines    40..92
          │         │        └───── value — its shape follows the origin
          │         └────────────── selector — a WORD, and the core checks
          │                         it against nothing
          └──────────────────────── all the grammar reads here: one word,
                                    then one value
        end content

        content markdown
          Region examples — the selector is an open word, not one of a fixed set:
        end content

        content weave
          region lines 40..92
          region page 221
          region section "9.2.2"
          region time "2026-06-25T10:00:00Z" .. "2026-06-25T11:00:00Z"
        end content

        content markdown
          | selector | value shape | how that origin names its parts |
          | --- | --- | --- |
          | `lines` | integers joined by two dots — `40..92` | a text file, by line |
          | `page` | a bare number — `221` | a scan or a print edition, by page |
          | `section` | a quoted label — `"9.2.2"` | a standard or a book, by section |
          | `time` | two quoted timestamps, two dots | a recording, by elapsed time |
          | *a word nobody has used yet* | whatever that origin uses | a frame number, a cell range, a track offset |

          Four rows, not four options. Resolving the word is the job of the tool that
          reads the source, not of the language — `region` is one of
          [the fields that name material](#wl.named.naming).
        end content
      }

      unit wl.named.outline kind document.mechanism "The outline" {
        ref "4.6"
        name "The outline"
        meta icon "🌲"
        summary "An outline sits inside named material and carries the source's
                 structural region tree, because the renderer holds no bytes and cannot
                 open the file to see where a citation sits or what the rest contains.
                 Each line names a real line range and a kind, and may add a name, a
                 gist, and a rank. The tree covers the whole source, not only the cited
                 part — a worked example outlines a 780-line file around a citation of
                 lines 109 to 140, so a renderer can fold the rest behind a one-line
                 gist."
        collapsed_summary "An outline distils the real source's region tree — line
                           ranges with a structural kind, an optional symbol name, a
                           fold gist, and a 0–100 rank — so a renderer that does not
                           hold the bytes can still fold the material well."
        preview_summary "Inside: the field table for an outline's own grammar, the
                         worked 780-line Go file with its ranked, gisted regions, the
                         one-line grammar itself, and a diagram of what stays open and
                         what folds."

        content face.table
          | piece | required | what it states |
          | --- | --- | --- |
          | `region lines <start>..<end>` | yes | the real line range in the source |
          | `<kind>` | yes | the structural unit, a free word — see [the laws it obeys](#wl.named.laws) |
          | `name "<symbol>"` | no | the symbol declared there |
          | `gist "<one-liner>"` | no | what the lines say once they are folded away |
          | `rank <0-100>` | no | significance relative to the unit that cited the material |
        end content

        content weave
          content go in pr.head {
            at     "common/request.go"
            region lines 109..140
            props  { significance 87  role "defines the request directives contract" }

            outline {
              region lines 1..780   file    name "common/request.go"
              region lines 1..14    imports rank 5
              region lines 109..540 struct  name "RequestDirectives" rank 90
              region lines 117..538 run     gist "remaining directive fields, with json tags" rank 20
              region lines 545..690 func    name "ApplyDirectiveDefaults" gist "copy each non-nil default onto r.directives" rank 70
            }
          }
        end content

        content txt
          region lines <start>..<end> <kind> [name "<symbol>"] [gist "<one-liner>"] [rank <0-100>]
        end content

        content diagram
          common/request.go — 780 lines; this unit cites 109..140

            1..14     imports                      rank  5   ⋯
            109..540  struct RequestDirectives     rank 90   OPEN
            │ 109       type RequestDirectives struct {      shown
            │ 110..116  the cited fields                     shown
            │ 117..538  run                        rank 20   ⋯
            │           ⋯ "remaining directive fields, with json tags"
            │ 540       the struct's closing line            shown
            545..690  func ApplyDirectiveDefaults  rank 70   ⋯
                        ⋯ "copy each non-nil default onto r.directives"

          ⋯ = the whole region, folded to one line: its gist.
          The reader gets the opening line, the telling middle, the closing
          bracket — and no cut lands in the middle of a declaration.
        end content
      }

      unit wl.named.laws kind document.laws "The four outline laws" {
        ref "4.6"
        name "Outline laws"
        meta icon "⚖"
        summary "An outline obeys four laws and leaves one word free. Boundaries are
                 real lines, 1-based inclusive; a range matching no real material is
                 fabrication. Nesting is containment: a fold lands on region boundaries,
                 never mid-way. A gist must describe exactly the lines it hides. A rank,
                 0 to 100, orders significance, never a layout instruction. The four
                 divide the labour one way — the outline states facts, the renderer
                 decides policy. The free word is `kind`, the structural unit's name:
                 naming every form's units in advance is a commitment the language
                 declines."
        collapsed_summary "An outline's ranges must be real 1-based inclusive lines, its
                           nesting must be containment so folds land on boundaries, its
                           gists must describe exactly the lines they hide, and its
                           0–100 ranks order significance without dictating a view."
        preview_summary "Inside: the verbatim five-item rule list — four laws and the
                         one free word, `kind` — beside a table pairing what the outline
                         states as fact against what the renderer alone decides as
                         policy."

        content face.table
          | what the outline states — fact | what the renderer settles — policy |
          | --- | --- |
          | where each region begins and ends | where the view is cut |
          | which region contains which | which regions get folded |
          | what the hidden lines say — `gist` | whether to fold at all |
          | how significant, 0–100 — `rank` | at which depth each rank opens |
        end content

        content markdown
          - **Boundaries are real lines, never invented.** 1-based inclusive; `start` is the
            opening line and `end` the last. A region that does not correspond to real
            material is fabrication.
          - **Nesting is containment.** A region inside another is its child; parents sort
            first. A fold must land on region boundaries and never cut a block mid-way.
          - `kind` names the structural unit and is a **free word** — `file`, `struct`,
            `func`, `imports`, `run` for an undeclared stretch, `section` or `paragraph` for
            prose, or anything a new material form needs.
          - `gist` is the one-line gloss shown when the region is folded: what the hidden
            material *does*, in the source's own vocabulary. It must describe exactly the
            lines it hides.
          - `rank` (0–100) orders significance relative to the citing unit; higher ranks open
            at shallower depth. The outline supplies facts, the renderer supplies policy.
        end content

        content markdown
          The division runs one way, and both failures are visible from it: an outline
          that dictates a view has overstepped, and [a renderer](#wl.tools.render.material)
          that invents a boundary has no facts to stand on.
        end content
      }
    }

    unit wl.weakness kind document.principle "The weak core" {
          ref     "1.3, 5, 14"
          name "Weak core"
          meta icon "🪶"
          summary "One decision procedure runs through this whole area three times,
                  always the same direction. First, the razor: among designs that decide
                  the observed cases, WeaveLang takes the weakest, and it deletes a
                  commitment but never a capability. Second, props and meta: because the
                  core admits only ground truth, every opinion rides these two open
                  mechanisms instead, so refusing a core field for it costs an author
                  nothing. Third, non-goals: at a few boundaries even that free home is
                  refused, and the claim is declined outright, never weakened."
          collapsed_summary "WeaveLang commits to nothing its material forces it to commit
                            to: the razor deletes commitments but never capabilities,
                            opinions ride props and meta, and claims that would need a
                            commitment are declined outright."
          preview_summary "Inside: the razor's criterion and its four rules, verbatim;
                          the props/meta split with a worked TransportPool example and
                          two conventions; and the non-goals WeaveLang refuses, plus the
                          opacity rule that lets a content block hold real code."

          content face.bullets
            - The razor forbids the commitment; it never forbids the capability — [the razor](#wl.weakness.razor).
            - An opinion always has a home in [props/meta](#wl.weakness.props_meta), so refusing it a core field costs nothing.
            - Where even that home is refused, [non-goals](#wl.weakness.nongoals) declines the claim outright.
          end content

          content diagram
            a proposed addition
                    │
                    ▼
            ┌───────────────────────────────────────────────────┐
            │ RAZOR      does it foreclose anything?            │
            │            yes → a COMMITMENT → delete it         │
            │            no  → a CAPABILITY → weakest form      │
            └───────────────────────────────────────────────────┘
                    │  the expression still has to live somewhere
                    ▼
            ┌───────────────────────────────────────────────────┐
            │ props/meta an opinion's legal home outside the    │
            │            core, so refusing a core field for it  │
            │            costs the author nothing               │
            └───────────────────────────────────────────────────┘
                    │  a few claims cannot be held even there
                    ▼
            ┌───────────────────────────────────────────────────┐
            │ NON-GOALS  the claim is declined, not weakened    │
            └───────────────────────────────────────────────────┘

            read downward: each stage exists because the one above it refused
            something. Nothing ever reads back up.
          end content

          unit wl.weakness.razor kind document.rule "The design razor" {
            ref     "1.3"
            name "The razor"
            meta icon "🪒"
            summary "The design is selected, not accumulated: among designs that decide
                    the observed cases exactly, WeaveLang takes the weakest, measured by
                    extension — the unseen material a design still handles — never by
                    form. The cut runs one way only: it deletes commitments and never
                    capabilities, because deleting a capability shrinks extension
                    exactly as adding a commitment does. Foreclosure is the test that
                    tells them apart; four rules turn the criterion into a check every
                    addition must pass."
            collapsed_summary "Among designs that decide the observed cases exactly,
                              WeaveLang takes the weakest; it deletes commitments, never
                              capabilities, and four rules make that a test every addition
                              must pass."
            preview_summary "The criterion and its citation verbatim, then the single
                            question that tells a commitment from a capability, then the
                            four rules and the one cost that really does scale."

            content face.bullets
              - The razor deletes a commitment; it never deletes a capability — that's the whole cut.
              - [Foreclosure](#wl.weakness.razor.foreclose) is the one question that tells them apart.
              - [Four rules](#wl.weakness.razor.rules) turn the criterion into a test every addition must pass.
            end content

            content markdown
              Among designs that decide the observed cases exactly, WeaveLang takes the
              **weakest** — the one committing least beyond the data (Bennett,
              arXiv:2301.12987). Generality is a property of a design's extension, not its form.
            end content

            content markdown
              - **The candidate set comes first.** Only designs that decide the observed cases *exactly* are considered; the razor chooses among those, and never excuses a design that decides them wrongly.
              - **Extension is the measure, form is not.** A short, tidy design can be maximally overcommitted, so compactness never argues for a construct.
              - **The cut is one-directional.** Deleting a capability shrinks extension exactly as adding a commitment does — [one question separates the two](#wl.weakness.razor.foreclose).
              - **The criterion becomes a checklist.** [Four rules](#wl.weakness.razor.rules) put every proposed addition through the same test, against the one cost that really scales.
              - This is the argument behind every number in the language: [five constructs, seven symbols, no enums in the middle](#wl.subject.creed).
            end content

            unit wl.weakness.razor.foreclose kind document.distinction "Commitments versus capabilities" {
              ref     "1.3"
              name "Foreclosure"
              meta icon "🔒"
              summary "The razor is asymmetric because it maximises extension: a
                      commitment forecloses material the author never saw, so deleting
                      one is the point; a capability only offers an expression some
                      material will need, and deleting it shrinks extension exactly as
                      adding a commitment does. One question tells them apart — does
                      this construct foreclose anything? Coverage is forced by the
                      purpose, shape by the data, so a missing example never argues for
                      removing an expression, only for holding it in its weakest form."
              collapsed_summary "One question — does this construct foreclose anything? —
                                separates a commitment, which the razor deletes, from a
                                capability, which it never deletes for want of an example."
              preview_summary "Inside: §1.3 verbatim on commitments and capabilities, the
                              one foreclosure test, and a table setting a commitment
                              against a capability across five questions — what it is,
                              whether it forecloses, the worked example, the razor's
                              move, and whether absence of use counts."

              content face.table
                | | a commitment | a capability |
                | --- | --- | --- |
                | forecloses unseen material | yes | no |
                | the razor's move | delete it | keep it |
                | "no weave uses it yet" | never why it was there | not an argument |
              end content

              content markdown
                The razor maximises extension. So it deletes **commitments** — an enum, a fixed
                ladder, a rule keyed to one vocabulary — because a commitment rules out material
                the author never saw. It says nothing about deleting **capabilities**, and a
                capability deleted shrinks extension exactly as a commitment added does.

                The two are told apart by one question: **does this construct foreclose anything?**

                | | a commitment | a capability |
                | --- | --- | --- |
                | what it is | an enum, a fixed ladder, a rule keyed to one vocabulary | an expression some material will need |
                | does it foreclose? | **yes** — it rules out material the author never saw | **no** |
                | the example | a `layers` block asserting that depth 3 means the same in every branch, which forecloses every document whose branches differ | a `relation` |
                | the razor's move | delete it | keep it — deleting it shrinks extension exactly as adding a commitment does |
                | "no weave uses it yet" | never why it was there | **not an argument** |

                **Coverage is forced by the purpose; shape is forced by the data.** WeaveLang
                exists to express any subject — a book, a program, a standard, an argument. That
                purpose forces coverage of material nobody has woven yet, so *"there is no example
                yet"* is never grounds for removing an expression. It is only ever grounds for
                holding the expression in its weakest form until real material shapes it.
              end content
            }

            unit wl.weakness.razor.rules kind document.rule "The four rules" {
              ref     "1.3"
              name "Four rules"
              meta icon "📋"
              summary "The criterion becomes operational as four rules, and a proposed addition
                      is put through all four. Two settle what to cut: delete a commitment,
                      and never delete a capability merely because no material has used one
                      yet. Two settle where an expression starts and where precision belongs —
                      in the open mechanisms first, and at the edge, where a line range or a
                      revision hash is explicit and validated. One cost alone scales with the
                      core: the conformance surface every tool must handle forever."
              collapsed_summary "Four rules apply the razor to every proposed addition — delete
                                commitments, never delete capabilities, start an expression in
                                the open mechanisms, keep boundedness at the edge — against the
                                one cost that really scales."
              preview_summary "The four rules verbatim, and the argument that the conformance
                              surface is a reason to hold an expression in `meta` and never a
                              reason to make it inexpressible."

              content face.bullets
                - Delete a **commitment** — it forecloses material the author never saw.
                - Never delete a **capability** for want of an example; weaken its form instead.
                - A new expression starts in [`kind`, `props` and `meta`](#wl.weakness.props_meta), never in core grammar.
                - Boundedness lives at the **edge**: open dimensions stay strings, protocol facts are validated.
                - The one cost that scales is the **conformance surface** every tool must handle forever.
              end content

              content markdown
                The four rules follow, and they govern every addition:

                - **Weaken by deleting commitments.** A construct that decides something the
                  material does not force adds form and shrinks extension.
                - **Never delete a capability for want of an example.** Ask instead whether it is
                  in its weakest form.
                - **A new expression starts in the open mechanisms.** `kind`, `props` and `meta`
                  cost the core nothing and cannot be wrongly shaped. An expression is promoted to
                  core grammar only when real material has shaped it — because speculative
                  machinery is rarely wrong to exist, and frequently wrong in its shape, and a
                  wrongly-shaped core field is paid for by every tool forever.
                - **Boundedness lives at the edge.** Open-ended dimensions — domain vocabulary,
                  material formats, locators — stay strings resolved by convention. Real protocol
                  facts, like a line range or a revision hash, are explicit and validated.

                The cost that does scale is the **conformance surface**: every construct the core
                names is one every tool must handle. That is the argument for holding expressions
                in `meta` — never the argument for making them inexpressible.
              end content
            }
          }

          unit wl.weakness.props_meta kind document.mechanism "props and meta" {
            ref     "5"
            name "props/meta"
            meta icon "🧷"
            summary "The core admits only ground truth. Everything subjective,
                    interpretive or renderer-facing rides two open mechanisms, split by
                    cardinality, not importance: props holds one typed scalar per key,
                    meta accumulates repeatable annotations under a free kind — so
                    fields like risk, status, time and value live here rather than in
                    the core. Two further conventions ride the same mechanisms rather
                    than the grammar, each in its weakest form until real material
                    settles its shape: that is what makes the razor affordable, because
                    an opinion always has a home outside the core."
            collapsed_summary "Anything subjective, interpretive or renderer-facing rides
                              props (typed scalars) or meta (repeatable annotations), two
                              open mechanisms whose keys and kinds the core never
                              interprets."
            preview_summary "The TransportPool example verbatim, the cardinality split
                            between the two, the seven fields a schema-first design
                            would have promoted into the core, and two conventions in
                            full: the author's brief for unwritten parts, and provenance
                            back to the material."

            content face.bullets
              - The core admits only ground truth; opinions like risk, severity, status, time, value, actor and condition ride here instead.
              - [Authorial intent](#wl.weakness.props_meta.intent) is one convention riding these mechanisms: the brief for parts not yet written.
              - [Provenance](#wl.weakness.props_meta.provenance) is the other: the step back from a summary phrase to its material.
            end content

            content weave
              unit pool kind software.component "TransportPool" {
                summary "Process-global transport cache keyed by upstream."
                props { language "Go"  public true  score 0.91 }   // typed scalars
                meta point     "lazy creation on first call"        // repeatable, free kind
                meta point     "mutex-protected map"
                meta attention "process-global singleton"
                meta risk      "medium"                             // a judgment, so meta
              }
            end content

            content markdown
              `props` carries typed scalars; `meta` carries repeatable annotations. Fields like
              `risk`, `severity`, `status`, `time`, `value`, `actor`, and `condition` are not
              core language — they are opinions, workflow state, or domain facts, and they live
              here under whatever convention applies. A renderer that knows the convention may
              style them; one that does not ignores them.

              The split is cardinality, not importance:

              | | `props` | `meta` |
              | --- | --- | --- |
              | written as | `props { language "Go" }` | `meta point "mutex-protected map"` |
              | carries | typed scalars | annotations under a free kind word |
              | cardinality | one value per key | repeatable — the same kind many times on one unit |
              | it answers | what the value of this key is | what has been noticed |
              | the core's opinion of the key or kind | none | none |

              An event is `unit kind event { props { time "…" } }`. A desired state is
              `unit kind state { props { value "3 replicas" } }`. The core stays out of both.
            end content

            unit wl.weakness.props_meta.intent kind document.convention "Authorial intent" {
              ref     "5.1"
              name "Authorial intent"
              meta icon "🎯"
              summary "An author of an unfinished weave needs to say things about parts
                      not yet written: who may write them, what they must not become,
                      how firmly the words are meant. These are expressions the purpose
                      requires, but not core grammar, because no real material has
                      shaped them yet — so the brief lives as five conventions on meta
                      and props, and the core has no opinion about any of them. Negative
                      space is the one a generator cannot infer, because a summary never
                      states what a part must NOT become."
              collapsed_summary "Five conventions on meta and props carry the brief for a
                                part not yet written — who may write it, what it must not
                                become, how firmly the words are meant — and negative space
                                is the one a generator cannot infer."
              preview_summary "Inside: §5.1 verbatim — the `cap.serve` example carrying
                              all five conventions, and the closing case for why
                              negative space alone cannot be inferred — beside a table
                              pairing each annotation with what it settles and its
                              words."

              content face.bullets
                - Five conventions on meta and props carry the brief: who may write a part, what it must not become, how firmly it's meant.
                - Negative space is the one of the five a generator cannot infer — nothing in a summary states what a part must NOT become.
                - `meta hand` records who wrote it: human, model, or `importer.<name>` — so authorship is never guessed.
              end content

              content weave
                unit cap.serve kind software.capability "Serving a slug" {
                  summary "A request for a retired slug redirects permanently to its successor."

                  meta infer  "allowed"          // may a generator write this described part?
                                                 // allowed · ask · forbidden · stub · convention
                  meta avoid  "slug reuse"       // negative space: what it must NOT become.
                  meta avoid  "redirect chains"  // repeatable, because a brief has many edges.
                  meta intent "strict"           // how firmly the words are meant.
                                                 // strict · normal · loose · exploratory
                  meta hand   "human"            // who wrote this: human · model · importer.<name>
                  props { locked true }          // do not regenerate, whatever else is asked.
                }
              end content

              content markdown
                | annotation | what it settles | its words |
                | --- | --- | --- |
                | `meta infer` | may a generator write this described part | `allowed` · `ask` · `forbidden` · `stub` · `convention` |
                | `meta avoid` | negative space: what it must NOT become | free text, repeatable |
                | `meta intent` | how firmly the words are meant | `strict` · `normal` · `loose` · `exploratory` |
                | `meta hand` | who wrote this | `human` · `model` · `importer.<name>` |
                | `props locked` | do not regenerate, whatever else is asked | a boolean |

                **Negative space is the one of these that cannot be inferred.** A summary states
                what a part is; nothing in it states what the part must not become. An author who
                knows that a plausible, conventional, wrong answer exists — social login, a
                redirect chain, a retry on a non-idempotent method — has no other way to rule it
                out, and a generator will produce it.
              end content
            }

            unit wl.weakness.props_meta.provenance kind document.convention "The provenance record" {
              ref     "5.2"
              name "Provenance"
              meta icon "🔎"
              summary "Where a producer can track which span of a unit's material a
                      summary phrase came from, recording it lets a reader step from an
                      interpretation to the material in one action. Two facts hold at
                      once: the capability is required, because an unchecked summary is
                      the format's risk, and the shape is not settled, because no corpus
                      has shaped the offsets yet. So the record stays one string under a
                      convention — pairing a summary range with a content range — never
                      core grammar, and a tool without the key skips the step-down."
              collapsed_summary "A summary phrase can record the span of material it came
                                from, as a string under a convention rather than core
                                grammar, because the capability is required and the shape is
                                not yet settled."
              preview_summary "Inside: the `derived_from` snippet verbatim from §5.2, and
                              a table asking the same two questions of the capability
                              and the shape — required, unsettled — and what a tool does
                              either way."

              content face.table
                | the question | the answer |
                | --- | --- |
                | Is the capability required? | **Yes** — an uncheckable summary is the format's central risk |
                | Is the shape settled? | **No** — no corpus has shaped the offsets yet |
                | So what carries it? | one string in `props`, under a convention |
              end content

              content weave
                props {
                  derived_from "summary 7..44 → content 210..268"
                }
              end content

              content markdown
                | the question | the answer, and why the form follows from it |
                | --- | --- |
                | Is the capability required? | **Yes** — a summary that cannot be checked against its own material is the format's central risk. |
                | Is the shape settled? | **No** — no real corpus has yet shaped the offsets, and guessing now is how a core field comes out wrong. |
                | So what carries it? | A string under a convention, in `props`. The weakest form that still expresses it. |
                | What does a tool do without it? | It does not offer the step-down. Nothing else changes. |

                Required-but-unsettled is exactly the pair [the third rule of the razor](#wl.weakness.razor.rules)
                answers: never delete the capability for want of an example, and hold it in its
                weakest form until real material shapes it.
              end content
            }
          }

          unit wl.weakness.nongoals kind document.boundary "The five refusals" {
            ref     "14"
            name "Non-goals"
            meta icon "⛔"
            summary "At some boundaries the honest move is not to weaken a claim but to
                    decline it, and WeaveLang declines five — standing in for a
                    modelling standard, or guaranteeing a summary is correct, among
                    them. Each refusal is the razor reaching a commitment too large to
                    make: no observed case forces it, so none is made. The refusals are
                    the enabling condition for what the language does do: a `content`
                    block stays opaque, never parsed, evaluated or type-checked, so a
                    function, a diagram, and a chapter are the same kind of part."
            collapsed_summary "WeaveLang is not a programming language, a source-code
                              replacement, a stand-in for UML, BPMN, RDF, OpenAPI or
                              tracing, a visual notation, or a correctness guarantee — and
                              a content block stays opaque, which is how it carries code."
            preview_summary "Inside: §14 verbatim — the five refusals and the opacity
                            rule — a table costing out two of them, and a diagram
                            showing a Go function, a BPMN process and a novel's chapter
                            as the same kind of part."

            content face.bullets
              - Not a programming language, and not a replacement for source code.
              - Not a replacement for UML, BPMN, RDF, OpenAPI, or tracing systems.
              - Not a visual notation, and not a guarantee that a generated summary is correct.
              - Standing in for a modelling standard would force the core to hold opinions about its own subject matter.
              - A `content` block stays opaque — never parsed, evaluated, or type-checked — which is how it carries code without becoming one.
            end content

            content markdown
              WeaveLang is not a programming language, not a replacement for source code, not a
              replacement for UML, BPMN, RDF, OpenAPI, or tracing systems, not a visual
              notation, and not a guarantee that a generated summary is correct.

              Two of those refusals show what the others cost, if the commitment were made:

              | the claim declined | the commitment it would require |
              | --- | --- |
              | standing in for a modelling or interface standard | the core would have to hold opinions about that standard's subject matter |
              | guaranteeing that a generated summary is correct | the core would have to evaluate the material it is summarising |

              It carries source code without becoming one. A `content` block is opaque to the
              core: the language never parses, evaluates, or type-checks what is inside it. It
              only knows where the material sits in the structure of meaning.
            end content

            content diagram
              ┌── the core knows ────────────────────────────────────────┐
              │  WHERE this part sits in the structure of meaning,       │
              │  and one free kind string beside it. Nothing else.       │
              └───────────┬──────────────────┬──────────────────┬────────┘
                          │                  │                  │
                     content go        content bpmn       content prose
                 ┌────────────────┐ ┌────────────────┐ ┌────────────────┐
                 │  func Get(u)…  │ │  <bpmn:proc…>  │ │  On an exce…   │
                 └────────────────┘ └────────────────┘ └────────────────┘

                 never parsed · never evaluated · never type-checked
                 ⇒ all three are the same kind of part
            end content
          }
        }

    unit wl.conventions kind document.vocabulary "Shared vocabulary" {
      ref "6"
      name "Conventions"
      meta icon "🤝"
      summary "A convention is a named vocabulary a community converges on — kinds,
               verbs, form words, selector words — and it adds no syntax. A `use profile`
               declares the intent and cannot fail; a kind is a string, so an unfamiliar
               one still parses. Agreement buys specific tool behaviour, at
               every grain: ten published vocabularies, the parts inside one symbol,
               render hints, and a policy that retires a term without stranding a weave.
               Every one carries the same asymmetry — agreement may be absent, unknown,
               wrong or out of date, and no weave is ever invalid."
      collapsed_summary "A convention is a named vocabulary tools agree on; the core
                         checks only that a kind is a well-formed identifier, so an
                         unfamiliar term still parses, still renders — generically if
                         unknown — and is never dropped."
      preview_summary "Inside: the use-profile declaration and why it cannot fail; the
                       open-kind rule; the four-way payoff; ten published vocabularies
                       with their core and domain listings; sub-symbol names; render
                       hints; and the patch/minor/major versioning policy."

      content face.bullets
        - A use profile in the header states intent and cannot fail — [the mechanism](#wl.conventions.profile).
        - A kind is a string, not an enum, so an unfamiliar one still parses — [open kinds](#wl.conventions.open_kinds).
        - Agreement buys tools something specific instead of something generic — [the payoff](#wl.conventions.payoff).
        - [Published vocabularies](#wl.conventions.published) name a domain; [sub-symbol names](#wl.conventions.subsymbol) and [render hints](#wl.conventions.hints) go finer still.
        - A vocabulary versions semantically, so a retired term never strands a weave — [versioning](#wl.conventions.versioning).
      end content

      content markdown
        | a convention supplies | it lands on | as in |
        | --- | --- | --- |
        | **kinds** for units | `kind` on a [`unit`](#wl.constructs.unit) | `software.service` |
        | **verbs** for relations | `kind` on a [`relation`](#wl.constructs.relation) | `software.reads` |
        | **[form words](#wl.material.form)** for material | the word after `content` | `content go` |
        | **[selector words](#wl.named.selectors)** for regions | the word after `region` | `region lines 40..92` |

        Not one of the four is fetched, bound, or checked against a list by the core.
      end content

      unit wl.conventions.profile kind document.mechanism "The use profile" {
        ref "6"
        name "use profile"
        meta icon "🪪"
        summary "Declaring a profile is one statement in the header — use profile
                 weave.software — and a weave may declare several. An optional version
                 clause names the release it was written against. Neither resolves
                 anything: nothing is fetched, bound, or checked against a registry, so
                 an unpublished name or version still leaves the weave valid. It is a
                 declaration of intent, not an import that can fail; a weave that invents
                 every kind and declares none is equally valid. The statement only tells
                 a reader which vocabulary to try first."
        collapsed_summary "A use profile line names the vocabulary a weave intends to use,
                           optionally with a version string; it binds nothing, resolves
                           nothing, and a weave that declares none is still valid."
        preview_summary "Inside: a two-line worked example declaring two profiles at
                         once, and a diagram naming each part of the statement — the
                         vocabulary, its optional version — and what each one resolves."

        content face.diagram
          use profile weave.software version "2.1"
             ▲                          ▲
             name: fetches nothing      optional: names a version, resolves nothing
          one header statement · adds no syntax · cannot fail
        end content

        content weave
          weave "Example" {
            use profile weave.software
            use profile weave.security
          }
        end content

        content diagram
          use profile weave.software version "2.1"
          ─────┬───── ──────┬─────── ──────┬──────
               │            │              │
               │            │              └─ optional. Names the
               │            │                 vocabulary version this
               │            │                 weave was written
               │            │                 against (§6.6). Like the
               │            │                 name, it resolves nothing.
               │            │
               │            └─ a name. Nothing is fetched and nothing is
               │               bound; no name is checked against a
               │               registry.
               │
               └─ a statement in the weave body. A unit body has no use.
        end content
      }

      unit wl.conventions.open_kinds kind document.rule "Kinds as strings" {
        ref "6.1"
        name "Open kinds"
        meta icon "🔤"
        summary "The core validates only that a kind is a well-formed identifier,
                 nothing more. A weave using kind acme.sla_tier parses, validates, and
                 renders — generically if the term is unknown, specifically if known —
                 and an unknown term is preserved verbatim, never dropped, rewritten, or
                 rejected. This is not tolerance but a claim about the future: a closed
                 list would be wrong the first time material names a subject nobody
                 imagined, so refusing an unfamiliar noun forecloses subjects in
                 advance."
        collapsed_summary "A kind only has to be a well-formed identifier; an unknown one
                           parses, renders generically, and is kept verbatim, because any
                           closed list would exclude subjects nobody has woven yet."
        preview_summary "Inside: the full six-row comparison — parser, core validation,
                         convention validation, a renderer, a round-trip, and being
                         dropped — for a known kind against acme.sla_tier, an unknown
                         one, and why the gap between the columns is never the core's to
                         notice."

        content face.table
          | | `software.service`, known | `acme.sla_tier`, unknown |
          | --- | --- | --- |
          | parses and validates | yes | yes |
          | a renderer draws it | specifically | generically |
          | round-trips, never dropped | verbatim | verbatim |
        end content

        content markdown
          | what the kind meets | `software.service`, known to the tool | `acme.sla_tier`, unknown to it |
          | --- | --- | --- |
          | the parser | accepted | accepted |
          | core validation | a well-formed identifier, and nothing more | a well-formed identifier, and nothing more |
          | convention validation | passes | a warning at most, never an error (§9) |
          | a renderer | renders it specifically | renders it generically |
          | a round-trip | verbatim | verbatim |
          | being dropped, rejected, or rewritten to the nearest familiar kind | never | never |

          The right-hand term was invented by one company for one weave. The two columns
          part only where a tool's own knowledge parts; to the core they are the same
          string, and which column a kind falls in is not a property of the kind. Refusing
          a closed list is [the weakness razor](#wl.weakness.razor)'s largest single
          application: the core commits to nothing today's data does not force.
        end content
      }

      unit wl.conventions.payoff kind document.rationale "What agreement buys" {
        ref "6.2"
        name "The payoff"
        meta icon "🧰"
        summary "Agreement lets a tool act specifically instead of generically, without
                 the language learning anything about the term. Explorers render a known
                 kind expressively and fall back to a plain card otherwise; analyzers
                 answer questions meaningless in general; compilers treat a known kind
                 as a target; search and merge make two teams' weaves comparable without
                 coordinating. The unknown case still works, only generically — the
                 deliberate trade: a convention that guesses wrong costs one renderer a
                 fallback, a core that guesses wrong costs the language a subject it can
                 never express."
        collapsed_summary "Agreement lets explorers, analyzers, compilers, and merge do
                           something specific rather than generic, and the failure of a
                           convention costs a fallback while a failure of the core costs
                           a subject."
        preview_summary "Inside: the verbatim four-way breakdown — explorers, analyzers,
                         compilers, and merge — of what agreement buys each, and the
                         asymmetric-cost drawing: a wrong convention pays once, a wrong
                         core pays forever."

        content face.diagram
          a convention that guesses wrong   a core that guesses wrong
          ┌───────────────────────────┐    ┌───────────────────────────┐
          │ one renderer falls back   │    │ one subject the language  │
          │ to a plain card           │    │ can never express         │
          └───────────────────────────┘    └───────────────────────────┘
             paid once, by one tool           paid forever, by everyone
        end content

        content markdown
          - **Explorers** render a known kind expressively — a cylinder for a database, a
            diff surface for a changed function — and fall back to a plain card otherwise.
          - **Analyzers** answer questions that are meaningless in general and obvious inside
            a convention: which services read this table, which requirements have no
            implementing unit, which described units still need writing.
          - **Compilers** treat a known kind as a target. `software.function` with material
            is a file to write; `go.fields` that is described is a declaration to generate.
          - **Search and merge** work because two teams that both say `software.endpoint`
            have made their weaves comparable without coordinating.
        end content

        content markdown
          The described units an analyzer looks for are not a special case: they are
          [ordinary described units](#wl.material.described), the same construct that
          lets any part of a weave stand as a brief instead of bytes.
        end content
      }

      unit wl.conventions.published kind document.registry "Published vocabularies" {
        ref "6.3"
        name "Published vocabularies"
        meta icon "📖"
        summary "Ten conventions are published, each at a stable URI — the registry, not
                 this document, is the list. Terms split into two layers by whether a
                 word depends on a subject: weave.core supplies the kinds anything can
                 be and the verbs any two things can stand in, enough alone for a
                 subject no convention covers; a domain convention adds only the words
                 its own subject already uses, never replacing the core. weave.book also
                 publishes fully woven, a whole-weave property checked by hashing the
                 leaves against the source, never merely asserted."
        collapsed_summary "Ten conventions publish their terms at stable URIs, with
                           weave.core carrying subject-independent kinds and verbs and the
                           domain conventions adding the nouns their own field already
                           uses."
        preview_summary "Inside: weave.core's representative kinds and verbs; four
                         domain listings for software, book, document, and history; the
                         ten-name registry a stable URI backs; and weave.book's
                         fully-woven property, checkable by hash."

        content face.bullets
          - weave.core supplies the words that don't depend on a subject — [core kinds](#wl.conventions.published.core_kinds).
          - A domain convention adds only the words its own subject already uses — [domain kinds](#wl.conventions.published.domain_kinds).
          - Ten names are published today; the registry, not this page, is the list — [the registry](#wl.conventions.published.registry).
          - weave.book also publishes fully woven, a whole-weave property checked by hashing, never asserted.
        end content

        content markdown
          Each publishes its terms at a stable URI; the registry, not this document, is the
          list.

          A convention may also publish a named property of whole weaves. `weave.book`
          publishes **fully woven**: the union of the leaf units' literal material
          reproduces the work verbatim — normalized only for typesetting artifacts such
          as hard line-wraps — so the deepest layer *is* the book. A book weave that is
          not fully woven says so in its top unit.
        end content

        content diagram
          weave.software  weave.cloud  weave.security  weave.book
          weave.document  weave.news   weave.history   weave.llm_response
          weave.argument
              │
              │  each adds the words only its own subject has —
              │  adds to the core, never replaces it
              ▼
          weave.core
              the kinds anything can be, and the verbs any two things
              can stand in — enough alone for a subject no published
              convention covers
        end content

        unit wl.conventions.published.core_kinds kind document.vocabulary "The weave.core vocabulary" {
          ref "6.3"
          name "Core kinds"
          meta icon "🧱"
          summary "weave.core is the vocabulary that holds for any subject, in two
                   halves. Its unit kinds name what a thing can be — thing, actor,
                   claim, risk, decision, and twelve more — so any subject is writable
                   in core terms alone. Its relation kinds name how two things stand to
                   each other, grouped into six kinds of claim, from structural to
                   temporal, with relates_to reserved for an unclaimed connection. The
                   listing is representative; the registry's URI carries the whole of
                   it."
          collapsed_summary "weave.core names the kinds of thing anything can be and the
                             verbs any two things can stand in, so any subject is writable
                             without a domain convention."
          preview_summary "Inside: the full verbatim word lists — seventeen unit kinds,
                           twenty relation kinds — and a table grouping every verb by
                           the kind of claim it makes, from structural to temporal to
                           unclaimed."

          content face.bullets
            - weave.core's unit kinds name what a thing can be — thing, actor, claim, risk, decision, and twelve more.
            - Its relation kinds name how two things stand to each other, grouped into six kinds of claim.
            - `reveals` and `cites` are spelled the same as fields on a unit, so one fact may be a field or a relation.
            - The listing here is representative; the registry's URI carries the whole of it.
          end content

          content txt
            units      thing concept entity actor system boundary process event state
                       claim question risk decision requirement metric location collection
            relations  relates_to part_of depends_on causes prevents enables blocks
                       supports contradicts qualifies summarizes refines reveals cites
                       derived_from attributed_to located_in before after during overlaps
          end content

          content markdown
            The verbs group by the sort of claim being made:

            | the claim | the verbs |
            | --- | --- |
            | structural | `part_of`, `depends_on` |
            | causal | `causes`, `prevents`, `enables`, `blocks` |
            | argumentative | `supports`, `contradicts`, `qualifies` |
            | editorial | `summarizes`, `refines`, `reveals`, `cites` |
            | attributive | `derived_from`, `attributed_to`, `located_in` |
            | temporal | `before`, `after`, `during`, `overlaps` |
            | none — the author is not claiming one | `relates_to` |

            `reveals` and `cites` are spelled the same as fields on a unit, so the same fact
            may be recorded either as a field or as a relation.
          end content
        }

        unit wl.conventions.published.domain_kinds kind document.vocabulary "Domain vocabularies" {
          ref "6.3"
          name "Domain kinds"
          meta icon "🗣"
          summary "A domain convention publishes the nouns its own subject already uses,
                   in four representative listings. software runs from systems to a
                   function and outward to api, database, and queue. book covers a
                   work's structure and what a reader follows through it. document names
                   the parts of a specification, including two judgement terms, error
                   and ambiguity. history names arcs and periods with cause,
                   consequence, and interpretation. None of these words is invented for
                   the language; each is a field's own vocabulary."
          collapsed_summary "Each domain convention publishes the nouns its subject
                             already uses — services and endpoints, chapters and motifs,
                             clauses and ambiguities, periods and consequences."
          preview_summary "Inside: the verbatim word lists for software, book, document,
                           and history, and a drawing of event and actor recurring from
                           weave.core into weave.history under a different owner."

          content face.bullets
            - software runs from whole systems to a single function, then outward to api, database, and queue.
            - book covers a work's structure — part, chapter, scene — and what a reader follows through it.
            - document names the parts of a specification, including two judgement terms: error and ambiguity.
            - history names arcs and periods together with cause, consequence, and interpretation.
          end content

          content txt
            software   system domain capability service module component class function
                       api endpoint database table queue worker test config deployment
            book       work part chapter scene paragraph character theme motif turning_point
            document   spec clause definition requirement mechanism field error ambiguity
            history    arc period event actor cause consequence interpretation document
          end content

          content diagram
            event and actor are core kinds that history uses again

              weave.core     ─▶  kind event          kind actor
              weave.history  ─▶  kind history.event  kind history.actor

            the convention that owns a term tells the two apart; the
            word alone does not
          end content
        }

        unit wl.conventions.published.registry kind document.registry "The registry" {
          ref "6.3"
          name "The registry"
          meta icon "📇"
          summary "Ten conventions are published today: weave.core underneath all of
                   them, weave.software, weave.cloud and weave.security for running
                   systems, weave.book, weave.document and weave.news for written works,
                   and weave.history, weave.llm_response and weave.argument for subjects
                   that are neither. Each publishes its terms at a stable URI, and the
                   registry, not this document, is the list, so this enumeration may go
                   stale without anything breaking. Naming a convention buys nothing at
                   parse time; its value is to an author, who discovers a subject
                   already has a vocabulary instead of coining a private set no tool
                   will recognise."
          collapsed_summary "Ten conventions are published by name, each with its terms at
                             a stable URI, and the registry rather than this document is
                             the authoritative list."
          preview_summary "Inside: the verbatim ten-name list, grouped here into what
                           sits under everything, what runs systems, what is a written
                           work, and what is neither."

          content face.bullets
            - weave.core sits under all of them.
            - weave.software, weave.cloud, and weave.security cover running systems.
            - weave.book, weave.document, and weave.news cover written works.
            - weave.history, weave.llm_response, and weave.argument cover subjects that are neither.
          end content

          content markdown
            `weave.core`, `weave.software`, `weave.cloud`, `weave.security`, `weave.book`,
            `weave.document`, `weave.news`, `weave.history`, `weave.llm_response`,
            `weave.argument`.

            Each publishes its terms at a stable URI; the registry, not this document, is the
            list.
          end content

          content markdown
            - **The ordering is the point.** This page names the set at the moment it was written; the registry names it now, so the enumeration may go stale without anything breaking.
            - **A convention the registry holds and this page never mentions is in no way lesser.** Publication is a fact about tooling, not about validity.
            - **Naming one buys nothing at parse time.** A published kind and one invented an hour ago are [the same string to the core](#wl.conventions.open_kinds).
            - **Its value is to an author**, who can discover that a subject already has a vocabulary and use those words instead of coining a private set no other tool will recognise.
          end content
        }
      }

      unit wl.conventions.subsymbol kind document.vocabulary "The sub-symbol vocabulary" {
        ref "6.4"
        name "Sub-symbol kinds"
        meta icon "🔬"
        summary "Material composes from parts, so a convention may name parts smaller
                 than a whole symbol. weave.software publishes eight such terms for the
                 common languages, from declaration and imports at the top to guard,
                 branch, loop, and error_path in the body, down to fields for a type's
                 own members. Published per language, they wear a language prefix in
                 use, as in go.fields. They are ordinary kinds and carry no special
                 meaning to the core, which does not know that a guard usually precedes
                 a body."
        collapsed_summary "A convention may name the parts of a single symbol —
                           declaration, fields, branch, loop, guard, error_path, imports,
                           body — so a tool knows what a described part should be written
                           as."
        preview_summary "Inside: the verbatim eight-term glossary from declaration to
                         body, and a Go function wearing each term as a language prefix,
                         line by line."

        content face.diagram
          in use they wear a language prefix
          go.declaration   func Fetch(u string) (*Res, error) {
          go.guard           if u == "" { return nil, ErrEmpty }
          go.error_path      if err != nil { return nil, wrap(err) }
                           }
          each term is an ordinary kind; the core knows no order among them
        end content

        content txt
          declaration   the opening line of a type, class, or function
          fields        a run of struct or class members
          branch        one arm of a conditional
          loop          a loop body
          guard         an early return or precondition check
          error_path    the handling of a failure case
          imports       an import or include block
          body          the remainder of a symbol's implementation
        end content

        content diagram
          in use they wear a language prefix

          go.imports       import ( … )
          go.declaration   func Fetch(u string) (*Res, error) {
          go.guard           if u == "" { return nil, ErrEmpty }
          go.body            res, err := do(u)
          go.error_path      if err != nil { return nil, wrap(err) }
          go.branch          if res.Cached { return res, nil }
          go.loop            for _, h := range res.Hooks { h(res) }
                           }

          go.fields does the same for a type's members. The core knows
          none of this order: each term is an ordinary kind.
        end content

        content markdown
          Their value shows up on a described unit: a tool reading `kind go.fields` on a
          unit with no material knows it is asking for struct members, not prose, and
          can [offer to write them](#wl.tools.fill).
        end content
      }

      unit wl.conventions.hints kind document.mechanism "Rendering hints" {
        ref "6.5"
        name "Rendering hints"
        meta icon "🎨"
        summary "A convention may suggest an icon, a colour, a shape, an edge marker, or
                 a layout preference for a kind, and a unit may carry an icon of its own,
                 which outranks it. A renderer may ignore any hint, because it suggests
                 presentation, never a fact about the subject, but must preserve one on
                 round-trip, so no tool deletes it for the next tool that can use it.
                 None are core fields; the semantic model stays useful with
                 every hint stripped, so a picture of a weave renders the meaning and
                 never stores it."
        collapsed_summary "Icons, colours, shapes, edge markers and layout preferences are
                           convention-level suggestions on a kind — and one glyph a unit
                           may carry for itself — that a renderer may ignore and must
                           preserve; none of them are core fields."
        preview_summary "Inside: a verbatim example styling software.database and the
                         blocks relation with an icon, a shape, a colour, and a head
                         marker, a unit carrying its own glyph, and the ignore/preserve
                         rule that governs every hint."

        content face.table
          | a renderer | the hint |
          | --- | --- |
          | **may ignore** it | a suggestion about presentation, never the subject |
          | **must preserve** it on round-trip | the next tool may be able to use it |
          | never reads meaning from it | the model stays whole with every hint stripped |
        end content

        content weave
          kind software.database { icon "database"  shape cylinder  color "#0f766e" }
          relation_kind blocks   { head_marker bar }

          unit ch5.p4 kind book.passage "The magneto line halves and halves again" {
            name "The magneto line"
            meta icon "⚙"
          }
        end content

        content markdown
          A hint hangs on a [`kind`](#wl.conventions.open_kinds). The one exception is
          `meta icon`: one glyph a unit carries for itself, which outranks its kind's icon
          and sits one rung below [`name`](#wl.constructs.name) on the display ladder —
          what a box shows when it cannot hold two small words. Either way, the two
          obligations a hint places on a renderer run in opposite directions:

          | a renderer | because |
          | --- | --- |
          | **may ignore** any hint | a hint is a suggestion about presentation, never a fact about the subject |
          | **must preserve** every hint it round-trips | a tool that cannot use a hint must not delete it for the next tool that can |

          None of them are core fields, and the reason is a property the language keeps by
          construction: the semantic model stays useful with every visual hint stripped. A
          picture of a weave is therefore always a rendering of the meaning, never a place
          any of the meaning is kept — which is why [a renderer's own output is a query
          result](#wl.tools.render) and not a fact about the subject.
        end content
      }

      unit wl.conventions.versioning kind document.policy "Vocabulary versioning" {
        ref "6.6"
        name "Versioning"
        meta icon "🔢"
        summary "Conventions follow semantic versioning: patch for wording and icons,
                 minor for new kinds, major for removed terms or changed semantics, and
                 only major can strand an already-written weave. Removal is done by
                 marking rather than deleting, and the two consumers then part ways on
                 purpose: renderers keep rendering the deprecated term, so an old weave
                 still displays as it always did, while validators warn, so its author
                 learns a newer word exists. Nothing forces the migration: a weave
                 written against an old version stops being current, but never stops
                 being readable."
        collapsed_summary "Vocabularies version semantically and retire a term with
                           deprecated true and replaced_by, so renderers keep rendering it
                           while validators warn."
        preview_summary "Inside: the patch/minor/major table of what each level may
                         change and break, and a worked example marking
                         software.microservice deprecated in favour of
                         software.service."

        content face.table
          | level | what may change | what it can break for a reader |
          | --- | --- | --- |
          | patch | wording and icons | nothing |
          | minor | new kinds | nothing |
          | major | removed terms or changed semantics | a weave already written |
        end content

        content markdown
          Only major can strand a weave, so a retired term is marked rather than
          deleted, and the two consumers then part ways on purpose:

          - **Renderers** keep rendering the deprecated term, so an old weave still
            displays as it always did.
          - **Validators** warn, so the author of that weave learns a newer word exists and
            can migrate when it suits them.
        end content

        content weave
          // an illustration: a retired term stays in the vocabulary, marked
          kind software.microservice {
            deprecated  true
            replaced_by software.service
          }
        end content
      }
    }

    unit wl.notation kind document.notation "The notation" {
      ref     "7, 7.1, 7.2, 7.3, 7.4, 7.5, 7.6, 8"
      name "Notation"
      meta icon "✒"

      summary "WeaveLang has one text form and one canonical JSON. The text form rests
               on seven symbol forms and one statement rule keyed to the token after the
               head, a stable identifier pattern, and the single place whitespace
               carries meaning; fourteen EBNF productions fix the whole of it, none
               naming a domain word. The JSON form is that same material in a parts
               array preserving its order. Both surfaces answer to one asymmetry: a tool
               may rewrite everything about how a weave is spelled, and nothing about
               what it says."

      collapsed_summary "The language is written with seven symbols and otherwise plain words,
                         compiles to a canonical JSON whose parts array preserves material
                         order, and lets a tool normalise every aspect of form while forbidding
                         it to touch a byte of material."

      preview_summary "Inside: the seven-symbol table, six statement shapes keyed by the
                       token after the head, the identifier pattern and the six things a
                       stable id buys, the one dedent that is significant whitespace,
                       the fourteen-production grammar, the JSON parts array, and the
                       seven canonicalization guarantees."

      content face.bullets
        - [Seven symbols](#wl.notation.symbols), no more, and [six statement shapes](#wl.notation.statements) pick the rest.
        - [One id pattern](#wl.notation.identifiers) stays stable; [one dedent](#wl.notation.textblocks) is the only meaningful whitespace.
        - [Fourteen productions](#wl.notation.grammar) fix the grammar, none naming a domain word.
        - [One canonical JSON](#wl.notation.json) keeps the parts array in material order.
        - [Seven guarantees](#wl.notation.canonicalization) bound a tool: rewrite spelling, never what a weave says.
      end content

      content diagram
        THE HUMAN SURFACE                  THE MACHINE SURFACE
        ─────────────────                  ───────────────────
        seven symbol forms; every          one object: units,
        other token is a word              relations, sources

        one statement rule — the           one parts array per unit,
        token after the head               part by part, in the order
        decides the shape                  of the material

        fourteen EBNF productions,         described, and named, are
        not one naming a domain word       read from the shape of that
                                           array and never from a flag

                     └──────────── ONE FORM ────────────┘

        ┌───────────────────────────────────────────────────────┐
        │ a tool may rewrite  HOW A WEAVE IS SPELLED            │
        │   unit order, ids, convention names, shorthand edges, │
        │   time formats, duplicate references                  │
        │                                                       │
        │ a tool may rewrite  NOTHING OF WHAT A WEAVE SAYS      │
        │   material is dedented, and never reflowed            │
        └───────────────────────────────────────────────────────┘
      end content

      unit wl.notation.symbols kind document.rule "The seven symbols" {
        ref     "7.1, 7.5"
        name "Symbols"
        meta icon "{"
        summary "A symbol that must be explained should not exist, so the whole
                 non-alphanumeric vocabulary is seven entries: braces open and close a
                 block, brackets open and close a list, the quote delimits a short
                 string, the comma separates list items, the arrow directs a shorthand
                 edge, two dots give a range, and the slash forms carry a line comment
                 and a block comment. Everything else — every keyword, kind, form word,
                 selector and relation verb — is a plain word, and a new capability
                 always arrives as one."
        collapsed_summary "Seven symbol forms, comments included, are the entire punctuation of
                           the language; everything else is a word, and additions must be words
                           too."
        preview_summary "Inside: the seven-entry symbol table verbatim from §7.1 and
                         §7.5, and two worked examples — the line and block comment
                         forms, then one snippet using all seven symbols at once."

        content face.bullets
          - Seven entries are the entire non-alphanumeric vocabulary — comments included.
          - Everything else is a word: keyword, kind, form word, selector, relation verb.
          - The rule for growth: if a reader must be taught a character, use a word instead.
        end content

        content txt
          { }        open and close a block
          [ ]        open and close a list
          "          delimit a short string
          ,          separate list items
          ->         direct a shorthand edge
          ..         a range between two values
          //  /* */  comments
        end content

        content weave
          // line comment
          /* block comment */
        end content

        content weave
          // all seven, once each
          /* the comment forms are two of the seven */
          weave "every symbol" {
            unit u kind k "Title" {           // { } a block, " a short string
              cites [a, b, c]                 // [ ] a list, , separates items
              content txt in src {
                region lines 10..24           // .. a range between two values
              }
            }
            edge a -> b kind calls "reads"    // -> directs a shorthand edge
          }
        end content
      }

      unit wl.notation.statements kind document.rule "Statement shapes" {
        ref     "7.2"
        name "Statement shapes"
        meta icon "¶"
        summary "A statement runs to the end of its line, and the token after the head
                 decides its shape, so no keyword needs a rule of its own. The head is
                 fixed: keyword, optional id, kind, quoted title. Six shapes
                 follow, from a brace opening a block, through a bracketed list and a
                 quoted string, to an empty rest-of-line opening a text block. The same
                 rule covers a unit
                 declaration, an attribute, a props map and a content block — the one
                 place the notation splits material held in the file from material held
                 elsewhere."
        collapsed_summary "A statement runs to the end of its line, and the token after the head
                           — brace, bracket, quote, or nothing — decides whether the value is a
                           block, a list, a short string, or a text block."
        preview_summary "Inside: the six statement patterns verbatim from §7.2, a table
                         pairing each head token with the shape it opens, and a drawing
                         of the head's own anatomy beside the one line where a
                         named-material block diverges from a literal one."

        content face.table
          | the token after the head | what it opens |
          | --- | --- |
          | `{`, `[`, or `"` | an immediate value: a block, a list, or a short string |
          | end of line | a text block, verbatim in the file until `end <keyword>` |
          | `{` after a form word or `in <source>` | a named-material block, verbatim elsewhere |
        end content

        content txt
          <keyword> [id] [kind <kind>] ["Title"] [{ block }]
          <keyword> "short value"
          <keyword> [list, of, ids]
          <keyword> { key value }
          <keyword> [form-word] [in <source>]     // end of line opens a text block
          <keyword> [form-word] [in <source>] {   // a brace opens a named-material block
        end content

        content markdown
          Six shapes, and one token picks between them:

          | the token after the head | the form it opens | written like |
          | --- | --- | --- |
          | `{` | a block | `unit d kind go.struct "Directives" { … }` |
          | `"` | a short value | `summary "One knob per request."` |
          | `[` | a list of ids | `cites [d.retry, d.integrity]` |
          | `{` holding bare key-and-value pairs | a map — this is how `props` is written | `props { significance 87 }` |
          | end of line | a text block, running until an end line naming the same keyword | `content go` … `end content` |
          | `{` after a form word or an `in <source>` clause | a named-material block, not a literal one | `content go in pr.head { … }` |

          The last two are the single point where the two ways of holding material diverge
          in the notation: the same `content` keyword, and only the token after the head
          says whether the bytes are in the file or somewhere else.
        end content

        content diagram
          unit   d.retry   kind go.fields   "Retry knobs"   { … }
          ────   ───────   ──────────────   ─────────────   ─────
            │       │            │                │           │
            └───────┴────────────┴────────────────┘           │
                  THE HEAD: keyword, id, kind, title,         │
                  in that order                               │
                                                              │
                              what follows the head ──────────┘
                              decides the form

          content   go     in pr.head    { … }
          ───────   ──     ──────────    ─────
          keyword   form   the source    a brace here means the material
                    word   it lives in   is named, not written
        end content
      }

      unit wl.notation.identifiers kind document.rule "Stable identifiers" {
        ref     "7.3"
        name "Identifiers"
        meta icon "🔑"
        summary "Every renderable object carries a stable id drawn from one pattern: a
                 letter or underscore first, then letters, digits, underscores or
                 hyphens, in dot-separated segments. Uniqueness alone is not the point;
                 stability is — an id names the subject rather than its place in the
                 file. That stability lets a tool hold state about a subject while the
                 text around it changes: six operations, from locating one part to
                 merging an edit into a regenerated file, all reduce to it. Move the id
                 with the prose and every one collapses into fuzzy matching."
        collapsed_summary "One pattern defines the ids that every renderable object carries, and
                           their stability is what lets tools address, track, annotate, diff and
                           merge subjects across versions."
        preview_summary "Inside: the identifier regex verbatim from §7.3, a drawing of
                         the segment grammar beside valid and invalid examples, and the
                         bulleted list of six things a stable id buys a tool that fuzzy
                         text matching cannot."

        content face.bullets
          - One pattern: a letter or underscore, then letters, digits, underscores or hyphens, in dot-separated segments.
          - Uniqueness is not the point — stability is: an id names the subject, not its place in the file.
          - A stable id lets a tool hold state across edits: locate, track, annotate, diff, and merge a subject.
        end content

        content txt
          [a-zA-Z_][a-zA-Z0-9_-]*(\.[a-zA-Z_][a-zA-Z0-9_-]*)*
        end content

        content diagram
          segment  :=  [a-zA-Z_] [a-zA-Z0-9_-]*
                        │          └── letters, digits, underscores, hyphens
                        └───────────── a letter or an underscore, first
          id       :=  segment ( "." segment )*

          valid                      not valid
          ─────                      ─────────
          wl.notation.identifiers    2d        a digit cannot open a segment
          _internal                  d.        a segment cannot be empty
          d-2                        d e       a space is not in the pattern

          the dots are ordinary characters IN the pattern: a dotted id reads
          as a path, and nesting is still braces — never a namespace
        end content

        content markdown
          Uniqueness alone is not the point; stability is. Because an id names the subject
          and not its position in the file, six things become possible for a tool:

          - render a **focused view** of one part
          - **track** a subject across versions
          - **anchor comments** to it
          - **remember** which parts a reader had expanded
          - **diff** two generated weaves
          - **merge** a human edit back into a regenerated one

          Every one of those is the same operation — holding state about a subject while the
          text around it changes — and every one collapses into fuzzy text matching the
          moment ids move with the prose.
        end content
      }

      unit wl.notation.textblocks kind document.rule "Text blocks" {
        ref     "7.4"
        name "Text blocks"
        meta icon "␣"
        summary "A text block is not a feature of the content keyword: any text-valued
                 keyword may open one, standing alone on its line with an optional form
                 word after it, closed by an end line naming that keyword at the same
                 indentation. Matching indentation is the whole delimiter, so the block
                 needs no escapes and can hold any syntax, including this language's
                 own. This is the only place in WeaveLang where whitespace carries
                 meaning: a dedent. Structure still comes from braces alone, and the
                 block's own rules live with material."
        collapsed_summary "Any text-valued keyword may open a block by standing alone on its line
                           and closing with an end line at the same indentation, and that dedent
                           is the only meaning whitespace ever has."
        preview_summary "Inside: a drawing of the opening line, the verbatim body, and
                         the matching end line that closes a text block, plus a worked
                         example of a weave nested — unescaped — inside another block of
                         the same kind."

        content face.diagram
          <keyword>              alone on its line — a text block opens
            ...verbatim...       every line between it, untouched
          end <keyword>          same keyword, same column — it closes
          the matching column is the only meaning whitespace ever carries
        end content

        content diagram
          the opening indentation
          │
          v
          summary             the keyword stands alone (an optional form
                              word may follow it)
            A text block is   ┐
              not a feature   │  every line between is verbatim
            of the keyword.   ┘
          end summary         `end` + the SAME keyword, at the opening column
          ^
          │
          the same column, and that match is the whole delimiter

          captured text, the common indentation stripped and nothing else —
          the one meaning whitespace ever carries:

          A text block is
            not a feature
          of the keyword.
        end content

        content weave
          unit u kind k "Any text-valued keyword may open a block" {
            summary
              A text block is not a feature of the content keyword.
              This one is opened by `summary`, so `end summary` closes it.
            end summary

            content weave
                unit inner kind k "A weave inside a weave, unescaped" {
                  content markdown
                    No escapes and no delimiters, so a block holds any
                    syntax at all — including this language's own.
                  end content
                }
            end content
          }
        end content

        content markdown
          The full block rules — where a block starts and ends, that every line between
          is verbatim, and that indentation is removed per unit rather than per block —
          belong with [material](#wl.material.literal), because they govern the bytes
          rather than the notation.
        end content
      }

      unit wl.notation.grammar kind document.grammar "The fourteen productions" {
        ref     "7.6"
        name "Grammar"
        meta icon "→"
        summary "Fourteen productions cover the whole language, from a weave taking an
                 id or a string down to a bare use declaration. A unit holds attributes,
                 content, child units, relations, props and meta. Content is the only
                 construct with two right-hand sides — a braced form pinning material
                 already living elsewhere, and a newline form holding it verbatim — the
                 one place the grammar tells the two kinds of bytes apart. Elsewhere it
                 never freezes a vocabulary: kind, an attribute's name, a form word, a
                 selector, all resolve to a bare word or an id."
        collapsed_summary "Fourteen EBNF productions define the entire language, none of them
                           naming a domain word, and a unit's content blocks and child units are
                           significant in the order they appear."
        preview_summary "Inside: all fourteen productions verbatim from §7.6, a drawing
                         of the one production with two right-hand sides, and the table
                         showing every vocabulary slot in the grammar resolving to a
                         bare word or id."

        content face.bullets
          - Fourteen productions cover the whole language, from `weave` down to `use`.
          - `content` is the only production with two right-hand sides: bytes in the file, or bytes named elsewhere.
          - No production freezes a vocabulary: `kind`, an attribute's name, a form word, a selector all resolve to a bare `word` or `id`.
          - A unit's content blocks and child units are significant in the order they appear — together, that order is its material.
        end content

        content txt
          weave        := "weave" (id | string) kind? "{" body* "}"
          body         := unit | relation | edge | source | attribute | props | meta | use
          unit         := "unit" id kind? string "{" (attribute | content | unit
                          | relation | props | meta)* "}"
          relation     := "relation" id? kind? "{" (attribute | props | meta)* "}"
          edge         := "edge" id "->" id kind? string?
          source       := "source" id kind? "{" attribute* "}"
          content      := "content" word? ("in" id)? ( "{" (attribute | outline)* "}"
                          | NEWLINE material "end" "content" )
          outline      := "outline" "{" region* "}"
          region       := "region" selector value word attribute*
          kind         := "kind" id
          attribute    := word (string | number | id | list | range)
          props        := "props" "{" (word scalar)* "}"
          meta         := "meta" word string
          use          := "use" "profile" id ("version" string)?
        end content

        content diagram
          content ─┬─ "{" (attribute | outline)* "}"
                   │      the bytes live OUTSIDE the file — at, region,
                   │      sha256, outline pin them where they already are
                   │
                   └─ NEWLINE material "end" "content"
                          the bytes live INSIDE the file, verbatim,
                          until the end line at the opening column

          the only construct with two right-hand sides, and therefore the
          only place the grammar tells those two kinds of bytes apart
        end content

        content markdown
          Not one production names a domain word. Everywhere a vocabulary could have been
          frozen into the grammar, the grammar takes a bare word or an id instead:

          | where a vocabulary could have been frozen | what the grammar takes |
          | --- | --- |
          | a unit's or a relation's domain (`kind`) | an `id` |
          | an attribute's name | a `word` |
          | a material's form word | a `word` |
          | a region's selector | a `word` |
          | a `meta` field's name | a `word` |
          | a published profile (`use`) | an `id` |

          And the production list closes on the fact that carries the whole of the material
          chapter: a unit's `content` blocks and child `unit` declarations are significant in
          the order they appear, and together they are its material.
        end content
      }

      unit wl.notation.json kind document.encoding "Canonical JSON" {
        ref     "8"
        name "Canonical JSON"
        meta icon "💾"
        summary "The text syntax compiles to a canonical JSON object holding units,
                 relations and sources, and nothing is lost because the JSON is the same
                 form wearing different brackets. A unit's parts array preserves the
                 order of its material, part by part: a content part carries its form
                 word and text, a unit part carries only the child's id, and a sibling
                 units array holds those children in full. Two facts are read from that
                 shape, not a flag: an empty parts array with no children means
                 described, and outside material carries a ref object."
        collapsed_summary "The text compiles to a canonical JSON where a unit's parts array
                           preserves material order, an empty parts array with no children means
                           described, and named material carries a ref object in place of text."
        preview_summary "Inside: a drawing mapping weave text to parts-array entries,
                         the full canonical JSON example verbatim from §8, and the table
                         that tells a literal, delegated, or named part apart by a
                         single key."

        content face.table
          | a part is | how it is written | the key that says so |
          | --- | --- | --- |
          | literal | `{ "t": "content", "form": "go", "text": "…" }` | `text` — the bytes are right here |
          | delegated | `{ "t": "unit", "id": "d.retry" }` | `"t": "unit"` — the bytes are the child's |
          | named | `{ "t": "content", "form": "go", "ref": { … } }` | `ref` — an object naming source, path, region, checksum and outline |
        end content

        content diagram
          the weave text             the parts array
          ──────────────             ───────────────
          content go …         ──>   { "t":"content", "text":"type … {" }
          unit d.retry { … }   ──>   { "t":"unit", "id":"d.retry" }
          content go …         ──>   { "t":"content", "text":"ReadTimeout …" }
          unit d.integrity { } ──>   { "t":"unit", "id":"d.integrity" }
          content go …         ──>   { "t":"content", "text":"}" }

          a unit part carries the child's id and nothing else; the sibling
          "units" array holds those same children in full
        end content

        content json
          {
            "weave": {
              "id": "request-directives",
              "units": [
                {
                  "id": "directives",
                  "kind": "go.struct",
                  "ref": "common/request.go:RequestDirectives",
                  "title": "RequestDirectives",
                  "summary": "Every knob a caller may set for one request.",
                  "parts": [
                    { "t": "content", "form": "go", "text": "type RequestDirectives struct {" },
                    { "t": "unit", "id": "d.retry" },
                    { "t": "content", "form": "go", "text": "  ReadTimeout time.Duration" },
                    { "t": "unit", "id": "d.integrity" },
                    { "t": "content", "form": "go", "text": "}" }
                  ],
                  "units": [
                    { "id": "d.retry", "kind": "go.fields", "title": "Retry knobs",
                      "summary": "Attempt count, backoff base, and whether jitter is applied.",
                      "parts": [] },
                    { "id": "d.integrity", "kind": "go.fields", "title": "Integrity knobs",
                      "summary": "The checksum algorithm, and whether a mismatch is fatal.",
                      "parts": [] }
                  ]
                }
              ],
              "relations": [],
              "sources": []
            }
          }
        end content

        content markdown
          A unit with an empty `parts` array and no children is described rather than
          written. A description therefore costs no keyword and cannot be forgotten in the
          encoding.
        end content
      }

      unit wl.notation.canonicalization kind document.rule "The seven guarantees" {
        ref     "8"
        name "Canonicalization"
        meta icon "🧹"
        summary "Canonicalization is defined by seven guarantees, and the seventh is why
                 the other six can be so free. Six rewrite how a weave is spelled — unit
                 order, ids and convention names, shorthand edges, time formats,
                 references — while the seventh forbids rewriting what it says: material
                 is dedented, and never reflowed. The line runs exactly at a content
                 block's boundary. Preserved part order sits on the material side of
                 that line, since reordering parts would rewrite the composition itself.
                 The six free guarantees buy comparability between two encodings of one
                 weave."
        collapsed_summary "Canonicalization may reorder, normalise, expand and dedupe everything
                           about how a weave is written, and may only dedent — never reflow —
                           the material it holds."
        preview_summary "Inside: the seven guarantees verbatim from §8, the table
                         pairing each one with what it settles, and a drawing of the
                         line — running at a content block's own boundary — that a
                         canonicalizer may never cross."

        content face.diagram
          OUTSIDE a content block:  reorder, normalise, expand, dedupe — freely
          INSIDE a content block:   remove indentation, and do nothing else
          the line runs at the block's own boundary — never through the bytes
        end content

        content
          Canonicalization defines: stable unit ordering within each parent, preserved part
          order, normalized ids and convention names, expanded shorthand edges, normalized
          time formats, deduplicated references — and material dedented, never reflowed.
          A canonicalizer that rewraps a paragraph or reindents a function has corrupted the
          material.
        end content

        content markdown
          | the guarantee | what it settles |
          | --- | --- |
          | stable unit ordering within each parent | a storage decision that the `parts` array already overrides |
          | preserved part order | the composition of the material, which is never rewritten |
          | normalized ids and convention names | one spelling per name |
          | expanded shorthand edges | `edge a -> b` and the full `relation` compare equal |
          | normalized time formats | one spelling per instant |
          | deduplicated references | one entry per reference |
          | **material dedented, never reflowed** | the bytes themselves — the same discipline as [literal material](#wl.material.literal) |

          What the six guarantees buy is **comparability**: two canonical encodings of the
          same weave differ only where the weaves differ, which is what makes diffing and
          merging generated weaves a mechanical operation.
        end content

        content diagram
          The line runs exactly at the boundary of a content block.

          ┌─ OUTSIDE a content block ─────────────────────────────┐
          │   order the units          normalise ids and          │
          │   expand shorthand edges     convention names         │
          │   normalise time formats   dedupe references          │
          │                                                       │
          │   a canonicalizer may rewrite all of this, at will    │
          └───────────────────────────────────────────────────────┘

          ┌─ INSIDE a content block ──────────────────────────────┐
          │   remove indentation                                  │
          │                                                       │
          │   and do nothing else                                 │
          └───────────────────────────────────────────────────────┘

          rewrap a paragraph, reindent a function
            = the material is corrupted, not formatted
        end content
      }
    }

    unit wl.tools kind document.contract "The tool contract" {
      ref "9, 10, 11, 12, 12.1, 12.2, 12.3"
      name "Tools"
      meta icon "🛠"
      summary "Nothing in a weave records how it should be looked at, so every duty
               sits with tools. All of them follow one asymmetry: interpretation —
               titles, summaries, structure — is regenerable, and material, the
               bytes in a content block, is not. Six roles split the work across
               three file types. A renderer draws three sets from three summaries;
               a validator's errors feed the generator that repairs them; a
               generator that leaves a unit described hands the writer its brief;
               a reader takes what remains as ground truth."
      collapsed_summary "Nothing in a weave says how to look at it, so the duties sit
                         in the tools: a view is computed from a focus and a depth, a
                         summary may be regenerated, and literal material may never
                         be edited."
      preview_summary "Inside: six roles and three file types; the rendering
                       query's seven steps; five validation levels and the repair
                       loop; eleven generator rules; the six inputs that fill a
                       described unit; and the six reader assumptions, ending in
                       the one thing it may never do."

      content face.diagram
        the asymmetry every duty here runs on

          interpretation   summaries, titles, structure   regenerable
          material         the bytes in a content block   NOT regenerable
      end content

      content markdown
        - A parser emits canonical JSON, and [every other role is specified against that JSON](#wl.tools.roles) rather than against the syntax — which is why conformance is six duties and not one badge.
        - A view is computed, never stored: [a focus and a depth go in, three sets come out](#wl.tools.render), each drawn from a different one of the unit's three summaries.
        - [Five ascending levels](#wl.tools.validate) check a weave, from whether it parses up to whether each summary is true of its own subtree — and an unknown convention term stays a warning.
        - [Eleven numbered rules](#wl.tools.write) bind a generating model, and [the literal parts on either side of a described unit](#wl.tools.fill) are the sharpest constraint on whoever fills it.
        - [A reader](#wl.tools.read) takes the active depth as complete and the material as ground truth, and never invents a child.
      end content

      content diagram
        the file holds no view, so a tool computes one on demand

          focus + depth ─►┌───────┐─► active world      ◄ summary
                          │ a     │─► ancestor envelope ◄ collapsed_summary
                          │ tool  │─► child previews    ◄ preview_summary
                          └───────┘

        the roles lean on one another in one direction

          generator ──writes the three summaries──► renderer
          validator ──errors it repairs from─────► generator
          generator ──leaves a unit described────► writer
      end content

      unit wl.tools.roles kind document.conformance "The six roles" {
        ref "10"
        name "Conforming roles"
        meta icon "🎭"
        summary "Conformance is six duties, so an implementation claims only the
                 work it does. A parser turns text into canonical JSON; every
                 other role specifies against JSON, not syntax. A validator checks
                 core semantics without convention knowledge, so validation stays
                 complete while vocabulary stays open. A renderer renders at least
                 one view — a view is a query, and none is canonical. A resolver
                 alone reaches outside the file; a generator marks material,
                 uncertainty, and convention usage; a writer fills one described
                 unit. Three file types keep the text, the AST, and the resolved
                 conventions apart."
        collapsed_summary "Six named roles — parser, validator, renderer, resolver,
                           generator, writer — each with a single duty, plus three
                           file types for the text, the canonical AST, and the
                           resolved conventions."
        preview_summary "Inside: the six roles verbatim, each with its one-line
                         duty, and the three file types; and a diagram tracing
                         the pipeline from `.weave` through validation and
                         rendering to the errors a generator repairs."

        content face.diagram
          .weave ──WL-Parser──► .weave.json ──WL-Renderer──► one view
             ▲                       │
             │                  WL-Validator   core only; kinds stay open
             │                       │
          WL-Generator ◄──errors─────┘
        end content

        content markdown
          - **WL-Parser** — parses `.weave` and emits canonical JSON.
          - **WL-Validator** — validates core semantics without convention knowledge.
          - **WL-Renderer** — renders at least one view from canonical JSON.
          - **WL-Resolver** — resolves named material and verifies checksums.
          - **WL-Generator** — generates WeaveLang and marks material, uncertainty, and
          convention usage.
          - **WL-Writer** — writes material for described units, from their summaries and
          their surroundings (§12.2).

          File types: `.weave` (text), `.weave.json` (canonical AST), `.weave.lock`
          (resolved conventions).
        end content

        content diagram
          .weave ──WL-Parser──► .weave.json ──WL-Renderer──► one view
             ▲                       │
             │                  WL-Validator   core only; kinds stay open
             │                       │
          WL-Generator ◄──errors─────┘

          WL-Writer ─── fills one described unit, and moves nothing else
          WL-Resolver ─ the only role that reaches outside the file
          .weave.lock ─ records the convention versions resolved against
        end content
      }

      unit wl.tools.render kind document.mechanism "Rendering a view" {
        ref "11"
        name "Rendering"
        meta icon "🖼"
        summary "A renderer answers a query, not a file: a focus and a depth go in,
                 and three sets come out — the active world (siblings plus the
                 focus), the ancestor envelope, and the child previews — each drawn
                 from a different summary field. Neither value lives in the weave,
                 so two tools may render one unit differently and both be right.
                 A seven-step algorithm resolves the sets in order; material
                 resolves more finely as depth increases but a described part is
                 never omitted. Five familiar renderings are refused, each
                 discarding something the weave carries."
        collapsed_summary "A renderer is handed a focus and a depth and returns the
                           active world, the ancestor envelope, and the child
                           previews, each drawn from a different summary field."
        preview_summary "Inside: the seven steps from focus to three sets,
                         including collapsed relations and hidden portals; the
                         shallow/middle/deepest material ladder; and the
                         renderings to avoid, ending in the ban on piping a
                         whole weave straight to a drawing tool."

        content face.diagram
          one query in, three sets out, three summary fields

            above  ancestors → envelope         ◄ collapsed_summary
            here   siblings + FOCUS → active     ◄ summary
            below  children → previews           ◄ preview_summary
        end content

        content markdown
          - Two values the tool supplies and the file never holds: which unit is the **focus**, and how **deep** to go. Two tools may render one weave differently and both be right.
          - The three sets are why a unit carries three summaries rather than one — [three fields written for three reading moments](#wl.constructs.summaries).
          - A relation crossing out of the active world is **collapsed, not dropped**, and everything below the requested depth survives as an expandable portal — [the seven steps](#wl.tools.render.query).
          - Depth changes only the **grain** of each part, never the set of parts, and a described part is visible at every rung — [shallow, middle, deepest](#wl.tools.render.material).
          - A whole weave is never handed straight to a drawing tool: [resolve the three sets first, then draw only those](#wl.tools.render.avoid).
        end content

        unit wl.tools.render.query kind document.algorithm "The world query" {
          ref "11"
          name "World query"
          meta icon "🎯"
          summary "The algorithm is seven steps and its order is its argument. It
                   resolves the focus first, since every other set depends on it;
                   takes the focus and its siblings together as the active world;
                   renders ancestors as
                   envelopes from `collapsed_summary` and children — lexical and
                   revealed — as previews from `preview_summary`; keeps relations
                   among active units and collapses, never drops, those crossing
                   outward; walks a unit's parts in written order, literal
                   verbatim and described as summary; and preserves everything
                   below the requested depth as an expandable portal."
          collapsed_summary "Seven ordered steps turn a focus and a depth into the
                             three sets, and the order is the argument rather than an
                             implementation detail."
          preview_summary "Inside: the seven numbered steps verbatim, in the
                           order they run; and a drawing of steps 5 and 7,
                           showing how an outward-crossing relation and a hidden
                           subtree both stay visible instead of disappearing."

          content face.timeline
            1. focus — resolve the focus unit
            2. active — the focus and its siblings
            3. envelope + previews — ancestors and children, from their summary fields
            4. material — parts in order, literal verbatim, described as summary
            5. depth — hidden descendants preserved as portals
          end content

          content txt
            1. Resolve the focus unit.
            2. The focus and its siblings are the active world.
            3. Ancestors are envelopes, rendered from collapsed_summary.
            4. Children (lexical and revealed) are previews, rendered from preview_summary.
            5. Include relations among active units; collapse those crossing outward.
            6. At a unit with material, render its parts in order: literal parts verbatim,
               described parts as their summaries, in place.
            7. Preserve hidden descendants as expandable portals.
          end content

          content diagram
            steps 5 and 7 both refuse to delete: an edge and a subtree
            that leave the view stay visible as the fact that they left

              both ends active   A ──depends_on──► B     drawn in full
              far end outside    A ──depends_on──►(  )   collapsed, the
                                                         edge remains
              below the depth    C ▼ hidden descendants  an expandable
                                                         portal

            a boundary of the view is a door, never an edge of the world
          end content
        }

        unit wl.tools.render.material kind document.rule "Material grain" {
          ref "11"
          name "Material grain"
          meta icon "🔬"
          summary "Depth changes the grain of the material, never which parts
                   exist. Three recommended rungs — shallow, middle, deepest —
                   each name the units the material already has, in the
                   material's own vocabulary rather than in bytes, so the same
                   three rungs serve code, prose, and transcripts alike. What the
                   ladder never does is remove a part: a described part stays
                   visibly a description at every rung, and omitting one
                   silently is not a shortcut but a false claim that the
                   material is complete when it is not."
          collapsed_summary "Depth sets the grain — headings, then signatures and
                             hunks, then exact lines — but never removes a part, and
                             a described part is always shown as a visible
                             description."
          preview_summary "Inside: the shallow/middle/deepest ladder verbatim,
                           and a table tracking one described part across all
                           three rungs, showing it stays a visible description
                           and never turns to bytes or disappears."

          content face.table
            | depth | part 1 | part 2 | part 3 |
            | --- | --- | --- | --- |
            | shallow | heading | described (summary) | heading |
            | middle | signature + hunk | described (summary) | signature + hunk |
            | deepest | exact lines | described (summary) | exact lines |
          end content

          content txt
            shallow: files, headings, symbols, scene titles
            middle:  signatures, hunks, focused paragraphs
            deepest: exact lines, exact text, transcript ranges
          end content

          content markdown
            - **Each rung is stated in the material's own vocabulary**, not in bytes, which is why the same three serve code, prose and transcripts alike.
            - **The rungs are recommendations, not a fixed scale** — and they run over the grain of one written part, never over [the parts themselves](#wl.material.resolution).
            - **The ladder never removes a part.** A [described part](#wl.material.described) must be visibly a description and must never be silently omitted.
            - **Omission is a false claim about coverage** — a reader who cannot see that something belongs here has been told the material is complete when it is not, and it is the one error no reader can detect from inside the view.
          end content

          content diagram
            depth changes the GRAIN of each part, never the SET of parts

              shallow │ heading   │ described │ heading   │
                      │           │ (summary) │           │
              middle  │ signature │ described │ signature │
                      │ + hunk    │ (summary) │ + hunk    │
              deepest │ exact     │ described │ exact     │
                      │ lines     │ (summary) │ lines     │
                        part 1      part 2      part 3

            part 2 is present at every rung, and at every rung it is
            visibly a description and not bytes
          end content
        }

        unit wl.tools.render.avoid kind document.antipattern "The refused renderings" {
          ref "11"
          name "Avoided renderings"
          meta icon "🚫"
          summary "Five familiar renderings are refused, each discarding something
                   specific the weave carries: nesting without depth's claim to
                   wholeness, meaning's structure for storage's, an open kind
                   forced into a fixed shape, a relation's kind, or resolution
                   itself when a graphic only changes scale. The closing rule is
                   a pipeline order, not a taste: never convert a whole weave
                   straight to Mermaid, Graphviz, SVG, or canvas. A drawing tool
                   draws exactly what it is handed, so the culling — resolving
                   the three sets first — belongs to the renderer, not the
                   drawing tool."
          collapsed_summary "Five renderings are refused — a bullet tree, a file
                             explorer, a UML clone, a flat mind map, a mere zoom —
                             and a whole weave is never piped straight into a drawing
                             tool."
          preview_summary "Inside: a table of five refused renderings and what
                           each discards; the verbatim ban on Mermaid, Graphviz,
                           SVG, and canvas; and a drawing of the correct order —
                           three sets resolved before anything is handed to a
                           drawing tool."

          content face.table
            | the rendering | what it discards |
            | --- | --- |
            | collapsible bullet tree | the claim that every depth is a whole world |
            | file explorer | the structure of meaning, for the structure of storage |
            | UML clone | open kind strings, forced into fixed shapes |
            | flat mind map | the relation kind, which made the edge worth drawing |
            | a zoom | resolution — bigger pixels, the same sentence |
          end content

          content txt
            What renderers avoid: treating a weave as a collapsible bullet tree, a file
            explorer, a UML clone, a mind map where every edge means the same thing, or a
            graphic where the scale changes but the semantics do not. Never convert a whole
            weave straight to Mermaid, Graphviz, SVG, or canvas — resolve the three sets
            first, then draw only those.
          end content

          content diagram
            the culling happens before the handoff, never after

              whole weave ──────────────────────► drawing tool   NEVER
              whole weave ─► three sets ────────► drawing tool   the order

            a drawing tool draws exactly what it is handed, so handing it
            the file makes it faithfully draw the thing a weave avoids
          end content
        }
      }

      unit wl.tools.validate kind document.mechanism "The five validation levels" {
        ref "9"
        name "Validation"
        meta icon "✔"
        summary "Validation is layered, ascending from mechanical checks to
                 judgement calls. Syntax checks that the file parses; core checks
                 the object graph; material checks the bytes and locators —
                 checksums, region validity, dedent round-trips; depth checks that
                 no summary needs its children to be understood; truth checks that
                 each summary is true of its subtree. Convention checks sit outside
                 the five, advisory: an unknown kind warns, never errors. Errors are
                 machine-readable objects a generator repairs from, in a loop —
                 validate, repair, validate — since a repair can reopen what was
                 clean."
        collapsed_summary "Five levels — syntax, core, material, depth, truth — check
                           a weave from whether it parses up to whether each summary
                           is true of its subtree, while unknown convention terms
                           stay warnings."
        preview_summary "Inside: the five-level table verbatim, a sample error
                         object with the fields a generator branches on, and the
                         generate-validate-repair-validate-format loop, verbatim,
                         with a drawing of why the second validate is not a
                         formality."

        content face.diagram
          the levels ascend from mechanical checks to judgement calls

            syntax → core → material → depth → truth

          conventions sit outside all five: an unknown kind warns, never errors
        end content

        content markdown
          | Level | Checks |
          | --- | --- |
          | syntax | the file parses; every text block has a matching `end`; blocks balanced |
          | core | ids unique; references resolve; `from`/`to` exist |
          | material | named sources exist; regions valid against the source; checksums match; outline regions nest without crossing; literal material round-trips after dedent |
          | depth | no summary depends on its children to be understood; leaves are written, described, or natural |
          | truth | each summary describes the material in its subtree; low-confidence claims are not rendered as fact; contradictions are explicit relations, not omissions |
        end content

        content json
          {
            "error": "unknown_reference",
            "path": "units[3].reveals[1]",
            "reference": "service.payments",
            "message": "Unit service.payments is referenced but not defined."
          }
        end content

        content markdown
          | field | what it gives the generator |
          | --- | --- |
          | `error` | the code to branch on |
          | `path` | the node to open |
          | `reference` | the offending name |
          | `message` | the sentence for a human |
        end content

        content txt
          generate -> validate -> repair -> validate -> format
        end content

        content diagram
          the second validate is not a formality: a repair can break
          something the first pass had already found clean

            generate ─► validate ─► repair ─► validate ─► format
                                       │          │
                                       └──────────┘ format runs last, so
                                         it can never mask a real error
        end content
      }

      unit wl.tools.write kind document.rules "The eleven rules" {
        ref "12.1"
        name "Writing"
        meta icon "✍"
        summary "Eleven numbered rules bind a model that generates WeaveLang, and they
                 sort by what each one protects. Three protect the material and its
                 identity, which no later pass can recover. Two protect the reader's
                 descent. Three protect honesty, ending in an audit run by a different
                 call than the one that wrote the summaries. Three are findings about how
                 generation actually fails — a flat plan before a nested emission, one
                 head noun phrase across the three summaries, and a short `name` on every
                 unit."
        collapsed_summary "Eleven numbered rules bind a model generating WeaveLang,
                           grouped by what they protect: the material and its identity,
                           the reader's descent, honesty, and three findings about how
                           generation actually fails."
        preview_summary "Inside: the eleven rules verbatim, the four-group table that sorts
                         them by what each protects, and the flat plan — `id | depth |
                         parent | kind | material?` — that rule 6 emits a tree from."

        content face.table
          | what the group protects | the rules in it |
          | --- | --- |
          | the material and its identity | 1 never edit, 4 preserve locators, 8 copy `ref` verbatim |
          | the reader's descent | 2 each depth independently readable, 10 describe rather than pad |
          | honesty | 3 mark uncertainty, 5 do not hide conflicts, 11 audit before publishing |
          | how generation actually fails | 6 plan flat, 7 one head noun phrase, 9 give every unit a [`name`](#wl.constructs.unit) |
        end content

        content markdown
          A model generating WeaveLang must:

          1. **Never edit the material.** Literal material is verbatim; everything above it
             is interpretation. If material needs describing, describe it in the summary.
          2. **Make each depth independently readable.** Short summaries shallow, nuance and
             material deep. Never expand every branch equally.
          3. **Mark uncertainty** with `confidence` and explicit `cites`, and never render a
             low-confidence claim as fact.
          4. **Preserve locators** for named material — paths, revisions, line ranges,
             symbols — at the granularity of the citing depth.
          5. **Not hide conflicts.** Two incompatible readings are two units and a
             `kind contradicts` relation between them, never one smoothed sentence.
          6. **Plan flat, emit nested.** Plan as `id | depth | parent | kind | title |
             summary | material?`, then emit. This reduces orphaned children and broken
             references.
          7. **Name a unit the same way in all three summaries.** The variants must share
             their head noun phrase. Readers treat a concept referred to by a repeated label
             as a main topic and one referred to by varied paraphrase as minor, regardless
             of its actual importance, so elegant variation makes a reader down-rank the
             unit.
          8. **Copy `ref` verbatim.** Never normalise, renumber, or prettify it. Its whole
             value is that it is a copy.
          9. **Give every unit a `name`,** one or two words where they suffice and never
             more than three, sharing its head noun with the three summaries. The name is
             what chips, crumbs and dots carry; a weave without names forces every
             renderer to truncate claims, and a wordy name defeats the smallest boxes it
             exists for.
          10. **Describe rather than pad.** A part that is conventional or uninteresting at
             this depth is a described unit with a real summary, not invented material and
             not a silent gap.
          11. **Audit before publishing.** Every unit is judged against the §13 checklist
             in an independent pass — the model that summarizes and the model that checks
             are never the same call. Every number a summary, bullet, or face carries is
             verified against the material or child that claims it; a number that cannot
             be pointed to is removed, not softened. Where a convention publishes a
             whole-weave property (§6.3's fully woven), the property is checked
             mechanically, not asserted.
        end content

        content diagram
          rule 6 in practice: the plan is rows, the emission is a tree

            id           | depth | parent    | kind     | material?
            ─────────────┼───────┼───────────┼──────────┼──────────
            api          |   0   | —         | service  | no
            api.auth     |   1   | api       | module   | no
            api.auth.jwt |   2   | api.auth  | function | yes

            every parent named in the plan already exists as a row, so
            the emitted tree cannot orphan a child or break a reference
        end content
      }

      unit wl.tools.fill kind document.procedure "Filling a described unit" {
        ref "12.2"
        name "Filling"
        meta icon "🧩"
        summary "A described unit is a brief; filling it is not a structural
                 choice. Six inputs constrain the writing: summary states what
                 belongs, kind states the form, ancestors' summaries are the
                 constraints it must satisfy, relations and cites supply the
                 facts, sibling material supplies the style. The two literal
                 parts on either side are the sharpest constraint — the actual
                 bytes the result must join, fixing what it continues and leads
                 into. The writer moves nothing around the slot; where the
                 summary is too weak to write from, it asks rather than
                 guesses."
        collapsed_summary "A described unit is a brief, and six inputs — above all
                           the literal parts on either side of it — fix what to write
                           into it; the writer fills the slot and restructures
                           nothing."
        preview_summary "Inside: the six inputs verbatim, listed as a how-to;
                         and a worked example — a `charge` function with one
                         described unit, `charge.attempts`, filled from nothing
                         but its own summary."

        content face.diagram
          ┌ preceding part ─ what it must CONTINUE
          │  summary = the brief · kind = the form
          │  ancestors, relations+cites, siblings = constraints, facts, style
          └ following part ─ what it must LEAD INTO
        end content

        content markdown
          A described unit is a brief. To write its material, use:

          - its `summary`, which states what belongs there;
          - its `kind`, which states what form it takes;
          - the **literal parts on either side of it**, which fix its context exactly — the
            preceding part shows what it must continue, and the following part shows what it
            must lead into;
          - its ancestors' summaries, which are the constraints it must satisfy;
          - its relations and `cites`;
          - sibling material as a style reference.

          Write into the unit as a `content` block. Do not move it, rename it, merge it with
          a neighbour, or alter any surrounding literal part. If the summary is too weak to
          write from, add a `unit kind question` rather than guessing.
        end content

        content diagram
          the slot, and the six things that pin it

            ┌ preceding literal part ─ what the material must CONTINUE
            │
            │   the described unit    summary ── the brief: what belongs
            │                         kind ───── the form it takes
            │      ▲ ancestors' summaries ─ constraints it must satisfy
            │      ▲ relations and cites ── the facts it may use
            │      ▲ sibling material ───── the style
            │
            └ following literal part ─ what the material must LEAD INTO

          the two literal parts are the sharpest constraint of the six:
          they are the actual bytes the result has to join
        end content

        content weave
          unit charge kind function "Charge a saved card" {
            content code
              func Charge(ctx context.Context, id string) error {
                if err := validate(id); err != nil { return err }
            end content

            unit charge.attempts kind block "The attempt loop and its backoff" {
              summary "Tries the charge up to maxTries times and sleeps
                       base * 2^i between attempts, returning the last
                       error when every attempt has failed."
            }

            content code
                return nil
              }
            end content
          }
        end content
      }

      unit wl.tools.read kind document.contract "Reading a weave" {
        ref "12.3"
        name "Reading"
        meta icon "👓"
        summary "A model reading a weave is bound by six assumptions, mirroring what
                 the author promised. The active depth is complete — an absent fact
                 is absent, and descending is for nuance, not repair. Ancestors
                 give orientation only, never a fact about this level. Children
                 are optional: an answer need not open one. Literal material is
                 immutable ground truth. A described unit states what belongs
                 there, not that nothing does. It never invents an unnamed
                 subdivision. Reading is the dual of writing: a reader may
                 descend but not add, a writer may fill but not restructure."
        collapsed_summary "Six assumptions bind a model reading a weave, and they are
                           the exact mirror of what the author promised."
        preview_summary "Inside: a six-row table pairing each assumption with
                         the move it forbids — reading an ancestor as fact,
                         inventing a child — and a drawing of the writer and
                         the reader as duals, each barred from the other's one
                         move."

        content face.diagram
          writer and reader are duals, each barred from the other's move

            writer   may FILL what was described     may not RESTRUCTURE
            reader   may DESCEND into a child         may not ADD
        end content

        content markdown
          | what the reader assumes | so it must not |
          | --- | --- |
          | the active depth is complete | descend to repair an absence |
          | ancestors give orientation | read an ancestor as a fact about this level |
          | children are optional | withhold an answer until it has opened one |
          | literal material is immutable ground truth | argue with the bytes |
          | a described unit states what belongs there | conclude that nothing is there |
          | the weave names every child it has | invent a child |
        end content
      }
    }

    unit wl.authoring kind document.laws "The authoring law" {
      ref "13"
      name "Authoring"
      meta icon "⚖"
      summary "One law governs this area: a unit is a complete and true account of
               everything below it, at its own resolution — complete at the fact, silent
               at the mechanism, and surprising only there. Parent supplies the derivation
               and its two tests. Size, boundary and shape are what the law costs a reader
               once it is held. Redundancy and face are the same law read at the surface.
               The checklist makes all of it runnable, bottom-up; the unsettled section
               marks every judgment call as one, not a result."

      collapsed_summary "A unit is a complete and true account of everything below it,
                         complete at the fact and silent at the mechanism — and the laws
                         for size, boundary, shape, redundancy and the face all follow
                         from that one sentence, with thirty-seven checks that run it."

      preview_summary "Inside: how a parent is derived and tested; the size budget and the
                       split/merge seams; the width and depth dials; why the same idea at
                       three resolutions pays, and how the face composes it; the
                       thirty-seven-item checklist; and five things this law does not
                       settle."

      content face.bullets
        - A parent is derived by three operations and tested by negation — [parent](#wl.authoring.parent).
        - What the law costs a reader: [size](#wl.authoring.size), the split/merge [seam](#wl.authoring.boundary), and [shape](#wl.authoring.shape).
        - One idea at three resolutions, composed into one element — [redundancy](#wl.authoring.redundancy), [face](#wl.authoring.face).
        - Thirty-seven checks make the law runnable, per unit and bottom-up — [checklist](#wl.authoring.checklist).
        - Five things are named as calls, so none passes as a result — [unsettled](#wl.authoring.unsettled).
      end content

      content markdown
        - **The law.** A unit is a complete and true account of everything below it, at its own resolution. The reader who stops holds no false belief; they descend for mechanism, not for correction.
        - **Complete at the fact, silent at the mechanism.** A unit that pre-explains everything measurably damages learning from its own children, so the gap is placed rather than closed.
        - **Surprise is allowed exactly once.** At the level of mechanism it is the payload of descent; at the level of fact it is a defect.
        - **Truth governs shape, never the reverse.** How big, where it splits, how wide and how deep are all consequences of what a parent owes its children.
        - **Thirty-seven checks, run per unit, bottom-up.** A failure is a defect, not a preference — and every judgment call in the law is named as one.
      end content

      content diagram
        one law, and the rest is its operative content

            a unit is a COMPLETE and TRUE account of
            everything below it, at its own resolution
                             │
              ┌──────────────┴──────────────┐
              │                             │
          TRUE of its children       COMPLETE, but bounded:
          three operations,          complete at the level of
          entailment, coverage,      FACT, silent at the level
          stated direction           of MECHANISM
              │                             │
              └──────────────┬──────────────┘
                             │
            what it costs once a reader must hold it:
              size    one claim, at most 3 co-varying things
              split   at the seam where the least carries over
              merge   where a child entails nothing new
              shape   wide at the top, narrower with depth
                             │
            how it reaches the page:
              one body of content, filtered three times —
              and each descent a DIFFERENT act of comprehension
              gist (read) · distillate (scanned) · figure (seen)

        surprise at the MECHANISM is what descent is for
        surprise at the FACT is a defect
      end content

      unit wl.authoring.parent kind document.laws "The derived parent" {
        ref "13 E"
        name "Parent"
        meta icon "🌳"
        summary "The macrostructure theory backs the governing law: every parent statement
                 is a deletion, a generalization, or a construction over its children —
                 nothing else is admissible — and entailment tests it. That is necessary
                 but not sufficient; the reader and purpose set the rest. The finished
                 account owes total coverage, with the direction of every dependency
                 stated. It may never absorb the mechanism, exact wording, or a
                 contradiction — those stay below, stated by the child itself."

        collapsed_summary "Every parent statement is a deletion, an immediate-superset
                           generalization, or a construction over its children; entailment
                           tests it, total coverage and stated direction complete it, and
                           mechanism, exact wording and contradiction all stay below."

        preview_summary "Inside: the three macrorules and the constraint keeping each
                         honest; the entailment test, run by negating one child fact; what
                         the account owes — coverage, stated direction; and the three
                         things it leaves alone — mechanism, exact wording, a
                         contradiction the child states itself."

        content face.bullets
          - Three operations, and an entailment test that catches a teaser — [the operations](#wl.authoring.parent.operations).
          - Total coverage, with the direction of every dependency stated — [coverage](#wl.authoring.parent.coverage).
          - The mechanism, exact wording, and a contradiction all stay below — [the gap](#wl.authoring.parent.gap).
          - Entailment is necessary, not sufficient — the declared reader and purpose supply the rest.
          - This is the operative test behind the invariant that a depth stays [true of its material](#wl.depth.true).
        end content

        content markdown
          - **Deletion, generalization, construction — and nothing else.** Generalization must name an **immediate** superset; construction is the only rule that adds a proposition no child states, and it is the one novices skip.
          - **The negation test.** Negate any single fact in a child. If the parent still reads true, the parent is not about that child.
          - **Coverage is total.** A parent that accounts for some children and omits the rest leaves the omitted ones recalled **worse** than no parent would.
          - **Direction, not enumeration.** From the parent alone a reader can tell `therefore` from `because`, or the parent has listed instead of explained.
          - **The gap sits at the mechanism** — never at the fact, and never an exact string paraphrased upward.
        end content

        content diagram
          the parent is DERIVED, and the derivation is testable

            child   child   child   child     ← the microstructure
              └───────┴───┬───┴───────┘
                          │
              delete ─────┤ drop from this resolution, not the weave
                          │
              generalize ─┤ an IMMEDIATE superset, or it goes vacuous
                          │
              construct ──┤ the only rule that adds a proposition
                          │ no child states
                          ▼
                     the parent

          two tests, run in opposite directions:

            negate one child fact, is the parent still true?
                                              ⇒ a TEASER
            find the child that entails this sentence, none?
                                              ⇒ a FABRICATION
        end content

        unit wl.authoring.parent.operations kind document.rule "The three operations" {
          ref "13 E"
          name "Operations"
          meta icon "⊕"
          summary "The macrorules license exactly three meaning-reducing operations, and a
                   parent statement that is none of them has no warrant: deletion, an
                   immediate-superset generalization, and construction, the only one that
                   introduces a proposition no child states. Entailment is necessary but
                   not sufficient — the declared reader and purpose set the rest, and the
                   authors concede there is no decision procedure, only intuition. Two
                   constraints bound what may be dropped: nothing goes that a remaining
                   statement needs, and with every child deleted the parent still reads
                   connected."

          collapsed_summary "Deletion, generalization to an immediate superset, and
                             construction are the only operations that may produce a
                             parent sentence; entailment tests them, the declared reader
                             and purpose settle what counts as relevant, and nothing may
                             be dropped that a remaining statement needs."

          preview_summary "Inside: a table setting each operation against the constraint
                           that keeps it honest, and the residual facts — ranking cannot
                           build a parent, and the standalone test — plus the authors' own
                           concession that there is no decision procedure, only intuition."

          content face.table
            | operation | test |
            | --- | --- |
            | deletion | not an interpretation condition of what remains |
            | generalization | only an immediate superset — nothing vaguer |
            | construction | the only one that adds a proposition no child states |
          end content

          content markdown
            - **Entailment is necessary, never sufficient.** The declared reader and purpose supply the missing determinant; without them, two correct parents can differ and neither is wrong.
            - **Nothing is deleted that a remaining statement cannot be interpreted without.** This is also what keeps the parent connected rather than a heap of unrelated sentences.
            - **Delete every child, and the parent still reads as one account.** Coherence here is referential overlap between propositions — a tractable proxy, not a definition.
            - **Ranking cannot build a parent.** Top-`k` selection is blind to interpretation dependencies and drops exactly the connective facts.
          end content

          content markdown
            | operation | what it licenses | the constraint that keeps it honest |
            | --- | --- | --- |
            | **deletion** | dropping a proposition from this resolution | it may not be an interpretation condition of anything that remains |
            | **generalization** | one proposition standing for a sequence | the superset must be **immediate**, or the parent goes vacuous |
            | **construction** | a proposition **no child states** | the children's facts must be its normal conditions, components, or consequences |

            There is no decision procedure for choosing among them. The authors say so:
            the choice is decided "on the basis of intuition at present". The checks are the
            enforcement, and they are not a proof.
          end content
        }

        unit wl.authoring.parent.coverage kind document.rule "Coverage and direction" {
          ref "13 E"
          name "Coverage"
          meta icon "🗺"
          summary "Three demands decide whether a finished account is worth reading, and
                   each prevents a documented failure. Coverage is total, because silence
                   about a child leaves it recalled worse than no parent at all. The
                   parent states which way each dependency runs, so a reader can tell
                   therefore from because — a correct list of what children do, without
                   their relation, confers nothing. And it names components while leaving
                   interactions to the children, written as an organizer rather than a
                   précis: true of all children, verbatim in none."

          collapsed_summary "A parent accounts for every child without exception, states
                             which way each dependency runs so a reader can tell therefore
                             from because, names the components while leaving interactions
                             to the children, and reads as an organizer — true of all
                             children, verbatim in none."

          preview_summary "Inside: the evidence behind each demand — half-signalled
                           recall, the therefore/because test, parts-up-interactions-down
                           at d ≈ 0.75–0.88 — and the
                           deletion/invention/superordination/segmentation rates that
                           separate an expert summariser from a novice one."

          content face.bullets
            - Coverage is total — silence about a child is negative, not neutral.
            - State the direction: a reader can tell "therefore" from "because."
            - Parts up, interactions down — the best-evidenced move, at d ≈ 0.75–0.88.
            - The organizer test: true of all children, and verbatim in none.
          end content

          content markdown
            - **Silence about a child is negative, not neutral.** Unsignalled content in a half-signalled text is recalled worse than the same content with no signals at all.
            - **Tell "therefore" from "because".** A parent that lists what its children do, without the relation among them, is a correct summary that confers nothing.
            - **Parts up, interactions down.** Naming components before their interactions runs at a median d ≈ 0.75–0.88; a parent that describes interactions is doing its child's job at lower fidelity.
            - **The organizer test.** Producible by deleting sentences from the children ⇒ an outline. True of all children and verbatim in none ⇒ an organizer.
            - **Coverage is not the gate.** Deletion is at ceiling for every adult; only invention discriminates.
          end content

          content markdown
            | operation | what it discriminates | the measured gap |
            | --- | --- | --- |
            | **deletion** | nothing — it is at ceiling | college students deleted 93% of trivial and 95% of redundant material |
            | **invention** | almost everything | experts on 84% of warranted occasions; four-year college students 49%; tenth graders about a third |
            | **superordination** | almost everything | experts perfect, against 70% for college students |
            | **segmentation** | expert from novice directly | experts combine paragraphs top-down; novices are captured by the source's own divisions |

            Expert N = 2 — and the experts could not state their own rules when asked
            afterwards, so the criterion cannot be elicited by interviewing a good
            summariser.
          end content
        }

        unit wl.authoring.parent.gap kind document.rule "The placed gap" {
          ref "13 E"
          name "Gap"
          meta icon "…"
          summary "A parent that explains everything is not a better parent, and the cost
                   is measured: a fully consistent outline raises verbatim recall and
                   roughly halves inference, leaving no room for the reader's own work.
                   The gap sits at the mechanism, never the fact, and it penalises novices
                   while it pays experts. Two things never travel upward — a claim resting
                   on exact wording, and a contradiction of what the parent implies, which
                   the child must state itself, since readers miss it even when told to
                   look."

          collapsed_summary "A parent is complete at the fact and silent at the mechanism;
                             exact wording stays verbatim in a leaf, and a child that
                             overturns its parent says so itself — because readers miss up
                             to 51% of contradictions even when told to hunt for them."

          preview_summary "Inside: the measured price of perfect pre-organisation, the
                           expertise reversal in problem-solving scores, and a drawing of
                           the fact/mechanism split — plus the rise from .064 to .511 in
                           undetected contradiction that puts the burden on the child."

          content face.table
            | level | the parent's stance |
            | --- | --- |
            | the fact | complete |
            | the mechanism | silent — that silence is what descent is for |
            | exact wording | never paraphrased upward |
            | a contradiction | never absorbed — the child states it itself |
          end content

          content markdown
            - **Complete at the fact, silent at the mechanism** — and never the reverse. The gap only works when a diligent reader could generate what was left implicit; a merely disorganized text will not do.
            - **Perfect pre-organisation has a price.** A fully consistent outline raised verbatim verification and roughly halved inference.
            - **The gap pays experts and penalises novices.** 61% vs 46% on problem solving for high-knowledge readers; 17% vs 30% for low-knowledge ones.
            - **Exact strings never travel upward.** Gist and verbatim are encoded in parallel, and gist-based false memories are **more** consistent over time than true ones.
            - **Contradiction is stated by the child.** Told to hunt for them, readers still missed up to 51%, and three introductory paragraphs made it worse than one.
          end content

          content diagram
            where the gap belongs, and where it is a defect

              level of FACT       what is there, and how the parts
                                  depend on one another
                                  ── the parent is COMPLETE here

              level of MECHANISM  why it works
                                  ── the parent is SILENT here, and
                                     that silence is what descent is for

            invert the two and both readers lose:

              gap at the FACT      ⇒ the reader who stopped now holds
                                     a false belief
              no gap at all        ⇒ verbatim recall up, inference
                                     roughly halved
          end content
        }
      }

      unit wl.authoring.size kind document.rule "The size budget" {
        ref "13 A"
        name "Size"
        meta icon "📏"
        summary "Size is governed by one quantity, and it is not the obvious one: the new,
                 mutually dependent ideas a reader must hold for the claim to be true —
                 not how many facts a unit states, not how many children it has. The
                 budget is not a format constant; it is the material crossed with the
                 reader. Two numbers follow: at most three co-varying things, and well
                 under a dozen ideas overall. A parent shrinks by carrying fewer ideas,
                 never the same ideas in fewer words."

        collapsed_summary "A unit is as big as the number of new, mutually dependent ideas
                           its claim needs — at most three things that must co-vary, and
                           well under a dozen interacting ideas — while the count of facts
                           it states is unbounded and free."

        preview_summary "Inside: a table setting the three quantities against their
                         bounds, the by-hand counting procedure (mark, strike, strike,
                         count the residue), the one published calibration — 16 elements
                         in 171 words — and why 3–5 and terse prose are both the wrong
                         target."

        content face.table
          | quantity | bound |
          | --- | --- |
          | facts stated | unbounded — free |
          | new interacting ideas | ≤3 co-varying, well under a dozen |
          | children | a navigation dial, not a size limit |
        end content

        content markdown
          - **"3–5" does not bind.** It is chunk capacity under conditions a visible, re-readable page violates by construction.
          - **Terse is not small.** Reading time follows propositions, so a parent shrinks by carrying fewer ideas, never the same ideas in fewer words.
        end content

        content markdown
          | quantity | governed by | bound |
          | --- | --- | --- |
          | how many things the unit states | nothing | unbounded — and free |
          | how many NEW interacting ideas the claim needs held at once | element interactivity | the real budget: ≤ 3 co-varying, well under a dozen |
          | how many children the unit has | visual search and steering cost | a navigation dial, not a size limit |
        end content

        content diagram
          the count, executable by hand:

            mark every idea unit in the account
                │
                ├─ strike each one the intended reader already knows
                │
                ├─ strike each one that depends on no other
                │
                ▼
            the residue is the number that matters

          the only published expository calibration:
            171 words · at least 16 interacting elements · HIGH
            ⇒ roughly one interacting idea per 11 words of
              unrelieved dependency

          the call: a dozen. no measured threshold exists, and
          Cognitive Load Theory declines to name one on principle.
        end content
      }

      unit wl.authoring.boundary kind document.rule "Split and merge" {
        ref "13 B, 13 C"
        name "Boundary"
        meta icon "✂"
        summary "Splitting and merging are one decision read in two directions, and
                 neither is answered by length. A unit splits when its account needs an
                 and-also between two relations, or a fourth co-varying dimension, and it
                 splits where carry-over is smallest — a badly placed split announces
                 itself as a referential stumble, not as overload. It merges where a child
                 entails nothing new, names only its children, or stands as the only
                 child. Splitting has a real price; the seam test itself is
                 theory-motivated, not proven."

        collapsed_summary "A unit splits when its account needs an and-also between two
                           relations, or a fourth co-varying dimension, at the seam where
                           the fewest referents carry over; it merges when a child entails
                           nothing new, only names its children, or stands as an only
                           child."

        preview_summary "Inside: a table of seven verdicts — split, leave, merge, absorb,
                         defect — a drawing of the seam and the referential stumble a bad
                         cut produces, and the price of splitting in effect sizes:
                         retention and transfer up, learning time significantly down."

        content face.table
          | the account | verdict |
          | --- | --- |
          | needs "and also," or a fourth co-varying dimension | split |
          | is merely long | leave it |
          | entails nothing new, or only names its children | merge, or absorb |
          | has exactly one child | defect |
          | stands over simple, parallel children | earns nothing |
        end content

        content markdown
          - **Length is not a signal, in either direction.** No unit is split for volume, and none is kept for it.
          - **One unit, one relation.** The moment an account needs "and also" between two independent relations — or a fourth [co-varying dimension](#wl.authoring.size) — it is two units.
          - **The seam is referential.** A bad split announces itself at the boundary as **wait, what is this referring to?** — never as overload.
          - **Splitting is not free.** Segmenting makes learning significantly slower (d = −0.92), and under reader-controlled pacing the retention gain is marginal (d = 0.19, n.s.) while transfer holds (d = 0.45).
        end content

        content markdown
          | what the account does | the verdict | why |
          | --- | --- | --- |
          | needs "and also" between two independent relations | **split** | one unit carries one relation |
          | needs a fourth dimension that must co-vary | **split** | that is two claims |
          | is merely long | **leave it** | volume is not a signal |
          | states nothing its parent already entails | **merge up** | it is a re-read |
          | only names its children | **absorb it** | it is a label, not a unit |
          | has exactly one child | **defect** | a level that states no relation |
          | stands over simple or obviously parallel children | **earns nothing** | signalling had no effect under simple structure |
        end content

        content diagram
          the seam: cut where the least carries over

            A ─ B ─ C │ D ─ E ─ F      good — nothing crosses the cut
                      ▲
                      └── carry-over is smallest here

            A ─ B ─ C ─ D │ E ─ F      bad — E still needs D
                          ▲
                          └── the reader stumbles at the boundary:
                              "wait, what is this referring to?"

          the unit of substance is ONE COMPLETED STEP of one relation,
          and there is no optimal size, because size follows the
          content's own step structure
        end content
      }

      unit wl.authoring.shape kind document.rule "Width and depth" {
        ref "13 D"
        name "Shape"
        meta icon "📐"
        summary "Two dials control a weave's shape, and they answer to different evidence
                 — their divergence is not a contradiction. Navigation evidence favours
                 wide and shallow: an 8×3 hierarchy was the slowest and most disorienting
                 shape tested. Learning evidence never manipulates fanout at all; what it
                 shows instead is that an explicit superordinate account is what pays.
                 Four rules follow: prefer wide at the top, add a level only for a real
                 account, choose labels for decidability, and allow no cross-links between
                 siblings."

        collapsed_summary "Width is set from navigation evidence — wide at the top,
                           narrower with depth, no cap below about thirty decidable
                           siblings — while depth is set from comprehension evidence,
                           which never varied fanout at all and shows instead that the
                           superordinate account is what pays."

        preview_summary "Inside: the navigation numbers behind wide-and-shallow — 8×3
                         slowest, 16×32 fastest — why no study crosses fanout with
                         comprehension, and the tree's own charge for what it buys: better
                         synthesis, at a real cost in retrieval time."

        content face.table
          | dial | set by |
          | --- | --- |
          | width | navigation — wide at the top, no cap below ~30 decidable siblings |
          | depth | comprehension — a level only where it carries a real account |
          | labels | decidability, not brevity |
          | cross-links | none — every link is paid from working memory |
        end content

        content markdown
          - **Wide at the top, narrower with depth.** 8 × 3 was reliably the slowest and most disorienting shape tested; 16 × 32 was fastest.
          - **The study this question wants does not exist.** No experiment crosses breadth, depth and topology against comprehension, so every fanout number here is a navigation result or a judgment call.
          - **What pays is the superordinate account, not the shape.** An explicit hierarchy raised low-prior-knowledge recall by about a third and left experts untouched.
          - **Labels are chosen for decidability, not brevity.** Label quality, not structure, was the operative factor.
          - **No sibling cross-links.** Lateral links on top of a hierarchy slowed navigation in 4 of 5 studies and bought nothing.
        end content

        content diagram
          two dials, two bodies of evidence, one shape

            WIDTH ── a navigation dial
                     measured by: search time, disorientation
                     setting:     wide at the top, narrower with
                                  depth; no cap below ~30 siblings,
                                  provided every label decides

            DEPTH ── a comprehension dial
                     measured by: recall, disorientation, reading
                                  order — never fanout, which no
                                  learning study has manipulated
                     setting:     add a level only when it carries
                                  a real account

          they diverge, and the divergence is not a contradiction:
          each dial is set from the evidence that measures it

          and the tree charges for what it buys — a co-present coarse
          view bought about half a grade of synthesis, at ~20% more
          time on retrieval with no gain in answer quality
        end content
      }

      unit wl.authoring.redundancy kind document.mechanism "Redundancy across levels" {
        ref "13 F"
        name "Redundancy"
        meta icon "🔁"
        summary "The same idea at three resolutions is correct, and it is not what the
                 redundancy principle prohibits — that principle is about modal
                 redundancy, not content redundancy, and the two run opposite in sign. The
                 operative rule is that exactly one rendering is visible at a time; a
                 parent's sentence is never re-shown while its child is open. A parent is
                 not a concession — summaries have outperformed full chapters — though no
                 study has tested the same content at two resolutions together."

        collapsed_summary "Depth is a filter over one body of content, not a partition, so
                           every level accounts for everything below; repetition pays only
                           when each descent changes kind, and it turns costly under
                           expertise — show the parent, keep it short, skip in one action."

        preview_summary "Inside: a drawing of depth as a filter over one body of content,
                         the reproduction curve that saturates across levels, and why
                         elision is not restatement — a collapsed section gets opened but
                         spends about 30% less time under attention."

        content face.diagram
          depth 0   ████░░░░░░░░████░░░░
          depth 1   ████████░░░░████░░░░  ← same content, stricter each time
          depth 2   ████████████████░░░░
          pays only when each descent changes KIND: frame → mechanism → verbatim
          a child that changes only length is a re-read
        end content

        content markdown
          - **Content redundancy is not modal redundancy.** Depth is a filter over one body of content, not a partition of it, so every level can account for everything below.
          - **The top is the retention set.** High-level propositions are recalled 2–3× better, so partial coverage in a parent is destructive, not merely incomplete.
          - **Redundancy earns its keep only when each descent changes kind** — frame, then mechanism, then verbatim detail. A child that changes only length is a re-read, which is what [the face](#wl.authoring.face) exists to prevent.
          - **The benefit reverses by expertise** (d = +0.505 for novices, −0.428 for experts), which sets the default: show the parent, keep it short, make skipping one action.
          - **Do not claim spacing or the spiral curriculum as support.** Three resolutions read in one sitting is near-massed, and the measured win in technical documentation is cutting, not layering.
        end content

        content diagram
          a filter over one body of content — never a partition

            depth 0            ██░░░░░░░░░░░░░░░░░░░░░░░░░░
                                 ▲  stricter again
            depth 1            ████░░░░░░░░░░░░████░░░░░░░░
                                 ▲  a stricter relevance criterion
            depth 2            ████████░░░░████░░░░████░░░░
                                 ▲
            the whole content  ████████████████████████████

          the rules are applied again at each level up, until a single
          proposition — essentially a title — remains. so every level is
          an account of ALL of it, and the return saturates:
          1 − (1 − m)^k  rises steeply, then flattens

          elision is NOT restatement: a collapsed level is opened but
          under-attended (~30% less time on it), so a parent must be a
          SUBSTITUTE for its children and never a pointer to them
        end content
      }

      unit wl.authoring.face kind document.mechanism "The face" {
        ref "13 G"
        name "Face"
        meta icon "📊"
        summary "The face is a convention about composing the account, not a new
                 construct: it lives in ordinary fields and content blocks. Open, a
                 unit shows a gist to read, a distillate to scan, and a figure only
                 where a mechanism affords one — five element types, chosen by the
                 claim, and a fact a child carries is a door to it. Closed, it shows
                 one element, three to five rows. Every account spills
                 its outcomes — only `preview_summary` may invite — and no element is
                 an essay: it changes shape or moves down, never densifies."

        collapsed_summary "A unit's face composes from five element types — paragraph,
                           bullets, table, diagram, timeline — and the claim picks the
                           shape: a comparison faces as a table, a sequence as a
                           timeline, independent facts as bullets, a mechanism as a
                           diagram. Several when open, one when closed, uniform
                           across siblings, none past three to four lines, every account
                           spilling its outcomes, and every child's fact carrying a door
                           to it."

        preview_summary "Inside: why the gist is read and the distillate scanned, the
                         spill rule that bans the teaser from every rung but the
                         preview, a drawing of the two readings that never show at
                         once, and the five-shape vocabulary mapped to its trigger —
                         comparison, sequence, independent facts, mechanism, one
                         sentence."

        content face.table
          | the claim is | the shape |
          | --- | --- |
          | a comparison | table |
          | a dated sequence | timeline |
          | independent facts | bullets |
          | a mechanism | diagram |
          | one sentence | paragraph — no face block at all |
        end content

        content markdown
          - **The gist is read; the distillate is scanned.** Different jobs, not two lengths of one sentence. Two to five bullets, one load-bearing fact each — a number, a name, a mechanism.
          - **The spill rule: a weave has no spoilers.** The account includes outcomes, endings, and conclusions — never a teaser; only `preview_summary` may invite, and a gist that protects a surprise fails completeness.
          - **The claim chooses the shape** — paragraph, bullets, table, diagram, timeline. Two elements stating one claim in two shapes are one statement rendered twice, the same discipline [the summary ladder](#wl.constructs.summaries) itself keeps.
          - **Short breath: three to four set lines, roughly 60–90 words.** What needs more room changes shape or moves down a level. It is never tightened into density.
          - **Bullets are doors.** A fact a child carries links that child, so deciding where to dig costs one activation; a link that resolves nowhere renders as plain text.
          - **Open takes several elements; closed takes exactly one.** And faces are uniform across siblings, because a scan pattern is learned once per level.
        end content

        content diagram
          the face has two readings, and they never show at once

          OPEN — the unit is the active world

            GIST        the summary paragraph — complete and true,
                        a SUBSTITUTE for the children       ── read
                        and it SPILLS: outcomes, endings and
                        conclusions included — the hook lives
                        in preview_summary alone

            DISTILLATE  2–5 bullets, one load-bearing fact each
                        (a number · a name · a mechanism) ── scanned

            FIGURE      one visual block, and ONLY where the material
                        holds a flow · arithmetic · timeline ·
                        comparison                          ── seen

          CLOSED — the unit is seen from outside

            at most ONE `face`-role block, the first, standing in
            for the prose summaries. 3–5 rows is the ceiling.

          one vocabulary serves both; the CLAIM picks the element,
          and never variety:

            a comparison        ─► table
            a dated sequence    ─► timeline
            independent facts   ─► bullets
            a mechanism         ─► diagram
            one sentence        ─► paragraph, and no face block at
                                   all; the summary ladder carries it

          two elements stating ONE claim in two shapes are one
          statement rendered twice

          and no element is an essay — 3–4 set lines, ~60–90 words.
          past that it CHANGES SHAPE or MOVES DOWN, never densifies

          all of it is ordinary fields and content blocks, so the core
          gains nothing: a tool that shows only summaries still holds a
          valid weave, and a tool that knows no roles renders a face
          block as ordinary material, which degrades to honest
        end content
      }

      unit wl.authoring.checklist kind document.rules "The thirty-seven checks" {
        ref "13 H"
        name "Checklist"
        meta icon "📋"
        summary "The checklist is where every law in this area becomes runnable:
                 thirty-seven checks, run per unit and bottom-up, where a failure is a
                 defect rather than a preference. They fall into four groups, one per
                 thing that can go wrong independently — truth and completeness, size,
                 shape and surface, and the face — twelve, ten, six and nine items.
                 Bottom-up is load-bearing: coverage, entailment and direction are
                 statements about children, so a unit checked before them is checked again
                 after."

        collapsed_summary "Thirty-seven checks in four groups — twelve on truth and
                           completeness, ten on size, six on shape and surface, nine on
                           the face — run per unit and bottom-up, because coverage,
                           entailment and direction are all statements about children."

        preview_summary "Inside: all thirty-seven checks, verbatim, grouped under truth
                         and completeness, size, shape and surface, and the face — the
                         exact wording a tool runs against a finished weave, item by
                         item."

        content face.table
          | group | items | catches |
          | --- | --- | --- |
          | truth and completeness | 12 | the teaser, the fabrication, the outline |
          | size | 10 | two claims in one unit, a level that states no relation |
          | shape and surface | 6 | a fanout hit, a cross-link, a statement shown twice |
          | the face | 9 | the wrong shape, a withheld ending, a sentence-title |
        end content

        content markdown
          - **12 items on truth and completeness** — they catch the teaser (survives a negated child fact), the fabrication (entailed by no child), and the outline (producible by deletion).
          - **10 items on size** — one relation, at most three co-varying things, a residue under a dozen, no split for length, no lone child, no inherited boundary.
          - **6 items on shape and surface** — real levels, decidable labels, no sibling cross-links, one rendering at a time, a one-action skip, and each descent a different kind.
          - **9 items on the face** — the gist substitutes, a distillate where a unit stands on three or more independent facts, a figure only on affordance, siblings uniform, one shape per claim, bullets that open doors, no rung past three to four lines, every outcome spilled, and titles that address the subject.
          - **Bottom-up is load-bearing.** Coverage, entailment and direction are statements about children, so a unit checked before its children must be checked again after them — the same order [a writing tool](#wl.tools.write) runs the audit in.
        end content

        content markdown
          Run per unit, bottom-up. A failure is a defect, not a preference. Thirty-seven
          items in four groups.

          **Truth and completeness**

          - **1. Claim in the account, subject in the title.** The unit's summary asserts something; the title addresses the subject directly in two to five words and is not a sentence.
          - **2. Invention.** The parent's claim is true of all children and appears verbatim in none.
          - **3. Entailment.** Every parent statement is a deletion, an immediate-superset generalization, or a construction over the children. Negate any single child fact — if the parent still reads true, it is not about that child.
          - **4. Interpretation conditions.** Nothing is deleted that a remaining parent statement cannot be interpreted without.
          - **5. Standalone.** With all children deleted, the parent still reads as one connected account.
          - **6. Total coverage.** Every child is accounted for. No child is silently unmentioned.
          - **7. Direction.** For every dependency among children, the parent states which way it runs. A reader can tell "therefore" from "because".
          - **8. Parts up, interactions down.** The parent names the components and their characteristics; the children carry how they interact.
          - **9. Gap placement.** The parent is complete at the level of fact and silent at the level of mechanism — never the reverse.
          - **10. Verbatim.** Every exact string, number, signature, or flag name lives verbatim in a leaf and is not paraphrased upward.
          - **11. Revision marked.** A child that overturns something its parent implies says so, in the child.
          - **12. Purpose declared.** The weave states the reader and purpose that set its relevance criterion.

          **Size**

          - **13. One relation.** The account turns on a single relation — comparison, cause, problem/solution, sequence — not a collection of descriptions.
          - **14. Ternary ceiling.** The claim relates at most three things that must co-vary.
          - **15. Interacting-idea count.** Strike ideas already known to the intended reader and ideas that depend on nothing; the residue is well under a dozen.
          - **16. No volume splits.** No unit was split for length alone.
          - **17. Seam.** Every split falls where referents carry over least; no child opens with an unresolvable reference.
          - **18. Child earns its place.** Every child states at least one proposition not inferable from its parent.
          - **19. No lone children.** No unit has exactly one child.
          - **20. No pointer units.** No unit's account merely names its children.
          - **21. No padding.** No unit contains material that lengthens it without adding a main idea.
          - **22. Boundaries recut.** Unit boundaries are not inherited from the source's own segmentation where meaning cuts differently.

          **Shape and surface**

          - **23. Depth earns itself.** Every level carries a real account; none exists to hit a fanout number.
          - **24. Labels decide.** Every sibling label lets a reader choose without opening it.
          - **25. No sibling cross-links.**
          - **26. One rendering.** A given statement is visible in exactly one place at a time.
          - **27. Skippable.** The parent shows by default; skipping it and descending are each one action.
          - **28. Each descent changes kind.** Frame, then mechanism, then verbatim detail — no level differs from its parent only in length.

          **Face**

          - **29. Gist present.** The unit's summary is a substitute for its children, not a pointer at them.
          - **30. Distillate where it pays.** A unit standing on three or more independent facts carries 2–5 bullets, each holding a number, name, or mechanism; none restates the gist's phrasing.
          - **31. Figure only on affordance.** A visual exists exactly where the unit's material holds a flow, arithmetic, timeline, or comparison — and nowhere else.
          - **32. Uniform faces.** Siblings at one level compose their faces the same way.
          - **33. Shape by claim.** Every gist element's type — paragraph, bullets, table, diagram, timeline — is the one its claim calls for; no claim is rendered in two shapes.
          - **34. Bullets are doors.** Each authored bullet whose fact a child carries links that child; no link targets an id that does not resolve.
          - **35. Short breath.** No gist paragraph or summary rung runs past three to four set lines; what needs more room changes shape or moves down a level, never densifies.
          - **36. The spill.** The account states every outcome, ending, and conclusion at its resolution — nothing withheld for effect; teaser language in a gist is a defect.
          - **37. Direct titles.** The title addresses the unit's subject in two to five words, never a sentence; the claim lives in the summary. Child boxes carry the title where it fits, grandchildren the 1–2 word name, and below that the icon.
        end content

      }

      unit wl.authoring.unsettled kind document.boundary "Five open questions" {
        ref "13 I"
        name "Unsettled"
        meta icon "❓"
        summary "The area names its own open questions, because a judgment call left
                 unmarked reads exactly like a measurement. No study crosses branching
                 factor with depth against comprehension, so every fanout number here is a
                 navigation result or a call. No measured threshold for unit size exists
                 either, and the number of levels is unevidenced the same way. Whether one
                 piece of writing can be both a substitute and a good preparation is
                 untested. And every study cited used linear prose read once, in documents
                 far smaller than a weave."

        collapsed_summary "Five open questions, named so no judgment call passes as a
                           result: no study crosses fanout with depth, no threshold for
                           unit size exists, the number of levels is a call, substitute
                           versus organizer is untested, and every cited study used linear
                           prose read once."

        preview_summary "Inside: a table pairing each open question with its status and
                         what stands in for an answer — the fanout study that does not
                         exist, the uncalibrated size threshold, and an evidence base of
                         linear prose read once, in documents far smaller than a weave."

        content face.table
          | the question | status |
          | --- | --- |
          | how wide, against how deep | no study exists |
          | how big one unit may be | no measured threshold |
          | how many levels | unevidenced |
          | substitute, or organizer | untested |
          | does any of it transfer to a tree | an inference |
        end content

        content markdown
          | the question | its status | what stands in for an answer |
          | --- | --- | --- |
          | how wide, against how deep | **no study exists** | navigation results, and a stated call |
          | how big one unit may be | **no measured threshold** | one published count: 16 elements in 171 words |
          | how many levels | **unevidenced** | three, with a fourth where the material forces it |
          | substitute, or organizer | **untested** | organizer first; the substitute property follows from coverage |
          | does any of it transfer to a tree | **an inference** | the mechanisms generalise; the shapes do not |
        end content
      }
    }

  }

  relation r.authoring_operationalises_truth kind enables {
      from  wl.authoring.parent
      to    wl.depth.true
      label "the second invariant names the duty; the macrorules are what discharge it"
      summary "Depth states that every depth must be true of the material below it, and stops there. The parent's account is where true acquires operative content: every statement is a deletion, an immediate-superset generalization, or a construction over the children, entailment is the necessary condition, and negating a single child fact is the test that separates an account from a teaser. Read alone, the invariant names a duty nobody can visibly fail; read together, it names three operations and two tests."
    }

    relation r.face_composes_what_the_summaries_schedule kind refines {
      from  wl.authoring.face
      to    wl.constructs.summaries
      label "the three summaries say WHEN; the face says HOW the read one is composed"
      summary "The three summary fields are declared as three jobs for three reading moments, and they settle which field a renderer reaches for at each moment. Not one of them says how the active world's account is put together. The face is that missing half: a gist to be read, a distillate of two to five load-bearing bullets to be scanned, and a figure only where the material holds a real structure. It adds no field to the language."
    }

    relation r.checklist_gates_what_generation_promises kind supports {
      from  wl.authoring.checklist
      to    wl.tools.write
      label "eleven rules bind the writer; thirty-seven checks bind the finished weave"
      summary "The generation rules bind a model while it writes: never edit the material, describe rather than pad, plan flat and emit nested. They are obligations on the act. The checklist is the other side of the same duty — thirty-seven checks run per unit and bottom-up against a weave that already exists, several of them statements about children that no single downward pass can answer. Rule 11 is the join: it sends the finished weave through the checklist in a pass the writing model does not run."
    }

  relation r.parts_make_compression kind supports {
      from  wl.material.parts
      to    wl.subject.compression
      label "ordered parts are why a description is a place, not a gap"
      summary "The thesis claims that written and described parts sit in one tree with no seam, and that claim is cashed by a rule stated elsewhere: a unit's material is its parts in the order they are written, and a child contributes its own material. Because composition is total and ordered, a part carrying no bytes still occupies its exact place among the parts around it. Remove the ordering and a described part stops being an address and becomes an absence."
    }

    relation r.razor_decides_kinds kind supports {
      from  wl.weakness.razor
      to    wl.conventions.open_kinds
      label "an open kind string is the razor's largest single application"
      summary "Kinds are strings rather than an enum for exactly the reason the razor gives: a closed list is a commitment no observed material forces, and it shrinks the set of subjects the design still handles. The principle is stated once, with the razor. This is the instance that decides the most, because it is the one that decides which subjects are permitted to exist at all."
    }

    relation r.naming_costs_self_containment kind qualifies {
      from  wl.named.naming
      to    wl.subject.self_contained
      label "named material withdraws the self-containment the thesis grants by default"
      summary "The thesis grants self-containment as the default: with every part written out, the file holds the thing it is about. Naming material withdraws that one grant and changes nothing else, because the semantics are identical and only the storage differs. The specification calls it a trade a tool may make and never a default the language prefers, so the two statements bound each other rather than conflict."
    }

    relation r.naming_needs_a_pinned_source kind depends_on {
      from  wl.named.naming
      to    wl.constructs.source
      label "a locator resolves only against an origin pinned somewhere else"
      summary "Named material carries `in <source>`, `at`, `region` and `sha256`, and not one of them resolves alone. The source construct is what they resolve against, declared once per origin so the revision is stated in exactly one place. Read apart, `source` looks like an optional header field; read together, it is the half of named material that fixes which revision every leaf read."
    }

    relation r.material_bounds_canonicalization kind qualifies {
      from  wl.material.literal
      to    wl.notation.canonicalization
      label "the one thing a canonicalizer may never normalise is stated with the material"
      summary "Canonicalization is a licence: order the units, normalise ids and convention names, expand shorthand edges, normalise times, dedupe references. The material rules carve out its single exclusion — never tidy, reflow, or rewrap — which canonicalization restates as dedented, never reflowed. A canonicalizer that rewraps a paragraph has not tidied a file; it has corrupted the material."
    }

    relation r.textblocks_defer_to_material kind depends_on {
      from  wl.notation.textblocks
      to    wl.material.literal
      label "the syntax chapter defers the block rules instead of repeating them"
      summary "Any text-valued keyword may open a block, and that is the only place whitespace carries meaning in the language. Where the block ends, that every line between is verbatim with no escapes, and that indentation is stripped per unit rather than per block are all stated once, with material. The notation area is deliberately incomplete on its own, and reading it alone leaves a parser author short of the rules."
    }

    relation r.described_must_stay_visible kind depends_on {
      from  wl.tools.render.material
      to    wl.material.described
      label "described is a position, so a renderer must show it"
      summary "The written-and-described table says a described part occupies a position, is addressable, and lacks only bytes. That is why a renderer may never silently omit one: a reader who cannot see that something belongs here has been told the material is complete when it is not. The table states the property; the rendering rule is where the property becomes an obligation, and it names the one error a reader cannot detect from inside the view."
    }

    relation r.outline_supplies_the_facts kind enables {
      from  wl.named.laws
      to    wl.tools.render.material
      label "the outline supplies facts; the renderer supplies policy"
      summary "Real line boundaries, containment, gists and ranks are stated as laws about the source, never as display instructions. They are what lets a renderer resolve material it does not hold: it folds on region boundaries, shows a gist in place of what it hid, and opens high ranks at shallower depth. A renderer holding only a line range and no outline has no fact to fold on and must cut arbitrarily."
    }

    relation r.truth_level_checks_the_invariant kind enables {
      from  wl.tools.validate
      to    wl.depth.true
      label "the truth level is where the second invariant becomes a check"
      summary "Depth states that every depth must be true of the material below it, and notes that material makes this checkable. Validation is where the check exists: the truth level holds each summary against its own subtree, refuses a low-confidence claim rendered as fact, and requires a contradiction to appear as an explicit relation rather than as an omission. The invariant names the duty; the level names who runs it, and against what."
    }

    relation r.unknown_kinds_stay_warnings kind depends_on {
      from  wl.tools.validate
      to    wl.conventions.open_kinds
      label "convention checks are advisory because a closed world would defeat open kinds"
      summary "Validation is otherwise a list of errors. Unknown convention terms are the deliberate exception, and the reason is not leniency: an unknown kind that failed validation would restore the closed list of admissible subjects that the open-kind rule exists to prevent. Advisory is the only setting compatible with a vocabulary the core never learns."
    }

    relation r.a_brief_needs_its_neighbours kind depends_on {
      from  wl.tools.fill
      to    wl.material.composed
      label "the literal parts on either side are what fix a described unit's brief"
      summary "Writing a described unit uses the parts around it: the preceding part shows what the new material must continue, and the following part shows what it must lead into. That instruction only means something because a unit's parts are ordered and a described unit sits between two of them. Remove the ordering rule and the writer loses its sharpest constraint — sharper than any summary, because it is the actual bytes the result has to join."
    }

    relation r.three_summaries_three_sets kind enables {
      from  wl.constructs.summaries
      to    wl.tools.render.query
      label "each summary is written for one of the three sets a query returns"
      summary "The three summaries are declared as three jobs for three reading moments. The rendering query is where those moments become mechanical: ancestors render from `collapsed_summary`, children from `preview_summary`, and the active world from `summary`. Neither statement is complete alone — one says why the fields differ, the other says when each is read, and only together do they say why a unit carries three and not one."
    }

    relation r.props_absorb_the_short_table kind qualifies {
      from  wl.weakness.props_meta
      to    wl.constructs.unit
      label "props and meta hold every field the unit table declines to name"
      summary "The unit's field table is short, and its shortness is a decision rather than an omission. Risk, severity, status, time, value, actor and condition are all things authors really record; they are absent from the core because two open mechanisms carry them under whatever convention applies. A reader who studies the field table alone would wrongly conclude the language cannot express a judgment."
    }

    relation r.reveals_needs_global_ids kind depends_on {
      from  wl.depth.reveals
      to    wl.notation.identifiers
      label "a shared child works only because ids are global"
      summary "`reveals` lets a child be declared once and appear under more than one parent. That is possible only under the identifier rule: ids are globally unique within a weave and independent of nesting, so a deeply nested id stays addressable from anywhere. Make ids path-scoped and reveals collapses into duplication."
    }

    relation r.ref_is_a_copy kind supports {
      from  wl.constructs.ref
      to    wl.tools.write
      label "ref earns its place by being a copy, so never prettify it"
      summary "A ref is the one string in a weave that cannot be wrong, because it is copied rather than interpreted. The generation rules turn that property into an obligation: copy it verbatim, never normalise, renumber, or prettify it. A tidied ref keeps its shape and loses the entire reason the core carries the field."
    }

    relation r.opacity_carries_code kind enables {
      from  wl.weakness.nongoals
      to    wl.material.literal
      label "refusing to parse a block is what lets a block hold anything"
      summary "Literal material is unescaped and undelimited and may contain any syntax, including this language's own. The refusals are why: the core never parses, evaluates, or type-checks what a block holds, and knows only where the material sits in the structure of meaning. WeaveLang carries source code because it declined to become one, so opacity and the non-goals are the same decision read from two ends."
    }

    relation r.creed_is_a_result kind depends_on {
      from  wl.subject.creed
      to    wl.weakness.razor
      label "five constructs is a result of the selection rule, not an aesthetic"
      summary "The creed reads as a stylistic boast until it is read against the razor. Every construct absent from the language is absent by one argument: nothing in the observed material could not be decided without it, and each addition would have shrunk the set of subjects still expressible. The count is what the criterion produced, and it changes only when real material cannot be decided without a sixth."
    }

    relation r.two_different_ladders kind refines {
      from  wl.tools.render.material
      to    wl.material.resolution
      label "two ladders: the renderer's sits inside a single rung of the other"
      summary "Both areas print a short ladder, and they measure different things. The material ladder runs over a unit's parts: its own summary, then its children's summaries, then the literal parts verbatim with described parts standing as their summaries. The renderer's ladder runs over the grain of one written part: files and symbols, then signatures and hunks, then exact lines. The second refines a single rung of the first, and neither converts into the other."
    }

    relation r.useful_keeps_the_promise kind supports {
      from  wl.depth.useful
      to    wl.subject.resolution
      label "the first invariant is what makes stopping safe"
      summary "The thesis promises that nothing skipped was load-bearing, which is a promise about the level the reader stopped at rather than about the levels below it. The useful-by-itself invariant is the whole of its enforcement: a summary that forces a reader downward to learn anything has already broken it. One semantically empty depth falsifies the guarantee for every reader who stopped above it."
    }

    relation r.subsymbol_names_the_form kind enables {
      from  wl.conventions.subsymbol
      to    wl.tools.fill
      label "one kind string tells a writer what form the missing material takes"
      summary "A writer filling a described unit reads its `kind` to learn what form the material takes, and the sub-symbol vocabulary is what makes that string informative below the level of a whole symbol. `go.fields` on a unit with no material asks for struct members rather than prose; `guard` asks for a precondition check. The core knows none of this, so the narrowing is done entirely by a convention the tool happens to hold."
    }

    relation r.json_keeps_no_flag kind depends_on {
      from  wl.notation.json
      to    wl.material.described
      label "the machine surface adds no flag either: empty parts is the whole signal"
      summary "In the text form the written/described distinction is carried by nothing but the absence of material. Canonical JSON preserves that exactly: a unit with an empty `parts` array and no children is described, and no field anywhere says so. The encoding depends on the rule instead of restating it — add a boolean and the two surfaces could disagree about which units are written."
    }
}