frontier-os-app-builder 1.0.0 → 1.2.0

package/references/app-patterns.md

@@ -13,7 +13,7 @@ Reference for the standard structure, conventions, and tech stack used by all Fr
 | Language     | TypeScript                      | 5.9       |
 | CSS          | Tailwind CSS (via PostCSS)      | 4         |
 | Testing      | Vitest + jsdom + Testing Library| 4 / 27    |
-| SDK          | @frontiertower/frontier-sdk     | 0.15.0    |
+| SDK          | @frontiertower/frontier-sdk     | 0.24.0    |
 | Routing      | react-router-dom                | 7         |
 
 ---
@@ -34,7 +34,9 @@ app-<name>/
     main.tsx                 # React root + RouterProvider (identical pattern)
     router.tsx               # Route definitions (parameterized)
     lib/
-      sdk-context.tsx        # SdkProvider + useSdk hook (identical)
+      frontier-services.tsx  # useServices() provider + mock services (identical across all apps)
+      sdk-context.tsx        # SdkProvider + useSdk hook (added during SDK Integration phase)
+      sdk-services.tsx       # SDK adapter mapping services to real SDK (added during SDK Integration phase)
     views/
       Layout.tsx             # Shell layout component (parameterized)
       <FeatureViews>.tsx     # App-specific view components
@@ -65,10 +67,14 @@ app-<name>/
 
 These files are copied verbatim. They must not be modified per app.
 
-### `src/lib/sdk-context.tsx`
+### `src/lib/frontier-services.tsx`
+
+This file provides the `useServices()` hook and `FrontierServicesProvider`. It is identical across all apps and stays **SDK-free** (imports only React) — it is the mock seam. During standalone development `FrontierServicesProvider` returns mock services; after SDK Integration the **Layout** passes it real SDK-backed services in-frame (mocks standalone), so feature code never changes.
+
+### `src/lib/sdk-context.tsx` — identical across all apps, created during SDK Integration phase (not at scaffold time)
 
 ```tsx
-import { createContext, useContext, useEffect, useRef, useState, type ReactNode } from 'react';
+import { createContext, useContext, useEffect, useState, type ReactNode } from 'react';
 import { FrontierSDK } from '@frontiertower/frontier-sdk';
 
 const SdkContext = createContext<FrontierSDK | null>(null);
@@ -80,29 +86,33 @@ export const useSdk = (): FrontierSDK => {
 };
 
 export const SdkProvider = ({ children }: { children: ReactNode }) => {
-  const sdkRef = useRef<FrontierSDK | null>(null);
-  const [ready, setReady] = useState(false);
+  const [sdk, setSdk] = useState<FrontierSDK | null>(null);
 
   useEffect(() => {
-    const sdk = new FrontierSDK();
-    sdkRef.current = sdk;
-    setReady(true);
+    const instance = new FrontierSDK();
+    setSdk(instance);
 
     return () => {
-      sdk.destroy();
+      instance.destroy();
     };
   }, []);
 
-  if (!ready) return null;
+  if (!sdk) return null;
 
   return (
-    <SdkContext.Provider value={sdkRef.current}>
+    <SdkContext.Provider value={sdk}>
       {children}
     </SdkContext.Provider>
   );
 };
 ```
 
