@litfamily/litgrok 1.0.0

package/.grok/skills/lit-code/references/rust-ub/ub-taxonomy.md

@@ -0,0 +1,269 @@
+# Rust Undefined Behavior Taxonomy
+
+Every category of UB the Rust compiler, Miri, and the language specification recognize. The agent must know the full surface to hunt systematically. Each entry names the UB class, its root cause, canonical trigger, Miri detection status, and the canonical fix.
+
+## 1. Aliasing Violations (Stacked Borrows / Tree Borrows)
+
+**Root cause:** Two pointers access the same memory in ways that violate Rust's borrowing model — even through raw pointers inside `unsafe`.
+
+**Canonical triggers:**
+- Creating a `&mut T` while another `&T` or `&mut T` to the same location exists.
+- Dereferencing a raw pointer derived from a reference after that reference was invalidated (e.g., `&mut` was retaken).
+- Calling `slice::from_raw_parts_mut` on overlapping regions.
+- Interior mutability through `UnsafeCell` without going through the `UnsafeCell` API.
+- Casting `&T` to `*mut T` and writing through it (even via FFI).
+
+**Miri detection:** YES — Stacked Borrows is the default model. Tree Borrows (`-Zmiri-tree-borrows`) is the newer, more permissive model. Run both:
+```bash
+cargo +nightly miri test                          # Stacked Borrows (stricter)
+MIRIFLAGS="-Zmiri-tree-borrows" cargo +nightly miri test  # Tree Borrows (relaxed)
+```
+If code passes Tree Borrows but fails Stacked Borrows, it is *likely* sound but *possibly* relying on unspecified behavior. Fix it anyway — Stacked Borrows is the conservative bet.
+
+**Fix pattern:** Use `UnsafeCell` for all interior mutability. Never cast `&T` to `*mut T`. Derive mutable pointers from `*mut T` obtained via `UnsafeCell::get()` or `addr_of_mut!()`.
+
+---
+
+## 2. Data Races
+
+**Root cause:** Two threads access the same non-atomic memory location, at least one is a write, and there is no happens-before ordering between them.
+
+**Canonical triggers:**
+- `unsafe impl Send for T` on a type containing `*mut U` without synchronization.
+- `unsafe impl Sync for T` on a type containing `Cell<T>` or `UnsafeCell<T>` without a lock.
+- Using `std::ptr::write` from multiple threads to the same allocation.
+- Shared `&T` where `T` has interior mutability but no atomic/lock guard.
+
+**Miri detection:** YES — Miri's data-race detector is on by default. It detects races on non-atomic accesses. For **preemptive scheduling** stress, use:
+```bash
+MIRIFLAGS="-Zmiri-preemption-rate=0.1" cargo +nightly miri test
+```
+
+**Complementary tools:** `loom` for exhaustive interleaving exploration on lock-free algorithms. ThreadSanitizer (TSAN) for integration tests Miri cannot run (I/O, FFI).
+
+**Fix pattern:** Wrap in `Mutex`/`RwLock`/`AtomicXxx`. Never `unsafe impl Sync` unless you can name the synchronization primitive guarding every mutable field.
+
+---
+
+## 3. Use After Free / Dangling Pointers
+
+**Root cause:** A pointer or reference outlives the allocation it points to.
+
+**Canonical triggers:**
+- Returning a reference to a local variable (compiler catches most, but raw pointers escape).
+- `Box::into_raw` → manual `Box::from_raw` with wrong lifetime.
+- `Vec` reallocation invalidating raw pointers obtained from `as_ptr()` / `as_mut_ptr()`.
+- `Pin<Box<T>>` unpinned and moved after self-referential pointers were set up.
+
+**Miri detection:** YES — allocation tracking catches use-after-free on the exact operation.
+
+**Fix pattern:** Borrow checker for references. For raw pointers: tie pointer validity to an explicit lifetime via a `PhantomData<&'a T>` in the wrapper, or use arena allocation (`bumpalo`) so all pointers share one lifetime.
+
+---
+
+## 4. Uninitialized Memory
+
+**Root cause:** Reading a value from memory that was never written to.
+
+**Canonical triggers:**
+- `MaybeUninit::assume_init()` before all bytes are written.
+- `mem::uninitialized()` (deprecated, still compiles).
+- `alloc::alloc(layout)` returns uninitialized memory — reading it before writing is UB.
+- Padding bytes in structs read via `transmute` or raw pointer casts.
+- `read_unaligned` on uninitialized memory.
+
+**Miri detection:** YES — tracks initialization state per byte. Catches partial-init structs, padding reads, and premature `assume_init`.
+
+**Fix pattern:** Use `MaybeUninit::zeroed()` when zero-init is acceptable. Write every field before calling `assume_init()`. Use `MaybeUninit::write()` instead of raw pointer writes. Never `transmute` structs with padding unless you zeroed the padding.
+
+---
+
+## 5. Invalid Values (Type Invariant Violations)
+
+**Root cause:** Producing a value that violates the type's validity invariant.
+
+**Canonical triggers:**
+- `bool` not 0 or 1.
+- `char` outside Unicode scalar range.
+- Enum discriminant not matching any variant.
+- `NonZeroU32` containing 0.
+- `&T` or `&mut T` that is null or dangling.
+- `str` containing non-UTF-8 bytes.
+- `fn` pointer that is null.
+
+**Miri detection:** YES — validity checks are on by default. Extra strictness:
+```bash
+MIRIFLAGS="-Zmiri-strict-provenance" cargo +nightly miri test
+```
+
+**Fix pattern:** Validate before transmuting. Use `TryFrom` at boundaries. Never `transmute` to enum types — use a checked conversion function.
+
+---
+
+## 6. Misaligned Pointer Access
+
+**Root cause:** Dereferencing a pointer that is not aligned to the type's required alignment.
+
+**Canonical triggers:**
+- Casting `*const u8` to `*const u64` and dereferencing (alignment goes from 1 to 8).
+- `#[repr(packed)]` struct field references (the compiler warns, but raw pointers bypass the warning).
+- Network buffer parsing where offsets are arbitrary.
+
+**Miri detection:** YES — immediate trap on misaligned read/write.
+
+**Fix pattern:** Use `read_unaligned` / `write_unaligned` for packed data. Use `bytemuck` or `zerocopy` for safe reinterpretation with alignment checks.
+
+---
+
+## 7. Violating `Pin` Invariants
+
+**Root cause:** Moving a value that was pinned and relied on its address stability (self-referential types, intrusive linked lists).
+
+**Canonical triggers:**
+- `mem::swap` on a `Pin<&mut T>` after `unsafe` deref.
+- Implementing `Unpin` for a type that contains self-referential pointers.
+- Manually calling `Pin::new_unchecked` on a movable allocation.
+
+**Miri detection:** PARTIAL — Miri detects the resulting aliasing/use-after-free if the self-referential pointer is actually used. It does not detect "Pin contract violated but pointer was never dereferenced."
+
+**Fix pattern:** Never `impl Unpin` for self-referential types. Use `pin_project` or `pin_project_lite` for safe pin projections. Review every `Pin::new_unchecked` call.
+
+---
+
+## 8. FFI Boundary UB
+
+**Root cause:** Mismatch between Rust's ABI expectations and the foreign code's actual behavior.
+
+**Canonical triggers:**
+- C function returning uninitialized memory into a Rust `&T`.
+- Wrong `#[repr(C)]` layout (padding differs between platforms).
+- Passing a Rust `enum` to C without `#[repr(C)]` or `#[repr(i32)]`.
+- Null pointer passed where C expects non-null (and Rust wraps it in `&T`).
+- C code writing to Rust-owned memory through a pointer Rust considers immutable.
+- Forgetting to mark FFI functions as `unsafe extern "C"`.
+- longjmp/setjmp across Rust frames (unwinding UB).
+
+**Miri detection:** LIMITED — Miri cannot execute foreign code. It detects UB in the Rust-side handling of FFI return values.
+
+**Complementary tools:** AddressSanitizer (ASAN), MemorySanitizer (MSAN) for detecting actual FFI-side corruption. Valgrind as a last resort.
+
+**Fix pattern:** Validate every FFI return at the boundary. Use `Option<NonNull<T>>` for nullable pointers. Use `CStr`/`CString` for strings. Add `cbindgen` to CI to verify layout agreement. Wrap every FFI call in a safe Rust function that checks preconditions.
+
+---
+
+## 9. Incorrect `Send` / `Sync` Implementations
+
+**Root cause:** Manually implementing `Send` or `Sync` for a type that does not actually uphold the required invariant.
+
+**Canonical triggers:**
+- `unsafe impl Send for Wrapper(*mut T)` when `T` is not `Send`.
+- `unsafe impl Sync for Wrapper(UnsafeCell<T>)` without a lock, atomic, or other synchronization.
+- Types containing `Rc<T>` with a manual `Send` impl (Rc is explicitly !Send).
+
+**Miri detection:** YES for the *resulting* data race if exercised. Miri's data-race detector will fire when two threads access the same location unsynchronized.
+
+**Fix pattern:** Never manually implement `Send`/`Sync` unless you can write a SAFETY proof naming the synchronization mechanism. Use `PhantomData<*const ()>` to opt-out of auto-`Send`/`Sync` when in doubt.
+
+---
+
+## 10. Out-of-Bounds Memory Access
+
+**Root cause:** Pointer arithmetic or indexing that escapes the allocation.
+
+**Canonical triggers:**
+- `ptr.offset(n)` where `n` exceeds the allocation size.
+- `slice::from_raw_parts(ptr, len)` where `len` is too large.
+- Off-by-one in manual buffer management.
+- Integer overflow in size calculations leading to undersized allocation.
+
+**Miri detection:** YES — allocation-precise bounds checking.
+
+**Fix pattern:** Use checked arithmetic (`checked_add`, `checked_mul`) for size calculations. Use `slice::from_raw_parts` only with validated lengths. Prefer safe indexing (`get()`, iterators) over raw pointer arithmetic.
+
+---
+
+## 11. Provenance Violations
+
+**Root cause:** Using a pointer whose provenance does not grant access to the target memory, even if the address is numerically correct.
+
+**Canonical triggers:**
+- Casting an integer to a pointer and dereferencing it (`addr as *const T`).
+- Roundtripping a pointer through `usize` and back (`ptr as usize as *const T`) — the provenance is lost.
+- Using `ptr::from_exposed_addr` without a corresponding `ptr.expose_provenance()`.
+
+**Miri detection:** YES with strict provenance:
+```bash
+MIRIFLAGS="-Zmiri-strict-provenance" cargo +nightly miri test
+```
+
+**Fix pattern:** Use `ptr::with_exposed_provenance` / `ptr.expose_provenance()` for legitimate int-to-ptr roundtrips. Avoid `as usize as *const T` entirely. Use `sptr` crate for provenance-safe pointer manipulation on stable.
+
+---
+
+## 12. Double Free / Invalid Free
+
+**Root cause:** Freeing the same allocation twice, or freeing memory not obtained from the allocator.
+
+**Canonical triggers:**
+- `Box::from_raw` called twice on the same pointer.
+- Manual `dealloc` on a pointer already freed.
+- `ManuallyDrop` dropped explicitly then the outer type also drops it.
+
+**Miri detection:** YES — immediate trap.
+
+**Fix pattern:** Enforce single ownership via RAII. Use `ManuallyDrop` with extreme care — document who is responsible for the drop. Never clone a raw pointer and `Box::from_raw` both copies.
+
+---
+
+## 13. Library / Unsafe Contract Violations
+
+**Root cause:** Violating the documented safety invariant of a safe or unsafe API, where the library author relied on the invariant for soundness.
+
+**Canonical triggers:**
+- `Vec::set_len(n)` where the first `n` elements are not initialized.
+- `String::from_utf8_unchecked` on non-UTF-8 bytes.
+- `HashMap` key mutated after insertion (violates hash invariant — not UB per se, but unsound and Miri may detect downstream effects).
+- `BTreeMap` key with broken `Ord` impl (the standard library assumes a total order).
+
+**Miri detection:** DEPENDS — Miri catches the downstream UB (e.g., reading uninitialized bytes from a `Vec` with inflated len). It does not catch "you violated the documented contract" if no memory-level UB results.
+
+**Fix pattern:** Read the `# Safety` section of every `unsafe fn` you call. Document the invariant in your SAFETY comment. When in doubt, use the safe API and pay the cost.
+
+---
+
+## 14. Unwinding Across `extern "C"` Boundaries
+
+**Root cause:** A Rust panic unwinding through a frame that uses the C calling convention.
+
+**Canonical triggers:**
+- `panic!()` inside a `#[no_mangle] extern "C" fn` callback passed to C code.
+- `unwrap()` inside FFI callbacks.
+
+**Miri detection:** PARTIAL — Miri does not model foreign unwinding, but it can detect the immediate UB if the panic reaches the FFI boundary.
+
+**Fix pattern:** Use `std::panic::catch_unwind` at every FFI entry point. Mark FFI callbacks as `extern "C-unwind"` when panic propagation is intentional (nightly). Prefer returning `Result`-like error codes from FFI callbacks.
+
+---
+
+## Summary Table
+
+| # | Category | Miri Detects? | Complementary Tool |
+|---|----------|--------------|-------------------|
+| 1 | Aliasing (Stacked/Tree Borrows) | YES | — |
+| 2 | Data races | YES | loom, TSAN |
+| 3 | Use-after-free / dangling | YES | ASAN |
+| 4 | Uninitialized memory | YES | MSAN |
+| 5 | Invalid values | YES | — |
+| 6 | Misaligned access | YES | UBSAN |
+| 7 | Pin invariant violation | PARTIAL | manual review |
+| 8 | FFI boundary UB | LIMITED | ASAN, MSAN, Valgrind |
+| 9 | Incorrect Send/Sync | YES (via race) | loom |
+| 10 | Out-of-bounds access | YES | ASAN |
+| 11 | Provenance violations | YES (strict mode) | — |
+| 12 | Double free | YES | ASAN |
+| 13 | Library contract violations | PARTIAL | proptest, fuzzing |
+| 14 | Unwinding across FFI | PARTIAL | — |
+
+## Miri Coverage Assessment
+
+Miri catches categories 1-6, 9-12 with high confidence. Categories 7, 8, 13, 14 require supplementary tools or manual audit. **Miri is the single highest-leverage tool** — it should run on every PR that touches `unsafe`, and ideally on the full test suite regularly.

