@hailer/mcp 1.2.0 → 1.3.9

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

@@ -1,127 +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.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
+npx hailer-mcp prep-app <project-name>
 ```
 
-- 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>
-
-<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
+
+**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>
+
+<dev-publish>
+## Step 3 — Dev Iteration
+
+**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>
+<credentials>
+## Credentials — Read This Before Publishing Fails
 
-<step-5>
-## Step 5 — Subsequent Publishes
+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).
 
-```bash
-npm run publish-production -- --force
+- **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.**
+
+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>
+
+<validate>
+## Step 4 — Validate BEFORE Any Production Publish
+
+Check before publishing:
+
+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):
+
+```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 `appId` in `manifest.json` determines which app gets updated. No API key needed — `~/.env` is picked up automatically.
-</step-5>
+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>
+
+<prod-publish>
+## Step 5 — Production Publish (only when the user explicitly asks)
+
+**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:
+
+| 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 |
+
+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.
 
-<dev-vs-prod>
-## Dev vs Production Strategy
+```bash
+# FIRST publish (fresh scaffold) — local machine
+npm run publish-production -- --create --app-name "<App Name>" --workspace <workspaceId> --force
 
-Maintain two separate published apps:
+# 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
 
-| App | Purpose |
-|-----|---------|
-| My App Dev | Publish here during iteration |
-| My App | Publish here only when ready for users |
+# UPDATE (manifest already has a real appId)
+npm run publish-production -- --force
+```
 
-Switch between them by changing `appId` in `public/manifest.json` before publishing.
-</dev-vs-prod>
+**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 |
 
-<environments>
-## Environments
+**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.
 
-| 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>
+**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.
 
-<checklist>
-## Checklist Before Publishing
+**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}/`.
 
-- [ ] 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>
+**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).
+
+| 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>

