@hailer/mcp 1.2.1 → 1.3.9

package/.claude/skills/create-and-publish-app/SKILL.md

@@ -1,204 +1,194 @@
 ---
 name: create-and-publish-app
-description: How to scaffold, create and publish Hailer apps using @hailer/create-app npm package (CLI-based alternative to scaffold_hailer_app MCP tool)
-version: 1.1.0
+description: Scaffold, develop, and publish Hailer apps with @hailer/create-app — dev iteration, production publish, marketplace, validation, and cache gotchas
+version: 2.0.0
 triggers:
   - create-app
   - npx create-app
-  - hailer create-app
   - scaffold app cli
+  - publish app
+  - deploy app
+  - production app
 ---
 
 # Create and Publish Hailer App
 
-Scaffold, create and publish Hailer apps using `@hailer/create-app` npm package.
+The full app lifecycle with `@hailer/create-app`: scaffold → build → dev publish → production publish → marketplace.
 
 **npm package docs:** https://www.npmjs.com/package/@hailer/create-app
-**Registry README (machine-readable):** https://registry.npmjs.org/@hailer/create-app (check `readme` field)
 
 <when-to-use>
-## When to Use This vs scaffold_hailer_app MCP Tool
+## Scripts Are the ONLY Path
 
-| Approach | When |
-|----------|------|
-| `npx @hailer/create-app` (this skill) | CLI-based scaffolding, `npm run publish-production` for publishing |
-| `scaffold_hailer_app` MCP tool | MCP-based scaffolding, `publish_hailer_app` MCP tool for publishing |
-
-Both create valid Hailer apps. This skill covers the npm CLI path.
-
-**IMPORTANT: The `scaffold_hailer_app` MCP tool uses `/bin/sh` internally. In Hailer Studio (cluster environment), `/bin/sh` is not at the standard path and the MCP tool will fail with `spawnSync /bin/sh ENOENT`. Always use `npx @hailer/create-app` in Hailer Studio.**
+Apps are scaffolded and published exclusively through the scripts: `npx @hailer/create-app` and `npm run publish-*`. There are NO MCP tools for scaffolding or publishing — the MCP surface only covers the app registry (`manage_app`, `list_apps`, `remove_app`) and marketplace listings (`browse_marketplace`, `install_marketplace`, `publish_marketplace`).
 </when-to-use>
 
-<step-1>
-## Step 1 — Scaffold the Project
+<scaffold>
+## Step 1 — Scaffold
 
 ```bash
 npx @hailer/create-app <project-name> --template react-ts
+npx hailer-mcp prep-app <project-name>
 ```
 
-- Run from a parent directory (e.g. project root or an `apps/` subfolder — create it first if needed: `mkdir -p apps`)
-- `react-ts` is the recommended template
-- **CRITICAL:** The CLI is interactive-only when called via `npm create` — always use `npx @hailer/create-app` with the name and template as arguments to avoid prompts
-- **Hailer Studio only:** Do NOT use `scaffold_hailer_app` MCP tool — it fails with `spawnSync /bin/sh ENOENT` in the cluster environment
-</step-1>
-
-<step-2>
-## Step 2 — Install Dependencies
+**Run `npx hailer-mcp prep-app <project-name>` immediately after scaffolding — it neutralizes the scaffold's two built-in papercuts so you never hit them:** clears the placeholder `appId` (`65143728…`) and fake "Magic Apps Ltd." author from `public/manifest.json` (so first-publish detection is clean and no demo identity leaks), and fixes the `StoreSet` `tsc` error in `src/hailer/use-app.ts`. Idempotent and safe to re-run. (Run it from the SDK project root, where `npx hailer-mcp` resolves; pass the app dir or `apps/<name>`.)
 