package/.grok/skills/lit-code/references/tool-boundaries.md

@@ -0,0 +1,66 @@
+# Tool-by-tool implementation boundaries
+
+Load this reference when a programming task crosses more than one tool class, when the same operation could be attempted through several tools, or when a safe verification path is unclear. This is a decision table, not a catalog of every host tool.
+
+## Boundary table
+
+| Tool or action | Primary effect | Permission filter | Sandbox concern | Safe programming use | Stop condition |
+| --- | --- | --- | --- | --- | --- |
+| read a file | observes bytes | `Read` / `read` | source path must be readable | inspect guidance, source, tests, and generated ownership | path is outside authorized scope or contains protected secrets |
+| list or search | discovers paths/text | `Grep` / `grep` or read-like rules | traversal remains within readable roots | locate symbols, callers, manifests, and guards | query would scan a prohibited sibling or private root |
+| edit existing file | mutates bytes | `Edit` / `edit` | destination must be writable | targeted patch to an owned file after reading it | target is foreign, generated without its generator, or outside scope |
+| write new file | creates bytes | write/edit feature and rules | parent directory must be writable | add a required source, test, or reference with a known owner | destination schema is undocumented or conflicts with existing state |
+| shell command | launches process | `Bash` / `bash` | child filesystem and network limits apply | run documented tests, syntax checks, and read-only status commands | destructive or external effect lacks explicit authority |
+| package test | executes repository scripts | usually shell rules | may write caches or evidence | run from the documented product root and report counts | command is known to mutate protected artifacts without isolation |
+| formatter | rewrites source | shell plus write reach | all formatted paths must be writable | run only on named files when formatting is required | repository-wide format would touch unrelated dirty files |
+| generator | rewrites derived files | shell plus write reach | output roots must be writable | run the owning generator after source changes | generator scope is unknown or includes protected mirrors |
+| package dry run | resolves shipped payload | shell; may read package files | temp/cache paths must be writable | inspect structured JSON listing without publishing | lifecycle scripts have unreviewed external effects |
+| network fetch | reaches remote service | `WebFetch`, `WebSearch`, or tool-specific rule | child-network setting may not cover in-process tools | retrieve a named primary source when current facts require it | credentials, purchase, upload, or private data transfer is implied |
+| MCP tool | invokes configured server | `MCPTool` / `mcp` | server process and transport have separate reach | use only a configured, documented server and namespaced tool | server identity, arguments, or external effect is unclear |
+| background task | persists command beyond turn | shell rules | same child limits continue | bounded long test or monitor with explicit receipt | completion cannot be observed or cancellation would corrupt state |
+| worktree operation | creates isolated checkout | shell and filesystem writes | parent and checkout paths must be writable | isolate a baseline or parallel change when authorized | dirty state would be lost or target branch/ref is ambiguous |
+| version-control commit | records repository state | shell rules | `.git` must be writable | only with explicit commit authority and explicit staging | broad staging, generated attribution, or unexpected paths appear |
+| push, publish, deploy | mutates external state | shell/network rules | credentials and remote reach required | only under explicit release authorization | authorization is absent, version is unresolved, or destination differs |
+
+Permission filters name host matching categories. They do not promise that a particular tool is enabled or that its input schema has a certain shape. Inspect the live tool surface before constructing a call.
+
+## Tool substitution rule
+
+Do not substitute a different tool merely because the intended one is denied. Editing through shell redirection is still an edit. Calling a network-capable server instead of a blocked child process is still a network action. Writing a generated file manually is still mutation of a derived artifact. Authorization follows the effect, not the tool label.
+
+A substitute is acceptable only when it stays within the same authorized effect, its permission and sandbox boundaries are independently satisfied, it preserves validation and cleanup, the evidence still exercises the user-facing path, and it does not bypass a denial or hard stop.
+
+## Read and search boundary
+
+Read the narrowest sources that establish ownership and behavior. A repository search can reveal generated copies, registrations, and tests; it can also cross scope if rooted too high. Resolve the product root before searching. Keep secrets, ignored credentials, and unrelated trees outside the query. Treat matches as pointers, then read the owning context.
+
+Search output is not execution evidence. A symbol existing in source does not prove registration, packaging, or runtime reachability. Follow it to the surface the user touches.
+
+## Edit and write boundary
+
+Before mutation, inspect status, read the exact file and nearest test, decide whether it is source or generated output, resolve conflict policy, add a focused failing test when behavior changes, and prefer a patch that leaves unrelated lines intact.
+
+After mutation, inspect the diff. A parser check does not prove behavior. A focused test does not prove package inclusion. Select the next verification layer based on the changed surface.
+
+## Shell boundary
+
+Shell commands can read, write, spawn children, access the network, and change external state. Classify the command before running it. Avoid combining commands whose exit states matter. Quote paths safely. Keep untrusted text out of interpolation. Use explicit working directories. Treat timeouts as timeouts, and inspect background tasks instead of declaring them failed or complete by elapsed time alone.
+
+Commands that delete, reset, clean, stash, commit, push, publish, deploy, grant trust, or rewrite host configuration require their own authorization. A broad task such as “fix tests” does not imply them.
+
+## Verification boundary
+
+| Change type | First evidence | Adjacent evidence | User-surface evidence |
+| --- | --- | --- | --- |
+| parser or pure function | focused unit test | module test file | caller integration |
+| CLI behavior | argument/exit test | package test | temp-directory invocation |
+| installer payload | synthetic conflict test | pack listing | real temp install and file inventory |
+| hook command | stdin driver | config-schema test | documented event-shaped invocation |
+| documentation contract | structural test | full docs suite | packed path and reachability link |
+| generated manifest | generator RED/GREEN | hash or consistency check | packed/install listing |
+
+Use the table to select evidence, not to demand every layer for every edit. State which load-bearing layer was omitted and why.
+
+## External-state boundary
+
+Authentication, host configuration, repository history, remote branches, registries, deployment targets, messages, and purchases are external state. Preparation can be in scope while mutation is not. A task may authorize a version edit without authorizing publication, or authorize a commit without authorizing push. Preserve those distinctions in tool choice and receipts.