package/.claude/skills/hailer-ui-guide/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: hailer-ui-guide
+description: Hailer UI structure and navigation guide for AI Helper
+version: 1.0.0
+triggers:
+  - hailer ui
+  - hailer interface
+  - onboarding
+---
+
+# Hailer UI Guide
+
+Complete guide to Hailer's user interface for providing accurate navigation assistance.
+
+<layout>
+## Main Layout Structure
+
+Hailer uses a three-column layout:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Top Toolbar (mobile only)            │
+├────────┬────────────────────────────┬───────────────────┤
+│        │                            │                   │
+│  Left  │       Main Content         │     Sidenav       │
+│  Nav   │       (router-outlet)      │    (400px)        │
+│ (56px) │                            │                   │
+│        │                            │                   │
+├────────┴────────────────────────────┴───────────────────┤
+│                 Mobile Navigation (mobile only)         │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Desktop (>600px):**
+- Left sidebar: 56px vertical icon menu
+- Main content: fills remaining space
+- Right sidenav: 400px panel for activity/discussion details
+
+**Mobile (<=600px):**
+- Top toolbar visible
+- Full-screen sidenav (100vw)
+- Bottom navigation bar
+</layout>
+
+<left-nav>
+## Left Navigation Menu
+
+Vertical icon menu on the left side (always visible on desktop).
+
+**Menu items from top to bottom:**
+1. **Discussions** (icon: hailer-discussion) - Chat and team discussions
+2. **Feed** (icon: hailer-feed) - Activity feed and updates
+3. **Calendar** (icon: hailer-calendar) - Events and schedules
+4. **Activities** (icon: hailer-activity) - Workflows and kanban boards
+5. **Apps** (icon: hailer-apps) - Custom applications
+6. **People** (icon: hailer-people) - User directory
+
+**Bottom section:**
+- **Settings** (icon: hailer-settings) - Workspace settings (admins only)
+- **User profile** - Opens user menu with:
+  - Profile settings
+  - Language selection
+  - Dark/light mode toggle
+  - Logout
+
+**Navigation instruction example:**
+"Click the 'Activities' icon in the left menu (4th from top, looks like a kanban board)"
+</left-nav>
+
+<activities-section>
+## Activities Section (Workflows)
+
+When user navigates to `/activities`:
+
+**Workflow List View:**
+- Shows all available workflows as cards
+- Each card shows workflow name and icon
+- Click a workflow to open it
+
+**Workflow View (Kanban):**
+URL: `/activities/{workflowId}`
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Workflow Name                    [+ Add] [View Toggle] │
+├──────────┬──────────┬──────────┬──────────┬────────────┤
+│  Phase 1 │  Phase 2 │  Phase 3 │  Phase 4 │  Phase 5   │
+│  (New)   │ (Active) │(Review)  │ (Done)   │ (Archive)  │
+├──────────┼──────────┼──────────┼──────────┼────────────┤
+│ [Card]   │ [Card]   │ [Card]   │          │            │
+│ [Card]   │ [Card]   │          │          │            │
+│ [Card]   │          │          │          │            │
+└──────────┴──────────┴──────────┴──────────┴────────────┘
+```
+
+**View modes** (toggle in top-right):
+- **Kanban** - Cards in columns by phase (default)
+- **Table** - List view with sortable columns
+- **Calendar** - Timeline/calendar view
+- **Map** - Location-based view (if enabled)
+
+**Actions:**
+- **Create activity:** Click [+ Add] button top-right, or click empty area in phase column
+- **Open activity:** Click any card to open in sidenav
+- **Move activity:** Drag card to another phase column, OR open card and use phase selector
+- **Filter:** Use search bar or filter controls at top
+</activities-section>
+
+<activity-sidenav>
+## Activity Sidenav (Right Panel)
+
+Opens when user clicks an activity card. Width: 400px on desktop, fullscreen on mobile.
+
+**Header section:**
+- Activity name (large text)
+- Workspace badge (colored tag)
+- Workflow badge (colored tag, clickable - navigates to workflow)
+- Copy tag button (mentions activity in discussions)
+- Call button (if video calls enabled)
+
+**Tab bar** (icons below header):
+1. **Detail** (icon: hailer-activity) - Main fields and info
+2. **Participants** (icon: hailer-group) - Followers with badge count
+3. **Discussion** (icon: hailer-discussion) - Activity chat with unread badge
+4. **Files** (icon: hailer-attach) - Attachments with count badge
+5. **Location** (icon: hailer-location) - Map view (if enabled)
+6. **Linked** (icon: hailer-linked-activity) - Related activities with count
+7. **Options** (icon: hailer-settings) - Activity settings (if permitted)
+
+**Control buttons** (bottom, visible in edit/create mode):
+- **Cancel** - Discard changes
+- **Save** (with checkmark icon) - Save changes
+
+**Modes:**
+- **View mode:** Read-only display of activity
+- **Edit mode:** Fields become editable, Save/Cancel buttons appear
+- **Create mode:** Empty form for new activity
+
+**Instruction examples:**
+- "Click the 'Detail' tab (first icon) to see all fields"
+- "Click the 'Discussion' tab (chat bubble icon) to see comments"
+- "Click 'Save' in the bottom right to save your changes"
+</activity-sidenav>
+
+<phase-transitions>
+## Moving Activities Between Phases
+
+**Method 1: Drag and Drop (Kanban view)**
+"Drag the card from the '{current phase}' column and drop it in the '{target phase}' column"
+
+**Method 2: Phase Selector (in activity sidenav)**
+"Open the activity, click the phase dropdown near the top, and select '{target phase}'"
+
+**Phase order:**
+Phases are displayed left-to-right in the order defined by workflow.
+First phase = leftmost column (usually "New" or "Draft")
+Last phase = rightmost column (usually "Done" or "Archived")
+</phase-transitions>
+
+<discussions-section>
+## Discussions Section
+
+URL: `/discussions`
+
+**Discussion list:**
+- Shows all discussions user is part of
+- Unread count badges on each discussion
+- Search bar at top
+
+**Discussion view:**
+- Message list (chronological)
+- Input field at bottom
+- File attachment button
+- Emoji picker
+- @mention support
+
+**Activity discussions:**
+- Activities can have linked discussions
+- Access via "Discussion" tab in activity sidenav
+- Must "Join" discussion to see messages
+</discussions-section>
+
+<common-patterns>
+## Common UI Patterns
+
+**Buttons:**
+- Primary action: Blue filled button (e.g., "Save", "Create")
+- Secondary action: Outlined button (e.g., "Cancel")
+- Icon buttons: Small circular buttons with icons
+
+**Cards:**
+- White background (light mode) / Dark gray (dark mode)
+- Rounded corners
+- Subtle shadow
+- Click to select/open
+
+**Badges:**
+- Small colored pills showing counts or status
+- Red badge = requires attention
+- Gray badge = informational
+
+**Tooltips:**
+- Hover over icon buttons to see label
+- Useful for understanding unclear icons
+
+**Color coding:**
+- Phases have assigned colors (visible in kanban columns)
+- Workflow badges use workflow color
+- Workspace badges use workspace color
+</common-patterns>
+
+<context-to-instruction>
+## Translating Context to Instructions
+
+When you receive user context, use these patterns:
+
+**Context:** `section: 'activities', view.mode: 'kanban', view.workflowName: 'Sales'`
+**Know:** User is looking at Sales workflow kanban board
+
+**Context:** `sidenav.open: true, sidenav.type: 'activity', sidenav.activeTab: 'detail'`
+**Know:** User has an activity open and is viewing the detail tab
+
+**Context:** `sidenav.mode: 'edit', sidenav.buttons: ['save', 'cancel']`
+**Know:** User is editing an activity, Save and Cancel buttons are visible
+
+**Context:** `user.role: 'admin'`
+**Know:** User can access Settings and admin features
+
+**Instruction patterns by context:**
+
+| User location | They want to... | Say... |
+|--------------|-----------------|--------|
+| Kanban view | Create activity | "Click the '+ Add' button in the top right, or click the '+' at the bottom of any phase column" |
+| Kanban view | Open activity | "Click on the card you want to open" |
+| Activity sidenav | Edit fields | "Click the 'Edit' button (pencil icon) to enable editing, make your changes, then click 'Save'" |
+| Activity sidenav | See comments | "Click the 'Discussion' tab (speech bubble icon, 3rd from left)" |
+| Activity sidenav | Move to phase | "Click the phase badge at the top and select the new phase from the dropdown" |
+| Activity edit | Save changes | "Click the 'Save' button in the bottom right corner" |
+| Activity edit | Cancel changes | "Click 'Cancel' on the left to discard changes" |
+</context-to-instruction>
+
+<troubleshooting>
+## Common User Issues
+
+**"I can't see the workflow"**
+- Check if user has permission to the workflow
+- Admin may need to grant access in workflow settings
+
+**"I can't edit this activity"**
+- Check if user has edit permission for this phase
+- Some phases may be read-only for certain users
+
+**"I can't move the card"**
+- Phase transitions may be restricted
+- Check workflow settings for allowed transitions
+
+**"Where are my discussions?"**
+- User must be a member of the discussion
+- Check "Discussions" in left menu
+- For activity discussions, must "Join" first
+
+**"I can't see the Settings"**
+- Settings is admin-only
+- Regular users don't see this menu item
+</troubleshooting>