frontier-os-app-builder 1.0.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

@@ -1,6 +1,13 @@
 # Frontier OS App Builder
 
-A meta-prompting framework for building Frontier OS apps with Claude Code. Provides a guided workflow from idea to deployed app, with built-in knowledge of the Frontier SDK, app patterns, and deployment requirements.
+[![npm version](https://img.shields.io/npm/v/frontier-os-app-builder.svg)](https://www.npmjs.com/package/frontier-os-app-builder)
+
+A meta-prompting framework for building [Frontier OS](https://os.frontiertower.io) apps with [Claude Code](https://claude.ai/code). Provides a guided workflow from idea to deployed app, with built-in knowledge of the Frontier SDK, app patterns, and deployment requirements.
+
+## Prerequisites
+
+- [Claude Code](https://claude.ai/code) installed
+- Node.js 18+
 
 ## Install
 
@@ -10,21 +17,25 @@ 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
 npx frontier-os-app-builder --uninstall
 ```
 
-## Usage
+## Quick Start
 
-Create a new directory for your app, then run:
+1. Create a directory for your new app
+2. Open Claude Code in that directory
+3. Run:
 
 ```
-/fos:new-app "a room booking app for Frontier members"
+/fos:new-app "A tip jar app where members can tip baristas and staff with FND"
 ```
 
-The framework guides you through each step, telling you when to `/clear` and what command to run next:
+4. Follow the guided workflow — the framework tells you what to do next after each step:
 
 ```
 /fos:new-app "description"     → gather requirements, infer SDK modules, create roadmap
@@ -39,6 +50,16 @@ The framework guides you through each step, telling you when to `/clear` and wha
 /fos:ship                       → deploy to Vercel + register in app store
 ```
 
+5. Keep building — add features or start a new version:
+
+```
+/fos:add-feature "leaderboard"  → adds a new phase to the current milestone
+  /clear
+/fos:discuss N → /fos:plan N → /fos:execute N   → same loop
+
+/fos:new-milestone "v2 features" → archives v1, creates new phases for v2
+```
+
 ## Commands
 
 | Command | Purpose |
@@ -53,6 +74,12 @@ The framework guides you through each step, telling you when to `/clear` and wha
 | `/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:
@@ -63,20 +90,53 @@ The framework is a multi-layered meta-prompting system:
 - **References** — built-in Frontier SDK and app pattern knowledge
 - **Templates** — production-tested boilerplate from existing Frontier OS apps
 
-Each command reads state from `.frontier-app/` on disk, does its work, writes updated state, and tells you what to do next. The `/clear` between steps keeps your context window fresh.
+Each command reads state from `.frontier-app/` on disk, does its work, writes updated state, and tells you what to do next. Running `/clear` between steps keeps your context window fresh — the file-based state bridges the gap.
 
 ## Key features
 
-- Infers SDK modules from your app description ("room booking" → Events + Wallet)
-- Asks smart domain questions, not generic ones
-- Researches patterns from production Frontier OS apps
-- Uses proven templates instead of generating code from scratch
-- Verifies against Frontier-specific rules (CORS, iframe detection, permissions)
-- Milestone system for iterative development (v1 → v2 → v3)
+- **Module inference** — describe your app in plain English and the framework maps it to the right SDK modules ("room booking" → Events + Wallet + User)
+- **Smart questions** — asks domain questions ("Should bookings require FND payment?"), not technical ones ("Which SDK modules?")
+- **Production templates** — boilerplate extracted from real Frontier OS apps, not generated from scratch
+- **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
 
-## State
+## Frontier Studio
 
-All project state lives in `.frontier-app/` as human-readable Markdown and JSON:
+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:
+
+| Module | What it does |
+|---|---|
+| Wallet | Balances, FND transfers, token swaps, fiat on/off-ramp |
+| User | Profiles, referrals, KYC, access controls |
+| Events | Event management, room listings, bookings |
+| Communities | Community management, internship passes |
+| Partnerships | Sponsor passes |
+| Offices | Building access passes |
+| Storage | Persistent key-value storage |
+| Chain | Network config, contract addresses |
+| ThirdParty | App registration, webhooks, developer accounts |
+| Navigation | App-to-app deep linking |
+
+## Project State
+
+All state lives in `.frontier-app/` as human-readable Markdown and JSON — no database, no server:
 
 ```
 .frontier-app/
@@ -90,3 +150,19 @@ All project state lives in `.frontier-app/` as human-readable Markdown and JSON:
     ├── 02-feature/
     └── ...
 ```
+
+## Example Apps
+
+Ideas to get started:
+
+| App | Description | SDK Modules |
+|---|---|---|
+| Tip Jar | Members tip baristas with FND | Wallet, User |
+| Visitor Check-in | Kiosk for building access passes | Offices, User |
+| Room Booking | Book coworking rooms with payment | Events, Wallet, User |
+| Event Organizer | Create and manage community events | Events, Communities, User |
+| Sponsor Dashboard | Manage partnership passes | Partnerships, User |
+
+## License
+
+MIT

package/agents/fos-executor.md

@@ -27,7 +27,26 @@ Before executing, discover project context:
 
 <execution_flow>
 
-<step name="load_project_state" priority="first">
+<step name="verify_cwd" priority="first">
+**CRITICAL — Verify working directory before anything else.**
+
+When spawned in a worktree, your CWD may be the worktree root, not the app directory. Check:
+
+```bash
+ls .frontier-app/manifest.json 2>/dev/null && echo "CWD OK" || echo "CWD WRONG"
+```
+
+If `CWD WRONG`: look for the app directory inside the current directory. The worktree contains a copy of the repo — `cd` into it:
+```bash
+# Find the app directory (has .frontier-app/)
+APP_DIR=$(find . -maxdepth 2 -name "manifest.json" -path "*/.frontier-app/*" -exec dirname {} \; | head -1 | sed 's|/.frontier-app||')
+cd "$APP_DIR"
+```
+
+**All subsequent commands and file paths must be relative to the app root (where `.frontier-app/` exists).** Never use absolute worktree paths in git add commands — use paths relative to the repo root (e.g., `git add .frontier-app/phases/01-scaffold/01-01-SUMMARY.md`, NOT `git add frontier-os-app-name/.frontier-app/...`).
+</step>
+
+<step name="load_project_state">
 Load execution context:
 
 1. Read `.frontier-app/PROJECT.md` — app name, description, SDK modules
@@ -102,27 +121,43 @@ node $HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs scaffold <template>
 | Template | Destination |
 |----------|-------------|
 | `index.html` | `./index.html` |
-| `package.json` | `./package.json` |
+| `package-standalone.json` | `./package.json` |
 | `postcss.config.js` | `./postcss.config.js` |
 | `tsconfig.json` | `./tsconfig.json` |
-| `vercel.json` | `./vercel.json` |
+| `vercel-standalone.json` | `./vercel.json` |
 | `vite.config.ts` | `./vite.config.ts` |
-| `sdk-context.tsx` | `./src/lib/sdk-context.tsx` |
-| `layout.tsx` | `./src/views/Layout.tsx` |
-| `main-router.tsx` or `main-simple.tsx` | `./src/main.tsx` |
+| `frontier-services.tsx` | `./src/lib/frontier-services.tsx` |
+| `layout-standalone.tsx` | `./src/views/Layout.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/sdk-context.tsx` — NEVER modify after scaffold. Identical across all apps.
-- `src/views/Layout.tsx` — Must include `isInFrontierApp()` detection, `createStandaloneHTML()` fallback, `SdkProvider` wrapping children
+- `src/lib/frontier-services.tsx` — Exports `useServices()` with mock backend. Modified only during SDK Integration phase.
+- `src/views/Layout.tsx` — Dark-themed shell wrapping Outlet with FrontierServicesProvider. SdkProvider added during SDK Integration phase.
 - `src/styles/index.css` — Must include `@import "tailwindcss"`, complete `@theme` block with ALL CSS variables, `@layer base` with body styles
 - `index.html` — Must have `<body class="dark">`, Plus Jakarta Sans font links
-- `vercel.json` — Must have all 5 CORS origin blocks + SPA rewrite
+- `vercel.json` — SPA rewrite only at scaffold time. CORS origins added during SDK Integration phase.
 - `package.json` — Must have correct scripts (dev, build, preview, lint, test) and all required dependencies
 
+**Phase 1 scaffold BLOCKLIST — If any of these exist after scaffold, you have a bug. Fix it before committing:**
+- ❌ `src/lib/sdk-context.tsx` — DELETE if created. This file belongs to SDK Integration phase only.
+- ❌ `@frontiertower/frontier-sdk` in package.json — REMOVE from dependencies. SDK is added in SDK Integration phase.
+- ❌ `isInFrontierApp` or `createStandaloneHTML` in Layout.tsx — REWRITE Layout to use simple FrontierServicesProvider + Outlet pattern.
+- ❌ `SdkProvider` anywhere — REPLACE with FrontierServicesProvider.
+- ❌ `useSdk` anywhere — REPLACE with useServices.
+- ❌ Any import from `@frontiertower/frontier-sdk` — REMOVE. The SDK package does not exist in Phase 1.
+- ❌ CORS headers in vercel.json — REMOVE. Use SPA rewrite only.
+
+**Self-check after scaffold (run before committing):**
+```bash
+# All of these must return NO matches. If any match, fix before committing.
+grep -r "sdk-context\|useSdk\|SdkProvider\|@frontiertower/frontier-sdk\|isInFrontierApp\|createStandaloneHTML" src/ package.json vercel.json --include="*.tsx" --include="*.ts" --include="*.json" 2>/dev/null | grep -v node_modules || echo "CLEAN: No SDK artifacts in Phase 1"
+```
+
 </scaffold_execution>
 
 <feature_execution>
@@ -131,37 +166,41 @@ node $HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs scaffold <template>
 
 For feature tasks (Phase 2+), write actual TypeScript/React code.
 
-### SDK Code Patterns
+### Services Code Patterns
 
 **Always use these exact patterns:**
 
-**Import SDK:**
+**Import services:**
 ```typescript
-import { useSdk } from '../lib/sdk-context';
+import { useServices } from '../lib/frontier-services';
 ```
 
 **Access module:**
 ```typescript
-const sdk = useSdk();
-const wallet = sdk.getWallet();
+const services = useServices();
+const wallet = services.wallet;
 ```
 
 **Create hooks with loading/error states:**
 ```typescript
 import { useState, useEffect } from 'react';
-import { useSdk } from '../lib/sdk-context';
-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() {
-  const sdk = useSdk();
-  const [data, setData] = useState<ReturnType | null>(null);
+export function useBalance() {
+  const services = useServices();
+  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 sdk.getModule().method();
+        const result = await services.wallet.getBalance();
         setData(result);
       } catch (err) {
         setError(err instanceof Error ? err.message : 'Failed to load data');
@@ -170,7 +209,7 @@ export function useFeature() {
       }
     };
     fetchData();
-  }, [sdk]);
+  }, [services]);
 
   return { data, loading, error };
 }
@@ -207,25 +246,51 @@ 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
+
+Access modules via `services.<module>` from `useServices()`. Property names match SDK module names in lowercase (`services.wallet`, `services.events`, etc.).
+
 </feature_execution>
 
+<frontier_os_rules>
+**CRITICAL — These rules apply to ALL code written for Frontier OS apps.**
+
+**Read the current phase and sdkPhase from manifest.json to determine which tier applies.**
+
+**TIER 1 — ALL PHASES:**
+1. **Dark theme:** Tailwind dark theme. Backgrounds: `bg-background`, `bg-card`, `bg-muted-background`. Text: `text-foreground`, `text-card-foreground`, `text-muted-foreground`. No hardcoded colors (no bg-white, text-black, bg-gray-900).
+2. **Error handling:** All service calls wrapped in try/catch. Loading states for async operations. Error states with user-friendly messages.
+3. **TypeScript strict:** All code in TypeScript strict mode. No `any` types unless explicitly justified.
+4. **Testing:** Vitest for unit tests. Test files in `src/test/`.
+5. **Service access:** Feature phases use `useServices()` from `src/lib/frontier-services.tsx`. Never import SDK directly in feature hooks or views.
+6. **Mock layer:** Mock services return realistic data matching SDK return types. Hooks must work identically whether backed by mocks or real SDK.
+
+**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. **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 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>
+
+<sdk_integration_execution>
+
+### SDK Integration Phase Execution
+
+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>
+
 <deviation_rules>
 **While executing, you WILL discover work not in the plan.** Apply these rules automatically. Track all deviations for Summary.
 
@@ -239,7 +304,7 @@ No user permission needed for Rules 1-3.
 
 **Trigger:** Code doesn't work as intended (broken behavior, errors, incorrect output)
 
-**Examples:** Wrong SDK method call, type errors, null pointer exceptions, broken imports, incorrect hook dependencies, missing await on SDK promises
+**Examples:** Wrong service method call, type errors, null pointer exceptions, broken imports, incorrect hook dependencies, missing await on service promises
 
 ---
 
@@ -247,7 +312,7 @@ No user permission needed for Rules 1-3.
 
 **Trigger:** Code missing essential features for correctness, security, or basic operation
 
-**Examples:** Missing error handling on SDK calls, no loading states, missing null checks on SDK responses, no standalone fallback in Layout, missing CORS headers in vercel.json, no dark theme on new components
+**Examples:** Missing error handling on service calls, no loading states, missing null checks on service responses, no dark theme on new components
 
 ---
 
@@ -255,7 +320,7 @@ No user permission needed for Rules 1-3.
 
 **Trigger:** Something prevents completing current task
 
-**Examples:** Missing dependency, wrong import path, build error, TypeScript error, missing SDK type export, Vite config issue
+**Examples:** Missing dependency, wrong import path, build error, TypeScript error, missing type export, Vite config issue
 
 ---
 
@@ -263,7 +328,7 @@ No user permission needed for Rules 1-3.
 
 **Trigger:** Fix requires significant structural modification
 
-**Examples:** Changing SDK module approach, switching from single view to router, changing state management strategy, adding a new SDK module not in manifest
+**Examples:** Changing service module approach, switching from single view to router, changing state management strategy, adding a new service module not in manifest
 
 **Action:** STOP --> return checkpoint with: what found, proposed change, why needed, impact, alternatives. **User decision required.**
 
@@ -388,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
 
@@ -400,11 +465,11 @@ tasks_completed: N/N
 
 - [Decision and rationale]
 
-## SDK Methods Used
+## Service Methods Used
 
 | Method | Module | Permission | Files |
 |--------|--------|------------|-------|
-| getBalanceFormatted() | Wallet | wallet:getBalanceFormatted | src/hooks/useBalance.ts |
+| wallet.getBalance() | Wallet | wallet:getBalance | src/hooks/useBalance.ts |
 
 ## Deviations from Plan
 
@@ -452,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,8 +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 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
@@ -84,23 +86,25 @@ Then verify each level against the actual plan files.
 - 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
 
 **Question:** Do SDK methods used in plans have corresponding permissions in manifest.json?
 
+For feature phases: permission mismatches are severity **warning** (permissions are enforced at SDK Integration). For SDK Integration phase: permission mismatches are severity **blocker** (permissions must match real SDK calls).
+
 **Process:**
 1. Extract all SDK method calls from plan tasks
 2. Map each to its required permission using the pattern: `sdk.getModule().method()` --> `module:method`
@@ -124,10 +128,10 @@ issue:
 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
@@ -147,13 +151,14 @@ issue:
    - Files outside `src/` that should be inside
    - Wrong casing (lowercase views, PascalCase hooks)
    - Tests not in `src/test/`
-   - SDK-context.tsx modification (it must be identical across apps)
+   - Feature phase tasks importing from `sdk-context` instead of `frontier-services`
 
 **Red flags:**
 - `src/components/layout.tsx` (wrong case — should be `Layout.tsx`)
 - `src/useBalance.ts` (wrong location — should be `src/hooks/useBalance.ts`)
 - `tests/` at root (wrong — should be `src/test/`)
-- Any task modifying `src/lib/sdk-context.tsx`
+- Feature phase task importing from `src/lib/sdk-context` (should be `src/lib/frontier-services`)
+- Any task modifying `src/lib/sdk-context.tsx` (only created during SDK Integration phase)
 
 **Example issue:**
 ```yaml
@@ -176,30 +181,42 @@ issue:
    - `package.json` (correct scripts, dependencies)
    - `postcss.config.js` (imports @tailwindcss/postcss)
    - `tsconfig.json` (strict mode, correct types)
-   - `vercel.json` (all 5 CORS origins)
+   - `vercel.json`
    - `vite.config.ts`
    - `src/main.tsx`
-   - `src/lib/sdk-context.tsx`
-   - `src/views/Layout.tsx` (with isInFrontierApp, createStandaloneHTML, SdkProvider)
+   - `src/lib/frontier-services.tsx` (with `useServices()` export and `createMockServices()` export)
+   - `src/views/Layout.tsx` (with `FrontierServicesProvider`)
    - `src/styles/index.css` (Tailwind import, @theme block with all CSS variables, @layer base)
    - `.gitignore`
 2. Check that task actions mention key requirements:
-   - iframe detection via `isInFrontierApp()`
-   - Standalone fallback via `createStandaloneHTML()`
-   - SdkProvider wrapping children
+   - `useServices()` export in frontier-services.tsx
+   - `createMockServices()` export in frontier-services.tsx
+   - `FrontierServicesProvider` wrapping children in Layout
    - Dark theme CSS variables (all variables from T-01)
    - Plus Jakarta Sans font loading (T-03)
-   - 5 CORS origins in vercel.json (C-01)
    - Correct package.json scripts: dev, build, preview, lint, test (C-04)
 
+3. **BLOCKLIST CHECK** — Scan the plan for any of these. If found, it is a **blocker**:
+   - ❌ `sdk-context.tsx` referenced as a file to create — belongs to SDK Integration phase only
+   - ❌ `@frontiertower/frontier-sdk` in dependencies — SDK not installed until SDK Integration
+   - ❌ `isInFrontierApp` or `createStandaloneHTML` in any task action — SDK Integration concerns
+   - ❌ `SdkProvider` in any task action — use `FrontierServicesProvider` instead
+   - ❌ `useSdk` in any task action — use `useServices` instead
+   - ❌ `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`
+   - ❌ 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."
+
 **Example issue:**
 ```yaml
 issue:
   dimension: scaffold_completeness
   severity: blocker
-  description: "Scaffold plan missing vercel.json creation — required for CORS and SPA routing"
+  description: "Phase 1 plan creates sdk-context.tsx — this belongs to SDK Integration phase, not scaffold"
   plan: "01-01"
-  fix_hint: "Add task or expand existing task to create vercel.json with all 5 CORS origin blocks and SPA rewrite"
+  fix_hint: "Remove sdk-context.tsx from plan. Phase 1 uses frontier-services.tsx for the services layer."
 ```
 
 ## Dimension 5: Task Completeness
@@ -227,7 +244,7 @@ issue:
 issue:
   dimension: task_completeness
   severity: blocker
-  description: "Task 2 action says 'create payment handler' without specifying which SDK method (payWithFrontierDollar? transferOverallFrontierDollar?)"
+  description: "Task 2 action says 'create payment handler' without specifying which SDK method (transferFrontierDollar? transferOverallFrontierDollar?)"
   plan: "02-01"
   task: 2
   fix_hint: "Specify exact SDK method, parameters, return type, and error handling in action"
@@ -244,13 +261,14 @@ issue:
 
 **Frontier OS specific wiring patterns:**
 ```
-Hook --> Component: Does a view import and call the hook?
-Component --> SdkProvider: Is the view rendered inside SdkProvider?
-SDK call --> Error handling: Does the action mention try/catch?
-Router --> View: Does the router import the view component?
-Layout --> SdkProvider: Does Layout wrap children with SdkProvider?
+Hook --> Component: Does view import and call hook?
+Hook --> Services: Does hook import useServices() from frontier-services?
+Service call --> Error handling: Does action mention try/catch?
+Router --> View: Does router import view component?
 ```
 
+Note: SdkProvider wiring is checked only for SDK Integration phase plans.
+
 **Red flags:**
 - Hook created but no view imports it
 - View created but not added to router
@@ -329,6 +347,23 @@ issue:
 - Test files in wrong location
 - Test task with vague action ("write tests") instead of specific test cases
 
+## Dimension 10: SDK Integration Phase Completeness
+
+**Applies to:** SDK Integration phase plans only. Skip for feature phase plans.
+
+**Question:** Does the plan cover all mechanical steps for SDK Integration?
+
+**Checklist:**
+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 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)
+
+**Severity:** blocker for any missing step — SDK Integration is standardized and every step is required.
+
 </verification_dimensions>
 
 <output_format>
@@ -357,6 +392,7 @@ Return structured PASS/FAIL with issues list:
 | 7 | Context Compliance | PASS/FAIL/N/A | [count] |
 | 8 | Scope Sanity | PASS/FAIL | [count] |
 | 9 | Test Coverage | PASS/FAIL | [count] |
+| 10 | SDK Integration Completeness | PASS/FAIL/N/A | [count] |
 
 ### Issues
 
@@ -378,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>