@hailer/mcp 1.1.17-beta.3 → 1.2.1

package/.claude/CLAUDE.md

@@ -1,167 +1,126 @@
-# Hailer MCP Server
+# Hailer SDK + MCP Project
 
-## Rules (MUST follow)
+## The One Rule
 
-1. **Workspace reads → spawn haiku sub-agent.** Never read `workspace/` files in main context. They fill context and can't be freed.
-2. **Skill loads → sub-agent only.** Never load skills (Skill tool) in main context. Tell the sub-agent which skills to load.
-3. **Workspace edits → spawn sonnet sub-agent.** Fields, functions, phases — always in a sub-agent with skill names + IDs front-loaded.
-4. **MCP tools are fine in main context.** Tool results are small. Use them for discovery (IDs, schemas, data).
-5. **Load skills before editing.** `sdk-function-fields` + `sdk-ws-config-skill` for function fields. Skills have critical steps (omit `_id` for new fields, push → pull → phases).
-6. **New fields: omit `_id`.** The server assigns it. Push → pull → add to phases → push phases.
-7. **Function fields: `fields-push:force`** not `fields-push`. Non-force skips `functionVariables` diffs.
-8. **After pull: verify enum imports.** Identical hex suffixes across workflows can resolve to wrong enum. Fix manually.
-9. **Pattern:** MCP discovery (main) → spawn sub-agent with IDs + skill names + task → sub-agent does all file work → returns summary.
+**If it can be done locally, do it locally. MCP tools are ONLY for things that require a server call.**
 
----
+This project has `workspace/` files managed by `@hailer/sdk`. These files ARE the source of truth for all workflow configuration. The MCP server provides tools for runtime operations that require talking to Hailer's API.
 
-MCP tools for Hailer workspaces: workflows, activities, insights, and apps.
+## What Goes Where
 
-## Quick Start
+| Need | Do this | NEVER this |
+|------|---------|------------|
+| **Find workflow/field/phase IDs** | Read `workspace/enums.ts` | ~~`list_workflows_minimal`~~, ~~`get_workflow_schema`~~, ~~`list_workflow_phases`~~ |
+| **See field types, labels, options** | Read `workspace/<Name>_<id>/fields.ts` | ~~`get_workflow_schema`~~ |
+| **See phases** | Read `workspace/<Name>_<id>/phases.ts` | ~~`list_workflow_phases`~~ |
+| **See all workflows** | Read `workspace/workflows.ts` | ~~`list_workflows`~~ |
+| **Create/modify fields** | Edit `fields.ts` → `npm run fields-push:force` | ~~`update_workflow_field`~~ |
+| **Create/modify phases** | Edit `phases.ts` → `npm run phases-push:force` | ~~`update_workflow_phase`~~ |
+| **Create/modify workflows** | Edit `workflows.ts` → `npm run workflows-sync:force` | ~~`install_workflow`~~ |
+| **Create/modify teams** | Edit `teams.ts` → `npm run teams-push:force` | — |
+| **Create/modify groups** | Edit `groups.ts` → `npm run groups-push:force` | — |
+| **Create activities** | MCP `create_activity` | — |
+| **List/read activities** | MCP `list_activities`, `show_activity_by_id` | — |
+| **Update activities** | MCP `update_activity` | — |
+| **Query data** | MCP `preview_insight`, `create_insight` | — |
+| **Discussions** | MCP discussion tools | — |
+| **Activity counts** | MCP `core_init` (once per session) | — |
+| **Scaffold app** | MCP `scaffold_hailer_app` | — |
+| **Publish app** | MCP `publish_hailer_app` | — |
 
-```bash
-npm init @hailer/sdk              # Scaffold project with workspace/ config
-npm run pull                      # Pull latest workflow schemas from Hailer
-npm run generate                  # Generate TypeScript types
-```
-
-## How to Work
+**If you're about to call an MCP tool, ask yourself: "Is this data in workspace/ files?" If yes, read the file instead.**
 
-Do simple things directly. For complex tasks, spawn parallel sub-agents.
+## How to Read workspace/ Files
 
-**Model usage — conserve Opus for orchestration only:**
-- **You (Opus):** Orchestrate, synthesize results, make decisions. Do NOT write large code blocks yourself.
-- **Sub-agents (Sonnet):** Write code, build features, complex edits. Use `model: "sonnet"`.
-- **Sub-agents (Haiku):** Read files, search code, data lookups, reviews. Use `model: "haiku"`.
-- **Rule:** If a task takes more than ~20 lines of code, delegate to a sonnet sub-agent.
+**Never read workspace/ files in main context** — they're large and fill context permanently.
 