+> The SDK is held in `useState` (not a `useRef`): under React StrictMode the effect runs mount → cleanup → mount, so the first instance is created then destroyed. Storing it in state makes the second `setSdk(...)` re-render the Provider with the live instance, instead of leaving consumers pinned to the destroyed one. Do not "simplify" this back to a ref.
+
+### `src/lib/sdk-services.tsx` — identical across all apps, created during SDK Integration phase (not at scaffold time)
+
+This file provides the adapter that maps the `FrontierServices` interface to real SDK calls. It is created during the SDK Integration phase.
+
 ### `postcss.config.js`
 
 ```js
@@ -142,7 +152,7 @@ export default {
 
 ### `vercel.json`
 
-See [deployment.md](deployment.md) for the full file. All apps share the same CORS configuration with 5 origin blocks.
+See [deployment.md](deployment.md) for the full file. All apps share the same `vercel.json`: CORS for the production origin plus a `Content-Security-Policy: frame-ancestors` listing the 3 live Frontier OS origins (production `os.frontiertower.io`, sandbox `sandbox.os.frontiertower.io`, and `localhost:5173`) and the standard security headers.
 
 ---
 
@@ -165,7 +175,7 @@ Fixed fields (do not change):
 - `"private": true`
 - `"type": "module"`
 - `scripts` block (see Package Scripts below)
-- Core dependencies: `@frontiertower/frontier-sdk`, `react`, `react-dom`, `react-router-dom`
+- Core dependencies: `@frontiertower/frontier-sdk`, `react`, `react-dom`, `react-router-dom`, `viem` (`^2.44.0` — for on-chain apps that build calldata for `executeCall`/`executeBatchCall`; safe to drop for pure-UI apps)
 - Core devDependencies: `@tailwindcss/postcss`, `@types/react`, `@types/react-dom`, `@vitejs/plugin-react`, `postcss`, `tailwindcss`, `typescript`, `vite`
 - Test devDependencies (when tests exist): `@testing-library/jest-dom`, `@testing-library/react`, `@testing-library/user-event`, `@vitest/coverage-v8`, `jsdom`, `vitest`
 
@@ -308,9 +318,14 @@ export const Layout = () => {
     );
   }
 
+  // In-frame: SdkProvider provides the SDK; SdkServicesBridge wires it into
+  // FrontierServicesProvider so feature code's useServices() works unchanged.
+  // (SdkServicesBridge helper — see templates/app/layout.tsx.)
   return (
     <SdkProvider>
-      <Outlet />
+      <SdkServicesBridge>
+        <Outlet />
+      </SdkServicesBridge>
     </SdkProvider>
   );
 };
@@ -320,6 +335,69 @@ The `isInFrontierApp()` function checks `window.self !== window.top` -- it retur
 
 The `createStandaloneHTML()` fallback renders a branded page telling the user to open the app inside Frontier Wallet.
 
+#### Standalone-First Layout (Phase 1 through feature phases)
+
+```typescript
+import { Outlet } from 'react-router-dom';
+import { FrontierServicesProvider } from '../lib/frontier-services';
+
+export const Layout = () => (
+  <FrontierServicesProvider>
+    <Outlet />
+  </FrontierServicesProvider>
+);
+```
+
+No iframe detection, no loading state, no standalone fallback. The app just renders with mock services.
+
+#### SDK-Aware Layout (after SDK Integration phase)
+
+The Layout pattern with `isInFrontierApp()`, `createStandaloneHTML()`, `SdkProvider`, AND the `FrontierServicesProvider` bridge (so `useServices()` works against the real SDK) is applied during the SDK Integration phase. See the SDK-Aware Layout Pattern above and `templates/app/layout.tsx`.
+
+---
+
+### Services Pattern (Standalone-First)
+
+New apps use the `useServices()` abstraction instead of `useSdk()` directly. This enables standalone development with mock data before the SDK is wired in.
+
+**Standard hook using services:**
+
+```typescript
+import { useState, useEffect } from 'react';
+import { formatAmount } from '@frontiertower/frontier-sdk';
+import { useServices } from '../lib/frontier-services';
+
+export function useBalance() {
+  const services = useServices();
+  // Balance fields are bigint base units; format them for display with formatAmount().
+  const [balance, setBalance] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const fetch = async () => {
+      try {
+        const result = await services.wallet.getBalance();
+        setBalance(formatAmount(result.total));
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to load balance');
+      } finally {
+        setLoading(false);
+      }
+    };
+    fetch();
+  }, [services]);
+
+  return { balance, loading, error };
+}
+```
+
+**Key differences from SDK pattern:**
+- Import `useServices` from `../lib/frontier-services` (not `useSdk` from `../lib/sdk-context`)
+- Access modules as properties: `services.wallet` (not `sdk.getWallet()`)
+- Types imported from `../lib/frontier-services` (not `@frontiertower/frontier-sdk`)
+- Works standalone with mock data — no iframe required during development
+
 ---
 
 ## Router Variant (Standard)
@@ -345,13 +423,25 @@ export const router = createBrowserRouter([
 ]);
 ```
 
