# Agent action log
Source: https://docs.gainable.dev/autopilot/agent-action-log
The audit trail for everything a Autopilot agent does
## What is the action log?
Every time a Autopilot agent runs, the runtime records what happened. The result is a structured, queryable log that lives in your app as the `AgentAction` collection. If something is in doubt, the action log is the source of truth.
The log captures four things for every run:
1. **The trigger.** Which playbook fired and why.
2. **The observation.** What the agent looked at (records, signals, prior actions).
3. **The reasoning.** What the agent decided and why.
4. **The outcome.** Which tools ran, what they returned, what happened next.
This isn't optional. The log is always on. The runtime cannot run a tool without writing to it.
## Why every action is logged
* **Trust.** Users approve drafts faster when they can see the full reasoning chain. Skeptics become believers when they can audit every step.
* **Debugging.** When a playbook misbehaves, the log shows where the reasoning went sideways.
* **Compliance.** Regulated environments need provable audit trails. The log is structured for export.
* **Graduation.** [Risk tier graduation](/autopilot/risk-tiers) uses approval rates from the log. No log, no graduation.
* **Improvement.** Approval and skip patterns reveal which objectives are tuned correctly and which need editing.
## Schema
The `AgentAction` collection is a system-managed collection in every Gainable app. You can query it through the [Copilot](/copilots/overview), the dashboard, or the action log UI in [Autopilot](/autopilot/inbox).
| Field | Type | What it stores |
| ------------------ | --------- | -------------------------------------------------------------------------- |
| `id` | string | Unique action ID |
| `agent_id` | string | The agent that produced the action |
| `playbook_id` | string | The playbook that ran |
| `objective_id` | string | The objective the playbook was working toward |
| `scope` | enum | `app_wide` or `personal` |
| `trigger_type` | enum | `schedule`, `data_change`, `webhook`, `user_triggered` |
| `trigger_payload` | json | Full payload of the trigger |
| `observation` | json | Records and signals the agent considered |
| `reasoning` | text | Human-readable reasoning chain |
| `tool_calls` | array | Each tool the playbook called, with inputs and outputs |
| `outcome` | enum | `approved`, `skipped`, `auto_executed`, `rate_limited`, `error`, `pending` |
| `owner_user_id` | string | The user the action's draft was routed to |
| `created_at` | timestamp | When the run began |
| `resolved_at` | timestamp | When the action reached a terminal outcome |
| `parent_action_id` | string | If this action was a follow-up to another |
## Outcomes
| Outcome | What it means |
| --------------- | ---------------------------------------------------------- |
| `pending` | Draft is waiting in Autopilot |
| `approved` | Owner approved; underlying tool ran |
| `skipped` | Owner skipped the draft |
| `auto_executed` | Action ran without approval (auto tier or auto-with-undo) |
| `rate_limited` | Action was blocked by a rate limit |
| `error` | Tool call failed; reason captured in `tool_calls[*].error` |
## Querying the log
The action log is just a collection, so you can query it the same way you query anything else.
### From Copilot
Ask the [Copilot](/copilots/overview) directly:
```text theme={null}
Show all SLA-enforcer actions from the last 7 days
where the outcome was skipped.
```
```text theme={null}
Which playbook produced the most rate_limited
outcomes this month?
```
### From a dashboard
Drop a chart or table view onto a dashboard scoped to the `AgentAction` collection:
```text theme={null}
Add a chart to the operations dashboard showing
SLA-enforcer outcomes (approved, skipped, error)
over the last 30 days, grouped by week.
```
### From a playbook
Yes, agents can read their own action log. This is how follow-up playbooks know what's already been tried:
```yaml theme={null}
- tool: query_collection
collection: AgentAction
filter: "playbook_id = 'stalled_deal_chaser' AND owner_user_id = {{ deal.owner }} AND created_at > now - 7_days"
limit: 1
```
If a stalled-deal playbook sees that it already drafted a nudge for this deal in the last 7 days, it can skip drafting another. Ackermann-class loops are bounded.
## What gets logged for each tool
| Tool | Logged inputs | Logged outputs |
| -------------------- | ----------------------------- | ------------------------------------ |
| `query_collection` | Filter, sort, limit, fields | Record IDs returned, count |
| `update_records` | Filter, set clause | IDs updated, prior values for undo |
| `send_email` | Recipient, subject, body hash | Provider message ID, delivery status |
| `send_slack` | Channel, message hash | Slack message ID |
| `send_sms` | Recipient hash, body hash | Provider message ID |
| `notify_user` | User ID, title, body | Notification ID |
| `call_external` | URL, method, body hash | Status code, response hash |
| `ask_human` | User ID, question, options | Answer, response time |
| `create_task` | Task fields | Created task ID |
| `draft_for_approval` | Underlying payload | Draft ID, owner |
Bodies of outbound messages are hashed by default for compactness. The full content is retained on the draft itself in [Autopilot](/autopilot/inbox) until the configured retention window closes.
## Retention
| Data | Retention |
| -------------------------- | ------------------------------------------ |
| Action records | Indefinite (or per-org configured) |
| Full draft bodies | 90 days after `resolved_at` (configurable) |
| Tool input/output payloads | 30 days (configurable) |
| Hashes and metadata | Same as the action record |
For regulated environments, retention can be raised to 7+ years. For consumer-facing apps with privacy obligations, retention can be tightened.
## Common queries
### Approval rate per playbook
```text theme={null}
Show approval rate per playbook over the last 30 days,
sorted highest to lowest.
```
This is the number you watch when deciding whether to graduate a playbook to a higher [risk tier](/autopilot/risk-tiers).
### Why was this draft created?
Open the draft in [Autopilot](/autopilot/inbox). The `reasoning` and `observation` fields render alongside the proposed action. No need to query the log directly.
### What did this agent do this morning?
```text theme={null}
Show all actions from the daily-briefing agent
in the last 24 hours.
```
### Where are skips concentrated?
```text theme={null}
Which objectives have the lowest approval rate this month?
```
A low approval rate means the objective is producing drafts that don't match what users actually want. Tighten the trigger filter or revise the template.
## Best practices
A dashboard with approval rate, skip reasons, and rate-limited counts is the single most useful artifact for tuning agents. Add it during the autonomy build phase.
Errors in `tool_calls` are usually a sign of upstream changes (renamed fields, missing API keys, deleted records). Spikes mean something broke.
When playbook B runs because playbook A's draft was approved, link them. The thread of reasoning becomes traceable.
The runtime owns the schema. Custom apps that try to insert their own action records will fail validation. Use [`create_task`](/autopilot/tools) for human-visible TODOs instead.
## Learn more
What gets logged per tool
How the log feeds graduation
Where the log surfaces in the UI
How log slicing maps to scope
# Connect outbound
Source: https://docs.gainable.dev/autopilot/connect-outbound
Slack, SMS, calendar, DocuSign, Stripe, generic webhooks. Inbound and outbound integrations for agents
## What Connect does
Gainable Connect is the integration layer between your Gainable app and external systems. For [Gaia Autopilot](/autopilot/overview), Connect plays two roles:
* **Outbound.** The targets agents can reach when they call [tools](/autopilot/tools) like `send_slack` or `call_external`.
* **Inbound.** The sources that fire [webhook triggers](/autopilot/triggers).
If you've used [datasets](/building/data-connectors) for ingesting data, Connect is the same idea applied to action and event flow. Datasets bring data in for the [Copilot](/copilots/overview) and the [build agents](/concepts/agents) to read. Connect routes outbound work and inbound events for agents.
## Outbound channels
Every outbound integration lives behind a typed [tool](/autopilot/tools) and inherits a default [risk tier](/autopilot/risk-tiers). The org configures credentials once; the agent calls the tool.
### Slack
```yaml theme={null}
- tool: send_slack
channel: "#sales-ops"
text: "Pipeline summary"
blocks: "{{ rendered }}"
```
| Capability | Notes |
| ----------------- | -------------------------------------------------- |
| Channels | Public, private (with bot installed) |
| DMs | Yes, to bot-installed users |
| Threading | `thread_ts` parameter |
| Default risk tier | High (draft-and-approve) |
| Common graduation | Internal channels can graduate to `auto_with_undo` |
### SMS
```yaml theme={null}
- tool: send_sms
to: "{{ contact.phone }}"
body: "{{ message }}"
```
| Capability | Notes |
| ----------------- | ---------------------------------------------------------------------------- |
| Provider | Twilio (default), configurable |
| Delivery receipts | Logged in action log |
| Default risk tier | High (draft-and-approve), no auto-with-undo path |
| Notes | SMS undo isn't possible. Always draft-and-approve unless explicitly opted-in |
### Calendar
Outbound calendar operations through the configured calendar provider (Google Calendar, Microsoft 365).
```yaml theme={null}
- tool: call_external
via: calendar
action: create_event
calendar_id: "{{ user.calendar_id }}"
event:
title: "Follow-up: {{ deal.name }}"
start: "{{ next_business_day_at_2pm }}"
duration_minutes: 30
attendees:
- "{{ contact.email }}"
```
| Capability | Notes |
| ----------------- | --------------------------------- |
| Create event | Yes, draft-and-approve by default |
| Update event | Yes, with undo window |
| Delete event | Yes, draft-and-approve only |
| Default risk tier | High (calendars are user-visible) |
### DocuSign
```yaml theme={null}
- tool: call_external
via: docusign
action: send_envelope
template_id: "{{ template_id }}"
recipients:
- email: "{{ contact.email }}"
name: "{{ contact.name }}"
role: "Signer"
```
| Capability | Notes |
| ----------------- | ---------------------------------------- |
| Send envelope | Always draft-and-approve. No exceptions. |
| Voiding | Allowed with explicit user action |
| Default risk tier | High (legally binding), no auto path |
### Stripe
```yaml theme={null}
- tool: call_external
via: stripe
action: create_invoice
customer: "{{ stripe_customer_id }}"
items:
- amount: "{{ amount_cents }}"
currency: usd
description: "{{ description }}"
```
| Capability | Notes |
| ----------------- | ----------------------------------------- |
| Create invoice | Draft-and-approve |
| Capture payment | Draft-and-approve only |
| Refund | Draft-and-approve only |
| Default risk tier | High (financial operations), no auto path |
### Generic webhooks (`call_external`)
When the registry doesn't have a dedicated tool, use [`call_external`](/autopilot/tools).
```yaml theme={null}
- tool: call_external
method: POST
url: "https://api.example.com/notify"
headers:
Authorization: "Bearer {{ secrets.example_key }}"
body:
event: "deal_lost"
deal_id: "{{ deal.id }}"
```
The runtime can't reason about what an arbitrary endpoint does, so the default tier is high. If the call is well-understood and idempotent, it can be graduated.
## Inbound webhooks (as triggers)
Inbound webhooks become [webhook triggers](/autopilot/triggers) on a playbook. The runtime provisions a unique URL per trigger and verifies signatures where the source supports it.
### Provisioning
When you add a webhook trigger, Connect generates a URL:
```
https://api.gainable.dev/webhooks/{app_id}/{trigger_id}
```
You configure the source system to POST to that URL.
### Signature verification
| Source | Verification method |
| -------- | ------------------------------------------------------- |
| Stripe | `Stripe-Signature` header, HMAC-SHA256 |
| GitHub | `X-Hub-Signature-256` header |
| SendGrid | Public key signature on each event |
| Twilio | `X-Twilio-Signature` header |
| Generic | HMAC if shared secret is configured, else IP allow-list |
The runtime rejects unverified webhooks before the playbook runs. Rejections are logged in the [action log](/autopilot/agent-action-log) for debugging.
### Common inbound sources
| Source | Example events | Common playbook |
| -------- | ------------------------------- | --------------------------------------------------------- |
| Stripe | `invoice.payment_failed` | Draft a payment-failure recovery email |
| Stripe | `customer.subscription.deleted` | Draft a churn outreach |
| SendGrid | `bounce`, `spamreport` | Mark contact as undeliverable, exclude from future drafts |
| GitHub | `issue.opened` | Route to engineering Autopilot |
| Calendar | `event.created` | Draft a pre-meeting briefing |
| Twilio | inbound SMS | Draft a reply suggestion to the assigned rep |
## Configuring credentials
Credentials are stored at the org level, not per-app. To add a Slack workspace, a Stripe key, or a Twilio account, the org admin connects it once. All apps in the org can use the connected services through the tool registry.
```text theme={null}
Connect our Slack workspace so agents in the
sales app can post to #sales-ops.
```
```text theme={null}
Add the Stripe production key for the
billing app's invoice playbook.
```
Credentials never appear in the [action log](/autopilot/agent-action-log). They're referenced by name (e.g. `secrets.stripe_key`); the runtime resolves them at call time and never logs the resolved value.
## Allow-lists for outbound recipients
For external messaging tools (`send_email`, `send_slack` to external workspaces, `send_sms`), Connect supports allow-lists at the org level:
| Allow-list | What it does |
| --------------------------- | --------------------------------------------------- |
| Allowed email domains | Drafts to other domains are blocked at send time |
| Allowed phone country codes | Drafts to other countries are blocked at send time |
| Allowed Slack workspaces | Drafts to other workspaces are blocked at send time |
| `do_not_contact` collection | A list of recipients excluded regardless of domain |
The allow-list is applied **after** the draft is approved but **before** the underlying tool runs. A user can approve a draft and still see it blocked if the recipient isn't allowed.
## Best practices
Inbound webhooks without signature verification are an attack surface. Configure the secret on the source side and the runtime will reject anything unsigned.
A new sales agent can email `acmecorp.com` and `gainable.dev`. After a clean approval history, expand. Loud allow-lists invite mistakes.
Every `call_external` is a system the runtime can't reason about. Prefer a first-class tool when one exists. If you find yourself using `call_external` for the same target repeatedly, that target is a candidate for promotion.
Capture a real payload from the source, then replay it through [Simulate on last 30 days](/autopilot/playbooks). It's the safest way to verify your filter and steps.
## Learn more
The fixed registry, including outbound tools
Webhook trigger configuration
Default tiers per outbound channel
Inbound data ingestion (different from action and event flow)
# Inbox
Source: https://docs.gainable.dev/autopilot/inbox
Where Autopilot drafts land for approval. Three renderings: full view, ambient strip, dashboard widget
## What is the inbox?
The inbox is where [Gaia Autopilot](/autopilot/overview) becomes visible. It's where drafts land, the activity feed for what's run, the roster of agents in the app, and the editor for [playbooks](/autopilot/playbooks).
Every Gainable app gets an Autopilot inbox. There's nothing to install. As soon as the autopilot phase of the build runs, it appears in the app.
The split between Copilot and Autopilot mirrors the split between asking and acting. Copilot is the chat panel for "ask me anything." The inbox is the panel for "here's what I did, here's what I want to do, what should I send?"
## Three renderings
The inbox shows up in three places, each tuned for a different moment in the user's day.
| Rendering | Where it lives | Best for |
| -------------------- | ----------------------------------------------- | --------------------------------------- |
| **Full view** | The `/autopilot` route inside the app | Dedicated review sessions, inbox triage |
| **Ambient strip** | A pill in the app's chrome (top bar) | Awareness without context-switching |
| **Dashboard widget** | A drop-in widget alongside Chart, Kanban, Table | Mixed-use dashboards |
A single agent's drafts and activity show up in all three, scoped appropriately.
## Full view
The `/autopilot` route is the main UI. It has four panels:
### Inbox
The list of drafts waiting for review. For each draft:
* The originating playbook
* The objective it's working toward
* The full reasoning chain (which trigger, which records, why this draft)
* The proposed action (the email body, the Slack message, the record update)
* Approve, edit, skip, and "unsubscribe from this class" buttons
### Activity feed
A reverse-chronological log of what's run. Both auto-tier actions and approved/skipped drafts appear here. Each entry links to the corresponding [action log](/autopilot/agent-action-log) row.
### Agent roster
The agents configured in this app. For each agent:
* Its objectives
* Its playbooks
* Approval rate (used for [graduation](/autopilot/risk-tiers))
* Last run time
* Status: active, paused, error
### Playbook editor
The editor for trigger, steps, and guardrails. See [playbooks](/autopilot/playbooks) for the editor details.
## Ambient strip
The ambient strip is a small element in the app's chrome. It shows:
* A count of drafts in the user's inbox
* A pulse when a new draft arrives
* A click target that opens the inbox panel without leaving the current page
The strip is designed to be non-intrusive. It doesn't pop up modals; it doesn't interrupt typing. It tells the user "there's something to look at" and gets out of the way.
## Dashboard widget
You can drop an Autopilot widget onto any dashboard, alongside KPI cards, charts, kanban boards, and tables. The widget can be scoped:
* **Inbox.** This user's pending drafts.
* **Recent activity.** Last N actions, with quick access to detail.
* **Specific objective.** Just the work tied to one objective ("Stalled deals" only).
* **Specific playbook.** Just one playbook's drafts and activity.
```text theme={null}
Add an Autopilot widget to the sales dashboard
showing recent stalled-deal drafts.
```
```text theme={null}
Put an Autopilot inbox widget at the top of the
home page so users see pending drafts on login.
```
## Personal vs app-wide
The inbox is scoped automatically based on the agent's [scope](/autopilot/scopes):
* A **personal-scope** agent's drafts only appear in its owner's inbox.
* An **app-wide** agent's drafts appear in the inbox of whichever user is the configured owner of each draft (e.g. `deal.owner`).
Users never see drafts from other users' personal agents. They never see drafts they aren't the configured owner of.
## What the inbox is not
The inbox is not the [Copilot](/copilots/overview). The Copilot is conversational; the user types, the Copilot answers. The inbox is the proactive surface; agents act, the user reviews.
You can have both on the same page. They serve different moments.
| Copilot | Autopilot inbox |
| ---------------------------------------- | ------------------------------------------- |
| User initiates | Agent initiates |
| Synchronous chat | Asynchronous inbox |
| Reactive | Proactive |
| Powered by [Copilot](/copilots/overview) | Powered by [Autopilot](/autopilot/overview) |
## Adding the inbox to a page
The full view is always at `/autopilot`. The ambient strip is part of the app chrome and on by default. The widget you add explicitly:
```text theme={null}
Add an Autopilot inbox widget to the deals dashboard.
```
```text theme={null}
Put the Autopilot activity feed on the home page,
limited to the last 10 entries.
```
## Best practices
A widget on the dashboard a user opens 20 times a day beats a route they have to remember to visit.
Skeptical users approve faster when they can see the agent's history. The activity feed is the single best place to send them.
If a playbook is producing drafts that don't feel right, pause it from the agent roster instead of deleting it. The history stays. You can re-enable with one click.
For users who only want to know about high-priority drafts, configure the ambient strip to count only drafts from specific objectives.
## Learn more
What Gaia Autopilot is
The editor inside the inbox
How approve, edit, skip translates to action
The full audit trail
The conversational counterpart
# Objectives
Source: https://docs.gainable.dev/autopilot/objectives
What an agent is trying to maintain or move forward
## What is an objective?
An **objective** is the goal an agent works toward. It's the "why" behind every playbook the agent runs. Examples:
* "Every claim resolved within 14 days."
* "No deal sits in a single stage for more than 21 days."
* "Inventory above the configured reorder point at all times."
* "Every sales rep gets a daily briefing of their pipeline by 8 AM."
Objectives are not free-form rules. Each one is a measurable target tied to a collection, a field, and a threshold. That's what makes them enforceable by an agent rather than a vague aspiration.
## How Gaia infers objectives
When you finish the [data and UI phases](/concepts/how-it-works) of a build, the **autonomy** phase kicks in. Gaia reads:
* **Your schema.** Field names, enum values, dates, foreign keys, status fields.
* **Your views.** What you've put on dashboards, kanban boards, and tables.
* **Your seed data.** Volume, distribution, recency.
* **Your prompt history.** The intent behind the app.
From these signals it proposes a starting set of objectives. A CRM with a `stage` enum and a `close_date` field gets stalled-deal objectives. A support app with a `status` field and `created_at` gets SLA objectives. An inventory app with a `quantity` field and a `reorder_point` field gets stock-level objectives.
You always see the objectives before they go live. The autonomy contract is reviewable, editable, and disablable. Nothing runs until you sign off.
## Anatomy of an objective
Each objective has the same shape:
| Field | What it is | Example |
| -------------- | -------------------------------------- | -------------------------------------- |
| **Name** | Short label for humans | "Stalled deal" |
| **Collection** | The data model the objective watches | `deals` |
| **Measure** | What's being measured | Days since `stage_changed_at` |
| **Threshold** | When the objective is at risk | More than 14 days |
| **Filter** | Which records the objective applies to | `amount > 5000 AND status != "closed"` |
| **Owner** | Who the resulting drafts go to | `deal.owner` |
| **Risk tier** | How the objective acts | Draft-and-approve |
## Editing objectives
Every objective is editable through follow-up prompts or the Autopilot UI:
```text theme={null}
Change the stalled-deal threshold from 14 days to 21 days.
```
```text theme={null}
Only apply the stalled-deal objective to deals over $10,000.
```
```text theme={null}
Disable the inventory low-stock objective for the
"discontinued" product line.
```
## Adding objectives manually
You're not limited to inferred objectives. Add new ones in natural language:
```text theme={null}
Add an objective: every new contact created in HubSpot
gets a welcome email drafted within 24 hours, sent
to the account owner's Autopilot inbox.
```
```text theme={null}
Add an objective: any invoice over 30 days past due
gets a draft escalation to the controller.
```
## When objectives fire
An objective produces work when its threshold is crossed. The trigger that detects the crossing depends on the objective:
* A **time-based** objective ("14 days idle") uses a [schedule trigger](/autopilot/triggers).
* A **state-change** objective ("stage moves to lost") uses a [data change trigger](/autopilot/triggers).
* An **inbound** objective ("new ticket from VIP") uses a [webhook trigger](/autopilot/triggers).
* An **on-demand** objective ("draft me a recap") uses a [user-triggered](/autopilot/triggers) button.
The objective stays the same. The trigger reflects how the world tells the agent the objective needs attention.
## Example: a stalled-deal objective end to end
```yaml theme={null}
name: Stalled deal
collection: deals
measure: days_since_stage_changed_at
threshold: ">= 14"
filter: "amount > 5000 AND status NOT IN ('won','lost')"
owner: deal.owner
risk_tier: draft_and_approve
playbook: nudge_with_email
```
When this objective fires:
1. The runtime queries `deals` for matching records once a day.
2. For each match, the `nudge_with_email` [playbook](/autopilot/playbooks) runs.
3. The playbook drafts a follow-up email referencing the deal's last activity.
4. The draft lands in the deal owner's [Autopilot inbox](/autopilot/inbox) with full reasoning attached.
5. The owner approves, edits, or skips. Nothing leaves until they do.
## Best practices
A high-stakes objective ("escalate every late invoice") creates more drafts than the team can review. Start with the top 10% of cases by amount or risk. Widen once approval rates settle.
`deal.owner` is more useful than "the sales team." Personal Autopilot inboxes are more actionable than a shared queue.
Disabled objectives keep their history and can be turned on with one click. Deleting loses the configuration.
The [agent action log](/autopilot/agent-action-log) shows what fired, what got drafted, what got approved, and what got skipped. Skipped drafts are the strongest signal that an objective needs editing.
## Learn more
The trigger, steps, and guardrails an objective runs
The four ways a playbook starts
How drafts become actions
The inbox where drafts land
# Gaia Autopilot
Source: https://docs.gainable.dev/autopilot/overview
The autonomous runtime that watches your data, drafts work, and lands it in your inbox for approval
## What is Gaia Autopilot?
Gaia Autopilot is autonomous. It runs on its own. It watches data against objectives Gainable infers from your app, drafts work when something needs attention, and lands that work in your inbox for you to approve, edit, or skip.
Internally, Autopilot is a fleet of small, scope-bounded agents (one per objective). The umbrella, the inbox, the activity feed, and the playbook editor are all Autopilot.
If [Gaia Copilot](/copilots/overview) is "the user asks, the Copilot answers," Autopilot is "work shows up before anyone asks." Two halves of the same intelligence layer. The Copilot is reactive. Autopilot is proactive.
**Apps that work for you, not apps you work with.** Autopilot does the thinking in the background. You stay in control through the inbox. Draft-and-approve is the default, so nothing leaves the building until you say so.
## Test for which one applies
> Does the user have to ask first?
>
> * **Yes** → [Gaia Copilot](/copilots/overview)
> * **No** (work shows up before they ask) → Gaia Autopilot
## What Autopilot does
Subscribes to change streams, schedules, webhooks, and explicit clicks. Reacts when something matches.
Inferred goals like "every claim resolved in 14 days" or "follow up on stalled deals."
Composes emails, Slack messages, status updates, summaries, and SLA escalations.
Drafts arrive in the [Autopilot inbox](/autopilot/inbox) with full reasoning, ready for one-click approve, edit, or skip.
## How Autopilot comes to life
Every Gainable app moves through a five-phase build contract:
```
data → derives → seed → ui → autopilot → built
```
The **autopilot** phase is where agents are inferred from your schema and intent. Gainable reads your data model, looks at how the app is shaped, and proposes objectives, playbooks, tools, and risk tiers. You review the autonomy contract, edit it, and ship.
Datasets and data models give Gainable the schema to work with.
Tables, forms, dashboards, and the Autopilot inbox are added to the app.
Gaia proposes objectives ("keep claims moving"), playbooks ("nudge after 7 days idle"), tools ("send\_email"), and risk tiers ("draft, don't auto-send").
Edit anything you want. Disable any objective. Tighten the risk posture.
The runtime starts watching change streams, schedules, and webhooks. Drafts begin landing in the inbox.
## Two scopes
Each agent runs in one of two scopes. The difference matters for permissions and visibility.
| Scope | Runs as | Visibility | Use for |
| ------------ | --------------- | -------------------------------------------- | ----------------------------------------------------------- |
| **App-wide** | The org | Drafts visible to anyone with the right role | Stalled-deal chasers, SLA enforcers, digest publishers |
| **Personal** | A specific user | Drafts visible only to that user, RBAC-bound | Daily briefings, personal follow-ups, my-pipeline summaries |
See [scopes](/autopilot/scopes) for the full boundary rules.
## What Autopilot does *not* do
Autopilot is not a magic wand. By default it:
* Doesn't send anything to a customer without approval
* Doesn't take destructive write actions without explicit graduation
* Doesn't run outside the risk tier you signed off on
* Doesn't see data the configured scope doesn't allow
All of this is enforced by the [risk tiers](/autopilot/risk-tiers) and [tool registry](/autopilot/tools), not by hope.
## Autopilot at a glance
| Concept | What it is |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [Objectives](/autopilot/objectives) | What an agent maintains, e.g. "every claim resolved in 14 days" |
| [Playbooks](/autopilot/playbooks) | The trigger → steps → guardrails recipe inside an agent |
| [Triggers](/autopilot/triggers) | The four ways a playbook starts: schedule, data change, webhook, user-triggered |
| [Tools](/autopilot/tools) | The fixed registry agents call: `query_collection`, `send_email`, `draft_for_approval`, and so on |
| [Risk tiers](/autopilot/risk-tiers) | Trust posture: draft-and-approve by default, graduation, undo windows |
| [Inbox](/autopilot/inbox) | The user-facing inbox, ambient strip, and dashboard widget |
| [Action log](/autopilot/agent-action-log) | The audit trail. Every trigger, tool call, and outcome is recorded |
## Prompt examples
You can describe Autopilot agents in natural language:
```text theme={null}
Add a stalled-deal chaser. Watch the deals collection.
If a deal hasn't moved stage in 14 days and the amount is
over $5,000, draft a follow-up email to the contact and
land it in the deal owner's Autopilot inbox.
```
```text theme={null}
Add a daily briefing for each sales rep. At 8 AM in their
timezone, summarize: deals closing this week, deals with no
activity in 7+ days, top 3 deals by amount. Personal scope,
draft to their inbox.
```
```text theme={null}
Add an SLA enforcer for tickets. If a ticket has been "open"
for more than 24 hours with no response, escalate to the
team lead and draft a status update for the customer.
```
## Learn more
What agents are trying to maintain
Trigger, steps, and guardrails
Schedule, data change, webhook, user-triggered
The fixed tool registry
Draft-and-approve by default
Where drafts land
Worked examples of common playbooks
Looking for the conversational side?
# Playbooks
Source: https://docs.gainable.dev/autopilot/playbooks
The trigger, steps, and guardrails recipe inside every agent
## What is a playbook?
A **playbook** is the recipe an agent runs when an [objective](/autopilot/objectives) needs attention. It has three parts:
1. **A trigger.** What starts the playbook. One of [schedule, data change, webhook, or user-triggered](/autopilot/triggers).
2. **Steps.** A sequence of [tool calls](/autopilot/tools), each one observed by the runtime and recorded in the [action log](/autopilot/agent-action-log).
3. **Guardrails.** Constraints that bound the playbook: rate limits, scopes, risk tier, allowed recipients, max recursion.
Think of an objective as the "why" and the playbook as the "how."
## The shape of a playbook
```yaml theme={null}
name: Nudge stalled deals
trigger:
type: schedule
cron: "0 9 * * 1-5"
steps:
- tool: query_collection
collection: deals
filter: "stage != 'closed' AND days_since_stage_changed_at >= 14"
- tool: query_collection
collection: contacts
filter: "id IN {{ step1.deals[*].contact_id }}"
- tool: draft_for_approval
template: stalled_deal_followup
recipient: "{{ step2.contact.email }}"
owner: "{{ step1.deal.owner }}"
guardrails:
scope: app_wide
risk_tier: draft_and_approve
rate_limit_per_user: "10/day"
exclude_recipients_in: [unsubscribes, do_not_contact]
```
This pattern, **trigger → steps → guardrails**, is the same for every playbook in every Gainable app. Once you understand it, you understand all of them.
## The playbook editor
Playbooks live in the [Autopilot](/autopilot/inbox) UI. The editor shows:
* **Trigger panel.** Pick the trigger type and configure it.
* **Step list.** Drag steps. Each step is a [tool](/autopilot/tools) call. Inputs can reference previous step outputs.
* **Guardrails panel.** Risk tier, rate limits, scopes, recipient exclusions.
* **Test panel.** Run the playbook against test data without lighting up real recipients.
You don't have to use the editor. Almost everything you can configure in it can be described in natural language during a build prompt. The editor is for fine-tuning after the fact.
## "Simulate on last 30 days"
Before turning a playbook live, run **Simulate on last 30 days**. The runtime replays your real data through the playbook against the last 30 days of activity and shows:
* How many times the trigger would have fired
* How many drafts would have been produced
* Per draft: the recipient, the message, the reasoning chain, the tool calls
* An estimate of approval workload (drafts per day, per user)
**Simulate is the safety net.** It's the difference between "the playbook looks reasonable" and "the playbook would have produced 240 emails to one customer last Tuesday." Always simulate before going live.
The simulation runs in a sandbox. It does not call `send_email`, `send_slack`, `send_sms`, or `call_external` for real. It produces drafts you can read but never delivers them.
## Step references
Steps can reference each other's outputs. The reference syntax is `{{ stepN.field }}` or `{{ stepN.collection[*].field }}` for arrays.
```yaml theme={null}
steps:
- tool: query_collection
collection: deals
filter: "amount > 10000 AND stage = 'proposal'"
limit: 50
- tool: query_collection
collection: contacts
filter: "id IN {{ step1.deals[*].contact_id }}"
- tool: draft_for_approval
template: proposal_followup
recipient: "{{ step2.contact.email }}"
context:
deal_name: "{{ step1.deal.name }}"
deal_amount: "{{ step1.deal.amount }}"
```
## Guardrails
Guardrails bound what a playbook can do regardless of its steps. They are the policy layer that exists outside the agent's reasoning.
| Guardrail | What it does |
| ---------------------------- | ---------------------------------------------------------------------------------------------- |
| **Risk tier** | One of `draft_and_approve`, `auto_with_undo`, `auto`. See [risk tiers](/autopilot/risk-tiers). |
| **Rate limit per user** | Max drafts a single user can be the owner of in a window |
| **Rate limit per recipient** | Max drafts that can target a single recipient in a window |
| **Allowed recipients** | Whitelist of domains or addresses |
| **Excluded recipients** | Reference to a `do_not_contact` collection |
| **Scope** | `app_wide` or `personal` ([scopes](/autopilot/scopes)) |
| **Max steps** | Hard cap on tool calls per playbook run |
| **Max recursion** | Prevents a playbook from triggering itself unbounded |
## Common playbook shapes
### Watch and notify
```yaml theme={null}
trigger:
type: data_change
collection: tickets
on: [create]
where: "priority = 'p0'"
steps:
- tool: notify_user
recipient: "on_call_user"
message: "P0 ticket: {{ trigger.record.title }}"
```
### Watch and draft
```yaml theme={null}
trigger:
type: data_change
collection: deals
on: [update]
where: "stage = 'lost'"
steps:
- tool: draft_for_approval
template: lost_deal_postmortem
owner: "{{ trigger.record.owner }}"
```
### Schedule and digest
```yaml theme={null}
trigger:
type: schedule
cron: "0 8 * * 1-5"
steps:
- tool: query_collection
collection: deals
filter: "owner = {{ context.user_id }}"
- tool: draft_for_approval
template: daily_briefing
owner: "{{ context.user_id }}"
```
### Inbound and route
```yaml theme={null}
trigger:
type: webhook
source: stripe
event: invoice.payment_failed
steps:
- tool: query_collection
collection: customers
filter: "stripe_id = {{ trigger.body.customer }}"
- tool: draft_for_approval
template: payment_failed
recipient: "{{ step1.customer.email }}"
owner: "{{ step1.customer.account_owner }}"
```
## Editing playbooks
Edit through chat or the editor:
```text theme={null}
Update the stalled-deal playbook to also cc the
sales manager when the deal is over $50,000.
```
```text theme={null}
Add a guardrail to the daily-briefing playbook:
max one draft per user per day.
```
```text theme={null}
Change the SLA-enforcer playbook trigger from
every hour to every 15 minutes.
```
## Best practices
A 30-day simulation catches load problems, recipient explosions, and bad filters before they reach real users.
"Nudge stalled deals" is a clear playbook. "Manage the sales pipeline" is a bundle of five playbooks pretending to be one.
The default for outbound work is `draft_for_approval` for a reason. Graduate to `auto_with_undo` only after a clean approval history.
A `do_not_contact` collection lets you opt specific records out without breaking the whole playbook for everyone else.
## Learn more
Schedule, data change, webhook, user-triggered
The fixed registry of tool calls
Draft-and-approve, auto-with-undo, auto
Worked examples of common playbooks
# Recipes
Source: https://docs.gainable.dev/autopilot/recipes
Worked examples of common Autopilot agent playbooks
## How to use these recipes
Each recipe is a complete, runnable [playbook](/autopilot/playbooks) you can describe in natural language during a build prompt. Read the recipe, copy the prompt, adapt the field names to your data model, and ship.
Every recipe includes:
* The objective the playbook serves
* The trigger and tool calls
* The default [risk tier](/autopilot/risk-tiers) and recommended graduation path
* A natural-language prompt you can paste into the build chat
## 1. Stalled-deal chaser (sales)
**Objective.** No deal sits in a single stage for more than 14 days without a follow-up attempt.
**Shape.**
```yaml theme={null}
name: Stalled deal chaser
scope: app_wide
trigger:
type: schedule
cron: "0 9 * * 1-5"
steps:
- tool: query_collection
collection: deals
filter: "stage NOT IN ('won','lost') AND days_since_stage_changed_at >= 14 AND amount > 5000"
- tool: query_collection
collection: contacts
filter: "id IN {{ step1.deals[*].contact_id }}"
- tool: draft_for_approval
underlying: send_email
template: stalled_deal_followup
owner: "{{ deal.owner }}"
payload:
to: "{{ step2.contact.email }}"
subject: "Following up on {{ step1.deal.name }}"
guardrails:
risk_tier: draft_and_approve
rate_limit_per_user: "10/day"
rate_limit_per_recipient: "1/2_weeks"
```
**Prompt.**
```text theme={null}
Add a stalled-deal chaser to the sales app. Watch the
deals collection. Every weekday at 9 AM, find deals over
$5,000 that haven't moved stage in 14 days. For each,
draft a follow-up email to the contact and route it to
the deal owner's Autopilot inbox. Cap at 10 drafts per
owner per day, 1 per recipient per 2 weeks.
```
**Graduation.** Stay in `draft_and_approve` until the action log shows a 90%+ approval rate over 30+ days. Internal-only graduation paths don't apply (these are external recipients).
***
## 2. SLA enforcer (operations)
**Objective.** No customer ticket goes more than 24 hours without first response.
**Shape.**
```yaml theme={null}
name: SLA enforcer
scope: app_wide
trigger:
type: schedule
cron: "*/15 * * * *"
steps:
- tool: query_collection
collection: tickets
filter: "status = 'open' AND first_response_at IS NULL AND age_hours >= 24"
- tool: notify_user
user_id: "{{ ticket.assignee }}"
title: "SLA breach: {{ ticket.title }}"
link: "/tickets/{{ ticket.id }}"
- tool: draft_for_approval
underlying: send_email
template: sla_breach_customer_update
owner: "{{ ticket.team_lead }}"
payload:
to: "{{ ticket.customer_email }}"
guardrails:
risk_tier: draft_and_approve
rate_limit_per_user: "20/day"
```
**Prompt.**
```text theme={null}
Add an SLA enforcer to the support app. Every 15 minutes,
find open tickets older than 24 hours with no first
response. Notify the assignee in-app, and draft a customer
status update for the team lead's Autopilot inbox.
```
**Graduation.** The `notify_user` step is already auto-tier (internal). The customer-facing email stays in draft-and-approve.
***
## 3. Inventory watchdog (e-commerce)
**Objective.** No SKU drops below its reorder point without a draft purchase order.
**Shape.**
```yaml theme={null}
name: Inventory watchdog
scope: app_wide
trigger:
type: data_change
collection: products
on: [update]
where: "changed('quantity_on_hand') AND new.quantity_on_hand <= reorder_point"
steps:
- tool: query_collection
collection: suppliers
filter: "id = {{ trigger.record.preferred_supplier_id }}"
- tool: draft_for_approval
underlying: send_email
template: reorder_request
owner: "{{ ops_team_lead }}"
payload:
to: "{{ step1.supplier.contact_email }}"
subject: "Reorder request: {{ trigger.record.sku }}"
context:
sku: "{{ trigger.record.sku }}"
quantity: "{{ trigger.record.reorder_quantity }}"
guardrails:
risk_tier: draft_and_approve
rate_limit_per_recipient: "1/day"
```
**Prompt.**
```text theme={null}
Add an inventory watchdog to the warehouse app. Watch the
products collection. When a product's quantity drops to or
below its reorder point, look up its preferred supplier and
draft a reorder request email to ops. Cap at one draft per
supplier per day.
```
**Graduation.** Internal-only variants (POs to a procurement queue rather than directly to a supplier) can graduate to `auto_with_undo`.
***
## 4. Daily briefing (personal, every role)
**Objective.** Every user starts the day with a summary of what's on their plate.
**Shape.**
```yaml theme={null}
name: Daily briefing
scope: personal
trigger:
type: schedule
cron: "0 8 * * 1-5"
timezone: "{{ user.timezone }}"
steps:
- tool: query_collection
collection: deals
filter: "owner = {{ user.id }} AND close_date_within = '7_days'"
sort: "amount desc"
limit: 5
- tool: query_collection
collection: tasks
filter: "assignee = {{ user.id }} AND status != 'done' AND due_date <= today + 1"
- tool: draft_for_approval
underlying: notify_user
template: daily_briefing
owner: "{{ user.id }}"
payload:
title: "Your day at a glance"
sections:
- "Top deals closing this week"
- "Tasks due today and tomorrow"
guardrails:
risk_tier: draft_and_approve
rate_limit_per_user: "1/day"
```
**Prompt.**
```text theme={null}
Add a personal daily briefing for each user. At 8 AM in
their timezone on weekdays, summarize: top 5 deals closing
this week (by amount), tasks due today and tomorrow. Land
the draft in the user's Autopilot inbox. One per day max.
```
**Graduation.** A daily briefing is a strong candidate for `auto_with_undo` after a trial period. It's personal, internal, and reversible (notification can be dismissed).
***
## 5. Anomaly detector (finance / payouts)
**Objective.** Any payout that's an outlier compared to history gets a human eye before it processes.
**Shape.**
```yaml theme={null}
name: Payout anomaly detector
scope: app_wide
trigger:
type: data_change
collection: payouts
on: [create]
where: "amount > 50000 OR amount > 5 * customer.avg_payout_last_90_days"
steps:
- tool: query_collection
collection: customers
filter: "id = {{ trigger.record.customer_id }}"
- tool: ask_human
user_id: "{{ finance_lead }}"
question: "Approve payout of {{ trigger.record.amount }} to {{ step1.customer.name }}? (5x normal)"
options: [approve, hold_for_review, deny]
timeout: "4h"
guardrails:
risk_tier: draft_and_approve
```
**Prompt.**
```text theme={null}
Add a payout anomaly detector to the finance app. When a
new payout is created above $50,000 or 5x the customer's
90-day average, ask the finance lead in Autopilot to
approve, hold, or deny. Default to hold if no answer in 4 hours.
```
**Graduation.** This stays in human-in-the-loop forever. Anomaly detection is exactly the case where you don't graduate.
***
## 6. Digest publisher (org-wide)
**Objective.** The leadership team gets a weekly summary of pipeline, SLA, and ops health without anyone having to assemble it.
**Shape.**
```yaml theme={null}
name: Weekly leadership digest
scope: app_wide
trigger:
type: schedule
cron: "0 16 * * 5" # Friday 4 PM
steps:
- tool: query_collection
collection: deals
filter: "stage_changed_at > now - 7_days"
- tool: query_collection
collection: tickets
filter: "created_at > now - 7_days OR resolved_at > now - 7_days"
- tool: query_collection
collection: AgentAction
filter: "created_at > now - 7_days"
- tool: draft_for_approval
underlying: send_slack
template: leadership_digest
owner: "{{ chief_of_staff }}"
payload:
channel: "#leadership"
blocks: "{{ rendered }}"
guardrails:
risk_tier: draft_and_approve
rate_limit_per_user: "1/week"
```
**Prompt.**
```text theme={null}
Every Friday at 4 PM, draft a weekly leadership digest
combining pipeline movement, ticket throughput, and agent
activity from the past 7 days. Route the draft to the chief
of staff's Autopilot inbox. On approval, post to #leadership.
```
**Graduation.** Once the chief of staff has approved 4+ weeks unchanged, this is a strong candidate for `auto_with_undo` to Slack.
***
## Adapting recipes to your data
Field names like `deal.owner`, `ticket.assignee`, and `customer.avg_payout_last_90_days` are placeholders. When you describe the playbook in a build prompt, Gainable's [build agents](/concepts/agents) read your actual schema and rewire the references.
If a recipe references a field your schema doesn't have (e.g. `avg_payout_last_90_days`), the autopilot phase will offer to add it as a derived field during the build. You can accept, edit, or skip.
## Patterns you'll see across recipes
* **`query_collection` first, then `draft_for_approval`.** Almost every recipe reads relevant context before drafting. The action log captures both, so reasoning is auditable.
* **Personal scope binds timezone to the user.** Personal recipes use `{{ user.timezone }}` so 8 AM means 8 AM where the user lives.
* **Rate limits are not optional.** Every recipe has at least one. They're the difference between "the agent helps" and "the agent floods."
* **Graduation paths are explicit.** Each recipe states whether and when graduation is appropriate.
## Best practices
Pick the recipe that solves the loudest problem your team has today. Get it through approval, edit, and graduation. Then add the next one.
Replace placeholder field names with yours. Adjust thresholds to your data's volume. The shape stays the same; the values are yours.
[Simulate on last 30 days](/autopilot/playbooks) before going live. Recipes that look reasonable in a doc can produce surprising volume against real data.
Approval rate, skip reasons, and rate-limited counts tell you whether the playbook is tuned correctly. Tune in week one. Graduate in month one.
## Learn more
The shape every recipe follows
What each step in a recipe calls
How recipes graduate
Where Slack, email, and Stripe payouts connect
# Risk tiers
Source: https://docs.gainable.dev/autopilot/risk-tiers
How agents earn trust. Draft-and-approve by default, graduation, undo, rate limits
## The trust model
Gaia Autopilot is autonomous. Autonomy without guardrails is reckless, so every agent action is bounded by a **risk tier**. The tier governs whether an action runs, whether it pauses for approval, whether it can be undone, and how often it's allowed to run.
The default for outbound work is **draft-and-approve**. Nothing goes to a customer without a human reviewing it. Agents earn higher autonomy by demonstrating, in the [action log](/autopilot/agent-action-log), that their drafts are consistently approved as written.
## The three tiers
| Tier | Behavior | Default for |
| ------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `draft_and_approve` | Drafts are produced and land in [Autopilot](/autopilot/inbox). Nothing executes until a human approves. | All outbound communication tools |
| `auto_with_undo` | Action executes immediately. Has a configurable undo window during which the user can reverse it. | Internal updates, low-blast-radius changes |
| `auto` | Action executes immediately. No human review. Cannot be reversed by the user. | Reads, internal notifications, action-log writes |
You'll rarely choose tiers manually. Each [tool](/autopilot/tools) has a default tier. Each playbook can constrain tiers further but never relax them.
## Graduation
Tiers aren't immutable. A playbook can graduate from `draft_and_approve` to `auto_with_undo` (and rarely to `auto`) when:
* It has a long enough history of drafts being approved as written
* The recipient class is internal or trusted (org employees, internal channels)
* The org explicitly opts in
The runtime tracks **approval rate** per playbook, per tool, and per recipient class. The Autopilot UI shows when graduation is available and what the recommended next tier is.
**Graduation is opt-in.** Gainable never silently changes a risk tier. The recommendation appears in Autopilot. The org decides whether to act on it.
## Undo windows
`auto_with_undo` actions are reversible. The undo window varies by tool:
| Tool | Undo window | What undo does |
| ---------------- | --------------------------------- | ------------------------------------------------------- |
| `update_records` | 24 hours | Restores prior field values |
| `notify_user` | 5 minutes | Removes the notification before it's read |
| `create_task` | 24 hours | Marks the task as withdrawn |
| `send_email` | Not eligible for `auto_with_undo` | (always `draft_and_approve` unless graduated to `auto`) |
| `send_slack` | 5 minutes | Deletes the message |
| `send_sms` | Not undoable | (always `draft_and_approve`) |
| `call_external` | Not undoable | (always `draft_and_approve`) |
The undo window is enforced by the runtime. Once the window closes, the action is permanent.
## Rate limits
Every playbook has rate limits. The defaults are conservative; the org can tighten or loosen them.
| Limit | Default | Why |
| ---------------------------------- | ------- | ------------------------------------------------- |
| Drafts per user per day | 25 | Keeps an individual's Autopilot inbox manageable |
| Drafts per recipient per week | 3 | Protects external recipients from agent floods |
| Auto actions per playbook per hour | 100 | Bounds blast radius if a playbook fires too often |
| Tool calls per playbook run | 50 | Hard cap. Prevents runaway loops. |
Rate limits are checked **before** the tool runs. A blocked call writes to the [action log](/autopilot/agent-action-log) with a `rate_limited` outcome.
## Per-user caps
Personal-scope playbooks (see [scopes](/autopilot/scopes)) inherit per-user caps. Two examples:
* A user with 50 deals can't generate 50 outbound drafts in a day from a single playbook unless the cap is raised.
* A user can't run a `call_external` tool more than 10 times an hour, even on-demand.
Per-user caps protect the org from a single user inadvertently turning an agent into a denial-of-service.
## How a draft becomes an action
The lifecycle of a draft-and-approve outbound:
Schedule, data change, webhook, or user click.
Steps execute. The final outbound step is wrapped in `draft_for_approval`.
The configured owner sees it in their inbox. The action log records the draft creation.
Approve, edit, skip, or unsubscribe future drafts in this class.
`send_email`, `send_slack`, etc. Action log records the execution.
The action log records the skip with the reason if provided.
## How auto-with-undo runs
The lifecycle of an auto-with-undo action:
Same as above.
The action takes effect.
The user sees what happened with an "Undo" button.
Configurable per tool. 5 minutes for messaging, 24 hours for record updates.
Records restored, messages deleted, notifications removed.
No further reversal. The action log shows the final outcome.
## Configuring tiers
Risk tiers are part of the [playbook](/autopilot/playbooks) guardrails:
```yaml theme={null}
guardrails:
risk_tier: draft_and_approve
rate_limit_per_user: "10/day"
rate_limit_per_recipient: "1/week"
undo_window: "24h"
```
You can describe risk posture in natural language too:
```text theme={null}
For the stalled-deal playbook, keep risk tier at
draft-and-approve. The deals manager wants to review
every outgoing nudge before it sends.
```
```text theme={null}
Graduate the daily-briefing playbook to auto-with-undo
with a 5-minute window. It only writes to personal inboxes,
so the cost of a mistake is low.
```
## Best practices
Don't graduate a playbook to `auto_with_undo` because it would be more convenient. Graduate it because the action log shows users approve drafts unchanged at least 90% of the time.
When a playbook is producing too many drafts, tighten the trigger filter or rate limit before relaxing the risk tier.
Internal Slack? Graduation candidate. External customer email? Stay in draft-and-approve unless you have an explicit, opted-in customer commitment to automated communication.
A spike in `rate_limited` outcomes in the action log means the playbook is firing more often than expected. Investigate before raising the limit.
## Learn more
Default risk tier per tool
Where tiers are configured
Where drafts and undo surfaces live
The audit trail behind tier decisions
# Scopes
Source: https://docs.gainable.dev/autopilot/scopes
App-wide vs personal agents, and the boundary rules between them
## Two scopes
Every Autopilot agent runs in one of two scopes. The choice is permanent for the playbook (changing it means a new playbook) and it determines who sees the work, who approves it, and what data the agent reads.
| Scope | Runs as | Sees | Drafts go to |
| ------------ | --------------- | ----------------------------------------- | -------------------------------------------------- |
| **App-wide** | The org | All app data within configured guardrails | The owner field on each record (e.g. `deal.owner`) |
| **Personal** | A specific user | Only data the user has RBAC access to | That user's Autopilot inbox |
## App-wide agents
App-wide agents act on behalf of the org. They watch all relevant data, apply objectives at scale, and route drafts to whichever user is the configured owner of each record.
### Use for
* **Stalled-deal chasers.** One playbook, scoped to all deals. Drafts route to each deal's owner.
* **SLA enforcers.** One playbook, scoped to all tickets. Escalations go to the team lead and the assigned owner.
* **Inventory watchdogs.** One playbook for the whole catalog. Reorder drafts go to the operations owner.
* **Digest publishers.** One playbook that produces an org-wide digest sent to a channel or distribution list.
### Permissions
App-wide agents read every record their guardrails allow. The runtime enforces field-level scoping (no PII unless explicitly granted), tool-level scoping (no `send_email` unless allowed), and recipient-level scoping (no external email unless the recipient class is allowed).
### Visibility
Drafts and activity from app-wide agents appear in the [Autopilot](/autopilot/inbox) of the user who owns the underlying record. A stalled-deal draft for a deal owned by Sarah appears in Sarah's inbox, not in everyone else's.
## Personal agents
Personal agents act on behalf of a single user. They run inside that user's RBAC boundary. They draft only to the user. They see only what the user is allowed to see.
### Use for
* **Daily briefings.** "My pipeline this morning." Per-user, per-timezone.
* **Personal follow-ups.** "Remind me to follow up on these three deals next week."
* **My-queue summaries.** "Top 5 things on my plate today."
* **Anything that's about *me*, not *us*.**
### Permissions
A personal agent inherits its owner's permissions. If the user can't read a record, the agent can't either. If the user has read-only access to a collection, the agent can't write to it. The user is the upper bound on the agent's authority.
### Visibility
A personal agent's drafts appear *only* in its owner's Autopilot inbox. No one else can see them, including admins (except in the [action log](/autopilot/agent-action-log) for audit purposes).
## Choosing scope
| Question | Answer |
| -------------------------------------------------------------- | ----------------------------------------- |
| Should a manager review work for their team? | **App-wide**, scope drafts to the manager |
| Should each user see their own drafts and no one else's? | **Personal** |
| Does the work cross multiple users' records? | **App-wide** |
| Is this "for me" rather than "for the team"? | **Personal** |
| Is the data sensitive enough that only the user should see it? | **Personal** |
If two answers contradict, you probably have two playbooks pretending to be one. Split them.
## Boundary rules (non-negotiable)
These rules are enforced by the runtime, not by the playbook author.
1. **A personal agent never sees data its owner can't see.** RBAC is the floor.
2. **A personal agent never drafts to anyone but its owner.** Cross-user drafting is app-wide territory.
3. **A personal agent's outputs are private by default.** Activity surfaces in the owner's Autopilot, not the org-wide feed.
4. **An app-wide agent runs as the org, not as a user.** No "I'll just elevate myself" path.
5. **An app-wide agent honors record-level ownership for routing.** A draft about Sarah's deal goes to Sarah, not the whole sales team.
6. **External recipients are bounded by allow-lists.** Both scopes. Neither can email outside the configured allowed domains without explicit graduation.
7. **The action log is the source of truth for both scopes.** Personal agents log to a private slice; app-wide agents log to the org slice. Admins can audit; users can't read each other's logs.
## Mixed-scope playbooks
You can't have one playbook that's both app-wide and personal. You can have **two playbooks** that share a template:
* An app-wide stalled-deal playbook that routes drafts to deal owners
* A personal "my stalled deals" playbook each user can opt into for richer per-user reasoning
The [autonomy contract](/autopilot/overview) often proposes both. You can keep one, both, or neither.
## Examples
### App-wide example
```yaml theme={null}
name: SLA enforcer
scope: app_wide
trigger:
type: schedule
cron: "*/15 * * * *"
steps:
- tool: query_collection
collection: tickets
filter: "status = 'open' AND age_hours > 24"
- tool: draft_for_approval
template: sla_breach
owner: "{{ ticket.assignee }}"
guardrails:
rate_limit_per_user: "5/day"
```
### Personal example
```yaml theme={null}
name: Daily briefing
scope: personal
trigger:
type: schedule
cron: "0 8 * * 1-5"
timezone: "{{ user.timezone }}"
steps:
- tool: query_collection
collection: deals
filter: "owner = {{ user.id }}"
sort: "amount desc"
limit: 5
- tool: draft_for_approval
template: daily_briefing
owner: "{{ user.id }}"
guardrails:
rate_limit_per_user: "1/day"
```
## Best practices
If the playbook reasons about more than one user's records, app-wide is almost always the right scope.
Daily briefings, my-queue summaries, and on-demand drafts belong in personal scope.
Personal and app-wide agents have separate slices of the action log on purpose. Cross-scope reasoning is a sign you actually have two objectives.
[Simulate on last 30 days](/autopilot/playbooks) shows you exactly which records and which users would have been touched. Use it to verify the boundary is where you think it is.
## Learn more
What Autopilot agents are
Where scope is configured
Where drafts surface, scoped accordingly
The audit trail, sliced by scope
# Tools
Source: https://docs.gainable.dev/autopilot/tools
The fixed registry of actions Autopilot agents can take
## Why a fixed registry?
Every step in a [playbook](/autopilot/playbooks) is a tool call. The set of available tools is fixed and small. New tools don't appear because an agent decided they should. The registry is a closed vocabulary, the same way [triggers](/autopilot/triggers) are.
This matters for three reasons:
* **Auditable.** Every action in the [agent action log](/autopilot/agent-action-log) maps to a known tool with a known signature.
* **Predictable.** No tool can do something it wasn't designed to do.
* **Governable.** Each tool has a [risk tier](/autopilot/risk-tiers). The runtime enforces it.
If you've used MCP-style tool-use with the Anthropic SDK, the model is familiar. The difference is that here the registry is curated for internal-app autonomy, not general-purpose agency.
## The registry
| Tool | Reads | Writes | Default risk tier |
| -------------------- | -------- | ------------------- | --------------------------------- |
| `query_collection` | App data | No | Low |
| `update_records` | App data | App data | Medium |
| `send_email` | None | External | High (draft-and-approve) |
| `send_slack` | None | External | High (draft-and-approve) |
| `send_sms` | None | External | High (draft-and-approve) |
| `notify_user` | None | In-app notification | Low |
| `call_external` | None | External HTTP | High (draft-and-approve) |
| `ask_human` | None | Pauses playbook | Low |
| `create_task` | None | App data | Low |
| `draft_for_approval` | None | Autopilot inbox | Low (drafts always land in inbox) |
Each tool has a strict signature. A playbook calls a tool with typed arguments; the runtime validates them before the call runs.
***
### `query_collection`
Read-only, schema-aware queries against your app data.
```yaml theme={null}
- tool: query_collection
collection: deals
filter: "stage = 'proposal' AND amount > 10000"
sort: "amount desc"
limit: 50
fields: [id, name, amount, owner, contact_id]
```
**Use when:** You need to fetch records to feed a downstream step.
**Risk tier:** Low. Reads only. Honors agent [scopes](/autopilot/scopes).
***
### `update_records`
Write field values back to a collection.
```yaml theme={null}
- tool: update_records
collection: deals
filter: "id = {{ trigger.record.id }}"
set:
last_nudged_at: "{{ now }}"
nudge_count: "{{ record.nudge_count + 1 }}"
```
**Use when:** You need to mark records as processed, advance state, or annotate.
**Risk tier:** Medium. Writes to app data, no external surface. Bounded by guardrails (`max_records_per_call`, scope).
***
### `send_email`
Outbound email through the configured provider.
```yaml theme={null}
- tool: send_email
to: "{{ contact.email }}"
from: "sales@{{ org.domain }}"
subject: "Following up on {{ deal.name }}"
body: "{{ rendered_template }}"
template_id: stalled_deal_followup
```
**Use when:** You want the agent to email someone.
**Risk tier:** High. Defaults to `draft_for_approval`. Graduate to `auto_with_undo` only after a clean approval history. See [risk tiers](/autopilot/risk-tiers).
***
### `send_slack`
Outbound Slack message to a user, channel, or thread.
```yaml theme={null}
- tool: send_slack
channel: "#sales-ops"
text: "Pipeline summary for {{ today }}"
blocks: "{{ rendered_blocks }}"
```
**Use when:** You want the agent to post to Slack.
**Risk tier:** High. Defaults to draft-and-approve. Internal channels can be graduated faster than external-customer DMs.
***
### `send_sms`
Outbound SMS through the configured provider.
```yaml theme={null}
- tool: send_sms
to: "{{ contact.phone }}"
body: "{{ short_message }}"
```
**Use when:** Time-sensitive notifications where email or in-app isn't enough.
**Risk tier:** High. SMS has the highest cost-of-mistake of any messaging tool. Always draft-and-approve unless the customer has explicitly opted in to automated SMS.
***
### `notify_user`
In-app notification. Renders in the user's notification panel and the [Autopilot](/autopilot/inbox) ambient strip.
```yaml theme={null}
- tool: notify_user
user_id: "{{ deal.owner }}"
title: "Deal moved to lost"
body: "{{ deal.name }} ({{ deal.amount }}) was just marked lost."
link: "/deals/{{ deal.id }}"
```
**Use when:** The user needs to know something but doesn't need a draft to approve.
**Risk tier:** Low. Internal only. Always live (no draft-and-approve overhead).
***
### `call_external`
Generic outbound HTTP call. The escape hatch for tools the registry doesn't cover yet.
```yaml theme={null}
- tool: call_external
method: POST
url: "https://api.example.com/webhook"
headers:
Authorization: "Bearer {{ secrets.example_api_key }}"
body:
deal_id: "{{ deal.id }}"
amount: "{{ deal.amount }}"
```
**Use when:** You need to integrate with a system that isn't covered by a dedicated tool.
**Risk tier:** High. The runtime can't know what an external endpoint does. Always draft-and-approve until you've validated the call's effect.
***
### `ask_human`
Pause the playbook and ask a question. The question lands in the configured user's [Autopilot inbox](/autopilot/inbox) or [Copilot](/copilots/overview). The playbook resumes when they answer.
```yaml theme={null}
- tool: ask_human
user_id: "{{ deal.owner }}"
question: "Should I escalate {{ deal.name }} to procurement?"
options: [yes, no, skip]
timeout: "24h"
```
**Use when:** The agent needs a decision it can't make on its own.
**Risk tier:** Low. The action is "ask a question." The follow-up tool calls inherit their own tiers.
***
### `create_task`
Surface a TODO item in a tasks collection. Use this when the right action is "a human should do something" rather than "the agent should do something."
```yaml theme={null}
- tool: create_task
title: "Review {{ deal.name }} terms"
description: "Deal moved to legal review. Standard MSA in place?"
assignee: "{{ deal.owner }}"
due_date: "{{ now + 2_days }}"
```
**Use when:** The right next action is human work, not agent work.
**Risk tier:** Low. Writes a record, doesn't reach outside the app.
***
### `draft_for_approval`
The default tool for outbound work. Composes a draft (email, Slack, SMS, external call) and lands it in the configured user's [Autopilot inbox](/autopilot/inbox). The user approves, edits, or skips. Only on approval does the underlying outbound tool run.
```yaml theme={null}
- tool: draft_for_approval
underlying: send_email
owner: "{{ deal.owner }}"
payload:
to: "{{ contact.email }}"
subject: "Following up on {{ deal.name }}"
body: "{{ rendered_template }}"
reasoning: "{{ agent.reasoning }}"
```
**Use when:** Almost always, for any outbound tool. This is the default in every Gainable app and the reason agents are safe by default.
**Risk tier:** Low. Drafts never reach a recipient on their own.
***
## Tool-tier interaction
The risk tier on a tool is the *default*. A playbook's [risk tier](/autopilot/risk-tiers) can constrain it further, but never relax it. A tool that defaults to high stays high until the org explicitly graduates it.
A playbook configured at `auto_with_undo` doesn't make `send_email` skip the draft step unless `send_email` has graduated for that org or that recipient class. The runtime is the final word.
## Adding a tool the registry doesn't cover
When you need behavior the registry doesn't have, the right question is usually "is this an outbound integration?"
* **Yes.** Use `call_external`. If it becomes a recurring pattern, it's a candidate for promotion to a first-class tool.
* **No, it's pure data work.** It probably belongs in a derived field or a [build agent](/concepts/agents) step, not in a runtime tool.
We deliberately keep the registry small. Every tool we add is one more thing the action log, the risk tiers, and the Autopilot UI have to know about.
## Best practices
Outbound tools should almost always be wrapped in `draft_for_approval`. The exceptions are graduated tools that have earned auto status with a clean approval history.
If the agent doesn't have enough information, `ask_human` is cheaper than a wrong action. The user is in the loop anyway.
Every tool call writes to the [action log](/autopilot/agent-action-log) automatically. Don't add side effects that don't show up there.
A surfaced task in the user's queue is often more useful than a draft message. Don't force every objective into an outbound message.
## Learn more
Draft-and-approve, auto-with-undo, auto
Every tool call recorded
How tools fit into a playbook
Slack, SMS, calendar, DocuSign, Stripe, generic webhooks
# Triggers
Source: https://docs.gainable.dev/autopilot/triggers
The four ways a playbook starts
## The closed vocabulary
Every [playbook](/autopilot/playbooks) starts from one of exactly four trigger types. Nothing else. The closed vocabulary is deliberate. It keeps agents auditable, predictable, and easy to reason about.
| Trigger | Started by | Use for |
| ------------------ | ------------------------------------ | ------------------------------------------------------ |
| **Schedule** | Cron expression | Daily briefings, weekly digests, time-based SLA checks |
| **Data change** | Change-stream events on a collection | Reactive work tied to record state |
| **Webhook** | Inbound HTTP from an external system | Stripe events, SendGrid bounces, GitHub issues |
| **User-triggered** | Explicit button click in the app | "Draft me a recap," "Run this playbook now" |
## Schedule
A cron-style schedule. The runtime fires the playbook at the specified time.
```yaml theme={null}
trigger:
type: schedule
cron: "0 9 * * 1-5" # 9 AM, Monday to Friday
timezone: "America/New_York"
```
### Common cron patterns
| Pattern | Meaning |
| -------------- | -------------------------------- |
| `0 8 * * *` | Every day at 8 AM |
| `0 9 * * 1-5` | Weekdays at 9 AM |
| `0 */4 * * *` | Every 4 hours |
| `0 0 1 * *` | First of every month at midnight |
| `*/15 * * * *` | Every 15 minutes |
### Timezone handling
For [personal-scope](/autopilot/scopes) playbooks, the timezone resolves to the user's timezone. For app-wide playbooks, the timezone is set on the trigger.
```yaml theme={null}
trigger:
type: schedule
cron: "0 8 * * 1-5"
timezone: "{{ user.timezone }}" # personal scope
```
### When to use schedule
* Recurring digests, briefings, and reports
* Time-based SLA enforcement ("any open ticket older than 24 hours")
* Periodic refreshes ("recompute pipeline forecast every Monday")
## Data change
A change-stream event on a collection. The runtime observes inserts, updates, and deletes, and fires the playbook when an event matches the filter.
```yaml theme={null}
trigger:
type: data_change
collection: deals
on: [update]
where: "stage = 'lost' AND amount > 10000"
```
### Operations
| Operation | Fires when |
| --------- | ---------------------------------- |
| `create` | A new record is inserted |
| `update` | An existing record's fields change |
| `delete` | A record is removed |
You can listen to multiple operations in one trigger:
```yaml theme={null}
trigger:
type: data_change
collection: tickets
on: [create, update]
where: "priority = 'p0'"
```
### Field-level filters
The `where` clause can reference the new state of the record. For updates, it can also reference what changed:
```yaml theme={null}
trigger:
type: data_change
collection: deals
on: [update]
where: "changed('stage') AND new.stage = 'lost'"
```
### When to use data change
* Reactive work tied to a state change ("when a deal moves to lost…")
* Onboarding flows ("when a new contact is created…")
* Anomaly detection ("when an order's total exceeds \$50,000…")
The change-stream pattern is the same one Gainable uses internally for the email daemon and other observation services. The runtime does the heavy lifting; the playbook just describes the filter.
## Webhook
An inbound HTTP request from an external system. The runtime exposes a unique URL per webhook and fires the playbook when a request arrives.
```yaml theme={null}
trigger:
type: webhook
source: stripe
event: invoice.payment_failed
secret: "{{ secrets.stripe_webhook }}"
```
### How webhook URLs work
When you configure a webhook trigger, Gainable provisions a URL like:
```
https://api.gainable.dev/webhooks/{app_id}/{trigger_id}
```
You configure the source system to POST to that URL. The runtime verifies the signature (when applicable), parses the body, and exposes it as `trigger.body` to the playbook.
### Common sources
| Source | Example events |
| -------- | --------------------------------------------------------- |
| Stripe | `invoice.payment_failed`, `customer.subscription.deleted` |
| SendGrid | `bounce`, `spamreport` |
| GitHub | `pull_request.opened`, `issue_comment.created` |
| Calendar | `event.created`, `event.updated` |
| Generic | Any system that can POST JSON |
### When to use webhook
* Reacting to events in external systems you don't own
* Bridging Gainable apps to third-party tools
* Receiving callbacks from long-running external jobs
See [Connect outbound](/autopilot/connect-outbound) for the full inbound and outbound integration story.
## User-triggered
An explicit button click in the app. A user opens a record (or a page) and clicks a button labeled "Run this playbook now."
```yaml theme={null}
trigger:
type: user_triggered
button_label: "Draft recap"
surfaces: [deal_detail_page, dashboard]
```
### How it appears
Gainable renders user-triggered playbooks as buttons in the [Autopilot](/autopilot/inbox) widget on the page you specified. When the user clicks:
1. The runtime fires the playbook with `trigger.user_id` set to the clicker
2. The playbook runs with that user's permissions
3. The resulting draft (if any) lands in their personal Autopilot inbox
### When to use user-triggered
* On-demand drafts ("write me a follow-up for this deal right now")
* Bulk operations the user wants to start manually
* Anything the user wants control over the timing of, even if the rest of the playbook is automatic
## Choosing the right trigger
| Question | Answer |
| --------------------------------------------------- | ------------------ |
| Does this need to happen at a specific time of day? | **Schedule** |
| Does this react to a record changing? | **Data change** |
| Does this come from an external system? | **Webhook** |
| Should the user choose when this runs? | **User-triggered** |
If two answers are yes, you probably have two playbooks pretending to be one. Split them.
## Best practices
A `schedule` trigger that scans a collection every 5 minutes is almost always worse than a `data_change` trigger that fires only on the relevant transition. Faster, cheaper, and more accurate.
The more selective the trigger's `where` clause, the less work the runtime does and the cleaner your action log gets.
A daily briefing fired at 8 AM UTC is 3 AM in California. Bind the timezone to the user.
Webhook triggers can be tested by replaying captured payloads. Always do this before going live.
## Learn more
Trigger, steps, and guardrails together
What playbooks call after the trigger fires
Webhooks and external systems
Where user-triggered buttons render
# Build from data
Source: https://docs.gainable.dev/build-from-data
Connect your existing data sources and let AI build an app around them
## Start from your data
Already have data in Google Sheets, HubSpot, Stripe, or another tool? You don't need to describe an app from scratch. Connect your data and Gainable's DataAnalyzer agent will examine it, recommend features, and build a complete app around it.
Your existing data becomes the specification. Instead of writing a prompt that describes your app from scratch, the AI reads your actual schema from your datasets, detects what domain you're in, and proposes an app tailored to your data.
This path is ideal when you already have data in external systems and want to build views, dashboards, and workflows on top of it.
## How it works
Choose from 15+ supported sources including Google Sheets, HubSpot, Stripe, Airtable, and Supabase. Authenticate via OAuth or API key.
Group your sources into a dataset and sync the data into Gainable. You can connect multiple sources to combine data from different systems.
On the new project page, choose **Build from data** and select one or more datasets.
The DataAnalyzer agent examines your schema, sample rows, and field types. It identifies the domain (CRM, project management, finance, etc.) and recommends features matched to your data patterns.
The agent asks 2-3 clarifying questions through interactive multiple-choice options. You shape the app through a short Q\&A conversation.
The Build Agent generates a complete application with views, dashboards, and collaboration features, pre-populated with your synced data.
## What AI analyzes
When you connect data, the DataAnalyzer agent examines:
| Signal | What it tells the AI |
| ----------------------------- | ------------------------------------------------------------------------------------------- |
| **Field names** | Domain context (e.g., "deal\_amount" signals sales, "due\_date" signals project management) |
| **Field types** | What UI to generate (currency fields get KPI cards, dates get timeline views) |
| **Enum values** | Pipeline stages, statuses, and categories that map to kanban columns or chart segments |
| **Sample rows** | Real data patterns that inform layout and feature recommendations |
| **Cross-model relationships** | How datasets connect (contacts to companies, tasks to projects) |
### Domain detection
The agent recognizes common business domains and tailors its recommendations:
* **CRM / Sales** — Pipeline boards, deal value dashboards, contact card grids
* **Project management** — Kanban boards, timeline views, progress tracking
* **Finance / Payments** — Revenue dashboards, transaction tables, KPI cards
* **HR / People** — Employee directories, org charts, onboarding trackers
* **Inventory / Operations** — Stock level dashboards, order tables, status tracking
## Interactive refinement
The DataAnalyzer doesn't just guess. It asks you to confirm and refine through interactive options:
After analyzing a Google Sheet with deal data, the agent asks:
**Question 1:** "I see a sales pipeline with 5 stages and deal values. What should be the primary view?"
* Pipeline Board (kanban by stage)
* Revenue Dashboard
* Deal Table
**Question 2:** "How should I handle the 'Owner' field?"
* Show as a filter on the pipeline board
* Create a separate view grouped by owner
* Both
**Question 3:** "I can add these collaboration features. Which ones?"
* Comments on individual deals
* Team activity feed on the dashboard
* AI copilot for sales questions
Each answer updates the app specification before building begins.
The conversation typically takes 2-3 turns before the spec is finalized. You're always in control of what gets built.
## What gets built
The output is a complete, working application with features matched to your data:
Kanban boards for pipeline enums, dashboards for numeric fields, card grids for people data, tables for transactional data
Automatic visualization of key metrics based on currency, count, and date fields in your data
Comments, chat, and activity feeds placed in context based on the domain
An AI assistant configured with knowledge of your data domain, ready to answer questions
## Supported data sources
More connectors are added regularly. If you need a source that isn't listed, reach out via the live chat in the bottom-left corner of the builder or email [support@gainable.dev](mailto:support@gainable.dev).
### CRM
| Source | Auth | Capabilities |
| -------------- | ------- | --------------------------------------- |
| **HubSpot** | OAuth | Read & write contacts, companies, deals |
| **Attio** | OAuth | Read & write CRM data |
| **Folk CRM** | API key | Read & write CRM data |
| **Salesforce** | OAuth | Read & write CRM data |
### Databases and spreadsheets
| Source | Auth | Capabilities |
| ----------------- | ------------- | ------------------- |
| **Google Sheets** | OAuth | Read & write rows |
| **Airtable** | OAuth | Read & write bases |
| **Supabase** | API key + URL | Read & write tables |
### Analytics and product
| Source | Auth | Capabilities |
| -------------------- | ------- | ------------------------ |
| **Google Analytics** | OAuth | Read analytics data |
| **PostHog** | API key | Read event and user data |
| **Mixpanel** | OAuth | Read analytics data |
| **Typeform** | OAuth | Read form responses |
| **Linear** | OAuth | Read & write issues |
| **Jira** | OAuth | Read & write issues |
### Payments and data warehouses
| Source | Auth | Capabilities |
| -------------- | ------------------ | --------------------------------------- |
| **Stripe** | API key | Read customers, invoices, subscriptions |
| **Databricks** | Client credentials | Read catalogs, schemas, tables, run SQL |
## Build from data vs. describe your app
Not sure which path to choose? Here's how they compare:
| | Describe your app | Build from data |
| ------------------ | ----------------------------------------- | ------------------------------------------------ |
| **Best when** | Starting from scratch with an idea | You have existing data in external systems |
| **Data** | Data models created from your description | Derived from your datasets and connected sources |
| **Configuration** | Write a prompt | Interactive Q\&A with AI |
| **Agent pipeline** | Planner → Build → Validation | DataAnalyzer → Build → Validation |
| **Data** | Starts empty, you add data later | Pre-populated from connected sources |
You can combine both approaches. Connect data sources first, then describe additional features you want on top of them in the prompt.
## Next steps
Detailed guide to creating datasets and connecting data sources
Try the prompt-based path instead
Understand the full agent pipeline
Learn how your data is organized
# Collaboration
Source: https://docs.gainable.dev/building/collaboration
Add team chat, file sharing, and comments to your apps
## Built-in collaboration
Gainable apps can include collaboration features powered by Weavy. These are self-contained components that work out of the box.
## Available features
### Team chat
Real-time messaging for groups.
```text theme={null}
"Add a team chat to the project page"
"Include a group chat for discussing deals"
```
What you get:
* Real-time messaging
* Message history
* Typing indicators
* Read receipts
* Emoji reactions
### Direct messaging
Private conversations between users.
```text theme={null}
"Add a messenger for direct messages between users"
"Let users send private messages"
```
What you get:
* One-on-one conversations
* Conversation list
* Unread message counts
* User presence indicators
### File sharing
Upload and share documents.
```text theme={null}
"Add file sharing to the project"
"Let users upload documents to deals"
```
What you get:
* File upload (drag and drop)
* File previews
* Download options
* File organization
### Comments
Discussion threads on specific items.
```text theme={null}
"Add comments to tasks"
"Let users comment on deals"
```
What you get:
* Threaded discussions
* Mentions (@user)
* Timestamps
* Edit and delete
### Activity feeds
Social-style updates and announcements.
```text theme={null}
"Add an activity feed to the dashboard"
"Include a news feed for team updates"
```
What you get:
* Post creation
* Comments on posts
* Reactions
* Chronological feed
### AI Copilot
Add an AI-powered chat assistant alongside your team collaboration features.
```text theme={null}
"Add an AI copilot to the project page that can look up
task data and answer questions about the project"
```
```text theme={null}
"Add a smart assistant to the deals page that helps
reps find deals and get pipeline insights"
```
**Copilot vs team chat:** The copilot is a conversational assistant powered by [Gaia Copilot](/copilots/overview). It responds with data lookups and knowledge-based answers. Team chat is human-to-human messaging. You can use both on the same page.
## How to request collaboration
Simply describe what you want in natural language:
```text Chat theme={null}
"Add a team chat to the project page"
"Include chat for discussing deals"
"Add group messaging"
```
```text Files theme={null}
"Add file sharing"
"Let users upload documents"
"Include file attachments"
```
```text Comments theme={null}
"Add comments to tasks"
"Let users discuss items"
"Include threaded comments"
```
```text Messaging theme={null}
"Add direct messages"
"Let users message each other"
"Include private messaging"
```
## Where to place collaboration
You can add collaboration features to specific contexts:
### Page-level chat
```text theme={null}
"Add a team chat to the dashboard page"
```
Everyone on that page sees the same chat.
### Item-level chat
```text theme={null}
"Add a chat for each project"
```
Each project has its own separate conversation.
### Global messaging
```text theme={null}
"Add a messenger accessible from anywhere"
```
Users can access direct messages from any page.
## Notifications
Collaboration features include notifications:
* **Toast notifications** - Pop-up alerts for new messages
* **Badge counts** - Unread message indicators
* **Sound alerts** - Optional audio notifications
Notifications are enabled by default. Users can manage their preferences.
## User presence
See who's online and active:
* **Online indicators** - Green dots for active users
* **Typing indicators** - See when someone is typing
* **Last seen** - Know when users were last active
## Best practices
### Choose the right feature
| Need | Use |
| ------------------------- | ---------- |
| Team discussions | Chat |
| Private conversations | Messenger |
| Document collaboration | Files |
| Item-specific discussions | Comments |
| Announcements | Posts/Feed |
### Place chat contextually
```text Good theme={null}
"Add a chat to each project page for project-specific discussions"
```
```text Less useful theme={null}
"Add chat" (without specifying where)
```
### Combine features
```text theme={null}
"Add to each project:
- Team chat for discussions
- File sharing for documents
- Activity feed for updates"
```
## Example integrations
### Project management
```text theme={null}
Build a project tracker with:
- Projects with name and status
- Tasks for each project
On the project detail page, add:
- Team chat for discussions
- File sharing for documents
```
### CRM
```text theme={null}
Build a CRM with:
- Companies and contacts
- Deals linked to companies
On each deal page, add:
- Comments for internal notes
- File attachments for proposals
```
### Team dashboard
```text theme={null}
Build a team dashboard with:
- Activity feed for announcements
- Team chat for discussions
- File area for shared documents
```
## Learn more
Detailed collaboration features
How real-time sync works
# Datasets
Source: https://docs.gainable.dev/building/data-connectors
Group external data sources into datasets and attach them to your apps
## What are datasets?
Datasets let you bring data from external systems into Gainable. A dataset groups data from one or more connected sources — like Google Sheets, HubSpot, and Stripe — into a single collection. The data comes in as-is from each source, with no transformation or merging required.
You can have several sources in one dataset, and each source's data stays separate within it. When you're ready, attach the entire dataset to an app or use it to [build a new app from data](/build-from-data).
If you need to merge or normalize data from multiple sources into a single unified output (e.g., matching contacts by email across HubSpot and Google Sheets), use a [data model](/building/data-models) and include it in your dataset.
Data that doesn't come from a supported connector — an internal API, a partner feed, something you assemble yourself — can still become a dataset. Write a script that emits the rows and keep them fresh on a schedule. See [Recurring data pipelines](/mcp/datasets).
## Two ways to use datasets
Create a dataset, sync your sources, and let the DataAnalyzer agent design an entire app around your data. Best when starting a new project from existing data.
Attach a dataset to an app you've already built. The synced data appears as read-only collections in your app.
## Supported data sources
### CRM
| Source | Auth | Capabilities |
| -------------- | ------- | --------------------------------------- |
| **HubSpot** | OAuth | Read & write contacts, companies, deals |
| **Attio** | OAuth | Read & write CRM data |
| **Folk CRM** | API key | Read & write CRM data |
| **Salesforce** | OAuth | Read & write CRM data |
### Databases and spreadsheets
| Source | Auth | Capabilities |
| ----------------- | ------------- | ------------------- |
| **Google Sheets** | OAuth | Read & write rows |
| **Airtable** | OAuth | Read & write bases |
| **Supabase** | API key + URL | Read & write tables |
### Analytics and product
| Source | Auth | Capabilities |
| -------------------- | ------- | ------------------------ |
| **Google Analytics** | OAuth | Read analytics data |
| **PostHog** | API key | Read event and user data |
| **Mixpanel** | OAuth | Read analytics data |
| **Typeform** | OAuth | Read form responses |
| **Linear** | OAuth | Read & write issues |
| **Jira** | OAuth | Read & write issues |
### Payments and data warehouses
| Source | Auth | Capabilities |
| -------------- | ------------------ | --------------------------------------- |
| **Stripe** | API key | Read customers, invoices, subscriptions |
| **Databricks** | Client credentials | Read catalogs, schemas, tables, run SQL |
## How it works
Choose a connector and authenticate with OAuth or an API key. Gainable securely stores the connection. You can have several connectors to the same source with different credentials, for example multiple HubSpot accounts.
Create a new dataset and give it a name. A dataset is a container for one or more data sources.
Select which connected sources to include in the dataset. For each source, pick what data to include (for Google Sheets: spreadsheet + sheet, for HubSpot: contacts, deals, etc.).
You can add multiple sources to the same dataset — for example, contacts from HubSpot, revenue data from Google Sheets, and payment data from Stripe.
If you need merged or normalized views of your data, [create a data model](/building/data-models) and include it in the dataset. Data models let you combine data from multiple sources using merge keys and field mappings.
Sync to pull the latest data from all connected sources into Gainable. Each source's data is stored as-is in the dataset.
## Multiple sources in one dataset
A key feature of datasets is combining data from different systems without merging. Each source stays separate — you're grouping related data together, not transforming it.
You have customer data spread across three systems:
* **HubSpot** — contacts and deals
* **Google Sheets** — quarterly targets and notes
* **Stripe** — payments and subscriptions
Create a single "Sales Operations" dataset and add all three sources. After syncing, your dataset contains all the data from each source, kept separate but accessible together. When you build an app from this dataset or attach it to an existing app, all three sources are available.
## Including data models in a dataset
Datasets take data as-is from sources. But sometimes you need a unified view — for example, merging contacts from HubSpot and Google Sheets by email, or normalizing field names across systems.
For this, create a [data model](/building/data-models) with merge keys and field mappings, then include it in your dataset. The data model produces a single merged output that lives alongside your raw source data in the dataset.
## Manage datasets
The dataset interface has 3 main areas:
* **Connections tab**: View all connected sources in the dataset
* **Preview tab**: View sample data from connected sources before committing a sync
* **Cron tab**: Enable auto sync to keep the data updated from connected sources
Use the **Sync** button in the **Preview tab** to pull the latest data from connected sources.
## Best practices
Put sources that serve the same business function into one dataset. A "Sales" dataset might include your CRM, payment processor, and a forecasting spreadsheet. This makes it easy to build apps that span multiple systems.
Don't try to work around source boundaries. If you need to match records across sources (e.g., contacts by email), create a data model with merge keys and include it in the dataset.
Always check the Preview tab before running a full sync. This lets you catch unexpected data or connection issues before they reach your app.
## Learn more
Let AI analyze your dataset and build an app around it
Merge and normalize data from multiple sources
Collect data on a schedule and keep a dataset in sync from a script
Add a conversational assistant to your app
Add autonomous agents that draft work in the background
# Data models
Source: https://docs.gainable.dev/building/data-models
How Gainable organizes and stores your application data
## Understanding data in Gainable
When you describe data in your prompts, Gainable creates **data models** — structured definitions of what information your app stores. Think of a data model as a template for each type of thing you're tracking.
Data models are also used to **merge and normalize** external data from multiple sources into a single unified output. When you need to combine contacts from HubSpot and Google Sheets by email, or normalize field names across systems, you create a data model with merge keys and field mappings, then include it in a [dataset](/building/data-connectors).
## What is a data model?
A data model defines:
* **What fields** each item has (name, email, status, etc.)
* **What type** each field is (text, number, date, etc.)
* **How items relate** to other items (belongs to, has many)
When you say "track deals with name, amount, and status", Gainable creates a Deal model:
| Field | Type | Description |
| --------- | ------- | -------------------------------- |
| name | Text | The deal name |
| amount | Number | The deal value |
| status | Options | Selected from predefined choices |
| createdAt | Date | Automatically added |
| updatedAt | Date | Automatically added |
## Collection types
The **Data** tab in your app groups collections into 3 categories:
| Aspect | App Collections | Data Collections | Core Collections |
| ------------ | ----------------------- | ------------------------------------ | -------------------------- |
| Source | Created in your app | Synced via datasets | Built-in system models |
| Editable | Yes | Read-only (managed via datasets) | Read-only |
| Examples | companies, deals, tasks | HubSpot contacts, Google Sheets rows | users, agents, connections |
| Chat enabled | Yes | No | No |
### App Collections
Custom collections created when you describe data models. Fully editable and specific to your app. These are what you build.
### Data Collections
External data synced via [datasets](/building/data-connectors) (HubSpot, Sheets, Stripe, etc.). They appear automatically when you attach a dataset to your app. Read-only from the app, managed through the datasets interface.
### Core Collections
Built-in system collections present in every app: users, agents, email templates, email logs, user field metadata, and connections. Read-only, managed by the platform.
## Field types
When describing your data, you can specify field types to get exactly what you need:
### Text fields
For names, descriptions, and other text content.
```text theme={null}
Prompt: "title (text)" or just "title"
Stores: Any text content
Example: "Enterprise License Renewal"
```
### Number fields
For quantities, amounts, and measurements.
```text theme={null}
Prompt: "quantity (number)" or "amount"
Stores: Numeric values
Example: 42, 3.14, 1000000
```
### Currency fields
For money values with proper formatting.
```text theme={null}
Prompt: "price (currency)" or "amount in dollars"
Stores: Numeric value
Displays: $1,234.56
```
### Date fields
For dates and timestamps.
```text theme={null}
Prompt: "due date" or "created date"
Stores: Date and time
Displays: Formatted date
```
### Option fields (Enums)
For selecting from a predefined list.
```text theme={null}
Prompt: "status (new, in progress, done)"
Stores: One of the specified options
Displays: Dropdown or badges
```
### Yes/No fields (Boolean)
For true/false values.
```text theme={null}
Prompt: "is active (yes/no)" or "completed (checkbox)"
Stores: True or false
Displays: Checkbox or toggle
```
### Reference fields
For linking to other data models.
```text theme={null}
Prompt: "assigned to (user)" or "belongs to company"
Stores: Link to another item
Displays: Name or selector
```
## Relationships between data
### One-to-Many
One item has multiple related items.
```text theme={null}
"Each project has many tasks"
"Tasks belong to a project"
```
This creates:
* Project model (parent)
* Task model with a "project" field linking to Project
### Many-to-One
Multiple items link to one item.
```text theme={null}
"Contacts belong to a company"
"Deals are linked to a contact"
```
### Self-referential
Items that reference the same type.
```text theme={null}
"Each employee has a manager (another employee)"
"Tasks can have subtasks"
```
## Automatic fields
Every data model automatically includes:
| Field | Purpose |
| ----------- | ------------------------------- |
| `_id` | Unique identifier for each item |
| `createdAt` | When the item was created |
| `updatedAt` | When the item was last modified |
You don't need to ask for these - they're always there.
## Merging data from multiple sources
When the same type of data lives in different systems — for example, contacts in both HubSpot and a Google Sheet — you can create a data model that merges them into a single unified output.
### How merging works
1. **Connect each source** to the data model
2. **Define a merge key** — a shared field (like email) used to match records across sources
3. **Set source priority** — choose which source takes precedence when the same field has different values
4. **Map fields** — select which columns to include, rename fields, and set types
The merged output can then be included in a [dataset](/building/data-connectors) alongside your raw source data.
You have contacts in HubSpot (with deal history) and a Google Sheet (with custom scoring). Both share an email column.
1. Create a **Contacts** data model
2. Connect HubSpot and Google Sheets as sources
3. Set **email** as the merge key
4. Set HubSpot as the primary source (higher priority)
5. Include the data model in your dataset
After sync, each contact has deal data from HubSpot and scoring from Google Sheets, matched by email. If both sources have a "company" field with different values, HubSpot's value is used because it has higher priority.
## Best practices
### Be explicit about fields
```text Good theme={null}
Build a contact manager with:
- Full name
- Email address
- Phone number
- Company
- Job title
- Notes
```
```text Vague theme={null}
Build a contact manager
```
### Specify options for status fields
```text Good theme={null}
Status options: draft, pending, approved, rejected
```
```text Vague theme={null}
Add a status field
```
### Name relationships clearly
```text Good theme={null}
Each task belongs to one project
Each project has many tasks
Tasks can be assigned to one user
```
```text Confusing theme={null}
Tasks, projects, and users are related
```
### Use meaningful field names
```text Good theme={null}
closeDate, expectedRevenue, primaryContact
```
```text Confusing theme={null}
date1, field2, ref
```
## Viewing your data
Once your app is built, you can:
* **See all items** in list views
* **Add new items** through forms
* **Edit items** by clicking on them
* **Delete items** with confirmation
* **Filter and search** to find specific items
## Data persistence
All data in Gainable apps is:
* **Automatically saved** when you create or edit items
* **Persistent** across sessions and users
* **Backed up** regularly
* **Accessible** via API endpoints
You don't need to worry about "saving" - data is stored as soon as you submit a form or complete an action.
## Learn more
Group external data sources and attach them to your app
How your data is displayed
Live data updates
# Real-time updates
Source: https://docs.gainable.dev/building/real-time
How Gainable keeps data synchronized across all users
## What are real-time updates?
Real-time updates mean changes appear instantly for all users without refreshing the page. When someone adds a deal, updates a task, or deletes a contact, everyone sees the change immediately.
## How it works
Gainable apps use WebSocket connections to push updates:
1. **User A** creates a new task
2. **Server** saves the task to the database
3. **Server** broadcasts "new task created" to all connected users
4. **User B's screen** updates automatically to show the new task
This happens in milliseconds - changes feel instantaneous.
## What updates in real-time?
By default, these actions trigger real-time updates:
| Action | What happens |
| ---------- | ------------------------------------------- |
| **Create** | New item appears in lists and counts update |
| **Update** | Changed item refreshes with new values |
| **Delete** | Item disappears from all views |
This applies to:
* List views and tables
* Dashboard KPIs and charts
* Kanban board cards
* Detail views
## Requesting real-time features
Real-time is built into Gainable apps by default. To emphasize it:
```text theme={null}
"Make sure the task list updates in real-time"
"Show live updates when deals change"
"Sync changes across all users instantly"
```
## Use cases
### Collaborative dashboards
Multiple team members viewing the same dashboard see updates as data changes:
* New deals added to pipeline
* Status changes on tasks
* KPI totals recalculating
### Kanban boards
When someone drags a card to a new column:
* All users see the card move
* Column counts update
* No page refresh needed
### Activity feeds
Real-time is especially useful for:
* Team activity logs
* Comment threads
* Notification counts
## What doesn't update in real-time
Some things require a page refresh:
* **Navigation changes** - New pages or routes added
* **Layout changes** - Structural modifications to the UI
* **Filter states** - Your current filter selections stay the same
## Performance considerations
Real-time updates are optimized for typical use:
* **Efficient updates** - Only changed data is sent
* **Smart rendering** - Only affected components re-render
* **Connection management** - Automatic reconnection if disconnected
Real-time works best for apps with moderate data volumes. For very large datasets (thousands of items), consider using filters to limit the displayed data.
## Combining with other features
Real-time updates work with:
### Charts
```text theme={null}
"Dashboard charts that update when new data is added"
```
Charts recalculate and animate when underlying data changes.
### Kanban boards
```text theme={null}
"Kanban board where all users see cards move in real-time"
```
Drag-and-drop actions sync across all connected users.
### Collaboration
```text theme={null}
"Team chat with real-time messages"
```
Messages appear instantly for all participants.
## Troubleshooting
### Changes not appearing?
* Check your internet connection
* Try refreshing the page once
* Ensure you're looking at the same data (filters, etc.)
### Updates seem delayed?
* High network latency can cause slight delays
* Large data changes may take a moment to process
* Complex views may have brief rendering delays
## Learn more
Understanding your app's interface
Team chat and file sharing
# Views
Source: https://docs.gainable.dev/building/views
How Gainable creates user interfaces for your apps
## Understanding views
Views are the pages and screens in your application. When you describe what you want to see, Gainable creates views that display your data and allow interaction.
## Types of views
### List views
Display multiple items in a table or card layout.
```text theme={null}
"Show all deals in a list"
"Display tasks as cards"
"Create a table of contacts"
```
Features typically included:
* Column headers or card titles
* Sorting options
* Pagination for large lists
* Click to view/edit details
### Detail views
Show all information for a single item.
```text theme={null}
"When I click a deal, show all its details"
"Project detail page with tasks"
```
Features typically included:
* All fields displayed
* Edit functionality
* Related items (if applicable)
* Delete option
### Dashboard views
Overview of data with summaries and charts.
```text theme={null}
"Dashboard showing deal totals and charts"
"Overview page with KPIs"
```
Features typically included:
* KPI cards with totals
* Charts and graphs
* Recent activity
* Quick actions
### Kanban views
Cards organized in columns for workflow management.
```text theme={null}
"Kanban board for tasks by status"
"Pipeline view for deals"
```
Features typically included:
* Drag-and-drop between columns
* Card summaries
* Column totals
* Quick edit
## UI components
Gainable uses a variety of components to build your interfaces:
### Cards
Compact display of item information.
```text theme={null}
"Show deals as cards with name, amount, and status"
```
### Tables
Structured rows and columns for data.
```text theme={null}
"Display contacts in a table with sortable columns"
```
### Forms
Input fields for creating and editing data.
```text theme={null}
"Add deal form with all fields"
"Edit contact modal"
```
### Modals and drawers
Overlay panels for focused interactions.
```text theme={null}
"Open edit form in a modal"
"Show details in a slide-out drawer"
```
### Filters
Narrow down displayed data.
```text theme={null}
"Filter deals by status"
"Search contacts by name"
"Date range filter for orders"
```
### Charts
Visual data representation.
```text theme={null}
"Pie chart of deals by status"
"Line chart showing monthly revenue"
```
## Responsive design
All Gainable views are automatically responsive:
* **Desktop**: Full layout with sidebars and multi-column grids
* **Tablet**: Adapted layout with collapsible elements
* **Mobile**: Single-column layout with touch-friendly controls
You don't need to specify this - it's built in.
## Navigation
Gainable creates navigation between views automatically:
* **Header navigation** for main pages
* **Breadcrumbs** for hierarchical navigation
* **Links** between related items
* **Back buttons** for returning to lists
### Requesting specific navigation
```text theme={null}
"Add a sidebar with links to Dashboard, Deals, and Contacts"
"Put navigation tabs at the top"
```
## Customizing views
### Layout requests
```text theme={null}
"Put the chart on the left and the list on the right"
"Stack the KPI cards horizontally"
"Use a 2-column layout for the form"
```
### Placement requests
```text theme={null}
"Add the filter above the table"
"Put the add button in the top right"
"Show the total at the bottom of the list"
```
### Display requests
```text theme={null}
"Show the status as a colored badge"
"Display amounts in green for positive, red for negative"
"Use avatars for user assignments"
```
## View-specific tips
### For dashboards
* Request specific KPIs: "Show total revenue, deal count, and average deal size"
* Name your charts: "Pie chart showing deals by status"
* Include recent activity: "List of last 10 deals created"
* Add quick actions: "Button to create new deal"
### For lists
* Specify columns: "Show name, email, company, and status"
* Request sorting: "Sort by created date, newest first"
* Add filters: "Filter by status and date range"
* Enable search: "Search by name or email"
### For kanban boards
* Define columns: "Columns: Backlog, In Progress, Review, Done"
* Specify card content: "Cards show title, assignee, and due date"
* Request column totals: "Show count in each column header"
* Enable drag-and-drop: "Drag tasks between columns"
## Themes and styling
Gainable apps use themes for consistent styling:
```text theme={null}
"Use the corporate theme"
"Apply a dark color scheme"
"Use the cupcake theme for a playful look"
```
Available themes include: light, dark, cupcake, corporate, retro, cyberpunk, and more.
Learn more about themes and styling
## Learn more
Live data synchronization
Chat, files, and comments
# Build agents
Source: https://docs.gainable.dev/concepts/agents
Meet the build agents that turn your prompt into a working application
## The build agent system
Gainable uses multiple specialized build agents, each with a specific role in turning your prompt into a working app. Think of them as a team of experts working together.
**Build agents vs Gaia.** This page is about the agents that *build* your app: Planner, DataAnalyzer, Build, Validation, Conversation. Once your app is live, two more pieces of Gaia run *inside* it: [Gaia Copilot](/copilots/overview) for conversation and [Gaia Autopilot](/autopilot/overview) for autonomous work.
## Planner Agent
The Planner is the first agent to see your request. It analyzes what you want and creates a structured plan.
* Understands your intent (create, update, or seed data)
* Identifies what data models you need
* Determines which views and features to build
* Recognizes when to use built-in skills (charts, kanban, chat)
* Creates a checklist of what will be delivered
### Example: Planner in action
When you say: *"Build a project tracker with tasks and due dates"*
The Planner creates:
```
Intent: Create new application
Summary: Build project tracker with task management
Data models needed:
- Project (name, description, status)
- Task (title, due date, priority, linked to project)
Views:
- Project list with task counts
- Task management within each project
Features:
- Create/edit/delete projects
- Add tasks with due dates
- Filter tasks by status
```
This plan is then handed to the Build Agent.
## DataAnalyzer Agent
The DataAnalyzer is used when you [build from data](/build-from-data) instead of describing an app. It examines your synced data and designs an app spec through conversation.
* Analyzes schema, field types, and sample data from connected sources
* Identifies the domain (CRM, project management, finance, etc.)
* Detects patterns that map to features (pipeline enums → kanban, currency → dashboards)
* Asks clarifying questions through interactive multiple-choice options
* Produces a multi-stage build specification
* Decides where to place collaboration features based on domain context
### Example: DataAnalyzer in action
When you connect a Google Sheet with deal data (name, amount, stage, close date), the DataAnalyzer:
```
Domain detected: CRM / Sales
Key patterns:
- "stage" enum with pipeline values → Kanban board
- "amount" currency field → Dashboard KPIs + charts
- "close_date" date field → Timeline filtering
Recommended views:
- Pipeline (kanban by stage)
- Dashboard (revenue KPIs + charts)
- Deals table (searchable, sortable)
```
It then asks 2-3 questions to refine the spec before handing off to the Build Agent.
## Build Agent
The Build Agent is the workhorse that generates all your application code.
* Creates database models to store your data
* Builds API routes for data operations
* Generates user interface pages
* Implements forms, tables, and interactive elements
* Follows proven patterns for reliability
### Skills and expertise
The Build Agent has deep knowledge of:
* **Data visualization** - Charts, graphs, KPIs
* **Drag-and-drop** - Kanban boards, sortable lists
* **Real-time updates** - Live data synchronization
* **UI patterns** - Forms, modals, drawers, navigation
* **Collaboration** - Chat, files, comments integration
When you request a specific feature like "add a chart" or "add a kanban board", the Build Agent uses specialized knowledge to implement it correctly.
## Validation Agent
Before your app is delivered, the Validation Agent checks for common issues.
* Forms that don't save data correctly
* Missing connections between data and views
* UI patterns that could break on mobile
* Common coding mistakes
This happens automatically - you don't need to do anything. It's like having a quality assurance team review the code before you see it.
## Conversation Agent
When you ask questions about your project (instead of requesting changes), the Conversation Agent helps.
* Answers questions about what was built
* Explains how features work
* Helps troubleshoot issues
* Provides guidance on next steps
### Example: Asking questions
```text Your question theme={null}
"How does the task filtering work?"
```
```text Conversation Agent response theme={null}
"Tasks can be filtered by status using the dropdown menu
at the top of the task list. The filter is applied
client-side, so it updates instantly as you select
different options. The available statuses are:
pending, in progress, and completed."
```
## How agents communicate
The agents work in sequence, each building on the previous work:
You describe what you want to build or change
The system determines: build, question, or seed data
For build requests, the Planner analyzes and structures the work
Code is generated following the plan
Generated code is checked for issues
Your working app appears in the preview
When you use the [Build from data](/build-from-data) path, the DataAnalyzer Agent replaces the Planner Agent in this sequence. Instead of analyzing a text prompt, it analyzes your data schema and produces a build specification through interactive conversation. The Build Agent and Validation Agent work the same way in both paths.
## Context preservation
All agents share context about your project:
* **What's already built** - Existing models, views, and features
* **Your preferences** - Design choices, naming conventions
* **Project history** - Previous changes and iterations
This means you can say things like "add a filter to the deals page" and the agents understand exactly which page you mean.
Context is preserved throughout your session. Each new request builds on everything that came before.
## Best practices
To get the most from the agent system:
1. **Be specific** - The more detail you provide, the better the results
2. **One thing at a time** - Let each build complete before requesting the next
3. **Use natural language** - Write like you're explaining to a colleague
4. **Request by feature name** - "Add a pie chart" is clearer than "visualize this somehow"
## Gaia inside your finished apps
The agents described above (Planner, Build, Validation, Conversation) are **build agents** that work behind the scenes to create your app. Once your app is live, two more pieces of Gaia run inside it:
* **Gaia Copilot.** The conversational assistant. The user asks; the Copilot answers. It reads your app's live data and references uploaded knowledge.
* **Gaia Autopilot.** The autonomous side. They watch data, draft work, and land it in Autopilot for approval. They run on their own.
The two are designed to work side by side. Copilot is reactive. Agents are proactive.
Conversational assistant with data access, knowledge bases, and an embedded chat interface
Autonomous agents that watch data and draft work for approval in Autopilot
## Learn more
Explore built-in features you can request
Write better prompts for better results
The conversational layer of every app
The proactive, autonomous layer
# How it works
Source: https://docs.gainable.dev/concepts/how-it-works
Understand how Gainable turns your ideas into working apps
## Two paths to your app
Gainable uses specialized build agents that work together to create your application. The agents involved depend on how you start:
Write what you want in plain English. The Planner Agent creates a build plan, the Build Agent generates code, and the Validation Agent ensures quality.
Connect external data sources. The DataAnalyzer Agent examines your schema, recommends features through interactive Q\&A, and produces a build specification.
Both paths converge at the Build Agent, which generates your complete application.
### Path 1: Describe your app
Write what you want in plain English. Be as specific or general as you like.
The Planner understands your intent, identifies what data you need, and creates a structured build plan.
The Build Agent creates your complete application: database models, user interface, and all the logic.
Before delivering your app, validation checks catch common issues and ensure everything works.
A fully functional application is ready to use immediately.
### Path 2: Build from data
Choose a data source (Google Sheets, HubSpot, Stripe, etc.), authenticate, and sync your data into Gainable.
The agent analyzes your field names, types, sample rows, and enum values. It identifies the domain (CRM, project management, finance, etc.) and detects patterns like pipeline stages, currency fields, or contact records.
The agent asks 2-3 clarifying questions through multiple-choice options. You shape the app spec through conversation.
The same Build Agent used in the prompt path executes the spec, creating views, dashboards, and collaboration features matched to your data.
Validation checks run to catch common issues before delivery.
A fully functional application appears, pre-populated with your synced data.
## What makes this different?
Gainable creates **complete, production-ready applications**, not code snippets:
| Traditional AI Code | Gainable |
| ----------------------- | -------------------------------------- |
| Generates code snippets | Generates complete apps |
| You assemble the pieces | Everything is connected |
| Basic text completion | Specialized agents with deep expertise |
| Generic output | Follows proven patterns |
## The agent system
Gainable uses multiple build agents, each specialized for a specific task:
Analyzes your request and creates a detailed build plan. Identifies data models, views, and features needed.
Generates the code for your application. Creates database models, routes, and user interfaces.
Examines synced data schemas and sample data. Identifies the domain, recommends features, and produces a build specification through interactive conversation. Used in the "Build from data" path.
Checks generated code for common issues and ensures it follows best practices.
Answers questions about your project and helps you understand what was built.
## Beyond building: Gaia inside your apps
The agents above (Planner, Build, Validation, Conversation) work behind the scenes to *build* your app. Once it's live, two more pieces of Gaia run inside it:
* **Gaia Copilot.** The conversational layer. The user asks; the Copilot answers. It reads live app data and references uploaded knowledge.
* **Gaia Autopilot.** The autonomous layer. They watch data against inferred objectives, draft work, and land it in [Autopilot](/autopilot/inbox) for approval.
The two are designed to live side by side. Copilot is reactive. Agents are proactive.
The conversational layer for "the user asks, the Copilot answers"
The proactive layer for "work shows up before anyone asks"
## What happens when you send a prompt
Let's follow a real example through the system:
**1. Planner Agent receives your request**
The Planner identifies:
* You need a Task data model
* Fields: title, description, due date, priority
* You'll need a view to manage tasks
* CRUD operations (create, read, update, delete)
**2. Plan is created**
```
Summary: Build task tracker with due dates and priority levels
Features:
- Task management (add, edit, delete tasks)
- Due date tracking
- Priority levels (low, medium, high)
- Task list view
Data model:
- Task: title, description, dueDate, priority, completed
```
**3. Build Agent generates code**
The Build Agent creates:
* Database model for Task
* API routes for CRUD operations
* A task list view with forms
* Priority badges and date formatting
**4. Validation runs**
Checks ensure:
* All fields are properly connected
* Forms save data correctly
* The interface works on mobile
**5. Your app is ready**
You now have a working task tracker you can use immediately.
**1. You connect and sync your Google Sheet**
The sheet has columns: Deal Name, Company, Amount, Stage (New, Qualified, Proposal, Won, Lost), Close Date, Owner.
**2. DataAnalyzer Agent analyzes the schema**
The agent identifies:
* Domain: CRM / Sales (deal + amount + stage enum)
* Pipeline enum: Stage with 5 values → kanban board
* Currency field: Amount → KPI cards and charts
* Date field: Close Date → timeline filtering
**3. Agent asks clarifying questions**
"I see a sales pipeline with 5 stages and deal values. What should be the primary view?"
Options: Pipeline Board / Revenue Dashboard / Deal Table
**4. You refine through Q\&A**
You pick "Pipeline Board" as the primary view. The agent asks one more question about how to handle the Owner field.
**5. Build Agent generates the app**
The Build Agent creates:
* A kanban board with deals grouped by stage
* A dashboard with pipeline value KPIs and charts by stage
* A searchable deal table
* Comments on individual deals
* An AI copilot configured for sales questions
**6. Your app is ready**
Pre-populated with all your Google Sheet data, ready to use immediately.
## How iteration works
Gainable remembers everything about your project. When you ask for changes:
1. **Context is preserved** - The AI knows what's already built
2. **Existing features are protected** - New additions don't break what works
3. **Changes are targeted** - Only the relevant parts are modified
4. **Every change is versioned** - Each successful build creates a snapshot you can revert to
This means you can build incrementally and experiment freely. Start with something simple, add features one at a time, and undo anything that doesn't work out.
For how to phrase those requests, see [Changing a built app](/prompting/refining).
### Undo this build
Not happy with the latest change? Click the **undo button** (↩) on any build completion message to revert it instantly.
When you undo a build:
* **Everything from that step is reverted** — code, views, data models, routes
* **You can only undo one step at a time** — this prevents cascading issues and keeps your app stable
* **Your previous state is fully restored** — as if the build never happened
You can only undo the most recent build. To go further back, use Commit history.
### Commit history
Every build creates a versioned commit with a description of what changed. You can view and rollback to any point in your build history.
1. Click the **three-dot menu** (⋮) at the top of the Pages panel
2. Select **Commit history**
The history shows all your builds with descriptions and timestamps. Click **Rollback** on any previous entry to restore your app to that point.
When you rollback, Gainable automatically creates a safety snapshot of your current state before reverting. This means you can **undo a rollback** if you change your mind — just open Commit history again and click **Undo** to restore the state before the rollback.
## Technical foundation
Every Gainable app is built on a proven tech stack:
| Layer | Technology | What it does |
| ----------------- | ------------------ | --------------------------------------------- |
| **Database** | MongoDB | Stores all your data flexibly |
| **Backend** | Node.js + Express | Handles data operations |
| **Frontend** | Modern HTML/CSS/JS | Responsive interface that works on any device |
| **Real-time** | Socket.IO | Instant updates across users |
| **UI Components** | DaisyUI + Tailwind | Polished, themeable design |
| **Collaboration** | Weavy | Chat, files, and comments |
You don't need to know any of these technologies to use Gainable. This is just what powers your apps behind the scenes.
## Learn more
Deep dive into the agents that build your app
Connect external data sources and let Gainable design your app
Discover built-in features you can request
Add a conversational assistant to your app
Add autonomous agents that draft work in the background
# Skills
Source: https://docs.gainable.dev/concepts/skills
Built-in features you can request in your apps
## What are skills?
Skills are pre-built capabilities that Gainable can add to your applications. When you request a skill by name, the Build Agent uses specialized knowledge to implement it correctly.
You don't need to know how these work internally. Just request them by name in your prompts, and Gainable handles the implementation.
## Available skills
### Data Visualization
Request charts and graphs to visualize your data.
**Keywords to use:** chart, graph, visualization, pie chart, bar chart, line chart
**Example prompts:**
* "Add a pie chart showing deals by status"
* "Show monthly revenue as a line chart"
* "Add a bar chart comparing sales by region"
Available chart types:
* **Line charts** - Trends over time
* **Bar charts** - Comparing categories
* **Pie charts** - Showing proportions
* **Doughnut charts** - Proportions with a hole in the center
### Kanban Boards
Drag-and-drop boards for workflow management.
**Keywords to use:** kanban, board, columns, drag and drop, workflow
**Example prompts:**
* "Add a kanban board for task status"
* "Create a deal pipeline board"
* "Show projects as draggable cards in columns"
What you get:
* Draggable cards between columns
* Automatic status updates on drop
* Real-time sync across users
* Customizable column colors
### Collaboration
Add team communication features to your app.
**Keywords to use:** chat, messaging, comments, files, collaboration
**Example prompts:**
* "Add a team chat"
* "Add file sharing"
* "Add comments to tasks"
* "Add a group chat for the project"
Available features:
* **Chat** - Real-time messaging
* **Messenger** - Direct messages between users
* **Files** - Upload and share documents
* **Comments** - Add discussions to any item
* **Posts** - Activity feeds and announcements
### Real-time Updates
Make your app update instantly across all users.
**Keywords to use:** real-time, live updates, instant, sync
**Example prompts:**
* "Make the task list update in real-time"
* "Show live updates when deals change"
* "Sync data across all users instantly"
What this enables:
* Changes appear immediately for all users
* No page refresh needed
* Great for dashboards and team tools
### Sortable Lists
Reorder items by dragging them.
**Keywords to use:** sortable, reorder, drag to reorder, ranked list
**Example prompts:**
* "Let me reorder tasks by dragging"
* "Add a priority list I can sort"
* "Make the items draggable"
### AI Copilot
Embed an AI chat assistant in your app pages.
**Keywords to use:** copilot, AI assistant, AI chat, agent, smart assistant
**Example prompts:**
* "Add an AI copilot to the deals page"
* "Create an AI assistant that can look up customer data"
* "Add a smart chat panel that helps users find information"
What you get:
* Conversational AI interface on any page
* Data lookups through agent functions
* Document-backed answers from knowledge bases
* Conversation starters to guide users
## How to request skills
Just describe what you want in plain English. Gainable recognizes skill keywords and applies the right implementation.
```text Asking for charts theme={null}
"Add a dashboard with:
- Total deals count
- Pipeline value
- A pie chart showing deals by status
- A line chart showing deals closed per month"
```
```text Asking for kanban theme={null}
"I want to see my tasks as a kanban board with columns:
- To Do
- In Progress
- Review
- Done
Let me drag tasks between columns."
```
```text Asking for collaboration theme={null}
"Add a team chat to the project page where
team members can discuss the project."
```
## Combining skills
You can combine multiple skills in one app:
```text theme={null}
Build a project management app with:
- Projects with name, description, and status
- Tasks for each project with assignee and due date
- A kanban board view for tasks
- A dashboard with charts showing:
- Tasks by status (pie chart)
- Tasks completed per week (line chart)
- Team chat on each project page
- Real-time updates across the app
```
## Skill-specific tips
### Charts
* Good: "Pie chart showing deals grouped by status"
* Vague: "Add some charts"
* Good: "Show total revenue, average deal size, and deal count"
* Vague: "Show some KPIs"
### Kanban
* Good: "Columns: Backlog, In Progress, Review, Done"
* Vague: "Add a kanban board"
* Good: "Cards show title, assignee, and due date"
* Vague: "Show tasks on the board"
### Collaboration
* **Chat**: Group conversation for a specific context (project chat, team chat)
* **Messenger**: Direct messages between users (like Slack DMs)
* Good: "Add chat to the project detail page"
* Vague: "Add chat"
## Learn more
Deep dive into data visualization
Learn about kanban boards
Explore chat, files, and comments
Customize your app's look and feel
Embed a conversational assistant in your app
Add autonomous agents that draft work in the background
# Configuring a Copilot
Source: https://docs.gainable.dev/copilots/configuring
Define your Copilot's name, instructions, and personality
## How configuration works
When you describe the assistant you want, Gainable's Copilot Planner analyzes your request and the Copilot Builder creates it. The Copilot stays synced with your app. As you add data models or features, you can update the Copilot to work with them.
Tell Gainable what kind of assistant you want, what it should know, and how it should behave.
The planner determines the Copilot's name, instructions, data access, and configuration.
The builder sets up the Copilot with all its properties and connects it to your app.
As your app changes, you can update the Copilot through follow-up prompts.
## Properties
| Property | Description |
| ------------------------- | ------------------------------------------------------------------------- |
| **Name** | Display name shown in the Copilot header (e.g. "Sales Coach") |
| **Description** | Short summary of what the Copilot does, shown to users |
| **Instructions** | System prompt that defines behavior, tone, and rules |
| **Conversation starters** | Pre-defined prompts displayed as buttons to help users begin |
| **Web search** | Whether the Copilot can search the web for additional information |
| **Data access** | MCP Server connection to your app data. Optionally restricted with scopes |
| **Knowledge** | Uploaded documents the Copilot can reference when answering |
## Writing good prompts
Be specific about what the Copilot should do, who it helps, and what data it needs.
```text Good prompt theme={null}
Create a Sales Coach Copilot for our sales team.
It should:
- Help reps find deals by status, company, or amount
- Answer questions about our sales process
- Use a friendly, encouraging tone
- Start conversations with: "Show my open deals",
"What deals are closing this month?",
"Find deals over $10k"
- Have access to deals and contacts data
- Be able to search the web for company information
```
```text Vague prompt theme={null}
Add an assistant to help with sales stuff.
```
## Writing effective instructions
The Copilot's **instructions** act as its system prompt. They define how it behaves in every conversation. Good instructions include:
* **Role definition.** Who the Copilot is and what it specializes in.
* **Tone and personality.** How it should communicate.
* **Rules and boundaries.** What it should and shouldn't do.
* **Data awareness.** What data it has access to.
### Example instructions
```text theme={null}
You are Sales Coach, a helpful Copilot for the sales team.
Your role:
- Help reps find and analyze their deals
- Provide pipeline insights and status updates
- Suggest next steps based on deal stage
Tone:
- Friendly and encouraging
- Concise, prefer bullet points over long paragraphs
- Use data to back up suggestions
Rules:
- Always confirm before making changes to deals
- If you don't know something, say so
- Focus on deals and sales, redirect other questions
```
## Conversation starters
Conversation starters are pre-defined prompts displayed as clickable buttons when the Copilot opens. They help users discover what the Copilot can do.
### Best practices
* **Keep them short.** 3 to 8 words per starter.
* **Make them varied.** Cover different capabilities.
* **Be domain-specific.** Match your Copilot's purpose.
* **Use action language.** Start with verbs.
```text Good starters theme={null}
"Show my open deals"
"Deals closing this month"
"Find deals over $10k"
"Pipeline summary"
```
```text Weak starters theme={null}
"Help me"
"What can you do?"
"Tell me something"
"Hi"
```
## Web search
Enabling web search lets the Copilot look up external information during conversations.
**When to enable:**
* The Copilot needs current information (news, market data, company details)
* Users might ask questions beyond your app data and documents
**When to skip:**
* The Copilot only works with internal data
* You want to keep responses focused on your content
* Sensitive contexts where external information could be misleading
## Updating a Copilot
You can update Copilots through follow-up prompts at any time:
```text theme={null}
Update the Sales Coach Copilot to greet users by name
and add a conversation starter for "Top deals this week"
```
```text theme={null}
Change the support Copilot's tone to be more formal
and remove the web search capability
```
```text theme={null}
Add a new conversation starter: "Check order status"
```
## Tips
A Copilot that "helps with everything" is less useful than one focused on a specific area like sales, support, or HR.
Copilots feel more natural when they have a consistent personality. Specify whether it should be formal, casual, encouraging, or direct.
Tell the Copilot what data models it should use. "Give it access to deals and contacts" is much clearer than "let it see the data."
After creating a Copilot, try asking it the kinds of questions your users would ask. Refine instructions based on the results.
## Learn more
Connect your Copilot to app data via MCP
Upload documents for your Copilot
Place the Copilot chat in your app
Back to Gaia Copilot overview
Looking for the autonomous side? Agents run on their own
# Data access
Source: https://docs.gainable.dev/copilots/data-access
Connect Copilots to your app data through an MCP Server
## How Copilots access your data
Gaia Copilot connects to your app's data through an **MCP Server** (Model Context Protocol). This gives the Copilot flexible access to read, update, and insert data. No endpoint configuration or function definitions needed.
The MCP Server is how Copilots interact with your app's live data. Without it, a Copilot can only chat and reference knowledge base documents. With MCP data access, it can answer questions like "Show me all deals closing this month" by querying your data directly.
## How it works
Create your application with the data models and features you need.
Describe the assistant you want and what data it should access.
The MCP Server automatically connects your Copilot to your app's data. No manual configuration.
By default, the Copilot can access all your app's collections. Add scopes to restrict access when needed.
Copilots can also access data synced from external sources via [datasets](/building/data-connectors). Add sources like HubSpot or Google Sheets to a dataset, sync the data, and the Copilot can query it alongside your app data.
## Query capabilities
A Copilot with MCP data access can run powerful queries across your data:
| Capability | Example question | What happens |
| --------------------------- | -------------------------------------------- | -------------------------------------------- |
| **Filter** | "Show deals with status won" | Filters records by field value |
| **Sort** | "Show deals sorted by amount, highest first" | Orders results by a field |
| **Search** | "Find contacts at Acme Corp" | Searches text fields |
| **Date ranges** | "Deals closing this month" | Filters by date ranges |
| **Numeric ranges** | "Deals over \$10,000" | Filters by numeric thresholds |
| **Limits** | "Show the top 5 deals" | Limits result count |
| **Combined filters** | "Open deals over \$10k closing this quarter" | Applies multiple filters at once |
| **Aggregate** | "What's the average deal size by status?" | Groups and calculates sums, averages, counts |
| **Join across collections** | "Show deals with their contact details" | Combines data from related collections |
| **Insert** | "Add a new deal for Acme Corp" | Creates new records |
| **Update** | "Mark that deal as won" | Modifies existing records |
## Scopes
By default, a Copilot can access **all collections** in your app. Use **scopes** to restrict it to specific collections when you want to limit what it can see.
### When to use scopes
* **Customer-facing Copilots.** Restrict to only the data relevant to the user's context.
* **Role-specific Copilots.** A sales Copilot only needs deals and contacts, not HR data.
* **Privacy-sensitive apps.** Limit access to prevent the Copilot from exposing sensitive data.
### Prompt examples
```text theme={null}
Give the Sales Coach access to only deals and contacts.
It shouldn't see employee or payroll data.
```
```text theme={null}
Restrict the support Copilot's data access to orders
and tickets only.
```
If you don't specify scopes, the Copilot can access all app collections. This is fine for most internal tools. Only add scopes when you need to restrict access.
## Prompt examples
```text theme={null}
Give the Sales Coach Copilot access to deals and contacts
so it can look up pipeline data and find contact information.
```
```text theme={null}
Add data access to the support Copilot so it can look up
orders by order number and check order status.
```
```text theme={null}
Let the HR Copilot query employee records and
time-off requests.
```
Your app must be built with data models before a Copilot can access data. The MCP Server connects to your existing collections. Build your app first, then configure the Copilot.
## Updating data access
You can update what data a Copilot can access through follow-up prompts:
### Expanding access
```text theme={null}
Give the Sales Coach access to the products data
so it can answer questions about pricing.
```
### Restricting access
```text theme={null}
Restrict the Sales Coach to only deals and contacts.
Remove access to everything else.
```
### Adding write capabilities
```text theme={null}
Let the support Copilot update order status
and add notes to customer records.
```
## Best practices
Begin by giving Copilots the ability to read and query data. Add write capabilities (inserting or updating records) only when needed.
Internal Copilots usually don't need scopes, they can access everything. For customer-facing Copilots, use scopes to restrict access to only the relevant collections.
A sales Copilot needs deals and contacts. A support Copilot needs orders and tickets. Keep access relevant to what the Copilot does.
Data access handles live data queries. Knowledge bases handle static reference material. Together, the Copilot can look up a customer's order *and* reference your return policy to answer a question.
## Copilot vs Agents data access
[Gaia Autopilot](/autopilot/overview) use a different model. Instead of a single MCP Server, agents call a fixed [tool registry](/autopilot/tools) (`query_collection`, `update_records`, `send_email`, `draft_for_approval`, and so on) with explicit risk tiers and an action log. Use the right one for the job:
* **Copilot reads and writes through MCP** for synchronous, user-driven questions.
* **Agents call typed tools** for asynchronous, autonomous work where every action is logged and high-risk steps go through draft-and-approve.
## Learn more
Set up name, instructions, and behavior
Add document references to your Copilot
Place the Copilot chat in your app
How app data is structured
Group external data sources and attach them to your app
How autonomous Agents access data and take action
# Embedding
Source: https://docs.gainable.dev/copilots/embedding
Place the Copilot chat interface on any page of your app
## What is the Copilot component?
The Copilot is rendered with the `` component. You can embed it on any page of a Gainable app. Each instance is linked to one configured Copilot, so you can place several across the app, each connected to a different one.
For example, a sales Copilot on the deals page and a support Copilot on the tickets page. They share the underlying chat component but have different names, instructions, knowledge, and data access.
## Adding a Copilot to a page
Describe where you want the Copilot and which one it should use:
```text theme={null}
Add the Sales Coach Copilot to the deals page.
```
```text theme={null}
Put a chat panel on the support dashboard
using the Support Assistant Copilot.
```
```text theme={null}
Add Copilots to each main page:
- Deals page: Sales Coach
- Support page: Support Assistant
- HR page: HR Helper
```
## What users see
When a Copilot is placed on a page, users see:
* **Name and description** in the chat header
* **Conversation starters** as clickable buttons to begin
* **Message input** for typing questions
* **Chat responses** with formatted text, lists, and data from MCP and knowledge
## Capabilities
The embedded Copilot inherits all capabilities from its configuration:
| Capability | Description |
| ------------------------- | -------------------------------------------------------------- |
| **Chat** | Natural language conversation |
| **Data access (MCP)** | Read, update, and insert app data through the MCP Server |
| **Knowledge queries** | Reference uploaded documents from the Copilot's knowledge base |
| **Web search** | Search the web if enabled |
| **Conversation starters** | Pre-defined prompts shown as buttons |
## Placement patterns
### Specific page placement
Place a Copilot on the page where it's most relevant:
```text theme={null}
Add the Sales Coach Copilot to the deals page.
```
### Multiple pages, same Copilot
Use the same Copilot on several pages:
```text theme={null}
Add the Support Assistant Copilot to both the
tickets page and the customer detail page.
```
### Different Copilots per page
Match the Copilot to the page context:
```text theme={null}
Add Copilots:
- Deals page → Sales Coach
- Tickets page → Support Assistant
- Dashboard → Analytics Helper
```
## Copilot vs team chat
The Copilot and [team chat](/building/collaboration) serve different purposes:
| | Copilot | Team chat |
| --------------- | ---------------------------------- | ------------------------------- |
| **Purpose** | Conversational assistant for users | Human-to-human messaging |
| **Powered by** | Gaia Copilot | Weavy collaboration |
| **Responds** | Gaia, with data access | Other team members |
| **Best for** | Questions, lookups, guidance | Discussions, decisions, updates |
| **Data access** | Queries app data via MCP Server | No direct data access |
You can have both on the same page. Use team chat for human collaboration and the Copilot for AI-assisted data lookups and guidance.
## Copilot vs Autopilot
The Copilot is reactive. The user asks; it answers. [Autopilot](/autopilot/inbox) is the user-facing surface for [Gaia Autopilot](/autopilot/overview), which run on their own and draft work for approval. The two are designed to live side by side:
* The Copilot answers a sales rep's question in chat.
* Autopilot lands the same rep's "stalled deal" follow-up draft in their inbox before they ask.
## Full end-to-end example
Here's a complete prompt that builds an app, configures a Copilot, and embeds it:
```text theme={null}
Build a CRM with:
- Companies (name, industry, size)
- Contacts (name, email, phone, linked to company)
- Deals (name, amount, status, linked to company and contact)
- Dashboard with pipeline value and deals by status chart
Create a Sales Coach Copilot that:
- Helps reps find deals and contacts
- Can query all CRM data
- Uses a friendly, encouraging tone
- Has conversation starters:
"Show my open deals"
"Deals closing this month"
"Find contacts at a company"
"Pipeline summary"
Add the Sales Coach Copilot to the deals page.
```
This single prompt creates the app, configures the Copilot with data access, and embeds it on the deals page.
## Best practices
Put a Copilot on pages where users are likely to have questions or need to look up data. A deals page Copilot is more useful than one on a simple settings page.
If you have multiple Copilots, use ones that are relevant to each page. A sales Copilot on the deals page, a support Copilot on the tickets page.
Good conversation starters show users what the Copilot can do. Include starters that demonstrate its key capabilities.
Copilots work alongside team chat, kanban boards, dashboards, and other features. They add conversational AI without replacing existing collaboration tools.
## Learn more
Set up the Copilot behind the chat
Connect to app data via MCP
Add document references
Team chat and other collaboration features
The proactive side, where Agents draft work for approval
# Knowledge bases
Source: https://docs.gainable.dev/copilots/knowledge
Upload documents your Copilot can reference when answering
## What are knowledge bases?
Knowledge bases let you upload documents that Gaia Copilot can reference during conversations. This is powered by **RAG** (retrieval-augmented generation). When a user asks a question, the Copilot searches your uploaded documents for relevant information and uses it to generate accurate answers.
Think of a knowledge base as a reference library for the Copilot. Instead of making up answers, it can look up the right information from your documents.
## How it works
Set up a Copilot with a name, instructions, and data access.
In the Gainable interface, open the Copilot's detail panel.
The folder icon opens the knowledge base manager for that Copilot.
Drag and drop or select files to upload. The Copilot can now reference them.
## What to upload
Sales playbooks, process guides, standard operating procedures
Product catalogs, feature descriptions, specifications, pricing sheets
Company policies, compliance documents, terms of service, HR guidelines
Onboarding docs, training manuals, FAQs, troubleshooting guides
## Use cases
Upload your product catalog and pricing sheet. The Copilot can answer questions like "What's the price for the Enterprise plan?" or "Compare the Pro and Business tiers" using your product data.
Upload troubleshooting documentation and FAQs. The Copilot can walk users through solutions. "My printer won't connect" triggers a lookup of your troubleshooting steps for printer connectivity.
Upload the employee handbook, PTO policies, and benefits guide. Employees can ask "How many vacation days do I get?" and get accurate answers from your policy documents.
Upload onboarding guides and training docs. New hires can ask "What's the process for setting up my development environment?" and get step-by-step instructions from your materials.
## Managing knowledge bases
Knowledge bases are managed through the UI using the folder icon on the Copilot detail panel, not through chat prompts. You can add, remove, and replace documents at any time through this interface.
To update a knowledge base:
1. Open the Copilot detail panel
2. Click the folder icon
3. Add new documents or remove existing ones
4. Changes take effect immediately
## Combining knowledge with data access
Knowledge bases and [data access](/copilots/data-access) work together to give the Copilot maximum capability:
| Source | Best for | Example |
| --------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **Data access (MCP)** | Live app data that changes frequently | "How many open deals do I have?" |
| **Knowledge** | Static reference material and documentation | "What's our refund policy?" |
| **Both** | Questions that need data context plus reference material | "This customer wants a refund. What's the policy and what's their order history?" |
```text theme={null}
Create a support Copilot that can:
- Look up customer orders (data access)
- Reference our return policy and FAQ (knowledge base)
- Search the web for product compatibility info (web search)
```
## Best practices
Upload specific, relevant documents rather than entire document libraries. A focused knowledge base produces more accurate answers.
Documents with headings, sections, and organized content work better for retrieval. Well-structured documents help the Copilot find the right information faster.
If your policies or product information changes, replace the old documents with updated versions. The Copilot always uses the latest uploaded content.
After uploading documents, ask the Copilot questions your users would ask. Verify it finds and uses the right information.
## Learn more
Set up your Copilot's configuration
Connect to live app data via MCP
Place the Copilot chat in your app
Back to Gaia Copilot overview
# Gaia Copilot
Source: https://docs.gainable.dev/copilots/overview
The conversational AI inside every Gainable app
## What is Gaia Copilot?
Gaia Copilot is the conversational layer of every Gainable app. The user asks; the Copilot answers. It reads live app data through an MCP Server, references documents you've uploaded as knowledge, and can take action when asked.
The Copilot is reactive. It waits for a question. If you want AI that runs on its own, watches data, and drafts work without being asked, that's [Gaia Autopilot](/autopilot/overview). The two are designed to work together.
**Build agents vs Gaia Copilot.** Gainable uses [build agents](/concepts/agents) (Planner, Build, Validation, Conversation) to *create* your app. Gaia Copilot is different. It's a configurable assistant that lives *inside* your finished app and helps your users.
## What Gaia Copilot can do
Answer questions using uploaded knowledge and look up live order or account data
Query your app data, filter results, and surface insights through conversation
Walk users through processes with conversation starters and step-by-step guidance
Reference uploaded documents like policies, playbooks, and product catalogs
## What Gaia Copilot does *not* do
The Copilot is reactive by design. It doesn't:
* Run on its own without being asked
* Watch your data for changes in the background
* Draft work proactively before a user opens the chat
* Send outbound emails, Slack messages, or webhooks on a schedule
That's the job of [Gaia Autopilot](/autopilot/overview). Use Copilot for "the user asks, the Copilot answers." Use Agents for "work shows up before the user asks."
## How it fits together
Create your application with data models, views, and features.
Describe the assistant you want. Gainable creates it with a name, instructions, and personality.
The Copilot automatically gets access to your app's data through an MCP Server. It can query, update, and insert records.
Upload documents (PDFs, guides, policies) the Copilot can reference when answering questions.
Place the `` chat interface on any page so users can interact with it.
## Capabilities
| Capability | Description |
| ------------------------- | --------------------------------------------------------------- |
| **Chat** | Natural language conversation with your users |
| **Data access (MCP)** | Read, update, and insert data through the MCP Server |
| **Knowledge bases** | Reference uploaded documents (RAG) |
| **Web search** | Search the web for additional context when enabled |
| **Conversation starters** | Pre-defined prompts that help users begin |
| **Datasets** | Query data brought in via [datasets](/building/data-connectors) |
## Prompt examples
You can request a Copilot in natural language:
```text theme={null}
Create a Sales Coach Copilot that helps reps find deals,
check pipeline status, and get selling tips.
Give it access to the deals and contacts data.
Add it to the deals page.
```
```text theme={null}
Add a support assistant to the support page that can
look up customer orders and answer questions from
our FAQ document.
```
## Test for which one applies
> Does the user have to ask first?
>
> * **Yes** → Gaia Copilot
> * **No** (work shows up before they ask) → [Gaia Autopilot](/autopilot/overview)
## Learn more
Define name, instructions, and personality
Connect Copilots to your app data via MCP
Upload documents the Copilot can reference
Place the chat interface on any page
Looking for the autonomous side? Agents run on their own
Group external data sources and attach them to your app
# Introduction
Source: https://docs.gainable.dev/introduction
Turn your ideas into working apps with AI-powered development
## What is Gainable?
Gainable is a no-code platform that lets non-technical teams build custom internal tools, dashboards, and workflows in minutes. Start from an idea and describe what you need, or connect your existing data sources and let AI build an app around them. Either way, you get a complete, working application in minutes.
You don't need to write code, wait on an engineering backlog, or sign a \$50K contract. Just pick a path and start building.
Describe what you want in plain English and AI creates everything for you.
Connect Google Sheets, HubSpot, Stripe, or other sources and build on top of your data.
Either path works in the browser or from the AI agent you already use — Claude Code, Claude, Cowork, or Codex. See [Use your favorite agent](#use-your-favorite-agent).
## Who is Gainable for?
Gainable is built for teams who need custom tools but don't have the time, budget, or engineering resources to build them from scratch:
Build custom CRMs, client portals, and operations hubs tailored to your workflow instead of paying for 10 SaaS tools that don't fit.
Connect campaign spend to revenue outcomes. Build live dashboards for attribution, lead scoring, and audience segmentation.
Unify data scattered across 5 or more systems into a single view. Build pipeline dashboards, coordination tools, and executive reports.
Consolidate roadmaps, feedback, and OKR tracking into one place, connected to your backlog and support channels.
Build the pipeline view your CRM won't give you. Personal deal boards, forecast trackers, and account-specific tools with live data sync.
If you've ever waited weeks for a custom dashboard or report, Gainable lets you build it yourself in minutes.
## What can you build?
Gainable excels at building data-driven business applications:
Track deals, manage contacts, and monitor your sales pipeline
Manage tasks, milestones, and team assignments
Visualize your data with charts, KPIs, and real-time updates
Build kanban boards, approval flows, and process trackers
Add intelligent AI assistants that can answer questions, analyze data, and guide users
## How it works
Gainable gives you two ways to create an app:
**Start from an idea** — Describe what you want in plain English. The Planner Agent breaks down your request, the Build Agent generates your app, and validation ensures quality.
**Start from your data** — Connect an external data source like Google Sheets or HubSpot. The DataAnalyzer agent examines your schema, recommends features through interactive Q\&A, and produces a build specification.
Both paths lead to the same result: a complete, working app with a database, modern UI, and real-time updates.
You can also combine both approaches: connect data sources and describe additional features you want on top of them.
## Use your favorite agent
You don't have to build in the browser. The **Gaia harness** is accessible via a remote [MCP](https://modelcontextprotocol.io) server, so the AI agent you already work in can drive it for you — describe what you want and it builds, refines, and publishes the app on your behalf.
There's one URL and nothing to install:
```
https://build.gainable.dev/mcp
```
Add it, sign in through your browser, and start asking:
```
Build me an app from this planning spreadsheet
Add KPI cards to the top of the sponsors view
Publish it
```
Build from your terminal, in the folder you're already working in.
Add it once and it's there in chat, Cowork, Desktop, and mobile.
The same connector in OpenAI Codex.
Any MCP client can connect to the same URL.
It's the same harness either way — the same contract conversation, Build Agent, and validators as the web app, with nothing downgraded. So an operator can iterate in Cowork while an engineer works from the terminal, and both are editing the same app.
Prefer to keep the code in your own hands? Grant **author mode** at sign-in and your agent writes the views, routes, and models itself, checked by the same validators the Build Agent uses. See [the connector overview](/mcp/overview).
## What's included in every app?
Every Gainable app comes with:
| Feature | Description |
| -------------------------- | ------------------------------------------------------------------------------------------ |
| **Database** | Automatic data storage that grows with your needs |
| **Modern UI** | Responsive design that works on any device |
| **Real-time updates** | See changes instantly as data is added or modified |
| **Charts & visualization** | Built-in support for data visualization |
| **Team collaboration** | Chat, file sharing, and comments (via Weavy integration) |
| **User management** | Built-in authentication and user accounts |
| **Gaia Copilot** | A conversational assistant in every app that reads live data and references your knowledge |
| **Gaia Autopilot** | Autonomous agents that watch data, draft work, and land it in your inbox for approval |
| **Datasets** | Connect and group external data sources like HubSpot, Google Sheets, and Stripe |
## Next steps
Build your first app in 5 minutes
Connect your existing data and let AI design the app
Build from Claude Code, Claude, Cowork, or Codex
Learn how Gainable builds your app
Write better prompts for better apps
See real prompts you can copy
Add a conversational assistant to your app
Add autonomous agents that draft work in the background
# Claude and Cowork
Source: https://docs.gainable.dev/mcp/claude
Add the Gaia connector to Claude chat, Cowork, and Claude Desktop
The Gaia harness is accessible via a **remote MCP server**, which is what Claude calls a *custom connector*. Add it once and it appears everywhere you use Claude — chat on the web, Cowork, Desktop, and mobile.
This is the surface that needs no terminal at all. An operator with a spreadsheet can build the app themselves, in the same chat where they'd have asked someone else to do it.
Claude connects to the connector from Anthropic's cloud, not from your device — so there is nothing to install locally and nothing to keep running. It works the same on mobile as on desktop.
## Add the connector
In Claude, go to **Settings → Connectors** (some versions label this **Customize → Connectors**).
Click **Add custom connector** (on some versions: **+** → *Add custom connector*), then enter:
```
https://build.gainable.dev/mcp
```
Leave **Advanced settings** alone — the connector registers itself, so you don't need to supply an OAuth client ID or secret.
Click **Add**, then **Connect**. Your browser opens the Gainable sign-in, you pick which account to connect, and you're done.
The consent screen has up to three checkboxes — for your **datasets**, for **managing people** on the account, and for [author mode](/mcp/tools#author-mode). Building, changing, publishing and sharing apps works without any of them. See [what you're granting](/mcp/overview#what-youre-granting).
An Owner or Admin adds it once for the whole organization; members then connect their own Gainable account to it.
Go to **Admin settings → Connectors** (also shown as **Organization settings → Connectors**), click **Add custom connector**, and enter:
```
https://build.gainable.dev/mcp
```
Click **Add**. It now appears for everyone in the organization, labelled **Custom**.
Each member opens **Settings → Connectors**, finds **Gainable (Gaia)** under the Custom label, and clicks **Connect** to sign in with their own Gainable account.
Each member's connection is bound to their own Gainable account, so apps land where that person has access. The admin adds the *server*; they don't share a login.
## Turn it on in a conversation
Adding a connector doesn't switch it on everywhere. In any chat or Cowork session, use the **+** button in the message box → **Connectors**, and toggle **Gainable (Gaia)** on.
Then check it:
```
List my Gainable apps
```
Your apps listed back means everything is connected.
## Build something
Attach a spreadsheet to the message and ask:
```
Have Gaia build me an app from this planning sheet
```
Claude imports the workbook, asks you a handful of questions about your own data — which sheet is reference material, whether a "TOTAL" row is a summary to drop — then walks the contract conversation and runs the build. Give it 90–180 seconds at the end and paste-ready URLs come back.
**Name Gaia in the first message.** Without it, *"build me an app from this sheet"* is a request Claude can answer by itself — and it will, without ever calling the connector. See [Say "Gaia" in your first message](/mcp/overview#say-gaia-in-your-first-message).
No spreadsheet handy? Download the [event planning sample](https://www.gainable.dev/samples/horizon-summit-2026-planning.xlsx) and attach that.
From there it's ordinary conversation — the app is in context now, so you don't need to name Gaia again:
```
Add a probability column to the deals table
Make the sponsors view the home page
Publish it
```
## Cowork specifics
Cowork uses the same account-level connector list as Claude chat, so if you added it above there is nothing more to add. Two things behave differently, and both are worth knowing.
### Name the app you mean
Cowork re-establishes its connection before each tool call, so the connector can't tell one Cowork conversation from another on the same account. Rather than guess — and risk editing a different app you have open elsewhere — **it refuses to assume and asks which app you mean.**
In practice that means the first request in a session should name the app:
```
In the Horizon Summit tracker, add a venue capacity column
```
Once Claude has the app's `projectId` from `apps_list` or from creating it, it carries it forward for the rest of the conversation. Claude Code doesn't hit this because a folder's `.gaia/project.json` answers the question for it.
This is a guard, not a limitation. The "currently active" app is remembered per **account**, so on a connection the server can't isolate, a remembered app is as likely to belong to another session as to yours — and building into the wrong app looks exactly like success until much later.
### Give it your context
A Gainable app is shaped by things the connector cannot know: what you call things, your currency and date format, who uses the app, what must never appear on a list view.
Ask Claude to **set up the project** and it returns a starter you can use either way:
* **A Cowork project with a folder** — it writes a `README.md`, a `CLAUDE.md` for your domain context, and `data/` and `apps/` folders.
* **A chat-only project** — there is nowhere to write files, so it shows you a block to paste into the project's **Instructions** (or the *"What are you trying to achieve?"* box when you create one). That box is the only place project-level context survives without a folder.
Either way the template is placeholders in angle brackets — fill them in, or it does nothing.
### If a file upload fails
Cowork sandboxes can have network egress switched off, which blocks the direct upload path for spreadsheets. Claude will fall back to sending the file in slices, which works but costs context. To use the fast path, an admin can enable **Settings → Capabilities → Code execution → Allow network egress**.
If Claude offers to trim, split, or convert a spreadsheet "so it fits" — say no. The analyzer reads the real workbook, including section-divider rows, banded sheets, and reference tabs, to decide the schema. A slimmed file doesn't import a smaller app; it imports a different and wrong one.
## How it compares to Claude Code
Same connector, same tools, same harness. What differs is what the client can see:
| | Claude / Cowork | Claude Code |
| --------------------------- | ----------------------------------------------- | --------------------------------------- |
| Setup | Add a URL in Settings | `claude mcp add` |
| Which app you're working on | Name it in the conversation | `.gaia/project.json` in the folder |
| Project context | Project Instructions | `CLAUDE.md` |
| Spreadsheets | Attach to the message | Read from the working folder |
| A record of the app | The chat, plus project files if it has a folder | An `.md` written to the folder |
| Optional scopes | Available if granted | Available if granted |
Both surfaces edit the same app. An operator can iterate in Cowork while an engineer works from the terminal, so handing off no longer means handing over.
## Manage the connection
* **Change or revoke it in Claude** — **Settings → Connectors**, then the three-dot menu.
* **Change or revoke it in Gainable** — [Account → Connections](https://build.gainable.dev/account/connections). This is also where you turn any of the three optional [scopes](/mcp/tools#scopes) — datasets, people, author mode — on or off without reconnecting.
## Next steps
Every tool the connector exposes.
The same connector, from your terminal.
# Claude Code
Source: https://docs.gainable.dev/mcp/claude-code
Add the Gaia connector to Claude Code and build apps from your terminal
Two commands and you're building. [Claude Code](https://claude.com/claude-code) talks to the Gaia connector over MCP, so describing a change is enough — Claude picks the right tool, relays the harness's questions back to you, and pastes the resulting URL into your session.
## Add the connector
```bash theme={null}
claude mcp add --transport http gainable https://build.gainable.dev/mcp
```
Add `--scope user` to make it available in every project instead of just this one.
```bash theme={null}
claude
```
```
> /mcp
```
Pick **gainable**, choose **Authenticate**, and finish in the browser. Your token is stored in your OS keyring.
The consent screen has up to three checkboxes — for your **datasets**, for **managing people** on the account, and for [author mode](/mcp/tools#author-mode). Building, changing, publishing and sharing apps works without any of them. Tick what you need now or later, from [Account → Connections](https://build.gainable.dev/account/connections), without reconnecting. See [what you're granting](/mcp/overview#what-youre-granting).
```
> List my Gainable apps
```
Your apps listed back means everything is connected.
## Build something
Drop a spreadsheet in an empty folder and ask:
```
> Have Gaia build an event planning app using the Excel file in this folder
```
Claude imports the workbook, walks the contract conversation with you, then runs the build pipeline. That last stage takes 90–180 seconds and streams back as a live checklist.
No spreadsheet handy? Download the [event planning sample](https://www.gainable.dev/samples/horizon-summit-2026-planning.xlsx) and use that.
Note the **"Have Gaia"** at the front. The first message has to name the product or Claude will just answer it itself, without ever calling the connector — see [Say "Gaia" in your first message](/mcp/overview#say-gaia-in-your-first-message).
Then keep talking. The app is in context now, so follow-ups don't need to name it:
```
> add a probability column to the deals table
✓ completion ready: 2 files changed
> Publish it
{"event":"app_published","payload":{"url":"https://deals-pipeline.gainable.app"}}
```
Each refinement is a single turn: the harness's planner decides, the Build Agent edits, validators check, and the summary streams back.
## Why the terminal is the best seat
Claude Code has a working directory, and the connector uses it.
When a tool returns a project anchor, Claude writes `.gaia/project.json`. Tomorrow's session in that folder picks up the same app instead of whatever was last active on your account.
A `CLAUDE.md` in the folder tells the harness what you call things, your currency and date format, who uses the app. `project_setup` writes a starter if you don't have one.
After a build, Claude writes `.md` with the launcher URL, the public URL, and one line on what it does — so the app isn't just a link that scrolls away.
Claude asks for an upload URL and `curl`s the spreadsheet straight there. A 5 MB workbook costs zero tokens.
## Multiple accounts
If you connect more than one Gainable account — a personal one and a work one, say — give them distinct names:
```bash theme={null}
claude mcp add --transport http gainable-work https://build.gainable.dev/mcp
```
Claude will ask which one to use before creating anything, because that choice decides where the app lands.
## Manage the connection
```bash theme={null}
claude mcp list # what's registered, and whether it's connected
claude mcp get gainable # details for one server
claude mcp remove gainable # disconnect
```
To sign out without removing the server, revoke the connection at [Account → Connections](https://build.gainable.dev/account/connections) and re-authenticate with `/mcp`.
## Troubleshooting
Run `claude mcp list` to see the error. The most common cause is an expired or revoked token — re-authenticate from `/mcp`. Check [Account → Connections](https://build.gainable.dev/account/connections) to confirm the connection still exists.
It probably didn't. `build action:"run"` takes 90–180 seconds and may hand the wait back with `outcome:"running"` before it finishes. The right move is `status`, which Claude should call on its own. **Never ask it to run the build again** — the first one is still going server-side, and a second start creates duplicate work someone has to clear by hand.
The active app is remembered per *account*, not per conversation, so a session in another folder can leave a different one selected. Ask Claude to select the app by name, or keep a `.gaia/project.json` in the folder — that file is authoritative and survives between sessions.
Tell it to relay the connector's questions verbatim. Layout, scope, and which field identifies a row are your calls; answering them for you produces an app you didn't ask for.
## Next steps
Every tool the connector exposes.
The same connector, away from the terminal.
# Codex
Source: https://docs.gainable.dev/mcp/codex
Add the Gaia connector to OpenAI Codex and build apps from your terminal
[OpenAI Codex](https://developers.openai.com/codex) speaks MCP, so the Gaia connector works there the same way it does in Claude Code — two commands, then you're building.
## Add the connector
```bash theme={null}
codex mcp add gainable --url https://build.gainable.dev/mcp
```
```bash theme={null}
codex mcp login gainable
```
Your browser opens, you sign in, and you pick which account to connect. The token is stored in your OS keyring.
The consent screen has up to three checkboxes — for your **datasets**, for **managing people** on the account, and for [author mode](/mcp/tools#author-mode). Building, changing, publishing and sharing apps works without any of them. Tick what you need now or later, from [Account → Connections](https://build.gainable.dev/account/connections), without reconnecting. See [what you're granting](/mcp/overview#what-youre-granting).
```bash theme={null}
codex mcp list
```
Then, in a session:
```
> List my Gainable apps
```
## Build something
Drop a spreadsheet in an empty folder and ask:
```
> Have Gaia build an event planning app using the Excel file in this folder
```
Codex imports the workbook, walks the contract conversation with you, then runs the build pipeline. When the harness needs a decision it presents the options as a numbered list in chat — reply with the number or the option name and it continues.
No spreadsheet handy? Download the [event planning sample](https://www.gainable.dev/samples/horizon-summit-2026-planning.xlsx) and use that.
Note the **"Have Gaia"** at the front. The first message has to name the product or Codex will just answer it itself, without ever calling the connector — see [Say "Gaia" in your first message](/mcp/overview#say-gaia-in-your-first-message).
Then keep talking. The app is in context now, so follow-ups don't need to name it:
```
> add a probability column to the deals table
> publish it
```
## Long builds
`build` takes 90–180 seconds and a `chat` turn can take over a minute. If your client doesn't send a progress token, the connector hands the wait back after about 50 seconds with `outcome:"running"` rather than risk the call being abandoned.
That is **not** a failure. The right response is a `status` call, which Codex should make on its own.
Never ask Codex to run the build again to check on it. The first build is still running server-side, so a second start isn't a retry — it creates duplicate work someone has to clear by hand. The same goes for re-sending a `chat` message.
## Manage the connection
```bash theme={null}
codex mcp list # what's registered
codex mcp logout gainable # drop the stored token
codex mcp remove gainable # remove the server
```
You can also review or revoke the grant from [Account → Connections](https://build.gainable.dev/account/connections).
## How Codex differs from Claude Code
Same connector, same tools, same harness — only the client's interface differs:
| | Claude Code | Codex |
| ---------------------------- | --------------------------------- | -------------------------- |
| Add the server | `claude mcp add --transport http` | `codex mcp add --url` |
| Sign in | `/mcp` → Authenticate | `codex mcp login gainable` |
| Forwarding harness questions | `AskUserQuestion` picker | Numbered list in chat |
| Build progress | Live task list | Plain-text stage updates |
The connector is an MCP server, not a shell command, so there are no per-command approval rules to configure. Codex asks once when a tool is first used, and that's it.
## Next steps
Every tool the connector exposes.
The same connector, in Claude Code.
# Recurring data pipelines
Source: https://docs.gainable.dev/mcp/datasets
Collect data on a schedule and keep a Gainable dataset in sync with it
Connector-backed datasets pull from systems Gainable already integrates with. When your data lives somewhere else — an internal API, a partner feed, something you assemble from several places — you can write a small script that collects it and keep a dataset in sync with it.
The shape is **create once, sync forever**:
```
Create a dataset called "Ops Metrics" from what collect.js prints
→ types the columns, picks a stable key, prints the write contract
Run collect.js and sync Ops Metrics
✓ metrics: 214 rows (+3 ~209 -2)
```
A dataset created this way is standalone. Attach it to an app whenever you want a UI over it, the same as any other dataset.
The dataset tools sit behind the `datasets` [scope](/mcp/tools#scopes) — the *"Also let it work with your datasets"* checkbox when you connect. If your client can't find them, tick it at [Account → Connections](https://build.gainable.dev/account/connections); no reconnect needed.
## The three rules
Everything else follows from these.
Every sync **replaces the entire dataset**. Your script must emit every row that should exist, every time — never a delta, never just today's rows. Rows absent from the payload are deleted.
This is deliberate. It is how corrections and deletions propagate, and it means a missed run costs nothing: the next run reconciles. There is no drift between your source and the dataset.
The dataset remembers the exact keys from your seed data. A sync missing any of them is rejected wholesale and **nothing is written**.
Adding a key is safe — extra keys are ignored. Renaming or removing one is not. To change the shape, create a new dataset.
`dataset_schema` returns exactly what to emit — required keys, the primary key, and the expected form of every field. Never infer the shape from memory of your seed data.
## Set it up
A script that prints your rows as JSON on stdout. Anything that can produce JSON works — Node, Python, a shell pipeline.
Seed it with **5–20 representative real rows**. The analyzer infers column types and picks the primary key from actual values, and that choice is frozen for the dataset's life — a one-row seed produces a schema you cannot fix later.
Ask your client to create it from the collector's output — that's `dataset_sync` with `action:"create"`. The analyzer will ask a clarifying question or two, usually about which column should be the primary key. **Those are your calls, not the model's**; a good client relays them rather than answering them.
The final result carries the `collectionId` and the full write contract, so there's no second call to make.
The contract's `requiredKeys` lists what to emit, and every field carries a `writeAs` describing its exact form — *"JSON number, not a formatted string"*, *"ISO 8601 date string"*, and so on. Keys are matched exactly and are case-sensitive.
Ask for the dataset's rows — `dataset_records` — after the first real sync. It reads back the stored values, so *"did the sync land, and did the dates survive as dates"* is one question rather than a whole app you have to build to find out.
See [Putting it on a schedule](#putting-it-on-a-schedule) below.
### Creating and syncing are one tool
`dataset_sync` does both, but it will never quietly switch between them:
| What you want | Ask for |
| ------------------------------------------------- | ------------------------------------------- |
| A new dataset, every time | `action:"create"` |
| Replace an existing one | `action:"sync"` — the default |
| Seed on the first run, replace on every run after | `action:"sync"` with `createIfMissing:true` |
A plain sync against a name that matches nothing is an **error**, and nothing is created. That's deliberate: the server can't tell a typo from a new dataset, so without the guard a mistyped name on a nightly job would mint *"Ops Metrics (2)"* and fill it happily while the real dataset went stale in silence. `createIfMissing` is for an unattended collector that owns its dataset — not for a sync you're driving by hand, where catching the typo is the point.
## Two collector patterns
Which one you need depends on your source.
**The source returns full current state** — "list all deals", "list all repos". Emit it straight through. No local state at all, and the loop is self-healing.
**The source is append-only** — daily metrics, event logs. Something has to accumulate history, because a sync deletes rows absent from the payload. Your script owns that: merge new rows into a local store, then emit the whole store.
Prefer the stateless shape wherever the source supports it. If you must keep a local store, write it atomically (temp file, then rename) so a crash never leaves a truncated snapshot for the next run to pick up.
## Choosing a primary key
This is the one decision worth slowing down for, because it cannot be changed later.
Your app derives each row's comment and file thread from its primary key value. Use a **natural key that comes from the source itself** — an upstream record ID, a canonical slug. Never an array index, a row number, a collection timestamp, or a hash of fields that can be edited.
A rotating primary key silently destroys every comment and file attached to those rows on the next sync — and the row counts look perfectly normal while it happens.
The connector guards against this: it refuses a sync whose primary keys barely overlap what is already stored. `force` overrides the guard and should only be used when you genuinely intend that turnover.
If a key value does legitimately change — you fix a typo in the column the analyzer picked — Gainable matches the row back by its other columns and carries its identity forward, so attached comments and files survive.
## Putting it on a schedule
The sync goes through the connector, so a scheduled sync is a scheduled **agent** run. Two ways to get one, depending on where the connector lives.
Set the sync up as recurring work in Cowork. Once the connector is [added and enabled](/mcp/claude), schedule a task that says what to collect and where to put it:
```
Every weekday at 07:00, run the ops metrics collector and have Gaia
sync the result to the Ops Metrics dataset.
If the collector fails, don't sync — tell me instead.
```
Best when the data comes from somewhere Cowork can already reach, and when you want the failures to land in front of a person rather than in a log file.
Run Claude Code non-interactively from your own scheduler, on a machine where the connector is [already signed in](/mcp/claude-code):
```bash cron (macOS/Linux) theme={null}
0 7 * * * cd /path/to/pipeline && ./sync.sh >> sync.log 2>&1
```
```powershell Task Scheduler (Windows) theme={null}
$action = New-ScheduledTaskAction -Execute 'pwsh.exe' `
-Argument '-NoProfile -File "C:\path\to\sync.ps1"'
$trigger = New-ScheduledTaskTrigger -Daily -At 07:00
Register-ScheduledTask -TaskName 'My data sync' -Action $action -Trigger $trigger
```
Keep the instruction specific enough that there's nothing to decide at 7am — name the collector, name the dataset, and say what to do when it fails:
```
Run collect.js in this folder and have Gaia sync its output to the
Ops Metrics dataset. If collect.js exits non-zero, do not sync.
```
Best when the collector has to run next to something private — a VPN, a local database, a machine with the right credentials.
Whichever you pick, the run needs to be able to use the connector's tools without stopping to ask. Allow them up front, or the job hangs on a permission prompt nobody is there to answer.
**Name Gaia in the instruction.** An unattended run that doesn't is the worst version of this failure: the assistant answers the request itself, reports success, and never touches your dataset — every morning, with nothing in the log to say so. See [Say "Gaia" in your first message](/mcp/overview#say-gaia-in-your-first-message).
### Reading the result
`dataset_sync` reports what happened rather than throwing:
| Result | Meaning |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `ok: true` | Synced. Per-entity inserted / updated / deleted counts come back with it. |
| `ok: false`, `reason: "drift"` | The payload no longer matches the frozen shape. **Nothing was written.** Fix the collector; don't retry unchanged. |
| `ok: false`, `reason: "low_primary_key_overlap"` | The payload barely overlaps what's stored — the signature of a truncated run or a regenerated key. **Nothing was written.** |
| `ok: false`, `reason: "not_found"` | No dataset matched the name. **Nothing was written and nothing was created.** The nearest existing names come back with it. |
All three need a human. Have the job surface them rather than retrying in a loop.
**Never sync a partial payload.** If your collector fails halfway, abort the run — do not sync what it managed to collect, because a partial payload deletes the rest of the dataset.
Make that explicit in the instruction, and have the collector exit non-zero on failure so there's an unambiguous signal to stop on.
Ask your agent for `dataset_schema` once before writing the collector. It gives you the exact sheet name, every required key, and the form each field must take — all of which are matched exactly at sync time.
## Working with spreadsheets instead
A `.csv` or `.xlsx` works anywhere JSON does. Transports are interchangeable after creation — a dataset seeded from a workbook can still be synced from JSON, and vice versa.
For a single-table dataset, prefer JSON. Types survive better through it, and the primary-key guard runs before anything is uploaded rather than after.
## Datasets that re-fetch themselves
Google Sheets, Excel Online, and Airtable datasets pull from upstream instead of being pushed to. For those, a sync with **no payload** tells Gainable to go and re-read the source.
`dataset_list` shows which of your sources are syncable from a payload; `dataset_schema` reports each source's transport.
## Retiring one
`dataset_list` reports `connectedApps` on every row — which apps depend on that dataset. A dataset any app is still using **cannot be deleted**; the refusal names them, and they have to be detached first.
Deleting one that is free drops its configuration and every row it holds, with no undo and no export. Your client has to repeat the dataset's exact name back to go through with it, which is what forces the name into the conversation where you can catch the wrong one.
## Next steps
Every dataset tool and parameter.
Connector-backed datasets and how they attach to apps.
# Overview
Source: https://docs.gainable.dev/mcp/overview
Drive Gainable from Claude Code, Claude, Cowork, or Codex through one MCP connector
Gainable isn't only a web app. The **Gaia harness** is accessible via a remote [MCP](https://modelcontextprotocol.io) server, so an AI client can build, refine, publish, and share your apps — from your terminal, from a Claude chat, or from a Cowork session.
There is one endpoint and nothing to install:
```
https://build.gainable.dev/mcp
```
## What you get
No package to install and nothing to keep on your `PATH`. Add a URL, sign in through your browser, and you're building.
Claude Code, Claude, Cowork, Claude Desktop, and Codex all connect to the same endpoint and get the same tools.
The connector drives the exact same contract agent, planner, Build Agent, and validators as the web app. Nothing is downgraded.
Generated files never enter your context. The harness builds server-side and streams back a summary.
## Pick your client
One `claude mcp add`, then `/mcp` to sign in.
Add it once as a custom connector — it shows up in chat, Cowork, Desktop, and mobile.
`codex mcp add`, then `codex mcp login`.
Any MCP client that speaks streamable HTTP and OAuth 2.1 can connect to the same URL.
## How it fits together
```
You ──▶ Claude Code / Claude / Cowork / Codex ──▶ build.gainable.dev/mcp ──▶ your app
(the MCP client) (the Gaia harness)
```
1. You describe what you want in your client's chat.
2. The client calls a connector tool — `build`, `chat`, `import`, `publish`.
3. The harness does the work **server-side** and streams progress back.
4. Your client relays the harness's questions to you and your answers back to it.
That relay is the whole job. When the harness asks which view should be the home page, or which column identifies a row, those are your calls — a good client forwards them verbatim rather than answering on your behalf.
## Two modes
Most work happens in the first one.
Your request goes to the Gainable harness. The planner and Build Agent do the work server-side in one cheap turn — the same path as typing in the web app. Right for almost everything: "add KPIs", "fix this view", "change the layout", "build me a CRM".
Your client writes the app code itself: it reads the build conventions and the files it needs, edits them, runs the **same validators** the Build Agent uses, and pushes. Only when you explicitly ask — "code it yourself", "without the harness".
Author mode is a separate OAuth scope, not a setting. You grant it with a checkbox when you sign in, so a connection that can build apps can't write code into them unless you said so. See [Author mode](/mcp/tools#author-mode).
## Signing in
The connector uses OAuth 2.1 with dynamic client registration and PKCE, so every client handles sign-in the same way: it opens your browser, you approve, and the token is stored by the client (in your OS keyring for terminal clients).
| | |
| ---------------------- | ----------------------------------------------------------------- |
| Endpoint | `https://build.gainable.dev/mcp` |
| Transport | Streamable HTTP (`POST` only — there is no separate SSE endpoint) |
| Scopes | `mcp` (always) · `datasets` · `users` · `code` |
| Shown in client UIs as | **Gainable (Gaia)** |
### What you're granting
Building, changing, publishing and sharing apps comes with every connection. Three groups of tools sit behind their own checkbox on the consent screen, and a connection that doesn't have one **can't see those tools at all** — they're absent from the list, not refused at call time.
| Checkbox | Scope | What it adds |
| -------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *Also let it work with your datasets* | `datasets` | List datasets and read their rows, create new ones, replace the contents of one, delete one no app is using. Importing a spreadsheet into a new app works without it. |
| *Also let it add and manage people on the account* | `users` | Invite people by email, change whether they're a builder or an app user, remove them. **Inviting a builder uses a paid seat.** |
| *Also let it write code in your apps* | `code` | [Author mode](/mcp/tools#author-mode) — write views, routes and models directly instead of asking Gainable to make the change. |
You can review or revoke any connection at any time from **[Account → Connections](https://build.gainable.dev/account/connections)**, and flip any of the three scopes there without reconnecting — the change takes effect on the connection's next request.
The people checkbox is only **offered** to someone who could manage users themselves. Connecting a client can never hand out more access than you already had.
After you approve, Gainable opens a short **what-now** page with a few first prompts you can copy. Every one of them names the product — see below for why that matters.
No Gainable account yet? You can [create one free](https://build.gainable.dev/auth/signup) during the sign-in step and carry straight on.
## Say "Gaia" in your first message
This is the single thing most worth knowing, and the most common reason a connected client does nothing.
Connecting the server doesn't make your assistant use it. *"Build me an app to track expenses"* is a request it can answer from its own head — and it will, producing something that looks like an answer and never touching Gainable at all. Naming the product is what routes the request.
```text Routes to Gaia theme={null}
Have Gaia build an event planning app from this spreadsheet
```
```text Answered from its own head theme={null}
Build me an app to track expenses
```
**Only the first message needs it.** Once a tool has run, the app's `projectId` is in the conversation and everything after it is ordinary follow-up:
```text theme={null}
Have Gaia build a deals pipeline from this sheet ← names it
Add a probability column to the deals table ← doesn't need to
Make the sponsors view the home page
Publish it
```
Gaia, Gainable, "Gaia Build" and "Gainable Build" all name the same product, so any of them routes correctly. In ChatGPT you can also pick the connector directly with **@ Gaia** instead of naming it in the sentence.
This matters most where nobody is watching. A [scheduled sync](/mcp/datasets#putting-it-on-a-schedule) whose instruction doesn't name Gaia can run every morning, answer itself, and never touch your dataset — with nothing in the log to say so.
Starting a genuinely new app later in the same conversation is also a first message: name Gaia again, and say it's a new app, or you may get a change to the one you already have.
## Not to be confused with your app's MCP server
Gainable involves two different MCP servers, and they do opposite jobs:
| | The Gaia harness MCP | Your app's MCP server |
| ------------- | ----------------------------------------------- | -------------------------------------------------- |
| URL | `build.gainable.dev/mcp` | `.gainable.app/mcp` |
| Purpose | **Build** apps | **Query and write** an app's data |
| Used by | You, from Claude Code / Claude / Cowork / Codex | Your app's Copilots, and any agent you point at it |
| Documented in | This section | [Copilot data access](/copilots/data-access) |
This section is about the first one. The second is what makes an app you build this morning a queryable data source this afternoon.
## What the connector can do
Ten tools by default, and up to eighteen depending on which scopes you granted. You never name them — your client picks from what you ask — but this is the shape of it:
| | Tools | Scope |
| --------------------------- | ----------------------------------------------------------------------------------------- | ---------- |
| Find your way around | `apps_list` · `apps_select` · `project_setup` | `mcp` |
| Build a new app | `import` · `build` | `mcp` |
| Change a built app | `chat` | `mcp` |
| Ship it | `publish` · `share` | `mcp` |
| Decide who can open it | `app_access` · `app_users` | `mcp` |
| Work with your data | `dataset_list` · `dataset_schema` · `dataset_records` · `dataset_sync` · `dataset_delete` | `datasets` |
| Manage the account's people | `account_users` | `users` |
| Author mode | `code_context` · `code_push` | `code` |
See the [tool reference](/mcp/tools) for every parameter.
The connector ships its own operating instructions to every client on connect, so there is no plugin, skill, or rules file to install alongside it. Adding the URL is the whole setup.
## Next steps
Add the connector to your terminal.
Add it to chat, Cowork, and Desktop.
Every tool, action, and parameter.
Create a dataset once, sync it forever.
# Tool reference
Source: https://docs.gainable.dev/mcp/tools
Every tool the Gaia connector exposes, and what each parameter does
You don't call these yourself — your AI client does, based on what you ask it in plain language. This page is here for when you want to know exactly what happened, ask for something specific, or debug a client that picked the wrong tool.
The connector exposes **10 tools** by default, and up to **18** depending on which [scopes](#scopes) you granted when you signed in.
## Conventions
Every tool returns pretty-printed JSON. A few patterns repeat:
* **`ok: false` is a report, not a crash.** A rejected dataset sync or a drifted payload comes back as a normal result saying nothing was written. Your client should read it, not retry it.
* **`outcome: "running"` is not a timeout.** Long operations hand the wait back rather than risk the call being dropped. The answer is a `status` call, never a second start.
* **URLs come back as exact strings.** They're also emitted as resource links. Never construct a Gainable URL by hand — an app's own hostname isn't reachable without a key the launcher injects.
### Scopes
Three groups of tools are **absent from the connection entirely** unless you ticked their box at sign-in. Not hidden, not refused — not in the list your client can see at all, which is a harder guarantee than a description asking a model not to reach for something.
| Scope | Checkbox at sign-in | Tools it adds |
| ---------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `mcp` | Always on | The ten below: lifecycle, build, chat, ship, app access |
| `datasets` | *"Also let it work with your datasets"* | `dataset_list` · `dataset_schema` · `dataset_records` · `dataset_sync` · `dataset_delete` |
| `users` | *"Also let it add and manage people on the account"* | `account_users` |
| `code` | *"Also let it write code in your apps"* | `code_context` · `code_push` |
You can turn any of them on or off later from **[Account → Connections](https://build.gainable.dev/account/connections)** without reconnecting; the change takes effect on the connection's next request.
The `users` box is only **offered** to someone who could manage users themselves — the account owner, or a member holding the `manage_users` permission. Connecting a client can never hand out more than the human behind it already had.
If your client can't find a `dataset_*` tool, that's the scope, not a bug. `import` deliberately stays on the default scope, so building an app from a spreadsheet works without the datasets box.
### Which app a tool acts on
Most tools take an optional `projectId`. Where it comes from, in order of authority:
1. **`.gaia/project.json` in the working folder** — written when a tool returns a project anchor, read on the next session. This is what makes a folder remember its app.
2. **The tool that created or selected the app**, earlier in the same conversation.
3. **`apps_list`**, when you have neither.
The "currently active" app is remembered **per account, not per conversation**. On a client the connector can't isolate — one that reconnects before every call, like Cowork — it refuses to guess and asks you to name the app instead. An active app also goes stale after 30 minutes of no use.
***
## Lifecycle
### `project_setup`
Returns a starter for a new Gainable project: a `README.md`, a `CLAUDE.md` for your domain context, `data/` and `apps/` folders, and the same context condensed into a block you can paste into a project's Instructions box when there's no folder to write to.
| Parameter | Type | Description |
| ----------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `overwrite` | boolean | Only when you explicitly asked to reset the files. A hand-written `CLAUDE.md` is your work, not a template. |
Your client should offer this once, ask before writing anything, and read your existing context instead if you already have some.
The starter teaches one habit worth knowing yourself: **name Gaia in the request**. An assistant with several tools connected has nothing else to go on — *"build me an app to track expenses"* is just as likely to be answered out of its own head as routed to the connector. *"Using Gaia, build me…"* is what makes it land.
### `apps_list`
Lists the apps in the connected account, most recently used first.
| Parameter | Type | Description |
| --------- | ------ | --------------------------------------------------- |
| `query` | string | Case-insensitive filter on the app or project name. |
### `apps_select`
Sets which app the following tools act on.
| Parameter | Type | Description |
| --------- | --------------------- | ----------------------------------------------- |
| `app` | string · **required** | A `projectId` (`project-1784…`) or an app name. |
An ambiguous name comes back as a list of matches rather than a guess.
***
## Building a new app
### `import`
Turns an Excel or CSV file into a dataset attached to a project, ready to build from.
| Parameter | Type | Description |
| ----------------- | ------------------- | ------------------------------------------------------------------------------------------------ |
| `action` | enum · **required** | `upload_url` · `upload_chunk` · `upload` · `answer` · `state` · `finalize` · `attach` · `cancel` |
| `fileName` | string | The original filename, with its extension — the analyzer picks its parser from it. |
| `fileBase64` | string | The file contents, for `upload`. Small files only (\~40 KB). |
| `uploadToken` | string | The token from `upload_url` or `upload_chunk`. |
| `chunkBase64` | string | One slice of the base64 file, for `upload_chunk`. |
| `isLastChunk` | boolean | True on the final slice — the import starts automatically. |
| `answers` | object | Your reply to the pending question, e.g. `{"choice":"keep"}`. |
| `importSessionId` | string | Thread this through every follow-up call. |
| `datasetName` | string | For `attach` — defaults to the file name. |
| `projectId` | string | For `attach` — add the data to this existing app instead of creating a new one. |
| `projectName` | string | For `attach` — name the project this creates. |
**Three ways to send the file, tried in this order:**
The connector returns a URL; your client POSTs the file straight to it. No size limit, and the bytes never enter its context.
Some sandboxes block network egress. The base64 goes up in slices instead: no egress needed, no size limit, but it costs context.
Simplest, but the whole string passes through your client's context, so it's capped around 40 KB.
A file that won't fit one road means take the next road. It never means shrink, split, or convert the file. Sending a "cleaned up" workbook doesn't import a simpler app — it imports a different and wrong one.
After `attach`, the build conversation starts with `build`.
### `build`
Drives the whole new-app journey: a contract conversation through five phases — `data → derives → seed → ui → autonomy` — and then the deterministic build pipeline.
| Parameter | Type | Description |
| ------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `action` | enum · **required** | `turn` · `reply` · `run` · `status` |
| `message` | string | For `turn` — your idea, or the **full text** of a spec document. |
| `replies` | string\[] | For `reply` — the option **labels** you picked, in the order they were asked. A multi-select is one comma-separated string. |
| `newApp` | boolean | For `turn` — start a fresh project instead of continuing the active one. |
| `projectId` | string | For `turn` — continue this project's contract conversation. |
| `projectName` | string | Name the project when this call creates it. |
| `silent` | boolean | Don't surface this message as a chat bubble. Used for the post-import kickoff. |
**The harness can't read files.** If you point at a spec document, your client must paste its complete contents into `message`. A path or a one-line summary makes the server design from generic domain knowledge instead of your spec.
Spreadsheets are the exception — they go through `import`, never into `build` as a spec.
`action:"run"` takes 90–180 seconds. Only `outcome:"built"` means done; anything else means keep watching with `status`.
**"Build an app from this" always means a new app** — even from the same spreadsheet you used an hour ago. Same data is not the same app, and silently attaching new data to an existing one is rarely what anyone wants. Only target an existing app when you name it: *"add this to the Summit tracker"*.
***
## Changing a built app
### `chat`
One turn: a server-side planner decides the change and the Build Agent applies it. This is the right tool for almost every edit — adding a field, fixing a view, changing a layout, adjusting behaviour. Asking for a page the app doesn't have creates it; renaming a page is a **display** change, so the slug, the URL and the filenames stay put.
| Parameter | Type | Description |
| ----------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `message` | string | What you want changed, in your own words. Required unless `action` is `status`. |
| `pageSlug` | string | The page you're talking about. Context for the turn, not a restriction — the change lands wherever it belongs. |
| `projectId` | string | Which app to act on. |
| `chatId` | string | Continue a specific conversation, using a `chatId` from an earlier result. |
| `newChat` | boolean | Start a separate conversation instead of continuing the current one. |
| `action` | enum | `send` (default) · `status` |
If the planner needs a decision it can't make, the result is `outcome:"needs_clarification"` with a question. Answer it as a **new** `chat` call — the server recognises the pending clarification and merges it in.
**The plan auto-accepts on this path.** In the web builder the planner's plan card waits for you to click Accept; through `chat` it applies as soon as it's written. There is no approval step to wait for and no button to look for.
#### Every turn belongs to a chat
Work done through the connector lands in the same conversation unit the builder screen shows, so you can open the app in Gainable and see it. Calls continue the current chat; `newChat:true` starts a separate one when you move to an unrelated topic.
The `chatId` comes back in **every** result. A client that reconnects between calls — Cowork does — loses its in-memory sense of which conversation it was in, so passing the `chatId` back is how a turn rejoins the right thread rather than starting a new one each time.
**Never re-send the same `chat` message.** The turn keeps running server-side whatever happens to the connection, so a second call isn't a retry: it runs the planner again and stacks a duplicate plan card someone has to clear by hand.
***
## Shipping
### `publish`
Deploys the app to its public `https://.gainable.app` URL — the same as the **Publish** button in the web app. Idempotent.
| Parameter | Type | Description |
| ----------- | ------ | ------------------------------ |
| `action` | enum | `publish` (default) · `status` |
| `projectId` | string | Which app to act on. |
### `share`
Reports the app's links **and who can actually open each one**: the public URL when it's published, and the in-Gainable launcher link for teammates. It mints nothing — it only tells you what exists.
| Parameter | Type | Description |
| ----------- | ------ | -------------------- |
| `projectId` | string | Which app to act on. |
Reach for this whenever you're about to send someone a link. The failure worth avoiding is mailing a teammate a URL that 404s for them.
***
## Who can use an app
`share` reports the links. These two decide who those links work for — the **Users** tab of an app in Gainable, reachable from your client.
### `app_access`
Reads or changes the app's audience. Two independent questions, and the tool answers both in words as well as values.
| Parameter | Type | Description |
| -------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `action` | enum | `get` (default) · `set` |
| `accessMode` | enum | Which members of the **owning account** get in. `account` = every active member. `invited` = only members added to this app. |
| `externalAccess` | enum | Whether people **outside** the account exist at all. `none` = no login page. `invited` = you add them by hand. `signup` = anyone can create an account on the app. |
| `requireEmailVerification` | boolean | Signup only — make new signups verify their email first. |
| `domainWhitelist` | string\[] | Signup only — restrict signup to these email domains. `[]` clears it. |
| `projectId` | string | Which app to act on. |
**The two axes land at different times.** `accessMode` is enforced on every launch, so it takes effect the moment it's saved. `externalAccess`, `requireEmailVerification` and `domainWhitelist` become part of the app when it's **published** — a published app keeps its old login and signup pages until you republish it.
The result says which: `requiresRepublish: true` means the live app still behaves the old way.
Narrowing `accessMode` to `invited` revokes access for every account member who isn't on the app's list, immediately. The tool says so in its `next`, but it's your call to make before asking for it.
### `app_users`
The people list. Two kinds of member, and the difference isn't cosmetic:
* **Internal** (`external:false`, the default) — someone already on this Gainable account, added to this app. They sign in with their Gainable login and arrive over SSO.
* **External** (`external:true`) — a user who exists only inside this app, with their own password and no Gainable account.
| Parameter | Type | Description |
| ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------ |
| `action` | enum | `list` (default) · `add` · `remove` · `update` |
| `users` | object\[] | For `add` — `{ email, name?, isAdmin? }`. `name` is required when `external:true`. |
| `emails` | string\[] | For `remove` and `update`. Also a shorthand for `add` when adding account members. |
| `external` | boolean | `add` only — which kind of user to create. |
| `isAdmin` | boolean | `update` only — the admin flag to set on everyone in `emails`. This is the **app's** admin, not a Gainable account role. |
| `query` | string | `list` only — case-insensitive filter on name or email. |
| `projectId` | string | Which app to act on. |
Both kinds of `add` are gated on the access settings, and the tool enforces the gates rather than describing them:
| You asked for | It refuses unless |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| An internal user | `accessMode` is `invited` — while it's `account` everyone can already open the app, so adding one person changes nothing |
| An external user | `externalAccess` is on — with no login page there's no way for them to sign in |
**No invitation email is sent, either way.** External users are created without a password and set their first one through *Forgot password* on the app's own login page. Internal users simply find the app in their launcher. Tell them yourself.
A `list` in `account` mode is **not** authoritative — every active member can open the app whether or not they appear, and rows appear as people first use it. It only becomes the gate once `accessMode` is `invited`.
Removing an external user **deletes them** — that app login was the only one they had. Removing an internal user only revokes their access to that app; their Gainable account is untouched.
***
## People on the account
### `account_users`
Needs the `users` scope, and the connected person must be the account owner.
Everyone on the Gainable **account**, as opposed to on one app — the Users page in settings. This is where somebody has to exist before `app_users` can add them to an app, and it's the refusal `app_users` gives when they don't.
| Parameter | Type | Description |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
| `action` | enum | `list` (default) · `invite` · `resend` · `remove` · `set_type` · `set_permissions` |
| `users` | object\[] | For `invite` — `{ email, type?, permissions? }`. |
| `emails` | string\[] | For `resend`, `remove` and `set_type`. |
| `type` | enum | `builder` or `app-user`. |
| `permissions` | enum\[] | The **complete** set of account capabilities, applied to everyone in the call. Anything left out is revoked. |
| `query` | string | `list` only — case-insensitive filter on name or email. |
Two types of person, and the difference is money and reach:
| Type | What they get | Cost |
| ---------- | -------------------------------------------- | ---------------------------------- |
| `builder` | Full platform access — builds and edits apps | **Uses a paid seat** from the plan |
| `app-user` | Only the launcher and the apps they're given | Unlimited |
Separately from the type, a person can hold account **capabilities**: `manage_users` (invite and manage people), `api_keys` (mint account API keys), `connections` (manage connected apps), `account_views` (create shared views in the apps grid). These are orthogonal — either type may hold any of them — and `[]` is a normal answer, but it has to be an answer rather than an omission. You can't pass on a capability you don't hold yourself.
**Inviting sends email to a third party and can spend money.** `action:"invite"` mails an invitation link that expires in 14 days; they are not on the account until they accept it. The right word in a report is *invited*, not *added*.
`list` comes back with `builderSeatsUsed`, `builderSeatLimit` and `builderSeatsFree`, so a client can tell you a promotion will fail before it tries.
***
## Datasets
All five need the `datasets` scope. `import` does not — that's the spreadsheet-to-app path, and scoping it would mean a connection without the box ticked couldn't build an app from a file at all.
`import` bootstraps an app from a spreadsheet. These five work with **standalone** datasets that a script keeps fresh — create once, sync forever. See [Recurring data pipelines](/mcp/datasets) for the full workflow.
### `dataset_list`
Find a dataset before syncing, reading or deleting it.
| Parameter | Type | Description |
| --------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `query` | string | Case-insensitive filter on the dataset name, applied across **every** dataset rather than the current page. |
| `limit` | integer | How many to return. Default `25`, max `100`. |
| `skip` | integer | How many to skip, for paging. Newest first. |
Each row carries the provider, row count, last sync, whether the source is syncable from a payload or only re-fetchable from upstream, and **`connectedApps`** — which apps depend on it. That last one is what you need before proposing to replace or delete anything, so it's always there rather than behind a flag.
### `dataset_schema`
Returns the **write contract**: the required keys per sheet, the primary key, and the expected form of every field. Read this before writing any collector.
| Parameter | Type | Description |
| --------- | --------------------- | ------------------------------------ |
| `dataset` | string · **required** | The `col_…` id, or the dataset name. |
Each field carries a `writeAs` describing exactly what to emit:
| Type | Write as |
| --------------- | --------------------------------------------------------------------- |
| `number` | JSON number, not a formatted string — `1234.5`, not `"1234.5"` |
| `boolean` | JSON `true` / `false` |
| `date` | ISO 8601 date string, e.g. `"2026-07-28"` |
| `stringArray` | Array of strings |
| `objectIdArray` | The referenced row's primary value — the link is resolved server-side |
| `string` | String |
### `dataset_records`
Reads the **rows** — the actual values, not the shape. Before this existed, the only way to see whether a sync landed was to build an app over the dataset.
| Parameter | Type | Description |
| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `dataset` | string · **required** | The `col_…` id, or the dataset name. |
| `sourceKey` | string | Which entity to read, as `s_e` — e.g. `s0_e1`. Defaults to the first; the response always says which it read. |
| `limit` | integer | Rows to return. Default `25`, max `200`. |
| `skip` | integer | Rows to skip, for paging. |
| `include` | enum\[] | `relations` and/or `attachments`. Both are large per-row blobs, omitted by default. |
`availableEntities` is on every response even when there's only one, so a multi-entity dataset never gets reported as if its first entity were the whole thing.
Only adapter-backed sources store rows in Gainable. A source whose data stays at the provider comes back as an explicit refusal naming the entity, rather than as an empty page you'd have no way to see through.
### `dataset_sync`
Gets data **into** a dataset — creating one when there isn't one yet. This was two tools; which applied depended on whether the dataset already existed, which is a fact about the account rather than about what you meant.
| Parameter | Type | Description |
| ----------------- | --------- | ----------------------------------------------------------------------------------------------------- |
| `action` | enum | `sync` (default) · `create` · `answer` · `finish` · `upload_url` |
| `dataset` | string | For `sync` — the `col_…` id or dataset name to replace. |
| `name` | string | For `create` — name for the new dataset. |
| `createIfMissing` | boolean | For `sync` — create it instead of failing when nothing matches `dataset`. |
| `rows` | object\[] | The complete snapshot for a single-sheet dataset. On `create`, 5–20 representative real rows instead. |
| `sheets` | object | The complete snapshot for a multi-sheet dataset: `{ "": [ …rows ] }`. |
| `fileBase64` | string | A spreadsheet instead of JSON rows. Works for both creating and replacing; keep it small (\~100 KB). |
| `uploadToken` | string | The token from `action:"upload_url"`, once the file has been POSTed. Preferred over `fileBase64`. |
| `fileName` | string | The filename, with extension, when sending a file. |
| `sourceIndex` | integer | Which source to write to, when the dataset has several. |
| `minOverlap` | number | Minimum share of existing primary keys the payload must still contain. Default `0.5`. JSON rows only. |
| `force` | boolean | Proceed despite low overlap. **This is the flag that destroys comment threads.** |
| `sessionId` | string | Thread this through every follow-up call during a `create`. |
| `answers` | object | For `answer` — your reply to the analyzer's pending question. |
**Three transports, picked by what you send:**
| You send | What happens |
| ------------------ | ------------------------------------------------------------------------------------ |
| `rows` or `sheets` | The snapshot is pushed in |
| A file | Same, but the server parses it |
| Nothing | Gainable re-fetches from upstream — the Google Sheets / Excel Online / Airtable path |
**Every sync replaces everything.** Rows absent from the payload are deleted. Send the complete set every time — if a collector failed halfway, abort rather than syncing what it managed to collect.
**Syncing never creates.** An unmatched name is an error, because the server can't tell a typo from a new dataset and would silently make a duplicate — `"Deals Pipeline (2)"` — while the real one quietly goes stale.
Use `action:"create"` when you want a new dataset every time, or `createIfMissing:true` for an unattended collector that should seed on its first run and replace on every run after. Not for a one-off sync you're driving by hand, where a caught typo is the point.
Seed a `create` with **5–20 real rows**. The analyzer infers column types and picks the primary key from actual values, and that choice is frozen for the dataset's life — a one-row seed produces a schema you cannot fix later.
### `dataset_delete`
Permanently deletes the dataset, its configuration and every row in it. No undo, no export first.
| Parameter | Type | Description |
| --------- | --------------------- | --------------------------------------------------------------------------- |
| `dataset` | string · **required** | The `col_…` id, or the dataset name. |
| `confirm` | string · **required** | The dataset's **exact** name, repeated back. A mismatch refuses the delete. |
Two guards, against two different mistakes. `confirm` is against deleting the wrong thing on a vague instruction — *"get rid of the old pipeline one"* resolves to exactly one dataset without anybody having seen which, so the name has to travel through the conversation where you can catch it. And a dataset any app is still using can't be deleted at all: the refusal names the apps, and they have to be detached first.
***
## Author mode
Two extra tools appear **only** when you granted the `code` [scope](#scopes) — the *"Also let it write code in your apps"* checkbox at sign-in.
This is a scope, not a setting, for two reasons. A token that can build apps shouldn't automatically be able to author code into them. And a model can't over-reach for a tool that isn't in its list, which is a harder guarantee than a description asking it not to.
**Only ask for author mode when you actually want it.** Ordinary requests — "add KPIs to the sponsors view", "redesign the deals page", "fix the kanban bug" — belong to `chat`, which is one cheap turn and does them well. Author mode reads conventions, reads files, and runs validators. It's the exception, not the upgrade.
### `code_context`
Step one: read before you write.
| Parameter | Type | Description |
| ----------- | ------------------- | ------------------------------------------------------------------------- |
| `action` | enum · **required** | `manifest` · `conventions_file` · `app_file` |
| `id` | string | For `conventions_file` — a guide id from the manifest. |
| `path` | string | For `app_file` — a path relative to the app root, e.g. `views/deals.ejs`. |
| `projectId` | string | Which app to act on. |
`manifest` returns the app index — every file with its path, mode, and hash — plus the list of convention guides, with no file contents. Your client then fetches the two or three guides for the area it's touching and the files it will actually change, rather than everything.
`app_file` returns the content **and a hash**. That hash goes back as `baseHash` when you push.
### `code_push`
Step two: check your work, then commit it.
| Parameter | Type | Description |
| ----------- | ------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `action` | enum · **required** | `validate` · `push` |
| `files` | object\[] · **required** | `{ path, content, baseHash }`. `baseHash` is required when editing an existing file, omitted when creating one. |
| `summary` | string | Required for `push`. One to three sentences on what changed and why. |
| `projectId` | string | Which app to act on. |
`push` validates the whole batch, writes it atomically, registers new view routes, commits to the app's git history, and records the session in the project's chat history — which is why `summary` is mandatory: it's what the human sees alongside their own refinements.
**The rules that make this work:**
1. **Only `rw` files are writable** — `views/`, `routes/`, `db/models/`, `public/css/`, `public/js/`. Everything else is framework-owned and push rejects it.
2. **`server.js` belongs to the registrar.** Write the view and the route; push wires them up.
3. **Push the whole stack of a feature in one call** — view, route, and model together. The cross-file validators judge the batch as a whole, so a view whose route is "coming next" is correctly rejected.
4. **Treat validator output as binding.** Those \~100 rules each encode a production incident someone already had. A rejection is the rule being right.
5. **Pass `baseHash` when editing.** A `stale` rejection means the file changed server-side since you read it: re-read, re-apply, re-push. Don't drop the hash to force it through.
***
## When something goes wrong
| What you see | What it means |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outcome: "running"` | Still working. Call `status` — don't start it again. |
| `outcome: "needs_clarification"` | The planner needs a decision. Answer as a new `chat` call. |
| `ok: false, reason: "drift"` | The payload no longer matches the dataset's frozen shape. Nothing was written. Fix the collector. |
| `ok: false, reason: "low_primary_key_overlap"` | The payload barely matches what's stored — the signature of a truncated run or a regenerated key. Nothing was written. |
| `ok: false, reason: "not_found"` (dataset) | Nothing matched the name. **Nothing was created either** — the nearest existing datasets come back with it. Fix the typo, or ask for `action:"create"`. |
| `reason: "stale"` (author mode) | The file changed server-side since you read it. Re-read and re-apply. |
| A tool your client can't find | Its [scope](#scopes) wasn't granted. Tick the box at [Account → Connections](https://build.gainable.dev/account/connections). |
| "A turn is already running for this project" | Two calls hit the same app at once. Wait for the first, or call `status`. |
| "This app belongs to a different account" | You're connected to the wrong Gainable account for this app. |
| "confirm does not match" | `dataset_delete` guard. The exact name has to be repeated back — don't just copy the expected value across, show it to a human. |
| "Every member of this account can already open this app" | `app_users` on an app whose `accessMode` is `account`. Adding one person there changes nothing; narrow it with `app_access` first. |
| "This app has no login page" | Adding an external user while `externalAccess` is `none`. Turn it on with `app_access` — and republish if the app is already live. |
| "Only the account owner can manage who is on the account" | `account_users` needs the owner. The scope says what the connection may attempt; the permission says what the person may do, and both have to pass. |
| "No active subscription or its trial has expired" | Check [billing](https://build.gainable.dev). |
## Next steps
The full dataset workflow, end to end.
How the connector fits together.
# Best practices
Source: https://docs.gainable.dev/prompting/best-practices
Dos and don'ts for writing effective prompts
## Do this
### Be specific about data fields
```text Do this theme={null}
Track contacts with:
- Full name
- Email address
- Phone number
- Company name
- Job title
- LinkedIn profile URL
```
```text Don't do this theme={null}
Track contact information
```
### Specify field types when it matters
```text Do this theme={null}
Track deals with:
- Deal name (text)
- Amount (currency)
- Close date (date)
- Probability (percentage)
- Status (new, negotiating, won, lost)
```
```text Don't do this theme={null}
Track deals with name, amount, date, probability, status
```
Common field types to specify:
* **Currency**: "amount (currency)" or "price in dollars"
* **Date**: "due date" or "close date"
* **Percentage**: "probability (percentage)"
* **Options**: "status (option A, option B, option C)"
* **Yes/No**: "is active (yes/no)" or "completed (checkbox)"
### Describe relationships clearly
```text Do this theme={null}
Build a project system where:
- Projects have a name and description
- Each project has multiple tasks
- Tasks have a title, due date, and status
- Each task is assigned to one user
```
```text Don't do this theme={null}
Track projects, tasks, and users
```
### Request specific visualizations
```text Do this theme={null}
Add a dashboard with:
- Total revenue card
- Number of deals card
- Pie chart showing deals by status
- Line chart showing monthly revenue trend
```
```text Don't do this theme={null}
Add a dashboard with some charts
```
### Define options explicitly
```text Do this theme={null}
Status options: draft, pending review, approved, rejected
Priority levels: low, medium, high, critical
```
```text Don't do this theme={null}
Add status and priority fields
```
***
## Don't do this
### Don't reference other products
```text Don't do this theme={null}
Build something like Asana
Make it work like Notion
Copy the Salesforce pipeline
```
```text Do this instead theme={null}
Build a task manager with:
- Projects containing tasks
- Tasks with title, assignee, due date, status
- Kanban board view
- List view with filters
```
Why: Gainable doesn't know what features you want from those products. Describe the specific features you need.
### Don't use vague design terms
```text Don't do this theme={null}
Make it modern
Keep it clean
Professional looking
```
```text Do this instead theme={null}
Use the corporate theme
Use blue and gray colors
Use a sidebar navigation layout
```
### Don't request everything at once
```text Don't do this theme={null}
Build a complete CRM with leads, contacts, companies,
deals, tasks, emails, calendar, reports, dashboards,
team management, permissions, notifications, and
mobile app with offline support.
```
```text Do this instead theme={null}
Build a deal tracker with:
- Deals (name, amount, status, close date)
- Contacts (name, email, linked to deal)
- Dashboard with deal totals
(Then add more features in subsequent prompts)
```
### Don't assume Gainable knows your domain
```text Don't do this theme={null}
Build a standard e-commerce checkout flow
Add the usual project management features
```
```text Do this instead theme={null}
Build checkout with:
- Cart review step
- Shipping address form
- Payment method selection
- Order confirmation page
```
***
## Changing an app you have already built
Everything above is about the prompt that creates an app. Once it exists, the rules shift: you are naming things that are already there, and a plan card appears before anything changes.
Naming pages and components, bug versus preference, screenshots, and the plan card.
***
## Quick reference
| Situation | Best Practice |
| --------------- | ------------------------------------------ |
| Defining data | List all fields with types |
| Connecting data | Explicitly state relationships |
| Adding charts | Name the chart type and what data it shows |
| Adding features | Use feature names (kanban, chat, filter) |
| Styling | Reference theme names or specific colors |
## Learn more
Prompting once it's up and running
See real prompts in action
Templates for common app types
# Common patterns
Source: https://docs.gainable.dev/prompting/common-patterns
Templates for building common types of applications
## Pattern templates
These are reusable templates for common app types. Fill in the blanks to create your own version.
***
## CRUD Application
The most basic pattern: Create, Read, Update, Delete.
```text theme={null}
Build a [thing] tracker with:
- [field 1] (text)
- [field 2] (text/number/date)
- [field 3] (options: option1, option2, option3)
- [field 4] (yes/no)
Features:
- List all [things]
- Add new [thing]
- Edit existing [thing]
- Delete [thing]
```
```text theme={null}
Build a bug tracker with:
- Title (text)
- Description (text)
- Severity (options: low, medium, high, critical)
- Resolved (yes/no)
Features:
- List all bugs
- Add new bug
- Edit existing bug
- Delete bug
```
***
## Dashboard Application
Data overview with KPIs and charts.
```text theme={null}
Build a [domain] dashboard showing:
KPI Cards:
- Total [things] count
- [Things] with [status] count
- Total [numeric field] sum
- Average [numeric field]
Charts:
- [Things] by [category field] (pie chart)
- [Things] over time (line chart)
- [Numeric field] by [category] (bar chart)
Recent activity:
- Last 10 [things] added
```
```text theme={null}
Build a sales dashboard showing:
KPI Cards:
- Total deals count
- Deals won count
- Total pipeline value
- Average deal size
Charts:
- Deals by status (pie chart)
- Revenue over time (line chart)
- Revenue by region (bar chart)
Recent activity:
- Last 10 deals added
```
***
## Kanban / Pipeline
Workflow management with drag-and-drop.
```text theme={null}
Build a [thing] board with columns:
- [Status 1]
- [Status 2]
- [Status 3]
- [Status 4]
Each [thing] card shows:
- [Primary field]
- [Secondary field]
- [Badge/tag field]
Features:
- Drag [things] between columns to update status
- Click card to edit details
- Add new [thing] to any column
- Real-time sync
```
```text theme={null}
Build a hiring pipeline with columns:
- Applied
- Phone Screen
- Interview
- Offer
- Hired
Each candidate card shows:
- Name
- Position applying for
- Source (referral, LinkedIn, etc)
Features:
- Drag candidates between columns to update status
- Click card to edit details
- Add new candidate to any column
- Real-time sync
```
***
## Master-Detail
List of items with detailed view.
```text theme={null}
Build a [thing] manager where:
[Things] have:
- [field 1], [field 2], [field 3]
- Status: [status options]
Each [thing] has many [sub-things]:
- [sub-field 1], [sub-field 2]
- Linked to parent [thing]
Views:
- [Things] list page (shows count of [sub-things])
- [Thing] detail page showing:
- All [thing] info
- List of [sub-things]
- Add/edit/delete [sub-things]
```
```text theme={null}
Build a project manager where:
Projects have:
- Name, description, status
- Status: active, on hold, complete
Each project has many tasks:
- Title, due date, completed
- Linked to parent project
Views:
- Projects list page (shows count of tasks)
- Project detail page showing:
- All project info
- List of tasks
- Add/edit/delete tasks
```
***
## Multi-Entity CRM
Multiple related data types.
```text theme={null}
Build a [domain] system where:
[Entity A] has:
- [fields...]
- Status: [options]
[Entity B] has:
- [fields...]
- Belongs to one [Entity A]
[Entity C] has:
- [fields...]
- Linked to [Entity A] and [Entity B]
Views:
- [Entity A] list and detail pages
- [Entity B] list with [Entity A] filter
- [Entity C] kanban board
- Dashboard with totals and charts
```
```text theme={null}
Build a real estate CRM where:
Properties have:
- Address, price, bedrooms, bathrooms
- Status: available, pending, sold
Clients have:
- Name, email, phone, budget range
- Looking for: buy, rent
Showings have:
- Date, time, notes
- Linked to a property and a client
Views:
- Properties list and detail pages
- Clients list with budget filter
- Showings calendar view
- Dashboard with totals and charts
```
***
## Form + Workflow
Data collection with status progression.
```text theme={null}
Build a [thing] submission system:
[Things] have:
- [Form fields...]
- Status: draft, submitted, under review, approved, rejected
- Submitted by (user)
- Reviewed by (user)
- Submission date
Workflow:
1. User creates [thing] in draft
2. User submits for review
3. Reviewer approves or rejects
4. User can see all their [things] and status
Admin dashboard:
- Pending reviews count
- [Things] by status
- Recent submissions
```
```text theme={null}
Build an expense report system:
Expenses have:
- Description, amount, category, receipt image
- Status: draft, submitted, under review, approved, rejected
- Submitted by (user)
- Reviewed by (manager)
- Submission date
Workflow:
1. User creates expense in draft
2. User submits for review
3. Manager approves or rejects
4. User can see all their expenses and status
Admin dashboard:
- Pending reviews count
- Expenses by status
- Recent submissions
```
***
## Booking / Reservation
Time-based scheduling.
```text theme={null}
Build a [thing] booking system:
[Resources] have:
- Name, description
- Availability hours
- [Other attributes]
[Bookings] have:
- [Resource] selected
- Date and time
- Duration
- [Booker info]
- Status: confirmed, cancelled
Features:
- Calendar view of bookings
- Check availability before booking
- Confirmation notifications
- Manage my bookings
```
```text theme={null}
Build a meeting room booking system:
Rooms have:
- Name, capacity, amenities
- Building/floor
- Availability hours
Bookings have:
- Room selected
- Date and time
- Duration (30min, 1hr, 2hr)
- Booked by, attendees count
- Status: confirmed, cancelled
Features:
- Calendar view of room bookings
- Check availability before booking
- Confirmation notifications
- Manage my bookings
```
***
## Using these patterns
Pick the template closest to what you want to build
Replace bracketed text with your specific details
Customize fields, features, and views to match your needs
Build the basic version first, then add features
## Combining patterns
You can combine multiple patterns:
```text theme={null}
Build a customer success platform with:
[Master-Detail Pattern]
Accounts with contacts and activities
[Kanban Pattern]
Support tickets on a status board
[Dashboard Pattern]
KPIs and charts for health metrics
```
## Learn more
See complete prompt examples
Write better prompts
# Examples
Source: https://docs.gainable.dev/prompting/examples
Real prompts you can copy and adapt for your projects
## Copy-and-adapt prompts
These are real prompts that produce great results. Copy them and modify the specifics for your use case.
***
## CRM / Sales
### Basic deal tracker
```text theme={null}
Build a deal tracker with:
- Deal name
- Company name
- Amount (currency)
- Status: new, proposal, negotiation, won, lost
- Expected close date
- Contact name and email
Show a dashboard with:
- Total pipeline value
- Deals won this month
- Pie chart of deals by status
```
### Full CRM with contacts
```text theme={null}
Build a CRM where:
Companies have:
- Name, industry, website
- Size (small, medium, large, enterprise)
- Status (prospect, customer, churned)
Contacts have:
- Name, email, phone, job title
- Each contact belongs to one company
Deals have:
- Name, amount, status, close date
- Linked to a company and a primary contact
I need:
- Company list page
- Contact list page
- Deal pipeline as a kanban board
- Dashboard with total revenue and deals by status
```
***
## Project Management
### Task tracker
```text theme={null}
Build a task tracker with:
- Task title and description
- Status: to do, in progress, done
- Priority: low, medium, high
- Due date
- Assigned to (user selection)
Features:
- Kanban board view by status
- Filter by priority and assignee
- Real-time updates
```
### Project with phases
```text theme={null}
Build a project tracker where:
Projects have:
- Name, description, status
- Start date and target end date
- Project manager (user)
Each project has multiple milestones:
- Milestone name
- Target date
- Status: pending, complete
Each milestone has multiple tasks:
- Task name
- Status: not started, in progress, complete
- Assigned to
Show:
- Project list with progress percentage
- Project detail page with milestones
- Gantt-style timeline would be nice
```
***
## Inventory / Products
### Product catalog
```text theme={null}
Build a product catalog with:
- Product name and SKU
- Category (electronics, clothing, home, other)
- Price (currency)
- Quantity in stock
- Reorder point
- Active (yes/no)
Dashboard showing:
- Total products count
- Low stock alerts (below reorder point)
- Products by category (pie chart)
- Inventory value total
```
### Order tracking
```text theme={null}
Build an order tracking system:
Products have:
- Name, SKU, price
Orders have:
- Order number (auto-generated)
- Customer name and email
- Status: pending, processing, shipped, delivered
- Order date
- Total amount
Order items:
- Linked to an order
- Product selected from products
- Quantity
- Line total
Features:
- Order list with status filter
- Order detail page showing items
- Dashboard with order totals
```
***
## Events / Bookings
### Event management
```text theme={null}
Build an event manager with:
Events have:
- Name, description
- Date and time
- Location
- Capacity (number)
- Status: draft, published, cancelled
Registrations have:
- Linked to an event
- Attendee name and email
- Registration date
- Status: confirmed, waitlist, cancelled
Show:
- Event list page
- Event detail with registration count
- Add registration form
- Export attendee list option
```
### Appointment scheduler
```text theme={null}
Build an appointment scheduler:
Services have:
- Name, duration (minutes), price
Appointments have:
- Client name, email, phone
- Service (selected from services)
- Date and time
- Status: scheduled, completed, cancelled, no-show
- Notes
Dashboard:
- Today's appointments
- This week's revenue
- Appointments by status (chart)
```
***
## HR / Team
### Employee directory
```text theme={null}
Build an employee directory with:
- Name, email, phone
- Department: engineering, sales, marketing, operations, HR
- Job title
- Start date
- Manager (another employee)
- Status: active, on leave, departed
Features:
- Search by name
- Filter by department
- Org chart view would be nice
- Employee detail page
```
### Time off tracker
```text theme={null}
Build a time off tracker:
Time off requests have:
- Employee name
- Type: vacation, sick, personal, other
- Start date and end date
- Status: pending, approved, rejected
- Notes
- Reviewed by (manager)
Dashboard:
- Pending requests count
- Approved days this month
- Requests by type (chart)
Features:
- Filter by status
- Calendar view of approved time off
```
***
## Adding to an app that already exists
Asking for a feature on a built app is its own skill — name the page, name the component, and read the plan card before accepting it. See [Changing a built app](/prompting/refining).
Each feature has a page of its own, with the prompts and the options that go with it:
| Want to add | See |
| ---------------------------- | -------------------------------- |
| Charts and KPI cards | [Charts](/skills/chartjs) |
| A kanban board | [Kanban](/skills/kanban) |
| Chat, comments, presence | [Collaboration](/skills/weavy) |
| Filters, search, view layout | [Views](/building/views) |
| Live updates | [Real-time](/building/real-time) |
| Themes, colours, layout | [Design](/skills/design) |
***
## Gaia Copilot
### Create a data-aware Copilot
```text theme={null}
Build a CRM with companies, contacts, and deals.
Create a Sales Coach Copilot that:
- Helps reps find and analyze deals
- Can query deals, contacts, and companies data
- Uses a friendly, encouraging tone
- Has conversation starters:
"Show my open deals"
"Deals closing this month"
"Find contacts at a company"
"Pipeline summary"
```
### Create a knowledge-based Copilot
```text theme={null}
Create a Support Assistant Copilot that:
- Answers customer questions using our FAQ and troubleshooting docs
- Can search the web for additional product information
- Uses a helpful, patient tone
- Has conversation starters:
"How do I reset my password?"
"Check my order status"
"Return policy"
"Contact support"
```
### Add a Copilot to a page
```text theme={null}
Add a Copilot to the deals page connected
to the Sales Coach.
```
### Full Copilot setup
```text theme={null}
Build an employee onboarding app with:
- New hires (name, email, start date, department, buddy)
- Onboarding tasks (task name, description, due date, status, linked to new hire)
- A checklist view for each new hire's tasks
Create an Onboarding Guide Copilot that:
- Helps new hires find their tasks and deadlines
- Can query new hires and onboarding tasks data
- Uses a warm, welcoming tone
- Has conversation starters:
"What are my onboarding tasks?"
"What's due this week?"
"Who is my onboarding buddy?"
"Company policies"
Upload our employee handbook and IT setup guide
to the Copilot's knowledge base.
Add the Onboarding Guide Copilot to the onboarding
checklist page.
```
***
## Gaia Autopilot
### Stalled-deal chaser
```text theme={null}
Add a stalled-deal chaser. Watch the deals collection.
Every weekday at 9 AM, find deals over $5,000 that
haven't moved stage in 14 days. Draft a follow-up email
to the contact and route it to the deal owner's
Autopilot inbox.
```
### Daily briefing per user
```text theme={null}
Add a personal daily briefing for each sales rep.
At 8 AM in their timezone on weekdays, summarize:
top 5 deals closing this week, tasks due today and
tomorrow. Land the draft in the user's Autopilot inbox.
One per day max.
```
### SLA enforcer for tickets
```text theme={null}
Add an SLA enforcer to the support app. Every 15 minutes,
find open tickets older than 24 hours with no first
response. Notify the assignee in-app, and draft a customer
status update for the team lead's Autopilot inbox.
```
### Inventory watchdog
```text theme={null}
Add an inventory watchdog. Watch the products collection.
When a product's quantity drops to or below its reorder
point, draft a reorder request email to the preferred
supplier and route it to the operations lead's Autopilot.
```
***
## Tips for adapting these prompts
Anywhere you see `[something]`, replace it with your specific details.
These are starting points. Add fields you need, remove ones you don't.
Mix and match sections from different examples.
Start with the basic version, then add features in follow-up prompts.
## Learn more
Templates organized by app type
Detailed dos and don'ts
# Prompt strategy
Source: https://docs.gainable.dev/prompting/overview
How to talk to Gainable for the best results
## The art of prompting
Gainable understands natural language, but how you describe things affects what you get. This guide will help you write prompts that produce exactly what you want.
## The golden rule
**Be specific about your data, clear about relationships, and explicit about features.**
The more specific your prompt, the more accurate your app.
## 5 key principles
### 1. Name your fields explicitly
Tell Gainable exactly what data you want to track.
```text Good theme={null}
Build a contact manager with:
- Name, email, phone number
- Company they work for
- Job title
- Last contacted date
```
```text Vague theme={null}
Build something to track contacts
```
Why this matters: When you name fields, Gainable creates exactly those fields. When you're vague, it has to guess.
### 2. Describe relationships
If data is connected, say how.
```text Good theme={null}
Build a CRM where:
- Companies have a name, industry, and size
- Contacts belong to a company
- Deals are linked to both a company and a contact
```
```text Missing relationships theme={null}
Track companies, contacts, and deals
```
Common relationship patterns:
* "X belongs to Y" - Each X is linked to one Y
* "X has many Y" - One X can have multiple Y items
* "X and Y are linked" - They reference each other
### 3. Describe the user journey
Explain how people will use the app.
```text Good theme={null}
Users should be able to:
1. Create a new project
2. Add tasks to that project
3. Assign tasks to team members
4. Mark tasks as complete
5. See a progress dashboard
```
```text Unclear theme={null}
Make a project tracker
```
### 4. Request features by name
Use specific feature names when you know what you want.
| Instead of... | Say... |
| --------------------------- | ----------------------------------------- |
| "Show the data graphically" | "Add a pie chart showing deals by status" |
| "Make it organized" | "Add a kanban board with columns" |
| "Let people talk" | "Add a team chat" |
| "Make it sortable" | "Let me drag to reorder items" |
### 5. Iterate incrementally
Build your app step by step instead of all at once.
"Build a task tracker with title, description, and status"
"Add due date and priority to tasks"
"Add a dashboard with a chart showing tasks by status"
"Add a kanban board view"
Incremental building is more reliable than trying to specify everything upfront. Each step is smaller and easier for Gainable to get right.
## Prompt structure
A well-structured prompt typically has 3 parts:
### 1. What you're building (the entity)
```text theme={null}
Build a [thing] tracker...
Create a [thing] management system...
I need to track [things]...
```
### 2. What data it stores (the fields)
```text theme={null}
...with [field 1], [field 2], and [field 3]
...including name, status, and due date
...that has title, description, priority, and assignee
```
### 3. What you can do with it (the features)
```text theme={null}
...and a dashboard showing totals
...with a kanban board for status
...where I can filter by date
```
## Complete example
Here's a well-structured prompt that combines all principles:
```text theme={null}
Build a customer support ticket system where:
Tickets have:
- Title and description
- Priority (low, medium, high, urgent)
- Status (new, in progress, resolved, closed)
- Customer email
- Assigned agent
- Created date
I should be able to:
- Create new tickets
- Assign tickets to agents
- Update ticket status
- Add comments to tickets
Show a dashboard with:
- Total open tickets count
- Tickets by priority (pie chart)
- Tickets by status (bar chart)
- Recent tickets list
Use a kanban board for the main ticket view, organized by status.
```
This prompt is specific about data, clear about features, and describes the user journey.
## What to avoid
These patterns lead to unpredictable results:
| Don't | Do instead |
| ------------------------ | ---------------------------------------------------------- |
| "Make me a CRM" | "Track deals with company, amount, status, and close date" |
| "Add some charts" | "Add a pie chart showing deals by status" |
| "Make it pretty" | "Use the cupcake theme" |
| "Like Salesforce" | Describe the specific features you need |
| Everything in one prompt | Build incrementally |
## Learn more
Detailed dos and don'ts
Real prompts you can copy
Templates for common app types
# Changing a built app
Source: https://docs.gainable.dev/prompting/refining
How to ask for changes once your app is up and running
Building an app is one conversation. Changing it is a different one, with different rules — the app already exists, so every request lands against something real.
This page is about the chat panel in the Gainable builder. Driving Gaia from Claude Code, Claude, or Cowork instead? The same planner does the work and the same advice applies — see the [`chat` tool reference](/mcp/tools#chat) for what differs.
## What happens when you send a change
It sees what's already built, not just your sentence.
A title, a one-line summary, and a checklist — written live, filling in as the planner works.
Nothing changes until you click **Accept**. **Reject** doesn't undo anything; it throws the plan away so you can describe it differently.
The send button becomes a **stop** button and the input reads *"Agent working…"*. Click stop to cancel.
Reading the plan card before accepting is the cheapest quality check available. If the checklist mentions a page you didn't ask about, reject it and say which page you meant — that costs seconds, where letting it run costs a build and an undo.
Notice how short that checklist is. A one-line request should produce a one-line plan; a checklist that has grown extra items is usually a sign the request carried more than you meant it to.
The **Auto accept plans** toggle in the chat toolbar skips the approval step. Useful once you trust a run of small changes; turn it back off for anything structural.
**One change runs per app at a time.** Sending a second request while one is building is refused rather than queued — wait for the first to finish.
### When Gaia asks a question back
Sometimes the plan card is replaced by a question with two to four options. That happens when the request has more than one reasonable reading, is missing something the planner can't infer, or is too vague to scope.
It is not a failure, and it's cheaper than the alternative. Answer it and the turn continues.
If your request was about something you screenshotted, attach the screenshot again with your answer. The follow-up is an ordinary message, and re-attaching is the reliable way to keep the picture in play.
## Say where the change goes
### The page you're on is a hint, not a target
The builder tells the planner which page you're looking at, but treats it as a clue rather than an instruction — because a request that names somewhere else has to win.
```text Good theme={null}
On the deals page, add a filter dropdown for status
```
```text Ambiguous theme={null}
Add filtering
```
Name the page whenever the change belongs to a specific one. Asking about deals while standing on Companies has produced a plan that targeted Companies — the page you're on is a strong hint, and an unnamed request lets it win.
Attaching a screenshot or selecting an element on the page removes the ambiguity entirely. Then the page isn't a hint any more — it's the thing you pointed at.
### Name the thing you're changing
Reference what already exists, by the name the app uses for it.
```text Good theme={null}
Add a due date field to the Task model
```
```text Less clear theme={null}
Add due dates
```
```text Good theme={null}
Add a chart showing Tasks grouped by status
```
```text Creates confusion theme={null}
Add a chart showing items by category
```
### Say it in the app's own words
If the app already has a component that does the job, name it and you'll get that component. Describe the behaviour instead and you may get a hand-written reimplementation of something that already shipped.
```text Good theme={null}
Add a task list to the deal detail page
```
```text Invites a reimplementation theme={null}
Add a checklist where I can tick things off,
with overdue ones in red
```
## Bug or preference?
This distinction is worth more than any other phrasing tip on this page.
A **bug** is the app failing to do what it was built to do. A **preference** is you wanting it to do something different. Gaia handles both, but it handles them through different paths — and a preference reported as a bug sends it hunting for a defect that was never there.
```text Preference — say it as a change theme={null}
Change the notes field on the task form
from required to optional
```
```text Reads as a bug report theme={null}
Notes shouldn't be mandatory, please fix this
```
"Make notes not mandatory" phrased as a defect has cost thirty turns of diagnosis for what was a one-line change. If the app is doing exactly what you asked for and you've changed your mind, say so plainly — *"change X to Y"*, not *"X is broken"*.
When something genuinely is broken, describe what you saw and what you expected:
```text Good theme={null}
The deal amount is showing without a dollar sign.
It should display as currency, like $50,000
```
```text Vague theme={null}
The amounts look wrong
```
```text Good theme={null}
On the deals page, when I click Add Deal and submit the form,
the deal doesn't appear in the list. I have to refresh to see it
```
```text Vague theme={null}
Adding doesn't work
```
Can't pin down what's wrong? Run [Audit codebase](/reference/troubleshooting#audit-codebase) — it checks the whole app rather than the part you suspect.
## Keep the request small
### One change per message
A small request gets a small, correctly-scoped plan. Padding one with extras you don't need produces a plan that touches more of the app than it should.
```text Good theme={null}
Add a phone number field to the Contact form
```
```text Over-scoped theme={null}
Add a phone number field to the Contact form, and while
you're there tidy up the layout, check the validation,
and maybe add a country code picker
```
Send them as separate messages instead. Each one gets its own plan you can read.
### Name both ends of a move
A move needs a source and a destination. With only one, there's nothing to change.
```text Good theme={null}
Move the Notes field from the sidebar into the main form
```
```text Does nothing theme={null}
Move the Notes field
```
### Don't add "keep X unchanged"
It reads like a safety net and works as the opposite. If `X` doesn't match something actually on the page, the clause sends the planner looking for it, and the request it was protecting gets lost. Existing views are edited surgically, never rewritten wholesale — the things you didn't mention are already safe.
```text Good theme={null}
Add a due date column to the tasks table
```
```text Risky theme={null}
Add a due date column to the tasks table, but keep the
sort order and grouping exactly as they are
```
## Show it instead: screenshots
Sometimes words aren't enough. Take a screenshot of your app and **annotate it** with drawings, arrows, and text to show exactly what you mean.
Draw freehand, add arrows, drop in text labels, or box an area.
The drawing says where; the sentence says what.
Reach for it when something **looks** wrong, when a layout needs rearranging, when an element is missing and you can point at the gap, or when position matters more than words can carry.
A circle and an arrow with "move this here" beats a paragraph. It also pins the page, so there's no ambiguity about which one you mean.
## Asking versus changing
Gaia can answer questions about your app without touching it.
```text Asks — nothing is built theme={null}
How does the task filtering work?
What fields does the Deal model have?
```
```text Changes — a plan card appears theme={null}
Add a due date field to tasks
Change the dashboard to show monthly data
```
Opening with "how", "what", "where", or "explain" gets you an answer. If a plan card appears when you only wanted to know something, reject it — nothing has changed.
## Adding a page, renaming a page
Asking for a page that doesn't exist **creates** it. You don't need a different command for a new page than for a change to an existing one — describe what you want and the planner checks it against the app's real page list.
Renaming a page is a **display** change. The name updates everywhere you see it, while the slug, the URL, and the underlying filenames stay as they are — so existing links keep working.
Changing the URL is a different, larger request. Say so explicitly if that's what you want.
## Conversations
Every change belongs to a **chat** — the same conversation unit you see in the builder. An app can have as many as you like, and each is titled automatically from its first message.
Start a new chat when you move to an unrelated topic. A long chat carries its history into every new request, which helps while you're iterating on one thing and gets in the way once you've moved on. You can pin, rename, and archive chats as they accumulate.
Which page you're looking at doesn't decide which chat you're in. A chat can span the whole app.
## Undoing a change
Every successful build is a snapshot. The most recent one can be reverted with the **Undo this build** button on its completion message.
To go further back, use commit history. See [How iteration works](/concepts/how-it-works#how-iteration-works) for both, including how rollback safety works.
The completion message is a summary of what the agent *did*, not proof of what you'll *see*. When a change is visual, look at the app before moving on — expanding the completion row shows which files were actually edited.
## Example requests
Refinement-shaped requests, in the form that works:
```text theme={null}
On the deals page, add a filter dropdown for status
Add a due date field to the Task model and show it in the tasks table
Move the Notes field from the sidebar into the main form
Change the notes field on the task form from required to optional
The chart should group deals by status, but it's grouping by company
Make the sponsors view the home page
```
Looking for a specific feature instead? Those live with the feature: [charts](/skills/chartjs), [kanban boards](/skills/kanban), [collaboration](/skills/weavy), [real-time updates](/building/real-time), [filters and views](/building/views), and [themes and colours](/skills/design).
## Learn more
Writing the prompt that builds it in the first place
Iteration, undo, and commit history
When something's wrong and you can't say what
The same changes from Claude Code, Claude, or Cowork
# Quickstart
Source: https://docs.gainable.dev/quickstart
Build your first app in 5 minutes
This quickstart shows the "Describe your app" path. If you already have data in Google Sheets, HubSpot, or another tool, check out [Build from data](/build-from-data) for a guided experience that starts from your existing data.
## Create your first app
Let's build a simple deal tracker to see Gainable in action. This will take about 5 minutes.
### Step 1: Start a new project
1. Go to [build.gainable.dev](https://build.gainable.dev)
### Step 2: Describe what you want
In the input box, type your first prompt:
```text Good prompt wrap theme={null}
Setup a dashboard with 3 KPIs: Total deals, won deals, and lost deals.
Create a table listing deals with customer, amount, assigned to, and close date for each deal; include a "Add new" deal button.
Lastly, add a line chart showing deals for each status over the last 12 months by deal close date.
Have it all vertically stacked; with KPIs 1st, chart 2nd, and table last.
```
```text What this creates theme={null}
- A Deal data model with all your fields
- A deals page with a table to manage deals
- Add, edit, and delete functionality
- A dashboard with KPI cards and a line chart
```
Being specific about your fields (like "deal name, company, and amount") helps Gainable create exactly what you need.
### Step 3: Watch it build
Gainable will show you a plan of what it's going to build, and if you choose to accept it will generate your entire application. You'll see:
1. **Plan preview** - What features will be created; if Gainable finds the request ambiguous it will ask follow-up questions
2. **Build progress** - Watch the build being generated
3. **Your app** - A working application appears in the preview panel with a message telling you what's been done
### Step 4: Use your app
Once the build completes, you can:
* **Add a deal** - Click the "Add Deal" button and fill in the form
* **View your dashboard** - See your data visualized in charts
* **Edit or delete** - Click on any deal to modify it
Your app updates in real-time. If you add a deal, the dashboard chart updates automatically.
## Try adding a feature
Now let's add something new. In the chat, type:
```text theme={null}
Add a kanban board view where I can drag deals between status columns
```
Gainable shows you a plan first. Accept it, and the kanban board is added to your existing app, preserving everything you've already built.
Changing an app follows different rules from building one — name the page you mean, keep each request to one change, and read the plan before accepting. See [Changing a built app](/prompting/refining).
## Tips for success
Instead of "track customers", say "track customers with name, email, company, and signup date"
If things are connected, say so: "each project has many tasks" or "contacts belong to companies"
Start simple and add features one at a time. Don't try to build everything in one prompt.
Ask for specific features: "add a pie chart", "add a kanban board", "add real-time updates"
## What's next?
Write prompts that get great results
Copy and adapt real prompts
Discover built-in features you can request
Connect existing data sources and build on top of them
A conversational assistant inside your app
Autonomous agents that draft work for approval
# API reference
Source: https://docs.gainable.dev/reference/api
Understanding the APIs in your generated apps
## Overview
Every Gainable app includes automatically generated API endpoints. These APIs power your app's functionality and can be used by external integrations.
You don't need to know about APIs to use Gainable. This reference is for users who want to understand how their apps work internally or integrate with external systems.
## API structure
For each data model you create, Gainable generates RESTful endpoints:
| Endpoint | Method | Description |
| ------------------ | ------ | --------------- |
| `/api/{model}` | GET | List all items |
| `/api/{model}` | POST | Create new item |
| `/api/{model}/:id` | GET | Get single item |
| `/api/{model}/:id` | PUT | Update item |
| `/api/{model}/:id` | DELETE | Delete item |
### Example
If you create a Deal model, you get:
| Endpoint | Method | Description |
| --------------- | ------ | ----------------- |
| `/api/deal` | GET | List all deals |
| `/api/deal` | POST | Create new deal |
| `/api/deal/:id` | GET | Get specific deal |
| `/api/deal/:id` | PUT | Update deal |
| `/api/deal/:id` | DELETE | Delete deal |
## Response format
All API responses follow this structure:
### Success response
```json theme={null}
{
"success": true,
"data": {
"_id": "507f1f77bcf86cd799439011",
"name": "Enterprise License",
"amount": 50000,
"status": "won",
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z"
}
}
```
### List response
```json theme={null}
{
"success": true,
"data": [
{ "_id": "...", "name": "Deal 1", ... },
{ "_id": "...", "name": "Deal 2", ... }
]
}
```
### Error response
```json theme={null}
{
"success": false,
"error": "Deal not found"
}
```
## Common operations
### Create an item
```bash theme={null}
POST /api/deal
Content-Type: application/json
{
"name": "Enterprise License",
"amount": 50000,
"status": "new"
}
```
### Update an item
```bash theme={null}
PUT /api/deal/507f1f77bcf86cd799439011
Content-Type: application/json
{
"status": "won"
}
```
### Delete an item
```bash theme={null}
DELETE /api/deal/507f1f77bcf86cd799439011
```
## Filtering
Most list endpoints support query parameters for filtering:
```bash theme={null}
# Filter by status
GET /api/deal?status=won
# Filter by multiple fields
GET /api/deal?status=won&amount[$gte]=10000
# Sort results
GET /api/deal?sort=-createdAt
# Limit results
GET /api/deal?limit=10
```
## Real-time events
When data changes, the server broadcasts events via WebSocket:
| Event | Payload | When |
| ----------------- | --------------- | ---------------- |
| `{model}:created` | New item | Item is created |
| `{model}:updated` | Updated item | Item is modified |
| `{model}:deleted` | Deleted item ID | Item is deleted |
### Example events
```javascript theme={null}
// Listen for new deals
socket.on('deal:created', (deal) => {
console.log('New deal:', deal);
});
// Listen for updates
socket.on('deal:updated', (deal) => {
console.log('Deal updated:', deal);
});
// Listen for deletions
socket.on('deal:deleted', (data) => {
console.log('Deal deleted:', data._id);
});
```
## Authentication
API requests require authentication. Your app handles this automatically through session cookies when accessed through the browser.
For external integrations, reach out via the live chat in the builder or email [support@gainable.dev](mailto:support@gainable.dev) for API key access.
## Rate limits
APIs have reasonable rate limits to ensure stability:
* **Standard**: 100 requests per minute
* **Bulk operations**: 10 requests per minute
If you hit a rate limit, you'll receive a 429 response.
## Data types
### Automatic fields
Every item includes:
| Field | Type | Description |
| ----------- | -------- | --------------------- |
| `_id` | ObjectId | Unique identifier |
| `createdAt` | Date | Creation timestamp |
| `updatedAt` | Date | Last update timestamp |
### Reference fields
When models reference each other, the API returns IDs:
```json theme={null}
{
"_id": "507f1f77bcf86cd799439011",
"title": "Task 1",
"project": "507f1f77bcf86cd799439012"
}
```
Use the project ID to fetch the related project.
## Best practices
The app's UI is the easiest way to interact with your data. Use APIs only when you need external integration.
Check for `success: false` responses and handle them appropriately.
Instead of polling, listen for WebSocket events to get instant updates.
## Learn more
Understanding your data structure
How real-time sync works
# Troubleshooting
Source: https://docs.gainable.dev/reference/troubleshooting
Common issues and how to resolve them
## Common issues
### Build didn't create what I expected
**Problem:** The app looks different from what you described.
**Solutions:**
1. **Be more specific** - Add detail to your prompt
2. **Break it down** - Build in smaller steps
3. **Clarify fields** - List exact field names and types
**Before (vague):**
```text theme={null}
Make a CRM
```
**After (specific):**
```text theme={null}
Build a CRM with:
- Companies (name, industry, size)
- Contacts (name, email, phone, linked to company)
- Deals (name, amount, status, linked to company)
- Dashboard with deal totals
```
### Data isn't saving
**Problem:** You fill out a form but the data disappears.
**Solutions:**
1. **Check required fields** - Make sure all required fields are filled
2. **Describe the issue** - Tell Gainable: "The deal form isn't saving. The data disappears after I click save."
3. **Reload and retry** - Refresh the page and try again
### Changes not appearing for other users
**Problem:** Real-time updates aren't working.
**Solutions:**
1. **Check internet connection** - Ensure you're online
2. **Refresh the page** - Sometimes connections need to reconnect
3. **Same view?** - Make sure other users are viewing the same page
### Chart showing wrong data
**Problem:** The chart doesn't match your expectations.
**Solutions:**
1. **Specify the grouping** - "Group by status" vs "group by month"
2. **Name the date field** - "Use close date for the timeline"
3. **Request a change** - "The chart should show deals by status, not by company"
```text theme={null}
The deals by status pie chart is showing the wrong data.
It should group deals by their status field (new, won, lost)
and show the count in each status.
```
### Kanban cards not dragging
**Problem:** Cards won't move between columns.
**Solutions:**
1. **Refresh the page** - Reload to reinitialize
2. **Check console** - Open browser dev tools for error messages
3. **Report the issue** - "Cards on the kanban board aren't dragging"
### Filter not working
**Problem:** Filter selections don't change the displayed data.
**Solutions:**
1. **Clear and reselect** - Reset the filter and try again
2. **Check the field** - Make sure items have values in the filtered field
3. **Describe the issue** - "The status filter on the deals page isn't filtering"
## Requesting fixes
How you phrase a fix decides how fast it lands — say what you saw and what you expected, and say whether it is a defect or a change of mind.
Reporting a bug precisely, and why a preference reported as a bug costs so much longer.
## Getting help
### Describe the issue clearly
Include:
* **What you were trying to do**
* **What happened instead**
* **Any error messages you saw**
* **Steps to reproduce**
### Example help request
```text theme={null}
Issue: New tasks aren't showing on the kanban board
Steps:
1. Click "Add Task" button
2. Fill out the form (title: "Test task", status: "To Do")
3. Click Save
4. Form closes but task doesn't appear in "To Do" column
5. After refreshing the page, the task appears
Expected: Task should appear immediately after saving
```
## Browser issues
### Clear cache and cookies
Sometimes browser data causes issues:
1. Open browser settings
2. Find "Clear browsing data"
3. Select "Cookies" and "Cached images/files"
4. Clear for the Gainable site
### Try a different browser
If issues persist, try:
* Chrome
* Firefox
* Safari
* Edge
### Disable extensions
Browser extensions can interfere. Try:
1. Disable ad blockers temporarily
2. Disable other extensions
3. Try incognito/private mode
## Performance issues
### Slow loading
If your app feels slow:
1. **Check your data volume** - Very large datasets may load slowly
2. **Add pagination** - "Paginate the deals list with 25 items per page"
3. **Add filters** - Filter to show fewer items at once
### Charts loading slowly
For charts with lots of data:
1. **Limit the data** - "Show last 12 months only"
2. **Aggregate** - "Group by month instead of by day"
3. **Simplify** - Reduce the number of charts on one page
## Audit codebase
When something is stuck or behaving unexpectedly, you can run an automatic audit that analyzes your entire codebase to identify issues.
### How to run an audit
1. Open the **Pages panel** on the left side of the builder
2. Click the **three-dot menu** (⋮) at the top of the panel
3. Select **Audit codebase**
The audit will analyze your codebase to identify issues that may be causing problems with your build. This may take a while depending on the size of your codebase.
Use **Audit codebase** whenever something is getting stuck or behaving unexpectedly. It's the fastest way to diagnose build issues without contacting support.
## Still stuck?
If you've tried the above and still have issues, reach out to our support team. You can get help two ways:
### Live chat support
Click the **chat icon** in the bottom-left corner of the builder. This is available on any screen — whether you're working with Pages, Agents, Mail, Users, Collections, or managing Datasets, Data models, and Connectors.
You'll be connected to our support team instantly, right inside the app.
### Email support
You can also email us at **[support@gainable.dev](mailto:support@gainable.dev)** for non-urgent issues or longer requests.
### Tips for faster resolution
When reaching out, include:
1. **What you were trying to do**
2. **What happened instead**
3. **Any error messages you saw**
4. **Your chat history** — this helps our team track down issues much faster
### How to export chat history
Your chat history contains the full conversation with the build agent, including what you asked for and what was built. To export it:
1. Click the **three-dot menu** (⋮) at the top of the Pages panel
2. Select **Chat history**
Always attach your chat history when contacting support — whether via live chat or email. It gives our team full context and helps us resolve your issue much faster.
Open the builder and click the chat icon in the bottom-left corner
Email us at [support@gainable.dev](mailto:support@gainable.dev)
# Charts & visualization
Source: https://docs.gainable.dev/skills/chartjs
Add data visualization to your Gainable apps
## Overview
Gainable apps include Chart.js for data visualization. You can add charts to any page by describing what you want to see.
## Chart types
### Line charts
Best for showing trends over time.
```text theme={null}
"Add a line chart showing sales per month"
"Display order count over the last 12 months"
"Show revenue trend as a line graph"
```
### Bar charts
Best for comparing categories.
```text theme={null}
"Add a bar chart comparing sales by region"
"Show deals closed by salesperson"
"Display monthly revenue as bars"
```
### Pie charts
Best for showing proportions.
```text theme={null}
"Add a pie chart showing deals by status"
"Display tasks by priority as a pie chart"
"Show revenue breakdown by product category"
```
### Doughnut charts
Similar to pie charts with a hole in the center.
```text theme={null}
"Add a doughnut chart for expense categories"
"Show completion status as a doughnut"
```
## Requesting charts
### Be specific about the data
```text Good theme={null}
"Add a pie chart showing deals grouped by status (won, lost, pending)"
```
```text Vague theme={null}
"Add a chart"
```
### Specify the chart type
```text Good theme={null}
"Add a line chart showing monthly revenue"
```
```text Ambiguous theme={null}
"Show monthly revenue"
```
### Name your metrics
```text Good theme={null}
"Dashboard with:
- Total deals (count)
- Pipeline value (sum of amounts)
- Deals by status (pie chart)
- Revenue by month (line chart)"
```
```text Incomplete theme={null}
"Dashboard with some charts"
```
## Common patterns
### Dashboard with KPIs and charts
```text theme={null}
"Add a dashboard showing:
- Total deals count (KPI card)
- Total pipeline value (KPI card)
- Average deal size (KPI card)
- Deals by status (pie chart)
- Deals closed per month (line chart)
- Top 5 deals by amount (table)"
```
### Charts on detail pages
```text theme={null}
"On the company detail page, add:
- Deals by status for this company (pie chart)
- Monthly revenue from this company (line chart)"
```
### Comparative charts
```text theme={null}
"Add a bar chart comparing:
- Deals by salesperson
- Revenue by product
- Orders by region"
```
## Date-based charts
When charting data over time, specify the date field:
```text theme={null}
"Line chart showing deals by close date per month"
"Bar chart of orders by order date"
```
If your data has a business date (like close date or order date), specify it. Otherwise, charts will use the creation date.
## Interactive features
Charts in Gainable are interactive:
* **Hover** - See exact values
* **Click** - Filter or drill down (when configured)
* **Resize** - Responsive to container size
* **Animate** - Smooth transitions on data change
## Real-time updates
Charts update automatically when data changes:
* New records are added to the chart
* Updated values refresh the visualization
* Deleted records are removed
* All without page refresh
## Chart placement
### On dashboards
```text theme={null}
"Dashboard with a pie chart on the left and line chart on the right"
```
### In cards
```text theme={null}
"Show the status distribution chart in a card"
```
### With data tables
```text theme={null}
"Above the deals table, show a chart of deals by status"
```
## Customization
### Colors
```text theme={null}
"Use green for won deals, red for lost, yellow for pending"
"Use the theme colors for the chart"
```
### Labels
```text theme={null}
"Show percentages on the pie chart"
"Include data values on the bars"
```
### Legends
```text theme={null}
"Put the legend below the chart"
"Hide the legend" (for simple charts)
```
## Best practices
* **Trends over time** → Line chart
* **Category comparison** → Bar chart
* **Part of whole** → Pie or doughnut
Limit pie charts to 5-7 segments. Use bar charts for more categories.
"Deals by Status" is clearer than "Chart 1"
Place charts where they're relevant - sales charts on sales pages, etc.
## Examples
### Sales dashboard
```text theme={null}
Build a sales dashboard with:
- Total revenue (KPI card)
- Deal count (KPI card)
- Win rate (KPI card)
- Revenue by month (line chart)
- Deals by stage (pie chart)
- Top salespeople (bar chart)
```
### Project overview
```text theme={null}
Add to the project dashboard:
- Tasks by status (doughnut chart)
- Tasks completed per week (line chart)
- Overdue tasks count (KPI card)
```
## Learn more
Understanding your data
Live chart updates
# Design & theming
Source: https://docs.gainable.dev/skills/design
Customize the look and feel of your Gainable apps
## Overview
Gainable apps use DaisyUI themes for consistent styling. You can customize colors, apply themes, and adjust the visual design through your prompts.
## Themes
Themes provide a complete color palette for your app. Request a theme by name:
```text theme={null}
"Use the corporate theme"
"Apply the cupcake theme"
"Switch to dark mode"
```
### Available themes
| Theme | Description |
| ----------- | ------------------------------------ |
| `light` | Clean, minimal light theme (default) |
| `dark` | Dark mode with high contrast |
| `cupcake` | Soft, playful pastels |
| `corporate` | Professional blues and grays |
| `retro` | Warm, vintage colors |
| `cyberpunk` | Bold neons on dark |
| `valentine` | Pinks and romantic tones |
| `garden` | Fresh greens and naturals |
| `forest` | Deep, earthy greens |
| `lofi` | Muted, relaxed tones |
| `pastel` | Soft pastel colors |
| `fantasy` | Purple and magical |
| `luxury` | Gold and black elegance |
| `autumn` | Warm oranges and browns |
| `business` | Serious, professional |
| `night` | Deep blue dark mode |
| `winter` | Cool blues and whites |
| `nord` | Nordic-inspired palette |
| `emerald` | Rich emerald greens |
### Choosing a theme
Match the theme to your app's purpose:
| App Type | Suggested Themes |
| -------------- | -------------------------- |
| Business/CRM | corporate, business, light |
| Fun/Consumer | cupcake, pastel, fantasy |
| Tech/Developer | cyberpunk, night, nord |
| Nature/Eco | garden, forest, emerald |
| Premium/Luxury | luxury, dark |
| Warm/Friendly | autumn, retro, lofi |
## Requesting themes
### Direct theme request
```text theme={null}
"Use the corporate theme"
"Apply dark mode"
```
### By description
```text theme={null}
"Professional, corporate feel" → corporate or business
"Playful and fun" → cupcake or pastel
"Modern and techy" → cyberpunk or night
"Warm and cozy" → autumn or retro
"Premium look" → luxury or dark
"Fresh and natural" → garden or emerald
```
If you describe a style like "professional" or "playful", Gainable will choose an appropriate theme automatically.
## Color customization
Beyond themes, you can request specific colors:
```text theme={null}
"Use blue and gray colors"
"Make the primary color green"
"Use a purple accent color"
```
### Color contexts
| Context | What it affects |
| --------- | ----------------------------- |
| Primary | Buttons, links, active states |
| Secondary | Secondary buttons, accents |
| Accent | Highlights, special elements |
| Neutral | Backgrounds, text |
## UI components
Gainable apps use DaisyUI components that adapt to your theme:
### Buttons
```text theme={null}
"Primary action buttons"
"Outline style buttons"
"Ghost buttons for subtle actions"
```
### Cards
```text theme={null}
"Cards with shadows"
"Bordered cards"
"Compact cards"
```
### Forms
```text theme={null}
"Bordered input fields"
"Floating label inputs"
"Compact form layout"
```
### Navigation
```text theme={null}
"Tab navigation"
"Sidebar navigation"
"Breadcrumb navigation"
```
## Layout requests
### Page structure
```text theme={null}
"Sidebar on the left with main content on the right"
"Header at top, content below"
"Full-width layout"
```
### Content layout
```text theme={null}
"2-column layout"
"Grid of cards"
"Stacked sections"
```
### Spacing
```text theme={null}
"More padding around content"
"Compact layout"
"Spacious design"
```
## Responsive design
All Gainable apps are automatically responsive. The layout adjusts for:
* **Desktop**: Full sidebar, multi-column grids
* **Tablet**: Collapsible sidebar, adjusted columns
* **Mobile**: Single column, hamburger menu
You don't need to request this - it's built in.
## Common customizations
### Add a sidebar
```text theme={null}
"Add a sidebar with navigation links to Dashboard, Deals, and Contacts"
```
### Style badges
```text theme={null}
"Show priority as colored badges:
- High: red
- Medium: yellow
- Low: green"
```
### Card styling
```text theme={null}
"Show deals as cards with shadows and hover effects"
```
### Table styling
```text theme={null}
"Striped table rows"
"Compact table with smaller text"
"Bordered table cells"
```
## Best practices
Consistency is better than mixing styles. Pick a theme that fits your purpose.
Themes handle colors automatically. You don't need to specify colors for every element.
"Professional and clean" works better than "use #1a1a1a with 16px padding"
Business apps → corporate themes. Fun apps → playful themes. Match user expectations.
## Examples
### Professional dashboard
```text theme={null}
"Use the corporate theme.
Clean layout with:
- Sidebar navigation
- KPI cards at the top
- Charts below
- Professional, minimal design"
```
### Playful task app
```text theme={null}
"Use the cupcake theme.
Friendly design with:
- Colorful status badges
- Card-based layout
- Fun, approachable feel"
```
### Dark mode app
```text theme={null}
"Use dark mode.
Modern, sleek design with:
- High contrast text
- Subtle borders
- Glowing accent colors"
```
## Changing themes later
You can always update the theme:
```text theme={null}
"Change the theme to dark mode"
"Switch to the forest theme"
"Make it look more professional"
```
The entire app updates to the new theme while keeping all your data and features.
## Learn more
Page layouts and components
Writing effective prompts
# Kanban boards
Source: https://docs.gainable.dev/skills/kanban
Add drag-and-drop workflow boards to your apps
## Overview
Kanban boards let you visualize work as cards in columns. Drag cards between columns to update their status. Gainable makes it easy to add kanban boards to any app.
## Requesting a kanban board
Simply describe what you want:
```text theme={null}
"Add a kanban board for tasks with columns: To Do, In Progress, Done"
"Show deals as a pipeline board"
"Create a task board where I can drag cards between columns"
```
## What you get
When you request a kanban board, Gainable creates:
* **Columns** based on your status options
* **Cards** for each item showing key information
* **Drag-and-drop** to move cards between columns
* **Real-time sync** so all users see changes
* **Column counts** showing how many items are in each column
## Defining columns
Columns typically correspond to status values. Be explicit:
```text Good theme={null}
"Kanban board with columns:
- Backlog
- In Progress
- Review
- Done"
```
```text Vague theme={null}
"Add a kanban board"
```
## Card content
Specify what information appears on each card:
```text theme={null}
"Cards show:
- Task title
- Assignee name
- Due date
- Priority badge"
```
Default card content usually includes:
* Primary field (name/title)
* Status or category badge
* Key details (date, assignee, etc.)
## Common patterns
### Task board
```text theme={null}
Build a task tracker with:
- Tasks: title, description, assignee, due date
- Status: to do, in progress, review, done
Add a kanban board where:
- Each column is a status
- Cards show title, assignee, and due date
- Dragging updates the task status
```
### Deal pipeline
```text theme={null}
Build a CRM with:
- Deals: name, company, amount, stage
- Stages: lead, qualified, proposal, negotiation, closed
Show deals as a pipeline board where:
- Each column is a stage
- Cards show deal name, company, and amount
- Dragging moves the deal to that stage
```
### Hiring tracker
```text theme={null}
Track candidates with:
- Name, position, source
- Status: applied, phone screen, interview, offer, hired
Kanban board with:
- Columns for each status
- Cards showing name and position
- Drag to advance candidates through the pipeline
```
## Customization
### Column colors
```text theme={null}
"Color the columns:
- To Do: purple
- In Progress: blue
- Done: green"
```
### Column actions
```text theme={null}
"Add a + button in each column header to create a new item in that status"
```
### Card actions
```text theme={null}
"Click a card to open an edit modal"
"Add a delete button to cards"
```
### Sublabels
```text theme={null}
"Show the total deal value in each column header"
"Display task count below each column name"
```
## Sorting within columns
By default, cards maintain their order. You can request ordering:
```text theme={null}
"Sort cards by due date within each column"
"Order cards by priority (high first)"
"Let users drag to reorder cards within a column"
```
## Real-time updates
Kanban boards update in real-time:
* **Card moves** appear instantly for all users
* **New cards** show up when created
* **Edited cards** refresh with new content
* **Deleted cards** disappear
When you drag a card, the change is saved immediately and all connected users see the move in real-time.
## Filtering
Add filters to focus on specific cards:
```text theme={null}
"Filter the board by assignee"
"Add a priority filter"
"Search cards by title"
```
## Multiple boards
You can have multiple kanban views:
```text theme={null}
"One board for my tasks (filtered to my assignments)"
"Team board showing all tasks"
"Archive board for completed items"
```
## Best practices
Too many columns make the board hard to use. Combine similar statuses if needed.
Show only essential info on cards. Details can go in a detail view on click.
"In Progress" is clearer than "Stage 2"
Colors help users quickly identify stages. Green for done, yellow for in progress, etc.
## Combining with other features
### Charts
```text theme={null}
"Above the kanban board, show a bar chart of task counts by status"
```
### List view toggle
```text theme={null}
"Let users switch between kanban view and list view"
```
### Filters
```text theme={null}
"Add assignee and priority filters above the board"
```
## Example: Complete task board
```text theme={null}
Build a task management app:
Tasks have:
- Title, description
- Status: backlog, to do, in progress, review, done
- Priority: low, medium, high
- Assignee (user)
- Due date
Show a kanban board where:
- Columns: Backlog, To Do, In Progress, Review, Done
- Column colors: gray, purple, blue, orange, green
- Cards show: title, priority badge, assignee avatar, due date
- Drag to move between columns
- Click card to edit details
- + button in each column header to add new task
Filters above the board:
- Filter by assignee
- Filter by priority
```
## Learn more
How sync works
Other view types
# Collaboration features
Source: https://docs.gainable.dev/skills/weavy
Add chat, files, comments, and messaging to your apps
## Overview
Gainable apps can include collaboration features powered by Weavy. These components are self-contained and work out of the box.
## Available components
### Chat
Real-time group messaging for teams or contexts.
```text theme={null}
"Add a team chat"
"Include chat for each project"
"Add a discussion area"
```
**Best for:**
* Team discussions
* Project-specific conversations
* Context-based chat (per deal, per task, etc.)
**Features included:**
* Real-time messages
* Message history
* Typing indicators
* Read receipts
* Emoji reactions
* File sharing in chat
### Messenger
Private direct messaging between users.
```text theme={null}
"Add direct messaging"
"Let users send private messages"
"Include a messenger"
```
**Best for:**
* One-on-one conversations
* Private discussions
* User-to-user communication
**Features included:**
* Conversation list
* Direct messages
* Unread counts
* User presence (online/offline)
* Search conversations
**Chat vs Messenger:**
* Use **Chat** for group/contextual conversations (project chat, team chat)
* Use **Messenger** for private user-to-user messaging (like Slack DMs)
### Files
Document upload and sharing.
```text theme={null}
"Add file sharing"
"Let users upload documents"
"Include file attachments"
```
**Best for:**
* Document collaboration
* Sharing attachments
* File organization
**Features included:**
* Drag-and-drop upload
* File previews
* Download links
* File type icons
* Version history
### Comments
Threaded discussions on specific items.
```text theme={null}
"Add comments to tasks"
"Let users comment on deals"
"Include discussion threads"
```
**Best for:**
* Item-specific discussions
* Feedback and reviews
* Activity logs
**Features included:**
* Threaded replies
* @mentions
* Timestamps
* Edit and delete
* Reactions
### Posts / Activity Feed
Social-style updates and announcements.
```text theme={null}
"Add an activity feed"
"Include a news feed"
"Add team announcements"
```
**Best for:**
* Team updates
* Announcements
* Activity streams
**Features included:**
* Create posts
* Comments on posts
* Reactions
* Rich text formatting
* File attachments
### Notifications
Notification center for all collaboration activity.
```text theme={null}
"Add notifications"
"Show unread message count"
"Include notification bell"
```
**Features included:**
* Unread counts
* Notification list
* Mark as read
* Click to navigate
## Placement patterns
### Page-level
Everyone on the page sees the same component:
```text theme={null}
"Add a team chat to the dashboard"
```
### Item-level
Each item has its own instance:
```text theme={null}
"Add chat to each project"
"Add files to each deal"
"Add comments to each task"
```
### Global
Accessible from anywhere:
```text theme={null}
"Add a messenger accessible from all pages"
"Add notification bell in the header"
```
## Examples
### Project workspace
```text theme={null}
Build a project manager with:
- Projects (name, status, description)
- Tasks for each project
On the project detail page, add:
- Team chat for project discussions
- File sharing for project documents
- Activity feed for updates
```
### CRM with collaboration
```text theme={null}
Build a CRM with:
- Companies and contacts
- Deals linked to companies
On each deal page, add:
- Comments for internal notes
- Files for proposals and contracts
```
### Team dashboard
```text theme={null}
Build a team dashboard with:
- Announcements feed
- Team chat
- Shared files area
- Notification bell in header
```
## Combining components
You can use multiple collaboration features together:
```text theme={null}
"On the project page:
- Chat tab for discussions
- Files tab for documents
- Activity tab for updates
- Comments on individual tasks"
```
## Real-time behavior
All collaboration components are real-time:
* Messages appear instantly
* Files show immediately after upload
* Comments update live
* Notifications push automatically
## Notifications
Gainable handles notifications automatically:
* **Toast notifications** appear for new messages
* **Badge counts** show unread items
* **Notification center** collects all activity
Users receive notifications for:
* New messages in their chats
* @mentions in comments
* Replies to their posts
* File shares
## Best practices
* **Chat**: Ongoing discussions
* **Comments**: Item-specific feedback
* **Files**: Document sharing
* **Messenger**: Private conversations
Put chat on project pages for project discussions, not floating randomly.
* Global chat can get noisy
* Item-level chat stays focused
* Choose based on your team size and use case
Pick the collaboration features that make sense. Not every page needs chat, files, and comments.
## Layout options
### Inline
Component appears directly on the page:
```text theme={null}
"Show the chat in the main content area"
```
### Drawer
Component slides out from the side:
```text theme={null}
"Open chat in a slide-out drawer"
"Show files in a right panel"
```
### Modal
Component appears in an overlay:
```text theme={null}
"Open messenger in a modal"
```
### Tab
Component is one tab among several:
```text theme={null}
"Tabs: Overview, Chat, Files, Comments"
```
## Learn more
How real-time works
Integration patterns