mythik 0.1.5 → 0.2.0

package/docs/wiki/compiled/cli-agent.md

@@ -0,0 +1,70 @@
+---
+id: cli-agent
+title: `mythik agent` - project-local AI operating context
+kind: cli
+sources: [docs/consumer/ai-context.md#cli-workflow, docs/consumer/reference-doc.md#rule-297]
+---
+
+# `mythik agent`
+
+`mythik agent` installs and refreshes project-local instructions for AI
+agents working in a Mythik project.
+
+Use it when a fresh agent joins a project, before asking the agent to
+create or modify specs.
+
+## Commands
+
+```bash
+mythik agent init codex
+mythik agent init claude
+mythik agent init all
+mythik agent context --app <app-id> --include-screens --out .mythik/agent/context.md
+```
+
+`agent init` creates thin adapter files such as `AGENTS.md` and
+`CLAUDE.md`, plus shared instructions under `.mythik/agent/`.
+
+`agent context` generates the project-specific operating map from the
+active Mythik store. It can include AppSpec structure, screens, API
+specs, commands, storage configuration, and safety rules.
+
+## Required agent loop
+
+Existing stored specs stay on:
+
+```text
+manifest -> elements -> patch --from-file --author -> validate -> verify
+```
+
+`push` is for new specs or intentional full replacement. Existing
+specs require explicit `--replace`. Persisted writes require
+`--author <name>` for versioned stores or explicit
+`--allow-unversioned` for intentionally unversioned stores.
+
+## Source of truth
+
+The active Mythik store is the source of truth. Local spec files are
+drafts, snapshots, migrations, backups, or fixtures unless the project
+intentionally uses a file store.
+
+Use `mythik lint` for local drafts, replacement files, bulk
+imports/migrations, and relevant consumer code changes. Use TOON for
+large reads when supported.
+
+## Related articles
+
+- [[@concept-agent-context-protocol]]
+- [[@cli-existing-spec-edit-loop]]
+- [[@cli-manifest]]
+- [[@cli-elements]]
+- [[@cli-patch]]
+- [[@cli-push]]
+- [[@cli-toon]]
+- [[@cli-lint]]
+- [[@cli-reveal]]
+
+## Sources
+
+- `docs/consumer/ai-context.md`
+- `docs/consumer/reference-doc.md`

package/docs/wiki/compiled/cli-existing-spec-edit-loop.md

@@ -14,11 +14,12 @@ Required loop:
 1. `mythik manifest <id>` - inspect the current structure and identify candidate element IDs.
 2. `mythik elements <id> <ids>` - inspect only the exact nodes and nearby containers that will change.
 3. Write a small RFC 6902 patch file.
-4. `mythik patch <id> --from-file patch.json` - apply through the validated CLI path.
-5. Re-run `manifest` or `elements` to verify the changed surface.
-
-`pull` is for backup, migration, review, or full-document work. `push` is for new specs or intentional full replacement. Routine edits should not replace whole screens.
-
-Never edit database rows directly and never call `SpecStore.save()` from app code. Those bypass validation.
-
-Related: [[@cli-manifest]], [[@cli-elements]], [[@cli-patch]], [[@antipattern-store-save-bypass]].
+4. `mythik patch <id> --from-file patch.json --author <agent>` - apply through the validated, versioned CLI path.
+5. Run `mythik validate <id>`.
+6. Re-run `manifest` or `elements` to verify the changed surface.
+
+`pull` is for backup, migration, review, or full-document work. `push` is for new specs or intentional full replacement with explicit `--replace`. Routine edits should not replace whole screens.
+
+Never edit database rows directly and never call `SpecStore.save()` from app code. Those bypass validation.
+
+Related: [[@cli-manifest]], [[@cli-elements]], [[@cli-patch]], [[@cli-agent]], [[@antipattern-store-save-bypass]].

package/docs/wiki/compiled/cli-overview.md

@@ -16,17 +16,20 @@ forms are documented in [[@cli-push]] and rule 248.
 mythik init   --store supabase --url <url> --key $MYTHIK_API_KEY  # configure
 mythik docs path                                                  # locate bundled AI docs
 mythik docs copy ./mythik-docs                                    # copy docs for an AI agent
-mythik push <screen>                                              # create/replace
+mythik push <screen> --from-file spec.json --author <name>        # create
+mythik push <screen> --from-file spec.json --replace --author <name> # replace
 mythik pull <screen>                                              # export to stdout
 mythik manifest <screen>                                          # structural tree
 mythik elements <screen> <id1,id2,...>                            # element details
-mythik patch <screen> --from-file patch.json                      # RFC 6902
+mythik patch <screen> --from-file patch.json --author <name>      # RFC 6902
 mythik validate <screen>                                          # validate
 mythik delete <screen> --confirm                                  # delete (requires --confirm)
 mythik tokens --dna '{"primary":"#0D9488"}' --json                # inspect tokens
 mythik contract --app <id> --api <id>                             # cross-validate
 mythik lint [--from-file path | --from-dir folder]                # detect anti-patterns
-mythik history <screen>                                           # version history
+mythik history <screen>                                           # version history
+mythik agent init codex                                           # install agent protocol
+mythik agent context --app <id> --include-screens                 # generate agent context
 ```
 
 ## Common flags
@@ -48,8 +51,9 @@ Manifest output adapts per doctype. See [[@cli-app-spec]].
 1. **`docs path`** - locate the installed AI docs
 2. **`manifest`** - see structure, decide what to modify
 3. **`elements`** - inspect specific elements
-4. **`patch --from-file patch.json`** - apply surgical changes
-5. **`manifest`** - verify
+4. **`patch --from-file patch.json --author <name>`** - apply surgical changes
+5. **`validate`** - check the stored result
+6. **`manifest`** - verify
 
 ## Related concepts
 
@@ -68,8 +72,9 @@ Manifest output adapts per doctype. See [[@cli-app-spec]].
 - [[@cli-lint]]
 - [[@cli-history]]
 - [[@cli-versioning-author]]
-- [[@cli-app-spec]]
-- [[@cli-programmatic-api]]
+- [[@cli-app-spec]]
+- [[@cli-programmatic-api]]
+- [[@cli-agent]]
 
 ## Sources (raw)
 

package/docs/wiki/compiled/cli-patch.md

@@ -15,22 +15,22 @@ other shell-sensitive strings.
 
 ### Preferred path - 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. Intentional stdin
 still works via `--from-file -` or a pipe without `--from-file`:
 
 ```bash
-cat patch.json | mythik patch task-manager
-mythik patch task-manager --from-file -
+cat patch.json | mythik patch task-manager --author <agent>
+mythik patch task-manager --from-file - --author <agent>
 ```
 
 ### Inline
 
 ```bash
-mythik patch task-manager '[{"op":"replace","path":"/elements/title/props/content","value":"New Title"}]'
+mythik patch task-manager '[{"op":"replace","path":"/elements/title/props/content","value":"New Title"}]' --author <agent>
 ```
 
 Inline remains valid for tiny patches, but file input is the canonical
@@ -55,7 +55,7 @@ Patch input autodetects format: JSON (starts with `[` or `{`) or TOON
 (everything else):
 
 ```bash
-mythik patch task-manager --from-file patch.toon
+mythik patch task-manager --from-file patch.toon --author <agent>
 ```
 
 See [[@cli-toon]].
@@ -66,9 +66,11 @@ Use `/layout/elements/...`, NOT `/elements/...`. See [[@cli-app-spec]].
 
 ## Versioning
 
-`--author <name>` records history when the resolved store supports
-`saveVersion`. JSON/TOON success output includes `versioned: boolean`
-and `version?: number`. See [[@cli-versioning-author]].
+`--author <name>` is the normal persisted-write path. It records
+history when the resolved store supports `saveVersion`. JSON/TOON
+success output includes `versioned: boolean` and `version?: number`.
+Use `--allow-unversioned` only for intentionally unversioned stores.
+See [[@cli-versioning-author]].
 
 ## Related concepts
 
@@ -77,7 +79,8 @@ and `version?: number`. See [[@cli-versioning-author]].
 - [[@cli-app-spec]]
 - [[@cli-versioning-author]]
 - [[@cli-history]]
-- [[@cli-programmatic-api]] - `runPatch`
+- [[@cli-programmatic-api]] - `runPatch`
+- [[@concept-agent-context-protocol]]
 
 ## Sources (raw)
 

package/docs/wiki/compiled/cli-programmatic-api.md

@@ -33,13 +33,23 @@ import {
 
 ## Example
 
-```ts
-import { runPush } from 'mythik-cli/api';
-
-const result = await runPush({ id: 'my-screen', spec: doc, json: true });
-const data = JSON.parse(result.output);
-console.log(data.elementCount, data.warnings);
-```
+```ts
+import { readFile } from 'node:fs/promises';
+import { runPush } from 'mythik-cli/api';
+
+const input = await readFile('spec.json', 'utf8');
+const result = await runPush('my-screen', input, {
+  store,
+  json: true,
+  force: false,
+  author: 'agent-name'
+});
+const data = JSON.parse(result.output);
+console.log(data.elementCount, data.warnings);
+```
+
+Programmatic callers provide the same `SpecStore` they would configure
+for the CLI.
 
 ## `PushResult` extension
 

package/docs/wiki/compiled/cli-push.md

@@ -14,13 +14,14 @@ spec writes** — `SpecStore.save()` is `@internal`.
 
 ### Shell — single file
 
-```bash
-mythik push <id> --from-file spec.json
-mythik push <id> < spec.json          # stdin
-cat spec.json | mythik push <id>      # pipe
-mythik push <id> <<'EOF'              # heredoc
-{ ... }
-EOF
+```bash
+mythik push <id> --from-file spec.json --author <agent>
+mythik push <id> --from-file spec.json --replace --author <agent>
+mythik push <id> --from-file - --author <agent>          # stdin
+cat spec.json | mythik push <id> --author <agent>        # pipe
+mythik push <id> <<'EOF'              # heredoc
+{ ... }
+EOF
 ```
 
 `--from-file` is **cross-shell ergonomic** for any spec containing
@@ -30,7 +31,7 @@ EOF
 ### Bulk — directory
 
 ```bash
-mythik push --from-dir ./specs/
+mythik push --from-dir ./specs/ --author <agent>
 ```
 
 Sequential per-file push of every `*.json`. **Continue-on-error**:
@@ -39,23 +40,33 @@ recovers by fixing failures and re-running.
 
 ### Programmatic — `mythik-cli/api`
 
-```ts
-import { runPush, type PushOptions, type PushResult } from 'mythik-cli/api';
-
-const result = await runPush({ id: 'my-screen', spec: doc, json: true });
-const data = JSON.parse(result.output) as PushResult;
-```
-
-Same code path as the binary, no shell. Pass `json: true` to receive
-structured `PushResult`.
+```ts
+import { readFile } from 'node:fs/promises';
+import { runPush, type PushOptions, type PushResult } from 'mythik-cli/api';
+
+const input = await readFile('spec.json', 'utf8');
+const result = await runPush('my-screen', input, {
+  store,
+  author: 'agent',
+  json: true,
+  force: false
+} satisfies PushOptions);
+const data = JSON.parse(result.output) as PushResult;
+```
+
+Same code path as the binary, no shell. Provide the same `SpecStore`
+you would configure the CLI with. Pass `json: true` to receive
+structured `PushResult`.
 
 ## Input precedence
 
 - `--from-file <path>` wins over ambient non-TTY stdin.
 - Intentional stdin remains supported via `--from-file -` or by piping without `--from-file`.
-- `--from-file` plus a positional argument is still a conflict.
-- `--from-dir` is mutually exclusive with `<screen>` argument and `--from-file`.
-- Conflicts produce explicit error + exit 1.
+- `--from-file` plus a positional argument is still a conflict.
+- `--from-dir` is mutually exclusive with `<screen>` argument and `--from-file`.
+- Conflicts produce explicit error + exit 1.
+- Existing specs require explicit `--replace`.
+- Persisted writes require `--author <name>` or intentional `--allow-unversioned`.
 
 ## Validation behavior
 
@@ -67,8 +78,8 @@ structured `PushResult`.
 
 ## Versioning
 
-`--author <name>` activates `VersionedSpecStore.saveVersion()`. See
-[[@cli-versioning-author]].
+`--author <name>` activates `VersionedSpecStore.saveVersion()` when
+available. See [[@cli-versioning-author]].
 
 ## Constraints / Anti-patterns
 
@@ -81,8 +92,9 @@ structured `PushResult`.
 - [[@cli-config]]
 - [[@cli-versioning-author]]
 - [[@cli-programmatic-api]]
-- [[@cli-lint]]
-- [[@antipattern-store-save-bypass]]
+- [[@cli-lint]]
+- [[@antipattern-store-save-bypass]]
+- [[@concept-agent-context-protocol]]
 
 ## Sources (raw)
 

package/docs/wiki/compiled/cli-reveal.md

@@ -0,0 +1,64 @@
+---
+id: cli-reveal
+title: `mythik reveal` - live runtime context
+kind: cli
+sources: [docs/consumer/ai-context.md#mythik-reveal-live-context-for-ai-agents, docs/consumer/reference-doc.md#mythik-reveal--live-runtime-context-for-ai-agents]
+---
+
+# `mythik reveal`
+
+`mythik reveal` connects the CLI to a running Mythik app through a
+local Reveal Bridge.
+
+Start the 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 app's development-only `reveal` config.
+
+## Query commands
+
+```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
+```
+
+`apps` lists connected sessions. `context` asks for the full app
+context. `current`, `screen`, and `element` scope the request.
+
+For Android emulator smoke, reverse the bridge port before loading the
+native app:
+
+```bash
+adb reverse tcp:17373 tcp:17373
+```
+
+## Agent rule
+
+If a running Mythik app misbehaves and Reveal is available, the agent
+should inspect Reveal context before proposing a patch. This avoids
+debugging from stale pulled specs, screenshots, or source-code
+assumptions.
+
+## Related articles
+
+- [[@concept-mythik-reveal]]
+- [[@cli-existing-spec-edit-loop]]
+- [[@cli-docs]]
+
+## Sources
+
+- `docs/consumer/ai-context.md`
+- `docs/consumer/reference-doc.md`

package/docs/wiki/compiled/cli-toon.md

@@ -12,9 +12,9 @@ TOON is a token-efficient format. Patch input autodetects JSON vs TOON;
 
 ## Use on `elements` and `patch`
 
-```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 input autodetect
@@ -24,15 +24,15 @@ mythik patch task-manager --from-file patch.toon --toon
 
 JSON input:
 
-```bash
-mythik patch task-manager --from-file patch.json
-```
+```bash
+mythik patch task-manager --from-file patch.json --author <agent>
+```
 
 TOON input:
 
-```bash
-mythik patch task-manager --from-file patch.toon
-```
+```bash
+mythik patch task-manager --from-file patch.toon --author <agent>
+```
 
 ## Related concepts
 

package/docs/wiki/compiled/cli-versioning-author.md

@@ -5,18 +5,18 @@ kind: concept
 sources: [docs/consumer/reference-doc.md#rules-92-110]
 ---
 
-# `--author` flag
-
-`mythik push` and `mythik patch` **without `--author`** write directly to
-the `screens` table with NO version history. **With `--author <name>`**,
-they use `VersionedSpecStore` which writes to BOTH `screens` AND
-`screen_versions`, enabling `history`, `diff`, and `rollback` commands.
+# `--author` flag
+
+`mythik push` and `mythik patch` with `--author <name>` use
+`VersionedSpecStore` when the resolved store supports it. That writes
+to BOTH `screens` AND `screen_versions`, enabling `history`, `diff`,
+and `rollback` commands.
 
 ## Usage
 
 ```bash
-mythik push my-screen --author alice --description "Initial layout"
-mythik patch screen-id --from-file patch.json --author alice --description "Fixed layout"
+mythik push my-screen --from-file spec.json --author alice --description "Initial layout"
+mythik patch screen-id --from-file patch.json --author alice --description "Fixed layout"
 ```
 
 The version row includes:
@@ -24,12 +24,15 @@ The version row includes:
 - `source_type` — `push` or `patch`
 - `description` — optional, via `--description`
 
-**Always use `--author` during development** (rule 110).
-
-## Without `--author`
-
-Commands work as before (no versioning). Useful for git-backed workflows
-where `git log` IS the audit trail.
+**Always use `--author` during development** (rule 110).
+
+## Without `--author`
+
+Persisted writes are rejected unless `--allow-unversioned` is explicit.
+Use `--allow-unversioned` only when the project intentionally has no
+versioned store, such as a file-store smoke test.
+
+Existing full-spec replacement also requires explicit `--replace`.
 
 ## Patch output metadata
 
@@ -51,7 +54,8 @@ migration script needed.
 - [[@concept-storage-table-versions]]
 - [[@concept-rollback]]
 - [[@concept-promote-gate]]
-- [[@pattern-git-vs-db-versioning]]
+- [[@pattern-git-vs-db-versioning]]
+- [[@concept-agent-context-protocol]]
 
 ## Sources (raw)
 

package/docs/wiki/compiled/concept-agent-context-protocol.md

@@ -0,0 +1,76 @@
+---
+id: concept-agent-context-protocol
+title: Mythik Agent Context and Agent Protocol
+kind: concept
+sources: [docs/consumer/ai-context.md#required-edit-loop-for-existing-specs, docs/consumer/ai-context.md#rule-100, docs/consumer/reference-doc.md#rule-297]
+---
+
+# Mythik Agent Context and Agent Protocol
+
+Mythik Agent Context is the project-specific operating map an AI agent
+reads before editing a Mythik app.
+
+Agent Protocol is the mandatory write discipline that keeps the agent
+on the validated Mythik workflow instead of drifting into full-spec
+rewrites, direct database edits, or stale local files.
+
+## Why it exists
+
+Fresh AI agents often know how to edit JSON but not how Mythik wants
+stored specs to be changed. The protocol makes the correct behavior
+local, explicit, and repeatable:
+
+- inspect stored structure with `manifest`
+- inspect exact target nodes with `elements`
+- write a small RFC 6902 patch file
+- apply with `patch --from-file --author`
+- validate
+- verify with `manifest`, `elements`, browser smoke, or Reveal
+
+## Store-backed source of truth
+
+For DB-backed Mythik projects, the active store is the source of
+truth. Local spec files are drafts, snapshots, migrations, backups, or
+fixtures. They are not the canonical document unless the project has
+intentionally configured a file store.
+
+This prevents the common failure where an agent patches the database
+correctly, then overwrites the result from an older local `spec.json`.
+
+## Strict write intent
+
+Persisted writes are strict by default:
+
+- Existing full-spec replacement requires `--replace`.
+- Normal persisted writes use `--author <name>`.
+- `--allow-unversioned` is only for intentionally unversioned stores.
+
+These guardrails preserve version history and make destructive writes
+explicit.
+
+## Relationship to Reveal
+
+Agent Protocol edits stored specs. Mythik Reveal inspects the running
+app.
+
+Use both:
+
+- `manifest` / `elements` / `patch` to change the stored contract.
+- `reveal current`, `reveal screen`, or `reveal element` to understand
+  runtime state, resolved props, warnings, render errors, and events
+  before guessing.
+
+## Related articles
+
+- [[@cli-agent]]
+- [[@cli-existing-spec-edit-loop]]
+- [[@cli-versioning-author]]
+- [[@cli-reveal]]
+- [[@concept-mythik-reveal]]
+- [[@concept-source-of-truth-references]]
+- [[@pattern-push-vs-patch]]
+
+## Sources
+
+- `docs/consumer/ai-context.md`
+- `docs/consumer/reference-doc.md`

package/docs/wiki/compiled/concept-mythik-reveal.md

@@ -0,0 +1,63 @@
+---
+id: concept-mythik-reveal
+title: Mythik Reveal - live runtime context for AI agents
+kind: concept
+sources: [docs/consumer/ai-context.md#mythik-reveal-live-context-for-ai-agents, docs/consumer/reference-doc.md#mythik-reveal--live-runtime-context-for-ai-agents]
+---
+
+# Mythik Reveal
+
+Mythik Reveal lets a running Mythik app expose its live contract, state,
+actions, diagnostics, environment, and render errors as structured
+context for AI agents.
+
+Reveal is for runtime truth. It complements the normal spec workflow:
+
+- `manifest` and `elements` read stored specs.
+- `lint` and `validate` check candidate specs.
+- `patch --from-file` writes validated changes.
+- Reveal reads the app that is actually running.
+
+Use Reveal before guessing when a runtime symptom is visible: a button
+does not fire, a screen renders the wrong branch, a dataSource fails,
+a render error appears, or React Native behaves differently from web.
+
+## What Reveal exposes
+
+Reveal context can include:
+
+- renderer and platform (`react`, `react-native`, `android`, etc.)
+- app and environment metadata
+- mounted spec summary
+- selected screen or element context
+- resolved public props and element dependency paths
+- selected state paths, with redaction
+- render errors and warnings
+- action, transaction, dataSource, navigation, lifecycle, and render
+  error events
+- patch target metadata when available
+- redaction and truncation metadata
+
+## Security contract
+
+Reveal is development tooling.
+
+- Do not enable it in production.
+- Do not commit or publish Reveal tokens.
+- Use narrow `includeStatePaths`.
+- Redact `/auth`, `/secrets`, tokens, passwords, API keys, and session
+  values.
+- Memoize React and React Native `reveal` config objects so bridge
+  clients stay stable across renders.
+
+## Related articles
+
+- [[@cli-reveal]]
+- [[@cli-existing-spec-edit-loop]]
+- [[@concept-debugging-runtime-pointers]]
+- [[@concept-render-error-visibility]]
+
+## Sources
+
+- `docs/consumer/ai-context.md`
+- `docs/consumer/reference-doc.md`

package/docs/wiki/compiled/concept-package-layout.md

@@ -13,12 +13,13 @@ sources: [docs/consumer/ai-context.md, docs/consumer/WHERE-TO-LOOK.md]
 |---|---|
 | `mythik` | Browser-safe core. State, expressions, validation, renderer engine, design, auth, data, security, and browser-safe spec stores |
 | `mythik/server` | Node-only spec stores, SQL drivers, and SQL DDL helpers: `FileSpecStore`, `SqlSpecStore`, `SqlVersionedSpecStore`, `SqlEnvironmentStore`, `createSqlDriver`, `getSqlStoreDdl`, and SQL Server compatibility stores |
-| `mythik-react` | React host, renderer, and web primitives |
-| `mythik-cli` | CLI package; installs the `mythik` command |
-| `mythik-cli/api` | Programmatic CLI API: `runPush`, `runPatch`, `runLint`, `parsePatchInput`, and types |
-| `mythik-server` | Express server runtime for ApiSpecs |
-
-React Native work lives in the repository as a preview track and is not part of the supported npm publish surface yet.
+| `mythik-react` | React host, renderer, and web primitives |
+| `mythik-react-native` | React Native and Expo renderer, public preview, with an explicit primitive support matrix |
+| `mythik-cli` | CLI package; installs the `mythik` command |
+| `mythik-cli/api` | Programmatic CLI API: `runPush`, `runPatch`, `runLint`, `parsePatchInput`, and types |
+| `mythik-server` | Express server runtime for ApiSpecs |
+
+`mythik-react-native` is published on the same version line as the rest of Mythik, but remains a public preview while native primitive parity and smoke coverage continue to expand.
 
 ## Browser vs server core entries