@akanjs/cli 3.0.0-alpha.4 → 3.0.0-alpha.6

package/{repair.command-nakkq2zp.js → repair.command-mfv749ha.js}

@@ -1,16 +1,16 @@
 // @bun
 import {
   RepairRunner
-} from "./index-b978vs2e.js";
-import"./index-4yp06pn1.js";
-import"./index-4zgs8g1w.js";
+} from "./index-6npsfpxr.js";
+import"./index-jn9vfpwz.js";
+import"./index-m4kpmmtj.js";
 import {
   Workspace,
   command,
   script
-} from "./index-jk9q6pse.js";
-import"./index-jtm86byd.js";
-import"./index-6pz1j0zj.js";
+} from "./index-jkynkyfk.js";
+import"./index-47qxw1tz.js";
+import"./index-mxvakhsm.js";
 import"./index-xys926f2.js";
 import"./index-67546d0j.js";
 import"./index-r24hmh0q.js";

package/{scalar.command-fjq272gs.js → scalar.command-hs3nwzv1.js}

@@ -1,19 +1,19 @@
 // @bun
 import {
   ScalarScript
-} from "./index-fmgbwsr5.js";
+} from "./index-wrrb8rxk.js";
 import"./index-ss469dec.js";
-import"./index-3pgtw35d.js";
+import"./index-0cj2zxbm.js";
 import {
   renderPrimitiveReport
-} from "./index-4zgs8g1w.js";
-import"./index-xwgm94zr.js";
+} from "./index-m4kpmmtj.js";
+import"./index-qp089jp0.js";
 import {
   Sys,
   command
-} from "./index-jk9q6pse.js";
-import"./index-jtm86byd.js";
-import"./index-6pz1j0zj.js";
+} from "./index-jkynkyfk.js";
+import"./index-47qxw1tz.js";
+import"./index-mxvakhsm.js";
 import"./index-67546d0j.js";
 import"./index-r24hmh0q.js";
 

package/templates/lib/db.ts

