@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.190

package/docs/more/08-developer-experience.mdx

@@ -0,0 +1,134 @@
+---
+title: 'Developer Experience'
+description: 'Dev logging, hydration diffs, Server-Timing headers, build reports, and more.'
+slug: 'developer-experience'
+---
+
+# Developer Experience
+
+timber.js includes a suite of development tools that surface what your app is doing — where time is spent, what's cached, where errors come from — without reaching for external profiling tools.
+
+## Dev Logging
+
+Every request in development emits a structured tree to `stderr` showing the full execution pipeline with timing:
+
+```
+POST /dashboard/projects/123  trace_id: 4bf92f3577b34da6a3ce929d0e0e4736
+├─ [proxy]   proxy.ts                               0ms →  2ms
+├─ [rsc]     middleware.ts                           2ms →  4ms
+│  ├── fired: requireUser()                    (timber.cache prefetch)
+│  ├── fired: getProject("123")               (timber.cache prefetch)
+│  └── fired: getTaskCounts("123")            (timber.cache prefetch)
+├─ [rsc]     render                                 4ms
+│  ├─ [rsc]  AccessGate (authenticated)             4ms →  5ms
+│  │  └── requireUser()                        timber.cache HIT  <1ms
+│  ├─ [rsc]  ProjectPage                            8ms → 12ms
+│  │  └── getTaskCounts("123")                 timber.cache HIT  <1ms
+│  └── onShellReady                                12ms
+├─ [ssr]     hydration render                      13ms → 18ms
+└─ ✓ 200 OK                              total    18ms
+```
+
+The tree mirrors the execution structure. `[rsc]`/`[ssr]`/`[client]` labels show which Vite environment each phase runs in. Cache hits and misses are annotated inline.
+
+### Fetch Instrumentation
+
+`fetch()` calls from server components appear as children of the component that made them:
+
+```
+├─ [rsc]  page /                              6ms → 101ms
+│     ├─ fetch GET https://api.example.com/products  12ms → 89ms (77ms)
+│     └─ fetch GET https://api.example.com/user      12ms → 45ms (33ms) [cdn: HIT]
+```
+
+Start times reveal whether fetches ran concurrently or sequentially. Cache status from `X-Cache` or `CF-Cache-Status` headers is surfaced automatically. Fetch instrumentation is dev-only — `globalThis.fetch` is not patched in production.
+
+### Log Modes
+
+Control the verbosity with `TIMBER_DEV_LOG`:
+
+| Mode      | Output                                                     |
+| --------- | ---------------------------------------------------------- |
+| `tree`    | Full indented tree per request (default)                   |
+| `verbose` | Detailed tree showing every component render               |
+| `summary` | One line per request: `POST /path → 200 OK  18ms`         |
+| `json`    | Chronological NDJSON of all spans with full attributes     |
+
+Suppress all dev logging with `TIMBER_DEV_QUIET=1`.
+
+### Slow Phase Warnings
+
+Phases that exceed a configurable threshold are highlighted in the tree output. The default is 200ms:
+
+```ts title="timber.config.ts"
+export default {
+  dev: {
+    slowPhaseMs: 200,
+  },
+};
+```
+
+This surfaces performance bottlenecks during development without requiring explicit profiling.
+
+## Server-Timing Header
+
+timber.js emits a `Server-Timing` HTTP header for every response. The level of detail is configurable:
+
+| Value        | Output                                                   | Default in  |
+| ------------ | -------------------------------------------------------- | ----------- |
+| `'detailed'` | Per-phase breakdown: proxy, middleware, render, SSR       | Development |
+| `'total'`    | Single `total;dur=N` entry                               | Production  |
+| `false`      | No header                                                | —           |
+
+```ts title="timber.config.ts"
+export default {
+  serverTiming: 'detailed',
+};
+```
+
+In production, you can opt into `'detailed'` for APM integration — browser DevTools and monitoring tools parse `Server-Timing` automatically.
+
+## Hydration Mismatch Diff
+
+When React 19 detects a hydration mismatch, timber parses the diff and renders it with color-coded lines:
+
+- Green (`+`) lines show the client-side markup
+- Red (`-`) lines show the server-side markup
+
+This replaces Vite's plain-text rendering of hydration errors, making mismatches easy to spot and fix. Multiple hydration errors accumulate in the same overlay.
+
+## Error Overlay
+
+Errors during development are shown in a browser overlay with:
+
+- **Component stacks** — the React component hierarchy leading to the error
+- **Phase labels** — whether the error occurred in middleware, access check, RSC render, SSR, or a client component
+- **Source-mapped stack traces** — pointing to your original source files
+
+Client-side errors are forwarded to the overlay via Vite's HMR channel, so they get the same treatment as server errors.
+
+## Compiling Indicator
+
+A small "Compiling…" indicator appears in the bottom-left corner during HMR updates. It has a 200ms debounce — fast updates never show it. It fades out when the update completes.
+
+## Build Report
+
+After `timber build`, a route table shows every route with its bundle size, route type, and first-load JS:
+
+| Symbol | Meaning        |
+| ------ | -------------- |
+| ○      | Static page    |
+| λ      | Dynamic (SSR)  |
+| ƒ      | API route      |
+
+This helps identify large bundles and verify route classification.
+
+## HTTPS / HTTP-2 Dev Server
+
+timber supports `server.https` in your Vite config for local HTTPS development. The request scheme is derived from the TLS socket (not hardcoded), so CSRF protection works correctly under HTTPS. HTTP/2 pseudo-headers are handled automatically.
+
+## What's Next
+
+- [Instrumentation](/docs/instrumentation) — production tracing with OpenTelemetry
+- [Configuration](/docs/configuration) — all config options
+- [Streaming](/docs/streaming) — Suspense placement and `deferSuspenseFor`