-**Speed rules:**
-- Do data discovery yourself (MCP calls are instant)
-- Spawn all agents in one message
-- Front-load context — agents should write code, not discover things
-- Background long tasks with `run_in_background: true`
+1. Spawn a **haiku sub-agent** to read the files
+2. Have it extract what you need (IDs, field types, phase names)
+3. It returns a short summary
+4. Use that summary for MCP runtime calls
 
-**Feature requests:** Ask "Want me to create a PRD first?" before implementing.
+```
+Pattern: haiku reads workspace/ → you get IDs → MCP create_activity/list_activities
+```
 
-## Skills
+## Sub-Agent Rules
 
-Skills are in `.claude/skills/<name>/SKILL.md`. Load via the Skill tool.
+- **Haiku:** Read files, search code, data lookups, reviews
+- **Sonnet:** Write code, build features, complex edits
+- **You (Opus):** Orchestrate, synthesize results, make decisions
+- **Skills:** Load in sub-agents only, never in main context
+- If a task takes more than ~20 lines of code, delegate to sonnet
 
-### Workspace & Config
-| Skill | Use when |
-|-------|----------|
-| `sdk-ws-config-skill` | Workflows, fields, phases, teams, groups, new project setup |
-| `sdk-function-fields` | Calculated fields, nameFunction |
-| `sdk-activity-patterns` | Creating/updating activities |
-| `sdk-insight-queries` | SQL-like insight queries, cross-workflow JOINs |
-| `sdk-document-templates` | PDF/CSV document templates |
-| `hailer-permissions-system` | Workflow permissions |
-
-### App Development
-| Skill | Use when |
-|-------|----------|
-| `hailer-app-builder` | Building Hailer apps (React/Chakra) |
-| `hailer-design-system` | Theme, colors, icons, layout, spacing, responsive design |
-| `hailer-apps-pictures` | Images/photos in apps |
-| `publish-hailer-app` | Publishing to production |
-
-### Integrations
-| Skill | Use when |
-|-------|----------|
-| `hailer-monolith-automations` | Webhook handlers, scheduled jobs, phase cascade bots |
-| `zapier-hailer-patterns` | Zapier integrations |
-| `integration-patterns` | General integration patterns |
-| `hailer-api-client` | HailerApiClient for backend |
-
-### Code Quality
-| Skill | Use when |
-|-------|----------|
-| `testing-patterns` | Vitest/playwright tests |
-| `api-documentation-patterns` | API endpoint docs |
-| `lsp-setup` | LSP code inspection |
-| `tool-builder` | Building new MCP tools |
-
-## Local-First Data
-
-Check workspace/ BEFORE making API calls.
+## workspace/ Structure
 
 ```
 workspace/
-├── workflows.ts, enums.ts, teams.ts, groups.ts
-└── [Workflow]_[id]/
-    ├── fields.ts
-    └── phases.ts
+├── enums.ts          # ALL IDs — WorkflowIds, FieldIds, PhaseIds, etc.
+├── workflows.ts      # Workflow registry
+├── teams.ts          # Team definitions
+├── groups.ts         # Group definitions
+├── insights.ts       # Insight definitions
+└── <WorkflowName>_<id>/
+    ├── fields.ts     # Field definitions (type, label, key, options, required)
+    ├── phases.ts     # Phase definitions (name, key, isInitial, isEndpoint)
+    ├── main.ts       # Workflow config
+    └── functions/    # Function field code (if any)
 ```
 
-LOCAL: Workflow/field/phase IDs, field types, labels, options
-API: Activity data, counts, discussion messages
-REFRESH: `npm run pull`
+**Refresh:** `npm run pull` syncs server → local files
 
-## Hooks
+## SDK Push Commands (all use `:force` to avoid interactive prompts)
 
-4 safety hooks in `.claude/hooks/`:
+| Command | What it does |
+|---------|-------------|
+| `npm run push:force` | Push everything |
+| `npm run fields-push:force` | Push field changes only |
+| `npm run phases-push:force` | Push phase changes only |
+| `npm run workflows-sync:force` | Sync workflow registry (create/delete) |
+| `npm run teams-push:force` | Push team changes |
+| `npm run groups-push:force` | Push group changes |
+| `npm run pull` | Pull latest from Hailer → local files |
 
