kimaki 0.26.0 → 0.27.0

package/skills/goke/SKILL.md

@@ -5,8 +5,9 @@ description: >
   with Standard Schema support (Zod, Valibot, ArkType). Use goke when building CLI
   tools — it handles commands, subcommands, options, type coercion, help generation,
   and more. Schema-based options give you automatic type inference, coercion from
-  strings, and help text generation. ALWAYS read this skill when a repo uses goke
-  for its CLI.
+  strings, and help text generation. Pair with `@goke/mcp` to generate CLI
+  commands automatically from an MCP server. ALWAYS read this skill when a repo
+  uses goke for its CLI.
 version: 0.0.1
 ---
 
@@ -30,14 +31,51 @@ npm install goke # or bun, pnpm, etc
 
 ## Quick Notes
 
-- Core APIs: `cli.option`, `cli.use`, `cli.version`, `cli.help`, `cli.completions`, `cli.parse`
+- Core APIs: `cli.option`, `cli.use`, `cli.section`, `cli.version`, `cli.help`, `cli.completions`, `cli.parse`
 - Prefer injected `{ fs, console, process }` over globals
 - Use relative paths with injected `fs`; if a helper needs current-cwd semantics, pass injected `process.cwd` into that helper
 - For JustBash compatibility tests, import the existing CLI from app code instead of defining a new CLI inside the test
 - **Never install `picocolors`, `chalk`, `kleur`, or any color library.** Use `import { colors } from 'goke'` instead. It's a vendored picocolors with zero extra dependencies.
