@toa.io/extensions.configuration 1.0.0-alpha.273 → 1.0.0-alpha.274

package/ui/.agents/skills/antcn/references/geo.md

@@ -0,0 +1,27 @@
+# geo
+
+Consent-zone lookup. Resolves whether the current visitor sits in a prior-consent jurisdiction (where a consent banner must be shown before loading trackers) by querying your API through the `@/net` origin. Headless — service only, no UI.
+
+## Notes
+
+- **Backend contract** — exposes `geo()`, which `GET`s `/geo/` on your API (resolved against `$config.origin` via `@/net`). The endpoint must answer with `{ "privacy": boolean, "country"?: string }`, where `privacy: true` means the visitor is inside a prior-consent zone. Typically your backend derives this from the request IP / edge geolocation headers.
+- **Dev override** — when running in dev, a `?privacy=0|1` query param short-circuits the backend lookup so you can force either branch locally (`?privacy=1` → in-zone, `?privacy=0` → out-of-zone). The override is dev-only and browser-only; production always defers to the API.
+- **Failure** — a network/parse failure resolves to an `Error` (not a throw); the caller decides the safe default (typically: show the banner).
+
+## Usage
+
+```ts
+import { geo } from '@/geo'
+
+const zone = await geo()
+
+if (zone instanceof Error) {
+  // lookup failed — default to the privacy-safe path (show the banner)
+} else if (zone.privacy) {
+  // prior-consent jurisdiction — collect consent before loading trackers
+}
+```
+
+## Props
+
+None — this Solution exports a single `geo()` function and the `Geo` type. It renders nothing.

package/ui/.agents/skills/antcn/references/globals.md