-- `session-start.cjs` — loads SESSION-HANDOFF.md on start
-- `bash-guard.cjs` — confirms destructive shell commands
-- `bulk-activity-guard.cjs` — confirms bulk activity writes
-- `publish-template-guard.cjs` — confirms template publishes
-- `context-watchdog.cjs` — monitors context usage
+## SDK Gotchas
+
+| Gotcha | Correct | Wrong |
+|--------|---------|-------|
+| New fields | Omit `_id` — server assigns it | Adding `_id` manually |
+| After push | Always `npm run pull` to get server-assigned IDs | Assuming local IDs are final |
+| Function fields | `npm run fields-push:force` (non-force skips functionVariables) | `npm run fields-push` |
+| Enum imports | Verify after pull — identical hex suffixes can collide | Trusting auto-generated imports |
+| `linkedfrom` fields | Don't work in isolated-vm — use `<` backlink dependency | Using in function fields |
+| Function field code | Plain JavaScript only | TypeScript syntax |
+| Phase transitions | Exact string match on phase name | Guessed names |
+| Field values (MCP) | Date: Unix ms (`1730937600000`), Dropdown: exact string, ActivityLink: string ID | ISO dates, arrays, objects |
 
 ## App Development
 
-**Scaffold:** Always use `scaffold_hailer_app` MCP tool. Never copy an existing app.
+| Step | How |
+|------|-----|
+| Scaffold | MCP `scaffold_hailer_app` — never copy apps |
+| Publish | MCP `publish_hailer_app` — auto icon, name, description, sharing |
+| Local dev | `npm run dev` from app directory |
 
-**Local dev:** Scaffold creates app at `http://localhost:3000`. Run `npm run dev`.
+## Skills
 
-**Publishing:** Only when user asks. Load `publish-hailer-app` skill.
+Load in sub-agents via Skill tool. Never in main context.
+
+| Skill | When |
+|-------|------|
+| `sdk-ws-config-skill` | Workflows, fields, phases, teams, groups |
+| `sdk-function-fields` | Calculated fields, nameFunction |
+| `sdk-activity-patterns` | Creating/updating activities via MCP |
+| `sdk-insight-queries` | SQL insight queries |
+| `hailer-app-builder` | Building Hailer apps (React/Chakra) |
+| `hailer-design-system` | Theme, colors, icons, layout |
+| `publish-hailer-app` | Publishing apps to production |
+| `testing-patterns` | Vitest/playwright tests |
 
 ## Commands
 
-`/command <param>` (angle brackets = required). `/help:topic` (colon = subtopic).
+`/command <param>` — angle brackets = required
 
 **Essential:** `/save`, `/handoff`, `/prd`, `/autoplan`, `/ws-pull`
 
-**Squads:**
-| Squad | Use for |
-|-------|---------|
-| `/app-squad` | Build apps end-to-end |
-| `/review-squad` | Code review + tests |
-| `/config-squad` | Workflow + fields + insights |
-| `/hotfix-squad` | Quick bug fixes |
-| `/debug-squad` | Investigation |
-| `/swarm <desc>` | Large-scale parallel work |
-
-## Project Structure
-
-```
-src/                 # MCP server source
-workspace/           # Hailer config - check FIRST for IDs
-apps/                # Frontend apps
-integrations/        # Backend services
-.claude/             # Skills, hooks, commands
-```
-
-## When to Use SDK Files vs MCP Tools
-
-| Task | Use | NOT |
-|------|-----|-----|
-| Create/modify fields, phases, workflows | Edit `workspace/` files → `npm run push` | MCP `update_workflow_field` |
-| Create function fields | Edit `fields.ts` + `functions/` → `vitest` → `npm run fields-push` | MCP tools |
-| Read/write activity data | MCP tools (`list_activities`, `create_activity`, etc.) | Editing files |
-| Query/report on data | MCP `preview_insight`, `create_insight` | — |
-| Test existing function field code | MCP `test_function_field` (with `functionVariables`) | — |
-
-**Function field workflow:** See Rules #5-8 at top of file.
-
-## Hailer SDK Gotchas
-
-| Gotcha | Correct | Wrong |
-|--------|---------|-------|
-| Activity field updates | `{type: "string", value: "x"}` | Raw value `"x"` |
-| `linkedfrom` field type | Does NOT work in isolated-vm | Use `<` backlink dependency in functionVariables instead |
-| Code in isolated-vm | Plain JavaScript only | TypeScript syntax |
-| Phase transitions | Exact string match | Guessed names |
-| Field IDs | Read from workspace/ | Guessing from labels |
-| Dropdown values | `{data: [{value, label}]}` | `{options: [...]}` |
-| ActivityLink format | Plain string array | Nested objects |
-
-**Rule:** Always read workspace/ first. Never guess IDs or formats.
+**Squads:** `/app-squad`, `/review-squad`, `/config-squad`, `/hotfix-squad`, `/debug-squad`, `/swarm <desc>`

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

