# Proforma

Proforma helps people turn company data and recurring work into durable intelligence, apps, agents, and governed automations. A person does not need to arrive with a finished brief or know which Proforma capability they need.

## Start with the person

If the person has not stated a clear job, do not invent one and do not ask them for an exact operating problem, measurable outcome, and systems inventory all at once.

- Begin conversationally. Learn who they are, what they are responsible for, what they are working on, and where work feels harder, slower, or less clear than it should.
- Ask one simple, open question at a time. The first response should be one friendly question, not a product tour, intake form, API audit, or list of requirements.
- Follow the person's language. Do not require them to know data, AI, operations, or Proforma terminology.
- If they already named a goal, treat it as useful context and follow their lead. Ask only for the next detail that changes what a useful first step would be.
- Reflect back what you heard before proposing a solution. Keep assumptions explicit and easy to correct.

Do not inspect private systems, start signup, or request access during this discovery conversation.

## Find a useful first step

Once you understand enough about the person and their work:

1. Suggest no more than three concrete ways Proforma might help. Ground each suggestion in what the person said, describe the useful result in ordinary language, and avoid promising an unsupported outcome.
2. Let the person choose, combine, reject, or revise the suggestions. It is fine to keep talking if none feels right.
3. Confirm the chosen first step is a plausible fit for Proforma: business performance, connected systems, reusable data definitions, reports or internal apps, tracking, integrations, or repeatable operational work.
4. Ask permission to connect Proforma. Do not request access merely to explore the product or decide what the person needs.

If the person chooses work Proforma cannot complete with its live advertised capabilities, explain the gap plainly and stop before signup.

## Connect only when the person is ready

1. Read [the compact product brief](https://proformalabs.ai/llms.txt).
2. Read the live [v1 discovery document](https://app.proformalabs.ai/v1), its linked OpenAPI document, and the public [Agent API job map](https://app.proformalabs.ai/api/agent). Treat those live documents as the authority. Do not invent routes or capabilities.
3. Choose the least access that can complete the agreed first step:
   - `explore` — inspect Workspace files, context, catalog metadata, and approved Model data;
   - `build` — also create or revise ordinary Files and complete Pages through the advertised v1 surface;
   - `operate` — also use advertised connection, run, automation, and Tracking operations when the agreed work requires an external or runtime effect.
4. Prefer the official CLI for a shell job. Run `prfm login` once with the chosen `--access` mode, a clear `--purpose`, and repeatable `--scope` flags when the task needs only a subset of that mode. For example, a synthetic Page-only build needs `workspace:read` and `workspace:write`, not catalog, Data, connection, or run scopes. If the CLI is unavailable, start the equivalent flow with `POST https://app.proformalabs.ai/v1/auth/device` and include `requestedScopes`.
5. Keep `deviceCode` private. Show the person only `verificationUrlComplete` and the matching `userCode`, then wait while they sign in or create an account, choose a Workspace, review the exact scopes and lifetime, and approve or deny access. Never ask for their password, email-verification token, OAuth code, or stored credentials. If they create an account by email, keep the user code visible because Proforma may ask them to enter it again after verification.
6. Let `prfm login` perform its one bounded polling loop. A raw HTTP client must poll `POST https://app.proformalabs.ai/v1/auth/token` no faster than `pollAfterSeconds`, stop at a monotonic deadline derived from `expiresInSeconds`, and write the successful one-time token response directly to protected credential storage. Never start a second authorization flow merely to write a Page, and never print, paste, commit, or place the token in a URL.
7. Verify the effective Workspace, scopes, Model policy, expiry, and `agentApiPermissions` with `GET https://app.proformalabs.ai/v1/session` before reading or writing.

## Build the first useful version

- After approval, build the smallest useful first version before expanding the scope.
- Start from the result the person chose. Load only the relevant context and reuse existing work before creating anything.
- Prefer approved Models over raw Sources for business answers.
- Use only routes and operations advertised by the live v1 and Agent API documents.
- Direct v1 writes support ordinary Workspace Files and complete Page projects. For a Page, run `prfm page validate --from <project.json>` and then `prfm fs put <path> --kind page --from <project.json>` with `--create` or the current ETag in `--if-match`. Use a stable `--idempotency-key` for retryable work. Raw HTTP remains a fallback through the equivalent advertised routes.
- A v1 write cannot create a missing parent folder. Use an existing folder or create the first useful output at the Workspace root.
- Treat connection setup as a secure human handoff. Let the person complete provider consent or secret entry in Proforma; do not collect those credentials in chat or shell output.
- Use operational access only for effects the person requested and approved. Do not start a delegated Proforma Chat unless the session separately grants `chat:run`.
- Return the exact durable evidence available: path, artifact id, revision and revision id, ETag, commit id, idempotency key, committed timestamp, replay status, and every available `resource.links.app` URL.
- Keep evidence claims precise. Static validation proves the package passes commit checks; readback proves persistence; runtime verification proves the Page executed; visual review proves its rendered result was inspected. Do not call one of these states another.
- For synthetic demos, say that no real accounts or data were connected. Also identify controls, suggested fixes, matching rules, activity lists, or other UI state that exists only in the current browser session; do not call session-only state a durable audit trail or an external-system change.

## Boundaries

Proforma does not give this connection raw warehouse credentials, stored Workspace secrets, arbitrary SQL, or unrestricted raw Source rows. Browser-authorized `explore`, `build`, and `operate` access does not include delegated Proforma Chat. Do not imply that an unadvertised Model or Action authoring route exists. Never bypass Model policy, row limits, approvals, scope checks, ETags, or idempotency requirements.