kimaki 0.26.0 → 0.28.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

@@ -4,7 +4,8 @@ repo: https://github.com/remorses/holocron
 description: >
   Holocron is a Mintlify-compatible docs site generator and Vite plugin.
   Use this skill when creating, migrating, customizing, or deploying a
-  Holocron documentation site.
+  Holocron documentation site. Also load when writing index.mdx, page
+  titles, hideTitle, Above heroes, or homepage SEO for Google brand ranking.
 ---
 
 # Holocron
@@ -182,6 +183,7 @@ README as the index page:
 
 ```mdx
 ---
+$schema: https://holocron.so/frontmatter.json
 title: My Project
 ---
 
@@ -304,9 +306,56 @@ 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.
+
+### Migrating an existing docs site
+
+When moving a docs site to Holocron, write each `prompt` as if the page was
+authored from scratch. Keep it a short summary of what the page documents.
+
+Do not mention migration, recreation, or the old docs URL. Do not add
+`@https://old-site/...` references. The source site is going away after the
+move unless the user says otherwise.
+
+```yaml
+prompt: |
+  Document connecting the first integration, role access, and chat validation.
+```
+
 **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 +368,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
 ---
@@ -328,35 +378,121 @@ sidebarTitle: Auth Providers
 below the title and in search engine snippets. Write a single sentence that
 summarizes the page content. Longer descriptions get truncated with an ellipsis.
 