package/docs/more/40-why-timber.mdx

@@ -0,0 +1,50 @@
+---
+title: 'Why timber.js?'
+description: 'The design decisions behind timber.js and why they matter.'
+slug: 'why-timber'
+---
+
+# Why timber.js?
+
+timber.js exists because we think the current generation of React frameworks made a wrong turn on streaming.
+
+## The Premise
+
+Most React frameworks stream HTML as fast as possible. The moment the server starts rendering, bytes go to the browser. This sounds great in theory — faster Time to First Byte, progressive rendering, the user sees _something_ sooner.
+
+The cost is real:
+
+- **Every page returns HTTP 200.** A 404? That's a 200 with an error boundary. A redirect? That's a 200 with client-side navigation. A 500? Also 200. Once you start streaming, you've committed the status code.
+- **Pages don't work without JavaScript.** The client needs JS to resolve suspense boundaries, handle error states, and execute redirects that the server couldn't express through HTTP.
+- **Loading states everywhere.** `loading.tsx` exists because the framework sends the shell before data is ready. Now you're designing skeleton states for every route, managing layout shift, and adding perceived complexity.
+
+## What timber.js Does Differently
+
+timber.js holds the response until the shell is ready. That's the content outside `<Suspense>` boundaries — the stuff that actually determines the page's HTTP status, headers, and primary content.
+
+The trade-off is roughly 20ms of server-side buffering before the first byte. In exchange:
+
+- **Real status codes.** `deny(404)` sends a genuine HTTP 404. CDNs cache it correctly. Search engines deindex it. `curl` sees it. APM tools report it.
+- **Pages work without JavaScript.** The initial render arrives complete. No JS needed to show the primary content.
+- **No implicit loading states.** There's no `loading.tsx`. If you want a loading state, you place a `<Suspense>` boundary explicitly around the slow content — and you choose where.
+
+Secondary content (reviews on a product page, comments on a post) can still stream via `<Suspense>`. You decide where the flush boundary sits. The framework doesn't decide for you.
+
+## What timber.js is Not
+
+This is not a framework for every use case. It's opinionated about a few things:
+
+- **Server-first rendering.** If you're building a single-page app with no server, this isn't the right tool.
+- **Explicit over implicit.** There's no magic caching, no implicit data fetching, no hidden loading states. You opt into each behavior.
+- **Smaller API surface.** We'd rather have fewer features that work correctly than many features with edge cases.
+
+Next.js is more mature, more battle-tested, and supports more use cases. If you're happy with it, there's no reason to switch. timber.js is for people who've run into the limitations of streaming-first and want HTTP semantics that work.
+
+## Built on Vite
+
+timber.js is a Vite plugin, not a standalone build system. You get Vite's ecosystem: sub-second HMR, the plugin ecosystem, native ESM, and Rolldown for production builds. Your `vite.config.ts` stays normal — timber.js adds to it, it doesn't replace it.
+
+## What's Next
+
+- [Getting Started](/docs/quick-start) — create a project in under five minutes
+- [timber.js vs Next.js](/docs/timber-vs-nextjs) — an honest comparison

