mythik 0.0.1 → 0.1.0

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

@@ -0,0 +1,39 @@
+---
+id: cli-elements
+title: `mythik elements` — inspect specific elements
+kind: concept
+sources: [docs/consumer/ai-context.md#cli-workflow, docs/consumer/reference-doc.md#appspec--app-level-configuration]
+---
+
+# `mythik elements`
+
+Inspects specific elements by ID. **Supports dot-notation for AppSpec
+sections** (tokens, screens, navigation, translations, sharedState).
+
+## Usage
+
+```bash
+mythik elements task-manager btn,nav                              # screen-spec elements
+mythik elements task-manager btn,nav --toon                        # token-efficient
+
+# AppSpec — dot-notation for non-element sections
+mythik elements app-demo tokens.colors
+mythik elements app-demo screens.task-manager
+mythik elements app-demo navigation.auth
+mythik elements app-demo sidebar,nav-item                          # layout elements (simple ID)
+mythik elements app-demo sidebar,tokens.colors,screens.task-manager # mixed
+
+# ApiSpec
+mythik elements ejecucion-api endpoints.ejecucion-crud
+```
+
+## Related concepts
+
+- [[@cli-manifest]]
+- [[@cli-toon]]
+- [[@cli-app-spec]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § CLI Workflow`
+- `docs/consumer/reference-doc.md § AppSpec → AppSpec — App-Level Configuration`

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

@@ -0,0 +1,24 @@
+---
+id: cli-existing-spec-edit-loop
+title: Existing spec edit loop
+kind: cli
+sources: [docs/consumer/ai-context.md, docs/consumer/reference-doc.md, docs/consumer/WHERE-TO-LOOK.md]
+---
+
+# Existing spec edit loop
+
+For existing persisted specs, AI agents must inspect first, patch second, and verify after.
+
+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]].

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

@@ -0,0 +1,38 @@
+---
+id: cli-history
+title: `mythik history` — version history with diffs
+kind: concept
+sources: [docs/consumer/reference-doc.md#rule-93]
+---
+
+# `mythik history`
+
+Shows version history with **inline diffs** between consecutive versions.
+Uses `computeStructuralDiff` to show actual before/after values.
+
+## Output
+
+```
+v3 (alice, 2026-04-25, push)  "Fixed layout"
+   ~ element "btn" prop content: "Send" → "Submit"
+v2 (bob,   2026-04-24, push)
+   + element "footer-link" added
+v1 (system, 2026-04-23, push)
+```
+
+## Requirements
+
+`history` only works on specs written via `--author <name>` (which
+activates `VersionedSpecStore`). See [[@cli-versioning-author]].
+
+## Related concepts
+
+- [[@cli-versioning-author]]
+- [[@concept-versioned-store]]
+- [[@concept-rollback]]
+- [[@concept-promote-gate]]
+- [[@concept-storage-table-versions]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rules 92, 93`

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

@@ -0,0 +1,77 @@
+---
+id: cli-lint
+title: `mythik lint` — anti-pattern detection
+kind: concept
+sources: [, docs/consumer/ai-context.md#pre-push-linting, docs/consumer/reference-doc.md#rule-249]
+---
+
+# `mythik lint`
+
+Detect known anti-patterns in specs and consumer code. **4 rules in v0.1.**
+
+## Usage
+
+```bash
+mythik lint --from-file spec.json    # single spec file
+mythik lint --from-dir specs/        # bulk over a directory
+mythik lint                          # auto-discovers via .mythikrc + scans ./src for code rules
+mythik lint --specs-only             # filter
+mythik lint --code-only              # filter
+mythik lint --code-dir <path>        # override default code scan root (default: ./src)
+mythik lint --json                   # machine-readable output
+```
+
+Programmatic: `import { runLint } from 'mythik-cli/api'`.
+
+## 4 rules in v0.1
+
+| Rule ID | Surface | Severity | Description |
+|---|---|---|---|
+| `spec-row-literal` | spec | warning | `$row` is not an expression — use `$state: '/ui/selectedRow/<key>'`. See [[@antipattern-row-literal]] |
+| `spec-crud-id-collision` | spec | error | `endpoint.path` ending `/:id` combined with `crud: {}` produces `/path/:id/:id`. See [[@antipattern-crud-id-collision]] |
+| `spec-auth-domains-port` | spec | warning | `auth.authDomains[i]` containing `:port` strips the port silently. See [[@antipattern-auth-domains-port]] |
+| `code-store-save-bypass` | code | error | Calling `*store*.save()` outside `packages/core/` and `packages/cli/` bypasses validation. See [[@antipattern-store-save-bypass]] |
+
+## Defense in depth
+
+Spec rules ALSO run during `mythik push` and `mythik validate` (not just
+`lint`). Code rules run only via `mythik lint` (push doesn't see consumer code).
+
+## TypeScript peer dependency
+
+Code rules require TypeScript ^5.0.0 as `peerDependency` (optional). If
+not installed, code rules emit one warning finding
+`lint-meta-no-typescript` and skip cleanly. Spec rules run independently.
+
+## Exit codes
+
+- `0` — no errors
+- `1` — errors found
+- `2` — runtime error (e.g., unreadable file)
+
+## Code rule scope (limitations)
+
+`code-store-save-bypass` matches `<Identifier>.save()` callees only
+(e.g. `myStore.save(...)`). **Does NOT detect**:
+- `this.store.save()`
+- `<obj>.<store>.save()`
+- `(await getStore()).save()`
+
+These slip through the AST scanner. Generation-level guidance in
+`ai-context.md` (anti-patterns) covers all variants; the lint rule is
+defense-in-depth, not complete catch.
+
+## Related concepts
+
+- [[@cli-validate]]
+- [[@cli-push]]
+- [[@antipattern-row-literal]]
+- [[@antipattern-crud-id-collision]]
+- [[@antipattern-auth-domains-port]]
+- [[@antipattern-store-save-bypass]]
+
+## Sources (raw)
+
+- ` § Item I`
+- `docs/consumer/ai-context.md § Pre-push linting`
+- `docs/consumer/reference-doc.md § rule 249`

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

@@ -0,0 +1,43 @@
+---
+id: cli-manifest
+title: `mythik manifest` — structural tree
+kind: concept
+sources: [docs/consumer/ai-context.md#cli-workflow]
+---
+
+# `mythik manifest`
+
+Shows the structural tree of a spec — colorized output, tree view.
+
+## Usage
+
+```bash
+mythik manifest task-manager       # screen spec — element tree
+mythik manifest app-demo           # AppSpec — layout + screens + tokens
+mythik manifest ejecucion-api      # ApiSpec — catalogs + endpoints + auth
+```
+
+## Output adapts per doctype
+
+- **Screen spec**: element tree.
+- **AppSpec**: layout + screens + tokens summary.
+- **ApiSpec**: catalogs + endpoints + auth config.
+
+## Workflow
+
+1. `manifest` — see structure, decide what to modify
+2. `elements` — inspect specific elements
+3. `patch` — apply surgical changes
+4. `manifest` — verify
+
+## Related concepts
+
+- [[@cli-elements]]
+- [[@cli-patch]]
+- [[@cli-overview]]
+- [[@cli-app-spec]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § CLI Workflow`
+- `docs/consumer/reference-doc.md § Workflow: Manifest → Elements → Patch`

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

@@ -0,0 +1,77 @@
+---
+id: cli-overview
+title: CLI overview - `mythik <command>`
+kind: concept
+sources: [docs/consumer/ai-context.md#cli-workflow, docs/consumer/reference-doc.md#cli--spec-modification-via-mythik-cli]
+---
+
+# CLI overview
+
+The `mythik` CLI is the only approved path for spec writes. Three approved
+forms are documented in [[@cli-push]] and rule 248.
+
+## Commands
+
+```bash
+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 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 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
+```
+
+## Common flags
+
+- `--json` - machine-parseable output
+- `--store <type>` - store type (`supabase`, `sqlserver`, `memory`, `file`)
+- `--url <url>` - connection URL
+- `--key <key>` - API key (NEVER inline; see [[@cli-config]])
+- `--table <name>` - override store table (rule 91)
+- `--toon` - TOON format
+
+## Spec types auto-detected
+
+CLI detects `type: "app"`, `type: "api"`, or screen-spec automatically.
+Manifest output adapts per doctype. See [[@cli-app-spec]].
+
+## Workflow
+
+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
+
+## Related concepts
+
+- [[@cli-docs]]
+- [[@cli-config]]
+- [[@cli-push]]
+- [[@cli-pull]]
+- [[@cli-manifest]]
+- [[@cli-elements]]
+- [[@cli-patch]]
+- [[@cli-toon]]
+- [[@cli-validate]]
+- [[@cli-delete]]
+- [[@cli-tokens]]
+- [[@cli-contract]]
+- [[@cli-lint]]
+- [[@cli-history]]
+- [[@cli-versioning-author]]
+- [[@cli-app-spec]]
+- [[@cli-programmatic-api]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md` CLI Workflow
+- `docs/consumer/reference-doc.md` CLI spec modification

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

@@ -0,0 +1,85 @@
+---
+id: cli-patch
+title: `mythik patch` - RFC 6902 patches
+kind: concept
+sources: [docs/consumer/ai-context.md#cli-workflow, docs/consumer/reference-doc.md#patch-input-file-vs-stdin]
+---
+
+# `mythik patch`
+
+Apply RFC 6902 JSON patches. Prefer `--from-file` for cross-shell
+ergonomics when the patch contains `$state`, `$template`, `$auth`, or
+other shell-sensitive strings.
+
+## Usage
+
+### Preferred path - file
+
+```bash
+mythik patch task-manager --from-file patch.json
+```
+
+`--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 -
+```
+
+### Inline
+
+```bash
+mythik patch task-manager '[{"op":"replace","path":"/elements/title/props/content","value":"New Title"}]'
+```
+
+Inline remains valid for tiny patches, but file input is the canonical
+cross-shell path.
+
+## Patch rules
+
+- **`"op": "add"` with numeric index inserts BEFORE** that index - does
+  NOT replace.
+- Use `/-` to append at the end.
+- Use `"op": "replace"` to overwrite.
+
+## Never inline large JSON or shell-sensitive expressions
+
+Shell quoting breaks with nested quotes and `$<word>` strings. Use
+`--from-file` for anything beyond a few ops or for any patch containing
+`$state`, `$template`, `$auth`, or `$row`.
+
+## TOON input autodetection
+
+Patch input autodetects format: JSON (starts with `[` or `{`) or TOON
+(everything else):
+
+```bash
+mythik patch task-manager --from-file patch.toon
+```
+
+See [[@cli-toon]].
+
+## AppSpec patch paths
+
+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]].
+
+## Related concepts
+
+- [[@cli-overview]]
+- [[@cli-toon]]
+- [[@cli-app-spec]]
+- [[@cli-versioning-author]]
+- [[@cli-history]]
+- [[@cli-programmatic-api]] - `runPatch`
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md` CLI Workflow / Patch rules
+- `docs/consumer/reference-doc.md` Patch Input: File vs Stdin

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

@@ -0,0 +1,73 @@
+---
+id: cli-programmatic-api
+title: Programmatic API — `mythik-cli/api`
+kind: concept
+sources: [, docs/consumer/ai-context.md#cli-is-the-only-approved-path-for-spec-writes]
+---
+
+# Programmatic API — `mythik-cli/api`
+
+Subpath that exposes CLI internals as public functions. **Use this
+instead of deep imports** (`mythik-cli/dist/...`).
+
+## Public exports
+
+```ts
+import {
+  runPush, runPatch, parsePatchInput, runLint,
+  type PushOptions, type PushResult,
+  type PatchOptions, type CommandResult,
+  type LintFinding, type LintSuggestion, type LintResult, type LintOptions,
+  type LintSeverity, type LintLocation, type LintSummary,
+  // re-exported from mythik:
+  type SpecStore, type JsonPatch, type ValidationError, type PatchResult
+} from 'mythik-cli/api';
+```
+
+## Use cases
+
+- IDE tooling.
+- Test harnesses.
+- CI scripts.
+- Programmatic CRUD over specs without shell.
+
+## 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);
+```
+
+## `PushResult` extension
+
+Gained optional `warnings?: ValidationError[]` field (additive,
+non-breaking) to surface prop warnings in JSON mode (used by bulk push).
+
+## `runPatch` JSON/TOON metadata
+
+When `runPatch` succeeds with a versioned store and `author`, it records a
+version in every output mode. JSON/TOON success output includes additive
+`versioned: boolean` and `version?: number` fields.
+
+## Migration
+
+If your tooling uses deep imports:
+```diff
+- import { runPush } from 'mythik-cli/dist/commands/push.js';
++ import { runPush } from 'mythik-cli/api';
+```
+
+## Related concepts
+
+- [[@cli-push]]
+- [[@cli-patch]]
+- [[@cli-lint]]
+- [[@concept-package-layout]]
+
+## Sources (raw)
+
+- ` § Item F`
+- `docs/consumer/ai-context.md § CLI is the only approved path for spec writes`

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

@@ -0,0 +1,39 @@
+---
+id: cli-pull
+title: `mythik pull` — export spec
+kind: concept
+sources: [docs/consumer/ai-context.md#cli-workflow, docs/consumer/reference-doc.md#cli--spec-modification-via-mythik-cli]
+---
+
+# `mythik pull`
+
+Exports a full spec to stdout.
+
+## Examples
+
+```bash
+mythik pull task-manager > task-manager.json     # backup
+mythik pull task-manager --json                  # always JSON
+mythik pull task-manager --store memory          # different store
+
+# Cross-store migration
+mythik pull <id> --store A | mythik push <id> --store B
+```
+
+## Use cases
+
+- Backup before destructive operation.
+- Cross-store migration.
+- Inspect / diff specs locally.
+
+## Related concepts
+
+- [[@cli-push]]
+- [[@cli-overview]]
+- [[@cli-manifest]] — alternative to `pull` for structural inspection
+- [[@cli-history]] — for versioned specs
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § CLI Workflow`
+- `docs/consumer/reference-doc.md § CLI Workflow → Full Spec Lifecycle`

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

@@ -0,0 +1,91 @@
+---
+id: cli-push
+title: `mythik push` — three approved write paths
+kind: concept
+sources: [docs/consumer/ai-context.md#cli-is-the-only-approved-path-for-spec-writes, docs/consumer/reference-doc.md#rule-248]
+---
+
+# `mythik push`
+
+CLI command for creating / replacing specs. **The only approved path for
+spec writes** — `SpecStore.save()` is `@internal`.
+
+## Three approved forms
+
+### 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
+```
+
+`--from-file` is **cross-shell ergonomic** for any spec containing
+`$state`, `$template`, `$auth`, or `$row` — PowerShell expands
+`$<word>` in double-quoted strings (rule 248).
+
+### Bulk — directory
+
+```bash
+mythik push --from-dir ./specs/
+```
+
+Sequential per-file push of every `*.json`. **Continue-on-error**:
+failures don't stop subsequent specs. **No rollback.** Partial state
+recovers by fixing failures and re-running.
+
+### Programmatic — `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`.
+
+## 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.
+
+## Validation behavior
+
+- **New screens** save even with validation errors (fix later with
+  `mythik patch`).
+- **Existing screens** reject invalid specs unless `--force` is used.
+- Validation errors include suggested fix patches for auto-fixable
+  issues (typos, orphan children).
+
+## Versioning
+
+`--author <name>` activates `VersionedSpecStore.saveVersion()`. See
+[[@cli-versioning-author]].
+
+## Constraints / Anti-patterns
+
+- **Never call `SpecStore.save()` from app code** — bypasses validation,
+  produces silently-broken specs. See [[@antipattern-store-save-bypass]].
+
+## Related concepts
+
+- [[@cli-overview]]
+- [[@cli-config]]
+- [[@cli-versioning-author]]
+- [[@cli-programmatic-api]]
+- [[@cli-lint]]
+- [[@antipattern-store-save-bypass]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § CLI is the only approved path for spec writes`
+- ` § Item F`
+- `docs/consumer/reference-doc.md § rule 248`

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

@@ -0,0 +1,38 @@
+---
+id: cli-tokens
+title: `mythik tokens` — DNA inspection
+kind: concept
+sources: [docs/consumer/reference-doc.md#cli-token-inspection]
+---
+
+# `mythik tokens`
+
+Inspects DNA derivation. Shows full resolved token set.
+
+## Usage
+
+```bash
+mythik tokens --dna '{"primary":"#0D9488","roundness":0.7}' --json
+```
+
+## Output
+
+JSON tree of resolved tokens (colors, shape, typography, spacing,
+elevation, motion, opacity, identity).
+
+## Use cases
+
+- Verify what DNA generates before applying.
+- Debug unexpected resolved values.
+- Compare two DNA settings side by side.
+
+## Related concepts
+
+- [[@concept-dna-seeds]]
+- [[@concept-token-system]]
+- [[@concept-cli-tokens-inspect]]
+- [[@cli-overview]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § CLI Token Inspection`

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

@@ -0,0 +1,44 @@
+---
+id: cli-toon
+title: `--toon` - token-efficient format
+kind: concept
+sources: [docs/consumer/reference-doc.md#toon-format-token-efficient-output]
+---
+
+# `--toon`
+
+TOON is a token-efficient format. Patch input autodetects JSON vs TOON;
+`--toon` controls TOON output.
+
+## Use on `elements` and `patch`
+
+```bash
+mythik elements task-manager btn,nav --toon
+mythik patch task-manager --from-file patch.toon --toon
+```
+
+## TOON input autodetect
+
+`mythik patch` autodetects format from the first character: JSON (`[` or
+`{`) vs TOON (everything else).
+
+JSON input:
+
+```bash
+mythik patch task-manager --from-file patch.json
+```
+
+TOON input:
+
+```bash
+mythik patch task-manager --from-file patch.toon
+```
+
+## Related concepts
+
+- [[@cli-elements]]
+- [[@cli-patch]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md` TOON Format