@akanjs/cli 2.4.2-rc.2 → 3.0.0-alpha.0

package/.build-stamp

@@ -1 +1 @@
-6f93500c73ae1edf5c631b83d87c67fb74323b45daf56ae9a89e6c48596c14b8
+ce7835b9c7e649ebc830a1ac94fa9db80a2c2aaec64459445780b8dc7bd627a0

package/abstractCompactor-rk6twzvj.js

@@ -0,0 +1,103 @@
+// @bun
+import {
+  AiSession
+} from "./index-3pgtw35d.js";
+import {
+  AbstractDoc
+} from "./index-0wae5ebk.js";
+import"./index-6pz1j0zj.js";
+import"./index-67546d0j.js";
+import"./index-r24hmh0q.js";
+
+// pkgs/@akanjs/devkit/abstractCompactor.ts
+import { Logger } from "akanjs/common";
+import chalk from "chalk";
+class AbstractCompactor {
+  static #reviewRequest = `Review the compacted file you just wrote against the original.
+- Did you drop an invariant, a security reason, or a workflow step that the source files cannot show by themselves? Restore it.
+- Did you keep anything that only restates code, scaffold wording, or history? Remove it.
+- Is it in the same language as the original, within the line budget, and one short line per bullet?
+Respond with exactly one \`\`\`markdown code block holding the corrected file and nothing else. If nothing needs to change, repeat the file unchanged.`;
+  #sys;
+  #minLines;
+  #interactive;
+  constructor(sys, { minLines = AbstractDoc.compactMinLines, interactive = false } = {}) {
+    this.#sys = sys;
+    this.#minLines = minLines;
+    this.#interactive = interactive;
+  }
+  async compactAll({ module } = {}) {
+    const docs = await AbstractDoc.findAll(this.#sys, { module });
+    const targets = docs.filter((doc) => doc.lineCount > this.#minLines);
+    const reports = [];
+    for (const doc of targets)
+      reports.push(await this.compact(doc));
+    return { scanned: docs.length, reports };
+  }
+  async compact(doc) {
+    const session = new AiSession("compactAbstract", {
+      workspace: this.#sys.workspace,
+      cacheKey: `${this.#sys.name}-${doc.moduleName}`
+    });
+    const approve = !this.#interactive;
+    const compacted = await session.editMarkdown(this.#request(doc), { approve });
+    const reviewed = await session.editMarkdown(AbstractCompactor.#reviewRequest, { approve });
+    const next = [reviewed, compacted].map((candidate) => candidate.trim()).find((candidate) => doc.canReplaceWith(candidate));
+    const beforeLines = doc.lineCount;
+    if (!next) {
+      Logger.rawLog(chalk.yellow(`${doc.path}: the editor returned no shorter abstract, keeping the current file`));
+      return { path: doc.path, beforeLines, afterLines: beforeLines, status: "failed" };
+    }
+    if (next === doc.content.trim())
+      return { path: doc.path, beforeLines, afterLines: beforeLines, status: "unchanged" };
+    const content = `${next}
+`;
+    await this.#sys.writeFile(doc.path, content);
+    return { path: doc.path, beforeLines, afterLines: AbstractDoc.lineCountOf(content), status: "compacted" };
+  }
+  #targetShape(kind) {
+    if (kind === "other")
+      return "  - keep the headings that still carry information and drop the rest; do not impose a new structure";
+    return [
+      "  - `# <name> Abstract` title line",
+      "  - one declarative sentence naming what this module owns",
+      "  - `## Rules` \u2014 two to five bullets, each an invariant the code cannot show by itself",
+      "  - optional `## Workflow` \u2014 the lifecycle as an arrow chain (`draft -> signed -> active`) or a few bullets"
+    ].join(`
+`);
+  }
+  #request(doc) {
+    return `You are compacting an Akan.js abstract file.
+
+An abstract is the summary a coding agent reads before changing a module. Repeated edits have made this one
+bloated, and it has to shrink back to what the source files cannot show by themselves.
+
+# Target file
+${this.#sys.type}s/${this.#sys.name}/${doc.path} (${doc.kind} module "${doc.moduleName}", ${doc.lineCount} lines)
+
+# Source files in the same folder
+${doc.siblingFiles.join(", ") || "none"}
+
+# Current content
+\`\`\`markdown
+${doc.content}
+\`\`\`
+
+# Rules for the compacted file
+- Write it in the SAME language as the current content. Never translate.
+- Keep every invariant, constraint, security reason, and workflow step that the source files cannot show by
+  themselves. Merge duplicates instead of dropping either one.
+- Delete what the code already states: field lists, types, labels, signatures, file lists, and imports.
+- Delete scaffold and placeholder wording, changelog or migration history, TODOs, and any instruction about
+  reading or updating this file.
+- Never invent a rule that the current content does not state.
+- Keep every bullet to one short line, and stay under ${AbstractDoc.compactMinLines} lines in total.
+- Shape:
+${this.#targetShape(doc.kind)}
+
+Respond with exactly one \`\`\`markdown code block holding the whole new file and nothing else.`;
+  }
+}
+export {
+  AbstractCompactor
+};

package/{agent.command-ej4g9pbb.js → agent.command-jfz8yfwy.js}

@@ -1,17 +1,18 @@
 // @bun
 import {
   AgentScript
-} from "./index-40w1kqp1.js";
-import"./index-v9jqrdd1.js";
-import"./index-pfnh87f9.js";
-import"./index-xftstr5s.js";
+} from "./index-n0z3f2xg.js";
+import"./index-4yp06pn1.js";
+import"./index-4zgs8g1w.js";
+import"./index-xwgm94zr.js";
 import {
   Workspace,
   command
-} from "./index-d0h48d2f.js";
-import"./index-xwfg9bam.js";
-import"./index-67546d0j.js";
+} from "./index-jk9q6pse.js";
+import"./index-jtm86byd.js";
 import"./index-6pz1j0zj.js";