@@ -0,0 +1,204 @@
+---
+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
+triggers:
+  - create-app
+  - npx create-app
+  - hailer create-app
+  - scaffold app cli
+---
+
+# Create and Publish Hailer App
+
+Scaffold, create and publish Hailer apps using `@hailer/create-app` npm package.
+
+**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
+
+| 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.**
+</when-to-use>
+
+<step-1>
+## Step 1 — Scaffold the Project
+
+```bash
+npx @hailer/create-app <project-name> --template react-ts
+```
+
+- 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
+
+```bash
+cd apps/<project-name>
+npm install
+```
+</step-2>
+
+<step-3>
+## Step 3 — Build the App UI
+
+Replace `src/App.tsx` and add components. Key patterns:
+
+- 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>
+
+<step-4>
+## Step 4 — Publish Dev Version
+
+**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.
+
+### Hailer Studio (cluster)
+
+```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>" })
+```
+
+**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.
+
+**Only proceed to Step 5 when the user explicitly says they are happy and want to publish to production.**
+</step-4>
+
+<step-5>
+## Step 5 — Publish to Production (Only When User Explicitly Asks)
+
+When the user confirms they are happy with the dev version and explicitly asks to publish:
+
+Update `public/manifest.json` — clear the `appId` (or use a different one) so `--create` makes a new separate production app entry. Then:
+
+### On a developer's local machine (can reach api.hailer.com)
+
+```bash
+npm run publish-production -- --create --app-name "<App Name>" --workspace <workspaceId> --force
+```
+
+### In Hailer Studio (cluster environment — cannot reach api.hailer.com)
+
+```bash
+npm run publish-production -- --host http://hailer-api:1337 --create --app-name "<App Name>" --workspace <workspaceId> --force
+```
+
+The `--host` flag overrides the hardcoded `https://api.hailer.com` default. Credentials are picked up automatically from `~/.env`.
+
+| 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 |
+
+**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
+
+After running, `public/manifest.json` is auto-updated with the new `appId`.
+
+### 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
+
+```bash
+npm run publish-production -- --force
+```
+
+### Hailer Studio (cluster)
+
+```bash
+npm run publish-production -- --host http://hailer-api:1337 --force
+```
+
+The `appId` in `manifest.json` determines which app gets updated.
+</step-6>
+
+<dev-vs-prod>
+## Dev vs Production Strategy
+
+Always maintain two separate published app entries in Hailer:
+
+| 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 |
+
+**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.**
+
+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>

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

@@ -483,6 +483,53 @@ const workspaces = await hailer.workspace.list();
 ```
 </sdk-api>
 
+<field-resolver>
+## Field Resolver Pattern
+
+Every scaffolded app includes `src/hailer/field-resolver.ts`. It resolves human-readable field keys to hex IDs at runtime.
+
+### Functions
+
+**`createFieldResolver(workflowFields)`** — low-level. Takes a workflow's `fields` map, returns a resolver function.
+
+**`useFieldResolver(workflows, workflowId)`** — hook-friendly wrapper. Takes `useApp().app.workflows` and a workflow ID.
+
+### How It Works
+
+- Pass a field **key** (e.g., `'matchDate'`) → resolves to hex ID at runtime
+- Pass a field **hex ID** (e.g., `'691ffdf84217e9e8434e5697'`) → returns as-is
+- Workflows without keys → passthrough, hex IDs still work
+
+### Usage
+
+```typescript
+import { useFieldResolver } from './hailer/field-resolver';
+import { useApp } from './hailer/use-app';
+
+const WORKFLOW_ID = '691ffdf84217e9e8434e56a5';
+const FIELD_KEYS = {
+  MATCH_DATE: 'matchDate',
+  HOME_TEAM: 'homeTeam',
+};
+
+function MyComponent() {
+  const { app } = useApp();
+  const f = useFieldResolver(app.workflows, WORKFLOW_ID);
+
+  // f() resolves keys to IDs — works with either
+  const date = activity.fields?.[f(FIELD_KEYS.MATCH_DATE)];
+  const team = activity.fields?.[f(FIELD_KEYS.HOME_TEAM)];
+}
+```
+
+### Key Points
+
+- Define field keys as constants (human-readable, portable across workspaces)
+- The resolver handles both keys and hex IDs — safe to pass either
+- Wait for workflow data before fetching activities — add the workflow to `useEffect` deps
+- `useApp().app.workflows` is loaded on init by the scaffold's `onReady` handler
+</field-resolver>
+
 <field-patterns>
 ## Extracting Field Values
 

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

@@ -86,11 +86,17 @@ publish_hailer_app({
 ```
 
 This does everything in one call:
