API docs - @fuzdev stack

fuz_docs

experimental AI-generated docs and skills for Fuz, a zippy stack for human agency 📜

docs.fuz.dev

introduction #

Overview
#

fuz_docs is an experimental website with AI-generated documentation and agent skills for Fuz, a zippy stack for human agency. It's a poorly-reviewed actively-evolving dumping ground of conventions, patterns, and reference material for @fuzdev projects. Everything is in flux, not all patterns are endorsed, and some content is plain slop.

This website is designed for both human and machine consumption. Humans are welcome to browse docs and skills, but expect rough edges.

Skills
#

AI agent skills are structured knowledge files that Claude Code loads for context. Each skill has a main SKILL.md and optional detailed references.

Skill	Purpose
fuz-stack	Coding conventions and patterns for TypeScript and Svelte 5 projects
grimoire	Cross-repo coordination with lore, quests, and skills

Browse all skills at /skills.

Reference
#

Auto-generated documentation from the @fuzdev ecosystem.

Docs	Contents
stack	Toolchain versions, all packages, dependency graph
api	Auto-generated TypeScript and Svelte API documentation
library	Package metadata and exports

Stack
#

fuz_util → gro + fuz_css → fuz_ui → fuz_* apps

gro is the durable web-dev workflow surface — its internals progressively adopt Rust (tsv, then fuz crates) while it stays complementary to fuz and zap. See stack for details.

fuz-stack #

Overview
#

Coding conventions and patterns for the @fuzdev TypeScript and Svelte 5 ecosystem. These conventions keep agent-assisted development consistent across ~20 repos — from naming and file organization to error handling, testing, and validation patterns.

This content is AI-generated and mostly poorly reviewed. Not all patterns described here are endorsed, and some may be out of date or incorrect.

The full skill documentation is at skills/fuz-stack.

Conventions
#

Area	Convention
Naming	snake_case functions/variables, PascalCase types/components, SCREAMING_SNAKE_CASE constants
File organization	`src/lib/` for library code, `src/test/` for tests (not co-located), `src/routes/` for SvelteKit
Imports	Import by real source extension (`.ts`/`.svelte.ts`), directly from source (no barrels/re-exports)
Formatting	`tsv` with tabs, 100 char width
Breaking changes	Acceptable — delete unused code, don't shim or alias
Flat namespace	All exported identifiers unique across all modules; the `svelte-docinfo` analysis enforces
Build	`gro check` runs typecheck + test + gen --check + format --check + lint

// snake_case functions — domain-prefix when bare name would be ambiguous
function git_push() {}  // git_* cluster, "push" alone is ambiguous
function truncate() {}  // action-first, self-descriptive

// PascalCase types and components
type PackageJson = {};
// file: DocsLink.svelte

// real source extension in imports (.ts, not the old .js form)
import {git_push} from './git.ts';

Core patterns
#

Beyond surface conventions, several deeper patterns define how @fuzdev code is structured:

Pattern	Convention
Error handling	`Result<TValue, TError>` discriminated union — never throw for expected errors
Dependency injection	Small `*Deps` interfaces for all I/O, plain object mocks — no mocking libraries
Validation	`z.strictObject()` by default, PascalCase schema naming, `.brand()` for nominal types
Testing	Fixture-based testing for parsers — input files, generated `expected.json`, never manually edit

// Result pattern — properties directly on the result object
function parse_config(text: string): Result<{value: Config}, {error: ParseError}> {
	return {ok: true, value: JSON.parse(text)};
}

// Deps pattern — small interfaces, no god types
export interface FsDeps {
	read_file: (path: string) => Promise<string>;
	write_file: (path: string, content: string) => Promise<void>;
}

References
#

22 detailed reference documents:

Reference	Covers
Async Patterns	Concurrency primitives — semaphore, deferred, concurrent map/each
Code Generation	Gro gen system — .gen.* files, dependencies, output formats
Common Utilities	Result type, Logger, Timings, DAG execution
CSS Patterns	fuz_css styling — default-reliance, the styling ladder, variables, extraction
Dependency Injection	Injectable *Deps interfaces, mock factories, composition patterns
Documentation System	Docs pipeline — Tome system, layout architecture, project setup
File Organization	src/ tree, domain subdirectories, full-path imports, test mirroring
mdz — Strict Markdown Dialect	mdz dialect — grammar surface, component registration, rendering seam, autolink, preprocessor
Approved npm Dependencies	Approved external npm package allowlist for TS/Svelte repos
Path References in Documentation	Path typography — navigational vs src/lib module vs code-shaped
Approved Rust Dependencies	Approved external crate allowlist for Rust workspaces
Rust Patterns for the Fuz Ecosystem	Rust lints, errors, DI ladder, idioms, CLI patterns
Rust Performance Patterns	Rust perf — profiling, arenas, locks, hot-path idioms, SIMD
Rust Spine & Consumer Servers	Spine crate map, consumer servers, env, daemon lifecycle
Svelte 5 Patterns	Svelte 5 runes, contexts, snippets, attachments
Task Patterns	Gro task system — .task.ts files, TaskContext, error handling
Testing Patterns	Vitest patterns, fixtures, mocks, assertion helpers
TSDoc Comment Style Guide	TSDoc style guide — tags, conventions, drift detection
Twin Implementations (TS ↔ Rust)	TS ↔ Rust twin implementations — convergence, naming parity, wire crates
Type Utilities	Nominal typing (Flavored/Branded), strict utility types
WASM Patterns for the Fuz Ecosystem	WASM/N-API build targets — wasm-bindgen, component model, JS interop
Zod Schemas	Zod conventions — strictObject, branded types, introspection

Stack
#

fuz_util → gro + fuz_css → fuz_ui → fuz_* apps

gro is the durable web-dev workflow surface — its internals progressively adopt Rust (tsv, then fuz crates) while it stays complementary to fuz and zap. See stack for the full dependency graph and package details.

For cross-repo coordination patterns — planning, TODOs, and multi-repo goals — see grimoire.

grimoire #

Overview
#

Units of work often cut across repos — a type change ripples through three packages, a new feature needs coordinated planning in four. A grimoire gives those units a home without polluting implementation repos with planning artifacts. It's a markdown meta-repo that holds working understanding: what was decided and why, what's next, what connects to what.

For AI agents, a grimoire is persistent memory across stateless sessions. Each agent arrives fresh, reads the grimoire to orient, does work, and updates it before the session ends. The grimoire bridges what one session learned to the next.

The full skill documentation is at skills/grimoire.

Structure
#

Three core primitives, plus supporting layers that emerge as the grimoire grows:

Primitive	Location	Purpose
Lore	`lore/{project}/`	Per-repo planning projections — decisions, TODOs, cross-cutting concerns. Standard pair: `CLAUDE.md` + `TODO.md`
Quests	`quests/`	Cross-repo goals with dependencies and completion criteria. Single-repo work stays in lore TODOs
Skills	`skills/{name}/`	Agent skill knowledge files — conventions, references, and tooling scripts

grimoire/
├── lore/           # per-repo planning projections
│   └── {project}/
│       ├── CLAUDE.md    # planning context, decisions
│       └── TODO.md      # active work items
├── quests/         # cross-repo goals
│   ├── CLAUDE.md        # quest index
│   └── {slug}.md        # individual quests
├── skills/         # agent knowledge modules
│   └── {name}/
│       └── SKILL.md
└── writing/        # philosophy and vision (not repo-scoped)

writing/ holds ideas that span the whole ecosystem rather than projecting a single repo — design philosophies, conceptual foundations. Supporting directories like scripts/ and scries/ for experimental linting may emerge from need; a new grimoire starts with just lore/ and grows.

Work loop
#

Each agent session reads the grimoire to orient, does the work, then writes back what changed.

Phase	Action
Orient	Read `lore/{project}/` for planning context and TODOs. Check `quests/` for cross-repo goals touching this project. Read the repo's own `CLAUDE.md` for implementation context.
Work	Do the implementation work in the target repo.
Update	Update `TODO.md` for work items. Check off quest tasks. Update `CLAUDE.md` if decisions changed.
Graduate	Should content advance? Done quests synthesize into lore, then get deleted. Ideas that matured into code get removed from TODOs.

Knowledge lifecycle
#

Content flows forward through stages and gets deleted from earlier ones when it graduates — existing in one place at a time, wherever it's most useful right now.

lore → quest → implementation → published → lore
 (ideas)  (goals)    (code)        (docs)     (new understanding)

The cycle turns at different speeds — ideas accumulate slowly in lore, quests can move fast through implementation — but content should exist in one place at a time, wherever it's most useful right now.

Key ideas
#

Taste. A grimoire encodes a developer's preferences — which patterns are valued, which tradeoffs are preferred, what "good" looks like. This is what makes a grimoire yours rather than generic documentation. Agents can apply taste fluidly rather than following rigid rules.

