@hailer/mcp 1.2.0 → 2.0.0-beta.1

package/.claude/commands/review-squad.md

@@ -1,152 +1,30 @@
 ---
-description: Run parallel code review with security, LSP inspection, and test verification
+description: Run parallel code review with security, static inspection, and test verification
 argument-hint: [files, directory, or blank for recent changes]
-allowed-tools: Task, Bash
+allowed-tools: Workflow, Bash, Read
 ---
 # Review Squad
 
-Parallel code review with iterative fix loop: find issues, auto-fix criticals, re-review.
+Parallel code review via the native Workflow tool: find issues per dimension, adversarially verify, auto-fix criticals, re-check.
 
-**Roles:**
-- **Code Reviewer** - Code review (bugs, security, best practices)
-- **LSP Inspector** - LSP inspection (dead code, unused imports, type errors)
-- **Test Runner** - Test runner (run tests, verify builds)
-- **Code Editor** - Auto-fix critical issues (only in loop iterations)
+**Target:** $ARGUMENTS — if blank, use `git diff --name-only HEAD` output.
+Flags: `--no-fix` (report only), `--skip-tests` (drop the test dimension).
 
-**Target:** $ARGUMENTS (if blank, use recent git changes)
+## Orchestration
 
-**Changed files:** Run `git diff --name-only HEAD` via Bash to get recent changes. Use the output as TARGET if no specific files are given.
+Author a Workflow script (this command is your opt-in to call the Workflow tool):
 
-## Protocol
+1. **Review phase** — one agent per dimension, in a `pipeline()` over:
+   - `bugs`: correctness, logic errors, race conditions, missing null checks
+   - `security`: injection, auth/permission gaps, secrets, fail-open paths
+   - `conventions`: repo eslint rules (no else/else-if, no nested ifs, no `=== undefined`, single quotes, 4-space indent, ≤140 cols), dead code, unused imports — verify with `npx eslint` + `npx tsc --noEmit`, not eyeballing
+   - `tests` (unless --skip-tests): run `npm test`, verify build, flag untested changed logic
+   Each returns findings via a `schema`: `{ file, line, severity: 'critical'|'warning', title, detail, autoFixable }`.
 
-### Step 1: Determine Target
+2. **Verify phase** — each finding goes to one adversarial verifier prompted to REFUTE it; drop refuted findings. (Same pipeline, no barrier.)
 
-If `$ARGUMENTS` has specific files/directories, use those.
-Otherwise, use the changed files list above as the target.
+3. **Fix phase** (skip with --no-fix) — if confirmed criticals are autoFixable (unused imports, dead code, simple type errors, obvious test fixes — NOT architecture/design/complex logic), spawn one fixer agent with the exact list: "minimal fixes only, no refactoring". Then re-run the affected dimension once. Max 2 fix iterations.
 
-If `$ARGUMENTS` contains `--skip-tests`:
-- Remove flag from target
-- Skip Test Runner in Step 2
+## Report
 