package/docs/more/41-timber-vs-nextjs.mdx

@@ -0,0 +1,81 @@
+---
+title: 'timber.js vs Next.js'
+description: 'An honest comparison of timber.js and Next.js — where they differ and why.'
+slug: 'timber-vs-nextjs'
+---
+
+# timber.js vs Next.js
+
+Next.js is the most widely used React framework. It's mature, well-documented, and backed by Vercel. timber.js would not exist without it — the app directory routing model, server components, and many API patterns are directly inspired by Next.js.
+
+That said, we made different design decisions in a few areas. Here's an honest comparison.
+
+## HTTP Semantics
+
+| Behavior           | Next.js                                          | timber.js                                        |
+| ------------------ | ------------------------------------------------ | ------------------------------------------------ |
+| Status codes       | Always 200 (streaming commits early)             | Real status codes (flush held until shell ready) |
+| 404 pages          | 200 + `not-found.tsx` error boundary             | HTTP 404 + `404.tsx`                             |
+| Redirects in pages | Client-side via `redirect()` after 200           | HTTP 302/301 before any bytes sent               |
+| Works without JS   | Partially (primary content yes, interactions no) | Fully (forms, navigation, status codes all work) |
+
+This is the core philosophical difference. Next.js optimizes for earliest possible TTFB. timber.js optimizes for correct HTTP responses, at the cost of ~20ms additional server buffering.
+
+## Streaming
+
+Both frameworks support React Suspense streaming. The difference is when it starts:
+
+- **Next.js:** Streams immediately. `loading.tsx` renders while data loads. Status code is already committed.
+- **timber.js:** Holds until the shell is ready (everything outside `<Suspense>`). Then streams Suspense content. No `loading.tsx` — `<Suspense>` is opt-in only.
+
+## Routing
+
+Both use file-system routing in an `app/` directory. The models are similar:
+
+- Layouts, pages, dynamic segments, catch-all routes — same patterns
+- Parallel routes (slots) — both support `@sidebar`, `@modal` patterns
+- Route groups — both support `(group)` directories
+
+**Differences:**
+
+- **Middleware:** Next.js has a single global `middleware.ts`. timber.js has per-segment `middleware.ts` files.
+- **Authorization:** timber.js has `access.ts` files for per-segment access control with `deny()`. Next.js uses middleware or in-component checks.
+- **Typed routes:** timber.js generates route types at build time — `<Link>` type-checks `href` and params.
+
+## Caching
+
+| Behavior          | Next.js                                              | timber.js                                             |
+| ----------------- | ---------------------------------------------------- | ----------------------------------------------------- |
+| `fetch()` caching | Cached by default (opt out with `cache: 'no-store'`) | Never cached (explicit is better)                     |
+| Cache API         | `unstable_cache` / `'use cache'`                     | `timber.cache()` with TTL, tags, staleWhileRevalidate |
+| Revalidation      | `revalidateTag()`, `revalidatePath()`                | `revalidateTag()`                                     |
+
+timber.js takes the position that implicit caching causes more bugs than it prevents. Nothing is cached unless you wrap it in `timber.cache()`.
+
+## Build System
+
+|                  | Next.js             | timber.js                             |
+| ---------------- | ------------------- | ------------------------------------- |
+| Bundler          | Turbopack / Webpack | Vite 7 (Rolldown)                     |
+| Config           | `next.config.js`    | `vite.config.ts` + `timber.config.ts` |
+| Plugin ecosystem | Next.js-specific    | Full Vite plugin ecosystem            |
+
+## Platform Support
+
+Next.js is optimized for Vercel and works on other platforms through community adapters. timber.js ships a first-party Cloudflare Workers adapter and a Nitro adapter that covers Node.js, Vercel, Bun, Netlify, AWS Lambda, and more.
+
+## When to Use Next.js
+
+- You need the largest ecosystem and community support
+- You're deploying to Vercel
+- You need features timber.js hasn't built yet (image optimization, ISR, etc.)
+- Your team is already productive with Next.js
+
+## When to Use timber.js
+
+- You care about correct HTTP status codes and headers
+- You want pages that work fully without JavaScript
+- You're deploying to Cloudflare Workers
+- You prefer explicit caching over implicit
+- You want per-segment middleware and authorization
+- You want Vite's build speed and plugin ecosystem

