# Proforma agent playbook

Proforma is your AI research lab: investigate with data, build Apps and
carry improvements into software and operations. Bring data, code, documents and AI into
one place. Apps are the interactive surface; calculation logic, methods and
evidence support the work.

The five workspace primitives are:

- **Source** — a raw queryable relation produced by ingest;
- **Model** — a reusable SQL-defined derived relation;
- **App** — one atomic multi-file React project with its own routes;
- **Action** — a TypeScript routine for execution and orchestration;
- **Chat** — an AI agent conversation.

A Workspace holds the primitives. Files are the authoring surface; Data is the
unified discovery and query interface for permitted relations. Keep research
notes and findings in Files, analyses in Models or Actions, and interactive
views in Apps. Record the inputs and assumptions needed to understand a result.

Some live API and CLI commands retain legacy Page naming. Follow advertised
routes and schemas rather than inferring API names from product labels.

## Public product map

The canonical public surface maps every product job to a stable page:

- [Company overview](/) — interactive Apps for experimentation, a worked
  example, and ways to start;
- [Product](/product) — interactive Apps and computational tools: notes,
  data, models, Apps, Actions, agents and the five primitives;
- [Projects](/projects) — research and delivery across diligence, growth,
  technical R&D and other investigations, with practical examples; and
- catalogues and reference: [Integrations](/integrations),
  [Developer reference](/developers), [Security](/security), and
  [Company](/company).

These capability pages combine Source, Model, App, Action, and Chat. They do
not introduce additional workspace primitives or separate API entities.

### Website growth requirements and exclusions

- Pageviews, sessions or visitors, referrer and UTM fields, form submissions,
  custom events, configurable date windows, and equivalent prior-period
  comparisons can be analyzed through tracking plus Models or queries.
- Known-person and account resolution requires `identify` or `group`
  instrumentation and a configured HubSpot or Salesforce Source. Calling an
  account a top prospect also requires an agreed prospect or account score.
- The current tracking relation does not expose queryable engaged time or
  aggregate maximum scroll depth. Do not infer either measure from
  session-replay scroll events.
- A reusable parameterized review and arbitrary scheduled outbound Slack
  delivery are not included today. A Chat can reply only through its
  originating channel; this is not a general Slack action.
- Creating a task, content change, experiment scaffold, or pull request
  requires an eligible executor Connection, repository access, explicit human
  approval, and auditable execution. An executor assignment may return a branch
  or pull request; it never inherits merge or production-deployment authority.

## Work from the outcome

1. Restate the business question or implementation result the user needs.
2. Load only the workspace context relevant to that result.
3. Reuse existing definitions and artifacts before creating new ones.
4. Prefer approved Models over raw Sources when answering business questions.
5. Keep lasting work in a Model, Page, Action, or Chat rather than only in your
   response.
6. Write approved changes as normal Workspace revisions only when the
   connection explicitly grants them. Use ETags and stable idempotency keys.
7. Return ids and links for anything you create or run, including
   `resource.links.app` for every Page write.

## Run a governed software intervention

1. Start from a specific business signal and measurable result, not a request
   to generate code in the abstract.
2. Keep the outcome, acceptance criteria, repository or Workspace scope,
   budget, approvals, and expected proof in durable Work.
3. Build with Proforma Pages and Actions when the work belongs inside the
   Workspace. Use an executor assignment when bounded repository code is the
   right implementation path.
4. Cursor Cloud is the current outbound coding executor. In an interactive
   Chat, let the person review the repository allowlist and continue through
   Cursor's browser sign-in; do not ask them to mint or paste an API key.
5. Treat Codex, OpenCode, and private runners as future or private adapter paths
   until live discovery reports an eligible Connection. Do not imply that an
   unavailable provider is connected.
6. Track normalized status, usage, branch, and pull-request evidence beneath
   the same Work. The assignment stops before merge and deployment; repository
   CI, human review, and release policy retain that authority.
7. Use only approved, currently available product and channel capabilities to
   reach the audience. Connect adoption, conversion, CRM, billing, support, and
   warehouse outcomes back to the original Work before proposing the next
   decision.