-If `$ARGUMENTS` contains `--skip-lsp`:
-- Remove flag from target
-- Skip LSP Inspector in Step 2
-
-If `$ARGUMENTS` contains `--no-fix`:
-- Skip the fix loop entirely (old behavior - report only)
-
-### Step 2: Launch Review Agents in Parallel
-
-**Set:** `iteration = 1`
-
-If `--bg` is present, add `run_in_background: true` to all agent calls below and tell the user they'll be notified when complete.
-
-Spawn all review agents simultaneously using multiple Task tool calls in a single message:
-
-**Code Reviewer:**
-```
-Task(prompt="Load testing-patterns skill for understanding test-related code issues.\n\nReview these files for bugs, security issues, and best practices: [TARGET]. [IF iteration > 1: Previous issues that were auto-fixed: [LIST FIXES APPLIED]. Verify these are resolved and check for any NEW issues introduced by the fixes.] Return verdict (APPROVE/REQUEST_CHANGES), critical count, warning count, and details. Categorize each issue as CRITICAL or WARNING.")
-```
-
-**LSP Inspector:**
-```
-Task(prompt="Load lsp-setup skill for understanding code inspection tools.\n\nInspect these files for dead code, unused imports, and type errors: [TARGET]. [IF iteration > 1: Previous issues that were auto-fixed: [LIST FIXES APPLIED]. Verify these are resolved.] Use LSP if available, fall back to tsc/eslint.")
-```
-
-**Test Runner:**
-```
-Task(prompt="Load testing-patterns skill for test execution.\n\nRun tests associated with these files: [TARGET]. Include build verification. Report pass/fail counts.")
-```
-
-### Step 3: Evaluate Results - Fix or Report
-
-Collect results from all agents. Check for **auto-fixable issues**:
-
-**Auto-fixable** (Code Editor can handle):
-- Unused imports
-- Dead code removal
-- Missing null checks
-- Simple type errors
-- Test failures with obvious fixes
-
-**NOT auto-fixable** (escalate to user):
-- Architecture concerns
-- Design pattern issues
-- Complex logic bugs
-- Security issues requiring design changes
-- Performance concerns
-
-#### If critical auto-fixable issues found AND `--no-fix` not set AND `iteration < 3`:
-
-Spawn a code editor with the specific issues:
-
-```
-Task(prompt="Fix these critical issues found by the review squad:\n\n[LIST AUTO-FIXABLE ISSUES WITH FILE PATHS AND LINE NUMBERS]\n\nFrom Code Reviewer: [critical issues]\nFrom LSP Inspector: [dead code, unused imports]\nFrom Test Runner: [test failures if obvious fix]\n\nApply minimal fixes only. Do not refactor or improve beyond the reported issues.")
-```
-
-After Code Editor finishes:
-- Increment `iteration`
-- Go back to **Step 2** to re-review the fixed code
-- On re-review, include what Code Editor fixed so agents can verify fixes and check for regressions
-
-#### If no auto-fixable criticals OR `--no-fix` set OR `iteration >= 3`:
-
-Proceed to Step 4 (report).
-
-### Step 4: Report
-
-```markdown
-## Review Squad Report
-
-### Loop Summary
-- Review iterations: [count]
-- Auto-fixes applied: [yes/no, count of issues fixed]
-
-### Code Reviewer
-**Verdict:** APPROVE / REQUEST_CHANGES
-- Critical: X (Y auto-fixed)
-- Warnings: X
-- [Remaining issues grouped by file]
-
-### LSP Inspector
-- Dead code: X items (Y auto-removed)
-- Unused imports: X (Y auto-removed)
-- Type errors: X
-- [Remaining issues grouped by file]
-
-### Test Runner
-- Tests: X passed, X failed
-- Build: Pass/Fail
-- [Failed test details if any]
-
-### Auto-Fixes Applied
-[If Code Editor made changes:]
-- [File]: [what was fixed]
-- [File]: [what was fixed]
-
-### Remaining Issues (Manual Action Needed)
-[Issues that couldn't be auto-fixed]
-
-### Summary
-[1-2 sentence overall assessment]
-```
-
-If any agent fails or times out, report partial results from successful agents, note which failed, and offer to re-run individually.
-
-## Options
-
-| Flag | Effect |
-|------|--------|
-| `--skip-tests` | Skip Test Runner (faster, no test execution) |
-| `--skip-lsp` | Skip LSP Inspector (when LSP not configured) |
-| `--no-fix` | Report only, no auto-fix loop (old behavior) |
-| `--bg` | Run all agents in background mode |
-
-If `--bg` is present, launch all agents with `run_in_background: true` and tell the user they'll be notified when complete.
-
-## Notes
-
-- Max 2 re-review iterations (3 total reviews) to prevent infinite loops
-- Code Editor only fixes clear-cut issues - ambiguous problems go to user
-- Each re-review is a full parallel sweep, not just Code Reviewer
-- The `--no-fix` flag gives the old report-only behavior
+Verdict (APPROVE / REQUEST_CHANGES), confirmed findings grouped by file with severity, what was auto-fixed, what needs manual action, test/build status. If a workflow stage dies, report partial results and say which dimension failed.

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

