Difusión Demos Are Demonstration-Scenarios Projected From the Modes, Not a New Kind or Hand-Authored Prose
Proposed
Context
A difusión proposal asked for concrete "con y sin ontoref" demos — each facing a real problem and showing a way to manage it — published across four surfaces: mdBook (docs/), code examples, presentation examples, and web pages with asciinema. Two naive shapes were on the table and both are wrong for this project.
The first naive shape is a NEW typed kind (a `CaseStudy` projecting a `Proof`): extra schema, a migration, and a second seam duplicating what the positioning Proof already binds. The second naive shape is hand-authored prose case studies anchored to ids by hand: marketing copy that drifts from the claims it sells and cannot be run or verified.
The interview that produced ADR-057 already established the discipline that defeats both: the worldview is transmitted by encounter with a runnable artifact, not by argument. And ontoref already ships the machinery. The `generate-examples` mode encodes the axiom "the modes ARE the examples" — an example is a runnable, verifiable artifact, not a static directory. The `Scenario` schema (reflection/schemas/scenario.ncl) already models exactly a demo: `description` (the problem — "without ontoref"), `run` (the way to manage it — "with ontoref"), `validates` (the proof), under `purpose = 'Demonstration`. The `generate-mdbook` mode and the generator (reflection/modules/generator.nu) already extract scenarios and compose them into the doc-data. The asciinema pattern is already proven in outreach/study-group-ontoref/demo/recording/record.sh.
The gap was never a missing abstraction; it was that nothing authored the demos as scenarios and nothing projected them to the difusión surfaces.
Decision
A difusión demo IS a `Scenario` with `purpose = 'Demonstration`, authored once under .ontoref/reflection/scenarios/<demo>/ and PROJECTED to every surface by the generator. No new typed kind, no per-surface hand-authored copy. Concretely:
Demo = Demonstration-scenario — the problem the visitor faces is the scenario's `description` (the "sin ontoref" frame), the way to manage it is `run` (the "con ontoref" verifiable command), and what it proves is `validates`. This reuses the Proof seam of positioning as an honesty anchor (each demo maps to a Validated Proof) without duplicating it as a new kind.
Project, don't duplicate — one Scenario source feeds five outputs. mdBook is rendered by `docs generate --fmt mdbook` (a Demos chapter: problem → management → proof). The other four surfaces — the example repo README, the Slidev section, the asciinema web page, and the Rustelo site page — are materialised by a dedicated `docs demos project --surface <s>` command. A demo edited in one place regenerates everywhere; no copy maintained per surface.
Runnable, not staged — the demo is executable and its `.cast` is recorded from REAL execution against the `onref` branch of the example repo (the generate-examples mode runs the scenario and records the cast). A demo is not a staged screenshot; the example's `onref` side carries a minimal real `.ontoref/` so the query actually answers.
Honest hook, not a recipe — the demo hooks by the PROBLEM (`description`) and the question the "without" world cannot answer, never by a deterministic A→B recipe. The cast shows the real query with its limit (sufficient, not complete); the repulsion of the recipe-seeker is the qualifier (reach-vs-qualification), not funnel leakage.
Constraints
- Hard A difusión demo MUST be authored as a Scenario (reflection/scenarios/<demo>/scenario.ncl) with purpose 'Demonstration — its description the problem, its run the management, its validates the proof — NOT as a new typed kind or standalone prose.
- Hard The difusión surfaces (mdBook, example README, slides, web, site) MUST be projected by the generator from the single Scenario source, never hand-maintained per surface. A demo edit MUST regenerate every surface, not be copied.
- Soft A demo's run MUST be executable and its .cast recorded from real execution against the onref branch (whose minimal .ontoref/ makes describe answer). A demo MUST NOT be a staged screenshot or a non-reproducible capture.
- Soft Demo copy MUST hook by the problem (the question the 'without' world cannot answer) and MUST NOT promise a deterministic recipe. The cast MUST show the real query with its limit (sufficient, not complete).
Alternatives considered
- A new typed `CaseStudy` kind that projects a positioning `Proof` — rejected: Scenario with purpose 'Demonstration already models problema/gestión/prueba; a CaseStudy kind adds schema, a migration, and a second seam duplicating the Proof it would reference. The Proof is reused as an honesty anchor instead, with no new kind.
- Hand-authored prose case studies anchored to audience/value-prop ids by hand — rejected: Free prose drifts from the claims it sells, is not runnable, and is not verifiable — reintroducing the static, unverifiable examples that generate-examples exists to abolish ('the modes ARE the examples').
- A static before/after code diff (same project, with and without the .ontoref/ files) — rejected: A static diff sells a deterministic recipe (reach-vs-qualification) and shows ontoref's cost while hiding its benefit, which only appears at the moment of consequence. The demo's climax must be the runnable query the 'without' world cannot answer, recorded and named as sufficient-not-complete.
Anti-patterns
- Selling ontoref With a Static Before/After Code Diff — A demo is built as a static with/without code diff of the same project. It promises a deterministic recipe (reach-vs-qualification) and shows ontoref's cost — the extra .ncl files, the friction — while hiding its benefit, which only appears at the moment of consequence. It reads as ceremony.
- Inventing a Typed Kind for What Scenario Already Models — A contributor adds a CaseStudy (or similar) typed kind to model difusión demos, adding schema and a migration, when Scenario with purpose 'Demonstration already carries description/run/validates. The new kind duplicates the positioning Proof it would reference.
- Hand-Authoring the Same Demo Once Per Surface — The same demo is written separately for mdBook, the example README, the slides, the web page and the site. The five copies drift from each other and from the scenario — the per-surface drift projection exists to abolish.