API docs - @fuzdev stack

fuz_docs

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

docs.fuz.dev

introduction #

Overview
#

fuz_docs is an experimental website with AI-generated documentation and agent skills for Fuz, a zippy stack for autonomy. 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 a temporary build tool, to be replaced by fuz (Rust daemon + CLI). 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	Always include `.js` extension, import directly from source module (no re-exports)
Formatting	Prettier 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; `gro gen` 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

// .js extension in imports, even for .ts files
import {git_push} from './git.js';

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
#

14 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 — variables, utility classes, modifiers, extraction
Dependency Injection	Injectable *Deps interfaces, mock factories, composition patterns
Documentation System	Docs pipeline — Tome system, layout architecture, project setup
Rust Conventions for the Fuz Ecosystem	Shared Rust patterns — edition 2024, unsafe forbid, lints, crate structure
Svelte 5 Patterns	Svelte 5 runes, contexts, snippets, attachments, Cell pattern
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, auditing
Type Utilities	Nominal typing (Flavored/Branded), strict utility types
WASM Patterns for the Fuz Ecosystem	WASM 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 a temporary build tool, to be replaced by fuz (Rust daemon + CLI). 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 #

Toolchain
#

Tool	Version
rustc	`rustc 1.94.0 (4a4ef493e 2026-03-02)`
cargo	`cargo 1.94.0 (85eff7c80 2026-01-15)`
node	`v24.9.0`
svelte	`5.55.0`
sveltekit	`2.55.0`
typescript	`5.9.3`
gro	`0.197.2`
prettier	`3.7.4`
vitest	`4.0.15`

TypeScript and Svelte packages
#

13 packages, 753 exported modules (794 total), 3666 exports

Package	Version	Description	Modules	Exports	Published
🦕 @fuzdev/fuz_util	`0.55.0`	utility belt for JS	51	416	yes
🌰 @fuzdev/gro	`0.197.2`	task runner and toolkit extending SvelteKit	60/82	322	yes
🪴 @fuzdev/fuz_css	`0.58.0`	CSS framework and design system for semantic HTML	30/31	669	yes
🧶 @fuzdev/fuz_ui	`0.191.3`	Svelte UI library	111	390	yes
🗝 @fuzdev/fuz_app	`0.2.1`	fullstack app library	150/151	709	yes
🎨 @fuzdev/fuz_code	`0.45.1`	syntax styling utilities and components for TypeScript, Svelte, Markdown, and more	19/20	42	yes
❄ @fuzdev/fuz_template	`0.0.1`	a static web app and Node library template with TypeScript, Svelte, SvelteKit, Vite, esbuild, Gro, and Fuz	2	2	no
🖊️ @fuzdev/fuz_blog	`0.24.1`	blog software from scratch with SvelteKit	8/11	24	yes
🦣 @fuzdev/fuz_mastodon	`0.39.0`	Mastodon components and helpers for Svelte, SvelteKit, and Fuz	8	29	yes
🪄 @fuzdev/fuz_gitops	`0.68.0`	a tool for managing many repos	46/51	189	yes
📜 @fuzdev/fuz_docs	`0.0.1`	experimental AI-generated docs and skills for Fuz, a zippy stack for autonomy	2/5	2	no
🦋 @fuzdev/fuz.dev	`0.0.1`	website for the Fuz, a zippy stack for autonomy	0	0	no
💤 @fuzdev/zzz	`0.0.1`	local-first forge for power users and devs	266/271	872	no

Rust workspaces
#

blake3

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

Dependency graph
#

@fuzdev/fuz_util
  └── @fuzdev/blake3_wasm
@fuzdev/gro
  ├── @fuzdev/blake3_wasm
  └── @fuzdev/fuz_util
@fuzdev/fuz_css
  ├── @fuzdev/blake3_wasm
  ├── @fuzdev/fuz_util
  └── @fuzdev/gro
@fuzdev/fuz_ui
  ├── @fuzdev/fuz_code
  ├── @fuzdev/fuz_css
  ├── @fuzdev/fuz_util
  └── @fuzdev/gro
@fuzdev/fuz_app
  ├── @fuzdev/blake3_wasm
  └── @fuzdev/fuz_util
@fuzdev/fuz_code
  ├── @fuzdev/fuz_css
  └── @fuzdev/fuz_util
@fuzdev/fuz_blog
  ├── @fuzdev/fuz_css
  ├── @fuzdev/fuz_mastodon
  ├── @fuzdev/fuz_ui
  ├── @fuzdev/fuz_util
  └── @fuzdev/gro
@fuzdev/fuz_mastodon
  ├── @fuzdev/fuz_css
  ├── @fuzdev/fuz_ui
  └── @fuzdev/fuz_util
@fuzdev/fuz_gitops
  ├── @fuzdev/fuz_css
  ├── @fuzdev/fuz_ui
  ├── @fuzdev/fuz_util
  └── @fuzdev/gro

Unpublished packages:
@fuzdev/fuz_template (no runtime @fuzdev deps)
@fuzdev/fuz_docs (no runtime @fuzdev deps)
@fuzdev/fuz.dev (no runtime @fuzdev deps)
@fuzdev/zzz
  ├── @fuzdev/blake3_wasm
  └── @fuzdev/gro