@@ -1,127 +1,146 @@
 ---
 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.0.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.
+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
 ```
 
-- Run from the `apps/` directory (create it first if it doesn't exist: `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
-</step-1>
+- 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`
+</scaffold>
 
-<step-2>
-## Step 2 — Install Dependencies
+<build>
+## Step 2 — Build the App UI
 
-```bash
-cd apps/<project-name>
-npm install
-```
-</step-2>
+Replace `src/App.tsx` and add components (load `hailer-app-builder` + `hailer-design-system` skills for patterns):
 
-<step-3>
-## Step 3 — Build the App UI
+- Use `useApp` from `src/hailer/use-app.ts` (zustand-based state)
+- Call `api.init()` in a `useEffect` in `App.tsx`
+- `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
+</build>
 
-Replace `src/App.tsx` and add components. Key patterns:
+<dev-publish>
+## Step 3 — Dev Iteration
 
-- Use `useApp` from `src/hailer/use-app.ts` (the new template uses 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>
+**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.
 
-<step-4>
-## Step 4 — Create and Publish (First Time)
+**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 -- --create --app-name "<App Name>" --workspace <workspaceId> --force
+npm run publish-production -- --host http://hailer-api:1337 --create --app-name "<App Name> - Dev" --workspace <workspaceId> --force
 ```
 
-| 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 |
+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>" })`.
 
-**No `--user-api-key` needed** — the publish script automatically picks up credentials from the `~/.env` file injected by Hailer Studio. 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` ← this is what Hailer Studio provides automatically
+| App | Name | Purpose |
+|-----|------|---------|
+| Dev | `My App - Dev` | publish repeatedly while iterating |
+| Production | `My App` | publish only when the user explicitly asks |
+</dev-publish>
 
-After running, `public/manifest.json` is auto-updated with the new `appId`.
-</step-4>
+<validate>
+## Step 4 — Validate BEFORE Any Production Publish
 
-<step-5>
-## Step 5 — Subsequent Publishes
+The publish CLI is `@hailer/app-sdk`'s `tools/publish.cjs` (scaffolded projects wrap it as `npm run publish-*`). Check before publishing:
 
-```bash
-npm run publish-production -- --force
-```
-
-The `appId` in `manifest.json` determines which app gets updated. No API key needed — `~/.env` is picked up automatically.
-</step-5>
+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):
 
-<dev-vs-prod>
-## Dev vs Production Strategy
+```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" />
+```
 
-Maintain two separate published apps:
+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>
 
-| App | Purpose |
-|-----|---------|
-| My App Dev | Publish here during iteration |
-| My App | Publish here only when ready for users |
+<prod-publish>
+## Step 5 — Production Publish (only when the user explicitly asks)
 
-Switch between them by changing `appId` in `public/manifest.json` before publishing.
-</dev-vs-prod>
+```bash
+# Local machine (reaches api.hailer.com)
+npm run publish-production -- --create --app-name "<App Name>" --workspace <workspaceId> --force
 
-<environments>
-## Environments
+# 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
+```
 
-| Command | Target |
-|---------|--------|
-| `npm run publish-production` | Production (https://api.hailer.com) |
-| `npm run publish-development` | Development (https://testapi.hailer.biz) |
-| `npm run publish-staging` | Staging (https://api.hailer.biz) |
-</environments>
+**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}/`.
 
-<checklist>
-## Checklist Before Publishing
+**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).
 
-- [ ] Read `apps/<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
-- [ ] No API key needed — `~/.env` is picked up automatically by the publish script
-</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`) — 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

@@ -15,7 +15,7 @@ Patterns and templates for building Hailer apps with @hailer/app-sdk.
 <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 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.)
 
 **For project data structure (workflows, fields, phases):**
 - READ workspace/ TypeScript files directly (fields.ts, phases.ts, enums.ts)
@@ -171,7 +171,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>