mythik 0.1.5 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/README.md +96 -36
  2. package/dist/actions/dispatcher.d.ts +2 -0
  3. package/dist/actions/dispatcher.d.ts.map +1 -1
  4. package/dist/actions/dispatcher.js +11 -2
  5. package/dist/actions/dispatcher.js.map +1 -1
  6. package/dist/actions/transaction-engine.d.ts +10 -0
  7. package/dist/actions/transaction-engine.d.ts.map +1 -1
  8. package/dist/actions/transaction-engine.js +13 -1
  9. package/dist/actions/transaction-engine.js.map +1 -1
  10. package/dist/agent-context/inventory.d.ts +62 -0
  11. package/dist/agent-context/inventory.d.ts.map +1 -0
  12. package/dist/agent-context/inventory.js +248 -0
  13. package/dist/agent-context/inventory.js.map +1 -0
  14. package/dist/contract/extractor.js +3 -0
  15. package/dist/contract/extractor.js.map +1 -1
  16. package/dist/data/data-sources.d.ts +16 -0
  17. package/dist/data/data-sources.d.ts.map +1 -1
  18. package/dist/data/data-sources.js +16 -1
  19. package/dist/data/data-sources.js.map +1 -1
  20. package/dist/editor-session/engine.d.ts +1 -0
  21. package/dist/editor-session/engine.d.ts.map +1 -1
  22. package/dist/editor-session/engine.js +5 -4
  23. package/dist/editor-session/engine.js.map +1 -1
  24. package/dist/fetch/framework-fetch.d.ts +1 -0
  25. package/dist/fetch/framework-fetch.d.ts.map +1 -1
  26. package/dist/fetch/framework-fetch.js +34 -4
  27. package/dist/fetch/framework-fetch.js.map +1 -1
  28. package/dist/fetch/interceptors/auth.d.ts +2 -0
  29. package/dist/fetch/interceptors/auth.d.ts.map +1 -1
  30. package/dist/fetch/interceptors/auth.js +31 -2
  31. package/dist/fetch/interceptors/auth.js.map +1 -1
  32. package/dist/fetch/types.d.ts +4 -0
  33. package/dist/fetch/types.d.ts.map +1 -1
  34. package/dist/index.d.ts +12 -2
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +5 -0
  37. package/dist/index.js.map +1 -1
  38. package/dist/renderer/engine.d.ts.map +1 -1
  39. package/dist/renderer/engine.js +29 -4
  40. package/dist/renderer/engine.js.map +1 -1
  41. package/dist/renderer/prop-schemas.d.ts +5 -0
  42. package/dist/renderer/prop-schemas.d.ts.map +1 -1
  43. package/dist/renderer/prop-schemas.js +11 -2
  44. package/dist/renderer/prop-schemas.js.map +1 -1
  45. package/dist/reveal/context.d.ts +22 -0
  46. package/dist/reveal/context.d.ts.map +1 -0
  47. package/dist/reveal/context.js +159 -0
  48. package/dist/reveal/context.js.map +1 -0
  49. package/dist/reveal/index.d.ts +7 -0
  50. package/dist/reveal/index.d.ts.map +1 -0
  51. package/dist/reveal/index.js +7 -0
  52. package/dist/reveal/index.js.map +1 -0
  53. package/dist/reveal/protocol.d.ts +28 -0
  54. package/dist/reveal/protocol.d.ts.map +1 -0
  55. package/dist/reveal/protocol.js +2 -0
  56. package/dist/reveal/protocol.js.map +1 -0
  57. package/dist/reveal/recorder.d.ts +20 -0
  58. package/dist/reveal/recorder.d.ts.map +1 -0
  59. package/dist/reveal/recorder.js +31 -0
  60. package/dist/reveal/recorder.js.map +1 -0
  61. package/dist/reveal/redaction.d.ts +12 -0
  62. package/dist/reveal/redaction.d.ts.map +1 -0
  63. package/dist/reveal/redaction.js +85 -0
  64. package/dist/reveal/redaction.js.map +1 -0
  65. package/dist/reveal/truncation.d.ts +4 -0
  66. package/dist/reveal/truncation.d.ts.map +1 -0
  67. package/dist/reveal/truncation.js +48 -0
  68. package/dist/reveal/truncation.js.map +1 -0
  69. package/dist/reveal/types.d.ts +104 -0
  70. package/dist/reveal/types.d.ts.map +1 -0
  71. package/dist/reveal/types.js +2 -0
  72. package/dist/reveal/types.js.map +1 -0
  73. package/dist/runtime/mount-spec-runtime.d.ts +7 -0
  74. package/dist/runtime/mount-spec-runtime.d.ts.map +1 -1
  75. package/dist/runtime/mount-spec-runtime.js +5 -1
  76. package/dist/runtime/mount-spec-runtime.js.map +1 -1
  77. package/dist/security/spec-validator.d.ts.map +1 -1
  78. package/dist/security/spec-validator.js +61 -0
  79. package/dist/security/spec-validator.js.map +1 -1
  80. package/dist/spec-stores/file.js +1 -1
  81. package/dist/spec-stores/file.js.map +1 -1
  82. package/dist/types.d.ts +8 -0
  83. package/dist/types.d.ts.map +1 -1
  84. package/docs/consumer/README.md +11 -0
  85. package/docs/consumer/WHERE-TO-LOOK.md +1 -1
  86. package/docs/consumer/ai-context-patterns.md +42 -7
  87. package/docs/consumer/ai-context-primitives.md +25 -2
  88. package/docs/consumer/ai-context-runtime-semantics.md +32 -19
  89. package/docs/consumer/ai-context.md +106 -20
  90. package/docs/consumer/reference-doc.md +170 -35
  91. package/docs/llms.txt +6 -1
  92. package/docs/wiki/compiled/README.md +13 -11
  93. package/docs/wiki/compiled/_gaps.md +1 -1
  94. package/docs/wiki/compiled/_index.md +11 -7
  95. package/docs/wiki/compiled/_inventory.md +22 -14
  96. package/docs/wiki/compiled/_lint.md +21 -17
  97. package/docs/wiki/compiled/antipattern-store-save-bypass.md +13 -8
  98. package/docs/wiki/compiled/cli-agent.md +70 -0
  99. package/docs/wiki/compiled/cli-existing-spec-edit-loop.md +9 -8
  100. package/docs/wiki/compiled/cli-overview.md +12 -7
  101. package/docs/wiki/compiled/cli-patch.md +14 -11
  102. package/docs/wiki/compiled/cli-programmatic-api.md +17 -7
  103. package/docs/wiki/compiled/cli-push.md +36 -24
  104. package/docs/wiki/compiled/cli-reveal.md +64 -0
  105. package/docs/wiki/compiled/cli-toon.md +9 -9
  106. package/docs/wiki/compiled/cli-versioning-author.md +19 -15
  107. package/docs/wiki/compiled/concept-agent-context-protocol.md +76 -0
  108. package/docs/wiki/compiled/concept-component-variants.md +39 -10
  109. package/docs/wiki/compiled/concept-mythik-reveal.md +63 -0
  110. package/docs/wiki/compiled/concept-package-layout.md +7 -6
  111. package/docs/wiki/compiled/concept-public-package-names.md +9 -5
  112. package/docs/wiki/compiled/concept-shape-animations.md +4 -2
  113. package/docs/wiki/compiled/concept-spec-store-interface.md +7 -4
  114. package/docs/wiki/compiled/concept-spec-store-layering.md +5 -5
  115. package/docs/wiki/compiled/concept-templates-vs-variants.md +77 -13
  116. package/docs/wiki/compiled/concept-versioned-store.md +8 -5
  117. package/docs/wiki/compiled/pattern-git-vs-db-versioning.md +8 -6
  118. package/docs/wiki/compiled/pattern-push-vs-patch.md +13 -12
  119. package/docs/wiki/compiled/pattern-reusable-components.md +42 -12
  120. package/package.json +1 -1