@@ -0,0 +1,31 @@
+# Globals
+
+Shared theme tokens, Tailwind variants, and utility classes for antcn components.
+
+## What's included
+
+| Kind | Examples |
+| --- | --- |
+| CSS variables | `--constructive`, `--constructive-foreground`, `--destructive-foreground`, `--shadow-color` → `bg-constructive`, `text-constructive-foreground`, `text-destructive-foreground`, popover shadows |
+| Custom variants | `standalone:`, `tim:` |
+| Shared layers | `@layer transitions` — `transition-morph` / `transition-spring` / `transition-instant` timing, reduced-motion guard |
+| Utility classes | `.no-scrollbar` — hide scrollbars while keeping scroll; `.selected` — accent ring for selected rows |
+| Typography | `.typeset` — document rhythm for rendered Markdown, sized relative to its container |
+
+Component-specific view-transition rules stay in each component's `<style>` block.
+
+## Typography
+
+`.typeset` is [shadcn/typeset](https://ui.shadcn.com/docs/typeset), snapshotted from <https://ui.shadcn.com/typeset.css> on 2026-08-05. It has no registry entry and no npm package — it ships as a file plus a web builder, so it is vendored here as `typeset.css` and refreshing it is a diff against a fresh download.
+
+The file ships verbatim: `globals` carries it as a `registry:file` targeting `src/lib/typeset.css`, and its `css` carries the matching `@import '$lib/typeset.css'` key, which the CLI merges into your stylesheet — so after install you own a readable `typeset.css` and it is already wired. Edit it like any other file in your project.
+
+The deviation, one rule: upstream nests lists with a bare `:where(ul ul)`, so a structural `<ul>` _outside_ the typeset container counts as a nesting level and Markdown lists render `circle`. It is scoped to `.typeset ul ul` (and `.typeset ul ul ul`) instead. This is generic — any layout that puts a Markdown container inside a list hits it.
+
+Put the class on the element that roots a whole document, not on each Markdown fragment, so headings and prose share one typographic root. Elements inside it that are structure rather than prose opt out with explicit utilities — note that Tailwind v4 implements `space-y-*` as `margin-block-end`, which collides with typeset's list spacing, so spacing between structural items wants an explicit margin instead.
+
+## After install
+
+Installing or re-installing globals merges its `css` and `cssVars` into your project CSS (usually `src/app.css`). Simple tokens dedupe reliably; **complex selectors** — `@layer transitions`, `@custom-variant`, comma-grouped `::view-transition-*` rules — match by exact formatting. If your file is pretty-printed differently from what the CLI emits, overwrite may fail and rules get **appended as duplicates**.
+
+After each install, check your CSS and **delete duplicate blocks** (most often under `@layer transitions`). Replace the whole bloated section with one copy — don't leave stacked repeats.

package/ui/.agents/skills/antcn/references/grammatical-form.md

@@ -0,0 +1,69 @@
+# Grammatical form
+
+In some languages the wording of a message depends on the subject's grammatical gender (`{name} added` vs Russian `{name} добавил` / `добавила`). svintl turns this into a translation concern, and the app stores a per-user choice — the same way it stores a chosen locale. It is **not** part of any one Solution: the mechanics live in the svintl host, the field on the account, and the picker in the consumer's profile.
+
+## How svintl exposes it
+
+Enable gender guidance once on the host dictionary (`$lib/intl`), listing the gender tokens your strings vary by — the **last** one is treated as the neutral/fallback form:
+
+```bash
+npx intl genders he she none   # writes `genders: [he, she, none]` to context.yaml
+npx intl genders               # prints the current values
+npx intl build                 # regenerates types + dictionaries
+```
+
+`build` then emits a `Grammar` union from those tokens:
+
+```ts
+// $lib/intl
+export type Grammar = 'he' | 'she' | 'none' // = string when genders is unset
+```
+
+Gender-dependent phrases become `!js` functions whose **last** argument is the gender; the phrase's own arguments (if any) come first. A phrase with no other placeholders is just `(gender) => …`:
+
+```yaml
+# one own argument (name) + gender
+example:
+  !js
+  (name, gender) => gender === 'he' ? `${name} добавил` : gender === 'she' ? `${name} добавила` : `${name} добавил(а)`
+# no own arguments — single gender param
+status:
+  !js
+  (gender) => gender === 'she' ? 'готова' : gender === 'he' ? 'готов' : 'готов(а)'
+```
+
+A language with no gender distinction for a phrase returns a plain string, not a function.
+
+## API field
+
+The subject's gender lives on the account as `grammar?: Grammar | null` (`Grammar` imported from `$lib/intl`). antcn's `iam` Solution already carries it on `Echo`. Persist the user's choice there.
+
+## Two consumption modes
+
+- **Current user** — for "you did X" texts, feed a `grammar` store derived from the active account (`$lib/intl` can expose `grammar = derived(account, $a => $a?.grammar ?? 'none')`).
+- **Per subject** — for "{name} did X" texts about *other* people, pass that account's own field explicitly: `$dict.contacts.transferred.received(name, amount, account.grammar)`. Forgetting this is the common bug — the dictionary function needs the *subject's* gender, not the viewer's.
+
+## Picker (interface pattern — not shipped by antcn)
+
+Mirror the language switcher: a small control that edits `account.grammar` and reports the choice for persistence, exactly like the `locale` Solution's `Languages` / `Language` report a `Locale` via `onselect`.
+
+```svelte
+<script lang="ts">
+  import type { Grammar } from '$lib/intl'
+  import { me } from '@/accounts'
+
+  // value seeded from account.grammar; toggle-group over the gender tokens
+  function persist(grammar: Grammar) {
+    void me.update({ grammar })
+  }
+</script>
+```
+
+Suggested interface:
+
+| Prop       | Type                          | Notes                                              |
+| ---------- | ----------------------------- | -------------------------------------------------- |
+| `value`    | `Grammar \| ''`               | Current account gender; `''` for unset             |
+| `onselect` | `(grammar: Grammar) => void`  | Fires after the choice changes; persist it         |
+
+A toggle-group of the gender tokens (e.g. `he` / `she` / `none` with icons) is the proven shape.

package/ui/.agents/skills/antcn/references/hints.md

@@ -0,0 +1,44 @@
+## hint
+
+Per-account dismissable onboarding hints — acknowledge a hint permanently, or snooze it until a timestamp. State is persisted under the signed-in `@/iam` account, so each user sees each hint once (or once per snooze window).
+
+`Hints` is intentionally an **empty interface extending `Record<string, Hint | undefined>`**. Declare your hint keys by extending it; `acknowledge` / `later` / `unfamiliar` then narrow to those keys.
+
+## Notes
+
+- **Requires `@/iam`.** The hint store binds to `@/iam`'s `account` and clears on logout — no account, no persisted hints. Pulled automatically via `local:iam`.
+- **No UI ships.** This Solution is service-only; render the prompt with whatever surface you like (a `Card`, banner, dialog). `unfamiliar(key)` gates rendering; `acknowledge` / `later` dismiss it.
+- **Extending `Hints` is how you wire keys.** Without an `interface Hints` augmentation in your project, every key is valid but untyped. The `transmission` Solution does this for `transmission_permission`.
+
+## Usage
+
+Declare a hint key, then gate a prompt on `unfamiliar`:
+
+```ts
+// src/@/your-feature/svc/hints.ts
+import type { Hint } from '@/hints'
+
+declare module '@/hints' {
+  interface Hints {
+    welcome?: Hint
+  }
+}
+```
+
+```svelte
+<script lang="ts">
+  import { unfamiliar, acknowledge, later } from '@/hints'
+
+  const day = 24 * 60 * 60 * 1000
+</script>
+
+{#if unfamiliar('welcome')}
+  <Card>
+    <p>Welcome aboard.</p>
+    <Button onclick={() => later('welcome', 7 * day)}>Later</Button>
+    <Button onclick={() => acknowledge('welcome')}>Got it</Button>
+  </Card>
+{/if}
+```
+
+`unfamiliar(key)` returns `true` when there is no record for `key` **or** the record is a snooze (`value: false`) whose `expiration` has passed. `acknowledge(key)` writes `{ value: true }` (hides forever). `later(key, delay)` writes `{ value: false, expiration: Date.now() + delay }` (hides until then).

package/ui/.agents/skills/antcn/references/hold.md

@@ -0,0 +1,34 @@
+# Hold
+
+`Alt`+click fires `onclick` immediately (power users / tests). Right-click is swallowed.
+
+Use a unique `name` per instance when several holds share a page (CSS anchor). Set `portal={false}` inside transformed ancestors — Safari CSS anchor positioning quirk.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { Hold } from '$com/hold'
+</script>
+
+<Hold label="hold to log out" onclick={() => signOut()}>
+  Log out
+</Hold>
+```
+
+## Props
+
+| Prop       | Type                                              | Default   | Notes                                                                        |
+| ---------- | ------------------------------------------------- | --------- | ---------------------------------------------------------------------------- |
+| `name`     | `string`                                          | `'hold'`  | CSS anchor name. Use a unique value per instance if multiple on one page.    |
+| `duration` | `number` (ms)                                     | `800`     | How long the user must hold before `onclick` fires.                          |
+| `label`    | `string`                                          | —         | Hint text shown in the tooltip while held. Use `message` snippet for richer markup. |
+| `message`  | `Snippet`                                         | —         | Overrides `label` for non-string content.                                    |
+| `position` | `'center' \| 'left' \| 'right' \| 'top' \| 'bottom'` | `'left'`  | Tooltip side (CSS anchor `position-area` first axis).                        |
+| `align`    | `'center' \| 'left' \| 'right' \| 'top' \| 'bottom'` | `'center'` | Tooltip alignment along the chosen side.                                     |
+| `portal`   | `boolean`                                         | `true`    | Teleport tooltip to `body`. Set `false` inside transformed ancestors (Safari anchor quirk). |
+| `onpress`  | `() => void`                                      | —         | Fires when the hold starts.                                                  |
+| `onclick`  | `() => void`                                      | —         | Fires after the full duration is held, or immediately on `Alt`+click.        |
+| `variant`  | `ButtonVariant`                                   | `'ghost'` | Forwarded to shadcn `Button`.                                                |
+
+All other props pass through to the underlying `Button`.

package/ui/.agents/skills/antcn/references/iam.md

@@ -0,0 +1,117 @@
+# iam
+
+Identity & access — a complete authentication surface plus the services behind it. UI covers passkey, password, one-time-passcode, and OIDC (Google/Apple) sign-in/sign-up, an `Authenticated` gate, an `Authorized` conditional-render guard, and session refresh on expiry. Services expose the `account` store, `logout`, `update`, `named`, and the `basic` / `otp` / `passkeys` / `oidc` flows.
+
+## `$config`
+
+| Field              | Type                | Notes                                                |
+| ------------------ | ------------------- | ---------------------------------------------------- |
+| `navigation.entry` | `{ entry: string }` | Route to land on after a successful OIDC redirect.   |
+
+Network access (`origin`, `sleep`) flows through `@/net`.
+
+## Environment
+
+OIDC client IDs come from `$env/dynamic/public`. Omit or leave empty to hide the provider button:
+
+| Var                       | Notes                                              |
+| ------------------------- | -------------------------------------------------- |
+| `PUBLIC_GOOGLE_CLIENT_ID` | Google OIDC client ID. Empty hides the Google button. |
+| `PUBLIC_APPLE_CLIENT_ID`  | Apple OIDC client ID. Empty hides the Apple button.  |
+
+## Notes
+
+- **OIDC is opt-in.** Missing/empty `PUBLIC_*_CLIENT_ID` disables the provider buttons — no wiring crashes if you only want password/passkey/OTP.
+- **Account shape.** Components accept an `AccountLike` (`Pick` of the account fields they render); the `account` store holds the authenticated `Echo`. Extend `Echo` (`svc/net/Echo.ts`) if your API returns extra profile fields.
+- **`Credentials` manager.** Renders the signed-in account's security surface: a passkey manager (register / list / hold-to-delete — a thin layer over `@/passkeys`), inert provider rows (email/Google/Apple; the `Connect` CTA carries no behaviour yet), and a "sign in on another device" action whose QR encodes the current session `challenge`. It gates itself on the `account` store, so just mount it anywhere inside your authenticated area.
+- **Session transfer is two-sided.** The QR is the *sending* device; the *receiving* device adopts the session by reading the fragment `challenge` on load. `rc()` already does this on init (shared `consume()`), so transfer completes as long as `rc()` runs once at app start.
+
+## Usage
+
+Gate an app behind authentication (`Authenticated` shows the auth surface until signed in, then renders its children):
+
+```svelte
+<script lang="ts">
+  import { Authenticated } from '@/iam/ui'
+</script>
+
+<Authenticated>
+  <Dashboard />
+</Authenticated>
+```
+
+Conditionally render UI with `Authorized`. It renders its children only when **at least one** passed check passes: `dev` (matches `$app/environment` `dev`), `beta` (host starts with `beta.`), `debug` (`dev` or `beta`), or `role` (scoped match against the account's `roles` — `app` matches `app`, `app:codes`, and deeper; `app:codes` matches only `app:codes` and deeper). No matching check → nothing renders.
+
+```svelte
+<script lang="ts">
+  import { Authorized } from '@/iam/ui'
+</script>
+
+<Authorized role="admin">
+  <AdminPanel />
+</Authorized>
+
+<Authorized dev>
+  <DebugToolbar />
+</Authorized>
+```
+
+Read the session reactively and sign out. `account` is a `svas` store of the authenticated `Echo` (`null` when signed out):
+
+```svelte
+<script lang="ts">
+  import { account, logout } from '@/iam'
+  import { goto } from '$app/navigation'
+
+  async function getout() {
+    logout()
+    void goto('/')
+  }
+</script>
+
+{#if $account}
+  <p>Signed in as {$account.name}</p>
+  <button onclick={getout}>Log out</button>
+{/if}
+```
+
+Block an action until the account has a display name — `named()` resolves once `account.name` is set (prompting through the auth surface if missing), so guarded flows can `await` it:
+
+```ts
+import { having } from 'svas'
+import { account, named } from '@/iam'
+
+async function onaccept() {
+  await having(account) // wait for a session
+  await named() // …and a chosen name
+  await invitations.accept(id)
+}
+```
+
+Patch the local session optimistically (e.g. after a profile edit) — `update` merges a partial into the `account` store without a round-trip:
+
+```ts
+import { update } from '@/iam'
+
+update({ name: 'Ada Lovelace' })
+```
+
+Gate non-UI logic on the `authenticated` derived boolean (true only when a challenge + account exist and nothing is processing):
+
+```ts
+import { authenticated } from '@/iam'
+
+authenticated.subscribe((ok) => ok && sync())
+```
+
+Render the account's credentials manager inside an authenticated area (passkeys, connected providers, device transfer). It only renders once a session exists, so no extra gating is needed:
+
+```svelte
+<script lang="ts">
+  import { Credentials } from '@/iam/ui'
+</script>
+
+<Credentials />
+```
+
+`Credentials` takes a single optional `class` (`ClassValue`) — everything else is driven by the `account` and `@/passkeys` stores.

package/ui/.agents/skills/antcn/references/input-form.md

@@ -0,0 +1,34 @@
+# InputForm
+
+Centered text field in a form that submits on blur when the value changed, or on Enter. Empty blur resets to the initial value. `onsubmit` may return a new string to sync the field after save.
+
+## Notes
+
+Exposes an imperative `focus()` method — bind the instance (`bind:this`) and call it to move focus to the field (e.g. when revealing the form).
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { InputForm } from '$com/input-form'
+
+  let name = $state('Alex')
+</script>
+
+<InputForm
+  value={name}
+  onsubmit={async (value) => {
+    name = value
+    return value
+  }}
+/>
+```
+
+## Props
+
+| Prop       | Type                                                              | Default | Notes                                              |
+| ---------- | ----------------------------------------------------------------- | ------- | -------------------------------------------------- |
+| `value`       | `string`                                                          | —             | Initial/current value; resets to this when cleared. |
+| `class`       | `ClassValue`                                                      | —             | Extra classes on the shadcn `Input`.               |
+| `placeholder` | `string`                                                          | `'Enter name'`| Placeholder text when the field is empty.          |
+| `onsubmit`    | `(value: string) => Promise<string \| undefined> \| string \| undefined` | —       | Called on blur (if changed) or form submit. Return a string to update the field. |

package/ui/.agents/skills/antcn/references/locale.md

@@ -0,0 +1,66 @@
+# locale
+
+Locale switching over the host svintl store. Two interchangeable switchers — `Languages` (snap-scroller) and `Language` (`Select` dropdown) — both set the active locale and fire `onselect` for persistence.
+
+## Languages
+
+Horizontal snap-scroller of native language names.
+
+### Usage
+
+```svelte
+<script lang="ts">
+  import { Languages } from '@/locale/ui'
+</script>
+
+<Languages />
+```
+
+`onselect` fires after the store updates — use it for side effects like persistence:
+
+```svelte
+<script lang="ts">
+  import { Languages } from '@/locale/ui'
+  import { me } from '@/accounts'
+  import type { Locale } from '$lib/intl'
+
+  function persist(locale: Locale) {
+    void me.update({ locale })
+  }
+</script>
+
+<Languages onselect={persist} />
+```
+
+### Props
+
+| Prop       | Type                       | Default | Notes                                                                                       |
+| ---------- | -------------------------- | ------- | ------------------------------------------------------------------------------------------- |
+| `onselect` | `(locale: Locale) => void` | —       | Fires after the host store is set. Use it to persist or track the choice.                   |
+| `infinite` | `boolean`                  | _auto_  | Forces the loop/clone scroller on or off. Defaults to on when `locales.length >= 10`.       |
+
+### Notes
+
+The active locale stays centered in the track. A long set (`>= 10`) loops endlessly; a short one renders once and centers via 50% gutters — dead-center whether it underfills or overflows. Centering is relative to the track's own width, so wrap it in a narrower box to constrain the window. `infinite` overrides the auto choice.
+
+## Language
+
+Compact `Select` for a settings row.
+
+### Usage
+
+```svelte
+<script lang="ts">
+  import { Language } from '@/locale/ui'
+  import { me } from '@/accounts'
+  import type { Locale } from '$lib/intl'
+</script>
+
+<Language onselect={(l: Locale) => me.update({ locale: l })} />
+```
+
+### Props
+
+| Prop       | Type                       | Default | Notes                                                                     |
+| ---------- | -------------------------- | ------- | ------------------------------------------------------------------------- |
+| `onselect` | `(locale: Locale) => void` | —       | Fires after the host store is set. Use it to persist or track the choice. |

package/ui/.agents/skills/antcn/references/net.md

@@ -0,0 +1,33 @@
+# net
+
+The networking foundation every other Solution builds on. Connects a single `@toa.io/origin` client to your API and re-exports it as `origin`, plus the `query` helper for building criteria query strings. Sibling Solutions import `origin` from `@/net` to declare their resources.
+
+## `$config`
+
+`net` reads two fields from your `$config` module (`import * as config from '$config'`):
+
+| Field    | Type                            | Notes                                                                       |
+| -------- | ------------------------------- | --------------------------------------------------------------------------- |
+| `origin` | `string`                        | Absolute API origin; `''` is invalid (resolved via `new URL(path, origin)`). |
+| `sleep`  | `[number, number] \| undefined` | Dev-only artificial latency range; `undefined` disables it.                 |
+
+## Usage
+
+Declare a resource against the shared client and call it:
+
+```ts
+import { origin, query, type RequestOptions } from '@/net'
+
+const echo = origin.resource<{ message: string }>('/accounts/echo/')
+
+async function ping(): Promise<{ message: string } | Error> {
+  return echo.json({ method: 'GET' } satisfies RequestOptions)
+}
+```
+
+`query` turns a `URLSearchParams` into a criteria string; `omit`/`limit`/`search` stay as plain pairs, everything else becomes `criteria=key==value;…`:
+
+```ts
+const params = new URLSearchParams({ status: 'active', limit: '20' })
+query(params) // '?criteria=status==active&limit=20'
+```

package/ui/.agents/skills/antcn/references/panel.md

@@ -0,0 +1,44 @@
+# Panel
+
+List row built on shadcn `Button`: main content in `left`/`right`/`icon` snippets, optional swipe-reveal `actions` on the trailing edge. Set `h` (e.g. `h-14`) when using `collapsed` — height animates to zero. Pass `selected` for accent ring styling (from `globals`).
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { Panel, type Action } from '$com/panel'
+
+  const actions: Action[] = [{ id: 'delete', onclick: () => remove() }]
+</script>
+
+<Panel h="h-14" class="bg-card border border-border" href="/items/1">
+  {#snippet left()}
+    <span class="font-medium">Item title</span>
+  {/snippet}
+  {#snippet right()}
+    <span class="text-muted-foreground">$12</span>
+  {/snippet}
+  {#snippet action(id)}
+    {#if id === 'delete'}Delete{/if}
+  {/snippet}
+  {actions}
+</Panel>
+```
+
+## Props
+
+| Prop        | Type                         | Default     | Notes                                                                 |
+| ----------- | ---------------------------- | ----------- | --------------------------------------------------------------------- |
+| `left`      | `Snippet`                    | —           | Main label/content (required).                                        |
+| `right`     | `Snippet`                    | —           | Trailing slot (balance, badge, etc.).                                 |
+| `icon`      | `Snippet`                    | —           | Leading icon/avatar before `left`.                                    |
+| `collapsed` | `boolean`                    | `false`     | Animate height to zero. Requires `h`.                                 |
+| `selected`  | `boolean`                    | `false`     | Applies `.selected` ring styling.                                     |
+| `h`         | `string`                     | —           | Tailwind height class on the row and collapse wrapper.                |
+| `actions`   | `Action[]`                   | —           | Swipe-reveal toolbar items. Pair with `action` snippet.               |
+| `action`    | `Snippet<[string]>`          | —           | Renders one action by `id`. Required when `actions` is set.           |
+| `variant`   | `ButtonVariant`              | `'outline'` | Forwarded to shadcn `Button`.                                         |
+
+`Action`: `{ id, class?: ClassValue, href?, onclick? }` — tapping an action scrolls the row back; `href` navigates via SvelteKit `goto`.
+
+All other props pass through to the underlying `Button` (`href`, `onclick`, `class`, etc.).

package/ui/.agents/skills/antcn/references/passkeys.md

@@ -0,0 +1,27 @@
+# passkeys
+
+WebAuthn credential management — registers, lists, and removes passkeys for the signed-in account against your `/identity/passkeys` API. Wraps the browser `navigator.credentials` ceremony (challenge → `create`/`get` → attestation) so callers work with plain async operations that return values or `Error`.
+
+## Notes
+
+- **Requires `@/iam`.** The `passkeys` store keys credentials by the current `@/iam` `account`; `get`/`remove`/`store` all read it. No signed-in account → empty store. `iam` is **not** pulled automatically (that would form an install cycle — `iam` already depends on `passkeys`), so install it yourself: `npx shadcn-svelte add http://cn.ants.dev/r/iam.json`. Installing `iam` brings `passkeys` along, so most consumers never add `passkeys` directly.
+- **Feature detection.** `supported` is a boolean (`window.PublicKeyCredential !== undefined`, `true` on the server). Gate registration UI on it — the ceremony rejects on unsupported browsers.
+- **`ui/aaguid.json`** ships the FIDO AAGUID → authenticator-metadata map (name + light/dark icon, base64 SVG). Look up `aaguid[credential.aaguid]` to label a passkey by its authenticator (e.g. "Google Password Manager", "iCloud Keychain"). Optional — nothing imports it for you.
+
+## Usage
+
+```ts
+import { supported, add, request, remove, passkeys } from '@/passkeys'
+
+if (supported) {
+  const out = await add(identity, name) // full register: ceremony → POST → store
+  if (out instanceof Error) handle(out)
+}
+
+// reactive list for the current account
+passkeys.subscribe((list) => render(list))
+
+await remove(id) // revoke one
+```
+
+`request(id?)` runs the authentication (login) ceremony and returns the assertion (`RequestResponse`) for your auth flow to exchange. `create(name, identity?)` is the lower-level ceremony `add` builds on.

package/ui/.agents/skills/antcn/references/payments.md

@@ -0,0 +1,99 @@
+# payments
+
+Subscription paywall stack: a tier selector, animated benefits table, pay button, platform-mandated legal disclaimers, and a processing overlay, backed by four payment processors (App Store, Google Play, Stripe, a dev mock) behind one `Processor` interface. Ships a neutral SaaS example (Storage / Seats / Priority / API) you adapt to your product.
+
+## `$config`
+
+| Field    | Used by                                                                                   |
+| -------- | ----------------------------------------------------------------------------------------- |
+| `origin` | All three live processors resolve their backend endpoints through `@/net`'s `origin`, which reads `$config.origin`. |
+
+The App Store / Google Play processors transact through the native shell (`@/bridge`); the dev processor stands in whenever `$app/environment`'s `dev` is true and there is no native host. No other `$config` field is read.
+
+## Entitlements
+
+`tier` is the only entitlement the shipped UI reads. Everything else in `Entitlements` is a neutral example you replace with your product's metered (`number`) and flag (`boolean`) entitlements — edit the interface in `svc/entitlements.ts`:
+
+```ts
+export interface Entitlements {
+  tier: Tier
+  seats: number      // metered → gated by usage(account, 'seats') >= seats
+  storage: number    // metered
+  priority: boolean  // flag → gated by the boolean itself
+}
+```
+
+`cant(account, key?)` gates generically off the value type — no per-key `switch`:
+
+- no `key` → `true` unless the account has unexpired premium.
+- `boolean` entitlement → `true` when the flag is off.
+- `number` entitlement → `true` when summed usage (`account.usage`) has reached the limit.
+- anything else (e.g. the `tier` string) → never gated.
+
+`usages()` (the `Entitlements` UI) derives one usage bar per **numeric** entitlement automatically, so adding/removing a metered key needs no UI change. When you rename a key, add a matching `used.<key>` and `benefits.<key>` entry to the intl mount.
+
+The account shape is `AccountLike` (`id`, optional `premium`, `processor`, `interval`, `entitlements`, `usage`) — a structural subset of your identity account; pass your `@/iam` account (or any object satisfying it) to `cant`/`usages`/the UI. `interval` is the account's current billing period as an ISO-8601 duration (`P1M`/`P1Y`); the paywall reads it to preselect the matching interval tab.
+
+## Tiers
+
+The upgrade ladder is `tiers = ['basic', 'premium', 'expert']` in `svc/tier.ts` (`rank()` orders upgrades off it). Override it by editing that array in place — there is no config hook. Keep the `tier` values, the `Entitlements.tier` type, the `groups`/`plans` intl keys, and your store product groups in sync with it.
+
+## Notes
+
+- **Products come from the store, not this Solution.** Each processor fetches its own catalog: App Store / Google Play via the native bridge over a fixed set of product IDs (`<tier>_<month|year>`, edit the `IDS` array per processor), Stripe via `GET /stripe/checkout/products`. The dev processor serves the static `svc/processors/dev/products.ts` list so the paywall renders with no backend. Align your store product IDs / Stripe price `metadata.tier` with your `tiers`.
+- **Backend endpoints.** Live processors call, under `$config.origin`: `POST/PATCH /appstore/transactions/{id}`, `POST /googleplay/transactions/{id}`, `GET /stripe/checkout/products`, `POST /stripe/checkout/{id}` (+ `/{id}/portal`), `POST /stripe/transactions/{id}`. You implement these.
+- **Stripe return.** Stripe checkout redirects back to `#stripe={CHECKOUT_SESSION_ID}`; `rc()` reads that one-shot hash through `@/fragments` and commits the transaction behind the processing overlay. Call `rc()` once on app start.
+- **Google Play package id.** `svc/processors/googleplay/processor.ts` builds the manage-subscription URL from a placeholder `com.example.twa` — replace it with your Trusted Web Activity package id (the same one you set in `@/bridge`).
+- **Analytics.** The processors emit `checkout` / `purchase` events through `@/analytics`; `Payguard` emits `paywall`. `analytics.d.ts` augments the analytics `Events` interface with the `paywall` / `checkout` shapes.
+- **Legal copy & links.** The disclaimers are neutral, store-compliant defaults; `Legal.svelte` links to `/terms/` and `/privacy/` — point them at your pages. Ships its own svintl mount in the registry's four locales; after install reconcile it: `npx intl import payments src/@/payments/ui/intl`.
+
+## Usage
+
+Commit a pending Stripe return once on app start, then drop the paywall behind anything that needs premium:
+
+```svelte
+<script lang="ts">
+  import { onMount } from 'svelte'
+  import { rc } from '@/payments/rc'
+  import { Payguard, Entitlements } from '@/payments/ui'
+  import { Button } from '$ui/button'
+  import { account } from '@/iam'
+
+  onMount(rc)
+</script>
+
+<!-- gates the action: opens the paywall when the account can't use `seats` -->
+<Payguard entitlement="seats">
+  <Button>Invite a teammate</Button>
+</Payguard>
+
+{#if $account}
+  <Entitlements account={$account} />
+{/if}
+```
+
+`<Paywall>` is the full-screen plan picker `<Payguard>` opens; mount it directly when you want a standalone pricing page.
+
+## Props
+
+### `Payguard`
+
+| Prop          | Type                   | Default | Notes                                                                       |
+| ------------- | ---------------------- | ------- | --------------------------------------------------------------------------- |
+| `children`    | `Snippet`              | —       | The gated trigger; rendered as-is when the account already has entitlement. |
+| `entitlement` | `keyof Entitlements`   | —       | When set, gates on that specific entitlement; omit to gate on premium only. |
+| `crown`       | `boolean`              | `true`  | Show the crown badge on the gated trigger.                                  |
+| `class`       | `ClassValue`           | —       | Forwarded to the trigger button.                                            |
+
+### `Paywall`
+
+| Prop         | Type         | Default | Notes                                  |
+| ------------ | ------------ | ------- | -------------------------------------- |
+| `oncomplete` | `() => void` | —       | Fired after a successful checkout or dismissal. |
+
+### `Entitlements`
+
+| Prop      | Type          | Default | Notes                                                  |
+| --------- | ------------- | ------- | ------------------------------------------------------ |
+| `account` | `AccountLike` | —       | Renders the current plan, usage bars, and manage/upgrade action. |
+| `class`   | `ClassValue`  | —       | Root class.                                            |