mythik 0.1.4 → 0.2.0

package/docs/consumer/reference-doc.md

@@ -34,18 +34,29 @@ mythik manifest <screen>
 # Get specific element details
 mythik elements <screen> <id1,id2,...>
 
-# Apply RFC 6902 patches
-mythik patch <screen> --from-file patch.json
+# Apply RFC 6902 patches
+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
 ```
@@ -72,15 +83,15 @@ Set the env var once per session: `export MYTHIK_API_KEY="your-key"`. The CLI re
 ### Patch Input: File vs Stdin
 
 **Preferred shell-safe path** - write patch JSON to a file:
-```bash
-mythik patch task-manager --from-file patch.json
-```
+```bash
+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 -
-```
+```bash
+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.
 
@@ -90,9 +101,9 @@ Inline JSON still works for tiny patches, but `--from-file` is preferred for any
 
 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
+```bash
+mythik elements task-manager btn,nav --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,33 +112,117 @@ 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 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
-Read:      mythik manifest <id> / mythik elements <id> ids / mythik pull <id>
-Modify:    mythik patch <id> --from-file patch.json
-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
-Tokens:    mythik tokens --dna '{"primary":"#0D9488"}' --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 --author <agent>
+Validate:  mythik validate <id>
+Delete:    mythik delete <id> --confirm
+Backup:    mythik pull <id> > backup.json
+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
 ```
 
 ### Push — Create New Screens
@@ -386,6 +481,7 @@ Resolves to different values based on the current platform (`web`, `ios`, `andro
 { "$platform": { "web": "layout-web", "native": "layout-native" } }
 { "$platform": { "web": "hover-card", "ios": "ios-card", "android": "android-card" } }
 ```
+If no key matches, `$platform` resolves to `undefined`; it does not support a `default` key. Keep top-level `root` as a stable string element id and use `$platform` only in localized props, style, children, or values.
 
 **Use with `$breakpoint`** — `$breakpoint` handles responsive layout (viewport width), `$platform` handles platform-specific techniques (CSS vs native components). They are complementary, not alternatives.
 
@@ -1989,7 +2085,7 @@ 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)
 
@@ -2008,7 +2104,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)
@@ -2973,7 +3069,7 @@ Mythik backgrounds use a structured `LayerBackground` model. Apps declare `token
 
 178. **`BackgroundLayer` + `BackgroundStack` components shipped for web and RN** — Web: `packages/react/src/background/` using CSS for solid/gradient/image + inline SVG for pattern/grain. RN: `packages/react-native/src/background/` using `react-native-svg` `SvgXml` for all layers + View for solid + Image for image. Accepts `LayerBackground` config OR recipe string name
 
-179. **`custom-svg` sanitized escape hatch** — When built-in patterns aren't enough, consumers pass SVG shape fragments via `{ kind: 'custom-svg', shapes: '<circle.../>', tileSize: 20 }`. `sanitizeSVGShapes` uses regex pre-strip + DOMPurify allowlist. Only circle/rect/path/line/polygon/polyline/ellipse/g/defs/gradients + geometric attrs survive. Cross-platform safe (isomorphic-dompurify)
+179. **`custom-svg` sanitized escape hatch** — When built-in patterns aren't enough, consumers pass SVG shape fragments via `{ kind: 'custom-svg', shapes: '<circle.../>', tileSize: 20 }`. `sanitizeSVGShapes` uses a platform-safe regex pre-strip plus a strict SVG tag/attribute allowlist, without DOM-only sanitizer dependencies. Only circle/rect/path/line/polygon/polyline/ellipse/g/defs/gradients plus geometric attrs survive.
 
 ---
 
@@ -3057,7 +3153,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** — Repository-preview implementation in `packages/react-native/src/animation/useShapeAnimations.ts`; it is not part of the supported npm publish surface yet. 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`).
 
@@ -3133,7 +3229,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).
 
@@ -3148,7 +3244,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.
 
