@vertekum/schema-builder 0.1.7 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @vertekum/schema-builder
 
+## 0.2.1
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @vertekum/core@0.2.1
+
+## 0.2.0
+
+### Minor Changes
+
+- [`1faab42`](https://github.com/moros-oxus/vertekum/commit/1faab429acdd5c53565b3975654ce8da05e89bfc) Thanks [@tschemmer](https://github.com/tschemmer)! - The emission model: public productions emit as open `$defs` patterns (sealing belongs to the positions that apply them, composed via `allOf`); `:name` declares a private production — inlined, invisible to importers; the `scope` pragma names the file's nature (`document` | `def` | `inline` — a def file's root also lands as `$defs.<filename>` and rootless files emit defs-only artifacts by default) while `sealed "true" | "false"` takes over the document-top seal (`scope "branch"` parses as a deprecated alias); the empty leaf dedupes into `$defs.terminal`; `schemaId` derives artifact `$id`s from a configured base; linked emission gains `#/$defs/…` pattern refs; lint reports non-failing warnings (open-merge, deprecations). Atlassian artifacts regenerate under the new shape — the granted vocabulary is unchanged.
+
+### Patch Changes
+
+- [`84172d2`](https://github.com/moros-oxus/vertekum/commit/84172d2ca90320b60ec4c42730a69c056631a81c) Thanks [@tschemmer](https://github.com/tschemmer)! - Affixed scales: a parenthesized formula may carry word fragments on either or both ends — `(2-4)xs` → `2xs 3xs 4xs`, `xs(2-4)`, `x(2-8/2)s` — with the full formula grammar (geometric ratios, quantization, zero-pad) available inside the parentheses. `evaluateScale` gains optional `prefix`/`suffix`; affixes wrap the names while values stay numeric. The additive step is now optional: `2-4` means `2-4/1`.
+
+- [`cd36a42`](https://github.com/moros-oxus/vertekum/commit/cd36a421dbec1a71a06f173a32dbcd4482f85199) Thanks [@tschemmer](https://github.com/tschemmer)! - `schema lint`, `schema fmt`, and `schema build` accept a directory argument and sweep it — `.dfn` sources need not live under `./schemas`. A nonexistent path errors up front instead of `1:1 cannot read`.
+
+- [`be89083`](https://github.com/moros-oxus/vertekum/commit/be89083f58d8d01062240a84679ea9967071b3c4) Thanks [@tschemmer](https://github.com/tschemmer)! - Adds `vertekum schema fmt` — canonical `.dfn` formatting with JS-literal block indentation (indent resolves from `format.indent`, then `.editorconfig`), `--check` as the CI gate — and `schema lint --fix`, which relocates a misplaced trailing `*` into the reference or group it opens. The grammar itself gains block statements: a statement ends at the first newline at bracket depth 0, so a multi-line `[ … ]` may close at any indentation, and an unclosed `[` reports its opening position.
+
+- [`c81e024`](https://github.com/moros-oxus/vertekum/commit/c81e024133cf4f67b3cf690bfb77b849921ca9a2) Thanks [@tschemmer](https://github.com/tschemmer)! - Linked emission (`schemaBuilderExtension({ link: true })`): an unmodified `<@module>` root embedding emits a `$ref` into the child module's own artifact — `"color": { "$ref": "./primitives/color.json#/properties/color" }` — instead of inlining a duplicate. Property keys stay local so sealing is unchanged; modified, open, tailed, and production references still inline, as do modules the project does not build. Default remains self-contained artifacts.
+
+- [`ef1ca4a`](https://github.com/moros-oxus/vertekum/commit/ef1ca4a0b696b799275c0f0acf7fde9414793f8d) Thanks [@tschemmer](https://github.com/tschemmer)! - Pick/omit lists take references as members — set algebra with sets as operands: `<@fullcolors ![<@fullcolors/saturated>, white]>` omits every saturated name plus white. Operands resolve with normal scope and privacy rules, keep member-by-member validation, and an open member reference is refused.
+
+- [`1de5e76`](https://github.com/moros-oxus/vertekum/commit/1de5e76929f9a1e17e6625cb3bfd36a3fd86ceec) Thanks [@tschemmer](https://github.com/tschemmer)! - The input/output pair is configurable on the extension — `schemaBuilderExtension({ source: './src/dfn', out: './src/schemas' })`. `source` becomes the default sweep for `schema build`, `lint`, and `fmt`; `out` redirects built schemas, mirroring `source`'s directory structure. `schema build` also takes a positional `[out]` for one invocation: a directory argument mirrors into it, a file argument lands directly in it.
+- Updated dependencies [[`84172d2`](https://github.com/moros-oxus/vertekum/commit/84172d2ca90320b60ec4c42730a69c056631a81c), [`82b695e`](https://github.com/moros-oxus/vertekum/commit/82b695e32cf1b7ee37f9d2f2f753aeff8ae3d15f)]:
+  - @vertekum/core@0.2.0
+
 ## 0.1.7
 
 ### Patch Changes

package/README.md

@@ -41,7 +41,8 @@ npx vertekum check                 # the built schema now governs your token nam
 
 The grammar reads the way a design system talks: nesting is `.`, choice is `|`,
 denotations are named productions referenced as `<emphasis>`, scales are enumerated
-expressions (`100-900/100`, `16-64*1.25~4`), and `?` marks a slot as optional. One
+expressions — plain (`100-900/100`, `16-64*1.25~4`) or affixed (`(2-4)xs` → `2xs 3xs
+4xs`) — and `?` marks a slot as optional. One
 expression grants a whole syntagm:
 
 ```dfn
@@ -61,7 +62,10 @@ root = color.<property>.<role>?.<emphasis>?.<state>?
 - [`schema build`](./docs/build.md) — the command, the sweep, the ownership stamp, the
   `--check` CI gate, programmatic use.
 - [`schema lint`](./docs/lint.md) — validate the `.dfn` sources themselves: fragments
-  included, every production, findings collected with positions.
+  included, every production, findings collected with positions; `--fix` repairs the
+  mechanical ones.
+- [`schema fmt`](./docs/format.md) — canonical formatting: JS-literal blocks, indent
+  from `format.indent`/.editorconfig, `--check` for CI.
 - [What a build emits](./docs/emission.md) — the names-and-order schema shape, open
   positions, `$defs`, scope; a complete dfn→JSON example.
 

package/docs/build.md

@@ -5,26 +5,51 @@ is contributed by this extension — it exists once `schemaBuilderExtension` is
 project's config, and appears in `vertekum --help` and `vertekum describe` from then on.
 
 ```bash
-# vertekum schema build [module] [--check] [--dry-run] [--json] [--cwd <dir>]
+# vertekum schema build [module|directory] [out] [--check] [--dry-run] [--json] [--cwd <dir>]
 vertekum schema build                       # every module under ./schemas
 vertekum schema build schemas/color.dfn     # one module
+vertekum schema build src/dfn src/schemas   # sweep a directory, mirror into an out dir
 vertekum schema build --check               # CI: verify nothing is stale
 ```
 
 | Argument / flag | What it does                                                                 |
 | --------------- | ----------------------------------------------------------------------------- |
-| `[module]`      | A `.dfn` file, relative to the working directory. Default: the sweep (below). |
+| `[module]`      | A `.dfn` file, or a directory swept with the same semantics as the default (below). Default: the configured [`source`](#configuration). |
+| `[out]`         | Output directory for this run — a directory `[module]` mirrors its structure into it; a file lands directly in it. Default: the configured [`out`](#configuration), else beside each module. |
 | `--check`       | Verify the built files on disk are current; write nothing.                    |
 | `--dry-run`     | Report what would be written without writing — owned by the runner, like every contributed command (see `@vertekum/cli`'s documentation). |
 | `--json`        | Machine-readable result (`files`, plus `skipped` and `fragments` under `data`). |
 | `--cwd <dir>`   | Project discovery starts here.                                                |
 
+## Configuration
+
+The input/output pair is declared once, on the extension:
+
+```ts
+extensions: [
+  schemaBuilderExtension({ source: './src/dfn', out: './src/schemas' }),
+],
+schemas: [{ from: './src/schemas', use: { 'color.json': '*-tokens.json' } }],
+```
+
+| Setting  | Default       | Meaning                                                        |
+| -------- | ------------- | --------------------------------------------------------------- |
+| `source` | `'./schemas'` | Where the `.dfn` modules live — the default sweep for `build`, [`lint`](./lint.md), and [`fmt`](./format.md). |
+| `out`    | — (beside)    | Where built `.json` files land, mirroring `source`'s structure. |
+| `link`   | `false`       | [Linked emission](./emission.md#linked-emission): cross-file embeddings `$ref` the child's artifact instead of inlining a copy. |
+| `schemaId` | —           | Base URI for derived `$id`s: each artifact gets base + its artifact-relative path; a file's `id` pragma wins. |
+
+Input and output are a **pair**, not a redirect: `out` maps modules under `source`
+(and a positional `[out]` maps modules under this invocation's `[module]` root); a
+module outside the pair's root builds beside itself. The stamp-ownership contract and
+`--check` follow the mapped target.
+
 ## The sweep
 
-With no argument, every `.dfn` under the project's `schemas/` directory builds —
-recursively, so nested module directories are included (`node_modules` is not).
-Modules without a `root` are **fragments**: the sweep skips them with a notice, while
-naming one explicitly is an error — see [modules](./modules.md#fragments).
+With no argument, every `.dfn` under the configured `source` builds — recursively,
+with `node_modules` excluded. Every module emits by default (a rootless one emits a
+defs-only artifact); only [`scope "inline"`](./language.md#pragmas) modules are
+skipped, with a notice — and naming one explicitly is an error.
 
 ## Artifacts
 

package/docs/emission.md

@@ -1,29 +1,49 @@
 # What a build emits
 
-A built schema is ordinary JSON Schema (2020-12), in the **names-and-order** shape
-hand-written vocabulary schemas use — so a generated file and a hand-written one are
-interchangeable, and taking ownership of a generated file (removing the stamp) leaves
-you with idiomatic schema, not machine soup.
+A built schema is ordinary JSON Schema (2020-12). One content rule, every file:
+**public productions emit as `$defs` patterns; the root emits as the document's
+`properties` — the definitive syntagma; private productions inline.** A pattern never
+seals — sealing belongs to the positions that apply patterns.
 
-## The position shape
+## Patterns and positions
 
-Every position in the name tree becomes:
+A **pattern** (a `$def` body) is open at its top:
+
+```json
+{ "type": "object", "properties": { "…members…": {} }, "patternProperties": { "^\\$": true } }
+```
+
+A **position** that applies patterns composes them under its own seal:
 
 ```json
 {
+  "allOf": [{ "$ref": "#/$defs/named-even" }, { "$ref": "#/$defs/named-odd" }],
   "type": "object",
-  "properties": { "…declared children…": {} },
+  "properties": { "…locals and expansions…": {} },
   "patternProperties": { "^\\$": true },
   "unevaluatedProperties": false
 }
 ```
 
-- `properties` holds the granted names, one position schema each.
-- `patternProperties: { "^\\$": true }` lets DTCG's structural members (`$value`,
-  `$type`, `$description`, …) pass at every level — the vocabulary governs **names**,
-  not the token format (the format schemas do that separately).
-- `unevaluatedProperties: false` is the closure: a name outside the grant is a
-  violation, which is the entire point of a vocabulary schema.
+- A reference becomes a `$ref` exactly when it **ends its path**; a tail forces
+  expansion at that spot (a `$ref` cannot be parameterized). Modified (pick/omit) and
+  open references always expand — a modified set is a new set.
+- A merge that grew a pattern's member drops the `$ref` back to expansion — emission
+  deep-checks every pattern before referencing it.
+- `patternProperties: { "^\\$": true }` lets DTCG's structural members pass at every
+  level; `unevaluatedProperties: false` is the closure, and 2020-12's `unevaluated`
+  sees through `allOf`/`$ref`, which is what makes sealed composition sound.
+- The empty sealed leaf emits once as **`$defs.terminal`** and is referenced from
+  every leaf.
+
+## The file's nature
+
+Per the [`scope` pragma](./language.md#pragmas): a `document` file emits its root tree
+as sealed properties (per `sealed`, default true). A `def` file emits its `$defs` —
+and when it has a root, the root ALSO lands as `$defs.root` while the document body
+applies it (`allOf`, unsealed by default — pattern-natured), so the file stands alone
+AND serves as a pattern source. Externally, a def module's root is referenced as the
+FILE itself. An `inline` file never emits.
 
 ## Open positions
 
@@ -42,33 +62,68 @@ with a route for additions:
 Additions join the set: they take the same tail every listed member has (which is
 well-defined precisely because `*` is restricted to name-only sets).
 
-## Denotations become `$defs`
+## Linked emission
+
+By default every artifact is **self-contained** — an embedded module's expansion is
+inlined, so a file validates and diffs alone. With `link: true` on the extension
+(see [build § configuration](./build.md#configuration)), an unmodified `<@module>`
+root embedding with nothing threaded beneath it is emitted as a reference into the
+child module's own artifact instead — a document child by top-level name, a def
+child's root as the whole file (or, when the child is `sealed "true"`, as its unsealed
+`…#/$defs/root`), any public production by pattern:
+
+```json
+"color": { "$ref": "./primitives/color.json#/properties/color" }
+{ "allOf": [{ "$ref": "./primitives/color.json" }], "…seal…": "" }
+"scale": { "allOf": [{ "$ref": "./primitives/color.json#/$defs/scale" }], "…seal…": "" }
+```
+
+Property keys stay local — the parent's seal is untouched. What still inlines under
+`link: true`, for correctness: picked/omitted refs (a modified set is a new set),
+open refs, refs with a non-terminal tail (the tail threads through every leaf),
+`scope "inline"` children, and modules this project does not build (package imports).
+Binding validation resolves the linked graph offline via the relative paths;
+standalone validators need the referenced files registered.
 
-A terminal denotation referenced from **two or more** positions is emitted once under
-`$defs` and `$ref`'d — matching how a hand author avoids repeating themselves. A
-single-use denotation is inlined. A [picked or omitted](./expressions.md#pick-and-omit)
-set never shares the source's `$def`: a modified set is a different set.
+## Linked emission
+
+By default every artifact is **self-contained** — an embedded module's expansion is
+inlined, so a file validates and diffs alone. With `link: true` on the extension
+(see [build § configuration](./build.md#configuration)), an unmodified `<@module>`
+root embedding with nothing threaded beneath it is emitted as a reference into the
+child module's own artifact instead:
+
+```json
+"color": { "$ref": "./primitives/color.json#/properties/color" }
+```
+
+The property key stays local — the parent's seal is untouched — and the referenced
+subtree is semantically identical to the inline copy. What still inlines under
+`link: true`, for correctness: picked/omitted refs (a modified set is a new set),
+open refs, refs with a non-terminal tail (the tail threads through every leaf),
+production refs (fragments and productions have no artifact), and modules this
+project does not build (package imports). Binding validation resolves the linked
+pair offline; standalone validators need the referenced files registered.
 
 ## Document keys
 
 | Key                     | From                                                             |
 | ----------------------- | ----------------------------------------------------------------- |
 | `$schema`               | always `https://json-schema.org/draft/2020-12/schema`             |
-| `$id`                   | the [`id` pragma](./language.md#pragmas), when declared           |
+| `$id`                   | the [`id` pragma](./language.md#pragmas), else derived from the configured [`schemaId`](./build.md#configuration) |
 | `$comment`              | the provenance stamp — the [ownership contract](./build.md#ownership-the-stamp) |
 | `title`, `description`  | their pragmas, when declared                                      |
-| `$defs`                 | shared denotations, when any                                      |
-| the root position       | `type`, `properties`, `patternProperties`, and the seal           |
+| `$defs`                 | `terminal`, the public patterns (declaration order), then a def-scope root |
+| the document body       | `allOf?`, `type`, `properties`, `patternProperties`, and the seal |
 
-## Scope
+## Sealing
 
-The [`scope` pragma](./language.md#pragmas) decides the **root** seal only:
-
-- `"document"` (default): the root carries `unevaluatedProperties: false` — nothing
-  beyond the granted top-level names may exist in a bound file.
-- `"branch"`: the root omits it — the schema governs its own branches and ignores
-  siblings, so several per-aspect schemas can bind over one collection. Every level
-  *below* the root stays sealed either way.
+The [`sealed` pragma](./language.md#pragmas) decides the **document top** only:
+`"true"` (default) carries `unevaluatedProperties: false` — nothing beyond the granted
+top-level names may exist in a bound file; `"false"` omits it, so several per-aspect
+schemas can bind over one collection. Every level *below* the top stays sealed either
+way — and patterns are open at their tops by nature, sealed by the positions that
+apply them.
 
 ## A complete example
 
@@ -87,24 +142,19 @@ builds to `schemas/color.json`:
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$comment": "built by @vertekum/schema-builder from schemas/color.dfn — do not hand-edit; remove this comment to take ownership",
   "$defs": {
+    "terminal": {
+      "type": "object",
+      "properties": {},
+      "patternProperties": { "^\\$": true },
+      "unevaluatedProperties": false
+    },
     "emphasis": {
       "type": "object",
       "properties": {
-        "subtle": {
-          "type": "object",
-          "properties": {},
-          "patternProperties": { "^\\$": true },
-          "unevaluatedProperties": false
-        },
-        "bold": {
-          "type": "object",
-          "properties": {},
-          "patternProperties": { "^\\$": true },
-          "unevaluatedProperties": false
-        }
+        "subtle": { "$ref": "#/$defs/terminal" },
+        "bold": { "$ref": "#/$defs/terminal" }
       },
-      "patternProperties": { "^\\$": true },
-      "unevaluatedProperties": false
+      "patternProperties": { "^\\$": true }
     }
   },
   "type": "object",
@@ -112,8 +162,18 @@ builds to `schemas/color.json`:
     "color": {
       "type": "object",
       "properties": {
-        "text": { "$ref": "#/$defs/emphasis" },
-        "icon": { "$ref": "#/$defs/emphasis" }
+        "text": {
+          "allOf": [{ "$ref": "#/$defs/emphasis" }],
+          "type": "object",
+          "patternProperties": { "^\\$": true },
+          "unevaluatedProperties": false
+        },
+        "icon": {
+          "allOf": [{ "$ref": "#/$defs/emphasis" }],
+          "type": "object",
+          "patternProperties": { "^\\$": true },
+          "unevaluatedProperties": false
+        }
       },
       "patternProperties": { "^\\$": true },
       "unevaluatedProperties": false
@@ -124,6 +184,8 @@ builds to `schemas/color.json`:
 }
 ```
 
-`<emphasis>` sits at two terminal positions (`color.text`, `color.icon`), so it became
-a shared `$def`. A token file bound to this schema may hold `color.text.subtle` with
-any `$`-members along the way — and nothing named outside the grant.
+`emphasis` is a public production, so it emits as an open pattern in `$defs`; the
+positions `color.text` and `color.icon` apply it under their own seals; every empty
+leaf is one `$ref` to `$defs.terminal`. A token file bound to this schema may hold
+`color.text.subtle` with any `$`-members along the way — and nothing named outside
+the grant.

package/docs/expressions.md

@@ -15,7 +15,7 @@ production's `=` is one of these forms, freely composed.
 | [`<name ![a, b]>`](#pick-and-omit) | **omit** — the set minus the listed members           |
 | [`<name*>`, `[a \| b *]`](#open-sets) | **open set** — additions are permitted             |
 | [`step?`](#optional-slots) | **optional slot** — the step may be skipped                   |
-| [`100-900/100`, `16-64*1.25~4`](./scales.md) | a numeric scale, enumerated at build — see [scales](./scales.md) |
+| [`100-900/100`, `16-64*1.25~4`, `(2-4)xs`](./scales.md) | a numeric scale, enumerated at build, optionally affixed — see [scales](./scales.md) |
 
 ## Nesting
 
@@ -80,7 +80,17 @@ use "./space.dfn"
 root = space.[<scale> | negative.<scale ![0, 1000]>]
 ```
 
-A modified set is a **new** set: it never shares the source denotation's `$def` in the
+A member may itself be a **reference**, denoting every name of the set it names — set
+algebra with sets as operands, validated member-by-member exactly like plain names
+(and an open member `<x*>` is refused: an operand names a closed set):
+
+```dfn
+use "./fullcolors.dfn"
+
+accent-only = <@fullcolors ![<@fullcolors/saturated>, white]>
+```
+
+A modified set is a **new** set: it never shares the source pattern's `$def` in the
 built schema — narrowing a set and changing the set are the same act. Naming the
 narrowed form derives a new denotation:
 

package/docs/format.md

@@ -0,0 +1,75 @@
+# `vertekum schema fmt`
+
+Canonical formatting for the `.dfn` sources. One style, mechanically applied — the
+choices that stay yours are *where* statements break; everything inside that choice is
+the formatter's.
+
+```bash
+# vertekum schema fmt [module|directory] [--check] [--dry-run] [--json] [--cwd <dir>]
+vertekum schema fmt                       # every module under ./schemas
+vertekum schema fmt schemas/color.dfn     # one module
+vertekum schema fmt --check               # CI: verify formatting, write nothing
+```
+
+| Argument / flag | What it does                                                                 |
+| --------------- | ----------------------------------------------------------------------------- |
+| `[module]`      | A `.dfn` file **or directory** (swept recursively), relative to the working directory. Default: every module under the configured [`source`](./build.md#configuration) — fragments included. |
+| `--check`       | Verify formatting; write nothing. Unformatted files are an error (exit `1`).   |
+| `--dry-run`     | Report what would be rewritten without writing.                                |
+| `--json`        | Machine-readable result.                                                       |
+| `--cwd <dir>`   | Project discovery starts here.                                                 |
+
+A module whose grammar cannot even be lexed is **skipped with a notice** — broken
+grammar is [`schema lint`](./lint.md)'s report, and fmt never rewrites what it cannot
+read.
+
+## Blocks: JS-literal formatting, your break choices
+
+A `[` with content on its line is **inline**; a `[` followed by a newline is a
+**block** — exactly a JavaScript array literal, and exactly what the grammar means: a
+statement ends at the first newline at bracket depth 0, so a block carries its
+statement to the matching `]`. The formatter never changes which you chose. What it
+normalizes, recursively at any depth:
+
+- each block level indents **one unit**;
+- the closing `]` dedents to its opener's line;
+- a leading `|` sits at its level's indent;
+- inline groups ride inside block levels without adding one.
+
+```dfn
+root = color.[
+  <property>.<role>?.<emphasis>?
+  | border.[bold | code | focused]
+  | interaction.[
+    hovered
+    | pressed
+  ]
+]
+```
+
+## The indent unit resolves from what the repo uses
+
+1. **`format.indent`** in `vertekum.config.ts` — the same field JSON output honors.
+2. **`.editorconfig`** — standard walk-up and section cascade for the file
+   (`indent_style` / `indent_size`; `[*.dfn]` over `[*]`; `root = true` stops the walk).
+3. Default: two spaces.
+
+Everything below the indent unit — bracket hugging, operator spacing, comma style — is
+**canonical, deliberately without knobs**: `.dfn` files are published, ejected, and
+diffed across repos, and one style is what keeps those diffs meaningful.
+
+## Canonical spacing
+
+| Around                | Rule                                        | Example                  |
+| --------------------- | ------------------------------------------- | ------------------------ |
+| `=`, `\|`             | one space each side                         | `a = b \| c`             |
+| `.`                   | tight                                       | `color.text`             |
+| `?`                   | tight to its step                           | `<role>?`                |
+| `*`                   | tight in a reference; spaced before `]`     | `<x*>`, `[a \| b *]`     |
+| pick/omit             | space before `[`/`![`; `, ` between members | `<scale ![0, 1000]>`     |
+| group after a dot     | tight                                       | `color.[text \| icon]`   |
+| affixed scales        | tight throughout                            | `(2-4)xs`                |
+| comments              | full-line at its level; trailing two spaces off the code | `100  # loud` |
+
+Plus hygiene: trailing whitespace stripped, blank-line runs collapse to one, exactly
+one trailing newline.

package/docs/language.md

@@ -17,15 +17,17 @@ root = color.[text | icon].<role>.<@emphasis>
 
 ## Lexical rules
 
-- **Statements are lines.** One statement per line; a line that starts with whitespace
-  **continues** the statement above it, so a long expression wraps without any
-  continuation character:
+- **A statement ends at the first newline at bracket depth 0.** A `[` whose content
+  continues past its line opens a **block**, closed by its `]` — newlines inside are
+  insignificant, nesting is unbounded, and an unclosed `[` reports its opening
+  position. A line that starts with whitespace also continues the statement above it
+  (the unbracketed-wrap fallback).
 
   ```dfn
   root = color.[
-      <property>.<role>?.<emphasis>?
+    <property>.<role>?.<emphasis>?
     | <code>
-    ]
+  ]
   ```
 
 - **`#` starts a comment**, running to the end of the line.
@@ -33,24 +35,29 @@ root = color.[text | icon].<role>.<@emphasis>
   digits **when they contain a letter** (`2xs`, `4k-display`). A term that is purely
   numeric keeps its numeric meaning: a bare number (`950`) or a
   [scale expression](./scales.md) (`100-300/50`) — which is why hyphens inside names
-  never collide with range syntax.
+  never collide with range syntax. A parenthesized formula with word affixes
+  (`(2-4)xs`) is one term; parentheses appear nowhere else in the grammar.
 - **Strings** (pragma and `use` arguments) are double-quoted.
 
 ## Statements
 
 | Statement                | What it is                                                       |
 | ------------------------ | ----------------------------------------------------------------- |
-| [`name = expression`](#productions) | A **production**: a named fragment of the vocabulary.  |
-| [`root = expression`](#root)        | The reserved production a build materializes.          |
+| [`name = expression`](#productions) | A **public** production — a named export: importable (`<@mod/name>`) and emitted as a `$defs` pattern. |
+| [`:name = expression`](#productions) | A **private** production — inlined at use, invisible to importers. |
+| [`root = expression`](#root)        | The default export: the definitive syntagma.           |
 | [`use "…" [as name]`](#use)         | Import another module.                                 |
-| [`id` / `title` / `description` / `scope` `"…"`](#pragmas) | Document metadata pragmas.      |
+| [`id` / `title` / `description` / `scope` / `sealed` `"…"`](#pragmas) | Metadata and nature pragmas. |
 
 ### Productions
 
 `name = expression` binds a name to an expression — a denotation (a set of names), a
-branch, or a whole subtree. Productions exist to be referenced (`<name>`) from other
-productions or the root; an unreferenced production builds nothing on its own. A
-production may not expand through itself — a reference cycle is a build error.
+branch, or a whole subtree. A production is referenced as `<name>` locally and, when
+public, as `<@module/name>` by importers. Like JavaScript's exports: a plain
+declaration is a named export — it emits into the artifact's `$defs` as a PATTERN —
+while `:name = …` declares it **private**: usable locally, inlined wherever it
+appears, refused to importers, absent from the artifact. A production may not expand
+through itself — a reference cycle is a build error.
 
 ### `root`
 
@@ -71,23 +78,31 @@ forms, import accessors, and collision handling are [modules](./modules.md).
 
 A pragma is an identifier followed by a string, each usable at most once per module:
 
-| Pragma        | Value                        | Lands in the built schema as              |
+| Pragma        | Value                        | Meaning                                   |
 | ------------- | ---------------------------- | ----------------------------------------- |
-| `id`          | any string (usually a URI)   | `$id`                                     |
+| `id`          | any string (usually a URI)   | `$id` (wins over the configured [`schemaId`](./build.md#configuration) derivation) |
 | `title`       | any string                   | `title`                                   |
 | `description` | any string                   | `description`                             |
-| `scope`       | `"document"` \| `"branch"`   | whether the document root is sealed       |
-
-`scope` is the one with semantics, and exactly two values:
-
-| Value        | Meaning                                                                                       |
-| ------------ | ---------------------------------------------------------------------------------------------- |
-| `"document"` | Default. The schema **seals** the document root: nothing beyond the granted names may exist.   |
-| `"branch"`   | The schema governs only the top-level branches it names — the root stays **unsealed**, so sibling vocabularies (a colour module, a spacing module) can each bind over the same token files without rejecting each other's branches. |
-
-A single whole-vocabulary schema wants the default; per-aspect schemas that co-validate
-one collection want `"branch"`. The exact effect on the emitted JSON is
-[emission](./emission.md#scope).
+| `scope`       | `"document"` \| `"def"` \| `"inline"` | The file's NATURE — how it emits and how consumers reference it. |
+| `sealed`      | `"true"` (default) \| `"false"` | Whether the document top is sealed.    |
+
+`scope` — the file's nature:
+
+| Value        | Emitted? | root | Consumers reference                                    |
+| ------------ | -------- | ---- | ------------------------------------------------------- |
+| `"document"` | own file | **required** | its top-level names (`…#/properties/<name>`)     |
+| `"def"`      | own file | optional — also lands as `$defs.root` | the root as the **file itself** (`{ "$ref": "./color.json" }`); productions as `…#/$defs/<name>` |
+| `"inline"`   | never    | optional | expansion only — `:private` at file level          |
+
+Absent, the nature defaults from the root: root → `document`, rootless → `def`.
+
+`sealed` defaults by nature: a `document` seals (`"true"` — it validates alone), a
+`def` file does not (`"false"` — pattern-natured, so consumers can whole-file-compose
+it beside siblings); either can override. `sealed "false"` on a document lets
+per-aspect vocabularies bind over the same token files without rejecting each other's
+branches. (The historical `scope "branch"` still parses as an alias, with a lint
+deprecation warning.)
+The exact effect on the emitted JSON is [emission](./emission.md).
 
 ## Editor support
 

package/docs/lint.md

@@ -4,14 +4,17 @@ Validate the `.dfn` sources themselves — fragments included, every production
 without building anything.
 
 ```bash
-# vertekum schema lint [module] [--json] [--cwd <dir>]
+# vertekum schema lint [module|directory] [--fix] [--json] [--cwd <dir>]
 vertekum schema lint                        # every module under ./schemas
 vertekum schema lint schemas/color.dfn      # one module — fragment or rooted
+vertekum schema lint src/dfn                # sweep any directory
+vertekum schema lint --fix                  # repair what is mechanical first
 ```
 
 | Argument / flag | What it does                                                                 |
 | --------------- | ----------------------------------------------------------------------------- |
-| `[module]`      | A `.dfn` file, relative to the working directory. Default: every module under `./schemas`, recursively — **fragments included**. |
+| `[module]`      | A `.dfn` file **or directory** (swept recursively), relative to the working directory. Default: every module under the configured [`source`](./build.md#configuration) — **fragments included**. |
+| `--fix`         | Apply mechanical repairs before linting (below).                               |
 | `--json`        | Machine-readable result.                                                       |
 | `--cwd <dir>`   | Project discovery starts here.                                                 |
 
@@ -40,6 +43,24 @@ Lint's contract is the source:
 Findings **collect**: one broken production does not hide the next, so a module with
 three mistakes is one lint run, not three.
 
+Lint also reports **warnings** — non-failing (exit `0` when nothing else is wrong):
+an open set merging with closed siblings at one position (the whole position becomes
+open — restructure or accept it), and deprecated forms such as `scope "branch"`
+(write `sealed "false"`).
+
+## `--fix`
+
+`--fix` applies the repairs that are **mechanical and unambiguous** — currently one:
+a trailing open-set mark relocates into the reference or group it opens (`<roles>*`
+→ `<roles*>`, `[a | b]*` → `[a | b *]`), printed through the
+[formatter](./format.md)'s emitter so the repaired line comes out canonical. Repairs
+that would guess intent are never applied — the bare `*` (`color.*`) stays a hinted
+diagnostic, because *which* set to open is yours to say.
+
+The fixed content is validated in memory before anything is written, and the runner
+persists it (`--dry-run` previews). Exit `0` when fixes clear everything; unfixable
+findings still exit `1`, listed after the applied fixes.
+
 ## Sound vs. current
 
 `lint` and [`build --check`](./build.md#--check-the-staleness-gate) answer different

package/docs/modules.md

@@ -45,19 +45,22 @@ use "./system/color.dfn" as system-color
 When two imports both declare `<accent>`, the unqualified `<@accent>` refuses with the
 qualified form to use. Local productions (`<name>`, no `@`) never collide with imports.
 
-## Fragments
+## Fragments and natures
 
 A module without a `root` is a **fragment** — a library of denotations meant to be
-imported, never built:
+imported:
 
 ```dfn
 # denotations/emphasis.dfn
 emphasis = subtle | bold
 ```
 
-The build sweep skips fragments with a notice (`… declares no root (a fragment) —
-skipped`); naming one explicitly as the build argument is an error, so a module whose
-`root` was mistyped cannot be silently skipped.
+By default a fragment still EMITS — a defs-only artifact (`$defs.emphasis`), its
+public productions addressable by consumers. A file that should never emit says so:
+[`scope "inline"`](./language.md#pragmas) — the sweep skips it with a notice, and
+naming it explicitly as the build argument is an error. Private productions
+(`:name = …`) are invisible to importers in every nature — a qualified reference to
+one is refused, naming the module's public productions.
 
 ## Aggregate roots