-```bash
-cd apps/<project-name>
-npm install
-```
-</step-2>
+**This exact form is non-interactive — it runs with zero prompts. Do NOT deviate:**
+- **`<project-name>` is a POSITIONAL argument, not a flag.** `--name <x>` is silently ignored and the CLI drops to an interactive "Project name:" prompt that hangs an agent. Put the name first, bare.
+- **`--template` must be a real template name:** `react-ts` (recommended), `react`, `react-swc-ts`, `vanilla-ts`, `vanilla`, `preact-ts`, `preact`, `svelte-ts`, `svelte`. NOT `minimal` (invalid → drops to a "Select a framework" prompt that hangs).
+- **Use a fresh, lowercase, kebab-case name** in an empty target dir — that skips the overwrite prompt AND the package-name prompt. e.g. `injured-players-cost`.
+- Never run `npx @hailer/create-app` bare and never pipe input to it (`echo …|`, `printf`, `expect`) — the one-line form above already needs no input.
+- Run from a parent directory (`mkdir -p apps` first if needed), NEVER copy an existing app, then `cd <project-name> && npm install`.
+</scaffold>
 
-<step-3>
-## Step 3 — Build the App UI
+<build>
+## Step 2 — Build the App UI
 
-Replace `src/App.tsx` and add components. Key patterns:
+Replace `src/App.tsx` and add components (load `hailer-app-builder` + `hailer-design-system` skills for patterns):
 
-- Use `useApp` from `src/hailer/use-app.ts` (the new template uses zustand-based state)
+- Use `useApp` from `src/hailer/use-app.ts` (zustand-based state)
 - Call `api.init()` in a `useEffect` in `App.tsx`
-- Use `hailer.activity.list(workflowId, phaseId, options)` to fetch data — call once per phase in parallel with `Promise.all`
-- Use `hailer.ui.activity.open(id)` to open an activity sidebar
-- Use `hailer.ui.activity.create(workflowId)` to open the create form
-</step-3>
+- `hailer.activity.list(workflowId, phaseId, options)` — one call per phase, in parallel with `Promise.all`
+- `hailer.ui.activity.open(id)` / `hailer.ui.activity.create(workflowId)` for the sidebar/create form
+- Apps must render outside Hailer too — empty state, never an error
 
-<step-4>
-## Step 4 — Publish Dev Version
+**Two scaffold facts that save a rabbit hole every build:**
+1. **The scaffold ships with ONE known `tsc` error** — `src/hailer/use-app.ts` types `StoreSet` `replace?: boolean`; it must be `replace?: false`. Fix that one line as your very first edit and tsc is clean. (Upstream create-app bug; not your code.)
+2. **Verify with `npm run build-production`, NOT `tsc` / `npm run build`.** `build-production` is vite-only — it's the exact command the publish runs. `npm run build` and `npx tsc --noEmit` run `tsc`, which trips on the scaffold error above and sends you chasing a problem the publish never sees. Verify the way you ship.
+</build>
 
-**Do NOT publish as production yet WHEN IN HAILER STUDIO.** Publish the app under the name `<App Name> - Dev` so it can be tested inside Hailer. This is the dev iteration loop — build, publish as Dev, test, fix, repeat.
+<dev-publish>
+## Step 3 — Dev Iteration
 
-### Hailer Studio (cluster)
+**Local machine:** `npm run dev` → test at `http://localhost:3000`. The scaffold's dev app entry stays at localhost forever — it's your development slot.
+
+**Hailer Studio:** `localhost:3000` is unreachable from outside the sandbox — publishing is the only way to test inside Hailer. Publish a SEPARATE dev app and iterate on it:
 
 ```bash
 npm run publish-production -- --host http://hailer-api:1337 --create --app-name "<App Name> - Dev" --workspace <workspaceId> --force
 ```
 
-After the first publish, `public/manifest.json` is updated with the dev app's `appId`. Subsequent dev publishes just need `--force` — no `--create` or `--app-name` needed.
-
-Then share it with the workspace:
-
-```javascript
-add_app_member({ appId: "<devAppId>", member: "network_<workspaceId>" })
-```
+After the first publish `public/manifest.json` holds the dev `appId`; later iterations just need `--host ... --force`. Share it: MCP `manage_app({ action: 'add_member', appId, member: "network_<workspaceId>" })`.
 
