@hailer/mcp 1.2.1 → 2.0.0-beta.3

package/dist/public-chat/knowledge.js

@@ -0,0 +1,1339 @@
+"use strict";
+// AUTO-GENERATED from prepared-docs/HailerPublic/ — do not edit by hand.
+// Regenerate via: python3 scripts/build-public-chat-knowledge.py
+//
+// Source chunks: 62
+// Scopes: developer, legal, product
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HAILER_KNOWLEDGE_BYTES = exports.HAILER_KNOWLEDGE_CORPUS = void 0;
+exports.HAILER_KNOWLEDGE_CORPUS = `# Hailer Knowledge Base
+
+This is the curated, public-safe knowledge corpus that the public chatbot uses to answer questions about Hailer. It covers product concepts, the user interface, the MCP server, app development, and getting started.
+
+## Developer & MCP
+
+### Apps & Marketplace
+
+#### What Hailer apps are and how they relate to the MCP server
+
+Hailer apps are custom web applications that run inside Hailer workspaces. They are full frontend applications — React, Svelte, vanilla JS — that use Hailer's API for data and are embedded inside the Hailer UI.
+
+The Hailer MCP server itself does not contain apps. It provides the tools to create, manage, and publish them. Each app lives in its own project directory.
+
+The lifecycle is: Scaffold (about a minute) → Develop (locally) → Publish (to CDN) → Share (control access).
+
+This lifecycle is script-driven everywhere: scaffold with npx @hailer/create-app, develop with cd app && npm run dev, publish with cd app && npm run publish-production (add -- --market for marketplace versions). In an SDK project, register/share by editing workspace/apps.ts then running npx hailer-sdk ws-config apps push --force; otherwise share via the manage_app MCP tool. There are no MCP tools for scaffolding or publishing — the scripts are the only path.
+
+#### Scaffolding a new Hailer app with npx @hailer/create-app
+
+Scaffold a new app in one step with npx @hailer/create-app. Ask Claude Code something like 'Create a task dashboard app' and the CLI will:
+
+1. Create a Vite + React-TS project (or another template).
+2. Install @hailer/app-sdk and Chakra UI.
+3. Generate an app icon (gradient SVG).
+4. Create a dev app entry in Hailer pointing to localhost:3000.
+5. Configure CORS in vite.config.ts.
+6. Share the app with the workspace.
+7. Create a manifest.json with the assigned appId.
+8. Start the dev server.
+
+The scaffolded structure:
+\`\`\`
+my-app/
+├── public/manifest.json   # App metadata (appId, name, version)
+├── src/
+│   ├── main.tsx           # React entry point
+│   ├── App.tsx            # Main component
+│   └── ...
+├── package.json
+├── vite.config.ts         # Build config with CORS
+└── tsconfig.json
+\`\`\`
+
+The key rule: always scaffold fresh with npx @hailer/create-app to create new apps. Never copy an existing app — the scaffold tool handles app registration, icon generation, CORS config, manifest creation, and sharing in one step.
+
+#### Available app templates
+
+The scaffold (npx @hailer/create-app) supports multiple frontend stacks. Pick the one that matches the team's preferences:
+
+- react-ts (default) — React + TypeScript + Chakra UI.
+- react — React + JavaScript.
+- preact-ts — Preact + TypeScript.
+- preact — Preact + JavaScript.
+- svelte-ts — Svelte + TypeScript.
+- svelte — Svelte + JavaScript.
+- vanilla-ts — Vanilla + TypeScript.
+- vanilla — Vanilla JavaScript.
+
+React-TS is the most heavily documented and is what the design-system skill targets. Other templates work but get less first-party support around components, hooks, and example code.
+
+#### Developing a Hailer app locally and connecting to Hailer data
+
+After scaffolding, run the app locally:
+
+\`\`\`bash
+cd my-app
+npm run dev   # starts Vite on port 3000
+\`\`\`
+
+The dev app entry inside Hailer points at http://localhost:3000, so changes appear live in the workspace.
+
+Apps use the Hailer API client to fetch and modify data through the @hailer/app-sdk hook:
+
+\`\`\`typescript
+import { useHailer } from '@hailer/app-sdk';
+
+function TaskList() {
+  const hailer = useHailer();
+  const [tasks, setTasks] = useState([]);
+
+  useEffect(() => {
+    const fetch = async () => {
+      const result = await hailer.request('v3.activity.list', [
+        workflowId,
+        { phase: activePhaseId, limit: 50 },
+      ]);
+      setTasks(result.activities);
+    };
+    fetch();
+  }, []);
+
+  return <TaskTable data={tasks} />;
+}
+\`\`\`
+
+The default React-TS template also includes Hailer's Chakra UI v2 theme: brand colors, a custom icon set, pre-configured components, responsive grid patterns, and consistent typography. See the hailer-design-system skill for the full reference.
+
+#### Publishing a Hailer app with npm run publish-production
+
+When an app is ready for production, run cd app && npm run publish-production — the only publishing path. It handles:
+
+1. Runs npm run build (Vite production build).
+2. Packages dist/ together with manifest.json as a tar archive.
+3. Uploads the tar to the Hailer CDN.
+4. Creates a published app entry with an auto-generated URL.
+5. Updates the app's URL from localhost to the production CDN URL.
+
+App entries inside Hailer come in two shapes:
+
+Development app:
+\`\`\`json
+{ "name": "Task Dashboard", "description": "View and manage tasks", "url": "http://localhost:3000", "image": "<fileId>", "config": {} }
+\`\`\`
+
+Published app:
+\`\`\`json
+{ "name": "Task Dashboard", "description": "View and manage tasks", "url": "", "image": "<fileId>" }
+\`\`\`
+A published app uses an empty url, which causes Hailer to serve from the auto-generated CDN URL.
+
+#### Sharing apps with workspace members, teams, users, and groups
+
+Once an app is scaffolded or published, control who can use it with the add_app_member MCP tool. Recipients are addressed by typed identifier:
+
+- Workspace-wide: pass network_<workspaceId>.
+- Team: pass team_<teamId>.
+- User: pass user_<userId>.
+- Group: pass group_<groupId>.
+
+This matches Hailer's broader sharing model — the same id-prefix convention is used wherever you grant access. By scaffold time, the tool has already shared the dev app with the current workspace, so no manual sharing is needed for the developer's own use.
+
+#### Marketplace: templates and apps you can distribute across workspaces
+
+The marketplace lets you distribute apps and templates across workspaces.
+
+Templates are reusable workspace configurations — workflow definitions, field setups, and optionally apps. Marketplace apps are the same idea for apps. Three tools cover both:
+- browse_marketplace — list products, or get one product's details (includeManifest: true adds versions + workflows).
+- install_marketplace — deploy a template or app product to a workspace.
+- publish_marketplace — publish a template (type: 'template') or app (type: 'app') to the marketplace.
+
+Marketplace submissions must include a complete metadata bundle (title, description, version, version description, publisher, icon file ID); a publish-template guard hook enforces this before anything is sent.
+
+#### Marketplace publishing requirements and recommended skills
+
+Marketplace submissions must include the following metadata. The publish-template guard hook validates each field before submission:
+
+- title — required, max 64 characters.
+- description — required, max 4096 characters.
+- version — semantic version (for example, '1.0.0').
+- versionDescription — release notes.
+- publisher — company or person name.
+- iconFileId — 24-character file ID for the app icon.
+
+When building apps, sub-agents should load the relevant skills for context:
+
+- hailer-app-builder — React patterns, @hailer/app-sdk hooks, component patterns.
+- hailer-design-system — Chakra UI theme, colors, icons, layout, responsive design.
+- hailer-apps-pictures — fetching and displaying images stored in Hailer.
+- publish-hailer-app — full publishing workflow and manifest validation.
+- create-and-publish-app — CLI-based scaffold and publish via the @hailer/create-app npm package.
+
+### Getting Started
+
+#### Installing and running @hailer/mcp
+
+Hailer MCP is published on the public npm registry as @hailer/mcp. There are two common ways to use it:
+
+Install and run as a global CLI:
+\`\`\`bash
+npm install @hailer/mcp
+npx @hailer/mcp
+\`\`\`
+
+Or run directly with npx without a global install:
+\`\`\`bash
+npx @hailer/mcp --port 3030
+\`\`\`
+
+By default the server starts on http://localhost:3030. The default port can be overridden with the PORT environment variable or the --port flag.
+
+Before the server can talk to Hailer it needs at least one configured account. Provide a CLIENT_CONFIGS environment variable that maps an API key (used by your MCP client) to a Hailer account (used to call Hailer). One CLIENT_CONFIGS entry covers a single account; you can list more than one to support multiple accounts on the same server.
+
+#### Connecting Hailer MCP to Claude Code
+
+Once the server is running locally on http://localhost:3030 you can attach it to Claude Code with the claude CLI:
+
+\`\`\`bash
+claude mcp add hailer npx mcp-remote "http://localhost:3030/api/mcp?apiKey=your-api-key"
+\`\`\`
+
+The apiKey query parameter must match a key you defined in CLIENT_CONFIGS — the server uses it to look up which Hailer account to authenticate as.
+
+After this, Claude Code will see the Hailer MCP tools (activity, workflow, discussion, insight, app management) the next time it lists tools. Common tools include list_activities, create_activity, describe_workflows, add_discussion_message, and the SQL-style insight tools (run_insight, save_insight).
+
+If you use Claude Desktop instead of Claude Code, prefer the OAuth flow at /api/cowork/oauth/* — it logs you into your real Hailer account rather than reusing a service-account key.
+
+#### Tools you get out of the box
+
+After connecting Hailer MCP to your AI client, the available tools are grouped by domain:
+
+- Activity tools — create, read, update, list activities. Bulk operations are supported. Phase transitions go through update with the new phase ID.
+- Workflow tools — manage workflows, fields, phases, and inspect workflow schemas. These are how you discover what fields exist on a workflow before you start writing data.
+- Discussion tools — chat and messaging within activities. Read messages, send messages, join or leave discussions, invite users.
+- Insight tools — SQL-like reporting over workflow data. You can preview a query, save it as an insight, and read the results.
+- App tools — Hailer app scaffolding, publishing, sharing, and marketplace operations.
+- Workspace tools — initialize workspace data once per session, search users, manage teams and groups.
+
+Not every tool is available to every account — the tool registry filters tools by the access groups granted to the API key in use.
+
+### hailer-studio
+
+#### What Hailer Studio is — the SDK workspace experience in the cloud
+
+Hailer Studio is the cloud-hosted version of the Hailer SDK workspace-configuration experience. To understand it, start with the SDK.
+
+The Hailer SDK (@hailer/sdk on npm) lets you initialise a Hailer workspace as a code project. Instead of clicking through the website UI to create workflows, fields, and phases, you define the workspace configuration in code, then push changes with CLI commands. The workspace is shaped from code rather than from the UI — 'workspace as code', which you can version, diff, and review.
+
+Hailer Studio takes that exact experience and puts it in the cloud, so there is no local setup. When a user starts a Studio session, they get:
+- An initialised Hailer SDK project, already set up in the cloud — no npm install, no local toolchain.
+- An AI agent, already initialised, that the user talks to through Hailer's chat. The agent comes pre-loaded with instructions on how to manipulate the configuration code and run the CLI commands that push changes to the workspace.
+
+Two ways to edit your workspace configuration in Studio:
+1. The built-in code editor in the Studio frontend — edit the SDK project's configuration files directly, like an IDE in the browser.
+2. The AI agent — describe the change in chat ('add a priority dropdown to the support workflow', 'split the Done phase into Resolved and Archived'), and the agent edits the code and runs the CLI command to apply it.
+
+How Studio relates to the other surfaces:
+- vs the in-workspace Hailer Helper bot: the Helper makes runtime changes through the MCP tools (create a workflow, add a field, create activities) against a live workspace. Studio is the config-as-code path — you edit the SDK project and push, closer to how a developer evolves a system. The Helper operates inside a workspace; Studio shapes the workspace's structure as code.
+- vs the local SDK flow: Studio is the same SDK project model, just hosted in the cloud with a browser code editor and a chat-driven AI agent instead of a local terminal. A developer who prefers their own machine can still use @hailer/sdk locally; Studio is for people who want the code-based workflow without local setup.
+- vs Hailer Apps: Apps are custom React / Svelte / vanilla applications that run inside Hailer. Studio is about workspace configuration (workflows, fields, phases), not about building front-end applications. Do NOT describe Studio as an 'app builder' — that conflates it with the Apps SDK, which is a different surface.
+
+Who it is for: workspace admins and developers who want code-based, reviewable, AI-assisted control over their workspace structure — without installing the SDK toolchain locally. It suits technical users and teams who treat their workspace as something to version and evolve deliberately, rather than click together ad hoc.
+
+One-liner pitch: Hailer Studio is the Hailer SDK experience in the cloud — a code-configured workspace plus an AI agent that edits the config and runs the CLI for you, no local setup required.
+
+Graduation-flow note: the 'Continue in Hailer' pathway pre-warms a Studio session for the new user, so they can land in a ready-to-go cloud SDK project with the AI agent already initialised. This is why a visitor who graduates may encounter Studio as well as the in-workspace Helper.
+
+### MCP Server
+
+#### What the Model Context Protocol (MCP) is
+
+The Model Context Protocol (MCP) is an open standard that lets AI assistants call tools on external systems. Instead of the AI guessing or asking the user to copy-paste data, it can directly query databases, create records, and perform actions through a structured tool interface.
+
+The Hailer MCP server implements MCP over HTTP using JSON-RPC 2.0, making Hailer's full API accessible to any MCP-compatible client (Claude Code, Claude Desktop, and others). The server is an Express.js application; the main entry point is the MCPServerService class.
+
+#### MCP server endpoints and what each is for
+
+The Hailer MCP server exposes these HTTP endpoints:
+
+- /api/mcp — main MCP endpoint for direct API key access.
+- /api/cowork/mcp — MCP endpoint for OAuth-authenticated sessions (used by Claude Desktop's native connector).
+- /api/vipunen — Vipunen RAG tools (no Hailer auth required).
+- /health — health check.
+- /.well-known/oauth-authorization-server — OAuth 2.0 metadata (RFC 8414).
+- /.well-known/oauth-protected-resource — OAuth Protected Resource Metadata.
+- POST /api/cowork/oauth/register — Dynamic Client Registration (RFC 7591).
+- /api/cowork/oauth/* — OAuth flow (authorize, token, callback).
+- POST /api/cowork/auth/register — register a Hailer API key session, called by the frontend after login.
+- POST /:apiKey — alternative API key as path parameter.
+
+Most integrations only need /api/mcp (direct API key) or the OAuth endpoints under /api/cowork.
+
+#### JSON-RPC 2.0 protocol used for tool discovery and execution
+
+All MCP tool communication uses JSON-RPC 2.0. There are two main calls:
+
+Tool discovery (tools/list):
+\`\`\`json
+{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }
+\`\`\`
+The response returns an array of tools, each with a name, description, and JSON Schema for its arguments.
+
+Tool execution (tools/call):
+\`\`\`json
+{
+  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
+  "params": {
+    "name": "list_activities",
+    "arguments": { "workflowId": "<id>", "limit": 10 }
+  }
+}
+\`\`\`
+
+Responses follow MCP's content-array format:
+\`\`\`json
+{ "jsonrpc": "2.0", "id": 2, "result": { "content": [{ "type": "text", "text": "..." }] } }
+\`\`\`
+This is what every Hailer MCP tool returns.
+
+#### Authentication: direct API key, OAuth 2.0 with PKCE, pre-configured accounts
+
+The Hailer MCP server supports three authentication methods:
+
+1. Direct API key (simplest) — pass the Hailer API key as a query parameter, e.g. POST /api/mcp?apiKey=your-hailer-api-key. Used by Claude Code via the mcp-remote bridge.
+
+2. OAuth 2.0 with PKCE — for Claude Desktop and other MCP clients that support OAuth. The flow:
+  - Client discovers OAuth metadata at /.well-known/oauth-authorization-server.
+  - Client redirects the user to /api/cowork/oauth/authorize.
+  - User logs into Hailer and selects a workspace.
+  - Hailer redirects back with an authorization code.
+  - Client exchanges the code for an access_token at /api/cowork/oauth/token.
+  - Client sends the access_token in an Authorization: Bearer header.
+The real Hailer API key stays server-side in the session store; the client only ever sees a key_id.
+
+3. Pre-configured accounts (CLIENT_CONFIGS) — service accounts defined in the environment as a JSON map of API key → account credentials. This is the most common setup for development and production deployments.
+
+#### Session management: max TTL, inactivity TTL, cleanup
+
+OAuth sessions in the MCP server have two expiry rules running in parallel:
+
+- Max TTL: 24 hours absolute lifetime. After this the session is gone regardless of activity.
+- Inactivity TTL: 30 minutes; resets on each use.
+
+A session record stores: { apiKey, workspaceId, createdAt, lastAccessedAt }. A cleanup job runs every 5 minutes to remove expired sessions.
+
+This dual-TTL design means active users stay logged in for the full 24 hours but abandoned tabs lose their session quickly — which is the right trade-off for a tool with backend write access. The implementation lives in src/mcp/session-store.ts.
+
+#### User context: what every authenticated request gets
+
+Every authenticated MCP request gets a UserContext object containing the data tools need:
+
+- client: HailerClient — socket/REST connection.
+- init: full workspace data (workflows with fields and phases, all workspace users, team and group definitions, workspace metadata).
+- workspaceCache: structured lookups for fast access.
+- hailer: API call wrapper.
+- apiKey: identifier.
+- createdAt: session creation timestamp.
+- email, password: credentials for session renewal.
+- workspaceRoles: a per-workspace role map.
+- currentWorkspaceId: the active workspace.
+- allowedGroups: tool access groups for this session.
+
+The init data is fetched once via v2.core.init and cached for 15 minutes per API key, so subsequent tool calls are fast — they read from cache instead of calling Hailer again. This is implemented in src/mcp/UserContextCache.ts.
+
+#### Tool registry, tool definition pattern, and tool lifecycle
+
+The tool registry manages MCP tool lifecycle in three stages:
+
+- Registration (startup): app.ts imports allTools and registers each with Core, which passes them to the ToolRegistry.
+- Discovery (tools/list): the registry returns tool names, descriptions, and JSON schemas. Nuclear (destructive) tools are excluded unless ENABLE_NUCLEAR_TOOLS=true.
+- Execution (tools/call): the registry looks up the tool by name, validates arguments with the Zod schema, pre-transforms common LLM mistakes (e.g., converting an array into the expected object), then calls tool.execute(validatedArgs, userContext) and returns the MCP response.
+
+Every tool follows this pattern:
+\`\`\`typescript
+export const myTool: Tool = {
+  name: 'my_tool_name',
+  group: ToolGroup.READ,
+  contextType: 'hailer',
+  description: 'What this tool does',
+  schema: z.object({
+    requiredParam: z.string().describe('What this param is'),
+  }),
+  async execute(args, context: UserContext) {
+    const result = await context.hailer.request('v3.some.method', [args.requiredParam]);
+    return { content: [{ type: 'text', text: \`Result: \${JSON.stringify(result)}\` }] };
+  },
+};
+\`\`\`
+
+#### MCP server error handling and configuration
+
+The server handles errors at multiple levels: schema validation (Zod catches invalid inputs before execution), pre-transformation (fixes common LLM formatting mistakes), tool-level try/catch, response builder (standardized error formatting with isError: true), and request-logger HTTP-level error tracking.
+
+Error responses include helpful context so the AI can self-correct, for example:
+\`\`\`json
+{ "content": [{ "type": "text", "text": "Error: workflowId is required. Available workflows: ..." }], "isError": true }
+\`\`\`
+
+All server configuration flows through a single Zod-validated config: environment variables → Zod validation → ApplicationConfig instance. Key settings:
+
+- PORT — server port (default 3030).
+- NODE_ENV — environment mode (default development).
+- CLIENT_CONFIGS — required JSON map of API key → account credentials.
+- CORS_ORIGINS — allowed origins; an empty array means allow all.
+- ENABLE_NUCLEAR_TOOLS — show destructive tools (default false).
+- DISABLE_MCP_SERVER — skip server startup (default false).
+- WORKSPACE_CONFIG_PATH — path to local workspace files (optional).
+- DEV_APPS_PATH — path for scaffolded apps (optional).
+
+### rest-api-and-webhooks
+
+#### REST API surface: auth, field types, webhooks, iCal feed, and Excel import
+
+Hailer exposes a REST API for programmatic access. This chunk is the developer-archetype reference. The MCP server (covered in its own chunks) is a higher-level surface that wraps these REST calls for AI agents; this chunk is for engineers who want to call Hailer directly.
+
+API entry point:
+- Base URL: \`https://api.hailer.com/api/\` (substitute the right host for self-hosted or staging deployments).
+- Operator pattern: every endpoint is \`/api/<operator>\` where the operator is a versioned dotted name, e.g. \`v3.activity.list\`, \`v3.activity.create\`, \`v2.forms.process.get\`. The operator name lives in the URL path, not as a JSON-RPC method body.
+- Methods: GET for reads (args URL-decoded from the query string), POST for writes (JSON body). Max request body size is 20 MB.
+- API versioning: most modern endpoints are v3; some legacy endpoints are still v2. There is no v1 surface to worry about.
+
+Authentication:
+- User API keys are the primary auth for programmatic access. A workspace admin generates a key in account settings; the key is bcrypt-hashed server-side.
+- Send keys either as \`Authorization: Bearer <key>\` or as the \`hlrkey\` header — both are accepted.
+- Per-key IP whitelisting is supported: when a key has an IP whitelist set, requests from any other IP are rejected. Useful for hardening server-to-server integrations.
+- Session cookies are also accepted (the regular login session) for browser callers.
+
+Webhooks (outbound):
+- Webhooks are configured per workflow phase, not per workspace. On the workflow's phase settings, an admin sets \`webhooksEnabled: true\` and a \`webhookUrl\` (multiple URLs by regex match are supported in one phase).
+- They fire when an activity is created in that phase or moves into that phase. Hailer POSTs an activity-state payload to the configured URL(s). Failed sends are queued and retried.
+- This is the integration path most Hailer customers use today for outbound notifications and downstream automations.
+
+Field type catalog (what kinds of fields workflows can have):
+- Text: \`text\`, \`textarea\`, \`textunit\` (text with a unit suffix), \`textpredefinedoptions\` (dropdown).
+- Numbers: \`numeric\`, \`numericunit\`.
+- Time: \`date\`, \`datetime\`, \`time\`, \`daterange\`, \`timerange\`, \`datetimerange\`.
+- People: \`users\`, \`teams\`.
+- Geographic: \`country\`.
+- Cross-workflow: \`activitylink\` (reference activities in another workflow), \`linkedfrom\` (backlink — automatically populated from activitylinks pointing at this activity; valid only in the process schema, not as a user-set value).
+- Structural: \`subheader\` (groups fields visually; not user-data; valid only in the process schema).
+- Calculated: any field type above can be turned into a calculated/function field by setting \`function\` (JavaScript code) and \`functionEnabled: true\`. The function runs server-side in an isolated VM.
+
+Excel/CSV import:
+- Activity bulk-import endpoint: \`v3.activity.import\`. Hailer expects an XLSX file with workflow ID, phase ID, and column headers in specific cells (documented in Hailer's help center). The endpoint returns the count of created activities and any per-row errors. A separate bulk-user-invite Excel flow lives in workspace settings.
+
+iCal calendar feed:
+- Personal iCal subscription URL: \`https://api.hailer.com/ical/{subscribe_code}\` (subscribe code is a per-user token generated in calendar settings). Output is RFC 5545 compliant — paste the URL into Gmail/Outlook/Apple Calendar and Hailer events show up.
+
+What Hailer does NOT have (be honest):
+- No first-party GraphQL or OData. REST + webhooks is the surface.
+- No public rate-limit table; if a visitor needs a hard SLO commitment, recommend they talk to the Hailer team.
+- No Postman collection shipped publicly; describe operators by name and point at the help center.
+- Zapier integration exists, but it's a Zapier-side app that calls this REST API — not a separate backend feature inside hailer-api.
+
+## Legal & Privacy
+
+### demo-chat-privacy
+
+#### What happens to your demo conversation
+
+If a visitor asks 'where does this chat go?', 'is this conversation kept?', 'do you train on this?', or anything in that family — the answer is in this section. This is a plain-English summary of the demo-chat handling, in addition to (not instead of) Hailer's formal Privacy Policy.
+
+The demo chat on the Hailer login page:
+- Is anonymous. We do not collect the visitor's name, email, or contact info during the chat. There is no signup gate to begin chatting.
+- Is stored server-side under an anonymous session ID generated in the browser. This session ID is the only identifier tied to the conversation; the visitor can clear it by clearing their browser's localStorage.
+- Is used in one of two ways: (a) to let the bot answer follow-up questions in the same conversation, and (b) if the visitor clicks 'Continue in Hailer' and creates a Hailer workspace, to give the new Hailer Helper bot in that workspace context about what was discussed (the 'seed context'). Without 'Continue in Hailer', the chat is never linked to a Hailer account.
+- Is sent to Anthropic's Claude API in order to generate the bot's replies. Anthropic processes the conversation under their published data-use terms; Anthropic does not train on API content by default.
+- Is not used to train Hailer's own models. We do not have first-party AI models — the chat is processed by Anthropic for replies and stored locally for handoff. We do not sell or share the conversation contents with third parties.
+- Has a server-side retention limit. The in-memory store the demo uses is cleared when the server restarts; a longer-lived store, if introduced later, will retain conversations for a short window (3 days planned) before purging.
+
+If the visitor wants their demo chat deleted before retention expires, or wants a copy of the data, they can contact privacy@hailer.com with the session ID (visible in the browser's localStorage as \`hailerPublicChatSessionId\`).
+
+### Privacy Policy
+
+#### Privacy Policy overview, data controller, and structure
+
+Hailer's Privacy Policy covers what information Hailer collects when you use the products or services or otherwise interact with the company (for example by attending events or communicating with Hailer staff), unless a different policy is displayed.
+
+Data controller: Hailer Oy, business ID 2772571-4, Rihkamatori 2, Porvoo, Finland. All inquiries regarding the Privacy Policy should be directed to privacy@hailer.com.
+
+If you do not agree with the policy, you should not access or use Hailer services or interact with any other aspect of the business.
+
+The policy is split into two sections: (1) how the Hailer Application collects and processes your data, and (2) how the Hailer website and social-media channels collect and process your data. The full policy is published at https://app.hailer.com/#/privacy-policy.
+
+#### Hailer Application — what data is collected
+
+Section 1 of the Privacy Policy covers the Hailer Application, which means any of: (1) the web client at app.hailer.com, (2) the Hailer Android app, (3) the Hailer iOS app, and (4) Hailer API users.
+
+What data is collected:
+
+- To use the service and identify the user, certain data has to be collected for the service to be functional. This data includes (but is not limited to) email address, full name, and any other data inserted into the application.
+- Payment and billing information is collected when you register for certain paid services — for example, payment card details, which are collected via secure payment processing services.
+- Some information is collected automatically, including (but not limited to) the type of mobile device you use, your mobile device's unique device ID, the IP address of your mobile device, your mobile operating system, the type of mobile internet browser you use, and information about how you use the Application.
+
+#### Hailer Application — how the data is used; end-user note
+
+How Hailer uses the data it collects (Application section):
+
+Hailer uses data and collective learnings (including feedback) about how people use the application to troubleshoot, identify trends, usage and activity patterns, find areas for integration and product improvement, and develop new products, features, and technologies that benefit users.
+
+Important note for end users of organization workspaces:
+
+Many Hailer products are intended for use by organizations. When the services are made available to you through an organization (for example, your employer), that organization is the administrator of the workspace and is responsible for it. In these cases, direct your data-privacy questions to your administrator — your use of the services is subject to that organization's policies. Hailer is not responsible for the privacy or security practices of an administrator's organization, which may differ from Hailer's policy.
+
+#### Hailer subprocessors — infrastructure and third-party services
+
+Hailer uses Amazon Web Services (AWS) infrastructure for providing the Hailer cloud service. The server infrastructure is located in the EU and AWS is committed to handle all data traffic compliant with EU data protection legislation (see the AWS GDPR DPA at https://d1.awsstatic.com/legal/aws-gdpr/AWS_GDPR_DPA.pdf).
+
+Data residency specifics: all Hailer infrastructure runs in the AWS eu-west-1 region, located in Ireland. The MongoDB database is hosted in the same region. Every workspace's data resides there — there is currently no option to choose a different region or to pin a workspace to another location. So data residency is EU (Ireland) for all customers by default, but customer-selectable region / data residency is not offered today.
+
+Full list of Hailer subprocessors:
+
+- Amazon Web Services (AWS) — server infrastructure; all Hailer data.
+- MongoDB Atlas (MongoDB Inc.) — databases; all Hailer data.
+- Mailgun (Mailgun Technologies, Inc.) — sending email from Hailer; email address, name, password reset and invitation links.
+- Splunk (Splunk Inc.) — server log management; infrastructure logs.
+- Apple Push Notification Service / APN (Apple) — sending push notifications; push notification content and metadata to Apple devices.
+- Firebase Cloud Messaging / FCM (Alphabet Inc.) — sending web push notifications; push notification metadata and content to web clients.
+- Stripe — online payments; client payment information.
+- Creamailer (Creamailer Oy) — newsletters; email address and name.
+
+#### Hailer website and social media — data collection and use
+
+Section 2 of the Privacy Policy covers Hailer's website and social-media channels.
+
+What data is collected:
+
+Hailer collects information you input into the website, social-media accounts, or provide directly through other communications. Website visitors are the primary source of personal, company, and technical information — including registration data, contact information, and anything else provided through Hailer's digital assets. Some information also comes from third-party platforms (advertising platforms, content on third-party sites, social networks).
+
+How the data is used:
+
+Processing is based on Hailer's legitimate interest to ensure the functionality and security of the website and to provide information and services to data subjects visiting Hailer's digital assets. Personal data is also processed to develop and customize the website content for people interested in Hailer's products and services.
+
+Contact details collected through web forms include: name, email address, telephone number, interest in the system, and the company you work for.
+
+#### Your rights, data disclosure cases, and policy changes
+
+Disclosure of user information may happen in these specific cases:
+
+- As required by law (for example, to comply with a subpoena or similar legal process).
+- When Hailer believes in good faith that disclosure is necessary to protect its rights, protect your safety or the safety of others, investigate fraud, or respond to a government request.
+- With trusted service providers acting on Hailer's behalf. These providers don't have independent use of the information and have agreed to follow the rules in the privacy statement.
+- If Hailer is involved in a merger, acquisition, or sale of all or part of its assets, users will be notified by email and/or a prominent notice on the website about ownership changes or new uses of the information, and any choices users have.
+
+Your rights:
+
+You have the right to request a copy of your information, object to its use (including for marketing), request deletion or restriction of your data, or request your information in a structured electronic format. Submit requests to privacy@hailer.com.
+
+Hailer may decline requests that are unreasonably repetitive, systematic, technically disproportionate, conflict with others' privacy, are extremely impractical, or where access is not legally required. Some data may be retained as needed to comply with legal obligations, resolve disputes, or in backups. For website-form data you can opt out manually at any time.
+
+Policy changes:
+
+Hailer can update the privacy policy when the methods or purposes of processing change. New versions are posted on the privacy-policy page and users are informed by email.
+
+## Product & UI
+
+### customer-stories
+
+#### Customer story — Viestintä Ruuti (communications agency, Lahti, Finland)
+
+Viestintä Ruuti Oy is a content-marketing and communications agency in Lahti, Finland. The story below is summarised from the published customer reference at hailerreferences.com/tarinat/viestinta-ruuti.html (Finnish-language original; quotes translated). Use it when a visitor's situation resembles theirs.
+
+The company:
+- Founded by CEO Riina Kruut.
+- Grew from a one-person operation to a five-person core team plus a freelancer network over roughly five years.
+- Services include social-media management, expert branding, training, and strategic communications planning.
+- Multi-client agency model — each client comes with its own scope, billing structure, and stakeholders.
+
+The pain before Hailer:
+- Client information was scattered across Excel spreadsheets, PowerPoint slides, Word documents, and sticky notes.
+- Hour tracking was difficult because each client had its own billing structure — different rates, different recurring/one-off arrangements, different reporting expectations.
+- As the team grew from one person to five, the founder could no longer hold all the client context in her head, and the existing tools didn't give her a clean way to verify what work had been done before invoicing.
+- Quote (translated): 'Various client relationships and billing structures caused challenges in keeping up with hour tracking.'
+
+How they use Hailer today:
+- One central place for all client data — contact details, billing arrangements, account credentials, project notes.
+- Hour and project tracking — team members log hours per client and project monthly; the founder can verify exactly what work was done before sending invoices.
+- Internal communication tied to the work — conversation threads attach to the relevant client or project record, alongside notes, billing changes, and responsibility assignments.
+- Project documentation lives on the record, so the founder no longer has to chase teammates for status updates.
+
+Concrete outcomes:
+- Visibility she trusts: 'If I didn't have clarity on who worked where and how much, I couldn't manage billing responsibly.' Hailer gave her that clarity.
+- Less management overhead — instead of asking team members what they did, the founder can see the logs and confirm work was done.
+- Cleaner billing — the agency and its clients both benefit from documented deliverables and hours, reducing back-and-forth at invoicing time.
+- Scalability foundation — growing from one person to five with multiple complex billing structures only worked because client info, hours, and conversations all lived in one place.
+- Quote (translated): 'All client-related matters are always found in one place.'
+
+When this story is the right one to reach for:
+- Visitor is running an agency, consultancy, or any client-services business with multiple clients and per-client billing variation.
+- Visitor mentions time tracking, hour logs, billing accuracy, or invoicing as a pain.
+- Visitor describes information scattered across spreadsheets, slide decks, docs, sticky notes, or email threads.
+- Visitor is at the 'I can't hold it all in my head anymore' moment — typically 3–10 people, growing.
+- Visitor mentions freelancers or contractors alongside core team — the agency context resonates.
+
+How to use it in the chat:
+- Don't read the case study back as a brochure. Pull the one or two threads that match what the visitor just told you and connect those to their situation.
+- Lead with the pain the visitor named ('scattered info', 'never sure what was actually done before billing'), then mention that a Finnish agency hit the same wall growing from one person to five, and tell them what Hailer changed for that agency.
+- Reference is publicly published, so naming Viestintä Ruuti and Riina Kruut is fine. Don't fabricate detail beyond what's in this chunk — the original story is short, and embellishment is the fastest way to lose credibility.
+- If a visitor asks for more customer stories from other industries, be honest: this is the one with a published reference today; more are coming.
+
+### demo-apps-page
+
+#### What the demo's Apps page shows — and what's real vs. illustrative
+
+The interactive Hailer demo at /demo has an Apps page (reached via the left nav 'Apps' button). It mocks the Hailer apps surface — two sections, 'Installed' and 'Marketplace' — with six tiles. The tiles are visually rich and clickable, but the demo is read-only and the page is a mock-up, NOT a real apps catalogue. Some tiles correspond to real Hailer surfaces; others are illustrative examples invented to make the marketplace concept tangible.
+
+When a visitor asks 'what does X do?' for one of these tiles, answer honestly using the table below. Do NOT promise that the illustrative ones ship today.
+
+Installed tiles:
+- AI Hub — REAL. Hailer ships an AI Hub surface in every workspace for managing AI agents (bots), their system prompts, the people they can talk to, and token usage. The in-workspace Hailer Helper bot is one such agent. After 'Continue in Hailer' the visitor can find AI Hub in their real workspace.
+- Document Templates — REAL feature, packaged as an app for demo clarity. Hailer's PDF/document generator turns activity data into offers, invoices, certificates, and other structured documents using the same function-field engine that powers calculated fields. The 'Document Templates' name is the demo's framing; in production this lives inside the workspace's template configuration rather than as a standalone marketplace app.
+
+Marketplace tiles (all ILLUSTRATIVE — none of these ship as named apps today, but each represents a pattern Hailer supports):
+- Customer Portal — ILLUSTRATIVE. Hailer does support public web forms that create activities in a workflow (the publicForm feature). Branding it as a 'Customer Portal' app is the demo's shorthand for that capability.
+- Equipment Inventory — ILLUSTRATIVE. Represents the dataset pattern (a single-phase or Active/Archived workflow used as a reference list). A user could build this themselves; it's not a one-click install.
+- Slack Bridge — ILLUSTRATIVE. Hailer's first-party Slack story is the Zapier integration (Zapier triggers Slack messages from Hailer events). There is no purpose-built 'Slack Bridge' app today.
+- Stripe Receipts — ILLUSTRATIVE. Combines automation (phase-change triggers) and document generation patterns Hailer does support, but there's no shipping Stripe-specific app.
+
+How to answer typical questions:
+- 'Can I install Slack Bridge?' — 'That tile is illustrative. Hailer's Slack story today is the Zapier integration, which can post Slack messages from Hailer events.'
+- 'What's AI Hub?' — 'AI Hub is the real surface where you manage your workspace's AI agents — including the Hailer Helper bot that gets provisioned when you Continue in Hailer.'
+- 'Can I build my own apps like these?' — 'Yes. Apps are built with the Hailer Apps SDK (React, Svelte, vanilla, etc.) or scaffolded by an AI agent via the @hailer/mcp tools. The marketplace lets you publish them to other workspaces.'
+- 'How do I get an app for my [specific use case]?' — Recommend the route honestly: 'For something custom, scaffold a Hailer App with the SDK or ask the in-workspace Helper to scaffold one. For a configuration-only solution (workflow + fields + a function field generating documents), describe it to the in-workspace Helper after you Continue in Hailer.'
+
+Key rule: if the visitor seems to assume these are all shippable apps they can install today, gently correct that — Hailer apps are mostly something teams build (or commission), not a fully populated marketplace. The deck's Apps & Studio slide ('apps-studio' slide id) explains this in the broader story.
+
+### Frequently Asked Questions
+
+#### Trial, integrations, and data import/export
+
+Frequently asked questions from the Hailer help site:
+
+Can I test Hailer for free?
+Yes. Every new Hailer workspace starts with full Hailer functionality and a starter AI token grant for trying the AI features. Token consumption applies only to AI-driven operations — chats with the in-workspace Hailer Helper, AI Hub bots, and MCP-driven AI sessions. Creating activities, using kanban, the calendar, discussions, and everything else in the regular Hailer UI does not consume from this budget. When the AI token balance runs low, the workspace owner can top up via the billing area. For the current grant size and rough estimates of what it covers, see the 'How Hailer's free AI token grant works' chunk — that chunk is the single source of truth for the grant figure; do not quote a number from this FAQ.
+
+What integrations does Hailer have?
+Hailer currently offers a Zapier integration and a REST API. Through a Zapier workflow you can create a new Hailer activity or update an existing one, create a new calendar event, upload files, or create a new wall post on the feed.
+
+Can I import data from old systems to Hailer? What about export?
+Yes. You can do an Excel import in a few minutes, or export your data out the same way.
+
+#### Calendar sync, custom workflows, and public forms
+
+More frequently asked questions from the Hailer help site:
+
+Can I sync Hailer events to Gmail or another calendar?
+Yes. You can sync Hailer events to your Gmail or Office account using an iCal link.
+
+Can I create a custom workflow for my business?
+Yes. You can create any type of workflow or process in Hailer. A few ready-made templates are available, and if none fit your needs you can easily build a custom workflow from scratch.
+
+I want to collect data from external persons — is that possible?
+Yes. Workspace admins can enable a public form on any workflow or dataset. This produces a web form whose link you can embed in a webpage or share wherever you need to gather data from people outside the workspace.
+
+### free-tier-tokens
+
+#### How Hailer's free AI token grant works
+
+MAINTAINER NOTE — this chunk is the single source of truth for the AI token grant figure. The faq.json and graduation.json chunks deliberately do NOT quote the number; they cross-reference here. When the backend changes the grant, update ONLY this chunk and the corpus stays coherent.
+
+Every new Hailer workspace gets an AI token grant at signup. The current grant is 1500 tokens — this number is set on Hailer's backend and may change in the future, so always describe it as 'the current signup grant' rather than a permanent figure.
+
+What tokens are spent on:
+- Conversations with the in-workspace Hailer Helper bot.
+- AI Hub bots running on behalf of the workspace.
+- MCP-driven AI sessions (e.g. Claude Code connected to the workspace).
+- Function-field execution — calculated fields run sandboxed JavaScript, and each execution draws from the same token bucket. Function fields evaluated at scale (long lists, frequent re-calculation, heavy data) can therefore consume meaningful tokens on their own.
+
+What does NOT spend tokens:
+- Creating, updating, or moving activities through the regular Hailer UI.
+- Sending discussion messages to other humans.
+- Calendar entries, feed posts, file uploads.
+- Reading existing activity data that doesn't trigger a function-field recompute.
+
+How the meter works:
+- Tokens are 'output-normalized' — Hailer converts every kind of AI usage to an equivalent number of model-output tokens before deducting. The default underlying model is Claude Haiku 4.5.
+- A typical single bot turn (the user asks something, the bot reads context and replies) costs roughly 500 to 1000 normalized tokens depending on how long the user's question and the bot's reply are. A modest reply costs around 700 tokens.
+- Turns that involve tool use (the bot creating a workflow, adding fields, creating activities, fetching data) can cost more per turn because the bot does more work inside one response.
+
+What 1500 tokens covers, roughly, at the current rate:
+- About two substantive back-and-forth chats with the Hailer Helper. Enough for a 'set up my workspace' conversation or a couple of follow-up questions.
+- Or one moderately complex workflow-creation request that involves multiple tool calls in a single turn.
+- Or a handful of short prompts like 'add an activity for Acme Deal' if the bot's replies stay brief.
+
+These estimates are approximate and depend heavily on prompt length, model choice, and how much tool use the bot does. A workspace running heavier AI features (Sonnet instead of Haiku, very long prompts, deep multi-turn tool chains) will burn through 1500 tokens faster.
+
+When the balance runs low:
+- Below 100 tokens, the system flags the workspace as 'LOW'. The bot continues to respond and function fields continue to run.
+- At zero or negative, two things pause: (a) AI features stop generating responses (Helper bot, AI Hub bots, MCP-driven AI sessions) and (b) function-field execution halts — calculated fields stop recomputing until the workspace tops up.
+- The rest of manual Hailer use keeps working — creating and moving activities through the UI, posting discussion messages to other humans, calendar entries, feed posts, file uploads. Only AI features and function-field execution are gated by the token balance.
+
+To top up, the workspace owner uses the billing area of Hailer. Top-ups work on an on-use / pay-as-you-go basis — purchase additional tokens as needed rather than committing to a fixed monthly bucket. The 1500-token grant is a starter allotment, not a permanent free quota.
+
+### graduation
+
+#### What the 'Continue in Hailer' button does
+
+On the Hailer login page, the 'Continue in Hailer' button (also shown as 'I've verified — finish setup' after a fresh signup confirms their email) signs the visitor up for a free Hailer workspace and provisions a Hailer Helper bot inside it before the user even lands in Hailer.
+
+The flow:
+1. The visitor clicks 'Continue in Hailer'.
+2. They sign up (or sign in if returning) and confirm their email.
+3. A free workspace is created for them — full Hailer functionality, plus the standard signup AI token grant for trying out the AI features. See the 'How Hailer's free AI token grant works' chunk for the current grant figure; that chunk is the single source of truth — do not quote a number from here.
+4. An 'Agent Directory' workflow is installed in that workspace if it isn't already.
+5. A bot activity is created in the Deployed phase — this becomes the workspace's Hailer Helper.
+6. The bot's Hailer account is auto-provisioned with admin permissions in the workspace.
+7. The conversation the visitor had with the demo bot on the login page is carried forward as context — the new Helper's first message references what they discussed.
+8. The visitor lands directly inside the Helper's discussion in Hailer, with the welcome message already posted.
+
+The whole flow typically completes in a few seconds. The visitor never has to paste an API key or configure anything — the authorize step is one click. The Helper's first replies will use a small portion of the workspace's AI token grant; see 'How Hailer's free AI token grant works' for the math.
+
+#### What the post-signup Hailer Helper bot does in a workspace
+
+The Hailer Helper bot that gets provisioned by the 'Continue in Hailer' flow is the user's starter assistant in their brand-new workspace. It has admin-level permissions and inherits the demo conversation as context.
+
+What it can do today:
+- Read and understand the workspace's structure (workflows, phases, fields, teams, users) using the standard Hailer MCP toolset.
+- Create workflows tailored to what the user described in the demo chat — sales pipelines, project trackers, support queues, recruiting funnels, anything the conversation pointed at.
+- Add and modify fields and phases on existing workflows.
+- Invite team members to the workspace (admin permission allows this).
+- Create activities, follow discussions, and post messages.
+- Answer follow-up questions about Hailer using the same knowledge base the demo bot used, but now grounded in the user's real workspace state.
+- Build dashboards (insights) using Hailer's SQL-based query layer.
+
+What it does NOT do (don't promise these):
+- Write production code outside Hailer.
+- Integrate third-party services (Salesforce, HubSpot, etc.) on its own — those are separate Hailer integrations the user sets up via Zapier or the REST API.
+- Replace a human developer building custom Hailer Apps with the SDK.
+- Operate independently in the background — it responds to messages in its own discussion, not autonomously.
+
+The bot is a separate Hailer user account in the workspace; the visitor can chat with it, rename it, or disable it from AI Hub at any time.
+
+#### Continuity between the demo chat and the post-signup workspace
+
+When a visitor clicks 'Continue in Hailer', the conversation they had on the login page does not disappear — it carries forward as seed context for the bot that greets them in their new workspace.
+
+How continuity works:
+- The demo chat stores each user message and bot reply server-side under a session ID that the demo page generates and keeps in the browser.
+- That session ID is included in the authorize popup URL when the visitor clicks 'Continue in Hailer'.
+- When the workspace is provisioned, the demo turns are passed to the new Hailer Helper bot as \`seedContext\` — a structured record of the conversation.
+- The new bot's first message in its own discussion references what the visitor talked about ('I see you were thinking about a sales pipeline for your team — here's what I'd suggest').
+- Without seed context (e.g., a visitor signs up without chatting first, or the server restarted and lost the in-memory store), the new bot falls back to a generic introduction. The workspace and Hailer Helper still work; only the personalised opener differs.
+
+What the visitor sees:
+- The same conversation thread does NOT continue verbatim in the new workspace — it's a fresh discussion with a separate bot, but that bot already knows the context. Think of it as the demo bot briefing the workspace bot before handing the visitor over.
+- More demo turns before clicking 'Continue in Hailer' = a more specific, personalised welcome in the workspace. Four to eight back-and-forth turns is the sweet spot.
+
+### helper-capabilities
+
+#### Hailer Helper bot capabilities — the in-workspace toolset
+
+After a visitor clicks 'Continue in Hailer' and lands in their new workspace, the in-workspace Hailer Helper bot has access to a rich set of tools backed by the Hailer MCP server. The bot is a workspace admin, so its permissions cover everything in this list inside the visitor's workspace. This is what the bot can actually do once the visitor is in Hailer.
+
+Workflow and dataset setup:
+- List existing workflows and datasets in the workspace and read their schemas (fields, phases, permissions).
+- Install new workflows from templates or scratch — sales pipelines, project trackers, support queues, recruiting funnels, anything with a lifecycle of stages.
+- Install datasets for reference data — customer lists, product catalogs, equipment registers, vendor lists. Datasets are modelled as workflows with a single phase (or two, like Active/Archived) so items live in categories rather than moving through stages.
+- The Helper should pick the right shape (workflow vs dataset) based on the use case: lifecycle → workflow, reference list → dataset. When the user's intent is ambiguous, the Helper should ask once before building rather than default to a multi-phase workflow.
+- Create and update fields on a workflow or dataset (text, dropdown, date, calculated/function fields, file fields, user fields, etc.).
+- Create and update phases on a workflow, including transitions between them.
+- Grant or revoke per-workflow permissions for users and teams.
+- Remove workflows or datasets when they're no longer needed.
+
+Activities (the work records inside workflows):
+- Create activities in any workflow, with field values populated from a description.
+- List, search, count, and show activity details.
+- Update activity fields and move activities between phases.
+- Read an activity's linked discussion to follow the conversation context.
+
+Discussions and messaging:
+- List the bot's own discussions.
+- Fetch messages from a discussion (recent and historical).
+- Post messages into a discussion.
+- Invite users into a discussion or join/leave existing ones.
+- Look up which activity is linked to a given discussion.
+
+Calendar and events:
+- List the workspace's calendars and their upcoming events.
+- Create new calendar events.
+
+Files:
+- Upload files to the workspace.
+- Download existing files.
+
+Reporting and insights:
+- List existing insights (saved SQL queries) and run them to fetch data.
+- Create new SQL-based insights to summarise and aggregate workflow data.
+- Update or remove existing insights.
+- Preview an insight before saving it.
+
+Users, teams, and permissions:
+- Search the workspace's users.
+- Set a user's role (admin, user) in the workspace.
+- Check a specific user's permissions on a workflow.
+
+Hailer Apps (custom React applications inside Hailer):
+- Scaffold a brand-new Hailer app project (React + Vite) and configure it.
+- Publish an existing app so other users can install it.
+- List installed apps and read their manifests.
+- Add or remove members from an app's allowlist.
+- Install marketplace apps and templates published by others.
+
+Templates and the marketplace:
+- List, get, install, create, and publish workflow templates so configurations can be reused or shared across workspaces.
+
+Self-management:
+- Read and update its own system prompt (so the visitor can personalise how the Helper behaves).
+- Set its own profile picture.
+- Check the workspace's AI token balance.
+
+Utilities:
+- Resolve relative dates ('next Friday', 'end of quarter') into concrete timestamps.
+
+What the Helper cannot do:
+- Run code in the visitor's local environment, terminal, or developer tools — that's the Hailer Studio surface, not the workspace Helper.
+- Talk to third-party services (Salesforce, HubSpot, Slack, etc.) on its own. The user can wire those up via Zapier or the REST API, but the Helper doesn't have those credentials.
+- Send email or SMS from the workspace's domain.
+- Modify another workspace it isn't a member of.
+- Replace a human developer building a fully custom Hailer App with the SDK — it can scaffold and publish apps, but production-quality app code typically needs a developer.
+
+The overall pattern: anything that lives inside a Hailer workspace's data model — workflows, activities, fields, phases, discussions, files, calendars, insights, apps, templates, user roles — the Helper can read, create, and modify on the visitor's behalf. Anything that crosses the boundary into the outside world (third-party APIs, the visitor's own machine, email systems) is outside its toolset.
+
+Proactive setup offer on first contact:
+- The Helper's very first message in its discussion scans the demo conversation for concrete workspace-setup intent (a process the user described, records they want to manage, fields they need, stages an item moves through).
+- If the demo gave enough detail to start building, the Helper offers to set it up immediately — naming the phases or dataset shape, naming the key fields — and asks 'want me to go ahead?' rather than building unilaterally.
+- If the demo is too vague to act on, the Helper asks one or two specific clarifying questions instead of generic 'what do you want to track?' prompts.
+- This proactive offer only fires on the first message, when the seed context is fresh. Subsequent turns behave normally.
+
+### mobile-and-localization
+
+#### Mobile apps, push notifications, video calls, and supported languages
+
+Hailer ships native iOS and Android apps (built on Capacitor, packaging the same Hailer web UI) alongside the web app. Anything below is shipping; don't promise features that aren't listed.
+
+Mobile apps:
+- iOS and Android both have native apps. They share the web UI under the hood, so feature parity is high — workflows, kanban, activities, discussions, calendar, feed, settings all work.
+- Native push notifications: the apps receive push for incoming discussion messages, mentions, and ball-passing events (when an activity moves to a user). Notification taps deep-link into the relevant discussion or activity.
+- Video calls: the apps handle incoming Hailer video calls natively with accept/decline actions on the lock screen and from notifications. The video call surface is wired into the discussion thread it belongs to.
+- Workspace admins can require biometric unlock on every launch (Force local auth — see the SSO and admin controls chunk).
+
+Offline support:
+- The apps work online primarily; substantial offline editing isn't a documented feature. If a visitor explicitly asks about offline-first usage, say honestly that Hailer is online-first and recommend they reach out to Hailer if offline support is critical.
+
+Languages:
+- The Hailer UI ships in English, Finnish, and Swedish. Visitors will see their browser's language by default if it's one of the three; otherwise English. There's no per-workspace language pin — each user sees their own preference, set in their account.
+- Activity content (the things users create — workflow names, field labels, discussion messages) is whatever the user typed; Hailer doesn't translate user content.
+- If a visitor asks about other languages (German, French, Spanish), be honest: only en/fi/sv are supported today.
+
+Notifications model overview (not exhaustive):
+- Native push (iOS/Android apps) — the primary channel for time-sensitive events.
+- In-app notifications — visible inside the Hailer UI on web and mobile.
+- Email — used for invites, password resets, and certain admin-configured workflow events; granular per-user email controls aren't a documented public feature beyond standard unsubscribe.
+- If a visitor asks 'will this spam me?', the honest answer is: push and in-app notifications follow the events that involve them (mentions, balls passed, etc.); email is used sparingly for transactional things.
+
+Tone guidance: don't oversell offline. Don't promise translations beyond en/fi/sv. Don't claim email-frequency settings exist unless the visitor mentions them — if they do, recommend they ask the Hailer team directly.
+
+### Overview
+
+#### What Hailer MCP is and what it does
+
+Hailer MCP Server (@hailer/mcp) is a Node.js application that bridges AI assistants with Hailer — a workspace and CRM platform for managing workflows, activities, teams, and apps. It implements the Model Context Protocol (MCP), an open standard that lets AI models (Claude, ChatGPT) call tools on external systems. Think of it as a universal adapter: an AI assistant asks 'list all activities in the Sales pipeline', and the server translates that into the right Hailer API calls and returns structured results.
+
+The server exposes 71 tools to any MCP-compatible AI client. Tools cover everything you can do in Hailer: create activities, manage workflows, query data, build apps, and control permissions. The flow is: AI client → HTTP → MCP Server → Socket/REST → Hailer API.
+
+#### MCP Server, Bot Client, and Plugin System capabilities
+
+Hailer MCP provides three things:
+
+1. MCP Server (Primary) — An HTTP server that exposes 71 tools to any MCP-compatible AI client. Tools cover the full surface of Hailer: creating activities, managing workflows, querying data, building apps, and controlling permissions.
+
+2. Bot Client (Optional) — Automated AI agents that live inside Hailer discussions. When someone @mentions the bot, it reads the conversation, uses the same 71 tools to gather context, and responds with AI-generated answers.
+
+3. Plugin System — Extensible architecture for additional capabilities. Currently includes Vipunen, a Weaviate-based RAG (Retrieval-Augmented Generation) plugin for semantic search over documentation.
+
+#### Hailer ecosystem core concepts: workflows, activities, phases, fields
+
+To understand Hailer you need to know its key concepts. A Workspace contains everything else:
+
+- Workflows — like database tables: 'Projects', 'Tasks', 'Invoices'.
+  - Fields — columns on a workflow: 'Title', 'Due Date', 'Assignee'.
+  - Phases — stages an activity moves through: 'New' → 'In Progress' → 'Done'.
+  - Activities — rows in the workflow: individual records or items.
+- Discussions — chat threads, can be attached to activities.
+- Teams & Groups — organizational units used for permissions.
+- Apps — custom web applications embedded in Hailer.
+- Insights — SQL-like queries for reporting.
+- Users — workspace members with roles.
+
+Definitions:
+- Workflow = a structured process (like a Kanban board or database table).
+- Activity = a single item in a workflow (like a task, project, or invoice).
+- Phase = a stage in the workflow lifecycle (like 'Draft' → 'Review' → 'Published').
+- Field = a data point on an activity (like 'Title', 'Due Date', 'Assigned To').
+
+#### Hailer MCP technology stack and package
+
+Hailer MCP is built with these technologies:
+
+- Language: TypeScript 5 (strict mode) for type-safe server code
+- Runtime: Node.js 20
+- HTTP: Express.js
+- Protocol: JSON-RPC 2.0 over Server-Sent Events (SSE) for MCP communication
+- Validation: Zod for input schema validation
+- Hailer API: @hailer/cli (socket.io) for backend communication
+- AI: Anthropic Claude SDK and OpenAI SDK for the bot client
+- RAG: Weaviate for vector search via the Vipunen plugin
+- Build: TypeScript compiler (tsc)
+- Deploy: Docker (multi-platform images)
+
+The package is published to the public npm registry as @hailer/mcp. Install or run it with:
+
+npx @hailer/mcp --port 3030
+
+It also installs as a global CLI command 'hailer-mcp'.
+
+### overview-presentation
+
+#### The Hailer overview presentation — what the in-demo slide deck covers
+
+The Hailer demo page (the interactive mock workspace at /demo) ships with a spatial slide presentation that introduces Hailer's story. It opens as a fullscreen overlay above the mock UI — launched by clicking the 'Tour' button in the top-right of the demo topbar, or by the bot emitting a <bot-action type="presentation" target="open" /> tag. ESC closes it; arrow keys / Space / PgUp / PgDn step through slides; mouse wheel zooms; click-drag pans; 0–9 jumps to a percentage of the deck.
+
+The deck has 15 slides arranged in three rows on a Prezi-style canvas — the camera flies between them. It is NOT the interactive demo (clickable kanban, table, discussions, etc.). The presentation is a narrative; the demo is a sandbox. Offer the presentation when the visitor wants the conceptual map; offer the demo tour (navigate + point chain) when they want to see the product in use.
+
+Slides — each line is \`slide-id — title — what it covers\`. Bot can reference any slide inline via <bot-action type="slide" target="{slide-id}" />, which renders a clickable chip in the chat that opens the deck on that exact slide:
+- \`title\` — 'Hailer / Where work flows' — the opening cover.
+- \`what\` — Hailer is a workspace platform for structured work + team chat in one.
+- \`problem\` — Trackers and chat live apart; context dies in translation.
+- \`core-label\` — section divider: Core concepts.
+- \`workspaces\` — Multi-tenant homes; SSO; per-workspace AI agents.
+- \`workflows\` — Phases, fields, automations, permissions — the configurable process.
+- \`activities\` — Work items moving through phases; ball tracking; audit history.
+- \`discussions\` — Built-in chat per activity; real-time; bots and AI participants.
+- \`build-label\` — section divider: Build & extend.
+- \`apps-studio\` — Hailer Studio (cloud SDK editor for workspace config, with an AI agent) + apps marketplace. (Studio shapes workspace configuration as code; it is NOT an app builder — the Apps SDK and marketplace cover app-building. See the hailer-studio chunk.)
+- \`sdk\` — Workspace config as code; @hailer/sdk on npm.
+- \`sdk-code\` — TypeScript workflow definition example (fields + phases + automation).
+- \`mcp\` — Model Context Protocol surface; @hailer/mcp on npm.
+- \`insights\` — Saved chart/table queries + phase-change automations.
+- \`closer\` — One platform: system of record + team chat under one roof.
+
+When to recommend the presentation: visitor asks 'what is Hailer?', 'show me the overview', 'the elevator pitch', 'give me the slides', 'I want to understand the whole thing'. Don't open it on detail questions ('how do permissions work?', 'is there a free trial?') — those get a direct prose answer.
+
+When to embed a slide chip inline: the visitor's question maps cleanly to one slide's topic. Answer in prose, drop the chip mid-paragraph where it makes sense, move on. One or two chips per reply max. Don't substitute chips for prose — they're a side door, not the answer.
+
+When NOT to use either: as a substitute for the live demo tour. The two surfaces are complementary. The demo tour shows HOW Hailer feels in daily use. The presentation tells the STORY of what Hailer is and how the pieces fit together.
+
+### Product Description
+
+#### What Hailer is — the cloud platform overview
+
+Hailer is a cloud platform designed for process-driven business management and communication. The largest organizational unit in Hailer is the workspace, and there is typically one workspace per customer.
+
+A workspace contains the structures the team works in: workflows and datasets that organize activities, discussions for messaging, a feed for company-wide updates, calendars for events, files, users, and teams. Hailer is built around the idea that day-to-day work — sales cases, tasks, projects, support tickets — moves through a structured process the team can configure rather than a fixed product taxonomy.
+
+#### Activities, workflows, and datasets
+
+Activities form the core of Hailer. They model the structured organizational work — sales cases, tasks, projects — that progresses through a defined process.
+
+Activities live inside two related structures:
+
+- Workflows are configurable processes. The process owner defines which steps (phases) the workflow consists of, plus what data is collected within the workflow. Activities move from phase to phase as the work progresses.
+
+- Datasets share most properties with workflows but disable phase transitions between categories — they're more like a labeled list than a stage-by-stage process. Datasets are useful for reference data (customers, products, equipment) where items don't move between stages.
+
+A single workspace can have many workflows and datasets side by side.
+
+#### Available field types and advanced field features
+
+Each workflow defines what data is captured on its activities. Hailer supports a wide range of field types:
+
+- Text, Predefined Options, Text Area
+- Numeric, Numeric with Unit
+- Date, Date Range, Time, Time Range, Date & Time, Date & Time Range
+- Country
+- Activity links, User links, Team links, Linked activities
+- Subheader fields (visual grouping)
+
+Activities can also carry location data with coordinates and file attachments.
+
+Advanced field capabilities:
+
+- All field types can be turned into function fields — calculated fields whose values come from JavaScript-based rules running in sandboxed virtual environments.
+- Fields can be marked mandatory.
+- Phase-specific visibility lets a field show only in certain phases.
+- User- and team-level access restrictions hide fields from users without permission.
+- A PDF document generator produces offers, invoices, packing lists, confirmations, certificates, and reports from activity data.
+
+#### Discussions, feed, and calendar
+
+Hailer has three communication surfaces:
+
+Discussions come in four flavors:
+- Private discussions — direct messages between users who share a workspace.
+- Group discussions — multi-participant chats.
+- Activity discussions — chats linked to a specific activity (task/project/case).
+- Event discussions — chats linked to a calendar event.
+
+Feed: every Hailer workspace comes with a feed available to all workspace members, used for organization-wide updates. Hailer also automatically posts to the feed when notable workflow events happen, so the team sees milestones without anyone having to broadcast them manually.
+
+Calendar: workspaces support multiple calendars with restricted visibility (per user or team). Each event can have its own discussion thread, so conversation around an event lives next to the event itself.
+
+#### Hailer Apps (Beta) and Insights
+
+Hailer Apps (Beta) are customized applications that use Hailer as their infrastructure. Apps are built on top of the platform's data model and authentication. New apps are currently available through development inquiry — Hailer's team works with customers to scope and build them.
+
+Insights is built on top of Apps. It provides:
+- A SQL query builder for assembling reports from workflow data
+- Pivot tables
+- Visual charts
+- Plain data tables, with the ability to drill into the underlying activities
+
+Insights is how teams turn the structured data inside their workflows into dashboards, KPIs, and management reporting.
+
+#### Users, teams, and files
+
+Users: Hailer accounts are global — once a user has a profile they can participate in multiple workspaces with the same identity. Each workspace has its own attributes for the user (role, team membership, etc.) so a person can be an admin in one workspace and a regular member in another.
+
+Teams: workspaces use teams to group users. Team membership drives content visibility — fields, phases, and activities can be restricted to specific teams so members only see what's relevant to their role.
+
+Files: Hailer has an inbuilt file management system to make it easy to store, track, find, and share files. Files can be attached to activities, posted in discussions, or uploaded to the feed, and they're searchable across the workspace.
+
+#### API, platform support, and technology stack
+
+API: Hailer exposes an HTTP REST API. Requests use JSON, and authentication is via username/password credentials.
+
+Platform support: the fully responsive Hailer web application is supported on Chrome, Firefox, Safari, and Edge. Native iOS (13+) and Android applications are also available. The iOS app includes additional field-operations capabilities for users working off-site.
+
+Technology stack:
+- Frontend: Angular
+- iOS: Swift (native)
+- Android: web-based wrapper
+- Backend: Node.js
+- Database: MongoDB
+- Language: TypeScript across the stack
+- Infrastructure: AWS
+
+### sso-and-admin-controls
+
+#### SSO, login methods, and workspace-admin controls (audit, biometric, bulk invite)
+
+Hailer supports the following login methods and admin controls. Anything below is shipping today; describe them honestly, don't add features that aren't here.
+
+Single sign-on:
+- Microsoft Entra ID (Azure AD) login is supported via a dedicated route: \`/#/entralogin/{clientId}/{tenantId}\`. The workspace's IT admin provides the Entra app's client and tenant IDs; users authenticate against Microsoft and are then signed into Hailer. This is the SSO answer for organisations on the Microsoft stack.
+- Username + password is the default login.
+- There is NO first-party SAML or generic OIDC provider beyond Entra at this time. If a visitor asks about Okta, OneLogin, Auth0, or 'plain SAML', be honest: the supported enterprise SSO today is Microsoft Entra. The Hailer team can be contacted for other identity provider questions.
+
+Biometric / local-auth lock:
+- Workspace admins can enable a 'Force local auth' setting that requires users on iOS/Android to unlock the app with their device biometrics (Face ID, Touch ID, fingerprint) or PIN on every launch. Useful for shared devices or high-security workflows.
+
+Audit log:
+- Workspace admins have access to an audit log in workspace settings that records operations with the user, timestamp, IP address, request/response details, and success/failure status. Use it for compliance reviews or to investigate unexpected changes.
+
+Bulk user invitation via Excel:
+- Admins can invite many users at once by uploading an Excel file from workspace settings. The template supports user details, team assignment, role, and a notes column. This is separate from the per-activity Excel import (\`v3.activity.import\`); both surfaces exist but they import different things.
+
+Data residency / hosting location:
+- All Hailer infrastructure runs in AWS region eu-west-1, located in Ireland. The MongoDB database is in the same region. Every workspace's data resides in the EU (Ireland) by default.
+- There is currently NO option to choose a different region or pin a workspace to another location — it's eu-west-1 for all customers. If a visitor needs US, APAC, or in-country hosting, be honest: that isn't offered today, and they should contact the Hailer team to discuss requirements.
+- This is good news for EU/GDPR data-residency questions: 'your data stays in the EU — specifically AWS in Ireland.' It's a limitation for anyone who requires data to live outside the EU.
+
+What to tell different visitors:
+- IT / admin asking about SSO: 'Microsoft Entra ID is the supported SSO today. The login URL pattern is \`/#/entralogin/{clientId}/{tenantId}\`. SAML / Okta / other IdPs aren't first-party today — reach out to Hailer if that's a requirement.'
+- IT asking about audit + access reviews: 'Yes, workspace admins have an audit log under settings; it records user actions with IP and timestamp.'
+- IT / admin asking about data residency or 'where is our data hosted?': 'Everything runs on AWS in the EU — region eu-west-1, in Ireland — including the database. There's no region-selection option today; all workspaces are hosted there. If you need hosting outside the EU, that's a conversation with the Hailer team.'
+- Operations / decision-maker asking about onboarding many users: 'You can invite users one at a time or upload an Excel of users in settings.'
+- End user asking about device security: 'On mobile, your workspace admin may require Face ID/Touch ID to open the app — that's the Force-local-auth setting.'
+
+### UI Guide
+
+#### Hailer main layout: three-column structure with left nav, content, and sidenav
+
+Hailer uses a three-column layout. On desktop screens (wider than 600px) the layout is:
+
+- Left sidebar: a 56-pixel vertical icon menu, always visible.
+- Main content: fills the remaining horizontal space; this is where workflow boards, lists, and pages render via the Angular router-outlet.
+- Right sidenav: a 400-pixel panel that opens when you click an activity or discussion to show its details.
+
+On mobile (600px and below) the layout collapses:
+- A top toolbar appears.
+- The sidenav becomes full screen (100vw) when opened.
+- A bottom navigation bar replaces the left sidebar.
+
+This structure stays consistent across the entire application — once a user understands it, they can navigate any section.
+
+#### Left navigation menu — icons and what each section does
+
+The left navigation is a vertical icon menu always visible on desktop. From top to bottom:
+
+1. Discussions — chat and team discussions.
+2. Feed — activity feed and updates.
+3. Calendar — events and schedules.
+4. Activities — workflows and kanban boards.
+5. Apps — custom applications.
+6. People — user directory.
+
+At the bottom:
+- Settings — workspace settings (admins only; regular users do not see this).
+- User profile — opens a menu with profile settings, language selection, dark/light mode toggle, and logout.
+
+When guiding someone, refer to icons by position. Example phrasing: 'Click the Activities icon in the left menu — it's the 4th icon from the top, and looks like a kanban board.'
+
+#### Activities section: workflow list, kanban view, view modes, and actions
+
+When the user navigates to /activities they see the workflow list view: every workflow they have access to appears as a card with a name and an icon. Clicking a card opens that workflow.
+
+The default workflow view is Kanban (URL pattern: /activities/{workflowId}). Phases are columns, activities are cards inside columns. View modes can be toggled in the top-right:
+- Kanban — cards in columns by phase (default).
+- Table — list view with sortable columns.
+- Calendar — timeline/calendar view.
+- Map — location-based view (only when enabled for the workflow).
+
+Primary actions in the workflow view:
+- Create activity: click the [+ Add] button in the top-right, or click empty space inside any phase column.
+- Open activity: click any card — it opens the activity detail in the right sidenav.
+- Move activity: drag a card to another phase column, OR open the card and use the phase selector in the header.
+- Filter: use the search bar or filter controls at the top.
+
+#### Activity sidenav: tabs, modes, and control buttons in the right panel
+
+The activity sidenav opens when you click an activity card. It is 400 pixels wide on desktop and full-screen on mobile.
+
+Header section shows: activity name (large text), workspace badge (colored tag), workflow badge (clickable — navigates to the workflow), a copy-tag button (mentions the activity in discussions), and a call button when video calls are enabled.
+
+A tab bar of icons sits below the header:
+1. Detail — main fields and info.
+2. Participants — followers, with a badge count.
+3. Discussion — activity chat with an unread count badge.
+4. Files — attachments with a count badge.
+5. Location — map view (when enabled).
+6. Linked — related activities with a count.
+7. Options — activity settings (when permitted).
+
+Three modes determine what the user sees:
+- View mode: read-only display.
+- Edit mode: fields become editable; Cancel and Save buttons appear at the bottom.
+- Create mode: empty form for a new activity.
+
+The control buttons at the bottom (visible in edit and create modes) are Cancel (discard changes) and Save (with checkmark icon).
+
+#### How to move activities between phases
+
+Activities can move between phases two ways:
+
+Method 1 — Drag and Drop in Kanban view:
+Drag the card from its current phase column and drop it in the target phase column. Best for quick rearrangements when you can see both columns.
+
+Method 2 — Phase selector in the activity sidenav:
+Open the activity to expose the phase dropdown near the top of the sidenav, then select the target phase. Best when phases are off-screen, you're already inside the activity, or many fields need to change at once.
+
+Phases are displayed left-to-right in the order defined by the workflow. The first phase is the leftmost column (typically 'New' or 'Draft'). The last phase is the rightmost column (typically 'Done' or 'Archived').
+
+#### Discussions section: list, threads, and activity-linked chats
+
+The Discussions section is at /discussions.
+
+Discussion list view shows every discussion the user is part of. Unread message counts appear as badges on each item. A search bar at the top lets users filter by name or content.
+
+Discussion view layout:
+- Message list shown chronologically.
+- Input field at the bottom for typing messages.
+- File attachment button (paperclip icon).
+- Emoji picker.
+- @mention support — typing @ surfaces a user picker.
+
+Activity discussions are a special case: an activity can have its own attached discussion. To access it, open the activity sidenav and click the Discussion tab (3rd tab, speech-bubble icon). Users must Join the discussion before they can see and post messages — this is by design so people don't auto-subscribe to every activity's chat.
+
+#### Common Hailer UI patterns: buttons, cards, badges, tooltips, colors
+
+Common patterns repeat across Hailer's interface:
+
+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 in light mode, dark gray in dark mode.
+- Rounded corners with a subtle shadow.
+- Click to select or open.
+
+Badges:
+- Small colored pills showing counts or status.
+- Red badge: requires attention.
+- Gray badge: informational.
+
+Tooltips:
+- Hover over an icon button to see its label. This is the fastest way to understand an unclear icon.
+
+Color coding:
+- Phases have assigned colors (visible as the column accent in kanban).
+- Workflow badges use the workflow's own color.
+- Workspace badges use the workspace's color.
+
+#### Common Hailer user issues and how to resolve them
+
+Common issues and what they usually mean:
+
+'I can't see the workflow' — the user probably lacks permission to that workflow. An admin needs to grant access in the workflow's permissions settings.
+
+'I can't edit this activity' — the user does not have edit permission for this phase. Some phases are read-only for certain roles.
+
+'I can't move the card' — phase transitions may be restricted by the workflow's configuration. Check the workflow settings to see which transitions are allowed.
+
+'Where are my discussions?' — the user must be a member of a discussion to see it. Check the Discussions section in the left menu. For activity-linked discussions, the user must Join the discussion first via the activity's Discussion tab.
+
+'I can't see Settings' — Settings is admin-only. Regular (non-admin) users do not see this menu item; this is by design.
+
+### use-case-contract-management
+
+#### Use case — contract management on Hailer with e-signature integration
+
+Contract management is a common use case Hailer is well-shaped for. A legal team handles many contracts every week — NDAs, supplier agreements, employment contracts, letters of representation, partnership agreements. Without a system, these tend to live across Word documents, email threads, shared folders, and tracking spreadsheets. Versions get lost, the wrong draft gets signed, and nobody knows what's pending or about to expire. The Hailer pattern below addresses that.
+
+The pattern — a 'Contracts' workflow with four phases:
+- Draft — the lawyer is writing the contract or revising it after counterparty feedback.
+- Negotiation — the draft has been shared with the counterparty and they're proposing changes (back and forth as needed).
+- Ready to sign — both sides have agreed on the final version; awaiting signatures.
+- Signed — fully executed; the signed PDF and metadata are stored on the activity.
+
+Fields commonly added to the contract activity:
+- Contract type (NDA, supplier agreement, employment, etc.) as a dropdown.
+- Counterparty name and country (a link to a 'Companies' dataset if the team tracks counterparties).
+- Effective date and expiry date — drives the calendar view and the 'expiring soon' alerts.
+- Owner — the responsible lawyer.
+- Version number — incremented each time the draft is revised.
+- The current draft (file attachment) and, once executed, the signed PDF.
+- Notes / risk flags as a text-area field.
+
+E-signature integration — the editing/signing separation:
+- Editing and signing are two separate stages. Hailer hosts the editing and negotiation; an external e-signature service handles the final signing.
+- All draft revisions happen inside Hailer in the Draft or Negotiation phase. The counterparty's comments come in by email or via a shared Hailer discussion; the lawyer brings the changes into the next version. Each version is saved on the activity, so the negotiation has a full audit trail.
+- Only the final, agreed PDF is sent for signature. The activity moves to 'Ready to sign' when the lawyer clicks the equivalent of 'send for signing'.
+- When signatures complete, the signed PDF is returned to Hailer automatically and the activity advances to 'Signed'.
+- Hailer can integrate with e-signature services through its REST API, webhooks, and Zapier integration. The supported services depend on what's available in the customer's region — in particular, e-signature providers vary by country because of differing legal-validity rules (e.g. providers that work with national bank IDs). For specific integrations the in-workspace Helper or the Hailer team can confirm the current options.
+- Counterparties do not need a Hailer account to participate. They receive a signing link by email, click 'Sign' in their browser, and the signature flows back into Hailer. No account creation, no software install on their side.
+
+The old way vs the new way:
+- OLD: Lawyer writes the contract in Word → emails it to the other party → the other party prints, signs, scans, emails back → someone saves it in a folder → someone updates a spreadsheet → next month nobody remembers where it is or when it expires.
+- NEW (Hailer + e-signature integration): Lawyer drafts the contract inside Hailer → revises through the Draft/Negotiation phases as needed → clicks 'Send for signing' when both sides agree → signing happens online, signed PDF returns to Hailer automatically → status is always visible (Draft, Negotiation, Ready to sign, Signed, Expiring soon) → calendar and feed surface upcoming expiries automatically.
+
+What the customer gets:
+- Time saved per contract — no printing, no scanning, no chasing people for wet signatures.
+- One place for every contract — nothing gets lost in email threads or shared folders.
+- Always-visible status — who has signed, who hasn't, what's overdue, what expires soon.
+- Cross-border signing — counterparties without a national e-ID can still sign through e-signature providers that support international flows.
+- Legal proof — every signature is timestamped, and the negotiation history lives on the contract activity for audit purposes.
+- Automatic reminders — Hailer can trigger feed posts or calendar alerts when a contract is about to expire or has been waiting for a signature too long.
+
+Who this pattern fits:
+- Companies handling many legal contracts (10+ per month is a useful threshold).
+- Small legal teams spending disproportionate time on administrative tracking.
+- Organisations working with international partners where signatures cross borders.
+- Industries with heavy contract volume — law firms, construction and real estate, HR-heavy organisations (employment contracts, NDAs), consulting firms, property management, manufacturers with supplier networks, any business with a mix of domestic and foreign partners.
+- Teams that need a clear audit trail for compliance reviews.
+
+When a visitor describes contract chaos — 'we lose versions', 'I never know what's pending', 'half my week is chasing signatures' — translate this pattern back into their words. Lead with the pain ('versions getting lost', 'signatures across countries', 'no audit trail') and describe how the Hailer + e-signature flow addresses it before naming Hailer terms like phase, activity, dataset.
+
+If a visitor wants advanced collaborative editing inside Hailer (track-changes, real-time co-editing of the contract document itself), be honest: today the pattern relies on revising the draft activity-by-activity in the Draft phase, with the document attached as a file. For organisations that do very heavy in-document negotiation, that's a future-roadmap conversation rather than a shipped feature today.
+
+### value-propositions
+
+#### Why Hailer — the seven benefits to translate from
+
+When a visitor describes their current setup and the pain points in it, these are the seven angles Hailer's value tends to land on. Use them as the translation targets when answering 'how would this work for us?' — pick the one or two that match their pain, never all seven.
+
+Modular — building blocks, not a fixed product.
+- Workflows, datasets, fields, phases, discussions, calendars, and apps are independent pieces a team assembles.
+- A 'CRM' is just a sales-pipeline workflow plus a customer dataset. A 'project tracker' is a project workflow plus a task workflow. A 'helpdesk' is a ticket workflow plus a customer dataset plus public forms.
+- You don't buy a CRM module and a PM module separately and bolt them together. You compose the pieces that fit, and you add more pieces as the team grows.
+- Translation example: someone running a small consultancy hears 'modular' as 'I'd have a deals pipeline, a project tracker, and a client list as three pieces that already know about each other — not three apps I have to reconcile'.
+
+Cost saving — one platform replaces the stack of single-purpose tools.
+- The teams who get the most from Hailer were running 3–5 tools before: a CRM, a project tracker, a ticketing system, a chat app, maybe a doc generator on top.
+- Hailer is one subscription with one auth, one permission model, one data model, doing all of it. Total cost ends up lower than the per-seat sum of the individual tools, especially as headcount grows.
+- Translation example: 'instead of paying for HubSpot + Asana + Intercom + Slack + a PDF tool, your team works in one place and the bill is one line item.' (When talking to a visitor, name their pain — 'the stack you're paying for today' — instead of naming the competitors.)
+
+Time saving — no re-keying, no swivel-chair, context-with-the-work.
+- Customer info lives once, as structured fields, and every related deal, project, ticket, or invoice references it.
+- Conversations attach to the record they're about, so handoffs don't lose context — sales-to-delivery, support-to-engineering, ops-to-finance.
+- Phase changes show up in the feed automatically; status updates write themselves.
+- The time savings come from removing seams, not from being faster at any one thing.
+- Translation example: 'when a deal moves to "won", everyone watching it sees the move and the conversation history is right there on the deal — nobody has to re-summarize the deal in the project channel.'
+
+Customizable apps — every workspace can extend itself.
+- The Apps SDK (React, Svelte, vanilla JS) lets teams build their own surfaces on top of their data — dashboards, kiosks, customer portals, public forms, anything. (Hailer Studio is a separate surface — a cloud SDK editor for workspace configuration, not an app builder; don't conflate the two.)
+- The in-workspace Helper bot can scaffold an app on request, so non-engineers can describe what they need and get a starting point.
+- If the off-the-shelf workflow shape doesn't quite fit the team's process, the workspace grows new surfaces to match. The platform bends to the team, not the other way around.
+- Translation example: 'if your field techs need a phone-friendly intake form their customers can fill in, that's a public form on your job workflow — you don't go shop for a SaaS form builder.'
+
+Still just a chat — discussions are the spine.
+- Everything in Hailer ties back to a conversation. Activities have discussions. Calendar events have discussions. The AI Helper bot lives in a discussion.
+- Teams trying Hailer find the learning curve gentle because the dominant interaction is still 'send a message' — the structured-work side is where the chat output gets organized, not a separate paradigm.
+- This matters for adoption: the people on the team who only ever want to chat can stay in chat; the people who want to track structure see the structure; everyone is in the same workspace.
+- Translation example: 'for the half of your team that just wants to talk things through, Hailer feels like a chat app — the kanban board is for the other half, but they're both looking at the same deals.'
+
+Works across the team and beyond it — not just one business function, and not strictly business at all.
+- Hailer's data model is flexible enough to hold a sales pipeline and a household maintenance log; a hobby club's event list and a freelancer's invoicing; a charity's volunteer roster and a school's parent-communications log.
+- Personal / hobby / non-commercial use of the free workspace is explicitly permitted by Hailer's TOS. A real example: a board-game club uses Hailer to maintain their internal documentation and a list of currently-active members. Other communities have used Hailer the same way for training programs, conference logistics, family-business operations, equipment registers, asset tracking.
+- The platform doesn't prescribe a business shape — it gives you the building blocks, and the same workspace can hold multiple unrelated workflows for the same team.
+- Translation example (mixed team): 'the same workspace your sales team lives in can also hold the engineering team's release calendar and HR's onboarding tracker — you're not buying separate tools for each function.'
+- Translation example (personal / community): 'if you're running a club or volunteer group, the same building blocks work — your member list is a dataset, your events are a workflow with phases like planned, confirmed, ran, retrospective. The free tier covers it for small groups; pay-as-you-go tokens only enter the picture if you start using AI features or heavy calculated fields.'
+
+Your system = your code — workspace as code via the SDK.
+- With @hailer/sdk on npm, a workspace's full configuration (workflows, fields, phases, teams, groups, insights, function fields) is just TypeScript files in a git repo.
+- Version it, diff it, code-review it, branch it, automate it. For engineering-led teams this turns workspace evolution from 'someone clicks around in settings' into a normal development loop with PRs and history.
+- Combined with @hailer/mcp it means AI assistants like Claude Code can read and modify workspace structure directly — describe a change in chat, the AI proposes the SDK edit, you review and push.
+- Translation example (developer-leaning visitor): 'when your ops manager asks for a new field on the deal workflow, that's a one-line edit in the workspace repo, code-reviewed and pushed like any other change. The workspace is configuration as code.'
+
+How to use these in the chat:
+- After the visitor has described their current setup and pain points, pick ONE or TWO of these benefits that match what they said. Never list all seven; that's a brochure, not a conversation.
+- Translate the benefit into the visitor's words and concrete examples. If they named tools, name the seams between those tools; if they named a workflow ('our intake process'), name the Hailer shape ('a workflow with intake → review → action → done phases') in that language.
+- Lead with the benefit's effect ('you stop re-keying client info') before naming the underlying capability ('referenced fields between a deal workflow and a client dataset').
+- Don't oversell. If a visitor has a small simple need, 'modular building blocks' is overkill — just say 'you'd model it as one workflow with three phases' and move on. The benefits are a vocabulary for fit, not a checklist to recite.
+
+### workflow-vs-dataset
+
+#### Workflow vs Dataset — which one to use
+
+Hailer has two related structures that both hold activities: workflows and datasets. They share most properties (fields, permissions, views, public forms, calendar entries) but differ in how phases work. Picking the right one is one of the first questions when modelling a use case.
+
+Use a WORKFLOW when:
+- The records have a lifecycle with stages — leads become qualified, qualified become proposals, proposals become won/lost.
+- The activity moves through ordered phases as the work progresses.
+- Phase changes are meaningful events (you want them in the feed, want to trigger automations, want reports of how long activities spent in each stage).
+- Examples: sales pipelines, recruitment funnels, project trackers, support tickets, onboarding processes, deal management, incident response, change-management approvals.
+
+Use a DATASET when:
+- The records are reference data or a catalog — they have categories but don't 'flow' through them.
+- An item doesn't progress from one state to another; it either stays in its category permanently or moves only as an admin correction.
+- Phase changes are not meaningful events on their own — categories function more like tags than stages.
+- Examples: customer lists, product catalogs, equipment registers, vendor lists, location lists, employee directories, contact lists, asset inventories, price lists, knowledge-base entries, FAQ items.
+
+Decision questions to ask when a user describes a use case:
+1. Does this thing have a beginning, middle, and end? (workflow if yes; dataset if no)
+2. Would the team expect to see a kanban view of these moving through stages? (workflow)
+3. Or do they mostly want a sortable, filterable list to look things up in? (dataset)
+4. Is the same item likely to stay in one state for months or years? (dataset)
+5. Is the same item likely to move between states within days or weeks? (workflow)
+
+Mixed cases — when a user says 'customer list':
+- A pure customer list (names, contact info, segment) is a DATASET.
+- A list of customers with sales activity that progresses (active prospects, current customers, churned, won-back) is closer to a workflow with phases for those stages. Ask what they actually need before committing.
+
+Mixed cases — when a user says 'projects':
+- Active projects that move from planning → execution → review → done are a WORKFLOW.
+- A reference list of completed projects for portfolio display is a DATASET.
+
+When unclear, default to a workflow with a small number of phases — it's the more general structure. Datasets can be thought of as 'workflows whose phases are categories, not stages'. You can later split a dataset off from a workflow if the use case clarifies.
+
+The Helper bot inside a Hailer workspace should make this distinction explicitly when a user asks for something modelled. If the user says 'make a customer list', the Helper should reply 'I'll set this up as a dataset — a labelled list rather than a stage-by-stage process — does that match what you have in mind?' rather than silently building a phase-rich workflow.
+
+Technical detail (developer-archetype question): in Hailer's data model, a dataset is a workflow with the boolean flag \`enableUnlinkedMode\` set to \`true\`. The same backing entity backs both — datasets are workflows in unlinked mode. Effects of setting the flag:
+- The item is listed under 'Datasets' in the UI instead of under 'Workflows'.
+- Phases on the workflow are not linked together — i.e. the ordered phase transitions that workflows support are disabled, and phases function as labels/categories rather than ordered stages.
+- Field, permission, public-form, and calendar capabilities work the same as on workflows.
+
+For developers building against Hailer's API: see the hailer-api workflow schema for the full set of options that flip with the flag. When creating a workflow via @hailer/sdk or the REST API, set \`enableUnlinkedMode: true\` to make it a dataset from the start; flipping the flag on an existing workflow is also supported but changes how its phases behave.
+`;
+exports.HAILER_KNOWLEDGE_BYTES = exports.HAILER_KNOWLEDGE_CORPUS.length;
+//# sourceMappingURL=knowledge.js.map