feat(dogfood): add block-authored surface contracts

docs/BEARING.md

@@ -15,6 +15,8 @@ Current direction and active tensions. Historical ship data is in `CHANGELOG.md`
   command-intent, lifecycle, active-binding, first-party definition, DOGFOOD
   documentation, and fixture-demo proof. The visible product layer is still
   emerging; the architecture is ahead of the rendered catalog.
+- `LX-019` — DOGFOOD text lookup now goes through an application-facing
+  localization port instead of view code reaching for the concrete runtime.
 - `4.4.1` — framed-shell polish and background-fill recovery after `4.4.0`.
 - `4.2.0` — [RE-007](./design/RE-007-migrate-framed-shell-onto-runtime-engine-seams.md)
   lands the framed shell on the runtime-engine seams and ships
@@ -43,18 +45,19 @@ Current direction and active tensions. Historical ship data is in `CHANGELOG.md`
 - New Block work should consume the existing contracts, not invent provider,
   lifecycle, callback, or localization policy while rendering.
 
-### 3. Localization Port Before More View-Level Lookup
+### 3. DOGFOOD Becomes Block-Authored
 
-- English fallback is separate from selected-locale catalogs.
-- Missing selected-locale strings are now real missing data, not disguised
-  English.
-- DOGFOOD now needs an app-facing localization port so views ask for localized
-  objects instead of depending directly on the concrete i18n runtime.
+- DOGFOOD should prove Bijou's Block system by using Blocks for semantic app
+  surfaces, not merely previewing Blocks in one section.
+- Components remain the leaf rendering vocabulary inside Blocks.
+- Storybook should move onto the shared framed shell path and expose a
+  `StorybookWorkbenchBlock` contract instead of staying a parallel bespoke TUI.
 
 ## Tensions
 
-- **View-Level Runtime Leakage**: DOGFOOD still passes the concrete i18n
-  runtime through rendering helpers for ordinary text lookup.
+- **Block Boundary Drift**: It is tempting to wrap every component in a Block.
+  That would blur the useful boundary; Blocks should own product semantics,
+  while components own leaf rendering.
 - **Product Proof Lag**: Blocks have better contracts than visible rendered
   proof. AppShell rendering must consume existing data-flow contracts instead of
   creating a parallel prop/callback path.
@@ -67,26 +70,27 @@ Current direction and active tensions. Historical ship data is in `CHANGELOG.md`
 ## Next Target
 
 The immediate focus is
-[LX-019 — Localization Port Contract](./design/LX-019-localization-port-contract.md).
+[DF-069 — Block-Authored DOGFOOD](./design/DF-069-block-authored-dogfood.md).
 
-LX-019 should stay boundary-focused:
+DF-069 should stay product-composition focused:
 
-- define the application-facing `LocalizationPort` in `@flyingrobots/bijou-i18n`
-- return structured localized objects instead of naked strings
-- keep catalog/file loading in adapters
-- keep DOGFOOD runtime composition at the app boundary
-- migrate DOGFOOD text helpers to the port
+- move Storybook toward the framed shell path
+- introduce DOGFOOD Blocks for semantic app/page surfaces
+- keep low-level components as rendering primitives inside Blocks
+- preserve unidirectional data-binding and localization-port boundaries
 
 Non-goals for the next cycle:
 
-- no localization dashboard
-- no translation workbench
-- no portable preference system
-- no broad catalog expansion
-- no remote localization service
+- no full visual redesign of DOGFOOD
+- no conversion of every leaf component into a Block
+- no hidden global block registry
+- no new provider lifecycle system
+- no localization runtime rewrite
 
 Expected sequence:
 
-1. `LX-019` puts application-facing localization lookup behind a port.
-2. Remaining DOGFOOD text surfaces continue moving into catalogs.
-3. Blocks product proof resumes with less view-level localization leakage.
+1. `DF-069` makes the next DOGFOOD proof block-authored at semantic boundaries.
+2. Storybook moves onto the same framed-shell model.
+3. DOGFOOD pages migrate to Blocks incrementally, starting with title,
+   navigation, documentation article, settings, block preview, and inspector
+   surfaces.

docs/CHANGELOG.md

