frontier-os-app-builder 1.1.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BerlinhouseLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -17,6 +17,8 @@ npx frontier-os-app-builder
 
 That's it. This installs `/fos:*` commands into your Claude Code environment.
 
+> Running `npx frontier-os-app-builder` executes the installer automatically. If you install globally instead (`npm i -g frontier-os-app-builder`), run `frontier-os-app-builder` once afterward to populate `~/.claude`.
+
 To uninstall:
 
 ```bash
@@ -72,6 +74,12 @@ npx frontier-os-app-builder --uninstall
 | `/fos:next` | Auto-route to the next step in the workflow |
 | `/fos:status` | Show current project state |
 
+## Configuration
+
+| Environment variable | Used by | Effect |
+|---|---|---|
+| `FOS_GITHUB_ORG` | `/fos:ship` | Creates the deployed app's GitHub repo under this organization. When unset (the default), the repo is created under your authenticated `gh` user account. |
+
 ## How it works
 
 The framework is a multi-layered meta-prompting system:
@@ -92,6 +100,23 @@ Each command reads state from `.frontier-app/` on disk, does its work, writes up
 - **Frontier-specific verification** — checks CORS origins, iframe detection, standalone fallback, SDK permissions, dark theme
 - **Milestones** — iterative development with `/fos:new-milestone` for v2, v3, and beyond
 
+## Frontier Studio
+
+Frontier Studio is a live companion dashboard that runs alongside Claude Code. It watches your `.frontier-app/` state files and shows a visual dashboard with a live app preview in your browser.
+
+```bash
+cd your-app-directory
+npx frontier-studio
+```
+
+Opens `http://localhost:4983` with:
+
+- **Project dashboard** — phases, status, SDK modules, progress, next action
+- **Live preview** — your app rendered via Vite HMR in an iframe (desktop/tablet/mobile)
+- **Activity stream** — file changes, git commits, phase transitions in real time
+
+See [studio/README.md](./studio/README.md) for development details.
+
 ## SDK Coverage
 
 The framework has built-in knowledge of all 10 Frontier SDK modules:

package/agents/fos-executor.md

@@ -128,11 +128,12 @@ node $HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs scaffold <template>
 | `vite.config.ts` | `./vite.config.ts` |
 | `frontier-services.tsx` | `./src/lib/frontier-services.tsx` |
 | `layout-standalone.tsx` | `./src/views/Layout.tsx` |
-| `main-router.tsx` or `main-simple-standalone.tsx` | `./src/main.tsx` |
+| `main-router.tsx` | `./src/main.tsx` |
 | `router.tsx` | `./src/router.tsx` |
 | `index.css` | `./src/styles/index.css` |
 | `test-setup.ts` | `./src/test/setup.ts` |
 | `gitignore` | `./.gitignore` |
+| `public/` | `./public/` |
 
 **Critical scaffold requirements:**
 - `src/lib/frontier-services.tsx` — Exports `useServices()` with mock backend. Modified only during SDK Integration phase.
