deps: condense fuz-stack skill

Author: ryanatkn

skills/fuz-stack/SKILL.md

@@ -268,8 +268,10 @@ patterns, and drift-detection guidance.
   period; multi-sentence: capitalize, end with period
 - `@returns` (not `@return`): same single/multi-sentence rule as `@param`
 - `@module`: complex modules get a module-level doc comment with `@module` at end
-- `@mutates target - description`: document parameter/state mutations
-  (also `` @mutates `target` `` for self-evident mutations)
+- `@mutates target - description`: document parameter/state mutations. The
+  description carries the tag — name the columns, cascades, or side channels a
+  reader wouldn't guess. When the method name already says it, omit the tag
+  rather than writing a bare `` @mutates `target` ``
 - `@nodocs`: exclude from docs and flat namespace validation
 - Wrap identifier references in backticks for auto-linking via `mdz`
 
@@ -334,16 +336,18 @@ caveat, anti-patterns, and formatter cautions.
 
 ## Svelte 5 Patterns
 
-See ./references/svelte-patterns.md for `$state.raw()`, `$derived.by()`,
-reactive collections (SvelteMap/SvelteSet), schema-driven reactive classes,
-snippets, effects, attachments, props, event handling, component composition,
-and legacy features to avoid.
+See ./references/svelte-patterns.md for `$derived.by()`, reactive collections
+(SvelteMap/SvelteSet), schema-driven reactive classes, snippets, effects,
+attachments, props, event handling, component composition, and legacy features
+to avoid.
 
 ### Runes API
 
-`$state.raw()` by default for all reactive state. `$state()` only for
-arrays/objects mutated in place (push, splice, index assignment). `$derived`
-for computed values, `$effect` for side effects.
+`$state()` for all reactive state — it proxies objects and arrays so in-place
+mutation (push, splice, property writes, `bind:` on object properties) triggers
+updates. `$state.raw()` is a performance opt-out for large wholesale-replaced
+values, not a default. `$derived` for computed values, `$effect` for side
+effects.
 
 ### Context Pattern
 
@@ -392,20 +396,19 @@ no `<style>` block at all.
 5. Literal classes (`display:flex`, `width:100%`, `hover:opacity:80%`)
 6. `<style>` block with design tokens
 
-Rungs 3–5 are one tier in practice — mix freely (a composite when one exactly
-matches, else tokens/literals); literal flex classes are common, not a rare last
-resort. The real cut points are semantic-vs-class and classes-vs-`<style>`. Don't
-churn existing `<style>` blocks into long class strings (4–6 classes is the
-comfortable ceiling). See css-patterns.md §Default styling is the baseline.
+Rungs 3–5 are one tier in practice — mix freely; the real cut points are
+semantic-vs-class and classes-vs-`<style>`. Don't churn existing `<style>`
+blocks into long class strings. See ./references/css-patterns.md §The Styling
+Ladder.
 
 **Class naming**: fuz_css tokens use `snake_case` (`p_md`, `gap_lg`);
 component-local classes use `kebab-case` (`site-header`) — the target convention,
 adopted in zzz and fuz_ui.
 
 Architecture — the three layers (semantic defaults, design tokens, utility
 classes), the class families, and the classes-vs-`<style>` matrix: see
-css-patterns.md §Style Variables (Design Tokens), §Utility Classes, and
-§When to Use Classes vs Styles.
+./references/css-patterns.md §Style Variables (Design Tokens), §Utility
+Classes, and §When to Use Classes vs Styles.
 
 ## Dependency Injection
 
@@ -463,7 +466,9 @@ metadata, CLI help text, and serialization. Schema changes cascade through the
 stack; treat them as critical review points.
 
 - **`z.strictObject()`** — default for all object schemas. `z.looseObject()`
-  or `z.object()` for external/third-party data with a comment explaining why.
+  or `z.object()` for external/third-party data, client-consumed
+  response/error schemas, and protocol shapes the other side may extend —
+  with a comment explaining why.
 - **PascalCase naming** — schema and type share the same name, no suffix:
   `const Foo = z.strictObject({...}); type Foo = z.infer<typeof Foo>;`
 - **`.meta({description: '...'})`** — not `.describe()`. Both work in Zod 4

skills/fuz-stack/references/async-patterns.md