+import"./index-xys926f2.js";
+import"./index-67546d0j.js";
 import"./index-r24hmh0q.js";
 
 // pkgs/@akanjs/cli/agent/agent.command.ts

package/{application.command-smn51a28.js → application.command-3smsv7mq.js}

@@ -1,23 +1,26 @@
 // @bun
+import {
+  AbstractDoc
+} from "./index-0wae5ebk.js";
 import {
   ApplicationScript
-} from "./index-panyahn4.js";
+} from "./index-ev6rjw9n.js";
 import {
   getMobileTargetChoices
 } from "./index-76rn3g2c.js";
-import"./index-s9s0n5fz.js";
+import"./index-cn24dcqn.js";
 import {
   App,
   Exec,
   Sys,
   Workspace,
   command
-} from "./index-d0h48d2f.js";
+} from "./index-jk9q6pse.js";
 import"./index-fgc8r6dj.js";
-import"./index-xwfg9bam.js";
-import"./index-67546d0j.js";
 import"./index-bjpxzr6s.js";
+import"./index-jtm86byd.js";
 import"./index-6pz1j0zj.js";
+import"./index-67546d0j.js";
 import"./index-r24hmh0q.js";
 
 // pkgs/@akanjs/cli/application/application.command.ts
@@ -39,6 +42,13 @@ class ApplicationCommand extends command("application", [ApplicationScript], ({
   sync: target({ desc: "Sync dependencies and configuration for an app or library" }).with(Sys).exec(async function(sys) {
     await this.applicationScript.sync(sys);
   }),
+  compact: target({ desc: "Compact the *.abstract.md files of an app or library with the AI editor" }).with(Sys).option("module", String, { desc: "single module to compact", nullable: true }).option("minLines", Number, {
+    flag: "n",
+    desc: "only compact abstracts longer than this",
+    default: AbstractDoc.compactMinLines
+  }).option("interactive", Boolean, { desc: "confirm or refine each rewrite", default: false }).exec(async function(sys, module, minLines, interactive) {
+    await this.applicationScript.compact(sys, { module, minLines, interactive });
+  }),
   script: target({ desc: "Run a custom script in the application" }).with(App).arg("filename", String, { desc: "name of script", nullable: true }).exec(async function(app, filename) {
     await this.applicationScript.script(app, filename);
   }),

package/{applicationBuildRunner-554a2vnk.js → applicationBuildRunner-aq7mb3z6.js}

@@ -4,7 +4,8 @@ import {
   CsrArtifactBuilder,
   SsrBaseArtifactBuilder,
   precompressArtifacts
-} from "./index-7k9sj7j5.js";
+} from "./index-pyt2b4nw.js";
+import"./index-xjd3rqzj.js";
 import"./index-rh16j3c7.js";
 import"./index-bjpxzr6s.js";
 import {

package/buildBatch.proc.js

@@ -1,19 +1,20 @@
 // @bun
-import {
-  AppExecutor,
-  WorkspaceExecutor
-} from "./index-xwfg9bam.js";
-import"./index-67546d0j.js";
 import {
   CsrArtifactBuilder,
   CssCompiler,
   FontOptimizer,
   PagesBundleBuilder,
   SsrBaseArtifactBuilder
-} from "./index-7k9sj7j5.js";
+} from "./index-pyt2b4nw.js";
+import"./index-xjd3rqzj.js";
 import"./index-rh16j3c7.js";
 import"./index-bjpxzr6s.js";
+import {
+  AppExecutor,
+  WorkspaceExecutor
+} from "./index-jtm86byd.js";
 import"./index-6pz1j0zj.js";
+import"./index-67546d0j.js";
 import"./index-r24hmh0q.js";
 
 // pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts

package/{capacitorApp-yg9b4ajz.js → capacitorApp-q3mpmkkz.js}

@@ -24,11 +24,11 @@ import {
   selectLocalDevHost,
   sortIosRunTargets,
   writeRootCapacitorConfig
-} from "./index-zfp1gz9f.js";
+} from "./index-sggm9qkv.js";
 import"./index-76rn3g2c.js";
-import"./index-xwfg9bam.js";
-import"./index-67546d0j.js";
+import"./index-jtm86byd.js";
 import"./index-6pz1j0zj.js";
+import"./index-67546d0j.js";
 import"./index-r24hmh0q.js";
 export {
   writeRootCapacitorConfig,

package/{cloud.command-2v7ga38h.js → cloud.command-rk4e9vrt.js}

@@ -1,25 +1,25 @@
 // @bun
 import {
   CloudScript
-} from "./index-majzj044.js";
-import"./index-j3j3qc9j.js";
+} from "./index-f4gqk0dd.js";
+import"./index-ktprgc5g.js";
+import"./index-e3qskyt2.js";
 import {
   GlobalConfig
-} from "./index-nsj2ftxj.js";
-import"./index-panyahn4.js";
+} from "./index-3pgtw35d.js";
+import"./index-ev6rjw9n.js";
 import"./index-76rn3g2c.js";