+- Use [`@goke/mcp`](https://github.com/remorses/goke/tree/main/mcp) to generate CLI commands from an MCP server. `addMcpCommands({ cli, getMcpUrl, loadCache, saveCache })` discovers tools and registers a typed command for each one.
 
 The README is the source of truth for rules, examples, testing patterns, JustBash integration, and API details.
 
+## Reporting goke bugs
+
+If you find a bug in goke, **always open a GitHub issue with the `gh` CLI**. Do not only mention it in chat.
+
+```bash
+gh issue create --repo remorses/goke --title "Short bug title" --body "$(cat <<'EOF'
+**Model:** grok-4.6
+**Harness:** OpenCode / Kimaki
+
+**What happened**
+Describe the unexpected behavior.
+
+**Relevant goke code**
+Paste the CLI definition or goke API usage from this package that triggered the bug.
+
+**Reproduction**
+Minimal example that fails:
+
+```ts
+import { goke } from 'goke'
+
+const cli = goke('mycli')
+cli.command('deploy', 'Deploy').action(() => {})
+cli.parse()
+```
+EOF
+)"
+```
+
+Always include in the issue body:
+
+- the **model** used (for example `grok-4.6`, `claude-opus-4-6`)
+- the **harness** (for example OpenCode, Claude Code, Cursor, Codex)
+- the **relevant goke code** from this package that hit the bug
+- a **minimal reproduction** example
+
 If the README or this skill mentions a `goke` export that is missing from the installed package, upgrade `goke` to latest first before adding workarounds or custom local detection code:
 
 ```bash
@@ -72,15 +110,30 @@ if (isAgent) {
 }
 ```
 
-When guarding interactive prompts, check `isAgent` alongside `!process.stdin.isTTY`:
+`isAgent` is for **skipping interactive prompts that have a CLI flag alternative** (e.g. `--env staging` instead of a clack select). Use it to require the flag and fail with a usage hint instead of hanging on stdin:
 
 ```ts
-if (isAgent || !process.stdin.isTTY) {
-  console.error('Missing --env. Usage: deploy --env staging|production')
+if (!env) {
+  if (isAgent || !process.stdin.isTTY) {
+    console.error('Missing --env. Usage: deploy --env staging|production')
+    process.exit(1)
+  }
+  // ... clack prompt fallback
+}
+```
+
+**Never use `isAgent` to block commands that have no flag alternative**, like device-flow login. Those commands don't read stdin at all; they open a browser, print a code, and poll. The only real requirement is a TTY for spinner output. Use `!process.stdin.isTTY` or `!process.stdout.isTTY` alone for those:
+
+```ts
+// login command — no flag alternative, agent can run it in tuistory
+if (!process.stdin.isTTY) {
+  console.error('Login requires a terminal. Run in tuistory or tmux.')
   process.exit(1)
 }
 ```
 
+Agents can run login commands in a PTY via tuistory and complete the browser flow with playwriter. Blocking them with `isAgent` makes login impossible from agent contexts.
+
 Supported agents: `cursor`, `claude`, `devin`, `replit`, `gemini`, `codex`, `auggie`, `opencode`, `kiro`, `goose`, `pi`. Set `AI_AGENT` env var to override.
 
 ## Long-Running Interactive Commands
@@ -96,16 +149,22 @@ cli
   .command('login', 'Authenticate with browser login')
   .action(async (options, ctx) => {
     if (ctx.daemon.isDaemon) {
-      // ── DAEMON: run the long-running flow in background ──
-      const result = await startOAuthFlow({ /* ... */ })
+      // ── DAEMON: create the URL, hand it to the foreground, then wait ──
+      const flow = await startOAuthFlow({ /* ... */ })
+      ctx.daemon.publishStartupMessage(`Authorize: ${flow.authorizationUrl}`)
+      ctx.daemon.ready()
+      const result = await flow.waitForApproval()
       if (result.success) saveAuth(result)
       return // daemon exits, PID file is cleaned up
     }
 
     // ── CLIENT: decide foreground vs background ──
     if (isAgent) {
-      // Agent mode: start daemon and return immediately
-      await ctx.daemon.start({ timeoutMs: 10 * 60 * 1000 })
+      // Agent mode: return after the daemon publishes its authorization URL
+      await ctx.daemon.start({
+        waitForStartup: true,
+        timeoutMs: 10 * 60 * 1000,
+      })
       ctx.console.log('Login running in background.')
       ctx.console.log('After approving in browser, verify with: mycli me')
       return
@@ -117,6 +176,8 @@ cli
   })
 ```
 
+Use `waitForStartup: true` when the daemon creates an OAuth URL, device code, or other value that the agent must see before the foreground command returns. Publish ordered messages with `publishStartupMessage(message, { stream: 'stdout' | 'stderr' })`, then call `ready()`. Detached stdio remains ignored. Attached mode still receives the messages directly and waits for the daemon to exit.
+
 Add a `me` command (exits 0 if logged in, 1 if not) so agents can poll for completion. Use `ctx.daemon.forCommand('login')` to check the login daemon status from other commands. See the **Background Daemons** section in the goke README for the full pattern, including `env` passthrough and PID file safety.
 
 ## Shell Completions
@@ -220,6 +281,17 @@ project remove
 
 Pick **singular or plural** for the noun and stick with it across the entire CLI. If `project list` exists, don't add `projects add`.
 
+**Always group namespaced commands with `.section()`.** Commands that share a parent word (`get pods`, `get services`, `auth login`) must sit under a named heading in root help. Call `cli.section('Get')` before registering that group. Use `.command(...).section('Name')` when one command belongs in a different group.
+
+```ts
+cli.section('Get')
+cli.command('get pods', 'List pods')
+cli.command('get services', 'List services')
+
+cli.section('Describe')
+cli.command('describe pod <name>', 'Describe a pod')
+```
+
 ### Consistent verbs
 
 Choose one verb per action and reuse it everywhere:
@@ -233,6 +305,16 @@ Choose one verb per action and reuse it everywhere:
 
 Check which verbs the CLI already uses and match them. If existing commands use `add`, every new "create something" command should also use `add`.
 
+### Never mix different ID kinds in positionals
+
+All positionals of a command must identify the same kind of thing. Never give the first positional a different meaning than the rest (e.g. `events <recordingId> [...eventIds]`): a call like `events 1 4 7` is unreadable because the first number silently refers to a different entity. Move the parent/scoping ID to an optional flag with a sensible default and keep positionals homogeneous:
+
+```ts
+cli
+  .command('recorder events [...eventIds]', 'Print recorded events')
+  .option('-r, --recording <id>', 'Recording ID (defaults to the latest recording)')
+```
+
 ## Prefer Optional Flags Over Required Flags
 
 **Never make a flag required when it can be optional with an interactive fallback.** Required flags force users to read `--help` before they can run anything. Optional flags let them run the bare command and discover options progressively through prompts.
@@ -301,6 +383,19 @@ if (!options.name) {
 }
 ```
 
+## Error Messages with Recovery Hints
+
+**Every error message should include a hint showing how to fix or rerun the command.** When a CLI exits with an error, the user (or agent) should be able to copy-paste a corrected command immediately instead of reading `--help`.
+
+```ts
+console.error('Failed to detect local port.')
+console.error('If your server prints the port in an unusual format, specify it explicitly:')
+console.error(`  mycli serve -p <port> -- ${shellQuote(args)}`)
+process.exit(1)
+```
+
+Include the user's original arguments in the suggested command when possible, so the hint is directly copy-pasteable. For timeouts, show how long it waited so the user knows whether to wait longer or try a different approach.
+
 ## Interactive Prompts with @clack/prompts
 
 Use `@clack/prompts` for interactive CLI prompts like `select`, `confirm`, and text input.
@@ -553,3 +648,48 @@ cli
 - Developers can point to `http://localhost:3000` during development without losing their production token
 - Switching servers is just `--api-url` or setting an env var; no re-login needed if the server was used before
 ```
+
+## MCP CLIs (`@goke/mcp`)
+
+Use `addMcpCommands` from `@goke/mcp`. Do not hide `--help` behind a token. Put token steps on a `config` command. Never write `isSetupCmd` or a first-run prompt that blocks no-args.
+
+Use `getMcpUrl` plus `getHeaders` for HTTP Bearer tokens. Use `getMcpTransport` for stdio or any custom transport.
+
+```ts
+await addMcpCommands({
+  cli,
+  getMcpUrl: () => MCP_URL,
+  getHeaders: () => {
+    const token = process.env.TOKEN || loadConfig().token
+    if (!token) return
+    return { Authorization: `Bearer ${token}` }
+  },
+  loadCache: () => loadConfig().cache,
+  saveCache: (cache) => saveConfig({ cache }),
+})
+```
+
+## Writing a Skill for a goke CLI
+
+When creating a SKILL.md for a CLI built with goke, keep it **thin**. The skill is a bridge between the agent and the canonical docs, not a copy of them.
+
+### Structure
+
+1. **Always start with `--help`.** The CLI self-documents commands, options, and examples via goke's help generator. Make agents read it first, in full, every session. Add a "Read the help first" section with `mycli --help` and a rule to never truncate with `head`, `tail`, or `sed -n`.
+
+2. **Point at canonical docs.** If the CLI has a docs site with `llms-full.txt` (e.g. built with Holocron), tell agents to `curl -s https://mycli.dev/llms-full.txt` as the single source of truth. For OSS repos without a docs site, curl the raw README from GitHub: `curl -s https://raw.githubusercontent.com/owner/repo/main/README.md`. Add a "never truncate" rule next to the curl command. Optionally list 3-4 individual page URLs for the most common quick lookups.
+
+3. **Install and auth.** Just the commands, one per line, minimal prose. Start with `which mycli` so agents check before installing. Then `npm install -g mycli`, `mycli auth check`, `mycli auth login`, and `mycli auth set --key` for CI.
+
+4. **Gotchas.** Agent-specific knowledge that is not obvious from `--help` or the docs. Things like browser flows that need user interaction, remote vs local file path restrictions, implicit defaults that cause silent failures, and subscription requirements.
+
+5. **MCP alternative.** If the CLI has an MCP server, include the one-liner install command.
+
+### What NOT to put in the skill
+
+- **Command reference** — already in `--help` output
+- **Workflow examples** — belong in the docs site (quickstart, guides)
+- **Option descriptions** — already in Zod `.describe()` strings that goke renders in help
+- **Output format details** — covered by `--help` and docs
+
+If a section in the skill duplicates content from `--help` or the docs, delete it. The agent will fetch the canonical source.

package/skills/holocron/SKILL.md

@@ -182,6 +182,7 @@ README as the index page:
 
 ```mdx
 ---
+$schema: https://holocron.so/frontmatter.json
 title: My Project
 ---
 
@@ -304,9 +305,42 @@ title: Quickstart
 description: Build and deploy your first Holocron docs site.
 icon: lucide:rocket
 tag: NEW
+prompt: |
+  Write the Quickstart from @/cli/src/create.ts.
+---
+```
+
+### Record the generation prompt
+
+Every documentation page you create must include a **`prompt`** field that
+records the instruction and sources used to generate that page. When editing an
+older page without one, add it when you can identify the real sources. Write the
+original generation recipe, not a maintenance instruction.
+
+Use **`@/path`** for source files and folders from the **repository root**.
+Use `@./path` or `@../path` only when the source sits next to the MDX page.
+Prefix remote sources with **`@https://`**. Bare URLs are not references. Do
+not invent sources, and update the prompt when source locations or page scope
+change.
+
+```yaml
+---
+$schema: https://holocron.so/frontmatter.json
+title: Authentication
+prompt: |
+  Write the authentication guide from @/src/auth/ and
+  @/src/middleware/session.ts.
+  Use @https://github.com/example/project/releases for recent behavior.
+
+  Explain sessions, API keys, and GitHub Actions OIDC.
+  Include a complete TypeScript example for every method.
 ---
 ```
 
+Holocron Maintain extracts these references and reruns the generation prompt
+when a source changes. A folder reference matches changes to any tracked file
+inside that folder.
+
 **Title** should be **50-60 characters** max. It appears in the OG image at large
 font size, in the browser tab, and in search results. Keep it concise and
 descriptive.
@@ -319,6 +353,7 @@ the full title still appears in the page heading, browser tab, and OG image.
 
 ```mdx
 ---
+$schema: https://holocron.so/frontmatter.json
 title: Configuring Authentication Providers
 sidebarTitle: Auth Providers
 ---
@@ -342,6 +377,7 @@ sidebar and often wraps or looks verbose.
 
 ```mdx
 ---
+$schema: https://holocron.so/frontmatter.json
 title: Open-source browser automation for AI agents
 sidebarTitle: Home
 description: Automate any browser with a simple TypeScript API.
@@ -369,6 +405,7 @@ In both modes the content can feel too wide. Use **`maxWidth`** to constrain it:
 
 ```yaml
 ---
+$schema: https://holocron.so/frontmatter.json
 mode: "custom"
 maxWidth: 700
 ---

package/skills/npm-package/SKILL.md

@@ -3,8 +3,9 @@ name: npm-package
 description: >
   Opinionated TypeScript npm package template for ESM packages. Enforces
   src→dist builds with tsc, strict TypeScript defaults, explicit exports, and
-  publish-safe package metadata. Use this when creating or updating any npm
-  package in this repo.
+  publish-safe package metadata. Relative source imports must use .ts or .tsx
+  (never .js); tsc rewrites them via rewriteRelativeImportExtensions. Use this
+  when creating or updating any npm package in this repo.
 version: 0.0.1
 ---
 
@@ -45,19 +46,36 @@ Use this skill when scaffolding or fixing npm packages.
      README at the repository root. Package READMEs don't get read by anyone.
      The root README is the single source of truth for the whole project.
 10. `scripts.build` should be `tsc && chmod +x dist/cli.js` (skip the chmod if
-    the package has no bin). No bundling. Do not delete `dist/` in `build` by
-    default because forcing a clean build on every local build can cause
-    issues. Optionally include running scripts with `tsx` if needed to
-    generate build artifacts.
-11. `prepublishOnly` must always do the cleanup before `build` (optionally run
-    generation before build when required). Always add this script:
+    the package has no bin). No bundling. Optionally include running scripts
+    with `tsx` if needed to generate build artifacts.
+
+    **Never put `rm -rf`, `rimraf`, or any delete in `build`.** `build` runs on
+    every edit, watch loop, and CI test job. Deleting `dist/` there breaks live
+    dev servers that hold it in their module graph (Bun fails with `Failed to
+    load bundled module '<pkg>/dist/index.js'` until restarted) and throws away
+    incremental compilation. A stale file only matters in a published tarball,
+    which `prepublishOnly` already handles.
+
+11. `prepublishOnly` is the **only** place a delete belongs. It keeps a file
+    deleted from `src/` out of the published package:
     ```json
     { "prepublishOnly": "rimraf dist \"*.tsbuildinfo\" && pnpm build" }
     ```
-    This ensures `dist/` is fresh before every `npm publish`, so deleted files
-    do not accidentally stay in the published package. Use `rimraf` here
-    instead of bare shell globs so the script behaves the same in zsh, bash,
-    and Windows shells even when no `.tsbuildinfo` file exists.
+    **Always use `rimraf`, never `rm -rf`.** This holds for every package.json
+    script, not just this one. `rm -rf` is not portable to Windows, and with no
+    `.tsbuildinfo` present zsh aborts `rm -rf dist *.tsbuildinfo` with `no
+    matches found`, so the build after `&&` never runs and you publish a stale
+    `dist/`. `sh` and `bash` only survive because `rm -f` ignores the literal
+    unmatched name. Install `rimraf` as a devDependency; never rely on
+    `npx`/`bunx` at publish time.
+
+    When the package also has a publish guard, chain it first so the guard
+    still runs before anything is deleted:
+    ```json
+    {
+      "prepublishOnly": "node -e \"if (!process.env.CI) process.exit(1)\" && rimraf dist \"*.tsbuildinfo\" && pnpm build"
+    }
+    ```
 
 ## bin field
 
@@ -175,33 +193,33 @@ Use Node ESM-compatible compiler settings:
 
 - Always use "rootDir": "src"
 - Add `"DOM"` to `lib` only when browser globals are needed.
-- Use `.ts` and `.tsx` extensions in source imports. `tsc` rewrites them to
-  `.js` in the emitted `dist/` output automatically via
-  `rewriteRelativeImportExtensions`. This means source code works directly in
-  runtimes like `tsx`, `bun`, and frameworks like Next.js that expect `.ts`
-  extensions, while the published `dist/` has correct `.js` imports that Node.js
-  and other consumers resolve without issues.
-
-  ```ts
-  // source (src/index.ts) — use .ts/.tsx extensions
-  import { helper } from "./utils.ts";
-  import { Button } from "./button.tsx";
-
-  // emitted output (dist/index.js) — tsc rewrites to .js
-  // import { helper } from './utils.js'
-  // import { Button } from './button.js'
-  ```
-
-- Only relative imports are rewritten. Path aliases (`paths` in tsconfig) are
-  not supported by `rewriteRelativeImportExtensions` — this is fine since npm
-  packages should use relative imports anyway.
-- Requires TypeScript 5.7+.
+- Requires TypeScript 5.7+ (`rewriteRelativeImportExtensions`).
 - Install `@types/node` as a dev dependency whenever Node APIs are used.
 - If generation is required, keep generators in `scripts/*.ts` and invoke them
   from package scripts before build/publish.
 
 > IMPORTANT! always use rootDir src. if there are other root level folders that should be type checked you should create other tsconfig.json files inside those folder. DO NOT add other folders inside src or the dist/ will contain dist/src, dist/other-folder. which breaks imports. the tsconfig.json inside these other folders can be minimal, using noEmit true, declaration false. Because usually these folders do not need to be emitted or compiled. just type checked. tests should still be put inside src. other folders can be things like `scripts` or `fixtures`.
 
+## Relative imports
+
+Always write `.ts` or `.tsx` in relative source imports. Never write `.js`.
+
+TypeScript 5.7+ rewrites those extensions to `.js` in `dist/` when
+`rewriteRelativeImportExtensions` is on. Source then runs as-is in `tsx`,
+`bun`, Next.js, and Node type-stripping. Published JS still resolves.
+
+```ts
+import { helper } from "./utils.ts";
+import { Button } from "./button.tsx";
+```
+
+`tsc` emits `./utils.js` and `./button.js`. Only relative paths (`./`, `../`)
+are rewritten. Path aliases, `#` imports, and bare specifiers are not. npm
+packages should use relative imports anyway.
+
+Docs: [rewriteRelativeImportExtensions](https://www.typescriptlang.org/tsconfig/#rewriteRelativeImportExtensions),
+[TypeScript 5.7 path rewriting](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-7.html#path-rewriting-for-relative-paths).
+
 ## Preferred exports template
 
 ```json
@@ -355,7 +373,7 @@ Source of truth: [TypeScript Modules Reference — package.json "imports" and se
 
 ## tests location
 
-test files should be close with the associated source files. for example if you have an utils.ts file you will create utils.test.ts file next to it. with tests, importing from utils. preferred testing framework is vitest (or bun if project already using `bun test` or depends on bun APIs, rare)
+test files should be close with the associated source files. for example if you have an utils.ts file you will create utils.test.ts file next to it. with tests, importing from `./utils.ts`. preferred testing framework is vitest (or bun if project already using `bun test` or depends on bun APIs, rare)
 
 ## Agent skill
 
@@ -665,8 +683,10 @@ To make peer dependencies optional, add `peerDependenciesMeta`:
 
 ## common mistakes
 
+- never write `.js` in relative source imports. use `.ts` or `.tsx`. tsc rewrites them in `dist/`
 - if you need to use zod always use latest version
 - always install packages as dev dependencies if used only for scripts, testing or types only
-- if the package uses `rimraf` in scripts, install it as a dev dependency instead of relying on platform-specific shell behavior
+- never use `rm -rf` in a package.json script. always use `rimraf`, installed as a dev dependency. `rm -rf` is not portable to Windows and zsh aborts the whole `&&` chain when a glob matches nothing
+- never delete anything in `build`. deletes belong in `prepublishOnly` only
 - never use em-dashes (—) or dashes as inline separators (like `word - word`) in README or documentation. instead restructure the sentence: use periods to split into two sentences, colons, commas, or parentheses
 - never add badge images (shields.io, etc.) or any images you don't have locally in the repo. don't invent image URLs

package/skills/profano/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: profano
-description: CLI tool to analyze V8 .cpuprofile files and Chrome Performance traces and print top functions by self-time or total-time in the terminal. ALWAYS load this skill when CPU profiling JavaScript or TypeScript programs (Node, Vitest, Bun, Chrome DevTools exports) — it shows how to generate .cpuprofile files and how to inspect them from the terminal without opening Chrome DevTools.
+repo: remorses/profano
+description: >
+  CLI tool to analyze V8 .cpuprofile files and Chrome Performance traces and
+  print top functions by self-time or total-time in the terminal. ALWAYS load
+  this skill when CPU profiling JavaScript or TypeScript programs (Node, Vitest,
+  Bun, Chrome DevTools exports, Cloudflare Workers startup or request CPU).
+  It shows how to generate .cpuprofile files and how to inspect them from the
+  terminal without opening Chrome DevTools.
 ---
 
 # profano
@@ -13,6 +20,14 @@ Every time you use profano, you MUST fetch the latest README and read it in full
 curl -s https://raw.githubusercontent.com/remorses/profano/main/README.md  # NEVER pipe to head/tail, read in full
 ```
 
-The README covers generating `.cpuprofile` files (Node, Vitest, Bun, Chrome Performance traces, browser pages via playwriter, React component profiling), all CLI options, and how to read the output columns.
+The README covers generating `.cpuprofile` files (Node, Vitest, Bun, **Cloudflare Workers** startup and request, Chrome Performance traces, browser pages via playwriter, React component profiling), all CLI options, and how to read the output columns.
 
 Chrome Performance **Save profile** writes a trace JSON. Pass it to `profano Trace.json` directly. Do not convert it first.
+
+## Cloudflare Workers
+
+A Worker needs **two** profiles. Startup is `wrangler check startup`. A request is `wrangler dev --inspector-port 9230` plus `profano workers request <url>`. `wrangler tail` `cpuTime` is only a total. Never paste a one-off CDP script; use the CLI command.
+
+Do **not** copy `dist/` to a temp folder unless `wrangler check startup` errors about two wrangler configs with different base paths. That copy is an exception, not the default.
+
+Trust the **function mix** in a local profile. Do not treat local milliseconds as Cloudflare CPU.

package/skills/spiceflow/SKILL.md

@@ -64,6 +64,28 @@ Always import and use `Link` from `spiceflow/react` for navigational links in Sp
 
 **`Link` auto-prepends the Vite `base` path.** Never manually prepend the base path to `Link` href values. `<Link href="/dashboard" />` automatically renders as `<a href="/my-app/dashboard">` when the Vite base is `/my-app/`. Manually prepending causes double-prefixing. This only applies to `Link`; raw `fetch()` calls, `Response.redirect()`, and other non-Link URL construction still need manual base path handling.
 
+## `<Head>` is server-only
+
+`<Head>` renders nothing. It records its children during the RSC render, and spiceflow reads them back to build the document head. A `'use client'` module never runs in that render, so a `<Head>` inside one contributes nothing at all.
+
+Always put `<Head>` in the `.page()` or `.layout()` handler, never in a `'use client'` component:
+
+```tsx
+.page('/', async () => {
+  return (
+    <>
+      <Head>
+        <Head.Title>Dashboard | My App</Head.Title>
+        <Head.Meta name="description" content="Your account overview." />
+      </Head>
+      <InteractiveDashboard />
+    </>
+  )
+})
+```
+
+Importing `Head` into a `'use client'` module fails the build, and rendering one throws. To change the title from the browser after load, set `document.title` in an effect instead.
+
 ## OpenTelemetry instrumentation
 
 Spiceflow supports automatic route instrumentation when you pass an OpenTelemetry-compatible tracer to the constructor:
@@ -150,14 +172,28 @@ export async function deleteProject(id: string) {
 
 Never assume a server action is only reachable through your own UI. Treat every server action like a public API endpoint.
 
+## Always `throw redirect(...)`, never `return redirect(...)`
+
+Both work at runtime, but `throw` is safer: it prevents the redirect from contributing to the handler's inferred return type, avoiding circular TS7022 errors with `SpiceflowRegister`. It also short-circuits the handler immediately, making control flow explicit. This applies to `.page()`, `.layout()`, `.loader()`, `.get()`, `.post()`, server actions, and middleware.
+
 ## Never `router.refresh()` after server actions
 
 Successful server actions re-run matching loaders and reconcile the current page. Do not call `router.refresh()` afterward. Use it only when data changes outside a server action.
 
 `router.refresh()` is fire-and-forget. Do not await a custom refresh or navigation commit helper inside a React form action because the transition can deadlock.
 
-## Router usage in app entry handlers
+## Circular types in app entry handlers
+
+Circular TypeScript errors (TS7022) happen when any API that reads from `SpiceflowRegister` (i.e. `typeof app`) appears in a handler's **return value**. This affects `router.href()`, `router.getLoaderData()`, `createSpiceflowFetch()`, `useLoaderData()`, `Link`, and any future API typed against the registered app.
+
+**Safe** (no circular):
+- Any registered API in **JSX children, attributes, or event handlers** (`.page()`, `.layout()`)
+- `throw` expressions: `throw redirect(router.href(...))` in any handler
+- Any registered API in **client components, server components, and separate files**
 
-`router` from `spiceflow/react` is typed from the globally registered `typeof app`. Do **not** use `router` inside `.loader()`, `.get()`, `.post()`, or `.route()` handlers in the same file that initializes `export const app = new Spiceflow()`. Those handlers feed return types back into `typeof app` through loader data or typed API responses, so `router.href()` can create recursive circular TypeScript errors such as TS7022.
+**Circular** (causes TS7022):
+- Any registered API in a `.loader()` **return value**
+- Any registered API in a `.get()` or `.post()` **return value**
+- `return redirect(router.href(...))` inside `.page()` on paths **with loaders**
 
-`router.href()` is okay in components, other modules, and for JSX links inside `.page()` / `.layout()` handlers because rendered page/layout JSX is not part of the app metadata. If a loader-heavy app still hits a circular `typeof app` error from page/layout usage, move the link UI into a component module. Context `redirect()` intentionally accepts a plain `string`; do not pass `router.href()` into redirects inside app-entry handlers because redirect return values participate in handler return inference and can reintroduce the cycle.
+The rule: circular happens when a `RegisteredApp`-typed expression reaches a **return value** that feeds `typeof app` inference. JSX, `throw`, and event handler callbacks don't feed return types. See `spiceflow/src/type-repros/registered-app-circular.test.ts` for the exact boundaries.

package/skills/strada/SKILL.md

@@ -98,6 +98,16 @@ Rules to never break:
 - **Browser project id needs a public prefix** or the bundler will strip it.
 - In **RSC / server-rendered** apps, run browser `initStrada()` from a side-effect-only `"use client"` module rendered once in the root layout (a component that returns `null`). A bare `import` runs on the server and gets tree-shaken from the client bundle. See `website/src/docs/quickstart.mdx` for the pattern.
 - If the framework exposes an OTel tracer hook (e.g. Spiceflow `new Spiceflow({ tracer })`), pass `trace.getTracer("my-app")` from the SDK so request spans flow to the same project.
+- In **Cloudflare Workers**, import `env` from `cloudflare:workers` and call
+  `initStrada()` at module scope. Never initialize in per-request middleware.
+  See the Cloudflare Workers section of `website/src/sdk/README.mdx`.
+- **Email and user id belong on errors, logs, and product events.** That is how
+  you open an issue and see who hit it. Use `strataBetterAuth()` (default
+  `includeUserDetails: true`), `identifyUser()`, or `tags` / event properties
+  with `user.id` and `user.email`. Do not strip them.
+- Never attach API keys, prompts, or raw user content (the text they typed)
+  to tags or events. Use stable route, handler, service, and environment
+  identifiers for those.
 
 ## Terminal UI
 
@@ -233,4 +243,33 @@ FROM otel_traces
 WHERE Duration > 1000000000
 ORDER BY Duration DESC
 LIMIT 20
+
+-- HTTP route performance: top routes by RPS and latency
+-- ParentSpanId = '' filters to root spans (one per HTTP request)
+-- Duration is nanoseconds, divide by 1e6 for milliseconds
+SELECT
+  SpanName AS path,
+  count() AS total_requests,
+  round(count() / 3600, 2) AS rps,
+  round(avg(Duration) / 1e6, 1) AS avg_ms,
+  round(quantile(0.95)(Duration) / 1e6, 1) AS p95_ms,
+  round(max(Duration) / 1e6, 1) AS max_ms
+FROM otel_traces
+WHERE Timestamp >= now() - INTERVAL 1 HOUR
+  AND ParentSpanId = ''
+GROUP BY path
+ORDER BY total_requests DESC
+LIMIT 30
+
+-- Per-minute traffic pattern for a specific route
+SELECT
+  toStartOfMinute(Timestamp) AS minute,
+  count() AS requests
+FROM otel_traces
+WHERE Timestamp >= now() - INTERVAL 1 HOUR
+  AND ParentSpanId = ''
+  AND SpanName = 'POST /api/my-route'
+GROUP BY minute
+ORDER BY minute DESC
+LIMIT 60
 ```

package/skills/zele/SKILL.md

@@ -60,3 +60,22 @@ The README and `zele --help` output are the source of truth for commands, option
    zele mail watch --filter "is:unread from:bob@example.com subject:Re:Question" --timeout 600
    ```
    If the matched email wasn't the expected one, call `zele mail watch` again with a more specific filter. Exit code 0 means a match was found, exit code 1 means timeout.
+8. **Check reply recipients before sending** with `zele mail reply <thread-id> --dry-run`. Recipients are inferred from the thread, not from the sender of the last message, so a thread whose last message you sent still replies to the other person. If a reply would only reach the account's own address, zele refuses to send:
+   ```bash
+   # see to / cc / subject / In-Reply-To without sending
+   zele mail reply <thread-id> --dry-run
+
+   # override the inferred recipient
+   zele mail reply <thread-id> --to paul@acme.com --body "..."
+
+   # deliberately reply to yourself (normally refused)
+   zele mail reply <thread-id> --allow-self --body "..."
+   ```
+    Never work around a `SelfRecipientError` by switching to `zele mail send`; pass `--to` to `zele mail reply` instead, so threading headers stay correct.
+9. **Read a thread before replying.** `zele mail reply` and `zele mail send --thread-id` fail with `UnseenLatestError` unless `zele mail read <thread-id>` already showed the live last message. `mail watch` and `mail list` do **not** count. If a new reply arrives after you read, read again before sending:
+    ```bash
+    zele mail read <thread-id>
+    zele mail reply <thread-id> --body "..."
+    ```
+    Never pass `--force` to skip this unless the user explicitly asks to send without reading.
+10. **Send into an existing thread** with `zele mail send --thread-id <thread-id>` when you need full control of recipients and subject but still want correct `In-Reply-To`/`References` headers. Recipients and subject are inferred from the thread when omitted. The same read-before-reply rule applies.