@forinda/kickjs-cli 8.10.0 → 8.10.2

package/README.md

@@ -13,6 +13,8 @@ npx @forinda/kickjs-cli new my-api
 
 ## Commands
 
+The CLI is a dev dependency, so in a shell run it through your package manager — `npx kick dev`, `pnpm exec kick dev`, `yarn kick dev`, `bunx kick dev` — or through the project's scripts (`npm run dev`). A bare `kick` needs a global install.
+
 ```bash
 kick new <name>           # Scaffold a new KickJS project
 kick dev                  # Start dev server with Vite HMR

package/dist/{agent-docs-CvBsLoE4.mjs → agent-docs-As_KjQBC.mjs}

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v8.10.0
+ * @forinda/kickjs-cli v8.10.2
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,7 +8,7 @@
  *
  * @license MIT
  */
-import{t as e}from"./rolldown-runtime-vT0bVE76.mjs";import{a as t}from"./config-DO4J2xgV.mjs";import{r as n}from"./fs-CT9PRuSw.mjs";import{existsSync as r,readFileSync as i}from"node:fs";import{join as a}from"node:path";import*as o from"@clack/prompts";import s from"picocolors";const c={GET:s.green,POST:s.cyan,PUT:s.yellow,PATCH:s.magenta,DELETE:s.red};function l(e){return(c[e]??s.dim)(e.padEnd(7))}function u(e){let t=`[${e}]`.padEnd(10);switch(e){case`CRITICAL`:return s.red(t);case`WARNING`:return s.yellow(t);case`INFO`:return s.blue(s.dim(t));default:return t}}s.green(`✓`),s.red(`✖`),s.yellow(`⚠`),s.blue(`ℹ`);function d(e){o.intro(s.bgCyan(s.black(` ${e} `)))}function f(e){o.outro(e)}function p(e){o.isCancel(e)&&(o.cancel(`Operation cancelled.`),process.exit(0))}async function m(e){let t=await o.text(e);return p(t),t}async function h(e){let t=await o.select(e);return p(t),t}async function g(e){let t=await o.multiselect(e);return p(t),t}async function _(e){let t=await o.confirm(e);return p(t),t}function v(){return o.spinner()}const y=o.log;function b(e,t,n){return`# CLAUDE.md — ${e}
+import{t as e}from"./rolldown-runtime-7c5UUG6D.mjs";import{o as t,r as n,u as r}from"./config-Ck9aQVpE.mjs";import{n as i,o as a}from"./package-manager--IUl91nq.mjs";import{existsSync as o,readFileSync as s}from"node:fs";import{join as c}from"node:path";import*as l from"@clack/prompts";import u from"picocolors";const d={GET:u.green,POST:u.cyan,PUT:u.yellow,PATCH:u.magenta,DELETE:u.red};function f(e){return(d[e]??u.dim)(e.padEnd(7))}function p(e){let t=`[${e}]`.padEnd(10);switch(e){case`CRITICAL`:return u.red(t);case`WARNING`:return u.yellow(t);case`INFO`:return u.blue(u.dim(t));default:return t}}u.green(`✓`),u.red(`✖`),u.yellow(`⚠`),u.blue(`ℹ`);function m(e){l.intro(u.bgCyan(u.black(` ${e} `)))}function h(e){l.outro(e)}function g(e){l.isCancel(e)&&(l.cancel(`Operation cancelled.`),process.exit(0))}async function _(e){let t=await l.text(e);return g(t),t}async function v(e){let t=await l.select(e);return g(t),t}async function y(e){let t=await l.multiselect(e);return g(t),t}async function b(e){let t=await l.confirm(e);return g(t),t}function x(){return l.spinner()}const S=l.log;function C(e,t){let n=e;return t===`fullstack`&&n!==`pnpm`?`${r(n,`dev:server`)} + ${r(n,`dev:web`)}`:r(n,`dev`)}function w(e,t,i){return`# CLAUDE.md — ${e}
 
 **Read \`./.agents/AGENTS.md\` first.** It is the canonical, multi-agent
 reference for this project (Claude, Copilot, Codex, Gemini, etc.) —
@@ -56,14 +56,17 @@ prose.
 ## Quick reference (full version in .agents/AGENTS.md)
 
 \`\`\`bash
-${n} install            # Install dependencies
-kick dev                 # Dev server with HMR + typegen
-kick build && kick start # Production
-${n} run test           # Vitest
-kick typecheck           # tsc/tsgo, whichever the project has
-kick format              # oxfmt
+${i} install
+${C(i,t)}     # Dev server with HMR + typegen
+${r(i,`build`)} && ${r(i,`start`)}  # Production
+${r(i,`test`)}    # Vitest
+${t===`fullstack`?r(i,`typecheck`):`${n(i,`kick`)} typecheck`}   # tsc/tsgo, whichever the project has
+${t===`fullstack`?r(i,`format`):`${n(i,`kick`)} format`}      # oxfmt
 \`\`\`
 
+\`kick\` is this project's dev dependency, not a global command: every \`kick …\`
+in these docs runs as \`${n(i,`kick`)} …\` in a shell.
+
 ## v4 framework reminders
 
 When generating or modifying code in this project, stay aligned with the v4 conventions documented in \`.agents/AGENTS.md\`:
@@ -83,7 +86,7 @@ When generating or modifying code in this project, stay aligned with the v4 conv
 - **Refresh these files**: \`kick g agents -f\` regenerates \`CLAUDE.md\` at the project root and \`.agents/AGENTS.md\` + \`.agents/GEMINI.md\` + \`.agents/COPILOT.md\` + every \`.agents/skills/<name>/SKILL.md\` from the latest CLI templates. Hand-edited content is overwritten — keep customisation in \`.agents/AGENTS.local.md\` or per-skill \`SKILL.local.md\` files alongside.
 
 For everything else (controllers, services, modules, RequestContext API, generators, CLI commands, package additions, env wiring, troubleshooting) → \`.agents/AGENTS.md\`.
-`}function x(e,t,n){return`# AGENTS.md — AI Agent Guide for ${e}
+`}function T(e,t,i){return`# AGENTS.md — AI Agent Guide for ${e}
 
 This guide is the **canonical, multi-agent reference** for this KickJS
 application — Claude, Copilot, Codex, Gemini, etc. all read it first.
@@ -92,13 +95,18 @@ add tool-specific affordances on top.
 
 ## Before You Start
 
-1. Run \`${n} install\` to install dependencies
-2. Run \`kick dev\` to verify the app starts${t===`fullstack`?`
+1. Run \`${i} install\` to install dependencies
+2. Run \`${C(i,t)}\` to verify the app starts
+
+\`kick\` is this project's dev dependency, not a global command: every \`kick …\`
+below runs as \`${n(i,`kick`)} …\` in a shell.${t===`fullstack`?`
 
 ## Fullstack workspace layout
 
 This is a WORKSPACE root — the KickJS API lives in \`server/\`, the typed web
-app in \`web/\`. Run both with \`${n===`pnpm`?`pnpm dev`:`${n} run dev:server + ${n} run dev:web`}\`.
+app in \`web/\`. Run both with \`${C(i,t)}\`. From this root,
+\`${r(i,`test`)}\`, \`${r(i,`typecheck`)}\` and \`${r(i,`format`)}\` reach into
+\`server/\` (and \`web/\` for typecheck).
 
 The type loop (do not break it):
 1. \`server/\` handlers RETURN their payloads → \`kick typegen\` emits
@@ -112,8 +120,8 @@ The type loop (do not break it):
    relative \`/api/v1\` (Vite proxies it in dev) unless \`VITE_API_URL\` points at
    an API on another origin.
 
-Rules: kick commands (\`kick g\`, \`kick typegen\`, \`kick dev\`) run in
-\`server/\`; never import server runtime code into \`web/\` (the d.ts bridge is
+Rules: kick commands (\`kick g\`, \`kick typegen\`, \`kick dev\`, \`kick typecheck\`)
+run in \`server/\` — the root has no \`kick.config.ts\`; never import server runtime code into \`web/\` (the d.ts bridge is
 type-only); prefer return-value handlers so responses stay inferable.`:``}
 3. Read the [KickJS documentation](https://kickjs.app/) for framework details
 
@@ -358,7 +366,7 @@ See the **\`kickjs-write-controller-test\`** skill for the canonical test — it
 carries the call shape, the DI reset, and the env side-effect import, each of
 which has its own failure mode.
 
-Run with \`${n} run test\` (\`test:watch\` for watch mode).
+Run with \`${i} run test\` (\`test:watch\` for watch mode).
 
 ## Environment Variables
 
@@ -493,7 +501,7 @@ page and lists the local tools (\`kick explain\`, \`kick doctor\`, \`kick inspec
 
 Start at <https://kickjs.app/>.
 
-`}function S(e,t=`define`){let n=t===`class`?`UserModule`:`UserModule()`;return[{slug:`add-module`,frontmatterName:`kickjs-add-module`,description:`Use when the user asks to add a new feature module (controller + service + repo + DTOs).`,body:`**Trigger phrases**: "add a users module", "scaffold tasks", "new feature for X".
+`}function E(e,t=`define`){let i=t===`class`?`UserModule`:`UserModule()`;return[{slug:`add-module`,frontmatterName:`kickjs-add-module`,description:`Use when the user asks to add a new feature module (controller + service + repo + DTOs).`,body:`**Trigger phrases**: "add a users module", "scaffold tasks", "new feature for X".
 
 **Steps**:
 1. Run \`kick g module <name>\` (use plural form if the project pluralizes — check \`kick.config.ts\`).
@@ -567,7 +575,7 @@ describe('UserController', () => {
     // configured with. Pass \`runtime\` to \`createTestApp\` to match production.
     const { app } = await createTestApp({
       // Matches this project's \`modules.style\`.
-      modules: [${n}],
+      modules: [${i}],
     })
     const res = await request(app.handle.bind(app)).get('/api/v1/users')
     expect(res.status).toBe(200)
@@ -597,7 +605,43 @@ async create(ctx: Ctx<KickRoutes.TodoController['create']>) {
 
 **Nuances**:
 - \`@Inject\` and \`@Autowired\` are interchangeable — same runtime, same types; pick by readability.
-- \`@Value('MISSING_KEY')\` with no default **throws on property access**, not at construction — tests that exercise the getter will surface the missing-env issue.`},{slug:`env-wiring-check`,frontmatterName:`kickjs-env-wiring-check`,description:`Use when ConfigService.get('SOME_KEY') returns undefined or @Value silently falls back to process.env.`,body:"**Fastest path**: `kick explain \"ConfigService.get('MY_KEY') returned undefined\"` —\npipe a failing run straight in if you prefer (`pnpm test 2>&1 | kick explain`). It\ndistinguishes the entry-file cause from the test-file one, which is the step most\npeople lose time on. The manual checks below are the same reasoning.\n\n**Diagnosis (in order)**:\n1. Open `src/index.ts`. The **first non-`reflect-metadata`** import MUST be `import './config'`.\n2. Open `src/config/index.ts`. It MUST run the loader as a top-level side effect — not just declare the schema. This is what `kick new` generates:\n   ```ts\n   import { loadEnvFromSchema } from '@forinda/kickjs/config'\n   import { fromZod } from '@forinda/kickjs-schema/zod'\n   const envSchema = fromZod(z.object({ DATABASE_URL: z.url() }))\n   export const env = loadEnvFromSchema(envSchema)\n   ```\n3. The new key MUST be declared in the schema. `@Value('NEW_KEY')` accepts any string at the type level and **falls back to raw `process.env`** when the schema doesn't know the key — silently skipping its parsing and defaults.\n4. After adding a key, re-run `kick typegen` (or restart `kick dev` if the typegen watcher missed it) so the global `KickEnv` augmentation picks it up.\n\n5. **In a test?** `createTestApp` never loads `src/index.ts`, so the entry's\n   `import './config'` never runs no matter how correct it is. The test file\n   must import it itself:\n   ```ts\n   import '@/config'\n   ```\n   Symptom is identical to the missing-entry-import case, and step 1 will look\n   fine, which is what makes it slow to spot.\n\n**Why `@Value` \"works\" but `ConfigService.get` doesn't**: `@Value` has the `process.env` fallback that masks missing-side-effect-import bugs; `ConfigService` has none. If `@Value('FOO')` returns a value but `ConfigService.get('FOO')` returns `undefined`, the side-effect import of `./config` is missing.\n\n**`reloadEnv` vs `resetEnvCache`** — distinct, frequently mixed up:\n- `reloadEnv()` — re-reads `process.env` against the **already registered** schema. Use in HMR plugins after `.env` file changes. Schema survives.\n- `resetEnvCache()` — drops the registered schema entirely. **Test-only.** Calling it between dev requests drops the project's keys.\n\n**Nuances**:\n- `dotenv` is an **optional peer dep** in v5+ — projects upgrading from older versions may need to add it explicitly.\n- For HMR-friendly `.env` edits, add `envWatchPlugin()` to `vite.config.ts` — calls `reloadEnv()` automatically.\n\n**Fix recipe**: add the key to the schema; add `import './config'` as the first non-reflect-metadata import in `src/index.ts`; add `import '@/config'` to any test that reads config; re-run `kick typegen`."},{slug:`bootstrap-export`,frontmatterName:`kickjs-bootstrap-export`,description:`Use when HMR is silently doing full restarts on every save, or createTestApp can't find the app handle.`,body:"**Check** `src/index.ts`'s last line:\n\n```ts\n// CORRECT — Vite plugin + createTestApp import the named `app` symbol\nexport const app = await bootstrap({ ... })\n\n// WRONG — HMR degrades to full restart, createTestApp loses the handle\nawait bootstrap({ ... })\n```\n\nThe Vite plugin imports the named `app` symbol via `virtual:kickjs/app`; testing helpers do too. Without the export, both fall back to slower paths (full restart on save, mock handle in tests) **without warning**.\n\n**Red flags**:\n- A bare `await bootstrap(...)` with no `export` — fix by adding `export const app =`.\n- Re-assigning `app` later in the file (`app = somethingElse`) — Vite imports by reference at module-load time; reassignments don't propagate.\n- Multiple files calling `bootstrap()` — only the entry should. Tests use `createTestApp` instead."},{slug:`thin-entry-file`,frontmatterName:`kickjs-thin-entry-file`,description:`Use when src/index.ts is accumulating module/middleware/plugin/adapter literals.`,body:`**Refactor target**:
+- \`@Value('MISSING_KEY')\` with no default **throws on property access**, not at construction — tests that exercise the getter will surface the missing-env issue.`},{slug:`env-wiring-check`,frontmatterName:`kickjs-env-wiring-check`,description:`Use when ConfigService.get('SOME_KEY') returns undefined or @Value silently falls back to process.env.`,body:`**Fastest path**: \`kick explain "ConfigService.get('MY_KEY') returned undefined"\` —
+pipe a failing run straight in if you prefer (\`${r(e,`test`)} 2>&1 | ${n(e,`kick`)} explain\`). It
+distinguishes the entry-file cause from the test-file one, which is the step most
+people lose time on. The manual checks below are the same reasoning.
+
+**Diagnosis (in order)**:
+1. Open \`src/index.ts\`. The **first non-\`reflect-metadata\`** import MUST be \`import './config'\`.
+2. Open \`src/config/index.ts\`. It MUST run the loader as a top-level side effect — not just declare the schema. This is what \`kick new\` generates:
+   \`\`\`ts
+   import { loadEnvFromSchema } from '@forinda/kickjs/config'
+   import { fromZod } from '@forinda/kickjs-schema/zod'
+   const envSchema = fromZod(z.object({ DATABASE_URL: z.url() }))
+   export const env = loadEnvFromSchema(envSchema)
+   \`\`\`
+3. The new key MUST be declared in the schema. \`@Value('NEW_KEY')\` accepts any string at the type level and **falls back to raw \`process.env\`** when the schema doesn't know the key — silently skipping its parsing and defaults.
+4. After adding a key, re-run \`kick typegen\` (or restart \`kick dev\` if the typegen watcher missed it) so the global \`KickEnv\` augmentation picks it up.
+
+5. **In a test?** \`createTestApp\` never loads \`src/index.ts\`, so the entry's
+   \`import './config'\` never runs no matter how correct it is. The test file
+   must import it itself:
+   \`\`\`ts
+   import '@/config'
+   \`\`\`
+   Symptom is identical to the missing-entry-import case, and step 1 will look
+   fine, which is what makes it slow to spot.
+
+**Why \`@Value\` "works" but \`ConfigService.get\` doesn't**: \`@Value\` has the \`process.env\` fallback that masks missing-side-effect-import bugs; \`ConfigService\` has none. If \`@Value('FOO')\` returns a value but \`ConfigService.get('FOO')\` returns \`undefined\`, the side-effect import of \`./config\` is missing.
+
+**\`reloadEnv\` vs \`resetEnvCache\`** — distinct, frequently mixed up:
+- \`reloadEnv()\` — re-reads \`process.env\` against the **already registered** schema. Use in HMR plugins after \`.env\` file changes. Schema survives.
+- \`resetEnvCache()\` — drops the registered schema entirely. **Test-only.** Calling it between dev requests drops the project's keys.
+
+**Nuances**:
+- \`dotenv\` is an **optional peer dep** in v5+ — projects upgrading from older versions may need to add it explicitly.
+- For HMR-friendly \`.env\` edits, add \`envWatchPlugin()\` to \`vite.config.ts\` — calls \`reloadEnv()\` automatically.
+
+**Fix recipe**: add the key to the schema; add \`import './config'\` as the first non-reflect-metadata import in \`src/index.ts\`; add \`import '@/config'\` to any test that reads config; re-run \`kick typegen\`.`},{slug:`bootstrap-export`,frontmatterName:`kickjs-bootstrap-export`,description:`Use when HMR is silently doing full restarts on every save, or createTestApp can't find the app handle.`,body:"**Check** `src/index.ts`'s last line:\n\n```ts\n// CORRECT — Vite plugin + createTestApp import the named `app` symbol\nexport const app = await bootstrap({ ... })\n\n// WRONG — HMR degrades to full restart, createTestApp loses the handle\nawait bootstrap({ ... })\n```\n\nThe Vite plugin imports the named `app` symbol via `virtual:kickjs/app`; testing helpers do too. Without the export, both fall back to slower paths (full restart on save, mock handle in tests) **without warning**.\n\n**Red flags**:\n- A bare `await bootstrap(...)` with no `export` — fix by adding `export const app =`.\n- Re-assigning `app` later in the file (`app = somethingElse`) — Vite imports by reference at module-load time; reassignments don't propagate.\n- Multiple files calling `bootstrap()` — only the entry should. Tests use `createTestApp` instead."},{slug:`thin-entry-file`,frontmatterName:`kickjs-thin-entry-file`,description:`Use when src/index.ts is accumulating module/middleware/plugin/adapter literals.`,body:`**Refactor target**:
 
 \`\`\`ts
 // src/modules/index.ts — fluent chain (default for \`modules.style: 'define'\`)
@@ -793,7 +837,7 @@ fine and fails at runtime.
 **Local, and usually faster**
 
 - \`kick explain "<error message>"\` — matches known failures and gives the fix.
-  Pipe a failing run in: \`${e} test 2>&1 | kick explain\`.
+  Pipe a failing run in: \`${r(e,`test`)} 2>&1 | ${n(e,`kick`)} explain\`.
 - \`kick doctor\` — checks this project's wiring.
 - \`kick inspect\` — the live route / adapter table.
 - \`.kickjs/types/\` — generated types are ground truth for what exists.
@@ -802,7 +846,7 @@ fine and fails at runtime.
 
 **Rule**: if you would be guessing, look it up. If a doc page contradicts the
 installed \`.d.mts\`, trust the \`.d.mts\` and say so — the docs may be behind the
-version this project has.`},{slug:`refresh-agent-docs`,frontmatterName:`kickjs-refresh-agent-docs`,description:`Use after a KickJS version bump to sync the .agents/ docs with the latest CLI templates.`,body:"**Steps**:\n1. `kick g agents -f --only both` — overwrites `CLAUDE.md` (root) and `.agents/AGENTS.md`.\n2. `kick g agents -f --only skills` — refreshes every `.agents/skills/<slug>/SKILL.md`.\n3. `kick g agents -f --only gemini` / `--only copilot` — refresh the per-agent files when needed.\n4. Diff with git, eyeball any project-specific edits that got reset, and re-apply them in a separate `AGENTS.local.md` or per-skill `SKILL.local.md` alongside.\n5. Commit as `docs(agents): sync from CLI vX.Y`.\n\n**`.agents/` layout** (post-restructure):\n\n```\nCLAUDE.md                 # at root — Claude Code auto-loads from here\n.agents/\n├── AGENTS.md             # canonical multi-agent reference\n├── GEMINI.md             # Gemini-specific notes\n├── COPILOT.md            # Copilot CLI notes\n└── skills/\n    ├── add-module/SKILL.md\n    ├── add-adapter/SKILL.md\n    └── …                 # one SKILL.md per skill, frontmatter-namespaced\n```\n\nCustomisation goes in `.local.md` siblings (`AGENTS.local.md`, `skills/<slug>/SKILL.local.md`) — those are never overwritten."},{slug:`deny-list`,frontmatterName:`kickjs-deny-list`,description:`Patterns to refuse outright when the user asks for them — they break v4 invariants.`,body:"**Module / adapter / plugin shape**:\n- `class implements AppAdapter` → use `defineAdapter()`.\n- `class implements KickPlugin` / function returning `KickPlugin` → use `definePlugin()`.\n- `class implements AppModule` for new code → use `defineModule()`.\n- `bootstrap({ adapters: [MyAdapter] })` (factory) → `MyAdapter()` (instance, with parens).\n- `@Controller('/path')` with a path argument → `@Controller()`, with the prefix in `routes().path`.\n- Module file named `<name>.ts` (no `.module` suffix) → rename to `<name>.module.ts`. Vite HMR's glob doesn't pick up the unsuffixed form.\n\n**DI**:\n- `new Container()` or `Container.getInstance().reset()` in tests → use `Container.reset()` in `beforeEach` (or `Container.create()` for fully isolated graphs).\n- DI tokens with `:` separator (`'app:db:url'`) or in PascalCase → use slash-delimited lower-case (`'app/db/url'`). First-party uses reserved `'kick/'` prefix.\n- `Symbol.for(...)` for DI tokens — globally interned, **collides across files**. Use `createToken<T>('name')`.\n- Raw string tokens (`@Inject('config')`) — silent collisions; widens to `unknown`. Use `createToken<T>`.\n- Injecting a `Scope.REQUEST` service into a `SINGLETON` — container throws at resolve time.\n\n**Bootstrap / entry file**:\n- `bootstrap({ ... })` without `export const app = ...` → always export. HMR degrades to full restart and `createTestApp` loses the handle.\n- `bootstrap({ register: ... })` — that option doesn't exist. Use an inline plugin in `plugins`.\n\n**Middleware**:\n- Using `(ctx, next)` for global middleware in `bootstrap({ middlewares })` — global middleware uses raw Express `(req, res, next)`. Wrong signature throws \"Cannot read properties of undefined\".\n- Using `(req, res, next)` for an `@Middleware()` decorator — those use `(ctx, next)`.\n- `@Middleware()` whose only output is `ctx.set('x', v)` — should be a context decorator (typed, ordered, testable).\n\n**Context contributors**:\n- `ctx.tenant = x` from a contributor — only sticks to one `RequestContext` instance. **Return the value** so the runner writes it via `ctx.set(key, value)`.\n- Omitting the `declare module '@forinda/kickjs'` block — without it `ctx.get('tenant')` is `unknown`.\n- `getRequestValue<string>('traceId')` — generic is the **key** type, not value type.\n\n**Env / config**:\n- `@Value('NEW_KEY')` without the key in the Zod schema — silent fallback to raw `process.env`, no coercion.\n- `resetEnvCache()` outside tests — drops the registered schema.\n\n**List endpoints**:\n- Reading `req.query.status` directly — bypasses the allow-list. Use `ctx.qs({ filterable })`.\n- Returning a bare array from a list endpoint — breaks the `PaginatedResponse<T>` contract. Use `ctx.paginate()`.\n\n**Assets**:\n- Hand-rolled `__dirname` arithmetic for template paths — use `assets.<ns>.<key>()` and add the namespace to `kick.config.ts assetMap`."}]}function C(e,t,n,r=`define`){let i=`<!-- Generated by \`kick g agents\` for ${e}. Edits are overwritten on the next refresh; keep customisation in a SKILL.local.md alongside. -->`;return S(n,r).map(e=>({slug:e.slug,content:`---
+version this project has.`},{slug:`refresh-agent-docs`,frontmatterName:`kickjs-refresh-agent-docs`,description:`Use after a KickJS version bump to sync the .agents/ docs with the latest CLI templates.`,body:"**Steps**:\n1. `kick g agents -f --only both` — overwrites `CLAUDE.md` (root) and `.agents/AGENTS.md`.\n2. `kick g agents -f --only skills` — refreshes every `.agents/skills/<slug>/SKILL.md`.\n3. `kick g agents -f --only gemini` / `--only copilot` — refresh the per-agent files when needed.\n4. Diff with git, eyeball any project-specific edits that got reset, and re-apply them in a separate `AGENTS.local.md` or per-skill `SKILL.local.md` alongside.\n5. Commit as `docs(agents): sync from CLI vX.Y`.\n\n**`.agents/` layout** (post-restructure):\n\n```\nCLAUDE.md                 # at root — Claude Code auto-loads from here\n.agents/\n├── AGENTS.md             # canonical multi-agent reference\n├── GEMINI.md             # Gemini-specific notes\n├── COPILOT.md            # Copilot CLI notes\n└── skills/\n    ├── add-module/SKILL.md\n    ├── add-adapter/SKILL.md\n    └── …                 # one SKILL.md per skill, frontmatter-namespaced\n```\n\nCustomisation goes in `.local.md` siblings (`AGENTS.local.md`, `skills/<slug>/SKILL.local.md`) — those are never overwritten."},{slug:`deny-list`,frontmatterName:`kickjs-deny-list`,description:`Patterns to refuse outright when the user asks for them — they break v4 invariants.`,body:"**Module / adapter / plugin shape**:\n- `class implements AppAdapter` → use `defineAdapter()`.\n- `class implements KickPlugin` / function returning `KickPlugin` → use `definePlugin()`.\n- `class implements AppModule` for new code → use `defineModule()`.\n- `bootstrap({ adapters: [MyAdapter] })` (factory) → `MyAdapter()` (instance, with parens).\n- `@Controller('/path')` with a path argument → `@Controller()`, with the prefix in `routes().path`.\n- Module file named `<name>.ts` (no `.module` suffix) → rename to `<name>.module.ts`. Vite HMR's glob doesn't pick up the unsuffixed form.\n\n**DI**:\n- `new Container()` or `Container.getInstance().reset()` in tests → use `Container.reset()` in `beforeEach` (or `Container.create()` for fully isolated graphs).\n- DI tokens with `:` separator (`'app:db:url'`) or in PascalCase → use slash-delimited lower-case (`'app/db/url'`). First-party uses reserved `'kick/'` prefix.\n- `Symbol.for(...)` for DI tokens — globally interned, **collides across files**. Use `createToken<T>('name')`.\n- Raw string tokens (`@Inject('config')`) — silent collisions; widens to `unknown`. Use `createToken<T>`.\n- Injecting a `Scope.REQUEST` service into a `SINGLETON` — container throws at resolve time.\n\n**Bootstrap / entry file**:\n- `bootstrap({ ... })` without `export const app = ...` → always export. HMR degrades to full restart and `createTestApp` loses the handle.\n- `bootstrap({ register: ... })` — that option doesn't exist. Use an inline plugin in `plugins`.\n\n**Middleware**:\n- Using `(ctx, next)` for global middleware in `bootstrap({ middlewares })` — global middleware uses raw Express `(req, res, next)`. Wrong signature throws \"Cannot read properties of undefined\".\n- Using `(req, res, next)` for an `@Middleware()` decorator — those use `(ctx, next)`.\n- `@Middleware()` whose only output is `ctx.set('x', v)` — should be a context decorator (typed, ordered, testable).\n\n**Context contributors**:\n- `ctx.tenant = x` from a contributor — only sticks to one `RequestContext` instance. **Return the value** so the runner writes it via `ctx.set(key, value)`.\n- Omitting the `declare module '@forinda/kickjs'` block — without it `ctx.get('tenant')` is `unknown`.\n- `getRequestValue<string>('traceId')` — generic is the **key** type, not value type.\n\n**Env / config**:\n- `@Value('NEW_KEY')` without the key in the Zod schema — silent fallback to raw `process.env`, no coercion.\n- `resetEnvCache()` outside tests — drops the registered schema.\n\n**List endpoints**:\n- Reading `req.query.status` directly — bypasses the allow-list. Use `ctx.qs({ filterable })`.\n- Returning a bare array from a list endpoint — breaks the `PaginatedResponse<T>` contract. Use `ctx.paginate()`.\n\n**Assets**:\n- Hand-rolled `__dirname` arithmetic for template paths — use `assets.<ns>.<key>()` and add the namespace to `kick.config.ts assetMap`."}]}function D(e,t,n,r=`define`){let i=`<!-- Generated by \`kick g agents\` for ${e}. Edits are overwritten on the next refresh; keep customisation in a SKILL.local.md alongside. -->`;return E(n,r).map(e=>({slug:e.slug,content:`---
 name: ${e.frontmatterName}
 description: ${e.description}
 ---
@@ -810,7 +854,7 @@ description: ${e.description}
 ${i}
 
 ${e.body}
-`}))}function w(e,t,n){return`# GEMINI.md — ${e}
+`}))}function O(e,t,n){return`# GEMINI.md — ${e}
 
 **Read \`./AGENTS.md\` first.** It is the canonical, multi-agent
 reference for this project — every convention, structure, decorator
@@ -844,7 +888,7 @@ without us copy-pasting.
 \`kick g agents --only gemini -f\` regenerates this file from the
 CLI template. Hand-edited content is overwritten — keep customisation
 in \`.agents/GEMINI.local.md\`.
-`}function T(e,t,n){return`# COPILOT.md — ${e}
+`}function k(e,t,n){return`# COPILOT.md — ${e}
 
 **Read \`./AGENTS.md\` first.** It is the canonical, multi-agent
 reference for this project — every convention, structure, decorator
@@ -877,4 +921,4 @@ Codex / Cursor / Gemini / Claude Code without copy-pasting.
 \`kick g agents --only copilot -f\` regenerates this file from the
 CLI template. Hand-edited content is overwritten — keep customisation
 in \`.agents/COPILOT.local.md\`.
-`}var E=/* @__PURE__ */ e({generateAgentDocs:()=>N});const D=`.agents`,O=/* @__PURE__ */ new Set([`rest`,`minimal`,`fullstack`,`inertia`]);function k(e,t){if(t)return t;try{let t=JSON.parse(i(a(e,`package.json`),`utf-8`));if(t.name)return t.name.replace(/^@[^/]+\//,``)}catch{}return e.split(`/`).findLast(Boolean)??`app`}function A(e,t){if(t)return t;try{let t=JSON.parse(i(a(e,`package.json`),`utf-8`));if(t.packageManager)return t.packageManager.split(`@`)[0]}catch{}return`pnpm`}async function j(e){try{return(await t(e))?.modules?.style===`class`?`class`:`define`}catch{return`define`}}async function M(e,n){if(n)return n;try{let n=(await t(e))?.pattern;if(n&&O.has(n))return n}catch{}return`rest`}async function N(e){let t=e.only??`all`,i=k(e.outDir,e.name),o=A(e.outDir,e.pm),s=await M(e.outDir,e.template),c=await j(e.outDir),l=t===`agents`||t===`both`||t===`all`,u=t===`claude`||t===`both`||t===`all`,d=t===`skills`||t===`all`,f=t===`gemini`||t===`all`,p=t===`copilot`||t===`all`,m=[];if(l&&m.push({file:a(e.outDir,D,`AGENTS.md`),render:()=>x(i,s,o)}),u&&m.push({file:a(e.outDir,`CLAUDE.md`),render:()=>b(i,s,o)}),d)for(let t of C(i,s,o,c))m.push({file:a(e.outDir,D,`skills`,t.slug,`SKILL.md`),render:()=>t.content});f&&m.push({file:a(e.outDir,D,`GEMINI.md`),render:()=>w(i,s,o)}),p&&m.push({file:a(e.outDir,D,`COPILOT.md`),render:()=>T(i,s,o)});let h=[];for(let{file:t,render:i}of m)r(t)&&!e.force&&!await _({message:`${t.replace(e.outDir+`/`,``)} already exists. Overwrite?`,initialValue:!1})?console.log(`  Skipped — existing ${t.replace(e.outDir+`/`,``)} preserved.`):(await n(t,i()),h.push(t));return h}export{y as a,h as c,l as d,s as f,d as i,v as l,N as n,g as o,u as p,_ as r,f as s,E as t,m as u};
+`}var A=/* @__PURE__ */ e({generateAgentDocs:()=>I});const j=`.agents`,M=/* @__PURE__ */ new Set([`rest`,`minimal`,`fullstack`,`inertia`]);function N(e,t){if(t)return t;try{let t=JSON.parse(s(c(e,`package.json`),`utf-8`));if(t.name)return t.name.replace(/^@[^/]+\//,``)}catch{}return e.split(`/`).findLast(Boolean)??`app`}async function P(e){try{return(await t(e))?.modules?.style===`class`?`class`:`define`}catch{return`define`}}async function F(e,n){if(n)return n;try{let n=(await t(e))?.pattern;if(n&&M.has(n))return n}catch{}return`rest`}async function I(e){let t=e.only??`all`,n=N(e.outDir,e.name),r=await i(e.pm,e.outDir),s=await F(e.outDir,e.template),l=await P(e.outDir),u=t===`agents`||t===`both`||t===`all`,d=t===`claude`||t===`both`||t===`all`,f=t===`skills`||t===`all`,p=t===`gemini`||t===`all`,m=t===`copilot`||t===`all`,h=[];if(u&&h.push({file:c(e.outDir,j,`AGENTS.md`),render:()=>T(n,s,r)}),d&&h.push({file:c(e.outDir,`CLAUDE.md`),render:()=>w(n,s,r)}),f)for(let t of D(n,s,r,l))h.push({file:c(e.outDir,j,`skills`,t.slug,`SKILL.md`),render:()=>t.content});p&&h.push({file:c(e.outDir,j,`GEMINI.md`),render:()=>O(n,s,r)}),m&&h.push({file:c(e.outDir,j,`COPILOT.md`),render:()=>k(n,s,r)});let g=[];for(let{file:t,render:n}of h)o(t)&&!e.force&&!await b({message:`${t.replace(e.outDir+`/`,``)} already exists. Overwrite?`,initialValue:!1})?console.log(`  Skipped — existing ${t.replace(e.outDir+`/`,``)} preserved.`):(await a(t,n()),g.push(t));return g}export{S as a,v as c,f as d,u as f,m as i,x as l,I as n,y as o,p,b as r,h as s,A as t,_ as u};

package/dist/{agent-docs-CmPrfpaP.mjs → agent-docs-ZgfnGL-j.mjs}

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v8.10.0
+ * @forinda/kickjs-cli v8.10.2
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,7 +8,7 @@
  *
  * @license MIT
  */
-import{t as e}from"./rolldown-runtime-vT0bVE76.mjs";import{r as t}from"./fs-gRPNbfZO.mjs";import{t as n}from"./prompts-DKR7UZkc.mjs";import{o as r}from"./config-B7ZUrOl6.mjs";import{join as i}from"node:path";import{existsSync as a,readFileSync as o}from"node:fs";function s(e,t,n){return`# CLAUDE.md — ${e}
+import{t as e}from"./rolldown-runtime-7c5UUG6D.mjs";import{n as t,o as n}from"./package-manager-DBmD5nSr.mjs";import{t as r}from"./prompts-D4nwf5mP.mjs";import{d as i,i as a,s as o}from"./config-CsOfUFfq.mjs";import{join as s}from"node:path";import{existsSync as c,readFileSync as l}from"node:fs";function u(e,t){let n=e;return t===`fullstack`&&n!==`pnpm`?`${i(n,`dev:server`)} + ${i(n,`dev:web`)}`:i(n,`dev`)}function d(e,t,n){return`# CLAUDE.md — ${e}
 
 **Read \`./.agents/AGENTS.md\` first.** It is the canonical, multi-agent
 reference for this project (Claude, Copilot, Codex, Gemini, etc.) —
@@ -56,14 +56,17 @@ prose.
 ## Quick reference (full version in .agents/AGENTS.md)
 
 \`\`\`bash
-${n} install            # Install dependencies
-kick dev                 # Dev server with HMR + typegen
-kick build && kick start # Production
-${n} run test           # Vitest
-kick typecheck           # tsc/tsgo, whichever the project has
-kick format              # oxfmt
+${n} install
+${u(n,t)}     # Dev server with HMR + typegen
+${i(n,`build`)} && ${i(n,`start`)}  # Production
+${i(n,`test`)}    # Vitest
+${t===`fullstack`?i(n,`typecheck`):`${a(n,`kick`)} typecheck`}   # tsc/tsgo, whichever the project has
+${t===`fullstack`?i(n,`format`):`${a(n,`kick`)} format`}      # oxfmt
 \`\`\`
 
+\`kick\` is this project's dev dependency, not a global command: every \`kick …\`
+in these docs runs as \`${a(n,`kick`)} …\` in a shell.
+
 ## v4 framework reminders
 
 When generating or modifying code in this project, stay aligned with the v4 conventions documented in \`.agents/AGENTS.md\`:
@@ -83,7 +86,7 @@ When generating or modifying code in this project, stay aligned with the v4 conv
 - **Refresh these files**: \`kick g agents -f\` regenerates \`CLAUDE.md\` at the project root and \`.agents/AGENTS.md\` + \`.agents/GEMINI.md\` + \`.agents/COPILOT.md\` + every \`.agents/skills/<name>/SKILL.md\` from the latest CLI templates. Hand-edited content is overwritten — keep customisation in \`.agents/AGENTS.local.md\` or per-skill \`SKILL.local.md\` files alongside.
 
 For everything else (controllers, services, modules, RequestContext API, generators, CLI commands, package additions, env wiring, troubleshooting) → \`.agents/AGENTS.md\`.
-`}function c(e,t,n){return`# AGENTS.md — AI Agent Guide for ${e}
+`}function f(e,t,n){return`# AGENTS.md — AI Agent Guide for ${e}
 
 This guide is the **canonical, multi-agent reference** for this KickJS
 application — Claude, Copilot, Codex, Gemini, etc. all read it first.
@@ -93,12 +96,17 @@ add tool-specific affordances on top.
 ## Before You Start
 
 1. Run \`${n} install\` to install dependencies
-2. Run \`kick dev\` to verify the app starts${t===`fullstack`?`
+2. Run \`${u(n,t)}\` to verify the app starts
+
+\`kick\` is this project's dev dependency, not a global command: every \`kick …\`
+below runs as \`${a(n,`kick`)} …\` in a shell.${t===`fullstack`?`
 
 ## Fullstack workspace layout
 
 This is a WORKSPACE root — the KickJS API lives in \`server/\`, the typed web
-app in \`web/\`. Run both with \`${n===`pnpm`?`pnpm dev`:`${n} run dev:server + ${n} run dev:web`}\`.
+app in \`web/\`. Run both with \`${u(n,t)}\`. From this root,
+\`${i(n,`test`)}\`, \`${i(n,`typecheck`)}\` and \`${i(n,`format`)}\` reach into
+\`server/\` (and \`web/\` for typecheck).
 
 The type loop (do not break it):
 1. \`server/\` handlers RETURN their payloads → \`kick typegen\` emits
@@ -112,8 +120,8 @@ The type loop (do not break it):
    relative \`/api/v1\` (Vite proxies it in dev) unless \`VITE_API_URL\` points at
    an API on another origin.
 
-Rules: kick commands (\`kick g\`, \`kick typegen\`, \`kick dev\`) run in
-\`server/\`; never import server runtime code into \`web/\` (the d.ts bridge is
+Rules: kick commands (\`kick g\`, \`kick typegen\`, \`kick dev\`, \`kick typecheck\`)
+run in \`server/\` — the root has no \`kick.config.ts\`; never import server runtime code into \`web/\` (the d.ts bridge is
 type-only); prefer return-value handlers so responses stay inferable.`:``}
 3. Read the [KickJS documentation](https://kickjs.app/) for framework details
 
@@ -493,7 +501,7 @@ page and lists the local tools (\`kick explain\`, \`kick doctor\`, \`kick inspec
 
 Start at <https://kickjs.app/>.
 
-`}function l(e,t=`define`){let n=t===`class`?`UserModule`:`UserModule()`;return[{slug:`add-module`,frontmatterName:`kickjs-add-module`,description:`Use when the user asks to add a new feature module (controller + service + repo + DTOs).`,body:`**Trigger phrases**: "add a users module", "scaffold tasks", "new feature for X".
+`}function p(e,t=`define`){let n=t===`class`?`UserModule`:`UserModule()`;return[{slug:`add-module`,frontmatterName:`kickjs-add-module`,description:`Use when the user asks to add a new feature module (controller + service + repo + DTOs).`,body:`**Trigger phrases**: "add a users module", "scaffold tasks", "new feature for X".
 
 **Steps**:
 1. Run \`kick g module <name>\` (use plural form if the project pluralizes — check \`kick.config.ts\`).
@@ -597,7 +605,43 @@ async create(ctx: Ctx<KickRoutes.TodoController['create']>) {
 
 **Nuances**:
 - \`@Inject\` and \`@Autowired\` are interchangeable — same runtime, same types; pick by readability.
-- \`@Value('MISSING_KEY')\` with no default **throws on property access**, not at construction — tests that exercise the getter will surface the missing-env issue.`},{slug:`env-wiring-check`,frontmatterName:`kickjs-env-wiring-check`,description:`Use when ConfigService.get('SOME_KEY') returns undefined or @Value silently falls back to process.env.`,body:"**Fastest path**: `kick explain \"ConfigService.get('MY_KEY') returned undefined\"` —\npipe a failing run straight in if you prefer (`pnpm test 2>&1 | kick explain`). It\ndistinguishes the entry-file cause from the test-file one, which is the step most\npeople lose time on. The manual checks below are the same reasoning.\n\n**Diagnosis (in order)**:\n1. Open `src/index.ts`. The **first non-`reflect-metadata`** import MUST be `import './config'`.\n2. Open `src/config/index.ts`. It MUST run the loader as a top-level side effect — not just declare the schema. This is what `kick new` generates:\n   ```ts\n   import { loadEnvFromSchema } from '@forinda/kickjs/config'\n   import { fromZod } from '@forinda/kickjs-schema/zod'\n   const envSchema = fromZod(z.object({ DATABASE_URL: z.url() }))\n   export const env = loadEnvFromSchema(envSchema)\n   ```\n3. The new key MUST be declared in the schema. `@Value('NEW_KEY')` accepts any string at the type level and **falls back to raw `process.env`** when the schema doesn't know the key — silently skipping its parsing and defaults.\n4. After adding a key, re-run `kick typegen` (or restart `kick dev` if the typegen watcher missed it) so the global `KickEnv` augmentation picks it up.\n\n5. **In a test?** `createTestApp` never loads `src/index.ts`, so the entry's\n   `import './config'` never runs no matter how correct it is. The test file\n   must import it itself:\n   ```ts\n   import '@/config'\n   ```\n   Symptom is identical to the missing-entry-import case, and step 1 will look\n   fine, which is what makes it slow to spot.\n\n**Why `@Value` \"works\" but `ConfigService.get` doesn't**: `@Value` has the `process.env` fallback that masks missing-side-effect-import bugs; `ConfigService` has none. If `@Value('FOO')` returns a value but `ConfigService.get('FOO')` returns `undefined`, the side-effect import of `./config` is missing.\n\n**`reloadEnv` vs `resetEnvCache`** — distinct, frequently mixed up:\n- `reloadEnv()` — re-reads `process.env` against the **already registered** schema. Use in HMR plugins after `.env` file changes. Schema survives.\n- `resetEnvCache()` — drops the registered schema entirely. **Test-only.** Calling it between dev requests drops the project's keys.\n\n**Nuances**:\n- `dotenv` is an **optional peer dep** in v5+ — projects upgrading from older versions may need to add it explicitly.\n- For HMR-friendly `.env` edits, add `envWatchPlugin()` to `vite.config.ts` — calls `reloadEnv()` automatically.\n\n**Fix recipe**: add the key to the schema; add `import './config'` as the first non-reflect-metadata import in `src/index.ts`; add `import '@/config'` to any test that reads config; re-run `kick typegen`."},{slug:`bootstrap-export`,frontmatterName:`kickjs-bootstrap-export`,description:`Use when HMR is silently doing full restarts on every save, or createTestApp can't find the app handle.`,body:"**Check** `src/index.ts`'s last line:\n\n```ts\n// CORRECT — Vite plugin + createTestApp import the named `app` symbol\nexport const app = await bootstrap({ ... })\n\n// WRONG — HMR degrades to full restart, createTestApp loses the handle\nawait bootstrap({ ... })\n```\n\nThe Vite plugin imports the named `app` symbol via `virtual:kickjs/app`; testing helpers do too. Without the export, both fall back to slower paths (full restart on save, mock handle in tests) **without warning**.\n\n**Red flags**:\n- A bare `await bootstrap(...)` with no `export` — fix by adding `export const app =`.\n- Re-assigning `app` later in the file (`app = somethingElse`) — Vite imports by reference at module-load time; reassignments don't propagate.\n- Multiple files calling `bootstrap()` — only the entry should. Tests use `createTestApp` instead."},{slug:`thin-entry-file`,frontmatterName:`kickjs-thin-entry-file`,description:`Use when src/index.ts is accumulating module/middleware/plugin/adapter literals.`,body:`**Refactor target**:
+- \`@Value('MISSING_KEY')\` with no default **throws on property access**, not at construction — tests that exercise the getter will surface the missing-env issue.`},{slug:`env-wiring-check`,frontmatterName:`kickjs-env-wiring-check`,description:`Use when ConfigService.get('SOME_KEY') returns undefined or @Value silently falls back to process.env.`,body:`**Fastest path**: \`kick explain "ConfigService.get('MY_KEY') returned undefined"\` —
+pipe a failing run straight in if you prefer (\`${i(e,`test`)} 2>&1 | ${a(e,`kick`)} explain\`). It
+distinguishes the entry-file cause from the test-file one, which is the step most
+people lose time on. The manual checks below are the same reasoning.
+
+**Diagnosis (in order)**:
+1. Open \`src/index.ts\`. The **first non-\`reflect-metadata\`** import MUST be \`import './config'\`.
+2. Open \`src/config/index.ts\`. It MUST run the loader as a top-level side effect — not just declare the schema. This is what \`kick new\` generates:
+   \`\`\`ts
+   import { loadEnvFromSchema } from '@forinda/kickjs/config'
+   import { fromZod } from '@forinda/kickjs-schema/zod'
+   const envSchema = fromZod(z.object({ DATABASE_URL: z.url() }))
+   export const env = loadEnvFromSchema(envSchema)
+   \`\`\`
+3. The new key MUST be declared in the schema. \`@Value('NEW_KEY')\` accepts any string at the type level and **falls back to raw \`process.env\`** when the schema doesn't know the key — silently skipping its parsing and defaults.
+4. After adding a key, re-run \`kick typegen\` (or restart \`kick dev\` if the typegen watcher missed it) so the global \`KickEnv\` augmentation picks it up.
+
+5. **In a test?** \`createTestApp\` never loads \`src/index.ts\`, so the entry's
+   \`import './config'\` never runs no matter how correct it is. The test file
+   must import it itself:
+   \`\`\`ts
+   import '@/config'
+   \`\`\`
+   Symptom is identical to the missing-entry-import case, and step 1 will look
+   fine, which is what makes it slow to spot.
+
+**Why \`@Value\` "works" but \`ConfigService.get\` doesn't**: \`@Value\` has the \`process.env\` fallback that masks missing-side-effect-import bugs; \`ConfigService\` has none. If \`@Value('FOO')\` returns a value but \`ConfigService.get('FOO')\` returns \`undefined\`, the side-effect import of \`./config\` is missing.
+
+**\`reloadEnv\` vs \`resetEnvCache\`** — distinct, frequently mixed up:
+- \`reloadEnv()\` — re-reads \`process.env\` against the **already registered** schema. Use in HMR plugins after \`.env\` file changes. Schema survives.
+- \`resetEnvCache()\` — drops the registered schema entirely. **Test-only.** Calling it between dev requests drops the project's keys.
+
+**Nuances**:
+- \`dotenv\` is an **optional peer dep** in v5+ — projects upgrading from older versions may need to add it explicitly.
+- For HMR-friendly \`.env\` edits, add \`envWatchPlugin()\` to \`vite.config.ts\` — calls \`reloadEnv()\` automatically.
+
+**Fix recipe**: add the key to the schema; add \`import './config'\` as the first non-reflect-metadata import in \`src/index.ts\`; add \`import '@/config'\` to any test that reads config; re-run \`kick typegen\`.`},{slug:`bootstrap-export`,frontmatterName:`kickjs-bootstrap-export`,description:`Use when HMR is silently doing full restarts on every save, or createTestApp can't find the app handle.`,body:"**Check** `src/index.ts`'s last line:\n\n```ts\n// CORRECT — Vite plugin + createTestApp import the named `app` symbol\nexport const app = await bootstrap({ ... })\n\n// WRONG — HMR degrades to full restart, createTestApp loses the handle\nawait bootstrap({ ... })\n```\n\nThe Vite plugin imports the named `app` symbol via `virtual:kickjs/app`; testing helpers do too. Without the export, both fall back to slower paths (full restart on save, mock handle in tests) **without warning**.\n\n**Red flags**:\n- A bare `await bootstrap(...)` with no `export` — fix by adding `export const app =`.\n- Re-assigning `app` later in the file (`app = somethingElse`) — Vite imports by reference at module-load time; reassignments don't propagate.\n- Multiple files calling `bootstrap()` — only the entry should. Tests use `createTestApp` instead."},{slug:`thin-entry-file`,frontmatterName:`kickjs-thin-entry-file`,description:`Use when src/index.ts is accumulating module/middleware/plugin/adapter literals.`,body:`**Refactor target**:
 
 \`\`\`ts
 // src/modules/index.ts — fluent chain (default for \`modules.style: 'define'\`)
@@ -793,7 +837,7 @@ fine and fails at runtime.
 **Local, and usually faster**
 
 - \`kick explain "<error message>"\` — matches known failures and gives the fix.
-  Pipe a failing run in: \`${e} test 2>&1 | kick explain\`.
+  Pipe a failing run in: \`${i(e,`test`)} 2>&1 | ${a(e,`kick`)} explain\`.
 - \`kick doctor\` — checks this project's wiring.
 - \`kick inspect\` — the live route / adapter table.
 - \`.kickjs/types/\` — generated types are ground truth for what exists.
@@ -802,7 +846,7 @@ fine and fails at runtime.
 
 **Rule**: if you would be guessing, look it up. If a doc page contradicts the
 installed \`.d.mts\`, trust the \`.d.mts\` and say so — the docs may be behind the
-version this project has.`},{slug:`refresh-agent-docs`,frontmatterName:`kickjs-refresh-agent-docs`,description:`Use after a KickJS version bump to sync the .agents/ docs with the latest CLI templates.`,body:"**Steps**:\n1. `kick g agents -f --only both` — overwrites `CLAUDE.md` (root) and `.agents/AGENTS.md`.\n2. `kick g agents -f --only skills` — refreshes every `.agents/skills/<slug>/SKILL.md`.\n3. `kick g agents -f --only gemini` / `--only copilot` — refresh the per-agent files when needed.\n4. Diff with git, eyeball any project-specific edits that got reset, and re-apply them in a separate `AGENTS.local.md` or per-skill `SKILL.local.md` alongside.\n5. Commit as `docs(agents): sync from CLI vX.Y`.\n\n**`.agents/` layout** (post-restructure):\n\n```\nCLAUDE.md                 # at root — Claude Code auto-loads from here\n.agents/\n├── AGENTS.md             # canonical multi-agent reference\n├── GEMINI.md             # Gemini-specific notes\n├── COPILOT.md            # Copilot CLI notes\n└── skills/\n    ├── add-module/SKILL.md\n    ├── add-adapter/SKILL.md\n    └── …                 # one SKILL.md per skill, frontmatter-namespaced\n```\n\nCustomisation goes in `.local.md` siblings (`AGENTS.local.md`, `skills/<slug>/SKILL.local.md`) — those are never overwritten."},{slug:`deny-list`,frontmatterName:`kickjs-deny-list`,description:`Patterns to refuse outright when the user asks for them — they break v4 invariants.`,body:"**Module / adapter / plugin shape**:\n- `class implements AppAdapter` → use `defineAdapter()`.\n- `class implements KickPlugin` / function returning `KickPlugin` → use `definePlugin()`.\n- `class implements AppModule` for new code → use `defineModule()`.\n- `bootstrap({ adapters: [MyAdapter] })` (factory) → `MyAdapter()` (instance, with parens).\n- `@Controller('/path')` with a path argument → `@Controller()`, with the prefix in `routes().path`.\n- Module file named `<name>.ts` (no `.module` suffix) → rename to `<name>.module.ts`. Vite HMR's glob doesn't pick up the unsuffixed form.\n\n**DI**:\n- `new Container()` or `Container.getInstance().reset()` in tests → use `Container.reset()` in `beforeEach` (or `Container.create()` for fully isolated graphs).\n- DI tokens with `:` separator (`'app:db:url'`) or in PascalCase → use slash-delimited lower-case (`'app/db/url'`). First-party uses reserved `'kick/'` prefix.\n- `Symbol.for(...)` for DI tokens — globally interned, **collides across files**. Use `createToken<T>('name')`.\n- Raw string tokens (`@Inject('config')`) — silent collisions; widens to `unknown`. Use `createToken<T>`.\n- Injecting a `Scope.REQUEST` service into a `SINGLETON` — container throws at resolve time.\n\n**Bootstrap / entry file**:\n- `bootstrap({ ... })` without `export const app = ...` → always export. HMR degrades to full restart and `createTestApp` loses the handle.\n- `bootstrap({ register: ... })` — that option doesn't exist. Use an inline plugin in `plugins`.\n\n**Middleware**:\n- Using `(ctx, next)` for global middleware in `bootstrap({ middlewares })` — global middleware uses raw Express `(req, res, next)`. Wrong signature throws \"Cannot read properties of undefined\".\n- Using `(req, res, next)` for an `@Middleware()` decorator — those use `(ctx, next)`.\n- `@Middleware()` whose only output is `ctx.set('x', v)` — should be a context decorator (typed, ordered, testable).\n\n**Context contributors**:\n- `ctx.tenant = x` from a contributor — only sticks to one `RequestContext` instance. **Return the value** so the runner writes it via `ctx.set(key, value)`.\n- Omitting the `declare module '@forinda/kickjs'` block — without it `ctx.get('tenant')` is `unknown`.\n- `getRequestValue<string>('traceId')` — generic is the **key** type, not value type.\n\n**Env / config**:\n- `@Value('NEW_KEY')` without the key in the Zod schema — silent fallback to raw `process.env`, no coercion.\n- `resetEnvCache()` outside tests — drops the registered schema.\n\n**List endpoints**:\n- Reading `req.query.status` directly — bypasses the allow-list. Use `ctx.qs({ filterable })`.\n- Returning a bare array from a list endpoint — breaks the `PaginatedResponse<T>` contract. Use `ctx.paginate()`.\n\n**Assets**:\n- Hand-rolled `__dirname` arithmetic for template paths — use `assets.<ns>.<key>()` and add the namespace to `kick.config.ts assetMap`."}]}function u(e,t,n,r=`define`){let i=`<!-- Generated by \`kick g agents\` for ${e}. Edits are overwritten on the next refresh; keep customisation in a SKILL.local.md alongside. -->`;return l(n,r).map(e=>({slug:e.slug,content:`---
+version this project has.`},{slug:`refresh-agent-docs`,frontmatterName:`kickjs-refresh-agent-docs`,description:`Use after a KickJS version bump to sync the .agents/ docs with the latest CLI templates.`,body:"**Steps**:\n1. `kick g agents -f --only both` — overwrites `CLAUDE.md` (root) and `.agents/AGENTS.md`.\n2. `kick g agents -f --only skills` — refreshes every `.agents/skills/<slug>/SKILL.md`.\n3. `kick g agents -f --only gemini` / `--only copilot` — refresh the per-agent files when needed.\n4. Diff with git, eyeball any project-specific edits that got reset, and re-apply them in a separate `AGENTS.local.md` or per-skill `SKILL.local.md` alongside.\n5. Commit as `docs(agents): sync from CLI vX.Y`.\n\n**`.agents/` layout** (post-restructure):\n\n```\nCLAUDE.md                 # at root — Claude Code auto-loads from here\n.agents/\n├── AGENTS.md             # canonical multi-agent reference\n├── GEMINI.md             # Gemini-specific notes\n├── COPILOT.md            # Copilot CLI notes\n└── skills/\n    ├── add-module/SKILL.md\n    ├── add-adapter/SKILL.md\n    └── …                 # one SKILL.md per skill, frontmatter-namespaced\n```\n\nCustomisation goes in `.local.md` siblings (`AGENTS.local.md`, `skills/<slug>/SKILL.local.md`) — those are never overwritten."},{slug:`deny-list`,frontmatterName:`kickjs-deny-list`,description:`Patterns to refuse outright when the user asks for them — they break v4 invariants.`,body:"**Module / adapter / plugin shape**:\n- `class implements AppAdapter` → use `defineAdapter()`.\n- `class implements KickPlugin` / function returning `KickPlugin` → use `definePlugin()`.\n- `class implements AppModule` for new code → use `defineModule()`.\n- `bootstrap({ adapters: [MyAdapter] })` (factory) → `MyAdapter()` (instance, with parens).\n- `@Controller('/path')` with a path argument → `@Controller()`, with the prefix in `routes().path`.\n- Module file named `<name>.ts` (no `.module` suffix) → rename to `<name>.module.ts`. Vite HMR's glob doesn't pick up the unsuffixed form.\n\n**DI**:\n- `new Container()` or `Container.getInstance().reset()` in tests → use `Container.reset()` in `beforeEach` (or `Container.create()` for fully isolated graphs).\n- DI tokens with `:` separator (`'app:db:url'`) or in PascalCase → use slash-delimited lower-case (`'app/db/url'`). First-party uses reserved `'kick/'` prefix.\n- `Symbol.for(...)` for DI tokens — globally interned, **collides across files**. Use `createToken<T>('name')`.\n- Raw string tokens (`@Inject('config')`) — silent collisions; widens to `unknown`. Use `createToken<T>`.\n- Injecting a `Scope.REQUEST` service into a `SINGLETON` — container throws at resolve time.\n\n**Bootstrap / entry file**:\n- `bootstrap({ ... })` without `export const app = ...` → always export. HMR degrades to full restart and `createTestApp` loses the handle.\n- `bootstrap({ register: ... })` — that option doesn't exist. Use an inline plugin in `plugins`.\n\n**Middleware**:\n- Using `(ctx, next)` for global middleware in `bootstrap({ middlewares })` — global middleware uses raw Express `(req, res, next)`. Wrong signature throws \"Cannot read properties of undefined\".\n- Using `(req, res, next)` for an `@Middleware()` decorator — those use `(ctx, next)`.\n- `@Middleware()` whose only output is `ctx.set('x', v)` — should be a context decorator (typed, ordered, testable).\n\n**Context contributors**:\n- `ctx.tenant = x` from a contributor — only sticks to one `RequestContext` instance. **Return the value** so the runner writes it via `ctx.set(key, value)`.\n- Omitting the `declare module '@forinda/kickjs'` block — without it `ctx.get('tenant')` is `unknown`.\n- `getRequestValue<string>('traceId')` — generic is the **key** type, not value type.\n\n**Env / config**:\n- `@Value('NEW_KEY')` without the key in the Zod schema — silent fallback to raw `process.env`, no coercion.\n- `resetEnvCache()` outside tests — drops the registered schema.\n\n**List endpoints**:\n- Reading `req.query.status` directly — bypasses the allow-list. Use `ctx.qs({ filterable })`.\n- Returning a bare array from a list endpoint — breaks the `PaginatedResponse<T>` contract. Use `ctx.paginate()`.\n\n**Assets**:\n- Hand-rolled `__dirname` arithmetic for template paths — use `assets.<ns>.<key>()` and add the namespace to `kick.config.ts assetMap`."}]}function m(e,t,n,r=`define`){let i=`<!-- Generated by \`kick g agents\` for ${e}. Edits are overwritten on the next refresh; keep customisation in a SKILL.local.md alongside. -->`;return p(n,r).map(e=>({slug:e.slug,content:`---
 name: ${e.frontmatterName}
 description: ${e.description}
 ---
@@ -810,7 +854,7 @@ description: ${e.description}
 ${i}
 
 ${e.body}
-`}))}function d(e,t,n){return`# GEMINI.md — ${e}
+`}))}function h(e,t,n){return`# GEMINI.md — ${e}
 
 **Read \`./AGENTS.md\` first.** It is the canonical, multi-agent
 reference for this project — every convention, structure, decorator
@@ -844,7 +888,7 @@ without us copy-pasting.
 \`kick g agents --only gemini -f\` regenerates this file from the
 CLI template. Hand-edited content is overwritten — keep customisation
 in \`.agents/GEMINI.local.md\`.
-`}function f(e,t,n){return`# COPILOT.md — ${e}
+`}function g(e,t,n){return`# COPILOT.md — ${e}
 
 **Read \`./AGENTS.md\` first.** It is the canonical, multi-agent
 reference for this project — every convention, structure, decorator
@@ -877,5 +921,5 @@ Codex / Cursor / Gemini / Claude Code without copy-pasting.
 \`kick g agents --only copilot -f\` regenerates this file from the
 CLI template. Hand-edited content is overwritten — keep customisation
 in \`.agents/COPILOT.local.md\`.
-`}var p=/* @__PURE__ */ e({generateAgentDocs:()=>b});const m=`.agents`,h=/* @__PURE__ */ new Set([`rest`,`minimal`,`fullstack`,`inertia`]);function g(e,t){if(t)return t;try{let t=JSON.parse(o(i(e,`package.json`),`utf-8`));if(t.name)return t.name.replace(/^@[^/]+\//,``)}catch{}return e.split(`/`).findLast(Boolean)??`app`}function _(e,t){if(t)return t;try{let t=JSON.parse(o(i(e,`package.json`),`utf-8`));if(t.packageManager)return t.packageManager.split(`@`)[0]}catch{}return`pnpm`}async function v(e){try{return(await r(e))?.modules?.style===`class`?`class`:`define`}catch{return`define`}}async function y(e,t){if(t)return t;try{let t=(await r(e))?.pattern;if(t&&h.has(t))return t}catch{}return`rest`}async function b(e){let r=e.only??`all`,o=g(e.outDir,e.name),l=_(e.outDir,e.pm),p=await y(e.outDir,e.template),h=await v(e.outDir),b=r===`agents`||r===`both`||r===`all`,x=r===`claude`||r===`both`||r===`all`,S=r===`skills`||r===`all`,C=r===`gemini`||r===`all`,w=r===`copilot`||r===`all`,T=[];if(b&&T.push({file:i(e.outDir,m,`AGENTS.md`),render:()=>c(o,p,l)}),x&&T.push({file:i(e.outDir,`CLAUDE.md`),render:()=>s(o,p,l)}),S)for(let t of u(o,p,l,h))T.push({file:i(e.outDir,m,`skills`,t.slug,`SKILL.md`),render:()=>t.content});C&&T.push({file:i(e.outDir,m,`GEMINI.md`),render:()=>d(o,p,l)}),w&&T.push({file:i(e.outDir,m,`COPILOT.md`),render:()=>f(o,p,l)});let E=[];for(let{file:r,render:i}of T)a(r)&&!e.force&&!await n({message:`${r.replace(e.outDir+`/`,``)} already exists. Overwrite?`,initialValue:!1})?console.log(`  Skipped — existing ${r.replace(e.outDir+`/`,``)} preserved.`):(await t(r,i()),E.push(r));return E}export{b as n,p as t};
-//# sourceMappingURL=agent-docs-CmPrfpaP.mjs.map
+`}var _=/* @__PURE__ */ e({generateAgentDocs:()=>C});const v=`.agents`,y=/* @__PURE__ */ new Set([`rest`,`minimal`,`fullstack`,`inertia`]);function b(e,t){if(t)return t;try{let t=JSON.parse(l(s(e,`package.json`),`utf-8`));if(t.name)return t.name.replace(/^@[^/]+\//,``)}catch{}return e.split(`/`).findLast(Boolean)??`app`}async function x(e){try{return(await o(e))?.modules?.style===`class`?`class`:`define`}catch{return`define`}}async function S(e,t){if(t)return t;try{let t=(await o(e))?.pattern;if(t&&y.has(t))return t}catch{}return`rest`}async function C(e){let i=e.only??`all`,a=b(e.outDir,e.name),o=await t(e.pm,e.outDir),l=await S(e.outDir,e.template),u=await x(e.outDir),p=i===`agents`||i===`both`||i===`all`,_=i===`claude`||i===`both`||i===`all`,y=i===`skills`||i===`all`,C=i===`gemini`||i===`all`,w=i===`copilot`||i===`all`,T=[];if(p&&T.push({file:s(e.outDir,v,`AGENTS.md`),render:()=>f(a,l,o)}),_&&T.push({file:s(e.outDir,`CLAUDE.md`),render:()=>d(a,l,o)}),y)for(let t of m(a,l,o,u))T.push({file:s(e.outDir,v,`skills`,t.slug,`SKILL.md`),render:()=>t.content});C&&T.push({file:s(e.outDir,v,`GEMINI.md`),render:()=>h(a,l,o)}),w&&T.push({file:s(e.outDir,v,`COPILOT.md`),render:()=>g(a,l,o)});let E=[];for(let{file:t,render:i}of T)c(t)&&!e.force&&!await r({message:`${t.replace(e.outDir+`/`,``)} already exists. Overwrite?`,initialValue:!1})?console.log(`  Skipped — existing ${t.replace(e.outDir+`/`,``)} preserved.`):(await n(t,i()),E.push(t));return E}export{C as n,_ as t};
+//# sourceMappingURL=agent-docs-ZgfnGL-j.mjs.map