@xmachines/docs 1.0.0-beta.45 → 1.0.0-beta.48

package/guides/getting-started.md

@@ -1,50 +1,95 @@
 <!-- generated-by: gsd-doc-writer -->
 
-# Getting Started
+# Getting Started with XMachines Play
 
-Welcome to XMachines! This guide gets you from zero to a running actor using the current XState v5 + XMachines API.
+This guide walks you through installing XMachines packages, wiring a state machine with [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md), connecting a view renderer, and plugging in a router adapter — from zero to a running actor-driven application.
 
-## What is XMachines?
+---
 
-XMachines is a TypeScript implementation of the Universal Player Architecture — a state machine system that strictly separates business logic from infrastructure. State machines (actors) control routing, views, and navigation through TC39 Signals. Infrastructure (routers, renderers, React components) passively observes and reflects actor state.
+## Prerequisites
 
-Your state machines have **zero framework dependencies**. Routers and renderers are optional adapters.
+- **Node.js** `>= 22.0.0`
+- **npm** `>= 10.0.0`
+- **TypeScript** `>= 5.7` (strict mode recommended)
+- **XState** `v5` (required peer dependency for [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md))
+
+All packages are ES modules (`"type": "module"`). Use `.js` extensions in all TypeScript imports.
+
+---
 
 ## Installation
 
-Install the core packages (see [Installation →](installation.md) for the full package guide):
+### Step 1: Install the core packages
+
+Every XMachines application needs these three packages plus XState:
+
+```bash
+npm install xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
+```
+
+| Package                                                               | Role                                                                                                                                                                |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `xstate`                                                              | XState v5 state machine engine (peer dependency)                                                                                                                    |
+| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)   | [`definePlayer()`](../api/@xmachines/play-xstate/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md), routing helpers |
+| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)     | Abstract actor base class and interface types                                                                                                                       |
+| [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) | TC39 Signals polyfill (`Signal.State`, `Signal.Computed`, [`watchSignal`](../api/@xmachines/play-signals/functions/watchSignal.md))                                 |
+
+### Step 2: Install a router adapter (pick one)
+
+```bash
+# Framework-integrated routers (provider pattern)
+npm install @xmachines/play-tanstack-react-router   # TanStack Router (React)
+npm install @xmachines/play-tanstack-solid-router   # TanStack Router (SolidJS)
+npm install @xmachines/play-react-router            # React Router v7
+npm install @xmachines/play-vue-router              # Vue Router 4.x/5.x
+npm install @xmachines/play-solid-router            # SolidJS Router
+
+# connectRouter pattern (framework-agnostic)
+npm install @xmachines/play-dom-router              # Vanilla DOM (Browser History API)
+npm install @xmachines/play-sveltekit-router        # SvelteKit
+npm install @xmachines/play-svelte-spa-router       # Svelte SPA Router
+```
+
+### Step 3: Install a view renderer (pick one)
 
 ```bash
-npm install @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals xstate
+npm install @xmachines/play-react    # React 18/19
+npm install @xmachines/play-vue      # Vue 3
+npm install @xmachines/play-solid    # SolidJS
+npm install @xmachines/play-svelte   # Svelte 5
+npm install @xmachines/play-dom      # Vanilla DOM
 ```
 
-## Step 1: Define a Machine
+---
+
+## First Run: Core Actor (No Router, No Renderer)
 
