Documentation

The experimental Byline CLI: 'byline init' against an existing TanStack Start app, plus 'doctor' and other commands for adding Byline to a fresh project.

Why Byline exists: an AI-first, structurally sound headless CMS that takes versioning, workflow, translation, and editorial provenance seriously by default.

Why structured versioning, workflow, and translation matter more — not less — when AI starts producing content at scale, and what provenance looks like in that world.

The load-bearing design decisions behind Byline: universal EAV storage, immutable versioning, patch-based updates, the schema/admin split, and the workflow system.

Universal EAV-per-type storage: typed store_* tables, the path notation, flatten/reconstruct, immutable versioning, current_documents views, and selective field loading.

The complete i18n story for Byline and the reference host: two coordinated-but-separate translation systems (host interface, Byline admin interface) and a third axis (content locales). Covers admin-interface translation (the @byline/i18n package), content-locale resolution and fallback, the availableLocales advertising control and its 'ready' widget, the non-sticky content-locale routing the host implements, and the administrative task of switching a system's default content locale.

Defining collections in Byline: defineCollection, the workflow system, lifecycle hooks (beforeCreate, beforeRead, afterUpdate…), and the admin presentation split.

The Fields API: built-in types, optional, localized, validation, hooks, the schema-vs-admin split, and how to build reusable field helpers like publishedOnField.

How actors, abilities, and request context flow through Byline — plus six worked beforeRead recipes for row-level access control on document reads and populate.

The in-process @byline/client SDK above the storage primitives — find, create, update, populate, status-aware reads, plus the read and write hook contracts.

Roadmap for how Byline's core packages compose: registry/DI, server config, the host adapter, and what's planned for framework-agnostic distribution.

Why the Byline client config is registered from two points on the _byline route, the root cause that blocks collapsing it to one eager point, and whether an eager single-point registration is even possible given that custom slot components need React context.

How byline_document_paths keys (document_id, locale) → path, why path lives outside the EAV stores, and how the slugifier resolves uniqueness on create and update.

The full upload pipeline — field-level validation, storage providers, image variant generation via Sharp, and how the Media collection plus a relation forms a shared library.

First-class typed relations: the populate pipeline, depth-bounded recursion via ReadContext, two-axis populate DSL, and the unified relation envelope across all states.

How Byline applications cache HTML at the CDN edge, how editors bypass that cache for instant preview, and where an optional in-memory data cache fits.

Byline's Lexical-based rich text editor: the extension API, built-in nodes (links, inline images, admonitions, layout, code, tables), and the runtime serializer pipeline.

The current internal-transport phase — TanStack Start server functions per area — and why a stable public HTTP API is deferred until a second client arrives.

The pluggable transport family — a single framework-agnostic operation contract bound to many runtimes (Nitro, Fastify, Hono) plus MCP as a peer transport. The concrete shape of the stable boundary ROUTING-API.md defers.

Byline as a Model Context Protocol server — a peer transport that binds the operation layer to MCP tools/resources/prompts, with draft-by-default writes, service-account auth, and the workflow lifecycle as the human gate. The literal proof of 'AI-first'.

The shared @byline/ui component library — primitives, themed surfaces, design tokens, and the Rslib build pipeline used to ship it to admin and downstream consumers.

Two suites, two commands: pnpm test (unit, no Postgres) and pnpm test:integration (real db). Isolation, safety guards, and how to run a single test file.

Single landing page for 'what's next?'. An index of authoritative phase sections across the docs — priority lives here, detail lives in the linked doc.