## Connect to the workspace

The shell agent should initiate access. If the `prfm` CLI is available, run:

```sh
prfm login --api-url https://app.proformalabs.ai --access explore
```

Use `--access build` when a CLI task must create or revise ordinary Workspace
Files or Pages. Repeat `--scope` to request only the subset of that mode needed
for the current job. A synthetic Page-only build, for example, can use:

```sh
prfm login --api-url https://app.proformalabs.ai \
  --access build \
  --scope workspace:read \
  --scope workspace:write \
  --purpose "Publish a synthetic reconciliation Page"
```

The command shows a verification link and matching user code. The human signs
in, selects a Workspace, reviews the exact scopes and expiry, and approves or
denies the request. The CLI polls privately, validates `/v1/session`, and stores
the issued token in an origin- and Workspace-specific credential profile without
printing it.

The CLI credential remains private to `prfm`: `prfm login` does not print or
export `PROFORMA_API_TOKEN` for a later `curl` command. The same stored
credential can validate and write Pages through CLI commands; do not start a
second device flow merely to author a Page.

If the CLI is unavailable, an HTTP-capable agent can use the installation-free
device flow. Request an exact scope subset when the complete preset is not
needed:

```sh
export PROFORMA_API_URL=https://app.proformalabs.ai
umask 077
authorization_file="$(mktemp)"

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"connectionName":"Shell agent","access":"build","requestedScopes":["workspace:read","workspace:write"],"purpose":"Write the requested Page in the Workspace"}' \
  --output "$authorization_file" \
  "$PROFORMA_API_URL/v1/auth/device"

jq -r '"Open: \(.verificationUrlComplete)\nConfirm code: \(.userCode)"' "$authorization_file"
```

Keep the returned `deviceCode` in a private file, show only the safe verification
link and user code, and poll `POST /v1/auth/token` no faster than the response's
advertised interval. Write the successful exchange directly to a mode-`0600`
credential file or secret store. Never paste the token into chat, commit it, put
it in a URL, or expose it to browser code. Bound polling with a monotonic local
deadline derived from `expiresInSeconds`; use `expiresAt` only for display.

For this raw HTTP path, load the token from that client's private store into
only the process making requests, then verify the live grant:

```sh
export PROFORMA_API_TOKEN='<read from the private credential store>'

curl \
  -H "Authorization: Bearer $PROFORMA_API_TOKEN" \
  "$PROFORMA_API_URL/v1/session"
```

The response identifies the Workspace, connection, expiry, scopes, and currently
available operations. Start from `GET /v1` for the machine-readable contract.
Manual token creation in Settings -> Coding agents remains a fallback for
administrators and non-interactive environments.

The raw browser grant covers only its approved scope list. Browse with
`GET /v1/fs?path=/`; validate a Page with `POST /v1/pages/validate`; use
conditional `PUT /v1/fs` for ordinary File or complete Page writes. Linked
`/api/agent/*` operations below require their own explicitly granted scopes
until equivalent v1 links appear in discovery.

## Load the context for this job

Send the user's actual request, not a generic category:

```sh
curl \
  -X POST \
  -H "Authorization: Bearer $PROFORMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task":"Explain the retention decline, publish the review Page, and monitor the affected accounts","maxModels":6}' \
  "$PROFORMA_API_URL/api/agent/context"
```

Follow the returned links to inspect relevant Sources, Models, Pages, Actions,
and existing Page context. Agents receive bounded data access rather than
warehouse credentials.

## Investigate a changing metric

Use this sequence for questions such as “Why did margin fall?” or “Which
accounts explain the retention decline?”

1. Find the approved Model that defines the metric.
2. Confirm its grain, time window, filters, and freshness.
3. Compare the relevant periods or cohorts.
4. Quantify the largest drivers and identify the evidence behind them.
5. Save repeatable analysis in a Page or continue it in a Chat.
6. Report the answer, caveats, supporting artifact, and next action.

## Build an operating Page