-Use `setup({ types })` from XState v5 to declare types, then call `setup.createMachine()`:
+The minimum viable XMachines actor — no framework dependencies:
 
 ```typescript
 import { setup } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
 
-const toggleSetup = setup({
+// 1. Declare types with setup() — the XState v5 typed entry point
+const appSetup = setup({
 	types: {
 		context: {} as { count: number },
 		events: {} as { type: "toggle" },
-		input: {} as { count?: number } | undefined,
+		input: {} as undefined,
 	},
 });
 
-const toggleMachine = toggleSetup.createMachine({
-	id: "toggle",
+// 2. Create the machine using setup().createMachine()
+const machine = appSetup.createMachine({
+	id: "app",
 	initial: "off",
-	context: ({ input }) => ({
-		count: input?.count ?? 0,
-	}),
+	context: { count: 0 },
 	states: {
 		off: {
 			on: {
 				toggle: {
 					target: "on",
-					actions: toggleSetup.assign({ count: ({ context }) => context.count + 1 }),
+					actions: appSetup.assign({ count: ({ context }) => context.count + 1 }),
 				},
 			},
 		},
@@ -52,70 +97,46 @@ const toggleMachine = toggleSetup.createMachine({
 			on: {
 				toggle: {
 					target: "off",
-					actions: toggleSetup.assign({ count: ({ context }) => context.count + 1 }),
+					actions: appSetup.assign({ count: ({ context }) => context.count + 1 }),
 				},
 			},
 		},
 	},
 });
-```
 
-**Key rules:**
+// 3. Create a player factory
+const createPlayer = definePlayer({ machine });
 
-- Always use `setup({ types })` before `createMachine` — not the bare `createMachine` from xstate.
-- Use `setup.assign(...)` (not the bare `assign` from xstate) for context mutations.
-- Event types use lowercase dot-separated names: `"toggle"`, `"auth.login"`, `"play.route"`.
-
-## Step 2: Define a Player
-
-`definePlayer` wraps the machine in a factory. Each call to the factory creates an independent `PlayerActor` instance:
-
-```typescript
-import { definePlayer } from "@xmachines/play-xstate";
-
-const createPlayer = definePlayer({ machine: toggleMachine });
-```
-
-## Step 3: Create and Start an Actor
-
-```typescript
+// 4. Create and start an actor
 const actor = createPlayer();
 actor.start();
 
-// Read initial state
+// 5. Read state
 console.log(actor.getSnapshot().value); // "off"
-console.log(actor.getSnapshot().context); // { count: 0 }
+console.log(actor.state.get().value); // "off" (TC39 Signal)
 
-// Send events
+// 6. Send events — the machine's guards decide all transitions
 actor.send({ type: "toggle" });
 console.log(actor.getSnapshot().value); // "on"
-console.log(actor.getSnapshot().context.count); // 1
 
-// Cleanup
+// 7. Cleanup
 actor.stop();
 ```
 
-## Step 4: Read State via TC39 Signals
+**Key rules:**
 
-`actor.state` is a `Signal.State<Snapshot>`. Use it when wiring infrastructure that needs to react to state changes:
+- Always use `setup({ types })` before `createMachine` — never bare `createMachine` from xstate.
+- Use `setup.assign(...)` for context mutations — not the bare `assign` from xstate.
+- Call `actor.start()` before sending events.
+- Call `actor.stop()` when done to clean up signal subscriptions.
 