@@ -16,25 +16,6 @@ Lifecycle type for tracking async operations in UI:
 type AsyncStatus = 'initial' | 'pending' | 'success' | 'failure';
 ```
 
-## Basic Utilities
-
-### wait
-
-```typescript
-await wait(500); // wait 500ms
-await wait(); // wait 0ms (next macrotask via setTimeout)
-```
-
-### is_promise
-
-Type guard for Promise/thenable detection:
-
-```typescript
-if (is_promise(value)) {
-	const result = await value;
-}
-```
-
 ## Deferred Pattern
 
 Separates promise creation from resolution — external control over when and

skills/fuz-stack/references/code-generation.md

@@ -213,15 +213,9 @@ gro gen src/lib/foo.gen.ts  # run a specific gen file
 gro gen --check      # verify no drift (used by gro check and CI)
 ```
 
-| Arg           | Default           | Description                                      |
-| ------------- | ----------------- | ------------------------------------------------ |
-| `_`           | `['src']`         | input paths (files or directories to scan)       |
-| `--root_dirs` | `[process.cwd()]` | root directories to resolve input paths against  |
-| `--check`     | `false`           | exit nonzero if any generated files have changed |
-
-`gro gen --check` compares generated output against existing files; if any is
-new or changed, it fails with a message to run `gro gen`. Called by `gro check`
-as part of CI.
+Positional args default to `['src']`; `--root_dirs` (default `[process.cwd()]`)
+resolves them. `gro gen --check` compares generated output against existing
+files and fails if any is new or changed — called by `gro check` as part of CI.
 
 ## Common Patterns
 

skills/fuz-stack/references/common-utilities.md

@@ -217,20 +217,10 @@ nominal typing and strict utility types.
 
 ### `swallow`
 
-Claims an event by preventing its default action and stopping propagation:
-
-```typescript
-import { swallow } from '@fuzdev/fuz_util/dom.ts';
-
-swallow(event); // preventDefault + stopImmediatePropagation
-swallow(event, false); // preventDefault + stopPropagation (non-immediate)
-swallow(event, true, false); // stopImmediatePropagation only (no preventDefault)
-```
-
-Design principle: if you `preventDefault`, you're claiming the event — use
-`swallow` to also stop propagation. Parents needing to observe before children
-claim should use the `capture` phase. See ./svelte-patterns.md
-§Event Handling for full guidance.
+Claims an event by preventing its default action and stopping propagation —
+`swallow(event, immediate?, preventDefault?)`. The design principle (handling
+an event = claiming it) and usage guidance: ./svelte-patterns.md §Event
+Handling.
 
 ### `handle_target_value`
 

skills/fuz-stack/references/documentation-system.md