@@ -910,6 +910,10 @@ Generated from article frontmatter and Sources sections. `docs/consumer` is the
910
910
  ## docs/consumer/ai-context.md
911
911
 
912
912
  - [[@action-apply-preset]] - `applyPreset` — apply curated DNA+Identity
913
+ - [[@cli-reveal]] - `mythik reveal` - live runtime context
914
+ - [[@cli-agent]] - `mythik agent` - project-local AI operating context
915
+ - [[@concept-mythik-reveal]] - Mythik Reveal - live runtime context for AI agents
916
+ - [[@concept-agent-context-protocol]] - Mythik Agent Context and Agent Protocol
913
917
  - [[@cli-existing-spec-edit-loop]] - Existing spec edit loop
914
918
  - [[@cli-overview]] - CLI overview - `mythik <command>`
915
919
  - [[@cli-patch]] - `mythik patch` - RFC 6902 patches
@@ -1415,11 +1419,11 @@ Generated from article frontmatter and Sources sections. `docs/consumer` is the
1415
1419
  - [[@cli-programmatic-api]] - Programmatic API — `mythik-cli/api`
1416
1420
  - [[@cli-push]] - `mythik push` — three approved write paths
1417
1421
 
1418
- ## docs/consumer/ai-context.md#cli-workflow
1419
-
1420
- - [[@cli-docs]] - `mythik docs` — bundled AI documentation
1421
- - [[@cli-elements]] - `mythik elements` — inspect specific elements
1422
- - [[@cli-manifest]] - `mythik manifest` — structural tree
1422
+ ## docs/consumer/ai-context.md#cli-workflow
1423
+
1424
+ - [[@cli-docs]] - `mythik docs` — bundled AI documentation
1425
+ - [[@cli-elements]] - `mythik elements` — inspect specific elements
1426
+ - [[@cli-manifest]] - `mythik manifest` — structural tree
1423
1427
  - [[@cli-overview]] - CLI overview - `mythik <command>`
