@forinda/kickjs-cli 8.7.8 → 8.8.0

package/bin.js

@@ -2,7 +2,7 @@
 
 // ESM wrapper for the ESM CLI entry.
 // Bin entries must be plain .js (not .mjs) for universal Node.js compatibility.
-import("./dist/cli.mjs").catch((err) => {
-  console.error("Failed to load CLI:", err)
+import('./dist/cli.mjs').catch((err) => {
+  console.error('Failed to load CLI:', err)
   process.exit(1)
 })

package/dist/{agent-docs-z03QAZuD.mjs → agent-docs-BsXKM5QH.mjs}

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v8.7.8
+ * @forinda/kickjs-cli v8.8.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,7 +8,7 @@
  *
  * @license MIT
  */
-import{t as e}from"./rolldown-runtime-DBz5c2Bd.mjs";import{r as t}from"./fs-Cng50pl3.mjs";import{t as n}from"./prompts-CV5JHDs4.mjs";import{o as r}from"./config-wzsPHJ1r.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-OACgOwtl.mjs";import{r as t}from"./fs-BB3QxPj8.mjs";import{t as n}from"./prompts-BJTp1w0l.mjs";import{o as r}from"./config-F9g6CNDA.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}
 
 **Read \`./.agents/AGENTS.md\` first.** It is the canonical, multi-agent
 reference for this project (Claude, Copilot, Codex, Gemini, etc.) —
@@ -101,12 +101,16 @@ 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`}\`.
 
 The type loop (do not break it):
-1. \`server/\` handlers RETURN their payloads → \`kick typegen\` (auto under
-   \`kick dev\`) emits \`server/.kickjs/types/kick__routes.ts\` incl. the flat
-   \`KickRoutes.Api\` map with inferred response types.
-2. \`web/src/types/kick-routes.d.ts\` imports that file TYPE-ONLY.
-3. \`web/src/api.ts\` = \`createClient<KickApi>({ baseUrl: '/api/v1' })\`
-   — every call site is typed from the server's handlers.
+1. \`server/\` handlers RETURN their payloads → \`kick typegen\` emits
+   \`server/.kickjs/types/kick__client.d.ts\`: the ambient \`KickClientApi\`
+   namespace, every response resolved to a plain shape. \`kick dev\` writes it
+   at startup but NOT on save — run \`kick typegen\` in \`server/\` after changing a route or a
+   response (the root \`build\` script runs it too).
+2. \`web/tsconfig.json\` lists that file in \`compilerOptions.types\`.
+3. \`web/src/api.ts\` = \`createClient<KickClientApi.Api>({ baseUrl })\`
+   — every call site is typed from the server's handlers. \`baseUrl\` is the
+   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
@@ -142,7 +146,7 @@ Rules that keep generated code correct on **every** engine:
   Don't assume \`ctx.req\` is an \`express.Request\` in portable code.
 - **Global middleware** in \`bootstrap({ middlewares })\` is connect-style
   \`(req, res, next)\` — it runs on all engines (Fastify via \`@fastify/middie\`,
-  h3 via \`fromNodeMiddleware\`). But on Fastify / h3 the engine parses the body
+  h3 via \`fromNodeHandler\`). But on Fastify / h3 the engine parses the body
   natively, so the default \`express.json()\` is **auto-skipped** (\`nativeBodyParsing\`).
   Don't add \`express.json()\` manually on those engines.
 - **File uploads** work on all three: \`@FileUpload({ mode, fieldName, ... })\` →
@@ -631,7 +635,7 @@ plugins: [
 **Red flags**:
 - Any \`new SomeAdapter()\` / \`SomePlugin()\` literal inside \`bootstrap({ ... })\` instead of imported from a category folder.
 - Mixing middleware signatures: \`bootstrap({ middlewares })\` is **raw Express** \`(req, res, next)\`; \`@Middleware()\` decorators are \`(ctx, next)\`; adapter middleware is connect-style too (mounted through the runtime seam, so it is not Express-only). Wrong shape in the wrong slot throws "Cannot read properties of undefined".
-- \`bootstrap({ register: ... })\` — that option doesn't exist. Use an inline plugin.`},{slug:`context-contributor`,frontmatterName:`kickjs-context-contributor`,description:`Use when a middleware's only job is to set ctx values consumed elsewhere — replace with defineHttpContextDecorator (HTTP) or defineContextDecorator (transport-agnostic).`,body:"**Pattern** (HTTP — most common):\n\n```ts\nimport { defineHttpContextDecorator, type RequestContext } from '@forinda/kickjs'\n\n// Augment ContextMeta — required for ctx.get('tenant') to be typed\ndeclare module '@forinda/kickjs' {\n  interface ContextMeta {\n    tenant: { id: string; name: string }\n  }\n}\n\n// The `declare module` block above is all you need for typed `ctx.get`.\n\nconst LoadTenant = defineHttpContextDecorator({\n  key: 'tenant',\n  deps: { repo: TENANT_REPO }, // typed DI\n  resolve: (ctx, { repo }) => repo.findById(ctx.req.headers['x-tenant-id'] as string),\n})\n\nconst LoadProject = defineHttpContextDecorator({\n  key: 'project',\n  dependsOn: ['tenant'], // typo'd key = tsc error\n  resolve: (ctx) => projectsRepo.find(ctx.get('tenant')!.id, ctx.params.id),\n})\n\n@LoadTenant\n@LoadProject\n@Get('/projects/:id')\ngetProject(ctx: RequestContext) {\n  return ctx.get('project')\n}\n```\n\nUse `defineContextDecorator` (no Http prefix) only when the contributor must run across HTTP, WebSocket, queue, and cron transports — `Ctx` defaults to the smaller `ExecutionContext` surface (`get` / `set` / `requestId` only, no `req`).\n\n**Five precedence levels** (high → low):\n**method > class > module > adapter > global**\n\nSame-key collisions WITHIN a precedence level throw `DuplicateContributorError`. Across levels, the higher precedence silently overrides — a feature, not a bug, but debug it by giving resolvers distinguishable return values.\n\n**Boot-time validation**:\n- Cycles in `dependsOn` → `ContributorCycleError`.\n- `dependsOn` referring to an unknown key → `MissingContributorError`.\n- Both errors fail boot, not first request.\n\n**Critical rules — all stem from the same shared-via-ALS instance model**:\n- Every per-request stage (middleware → contributors → handler) gets its OWN `RequestContext` instance, but they all read/write the SAME `AsyncLocalStorage`-backed bag.\n- **`resolve` and `onError` must RETURN the value** — the runner writes it via `ctx.set(key, value)`. Direct property assignment (`ctx.tenant = …`) sticks to one instance only and the handler instance never sees it.\n- `ctx.set('tenant', x)` then `ctx.get('tenant')` works across instances. `ctx.req.headers[...]` works (the underlying node request is shared). Note it is a node `IncomingMessage` on Fastify and h3, not an `express.Request`.\n- Services with no `ctx` reference: `getRequestValue('tenant')` returns `MetaValue<'tenant'> | undefined` (typed via the augmented `ContextMeta`). For `requestId` use `getRequestStore()`.\n- **No `setRequestValue` — writes flow through `ctx.set` or a contributor's return value.** Avoids \"spooky action at a distance\" where any service can pollute the per-request bag.\n\n**Error matrix**:\n- `optional: true` — `resolve` throws → key left unset; downstream sees `ctx.get(key) === undefined`.\n- `optional: false` (default) + `onError` — return a fallback value to write; return `undefined` to skip; throw to forward to the request error handler.\n- `optional: false` + no `onError` — throw propagates straight to the request error handler.\n\n**Don't use this for**: response short-circuit, stream mutation, or pre-route-matching work — keep `@Middleware()` for those.\n\n**Red flags**:\n- `ctx.get('key')!` — the non-null assertion compiles even when the producing decorator isn't on the route. Use `ctx.require('key')`.\n- `contributors: [LoadX]` at a module / adapter / bootstrap site — those take registrations: `LoadX.registration` or `LoadX.with({ ... }).registration`.\n- A `paramDefaults` value that every call site overrides (`action: 'settings:read'`) — drop it and let the compiler require the field at each site.\n- `defineContextDecorator<'k', Deps, Params>(spec)` positional form for a parameterised contributor — use `.withParams<Params>()(spec)` or `deps` inference is lost.\n- `ctx.tenant = x` instead of returning the value from `resolve` — sticks to one instance only.\n- Plugin / adapter authors using bare keys (`'state'`) instead of namespaced (`'@my-plugin/state'`) — collides with adopter keys.\n- `getRequestValue<string>('traceId')` — generic is the **key** type, not value type."},{slug:`guard-vs-middleware-vs-contributor`,frontmatterName:`kickjs-guard-vs-middleware-vs-contributor`,description:`Use when adding auth checks, request-scoped values, or anything "before the handler" — picks between a guard, a middleware, and a context contributor.`,body:"**KickJS has no guard primitive.** There is no `@Guard`, no `canActivate`, no guard\nclass to implement. A guard IS a middleware — the word only names a convention\nand a directory. If you are porting NestJS habits, this is the first thing to\nunlearn.\n\n| | Guard | Middleware | Context contributor |\n|---|---|---|---|\n| What it is | a middleware, by convention | a middleware | a declarative value producer |\n| Signature | `(ctx, next)` | `(ctx, next)` on `@Middleware()`, `(req, res, next)` in `bootstrap({ middlewares })` | `resolve(ctx, deps)` returning a value |\n| Can end the request | yes | yes | **no** |\n| Runs | in the middleware stage | in the middleware stage | after ALL middleware |\n| Attached by | `@Middleware(fn)` | `@Middleware(fn)` or `bootstrap({ middlewares })` | `@LoadX`, or a registration at module / adapter / bootstrap level |\n| Generator | `kick g guard <name>` | `kick g middleware <name>` | `kick g contributor <name>` |\n| Lands in | `src/guards/<name>.guard.ts` | `src/middleware/<name>.middleware.ts` | `src/contributors/<name>.contributor.ts` |\n\nAdd `-m <module>` to any of those generators to place the file inside a module\ninstead of the app-level directory.\n\n**Choosing**: does the thing ever need to STOP the request?\n- Yes, and it is authorization → guard.\n- Yes, anything else (rate limit, body rewrite, response stream, work before route matching) → middleware.\n- No, it only computes a value the handler or a service reads off `ctx` → contributor. Typed, ordered, boot-validated, and it cannot silently swallow the request.\n\n**Ordering — guards run BEFORE contributors.** Every runtime does the same\nthing: run `entry.middlewares` in order, bail if the response was written,\nthen run the contributor pipeline, then the handler. So:\n\n```ts\n// WRONG — tenant is always undefined here.\nexport async function tenantGuard(ctx: RequestContext, next: () => void) {\n  const tenant = ctx.get('tenant') // contributors have not run yet\n  if (!tenant) return ctx.problem.forbidden()\n  next()\n}\n```\n\nA guard that needs a resolved value must resolve it itself, or the check\nbelongs in the contributor's own `resolve` (throw from there and the request\nerror handler takes over).\n\n**Write responses with `ctx.*`, never `ctx.res`.** `ctx.res` is the ENGINE-NATIVE\nresponse object, so `ctx.res.status(401).json(...)` only works on Express —\n`FastifyReply` has no `.json()` and h3's event has no `.status()`. Use\n`ctx.problem.unauthorized({ detail })` (RFC 9457) or `ctx.json(body, status)`,\nand the helper for anything else you would reach `ctx.res` for:\n`ctx.download(buffer, filename, contentType?)` for a generated file,\n`ctx.html(content)`, `ctx.redirect(url, status?)`, `ctx.sse()` for a stream.\nAll of them work on all four runtimes. Never hand `ctx.redirect` a destination\ntaken from the request unchecked — allow-list it, or accept only a same-site path\n(one leading `/`, not `//`) — or the route is an open redirect.\n\n**Guard shape**:\n\n```ts\nimport type { RequestContext } from '@forinda/kickjs'\n\nexport async function adminGuard(ctx: RequestContext, next: () => void): Promise<void> {\n  // Requires the session() middleware. Type the key once:\n  // declare module '@forinda/kickjs' { interface SessionData { role?: 'admin' | 'member' } }\n  const role = ctx.session?.data.role\n  if (!role) {\n    ctx.problem.unauthorized({ detail: 'Not signed in' })\n    return // do NOT call next()\n  }\n  if (role !== 'admin') {\n    ctx.problem.forbidden({ detail: 'Admin only' })\n    return\n  }\n  next()\n}\n```\n\n```ts\n@Middleware(adminGuard)\n@Get('/admin/stats')\nstats(ctx: RequestContext) { ... }\n```\n\nRole checks that are purely declarative (`@Public()`, `@Roles('admin')`,\n`@Can(...)`) are yours to define — see the BYO Auth recipe in the docs.\nHand-write a guard only for logic those don't express.\n\n**Red flags**:\n- `class AdminGuard implements CanActivate` / `@UseGuards()` — NestJS, not KickJS. Export a `(ctx, next)` function and attach with `@Middleware()`.\n- A guard calling `next()` AND writing a response — pick one; writing then continuing double-sends.\n- A guard reading `ctx.get(...)` for a contributor-produced key — contributors have not run yet.\n- `ctx.res.status(403).json(...)` in a guard — Express-only. Use `ctx.problem.forbidden()`.\n- A \"guard\" that only sets a value and always calls `next()` — that is a contributor wearing a guard's name.\n- Passing a `(ctx, next)` guard to `bootstrap({ middlewares })` — global middleware is connect-style `(req, res, next)`. Mount guards per-route with `@Middleware()`.\n"},{slug:`query-parsing-list-endpoint`,frontmatterName:`kickjs-query-parsing-list-endpoint`,description:`Use when adding a paginated/filterable list route — emit ctx.qs + ctx.paginate with an allow-list.`,body:"**Canonical list endpoint**:\n\n```ts\n@Get('/')\nasync list(ctx: Ctx<KickRoutes.TodoController['list']>) {\n  const parsed = ctx.qs({\n    filterable: ['status', 'priority', 'assigneeId'], // allow-list, MUST be set\n    sortable: ['createdAt', 'updatedAt', 'priority'],\n    searchColumns: ['title', 'description'], // free-text search targets\n  })\n\n  return ctx.paginate(async () => {\n    const { data, total } = await this.service.list(parsed)\n    return { data, total }\n  }, parsed)\n}\n```\n\n**Operator format** (fixed): `?filter=field:op:value` where `op ∈ eq | neq | gt | gte | lt | lte | between | in | contains | starts | ends`. Sort is `?sort=field:asc|desc`. Only the first two colons are delimiters, so timestamps work (`createdAt:gt:2026-01-01T00:00:00Z`).\n\n**Drizzle adopters** — pass a `DrizzleQueryParamsConfig` with column refs:\n\n```ts\nconst TASK_QUERY_CONFIG = {\n  filterable: { status: tasks.status, priority: tasks.priority },\n  sortable: { createdAt: tasks.createdAt },\n  searchColumns: [tasks.title, tasks.description],\n}\nconst parsed = ctx.qs(TASK_QUERY_CONFIG)\n```\n\n**ORM-agnostic builders** — implement `QueryBuilderAdapter<TResult, TConfig>` with `build(parsed, config)`. The Drizzle + Prisma adapters live here.\n\n**Red flags**:\n- Reading `req.query.status` directly — bypasses the allow-list; opens unbounded filtering. Use `ctx.qs({ filterable })`.\n- Omitting `filterable` / `sortable` allow-list — every client-supplied filter is **silently dropped** (security default, but looks like a bug).\n- Hand-building the pagination meta in the controller — inconsistent response shape across endpoints. Always use `ctx.paginate()`.\n- Returning a bare array from a list endpoint when pagination is implied — breaks the `PaginatedResponse<T>` contract.\n- Mixing string `searchable` config with column `searchColumns` (Drizzle) — silently no-ops.\n\n**Nuances**:\n- `limit` is capped at 100 server-side; `q` (search) is truncated to 200 chars. Don't re-validate client-side.\n- Sort direction defaults to `asc` when omitted (`?sort=createdAt` ≡ `?sort=createdAt:asc`)."},{slug:`use-asset-manager`,frontmatterName:`kickjs-use-asset-manager`,description:`Use when code reads template files / JSON fixtures via fs.readFile + path arithmetic — switch to assets.<ns>.<key>() and the kick.config.ts assetMap.`,body:"**Configure** `kick.config.ts`:\n\n```ts\nexport default defineConfig({\n  assetMap: {\n    mails: { src: 'src/templates/mails' },\n    reports: { src: 'src/templates/reports', glob: '**/*.{ejs,html}' },\n  },\n})\n```\n\n**Consume** via the typed Proxy — no `__dirname` arithmetic, dev/prod paths handled:\n\n```ts\nimport { assets } from '@forinda/kickjs'\n\nconst html = await assets.mails.welcome() // typed: tsc errors on bad key\n```\n\n**Class-field decorator** (lazy getter, swappable in tests):\n\n```ts\nclass WelcomeMailService {\n  @Asset('mails/welcome') private welcomeTemplate!: () => Promise<string>\n\n  async send(to: string) {\n    const body = await this.welcomeTemplate()\n  }\n}\n```\n\n**Dynamic dispatch** (CMS templates, codegen) — `resolveAsset(ns, key)` throws `UnknownAssetError` with `{ namespace, key }` fields when the key is missing.\n\n**Test fixtures** — swap via env override + cache clear:\n\n```ts\nbeforeEach(() => {\n  process.env.KICK_ASSETS_ROOT = path.resolve('__fixtures__/assets')\n  clearAssetCache()\n})\nafterEach(() => {\n  delete process.env.KICK_ASSETS_ROOT\n  clearAssetCache()\n})\n```\n\n**Red flags**:\n- Hand-rolled `process.env.NODE_ENV === 'production' ? join(__dirname, '../templates') : join(__dirname, 'templates')` — exactly what the asset manager replaces.\n- `keys: 'strip'` setting in `assetMap.<ns>` when basenames may collide — silent last-walk-wins data loss. Default `'auto'` keeps extensions only for colliding groups.\n- Non-default Vite `outDir` without mirroring in `kick.config.ts` — manifest writes at `dist/.kickjs-assets.json` but the resolver can't find it. Mirror via `build.outDir`.\n- Forgetting to re-run `kick typegen` after adding files — `assets.mails.newTemplate` is a tsc error even though the file ships. `kick dev` does this on-change; one-shot CI builds need `kick build` (or `kick build:assets` for manifest-only).\n- Same-name `welcome.ejs` + `welcome/login.ejs` — directory wins in the typed surface; the `.ejs` file still copies but isn't addressable.\n\n**Nuances**:\n- Resolution pipeline (cached): `KICK_ASSETS_ROOT` env override > built manifest at `build.outDir` / `dist` / `build` / `out` > dev-fallback in-memory walk. Manifest presence = \"running from built dist.\"\n- Dev-mode glob matcher is a lite implementation — `**/*`, `**/*.ext`, `**/*.{a,b}` are guaranteed; exotic globs warn-once and accept everything. Run `kick build:assets` to exercise the real glob engine."},{slug:`cli-commands-cheatsheet`,frontmatterName:`kickjs-cli-commands-cheatsheet`,description:`Use as a quick reference for the most common kick CLI workflows — scaffolding, dev/build/start, generation, inspection.`,body:`**Top commands**:
+- \`bootstrap({ register: ... })\` — that option doesn't exist. Use an inline plugin.`},{slug:`context-contributor`,frontmatterName:`kickjs-context-contributor`,description:`Use when a middleware's only job is to set ctx values consumed elsewhere — replace with defineHttpContextDecorator (HTTP) or defineContextDecorator (transport-agnostic).`,body:"**Pattern** (HTTP — most common):\n\n```ts\nimport { defineHttpContextDecorator, type RequestContext } from '@forinda/kickjs'\n\n// Augment ContextMeta — required for ctx.get('tenant') to be typed\ndeclare module '@forinda/kickjs' {\n  interface ContextMeta {\n    tenant: { id: string; name: string }\n  }\n}\n\n// The `declare module` block above is all you need for typed `ctx.get`.\n\nconst LoadTenant = defineHttpContextDecorator({\n  key: 'tenant',\n  deps: { repo: TENANT_REPO }, // typed DI\n  resolve: (ctx, { repo }) => repo.findById(ctx.req.headers['x-tenant-id'] as string),\n})\n\nconst LoadProject = defineHttpContextDecorator({\n  key: 'project',\n  dependsOn: ['tenant'], // typo'd key = tsc error\n  resolve: (ctx) => projectsRepo.find(ctx.get('tenant')!.id, ctx.params.id),\n})\n\n@LoadTenant\n@LoadProject\n@Get('/projects/:id')\ngetProject(ctx: RequestContext) {\n  return ctx.get('project')\n}\n```\n\nUse `defineContextDecorator` (no Http prefix) only when the contributor must run across HTTP, WebSocket, queue, and cron transports — `Ctx` defaults to the smaller `ExecutionContext` surface (`get` / `set` / `requestId` only, no `req`).\n\n**Five precedence levels** (high → low):\n**method > class > module > adapter > global**\n\nSame-key collisions WITHIN a precedence level throw `DuplicateContributorError`. Across levels, the higher precedence silently overrides — a feature, not a bug, but debug it by giving resolvers distinguishable return values.\n\n**Boot-time validation**:\n- Cycles in `dependsOn` → `ContributorCycleError`.\n- `dependsOn` referring to an unknown key → `MissingContributorError`.\n- Both errors fail boot, not first request.\n\n**Critical rules — all stem from the same shared-via-ALS instance model**:\n- Every per-request stage (middleware → contributors → handler) gets its OWN `RequestContext` instance, but they all read/write the SAME `AsyncLocalStorage`-backed bag.\n- **`resolve` and `onError` must RETURN the value** — the runner writes it via `ctx.set(key, value)`. Direct property assignment (`ctx.tenant = …`) sticks to one instance only and the handler instance never sees it.\n- `ctx.set('tenant', x)` then `ctx.get('tenant')` works across instances. `ctx.req.headers[...]` works (the underlying node request is shared). Note it is a node `IncomingMessage` on Fastify and a web-backed request on h3, not an `express.Request`.\n- Services with no `ctx` reference: `getRequestValue('tenant')` returns `MetaValue<'tenant'> | undefined` (typed via the augmented `ContextMeta`). For `requestId` use `getRequestStore()`.\n- **No `setRequestValue` — writes flow through `ctx.set` or a contributor's return value.** Avoids \"spooky action at a distance\" where any service can pollute the per-request bag.\n\n**Error matrix**:\n- `optional: true` — `resolve` throws → key left unset; downstream sees `ctx.get(key) === undefined`.\n- `optional: false` (default) + `onError` — return a fallback value to write; return `undefined` to skip; throw to forward to the request error handler.\n- `optional: false` + no `onError` — throw propagates straight to the request error handler.\n\n**Don't use this for**: response short-circuit, stream mutation, or pre-route-matching work — keep `@Middleware()` for those.\n\n**Red flags**:\n- `ctx.get('key')!` — the non-null assertion compiles even when the producing decorator isn't on the route. Use `ctx.require('key')`.\n- `contributors: [LoadX]` at a module / adapter / bootstrap site — those take registrations: `LoadX.registration` or `LoadX.with({ ... }).registration`.\n- A `paramDefaults` value that every call site overrides (`action: 'settings:read'`) — drop it and let the compiler require the field at each site.\n- `defineContextDecorator<'k', Deps, Params>(spec)` positional form for a parameterised contributor — use `.withParams<Params>()(spec)` or `deps` inference is lost.\n- `ctx.tenant = x` instead of returning the value from `resolve` — sticks to one instance only.\n- Plugin / adapter authors using bare keys (`'state'`) instead of namespaced (`'@my-plugin/state'`) — collides with adopter keys.\n- `getRequestValue<string>('traceId')` — generic is the **key** type, not value type."},{slug:`guard-vs-middleware-vs-contributor`,frontmatterName:`kickjs-guard-vs-middleware-vs-contributor`,description:`Use when adding auth checks, request-scoped values, or anything "before the handler" — picks between a guard, a middleware, and a context contributor.`,body:"**KickJS has no guard primitive.** There is no `@Guard`, no `canActivate`, no guard\nclass to implement. A guard IS a middleware — the word only names a convention\nand a directory. If you are porting NestJS habits, this is the first thing to\nunlearn.\n\n| | Guard | Middleware | Context contributor |\n|---|---|---|---|\n| What it is | a middleware, by convention | a middleware | a declarative value producer |\n| Signature | `(ctx, next)` | `(ctx, next)` on `@Middleware()`, `(req, res, next)` in `bootstrap({ middlewares })` | `resolve(ctx, deps)` returning a value |\n| Can end the request | yes | yes | **no** |\n| Runs | in the middleware stage | in the middleware stage | after ALL middleware |\n| Attached by | `@Middleware(fn)` | `@Middleware(fn)` or `bootstrap({ middlewares })` | `@LoadX`, or a registration at module / adapter / bootstrap level |\n| Generator | `kick g guard <name>` | `kick g middleware <name>` | `kick g contributor <name>` |\n| Lands in | `src/guards/<name>.guard.ts` | `src/middleware/<name>.middleware.ts` | `src/contributors/<name>.contributor.ts` |\n\nAdd `-m <module>` to any of those generators to place the file inside a module\ninstead of the app-level directory.\n\n**Choosing**: does the thing ever need to STOP the request?\n- Yes, and it is authorization → guard.\n- Yes, anything else (rate limit, body rewrite, response stream, work before route matching) → middleware.\n- No, it only computes a value the handler or a service reads off `ctx` → contributor. Typed, ordered, boot-validated, and it cannot silently swallow the request.\n\n**Ordering — guards run BEFORE contributors.** Every runtime does the same\nthing: run `entry.middlewares` in order, bail if the response was written,\nthen run the contributor pipeline, then the handler. So:\n\n```ts\n// WRONG — tenant is always undefined here.\nexport async function tenantGuard(ctx: RequestContext, next: () => void) {\n  const tenant = ctx.get('tenant') // contributors have not run yet\n  if (!tenant) return ctx.problem.forbidden()\n  next()\n}\n```\n\nA guard that needs a resolved value must resolve it itself, or the check\nbelongs in the contributor's own `resolve` (throw from there and the request\nerror handler takes over).\n\n**Write responses with `ctx.*`, never `ctx.res`.** `ctx.res` is the ENGINE-NATIVE\nresponse object, so `ctx.res.status(401).json(...)` only works on Express —\n`FastifyReply` has no `.json()` and h3's event has no `.status()`. Use\n`ctx.problem.unauthorized({ detail })` (RFC 9457) or `ctx.json(body, status)`,\nand the helper for anything else you would reach `ctx.res` for:\n`ctx.download(buffer, filename, contentType?)` for a generated file,\n`ctx.html(content)`, `ctx.redirect(url, status?)`, `ctx.sse()` for a stream.\nAll of them work on all four runtimes. Never hand `ctx.redirect` a destination\ntaken from the request unchecked — allow-list it, or accept only a same-site path\n(one leading `/`, not `//`) — or the route is an open redirect.\n\n**Guard shape**:\n\n```ts\nimport type { RequestContext } from '@forinda/kickjs'\n\nexport async function adminGuard(ctx: RequestContext, next: () => void): Promise<void> {\n  // Requires the session() middleware. Type the key once:\n  // declare module '@forinda/kickjs' { interface SessionData { role?: 'admin' | 'member' } }\n  const role = ctx.session?.data.role\n  if (!role) {\n    ctx.problem.unauthorized({ detail: 'Not signed in' })\n    return // do NOT call next()\n  }\n  if (role !== 'admin') {\n    ctx.problem.forbidden({ detail: 'Admin only' })\n    return\n  }\n  next()\n}\n```\n\n```ts\n@Middleware(adminGuard)\n@Get('/admin/stats')\nstats(ctx: RequestContext) { ... }\n```\n\nRole checks that are purely declarative (`@Public()`, `@Roles('admin')`,\n`@Can(...)`) are yours to define — see the BYO Auth recipe in the docs.\nHand-write a guard only for logic those don't express.\n\n**Red flags**:\n- `class AdminGuard implements CanActivate` / `@UseGuards()` — NestJS, not KickJS. Export a `(ctx, next)` function and attach with `@Middleware()`.\n- A guard calling `next()` AND writing a response — pick one; writing then continuing double-sends.\n- A guard reading `ctx.get(...)` for a contributor-produced key — contributors have not run yet.\n- `ctx.res.status(403).json(...)` in a guard — Express-only. Use `ctx.problem.forbidden()`.\n- A \"guard\" that only sets a value and always calls `next()` — that is a contributor wearing a guard's name.\n- Passing a `(ctx, next)` guard to `bootstrap({ middlewares })` — global middleware is connect-style `(req, res, next)`. Mount guards per-route with `@Middleware()`.\n"},{slug:`query-parsing-list-endpoint`,frontmatterName:`kickjs-query-parsing-list-endpoint`,description:`Use when adding a paginated/filterable list route — emit ctx.qs + ctx.paginate with an allow-list.`,body:"**Canonical list endpoint**:\n\n```ts\n@Get('/')\nasync list(ctx: Ctx<KickRoutes.TodoController['list']>) {\n  const parsed = ctx.qs({\n    filterable: ['status', 'priority', 'assigneeId'], // allow-list, MUST be set\n    sortable: ['createdAt', 'updatedAt', 'priority'],\n    searchColumns: ['title', 'description'], // free-text search targets\n  })\n\n  return ctx.paginate(async () => {\n    const { data, total } = await this.service.list(parsed)\n    return { data, total }\n  }, parsed)\n}\n```\n\n**Operator format** (fixed): `?filter=field:op:value` where `op ∈ eq | neq | gt | gte | lt | lte | between | in | contains | starts | ends`. Sort is `?sort=field:asc|desc`. Only the first two colons are delimiters, so timestamps work (`createdAt:gt:2026-01-01T00:00:00Z`).\n\n**Drizzle adopters** — pass a `DrizzleQueryParamsConfig` with column refs:\n\n```ts\nconst TASK_QUERY_CONFIG = {\n  filterable: { status: tasks.status, priority: tasks.priority },\n  sortable: { createdAt: tasks.createdAt },\n  searchColumns: [tasks.title, tasks.description],\n}\nconst parsed = ctx.qs(TASK_QUERY_CONFIG)\n```\n\n**ORM-agnostic builders** — implement `QueryBuilderAdapter<TResult, TConfig>` with `build(parsed, config)`. The Drizzle + Prisma adapters live here.\n\n**Red flags**:\n- Reading `req.query.status` directly — bypasses the allow-list; opens unbounded filtering. Use `ctx.qs({ filterable })`.\n- Omitting `filterable` / `sortable` allow-list — every client-supplied filter is **silently dropped** (security default, but looks like a bug).\n- Hand-building the pagination meta in the controller — inconsistent response shape across endpoints. Always use `ctx.paginate()`.\n- Returning a bare array from a list endpoint when pagination is implied — breaks the `PaginatedResponse<T>` contract.\n- Mixing string `searchable` config with column `searchColumns` (Drizzle) — silently no-ops.\n\n**Nuances**:\n- `limit` is capped at 100 server-side; `q` (search) is truncated to 200 chars. Don't re-validate client-side.\n- Sort direction defaults to `asc` when omitted (`?sort=createdAt` ≡ `?sort=createdAt:asc`)."},{slug:`use-asset-manager`,frontmatterName:`kickjs-use-asset-manager`,description:`Use when code reads template files / JSON fixtures via fs.readFile + path arithmetic — switch to assets.<ns>.<key>() and the kick.config.ts assetMap.`,body:"**Configure** `kick.config.ts`:\n\n```ts\nexport default defineConfig({\n  assetMap: {\n    mails: { src: 'src/templates/mails' },\n    reports: { src: 'src/templates/reports', glob: '**/*.{ejs,html}' },\n  },\n})\n```\n\n**Consume** via the typed Proxy — no `__dirname` arithmetic, dev/prod paths handled:\n\n```ts\nimport { assets } from '@forinda/kickjs'\n\nconst html = await assets.mails.welcome() // typed: tsc errors on bad key\n```\n\n**Class-field decorator** (lazy getter, swappable in tests):\n\n```ts\nclass WelcomeMailService {\n  @Asset('mails/welcome') private welcomeTemplate!: () => Promise<string>\n\n  async send(to: string) {\n    const body = await this.welcomeTemplate()\n  }\n}\n```\n\n**Dynamic dispatch** (CMS templates, codegen) — `resolveAsset(ns, key)` throws `UnknownAssetError` with `{ namespace, key }` fields when the key is missing.\n\n**Test fixtures** — swap via env override + cache clear:\n\n```ts\nbeforeEach(() => {\n  process.env.KICK_ASSETS_ROOT = path.resolve('__fixtures__/assets')\n  clearAssetCache()\n})\nafterEach(() => {\n  delete process.env.KICK_ASSETS_ROOT\n  clearAssetCache()\n})\n```\n\n**Red flags**:\n- Hand-rolled `process.env.NODE_ENV === 'production' ? join(__dirname, '../templates') : join(__dirname, 'templates')` — exactly what the asset manager replaces.\n- `keys: 'strip'` setting in `assetMap.<ns>` when basenames may collide — silent last-walk-wins data loss. Default `'auto'` keeps extensions only for colliding groups.\n- Non-default Vite `outDir` without mirroring in `kick.config.ts` — manifest writes at `dist/.kickjs-assets.json` but the resolver can't find it. Mirror via `build.outDir`.\n- Forgetting to re-run `kick typegen` after adding files — `assets.mails.newTemplate` is a tsc error even though the file ships. `kick dev` does this on-change; one-shot CI builds need `kick build` (or `kick build:assets` for manifest-only).\n- Same-name `welcome.ejs` + `welcome/login.ejs` — directory wins in the typed surface; the `.ejs` file still copies but isn't addressable.\n\n**Nuances**:\n- Resolution pipeline (cached): `KICK_ASSETS_ROOT` env override > built manifest at `build.outDir` / `dist` / `build` / `out` > dev-fallback in-memory walk. Manifest presence = \"running from built dist.\"\n- Dev-mode glob matcher is a lite implementation — `**/*`, `**/*.ext`, `**/*.{a,b}` are guaranteed; exotic globs warn-once and accept everything. Run `kick build:assets` to exercise the real glob engine."},{slug:`cli-commands-cheatsheet`,frontmatterName:`kickjs-cli-commands-cheatsheet`,description:`Use as a quick reference for the most common kick CLI workflows — scaffolding, dev/build/start, generation, inspection.`,body:`**Top commands**:
 - \`kick new <name>\` — start a new project (prompts for template / repo / pm).
 - \`kick dev\` — local dev server with Vite HMR.
 - \`kick build\` — production bundle via Vite.
@@ -847,5 +851,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=e({generateAgentDocs:()=>b});const m=`.agents`,h=new Set([`rest`,`minimal`,`fullstack`]);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){if(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.`);continue}await t(r,i()),E.push(r)}return E}export{b as n,p as t};
-//# sourceMappingURL=agent-docs-z03QAZuD.mjs.map
+`}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-BsXKM5QH.mjs.map

package/dist/agent-docs-BsXKM5QH.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-docs-BsXKM5QH.mjs","names":["__exportAll","writeFileSafe","confirm","loadKickConfig","generateClaude","name","pm","generateAgents","template","buildSkills","moduleEntry","style","generateKickJsSkillFiles","banner","skill","generateGemini","generateCopilot","agent_docs_exports","generateAgentDocs","AGENTS_DIR","VALID_TEMPLATES","detectName","override","pkg","readFileSync","join","outDir","detectPm","detectStyle","detectTemplate","pattern","only","options","wantsAgents","wantsClaude","wantsSkills","wantsGemini","wantsCopilot","targets","written","existsSync","file","render"],"sources":["../src/generators/templates/project-docs.ts","../src/generators/agent-docs.ts"],"sourcesContent":["import type { ModuleStyle } from './types'\ntype ProjectTemplate = 'rest' | 'minimal' | 'fullstack' | 'inertia'\n\n/**\n * Generate CLAUDE.md.\n *\n * v4 update: this file is intentionally thin. AGENTS.md is the\n * canonical, multi-agent project reference (Claude / Copilot /\n * Codex / Gemini / etc.) — duplicating it here meant two files\n * drifting out of sync after every framework change. The generated\n * CLAUDE.md now redirects there + adds Claude-specific affordances\n * only.\n */\nexport function generateClaude(name: string, _template: ProjectTemplate, pm: string): string {\n  return `# CLAUDE.md — ${name}\n\n**Read \\`./.agents/AGENTS.md\\` first.** It is the canonical, multi-agent\nreference for this project (Claude, Copilot, Codex, Gemini, etc.) —\nproject conventions, structure, decorator patterns, env wiring, CLI\ngenerators, every gotcha.\n\n**Then browse \\`./.agents/skills/\\`.** Each subdirectory is a single\ntask-oriented skill (\\`add-module/\\`, \\`write-controller-test/\\`,\n\\`bootstrap-export/\\`, \\`deny-list/\\`, …) containing a \\`SKILL.md\\`\nwith YAML frontmatter (\\`name\\`, \\`description\\`) and the recipe body.\nThe structure follows the Claude Code skills convention — agents that\nauto-load skills from \\`.agents/skills/\\` will pick each up by its\nfrontmatter. Use this directory as the playbook when executing common\nKickJS workflows.\n\nThis file is a thin Claude-specific layer on top of those two; when\nthey disagree on anything substantive, treat \\`.agents/AGENTS.md\\` as\nauthoritative and flag the discrepancy.\n\n## Why \\`.agents/\\` + this thin pointer\n\n\\`.agents/AGENTS.md\\` is what every agent reads (Codex, Cursor, Gemini,\nCopilot, Aider, …) — one canonical source so the prose doesn't drift\nacross copies. \\`CLAUDE.md\\` is what Claude Code automatically loads as\nproject context on each conversation, so it stays at the project root.\nKeeping CLAUDE.md slim and pointing at \\`.agents/\\` avoids two\nout-of-sync copies of the same content. Per-agent files\n(\\`.agents/GEMINI.md\\`, \\`.agents/COPILOT.md\\`) live alongside\n\\`AGENTS.md\\` for tool-specific notes that don't belong in the shared\nprose.\n\n## Claude-specific notes\n\n- **Slash commands** — \\`/help\\` for Claude Code commands; \\`/init\\`\n  to refresh project memory if AGENTS.md changes substantially.\n- **Feedback** — file issues at <https://github.com/anthropics/claude-code/issues>.\n- **Persistent memory** — Claude maintains user/feedback/project/\n  reference memories under \\`.claude/memory/\\`. If you ask for\n  something that contradicts a remembered preference, Claude flags\n  it before acting; corrections update memory automatically.\n- **Long-running tasks** — \\`/loop\\` and \\`/schedule\\` for recurring\n  or background work. Useful for \"wait for the deploy then open a\n  cleanup PR\" or \"every Monday triage the issue board\" patterns.\n\n## Quick reference (full version in .agents/AGENTS.md)\n\n\\`\\`\\`bash\n${pm} install            # Install dependencies\nkick dev                 # Dev server with HMR + typegen\nkick build && kick start # Production\n${pm} run test           # Vitest\nkick typecheck           # tsc/tsgo, whichever the project has\nkick format              # oxfmt\n\\`\\`\\`\n\n## v4 framework reminders\n\nWhen generating or modifying code in this project, stay aligned with the v4 conventions documented in \\`.agents/AGENTS.md\\`:\n\n- **Adapters**: \\`defineAdapter()\\` factory — never \\`class implements AppAdapter\\`.\n- **Plugins**: \\`definePlugin()\\` factory — never plain function returning \\`KickPlugin\\`.\n- **DI tokens**: \\`<scope>/<PascalKey>[/<suffix>]\\` — scope is lowercase, the key segment is **PascalCase** (e.g. \\`'app/Users/repository'\\`, \\`'mycorp/Cache/redis'\\`). First-party uses the reserved \\`'kick/'\\` prefix; this project owns its own scope.\n- **Decorators**: \\`@Controller()\\` (no path arg — mount prefix comes from \\`routes().path\\`).\n- **HTTP runtime**: this app may run on Express, Fastify, or h3 — check \\`kick.config.ts\\` \\`runtime\\` (or \\`bootstrap({ runtime })\\`) before writing engine-specific code. Prefer engine-neutral \\`ctx\\` APIs (\\`ctx.json\\`/\\`ctx.body\\`/\\`ctx.params\\`/\\`ctx.sse\\`); don't assume \\`ctx.req\\` is an Express request. Uploads (\\`@FileUpload\\` → \\`ctx.file\\`/\\`ctx.files\\`) work on all three (\\`kick add upload\\` installs the driver). Full rules in \\`.agents/AGENTS.md\\` → \"HTTP runtime\".\n- **Module entry file** MUST be named \\`<name>.module.ts\\` and live under \\`src/modules/<name>/\\`. The Vite plugin auto-discovers \\`*.module.[tj]sx?\\` for graceful HMR — a misnamed \\`projects.ts\\` silently degrades every save into a full restart.\n- **Env**: schema lives in \\`src/config/index.ts\\`; \\`import './config'\\` MUST be the first import in \\`src/index.ts\\` (side-effect registers the schema before any \\`@Value\\` resolves).\n- **Assets**: drop new template files into \\`src/templates/<namespace>/\\`; the dev watcher auto-rebuilds the \\`KickAssets\\` augmentation + \\`assets.x.y()\\` re-walks on next call. No restart, no manual build.\n- **Context Contributors** (\\`defineContextDecorator\\`) over \\`@Middleware()\\` for ctx-population work.\n- **Repos under tests**: \\`Container.create()\\` for isolation — never \\`new Container()\\` or \\`getInstance().reset()\\`.\n- **Bootstrap export**: \\`src/index.ts\\` must end with \\`export const app = await bootstrap({ ... })\\`. The Vite plugin and \\`createTestApp\\` import the named \\`app\\`; without the export, HMR silently degrades to full restarts.\n- **Thin entry file**: aggregate \\`modules\\`, \\`middlewares\\`, \\`plugins\\`, \\`adapters\\` in their own folders (\\`src/modules/index.ts\\`, \\`src/middleware/index.ts\\`, …) and pass them by name to \\`bootstrap()\\` — never inline the lists in \\`src/index.ts\\`.\n- **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.\n\nFor everything else (controllers, services, modules, RequestContext API, generators, CLI commands, package additions, env wiring, troubleshooting) → \\`.agents/AGENTS.md\\`.\n`\n}\n\n/** Generate AGENTS.md with AI agent guide */\nexport function generateAgents(name: string, template: ProjectTemplate, pm: string): string {\n  return `# AGENTS.md — AI Agent Guide for ${name}\n\nThis guide is the **canonical, multi-agent reference** for this KickJS\napplication — Claude, Copilot, Codex, Gemini, etc. all read it first.\nPer-agent files (\\`CLAUDE.md\\`, \\`GEMINI.md\\`, etc.) are thin layers that\nadd tool-specific affordances on top.\n\n## Before You Start\n\n1. Run \\`${pm} install\\` to install dependencies\n2. Run \\`kick dev\\` to verify the app starts${\n    template === 'fullstack'\n      ? `\n\n## Fullstack workspace layout\n\nThis is a WORKSPACE root — the KickJS API lives in \\`server/\\`, the typed web\napp in \\`web/\\`. Run both with \\`${pm === 'pnpm' ? 'pnpm dev' : `${pm} run dev:server + ${pm} run dev:web`}\\`.\n\nThe type loop (do not break it):\n1. \\`server/\\` handlers RETURN their payloads → \\`kick typegen\\` emits\n   \\`server/.kickjs/types/kick__client.d.ts\\`: the ambient \\`KickClientApi\\`\n   namespace, every response resolved to a plain shape. \\`kick dev\\` writes it\n   at startup but NOT on save — run \\`kick typegen\\` in \\`server/\\` after changing a route or a\n   response (the root \\`build\\` script runs it too).\n2. \\`web/tsconfig.json\\` lists that file in \\`compilerOptions.types\\`.\n3. \\`web/src/api.ts\\` = \\`createClient<KickClientApi.Api>({ baseUrl })\\`\n   — every call site is typed from the server's handlers. \\`baseUrl\\` is the\n   relative \\`/api/v1\\` (Vite proxies it in dev) unless \\`VITE_API_URL\\` points at\n   an API on another origin.\n\nRules: kick commands (\\`kick g\\`, \\`kick typegen\\`, \\`kick dev\\`) run in\n\\`server/\\`; never import server runtime code into \\`web/\\` (the d.ts bridge is\ntype-only); prefer return-value handlers so responses stay inferable.`\n      : ''\n  }\n3. Read the [KickJS documentation](https://kickjs.app/) for framework details\n\n## HTTP runtime — DON'T assume Express-only\n\nKickJS is **engine-pluggable**. It runs on **Express (default), Fastify, or h3** —\nchosen with one line: \\`bootstrap({ runtime: fastifyRuntime() })\\`. Before writing\nany engine-specific code, **check which engine this project uses**:\n\n- \\`kick.config.ts\\` → the \\`runtime\\` field (\\`'express'\\` | \\`'fastify'\\` | \\`'h3'\\`), and/or\n- \\`src/index.ts\\` → the \\`runtime:\\` passed to \\`bootstrap()\\`, and/or\n- \\`package.json\\` → \\`fastify\\` / \\`h3\\` in deps.\n\nRules that keep generated code correct on **every** engine:\n\n- **Prefer return-value handlers.** \\`return payload\\` sends 200 json on every\n  engine and lets \\`kick typegen\\` infer the response type into\n  \\`KickRoutes.Api\\` (consumed by the \\`@forinda/kickjs-client\\` typed client);\n  \\`reply(status, body)\\` for non-200, \\`reply.noContent()\\` for 204. A declared\n  \\`{ response: schema }\\` on the route feeds BOTH the OpenAPI success response\n  and the typegen response type. \\`ctx.json(...)\\` stays fully supported but\n  infers \\`unknown\\`.\n- **Lifecycle hooks:** \\`@PostConstruct()\\` after instantiation; \\`@PreDestroy()\\`\n  when a REQUEST-scoped service's request closes (release transactions/handles).\n- **Write to \\`ctx\\`, not the raw request/response.** \\`ctx.json()\\`, \\`ctx.body\\`,\n  \\`ctx.params\\`, \\`ctx.query\\`, \\`ctx.set/get\\`, \\`ctx.sse()\\` are engine-neutral and\n  work identically everywhere. \\`ctx.req\\` / \\`ctx.res\\` are the engine-native\n  objects — their **type follows the active runtime** (Express by default; the\n  \\`kick/runtime\\` typegen retypes them to Fastify / h3 when \\`runtime\\` is set).\n  Don't assume \\`ctx.req\\` is an \\`express.Request\\` in portable code.\n- **Global middleware** in \\`bootstrap({ middlewares })\\` is connect-style\n  \\`(req, res, next)\\` — it runs on all engines (Fastify via \\`@fastify/middie\\`,\n  h3 via \\`fromNodeHandler\\`). But on Fastify / h3 the engine parses the body\n  natively, so the default \\`express.json()\\` is **auto-skipped** (\\`nativeBodyParsing\\`).\n  Don't add \\`express.json()\\` manually on those engines.\n- **File uploads** work on all three: \\`@FileUpload({ mode, fieldName, ... })\\` →\n  \\`ctx.file\\` / \\`ctx.files\\` (same Multer-shaped object everywhere). Backends:\n  Express \\`multer\\`, Fastify \\`@fastify/multipart\\`, h3 native. Run\n  \\`kick add upload\\` to install the runtime-correct driver. The \\`@FileUpload\\`\n  decorator is **memory-only** (portable); disk / custom-storage (\\`storage\\` /\n  \\`dest\\`) is Express-only via the \\`upload.single/array()\\` middleware.\n- **Engine subpaths**: \\`import { fastifyRuntime } from '@forinda/kickjs/fastify'\\`\n  or \\`h3Runtime\\` from \\`'@forinda/kickjs/h3'\\`. Express is the zero-config default\n  (no import, nothing to install).\n- **Not supported on Fastify / h3**: \\`ctx.render()\\` (no view engine). Calling it\n  throws a clear error rather than failing silently.\n- Run \\`kick doctor\\` to verify the runtime's engine peers + upload driver are installed.\n\n## v4 Conventions (don't skip)\n\nKickJS v4 made a handful of structural changes from v3. Internalise these\nbefore generating or modifying code — they are the source of most agent\nmistakes:\n\n- **Adapters** — \\`defineAdapter()\\` factory. Never write \\`class Foo implements AppAdapter\\`.\n\n  \\`\\`\\`ts\n  export const MyAdapter = defineAdapter<MyOptions>({\n    name: 'MyAdapter',\n    defaults: { ... },\n    build: (config) => ({\n      beforeMount({ app }) { /* ... */ },\n      afterStart({ server }) { /* ... */ },\n    }),\n  })\n  \\`\\`\\`\n\n- **Plugins** — \\`definePlugin()\\` factory. Same shape, never plain function returning \\`KickPlugin\\`.\n\n- **DI tokens** — \\`<scope>/<PascalKey>[/<suffix>]\\`. Scope is lowercase,\n  the key segment is **PascalCase** (the regex enforces both):\n\n  \\`\\`\\`ts\n  const USERS_REPO = createToken<UsersRepo>('app/Users/repository')\n  const DB         = createToken<Database>('app/Db/connection')\n  \\`\\`\\`\n\n  The \\`kick/\\` prefix is reserved for first-party packages; this project\n  owns its own scope (\\`app/\\`, your domain name, etc.).\n\n- **\\`@Controller()\\`** takes **no arguments**. Set the route prefix with the\n  module's \\`routes().path\\`.\n\n- **Env** — the schema lives in \\`src/config/index.ts\\`. \\`src/index.ts\\` imports\n  it once, as its **first** import (\\`import './config'\\`, before \\`bootstrap()\\`);\n  tests that read config import it too (\\`import '@/config'\\`). Nothing else\n  imports from \\`src/config\\`: read values with \\`getEnv('KEY')\\`, an injected\n  \\`ConfigService\\` (\\`config.get('KEY')\\`), or \\`@Value('KEY')\\` typed as\n  \\`Env<'KEY'>\\` — never \\`process.env\\`. Add a key to the schema before reading it.\n\n- **Module entry files MUST be named \\`<name>.module.ts\\`** — see the Vite\n  HMR contract at the top of \"Module Pattern\" below. The CLI enforces this;\n  hand-rolled files must too.\n\n- **Assets** — drop new template files into \\`src/templates/<namespace>/\\`\n  (or wherever \\`kick.config.ts\\` points). The dev watcher auto-rebuilds the\n  \\`KickAssets\\` augmentation; \\`assets.x.y()\\` re-walks on next call. No restart,\n  no manual build step.\n\n- **Context over \\`@Middleware()\\`** — when a middleware's only job is to\n  populate \\`ctx.set('key', value)\\`, use \\`defineHttpContextDecorator()\\`\n  (HTTP) or \\`defineContextDecorator()\\` (transport-agnostic) instead.\n  Typed via \\`ContextMeta\\`, ordered via \\`dependsOn\\`, validated at boot.\n  Reserve \\`@Middleware()\\` for response short-circuit / stream mutation /\n  pre-route-matching work.\n\n  Two ground rules around the data flow — both stem from the fact that\n  every per-request stage gets its OWN \\`RequestContext\\` instance, all\n  reading/writing the SAME \\`AsyncLocalStorage\\`-backed Map:\n  - **\\`resolve\\` and \\`onError\\` must RETURN the value.** The runner\n    writes it via \\`ctx.set(reg.key, value)\\` on your behalf. Direct\n    property assignment (\\`ctx.tenant = …\\`) sticks to the contributor\n    instance only — the handler instance never sees it.\n  - **Read across instances via \\`ctx.set\\` / \\`ctx.get\\`** (or\n    \\`getRequestValue(key)\\` from a service that has no \\`ctx\\` reference\n    — typed via \\`MetaValue<K>\\`). \\`ctx.req\\` works because the underlying\n    Express request is shared; bespoke property assignments don't.\n\n- **Test isolation** — default to \\`Container.create()\\` for fresh DI state.\n  Never \\`new Container()\\` and never \\`getInstance().reset()\\` — both leak\n  registrations between tests.\n\n  \\`\\`\\`ts\n  const container = Container.create()\n  // ... register test-scoped providers, run, discard\n  \\`\\`\\`\n\n- **Bootstrap export** — \\`src/index.ts\\` MUST end with\n  \\`export const app = await bootstrap({ ... })\\`. The Vite plugin imports\n  the named \\`app\\` symbol to drive HMR module swaps; testing helpers\n  (\\`createTestApp\\`) and the OpenAPI introspector also rely on it. Drop\n  the \\`export\\` and \\`kick dev\\` will silently fall back to a full restart\n  on every save while \\`createTestApp\\` complains about a missing handle.\n\n- **Keep \\`src/index.ts\\` thin** — collect plugins, modules, middleware, and\n  adapters in dedicated folders and re-export aggregated arrays. Do **not**\n  inline registration in the entry file:\n\n  \\`\\`\\`ts\n  // src/modules/index.ts — fluent chain (default for \\`modules.style: 'define'\\`)\n  export const modules = defineModules().mount(HelloModule()).mount(UsersModule())\n  // OR with \\`modules.style: 'class'\\`:\n  //   export const modules: AppModuleEntry[] = [HelloModule, UsersModule]\n\n  // src/middleware/index.ts\n  export const middleware = [helmet(), cors(), requestId(), ...]\n\n  // src/plugins/index.ts\n  export const plugins = [MetricsPlugin(), AuditPlugin()]\n\n  // src/adapters/index.ts\n  export const adapters = [SwaggerAdapter({ ... }), DevToolsAdapter()]\n  \\`\\`\\`\n\n  \\`\\`\\`ts\n  // src/index.ts — stays small; one import per category\n  import 'reflect-metadata'\n  import './config'\n  import { bootstrap } from '@forinda/kickjs'\n  import { modules } from './modules'\n  import { middleware } from './middleware'\n  import { plugins } from './plugins'\n  import { adapters } from './adapters'\n\n  export const app = await bootstrap({ modules, middlewares, plugins, adapters })\n  \\`\\`\\`\n\n  This keeps the entry file diff-friendly, scales to dozens of modules\n  without git churn, and lets each domain own its own registration list.\n  The generators (\\`kick g module\\`, \\`kick g middleware\\`, \\`kick g plugin\\`,\n  \\`kick g adapter\\`) follow this layout — manual additions should too.\n\nEverything else (controllers, services, modules, RequestContext API, generators,\npackage additions, env access patterns, troubleshooting) is detailed below.\n\n## Where to Find Things\n\n### Application Structure\n\n| What | Where |\n|------|-------|\n| Entry point | \\`src/index.ts\\` |\n| Module registry | \\`src/modules/index.ts\\` |\n| Feature modules | \\`src/modules/<module-name>/\\` |\n| **Module entry file** | \\`src/modules/<name>/<name>.module.ts\\` (filename suffix is required — see Vite HMR contract below) |\n| Env values | \\`.env\\` |\n| Env schema (Zod) | \\`src/config/index.ts\\` |\n| TypeScript config | \\`tsconfig.json\\` |\n| Vite config (HMR) | \\`vite.config.ts\\` |\n| Vitest config | \\`vitest.config.ts\\` |\n| Formatter config | \\`.oxfmtrc.json\\` (oxfmt) |\n| CLI config | \\`kick.config.ts\\` |\n\n### Module Pattern (${template.toUpperCase()})\n\n> **Vite HMR auto-discovery contract:** module files **must** be named \\`<name>.module.ts\\` (or \\`.tsx\\`/\\`.js\\`/\\`.jsx\\`) and live under \\`src/modules/\\`. The Vite plugin scans for \\`*.module.[tj]sx?\\` to drive graceful HMR rebuilds; renaming a file to \\`projects.ts\\` (no \\`.module\\`) silently breaks HMR — saves trigger a full restart instead of a swap. The CLI generator (\\`kick g module <name>\\`) follows the convention; manual files must too.\n\nEach module in \\`src/modules/<name>/\\` typically contains:\n\n${\n  template === 'rest'\n    ? `\\`\\`\\`\n<name>/\n├── <name>.controller.ts     # HTTP routes (@Controller)\n├── <name>.service.ts        # Business logic (@Service)\n├── <name>.repository.ts     # Data access — factory + contract + token\n├── dtos/                    # Request/response schemas (Zod)\n└── <name>.module.ts         # Module definition (defineModule factory)\n\\`\\`\\`\n`\n    : `\\`\\`\\`\nsrc/\n├── index.ts                 # Add routes here\n└── ...                      # Custom structure\n\\`\\`\\`\n`\n}\n\n## Checklist: Adding a Feature\n\nFollow the **\\`kickjs-add-module\\`** skill — it has the ordered steps, the\ncanonical \\`defineModule\\` shape, and the \\`import.meta.glob\\` requirement that\nsilently breaks DI when omitted.\n\n## Common Tasks\n\nEach of these has a skill with the steps and the traps:\n\n| Task | Skill |\n| --- | --- |\n| Add a feature module | \\`kickjs-add-module\\` |\n| Add an adapter | \\`kickjs-add-adapter\\` |\n| Add a plugin | \\`kickjs-add-plugin\\` |\n| Add a context contributor | \\`kickjs-context-contributor\\` |\n| Write a controller test | \\`kickjs-write-controller-test\\` |\n| List endpoint with filters / pagination | \\`kickjs-query-parsing-list-endpoint\\` |\n| Serve bundled assets | \\`kickjs-use-asset-manager\\` |\n| Flag a route (public, exempt, unmetered) | \\`kickjs-route-flags\\` |\n| Add a kick CLI command or generator | \\`kickjs-cli-plugin\\` |\n| Deploy to Netlify / Vercel / Cloudflare | \\`kickjs-deploy\\` |\n| Anything else | \\`kickjs-docs-lookup\\` |\n\n## Testing Guidelines\n\nSee the **\\`kickjs-write-controller-test\\`** skill for the canonical test — it\ncarries the call shape, the DI reset, and the env side-effect import, each of\nwhich has its own failure mode.\n\nRun with \\`${pm} run test\\` (\\`test:watch\\` for watch mode).\n\n## Environment Variables\n\nThe schema lives in \\`src/config/index.ts\\` and registers itself with kickjs **at\nmodule load**; \\`src/index.ts\\` imports it (\\`import './config'\\`) before\n\\`bootstrap()\\` so the cache is populated before DI resolves anything. Add a key\nto the schema, put its value in \\`.env\\`, and it is typed everywhere.\n\nRead it with \\`@Value('KEY')\\` for construction-time values, or inject\n\\`ConfigService\\` for dynamic access.\n\nWhen a key reads as \\`undefined\\`, use the **\\`kickjs-env-wiring-check\\`** skill or\nrun \\`kick explain \"ConfigService.get('KEY') returned undefined\"\\`. The cause\ndiffers between app code and tests and the two look identical, which is what\nmakes it slow to spot.\n\n## Standalone Utilities (No DI Required)\n\nThese work anywhere — scripts, plain files, outside \\`@Service\\`/\\`@Controller\\`:\n\n| Utility | Import | Example |\n|---------|--------|---------|\n| \\`Logger.for(name)\\` | \\`@forinda/kickjs\\` | \\`const log = Logger.for('MyScript')\\` |\n| \\`createLogger(name)\\` | \\`@forinda/kickjs\\` | \\`const log = createLogger('Worker')\\` |\n| \\`createToken<T>(name)\\` | \\`@forinda/kickjs\\` | \\`const TOKEN = createToken<string>('app/Db/url')\\` |\n| \\`ref(value)\\` | \\`@forinda/kickjs\\` | \\`const count = ref(0)\\` |\n| \\`computed(fn)\\` | \\`@forinda/kickjs\\` | \\`const doubled = computed(() => count.value * 2)\\` |\n| \\`watch(source, cb)\\` | \\`@forinda/kickjs\\` | \\`watch(() => count.value, (v) => log(v))\\` |\n| \\`reactive(obj)\\` | \\`@forinda/kickjs\\` | \\`const state = reactive({ count: 0 })\\` |\n| \\`HttpException\\` | \\`@forinda/kickjs\\` | \\`throw new HttpException(404, 'Not found')\\` |\n| \\`HttpStatus\\` | \\`@forinda/kickjs\\` | \\`HttpStatus.NOT_FOUND // 404\\` |\n\n## Key Decorators\n\n### HTTP Routes\n| Decorator | Purpose |\n|-----------|---------|\n| \\`@Controller()\\` | Define route prefix |\n| \\`@Get('/'), @Post('/')\\` | HTTP method handlers |\n| \\`@Middleware(fn)\\` | Attach middleware |\n| \\`@Public()\\` | Skip auth (requires auth adapter) |\n| \\`@Roles('admin')\\` | Role-based access |\n\n### Dependency Injection\n| Decorator | Purpose |\n|-----------|---------|\n| \\`defineModule({...})\\` | Define feature module (factory; preferred — paired with \\`defineModules()\\` registry) |\n| \\`defineModules()\\` | Build the modules registry as a chainable list (\\`.mount(X())\\`) |\n| \\`AppModule\\` interface | Legacy module shape — \\`class X implements AppModule\\` (toggle via \\`modules.style: 'class'\\`) |\n| \\`@Service()\\` | Register singleton service |\n| \\`@Repository()\\` | Register repository |\n| \\`@Autowired()\\` | Property injection |\n| \\`@Inject('token')\\` | Token-based injection |\n| \\`@Value('VAR')\\` | Inject env variable |\n\n### Context Decorators\n\nTyped, ordered way to populate \\`ctx.set/get\\` keys before the handler runs.\nUse this **instead of \\`@Middleware()\\`** when the middleware's only output\nis a value other code reads off \\`ctx\\`.\n\n**Authoring** — pick the right factory:\n\n| Factory | When |\n|---------|------|\n| \\`defineHttpContextDecorator(spec)\\` | HTTP only (the common case). \\`Ctx\\` is \\`RequestContext\\`, so \\`ctx.req\\` / \\`ctx.params\\` / \\`ctx.query\\` are typed. |\n| \\`defineContextDecorator(spec)\\` | Transport-agnostic (HTTP + WS + queue + cron). \\`Ctx\\` is \\`ExecutionContext\\` — only \\`get\\` / \\`require\\` / \\`set\\` / \\`requestId\\`. |\n| \\`<either>.withParams<P>()(spec)\\` | The contributor takes per-call params. **Always use the curried form for params** — the positional form forces you to spell \\`K\\` and \\`D\\` and loses \\`deps\\` inference. |\n\nSpec fields: \\`{ key, deps, dependsOn, optional, paramDefaults, requiredParams, onError, resolve }\\`.\n\n**Call sites — all five, precedence high → low:**\n\n| # | Site | Form |\n|---|------|------|\n| 1 | Method | \\`@LoadX\\` / \\`@LoadX({ ... })\\` above a controller method |\n| 2 | Class | \\`@LoadX\\` / \\`@LoadX({ ... })\\` above the controller class |\n| 3 | Module | \\`defineModule({ build: () => ({ contributors: () => [LoadX.registration] }) })\\` — or \\`AppModule.contributors?()\\` in class form |\n| 4 | Adapter | \\`AppAdapter.contributors?(): ContributorRegistration[]\\` |\n| 5 | Global | \\`bootstrap({ contributors: [LoadX.registration] })\\` |\n\nSites 3–5 take **registrations**, not decorators:\n\n- \\`LoadX.registration\\` — uses \\`paramDefaults\\` as-is.\n- \\`LoadX.with({ ...params }).registration\\` — call-site params merged over \\`paramDefaults\\`.\n\nDuplicate keys are resolved by precedence; the lower-precedence one is\ndropped silently, which is how a method-level decorator overrides an\nadapter-shipped default.\n\n**Params:** a **required** field of \\`P\\` with no \\`paramDefaults\\` entry must be\nsupplied at every call site — \\`@LoadX\\` bare, \\`@LoadX()\\`, and \\`.registration\\`\nare compile errors for such a decorator. Never invent a placeholder default\njust to make the type check; add \\`requiredParams: ['field']\\` for runtime\nenforcement at JS call sites.\n\n**Reading values:** \\`ctx.require('key')\\` for values a contributor guarantees\n(throws \\`MissingContextValueError\\`, returns a non-optional type);\n\\`ctx.get('key')\\` for \\`optional: true\\` contributors and ad-hoc keys (returns\n\\`| undefined\\`). Never \\`ctx.get('key')!\\` — it compiles even when the producing\ndecorator isn't applied to the route.\n\n| Concept | Where it lives |\n|---------|----------------|\n| Type augmentation (value types) | \\`declare module '@forinda/kickjs' { interface ContextMeta { ... } }\\` |\n| Type augmentation (key-only) | \\`declare module '@forinda/kickjs' { interface ContextKeys { ... } }\\` — valid in \\`dependsOn\\`, value stays \\`unknown\\` |\n\nCycles and missing \\`dependsOn\\` keys throw at \\`app.setup()\\` (boot fails\nfast). The \\`onError\\` hook is async-permitted.\n\nFull guide: <https://kickjs.app/guide/context-decorators>.\n\n## Common Pitfalls\n\nSee the **\\`kickjs-deny-list\\`** skill — the maintained list of things that\ncompile, run, and are still wrong.\n\nFor a specific failure, \\`kick explain \"<error message>\"\\` beats reading either:\nit matches the message against known causes and prints the fix.\n\n## CLI Commands Reference\n\nSee the **\\`kickjs-cli-commands-cheatsheet\\`** skill for the full table, the\nshell-safe field syntax, and the non-obvious flags. \\`kick --help\\` and\n\\`kick <cmd> --help\\` are authoritative for the installed version.\n\n## Learn More\n\nUse the **\\`kickjs-docs-lookup\\`** skill — it maps questions to the right guide\npage and lists the local tools (\\`kick explain\\`, \\`kick doctor\\`, \\`kick inspect\\`,\n\\`.kickjs/types/\\`) that usually answer faster than a search.\n\nStart at <https://kickjs.app/>.\n\n`\n}\n\n/**\n * One emitted skill — slug becomes the directory name under\n * `.agents/skills/<slug>/SKILL.md`. `frontmatterName` is the value\n * agents use to look the skill up at activation time and follows the\n * `kickjs-<slug>` convention to keep the skill registry namespaced.\n */\nexport interface KickJsSkillFile {\n  /** kebab-case directory name (`add-module`, `write-controller-test`). */\n  slug: string\n  /** Full SKILL.md content with YAML frontmatter + body. */\n  content: string\n}\n\n/**\n * Render every KickJS task-skill as its own `SKILL.md` file, ready to\n * write under `.agents/skills/<slug>/SKILL.md`. Each file follows the\n * standard Claude Code skill format:\n *\n * ```\n * ---\n * name: kickjs-<slug>\n * description: <when to use this skill>\n * ---\n *\n * <body>\n * ```\n *\n * Agents that auto-discover skills from `.agents/skills/` (Claude\n * Code, Copilot CLI plugins, Gemini's activate_skill) pick each up by\n * its frontmatter without us shipping an index file. The legacy\n * single-file format (`kickjs-skills.md`) is gone — adopters with\n * existing root-level copies keep them untouched until they run\n * `kick g agents -f --only skills`, which emits the new layout\n * alongside without deleting the old file.\n */\ninterface KickJsSkill {\n  slug: string\n  frontmatterName: string\n  description: string\n  body: string\n}\n\n/**\n * Single source of truth for the agent skills.\n *\n * Rendered twice — one `SKILL.md` per entry, and the aggregate\n * `kickjs-skills.md`. The aggregate used to restate all of this by hand and had\n * drifted badly: 9 skills against 13, with an env recipe still naming a\n * superseded API. Add a skill here and both outputs pick it up.\n */\nfunction buildSkills(pm: string, style: ModuleStyle = 'define'): KickJsSkill[] {\n  // A class module is passed bare; a define module is invoked. Emitting the\n  // wrong one calls a class without `new`, or hands the framework a factory.\n  const moduleEntry = style === 'class' ? 'UserModule' : 'UserModule()'\n  const skills: Array<{\n    slug: string\n    frontmatterName: string\n    description: string\n    body: string\n  }> = [\n    {\n      slug: 'add-module',\n      frontmatterName: 'kickjs-add-module',\n      description:\n        'Use when the user asks to add a new feature module (controller + service + repo + DTOs).',\n      body: `**Trigger phrases**: \"add a users module\", \"scaffold tasks\", \"new feature for X\".\n\n**Steps**:\n1. Run \\`kick g module <name>\\` (use plural form if the project pluralizes — check \\`kick.config.ts\\`).\n2. Verify the new folder under \\`src/modules/<name>/\\` contains \\`<name>.module.ts\\` (filename suffix is mandatory for Vite HMR).\n3. Confirm the module appears in \\`src/modules/index.ts\\` exports — generator does this automatically; verify if you bypassed it.\n4. Open \\`<name>.dto.ts\\` and tighten the Zod schemas to real fields (the generator emits placeholders).\n5. Run \\`kick typecheck\\` and \\`${pm} run test\\` before claiming done.\n\n**Canonical module shape** — \\`defineModule\\` factory, never \\`class implements AppModule\\`:\n\n\\`\\`\\`ts\nexport const TodosModule = defineModule({\n  name: 'TodosModule',\n  build: () => ({\n    register(container) {\n      container.registerFactory(TODO_REPO, () => createTodoRepository())\n    },\n    routes() {\n      return { path: '/todos', controller: TodosController }\n    },\n  }),\n})\n\\`\\`\\`\n\nThe module file MUST include \\`import.meta.glob([...], { eager: true })\\` for every \\`@Controller\\` / \\`@Service\\` / \\`@Repository\\` / \\`@Component\\` class — without it, decorators never fire and DI silently resolves to \\`undefined\\` (or routes vanish). Use **recursive** patterns (\\`./**/*.controller.ts\\`) so the glob keeps working when you nest files into sub-folders (\\`controllers/\\`, \\`presentation/\\`, …). If you reorganise and a class stops loading, \\`kick typegen\\` flags it as orphaned and \\`kick typegen --fix\\` patches the glob for you.\n\n**Multiple route sets / versioning** — \\`routes()\\` may return an array with per-entry \\`version\\` override:\n\n\\`\\`\\`ts\nroutes() {\n  return [\n    { path: '/todos', controller: TodosController },               // /api/v1/todos\n    { path: '/todos', version: 2, controller: TodosV2Controller }, // /api/v2/todos\n  ]\n}\n\\`\\`\\`\n\n**Conditional / per-tenant mounting** — use \\`bootstrap({ setup(registry) { registry.mount(...) } })\\`, not the static \\`modules\\` array.\n\n**Composition** — \\`defineModules().mount(TodosModule()).mount(UsersModule())\\` (fluent) or \\`AppModuleEntry[]\\` (array form).\n\n**Red flags** (stop and ask):\n- File created as \\`<name>.ts\\` instead of \\`<name>.module.ts\\` — Vite plugin's \\`*.module.[tj]sx?\\` glob doesn't pick it up; every save becomes a full restart.\n- \\`@Controller('/path')\\` with a path argument — \\`@Controller()\\` takes no arguments; the prefix goes in the module's \\`routes().path\\`.\n- \\`TodosModule\\` instead of \\`TodosModule()\\` for a module that takes config — refused, since the bare name would silently select the defaults. A module with no config accepts either, but prefer the invoked form for consistency.\n- \\`routes()\\` returning \\`router: …\\` when a \\`controller:\\` would do — controller form is required for OpenAPI/Swagger introspection.\n- Module not registered in \\`src/modules/index.ts\\`.`,\n    },\n    {\n      slug: 'add-adapter',\n      frontmatterName: 'kickjs-add-adapter',\n      description:\n        'Use when wiring a single-concern lifecycle integration (Swagger, DevTools, Sentry, Redis client).',\n      body: `**Steps**:\n1. \\`kick g adapter <name>\\` to scaffold the boilerplate, OR install via \\`kick add <package>\\` for first-party adapters.\n2. The generated file uses \\`defineAdapter()\\` — never \\`class implements AppAdapter\\`.\n3. Add the adapter instance (note the parens) to \\`src/adapters/index.ts\\` — don't inline in \\`src/index.ts\\`.\n4. Pick the right hook and middleware phase deliberately.\n5. Verify with \\`kick dev\\` that the adapter's lifecycle logs fire.\n\n**Canonical shape** — factory closure owns instance state:\n\n\\`\\`\\`ts\nexport const RedisAdapter = defineAdapter<RedisConfig>({\n  name: 'RedisAdapter',\n  defaults: { url: 'redis://localhost' },\n  build: (config) => {\n    const client = createClient(config.url)\n    return {\n      beforeStart: ({ container }) => {\n        container.registerInstance(REDIS_CLIENT, client)\n      },\n      afterStart: () => client.connect(),\n      shutdown: () => client.quit(),\n    }\n  },\n})\n\n// In src/adapters/index.ts:\nexport const adapters = [RedisAdapter({ url: env.REDIS_URL })] // <-- note parens\n\\`\\`\\`\n\n**Lifecycle hook decision tree**:\n- \\`beforeMount\\` — register early routes that should bypass middleware (health, docs UI).\n- \\`beforeStart\\` — DI ready, server not listening yet. **Use this for \\`container.registerInstance(...)\\` calls** so they work under \\`createTestApp\\` too.\n- \\`afterStart\\` — server has \\`ctx.server\\` available. Only use for things that need a listening server (Socket.IO upgrades, port logging). **Doesn't fire under \\`createTestApp\\`.**\n- \\`shutdown\\` — runs concurrently via \\`Promise.allSettled\\`, so one failure doesn't block siblings (but errors are swallowed — log inside).\n\n**Middleware phases** (see \\`MiddlewarePhase\\` JSDoc):\n\\`beforeGlobal\\` | \\`afterGlobal\\` (default) | \\`beforeRoutes\\` | \\`afterRoutes\\` (fires only on fall-through — matched routes that respond skip it).\n\n**Multi-instance** — \\`.scoped('cache', { url: ... })\\` makes \\`name\\` become \\`RedisAdapter:cache\\`. **Deferred config** — \\`.async({ inject, useFactory })\\` for config that depends on DI-resolved services.\n\n**Red flags**:\n- \\`bootstrap({ adapters: [MyAdapter] })\\` — passed the factory, not the instance. Call it: \\`MyAdapter()\\`.\n- Inlining the adapter list directly in \\`src/index.ts\\` — entry file should stay thin.\n- Returning a plain object instead of going through \\`defineAdapter()\\` — type inference for \\`config\\` will be wrong.\n- Using \\`.async()\\` for an adapter that returns \\`middleware()\\` / \\`contributors()\\` / \\`beforeMount()\\` / \\`onRouteMount()\\` — those hooks have already run by the time \\`.async()\\` resolves and are silently skipped.\n- Cross-adapter ordering via array position when it's load-bearing — use \\`dependsOn: ['OtelAdapter']\\`; cycles throw \\`MountCycleError\\` at boot.\n- Using an adapter when the integration ships **modules + DI bindings + middleware** together → that's a plugin. Promote to \\`definePlugin()\\` (see \\`add-plugin\\` skill).\n\n**Nuances**:\n- \\`AdapterContext.server\\` is \\`undefined\\` outside \\`afterStart\\`.\n- \\`shutdown\\` errors are swallowed by \\`Promise.allSettled\\` — wrap in try/catch and log if you care.`,\n    },\n    {\n      slug: 'add-plugin',\n      frontmatterName: 'kickjs-add-plugin',\n      description:\n        'Use when scaffolding a feature that bundles modules + DI + middleware + adapters together (auth, monitoring suite, multi-tenant scaffolding).',\n      body: `**When plugin > adapter**: a plugin is the right answer when the integration ships **more than one** of: a module, a DI binding, middleware, or another adapter. If you have a single hook (\\`beforeStart\\`) and no other contributions, use \\`defineAdapter\\` instead.\n\n**Canonical shape**:\n\n\\`\\`\\`ts\nimport { definePlugin } from '@forinda/kickjs'\n\nexport const AuthPlugin = definePlugin({\n  name: 'AuthPlugin',\n  defaults: { tokenTtl: '1h' },\n  build: (config, { name }) => ({\n    modules: () => [AuthModule()],\n    adapters: () => [JwtAdapter({ ttl: config.tokenTtl })],\n    middleware: () => [requestIdMiddleware()],\n    register(container) {\n      container.registerFactory(TOKEN_SIGNER, () => createSigner(config))\n    },\n    contributors() {\n      return [LoadCurrentUser.registration]\n    },\n    onReady({ server }) {\n      log.info(\\`AuthPlugin listening on port \\${server.address().port}\\`)\n    },\n  }),\n})\n\n// In bootstrap:\nbootstrap({ plugins: [AuthPlugin({ tokenTtl: env.TOKEN_TTL })] }) // <-- parens\n\\`\\`\\`\n\n**Inline plugin literal** — the canonical answer for one-off DI bindings. There's no top-level \\`register:\\` on \\`bootstrap\\` itself:\n\n\\`\\`\\`ts\nbootstrap({\n  plugins: [{ name: 'vector-store', register(c) { c.registerInstance(VECTOR_STORE, store) } }],\n})\n\\`\\`\\`\n\n**Execution order** (memorize):\nplugin \\`register()\\` → plugin \\`middleware()\\` → plugin \\`modules()\\` + user modules → plugin \\`adapters()\\` + user adapters → server listens → plugin \\`onReady()\\`.\n\n**Static vs dynamic modules**: \\`modules()\\` returning an array is introspectable (Swagger, DevTools see it). \\`setup(registry)\\` is imperative — pick the latter when the module set depends on resolved config.\n\n**Multi-instance** — \\`.scoped('users', { url })\\`; derive unique DI tokens from \\`ctx.name\\` inside \\`build\\`:\n\n\\`\\`\\`ts\nbuild: (config, { name }) => ({\n  register(c) {\n    c.registerInstance(createToken(\\`cache/\\${name}\\`), client)\n  },\n})\n\\`\\`\\`\n\n**Precedence**: plugin contributors land at \\`'adapter'\\` precedence — beat global, lose to module/class/method same-key.\n\n**Red flags**:\n- \\`bootstrap({ plugins: [AuthPlugin] })\\` — passed factory. Call it: \\`AuthPlugin()\\`.\n- Reaching for a plugin when an adapter would do (no modules, no DI bindings, no contributors) — overkill; use \\`defineAdapter()\\`.\n- \\`.async()\\` plugin that depends on \\`modules()\\` / \\`middleware()\\` / \\`adapters()\\` / \\`contributors()\\` — those are dropped. \\`.async()\\` only resolves \\`register()\\` + \\`onReady()\\`.\n- Confusing CLI plugins (\\`defineCliPlugin\\` from \\`@forinda/kickjs-cli\\`) with runtime plugins (\\`definePlugin\\` from \\`@forinda/kickjs\\`) — different surfaces, different registration sites.\n- \\`dependsOn: ['SomePlugin']\\` referring to a plugin not in the boot list — throws \\`MissingMountDepError\\` at boot.\n\n**Nuances**:\n- \\`definition\\` is \\`Object.freeze\\`'d metadata; useful for version checks (\\`compare(AuthPlugin.definition.version, '1.2.0')\\`) — not mountable.`,\n    },\n    {\n      slug: 'write-controller-test',\n      frontmatterName: 'kickjs-write-controller-test',\n      description: 'Use when adding a Vitest test that exercises an HTTP route or DI graph.',\n      body: `**Template** (copy/paste, adjust):\n\n\\`\\`\\`ts\nimport { describe, it, expect, beforeEach } from 'vitest'\nimport request from 'supertest'\nimport { Container } from '@forinda/kickjs'\nimport { createTestApp } from '@forinda/kickjs-testing'\n// Side-effect import — registers the env schema, exactly as src/index.ts does.\n// \\`createTestApp\\` never loads the entry file, so without this\n// \\`ConfigService.get('YOUR_KEY')\\` is undefined under test while \\`@Value()\\`\n// still appears to work via its process.env fallback — the two disagree only\n// in tests.\nimport '@/config'\n\ndescribe('UserController', () => {\n  beforeEach(() => Container.reset()) // isolate DI between tests\n\n  it('returns users', async () => {\n    // \\`createTestApp\\` takes an OPTIONS OBJECT and returns\n    // \\`{ app, container }\\`. Passing a bare array throws\n    // \"this.options.modules is not iterable\"; the result has no \\`.get()\\`.\n    //\n    // Drive \\`app.handle\\` rather than \\`expressApp\\`: it is the Application's\n    // own Node listener, so the test runs on whichever runtime the app is\n    // configured with. Pass \\`runtime\\` to \\`createTestApp\\` to match production.\n    const { app } = await createTestApp({\n      // Matches this project's \\`modules.style\\`.\n      modules: [${moduleEntry}],\n    })\n    const res = await request(app.handle.bind(app)).get('/api/v1/users')\n    expect(res.status).toBe(200)\n  })\n})\n\\`\\`\\`\n\n**Typed handler signature** — pair with \\`kick typegen\\` so \\`ctx.body\\` / \\`params\\` / \\`query\\` are typed by the route's Zod schema:\n\n\\`\\`\\`ts\n@Post('/', { body: createTodoSchema })\nasync create(ctx: Ctx<KickRoutes.TodoController['create']>) {\n  // ctx.body is typed from createTodoSchema; ctx.params from the route.\n  // Returning (vs ctx.created) lets typegen infer the response type.\n  return reply(201, await this.service.create(ctx.body))\n}\n\\`\\`\\`\n\n**Red flags**:\n- \\`new Container()\\` — wrong; use \\`Container.reset()\\` in \\`beforeEach\\` or \\`Container.create()\\` for fully isolated graphs.\n- \\`Container.getInstance().reset()\\` — wrong; same fix.\n- Sharing a container instance across \\`it()\\` blocks — leaks registrations between tests.\n- Injecting a \\`Scope.REQUEST\\` service into a \\`SINGLETON\\` — container throws at resolve. Singletons must resolve request-scoped services explicitly per call.\n- Calling \\`getRequestValue<string>('traceId')\\` — the generic slot is the **key** type, not the value type; widens key and bypasses typed lookup.\n- Asserting on \\`res.body.requestId\\` when \\`requestId()\\` middleware isn't mounted in the test app — value will be \\`undefined\\`.\n- Using \\`Scope.REQUEST\\` services in a test without mounting \\`requestScopeMiddleware()\\` — \\`getRequestValue\\` silently returns \\`undefined\\`; \\`getRequestStore\\` throws.\n\n**Nuances**:\n- \\`@Inject\\` and \\`@Autowired\\` are interchangeable — same runtime, same types; pick by readability.\n- \\`@Value('MISSING_KEY')\\` with no default **throws on property access**, not at construction — tests that exercise the getter will surface the missing-env issue.`,\n    },\n    {\n      slug: 'env-wiring-check',\n      frontmatterName: 'kickjs-env-wiring-check',\n      description:\n        \"Use when ConfigService.get('SOME_KEY') returns undefined or @Value silently falls back to process.env.\",\n      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\\`.`,\n    },\n    {\n      slug: 'bootstrap-export',\n      frontmatterName: 'kickjs-bootstrap-export',\n      description:\n        \"Use when HMR is silently doing full restarts on every save, or createTestApp can't find the app handle.\",\n      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.`,\n    },\n    {\n      slug: 'thin-entry-file',\n      frontmatterName: 'kickjs-thin-entry-file',\n      description:\n        'Use when src/index.ts is accumulating module/middleware/plugin/adapter literals.',\n      body: `**Refactor target**:\n\n\\`\\`\\`ts\n// src/modules/index.ts — fluent chain (default for \\`modules.style: 'define'\\`)\nexport const modules = defineModules().mount(HelloModule()).mount(UsersModule())\n// OR for class-form projects (\\`modules.style: 'class'\\`):\n//   export const modules: AppModuleEntry[] = [HelloModule, UsersModule]\n\n// src/middleware/index.ts — global middleware uses RAW EXPRESS signature\n//                            (req, res, next), NOT (ctx, next)\n// \\`express.json()\\` is auto-skipped on Fastify and h3, which parse bodies\n// natively — harmless to list, but don't reach for it as the body parser there.\nexport const middleware = [requestId(), express.json(), helmet(), cors(), traceContext()]\n\n// src/plugins/index.ts\nexport const plugins = [MetricsPlugin(), AuthPlugin({ tokenTtl: env.TOKEN_TTL })]\n\n// src/adapters/index.ts\nexport const adapters = [SwaggerAdapter({ ... }), DevToolsAdapter()]\n\n// src/index.ts — stays small\nimport 'reflect-metadata'\nimport './config' // MUST be early — side-effect schema load\nimport { bootstrap } from '@forinda/kickjs'\nimport { modules } from './modules'\nimport { middleware } from './middleware'\nimport { plugins } from './plugins'\nimport { adapters } from './adapters'\nexport const app = await bootstrap({ modules, middlewares, plugins, adapters })\n\\`\\`\\`\n\n**One-off DI binding** — inline a literal plugin inside \\`plugins\\`, not a top-level option:\n\n\\`\\`\\`ts\nplugins: [\n  ...plugins,\n  { name: 'vector-store', register(c) { c.registerInstance(VECTOR_STORE, store) } },\n]\n\\`\\`\\`\n\n**Red flags**:\n- Any \\`new SomeAdapter()\\` / \\`SomePlugin()\\` literal inside \\`bootstrap({ ... })\\` instead of imported from a category folder.\n- Mixing middleware signatures: \\`bootstrap({ middlewares })\\` is **raw Express** \\`(req, res, next)\\`; \\`@Middleware()\\` decorators are \\`(ctx, next)\\`; adapter middleware is connect-style too (mounted through the runtime seam, so it is not Express-only). Wrong shape in the wrong slot throws \"Cannot read properties of undefined\".\n- \\`bootstrap({ register: ... })\\` — that option doesn't exist. Use an inline plugin.`,\n    },\n    {\n      slug: 'context-contributor',\n      frontmatterName: 'kickjs-context-contributor',\n      description:\n        \"Use when a middleware's only job is to set ctx values consumed elsewhere — replace with defineHttpContextDecorator (HTTP) or defineContextDecorator (transport-agnostic).\",\n      body: `**Pattern** (HTTP — most common):\n\n\\`\\`\\`ts\nimport { defineHttpContextDecorator, type RequestContext } from '@forinda/kickjs'\n\n// Augment ContextMeta — required for ctx.get('tenant') to be typed\ndeclare module '@forinda/kickjs' {\n  interface ContextMeta {\n    tenant: { id: string; name: string }\n  }\n}\n\n// The \\`declare module\\` block above is all you need for typed \\`ctx.get\\`.\n\nconst LoadTenant = defineHttpContextDecorator({\n  key: 'tenant',\n  deps: { repo: TENANT_REPO }, // typed DI\n  resolve: (ctx, { repo }) => repo.findById(ctx.req.headers['x-tenant-id'] as string),\n})\n\nconst LoadProject = defineHttpContextDecorator({\n  key: 'project',\n  dependsOn: ['tenant'], // typo'd key = tsc error\n  resolve: (ctx) => projectsRepo.find(ctx.get('tenant')!.id, ctx.params.id),\n})\n\n@LoadTenant\n@LoadProject\n@Get('/projects/:id')\ngetProject(ctx: RequestContext) {\n  return ctx.get('project')\n}\n\\`\\`\\`\n\nUse \\`defineContextDecorator\\` (no Http prefix) only when the contributor must run across HTTP, WebSocket, queue, and cron transports — \\`Ctx\\` defaults to the smaller \\`ExecutionContext\\` surface (\\`get\\` / \\`set\\` / \\`requestId\\` only, no \\`req\\`).\n\n**Five precedence levels** (high → low):\n**method > class > module > adapter > global**\n\nSame-key collisions WITHIN a precedence level throw \\`DuplicateContributorError\\`. Across levels, the higher precedence silently overrides — a feature, not a bug, but debug it by giving resolvers distinguishable return values.\n\n**Boot-time validation**:\n- Cycles in \\`dependsOn\\` → \\`ContributorCycleError\\`.\n- \\`dependsOn\\` referring to an unknown key → \\`MissingContributorError\\`.\n- Both errors fail boot, not first request.\n\n**Critical rules — all stem from the same shared-via-ALS instance model**:\n- Every per-request stage (middleware → contributors → handler) gets its OWN \\`RequestContext\\` instance, but they all read/write the SAME \\`AsyncLocalStorage\\`-backed bag.\n- **\\`resolve\\` and \\`onError\\` must RETURN the value** — the runner writes it via \\`ctx.set(key, value)\\`. Direct property assignment (\\`ctx.tenant = …\\`) sticks to one instance only and the handler instance never sees it.\n- \\`ctx.set('tenant', x)\\` then \\`ctx.get('tenant')\\` works across instances. \\`ctx.req.headers[...]\\` works (the underlying node request is shared). Note it is a node \\`IncomingMessage\\` on Fastify and a web-backed request on h3, not an \\`express.Request\\`.\n- Services with no \\`ctx\\` reference: \\`getRequestValue('tenant')\\` returns \\`MetaValue<'tenant'> | undefined\\` (typed via the augmented \\`ContextMeta\\`). For \\`requestId\\` use \\`getRequestStore()\\`.\n- **No \\`setRequestValue\\` — writes flow through \\`ctx.set\\` or a contributor's return value.** Avoids \"spooky action at a distance\" where any service can pollute the per-request bag.\n\n**Error matrix**:\n- \\`optional: true\\` — \\`resolve\\` throws → key left unset; downstream sees \\`ctx.get(key) === undefined\\`.\n- \\`optional: false\\` (default) + \\`onError\\` — return a fallback value to write; return \\`undefined\\` to skip; throw to forward to the request error handler.\n- \\`optional: false\\` + no \\`onError\\` — throw propagates straight to the request error handler.\n\n**Don't use this for**: response short-circuit, stream mutation, or pre-route-matching work — keep \\`@Middleware()\\` for those.\n\n**Red flags**:\n- \\`ctx.get('key')!\\` — the non-null assertion compiles even when the producing decorator isn't on the route. Use \\`ctx.require('key')\\`.\n- \\`contributors: [LoadX]\\` at a module / adapter / bootstrap site — those take registrations: \\`LoadX.registration\\` or \\`LoadX.with({ ... }).registration\\`.\n- A \\`paramDefaults\\` value that every call site overrides (\\`action: 'settings:read'\\`) — drop it and let the compiler require the field at each site.\n- \\`defineContextDecorator<'k', Deps, Params>(spec)\\` positional form for a parameterised contributor — use \\`.withParams<Params>()(spec)\\` or \\`deps\\` inference is lost.\n- \\`ctx.tenant = x\\` instead of returning the value from \\`resolve\\` — sticks to one instance only.\n- Plugin / adapter authors using bare keys (\\`'state'\\`) instead of namespaced (\\`'@my-plugin/state'\\`) — collides with adopter keys.\n- \\`getRequestValue<string>('traceId')\\` — generic is the **key** type, not value type.`,\n    },\n    {\n      slug: 'guard-vs-middleware-vs-contributor',\n      frontmatterName: 'kickjs-guard-vs-middleware-vs-contributor',\n      description:\n        'Use when adding auth checks, request-scoped values, or anything \"before the handler\" — picks between a guard, a middleware, and a context contributor.',\n      body: `**KickJS has no guard primitive.** There is no \\`@Guard\\`, no \\`canActivate\\`, no guard\nclass to implement. A guard IS a middleware — the word only names a convention\nand a directory. If you are porting NestJS habits, this is the first thing to\nunlearn.\n\n| | Guard | Middleware | Context contributor |\n|---|---|---|---|\n| What it is | a middleware, by convention | a middleware | a declarative value producer |\n| Signature | \\`(ctx, next)\\` | \\`(ctx, next)\\` on \\`@Middleware()\\`, \\`(req, res, next)\\` in \\`bootstrap({ middlewares })\\` | \\`resolve(ctx, deps)\\` returning a value |\n| Can end the request | yes | yes | **no** |\n| Runs | in the middleware stage | in the middleware stage | after ALL middleware |\n| Attached by | \\`@Middleware(fn)\\` | \\`@Middleware(fn)\\` or \\`bootstrap({ middlewares })\\` | \\`@LoadX\\`, or a registration at module / adapter / bootstrap level |\n| Generator | \\`kick g guard <name>\\` | \\`kick g middleware <name>\\` | \\`kick g contributor <name>\\` |\n| Lands in | \\`src/guards/<name>.guard.ts\\` | \\`src/middleware/<name>.middleware.ts\\` | \\`src/contributors/<name>.contributor.ts\\` |\n\nAdd \\`-m <module>\\` to any of those generators to place the file inside a module\ninstead of the app-level directory.\n\n**Choosing**: does the thing ever need to STOP the request?\n- Yes, and it is authorization → guard.\n- Yes, anything else (rate limit, body rewrite, response stream, work before route matching) → middleware.\n- No, it only computes a value the handler or a service reads off \\`ctx\\` → contributor. Typed, ordered, boot-validated, and it cannot silently swallow the request.\n\n**Ordering — guards run BEFORE contributors.** Every runtime does the same\nthing: run \\`entry.middlewares\\` in order, bail if the response was written,\nthen run the contributor pipeline, then the handler. So:\n\n\\`\\`\\`ts\n// WRONG — tenant is always undefined here.\nexport async function tenantGuard(ctx: RequestContext, next: () => void) {\n  const tenant = ctx.get('tenant') // contributors have not run yet\n  if (!tenant) return ctx.problem.forbidden()\n  next()\n}\n\\`\\`\\`\n\nA guard that needs a resolved value must resolve it itself, or the check\nbelongs in the contributor's own \\`resolve\\` (throw from there and the request\nerror handler takes over).\n\n**Write responses with \\`ctx.*\\`, never \\`ctx.res\\`.** \\`ctx.res\\` is the ENGINE-NATIVE\nresponse object, so \\`ctx.res.status(401).json(...)\\` only works on Express —\n\\`FastifyReply\\` has no \\`.json()\\` and h3's event has no \\`.status()\\`. Use\n\\`ctx.problem.unauthorized({ detail })\\` (RFC 9457) or \\`ctx.json(body, status)\\`,\nand the helper for anything else you would reach \\`ctx.res\\` for:\n\\`ctx.download(buffer, filename, contentType?)\\` for a generated file,\n\\`ctx.html(content)\\`, \\`ctx.redirect(url, status?)\\`, \\`ctx.sse()\\` for a stream.\nAll of them work on all four runtimes. Never hand \\`ctx.redirect\\` a destination\ntaken from the request unchecked — allow-list it, or accept only a same-site path\n(one leading \\`/\\`, not \\`//\\`) — or the route is an open redirect.\n\n**Guard shape**:\n\n\\`\\`\\`ts\nimport type { RequestContext } from '@forinda/kickjs'\n\nexport async function adminGuard(ctx: RequestContext, next: () => void): Promise<void> {\n  // Requires the session() middleware. Type the key once:\n  // declare module '@forinda/kickjs' { interface SessionData { role?: 'admin' | 'member' } }\n  const role = ctx.session?.data.role\n  if (!role) {\n    ctx.problem.unauthorized({ detail: 'Not signed in' })\n    return // do NOT call next()\n  }\n  if (role !== 'admin') {\n    ctx.problem.forbidden({ detail: 'Admin only' })\n    return\n  }\n  next()\n}\n\\`\\`\\`\n\n\\`\\`\\`ts\n@Middleware(adminGuard)\n@Get('/admin/stats')\nstats(ctx: RequestContext) { ... }\n\\`\\`\\`\n\nRole checks that are purely declarative (\\`@Public()\\`, \\`@Roles('admin')\\`,\n\\`@Can(...)\\`) are yours to define — see the BYO Auth recipe in the docs.\nHand-write a guard only for logic those don't express.\n\n**Red flags**:\n- \\`class AdminGuard implements CanActivate\\` / \\`@UseGuards()\\` — NestJS, not KickJS. Export a \\`(ctx, next)\\` function and attach with \\`@Middleware()\\`.\n- A guard calling \\`next()\\` AND writing a response — pick one; writing then continuing double-sends.\n- A guard reading \\`ctx.get(...)\\` for a contributor-produced key — contributors have not run yet.\n- \\`ctx.res.status(403).json(...)\\` in a guard — Express-only. Use \\`ctx.problem.forbidden()\\`.\n- A \"guard\" that only sets a value and always calls \\`next()\\` — that is a contributor wearing a guard's name.\n- Passing a \\`(ctx, next)\\` guard to \\`bootstrap({ middlewares })\\` — global middleware is connect-style \\`(req, res, next)\\`. Mount guards per-route with \\`@Middleware()\\`.\n`,\n    },\n    {\n      slug: 'query-parsing-list-endpoint',\n      frontmatterName: 'kickjs-query-parsing-list-endpoint',\n      description:\n        'Use when adding a paginated/filterable list route — emit ctx.qs + ctx.paginate with an allow-list.',\n      body: `**Canonical list endpoint**:\n\n\\`\\`\\`ts\n@Get('/')\nasync list(ctx: Ctx<KickRoutes.TodoController['list']>) {\n  const parsed = ctx.qs({\n    filterable: ['status', 'priority', 'assigneeId'], // allow-list, MUST be set\n    sortable: ['createdAt', 'updatedAt', 'priority'],\n    searchColumns: ['title', 'description'], // free-text search targets\n  })\n\n  return ctx.paginate(async () => {\n    const { data, total } = await this.service.list(parsed)\n    return { data, total }\n  }, parsed)\n}\n\\`\\`\\`\n\n**Operator format** (fixed): \\`?filter=field:op:value\\` where \\`op ∈ eq | neq | gt | gte | lt | lte | between | in | contains | starts | ends\\`. Sort is \\`?sort=field:asc|desc\\`. Only the first two colons are delimiters, so timestamps work (\\`createdAt:gt:2026-01-01T00:00:00Z\\`).\n\n**Drizzle adopters** — pass a \\`DrizzleQueryParamsConfig\\` with column refs:\n\n\\`\\`\\`ts\nconst TASK_QUERY_CONFIG = {\n  filterable: { status: tasks.status, priority: tasks.priority },\n  sortable: { createdAt: tasks.createdAt },\n  searchColumns: [tasks.title, tasks.description],\n}\nconst parsed = ctx.qs(TASK_QUERY_CONFIG)\n\\`\\`\\`\n\n**ORM-agnostic builders** — implement \\`QueryBuilderAdapter<TResult, TConfig>\\` with \\`build(parsed, config)\\`. The Drizzle + Prisma adapters live here.\n\n**Red flags**:\n- Reading \\`req.query.status\\` directly — bypasses the allow-list; opens unbounded filtering. Use \\`ctx.qs({ filterable })\\`.\n- Omitting \\`filterable\\` / \\`sortable\\` allow-list — every client-supplied filter is **silently dropped** (security default, but looks like a bug).\n- Hand-building the pagination meta in the controller — inconsistent response shape across endpoints. Always use \\`ctx.paginate()\\`.\n- Returning a bare array from a list endpoint when pagination is implied — breaks the \\`PaginatedResponse<T>\\` contract.\n- Mixing string \\`searchable\\` config with column \\`searchColumns\\` (Drizzle) — silently no-ops.\n\n**Nuances**:\n- \\`limit\\` is capped at 100 server-side; \\`q\\` (search) is truncated to 200 chars. Don't re-validate client-side.\n- Sort direction defaults to \\`asc\\` when omitted (\\`?sort=createdAt\\` ≡ \\`?sort=createdAt:asc\\`).`,\n    },\n    {\n      slug: 'use-asset-manager',\n      frontmatterName: 'kickjs-use-asset-manager',\n      description:\n        'Use when code reads template files / JSON fixtures via fs.readFile + path arithmetic — switch to assets.<ns>.<key>() and the kick.config.ts assetMap.',\n      body: `**Configure** \\`kick.config.ts\\`:\n\n\\`\\`\\`ts\nexport default defineConfig({\n  assetMap: {\n    mails: { src: 'src/templates/mails' },\n    reports: { src: 'src/templates/reports', glob: '**/*.{ejs,html}' },\n  },\n})\n\\`\\`\\`\n\n**Consume** via the typed Proxy — no \\`__dirname\\` arithmetic, dev/prod paths handled:\n\n\\`\\`\\`ts\nimport { assets } from '@forinda/kickjs'\n\nconst html = await assets.mails.welcome() // typed: tsc errors on bad key\n\\`\\`\\`\n\n**Class-field decorator** (lazy getter, swappable in tests):\n\n\\`\\`\\`ts\nclass WelcomeMailService {\n  @Asset('mails/welcome') private welcomeTemplate!: () => Promise<string>\n\n  async send(to: string) {\n    const body = await this.welcomeTemplate()\n  }\n}\n\\`\\`\\`\n\n**Dynamic dispatch** (CMS templates, codegen) — \\`resolveAsset(ns, key)\\` throws \\`UnknownAssetError\\` with \\`{ namespace, key }\\` fields when the key is missing.\n\n**Test fixtures** — swap via env override + cache clear:\n\n\\`\\`\\`ts\nbeforeEach(() => {\n  process.env.KICK_ASSETS_ROOT = path.resolve('__fixtures__/assets')\n  clearAssetCache()\n})\nafterEach(() => {\n  delete process.env.KICK_ASSETS_ROOT\n  clearAssetCache()\n})\n\\`\\`\\`\n\n**Red flags**:\n- Hand-rolled \\`process.env.NODE_ENV === 'production' ? join(__dirname, '../templates') : join(__dirname, 'templates')\\` — exactly what the asset manager replaces.\n- \\`keys: 'strip'\\` setting in \\`assetMap.<ns>\\` when basenames may collide — silent last-walk-wins data loss. Default \\`'auto'\\` keeps extensions only for colliding groups.\n- Non-default Vite \\`outDir\\` without mirroring in \\`kick.config.ts\\` — manifest writes at \\`dist/.kickjs-assets.json\\` but the resolver can't find it. Mirror via \\`build.outDir\\`.\n- Forgetting to re-run \\`kick typegen\\` after adding files — \\`assets.mails.newTemplate\\` is a tsc error even though the file ships. \\`kick dev\\` does this on-change; one-shot CI builds need \\`kick build\\` (or \\`kick build:assets\\` for manifest-only).\n- Same-name \\`welcome.ejs\\` + \\`welcome/login.ejs\\` — directory wins in the typed surface; the \\`.ejs\\` file still copies but isn't addressable.\n\n**Nuances**:\n- Resolution pipeline (cached): \\`KICK_ASSETS_ROOT\\` env override > built manifest at \\`build.outDir\\` / \\`dist\\` / \\`build\\` / \\`out\\` > dev-fallback in-memory walk. Manifest presence = \"running from built dist.\"\n- Dev-mode glob matcher is a lite implementation — \\`**/*\\`, \\`**/*.ext\\`, \\`**/*.{a,b}\\` are guaranteed; exotic globs warn-once and accept everything. Run \\`kick build:assets\\` to exercise the real glob engine.`,\n    },\n    {\n      slug: 'cli-commands-cheatsheet',\n      frontmatterName: 'kickjs-cli-commands-cheatsheet',\n      description:\n        'Use as a quick reference for the most common kick CLI workflows — scaffolding, dev/build/start, generation, inspection.',\n      body: `**Top commands**:\n- \\`kick new <name>\\` — start a new project (prompts for template / repo / pm).\n- \\`kick dev\\` — local dev server with Vite HMR.\n- \\`kick build\\` — production bundle via Vite.\n- \\`kick start\\` — run the built artifact (\\`NODE_ENV=production\\` auto-set).\n- \\`kick g module <name>\\` — add a feature module; structure follows \\`pattern\\` in \\`kick.config.ts\\`.\n- \\`kick g scaffold <Name> <field:type>...\\` — full CRUD module from field definitions.\n- \\`kick g guard <name>\\` / \\`kick g middleware <name>\\` / \\`kick g contributor <name>\\` — the three \"before the handler\" shapes. A guard is a middleware by convention, NOT a separate primitive.\n- \\`kick add <pkg>\\` — install optional packages (auto-resolves peer deps + package manager).\n- \\`kick g --list\\` — list every available generator (built-ins + plugin-shipped).\n- \\`kick info\\` — environment / version dump for bug reports.\n- \\`kick inspect\\` — introspect a running app: routes, middleware, adapters, DI graph.\n\n**Useful flag combos**:\n\n\\`\\`\\`bash\nkick new my-api --yes                                  # CI-safe: minimal + inmemory, no prompts\nkick new my-api -t ddd --pm ${pm} --no-git --install   # Fully scriptable DDD scaffold\nkick new . --yes --force                               # Scaffold into current dir, clear existing files\nkick g scaffold Post title:string body:text:optional   # Shell-safe optional field syntax\nkick g agents -f --only skills                         # Refresh just the skills after upgrade\nkick add queue:bullmq                                  # Package + peer deps (bullmq + ioredis) in one shot\nkick inspect --port 4000 --json                        # Machine-readable route/adapter dump\nkick g config --force --repo postgres                  # Drop a kick.config.ts into a legacy project\n\\`\\`\\`\n\n**Lesser-known, high-value**:\n- \\`kick inspect --watch\\` — live route/middleware/adapter table that re-renders on hot reload; faster than re-curling \\`/_debug\\`.\n- \\`kick g agents -f\\` — regenerates \\`CLAUDE.md\\` (root) and \\`.agents/AGENTS.md\\` / \\`GEMINI.md\\` / \\`COPILOT.md\\` + every \\`.agents/skills/<slug>/SKILL.md\\` from the current CLI templates.\n- \\`kick dev:debug\\` — same flags as \\`kick dev\\` but opens a Node inspector port for IDE attach.\n- \\`kick list --all\\` (alias \\`kick ls --all\\`) — full optional-package catalog at this CLI version.\n- \\`kick typegen --watch\\` — standalone typegen watcher when \\`kick dev\\` isn't running.\n- \\`kick check\\` — preflight gate (typecheck + lint + format) before commit.\n- \\`kick codemod\\` — automated AST-level migration between framework versions.\n\n**Red flags**:\n- Using globally-installed \\`@forinda/kickjs-cli\\` while contributing to the monorepo — \\`pnpm link --global\\` from \\`packages/cli\\` so generators match the framework.\n- Writing \\`\"name:type?\"\\` for optional scaffold fields — \\`?\\` is a shell glob in bash/zsh; use \\`name:type:optional\\`.\n- Running \\`kick new <name> --yes\\` in a non-empty directory expecting it to wipe — \\`--yes\\` aborts without \\`--force\\`; pair them when destruction is intended.\n- Skipping \\`kick g config\\` on a legacy project then wondering why generators ignore \\`modules.dir\\` / \\`modules.repo\\`.\n- Editing \\`kick.config.ts\\` with deprecated top-level \\`modulesDir\\` / \\`defaultRepo\\` / \\`schemaDir\\` / \\`pluralize\\` instead of the nested \\`modules\\` block.`,\n    },\n    {\n      slug: 'route-flags',\n      frontmatterName: 'kickjs-route-flags',\n      description:\n        'Use when a fact about a route (public, CSRF-exempt, unmetered, expose as a tool) has to be read by auth, CSRF, rate limiting, OpenAPI or MCP — instead of repeating it as paths in each consumer.',\n      body: `A route flag is a named, inheritable fact about a route. It carries no\nbehaviour: it records something every consumer can read, so \"this endpoint is\nopen\" is declared once instead of restated as an auth contributor, a\n\\`csrf ignorePaths\\` entry and a \\`rateLimit skipPaths\\` entry — two of which are\npathname strings that cannot express \\`/users/:id\\`.\n\n**Steps**:\n1. Declare it once, in its own module:\n   \\`\\`\\`ts\n   import { defineRouteFlag } from '@forinda/kickjs'\n\n   export const Public = defineRouteFlag('auth.public')\n   export const Limit = defineRouteFlag<{ rpm: number }>('rate.limit')\n   \\`\\`\\`\n2. Apply it. A class flag is inherited by every route under it; \\`.off\\` on a\n   method removes it:\n   \\`\\`\\`ts\n   @Public // every route below inherits it\n   @Controller()\n   export class WebhooksController {\n     @Get('/health')\n     health(ctx: RequestContext) {} // public\n\n     @Public.off // the method wins\n     @Post('/admin')\n     admin(ctx: RequestContext) {} // not public\n\n     @Limit({ rpm: 10 }) // flags can carry a value\n     @Post('/login')\n     login(ctx: RequestContext) {}\n   }\n   \\`\\`\\`\n3. Read it from the consumer that already exists, rather than a new one.\n   **Where a consumer is mounted decides how it reads flags** — everything\n   after route matching gets \\`ctx.route\\`; anything before it does not:\n\n   | Consumer | Mounted at | Reads flags by |\n   | --- | --- | --- |\n   | Handler | the route itself | \\`ctx.route?.flags.has('auth.public')\\` |\n   | Guard / \\`@Middleware()\\` | \\`@Middleware(fn)\\` on a method or controller class | \\`ctx.route\\`, or the built-ins' \\`exemptWhen\\` |\n   | \\`csrfGuard()\\` / \\`rateLimitGuard()\\` | same — \\`@Middleware()\\`, class or method | \\`exemptWhen: 'csrf.exempt'\\` |\n   | Contributor | method > class > module \\`contributors()\\` > adapter \\`contributors()\\` > \\`bootstrap({ contributors })\\` | \\`skipWhen\\` / \\`onlyWhen\\` on the registration |\n   | Global middleware (\\`rateLimit()\\`) | \\`bootstrap({ middlewares: [...] })\\` — runs **before** matching | the route policy table (\\`bindRoutePolicy\\`); \\`ctx.route\\` is \\`undefined\\` here |\n   | Adapter middleware | \\`AppAdapter.middleware()\\`, phase \\`beforeGlobal\\` … \\`afterRoutes\\` | the policy table — the handler is Express-style \\`(req, res, next)\\`, so there is no \\`ctx\\` in any phase |\n   | OpenAPI | \\`SwaggerAdapter({ publicFlag: 'auth.public' })\\` | read once at startup, not per request |\n   | MCP / AI tools | \\`McpAdapter({ exposeWhen: 'mcp.tool', hideWhen: 'mcp.hidden' })\\` | read once at startup |\n\n   The contributor row is the one that buys the most: those five levels mean a\n   plugin's contributor can be skipped on one route (\\`skipWhen\\`) without\n   forking it, and a method-level registration beats the adapter's.\n\n4. Run \\`kick typegen\\`. It writes the \\`KickRouteFlags\\` augmentation, so flag\n   names autocomplete and a typo fails \\`tsc\\` instead of silently never matching.\n\n**Red flags**:\n- Writing \\`@Public(false)\\` to remove a flag — removal is \\`@Public.off\\`. A\n  resolved flag is present or absent; \\`false\\` is a legitimate *value* for a\n  flag declared \\`boolean\\`, and a presence check would still answer \\`true\\`.\n- A new consumer growing its own \\`skipPaths\\` / \\`ignorePaths\\` list — that is\n  the duplication flags exist to remove, and path strings break on params and\n  on any \\`apiPrefix\\` change.\n- \\`@Public.off\\` on a route that never inherited the flag — a no-op, and\n  usually a sign the expected class-level flag is not there.\n- Reading \\`ctx.route\\` in global middleware — it is \\`undefined\\` before a route\n  is matched (steps 1-6 of the pipeline). Move the check into a guard mounted\n  with \\`@Middleware()\\`, or read the policy table.\n- Inventing a flag name per consumer (\\`auth.open\\`, \\`public\\`, \\`isPublic\\`). The\n  framework names none of them; pick one name per fact and reuse it.`,\n    },\n    {\n      slug: 'cli-plugin',\n      frontmatterName: 'kickjs-cli-plugin',\n      description:\n        'Use when adding a kick <name> command, a kick g <name> generator, or a typegen emitter to this project or a package it ships.',\n      body: `A CLI plugin contributes commands, generators and typegen emitters to the\n\\`kick\\` CLI. Every built-in command ships as one, so the contract is the same\none the framework uses.\n\n**Steps**:\n1. Write the plugin. All four contribution kinds are optional:\n   \\`\\`\\`ts\n   // kick-tool.ts\n   import { defineCliPlugin } from '@forinda/kickjs-cli'\n\n   export const toolPlugin = (options: { watch?: boolean } = {}) =>\n     defineCliPlugin({\n       // Stable id, unique across plugins — it names the plugin in conflict errors.\n       name: 'my-tool',\n       // Declarative: same shape as kick.config.ts \\`commands\\`.\n       commands: [{ name: 'db:migrate', description: 'Apply migrations', steps: 'node ./scripts/migrate.js' }],\n       // Programmatic: full commander API, when you need options or subcommands.\n       register(program, ctx) {\n         program\n           .command('my-tool')\n           .description('Do the thing')\n           .option('--watch', 'Watch mode')\n           .action(async () => {\n             ctx.log(\\`running in \\${ctx.projectRoot}\\`)\n             // ctx.config is the loaded kick.config.ts\n           })\n       },\n     })\n   \\`\\`\\`\n2. Register it in \\`kick.config.ts\\`:\n   \\`\\`\\`ts\n   import { toolPlugin } from './kick-tool'\n\n   export default defineConfig({ plugins: [toolPlugin()] })\n   \\`\\`\\`\n3. Check it is loaded, per contribution kind: \\`kick --help\\` lists a command,\n   \\`kick g --list\\` lists a generator, \\`kick typegen\\` runs an emitter. A\n   plugin that fails to load takes the whole CLI down with a conflict error,\n   so silence here means the config never referenced it.\n\n**Which kind to use**: \\`commands\\` for a shell one-liner, \\`register\\` for\noptions / subcommands / async work, \\`generators\\` (\\`defineGenerator\\`) for\n\\`kick g <name>\\` scaffolders, \\`typegens\\` for a file under \\`.kickjs/types/\\`.\n\n**Red flags**:\n- Confusing this with a runtime plugin: \\`defineCliPlugin\\` (from\n  \\`@forinda/kickjs-cli\\`) extends the CLI; \\`definePlugin\\` (from\n  \\`@forinda/kickjs\\`) hooks the running app. They share nothing.\n- Claiming a command name a built-in owns (\\`build:netlify\\`, \\`typegen\\`,\n  \\`generate\\`) — duplicate declarative names are a startup conflict, and\n  \\`register\\` has no conflict detection at all, so it silently loses. Namespace\n  your own (\\`my-tool:build\\`).\n- Doing real work inside \\`register\\` — it runs at CLI startup for every\n  command, so it must only register. Put the work in the action.\n- Importing heavy dependencies at module scope. \\`await import()\\` them inside\n  the action, so an unrelated \\`kick dev\\` does not pay for them.`,\n    },\n    {\n      slug: 'deploy',\n      frontmatterName: 'kickjs-deploy',\n      description:\n        'Use when deploying this app — Netlify, Vercel or Cloudflare Workers — or when an API route returns the SPA shell, the platform build fails, or the function is missing from a deploy.',\n      body: `**Netlify and Vercel** run the app as a Node function; the CLI builds both:\n\n\\`\\`\\`bash\n${pm} run build:netlify   # → .netlify/v1/functions/api.mjs\n${pm} run build:vercel    # → .vercel/output (Build Output API v3)\n\\`\\`\\`\n\nBoth bundle \\`src/serverless.ts\\` (\\`createHandler\\`), which is a second entry\nbeside \\`src/index.ts\\` — the long-running server. Keep the shared options in\none module both import, so they cannot drift.\n\nSettings are detected from the layout: a workspace member beside a \\`web\\`\npackage publishes \\`web/dist\\` and routes \\`/api/*\\`; a standalone API takes\nevery path. Override in \\`kick.config.ts\\`:\n\n\\`\\`\\`ts\nexport default defineConfig({\n  deploy: { apiPath: '/api', staticDir: '../web/dist' },\n})\n\\`\\`\\`\n\n**Cloudflare Workers** is a different entry, not a third flag on this one.\nWorkers have no \\`node:http\\`, so \\`createHandler\\` cannot run there; use the\nweb entry over h3 v2:\n\n\\`\\`\\`ts\n// src/worker.ts\nimport 'reflect-metadata'\nimport { createFetchHandler } from '@forinda/kickjs/web'\nimport * as h3 from 'h3' // v2 — passed in, edge bundlers have no createRequire\nimport { modules } from './modules'\n\nexport default createFetchHandler((env) => ({ h3, modules, env }))\n\\`\\`\\`\n\nTwo things make or break that deploy:\n\n1. **Pre-bundle it yourself.** Point \\`wrangler.jsonc\\`'s \\`main\\` at a bundle\n   built with SWC (the same Vite + \\`unplugin-swc\\` setup as the other\n   targets), never at \\`src/worker.ts\\`. Wrangler's own esbuild compiles\n   decorators as ES decorators and emits no decorator metadata, so DI fails\n   at startup with a \\`getOwnMetadata\\` TypeError before any request lands.\n2. **\\`compatibility_flags = [\"nodejs_compat\"]\\`** — request-scoped DI and\n   \\`ctx.set\\` / \\`ctx.get\\` ride on \\`AsyncLocalStorage\\`.\n3. **Do not \\`import './config'\\` here.** It is required in \\`src/index.ts\\` and\n   \\`src/serverless.ts\\`, and wrong in a Worker twice over: the config module\n   reaches for \\`node:fs\\` / \\`createRequire\\`, which kills the Worker at\n   startup, and \\`loadEnvFromSchema\\` parses \\`process.env\\`, which Workers do\n   not have. The \\`env\\` binding threaded through \\`createFetchHandler\\` is what\n   feeds \\`ConfigService.get()\\` and \\`@Value()\\` instead — so values arrive as\n   the raw strings the platform holds, without the schema's coercion or\n   defaults. Coerce where you read them.\n\nNot available on Workers: views, SPA/static serving, \\`@Asset\\`, adapters and\nplugins. Serve static files from Workers Assets or a separate deploy.\n\n**Red flags**:\n- An \\`/api/*\\` route returning \\`index.html\\` on Netlify — the function is not\n  routed. Check the deploy summary says a function was deployed, keep\n  \\`preferStatic\\` out of its config, and leave Netlify's **Package directory**\n  unset so it reads the function at the repo root.\n- Committing \\`.netlify/\\` or \\`.vercel/\\` — both are build output.\n- A frontend that builds somewhere other than \\`web/dist\\` and only one of\n  \\`deploy.staticDir\\`, \\`SpaAdapter({ clientDir })\\` and netlify.toml's\n  \\`publish\\` updated. All three name that directory.\n- Pointing a platform at \\`src/index.ts\\` — it calls \\`bootstrap()\\`, which\n  listens on a port and registers signal handlers inside the function.\n- Expecting \\`kick build\\` alone to produce a deployable function; it builds\n  the server. Run the target command after it.`,\n    },\n    {\n      slug: 'docs-lookup',\n      frontmatterName: 'kickjs-docs-lookup',\n      description:\n        'Use FIRST when unsure about any KickJS API, option, or behaviour — before guessing from memory or inferring from surrounding code.',\n      body: `These skills are deliberately short — they cover the traps, not the whole API\nsurface. When the answer is not in one of them, read the docs rather than\ninferring it from nearby code: a wrong guess about a framework API compiles\nfine and fails at runtime.\n\n**Where to look**\n\n| Question | Page |\n| --- | --- |\n| Anything — start here | https://kickjs.app/ |\n| Controllers, routing, \\`ctx\\` helpers | https://kickjs.app/guide/controllers |\n| DI, tokens, scopes | https://kickjs.app/guide/dependency-injection |\n| Modules and mounting | https://kickjs.app/guide/modules |\n| Adapters, plugins, lifecycle hooks | https://kickjs.app/guide/adapters |\n| Context Contributors | https://kickjs.app/guide/context-decorators |\n| Env, \\`ConfigService\\`, \\`@Value\\` | https://kickjs.app/guide/configuration |\n| Middleware and guards | https://kickjs.app/guide/middleware |\n| Testing (\\`createTestApp\\`) | https://kickjs.app/guide/testing |\n| Typegen and generated types | https://kickjs.app/guide/typegen |\n| HMR and the dev server | https://kickjs.app/guide/hmr |\n\n**Local, and usually faster**\n\n- \\`kick explain \"<error message>\"\\` — matches known failures and gives the fix.\n  Pipe a failing run in: \\`${pm} test 2>&1 | kick explain\\`.\n- \\`kick doctor\\` — checks this project's wiring.\n- \\`kick inspect\\` — the live route / adapter table.\n- \\`.kickjs/types/\\` — generated types are ground truth for what exists.\n- \\`node_modules/@forinda/kickjs/dist/*.d.mts\\` — the real signature when a doc\n  page and the code disagree.\n\n**Rule**: if you would be guessing, look it up. If a doc page contradicts the\ninstalled \\`.d.mts\\`, trust the \\`.d.mts\\` and say so — the docs may be behind the\nversion this project has.`,\n    },\n    {\n      slug: 'refresh-agent-docs',\n      frontmatterName: 'kickjs-refresh-agent-docs',\n      description:\n        'Use after a KickJS version bump to sync the .agents/ docs with the latest CLI templates.',\n      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.`,\n    },\n    {\n      slug: 'deny-list',\n      frontmatterName: 'kickjs-deny-list',\n      description:\n        'Patterns to refuse outright when the user asks for them — they break v4 invariants.',\n      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\\`.`,\n    },\n  ]\n\n  return skills\n}\n\nexport function generateKickJsSkillFiles(\n  name: string,\n  _template: ProjectTemplate,\n  pm: string,\n  style: ModuleStyle = 'define',\n): KickJsSkillFile[] {\n  const banner = `<!-- Generated by \\`kick g agents\\` for ${name}. Edits are overwritten on the next refresh; keep customisation in a SKILL.local.md alongside. -->`\n\n  const skills = buildSkills(pm, style)\n\n  return skills.map((skill) => ({\n    slug: skill.slug,\n    content: `---\nname: ${skill.frontmatterName}\ndescription: ${skill.description}\n---\n\n${banner}\n\n${skill.body}\n`,\n  }))\n}\n\n/**\n * @deprecated Kept only for back-compat with adopters who programmatically\n * import this function from `@forinda/kickjs-cli`. The CLI itself no\n * longer calls it — `kick g agents` emits per-skill SKILL.md files via\n * {@link generateKickJsSkillFiles}. Will be removed in a future minor.\n */\nexport function generateGemini(name: string, _template: ProjectTemplate, _pm: string): string {\n  return `# GEMINI.md — ${name}\n\n**Read \\`./AGENTS.md\\` first.** It is the canonical, multi-agent\nreference for this project — every convention, structure, decorator\npattern, env wiring rule, generator usage. This file is a thin\nGemini-specific layer; when the two disagree on anything substantive,\ntreat \\`AGENTS.md\\` as authoritative and flag the discrepancy.\n\n## Why this file\n\nGemini CLI auto-loads \\`GEMINI.md\\` when it lives alongside the\nagent-context files. Keeping it in \\`.agents/\\` next to \\`AGENTS.md\\`\nmeans Gemini reads the same shared prose as Codex / Cursor / Copilot\nwithout us copy-pasting.\n\n## Gemini-specific notes\n\n- **Skills activation** — Gemini activates skills via\n  \\`activate_skill\\` (its native MCP-style tool); the equivalent on\n  Claude Code is the \\`Skill\\` tool. Cross-reference the\n  \\`kickjs-skills.md\\` index for the available triggers.\n- **Tool naming** — Gemini's tool names differ from Claude Code's\n  (e.g. \\`read_file\\` vs \\`Read\\`, \\`run_terminal_command\\` vs\n  \\`Bash\\`). The shared prose in \\`AGENTS.md\\` describes intents, not\n  tool names; consult Gemini's docs for the concrete invocation.\n- **File ops** — Gemini's file edits are sandboxed; large refactors\n  may need explicit confirmation. Prefer the smallest-possible-edit\n  pattern.\n\n## Refreshing this file\n\n\\`kick g agents --only gemini -f\\` regenerates this file from the\nCLI template. Hand-edited content is overwritten — keep customisation\nin \\`.agents/GEMINI.local.md\\`.\n`\n}\n\n/**\n * Render the GitHub Copilot CLI agent file emitted at\n * `.agents/COPILOT.md`. Same pattern as `generateGemini` — thin\n * pointer to `.agents/AGENTS.md` with notes specific to Copilot\n * CLI's tool surface and conventions.\n */\nexport function generateCopilot(name: string, _template: ProjectTemplate, _pm: string): string {\n  return `# COPILOT.md — ${name}\n\n**Read \\`./AGENTS.md\\` first.** It is the canonical, multi-agent\nreference for this project — every convention, structure, decorator\npattern, env wiring rule, generator usage. This file is a thin\nCopilot-specific layer; when the two disagree on anything substantive,\ntreat \\`AGENTS.md\\` as authoritative and flag the discrepancy.\n\n## Why this file\n\nGitHub Copilot CLI auto-loads \\`COPILOT.md\\` when it lives alongside\nthe agent-context files. Keeping it in \\`.agents/\\` next to\n\\`AGENTS.md\\` means Copilot reads the same shared prose as\nCodex / Cursor / Gemini / Claude Code without copy-pasting.\n\n## Copilot-specific notes\n\n- **Skills** — Copilot CLI auto-discovers skills from installed\n  plugins; cross-reference \\`kickjs-skills.md\\` for available\n  triggers in this project.\n- **Tool naming** — Copilot's tool names differ from Claude Code's\n  (\\`edit\\` vs \\`Edit\\`, \\`shell\\` vs \\`Bash\\`, etc.). The shared\n  prose in \\`AGENTS.md\\` describes intents, not tool names; consult\n  Copilot's docs for the concrete invocation.\n- **Confirmation flows** — Copilot CLI surfaces destructive\n  operations through an explicit approval gate. Stage edits with\n  short, focused diffs so each one is easy to review at the prompt.\n\n## Refreshing this file\n\n\\`kick g agents --only copilot -f\\` regenerates this file from the\nCLI template. Hand-edited content is overwritten — keep customisation\nin \\`.agents/COPILOT.local.md\\`.\n`\n}\n","import { join } from 'node:path'\nimport { existsSync, readFileSync } from 'node:fs'\nimport { writeFileSafe } from '../utils/fs'\nimport { confirm } from '../utils/prompts'\nimport {\n  generateClaude,\n  generateAgents,\n  generateKickJsSkillFiles,\n  generateGemini,\n  generateCopilot,\n} from './templates/project-docs'\nimport { loadKickConfig } from '../config'\nimport type { ModuleStyle } from './templates/types'\n\ntype ProjectTemplate = 'rest' | 'minimal' | 'fullstack' | 'inertia'\n\n/**\n * Subdirectory (relative to the project root) where every shared\n * agent-context file lands. CLAUDE.md is the only exception — it stays\n * at the project root because Claude Code auto-loads CLAUDE.md from\n * there. CLAUDE.md is generated as a thin pointer that tells Claude\n * to read `.agents/AGENTS.md` first.\n *\n * Existing root-level AGENTS.md / kickjs-skills.md files (from older\n * scaffolds before this restructure) are left untouched — the\n * generator emits the new layout alongside them and leaves migration\n * to the adopter.\n */\nconst AGENTS_DIR = '.agents'\n\nexport interface GenerateAgentDocsOptions {\n  outDir: string\n  /** Override project name (defaults to package.json `name`). */\n  name?: string\n  /** Override package manager (defaults to package.json `packageManager` field, then 'pnpm'). */\n  pm?: string\n  /** Override template (defaults to kick.config.ts `pattern`, then 'rest'). */\n  template?: ProjectTemplate\n  /**\n   * Which file(s) to (re)generate. All `.agents/`-bound files land in\n   * the project's `.agents/` subdirectory; `claude` is the only file\n   * that stays at the project root.\n   *\n   * - `agents`  → `.agents/AGENTS.md`\n   * - `claude`  → `CLAUDE.md` (root; thin pointer to .agents/)\n   * - `skills`  → `.agents/skills/<slug>/SKILL.md` (one per skill)\n   * - `gemini`  → `.agents/GEMINI.md`\n   * - `copilot` → `.agents/COPILOT.md`\n   * - `both`    → `.agents/AGENTS.md` + `CLAUDE.md` (legacy alias)\n   * - `all`     → every file above\n   */\n  only?: 'agents' | 'claude' | 'skills' | 'gemini' | 'copilot' | 'both' | 'all'\n  /** Skip the overwrite prompt. */\n  force?: boolean\n}\n\nconst VALID_TEMPLATES = new Set<ProjectTemplate>(['rest', 'minimal', 'fullstack', 'inertia'])\n\nfunction detectName(outDir: string, override?: string): string {\n  if (override) return override\n  try {\n    const pkg = JSON.parse(readFileSync(join(outDir, 'package.json'), 'utf-8')) as { name?: string }\n    if (pkg.name) return pkg.name.replace(/^@[^/]+\\//, '')\n  } catch {\n    // No package.json — fall back to folder name\n  }\n  return outDir.split('/').findLast(Boolean) ?? 'app'\n}\n\nfunction detectPm(outDir: string, override?: string): string {\n  if (override) return override\n  try {\n    const pkg = JSON.parse(readFileSync(join(outDir, 'package.json'), 'utf-8')) as {\n      packageManager?: string\n    }\n    if (pkg.packageManager) return pkg.packageManager.split('@')[0]\n  } catch {\n    // ignore\n  }\n  return 'pnpm'\n}\n\n/**\n * Module declaration style, so generated examples show the form this project\n * actually uses. A `class` module passed as `UserModule()` calls a class\n * without `new`; a `define` module passed bare is refused when it takes config.\n */\nasync function detectStyle(outDir: string): Promise<ModuleStyle> {\n  try {\n    const cfg = await loadKickConfig(outDir)\n    return cfg?.modules?.style === 'class' ? 'class' : 'define'\n  } catch {\n    return 'define'\n  }\n}\n\nasync function detectTemplate(\n  outDir: string,\n  override?: ProjectTemplate,\n): Promise<ProjectTemplate> {\n  if (override) return override\n  try {\n    const cfg = await loadKickConfig(outDir)\n    const pattern = cfg?.pattern as ProjectTemplate | undefined\n    if (pattern && VALID_TEMPLATES.has(pattern)) return pattern\n  } catch {\n    // ignore\n  }\n  return 'rest'\n}\n\nexport async function generateAgentDocs(options: GenerateAgentDocsOptions): Promise<string[]> {\n  const only = options.only ?? 'all'\n  const name = detectName(options.outDir, options.name)\n  const pm = detectPm(options.outDir, options.pm)\n  const template = await detectTemplate(options.outDir, options.template)\n  const style = await detectStyle(options.outDir)\n\n  const wantsAgents = only === 'agents' || only === 'both' || only === 'all'\n  const wantsClaude = only === 'claude' || only === 'both' || only === 'all'\n  const wantsSkills = only === 'skills' || only === 'all'\n  const wantsGemini = only === 'gemini' || only === 'all'\n  const wantsCopilot = only === 'copilot' || only === 'all'\n\n  // CLAUDE.md stays at the project root because Claude Code auto-loads\n  // it from there. Every other shared-context file lands under\n  // `.agents/` so the root stays uncluttered. `writeFileSafe` creates\n  // parent directories automatically — no need to pre-mkdir.\n  const targets: { file: string; render: () => string }[] = []\n  if (wantsAgents) {\n    targets.push({\n      file: join(options.outDir, AGENTS_DIR, 'AGENTS.md'),\n      render: () => generateAgents(name, template, pm),\n    })\n  }\n  if (wantsClaude) {\n    targets.push({\n      file: join(options.outDir, 'CLAUDE.md'),\n      render: () => generateClaude(name, template, pm),\n    })\n  }\n  if (wantsSkills) {\n    // Per-skill SKILL.md under `.agents/skills/<slug>/` so agents that\n    // auto-discover skills (Claude Code, Copilot CLI plugins, Gemini's\n    // activate_skill) pick each up by its frontmatter without needing\n    // a separate index file.\n    for (const skill of generateKickJsSkillFiles(name, template, pm, style)) {\n      targets.push({\n        file: join(options.outDir, AGENTS_DIR, 'skills', skill.slug, 'SKILL.md'),\n        render: () => skill.content,\n      })\n    }\n  }\n  if (wantsGemini) {\n    targets.push({\n      file: join(options.outDir, AGENTS_DIR, 'GEMINI.md'),\n      render: () => generateGemini(name, template, pm),\n    })\n  }\n  if (wantsCopilot) {\n    targets.push({\n      file: join(options.outDir, AGENTS_DIR, 'COPILOT.md'),\n      render: () => generateCopilot(name, template, pm),\n    })\n  }\n\n  const written: string[] = []\n  for (const { file, render } of targets) {\n    if (existsSync(file) && !options.force) {\n      const overwrite = await confirm({\n        message: `${file.replace(options.outDir + '/', '')} already exists. Overwrite?`,\n        initialValue: false,\n      })\n      if (!overwrite) {\n        console.log(`  Skipped — existing ${file.replace(options.outDir + '/', '')} preserved.`)\n        continue\n      }\n    }\n    await writeFileSafe(file, render())\n    written.push(file)\n  }\n  return written\n}\n"],"mappings":";;;;;;;;;;uQAaA,SAAgBI,EAAe,EAAc,EAA4B,EAAoB,CAC3F,MAAO,iBAAiBC,EAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgD7BC,EAAG;;;EAGHA,EAAG;;;;;;;;;;;;;;;;;;;;;;;;CAyBL,CAGA,SAAgBC,EAAe,EAAc,EAA2B,EAAoB,CAC1F,MAAO,oCAAoCF,EAAK;;;;;;;;;WASvCC,EAAG;8CAEVE,IAAa,YACT;;;;;mCAK2BF,IAAO,OAAS,WAAa,GAAGA,EAAG,oBAAoBA,EAAG,cAAc;;;;;;;;;;;;;;;;uEAiBnG,GACL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAiMmBE,EAAS,YAAY,EAAE;;;;;;EAO3CA,IAAa,OACT;;;;;;;;EASA,oHAML;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAgCYF,EAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwIhB,CAoDA,SAASG,EAAY,EAAY,EAAqB,SAAyB,CAG7E,IAAMC,EAAcC,IAAU,QAAU,aAAe,eA4/BvD,MAAO,CAr/BL,CACE,KAAM,aACN,gBAAiB,oBACjB,YACE,2FACF,KAAM;;;;;;;kCAOsBL,EAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qDAyCjC,EACA,CACE,KAAM,cACN,gBAAiB,qBACjB,YACE,oGACF,KAAM,0gGAmDR,EACA,CACE,KAAM,aACN,gBAAiB,oBACjB,YACE,gJACF,KAAM,i3FAgER,EACA,CACE,KAAM,wBACN,gBAAiB,+BACjB,YAAa,0EACb,KAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA2BMI,EAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oKA+B1B,EACA,CACE,KAAM,mBACN,gBAAiB,0BACjB,YACE,yGACF,KAAM,opFAqCR,EACA,CACE,KAAM,mBACN,gBAAiB,0BACjB,YACE,0GACF,KAAM,s0BAgBR,EACA,CACE,KAAM,kBACN,gBAAiB,yBACjB,YACE,mFACF,KAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sFA4CR,EACA,CACE,KAAM,sBACN,gBAAiB,6BACjB,YACE,4KACF,KAAM,4mIAoER,EACA,CACE,KAAM,qCACN,gBAAiB,4CACjB,YACE,yJACF,KAAM,6hJA0FR,EACA,CACE,KAAM,8BACN,gBAAiB,qCACjB,YACE,qGACF,KAAM,okEA2CR,EACA,CACE,KAAM,oBACN,gBAAiB,2BACjB,YACE,wJACF,KAAM,06EAwDR,EACA,CACE,KAAM,0BACN,gBAAiB,iCACjB,YACE,0HACF,KAAM;;;;;;;;;;;;;;;;;8BAiBkBJ,EAAG;;;;;;;;;;;;;;;;;;;;;;;iKAwB7B,EACA,CACE,KAAM,cACN,gBAAiB,qBACjB,YACE,oMACF,KAAM,gvHAoER,EACA,CACE,KAAM,aACN,gBAAiB,oBACjB,YACE,gIACF,KAAM,iiFAwDR,EACA,CACE,KAAM,SACN,gBAAiB,gBACjB,YACE,wLACF,KAAM;;;EAGVA,EAAG;EACHA,EAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+CAiED,EACA,CACE,KAAM,cACN,gBAAiB,qBACjB,YACE,qIACF,KAAM;;;;;;;;;;;;;;;;;;;;;;;;6BAwBiBA,EAAG;;;;;;;;;0BAU5B,EACA,CACE,KAAM,qBACN,gBAAiB,4BACjB,YACE,2FACF,KAAM,sjCAsBR,EACA,CACE,KAAM,YACN,gBAAiB,mBACjB,YACE,sFACF,KAAM,80FAuCR,CAGU,CACd,CAEA,SAAgBM,EACd,EACA,EACA,EACA,EAAqB,SACF,CACnB,IAAMC,EAAS,2CAA2CR,EAAK,oGAI/D,OAFeI,EAAYH,EAAIK,CAEnB,CAAC,CAAC,IAAK,IAAW,CAC5B,KAAMG,EAAM,KACZ,QAAS;QACLA,EAAM,gBAAgB;eACfA,EAAM,YAAY;;;EAG/BD,EAAO;;EAEPC,EAAM,KAAK;CAEX,EAAE,CACJ,CAQA,SAAgBC,EAAe,EAAc,EAA4B,EAAqB,CAC5F,MAAO,iBAAiBV,EAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmC/B,CAQA,SAAgBW,EAAgB,EAAc,EAA4B,EAAqB,CAC7F,MAAO,kBAAkBX,EAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkChC,oDCxoDA,MAAMc,EAAa,UA4BbC,kBAAkB,IAAI,IAAqB,CAAC,OAAQ,UAAW,YAAa,SAAS,CAAC,EAE5F,SAASC,EAAW,EAAgB,EAA2B,CAC7D,GAAIC,EAAU,OAAOA,EACrB,GAAI,CACF,IAAMC,EAAM,KAAK,MAAMC,EAAaC,EAAKC,EAAQ,cAAc,EAAG,OAAO,CAAC,EAC1E,GAAIH,EAAI,KAAM,OAAOA,EAAI,KAAK,QAAQ,YAAa,EAAE,CACvD,MAAQ,CAER,CACA,OAAOG,EAAO,MAAM,GAAG,CAAC,CAAC,SAAS,OAAO,GAAK,KAChD,CAEA,SAASC,EAAS,EAAgB,EAA2B,CAC3D,GAAIL,EAAU,OAAOA,EACrB,GAAI,CACF,IAAMC,EAAM,KAAK,MAAMC,EAAaC,EAAKC,EAAQ,cAAc,EAAG,OAAO,CAAC,EAG1E,GAAIH,EAAI,eAAgB,OAAOA,EAAI,eAAe,MAAM,GAAG,CAAC,CAAC,EAC/D,MAAQ,CAER,CACA,MAAO,MACT,CAOA,eAAeK,EAAY,EAAsC,CAC/D,GAAI,CAEF,OAAO,MADWzB,EAAeuB,CAAM,EAAA,EAC3B,SAAS,QAAU,QAAU,QAAU,QACrD,MAAQ,CACN,MAAO,QACT,CACF,CAEA,eAAeG,EACb,EACA,EAC0B,CAC1B,GAAIP,EAAU,OAAOA,EACrB,GAAI,CAEF,IAAMQ,GAAU,MADE3B,EAAeuB,CAAM,EAAA,EAClB,QACrB,GAAII,GAAWV,EAAgB,IAAIU,CAAO,EAAG,OAAOA,CACtD,MAAQ,CAER,CACA,MAAO,MACT,CAEA,eAAsBZ,EAAkB,EAAsD,CAC5F,IAAMa,EAAOC,EAAQ,MAAQ,MACvB3B,EAAOgB,EAAWW,EAAQ,OAAQA,EAAQ,IAAI,EAC9C1B,EAAKqB,EAASK,EAAQ,OAAQA,EAAQ,EAAE,EACxCxB,EAAW,MAAMqB,EAAeG,EAAQ,OAAQA,EAAQ,QAAQ,EAChErB,EAAQ,MAAMiB,EAAYI,EAAQ,MAAM,EAExCC,EAAcF,IAAS,UAAYA,IAAS,QAAUA,IAAS,MAC/DG,EAAcH,IAAS,UAAYA,IAAS,QAAUA,IAAS,MAC/DI,EAAcJ,IAAS,UAAYA,IAAS,MAC5CK,EAAcL,IAAS,UAAYA,IAAS,MAC5CM,EAAeN,IAAS,WAAaA,IAAS,MAM9CO,EAAoD,CAAC,EAa3D,GAZIL,GACFK,EAAQ,KAAK,CACX,KAAMb,EAAKO,EAAQ,OAAQb,EAAY,WAAW,EAClD,WAAcZ,EAAeF,EAAMG,EAAUF,CAAE,CACjD,CAAC,EAEC4B,GACFI,EAAQ,KAAK,CACX,KAAMb,EAAKO,EAAQ,OAAQ,WAAW,EACtC,WAAc5B,EAAeC,EAAMG,EAAUF,CAAE,CACjD,CAAC,EAEC6B,EAKF,IAAK,IAAMrB,KAASF,EAAyBP,EAAMG,EAAUF,EAAIK,CAAK,EACpE2B,EAAQ,KAAK,CACX,KAAMb,EAAKO,EAAQ,OAAQb,EAAY,SAAUL,EAAM,KAAM,UAAU,EACvE,WAAcA,EAAM,OACtB,CAAC,EAGDsB,GACFE,EAAQ,KAAK,CACX,KAAMb,EAAKO,EAAQ,OAAQb,EAAY,WAAW,EAClD,WAAcJ,EAAeV,EAAMG,EAAUF,CAAE,CACjD,CAAC,EAEC+B,GACFC,EAAQ,KAAK,CACX,KAAMb,EAAKO,EAAQ,OAAQb,EAAY,YAAY,EACnD,WAAcH,EAAgBX,EAAMG,EAAUF,CAAE,CAClD,CAAC,EAGH,IAAMiC,EAAoB,CAAC,EAC3B,IAAK,GAAM,CAAE,OAAM,YAAYD,EACzBE,EAAWC,CAAI,GAAK,CAACT,EAAQ,OAK3B,CAAC,MAJmB9B,EAAQ,CAC9B,QAAS,GAAGuC,EAAK,QAAQT,EAAQ,OAAS,IAAK,EAAE,EAAE,6BACnD,aAAc,EAChB,CAAC,EAEC,QAAQ,IAAI,wBAAwBS,EAAK,QAAQT,EAAQ,OAAS,IAAK,EAAE,EAAE,YAAY,GAI3F,MAAM/B,EAAcwC,EAAMC,EAAO,CAAC,EAClCH,EAAQ,KAAKE,CAAI,GAEnB,OAAOF,CACT"}