@@ -183,19 +184,23 @@ const wallet = services.wallet;
 **Create hooks with loading/error states:**
 ```typescript
 import { useState, useEffect } from 'react';
-import { useServices } from '../lib/frontier-services';
-import type { ReturnType } from '@frontiertower/frontier-sdk';
+import { useServices, type FrontierServices } from '../lib/frontier-services';
+
+// Derive feature data types from the FrontierServices seam — NEVER import the
+// SDK in feature code (it isn't installed in scaffold/feature phases and fails
+// verification rule M-03). `ReturnType` here is the TypeScript built-in.
+type Balance = Awaited<ReturnType<FrontierServices['wallet']['getBalance']>>;
 
-export function useFeature() {
+export function useBalance() {
   const services = useServices();
-  const [data, setData] = useState<ReturnType | null>(null);
+  const [data, setData] = useState<Balance | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
 
   useEffect(() => {
     const fetchData = async () => {
       try {
-        const result = await services.module.method();
+        const result = await services.wallet.getBalance();
         setData(result);
       } catch (err) {
         setError(err instanceof Error ? err.message : 'Failed to load data');
@@ -241,39 +246,18 @@ export default function FeatureView() {
 
 ### Tailwind Dark Theme Classes
 
-Always use these semantic classes (defined in index.css @theme block):
-- **Backgrounds:** `bg-background`, `bg-card`, `bg-muted-background`
-- **Text:** `text-foreground`, `text-card-foreground`, `text-muted-foreground`
-- **Borders:** `border-border`
-- **Interactive:** `bg-primary text-primary-foreground`, `bg-accent text-accent-foreground`
-- **Status:** `text-success`, `text-danger`, `text-alert`
-- **Inputs:** `bg-input`, `ring-ring`, `outline-outline`
-
-**NEVER use hardcoded colors** (no `bg-white`, `text-black`, `bg-gray-900`). Always use the semantic CSS variable classes.
+Use semantic Tailwind classes from the app's index.css @theme block (bg-background, text-foreground, etc.). See app-patterns.md "Dark Theme CSS Variables" section for the full token list. **NEVER use hardcoded colors** (no `bg-white`, `text-black`, `bg-gray-900`).
 
 ### Type Safety
 
 - Always use the SDK types from `@frontiertower/frontier-sdk`
-- Never invent types — use `WalletBalance`, `WalletBalanceFormatted`, `UserOperationReceipt`, `SmartAccount`, etc.
+- Never invent types — use `WalletBalance`, `UserOperationReceipt`, `SmartAccount`, etc.
 - If a type is not exported by the SDK, define a local interface that matches the SDK's return shape
 - Always use `strict: true` TypeScript
 
-### Module Access Reference
+### Module Access
 
-When accessing modules via `useServices()`, use these property names:
-
-| Service Property | Description |
-|-----------------|-------------|
-| `services.wallet` | Wallet operations (balance, transactions, send) |
-| `services.storage` | Storage operations (get, set, delete) |
-| `services.chain` | Chain/blockchain operations |
-| `services.user` | User profile and authentication |
-| `services.partnerships` | Partnerships module |
-| `services.thirdParty` | Third-party integrations |
-| `services.communities` | Communities module |
-| `services.events` | Events module |
-| `services.offices` | Offices module |
-| `services.navigation` | Navigation module |
+Access modules via `services.<module>` from `useServices()`. Property names match SDK module names in lowercase (`services.wallet`, `services.events`, etc.).
 
 </feature_execution>
 
@@ -293,9 +277,9 @@ When accessing modules via `useServices()`, use these property names:
 **TIER 2 — SDK INTEGRATION PHASE ONLY:**
 7. **SDK access:** `useSdk()` hook from `src/lib/sdk-context.tsx`, used only inside `sdk-services.tsx` and `Layout.tsx`.
 8. **Iframe detection:** `isInFrontierApp()` check in Layout.tsx. Standalone mode shows fallback banner.
-9. **SdkProvider wrapping:** App wrapped in SdkProvider when inside iframe. SDK initialized once via useRef, destroyed on unmount.
+9. **Provider wrapping:** In-frame, Layout wraps the app in `SdkProvider` AND bridges the SDK into `FrontierServicesProvider` (so `useServices()` resolves). SDK created once in an effect and exposed via `useState`, destroyed on unmount.
 10. **Permissions:** Every SDK method used must have permission declared in manifest.json.
-11. **CORS:** vercel.json must include all 3 Frontier OS origins (os.frontiertower.io, sandbox.os.frontiertower.io, localhost:5173).
+11. **CORS:** vercel.json sets CORS for the production origin plus a CSP `frame-ancestors` listing the 3 Frontier OS origins (os.frontiertower.io, sandbox.os.frontiertower.io, localhost:5173) and security headers. Copy templates/app/vercel.json verbatim.
 12. **SDK imports:** Use `@frontiertower/frontier-sdk` for SDK classes. Exact import paths, not barrel imports.
 </frontier_os_rules>
 
@@ -303,35 +287,7 @@ When accessing modules via `useServices()`, use these property names:
 
 ### SDK Integration Phase Execution
 
-For the SDK Integration phase (always the final phase), perform these mechanical operations:
-
-**Step 1: Add SDK dependency**
-```bash
-npm install @frontiertower/frontier-sdk
-```
-
-**Step 2: Create sdk-context.tsx**
-Render from `templates/app/sdk-context.tsx` to `src/lib/sdk-context.tsx`.
-This file is IDENTICAL across all apps — never customize it.
-
-**Step 3: Create sdk-services.tsx**
-Render from `templates/app/sdk-services.tsx` to `src/lib/sdk-services.tsx`.
-This adapter maps each `FrontierServices` method to the corresponding `sdk.getModule().method()` call.
-
-**Step 4: Upgrade frontier-services.tsx**
-Modify `src/lib/frontier-services.tsx` to add environment detection:
-- Import `isInFrontierApp` from `@frontiertower/frontier-sdk/ui-utils`
-- If in iframe: import and use `createSdkServices` from `./sdk-services`
-- If standalone: use existing `createMockServices()` (no change to mock code)
-
-**Step 5: Upgrade Layout.tsx**
-Follow standard Layout pattern from `templates/app/layout.tsx`:
-- Add `isInFrontierApp()` detection
-- Add `createStandaloneHTML()` fallback for standalone mode
-- Wrap children in `SdkProvider` when in iframe
-
-**Step 6: Add CORS origins to vercel.json**
-Replace vercel.json with full version from `templates/app/vercel.json` (has all 3 CORS origin blocks plus SPA rewrite).
+Follow the SDK Integration pattern from app-patterns.md "SDK Integration Pattern" section. The steps are: add SDK dependency; create sdk-context.tsx; create sdk-services.tsx (wire the modules your app uses); swap in templates/app/layout.tsx (it bridges the SDK into FrontierServicesProvider so useServices() works in-frame); swap in the full vercel.json. Leave frontier-services.tsx unchanged — it stays the SDK-free mock seam; do NOT add SDK imports or detection to it. Use templates from templates/app/ for each file.
 
 </sdk_integration_execution>
 
@@ -497,7 +453,7 @@ tasks_completed: N/N
 
 # Phase [X] Plan [Y]: [Name] Summary
 
-[One-liner must be substantive: "Balance display with useBalance hook calling getBalanceFormatted(), card-based UI with loading/error states" NOT "Balance feature implemented"]
+[One-liner must be substantive: "Balance display with useBalance hook calling getBalance() and formatting via formatAmount(), card-based UI with loading/error states" NOT "Balance feature implemented"]
 
 ## Tasks Completed
 
@@ -513,7 +469,7 @@ tasks_completed: N/N
 
 | Method | Module | Permission | Files |
 |--------|--------|------------|-------|
-| wallet.getBalanceFormatted() | Wallet | wallet:getBalanceFormatted | src/hooks/useBalance.ts |
+| wallet.getBalance() | Wallet | wallet:getBalance | src/hooks/useBalance.ts |
 
 ## Deviations from Plan
 
@@ -561,7 +517,8 @@ Do NOT skip. Do NOT proceed to state updates if self-check fails.
 </self_check>
 
 <sdk_reference>
-@frontier-os-app-builder/references/sdk-surface.md
+Focused SDK reference is provided via <files_to_read> in the spawn prompt.
+Contains only modules relevant to this app (from references/sdk/*.md).
 </sdk_reference>
 
 <app_patterns_reference>

package/agents/fos-plan-checker.md

@@ -48,7 +48,7 @@ Before verifying, load project context:
 <core_principle>
 **Plan completeness =/= Goal achievement**
 
-A task "create balance display" can be in the plan while the SDK method `getBalanceFormatted()` is called with wrong arguments. The task exists but the goal "show user's balance" won't be achieved.
+A task "create balance display" can be in the plan while the SDK method `getBalance()` is called with wrong arguments. The task exists but the goal "show user's balance" won't be achieved.
 
 Goal-backward verification works backwards from outcome:
 
@@ -74,10 +74,10 @@ Then verify each level against the actual plan files.
 3. Check method signatures match (parameter types, return types)
 4. Verify the correct module accessor is used (e.g., `getWallet()` not `wallet()`)
 
-Feature phases access methods via `services.module.method()` (not `sdk.getModule().method()`). The method NAMES are the same — validate against sdk-surface.md for correctness. The import path should be `../lib/frontier-services`, not `../lib/sdk-context`.
+Feature phases access methods via `services.module.method()` (not `sdk.getModule().method()`). The method NAMES are the same — validate against the per-module SDK reference files (references/sdk/*.md) for correctness. The import path should be `../lib/frontier-services`, not `../lib/sdk-context`.
 
 **Validation rules:**
-- Method must exist in @frontier-os-app-builder/references/sdk-surface.md
+- Method must exist in the focused SDK reference (provided via <files_to_read>)
 - Module accessor must use the correct getter: `sdk.getWallet()`, `sdk.getStorage()`, etc.
 - Parameter types must match SDK definitions (e.g., `bigint` for amounts, `string` for addresses)
 - Return types referenced in task must match SDK definitions
@@ -86,17 +86,17 @@ Feature phases access methods via `services.module.method()` (not `sdk.getModule
 - Method name doesn't exist in SDK (e.g., `getTokenBalance()` instead of `getBalance()`)
 - Wrong module (e.g., `sdk.getUser().getBalance()` instead of `sdk.getWallet().getBalance()`)
 - Wrong parameter types (e.g., `number` instead of `bigint` for token amounts)