1424
1428
  - [[@cli-patch]] - `mythik patch` - RFC 6902 patches
1425
1429
  - [[@cli-pull]] - `mythik pull` — export spec
@@ -1691,10 +1695,14 @@ Generated from article frontmatter and Sources sections. `docs/consumer` is the
1691
1695
 
1692
1696
  - [[@pattern-fetch-vs-datasources]] - Pattern — `fetch` vs `dataSources` decision
1693
1697
 
1694
- ## docs/consumer/reference-doc.md
1695
-
1696
- - [[@cli-existing-spec-edit-loop]] - Existing spec edit loop
1697
- - [[@cli-overview]] - CLI overview - `mythik <command>`
1698
+ ## docs/consumer/reference-doc.md
1699
+
1700
+ - [[@cli-existing-spec-edit-loop]] - Existing spec edit loop
1701
+ - [[@cli-reveal]] - `mythik reveal` - live runtime context
1702
+ - [[@cli-agent]] - `mythik agent` - project-local AI operating context
1703
+ - [[@concept-mythik-reveal]] - Mythik Reveal - live runtime context for AI agents
1704
+ - [[@concept-agent-context-protocol]] - Mythik Agent Context and Agent Protocol
1705
+ - [[@cli-overview]] - CLI overview - `mythik <command>`
1698
1706
  - [[@cli-patch]] - `mythik patch` - RFC 6902 patches
1699
1707
  - [[@cli-toon]] - `--toon` - token-efficient format
1700
1708
  - [[@concept-auth-config]] - AppSpec auth config
@@ -2472,11 +2480,11 @@ Generated from article frontmatter and Sources sections. `docs/consumer` is the
2472
2480
 
2473
2481
  - [[@concept-skeleton-auto]] - Auto-skeleton — zero-config loading state
2474
2482
 
2475
- ## docs/consumer/reference-doc.md#cli--spec-modification-via-mythik-cli
2476
-
2477
- - [[@cli-docs]] - `mythik docs` — bundled AI documentation
2478
- - [[@cli-overview]] - CLI overview - `mythik <command>`
2479
- - [[@cli-pull]] - `mythik pull` — export spec
2483
+ ## docs/consumer/reference-doc.md#cli--spec-modification-via-mythik-cli
2484
+
2485
+ - [[@cli-docs]] - `mythik docs` — bundled AI documentation
2486
+ - [[@cli-overview]] - CLI overview - `mythik <command>`
2487
+ - [[@cli-pull]] - `mythik pull` — export spec
2480
2488
 
2481
2489
  ## docs/consumer/reference-doc.md#cli-token-inspection
2482
2490
 
@@ -1,10 +1,10 @@
1
- # Lint Report - Event Binding Guard Refresh
1
+ # Lint Report - Mythik Agent Context Refresh
2
2
 
3
- Validation of cross-references, stale public references, and generated wiki shape after refreshing the compiled wiki delta from `docs/consumer` on 2026-05-09.
3
+ Validation of cross-references, stale public references, and generated wiki shape after refreshing the compiled wiki delta from `docs/consumer` on 2026-05-21.
4
4
 
5
5
  ## Broken Cross-References
6
6
 
7
- **0 broken wiki links** across compiled wiki files.
7
+ **0 broken wiki links** across compiled wiki files.
8
8
 
9
9
  ## Stale / Private Reference Scan
10
10
 
@@ -19,28 +19,32 @@ Validation of cross-references, stale public references, and generated wiki shap
19
19
 
20
20
  ## Article Counts
21
21
 
22
- - Total markdown files in `compiled`: **333**
23
- - Generated article files, excluding `README.md` and `_*.md`: **327**
22
+ - Total markdown files in `compiled`: **337**
23
+ - Generated article files, excluding `README.md` and `_*.md`: **331**
24
24
  - Migration pages removed: **yes** (`migration-*.md` no longer publish)
25
25
  - Metadata folder publish status: **excluded**
26
26
 