+- **Auto-derives app name** from project directory (e.g., `upcoming-matches` → "Upcoming Matches")
+- **Auto-sets description** from `versionDescription` in manifest.json
+- **Auto-generates and uploads a colored icon** with initials (e.g., green "UM" circle)
+- **Auto-shares** with the entire workspace
 - Copies manifest.json into dist/
 - Creates .tgz with `package/` prefix (matches npm pack format)
 - Uploads to S3 via POST /app/publish
 - **Auto-updates app URL** to `https://apps.hailer.com/{workspaceId}/{appId}/`
 
+No manual `update_app` calls needed after publish — name, description, icon, and sharing are all automatic.
+
 ### Step 3: Verify
 
 ```javascript
@@ -124,9 +130,14 @@ If missing/empty, the tool returns "Success" but files are NOT uploaded.
 **Flow:**
 1. `scaffold_hailer_app` checks for existing dev app at localhost:3000 — reuses it instead of creating duplicates
 2. Dev app stays at localhost forever — it's your development slot
-3. When user says "publish": `publish_hailer_app` detects the dev app URL, auto-creates a NEW production app entry, publishes to it, and updates the URL
-
-**No manual `update_app` or `create_app` needed.** The publish tool handles everything automatically.
+3. When user says "publish": `publish_hailer_app` detects the dev app URL, auto-creates a NEW production app with:
+   - Name derived from project directory (e.g., `upcoming-matches` → "Upcoming Matches")
+   - Description from `versionDescription` in manifest.json
+   - Colored icon with initials (auto-generated, uploaded as public)
+   - Shared with entire workspace
+   - URL pointing to production CDN
+
+**No manual `update_app` or `create_app` needed.** The publish tool handles name, description, icon, sharing, and URL automatically.
 </dev-vs-prod>
 
 <updating>
@@ -181,6 +192,8 @@ Use `publish_app` with `productId` (the marketplace listing ID, NOT the targetId
 <sharing>
 ## Sharing Apps
 
+Workspace sharing is automatic on first publish. For manual sharing:
+
 ```javascript
 // Entire workspace
 add_app_member({ appId: "...", member: "network_{workspaceId}" })
@@ -193,6 +206,22 @@ add_app_member({ appId: "...", member: "user_{userId}" })
 ```
 </sharing>
 
+<gotchas>
+## Gotchas
+
+**App icons MUST be uploaded with `isPublic: true`.**
+Files uploaded without this flag are private — the Hailer frontend can't load them and shows a broken/transparent image. The publish tool handles this automatically, but if you manually upload an icon via `upload_files`, always include `isPublic: true`:
+```javascript
+upload_files({ files: [{ path: "/tmp/icon.png", isPublic: true }] })
+```
+
+**SVG images don't work as app icons.**
+Hailer's backend image pipeline uses sharp for resizing and doesn't serve SVGs correctly. Always use PNG or JPEG.
+
+**Don't use SVG gradients in icon generation.**
+Sharp's `flatten()` with SVG `linearGradient` produces transparency. Use `sharp.create()` with solid RGB background + composite for text.
+</gotchas>
+
 <vite-config>
 ## CRITICAL: Vite Base Path
 
@@ -241,9 +270,11 @@ Hailer apps are served from `apps.hailer.com` static hosting - we can't control
 
 - [ ] manifest.json `appId` is 24 chars (dev app ID is fine — publish auto-creates prod app)
 - [ ] manifest.json `version` is set (e.g., "1.0.0")
-- [ ] manifest.json `versionDescription` is set (not empty)
+- [ ] manifest.json `versionDescription` is set (not empty — also used as app description)
 - [ ] vite.config.ts has `base: './'`
 - [ ] index.html has no-cache meta tags (see cache-busting section)
 - [ ] node_modules exists (dependencies installed)
 - [ ] After publish: verify URL auto-updated to production format (check with `list_apps`)
+
+**Automatic on first publish** (no action needed): app name, description, colored icon, workspace sharing.
 </checklist>