mythik 0.1.5 → 0.2.1

package/docs/consumer/reference-doc.md

@@ -35,17 +35,28 @@ mythik manifest <screen>
 mythik elements <screen> <id1,id2,...>
 
 # Apply RFC 6902 patches
-mythik patch <screen> --from-file patch.json
+mythik patch <screen> --from-file patch.json --author <agent>
 
 # Export a full screen spec for backup/review
 mythik pull <screen>
 
-# Create or intentionally replace a full screen spec from stdin
-mythik push <screen>
+# Create a new screen spec or intentionally replace a full screen spec
+mythik push <screen> --from-file spec.json --author <agent>
+mythik push <screen> --from-file spec.json --replace --author <agent>
 
 # Validate a screen spec
 mythik validate <screen>
 
+# Start and query live runtime context for AI agents
+mythik reveal start
+mythik reveal apps --json
+mythik reveal context --app <name>
+mythik reveal element <element-id> --app <name>
+
+# Install and refresh project-local AI operating context
+mythik agent init codex|claude|all
+mythik agent context --app <app-id> --include-screens --out .mythik/agent/context.md
+
 # Delete a screen (preview without --confirm)
 mythik delete <screen> --confirm
 ```
@@ -73,13 +84,13 @@ Set the env var once per session: `export MYTHIK_API_KEY="your-key"`. The CLI re
 
 **Preferred shell-safe path** - write patch JSON to a file:
 ```bash
-mythik patch task-manager --from-file patch.json
+mythik patch task-manager --from-file patch.json --author <agent>
 ```
 
 `--from-file <path>` wins over ambient non-TTY stdin. Use `--from-file -` or pipe without `--from-file` when stdin is intentional:
 ```bash
-cat patch.json | mythik patch task-manager
-mythik patch task-manager --from-file -
+cat patch.json | mythik patch task-manager --author <agent>
+mythik patch task-manager --from-file - --author <agent>
 ```
 
 Inline JSON still works for tiny patches, but `--from-file` is preferred for anything containing `$state`, `$template`, `$auth`, or shell-sensitive quoting.
@@ -92,7 +103,7 @@ Use `--toon` for token-efficient output on `elements` and `patch` commands:
 
 ```bash
 mythik elements task-manager btn,nav --toon
-mythik patch task-manager --from-file patch.toon --toon
+mythik patch task-manager --from-file patch.toon --toon --author <agent>
 ```
 
 TOON reduces output by ~40% vs JSON. Lossless roundtrip. Based on `@toon-format/toon` v2.
@@ -101,32 +112,140 @@ TOON reduces output by ~40% vs JSON. Lossless roundtrip. Based on `@toon-format/
 
 ```bash
 # JSON input (as before)
-mythik patch task-manager --from-file patch.json
+mythik patch task-manager --from-file patch.json --author <agent>
 
 # TOON input (autodetected)
-mythik patch task-manager --from-file patch.toon
+mythik patch task-manager --from-file patch.toon --author <agent>
 ```
 
 ### Workflow: Manifest → Elements → Patch
 
 1. **`mythik manifest <screen>`** — see the structure, decide what to modify
 2. **`mythik elements <screen> <ids>`** — inspect specific elements you need to change
-3. **`mythik patch <screen> --from-file patch.json`** - apply surgical changes
-4. **`mythik manifest <screen>`** — verify the result
+3. **`mythik patch <screen> --from-file patch.json --author <agent>`** - apply a surgical, versioned change
+4. **`mythik validate <screen>`** — validate the stored result
+5. **`mythik manifest <screen>`** — verify the changed structure
 
 This is the required default loop for AI agents editing an existing spec. Do not begin a small change by pulling the full spec and rewriting it. `manifest` gives the structural map, `elements` gives the exact JSON for the target nodes, and `patch --from-file` keeps the write validated, versionable, and reviewable. Use `pull` for backup/migration/review and `push` for new specs or deliberate full replacement only.
 
+### Mythik Sentinel - Agent Protocol Guardrail
+
+Mythik Sentinel is built into the CLI so a fresh AI agent is not left
+alone with generic command habits. It is advisory and best-effort: it
+does not change the real command exit code, and it never stores specs,
+patches, URLs, credentials, state values, or Reveal context.
+
+Sentinel watches command intent per project. On first CLI use, it asks
+the agent to run `mythik agent init codex|claude|all`. If it sees
+repeated full replacement intent (`push --replace` or
+`push --from-dir --replace`) with little/no `patch` usage, it warns the
+agent back to `manifest -> elements -> patch --from-file --author ->
+validate -> verify`.
+
+Machine-readable output stays machine-readable. JSON object outputs may
+receive `protocol.warnings`. TOON output and other machine formats are
+not wrapped with human text. Use `MYTHIK_SENTINEL=off` only for
+exceptional automation that needs to suppress advisory warnings.
+
+`push --replace` also has no-diff protection. If the submitted document
+is identical to the stored document, Mythik skips the write instead of
+creating a new version. JSON output reports `skipped: true` and
+`skipReason: "no-diff"`.
+
+### Mythik Reveal — Live Runtime Context for AI Agents
+
+`mythik reveal` lets a running Mythik app expose its live contract,
+state, actions, diagnostics, and environment as structured context for
+AI agents. It complements the spec-edit loop:
+
+- `manifest` and `elements` read stored specs.
+- `lint` and `validate` check candidate specs before runtime.
+- `reveal` reads the app that is actually running.
+
+Use Reveal when the symptom is runtime behavior: a button does not
+fire, a dataSource does not load, a screen renders the wrong branch, a
+native app behaves differently from web, or a render error appears.
+Do not guess from source files first when a Reveal-enabled app can
+answer with live context.
+
+Start the local bridge:
+
+```bash
+mythik reveal start --port 17373
+```
+
+The command prints:
+
+```text
+MYTHIK_REVEAL_URL=http://127.0.0.1:17373
+MYTHIK_REVEAL_TOKEN=<generated-token>
+```
+
+Pass those values into the host runtime in development:
+
+```tsx
+const reveal = React.useMemo(() => ({
+  enabled: import.meta.env.DEV,
+  appName: 'my-app',
+  bridgeUrl: import.meta.env.VITE_MYTHIK_REVEAL_URL,
+  token: import.meta.env.VITE_MYTHIK_REVEAL_TOKEN,
+  environment: { id: 'dev', source: 'host' as const },
+  includeStatePaths: ['/ui', '/form'],
+  redactStatePaths: ['/auth', '/secrets'],
+}), []);
+
+<MythikApp appSpec={appSpec} specStore={specStore} reveal={reveal} />
+```
+
+Then query the connected app:
+
+```bash
+mythik reveal apps --json
+mythik reveal context --app my-app
+mythik reveal current --app my-app
+mythik reveal screen dashboard --app my-app
+mythik reveal element save-button --app my-app
+```
+
+Reveal context includes:
+
+- runtime renderer (`react`, `react-native`, `server`, or `unknown`)
+- app name, platform, and environment metadata
+- spec summary and optional screen/element summary
+- resolved public props for inspected elements
+- dependency paths for inspected elements
+- included state paths and omitted paths
+- render errors and warnings
+- action, transaction, dataSource, navigation, lifecycle, and render
+  error events
+- patch target metadata when the host can identify a versioned spec
+- redaction and truncation metadata
+
+Security rules:
+
+- Reveal is development tooling. Do not enable it in production.
+- The bridge is local and token-protected. Never commit or publish the
+  token.
+- Use narrow `includeStatePaths`; do not expose the whole store by
+  default.
+- Redact `/auth`, `/secrets`, tokens, passwords, API keys, and session
+  values.
+- React and React Native hosts should memoize the `reveal` config
+  object so the bridge client is stable across renders.
+- For Android emulator testing, use `adb reverse tcp:17373 tcp:17373`
+  before querying the host bridge from the native app.
+
 ### Full Spec Lifecycle
 
 ```bash
-Create:    mythik push <id> < spec.json
+Create:    mythik push <id> --from-file spec.json --author <agent>
 Read:      mythik manifest <id> / mythik elements <id> ids / mythik pull <id>
-Modify:    mythik patch <id> --from-file patch.json
+Modify:    mythik patch <id> --from-file patch.json --author <agent>
 Validate:  mythik validate <id>
 Delete:    mythik delete <id> --confirm
 Backup:    mythik pull <id> > backup.json
-Restore:   mythik push <id> < backup.json
-Migrate:   mythik pull <id> --store A | mythik push <id> --store B
+Restore:   mythik push <id> --from-file backup.json --replace --author <agent>
+Migrate:   mythik push <id> --from-file exported.json --author <agent> --store B
 Tokens:    mythik tokens --dna '{"primary":"#0D9488"}' --json
 ```
 