-import"./index-s9s0n5fz.js";
-import"./index-z36qzgzp.js";
+import"./index-cn24dcqn.js";
 import {
   Workspace,
   command
-} from "./index-d0h48d2f.js";
+} from "./index-jk9q6pse.js";
 import"./index-fgc8r6dj.js";
-import"./index-xwfg9bam.js";
-import"./index-46tjzh6s.js";
-import"./index-67546d0j.js";
 import"./index-bjpxzr6s.js";
+import"./index-jtm86byd.js";
 import"./index-6pz1j0zj.js";
+import"./index-46tjzh6s.js";
+import"./index-67546d0j.js";
 import"./index-r24hmh0q.js";
 
 // pkgs/@akanjs/cli/cloud/cloud.command.ts

package/commandManifest.json

@@ -1 +1 @@
-{"byCommand":{"create-workspace":"workspace","generate-agent-rules":"workspace","lint":"workspace","lint-all":"workspace","sync-all":"workspace","init":"workspace","agent":"agent","create-application":"application","remove-application":"application","sync":"application","script":"application","console":"application","build":"application","b":"application","typecheck":"application","t":"application","test":"application","build-ios":"application","bi":"application","build-android":"application","ba":"application","start":"application","s":"application","start-ios":"application","si":"application","start-android":"application","sa":"application","release-ios":"application","release-android":"application","release-source":"application","codepush":"application","dbup":"application","dbdown":"application","configure-app":"application","create-library":"library","remove-library":"library","sync-library":"library","install-library":"library","start-registry":"localRegistry","reset-registry":"localRegistry","smoke-registry":"localRegistry","version":"package","create-package":"package","remove-package":"package","sync-package":"package","build-package":"package","verify-dist-package":"package","verify-akan-publish-packages":"package","create-module":"module","remove-module":"module","create-service":"module","create-view":"module","create-unit":"module","create-template":"module","create-crud-page":"page","context":"context","doctor":"context","mcp-install":"context","mcp":"context","mcp-call":"context","login":"cloud","logout":"cloud","set-llm":"cloud","reset-llm":"cloud","ask":"cloud","deploy-akan":"cloud","update":"cloud","download-env":"cloud","upload-env":"cloud","guideline":"guideline","generate-instruction":"guideline","update-instruction":"guideline","generate-document":"guideline","reapply-instruction":"guideline","create-scalar":"scalar","remove-scalar":"scalar","create-ui":"primitive","add-field":"primitive","add-enum-field":"primitive","quality":"quality","repair":"repair","workflow":"workflow"}}
+{"byCommand":{"create-workspace":"workspace","generate-agent-rules":"workspace","lint":"workspace","lint-all":"workspace","sync-all":"workspace","init":"workspace","agent":"agent","create-application":"application","remove-application":"application","sync":"application","compact":"application","script":"application","console":"application","build":"application","b":"application","typecheck":"application","t":"application","test":"application","build-ios":"application","bi":"application","build-android":"application","ba":"application","start":"application","s":"application","start-ios":"application","si":"application","start-android":"application","sa":"application","release-ios":"application","release-android":"application","release-source":"application","codepush":"application","dbup":"application","dbdown":"application","configure-app":"application","create-library":"library","remove-library":"library","sync-library":"library","install-library":"library","start-registry":"localRegistry","reset-registry":"localRegistry","smoke-registry":"localRegistry","version":"package","create-package":"package","remove-package":"package","sync-package":"package","build-package":"package","verify-dist-package":"package","verify-akan-publish-packages":"package","create-module":"module","remove-module":"module","create-service":"module","create-view":"module","create-unit":"module","create-template":"module","create-crud-page":"page","context":"context","doctor":"context","mcp-install":"context","mcp":"context","mcp-call":"context","login":"cloud","logout":"cloud","set-llm":"cloud","reset-llm":"cloud","ask":"cloud","deploy-akan":"cloud","update":"cloud","download-env":"cloud","upload-env":"cloud","guideline":"guideline","generate-instruction":"guideline","update-instruction":"guideline","generate-document":"guideline","reapply-instruction":"guideline","create-scalar":"scalar","remove-scalar":"scalar","create-ui":"primitive","add-field":"primitive","add-enum-field":"primitive","quality":"quality","repair":"repair","workflow":"workflow"}}

