react-mnemonic 1.1.0-beta0 → 1.2.1-beta1.0

package/README.md

@@ -1,47 +1,12 @@
 # react-mnemonic
 
-Persistent, type-safe state management for React.
+AI-friendly, persistent, type-safe state for React.
 
 [![npm version](https://img.shields.io/npm/v/react-mnemonic.svg)](https://www.npmjs.com/package/react-mnemonic)
 [![docs](https://img.shields.io/badge/docs-online-0A7EA4.svg)](https://thirtytwobits.github.io/react-mnemonic/)
-[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=thirtytwobits_react-mnemonic&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=thirtytwobits_react-mnemonic)
-[![dependencies](https://img.shields.io/badge/dependencies-0-success.svg)](https://www.npmjs.com/package/react-mnemonic)
-[![license](https://img.shields.io/npm/l/react-mnemonic.svg)](./LICENSE.md)
-[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
+[![license](https://img.shields.io/npm/l/react-mnemonic.svg)](https://github.com/thirtytwobits/react-mnemonic/blob/main/LICENSE.md)
 
-**react-mnemonic** gives your React components persistent memory. Values survive
-page refreshes, synchronize across tabs, and stay type-safe end-to-end -- all
-through a single hook that works like `useState`.
-
-`1.1.0-beta0` is the current prerelease on the npm `latest` dist-tag. This minor
-`beta0` cut lands ahead of the `beta1` stabilization milestone, which is
-expected to receive only fixes and polish before the first production release.
-
-If you are evaluating alternatives, see the
-[Comparison Guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/comparisons-and-benchmarks).
-It publishes reproducible bundle measurements, an AI-friendliness benchmark
-built around one-shot app-building prompts, and controlled SSR/API tradeoff
-notes for `react-mnemonic`, Zustand persist, Jotai `atomWithStorage`,
-`use-local-storage-state`, and `usehooks-ts`.
-
-## Features
-
-- **`useState`-like API** -- `useMnemonicKey` returns `{ value, set, reset, remove }`
-- **JSON Schema validation** -- optional schema-based validation using a built-in JSON Schema subset
-- **Namespace isolation** -- `MnemonicProvider` prefixes every key to prevent collisions
-- **Cross-tab sync** -- opt-in `listenCrossTab` uses the browser `storage` event
-- **Pluggable storage** -- use `localStorage`, `sessionStorage`, or a synchronous `StorageLike` facade over custom persistence
-- **Schema versioning and migration** -- upgrade stored data with versioned schemas and migration rules
-- **Typed schema cohesion helpers** -- define one schema object and reuse it across runtime validation, key descriptors, and migrations
-- **Structural migration helpers** -- optional tree utilities for idempotent insert/rename/dedupe migration steps
-- **Read-time reconciliation** -- selectively enforce new defaults on persisted values without clearing the whole key
-- **Recovery helpers** -- build user-facing soft reset and hard reset flows with namespace-scoped clear helpers
-- **Write-time normalization** -- migrations where `fromVersion === toVersion` run on every write
-- **First-class key descriptors** -- define canonical, reusable key contracts once with `defineMnemonicKey(...)`
-- **Lifecycle callbacks** -- `onMount` and `onChange` hooks
-- **DevTools** -- inspect and mutate state from the browser console
-- **SSR-safe with explicit controls** -- defaults to `defaultValue` on the server, with optional `ssr.serverValue` and `client-only` hydration
-- **Tree-shakeable, zero dependencies** -- ships ESM + CJS with full TypeScript declarations
+`react-mnemonic` gives your components persistent memory through a hook that feels like `useState`. Values survive reloads, can stay in sync across tabs, and remain SSR-safe by default. It is designed to be AI-friendly, prioritizing visible structure and unambiguous specifications. When you need more than raw storage, the package can validate, version, and migrate persisted data.
 
 ## Installation
 
@@ -49,34 +14,15 @@ notes for `react-mnemonic`, Zustand persist, Jotai `atomWithStorage`,
 npm install react-mnemonic
 ```
 
-```bash
-yarn add react-mnemonic
-```
-
-```bash
-pnpm add react-mnemonic
-```
-
-### Peer dependencies
-
-React 18 or later is required. CI verifies packaged-consumer installs against
-React 18 and React 19.
-
-```json
-{
-    "peerDependencies": {
-        "react": ">=18",
-        "react-dom": ">=18"
-    }
-}
-```
+React 18 or later is required.
 
 ## Quick start
 
-Wrap your app in a `MnemonicProvider`, then call `useMnemonicKey` anywhere inside it.
+Wrap your app in a `MnemonicProvider`, then call `useMnemonicKey` anywhere
+inside it.
 
 ```tsx
-import { MnemonicProvider, useMnemonicKey } from "react-mnemonic";
+import { MnemonicProvider, useMnemonicKey } from "react-mnemonic/core";
 
 function Counter() {
     const { value: count, set } = useMnemonicKey("count", {
@@ -100,701 +46,48 @@ export default function App() {
 }
 ```
 
-The counter value persists in `localStorage` under the key `my-app.count` and
-survives full page reloads.
-
-In server-rendered apps, `useMnemonicKey(...)` renders `defaultValue` on the
-server by default and then hydrates to persisted storage on the client. When
-you need a deterministic server placeholder or want to delay storage reads
-until after mount, use `ssr.serverValue` and `ssr.hydration: "client-only"`.
-See the
-[Server Rendering guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/server-rendering)
-for Next.js and Remix examples.
-
-If the same key is used in multiple components, consider defining it once with
-`defineMnemonicKey(...)` and reusing that descriptor everywhere. This keeps the
-contract importable and explicit for both humans and AI-assisted tooling.
-
-For a deterministic implementation reference aimed at AI agents and advanced
-users, see the
-[AI docs overview](https://thirtytwobits.github.io/react-mnemonic/docs/ai).
-The canonical agent-facing prose lives under
-[`website/docs/ai/`](https://github.com/thirtytwobits/react-mnemonic/tree/main/website/docs/ai),
-with compact retrieval surfaces published as
-[`llms.txt`](https://thirtytwobits.github.io/react-mnemonic/llms.txt),
-[`llms-full.txt`](https://thirtytwobits.github.io/react-mnemonic/llms-full.txt),
-and
-[`ai-contract.json`](https://thirtytwobits.github.io/react-mnemonic/ai-contract.json).
-Agents should import published types from `react-mnemonic` and must not invent
-local `.d.ts` shims for the package.
-
-If you need evidence for where `react-mnemonic` is heavier, more explicit, or
-better suited to SSR-sensitive persistence than lighter hooks, see the
-[Comparison Guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/comparisons-and-benchmarks).
+This persists the counter in `localStorage` as `my-app.count`, so the value
+survives a full page reload.
 
-Persist only the durable slice of your app state. `useMnemonicKey` stores
-whatever you pass to `set`, so keep transient UI state like loading flags,
-hover state, and draft search text in plain React state unless you explicitly
-want them to rehydrate after reload. See the
-[Persisted vs Ephemeral State guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/persisted-vs-ephemeral-state)
-for patterns and an interactive example.
+## Why use it
 
-For self-service recovery UX, pair your per-key hooks with
-`useMnemonicRecovery` so users can clear stale filters, reset broken settings,
-or fully wipe a namespace without opening DevTools. See the
-[Reset and Recovery guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/reset-and-recovery)
-for soft-reset and hard-reset recipes.
+- `useState`-like API: `useMnemonicKey` returns `{ value, set, reset, remove }`
+- Namespaced persistence through `MnemonicProvider`
+- Optional cross-tab synchronization
+- SSR-safe defaults for server-rendered React apps
+- Optional schema validation, versioning, migrations, and reconciliation
+- Zero runtime dependencies with published TypeScript types
 
-If a field must stay cleared across reloads, model it as nullable and persist
-`null` explicitly. `remove()` deletes the key and falls back to `defaultValue`,
-while `reset()` writes the default again. See the
-[Clearable Persisted Values guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/clearable-persisted-values)
-for the canonical nullable pattern.
+## Pick the right entrypoint
 
-## Canonical key definitions
-
-When the same persisted key appears in more than one component, define it once
-and reuse it:
-
-```tsx
-import { defineMnemonicKey, useMnemonicKey } from "react-mnemonic";
-
-export const themeKey = defineMnemonicKey("theme", {
-    defaultValue: "light" as "light" | "dark",
-    listenCrossTab: true,
-});
-
-function ThemeToggle() {
-    const { value: theme, set } = useMnemonicKey(themeKey);
-    return <button onClick={() => set(theme === "light" ? "dark" : "light")}>{theme}</button>;
-}
-
-function ThemePreview() {
-    const { value: theme } = useMnemonicKey(themeKey);
-    return <p>Current theme: {theme}</p>;
-}
-```
-
-Descriptors help with:
-
-- keeping one canonical key contract per persisted value
-- reusing the same `defaultValue`, `schema`, `codec`, and `reconcile` logic
-- making AI-assisted code generation and refactors less ambiguous
-
-The original lightweight form still works:
-
-```ts
-const { value, set } = useMnemonicKey("theme", {
-    defaultValue: "light" as "light" | "dark",
-});
-```
-
-## Single source of truth schemas
-
-If you want the same schema object to drive both runtime validation and
-TypeScript inference, use the typed schema helpers:
-
-```tsx
-import {
-    MnemonicProvider,
-    createSchemaRegistry,
-    defineKeySchema,
-    defineMnemonicKey,
-    defineMigration,
-    mnemonicSchema,
-    useMnemonicKey,
-} from "react-mnemonic";
-
-const profileV1 = defineKeySchema(
-    "profile",
-    1,
-    mnemonicSchema.object({
-        name: mnemonicSchema.string(),
-    }),
-);
-
-const profileV2 = defineKeySchema(
-    "profile",
-    2,
-    mnemonicSchema.object({
-        name: mnemonicSchema.string(),
-        email: mnemonicSchema.string(),
-    }),
-);
-
-const profileKey = defineMnemonicKey(profileV2, {
-    defaultValue: { name: "", email: "" },
-    reconcile: (value) => ({
-        ...value,
-        email: value.email.trim().toLowerCase(),
-    }),
-});
-
-const registry = createSchemaRegistry({
-    schemas: [profileV1, profileV2],
-    migrations: [
-        defineMigration(profileV1, profileV2, (value) => ({
-            ...value,
-            email: "",
-        })),
-    ],
-});
-
-function ProfileForm() {
-    const { value: profile, set } = useMnemonicKey(profileKey);
-    return <button onClick={() => set({ ...profile, email: "hello@example.com" })}>Save</button>;
-}
-
-export default function App() {
-    return (
-        <MnemonicProvider namespace="my-app" schemaMode="default" schemaRegistry={registry}>
-            <ProfileForm />
-        </MnemonicProvider>
-    );
-}
-```
-
-This path gives you:
-
-- one schema object reused in the registry, key descriptor, and migrations
-- inferred types for `defaultValue`, `value`, `set`, and `reconcile`
-- typed migration callbacks via `defineMigration(...)`
-
-Tradeoffs versus the lightweight JSON-only path:
-
-- more setup upfront
-- best fit when a key is schema-managed and long-lived
-- not necessary for simple keys where `defaultValue` inference is already enough
-
-For a side-by-side comparison against competing persistence libraries, including
-bundle-size measurements and qualitative SSR/API notes, see the
-[Comparison Guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/comparisons-and-benchmarks).
-
-## API
-
-### `<MnemonicProvider>`
-
-Context provider that scopes storage keys under a namespace.
-
-```tsx
-<MnemonicProvider
-    namespace="my-app" // key prefix (required)
-    storage={localStorage} // StorageLike backend (default: localStorage)
-    schemaMode="default" // "default" | "strict" | "autoschema" (default: "default")
-    schemaRegistry={registry} // optional SchemaRegistry for versioned schemas
-    enableDevTools={false} // expose console helpers (default: false)
->
-    {children}
-</MnemonicProvider>
-```
-
-Multiple providers with different namespaces can coexist in the same app.
-
-### `defineMnemonicKey(key, options)`
-
-Define a reusable descriptor for a single persisted key.
-
-```ts
-const themeKey = defineMnemonicKey("theme", {
-    defaultValue: "light" as "light" | "dark",
-    listenCrossTab: true,
-});
-```
-
-The returned descriptor can be imported and passed directly to `useMnemonicKey`.
-
-### `mnemonicSchema`, `defineKeySchema`, and `defineMigration`
-
-Use these helpers when you want a schema-managed key to have one source of
-truth for runtime validation and TypeScript inference.
-
-```ts
-const themeSchema = defineKeySchema("theme", 1, mnemonicSchema.enum(["light", "dark"] as const));
-
-const themeKey = defineMnemonicKey(themeSchema, {
-    defaultValue: "light",
-});
-```
-
-`defineMigration(fromSchema, toSchema, migrate)` infers the migration callback
-from the source and target schemas, while `defineWriteMigration(schema, migrate)`
-creates a typed same-version normalizer.
-
-### `useMnemonicKey<T>(descriptor)` / `useMnemonicKey<T>(key, options)`
-
-Hook for reading and writing a single persistent value.
-
-```ts
-const { value, set, reset, remove } = useMnemonicKey(themeKey);
-const { value, set, reset, remove } = useMnemonicKey<T>(key, options);
-```
-
-| Return   | Type                                 | Description                                   |
-| -------- | ------------------------------------ | --------------------------------------------- |
-| `value`  | `T`                                  | Current decoded value (or default)            |
-| `set`    | `(next: T \| (cur: T) => T) => void` | Update the value (direct or updater function) |
-| `reset`  | `() => void`                         | Reset to `defaultValue` and persist it        |
-| `remove` | `() => void`                         | Delete the key from storage entirely          |
-
-For clearable fields, remember the semantic split:
-
-- `set(null)` persists a cleared value and stays cleared after reload
-- `remove()` deletes the key, so the next read falls back to `defaultValue`
-- `reset()` persists `defaultValue`
-
-#### Options
-
-| Option           | Type                                              | Default     | Description                                                   |
-| ---------------- | ------------------------------------------------- | ----------- | ------------------------------------------------------------- |
-| `defaultValue`   | `T \| ((error?: CodecError \| SchemaError) => T)` | _required_  | Fallback value or error-aware factory                         |
-| `codec`          | `Codec<T>`                                        | `JSONCodec` | Encode/decode strategy (bypasses schema validation)           |
-| `reconcile`      | `(value: T, context: ReconcileContext) => T`      | --          | Adjust a persisted value after read and persist if it changes |
-| `onMount`        | `(value: T) => void`                              | --          | Called once with the initial value                            |
-| `onChange`       | `(value: T, prev: T) => void`                     | --          | Called on every value change                                  |
-| `listenCrossTab` | `boolean`                                         | `false`     | Sync via the browser `storage` event                          |
-| `schema`         | `{ version?: number }`                            | --          | Pin writes to a specific schema version                       |
-
-### `useMnemonicRecovery(options)`
-
-Hook for namespace-scoped recovery actions such as "clear saved filters" or
-"reset all persisted app data".
-
-```ts
-const { namespace, canEnumerateKeys, listKeys, clearAll, clearKeys, clearMatching } = useMnemonicRecovery({
-    onRecover: (event) => console.log(event.action, event.clearedKeys),
-});
-```
-
-| Return             | Type                                                | Description                                           |
-| ------------------ | --------------------------------------------------- | ----------------------------------------------------- |
-| `namespace`        | `string`                                            | Current provider namespace                            |
-| `canEnumerateKeys` | `boolean`                                           | Whether the storage backend can list namespace keys   |
-| `listKeys`         | `() => string[]`                                    | List visible unprefixed keys in the current namespace |
-| `clearAll`         | `() => string[]`                                    | Clear every key in the namespace                      |
-| `clearKeys`        | `(keys: readonly string[]) => string[]`             | Clear an explicit set of unprefixed keys              |
-| `clearMatching`    | `(predicate: (key: string) => boolean) => string[]` | Clear keys whose names match a predicate              |
-
-`clearAll()` and `clearMatching()` require an enumerable storage backend such
-as `localStorage` or `sessionStorage`. If your custom storage does not support
-`length` and `key(index)`, use `clearKeys([...])` with the explicit durable-key
-list your app owns.
-
-### Codecs
-
-The default codec is `JSONCodec`, which handles all JSON-serializable values.
-You can create custom codecs using `createCodec` for types that need special
-serialization (e.g., `Date`, `Set`, `Map`).
-
-Using a custom codec bypasses JSON Schema validation -- the codec is a low-level
-escape hatch for when you need full control over serialization.
-
-```ts
-import { createCodec } from "react-mnemonic";
-
-const DateCodec = createCodec<Date>(
-    (date) => date.toISOString(),
-    (str) => new Date(str),
-);
-```
+- `react-mnemonic/core` for the lean persisted-state path
+- `react-mnemonic/schema` when you want schemas, validation, and migrations
+- `react-mnemonic` if you need the backward-compatible root entrypoint
 
-### `StorageLike`
+## AI resources
 
-The interface your custom storage backend must satisfy.
-
-```ts
-interface StorageLike {
-    getItem(key: string): string | null;
-    setItem(key: string, value: string): void;
-    removeItem(key: string): void;
-    key?(index: number): string | null;
-    readonly length?: number;
-    onExternalChange?: (callback: (changedKeys?: string[]) => void) => () => void;
-}
-```
-
-`StorageLike` is intentionally synchronous in v1 because Mnemonic's core
-store is built on React's synchronous snapshot contract. Async backends are
-still possible, but they need a synchronous facade: keep an in-memory cache for
-`getItem`/`setItem`/`removeItem`, then flush to IndexedDB or another async
-system outside the hook contract. Promise-returning `StorageLike` methods are
-unsupported and are treated as a storage misuse fallback at runtime.
-
-`onExternalChange` enables cross-tab sync for non-localStorage backends (e.g.
-IndexedDB over `BroadcastChannel`). The library handles all error cases
-internally -- see the `StorageLike` JSDoc for the full error-handling contract.
-Namespace-wide recovery helpers can only enumerate keys when the backend also
-implements `length` and `key(index)`.
-
-### `validateJsonSchema(schema, value)`
-
-Validate an arbitrary value against a JSON Schema (the same subset used by the
-hook). Returns an array of validation errors, empty when the value is valid.
-
-```ts
-import { validateJsonSchema } from "react-mnemonic";
-
-const errors = validateJsonSchema(
-    { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
-    { name: 42 },
-);
-// [{ path: ".name", message: 'Expected type "string"' }]
-```
-
-### `compileSchema(schema)`
-
-Pre-compile a JSON Schema into a reusable validator function. The compiled
-validator is cached by schema reference (via `WeakMap`), so calling
-`compileSchema` twice with the same object returns the identical function.
-
-```ts
-import { compileSchema } from "react-mnemonic";
-import type { CompiledValidator } from "react-mnemonic";
-
-const validate: CompiledValidator = compileSchema({
-    type: "object",
-    properties: {
-        name: { type: "string", minLength: 1 },
-        age: { type: "number", minimum: 0 },
-    },
-    required: ["name"],
-});
-
-validate({ name: "Alice", age: 30 }); // []
-validate({ age: -1 }); // [{ path: "", … }, { path: ".age", … }]
-```
-
-This is useful when you validate the same schema frequently outside of the hook
-(e.g. in form validation or server responses).
-
-### Error classes
-
-| Class         | Thrown when                          |
-| ------------- | ------------------------------------ |
-| `CodecError`  | Encoding or decoding fails           |
-| `SchemaError` | Schema validation or migration fails |
-
-Both are passed to `defaultValue` factories so you can inspect or log the
-failure reason.
-
-## Usage examples
-
-### Cross-tab theme sync
-
-```tsx
-const { value: theme, set } = useMnemonicKey<"light" | "dark">("theme", {
-    defaultValue: "light",
-    listenCrossTab: true,
-    onChange: (t) => {
-        document.documentElement.setAttribute("data-theme", t);
-    },
-});
-```
-
-### Error-aware defaults
-
-```tsx
-import { useMnemonicKey, CodecError, SchemaError } from "react-mnemonic";
-
-const getDefault = (error?: CodecError | SchemaError) => {
-    if (error instanceof CodecError) {
-        console.warn("Corrupt stored data:", error.message);
-    }
-    if (error instanceof SchemaError) {
-        console.warn("Schema validation failed:", error.message);
-    }
-    return { count: 0 };
-};
-
-const { value } = useMnemonicKey("counter", { defaultValue: getDefault });
-```
-
-## Schema modes and versioning
-
-Mnemonic supports optional schema versioning through `schemaMode` and an
-optional `schemaRegistry`.
-
-- `default`: Schemas are optional. Reads use a schema when one exists for the
-  stored version, otherwise the hook codec. Writes use the highest registered
-  schema for the key; if no schemas are registered, writes use an unversioned
-  (v0) envelope.
-- `strict`: Every stored version must have a registered schema. Reads without a
-  matching schema fall back to `defaultValue` with a `SchemaError`.
-  Writes require a registered schema when any schemas exist, but fall back to
-  a v0 envelope when the registry has none.
-- `autoschema`: Like `default`, but if no schema exists for a key, the first
-  successful read infers and registers a v1 schema. Subsequent reads/writes use
-  that schema.
-
-Version `0` is valid for schemas and migrations. Schemas at version `0` are
-treated like any other version.
-
-### JSON Schema validation
-
-Schemas use a subset of JSON Schema for validation. The supported keywords are:
-
-- `type` (including array form for nullable types, e.g., `["string", "null"]`)
-- `enum`, `const`
-- `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`
-- `minLength`, `maxLength`
-- `properties`, `required`, `additionalProperties`
-- `items`, `minItems`, `maxItems`
-
-```ts
-// Schema definition -- fully serializable JSON, no functions
-const schema: KeySchema = {
-    key: "profile",
-    version: 1,
-    schema: {
-        type: "object",
-        properties: {
-            name: { type: "string", minLength: 1 },
-            email: { type: "string" },
-            age: { type: "number", minimum: 0 },
-        },
-        required: ["name", "email"],
-    },
-};
-```
-
-### Write-time migrations (normalizers)
-
-A migration where `fromVersion === toVersion` runs on every write, acting as a
-normalizer. This is useful for trimming whitespace, lowercasing strings, etc.
-
-```ts
-const normalizer: MigrationRule = {
-    key: "name",
-    fromVersion: 1,
-    toVersion: 1,
-    migrate: (value) => String(value).trim().toLowerCase(),
-};
-```
-
-### Reconciliation
-
-Use `reconcile` when you want to keep persisted data but selectively enforce
-new application defaults after the value has been decoded and any read-time
-migrations have already run.
-
-```ts
-const { value } = useMnemonicKey("preferences", {
-    defaultValue: { theme: "dark", density: "comfortable", accents: true },
-    reconcile: (persisted, { persistedVersion }) => ({
-        ...persisted,
-        accents: persistedVersion === 0 ? true : persisted.accents,
-    }),
-});
-```
-
-Use a schema migration when the stored shape must move from one explicit version
-to another. Use `reconcile` for conditional, field-level policy changes such as
-rolling out a new default while preserving the rest of a user's stored data.
-
-### Structural migration helpers
-
-For layout-like data that already uses `id` and `children`, Mnemonic ships
-optional pure helpers for common idempotent migration steps:
-
-```ts
-import { insertChildIfMissing, renameNode, dedupeChildrenBy } from "react-mnemonic";
-
-const migrated = dedupeChildrenBy(
-    renameNode(insertChildIfMissing(layout, "sidebar", { id: "search", title: "Search" }), "prefs", "preferences"),
-    (node) => node.id,
-);
-```
-
-Use these inside your `MigrationRule.migrate` functions when you want repeatable
-tree edits without hand-writing the same traversal logic each time. See the
-[Schema Migration guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/schema-migration)
-for a cookbook example and custom adapter usage.
-
-### Example schema registry
-
-A schema registry stores versioned schemas for each key, and resolves migration
-paths to upgrade stored data. For the common immutable case, use
-`createSchemaRegistry(...)` instead of hand-rolling the indexing boilerplate.
-
-```tsx
-import {
-    createSchemaRegistry,
-    MnemonicProvider,
-    useMnemonicKey,
-    type KeySchema,
-    type MigrationRule,
-} from "react-mnemonic";
-
-const schemas: KeySchema[] = [
-    {
-        key: "profile",
-        version: 1,
-        schema: {
-            type: "object",
-            properties: { name: { type: "string" }, email: { type: "string" } },
-            required: ["name", "email"],
-        },
-    },
-    {
-        key: "profile",
-        version: 2,
-        schema: {
-            type: "object",
-            properties: {
-                name: { type: "string" },
-                email: { type: "string" },
-                migratedAt: { type: "string" },
-            },
-            required: ["name", "email", "migratedAt"],
-        },
-    },
-];
-
-const migrations: MigrationRule[] = [
-    {
-        key: "profile",
-        fromVersion: 1,
-        toVersion: 2,
-        migrate: (value) => {
-            const v1 = value as { name: string; email: string };
-            return { ...v1, migratedAt: new Date().toISOString() };
-        },
-    },
-    {
-        key: "profile",
-        fromVersion: 2,
-        toVersion: 2,
-        migrate: (value) => {
-            const profile = value as { name: string; email: string; migratedAt: string };
-            return { ...profile, email: profile.email.trim().toLowerCase() };
-        },
-    },
-];
-
-const registry = createSchemaRegistry({
-    schemas,
-    migrations,
-});
-
-function ProfileEditor() {
-    const { value, set } = useMnemonicKey<{ name: string; email: string; migratedAt: string }>("profile", {
-        defaultValue: { name: "", email: "", migratedAt: "" },
-    });
-    return <input value={value.name} onChange={(e) => set({ ...value, name: e.target.value })} />;
-}
-
-<MnemonicProvider namespace="app" schemaMode="default" schemaRegistry={registry}>
-    <ProfileEditor />
-</MnemonicProvider>;
-```
-
-`createSchemaRegistry` validates duplicate schemas and ambiguous migration
-graphs up front. If you need runtime schema registration for
-`schemaMode="autoschema"`, keep a custom mutable `SchemaRegistry`
-implementation.
-
-### Registry immutability
-
-In `default` and `strict` modes, the schema registry is treated as immutable for
-the lifetime of the provider. The hook caches registry lookups to keep read and
-write hot paths fast. To ship new schemas or migrations, publish a new app
-version and remount the provider.
-
-`autoschema` remains mutable because inferred schemas are registered at runtime.
-
-### Custom storage backend
-
-```tsx
-import { MnemonicProvider } from "react-mnemonic";
-import type { StorageLike } from "react-mnemonic";
-
-const cache = new Map<string, string>();
-const queueIndexedDbWrite = (key: string, value: string) => {
-    // application-specific async persistence
-};
-const queueIndexedDbDelete = (key: string) => {
-    // application-specific async persistence
-};
-
-const idbStorage: StorageLike = {
-    getItem: (key) => cache.get(key) ?? null,
-    setItem: (key, value) => {
-        cache.set(key, value);
-        queueIndexedDbWrite(key, value);
-    },
-    removeItem: (key) => {
-        cache.delete(key);
-        queueIndexedDbDelete(key);
-    },
-    onExternalChange: (cb) => {
-        const bc = new BroadcastChannel("my-app-sync");
-        bc.onmessage = (e) => cb(e.data.keys);
-        return () => bc.close();
-    },
-};
-
-<MnemonicProvider namespace="my-app" storage={idbStorage}>
-    <App />
-</MnemonicProvider>;
-```
-
-If your real persistence layer is async, initialize that adapter before
-rendering the provider and return a synchronous `StorageLike` facade, like the
-IndexedDB demo in the docs site.
-
-### DevTools
-
-Enable the console inspector in development:
-
-```tsx
-<MnemonicProvider namespace="app" enableDevTools={process.env.NODE_ENV === "development"}>
-```
-
-Then in the browser console:
-
-```js
-const app = window.__REACT_MNEMONIC_DEVTOOLS__?.resolve("app");
-
-app?.dump(); // table of all keys
-app?.get("theme"); // read a decoded value
-app?.set("theme", "dark"); // write
-app?.remove("theme"); // delete
-app?.keys(); // list all keys
-app?.clear(); // remove all keys
-```
-
-## TypeScript
-
-The library is written in strict TypeScript and ships its own declarations.
-All public types are re-exported from the package root:
-
-```ts
-import type {
-    Codec,
-    StorageLike,
-    MnemonicKeyDescriptor,
-    MnemonicProviderOptions,
-    MnemonicProviderProps,
-    UseMnemonicKeyOptions,
-    KeySchema,
-    MigrationRule,
-    MigrationPath,
-    SchemaRegistry,
-    SchemaMode,
-    JsonSchema,
-    JsonSchemaType,
-    JsonSchemaValidationError,
-    CompiledValidator,
-} from "react-mnemonic";
-```
+| Resource                                                                                          | Purpose                                                                           |
+| ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| [AI Docs](https://thirtytwobits.github.io/react-mnemonic/docs/ai)                                 | Canonical invariants, decision matrix, recipes, anti-patterns, and setup guidance |
+| [`llms.txt`](https://thirtytwobits.github.io/react-mnemonic/llms.txt)                             | Compact retrieval index for tight context windows                                 |
+| [`llms-full.txt`](https://thirtytwobits.github.io/react-mnemonic/llms-full.txt)                   | Long-form export for indexing and larger prompt contexts                          |
+| [`ai-contract.json`](https://thirtytwobits.github.io/react-mnemonic/ai-contract.json)             | Machine-readable persistence contract for tooling and agent integrations          |
+| [DeepWiki priorities](https://github.com/thirtytwobits/react-mnemonic/blob/main/.devin/wiki.json) | Steering file that points DeepWiki toward the highest-signal sources              |
+| [AI Assistant Setup](https://thirtytwobits.github.io/react-mnemonic/docs/ai/assistant-setup)      | Generated instruction packs plus the documented MCP-friendly retrieval path       |
 
-## Disclaimer
+## Learn more
 
-THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. The authors make no guarantees
-regarding the reliability, availability, or suitability of this library for any
-particular use case. See the [MIT License](./LICENSE.md) for full terms.
+- [Documentation home](https://thirtytwobits.github.io/react-mnemonic/)
+- [Quick Start](https://thirtytwobits.github.io/react-mnemonic/docs/getting-started/quick-start)
+- [Server Rendering](https://thirtytwobits.github.io/react-mnemonic/docs/guides/server-rendering)
+- [Canonical Key Definitions](https://thirtytwobits.github.io/react-mnemonic/docs/guides/canonical-key-definitions)
+- [Single Source of Truth Schemas](https://thirtytwobits.github.io/react-mnemonic/docs/guides/single-source-of-truth-schemas)
+- [Schema Migration](https://thirtytwobits.github.io/react-mnemonic/docs/guides/schema-migration)
+- [Auth-Aware Persistence](https://thirtytwobits.github.io/react-mnemonic/docs/guides/auth-aware-persistence)
+- [Context7 Rankings](https://thirtytwobits.github.io/react-mnemonic/docs/guides/context7-rankings)
+- [API Reference](https://thirtytwobits.github.io/react-mnemonic/docs/api)
+- [AI Overview](https://thirtytwobits.github.io/react-mnemonic/docs/ai)
 
 ## License
 
-[MIT](./LICENSE.md) -- Copyright Scott Dixon
+[MIT](https://github.com/thirtytwobits/react-mnemonic/blob/main/LICENSE.md)