Always slightly wrong. A grimoire is approximate context, not ground truth. It's trying to capture dimensions of a person's entire body of work — too large for any document to represent faithfully. When current state matters, read the actual repo. Past a certain threshold of staleness, a doc misleads more than it helps.

Rewrite, don't just prune. Conceptual staleness — content whose framing no longer matches reality — is more dangerous than old files. A lore doc untouched for months can still be accurate; a freshly-written TODO that assumes yesterday's architecture misleads immediately. Delete what's dead, rewrite what's drifted. The grimoire stays useful by staying accurate, not just lean.

Growth trajectory. A grimoire starts small — one CLAUDE.md, a couple of TODO.md files. Quests appear when work first spans multiple repos. Writing appears when ideas emerge that don't project any single repo. Don't build structure speculatively.

More
#

For full conventions — lore structure, quest format, creating new artifacts, common pitfalls — see the grimoire skill. For coding conventions across the @fuzdev ecosystem, see fuz-stack.

stack #

Dependency map
#

show dev dependencies

apps sites fullstack UI styling build tooling foundation

drag to pan · scroll to zoom · click a node to trace its dependencies

Toolchain
#

Tool	Version
rustc	`rustc 1.94.1 (e408947bf 2026-03-25)`
cargo	`cargo 1.94.1 (29ea6fb6a 2026-03-24)`
node	`v24.14.1`
svelte	`5.56.2`
sveltekit	`2.63.0`
typescript	`5.9.3`
gro	`0.205.1`
prettier	`3.7.4`
vitest	`4.1.9`

TypeScript and Svelte packages
#

13 packages, 584 exported modules (626 total), 3094 exports

Package	Version	Description	Modules	Exports	Published
🦕 @fuzdev/fuz_util	`0.65.2`	utility belt for JS	58	455	yes
🌰 @fuzdev/gro	`0.206.0`	task runner and toolkit extending SvelteKit	59/81	331	yes
🪴 @fuzdev/fuz_css	`0.63.2`	CSS framework and design system for semantic HTML	37/40	868	yes
🧶 @fuzdev/fuz_ui	`0.206.6`	Svelte UI library	96	305	yes
🗝 @fuzdev/fuz_app	`0.104.0`	fullstack app library	6	26	yes
🎨 @fuzdev/fuz_code	`0.47.0`	syntax styling utilities and components for TypeScript, Svelte, Markdown, and more	18/22	62	yes
❄ @fuzdev/fuz_template	`0.0.1`	a static web app template with optional Rust for the fuz-stack	2	4	no
🖊️ @fuzdev/fuz_blog	`0.28.1`	blog software from scratch with SvelteKit	8/11	24	yes
🦣 @fuzdev/fuz_mastodon	`0.43.0`	Mastodon components and helpers for Svelte, SvelteKit, and Fuz	8	29	yes
🪄 @fuzdev/fuz_gitops	`0.78.0`	a tool for managing many repos	50/55	222	yes
📜 @fuzdev/fuz_docs	`0.0.1`	experimental AI-generated docs and skills for Fuz, a zippy stack for human agency	4	12	no
💤 @fuzdev/zzz	`0.0.1`	software garage for power users and devs	208/211	557	no
📜 svelte-docinfo	`0.5.4`	static analysis for TypeScript and Svelte	30/32	199	yes

Rust workspaces
#

blake3

Crate	Version	Kind	Description	Deps
`blake3_wasm_core`	`0.1.1`	rlib	Shared BLAKE3 WASM bindings core (wasm-bindgen exports)
`blake3_wasm`	`0.1.1`	cdylib	BLAKE3 hashing compiled to WASM	blake3_wasm_core
`blake3_wasm_small`	`0.1.1`	cdylib	BLAKE3 hashing compiled to WASM, size-optimized build without SIMD	blake3_wasm_core
`blake3_debug`	`0.1.1`	bin	Development utilities for blake3_wasm (comparison, test vectors)
`blake3_component`	`0.1.1`	cdylib	BLAKE3 WASI component via WIT interface
`blake3_bench_wasmtime`	`0.1.1`	bin	BLAKE3 WASI component benchmarks using Wasmtime runtime

api #

Packages
#

13 packages, 626 modules, 3094 exports

library #

fuz_docs 📜

experimental AI-generated docs and skills for Fuz, a zippy stack for human agency

homepage

docs.fuz.dev

repo

fuzdev/fuz_docs

DataInput.svelte

DataInput

stack_graph_types.ts

stack_layout.ts

stack_repos.ts