-```typescript
-import { watchSignal } from "@xmachines/play-signals";
+---
 
-// Watch the state signal — callback fires on every transition
-const unwatch = watchSignal(actor.state, () => {
-	console.log("State changed to:", actor.state.get().value);
-});
+## Adding Routing
 
-actor.send({ type: "toggle" }); // logs "State changed to: on"
+State machines control navigation through `meta.route` on states and `play.route` events. The router is passive infrastructure that observes `actor.currentRoute`.
 
-// Stop watching
-unwatch();
-```
-
-## Step 5: Add Routing (Optional)
-
-Add `meta.route` to states and wrap the config with `formatPlayRouteTransitions`. The machine's context must include `params` and `query` fields:
+### Define a routable machine
 
 ```typescript
 import { setup } from "xstate";
@@ -124,24 +145,55 @@ import type { PlayRouteEvent } from "@xmachines/play-router";
 
 const appSetup = setup({
 	types: {
+		// params and query are REQUIRED for formatPlayRouteTransitions
 		context: {} as {
 			isAuthenticated: boolean;
 			params: Record<string, string>;
 			query: Record<string, string>;
 		},
-		events: {} as PlayRouteEvent | { type: "auth.login"; username: string },
+		events: {} as
+			| PlayRouteEvent
+			| { type: "auth.login"; username: string }
+			| { type: "auth.logout" },
 		input: {} as undefined,
 	},
 });
 
 const appMachine = appSetup.createMachine(
+	// formatPlayRouteTransitions auto-generates play.route handlers from id + meta.route pairs
 	formatPlayRouteTransitions({
 		id: "app",
 		initial: "home",
 		context: { isAuthenticated: false, params: {}, query: {} },
 		states: {
 			home: { id: "home", meta: { route: "/" } },
+			about: { id: "about", meta: { route: "/about" } },
 			login: { id: "login", meta: { route: "/login" } },
+			dashboard: {
+				id: "dashboard",
+				meta: { route: "/dashboard" },
+				// always guard: redirect to /login if not authenticated
+				always: {
+					guard: ({ context }) => !context.isAuthenticated,
+					target: "login",
+				},
+			},
+			profile: { id: "profile", meta: { route: "/profile/:username" } },
+		},
+		on: {
+			"auth.login": {
+				target: ".dashboard",
+				guard: ({ context }) => !context.isAuthenticated,
+				actions: appSetup.assign({
+					isAuthenticated: true,
+					username: ({ event }) => (event.type === "auth.login" ? event.username : null),
+				}),
+			},
+			"auth.logout": {
+				target: ".home",
+				guard: ({ context }) => context.isAuthenticated,
+				actions: appSetup.assign({ isAuthenticated: false }),
+			},
 		},
 	}),
 );
@@ -150,30 +202,118 @@ const createPlayer = definePlayer({ machine: appMachine });
 const actor = createPlayer();
 actor.start();
 
+// Read the current route via TC39 Signal
 console.log(actor.currentRoute.get()); // "/"
 
-actor.send({ type: "play.route", to: "#login" });
-console.log(actor.currentRoute.get()); // "/login"
+// Navigate — actor guards validate the transition
+actor.send({ type: "play.route", to: "#about" });
+console.log(actor.currentRoute.get()); // "/about"
+
+// Attempt a protected route — always guard redirects to login
+actor.send({ type: "play.route", to: "#dashboard" });
+console.log(actor.getSnapshot().value); // "login" (guard fired)
+
+// Navigate with params
+actor.send({ type: "auth.login", username: "alice" });
+actor.send({ type: "play.route", to: "#profile", params: { username: "alice" } });
+console.log(actor.currentRoute.get()); // "/profile/alice"
 
 actor.stop();
 ```
 
-## Step 6: Add a View Registry (Optional)
+**Routing rules:**
+
+- Every routable state **must** have an `id` — [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) throws `MissingStateIdError` if absent.
+- Send `play.route` events with `to: "#stateId"` — always use the `id` field prefixed with `#`, never raw URL paths.
+- The machine's context must include `params: Record<string, string>` and `query: Record<string, string>` for [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) to work.
+- Use `always` guards to protect states from direct URL access — these fire even on browser back/forward.
+
+---
+
+## Connecting a Router Adapter
+
+Router adapters synchronize `actor.currentRoute` with the browser URL bidirectionally. There are two integration patterns:
 
-Connect a renderer to map `meta.view` specs to real components.
+### Pattern 1: Provider pattern (React, Vue, SolidJS)
 