27
- ## Key Refresh Additions
28
-
29
- - Dotted `$let` binding reads for `$ref` and `$template`
30
- - Mixed event arrays containing actions plus transactions
31
- - `params.skipIf` dispatch-time action guards
32
- - Optional SQL adapter dependency wording
33
- - Generic SQL store / driver package-layout pages
34
- - `concept-public-package-names`
35
- - `cli-existing-spec-edit-loop`
36
- - `primitive-spatial-map`
27
+ ## Key Refresh Additions
28
+
29
+ - Dotted `$let` binding reads for `$ref` and `$template`
30
+ - Mixed event arrays containing actions plus transactions
31
+ - `params.skipIf` dispatch-time action guards
32
+ - Optional SQL adapter dependency wording
33
+ - Generic SQL store / driver package-layout pages
34
+ - `concept-public-package-names`
35
+ - `cli-existing-spec-edit-loop`
36
+ - `primitive-spatial-map`
37
37
  - `concept-spatial-map-editor`
38
38
  - `concept-spatial-map-zones`
39
39
  - `concept-editor-sessions`
40
40
  - `concept-editor-commit`
41
41
  - `concept-editor-save`
42
- - `concept-navigation-dirty-guard`
43
- - `cli-docs`
42
+ - `concept-navigation-dirty-guard`
43
+ - `cli-docs`
44
+ - `concept-mythik-reveal`
45
+ - `cli-reveal`
46
+ - `concept-agent-context-protocol`
47
+ - `cli-agent`
44
48
 
45
49
  ## Tooling
46
50
 
@@ -24,17 +24,22 @@ await store.save('my-screen', specObject); // BAD — no validation
24
24
  ## Right — three approved paths
25
25
 
26
26
  ```ts
27
- // Programmatic (best for tooling/CI):
28
- import { runPush } from 'mythik-cli/api';
29
- await runPush({ id: 'my-screen', spec: specObject });
27
+ // Programmatic (best for tooling/CI):
28
+ import { runPush } from 'mythik-cli/api';
29
+ await runPush('my-screen', JSON.stringify(specObject), {
30
+ store,
31
+ json: true,
32
+ force: false,
33
+ author: 'agent-name'
34
+ });
30
35
  ```
31
36
 
32
37
  ```bash
33
- # Shell:
34
- mythik push my-screen --from-file spec.json
35
-
36
- # Bulk:
37
- mythik push --from-dir ./specs/
38
+ # Shell:
39
+ mythik push my-screen --from-file spec.json --author <agent>
40
+
41
+ # Bulk:
42
+ mythik push --from-dir ./specs/ --author <agent>
38
43
  ```
39
44
 
40
45
  ## Why
