@hailer/mcp 2.0.0-beta.7 → 2.0.0-beta.9

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

@@ -30,10 +30,12 @@ Apps are scaffolded and published exclusively through the scripts: `npx @hailer/
 npx @hailer/create-app <project-name> --template react-ts
 ```
 
-- Run from a parent directory (`mkdir -p apps` first if needed)
-- NEVER copy an existing app — scaffold fresh
-- The CLI is interactive-only via `npm create` — always pass name + template as arguments
-- Then `cd apps/<project-name> && npm install`
+**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>
 
 <build>
@@ -111,6 +113,16 @@ npm run publish-production -- --create --app-name "<App Name>" --workspace <work
 npm run publish-production -- --host http://hailer-api:1337 --create --app-name "<App Name>" --workspace <workspaceId> --force
 ```
 
+**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 | re-run with `--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 |
+
+**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.
+
 **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.

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

@@ -28,12 +28,14 @@ The goal of the first version is **showing the correct data the user asked for**
    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. **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
 
-**Scaffold new apps with `npx @hailer/create-app` — scaffold fresh, never copy an existing app.** Never manually create the project structure. (Apps are script-only — no MCP scaffold tool exists.)
+**Scaffold with the exact non-interactive form: `npx @hailer/create-app <name> --template react-ts`.** 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. 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)

package/CLAUDE.md

@@ -25,9 +25,10 @@ Before any MCP call, ask: "Is this answerable from `workspace/` files or a CLI?"
 | Create / modify insights config | Edit `insights.ts` → `npm run insights-push:force` | — (runtime `run_insight` is fine) |
 | Create / modify document templates | Edit `templates/` → `npm run templates-sync:force` | — |
 | Test function field code | vitest locally | `test_function_field` |
-| Scaffold an app | `npx @hailer/create-app` (fresh — never copy an existing app) | — (script-only; no MCP tool exists) |
+| Scaffold an app | `npx @hailer/create-app <name> --template react-ts` (name is POSITIONAL, not `--name`; bare command PROMPTS and hangs agents) | — (script-only; no MCP tool exists) |
 | Publish an app | `cd app && npm run publish-production -- --force` (add `--market` for marketplace versions) | — (script-only; no MCP tool exists) |
-| Create / modify apps registry | Edit `workspace/apps.ts` → `npx hailer-sdk ws-config apps push --force` | `manage_app` |
+| Share / edit EXISTING app metadata | Edit `workspace/apps.ts` → `npx hailer-sdk ws-config apps push --force` | `manage_app` |
+| Create an app entry | NEVER via apps.ts — first publish with `--create` does it (correct URL included) | never invent placeholder URLs |
 | Create / update activities | MCP `create_activity`, `update_activity` | — |
 | List / read / count activities | MCP `list_activities` (`countOnly: true` for counts), `show_activity_by_id` | — |
 | Query data (SQL reports) | MCP `run_insight`, `save_insight` | — |
@@ -99,10 +100,10 @@ Always use `:force` — the non-force variants prompt interactively.
 
 | Step | How |
 |------|-----|
-| Scaffold | `npx @hailer/create-app` — scaffold fresh, never copy an existing app |
+| Scaffold | `npx @hailer/create-app <name> --template react-ts` (name POSITIONAL; bare = interactive prompt that hangs agents) — scaffold fresh, never copy an existing app |
 | Local dev | `cd app && npm run dev` |
 | Publish | `cd app && npm run publish-production -- --force` (add `--market` for marketplace; `--force` skips the overwrite prompt that hangs agents); then share via `manage_app` add_member |
-| Register / share | Edit `workspace/apps.ts` → `npx hailer-sdk ws-config apps push --force` |
+| Share (after publish) | `npm run pull`, then edit members in `workspace/apps.ts` → `npx hailer-sdk ws-config apps push --force`. NEVER create app entries in apps.ts — `--create` publish makes them |
 
 Publish auth: works flag-free once the local `npx hailer-mcp` server has run once — it mints a user API key from the project bot creds into `~/.env`, mirroring Studio. Exit 10 = no auth yet → start the server once, or pass `-- --user-api-key <key>`; NEVER read passwords or probe login endpoints. Details: `create-and-publish-app` skill.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hailer/mcp",
-  "version": "2.0.0-beta.7",
+  "version": "2.0.0-beta.9",
   "config": {
     "docker": {
       "registry": "registry.gitlab.com/hailer-repos/hailer-mcp"