1. Inspect existing Pages and Models for the requested workflow.
2. Reuse established metric definitions and visual patterns.
3. Build the smallest view that supports the decision.
4. Include freshness, filters, and enough evidence to explain the result.
5. Save the complete `project-v1` package locally and run
   `prfm page validate --from <project.json>`. Fix every error before writing.
6. Write it with `prfm fs put <extensionless-path> --kind page --from <project.json>`,
   using `--create` or the current ETag in `--if-match` and a stable
   `--idempotency-key`.
7. Return the response's path, Page id, revision, revision id, ETag, commit id,
   idempotency key, committed timestamp, replay status, and
   `resource.links.app`.
8. Call the result statically validated and durably saved. Claim runtime or
   visual verification only after performing those separate checks.

## Define or revise a Model

1. Confirm the business definition, grain, ownership, and downstream consumers.
2. Search for an existing Model that can be extended.
3. Write the SQL definition against accessible Sources or Models.
4. Validate representative rows and edge cases.
5. Describe what the Model means in business language.
6. Use only the authoring route advertised by live v1 discovery, then return
   its durable receipt with any affected Pages or Actions called out.

## Automate the follow-through

Use an Action when the result must keep running after the conversation:

1. Identify the signal, threshold, cadence or event, and responsible owner.
2. Read from an approved Model whenever possible.
3. Make the action observable and safe to retry.
4. Require review for consequential external actions unless the connection
   explicitly allows them.
5. Return the Action and run ids, current status, and how to stop it.

## Implement tracking or an integration

When working in an external codebase:

1. Load the workspace context and existing event or Source definitions.
2. Implement the instrumentation or connector in the user's codebase.
3. Validate that received data matches the expected shape.
4. Update the corresponding Proforma context, Source, Model, Page, or Action.
5. Return both the code change and the Proforma revision or run ids, plus app
   links for Pages.

## Run durable analysis with Proforma

Delegate warehouse analysis to a Chat when continuity, evidence, or later
inspection matters:

```sh
curl \
  -X POST \
  -H "Authorization: Bearer $PROFORMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat":"Quarterly revenue review",
    "createIfMissing":true,
    "message":"Explain the three largest changes in revenue this quarter and identify the owners of the next actions.",
    "metadata":{"callerName":"codex"}
  }' \
  "$PROFORMA_API_URL/api/agent-api/chat-runs"
```

Save the returned Chat and run ids. Use them to continue the analysis, inspect
status, or diagnose a failed run.

## Review and safety

- Treat the token as a secret and operate only within its workspace and scopes.
- Do not work around Model allow-lists, row limits, filters, or approvals.
- State when data is missing, stale, or insufficient for the requested decision.
- Use write access only for the concrete task the person approved, and preserve
  newer work with the current resource ETag.
- Keep external side effects proportional to the user's request and granted
  permissions.
- Keep verification claims tied to evidence: static validation, durable
  readback, runtime execution, and visual review are separate checks.
- For a synthetic demo, state that no real accounts or data were connected and
  distinguish session-only controls, suggestions, matching rules, or activity
  from durable Workspace audit history and real external-system effects.

## Connection references

- [Live v1 API map](https://app.proformalabs.ai/v1) — bootstrap, session,
  Workspace Files, current resources, and scopes
- [HTTP agent onboarding](/agents#http) — choose a task and copy a safe,
  installation-free connection prompt
- [Agent API map](https://app.proformalabs.ai/api/agent) — additional
  methods, and scopes
- [Coding-agent CLI](/product#cli) — shell commands and file-based implementation
  workflows
- [MCP connection](/product#mcp) — tool and resource discovery for MCP-capable hosts
- [Product](/product) — business outcomes, capabilities, and technical primitives
- [Projects](/projects) — project selection, implementation, and operating examples
- [Developer reference](/developers) — external agent workflow and live technical contracts
- [Integration catalog](/integrations) — provider resources and independent
  data, event, and action readiness

All connections use the same Workspace policy, revocation path, and audit
history. Browser authorization creates the same named connection used by manual
token provisioning; it does not create a parallel identity system.