@@ -8,6 +8,14 @@ All packages (`@flyingrobots/bijou`, `@flyingrobots/bijou-node`, `@flyingrobots/
 
 ### ✨ Features
 
+- **Block-authored DOGFOOD surface contracts** — DOGFOOD now has a local,
+  branded block registry for semantic product surfaces and publishes block
+  contracts for the title screen, navigation list, documentation article, block
+  preview, guide inspector, settings menu, and Storybook workbench. The
+  interactive Storybook entrypoint now runs through the AppFrame shell instead
+  of a parallel bespoke TUI, while registry discovery remains render-free and
+  does not introduce provider handles, subscriptions, command dispatch, or a
+  hidden global block registry.
 - **Localization port contract for `bijou-i18n`** —
   `@flyingrobots/bijou-i18n` now exports `LocalizationPort`,
   `LocalizationRequest`, `LocalizedObject`, localization status/issue/fact
@@ -52,8 +60,11 @@ All packages (`@flyingrobots/bijou`, `@flyingrobots/bijou-node`, `@flyingrobots/
   across `docs-app`, `dogfood-locale`, `component-stories`, and Storybook-style
   DOGFOOD entrypoints. The scanner filters ids, file paths, import paths, and
   catalog-backed fallback calls so review sees the remaining localization debt
-  without scraping terminal render output. `release:readiness` now runs the
-  i18n debt ratchet alongside the existing DOGFOOD coverage gate.
+  without scraping terminal render output. It also filters machine-only key
+  names, event discriminants, mode literals, pane policy tokens, tone tokens,
+  and internal thrown-error strings so framed Storybook protocol data does not
+  inflate visible-copy debt. `release:readiness` now runs the i18n debt ratchet
+  alongside the existing DOGFOOD coverage gate.
 - **DOGFOOD locale preference and i18n ratchet** — DOGFOOD now resolves its
   initial language through an explicit locale port with a Node adapter that
   reads operating-system locale signals, exposes a Settings drawer language

docs/design/DF-069-block-authored-dogfood.md

@@ -0,0 +1,149 @@
+# DF-069 - Block-Authored DOGFOOD
+
+Linked legend: [DF - DOGFOOD Field Guide](../legends/DF-dogfood-field-guide.md)
+
+## Sponsor human
+
+DOGFOOD should prove that Bijou applications can be authored from Blocks, not
+only that Blocks can be previewed inside DOGFOOD.
+
+## Sponsor agent
+
+An agent should be able to inspect DOGFOOD and identify the semantic blocks
+that make up the product surface without reverse-engineering bespoke render
+helpers.
+
+## Hill
+
+DOGFOOD becomes a block-authored application at the semantic surface boundary:
+title screen, shell regions, navigation, articles, settings, story previews,
+block previews, and inspector panes are declared as Blocks. Components remain
+the lower-level rendering vocabulary inside those Blocks.
+
+## Core Rule
+
+Blocks own product semantics. Components own leaf rendering.
+
+That means this work should create and consume Blocks for surfaces such as:
+
+- `TitleScreenBlock`
+- `NavigationListBlock`
+- `DocumentationArticleBlock`
+- `SettingsMenuBlock`
+- `StorybookWorkbenchBlock`
+- `BlockPreviewBlock`
+- `GuideInspectorBlock`
+
+It should not wrap every `boxSurface()`, `markdown()`, or list row in a Block.
+
+## Architecture
+
+The target composition is:
+
+```text
+DOGFOOD app
+  -> AppFrame / AppShell composition
+    -> page and region Blocks
+      -> components
+        -> surfaces
+```
+
+The existing unidirectional data-binding rule still applies:
+
+```text
+business logic / providers
+  -> immutable snapshots
+  -> binding frames
+  -> blocks and views render
+  -> command intents
+  -> business logic owns the next state
+```
+
+Block-authored DOGFOOD must not introduce hidden provider registries, callback
+backchannels, render-time refresh hooks, mutable view stores, or direct provider
+reads from rendering code.
+
+## Storybook Implication
+
+The standalone Storybook app should stop being a parallel bespoke TUI. It
+should use the same framed shell path as DOGFOOD and expose a
+`StorybookWorkbenchBlock` contract so story preview work exercises the product
+composition model.
+
+## Non-goals
+
+- no full visual redesign of DOGFOOD
+- no attempt to convert every low-level component into a Block
+- no new provider lifecycle system
+- no new localization runtime
+- no hidden global block registry
+- no rendered AppShell policy invented outside existing contracts
+
+## Accessibility / Assistive Posture
+
+Block-authored DOGFOOD should make semantic regions easier to lower across
+interactive, static, pipe, and accessible modes. Blocks should preserve facts
+about navigation, content, settings, previews, and inspector state without
+requiring agents or assistive modes to parse terminal art.
+
+## Localization / Directionality Posture
+
+Blocks should receive localized labels and copy through DOGFOOD's localization
+port, not through direct catalog access. Block metadata may describe the
+surface, but runtime-visible labels remain localized app data.
+
+## Agent Inspectability / Explainability Posture
+
+Agents should be able to ask which DOGFOOD Blocks are active, what data
+requirements they declare, which command intents they expose, and which surface
+they render into.
+
+## Linked Invariants
+
+- [Docs Are the Demo](../invariants/docs-are-the-demo.md)
+- [Runtime Truth Wins](../invariants/runtime-truth-wins.md)
+- [Commands Change State, Effects Do Not](../invariants/commands-change-state-effects-do-not.md)
+- [Tests Are the Spec](../invariants/tests-are-the-spec.md)
+
+## Implementation Outline
+
+1. Update BEARING so the next product gravity is block-authored DOGFOOD.
+2. Add DOGFOOD-local block registry helpers for semantic app surfaces.
+3. Add `StorybookWorkbenchBlock` and move Storybook toward the framed shell.
+4. Add DOGFOOD Blocks for title, navigation, documentation article, settings,
+   block preview, and guide inspector surfaces.
+5. Prove the block-authored registry without rendering every block during
+   discovery.
+6. Keep visual changes incremental and scoped.
+
+## Tests To Write First
+
+- behavior tests proving the Storybook app is framed rather than bespoke
+- behavior tests proving DOGFOOD block registry discovery does not call render
+- behavior tests proving core DOGFOOD surfaces have Block definitions
+- behavior tests proving localization and command intent boundaries stay
+  declarative
+
+## Playback
+
+DF-069A lands the block-authored DOGFOOD contract layer:
+
+- DOGFOOD has a local, branded `DogfoodBlockRegistry`.
+- Registry discovery rejects loose block-shaped objects.
+- Registry discovery records surface ownership without calling `render()`.
+- Storybook now has a `StorybookWorkbenchBlock` contract and the interactive
+  Storybook entrypoint uses the AppFrame shell.
+- DOGFOOD surface blocks now cover title, navigation, documentation article,
+  block preview, guide inspector, settings, and Storybook workbench surfaces.
+
+## Retrospective
+
+This slice deliberately stops at semantic surface contracts and the Storybook
+frame migration. It does not rewrite every DOGFOOD renderer yet, does not move
+provider lifecycle policy, and does not convert leaf components into Blocks.
+
+The final review gate also tightened the DOGFOOD i18n debt scanner so framed
+Storybook machine tokens such as key names, event discriminants, mode literals,
+pane overflow policy, tones, and internal thrown errors do not count as visible
+English copy. Storybook labels and rendered text still count as localization
+debt until they move behind a localization port.

docs/legends/DF-dogfood-field-guide.md

@@ -76,6 +76,7 @@ before DOGFOOD counts as a real terminal docs product, and can see that
 - latest DOGFOOD docs-surface closure:
   - [DF-025 — Make DOGFOOD The Only Human-Facing Docs Surface](../design/DF-025-make-dogfood-the-only-human-facing-docs-surface.md)
 - latest supporting closure:
+  - [DF-069 — Block-Authored DOGFOOD](../design/DF-069-block-authored-dogfood.md)
   - [DF-067 — Prove Responsive DOGFOOD Layout Variants](../design/DF-067-prove-responsive-dogfood-layout-variants.md)
   - [DF-027 — Storybook-Style Tool for Bijou](../design/DF-027-storybook-style-tool-for-bijou.md)
   - [DF-062 — Audit Notification System Family Across Real Surfaces](../design/DF-062-audit-notification-system-family-across-real-surfaces.md)