package/dist/{agent-docs-JuchqDDh.mjs → agent-docs-DQksWOe5.mjs}

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v8.7.8
+ * @forinda/kickjs-cli v8.8.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,7 +8,7 @@
  *
  * @license MIT
  */
-import{t as e}from"./rolldown-runtime-DBz5c2Bd.mjs";import{a as t}from"./config-2x1N_mV1.mjs";import{r as n}from"./fs-fU5dBnRJ.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-OACgOwtl.mjs";import{a as t}from"./config-ty1Nc3PN.mjs";import{r as n}from"./fs-BGHl3dHm.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}
 
 **Read \`./.agents/AGENTS.md\` first.** It is the canonical, multi-agent
 reference for this project (Claude, Copilot, Codex, Gemini, etc.) —
@@ -101,12 +101,16 @@ 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`}\`.
 
 The type loop (do not break it):
-1. \`server/\` handlers RETURN their payloads → \`kick typegen\` (auto under
-   \`kick dev\`) emits \`server/.kickjs/types/kick__routes.ts\` incl. the flat
-   \`KickRoutes.Api\` map with inferred response types.
-2. \`web/src/types/kick-routes.d.ts\` imports that file TYPE-ONLY.
-3. \`web/src/api.ts\` = \`createClient<KickApi>({ baseUrl: '/api/v1' })\`
-   — every call site is typed from the server's handlers.
+1. \`server/\` handlers RETURN their payloads → \`kick typegen\` emits
+   \`server/.kickjs/types/kick__client.d.ts\`: the ambient \`KickClientApi\`
+   namespace, every response resolved to a plain shape. \`kick dev\` writes it
+   at startup but NOT on save — run \`kick typegen\` in \`server/\` after changing a route or a
+   response (the root \`build\` script runs it too).
+2. \`web/tsconfig.json\` lists that file in \`compilerOptions.types\`.
+3. \`web/src/api.ts\` = \`createClient<KickClientApi.Api>({ baseUrl })\`
+   — every call site is typed from the server's handlers. \`baseUrl\` is the
+   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
@@ -142,7 +146,7 @@ Rules that keep generated code correct on **every** engine:
   Don't assume \`ctx.req\` is an \`express.Request\` in portable code.
 - **Global middleware** in \`bootstrap({ middlewares })\` is connect-style
   \`(req, res, next)\` — it runs on all engines (Fastify via \`@fastify/middie\`,
-  h3 via \`fromNodeMiddleware\`). But on Fastify / h3 the engine parses the body
+  h3 via \`fromNodeHandler\`). But on Fastify / h3 the engine parses the body
   natively, so the default \`express.json()\` is **auto-skipped** (\`nativeBodyParsing\`).
   Don't add \`express.json()\` manually on those engines.
 - **File uploads** work on all three: \`@FileUpload({ mode, fieldName, ... })\` →
@@ -631,7 +635,7 @@ plugins: [
 **Red flags**:
 - Any \`new SomeAdapter()\` / \`SomePlugin()\` literal inside \`bootstrap({ ... })\` instead of imported from a category folder.
 - Mixing middleware signatures: \`bootstrap({ middlewares })\` is **raw Express** \`(req, res, next)\`; \`@Middleware()\` decorators are \`(ctx, next)\`; adapter middleware is connect-style too (mounted through the runtime seam, so it is not Express-only). Wrong shape in the wrong slot throws "Cannot read properties of undefined".
-- \`bootstrap({ register: ... })\` — that option doesn't exist. Use an inline plugin.`},{slug:`context-contributor`,frontmatterName:`kickjs-context-contributor`,description:`Use when a middleware's only job is to set ctx values consumed elsewhere — replace with defineHttpContextDecorator (HTTP) or defineContextDecorator (transport-agnostic).`,body:"**Pattern** (HTTP — most common):\n\n```ts\nimport { defineHttpContextDecorator, type RequestContext } from '@forinda/kickjs'\n\n// Augment ContextMeta — required for ctx.get('tenant') to be typed\ndeclare module '@forinda/kickjs' {\n  interface ContextMeta {\n    tenant: { id: string; name: string }\n  }\n}\n\n// The `declare module` block above is all you need for typed `ctx.get`.\n\nconst LoadTenant = defineHttpContextDecorator({\n  key: 'tenant',\n  deps: { repo: TENANT_REPO }, // typed DI\n  resolve: (ctx, { repo }) => repo.findById(ctx.req.headers['x-tenant-id'] as string),\n})\n\nconst LoadProject = defineHttpContextDecorator({\n  key: 'project',\n  dependsOn: ['tenant'], // typo'd key = tsc error\n  resolve: (ctx) => projectsRepo.find(ctx.get('tenant')!.id, ctx.params.id),\n})\n\n@LoadTenant\n@LoadProject\n@Get('/projects/:id')\ngetProject(ctx: RequestContext) {\n  return ctx.get('project')\n}\n```\n\nUse `defineContextDecorator` (no Http prefix) only when the contributor must run across HTTP, WebSocket, queue, and cron transports — `Ctx` defaults to the smaller `ExecutionContext` surface (`get` / `set` / `requestId` only, no `req`).\n\n**Five precedence levels** (high → low):\n**method > class > module > adapter > global**\n\nSame-key collisions WITHIN a precedence level throw `DuplicateContributorError`. Across levels, the higher precedence silently overrides — a feature, not a bug, but debug it by giving resolvers distinguishable return values.\n\n**Boot-time validation**:\n- Cycles in `dependsOn` → `ContributorCycleError`.\n- `dependsOn` referring to an unknown key → `MissingContributorError`.\n- Both errors fail boot, not first request.\n\n**Critical rules — all stem from the same shared-via-ALS instance model**:\n- Every per-request stage (middleware → contributors → handler) gets its OWN `RequestContext` instance, but they all read/write the SAME `AsyncLocalStorage`-backed bag.\n- **`resolve` and `onError` must RETURN the value** — the runner writes it via `ctx.set(key, value)`. Direct property assignment (`ctx.tenant = …`) sticks to one instance only and the handler instance never sees it.\n- `ctx.set('tenant', x)` then `ctx.get('tenant')` works across instances. `ctx.req.headers[...]` works (the underlying node request is shared). Note it is a node `IncomingMessage` on Fastify and h3, not an `express.Request`.\n- Services with no `ctx` reference: `getRequestValue('tenant')` returns `MetaValue<'tenant'> | undefined` (typed via the augmented `ContextMeta`). For `requestId` use `getRequestStore()`.\n- **No `setRequestValue` — writes flow through `ctx.set` or a contributor's return value.** Avoids \"spooky action at a distance\" where any service can pollute the per-request bag.\n\n**Error matrix**:\n- `optional: true` — `resolve` throws → key left unset; downstream sees `ctx.get(key) === undefined`.\n- `optional: false` (default) + `onError` — return a fallback value to write; return `undefined` to skip; throw to forward to the request error handler.\n- `optional: false` + no `onError` — throw propagates straight to the request error handler.\n\n**Don't use this for**: response short-circuit, stream mutation, or pre-route-matching work — keep `@Middleware()` for those.\n\n**Red flags**:\n- `ctx.get('key')!` — the non-null assertion compiles even when the producing decorator isn't on the route. Use `ctx.require('key')`.\n- `contributors: [LoadX]` at a module / adapter / bootstrap site — those take registrations: `LoadX.registration` or `LoadX.with({ ... }).registration`.\n- A `paramDefaults` value that every call site overrides (`action: 'settings:read'`) — drop it and let the compiler require the field at each site.\n- `defineContextDecorator<'k', Deps, Params>(spec)` positional form for a parameterised contributor — use `.withParams<Params>()(spec)` or `deps` inference is lost.\n- `ctx.tenant = x` instead of returning the value from `resolve` — sticks to one instance only.\n- Plugin / adapter authors using bare keys (`'state'`) instead of namespaced (`'@my-plugin/state'`) — collides with adopter keys.\n- `getRequestValue<string>('traceId')` — generic is the **key** type, not value type."},{slug:`guard-vs-middleware-vs-contributor`,frontmatterName:`kickjs-guard-vs-middleware-vs-contributor`,description:`Use when adding auth checks, request-scoped values, or anything "before the handler" — picks between a guard, a middleware, and a context contributor.`,body:"**KickJS has no guard primitive.** There is no `@Guard`, no `canActivate`, no guard\nclass to implement. A guard IS a middleware — the word only names a convention\nand a directory. If you are porting NestJS habits, this is the first thing to\nunlearn.\n\n| | Guard | Middleware | Context contributor |\n|---|---|---|---|\n| What it is | a middleware, by convention | a middleware | a declarative value producer |\n| Signature | `(ctx, next)` | `(ctx, next)` on `@Middleware()`, `(req, res, next)` in `bootstrap({ middlewares })` | `resolve(ctx, deps)` returning a value |\n| Can end the request | yes | yes | **no** |\n| Runs | in the middleware stage | in the middleware stage | after ALL middleware |\n| Attached by | `@Middleware(fn)` | `@Middleware(fn)` or `bootstrap({ middlewares })` | `@LoadX`, or a registration at module / adapter / bootstrap level |\n| Generator | `kick g guard <name>` | `kick g middleware <name>` | `kick g contributor <name>` |\n| Lands in | `src/guards/<name>.guard.ts` | `src/middleware/<name>.middleware.ts` | `src/contributors/<name>.contributor.ts` |\n\nAdd `-m <module>` to any of those generators to place the file inside a module\ninstead of the app-level directory.\n\n**Choosing**: does the thing ever need to STOP the request?\n- Yes, and it is authorization → guard.\n- Yes, anything else (rate limit, body rewrite, response stream, work before route matching) → middleware.\n- No, it only computes a value the handler or a service reads off `ctx` → contributor. Typed, ordered, boot-validated, and it cannot silently swallow the request.\n\n**Ordering — guards run BEFORE contributors.** Every runtime does the same\nthing: run `entry.middlewares` in order, bail if the response was written,\nthen run the contributor pipeline, then the handler. So:\n\n```ts\n// WRONG — tenant is always undefined here.\nexport async function tenantGuard(ctx: RequestContext, next: () => void) {\n  const tenant = ctx.get('tenant') // contributors have not run yet\n  if (!tenant) return ctx.problem.forbidden()\n  next()\n}\n```\n\nA guard that needs a resolved value must resolve it itself, or the check\nbelongs in the contributor's own `resolve` (throw from there and the request\nerror handler takes over).\n\n**Write responses with `ctx.*`, never `ctx.res`.** `ctx.res` is the ENGINE-NATIVE\nresponse object, so `ctx.res.status(401).json(...)` only works on Express —\n`FastifyReply` has no `.json()` and h3's event has no `.status()`. Use\n`ctx.problem.unauthorized({ detail })` (RFC 9457) or `ctx.json(body, status)`,\nand the helper for anything else you would reach `ctx.res` for:\n`ctx.download(buffer, filename, contentType?)` for a generated file,\n`ctx.html(content)`, `ctx.redirect(url, status?)`, `ctx.sse()` for a stream.\nAll of them work on all four runtimes. Never hand `ctx.redirect` a destination\ntaken from the request unchecked — allow-list it, or accept only a same-site path\n(one leading `/`, not `//`) — or the route is an open redirect.\n\n**Guard shape**:\n\n```ts\nimport type { RequestContext } from '@forinda/kickjs'\n\nexport async function adminGuard(ctx: RequestContext, next: () => void): Promise<void> {\n  // Requires the session() middleware. Type the key once:\n  // declare module '@forinda/kickjs' { interface SessionData { role?: 'admin' | 'member' } }\n  const role = ctx.session?.data.role\n  if (!role) {\n    ctx.problem.unauthorized({ detail: 'Not signed in' })\n    return // do NOT call next()\n  }\n  if (role !== 'admin') {\n    ctx.problem.forbidden({ detail: 'Admin only' })\n    return\n  }\n  next()\n}\n```\n\n```ts\n@Middleware(adminGuard)\n@Get('/admin/stats')\nstats(ctx: RequestContext) { ... }\n```\n\nRole checks that are purely declarative (`@Public()`, `@Roles('admin')`,\n`@Can(...)`) are yours to define — see the BYO Auth recipe in the docs.\nHand-write a guard only for logic those don't express.\n\n**Red flags**:\n- `class AdminGuard implements CanActivate` / `@UseGuards()` — NestJS, not KickJS. Export a `(ctx, next)` function and attach with `@Middleware()`.\n- A guard calling `next()` AND writing a response — pick one; writing then continuing double-sends.\n- A guard reading `ctx.get(...)` for a contributor-produced key — contributors have not run yet.\n- `ctx.res.status(403).json(...)` in a guard — Express-only. Use `ctx.problem.forbidden()`.\n- A \"guard\" that only sets a value and always calls `next()` — that is a contributor wearing a guard's name.\n- Passing a `(ctx, next)` guard to `bootstrap({ middlewares })` — global middleware is connect-style `(req, res, next)`. Mount guards per-route with `@Middleware()`.\n"},{slug:`query-parsing-list-endpoint`,frontmatterName:`kickjs-query-parsing-list-endpoint`,description:`Use when adding a paginated/filterable list route — emit ctx.qs + ctx.paginate with an allow-list.`,body:"**Canonical list endpoint**:\n\n```ts\n@Get('/')\nasync list(ctx: Ctx<KickRoutes.TodoController['list']>) {\n  const parsed = ctx.qs({\n    filterable: ['status', 'priority', 'assigneeId'], // allow-list, MUST be set\n    sortable: ['createdAt', 'updatedAt', 'priority'],\n    searchColumns: ['title', 'description'], // free-text search targets\n  })\n\n  return ctx.paginate(async () => {\n    const { data, total } = await this.service.list(parsed)\n    return { data, total }\n  }, parsed)\n}\n```\n\n**Operator format** (fixed): `?filter=field:op:value` where `op ∈ eq | neq | gt | gte | lt | lte | between | in | contains | starts | ends`. Sort is `?sort=field:asc|desc`. Only the first two colons are delimiters, so timestamps work (`createdAt:gt:2026-01-01T00:00:00Z`).\n\n**Drizzle adopters** — pass a `DrizzleQueryParamsConfig` with column refs:\n\n```ts\nconst TASK_QUERY_CONFIG = {\n  filterable: { status: tasks.status, priority: tasks.priority },\n  sortable: { createdAt: tasks.createdAt },\n  searchColumns: [tasks.title, tasks.description],\n}\nconst parsed = ctx.qs(TASK_QUERY_CONFIG)\n```\n\n**ORM-agnostic builders** — implement `QueryBuilderAdapter<TResult, TConfig>` with `build(parsed, config)`. The Drizzle + Prisma adapters live here.\n\n**Red flags**:\n- Reading `req.query.status` directly — bypasses the allow-list; opens unbounded filtering. Use `ctx.qs({ filterable })`.\n- Omitting `filterable` / `sortable` allow-list — every client-supplied filter is **silently dropped** (security default, but looks like a bug).\n- Hand-building the pagination meta in the controller — inconsistent response shape across endpoints. Always use `ctx.paginate()`.\n- Returning a bare array from a list endpoint when pagination is implied — breaks the `PaginatedResponse<T>` contract.\n- Mixing string `searchable` config with column `searchColumns` (Drizzle) — silently no-ops.\n\n**Nuances**:\n- `limit` is capped at 100 server-side; `q` (search) is truncated to 200 chars. Don't re-validate client-side.\n- Sort direction defaults to `asc` when omitted (`?sort=createdAt` ≡ `?sort=createdAt:asc`)."},{slug:`use-asset-manager`,frontmatterName:`kickjs-use-asset-manager`,description:`Use when code reads template files / JSON fixtures via fs.readFile + path arithmetic — switch to assets.<ns>.<key>() and the kick.config.ts assetMap.`,body:"**Configure** `kick.config.ts`:\n\n```ts\nexport default defineConfig({\n  assetMap: {\n    mails: { src: 'src/templates/mails' },\n    reports: { src: 'src/templates/reports', glob: '**/*.{ejs,html}' },\n  },\n})\n```\n\n**Consume** via the typed Proxy — no `__dirname` arithmetic, dev/prod paths handled:\n\n```ts\nimport { assets } from '@forinda/kickjs'\n\nconst html = await assets.mails.welcome() // typed: tsc errors on bad key\n```\n\n**Class-field decorator** (lazy getter, swappable in tests):\n\n```ts\nclass WelcomeMailService {\n  @Asset('mails/welcome') private welcomeTemplate!: () => Promise<string>\n\n  async send(to: string) {\n    const body = await this.welcomeTemplate()\n  }\n}\n```\n\n**Dynamic dispatch** (CMS templates, codegen) — `resolveAsset(ns, key)` throws `UnknownAssetError` with `{ namespace, key }` fields when the key is missing.\n\n**Test fixtures** — swap via env override + cache clear:\n\n```ts\nbeforeEach(() => {\n  process.env.KICK_ASSETS_ROOT = path.resolve('__fixtures__/assets')\n  clearAssetCache()\n})\nafterEach(() => {\n  delete process.env.KICK_ASSETS_ROOT\n  clearAssetCache()\n})\n```\n\n**Red flags**:\n- Hand-rolled `process.env.NODE_ENV === 'production' ? join(__dirname, '../templates') : join(__dirname, 'templates')` — exactly what the asset manager replaces.\n- `keys: 'strip'` setting in `assetMap.<ns>` when basenames may collide — silent last-walk-wins data loss. Default `'auto'` keeps extensions only for colliding groups.\n- Non-default Vite `outDir` without mirroring in `kick.config.ts` — manifest writes at `dist/.kickjs-assets.json` but the resolver can't find it. Mirror via `build.outDir`.\n- Forgetting to re-run `kick typegen` after adding files — `assets.mails.newTemplate` is a tsc error even though the file ships. `kick dev` does this on-change; one-shot CI builds need `kick build` (or `kick build:assets` for manifest-only).\n- Same-name `welcome.ejs` + `welcome/login.ejs` — directory wins in the typed surface; the `.ejs` file still copies but isn't addressable.\n\n**Nuances**:\n- Resolution pipeline (cached): `KICK_ASSETS_ROOT` env override > built manifest at `build.outDir` / `dist` / `build` / `out` > dev-fallback in-memory walk. Manifest presence = \"running from built dist.\"\n- Dev-mode glob matcher is a lite implementation — `**/*`, `**/*.ext`, `**/*.{a,b}` are guaranteed; exotic globs warn-once and accept everything. Run `kick build:assets` to exercise the real glob engine."},{slug:`cli-commands-cheatsheet`,frontmatterName:`kickjs-cli-commands-cheatsheet`,description:`Use as a quick reference for the most common kick CLI workflows — scaffolding, dev/build/start, generation, inspection.`,body:`**Top commands**:
+- \`bootstrap({ register: ... })\` — that option doesn't exist. Use an inline plugin.`},{slug:`context-contributor`,frontmatterName:`kickjs-context-contributor`,description:`Use when a middleware's only job is to set ctx values consumed elsewhere — replace with defineHttpContextDecorator (HTTP) or defineContextDecorator (transport-agnostic).`,body:"**Pattern** (HTTP — most common):\n\n```ts\nimport { defineHttpContextDecorator, type RequestContext } from '@forinda/kickjs'\n\n// Augment ContextMeta — required for ctx.get('tenant') to be typed\ndeclare module '@forinda/kickjs' {\n  interface ContextMeta {\n    tenant: { id: string; name: string }\n  }\n}\n\n// The `declare module` block above is all you need for typed `ctx.get`.\n\nconst LoadTenant = defineHttpContextDecorator({\n  key: 'tenant',\n  deps: { repo: TENANT_REPO }, // typed DI\n  resolve: (ctx, { repo }) => repo.findById(ctx.req.headers['x-tenant-id'] as string),\n})\n\nconst LoadProject = defineHttpContextDecorator({\n  key: 'project',\n  dependsOn: ['tenant'], // typo'd key = tsc error\n  resolve: (ctx) => projectsRepo.find(ctx.get('tenant')!.id, ctx.params.id),\n})\n\n@LoadTenant\n@LoadProject\n@Get('/projects/:id')\ngetProject(ctx: RequestContext) {\n  return ctx.get('project')\n}\n```\n\nUse `defineContextDecorator` (no Http prefix) only when the contributor must run across HTTP, WebSocket, queue, and cron transports — `Ctx` defaults to the smaller `ExecutionContext` surface (`get` / `set` / `requestId` only, no `req`).\n\n**Five precedence levels** (high → low):\n**method > class > module > adapter > global**\n\nSame-key collisions WITHIN a precedence level throw `DuplicateContributorError`. Across levels, the higher precedence silently overrides — a feature, not a bug, but debug it by giving resolvers distinguishable return values.\n\n**Boot-time validation**:\n- Cycles in `dependsOn` → `ContributorCycleError`.\n- `dependsOn` referring to an unknown key → `MissingContributorError`.\n- Both errors fail boot, not first request.\n\n**Critical rules — all stem from the same shared-via-ALS instance model**:\n- Every per-request stage (middleware → contributors → handler) gets its OWN `RequestContext` instance, but they all read/write the SAME `AsyncLocalStorage`-backed bag.\n- **`resolve` and `onError` must RETURN the value** — the runner writes it via `ctx.set(key, value)`. Direct property assignment (`ctx.tenant = …`) sticks to one instance only and the handler instance never sees it.\n- `ctx.set('tenant', x)` then `ctx.get('tenant')` works across instances. `ctx.req.headers[...]` works (the underlying node request is shared). Note it is a node `IncomingMessage` on Fastify and a web-backed request on h3, not an `express.Request`.\n- Services with no `ctx` reference: `getRequestValue('tenant')` returns `MetaValue<'tenant'> | undefined` (typed via the augmented `ContextMeta`). For `requestId` use `getRequestStore()`.\n- **No `setRequestValue` — writes flow through `ctx.set` or a contributor's return value.** Avoids \"spooky action at a distance\" where any service can pollute the per-request bag.\n\n**Error matrix**:\n- `optional: true` — `resolve` throws → key left unset; downstream sees `ctx.get(key) === undefined`.\n- `optional: false` (default) + `onError` — return a fallback value to write; return `undefined` to skip; throw to forward to the request error handler.\n- `optional: false` + no `onError` — throw propagates straight to the request error handler.\n\n**Don't use this for**: response short-circuit, stream mutation, or pre-route-matching work — keep `@Middleware()` for those.\n\n**Red flags**:\n- `ctx.get('key')!` — the non-null assertion compiles even when the producing decorator isn't on the route. Use `ctx.require('key')`.\n- `contributors: [LoadX]` at a module / adapter / bootstrap site — those take registrations: `LoadX.registration` or `LoadX.with({ ... }).registration`.\n- A `paramDefaults` value that every call site overrides (`action: 'settings:read'`) — drop it and let the compiler require the field at each site.\n- `defineContextDecorator<'k', Deps, Params>(spec)` positional form for a parameterised contributor — use `.withParams<Params>()(spec)` or `deps` inference is lost.\n- `ctx.tenant = x` instead of returning the value from `resolve` — sticks to one instance only.\n- Plugin / adapter authors using bare keys (`'state'`) instead of namespaced (`'@my-plugin/state'`) — collides with adopter keys.\n- `getRequestValue<string>('traceId')` — generic is the **key** type, not value type."},{slug:`guard-vs-middleware-vs-contributor`,frontmatterName:`kickjs-guard-vs-middleware-vs-contributor`,description:`Use when adding auth checks, request-scoped values, or anything "before the handler" — picks between a guard, a middleware, and a context contributor.`,body:"**KickJS has no guard primitive.** There is no `@Guard`, no `canActivate`, no guard\nclass to implement. A guard IS a middleware — the word only names a convention\nand a directory. If you are porting NestJS habits, this is the first thing to\nunlearn.\n\n| | Guard | Middleware | Context contributor |\n|---|---|---|---|\n| What it is | a middleware, by convention | a middleware | a declarative value producer |\n| Signature | `(ctx, next)` | `(ctx, next)` on `@Middleware()`, `(req, res, next)` in `bootstrap({ middlewares })` | `resolve(ctx, deps)` returning a value |\n| Can end the request | yes | yes | **no** |\n| Runs | in the middleware stage | in the middleware stage | after ALL middleware |\n| Attached by | `@Middleware(fn)` | `@Middleware(fn)` or `bootstrap({ middlewares })` | `@LoadX`, or a registration at module / adapter / bootstrap level |\n| Generator | `kick g guard <name>` | `kick g middleware <name>` | `kick g contributor <name>` |\n| Lands in | `src/guards/<name>.guard.ts` | `src/middleware/<name>.middleware.ts` | `src/contributors/<name>.contributor.ts` |\n\nAdd `-m <module>` to any of those generators to place the file inside a module\ninstead of the app-level directory.\n\n**Choosing**: does the thing ever need to STOP the request?\n- Yes, and it is authorization → guard.\n- Yes, anything else (rate limit, body rewrite, response stream, work before route matching) → middleware.\n- No, it only computes a value the handler or a service reads off `ctx` → contributor. Typed, ordered, boot-validated, and it cannot silently swallow the request.\n\n**Ordering — guards run BEFORE contributors.** Every runtime does the same\nthing: run `entry.middlewares` in order, bail if the response was written,\nthen run the contributor pipeline, then the handler. So:\n\n```ts\n// WRONG — tenant is always undefined here.\nexport async function tenantGuard(ctx: RequestContext, next: () => void) {\n  const tenant = ctx.get('tenant') // contributors have not run yet\n  if (!tenant) return ctx.problem.forbidden()\n  next()\n}\n```\n\nA guard that needs a resolved value must resolve it itself, or the check\nbelongs in the contributor's own `resolve` (throw from there and the request\nerror handler takes over).\n\n**Write responses with `ctx.*`, never `ctx.res`.** `ctx.res` is the ENGINE-NATIVE\nresponse object, so `ctx.res.status(401).json(...)` only works on Express —\n`FastifyReply` has no `.json()` and h3's event has no `.status()`. Use\n`ctx.problem.unauthorized({ detail })` (RFC 9457) or `ctx.json(body, status)`,\nand the helper for anything else you would reach `ctx.res` for:\n`ctx.download(buffer, filename, contentType?)` for a generated file,\n`ctx.html(content)`, `ctx.redirect(url, status?)`, `ctx.sse()` for a stream.\nAll of them work on all four runtimes. Never hand `ctx.redirect` a destination\ntaken from the request unchecked — allow-list it, or accept only a same-site path\n(one leading `/`, not `//`) — or the route is an open redirect.\n\n**Guard shape**:\n\n```ts\nimport type { RequestContext } from '@forinda/kickjs'\n\nexport async function adminGuard(ctx: RequestContext, next: () => void): Promise<void> {\n  // Requires the session() middleware. Type the key once:\n  // declare module '@forinda/kickjs' { interface SessionData { role?: 'admin' | 'member' } }\n  const role = ctx.session?.data.role\n  if (!role) {\n    ctx.problem.unauthorized({ detail: 'Not signed in' })\n    return // do NOT call next()\n  }\n  if (role !== 'admin') {\n    ctx.problem.forbidden({ detail: 'Admin only' })\n    return\n  }\n  next()\n}\n```\n\n```ts\n@Middleware(adminGuard)\n@Get('/admin/stats')\nstats(ctx: RequestContext) { ... }\n```\n\nRole checks that are purely declarative (`@Public()`, `@Roles('admin')`,\n`@Can(...)`) are yours to define — see the BYO Auth recipe in the docs.\nHand-write a guard only for logic those don't express.\n\n**Red flags**:\n- `class AdminGuard implements CanActivate` / `@UseGuards()` — NestJS, not KickJS. Export a `(ctx, next)` function and attach with `@Middleware()`.\n- A guard calling `next()` AND writing a response — pick one; writing then continuing double-sends.\n- A guard reading `ctx.get(...)` for a contributor-produced key — contributors have not run yet.\n- `ctx.res.status(403).json(...)` in a guard — Express-only. Use `ctx.problem.forbidden()`.\n- A \"guard\" that only sets a value and always calls `next()` — that is a contributor wearing a guard's name.\n- Passing a `(ctx, next)` guard to `bootstrap({ middlewares })` — global middleware is connect-style `(req, res, next)`. Mount guards per-route with `@Middleware()`.\n"},{slug:`query-parsing-list-endpoint`,frontmatterName:`kickjs-query-parsing-list-endpoint`,description:`Use when adding a paginated/filterable list route — emit ctx.qs + ctx.paginate with an allow-list.`,body:"**Canonical list endpoint**:\n\n```ts\n@Get('/')\nasync list(ctx: Ctx<KickRoutes.TodoController['list']>) {\n  const parsed = ctx.qs({\n    filterable: ['status', 'priority', 'assigneeId'], // allow-list, MUST be set\n    sortable: ['createdAt', 'updatedAt', 'priority'],\n    searchColumns: ['title', 'description'], // free-text search targets\n  })\n\n  return ctx.paginate(async () => {\n    const { data, total } = await this.service.list(parsed)\n    return { data, total }\n  }, parsed)\n}\n```\n\n**Operator format** (fixed): `?filter=field:op:value` where `op ∈ eq | neq | gt | gte | lt | lte | between | in | contains | starts | ends`. Sort is `?sort=field:asc|desc`. Only the first two colons are delimiters, so timestamps work (`createdAt:gt:2026-01-01T00:00:00Z`).\n\n**Drizzle adopters** — pass a `DrizzleQueryParamsConfig` with column refs:\n\n```ts\nconst TASK_QUERY_CONFIG = {\n  filterable: { status: tasks.status, priority: tasks.priority },\n  sortable: { createdAt: tasks.createdAt },\n  searchColumns: [tasks.title, tasks.description],\n}\nconst parsed = ctx.qs(TASK_QUERY_CONFIG)\n```\n\n**ORM-agnostic builders** — implement `QueryBuilderAdapter<TResult, TConfig>` with `build(parsed, config)`. The Drizzle + Prisma adapters live here.\n\n**Red flags**:\n- Reading `req.query.status` directly — bypasses the allow-list; opens unbounded filtering. Use `ctx.qs({ filterable })`.\n- Omitting `filterable` / `sortable` allow-list — every client-supplied filter is **silently dropped** (security default, but looks like a bug).\n- Hand-building the pagination meta in the controller — inconsistent response shape across endpoints. Always use `ctx.paginate()`.\n- Returning a bare array from a list endpoint when pagination is implied — breaks the `PaginatedResponse<T>` contract.\n- Mixing string `searchable` config with column `searchColumns` (Drizzle) — silently no-ops.\n\n**Nuances**:\n- `limit` is capped at 100 server-side; `q` (search) is truncated to 200 chars. Don't re-validate client-side.\n- Sort direction defaults to `asc` when omitted (`?sort=createdAt` ≡ `?sort=createdAt:asc`)."},{slug:`use-asset-manager`,frontmatterName:`kickjs-use-asset-manager`,description:`Use when code reads template files / JSON fixtures via fs.readFile + path arithmetic — switch to assets.<ns>.<key>() and the kick.config.ts assetMap.`,body:"**Configure** `kick.config.ts`:\n\n```ts\nexport default defineConfig({\n  assetMap: {\n    mails: { src: 'src/templates/mails' },\n    reports: { src: 'src/templates/reports', glob: '**/*.{ejs,html}' },\n  },\n})\n```\n\n**Consume** via the typed Proxy — no `__dirname` arithmetic, dev/prod paths handled:\n\n```ts\nimport { assets } from '@forinda/kickjs'\n\nconst html = await assets.mails.welcome() // typed: tsc errors on bad key\n```\n\n**Class-field decorator** (lazy getter, swappable in tests):\n\n```ts\nclass WelcomeMailService {\n  @Asset('mails/welcome') private welcomeTemplate!: () => Promise<string>\n\n  async send(to: string) {\n    const body = await this.welcomeTemplate()\n  }\n}\n```\n\n**Dynamic dispatch** (CMS templates, codegen) — `resolveAsset(ns, key)` throws `UnknownAssetError` with `{ namespace, key }` fields when the key is missing.\n\n**Test fixtures** — swap via env override + cache clear:\n\n```ts\nbeforeEach(() => {\n  process.env.KICK_ASSETS_ROOT = path.resolve('__fixtures__/assets')\n  clearAssetCache()\n})\nafterEach(() => {\n  delete process.env.KICK_ASSETS_ROOT\n  clearAssetCache()\n})\n```\n\n**Red flags**:\n- Hand-rolled `process.env.NODE_ENV === 'production' ? join(__dirname, '../templates') : join(__dirname, 'templates')` — exactly what the asset manager replaces.\n- `keys: 'strip'` setting in `assetMap.<ns>` when basenames may collide — silent last-walk-wins data loss. Default `'auto'` keeps extensions only for colliding groups.\n- Non-default Vite `outDir` without mirroring in `kick.config.ts` — manifest writes at `dist/.kickjs-assets.json` but the resolver can't find it. Mirror via `build.outDir`.\n- Forgetting to re-run `kick typegen` after adding files — `assets.mails.newTemplate` is a tsc error even though the file ships. `kick dev` does this on-change; one-shot CI builds need `kick build` (or `kick build:assets` for manifest-only).\n- Same-name `welcome.ejs` + `welcome/login.ejs` — directory wins in the typed surface; the `.ejs` file still copies but isn't addressable.\n\n**Nuances**:\n- Resolution pipeline (cached): `KICK_ASSETS_ROOT` env override > built manifest at `build.outDir` / `dist` / `build` / `out` > dev-fallback in-memory walk. Manifest presence = \"running from built dist.\"\n- Dev-mode glob matcher is a lite implementation — `**/*`, `**/*.ext`, `**/*.{a,b}` are guaranteed; exotic globs warn-once and accept everything. Run `kick build:assets` to exercise the real glob engine."},{slug:`cli-commands-cheatsheet`,frontmatterName:`kickjs-cli-commands-cheatsheet`,description:`Use as a quick reference for the most common kick CLI workflows — scaffolding, dev/build/start, generation, inspection.`,body:`**Top commands**:
 - \`kick new <name>\` — start a new project (prompts for template / repo / pm).
 - \`kick dev\` — local dev server with Vite HMR.
 - \`kick build\` — production bundle via Vite.
@@ -847,4 +851,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=e({generateAgentDocs:()=>N});const D=`.agents`,O=new Set([`rest`,`minimal`,`fullstack`]);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){if(r(t)&&!e.force&&!await _({message:`${t.replace(e.outDir+`/`,``)} already exists. Overwrite?`,initialValue:!1})){console.log(`  Skipped — existing ${t.replace(e.outDir+`/`,``)} preserved.`);continue}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 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};

package/dist/{build-CLWPSTR5.mjs → build-Bnd_mk4h.mjs}

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v8.7.8
+ * @forinda/kickjs-cli v8.8.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,6 +8,6 @@
  *
  * @license MIT
  */
-import{t as e}from"./rolldown-runtime-DBz5c2Bd.mjs";import{dirname as t,isAbsolute as n,join as r,relative as i,resolve as a}from"node:path";import{cpSync as o,existsSync as s,mkdirSync as c,statSync as l,writeFileSync as u}from"node:fs";import{glob as d}from"glob";import{groupAssetKeys as f}from"@forinda/kickjs";var p=e({ASSET_MANIFEST_VERSION:()=>1,buildAssets:()=>m});async function m(e,t){let{cwd:n,silent:o=!1}=t,s=t.distDir??e?.build?.outDir??`dist`,l=e?.assetMap;if(!l||Object.keys(l).length===0)return null;let d=o?()=>{}:console.log,f=a(n,s);c(f,{recursive:!0});let p=[],m={};for(let[e,t]of Object.entries(l)){let r=await h(e,t,n,f);p.push(r.entrySummary),Object.assign(m,r.manifestSlice),d(`    ✓ ${e}: ${r.entrySummary.filesCopied} file(s) → ${r.entrySummary.dest}`)}let g={version:1,entries:m},_=r(f,`.kickjs-assets.json`);return u(_,JSON.stringify(g,null,2)+`
+import{t as e}from"./rolldown-runtime-OACgOwtl.mjs";import{dirname as t,isAbsolute as n,join as r,relative as i,resolve as a}from"node:path";import{cpSync as o,existsSync as s,mkdirSync as c,statSync as l,writeFileSync as u}from"node:fs";import{glob as d}from"glob";import{groupAssetKeys as f}from"@forinda/kickjs";var p=/* @__PURE__ */ e({ASSET_MANIFEST_VERSION:()=>1,buildAssets:()=>m});async function m(e,t){let{cwd:n,silent:o=!1}=t,s=t.distDir??e?.build?.outDir??`dist`,l=e?.assetMap;if(!l||Object.keys(l).length===0)return null;let d=o?()=>{}:console.log,f=a(n,s);c(f,{recursive:!0});let p=[],m={};for(let[e,t]of Object.entries(l)){let r=await h(e,t,n,f);p.push(r.entrySummary),Object.assign(m,r.manifestSlice),d(`    ✓ ${e}: ${r.entrySummary.filesCopied} file(s) → ${r.entrySummary.dest}`)}let g={version:1,entries:m},_=r(f,`.kickjs-assets.json`);return u(_,JSON.stringify(g,null,2)+`
 `,`utf-8`),d(`    ✓ wrote manifest → ${i(n,_)} (${Object.keys(m).length} entries)`),{manifestPath:_,entries:p,manifest:g}}async function h(e,n,l,u){let p=a(l,n.src),m=n.dest?a(l,n.dest):r(u,e);if(v(m,l))return console.warn(`  ⚠ assetMap.${e}.dest ('${n.dest}') resolves outside the project root — skipping copy`),{entrySummary:{namespace:e,src:n.src,dest:i(l,m),filesCopied:0},manifestSlice:{}};if(!s(p)||!y(p))return{entrySummary:{namespace:e,src:n.src,dest:i(l,m),filesCopied:0},manifestSlice:{}};let h=n.glob??`**/*`,b=await d(h,{cwd:p,nodir:!0,dot:!1,posix:!0});c(m,{recursive:!0});let x={},S=[...b].toSorted(),{pairs:C,collisionGroupsResolved:w}=f(e,S,{strategy:n.keys??`auto`}),T=0;for(let{rel:e,key:n}of C){let i=r(p,e),a=r(m,e);x[n]=_(u,a),!g(i,a)&&(c(t(a),{recursive:!0}),o(i,a),T++)}return w>0&&console.log(`  ℹ assetMap.${e}: auto-resolved ${w} basename collision(s) by keeping extensions (set 'keys: "strip"' to opt back into legacy last-write-wins behaviour, or 'keys: "with-extension"' to keep all keys verbose).`),{entrySummary:{namespace:e,src:n.src,dest:i(l,m),filesCopied:T},manifestSlice:x}}function g(e,t){if(!s(t))return!1;try{let n=l(e),r=l(t);return r.size===n.size&&r.mtimeMs>=n.mtimeMs}catch{return!1}}function _(e,t){return i(e,t).split(/[\\/]/).filter(Boolean).join(`/`)}function v(e,t){let r=i(t,e);return r===``?!1:r.startsWith(`..`)||n(r)}function y(e){try{return l(e).isDirectory()}catch{return!1}}export{p as n,m as t};
-//# sourceMappingURL=build-CLWPSTR5.mjs.map
+//# sourceMappingURL=build-Bnd_mk4h.mjs.map