-**Vanilla DOM** — use `createRenderer` (one-call pattern):
+```typescript
+// React + TanStack Router example
+import { useMemo, useEffect } from "react";
+import { createRouter, createRootRoute } from "@tanstack/react-router";
+import {
+  PlayRouterProvider,
+  createRouteMapFromTree,
+} from "@xmachines/play-tanstack-react-router";
+import { extractMachineRoutes } from "@xmachines/play-router";
+
+// Build these OUTSIDE of JSX — must be stable references
+const routeTree = extractMachineRoutes(appMachine);
+const routeMap = createRouteMapFromTree(routeTree);
+const router = createRouter({ routeTree: createRootRoute() });
+
+export function App() {
+  const actor = useMemo(() => {
+    const a = createPlayer();
+    a.start();
+    return a;
+  }, []);
+
+  useEffect(() => () => { actor.stop(); }, [actor]);
+
+  return (
+    <PlayRouterProvider
+      actor={actor}
+      router={router}
+      routeMap={routeMap}
+      renderer={(currentActor) => (
+        // Your shell/layout component here
+        <Shell actor={currentActor} />
+      )}
+    />
+  );
+}
+```
+
+### Pattern 2: `connectRouter` pattern (Vanilla DOM, SvelteKit, Svelte)
 
 ```typescript
-import { createRenderer, schema } from "@xmachines/play-dom";
+import { connectRouter, createRouteMap } from "@xmachines/play-dom-router";
+
+const routeMap = createRouteMap(appMachine);
+const actor = createPlayer();
+actor.start();
+
+// connectRouter handles bidirectional sync:
+// - actor.currentRoute signal → browser URL
+// - browser URL changes → play.route event sent to actor
+const disconnectRouter = connectRouter({ actor, routeMap });
+
+// Cleanup on unload
+window.addEventListener("beforeunload", () => {
+	disconnectRouter();
+	actor.stop();
+});
+```
+
+---
+
+## Connecting a View Renderer
+
+View renderers map `meta.view` specs from your machine states to real UI components. Each framework has a [`defineRegistry`](../api/@xmachines/play-dom/functions/defineRegistry.md) function that binds components and actions to a catalog.
+
+### Vanilla DOM
+
+```typescript
+import { createPlayUI, defineRegistry, schema } from "@xmachines/play-dom";
 import { defineCatalog } from "@json-render/core";
 import { z } from "zod";
 import type { ComponentFn } from "@xmachines/play-dom";
 
+// 1. Define a catalog (schema of components and actions)
 const catalog = defineCatalog(schema, {
 	components: {
 		Home: { props: z.object({ title: z.string() }) },
-		Login: { props: z.object({ title: z.string() }) },
+		Login: { props: z.object({}) },
 	},
 	actions: {
 		login: { params: z.object({ username: z.string() }) },
@@ -181,42 +321,46 @@ const catalog = defineCatalog(schema, {
 	},
 });
 
+// 2. Implement components
 const Home: ComponentFn<typeof catalog, "Home"> = ({ props }) => {
 	const el = document.createElement("section");
 	el.textContent = props.title;
 	return el;
 };
-const Login: ComponentFn<typeof catalog, "Login"> = ({ props, on }) => {
-	const el = document.createElement("section");
+const Login: ComponentFn<typeof catalog, "Login"> = ({ on }) => {
+	const el = document.createElement("div");
 	const btn = document.createElement("button");
-	const submit = on("submit");
-	btn.addEventListener("click", () => submit.emit());
+	btn.textContent = "Log in";
+	btn.addEventListener("click", () => on("submit").emit());
 	el.append(btn);
 	return el;
 };
 
-// Build factory once, mount when actor + container are ready
-const mount = createRenderer(catalog, { Home, Login });
-const disconnectRenderer = mount(actor, document.getElementById("app")!);
+// 3. Build registry and mount
+const registryResult = defineRegistry(catalog, {
+	components: { Home, Login },
+	actions: {
+		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		logout: async () => actor.send({ type: "auth.logout" }),
+	},
+});
+
+const mount = createPlayUI(registryResult);
+const disconnect = mount(actor, document.getElementById("app")!);
 
 // Cleanup
-window.addEventListener("beforeunload", () => {
-	disconnectRenderer();
-	actor.stop();
-});
+window.addEventListener("beforeunload", () => disconnect());
 ```
 
-**React** — use `PlayUIProvider` + `PlayRenderer` from `@xmachines/play-react`:
+### React
 
 ```tsx
 import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
-import { authCatalog } from "@xmachines/play-actor-shared";
-import { Home, Login } from "./components/index.js";
 
-const registryResult = defineRegistry(authCatalog, {
+const registryResult = defineRegistry(catalog, {
 	components: { Home, Login },
 	actions: {
-		login: async (params) => actor.send({ type: "auth.login", username: params!.username }),
+		login: async ({ username }) => actor.send({ type: "auth.login", username }),
 		logout: async () => actor.send({ type: "auth.logout" }),
 	},
 });
@@ -230,83 +374,148 @@ function App() {
 }
 ```
 
