@kr78/pi-coding-agent 17.2.10

package/src/discovery/builtin-rules/go-exp-promoted.md

@@ -0,0 +1,40 @@
+---
+description: "Use the standard library slices and maps packages instead of golang.org/x/exp/{slices,maps}"
+condition:
+  - '"golang.org/x/exp/slices"'
+  - '"golang.org/x/exp/maps"'
+scope: "tool:edit(*.go), tool:write(*.go)"
+interruptMode: never
+---
+
+`golang.org/x/exp/slices` and `golang.org/x/exp/maps` were promoted into the standard library as `slices` and `maps` in Go 1.21. Import the stdlib packages in new code instead of the experimental ones.
+
+## Migration
+
+```go
+// Before
+import (
+	"golang.org/x/exp/slices"
+	"golang.org/x/exp/maps"
+)
+
+// After
+import (
+	"slices"
+	"maps"
+)
+```
+
+Most call sites are unchanged: `slices.Sort`, `slices.Contains`, `slices.Index`, `slices.Equal`, `maps.Clone`, etc.
+
+## Watch the signature differences
+
+The promoted APIs were tweaked, so a blind path swap can break the build:
+
+- `x/exp/maps.Keys(m)` / `Values(m)` returned a slice; the stdlib `maps.Keys(m)` / `maps.Values(m)` return an **iterator** (`iter.Seq`). Use `slices.Collect(maps.Keys(m))` to recover a slice, or range over the iterator.
+- `slices.SortFunc` takes a comparison returning `int` (cmp-style), matching the stdlib signature.
+
+## Keep x/exp when
+
+- The module's `go` directive is below 1.21 (stdlib `slices`/`maps` don't exist yet).
+- You need an `x/exp` helper that was not promoted (e.g. parts of `x/exp/constraints` still live outside the stdlib).

package/src/discovery/builtin-rules/go-ioutil.md

@@ -0,0 +1,37 @@
+---
+description: "Use io and os instead of the deprecated io/ioutil package"
+condition: '"io/ioutil"'
+scope: "tool:edit(*.go), tool:write(*.go)"
+interruptMode: never
+---
+
+`io/ioutil` has been deprecated since Go 1.16. Every function moved to `io` or `os` with the same behavior. Do not import it in new code.
+
+## Mapping
+
+| io/ioutil | Replacement |
+| --- | --- |
+| `ioutil.ReadAll` | `io.ReadAll` |
+| `ioutil.ReadFile` | `os.ReadFile` |
+| `ioutil.WriteFile` | `os.WriteFile` |
+| `ioutil.ReadDir` | `os.ReadDir` (returns `[]os.DirEntry`, not `[]os.FileInfo`) |
+| `ioutil.TempFile` | `os.CreateTemp` |
+| `ioutil.TempDir` | `os.MkdirTemp` |
+| `ioutil.NopCloser` | `io.NopCloser` |
+| `ioutil.Discard` | `io.Discard` |
+
+## Migration
+
+```go
+// Before
+import "io/ioutil"
+data, err := ioutil.ReadFile(path)
+_ = ioutil.WriteFile(out, data, 0o644)
+
+// After
+import "os"
+data, err := os.ReadFile(path)
+_ = os.WriteFile(out, data, 0o644)
+```
+
+`os.ReadDir` returns `[]os.DirEntry` rather than `[]os.FileInfo` — call `entry.Info()` if you need the old `FileInfo`. Everything else is a drop-in rename.

package/src/discovery/builtin-rules/go-join-hostport.md

@@ -0,0 +1,30 @@
+---
+description: "Build network addresses with net.JoinHostPort, not fmt.Sprintf(\"%s:%d\", host, port) — the Sprintf form breaks on IPv6"
+condition: 'fmt\.Sprintf\("%s:%d"'
+scope: "tool:edit(*.go), tool:write(*.go)"
+interruptMode: never
+---
+
+Use `net.JoinHostPort(host, port)` to assemble a `host:port` address. `fmt.Sprintf("%s:%d", host, port)` produces invalid addresses for IPv6 hosts, which must be bracketed (`[::1]:80`). Go 1.25's `go vet` `hostport` analyzer flags exactly this pattern.
+
+## Why
+
+- An IPv6 literal like `::1` has its own colons, so `fmt.Sprintf("%s:%d", "::1", 80)` yields `::1:80` — unparseable by `net.Dial`.
+- `net.JoinHostPort` adds the brackets when the host contains a colon and leaves IPv4/hostnames untouched.
+
+## Avoid
+
+```go
+addr := fmt.Sprintf("%s:%d", host, port)
+conn, err := net.Dial("tcp", addr)
+```
+
+## Use
+
+```go
+// port is a string here; convert an int with strconv.Itoa.
+addr := net.JoinHostPort(host, strconv.Itoa(port))
+conn, err := net.Dial("tcp", addr)
+```
+
+`net.JoinHostPort` takes the port as a string. For an `int` port, wrap it in `strconv.Itoa`. The function is available in every supported Go version.