@@ -245,7 +364,7 @@ Every screen is a JSON Spec with a `root` ID, a flat `elements` map, and optiona
 | `style` | object | CSS styles (can contain expressions) |
 | `visible` | boolean or condition | Show/hide condition |
 | `permission` | object | Role-based access: `{ visible, editable, readonly }` |
-| `repeat` | object | Iterate over array: `{ statePath, key }` or `{ source: expression, key }` |
+| `repeat` | object | Iterate over array: `{ statePath, key }` or `{ source: expression, key }`; optional `layout` controls item row direction/gap/wrap |
 | `on` | object | Event handlers: `{ press: action, change: action }` |
 | `hover` | object | Style overrides when pointer enters (rendered via Motion) |
 | `active` | object | Style overrides when element is pressed (rendered via Motion) |
@@ -585,7 +704,7 @@ Each primitive accepts `style` (CSS object), `visible` (condition), and `permiss
 
 ### Icon Primitive
 
-The `icon` primitive renders icons from a connected icon library. By default it's a placeholder — apps connect a library via `plugins.overridePrimitive('icon', ...)`.
+The `icon` primitive renders icons from a connected icon library. By default it's a placeholder — apps connect a library once via `plugins.setIconRenderer(Component)`. Built-in icons, table action icons, toast icons, and React Native icon consumers use that same registration.
 
 ```json
 { "type": "icon", "props": { "name": "pencil-simple", "size": 16, "weight": "bold", "color": "#666" } }
@@ -1227,6 +1346,18 @@ Use `source` for filtered/paginated lists:
 
 Inside repeated elements, use `$item` and `$index` to access the current item's data. These work in `props`, `style`, `visible`, and `on` (event params).
 
+Use `repeat.layout` when the repeated items should render as a horizontal or wrapping row:
+
+```json
+"repeat": {
+  "source": { "$state": "/filters" },
+  "key": "id",
+  "layout": { "direction": "horizontal", "gap": 8, "wrap": true }
+}
+```
+
+Grouped repeats keep group headers/footers vertical and apply `repeat.layout` only to each group's item row.
+
 ### Grouped Repeat (`groupBy`)
 
 Two modes — auto-detected:
@@ -1938,7 +2069,7 @@ Reference tokens or write custom values:
 37. **Device context is auto-tracked** — viewport, platform, orientation, OS color scheme write to `/ui/device/*` automatically. Use `$breakpoint` for responsive values, `$platform` for cross-platform branching, `$state` for orientation detection
 38. **Use `forms` for coordinated validation** — form-level `isValid`, cross-field rules, submit gating. Use inline `checks` on inputs for standalone fields without form coordination
 39. **Use `$auth` for user data, not `$state`** — `{ "$auth": "email" }` is safer (whitelisted fields only) and more stable than `{ "$state": "/auth/user/email" }`. `$auth` blocks access to tokens/passwords even if somehow in state
-40. **Auth headers are auto-injected** — specs don't need to specify auth headers in `fetch`/`submitForm`. The framework injects Bearer tokens automatically for configured `authDomains`
+40. **Auth headers are auto-injected** — specs don't need to specify auth headers in `fetch`/`submitForm`. With `MythikApp apiBaseUrl`, framework-owned relative URLs inherit auth for that exact origin when `authDomains` is omitted or empty. Providing `authDomains` disables that automatic `apiBaseUrl` origin allowlist; list every trusted absolute host explicitly.
 41. **Login screen is a normal spec** — build login forms with regular primitives (input, button). The `login` action connects to the auth provider. No special components needed. Use `$bindState: "/login/username"` and `"/login/password"` for form fields. The `login` action receives `{ email: "$state /login/username", password: "$state /login/password" }`
 42. **Never trust client auth as security** — `AppAuthConfig` is UX routing (hide screens by role), not server-side security. Always validate tokens on the backend
 43. **Use `roleAccess` for centralized access control** — when defined, it's the sole source of truth. Roles not listed get zero access. `ScreenDefinition.roles` is only used when `roleAccess` is absent
@@ -1957,9 +2088,9 @@ Reference tokens or write custom values:
 56. **Auto-skeleton activates when spec has `fetch` in initialActions + loading + empty data** — zero config needed. Set `skeleton: false` on elements that show static content. Set `autoSkeleton={false}` on MythikRenderer to disable entirely
 57. **Use `export` action for data downloads, not custom fetch** — format `"csv"` is always available (built-in). For `"xlsx"` or `"pdf"`, register an ExportAdapter via `exportAdapters` prop on MythikRenderer
 58. **Export columns support formatting** — `format: "currency"` with `formatOptions: { currency: "USD", locale: "en-US", decimals: 2 }`. Same Intl formatters as `$format` expression handler
-59. **Use `variant` prop for consistent component styling** — don't copy style objects between elements. Define variants in `tokens.components.{type}.{variant}` and reference with `"variant": "primary"`
-60. **Element-level style/hover/active overrides variant** — variant is always the base. For one-off customizations, add explicit style/hover on the element. For reusable customizations, define a new variant
-61. **Use `$path` references in variant definitions** — `$colors.primary` resolves against active tokens so dark mode works automatically. No need for separate dark variant definitions unless the dark change isn't just a token swap
+59. **Use `variant` prop for consistent primitive styling** — don't copy style objects between elements. Define variants in `tokens.components.{type}.{variant}` and reference with `props.variant`. Variants are for visual slots (`style`, `hover`, `active`, `focus`, `transition`, `animations`), not arbitrary primitive props.
+60. **Element-level style/hover/active overrides variant** — variant is always the base. For one-off customizations, add explicit style/hover on the element. For reusable customizations, define a new variant. For reusable prop-bearing patterns such as table `headerStyle`/`rowStyle`, `columns`, `onRowClick`, or composed children, use `templates` or Layer 3 custom elements instead of copying props into every table/chip.
+61. **Use `$path` references in variant definitions** — `$colors.primary` resolves against active tokens so dark mode works automatically. Variant definitions do not evaluate render-context expressions such as `$state`, `$item`, or `$prop`; keep state/item-specific active styling on the element or move the composition to a template/custom element.
 62. **AppSpec patches use `/layout/elements/` not `/elements/`** — Screen spec elements are at `/elements/{id}`. AppSpec layout elements are at `/layout/elements/{id}`. Use dot-notation with `mythik elements` for inspecting non-element sections (tokens, screens, etc.)
 63. **AppSpec is filtered without Bearer token** — `GET /api/app/:id` strips `roleAccess` and `protectedScreens` from the response when no valid Bearer token is present. This prevents information disclosure of the authorization model. With a valid Bearer, the full AppSpec is returned. The endpoint never returns 401 — only the payload changes
 64. **CLI warns on unknown prop names** — `mythik push` and `mythik validate` check prop names against known schemas for all 38 primitives. Unknown props generate warnings (not errors) with Levenshtein suggestions: `⚠ unknown prop "inputType" for type "input" — did you mean "type"?`. Warnings don't block saves
