kimaki 0.26.0 → 0.28.0

package/skills/bump-holocron-consumers/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: bump-holocron-consumers
+repo: remorses/holocron
+description: >
+  Bump @holocron.so/vite and @holocron.so/cli in Tommy's other GitHub repos.
+  Use when asked to update holocron versions across remorses consumer sites,
+  find repos that depend on holocron.so/vite or holocron.so/cli, or sync
+  docs-site packages after a holocron release.
+---
+
+# Bump Holocron in consumer repos
+
+After a holocron npm release, bump **@holocron.so/vite** and **@holocron.so/cli** in Tommy's other repos. Do this on **local clones**. Do not clone missing repos unless asked. Do not commit unless asked.
+
+Load the **pnpm** skill before running any `pnpm update`.
+
+## 1. Read the latest versions
+
+```bash
+npm view @holocron.so/vite version
+npm view @holocron.so/cli version
+```
+
+Confirm they match `vite/package.json` and `cli/package.json` in this repo. Never guess.
+
+## 2. Search GitHub
+
+```bash
+gh search code '@holocron.so/vite' --owner remorses --filename package.json --limit 100 --json repository,path,textMatches
+
+gh search code '@holocron.so/cli' --owner remorses --filename package.json --limit 50 --json repository,path,textMatches
+```
+
+Read the **full** JSON. Never pipe to `head` or `tail`.
+
+Treat a hit as a real dependency only when it is in `dependencies` or `devDependencies`. Skip `packageExtensions`, the holocron package's own `"name"` field, and `workspace:^`.
+
+## 3. Skip these
+
+- **remorses/holocron** itself (`workspace:^`)
+- Specifiers already set to **`latest`** (template, throwaway test sites)
+- Empty directories and non-git folders
+- Repos not on this machine, unless the user asks to clone them
+
+Typical `latest` skips: `holocron-template`, `context-dev-docs`, `palmier-pro-docs`, `example-holocron-again`, `holocron-testing-again`, `holocron-example-againagain`, `holocron-test-antoher`, `holocron-docs-new-again`, `holocron-test-2`.
+
+## 4. Map GitHub repo to a local folder
+
+Search these roots, in order:
+
+1. `/Users/morse/Documents/GitHub/<name>`
+2. `/Users/morse/Documents/<name>`
+3. The alias table below
+4. `git remote -v` on nearby folders when the folder name differs from the GitHub name
+
+```bash
+for d in /Users/morse/Documents/GitHub/*/ /Users/morse/Documents/*/; do
+  url=$(git -C "$d" remote get-url origin 2>/dev/null) || continue
+  case "$url" in
+    *remorses/kimaki*) echo "kimaki -> $d" ;;
+    *remorses/gpuix*) echo "gpuix -> $d" ;;
+    *remorses/opensession*) echo "opensession -> $d" ;;
+    *remorses/traforo*) echo "traforo -> $d" ;;
+    *remorses/spiceflow*) echo "spiceflow -> $d" ;;
+  esac
+done
+```
+
+**Known aliases** (verify `origin` if a path is missing):
+
+| GitHub | Local path | Notes |
+|---|---|---|
+| remorses/kimaki | `/Users/morse/Documents/GitHub/kimakivoice` | `/GitHub/kimaki` is an empty dir. Dep lives in `website/` |
+| remorses/gpuix | `/Users/morse/Documents/GitHub/gpuixlocal` | `website/` is **not** in bun workspaces. Update from that folder |
+| remorses/opensession | `/Users/morse/Documents/GitHub/opensessions` | vite + cli |
+| remorses/traforo | `/Users/morse/Documents/GitHub/kimakivoice/traforo` | git submodule. kimaki workspace also includes `./traforo/website` |
+| remorses/spiceflow | `/Users/morse/Documents/spiceflow` | Not under GitHub/. Local HEAD can lag origin and omit `website/` |
+| remorses/playwriter | `/Users/morse/Documents/GitHub/playwriter` | `website/` |
+| remorses/termcast | `/Users/morse/Documents/GitHub/termcast` | `website/` |
+| remorses/egaki | `/Users/morse/Documents/GitHub/egaki` | `website/` |
+| remorses/sigillo | `/Users/morse/Documents/GitHub/sigillo` | Dep is in **`app/`**, not website/ |
+| remorses/subrouter | `/Users/morse/Documents/GitHub/subrouter` | Prefer this clone over `kimakivoice/subrouter` |
+| remorses/strada | `/Users/morse/Documents/GitHub/strada` | `website/` |
+| remorses/notaku | `/Users/morse/Documents/GitHub/notaku` | `website/` |
+
+Repos often **not** on disk: `akarso-private`, `dmcafreemusic`. Skip them. Report them.
+
+If `website/` is missing locally, do not `git pull` to create it unless asked. Report that the clone is behind.
+
+## 5. Update
+
+Pick the package manager from the lockfile at the **repo root** (`pnpm-lock.yaml` vs `bun.lock`).
+
+**pnpm workspace** (run at repo root):
+
+```bash
+pnpm update -r --latest @holocron.so/vite
+pnpm update -r --latest @holocron.so/cli
+```
+
+**bun**, from the folder whose `package.json` lists the dep (often `website/`):
+
+```bash
+bun update --latest @holocron.so/vite
+bun update --latest @holocron.so/cli
+```
+
+Never hand-edit `package.json` to bump a version. Never use `pnpm add` to update. Never add `pnpm.overrides`.
+
+If the dep folder is **not** a workspace member (gpuix `website/`), run the update **inside that folder**, not at the repo root.
+
+Keep the existing specifier style. Exact `0.33.0` stays exact. Caret `^0.30.0` stays caret.
+
+## 6. Same-day publish / minimum release age
+
+Global pnpm `minimumReleaseAge` is **1440** minutes. `@holocron.so/*` is already on the exclude list. If install still fails with:
+
+```text
+ERR_PNPM_NO_MATCHING_VERSION  No matching version found for @holocron.so/cli@^X.Y.Z
+The latest release of @holocron.so/cli is "X.Y.Z".
+```
+
+the project is pinned to an older pnpm via `packageManager` (notaku uses `pnpm@10.16.1`) and the exclude glob is ignored. Retry with:
+
+```bash
+npm_config_minimum_release_age=0 pnpm --filter website update @holocron.so/vite@<latest>
+```
+
+Do not write `minimum-release-age=0` into the consumer's `.npmrc`.
+
+## 7. Verify, then stop
+
+Read each touched `package.json` and confirm the specifier is the latest. Then stop. Do not commit. Do not push. Do not deploy.
+
+If the user asks to commit, commit **only** the holocron package.json + lockfile hunks in each consumer repo. Use that repo's own git. Never commit unrelated dirty files.
+
+When a new GitHub-to-folder alias is discovered, add it to the table in this skill.