package/{context.command-hhjyjtp7.js → context.command-ygzyb0xb.js}

@@ -1,27 +1,28 @@
 // @bun
 import {
   ContextScript
-} from "./index-y1e79mz3.js";
-import"./index-7ppn9v4n.js";
-import"./index-h971erkm.js";
-import"./index-z5v766nx.js";
-import"./index-acwxfncv.js";
-import"./index-04as43rp.js";
-import"./index-dgeaqwmw.js";
+} from "./index-h0bngh79.js";
+import"./index-b978vs2e.js";
+import"./index-csqk9z5j.js";
+import"./index-r4w8cry5.js";
+import"./index-vhv3xnjz.js";
+import"./index-hjzr8ja1.js";
+import"./index-fmgbwsr5.js";
 import"./index-ss469dec.js";
-import"./index-zfp1gz9f.js";
-import"./index-v9jqrdd1.js";
-import"./index-pfnh87f9.js";
-import"./index-xftstr5s.js";
-import"./index-nsj2ftxj.js";
+import"./index-sggm9qkv.js";
+import"./index-3pgtw35d.js";
+import"./index-4yp06pn1.js";
+import"./index-4zgs8g1w.js";
+import"./index-xwgm94zr.js";
 import"./index-76rn3g2c.js";
 import {
   Workspace,
   command
-} from "./index-d0h48d2f.js";
-import"./index-xwfg9bam.js";
-import"./index-67546d0j.js";
+} from "./index-jk9q6pse.js";
+import"./index-jtm86byd.js";
 import"./index-6pz1j0zj.js";
