chore: release v0.12.0

Bump to 0.12.0 and record the changelog: in-dialog send-to-wallet stepper,
past-date-blocking appointment/invoice pickers, wallet-number-only portal link,
and removal of the stale Settings Features section.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.agents/skills/heroui-migration/LICENSE.txt

@@ -0,0 +1,199 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. Please also get an approval
+      from the project maintainers before using the Apache License.
+
+   Copyright 2025 NextUI Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

.agents/skills/heroui-migration/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: heroui-migration
+description: "HeroUI v2 to v3 migration guide for agents. Use when migrating HeroUI v2 apps to v3, upgrading components, or accessing migration documentation. Keywords: HeroUI migration, v2 to v3, migration guide, upgrade HeroUI."
+metadata:
+  author: heroui
+  version: "2.0.0"
+  status: preview
+---
+
+# HeroUI v2 to v3 Migration Guide
+
+This skill helps agents migrate HeroUI v2 applications to v3. HeroUI v3 introduces breaking changes: compound components, no Provider, Tailwind v4, and removed hooks.
+
+---
+
+## Installation
+
+```bash
+curl -fsSL https://heroui.com/install | bash -s heroui-migration
+```
+
+---
+
+## CRITICAL: Always Fetch Migration Docs Before Applying
+
+**Do NOT assume v2 patterns work in v3.** Always fetch migration guides before implementing changes.
+
+### Key v2 → v3 Changes
+
+| Feature       | v2 (Migrate From)          | v3 (Migrate To)                        |
+| ------------- | -------------------------- | -------------------------------------- |
+| Provider      | `<HeroUIProvider>` required | **No Provider needed**                 |
+| Component API | Flat props: `<Card title="x">` | Compound: `<Card><Card.Header>`      |
+| Event handlers | `onClick`                 | `onPress`                              |
+| Styling       | `classNames` prop         | `className` prop                       |
+| Hooks         | `useSwitch`, `useDisclosure`, etc. | Compound components, `useOverlayState` |
+| Packages      | `@heroui/system`, `@heroui/theme` | `@heroui/react`, `@heroui/styles` |
+
+---
+
+## Accessing Migration Documentation
+
+**For migration details, examples, and step-by-step guides, always fetch documentation:**
+
+### Using Scripts
+
+```bash
+# List all available component migration guides
+node scripts/list_migration_guides.mjs
+
+# Get main migration workflow (full or incremental)
+node scripts/get_migration_guide.mjs full
+node scripts/get_migration_guide.mjs incremental
+
+# Get component-specific migration guides
+node scripts/get_component_migration_guides.mjs button
+node scripts/get_component_migration_guides.mjs button card modal
+
+# Get styling migration guide
+node scripts/get_styling_migration_guide.mjs
+
+# Get hooks migration guide
+node scripts/get_hooks_migration_guide.mjs
+```
+
+### Direct URLs
+
+Migration docs (preview): `https://heroui-git-docs-migration-heroui.vercel.app/docs/react/migration/{filename}`
+
+Examples:
+
+- Full migration: `.../agent-guide-full.mdx`
+- Incremental: `.../agent-guide-incremental.mdx`
+- Button: `.../button.mdx`
+- Styling: `.../styling.mdx`
+- Hooks: `.../hooks.mdx`
+
+Override base URL with `HEROUI_MIGRATION_DOCS_BASE` when docs are merged to production.
+
+### MCP Alternative
+
+When using Cursor or other MCP clients, configure the Migration MCP server for tool-based access:
+
+```json
+{
+  "mcpServers": {
+    "heroui-migration": {
+      "url": "https://migration-mcp.heroui.com"
+    }
+  }
+}
+```
+
+---
+
+## Migration Strategies
+
+### Full Migration
+
+- Best for: Projects that can dedicate focused time; teams comfortable with temporarily broken code
+- Migrate all component code first (project broken during migration)
+- Switch dependencies to v3
+- Complete styling migration
+
+### Incremental Migration
+
+- Best for: Projects that must stay functional; large codebases migrating gradually
+- Set up coexistence (pnpm aliases or component packages)
+- Migrate components one-by-one
+- Both v2 and v3 coexist during migration
+
+**Always fetch the agent guide before starting:** `node scripts/get_migration_guide.mjs full` or `incremental`
+
+---
+
+## Core Principles
+
+1. **Fetch first**: Use scripts to get migration guides before applying changes
+2. **Compound components**: v3 uses `Card.Header`, `Card.Title`, `Button` with children—not flat props
+3. **No Provider**: Remove `HeroUIProvider` when migrating
+4. **onPress not onClick**: All interactive components use `onPress`
+5. **Workflow**: Analyze → Migrate components → Switch deps → Styling migration
+
+---
+
+## Migration Workflow Summary
+
+1. Create migration branch
+2. Analyze project (HeroUI imports, component usage)
+3. Fetch main guide: `node scripts/get_migration_guide.mjs full`
+4. Migrate components in batches (fetch component guides per batch)
+5. Switch dependencies to v3
+6. Fetch styling guide: `node scripts/get_styling_migration_guide.mjs`
+7. Apply styling updates
+
+---
+
+## Preview Mode
+
+This skill targets the staging deployment of the `docs/migration` branch. Once docs are merged to main and live on heroui.com, set `HEROUI_MIGRATION_DOCS_BASE=https://heroui.com/docs/react/migration` or update the default in scripts.