package/skills/critique/SKILL.md

@@ -74,17 +74,17 @@ critique hunks list
 critique hunks list --filter "src/**/*.ts"
 
 # Stage specific hunks by ID
-critique hunks add 'src/main.ts:@-10,6+10,7'
-critique hunks add 'src/main.ts:@-10,6+10,7' 'src/utils.ts:@-5,3+5,4'
+critique hunks add 'src/main.ts:@a1b2c3d4e5f6'
+critique hunks add 'src/main.ts:@a1b2c3d4e5f6' 'src/utils.ts:@f6e5d4c3b2a1'
 ```
 
-Hunk ID format: `file:@-oldStart,oldLines+newStart,newLines` — derived from the `@@` diff header, stable across runs.
+Hunk ID format: `file:@<hash>` or `file:@<hash>.1`. The hash is from added and removed lines, so unrelated edits above or below the hunk do not change the ID. Duplicate payloads in the same file get `.1`, `.2`. Old `file:@-oldStart,...` IDs are no longer accepted. `hunks list` still prints the `@@` header under each ID.
 
 **Typical workflow:**
 
 ```bash
 critique hunks list                          # see all unstaged hunks
-critique hunks add 'file:@-10,6+10,7'       # stage only your hunks
+critique hunks add 'file:@a1b2c3d4e5f6'     # stage only your hunks
 git commit -m "your changes"                 # commit separately
 ```
 

package/skills/errore/SKILL.md

@@ -1,17 +1,25 @@
 ---
 name: errore
-description: >
-  errore is Go-style error handling for TypeScript: return errors instead of throwing them.
-  Instead of Go's two-value tuple (val, err), functions return a single Error | T union.
-  Instead of checking err != nil, you check instanceof Error. TypeScript narrows the type
-  automatically — forget to check and your code won't compile. No wrapper types, no Result
-  monads, just unions and instanceof. The errore npm package provides helper utilities
-  (createTaggedError, tryAsync, matchError, findCause, partition) but the core pattern is
-  zero-dependency. Benefits: every error is visible in the return type, callers can't forget
-  to handle errors, flat control flow with early returns instead of nested try-catch, and
-  errors carry typed properties with cause chains for debugging. ALWAYS read this skill when
-  a repo uses the errore "errors as values" convention (errore.org). ALWAYS use errore for
-  new TypeScript projects.
+description: |
+  Go-style error handling for TypeScript: return errors as a plain `Error | T` union
+  instead of throwing. `instanceof Error` narrows the type — no Result wrapper. The gist:
+
+  ```ts
+  class NotFoundError extends errore.createTaggedError({
+    name: 'NotFoundError',
+    message: 'User $id not found',
+  }) {}
+
+  async function getUser(id: string) {
+    const user = await db.findUser(id).catch((e) => new DbError({ cause: e }))
+    if (user instanceof Error) return user // early return, like Go's err != nil
+    if (!user) return new NotFoundError({ id })
+    return user // caller narrows the same way
+  }
+  ```
+
+  ALWAYS read this skill when a repo uses the errore convention (errore.org).
+  ALWAYS use errore for new TypeScript projects.
 version: 0.11.0
 ---
 
@@ -27,72 +35,42 @@ console.log(user.name) // TypeScript knows: User
 
 ## Rules
 
+Each rule is one line; the details live once in the pattern sections below.
+
 1. Always `import * as errore from 'errore'` — namespace import, never destructure
 2. Never throw for expected failures — return errors as values
 3. Never return `unknown | Error` — the union collapses to `unknown`, breaks narrowing. Common trap: `res.json()` returns `unknown`, so `return await res.json()` makes the return type `MyError | unknown` → `unknown`. Fix: cast with `as` → `return (await res.json()) as User`
-4. Avoid `try-catch` for control flow — use `.catch()` for async boundaries, `errore.try` for sync boundaries
-5. Use `createTaggedError` for domain errors — gives you `_tag`, typed properties, `$variable` interpolation, `cause`, `findCause`, `toJSON`, and fingerprinting
-6. Let TypeScript infer return types — only add explicit annotations when they improve readability (complex unions, public APIs) or when inference produces a wider type than intended
-7. Use `cause` to wrap errors — `new MyError({ ..., cause: originalError })`
-8. Use `| null` for optional values, not `| undefined` — three-way narrowing: `instanceof Error`, `=== null`, then value
-9. Use `const` + expressions, never `let` + try-catch — ternaries, IIFEs, `instanceof Error`
-10. Always handle errors inside `if` branches with early exits, keep the happy path at root — like Go's `if err != nil { return err }`, check the error, exit (return/continue/break), and continue the success path at the top indentation level. This makes the happy path readable top-to-bottom with minimal nesting
-11. Always include `Error` handler in `matchError` — required fallback for plain Error instances
-12. Use `.catch()` for async boundaries, `errore.try` for sync boundaries — only at the lowest call stack level where you interact with uncontrolled dependencies (third-party libs, `JSON.parse`, `fetch`, file I/O). Your own code should return errors as values, not throw.
-13. Always wrap `.catch()` in a tagged domain error — `.catch((e) => new MyError({ cause: e }))`. The `.catch()` callback receives `any`, but wrapping in a typed error gives the union a concrete type. Never use `.catch((e) => e as Error)` — always wrap.
-14. Always pass `cause` in `.catch()` callbacks — `.catch((e) => new MyError({ cause: e }))`, never `.catch(() => new MyError())`. Without `cause`, the original error is lost and `isAbortError` can't walk the chain to detect aborts. The `cause` preserves the full error chain for debugging and abort detection.
-15. Always prefer `errore.try` over `errore.tryFn` — they are the same function, but `errore.try` is the canonical name
-16. Use `errore.isAbortError` to detect abort errors — never check `error.name === 'AbortError'` manually, because tagged abort errors have their tag as `.name`
-17. Custom abort errors MUST extend `errore.AbortError` — so `isAbortError` detects them in the cause chain even when wrapped by `.catch()`
-18. Keep abort checks flat — check `isAbortError(result)` first as its own early return, then `result instanceof Error` as a separate early return. Never nest `isAbortError` inside `instanceof Error`:
+4. Convert exceptions to values only at boundaries — `.catch()` for async, `errore.try` for sync (see [Boundaries](#boundaries-catch-for-async-erroretry-for-sync)). Never `try-catch` for control flow
+5. Always wrap boundary catches in a tagged domain error with `cause` — `.catch((e) => new MyError({ cause: e }))`. Never `.catch((e) => e as Error)`, never omit `cause` (it preserves the chain for debugging and abort detection)
+6. Use `createTaggedError` for domain errors (see [Defining Errors](#defining-errors)); use `cause` to wrap errors
+7. Use `| null` for optional values, not `| undefined` — three-way narrowing: `instanceof Error`, `=== null`, then value
+8. Use `const` + expressions, never `let` + try-catch (see [Expressions over Statements](#expressions-over-statements))
+9. Handle errors inside `if` branches with early exits, keep the happy path at root indentation (see [Flat Control Flow](#flat-control-flow))
+10. Always include `Error` handler in `matchError` — required fallback for plain Error instances
+11. Always prefer `errore.try` over `errore.tryFn` — same function, `errore.try` is the canonical name
+12. Abort: custom abort errors MUST extend `errore.AbortError`, detect with `errore.isAbortError` (never `error.name === 'AbortError'`), and check `isAbortError(result)` as its own early return before `instanceof Error` (see [Abort & Cancellation](#abort--cancellation))
+13. Don't reassign after error early returns — TypeScript narrows the original variable; a `const narrowed = result` alias is redundant
+14. Write `instanceof Error` early returns on one line — `if (result instanceof Error) return result`. Use a `{` block only when the branch has more than one statement
+15. Always log errors that are not propagated — when an error branch doesn't `return` or `throw` (loops with `continue`, fallback branches, fire-and-forget calls), add a `console.warn`/`console.error` so the failure leaves a trace. Propagated errors don't need logging — the caller handles them:
 
     ```ts
-    const result = await fetchData({ signal }).catch(
-      (e) => new FetchError({ cause: e }),
+    const emailResult = await sendEmail(user.email).catch(
+      (e) => new EmailError({ email: user.email, cause: e }),
     )
-    if (errore.isAbortError(result)) return 'Request timed out'
-    if (result instanceof Error) return `Failed: ${result.message}`
-    ```
-
-19. Don't reassign after error early returns — TypeScript narrows the original variable automatically after `instanceof Error` checks return. A `const narrowed = result` alias is redundant:
-
-    ```ts
-    const result = await fetch(url).catch((e) => new FetchError({ cause: e }))
-    if (result instanceof Error) return `Failed: ${result.message}`
-    await result.json() // TS knows result is Response here
-    ```
-
-20. Always write `instanceof Error` early returns on one line — no `{` block, no extra lines. `if (x instanceof Error) return x` keeps the happy path readable and reduces visual noise. Only use a block when the branch has more than one statement:
-
-    ```ts
-    // good — one line, no block
-    if (result instanceof Error) return result
-    if (user instanceof Error) return user
-
-    // bad — block for a single return adds noise
-    if (result instanceof Error) {
-      return result
+    if (emailResult instanceof Error) {
+      console.warn('Failed to send email:', emailResult.message)
     }
     ```
 
-21. Always log errors that are not propagated — when an error branch doesn't `return` or `throw` the error (i.e. the error is intentionally swallowed), add a `console.warn` or `console.error` so failures are visible during debugging. Silent error swallowing makes bugs invisible:
+16. Always hint a **solution** in user-facing error messages — include a login URL, CLI command, or missing flag so agents and users can self-correct instead of guessing. Applies to HTTP responses and CLI output; internal errors (DB failures, parse errors) can stay technical:
 
     ```ts
-    // BAD: error silently ignored — if sync fails you'll never know
-    const result = await syncToCloud(data)
-    if (result instanceof Error) {
-      // nothing here — silent failure
-    }
-
-    // GOOD: log before continuing — error is visible in logs
-    const result = await syncToCloud(data)
-    if (result instanceof Error) {
-      console.warn('Cloud sync failed:', result.message)
-    }
+    class UnauthorizedError extends errore.createTaggedError({
+      name: 'UnauthorizedError',
+      message: 'Not logged in. Sign in at $loginUrl or run: $loginCommand',
+    }) {}
     ```
 
-    > Propagated errors (`return error`) don't need logging — the caller handles them. But errors you choose to ignore must leave a trace. This applies to loops with `continue`, fallback branches, and any path where the error is intentionally dropped.
-
 ## TypeScript Rules
 
 - **Object args over positional** — `({id, retries})` not `(id, retries)` for functions with 2+ params
@@ -103,24 +81,7 @@ console.log(user.name) // TypeScript knows: User
 - **No uninitialized `let`** — use IIFE with returns instead of `let x; if (...) { x = ... }`
 - **Type empty arrays** — `const items: string[] = []` not `const items = []`
 - **Module imports for node builtins** — `import fs from 'node:fs'` then `fs.readFileSync(...)`, not named imports
-- **Let TypeScript infer return types** — don't annotate return types by default. TypeScript infers them from the code and the inferred type is always correct. Only add an explicit return type when it genuinely improves readability (complex unions, public API boundaries) or when inference produces a wider type than intended:
-
-  ```ts
-  // let inference do its job
-  function getUser(id: string) {
-    const user = await db.find(id)
-    if (!user) return new NotFoundError({ id })
-    return user
-  }
-
-  // explicit annotation when it adds clarity on a complex public API
-  function processRequest(
-    req: Request,
-  ): Promise<ValidationError | AuthError | DbError | null | Response> {
-    // ...
-  }
-  ```
-
+- **Let TypeScript infer return types** — inferred types are always correct. Annotate only when it genuinely improves readability (complex unions, public API boundaries) or when inference produces a wider type than intended
 - **`.filter(isTruthy)` not `.filter(Boolean)`** — `Boolean` doesn't narrow types, so `(T | null)[]` stays `(T | null)[]` after filtering. Use a type guard:
 
   ```ts
@@ -130,53 +91,11 @@ console.log(user.name) // TypeScript knows: User
   const items = results.filter(isTruthy)
   ```
 
-- **`controller.abort()` must use typed errors** — `abort(reason)` throws `reason` as-is. MUST pass a tagged error extending `errore.AbortError`, NEVER `new Error()` or a string — otherwise `isAbortError` can't detect it in the cause chain:
-
-  ```ts
-  class TimeoutError extends errore.createTaggedError({
-    name: 'TimeoutError',
-    message: 'Request timed out for $operation',
-    extends: errore.AbortError,
-  }) {}
-  controller.abort(new TimeoutError({ operation: 'fetch' }))
-  ```
-
-- **Never silently suppress errors** — empty `catch {}` and unlogged error branches hide failures. With errore you rarely need catch at all, but at any boundary where an error is not propagated, always log it (see rule 20):
-
-  ```ts
-  const emailResult = await sendEmail(user.email).catch(
-    (e) => new EmailError({ email: user.email, cause: e }),
-  )
-  if (emailResult instanceof Error) {
-    console.warn('Failed to send email:', emailResult.message)
-  }
-  ```
-
 ## Flat Control Flow
 
 Keep block nesting minimal. Every level of indentation is cognitive load. The ideal function reads top to bottom at root level — checks and early returns, no `else`, no nested `if`, no `try-catch`.
 
-**Core pattern** — call → check error → exit if error → continue at root. This is the single most important structural rule.
-
-**Go:**
-
-```go
-user, err := getUser(id)
-if err != nil {
-    return fmt.Errorf("get user: %w", err)
-}
-// user is valid here, at root level
-
-posts, err := getPosts(user.ID)
-if err != nil {
-    return fmt.Errorf("get posts: %w", err)
-}
-// posts is valid here, at root level
-
-return render(user, posts)
-```
-
-**errore (identical structure):**
+**Core pattern** — call → check error → exit if error → continue at root. This is the single most important structural rule. Identical structure to Go's `if err != nil { return err }` blocks — speed bumps the reader skips over while scanning the left edge:
 
 ```ts
 const user = await getUser(id)
@@ -188,8 +107,6 @@ if (posts instanceof Error) return posts
 return render(user, posts)
 ```
 
-The reader scans the left edge of the function to follow the happy path — just like reading a Go function where `if err != nil` blocks are speed bumps you skip over.
-
 **No `else`** — early return eliminates it: `if (x) return 'A'; return 'B'`
 
 **No `else if` chains** — sequence of early-return `if` blocks:
@@ -203,7 +120,7 @@ function getStatus(code: number): string {
 }
 ```
 
-**Flatten nested `if`** — invert conditions and return early. `if (A) { if (B) { ... } }` becomes `if (!A) return; if (!B) return; ...`. The transformation rule: take the outermost `if` condition, negate it, return the failure case, then continue at root level. Repeat for each nested `if`. The happy path falls through to the end.
+**Flatten nested `if`** — invert conditions and return early. `if (A) { if (B) { ... } }` becomes `if (!A) return; if (!B) return; ...`. Take the outermost `if` condition, negate it, return the failure case, then continue at root level. Repeat for each nested `if`. The happy path falls through to the end.
 
 **Avoid `try-catch` for control flow** — `try-catch` is the worst offender for nesting. It forces a two-branch structure (`try` + `catch`) and hides which line threw. Convert exceptions to values at boundaries:
 
@@ -228,26 +145,6 @@ async function loadConfig(): Promise<Config> {
 
 **Errors in branches, happy path at root** — always handle errors inside `if` blocks, never success logic. Error handling goes in branches with early exits. Putting success logic inside `if` blocks inverts the flow and buries the happy path. **If you see `!(x instanceof Error)` in a condition, you've inverted the pattern — flip it.**
 
-**Keep the happy path at minimum indentation** — the reader scans down the left edge to follow the main logic:
-
-```ts
-async function handleRequest(req: Request): Promise<AppError | Response> {
-  const body = await parseBody(req)
-  if (body instanceof Error) return body
-
-  const user = await authenticate(req.headers)
-  if (user instanceof Error) return user
-
-  const permission = checkPermission(user, body.resource)
-  if (permission instanceof Error) return permission
-
-  const result = await execute(body.action, body.resource)
-  if (result instanceof Error) return result
-
-  return new Response(JSON.stringify(result), { status: 200 })
-}
-```
-
 Same in loops — error in `if` + `continue`, happy path flat:
 
 ```ts
@@ -330,47 +227,11 @@ async function getUser(id: string) {
 
 > Return the error, don't throw it. The return type tells callers exactly what can go wrong.
 
-### Handling Errors (Early Return)
-
-```ts
-const user = await getUser(id)
-if (user instanceof Error) return user
-
-const posts = await getPosts(user.id)
-if (posts instanceof Error) return posts
-
-return posts
-```
+### Boundaries (.catch for async, errore.try for sync)
 
-> Each error is checked at the point it occurs. TypeScript narrows the type after each check.
+`.catch()` and `errore.try` should only appear at the **lowest level** of your call stack — right at the boundary with code you don't control (third-party libraries, `JSON.parse`, `fetch`, file I/O, etc.). Your own functions return errors as values, so they never need `.catch()` or `try`.
 
-### Wrapping External Libraries
-
-```ts
-async function fetchJson<T>(url: string): Promise<NetworkError | T> {
-  const response = await fetch(url).catch(
-    (e) => new NetworkError({ url, reason: 'Fetch failed', cause: e }),
-  )
-  if (response instanceof Error) return response
-
-  if (!response.ok) {
-    return new NetworkError({ url, reason: `HTTP ${response.status}` })
-  }
-
-  const data = await (response.json() as Promise<T>).catch(
-    (e) => new NetworkError({ url, reason: 'Invalid JSON', cause: e }),
-  )
-  return data
-}
-```
-
-> `.catch()` on a promise converts rejections to typed errors. TypeScript infers the union (`Response | NetworkError`) automatically. Use `errore.try` for sync boundaries (`JSON.parse`, etc.).
-
-### Boundary Rule (.catch for async, errore.try for sync)
-
-`.catch()` and `errore.try` should only appear at the **lowest level** of your call stack — right at the boundary with code you don't control (third-party libraries, `JSON.parse`, `fetch`, file I/O, etc.). Your own functions should never throw, so they never need `.catch()` or `try`.
-
-For **async** boundaries: use `.catch((e) => new MyError({ cause: e }))` directly on the promise. TypeScript infers the union automatically. For **sync** boundaries: use `errore.try(() => ..., (e) => ...)`. The `.catch()` callback receives `any` (Promise rejections are untyped), but wrapping in a typed error gives the union a concrete type — no `as` assertions needed.
+For **async** boundaries: `.catch((e) => new MyError({ cause: e }))` directly on the promise. For **sync** boundaries: `errore.try(() => ..., (e) => ...)`. The `.catch()` callback receives `any` (Promise rejections are untyped), but wrapping in a typed error gives the union a concrete type — no `as` assertions needed. TypeScript infers the union automatically:
 
 ```ts
 async function getUser(id: string) {
@@ -379,6 +240,8 @@ async function getUser(id: string) {
   )
   if (res instanceof Error) return res
 
+  if (!res.ok) return new NetworkError({ url: `/users/${id}`, reason: `HTTP ${res.status}` })
+
   const data = await (res.json() as Promise<UserPayload>).catch(
     (e) => new NetworkError({ url: `/users/${id}`, cause: e }),
   )
@@ -389,7 +252,7 @@ async function getUser(id: string) {
 }
 ```
 
-> Think of `.catch()` and `errore.try` as the **adapter** between the throwing world (external code) and the errore world (errors as values). Once you've converted exceptions to values at the boundary, everything above is plain `instanceof` checks. Your own functions return errors as values — they never need `.catch()` or `try`.
+> Think of `.catch()` and `errore.try` as the **adapter** between the throwing world (external code) and the errore world (errors as values). Once you've converted exceptions to values at the boundary, everything above is plain `instanceof` checks.
 
 ### Optional Values (| null)
 
@@ -447,7 +310,7 @@ return res.status(response.status).json(response.body)
 
 ### Resource Cleanup (defer) — Replacing try/finally with `using`
 
-`try/finally` has a structural problem: **every resource adds a nesting level**. Two resources = two levels of indentation. The business logic gets buried deeper with each resource, and cleanup is split across `finally` blocks far from where the resource was acquired. `await using` + `DisposableStack` keeps the function flat — one `cleanup.defer()` per resource, same indentation whether you have one resource or ten. Cleanup runs automatically in reverse order on every exit path.
+`try/finally` has a structural problem: **every resource adds a nesting level**. Two resources = two levels of indentation, and cleanup is split across `finally` blocks far from where the resource was acquired. `await using` + `DisposableStack` keeps the function flat — one `cleanup.defer()` per resource, same indentation whether you have one resource or ten. Cleanup runs automatically in reverse (LIFO) order on every exit path — normal return, early error return, or exception.
 
 **tsconfig requirement:** add `"ESNext.Disposable"` to `lib`:
 
@@ -459,29 +322,6 @@ return res.status(response.status).json(response.body)
 }
 ```
 
-**Before — nested try/finally:**
-
-```ts
-async function importData(url: string, dbUrl: string) {
-  const db = await connectDb(dbUrl)
-  try {
-    const tmpFile = await createTempFile()
-    try {
-      const data = await (await fetch(url)).text()
-      await tmpFile.write(data)
-      await db.import(tmpFile.path)
-      return { rows: await db.count() }
-    } finally {
-      await tmpFile.delete()
-    }
-  } finally {
-    await db.close()
-  }
-}
-```
-
-**After — flat with `await using`:**
-
 ```ts
 async function importData(url: string, dbUrl: string): Promise<ImportError | { rows: number }> {
   await using cleanup = new errore.AsyncDisposableStack()
@@ -503,7 +343,7 @@ async function importData(url: string, dbUrl: string): Promise<ImportError | { r
 }
 ```
 
-> `await using` guarantees cleanup on every exit path — normal return, early error return, or exception. Resources release in LIFO order. Adding a resource is one line (`cleanup.defer()`), not another nesting level. The errore polyfill handles the runtime; the tsconfig `lib` entry handles the types.
+> Adding a resource is one line (`cleanup.defer()`), not another nesting level. The errore polyfill handles the runtime; the tsconfig `lib` entry handles the types.
 
 ### Fallback Values
 
@@ -570,7 +410,7 @@ async function legacyHandler(id: string) {
 
 ### Converting `{ data, error }` Returns
 
-Some SDKs (Supabase, Stripe, etc.) return `{ data, error }` instead of throwing. Destructure inline, check `error` first (truthy, not `instanceof` — most SDKs return plain objects), wrap in a tagged error, then continue with `data`:
+Some SDKs (Supabase, Stripe, etc.) return `{ data, error }` instead of throwing. Destructure inline, check `error` first with a truthy check (not `instanceof` — most SDKs return plain objects), wrap in a tagged error, then continue with `data`:
 
 ```ts
 const { data, error } = await supabase.from('users').select('*').eq('id', id)
@@ -579,7 +419,7 @@ if (data === null) return new NotFoundError({ id })
 // data is narrowed here
 ```
 
-> If the SDK's `error` is already an `Error` instance you can return it directly, but wrapping in a domain error is better — gives you `_tag`, typed properties, and `cause` chain. Check `error` with truthy check, not `instanceof Error`, since most SDK error objects are plain objects.
+> Wrapping in a domain error is better than returning the SDK's error directly — gives you `_tag`, typed properties, and the `cause` chain.
 
 ### Partition: Splitting Successes and Failures
 
@@ -595,9 +435,11 @@ errors.forEach((e) => console.warn('Failed:', e.message))
 
 ### Abort & Cancellation
 
-`controller.abort(reason)` throws `reason` as-is — whatever you pass is what `.catch()` receives. This means you MUST pass a typed error extending `errore.AbortError`, never a plain `Error` or string.
+`controller.abort(reason)` throws `reason` as-is — whatever you pass is what `.catch()` receives. This means you MUST pass a typed error extending `errore.AbortError`, never a plain `Error` or string — otherwise `isAbortError` can't detect it.
+
+Always use `errore.isAbortError(error)` to detect abort errors — never check `error.name === 'AbortError'` manually, because tagged abort errors have their tag as `.name`. `isAbortError` walks the entire `.cause` chain, so it works even when the abort error is wrapped by `.catch()`.
 
-Always use `errore.isAbortError(error)` to detect abort errors. It walks the entire `.cause` chain, so it works even when the abort error is wrapped by `.catch()`.
+Keep abort checks flat: `isAbortError(result)` first as its own early return, then `result instanceof Error` as a separate early return. Never nest one inside the other.
 
 ```ts
 import * as errore from 'errore'