package/docs/more/42-timber-vs-others.mdx

@@ -0,0 +1,68 @@
+---
+title: 'timber.js vs Other Frameworks'
+description: 'How timber.js compares to Vinext, Remix, and other React server frameworks.'
+slug: 'timber-vs-others'
+---
+
+# timber.js vs Other Frameworks
+
+Beyond Next.js, there are several React frameworks worth comparing against. Each makes different trade-offs.
+
+## Vinext (Cloudflare)
+
+Vinext is Cloudflare's implementation of Next.js on Vite. It aims for Next.js API compatibility running natively on Cloudflare Workers.
+
+**Shared ground:** Both timber.js and Vinext target Cloudflare Workers, use Vite, and support React Server Components.
+
+**Key differences:**
+
+|              | Vinext                                 | timber.js                                |
+| ------------ | -------------------------------------- | ---------------------------------------- |
+| Goal         | Next.js compatibility on Vite          | Independent design, different trade-offs |
+| Streaming    | Streams immediately (Next.js behavior) | Holds until shell ready                  |
+| Status codes | 200 for everything (Next.js behavior)  | Real HTTP status codes                   |
+| API surface  | Next.js-compatible                     | Similar but divergent where we disagree  |
+| Caching      | Next.js caching model                  | Explicit-only caching                    |
+
+If you want Next.js on Cloudflare with minimal code changes, Vinext is the right choice. If you want a different rendering model with correct HTTP semantics, that's timber.js.
+
+## Remix / React Router
+
+Remix (now React Router v7) pioneered many of the ideas timber.js agrees with: progressive enhancement, forms that work without JavaScript, and server-first rendering.
+
+**Shared philosophy:**
+
+- Forms should work without JS
+- Server rendering is the default
+- Progressive enhancement over client-side-first
+
+**Key differences:**
+
+|               | Remix / React Router                 | timber.js                                |
+| ------------- | ------------------------------------ | ---------------------------------------- |
+| Routing model | Flat route config or file convention | Nested `app/` directory (Next.js-style)  |
+| Data loading  | `loader` / `action` functions        | Async server components + server actions |
+| RSC support   | Not yet (planned)                    | Built on RSC from day one                |
+| Streaming     | Supports `defer()` for streaming     | `<Suspense>` with explicit flush point   |
+| Build system  | Vite (React Router v7)               | Vite                                     |
+
+Remix's `loader`/`action` model is elegant and well-understood. timber.js bets on RSC as the data loading primitive — your components are your data layer.
+
+## TanStack Start
+
+TanStack Start is a full-stack React framework from the TanStack Router team.
+
+**Shared ground:** Both use Vite, both aim for good TypeScript support, both support server-side rendering.
+
+**Key differences:**
+
+|                | TanStack Start                          | timber.js                                  |
+| -------------- | --------------------------------------- | ------------------------------------------ |
+| Routing        | TanStack Router (code-based, type-safe) | File-system routing with generated types   |
+| Data loading   | TanStack Query integration              | Async server components + `timber.cache()` |
+| RSC support    | Experimental                            | Core architecture                          |
+| Platform focus | General-purpose                         | Cloudflare-first, works everywhere         |
+
+## Summary
+
+Every framework makes trade-offs. timber.js trades streaming speed for HTTP correctness and trades API surface size for explicitness. If those trade-offs align with how you think about web development, it's worth trying. If they don't, the frameworks above are all excellent choices.