+import"./index-xys926f2.js";
+import"./index-67546d0j.js";
 import"./index-r24hmh0q.js";
 
 // pkgs/@akanjs/cli/context/context.command.ts

package/{guideline.command-vj956kfr.js → guideline.command-1m1ctar3.js}

@@ -1,23 +1,23 @@
 // @bun
-import {
-  Prompter
-} from "./index-xftstr5s.js";
 import {
   AiSession
-} from "./index-nsj2ftxj.js";
+} from "./index-3pgtw35d.js";
+import {
+  Prompter
+} from "./index-xwgm94zr.js";
 import {
   Workspace,
   command,
   runner,
   script
-} from "./index-d0h48d2f.js";
+} from "./index-jk9q6pse.js";
 import {
   getDirname
-} from "./index-xwfg9bam.js";
+} from "./index-jtm86byd.js";
+import"./index-6pz1j0zj.js";
 import {
   FileSys
 } from "./index-67546d0j.js";
-import"./index-6pz1j0zj.js";
 import"./index-r24hmh0q.js";
 
 // pkgs/@akanjs/cli/guideline/guideline.script.ts
@@ -151,7 +151,7 @@ ${await this.getDocumentation("framework")}
 2. Documentation page writing method
 ${await this.getDocumentation("docPageRule")}
 
-3. CSS rule with TailwindCSS and DaisyUI
+3. CSS rule with TailwindCSS and akanjs/ui primitives (semantic tokens; no daisyui)
 ${await this.getDocumentation("cssRule")}
 
 I want to update the Next.js server-side page located at ${writePath}.
@@ -165,8 +165,8 @@ Please update this page with the latest content below. A great design applicatio
 ${instruction}
 
 Please follow these CSS rules when writing:
