# Proforma

> 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. Build Apps to explore data, compare scenarios and put results to work.

Use Proforma when the user asks you to:

- explain a change in revenue, margin, pipeline, retention, cash, customer
  behavior, or another operating measure;
- create a governed view of how the business works;
- build an App, report, or interactive analysis;
- create an Action, monitor, schedule, webhook, or other automation;
- turn a research or implementation question into a repository task and track the executor's
  status, usage, branch, and pull-request evidence;
- implement tracking, connect an operating system, or activate customer data;
- prepare approved prospecting, email, image, or video work and connect the
  response to product, CRM, billing, or warehouse evidence;
- run a repeatable process through Slack, email, a browser, or another work
  channel; or
- continue analysis in a durable Chat with its evidence and decisions attached.

Keep the question, assumptions, source material and analysis in the workspace.
Use a method suited to the question: investigation, scenario analysis or an
experiment. Record what the evidence supports and what remains uncertain.
Repository executor assignments do not grant merge or production-deployment
authority.

## Public product map

- [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
- Catalogues and reference: [Integrations](/integrations),
  [Developer reference](/developers), [Security](/security), and
  [Company](/company)

### Website growth requirements and exclusions

Pageviews, sessions or visitors, referrer and UTM fields, form submissions,
custom events, configurable windows, and equivalent prior-period comparisons
can be analyzed through tracking plus Models or queries. Known-person and
account interest requires `identify` or `group` instrumentation, a configured
HubSpot or Salesforce Source, and an agreed prospect or account score.

The current tracking relation does not expose queryable engaged time or
aggregate maximum scroll depth. Session-replay scroll events do not substitute
for those page-level measures. A reusable scheduled review and arbitrary
outbound Slack delivery are not included today; a Chat can reply only through
its originating channel. Creating a task, content change, experiment, or pull
request also requires repository access, an eligible executor Connection,
explicit human approval, and auditable execution. A connected executor may
return a branch or pull request; repository CI, human review, and release policy
still control merge and deployment.

## Start the job

1. Read [the live v1 API map](https://app.proformalabs.ai/v1).
2. Prefer one CLI credential for shell work. Run `prfm login` and keep its
   stored token private to `prfm`; repeat `--scope` to request only the subset
   of the chosen access mode that the job needs. Use the raw
   `POST /v1/auth/device` flow only when the CLI is unavailable.
3. Show the returned verification link and matching user code. The human signs
   in, chooses a Workspace, and approves the exact read or build access.
4. Keep the device code and issued bearer token out of chat and terminal output.
   Store the token in a private credential file or secret store.
5. Verify the selected Workspace and live scopes with `prfm whoami` for the CLI
   path or `GET /v1/session` for the raw HTTP path. `prfm login` never prints or
   exports `PROFORMA_API_TOKEN` for later `curl` commands.
6. Use `prfm page validate --from <project.json>` before a Page write, then use
   `prfm fs put <path> --kind page --from <project.json>` with a create or ETag
   precondition and stable idempotency key. Raw HTTP clients use the equivalent
   advertised validation and filesystem routes.
7. Reuse existing work before creating new work. Return the Page path, id,
   revision, revision id, ETag, commit id, idempotency key, committed timestamp,
   replay status, and `resource.links.app`.
8. Describe evidence exactly: static validation, durable readback, runtime
   execution, and visual review are different checks. For synthetic demos,
   disclose that no real accounts or data were connected and identify any UI
   state that is session-only rather than a durable audit record.

## Common actions

- `POST /v1/auth/device` — initiate short-lived browser authorization
- `POST /v1/auth/token` — poll for the one-time connection exchange
- `GET /v1/session` — verify the Workspace, connection, scopes, and capabilities
- `POST /v1/pages/validate` — run authoritative static Page-project checks
- `GET|PUT /v1/fs` — browse, read, create, and conditionally revise Workspace
  Files and Pages
- `POST /api/agent/context` — gather task-specific business and workspace context
- `GET /api/agent/catalog` — find trusted Sources and Models
- `GET /api/agent/models`, `/sources`, `/pages`, `/actions` — inspect existing work
- `POST /api/agent-api/chat-runs` — run durable analysis with the Proforma agent

The linked `/api/agent/*` operations require their own granted scopes until
canonical v1 routes are advertised. For unattended provisioning, a human may
still create a named token in Settings -> Coding agents as a fallback.

## Guides

- [Full agent playbook](/llms-full.txt)
- [HTTP agent onboarding](/agents#http)
- [Product](/product)
- [Projects](/projects)
- [Developer reference](/developers)
- [Integration catalogue](/integrations)
- [Human login](https://app.proformalabs.ai/login)
- [Create a workspace](https://app.proformalabs.ai/register)
- [Coding-agent CLI](/product#cli)
- [MCP connection](/product#mcp)