package/.grok/skills/lit-code/references/typescript/README.md

@@ -0,0 +1,195 @@
+
+# TypeScript Programmer
+
+Modern TypeScript. Type-strict, stack-first, async-correct.
+
+## Philosophy
+
+The compiler is your proof system. Make illegal states unrepresentable. Parse at boundaries. Every function has a contract; the type system enforces it.
+
+## Hard rules
+
+These are deliberate project choices. Violations are always wrong, not "style preferences".
+
+### Tooling
+
+| Category | Use | Never |
+|---|---|---|
+| Runtime | Bun (native TS, single binary) | ts-node, tsx |
+| Package manager | `pnpm` | npm, yarn (unless workspace requires it) |
+| Linter + formatter | Biome | ESLint, Prettier |
+| Type checker | `tsc --noEmit` with strict config | skip type checking |
+| Web framework | Hono | Express |
+| Validation | Zod | joi, yup, class-validator |
+| Testing | `bun test` or vitest | jest |
+| ORM | Drizzle | TypeORM, Prisma (unless already in project) |
+
+### The iron list
+
+1. **Readonly by default** — all `type`/`interface` properties are `readonly`. Arrays are `readonly T[]`. Mutable only when mutation is the documented purpose.
+2. **Branded types for distinct IDs** — `type UserId = Brand<string, "UserId">`. Never pass raw `string` where a branded type exists.
+3. **Exhaustive switch** — every `switch` on a discriminated union ends with `default: assertNever(x)`. No fall-through.
+4. **No any** — `any` is banned in annotations, returns, and parameters. Use `unknown` and narrow.
+5. **No type assertions** — `as any`, `as unknown` banned. `as const` and `satisfies` are fine.
+6. **No non-null assertion** — `x!` is banned. Use narrowing or optional chaining (`x?.y`).
+7. **No @ts-ignore / @ts-expect-error** — fix the type.
+8. **No enum** — use `as const` objects + literal union types.
+9. **Zod at boundaries** — external input (API, user, file) → Zod schema. Internal → plain types.
+10. **Typed errors** — Error subclasses with typed fields. No `throw new Error("bare string")` for domain errors. Use Result for expected failures within 1-2 call levels; throw for propagation across many layers.
+11. **as const for constants** — module-level constant objects and arrays use `as const`.
+12. **import type** — type-only imports use `import type`. Enforced by `verbatimModuleSyntax`.
+13. **Named exports only** — no `export default`. Exception: framework requirement (Next.js pages, etc.).
+14. **No empty catch, no catch-and-swallow** — every `catch` block must either (a) narrow the error with `instanceof` and handle each case, or (b) re-throw. Empty catch blocks and `catch (e) { console.error(e) }` without narrowing or re-throw are banned — they hide bugs. At top-level boundaries (CLI entry, HTTP handler), opt out with `// no-excuse-ok: catch`.
+
+### Data modeling — which construct, when
+
+| Situation | Use |
+|---|---|
+| User input, API request/response | Zod schema + `z.infer` |
+| Internal value object | `type` with `readonly` properties |
+| Function with multiple outcomes | Discriminated union (`kind` field) |
+| Contract for implementations | `interface` |
+| Fixed constants | `as const` + literal union |
+| Distinct primitive (UserId vs OrderId) | Branded type |
+| Key-value map | `Record<K, V>` or index signature |
+
+**The one rule**: data crosses trust boundary → Zod. Everything else → plain `type` with `readonly`.
+
+Load `data-modeling.md` for the full decision flowchart and comparison.
+
+### When readonly does not apply
+
+- **Framework state** (React `useState`, signals) — managed by framework.
+- **Builder / accumulator** — object exists to be mutated (buffer, cache). Document why.
+- **ORM mutations** — Drizzle insert/update objects.
+
+### Why empty/unhandled catch is banned
+
+In TypeScript, every `catch` receives `unknown`. The language gives you no type safety in catch blocks — you must earn it with `instanceof`. A bare `catch (e) { console.error(e) }` swallows `TypeError`, `RangeError`, and your domain errors identically. When a new error type appears, nothing warns you.
+
+```typescript
+// BANNED — empty catch
+try { await fetchData() } catch {}
+try { await fetchData() } catch (e) { /* will fix later */ }
+
+// BANNED — catch-and-swallow (no narrowing, no rethrow)
+try {
+  const data = await api.get("/users")
+} catch (e) {
+  console.error("failed", e)
+}
+
+// GOOD — narrow with instanceof
+try {
+  const data = await api.get("/users")
+} catch (e) {
+  if (e instanceof HttpError) {
+    logger.warn(`API ${e.status}: ${e.message}`)
+    return fallback
+  }
+  throw e  // unknown errors propagate
+}
+
+// GOOD — top-level boundary (only place catch-all is acceptable)
+async function main(): Promise<void> {  // no-excuse-ok: catch
+  try {
+    await run()
+  } catch (e) {
+    console.error("unhandled:", e)
+    process.exit(1)
+  }
+}
+```
+
+### Libraries
+
+| Domain | Library | Why |
+|---|---|---|
+| HTTP framework | Hono | Lightweight, multi-runtime, middleware, OpenAPI |
+| Validation | Zod | Runtime validation + type inference |
+| ORM | Drizzle | Type-safe SQL, no codegen |
+| HTTP client | `ky` | Thin fetch wrapper (5KB); auto-throw on non-2xx, retry, timeout, hooks, prefixUrl. Browser + Node + Bun + Deno |
+| HTTP client (perf) | `undici` (direct API) | Node backend에서 connection pooling, HTTP/2, pipelining 필요 시 |
+
+> **HTTP client 규칙** — 프로덕션 코드에서 bare `fetch()`는 사용 금지. retry·timeout·에러 핸들링이 전무하여 장애 시 silent failure를 유발한다. **`ky`** 를 기본으로 설치하고, Node backend에서 대량 요청·커넥션 풀·HTTP/2 파이프라이닝이 필요하면 **`undici`** direct API를 쓴다. ~~`axios`~~ 는 supply-chain compromise(2026-03) 이후 사용 금지. `node-fetch`는 Node 18+ 내장 fetch로 대체되어 불필요.
+| Testing | `bun test` / vitest | Fast, ESM-native |
+| Logging | `pino` | Structured JSON, fast |
+| CLI | `@clack/prompts` + `commander` | Interactive + parsing |
+
+## tsconfig — the one true config
+
+Scaffold a new project with all strict defaults pre-configured:
+
+```bash
+bun run ../../scripts/typescript/new-project.ts my-api
+bun run ../../scripts/typescript/new-project.ts my-api --path ./projects
+```
+
+Creates: `package.json` (Hono + Zod + Biome), `tsconfig.json` (ultra-strict), `biome.json`, `src/index.ts`, `.gitignore`. Works on macOS, Linux, Windows.
+
+For manual setup: `bunx tsc --init`, then load `tsconfig-strict.md` for the full strict config.
+
+Key flags beyond `"strict": true`:
+
+| Flag | What it catches |
+|---|---|
+| `noUncheckedIndexedAccess` | `arr[0]` is `T \| undefined`, forces check |
+| `exactOptionalPropertyTypes` | `{ x?: string }` ≠ `{ x: string \| undefined }` |
+| `verbatimModuleSyntax` | Forces `import type` for type-only imports |
+| `noFallthroughCasesInSwitch` | Forgotten `break` / `return` |
+| `noPropertyAccessFromIndexSignature` | `.key` on index sig → bracket notation |
+
+## Reference loading
+
+Load on demand — not all at once.
+
+| Need | Load |
+|---|---|
+| Strict tsconfig + Biome config | `tsconfig-strict.md` |
+| Type patterns (branded, as const, satisfies, narrowing, assertNever) | `type-patterns.md` |
+| Data modeling (type vs interface vs Zod, readonly, parse-don't-validate) | `data-modeling.md` |
+| Error handling (Result, typed errors, union vs throw) | `error-handling.md` |
+| Bootstrapping a new project (Bun, pnpm, Hono, Vite) | `bootstrap.md` |
+| Hono backend stack (hono-openapi, Scalar, Swagger) | `backend-hono.md` |
+
+## No-excuse audit
+
+Violations caught by `../../scripts/typescript/check-no-excuse-rules.ts`. Run after every edit session.
+
+| Rule ID | Catches | Opt-out |
+|---|---|---|
+| `no-any-assertion` | `as any` | None — redesign types |
+| `no-unknown-assertion` | `as unknown` | None — redesign types |
+| `no-ts-ignore` | `@ts-ignore` | None — fix the type |
+| `no-ts-expect-error` | `@ts-expect-error` | None — fix the type |
+| `no-enum` | `enum` declarations | None — use `as const` |
+| `no-non-null-assertion` | `x!` postfix | None — narrow or `?.` |
+| `no-throw-literal` | `throw "string"` / `throw 123` | None — throw Error subclass |
+| `no-mutable-export` | `export let` / `export var` | None — use `export const` |
+| `no-any-annotation` | `: any` in parameter/return/variable types | `// no-excuse-ok: any` |
+| `no-explicit-any-return` | `(): any` or `(): Promise<any>` return types | `// no-excuse-ok: any` |
+| `empty-catch` | `catch { }` or `catch (e) { }` with empty body | `// no-excuse-ok: catch` |
+| `catch-without-narrowing` | `catch (e)` used without `instanceof` or re-throw | `// no-excuse-ok: catch` |
+
+Biome enforces additional rules (noExplicitAny, noNonNullAssertion, noDefaultExport, useImportType). The script catches what Biome cannot.
+
+## In tests
+
+Tests are strict too, with these exceptions (configure in `biome.jsonc` overrides):
+
+| In tests you may | Why |
+|---|---|
+| Use `expect()` assertions | That's how testing works |
+| Use magic numbers | Test data |
+| Access private members via bracket notation | Testing internals |
+| Skip readonly on test fixtures | Mutable setup/teardown |
+
+Tests still follow the iron list — branded types, typed errors, exhaustive switch.
+
+## Existing codebases
+
+When editing an existing file that doesn't follow these rules: **write new code in strict style, don't refactor existing code in the same change.**
+
+## Activation
+
+This skill activates whenever you are writing or modifying any `.ts` or `.tsx` file. Even one-off scripts get the strict treatment.