mythik 0.1.5 → 0.2.1

package/docs/consumer/ai-context-patterns.md

@@ -180,7 +180,7 @@ Parametrize via `$prop`. Use `$children` in template's `children` array to slot
 
 ### When to use `tokens.components.{type}.{variantName}`
 
-Define a reusable style set for a PRIMITIVE (button, input, card) that merges into every element declaring `variant: "name"`. Use for STYLE-ONLY reuse (same type, different visual variant).
+Define a reusable style set for a PRIMITIVE (button, input, card, table root, touchable chip shell) that merges into every element declaring `props.variant: "name"`. Use for STYLE-ONLY reuse (same type, different visual variant).
 
 **Defining a variant:**
 ```json
@@ -204,10 +204,44 @@ Define a reusable style set for a PRIMITIVE (button, input, card) that merges in
 }
 ```
 
-**Using in any spec:**
-```json
-{ "type": "button", "props": { "variant": "ctaPulse", "label": "..." } }
-```
+**Using in any spec:**
+```json
+{ "type": "button", "props": { "variant": "ctaPulse", "label": "..." } }
+```
+
+Variants intentionally cover visual slots only: `style`, `hover`, `active`, `focus`, `transition`, and `animations`. They do not carry arbitrary primitive props. If the repeated pattern includes table `headerStyle`/`rowStyle`, `columns`, `onRowClick`, child composition, or action bindings, use a template or custom element instead.
+
+**Data table chrome pattern:** put the panel shell in a `box` variant, then wrap the table in an AppSpec template so the shared `headerStyle`/`rowStyle` lives once.
+
+```json
+{
+  "tokens": {
+    "components": {
+      "box": {
+        "tableCard": { "style": { "padding": 0, "overflow": "hidden" } }
+      }
+    }
+  },
+  "templates": {
+    "ops-table": {
+      "type": "table",
+      "defaults": {
+        "headerStyle": { "minHeight": 44, "background": "#F8FAFC" },
+        "rowStyle": { "base": { "minHeight": 43 }, "hover": { "backgroundColor": "#F8FAFC" } }
+      },
+      "props": {
+        "data": { "$prop": "data" },
+        "columns": { "$prop": "columns" },
+        "onRowClick": { "$prop": "onRowClick" },
+        "headerStyle": { "$prop": "headerStyle" },
+        "rowStyle": { "$prop": "rowStyle" }
+      }
+    }
+  }
+}
+```
+
+**Filter chip pattern:** for chips composed from `touchable` + `text`, define static shell/label variants, then keep active-state `$state`/`$item` color expressions on the actual chip elements. Variants do not evaluate `$state`/`$item`; templates/custom elements are the heavier option when the composition itself should be reusable.
 
 ### Rule: don't duplicate style blocks across specs
 
@@ -235,8 +269,9 @@ If the same rich style object appears in 2+ specs (or 2+ places in same spec), e
 
 | Situation | Use |
 |---|---|
-| Same primitive type, different style set | `tokens.components.{type}.{variant}` |
-| Composite (custom type wrapping primitive + children slot) | `appSpec.templates` |
+| Same primitive type, different style set | `tokens.components.{type}.{variant}` |
+| Primitive style plus repeated primitive props (e.g. table `headerStyle`/`rowStyle`) | `appSpec.templates` |
+| Composite (custom type wrapping primitive + children slot) | `appSpec.templates` or Layer 3 custom element |
 | Style varies by state (hover/active/focus) | Variants (built-in state slots) |
 | Parametrized via props + children | Templates (with `$prop` + `$children`) |
 

package/docs/consumer/ai-context-primitives.md

@@ -41,6 +41,8 @@ Container element. Props: `className`, `surface`.
 | `variant` | string | — | `heading` (h2), `body` (p), `caption` (span), `label` (label), `mono` (code) |
 | `className` | string | — | CSS class |
 
+**Events:** `on.press` is supported for inline interactive text. The renderer supplies button semantics and keyboard activation on web and `accessibilityRole="button"` on React Native. Use `button` or `touchable` for primary actions and larger tap targets.
+
 ### image
 
 | Prop | Type | Default | Description |
@@ -61,7 +63,7 @@ Container element. Props: `className`, `surface`.
 
 Names are kebab-case, library-agnostic.
 