-**Why not localhost:3000?** In Hailer Studio the sandbox is not reachable from outside — `localhost:3000` is inaccessible to the user. Publishing is the only way to test the app inside Hailer.
+| App | Name | Purpose |
+|-----|------|---------|
+| Dev | `My App - Dev` | publish repeatedly while iterating |
+| Production | `My App` | publish only when the user explicitly asks |
+</dev-publish>
 
-**Only proceed to Step 5 when the user explicitly says they are happy and want to publish to production.**
-</step-4>
+<credentials>
+## Credentials — Read This Before Publishing Fails
 
-<step-5>
-## Step 5 — Publish to Production (Only When User Explicitly Asks)
+The publish CLI (`@hailer/app-sdk`'s `publish.cjs`, wrapped as `npm run publish-*`) authenticates ONLY from, in order: `--user-api-key` flag → `USER_API_KEY` / `HAILER_USER_API_KEY` env vars → `~/.env` in the HOME directory → `--email` flag (interactive password prompt — useless for agents).
 
-When the user confirms they are happy with the dev version and explicitly asks to publish:
+- **Hailer Studio:** `~/.env` is auto-injected — publishing just works, no flags.
+- **Local machines:** the `npx hailer-mcp` server self-provisions on first boot — it mints a user API key from the project bot's credentials and writes `HAILER_USER_API_KEY` to `~/.env` (Studio's mechanism, reproduced locally). So once the local MCP server has run once, publishing needs no auth flags. (Opt out: `HAILER_MCP_NO_PUBLISH_AUTH=true`.)
+- **ALWAYS pass `-- --force`.** Without it the publish stops at an interactive `Overwrite the app? (Y/n)` prompt — which an agent cannot answer, so the command hangs until it times out. Every publish command below includes it; never drop it.
+- **If publishing still hits exit code 10** (no auth — the CLI prints usage and quits): the local server hasn't run yet, or injection was disabled. Start `npx hailer-mcp` once, OR ask the user for a Hailer user API key (Hailer → profile → API keys) and pass `-- --user-api-key <key>`. **Never read passwords from .env, never log in via curl, never probe API endpoints for keys.**
 
-Update `public/manifest.json` — clear the `appId` (or use a different one) so `--create` makes a new separate production app entry. Then:
+Other exit codes: 8 = login failed (bad key/credentials), 7 = bundle isn't a .tgz (build problem), loud version error = `--market` without `version`/`versionDescription` in the manifest.
+</credentials>
 
-### On a developer's local machine (can reach api.hailer.com)
+<validate>
+## Step 4 — Validate BEFORE Any Production Publish
 
-```bash
-npm run publish-production -- --create --app-name "<App Name>" --workspace <workspaceId> --force
-```
+Check before publishing:
 
