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

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

@@ -0,0 +1,69 @@
+# realtime
+
+Server-pushed event stream layered on `@toa.io/origin` multipart. `connect(id)` opens a long-running multipart POST to `/presence/{id}/`, parses each chunk into a typed event, and re-emits it on a `mitt` bus. `rc()` ties the connection lifecycle to `@/iam`'s `authenticated` derived: connects with the current account id on sign-in, disconnects on sign-out, reconnects automatically on errors. Exposes a `dashboard` store (`status` + last 128 events), a `time` store (server clock — updated from `origin` response `Date` headers), and the `events` emitter for domain modules to subscribe to.
+
+## Wiring
+
+Both `@/iam` and `@/realtime` install `rc()` bootstraps that must run once in the browser. Call them from the root `+layout.ts`:
+
+```ts
+import { rc as iam } from '@/iam/rc'
+import { rc as realtime } from '@/realtime/rc'
+import { browser } from '$app/environment'
+
+if (browser) {
+  iam()
+  realtime()
+}
+```
+
+## Domain events
+
+`svc/events.ts` declares `Events = Record<string, unknown> // add domain events here`. Extend it per domain so the emitter is typed end-to-end. Convention: every domain that publishes server events exposes an `Events` type from `@/<domain>/svc/net` and the host intersects them:
+
+```ts
+// src/@/realtime/svc/events.ts (edit after install)
+import type { Events as Contacts } from '@/contacts/svc/net'
+import type { Events as Notifications } from '@/notifications/svc/net'
+
+export type Events = Contacts & Notifications
+```
+
+Subscribe in any domain's store:
+
+```ts
+import { events } from '@/realtime'
+
+events.on('contact.added', (data) => { /* … */ })
+```
+
+## Notes
+
+- **Backend contract.** `/presence/{id}/` must return `multipart/mixed` per `@toa.io/origin` multipart: first part `"ACK"`, then JSON parts of shape `{ event, data }` or the literal string `"heartbeat"`, terminated by `"FIN"`. The Solution forces `credentials: 'include'` and sends `{ timezone }` in the body.
+- **Auto-reconnect.** Errors other than `AbortError` retry after 3 s. `disconnect()` (or sign-out via `rc()`) aborts the in-flight request.
+- **`time` store.** Seeded with `Date.now()` and updated on every `origin` response — handy for clock skew correction in UI relative timestamps.
+
+## Usage
+
+Read connection status and the last events for a debug panel:
+
+```svelte
+<script lang="ts">
+  import { dashboard } from '@/realtime'
+</script>
+
+<p>Status: {$dashboard.status}</p>
+<ul>
+  {#each $dashboard.events as e (e)}
+    <li>{e.label}: {JSON.stringify(e.payload)}</li>
+  {/each}
+</ul>
+```
+
+Subscribe to a typed event:
+
+```ts
+import { events } from '@/realtime'
+
+events.on('heartbeat', () => console.debug('alive'))
+```

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