-- Use tailwindcss
-- Use className from the daisyui library
+- Use tailwindcss with the semantic design tokens (bg-background, text-foreground, bg-primary, text-muted-foreground, border-border, \u2026)
+- Use akanjs/ui primitives (Button, Badge, Input, Field, \u2026) instead of raw daisyui classes; do not use daisyui
 
 Please return only the file result in the following format for easy parsing.
 \`\`\`tsx

package/guidelines/componentRule/componentRule.instruction.md

@@ -4,7 +4,7 @@
 Use this for shared UI rules across module, scalar, app UI, and docs components.
 
 ## Ownership
-- Accept `className?: string` for reusable components and forward it through `clsx`.
+- Accept `className?: string` for reusable components and forward it through `cn` (from `akanjs/client`), or as the second argument of a recipe (`buttonRecipe(variants, className)`).
 - Use semantic HTML and accessible labels for interactive elements.
 - Use `akanjs/ui` and project UI libraries before adding new primitives.
 - Keep presentation components small; move page composition to Zone and actions to Util or store.
@@ -26,7 +26,7 @@ Use this for shared UI rules across module, scalar, app UI, and docs components.
 ## Codegen Rules
 - Do not put business workflow decisions in render code.
 - Do not use undocumented UI components or props.
-- Do not use hardcoded colors when DaisyUI semantic classes work.
+- Do not use hardcoded colors when semantic token classes (`bg-primary`, `text-foreground`, …) work.
 - Do not create broad component abstractions before repeated patterns exist.
 
 ## Review Checklist

package/guidelines/cssRule/cssRule.generate.json

@@ -1,6 +1,6 @@
 {
   "title": "CSS Rule",
-  "description": "Tailwind and DaisyUI styling rules",
+  "description": "Tailwind and akanjs/ui (semantic token) styling rules",
   "group": "core",
   "docsSource": "apps/akan/page/(docs)/docs/arch/css.tsx",
   "codegenPriority": 3,

package/guidelines/cssRule/cssRule.instruction.md

@@ -1,46 +1,69 @@
 # CSS Rule Guideline
 
 ## Purpose
-Use TailwindCSS and DaisyUI in a theme-safe, composable way for Akan UI and docs pages.
+Use TailwindCSS with Akan's semantic design-token layer and the `akanjs/ui` primitives for app UI and docs pages.
 
 ## Ownership
 - Use Tailwind utility classes for layout, spacing, typography, and responsive behavior.
-- Use DaisyUI semantic tokens such as base, primary, secondary, accent, info, success, warning, and error.
-- Use `clsx` from `akanjs/client` for conditional class composition.
-- Forward `className` at the end of composed class strings to allow callers to extend styles.
-
-## Current Akan Patterns
-- Prefer mobile-first responsive classes.
-- Use card, btn, input, badge, alert, divider, tabs, modal, and other documented DaisyUI classes when they match the design.
-- Use consistent density and spacing within one component family.
-- Keep custom CSS files rare and scoped to cases utilities cannot express cleanly.
-
-## Theme Customization (`apps/<app>/page/styles.css`)
-- The app theme is defined in `apps/<app>/page/styles.css` with daisyUI v5 `@plugin "daisyui/theme"` blocks (typically `light` and a `default: true` `dark`).
-- Brand-level customization means tuning the whole theme block, not only the color tokens. A theme that only changes `--color-*` still looks like the default framework skin.
-- Color tokens: `--color-primary`, `--color-secondary`, `--color-accent`, `--color-neutral`, `--color-info`, `--color-success`, `--color-warning`, `--color-error`, `--color-base-100/200/300`, and their `*-content` pairs.
-- Shape and feel tokens (set these too):
-  - `--radius-selector` — rounding for checkbox, toggle, badge.
-  - `--radius-field` — rounding for button, input, select, tab.
-  - `--radius-box` — rounding for card, modal, alert.
-  - `--size-selector`, `--size-field` — base scale (density) of selector and field controls.
-  - `--border` — component border width (e.g. `1px`, `2px`).
-  - `--depth` — `0` flat, `1` adds a subtle 3D lift to components.
-  - `--noise` — `0` off, `1` adds a grain texture to surfaces.
-- Keep shape/feel tokens consistent across the light and dark theme blocks unless the design deliberately differs by mode.
-
-## When Utilities Are Not Enough
-- Prefer theme tokens and DaisyUI component classes over one-off utility stacks that re-implement a component's look.
-- When a framework `akanjs/ui` component is structurally too restrictive, re-skin it with a `page/**/_overrides.tsx` slot override (see the componentRule guideline), not with `!important` utilities or a fork.
+- Use Akan's semantic color tokens — never a raw Tailwind palette color (`bg-blue-500`) or a hex value:
+  - Surfaces/text: `bg-background`, `text-foreground`, `bg-muted`, `text-muted-foreground`, `bg-card`, `bg-popover`, `border-border`, `border-input`, `ring-ring`.
+  - Brand/status: `primary`, `secondary`, `accent`, `destructive`, `success`, `warning`, `info`, `neutral`, `open` — each with a `-foreground` pair for text on that surface (e.g. `bg-primary text-primary-foreground`).
+- Compose classes with `cn` from `akanjs/client` (token-aware tailwind-merge) — the only class-combining function. No object syntax: write `cond && "x"`.
+- Forward `className` last so callers can extend styles.
+
+## Recipe Layer
+- Reusable or variant-like styling belongs in a recipe (a cva-style factory), not repeated inline class stacks.
+- Framework primitives ship recipes: `buttonRecipe` and `badgeRecipe` from `akanjs/ui`. Call them as `buttonRecipe(variants, className?)` — the second argument is merged automatically, so you never wrap it in `cn()`:
+  - `buttonRecipe({ variant: "primary", size: "lg" }, "w-full rounded-2xl")`
+- Prefer the `akanjs/ui` primitives (`Button`, `Badge`, `Input`, `Field`, `Table` …) over re-implementing a component's look with utility stacks. There is **no `Card`/`Box` primitive** — a card/box is a recipe surface (e.g. `appCard`), not an `akanjs/ui` component; do not `import { Card }`.
+- App-specific repeated surfaces go one-per-file in `apps/<app>/ui/Recipe/` (server-safe, no `"use client"`) via `recipe(tv({ base, variants }))`, imported from `@apps/<app>/ui`. App recipes **extend** (surfaces the lib lacks — chat bubble, tile); they never re-define a lib component in parallel.
+- Full recipe authoring/consumption policy: the `recipeRule` guideline. Never guess recipe names/imports — the authoritative list is `AGENTS.md` `## UI Recipes` plus the `list_recipes` tool.
+
+## Customization Decision (where a design delta goes)
+Screen code is invariant — a plain `<Button variant="primary">` never changes. Only these config files do:
+- **Theme differs** (color/radius/font) → override token *values* in `apps/<app>/page/styles.css`.
+- **A lib component's look differs** → recipe override: `export default override({ recipes: { button: neonButtonRecipe } })` in a `page/**/_overrides.tsx`. Every `<Button>` in that route subtree re-skins; behavior (async states, focus, a11y) is untouched. The swap recipe must accept the framework recipe's full variant surface.
+- **Structure/behavior differs** (modal → drawer) → component override (`override({ Modal: BrandModal })`), reassembling headless parts.
+- **A surface the lib lacks** → a new app recipe (extension).
+- Do not fight the cascade with `!important`, and when the same inline className tweak repeats, promote it to a recipe override or a variant.
+
+## Theme Declaration (`apps/<app>/page/styles.css`)
+- The file imports Tailwind and the framework tokens, then overrides token *values* per theme:
+  ```css
+  @import "tailwindcss";
+  @import "akanjs/ui/styles.css";
+
+  :root,
+  [data-theme="dark"] {
+    --background: #1a1a1a;
+    --foreground: #ffffff;
+    --primary: #ff493b;
+    --primary-foreground: #ffffff;
+    --muted: #2a2a2a;
+    --border: #3a3a3a;
+  }
+  [data-theme="light"] {
+    --background: #fafafa;
+    --foreground: #2c3e50;
+    --primary: #c33c32;
+    --primary-foreground: #ffffff;
+    --muted: #f5f5f5;
+    --border: #e5e5e5;
+  }
+  ```
+- The framework maps these variables to Tailwind color names (`@theme inline` in `akanjs/ui/styles.css`), so a class like `bg-primary` / `text-foreground` resolves to different colors per `data-theme` — the app only sets values, never re-declares the mapping.
+- Switching themes is toggling the `data-theme` attribute. Keep every token defined in both the dark and light blocks.
+- Radius uses `rounded-box` (cards/modals), `rounded-field` (buttons/inputs), `rounded-selector` (toggles/checkboxes).
 
 ## Codegen Rules