@@ -1990,13 +2121,13 @@ Reference tokens or write custom values:
 89. **Lazy bootstrap for existing specs** — first versioned save on an existing spec with no history automatically creates v1 (snapshot of current spec), then saves the change as v2. No migration script needed. Specs without history continue working via base `SpecStore.load()`
 90. **Use `navigateScreen` and `goBackScreen` in specs** — `navigateScreen` and `goBackScreen` are registered by MythikApp and call the AppEngine directly. The built-in `navigate` and `goBack` only set state intents. Always use `navigateScreen`/`goBackScreen` in specs for navigation that works. Example: `{ "action": "goBackScreen" }` goes back to the previous screen in the navigation history, regardless of which screen navigated to the current one
 91. **CLI `--table` flag overrides the current spec table** — all commands accept `--table <name>` to read/write from a different base table. Use `--table api_specs` to operate on api-specs. The flag overrides the base table for Supabase, SQL Server, PostgreSQL, MySQL, and SQLite stores. Version and environment tables are configured separately with `MYTHIK_VERSIONS_TABLE`, `MYTHIK_ENVIRONMENTS_TABLE`, or the equivalent `.mythikrc` SQL settings.
-92. **`push` and `patch` version automatically with `--author`** — when `--author` is provided, both commands use `VersionedSpecStore.saveVersion()` instead of `SpecStore.save()`. The version includes author, source type (`push`/`patch`), and optional `--description`. Without `--author`, commands work as before (no versioning). Example: `mythik patch screen-id --author alice --description "Fixed layout"`
+92. **`push` and `patch` require explicit write intent** — persisted writes should use `--author <name>` so the resolved versioned store records a version through `VersionedSpecStore.saveVersion()`. Existing specs require `--replace` for full replacement. Use `--allow-unversioned` only for intentionally unversioned stores such as file-store smoke tests. The version includes author, source type (`push`/`patch`), and optional `--description`. Example: `mythik patch screen-id --from-file patch.json --author alice --description "Fixed layout"`
 93. **`mythik history` shows inline diffs** — each version in the history output shows the actual changes (before/after values), not just a summary. Uses `computeStructuralDiff` between consecutive versions. Example output: `~ element "btn" prop content: "Send" → "Submit"`
 95. **`ai-context.md` is the AI-optimized spec reference** — compressed from this reference-doc (1145 lines vs 2658). Use ai-context.md for spec generation, reference-doc for full human reference. Validated via agent-based testing with progressive difficulty levels (L1-L4). Test scenarios in `../ai-context-test-scenarios.md`, results in `../ai-context-test-results.md` (framework-dev, not part of consumer publish surface)
 
 94. **Generic SQL versioned stores are available** — `resolveVersionedStore` supports `sqlserver`, `postgres`, `mysql`, and `sqlite` store types. It creates a driver-backed `SqlVersionedSpecStore` (specs + version history) plus `SqlEnvironmentStore` (environment pointers). Requires `screens`, `screen_versions`, and `screen_environments`; initialize with `mythik init-store` or apply the DDL from `mythik init-store --dry-run`.
 96. **SupabaseVersionedSpecStore available** — `resolveVersionedStore` supports `supabase` store type. Uses PostgREST REST API (no `@supabase/supabase-js` dependency). Same snapshot+patches pattern as SqlServer. Environment upsert uses `on_conflict=screen_id,environment` for PostgREST compatibility. Requires `screen_versions` and `screen_environments` tables created in Supabase dashboard
-97. **`variant` is a universal prop** — any primitive can use `variant` when component variants are defined in `tokens.components.{type}.{variant}`. The validator accepts `variant` on all primitives (via `COMMON_PROPS`). The render engine resolves variants before passing props to the primitive
+97. **`variant` is a universal prop** — any primitive can use `variant` when component variants are defined in `tokens.components.{type}.{variant}`. The validator accepts `variant` on all primitives (via `COMMON_PROPS`). The render engine resolves variants before passing props to the primitive. Put `variant` inside `props`, and use variants as the first-line reuse mechanism before duplicating visual style blocks.
 98. **Use DNA seeds for app identity** — define `tokens.dna` in AppSpec with 1-8 seed values. The framework derives all visual tokens (colors via OKLCH tonal palette, shape, typography, spacing, elevation, motion, opacity) plus auto dark mode. No manual color palette or radius scale needed — DNA generates it from `{ "primary": "#0D9488" }`
 99. **Three-layer token resolution** — Framework DEFAULTS (always present) → DNA derivation (if `dna` seed exists) → Manual overrides (explicit `tokens.*` values always win). Specs without tokens use defaults. Specs with only DNA get full derived identity. Specs with DNA + overrides get derived base with surgical customization
 100. **`$token` auto-converts elevation to CSS** — `{ "$token": "elevation.md" }` returns a CSS `boxShadow` string on web (e.g., `"0px 4px 12px rgba(0,0,0,0.15)"`). On RN, primitives handle elevation internally via native shadow props. No manual conversion needed
@@ -2009,7 +2140,7 @@ Reference tokens or write custom values:
 107. **`Element.key` forces remount on value change** — Add `key` to any element with a dynamic expression (e.g., `{ "$template": "preview-${/internal/tokenVersion}" }`). When the resolved value changes, React unmounts and remounts the element, re-triggering mount animations. Used by DNA Playground to re-animate preview on Apply DNA
 108. **Input supports `type: "color"`** — Renders native OS color picker. Use with `$bindState` for interactive color selection in specs
 109. **Slider label is display-only** — The slider primitive renders the `label` prop as-is without appending the current value. Use `$template` in the label to include the value if desired (e.g., `"label": { "$template": "Roundness: ${/dna/roundness}%" }`)
-110. **`--author` activates CLI versioning** — `mythik push` and `mythik patch` without `--author` write directly to the `screens` table with NO version history. With `--author ai-agent`, they use `VersionedSpecStore` which writes to both `screens` AND `screen_versions`, enabling `history`, `diff`, and `rollback` commands. Always use `--author` during development
+110. **`--author` is the normal persisted-write path** — `mythik push` and `mythik patch` with `--author ai-agent` use `VersionedSpecStore` when available, writing to both `screens` and `screen_versions` and enabling `history`, `diff`, and `rollback` commands. Without `--author`, persisted writes are rejected unless `--allow-unversioned` is explicit. Always use `--author` during development.
 111. **Identity System — `tokens.identity` controls visual identity beyond DNA** — DNA controls continuous/color values. Identity controls categorical dimensions: `surface` (how containers render), `radiusPattern` (corner shape), `typographyHierarchy` (heading scale), `labelStyle` (label formatting), `textDecoration` (heading decoration), `depth` (shadow intensity 0-1), `shadowAngle` (shadow direction 0-360°), `colorScheme` (light/dark/colored polarity), `colorWeight` (where color appears), `accentApplication` (where accent appears). Set via `tokens.identity` in AppSpec or screen Spec. Lint validates deep identity enum/range values; for example use `colorScheme: "light-surface"`, not `"light"`
 112. **Surface Treatment — 6 types transform all containers** — `identity.surface`: `elevated` (shadow+border, material), `flat` (color blocks only, no borders/shadows), `outlined` (borders only, transparent bg, Linear-like), `glass` (backdrop-filter blur, semi-transparent), `bold` (thick 2-3px borders, brutalist), `neo` (neumorphic inset+outset shadows). Every input, button, card, modal, select, textarea, checkbox, accordion, table adapts automatically
 113. **Surface styles are explicit — every property set, no implicit values** — All 6 surface types define `border` and `boxShadow` explicitly for every component category. Properties are `'none'` when not used, never omitted. This prevents browser defaults from showing (e.g., native button borders in flat mode)