package/docs/more/50-ai-agent-instructions.mdx

@@ -0,0 +1,171 @@
+---
+title: 'AI Agent Instructions'
+description: 'Structured reference for AI coding agents working with timber.js — key differences from Next.js, import paths, common mistakes, and reading order.'
+slug: 'ai-agent-instructions'
+---
+
+# AI Agent Instructions
+
+This page is for AI coding agents (Claude Code, Cursor, Copilot, Codex, etc.) and developers who paste context into agent prompts. It is concise and structured for machine consumption — but useful as a quick reference for humans too.
+
+## Fetching These Docs as Markdown
+
+Any timber.js documentation page can be fetched as plain markdown by sending an `Accept: text/markdown` header:
+
+```bash
+curl -H 'Accept: text/markdown' https://timberjs.com/docs/ai-agent-instructions
+```
+
+This returns the page content as `text/markdown` with a `203` status code, suitable for piping into agent context or saving to a file.
+
+## How timber.js Docs Are Organized
+
+| Location | Purpose | Audience |
+| --- | --- | --- |
+| `packages/website/content/docs/` | User-facing guides, tutorials, API reference | Developers building with timber |
+| `design/` | Design decisions, architecture, internal specs | Contributors and agents implementing features |
+| `CLAUDE.md` | Contributor workflow, commands, code style | Agents working on timber itself |
+
+**Read the user-facing docs for building apps.** Read the design docs only when you need to understand _why_ something works the way it does or when contributing to timber itself.
+
+## Reading Order by Task
+
+**Starting a new project:**
+1. [Introduction](/docs/introduction) — what timber is and its philosophy
+2. [Quick Start](/docs/quick-start) — project setup
+3. [Pages and Layouts](/docs/pages-and-layouts) — routing basics
+4. [Configuration](/docs/configuration) — `timber.config.ts`
+
+**Adding a feature:**
+1. [API: @timber-js/app/server](/docs/api-server) — server exports
+2. [API: @timber-js/app/client](/docs/api-client) — client exports
+3. The relevant guide (caching, forms, middleware, etc.)
+
+**Debugging:**
+1. [Coming from Next.js](/docs/coming-from-nextjs) — if the code assumes Next.js patterns
+2. [The Flush Point](/docs/the-flush-point) — if status codes or headers are wrong
+3. [Error Handling](/docs/error-handling) — deny, error boundaries, status files
+
+## Key Differences from Next.js
+
+These are the things you will get wrong if you assume Next.js behavior.
+
+| Concept | Next.js | timber.js |
+| --- | --- | --- |
+| Default component type | Client components need `'use client'` | **All components are server components** by default. Only add `'use client'` when you need browser APIs or hooks. |
+| Fetch caching | `fetch()` is patched with implicit caching | `fetch()` is **never patched**. Use `cache.data()` from `@timber-js/app/cache` explicitly. |
+| ISR | `revalidate` option | **Does not exist.** Use `cache.data()` with TTL and tags. |
+| `loading.tsx` | Convention for auto-Suspense | **Does not exist.** Use `<Suspense>` explicitly. |
+| Middleware | Single global `middleware.ts` with matchers | Per-segment `middleware.ts` files + global `proxy.ts`. One-arg signature: `middleware(ctx)`. |
+| `notFound()` | `notFound()` from `next/navigation` | `deny(404)` from `@timber-js/app/server`. Sends a real HTTP 404. |
+| `redirect()` | `redirect()` from `next/navigation` | `redirect()` from `@timber-js/app/server`. Same concept, different import. |
+| Search params | Untyped `useSearchParams()` | Typed `defineSearchParams()` with Zod schemas, in any module you import. |
+| Auth pattern | In middleware or components | `access.ts` per segment with slot degradation. |
+| Forms | `useFormState` / `useFormStatus` | `createActionClient` + `useActionState` returns a 4-tuple. Forms work without JS. |
+
+## Import Map
+
+| What you need | Import from |
+| --- | --- |
+| `deny`, `redirect`, `getHeaders`, `getCookieJar`, `createActionClient` | `@timber-js/app/server` |
+| `Link`, `useRouter`, `usePathname`, `useActionState` | `@timber-js/app/client` |
+| `cache`, `CacheHandler` | `@timber-js/app/cache` |
+| `defineSearchParams` | `@timber-js/app/search-params` |
+| `defineSchema`, `InferCodecType` | `@timber-js/app/params` |
+| Content collection data | `content-collections` |
+| `Metadata` type | `@timber-js/app/server` |
+
+There is **no** `@timber-js/app` default import. Always use the subpath exports above.
+
+## Project Structure
+
+```
+app/                    # Route tree — file-system routing
+  proxy.ts              # Global request handler (like global middleware)
+  layout.tsx            # Root layout
+  page.tsx              # Home page
+  [segment]/
+    page.tsx            # Dynamic route
+    middleware.ts       # Per-segment middleware
+    access.ts           # Per-segment authorization
+    denied.tsx          # Rendered when access.ts denies
+    error.tsx           # Error boundary for this segment
+    search-params.ts    # Search param definitions (ordinary module, not a convention)
+  schema.ts             # Segment param schemas (from @timber-js/app/params)
+content/                # Content collections (outside route tree)
+timber.config.ts        # Framework configuration
+mdx-components.tsx      # Custom MDX component mappings (optional)
+content-collections.ts  # Collection definitions (optional)
+```
+
+## Common Mistakes
+
+1. **Importing from `next/*`** — there is no `next` package. Use `@timber-js/app/server` and `@timber-js/app/client`. Exception: `next/navigation`'s `redirect()` and `notFound()` are shimmed for compatibility.
+
+2. **Adding `'use client'` to everything** — components are server components by default. Only add `'use client'` when you need browser APIs, event handlers, or React hooks like `useState`/`useEffect`.
+
+   The exception: `error.tsx`, `global-error.tsx`, and component status files (`404.tsx`, `4xx.tsx`, `503.tsx`, …) **always** need `'use client'`. timber passes them to a client error boundary as a prop, so a server component there breaks every page under that segment. The build rejects it and names the file. MDX status files (`404.mdx`) are exempt.
+
+3. **Using `fetch()` and expecting caching** — timber never patches `fetch`. Wrap data-fetching functions in `cache.data()` from `@timber-js/app/cache` when you want caching.
+
+4. **Creating `loading.tsx` files** — this convention does not exist. Use `<Suspense>` with an explicit fallback where you want streaming.
+
+5. **Using ISR patterns** (`revalidate`, `unstable_cache`) — ISR does not exist. Use `cache.data()` with `{ ttl: seconds, tags: ['tag'] }`.
+
+6. **Calling `notFound()`** — use `deny(404)` from `@timber-js/app/server` instead. It sends a real HTTP 404 status code.
+
+7. **Putting all middleware in one file** — middleware is per-segment. Place `middleware.ts` at the route level that matches the concern. Use `proxy.ts` for global concerns.
+
+8. **Assuming `useSearchParams()` exists** — use `defineSearchParams()` in any module with Zod schemas, then access via `.get()` (server) or `.useQueryStates()` (client).
+
+## Quick Patterns
+
+### Data fetching with caching
+
+```tsx
+import { cache } from '@timber-js/app/cache';
+
+const getProducts = cache.data(
+  async () => db.products.findMany(),
+  { ttl: 300, tags: ['products'] }
+);
+
+export default async function Page() {
+  const products = await getProducts();
+  return <ProductList products={products} />;
+}
+```
+
+### 404 handling
+
+```tsx
+import { deny } from '@timber-js/app/server';
+
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const item = await getItem(id);
+  if (!item) deny(404);
+  return <Item item={item} />;
+}
+```
+
+### Per-segment middleware
+
+```ts title="app/dashboard/middleware.ts"
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+export default async function middleware(ctx: MiddlewareContext) {
+  ctx.headers.set('X-Dashboard', 'true');
+}
+```
+
+### Access control
+
+```ts title="app/(auth)/access.ts"
+import { redirect, getCookieJar } from '@timber-js/app/server';
+
+export default async function access() {
+  const session = getSession(getCookieJar());
+  if (!session) redirect('/login');
+}
+```

