diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9d3767c..ea7b24f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -34,6 +34,7 @@ applies to every space of this project. Security problems go through
 | `pnpm typecheck`        | `tsc --noEmit`                                              |
 | `pnpm build`            | Typecheck + build `dist/` (ESM, CJS, rolled-up `.d.ts`)     |
 | `pnpm build:site`       | Build the docs site into `site/` (demo app + API reference) |
+| `pnpm wiki:sync`        | Push `docs/wiki/` to the GitHub wiki (maintainers only)     |
 
 The build has one entry per public import path: `lib/index.ts` becomes
 `dist/ai-form-fill.*` (imported as `ai-form-fill`) and `lib/voice/index.ts`
@@ -74,6 +75,16 @@ radio inputs) rather than the Radix-based shadcn `Select`/`Checkbox`/
 `RadioGroup`: the library writes to native form controls, and a Radix widget
 with a hidden mirror input would not update visually.
 
+## Wiki
+
+The [wiki](https://github.com/JDeffner/ai-form-fill/wiki) is authored in this repository, under
+`docs/wiki/`. Edit the page files there and open a pull request like any other change; do not edit
+the pages in the GitHub wiki UI, because the next sync overwrites them. After the pull request is
+merged, a maintainer runs `pnpm wiki:sync`, which clones the wiki repository, replaces its Markdown
+with `docs/wiki/*.md` and pushes. File names become page titles, so `Getting-Started.md` is the page
+"Getting Started" and links between pages are `[Getting Started](Getting-Started)`. `_Sidebar.md` and
+`_Footer.md` are the wiki's navigation.
+
 ## Docs site
 
 `pnpm build:site` builds what GitHub Pages serves at
diff --git a/README.md b/README.md
index 59a2155..1e86194 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ OpenAI-compatible API. Zero runtime dependencies.
 | You want                         | Use                                                           |
 | -------------------------------- | ------------------------------------------------------------- |
 | A finished panel, no build step  | A script tag plus `<ai-form-fill>`                            |
-| A finished panel inside your app | `import 'ai-form-fill/ui'` plus `<ai-form-fill>`              |
+| A finished panel inside your app | `defineFormFillElement()` plus `<ai-form-fill>`               |
 | Your own interface               | `createFormFill()`, `useFormFill()` or the `AIFormFill` class |
 
 The element is built on the controller, the controller is built on the class.
diff --git a/docs/wiki/Architecture.md b/docs/wiki/Architecture.md
new file mode 100644
index 0000000..12d29bd
--- /dev/null
+++ b/docs/wiki/Architecture.md
@@ -0,0 +1,146 @@
+# Architecture
+
+This page is the orientation for contributors: the data flow, the layers on top of it, the domains,
+the invariants, and how to extend the library. It mirrors `docs/ARCHITECTURE.md` in the repository.
+
+The library is small on purpose: zero runtime dependencies, one data flow, three domains.
+
+## Data flow
+
+```
+HTMLFormElement
+      |  lib/form/analyze.ts   getFormFields()
+      v
+FieldInfo[]              stable keys (name -> id -> field_<n>), labels
+      |                  (label[for], wrapping label, aria-*, title),
+      |                  normalized options, checkbox/radio grouping
+      v
+lib/prompt/build.ts      buildExtractionPrompt()  +  buildFormSchema()
+      |                  prompt text                JSON schema with enums
+      v
+AIProvider.chat()        lib/providers/*  - standard wire formats
+      |                  (Ollama REST, OpenAI chat-completions)
+      v
+raw model output
+      |  lib/prompt/parse-response.ts   parseModelResponse()
+      v
+Record<string, unknown>  throws ResponseParseError on garbage
+      |  lib/core/ai-form-fill.ts       applyExtraction() loop, by field.key
+      v
+lib/form/apply.ts        applyFieldValue(): per-type coercion, exact option
+      |                  matching, strict ISO date validation, native
+      v                  prototype setters + input/change events
+FillResult               { filled(+previous), skipped(+reason),
+                         unmatchedKeys, missingRequired, raw }
+```
+
+`extract()` is the same flow stopped one step early, at `Record<string, unknown>`: everything above
+the apply loop, nothing below it. The loop itself is `applyExtraction(data, fields)`, and
+`fillForm()` is literally `extract()` followed by that call, so the two cannot drift. A review step
+calls the two halves separately, with the user's edits in between. See
+[Events, Results and Review](Events-Results-and-Review).
+
+`fillField` is the single-field variant of the same flow: `analyzeField` -> `buildFieldPrompt` ->
+`chat` -> `applyFieldValue`.
+
+Every step reports itself as a bubbling `CustomEvent` on the form (`lib/core/events.ts`):
+`aff:start` before the request, `aff:field-filled` per written field, `aff:done` with the
+`FillResult`, `aff:error` when the extraction throws. Nothing in the library listens to them; they
+exist so a UI does not have to wrap the calls.
+
+`lib/form/revert.ts` runs the flow backwards: `revertFill(result)` writes each `filled` entry's
+`previous` value back through the same setters and events.
+
+`lib/core/controller.ts` sits on top of all of it. `createFormFill()` resolves a form, a text source
+and a trigger, owns one `AIFormFill`, and turns the promise into an observable `idle` / `working` /
+`done` / `error` snapshot with `cancel` and `undo`. It adds no DOM of its own, so UI layers build on
+the snapshot instead of on the promise.
+
+## Layers
+
+```
+        <ai-form-fill>            useFormFill()          your own UI
+        lib/ui/element.ts       lib/react/use-form-fill.ts
+                \                     |                    /
+                 \                    |                   /
+                  ------------  createFormFill()  --------
+                                lib/core/controller.ts
+                                        |
+                                  new AIFormFill()
+                              lib/core/ai-form-fill.ts
+                                        |
+                 form engine  +  prompt/schema  +  providers
+                  lib/form/        lib/prompt/     lib/providers/
+
+        createDictation()  ->  text  ->  any of the three layers above
+        lib/voice/dictation.ts
+```
+
+Each layer is a separate entry point, so nothing is paid for twice:
+
+| Entry point          | Builds on      | Contains                                  |
+| -------------------- | -------------- | ----------------------------------------- |
+| `ai-form-fill`       | -              | Class, controller, form engine, providers |
+| `ai-form-fill/ui`    | the controller | The custom element, its markup and CSS    |
+| `ai-form-fill/react` | the controller | One hook, `react` stays external          |
+| `ai-form-fill/voice` | nothing        | The Web Speech wrapper                    |
+
+The voice module is text-out only. It never calls the core, so the two are independent: dictation
+produces text, and what happens with it is the caller's decision.
+
+## Domains
+
+| Directory        | Responsibility                                                                |
+| ---------------- | ----------------------------------------------------------------------------- |
+| `lib/core/`      | Public class, controller, events, types, typed errors, defaults               |
+| `lib/form/`      | DOM work: reading (`analyze.ts`), writing (`apply.ts`), undo (`revert.ts`)    |
+| `lib/prompt/`    | LLM-facing text and schema (`build.ts`), output parsing (`parse-response.ts`) |
+| `lib/providers/` | Transport: base class, Ollama, OpenAI-compatible, shared HTTP helper          |
+| `lib/ui/`        | The `<ai-form-fill>` element and its stylesheet                               |
+| `lib/react/`     | The `useFormFill` hook                                                        |
+| `lib/voice/`     | Dictation through the Web Speech API                                          |
+
+## Key invariants
+
+- **`FieldInfo.key` is the single source of field identity.** The prompt, the schema and the fill
+  loop all use it. Keys are derived once in `getFormFields` and deduplicated; never re-derive
+  identity elsewhere.
+- **Option matching is exact** (value, then label, then case and whitespace insensitive equality). No
+  substring matching: `"male"` must never select `Female`. The schema's `enum` values make exact
+  model answers likely in the first place.
+- **Application never throws for value problems.** `applyFieldValue` returns
+  `{ applied: false, reason }`; only provider and parse failures throw (`ProviderError`,
+  `ResponseParseError`).
+- **Values go through native prototype setters** and `input` plus `change` events, so controlled
+  React, Vue and Svelte components observe the change.
+- **Configuration is per-instance.** `AFF_DEFAULTS` is frozen; there is no global mutable state.
+- **Schemas avoid provider-hostile constructs**: no `required` (extraction is optional per field),
+  and date and time constraints use `[0-9]` regex patterns, because grammar-based enforcers (Ollama,
+  llama.cpp) reject `\d` and would turn `format: 'time'` into RFC 3339 full-time with a UTC offset,
+  which HTML inputs reject.
+
+## Adding a provider
+
+Extend `AIProvider` (`lib/providers/provider.ts`):
+
+1. Implement `chat`, `listModels` and `isAvailable` using `requestJson`
+   (`lib/providers/http.ts`) for uniform timeout, abort and error handling. Failures must surface as
+   `ProviderError`.
+2. Set `supportsStructured = true` if the service accepts a JSON schema, and translate
+   `ChatRequest.format` into the service's mechanism (`response_format` for OpenAI-style, top-level
+   `format` for Ollama).
+3. Export it from `lib/index.ts`; add wire-format tests with a stubbed `fetch` (see
+   `tests/providers/`).
+
+A worked example is in [Providers](Providers).
+
+## Adding a field type
+
+1. `lib/form/analyze.ts`: make `analyzeField` extract whatever metadata the type needs (options,
+   multiplicity, and so on).
+2. `lib/prompt/build.ts`: give it a schema shape and, if needed, a format hint in the extraction
+   prompt.
+3. `lib/form/apply.ts`: add an application branch returning `applied` or `skipped` outcomes.
+4. Add unit tests for all three layers plus an end-to-end case in `tests/core/ai-form-fill.test.ts`.
+
+See [Contributing](Contributing) for the workflow around these changes.
diff --git a/docs/wiki/Contributing.md b/docs/wiki/Contributing.md
new file mode 100644
index 0000000..2a0e750
--- /dev/null
+++ b/docs/wiki/Contributing.md
@@ -0,0 +1,116 @@
+# Contributing
+
+This page covers the local setup, the scripts, the test layout and the pull request rules. It
+mirrors `CONTRIBUTING.md` in the repository.
+
+Bug reports, feature requests and pull requests are all welcome. The
+[code of conduct](https://github.com/JDeffner/ai-form-fill/blob/main/CODE_OF_CONDUCT.md) applies to
+every space of this project. Security problems go through
+[the security policy](https://github.com/JDeffner/ai-form-fill/security/advisories/new), not through
+a public issue.
+
+## Setup
+
+1. Install [Node.js](https://nodejs.org) 20 or newer and [pnpm](https://pnpm.io/installation).
+2. Clone the repository and run `pnpm install`.
+3. Optional, only for the integration tests and the local demo: install [Ollama](https://ollama.com)
+   and pull the default model.
+
+   ```bash
+   ollama pull gemma3:4b
+   ```
+
+4. Optional, only for the cloud provider demos: copy `.env.example` to `.env` and fill in the keys
+   you have. `.env` is gitignored.
+
+## Scripts
+
+| Script                  | What it does                                                  |
+| ----------------------- | ------------------------------------------------------------- |
+| `pnpm dev`              | Vite dev server with the demo pages                           |
+| `pnpm test`             | Unit tests once, no network needed                            |
+| `pnpm test:watch`       | Unit tests in watch mode                                      |
+| `pnpm test:integration` | The Ollama integration suite, needs a running Ollama          |
+| `pnpm lint`             | ESLint over the whole repository                              |
+| `pnpm lint:fix`         | ESLint with autofix                                           |
+| `pnpm format`           | Prettier write                                                |
+| `pnpm format:check`     | Prettier check, the CI mode                                   |
+| `pnpm typecheck`        | `tsc --noEmit`                                                |
+| `pnpm build`            | Typecheck and build `dist/` (ESM, CJS, rolled-up `.d.ts`)     |
+| `pnpm build:site`       | Build the docs site into `site/` (demo app and API reference) |
+| `pnpm wiki:sync`        | Push `docs/wiki/` to the GitHub wiki (maintainers)            |
+
+The build has one entry per public import path: `lib/index.ts` becomes `dist/ai-form-fill.*` and
+`lib/voice/index.ts` becomes `dist/voice.*`. Add an entry in `vite.config.js` and an `exports` key in
+`package.json` for every new one.
+
+## Tests
+
+- Unit tests live in `tests/` and run in a jsdom environment, so no local setup is required.
+  `document` and the DOM element classes are globals; reset state with `document.body.innerHTML = ''`
+  in a `beforeEach` if your test touches the DOM.
+- The files in `tests/requirements/` trace to thesis requirements (FR-01 to FR-11). Keep the `FR-XX`
+  prefix in the file names, and update the tests when the API changes, but do not delete them.
+- `tests/integration/ollama.integration.test.ts` talks to a real Ollama at
+  `http://localhost:11434` and **fails**, rather than skipping, when Ollama is unreachable. Run it
+  explicitly with `pnpm test:integration`.
+
+## Demo app
+
+`examples/` is a small React app with hash-routed pages in `examples/pages/`, styled with shadcn/ui.
+The pages are Element, Controller, Voice, React hook, Advanced and Script tag. The last one links to
+`examples/vanilla.html`, which is static, loads the built script-tag bundle by relative path and
+imports nothing from `lib/`, so run `pnpm build` once before opening it. `examples/snippets/` holds
+the Vue and Svelte snippets.
+
+The generated shadcn components live in `examples/components/ui/`, `components.json` configures the
+shadcn CLI (`pnpm dlx shadcn@latest add <component>`), and the `@/` alias points at `examples/`. All
+of this is dev-only: the library build has no Tailwind or shadcn dependency, and the only entry that
+touches React is `lib/react/`, where `react` is an optional peer dependency left external.
+
+Forms in the demos use native controls (`NativeSelect`, plain checkbox and radio inputs) rather than
+the Radix-based shadcn `Select`, `Checkbox` and `RadioGroup`: the library writes to native form
+controls, and a Radix widget with a hidden mirror input would not update visually.
+
+## Documentation
+
+- **The wiki** is authored in the repository, under `docs/wiki/`. Edit the page files there and open
+  a pull request like any other change; do not edit the pages in the GitHub wiki UI, because the next
+  sync overwrites them. After the pull request is merged, a maintainer runs `pnpm wiki:sync`, which
+  copies `docs/wiki/*.md` into the wiki repository and pushes it. File names become page titles, so
+  `Getting-Started.md` is the page "Getting Started" and links between pages are
+  `[Getting Started](Getting-Started)`. `_Sidebar.md` and `_Footer.md` are the wiki's navigation.
+- **The API reference** is generated from the TSDoc comments by `pnpm build:site`. Public symbols
+  carry TSDoc, and the rolled-up `dist/*.d.ts` preserves it for consumers, so document every new
+  exported symbol.
+- **The README** stays the short overview; the long guides belong in the wiki.
+
+## Docs site
+
+`pnpm build:site` builds what GitHub Pages serves at https://jdeffner.github.io/ai-form-fill/ into
+`site/`, which is gitignored:
+
+1. `vite build -c vite.site.config.js` builds the demo app with the base path `/ai-form-fill/`. The
+   app is hash-routed, so it needs no rewrite rules.
+2. `node scripts/build-site.mjs` copies `examples/vanilla.html` and the built
+   `dist/ai-form-fill.browser.js` into `site/examples/`. The page loads the bundle by relative path,
+   so the pair works under any base path.
+3. `typedoc` generates the API reference from the four entry points into `site/api`, which the "Docs"
+   link in the demo header points at. In `pnpm dev` that link 404s until you have run
+   `pnpm build:site` once.
+
+`.github/workflows/pages.yml` runs this on every push to `main` and deploys the result.
+
+## Pull requests
+
+- Keep pull requests focused. Renames and moves go in their own commit so diffs stay reviewable.
+- Before pushing, run
+  `pnpm lint && pnpm format:check && pnpm typecheck && pnpm test && pnpm build`. CI runs exactly
+  these, on Node 20 and 22.
+- Add a line under `## Unreleased` in `CHANGELOG.md` for anything a user would notice.
+- Public APIs carry TSDoc comments, so please document any new exported symbol.
+- `dist/` is tracked in git, because Composer installs from the repository. Do not edit it by hand,
+  but do commit the rebuilt output when you change `lib/`: CI fails a pull request against `main`
+  whose `dist/` is stale.
+
+The layout of the source and the invariants a change has to keep are in [Architecture](Architecture).
diff --git a/docs/wiki/Errors-and-Troubleshooting.md b/docs/wiki/Errors-and-Troubleshooting.md
new file mode 100644
index 0000000..5a2597e
--- /dev/null
+++ b/docs/wiki/Errors-and-Troubleshooting.md
@@ -0,0 +1,173 @@
+# Errors and Troubleshooting
+
+This page lists the error classes the library throws and the failures people actually hit, with the
+fix for each.
+
+## Error classes
+
+| Class                | Thrown when                                            | Carries                        |
+| -------------------- | ------------------------------------------------------ | ------------------------------ |
+| `AFFError`           | Base class; also configuration problems                | `message`                      |
+| `ProviderError`      | Network failure, HTTP error status, or timeout         | `provider`, `status?`, `cause` |
+| `ResponseParseError` | The model output was empty, not JSON, or not an object | `raw`                          |
+
+```typescript
+import { AFFError, ProviderError, ResponseParseError } from 'ai-form-fill';
+
+try {
+  await aiForm.fillForm(form, text);
+} catch (error) {
+  if (error instanceof ProviderError) {
+    console.error(`${error.provider} failed`, error.status, error.cause);
+  } else if (error instanceof ResponseParseError) {
+    console.error('Unusable model output:', error.raw);
+  } else if (error instanceof AFFError) {
+    console.error('Configuration problem:', error.message);
+  }
+}
+```
+
+Catch `AFFError` to handle all of them at once.
+
+Two rules make the rest predictable:
+
+- **Per-field problems never throw.** They land in `FillResult.skipped` with a reason.
+- **An abort you triggered is not an error.** A caller's `AbortSignal` rejection passes through
+  untouched, so cancelling is distinguishable from failing. The controller and the hook turn it into
+  a `null` result instead.
+
+`createFormFill` throws a plain `Error` when the form, source or trigger selector resolves to the
+wrong kind of element, with the selector in the message.
+
+## The fill does nothing and the console shows a CORS error
+
+Ollama only answers browser requests from origins it knows. `http://localhost` works, your staging
+domain does not.
+
+```bash
+OLLAMA_ORIGINS=https://app.example.com ollama serve
+```
+
+On Windows, set the `OLLAMA_ORIGINS` environment variable and restart Ollama. Several origins are
+comma-separated. Use `*` for local experiments only. The failure reaches your code as a
+`ProviderError` saying the connection failed, because the browser hides the reason from JavaScript.
+
+## `ProviderError` with status 401 or 403
+
+The request reached the service but was not authorised.
+
+- Through a proxy: the proxy did not add the key, the key is wrong, or the proxy requires your own
+  app's session and the request went out without it.
+- Direct: `apiKey` is missing. In a browser, `apiKey` also needs `allowApiKeyInBrowser: true`, and
+  the constructor throws an `AFFError` before any request goes out otherwise.
+
+Check `error.status` and `error.provider` to tell the two apart, and try the same call with `curl` to
+see the service's own message.
+
+## `ProviderError` with status 404
+
+The base URL is wrong. The library appends `/chat/completions` and `/models`, so `baseUrl` must be
+the prefix, not the full endpoint. `https://api.openai.com/v1` is right,
+`https://api.openai.com/v1/chat/completions` is not. Trailing slashes are stripped for you.
+
+For a proxy: it must forward exactly those two paths.
+
+## "does not support chat" or a 400 from Ollama
+
+The model is not a chat model, or the local copy is incomplete. Pull it again:
+
+```bash
+ollama pull gemma3:4b
+ollama run gemma3:4b "hello"
+```
+
+Embedding models (`nomic-embed-text` and friends) have no chat endpoint and cannot be used.
+
+## The model ignores the schema
+
+Symptoms: keys that are not in the form, prose around the JSON, option values that were never
+offered.
+
+- Check that the provider really enforces schemas. `supportsStructuredOutput()` has to be `true`, and
+  a custom provider must translate `ChatRequest.format` into the service's own mechanism.
+- Use a bigger or newer model. Very small models drift on long input.
+- Shorten the source text. A wall of unrelated text raises the chance of invented values.
+- Add `data-aff-hint` to the fields it gets wrong; see [Form Fields and Hints](Form-Fields-and-Hints).
+
+Values that are not in the schema simply end up in `result.unmatchedKeys` and are never written, so
+this is a quality problem, not a safety problem.
+
+## `ResponseParseError`
+
+The answer was empty, or it was not a JSON object. `error.raw` holds exactly what came back, which is
+usually enough to see the cause: a refusal, a code fence around the JSON, or a truncated answer.
+
+Turn on `debug: true` to log the extracted data and the result, and try the same prompt against the
+model directly.
+
+## The result is empty: nothing was filled
+
+Check in this order:
+
+1. `result.unmatchedKeys` is full. The model answered with its own key names. Give the fields proper
+   `name` attributes, because keys come from `name` first.
+2. `result.skipped` is full. Read the reasons: they say exactly what was rejected.
+3. Both are empty. The model found nothing in the text. Check `result.raw`.
+4. `skipFilled` is on and the fields already had values, so nothing was requested at all.
+
+## Dates are skipped
+
+The reason is `invalid-date-format`. Values must be ISO (`YYYY-MM-DD`, `YYYY-MM-DDTHH:MM`, `HH:MM`,
+`YYYY-MM`, `YYYY-Www`) and are validated against the calendar. A local format like `15.03.1990` is
+rejected rather than guessed. Add a hint that tells the model what the source text's date style
+means, for example "dates are written day first".
+
+## A select or radio group does not match
+
+The reason is `no-matching-option`. Matching is exact on the value, then on the label, then
+case-insensitive on either. There is no substring matching, on purpose.
+
+- Give options human labels. `<option value="de">Germany</option>` matches both "de" and "Germany".
+- An `<option value="">` is a placeholder and is never selected.
+- Check for stray whitespace or a non-breaking space in the label.
+
+## React state does not update
+
+Values are written through the native prototype setters before the `input` event is dispatched, so
+controlled inputs update on their own. If yours does not:
+
+- The component is not a native `<input>`, `<textarea>` or `<select>`. A custom widget that renders a
+  `<div>` with roles is not filled.
+- The input is uncontrolled and you read the value from state that was never set. Read
+  `form.elements` or listen for `aff:done`.
+- A UI library keeps a hidden mirror input and paints from its own store. The mirror is filled but the
+  visible part does not change. Use the library's native control instead.
+
+## The custom element renders nothing
+
+- `defineFormFillElement()` was never called. The script-tag build calls it for you, module builds do
+  not.
+- The import ran after the markup and the element never upgraded. Imports at module level are fine;
+  a dynamic import inside a click handler is not.
+- The panel shows "No form found": `for` points at a selector that does not resolve, or the element
+  is not inside a form. Both are resolved with `document.querySelector` when the element connects, so
+  the form has to exist at that moment.
+
+## Nothing happens when the microphone is pressed
+
+The browser has no Web Speech API, or permission was denied. See [Voice Input](Voice-Input): the
+element hides the microphone when `isDictationSupported()` is `false`, and Firefox never has it.
+
+## Turning on logging
+
+```typescript
+new AIFormFill('ollama', { debug: true });
+createFormFill({ form: '#contact', debug: true });
+```
+
+```html
+<ai-form-fill for="#contact" debug></ai-form-fill>
+```
+
+It logs the extracted data and the fill result under `[ai-form-fill]`, per instance. There is no
+global switch.
diff --git a/docs/wiki/Events-Results-and-Review.md b/docs/wiki/Events-Results-and-Review.md
new file mode 100644
index 0000000..243a1db
--- /dev/null
+++ b/docs/wiki/Events-Results-and-Review.md
@@ -0,0 +1,161 @@
+# Events, Results and Review
+
+This page covers what a fill reports: the `aff:*` DOM events, the `FillResult`, undo, and the review
+path that writes nothing until the user agrees.
+
+## Events
+
+Every fill reports itself as `CustomEvent`s on the form. They bubble and cross shadow boundaries, so
+one listener on the form or on any ancestor sees everything. The names are in `HTMLElementEventMap`,
+so `event.detail` is typed.
+
+| Event              | `detail`                            | When                                           |
+| ------------------ | ----------------------------------- | ---------------------------------------------- |
+| `aff:start`        | `{ text }`                          | Before the provider request                    |
+| `aff:field-filled` | `{ key, element, value, previous }` | After a field was written                      |
+| `aff:done`         | The `FillResult`                    | After the fill finished                        |
+| `aff:error`        | `{ error }`                         | Extraction failed; the error is rethrown after |
+
+Nothing in the library listens to them, so you can use them freely.
+
+```typescript
+const form = document.querySelector('#contact');
+
+form.addEventListener('aff:start', () => spinner.show());
+form.addEventListener('aff:field-filled', (event) => {
+  event.detail.element.classList.add('just-filled');
+});
+form.addEventListener('aff:done', (event) => {
+  spinner.hide();
+  status.textContent = `Filled ${event.detail.filled.length} field(s).`;
+});
+form.addEventListener('aff:error', (event) => {
+  spinner.hide();
+  console.error(event.detail.error);
+});
+```
+
+`fillField` dispatches `aff:field-filled` on the field it wrote, not on the form, because a single
+field fill has no form context of its own. `revertFill` dispatches the plain `input` and `change`
+events, not `aff:*` ones.
+
+## FillResult
+
+Both `fillForm` and `applyExtraction` resolve to the same shape.
+
+| Field             | Type                                       | Meaning                                                     |
+| ----------------- | ------------------------------------------ | ----------------------------------------------------------- |
+| `filled`          | `Array<{ key, element, value, previous }>` | Every field that was written, with the value it held before |
+| `skipped`         | `Array<{ key, reason }>`                   | Fields the model answered for, whose value was not usable   |
+| `unmatchedKeys`   | `string[]`                                 | Keys in the answer that match no field of the form          |
+| `missingRequired` | `string[]`                                 | Required fields that are still empty, over the whole form   |
+| `raw`             | `string`                                   | The unmodified model output, for debugging                  |
+
+```typescript
+const result = await aiForm.fillForm(form, text);
+
+for (const entry of result.filled) console.log(entry.key, entry.value);
+for (const { key, reason } of result.skipped) console.warn(`${key}: ${reason}`);
+if (result.missingRequired.length) {
+  status.textContent = `Still needed: ${result.missingRequired.join(', ')}.`;
+}
+```
+
+`value` and `previous` are a `string` for single-value fields and a `string[]` for multi-value ones
+(checkbox groups and `<select multiple>`). A radio group that had nothing checked reports `''`.
+
+### Skip reasons
+
+| Reason                | Cause                                                             |
+| --------------------- | ----------------------------------------------------------------- |
+| `empty-value`         | The answer was empty or one of the "no value" words               |
+| `invalid-date-format` | The date or time did not match the required ISO format            |
+| `no-matching-option`  | No option of a select, radio group or checkbox group matched      |
+| `unsupported-value`   | The value's type cannot go into this field, for example an object |
+
+A skip is never an error: application problems land here, only provider and parse failures throw.
+See [Errors and Troubleshooting](Errors-and-Troubleshooting).
+
+### Missing required fields
+
+`missingRequired` is computed after the fill, over **all** fields of the form, not only the targeted
+ones. A radio or checkbox group counts as required when any member carries `required`. Use it to
+tell the user what is left to do by hand.
+
+## Undo
+
+Every `filled` entry records `previous`, so a fill can be taken back exactly, including empty
+strings, unchecked radio groups and multi-selects. The restore goes through the same native setters
+and events, so frameworks observe it too.
+
+```typescript
+import { revertFill } from 'ai-form-fill';
+
+const result = await aiForm.fillForm(form, text);
+revertFill(result); // everything back
+revertFill(result, ['email']); // or one field
+```
+
+The controller wraps it as `undo()`, which also clears the result and returns the state to `idle`.
+The element shows an Undo button after a fill.
+
+## Review before writing
+
+`extract` runs the request and the parsing but leaves the form alone. `applyExtraction` writes a
+reviewed extraction and returns the same `FillResult` as a fill. `fillForm` is exactly the two in
+sequence, so they cannot drift apart.
+
+### With the class
+
+```typescript
+const { data, fields, raw } = await aiForm.extract(form, text);
+// data: { firstName: 'John', email: 'john@example.com', ... }
+
+const edited = await showReviewUI(data); // your UI, your rules
+const result = aiForm.applyExtraction(edited, fields, { raw, form });
+```
+
+`fields` is the `FieldInfo[]` the schema was built from, in document order. Pass it back unchanged;
+it carries the element each key belongs to. Drop a key from `data` and that field is never written.
+`raw` and `form` are optional: `raw` only travels into the result, and `form` is where the events are
+dispatched (it is derived from the fields when omitted).
+
+### With the controller
+
+```typescript
+const controller = createFormFill({ form: '#contact', source: '#notes' });
+
+const { data, fields } = await controller.extract();
+const approved = Object.fromEntries(Object.entries(data).filter(([key]) => userAccepted.has(key)));
+const result = controller.applyExtracted(approved, fields);
+```
+
+`extract` rejects the way `AIFormFill.extract` does and leaves the state untouched.
+`applyExtracted` puts the result into the snapshot, so `undo()` works afterwards.
+
+### With the React hook
+
+```tsx
+const { formRef, extract, applyExtracted } = useFormFill();
+
+async function review(text: string) {
+  const { data, fields } = await extract(text);
+  setPending({ data, fields }); // render checkboxes from data
+}
+
+function apply(chosen: Record<string, unknown>) {
+  const result = applyExtracted(chosen, pending.fields);
+}
+```
+
+### With the element
+
+The `review` attribute does all of it: the panel lists one row per value with a checkbox, and Apply
+writes only the checked rows.
+
+```html
+<ai-form-fill for="#contact" review></ai-form-fill>
+```
+
+Use the review path whenever the form carries anything consequential. Model output is not to be
+trusted blindly, and a fill is never a submit.
diff --git a/docs/wiki/FAQ-and-Non-Goals.md b/docs/wiki/FAQ-and-Non-Goals.md
new file mode 100644
index 0000000..4eaf53e
--- /dev/null
+++ b/docs/wiki/FAQ-and-Non-Goals.md
@@ -0,0 +1,120 @@
+# FAQ and Non-Goals
+
+This page answers the questions that come up most, and says plainly what the library does not do.
+
+## Why is there no streaming?
+
+A fill is one request with one JSON answer, and the answer is only useful once it is complete. There
+is nothing to show while the tokens arrive: a half-parsed object cannot be written to a form, and
+watching fields flicker into place is worse than a spinner and a result. Streaming would add a
+parser for partial JSON and a second code path for no benefit.
+
+What you get instead: `aff:start` and `aff:done` for a progress indicator, `aff:field-filled` per
+field, and `cancel()` for a request that takes too long.
+
+## Why is there no conversation or agent engine?
+
+The library does one thing: text in, filled form out. It holds no history, sends no follow-up
+questions, and never decides to call something. That keeps the blast radius small (see
+[Security and Privacy](Security-and-Privacy)) and the API tiny.
+
+If you want a conversation, build it around the library: collect the text your way, then call
+`fill(text)`. `extract` and `applyExtraction` exist exactly so a bigger flow can sit between the two
+halves.
+
+## Why is Whisper not supported?
+
+Dictation uses the browser's Web Speech API, which needs no model download, no server and no key. A
+Whisper integration means either a several hundred megabyte model in the browser or an audio upload
+to a server you run, and both are decisions an application makes, not a form-filling library.
+
+It is on the roadmap as an optional adapter behind the same `Dictation` interface, so a page could
+swap the recogniser without changing anything else. Until then: `createDictation` produces text, and
+so does any other transcription you wire up. `controller.fill(text)` does not care where the text
+came from.
+
+## Why no Vue or Svelte packages?
+
+There is nothing for them to do. The library writes values through the native prototype setters and
+then dispatches `input` and `change`, so controlled components in every framework already update. A
+Vue package would be `onMounted` and `onUnmounted` around `createFormFill`, which is four lines you
+can read; see [Framework Guides](Framework-Guides).
+
+React gets a hook because the ref lifecycle and `useSyncExternalStore` wiring are genuinely fiddly,
+and because a hook is the only way to make a fill ordinary React state.
+
+`<ai-form-fill>` is a standard custom element, so every framework can use the full UI without any
+binding at all.
+
+## Why Ollama by default?
+
+Because it needs no key, no account and no backend, and because the text never leaves the machine.
+Form input is usually personal data, so a default that keeps it local is the right default. It also
+makes the library usable in a thesis, in a demo and in an offline environment without signing up for
+anything.
+
+Ollama enforces JSON schemas, which is what makes small local models reliable enough here: the
+model's answer is constrained to the form's own fields and the real option values.
+
+Cloud providers are one option away when you need better quality on long or messy text; see
+[Providers](Providers).
+
+## Does it work without a build step?
+
+Yes. One script tag registers the element and puts the whole API on the `AIFormFill` global. See
+[Installation and Builds](Installation-and-Builds).
+
+## Does it submit the form?
+
+No, and it never will. The library fills fields, the user checks them, your code submits. A fill is
+model output, and model output gets looked at before it becomes an action.
+
+## Can it fill a page that is not a form?
+
+No. `getFormFields` needs an `HTMLFormElement`. If your controls are not inside a form, wrap them in
+one, or use `extract()` and write the values yourself with `applyFieldValue(element, value)`.
+
+## Can it fill custom widgets?
+
+Only when a native `<input>`, `<select>` or `<textarea>` is in the DOM and drives the widget. A
+widget that renders a `<div>` with ARIA roles and keeps its state in a store does not update. See the
+limits section in [Form Fields and Hints](Form-Fields-and-Hints).
+
+## Is there a server-side version?
+
+No. The library is DOM code: it reads a form element and writes to form elements. On a server there
+is no form. The provider layer would be reusable, but a Node script that asks a model for JSON does
+not need this library.
+
+## What about other input types, like images or PDFs?
+
+Out of scope. The library takes text. Extract the text first, with whatever tool fits, then pass it
+to `fill(text)`.
+
+## Thesis background
+
+This library is the practical part of a bachelor thesis on AI-assisted form filling in the browser.
+Tag `v1.0.0` is the exact state that was submitted, and it is identical to version 1.0.1 on npm. The
+files in `tests/requirements/` trace to the thesis requirements (FR-01 to FR-11) and keep their
+`FR-XX` prefixes for that reason.
+
+2.0.0 is a rewrite with breaking changes: a ready-made element, dictation, a headless controller, a
+React hook, standard wire formats, lifecycle events and undo. `CHANGELOG.md` lists all of them.
+
+## How do I cite it?
+
+```
+Deffner, J. (2026). ai-form-fill: AI-assisted form filling in the browser (Version 1.0.0)
+[Computer software]. https://github.com/JDeffner/ai-form-fill
+```
+
+Cite `v1.0.0` for the thesis version and the current tag for anything else. The repository is MIT
+licensed, so no permission is needed to use or fork it.
+
+## Where do I report a bug or ask for a feature?
+
+- Bugs and features: https://github.com/JDeffner/ai-form-fill/issues
+- Security problems: https://github.com/JDeffner/ai-form-fill/security/advisories/new, never a public
+  issue.
+- Documentation fixes: edit `docs/wiki/` in the repository and open a pull request; see
+  [Contributing](Contributing).
diff --git a/docs/wiki/Form-Fields-and-Hints.md b/docs/wiki/Form-Fields-and-Hints.md
new file mode 100644
index 0000000..5c9c17f
--- /dev/null
+++ b/docs/wiki/Form-Fields-and-Hints.md
@@ -0,0 +1,167 @@
+# Form Fields and Hints
+
+This page describes which controls the library reads, what the model is told about each one, how a
+value is applied, and how to steer the extraction from your markup.
+
+## Which controls are read
+
+`getFormFields(form)` returns every `<input>`, `<textarea>` and `<select>` inside the form, in
+document order, except `submit`, `reset`, `button`, `image`, `hidden` and `file` inputs.
+
+| Control                                             | The model is told                                    | How the value is applied                                |
+| --------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------- |
+| `text`, `email`, `tel`, `url`, `search`, `password` | Type, label, placeholder, `pattern`; schema `string` | Written as text (`url` also carries `format: 'uri'`)    |
+| `number`, `range`                                   | Schema `number`                                      | Coerced to a string and written                         |
+| `<textarea>`                                        | Type `textarea`; schema `string`                     | Written as text                                         |
+| `date`                                              | Format `YYYY-MM-DD`; schema `format: 'date'`         | Validated as a real calendar date, then written         |
+| `datetime-local`                                    | Format `YYYY-MM-DDTHH:MM`; regex schema              | Validated, then written                                 |
+| `time`                                              | Format `HH:MM` (24h); regex schema                   | `9:30` is padded to `09:30`, then validated and written |
+| `month`                                             | Format `YYYY-MM`; regex schema                       | Validated, then written                                 |
+| `week`                                              | Format `YYYY-Www`; regex schema                      | Validated, then written                                 |
+| `<select>`                                          | The options as an `enum` of their real values        | Matched against the options, then written               |
+| `<select multiple>`                                 | An array schema with the same `enum`                 | Every matching option is selected                       |
+| Radio group (same `name`)                           | One field, options as an `enum`                      | The matching radio is checked                           |
+| Single checkbox                                     | Schema `boolean`                                     | Checked or unchecked                                    |
+| Checkbox group (same `name`)                        | One multi-value field, options as an `enum`          | Every matching box is checked, the others are unchecked |
+| Other input types (`color`, ...)                    | Schema `string`                                      | Written as text                                         |
+
+Radio buttons and checkboxes that share a `name` become one field, positioned where the first member
+sits. Values are written through the native prototype setters and followed by `input` and `change`
+events, so controlled components in React, Vue and Svelte update.
+
+## Field keys
+
+Every field gets one stable key, and the prompt, the JSON schema and the fill step all use it. It is
+derived once, in this order:
+
+1. the `name` attribute,
+2. the `id` attribute,
+3. `field_<n>`, counting from 1 in document order.
+
+Collisions are deduplicated with a numeric suffix: a second field that would be called `email`
+becomes `email_2`.
+
+The keys are what you see in a `FillResult`, and what `targetFields` matches against. Because `name`
+comes first, targeting by the name attribute works naturally.
+
+## Labels
+
+A good label is the strongest signal the model gets. They are resolved in this order:
+
+1. `<label for="...">` matching the field's `id`,
+2. a `<label>` the field sits inside,
+3. `aria-label`,
+4. `aria-labelledby` (the referenced elements' text, joined),
+5. `title`.
+
+For radios and checkboxes, the label of each option is resolved the same way and becomes the option
+label. The `placeholder` and the `pattern` attributes are sent as well, so they are worth filling in.
+
+## Hints
+
+`data-aff-hint` adds one sentence of guidance for a single field. It goes into the prompt and into
+the schema description.
+
+```html
+<input name="ref" data-aff-hint="The six-digit customer number, not the invoice number." />
+<input name="salary" type="number" data-aff-hint="Yearly gross, in euros, digits only." />
+```
+
+On a radio or checkbox group, the hints of all members are merged into one, so you can put a hint on
+whichever option needs the explanation.
+
+Use hints for what the label cannot say: the unit, the expected precision, which of two similar
+fields wins, or a house rule ("use the legal name, not the trading name").
+
+## Targeting fields
+
+`targetFields` restricts a fill to a list of keys. Everything else is left out of the prompt, the
+schema and the fill.
+
+```typescript
+new AIFormFill('ollama', { targetFields: ['name', 'email'] });
+createFormFill({ form: '#contact', targetFields: ['name', 'email'] });
+```
+
+```html
+<ai-form-fill for="#contact" target-fields="name,email"></ai-form-fill>
+```
+
+The class can change it later with `setFields(['name'])`, or `setFields(undefined)` for all fields.
+
+`missingRequired` is still computed over the whole form, so a targeted fill still tells you what the
+user has to complete by hand.
+
+## Skipping filled fields
+
+`skipFilled` excludes every field that already holds a value. They never reach the prompt, so the
+model does not answer for them and they can never be overwritten.
+
+```typescript
+await aiForm.fillForm(form, text, { skipFilled: true });
+createFormFill({ form: '#contact', skipFilled: true });
+```
+
+```html
+<ai-form-fill for="#contact" skip-filled></ai-form-fill>
+```
+
+A field counts as empty when it has an empty string, no selected option, an unchecked radio group, or
+an unchecked checkbox.
+
+## Date and time formats
+
+Values must be ISO, and they are validated before they are written. Anything else is skipped with
+`invalid-date-format` rather than guessed, so `15.03.1990` never silently becomes a 1991 date.
+
+| Input type       | Format             | Example            |
+| ---------------- | ------------------ | ------------------ |
+| `date`           | `YYYY-MM-DD`       | `1990-03-15`       |
+| `datetime-local` | `YYYY-MM-DDTHH:MM` | `2026-09-05T14:30` |
+| `time`           | `HH:MM` (24h)      | `14:30`            |
+| `month`          | `YYYY-MM`          | `2026-09`          |
+| `week`           | `YYYY-Www`         | `2026-W36`         |
+
+Seconds are accepted for `time` and `datetime-local`. A `date` is also checked against the calendar,
+so `2026-02-30` is rejected. Add a hint when your users write dates in a local format and the model
+needs the reminder.
+
+## How options are matched
+
+The value the model returns is matched against the options in this order:
+
+1. exact match on the option's `value`,
+2. exact match on the option's label,
+3. case-insensitive and whitespace-collapsed match on either.
+
+There is no substring matching, so `male` can never select `Female`. If nothing matches, the field is
+skipped with `no-matching-option`.
+
+An `<option value="">` is treated as a placeholder: it is not offered to the model and never
+selected. Because the schema carries the real values as an `enum`, a structured-output provider
+usually returns an exact match in the first place.
+
+For a single checkbox, `true`, `yes`, `1`, `checked` and `on` check it, `false`, `no`, `0`,
+`unchecked` and `off` uncheck it, and the checkbox's own value or label also means "check it".
+
+## Values that mean "nothing"
+
+A model often answers with a word instead of leaving the key out. These are treated as "no value",
+and the field is left untouched with the skip reason `empty-value`: an empty string, `null`, `n/a`,
+`none`, `no value`, `empty`, `undefined`, `unknown`, `missing`. The comparison ignores case and extra
+whitespace.
+
+## Limits
+
+- **File inputs are never filled.** A browser does not allow it, and the library does not try.
+- **Hidden inputs are skipped**, so a token or a tracking field cannot be overwritten.
+- **`contenteditable` regions are not form controls** and are not detected. Mirror the content into a
+  hidden field yourself, or fill the region from `extract()` in your own code.
+- **Custom widgets** (Radix, Headless UI, a `<div>` with roles) are not filled. The library writes to
+  native elements. Widgets that keep a real `<input>` or `<select>` in the DOM and mirror it work;
+  widgets that render a hidden mirror without a native control do not update visually.
+- **Objects and arrays** in the model's answer are only usable for multi-value fields. Anywhere else
+  they are skipped with `unsupported-value`.
+- **Fields outside the form element** are not seen, even when they point at it with the `form`
+  attribute.
+- Nothing is submitted. The library fills, the user checks, your code submits.
diff --git a/docs/wiki/Framework-Guides.md b/docs/wiki/Framework-Guides.md
new file mode 100644
index 0000000..578b291
--- /dev/null
+++ b/docs/wiki/Framework-Guides.md
@@ -0,0 +1,223 @@
+# Framework Guides
+
+This page shows the shortest working integration for each environment: vanilla JavaScript, React,
+Vue, Svelte, any framework through the custom element, and server-rendered pages.
+
+The library writes values through the native prototype setters and then dispatches `input` and
+`change`, so controlled components in every framework observe a fill exactly like typing. No adapter
+is needed.
+
+## Vanilla with your own markup
+
+`createFormFill` resolves elements or selectors and gives you a state machine.
+
+```html
+<textarea id="notes"></textarea>
+<button id="fill">Fill form</button>
+<button id="undo" hidden>Undo</button>
+<p id="status"></p>
+
+<form id="contact">
+  <input name="name" type="text" />
+  <input name="email" type="email" />
+</form>
+```
+
+```typescript
+import { createFormFill } from 'ai-form-fill';
+
+const fillButton = document.querySelector('#fill');
+const undoButton = document.querySelector('#undo');
+const status = document.querySelector('#status');
+
+const controller = createFormFill({
+  form: '#contact',
+  source: '#notes',
+  trigger: '#fill',
+  onState: ({ state, result, error }) => {
+    fillButton.disabled = state === 'working';
+    undoButton.hidden = state !== 'done';
+    if (state === 'working') status.textContent = 'Filling the form.';
+    if (state === 'done') status.textContent = `Filled ${result.filled.length} field(s).`;
+    if (state === 'error') status.textContent = String(error);
+  },
+});
+
+undoButton.addEventListener('click', () => controller.undo());
+window.addEventListener('pagehide', () => controller.destroy());
+```
+
+`fill()` never rejects: a failure lands in the snapshot and resolves to `null`.
+
+## React
+
+`ai-form-fill/react` is one hook. It creates the controller when the form mounts and destroys it
+when the form unmounts.
+
+```tsx
+import { useState } from 'react';
+import { useFormFill } from 'ai-form-fill/react';
+
+export function Contact() {
+  const [values, setValues] = useState({ name: '', email: '' });
+  const [text, setText] = useState('');
+  const { formRef, fill, undo, state, result } = useFormFill();
+  const set = (key: 'name' | 'email') => (event: React.ChangeEvent<HTMLInputElement>) =>
+    setValues((current) => ({ ...current, [key]: event.target.value }));
+
+  return (
+    <>
+      <textarea value={text} onChange={(event) => setText(event.target.value)} />
+      <button disabled={state === 'working'} onClick={() => fill(text)}>
+        Fill form
+      </button>
+      {state === 'done' && <button onClick={undo}>Undo</button>}
+      {result && <p>Filled {result.filled.length} field(s).</p>}
+
+      <form ref={formRef}>
+        <input name="name" value={values.name} onChange={set('name')} />
+        <input name="email" value={values.email} onChange={set('email')} />
+      </form>
+    </>
+  );
+}
+```
+
+The hook returns `formRef`, `fill`, `extract`, `applyExtracted`, `cancel`, `undo`, `state`, `result`
+and `error`. It takes the same options as `createFormFill` minus `form`, `source`, `trigger` and
+`onState`.
+
+**Options are read once**, when the controller is created for the mounted form. A new object on
+every render does not rebuild it. To switch provider or model, remount the form:
+
+```tsx
+<form key={provider} ref={formRef}>
+  ...
+</form>
+```
+
+**StrictMode** mounts, unmounts and remounts in development. The ref callback destroys the
+controller and builds a new one, so this is safe; the only visible effect is that the state resets to
+`idle` on the second mount.
+
+## Vue
+
+`createFormFill` is plain DOM code, so it belongs in `onMounted`.
+
+```vue
+<script setup lang="ts">
+import { onMounted, onUnmounted, ref } from 'vue';
+import { createFormFill, type FormFillController } from 'ai-form-fill';
+
+const form = ref<HTMLFormElement>();
+const filled = ref(0);
+let controller: FormFillController;
+
+onMounted(() => {
+  controller = createFormFill({ form: form.value!, source: '#notes', trigger: '#fill' });
+  form.value!.addEventListener('aff:done', (e) => (filled.value = e.detail.filled.length));
+});
+onUnmounted(() => controller.destroy());
+</script>
+
+<template>
+  <textarea id="notes"></textarea>
+  <button id="fill">Fill form</button>
+  <form ref="form">...</form>
+  <p v-if="filled">Filled {{ filled }} field(s).</p>
+</template>
+```
+
+The one-line alternative, with no controller to own:
+
+```vue
+<script setup lang="ts">
+import { defineFormFillElement } from 'ai-form-fill/ui';
+defineFormFillElement();
+</script>
+
+<template>
+  <ai-form-fill for="#contact" voice />
+</template>
+```
+
+Add `ai-form-fill` to `compilerOptions.isCustomElement` in your Vite config so Vue leaves the tag
+alone.
+
+## Svelte
+
+```svelte
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { createFormFill } from 'ai-form-fill';
+
+  let form: HTMLFormElement;
+  let filled = 0;
+
+  onMount(() => {
+    const controller = createFormFill({ form, source: '#notes', trigger: '#fill' });
+    form.addEventListener('aff:done', (e) => (filled = e.detail.filled.length));
+    return () => controller.destroy();
+  });
+</script>
+
+<textarea id="notes"></textarea>
+<button id="fill">Fill form</button>
+<form bind:this={form}>...</form>
+{#if filled}<p>Filled {filled} field(s).</p>{/if}
+```
+
+Svelte passes unknown tags through untouched, so the element needs no compiler configuration.
+
+## Any framework, through the element
+
+`<ai-form-fill>` is a standard custom element, so every framework can render it. Register it once at
+module level:
+
+```typescript
+import { defineFormFillElement } from 'ai-form-fill/ui';
+
+defineFormFillElement();
+```
+
+- **React** renders custom elements natively since 19; for TypeScript, declare the tag once (see
+  [Installation and Builds](Installation-and-Builds)).
+- **Vue** needs `isCustomElement`, as above.
+- **Angular** needs `CUSTOM_ELEMENTS_SCHEMA` on the module or component.
+- **Svelte, Solid, Lit and plain HTML** need nothing.
+
+The element resolves its form with `document.querySelector`, so `for` has to point at a form that is
+in the document. Inside a component that renders both, put the form before the element.
+
+## Server-rendered pages
+
+Rails, Laravel, Django, ASP.NET, WordPress or any template engine: add one script tag and one
+element. There is no build step and nothing to import.
+
+```html
+<form id="signup" method="post" action="/signup">
+  <input name="full_name" type="text" required />
+  <input name="email" type="email" required />
+  <select name="country">
+    <option value="">Choose</option>
+    <option value="de">Germany</option>
+    <option value="at">Austria</option>
+  </select>
+  <button type="submit">Sign up</button>
+</form>
+
+<ai-form-fill for="#signup" voice></ai-form-fill>
+<script src="https://cdn.jsdelivr.net/npm/ai-form-fill@2/dist/ai-form-fill.browser.js"></script>
+```
+
+The panel writes values into the form; your existing submit handler and your server-side validation
+stay exactly as they are. Never auto-submit after a fill, and validate on the server as you would
+for any user input.
+
+For a cloud provider, point `base-url` at a route of your own application that adds the API key:
+
+```html
+<ai-form-fill for="#signup" provider="openai" base-url="/ai"></ai-form-fill>
+```
+
+See [Running a Proxy](Running-a-Proxy).
diff --git a/docs/wiki/Getting-Started.md b/docs/wiki/Getting-Started.md
new file mode 100644
index 0000000..58bc370
--- /dev/null
+++ b/docs/wiki/Getting-Started.md
@@ -0,0 +1,129 @@
+# Getting Started
+
+This page takes you from an empty project to a first filled form, with local Ollama and no API key.
+
+## Install
+
+```bash
+npm install ai-form-fill
+```
+
+`pnpm add ai-form-fill` and `yarn add ai-form-fill` work the same. You can also skip the install and
+use a script tag; see [Installation and Builds](Installation-and-Builds).
+
+## Set up Ollama
+
+Ollama runs the model on your machine, so no text leaves it and no key is needed.
+
+1. Install [Ollama](https://ollama.com).
+2. Pull the default model:
+
+   ```bash
+   ollama pull gemma3:4b
+   ```
+
+3. Check that it answers: `curl http://localhost:11434/api/tags`.
+
+The library talks to `http://localhost:11434` by default.
+
+### CORS, when your page is not on localhost
+
+Ollama only accepts browser requests from origins it knows. A page on `http://localhost:5173`
+works out of the box. A page on any other origin needs the origin in `OLLAMA_ORIGINS`:
+
+```bash
+OLLAMA_ORIGINS=https://app.example.com ollama serve
+```
+
+On Windows set the `OLLAMA_ORIGINS` environment variable and restart Ollama. Without it the fill
+fails with a `ProviderError` that says the connection failed, and the browser console shows a CORS
+error. See [Errors and Troubleshooting](Errors-and-Troubleshooting).
+
+## The first fill, three ways
+
+All three do the same work. Pick the highest one that fits, and drop a level when you need more
+control.
+
+### 1. The element
+
+The panel with a text box, a fill button, status, a summary and undo.
+
+```html
+<form id="contact">
+  <input name="name" type="text" />
+  <input name="email" type="email" />
+  <input name="phone" type="tel" />
+</form>
+<ai-form-fill for="#contact"></ai-form-fill>
+```
+
+```typescript
+import { defineFormFillElement } from 'ai-form-fill/ui';
+
+defineFormFillElement();
+```
+
+Full reference: [UI Component](UI-Component).
+
+### 2. The controller
+
+Your markup, the library's wiring: it resolves the form, the text source and the trigger, and
+reports an `idle` / `working` / `done` / `error` state.
+
+```html
+<textarea id="notes"></textarea>
+<button id="fill">Fill form</button>
+<form id="contact">
+  <input name="name" type="text" />
+  <input name="email" type="email" />
+</form>
+```
+
+```typescript
+import { createFormFill } from 'ai-form-fill';
+
+const button = document.querySelector('#fill');
+
+const controller = createFormFill({
+  form: '#contact',
+  source: '#notes',
+  trigger: '#fill',
+  onState: ({ state, result }) => {
+    button.disabled = state === 'working';
+    if (result) console.log(`Filled ${result.filled.length} field(s)`);
+  },
+});
+```
+
+Call `controller.destroy()` when the page or the component goes away.
+
+### 3. The class
+
+One fill per call, no DOM of its own.
+
+```typescript
+import { AIFormFill } from 'ai-form-fill';
+
+const form = document.querySelector('#contact');
+const aiForm = new AIFormFill('ollama', { model: 'gemma3:4b' });
+
+const result = await aiForm.fillForm(form, 'John Doe, john@example.com, 555-1234');
+console.log(result.filled.map((entry) => entry.key));
+```
+
+## What happens under the hood
+
+1. `getFormFields(form)` reads every fillable control and gives each a stable key.
+2. The prompt and a JSON schema are built from those fields, with the real option values as enums.
+3. The provider is called (`POST /api/chat` for Ollama).
+4. The answer is parsed into a `Record<string, unknown>` keyed by the field keys.
+5. Each value is written through the native setters, with `input` and `change` events, and the
+   outcome is reported as a `FillResult`.
+
+The details are in [Architecture](Architecture).
+
+## Next
+
+- Change the model or the service: [Providers](Providers).
+- Let the user speak instead of typing: [Voice Input](Voice-Input).
+- React to a fill in your own code: [Events, Results and Review](Events-Results-and-Review).
diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md
new file mode 100644
index 0000000..688c4fa
--- /dev/null
+++ b/docs/wiki/Home.md
@@ -0,0 +1,56 @@
+# ai-form-fill wiki
+
+This is the entry point of the guides: what the library does, and where every topic lives.
+
+`ai-form-fill` fills any HTML form from text or speech. The user pastes a paragraph or talks, the
+library reads the form, builds a JSON schema from it, asks a model, and writes the answer back
+through native setters. It runs against local [Ollama](https://ollama.com) with no key and no
+backend, or against any OpenAI-compatible API, and it has zero runtime dependencies.
+
+## The shortest working page
+
+```html
+<form id="contact">
+  <input name="name" type="text" />
+  <input name="email" type="email" />
+</form>
+<ai-form-fill for="#contact"></ai-form-fill>
+<script src="https://cdn.jsdelivr.net/npm/ai-form-fill@2/dist/ai-form-fill.browser.js"></script>
+```
+
+Install Ollama and run `ollama pull gemma3:4b` once, then open the page. See
+[Getting Started](Getting-Started) for the same thing with npm, and for the controller and class
+paths.
+
+## Use it
+
+- [Getting Started](Getting-Started) — install, Ollama, the first fill in three ways.
+- [Installation and Builds](Installation-and-Builds) — npm, script tag, entry points, types.
+- [UI Component](UI-Component) — every attribute, part and custom property of `<ai-form-fill>`.
+- [Voice Input](Voice-Input) — `createDictation`, browser support, permissions.
+- [Framework Guides](Framework-Guides) — vanilla, React, Vue, Svelte, server-rendered pages.
+
+## Configure
+
+- [Providers](Providers) — Ollama, OpenAI-compatible services, custom providers.
+- [Running a Proxy](Running-a-Proxy) — keep the API key on the server.
+- [Form Fields and Hints](Form-Fields-and-Hints) — supported controls, keys, labels, hints.
+- [Events, Results and Review](Events-Results-and-Review) — `aff:*` events, `FillResult`, undo.
+
+## Understand
+
+- [Architecture](Architecture) — the data flow and the extension points.
+- [Security and Privacy](Security-and-Privacy) — where the data goes, and what to guard.
+- [Errors and Troubleshooting](Errors-and-Troubleshooting) — error classes and common failures.
+
+## Contribute
+
+- [Contributing](Contributing) — setup, scripts, tests, pull request rules.
+- [Releasing](Releasing) — version policy, tags, npm publish, docs deploy.
+- [FAQ and Non-Goals](FAQ-and-Non-Goals) — what the library does not do, and why.
+
+## Elsewhere
+
+- Live demo: https://jdeffner.github.io/ai-form-fill/
+- API reference: https://jdeffner.github.io/ai-form-fill/api/
+- Source: https://github.com/JDeffner/ai-form-fill
diff --git a/docs/wiki/Installation-and-Builds.md b/docs/wiki/Installation-and-Builds.md
new file mode 100644
index 0000000..2a4312f
--- /dev/null
+++ b/docs/wiki/Installation-and-Builds.md
@@ -0,0 +1,133 @@
+# Installation and Builds
+
+This page covers every way to get the library into a page, and what each build output contains.
+
+## Package managers
+
+```bash
+npm install ai-form-fill
+pnpm add ai-form-fill
+yarn add ai-form-fill
+```
+
+Node 20 or newer is required for the build tooling; the library itself only needs a browser with
+`fetch` and `AbortController`. `react` is an optional peer dependency (`>=18`) and is only needed
+for `ai-form-fill/react`.
+
+## Script tag
+
+One tag registers `<ai-form-fill>` and puts the whole API on the `AIFormFill` global. No bundler, no
+import.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/ai-form-fill@2/dist/ai-form-fill.browser.js"></script>
+```
+
+unpkg serves the same file:
+
+```html
+<script src="https://unpkg.com/ai-form-fill@2/dist/ai-form-fill.browser.js"></script>
+```
+
+Pin the version for production. `@2` follows every 2.x release, `@2.0.0` never changes:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/ai-form-fill@2.0.0/dist/ai-form-fill.browser.js"></script>
+```
+
+From the global:
+
+```html
+<script>
+  const { createFormFill, revertFill, OllamaProvider } = window.AIFormFill;
+  const controller = createFormFill({ form: '#contact', source: '#notes', trigger: '#fill' });
+</script>
+```
+
+Load the script after the form, or at the end of `<body>`, so the element finds the form it points
+at on its first connect. If you load it in `<head>`, add `defer`.
+
+## Entry points
+
+| Import path          | ESM file                       | What it holds                                                   |
+| -------------------- | ------------------------------ | --------------------------------------------------------------- |
+| `ai-form-fill`       | `dist/ai-form-fill.js`         | `AIFormFill`, `createFormFill`, providers, form engine, errors  |
+| `ai-form-fill/ui`    | `dist/ui.js`                   | `defineFormFillElement`, `AIFormFillElement`, `DEFAULT_STRINGS` |
+| `ai-form-fill/voice` | `dist/voice.js`                | `createDictation`, `isDictationSupported`                       |
+| `ai-form-fill/react` | `dist/react.js`                | `useFormFill`                                                   |
+| script tag           | `dist/ai-form-fill.browser.js` | All of the above on the `AIFormFill` global, element registered |
+
+The split is deliberate: importing the core pulls in no markup, no speech code and no React.
+
+## ESM and CommonJS
+
+Every entry point ships both. `import` resolves to the `.js` file, `require` to the `.cjs` file:
+
+```typescript
+import { AIFormFill } from 'ai-form-fill';
+```
+
+```javascript
+const { AIFormFill } = require('ai-form-fill');
+```
+
+`dist/ai-form-fill.browser.js` is a minified IIFE for plain script tags. It is the only file with a
+side effect (it registers the element on load).
+
+## TypeScript
+
+Types ship with the package; no `@types` install is needed. Each entry point has a rolled-up
+declaration file (`dist/ai-form-fill.d.ts`, `dist/ui.d.ts`, `dist/voice.d.ts`, `dist/react.d.ts`)
+with the TSDoc comments preserved.
+
+The core declaration also augments `HTMLElementEventMap`, so `event.detail` is typed in a listener:
+
+```typescript
+form.addEventListener('aff:done', (event) => {
+  console.log(event.detail.filled.length); // FillResult
+});
+```
+
+The custom element is not in React's tag list, so a React app declares it once. An empty string
+means "attribute present":
+
+```tsx
+import type { HTMLAttributes } from 'react';
+
+type FormFillElementProps = HTMLAttributes<HTMLElement> & {
+  for?: string;
+  voice?: '';
+  review?: '';
+};
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'ai-form-fill': FormFillElementProps;
+    }
+  }
+}
+```
+
+## Composer and git installs
+
+`dist/` is tracked in the repository, so the package can be installed straight from git. This is for
+PHP asset pipelines; there are no PHP classes, it is a JavaScript asset package.
+
+```json
+{
+  "repositories": [{ "type": "vcs", "url": "https://github.com/JDeffner/ai-form-fill" }],
+  "require": { "jdeffner/ai-form-fill": "^2.0" }
+}
+```
+
+The files land in `vendor/jdeffner/ai-form-fill/dist/`. Serve
+`dist/ai-form-fill.browser.js` from your asset route, or point your bundler at `dist/ai-form-fill.js`.
+
+The same applies to a plain git dependency in `package.json`:
+
+```json
+{ "dependencies": { "ai-form-fill": "github:JDeffner/ai-form-fill#v2.0.0" } }
+```
+
+Because `dist/` is committed, no install-time build step runs.
diff --git a/docs/wiki/Providers.md b/docs/wiki/Providers.md
new file mode 100644
index 0000000..53ba695
--- /dev/null
+++ b/docs/wiki/Providers.md
@@ -0,0 +1,233 @@
+# Providers
+
+This page covers the two built-in providers, how to point them at any OpenAI-compatible service, and
+how to write your own.
+
+A provider does three things: it makes the network call, it translates the library's `ChatRequest`
+and `ChatResponse` to and from the service's wire format, and it reports which models it offers.
+Nothing else in the library knows about HTTP.
+
+## Ollama
+
+Local Ollama is the default and needs no configuration. It is the only provider that runs on the
+user's machine, so no text leaves it.
+
+```typescript
+import { AIFormFill, OllamaProvider } from 'ai-form-fill';
+
+const aiForm = new AIFormFill('ollama', { model: 'gemma3:4b' });
+// the same, explicitly:
+const provider = new OllamaProvider({ baseUrl: 'http://localhost:11434', model: 'gemma3:4b' });
+```
+
+| Option    | Default                  | Notes                            |
+| --------- | ------------------------ | -------------------------------- |
+| `baseUrl` | `http://localhost:11434` | Trailing slashes are stripped    |
+| `model`   | `gemma3:4b`              | Any tag `ollama list` shows      |
+| `timeout` | `30000`                  | Milliseconds                     |
+| `fetch`   | the global `fetch`       | Custom implementation, for tests |
+
+It calls `POST {baseUrl}/api/chat` with `stream: false`, and `GET {baseUrl}/api/tags` for the model
+list.
+
+**Structured output.** Ollama accepts a JSON schema in the top-level `format` field, so the model is
+constrained to the form's own fields and to the real option values. This is why small local models
+work well here. The schema avoids constructs that grammar-based enforcers reject; see
+[Architecture](Architecture).
+
+**Model choice.** Any instruction-following model works. `gemma3:4b` is the default because it is
+small enough for a laptop and follows the schema. Larger models make fewer mistakes on long text. A
+model without chat support fails with an HTTP error from Ollama; see
+[Errors and Troubleshooting](Errors-and-Troubleshooting).
+
+**CORS.** Ollama only answers browser requests from origins it knows. Set `OLLAMA_ORIGINS` when your
+page is not on localhost.
+
+## OpenAI-compatible services
+
+`OpenAICompatibleProvider` speaks the standard wire format: `POST {baseUrl}/chat/completions` and
+`GET {baseUrl}/models`, with structured output requested through
+`response_format: { type: 'json_schema', ... }`. Anything that speaks it works.
+
+### Presets
+
+A preset supplies a base URL and a default model. The names are also accepted directly by the
+`AIFormFill` constructor and by the element's `provider` attribute.
+
+| Name         | Base URL                       | Default model        |
+| ------------ | ------------------------------ | -------------------- |
+| `openai`     | `https://api.openai.com/v1`    | `gpt-5-nano`         |
+| `perplexity` | `https://api.perplexity.ai`    | `sonar`              |
+| `openrouter` | `https://openrouter.ai/api/v1` | `openai/gpt-4o-mini` |
+
+```typescript
+import { AIFormFill, OpenAICompatibleProvider } from 'ai-form-fill';
+
+const provider = new OpenAICompatibleProvider('openai', {
+  baseUrl: 'https://my-app.com/ai', // your proxy, the key stays server-side
+});
+const aiForm = new AIFormFill(provider);
+```
+
+### Any other service
+
+Any name works, as long as you supply a `baseUrl`. The name is only used for error messages and
+grouping. A missing `baseUrl` on a non-preset name throws an `AFFError` right in the constructor.
+
+```typescript
+// LM Studio
+new OpenAICompatibleProvider('lmstudio', {
+  baseUrl: 'http://localhost:1234/v1',
+  model: 'qwen2.5-7b-instruct',
+});
+
+// vLLM
+new OpenAICompatibleProvider('vllm', {
+  baseUrl: 'http://localhost:8000/v1',
+  model: 'meta-llama/Llama-3.1-8B-Instruct',
+});
+
+// Groq, Mistral, Anthropic and everything else: through your own gateway route,
+// so the key stays on the server.
+new OpenAICompatibleProvider('groq', { baseUrl: '/api/groq' });
+new OpenAICompatibleProvider('mistral', { baseUrl: '/api/mistral' });
+new OpenAICompatibleProvider('anthropic', {
+  baseUrl: '/api/anthropic',
+  model: 'claude-sonnet-4-5',
+});
+```
+
+Anthropic's own API is not OpenAI-compatible. Put a gateway (LiteLLM, an API gateway, or a route of
+your own) in front of it that speaks the OpenAI format, and point `baseUrl` at that.
+
+### Options
+
+| Option                 | Type                     | Notes                                                    |
+| ---------------------- | ------------------------ | -------------------------------------------------------- |
+| `baseUrl`              | `string`                 | Required for non-preset names                            |
+| `model`                | `string`                 | Falls back to the preset's model                         |
+| `apiKey`               | `string`                 | Sent as `Authorization: Bearer <key>`                    |
+| `allowApiKeyInBrowser` | `boolean`                | Explicit opt-in; without it `apiKey` throws in a browser |
+| `headers`              | `Record<string, string>` | Extra headers on every request                           |
+| `timeout`              | `number`                 | Milliseconds, default `30000`                            |
+| `fetch`                | `typeof fetch`           | Custom implementation                                    |
+
+### API keys
+
+The constructor refuses an `apiKey` in a browser, because anyone can read it out of a shipped page.
+For local prototyping you can opt in:
+
+```typescript
+const provider = new OpenAICompatibleProvider('openrouter', {
+  apiKey: 'sk-or-...',
+  allowApiKeyInBrowser: true, // prototyping only, never production
+  model: 'openai/gpt-4o-mini',
+});
+```
+
+In production, point `baseUrl` at a server-side passthrough instead. See
+[Running a Proxy](Running-a-Proxy) and [Security and Privacy](Security-and-Privacy).
+
+## Model selection and validation
+
+```typescript
+const models = await aiForm.getAvailableModels(); // GET {baseUrl}/models or /api/tags
+const ok = await aiForm.setSelectedModel('gemma3:12b');
+```
+
+`setSelectedModel` validates the name against the model list by default: it only sets the model, and
+only returns `true`, when the service actually offers it. When the list cannot be fetched, nothing
+is set and it returns `false`.
+
+Some services have no usable model list (Perplexity, most proxies that only forward
+`/chat/completions`). Skip the check there:
+
+```typescript
+await aiForm.setSelectedModel('sonar-pro', { validate: false }); // always true
+```
+
+`aiForm.getSelectedModel()` returns the current name, and `aiForm.isProviderAvailable()` resolves to
+`false` instead of throwing when the service cannot be reached.
+
+## Timeouts and abort
+
+Every request carries the provider's `timeout` (30 seconds by default). A timeout surfaces as a
+`ProviderError`.
+
+A caller's own `AbortSignal` is merged with it, and an abort you triggered is re-thrown untouched, so
+cancellation is distinguishable from failure:
+
+```typescript
+const abort = new AbortController();
+const result = await aiForm.fillForm(form, text, { signal: abort.signal });
+```
+
+The controller does this for you: `controller.cancel()` aborts the in-flight request and returns the
+state to `idle`, and starting a new fill cancels the previous one.
+
+## Writing a custom provider
+
+Extend `AIProvider` and use `requestJson` so timeouts, aborts and error translation stay uniform.
+
+```typescript
+import { AIProvider, requestJson, type ChatRequest, type ChatResponse } from 'ai-form-fill';
+import type { ProviderConfig, ProviderType } from 'ai-form-fill';
+
+type MyResponse = { output: string; model: string };
+
+export class MyProvider extends AIProvider {
+  protected readonly providerName = 'my-service';
+  protected readonly providerType: ProviderType = 'remote';
+  protected override supportsStructured = true;
+
+  constructor(config?: ProviderConfig) {
+    super({ ...config, baseUrl: config?.baseUrl ?? 'https://api.my-service.com' });
+  }
+
+  override async chat(request: ChatRequest): Promise<ChatResponse> {
+    const data = await requestJson<MyResponse>(`${this.baseUrl}/generate`, {
+      method: 'POST',
+      body: {
+        model: request.model,
+        messages: request.messages,
+        ...(request.format ? { schema: request.format } : {}),
+      },
+      timeout: this.timeout,
+      signal: request.signal,
+      provider: this.providerName,
+      fetchImpl: this.fetchImpl,
+    });
+    return { content: data.output, model: data.model };
+  }
+
+  override async listModels(): Promise<string[]> {
+    const data = await requestJson<{ models: string[] }>(`${this.baseUrl}/models`, {
+      timeout: this.timeout,
+      provider: this.providerName,
+      fetchImpl: this.fetchImpl,
+    });
+    return data.models ?? [];
+  }
+
+  override async isAvailable(): Promise<boolean> {
+    try {
+      await this.listModels();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+```
+
+Then pass the instance anywhere a provider name is accepted:
+
+```typescript
+const aiForm = new AIFormFill(new MyProvider());
+const controller = createFormFill({ form: '#contact', provider: new MyProvider() });
+document.querySelector('ai-form-fill').provider = new MyProvider();
+```
+
+Set `supportsStructured = true` only when the service really enforces a JSON schema, and translate
+`ChatRequest.format` into its mechanism. When it is `false`, the library still asks for JSON in the
+prompt and parses the answer, it just cannot guarantee the shape.
diff --git a/docs/wiki/Releasing.md b/docs/wiki/Releasing.md
new file mode 100644
index 0000000..af9af20
--- /dev/null
+++ b/docs/wiki/Releasing.md
@@ -0,0 +1,98 @@
+# Releasing
+
+This page describes how a version gets out: the version policy, the tag flow, what CI does, and the
+manual npm publish. Only the owner releases.
+
+## Version policy
+
+Semantic versioning. The public surface is everything exported from the four entry points, the
+element's attributes, properties, parts and `--aff-*` properties, and the `aff:*` event payloads.
+
+| Change                                                 | Bump  |
+| ------------------------------------------------------ | ----- |
+| Removing or renaming an export, an attribute or a part | major |
+| Changing a default that changes behaviour              | major |
+| A new export, option, attribute or provider            | minor |
+| A bug fix, a wording change, documentation             | patch |
+
+The current line is 2.x. Only 2.x gets fixes; 1.x and 0.x do not. Tag `v1.0.0` is the state submitted
+with the bachelor thesis and is identical to 1.0.1 on npm; it stays for reference.
+
+A prerelease uses a hyphen (`v2.1.0-rc.1`) and is marked as a prerelease automatically.
+
+## The release flow
+
+1. Update `CHANGELOG.md`: rename `## Unreleased` to `## X.Y.Z (YYYY-MM-DD)` and add a fresh empty
+   `## Unreleased` above it.
+2. Set the same version in `package.json`.
+3. Run `pnpm install && pnpm build`, then commit the rebuilt `dist/` as `release: vX.Y.Z`.
+4. Tag and push:
+
+   ```bash
+   git tag vX.Y.Z
+   git push && git push --tags
+   ```
+
+5. The tag triggers `.github/workflows/release.yml`.
+6. Publish to npm from a local checkout of the tag:
+
+   ```bash
+   npm publish --provenance --access public
+   ```
+
+## What CI does
+
+`.github/workflows/ci.yml` runs on every push and pull request, on Node 20 and 22: `pnpm lint`,
+`pnpm format:check`, `pnpm typecheck`, `pnpm test`, `pnpm build`. A separate job fails a pull request
+against `main` whose `dist/` is stale, because `dist/` is tracked for Composer installs. CI also
+fails a tag whose name does not match the version in `package.json`.
+
+`.github/workflows/release.yml` runs on a `v*` tag. It checks out the tag, runs lint, typecheck,
+tests and the build, fails if `dist/` does not match the source, reads the matching CHANGELOG section
+with `node scripts/changelog-section.mjs X.Y.Z`, and creates the GitHub release from it.
+
+It does **not** publish to npm. That is deliberate: no npm token lives in this repository. The
+workflow's last step prints the three commands for the manual publish.
+
+## Publishing to npm
+
+```bash
+git checkout vX.Y.Z
+pnpm install --frozen-lockfile && pnpm build
+npm publish --provenance --access public
+```
+
+`files` in `package.json` limits the tarball to `dist/`, `README.md` and `LICENSE`. Check the
+contents with `npm pack --dry-run` before publishing.
+
+Composer needs nothing: `jdeffner/ai-form-fill` installs from the git repository, and `dist/` is
+committed, so the tag is the release.
+
+## Documentation deploys
+
+- **The Pages site** (demo app and API reference) is built and deployed by
+  `.github/workflows/pages.yml` on every push to `main`. It needs no secret; the workflow uses the
+  built-in token with `pages: write` and `id-token: write`. The owner enables it once under
+  **Settings** -> **Pages** -> **Build and deployment** -> **Source: GitHub Actions**.
+- **The wiki** is not deployed by CI. After a pull request that touches `docs/wiki/` is merged, run:
+
+  ```bash
+  pnpm wiki:sync
+  ```
+
+  `scripts/sync-wiki.mjs` clones `https://github.com/JDeffner/ai-form-fill.wiki.git` into a temporary
+  directory, replaces its Markdown files with `docs/wiki/*.md`, commits
+  `docs: sync wiki from <sha>` and pushes. It does nothing when the content is unchanged, and it
+  removes the temporary clone afterwards. It needs push access to the wiki repository, which is the
+  same access as the code repository.
+
+## Release checklist
+
+- [ ] `## Unreleased` is empty and the new section is dated.
+- [ ] `package.json` version matches the tag you are about to create.
+- [ ] `pnpm lint && pnpm format:check && pnpm typecheck && pnpm test && pnpm build` passes.
+- [ ] `git status` is clean, with the rebuilt `dist/` committed.
+- [ ] The README and the wiki mention any new option, attribute or entry point.
+- [ ] The tag is pushed and the GitHub release looks right.
+- [ ] `npm publish` is done and the version shows up on npm.
+- [ ] `pnpm wiki:sync` is run if `docs/wiki/` changed.
diff --git a/docs/wiki/Running-a-Proxy.md b/docs/wiki/Running-a-Proxy.md
new file mode 100644
index 0000000..24f2654
--- /dev/null
+++ b/docs/wiki/Running-a-Proxy.md
@@ -0,0 +1,141 @@
+# Running a Proxy
+
+This page shows how to use a cloud provider without shipping the API key, with a Node proxy, a
+Cloudflare Worker, and a hardening checklist.
+
+## Why
+
+An API key in frontend code is a public key. Anyone can open the network tab, copy it, and spend
+your quota. The library refuses an `apiKey` in a browser for exactly this reason.
+
+The fix is a passthrough: the browser calls your server, your server adds the key and forwards the
+call. The library needs nothing special for this, because it speaks the standard OpenAI wire format.
+Your proxy only has to forward two routes:
+
+- `POST {baseUrl}/chat/completions`
+- `GET {baseUrl}/models`
+
+The second one is only used by `getAvailableModels()` and by `setSelectedModel` with validation. A
+proxy that forwards only the first route works, as long as you set the model explicitly or pass
+`{ validate: false }`.
+
+## Node
+
+`examples/server/proxy.mjs` in the repository is a zero-dependency passthrough of about 40 lines.
+
+```bash
+# OpenAI
+UPSTREAM=https://api.openai.com/v1 API_KEY=sk-... node examples/server/proxy.mjs
+
+# OpenRouter
+UPSTREAM=https://openrouter.ai/api/v1 API_KEY=sk-or-... node examples/server/proxy.mjs
+
+# Perplexity (no /models endpoint upstream, so set the model explicitly)
+UPSTREAM=https://api.perplexity.ai API_KEY=pplx-... node examples/server/proxy.mjs
+```
+
+On Windows, in PowerShell:
+
+```powershell
+$env:UPSTREAM = 'https://api.openai.com/v1'; $env:API_KEY = 'sk-...'; node examples/server/proxy.mjs
+```
+
+It listens on port 8787 by default (`PORT` changes it), forwards the two routes, answers everything
+else with 404, and sends permissive CORS headers, which is fine for local development and not for
+production.
+
+## Cloudflare Worker
+
+The same passthrough, deployed at the edge. Create it with `npm create cloudflare@latest`, replace
+`src/index.js`, then set the key as a secret with `npx wrangler secret put API_KEY`.
+
+```javascript
+const UPSTREAM = 'https://api.openai.com/v1';
+const ALLOWED_ORIGIN = 'https://app.example.com';
+
+const cors = {
+  'Access-Control-Allow-Origin': ALLOWED_ORIGIN,
+  'Access-Control-Allow-Headers': 'Content-Type',
+  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+  Vary: 'Origin',
+};
+
+export default {
+  async fetch(request, env) {
+    if (request.method === 'OPTIONS') return new Response(null, { status: 204, headers: cors });
+
+    const { pathname } = new URL(request.url);
+    const allowed =
+      (request.method === 'POST' && pathname === '/chat/completions') ||
+      (request.method === 'GET' && pathname === '/models');
+    if (!allowed) return new Response('Not found', { status: 404, headers: cors });
+
+    const upstream = await fetch(`${UPSTREAM}${pathname}`, {
+      method: request.method,
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${env.API_KEY}` },
+      body: request.method === 'POST' ? await request.text() : undefined,
+    });
+    return new Response(upstream.body, {
+      status: upstream.status,
+      headers: { ...cors, 'Content-Type': 'application/json' },
+    });
+  },
+};
+```
+
+`env.API_KEY` comes from the secret, so the key is never in the code, in the repository or in the
+browser.
+
+## Point the library at it
+
+```typescript
+import { AIFormFill, OpenAICompatibleProvider } from 'ai-form-fill';
+
+const provider = new OpenAICompatibleProvider('openai', {
+  baseUrl: 'https://ai-proxy.example.workers.dev',
+});
+const aiForm = new AIFormFill(provider);
+```
+
+With the controller, or with the element, the base URL is one option:
+
+```typescript
+createFormFill({ form: '#contact', provider: 'openai', baseUrl: '/ai' });
+```
+
+```html
+<ai-form-fill for="#contact" provider="openai" base-url="/ai"></ai-form-fill>
+```
+
+A same-origin route (`/ai`) needs no CORS headers at all, which is the simplest setup: add the two
+routes to the application you already run.
+
+## Hardening checklist
+
+The examples above are passthroughs. Before one faces the internet:
+
+- **Restrict the origin.** Set `Access-Control-Allow-Origin` to your exact origin, not `*`, and send
+  `Vary: Origin`. A same-origin route avoids the question.
+- **Authenticate your own users.** The proxy holds your key, so anyone who can call it can spend it.
+  Require the session cookie or bearer token your app already uses, and reject anonymous calls.
+- **Rate limit.** Per user and per IP. One filled form is one request; a hundred per minute is an
+  attack.
+- **Cap the request size.** Reject bodies over a few hundred kilobytes, so nobody sends a book.
+- **Pin the model, or allow-list it.** The body carries a `model` field from the browser. Overwrite
+  it server-side, or check it against a list, so nobody switches to your most expensive model.
+- **Do not forward client headers.** Build the upstream headers yourself, so a client cannot inject
+  its own `Authorization`.
+- **Forward only the two routes.** Everything else gets a 404, so the proxy is not a general tunnel
+  to the provider's API.
+- **Log without the payload.** The request body contains the user's text, which is usually personal
+  data. Log status codes and timing, not content.
+- **Set a timeout** on the upstream call, so a slow provider does not tie up your workers.
+
+## Alternatives
+
+The wire format is standard, so anything that speaks it can take the proxy's place:
+
+- **LiteLLM** in front of any provider, including Anthropic and Gemini.
+- An **API gateway** (Kong, APISIX, cloud gateways) with a key-injection plugin.
+- A **route in your existing backend**, which is usually the least work: you already have sessions,
+  rate limits and logging there.
diff --git a/docs/wiki/Security-and-Privacy.md b/docs/wiki/Security-and-Privacy.md
new file mode 100644
index 0000000..b884946
--- /dev/null
+++ b/docs/wiki/Security-and-Privacy.md
@@ -0,0 +1,131 @@
+# Security and Privacy
+
+This page describes where the data goes, what the library guarantees, and what you have to do
+yourself.
+
+Vulnerability reports go through
+[the security policy](https://github.com/JDeffner/ai-form-fill/security/advisories/new), not through
+a public issue.
+
+## Where the data goes
+
+One fill moves the user's text through this path:
+
+```
+user text (typed or dictated)
+  -> the browser (never stored by the library)
+  -> the configured provider: Ollama on the machine, or an HTTP endpoint you configured
+  -> the model's answer, back into the form's fields
+```
+
+Nothing else happens. The library writes no storage, sends no telemetry, and calls no endpoint other
+than the configured `baseUrl`. It has zero runtime dependencies, so no third-party code is loaded
+either.
+
+If the user dictates, there is one more hop **before** all of this: the browser sends the audio to
+its vendor's speech service. See [Voice Input](Voice-Input).
+
+## Local versus cloud
+
+|                     | Local Ollama             | Cloud provider                                   |
+| ------------------- | ------------------------ | ------------------------------------------------ |
+| Where the text goes | Stays on the machine     | To that vendor, under your contract with them    |
+| API key             | None                     | Required, and it must stay on your server        |
+| GDPR footprint      | None beyond the browser  | A processor, a legal basis, and a privacy notice |
+| Quality             | Good with a decent model | Usually better on long or messy text             |
+
+Local Ollama is the default for this reason: a form full of personal data can be filled with nothing
+leaving the machine.
+
+## API keys
+
+**Keys do not belong in shipped frontend code.** Anyone can read them out of a bundle or a network
+log. `OpenAICompatibleProvider` refuses an `apiKey` in a browser and throws an `AFFError` that says
+so.
+
+The escape hatch is explicit and named after what it is:
+
+```typescript
+new OpenAICompatibleProvider('openrouter', {
+  apiKey: 'sk-or-...',
+  allowApiKeyInBrowser: true, // local prototyping only
+});
+```
+
+Use it on your own machine while you try something, and never in a page you deploy. A key that leaks
+because a page shipped it on purpose with this flag is not a library vulnerability; a way around the
+check is.
+
+The production setup is a server-side passthrough: [Running a Proxy](Running-a-Proxy). Your proxy
+holds the key, authenticates your own users, and rate-limits them.
+
+## Prompt injection
+
+Text the user pastes or dictates is model input, and it can contain instructions. Assume it does.
+
+The design bounds the damage rather than trying to detect the attack:
+
+- Extracted values only ever reach fields of the form that was passed in. There is no selector, no
+  path and no element reference in the model's answer, only keys.
+- Keys that match no field are collected in `result.unmatchedKeys` and are never written.
+- Option-based fields are constrained by an `enum` of the real option values, and matching is exact.
+  A value that was not offered cannot be selected.
+- Model output is written as a field **value** through native setters and rendered as **text** in the
+  element's shadow root. It never becomes markup.
+- Nothing is submitted, nothing is stored, and no request other than the provider call is made.
+
+The worst case is therefore a form filled with wrong values, in front of a user who can see them.
+That is why the library never auto-submits, and why review mode exists.
+
+Your side of the bargain:
+
+- **Never auto-submit a filled form.** The user has to look at it.
+- **Validate on the server** exactly as you would for typed input. A filled field is user input.
+- **Prefer the review path** when the form carries anything consequential: money, permissions,
+  contracts, medical data.
+- Do not feed the model text from an untrusted third party and then submit the result automatically.
+
+## Cross-site scripting
+
+Model output is never inserted as HTML. Field values go through `value`, `checked` and `selected`,
+and the element's own labels and summaries are set with `textContent`. Anything that turns model
+output into markup or into an executed script is a bug worth reporting.
+
+The element lives in an open shadow root and exposes only the documented `::part` names and `--aff-*`
+properties. Anything that reaches the host page beyond that surface is also a bug.
+
+## GDPR notes
+
+This is a practical checklist, not legal advice.
+
+- **Form input is usually personal data.** Names, addresses, dates of birth, CVs. So is the source
+  text the user pastes, which is often a whole letter or CV.
+- **A cloud provider is a processor.** You need a legal basis, a data processing agreement, and an
+  entry in your record of processing activities. Check where the vendor runs and what it does with
+  the input.
+- **Say it in the privacy notice**: which provider receives the text, in which country, and that
+  dictation sends audio to the browser vendor.
+- **Local Ollama avoids all of it.** The text never leaves the device, so there is no transfer and no
+  processor.
+- **Data minimisation.** Use `targetFields` so only the fields you need are described to the model,
+  and do not log the source text. Log status codes and timing instead.
+- **The library stores nothing.** Retention is entirely a question about your provider and your own
+  logs.
+
+## Voice
+
+Dictation uses the browser's Web Speech API. In Chromium the audio is sent to a Google speech
+service, in Safari to Apple's. The library never touches the microphone stream itself; it only
+receives the transcript. Firefox has no such API, so the microphone is hidden there.
+
+Mention this in your privacy notice, and keep typing available as an alternative.
+
+## What counts as a vulnerability
+
+Reportable: an API key reaching the browser or a provider other than the configured one, extracted
+values written outside the given form, model output that becomes markup or script, and any escape
+from the shadow root beyond the documented surface.
+
+Not reportable: a model returning wrong values, text going to the provider you configured, a key
+leaking because the page shipped it with `allowApiKeyInBrowser: true`, and vulnerabilities in a
+provider service, in Ollama, or in the browser's speech API.
diff --git a/docs/wiki/UI-Component.md b/docs/wiki/UI-Component.md
new file mode 100644
index 0000000..bc3d4b0
--- /dev/null
+++ b/docs/wiki/UI-Component.md
@@ -0,0 +1,216 @@
+# UI Component
+
+This page is the full reference for `<ai-form-fill>`: attributes, properties, states, styling and
+accessibility.
+
+The element is plain DOM in a shadow root. It has no dependencies, injects no CSS into your page,
+and inherits the page font and text colour, so it reads on light and dark pages.
+
+## Register it
+
+```typescript
+import { defineFormFillElement } from 'ai-form-fill/ui';
+
+defineFormFillElement(); // registers <ai-form-fill>
+defineFormFillElement('my-fill'); // or under your own tag name
+```
+
+Calling it twice, or with a tag that is already taken, does nothing. The script-tag build registers
+`ai-form-fill` on load, so there is nothing to call.
+
+```html
+<form id="contact">...</form>
+<ai-form-fill for="#contact"></ai-form-fill>
+```
+
+Leave `for` out when the element sits inside the form.
+
+## Attributes
+
+| Attribute       | Value                                          | Default           | Effect                                                 |
+| --------------- | ---------------------------------------------- | ----------------- | ------------------------------------------------------ |
+| `for`           | CSS selector                                   | closest `<form>`  | The form to fill                                       |
+| `provider`      | `ollama`, `openai`, `perplexity`, `openrouter` | `ollama`          | Built-in provider by name                              |
+| `model`         | model id                                       | the provider's    | Model to use                                           |
+| `base-url`      | URL                                            | the provider's    | Endpoint, for example your proxy                       |
+| `target-fields` | comma-separated keys                           | all fields        | Fill only these fields                                 |
+| `skip-filled`   | present or absent                              | absent            | Leave fields that already hold a value alone           |
+| `voice`         | present or absent                              | absent            | Show the microphone, if the browser supports dictation |
+| `lang`          | BCP 47 tag, e.g. `de-DE`                       | document language | Language of the dictation                              |
+| `review`        | present or absent                              | absent            | Extract first, write only what the user checks         |
+| `label`         | text                                           | English default   | The label above the text box                           |
+| `placeholder`   | text                                           | English default   | The text box placeholder                               |
+| `debug`         | present or absent                              | absent            | Console logging for this instance                      |
+
+Changing any of them rebuilds the controller, which cancels an in-flight fill.
+
+## Properties
+
+Three things cannot fit in an attribute.
+
+| Property     | Type                                    | Notes                                                   |
+| ------------ | --------------------------------------- | ------------------------------------------------------- |
+| `provider`   | `AIProvider` instance or a name         | Wins over the `provider` attribute                      |
+| `strings`    | `Partial<AIFormFillStrings>`            | Replaces any piece of text; assign a partial object     |
+| `controller` | `FormFillController \| null`, read-only | The controller behind the panel, or `null` with no form |
+
+```typescript
+import { OpenAICompatibleProvider } from 'ai-form-fill';
+
+const panel = document.querySelector('ai-form-fill');
+panel.provider = new OpenAICompatibleProvider('openai', { baseUrl: '/api/ai' });
+panel.controller.subscribe((snapshot) => console.log(snapshot.state));
+```
+
+## States
+
+The panel node carries the current state as `data-state`, so your CSS can react to it.
+
+| State       | What is showing                                                      |
+| ----------- | -------------------------------------------------------------------- |
+| `idle`      | Text box and the fill button                                         |
+| `listening` | Dictation is running, the microphone is pressed                      |
+| `working`   | The provider request is in flight; Cancel is shown, Fill is disabled |
+| `review`    | The extracted values with one checkbox per row; Apply and Discard    |
+| `done`      | The result line, the skipped fields, and Undo                        |
+| `error`     | The failure message, in the error colour                             |
+
+## Review mode
+
+With the `review` attribute the element extracts first and writes nothing. Every value the model
+produced becomes a row with a checkbox, and Apply writes only the checked rows.
+
+```html
+<ai-form-fill for="#contact" review></ai-form-fill>
+```
+
+Discard drops the extraction and returns to `idle`. The same two halves are available in code; see
+[Events, Results and Review](Events-Results-and-Review).
+
+## Undo
+
+After a fill the panel shows Undo, which restores every value the fill overwrote, including empty
+strings and unchecked radio groups. It is `revertFill(result)` behind the button.
+
+## Follow-up fills
+
+The text box keeps its content after a fill, so the user can correct the text and press Fill again.
+A second fill overwrites what the first one wrote, and its own `previous` values become the new undo
+state. Add `skip-filled` when the second pass should only complete the empty fields:
+
+```html
+<ai-form-fill for="#contact" skip-filled></ai-form-fill>
+```
+
+Fields that already hold a value are then left out of the prompt and the schema entirely.
+
+## Wording
+
+Every piece of text is replaceable through the `strings` property. Import `DEFAULT_STRINGS` to see
+or reuse the English wording.
+
+```typescript
+import { DEFAULT_STRINGS } from 'ai-form-fill/ui';
+
+const panel = document.querySelector('ai-form-fill');
+panel.strings = {
+  label: 'Formular mit KI ausfüllen',
+  placeholder: 'Beschreiben Sie, was in das Formular soll.',
+  fill: 'Ausfüllen',
+  statusDone: (filled) => `${filled} Feld(er) ausgefüllt.`,
+};
+```
+
+| Key               | Type                                            | Where it shows                          |
+| ----------------- | ----------------------------------------------- | --------------------------------------- |
+| `label`           | `string`                                        | Label above the text box                |
+| `placeholder`     | `string`                                        | Text box placeholder                    |
+| `fill`            | `string`                                        | Fill button                             |
+| `dictate`         | `string`                                        | Microphone button while idle            |
+| `listening`       | `string`                                        | Microphone tooltip while listening      |
+| `stop`            | `string`                                        | Microphone button while listening       |
+| `cancel`          | `string`                                        | Cancel button                           |
+| `undo`            | `string`                                        | Undo button                             |
+| `apply`           | `string`                                        | Apply button in review mode             |
+| `discard`         | `string`                                        | Discard button in review mode           |
+| `statusListening` | `string`                                        | Status while dictating                  |
+| `statusWorking`   | `string`                                        | Status while the request runs           |
+| `statusEmpty`     | `string`                                        | Fill pressed with an empty text box     |
+| `statusDone`      | `(filled: number) => string`                    | Status after a fill                     |
+| `statusMissing`   | `(labels: string[]) => string`                  | Appended when required fields are empty |
+| `statusSkipped`   | `(label: string, reason: SkipReason) => string` | One line per skipped field              |
+| `statusReview`    | `string`                                        | Status while the review list is shown   |
+| `statusUndone`    | `string`                                        | Status after undo                       |
+| `statusNoForm`    | `string`                                        | No form resolved                        |
+| `errorProvider`   | `(provider: string, status?: number) => string` | Provider failure                        |
+| `errorParse`      | `string`                                        | Unreadable model answer                 |
+| `errorUnknown`    | `string`                                        | Anything else                           |
+
+## Styling
+
+### Custom properties
+
+Set them on the element or on any ancestor.
+
+| Property          | Default                                             | Used for                                              |
+| ----------------- | --------------------------------------------------- | ----------------------------------------------------- |
+| `--aff-accent`    | `#1d4ed8`                                           | Fill and Apply buttons, focus ring, active microphone |
+| `--aff-accent-fg` | `#fff`                                              | Text on the accent buttons                            |
+| `--aff-border`    | `color-mix(in srgb, currentColor 22%, transparent)` | Panel, text box and button borders                    |
+| `--aff-muted`     | `color-mix(in srgb, currentColor 65%, transparent)` | Status line and review values                         |
+| `--aff-radius`    | `8px`                                               | Corner radius everywhere                              |
+| `--aff-gap`       | `8px`                                               | Gap between rows and buttons                          |
+| `--aff-font`      | `inherit`                                           | Panel font shorthand                                  |
+
+```css
+ai-form-fill {
+  --aff-accent: #111;
+  --aff-radius: 4px;
+}
+```
+
+### Parts
+
+Every node is exposed, so `::part()` can restyle it.
+
+| Part                                                         | Node                                |
+| ------------------------------------------------------------ | ----------------------------------- |
+| `panel`                                                      | The outer box, carries `data-state` |
+| `label`, `textarea`, `actions`, `status`, `summary`          | The main regions                    |
+| `mic`, `mic-label`                                           | Microphone button and its text      |
+| `submit`, `cancel`, `undo`, `apply`, `discard`               | The buttons                         |
+| `summary-row`                                                | One skipped-field line              |
+| `review-row`, `review-check`, `review-label`, `review-value` | One review row and its three parts  |
+
+```css
+ai-form-fill::part(submit) {
+  text-transform: uppercase;
+}
+ai-form-fill::part(panel) {
+  border-style: dashed;
+}
+```
+
+### Highlighting the filled fields
+
+Every field the element writes carries `data-aff-filled` for 1.5 seconds. The attribute is on your
+own inputs, not in the shadow root, so one plain rule is enough:
+
+```css
+[data-aff-filled] {
+  outline: 2px solid #3b82f6;
+  transition: outline-color 0.4s;
+}
+```
+
+## Accessibility
+
+- The status line is a live region (`role="status"`, `aria-live="polite"`), so a screen reader
+  announces "Filling the form", the result and the missing required fields. On a failure the role
+  switches to `alert`.
+- The panel gets `aria-busy="true"` while the request is in flight.
+- The microphone button is a toggle with `aria-pressed`, and its tooltip changes with the state.
+- Keyboard: `Ctrl` + `Enter` (or `Cmd` + `Enter`) runs a fill from the text box, `Escape` stops a
+  running dictation and drops what it heard.
+- The focus ring uses `--aff-accent` through `:focus-visible`, so it follows your accent colour.
+- The text box has a real `<label>`, so set `label` to something your users understand.
diff --git a/docs/wiki/Voice-Input.md b/docs/wiki/Voice-Input.md
new file mode 100644
index 0000000..976a5ca
--- /dev/null
+++ b/docs/wiki/Voice-Input.md
@@ -0,0 +1,155 @@
+# Voice Input
+
+This page covers dictation: the `createDictation` API, the one-gesture flow, browser support, and
+what to tell your users about privacy.
+
+Speech is a separate entry point (`ai-form-fill/voice`), so importing the core pulls in no speech
+code. It wraps the browser's Web Speech API and produces text. What happens with that text is up to
+you.
+
+## The API
+
+```typescript
+import { createDictation, isDictationSupported } from 'ai-form-fill/voice';
+
+if (isDictationSupported()) {
+  const dictation = createDictation({
+    onText: (text) => (textarea.value = text), // full transcript so far
+    onEnd: (text) => controller.fill(text), // once, after stop or silence
+  });
+  micButton.addEventListener('click', () =>
+    dictation.listening ? dictation.stop() : dictation.start(),
+  );
+}
+```
+
+`isDictationSupported()` is a function, not a constant, so it is safe to import during server-side
+rendering. `createDictation` throws when the browser has no Web Speech API, so guard with it.
+
+### Options
+
+| Option      | Type                                                  | Default                                  | Meaning                                                      |
+| ----------- | ----------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------ |
+| `lang`      | `string`                                              | `<html lang>`, then `navigator.language` | BCP 47 tag for the recogniser, for example `de-DE`           |
+| `interim`   | `boolean`                                             | `true`                                   | Report text while the engine is still revising it            |
+| `silenceMs` | `number`                                              | `1500`                                   | Auto-stop after this long without a new result; `0` disables |
+| `onText`    | `(text: string, isFinal: boolean) => void`            | —                                        | Every result, with the full transcript so far                |
+| `onEnd`     | `(finalText: string) => void`                         | —                                        | Once per session, with the trimmed transcript                |
+| `onError`   | `(error: { error: string; message: string }) => void` | —                                        | Every recognition error                                      |
+
+### The returned object
+
+| Member      | Type         | Notes                                      |
+| ----------- | ------------ | ------------------------------------------ |
+| `start()`   | `() => void` | Starts a session and clears the transcript |
+| `stop()`    | `() => void` | Ends the session, which makes `onEnd` fire |
+| `listening` | `boolean`    | Read-only, true while a session runs       |
+
+One controller can run many sessions. Each `start()` begins with an empty transcript and ends with
+exactly one `onEnd` call.
+
+## The one-gesture flow
+
+`onText` reports the full transcript on every result, not the delta, so a text box only has to be
+assigned. The silence window restarts with every result, so the user presses once, speaks, and stops
+speaking: after 1.5 seconds of silence the session ends and `onEnd` fires. That is the whole
+interaction, with no second click.
+
+Set `silenceMs: 0` when you want an explicit stop button instead, and call `stop()` yourself.
+
+```typescript
+const dictation = createDictation({
+  lang: 'de-DE',
+  silenceMs: 2500,
+  onText: (text, isFinal) => {
+    textarea.value = text;
+    textarea.dataset.interim = String(!isFinal);
+  },
+  onEnd: (text) => {
+    if (text) void controller.fill(text);
+  },
+});
+```
+
+`isFinal` is `true` when nothing is pending, so you can render interim words in a lighter colour and
+commit them when it flips.
+
+## Browser support
+
+| Browser                      | Web Speech API | Notes                                                       |
+| ---------------------------- | -------------- | ----------------------------------------------------------- |
+| Chrome, Edge, other Chromium | Yes            | Audio is sent to a Google speech service                    |
+| Safari (macOS, iOS)          | Yes            | Prefixed as `webkitSpeechRecognition`, uses Apple's service |
+| Firefox                      | No             | `isDictationSupported()` returns `false`                    |
+
+Always keep typing available. The `<ai-form-fill>` element hides the microphone by itself when the
+API is missing, so a Firefox user only sees the text box.
+
+## Privacy
+
+The recognition does not run in the library and, in the browsers above, does not run on the device
+either: the audio goes to the browser vendor's speech service. That is a data flow your privacy
+notice has to mention, next to the provider the text is sent to afterwards. See
+[Security and Privacy](Security-and-Privacy).
+
+The user is asked for microphone permission by the browser, per origin. The library never touches
+`getUserMedia` itself.
+
+## Errors and permissions
+
+Errors are reported through `onError`, never thrown. The engine ends the session afterwards, and
+`onEnd` still fires. The `error` field is a Web Speech error code:
+
+| Code                  | Cause                                       | What to show                                           |
+| --------------------- | ------------------------------------------- | ------------------------------------------------------ |
+| `not-allowed`         | Microphone permission denied or blocked     | Ask the user to allow the microphone, and offer typing |
+| `service-not-allowed` | The speech service was refused              | Same as above                                          |
+| `no-speech`           | Nothing was heard                           | "I did not hear anything, try again"                   |
+| `audio-capture`       | No microphone available                     | Point at the device settings                           |
+| `network`             | The speech service was unreachable          | Offer typing                                           |
+| `aborted`             | `stop()` or a page change ended the session | Nothing, this is normal                                |
+
+```typescript
+const dictation = createDictation({
+  onError: ({ error }) => {
+    hint.textContent =
+      error === 'not-allowed'
+        ? 'Microphone access is blocked. Type the text instead.'
+        : 'Dictation failed. Type the text instead.';
+  },
+  onEnd: (text) => text && controller.fill(text),
+});
+```
+
+## With the controller
+
+Dictation produces text, the controller consumes it:
+
+```typescript
+import { createFormFill } from 'ai-form-fill';
+import { createDictation, isDictationSupported } from 'ai-form-fill/voice';
+
+const controller = createFormFill({ form: '#contact' });
+const dictation = isDictationSupported()
+  ? createDictation({
+      onText: (text) => (document.querySelector('#notes').value = text),
+      onEnd: (text) => text && controller.fill(text),
+    })
+  : null;
+
+document.querySelector('#mic').hidden = dictation === null;
+document.querySelector('#mic').addEventListener('click', () => dictation?.start());
+```
+
+## With the element
+
+The element does all of the above for you. Add `voice`, and `lang` when the page language is not the
+speaking language:
+
+```html
+<ai-form-fill for="#contact" voice lang="de-DE"></ai-form-fill>
+```
+
+The microphone only appears when the browser supports dictation. Press it, speak, stop speaking: the
+panel writes the transcript into its text box and starts the fill on its own. `Escape` cancels a
+running dictation and throws away what it heard.
diff --git a/docs/wiki/_Footer.md b/docs/wiki/_Footer.md
new file mode 100644
index 0000000..d3781ec
--- /dev/null
+++ b/docs/wiki/_Footer.md
@@ -0,0 +1,3 @@
+ai-form-fill, MIT. These docs live in `docs/wiki/` in the
+[repository](https://github.com/JDeffner/ai-form-fill/tree/main/docs/wiki); edit them there and open
+a pull request.
diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md
new file mode 100644
index 0000000..12e2020
--- /dev/null
+++ b/docs/wiki/_Sidebar.md
@@ -0,0 +1,33 @@
+### [ai-form-fill](Home)
+
+**Use it**
+
+- [Getting Started](Getting-Started)
+- [Installation and Builds](Installation-and-Builds)
+- [UI Component](UI-Component)
+- [Voice Input](Voice-Input)
+- [Framework Guides](Framework-Guides)
+
+**Configure**
+
+- [Providers](Providers)
+- [Running a Proxy](Running-a-Proxy)
+- [Form Fields and Hints](Form-Fields-and-Hints)
+- [Events, Results and Review](Events-Results-and-Review)
+
+**Understand**
+
+- [Architecture](Architecture)
+- [Security and Privacy](Security-and-Privacy)
+- [Errors and Troubleshooting](Errors-and-Troubleshooting)
+
+**Contribute**
+
+- [Contributing](Contributing)
+- [Releasing](Releasing)
+- [FAQ and Non-Goals](FAQ-and-Non-Goals)
+
+---
+
+- [Live demo](https://jdeffner.github.io/ai-form-fill/)
+- [API reference](https://jdeffner.github.io/ai-form-fill/api/)
diff --git a/eslint.config.js b/eslint.config.js
index c3a3fdd..2b5049e 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -5,7 +5,7 @@ import globals from 'globals';
 
 export default tseslint.config(
   {
-    ignores: ['dist/**', 'coverage/**', 'node_modules/**'],
+    ignores: ['dist/**', 'site/**', 'coverage/**', 'node_modules/**'],
   },
   {
     files: ['**/*.js'],
diff --git a/package.json b/package.json
index e1a48f8..f5d9594 100644
--- a/package.json
+++ b/package.json
@@ -73,6 +73,7 @@
     "dev": "vite",
     "build": "tsc --noEmit && vite build && vite build -c vite.browser.config.js",
     "build:site": "vite build -c vite.site.config.js && node scripts/build-site.mjs && typedoc",
+    "wiki:sync": "node scripts/sync-wiki.mjs",
     "release:build": "pnpm build",
     "preview": "vite preview",
     "typecheck": "tsc --noEmit",
diff --git a/scripts/sync-wiki.mjs b/scripts/sync-wiki.mjs
new file mode 100644
index 0000000..9d6dfba
--- /dev/null
+++ b/scripts/sync-wiki.mjs
@@ -0,0 +1,66 @@
+/**
+ * Push `docs/wiki/` to the GitHub wiki.
+ *
+ * The wiki pages are authored in this repository so they go through review like
+ * any other change. This script clones the wiki repository into a temporary
+ * directory, replaces its Markdown files with the ones in `docs/wiki/`, and
+ * pushes. It does nothing when the content is already identical.
+ *
+ * Run it after a pull request that touches `docs/wiki/` is merged:
+ *
+ *   pnpm wiki:sync
+ *
+ * Needs push access to the wiki repository, which is the same access as the
+ * code repository.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { cpSync, mkdtempSync, readdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const WIKI_REMOTE = 'https://github.com/JDeffner/ai-form-fill.wiki.git';
+const repoRoot = fileURLToPath(new URL('..', import.meta.url));
+const source = join(repoRoot, 'docs', 'wiki');
+
+/** Run a git command and return its trimmed stdout. */
+function git(cwd, ...args) {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'inherit'],
+  }).trim();
+}
+
+const pages = readdirSync(source).filter((name) => name.endsWith('.md'));
+if (pages.length === 0) {
+  console.error(`No Markdown files in ${source}.`);
+  process.exit(1);
+}
+
+const sha = git(repoRoot, 'rev-parse', '--short', 'HEAD');
+const clone = mkdtempSync(join(tmpdir(), 'aff-wiki-'));
+
+try {
+  console.log(`Cloning ${WIKI_REMOTE}`);
+  git(repoRoot, 'clone', '--depth', '1', WIKI_REMOTE, clone);
+
+  for (const name of readdirSync(clone).filter((name) => name.endsWith('.md'))) {
+    rmSync(join(clone, name));
+  }
+  for (const name of pages) {
+    cpSync(join(source, name), join(clone, name));
+  }
+
+  git(clone, 'add', '-A');
+  if (git(clone, 'status', '--porcelain') === '') {
+    console.log('The wiki is already up to date.');
+  } else {
+    git(clone, 'commit', '-m', `docs: sync wiki from ${sha}`);
+    git(clone, 'push');
+    console.log(`Pushed ${pages.length} page(s) from ${sha}.`);
+  }
+} finally {
+  rmSync(clone, { recursive: true, force: true });
+}