-**Icon renderer contract:** Mythik does not bundle an icon pack. The built-in `icon` primitive renders a placeholder unless the host app registers a renderer with `plugins.setIconRenderer(Component)`. Register it from `MythikApp.onPlugins`; the built-in primitive keeps identity behavior (container, default weight) and calls your renderer with `{ name, size, weight, color, style }`.
+**Icon renderer contract:** Mythik does not bundle an icon pack. Register icons once with `plugins.setIconRenderer(Component)`. The built-in `icon` primitive, table action icons, toast icons, and React Native icon consumers use that same registration. The built-in primitive keeps identity behavior (container, default weight) and calls your renderer with `{ name, size, weight, color, style }`. Use `overridePrimitive('icon')` only for full primitive replacement.
 
 ```tsx
 import { MythikApp } from 'mythik-react';
@@ -102,7 +104,7 @@ function LucideIcon({ name, size, color, style }) {
 
 **Troubleshooting:** if you see the placeholder circle, the renderer was not present in resolved tokens when the app applied plugins. Verify `onPlugins` calls `setIconRenderer`, verify the consumer is installed from a tarball/package that includes the `applyPlugins()` icon renderer fix, and avoid using source aliases when validating published-package behavior.
 
-**Advanced override:** `plugins.overridePrimitive('icon', ...)` is still supported, but it replaces the whole primitive and bypasses the built-in identity wrapper. The renderer function must return a Mythik `RenderNode`, not JSX:
+**Full primitive replacement:** `plugins.overridePrimitive('icon', ...)` is still supported, but it replaces the whole primitive and bypasses the built-in identity wrapper. The renderer function must return a Mythik `RenderNode`, not JSX:
 
 ```ts
 plugins.overridePrimitive('icon', (props, children) => ({
@@ -120,8 +122,25 @@ plugins.overridePrimitive('icon', (props, children) => ({
 | `gap` | number | — | Space between children (px) |
 | `align` | string | — | Cross-axis: `start`, `center`, `end`, `stretch` |
 | `justify` | string | — | Main-axis: `start`, `center`, `end`, `between`, `around` |
+| `wrap` | boolean | `false` | Allow horizontal rows to wrap |
 | `className` | string | — | CSS class |
 
+`repeat.layout` lets a repeated container render its item rows horizontally without changing the child primitive:
+
+```json
+{
+  "type": "stack",
+  "repeat": {
+    "source": { "$state": "/filters" },
+    "key": "id",
+    "layout": { "direction": "horizontal", "gap": 8, "wrap": true }
+  },
+  "children": ["filter-chip"]
+}
+```
+
+Grouped repeats keep group headers/footers vertical and apply `repeat.layout` only to each group's item row.
+
 ### grid
 
 | Prop | Type | Default | Description |
@@ -197,6 +216,8 @@ Props: `size` (px), `direction` (`vertical`/`horizontal`). Renders empty space.
 | `options` | array | — | Strings or `[{ label, value }]` objects |
 | `placeholder` | string | — | Placeholder text |
 | `label` | string/expression | — | Field label |
+| `labelKey` | string | — | Label field for catalog-shaped options |
+| `valueKey` | string | — | Value field for catalog-shaped options |
 | `disabled` | boolean/expression | `false` | Disable |
 | `required` | boolean | `false` | Visual indicator |
 
@@ -209,6 +230,8 @@ Options formats:
 "options": { "$state": "/cat/services/data" }, "labelKey": "name", "valueKey": "id"
 ```
 
+`select` matches the current value against options by normalized scalar key. DB integer IDs and string option values match for display. `0` is a valid selected value. Null/undefined show the placeholder. Existing `onChange` output remains string-compatible.
+
 `labelKey` defaults to `"label"` and `valueKey` defaults to `"value"`. Use them for catalog rows such as `{ "id": 1, "name": "Cambio de aceite" }`. Values are emitted as strings from `on.change`. Malformed object options render as disabled diagnostics instead of blank clickable rows.
 
 ### checkbox

package/docs/consumer/ai-context-runtime-semantics.md

@@ -14,7 +14,7 @@
 1. 🔴 [`/ui/selectedRow` magic path (§2.1)](#21-uiselectedrow--blocker-1)
 2. 🔴 [CRUD 1-endpoint 3-route auto-generation (§3.1)](#31-crud--one-endpoint-three-routes--blocker-3)
 3. 🟢 [dataSources + derive lifecycle (§5.2 + §5.3)](#52-datasources-lifecycle) — SHIPPED v0.1.0 Item E
-4. 🟢 [authDomains hostname-only matching (§4.1)](#41-authdomains-hostname-only--blocker-5)
+4. 🟢 [`apiBaseUrl` + `authDomains` auth target matching (§4.1)](#41-apibaseurl--authdomains--auth-target-matching)
 
 These five behaviors caused the most source-reading in the 2026-04 consumer-simulation experiment. If you read only one section of this doc, read these.
 
@@ -612,26 +612,35 @@ Implementation: `packages/server/src/server.ts` (search `buildScopeWhereClause`
 
 ## 4. Matcher Semantics
 
-### 4.1 `authDomains` — hostname-only 🟢 BLOCKER #5
+### 4.1 `apiBaseUrl` + `authDomains` — auth target matching
 
-**Contract:** auth headers (Bearer tokens) are auto-injected on fetch/submitForm requests when the URL's hostname matches any entry in `authDomains`. Port is stripped; only the hostname is compared.
+**Contract:** framework-owned runtime fetches resolve their URL before URL guards, auth interceptors, and fetch execution. When `MythikApp` receives `apiBaseUrl`, relative runtime URLs such as `/api/orders` resolve against that base. With web auth enabled, if `authDomains` is omitted or empty, the exact origin of `apiBaseUrl` (`protocol + host + port`) becomes the default effective auth target for framework-owned requests.
 
-**Matching rules:**
+**Default `apiBaseUrl` auth rule:**
+
+| Host config | Request URL in spec | Effective URL | Bearer token? |
+|---|---|---|---|
+| `apiBaseUrl: "http://localhost:3010"` | `/api/orders` | `http://localhost:3010/api/orders` | yes |
+| `apiBaseUrl: "http://localhost:3010"` | `http://localhost:3010/api/orders` | unchanged | yes |
+| `apiBaseUrl: "http://localhost:3010"` | `http://localhost:5173/api/orders` | unchanged | no |
+| `apiBaseUrl: "http://localhost:3010"` | `https://third-party.example/api` | unchanged | no |
+
+Same-host services on different ports do not inherit the `apiBaseUrl` token. Absolute third-party URLs never inherit that token unless explicitly listed in `authDomains`.
+
+**Explicit `authDomains` rule:** when `authDomains` is provided, it remains hostname-based for absolute `http://` and `https://` URLs. Port is stripped because `new URL(fetchUrl).hostname` excludes the port; subdomain matching is supported.
 
 | `authDomains` entry | Matches | Does NOT match |
 |---|---|---|
 | `"api.example.com"` | `https://api.example.com/...` (any port) | `https://notapi.example.com`, `https://example.com` |
 | `"example.com"` | `https://example.com`, `https://api.example.com`, `https://foo.example.com` (exact + subdomain) | `https://notexample.com` |
 | `"localhost"` | `http://localhost:5173/...`, `http://localhost:3010/...`, `http://localhost/...` | `http://127.0.0.1` |
-| `"localhost:5173"` | nothing (port is stripped from the URL side, but the domain entry literally contains `:5173` which is never the hostname of any URL) | everything |
-
-**Mechanism:** `new URL(fetchUrl).hostname` comparison. Port stripping is a side-effect of the URL API — `.hostname` excludes the port. Subdomain matching: an entry `"example.com"` matches any URL whose hostname ends with `.example.com` (note the leading dot in the comparison — prevents `"api.com"` from matching `"notapi.com"`).
+| `"localhost:5173"` | nothing (domain entries must be hostnames, not `host:port`) | everything |
 
-**Dev-mode guidance:** configure `authDomains: ["localhost"]` (no port). Tokens inject on any localhost port during dev.
+**Dev-mode guidance:** prefer `apiBaseUrl` for the app's own backend (`<MythikApp apiBaseUrl="http://localhost:3010" ... />`). If `authDomains` is omitted or empty, Mythik injects Bearer only for that exact `apiBaseUrl` origin. If you provide `authDomains`, the automatic `apiBaseUrl` origin allowlist is disabled; list every trusted absolute host explicitly. Do not add `:port` inside `authDomains[]`.
 
-**URL scheme filter:** only `http://` and `https://` URLs are considered. Relative paths (`/api/rooms`), `file:`, `data:`, and other schemes return `false` before matching — auth headers are not injected on those requests.
+**URL scheme filter:** only `http://` and `https://` URLs are considered for auth injection. `file:`, `data:`, and other schemes never receive auth headers.
 
-Implementation: `packages/core/src/fetch/interceptors/auth.ts:17-28`.
+Implementation: `packages/core/src/fetch/framework-fetch.ts` (base URL resolution) + `packages/core/src/fetch/interceptors/auth.ts` (auth target matching).
 
 ### 4.2 Contract URL template matching
 
@@ -755,12 +764,12 @@ The persistence layer has distinct paths used at different levels. Understanding
 - **`store.save(id, doc)`** - low-level persistence primitive. Accepts `doc: unknown`. No validation. Called by validated orchestration after checks succeed. **Never called from application code** - treat as `@internal`. Calling `store.save()` from your app bypasses validation and produces silently-broken specs.
 - **`store.saveVersion(id, doc, meta)`** - versioned write. Writes a row to `screen_versions` table and updates the current spec. Enables diff/rollback/promote/bisect.
 - **`SpecEngine.patch(id, patches)`** - validated orchestration. Applies RFC-6902 patches, runs DocumentHandler validation, short-circuits on error, and persists the patched document through `store.save`.
-- **CLI/API `mythik push` / `runPush`** - validates and handles `--author` / `author` by writing through `saveVersion` when the resolved store is versioned.
-- **CLI/API `mythik patch` / `runPatch`** - uses `SpecEngine.patch` for patch application + validation. Without `author`, it persists through the normal `store.save` path. With a versioned store + `author`, it captures the patched document and writes once through `saveVersion`, so lazy bootstrap preserves the pre-patch current spec as v1 and the patch becomes the next version. JSON/TOON success output includes `versioned: boolean` and `version?: number`.
+- **CLI/API `mythik push` / `runPush`** - validates and handles `--author` / `author` by writing through `saveVersion` when the resolved store is versioned. Existing specs require explicit `--replace` for full replacement.
+- **CLI/API `mythik patch` / `runPatch`** - uses `SpecEngine.patch` for patch application + validation. With a versioned store + `author`, it captures the patched document and writes once through `saveVersion`, so lazy bootstrap preserves the pre-patch current spec as v1 and the patch becomes the next version. JSON/TOON success output includes `versioned: boolean` and `version?: number`. Without `author`, persisted writes are rejected unless `allowUnversioned` / `--allow-unversioned` is explicit.
 
 **Consumer rule (to be enforced by Item I linter):** never call `store.save()` from application code. Use:
 
-- `mythik push <id>` / `mythik patch <id>` for interactive/shell work
+- `mythik push <id> --from-file spec.json --author <name>` / `mythik patch <id> --from-file patch.json --author <name>` for interactive/shell work
 - `runPush` / `runPatch` from `mythik-cli/api` for programmatic work (Item F exposes these as public exports)
 
 Implementation:
@@ -810,14 +819,14 @@ The framework supports two axes of workflow choice: **how you modify specs** (pu
 **Push paradigm:**
 
 - Specs live in git under `specs/*.json`
-- Modify locally, run `mythik push <id>`, CLI sends the full spec doc to the DB
+- Modify locally, run `mythik push <id> --from-file spec.json --author <name>`, CLI sends the full spec doc to the DB
 - Diff-reviewable in CI (normal git diff on the JSON file)
 - Full-spec bandwidth cost per write
 
 **Patch paradigm:**
 
 - Specs live in the DB; local files are optional (working copy)
-- Modify via `mythik patch <id> --from-file patch.json` for shell-safe surgical writes
+- Modify via `mythik patch <id> --from-file patch.json --author <name>` for shell-safe surgical writes
 - ~11x token efficiency vs full push (framework-internal measurement for typical single-element edits)
 - Requires `mythik pull <id>` to sync any local `specs/*.json` snapshot after a DB patch
 
@@ -840,8 +849,11 @@ The framework supports two axes of workflow choice: **how you modify specs** (pu
 **Git-backed history:**
 
 - Specs in repo, `git log` + `git blame` serve as audit trail
-- No `--author` flag needed on push/patch
-- CLI writes via `store.save` (unversioned path, see §5.4)
+- Persisted CLI writes must still be explicit: use `--author <name>`
+  whenever the resolved store supports versioning, or
+  `--allow-unversioned` only when the project intentionally uses a
+  non-versioned store
+- CLI writes via `store.save` only on the explicit unversioned path (see §5.4)
 - Best for: single-env apps, dev-loop iteration, specs-as-code
 
 **DB-versioned history:**
@@ -921,7 +933,7 @@ The `$state` resolves at click time against the just-written `/ui/selectedRow`.
 
 **Root:** §4.1 — matcher uses `parsed.hostname` (strips port). Entry `"localhost:5173"` never matches any URL's hostname (which is just `"localhost"`).
 
-**Solution:** `authDomains: ["localhost"]`. Matches all localhost ports (5173, 3010, etc.).
+**Solution:** prefer `apiBaseUrl: "http://localhost:3010"` on the host app for the app's own backend. If you intentionally need an explicit additional host, use `authDomains: ["localhost"]`, not `["localhost:5173"]`.
 
 ### 7.5 Wiring a reactive data source with a debounced filter
 
@@ -1012,7 +1024,8 @@ Login spec binds input to `/login/email`; `loginBody` maps it to `username` at d
 - `packages/core/src/device/context.ts` — DeviceContext interface
 
 **Fetch + auth:**
-- `packages/core/src/fetch/interceptors/auth.ts:17-28` — authDomains matcher
+- `packages/core/src/fetch/framework-fetch.ts` — `apiBaseUrl` resolution
+- `packages/core/src/fetch/interceptors/auth.ts` — auth target matcher
 
 **Server:**
 - `packages/server/src/server.ts:104-116` — `/api/auth/login` endpoint

package/docs/consumer/ai-context.md

@@ -88,7 +88,7 @@ Every screen is a flat tree: `root` ID + `elements` map + optional `initialActio
 | `style` | object | CSS styles (can contain expressions) |
 | `visible` | expression | Show/hide condition |
 | `permission` | object | `{ visible, editable, readonly }` per role |
-| `repeat` | object | Iterate over array: `{ statePath, key }` or `{ source, key }` |
+| `repeat` | object | Iterate over array: `{ statePath, key }` or `{ source, key }`; optional `layout` controls item row direction/gap/wrap |
 | `on` | object | Event handlers: `{ press, change, submit }` |
 | `hover` | object | Style overrides on pointer enter |
 | `active` | object | Style overrides on press |
@@ -108,10 +108,17 @@ mythik init-store --dialect postgres --dry-run           # Print SQL store DDL f
 mythik init-store --dialect sqlserver --server localhost --database Mythik --user "$DB_USER" --password "$DB_PASSWORD" --encrypt false --trust-server-certificate
 mythik manifest <screen>               # See structural tree
 mythik elements <screen> <id1,id2>     # Get element details
-mythik patch <screen> --from-file patch.json  # Apply RFC 6902 patches
+mythik patch <screen> --from-file patch.json --author <agent>  # Apply versioned RFC 6902 patches
 mythik pull <screen>                    # Export full spec for backup/review
-mythik push <screen>                    # Create or intentionally replace a full spec
+mythik push <screen> --from-file spec.json --author <agent>  # Create a new spec
+mythik push <screen> --from-file spec.json --replace --author <agent>  # Intentional full replacement
 mythik validate <screen>               # Validate spec
+mythik reveal start                    # Start local runtime context bridge
+mythik reveal apps --json              # List connected running apps
+mythik reveal context --app <name>     # Read live app contract/state/diagnostics
+mythik reveal element <id> --app <name>  # Inspect one live element
+mythik agent init codex|claude|all      # Install project-local AI operating protocol
+mythik agent context --app <app-id> --include-screens --out .mythik/agent/context.md
 ```
 
 ### Required edit loop for existing specs
@@ -121,20 +128,78 @@ When an AI agent modifies an existing Mythik spec, use this loop by default:
 1. `mythik manifest <screen>` - inspect the current structure and identify candidate element IDs.
 2. `mythik elements <screen> <id1,id2,...>` - inspect only the exact elements and nearby containers that will change.
 3. Write a small RFC 6902 patch file.
-4. `mythik patch <screen> --from-file patch.json` - apply the surgical change through the validated CLI path.
-5. Re-run `mythik manifest <screen>` or `mythik elements <screen> <ids>` to verify the changed surface.
+4. `mythik patch <screen> --from-file patch.json --author <agent>` - apply the surgical change through the validated, versioned CLI path.
+5. Run `mythik validate <screen>`.
+6. Re-run `mythik manifest <screen>` or `mythik elements <screen> <ids>` to verify the changed surface.
 
 Do not edit database rows directly, do not call `SpecStore.save()` from app code, and do not replace a whole screen with `push` when a targeted `patch` can express the change. `pull` is for backup, migration, review, or full-spec creation workflows; it is not the normal first step for a small edit.
 
-**Patch rules:** `"op": "add"` with numeric index **inserts before** (not replace). Use `/-` to append. Use `"op": "replace"` to overwrite. Prefer `mythik patch <id> --from-file patch.json` for any patch containing `$state`, `$template`, `$auth`, or other shell-sensitive strings.
+Mythik Sentinel is built into the CLI to help fresh agents stay on that loop. It prints advisory guidance on first project use and when it detects repeated full-replacement intent with little/no patch usage. Sentinel is best-effort: it does not change command exit codes, it does not store specs or credentials, and it preserves JSON/TOON machine-readable outputs. Disable only for exceptional automation with `MYTHIK_SENTINEL=off`.
 
-**Patch input precedence:** explicit sources win. `--from-file <path>` reads that file even if the host process has non-TTY stdin (common in PowerShell/agent runners). Stdin still works via `--from-file -` or by piping without `--from-file`: `cat patch.json | mythik patch <id>`.
+**Patch rules:** `"op": "add"` with numeric index **inserts before** (not replace). Use `/-` to append. Use `"op": "replace"` to overwrite. Prefer `mythik patch <id> --from-file patch.json --author <agent>` for any patch containing `$state`, `$template`, `$auth`, or other shell-sensitive strings.
+
+**Patch input precedence:** explicit sources win. `--from-file <path>` reads that file even if the host process has non-TTY stdin (common in PowerShell/agent runners). Stdin still works via `--from-file -` or by piping without `--from-file`: `cat patch.json | mythik patch <id> --author <agent>`.
 
 All commands accept `--json`, `--table <name>`, `--store`, `--url`, `--key`. Never pass API keys inline — use `.mythikrc` + env vars.
 
+### Mythik Reveal: live context for AI agents
+
+Use Mythik Reveal when debugging or changing a running app. Lint,
+validate, `manifest`, and `elements` inspect stored specs; Reveal
+inspects the live runtime. It exposes the active renderer, environment,
+mounted spec summary, selected screen/element, resolved public props,
+included state paths, render errors, warnings, and action/dataSource
+events as structured JSON.
+
+Start the local bridge:
+
+```bash
+mythik reveal start --port 17373
+```
+
+Pass the printed `MYTHIK_REVEAL_URL` and `MYTHIK_REVEAL_TOKEN` to the
+host app's `reveal` config. In React, memoize the object so the bridge
+client is stable:
+
+```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 inspect the running 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
+```
+
+For React Native Android emulator smoke, reverse the bridge port:
+
+```bash
+adb reverse tcp:17373 tcp:17373
+```
+
+Reveal is development tooling. Do not enable it in production, do not
+commit tokens, and expose only the state paths the agent needs.
+Redact auth, secrets, tokens, passwords, API keys, and session values.
+When a runtime symptom is visible but the cause is unknown, agents
+should ask Reveal before proposing a patch.
+
 ### CLI store configuration
 
-The CLI can read and write specs from `memory`, `file`, `supabase`, `sqlserver`, `postgres`, `mysql`, and `sqlite` stores. SQL stores share the same commands and the same required edit loop: `manifest -> elements -> patch -> validate`.
+The CLI can read and write specs from `memory`, `file`, `supabase`, `sqlserver`, `postgres`, `mysql`, and `sqlite` stores. SQL stores share the same commands and the same required edit loop: `manifest -> elements -> patch --from-file --author -> validate -> verify`.
 
 ```bash
 # SQLite: local development, tests, demos, lightweight deployments
@@ -166,12 +231,14 @@ Environment equivalents: `MYTHIK_STORE`, `MYTHIK_DATABASE_URL`, `MYTHIK_SQLITE_F
 
 Per reference-doc rule 248: three approved forms.
 
-- **Shell**: `mythik push <id> --from-file spec.json` and `mythik patch <id> --from-file patch.json` (cross-shell ergonomic for any spec/patch containing `$state`, `$template`, `$auth`, or `$row`)
-- **Bulk**: `mythik push --from-dir <folder>` — sequential per-file push of every `*.json`. Continue-on-error: failures don't stop subsequent specs. No rollback. Partial state recovers by fixing failures and re-running.
+- **Shell**: `mythik push <id> --from-file spec.json --author <agent>` and `mythik patch <id> --from-file patch.json --author <agent>` (cross-shell ergonomic for any spec/patch containing `$state`, `$template`, `$auth`, or `$row`)
+- **Bulk**: `mythik push --from-dir <folder> --author <agent>` — sequential per-file push of every `*.json`. Continue-on-error: failures don't stop subsequent specs. No rollback. Partial state recovers by fixing failures and re-running.
 - **Programmatic**: `import { runPush, runPatch, parsePatchInput, type PushResult } from 'mythik-cli/api'` — same code path as the binary, no shell. Pass `json: true` in options to receive structured command output via `JSON.parse(result.output)`. `runPatch` success output includes `versioned: boolean` and `version?: number` when a versioned store + `author` creates history.
 
 `SpecStore.save()` is `@internal` — calling it from application code skips validation and produces runtime errors only at render time. The three forms above are the only validated paths.
 
+Existing persisted specs are protected by the Agent Protocol: full replacements require `--replace`, and persisted writes require `--author <name>` for versioned stores or explicit `--allow-unversioned` for intentionally unversioned stores.
+
 ### Pre-push linting
 
 Run `mythik lint` to detect anti-patterns before pushing. Three approved invocations:
@@ -450,7 +517,7 @@ Any action binding may include `params.skipIf`. Mythik resolves `skipIf` at disp
 - Sets `/ui/loading` while in flight
 - On error: sets `/ui/lastError` with status and message
 - Optional `errorTarget` writes the same structured error to a screen-owned path and clears that path on success. Use it for critical screen-load fetches instead of relying only on global `/ui/lastError`
-- Auth headers auto-injected for `authDomains` URLs
+- Auth headers auto-injected for `apiBaseUrl` exact-origin framework URLs and explicit `authDomains` hosts
 
 ### Transactions (Optimistic Updates)
 
@@ -556,6 +623,18 @@ Chain: `$array: "filter"` → `$array: "search"` → `$array: "slice"` for filte
 
 Inside repeated elements: `$item`, `$index`, `$bindItem` access current item.
 
+Repeated rows can opt into horizontal/wrapping layout without changing the child primitive:
+
+```json
+"repeat": {
+  "source": { "$state": "/filters" },
+  "key": "id",
+  "layout": { "direction": "horizontal", "gap": 8, "wrap": true }
+}
+```
+
+For grouped repeats, group headers and footers remain vertical; `repeat.layout` applies only to each group's item row.
+
 ### Grouped Repeat
 
 **Client-side** (engine groups flat array): `groupBy: "category"`
@@ -855,7 +934,7 @@ Interceptors:
 "interceptors": { "logging": true, "timeout": { "ms": 15000 }, "retryOnError": { "maxRetries": 2, "statuses": [502, 503] } }
 ```
 
-Security: tokens NEVER in state (engine closure only). `$auth` blocks token/password fields. Auth headers only for `authDomains`. Credentials cleared after login. Rate limit: 5/min. Cross-tab sync automatic.
+Security: tokens NEVER in state (engine closure only). `$auth` blocks token/password fields. Auth headers are injected only for the host `apiBaseUrl` exact origin or explicit `authDomains`. Credentials cleared after login. Rate limit: 5/min. Cross-tab sync automatic.
 
 Custom JWT provider response mapping: `tokenPath`, `refreshTokenPath`, and `userPath` are dot paths against the full login/refresh response. `rolePath` and `rolesPath` use a compat dual contract: plain keys like `"role"` / `"roles"` resolve inside the extracted `userPath` object; dotted paths like `"user.role"` or `"data.user.role"` resolve against the full response. If no role or roles are found, Mythik uses `defaultRole` (`"user"` by default) and warns in development.
 
@@ -1167,7 +1246,7 @@ Reference: `"hover": { "$token": "motion.presets.hoverLift" }`
 
 ## Component Variants
 
-Token-driven styling. Define in `tokens.components.{type}.{variant}`:
+Token-driven styling. **Use this before copying the same style block into multiple elements.** Define in `tokens.components.{type}.{variant}` and reference it from `props.variant`:
 
 ```json
 "tokens": {
@@ -1184,7 +1263,9 @@ Token-driven styling. Define in `tokens.components.{type}.{variant}`:
 ```
 Usage: `{ "type": "button", "props": { "label": "Save", "variant": "primary" } }`
 `$path` references (`$colors.primary`) resolve against active tokens — dark mode works automatically.
-Element-level style/hover overrides variant (variant is base, element is override). Supports: `style`, `hover`, `active`, `focus`, `transition`.
+Element-level style/hover overrides variant (variant is base, element is override). Supports: `style`, `hover`, `active`, `focus`, `transition`.
+
+Important boundary: variants are for primitive visual slots. They do **not** carry arbitrary primitive props such as `table.headerStyle`, `table.rowStyle`, `columns`, or action bindings. For prop-bearing reusable patterns, define an AppSpec `templates` entry and use `$prop` to pass through data/columns/actions. Example: use `tokens.components.box.tableCard` for card styling, but use an `ops-table` template when several tables need the same `headerStyle` + `rowStyle` chrome. For composed filter chips (`touchable` + `text`), put static shared styling in variants and keep state/item-specific active colors on the element.
 
 ## Skeleton & Export
 
@@ -1401,8 +1482,8 @@ When the framework changes the schema in a future version, this section will gai
 28. loginScreen always accessible — prevents redirect loops
 29. Login renders fullscreen (no layout) — appears automatically when not authenticated
 30. Login paths: `/screens/login/...` not `/form/...` — clears on logout with statePolicy reset
-31. Auth headers auto-injected for `authDomains` — no manual headers in fetch
-32. Use `variant` prop for component styling — don't copy style objects
+31. Auth headers auto-injected for `apiBaseUrl` exact-origin framework URLs and explicit `authDomains` hosts — no manual headers in fetch
+32. Use `variant` prop for reusable primitive styling — don't copy style objects; put `variant` inside `props`
 33. `$path` references in variants resolve with dark mode automatically
 34. Use `mythik push` for spec creation — no seed scripts
 35. AppSpec patches use `/layout/elements/` not `/elements/`
@@ -1437,11 +1518,11 @@ When the framework changes the schema in a future version, this section will gai
 64. Custom element black-box boundary — consumer's instance-level `animations`, `hover`, `active`, `focus`, `motion`, `style`, `visible`, and `key` apply to the OUTER primitive only. Inner primitives are the author's domain and are not reachable from the consumer. Identity cascade (rule 63 / cascade level 1) still reaches inner primitives; consumer cannot override them directly
 65. `$prop` is nearest-enclosing-custom-element-scoped — inside a custom element's render tree, `$prop` resolves against THAT element's merged props. Nesting a custom element inside another pushes a new prop context; the outer's props are shadowed, not merged. Pass values explicitly via prop declarations when nested access is needed
 66. `$children` marker in custom element render trees — authors write `"$children"` as a string item in their render tree `children` array to mark where consumer children are inserted during expansion. Multiple markers each splice the full consumer children. Same slotting semantics as spec templates
-67. `variant` is a PROP — place it inside `props`, never as a top-level element field. Applies to built-in primitives and Layer 3 custom elements alike: `{ "type": "stat-card", "props": { "variant": "primary", ... } }`. Top-level `variant` is silently ignored (the renderer reads `props.variant` only). Consumer may drive it dynamically via an expression: `"variant": { "$switch": { "$state": "/filter/recordType" }, "cases": { "1": "active" }, "default": "inactive" }`
+67. `variant` is a PROP — place it inside `props`, never as a top-level element field. Applies to built-in primitives and Layer 3 custom elements alike: `{ "type": "stat-card", "props": { "variant": "primary", ... } }`. Top-level `variant` is silently ignored (the renderer reads `props.variant` only). Consumer may drive it dynamically via an expression. Variants are style/interaction slots only; use templates/custom elements when the reusable pattern must carry props like table `headerStyle`/`rowStyle` or composed children.
 68. Custom elements may expose action-chain props — author declares a prop (e.g. `onSelect`, type `"array"`) and the render tree's `on:<event>` references it as `{ "$prop": "onSelect" }`. Consumers supply the full action array as the prop value; inner `$state` / `$template` / `$item` inside those actions resolve at press time with the current state (not at render time). Enables tabs, menu items, and similar patterns where the consumer owns the action chain
 69. Never use `$row` literal — there is no `$row` expression handler. Read row data via `$state: '/ui/selectedRow/<key>'` (framework writes clicked row before column action dispatch).
 70. Never combine `crud: {}` with `endpoint.path` ending in `/:id`. CRUD operations auto-append `/:id` to PUT/DELETE routes. Declaring `path: '/api/x/:id'` produces `/api/x/:id/:id`.
-71. Never include `:port` in `auth.authDomains[]` entries. The matcher uses `URL.hostname` for comparison — ports are silently stripped, leading to apparent matches that don't actually match.
+71. Prefer `MythikApp apiBaseUrl` for the app's own backend. Relative runtime URLs (`/api/...`) resolve against that base and inherit auth only for the exact base origin when `authDomains` is omitted or empty. Providing `authDomains` disables the automatic `apiBaseUrl` origin allowlist; list every trusted absolute host explicitly. Never include `:port` in `auth.authDomains[]` entries because that matcher uses hostnames.
 72. `spatial-map` is the generic SVG/data-first primitive for floor plans, seating maps, parking maps, warehouse layouts, hospital beds, and similar spatial workflows. JSON `onItemPress` actions write item context to `/ui/selectedSpatialItem` before lazy dispatch. Compose domain menus/drawers/modals externally; do not encode restaurant-specific behavior into the primitive. Use `{ "$state": "/path" }` expressions for dynamic `items`, `zones`, `mode`, and `statusStyles`; do not invent `*Path` prop aliases.
 73. For `spatial-map` editing, use `editPolicy` for movement rules and `onItemChange` for persistence. Do not use `interactionPolicy` for drag/keyboard movement. In JSON specs, persist moved items with `$array: "replace"` reading from `/ui/spatialItemChange` or the configured `itemChangePath`; use plain `setState` for non-undoable screens and wrap the same value in `editorCommit` for undoable editors.
 74. For JSON-created client-side item ids, use `$uniqueId` with an explicit `source`, `field`, `prefix`, and optional `padding`. It is deterministic and scoped to the source array; use it for local/editor objects, not as a substitute for database primary keys when a backend owns identity.
@@ -1456,12 +1537,12 @@ When the framework changes the schema in a future version, this section will gai
 82. Use `editorSessions.<id>.persistence` plus `editorSave` for generic editor document persistence. The AI should not hand-compose `transaction` + `editorMarkSaved` for normal editor saves. `editorSave` captures the tracked paths snapshot, persists it through the host fetcher with URL-guard checks, and marks only the sent snapshot as saved after success. Failed saves keep `dirty: true` and expose save metadata under `/ui/editorSessions/<id>`.
 83. Use `navigation.editorSessionGuard` for generic unsaved-changes protection in app specs instead of hand-rolled JSON dirty checks. Configure `sessions`, render your own JSON modal from `/ui/navigationGuard/pending`, call `navigationGuardCancel`, `navigationGuardSaveAndProceed`, `navigationGuardProceed`, or `navigationGuardDiscardAndProceed`, and keep `pendingPath` under a consumer-owned `/ui/<segment>` path that does not collide with reserved framework paths. `navigationGuardSaveAndProceed` is the normal save-first UX for persisted editor sessions; `navigationGuardProceed` is a low-level non-destructive retry that only resumes after the pending editor sessions are already clean; use `navigationGuardDiscardAndProceed` when the user explicitly chooses to abandon unsaved tracked-path changes.
 84. In React apps without auth framework fetch, pass `fetcher` to `MythikApp` when editor sessions use `editorSave` or `navigationGuardSaveAndProceed`. Auth-enabled apps continue to use the framework fetch produced by auth interceptors. Do not route save-and-continue through `/ui/lastError` or a hand-composed fetch action; the editor session engine owns save metadata under `/ui/editorSessions/<id>`.
-85. For existing spec edits, the required AI loop is `mythik manifest` -> `mythik elements` -> `mythik patch --from-file` -> verify. Manifest tells you the structure; elements gives the exact JSON you are changing; patch is the validated write path. Do not skip directly to full-spec `pull`/rewrite/push for a local change, do not mutate DB rows manually, and do not call `SpecStore.save()` from app code. Use `push` for new specs or intentional full replacement only.
+85. For existing spec edits, the required AI loop is `mythik manifest` -> `mythik elements` -> `mythik patch --from-file --author` -> `mythik validate` -> verify. Manifest tells you the structure; elements gives the exact JSON you are changing; patch is the validated write path. Do not skip directly to full-spec `pull`/rewrite/push for a local change, do not mutate DB rows manually, and do not call `SpecStore.save()` from app code. Use `push` for new specs or intentional full replacement only; existing specs require explicit `--replace`.
 86. Mythik's AI documentation ships with the `mythik` npm package. Before generating or modifying specs, locate it with `mythik docs path` and start from `docs/llms.txt`, `docs/consumer/ai-context.md`, and `docs/wiki/compiled/README.md`. Use `mythik docs copy ./mythik-docs` when a project-local copy is easier to hand to an AI agent.
 87. DNA numeric seeds (`roundness`, `density`, `depth`, `formality`) are canonical `0–1` values. Generate `0.7`, not `70`. The runtime tolerates legacy `0–100` values by normalizing any numeric seed greater than `1` with `/100` during DNA derivation, including initial AppSpec load and runtime `updateTokens`.
 88. API query endpoints can combine `pagination: "offset"` with `scopeFilter`. For generated counts, Mythik applies the scope filter to the source query before `COUNT(*)`, so paginated totals remain tenant-scoped. Prefer generated counts. If a custom `endpoint.count` is truly needed with `scopeFilter`, 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. Use `:alias` for JOIN/subquery counts, and do not reference internal scope params directly.
 89. Transaction `confirm` failures from `fetch` preserve backend error details for `onError`. Read `/tx/error/message` for the best available message; when the backend returns `{ error: { code, message } }`, Mythik keeps that message, `code`, HTTP `status`, and raw `data` after rollback. Do not parse `/ui/lastError` from transaction specs.
-90. For SQL-backed stores and servers, use the generic `mythik/server` SQL boundary. Initialize tables with `mythik init-store --dialect <sqlserver|postgres|mysql|sqlite>` or inspect DDL with `--dry-run`; configure the CLI with `--store`, `--url`/`--filename`/SQL Server flags, or `MYTHIK_*` environment variables; and keep spec edits on the required `manifest -> elements -> patch --from-file -> validate` loop. Write custom API SQL in the selected dialect with Mythik named params (`@name`); Mythik does not translate custom SQL between dialects.
+90. For SQL-backed stores and servers, use the generic `mythik/server` SQL boundary. Initialize tables with `mythik init-store --dialect <sqlserver|postgres|mysql|sqlite>` or inspect DDL with `--dry-run`; configure the CLI with `--store`, `--url`/`--filename`/SQL Server flags, or `MYTHIK_*` environment variables; and keep spec edits on the required `manifest -> elements -> patch --from-file --author -> validate -> verify` loop. Write custom API SQL in the selected dialect with Mythik named params (`@name`); Mythik does not translate custom SQL between dialects.
 91. Event arrays may mix normal actions and transaction bindings. Mythik executes them sequentially and awaits each transaction before continuing. Use this when a flow needs a small action before or after an optimistic transaction; do not wrap a transaction inside another transaction phase.
 92. `$ref` and `$template` placeholders can read nested values from `$let` object bindings with dot notation, for example `{ "$ref": "user.name" }` or `${user.name}`. If a dotted `$ref` segment is missing, runtime throws an unknown `$ref` error rather than silently returning undefined.
 93. Use `params.skipIf` for a dispatch-time action guard when an action should be skipped but the surrounding action chain should continue. `skipIf` is resolved before other params and is removed before the action handler runs. Do not use `skipIf` as a substitute for form validation or transaction rollback.
@@ -1470,3 +1551,8 @@ When the framework changes the schema in a future version, this section will gai
 96. SQL adapters are optional peer dependencies, not installed-by-default runtime payload. Browser-only apps install `mythik mythik-react` without database drivers. SQL-backed stores/servers must install exactly one selected adapter: `mssql`, `pg`, `mysql2`, or `better-sqlite3`. SQLite uses native `better-sqlite3`; native-build helper warnings from that adapter are not Mythik runtime failures.
 97. Missing SQL adapter errors are actionable. The thrown `SqlDriverError` includes `packageName`, `installCommand`, and a message with the exact `npm install ...` command for the selected dialect.
 98. For native Expo apps, install renderer peer packages with `npx expo install react-native-svg react-native-reanimated react-native-worklets ...` 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. Keep `root` as a stable string element id; use `$platform` only inside localized props, style, children, or values. `$platform` matches exact platform keys first, then falls back from `ios`/`android` to `native`; it has no `default` key. Before using a primitive in native specs, check `REACT_NATIVE_PRIMITIVE_SUPPORT` or `getReactNativePrimitiveSupport` from `mythik-react-native`; native-milestone primitives should fail visibly instead of being treated as supported.
+99. Use Mythik Reveal before guessing about running-app behavior. Start `mythik reveal start`, wire the host `reveal` config in development, then inspect with `mythik reveal apps`, `context`, `current`, `screen`, or `element`. Reveal returns live renderer/environment/spec/state/diagnostics/events with redaction, so agents can diagnose runtime behavior from structured context instead of screenshots, stale pulled specs, or source-code assumptions. Never enable Reveal in production, never commit the token, and include/redact state paths deliberately.
+100. **Use Mythik Agent Context, Agent Protocol, and Sentinel for fresh AI agents**. Run `mythik agent init codex`, `mythik agent init claude`, or `mythik agent init all` to install project-local agent instructions. `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. Generate live project context with `mythik agent context --app <id> --include-screens --out .mythik/agent/context.md`. Existing stored specs stay on `manifest -> elements -> patch --from-file --author -> validate -> verify`. The active store is the source of truth; local spec files are drafts/snapshots/migrations/fixtures unless a file store is intentionally configured. Use TOON for large reads when supported, and use `mythik lint` for new local drafts, replacement files, bulk imports/migrations, and relevant consumer code changes. Mythik Sentinel runs from the CLI as advisory coaching: first project use reminds the agent to initialize instructions, repeated full replacement intent warns the agent back to patch-first edits, identical `push --replace` writes are skipped as `skipped: true`, and no spec contents or credentials are persisted in the Sentinel cache. Disable only with `MYTHIK_SENTINEL=off` for exceptional automation.
+101. `repeat.layout` controls repeated item rows (`direction`, `gap`, `wrap`). In grouped repeats, headers/footers remain vertical and the layout applies only to the group item row.
+102. `select` normalizes option identity for display: DB integer IDs and string option values match, `0` is a valid selected value, and null/undefined show the placeholder. Values emitted by existing `onChange` remain string-compatible.
+103. `text.on.press` is supported for inline interactive text. Web receives button semantics plus keyboard activation; React Native receives `accessibilityRole="button"`. Use `button` or `touchable` for primary/larger actions.