@@ -16,7 +16,9 @@ ${databaseModules.map((module) => `import * as ${module}Db from "./${module}/${m
 ${libs.map((lib) => `export { db as ${lib} } from "@libs/${lib}/server";`).join("\n")}
 
 ${databaseModules.map((module) => `class ${capitalize(module)}Input extends by(cnst.${capitalize(module)}Input) {}`).join("\n")}
+${databaseModules.map((module) => `class ${capitalize(module)}Insight extends by(cnst.${capitalize(module)}Insight) {}`).join("\n")}
 ${databaseModules.length ? `export type { ${databaseModules.map((module) => `${capitalize(module)}Input`).join(", ")} };` : ""}
+${databaseModules.length ? `export type { ${databaseModules.map((module) => `${capitalize(module)}Insight`).join(", ")} };` : ""}
 
 ${scalarModules.map((module) => `export type * from "./__scalar/${module}/${module}.document";`).join("\n")}
 ${databaseModules.map((module) => `export type * from "./${module}/${module}.document";`).join("\n")}
@@ -24,7 +26,7 @@ ${databaseModules.map((module) => `export type * from "./${module}/${module}.doc
 ${databaseModules
   .map((module) => {
     const names = { Module: module.charAt(0).toUpperCase() + module.slice(1) };
-    return `export const ${module} = DatabaseRegistry.buildModel("${module}" as const, ${names.Module}Input, ${module}Db.${names.Module}, ${module}Db.${names.Module}Model, cnst.${names.Module}, cnst.${names.Module}Insight, ${module}Db.${names.Module}Filter);`;
+    return `export const ${module} = DatabaseRegistry.buildModel("${module}" as const, ${names.Module}Input, ${module}Db.${names.Module}, ${module}Db.${names.Module}Model, cnst.${names.Module}, ${names.Module}Insight, ${module}Db.${names.Module}Filter);`;
   })
   .join("\n")}
 ${scalarModules.map((module) => `export const ${module} = DatabaseRegistry.buildScalar("${module}" as const, ${capitalize(module)});`).join("\n")}

package/templates/lib/useClient.ts

@@ -1,16 +1,22 @@
 import type { AppInfo, LibInfo } from "akanjs";
 
 export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { [key: string]: string } = {}) {
+  const isApp = (scanInfo?.type ?? "lib") === "app";
   return `
 import { makePageProto, registerClientRuntime } from "akanjs/client";
 import { FetchClient } from "akanjs/fetch";
 import * as cnst from "./cnst";
-import { getAllDictionary } from "./dict" with { type: "macro" };
-import type * as dict from "./dict";
+${isApp ? `import { getAllDictionary } from "./dict" with { type: "macro" };\n` : ""}import type * as dict from "./dict";
 import { getSerializedSignal } from "./sig" with { type: "macro" };
 import type * as signal from "./sig";
 
-const dictionary = process.env.AKAN_PUBLIC_RENDER_ENV === "csr" ? getAllDictionary() : {};
+${
+  isApp
+    ? `const dictionary = process.env.AKAN_PUBLIC_RENDER_ENV === "csr" ? getAllDictionary() : {};`
+    : `// dict.ts is cumulative, so a lib dictionary is a subset of the mounting app's. Translator state is global,
+// so the app's seed already resolves l() here — seeding again would ship the same payload a second time.
+const dictionary = {};`
+}
 const pageProto = makePageProto<typeof dict>(dictionary);
 const fetchProto = FetchClient.build<typeof signal>(cnst, getSerializedSignal(), { Err: pageProto.Err });
 export const runtime = registerClientRuntime({ ...pageProto, ...fetchProto }, { scope: ${JSON.stringify(scanInfo?.type ?? "lib")} });

package/templates/workspaceRoot/.cursor/rules/akan-sync-conventions.mdc.template

@@ -6,8 +6,9 @@ alwaysApply: false
 
 # Akan Sync Conventions
 
-- `apps/<appName>` root may only contain these files: `akan.app.json`, `akan.config.ts`, `capacitor.config.ts`, `client.ts`, `main.ts`, `package.json`, `server.ts`, `tsconfig.json`.
-- `apps/<appName>` root may only contain these folders: `.akan`, `android`, `common`, `env`, `ios`, `lib`, `page`, `private`, `public`, `script`, `srvkit`, `ui`, `webkit`.
+- `apps/<appName>` root may only contain these files: `AGENTS.md`, `CLAUDE.md`, `akan.app.json`, `akan.config.ts`, `capacitor.config.ts`, `client.ts`, `main.ts`, `package.json`, `server.ts`, `tsconfig.json`.
+- `apps/<appName>` root may only contain these folders: `.akan`, `android`, `common`, `env`, `ios`, `lib`, `mobile`, `page`, `plugin`, `private`, `public`, `script`, `secrets`, `srvkit`, `ui`, `webkit`.
+- `akan sync` maintains a scoped agent guide per app/lib (`apps/<app>/AGENTS.md` / `libs/<lib>/AGENTS.md`); the `akan:agent` block in it is generated, content outside the markers is hand-editable, and `akan lint` fails when the block is stale.
 - Do not add `apps/*/base`; place shared app utilities under `apps/*/common`.
 - `apps/*/lib` and `libs/*/lib` root files are limited to generated/support files: `cnst.ts`, `db.ts`, `dict.ts`, `option.ts`, `sig.ts`, `srv.ts`, `st.ts`, `useClient.ts`, `useServer.ts`.
 - Domain module folders are `lib/<model>` for database modules, `lib/_<service>` for service modules, and `lib/__scalar/<scalar>` for scalar modules.

package/templates/workspaceRoot/.cursor/rules/client-server-boundaries.mdc.template

@@ -15,3 +15,4 @@ alwaysApply: false
 - In domain UI the boundary is mechanical, not a judgment call: `Template`, `Zone`, and `Util` are always client components with `"use client"` on line 1; `Unit` and `View` are always server components and never carry the directive. `usePage()` is still legal in server files.
 - Preserve established domain file roles such as `.document.ts`, `.service.ts`, `.store.ts`, `.constant.ts`, and `.client.ts`.
 - When unsure, inspect nearby files in the same app or package before introducing a new boundary pattern.
+- The boundary is only half the rule: how *little* ends up on the client is the other half. See `ssr-first.mdc`.

package/templates/workspaceRoot/.cursor/rules/ssr-first.mdc.template

@@ -0,0 +1,59 @@
+---
+description: SSR-first rendering rules — keep JSX on the server and justify every "use client"
+globs: apps/**/*.tsx,libs/**/*.tsx
+alwaysApply: false
+---
+
+# SSR First — Server Rendering Is The Default
+
+Akan is SSR-first. A JSX element rendered on the server ships as HTML and costs nothing to hydrate; an element
+behind `"use client"` ships twice — as markup and as bundled JS that re-runs in the browser. The boundary question
+is not which file *may* be client, it is **how little** ends up on the client side.
+
+- **The default is server. `"use client"` is a cost you justify per component, not a habit.** A component earns the
+  directive only by using a client-only capability: a React hook, a JSX event handler, the store (`st.use.*` /
+  `st.do.*`), a browser global, or a client-only third-party package. Rendering markup, mapping over data, reading a
+  route param, and calling `l()` are server work — `usePage()` and `l()` never force a boundary.
+- The file role decides *where* the boundary sits (`Template`/`Zone`/`Util` are client, `Unit`/`View` are server);
+  it does not decide how much markup sits behind it. A `Zone` that hoards markup is still an SSR regression.
+- Measure with `akan quality ssr` (`--format json` for tooling). It reports the server render share per app and lib.
+  Treat **50% server share as the floor** and a falling share as a regression to justify or revert.
+
+## What `akan quality ssr` Flags
+
+- `akan.ssr.unnecessary-use-client` — the directive is there but nothing in the file needs it. Delete it.
+- `akan.ssr.client-static-component` — a component in a client file renders real markup with zero client-only
+  capability: pure server work sitting in the bundle.
+- `akan.ssr.client-static-markup` — a large subtree wraps one or two interactive touches. Split it.
+- `akan.ssr.client-mount-load` — a `useEffect(…, [])` loads server data the page could fetch first.
+- `akan.ssr.module-missing-server-view` — a module renders only from `Template`/`Zone`/`Util`, with no `Unit`/`View`.
+- `akan.ssr.template-client-state` — a `Template` holds form state in `useState` instead of the store.
+
+A third-party client package and the `ui/<Folder>/index_.tsx` + `lazy()` boundary both justify the directive and are
+not flagged. Interaction-driven `fetch.*` inside an `onClick` is not flagged either — only mount-time loads are.
+
+## Server-Side Implementation Playbook
+
+1. **Wrap the interaction, not the UI.** The smallest useful client component adds one behaviour and renders
+   `children` untouched, so the markup inside never reaches the bundle:
+   `export const ClickWrapper = ({ children, onPick }: ClickWrapperProps) => <div onClick={onPick}>{children}</div>;`
+2. **Split compound components so panels stay on the server.** A tab or accordion needs client state only for
+   *which* part is visible. `Tab` / `Tab.Menus` / `Tab.Menu` / `Tab.Panel` from `akanjs/ui` is the shape: only the
+   provider and menu hold state, and `<Tab.Panel>` renders children as-is, so a server `Unit`/`View` passed in stays
+   server-rendered. Never one client file with a mode `useState` and every panel body inlined.
+3. **Sync state instead of fetching it.** The page calls `fetch.initTaskInTodo()` / `fetch.viewTask(id)` and passes
+   the serializable result into a `Zone`; `Load.Units` / `Load.View` hydrate the store from it. Never a
+   `useEffect(…, [])` that fetches on mount.
+4. **Push the boundary down to the leaf that needs it.** A store-reading `Zone` holds zero markup and delegates to a
+   server `View`: `export const Self = () => <Task.View.General task={st.use.task()} />;`
+5. **Hand the promise across, not the awaited value.** `ClientInit` / `ClientView` are `PromiseOrObject<T>`, so a
+   page may pass an unawaited `fetch.initTaskInTodo()` and `Load.*` resolves it behind a skeleton.
+6. **Use named `ReactNode` slots, not just `children`.** `Layout.Navbar` takes `title`, `back`, `left`, `right`, and
+   `children`, so a client shell composes server content in five places.
+7. **Let the server do the derived work.** Display and predicate logic lives on `LightTask` (`isNew()`,
+   `canWrite(user?)`); enum→class lookups live in a module-scope `as const` map.
+8. **Gate auth on the server.** Check the session in `_layout.tsx` and redirect there, before any HTML is sent.
+9. **Prefer CSS over client state for pure visibility.** A `data-*` attribute plus `group-data-[…]` variants, or
+   `<details>`/`<summary>`, keeps both branches server-rendered.
+10. **Keep the heavy island out of the first load.** Put a large client-only widget behind the
+    `ui/<Folder>/index_.tsx` + `lazy()` pair.

package/templates/workspaceRoot/AGENTS.md.template

@@ -74,11 +74,12 @@ Use the local module shape before adding a new abstraction.
 9. Keep page and layout files server-oriented: route-level `usePage`, headers, static layout, and `akanjs/ui` `Tab` composition belong there.
 10. Put interactive loading, submit/import actions, local form state, and `router.push` in client `Util`, `Template`, or `Zone` components.
 11. Prefer `Tab` for static mode selection instead of extra `useState`; render one focused client component inside each `Tab.Panel`.
-12. Keep server-only logic out of client surfaces and client-only code out of server imports.
-13. Treat `AKAN_PUBLIC_*` env vars as public. Never put secrets in them.
-14. Add or update tests when behavior, contracts, or CLI output changes.
-15. Update `*.abstract.md` when business invariants, workflows, or public behavior change.
-16. Run the smallest relevant verification command after changes.
+12. Default to server rendering. Add `"use client"` only for a real client-only capability, and keep markup out of the component that carries it — see **SSR First** below.
+13. Keep server-only logic out of client surfaces and client-only code out of server imports.
+14. Treat `AKAN_PUBLIC_*` env vars as public. Never put secrets in them.
+15. Add or update tests when behavior, contracts, or CLI output changes.
+16. Update `*.abstract.md` when business invariants, workflows, or public behavior change.
+17. Run the smallest relevant verification command after changes. After touching any `.tsx`, that includes `akan quality ssr`.
 
 ## Common Commands
 
@@ -111,7 +112,11 @@ akan typecheck <%= appName %>
 # 3. Test — Run the test code (lib/*/*.signal.test.ts or others)
 akan test <%= appName %>
 
-# 4. Full production build — bundles the app, runs all type/lint checks combined
+# 4. SSR balance — only after touching .tsx files. Reports the server render share
+#    per app/lib and flags client code that should render on the server.
+akan quality ssr
+
+# 5. Full production build — bundles the app, runs all type/lint checks combined
 akan build <%= appName %>
 ```
 
@@ -128,6 +133,8 @@ akan create-scalar <scalar-name> <%= appName %>          # Add a scalar module (
 akan create-service <service-name> <%= appName %>        # Add a service module (lib/_<service-name>/)
 akan test <%= appName %>                             # Run the test code (lib/*/*.signal.test.ts or others)
 akan lint <%= appName %>                             # Lint only (no typecheck)
+akan quality scan                                # All code-quality warnings + SSR balance
+akan quality ssr                                 # SSR balance and client-boundary warnings only
 ```
 
 **CLI argument conventions.** Two argument styles, and mixing them up is a common mistake:
@@ -240,7 +247,7 @@ final fallback when no CLI command covers the change.
 | Add a reusable value type (e.g., Address, WorkHistory) | `lib/__scalar/<type>/` → constant, dictionary, abstract | `akan sync <name>` |
 | Create a new URL-visitable page | `page/` → `_index.tsx`, `_layout.tsx`, `[param]/_index.tsx` | Rebuild (akan start auto-detects) |
 | Change the app color theme / design tokens | `apps/<app>/page/styles.css` → override the semantic token values under `:root, [data-theme="dark"]` and `[data-theme="light"]` (`--primary`, `--background`, `--foreground`, …) | akan start hot-reloads |
-| Add a form or reusable UI component | `ui/` → PascalCase `.tsx` with `"use client"` if needed | `akan sync <name>` |
+| Add a form or reusable UI component | `ui/` → PascalCase `.tsx`, **no** `"use client"` unless it uses a hook, event handler, store, or browser API | `akan sync <name>` |
 | Add a React hook or browser helper | `webkit/` → camelCase `.ts` with `"use client"` | `akan sync <name>` |
 | Add a server-only guard, middleware, or adaptor | `srvkit/` → PascalCase `.ts` | `akan sync <name>` |
 | Add a pure helper (no DOM, no server API) | `common/` → camelCase `.ts` | `akan sync <name>` |
@@ -253,6 +260,7 @@ final fallback when no CLI command covers the change.
 | Create a file without running sync | New files won't appear in barrel exports. Imports like `import * as cnst from "../cnst"` will fail. | Always run `akan sync <name>` after creating, renaming, or deleting any module file |
 | Use JS `#private` in `*.constant.ts`, `*.document.ts`, `*.service.ts`, or `*.store.ts` | `no-js-private-class-method.grit` bans `#private` in exactly those four file suffixes. The rule is scoped by file path, not class shape — `#private` stays the house style under `srvkit/`, including `adapt()` classes. | `private _methodName()` in those four files; `#methodName()` in `srvkit/` |
 | Use `console.log()` | Biome lint forbids `console.log`. Only `console.error`, `console.info`, `console.warn` are allowed. | Use one of the three allowed console methods, or `this.logger.*` / `new Logger("ClassName")` on the server |
+| Write a `//!` marker in `ui/`, `webkit/`, `common/`, `page/**/*.tsx`, `*.constant.ts`, `*.store.ts`, or a module component file | `no-bang-comment-in-client.grit` bans it. Bun classifies `//!` and `/*!` as legal comments and keeps them through minification, so the note ships to every visitor. | `// FIXME:` in browser-reachable code; `//!` stays legal in server, `srvkit/`, and CLI files |
 | `throw new Error("...")` | `no-throw-raw-error.grit` bans raw errors outside tests, `*.constant.ts`, and `common/`. Raw errors carry no dictionary key, so they cannot be localized or toasted. | `throw new Err("task.error.<key>")` plus an `[en, ko]` entry in the module dictionary's `.error({})` |
 | Hand-order Tailwind classes, or reorder them to "fix" a diff | `useSortedClasses` is an error and also sorts the string arguments to `cn()`. Sorter output like `font-bold text-2xl` looks wrong but is correct. | Write classes in any order and let `akan lint` sort them |
 | A colour outside the semantic vocabulary — `bg-red-500`, `bg-[#3b82f6]`, `btn-primary`, `text-base-content`, `style={{ color: "#fff" }}` | The theme closes the vocabulary, so these produce **no CSS at all** — the element renders unstyled, and without the lint rules there is no error and no warning either. Raw-palette, arbitrary-colour, daisyUI-legacy and inline-colour rules all catch this. | Semantic tokens: `bg-primary`, `text-foreground/70`, `border-border`. A genuinely fixed colour takes a `// biome-ignore lint/plugin: <reason>` |
@@ -262,6 +270,120 @@ final fallback when no CLI command covers the change.
 | Use "use client" or `useState`/`useEffect` in pages/*.tsx, *.Unit.tsx, and *.View.tsx files | Server code cannot use React hooks. Wrap in a separate `"use client"` component. | Move hook logic to `webkit/` or a `"use client"` UI component |
 | Use `<a>` tag for internal navigation between pages | Akan.js uses `<Link>` from `akanjs/ui` for client-side navigation — avoids full page reloads. | `import { Link } from "akanjs/ui"` and use `<Link href="/task">...</Link>` |
 | Name a custom `Endpoint`/`Slice` like a generated CRUD op — `create<Model>`, `update<Model>`, `remove<Model>`, `view<Model>`, `edit<Model>`, `merge<Model>` | These names are already auto-generated. A collision can pass sync/typecheck/build and only fail at runtime. | Pick a distinct verb, e.g. `startTask`/`archiveTask`, never `createTask` for a custom endpoint |
+| Add `"use client"` to a file that renders markup but uses no hook, event handler, store, or browser API | The directive is a cost, not a formality: everything behind it ships twice, as HTML and as JS that re-runs in the browser. | Delete the directive. `akan quality ssr` flags this as `akan.ssr.unnecessary-use-client` |
+| Put a large static subtree inside a client component that only needs one `onClick` | The whole subtree lands in the bundle for the sake of one handler. | Keep the handler in a small client shell and pass the static markup in as `children`, or move it to a `Unit`/`View` |
+| Load server data with `useEffect(() => { void st.do.initTaskInTodo(); }, [])` | The page renders an empty shell, hydrates, then round-trips for data the server already had. | `await fetch.initTaskInTodo()` in the page and pass `init` to the `Zone` |
+
+## SSR First — Server Rendering Is The Default
+
+Akan is SSR-first. Every JSX element that renders on the server ships as HTML and costs nothing to hydrate; every
+element behind `"use client"` ships twice — as markup and as bundled JS that must re-run in the browser. The
+boundary question is not which file *may* be client, it is **how little** ends up on the client side.
+
+**The default is server. `"use client"` is a cost you justify per component, not a habit.** A component earns the
+directive only by using a client-only capability: a React hook, a JSX event handler, the store (`st.use.*` /
+`st.do.*`), a browser global, or a client-only third-party package. Rendering markup, mapping over data, reading a
+route param, and calling `l()` are all server work — `usePage()` and `l()` are legal in server components and never
+force a boundary.
+
+The file role decides *where* the boundary sits (`Template`/`Zone`/`Util` are client, `Unit`/`View` are server); it
+does not decide how much markup sits behind it. A `Zone` that hoards markup is still an SSR regression.
+
+Measure with `akan quality ssr` (`--format json` for tooling). It reports the server render share per app and lib —
+server-rendered JSX elements over total — plus the warnings below. Treat **50% server share as the floor** and a
+falling share as a regression to justify or revert.
+
+| Rule | Means |
+|---|---|
+| `akan.ssr.unnecessary-use-client` | The directive is there but nothing in the file needs it. Delete it. |
+| `akan.ssr.client-static-component` | A component in a client file renders real markup with zero client-only capability — pure server work sitting in the bundle. |
+| `akan.ssr.client-static-markup` | A large subtree wraps one or two interactive touches. Split it: interaction stays client, markup goes server. |
+| `akan.ssr.client-mount-load` | A `useEffect(…, [])` loads server data. The page can fetch it before the first byte. |
+| `akan.ssr.module-missing-server-view` | A module renders only from `Template`/`Zone`/`Util` and has no `Unit`/`View` at all. |
+| `akan.ssr.template-client-state` | A `Template` holds form state in `useState` instead of the store. |
+
+A third-party client package and the `ui/<Folder>/index_.tsx` + `lazy()` boundary both justify the directive and are
+not flagged. Interaction-driven `fetch.*` inside an `onClick` is not flagged either — only mount-time loads are,
+because those are the ones the server could have performed.
+
+### Server-Side Implementation Playbook
+
+**① Wrap the interaction, not the UI.** The smallest useful client component adds one behaviour and renders
+`children` untouched, so the markup inside never reaches the bundle.
+
+```tsx
+// apps/<%= appName %>/ui/ClickWrapper.tsx
+"use client";
+export const ClickWrapper = ({ children, onPick }: ClickWrapperProps) => <div onClick={onPick}>{children}</div>;
+
+// in a server page — Task.Unit.Card stays server-rendered
+<ClickWrapper onPick={…}>
+  <Task.Unit.Card task={task} />
+</ClickWrapper>
+```
+
+**② Split compound components so panels stay on the server.** A tab, accordion, or disclosure needs client state
+only for *which* part is visible — never for what the parts contain. `Tab` / `Tab.Menus` / `Tab.Menu` / `Tab.Panel`
+from `akanjs/ui` is the reference shape: only the provider and menu hold state, and `<Tab.Panel>` renders its
+children as-is, so a server `Unit`/`View` passed in stays server-rendered.
+
+```tsx
+<Tab defaultMenu="detail">
+  <Tab.Menus>
+    <Tab.Menu menu="detail">{l("task.detail")}</Tab.Menu>
+    <Tab.Menu menu="history">{l("task.history")}</Tab.Menu>
+  </Tab.Menus>
+  <Tab.Panel menu="detail">
+    <Task.View.General task={task} />
+  </Tab.Panel>
+</Tab>
+```
+
+Never collapse this into one `"use client"` file with a mode `useState` and every panel body inlined.
+
+**③ Sync state instead of fetching it.** A server component cannot hold state, so render the initial data on the
+server and hand it across the boundary as a serializable object. That is what `init` / `view` props are: the page
+calls `fetch.initTaskInTodo()` / `fetch.viewTask(id)`, passes the result into a `Zone`, and `Load.Units` /
+`Load.View` hydrate the store from it.
+
+```tsx
+export default async function Page() {
+  const [{ taskInitInTodo }] = await Promise.all([fetch.initTaskInTodo()]);
+  return <Task.Zone.Card init={taskInitInTodo} sliceName="taskInTodo" />;
+}
+```
+
+**④ Push the boundary down to the leaf that needs it.** When a `Zone` reads the store, it should hold *zero* markup
+and delegate to a server `View`, so the whole detail surface renders server-side wherever a page uses the `View`
+directly.
+
+```tsx
+"use client";
+export const Self = () => <Task.View.General task={st.use.task()} />;
+```
+
+**⑤ Hand the promise across, not the awaited value.** `ClientInit` / `ClientView` are `PromiseOrObject<T>`, so a
+page may pass an unawaited `fetch.initTaskInTodo()` and `Load.*` resolves it behind a skeleton. `await` blocks the
+shell for data the page needs immediately; passing the promise streams the rest. Independent fetches still go
+through one `Promise.all`.
+
+**⑥ Use named `ReactNode` slots, not just `children`.** A client shell can take several server-rendered subtrees:
+`Layout.Navbar` accepts `title`, `back`, `left`, `right`, and `children`, so it composes server content in five
+places instead of absorbing it.
+
+**⑦ Let the server do the derived work.** Display and predicate logic belongs on `LightTask` (`isNew()`,
+`canWrite(user?)`, `formatTimes()`), and enum→class lookups belong in a module-scope `as const` map. Both sides call
+the same method, so a client component that exists only to compute a label is markup in the wrong place.
+
+**⑧ Gate auth on the server.** Check the session in `_layout.tsx` and redirect there, before any HTML is sent. A
+client-side auth check costs a hydration round-trip and flashes the wrong UI first.
+
+**⑨ Prefer CSS over client state for pure visibility.** A `data-*` attribute plus `group-data-[…]` variants, or
+`<details>`/`<summary>`, keeps both branches server-rendered. Reach for `useState` when the state is real, not when
+a Tailwind variant would do.
+
+**⑩ Keep the heavy island out of the first load.** A large client-only widget goes behind the
+`ui/<Folder>/index_.tsx` + `lazy()` pair so the server renders the page around it.
 
 ## Code Style
 
@@ -367,6 +489,9 @@ Do not narrate code. Do document the thing the code cannot say. Both halves are
 - Markers: `TODO` unfinished work · `FIXME` known broken behavior · `XXX` hazard a reader must not miss · `//!`
   disabled or must-fix code · `//?` an explanatory aside · `//*` a design note · deletion caution, warning why
   removing a line would break something non-obvious.
+- `//!` is for server, `srvkit/`, and CLI files only. Bun's bundler treats `//!` and `/*!` as legal comments and
+  keeps them through minification, so in browser-reachable code the note ships verbatim to every visitor. Use
+  `// FIXME:` there — `no-bang-comment-in-client.grit` enforces it.
 - Keep allowed comments to one short line, and give every suppression a reason:
   `// biome-ignore lint/<rule>: <why>`. Never a bare disable block.
 - Match nearby file style: if the surrounding code has few comments, keep it that way.
@@ -533,7 +658,7 @@ export class TaskService extends serve(db.task, ({ plug }) => ({
 For a custom adapter class (not a predefined role), pass the class itself, e.g. `ipfsApi: plug(IpfsApi)`
 (see `libs/shared/lib/file/file.service.ts`). Injecting a file/image field is usually simpler than calling
 storage directly: declare `image: field(File).optional()` (or `images: field([File])`) on the model and let the
-store's generated `upload<Field>On<Model>(fileList)` action handle the upload. Add `{ cascade: "remove" }` to that
+store's generated `upload<Field>On<Model>(fileList)` action handle the upload. Add `{ cascade: "removeRef" }` to that
 field when the file belongs to the model alone, and removing the model removes the file and its stored object.
 
 ---
@@ -751,12 +876,23 @@ A short list of things the type system does not always catch:
   `secret` / `hidden` / `resolve()` fields with `text` throw at class-build time — the mirror is plaintext. Search
   runs on sqlite/libsql only; `q.search()` against Postgres throws. `thumb` is mirrored for rendering and is not
   indexed.
-- **`cascade: "remove"` takes a relation's target down with its owner.** Declare it on the relation itself —
-  `image: field(File, { cascade: "remove" })`, arrays included. The removal runs through the **target's service**,
-  so the target's own `_postRemove` runs too; that is how removing a model also deletes the file's stored object.
-  Only a relation accepts it: a `String`, an `ID`, or a scalar throws while the class is being built. Nothing
-  checks for other references to the same target, so declaring it asserts exclusive ownership. Document removal is
-  soft but the storage delete is not, and query-level removal fires no hooks and therefore no cascade.
+- **`cascade` names a direction, and the wrong one is a data loss.** Both actions can sit on the same field shape,
+  so the value has to say which end goes away. `cascade: "removeRef"` on the relation an owner holds
+  (`image: field(File, { cascade: "removeRef" })`, arrays included) removes the target when the owner is removed;
+  only a relation accepts it. `cascade: "removeWith"` on a child's own reference to its owner
+  (`field(ID, { ref: "agentSession", cascade: "removeWith" })`, or a relation, or `refPath` for a polymorphic
+  owner whose type field must be an `enumOf`) removes the child when the owner is — the owner never learns its
+  children exist. The removal runs through the **target's service** so its `_postRemove` runs too, unless the
+  target provably has no removal side effect, in which case the boot-time plan collapses it into one query. A
+  `removeWith` field gets its index automatically. Nothing checks for other references to the same target, so
+  `removeRef` asserts exclusive ownership. Removal is soft but a storage delete is not, and a query-level removal
+  fires no hooks and therefore no cascade.
+- **Removal is always soft, and `delete` is reserved.** `remove(id)`, the facade's `removeMany(query)`, and the
+  store's `removeManyByQuery` all stamp `removedAt`; the framework has no hard delete for a model table.
+- **The model facade spells out `Many`/`One` on its writes** — `updateOne`, `updateMany`, `removeOne`, `removeMany`
+  — because a bare `update`/`remove` would read like the document-path `update(id)` / `doc.remove()` while hitting
+  every match. Reads keep the short `find`/`findOne` pair, and counting is `count(query)` (`countDocuments` is
+  `@deprecated`).
 - **`q.search()` is a filter node, not a slice requirement.** Prefer
   `bySearch: filter().arg("text", String).query((text, q) => q.search(text, { prefix: true }))` — the generated
   `listBySearch` / `countBySearch` / `queryBySearch` / `insightBySearch` come for free. Only add a search slice when
@@ -834,8 +970,12 @@ akan sync automatically generates APIs across all layers. Only write custom logi
 | `pick[Query](args)`, `pickId[Query](args)` | Find one (throw if not found) |
 | `exists[Query](args)`, `count[Query](args)` | Existence check and count |
 | `insight[Query](args)`, `query[Query](args)` | Insight and raw query |
+| `remove[Query](args)`, `removeOne[Query](args)` | Query-level soft remove — all matches, or the newest one (`createdAt` desc, not caller-chosen) |
+| `update[Query](args).set(patch)`, `updateOne[Query](args).set(patch)` | Query-level update — the patch lands on a terminal `.set()`, because a filter's trailing args may be optional |
+
+**Rule**: Define `Filter` with `.query()` conditions in `document.ts`. akan sync auto-generates all 14 query helper methods per filter. Write `Document` chain methods only for state transitions with validation.
 
-**Rule**: Define `Filter` with `.query()` conditions in `document.ts`. akan sync auto-generates all 10 query helper methods per filter. Write `Document` chain methods only for state transitions with validation.
+**The four query-level writes fire no hooks**, so no `_pre`/`_postRemove` and no cascade run — same as `updateManyByQuery`. Reach for them when the model carries no removal side effect; otherwise remove documents one at a time. A filter keyed after its own model (filter `chat` on model `chat`) is rejected at boot, because `removeChat`/`updateChat` would otherwise shadow the generated single-document CRUD.
 
 ## Generated Context
 

package/templates/workspaceRoot/biome.json.template

@@ -166,6 +166,28 @@
       "includes": ["**/*.signal.ts"],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-redeclare-predefined-endpoint.grit"]
     },