-- Invented types not in SDK (e.g., `BalanceInfo` instead of `WalletBalanceFormatted`)
+- Invented types not in SDK (e.g., `BalanceInfo` instead of `WalletBalance`)
 
 **Example issue:**
 ```yaml
 issue:
   dimension: sdk_method_correctness
   severity: blocker
-  description: "Task 2 references sdk.getWallet().getTokenBalance() — method does not exist. Use getBalance() or getBalanceFormatted()"
+  description: "Task 2 references sdk.getWallet().getTokenBalance() — method does not exist. Use getBalance()"
   plan: "02-01"
   task: 2
-  fix_hint: "Replace getTokenBalance() with getBalanceFormatted() — returns WalletBalanceFormatted with .total, .fnd, .internalFnd string fields"
+  fix_hint: "Replace getTokenBalance() with getBalance() — returns WalletBalance with .total, .fnd, .internalFnd bigint fields; format each with formatAmount() from '@frontiertower/frontier-sdk'"
 ```
 
 ## Dimension 2: Permission Alignment
@@ -128,10 +128,10 @@ For feature phases: permission mismatches are severity **warning** (permissions
 issue:
   dimension: permission_alignment
   severity: blocker
-  description: "Task 1 calls sdk.getWallet().getBalanceFormatted() but manifest.json does not declare wallet:getBalanceFormatted permission"
+  description: "Task 1 calls sdk.getWallet().getBalance() but manifest.json does not declare wallet:getBalance permission"
   plan: "02-01"
   task: 1
-  fix_hint: "Add 'wallet:getBalanceFormatted' to permissions array in manifest.json, or add a task to update manifest"
+  fix_hint: "Add 'wallet:getBalance' to permissions array in manifest.json, or add a task to update manifest"
 ```
 
 ## Dimension 3: File Structure Compliance
@@ -205,7 +205,7 @@ issue:
    - ❌ `layout.tsx` template (without `-standalone`) — use `layout-standalone.tsx`
    - ❌ `package.json` template (without `-standalone`) — use `package-standalone.json`
    - ❌ `vercel.json` template (without `-standalone`) — use `vercel-standalone.json`
-   - ❌ `main-simple.tsx` template (without `-standalone`) — use `main-simple-standalone.tsx`
+   - ❌ single-component entries — use `main-router.tsx` instead (all apps use the router)
 
    If the researcher recommended SDK patterns from production apps, the planner should NOT have included them in Phase 1. Flag as blocker with fix hint: "Phase 1 is standalone-first. Remove SDK artifacts and use standalone templates."
 
@@ -357,8 +357,8 @@ issue:
 1. Plan includes task to add `@frontiertower/frontier-sdk` dependency (`npm install`)
 2. Plan includes task to create `src/lib/sdk-context.tsx` from template
 3. Plan includes task to create `src/lib/sdk-services.tsx` adapter
-4. Plan includes task to upgrade `src/lib/frontier-services.tsx` with environment detection
-5. Plan includes task to upgrade `src/views/Layout.tsx` with iframe detection + SdkProvider
+4. Plan keeps `src/lib/frontier-services.tsx` as the SDK-free mock seam (NO task to add SDK imports/detection there)
+5. Plan includes task to swap in `src/views/Layout.tsx` from the template (iframe detection + `SdkProvider` + `FrontierServicesProvider` bridge so `useServices()` resolves)
 6. Plan includes task to add CORS origins to `vercel.json`
 7. Plan includes verification task (build, typecheck, full validation)
 
@@ -414,7 +414,8 @@ Return structured PASS/FAIL with issues list:
 </output_format>
 
 <sdk_reference>
-@frontier-os-app-builder/references/sdk-surface.md
+Focused SDK reference is provided via <files_to_read> in the spawn prompt.
+Contains only modules relevant to this app (from references/sdk/*.md).
 </sdk_reference>
 
 <verification_rules_reference>

package/agents/fos-planner.md

@@ -121,14 +121,14 @@ Phase 1 ALWAYS produces a single plan that scaffolds the entire app. This plan u
 - `vite.config.ts` — Vite + Vitest config (parameterized: APP_NAME)
 - `frontier-services.tsx` — Service layer with mock implementations (parameterized: modules used)
 - `layout-standalone.tsx` — Shell layout for standalone mode (parameterized: APP_NAME)
-- `main-router.tsx` or `main-simple-standalone.tsx` — React root (choose based on routing needs)
+- `main-router.tsx` — React root (router entry; all apps use the router)
 - `router.tsx` — Route definitions (parameterized: routes)
 - `index.css` — Tailwind + dark theme variables (parameterized: app colors)
 - `test-setup.ts` — Vitest setup (identical across apps)
 - `gitignore` — Git ignore patterns
 
 **Scaffold plan specifics:**
-- ALL files listed in the template directory must be created
+- All standalone template files listed above must be created (excluding SDK-only and non-standalone variants from the BLOCKLIST below)
 - `frontier-services.tsx` goes to `src/lib/frontier-services.tsx`
 - `layout-standalone.tsx` goes to `src/views/Layout.tsx`
 - `index.css` goes to `src/styles/index.css`
@@ -142,7 +142,7 @@ Phase 1 ALWAYS produces a single plan that scaffolds the entire app. This plan u
 **Phase 1 BLOCKLIST — NEVER include these in a scaffold plan:**
 - ❌ `sdk-context.tsx` — this file is created during SDK Integration phase, NOT Phase 1
 - ❌ `layout.tsx` template — use `layout-standalone.tsx` instead (no iframe detection, no SdkProvider)
-- ❌ `main-simple.tsx` template — use `main-simple-standalone.tsx` instead
+- ❌ single-component entries — use `main-router.tsx` instead (all apps use the router; no single-component entry)
 - ❌ `package.json` template — use `package-standalone.json` instead (no SDK dependency)
 - ❌ `vercel.json` template — use `vercel-standalone.json` instead (no CORS headers)
 - ❌ `@frontiertower/frontier-sdk` in dependencies — SDK is added during SDK Integration phase
@@ -161,8 +161,8 @@ Feature phases create plans with tasks for:
 - **Tests** — Vitest tests for hooks and components
 
 **Task specificity requirements:**
-- Name exact service methods: `services.wallet.getBalanceFormatted()` not "get balance"
-- Name exact types: `WalletBalanceFormatted` not "balance type"
+- Name exact service methods: `services.wallet.getBalance()` not "get balance"
+- Name exact types: `WalletBalance` not "balance type"
 - Name exact file paths: `src/hooks/useBalance.ts` not "a balance hook"
 - Name exact Tailwind classes: `bg-card text-card-foreground rounded-lg p-4` not "styled card"
 - Name exact imports: `import { useServices } from '../lib/frontier-services'` not "import services"
@@ -177,17 +177,17 @@ The SDK Integration phase is ALWAYS the last phase. It is mechanical — no feat
 1. **Add SDK dependency** — `npm install @frontiertower/frontier-sdk@{{SDK_VERSION}}`. Add to package.json dependencies.
 2. **Create sdk-context.tsx** — Render from `templates/app/sdk-context.tsx` to `src/lib/sdk-context.tsx`. Standard SdkProvider + useSdk() hook, identical across all apps. NEVER modify after creation.
 3. **Create sdk-services.tsx** — Render from `templates/app/sdk-services.tsx` to `src/lib/sdk-services.tsx`. Adapter mapping FrontierServices interface to real SDK calls via useSdk().
-4. **Upgrade frontier-services.tsx** — Modify `src/lib/frontier-services.tsx` to detect environment: `window.self !== window.top`. If in iframe → import and use sdk-services adapter. If standalone → use existing mock services. Import `isInFrontierApp` from `@frontiertower/frontier-sdk/ui-utils`.
-5. **Upgrade Layout.tsx** — Follow standard Layout pattern from `templates/app/layout.tsx`: add `isInFrontierApp()` detection, `createStandaloneHTML()` fallback, `SdkProvider` wrapping of `<Outlet />`.
-6. **Add CORS origins to vercel.json** — Replace with full `templates/app/vercel.json` content (adds all 3 Frontier OS origin blocks).
+4. **Leave frontier-services.tsx unchanged** — it stays the SDK-free mock seam. The iframe/standalone switch lives in Layout (step 5); do NOT add SDK imports or detection to `src/lib/frontier-services.tsx`.
+5. **Swap in Layout.tsx** — Copy `templates/app/layout.tsx`: `isInFrontierApp()` detection, `createStandaloneHTML()` fallback, and in-frame wrap `<Outlet />` in `SdkProvider` + bridge the SDK into `FrontierServicesProvider` (`createSdkServices(sdk)`) so `useServices()` resolves.
+6. **Swap in the full vercel.json** — Replace with `templates/app/vercel.json` (CORS + CSP `frame-ancestors` for the 3 origins + security headers).
 7. **Verify** — Build passes (`npm run build`), typecheck passes (`npx tsc --noEmit`), all verification rules pass including Tier 2.
 
 **Success criteria (fixed, not user-determined):**
 1. `src/lib/sdk-context.tsx` exists and exports `useSdk` + `SdkProvider`
 2. `src/lib/sdk-services.tsx` exists and maps all used service methods to real SDK calls
-3. `src/lib/frontier-services.tsx` detects iframe and routes to SDK adapter
-4. `src/views/Layout.tsx` has `isInFrontierApp()` detection and `SdkProvider` wrapping
-5. `vercel.json` has all 3 CORS origin blocks
+3. `src/views/Layout.tsx` bridges the SDK into `FrontierServicesProvider` (via `createSdkServices`) so `useServices()` resolves in-frame
+4. `src/views/Layout.tsx` has `isInFrontierApp()` detection, `SdkProvider`, AND `FrontierServicesProvider`
+5. `vercel.json` has CORS + CSP `frame-ancestors` (3 origins) + security headers
 6. `npm run build` succeeds
 7. `npx tsc --noEmit` passes
 
@@ -209,22 +209,22 @@ Every task has six required fields:
 - Rule: At minimum, include the files this task's code will import from or integrate with.
 
 **<action>:** Specific implementation instructions with CONCRETE SDK values.
-- Good: "Create `useBalance` hook that calls `services.wallet.getBalanceFormatted()` returning `WalletBalanceFormatted`. Handle loading/error states with useState. The hook returns `{ balance: WalletBalanceFormatted | null, loading: boolean, error: string | null }`. Import `useServices` from `../lib/frontier-services`. Wrap the service call in try/catch. Call in a useEffect with `[services]` dependency."
+- Good: "Create `useBalance` hook that calls `services.wallet.getBalance()` returning `WalletBalance` (bigint fields `total`/`fnd`/`internalFnd`), formatting for display via `formatAmount` imported from `@frontiertower/frontier-sdk`. Handle loading/error states with useState. The hook returns `{ balance: WalletBalance | null, loading: boolean, error: string | null }`. Import `useServices` from `../lib/frontier-services`. Wrap the service call in try/catch. Call in a useEffect with `[services]` dependency."
 - Bad: "Create a hook that fetches the balance"
 
 **<verify>:** How to prove the task is complete.
-- Good: `grep -q "getBalanceFormatted" src/hooks/useBalance.ts && npx tsc --noEmit`
+- Good: `grep -q "getBalance" src/hooks/useBalance.ts && npx tsc --noEmit`
 - Bad: "It works"
 
 **<acceptance_criteria>:** Grep-verifiable conditions the executor checks programmatically. Every task MUST include this field.
 - Good:
-  - `grep -q "getBalanceFormatted" src/hooks/useBalance.ts`
+  - `grep -q "getBalance" src/hooks/useBalance.ts`
   - `grep -q "loading" src/hooks/useBalance.ts`
   - `npx tsc --noEmit` exits 0
 - Bad: "It compiles", or omitting acceptance_criteria entirely
 
 **<done>:** Acceptance criteria — measurable state of completion.
-- Good: "`useBalance.ts` exports a hook that returns `{ balance, loading, error }`. TypeScript compiles without errors. The hook calls `getBalanceFormatted()` with proper error handling."
+- Good: "`useBalance.ts` exports a hook that returns `{ balance, loading, error }`. TypeScript compiles without errors. The hook calls `getBalance()` and formats with `formatAmount()`, with proper error handling."
 - Bad: "Balance hook is complete"
 
 ## Task Types
@@ -299,7 +299,7 @@ SDK Modules: [Which SDK modules are used, if any]
 @.frontier-app/STATE.md
 
 # SDK reference for modules used:
-@frontier-os-app-builder/references/sdk-surface.md
+# Provided via <files_to_read> in spawn prompt (focused per-module refs from references/sdk/)
 
 # Prior plan summaries if needed:
 @.frontier-app/phases/XX-name/NN-NN-SUMMARY.md
@@ -376,57 +376,9 @@ Plans should complete within ~50% context. Each plan: 2-3 tasks maximum.
 
 <frontier_os_specifics>
 
-## Service Method Reference for Plans
+## Service Method Reference
 
-When referencing service methods in task actions, use the EXACT patterns:
-
-**Initialization (always via useServices):**
-```typescript
-import { useServices } from '../lib/frontier-services';
-const services = useServices();
-```
-
-**Module access:**
-```typescript
-const wallet = services.wallet;
-const storage = services.storage;
-const chain = services.chain;
-const user = services.user;
-const partnerships = services.partnerships;
-const thirdParty = services.thirdParty;
-const communities = services.communities;
-const events = services.events;
-const offices = services.offices;
-const navigation = services.navigation;
-```
-
-**Standard hook pattern:**
-```typescript
-export function useFeature() {
-  const services = useServices();
-  const [data, setData] = useState<FeatureType | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-
-  useEffect(() => {
-    const fetch = async () => {
-      try {
-        const result = await services.module.method();
-        setData(result);
-      } catch (err) {
-        setError(err instanceof Error ? err.message : 'Unknown error');
-      } finally {
-        setLoading(false);
-      }
-    };
-    fetch();
-  }, [services]);
-
-  return { data, loading, error };
-}
-```
-
-**Permission mapping:** `services.module.method()` requires permission `module:method` in manifest.json.
+Access modules via `services.<module>` from `useServices()` (imported from `../lib/frontier-services`). Property names match SDK module names in lowercase. Method signatures and types are in the focused SDK reference provided via `<files_to_read>`. Permission mapping: `services.module.method()` requires permission `module:method` in manifest.json.
 
 ## Required Patterns for All Plans
 
@@ -463,7 +415,8 @@ When spawned in revision mode with checker issues:
 </revision_mode>
 
 <sdk_reference>
-@frontier-os-app-builder/references/sdk-surface.md
+Focused SDK reference is provided via <files_to_read> in the spawn prompt.
+Contains only modules relevant to this app (from references/sdk/*.md).
 </sdk_reference>
 
 <app_patterns_reference>

package/agents/fos-researcher.md

@@ -48,16 +48,17 @@ If CONTEXT.md exists, it constrains your research scope. Don't explore alternati
 All production apps live at `~/frontieros/frontier-os-app-*`. Use this mapping to identify which apps to study based on the current phase's feature needs.
 
 ### Wallet / Payments / Transactions
-**Apps:** `frontier-os-app-pos`, `frontier-os-app-pos-payment`, `frontier-os-app-subscriptions`
+**Preferred apps (v0.23+ bigint amounts — study these first):** `frontier-os-app-fiat-rails` (bigint `transferFrontierDollar`/transfers + on/off-ramp), `frontier-os-app-ifnd-converter` (gold v0.24 migration — `getBalance()` + `formatAmount()`/`parseAmount()` patterns)
+**Legacy apps (PRE-bigint — useful for UI/flow patterns only, NOT for amount handling):** `frontier-os-app-pos`, `frontier-os-app-pos-payment`, `frontier-os-app-subscriptions`. WARNING: these predate v0.23, use `amount: string`, and `pos`/`pos-payment` still call the REMOVED `getBalanceFormatted()`. Do NOT copy their amount/balance code — use the preferred apps for that.
 **What to study:**
-- `transferFrontierDollar()` and `transferOverallFrontierDollar()` call patterns
+- `transferFrontierDollar()` and `transferOverallFrontierDollar()` call patterns — amounts are `bigint` base units (v0.23+); build with `parseAmount('10.5')` from `@frontiertower/frontier-sdk`
 - Payment confirmation flows and receipt UI
-- Balance display with `getBalanceFormatted()`
+- Balance display: `getBalance()` returns `WalletBalance { total, fnd, internalFnd }` (all `bigint`); format each field with `formatAmount()` from `@frontiertower/frontier-sdk`
 - Transaction error handling and retry patterns
 - Loading states during biometric auth prompts
 
 ### Events / Bookings / Reservations
-**Apps:** `frontier-os-app-superhero-hotel`
+**Apps:** `frontier-os-app-superhero-hotel` (PRE-bigint, v0.15.x — good for event/booking UI + flow patterns; if the phase touches FND amounts or the new event security-deposit methods, take amount/balance patterns from the v0.23+ Wallet apps above instead)
 **What to study:**
 - Event listing and detail views
 - Booking flow (date selection, confirmation, payment)
@@ -79,7 +80,7 @@ All production apps live at `~/frontieros/frontier-os-app-*`. Use this mapping t
 - Reward tracking with wallet integration
 
 ### Maintenance / AI / Tools
-**Apps:** `frontier-os-app-maintenance`
+**Apps:** `frontier-os-app-maintenance` (PRE-bigint, v0.15.x — good for ThirdParty/AI integration + tool-layout patterns; do not copy any FND amount/balance handling from it)
 **What to study:**
 - ThirdParty module usage
 - AI/ML integration patterns
@@ -201,20 +202,21 @@ For every SDK module relevant to the phase, document:
 ```typescript
 // Import
 import { useSdk } from '../lib/sdk-context';
+import { formatAmount } from '@frontiertower/frontier-sdk'; // bigint -> display string (package root, NOT /ui-utils)
 
 // In component
 const sdk = useSdk();
 const wallet = sdk.getWallet();
 
-// Call pattern
-const [balance, setBalance] = useState<WalletBalanceFormatted | null>(null);
+// Call pattern — getBalance() returns WalletBalance { total, fnd, internalFnd } (all bigint base units)
+const [balance, setBalance] = useState<WalletBalance | null>(null);
 const [loading, setLoading] = useState(true);
 const [error, setError] = useState<string | null>(null);
 
 useEffect(() => {
   const fetchBalance = async () => {
     try {
-      const result = await wallet.getBalanceFormatted();
+      const result = await wallet.getBalance(); // display via formatAmount(result.fnd) — getBalanceFormatted() was REMOVED in v0.23
       setBalance(result);
     } catch (err) {
       setError(err instanceof Error ? err.message : 'Failed to load balance');
@@ -225,7 +227,8 @@ useEffect(() => {
   fetchBalance();
 }, [wallet]);
 
-// Permission: wallet:getBalanceFormatted
+// Display: formatAmount(balance.total) — symbol-free decimal string; prepend '$' yourself if wanted
+// Permission: wallet:getBalance (import { formatAmount } from '@frontiertower/frontier-sdk')
 ```
 
 ### 2. Component Structure
@@ -357,7 +360,8 @@ Do NOT continue reading indefinitely. Research without output is a stuck signal.
 </analysis_paralysis_guard>
 
 <sdk_reference>
-@frontier-os-app-builder/references/sdk-surface.md
+Focused SDK reference is provided via <files_to_read> in the spawn prompt.
+Contains only modules relevant to this app (from references/sdk/*.md).
 </sdk_reference>
 
 <app_patterns_reference>

package/agents/fos-verifier.md

@@ -146,13 +146,14 @@ grep -q "createStandaloneHTML" src/views/Layout.tsx && echo "PASS: I-02" || echo
 
 Verify the pattern: when `isInFrontierApp()` returns false, `createStandaloneHTML()` is called and rendered via `dangerouslySetInnerHTML`.
 
-### I-03: SdkProvider wrapping children
+### I-03: SdkProvider + FrontierServicesProvider wrapping children
 
 ```bash
-grep -q "SdkProvider" src/views/Layout.tsx && echo "PASS: I-03" || echo "FAIL: I-03"
+grep -q "SdkProvider" src/views/Layout.tsx && echo "PASS: I-03 SdkProvider" || echo "FAIL: I-03 SdkProvider"
+grep -q "FrontierServicesProvider" src/views/Layout.tsx && echo "PASS: I-03 FrontierServicesProvider" || echo "FAIL: I-03 FrontierServicesProvider (useServices() will crash at runtime)"
 ```
 
-Verify `<SdkProvider>` wraps `<Outlet />` or the app's child component in the "in Frontier" code path.
+Verify the "in Frontier" path wraps children in `<SdkProvider>` AND bridges the SDK into `<FrontierServicesProvider>` (feature code uses `useServices()`, not `useSdk()`).
 
 ### I-04: useSdk() hook available and used
 
@@ -174,11 +175,15 @@ If any file outside `sdk-context.tsx` instantiates `new FrontierSDK()` directly,
 > **Tier 2 — SDK Integration phase only.** CORS origins are added during SDK Integration.
 
 ```bash
-# Check all 3 origins present
+# Check all 3 origins present (in the CSP frame-ancestors directive)
 for origin in "os.frontiertower.io" "sandbox.os.frontiertower.io" "localhost:5173"; do
   grep -q "$origin" vercel.json && echo "PASS: $origin" || echo "FAIL: $origin missing from vercel.json"
 done
 
+# Check CSP frame-ancestors + security headers
+grep -q "frame-ancestors" vercel.json && echo "PASS: CSP frame-ancestors" || echo "FAIL: CSP frame-ancestors missing"
+grep -q "X-Content-Type-Options" vercel.json && echo "PASS: security headers" || echo "FAIL: security headers missing"
+
 # Check SPA rewrite
 grep -q '"/(.*)"' vercel.json && echo "PASS: SPA rewrite" || echo "FAIL: SPA rewrite missing"
 ```
@@ -546,7 +551,8 @@ gaps: [list of failed check IDs, empty if passed]
 </verification_rules_reference>
 
 <sdk_reference>
-@frontier-os-app-builder/references/sdk-surface.md
+Focused SDK reference is provided via <files_to_read> in the spawn prompt.
+Contains only modules relevant to this app (from references/sdk/*.md).
 </sdk_reference>
 
 <app_patterns_reference>