@@ -0,0 +1,70 @@
1
+ ---
2
+ id: cli-agent
3
+ title: `mythik agent` - project-local AI operating context
4
+ kind: cli
5
+ sources: [docs/consumer/ai-context.md#cli-workflow, docs/consumer/reference-doc.md#rule-297]
6
+ ---
7
+
8
+ # `mythik agent`
9
+
10
+ `mythik agent` installs and refreshes project-local instructions for AI
11
+ agents working in a Mythik project.
12
+
13
+ Use it when a fresh agent joins a project, before asking the agent to
14
+ create or modify specs.
15
+
16
+ ## Commands
17
+
18
+ ```bash
19
+ mythik agent init codex
20
+ mythik agent init claude
21
+ mythik agent init all
22
+ mythik agent context --app <app-id> --include-screens --out .mythik/agent/context.md
23
+ ```
24
+
25
+ `agent init` creates thin adapter files such as `AGENTS.md` and
26
+ `CLAUDE.md`, plus shared instructions under `.mythik/agent/`.
27
+
28
+ `agent context` generates the project-specific operating map from the
29
+ active Mythik store. It can include AppSpec structure, screens, API
30
+ specs, commands, storage configuration, and safety rules.
31
+
32
+ ## Required agent loop
33
+
34
+ Existing stored specs stay on:
35
+
36
+ ```text
37
+ manifest -> elements -> patch --from-file --author -> validate -> verify
38
+ ```
39
+
40
+ `push` is for new specs or intentional full replacement. Existing
41
+ specs require explicit `--replace`. Persisted writes require
42
+ `--author <name>` for versioned stores or explicit
43
+ `--allow-unversioned` for intentionally unversioned stores.
44
+
45
+ ## Source of truth
46
+
47
+ The active Mythik store is the source of truth. Local spec files are
48
+ drafts, snapshots, migrations, backups, or fixtures unless the project
49
+ intentionally uses a file store.
50
+
51
+ Use `mythik lint` for local drafts, replacement files, bulk
52
+ imports/migrations, and relevant consumer code changes. Use TOON for
53
+ large reads when supported.
54
+
55
+ ## Related articles
56
+
57
+ - [[@concept-agent-context-protocol]]
58
+ - [[@cli-existing-spec-edit-loop]]
59
+ - [[@cli-manifest]]
60
+ - [[@cli-elements]]
61
+ - [[@cli-patch]]
62
+ - [[@cli-push]]
63
+ - [[@cli-toon]]
64
+ - [[@cli-lint]]
65
+ - [[@cli-reveal]]
66
+
67
+ ## Sources
68
+
69
+ - `docs/consumer/ai-context.md`
70
+ - `docs/consumer/reference-doc.md`
@@ -14,11 +14,12 @@ Required loop:
14
14
  1. `mythik manifest <id>` - inspect the current structure and identify candidate element IDs.
15
15
  2. `mythik elements <id> <ids>` - inspect only the exact nodes and nearby containers that will change.
16
16
  3. Write a small RFC 6902 patch file.
17
- 4. `mythik patch <id> --from-file patch.json` - apply through the validated CLI path.
18
- 5. Re-run `manifest` or `elements` to verify the changed surface.
19
-
20
- `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.
21
-
22
- Never edit database rows directly and never call `SpecStore.save()` from app code. Those bypass validation.
23
-
24
- Related: [[@cli-manifest]], [[@cli-elements]], [[@cli-patch]], [[@antipattern-store-save-bypass]].
17
+ 4. `mythik patch <id> --from-file patch.json --author <agent>` - apply through the validated, versioned CLI path.
18
+ 5. Run `mythik validate <id>`.
19
+ 6. Re-run `manifest` or `elements` to verify the changed surface.
20
+
21
+ `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.
22
+
23
+ Never edit database rows directly and never call `SpecStore.save()` from app code. Those bypass validation.
24
+
25
+ Related: [[@cli-manifest]], [[@cli-elements]], [[@cli-patch]], [[@cli-agent]], [[@antipattern-store-save-bypass]].
@@ -16,17 +16,20 @@ forms are documented in [[@cli-push]] and rule 248.
16
16
  mythik init --store supabase --url <url> --key $MYTHIK_API_KEY # configure
17
17
  mythik docs path # locate bundled AI docs
18
18
  mythik docs copy ./mythik-docs # copy docs for an AI agent
19
- mythik push <screen> # create/replace
19
+ mythik push <screen> --from-file spec.json --author <name> # create
20
+ mythik push <screen> --from-file spec.json --replace --author <name> # replace
20
21
  mythik pull <screen> # export to stdout
21
22
  mythik manifest <screen> # structural tree
22
23
  mythik elements <screen> <id1,id2,...> # element details
23
- mythik patch <screen> --from-file patch.json # RFC 6902
24
+ mythik patch <screen> --from-file patch.json --author <name> # RFC 6902
24
25
  mythik validate <screen> # validate
25
26
  mythik delete <screen> --confirm # delete (requires --confirm)
26
27
  mythik tokens --dna '{"primary":"#0D9488"}' --json # inspect tokens
27
28
  mythik contract --app <id> --api <id> # cross-validate
28
29
  mythik lint [--from-file path | --from-dir folder] # detect anti-patterns
29
- mythik history <screen> # version history
30
+ mythik history <screen> # version history
31
+ mythik agent init codex # install agent protocol
32
+ mythik agent context --app <id> --include-screens # generate agent context
30
33
  ```
31
34
 
32
35
  ## Common flags
@@ -48,8 +51,9 @@ Manifest output adapts per doctype. See [[@cli-app-spec]].
48
51
  1. **`docs path`** - locate the installed AI docs
49
52
  2. **`manifest`** - see structure, decide what to modify
50
53
  3. **`elements`** - inspect specific elements
51
- 4. **`patch --from-file patch.json`** - apply surgical changes
52
- 5. **`manifest`** - verify
54
+ 4. **`patch --from-file patch.json --author <name>`** - apply surgical changes
55
+ 5. **`validate`** - check the stored result
56
+ 6. **`manifest`** - verify
53
57
 
54
58
  ## Related concepts
55
59
 
@@ -68,8 +72,9 @@ Manifest output adapts per doctype. See [[@cli-app-spec]].
68
72
  - [[@cli-lint]]
69
73
  - [[@cli-history]]
70
74
  - [[@cli-versioning-author]]
71
- - [[@cli-app-spec]]
72
- - [[@cli-programmatic-api]]
75
+ - [[@cli-app-spec]]
76
+ - [[@cli-programmatic-api]]
77
+ - [[@cli-agent]]
73
78
 
74
79
  ## Sources (raw)
75
80
 
@@ -15,22 +15,22 @@ other shell-sensitive strings.
15
15
 
16
16
  ### Preferred path - file
17
17
 
18
- ```bash
19
- mythik patch task-manager --from-file patch.json
20
- ```
18
+ ```bash
19
+ mythik patch task-manager --from-file patch.json --author <agent>
20
+ ```
21
21
 
22
22
  `--from-file <path>` wins over ambient non-TTY stdin. Intentional stdin
23
23
  still works via `--from-file -` or a pipe without `--from-file`:
24
24
 
25
25
  ```bash
26
- cat patch.json | mythik patch task-manager
27
- mythik patch task-manager --from-file -
26
+ cat patch.json | mythik patch task-manager --author <agent>
27
+ mythik patch task-manager --from-file - --author <agent>
28
28
  ```
29
29
 
30
30
  ### Inline
31
31
 
32
32
  ```bash
33
- mythik patch task-manager '[{"op":"replace","path":"/elements/title/props/content","value":"New Title"}]'
33
+ mythik patch task-manager '[{"op":"replace","path":"/elements/title/props/content","value":"New Title"}]' --author <agent>
34
34
  ```
35
35
 
36
36
  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
55
55
  (everything else):
56
56
 
57
57
  ```bash
58
- mythik patch task-manager --from-file patch.toon
58
+ mythik patch task-manager --from-file patch.toon --author <agent>
59
59
  ```
60
60
 
61
61
  See [[@cli-toon]].
@@ -66,9 +66,11 @@ Use `/layout/elements/...`, NOT `/elements/...`. See [[@cli-app-spec]].
66
66
 
67
67
  ## Versioning
68
68
 
69
- `--author <name>` records history when the resolved store supports
70
- `saveVersion`. JSON/TOON success output includes `versioned: boolean`
71
- and `version?: number`. See [[@cli-versioning-author]].
69
+ `--author <name>` is the normal persisted-write path. It records
70
+ history when the resolved store supports `saveVersion`. JSON/TOON
71
+ success output includes `versioned: boolean` and `version?: number`.
72
+ Use `--allow-unversioned` only for intentionally unversioned stores.
73
+ See [[@cli-versioning-author]].
72
74
 
73
75
  ## Related concepts
74
76
 
@@ -77,7 +79,8 @@ and `version?: number`. See [[@cli-versioning-author]].
77
79
  - [[@cli-app-spec]]
78
80
  - [[@cli-versioning-author]]
79
81
  - [[@cli-history]]
80
- - [[@cli-programmatic-api]] - `runPatch`
82
+ - [[@cli-programmatic-api]] - `runPatch`
83
+ - [[@concept-agent-context-protocol]]
81
84
 
82
85
  ## Sources (raw)
83
86
 
@@ -33,13 +33,23 @@ import {
33
33
 
34
34
  ## Example
35
35
 
36
- ```ts
37
- import { runPush } from 'mythik-cli/api';
38
-
39
- const result = await runPush({ id: 'my-screen', spec: doc, json: true });
40
- const data = JSON.parse(result.output);
41
- console.log(data.elementCount, data.warnings);
42
- ```
36
+ ```ts
37
+ import { readFile } from 'node:fs/promises';
38
+ import { runPush } from 'mythik-cli/api';
39
+
40
+ const input = await readFile('spec.json', 'utf8');
41
+ const result = await runPush('my-screen', input, {
42
+ store,
43
+ json: true,
44
+ force: false,
45
+ author: 'agent-name'
46
+ });
47
+ const data = JSON.parse(result.output);
48
+ console.log(data.elementCount, data.warnings);
49
+ ```
50
+
51
+ Programmatic callers provide the same `SpecStore` they would configure
52
+ for the CLI.
43
53
 
44
54
  ## `PushResult` extension
45
55
 
@@ -14,13 +14,14 @@ spec writes** — `SpecStore.save()` is `@internal`.
14
14
 
15
15
  ### Shell — single file
16
16
 
17
- ```bash
18
- mythik push <id> --from-file spec.json
19
- mythik push <id> < spec.json # stdin
20
- cat spec.json | mythik push <id> # pipe
21
- mythik push <id> <<'EOF' # heredoc
22
- { ... }
23
- EOF
17
+ ```bash
18
+ mythik push <id> --from-file spec.json --author <agent>
19
+ mythik push <id> --from-file spec.json --replace --author <agent>
20
+ mythik push <id> --from-file - --author <agent> # stdin
21
+ cat spec.json | mythik push <id> --author <agent> # pipe
22
+ mythik push <id> <<'EOF' # heredoc
23
+ { ... }
24
+ EOF
24
25
  ```
25
26
 
26
27
  `--from-file` is **cross-shell ergonomic** for any spec containing
@@ -30,7 +31,7 @@ EOF
30
31
  ### Bulk — directory
31
32
 
32
33
  ```bash
33
- mythik push --from-dir ./specs/
34
+ mythik push --from-dir ./specs/ --author <agent>
34
35
  ```
35
36
 
36
37
  Sequential per-file push of every `*.json`. **Continue-on-error**:
@@ -39,23 +40,33 @@ recovers by fixing failures and re-running.
39
40
 
40
41
  ### Programmatic — `mythik-cli/api`
41
42
 
42
- ```ts
43
- import { runPush, type PushOptions, type PushResult } from 'mythik-cli/api';
44
-
45
- const result = await runPush({ id: 'my-screen', spec: doc, json: true });
46
- const data = JSON.parse(result.output) as PushResult;
47
- ```
48
-
49
- Same code path as the binary, no shell. Pass `json: true` to receive
50
- structured `PushResult`.
43
+ ```ts
44
+ import { readFile } from 'node:fs/promises';
45
+ import { runPush, type PushOptions, type PushResult } from 'mythik-cli/api';
46
+
47
+ const input = await readFile('spec.json', 'utf8');
48
+ const result = await runPush('my-screen', input, {
49
+ store,
50
+ author: 'agent',
51
+ json: true,
52
+ force: false
53
+ } satisfies PushOptions);
54
+ const data = JSON.parse(result.output) as PushResult;
55
+ ```
56
+
57
+ Same code path as the binary, no shell. Provide the same `SpecStore`
58
+ you would configure the CLI with. Pass `json: true` to receive
59
+ structured `PushResult`.
51
60
 
52
61
  ## Input precedence
53
62
 
54
63
  - `--from-file <path>` wins over ambient non-TTY stdin.
55
64
  - Intentional stdin remains supported via `--from-file -` or by piping without `--from-file`.
56
- - `--from-file` plus a positional argument is still a conflict.
57
- - `--from-dir` is mutually exclusive with `<screen>` argument and `--from-file`.
58
- - Conflicts produce explicit error + exit 1.
65
+ - `--from-file` plus a positional argument is still a conflict.
66
+ - `--from-dir` is mutually exclusive with `<screen>` argument and `--from-file`.
67
+ - Conflicts produce explicit error + exit 1.
68
+ - Existing specs require explicit `--replace`.
69
+ - Persisted writes require `--author <name>` or intentional `--allow-unversioned`.
59
70
 
60
71
  ## Validation behavior
61
72
 
@@ -67,8 +78,8 @@ structured `PushResult`.
67
78
 
68
79
  ## Versioning
69
80
 
70
- `--author <name>` activates `VersionedSpecStore.saveVersion()`. See
71
- [[@cli-versioning-author]].
81
+ `--author <name>` activates `VersionedSpecStore.saveVersion()` when
82
+ available. See [[@cli-versioning-author]].
72
83
 
73
84
  ## Constraints / Anti-patterns
74
85
 
@@ -81,8 +92,9 @@ structured `PushResult`.
81
92
  - [[@cli-config]]
82
93
  - [[@cli-versioning-author]]
83
94
  - [[@cli-programmatic-api]]
84
- - [[@cli-lint]]
85
- - [[@antipattern-store-save-bypass]]
95
+ - [[@cli-lint]]
96
+ - [[@antipattern-store-save-bypass]]
97
+ - [[@concept-agent-context-protocol]]
86
98
 
87
99
  ## Sources (raw)
88
100
 
@@ -0,0 +1,64 @@
1
+ ---
2
+ id: cli-reveal
3
+ title: `mythik reveal` - live runtime context
4
+ kind: cli
5
+ 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]
6
+ ---
7
+
8
+ # `mythik reveal`
9
+
10
+ `mythik reveal` connects the CLI to a running Mythik app through a
11
+ local Reveal Bridge.
12
+
13
+ Start the bridge:
14
+
15
+ ```bash
16
+ mythik reveal start --port 17373
17
+ ```
18
+
19
+ The command prints:
20
+
21
+ ```text
22
+ MYTHIK_REVEAL_URL=http://127.0.0.1:17373
23
+ MYTHIK_REVEAL_TOKEN=<generated-token>
24
+ ```
25
+
26
+ Pass those values into the host app's development-only `reveal` config.
27
+
28
+ ## Query commands
29
+
30
+ ```bash
31
+ mythik reveal apps --json
32
+ mythik reveal context --app my-app
33
+ mythik reveal current --app my-app
34
+ mythik reveal screen dashboard --app my-app
35
+ mythik reveal element save-button --app my-app
36
+ ```
37
+
38
+ `apps` lists connected sessions. `context` asks for the full app
39
+ context. `current`, `screen`, and `element` scope the request.
40
+
41
+ For Android emulator smoke, reverse the bridge port before loading the
42
+ native app:
43
+
44
+ ```bash
45
+ adb reverse tcp:17373 tcp:17373
46
+ ```
47
+
48
+ ## Agent rule
49
+
50
+ If a running Mythik app misbehaves and Reveal is available, the agent
51
+ should inspect Reveal context before proposing a patch. This avoids
52
+ debugging from stale pulled specs, screenshots, or source-code
53
+ assumptions.
54
+
55
+ ## Related articles
56
+
57
+ - [[@concept-mythik-reveal]]
58
+ - [[@cli-existing-spec-edit-loop]]
59
+ - [[@cli-docs]]
60
+
61
+ ## Sources
62
+
63
+ - `docs/consumer/ai-context.md`
64
+ - `docs/consumer/reference-doc.md`
@@ -12,9 +12,9 @@ TOON is a token-efficient format. Patch input autodetects JSON vs TOON;
12
12
 