+    {
+      "includes": [
+        "**/ui/**/*.ts",
+        "**/ui/**/*.tsx",
+        "**/webkit/**/*.ts",
+        "**/webkit/**/*.tsx",
+        "**/common/**/*.ts",
+        "**/page/**/*.tsx",
+        "**/*.constant.ts",
+        "**/*.store.ts",
+        "**/*.Template.tsx",
+        "**/*.Unit.tsx",
+        "**/*.Util.tsx",
+        "**/*.View.tsx",
+        "**/*.Zone.tsx",
+        "!**/*.test.ts",
+        "!**/*.test.tsx",
+        "!**/*.spec.ts",
+        "!**/*.spec.tsx"
+      ],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-bang-comment-in-client.grit"]
+    },
     {
       "includes": [
         "**/*.constant.ts",

package/{workflow.command-jswbgk90.js → workflow.command-z0e0fk0z.js}

@@ -1,31 +1,31 @@
 // @bun
 import {
   WorkflowRunner
-} from "./index-csqk9z5j.js";
+} from "./index-c94nq3c1.js";
 import {
   PrimitiveScript
-} from "./index-r4w8cry5.js";
+} from "./index-pfrt7qwh.js";
 import {
   ModuleScript
-} from "./index-vhv3xnjz.js";
-import"./index-hjzr8ja1.js";
+} from "./index-60a3jfcz.js";
+import"./index-hrwzz2wf.js";
 import {
   ScalarScript
-} from "./index-fmgbwsr5.js";
+} from "./index-wrrb8rxk.js";
 import"./index-ss469dec.js";
