mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/antipattern-overflow-hidden-with-shadow.md

@@ -0,0 +1,50 @@
+---
+id: antipattern-overflow-hidden-with-shadow
+title: Anti-pattern — `overflow: hidden` + `box-shadow` hover
+kind: pattern
+sources: [docs/consumer/ai-context.md#rule-15, docs/consumer/reference-doc.md#rule-35]
+---
+
+# Anti-pattern — `overflow: hidden` with `box-shadow` hover
+
+Combining `overflow: hidden` with a `boxShadow` change on hover **clips
+the shadow** — the hover effect is invisible.
+
+## Wrong
+
+```json
+{ "type": "box",
+  "style": { "overflow": "hidden", "borderRadius": 12 },
+  "hover": { "boxShadow": "0 8px 24px rgba(0,0,0,0.15)" }
+}
+```
+
+The shadow renders but is clipped to the box bounds.
+
+## Right — drop `overflow: hidden`, or use `filter: brightness()`
+
+If you don't need overflow clipping:
+```json
+{ "type": "box",
+  "style": { "borderRadius": 12 },
+  "hover": { "boxShadow": "0 8px 24px rgba(0,0,0,0.15)" }
+}
+```
+
+If you need overflow + a hover effect, use a non-shadow effect:
+```json
+{ "type": "box",
+  "style": { "overflow": "hidden" },
+  "hover": { "filter": "brightness(1.05)" }
+}
+```
+
+## Related concepts
+
+- [[@concept-interactive-states]]
+- [[@concept-css-vs-motion]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § rule 15`
+- `docs/consumer/reference-doc.md § rule 35`

package/docs/wiki/compiled/antipattern-required-if-equals.md

@@ -0,0 +1,59 @@
+---
+id: antipattern-required-if-equals
+title: Anti-pattern — `requiredIf` with value comparison
+kind: pattern
+sources: [docs/consumer/ai-context-patterns.md#requiredif-is-truthy-only]
+---
+
+# Anti-pattern — `requiredIf` with value comparison
+
+`requiredIf` is **truthy-only**. Does NOT support `eq`. Trying to require
+based on a specific value silently does nothing.
+
+## Wrong
+
+```json
+{ "type": "requiredIf", "args": { "field": { "$state": "/form/department" }, "eq": "Engineering" } }
+```
+
+`requiredIf` ignores `eq` and only checks `field` truthiness. The field
+is always truthy (whatever the department), so the rule always fires.
+
+## Right — derive a boolean first
+
+```json
+{
+  "derive": {
+    "/ui/isEngineering": {
+      "$cond": { "$state": "/form/department", "eq": "Engineering" },
+      "$then": true,
+      "$else": false
+    }
+  },
+  "forms": {
+    "employee-form": {
+      "fields": {
+        "salary": {
+          "statePath": "/form/salary",
+          "rules": [
+            { "type": "requiredIf", "args": { "field": { "$state": "/ui/isEngineering" } }, "message": "Salary required for Engineering" }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+See [[@pattern-form-validation-cross-field]] for the full pattern.
+
+## Related concepts
+
+- [[@concept-validators-catalog]]
+- [[@concept-derive]]
+- [[@expression-cond]]
+- [[@pattern-form-validation-cross-field]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-patterns.md § requiredIf is truthy-only`

package/docs/wiki/compiled/antipattern-row-literal.md

@@ -0,0 +1,70 @@
+---
+id: antipattern-row-literal
+title: Anti-pattern — `$row` literal
+kind: pattern
+sources: [docs/consumer/ai-context-runtime-semantics.md#21-uiselectedrow--blocker-1, docs/consumer/ai-context-primitives.md#table, docs/consumer/reference-doc.md#rule-69]
+---
+
+# Anti-pattern — `$row` literal
+
+**`$row` does NOT exist** as an expression handler. Writing
+`{ "$row": "name" }` in `setState` params, `$template`, or anywhere else
+treats the literal string `"$row"` as a value — silent failure.
+
+## Wrong
+
+```json
+{ "content": { "$row": "name" } }                                                  // BAD
+{ "action": "setState", "params": { "statePath": "/edit/id", "value": "$row" } }   // BAD
+```
+
+## Right
+
+Read row data via `$state` from `/ui/selectedRow/<key>` (framework writes
+clicked row before column action or `onRowClick` dispatch):
+
+```json
+{ "content": { "$state": "/ui/selectedRow/name" } }
+{ "content": { "$template": "Editing: ${ /ui/selectedRow/name }" } }
+```
+
+For column actions:
+```json
+"onPress": [{
+  "action": "openModal",
+  "params": { "id": "edit-modal", "itemId": { "$state": "/ui/selectedRow/id" } }
+}]
+```
+
+For `onRowClick`:
+```json
+"onRowClick": [{
+  "action": "openDrawer",
+  "params": { "id": "detail", "itemId": { "$state": "/ui/selectedRow/id" } }
+}]
+```
+
+## Why this matters
+
+The framework writes the clicked row to `/ui/selectedRow` before dispatching
+table row interactions. Use that path. See [[@path-ui-selected-row]].
+
+## Detection
+
+`mythik lint` rule **`spec-row-literal`** (severity: warning) catches `$row`
+in any spec value. Also runs during `mythik validate` and `mythik push`.
+See [[@cli-lint]].
+
+## Related concepts
+
+- [[@path-ui-selected-row]]
+- [[@primitive-table]]
+- [[@expression-state]]
+- [[@expression-template]]
+- [[@cli-lint]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 2.1`
+- `docs/consumer/ai-context-primitives.md § Table`
+- `docs/consumer/reference-doc.md § rule 69, 249`

package/docs/wiki/compiled/antipattern-row-template-capture.md

@@ -0,0 +1,42 @@
+---
+id: antipattern-row-template-capture
+title: Anti-pattern — `$item` directly in `$template`
+kind: pattern
+sources: [docs/consumer/ai-context-patterns.md#expression-resolution-contexts]
+---
+
+# Anti-pattern — `$item` directly in `$template`
+
+`$item` is a JSON expression, not a string token. **`$template` does NOT
+resolve `$item` directly.** Capture in `$let` first.
+
+## Wrong
+
+```json
+{ "$template": "Editing: ${ $item.name }" }     // BAD — does not work
+{ "$template": "Editing: ${ /item/name }" }      // BAD — wrong path
+```
+
+## Right
+
+```json
+{
+  "$let": { "x": { "$item": "name" } },
+  "$in": { "$template": "Editing: ${x}" }
+}
+```
+
+`${name}` references in `$template` resolve **only** `$let` bindings,
+plus `${/state/path}` for state reads. To bridge `$item` → `$template`,
+go through `$let`.
+
+## Related concepts
+
+- [[@expression-template]]
+- [[@expression-item-index]]
+- [[@expression-let-ref]]
+- [[@concept-expression-contexts]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-patterns.md § Expression Resolution Contexts → Key traps`

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

@@ -0,0 +1,72 @@
+---
+id: antipattern-store-save-bypass
+title: Anti-pattern — `store.save()` bypass
+kind: pattern
+sources: [docs/consumer/ai-context.md#cli-is-the-only-approved-path-for-spec-writes, docs/consumer/ai-context-runtime-semantics.md#54-specstore-layering--save-vs-saveversion-vs-cli-patch]
+---
+
+# Anti-pattern — `store.save()` from app code
+
+Calling `SpecStore.save()` directly from application code **bypasses
+validation** and produces silently-broken specs that fail only at render
+time.
+
+## Wrong
+
+```ts
+// In app code:
+import { SupabaseSpecStore } from 'mythik';
+
+const store = new SupabaseSpecStore({ ... });
+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 });
+```
+
+```bash
+# Shell:
+mythik push my-screen --from-file spec.json
+
+# Bulk:
+mythik push --from-dir ./specs/
+```
+
+## Why
+
+`SpecStore.save()` is `@internal` — JSDoc-marked. The CLI / engine path
+runs the document handler validation BEFORE persisting. Bypassing this
+skips validation entirely → renders fail with cryptic errors at runtime.
+
+## Detection (lint)
+
+`mythik lint` rule **`code-store-save-bypass`** (severity: **error**)
+matches `<Identifier>.save()` callees in code outside `packages/core/`
+and `packages/cli/`.
+
+**Known scope limitations** — does NOT detect:
+- `this.store.save()`
+- `<obj>.<store>.save()`
+- `(await getStore()).save()`
+
+These slip through the AST scanner. The lint rule is one layer of
+defense-in-depth, not a complete catch.
+
+## Related concepts
+
+- [[@concept-spec-store-interface]]
+- [[@concept-spec-store-layering]]
+- [[@cli-push]]
+- [[@cli-programmatic-api]]
+- [[@cli-lint]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § CLI is the only approved path for spec writes`
+- `docs/consumer/ai-context-runtime-semantics.md § 5.4`
+- `docs/consumer/reference-doc.md § rules 248, 249`

package/docs/wiki/compiled/antipattern-style-block-duplication.md

@@ -0,0 +1,56 @@
+---
+id: antipattern-style-block-duplication
+title: Anti-pattern — duplicate style blocks
+kind: pattern
+sources: [docs/consumer/ai-context-patterns.md#rule-dont-duplicate-style-blocks-across-specs]
+---
+
+# Anti-pattern — duplicate style blocks
+
+If the same rich style object appears in 2+ specs (or 2+ places in the
+same spec), extract to a template or variant. Duplication inflates DB
+storage, breaks DRY, makes updates O(N).
+
+## Wrong
+
+```json
+// screen-a.json
+{ "type": "button", "style": { "background": "linear-gradient(...)", "animation": "pulse 2s ...", ...20 lines } }
+
+// screen-b.json
+{ "type": "button", "style": { "background": "linear-gradient(...)", "animation": "pulse 2s ...", ...20 lines } }
+```
+
+## Right — extract to a template (composite)
+
+```json
+// appSpec.templates once
+"templates": { "button-pulse-cta": { ...full definition... } }
+
+// both screens
+{ "type": "button-pulse-cta", "props": { "label": "..." } }
+```
+
+## Or — extract to a variant (style-only)
+
+```json
+"tokens": { "components": { "button": { "ctaPulse": { ...style + states... } } } }
+
+// usage
+{ "type": "button", "props": { "variant": "ctaPulse", "label": "..." } }
+```
+
+## Decision
+
+See [[@concept-templates-vs-variants]] for the decision walk-through.
+
+## Related concepts
+
+- [[@concept-templates]]
+- [[@concept-component-variants]]
+- [[@concept-templates-vs-variants]]
+- [[@pattern-reusable-components]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-patterns.md § Rule: don't duplicate style blocks across specs`

package/docs/wiki/compiled/antipattern-submit-form-in-tx-confirm.md

@@ -0,0 +1,56 @@
+---
+id: antipattern-submit-form-in-tx-confirm
+title: Anti-pattern — `submitForm` in `transaction.confirm`
+kind: pattern
+sources: [docs/consumer/ai-context-patterns.md#submitform-in-transactionconfirm-is-not-recommended]
+---
+
+# Anti-pattern — `submitForm` in `transaction.confirm`
+
+`submitForm` is technically valid in any action context, but **inside
+`transaction.confirm` it conflicts** — `submitForm` includes its own
+validation gate and error handling, while the transaction engine handles
+rollback separately.
+
+## Wrong
+
+```json
+"confirm": [
+  { "action": "submitForm", "params": { "formId": "f", "url": "/api/save", "method": "POST", "body": {} } }
+]
+```
+
+The form's validation gate fires inside the transaction; if invalid,
+`submitForm` shows errors but the transaction engine sees no network
+attempt → no rollback path → ambiguous state.
+
+## Right — use plain `fetch` in `confirm`
+
+```json
+"confirm": [
+  { "action": "fetch", "params": {
+    "url": "/api/save",
+    "method": "POST",
+    "body": { "title": { "$state": "/form/title" } },
+    "target": "/tx/result"
+  }}
+]
+```
+
+Validate the form BEFORE the transaction (e.g., disable the trigger
+button via `$state: "/ui/forms/f/isValid"`):
+
+```json
+"disabled": { "$not": { "$state": "/ui/forms/f/isValid" } }
+```
+
+## Related concepts
+
+- [[@concept-transactions]]
+- [[@action-fetch]]
+- [[@action-submit-form]]
+- [[@concept-forms]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-patterns.md § submitForm in transaction.confirm is not recommended`

package/docs/wiki/compiled/cli-app-spec.md

@@ -0,0 +1,53 @@
+---
+id: cli-app-spec
+title: CLI on AppSpecs
+kind: concept
+sources: [docs/consumer/reference-doc.md#appspec--app-level-configuration]
+---
+
+# CLI on AppSpecs
+
+Same CLI commands work on AppSpec documents (`type: "app"`). **Detection
+is automatic.**
+
+## Examples
+
+```bash
+mythik manifest app-demo                                    # tree
+mythik elements app-demo tokens.colors                       # dot-notation for tokens
+mythik elements app-demo screens.task-manager                # dot-notation for screens
+mythik elements app-demo navigation.auth                     # dot-notation for navigation
+mythik elements app-demo sidebar,nav-item                    # layout elements (simple ID)
+mythik elements app-demo sidebar,tokens.colors,screens.task-manager  # mixed
+
+mythik patch app-demo '[{"op":"replace","path":"/tokens/colors/primary","value":"#2563EB"}]'
+mythik patch app-demo '[{"op":"replace","path":"/layout/elements/sidebar/props/style/width","value":280}]'
+mythik patch app-demo '[{"op":"add","path":"/screens/reports","value":{"label":"Reports","icon":"chart-bar"}}]'
+
+mythik validate app-demo
+```
+
+## Key differences from screen specs
+
+- **Elements live under `/layout/elements/`** (NOT `/elements/`).
+  See [[@antipattern-element-variant-top-level]] for the typical mix-up.
+- **Dot-notation** in `elements` for inspecting tokens, screens,
+  navigation, translations, sharedState.
+- **Patch paths** use full JSON Pointer: `/tokens/...`, `/screens/...`,
+  `/layout/elements/...`.
+- **Validation** includes cross-reference checks (screen existence,
+  roleAccess consistency).
+- **Translation key mismatches** are warnings, not errors.
+
+## Related concepts
+
+- [[@concept-app-spec]]
+- [[@cli-elements]]
+- [[@cli-patch]]
+- [[@cli-validate]]
+- [[@cli-overview]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § AppSpec — App-Level Configuration`
+- `docs/consumer/reference-doc.md § rule 62`

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

@@ -0,0 +1,46 @@
+---
+id: cli-config
+title: CLI config — `.mythikrc` + env vars
+kind: concept
+sources: [docs/consumer/reference-doc.md#configuration--never-pass-keys-inline]
+---
+
+# CLI config
+
+**Always** use `.mythikrc` + environment variables. **Never pass API keys
+as CLI flags** — they appear in terminal history, chat logs, and process
+lists.
+
+## `.mythikrc`
+
+```json
+{
+  "store": "supabase",
+  "supabase": {
+    "url": "https://xxx.supabase.co",
+    "apiKey": "$MYTHIK_API_KEY"
+  }
+}
+```
+
+## Env var
+
+```bash
+export MYTHIK_API_KEY="your-key"
+```
+
+The CLI resolves `$MYTHIK_API_KEY` at runtime.
+
+## Add to `.gitignore`
+
+```
+.mythikrc
+```
+
+## Related concepts
+
+- [[@cli-overview]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § Configuration — Never pass keys inline`

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

@@ -0,0 +1,73 @@
+---
+id: cli-contract
+title: `mythik contract` — frontend↔backend cross-validation
+kind: concept
+sources: [docs/consumer/reference-doc.md#typed-contract-sp4]
+---
+
+# `mythik contract`
+
+Cross-validates screen specs against api-specs before deploy. Only
+possible because both sides are declarative JSON.
+
+## Usage
+
+```bash
+# Single api-spec
+mythik contract --app app-demo --api ejecucion-api
+
+# Multiple api-specs (modular backends)
+mythik contract --app app-demo --api presupuesto-api,rrhh-api
+
+# Api-specs in separate table
+mythik contract --app app-demo --api ejecucion-api --api-table api_specs
+
+# Strip base URL
+mythik contract --app app-demo --api ejecucion-api --base-url http://localhost:3010
+
+# JSON output for CI/CD (exit code 1 on errors)
+mythik contract --app app-demo --api ejecucion-api --json
+```
+
+## 4 rules
+
+| Rule | Level | Checks |
+|---|---|---|
+| `endpoints-exist` | error | Every fetch URL in screens matches an endpoint, catalog, or builtin |
+| `fields-valid` | error | POST/PUT body fields exist in CRUD `insertable` / `updatable` |
+| `params-match` | warning | Query params match endpoint `params` config. `page`/`pageSize` always valid |
+| `permissions-consistent` | warning | If AppSpec `roleAccess` grants role access to a screen, endpoints used by that screen allow that role via `policies` |
+
+All include Levenshtein "did you mean?" suggestions.
+
+## Why this is unique
+
+The permissions-consistent rule — "Role X can access screen Y but API
+denies the action" — is only possible because both frontend (`roleAccess`)
+and backend (`policies`) are declarative JSON. In code-based systems, UI
+visibility and API permissions live in separate layers (rule 76).
+
+## Notes
+
+- **Duplicate findings collapsed** with `count` field (rule 79).
+- **Template domain URLs** (`http://${authDomain}/api/items`) normalized
+  to relative paths before matching (rule 80).
+- **`--base-url` is explicit only** — no auto-detection from authDomains.
+  Absolute URLs without `--base-url` emit a warning (rule 81).
+
+## Extensibility
+
+Rules are pluggable — adding a new rule is one file implementing
+`ContractRule` + adding to the rules array. No engine changes needed.
+
+## Related concepts
+
+- [[@pattern-fullstack-coherence]]
+- [[@concept-app-spec]]
+- [[@concept-api-spec]]
+- [[@concept-role-access]]
+- [[@cli-overview]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § Typed Contract (SP4)`

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

@@ -0,0 +1,37 @@
+---
+id: cli-delete
+title: `mythik delete` — with safety gate
+kind: concept
+sources: [docs/consumer/reference-doc.md#delete--with-safety-gate]
+---
+
+# `mythik delete`
+
+Deletes a spec. **Requires `--confirm`** — without it, only previews.
+
+## Usage
+
+Preview (no deletion):
+```bash
+mythik delete task-manager
+# → Screen "task-manager" (107 elements). Use --confirm to delete.
+```
+
+Delete with backup:
+```bash
+mythik delete task-manager --confirm > backup.json
+```
+
+Plain delete:
+```bash
+mythik delete task-manager --confirm
+```
+
+## Related concepts
+
+- [[@cli-pull]]
+- [[@cli-overview]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § Delete — With Safety Gate`

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

@@ -0,0 +1,44 @@
+---
+id: cli-docs
+title: `mythik docs` - bundled AI documentation
+kind: cli
+sources: [docs/consumer/ai-context.md#public-package-names, docs/consumer/ai-context.md#cli-workflow, docs/consumer/reference-doc.md#cli--spec-modification-via-mythik-cli]
+---
+
+# `mythik docs`
+
+The `mythik` npm package includes the documentation an AI agent needs to use the framework:
+
+- `docs/llms.txt`
+- `docs/consumer/ai-context.md`
+- `docs/consumer/reference-doc.md`
+- `docs/wiki/compiled/README.md`
+- `docs/wiki/compiled/_index.md`
+
+Use the CLI to locate the bundled docs after install:
+
+```bash
+mythik docs path
+```
+
+Use `copy` when the workflow needs a project-local folder to hand to an AI agent:
+
+```bash
+mythik docs copy ./mythik-docs
+```
+
+`copy` refuses to overwrite a non-empty target directory unless `--force` is provided.
+
+## Agent contract
+
+Before generating or modifying specs, point the AI at the docs path and start from
+`llms.txt`, `consumer/ai-context.md`, and `wiki/compiled/README.md`.
+
+For existing specs, continue to use the required edit loop in [[@cli-existing-spec-edit-loop]]:
+`manifest` -> `elements` -> `patch --from-file` -> verify.
+
+## Related concepts
+
+- [[@cli-overview]]
+- [[@cli-existing-spec-edit-loop]]
+- [[@concept-public-package-names]]