package/src/discovery/builtin-rules/go-new-expr.md

@@ -0,0 +1,44 @@
+---
+description: "Use new(expr) for pointer-to-value helpers instead of `func ptr[T any](v T) *T { return &v }` (Go 1.26)"
+interruptMode: never
+scope: "tool:edit(*.go), tool:write(*.go)"
+astCondition:
+  - "func $F($V $T) *$T { return &$V }"
+  - "func $F[$$$TP]($V $T) *$T { return &$V }"
+---
+
+Go 1.26 lets `new` take an expression: `new(expr)` allocates, stores `expr`, and returns its `*T`. That removes the need for hand-written `Ptr`/`boolPtr`/`Int64`-style helpers and the `x := v; p := &x` two-step.
+
+## Why
+
+- One builtin replaces a helper per type (`boolPtr`, `strPtr`, `int64Ptr`, …) and the generic `func Ptr[T any](v T) *T`.
+- No extra function-call frame and no separate heap escape — the value is constructed directly in the allocation.
+- The intent (`new(false)`) reads at the call site instead of hiding behind a helper name.
+
+## Avoid
+
+```go
+// A helper that just takes a value and returns its address.
+func boolPtr(v bool) *bool   { return &v }
+func strPtr(v string) *string { return &v }
+func Ptr[T any](v T) *T       { return &v }
+
+cfg := Config{Enabled: boolPtr(true), Name: strPtr("svc")}
+```
+
+## Use
+
+```go
+cfg := Config{Enabled: new(true), Name: new("svc")}
+
+// Was: x := int64(300); p := &x
+p := new(int64(300))
+```
+
+`new(true)` / `new(false)` give you `*bool`; `new(expr)` works for any expression, including function results (`new(time.Now())`).
+
+## Notes
+
+- Requires Go 1.26+. If the module's `go` directive is older, keep the helper or the temp-variable form until the toolchain is bumped.
+- This is for helpers that *only* take a value and return its address. A function that does real work before taking an address is not in scope.
+- `new(T)` (a bare type) is unchanged and still zero-initializes.

package/src/discovery/builtin-rules/go-rand-v2.md

@@ -0,0 +1,41 @@
+---
+description: Prefer math/rand/v2 over the legacy math/rand package
+condition: '"math/rand"'
+scope: "tool:edit(*.go), tool:write(*.go)"
+interruptMode: never
+---
+
+Use `math/rand/v2` instead of the legacy `math/rand` package (stable since Go 1.22).
+
+## Why
+
+- No global `Seed`: `math/rand`'s top-level functions read a process-global generator (auto-seeded since Go 1.20), so a fixed seed is global mutable state that's easy to misuse; `v2` drops the global `Seed` entirely.
+- Cleaner, better-bounded API: `rand.IntN(n)` / generic `rand.N(n)` replace `rand.Intn(n)`, and `Shuffle`, `Perm`, `Float64` carry over with clearer names.
+- Modern generators: `v2` exposes `PCG` and `ChaCha8` sources instead of the old default LCG.
+
+## Migration
+
+```go
+// Before
+import "math/rand"
+n := rand.Intn(100)
+f := rand.Float64()
+
+// After
+import "math/rand/v2"
+n := rand.IntN(100)
+f := rand.Float64()
+```
+
+| math/rand | math/rand/v2 |
+| --- | --- |
+| `rand.Intn(n)` | `rand.IntN(n)` |
+| `rand.Int63n(n)` | `rand.Int64N(n)` |
+| `rand.Intn`/`Int31n` on a `*Rand` | `(*Rand).IntN` / `Int32N` |
+| `rand.Seed(x)` | drop it — `v2` has no global seed |
+| explicit `rand.New(rand.NewSource(seed))` | `rand.New(rand.NewPCG(s1, s2))` or `rand.NewChaCha8(seed)` |
+
+## Keep math/rand only when
+
+- You need a reproducible stream from a fixed seed via the classic `NewSource`/`Seed` API that a caller already depends on.
+- Reach for `crypto/rand` instead when the values are security-sensitive — neither `math/rand` variant is cryptographically secure.