@@ -2052,7 +2183,7 @@ Reference tokens or write custom values:
 150. **Gradient interpolation in OKLCH** — All gradient text and gradient buttons use `linear-gradient(in oklch, ...)` for vibrant transitions. sRGB interpolation crosses through desaturated midpoints (purple→gold becomes muddy brown); OKLCH maintains saturation through the hue arc. Graceful degradation on older browsers
 151. **Gradient modes: vibrant, soft, muted** — `identity.gradients.text`, `identity.gradients.buttons`, and `identity.gradients.cards` accept `boolean | 'vibrant' | 'soft' | 'muted'`. For text and buttons: Vibrant = OKLCH primary→accent. Soft = OKLCH primaryLight→accentLight (subtle). Muted = sRGB primary→accent (desaturated center, luxury/editorial aesthetic). For cards: Vibrant = 33% primary alpha (dramatic). Muted = 20% primary alpha (balanced default). Soft = 8% primary alpha (subtle kiss). `true` maps to vibrant for text/buttons, muted for cards
 152. **Explicit accent hex preserved as-is** — When `dna.accent` is set explicitly, `deriveDna` uses the exact hex for `colors.accent` instead of passing through `generateTonalPalette` step 60. The palette is still generated (for `accentLight`), but the primary accent color is the user's exact choice
-153. **`setIconRenderer` replaces `overridePrimitive` for icons** — `plugins.setIconRenderer(Component)` registers a custom icon renderer. The framework's `icon.tsx` handles identity wrapping (container, weight default) while the registered component renders the actual icon. `overridePrimitive('icon', ...)` still works but bypasses identity features
+153. **`setIconRenderer` replaces `overridePrimitive` for icons** — `plugins.setIconRenderer(Component)` registers a custom icon renderer. The framework's `icon.tsx` handles identity wrapping (container, weight default) while the registered component renders the actual icon. Table action icons, toast icons, and React Native icon consumers use the same registration. `overridePrimitive('icon', ...)` still works for full primitive replacement but bypasses identity features
 154. **Do not emit Box `backgroundBlobs`** — Box `backgroundBlobs` and legacy per-element blob rendering are not part of the public primitive contract. App-level background lives exclusively at `tokens.identity.background` (rule 147) and mounts at MythikRenderer via `<BackgroundStack>`. Box is a pure surface-styled wrapper; primitives do not rely on `dangerouslySetInnerHTML` for keyframe injection.
 155. **Do not emit `$token: "backgroundCSS"`** — `$token: "backgroundCSS"` does not resolve. For preset-aware app backgrounds, set `tokens.identity.background` as a LayerBackground (rule 147) — presets update that field directly so the root `<BackgroundStack>` re-resolves on preset switch. No token alias indirection needed.
 156. **Accordion `badge` prop** — `accordion` accepts optional `badge` prop (`string | number | boolean`). Renders as: solid 8px primary-colored dot for `true`, pill with text/number for string/number values. Hidden when `false`, `0`, `undefined`, or `''`. Use with `$state` for reactive indicators: `"badge": { "$state": "/modified/mySection" }`