-- Do not hardcode hex colors or one-off brand colors unless the existing file already defines that design system.
-- Do not use important flags to fight component composition.
+- Do not hardcode hex or raw-palette colors (`bg-red-500`, `#ff0000`); use semantic tokens.
+- Do not put inline color literals in `style={{ }}`; use token classes.
+- Do not use `!important` to fight component composition.
 - Do not hide focus states on interactive elements.
-- Do not add global CSS for one component-specific layout.
+- When an `akanjs/ui` component is structurally too restrictive, re-skin it with a `page/**/_overrides.tsx` slot override (see the componentRule guideline), not `!important` utilities or a fork.
 
 ## Review Checklist
-- The instruction points to current docs pages, not removed docs routes.
-- Generated examples use current Akan builder APIs and scanner-friendly filenames.
+- All color goes through semantic tokens — no raw palette, no hex, no inline color.
+- Repeated/variant styling uses a recipe; class composition uses `cn` (never raw `twMerge`/`clsx` imports).
+- The instruction points to current docs pages and current Akan builder APIs.
 - The output contract tells the model which file paths to return.
-- The guide avoids broad framework essays when a concrete file rule is better.

package/guidelines/framework/framework.instruction.md

@@ -25,7 +25,7 @@ Use this as the compact framework context for AI codegen. It should explain how
 ## Theming And UI Customization
 When a request implies a distinct look and feel, do not stop at colors — customize both the theme and, when needed, the components.
 