package/src/discovery/builtin-rules/go-range-int.md

@@ -0,0 +1,45 @@
+---
+description: "Use for i := range n instead of the C-style for i := 0; i < n; i++ loop (Go 1.22)"
+interruptMode: never
+scope: "tool:edit(*.go), tool:write(*.go)"
+astCondition:
+  - "for $I := 0; $I < $N; $I++ { $$$BODY }"
+---
+
+Go 1.22 lets `for` range over an integer. A plain counting loop from `0` to `n` with step `1` reads better as `for i := range n` (or `for range n` when the index is unused).
+
+## Avoid
+
+```go
+for i := 0; i < n; i++ {
+	use(i)
+}
+
+for i := 0; i < len(s); i++ {
+	use(s[i])
+}
+```
+
+## Use
+
+```go
+for i := range n {
+	use(i)
+}
+
+// Ranging the slice directly is usually clearer than indexing.
+for i := range s {
+	use(s[i])
+}
+
+// Index unused → drop it entirely.
+for range n {
+	tick()
+}
+```
+
+## When it does not apply
+
+- Non-zero start, step other than `++`, or a descending loop (`for i := n - 1; i >= 0; i--`) — keep the explicit form.
+- The body reassigns the loop variable or depends on `i` surviving past the loop.
+- Requires Go 1.22+. If the module's `go` directive is older, keep the classic loop.

package/src/discovery/builtin-rules/index.ts