@@ -2097,7 +2228,7 @@ Reference tokens or write custom values:
 }
 ```
 
-**`authDomains` matcher behavior:** the matcher compares the URL's hostname only — the port is stripped. `"myproject.supabase.co"` matches requests to that hostname on any port. In dev, use `["localhost"]` (NOT `["localhost:5173"]`) — the port in the entry never matches because URL hostnames never contain ports. Subdomain matching is also supported: `"example.com"` matches `api.example.com`. See `ai-context-runtime-semantics.md § 4.1` for the full contract including URL scheme filter and subdomain rules.
+**`apiBaseUrl` + `authDomains` matcher behavior:** when a React host passes `apiBaseUrl`, framework-owned relative runtime URLs such as `/api/orders` resolve against that base before URL guards, auth interceptors, and fetch execution. If auth is enabled and `authDomains` is omitted or empty, the exact origin of `apiBaseUrl` (`protocol + host + port`) becomes the default auth target. Same-host services on other ports do not inherit that token. If `authDomains` is provided, the automatic `apiBaseUrl` origin allowlist is disabled; list every trusted absolute host explicitly. The matcher compares hostname only, strips ports, and supports exact/subdomain matching. See `ai-context-runtime-semantics.md § 4.1`.
 
 ### `$auth` Expression
 
@@ -2225,7 +2356,7 @@ The `statePolicy: "reset"` is what clears `/screens/login` on every navigation t
 
 - Tokens NEVER exist in the state store — only in engine closure
 - `$auth` blocks token/password fields via whitelist
-- Auth headers only injected for `authDomains` URLs
+- Auth headers only injected for the host `apiBaseUrl` exact origin or explicit `authDomains` URLs
 - Credentials cleared from state after login (success AND failure)
 - Refresh mutex: max 1 concurrent refresh (anti-stampede)
 - Login rate limit: 5 attempts/min with exponential backoff
@@ -2253,7 +2384,7 @@ The framework uses a scoped fetch wrapper (NOT `globalThis.fetch`). All `fetch`
 
 | Interceptor | Config | Behavior |
 |-------------|--------|----------|
-| **Auth** | Auto when auth configured | Injects Bearer token for `authDomains` URLs. Triggers refresh+retry on 401. |
+| **Auth** | Auto when auth configured | Injects Bearer token for the host `apiBaseUrl` exact origin or explicit `authDomains` URLs. Triggers refresh+retry on 401. |
 | **Logging** | `"logging": true` | Logs request method/URL and response status. Redacts sensitive query params (token, password, key). |
 | **Timeout** | `"timeout": { "ms": 15000 }` | Aborts request after configured milliseconds. Uses AbortController. |
 | **Retry** | `"retryOnError": { ... }` | Retries on transient server errors (502, 503, 504) with exponential backoff. |
@@ -3058,7 +3189,7 @@ The current background and motion stack combines app-level `LayerBackground`, an
 
 211. **`useShapeAnimations(ref, animations, options)` — Layer 3 web runner** — Exported from `mythik-react` via `packages/react/src/animation/useShapeAnimations.ts`. React hook for SVG-child animations (`<path>`/`<circle>`/`<rect>`/`<g>`…). Consumes the same `ElementAnimations` contract as `useElementAnimations` but narrowed to the `ambient` trigger ONLY; shape children have no hover/focus/active contract and no distinct mount ceremony. Attaches CSS animations via `el.style.animation` (surgical, preserves other inline styles); keyframes register once through the CSSOM singleton (zero `dangerouslySetInnerHTML`) and dedupe by hash so multiple shape instances with the same recipe share one CSS rule. Dev mode warns when non-ambient triggers are passed. Production silently ignores them. `options.recipes` SHOULD be stable for useMemo performance.
 
-212. **`useShapeAnimations(animations, options)` — Layer 3 RN runner** — Published through `mythik-react-native` from `packages/react-native/src/animation/useShapeAnimations.ts`. Reanimated parity of rule 211: returns `{ animatedProps }` that the consumer spreads onto `Animated.createAnimatedComponent(Path)` from `react-native-svg`. Uses the `HARD_PER_TRIGGER` (=6) fixed-pool `useSharedValue` pattern (`useSharedValueArray` helper, also exported) so React Hook count stays stable. Reuses `composeRNStyle(contributions, interpolate, interpolateColor)` shared with `useElementAnimations` — single composition pipeline for View-style and animated SVG props. Relies on `react-native-svg` v13+ auto-translating the transform array into SVG `transform="..."` strings. Same dev-mode non-ambient-trigger warning as the web hook.
+212. **`useShapeAnimations(animations, options)` — Layer 3 RN runner** — Implemented inside `mythik-react-native` at `packages/react-native/src/animation/useShapeAnimations.ts` for the native blob/background renderer. It is not exported from the package root as a standalone public hook. Reanimated parity of rule 211: returns `{ animatedProps }` that the renderer spreads onto `Animated.createAnimatedComponent(Path)` from `react-native-svg`. Uses the `HARD_PER_TRIGGER` (=6) fixed-pool `useSharedValue` pattern (`useSharedValueArray` helper) so React Hook count stays stable. Reuses `composeRNStyle(contributions, interpolate, interpolateColor)` shared with `useElementAnimations` — single composition pipeline for View-style and animated SVG props. Relies on `react-native-svg` v13+ auto-translating the transform array into SVG `transform="..."` strings. Same dev-mode non-ambient-trigger warning as the web hook.
 
 213. **Cross-platform Layer 3 parity pins** — `buildCSSKeyframes` (web) and `buildReanimatedSpec` (RN) interpret the same resolved `AnimationSpec` identically on load-bearing invariants: duration agreement (ms count matches regardless of input form `'28s'`/`'28000'`), keyframe stop count (web `%` markers match RN `inputRange` length), direction semantic (`'alternate'` token ⇔ `timing.reverse=true`), iterations `'infinite'`/numeric count, animated-prop enumeration (`translateX/Y`/`rotateDeg`/`scale`).
 
@@ -3134,7 +3265,7 @@ The current background and motion stack combines app-level `LayerBackground`, an
 
 247. **`derive` and `dataSources` are processed at runtime per spec mount** (v0.1.0). When `spec.derive` is present, the framework instantiates a `DeriveEngine`, evaluates all derive paths in topological order at mount, and re-evaluates dirty paths reactively on state changes. Derive paths are protected: setState targeting a derive path errors at validate time and runtime. When `spec.dataSources` is present, the framework instantiates a `DataSourcesEngine`, performs initial fetches (deferred to reactive resolution when URL template deps are undefined), and re-fetches reactively when dependencies change. The action `refreshDataSource` (params: `{ id: string }`) is automatically registered for any spec with dataSources. URL templating requires the explicit `{ $template: '...' }` form — plain strings with `${...}` are NOT substituted (validator catches at load). See `ai-context-runtime-semantics.md` for lifecycle, ordering, error degradation, and state protection details.
 
-248. **CLI is the only approved path for spec writes** (v0.1.0). Three approved forms: (a) **Shell** - `mythik push <id> --from-file spec.json` / `mythik patch <id> --from-file patch.json` (or intentional stdin via `--from-file -` / pipe without `--from-file`); (b) **Bulk** - `mythik push --from-dir ./specs/` (sequential, continue-on-error, no rollback; partial state on failure recovers by fixing failures and re-running the same command); (c) **Programmatic** - `import { runPush, runPatch } from 'mythik-cli/api'` for IDE tooling, test harnesses, CI scripts. NEVER call `SpecStore.save()` directly from application code. It is an internal persistence primitive marked `@internal`; validation happens at the CLI / engine tier. Bypassing this path skips validation and can produce runtime errors visible only at render time. `mythik patch --from-file <path>` is preferred over inline JSON for any patch containing `$state`, `$template`, `$auth`, or `$row` references (PowerShell expands `$<word>` in double-quoted strings).
+248. **CLI is the only approved path for spec writes** (v0.1.0). Three approved forms: (a) **Shell** - `mythik push <id> --from-file spec.json --author <name>` / `mythik patch <id> --from-file patch.json --author <name>` (or intentional stdin via `--from-file -` / pipe without `--from-file` plus `--author`); (b) **Bulk** - `mythik push --from-dir ./specs/ --author <name>` (sequential, continue-on-error, no rollback; partial state on failure recovers by fixing failures and re-running the same command); (c) **Programmatic** - `import { runPush, runPatch } from 'mythik-cli/api'` for IDE tooling, test harnesses, CI scripts. NEVER call `SpecStore.save()` directly from application code. It is an internal persistence primitive marked `@internal`; validation happens at the CLI / engine tier. Bypassing this path skips validation and can produce runtime errors visible only at render time. `mythik patch --from-file <path>` is preferred over inline JSON for any patch containing `$state`, `$template`, `$auth`, or `$row` references (PowerShell expands `$<word>` in double-quoted strings). Existing full-spec replacement requires `--replace`; intentionally unversioned writes require `--allow-unversioned`.
 
 249. **`mythik lint` detects known anti-patterns in specs and consumer code** (v0.1.0).
 
@@ -3149,7 +3280,7 @@ A new CLI command + programmatic API:
 - `spec-row-literal` (warning) — `$row` is not an expression handler; use `$state: '/ui/selectedRow/<key>'`. Validator-resident in `spec-validator.ts` (also surfaces during `mythik push` and `mythik validate`).
 - `spec-crud-id-collision` (error) — `endpoint.path` ending `/:id` combined with `crud: {}` produces `/path/:id/:id`. Strip trailing `/:id`. Walks the object-shaped `endpoints: Record<string, EndpointConfig>`; emits JSON Pointer paths `/endpoints/<name>/path`.
 - `spec-auth-domains-port` (warning) — `auth.authDomains[i]` containing `:port` strips the port silently (matcher uses hostname-only via `URL.hostname`). Walks the `string[]` shape; emits JSON Pointer paths `/auth/authDomains/<index>`.
-- `code-store-save-bypass` (error) — calling `*store*.save()` outside `packages/core/` and `packages/cli/` bypasses validation. Use `runPush` from `mythik-cli/api` or `mythik push --from-file`. **Known scope**: matches `<Identifier>.save()` callees only (e.g. `myStore.save(...)`). Does NOT detect `this.store.save()`, `<obj>.<store>.save()`, or `(await getStore()).save()` patterns — these slip through the AST scanner. Generation-level guidance in `ai-context.md` (anti-patterns section) covers all variants; the lint rule is one layer of defense-in-depth, not a complete catch. Widening the scanner to handle `PropertyAccessExpression` callees is tracked as a v0.2+ candidate if real consumer code shows these patterns slipping through generation guidance.
+- `code-store-save-bypass` (error) — calling `*store*.save()` outside `packages/core/` and `packages/cli/` bypasses validation. Use `runPush` from `mythik-cli/api` with `author` or `mythik push --from-file ... --author <name>`. **Known scope**: matches `<Identifier>.save()` callees only (e.g. `myStore.save(...)`). Does NOT detect `this.store.save()`, `<obj>.<store>.save()`, or `(await getStore()).save()` patterns — these slip through the AST scanner. Generation-level guidance in `ai-context.md` (anti-patterns section) covers all variants; the lint rule is one layer of defense-in-depth, not a complete catch. Widening the scanner to handle `PropertyAccessExpression` callees is tracked as a v0.2+ candidate if real consumer code shows these patterns slipping through generation guidance.
 
 **Code rules require TypeScript ^5.0.0 as peerDependency** (optional). If not installed, code rules emit one warning finding `lint-meta-no-typescript` (severity matches `LintSeverity = 'error' | 'warning'`) and skip cleanly. Spec rules run independently.
 
@@ -3161,7 +3292,7 @@ See `ai-context.md` for spec-gen anti-patterns the AI must NOT generate.
 
 250. **Storage tables are initialized explicitly, never silently at runtime** (v0.1.0). SQL-backed stores operate against three tables the consumer database must already have: `screens` (base, required), `screen_versions` (version history), and `screen_environments` (environment promotions). Use `mythik init-store --dialect <sqlserver|postgres|mysql|sqlite> --dry-run` to inspect canonical idempotent DDL, initialize a local SQLite file with `mythik init-store --dialect sqlite --target ./mythik.db`, or initialize a reachable SQL Server store with explicit `--server`, `--database`, `--user`, `--password`, `--encrypt`, and `--trust-server-certificate` flags. The same schema is described in `ai-context.md § Storage Setup`. Runtime reads/writes do not create missing tables. Production deployment scripts should verify required columns after apply.
 251. **`security.exposeErrors` controls render error detail** (v0.1.0). Default is `true`; set `createMythik({ security: { exposeErrors: false } })` for production-like hosts that must avoid leaking error messages/stacks. `_error` render nodes write diagnostics to `/ui/renderErrors` only when exposure is enabled. Primitive/component exceptions are caught by `MythikRenderer`'s error boundary: development + exposed mode shows an overlay with message and component stack; production or `exposeErrors: false` shows a neutral placeholder. The overlay resets when the spec changes so a corrected spec can recover without remounting the host.
-252. **Icon packs register through `plugins.setIconRenderer`** (v0.1.0). Mythik does not bundle Phosphor/Lucide/etc. Register one host-level renderer from `MythikApp.onPlugins`; the built-in `icon` primitive keeps identity behavior and calls the renderer with `{ name, size, weight, color, style }`. If the placeholder circle renders, verify `onPlugins` registered the renderer and the consumer is not validating against stale tarballs or source aliases.
+252. **Icon packs register through `plugins.setIconRenderer`** (v0.1.0). Mythik does not bundle Phosphor/Lucide/etc. Register one host-level renderer from `MythikApp.onPlugins`; the built-in `icon` primitive, table action icons, toast icons, and React Native icon consumers use that same registration. The built-in `icon` primitive keeps identity behavior and calls the renderer with `{ name, size, weight, color, style }`. If the placeholder circle renders, verify `onPlugins` registered the renderer and the consumer is not validating against stale tarballs or source aliases.
 253. **`overridePrimitive('icon')` returns a RenderNode, not JSX** (v0.1.0). Use it only for full primitive replacement. The renderer function must return `{ type, props, children }` with `_component` in props when targeting React. Returning `<Icon />` directly is not the primitive renderer contract and bypasses the built-in icon identity wrapper.
 254. **CLI explicit input wins over ambient stdin** (v0.1.0). For `mythik push`/`mythik patch`, `--from-file <path>` reads the file even if the host process exposes non-TTY stdin. Intentional stdin remains supported through `--from-file -` or by piping without an explicit file. `--from-file` plus a positional patch argument is still a conflict.
 255. **`runPatch` versions in every output mode when `author` is provided** (v0.1.0). `SpecEngine.patch` applies and validates patches. CLI/API `runPatch` persists through the normal `store.save` path without `author`; with a versioned store + `author`, it captures the patched document and writes once through `saveVersion`, preserving lazy-bootstrap pre-patch history. JSON/TOON success output includes additive `versioned` and `version` metadata.
@@ -3214,17 +3345,21 @@ See `ai-context.md` for spec-gen anti-patterns the AI must NOT generate.
 
 281. **`MythikApp.fetcher` supplies editor persistence when auth fetch is absent** - React hosts can pass `fetcher={(url, options) => ...}` to `MythikApp` so `editorSave` and `navigationGuardSaveAndProceed` have a transport in non-auth apps. When auth is configured, the framework fetch with auth interceptors remains the active fetcher. Save actions do not read global `/ui/lastError`; editor save status, errors, and attempts are reported under `/ui/editorSessions/<id>`.
 
-282. **Existing spec edits must use the CLI inspection-then-patch loop** - For an existing screen/app/api spec, AI agents should run `mythik manifest <id>` first, inspect only the target nodes with `mythik elements <id> <ids>`, apply a small RFC 6902 patch with `mythik patch <id> --from-file patch.json`, and verify with `manifest` or `elements`. This keeps edits surgical, validated, versionable, and reviewable. `pull` is for backup, migration, review, or full-document work; `push` is for new specs or intentional full replacement. Direct database edits and direct `SpecStore.save()` calls bypass validation and are not approved spec-write paths.
+282. **Existing spec edits must use the CLI inspection-then-patch loop** - For an existing screen/app/api spec, AI agents should run `mythik manifest <id>` first, inspect only the target nodes with `mythik elements <id> <ids>`, apply a small RFC 6902 patch with `mythik patch <id> --from-file patch.json --author <agent>`, validate, and verify with `manifest` or `elements`. This keeps edits surgical, validated, versionable, and reviewable. `pull` is for backup, migration, review, or full-document work; `push` is for new specs or intentional full replacement with explicit `--replace`. Direct database edits and direct `SpecStore.save()` calls bypass validation and are not approved spec-write paths.
 283. **Bundled AI docs are part of the install surface** - The `mythik` package includes `docs/llms.txt`, `docs/consumer/*`, and `docs/wiki/compiled/*`. Agents should run `mythik docs path` before spec generation and read the bundled docs rather than guessing from package source. Use `mythik docs copy ./mythik-docs` to create a project-local copy when the host workflow needs explicit files.
 284. **DNA numeric seeds are canonical `0–1`, with legacy `0–100` normalization** - Generate `tokens.dna.roundness`, `density`, `depth`, and `formality` as `0–1` numbers (`0.7`, not `70`). The runtime normalizes numeric seed values greater than `1` by dividing by `100` inside DNA derivation, so initial AppSpec load and runtime `updateTokens` share the same backward-compatible behavior.
 285. **Scoped pagination counts filter before aggregation** - Query endpoints may combine `pagination: "offset"` with `scopeFilter`. For generated counts, the server applies the scope filter to the query source first and then counts the scoped source, so the response `total` matches the same tenant/role slice as `data`. Prefer generated counts. If custom `endpoint.count` is truly needed with `scopeFilter`, it must include `{{scopeWhere[:alias]}}` or `{{scopeAnd[:alias]}}`; Mythik expands the macro to the correct scope predicate and removes it for bypass roles. Other custom count SQL is left verbatim. Specs should use `:alias` for JOIN/subquery counts and should not reference internal scope parameter names directly.
 286. **Transaction fetch failures preserve backend error details** - When a transaction `confirm` uses `fetch` and the backend returns an HTTP error payload such as `{ error: { code, message } }`, `/tx/error` is written after rollback with the best backend message plus `code`, HTTP `status`, and raw `data`. `onError` should read `/tx/error/message`; transaction specs should not read global `/ui/lastError`.
-287. **SQL-backed stores and servers use one dialect-aware `mythik/server` boundary** - Import `createSqlDriver`, `SqlSpecStore`, `SqlVersionedSpecStore`, `SqlEnvironmentStore`, and `getSqlStoreDdl` from `mythik/server` for Node-side SQL work. Supported dialects are `sqlserver`, `postgres`, `mysql`, and `sqlite`. Initialize store tables with `mythik init-store --dialect <dialect>` for reachable SQL stores, `--target` for SQLite, or `--dry-run` for review/apply through a deployment process. SQL Server `init-store` accepts explicit `--server`, `--database`, `--user`, `--password`, `--encrypt`, and `--trust-server-certificate` flags. CLI commands share the same store flags/env vars and must keep existing-spec edits on the `manifest -> elements -> patch --from-file -> validate` loop. ApiSpec `dialect` controls generated CRUD/catalog/pagination/scope SQL; custom SQL remains dialect-native with Mythik named params (`@name`) and is not translated between dialects.
+287. **SQL-backed stores and servers use one dialect-aware `mythik/server` boundary** - Import `createSqlDriver`, `SqlSpecStore`, `SqlVersionedSpecStore`, `SqlEnvironmentStore`, and `getSqlStoreDdl` from `mythik/server` for Node-side SQL work. Supported dialects are `sqlserver`, `postgres`, `mysql`, and `sqlite`. Initialize store tables with `mythik init-store --dialect <dialect>` for reachable SQL stores, `--target` for SQLite, or `--dry-run` for review/apply through a deployment process. SQL Server `init-store` accepts explicit `--server`, `--database`, `--user`, `--password`, `--encrypt`, and `--trust-server-certificate` flags. CLI commands share the same store flags/env vars and must keep existing-spec edits on the `manifest -> elements -> patch --from-file --author -> validate -> verify` loop. ApiSpec `dialect` controls generated CRUD/catalog/pagination/scope SQL; custom SQL remains dialect-native with Mythik named params (`@name`) and is not translated between dialects.
 288. **Event arrays may mix actions and transactions** - Event bindings can be a single action, a single transaction, or an array containing both normal action bindings and transaction bindings. Mythik executes the array sequentially and awaits each transaction before continuing. Transaction phases cannot contain nested transactions.
 289. **`$let` dotted references read nested binding values** - A `$ref` may target an object binding path such as `{ "$ref": "user.name" }`, and `$template` placeholders may read the same path as `${user.name}`. Use this for object values produced by `$let`; missing dotted `$ref` segments are invalid references and should be fixed instead of treated as optional data.
 290. **`params.skipIf` is a dispatch-time action guard** - Any action binding may include `params.skipIf`. Mythik resolves it before resolving the rest of the params; when truthy, the action is skipped and the action chain continues. The action handler never receives `skipIf`.
 291. **Direct `fetch` supports `errorTarget` for visible screen-load failures** - `fetch.params.errorTarget` writes HTTP/network errors to a consumer-owned state path and clears it on success. Use it for critical `initialActions` loads so the screen can render a local banner/empty state; `/ui/lastError` remains global compatibility state and can be overwritten by unrelated fetches.
-292. **`select` supports catalog keys and invalid-option diagnostics** - `select.options` may be strings, `{ label, value }`, or catalog-shaped objects when `labelKey`/`valueKey` are provided. Values emitted from the primitive are strings. Malformed option data renders as disabled diagnostics instead of blank clickable options or crashes, so AI-generated catalog bindings fail visibly.
+292. **`select` supports catalog keys, normalized matching, and invalid-option diagnostics** - `select.options` may be strings, `{ label, value }`, or catalog-shaped objects when `labelKey`/`valueKey` are provided. The current value is matched against options by normalized scalar key, so DB integer IDs and string option values match for display. `0` is a valid selected value. Null/undefined show the placeholder. Values emitted from the primitive remain string-compatible. Malformed option data renders as disabled diagnostics instead of blank clickable options or crashes, so AI-generated catalog bindings fail visibly.
 293. **SQL adapters are optional peer dependencies** - `mythik` does not install SQL drivers by default. Browser-only apps install `mythik mythik-react`. SQL-backed stores/servers must install exactly the selected adapter (`mssql`, `pg`, `mysql2`, or `better-sqlite3`). SQLite uses native `better-sqlite3`; warnings from its transitive native-build helpers are adapter-level install warnings, not Mythik runtime failures.
 294. **Missing SQL adapter errors are actionable** - If a SQL-backed store or server uses a dialect whose adapter package is not installed, Mythik throws `SqlDriverError` with `code: "SQL_DRIVER_DEPENDENCY_MISSING"`, `packageName`, `installCommand`, and a message containing the exact `npm install ...` command.
 295. **`mythik-react-native` publishes an explicit native support contract** - Expo apps should install React Native/Expo peer packages with `npx expo install ...`, including `react-native-reanimated` and its Expo-matched `react-native-worklets` peer, before installing `mythik mythik-react-native`, so Expo selects native module versions that match the app SDK. Keep `react-native-reanimated/plugin` last in the app Babel config. The package exports `REACT_NATIVE_PRIMITIVE_SUPPORT` and `getReactNativePrimitiveSupport(name)`. Supported native primitives are `box`, `stack`, `grid`, `scroll`, `divider`, `spacer`, `text`, `image`, `icon`, `input`, `textarea`, `select`, `checkbox`, `toggle`, `slider`, `button`, `touchable`, `list`, `modal`, `drawer`, `tabs`, `accordion`, `wizard`, `screen`, `screen-outlet`, `toast-container`, and `skeleton`. Native-milestone primitives are `bar-chart`, `line-chart`, `pie-chart`, `area-chart`, `table`, `kanban-board`, `spatial-map`, `file-upload`, `camera`, `signature`, and `audio-player`; they should surface diagnostics instead of silently rendering broken UI. Keep `root` as a stable string and use `$platform` only in localized props/style/children/value branches.
+296. **Mythik Reveal is the live-context bridge for AI agents** - Before guessing about running-app behavior, start `mythik reveal start`, wire the host `reveal` config in development, and inspect with `mythik reveal apps`, `context`, `current`, `screen`, or `element`. Reveal exposes renderer/environment/spec summaries, selected state paths, resolved public props, dependencies, render errors, warnings, events, patch-target metadata, and redaction/truncation metadata as structured JSON. It complements `manifest -> elements -> patch`: use the CLI loop to edit stored specs, and use Reveal to understand the app that is actually running. Keep it development-only, never commit tokens, memoize React/RN reveal config objects, use narrow `includeStatePaths`, and redact secrets deliberately.
+297. **`mythik agent context`, `mythik agent init`, and Mythik Sentinel install and reinforce the AI operating contract**. Use `mythik agent init codex`, `mythik agent init claude`, or `mythik agent init all` to create `.mythik/agent/*` plus thin agent adapters. `codex` creates/updates `AGENTS.md`, `claude` creates/updates `CLAUDE.md`, and `all` updates both; existing file content outside the Mythik-managed `<!-- mythik-agent-protocol:start -->` / `<!-- mythik-agent-protocol:end -->` block is preserved. Use `mythik agent context --app <id> --include-screens` to generate the project-specific operating map. The generated protocol requires existing stored specs to use `manifest -> elements -> patch --from-file --author -> validate -> verify`, names the active store as the source of truth, recommends TOON for token-efficient reads when supported, and scopes `lint` to local drafts, replacement files, bulk import/migration folders, and relevant consumer code. Sentinel runs as advisory CLI coaching: first project use points agents to `agent init`, repeated full-replacement intent warns back to patch-first edits, identical `push --replace` writes are skipped as `skipped: true`, machine-readable outputs stay parseable, and no specs or credentials are persisted in the Sentinel cache. Disable only with `MYTHIK_SENTINEL=off` for exceptional automation.
+298. **`repeat.layout` controls repeated item rows**. `repeat.layout` accepts `{ direction, gap, wrap }` and lets repeated items render horizontally or wrap without changing the child primitive. In grouped repeats, group headers and footers keep the outer vertical flow; the layout applies only to the group item row.
+299. **`text.on.press` is supported for inline interactive text**. Web text receives button semantics, `tabIndex=0`, pointer cursor, and Enter/Space keyboard activation. React Native text uses a pressable wrapper with `accessibilityRole="button"`. Use `button` or `touchable` for primary actions and larger tap targets.

package/docs/llms.txt

@@ -10,8 +10,13 @@ Start here:
 - wiki/compiled/README.md
 - wiki/compiled/_index.md
 
+Project-local agent protocol:
+1. mythik agent init codex|claude|all
+2. mythik agent context --app <app-id> --include-screens --out .mythik/agent/context.md
+
 Required edit loop for existing persisted specs:
 1. mythik manifest <spec-id>
 2. mythik elements <spec-id> <element-ids>
-3. mythik patch <spec-id> --from-file <patch.json>
+3. mythik patch <spec-id> --from-file <patch.json> --author <agent-name>
 4. mythik validate <spec-id>
+5. mythik manifest <spec-id> or mythik elements <spec-id> <element-ids> to verify

package/docs/wiki/compiled/README.md

@@ -1,6 +1,6 @@
 # Mythik - Compiled Wiki
 
-Compiled from `docs/consumer/` into **327 atomic articles**. The wiki is optimized for AI consumption: each article is one concept, and `_index.md` is the flat searchable graph.
+Compiled from `docs/consumer/` into **331 atomic articles**. The wiki is optimized for AI consumption: each article is one concept, and `_index.md` is the flat searchable graph.
 
 ## Reading order for first-time spec authoring
 
@@ -9,22 +9,24 @@ Compiled from `docs/consumer/` into **327 atomic articles**. The wiki is optimiz
 3. [concept-spec-types](concept-spec-types.md) - Screen vs AppSpec vs ApiSpec.
 4. [concept-expression-contexts](concept-expression-contexts.md) and [concept-expression-timing](concept-expression-timing.md) - where expressions work and when they resolve.
 5. [concept-primitives-overview](concept-primitives-overview.md) and [primitive-spatial-map](primitive-spatial-map.md) - primitives, including the spatial-map editor surface.
-6. [cli-existing-spec-edit-loop](cli-existing-spec-edit-loop.md) - required loop for modifying existing persisted specs.
-7. [cli-docs](cli-docs.md) - locate or copy the bundled AI documentation after `npm install`.
+6. [cli-existing-spec-edit-loop](cli-existing-spec-edit-loop.md) - required loop for modifying existing persisted specs.
+7. [concept-mythik-reveal](concept-mythik-reveal.md) and [cli-reveal](cli-reveal.md) - inspect live runtime context before guessing.
+8. [concept-agent-context-protocol](concept-agent-context-protocol.md) and [cli-agent](cli-agent.md) - install the project-local AI operating contract.
+9. [cli-docs](cli-docs.md) - locate or copy the bundled AI documentation after `npm install`.
 
-## Publish notes
-
-- Public package names are unscoped: `mythik`, `mythik-react`, `mythik-cli`, `mythik-server`, `mythik-react-native`.
-- `mythik-react-native` is a public preview release line with an explicit support matrix.
-- The wiki metadata folder is not publish content.
-- `docs/consumer` remains the canonical source.
+## Publish notes
+
+- Public package names are unscoped: `mythik`, `mythik-react`, `mythik-cli`, `mythik-server`, `mythik-react-native`.
+- `mythik-react-native` is a public preview release line with an explicit support matrix.
+- The wiki metadata folder is not publish content.
+- `docs/consumer` remains the canonical source.
 
 ## Catalog
 
 - [Actions](#actions) - 19
 - [Anti-patterns](#anti-patterns) - 21
-- [CLI](#cli) - 19
-- [Concepts](#concepts) - 177
+- [CLI](#cli) - 21
+- [Concepts](#concepts) - 179
 - [Expressions](#expressions) - 22
 - [Paths](#paths) - 13
 - [Patterns](#patterns) - 18

package/docs/wiki/compiled/_gaps.md

@@ -6,7 +6,7 @@ Per the compilation rules: **never fabricate, surface as a gap.**
 
 ## Status: 0 gaps detected during compilation
 
-All 326 articles were written from raw content present in the source
+All 331 articles were written from raw content present in the source
 files. Every fact in the compiled wiki traces to a `docs/consumer/<file>.md`
 section listed in the article's `sources:` frontmatter.
 

package/docs/wiki/compiled/_index.md

@@ -48,14 +48,15 @@ Flat catalog generated from `docs/wiki/compiled`. Use the article ID for wikilin
 @antipattern-style-block-duplication :: antipattern-style-block-duplication.md :: Anti-pattern — duplicate style blocks
 @antipattern-submit-form-in-tx-confirm :: antipattern-submit-form-in-tx-confirm.md :: Anti-pattern — `submitForm` in `transaction.confirm`
 
-## CLI (19)
+## CLI (21)
 
-@cli-app-spec :: cli-app-spec.md :: CLI on AppSpecs
+@cli-app-spec :: cli-app-spec.md :: CLI on AppSpecs
+@cli-agent :: cli-agent.md :: `mythik agent` - project-local AI operating context
 @cli-config :: cli-config.md :: CLI config — `.mythikrc` + env vars
 @cli-contract :: cli-contract.md :: `mythik contract` — frontend↔backend cross-validation
-@cli-delete :: cli-delete.md :: `mythik delete` — with safety gate
-@cli-docs :: cli-docs.md :: `mythik docs` — bundled AI documentation
-@cli-elements :: cli-elements.md :: `mythik elements` — inspect specific elements
+@cli-delete :: cli-delete.md :: `mythik delete` — with safety gate
+@cli-docs :: cli-docs.md :: `mythik docs` — bundled AI documentation
+@cli-elements :: cli-elements.md :: `mythik elements` — inspect specific elements
 @cli-existing-spec-edit-loop :: cli-existing-spec-edit-loop.md :: Existing spec edit loop
 @cli-history :: cli-history.md :: `mythik history` — version history with diffs
 @cli-lint :: cli-lint.md :: `mythik lint` — anti-pattern detection
@@ -65,12 +66,13 @@ Flat catalog generated from `docs/wiki/compiled`. Use the article ID for wikilin
 @cli-programmatic-api :: cli-programmatic-api.md :: Programmatic API — `mythik-cli/api`
 @cli-pull :: cli-pull.md :: `mythik pull` — export spec
 @cli-push :: cli-push.md :: `mythik push` — three approved write paths
+@cli-reveal :: cli-reveal.md :: `mythik reveal` - live runtime context
 @cli-tokens :: cli-tokens.md :: `mythik tokens` — DNA inspection
 @cli-toon :: cli-toon.md :: `--toon` - token-efficient format
 @cli-validate :: cli-validate.md :: `mythik validate`
 @cli-versioning-author :: cli-versioning-author.md :: `--author` flag — activates versioning
 
-## Concepts (177)
+## Concepts (179)
 
 @concept-action-chains :: concept-action-chains.md :: Action chains — sequential execution
 @concept-action-middleware :: concept-action-middleware.md :: Action middleware
@@ -81,7 +83,8 @@ Flat catalog generated from `docs/wiki/compiled`. Use the article ID for wikilin
 @concept-animation-null-semantics :: concept-animation-null-semantics.md :: Animation null semantics
 @concept-animation-recipes :: concept-animation-recipes.md :: 15 animation recipes
 @concept-animation-triggers :: concept-animation-triggers.md :: Animation triggers — 7 triggers
-@concept-animations-engine :: concept-animations-engine.md :: `animations` engine (preferred)
+@concept-animations-engine :: concept-animations-engine.md :: `animations` engine (preferred)
+@concept-agent-context-protocol :: concept-agent-context-protocol.md :: Mythik Agent Context and Agent Protocol
 @concept-api-audit :: concept-api-audit.md :: `audit` — auto-inject user + timestamp
 @concept-api-auth :: concept-api-auth.md :: API auth (`auth` block)
 @concept-api-catalogs :: concept-api-catalogs.md :: API catalogs — dropdown sources
@@ -179,6 +182,7 @@ Flat catalog generated from `docs/wiki/compiled`. Use the article ID for wikilin
 @concept-layer-background :: concept-layer-background.md :: `tokens.identity.background` — LayerBackground v2
 @concept-motion-field :: concept-motion-field.md :: `motion` field (legacy Framer-Motion)
 @concept-mount-spec-runtime :: concept-mount-spec-runtime.md :: `mountSpecRuntime` — internal mount helper
+@concept-mythik-reveal :: concept-mythik-reveal.md :: Mythik Reveal - live runtime context for AI agents
 @concept-mythik-renderer :: concept-mythik-renderer.md :: `MythikRenderer` - root mount
 @concept-navigation :: concept-navigation.md :: Navigation config
 @concept-navigation-dirty-guard :: concept-navigation-dirty-guard.md :: Navigation dirty guard