.agents/skills/heroui-migration/scripts/get_component_migration_guides.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * Get migration guides for HeroUI components (v2 to v3).
+ *
+ * Usage:
+ *   node get_component_migration_guides.mjs button
+ *   node get_component_migration_guides.mjs button card modal
+ *
+ * Output:
+ *   MDX migration guide content for each component
+ */
+
+const DOCS_BASE =
+  process.env.HEROUI_MIGRATION_DOCS_BASE ||
+  "https://heroui-git-docs-migration-heroui.vercel.app/docs/react/migration";
+const APP_PARAM = "app=migration-skills";
+
+/**
+ * Convert PascalCase or mixed case to kebab-case.
+ */
+function toKebabCase(name) {
+  return name
+    .replace(/([a-z])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
+    .toLowerCase()
+    .trim();
+}
+
+async function fetchDoc(filename) {
+  const url = `${DOCS_BASE}/${filename}?${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Migration-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return await response.text();
+  } catch (error) {
+    throw new Error(error.message);
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error("Usage: node get_component_migration_guides.mjs <Component1> [Component2] ...");
+    console.error("Example: node get_component_migration_guides.mjs button card modal");
+    console.error("\nUse list_migration_guides.mjs to see all available components.");
+    process.exit(1);
+  }
+
+  const components = args.map((c) => toKebabCase(c));
+
+  console.error(`# Fetching migration guides for: ${components.join(", ")}...`);
+
+  const results = [];
+
+  for (const component of components) {
+    const filename = `${component}.mdx`;
+
+    try {
+      const content = await fetchDoc(filename);
+      const title = component.charAt(0).toUpperCase() + component.slice(1).replace(/-/g, " ");
+
+      results.push({
+        component,
+        content: `# ${title} Migration Guide\n\n**Component:** ${component}\n**Source:** ${DOCS_BASE}/${filename}\n\n---\n\n${content}`,
+      });
+    } catch (error) {
+      results.push({
+        component,
+        error: error.message,
+      });
+    }
+  }
+
+  const failed = results.filter((r) => r.error);
+
+  if (failed.length > 0) {
+    failed.forEach((r) => console.error(`# Error for ${r.component}: ${r.error}`));
+  }
+
+  if (results.length === 1) {
+    const r = results[0];
+
+    if (r.content) {
+      console.log(r.content);
+    } else {
+      console.log(JSON.stringify(r, null, 2));
+      process.exit(1);
+    }
+  } else {
+    const output = results
+      .map((r) => (r.content ? r.content : `# ${r.component} Migration Guide\n\nError: ${r.error}`))
+      .join("\n\n---\n\n");
+
+    console.log(output);
+    if (failed.length === results.length) {
+      process.exit(1);
+    }
+  }
+}
+
+main();

.agents/skills/heroui-migration/scripts/get_hooks_migration_guide.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * Get the hooks migration guide for HeroUI v2 to v3.
+ *
+ * Usage:
+ *   node get_hooks_migration_guide.mjs
+ *
+ * Output:
+ *   MDX hooks migration guide content
+ */
+
+const DOCS_BASE =
+  process.env.HEROUI_MIGRATION_DOCS_BASE ||
+  "https://heroui-git-docs-migration-heroui.vercel.app/docs/react/migration";
+const APP_PARAM = "app=migration-skills";
+
+async function fetchDoc(filename) {
+  const url = `${DOCS_BASE}/${filename}?${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Migration-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return await response.text();
+  } catch (error) {
+    throw new Error(`Failed to fetch ${filename}: ${error.message}`);
+  }
+}
+
+async function main() {
+  const filename = "hooks.mdx";
+
+  console.error("# Fetching hooks migration guide...");
+
+  try {
+    const content = await fetchDoc(filename);
+
+    console.log(
+      `# HeroUI v2 to v3 Hooks Migration Guide\n\n**Source:** ${DOCS_BASE}/${filename}\n\n---\n\n${content}`,
+    );
+  } catch (error) {
+    console.error(`# Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();

.agents/skills/heroui-migration/scripts/get_migration_guide.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * Get the main migration workflow guide (full or incremental) for HeroUI v2 to v3.
+ *
+ * Usage:
+ *   node get_migration_guide.mjs [full|incremental]
+ *
+ * Default: full
+ *
+ * Output:
+ *   MDX migration guide content
+ */
+
+const DOCS_BASE =
+  process.env.HEROUI_MIGRATION_DOCS_BASE ||
+  "https://heroui-git-docs-migration-heroui.vercel.app/docs/react/migration";
+const APP_PARAM = "app=migration-skills";
+
+async function fetchDoc(filename) {
+  const url = `${DOCS_BASE}/${filename}?${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Migration-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return await response.text();
+  } catch (error) {
+    throw new Error(`Failed to fetch ${filename}: ${error.message}`);
+  }
+}
+
+async function main() {
+  const arg = (process.argv[2] || "full").toLowerCase();
+  const migrationType = arg === "incremental" ? "incremental" : "full";
+  const filename =
+    migrationType === "incremental" ? "agent-guide-incremental.mdx" : "agent-guide-full.mdx";
+
+  console.error(`# Fetching ${migrationType} migration guide...`);
+
+  try {
+    const content = await fetchDoc(filename);
+    const title =
+      migrationType === "incremental"
+        ? "HeroUI v2 to v3 Agent Migration Guide - Incremental Migration"
+        : "HeroUI v2 to v3 Agent Migration Guide - Full Migration";
+
+    console.log(`# ${title}\n\n**Source:** ${DOCS_BASE}/${filename}\n\n---\n\n${content}`);
+  } catch (error) {
+    console.error(`# Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();

.agents/skills/heroui-migration/scripts/get_styling_migration_guide.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * Get the styling migration guide for HeroUI v2 to v3.
+ *
+ * Usage:
+ *   node get_styling_migration_guide.mjs
+ *
+ * Output:
+ *   MDX styling migration guide content
+ */
+
+const DOCS_BASE =
+  process.env.HEROUI_MIGRATION_DOCS_BASE ||
+  "https://heroui-git-docs-migration-heroui.vercel.app/docs/react/migration";
+const APP_PARAM = "app=migration-skills";
+
+async function fetchDoc(filename) {
+  const url = `${DOCS_BASE}/${filename}?${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Migration-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return await response.text();
+  } catch (error) {
+    throw new Error(`Failed to fetch ${filename}: ${error.message}`);
+  }
+}
+
+async function main() {
+  const filename = "styling.mdx";
+
+  console.error("# Fetching styling migration guide...");
+
+  try {
+    const content = await fetchDoc(filename);
+
+    console.log(
+      `# HeroUI v2 to v3 Styling Migration Guide\n\n**Source:** ${DOCS_BASE}/${filename}\n\n---\n\n${content}`,
+    );
+  } catch (error) {
+    console.error(`# Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();

.agents/skills/heroui-migration/scripts/list_migration_guides.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * List all available HeroUI v2 to v3 component migration guides.
+ *
+ * Usage:
+ *   node list_migration_guides.mjs
+ *
+ * Output:
+ *   List of component names that have migration guides
+ *
+ * Note: Keep in sync with migration-mcp list-migration-guides.ts when adding components.
+ */
+
+// Component migration guides available - must match migration-mcp list-migration-guides.ts
+const AVAILABLE_COMPONENTS = [
+  "accordion",
+  "alert",
+  "autocomplete",
+  "avatar",
+  "breadcrumbs",
+  "button",
+  "button-group",
+  "card",
+  "checkbox",
+  "checkbox-group",
+  "chip",
+  "code",
+  "divider",
+  "dropdown",
+  "form",
+  "image",
+  "input",
+  "input-otp",
+  "kbd",
+  "link",
+  "listbox",
+  "modal",
+  "navbar",
+  "numberinput",
+  "popover",
+  "radio",
+  "radio-group",
+  "scroll-shadow",
+  "select",
+  "skeleton",
+  "slider",
+  "snippet",
+  "spacer",
+  "spinner",
+  "switch",
+  "tabs",
+  "toast",
+  "tooltip",
+  "user",
+];
+
+function main() {
+  const componentsList = AVAILABLE_COMPONENTS.map((name) => `  - ${name}`).join("\n");
+
+  console.log(
+    `# Available Component Migration Guides\n\nFound ${AVAILABLE_COMPONENTS.length} component migration guides:\n\n${componentsList}\n\nUse get_component_migration_guides.mjs with component names to fetch specific guides.\nExample: node get_component_migration_guides.mjs button card modal`,
+  );
+}
+
+main();

.agents/skills/heroui-native/LICENSE.txt

@@ -0,0 +1,199 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. Please also get an approval
+      from the project maintainers before using the Apache License.
+
+   Copyright 2025 NextUI Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

.agents/skills/heroui-native/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: heroui-native
+description: "HeroUI Native component library for React Native (Tailwind v4 via Uniwind). Use when building mobile UIs with HeroUI Native — creating Buttons, Cards, TextFields, Dialogs; installing heroui-native; configuring dark/light themes; or fetching component docs. Keywords: HeroUI Native, heroui-native, React Native UI, Uniwind, mobile components."
+metadata:
+  author: heroui
+  version: "2.0.1"
+---
+
+# HeroUI Native Development Guide
+
+HeroUI Native is a component library built on **Uniwind (Tailwind CSS for React Native)** and **React Native**, providing accessible, customizable UI components for mobile applications.
+
+---
+
+## Installation
+
+```bash
+curl -fsSL https://heroui.com/install | bash -s heroui-native
+```
+
+---
+
+## CRITICAL: Native Only - Do Not Use Web Patterns
+
+**This guide is for HeroUI Native ONLY.** Do NOT apply HeroUI React (web) patterns — the package, styling engine, and color format all differ:
+
+| Feature      | React (Web)          | Native (Mobile)                     |
+| ------------ | -------------------- | ----------------------------------- |
+| **Styling**  | Tailwind CSS v4      | Uniwind (Tailwind for React Native) |
+| **Colors**   | oklch format         | HSL format                          |
+| **Package**  | `@heroui/react` 	  | `heroui-native`                     |
+| **Platform** | Web browsers         | iOS & Android                       |
+
+```tsx
+// CORRECT — Native pattern
+import { Button } from "heroui-native";
+
+<Button variant="primary" onPress={() => console.log("Pressed!")}>
+	Click me
+</Button>;
+```
+
+**Always fetch Native docs before implementing.**
+
+---
+
+## Core Principles
+
+- Semantic variants (`primary`, `secondary`, `tertiary`) over visual descriptions
+- Composition over configuration (compound components)
+- Theme variables with HSL color format
+- React Native StyleSheet patterns with Uniwind utilities
+
+---
+
+## Accessing Documentation & Component Information
+
+**For component details, examples, props, and implementation patterns, always fetch documentation:**
+
+### Using Scripts
+
+```bash
+# List all available components
+node scripts/list_components.mjs
+
+# Get component documentation (MDX)
+node scripts/get_component_docs.mjs Button
+node scripts/get_component_docs.mjs Button Card TextField
+
+# Get theme variables
+node scripts/get_theme.mjs
+
+# Get non-component docs (guides, releases)
+node scripts/get_docs.mjs /docs/native/getting-started/theming
+```
+
+### Direct MDX URLs
+
+Component docs: `https://heroui.com/docs/native/components/{component-name}.mdx`
+
+Examples:
+
+- Button: `https://heroui.com/docs/native/components/button.mdx`
+- Dialog: `https://heroui.com/docs/native/components/dialog.mdx`
+- TextField: `https://heroui.com/docs/native/components/text-field.mdx`
+
+Getting started guides: `https://heroui.com/docs/native/getting-started/{topic}.mdx`
+
+**Important:** Always fetch component docs before implementing. The MDX docs include complete examples, props, anatomy, and API references.
+
+---
+
+## Installation Essentials
+
+### Quick Install
+
+```bash
+npm i heroui-native react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants
+```
+
+### Framework Setup (Expo - Recommended)
+
+1. **Install dependencies:**
+
+```bash
+npx create-expo-app MyApp
+cd MyApp
+npm i heroui-native uniwind tailwindcss
+npm i react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants
+```
+
+2. **Create `global.css`:**
+
+```css
+@import "tailwindcss";
+@import "uniwind";
+@import "heroui-native/styles";
+
+@source "./node_modules/heroui-native/lib";
+```
+
+3. **Wrap app with providers:**
+
+```tsx
+import { GestureHandlerRootView } from "react-native-gesture-handler";
+import { HeroUINativeProvider } from "heroui-native";
+import "./global.css";
+
+export default function Layout() {
+	return (
+		<GestureHandlerRootView style={{ flex: 1 }}>
+			<HeroUINativeProvider>
+				<App />
+			</HeroUINativeProvider>
+		</GestureHandlerRootView>
+	);
+}
+```
+
+### Critical Setup Requirements
+
+1. **Uniwind is Required** - HeroUI Native uses Uniwind (Tailwind CSS for React Native)
+2. **HeroUINativeProvider Required** - Wrap your app with `HeroUINativeProvider`
+3. **GestureHandlerRootView Required** - Wrap with `GestureHandlerRootView` from react-native-gesture-handler
+4. **Use Compound Components** - Components use compound structure (e.g., `Card.Header`, `Card.Body`)
+5. **Use onPress, not onClick** - React Native uses `onPress` event handlers
+6. **Platform-Specific Code** - Use `Platform.OS` for iOS/Android differences
+
+---
+
+## Component Patterns
+
+HeroUI Native uses **compound component patterns**. Each component has subcomponents accessed via dot notation.
+
+**Example - Card:**
+
+```tsx
+<Card>
+	<Card.Header>{/* Icons, badges */}</Card.Header>
+	<Card.Body>
+		<Card.Title>Title</Card.Title>
+		<Card.Description>Description</Card.Description>
+	</Card.Body>
+	<Card.Footer>{/* Actions */}</Card.Footer>
+</Card>
+```
+
+**Key Points:**
+
+- Always use compound structure - don't flatten to props
+- Subcomponents are accessed via dot notation (e.g., `Card.Header`)
+- Native Card uses `Card.Body` (not `Card.Content`); Title and Description go inside Body
+- **Fetch component docs for complete anatomy and examples**
+
+---
+
+## Semantic Variants
+
+HeroUI uses semantic naming to communicate functional intent:
+
+| Variant       | Purpose                           | Usage          |
+| ------------- | --------------------------------- | -------------- |
+| `primary`     | Main action to move forward       | 1 per context  |
+| `secondary`   | Alternative actions               | Multiple       |
+| `tertiary`    | Dismissive actions (cancel, skip) | Sparingly      |
+| `danger`      | Destructive actions               | When needed    |
+| `danger-soft` | Soft destructive actions          | Less prominent |
+| `ghost`       | Low-emphasis actions              | Minimal weight |
+| `outline`     | Secondary actions                 | Bordered style |
+
+**Don't use raw colors** - semantic variants adapt to themes and accessibility.
+
+---
+
+## Theming
+
+HeroUI Native uses CSS variables via Tailwind/Uniwind for theming. Theme colors are defined in `global.css`:
+
+```css
+@theme {
+	--color-accent: hsl(260, 100%, 70%);
+	--color-accent-foreground: hsl(0, 0%, 100%);
+}
+```
+
+**Get current theme variables:**
+
+```bash
+node scripts/get_theme.mjs
+```
+
+**Access theme colors programmatically:**
+
+```tsx
+import { useThemeColor } from "heroui-native";
+
+const accentColor = useThemeColor("accent");
+```
+
+**Theme switching (Light/Dark Mode):**
+
+```tsx
+import { Uniwind, useUniwind } from "uniwind";
+
+const { theme } = useUniwind();
+Uniwind.setTheme(theme === "light" ? "dark" : "light");
+```
+
+For detailed theming, fetch: `https://heroui.com/docs/native/getting-started/theming.mdx`

.agents/skills/heroui-native/scripts/get_component_docs.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * Get complete component documentation (MDX) for HeroUI Native components.
+ *
+ * Usage:
+ *   node get_component_docs.mjs Button
+ *   node get_component_docs.mjs Button Card TextField
+ *
+ * Output:
+ *   MDX documentation including imports, usage, variants, props, examples
+ */
+
+const API_BASE = process.env.HEROUI_NATIVE_API_BASE || "https://native-mcp-api.heroui.com";
+const FALLBACK_BASE = "https://heroui.com";
+const APP_PARAM = "app=native-skills";
+
+/**
+ * Convert PascalCase to kebab-case.
+ */
+function toKebabCase(name) {
+  return name
+    .replace(/([a-z])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
+    .toLowerCase();
+}
+
+/**
+ * Fetch data from HeroUI Native API with app parameter for analytics.
+ */
+async function fetchApi(endpoint, method = "GET", body = null) {
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${API_BASE}${endpoint}${separator}${APP_PARAM}`;
+
+  try {
+    const options = {
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": "HeroUI-Native-Skill/1.0",
+      },
+      method,
+      signal: AbortSignal.timeout(30000),
+    };
+
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+
+    if (!response.ok) {
+      return null;
+    }
+
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetch MDX directly from v3.heroui.com as fallback.
+ */
+async function fetchFallback(component) {
+  const kebabName = toKebabCase(component);
+  const url = `${FALLBACK_BASE}/docs/native/components/${kebabName}.mdx`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Native-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      return {component, error: `Failed to fetch docs for ${component}`};
+    }
+
+    const content = await response.text();
+
+    return {
+      component,
+      content,
+      contentType: "mdx",
+      source: "fallback",
+      url,
+    };
+  } catch {
+    return {component, error: `Failed to fetch docs for ${component}`};
+  }
+}
+
+/**
+ * Main function to get component documentation.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error("Usage: node get_component_docs.mjs <Component1> [Component2] ...");
+    console.error("Example: node get_component_docs.mjs Button Card");
+    process.exit(1);
+  }
+
+  const components = args;
+
+  // Try API first - use POST /v1/components/docs for batch requests
+  console.error(`# Fetching Native docs for: ${components.join(", ")}...`);
+  const data = await fetchApi("/v1/components/docs", "POST", {components});
+
+  if (data && data.results) {
+    // Output results
+    if (data.results.length === 1) {
+      // Single component - output content directly for easier reading
+      const result = data.results[0];
+
+      if (result.content) {
+        console.log(result.content);
+      } else if (result.error) {
+        console.error(`# Error for ${result.component}: ${result.error}`);
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(JSON.stringify(result, null, 2));
+      }
+    } else {
+      // Multiple components - output as JSON array
+      console.log(JSON.stringify(data, null, 2));
+    }
+
+    return;
+  }
+
+  // Fallback to individual component fetches
+  console.error("# API failed, using fallback...");
+  const results = [];
+
+  for (const component of components) {
+    const result = await fetchFallback(component);
+
+    results.push(result);
+  }
+
+  // Output results
+  if (results.length === 1) {
+    // Single component - output content directly for easier reading
+    const result = results[0];
+
+    if (result.content) {
+      console.log(result.content);
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+  } else {
+    // Multiple components - output as JSON array
+    console.log(JSON.stringify(results, null, 2));
+  }
+}
+
+main();

.agents/skills/heroui-native/scripts/get_docs.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * Get non-component HeroUI Native documentation (guides, theming, releases).
+ *
+ * Usage:
+ *   node get_docs.mjs /docs/native/getting-started/theming
+ *   node get_docs.mjs /docs/native/releases/beta-12
+ *
+ * Output:
+ *   MDX documentation content
+ *
+ * Note: For component docs, use get_component_docs.mjs instead.
+ */
+
+const API_BASE = process.env.HEROUI_NATIVE_API_BASE || "https://native-mcp-api.heroui.com";
+const FALLBACK_BASE = "https://heroui.com";
+const APP_PARAM = "app=native-skills";
+
+/**
+ * Fetch documentation from HeroUI Native API.
+ * Uses v1 endpoint pattern: /v1/docs/:path
+ */
+async function fetchApi(path) {
+  // The v1 API expects path without /docs/ prefix
+  // Input: /docs/native/getting-started/theming
+  // API expects: native/getting-started/theming (route is /v1/docs/:path(*))
+  let apiPath = path.startsWith("/docs/")
+    ? path.slice(6) // Remove /docs/ prefix
+    : path.startsWith("/")
+      ? path.slice(1) // Remove leading /
+      : path;
+
+  const separator = "?";
+  const url = `${API_BASE}/v1/docs/${apiPath}${separator}${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Native-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      console.error(`# API Error: HTTP ${response.status}`);
+
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`# API Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Fetch MDX directly from v3.heroui.com as fallback.
+ */
+async function fetchFallback(path) {
+  // Ensure path starts with /docs and ends with .mdx
+  let cleanPath = path.replace(/^\//, "");
+
+  if (!cleanPath.endsWith(".mdx")) {
+    cleanPath = `${cleanPath}.mdx`;
+  }
+
+  const url = `${FALLBACK_BASE}/${cleanPath}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Native-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      return {error: `HTTP ${response.status}: ${response.statusText}`, path};
+    }
+
+    const content = await response.text();
+
+    return {
+      content,
+      contentType: "mdx",
+      path,
+      source: "fallback",
+      url,
+    };
+  } catch (error) {
+    return {error: `Fetch Error: ${error.message}`, path};
+  }
+}
+
+/**
+ * Main function to get documentation for specified path.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error("Usage: node get_docs.mjs <path>");
+    console.error("Example: node get_docs.mjs /docs/native/getting-started/theming");
+    console.error();
+    console.error("Available paths include:");
+    console.error("  /docs/native/getting-started/theming");
+    console.error("  /docs/native/getting-started/colors");
+    console.error("  /docs/native/getting-started/styling");
+    console.error("  /docs/native/releases/beta-12");
+    console.error();
+    console.error("Note: For component docs, use get_component_docs.mjs instead.");
+    process.exit(1);
+  }
+
+  const path = args[0];
+
+  // Check if user is trying to get component docs
+  if (path.includes("/components/")) {
+    console.error("# Warning: Use get_component_docs.mjs for component documentation.");
+    const componentName = path.split("/").pop().replace(".mdx", "");
+    const titleCase = componentName.charAt(0).toUpperCase() + componentName.slice(1);
+
+    console.error(`# Example: node get_component_docs.mjs ${titleCase}`);
+  }
+
+  // Validate Native path
+  if (!path.startsWith("/docs/native/")) {
+    console.error("# Warning: Native documentation paths should start with /docs/native/");
+    console.error(`# Provided path: ${path}`);
+  }
+
+  console.error(`# Fetching Native documentation for ${path}...`);
+
+  // Try API first
+  const data = await fetchApi(path);
+
+  if (data && data.content) {
+    data.source = "api";
+    console.log(data.content);
+
+    return;
+  }
+
+  // Fallback to direct fetch
+  console.error("# API failed, using fallback...");
+  const fallbackData = await fetchFallback(path);
+
+  if (fallbackData.content) {
+    console.log(fallbackData.content);
+  } else {
+    console.log(JSON.stringify(fallbackData, null, 2));
+    process.exit(1);
+  }
+}
+
+main();

.agents/skills/heroui-native/scripts/get_theme.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/**
+ * Get theme variables and design tokens for HeroUI Native.
+ *
+ * Usage:
+ *   node get_theme.mjs
+ *
+ * Output:
+ *   Theme variables organized by light/dark with HSL color format
+ */
+
+const API_BASE = process.env.HEROUI_NATIVE_API_BASE || "https://native-mcp-api.heroui.com";
+const APP_PARAM = "app=native-skills";
+
+// Fallback theme reference when API is unavailable
+const FALLBACK_THEME = {
+  borderRadius: {
+    full: 9999,
+    lg: 12,
+    md: 8,
+    sm: 6,
+  },
+  dark: {
+    colors: [
+      {
+        category: "base",
+        name: "--color-background",
+        value: "hsl(0, 0%, 14.5%)",
+      },
+      {
+        category: "semantic",
+        name: "--color-foreground",
+        value: "hsl(0, 0%, 98.4%)",
+      },
+      {
+        category: "semantic",
+        name: "--color-accent",
+        value: "hsl(264.1, 100%, 55.1%)",
+      },
+      {
+        category: "status",
+        name: "--color-danger",
+        value: "hsl(25.3, 100%, 63.7%)",
+      },
+      {
+        category: "status",
+        name: "--color-success",
+        value: "hsl(163.2, 100%, 76.5%)",
+      },
+      {
+        category: "status",
+        name: "--color-warning",
+        value: "hsl(86.0, 100%, 79.5%)",
+      },
+    ],
+  },
+  latestVersion: "beta",
+  light: {
+    colors: [
+      {
+        category: "base",
+        name: "--color-background",
+        value: "hsl(0, 0%, 100%)",
+      },
+      {
+        category: "semantic",
+        name: "--color-foreground",
+        value: "hsl(285.89, 5.9%, 21.03%)",
+      },
+      {
+        category: "semantic",
+        name: "--color-accent",
+        value: "hsl(253.83, 100%, 62.04%)",
+      },
+      {
+        category: "status",
+        name: "--color-danger",
+        value: "hsl(25.74, 100%, 65.32%)",
+      },
+      {
+        category: "status",
+        name: "--color-success",
+        value: "hsl(150.81, 100%, 73.29%)",
+      },
+      {
+        category: "status",
+        name: "--color-warning",
+        value: "hsl(72.33, 100%, 78.19%)",
+      },
+    ],
+  },
+  note: "This is a fallback. For complete theme variables, ensure the API is accessible.",
+  opacity: {
+    disabled: 0.4,
+    hover: 0.8,
+    pressed: 0.6,
+  },
+  source: "fallback",
+  theme: "default",
+};
+
+/**
+ * Fetch data from HeroUI Native API with app parameter for analytics.
+ */
+async function fetchApi(endpoint) {
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${API_BASE}${endpoint}${separator}${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Native-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      console.error(`# API Error: HTTP ${response.status}`);
+
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`# API Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Format colors grouped by category.
+ */
+function formatColors(colors) {
+  const grouped = {};
+
+  for (const color of colors) {
+    const category = color.category || "semantic";
+
+    if (!grouped[category]) {
+      grouped[category] = [];
+    }
+    grouped[category].push(color);
+  }
+
+  const lines = [];
+
+  for (const [category, tokens] of Object.entries(grouped)) {
+    lines.push(`  /* ${category.charAt(0).toUpperCase() + category.slice(1)} Colors */`);
+    for (const token of tokens) {
+      const name = token.name || "";
+      const value = token.value || "";
+
+      lines.push(`  ${name}: ${value};`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Main function to get theme variables.
+ */
+async function main() {
+  console.error("# Fetching Native theme variables...");
+
+  const rawData = await fetchApi("/v1/themes/variables?theme=default");
+
+  let data;
+  let version;
+
+  if (!rawData) {
+    console.error("# API failed, using fallback theme reference...");
+    data = FALLBACK_THEME;
+    version = FALLBACK_THEME.latestVersion || "unknown";
+  } else {
+    // Handle API response format
+    data = rawData;
+    version = rawData.latestVersion || "unknown";
+  }
+
+  // Output as formatted structure for readability
+  console.log("/* HeroUI Native Theme Variables */");
+  console.log(`/* Theme: ${data.theme || "default"} */`);
+  console.log(`/* Version: ${version} */`);
+  console.log();
+
+  // Light mode colors
+  if (data.light && data.light.colors) {
+    console.log("/* Light Mode Colors */");
+    console.log(formatColors(data.light.colors));
+  }
+
+  // Dark mode colors
+  if (data.dark && data.dark.colors) {
+    console.log("/* Dark Mode Colors */");
+    console.log(formatColors(data.dark.colors));
+  }
+
+  // Border radius
+  if (data.borderRadius) {
+    console.log("/* Border Radius */");
+    for (const [key, value] of Object.entries(data.borderRadius)) {
+      console.log(`  --radius-${key}: ${value};`);
+    }
+    console.log();
+  }
+
+  // Opacity
+  if (data.opacity) {
+    console.log("/* Opacity */");
+    for (const [key, value] of Object.entries(data.opacity)) {
+      console.log(`  --opacity-${key}: ${value};`);
+    }
+    console.log();
+  }
+
+  // Also output raw JSON to stderr for programmatic use
+  console.error("\n# Raw JSON output:");
+  console.error(JSON.stringify(rawData || data, null, 2));
+}
+
+main();

.agents/skills/heroui-native/scripts/list_components.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * List all available HeroUI Native components.
+ *
+ * Usage:
+ *   node list_components.mjs
+ *
+ * Output:
+ *   JSON with components array, latestVersion, and count
+ */
+
+const API_BASE = process.env.HEROUI_NATIVE_API_BASE || "https://native-mcp-api.heroui.com";
+const APP_PARAM = "app=native-skills";
+const LLMS_TXT_URL = "https://heroui.com/native/llms.txt";
+
+/**
+ * Fetch data from HeroUI Native API with app parameter for analytics.
+ */
+async function fetchApi(endpoint) {
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${API_BASE}${endpoint}${separator}${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Native-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      console.error(`HTTP Error ${response.status}: ${response.statusText}`);
+
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`API Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Fetch component list from llms.txt fallback URL.
+ */
+async function fetchFallback() {
+  try {
+    const response = await fetch(LLMS_TXT_URL, {
+      headers: {"User-Agent": "HeroUI-Native-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const content = await response.text();
+
+    // Parse markdown to extract component names from pattern: - [ComponentName](url)
+    // Look for links under the Components section (### Components)
+    const components = [];
+    let inComponentsSection = false;
+
+    for (const line of content.split("\n")) {
+      // Check if we're entering the Components section (uses ### header)
+      if (line.trim() === "### Components") {
+        inComponentsSection = true;
+        continue;
+      }
+
+      // Check if we're leaving the Components section (another ### header)
+      if (inComponentsSection && line.trim().startsWith("### ")) {
+        break;
+      }
+
+      // Extract component name from markdown link pattern
+      // Match: - [ComponentName](https://www.heroui.com/docs/native/components/component-name)
+      // Skip "All Components" which links to /components without a specific component
+      if (inComponentsSection) {
+        const match = line.match(
+          /^\s*-\s*\[([^\]]+)\]\(https:\/\/www\.heroui\.com\/docs\/native\/components\/[a-z]/,
+        );
+
+        if (match) {
+          components.push(match[1]);
+        }
+      }
+    }
+
+    if (components.length > 0) {
+      console.error(`# Using fallback: ${LLMS_TXT_URL}`);
+
+      return {
+        components: components.sort(),
+        count: components.length,
+        latestVersion: "unknown",
+      };
+    }
+
+    return null;
+  } catch (error) {
+    console.error(`Fallback Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Main function to list all available HeroUI Native components.
+ */
+async function main() {
+  let data = await fetchApi("/v1/components");
+
+  // Check if API returned valid data with components
+  if (!data || !data.components || data.components.length === 0) {
+    console.error("# API returned no components, trying fallback...");
+    data = await fetchFallback();
+  }
+
+  if (!data || !data.components || data.components.length === 0) {
+    console.error("Error: Failed to fetch component list from API and fallback");
+    process.exit(1);
+  }
+
+  // Output formatted JSON
+  console.log(JSON.stringify(data, null, 2));
+
+  // Print summary to stderr for human readability
+  console.error(
+    `\n# Found ${data.components.length} Native components (${data.latestVersion || "unknown"})`,
+  );
+}
+
+main();

.agents/skills/heroui-react/LICENSE.txt

@@ -0,0 +1,199 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. Please also get an approval
+      from the project maintainers before using the Apache License.
+
+   Copyright 2025 NextUI Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

.agents/skills/heroui-react/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: heroui-react
+description: "HeroUI v3 React component library (Tailwind CSS v4 + React Aria). Use when building UIs with HeroUI — creating Buttons, Modals, Forms, Cards; installing @heroui/react; configuring dark/light themes with oklch variables; or fetching component docs. Keywords: HeroUI, Hero UI, heroui, @heroui/react, @heroui/styles."
+metadata:
+  author: heroui
+  version: "3.0.1"
+---
+
+# HeroUI v3 React Development Guide
+
+HeroUI v3 is a component library built on **Tailwind CSS v4** and **React Aria Components**, providing accessible, customizable UI components for React applications.
+
+---
+
+## Installation
+
+```bash
+curl -fsSL https://heroui.com/install | bash -s heroui-react
+```
+
+---
+
+## CRITICAL: v3 Only - Ignore v2 Knowledge
+
+**This guide is for HeroUI v3 ONLY.** Do NOT apply v2 patterns — the provider, styling, and component API all changed:
+
+| Feature       | v2 (DO NOT USE)                   | v3 (USE THIS)                               |
+| ------------- | --------------------------------- | ------------------------------------------- |
+| Provider      | `<HeroUIProvider>` required       | **No Provider needed**                      |
+| Animations    | `framer-motion` package           | CSS-based, no extra deps                    |
+| Component API | Flat props: `<Card title="x">`    | Compound: `<Card><Card.Header>`             |
+| Styling       | Tailwind v3 + `@heroui/theme`     | Tailwind v4 + `@heroui/styles`         	  |
+| Packages      | `@heroui/system`, `@heroui/theme` | `@heroui/react`, `@heroui/styles` 		  |
+
+```tsx
+// DO NOT DO THIS - v2 pattern
+import { HeroUIProvider } from "@heroui/react";
+import { motion } from "framer-motion";
+
+<HeroUIProvider>
+	<Card title="Product" description="A great product" />
+</HeroUIProvider>;
+```
+
+### CORRECT (v3 patterns)
+
+```tsx
+// DO THIS - v3 pattern (no provider, compound components)
+import { Card } from "@heroui/react";
+
+<Card>
+	<Card.Header>
+		<Card.Title>Product</Card.Title>
+		<Card.Description>A great product</Card.Description>
+	</Card.Header>
+</Card>;
+```
+
+**Always fetch v3 docs before implementing.**
+
+---
+
+## Core Principles
+
+- Semantic variants (`primary`, `secondary`, `tertiary`) over visual descriptions
+- Composition over configuration (compound components)
+- CSS variable-based theming with `oklch` color space
+- BEM naming convention for predictable styling
+
+---
+
+## Accessing Documentation & Component Information
+
+**For component details, examples, props, and implementation patterns, always fetch documentation:**
+
+### Using Scripts
+
+```bash
+# List all available components
+node scripts/list_components.mjs
+
+# Get component documentation (MDX)
+node scripts/get_component_docs.mjs Button
+node scripts/get_component_docs.mjs Button Card TextField
+
+# Get component source code
+node scripts/get_source.mjs Button
+
+# Get component CSS styles (BEM classes)
+node scripts/get_styles.mjs Button
+
+# Get theme variables
+node scripts/get_theme.mjs
+
+# Get non-component docs (guides, releases)
+node scripts/get_docs.mjs /docs/react/getting-started/theming
+```
+
+### Direct MDX URLs
+
+Component docs: `https://heroui.com/docs/react/components/{component-name}.mdx`
+
+Examples:
+
+- Button: `https://heroui.com/docs/react/components/button.mdx`
+- Modal: `https://heroui.com/docs/react/components/modal.mdx`
+- Form: `https://heroui.com/docs/react/components/form.mdx`
+
+Getting started guides: `https://heroui.com/docs/react/getting-started/{topic}.mdx`
+
+**Important:** Always fetch component docs before implementing. The MDX docs include complete examples, props, anatomy, and API references.
+
+---
+
+## Installation Essentials
+
+### Quick Install
+
+```bash
+npm i @heroui/styles @heroui/react tailwind-variants
+```
+
+### Framework Setup (Next.js App Router - Recommended)
+
+1. **Install dependencies:**
+
+```bash
+npm i @heroui/styles @heroui/react tailwind-variants tailwindcss @tailwindcss/postcss postcss
+```
+
+2. **Create/update `app/globals.css`:**
+
+```css
+/* Tailwind CSS v4 - Must be first */
+@import "tailwindcss";
+
+/* HeroUI v3 styles - Must be after Tailwind */
+@import "@heroui/styles";
+```
+
+3. **Import in `app/layout.tsx`:**
+
+```tsx
+import "./globals.css";
+
+export default function RootLayout({
+	children,
+}: {
+	children: React.ReactNode;
+}) {
+	return (
+		<html lang="en" suppressHydrationWarning>
+			<body>
+				{/* No Provider needed in HeroUI v3! */}
+				{children}
+			</body>
+		</html>
+	);
+}
+```
+
+4. **Configure PostCSS (`postcss.config.mjs`):**
+
+```js
+export default {
+	plugins: {
+		"@tailwindcss/postcss": {},
+	},
+};
+```
+
+### Critical Setup Requirements
+
+1. **Tailwind CSS v4 is MANDATORY** - HeroUI v3 will NOT work with Tailwind CSS v3
+2. **Use Compound Components** - Components use compound structure (e.g., `Card.Header`, `Card.Content`)
+3. **Use onPress, not onClick** - For better accessibility, use `onPress` event handlers
+4. **Import Order Matters** - Always import Tailwind CSS before HeroUI styles
+
+---
+
+## Component Patterns
+
+All components use the **compound pattern** shown above (dot-notation subcomponents like `Card.Header`, `Card.Content`). Don't flatten to props — always compose with subcomponents. Fetch component docs for complete anatomy and examples.
+
+---
+
+## Semantic Variants
+
+HeroUI uses semantic naming to communicate functional intent:
+
+| Variant     | Purpose                           | Usage          |
+| ----------- | --------------------------------- | -------------- |
+| `primary`   | Main action to move forward       | 1 per context  |
+| `secondary` | Alternative actions               | Multiple       |
+| `tertiary`  | Dismissive actions (cancel, skip) | Sparingly      |
+| `danger`    | Destructive actions               | When needed    |
+| `ghost`     | Low-emphasis actions              | Minimal weight |
+| `outline`   | Secondary actions                 | Bordered style |
+
+**Don't use raw colors** - semantic variants adapt to themes and accessibility.
+
+---
+
+## Theming
+
+HeroUI v3 uses CSS variables with `oklch` color space:
+
+```css
+:root {
+	--accent: oklch(0.6204 0.195 253.83);
+	--accent-foreground: var(--snow);
+	--background: oklch(0.9702 0 0);
+	--foreground: var(--eclipse);
+}
+```
+
+**Get current theme variables:**
+
+```bash
+node scripts/get_theme.mjs
+```
+
+**Color naming:**
+
+- Without suffix = background (e.g., `--accent`)
+- With `-foreground` = text color (e.g., `--accent-foreground`)
+
+**Theme switching:**
+
+```html
+<html class="dark" data-theme="dark"></html>
+```
+
+For detailed theming, fetch: `https://heroui.com/docs/react/getting-started/theming.mdx`

.agents/skills/heroui-react/scripts/get_component_docs.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * Get complete component documentation (MDX) for HeroUI v3 components.
+ *
+ * Usage:
+ *   node get_component_docs.mjs Button
+ *   node get_component_docs.mjs Button Card TextField
+ *
+ * Output:
+ *   MDX documentation including imports, usage, variants, props, examples
+ */
+
+const API_BASE = process.env.HEROUI_API_BASE || "https://mcp-api.heroui.com";
+const FALLBACK_BASE = "https://heroui.com";
+const APP_PARAM = "app=react-skills";
+
+/**
+ * Convert PascalCase to kebab-case.
+ */
+function toKebabCase(name) {
+  return name
+    .replace(/([a-z])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
+    .toLowerCase();
+}
+
+/**
+ * Fetch data from HeroUI API with app parameter for analytics.
+ */
+async function fetchApi(endpoint, method = "GET", body = null) {
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${API_BASE}${endpoint}${separator}${APP_PARAM}`;
+
+  try {
+    const options = {
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": "HeroUI-Skill/1.0",
+      },
+      method,
+      signal: AbortSignal.timeout(30000),
+    };
+
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+
+    if (!response.ok) {
+      return null;
+    }
+
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetch MDX directly from v3.heroui.com as fallback.
+ */
+async function fetchFallback(component) {
+  const kebabName = toKebabCase(component);
+  const url = `${FALLBACK_BASE}/docs/react/components/${kebabName}.mdx`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      return {component, error: `Failed to fetch docs for ${component}`};
+    }
+
+    const content = await response.text();
+
+    return {
+      component,
+      content,
+      contentType: "mdx",
+      source: "fallback",
+      url,
+    };
+  } catch {
+    return {component, error: `Failed to fetch docs for ${component}`};
+  }
+}
+
+/**
+ * Main function to get component documentation.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error("Usage: node get_component_docs.mjs <Component1> [Component2] ...");
+    console.error("Example: node get_component_docs.mjs Button Card");
+    process.exit(1);
+  }
+
+  const components = args;
+
+  // Try API first - use POST /v1/components/docs for batch requests
+  console.error(`# Fetching docs for: ${components.join(", ")}...`);
+  const data = await fetchApi("/v1/components/docs", "POST", {components});
+
+  if (data && data.results) {
+    // Output results
+    if (data.results.length === 1) {
+      // Single component - output content directly for easier reading
+      const result = data.results[0];
+
+      if (result.content) {
+        console.log(result.content);
+      } else if (result.error) {
+        console.error(`# Error for ${result.component}: ${result.error}`);
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(JSON.stringify(result, null, 2));
+      }
+    } else {
+      // Multiple components - output as JSON array
+      console.log(JSON.stringify(data, null, 2));
+    }
+
+    return;
+  }
+
+  // Fallback to individual component fetches
+  console.error("# API failed, using fallback...");
+  const results = [];
+
+  for (const component of components) {
+    const result = await fetchFallback(component);
+
+    results.push(result);
+  }
+
+  // Output results
+  if (results.length === 1) {
+    // Single component - output content directly for easier reading
+    const result = results[0];
+
+    if (result.content) {
+      console.log(result.content);
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+  } else {
+    // Multiple components - output as JSON array
+    console.log(JSON.stringify(results, null, 2));
+  }
+}
+
+main();

.agents/skills/heroui-react/scripts/get_docs.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * Get non-component HeroUI documentation (guides, theming, releases).
+ *
+ * Usage:
+ *   node get_docs.mjs /docs/react/getting-started/theming
+ *   node get_docs.mjs /docs/react/releases/v3-0-0-beta-3
+ *
+ * Output:
+ *   MDX documentation content
+ *
+ * Note: For component docs, use get_component_docs.mjs instead.
+ */
+
+const API_BASE = process.env.HEROUI_API_BASE || "https://mcp-api.heroui.com";
+const FALLBACK_BASE = "https://heroui.com";
+const APP_PARAM = "app=react-skills";
+
+/**
+ * Fetch documentation from HeroUI API.
+ * Uses v1 endpoint pattern: /v1/docs/:path
+ */
+async function fetchApi(path) {
+  // The v1 API expects path without /docs/ prefix
+  // Input: /docs/react/getting-started/theming
+  // API expects: react/getting-started/theming (route is /v1/docs/:path(*))
+  let apiPath = path.startsWith("/docs/")
+    ? path.slice(6) // Remove /docs/ prefix
+    : path.startsWith("/")
+      ? path.slice(1) // Remove leading /
+      : path;
+
+  const separator = "?";
+  const url = `${API_BASE}/v1/docs/${apiPath}${separator}${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      console.error(`# API Error: HTTP ${response.status}`);
+
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`# API Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Fetch MDX directly from v3.heroui.com as fallback.
+ */
+async function fetchFallback(path) {
+  // Ensure path starts with /docs and ends with .mdx
+  let cleanPath = path.replace(/^\//, "");
+
+  if (!cleanPath.endsWith(".mdx")) {
+    cleanPath = `${cleanPath}.mdx`;
+  }
+
+  const url = `${FALLBACK_BASE}/${cleanPath}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      return {error: `HTTP ${response.status}: ${response.statusText}`, path};
+    }
+
+    const content = await response.text();
+
+    return {
+      content,
+      contentType: "mdx",
+      path,
+      source: "fallback",
+      url,
+    };
+  } catch (error) {
+    return {error: `Fetch Error: ${error.message}`, path};
+  }
+}
+
+/**
+ * Main function to get documentation for specified path.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error("Usage: node get_docs.mjs <path>");
+    console.error("Example: node get_docs.mjs /docs/react/getting-started/theming");
+    console.error();
+    console.error("Available paths include:");
+    console.error("  /docs/react/getting-started/theming");
+    console.error("  /docs/react/getting-started/colors");
+    console.error("  /docs/react/getting-started/animations");
+    console.error("  /docs/react/releases/v3-0-0-beta-3");
+    console.error();
+    console.error("Note: For component docs, use get_component_docs.mjs instead.");
+    process.exit(1);
+  }
+
+  const path = args[0];
+
+  // Check if user is trying to get component docs
+  if (path.includes("/components/")) {
+    console.error("# Warning: Use get_component_docs.mjs for component documentation.");
+    const componentName = path.split("/").pop().replace(".mdx", "");
+    const titleCase = componentName.charAt(0).toUpperCase() + componentName.slice(1);
+
+    console.error(`# Example: node get_component_docs.mjs ${titleCase}`);
+  }
+
+  console.error(`# Fetching documentation for ${path}...`);
+
+  // Try API first
+  const data = await fetchApi(path);
+
+  if (data && data.content) {
+    data.source = "api";
+    console.log(data.content);
+
+    return;
+  }
+
+  // Fallback to direct fetch
+  console.error("# API failed, using fallback...");
+  const fallbackData = await fetchFallback(path);
+
+  if (fallbackData.content) {
+    console.log(fallbackData.content);
+  } else {
+    console.log(JSON.stringify(fallbackData, null, 2));
+    process.exit(1);
+  }
+}
+
+main();

.agents/skills/heroui-react/scripts/get_source.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * Get React/TypeScript source code implementation for HeroUI v3 components.
+ *
+ * Usage:
+ *   node get_source.mjs Button
+ *   node get_source.mjs Button Accordion Card
+ *
+ * Output:
+ *   Full TSX source code with GitHub URL for each component
+ */
+
+const API_BASE = process.env.HEROUI_API_BASE || "https://mcp-api.heroui.com";
+const GITHUB_RAW_BASE = "https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3";
+const APP_PARAM = "app=react-skills";
+
+/**
+ * Fetch data from HeroUI API with app parameter for analytics.
+ */
+async function fetchApi(endpoint, method = "GET", body = null) {
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${API_BASE}${endpoint}${separator}${APP_PARAM}`;
+
+  try {
+    const options = {
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": "HeroUI-Skill/1.0",
+      },
+      method,
+      signal: AbortSignal.timeout(30000),
+    };
+
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+
+    if (!response.ok) {
+      console.error(`# API Error: HTTP ${response.status}`);
+
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`# API Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Fetch source code directly from GitHub as fallback.
+ */
+async function fetchGithubFallback(component) {
+  // Try common patterns for component paths
+  const patterns = [
+    `packages/react/src/components/${component.toLowerCase()}/${component.toLowerCase()}.tsx`,
+    `packages/react/src/components/${component.toLowerCase()}/index.tsx`,
+  ];
+
+  for (const path of patterns) {
+    const url = `${GITHUB_RAW_BASE}/${path}`;
+
+    try {
+      const response = await fetch(url, {
+        headers: {"User-Agent": "HeroUI-Skill/1.0"},
+        signal: AbortSignal.timeout(30000),
+      });
+
+      if (response.ok) {
+        const content = await response.text();
+
+        return {
+          component,
+          filePath: path,
+          githubUrl: `https://github.com/heroui-inc/heroui/blob/v3/${path}`,
+          source: "fallback",
+          sourceCode: content,
+        };
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return {component, error: `Failed to fetch source for ${component}`};
+}
+
+/**
+ * Main function to get source code for specified components.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error("Usage: node get_source.mjs <Component1> [Component2] ...");
+    console.error("Example: node get_source.mjs Button Accordion");
+    process.exit(1);
+  }
+
+  const components = args;
+
+  // Try API first
+  console.error(`# Fetching source code for: ${components.join(", ")}...`);
+  const data = await fetchApi("/v1/components/source", "POST", {components});
+
+  if (data && data.results) {
+    for (const result of data.results) {
+      result.source = "api";
+    }
+
+    // Output results
+    if (data.results.length === 1) {
+      const result = data.results[0];
+
+      if (result.sourceCode) {
+        console.log(`// File: ${result.filePath || "unknown"}`);
+        console.log(`// GitHub: ${result.githubUrl || "unknown"}`);
+        console.log();
+        console.log(result.sourceCode);
+      } else {
+        console.log(JSON.stringify(result, null, 2));
+      }
+    } else {
+      console.log(JSON.stringify(data, null, 2));
+    }
+
+    return;
+  }
+
+  // Fallback to GitHub direct fetch
+  console.error("# API failed, using GitHub fallback...");
+  const results = [];
+
+  for (const component of components) {
+    const result = await fetchGithubFallback(component);
+
+    results.push(result);
+  }
+
+  if (results.length === 1) {
+    const result = results[0];
+
+    if (result.sourceCode) {
+      console.log(`// File: ${result.filePath || "unknown"}`);
+      console.log(`// GitHub: ${result.githubUrl || "unknown"}`);
+      console.log();
+      console.log(result.sourceCode);
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+  } else {
+    console.log(JSON.stringify({results}, null, 2));
+  }
+}
+
+main();

.agents/skills/heroui-react/scripts/get_styles.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * Get CSS styles (BEM classes) for HeroUI v3 components.
+ *
+ * Usage:
+ *   node get_styles.mjs Button
+ *   node get_styles.mjs Button Card Chip
+ *
+ * Output:
+ *   CSS file content with BEM classes and GitHub URL for each component
+ */
+
+const API_BASE = process.env.HEROUI_API_BASE || "https://mcp-api.heroui.com";
+const GITHUB_RAW_BASE = "https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3";
+const APP_PARAM = "app=react-skills";
+
+/**
+ * Fetch data from HeroUI API with app parameter for analytics.
+ */
+async function fetchApi(endpoint, method = "GET", body = null) {
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${API_BASE}${endpoint}${separator}${APP_PARAM}`;
+
+  try {
+    const options = {
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": "HeroUI-Skill/1.0",
+      },
+      method,
+      signal: AbortSignal.timeout(30000),
+    };
+
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+
+    if (!response.ok) {
+      console.error(`# API Error: HTTP ${response.status}`);
+
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`# API Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Fetch CSS styles directly from GitHub as fallback.
+ */
+async function fetchGithubFallback(component) {
+  // Try common patterns for style paths
+  const patterns = [
+    `packages/styles/src/components/${component.toLowerCase()}.css`,
+    `packages/styles/components/${component.toLowerCase()}.css`,
+  ];
+
+  for (const path of patterns) {
+    const url = `${GITHUB_RAW_BASE}/${path}`;
+
+    try {
+      const response = await fetch(url, {
+        headers: {"User-Agent": "HeroUI-Skill/1.0"},
+        signal: AbortSignal.timeout(30000),
+      });
+
+      if (response.ok) {
+        const content = await response.text();
+
+        return {
+          component,
+          filePath: path,
+          githubUrl: `https://github.com/heroui-inc/heroui/blob/v3/${path}`,
+          source: "fallback",
+          stylesCode: content,
+        };
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return {component, error: `Failed to fetch styles for ${component}`};
+}
+
+/**
+ * Main function to get CSS styles for specified components.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error("Usage: node get_styles.mjs <Component1> [Component2] ...");
+    console.error("Example: node get_styles.mjs Button Card");
+    process.exit(1);
+  }
+
+  const components = args;
+
+  // Try API first
+  console.error(`# Fetching styles for: ${components.join(", ")}...`);
+  const data = await fetchApi("/v1/components/styles", "POST", {components});
+
+  if (data && data.results) {
+    for (const result of data.results) {
+      result.source = "api";
+    }
+
+    // Output results
+    if (data.results.length === 1) {
+      const result = data.results[0];
+
+      if (result.stylesCode) {
+        console.log(`/* File: ${result.filePath || "unknown"} */`);
+        console.log(`/* GitHub: ${result.githubUrl || "unknown"} */`);
+        console.log();
+        console.log(result.stylesCode);
+      } else {
+        console.log(JSON.stringify(result, null, 2));
+      }
+    } else {
+      console.log(JSON.stringify(data, null, 2));
+    }
+
+    return;
+  }
+
+  // Fallback to GitHub direct fetch
+  console.error("# API failed, using GitHub fallback...");
+  const results = [];
+
+  for (const component of components) {
+    const result = await fetchGithubFallback(component);
+
+    results.push(result);
+  }
+
+  if (results.length === 1) {
+    const result = results[0];
+
+    if (result.stylesCode) {
+      console.log(`/* File: ${result.filePath || "unknown"} */`);
+      console.log(`/* GitHub: ${result.githubUrl || "unknown"} */`);
+      console.log();
+      console.log(result.stylesCode);
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+  } else {
+    console.log(JSON.stringify({results}, null, 2));
+  }
+}
+
+main();

.agents/skills/heroui-react/scripts/get_theme.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * Get theme variables and design tokens for HeroUI v3.
+ *
+ * Usage:
+ *   node get_theme.mjs
+ *
+ * Output:
+ *   Theme variables organized by common/light/dark with oklch color format
+ */
+
+const API_BASE = process.env.HEROUI_API_BASE || "https://mcp-api.heroui.com";
+const APP_PARAM = "app=react-skills";
+
+// Fallback theme reference when API is unavailable
+const FALLBACK_THEME = {
+  common: {
+    base: [
+      {name: "--font-sans", value: "ui-sans-serif, system-ui, sans-serif"},
+      {name: "--font-mono", value: "ui-monospace, monospace"},
+      {name: "--radius-sm", value: "0.375rem"},
+      {name: "--radius-md", value: "0.5rem"},
+      {name: "--radius-lg", value: "0.75rem"},
+      {name: "--radius-full", value: "9999px"},
+    ],
+    calculated: [{name: "--spacing-unit", value: "0.25rem"}],
+  },
+  dark: {
+    semantic: [
+      {name: "--color-background", value: "oklch(14.5% 0 0)"},
+      {name: "--color-foreground", value: "oklch(98.4% 0 0)"},
+      {name: "--color-accent", value: "oklch(55.1% 0.228 264.1)"},
+      {name: "--color-danger", value: "oklch(63.7% 0.237 25.3)"},
+      {name: "--color-success", value: "oklch(76.5% 0.177 163.2)"},
+      {name: "--color-warning", value: "oklch(79.5% 0.184 86.0)"},
+    ],
+  },
+  latestVersion: "3.0.0-beta",
+  light: {
+    semantic: [
+      {name: "--color-background", value: "oklch(100% 0 0)"},
+      {name: "--color-foreground", value: "oklch(14.5% 0 0)"},
+      {name: "--color-accent", value: "oklch(55.1% 0.228 264.1)"},
+      {name: "--color-danger", value: "oklch(63.7% 0.237 25.3)"},
+      {name: "--color-success", value: "oklch(76.5% 0.177 163.2)"},
+      {name: "--color-warning", value: "oklch(79.5% 0.184 86.0)"},
+    ],
+  },
+  note: "This is a fallback. For complete theme variables, ensure the API is accessible.",
+  source: "fallback",
+  theme: "default",
+};
+
+/**
+ * Fetch data from HeroUI API with app parameter for analytics.
+ */
+async function fetchApi(endpoint) {
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${API_BASE}${endpoint}${separator}${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      console.error(`# API Error: HTTP ${response.status}`);
+
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`# API Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Format theme variables for display.
+ */
+function formatVariables(variables) {
+  const lines = [];
+
+  for (const variable of variables) {
+    const name = variable.name || "";
+    const value = variable.value || "";
+    const desc = variable.description || "";
+
+    if (desc) {
+      lines.push(`  ${name}: ${value}; /* ${desc} */`);
+    } else {
+      lines.push(`  ${name}: ${value};`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Main function to get theme variables.
+ */
+async function main() {
+  console.error("# Fetching theme variables...");
+
+  const rawData = await fetchApi("/v1/themes/variables?theme=default");
+
+  let data;
+  let version;
+
+  if (!rawData) {
+    console.error("# API failed, using fallback theme reference...");
+    data = FALLBACK_THEME;
+    version = FALLBACK_THEME.latestVersion || "unknown";
+  } else {
+    // Handle API response format: { themes: [...], latestVersion: "..." }
+    if (rawData.themes && rawData.themes.length > 0) {
+      data = rawData.themes[0]; // Get first theme (default)
+      version = rawData.latestVersion || rawData.version || "unknown";
+    } else {
+      // Direct format
+      data = rawData;
+      version = rawData.latestVersion || "unknown";
+    }
+  }
+
+  // Output as formatted CSS-like structure for readability
+  console.log("/* HeroUI v3 Theme Variables */");
+  console.log(`/* Theme: ${data.theme || "default"} */`);
+  console.log(`/* Version: ${version} */`);
+  console.log();
+
+  // Common variables
+  if (data.common) {
+    console.log(":root {");
+    console.log("  /* Base Variables */");
+    if (data.common.base) {
+      console.log(formatVariables(data.common.base));
+    }
+    console.log();
+    console.log("  /* Calculated Variables */");
+    if (data.common.calculated) {
+      console.log(formatVariables(data.common.calculated));
+    }
+    console.log("}");
+    console.log();
+  }
+
+  // Light mode
+  if (data.light) {
+    console.log(":root, [data-theme='light'] {");
+    console.log("  /* Light Mode Semantic Variables */");
+    if (data.light.semantic) {
+      console.log(formatVariables(data.light.semantic));
+    }
+    console.log("}");
+    console.log();
+  }
+
+  // Dark mode
+  if (data.dark) {
+    console.log("[data-theme='dark'] {");
+    console.log("  /* Dark Mode Semantic Variables */");
+    if (data.dark.semantic) {
+      console.log(formatVariables(data.dark.semantic));
+    }
+    console.log("}");
+  }
+
+  // Also output raw JSON to stderr for programmatic use
+  console.error("\n# Raw JSON output:");
+  console.error(JSON.stringify(rawData || data, null, 2));
+}
+
+main();

.agents/skills/heroui-react/scripts/list_components.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * List all available HeroUI v3 components.
+ *
+ * Usage:
+ *   node list_components.mjs
+ *
+ * Output:
+ *   JSON with components array, latestVersion, and count
+ */
+
+const API_BASE = process.env.HEROUI_API_BASE || "https://mcp-api.heroui.com";
+const APP_PARAM = "app=react-skills";
+const LLMS_TXT_URL = "https://heroui.com/react/llms.txt";
+
+/**
+ * Fetch data from HeroUI API with app parameter for analytics.
+ */
+async function fetchApi(endpoint) {
+  const separator = endpoint.includes("?") ? "&" : "?";
+  const url = `${API_BASE}${endpoint}${separator}${APP_PARAM}`;
+
+  try {
+    const response = await fetch(url, {
+      headers: {"User-Agent": "HeroUI-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      console.error(`HTTP Error ${response.status}: ${response.statusText}`);
+
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`API Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Fetch component list from llms.txt fallback URL.
+ */
+async function fetchFallback() {
+  try {
+    const response = await fetch(LLMS_TXT_URL, {
+      headers: {"User-Agent": "HeroUI-Skill/1.0"},
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const content = await response.text();
+
+    // Parse markdown to extract component names from pattern: - [ComponentName](url)
+    // Look for links under the Components section (### Components)
+    const components = [];
+    let inComponentsSection = false;
+
+    for (const line of content.split("\n")) {
+      // Check if we're entering the Components section (uses ### header)
+      if (line.trim() === "### Components") {
+        inComponentsSection = true;
+        continue;
+      }
+
+      // Check if we're leaving the Components section (another ### header)
+      if (inComponentsSection && line.trim().startsWith("### ")) {
+        break;
+      }
+
+      // Extract component name from markdown link pattern
+      // Match: - [ComponentName](https://www.heroui.com/docs/react/components/component-name)
+      // Skip "All Components" which links to /components without a specific component
+      if (inComponentsSection) {
+        const match = line.match(
+          /^\s*-\s*\[([^\]]+)\]\(https:\/\/www\.heroui\.com\/docs\/react\/components\/[a-z]/,
+        );
+
+        if (match) {
+          components.push(match[1]);
+        }
+      }
+    }
+
+    if (components.length > 0) {
+      console.error(`# Using fallback: ${LLMS_TXT_URL}`);
+
+      return {
+        components: components.sort(),
+        count: components.length,
+        latestVersion: "unknown",
+      };
+    }
+
+    return null;
+  } catch (error) {
+    console.error(`Fallback Error: ${error.message}`);
+
+    return null;
+  }
+}
+
+/**
+ * Main function to list all available HeroUI v3 components.
+ */
+async function main() {
+  let data = await fetchApi("/v1/components");
+
+  // Check if API returned valid data with components
+  if (!data || !data.components || data.components.length === 0) {
+    console.error("# API returned no components, trying fallback...");
+    data = await fetchFallback();
+  }
+
+  if (!data || !data.components || data.components.length === 0) {
+    console.error("Error: Failed to fetch component list from API and fallback");
+    process.exit(1);
+  }
+
+  // Output formatted JSON
+  console.log(JSON.stringify(data, null, 2));
+
+  // Print summary to stderr for human readability
+  console.error(
+    `\n# Found ${data.components.length} components (${data.latestVersion || "unknown"})`,
+  );
+}
+
+main();

.claude/skills/heroui-migration

@@ -0,0 +1 @@
+../../.agents/skills/heroui-migration

.claude/skills/heroui-native

@@ -0,0 +1 @@
+../../.agents/skills/heroui-native

.claude/skills/heroui-react

@@ -0,0 +1 @@
+../../.agents/skills/heroui-react

.github/workflows/release.yml

@@ -35,6 +35,11 @@ jobs:
         id: meta
         run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
 
+      # QEMU lets the amd64 runner emulate arm64 so the images below build for
+      # both platforms (Intel + Apple Silicon self-hosters).
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
       - name: Set up Buildx
         uses: docker/setup-buildx-action@v3
 
@@ -49,6 +54,7 @@ jobs:
         with:
           context: ./backend
           push: true
+          platforms: linux/amd64,linux/arm64
           tags: |
             ${{ env.REGISTRY_NAMESPACE }}/temetro-backend:${{ steps.meta.outputs.version }}
             ${{ env.REGISTRY_NAMESPACE }}/temetro-backend:latest
@@ -58,6 +64,7 @@ jobs:
         with:
           context: ./frontend
           push: true
+          platforms: linux/amd64,linux/arm64
           tags: |
             ${{ env.REGISTRY_NAMESPACE }}/temetro-frontend:${{ steps.meta.outputs.version }}
             ${{ env.REGISTRY_NAMESPACE }}/temetro-frontend:latest

.mcp.json

@@ -6,6 +6,16 @@
         "shadcn@latest",
         "mcp"
       ]
+    },
+    "XcodeBuildMCP": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "xcodebuildmcp@latest",
+        "mcp"
+      ],
+      "env": {}
     }
   }
-}
+}

CHANGELOG.md

@@ -7,6 +7,276 @@ for how releases are cut and published.
 
 ## [Unreleased]
 
+## [0.12.0] — 2026-07-09
+
+### Added
+- **In-dialog "Sync to wallet" stepper.** When a clinician adds or edits a record for a
+  wallet-linked patient — invoice, appointment, prescription, patient demographics, or an AI
+  scribe note — the create/edit dialog shows a two-step stepper: after saving, step 2 offers to
+  push the change to the patient's wallet (reusing `pushWalletUpdate` + approval polling). Shared
+  `useWalletSync` hook and `DialogStepper` / `WalletSyncStep` components under `components/wallet/`.
+  Patients without a linked wallet see the old close-on-save behaviour.
+
+### Changed
+- **Appointment & invoice date pickers block past dates.** The new-appointment date picker disables
+  days before today; the invoice issue-date picker does too, with an opt-in **Back-date** checkbox
+  for recording genuinely older invoices (edit mode keeps existing past dates).
+- **Patient Portal wallet link is identified by wallet number only.** The portal `link` action no
+  longer asks the wallet app for a name + file number — it resolves the file the clinic already
+  paired the wallet number to (`services/portal.ts#linkWallet`), returning a friendly 404 when the
+  wallet isn't paired yet.
+
+### Removed
+- **Stale Settings "Features" section.** Dropped the inert "patient-owned storage" / "require signed
+  records" toggles (and their unused i18n keys) that did nothing.
+
+## [0.11.0] — 2026-07-09
+
+### Added
+- **Patient Portal over the Temetro Network relay + wallet linking.** The wallet app now reaches a
+  clinic's Patient Portal through the relay instead of a direct HTTP API, so it works from a real
+  phone. New `services/portal.ts` (clinic info, doctors, availability, wallet linking, conflict-aware
+  booking, results, downloadable lab files) runs behind a `portal:request` hub handler
+  (`backend/src/services/relay-client.ts`). A new nullable `patients.wallet_number` column stores the
+  link, and `walletNumberForPatient` resolves through it so clinic→wallet pushes work after a portal
+  link (not only after a permanent share). `GET /api/portal/:clinic/link` returns the relay-based
+  pairing descriptor (clinic signing key + relay URL).
+- **Portal "Link my wallet" option.** The Patient Portal kiosk adds a third card that shows a QR the
+  wallet app scans to link over the relay (`components/portal/portal-kiosk.tsx`).
+- **Appointments & invoices reach the wallet.** Clinic→wallet pushes now include the patient's
+  appointments and invoices in the sealed bundle, so they show up in the wallet app.
+- **Clinic location reverse-geocoding.** "Use my current location" now fills address / city /
+  country (OpenStreetMap Nominatim), not just latitude / longitude (`lib/geocode.ts`).
+
+### Fixed
+- **Patient Portal QR was unreachable from a phone.** Settings → Signing now encodes a
+  `temetro-portal:` pairing URI (relay URL + clinic signing key) instead of a `localhost` API URL, so
+  the wallet app can actually connect (`components/settings/settings-portal.tsx`).
+- **Arabic (RTL) sidebar.** The collapse arrow and notification bell now stack **above** the nav
+  icons instead of being pinned to the opposite edge; the toggle glyph mirrors and the notifications
+  popover opens toward the content side (`components/sidebar-02/app-sidebar.tsx`,
+  `components/ui/sidebar.tsx`, `components/sidebar-02/nav-notifications.tsx`).
+
+## [0.10.0] — 2026-07-07
+
+### Added
+- **Patient Portal doctor picker & availability.** The portal now lists the clinic's doctors and
+  books against a chosen provider, showing only free slots. New public endpoints
+  `GET /api/portal/:clinic/doctors` and `GET /api/portal/:clinic/availability?provider=&date=`
+  (display-safe fields only), and `POST /api/portal/:clinic/appointments` accepts an optional
+  `provider` (`backend/src/routes/portal.ts`). The existing 409 conflict check stays authoritative.
+- **Patient Portal links in Settings.** Settings → Signing → Patient Portal adds **open**, **copy
+  link**, and **QR code** actions (`components/settings/settings-portal.tsx`); the QR carries the
+  backend base (`?api=`) so the patient wallet app can book natively when it scans it.
+- **Clinic location "Use my current location".** The location editor fills map coordinates from the
+  browser's geolocation (`components/settings/settings-location.tsx`).
+- **Wallet app native Patient Portal.** Scanning a clinic's portal QR opens a native booking screen
+  (doctor list → free-slot picker → confirm) in the patient wallet app.
+
+### Fixed
+- **Arabic (RTL) layout.** The sidebar now anchors to the **right** for RTL locales and the toggle
+  switch mirrors correctly, instead of leaving the shell misaligned
+  (`components/sidebar-02/app-sidebar.tsx`, `components/ui/switch.tsx`).
+- **Wallet app:** record-card **bottom sheet no longer freezes** the app (dropped the per-frame
+  animated blur overlay for HeroUI's built-in overlay); **Reset wallet** now confirms in a native
+  HeroUI dialog with Liquid Glass actions; fixed the **white edge flash** on screen transitions in
+  dark mode; the home/onboarding/register **logo** is now the Temetro mark.
+
+### Changed
+- New i18n keys (`settings.portal.*`, geolocation strings) are translated into **all** shipped
+  locales (en, de, fr, ar, so).
+
+## [0.9.0] — 2026-07-06
+
+### Added
+- **Patient blood type & phone number.** The patient record now carries a `bloodType` (e.g. `O+`)
+  and a `phone` number. Both are shown in the record sheet and chat summary card and are editable in
+  the add/edit patient form. `phone` is a demographic/contact field (visible to and editable by the
+  **reception** role); `bloodType` is treated as clinical PHI and is **redacted for reception** (like
+  allergies/vitals). New columns `patients.phone` / `patients.blood_type` (migration `0033`).
+- **Clinic location setting.** A new org-scoped `clinic_settings` table (migration `0034`) stores the
+  clinic's address (address / city / country) plus optional map coordinates (latitude / longitude),
+  set in **Settings → Signing → Clinic location** (owner/admin only). New endpoints
+  `GET /api/clinic/settings` (any clinician) and `PUT /api/clinic/location` (owner/admin). This will
+  be surfaced in the patient wallet app to show a clinic's location.
+
+### Changed
+- New i18n keys for the above are translated into **all** shipped locales (en, de, fr, ar, so), per
+  the coverage rule now documented in `frontend/CLAUDE.md`.
+
+## [0.8.2] — 2026-07-05
+
+### Fixed
+- **`RELAY_URL` now defaults to the hosted relay** (`https://network.temetro.com`) instead of
+  `http://localhost:8080`. The old default silently failed for anyone who joined the network without
+  explicitly setting `RELAY_URL` — the backend's hub connection could never reach the relay (inside
+  Docker `localhost` is the container itself), so it never authenticated and QR pairing generated a
+  QR pointing at an unreachable `localhost`. Self-hosters running their own relay still override
+  `RELAY_URL`. Updated `.env.example` accordingly.
+
+### Changed
+- Generating a pairing QR (`POST /api/patients/wallet/pair`) now ensures the clinic's relay hub is
+  connected before pre-registering the request, so the routing is set up even if the connection was
+  opened lazily.
+
+### Fixed
+- **QR "scan to connect" pairing** was broken by the multi-clinic relay routing (v0.8.0): pairing
+  has no wallet number, so the clinic never sent a `wallet:send` to register the request, and the
+  relay rejected the scanning device's response as "unknown or expired". The clinic now
+  **pre-registers** the pairing request with the relay (a new `hub:expect { requestId }` event on
+  `POST /api/patients/wallet/pair`), so the device's response routes back correctly. On hub
+  (re)connect the backend re-registers its still-pending requests, so routing also survives a relay
+  restart. `POST /pair` now also requires the clinic to have joined the network (clear 409 instead of
+  a dead QR), surfaced in the import dialog.
+
+### Added
+- **Multi-clinic Temetro Network.** The relay now serves many self-hosted clinics at once. Each
+  clinic authenticates to the `/hub` namespace by **signing a challenge with its own Ed25519 clinic
+  signing key** (`services/signing.ts`) — a per-clinic identity, not a shared password — and the
+  relay routes every device response back to only the clinic that originated the request (keyed by
+  `requestId`), so clinics never see each other's traffic. `wallet:online` is fanned out only to
+  clinics with pending work for that wallet.
+- **"Join Temetro Network" opt-in.** A per-clinic toggle in **Settings → Signing** (backed by
+  `clinic_signing_keys.network_enabled`, `GET`/`PUT /api/signing/network`, owner/admin only). Off by
+  default; enabling opens the clinic's relay connection, disabling tears it down. Wallet
+  import/push endpoints return **409** while a clinic hasn't joined. Localised in all five languages.
+
+### Changed
+- **The backend keeps one authenticated relay connection per network-enabled org**
+  (`services/relay-client.ts` — `connectOrg`/`disconnectOrg`, a `hubs` map keyed by `orgId`), instead
+  of a single shared-token connection. `emitToWallet`/`sendToWallet` now take an `orgId`, and the
+  offline-flush (`pendingUpdatesForWallet`) is org-scoped.
+- **`RELAY_TOKEN` is now optional/legacy.** Clinics authenticate with their signing key, so an open
+  relay needs no shared secret; `RELAY_TOKEN` only gates an optional *private* relay.
+
+## [0.7.0] — 2026-07-05
+
+### Added
+- **Temetro Network** — a standalone, high-performance **relay** (Rust + Axum + socketioxide) that
+  connects the backend to patient wallet apps, in its own repo
+  ([github.com/temetro/temetro-network](https://github.com/temetro/temetro-network)) and deployable
+  on Railway. It replaces the flaky Cloudflare quick-tunnel that used to expose the backend's
+  embedded `/wallet` Socket.io namespace to phones. The relay is a **dumb, stateless pipe**: a
+  `/wallet` namespace for devices (challenge/Ed25519-signature auth, room keyed by wallet number)
+  and a `RELAY_TOKEN`-authenticated `/hub` namespace for the backend. It forwards sealed ciphertext
+  verbatim, keeps no database, and its only crypto is verifying a device's auth signature (proven
+  byte-for-byte compatible with `wallet-crypto.ts`).
+
+### Changed
+- **The backend is now a client of the relay, not the wallet server.** The `/wallet` Socket.io
+  namespace was removed from `src/realtime.ts`; a new `src/services/relay-client.ts` connects to the
+  relay's `/hub` (`emitToWallet` delegates to its `sendToWallet`), handles device responses
+  (`wallet:share-response` / `wallet:update-response` / `wallet:revoke`) and flushes missed updates on
+  `wallet:online` — calling the same `wallet-share` / `wallet-updates` services as before. New
+  `RELAY_URL` + `RELAY_TOKEN` env vars; the wallet-import QR now points at `RELAY_URL`.
+
+## [0.6.0] — 2026-07-04
+
+### Added
+- **Read-only FHIR R4 server** — temetro can now be a FHIR **server**, not just a client.
+  A new endpoint tree at **`/fhir`** (mounted outside `/api`, bearer-only) exposes each
+  clinic's records as FHIR R4: **Patient**, **Observation** (labs + synthesized vital signs),
+  **AllergyIntolerance**, **Condition**, **MedicationRequest**, **Encounter** and
+  **Appointment**, plus an unauthenticated **`GET /fhir/metadata`** CapabilityStatement.
+  Searches return searchset `Bundle`s with `_count`/`_offset` pagination and self/next/prev
+  links. Because temetro stores free-text clinical values, every `CodeableConcept` is
+  **text-only** (no SNOMED/LOINC) and patients carry an **age** extension rather than a
+  `birthDate` — documented in the CapabilityStatement and API docs.
+- **Per-clinic FHIR API keys** — machine-to-machine auth via `Authorization: Bearer tmf_…`.
+  Keys are created/revoked under **Settings → Integrations → FHIR server** (owner/admin),
+  **SHA-256-hashed** at rest, and shown **once** at creation. Every FHIR request is
+  org-scoped (no cross-clinic reads) and written to the activity log with the key name and
+  result count. New `fhir_api_keys` table, `middleware/fhir-auth.ts`, the
+  `services/fhir-server/` mapping module (queries, resources, bundle, capability, keys), the
+  `/fhir` router, and `GET/POST/DELETE /api/integrations/fhir-server/keys`. New `fhirServer`
+  locale namespace across all five languages.
+
+## [0.5.0] — 2026-07-03
+
+### Added
+- **Clinic → wallet record-update push** — a clinician can push an updated record to a
+  **wallet-linked** patient (a permanent, approved share). The record snapshot is **signed**
+  with the clinic's Ed25519 key and **sealed** to the wallet's X25519 key (derived from its
+  Ed25519 wallet number via the birational map — verified byte-for-byte against the wallet's
+  own derivation), stored `pending`, and delivered over the `/wallet` relay live **and** on
+  the wallet's next authenticated connect (so an offline phone catches up). The patient
+  reviews it in a **pending-updates inbox** and approves/denies; the wallet signs its
+  decision, the backend verifies it, and the on-device record is replaced only on approval.
+  The wallet **pins** the clinic key (TOFU) and warns on a key change. New
+  `POST /api/patients/wallet/push`, `GET /api/patients/wallet/{link/:fileNumber,updates,updates/:id}`,
+  `walletRecordUpdates` table + service, `wallet:update-request` / `wallet:update-response`
+  relay events, a "Push to wallet" dialog with live status, and a "Sent updates" list under
+  Settings → Signing. New `walletPush` / `walletUpdatesList` locale namespaces across all five
+  languages. (The wallet app half ships in the sibling `temetro-app` repo.)
+
+## [0.4.0] — 2026-07-03
+
+### Added
+- **Ambient AI visit scribe** — a **Record visit** action on the patient sheet turns a
+  clinician↔patient conversation into a draft **SOAP** encounter note. Record with the
+  microphone (`MediaRecorder`, stored as an auditable patient attachment) or paste a
+  transcript; the backend transcribes via the user's **OpenAI (Whisper)** or **Gemini**
+  key, de-identifies the transcript + patient context through **Veil**, and the model
+  drafts a structured note that the clinician **reviews and edits before saving** — the
+  same write-approval gate as the chat agent. New `POST /api/scribe/{transcribe,draft,save}`
+  (`backend/src/routes/scribe.ts`, `services/ai/transcribe.ts`), a `veil.redactText()`
+  free-text redactor, and an `appendEncounter` service that adds one note without touching
+  the rest of the record. Gated by `patient:write` + the clinic AI policy (reception and
+  disabled-AI accounts don't see it). New `scribe` locale namespace across all five
+  languages. Drafting also works with local Ollama from a pasted transcript.
+
+## [0.3.0] — 2026-07-02
+
+### Added
+- **Three new interface languages** — Somali (`so`), Arabic (`ar`) and German
+  (`de`) join English and French, selectable in Settings → Profile → Language.
+  Each locale carries a full translation of the ~1,660 UI strings, with native
+  names shown in the selector (Soomaali, العربية, Deutsch).
+- **Right-to-left (RTL) support** — selecting Arabic sets `dir="rtl"` on the
+  document (applied before first paint via an inline script, so no flash), flips
+  physical spacing/alignment to logical CSS utilities, mirrors directional icons,
+  and loads an Arabic-capable typeface (IBM Plex Sans Arabic) appended to the
+  font stack for per-character fallback.
+- **Language roams across devices** — the chosen language is persisted to the
+  per-user `user_settings` preferences and re-applied on sign-in, with
+  localStorage remaining the offline source of truth.
+- **`frontend/scripts/check-locales.mjs`** (+ `npm run check-locales`) — a parity
+  check that fails on missing/extra keys or `{{placeholder}}` mismatches across
+  locales and warns when Arabic count-keys lack the full CLDR plural forms.
+
+## [0.2.5] — 2026-07-01
+
+### Fixed
+- **Multi-arch Docker images** — the `release` workflow now builds and publishes
+  `khalidxv/temetro-backend` and `khalidxv/temetro-frontend` for both
+  `linux/amd64` and `linux/arm64`. Previously the images were amd64-only, so
+  `docker compose pull` on Apple Silicon failed with *no matching manifest for
+  linux/arm64/v8* and fell back to building from source.
+
+### Changed
+- **Language switcher** in Settings → Profile is now a **select** that asks for
+  confirmation before switching the interface language, instead of applying the
+  change instantly on a button tap.
+
+## [0.2.4] — 2026-06-29
+
+### Added
+- **Pagination** on the Activity and Invoices pages (10 per page), matching the
+  Patients page, via a shared `ListPagination` component.
+- **French (Français)** interface language, with a language switcher in
+  Settings → Profile. The choice persists on the device.
+- **"Check for updates"** button in Settings → About & updates that forces a
+  fresh check.
+
+### Changed
+- **Update detection** now reads the latest version from **Docker Hub** image
+  tags (the channel clinics actually pull), falling back to the GitHub release
+  if Docker Hub is unreachable. This fixes "About & updates" showing *Up to
+  date* when a newer image was already published.
+- **docker compose** host ports are now configurable (`BACKEND_PORT`,
+  `FRONTEND_PORT`, `ADMINER_PORT`, alongside `POSTGRES_PORT`) so a port clash on
+  `docker compose up -d` can be resolved from `.env` without editing the file.
+
 ## [0.2.3] — 2026-06-29
 
 ### Fixed

CLAUDE.md

@@ -27,12 +27,13 @@ repository (published as `temetro`).
 > "Patient wallet app" below) and an end-to-end **encrypted share / patient-approval** flow:
 > clinics hold a real **Ed25519 signing key** (Settings → Signing, `backend/src/services/signing.ts`),
 > and "Import from a patient app" on the Patients page relays an encrypted request to the wallet over
-> a **`/wallet` Socket.io namespace**, the patient approves on their phone, and the sealed record is
-> imported (with optional **temporary share + auto-delete**). See `backend/src/routes/{signing,patients-wallet}.ts`.
+> the **Temetro Network** relay (see below), the patient approves on their phone, and the sealed record
+> is imported (with optional **temporary share + auto-delete**). Clinic→wallet **record-update push**
+> and **QR pairing** are built too. See `backend/src/routes/{signing,patients-wallet}.ts`.
 >
-> **Still vision, not built:** clinic→wallet push of signed record updates, in-app record editing,
-> QR pairing, and cryptographic time-boxing of temporary shares. The AI chat is still **mock replies**.
-> Email verification is wired but currently **not enforced** at sign-in (see `backend/CLAUDE.md`).
+> **Still vision, not built:** in-app record editing and cryptographic time-boxing of temporary
+> shares. The AI chat is still **mock replies**. Email verification is wired but currently **not
+> enforced** at sign-in (see `backend/CLAUDE.md`).
 
 ## Patient wallet app (sibling repo `~/Desktop/temetro-app`)
 
@@ -47,6 +48,28 @@ here means keys + data live on the patient's device and the relay only ever forw
 is **not** a literal blockchain (records are off-chain, which is also what lets a temporary share be
 deleted). Commit/push that app inside its own repo, separately from this one.
 
+## Temetro Network (sibling repo/folder `~/Desktop/Temetro-network`)
+
+The **relay** that connects this backend to patient wallet apps. It is its **own git repo** on the
+Desktop (folder `~/Desktop/Temetro-network`, pushed to `github.com/temetro/temetro-network`), **not**
+in this monorepo — a standalone **Rust + Axum + socketioxide** service meant to run always-on (e.g.
+on **Railway**). It replaces the old flaky Cloudflare quick-tunnel that used to expose the backend's
+embedded `/wallet` Socket.io namespace to phones.
+
+It is a **dumb, stateless pipe**: two Socket.io namespaces — `/wallet` for devices
+(challenge/Ed25519-signature auth, room keyed by wallet number) and `/hub` for this backend
+(`RELAY_TOKEN`-authenticated). Devices and the backend both connect to it; it **forwards sealed
+ciphertext verbatim** and never opens bundles or touches a database. Its only crypto is verifying a
+device's auth signature (mirrors `backend/src/lib/wallet-crypto.ts`). The backend connects to it as a
+`/hub` client via `backend/src/services/relay-client.ts` (its `sendToWallet` is what `emitToWallet`
+now calls); configure with `RELAY_URL` + `RELAY_TOKEN`. Commit/push that service inside its own repo,
+separately from this one.
+
+> **Note:** in this sandbox the `~/Desktop/Temetro-network` folder blocks directory enumeration
+> (`ls`/`getcwd`/git inside it return EPERM) though plain file writes work. Develop/build/commit it
+> in an accessible copy and mirror the tree in with `tar`; drive git there via
+> `GIT_DIR`/`GIT_WORK_TREE` from an accessible cwd.
+
 ## Layout
 
 `frontend/` and `backend/` were previously separate per-folder git repos; they have been **merged
@@ -80,6 +103,11 @@ accurate (e.g. a new backend route needs an `content/docs/api/*.mdx` entry; a UI
 in the matching guide; status changes belong in the roadmap). Commit docs changes inside that
 repo, separately from this one.
 
+**Every release must also get a dated entry in the docs changelog**
+(`content/docs/changelog.mdx`, newest first) — not just the monorepo `CHANGELOG.md`. When you cut a
+version (see "Always release after pushing"), add a matching, user-facing section to that page in the
+same session so `../temetro/docs` never falls behind the shipped version.
+
 ## Running the stack
 
 From `backend/`: ensure a `.env` exists (`cp .env.example .env`, then set `BETTER_AUTH_SECRET` via

README.md

@@ -73,9 +73,11 @@ missing secrets on first start. Then open:
 Prefer to **build from source** (for development)? Use `docker compose up
 --build` instead. Migrations apply automatically on backend start.
 
-> **Port conflict?** If another Postgres holds host port `5432`, set
-> `POSTGRES_PORT` (e.g. `5433`) in `backend/.env`. The app still talks to
-> Postgres internally on `db:5432`; only the published host port changes.
+> **Port conflict?** If host ports `5432`, `4000` or `3000` are already in use,
+> set `POSTGRES_PORT`, `BACKEND_PORT` and/or `FRONTEND_PORT` (e.g. `5433` /
+> `4001` / `3001`) in `backend/.env`. The services still talk to each other on
+> their internal ports (`db:5432`, `backend:4000`); only the published host
+> ports change.
 
 ### Access from other computers (hospital LAN)
 

backend/.env.example

@@ -26,17 +26,29 @@ FRONTEND_URL=http://localhost:3000
 PORT=4000
 NODE_ENV=development
 
-# Host port Postgres is published on by docker compose. Change it if 5432 is
-# already in use on your machine (the app still talks to Postgres internally).
+# Host ports docker compose publishes. Change any that are already in use on
+# this machine (the services still talk to each other on their internal ports).
 POSTGRES_PORT=5432
+BACKEND_PORT=4000
+FRONTEND_PORT=3000
 
-# --- Patient wallet relay -------------------------------------------------
-# The URL baked into the QR a patient scans to import their record. Their phone
-# must be able to reach it — so localhost will NOT work from a real device. If
-# unset, the backend derives it from the request host (fine when you open the
-# web app over your LAN IP, e.g. http://192.168.1.20:3000). Otherwise set it
-# explicitly to a phone-reachable address: your machine's LAN IP or a public
-# tunnel URL.
+# --- Temetro Network relay ------------------------------------------------
+# The standalone relay (github.com/temetro/temetro-network) that connects this
+# backend to patient phones. Deploy it (e.g. on Railway) and point both this
+# backend and the wallet app at it. RELAY_URL is the relay's public URL (also
+# baked into the QR a patient scans). This clinic authenticates to the relay's
+# /hub with its own Ed25519 signing key, so no shared secret is needed.
+# RELAY_TOKEN is OPTIONAL/LEGACY — set it only for a private relay that also
+# gates on a shared token (then use the SAME value here and on the relay).
+# Defaults to the hosted relay (https://network.temetro.com) when unset, so
+# "Join Temetro Network" works out of the box; set RELAY_URL only to point at
+# your own relay. Do NOT use http://localhost — inside Docker that's the
+# container itself and the relay connection will silently fail.
+RELAY_URL=https://network.temetro.com
+RELAY_TOKEN=
+
+# (Legacy, pre-relay self-hosting.) A phone-reachable URL for the QR when NOT
+# using the Temetro Network relay. RELAY_URL takes precedence over this.
 # PUBLIC_RELAY_URL=http://192.168.1.20:4000
 
 # --- Email (optional) -----------------------------------------------------

backend/CLAUDE.md

@@ -60,6 +60,18 @@ No test runner is configured. Verify by running the stack (`docker compose up`)
 - **Real-time** lives in **`src/realtime.ts`** — a Socket.io server attached to the same HTTP server
   in `index.ts`; the handshake reuses Better Auth's `getSession`. Other modules push via
   `emitToUser` / `emitToConversation` (no direct socket import, so no circular deps).
+- **Patient-wallet relay** is **no longer hosted here.** Devices connect to the standalone **Temetro
+  Network** service (`~/Desktop/Temetro-network`, see root `CLAUDE.md`), which is **multi-clinic**.
+  This backend connects to it as a `/hub` client in **`src/services/relay-client.ts`**, keeping **one
+  authenticated connection per network-enabled org** (`hubs` map keyed by `orgId`). Each org
+  authenticates by signing the relay's `hub:challenge` with its clinic signing key
+  (`signWithClinicKey`) — no shared `RELAY_TOKEN` needed (it's now optional/legacy, only for a
+  private relay). `emitToWallet(orgId, …)` (realtime.ts) delegates to `sendToWallet(orgId, …)`, and
+  device responses (`wallet:share-response` / `wallet:update-response` / `wallet:revoke`) +
+  `wallet:online` replay are handled per-org there, calling the same `wallet-share` /
+  `wallet-updates` services the old `/wallet` namespace did. A clinic opts in via **"Join Temetro
+  Network"** (Settings → Signing → `PUT /api/signing/network`, `clinic_signing_keys.network_enabled`);
+  `connectOrg`/`disconnectOrg` open/close its connection, and wallet routes 409 when it's off.
 - **`src/lib/email.ts`** — `sendEmail` logs links to the console when SMTP is unset.
 
 ## Gotchas / conventions

backend/docker-compose.yml

@@ -25,6 +25,12 @@
 #
 # Optional DB browser (Adminer) lives behind a profile:
 #   docker compose --profile tools up adminer   # http://localhost:8080
+#
+# Host ports are configurable to avoid clashing with software already running on
+# this machine. Override any of them in a .env file (or inline), e.g.:
+#   POSTGRES_PORT=5433  BACKEND_PORT=4001  FRONTEND_PORT=3001  docker compose up -d
+# Only the published host port changes; the services still talk to each other on
+# their internal ports (db:5432, backend:4000).
 
 services:
   db:
@@ -62,6 +68,11 @@ services:
       BETTER_AUTH_URL: http://localhost:4000
       FRONTEND_URL: http://localhost:3000
       PORT: "4000"
+      # Temetro Network relay (github.com/temetro/temetro-network). Set RELAY_URL
+      # to your deployed relay's public URL and RELAY_TOKEN to the shared secret
+      # you configured on it — both are required for patient-wallet import.
+      RELAY_URL: ${RELAY_URL:-}
+      RELAY_TOKEN: ${RELAY_TOKEN:-}
       NODE_ENV: production
       # Uploaded patient/lab files live here, on the temetro_uploads volume.
       UPLOAD_DIR: /var/lib/temetro/uploads
@@ -76,7 +87,8 @@ services:
       # Persists uploaded files across restarts/rebuilds.
       - temetro_uploads:/var/lib/temetro/uploads
     ports:
-      - "4000:4000"
+      # Host port is configurable to avoid clashing with an existing service.
+      - "${BACKEND_PORT:-4000}:4000"
 
   frontend:
     image: khalidxv/temetro-frontend:${TEMETRO_VERSION:-latest}
@@ -90,7 +102,8 @@ services:
     depends_on:
       - backend
     ports:
-      - "3000:3000"
+      # Host port is configurable to avoid clashing with an existing service.
+      - "${FRONTEND_PORT:-3000}:3000"
 
   adminer:
     image: adminer:5
@@ -99,7 +112,7 @@ services:
     depends_on:
       - db
     ports:
-      - "8080:8080"
+      - "${ADMINER_PORT:-8080}:8080"
 
 volumes:
   temetro_pgdata:

backend/drizzle/0030_medical_blur.sql

@@ -0,0 +1,21 @@
+CREATE TABLE "wallet_record_updates" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organization_id" text NOT NULL,
+	"created_by" text NOT NULL,
+	"file_number" text NOT NULL,
+	"wallet_number" text NOT NULL,
+	"status" text DEFAULT 'pending' NOT NULL,
+	"payload_sealed" text NOT NULL,
+	"clinic_signature" text NOT NULL,
+	"clinic_public_key" text NOT NULL,
+	"clinic_fingerprint" text NOT NULL,
+	"changes" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"delivered_at" timestamp,
+	"resolved_at" timestamp
+);
+--> statement-breakpoint
+ALTER TABLE "wallet_record_updates" ADD CONSTRAINT "wallet_record_updates_organization_id_organization_id_fk" FOREIGN KEY ("organization_id") REFERENCES "public"."organization"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "wallet_record_updates" ADD CONSTRAINT "wallet_record_updates_created_by_user_id_fk" FOREIGN KEY ("created_by") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "wallet_updates_org_idx" ON "wallet_record_updates" USING btree ("organization_id");--> statement-breakpoint
+CREATE INDEX "wallet_updates_wallet_idx" ON "wallet_record_updates" USING btree ("wallet_number");

backend/drizzle/0031_stiff_gateway.sql

@@ -0,0 +1,15 @@
+CREATE TABLE "fhir_api_keys" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organization_id" text NOT NULL,
+	"name" text NOT NULL,
+	"key_hash" text NOT NULL,
+	"created_by" text,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"last_used_at" timestamp,
+	"revoked_at" timestamp,
+	CONSTRAINT "fhir_api_keys_key_hash_unique" UNIQUE("key_hash")
+);
+--> statement-breakpoint
+ALTER TABLE "fhir_api_keys" ADD CONSTRAINT "fhir_api_keys_organization_id_organization_id_fk" FOREIGN KEY ("organization_id") REFERENCES "public"."organization"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "fhir_api_keys" ADD CONSTRAINT "fhir_api_keys_created_by_user_id_fk" FOREIGN KEY ("created_by") REFERENCES "public"."user"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "fhir_api_keys_org_idx" ON "fhir_api_keys" USING btree ("organization_id");

backend/drizzle/0032_closed_dakota_north.sql

@@ -0,0 +1 @@
+ALTER TABLE "clinic_signing_keys" ADD COLUMN "network_enabled" boolean DEFAULT false NOT NULL;

backend/drizzle/0033_ambitious_reavers.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "patients" ADD COLUMN "phone" text DEFAULT '' NOT NULL;--> statement-breakpoint
+ALTER TABLE "patients" ADD COLUMN "blood_type" text DEFAULT '' NOT NULL;

backend/drizzle/0034_chunky_blacklash.sql

@@ -0,0 +1,12 @@
+CREATE TABLE "clinic_settings" (
+	"organization_id" text PRIMARY KEY NOT NULL,
+	"address" text DEFAULT '' NOT NULL,
+	"city" text DEFAULT '' NOT NULL,
+	"country" text DEFAULT '' NOT NULL,
+	"latitude" double precision,
+	"longitude" double precision,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "clinic_settings" ADD CONSTRAINT "clinic_settings_organization_id_organization_id_fk" FOREIGN KEY ("organization_id") REFERENCES "public"."organization"("id") ON DELETE cascade ON UPDATE no action;

backend/drizzle/0035_slippery_retro_girl.sql

@@ -0,0 +1 @@
+ALTER TABLE "patients" ADD COLUMN "wallet_number" text;

backend/drizzle/meta/_journal.json

@@ -211,6 +211,48 @@
       "when": 1782057030557,
       "tag": "0029_tiny_starhawk",
       "breakpoints": true
+    },
+    {
+      "idx": 30,
+      "version": "7",
+      "when": 1783093188246,
+      "tag": "0030_medical_blur",
+      "breakpoints": true
+    },
+    {
+      "idx": 31,
+      "version": "7",
+      "when": 1783117115021,
+      "tag": "0031_stiff_gateway",
+      "breakpoints": true
+    },
+    {
+      "idx": 32,
+      "version": "7",
+      "when": 1783263738631,
+      "tag": "0032_closed_dakota_north",
+      "breakpoints": true
+    },
+    {
+      "idx": 33,
+      "version": "7",
+      "when": 1783362745730,
+      "tag": "0033_ambitious_reavers",
+      "breakpoints": true
+    },
+    {
+      "idx": 34,
+      "version": "7",
+      "when": 1783363217049,
+      "tag": "0034_chunky_blacklash",
+      "breakpoints": true
+    },
+    {
+      "idx": 35,
+      "version": "7",
+      "when": 1783530491321,
+      "tag": "0035_slippery_retro_girl",
+      "breakpoints": true
     }
   ]
 }

backend/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "temetro-backend",
-  "version": "0.1.0",
+  "version": "0.6.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "temetro-backend",
-      "version": "0.1.0",
+      "version": "0.6.0",
       "license": "MIT",
       "dependencies": {
         "@ai-sdk/anthropic": "^3.0.84",
@@ -28,6 +28,7 @@
         "nodemailer": "^8.0.10",
         "pg": "^8.21.0",
         "socket.io": "^4.8.3",
+        "socket.io-client": "^4.8.3",
         "zod": "^4.4.3"
       },
       "devDependencies": {
@@ -3339,6 +3340,40 @@
         "node": ">=10.2.0"
       }
     },