-- **Theme (`apps/<app>/page/styles.css`).** The app theme is one or more daisyUI v5 `@plugin "daisyui/theme"` blocks. Match the brand by tuning the whole block, not only the `--color-*` tokens: set corner rounding (`--radius-selector`, `--radius-field`, `--radius-box`), control density (`--size-selector`, `--size-field`), outline weight (`--border`), and surface treatment (`--depth`, `--noise`). New workspaces ship these knobs at neutral defaults so they are visible to tune. Fetch `get_guideline` with `cssRule` for the full variable reference before a deep theme pass.
+- **Theme (`apps/<app>/page/styles.css`).** The app imports Tailwind and `akanjs/ui/styles.css`, then overrides semantic token *values* per theme under `:root, [data-theme="dark"]` and `[data-theme="light"]` (`--background`, `--foreground`, `--primary`, `--muted`, `--border`, … each with a `-foreground` pair for text). The framework maps them to Tailwind color names, so `bg-primary` / `text-foreground` follow the `data-theme` attribute; corner rounding uses `--radius-box` / `--radius-field`. Fetch `get_guideline` with `cssRule` for the full token set before a deep theme pass.
 - **Components (`page/**/_overrides.tsx`).** When a default `akanjs/ui` component (Button, Modal, Table, Input, Select, …) is too restrictive for the design, re-skin it per route instead of forking, wrapping, or fighting it with utility classes. Write a drop-in replacement in `apps/<app>/ui/` typed against the slot contract (`AkanModalComponent`, or `AkanUiOverrides["<Slot>"]`), composing the framework's headless parts, then bind it in a `page/**/_overrides.tsx` manifest with a single `export default override({ Slot: BrandComponent })`. Overrides cascade down the route tree like layouts (closest ancestor wins). Fetch `get_guideline` with `componentRule` and read the `references/ui/customize` docs page for the slot list and patterns.
 
 ## Review Checklist

package/guidelines/recipeRule/recipeRule.generate.json

@@ -0,0 +1,31 @@
+{
+  "title": "Recipe Rule",
+  "description": "Akan UI recipe authoring and consumption rules (reusable-look layer)",
+  "group": "core",
+  "docsSource": "apps/akan/page/(docs)/docs/arch/ui-recipe.tsx",
+  "codegenPriority": 3,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "docs",
+      "description": "Current docs source for Recipe Rule",
+      "path": "apps/akan/page/(docs)/docs/arch/ui-recipe.tsx"
+    },
+    {
+      "type": "example",
+      "description": "Existing recipe definitions",
+      "path": "{apps,libs}/*/ui/Recipe/*.ts",
+      "sample": 4
+    }
+  ],
+  "update": {
+    "filePath": "./recipeRule.instruction.md",
+    "contents": ["purpose", "ownership", "consuming", "authoring", "codegen rules", "review checklist"],
+    "rules": [
+      "Use current Akan APIs only",
+      "Keep output parseable for codegen",
+      "Include ownership boundaries and review checklist"
+    ]
+  },
+  "page": "apps/akan/page/(docs)/docs/arch/ui-recipe.tsx"
+}