@@ -0,0 +1,74 @@
+/**
+ * Bundled default rules shipped with the coding agent.
+ *
+ * Each markdown source is embedded via `with { type: "text" }` so it survives
+ * `bun build --compile` (the compiled binary ships no loose rule files; only
+ * the embedded text). The native source/tarball installs read the same modules.
+ *
+ * Registered by the lowest-priority `builtin-defaults` rule provider so any
+ * user/project/tool rule with the same name overrides the bundled copy.
+ */
+import goAddCleanup from "./go-add-cleanup.md" with { type: "text" };
+import goBenchLoop from "./go-bench-loop.md" with { type: "text" };
+import goExpPromoted from "./go-exp-promoted.md" with { type: "text" };
+import goIoutil from "./go-ioutil.md" with { type: "text" };
+import goJoinHostport from "./go-join-hostport.md" with { type: "text" };
+import goNewExpr from "./go-new-expr.md" with { type: "text" };
+import goRandV2 from "./go-rand-v2.md" with { type: "text" };
+import goRangeInt from "./go-range-int.md" with { type: "text" };
+import rsBoxLeak from "./rs-box-leak.md" with { type: "text" };
+import rsFuturePrelude from "./rs-future-prelude.md" with { type: "text" };
+import rsLazylock from "./rs-lazylock.md" with { type: "text" };
+import rsMatchErgonomics from "./rs-match-ergonomics.md" with { type: "text" };
+import rsParkingLot from "./rs-parking-lot.md" with { type: "text" };
+import rsResultType from "./rs-result-type.md" with { type: "text" };
+import tsBareCatch from "./ts-bare-catch.md" with { type: "text" };
+import tsImportType from "./ts-import-type.md" with { type: "text" };
+import tsNoAny from "./ts-no-any.md" with { type: "text" };
+import tsNoDeprecatedLeftovers from "./ts-no-deprecated-leftovers.md" with { type: "text" };
+import tsNoDynamicImport from "./ts-no-dynamic-import.md" with { type: "text" };
+import tsNoInlineCastAccess from "./ts-no-inline-cast-access.md" with { type: "text" };
+import tsNoLocalIsRecord from "./ts-no-local-is-record.md" with { type: "text" };
+import tsNoReturnType from "./ts-no-return-type.md" with { type: "text" };
+import tsNoTestTimers from "./ts-no-test-timers.md" with { type: "text" };
+import tsNoTinyFunctions from "./ts-no-tiny-functions.md" with { type: "text" };
+import tsPromiseWithResolvers from "./ts-promise-with-resolvers.md" with { type: "text" };
+import tsRedundantClearGuard from "./ts-redundant-clear-guard.md" with { type: "text" };
+import tsSetMap from "./ts-set-map.md" with { type: "text" };
+
+/** A bundled rule's stable name and raw markdown (frontmatter + body). */
+export interface BuiltinRuleSource {
+	name: string;
+	content: string;
+}
+
+/** All bundled default rules, ordered by name. */
+export const BUILTIN_RULE_SOURCES: readonly BuiltinRuleSource[] = [
+	{ name: "go-add-cleanup", content: goAddCleanup },
+	{ name: "go-bench-loop", content: goBenchLoop },
+	{ name: "go-exp-promoted", content: goExpPromoted },
+	{ name: "go-ioutil", content: goIoutil },
+	{ name: "go-join-hostport", content: goJoinHostport },
+	{ name: "go-new-expr", content: goNewExpr },
+	{ name: "go-rand-v2", content: goRandV2 },
+	{ name: "go-range-int", content: goRangeInt },
+	{ name: "rs-box-leak", content: rsBoxLeak },
+	{ name: "rs-future-prelude", content: rsFuturePrelude },
+	{ name: "rs-lazylock", content: rsLazylock },
+	{ name: "rs-match-ergonomics", content: rsMatchErgonomics },
+	{ name: "rs-parking-lot", content: rsParkingLot },
+	{ name: "rs-result-type", content: rsResultType },
+	{ name: "ts-bare-catch", content: tsBareCatch },
+	{ name: "ts-import-type", content: tsImportType },
+	{ name: "ts-no-any", content: tsNoAny },
+	{ name: "ts-no-deprecated-leftovers", content: tsNoDeprecatedLeftovers },
+	{ name: "ts-no-dynamic-import", content: tsNoDynamicImport },
+	{ name: "ts-no-inline-cast-access", content: tsNoInlineCastAccess },
+	{ name: "ts-no-local-is-record", content: tsNoLocalIsRecord },
+	{ name: "ts-no-return-type", content: tsNoReturnType },
+	{ name: "ts-no-test-timers", content: tsNoTestTimers },
+	{ name: "ts-no-tiny-functions", content: tsNoTinyFunctions },
+	{ name: "ts-promise-with-resolvers", content: tsPromiseWithResolvers },
+	{ name: "ts-redundant-clear-guard", content: tsRedundantClearGuard },
+	{ name: "ts-set-map", content: tsSetMap },
+];

package/src/discovery/builtin-rules/rs-box-leak.md

@@ -0,0 +1,49 @@
+---
+description: Never use Box::leak - it intentionally leaks memory
+condition: "Box::leak"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+interruptMode: never
+---
+
+Never use `Box::leak` to satisfy a lifetime. It intentionally leaks the allocation for the rest of the process.
+
+## Why
+
+- The allocation is never freed.
+- It hides ownership bugs.
+- It turns lifetime errors into process lifetime growth.
+- It makes tests pass while production memory grows.
+
+## Use instead
+
+| Need | Use |
+| --- | --- |
+| Shared async/thread data | `Arc<T>` or owned values |
+| Global lazy state | `LazyLock<T>` or `OnceLock<T>` |
+| Text escaping a scope | `String` / `Arc<str>` |
+| `'static` callback | `move` closure with owned captures |
+| FFI pointer | Explicit owner that frees on drop |
+
+## Examples
+
+```rust
+// Bad — leaking to manufacture 'static.
+fn label(id: u64) -> &'static str {
+    Box::leak(Box::new(format!("item_{id}")))
+}
+
+// Good — return owned data.
+fn label(id: u64) -> String {
+    format!("item_{id}")
+}
+
+// Bad — leaking before spawn.
+let state = Box::leak(Box::new(state));
+tokio::spawn(async move { use_state(state) });
+
+// Good — share owned state.
+let state = Arc::new(state);
+tokio::spawn(async move { use_state(&state) });
+```
+
+If `Box::leak` looks necessary, fix ownership instead.

package/src/discovery/builtin-rules/rs-future-prelude.md