+    "node_modules/engine.io-client": {
+      "version": "6.6.6",
+      "resolved": "https://registry.npmjs.org/engine.io-client/-/engine.io-client-6.6.6.tgz",
+      "integrity": "sha512-iY6QdftLQ9pyiPoX082bpf/u1UewnOaJrtJIF9T0++QB34lZrj0uP+Q/bj8AlUsAxqhnkTV2BS8SBZSxOmoV5Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@socket.io/component-emitter": "~3.1.0",
+        "debug": "~4.4.1",
+        "engine.io-parser": "~5.2.1",
+        "ws": "~8.21.0",
+        "xmlhttprequest-ssl": "~2.1.1"
+      }
+    },
+    "node_modules/engine.io-client/node_modules/ws": {
+      "version": "8.21.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz",
+      "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/engine.io-parser": {
       "version": "5.2.3",
       "resolved": "https://registry.npmjs.org/engine.io-parser/-/engine.io-parser-5.2.3.tgz",
@@ -4947,6 +4982,21 @@
         "ws": "~8.20.1"
       }
     },
+    "node_modules/socket.io-client": {
+      "version": "4.8.3",
+      "resolved": "https://registry.npmjs.org/socket.io-client/-/socket.io-client-4.8.3.tgz",
+      "integrity": "sha512-uP0bpjWrjQmUt5DTHq9RuoCBdFJF10cdX9X+a368j/Ft0wmaVgxlrjvK3kjvgCODOMMOz9lcaRzxmso0bTWZ/g==",
+      "license": "MIT",
+      "dependencies": {
+        "@socket.io/component-emitter": "~3.1.0",
+        "debug": "~4.4.1",
+        "engine.io-client": "~6.6.1",
+        "socket.io-parser": "~4.2.4"
+      },
+      "engines": {
+        "node": ">=10.0.0"
+      }
+    },
     "node_modules/socket.io-parser": {
       "version": "4.2.6",
       "resolved": "https://registry.npmjs.org/socket.io-parser/-/socket.io-parser-4.2.6.tgz",
@@ -5779,6 +5829,14 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/xmlhttprequest-ssl": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/xmlhttprequest-ssl/-/xmlhttprequest-ssl-2.1.2.tgz",
+      "integrity": "sha512-TEU+nJVUUnA4CYJFLvK5X9AOeH4KvDvhIfm0vV1GaQRtchnG0hgK5p8hw/xjv8cunWYCsiPCSDzObPyhEwq3KQ==",
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
     "node_modules/xtend": {
       "version": "4.0.2",
       "resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz",

backend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "temetro-backend",
-  "version": "0.2.3",
+  "version": "0.12.0",
   "private": true,
   "type": "module",
   "description": "temetro backend — Express + Postgres API with Better Auth (email/password, organizations) and org-scoped patient records.",
@@ -41,6 +41,7 @@
     "nodemailer": "^8.0.10",
     "pg": "^8.21.0",
     "socket.io": "^4.8.3",
+    "socket.io-client": "^4.8.3",
     "zod": "^4.4.3"
   },
   "devDependencies": {

backend/src/db/schema/clinic-settings.ts

@@ -0,0 +1,25 @@
+import { doublePrecision, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+
+import { organization } from "./auth.js";
+
+// Per-clinic (organization) settings. Currently holds the clinic's physical
+// location — a free-text address plus optional map coordinates — set in
+// Settings → Location by an owner/admin and surfaced to patients in the wallet
+// app later (e.g. a map pin for a clinic that shared a record). One row per org
+// (PK = organizationId), mirroring `clinic_signing_keys`.
+export const clinicSettings = pgTable("clinic_settings", {
+  organizationId: text("organization_id")
+    .primaryKey()
+    .references(() => organization.id, { onDelete: "cascade" }),
+  address: text("address").notNull().default(""),
+  city: text("city").notNull().default(""),
+  country: text("country").notNull().default(""),
+  // Optional map coordinates (WGS84). Null until the clinic sets them.
+  latitude: doublePrecision("latitude"),
+  longitude: doublePrecision("longitude"),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at")
+    .defaultNow()
+    .$onUpdate(() => new Date())
+    .notNull(),
+});

backend/src/db/schema/fhir-keys.ts

@@ -0,0 +1,30 @@
+import { index, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+
+import { organization, user } from "./auth.js";
+
+// Per-organization API keys for the read-only FHIR R4 server (`/fhir`). These
+// are machine-to-machine credentials (no Better Auth session): a caller sends
+// `Authorization: Bearer tmf_<secret>` and every query is scoped to the owning
+// clinic. Only the SHA-256 *hash* of the secret is stored — the plaintext key is
+// shown once at creation and never again. Revoking sets `revokedAt` (kept for
+// audit rather than hard-deleted).
+export const fhirApiKeys = pgTable(
+  "fhir_api_keys",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    organizationId: text("organization_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    name: text("name").notNull(),
+    // Hex SHA-256 of the full `tmf_…` secret. Unique so a lookup is a single
+    // indexed probe and two keys can never collide.
+    keyHash: text("key_hash").notNull().unique(),
+    createdBy: text("created_by").references(() => user.id, {
+      onDelete: "set null",
+    }),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    lastUsedAt: timestamp("last_used_at"),
+    revokedAt: timestamp("revoked_at"),
+  },
+  (t) => [index("fhir_api_keys_org_idx").on(t.organizationId)],
+);

backend/src/db/schema/index.ts

@@ -20,4 +20,7 @@ export * from "./integrations.js";
 export * from "./staff-profile.js";
 export * from "./meetings.js";
 export * from "./signing.js";
+export * from "./clinic-settings.js";
 export * from "./wallet-share.js";
+export * from "./wallet-updates.js";
+export * from "./fhir-keys.js";

backend/src/db/schema/patients.ts

@@ -36,6 +36,11 @@ export const patients = pgTable(
     pcp: text("pcp").notNull(),
     status: text("status").$type<PatientStatus>().notNull(),
     initials: text("initials").notNull(),
+    // Contact + clinical demographics. `phone` is a contact/registration field
+    // (reception may read/write it); `bloodType` is clinical (redacted for the
+    // reception role, like allergies/vitals).
+    phone: text("phone").notNull().default(""),
+    bloodType: text("blood_type").notNull().default(""),
     alerts: jsonb("alerts").$type<string[]>().notNull(),
     vitalsBp: text("vitals_bp").notNull(),
     vitalsHr: text("vitals_hr").notNull(),
@@ -59,6 +64,10 @@ export const patients = pgTable(
     // and passes, a scheduled sweep hard-deletes the row (services/wallet-share).
     shareOrigin: text("share_origin").$type<"wallet">(),
     shareExpiresAt: timestamp("share_expires_at"),
+    // The patient's wallet number (tmw_…) once they link their wallet from the
+    // Patient Portal. Lets clinic→wallet pushes and portal actions resolve to
+    // this file directly (services/portal.ts, wallet-updates.ts). Nullable.
+    walletNumber: text("wallet_number"),
     createdBy: text("created_by").references(() => user.id, {
       onDelete: "set null",
     }),

backend/src/db/schema/signing.ts

@@ -1,4 +1,4 @@
-import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
+import { boolean, pgTable, text, timestamp } from "drizzle-orm/pg-core";
 
 import { organization } from "./auth.js";
 
@@ -16,6 +16,11 @@ export const clinicSigningKeys = pgTable("clinic_signing_keys", {
   fingerprint: text("fingerprint").notNull(),
   // Encrypted (lib/crypto.ts) hex of the Ed25519 private key.
   privateKeyEnc: text("private_key_enc").notNull(),
+  // Whether this clinic has joined the Temetro Network relay ("Join Temetro
+  // Network" in Settings → Signing). Off by default: only when enabled does the
+  // backend open this clinic's relay hub connection and expose wallet features.
+  // The relay identity *is* this signing key, so the flag lives on the same row.
+  networkEnabled: boolean("network_enabled").notNull().default(false),
   createdAt: timestamp("created_at").defaultNow().notNull(),
   rotatedAt: timestamp("rotated_at"),
 });

backend/src/db/schema/wallet-updates.ts

@@ -0,0 +1,53 @@
+import { index, jsonb, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+
+import { organization, user } from "./auth.js";
+
+export type WalletUpdateStatus =
+  | "pending"
+  | "delivered"
+  | "approved"
+  | "denied";
+
+// One row per clinic→wallet record-update push. When a clinician edits a
+// wallet-linked patient they can push the updated record to the patient's app;
+// it lands here as `pending`, is sealed to the wallet's (X25519-from-Ed25519)
+// key and signed with the clinic's Ed25519 key. The relay delivers it live if
+// the device is connected, and again on the wallet's next authenticated connect
+// (so an offline phone still receives it). The patient reviews the change,
+// verifies the clinic signature, and approves/denies in-app — only then is the
+// on-device record replaced. The clinic polls `status` for delivery/approval.
+export const walletRecordUpdates = pgTable(
+  "wallet_record_updates",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    organizationId: text("organization_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    createdBy: text("created_by")
+      .notNull()
+      .references(() => user.id, { onDelete: "cascade" }),
+    fileNumber: text("file_number").notNull(),
+    walletNumber: text("wallet_number").notNull(),
+    status: text("status")
+      .$type<WalletUpdateStatus>()
+      .notNull()
+      .default("pending"),
+    // base64 sealed box of the full updated patient snapshot (sealed to the
+    // wallet's derived X25519 key).
+    payloadSealed: text("payload_sealed").notNull(),
+    // The clinic's Ed25519 signature over the plaintext bundle bytes + its
+    // public key + fingerprint, so the wallet can verify provenance (TOFU pin).
+    clinicSignature: text("clinic_signature").notNull(),
+    clinicPublicKey: text("clinic_public_key").notNull(),
+    clinicFingerprint: text("clinic_fingerprint").notNull(),
+    // Human-readable summary of what changed (shown in the wallet inbox).
+    changes: jsonb("changes").$type<string[]>().notNull().default([]),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    deliveredAt: timestamp("delivered_at"),
+    resolvedAt: timestamp("resolved_at"),
+  },
+  (t) => [
+    index("wallet_updates_org_idx").on(t.organizationId),
+    index("wallet_updates_wallet_idx").on(t.walletNumber),
+  ],
+);

backend/src/env.ts

@@ -28,6 +28,19 @@ const schema = z.object({
   // Overrides the version reported by GET /api/version. Normally derived from
   // package.json; the release pipeline can pin it explicitly.
   APP_VERSION: z.string().optional(),
+  // Temetro Network relay (github.com/temetro/temetro-network). Both this
+  // backend and patient phones connect to it; it routes the encrypted wallet
+  // messages between them. RELAY_URL is the relay's public URL (also baked into
+  // the QR a patient scans). Each clinic authenticates to the relay's /hub with
+  // its own Ed25519 signing key, so no shared secret is needed. RELAY_TOKEN is
+  // now *optional/legacy* — set it only for a private relay that also gates on a
+  // shared token (must then match the relay's RELAY_TOKEN).
+  //
+  // Defaults to the hosted relay so "Join Temetro Network" works out of the box;
+  // override only when running your own relay. (A `localhost` default silently
+  // fails inside Docker, where localhost is the container itself.)
+  RELAY_URL: z.string().min(1).default("https://network.temetro.com"),
+  RELAY_TOKEN: z.string().default(""),
   // Public, device-reachable URL of this backend's wallet relay, baked into the
   // QR a patient scans. Optional — when unset we derive it from the request host
   // (so opening the web app over the LAN yields a reachable LAN URL).
@@ -80,6 +93,9 @@ if (env.NODE_ENV === "production") {
     );
     process.exit(1);
   }
+  // RELAY_TOKEN is optional now: clinics authenticate to the relay with their
+  // own Ed25519 signing key, so an unset token is the normal "open relay" case —
+  // no warning needed.
 }
 
 export const isProd = env.NODE_ENV === "production";

backend/src/index.ts

@@ -16,8 +16,10 @@ import { analyticsRouter } from "./routes/analytics.js";
 import { attachmentsRouter } from "./routes/attachments.js";
 import { appointmentsRouter } from "./routes/appointments.js";
 import { chatRouter } from "./routes/chat.js";
+import { clinicRouter } from "./routes/clinic.js";
 import { conversationsRouter } from "./routes/conversations.js";
 import { dispensesRouter } from "./routes/dispenses.js";
+import { fhirRouter } from "./routes/fhir.js";
 import { integrationsRouter } from "./routes/integrations.js";
 import { inventoryRouter } from "./routes/inventory.js";
 import { invoicesRouter } from "./routes/invoices.js";
@@ -28,12 +30,14 @@ import { patientsRouter } from "./routes/patients.js";
 import { patientsWalletRouter } from "./routes/patients-wallet.js";
 import { portalRouter } from "./routes/portal.js";
 import { prescriptionsRouter } from "./routes/prescriptions.js";
+import { scribeRouter } from "./routes/scribe.js";
 import { settingsRouter } from "./routes/settings.js";
 import { signingRouter } from "./routes/signing.js";
 import { staffRouter } from "./routes/staff.js";
 import { networkRouter } from "./routes/network.js";
 import { tasksRouter } from "./routes/tasks.js";
 import { versionRouter } from "./routes/version.js";
+import { initRelayClient } from "./services/relay-client.js";
 import { beginQuickTunnelDiscovery } from "./services/relay-url.js";
 import { sweepExpiredShares } from "./services/wallet-share.js";
 
@@ -87,6 +91,7 @@ app.use("/api/network", networkRouter);
 app.use("/api/patients/wallet", patientsWalletRouter);
 app.use("/api/patients", patientsRouter);
 app.use("/api/signing", signingRouter);
+app.use("/api/clinic", clinicRouter);
 app.use("/api/attachments", attachmentsRouter);
 app.use("/api/notes", notesRouter);
 app.use("/api/appointments", appointmentsRouter);
@@ -104,10 +109,16 @@ app.use("/api/notifications", notificationsRouter);
 app.use("/api/settings", settingsRouter);
 app.use("/api/ai", aiRouter);
 app.use("/api/chat", chatRouter);
+app.use("/api/scribe", scribeRouter);
 app.use("/api/integrations", integrationsRouter);
 app.use("/api/portal", portalRouter);
 app.use("/api/auth-helpers", authHelpersRouter);
 
+// Read-only FHIR R4 server, mounted OUTSIDE /api. Bearer-only (per-clinic API
+// keys), no Better Auth session/cookie coupling. Errors are FHIR
+// OperationOutcomes, not our standard error JSON.
+app.use("/fhir", fhirRouter);
+
 app.use(notFound);
 app.use(errorHandler);
 
@@ -115,6 +126,11 @@ app.use(errorHandler);
 const server = createServer(app);
 initRealtime(server);
 
+// Connect to the Temetro Network relay (the device-facing hub). Patient phones
+// no longer connect to this backend directly — they connect to the relay, and
+// we push to / receive from them over its /hub namespace.
+initRelayClient();
+
 // Sweep expired temporary patient-wallet shares (auto-delete) every 5 minutes.
 const SHARE_SWEEP_INTERVAL = 5 * 60 * 1000;
 setInterval(() => {
@@ -144,8 +160,9 @@ server.listen(env.PORT, () => {
   console.log(`  • chat:     /api/chat  (LLM agent)`);
   console.log(`  • integr.:  /api/integrations  (FHIR / e-Rx / claims)`);
   console.log(`  • portal:   /api/portal  (public clinic kiosk)`);
+  console.log(`  • fhir:     /fhir  (read-only FHIR R4 server, API-key auth)`);
   console.log(`  • signing:  /api/signing  (Ed25519 clinic key)`);
-  console.log(`  • wallet:   /api/patients/wallet  (+ /wallet socket relay)`);
+  console.log(`  • wallet:   /api/patients/wallet  (via Temetro Network relay: ${env.RELAY_URL})`);
 });
 
 // Dockerized off-network testing: learn our public Cloudflare quick-tunnel URL

backend/src/lib/patient-validation.ts

@@ -105,6 +105,10 @@ export const patientInputSchema = z
     ),
     status: z.enum(["active", "inpatient", "discharged"]).default("active"),
     initials: z.string().trim().max(4).default(""),
+    phone: z.string().trim().max(30).default(""),
+    bloodType: z
+      .enum(["A+", "A-", "B+", "B-", "AB+", "AB-", "O+", "O-", ""])
+      .default(""),
     allergies: z.array(allergySchema).default([]),
     alerts: z.array(z.string()).default([]),
     medications: z.array(medicationSchema).default([]),

backend/src/lib/wallet-x25519.ts

@@ -0,0 +1,49 @@
+import { bytesToHex } from "@noble/hashes/utils.js";
+
+// Convert an Ed25519 public key to the matching X25519 (Montgomery) public key,
+// so the clinic can `seal()` a record update to a wallet that only publishes an
+// Ed25519 identity (its wallet number). The patient wallet derives the matching
+// X25519 *private* key from its Ed25519 seed (SHA-512 clamp) to `open()` it —
+// this file MUST stay byte-for-byte compatible with the wallet app's
+// src/lib/crypto.ts. @noble/curves does not export edwardsToMontgomery in the
+// pinned version, so the birational map u = (1 + y) / (1 - y) mod p is done here
+// with BigInt. Verified: edPubToMontU(A) === x25519.getPublicKey(edClamp(seed)).
+
+const P = 2n ** 255n - 19n;
+
+function modpow(base: bigint, exp: bigint, mod: bigint): bigint {
+  let result = 1n;
+  let b = base % mod;
+  let e = exp;
+  while (e > 0n) {
+    if (e & 1n) result = (result * b) % mod;
+    b = (b * b) % mod;
+    e >>= 1n;
+  }
+  return result;
+}
+
+// Modular inverse via Fermat's little theorem (p is prime).
+function inv(a: bigint): bigint {
+  return modpow(((a % P) + P) % P, P - 2n, P);
+}
+
+// Ed25519 public key (compressed, little-endian y with the x-sign in the high
+// bit) → X25519 u-coordinate, returned as 32-byte little-endian hex.
+export function ed25519PubToX25519Hex(edPub: Uint8Array): string {
+  if (edPub.length !== 32) throw new Error("Ed25519 public key must be 32 bytes.");
+  const bytes = edPub.slice();
+  bytes[31] = (bytes[31] as number) & 0x7f; // clear the x sign bit
+  let y = 0n;
+  for (let i = 31; i >= 0; i--) y = (y << 8n) | BigInt(bytes[i] as number);
+  y %= P;
+  // u = (1 + y) / (1 - y)  (mod p)
+  const u = ((1n + y) * inv((1n - y + P) % P)) % P;
+  const out = new Uint8Array(32);
+  let v = u;
+  for (let i = 0; i < 32; i++) {
+    out[i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  return bytesToHex(out);
+}

backend/src/middleware/fhir-auth.ts

@@ -0,0 +1,49 @@
+import type { NextFunction, Request, Response } from "express";
+
+import { resolveKey } from "../services/fhir-server/keys.js";
+import {
+  FHIR_CONTENT_TYPE,
+  operationOutcome,
+} from "../services/fhir-server/outcome.js";
+
+// Bearer-token auth for the read-only FHIR server. Unlike the rest of the API
+// (Better Auth session cookies), the `/fhir` endpoints authenticate with a
+// per-clinic API key: `Authorization: Bearer tmf_<secret>`. On success the
+// caller's organization is attached to `req.organizationId` and every downstream
+// query is scoped to it. Failures return a FHIR OperationOutcome, not our
+// standard error JSON.
+export async function requireFhirKey(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): Promise<void> {
+  const header = req.headers.authorization ?? "";
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+  const secret = match?.[1]?.trim();
+
+  const unauthorized = (diagnostics: string) => {
+    res
+      .status(401)
+      .type(FHIR_CONTENT_TYPE)
+      .set("WWW-Authenticate", "Bearer")
+      .json(operationOutcome("error", "login", diagnostics));
+  };
+
+  if (!secret) {
+    unauthorized("Missing bearer token. Send Authorization: Bearer tmf_…");
+    return;
+  }
+
+  try {
+    const resolved = await resolveKey(secret);
+    if (!resolved) {
+      unauthorized("Invalid or revoked API key.");
+      return;
+    }
+    req.organizationId = resolved.orgId;
+    req.fhirKey = { id: resolved.keyId, name: resolved.keyName };
+    next();
+  } catch (err) {
+    next(err);
+  }
+}

backend/src/realtime.ts

@@ -1,16 +1,14 @@
 import type { Server as HttpServer } from "node:http";
 
 import { fromNodeHeaders } from "better-auth/node";
-import { bytesToHex, randomBytes, utf8ToBytes } from "@noble/hashes/utils.js";
 import { Server, type Socket } from "socket.io";
 
 import { auth } from "./auth.js";
 import { env } from "./env.js";
-import { decodeWalletNumber, verifySignature } from "./lib/wallet-crypto.js";
 import * as meetings from "./services/meetings.js";
 import * as messaging from "./services/messaging.js";
 import { createNotification } from "./services/notifications.js";
-import * as walletShare from "./services/wallet-share.js";
+import { sendToWallet } from "./services/relay-client.js";
 import type { MessageAttachment } from "./types/messaging.js";
 
 let io: Server | null = null;
@@ -19,7 +17,6 @@ const userRoom = (userId: string) => `user:${userId}`;
 const convRoom = (conversationId: string) => `conv:${conversationId}`;
 const callRoom = (roomId: string) => `call:${roomId}`;
 const orgRoom = (orgId: string) => `org:${orgId}`;
-const walletRoom = (walletNumber: string) => `wallet:${walletNumber}`;
 
 // Mesh WebRTC tops out around four peers (each sends its stream to every other);
 // past that the room is closed to new joiners.
@@ -43,15 +40,18 @@ export function emitToConversation(
   io?.to(convRoom(conversationId)).emit(event, data);
 }
 
-// Relay an end-to-end-encrypted message to a patient wallet device (the /wallet
-// namespace, room keyed by wallet number). The relay only ever forwards
-// ciphertext — it cannot read the record bundle.
+// Relay an end-to-end-encrypted message to a patient wallet device. Devices no
+// longer connect to this server directly — they connect to the standalone
+// Temetro Network relay, which forwards to the room keyed by wallet number. We
+// push over the relay's /hub namespace (see services/relay-client.ts). The
+// relay only ever forwards ciphertext — it cannot read the record bundle.
 export function emitToWallet(
+  orgId: string,
   walletNumber: string,
   event: string,
   data: unknown,
 ): void {
-  io?.of("/wallet").to(walletRoom(walletNumber)).emit(event, data);
+  sendToWallet(orgId, walletNumber, event, data);
 }
 
 type Ack = (response: { ok: boolean; [key: string]: unknown }) => void;
@@ -285,106 +285,5 @@ export function initRealtime(httpServer: HttpServer): Server {
     });
   });
 
-  // --- Patient wallet relay (/wallet namespace) ----------------------------
-  // Devices have no clinic session, so this namespace is NOT cookie-gated.
-  // Instead a device proves control of its wallet keypair: the server issues a
-  // random challenge, the device signs it with its Ed25519 key, and only then
-  // may it join its own wallet room. The relay forwards encrypted share
-  // requests/responses without ever reading the record bundle.
-  const walletNs = io.of("/wallet");
-  walletNs.on("connection", (socket: Socket) => {
-    const challenge = bytesToHex(randomBytes(32));
-    socket.data.challenge = challenge;
-    socket.data.walletNumber = null as string | null;
-    socket.emit("wallet:challenge", { challenge });
-
-    socket.on(
-      "wallet:auth",
-      (payload: { walletNumber?: string; signature?: string }, ack?: Ack) => {
-        try {
-          const walletNumber = String(payload?.walletNumber ?? "");
-          const signature = String(payload?.signature ?? "");
-          const publicKey = decodeWalletNumber(walletNumber);
-          const ok = verifySignature(
-            publicKey,
-            signature,
-            utf8ToBytes(socket.data.challenge as string),
-          );
-          if (!ok) {
-            ack?.({ ok: false });
-            return;
-          }
-          socket.data.walletNumber = walletNumber;
-          socket.join(walletRoom(walletNumber));
-          ack?.({ ok: true });
-        } catch {
-          ack?.({ ok: false });
-        }
-      },
-    );
-
-    // The patient approved/denied a share on their device; the sealed bundle (if
-    // approved) rides along and is decrypted + verified server-side.
-    socket.on(
-      "wallet:share-response",
-      async (
-        payload: {
-          requestId?: string;
-          walletNumber?: string;
-          decision?: "approved" | "denied";
-          sealed?: string;
-          signature?: string;
-        },
-        ack?: Ack,
-      ) => {
-        try {
-          if (
-            !socket.data.walletNumber ||
-            socket.data.walletNumber !== payload?.walletNumber
-          ) {
-            ack?.({ ok: false });
-            return;
-          }
-          const view = await walletShare.applyShareResponse(
-            String(payload?.requestId ?? ""),
-            String(payload?.walletNumber ?? ""),
-            payload?.decision === "approved" ? "approved" : "denied",
-            payload?.sealed,
-            payload?.signature,
-          );
-          ack?.({ ok: !!view });
-        } catch (err) {
-          ack?.({ ok: false, error: (err as Error).message });
-        }
-      },
-    );
-
-    // The patient revoked a previously shared record; delete it from the clinic.
-    socket.on(
-      "wallet:revoke",
-      async (
-        payload: { requestId?: string; walletNumber?: string },
-        ack?: Ack,
-      ) => {
-        try {
-          if (
-            !socket.data.walletNumber ||
-            socket.data.walletNumber !== payload?.walletNumber
-          ) {
-            ack?.({ ok: false });
-            return;
-          }
-          const result = await walletShare.revokeShare(
-            String(payload?.requestId ?? ""),
-            String(payload?.walletNumber ?? ""),
-          );
-          ack?.({ ok: !!result });
-        } catch {
-          ack?.({ ok: false });
-        }
-      },
-    );
-  });
-
   return io;
 }

backend/src/routes/attachments.ts

@@ -41,6 +41,14 @@ const ALLOWED_MIME = new Set([
   "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
   "application/vnd.ms-excel",
   "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  // Ambient visit-scribe recordings (stored as a patient attachment so they're
+  // auditable). Voice Opus/AAC stays well under the 15 MB cap for a long visit.
+  "audio/webm",
+  "audio/ogg",
+  "audio/mp4",
+  "audio/mpeg",
+  "audio/wav",
+  "audio/x-m4a",
 ]);
 
 // Disk storage under UPLOAD_DIR/<orgId>/, keyed by a random id so original

backend/src/routes/clinic.ts

@@ -0,0 +1,61 @@
+import { Router } from "express";
+import { z } from "zod";
+
+import {
+  requireAuth,
+  requireOrg,
+  requirePermission,
+} from "../middleware/auth.js";
+import { recordActivity } from "../services/activity.js";
+import * as clinicSettings from "../services/clinic-settings.js";
+
+export const clinicRouter = Router();
+
+clinicRouter.use(requireAuth, requireOrg);
+
+// The clinic's settings (currently just its location). Readable by any
+// clinician so the app/UI can display the clinic address.
+clinicRouter.get(
+  "/settings",
+  requirePermission({ patient: ["read"] }),
+  async (req, res, next) => {
+    try {
+      res.json(await clinicSettings.getClinicSettings(req.organizationId!));
+    } catch (err) {
+      next(err);
+    }
+  },
+);
+
+// Set the clinic's location — owner/admin only (gated on the org-update
+// statement, same as signing-key rotation / network toggle).
+const locationSchema = z.object({
+  address: z.string().trim().max(200).default(""),
+  city: z.string().trim().max(120).default(""),
+  country: z.string().trim().max(120).default(""),
+  latitude: z.number().min(-90).max(90).nullable().default(null),
+  longitude: z.number().min(-180).max(180).nullable().default(null),
+});
+
+clinicRouter.put(
+  "/location",
+  requirePermission({ organization: ["update"] }),
+  async (req, res, next) => {
+    try {
+      const location = locationSchema.parse(req.body);
+      const view = await clinicSettings.setClinicLocation(
+        req.organizationId!,
+        location,
+      );
+      await recordActivity({
+        orgId: req.organizationId!,
+        actor: { id: req.user!.id, name: req.user!.name },
+        action: "Updated the clinic location",
+        entityType: "settings",
+      });
+      res.json(view);
+    } catch (err) {
+      next(err);
+    }
+  },
+);

backend/src/routes/fhir.ts

@@ -0,0 +1,275 @@
+import { createRequire } from "node:module";
+
+import { Router } from "express";
+import type { Request, Response } from "express";
+import type { ParsedQs } from "qs";
+
+import { env } from "../env.js";
+import { requireFhirKey } from "../middleware/fhir-auth.js";
+import { recordActivity } from "../services/activity.js";
+import {
+  paginate,
+  parseCount,
+  parseOffset,
+  searchsetBundle,
+} from "../services/fhir-server/bundle.js";
+import { capabilityStatement } from "../services/fhir-server/capability.js";
+import {
+  FHIR_CONTENT_TYPE,
+  operationOutcome,
+  type IssueCode,
+  type IssueSeverity,
+} from "../services/fhir-server/outcome.js";
+import * as q from "../services/fhir-server/queries.js";
+import {
+  allergyResource,
+  appointmentResource,
+  conditionResource,
+  encounterResource,
+  labObservation,
+  medicationRequestResource,
+  patientResource,
+  vitalObservations,
+  type FhirResource,
+} from "../services/fhir-server/resources.js";
+
+const require = createRequire(import.meta.url);
+const pkg = require("../../package.json") as { version?: string };
+const VERSION = env.APP_VERSION ?? pkg.version ?? "0.0.0";
+
+export const fhirRouter = Router();
+
+// --- helpers ----------------------------------------------------------------
+
+function baseUrl(req: Request): string {
+  return `${req.protocol}://${req.get("host")}/fhir`;
+}
+
+function sendResource(res: Response, resource: unknown): void {
+  res.type(FHIR_CONTENT_TYPE).json(resource);
+}
+
+function sendOutcome(
+  res: Response,
+  status: number,
+  severity: IssueSeverity,
+  code: IssueCode,
+  diagnostics: string,
+): void {
+  res
+    .status(status)
+    .type(FHIR_CONTENT_TYPE)
+    .json(operationOutcome(severity, code, diagnostics));
+}
+
+function qstr(v: string | ParsedQs | (string | ParsedQs)[] | undefined): string | undefined {
+  if (typeof v === "string") return v.trim() || undefined;
+  if (Array.isArray(v) && typeof v[0] === "string") return v[0].trim() || undefined;
+  return undefined;
+}
+
+// Best-effort audit: every FHIR request is logged with the key name + result
+// count, scoped to the org. Access to PHI over the API must leave a trail.
+function audit(req: Request, resourceType: string, count: number): void {
+  void recordActivity({
+    orgId: req.organizationId!,
+    actor: { name: `FHIR API · ${req.fhirKey?.name ?? "key"}` },
+    action: `Read ${resourceType} via the FHIR API (${count} result${count === 1 ? "" : "s"})`,
+    entityType: "patient",
+  });
+}
+
+// Materialize a page from a full resource array + emit a searchset Bundle.
+function respondSearch(
+  req: Request,
+  res: Response,
+  resourceType: string,
+  all: FhirResource[],
+): void {
+  const count = parseCount(qstr(req.query._count as never));
+  const offset = parseOffset(qstr(req.query._offset as never));
+  const { page, total } = paginate(all, count, offset);
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(req.query)) {
+    if (k === "_count" || k === "_offset") continue;
+    const s = qstr(v as never);
+    if (s !== undefined) params.set(k, s);
+  }
+  audit(req, resourceType, total);
+  sendResource(
+    res,
+    searchsetBundle({ baseUrl: baseUrl(req), resourceType, page, total, count, offset, params }),
+  );
+}
+
+// Resolve the `patient` / `patient.identifier` search parameter to a patient row
+// (org-scoped). Returns undefined when the param is absent or matches nobody.
+async function patientFromQuery(req: Request) {
+  const patientId = qstr(req.query.patient as never);
+  const identifier = qstr(req.query["patient.identifier"] as never);
+  if (!patientId && !identifier) return undefined;
+  return q.resolvePatientRef(req.organizationId!, { patientId, identifier });
+}
+
+// --- CapabilityStatement (unauthenticated, per FHIR convention) -------------
+
+fhirRouter.get("/metadata", (req, res) => {
+  sendResource(res, capabilityStatement(baseUrl(req), VERSION));
+});
+
+// Everything below requires a valid per-clinic API key.
+fhirRouter.use(requireFhirKey);
+
+// --- Patient ----------------------------------------------------------------
+
+fhirRouter.get("/Patient", async (req, res, next) => {
+  try {
+    const count = parseCount(qstr(req.query._count as never));
+    const offset = parseOffset(qstr(req.query._offset as never));
+    const { rows, total } = await q.searchPatients(req.organizationId!, {
+      identifier: qstr(req.query.identifier as never),
+      name: qstr(req.query.name as never),
+      limit: count,
+      offset,
+    });
+    const params = new URLSearchParams();
+    if (qstr(req.query.identifier as never))
+      params.set("identifier", qstr(req.query.identifier as never)!);
+    if (qstr(req.query.name as never)) params.set("name", qstr(req.query.name as never)!);
+    audit(req, "Patient", total);
+    sendResource(
+      res,
+      searchsetBundle({
+        baseUrl: baseUrl(req),
+        resourceType: "Patient",
+        page: rows.map(patientResource),
+        total,
+        count,
+        offset,
+        params,
+      }),
+    );
+  } catch (err) {
+    next(err);
+  }
+});
+
+fhirRouter.get("/Patient/:id", async (req, res, next) => {
+  try {
+    const row = await q.patientById(req.organizationId!, String(req.params.id));
+    if (!row) {
+      sendOutcome(res, 404, "error", "not-found", "Patient not found.");
+      return;
+    }
+    audit(req, "Patient", 1);
+    sendResource(res, patientResource(row));
+  } catch (err) {
+    next(err);
+  }
+});
+
+// --- Observation (labs + vitals) --------------------------------------------
+
+fhirRouter.get("/Observation", async (req, res, next) => {
+  try {
+    const patient = await patientFromQuery(req);
+    if (!patient) {
+      respondSearch(req, res, "Observation", []);
+      return;
+    }
+    const category = qstr(req.query.category as never);
+    const all: FhirResource[] = [];
+    if (category !== "vital-signs") {
+      const rows = await q.labsForPatient(patient.id);
+      all.push(...rows.map((r) => labObservation(r, patient)));
+    }
+    if (category !== "laboratory") {
+      all.push(...vitalObservations(patient));
+    }
+    respondSearch(req, res, "Observation", all);
+  } catch (err) {
+    next(err);
+  }
+});
+
+// --- AllergyIntolerance -----------------------------------------------------
+
+fhirRouter.get("/AllergyIntolerance", async (req, res, next) => {
+  try {
+    const patient = await patientFromQuery(req);
+    if (!patient) return respondSearch(req, res, "AllergyIntolerance", []);
+    const rows = await q.allergiesForPatient(patient.id);
+    respondSearch(req, res, "AllergyIntolerance", rows.map((r) => allergyResource(r, patient)));
+  } catch (err) {
+    next(err);
+  }
+});
+
+// --- Condition --------------------------------------------------------------
+
+fhirRouter.get("/Condition", async (req, res, next) => {
+  try {
+    const patient = await patientFromQuery(req);
+    if (!patient) return respondSearch(req, res, "Condition", []);
+    const rows = await q.problemsForPatient(patient.id);
+    respondSearch(req, res, "Condition", rows.map((r) => conditionResource(r, patient)));
+  } catch (err) {
+    next(err);
+  }
+});
+
+// --- MedicationRequest ------------------------------------------------------
+
+fhirRouter.get("/MedicationRequest", async (req, res, next) => {
+  try {
+    const patient = await patientFromQuery(req);
+    if (!patient) return respondSearch(req, res, "MedicationRequest", []);
+    const rows = await q.prescriptionsForFile(req.organizationId!, patient.fileNumber);
+    respondSearch(
+      req,
+      res,
+      "MedicationRequest",
+      rows.map((r) => medicationRequestResource(r, patient)),
+    );
+  } catch (err) {
+    next(err);
+  }
+});
+
+// --- Encounter --------------------------------------------------------------
+
+fhirRouter.get("/Encounter", async (req, res, next) => {
+  try {
+    const patient = await patientFromQuery(req);
+    if (!patient) return respondSearch(req, res, "Encounter", []);
+    const rows = await q.encountersForPatient(patient.id);
+    respondSearch(req, res, "Encounter", rows.map((r) => encounterResource(r, patient)));
+  } catch (err) {
+    next(err);
+  }
+});
+
+// --- Appointment ------------------------------------------------------------
+
+fhirRouter.get("/Appointment", async (req, res, next) => {
+  try {
+    const patient = await patientFromQuery(req);
+    if (!patient) return respondSearch(req, res, "Appointment", []);
+    const rows = await q.appointmentsForFile(req.organizationId!, patient.fileNumber);
+    respondSearch(req, res, "Appointment", rows.map((r) => appointmentResource(r, patient)));
+  } catch (err) {
+    next(err);
+  }
+});
+
+// --- Unknown resource / path -> OperationOutcome ----------------------------
+
+fhirRouter.use((req, res) => {
+  sendOutcome(
+    res,
+    404,
+    "error",
+    "not-supported",
+    `Unsupported FHIR path or resource: ${req.method} ${req.path}.`,
+  );
+});

backend/src/routes/integrations.ts

@@ -18,6 +18,7 @@ import {
   listConfigs,
   saveConfig,
 } from "../services/integrations/config.js";
+import { createKey, listKeys, revokeKey } from "../services/fhir-server/keys.js";
 import * as eprescribe from "../services/integrations/eprescribe.js";
 import * as fhir from "../services/integrations/fhir.js";
 
@@ -119,6 +120,75 @@ integrationsRouter.post(
   },
 );
 
+// --- FHIR server API keys (owner/admin only) --------------------------------
+// These credential the read-only /fhir server. The plaintext secret is returned
+// exactly once (on creation) and only its hash is stored.
+
+integrationsRouter.get(
+  "/fhir-server/keys",
+  requireAuth,
+  requireOrg,
+  async (req, res, next) => {
+    try {
+      assertAdmin(req.memberRole);
+      res.json(await listKeys(req.organizationId!));
+    } catch (err) {
+      next(err);
+    }
+  },
+);
+
+const createKeySchema = z.object({ name: z.string().trim().min(1).max(120) });
+
+integrationsRouter.post(
+  "/fhir-server/keys",
+  requireAuth,
+  requireOrg,
+  async (req, res, next) => {
+    try {
+      assertAdmin(req.memberRole);
+      const { name } = createKeySchema.parse(req.body);
+      const { secret, key } = await createKey(
+        req.organizationId!,
+        name,
+        req.user!.id,
+      );
+      void recordActivity({
+        orgId: req.organizationId!,
+        actor: { id: req.user!.id, name: req.user!.name },
+        action: `Created a FHIR API key ("${key.name}")`,
+        entityType: "settings",
+      });
+      // `secret` is present only in this response — the client must show it now.
+      res.status(201).json({ ...key, secret });
+    } catch (err) {
+      next(err);
+    }
+  },
+);
+
+integrationsRouter.delete(
+  "/fhir-server/keys/:id",
+  requireAuth,
+  requireOrg,
+  async (req, res, next) => {
+    try {
+      assertAdmin(req.memberRole);
+      const revoked = await revokeKey(req.organizationId!, String(req.params.id));
+      if (!revoked) throw new HttpError(404, "API key not found.");
+      void recordActivity({
+        orgId: req.organizationId!,
+        actor: { id: req.user!.id, name: req.user!.name },
+        action: "Revoked a FHIR API key",
+        entityType: "settings",
+      });
+      res.json({ revoked: true });
+    } catch (err) {
+      next(err);
+    }
+  },
+);
+
 // --- Actions ----------------------------------------------------------------
 
 const syncSchema = z.object({ fileNumber: z.string().trim().min(1) });

backend/src/routes/patients-wallet.ts

@@ -17,18 +17,36 @@ import {
 } from "../middleware/auth.js";
 import { emitToWallet } from "../realtime.js";
 import { recordActivity } from "../services/activity.js";
+import { connectOrg, expectResponse } from "../services/relay-client.js";
 import * as patientService from "../services/patients.js";
 import { awaitQuickTunnelUrl } from "../services/relay-url.js";
+import { getNetworkEnabled } from "../services/signing.js";
 import * as walletShare from "../services/wallet-share.js";
+import * as walletUpdates from "../services/wallet-updates.js";
 
 export const patientsWalletRouter = Router();
 
 patientsWalletRouter.use(requireAuth, requireOrg);
 
+// Wallet sharing rides the Temetro Network relay, which a clinic must opt into
+// ("Join Temetro Network" in Settings → Signing). Guard the actions that need a
+// live relay connection so a disabled clinic gets a clear message, not silence.
+async function requireNetwork(orgId: string): Promise<void> {
+  if (!(await getNetworkEnabled(orgId))) {
+    throw new HttpError(
+      409,
+      "This clinic hasn't joined the Temetro Network. Enable it in Settings → Signing to share with patient wallets.",
+    );
+  }
+}
+
 // The device-reachable URL the patient's app should connect to (baked into the
-// QR). Prefer an explicit PUBLIC_RELAY_URL; otherwise derive it from the request
-// host so that opening the web app over the LAN yields a reachable LAN URL.
+// QR). Devices connect to the standalone Temetro Network relay — the same relay
+// this backend is hubbed to — so RELAY_URL is the canonical answer. The legacy
+// PUBLIC_RELAY_URL / cloudflared / request-host fallbacks remain for pre-relay
+// self-hosting.
 async function resolveRelayUrl(req: Request): Promise<string> {
+  if (env.RELAY_URL) return env.RELAY_URL;
   if (env.PUBLIC_RELAY_URL) return env.PUBLIC_RELAY_URL;
   // A cloudflared quick tunnel (`npm run docker:tunnel`). Wait briefly for it to
   // become reachable so the QR never carries a not-yet-live URL.
@@ -67,6 +85,7 @@ patientsWalletRouter.post(
   requirePermission({ patient: ["write"] }),
   async (req, res, next) => {
     try {
+      await requireNetwork(req.organizationId!);
       const input = pairSchema.parse(req.body);
       const { view, ephemeralPubKey } = await walletShare.createPairingRequest(
         req.organizationId!,
@@ -74,6 +93,12 @@ patientsWalletRouter.post(
         input.mode,
         input.durationHours,
       );
+      // No wallet number to `wallet:send` to yet, so pre-register the request id
+      // with the relay so the scanning device's response routes back to us.
+      // Ensure the hub is (re)connected first; if it's still mid-handshake the
+      // on-auth re-registration of pending requests will catch this one.
+      await connectOrg(req.organizationId!);
+      expectResponse(req.organizationId!, view.id);
       res.status(201).json({
         ...view,
         ephemeralPubKey,
@@ -93,6 +118,7 @@ patientsWalletRouter.post(
   requirePermission({ patient: ["write"] }),
   async (req, res, next) => {
     try {
+      await requireNetwork(req.organizationId!);
       const input = requestSchema.parse(req.body);
       const { view, ephemeralPubKey } = await walletShare.createShareRequest(
         req.organizationId!,
@@ -105,7 +131,7 @@ patientsWalletRouter.post(
         .select({ name: organization.name })
         .from(organization)
         .where(eq(organization.id, req.organizationId!));
-      emitToWallet(input.walletNumber, "wallet:share-request", {
+      emitToWallet(req.organizationId!, input.walletNumber, "wallet:share-request", {
         requestId: view.id,
         clinicName: org?.name ?? "A clinic",
         requestedBy: req.user!.name,
@@ -138,6 +164,95 @@ patientsWalletRouter.get(
   },
 );
 
+// --- Clinic → wallet record-update push ------------------------------------
+
+// Whether a patient is linked to a wallet (drives the "Push update" button).
+// Returns the wallet number when linked, 404 otherwise.
+patientsWalletRouter.get(
+  "/link/:fileNumber",
+  requirePermission({ patient: ["read"] }),
+  async (req, res, next) => {
+    try {
+      const walletNumber = await walletUpdates.walletNumberForPatient(
+        req.organizationId!,
+        req.params.fileNumber as string,
+      );
+      if (!walletNumber) throw new HttpError(404, "Not wallet-linked.");
+      res.json({ walletNumber });
+    } catch (err) {
+      next(err);
+    }
+  },
+);
+
+const pushSchema = z.object({
+  fileNumber: z.string().trim().min(1),
+  changes: z.array(z.string().trim().min(1)).min(1).max(50),
+});
+
+// Push the current record snapshot to the linked wallet. Seals + signs it,
+// stores it pending, and delivers live if the device is connected (it is also
+// re-sent on the wallet's next connect). The patient must approve in-app.
+patientsWalletRouter.post(
+  "/push",
+  requirePermission({ patient: ["write"] }),
+  async (req, res, next) => {
+    try {
+      await requireNetwork(req.organizationId!);
+      const input = pushSchema.parse(req.body);
+      const row = await walletUpdates.createRecordUpdate(
+        req.organizationId!,
+        req.user!.id,
+        input.fileNumber,
+        input.changes,
+      );
+      const event = await walletUpdates.toEvent(row);
+      emitToWallet(req.organizationId!, row.walletNumber, "wallet:update-request", event);
+      await recordActivity({
+        orgId: req.organizationId!,
+        actor: { id: req.user!.id, name: req.user!.name },
+        action: `Pushed a record update to a patient wallet (#${row.fileNumber})`,
+        entityType: "patient",
+        entityId: row.fileNumber,
+        patientFileNumber: row.fileNumber,
+      });
+      res.status(201).json(walletUpdates.viewOf(row));
+    } catch (err) {
+      next(err);
+    }
+  },
+);
+
+// The clinic's recent update pushes (Signing panel + status polling).
+patientsWalletRouter.get(
+  "/updates",
+  requirePermission({ patient: ["read"] }),
+  async (req, res, next) => {
+    try {
+      res.json(await walletUpdates.listUpdates(req.organizationId!));
+    } catch (err) {
+      next(err);
+    }
+  },
+);
+
+patientsWalletRouter.get(
+  "/updates/:id",
+  requirePermission({ patient: ["read"] }),
+  async (req, res, next) => {
+    try {
+      const view = await walletUpdates.getUpdate(
+        req.organizationId!,
+        req.params.id as string,
+      );
+      if (!view) throw new HttpError(404, "Update not found.");
+      res.json(view);
+    } catch (err) {
+      next(err);
+    }
+  },
+);
+
 // Commit the (possibly clinician-edited) draft into a real patient record. The
 // temporary-share metadata (origin + auto-delete deadline) is taken from the
 // request server-side, so the clinic can't quietly keep a temporary record.

backend/src/routes/portal.ts

@@ -1,9 +1,11 @@
-import { eq } from "drizzle-orm";
+import { and, asc, eq, inArray } from "drizzle-orm";
 import { Router, type Request } from "express";
 import { z } from "zod";
 
 import { db } from "../db/index.js";
-import { organization } from "../db/schema/auth.js";
+import { member, organization, user } from "../db/schema/auth.js";
+import { staffProfile } from "../db/schema/staff-profile.js";
+import { env } from "../env.js";
 import { appointmentInputSchema } from "../lib/appointment-validation.js";
 import { HttpError } from "../lib/http-error.js";
 import { initialsFromName } from "../lib/initials.js";
@@ -11,6 +13,11 @@ import { patientInputSchema } from "../lib/patient-validation.js";
 import { recordActivity } from "../services/activity.js";
 import { createAppointment, listAppointments } from "../services/appointments.js";
 import { createPatient, getPatient } from "../services/patients.js";
+import { getOrCreateKey } from "../services/signing.js";
+
+// Clinical-capable roles that can be a patient's provider (mirrors
+// staff.ts PROVIDER_ROLES). Department roles (reception, pharmacy, lab) excluded.
+const PROVIDER_ROLES = ["owner", "admin", "doctor", "member"] as const;
 
 // Public, unauthenticated kiosk API for a clinic's Patient Portal (an iPad in the
 // waiting room). Scoped by the clinic slug in the URL — there is no session.
@@ -45,12 +52,97 @@ portalRouter.get("/:clinic", async (req, res, next) => {
   }
 });
 
+// GET /api/portal/:clinic/link — the relay-based pairing descriptor the wallet
+// app scans to talk to this clinic over the Temetro Network: the clinic's
+// signing public key (the relay's routing id) + the relay URL. Both values are
+// non-secret (the signing key is the clinic's public identity). This is what
+// makes the Patient Portal QR reachable from a real phone — it no longer bakes
+// in a localhost API URL.
+portalRouter.get("/:clinic/link", async (req, res, next) => {
+  try {
+    const clinic = await resolveClinic(req);
+    const key = await getOrCreateKey(clinic.id);
+    res.json({
+      clinicId: key.publicKey,
+      relay: env.RELAY_URL,
+      slug: String(req.params.clinic ?? "").trim(),
+      name: clinic.name,
+    });
+  } catch (err) {
+    next(err);
+  }
+});
+
+// GET /api/portal/:clinic/doctors — public list of the clinic's providers so a
+// patient can pick who to see. Returns only display-safe fields (name +
+// specialty); no ids, emails, or usernames leave this unauthenticated surface.
+portalRouter.get("/:clinic/doctors", async (req, res, next) => {
+  try {
+    const clinic = await resolveClinic(req);
+    const rows = await db
+      .select({ name: user.name, specialty: staffProfile.specialty })
+      .from(member)
+      .innerJoin(user, eq(user.id, member.userId))
+      .leftJoin(
+        staffProfile,
+        and(
+          eq(staffProfile.userId, member.userId),
+          eq(staffProfile.organizationId, member.organizationId),
+        ),
+      )
+      .where(
+        and(
+          eq(member.organizationId, clinic.id),
+          inArray(member.role, PROVIDER_ROLES as unknown as string[]),
+        ),
+      )
+      .orderBy(asc(user.name));
+    res.json(rows.map((r) => ({ name: r.name, specialty: r.specialty ?? null })));
+  } catch (err) {
+    next(err);
+  }
+});
+
+const availabilitySchema = z.object({
+  provider: z.string().trim().max(200).optional(),
+  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD."),
+});
+
+// GET /api/portal/:clinic/availability?provider=&date= — the taken time slots
+// for a provider on a given day, so the kiosk can render only free slots. The
+// filter mirrors the booking conflict check (an empty-provider appointment
+// blocks the slot clinic-wide). Booking still re-checks server-side (409).
+portalRouter.get("/:clinic/availability", async (req, res, next) => {
+  try {
+    const clinic = await resolveClinic(req);
+    const q = availabilitySchema.parse({
+      provider: req.query.provider,
+      date: req.query.date,
+    });
+    const provider = q.provider ?? "";
+    const taken = (await listAppointments(clinic.id))
+      .filter(
+        (a) =>
+          a.status !== "cancelled" &&
+          a.date === q.date &&
+          (!provider || !a.provider || a.provider === provider),
+      )
+      .map((a) => a.time);
+    res.json({ date: q.date, provider, taken: [...new Set(taken)].sort() });
+  } catch (err) {
+    next(err);
+  }
+});
+
 const bookingSchema = z.object({
   fileNumber: z.string().trim().min(1, "A file number is required.").max(64),
   name: z.string().trim().min(1, "Your name is required.").max(200),
   date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD."),
   time: z.string().regex(/^\d{2}:\d{2}$/, "Time must be HH:mm."),
   type: z.string().trim().max(120).optional(),
+  // Chosen provider (doctor name) from the portal's doctor picker; falls back
+  // to the patient's PCP when omitted.
+  provider: z.string().trim().max(200).optional(),
 });
 
 const newPatientSchema = z.object({
@@ -114,7 +206,7 @@ portalRouter.post("/:clinic/appointments", async (req, res, next) => {
       date: body.date,
       time: body.time,
       type: body.type || "Self-service booking",
-      provider: patient.pcp || "",
+      provider: body.provider || patient.pcp || "",
       status: "confirmed",
       source: "manual",
     });

backend/src/routes/scribe.ts

@@ -0,0 +1,240 @@
+import { readFile } from "node:fs/promises";
+
+import { generateText } from "ai";
+import { Router } from "express";
+import { z } from "zod";
+
+import { HttpError } from "../lib/http-error.js";
+import { isReceptionOnly, providerScope } from "../lib/role-scope.js";
+import {
+  requireAuth,
+  requireOrg,
+  requirePermission,
+} from "../middleware/auth.js";
+import { recordActivity } from "../services/activity.js";
+import { getAiSettings } from "../services/ai/config.js";
+import { aiAllowedFor, getPolicy } from "../services/ai/policy.js";
+import { resolveModel } from "../services/ai/provider.js";
+import { transcribeAudio } from "../services/ai/transcribe.js";
+import { createVeil } from "../services/ai/veil.js";
+import { absolutePath, getAttachmentRow } from "../services/attachments.js";
+import { appendEncounter, getPatient } from "../services/patients.js";
+import type { Encounter } from "../types/patient.js";
+
+export const scribeRouter = Router();
+
+// The ambient scribe drafts and saves a clinical encounter note, so it needs
+// full clinical write access — never reception (demographics only).
+scribeRouter.use(
+  requireAuth,
+  requireOrg,
+  requirePermission({ patient: ["write"] }),
+);
+
+// Guard shared by every scribe route: the clinic AI kill-switch must allow this
+// member, and reception (demographics-only) can never draft clinical notes.
+async function ensureScribeAllowed(req: {
+  organizationId?: string;
+  memberRole?: string;
+}): Promise<void> {
+  if (isReceptionOnly(req.memberRole)) {
+    throw new HttpError(403, "The visit scribe is not available for your role.");
+  }
+  const policy = await getPolicy(req.organizationId!);
+  if (!aiAllowedFor(policy, req.memberRole)) {
+    throw new HttpError(403, "The AI assistant is disabled for your account.");
+  }
+}
+
+const transcribeSchema = z.object({
+  attachmentId: z.string().trim().min(1),
+});
+
+// POST /api/scribe/transcribe — turn a stored audio attachment into a raw
+// transcript via the user's speech provider (OpenAI/Gemini). The audio does NOT
+// pass through Veil or the chat loop.
+scribeRouter.post("/transcribe", async (req, res, next) => {
+  try {
+    await ensureScribeAllowed(req);
+    const { attachmentId } = transcribeSchema.parse(req.body);
+    const row = await getAttachmentRow(req.organizationId!, attachmentId);
+    if (!row) throw new HttpError(404, "Recording not found.");
+    if (!row.mimeType.startsWith("audio/")) {
+      throw new HttpError(400, "That attachment is not an audio recording.");
+    }
+
+    const settings = await getAiSettings(req.user!.id);
+    const buffer = await readFile(absolutePath(row.storagePath));
+    const { transcript, provider } = await transcribeAudio(settings, {
+      buffer,
+      mimeType: row.mimeType,
+      filename: row.filename,
+    });
+
+    void recordActivity({
+      orgId: req.organizationId!,
+      actor: { id: req.user!.id, name: req.user!.name },
+      action: `Transcribed a visit recording (${provider})`,
+      entityType: "patient",
+      patientFileNumber: row.fileNumber,
+    });
+
+    res.json({ transcript });
+  } catch (err) {
+    next(err);
+  }
+});
+
+const draftSchema = z.object({
+  fileNumber: z.string().trim().min(1),
+  transcript: z.string().trim().min(1).max(100_000),
+  visitType: z.string().trim().max(120).optional(),
+  date: z.string().trim().max(40).optional(),
+});
+
+// Strip ```json fences and parse; returns null if the text isn't JSON.
+function parseDraftJson(text: string): { type?: string; summary?: string } | null {
+  const cleaned = text
+    .replace(/^\s*```(?:json)?/i, "")
+    .replace(/```\s*$/i, "")
+    .trim();
+  try {
+    const parsed = JSON.parse(cleaned);
+    return typeof parsed === "object" && parsed ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+const DRAFT_SYSTEM = [
+  "You are a clinical scribe. From a visit transcript, write a concise, structured",
+  "encounter note in SOAP format (Subjective, Objective, Assessment, Plan).",
+  "Rules:",
+  "- Use ONLY what the transcript supports. Never invent vitals, doses, or findings.",
+  "- If a SOAP section has nothing to report, write \"Not discussed.\" under it.",
+  "- Identifiers may appear as tokens like [PATIENT_1] or [PROVIDER_1]; keep them",
+  "  verbatim — do not guess real names.",
+  "Respond with a JSON object ONLY (no prose, no code fences):",
+  '{ "type": "<short visit type, e.g. Follow-up / New patient / Telehealth>",',
+  '  "summary": "<the SOAP note as markdown with **Subjective** / **Objective** /',
+  '  **Assessment** / **Plan** headings>" }',
+].join("\n");
+
+// POST /api/scribe/draft — draft an encounter note from a transcript. The
+// transcript + patient context are Veil-redacted before any external call and
+// the output is rehydrated. Nothing is written — the clinician reviews and
+// approves via POST /save (the same write-approval gate as the chat agent).
+scribeRouter.post("/draft", async (req, res, next) => {
+  try {
+    await ensureScribeAllowed(req);
+    const { fileNumber, transcript, visitType, date } = draftSchema.parse(
+      req.body,
+    );
+
+    const patient = await getPatient(
+      req.organizationId!,
+      fileNumber,
+      false,
+      providerScope(req.memberRole, req.user!.id),
+    );
+    if (!patient) throw new HttpError(404, "Patient not found.");
+
+    const settings = await getAiSettings(req.user!.id);
+    const resolved = resolveModel(settings, settings.defaultModel);
+    const veil = createVeil(settings.veilLevel, resolved.isExternal);
+
+    // Seed Veil's token maps with this patient's identifiers, then redact the
+    // free-text transcript against them before it leaves the clinic.
+    const redactedPatient = veil.redactPatient(patient);
+    const redactedTranscript = veil.redactText(transcript);
+
+    const context = [
+      `Patient: ${redactedPatient.name} (MRN ${redactedPatient.fileNumber}), ${patient.age}y ${patient.sex}.`,
+      patient.problems.length
+        ? `Known problems: ${patient.problems.map((p) => p.label).join(", ")}.`
+        : "",
+      patient.medications.length
+        ? `Current medications: ${patient.medications
+            .map((m) => `${m.name} ${m.dose}`)
+            .join(", ")}.`
+        : "",
+      visitType ? `Visit type hint: ${visitType}.` : "",
+      "",
+      "Transcript:",
+      redactedTranscript,
+    ]
+      .filter(Boolean)
+      .join("\n");
+
+    const result = await generateText({
+      model: resolved.model,
+      system: DRAFT_SYSTEM,
+      prompt: context,
+    });
+
+    const parsed = parseDraftJson(result.text);
+    const summary = veil.rehydrate(
+      (parsed?.summary ?? result.text ?? "").trim(),
+    );
+    const type = (parsed?.type ?? visitType ?? "Visit").trim() || "Visit";
+
+    const draft: Encounter = {
+      date: date || new Date().toISOString().slice(0, 10),
+      type,
+      // The responsible clinician is the signed-in user, not the model's guess.
+      provider: req.user!.name ?? "",
+      summary,
+    };
+
+    res.json({
+      draft,
+      veil: {
+        active: veil.active,
+        level: veil.level,
+        classes: veil.usedClasses(),
+        provider: resolved.providerLabel,
+      },
+    });
+  } catch (err) {
+    next(err);
+  }
+});
+
+const saveSchema = z.object({
+  fileNumber: z.string().trim().min(1),
+  encounter: z.object({
+    date: z.string().trim().min(1),
+    type: z.string().trim().min(1),
+    provider: z.string().trim().default(""),
+    summary: z.string().trim().min(1),
+  }),
+});
+
+// POST /api/scribe/save — the approval step: append the reviewed encounter note
+// to the patient record. Re-validates server-side and audits like any add.
+scribeRouter.post("/save", async (req, res, next) => {
+  try {
+    await ensureScribeAllowed(req);
+    const { fileNumber, encounter } = saveSchema.parse(req.body);
+    const updated = await appendEncounter(
+      req.organizationId!,
+      fileNumber,
+      encounter,
+    );
+    if (!updated) throw new HttpError(404, "Patient not found.");
+
+    void recordActivity({
+      orgId: req.organizationId!,
+      actor: { id: req.user!.id, name: req.user!.name },
+      action: `Added a scribe visit note for ${updated.name}`,
+      entityType: "patient",
+      entityId: updated.fileNumber,
+      patientName: updated.name,
+      patientFileNumber: updated.fileNumber,
+    });
+
+    res.status(201).json(updated);
+  } catch (err) {
+    next(err);
+  }
+});

backend/src/routes/signing.ts

@@ -1,4 +1,5 @@
 import { Router } from "express";
+import { z } from "zod";
 
 import {
   requireAuth,
@@ -6,6 +7,7 @@ import {
   requirePermission,
 } from "../middleware/auth.js";
 import { recordActivity } from "../services/activity.js";
+import { connectOrg, disconnectOrg } from "../services/relay-client.js";
 import * as signing from "../services/signing.js";
 import * as walletShare from "../services/wallet-share.js";
 
@@ -48,6 +50,52 @@ signingRouter.post(
   },
 );
 
+// Whether this clinic has joined the Temetro Network relay. Readable by any
+// clinician (the panel shows the toggle state + connection status).
+signingRouter.get(
+  "/network",
+  requirePermission({ patient: ["read"] }),
+  async (req, res, next) => {
+    try {
+      res.json({ enabled: await signing.getNetworkEnabled(req.organizationId!) });
+    } catch (err) {
+      next(err);
+    }
+  },
+);
+
+// Join / leave the Temetro Network — owner/admin only (same gate as key
+// rotation). Enabling opens this clinic's relay hub connection; disabling tears
+// it down.
+const networkSchema = z.object({ enabled: z.boolean() });
+
+signingRouter.put(
+  "/network",
+  requirePermission({ organization: ["update"] }),
+  async (req, res, next) => {
+    try {
+      const { enabled } = networkSchema.parse(req.body);
+      await signing.setNetworkEnabled(req.organizationId!, enabled);
+      if (enabled) {
+        await connectOrg(req.organizationId!);
+      } else {
+        disconnectOrg(req.organizationId!);
+      }
+      await recordActivity({
+        orgId: req.organizationId!,
+        actor: { id: req.user!.id, name: req.user!.name },
+        action: enabled
+          ? "Joined the Temetro Network"
+          : "Left the Temetro Network",
+        entityType: "settings",
+      });
+      res.json({ enabled });
+    } catch (err) {
+      next(err);
+    }
+  },
+);
+
 // Recent records shared from patient wallets — feeds the panel's shared-records
 // list.
 signingRouter.get(

backend/src/routes/version.ts

@@ -1,6 +1,8 @@
-// GET /api/version — reports the running version and whether a newer release
-// exists on GitHub. Public (no PHI); the frontend uses it for the Settings
-// "About & Updates" panel and the optional update banner.
+// GET /api/version — reports the running version and whether a newer image is
+// available. The latest version is read from Docker Hub (the actual update
+// channel: clinics run `docker compose pull`), falling back to the GitHub
+// release if Docker Hub's API is unreachable. Public (no PHI); the frontend uses
+// it for the Settings "About & Updates" panel and the optional update banner.
 import { createRequire } from "node:module";
 
 import { Router } from "express";
@@ -13,16 +15,24 @@ const require = createRequire(import.meta.url);
 const pkg = require("../../package.json") as { version?: string };
 const CURRENT = env.APP_VERSION ?? pkg.version ?? "0.0.0";
 
-const LATEST_RELEASE_URL =
+// The published image whose tags reflect what `docker compose pull` would fetch.
+const DOCKERHUB_TAGS_URL =
+  "https://hub.docker.com/v2/repositories/khalidxv/temetro-backend/tags?page_size=100";
+// GitHub release of a given version — used for the human-readable "what's new"
+// link, and as a fallback source for the latest version.
+const GITHUB_LATEST_RELEASE_URL =
   "https://api.github.com/repos/temetro/temetro/releases/latest";
-const CACHE_TTL = 6 * 60 * 60 * 1000; // 6h — releases are infrequent.
+const releaseUrlFor = (version: string) =>
+  `https://github.com/temetro/temetro/releases/tag/v${version}`;
+
+const CACHE_TTL = 60 * 60 * 1000; // 1h — surface a new release reasonably fast.
 const ERROR_TTL = 10 * 60 * 1000; // back off ~10m after a failed lookup.
 
 type LatestInfo = { latest: string | null; releaseUrl: string | null };
 let cache: { at: number; ttl: number; info: LatestInfo } | null = null;
 
 function parseSemver(v: string): [number, number, number] | null {
-  const m = v.trim().replace(/^v/, "").match(/^(\d+)\.(\d+)\.(\d+)/);
+  const m = v.trim().replace(/^v/, "").match(/^(\d+)\.(\d+)\.(\d+)$/);
   return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
 }
 
@@ -38,18 +48,52 @@ function isNewer(latest: string, current: string): boolean {
   return false;
 }
 
-async function fetchLatest(): Promise<LatestInfo> {
-  if (cache && Date.now() - cache.at < cache.ttl) return cache.info;
+// Highest strict X.Y.Z tag in the list (ignores `latest` and any non-semver).
+function maxSemver(versions: string[]): string | null {
+  let best: string | null = null;
+  for (const v of versions) {
+    if (parseSemver(v) && (best === null || isNewer(v, best))) best = v;
+  }
+  return best;
+}
+
+// Primary source: the published Docker Hub image tags.
+async function fetchFromDockerHub(): Promise<string | null> {
+  const res = await fetch(DOCKERHUB_TAGS_URL, {
+    headers: { Accept: "application/json", "User-Agent": "temetro" },
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!res.ok) throw new Error(`Docker Hub responded ${res.status}`);
+  const body = (await res.json()) as { results?: Array<{ name?: string }> };
+  const names = (body.results ?? [])
+    .map((r) => r.name)
+    .filter((n): n is string => typeof n === "string");
+  return maxSemver(names);
+}
+
+// Fallback source: the latest GitHub release tag (used if Docker Hub is blocked).
+async function fetchFromGitHub(): Promise<string | null> {
+  const res = await fetch(GITHUB_LATEST_RELEASE_URL, {
+    headers: { Accept: "application/vnd.github+json", "User-Agent": "temetro" },
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!res.ok) throw new Error(`GitHub responded ${res.status}`);
+  const body = (await res.json()) as { tag_name?: string };
+  return body.tag_name ? body.tag_name.replace(/^v/, "") : null;
+}
+
+async function fetchLatest(force = false): Promise<LatestInfo> {
+  if (!force && cache && Date.now() - cache.at < cache.ttl) return cache.info;
   try {
-    const res = await fetch(LATEST_RELEASE_URL, {
-      headers: { Accept: "application/vnd.github+json", "User-Agent": "temetro" },
-      signal: AbortSignal.timeout(5000),
-    });
-    if (!res.ok) throw new Error(`GitHub responded ${res.status}`);
-    const body = (await res.json()) as { tag_name?: string; html_url?: string };
+    let latest: string | null = null;
+    try {
+      latest = await fetchFromDockerHub();
+    } catch {
+      latest = await fetchFromGitHub();
+    }
     const info: LatestInfo = {
-      latest: body.tag_name ? body.tag_name.replace(/^v/, "") : null,
-      releaseUrl: body.html_url ?? null,
+      latest,
+      releaseUrl: latest ? releaseUrlFor(latest) : null,
     };
     cache = { at: Date.now(), ttl: CACHE_TTL, info };
     return info;
@@ -63,8 +107,10 @@ async function fetchLatest(): Promise<LatestInfo> {
 
 const router = Router();
 
-router.get("/", async (_req, res) => {
-  const { latest, releaseUrl } = await fetchLatest();
+router.get("/", async (req, res) => {
+  // `?refresh=1` powers the "Check for updates" button — bypass the cache.
+  const force = req.query.refresh === "1" || req.query.refresh === "true";
+  const { latest, releaseUrl } = await fetchLatest(force);
   res.json({
     current: CURRENT,
     latest,

backend/src/services/ai/transcribe.ts

@@ -0,0 +1,132 @@
+import { HttpError } from "../../lib/http-error.js";
+import type { userAiSettings } from "../../db/schema/ai.js";
+import { getApiKey } from "./config.js";
+
+type AiSettingsRow = typeof userAiSettings.$inferSelect;
+
+export type AudioInput = {
+  buffer: Buffer;
+  mimeType: string;
+  filename: string;
+};
+
+// Which transcription backend a user's AI settings can reach. Anthropic has no
+// speech-to-text API, so an Anthropic-only user must paste a transcript instead.
+export type TranscribeProvider = "openai" | "gemini";
+
+export function transcribeProviderFor(
+  settings: AiSettingsRow,
+): TranscribeProvider | null {
+  if (getApiKey(settings, "openai")) return "openai";
+  if (getApiKey(settings, "gemini")) return "gemini";
+  return null;
+}
+
+const OPENAI_MODEL = "whisper-1";
+const GEMINI_MODEL = "gemini-2.5-flash";
+
+const TRANSCRIBE_PROMPT =
+  "Transcribe this clinical visit recording verbatim. Return only the spoken words as plain text, with no commentary, headings, or timestamps.";
+
+async function transcribeWithOpenAI(
+  apiKey: string,
+  audio: AudioInput,
+): Promise<string> {
+  const form = new FormData();
+  form.append(
+    "file",
+    new Blob([new Uint8Array(audio.buffer)], { type: audio.mimeType }),
+    audio.filename,
+  );
+  form.append("model", OPENAI_MODEL);
+  form.append("response_format", "json");
+
+  const res = await fetch("https://api.openai.com/v1/audio/transcriptions", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${apiKey}` },
+    body: form,
+  });
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new HttpError(
+      502,
+      `Transcription failed (OpenAI ${res.status}). ${detail.slice(0, 300)}`,
+    );
+  }
+  const json = (await res.json()) as { text?: string };
+  return (json.text ?? "").trim();
+}
+
+async function transcribeWithGemini(
+  apiKey: string,
+  audio: AudioInput,
+): Promise<string> {
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${GEMINI_MODEL}:generateContent?key=${encodeURIComponent(
+    apiKey,
+  )}`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      contents: [
+        {
+          parts: [
+            {
+              inline_data: {
+                mime_type: audio.mimeType,
+                data: audio.buffer.toString("base64"),
+              },
+            },
+            { text: TRANSCRIBE_PROMPT },
+          ],
+        },
+      ],
+    }),
+  });
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new HttpError(
+      502,
+      `Transcription failed (Gemini ${res.status}). ${detail.slice(0, 300)}`,
+    );
+  }
+  const json = (await res.json()) as {
+    candidates?: { content?: { parts?: { text?: string }[] } }[];
+  };
+  const text =
+    json.candidates?.[0]?.content?.parts
+      ?.map((p) => p.text ?? "")
+      .join("")
+      .trim() ?? "";
+  return text;
+}
+
+// Send an audio recording to the user's transcription provider and return the
+// raw transcript. The audio never passes through the chat loop or Veil — Veil
+// cannot redact speech, so the caller must warn the clinician that audio leaves
+// the clinic when an external provider is used (only the DRAFTING step is
+// Veil-protected). Throws a 400 when no speech-capable provider is configured.
+export async function transcribeAudio(
+  settings: AiSettingsRow,
+  audio: AudioInput,
+): Promise<{ transcript: string; provider: TranscribeProvider }> {
+  const provider = transcribeProviderFor(settings);
+  if (!provider) {
+    throw new HttpError(
+      400,
+      "Transcription needs an OpenAI or Gemini API key. Add one in Settings → AI, or paste the visit transcript instead.",
+    );
+  }
+  const apiKey = getApiKey(settings, provider)!;
+  const transcript =
+    provider === "openai"
+      ? await transcribeWithOpenAI(apiKey, audio)
+      : await transcribeWithGemini(apiKey, audio);
+  if (!transcript) {
+    throw new HttpError(
+      502,
+      "The transcription came back empty — try again or paste the transcript.",
+    );
+  }
+  return { transcript, provider };
+}

backend/src/services/ai/veil.ts

@@ -26,6 +26,15 @@ export type Veil = {
   redactPatient: (patient: Patient) => Patient;
   /** Map a possibly-tokenized file number from a tool call back to the real one. */
   resolveFileNumber: (input: string) => string;
+  /**
+   * De-identify free text (e.g. a visit transcript) by swapping any KNOWN
+   * identifiers — the patient name, MRN and provider names already seen via
+   * redactPatient — for their tokens. Seed the token maps by calling
+   * redactPatient(patient) first. Note: this only catches identifiers we know
+   * about; free-text PHI spoken aloud (addresses, relatives' names) is not
+   * covered — see the ambient-scribe consent notice.
+   */
+  redactText: (text: string) => string;
   /** Swap any tokens in model output back to real identifiers. */
   rehydrate: (text: string) => string;
   /** Token classes actually emitted — for the audit log. */
@@ -81,6 +90,21 @@ export function createVeil(level: VeilLevel, active: boolean): Veil {
     return mrnByToken.get(input.trim()) ?? input;
   }
 
+  function redactText(text: string): string {
+    if (!isActive || fromToken.size === 0) return text;
+    let out = text;
+    // Longest real values first so a provider name containing the patient name
+    // (or similar overlap) is replaced whole before its substrings.
+    const byLength = [...fromToken.entries()]
+      .filter(([, real]) => real.trim().length > 0)
+      .sort((a, b) => b[1].length - a[1].length);
+    for (const [token, real] of byLength) {
+      const escaped = real.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      out = out.replace(new RegExp(escaped, "gi"), token);
+    }
+    return out;
+  }
+
   function rehydrate(text: string): string {
     if (!isActive || fromToken.size === 0) return text;
     let out = text;
@@ -101,6 +125,7 @@ export function createVeil(level: VeilLevel, active: boolean): Veil {
     level,
     redactPatient,
     resolveFileNumber,
+    redactText,
     rehydrate,
     usedClasses,
   };

backend/src/services/clinic-settings.ts

@@ -0,0 +1,82 @@
+import { eq } from "drizzle-orm";
+
+import { db } from "../db/index.js";
+import { clinicSettings } from "../db/schema/clinic-settings.js";
+
+export type ClinicLocation = {
+  address: string;
+  city: string;
+  country: string;
+  latitude: number | null;
+  longitude: number | null;
+};
+
+export type ClinicSettingsView = {
+  location: ClinicLocation;
+};
+
+const EMPTY_LOCATION: ClinicLocation = {
+  address: "",
+  city: "",
+  country: "",
+  latitude: null,
+  longitude: null,
+};
+
+type ClinicSettingsRow = typeof clinicSettings.$inferSelect;
+
+function toView(row: ClinicSettingsRow | undefined): ClinicSettingsView {
+  if (!row) return { location: { ...EMPTY_LOCATION } };
+  return {
+    location: {
+      address: row.address,
+      city: row.city,
+      country: row.country,
+      latitude: row.latitude,
+      longitude: row.longitude,
+    },
+  };
+}
+
+// Read a clinic's settings. Returns empty defaults when no row exists yet, so
+// the panel always renders.
+export async function getClinicSettings(
+  orgId: string,
+): Promise<ClinicSettingsView> {
+  const [row] = await db
+    .select()
+    .from(clinicSettings)
+    .where(eq(clinicSettings.organizationId, orgId))
+    .limit(1);
+  return toView(row);
+}
+
+// Upsert the clinic's location (address + optional coordinates).
+export async function setClinicLocation(
+  orgId: string,
+  location: ClinicLocation,
+): Promise<ClinicSettingsView> {
+  const values = {
+    organizationId: orgId,
+    address: location.address,
+    city: location.city,
+    country: location.country,
+    latitude: location.latitude,
+    longitude: location.longitude,
+  };
+  const [row] = await db
+    .insert(clinicSettings)
+    .values(values)
+    .onConflictDoUpdate({
+      target: clinicSettings.organizationId,
+      set: {
+        address: values.address,
+        city: values.city,
+        country: values.country,
+        latitude: values.latitude,
+        longitude: values.longitude,
+      },
+    })
+    .returning();
+  return toView(row);
+}

backend/src/services/fhir-server/bundle.ts

@@ -0,0 +1,77 @@
+import type { FhirResource } from "./resources.js";
+
+// searchset Bundle assembly + offset/limit pagination for the FHIR server.
+
+export const DEFAULT_COUNT = 50;
+export const MAX_COUNT = 200;
+
+// Clamp a client-supplied `_count` into [1, MAX_COUNT], defaulting when absent.
+export function parseCount(raw: string | undefined): number {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_COUNT;
+  return Math.min(Math.floor(n), MAX_COUNT);
+}
+
+export function parseOffset(raw: string | undefined): number {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return 0;
+  return Math.floor(n);
+}
+
+// Slice an already-materialized resource array to the requested page.
+export function paginate<T>(
+  all: T[],
+  count: number,
+  offset: number,
+): { page: T[]; total: number } {
+  return { page: all.slice(offset, offset + count), total: all.length };
+}
+
+export type SearchsetBundle = {
+  resourceType: "Bundle";
+  type: "searchset";
+  total: number;
+  link: { relation: string; url: string }[];
+  entry: { fullUrl: string; resource: FhirResource; search: { mode: "match" } }[];
+};
+
+// Build a FHIR searchset Bundle. `page` is the current slice; `total` the full
+// match count; `params` the effective query (already carrying `_count`/`_offset`)
+// used to derive self/next/prev links.
+export function searchsetBundle(opts: {
+  baseUrl: string; // e.g. https://host/fhir
+  resourceType: string;
+  page: FhirResource[];
+  total: number;
+  count: number;
+  offset: number;
+  params: URLSearchParams;
+}): SearchsetBundle {
+  const { baseUrl, resourceType, page, total, count, offset, params } = opts;
+
+  const linkFor = (nextOffset: number): string => {
+    const q = new URLSearchParams(params);
+    q.set("_count", String(count));
+    q.set("_offset", String(nextOffset));
+    return `${baseUrl}/${resourceType}?${q.toString()}`;
+  };
+
+  const link: { relation: string; url: string }[] = [
+    { relation: "self", url: linkFor(offset) },
+  ];
+  if (offset + count < total) link.push({ relation: "next", url: linkFor(offset + count) });
+  if (offset > 0)
+    link.push({ relation: "previous", url: linkFor(Math.max(0, offset - count)) });
+
+  return {
+    resourceType: "Bundle",
+    type: "searchset",
+    total,
+    link,
+    entry: page.map((resource) => ({
+      fullUrl: `${baseUrl}/${resource.resourceType}/${resource.id}`,
+      resource,
+      search: { mode: "match" },
+    })),
+  };
+}

backend/src/services/fhir-server/capability.ts

@@ -0,0 +1,114 @@
+// A static CapabilityStatement describing exactly what this read-only FHIR R4
+// server supports. It is intentionally honest: only the resources and search
+// params implemented below are listed, everything is `read`/`search-type` only,
+// and clinical concepts are text-only (no SNOMED/LOINC coding).
+
+type ResourceCapability = {
+  type: string;
+  interaction: { code: "read" | "search-type" }[];
+  searchParam?: { name: string; type: "token" | "string" | "reference" }[];
+};
+
+const RESOURCES: ResourceCapability[] = [
+  {
+    type: "Patient",
+    interaction: [{ code: "read" }, { code: "search-type" }],
+    searchParam: [
+      { name: "identifier", type: "token" },
+      { name: "name", type: "string" },
+    ],
+  },
+  {
+    type: "Observation",
+    interaction: [{ code: "read" }, { code: "search-type" }],
+    searchParam: [
+      { name: "patient", type: "reference" },
+      { name: "patient.identifier", type: "token" },
+      { name: "category", type: "token" },
+    ],
+  },
+  {
+    type: "AllergyIntolerance",
+    interaction: [{ code: "read" }, { code: "search-type" }],
+    searchParam: [
+      { name: "patient", type: "reference" },
+      { name: "patient.identifier", type: "token" },
+    ],
+  },
+  {
+    type: "Condition",
+    interaction: [{ code: "read" }, { code: "search-type" }],
+    searchParam: [
+      { name: "patient", type: "reference" },
+      { name: "patient.identifier", type: "token" },
+    ],
+  },
+  {
+    type: "MedicationRequest",
+    interaction: [{ code: "read" }, { code: "search-type" }],
+    searchParam: [
+      { name: "patient", type: "reference" },
+      { name: "patient.identifier", type: "token" },
+    ],
+  },
+  {
+    type: "Encounter",
+    interaction: [{ code: "read" }, { code: "search-type" }],
+    searchParam: [
+      { name: "patient", type: "reference" },
+      { name: "patient.identifier", type: "token" },
+    ],
+  },
+  {
+    type: "Appointment",
+    interaction: [{ code: "read" }, { code: "search-type" }],
+    searchParam: [
+      { name: "patient", type: "reference" },
+      { name: "patient.identifier", type: "token" },
+    ],
+  },
+];
+
+export function capabilityStatement(
+  baseUrl: string,
+  version: string,
+): Record<string, unknown> {
+  return {
+    resourceType: "CapabilityStatement",
+    status: "active",
+    date: new Date().toISOString(),
+    publisher: "temetro",
+    kind: "instance",
+    implementation: { description: "temetro FHIR server", url: baseUrl },
+    software: { name: "temetro", version },
+    fhirVersion: "4.0.1",
+    format: ["application/fhir+json", "json"],
+    rest: [
+      {
+        mode: "server",
+        documentation:
+          "Read-only FHIR R4 server. Authenticate with a per-clinic API key: " +
+          "Authorization: Bearer tmf_…. Clinical values are text-only " +
+          "CodeableConcepts (no SNOMED/LOINC). Patients expose age (extension), " +
+          "not birthDate. Pagination via _count (default 50, max 200) and _offset.",
+        security: {
+          description: "Bearer token (per-organization API key, tmf_ prefix).",
+          service: [
+            {
+              coding: [
+                {
+                  system:
+                    "http://terminology.hl7.org/CodeSystem/restful-security-service",
+                  code: "OAuth",
+                  display: "OAuth",
+                },
+              ],
+              text: "API key bearer token",
+            },
+          ],
+        },
+        resource: RESOURCES,
+      },
+    ],
+  };
+}

backend/src/services/fhir-server/keys.ts

@@ -0,0 +1,110 @@
+import { createHash, randomBytes } from "node:crypto";
+
+import { and, desc, eq, isNull } from "drizzle-orm";
+
+import { db } from "../../db/index.js";
+import { fhirApiKeys } from "../../db/schema/fhir-keys.js";
+
+// FHIR-server API keys. The secret is `tmf_` + 32 random bytes (base64url); we
+// persist only its SHA-256 hash, so a leaked database never yields usable keys
+// and the plaintext is returned exactly once (at creation).
+
+const PREFIX = "tmf_";
+
+export type FhirKeyView = {
+  id: string;
+  name: string;
+  createdAt: string;
+  lastUsedAt: string | null;
+  revoked: boolean;
+};
+
+function hashKey(secret: string): string {
+  return createHash("sha256").update(secret).digest("hex");
+}
+
+function toView(row: typeof fhirApiKeys.$inferSelect): FhirKeyView {
+  return {
+    id: row.id,
+    name: row.name,
+    createdAt: row.createdAt.toISOString(),
+    lastUsedAt: row.lastUsedAt ? row.lastUsedAt.toISOString() : null,
+    revoked: row.revokedAt !== null,
+  };
+}
+
+// List a clinic's keys (active first, then revoked), newest first. Never
+// exposes the hash.
+export async function listKeys(orgId: string): Promise<FhirKeyView[]> {
+  const rows = await db
+    .select()
+    .from(fhirApiKeys)
+    .where(eq(fhirApiKeys.organizationId, orgId))
+    .orderBy(desc(fhirApiKeys.createdAt));
+  return rows.map(toView);
+}
+
+// Mint a new key. Returns the one-time plaintext secret alongside the stored
+// view — the caller must surface the secret to the user immediately; it is not
+// recoverable afterwards.
+export async function createKey(
+  orgId: string,
+  name: string,
+  createdBy: string,
+): Promise<{ secret: string; key: FhirKeyView }> {
+  const secret = PREFIX + randomBytes(32).toString("base64url");
+  const [row] = await db
+    .insert(fhirApiKeys)
+    .values({
+      organizationId: orgId,
+      name: name.trim() || "FHIR key",
+      keyHash: hashKey(secret),
+      createdBy,
+    })
+    .returning();
+  return { secret, key: toView(row!) };
+}
+
+// Revoke a key (idempotent). Scoped to the org so one clinic can't revoke
+// another's. Returns false if no such active key exists.
+export async function revokeKey(orgId: string, id: string): Promise<boolean> {
+  const result = await db
+    .update(fhirApiKeys)
+    .set({ revokedAt: new Date() })
+    .where(
+      and(
+        eq(fhirApiKeys.id, id),
+        eq(fhirApiKeys.organizationId, orgId),
+        isNull(fhirApiKeys.revokedAt),
+      ),
+    )
+    .returning({ id: fhirApiKeys.id });
+  return result.length > 0;
+}
+
+export type ResolvedKey = { orgId: string; keyId: string; keyName: string };
+
+// Resolve a presented bearer secret to its owning organization (plus the key's
+// identity, for the audit log), or null when it is unknown or revoked. Bumps
+// `lastUsedAt` (throttled to once a minute) so the key list can show recent
+// activity without a write on every request.
+export async function resolveKey(secret: string): Promise<ResolvedKey | null> {
+  if (!secret.startsWith(PREFIX)) return null;
+  const [row] = await db
+    .select()
+    .from(fhirApiKeys)
+    .where(eq(fhirApiKeys.keyHash, hashKey(secret)))
+    .limit(1);
+  if (!row || row.revokedAt) return null;
+
+  const now = Date.now();
+  const last = row.lastUsedAt?.getTime() ?? 0;
+  if (now - last > 60_000) {
+    void db
+      .update(fhirApiKeys)
+      .set({ lastUsedAt: new Date() })
+      .where(eq(fhirApiKeys.id, row.id))
+      .catch(() => {});
+  }
+  return { orgId: row.organizationId, keyId: row.id, keyName: row.name };
+}

backend/src/services/fhir-server/outcome.ts

@@ -0,0 +1,36 @@
+// FHIR OperationOutcome helpers. Errors on a FHIR endpoint are returned as an
+// OperationOutcome resource (not our usual `{ error }` JSON), with the
+// `application/fhir+json` content type, so conformant clients can parse them.
+
+export const FHIR_CONTENT_TYPE = "application/fhir+json";
+
+export type IssueSeverity = "fatal" | "error" | "warning" | "information";
+export type IssueCode =
+  | "not-found"
+  | "not-supported"
+  | "security"
+  | "login"
+  | "forbidden"
+  | "invalid"
+  | "processing"
+  | "exception";
+
+export type OperationOutcome = {
+  resourceType: "OperationOutcome";
+  issue: {
+    severity: IssueSeverity;
+    code: IssueCode;
+    diagnostics?: string;
+  }[];
+};
+
+export function operationOutcome(
+  severity: IssueSeverity,
+  code: IssueCode,
+  diagnostics: string,
+): OperationOutcome {
+  return {
+    resourceType: "OperationOutcome",
+    issue: [{ severity, code, diagnostics }],
+  };
+}

backend/src/services/fhir-server/queries.ts

@@ -0,0 +1,168 @@
+import { and, asc, count, eq, ilike, sql } from "drizzle-orm";
+import type { SQL } from "drizzle-orm";
+
+import { db } from "../../db/index.js";
+import { appointments } from "../../db/schema/appointments.js";
+import {
+  allergies,
+  encounters,
+  labs,
+  medications,
+  patients,
+  problems,
+} from "../../db/schema/patients.js";
+import { prescriptions } from "../../db/schema/prescriptions.js";
+
+// Narrow, org-scoped reads for the FHIR server. Deliberately separate from the
+// app's `services/patients.ts` (which returns the reshaped canonical Patient and
+// applies role redaction): the FHIR layer needs raw rows *with their UUIDs* to
+// mint stable resource ids, and offset/limit pagination the app service doesn't
+// expose. Every function is scoped to a single organization.
+
+export type PatientRow = typeof patients.$inferSelect;
+export type LabRow = typeof labs.$inferSelect;
+export type AllergyRow = typeof allergies.$inferSelect;
+export type ProblemRow = typeof problems.$inferSelect;
+export type EncounterRow = typeof encounters.$inferSelect;
+export type PrescriptionRow = typeof prescriptions.$inferSelect;
+export type AppointmentRow = typeof appointments.$inferSelect;
+
+// --- Patient ----------------------------------------------------------------
+
+// Paginated Patient search. `identifier` matches the MRN (file number) exactly;
+// `name` is a case-insensitive substring. Returns the page plus the full total
+// for the searchset Bundle.
+export async function searchPatients(
+  orgId: string,
+  opts: { identifier?: string; name?: string; limit: number; offset: number },
+): Promise<{ rows: PatientRow[]; total: number }> {
+  const filters: SQL[] = [eq(patients.organizationId, orgId)];
+  if (opts.identifier) filters.push(eq(patients.fileNumber, opts.identifier));
+  if (opts.name) filters.push(ilike(patients.name, `%${opts.name}%`));
+  const where = and(...filters);
+
+  const [rows, [totalRow]] = await Promise.all([
+    db
+      .select()
+      .from(patients)
+      .where(where)
+      .orderBy(asc(patients.fileNumber))
+      .limit(opts.limit)
+      .offset(opts.offset),
+    db.select({ value: count() }).from(patients).where(where),
+  ]);
+
+  return { rows, total: totalRow?.value ?? 0 };
+}
+
+// A single patient by FHIR logical id (the row UUID), scoped to the org.
+export async function patientById(
+  orgId: string,
+  id: string,
+): Promise<PatientRow | undefined> {
+  // Guard against a non-UUID id: Postgres would otherwise error on the cast.
+  if (!/^[0-9a-f-]{36}$/i.test(id)) return undefined;
+  const [row] = await db
+    .select()
+    .from(patients)
+    .where(and(eq(patients.organizationId, orgId), eq(patients.id, id)))
+    .limit(1);
+  return row;
+}
+
+// Resolve a `patient` search parameter to a patient row. Accepts either the FHIR
+// logical id (`patient=<uuid>`) or the MRN (`patient.identifier=<file#>`).
+export async function resolvePatientRef(
+  orgId: string,
+  ref: { patientId?: string; identifier?: string },
+): Promise<PatientRow | undefined> {
+  if (ref.patientId) {
+    // A reference may arrive as "Patient/<id>" or a bare id.
+    const id = ref.patientId.replace(/^Patient\//, "");
+    return patientById(orgId, id);
+  }
+  if (ref.identifier) {
+    const [row] = await db
+      .select()
+      .from(patients)
+      .where(
+        and(
+          eq(patients.organizationId, orgId),
+          eq(patients.fileNumber, ref.identifier),
+        ),
+      )
+      .limit(1);
+    return row;
+  }
+  return undefined;
+}
+
+// --- Clinical child rows (by patient UUID) ----------------------------------
+
+export function labsForPatient(patientId: string): Promise<LabRow[]> {
+  return db
+    .select()
+    .from(labs)
+    .where(eq(labs.patientId, patientId))
+    .orderBy(asc(labs.position));
+}
+
+export function allergiesForPatient(patientId: string): Promise<AllergyRow[]> {
+  return db
+    .select()
+    .from(allergies)
+    .where(eq(allergies.patientId, patientId))
+    .orderBy(asc(allergies.position));
+}
+
+export function problemsForPatient(patientId: string): Promise<ProblemRow[]> {
+  return db
+    .select()
+    .from(problems)
+    .where(eq(problems.patientId, patientId))
+    .orderBy(asc(problems.position));
+}
+
+export function encountersForPatient(
+  patientId: string,
+): Promise<EncounterRow[]> {
+  return db
+    .select()
+    .from(encounters)
+    .where(eq(encounters.patientId, patientId))
+    .orderBy(asc(encounters.position));
+}
+
+// --- Denormalized resources (linked to the patient by MRN / file number) ----
+
+export function prescriptionsForFile(
+  orgId: string,
+  fileNumber: string,
+): Promise<PrescriptionRow[]> {
+  return db
+    .select()
+    .from(prescriptions)
+    .where(
+      and(
+        eq(prescriptions.organizationId, orgId),
+        eq(prescriptions.patientFileNumber, fileNumber),
+      ),
+    )
+    .orderBy(sql`${prescriptions.prescribedAt} desc`);
+}
+
+export function appointmentsForFile(
+  orgId: string,
+  fileNumber: string,
+): Promise<AppointmentRow[]> {
+  return db
+    .select()
+    .from(appointments)
+    .where(
+      and(
+        eq(appointments.organizationId, orgId),
+        eq(appointments.patientFileNumber, fileNumber),
+      ),
+    )
+    .orderBy(sql`${appointments.date} desc, ${appointments.time} desc`);
+}

backend/src/services/fhir-server/resources.ts

@@ -0,0 +1,317 @@
+import type { LabFlag } from "../../types/patient.js";
+import type {
+  AllergyRow,
+  AppointmentRow,
+  EncounterRow,
+  LabRow,
+  PatientRow,
+  PrescriptionRow,
+  ProblemRow,
+} from "./queries.js";
+
+// Pure mappers from temetro rows to FHIR R4 JSON. temetro stores clinical values
+// as **free text** (no SNOMED/LOINC coding), so every CodeableConcept here is
+// `text`-only — valid FHIR, deliberately un-coded (documented in the
+// CapabilityStatement and API docs). Resource ids are the rows' own UUIDs so
+// they are stable; synthesized vital-sign Observations derive their id from the
+// patient UUID.
+
+export type FhirResource = {
+  resourceType: string;
+  id?: string;
+  [key: string]: unknown;
+};
+
+// System URIs.
+const MRN_SYSTEM = "urn:temetro:mrn";
+const INTERPRETATION_SYSTEM =
+  "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation";
+const OBS_CATEGORY_SYSTEM =
+  "http://terminology.hl7.org/CodeSystem/observation-category";
+const AGE_EXTENSION =
+  "https://temetro.app/fhir/StructureDefinition/patient-age-years";
+
+// A FHIR dateTime from our stored strings. Passes date-only values (`YYYY-MM-DD`)
+// through unchanged (valid FHIR dateTime), otherwise parses display strings like
+// "Jun 28, 2025" to a full instant. Returns undefined when unparseable.
+function fhirDateTime(value: string | null | undefined): string | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  if (/^\d{4}-\d{2}-\d{2}$/.test(trimmed)) return trimmed;
+  const parsed = new Date(trimmed);
+  return Number.isNaN(parsed.getTime()) ? undefined : parsed.toISOString();
+}
+
+function humanName(full: string): Record<string, unknown>[] {
+  const parts = full.trim().split(/\s+/).filter(Boolean);
+  if (parts.length < 2) return [{ text: full }];
+  return [{ text: full, family: parts.at(-1), given: parts.slice(0, -1) }];
+}
+
+function subjectRef(patient: PatientRow) {
+  return { reference: `Patient/${patient.id}`, display: patient.name };
+}
+
+// --- Patient ----------------------------------------------------------------
+
+export function patientResource(row: PatientRow): FhirResource {
+  return {
+    resourceType: "Patient",
+    id: row.id,
+    identifier: [{ system: MRN_SYSTEM, value: row.fileNumber }],
+    active: row.status !== "discharged",
+    name: humanName(row.name),
+    gender: row.sex === "M" ? "male" : "female",
+    // temetro records age, not date of birth; expose it as an extension rather
+    // than fabricate a birthDate.
+    extension: [{ url: AGE_EXTENSION, valueInteger: row.age }],
+  };
+}
+
+// --- Observation ------------------------------------------------------------
+
+function interpretation(flag: LabFlag) {
+  const map: Record<LabFlag, { code: string; display: string }> = {
+    normal: { code: "N", display: "Normal" },
+    high: { code: "H", display: "High" },
+    low: { code: "L", display: "Low" },
+    critical: { code: "HH", display: "Critical high" },
+  };
+  const { code, display } = map[flag];
+  return [{ coding: [{ system: INTERPRETATION_SYSTEM, code, display }] }];
+}
+
+export function labObservation(row: LabRow, patient: PatientRow): FhirResource {
+  const effective = fhirDateTime(row.takenAt);
+  return {
+    resourceType: "Observation",
+    id: row.id,
+    status: "final",
+    category: [
+      {
+        coding: [
+          {
+            system: OBS_CATEGORY_SYSTEM,
+            code: "laboratory",
+            display: "Laboratory",
+          },
+        ],
+      },
+    ],
+    code: { text: row.name },
+    subject: subjectRef(patient),
+    ...(effective ? { effectiveDateTime: effective } : {}),
+    valueString: row.value,
+    interpretation: interpretation(row.flag),
+  };
+}
+
+// Synthesize vital-sign Observations from the denormalized columns on the
+// patient row. Returns an empty array when vitals are blank (e.g. a
+// reception-registered patient with clinical fields stripped).
+export function vitalObservations(patient: PatientRow): FhirResource[] {
+  const effective = fhirDateTime(patient.vitalsTakenAt);
+  const base = (idSuffix: string, text: string) => ({
+    resourceType: "Observation" as const,
+    id: `${patient.id}-vital-${idSuffix}`,
+    status: "final",
+    category: [
+      {
+        coding: [
+          {
+            system: OBS_CATEGORY_SYSTEM,
+            code: "vital-signs",
+            display: "Vital Signs",
+          },
+        ],
+      },
+    ],
+    code: { text },
+    subject: subjectRef(patient),
+    ...(effective ? { effectiveDateTime: effective } : {}),
+  });
+
+  const out: FhirResource[] = [];
+
+  if (patient.vitalsBp) {
+    const bp = base("bp", "Blood pressure");
+    const m = /^(\d+)\s*\/\s*(\d+)/.exec(patient.vitalsBp.trim());
+    if (m) {
+      out.push({
+        ...bp,
+        component: [
+          {
+            code: { text: "Systolic blood pressure" },
+            valueQuantity: { value: Number(m[1]), unit: "mmHg" },
+          },
+          {
+            code: { text: "Diastolic blood pressure" },
+            valueQuantity: { value: Number(m[2]), unit: "mmHg" },
+          },
+        ],
+      });
+    } else {
+      out.push({ ...bp, valueString: patient.vitalsBp });
+    }
+  }
+  if (patient.vitalsHr)
+    out.push({ ...base("hr", "Heart rate"), valueString: patient.vitalsHr });
+  if (patient.vitalsTemp)
+    out.push({
+      ...base("temp", "Body temperature"),
+      valueString: patient.vitalsTemp,
+    });
+  if (patient.vitalsSpo2)
+    out.push({
+      ...base("spo2", "Oxygen saturation"),
+      valueString: patient.vitalsSpo2,
+    });
+
+  return out;
+}
+
+// --- AllergyIntolerance -----------------------------------------------------
+
+export function allergyResource(
+  row: AllergyRow,
+  patient: PatientRow,
+): FhirResource {
+  return {
+    resourceType: "AllergyIntolerance",
+    id: row.id,
+    clinicalStatus: {
+      coding: [
+        {
+          system:
+            "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
+          code: "active",
+        },
+      ],
+    },
+    code: { text: row.substance },
+    patient: subjectRef(patient),
+    criticality: row.severity === "severe" ? "high" : "low",
+    reaction: [
+      { manifestation: [{ text: row.reaction }], severity: row.severity },
+    ],
+  };
+}
+
+// --- Condition --------------------------------------------------------------
+
+export function conditionResource(
+  row: ProblemRow,
+  patient: PatientRow,
+): FhirResource {
+  return {
+    resourceType: "Condition",
+    id: row.id,
+    clinicalStatus: {
+      coding: [
+        {
+          system: "http://terminology.hl7.org/CodeSystem/condition-clinical",
+          code: "active",
+        },
+      ],
+    },
+    code: { text: row.label },
+    subject: subjectRef(patient),
+    ...(row.since ? { onsetString: row.since } : {}),
+  };
+}
+
+// --- MedicationRequest ------------------------------------------------------
+
+export function medicationRequestResource(
+  row: PrescriptionRow,
+  patient: PatientRow,
+): FhirResource {
+  const status =
+    row.status === "completed"
+      ? "completed"
+      : row.status === "expired"
+        ? "stopped"
+        : "active";
+  const dosageText = [row.dose, row.frequency].filter(Boolean).join(" ").trim();
+  return {
+    resourceType: "MedicationRequest",
+    id: row.id,
+    status,
+    intent: "order",
+    medicationCodeableConcept: { text: row.medication },
+    subject: subjectRef(patient),
+    ...(row.prescribedAt ? { authoredOn: row.prescribedAt } : {}),
+    requester: { display: row.prescriber },
+    ...(dosageText ? { dosageInstruction: [{ text: dosageText }] } : {}),
+  };
+}
+
+// --- Encounter --------------------------------------------------------------
+
+function narrative(text: string): Record<string, unknown> {
+  const escaped = text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+  return {
+    status: "generated",
+    div: `<div xmlns="http://www.w3.org/1999/xhtml">${escaped}</div>`,
+  };
+}
+
+export function encounterResource(
+  row: EncounterRow,
+  patient: PatientRow,
+): FhirResource {
+  const start = fhirDateTime(row.date);
+  return {
+    resourceType: "Encounter",
+    id: row.id,
+    ...(row.summary ? { text: narrative(row.summary) } : {}),
+    status: "finished",
+    class: {
+      system: "http://terminology.hl7.org/CodeSystem/v3-ActCode",
+      code: "AMB",
+      display: "ambulatory",
+    },
+    type: [{ text: row.type }],
+    subject: subjectRef(patient),
+    ...(start ? { period: { start } } : {}),
+    participant: [{ individual: { display: row.provider } }],
+  };
+}
+
+// --- Appointment ------------------------------------------------------------
+
+export function appointmentResource(
+  row: AppointmentRow,
+  patient: PatientRow,
+): FhirResource {
+  const statusMap: Record<string, string> = {
+    confirmed: "booked",
+    "checked-in": "arrived",
+    completed: "fulfilled",
+    cancelled: "cancelled",
+  };
+  // Combine local date + time into an instant; omit when unparseable.
+  const startDate =
+    row.date && row.time ? new Date(`${row.date}T${row.time}:00`) : null;
+  const start =
+    startDate && !Number.isNaN(startDate.getTime())
+      ? startDate.toISOString()
+      : undefined;
+  return {
+    resourceType: "Appointment",
+    id: row.id,
+    status: statusMap[row.status] ?? "booked",
+    description: row.type,
+    ...(start ? { start } : {}),
+    participant: [
+      { actor: subjectRef(patient), status: "accepted" },
+      ...(row.provider
+        ? [{ actor: { display: row.provider }, status: "accepted" }]
+        : []),
+    ],
+  };
+}

backend/src/services/patients.ts

@@ -53,6 +53,8 @@ function toPatient(row: PatientRow, children: Children): Patient {
     primaryProviderId: row.primaryProviderId,
     status: row.status,
     initials: row.initials,
+    phone: row.phone,
+    bloodType: row.bloodType,
     allergies: children.allergies,
     alerts: row.alerts,
     medications: children.medications,
@@ -82,6 +84,8 @@ const EMPTY_TREND: Trend = { label: "", unit: "", points: [] };
 function redactClinical(patient: Patient): Patient {
   return {
     ...patient,
+    // bloodType is clinical PHI; phone is a demographic/contact field and stays.
+    bloodType: "",
     allergies: [],
     alerts: [],
     medications: [],
@@ -116,6 +120,8 @@ function patientColumns(orgId: string, input: PatientInput, createdBy?: string)
     primaryProviderId: input.primaryProviderId ?? null,
     status: input.status,
     initials: input.initials,
+    phone: input.phone,
+    bloodType: input.bloodType,
     alerts: input.alerts,
     vitalsBp: input.vitals.bp,
     vitalsHr: input.vitals.hr,
@@ -147,6 +153,8 @@ function demographicColumns(
     primaryProviderId: input.primaryProviderId ?? null,
     status: input.status,
     initials: input.initials,
+    phone: input.phone,
+    bloodType: "",
     source: input.source,
     alerts: [] as string[],
     vitalsBp: "",
@@ -172,6 +180,7 @@ function demographicUpdateColumns(input: PatientInput) {
     primaryProviderId: input.primaryProviderId ?? null,
     status: input.status,
     initials: input.initials,
+    phone: input.phone,
   };
 }
 
@@ -570,6 +579,46 @@ export async function appendLabs(
   return getPatient(orgId, fileNumber);
 }
 
+// Append a single encounter (visit note) without touching the rest of the
+// record — used by the ambient AI scribe, which drafts one note at a time and
+// must not go through updatePatient's wholesale child replacement. Position
+// continues after the current max so the new note sorts last.
+export async function appendEncounter(
+  orgId: string,
+  fileNumber: string,
+  entry: Encounter,
+): Promise<Patient | null> {
+  const inserted = await db.transaction(async (tx) => {
+    const [existing] = await tx
+      .select({ id: patients.id })
+      .from(patients)
+      .where(
+        and(
+          eq(patients.organizationId, orgId),
+          eq(patients.fileNumber, fileNumber),
+        ),
+      );
+    if (!existing) return false;
+
+    const [pos] = await tx
+      .select({ max: sql<number>`coalesce(max(${encounters.position}), -1)` })
+      .from(encounters)
+      .where(eq(encounters.patientId, existing.id));
+    await tx.insert(encounters).values({
+      patientId: existing.id,
+      position: (pos?.max ?? -1) + 1,
+      ...entry,
+    });
+    await tx
+      .update(patients)
+      .set({ updatedAt: new Date() })
+      .where(eq(patients.id, existing.id));
+    return true;
+  });
+  if (!inserted) return null;
+  return getPatient(orgId, fileNumber);
+}
+
 // Remove a single lab result from a patient, identified by its
 // name/value/takenAt (the frontend has no row id). Scoped to the org via the
 // owning patient. Returns the reloaded patient, or null when the chart is gone.

backend/src/services/portal.ts

@@ -0,0 +1,290 @@
+// Patient Portal actions, shared by the public REST kiosk (routes/portal.ts)
+// and the relay path used by the wallet app (relay-client.ts handles
+// `portal:request` and dispatches here). Both go through the same clinic-scoped
+// logic so a booking made in the phone shows up on the clinic's Appointments
+// page exactly like a kiosk booking.
+//
+// The relay path identifies the patient by their *verified* wallet number (the
+// relay only forwards a request after the device signed the relay challenge),
+// which is more trustworthy than the kiosk's name + file-number check.
+
+import { readFile } from "node:fs/promises";
+
+import { and, asc, eq, inArray } from "drizzle-orm";
+
+import { db } from "../db/index.js";
+import { member, organization, user } from "../db/schema/auth.js";
+import { patients } from "../db/schema/patients.js";
+import { staffProfile } from "../db/schema/staff-profile.js";
+import { appointmentInputSchema } from "../lib/appointment-validation.js";
+import { HttpError } from "../lib/http-error.js";
+import { initialsFromName } from "../lib/initials.js";
+import { recordActivity } from "./activity.js";
+import { createAppointment, listAppointments } from "./appointments.js";
+import {
+  absolutePath,
+  getAttachmentRow,
+  listAttachments,
+} from "./attachments.js";
+import { getPatient } from "./patients.js";
+
+// Clinical-capable roles that can be a patient's provider (mirrors portal.ts).
+const PROVIDER_ROLES = ["owner", "admin", "doctor", "member"] as const;
+
+export type PortalDoctor = { name: string; specialty: string | null };
+
+export async function getClinicInfo(orgId: string): Promise<{ name: string }> {
+  const [org] = await db
+    .select({ name: organization.name })
+    .from(organization)
+    .where(eq(organization.id, orgId))
+    .limit(1);
+  if (!org) throw new HttpError(404, "Clinic not found.");
+  return { name: org.name };
+}
+
+export async function listDoctors(orgId: string): Promise<PortalDoctor[]> {
+  const rows = await db
+    .select({ name: user.name, specialty: staffProfile.specialty })
+    .from(member)
+    .innerJoin(user, eq(user.id, member.userId))
+    .leftJoin(
+      staffProfile,
+      and(
+        eq(staffProfile.userId, member.userId),
+        eq(staffProfile.organizationId, member.organizationId),
+      ),
+    )
+    .where(
+      and(
+        eq(member.organizationId, orgId),
+        inArray(member.role, PROVIDER_ROLES as unknown as string[]),
+      ),
+    )
+    .orderBy(asc(user.name));
+  return rows.map((r) => ({ name: r.name, specialty: r.specialty ?? null }));
+}
+
+// Taken time slots for a provider on a day, so the client renders only free
+// ones. Mirrors routes/portal.ts (an empty-provider appointment blocks the slot
+// clinic-wide). Booking re-checks server-side.
+export async function getAvailability(
+  orgId: string,
+  provider: string,
+  date: string,
+): Promise<{ date: string; provider: string; taken: string[] }> {
+  const taken = (await listAppointments(orgId))
+    .filter(
+      (a) =>
+        a.status !== "cancelled" &&
+        a.date === date &&
+        (!provider || !a.provider || a.provider === provider),
+    )
+    .map((a) => a.time);
+  return { date, provider, taken: [...new Set(taken)].sort() };
+}
+
+// --- wallet linkage ---------------------------------------------------------
+
+// Confirm the wallet link for a device. The wallet is identified purely by its
+// relay-verified wallet number — the clinic attaches that number to the patient
+// file ahead of time (via "Import from a patient app" / QR pairing, which sets
+// `patients.walletNumber`), so the device never types a name or file number.
+// Resolves the linked file, or a friendly 404 when the clinic hasn't paired yet.
+export async function linkWallet(
+  orgId: string,
+  walletNumber: string,
+): Promise<{ fileNumber: string; name: string }> {
+  if (!walletNumber) {
+    throw new HttpError(400, "Missing wallet identity.");
+  }
+  const fileNumber = await fileNumberForWallet(orgId, walletNumber);
+  if (!fileNumber) {
+    throw new HttpError(
+      404,
+      "This wallet isn't paired with a record at this clinic yet. Ask the front desk to add your wallet number, then try again.",
+    );
+  }
+  const patient = await getPatient(orgId, fileNumber);
+  if (!patient) throw new HttpError(404, "Linked record not found.");
+  await recordActivity({
+    orgId,
+    actor: { id: "", name: patient.name },
+    action: `Patient portal — ${patient.name} confirmed their wallet link`,
+    entityType: "patient",
+    entityId: patient.fileNumber,
+  });
+  return { fileNumber: patient.fileNumber, name: patient.name };
+}
+
+// The file number a linked wallet maps to, or null.
+export async function fileNumberForWallet(
+  orgId: string,
+  walletNumber: string,
+): Promise<string | null> {
+  const [row] = await db
+    .select({ fileNumber: patients.fileNumber })
+    .from(patients)
+    .where(
+      and(
+        eq(patients.organizationId, orgId),
+        eq(patients.walletNumber, walletNumber),
+      ),
+    )
+    .limit(1);
+  return row?.fileNumber ?? null;
+}
+
+async function requireLinkedPatient(orgId: string, walletNumber: string) {
+  const fileNumber = await fileNumberForWallet(orgId, walletNumber);
+  if (!fileNumber) {
+    throw new HttpError(403, "This wallet isn't linked to a record at this clinic.");
+  }
+  const patient = await getPatient(orgId, fileNumber);
+  if (!patient) throw new HttpError(404, "Linked record not found.");
+  return patient;
+}
+
+// Book an appointment for the linked wallet (conflict-checked), attributed to
+// the patient's file so it appears on the clinic's Appointments page.
+export async function bookForWallet(
+  orgId: string,
+  walletNumber: string,
+  body: { date: string; time: string; type?: string; provider?: string },
+): Promise<{ date: string; time: string; type: string; provider: string }> {
+  const patient = await requireLinkedPatient(orgId, walletNumber);
+
+  const today = new Date().toISOString().slice(0, 10);
+  if (body.date < today) throw new HttpError(400, "Please pick a future date.");
+
+  const input = appointmentInputSchema.parse({
+    fileNumber: patient.fileNumber,
+    name: patient.name,
+    initials: patient.initials || initialsFromName(patient.name),
+    date: body.date,
+    time: body.time,
+    type: body.type || "Self-service booking",
+    provider: body.provider || patient.pcp || "",
+    status: "confirmed",
+    source: "manual",
+  });
+
+  const taken = (await listAppointments(orgId)).some(
+    (a) =>
+      a.status !== "cancelled" &&
+      a.date === input.date &&
+      a.time === input.time &&
+      (!input.provider || !a.provider || a.provider === input.provider),
+  );
+  if (taken) {
+    throw new HttpError(409, "That time slot is already taken. Please choose another time.");
+  }
+
+  const created = await createAppointment(orgId, "", input);
+  await recordActivity({
+    orgId,
+    actor: { id: "", name: patient.name },
+    action: `Patient portal booking — ${patient.name} on ${created.date} ${created.time}`,
+    entityType: "appointment",
+    entityId: created.id,
+  });
+  return {
+    date: created.date,
+    time: created.time,
+    type: created.type,
+    provider: created.provider,
+  };
+}
+
+// Results view for the linked wallet: upcoming appointments + downloadable lab
+// files (metadata only; bytes come from `getResultFile`).
+export async function resultsForWallet(
+  orgId: string,
+  walletNumber: string,
+): Promise<{
+  name: string;
+  upcoming: { date: string; time: string; type: string; provider: string; status: string }[];
+  files: { id: string; filename: string; mimeType: string; sizeBytes: number; labKey: string | null }[];
+}> {
+  const patient = await requireLinkedPatient(orgId, walletNumber);
+  const now = new Date();
+  const upcoming = (await listAppointments(orgId))
+    .filter(
+      (a) =>
+        a.fileNumber === patient.fileNumber &&
+        a.status !== "cancelled" &&
+        new Date(`${a.date}T${a.time}`) >= now,
+    )
+    .map((a) => ({
+      date: a.date,
+      time: a.time,
+      type: a.type,
+      provider: a.provider,
+      status: a.status,
+    }));
+  const files = (await listAttachments(orgId, patient.fileNumber)).map((f) => ({
+    id: f.id,
+    filename: f.filename,
+    mimeType: f.mimeType,
+    sizeBytes: f.sizeBytes,
+    labKey: f.labKey,
+  }));
+  return { name: patient.name, upcoming, files };
+}
+
+// A single lab/result file for the linked wallet, base64-encoded so it can ride
+// back over the relay. Verifies the file belongs to the patient's own record.
+export async function resultFileForWallet(
+  orgId: string,
+  walletNumber: string,
+  attachmentId: string,
+): Promise<{ filename: string; mimeType: string; base64: string }> {
+  const patient = await requireLinkedPatient(orgId, walletNumber);
+  const row = await getAttachmentRow(orgId, attachmentId);
+  if (!row || row.fileNumber !== patient.fileNumber) {
+    throw new HttpError(404, "File not found.");
+  }
+  const bytes = await readFile(absolutePath(row.storagePath));
+  return {
+    filename: row.filename,
+    mimeType: row.mimeType,
+    base64: bytes.toString("base64"),
+  };
+}
+
+// --- relay dispatch ---------------------------------------------------------
+
+type PortalPayload = Record<string, unknown>;
+
+// Dispatch a `portal:request` relayed from a wallet device. `walletNumber` is
+// the device's relay-verified wallet number (empty for the public reads).
+export async function handlePortalRequest(
+  orgId: string,
+  req: { action: string; payload: PortalPayload; walletNumber: string },
+): Promise<unknown> {
+  const { action, payload, walletNumber } = req;
+  const s = (k: string): string => String(payload[k] ?? "");
+  switch (action) {
+    case "clinic":
+      return getClinicInfo(orgId);
+    case "doctors":
+      return listDoctors(orgId);
+    case "availability":
+      return getAvailability(orgId, s("provider"), s("date"));
+    case "link":
+      return linkWallet(orgId, walletNumber);
+    case "book":
+      return bookForWallet(orgId, walletNumber, {
+        date: s("date"),
+        time: s("time"),
+        type: s("type") || undefined,
+        provider: s("provider") || undefined,
+      });
+    case "results":
+      return resultsForWallet(orgId, walletNumber);
+    case "result-file":
+      return resultFileForWallet(orgId, walletNumber, s("id"));
+    default:
+      throw new HttpError(400, `Unknown portal action: ${action}`);
+  }
+}

backend/src/services/relay-client.ts

@@ -0,0 +1,249 @@
+// Client connection to the Temetro Network relay
+// (github.com/temetro/temetro-network), a standalone Rust service that routes
+// encrypted wallet messages between this backend and patient phones.
+//
+// This backend was previously the device-facing Socket.io server itself (the
+// `/wallet` namespace in realtime.ts). Now it is a *client* of the relay's
+// `/hub` namespace: it pushes messages to devices via `sendToWallet` and handles
+// their responses here, calling the same wallet service functions the old socket
+// handlers did. Sealed bundles are decrypted here (we hold the ephemeral key);
+// the relay only ever forwards ciphertext.
+//
+// The relay is **multi-clinic**: each clinic (organization) authenticates to
+// `/hub` with its own Ed25519 signing key (a per-clinic identity, not a shared
+// password), and the relay routes each device response back only to the clinic
+// that originated the request. So this backend keeps **one hub connection per
+// network-enabled org**, opened when the org joins the network ("Join Temetro
+// Network" in Settings → Signing) and torn down when it leaves.
+
+import { io as connect, type Socket } from "socket.io-client";
+
+import { env } from "../env.js";
+import { HttpError } from "../lib/http-error.js";
+import { handlePortalRequest } from "./portal.js";
+import { networkEnabledOrgs, signWithClinicKey } from "./signing.js";
+import * as walletShare from "./wallet-share.js";
+import * as walletUpdates from "./wallet-updates.js";
+
+// One authenticated hub connection per network-enabled organization.
+const hubs = new Map<string, Socket>();
+
+type Ack = (response: { ok: boolean; [key: string]: unknown }) => void;
+
+// Push an end-to-end-encrypted message to a patient wallet device via the given
+// clinic's relay connection (the relay forwards it to the room keyed by wallet
+// number). A no-op if the clinic isn't on the network / not connected yet — the
+// device replays anything it missed on its next connect (see `wallet:online`).
+export function sendToWallet(
+  orgId: string,
+  walletNumber: string,
+  event: string,
+  data: unknown,
+): void {
+  hubs.get(orgId)?.emit("wallet:send", { walletNumber, event, data });
+}
+
+// Tell the relay to expect a device response for `requestId` and route it back
+// to this clinic — used by **QR pairing**, where there's no wallet number to
+// `wallet:send` to yet, so nothing would otherwise register the request.
+export function expectResponse(orgId: string, requestId: string): void {
+  hubs.get(orgId)?.emit("hub:expect", { requestId });
+}
+
+// Open (and authenticate) a hub connection for a clinic, if not already open.
+// Idempotent — safe to call on startup, when an org joins the network, and
+// before generating a pairing QR. The socket auto-reconnects on its own, so an
+// existing entry is left as-is.
+export async function connectOrg(orgId: string): Promise<void> {
+  if (hubs.has(orgId)) return;
+
+  const hub = connect(`${env.RELAY_URL}/hub`, {
+    transports: ["websocket"],
+    reconnection: true,
+    reconnectionDelayMax: 10_000,
+  });
+  hubs.set(orgId, hub);
+  registerHubHandlers(orgId, hub);
+}
+
+// Leave the network for a clinic: close and forget its hub connection.
+export function disconnectOrg(orgId: string): void {
+  const hub = hubs.get(orgId);
+  if (!hub) return;
+  hub.disconnect();
+  hubs.delete(orgId);
+}
+
+// Open a hub connection for every clinic already on the network. Called once at
+// startup; runtime joins/leaves go through connectOrg/disconnectOrg.
+export async function initRelayClient(): Promise<void> {
+  try {
+    const orgs = await networkEnabledOrgs();
+    await Promise.all(orgs.map((orgId) => connectOrg(orgId)));
+  } catch (err) {
+    console.warn(`Temetro Network: failed to open hub connections: ${(err as Error).message}`);
+  }
+}
+
+// Wire up auth + device-response handlers for one clinic's hub socket.
+function registerHubHandlers(orgId: string, hub: Socket): void {
+  // Authenticate by signing the relay's challenge with this clinic's signing
+  // key. `clinicId` is that key's public half (hex), which is how the relay
+  // identifies and routes to this clinic.
+  hub.on("hub:challenge", async (payload: { challenge?: string }) => {
+    const challenge = String(payload?.challenge ?? "");
+    if (!challenge) return;
+    try {
+      const { signature, publicKey } = await signWithClinicKey(
+        orgId,
+        new TextEncoder().encode(challenge),
+      );
+      hub.emit(
+        "hub:auth",
+        // `token` is only meaningful for a private relay (optional shared gate);
+        // an empty value is ignored by an open relay.
+        { clinicId: publicKey, signature, token: env.RELAY_TOKEN || undefined },
+        async (ack: { ok?: boolean } | undefined) => {
+          if (!ack?.ok) {
+            console.warn(`Temetro Network: relay rejected clinic ${orgId}`);
+            return;
+          }
+          console.log(`Temetro Network: clinic ${orgId} authenticated on the relay`);
+          // The relay keeps routing state in memory, so re-register this clinic's
+          // still-pending requests — restores QR-pairing / share routing after a
+          // relay restart or a reconnect.
+          try {
+            for (const requestId of await walletShare.pendingRequestIds(orgId)) {
+              expectResponse(orgId, requestId);
+            }
+          } catch {
+            /* best-effort */
+          }
+        },
+      );
+    } catch (err) {
+      console.warn(`Temetro Network: failed to sign relay challenge for ${orgId}: ${(err as Error).message}`);
+    }
+  });
+
+  hub.on("connect_error", (err) => {
+    console.warn(`Temetro Network relay unreachable (${env.RELAY_URL}) for ${orgId}: ${err.message}`);
+  });
+
+  // A device authenticated on the relay — flush any record updates it missed
+  // while offline (scoped to this clinic; the relay only delivers this to
+  // clinics with pending work for the wallet).
+  hub.on("wallet:online", async (payload: { walletNumber?: string }) => {
+    const walletNumber = String(payload?.walletNumber ?? "");
+    if (!walletNumber) return;
+    try {
+      const rows = await walletUpdates.pendingUpdatesForWallet(orgId, walletNumber);
+      for (const row of rows) {
+        sendToWallet(orgId, walletNumber, "wallet:update-request", await walletUpdates.toEvent(row));
+        await walletUpdates.markDelivered(row.id);
+      }
+    } catch {
+      /* best-effort */
+    }
+  });
+
+  // The patient approved/denied a clinic→wallet record update. Verify the
+  // wallet's signature over the decision and resolve the row.
+  hub.on(
+    "wallet:update-response",
+    async (
+      payload: {
+        requestId?: string;
+        walletNumber?: string;
+        decision?: "approved" | "denied";
+        signature?: string;
+      },
+      ack?: Ack,
+    ) => {
+      try {
+        const view = await walletUpdates.applyUpdateResponse(
+          String(payload?.requestId ?? ""),
+          String(payload?.walletNumber ?? ""),
+          payload?.decision === "approved" ? "approved" : "denied",
+          payload?.signature,
+        );
+        ack?.({ ok: !!view });
+      } catch (err) {
+        ack?.({ ok: false, error: (err as Error).message });
+      }
+    },
+  );
+
+  // The patient approved/denied a share; the sealed bundle (if approved) rides
+  // along and is decrypted + verified here.
+  hub.on(
+    "wallet:share-response",
+    async (
+      payload: {
+        requestId?: string;
+        walletNumber?: string;
+        decision?: "approved" | "denied";
+        sealed?: string;
+        signature?: string;
+      },
+      ack?: Ack,
+    ) => {
+      try {
+        const view = await walletShare.applyShareResponse(
+          String(payload?.requestId ?? ""),
+          String(payload?.walletNumber ?? ""),
+          payload?.decision === "approved" ? "approved" : "denied",
+          payload?.sealed,
+          payload?.signature,
+        );
+        ack?.({ ok: !!view });
+      } catch (err) {
+        ack?.({ ok: false, error: (err as Error).message });
+      }
+    },
+  );
+
+  // A wallet app made a Patient Portal request over the relay (book, view
+  // results, link, …). The relay forwards it here with the device's verified
+  // wallet number; we run the same portal logic the web kiosk uses and ack the
+  // result back down the relay to the device.
+  hub.on(
+    "portal:request",
+    async (
+      payload: {
+        action?: string;
+        payload?: Record<string, unknown>;
+        walletNumber?: string;
+      },
+      ack?: Ack,
+    ) => {
+      try {
+        const data = await handlePortalRequest(orgId, {
+          action: String(payload?.action ?? ""),
+          payload: payload?.payload ?? {},
+          walletNumber: String(payload?.walletNumber ?? ""),
+        });
+        ack?.({ ok: true, data });
+      } catch (err) {
+        const status = err instanceof HttpError ? err.status : 500;
+        ack?.({ ok: false, error: (err as Error).message, status });
+      }
+    },
+  );
+
+  // The patient revoked a previously shared record; delete it from the clinic.
+  hub.on(
+    "wallet:revoke",
+    async (payload: { requestId?: string; walletNumber?: string }, ack?: Ack) => {
+      try {
+        const result = await walletShare.revokeShare(
+          String(payload?.requestId ?? ""),
+          String(payload?.walletNumber ?? ""),
+        );
+        ack?.({ ok: !!result });
+      } catch {
+        ack?.({ ok: false });
+      }
+    },
+  );
+}

backend/src/services/signing.ts

@@ -74,6 +74,40 @@ export async function rotateKey(orgId: string): Promise<SigningKeyView> {
   return mintKey(orgId, true);
 }
 
+// Whether this clinic has joined the Temetro Network relay. Defaults to `false`
+// when the clinic has no signing key yet (it hasn't opted in).
+export async function getNetworkEnabled(orgId: string): Promise<boolean> {
+  const [row] = await db
+    .select({ networkEnabled: clinicSigningKeys.networkEnabled })
+    .from(clinicSigningKeys)
+    .where(eq(clinicSigningKeys.organizationId, orgId));
+  return row?.networkEnabled ?? false;
+}
+
+// Org ids of every clinic currently on the network — used at startup to open a
+// relay hub connection for each.
+export async function networkEnabledOrgs(): Promise<string[]> {
+  const rows = await db
+    .select({ organizationId: clinicSigningKeys.organizationId })
+    .from(clinicSigningKeys)
+    .where(eq(clinicSigningKeys.networkEnabled, true));
+  return rows.map((r) => r.organizationId);
+}
+
+// Join or leave the Temetro Network. Ensures the clinic has a signing key first
+// (the relay authenticates with it), then flips the flag. Returns the new state.
+export async function setNetworkEnabled(
+  orgId: string,
+  enabled: boolean,
+): Promise<boolean> {
+  await getOrCreateKey(orgId);
+  await db
+    .update(clinicSigningKeys)
+    .set({ networkEnabled: enabled })
+    .where(eq(clinicSigningKeys.organizationId, orgId));
+  return enabled;
+}
+
 // Sign a message with the clinic's signing key (creating one if needed). Returns
 // the signature + public key so a verifier can check provenance.
 export async function signWithClinicKey(

backend/src/services/wallet-share.ts

@@ -137,6 +137,22 @@ export async function listShareRequests(
   return rows.map(toView);
 }
 
+// Ids of this clinic's still-pending share/pairing requests. Used to re-register
+// them with the relay when the clinic's hub (re)connects (the relay keeps
+// routing state in memory, so it's lost on a relay restart / redeploy).
+export async function pendingRequestIds(orgId: string): Promise<string[]> {
+  const rows = await db
+    .select({ id: walletShareRequests.id })
+    .from(walletShareRequests)
+    .where(
+      and(
+        eq(walletShareRequests.organizationId, orgId),
+        eq(walletShareRequests.status, "pending"),
+      ),
+    );
+  return rows.map((r) => r.id);
+}
+
 // Apply a response relayed back from the patient's device. On approval we
 // decrypt the sealed bundle with the request's ephemeral private key and verify
 // the wallet's Ed25519 signature over it (provenance: it really came from that

backend/src/services/wallet-updates.ts

@@ -0,0 +1,272 @@
+import { hexToBytes, utf8ToBytes } from "@noble/hashes/utils.js";
+import { and, desc, eq, isNotNull, isNull } from "drizzle-orm";
+
+import { db } from "../db/index.js";
+import { organization } from "../db/schema/auth.js";
+import { patients } from "../db/schema/patients.js";
+import { walletRecordUpdates } from "../db/schema/wallet-updates.js";
+import { walletShareRequests } from "../db/schema/wallet-share.js";
+import { HttpError } from "../lib/http-error.js";
+import {
+  decodeWalletNumber,
+  fingerprint,
+  seal,
+  verifySignature,
+} from "../lib/wallet-crypto.js";
+import { ed25519PubToX25519Hex } from "../lib/wallet-x25519.js";
+import { listAppointments } from "./appointments.js";
+import { listInvoices } from "./invoices.js";
+import { getPatient } from "./patients.js";
+import { signWithClinicKey } from "./signing.js";
+
+type UpdateRow = typeof walletRecordUpdates.$inferSelect;
+
+// The payload the relay pushes to a wallet. `sealed` is the encrypted patient
+// snapshot; `signature`/`clinicPublicKey`/`fingerprint` let the wallet verify
+// provenance (TOFU pin) before applying.
+export type WalletUpdateEvent = {
+  requestId: string;
+  clinicName: string;
+  sealed: string;
+  signature: string;
+  clinicPublicKey: string;
+  fingerprint: string;
+  changes: string[];
+  createdAt: string;
+};
+
+// The clinic-facing view (no ciphertext) for the "Sent updates" list + polling.
+export type WalletUpdateView = {
+  id: string;
+  fileNumber: string;
+  walletNumber: string;
+  status: UpdateRow["status"];
+  changes: string[];
+  createdAt: string;
+  deliveredAt: string | null;
+  resolvedAt: string | null;
+};
+
+export function viewOf(row: UpdateRow): WalletUpdateView {
+  return toView(row);
+}
+
+function toView(row: UpdateRow): WalletUpdateView {
+  return {
+    id: row.id,
+    fileNumber: row.fileNumber,
+    walletNumber: row.walletNumber,
+    status: row.status,
+    changes: row.changes,
+    createdAt: row.createdAt.toISOString(),
+    deliveredAt: row.deliveredAt ? row.deliveredAt.toISOString() : null,
+    resolvedAt: row.resolvedAt ? row.resolvedAt.toISOString() : null,
+  };
+}
+
+// The wallet number a patient's record is linked to, or null when it isn't
+// wallet-backed. Only *permanent, approved, committed* shares qualify —
+// temporary shares auto-delete, so pushing an update to them is meaningless.
+export async function walletNumberForPatient(
+  orgId: string,
+  fileNumber: string,
+): Promise<string | null> {
+  // Preferred: the wallet number the patient linked from the Patient Portal
+  // (stored directly on the file). Falls back to a permanent, approved,
+  // committed share for records imported the older way.
+  const [linked] = await db
+    .select({ walletNumber: patients.walletNumber })
+    .from(patients)
+    .where(
+      and(
+        eq(patients.organizationId, orgId),
+        eq(patients.fileNumber, fileNumber),
+        isNotNull(patients.walletNumber),
+      ),
+    )
+    .limit(1);
+  if (linked?.walletNumber) return linked.walletNumber;
+
+  const [row] = await db
+    .select({ walletNumber: walletShareRequests.walletNumber })
+    .from(walletShareRequests)
+    .where(
+      and(
+        eq(walletShareRequests.organizationId, orgId),
+        eq(walletShareRequests.committedFileNumber, fileNumber),
+        eq(walletShareRequests.status, "approved"),
+        eq(walletShareRequests.shareMode, "permanent"),
+        isNotNull(walletShareRequests.walletNumber),
+      ),
+    )
+    .limit(1);
+  return row?.walletNumber ?? null;
+}
+
+// Compose, seal and sign a record-update push, and store it as pending. Loads
+// the current patient snapshot, seals it to the wallet's derived X25519 key, and
+// signs the plaintext bundle with the clinic's Ed25519 key. Returns the row.
+export async function createRecordUpdate(
+  orgId: string,
+  userId: string,
+  fileNumber: string,
+  changes: string[],
+): Promise<UpdateRow> {
+  const walletNumber = await walletNumberForPatient(orgId, fileNumber);
+  if (!walletNumber) {
+    throw new HttpError(409, "This patient is not linked to a wallet.");
+  }
+  const patient = await getPatient(orgId, fileNumber);
+  if (!patient) throw new HttpError(404, "Patient not found.");
+
+  // Appointments and invoices live in their own tables (not on the Patient
+  // snapshot), so pull the ones for this patient and ship them alongside — the
+  // wallet has no other way to see them and they'd otherwise silently vanish.
+  const [orgAppointments, orgInvoices] = await Promise.all([
+    listAppointments(orgId),
+    listInvoices(orgId),
+  ]);
+  const appointments = orgAppointments.filter(
+    (a) => a.fileNumber === fileNumber,
+  );
+  const invoices = orgInvoices.filter((i) => i.fileNumber === fileNumber);
+
+  // The wallet opens this, verifies the signature over the same bytes, then
+  // replaces its on-device record with `patient` (+ appointments/invoices).
+  const bundle = utf8ToBytes(
+    JSON.stringify({ patient, appointments, invoices, changes }),
+  );
+  const { signature, publicKey } = await signWithClinicKey(orgId, bundle);
+  const x25519Hex = ed25519PubToX25519Hex(decodeWalletNumber(walletNumber));
+  const sealed = seal(x25519Hex, bundle);
+
+  const [row] = await db
+    .insert(walletRecordUpdates)
+    .values({
+      organizationId: orgId,
+      createdBy: userId,
+      fileNumber,
+      walletNumber,
+      payloadSealed: sealed,
+      clinicSignature: signature,
+      clinicPublicKey: publicKey,
+      clinicFingerprint: fingerprint(hexToBytes(publicKey)),
+      changes,
+    })
+    .returning();
+  return row!;
+}
+
+// Build the wire event for a stored update row (joins the clinic name).
+export async function toEvent(row: UpdateRow): Promise<WalletUpdateEvent> {
+  const [org] = await db
+    .select({ name: organization.name })
+    .from(organization)
+    .where(eq(organization.id, row.organizationId));
+  return {
+    requestId: row.id,
+    clinicName: org?.name ?? "A clinic",
+    sealed: row.payloadSealed,
+    signature: row.clinicSignature,
+    clinicPublicKey: row.clinicPublicKey,
+    fingerprint: row.clinicFingerprint,
+    changes: row.changes,
+    createdAt: row.createdAt.toISOString(),
+  };
+}
+
+// Every unresolved update for a wallet — re-sent on each authenticated connect
+// so an offline device eventually receives what it missed.
+// Pending updates a wallet missed, scoped to one clinic — the relay delivers a
+// `wallet:online` over that clinic's own hub connection, so a clinic only ever
+// re-sends its *own* updates (never another clinic's).
+export async function pendingUpdatesForWallet(
+  orgId: string,
+  walletNumber: string,
+): Promise<UpdateRow[]> {
+  return db
+    .select()
+    .from(walletRecordUpdates)
+    .where(
+      and(
+        eq(walletRecordUpdates.organizationId, orgId),
+        eq(walletRecordUpdates.walletNumber, walletNumber),
+        isNull(walletRecordUpdates.resolvedAt),
+      ),
+    )
+    .orderBy(walletRecordUpdates.createdAt);
+}
+
+// Mark a pending update delivered (best-effort; only advances from pending).
+export async function markDelivered(id: string): Promise<void> {
+  await db
+    .update(walletRecordUpdates)
+    .set({ status: "delivered", deliveredAt: new Date() })
+    .where(
+      and(
+        eq(walletRecordUpdates.id, id),
+        eq(walletRecordUpdates.status, "pending"),
+      ),
+    );
+}
+
+// Apply the patient's decision relayed back from the wallet. Verifies the
+// wallet's Ed25519 signature over `${decision}:${requestId}` (provenance) before
+// resolving. Returns the resolved view, or null when unknown/already resolved.
+export async function applyUpdateResponse(
+  requestId: string,
+  walletNumber: string,
+  decision: "approved" | "denied",
+  signatureHex?: string,
+): Promise<WalletUpdateView | null> {
+  const [row] = await db
+    .select()
+    .from(walletRecordUpdates)
+    .where(eq(walletRecordUpdates.id, requestId));
+  if (!row || row.resolvedAt) return null;
+  if (row.walletNumber !== walletNumber.trim()) return null;
+  if (!signatureHex) return null;
+
+  const publicKey = decodeWalletNumber(walletNumber);
+  const message = utf8ToBytes(`${decision}:${requestId}`);
+  if (!verifySignature(publicKey, signatureHex, message)) {
+    throw new HttpError(400, "Response signature did not match the wallet.");
+  }
+
+  const [updated] = await db
+    .update(walletRecordUpdates)
+    .set({ status: decision, resolvedAt: new Date() })
+    .where(eq(walletRecordUpdates.id, requestId))
+    .returning();
+  return updated ? toView(updated) : null;
+}
+
+// Recent update pushes for the clinic (Signing panel "Sent updates" list).
+export async function listUpdates(
+  orgId: string,
+  limit = 30,
+): Promise<WalletUpdateView[]> {
+  const rows = await db
+    .select()
+    .from(walletRecordUpdates)
+    .where(eq(walletRecordUpdates.organizationId, orgId))
+    .orderBy(desc(walletRecordUpdates.createdAt))
+    .limit(limit);
+  return rows.map(toView);
+}
+
+export async function getUpdate(
+  orgId: string,
+  id: string,
+): Promise<WalletUpdateView | null> {
+  const [row] = await db
+    .select()
+    .from(walletRecordUpdates)
+    .where(
+      and(
+        eq(walletRecordUpdates.id, id),
+        eq(walletRecordUpdates.organizationId, orgId),
+      ),
+    );
+  return row ? toView(row) : null;
+}

backend/src/types/express.d.ts

@@ -15,6 +15,9 @@ declare global {
       };
       organizationId?: string;
       memberRole?: string;
+      // Set by the FHIR bearer-auth middleware (machine-to-machine API key)
+      // instead of a Better Auth session; used for org scoping + audit.
+      fhirKey?: { id: string; name: string };
     }
   }
 }

backend/src/types/patient.ts

@@ -61,6 +61,8 @@ export type Patient = {
   primaryProviderId?: string | null; // user id of the responsible clinician
   status: PatientStatus;
   initials: string; // for AvatarFallback
+  phone?: string; // contact number (demographic; visible to reception)
+  bloodType?: string; // e.g. "O+"; clinical — redacted for reception
   allergies: Allergy[];
   alerts: string[];
   medications: Medication[];

frontend/CLAUDE.md

@@ -104,12 +104,18 @@ white/6%), so layered surfaces stay close in lightness.
 
 ## i18n
 
-`i18next` + `react-i18next` (config in `lib/i18n/config.ts`, English resources in
-`lib/i18n/locales/en/translation.json`). `components/i18n-provider.tsx` wraps the app in
+`i18next` + `react-i18next` (config in `lib/i18n/config.ts`, resources in
+`lib/i18n/locales/<lng>/translation.json`). `components/i18n-provider.tsx` wraps the app in
 `app/layout.tsx`. Use `const { t } = useTranslation()` + nested keys (e.g. `t("auth.login.title")`)
 in **client** components. To add a language, drop a `locales/<lng>/translation.json` and register it
 in `resources`/`supportedLngs` in `config.ts`.
 
+> **Translate into EVERY locale, not just English.** The app ships multiple languages
+> (`lib/i18n/locales/`: currently `en`, `de`, `fr`, `ar`, `so`). Whenever you add or rename a
+> translation key, add it to **all** `locales/*/translation.json` files with a real translation for
+> each language (not the English string copied over) — leaving a key in only `en/` ships a broken UI
+> in the others. Keep the nested structure identical across every locale file.
+
 **Coverage:** essentially all user-facing strings are now keyed (every app page + its dialogs/sheets,
 auth pages, settings panels, the sidebar/user menu, chat input, patient cards/detail/form, messages,
 notifications, notes). Keys are grouped by feature (`appointments.*`, `patientCard.*`, `messages.*`,

frontend/app/globals.css

@@ -7,9 +7,11 @@
 @theme inline {
   --color-background: var(--background);
   --color-foreground: var(--foreground);
-  --font-sans: var(--font-sans);
+  /* Append the Arabic face so Arabic codepoints fall through per-character even
+     in LTR locales; Latin text still renders in Inter. See app/layout.tsx. */
+  --font-sans: var(--font-sans), var(--font-arabic);
   --font-mono: var(--font-mono);
-  --font-heading: var(--font-heading);
+  --font-heading: var(--font-heading), var(--font-arabic);
   --color-sidebar-ring: var(--sidebar-ring);
   --color-sidebar-border: var(--sidebar-border);
   --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);

frontend/app/layout.tsx

@@ -1,5 +1,5 @@
 import type { Metadata } from "next";
-import { Geist_Mono, Inter } from "next/font/google";
+import { Geist_Mono, IBM_Plex_Sans_Arabic, Inter } from "next/font/google";
 import "./globals.css";
 import { cn } from "@/lib/utils";
 import { ThemeProvider } from "@/components/theme-provider";
@@ -10,6 +10,27 @@ import { ToastProvider } from "@/components/ui/toast";
 const inter = Inter({ subsets: ["latin"], variable: "--font-sans" });
 const interHeading = Inter({ subsets: ["latin"], variable: "--font-heading" });
 const geistMono = Geist_Mono({ subsets: ["latin"], variable: "--font-mono" });
+// Arabic-capable fallback: Inter has no Arabic glyphs, so we append this to the
+// sans/heading stacks (see globals.css) for per-character fallback in every
+// locale, and rely on it fully when dir="rtl". Not a variable font — pin weights.
+const plexArabic = IBM_Plex_Sans_Arabic({
+  subsets: ["arabic"],
+  weight: ["400", "500", "600", "700"],
+  variable: "--font-arabic",
+});
+
+// Runs before first paint: mirror lib/i18n/config.ts `dirFor` so an Arabic user
+// gets dir="rtl" immediately instead of a flash of LTR. Detection order matches
+// i18next-browser-languagedetector (localStorage key "i18nextLng", then the
+// browser language). suppressHydrationWarning on <html> ignores the attr diff.
+const setInitialDir = `
+(function(){try{
+  var l=localStorage.getItem("i18nextLng")||navigator.language||"en";
+  var e=document.documentElement;
+  e.lang=l;
+  e.dir=l.indexOf("ar")===0?"rtl":"ltr";
+}catch(_){}})();
+`;
 
 export const metadata: Metadata = {
   title: "temetro — AI assistant for clinicians",
@@ -33,17 +54,22 @@ export default function RootLayout({
         inter.variable,
         interHeading.variable,
         geistMono.variable,
+        plexArabic.variable,
         "font-sans"
       )}
     >
       {/* suppressHydrationWarning: next-themes sets the theme class on <html>
-          before hydration, and browser extensions (e.g. ColorZilla's
-          cz-shortcut-listen) mutate <body>. Only ignores attribute diffs on
-          those elements, not their children. */}
+          before hydration, the dir script below sets lang/dir, and browser
+          extensions (e.g. ColorZilla's cz-shortcut-listen) mutate <body>. Only
+          ignores attribute diffs on those elements, not their children. */}
       <body
         className="h-dvh overflow-hidden flex flex-col"
         suppressHydrationWarning
       >
+        <script
+          // Sets <html dir/lang> before paint; see setInitialDir above.
+          dangerouslySetInnerHTML={{ __html: setInitialDir }}
+        />
         <ThemeProvider
           attribute="class"
           defaultTheme="dark"

frontend/components/activity/activity-view.tsx

@@ -28,6 +28,7 @@ import {
   DialogTitle,
 } from "@/components/ui/dialog";
 import { Button } from "@/components/ui/button";
+import { ListPagination } from "@/components/ui/list-pagination";
 import {
   type ActivityEntityType,
   type ActivityEntry,
@@ -103,15 +104,19 @@ function DetailRow({ label, value }: { label: string; value: string }) {
   return (
     <div className="flex items-baseline justify-between gap-3">
       <span className="shrink-0 text-muted-foreground text-xs">{label}</span>
-      <span className="text-right text-foreground text-sm">{value}</span>
+      <span className="text-end text-foreground text-sm">{value}</span>
     </div>
   );
 }
 
+// Entries shown per page in the activity feed before paginating.
+const PAGE_SIZE = 10;
+
 export function ActivityView() {
   const { t } = useTranslation();
   const [entries, setEntries] = useState<ActivityEntry[]>([]);
   const [selected, setSelected] = useState<ActivityEntry | null>(null);
+  const [page, setPage] = useState(1);
 
   useEffect(() => {
     let active = true;
@@ -153,6 +158,15 @@ export function ActivityView() {
     ];
   }, [entries, t]);
 
+  // Client-side pagination over the feed (10/page). `page` is clamped at render
+  // so a shrinking feed never leaves us past the last page.
+  const totalPages = Math.max(1, Math.ceil(entries.length / PAGE_SIZE));
+  const safePage = Math.min(page, totalPages);
+  const pageRows = entries.slice(
+    (safePage - 1) * PAGE_SIZE,
+    safePage * PAGE_SIZE,
+  );
+
   return (
     <div className="mx-auto flex w-full max-w-3xl flex-col gap-10 px-6 py-10">
       <div>
@@ -173,10 +187,11 @@ export function ActivityView() {
           {t("activity.empty")}
         </div>
       ) : (
+        <div>
         <ol className="flex flex-col">
-          {entries.map((entry, i) => {
+          {pageRows.map((entry, i) => {
             const Icon = entityIcon[entry.entityType] ?? FileText;
-            const isLast = i === entries.length - 1;
+            const isLast = i === pageRows.length - 1;
             const context = [
               entry.actorName,
               entry.patientName &&
@@ -197,7 +212,7 @@ export function ActivityView() {
 
                 <button
                   className={cn(
-                    "-mx-2 flex-1 rounded-lg px-2 py-1 text-left transition-colors hover:bg-accent/40",
+                    "-mx-2 flex-1 rounded-lg px-2 py-1 text-start transition-colors hover:bg-accent/40",
                     isLast ? "pb-1" : "mb-5",
                   )}
                   onClick={() => setSelected(entry)}
@@ -226,6 +241,13 @@ export function ActivityView() {
             );
           })}
         </ol>
+        <ListPagination
+          onPageChange={setPage}
+          page={safePage}
+          pageSize={PAGE_SIZE}
+          total={entries.length}
+        />
+        </div>
       )}
 
       <Dialog

frontend/components/analysis/trend-card.tsx

@@ -37,7 +37,7 @@ export function TrendCard({
   return (
     <>
       <button
-        className="w-full text-left"
+        className="w-full text-start"
         disabled={!hasData}
         onClick={() => setOpen(true)}
         type="button"

frontend/components/appointments/add-appointment-dialog.tsx

@@ -23,6 +23,11 @@ import { Popover, PopoverPopup, PopoverTrigger } from "@/components/ui/popover";
 import { listPatients, type Patient } from "@/lib/patients";
 import { listProviders, type Provider } from "@/lib/staff";
 import { notify } from "@/lib/toast";
+import { useWalletSync } from "@/components/wallet/use-wallet-sync";
+import {
+  DialogStepper,
+  WalletSyncStep,
+} from "@/components/wallet/wallet-sync-step";
 
 export type NewAppointment = {
   fileNumber: string;
@@ -51,6 +56,14 @@ const TYPES = [
 const controlClass =
   "h-9 w-full rounded-3xl border border-transparent bg-input/50 px-3 text-sm text-foreground outline-none transition-[color,box-shadow] focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/30";
 
+// Local start-of-day so the calendar can disable days strictly before today
+// (appointments can't be scheduled in the past).
+const startOfToday = () => {
+  const d = new Date();
+  d.setHours(0, 0, 0, 0);
+  return d;
+};
+
 function Field({ label, children }: { label: string; children: ReactNode }) {
   return (
     <label className="flex flex-col gap-1.5">
@@ -70,7 +83,7 @@ export function AddAppointmentDialog({
 }: {
   open: boolean;
   onOpenChange: (open: boolean) => void;
-  onAdd: (appt: NewAppointment) => void;
+  onAdd: (appt: NewAppointment) => void | Promise<void>;
 }) {
   const { t } = useTranslation();
   const [patients, setPatients] = useState<Patient[]>([]);
@@ -82,6 +95,10 @@ export function AddAppointmentDialog({
   const [type, setType] = useState(TYPES[0]);
   const [provider, setProvider] = useState("");
   const [providerQuery, setProviderQuery] = useState("");
+  const [step, setStep] = useState<"form" | "wallet">("form");
+  const [walletSummary, setWalletSummary] = useState("");
+
+  const sync = useWalletSync(selected?.fileNumber ?? null);
 
   // Load patients + providers lazily when the dialog opens (for the searches).
   useEffect(() => {
@@ -147,7 +164,16 @@ export function AddAppointmentDialog({
     setProviderQuery("");
   };
 
-  const submit = (event: FormEvent) => {
+  const handleOpenChange = (o: boolean) => {
+    onOpenChange(o);
+    if (!o) {
+      reset();
+      setStep("form");
+      sync.reset();
+    }
+  };
+
+  const submit = async (event: FormEvent) => {
     event.preventDefault();
     if (!selected) {
       notify.error(
@@ -156,7 +182,7 @@ export function AddAppointmentDialog({
       );
       return;
     }
-    onAdd({
+    await onAdd({
       fileNumber: selected.fileNumber,
       name: selected.name,
       initials: selected.initials,
@@ -169,26 +195,36 @@ export function AddAppointmentDialog({
       t("appointments.dialog.addedTitle"),
       `${selected.name} · ${time}`,
     );
-    reset();
-    onOpenChange(false);
+    if (sync.linked) {
+      setWalletSummary(
+        t("walletSync.summary.appointment", { date: keyOf(date), time }),
+      );
+      setStep("wallet");
+    } else {
+      reset();
+      onOpenChange(false);
+    }
   };
 
   return (
-    <Dialog
-      onOpenChange={(o) => {
-        onOpenChange(o);
-        if (!o) reset();
-      }}
-      open={open}
-    >
-      <DialogPopup className="sm:max-w-md">
+    <Dialog onOpenChange={handleOpenChange} open={open}>
+      <DialogPopup className="flex max-h-[85dvh] flex-col sm:max-w-md">
         <DialogHeader>
           <DialogTitle>{t("appointments.dialog.title")}</DialogTitle>
           <DialogDescription>
             {t("appointments.dialog.description")}
           </DialogDescription>
+          {sync.linked && <DialogStepper step={step} />}
         </DialogHeader>
 
+        {step === "wallet" ? (
+          <WalletSyncStep
+            onDone={() => handleOpenChange(false)}
+            patientName={selected?.name ?? ""}
+            summary={walletSummary}
+            sync={sync}
+          />
+        ) : (
         <form className="contents" onSubmit={submit}>
           <DialogPanel className="flex flex-col gap-4">
             <Field label={t("appointments.dialog.patient")}>
@@ -251,6 +287,7 @@ export function AddAppointmentDialog({
                   />
                   <PopoverPopup>
                     <Calendar
+                      disabled={{ before: startOfToday() }}
                       mode="single"
                       onSelect={(d) => {
                         if (d) {
@@ -311,6 +348,7 @@ export function AddAppointmentDialog({
             </Button>
           </DialogFooter>
         </form>
+        )}
       </DialogPopup>
     </Dialog>
   );

frontend/components/appointments/appointments-view.tsx

@@ -314,9 +314,9 @@ export function AppointmentsView() {
         </div>
         <div className="flex items-center gap-2">
           <div className="relative">
-            <Search className="-translate-y-1/2 absolute top-1/2 left-3 size-4 text-muted-foreground" />
+            <Search className="-translate-y-1/2 absolute top-1/2 start-3 size-4 text-muted-foreground" />
             <Input
-              className="w-full pl-9 sm:w-64"
+              className="w-full ps-9 sm:w-64"
               onChange={(event) => setQuery(event.target.value)}
               placeholder={t("appointments.searchPlaceholder")}
               value={query}

frontend/components/appointments/calendar-dialog.tsx

@@ -145,7 +145,7 @@ export function CalendarDialog({
                 type="button"
                 variant="ghost"
               >
-                <ChevronLeft />
+                <ChevronLeft className="rtl:rotate-180" />
               </Button>
               <Button
                 aria-label="Next month"
@@ -154,7 +154,7 @@ export function CalendarDialog({
                 type="button"
                 variant="ghost"
               >
-                <ChevronRight />
+                <ChevronRight className="rtl:rotate-180" />
               </Button>
             </div>
           </div>
@@ -182,7 +182,7 @@ export function CalendarDialog({
                 return (
                   <button
                     className={cn(
-                      "flex min-h-22 flex-col gap-1 rounded-lg border p-1.5 text-left align-top transition-colors hover:bg-accent/50",
+                      "flex min-h-22 flex-col gap-1 rounded-lg border p-1.5 text-start align-top transition-colors hover:bg-accent/50",
                       inMonth
                         ? "bg-card/30"
                         : "bg-transparent text-muted-foreground/40",

frontend/components/auth/app-auth-guard.tsx

@@ -5,6 +5,7 @@ import { type ReactNode, useEffect, useRef } from "react";
 
 import { useAiAccess } from "@/lib/ai-policy";
 import { authClient } from "@/lib/auth-client";
+import { applyStoredLanguage } from "@/lib/language";
 import { canAccessRoute, defaultLandingFor, useActiveRole } from "@/lib/roles";
 
 // Authoritative client-side gate for the app shell. Requires a session and an
@@ -24,6 +25,16 @@ export function AppAuthGuard({ children }: { children: ReactNode }) {
   const hasUser = Boolean(session?.user);
   const activeOrgId = session?.session?.activeOrganizationId ?? null;
 
+  // Adopt the language saved on the backend once signed in, so the UI language
+  // roams across devices. Best-effort and one-shot; localStorage stays the
+  // offline source of truth.
+  const languageSynced = useRef(false);
+  useEffect(() => {
+    if (!hasUser || languageSynced.current) return;
+    languageSynced.current = true;
+    void applyStoredLanguage();
+  }, [hasUser]);
+
   useEffect(() => {
     if (isPending) return;
     if (!hasUser) {

frontend/components/chat/action-preview-card.tsx

@@ -269,7 +269,7 @@ export function ActionPreviewCard({
         </span>
         {editable ? (
           <Button
-            className="ml-auto"
+            className="ms-auto"
             onClick={() => setEditOpen(true)}
             size="sm"
             variant="ghost"

frontend/components/chat/ai-setup-notice.tsx

@@ -60,7 +60,7 @@ export function AiSetupNotice() {
       </div>
       <button
         aria-label={t("chat.setupNotice.dismiss")}
-        className="-mr-1 shrink-0 rounded-md p-1 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
+        className="-me-1 shrink-0 rounded-md p-1 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
         onClick={() => setDismissed(true)}
         type="button"
       >

frontend/components/chat/batch-action-preview-card.tsx

@@ -115,7 +115,7 @@ export function BatchActionPreviewCard({
         <span className="font-medium text-sm">
           {t("chat.actionCard.batch.title", { count: items.length })}
         </span>
-        <Badge className="ml-auto gap-1" variant="secondary">
+        <Badge className="ms-auto gap-1" variant="secondary">
           <Sparkles className="size-3" />
           AI
         </Badge>

frontend/components/chat/chat-history-panel.tsx

@@ -104,9 +104,9 @@ export function ChatHistoryPanel() {
               {t("chat.history.startNew")}
             </Button>
             <div className="relative">
-              <Search className="-translate-y-1/2 absolute top-1/2 left-2.5 size-4 text-muted-foreground" />
+              <Search className="-translate-y-1/2 absolute top-1/2 start-2.5 size-4 text-muted-foreground" />
               <Input
-                className="pl-8"
+                className="ps-8"
                 onChange={(e) => setQuery(e.target.value)}
                 placeholder={t("chat.history.search")}
                 value={query}
@@ -123,7 +123,7 @@ export function ChatHistoryPanel() {
                   return (
                     <button
                       className={cn(
-                        "group flex items-center gap-2 rounded-md px-2 py-2 text-left text-sm transition-colors hover:bg-accent",
+                        "group flex items-center gap-2 rounded-md px-2 py-2 text-start text-sm transition-colors hover:bg-accent",
                         active
                           ? "bg-accent text-foreground"
                           : "text-muted-foreground",

frontend/components/chat/chat-input.tsx

@@ -242,7 +242,7 @@ export function ChatInput({
               />
             </label>
             <button
-              className={cn(contextPill, "ml-0.5")}
+              className={cn(contextPill, "ms-0.5")}
               onClick={() => {
                 setAddKey((k) => k + 1);
                 setAddOpen(true);
@@ -258,7 +258,7 @@ export function ChatInput({
             <ModePicker
               mode={mode}
               onModeChange={onModeChange}
-              triggerClassName={cn(pillButton, "mr-1")}
+              triggerClassName={cn(pillButton, "me-1")}
             />
             <button
               aria-label={

frontend/components/chat/chat-panel.tsx

@@ -421,7 +421,7 @@ export function ChatPanel() {
         </div>
         <button
           aria-label={t("chat.error.dismiss")}
-          className="-mr-1 shrink-0 rounded-md p-1 text-destructive-foreground/70 transition-colors hover:bg-destructive/10 hover:text-destructive-foreground"
+          className="-me-1 shrink-0 rounded-md p-1 text-destructive-foreground/70 transition-colors hover:bg-destructive/10 hover:text-destructive-foreground"
           onClick={() => setErrorDismissed(true)}
           type="button"
         >