@@ -367,22 +367,11 @@ consumers unchanged (see [Cross-Project Pattern](#cross-project-pattern)).
 
 ## Cross-Project Pattern
 
-fuz_ui **defines** all documentation components and the analysis pipeline.
-Other projects **import** them:
-
-```typescript
-// In fuz_ui (defines the components)
-import Docs from './Docs.svelte';
-import { library_context } from './library.svelte.ts';
-
-// In fuz_css or any consumer project
-import Docs from '@fuzdev/fuz_ui/Docs.svelte';
-import { library_context } from '@fuzdev/fuz_ui/library.svelte.ts';
-```
-
-Layout structure is identical — only tomes, categories, and breadcrumb
-branding differ. The `svelte-docinfo` Vite plugin and `virtual:svelte-docinfo`
-are the shared analysis engine across projects.
+fuz_ui **defines** all documentation components and the analysis pipeline;
+other projects import them unchanged from `@fuzdev/fuz_ui/*`. Layout structure
+is identical — only tomes, categories, and breadcrumb branding differ. The
+`svelte-docinfo` Vite plugin and `virtual:svelte-docinfo` are the shared
+analysis engine across projects.
 
 ## See Also
 

skills/fuz-stack/references/file-organization.md

@@ -73,20 +73,6 @@ import { create_app_backend } from '@fuzdev/fuz_app/server/app_backend.ts';
 
 ## Tests Mirror the Subdirectory Structure
 
-Tests live in `src/test/` (NOT co-located) and mirror `src/lib/` subdirectories:
-
-```
-src/test/
-├── env/
-│   ├── load.test.ts
-│   ├── resolve.test.ts
-│   ├── dotenv.test.ts
-│   └── mask.test.ts
-├── auth/
-│   ├── keyring.test.ts
-│   └── account_queries.db.test.ts  # .db.test.ts suffix for PGlite tests
-└── server/
-    └── env.test.ts     # server-specific env (BaseServerEnv, validate_server_env)
-```
-
+Tests live in `src/test/` (NOT co-located) and mirror `src/lib/`
+subdirectories — `src/lib/auth/keyring.ts` → `src/test/auth/keyring.test.ts`.
 See ./testing-patterns.md for the full test file layout, naming, and fixtures.

skills/fuz-stack/references/rust-dependencies.md

@@ -53,7 +53,7 @@ deps and belong here.
 | `url`                                                      | URL parsing                                                                                            |
 | `tempfile`                                                 | Temp files/dirs (`NamedTempFile`)                                                                      |
 | `smallvec`                                                 | Stack-allocated small vectors                                                                          |
-| `bumpalo`                                                  | Arena allocation (`collections` feature) — tsv's core AST strategy; see rust-perf.md §Arena allocation |
+| `bumpalo`                                                  | Arena allocation (`collections` feature) — tsv's core AST strategy; see ./rust-perf.md §Arena allocation |
 | `string-interner`                                          | String interning                                                                                       |
 | `phf`                                                      | Compile-time perfect-hash maps/sets (keyword tables)                                                   |
 | `unicode-ident` / `unicode-segmentation` / `unicode-width` | Unicode text handling                                                                                  |
@@ -75,7 +75,7 @@ deps and belong here.
 
 | Crate         | Purpose                                                                                                                                                     |
 | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `parking_lot` | `Mutex`/`RwLock` for sync-only critical sections (no poisoning). See rust-perf.md §Async lock hygiene for when to use `tokio::sync` or `std::sync` instead. |
+| `parking_lot` | `Mutex`/`RwLock` for sync-only critical sections (no poisoning). See ./rust-perf.md §Async lock hygiene for when to use `tokio::sync` or `std::sync` instead. |
 | `lru`         | Bounded LRU cache backing the `RateLimiter` — caps tracked keys so a key-enumeration attacker can't grow the map unboundedly (twin of fuz_app's `LruMap`).  |
 
 ## Database
@@ -112,7 +112,7 @@ deps and belong here.
 
 | Crate  | Purpose                                                                                             |
 | ------ | --------------------------------------------------------------------------------------------------- |
-| `argh` | Derive arg parser, size-optimized. See rust-patterns.md §CLI Patterns for the parser-tier guidance. |
+| `argh` | Derive arg parser, size-optimized. See ./rust-patterns.md §CLI Patterns for the parser-tier guidance. |
 
 ## Logging
 
@@ -133,7 +133,7 @@ deps and belong here.
 | `wit-bindgen`                         | Component-model bindings                                                                                                                                                                                                                                                                      |
 | `wasmtime` / `wasmtime-wasi`          | WASM host (tests, benches)                                                                                                                                                                                                                                                                    |
 
-See wasm-patterns.md for the binding-layer conventions these support.
+See ./wasm-patterns.md for the binding-layer conventions these support.
 
 ## Image processing
 
@@ -157,31 +157,22 @@ dependency graph or it is not, and that is auditable.
 - Enforcement is the `cargo xtask check-release` dep-graph audit (`fuz_audit`),
   which fails if any non-`testing_`-prefixed binary transitively links a
   forbidden crate; workspaces add extra forbids via `AuditRules`. See
-  rust-spine.md §xtask & check-release for the entry points and the
+  ./rust-spine.md §xtask & check-release for the entry points and the
   built-in layering rules.
 
-## Shared low-level leaves (consolidation candidates)
-
-The pattern is proven: the sandboxed config-eval harness was extracted from
-zap into the spine's `fuz_eval` — a spine-free leaf (no tokio-server/HTTP/DB
-surface) consumable even by spine-free repos — and is now shared across
-consumers, including the JS wrapper ingredients themselves
-(`DETERMINISM_STUBS_JS`, `CONSOLE_TO_STDERR_JS`,
-`build_extract_export_wrapper`). Remaining candidates, still independently
-reimplemented:
-
-- a minimal dotenv (`KEY=VALUE`) parser — three copies today (`zap_core`,
-  plus two inside zzz: the CLI's daemon-env loader and its xtask),
-- an env-isolating subprocess harness with a capped output drain —
-  prototyped in `fuz_forge_server`, promotion deferred until a second
-  consumer,
-- the atomic-write/flock transactional-file dance for spine-free consumers —
-  `fuz_sys::fs::write_atomic` is canonical but zap can't link it and
-  hand-rolls both authority calibrations (rust-patterns.md §Transactional
-  state files),
-- an exponential-backoff retry combinator — no generic one exists;
-  `fuz_sidecar`'s crash-recovery respawn loop is the only backoff
-  implementation, and it's supervision-shaped, not request-retry.
+## Shared low-level leaves
+
+**When a utility gets reimplemented a third time, extract it as a spine-free
+leaf** — no tokio-server/HTTP/DB surface, so spine-free repos can link it too.
+`fuz_eval` (the sandboxed config-eval harness, lifted out of zap) is the proven
+case, now shared down to its JS wrapper ingredients.
+
+Known-duplicated, not yet extracted: a minimal dotenv (`KEY=VALUE`) parser
+(three copies), an env-isolating subprocess harness with a capped output drain
+(one, awaiting a second consumer), the atomic-write/flock dance for consumers
+that can't link `fuz_sys::fs::write_atomic` (./rust-patterns.md §Transactional
+state files), and an exponential-backoff retry combinator (none generic today —
+the only backoff is supervision-shaped, not request-retry).
 
 Signal-crate convention: prefer `nix` for syscall wrappers; reserve `libc` for
 types/constants `nix` doesn't expose (PTY). Avoid pulling both into one
