docs: rebuild documentation around boundary-friendly error data

[braden-w]

Rebuilds wellcrafted's public documentation around plain, boundary-friendly error data and the familiar { data, error } Result shape, while retiring 23 overlapping documentation owners only after their durable material was migrated or deliberately rejected.

The old documentation had useful ideas, but they were spread across competing tutorials, philosophy essays, source-folder READMEs, integration pages, and user-facing agent skills. That made it difficult to know which page owned a claim, and several pages mixed current API guidance with stale names, unsupported reliability or productivity claims, and unconditional serialization language. We chose a smaller set of canonical owners because readers need one trustworthy route from application task to exact API contract.

Before
  getting-started + core tutorials + patterns + philosophy essays
  + source READMEs + integration pages + agent skills
                         │
                         ▼
              overlapping claims and examples

After
  README / Start      → first successful Result loop
  Guides              → application tasks and boundary decisions
  Reference           → exact exports and runtime contracts
  Integrations        → framework-specific boundary guidance
  Decisions           → durable rationale and known tradeoffs
  Agent skills        → secondary workflow convenience

The positioning is intentionally qualified: wellcrafted errors can move through JSON, HTTP, workers, IPC, logs, and UI without an error-class transformation layer when every field is JSON-compatible. defineErrors does not type-enforce that condition, arbitrary fields do not serialize perfectly, and preserving a JSON shape is not the same as runtime validation or end-to-end static typing.

What this adds

• A new front door, installation path, quick start, and surgical try/catch migration guide.
• Four task guides for defining error vocabularies, composing Results, owning service boundaries, and preserving errors across serialization boundaries.
• Sole reference owners for all 79 documented export tuples across the nine published subpaths.
• Dedicated decision records for the Result shape, the plain-object error contract, nested brand markers, and pragmatic propagation tradeoffs.
• Rebuilt TanStack Query, validation-library, and Hono integrations. The Hono guide explicitly separates JSON shape preservation, runtime validation, and shared static route typing.
• Four attributed Epicenter-derived application examples, adapted at pinned commit 4d438c0, plus runnable local examples and synchronized public snippets.
• Package-consumer, compatibility, runtime, export-coverage, claims, and snippet gates. The claims gate now scans all 42 remaining public files with no legacy exclusions.
• Reworked user-facing agent skills as a secondary convenience rather than the primary documentation surface.

Deletion audit

Every deletion below was approved before removal, verified while the old file still existed, and committed only after its replacement owners and the full proof suite passed.

Getting started and migration

Removed owner	Durable material retained or relocated	Material intentionally dropped
docs/getting-started/installation.mdx	Consumer installation, supported subpath imports, compiler modes, and tested runtime prerequisites moved to /start/installation.	Unsupported root-import guidance, legacy module-resolution assumptions, and contributor setup mixed into consumer docs.
docs/getting-started/quick-start.mdx	The first define/return/handle loop moved to /start/quick-start and is synchronized with the runnable quick-start example.	Undefined helpers, duplicate API tours, and examples that were not mechanically checked.
docs/migration/from-try-catch.mdx	Surgical adoption, caller migration, and the throwing rollback adapter moved to /start/migrating-from-try-catch.	Persona framing, combinator history, duplicate explanations, and stale links.

Core tutorials and patterns

Removed owner	Durable material retained or relocated	Material intentionally dropped
docs/core/result-pattern.mdx	Application flow moved to the composition guide; exact exports and edge behavior moved to Result reference; shape rationale moved to the Result decision.	Unsafe truthy-error guidance, duplicate API narration, and ambiguous treatment of Ok(null) / Err(null).
docs/core/error-system.mdx	Variant design moved to the vocabulary guide; serialization limits to the boundary guide; exact exports to Error reference; rationale to the error-contract decision.	Perfect-serialization implications, deep-immutability implications, stale factory shapes, and confusion between a tagged body and an Err wrapper.
docs/core/brand-types.mdx	Type behavior moved to Brand reference; validator recipes to the validation integration; representation rationale to the brand decision.	Claims that branding validates data, changes runtime values, or emits a serialization marker.
docs/patterns/optional-keys.mdx	Required-versus-optional variant fields and constructor ownership moved to the vocabulary guide.	Repeated factory reference and a second competing owner for the same design rule.
docs/patterns/real-world.mdx	The grounded service-to-caller flow moved to the service-boundary guide and runnable service example.	Broad framework, production, reliability, and universal-use claims.
docs/patterns/service-layer.mdx	Boundary ownership, classification, manual propagation, and caller handling moved to the service and composition guides.	Prescriptive folder architecture, duplicate helper APIs, and stale service-layer conventions.

Philosophy essays