-## Page titles (MUST follow)
+## Page titles and SEO (MUST follow)
+
+Google title links and snippets come from on-page title, H1, and description.
+See [title links](https://developers.google.com/search/docs/appearance/title-link)
+and [snippets](https://developers.google.com/search/docs/appearance/snippet).
+
+Holocron already appends the site name. `buildPageTitle` renders
+`{page title} — {site name}` unless `title` already starts with the site name.
+**Do not put the site name in `title` or in the H1.** That doubles the brand
+(`Kimaki: … — Kimaki`). Write the ranking keywords only. Let Holocron add
+` — {site name}`.
 
-Holocron renders the browser `<title>` as `{page title} — {site name}`. Two
-frontmatter fields control what appears where:
+Two frontmatter fields:
 
-- **`title`** — browser tab, Google results, OG image, page heading. Write for SEO.
-- **`sidebarTitle`** — sidebar navigation only. Write for scannability (short label).
+- **`title`** — browser tab, Google title link, OG image, and the injected H1. Write for SEO. Put the keywords this page should rank for.
+- **`sidebarTitle`** — sidebar only. Short label, under 30 characters.
 
-**Always set both.** `title` is the full descriptive phrase; `sidebarTitle` is
-the short sidebar label. Without `sidebarTitle`, the full title shows in the
-sidebar and often wraps or looks verbose.
+**Always set both.** Without `sidebarTitle`, the long SEO title wraps in the 230px sidebar.
+
+**Always quote frontmatter strings.** YAML treats `:` as a map. `title: Kimaki: AI agents` is nested YAML. Holocron then drops all frontmatter, and the browser title becomes the first body heading. Quote `title` and `description`. Holocron warns when an unquoted value contains `:`, and when a parsed key contains a space and `:`.
 
 ```mdx
 ---
-title: Open-source browser automation for AI agents
+$schema: https://holocron.so/frontmatter.json
+title: "Open-source browser automation"
 sidebarTitle: Home
-description: Automate any browser with a simple TypeScript API.
+description: "Automate any browser with a TypeScript API. Control Chrome from a CLI or agent."
 ---
 ```
 
-Browser tab: `Open-source browser automation for AI agents — Playwriter`
+Browser tab: `Open-source browser automation — Playwriter`
+Injected H1: `Open-source browser automation`
 Sidebar: `Home`
 
-**Rules:**
+On most pages Holocron injects `title` as the only H1, so **title and H1 are the same**. Keep it that way. Do not add another `#` or `<h1>` in the body.
+
+**Title rules:**
+
+- **Put ranking keywords in `title`.** The homepage title is the most important. Docs pages use the topic keywords (`Subscriptions`, `Worktrees`), not `Introduction` or `Overview`.
+- **Never start `title` with the site name.** Holocron already appends ` — {site name}`.
+- **Never set `title` identical to the site name.** A title of `Playwriter` becomes `Playwriter — Playwriter`.
+- **Every `title` MUST be unique, descriptive, and concise.** Google truncates long titles. Avoid keyword stuffing and boilerplate that only changes one word.
+- **`index.mdx` MUST use `sidebarTitle: Home`** (or `Overview`). See Homepage SEO below.
+
+**H1 rules:**
+
+- **One H1 per page.** It must contain the same ranking keywords as `title`. Prefer the exact `title` text. Holocron does this automatically when it injects the title.
+- Google uses the first prominent H1 as a title-link source. Extra H1s with the same weight can steal the tab title (`Quick Start — Site`). Heading count is not a ranking penalty. A clear main title is.
+
+**Description rules:**
+
+`description` becomes `<meta name="description">`. Google may use it as the snippet when it describes the page better than on-page text.
+
+- **Unique per page.** Site-wide copy on every page is useless in search results.
+- **Summarize this page**, in one or two sentences. Not a keyword list.
+- **Include ranking keywords naturally.** Do not stuff. Do not repeat the site name just because the title suffix already has it. The homepage may name the product once if that is the summary.
+- **Be specific.** Length has no hard cap. Google truncates to the device width. Aim for a short pitch, about 120 to 160 characters.
+- Quote the YAML string.
+
+```yaml
+description: "Run AI coding agents from Discord. Each channel is a project, each thread is a session."
+```
+
+## Homepage SEO
+
+The homepage title is the strongest brand query signal. Put the keywords people search in `title` and H1. Let Holocron append the site name.
+
+```mdx
+---
+$schema: https://holocron.so/frontmatter.json
+title: "AI coding agents from Discord"
+sidebarTitle: Home
+description: "Run AI coding agents from Discord. Each channel is a project, each thread is a session."
+---
+```
+
+Browser tab: `AI coding agents from Discord — Kimaki`
+H1: `AI coding agents from Discord`
 
-- **Never set `title` identical to the site name.** `Playwriter — Playwriter` is redundant.
-- **Every `title` MUST be descriptive, not a generic label.** `Introduction`, `Getting Started`, `Overview` say nothing in a browser tab. Write what the page covers.
-- **Every `title` MUST be unique across the site.**
-- **`index.mdx` MUST use `sidebarTitle: Home`** (or `Overview`) and a descriptive `title`.
+**One H1, same keywords as `title`.** Holocron injects that H1 unless the page has `<Above>` or `hideTitle: true`. A custom hero that also renders `<h1>` next to an injected title creates two H1s.
+
+**If the page has `<Above>`, that hero owns the H1.** Holocron skips the injected title. Set the hero H1 to the same text as `title`. Do not put the site name in the hero H1. Never write `#` or `<h1>` in the MDX body below it. The first body section must be `##`. Extra H1s are demoted to H2.
+
+```mdx
+---
+title: "AI coding agents from Discord"
+sidebarTitle: Home
+description: "Run AI coding agents from Discord. Each channel is a project, each thread is a session."
+---
+
+<Above>
+  <HeroSection />
+</Above>
+```
+
+```tsx
+<h1>
+  <span>AI coding agents</span>
+  <span>from Discord.</span>
+</h1>
+```
+
+If there is no custom hero, do **not** set `hideTitle`. Let Holocron inject `title` as the only H1.
+
+**Do not make `/` a clone of GitHub.** Importing `README.md` under the hero is fine. The homepage still needs its own title, H1, and description. If `/` is the same text as GitHub, Google prefers GitHub plus a unique inner docs page.
+
+A **logo link to `/`** is weak. Fix title, H1, and description first.
+
+After deploy, fetch the live HTML and check:
+
+```bash
+curl -sL -A 'Mozilla/5.0 (compatible; Googlebot/2.1)' 'https://example.com/' -o /tmp/home.html
+```
+
+Confirm **exactly one `<h1>`**, that H1 text matches `title`, and `<title>` is `{title} — {site name}` with the site name only at the end. Rank will not move until Google recrawls.
 
 ## Page modes — hiding sidebars
 
@@ -369,6 +505,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.