-## Complete Toggle Example
+### Vue 3
 
-```typescript
-import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
-import { watchSignal } from "@xmachines/play-signals";
+```html
+<!-- App.vue -->
+<template>
+	<PlayUIProvider :actor="actor" :registry-result="registryResult">
+		<PlayRenderer />
+	</PlayUIProvider>
+</template>
 
-const toggleSetup = setup({
-	types: {
-		context: {} as { count: number },
-		events: {} as { type: "toggle" },
-		input: {} as undefined,
-	},
-});
+<script setup lang="ts">
+	import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-vue";
 
-const toggleMachine = toggleSetup.createMachine({
-	id: "toggle",
-	initial: "off",
-	context: { count: 0 },
-	states: {
-		off: {
-			on: {
-				toggle: {
-					target: "on",
-					actions: toggleSetup.assign({ count: ({ context }) => context.count + 1 }),
-				},
-			},
-		},
-		on: {
-			on: {
-				toggle: {
-					target: "off",
-					actions: toggleSetup.assign({ count: ({ context }) => context.count + 1 }),
-				},
-			},
+	const registryResult = defineRegistry(catalog, {
+		components: { Home, Login },
+		actions: {
+			login: async ({ username }) => actor.send({ type: "auth.login", username }),
+			logout: async () => actor.send({ type: "auth.logout" }),
 		},
+	});
+</script>
+```
+
+### SolidJS
+
+```tsx
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-solid";
+
+const registryResult = defineRegistry(catalog, {
+	components: { Home, Login },
+	actions: {
+		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		logout: async () => actor.send({ type: "auth.logout" }),
 	},
 });
 
-const createPlayer = definePlayer({ machine: toggleMachine });
-const actor = createPlayer();
+function App() {
+	return (
+		<PlayUIProvider actor={actor} registryResult={registryResult}>
+			<PlayRenderer />
+		</PlayUIProvider>
+	);
+}
+```
 
-const unwatch = watchSignal(actor.state, () => {
-	const snap = actor.state.get();
-	console.log(`State: ${String(snap.value)}, Count: ${snap.context.count}`);
-});
+---
 
-actor.start();
-// logs: State: off, Count: 0
+## Common Setup Issues
 
-actor.send({ type: "toggle" });
-// logs: State: on, Count: 1
+### Missing `params` / `query` in context
+
+**Error:** `MissingQueryContextError` at runtime when using [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md).
+
+**Fix:** Add `params` and `query` fields to your machine context:
+
+```typescript
+context: {} as {
+  params: Record<string, string>;
+  query: Record<string, string>;
+  // ...other fields
+}
+// and initialize them:
+context: { params: {}, query: {}, /* ...other fields */ }
+```
+
+### Missing `id` on routable states
+
+**Error:** `MissingStateIdError: State "home" has meta.route "/" but no id`.
+
+**Fix:** Every state with `meta.route` must declare an explicit `id`:
+
+```typescript
+// ❌ Missing id
+home: { meta: { route: "/" } }
+
+// ✅ Correct
+home: { id: "home", meta: { route: "/" } }
+```
+
+### Actor sends events before `start()`
 
+**Symptom:** Events are silently dropped; state never changes.
+
+**Fix:** Always call `actor.start()` before `actor.send()`:
+
+```typescript
+const actor = createPlayer();
+actor.start(); // required before any send()
 actor.send({ type: "toggle" });
-// logs: State: off, Count: 2
+```
 
-unwatch();
-actor.stop();
+### `routeMap` or `actor` recreated on every render (React/Solid)
+
+**Symptom:** The router bridge disconnects and reconnects on every render.
+
+**Fix:** Construct stable references outside JSX or memoize them:
+
+```typescript
+// ✅ Built outside the component
+const routeTree = extractMachineRoutes(appMachine);
+const routeMap = createRouteMapFromTree(routeTree);
+
+// ✅ Or memoized inside the component
+const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);
 ```
 
-## Glossary
+### Wrong Node.js version
+
+**Error:** `SyntaxError: Cannot use import statement in a module` or TC39 Signals not available.
+
+**Fix:** Use Node.js `>= 22.0.0`. Check with:
+
+```bash
+node --version
+```
+
+---
+
+## Key Concepts Reference
+
+| Term                                                                                                  | Description                                                                                                     |
+| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `setup({ types })`                                                                                    | XState v5 entry point — declares TypeScript types for context, events, and input                                |
+| [`definePlayer({ machine })`](../api/@xmachines/play-xstate/functions/definePlayer.md)                | Creates a factory that produces [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md) instances |
+| `actor.start()`                                                                                       | Activates the machine — always call before sending events                                                       |
+| `actor.send({ type })`                                                                                | Sends an event; machine guards decide whether a transition occurs                                               |
+| `actor.getSnapshot()`                                                                                 | Synchronous read of current state and context                                                                   |
+| `actor.state`                                                                                         | `Signal.State<Snapshot>` — TC39 Signal for reactive state observation                                           |
+| `actor.currentRoute`                                                                                  | `Signal.Computed<string \| null>` — resolved URL from active state's `meta.route`                               |
+| `actor.currentView`                                                                                   | `Signal.State<PlaySpec \| null>` — view spec from active state's `meta.view`                                    |
+| [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) | Generates `play.route` handlers from `id` + `meta.route` state pairs                                            |
+| `play.route` event                                                                                    | Navigation event — `to: "#stateId"`, `params`, `query`                                                          |
+| `always` guard                                                                                        | Protects states — fires on entry before any event, even on direct URL access                                    |
 
-| Term                         | Description                                                                                        |
-| ---------------------------- | -------------------------------------------------------------------------------------------------- |
-| `setup({ types })`           | XState v5 entry point — declares TypeScript types for context, events, and input                   |
-| `definePlayer({ machine })`  | Creates a factory that produces `PlayerActor` instances from the machine                           |
-| `actor.start()`              | Activates the machine — always call before sending events                                          |
-| `actor.send({ type })`       | Sends an event to the machine                                                                      |
-| `actor.getSnapshot()`        | Synchronous snapshot of the current state and context                                              |
-| `actor.state`                | `Signal.State<Snapshot>` — TC39 Signal for reactive state observation                              |
-| `actor.currentRoute`         | `Signal.Computed<string \| null>` — resolved URL from the active state's `meta.route`              |
-| `actor.currentView`          | `Signal.State<PlaySpec \| null>` — view spec from the active state's `meta.view`; drives renderers |
-| `formatPlayRouteTransitions` | Utility that generates `play.route` handlers from `id` + `meta.route` state pairs                  |
+---
 
 ## Next Steps
 
-- **[Installation Guide](installation.md)** — Framework-specific packages, TypeScript config
-- **[Examples](../examples/README.md)** — Routing patterns, form validation, multi-router demos
-- **[API Reference](../api/README.md)** — Generated API docs for all packages
+- **[ARCHITECTURE.md](ARCHITECTURE.md)** — System design, component diagram, data flow, and architectural invariants
+- **[CONFIGURATION.md](CONFIGURATION.md)** — Environment variables and configuration options
+- **[Routing Patterns](../packages/docs/examples/routing-patterns.md)** — `meta.route`, `play.route`, `always` guards, and parameter routes
+- **[Multi-Router Integration](../packages/docs/examples/multi-router-integration.md)** — All 8 router adapters with full code examples
+- **[Examples Index](../packages/docs/examples/README.md)** — Basic state machine, form validation, and traffic light demos
+- **[API Reference](../packages/docs/api/README.md)** — Auto-generated API docs for all packages
 - **[Play RFC](../rfc/play.md)** — Complete architectural specification