@@ -0,0 +1,24 @@
+---
+description: Use Future not std::future::Future - it's in the prelude
+condition: "std::future::Future"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+interruptMode: never
+---
+
+Use `Future` directly instead of `std::future::Future` in type positions.
+
+Rust 2024 includes `Future` in the standard prelude. Older editions can import it once with `use std::future::Future;`. Repeating the fully qualified path makes signatures harder to read without adding safety.
+
+## Examples
+
+```rust
+// Bad — fully qualified in every signature.
+fn fetch() -> impl std::future::Future<Output = Result<Data>> { ... }
+fn poll(fut: Pin<&mut dyn std::future::Future<Output = i32>>) { ... }
+
+// Good — use the prelude or one import.
+fn fetch() -> impl Future<Output = Result<Data>> { ... }
+fn poll(fut: Pin<&mut dyn Future<Output = i32>>) { ... }
+```
+
+Pre-2024 edition? Add `use std::future::Future;` at the top.

package/src/discovery/builtin-rules/rs-lazylock.md

@@ -0,0 +1,52 @@
+---
+description: Prefer std::sync::LazyLock over OnceLock and once_cell
+condition:
+  - "once_cell::"
+  - "OnceLock::new"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+interruptMode: never
+---
+
+Prefer `std::sync::LazyLock` over `OnceLock` and the `once_cell` crate when the initializer is known at declaration time.
+
+`LazyLock` stores the cell and initializer together. There is no separate `init()` function, no repeated `get_or_init`, and no missing initialization path.
+
+## once_cell → std
+
+```rust
+// Before
+use once_cell::sync::Lazy;
+static CONFIG: Lazy<String> = Lazy::new(|| "value".to_string());
+
+// After
+use std::sync::LazyLock;
+static CONFIG: LazyLock<String> = LazyLock::new(|| "value".to_string());
+```
+
+## OnceLock → LazyLock
+
+```rust
+// Before — fixed initializer hidden in accessor.
+use std::sync::OnceLock;
+static SETTINGS: OnceLock<Settings> = OnceLock::new();
+fn settings() -> &'static Settings {
+    SETTINGS.get_or_init(Settings::load)
+}
+
+// After — initializer lives with the static.
+use std::sync::LazyLock;
+static SETTINGS: LazyLock<Settings> = LazyLock::new(Settings::load);
+```
+
+## Keep OnceLock when runtime input is required
+
+```rust
+use std::sync::OnceLock;
+static DATABASE: OnceLock<Database> = OnceLock::new();
+
+fn init_database(url: &str) {
+    let _ = DATABASE.set(Database::connect(url));
+}
+```
+
+Do not add `once_cell` for new code. Use the standard library equivalent.

package/src/discovery/builtin-rules/rs-match-ergonomics.md

@@ -0,0 +1,68 @@
+---
+description: Use match ergonomics instead of ref/ref mut patterns
+condition:
+  - "\\(ref mut "
+  - "\\(ref [a-z_]"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+interruptMode: never
+---
+
+Use match ergonomics instead of explicit `ref` / `ref mut` patterns. Borrow the scrutinee and let bindings receive references.
+
+## Shared references
+
+```rust
+// Before
+match value {
+    Some(ref item) => println!("{item}"),
+    None => {}
+}
+
+// After
+match &value {
+    Some(item) => println!("{item}"),
+    None => {}
+}
+
+if let Some(item) = &value {
+    println!("{item}");
+}
+```
+
+## Mutable references
+
+```rust
+// Before
+match value {
+    Some(ref mut item) => *item += 1,
+    None => {}
+}
+
+// After
+match &mut value {
+    Some(item) => *item += 1,
+    None => {}
+}
+
+if let Some(item) = &mut value {
+    *item += 1;
+}
+```
+
+## Result
+
+```rust
+// Before
+match result {
+    Ok(ref data) => println!("{data}"),
+    Err(ref err) => eprintln!("{err}"),
+}
+
+// After
+match &result {
+    Ok(data) => println!("{data}"),
+    Err(err) => eprintln!("{err}"),
+}
+```
+
+Modern Rust rarely needs `ref` in patterns. Borrow the value being matched.

package/src/discovery/builtin-rules/rs-parking-lot.md