13
13
  ## Use on `elements` and `patch`
14
14
 
15
- ```bash
16
- mythik elements task-manager btn,nav --toon
17
- mythik patch task-manager --from-file patch.toon --toon
15
+ ```bash
16
+ mythik elements task-manager btn,nav --toon
17
+ mythik patch task-manager --from-file patch.toon --toon --author <agent>
18
18
  ```
19
19
 
20
20
  ## TOON input autodetect
@@ -24,15 +24,15 @@ mythik patch task-manager --from-file patch.toon --toon
24
24
 
25
25
  JSON input:
26
26
 
27
- ```bash
28
- mythik patch task-manager --from-file patch.json
29
- ```
27
+ ```bash
28
+ mythik patch task-manager --from-file patch.json --author <agent>
29
+ ```
30
30
 
31
31
  TOON input:
32
32
 
33
- ```bash
34
- mythik patch task-manager --from-file patch.toon
35
- ```
33
+ ```bash
34
+ mythik patch task-manager --from-file patch.toon --author <agent>
35
+ ```
36
36
 
37
37
  ## Related concepts
38
38
 
@@ -5,18 +5,18 @@ kind: concept
5
5
  sources: [docs/consumer/reference-doc.md#rules-92-110]
6
6
  ---
7
7
 
8
- # `--author` flag
9
-
10
- `mythik push` and `mythik patch` **without `--author`** write directly to
11
- the `screens` table with NO version history. **With `--author <name>`**,
12
- they use `VersionedSpecStore` which writes to BOTH `screens` AND
13
- `screen_versions`, enabling `history`, `diff`, and `rollback` commands.
8
+ # `--author` flag
9
+
10
+ `mythik push` and `mythik patch` with `--author <name>` use
11
+ `VersionedSpecStore` when the resolved store supports it. That writes
12
+ to BOTH `screens` AND `screen_versions`, enabling `history`, `diff`,
13
+ and `rollback` commands.
14
14
 
15
15
  ## Usage
16
16
 
17
17
  ```bash