-### In Hailer Studio (cluster environment — cannot reach api.hailer.com)
+1. Read `public/manifest.json`
+2. `appId` exists, 24 chars — required for any non-`--create` publish (auto-written by `--create`)
+3. `version` + `versionDescription` non-empty — strictly required for `--market` publishes (the CLI errors loudly without them); keep them set always, `versionDescription` doubles as the app description
+4. `vite.config.ts` has `base: './'` — without it assets resolve to the root domain and production 403/404s while localhost works
+5. `index.html` has no-cache meta tags (apps.hailer.com is static hosting; server headers aren't controllable):
 
-```bash
-npm run publish-production -- --host http://hailer-api:1337 --create --app-name "<App Name>" --workspace <workspaceId> --force
+```html
+<meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate" />
+<meta http-equiv="Pragma" content="no-cache" />
+<meta http-equiv="Expires" content="0" />
 ```
 
-The `--host` flag overrides the hardcoded `https://api.hailer.com` default. Credentials are picked up automatically from `~/.env`.
+If a publish reports success but the app still serves the old/localhost version, re-check 2–5 — historical silent failures trace back to these.
+</validate>
 
-| Flag | Purpose |
-|------|---------|
-| `--create` | Creates a brand new app entry in Hailer |
-| `--app-name` | Name shown in Hailer |
-| `--workspace` | Workspace ID from `config.json` at project root |
-| `--force` | Skips confirmation prompt |
-| `--host` | API URL — required in cluster environments |
-| `--user-api-key` | API key — read from `~/.env` if not provided as flag |
+<prod-publish>
+## Step 5 — Production Publish (only when the user explicitly asks)
 
-**Credential resolution order:**
-1. `--user-api-key` or `--email` flags
-2. `USER_API_KEY` or `HAILER_USER_API_KEY` environment variables
-3. `HAILER_USER_API_KEY` from `~/.env` ← auto-injected by Hailer Studio
+**FIRST, decide first-publish vs update by READING `public/manifest.json` — never guess, never fail-first.** The scaffold ships a placeholder `appId` of `65143728d2bd678b13daf289` (the "Magic Apps" demo). That value, or empty/missing, means this app has never been published:
 
-After running, `public/manifest.json` is auto-updated with the new `appId`.
+| manifest `appId` | This is a… | Command |
+|---|---|---|
+| `65143728d2bd678b13daf289`, `""`, or missing | **FIRST publish** | `--create --app-name "<Name>" --workspace <wsId> --force` (all three required with `--create`) |
+| a real 24-char id you created earlier | **update** | `--force` only |
 
-### After publishing — share with workspace
-
-The CLI publish does NOT auto-share. Share manually via MCP:
-
-```javascript
-add_app_member({ appId: "<appId>", member: "network_<workspaceId>" })
-```
-</step-5>
-
-<step-6>
-## Step 6 — Subsequent Publishes
-
-### Local machine
+A plain publish against the scaffold's placeholder appId silently uploads to the demo app (wrong) or errors — so on a fresh scaffold, ALWAYS take the `--create` path on the very first publish. Get `<wsId>` from `config.json` (`workspaceId`); derive `<Name>` from the project (e.g. "Upcoming Matches") or ask.
 
 ```bash
-npm run publish-production -- --force
-```
+# FIRST publish (fresh scaffold) — local machine
+npm run publish-production -- --create --app-name "<App Name>" --workspace <workspaceId> --force
 
-### Hailer Studio (cluster)
+# FIRST publish — Hailer Studio (cluster, cannot reach api.hailer.com)
+npm run publish-production -- --host http://hailer-api:1337 --create --app-name "<App Name>" --workspace <workspaceId> --force
 
-```bash
-npm run publish-production -- --host http://hailer-api:1337 --force
+# UPDATE (manifest already has a real appId)
+npm run publish-production -- --force
 ```
 
-The `appId` in `manifest.json` determines which app gets updated.
-</step-6>
+**PUBLISH FAILURE PLAYBOOK — exact error → exact action, no improvising:**
+| Failure | Meaning | Action |
+|---|---|---|
+| exit 10, usage printed | no auth | start `npx hailer-mcp` once (mints the key), or `-- --user-api-key <key>` |
+| exit 2, "app was not found using <identity>" | manifest appId doesn't belong to this user/workspace (first publish, or a wrong appId) | re-run with **all three flags together — `--create` REQUIRES `--app-name "<Name>"` AND `--workspace <wsId>`** (`--create` alone, or with just `--force`, fails): `npm run publish-production -- --create --app-name "<Name>" --workspace <wsId> --force`. **NEVER "register the app first" via workspace/apps.ts** — that creates a registry entry with a URL you'd have to invent (placeholder URLs break the app: Hailer fetches `<url>/manifest.json` → "manifest missing"). `--create` makes the entry AND sets the real CDN URL |
+| exit 8 | login failed | the key/credentials are bad — re-mint or ask the user |
+| hangs at "Overwrite the app? (Y/n)" | missing `--force` | always pass it |
 
-<dev-vs-prod>
-## Dev vs Production Strategy
+**Manifest hand-edit rules:** never invent or copy an `appId` (only `--create` or a previous publish writes it); never delete `version`/`versionDescription` (versionDescription doubles as the app description, both are required for `--market`); do fix the placeholder `author` ("Magic Apps Ltd.") to the real one. apps.ts is for SHARING an app that already exists — after publish, `npm run pull` brings the entry in; edit members there.
 
-Always maintain two separate published app entries in Hailer:
+**FIRST-PUBLISH GOTCHA — the `--create` bundle embeds a stale manifest. Do these two things:**
+1. **Before publishing, fix `public/manifest.json`**: the scaffold leaves a placeholder `author` (e.g. "Magic Apps Ltd.") and `description`. Set the real values now — the agent controls these.
+2. **After the `--create` publish, republish once** (plain `npm run publish-production -- --force`). Reason: the script packs the tarball *before* `--create` learns the new `appId`, so the first uploaded bundle has the placeholder `appId` baked in. The second publish embeds the correct one (the manifest now holds the real `appId`). This is a known app-sdk ordering bug — the double-publish is the workaround, not optional.
 
-| App | Name convention | Purpose |
-|-----|----------------|---------|
-| Dev | `My App - Dev` | Publish here repeatedly during development and testing |
-| Production | `My App` | Publish here only when user confirms they are happy |
+**What the CLI itself does** (`@hailer/app-sdk` publish.cjs): `--create` makes the app entry (`v3.app.create`) and writes the `appId` to the manifest; the bundle is packed (`package/` prefix) and POSTed to `/app/publish`; the server hosts it at `https://apps.hailer.com/{workspaceId}/{appId}/`.
 
-**In Hailer Studio, `localhost:3000` is not accessible to the user — publishing is the only way to test inside Hailer. This means the dev app gets published and re-published on every iteration.**
+**What the CLI does NOT do:** icon, name/description updates, workspace sharing. Finish those after publishing: share with `manage_app({ action: 'add_member', appId, member: 'network_<wsId>' })`, and set an icon with `manage_app({ action: 'update', appId, image: <fileId> })` if wanted (icon files MUST be uploaded `isPublic: true`, PNG/JPEG only).
 
-To switch between dev and production app entries, keep track of both `appId` values. Before publishing production, set `appId` in `public/manifest.json` to the production app's ID (or use `--create` to make a new one).
-</dev-vs-prod>
-
-<environments>
-## Environments
-
-| Command | Default target |
-|---------|---------------|
-| `npm run publish-production` | https://api.hailer.com |
-| `npm run publish-development` | https://testapi.hailer.biz |
-| `npm run publish-staging` | https://api.hailer.biz |
-
-**In Hailer Studio**, append `-- --host http://hailer-api:1337` to any of the above to override the default host:
-
-```bash
-npm run publish-production -- --host http://hailer-api:1337 --force
-```
-</environments>
-
-<checklist>
-## Dev App Checklist (Step 4 — do this first)
-
-- [ ] Published as `<App Name> - Dev` using `--create --app-name "<App Name> - Dev"`
-- [ ] Shared dev app with workspace via MCP `add_app_member`
-- [ ] App opens and works correctly inside Hailer
-- [ ] Iterate: fix → `npm run publish-production -- --host ... --force` → test in Hailer → repeat
-
-## Production Publish Checklist (Step 5 — only when user asks to publish)
-
-- [ ] User has explicitly requested publishing/deploying
-- [ ] Read `<project-name>/README.md` — it always has the latest commands for that version
-- [ ] Verify `public/manifest.json` has the correct `appId` for the target app
-- [ ] `version` and `versionDescription` in manifest are only required for marketplace publishes
-- [ ] Build runs automatically as part of the publish script — no separate build step needed
-- [ ] Workspace ID is in `config.json` at the project root
-- [ ] Fixed `StoreSet` type error in `src/hailer/use-app.ts` (`replace?: false` not `boolean`)
-- [ ] **Hailer Studio:** Append `-- --host http://hailer-api:1337` to `npm run publish-*`
-- [ ] **After first publish:** Manually share via MCP `add_app_member` — CLI does not auto-share
-</checklist>
+| Flag | Purpose |
+|------|---------|
+| `--create` | New app entry (clear/replace `appId` in manifest first if reusing a dev manifest) |
+| `--app-name` | Name shown in Hailer (required with `--create`) |
+| `--workspace` | Workspace ID (`config.json` at project root; required with `--create`) |
+| `--market` | Also publish this version to the marketplace (requires `version` + `versionDescription`; server returns `targetId`, auto-saved to manifest) |
+| `--force` | Skip confirmation prompt |
+| `--host` | API URL override — required in cluster environments |
+| `--user-api-key` / `--email` | Else `USER_API_KEY`/`HAILER_USER_API_KEY` env, else `~/.env` (auto-injected in Studio) |
+| `--production` / `--development` / `--staging` / `--local` | Environment preset (the `npm run publish-*` wrappers set these) |
+
+**Subsequent publishes:** just `npm run publish-production -- --force` (+ `--host` in Studio) — the manifest `appId` picks the target. Bump `version`/`versionDescription` per release.
+
+**Environments:** `publish-production` → api.hailer.com, `publish-development` → testapi.hailer.biz, `publish-staging` → api.hailer.biz.
+
+**Verify:** MCP `list_apps()` — URL must be `https://apps.hailer.com/...`, not localhost.
+</prod-publish>
+
+<marketplace>
+## Marketplace Publishing
+
+Two different things:
+1. **App version publish** (`npm run publish-production -- --market --force`) — uploads files AND registers the version on the marketplace. Requires `version` + `versionDescription` in the manifest; the server returns a `targetId`, auto-saved to `public/manifest.json`.
+2. **Marketplace listing** (MCP `publish_marketplace` with `type: 'app'`) — title, description, icon, images on the listing. Does NOT upload app files.
+
+First-time: publish with `--market` (get `targetId`) → `publish_marketplace({ type: 'app', appId, versionId: <targetId>, title, ... })` → note the returned `productId`. Metadata updates later use `productId`; new versions re-publish with `--market`.
+
+| ID | What | Where |
+|----|------|-------|
+| `appId` | The app itself | manifest.json |
+| `targetId` | Version entry for marketplace | manifest.json (auto-saved) |
+| `productId` | Marketplace listing | returned by first `publish_marketplace`, find via `browse_marketplace` |
+</marketplace>
+
+<gotchas>
+## Gotchas
+
+- **Icons must be uploaded `isPublic: true`** — private files render as broken/transparent images. The publish tool handles it; manual `upload_files` must pass the flag.
+- **No SVG icons** — the backend image pipeline (sharp) doesn't serve them; use PNG/JPEG. No SVG gradients in generated icons either (`flatten()` produces transparency — use solid RGB + composite).
+- **`StoreSet` type error** in scaffolded `src/hailer/use-app.ts`: `replace?: false`, not `boolean`.
+- Read the scaffolded project's README — it carries the exact commands for its version.
+</gotchas>

package/.claude/skills/hailer-app-builder/SKILL.md

@@ -12,10 +12,37 @@ triggers:
 
 Patterns and templates for building Hailer apps with @hailer/app-sdk.
 
+<build-philosophy>
+## How to Build Fast: Correct Data First, Theme Does the Looks
+
+The goal of the first version is **showing the correct data the user asked for** — not a custom-designed UI. Get the data right; the user iterates on looks afterward. Two rules make apps both fast and good:
+
+1. **Spend your effort on the data layer, because that's what's easy to get wrong.** Read the real field/phase/workflow IDs from `workspace/enums.ts` + `fields.ts` (never guess, never use labels as keys), fetch with the SDK, and read field values by ID. A dashboard that shows the *wrong* numbers beautifully is a failure; correct numbers in plain components is a success.
+
+2. **Do NOT hand-design UI or build a component library — the scaffold already installed the Hailer theme.** `main.tsx` wires `<ChakraProvider theme={hailerTheme}>`, so **every stock Chakra component is already on Hailer brand** (Nunito Sans, the full Hailer palette, light/dark via system) and there are **214 ready icons** in `src/hailer/theme/icons/`. Compose the UI from plain Chakra primitives — they look right for free:
+   - Layout: `Box`, `Flex`, `Grid`, `SimpleGrid`, `Stack`, `Container`
+   - Data: `Stat`/`StatLabel`/`StatNumber`/`StatHelpText` (stat cards), `Table`/`Thead`/`Tbody`/`Tr`/`Td`, `Card`/`CardHeader`/`CardBody`
+   - Text/state: `Heading`, `Text`, `Badge`, `Tag`, `Spinner`, `Skeleton`, `Alert`
+   - Import icons like `import { HailerSearch } from './hailer/theme/icons/HailerSearch'`
+
+   Don't write custom CSS, custom color values, or bespoke styled components on the first pass. Reach for a Chakra component; it's already themed. The user refines the look later — your job is correct data in a clean themed shell.
+
+3. **Always handle the three states** — loading (`Spinner`/`Skeleton`), empty (a `Text`, never a crash), and outside-Hailer (the app must render standalone — never block on `inside`). Real data is async; assume it's missing first.
+
+4. **The scaffold's package.json IS the dependency budget — do NOT `npm install` anything else.** The scaffold already ships everything a v1 app needs: `@chakra-ui/react` (+emotion) for UI, `chart.js` + `react-chartjs-2` for charts, `framer-motion` for animation AND drag gestures, `zustand` for state, `immer`, and `@hailer/app-sdk`. No dnd-kit, no other chart libs, no date libs, no component kits — external packages mean unreviewed bytes shipped into the workspace and a look that drifts off-theme. If the requested UX genuinely seems to need a new dependency, FIRST prefer the simpler themed version (e.g. a board moves items with buttons/menus + `hailer.activity.update`, or framer-motion drag), and if that truly won't do, ASK the user before installing anything.
+
+5. **VERIFY data exists BEFORE building against it, and AFTER publishing.** An app that renders its empty state on real data is NOT done — it's unverified. Before writing components: check activity counts per phase (MCP `list_activities` with `countOnly: true`, or `core_init`) for every workflow+phase you plan to fetch. If the phase you targeted is empty (e.g. zero matches in "Scheduled"), pick the phases that actually hold the data — don't guess from phase names. After publishing: state what data the app should show ("8 matches in Scheduled, 24 fans across 4 phases") so the user can confirm the live app matches. "Shipped, shows 'no data'" is a failed delivery unless the workspace genuinely has no data — and then say so explicitly.
+</build-philosophy>
+
 <critical-rules>
 ## CRITICAL: Scaffolding and Data Sources
 
-**ALWAYS use scaffold_hailer_app MCP tool** to create new apps. Never manually create the project structure. Never call `create_app` separately during scaffolding — it creates duplicates.
+**Scaffold with the exact non-interactive form, then prep it:**
+```
+npx @hailer/create-app <name> --template react-ts
+npx hailer-mcp prep-app <name>
+```
+The name is POSITIONAL (not `--name`), the template must be valid (`react-ts`/`react`/`vanilla-ts`/`svelte-ts`/…, NOT `minimal`), and the dir must be fresh — that combination runs with zero prompts. A bare `npx @hailer/create-app`, a wrong `--name` flag, an invalid template, or piping input all drop into an interactive prompt that hangs the agent. `prep-app` then clears the scaffold's placeholder appId + fake author and fixes its `StoreSet` tsc error, so you skip those papercuts entirely. Scaffold fresh, never copy an existing app, never hand-create the structure. (Apps are script-only — no MCP scaffold tool exists.)
 
 **For project data structure (workflows, fields, phases):**
 - READ workspace/ TypeScript files directly (fields.ts, phases.ts, enums.ts)
@@ -171,7 +198,7 @@ export default function useHailer() {
 
 ### Giuseppe Rule
 
-After `scaffold_hailer_app`, ALWAYS replace `src/hailer/use-hailer.ts` with the shared-state version above.
+After scaffolding with `npx @hailer/create-app`, ALWAYS replace `src/hailer/use-hailer.ts` with the shared-state version above.
 </usehailer-fix>
 
 <sdk-api>