@@ -0,0 +1,45 @@
+---
+description: Use parking_lot instead of std::sync for Mutex/RwLock
+condition:
+  - "\\.lock\\(\\)\\.unwrap\\(\\)"
+  - "\\.read\\(\\)\\.unwrap\\(\\)"
+  - "\\.write\\(\\)\\.unwrap\\(\\)"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+interruptMode: never
+---
+
+Use `parking_lot::{Mutex, RwLock}` instead of `std::sync::{Mutex, RwLock}` when code immediately unwraps lock results.
+
+## Why
+
+- `lock()`, `read()`, and `write()` return guards directly.
+- No poisoning error path to unwrap.
+- Guards are smaller and faster in common contention cases.
+- The call site shows locking, not error handling boilerplate.
+
+## Migration
+
+```rust
+// Before
+use std::sync::Mutex;
+let data = Mutex::new(Vec::new());
+let guard = data.lock().unwrap();
+
+// After
+use parking_lot::Mutex;
+let data = Mutex::new(Vec::new());
+let guard = data.lock();
+```
+
+## Equivalents
+
+| std::sync | parking_lot |
+| --- | --- |
+| `Mutex<T>` | `Mutex<T>` |
+| `RwLock<T>` | `RwLock<T>` |
+| `Condvar` | `Condvar` |
+| `Once` | `Once` |
+
+## Keep async locks async
+
+Use `tokio::sync::Mutex` / `tokio::sync::RwLock` when a guard is held across `.await` or the lock belongs to async coordination.

package/src/discovery/builtin-rules/rs-result-type.md

@@ -0,0 +1,20 @@
+---
+description: Result type aliases must include a defaulted error type parameter
+condition: "type\\s+Result<[A-Za-z_]\\w*>\\s*="
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+interruptMode: never
+---
+
+`Result` aliases must expose the error type as a defaulted parameter.
+
+```rust
+pub type Result<T, E = anyhow::Error> = std::result::Result<T, E>;
+```
+
+Never write:
+
+```rust
+type Result<T> = std::result::Result<T, anyhow::Error>;
+```
+
+The default keeps common call sites short while preserving escape hatches for precise errors.

package/src/discovery/builtin-rules/ts-bare-catch.md

@@ -0,0 +1,39 @@
+---
+description: Use bare `catch {` when the error binding is unused
+condition: "catch \\(_"
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+interruptMode: never
+---
+
+Use bare `catch {}` when the caught value is unused. An underscore-prefixed binding adds noise and still allocates a local name.
+
+## Replace
+
+```typescript
+// Bad
+try {
+	await loadConfig();
+} catch (_err) {
+	return null;
+}
+
+// Good
+try {
+	await loadConfig();
+} catch {
+	return null;
+}
+```
+
+## Keep a real name when used
+
+```typescript
+try {
+	await saveConfig();
+} catch (err) {
+	logger.error("save failed", { err });
+	throw err;
+}
+```
+
+Unused error? Bare `catch`. Used error? Name it for what it carries.

package/src/discovery/builtin-rules/ts-import-type.md

@@ -0,0 +1,43 @@
+---
+description: "Use `import type`, not `import('pkg').Type` in type positions"
+condition: "import\\("
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+interruptMode: never
+---
+
+Use top-level `import type` declarations for type-only dependencies. NEVER write `import("pkg").Type` inside source annotations.
+
+## Why
+
+- Top-level imports expose dependencies immediately.
+- Import sorting and deduplication can manage them.
+- Signatures stay readable and reviewable.
+- Re-exports do not inherit noisy inline paths.
+
+## Avoid
+
+```typescript
+// Bad — inline imports hide dependencies in signatures.
+function run(client: import("some-sdk").Client, input: import("arktype").infer<Schema>): Promise<Output>;
+
+// Bad — annotations become path dumps.
+const options: import("some-sdk/config").ClientOptions = { ... };
+```
+
+## Use
+
+```typescript
+import type { Client } from "some-sdk";
+import type { ClientOptions } from "some-sdk/config";
+import type { infer as Infer } from "arktype";
+
+function run(client: Client, input: Infer<Schema>): Promise<Output>;
+const options: ClientOptions = { ... };
+```
+
+## Exceptions
+
+- Ambient `.d.ts` globals that must not become modules.
+- Generated files whose generator owns import management.
+
+In normal `.ts` / `.tsx` source, use `import type`.