Removed owner	Durable material retained or relocated	Material intentionally dropped
docs/philosophy/err-null-is-ok-null.md	The structural Err(null) collision, valid Ok(null), non-null error convention, and falsy-error handling moved to the Result decision and composition guide.	Any implication that the current type enforces the convention.
docs/philosophy/error-api-evolution.mdx	The durable progression from manual literals through brittle overloads to constructor functions moved to the error-contract decision.	Dates, call-site counts, historical tutorial detail, and superseded builder guidance.
docs/philosophy/rust-inspiration.mdx	The limited thiserror analogy moved to the error-contract decision.	Claims of language-level Rust enum equivalence and duplicate factory instruction.
docs/philosophy/why-name-and-message.mdx	The JavaScript vocabulary rationale for name and human-facing message moved to the error-contract decision.	Repeated API tutorials and overlapping ownership.
docs/philosophy/brand-implementation.mdx	Nested private-marker rationale and verified assignability behavior moved to the brand decision.	Runtime identity, validation, serialization-marker, and universal-composition claims.
docs/philosophy/for-the-pragmatic-fp-developer.mdx	Explicit propagation cost and guidance for choosing Results, exceptions, or an effect system moved to the pragmatic-tradeoffs decision.	Persona targeting and superiority framing.
docs/philosophy/from-effect-to-pragmatic-errors.mdx	TypeScript control-flow constraints and the honest Effect escape hatch moved to the pragmatic-tradeoffs decision.	Competitor size, performance, and universal-simplicity comparisons.
docs/philosophy/production-reliability.mdx	Grounded boundary-classification and serialization lessons moved into checked guides.	Uptime, production-hours, importer counts, incident-prevention claims, reliability anecdotes, and other vanity metrics. None were republished.
docs/philosophy/developer-experience.mdx	Ordinary narrowing, explicit branching, and test-helper behavior moved to current guides and Testing reference.	Debugging-speed, productivity, editor-universality, and anecdotal developer-experience claims.
docs/philosophy/design-principles.mdx	Plain-data errors, ordinary control flow, explicit costs, and the larger-system escape hatch moved to the README and decision records.	“Perfect serialization,” “works anywhere,” “never throws,” and other absolute claims.

Source-folder READMEs

Removed owner	Durable material retained or relocated	Material intentionally dropped
src/README.md	Package mental model, workflows, and exact APIs moved to the repository README, guides, and reference.	A second public tutorial tree hidden inside the source directory.
src/error/README.md	Variant rules, signatures, shallow-freeze behavior, and conditional JSON behavior moved to the vocabulary/boundary guides and Error reference.	Type-enforced or perfect-serialization implications and superseded API narration.
src/query/README.md	The two query families, exact handle shapes, defineKeys, reactive snapshots, cache ownership, and package prerequisite moved to the TanStack integration and Query reference.	Retired names, duplicate examples, and unsupported performance claims.

What was deliberately kept

• docs/integrations/hono-serialization.mdx remains as a compatibility notice that points readers to the canonical Hono guide; it was not in the deletion allowlist.
• Historical changelog entries and old specification records remain historical evidence. They are not treated as current user guidance.
• Every currently published subpath and export remains documented. This is a documentation ownership change, not a public API removal.
• Known runtime/type mismatches are documented rather than silently “fixed” in a docs pass: once after a throwing first call, extractErrorMessage edge cases, the @tanstack/query-core prerequisite, and runtime requirements around Object.groupBy, AsyncDisposable, and Symbol.asyncDispose.
• The raw-cause pattern remains valid inside a process. The docs only require deliberate normalization when values cross a serialization boundary.
• Unused template logo assets remain in the repository because the approved deletion wave was intentionally restricted to the exact 23-owner allowlist. Their stale Mint override is no longer configured.

What this does not change

There is no public API change and no new claim that serialization is enforced by TypeScript. Enforcing JSON-safe error fields would require a separate API proposal. This PR also does not add the missing Query peer dependency, change runtime behavior, publish documentation, or deploy anything.

Verification

• Frozen Bun install: no changes.
• Format, typecheck, build, and lint: pass; lint retains 12 pre-existing warnings and zero errors.
• Test suite: 188 passing tests.
• Package smoke: tarball, nine supported subpaths, unsupported root import, strict consumers, and explicit Query prerequisite pass.
• Type and runtime compatibility fixtures: pass.
• Documentation examples and synchronized snippets: pass.
• Export coverage: 79 tuples across nine sole reference owners.
• Claims audit: all 42 current public files pass with zero legacy exclusions.
• Mint 4.2.684 under Node 24.14.0: validation and broken-link checks pass.
• Desktop and 400px responsive review: home, quick start, serialization guide, Result reference, and Hono guide pass.
• Two independent final audits: all grounded first-reader findings incorporated; skeptical API and claims review returned no findings.

No open GitHub issue directly corresponds to this documentation pass.