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

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

@@ -113,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,6 +28,8 @@ 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>

package/CLAUDE.md

@@ -27,7 +27,8 @@ Before any MCP call, ask: "Is this answerable from `workspace/` files or a CLI?"
 | Test function field code | vitest locally | `test_function_field` |
 | 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` | — |
@@ -102,7 +103,7 @@ Always use `:force` — the non-force variants prompt interactively.
 | 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.8",
+  "version": "2.0.0-beta.9",
   "config": {
     "docker": {
       "registry": "registry.gitlab.com/hailer-repos/hailer-mcp"