@@ -192,7 +183,7 @@ workspace for the same job.
 - **`default-features = false` + explicit feature lists** for deps with heavy
   optional trees — `reqwest`, `nix`, `notify`, `futures-util` all do. Opt into
   exactly what the workspace uses; don't inherit a crate's default surface.
-- **`multiple_crate_versions = "allow"`** (rust-patterns.md §Lints) tolerates
+- **`multiple_crate_versions = "allow"`** (./rust-patterns.md §Lints) tolerates
   _forced_ duplicate majors from the dep graph — e.g. `tsv` carries hashbrown
   0.16 (via `string-interner`) and 0.17 (via `serde_json` → `indexmap`),
   unresolvable until `string-interner` bumps upstream. Not a license to ignore

skills/fuz-stack/references/rust-patterns.md

@@ -430,7 +430,7 @@ struct — `Keyring` deliberately has no trait.)
 trait": a one-shot injection point that must be generic over the consumer's
 type gets a boxed-`FnOnce` type alias, not a trait —
 `ExtraActionSpecsFactory<App>` / `PreMigrationHook<E>`
-(`fuz_actions::consumer_lifecycle`; see rust-spine.md §Server lifecycle).
+(`fuz_actions::consumer_lifecycle`; see ./rust-spine.md §Server lifecycle).
 The caller supplies it once at startup; test binaries hook through it; no
 trait ceremony accrues. A trait earns the slot only when the seam has
 multiple methods or long-lived polymorphic state.
@@ -701,20 +701,13 @@ key can capture.
 
 ### Sidecar controller
 
-The pattern for a long-running subprocess multiplexing many concurrent
-requests: a spawn config of function pointers (statically-known runtimes),
-JSON-lines framing over stdin/stdout, an mpsc command channel into a
-serializer task that owns stdin, per-request `oneshot` responses parked in a
-map keyed by request id, and the script embedded via `include_str!` + written
-to a `NamedTempFile` at spawn. Skip it for one-shot invocations (plain
-`tokio::process::Command`) or pure in-process work.
-
-**Currently dormant** — the sidecar _runtimes_ (`fuz_deno`/`fuz_python`
-factories, behind `fuzd`'s off-by-default `sidecar` feature) are gated off, so
-the shipped daemon wires no runtime into the pool; `fuz_sidecar` itself always
-links into `fuzd`/`fuzd_server` for the empty pool and dispatch (tsv replaced
-the Deno sidecar's parsing role). The controller and its crash-recovery
-respawn loop (exponential backoff, capped) remain the reference if a
+For a long-running subprocess multiplexing many concurrent requests: a spawn
+config of function pointers (statically-known runtimes), JSON-lines framing
+over stdin/stdout, an mpsc command channel into a serializer task that owns
+stdin, per-request `oneshot` responses parked in a map keyed by request id, and
+the script embedded via `include_str!`. Skip it for one-shot invocations (plain
+`tokio::process::Command`) or pure in-process work. **Dormant** — no shipped
+binary wires a runtime into the pool today; `fuz_sidecar` is the reference if a
 runtime-hosting workload returns.
 
 ### Security