18
- mythik push my-screen --author alice --description "Initial layout"
19
- mythik patch screen-id --from-file patch.json --author alice --description "Fixed layout"
18
+ mythik push my-screen --from-file spec.json --author alice --description "Initial layout"
19
+ mythik patch screen-id --from-file patch.json --author alice --description "Fixed layout"
20
20
  ```
21
21
 
22
22
  The version row includes:
@@ -24,12 +24,15 @@ The version row includes:
24
24
  - `source_type` — `push` or `patch`
25
25
  - `description` — optional, via `--description`
26
26
 
27
- **Always use `--author` during development** (rule 110).
28
-
29
- ## Without `--author`
30
-
31
- Commands work as before (no versioning). Useful for git-backed workflows
32
- where `git log` IS the audit trail.
27
+ **Always use `--author` during development** (rule 110).
28
+
29
+ ## Without `--author`
30
+
31
+ Persisted writes are rejected unless `--allow-unversioned` is explicit.
32
+ Use `--allow-unversioned` only when the project intentionally has no
33
+ versioned store, such as a file-store smoke test.
34
+
35
+ Existing full-spec replacement also requires explicit `--replace`.
33
36
 
34
37
  ## Patch output metadata
35
38
 
@@ -51,7 +54,8 @@ migration script needed.
51
54
  - [[@concept-storage-table-versions]]
52
55
  - [[@concept-rollback]]
53
56
  - [[@concept-promote-gate]]
54
- - [[@pattern-git-vs-db-versioning]]
57
+ - [[@pattern-git-vs-db-versioning]]
58
+ - [[@concept-agent-context-protocol]]
55
59
 
56
60
  ## Sources (raw)
57
61