@@ -3213,12 +3309,12 @@ 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`.
@@ -3226,3 +3322,6 @@ See `ai-context.md` for spec-gen anti-patterns the AI must NOT generate.
 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.
 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` install 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.

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,13 +9,15 @@ 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`.
-- React Native work is a repository preview track, not part of the supported npm publish surface yet.
+- 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.
 
@@ -23,8 +25,8 @@ Compiled from `docs/consumer/` into **327 atomic articles**. The wiki is optimiz
 
 - [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

package/docs/wiki/compiled/_inventory.md

@@ -910,6 +910,10 @@ Generated from article frontmatter and Sources sections. `docs/consumer` is the
 ## docs/consumer/ai-context.md
 
 - [[@action-apply-preset]] - `applyPreset` — apply curated DNA+Identity
+- [[@cli-reveal]] - `mythik reveal` - live runtime context
+- [[@cli-agent]] - `mythik agent` - project-local AI operating context
+- [[@concept-mythik-reveal]] - Mythik Reveal - live runtime context for AI agents
+- [[@concept-agent-context-protocol]] - Mythik Agent Context and Agent Protocol
 - [[@cli-existing-spec-edit-loop]] - Existing spec edit loop
 - [[@cli-overview]] - CLI overview - `mythik <command>`
 - [[@cli-patch]] - `mythik patch` - RFC 6902 patches
@@ -1415,11 +1419,11 @@ Generated from article frontmatter and Sources sections. `docs/consumer` is the
 - [[@cli-programmatic-api]] - Programmatic API — `mythik-cli/api`
 - [[@cli-push]] - `mythik push` — three approved write paths
 
-## docs/consumer/ai-context.md#cli-workflow
-
-- [[@cli-docs]] - `mythik docs` — bundled AI documentation
-- [[@cli-elements]] - `mythik elements` — inspect specific elements
-- [[@cli-manifest]] - `mythik manifest` — structural tree
+## docs/consumer/ai-context.md#cli-workflow
+
+- [[@cli-docs]] - `mythik docs` — bundled AI documentation
+- [[@cli-elements]] - `mythik elements` — inspect specific elements
+- [[@cli-manifest]] - `mythik manifest` — structural tree
 - [[@cli-overview]] - CLI overview - `mythik <command>`
 - [[@cli-patch]] - `mythik patch` - RFC 6902 patches
 - [[@cli-pull]] - `mythik pull` — export spec
@@ -1691,10 +1695,14 @@ Generated from article frontmatter and Sources sections. `docs/consumer` is the
 
 - [[@pattern-fetch-vs-datasources]] - Pattern — `fetch` vs `dataSources` decision
 
-## docs/consumer/reference-doc.md
-
-- [[@cli-existing-spec-edit-loop]] - Existing spec edit loop
-- [[@cli-overview]] - CLI overview - `mythik <command>`
+## docs/consumer/reference-doc.md
+
+- [[@cli-existing-spec-edit-loop]] - Existing spec edit loop
+- [[@cli-reveal]] - `mythik reveal` - live runtime context
+- [[@cli-agent]] - `mythik agent` - project-local AI operating context
+- [[@concept-mythik-reveal]] - Mythik Reveal - live runtime context for AI agents
+- [[@concept-agent-context-protocol]] - Mythik Agent Context and Agent Protocol
+- [[@cli-overview]] - CLI overview - `mythik <command>`
 - [[@cli-patch]] - `mythik patch` - RFC 6902 patches
 - [[@cli-toon]] - `--toon` - token-efficient format
 - [[@concept-auth-config]] - AppSpec auth config
@@ -2472,11 +2480,11 @@ Generated from article frontmatter and Sources sections. `docs/consumer` is the
 
 - [[@concept-skeleton-auto]] - Auto-skeleton — zero-config loading state
 
-## docs/consumer/reference-doc.md#cli--spec-modification-via-mythik-cli
-
-- [[@cli-docs]] - `mythik docs` — bundled AI documentation
-- [[@cli-overview]] - CLI overview - `mythik <command>`
-- [[@cli-pull]] - `mythik pull` — export spec
+## docs/consumer/reference-doc.md#cli--spec-modification-via-mythik-cli
+
+- [[@cli-docs]] - `mythik docs` — bundled AI documentation
+- [[@cli-overview]] - CLI overview - `mythik <command>`
+- [[@cli-pull]] - `mythik pull` — export spec
 
 ## docs/consumer/reference-doc.md#cli-token-inspection
 

package/docs/wiki/compiled/_lint.md

@@ -1,10 +1,10 @@
-# Lint Report - Event Binding Guard Refresh
+# Lint Report - Mythik Agent Context Refresh
 
-Validation of cross-references, stale public references, and generated wiki shape after refreshing the compiled wiki delta from `docs/consumer` on 2026-05-09.
+Validation of cross-references, stale public references, and generated wiki shape after refreshing the compiled wiki delta from `docs/consumer` on 2026-05-21.
 
 ## Broken Cross-References
 
-**0 broken wiki links** across compiled wiki files.
+**0 broken wiki links** across compiled wiki files.
 
 ## Stale / Private Reference Scan
 
@@ -19,28 +19,32 @@ Validation of cross-references, stale public references, and generated wiki shap
 
 ## Article Counts
 
-- Total markdown files in `compiled`: **333**
-- Generated article files, excluding `README.md` and `_*.md`: **327**
+- Total markdown files in `compiled`: **337**
+- Generated article files, excluding `README.md` and `_*.md`: **331**
 - Migration pages removed: **yes** (`migration-*.md` no longer publish)
 - Metadata folder publish status: **excluded**
 
-## Key Refresh Additions
-
-- Dotted `$let` binding reads for `$ref` and `$template`
-- Mixed event arrays containing actions plus transactions
-- `params.skipIf` dispatch-time action guards
-- Optional SQL adapter dependency wording
-- Generic SQL store / driver package-layout pages
-- `concept-public-package-names`
-- `cli-existing-spec-edit-loop`
-- `primitive-spatial-map`
+## Key Refresh Additions
+
+- Dotted `$let` binding reads for `$ref` and `$template`
+- Mixed event arrays containing actions plus transactions
+- `params.skipIf` dispatch-time action guards
+- Optional SQL adapter dependency wording
+- Generic SQL store / driver package-layout pages
+- `concept-public-package-names`
+- `cli-existing-spec-edit-loop`
+- `primitive-spatial-map`
 - `concept-spatial-map-editor`
 - `concept-spatial-map-zones`
 - `concept-editor-sessions`
 - `concept-editor-commit`
 - `concept-editor-save`
-- `concept-navigation-dirty-guard`
-- `cli-docs`
+- `concept-navigation-dirty-guard`
+- `cli-docs`
+- `concept-mythik-reveal`
+- `cli-reveal`
+- `concept-agent-context-protocol`
+- `cli-agent`
 
 ## Tooling
 

package/docs/wiki/compiled/antipattern-store-save-bypass.md

@@ -24,17 +24,22 @@ await store.save('my-screen', specObject);   // BAD — no validation
 ## Right — three approved paths
 
 ```ts
-// Programmatic (best for tooling/CI):
-import { runPush } from 'mythik-cli/api';
-await runPush({ id: 'my-screen', spec: specObject });
+// Programmatic (best for tooling/CI):
+import { runPush } from 'mythik-cli/api';
+await runPush('my-screen', JSON.stringify(specObject), {
+  store,
+  json: true,
+  force: false,
+  author: 'agent-name'
+});
 ```
 
 ```bash
-# Shell:
-mythik push my-screen --from-file spec.json
-
-# Bulk:
-mythik push --from-dir ./specs/
+# Shell:
+mythik push my-screen --from-file spec.json --author <agent>
+
+# Bulk:
+mythik push --from-dir ./specs/ --author <agent>
 ```
 
 ## Why