@@ -0,0 +1,39 @@
+# Scrollable
+
+Horizontal snap scroller with optional infinite loop and programmatic scroll-to-index. Give each child `snap-center` or `snap-start` (and fixed width) for predictable snapping.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { Scrollable } from '$com/scrollable'
+
+  let index = $state(0)
+  const items = ['One', 'Two', 'Three']
+</script>
+
+<Scrollable scroll={index} class="gap-2">
+  {#each items as item, i (item)}
+    <button class="snap-center shrink-0 rounded-lg border px-4 py-2" onclick={() => (index = i)}>
+      {item}
+    </button>
+  {/each}
+</Scrollable>
+```
+
+## Props
+
+| Prop         | Type                     | Default   | Notes                                                                 |
+| ------------ | ------------------------ | --------- | --------------------------------------------------------------------- |
+| `children`   | `Snippet`                | —         | Scroll items. Duplicated internally when `infinite` is true.          |
+| `infinite`   | `boolean`                | `false`   | Loop by cloning children; recenters on `scrollend`.                   |
+| `align`      | `'start' \| 'center'`    | `'start'` | How `scroll` index is positioned.                                     |
+| `scroll`     | `number`                 | `0`       | Child index to scroll to. Use `-1` to skip initial scroll.            |
+| `bleed`      | `boolean`                | `false`   | Break out to full viewport width (edge-to-edge carousel).             |
+| `gutter`     | `boolean`                | `false`   | Half-track end gutters so the first/last item can sit dead-center. Pairs with `align="center"`; ignored when `infinite`. |
+| `controlled` | `boolean`                | `false`   | Hide native overflow; drive scroll externally.                        |
+| `dir`        | `'ltr' \| 'rtl'`         | —         | Direction on the outer container.                                     |
+| `class`      | `ClassValue`             | —         | Classes on the scroll track (gap, padding, etc.).                     |
+| `style`      | `string`                 | —         | Inline style on the outer container.                                  |
+| `id`         | `string`                 | —         | Id on the scroll track.                                               |
+| `onscroll`   | `(e: Event) => void`     | —         | Scroll handler on the track.                                        |

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

@@ -0,0 +1,71 @@
+# Selector
+
+Card-style option list for single- or multi-choice selection. Import as a namespace (`import * as Selector from '$com/selector'`).
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import * as Selector from '$com/selector'
+
+  let value = $state('')
+  let values = $state<string[]>([])
+</script>
+
+<Selector.Root bind:value>
+  <Selector.Option value="yearly">
+    <Selector.Title>
+      <strong>Yearly</strong>
+      129,99€ per year
+    </Selector.Title>
+    <Selector.Description>32€ monthly</Selector.Description>
+  </Selector.Option>
+  <Selector.Option value="monthly">
+    <Selector.Title>
+      <strong>Monthly</strong>
+      29,99€ per month
+    </Selector.Title>
+    <Selector.Description>Flexible, slightly pricier</Selector.Description>
+  </Selector.Option>
+</Selector.Root>
+
+<Selector.Root bind:values type="multi" position="end">
+  <Selector.Option value="notifications">
+    <Selector.Title>Notifications</Selector.Title>
+    <Selector.Description>Email and push alerts</Selector.Description>
+  </Selector.Option>
+</Selector.Root>
+```
+
+## Notes
+
+More than one `Selector.Root` on the same page with overlapping option `value`s needs a unique `id` on each root (e.g. `id="billing"` / `id="addons"`).
+
+## Props
+
+### Root
+
+| Prop       | Type                  | Default   | Notes                                              |
+| ---------- | --------------------- | --------- | -------------------------------------------------- |
+| `id`       | `string`              | `'radio'` | Prefix for each option’s control/label id.         |
+| `type`     | `'single' \| 'multi'` | `'single'`| Single uses radio group; multi uses checkboxes.    |
+| `value`    | `string`              | `''`      | Bindable selection for `type="single"`.            |
+| `values`   | `string[]`            | `[]`      | Bindable selection for `type="multi"`.             |
+| `position` | `'start' \| 'end'`    | `'start'` | Indicator column: leading media or trailing actions. |
+| `variant`  | `ItemVariant`         | `'outline'` | Forwarded to each `Option` row.                  |
+| `size`     | `ItemSize`            | —         | Forwarded to each `Option` row.                    |
+| `class`    | `ClassValue`              | —         | Wrapper classes (`single` mode radio group only).  |
+| `children` | `Snippet`             | —         | `Option` slots.                                    |
+
+### Option
+
+| Prop       | Type      | Default | Notes                                      |
+| ---------- | --------- | ------- | ------------------------------------------ |
+| `value`    | `string`  | —       | Option id stored in `value` / `values`.    |
+| `id`       | `string`  | `{rootId}-{value}` | Override control/label id for this row. |
+| `class`    | `ClassValue`  | —       | Row classes.                               |
+| `children` | `Snippet` | —       | `Title` and `Description` slots.           |
+
+### Title / Description
+
+Pass through shadcn `Item` title and description props (`class`, etc.).

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

@@ -0,0 +1,36 @@
+# Shake
+
+## Notes
+
+Use for obvious failures on small forms where error copy adds little value — e.g. a wrong password is already clear from context. Prefer a real error message when the user needs to know *what* went wrong.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { Shake } from '$com/shake'
+
+  let shake: { shake: () => Promise<void> } | undefined = $state()
+</script>
+
+<Shake bind:this={shake} class="w-full">
+  <input type="password" />
+</Shake>
+
+<button onclick={() => shake?.shake()}>Retry</button>
+```
+
+## Props
+
+| Prop       | Type         | Default | Notes                          |
+| ---------- | ------------ | ------- | ------------------------------ |
+| `children` | `Snippet`    | —       | Content that shakes.           |
+| `class`    | `ClassValue` | —       | Classes on the wrapper `div`.  |
+
+## Instance methods
+
+Bind with `bind:this` to trigger the animation:
+
+| Method     | Notes                                      |
+| ---------- | ------------------------------------------ |
+| `shake()`  | Plays the shake; resolves when it finishes. |

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

@@ -0,0 +1,28 @@
+# Share
+
+Invokes the Web Share API when `navigator.share` exists; otherwise renders `Clipboard` with the share URL so desktop users can still copy the link.
+
+`data` may be a `ShareData` object or an async retriever (e.g. fetch an invite URL first). Returns early when the retriever resolves to `null`.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { Share } from '$com/share'
+
+  const data = { title: 'Join me', url: 'https://example.com/join/abc' }
+</script>
+
+<Share {data} label="Share invite" variant="outline" />
+```
+
+## Props
+
+| Prop      | Type                                      | Default | Notes                                                        |
+| --------- | ----------------------------------------- | ------- | ------------------------------------------------------------ |
+| `data`    | `ShareData \| () => Promise<ShareData \| null>` | —       | Payload for `navigator.share`. Retriever may return `null`.   |
+| `label`   | `string`                                  | —       | Button label when no `children` snippet.                     |
+| `onshare` | `() => void`                              | —       | Fires after share (or clipboard fallback copy).              |
+| `children`| `Snippet`                                 | —       | Custom button content; replaces icon + label.                |
+
+All other props pass through to the underlying `Button` (or `Clipboard` on unsupported browsers).

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

@@ -0,0 +1,139 @@
+# Shell
+
+## Notes
+
+`Screen` and `Nav` lay out against `env(safe-area-inset-*)`, which stays zero unless the viewport opts in. Add `viewport-fit=cover` to the viewport meta in `src/app.html`:
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+```
+
+Safari 26 on iOS also keeps its bottom toolbar translucent only while page content reaches the bottom edge — `Nav` holds itself 6px above it for that.
+
+## Usage
+
+Root layout with section nav:
+
+```svelte
+<script lang="ts">
+  import { Screen, Nav, type Section } from '$com/shell'
+  import { House } from '@lucide/svelte'
+
+  const sections: Section[] = [
+    { id: 'home', href: '/', label: 'Home', Icon: House },
+  ]
+
+  let { children } = $props()
+</script>
+
+<Screen>
+  {@render children()}
+  <Nav {sections} underlay />
+</Screen>
+```
+
+Nested route — show back instead of tabs:
+
+```svelte
+<script lang="ts">
+  import { Return } from '$com/shell'
+</script>
+
+<Return href=".." />
+```
+
+## `back` / `jump`
+
+History-aware navigation for nested routes and editors. Both use the [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API) session stack; when the stack cannot satisfy the request, they fall back to SvelteKit `goto(href)`.
+
+**Why not plain `goto`?** A SPA that pushes a new history entry on every screen builds a long back chain. Users expect Back to undo their recent steps (and to keep scroll position / in-app transitions). `back` and `jump` prefer real history moves so the browser — and your shell — behave like a native app.
+
+### `back(href)`
+
+Go back one step when possible; otherwise navigate to `href`.
+
+Use when closing a nested screen, cancelling an editor, or deleting an item — anywhere `<Return href="…" />` would go, but triggered from code:
+
+```svelte
+<script lang="ts">
+  import { back } from '$com/shell'
+
+  async function onDelete() {
+    await deleteItem(id)
+    await back(`/items/${parentId}/`)
+  }
+</script>
+```
+
+If the user landed via deep link (nothing to pop), `back` opens `href` instead of doing nothing.
+
+### `jump(href)`
+
+Return to a URL already visited earlier in this session — without pushing another entry.
+
+Walks the session history backwards, finds the nearest prior entry whose path matches `href`, and calls `history.go(-n)`. If no match (or the match is too far back), falls back to `goto(href)`.
+
+Use after save/complete when the target list or detail page is already on the stack — e.g. editor → save → land on the list the user came from, skipping intermediate steps:
+
+```svelte
+<script lang="ts">
+  import { jump } from '$com/shell'
+
+  async function onSaved() {
+    await save(data)
+    await jump('/contacts/')
+  }
+</script>
+```
+
+Typical split: **`back`** for “undo my last navigation” (one step, parent route); **`jump`** for “take me to that earlier screen” (possibly several steps, exact URL).
+
+## Exports
+
+| Export         | Role                                                                    |
+| -------------- | ----------------------------------------------------------------------- |
+| `Screen`       | Page wrapper with safe-area insets and optional iOS status-bar underlay |
+| `Header`       | Sticky top bar with blur                                                |
+| `Nav`          | Fixed bottom bar: sections, back, toolbar                               |
+| `Return`       | Registers a back button in `Nav` for the current route                  |
+| `Actions`      | Registers toolbar snippets in `Nav`                                     |
+| `Attention`    | Small constructive dot (e.g. unseen badge on nav item)                  |
+| `Underlay`     | Gradient fade under fixed chrome                                        |
+| `Sticky`       | Sticky top/bottom bar over a blurred `Underlay` (e.g. a pinned action bar) |
+| `Section`      | Type for nav tab config                                                 |
+| `back`, `jump` | History-aware navigation — see above                                    |
+
+## Nav sections
+
+Each `Section` has `id`, `href`, `label`, `Icon` (Lucide component), optional `nested` path prefixes, optional `unseen` badge.
+
+When the current path is nested under an active section, other tabs collapse and a back chevron returns to the section root.
+
+## Props
+
+### `Screen`
+
+| Prop       | Type      | Default | Notes                            |
+| ---------- | --------- | ------- | -------------------------------- |
+| `underlay` | `boolean` | `true`  | iOS status-bar gradient underlay |
+| `unsafe`   | `boolean` | `false` | Skip safe-area padding           |
+
+### `Nav`
+
+| Prop       | Type                           | Default   | Notes                               |
+| ---------- | ------------------------------ | --------- | ----------------------------------- |
+| `sections` | `Section[]`                    | `[]`      | Bottom tab config                   |
+| `position` | `'start' \| 'center' \| 'end'` | `'start'` | Toolbar side; also flips bar layout |
+| `underlay` | `boolean`                      | `false`   | Gradient fade behind the bar        |
+
+### `Return`
+
+| Prop   | Type     | Default | Notes                                          |
+| ------ | -------- | ------- | ---------------------------------------------- |
+| `href` | `string` | `'..'`  | Passed to `back()` when history cannot go back |
+
+### `Actions`
+
+| Prop     | Type                | Default | Notes                                        |
+| -------- | ------------------- | ------- | -------------------------------------------- |
+| `active` | `Writable<boolean>` | —       | When true, fades nav items (e.g. modal open) |

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

@@ -0,0 +1,53 @@
+# Stack
+
+Collapsible card stack with view-transition morphs. Click the stack (or press Enter/Space on the root) to expand; bind `collapsed` or call `collapse()` / `expand()` / `toggle()` on a `Root` ref. Each `Item` needs a stable `id` for transition names.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import * as Stack from '$com/stack'
+  import { Button } from '$ui/button'
+
+  let stack: ReturnType<typeof Stack.Root> | undefined
+</script>
+
+<Stack.Root bind:this={stack}>
+  {#each items as item (item.id)}
+    <Stack.Item id={item.id}>
+      <Card>{item.title}</Card>
+    </Stack.Item>
+  {/each}
+  <Stack.Toolbar>
+    <Button variant="ghost" size="sm" onclick={() => stack?.collapse()}>Collapse</Button>
+  </Stack.Toolbar>
+</Stack.Root>
+```
+
+## Props
+
+### Root
+
+| Prop        | Type          | Default | Notes                                                                 |
+| ----------- | ------------- | ------- | --------------------------------------------------------------------- |
+| `children`  | `Snippet`     | —       | `Item` and optional `Toolbar` slots.                                  |
+| `collapsed` | `boolean`     | `true`  | Bindable. When true and item count ≥ `min`, cards stack visually.     |
+| `min`       | `number`      | `3`     | Minimum items before the stacked collapsed layout applies.            |
+| `class`     | `ClassValue`  | —       | Root container classes.                                               |
+
+**Methods** (via `bind:this`): `toggle(on?)`, `expand()`, `collapse()`.
+
+### Item
+
+| Prop       | Type      | Default | Notes                                      |
+| ---------- | --------- | ------- | ------------------------------------------ |
+| `children` | `Snippet` | —       | Card content.                              |
+| `id`       | `string`  | —       | Stable key for `view-transition-name`.     |
+| `class`    | `ClassValue`  | —       | Wrapper classes.                           |
+
+### Toolbar
+
+| Prop       | Type         | Default | Notes                                                        |
+| ---------- | ------------ | ------- | ------------------------------------------------------------ |
+| `children` | `Snippet`    | —       | Shown only when expanded and stacked (≥ `min` items).        |
+| `class`    | `ClassValue` | —       | Wrapper classes.                                             |

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

@@ -0,0 +1,149 @@
+# system
+
+The app's browser/OS platform layer — the counterpart to `shell`/`bridge` for system integration (service-worker lifecycle, updates, offline shell, in-app-webview escape). Its first capability is transparent, user-controlled updates: an installed PWA sees the new version download with live progress, gets a one-tap install control when ready, and restarts cleanly into it. The app version is derived from a bundled `changelog` mount — the same source that feeds the in-app release notes — so the version a user sees, the notes they read, and the build they get never drift.
+
+## Version identity & ordering
+
+The version is the build's **commit short-hash** (e.g. `f3a9c21`), used verbatim as the changelog key, the git release tag, and the on-screen version — so a version you see traces straight to its source with `git show <version>`. It is separate from `$service-worker.version` (the per-build hash), which the worker uses only for its cache name.
+
+Chronological order lives in each entry's `timestamp` (Unix milliseconds): the history sort, the pre-apply update delta, and the running-build baseline all compare `timestamp`. The running build exposes both identities:
+
+| Constant | Type | Meaning |
+| --- | --- | --- |
+| `version` | `string` | the running build's hash — for display / logging / the SW broadcast |
+| `timestamp` | `number` | the running build's release time — the ordering signal |
+
+`timestamp` is stored in svintl as a digit string and read back as a `number`. A fresh install with no releases yet shows a friendly empty state — key `0000000`, headline `Hello`, no date — which the first merged release replaces.
+
+## Setup
+
+Solution-level wiring that feeds the update store the UI reads.
+
+### Runtime wiring — `rc()`
+
+Call `rc()` once in the browser from the root `+layout.ts`. It wires reload-on-apply, the broadcast listener that feeds the `update` store, and cold detection of an already-waiting worker. It never reloads on its own — only an explicit `apply()` (the install control) triggers a restart, so an update can never interrupt a form in progress.
+
+```ts
+// src/routes/+layout.ts
+import { rc } from '@/system/rc'
+import { browser } from '$app/environment'
+
+if (browser) void rc()
+```
+
+### Service worker & caches
+
+- **The worker is self-contained.** It carries its own inlined push-payload `Notification` type and keeps the push / notification-click / offline-shell behaviour of a typical app worker, with no `@/transmission` dependency. If you already run `@/transmission`, reconcile the two workers yourself.
+- **Two caches.** The versioned app shell + build assets live in `cache-${hash}` (evicted on every update, so the app never serves stale code); runtime images from the API — requests under `/pictures/` — live in a separate `storage` cache, cache-first. Nothing evicts `storage` automatically: it survives updates, so only an explicit `clear()` empties it.
+
+### Localization
+
+This Solution ships **two** svintl mounts — the UI strings (`ui/intl`) and the machine-owned release notes (`svc/changelog/intl`) — each carrying only the locales this repo builds. Reconcile **both** to your own locale set once after install:
+
+```sh
+npx intl import system src/@/system/ui/intl
+npx intl import changelog src/@/system/svc/changelog/intl
+```
+
+Until both are imported, each `built.js` is typed against your `Locale` union and `check` fails on the locales it lacks. Never hand-edit the generated `*.yaml`/`built.js`/`types.ts`.
+
+## In-app-webview escape — `InApp`
+
+An in-app webview (Telegram, Instagram, Facebook, generic embedded browsers) is an insecure, degraded context where passkeys and OIDC popups misbehave. `InApp` guards the whole app against it: on mount it tries to bounce the user out into the real system browser, and if the OS swallows that redirect it overlays a full-screen "Insecure Context" card with a manual Continue control. In a normal browser it renders nothing.
+
+Because the protection must fire on **every** route — not just an auth screen — mount it once, high in the tree, in the root `+layout.svelte`:
+
+```svelte
+<script lang="ts">
+  import { InApp } from '@/system/ui'
+  const { children } = $props()
+</script>
+
+<InApp />
+{@render children()}
+```
+
+The webview detection and the pop-out side-effect are internal — no conditional wiring or environment checks are needed in your layout.
+
+## `VersionControl`
+
+The update status card: a single row that reads the `update` state and renders the running build with an up-to-date check, download progress while caching, or a one-tap install control once an update is waiting. Pass the `update` store value; drop it into a settings/about screen.
+
+### Usage
+
+```svelte
+<script lang="ts">
+  import { VersionControl } from '@/system/ui'
+  import { update } from '@/system'
+</script>
+
+<VersionControl update={$update} href="/changelog" />
+```
+
+### Props
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `update` | `Update` | The update store value (`$update`). |
+| `href` | `string` | Optional. When set, renders a release-notes / what's-new link. |
+
+## `Changelog`
+
+The full release-notes list for a settings/about or dedicated notes screen. Renders the running build's bundled history and, when an update is waiting, the incoming entries above it — the waiting version carries an inline install control, and the running version is tagged as installed. Both come in as props, so you choose the source (the bundled `changelog` mount for history, the `update` store for the incoming delta).
+
+### Usage
+
+```svelte
+<script lang="ts">
+  import { Changelog } from '@/system/ui'
+  import { update, changelog } from '@/system'
+</script>
+
+<Changelog update={$update} {changelog} />
+```
+
+### Props
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `update` | `Update` | The update store value; a `ready` state contributes the incoming delta and its install control. |
+| `changelog` | `Log` | An all-locales changelog — typically the bundled `changelog` mount. |
+| `class` | `ClassValue` | Applied to the list. |
+
+## On-demand check — `check()`
+
+Force a fresh update check wherever it makes sense (settings/about screen, pull-to-refresh). `version` is the running app's commit short-hash — the same string shown, tagged, and keyed in the changelog.
+
+```ts
+import { check, version } from '@/system'
+
+await check()
+```
+
+## Authoring notes
+
+The `changelog` mount is maintained through the `npx intl` CLI — by hand, or automatically by the CI workflows below. Each entry is keyed by commit short-hash and holds translatable `headline`/`description` (Markdown) and non-translatable `timestamp` (Unix milliseconds) / `picture`. `description` renders through `marked` (trusted-content — the notes are authored in-repo, so there is no sanitizer). Never hand-edit the generated `*.yaml`/`built.js`/`types.ts`.
+
+## Automated versioning & changelog (CI)
+
+Two GitHub Actions workflows install to your repo (`.github/workflows/changelog.yml`, `.github/workflows/release.yml`) alongside a static agent prompt (`.github/changelog-prompt.md`). They keep the changelog, the version, and the git tag in sync with zero manual bumping — the responsibility split is deterministic-by-default: an AI agent only edits the intl mount, while committing, pushing, tagging, and releasing are done by fixed steps. **The version is never LLM-generated.**
+
+### `changelog.yml` — on merge to `dev`
+
+Each PR merged into `dev` folds its user-visible changes into the single unreleased "next release" entry:
+
+1. A deterministic Node step computes three things — the version (`git rev-parse --short=7 HEAD`, the commit short-hash), the release timestamp (`Date.now()`, Unix ms), and **which entry is unreleased**: the changelog key present on `dev` but not on `production` (a pure set difference over the built dictionaries, so it needs no ordering and survives a deleted tag). It fails loudly if it ever finds more than one unreleased entry. The agent never picks a version, a time, or an entry.
+2. The Cursor CLI is installed from the **official** `curl https://cursor.com/install` (no first-party Action exists; the third-party marketplace one is deliberately avoided — it would receive your `CURSOR_API_KEY` plus write access).
+3. `cursor-agent` runs `.github/changelog-prompt.md` and **edits the changelog intl mount only** (it is instructed never to commit, branch, push, or reason about git/ordering): it keys the unreleased entry to the computed hash, writes the timestamp verbatim, integrates the PR diff into its Markdown description, and rebuilds the mount via `npx intl`.
+4. `stefanzweifel/git-auto-commit-action` commits the result back to `dev` (`chore(changelog): <hash>`). A `pull_request` trigger does not re-run on this push, so there is no loop.
+
+### `release.yml` — on merge to `production`
+
+Fully deterministic, no AI: reads the newest changelog key (by `timestamp`), tags the released `production` commit with that key verbatim (the commit short-hash), and publishes a GitHub Release whose body is the entry's en-US `description`. The tag is a release label matching the changelog key; it points at the `production` commit, whose own hash differs from the tag name.
+
+### Setup
+
+- **`CURSOR_API_KEY` secret** — required by `changelog.yml`. Add it under repo → Settings → Secrets and variables → Actions.
+- **Let the Actions bot push to `dev`.** `changelog.yml` commits back to `dev` with the default `GITHUB_TOKEN`. If `dev` is a protected branch, either add the Actions bot to the bypass list or swap in a PAT / GitHub App token with push rights; on an unprotected `dev` it works as-is.
+- **svintl Cursor skill.** The agent drives `npx intl` through the svintl Cursor skill — install it in the repo if absent (e.g. `npx skills add temich/svintl -a --all`).
+- **Branches.** The workflows assume a `dev` → `production` flow; rename the trigger branches if yours differ.

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

@@ -0,0 +1,28 @@
+# TapTap
+
+Fires `onclick` only after `taps` consecutive presses within `gap` ms. Use the `child` snippet to wrap an existing control; otherwise renders a native `<button>`.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { TapTap } from '$com/taptap'
+</script>
+
+<TapTap taps={3} gap={400} onclick={() => confirm()}>
+  Tap 3×
+</TapTap>
+```
+
+## Props
+
+| Prop       | Type                                              | Default    | Notes                                                                 |
+| ---------- | ------------------------------------------------- | ---------- | --------------------------------------------------------------------- |
+| `taps`     | `number`                                          | `2`        | Consecutive presses required before `onclick` fires.                  |
+| `gap`      | `number` (ms)                                     | `500`      | Max interval between presses to count as consecutive.                 |
+| `onclick`  | `MouseEventHandler<HTMLButtonElement>`            | —          | Fires after the tap sequence completes.                               |
+| `child`    | `Snippet<[{ onclick: () => void; n: number }]>` | —          | Renders instead of the default button; pass `onclick` to your control. `n` is the current position in the sequence (`0` when idle). |
+| `children` | `Snippet`                                         | —          | Button content when `child` is omitted.                               |
+| `type`     | `HTMLButtonAttributes['type']`                    | `'button'` | Native button type when not using `child`.                            |
+
+All other props pass through to the underlying `<button>` when `child` is omitted.