-### Single-Component Variant
+### Simple Apps (Single View)
+
+Even an app with only one view uses the router — there is no "render the Layout directly from `main.tsx`" path. Define a single index route so `Layout` stays in the render tree:
+
+```tsx
+import { createBrowserRouter } from 'react-router-dom';
+import { Layout } from './views/Layout';
+import { Home } from './views/Home';
+
+export const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <Layout />,
+    children: [{ index: true, element: <Home /> }],
+  },
+]);
+```
 
-For very simple apps that need only one view, the router can be omitted. In this case:
-- `main.tsx` renders the Layout directly instead of `<RouterProvider>`
-- `Layout.tsx` renders the single view component instead of `<Outlet />`
-- No `router.tsx` file needed
-- `react-router-dom` can be removed from dependencies
+Keeping `Layout` mounted preserves the services seam: standalone it provides `FrontierServicesProvider`, and after SDK Integration it wraps the app in `SdkProvider` + `SdkServicesBridge` so `useServices()` resolves against the real SDK. `react-router-dom` stays a dependency. Do not bypass the router by rendering a view straight from `main.tsx` — that skips the Layout bridge and ships mock services in-frame.
 
 ### `main.tsx` (Identical Pattern)
 
@@ -499,3 +589,20 @@ Configured in `vite.config.ts`:
 
 - `"types": ["vitest/globals", "@testing-library/jest-dom"]` -- global type augmentation
 - `"exclude": ["src/test", "**/*.test.ts", "**/*.test.tsx"]` -- test files excluded from production type-check (`tsc --noEmit` / `tsc && vite build`)
+
+---
+
+### SDK Integration Pattern
+
+The final phase of every app wires the real Frontier SDK in. This is a mechanical step:
+
+1. **Add SDK dependency**: `npm install @frontiertower/frontier-sdk`
+2. **Create `src/lib/sdk-context.tsx`**: Standard SdkProvider + useSdk hook (from template)
+3. **Create `src/lib/sdk-services.tsx`**: Adapter mapping FrontierServices interface to real SDK calls
+4. **Leave `src/lib/frontier-services.tsx` unchanged**: it stays the SDK-free mock seam. The iframe/standalone switch happens in Layout (step 5) — do NOT add SDK imports or detection here.
+5. **Swap in `src/views/Layout.tsx`** (from `templates/app/layout.tsx`): `isInFrontierApp()` detection + standalone fallback; in-frame it wraps the app in `SdkProvider` AND bridges the SDK into `FrontierServicesProvider` (via `createSdkServices(sdk)`) so `useServices()` resolves against the real SDK
+6. **Swap in the full `vercel.json`**: CORS for the production origin + `Content-Security-Policy: frame-ancestors` listing the 3 live origins (`os.frontiertower.io`, `sandbox.os.frontiertower.io`, `localhost:5173`) + security headers
+
+After SDK Integration, the app works in both modes:
+- **Standalone** (browser): Uses mock services, shows development data
+- **Iframe** (Frontier PWA): Uses real SDK, shows live data

package/references/deployment.md