-import"./index-3pgtw35d.js";
-import"./index-4yp06pn1.js";
+import"./index-0cj2zxbm.js";
+import"./index-jn9vfpwz.js";
 import {
   createWorkflowStepRegistry
-} from "./index-4zgs8g1w.js";
-import"./index-xwgm94zr.js";
+} from "./index-m4kpmmtj.js";
+import"./index-qp089jp0.js";
 import {
   Workspace,
   command,
   script
-} from "./index-jk9q6pse.js";
-import"./index-jtm86byd.js";
-import"./index-6pz1j0zj.js";
+} from "./index-jkynkyfk.js";
+import"./index-47qxw1tz.js";
+import"./index-mxvakhsm.js";
 import"./index-xys926f2.js";
 import"./index-67546d0j.js";
 import"./index-r24hmh0q.js";

package/{workspace.command-h9wwcjpt.js → workspace.command-3ydyy991.js}

@@ -1,48 +1,48 @@
 // @bun
 import {
   ContextScript
-} from "./index-1s71fwrq.js";
-import"./index-b978vs2e.js";
-import"./index-csqk9z5j.js";
-import"./index-r4w8cry5.js";
-import"./index-vhv3xnjz.js";
-import"./index-hjzr8ja1.js";
+} from "./index-vkqxw0ek.js";
+import"./index-6npsfpxr.js";
+import"./index-c94nq3c1.js";
+import"./index-pfrt7qwh.js";
+import"./index-60a3jfcz.js";
+import"./index-hrwzz2wf.js";
 import {
   CloudScript
-} from "./index-ybybkec0.js";
+} from "./index-zr2wvx69.js";
 import {
   getLatestPackageVersion,
   getNpmRegistryUrl
-} from "./index-xj8bks3p.js";
+} from "./index-zbx0jheb.js";
 import {
   PackageScript
-} from "./index-e3qskyt2.js";
-import"./index-fmgbwsr5.js";
+} from "./index-meh7mmz9.js";
+import"./index-wrrb8rxk.js";
 import"./index-ss469dec.js";