package/llms.txt

@@ -0,0 +1,55 @@
+# @timber-js/app
+
+> Vite-native React Server Components framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript.
+
+timber.js is a React framework built on Vite and React Server Components. It uses file-system routing (app/ directory), server components by default, and produces real HTTP status codes. It deploys to Cloudflare Workers, Node.js, Vercel, Netlify, and more via adapters.
+
+It is inspired by, but _not_ next.js. Do not assume next.js features work in timber, though the routing is similar, much of the rest diverges.
+
+## Docs
+
+Documentation ships with this package in the `docs/` directory. All files are MDX.
+
+### Learn (core concepts, read in order)
+
+- [Introduction](docs/learn/00-introduction.mdx)
+- [Quick Start](docs/learn/01-quick-start.mdx)
+- [Pages and Layouts](docs/learn/02-pages-and-layouts.mdx)
+- [Fetching Data](docs/learn/03-fetching-data.mdx)
+- [Access Control](docs/learn/03b-access-control.mdx)
+- [Loading States](docs/learn/04-loading-states.mdx)
+- [The Flush Point](docs/learn/04b-the-flush-point.mdx)
+- [Typed Params](docs/learn/05-typed-params.mdx)
+- [Forms and Actions](docs/learn/06-forms-and-actions.mdx)
+- [Streaming](docs/learn/08-streaming.mdx)
+- [Caching](docs/learn/09-caching.mdx)
+- [Middleware](docs/learn/10-middleware.mdx)
+- [Error Handling](docs/learn/11-error-handling.mdx)
+- [Client Navigation](docs/learn/12-client-navigation.mdx)
+- [Configuration](docs/learn/13-configuration.mdx)
+- [Deploying](docs/learn/14-deploying.mdx)
+
+### More (advanced topics)
+
+- [Advanced Routing](docs/more/01-advanced-routing.mdx)
+- [Advanced Forms](docs/more/02-advanced-forms.mdx)
+- [Coming from Next.js](docs/more/03-coming-from-nextjs.mdx)
+- [Metadata and Fonts](docs/more/04-metadata-and-fonts.mdx)
+- [MDX](docs/more/04b-mdx.mdx)
+- [Content Collections](docs/more/05-content-collections.mdx)
+- [Instrumentation & Tracing](docs/more/06-instrumentation.mdx)
+- [Security](docs/more/07-security.mdx)
+
+### API Reference
+
+- [@timber-js/app/server](docs/api/30-api-server.mdx)
+- [@timber-js/app/client](docs/api/31-api-client.mdx)
+- [@timber-js/app/cache](docs/api/32-api-cache.mdx)
+- [Search & Segment Params](docs/api/33-api-search-params.mdx)
+- [timber.config.ts](docs/api/34-api-config.mdx)
+- [TypeScript](docs/api/35-api-typescript.mdx)
+- [CLI](docs/api/36-cli.mdx)
+
+## AI Agent Skill
+
+A Claude Code skill is included at `agent-skill.md`. Load it for guidance on building timber.js applications.