@@ -18,13 +18,6 @@ All Frontier OS apps deploy to Vercel. The `vercel.json` file is identical acros
   "headers": [
     {
       "source": "/(.*)",
-      "has": [
-        {
-          "type": "header",
-          "key": "Origin",
-          "value": "https://os.frontiertower.io"
-        }
-      ],
       "headers": [
         {
           "key": "Access-Control-Allow-Origin",
@@ -37,102 +30,22 @@ All Frontier OS apps deploy to Vercel. The `vercel.json` file is identical acros
         {
           "key": "Access-Control-Allow-Headers",
           "value": "Content-Type"
-        }
-      ]
-    },
-    {
-      "source": "/(.*)",
-      "has": [
-        {
-          "type": "header",
-          "key": "Origin",
-          "value": "https://alpha.os.frontiertower.io"
-        }
-      ],
-      "headers": [
-        {
-          "key": "Access-Control-Allow-Origin",
-          "value": "https://alpha.os.frontiertower.io"
-        },
-        {
-          "key": "Access-Control-Allow-Methods",
-          "value": "GET, OPTIONS"
-        },
-        {
-          "key": "Access-Control-Allow-Headers",
-          "value": "Content-Type"
-        }
-      ]
-    },
-    {
-      "source": "/(.*)",
-      "has": [
-        {
-          "type": "header",
-          "key": "Origin",
-          "value": "https://beta.os.frontiertower.io"
-        }
-      ],
-      "headers": [
-        {
-          "key": "Access-Control-Allow-Origin",
-          "value": "https://beta.os.frontiertower.io"
-        },
-        {
-          "key": "Access-Control-Allow-Methods",
-          "value": "GET, OPTIONS"
-        },
-        {
-          "key": "Access-Control-Allow-Headers",
-          "value": "Content-Type"
-        }
-      ]
-    },
-    {
-      "source": "/(.*)",
-      "has": [
-        {
-          "type": "header",
-          "key": "Origin",
-          "value": "https://sandbox.os.frontiertower.io"
-        }
-      ],
-      "headers": [
-        {
-          "key": "Access-Control-Allow-Origin",
-          "value": "https://sandbox.os.frontiertower.io"
         },
         {
-          "key": "Access-Control-Allow-Methods",
-          "value": "GET, OPTIONS"
+          "key": "Content-Security-Policy",
+          "value": "frame-ancestors https://os.frontiertower.io https://sandbox.os.frontiertower.io http://localhost:5173;"
         },
         {
-          "key": "Access-Control-Allow-Headers",
-          "value": "Content-Type"
-        }
-      ]
-    },
-    {
-      "source": "/(.*)",
-      "has": [
-        {
-          "type": "header",
-          "key": "Origin",
-          "value": "http://localhost:5173"
-        }
-      ],
-      "headers": [
-        {
-          "key": "Access-Control-Allow-Origin",
-          "value": "http://localhost:5173"
+          "key": "X-Content-Type-Options",
+          "value": "nosniff"
         },
         {
-          "key": "Access-Control-Allow-Methods",
-          "value": "GET, OPTIONS"
+          "key": "Referrer-Policy",
+          "value": "strict-origin-when-cross-origin"
         },
         {
-          "key": "Access-Control-Allow-Headers",
-          "value": "Content-Type"
+          "key": "Permissions-Policy",
+          "value": "camera=(), microphone=(), geolocation=()"
         }
       ]
     }
@@ -140,25 +53,23 @@ All Frontier OS apps deploy to Vercel. The `vercel.json` file is identical acros
 }
 ```
 
-### Why 5 Separate Blocks
+### One Header Block + CSP `frame-ancestors`
 
-Vercel does not support multiple values in a single `Access-Control-Allow-Origin` header. Each allowed origin requires its own conditional header block using the `has` matcher. The `has` condition checks the incoming `Origin` request header and only attaches the CORS response headers when the origin matches.
+A single unconditional header block applies CORS for the production origin plus the security headers to every response. Embedding by all three Frontier origins is granted by the `Content-Security-Policy: frame-ancestors` directive (which lists all three) — `frame-ancestors` is what actually governs iframe embedding, not per-origin CORS reflection. This replaces the older pattern of one `has`-matched CORS block per origin.
 
 ---
 
 ## Allowed Origins
 
-The Frontier Wallet PWA runs at these 5 origins. Apps must allow CORS from all of them:
+The Frontier Wallet PWA runs at these 3 origins. Apps must allow all of them to embed the app via the CSP `frame-ancestors` directive:
 
 | Origin                                    | Environment  | Description                                                    |
 | ----------------------------------------- | ------------ | -------------------------------------------------------------- |
 | `http://localhost:5173`                   | Development  | Local Vite dev server for the PWA                              |
 | `https://sandbox.os.frontiertower.io`     | Sandbox      | Sandbox environment                                            |
-| `https://alpha.os.frontiertower.io`       | Alpha        | Early access, design preview -- "there will be dragons"        |
-| `https://beta.os.frontiertower.io`        | Beta         | Internally QA'd and tested, no external audit                  |
 | `https://os.frontiertower.io`             | Production   | Production ready                                               |
 
-These origins are also hardcoded in the SDK at `@frontiertower/frontier-sdk/ui-utils/detection.ts` as `ALLOWED_ORIGINS`.
+These origins are also hardcoded in the SDK at `@frontiertower/frontier-sdk/ui-utils/detection.ts` as `ALLOWED_ORIGINS` (exactly these 3). Note: `isInFrontierApp()` no longer consults this list -- it returns `window.self !== window.top` -- so `ALLOWED_ORIGINS` is informational for CORS/CSP only.
 
 The `isInFrontierApp()` function checks `window.self !== window.top` to detect if the app is running inside the Frontier Wallet iframe. The `getParentOrigin()` function resolves the parent frame's origin via `document.referrer` or `window.parent.location.origin`.
 
@@ -168,16 +79,16 @@ The `isInFrontierApp()` function checks `window.self !== window.top` to detect i
 
 ## Security Headers
 
-In addition to CORS, all deployment targets should include:
+The `vercel.json` above already ships these alongside CORS — every app should keep them:
 
-| Header                       | Recommended Value                                  | Purpose                                     |
+| Header                       | Value (shipped in vercel.json)                     | Purpose                                     |
 | ---------------------------- | -------------------------------------------------- | ------------------------------------------- |
-| `Content-Security-Policy`    | Include `frame-ancestors` for all 5 Frontier origins | Prevents embedding by unauthorized sites   |
+| `Content-Security-Policy`    | `frame-ancestors https://os.frontiertower.io https://sandbox.os.frontiertower.io http://localhost:5173;` (the 3 live origins) | Restricts who may embed the app             |
 | `X-Content-Type-Options`     | `nosniff`                                          | Prevents MIME-type sniffing                 |
 | `Referrer-Policy`            | `strict-origin-when-cross-origin`                  | Controls referrer information leakage       |
-| `Permissions-Policy`         | Disable unnecessary browser APIs                   | Reduces attack surface                      |
+| `Permissions-Policy`         | `camera=(), microphone=(), geolocation=()`         | Disables unused browser APIs                |
 
-The `frame-ancestors` CSP directive is critical because apps load inside the PWA's iframe. Without it, the browser may block the embed.
+The `frame-ancestors` CSP directive is critical because apps load inside the PWA's iframe. Without it, the browser may block the embed. The CSP is intentionally limited to `frame-ancestors` so it never blocks app resources (e.g. the Google Fonts stylesheet the template loads); apps that self-host all assets may tighten it further.
 
 ---
 
@@ -192,7 +103,7 @@ The recommended way is to use the OS Developer app in the Frontier AppStore. The
 1. **Get developer access** -- contact support@frontiertower.io to be added as a developer manager.
 2. **Get your developer profile** -- install the OS Developer app from the AppStore, or call `GET /third-party/developers/`.
 3. **Rotate your API key** immediately after receiving it: `POST /third-party/developers/{developer_id}/rotate-key/`. Store the new key securely.
-4. **Create the app** -- via OS Developer or `POST /third-party/apps/` with metadata: `name`, `url`, `description`, optional DNS entries.
+4. **Create the app** -- via OS Developer (`sdk.getThirdParty().createApp(...)`) or `POST /third-party/apps/` with body `{ url, cnameEntry, txtEntry?, permissions: string[], permissionDisclaimer }` (OS Developer additionally sends `developer: <id>`). App `name`, `description`, and `icon` are NOT sent -- they are auto-fetched from the app URL's HTML metadata (`<title>`, `<meta name="description">`, `<link rel="icon">`).
 
 ### App Status Lifecycle
 
@@ -217,24 +128,29 @@ When registering, declare the SDK permissions your app requires:
 ```typescript
 const APP_REGISTRY: AppMetadata[] = [
   {
-    id: 'my-app',
-    url: 'https://my-app.appstore.frontiertower.io',
-    origin: 'https://my-app.appstore.frontiertower.io',
-    version: '1.0.0',
+    id: 'ifnd-converter',
+    url: 'https://ifnd-converter.apps.frontiertower.io',
+    icon: '/svgs/ifnd_converter.svg',
     developer: {
       name: 'Developer Name',
-      verified: true,
-    },
-    permissions: {
-      wallet: true,
-      storage: true,
-      notifications: false,
+      url: 'https://frontiertower.io',
+      description: 'Made with love by the Frontier Tower Action Team',
     },
+    permissions: [
+      'wallet:getBalance',
+      'wallet:getAddress',
+      'wallet:executeBatchCall',
+      'wallet:executeCall',
+      'chain:getCurrentChainConfig',
+    ],
+    permissionDisclaimer:
+      'This app accesses your wallet address and balance and executes the conversion calls.',
+    // optional: excludedAppStages?, requiresCitizenship?, requiresAdmin?
   } as AppMetadata,
 ];
 ```
 
-Permissions must match the SDK methods actually called in source code. The fos-verifier agent enforces this (see [verification-rules.md](verification-rules.md)).
+Permissions are a flat array of `module:method` strings -- each entry must match an SDK method actually called in source code. `name`, `description`, and `icon` are optional in `AppMetadata` (auto-fetched from the app's HTML when omitted). There is no `origin`, `version`, or `developer.verified` field, and there is no `notifications` permission. The fos-verifier agent enforces the permission-to-source match (see [verification-rules.md](verification-rules.md)).
 
 ---
 
@@ -260,15 +176,15 @@ VITE_API_URL=https://api.example.com
 
 ## DNS Configuration
 
-Apps are hosted on the `appstore.frontiertower.io` subdomain.
+Apps are hosted on the `apps.frontiertower.io` subdomain.
 
 ### Domain Pattern
 
 ```
-<app-name>.appstore.frontiertower.io
+<app-name>.apps.frontiertower.io
 ```
 
-Example: `kickstarter.appstore.frontiertower.io`
+Example: `kickstarter.apps.frontiertower.io`
 
 ### DNS Entries
 
@@ -276,12 +192,12 @@ Two DNS records are needed:
 
 1. **CNAME** -- points the subdomain to the Vercel deployment:
    ```
-   <app-name>.appstore.frontiertower.io  CNAME  cname.vercel-dns.com
+   <app-name>.apps.frontiertower.io  CNAME  cname.vercel-dns.com
    ```
 
 2. **TXT** -- Vercel domain verification:
    ```
-   _vercel.<app-name>.appstore.frontiertower.io  TXT  vc-domain-verify=<token>
+   _vercel.<app-name>.apps.frontiertower.io  TXT  vc-domain-verify=<token>
    ```
 
 Configure the custom domain in the Vercel dashboard after DNS propagation. Vercel automatically provisions an SSL certificate.
@@ -381,7 +297,7 @@ Call `POST /third-party/webhooks/{webhook_id}/rotate-key/`. Deliveries immediate
 After deploying, verify CORS is working:
 
 ```bash
-curl -I https://<app-name>.appstore.frontiertower.io \
+curl -I https://<app-name>.apps.frontiertower.io \
   -H "Origin: https://os.frontiertower.io"
 
 # Should include:

package/references/module-index.md

@@ -0,0 +1,32 @@
+# SDK Module Index
+
+Maps app descriptions to Frontier SDK modules. The CLI (`fos-tools.cjs infer-modules`) does keyword matching programmatically — this file documents the algorithm and serves as an index to per-module reference files.
+
+## Inference Algorithm
+
+This mirrors `cmdInferModules` in `fos-tools.cjs` exactly:
+
+1. Lowercase the entire description (`description.toLowerCase()`) — no tokenization or word splitting.
+2. For each SDK module, substring-match its trigger keywords against the lowercased description with `String.includes()` (keywords are listed in each module's reference file under `references/sdk/`). Because matching is by substring, multi-word phrases like `send money`, `access control`, and `api key` work, and a keyword can match inside a larger word (e.g. `fund` matches within `refund`).
+3. Always include Storage and Chain (the base modules — every app needs these).
+4. Include User if User's own keywords match, or if any of Wallet, Events, Communities, Partnerships, or Offices matched. User is NOT added by ThirdParty, Navigation, Storage, or Chain alone.
+5. Present the inferred modules for user confirmation.
+
+## Module Quick Reference
+
+| Module | Reference File | Primary Use Case |
+|--------|---------------|-----------------|
+| Wallet | `references/sdk/wallet.md` | Payments, transfers, FND/iFND, fiat on/off-ramp |
+| Storage | `references/sdk/storage.md` | Key-value persistence, preferences |
+| Chain | `references/sdk/chain.md` | Network config, contract addresses |
+| User | `references/sdk/user.md` | Profiles, access controls, membership |
+| Communities | `references/sdk/communities.md` | Groups, internships, member management |
+| Partnerships | `references/sdk/partnerships.md` | Sponsors, passes, brand partnerships |
+| Events | `references/sdk/events.md` | Calendar, rooms, bookings, RSVPs |
+| Offices | `references/sdk/offices.md` | Physical access passes, building entry |
+| ThirdParty | `references/sdk/thirdparty.md` | Developer tools, webhooks, API keys |
+| Navigation | `references/sdk/navigation.md` | Deep links, cross-app navigation |
+
+## After Inference
+
+Once modules are confirmed, read only the relevant `references/sdk/<module>.md` files for detailed method signatures, types, and permissions. Always include `references/sdk/init.md` and `references/sdk/types.md` as shared context. For any app that reads, displays, transfers, or swaps FND amounts, also read `references/sdk/token-amount.md` — FND amounts are `bigint` base units bridged to/from display strings via `formatAmount()`/`parseAmount()`.

package/references/sdk/chain.md

@@ -0,0 +1,92 @@
+# Chain Module
+
+**Trigger keywords:** network, chain, blockchain, contract, smart contract, on-chain, token address, stablecoin
+
+Access via `sdk.getChain()`. Query and switch blockchain networks.
+
+---
+
+## Methods
+
+```typescript
+getCurrentNetwork(): Promise<string>
+```
+Returns the current network identifier (e.g. `'base'`, `'base-sepolia'`). Permission: `chain:getCurrentNetwork`
+
+```typescript
+getAvailableNetworks(): Promise<string[]>
+```
+Returns all network identifiers the app can switch to. Permission: `chain:getAvailableNetworks`
+
+```typescript
+switchNetwork(network: string): Promise<void>
+```
+Switch active blockchain network. Affects all subsequent wallet operations. Permission: `chain:switchNetwork`
+
+```typescript
+getCurrentChainConfig(): Promise<ChainConfig>
+```
+Returns full chain configuration for the current network. Permission: `chain:getCurrentChainConfig`
+
+```typescript
+getContractAddresses(): Promise<{
+  fnd: string;
+  iFnd: string | null;
+  paymentRouter: string;
+  subscriptionManager: string;
+}>
+```
+Returns addresses for FND, iFND (may be null), PaymentRouter, and SubscriptionManager contracts on the current chain. Permission: `chain:getContractAddresses`
+
+---
+
+## Types
+
+```typescript
+enum Underlying {
+  USD = "USD",
+}
+
+interface Token {
+  name: string;
+  symbol: string;
+  decimals: number;
+  address: string;
+}
+
+interface StableCoin extends Token {
+  underlying: Underlying;
+}
+
+interface ChainConfig {
+  id: number;
+  name: string;
+  network: string;
+  bridgeSwapRouterFactoryAddress: string;
+  uniswapV3FactoryAddress: string;
+  nativeCurrency: {
+    name: string;
+    symbol: string;
+    decimals: number;
+  };
+  blockExplorer: {
+    name: string;
+    url: string;
+  };
+  stableCoins: StableCoin[];
+  supportedTokens: Token[];
+  testnet: boolean;
+}
+```
+
+---
+
+## Permissions (5)
+
+| Permission | Description |
+|---|---|
+| `chain:getCurrentNetwork` | Get current network name |
+| `chain:getAvailableNetworks` | Get list of available networks |
+| `chain:switchNetwork` | Switch to a different network |
+| `chain:getCurrentChainConfig` | Get full chain configuration |
+| `chain:getContractAddresses` | Get FND, iFND, PaymentRouter, SubscriptionManager addresses |