-import"./index-y0k42k04.js";
+import"./index-hk9rbcsz.js";
 import {
   GlobalConfig
-} from "./index-3pgtw35d.js";
+} from "./index-0cj2zxbm.js";
 import {
   AgentScript
-} from "./index-n0z3f2xg.js";
-import"./index-4yp06pn1.js";
-import"./index-4zgs8g1w.js";
-import"./index-xwgm94zr.js";
+} from "./index-nfxq39kj.js";
+import"./index-jn9vfpwz.js";
+import"./index-m4kpmmtj.js";
+import"./index-qp089jp0.js";
 import {
   ApplicationScript
-} from "./index-tq1y56tp.js";
+} from "./index-r7nqv8qj.js";
 import"./index-76rn3g2c.js";
 import {
   LibraryScript
-} from "./index-cn24dcqn.js";
+} from "./index-exhpp31y.js";
 import {
   Exec,
   Workspace,
   command,
   runner,
   script
-} from "./index-jk9q6pse.js";
+} from "./index-jkynkyfk.js";
 import"./index-fgc8r6dj.js";
 import {
   ThemeValidator,
@@ -59,8 +59,8 @@ import {
   collectScopeRecipeSources,
   extractAgentBlock,
   renderScopeAgentBlock
-} from "./index-jtm86byd.js";
-import"./index-6pz1j0zj.js";
+} from "./index-47qxw1tz.js";
+import"./index-mxvakhsm.js";
 import {
   collectRecipeSources,
   scanRecipes

package/templates/libRoot/base/baseLogic.ts

@@ -1,14 +0,0 @@
-interface Dict {
-  libName: string;
-}
-export default function getContent(scanInfo: null, dict: Dict) {
-  return `
-// 현 디렉토리에서는 프로젝트 내 전체적으로 사용되는 로직을 구현하며, 따라서 백/프론트 비의존적인 pure js 코드만 구현 가능합니다.
-// common폴더와 다른점은, base 코드는 시스템 전체에서 import되어 사용되므로, 가장 핵심적인 로직과 추상화된 기능만 구현해야합니다.
-// @${dict.libName}/base에서는 서버/클라이언트 관련 라이브러리(@*/server, @*/server, @*/client, @*/client)를 모두 import할 수 없으며, @*/base 라이브러리만 import 가능합니다.
-
-export const someBaseLogic = () => {
-  //
-};
-  `;
-}

package/templates/libRoot/base/index.ts

@@ -1,8 +0,0 @@
-interface Dict {
-  [key: string]: string;
-}
-export default function getContent(scanInfo: null, dict: Dict = {}) {
-  return `
-export * from "./baseLogic";
-  `;
-}