# Dreamstate Docs (llms-full)

## What is Dreamstate

Source: https://www.trydreamstate.com/docs

Dreamstate runs GTM work in one workspace across the web app, Architect, CLI, MCP, and REST.

Lists in workbooks, outreach sequences, the shared inbox, social publishing, AI visibility, CRM records, and the workflows between them run in one workspace. Every job is reachable from the web app with Architect, the dreamstate CLI, and any MCP client, over one API with the same approvals and one credit balance.

Reading these docs with an agent? Start with /llms.txt for the page map, or /llms-full.txt for the complete text.

## The guides, in order

- Your first session: Build a first workbook from workspace context and a sourcing plan.
- Warm network first: Turn post engagement into a worksheet and a sequence.
- Run a 50-lead outbound pilot: Build a worksheet, validate a sequence, and prepare a small outbound pilot.
- Build a founder posting system: Create a social drafting and scheduling system from workspace context.
- Turn replies into meetings: Use Inbox context and CRM records to draft follow-up work.
- Run a visibility sprint: Measure visibility evidence and save useful findings in Context.
- Speed to lead: Build a workflow that connects worksheet, sequence, and trigger work.
- Weekly review: Review runs, sequence activity, worksheets, and credit activity every week.
- Set up cold email infrastructure: Prepare a separate sending domain, two mailboxes, DNS readiness, and warm-up checks before outbound.
- Migrate one Clay table: Import one Clay table, rebuild columns, review ten pilot rows, and compare per-row cost.
- Prioritize identified website visitors: Add identified visitors to CRM context and read a daily ranked contact queue.
- 30-day GTM review: Review monthly spend, campaign results, failed-run causes, and one verdict per live motion.
- Launch a client workspace: Set up client context, review three plays, and quote first paid step.
- Clean up a worksheet: Use worksheet state and provenance to clean up working rows.
- Keep the CRM clean: Maintain saved records and their relationships in the workspace.
- Find out why something failed: Inspect workflow, worksheet, and sequence evidence to diagnose a failed run.
## Where each job lives

| Layer | Pack | Where it is |

| data | tables : Working lists, worksheets, sources, columns, and rows. | Workbooks /dashboard/workbooks |

| data | crm : Saved canonical people, companies, relationships, and deals. | Records /dashboard/records/person |

| knowledge | knowledge : Workspace context, documents, research, and revisions. | Context /dashboard/context |

| knowledge | visibility : AI visibility, attribution, and competitor evidence. | AI Visibility /dashboard/analytics?view=ai-visibility |

| action | sequence : Outreach sequences, cadence steps, and enrollment. | Sequences /dashboard/automations/sequences |

| action | social : Social drafts, schedules, publishing, and performance. | Calendar /dashboard/calendar |

| action | workflow : Automation graphs, triggers, runs, and diagnostics. | Workflows /dashboard/automations/workflows |

| action | unibox : Messages and replies in existing conversations. | Inbox /dashboard/unibox |

| action | tasks : Assigned work, due dates, delegation, and review. | Tasks /dashboard/tasks |

| control | integrations : Third-party connections, credentials, health, and sync. | Settings, Integrations /dashboard/settings?tab=integrations |

| control | senders : Sender identities, mailbox health, and suppression. | Settings, Outreach /dashboard/settings?tab=outreach |

| control | workspace : Members, billing, credits, tags, comments, and webhooks. | Settings /dashboard/settings |

Two things are deliberately not primitives. The doors you drive from, web app, Architect, CLI, MCP, and REST, all use the same thirteen controls. Outside services, including data providers, mailboxes, LinkedIn, and CRMs, connect under Integrations.

## Quickstart

Source: https://www.trydreamstate.com/docs/start/quickstart

Connect through Architect, the CLI, or MCP, then ask Dreamstate for the outcome you want.

Three ways to connect: the web app with Architect, the CLI, or an MCP client. Pick one and start asking for what you want.

All three reach the same workspace and credit balance.

Sign up on the pricing page. Growth is $99/mo with a 3-day free trial. Pro is $249/mo.

## From the web app

Open Architect in the web app and describe a useful first outcome. Start with work that can be inspected in the workspace, rather than a broad request to automate everything at once.
Agent prompt
Read my workspace Context and tell me which pack owns a small first result. Do not make changes until you show me the matching capability contract.Architect can route the job, find its capability, and link saved work back to its screen. Continue with Your first session when you want the Context and worksheet workflow.

## From the CLI

The CLI requires Node.js 22 or later. Install the @trydreamstate/cli package, which provides the dreamstate command.
CLI
npm install -g @trydreamstate/cli
dreamstate logindreamstate login opens browser sign-in. After successful login, it installs every hosted Dreamstate skill for each detected Claude Code, Codex, and Cursor installation. Use dreamstate login --no-skills to skip that installation. On a remote or SSH machine, create a session in the app and run dreamstate login --token <token>. Login still succeeds if no supported agent is detected or skills cannot install, and it prints Run dreamstate skills install to install Dreamstate skills.

Describe what you want, then read the exact contract before any run.
CLI
dreamstate tools search --goal "build a workbook" --toolset tables
dreamstate tools get tables.workbooks.createCLI reference lists every command and option.

## From an MCP client

Point your client at https://mcp.trydreamstate.com/mcp. Use OAuth first, so there is no key to copy. Sign in to Dreamstate and pick a workspace in the client's OAuth flow. A workspace machine key is only for CI and clients without OAuth, sent as Authorization: Bearer ds_live_your_key. Keep machine keys out of prompts and tool inputs.
MCP client configuration
{
"mcpServers": {
"dreamstate": {
"url": "https://mcp.trydreamstate.com/mcp"
}
}
}Start with whoami, then ask for the outcome. Read MCP server for connection and turn flow, or agent clients for supported client setup.

In Claude, open Customize > Connectors > Add custom connector, paste the URL, select Add, then select Connect. A Team or Enterprise Owner adds it from Organization settings > Connectors > Add > Custom > Web. In Advanced settings, select Use Claude's published identity or Register automatically.

In ChatGPT, open chatgpt.com/plugins, select +, then select Add custom MCP server. Enter Dreamstate and the URL, choose OAuth, review the warning, select I understand and want to continue, then select Create as a plugin and sign in. Older Enterprise and Edu workspaces use Settings > Apps > Advanced settings > Developer mode. Open the connection and select Refresh after new tools ship. ChatGPT confirms write actions.
Claude Code
claude mcp add --transport http dreamstate https://mcp.trydreamstate.com/mcpThe in-app CLI and MCP page is at /dashboard/settings/api. It has Claude, ChatGPT, and CLI tabs, each with a Copy first prompt button. Read tools do not need confirmation because MCP tools declare readOnlyHint.

## When it goes wrong

If the connection or workspace is wrong, reconnect and call whoami. If a capability run returns capability_not_fetched, search again, retain that turn's token, fetch the contract, and retry. A mutating run without an explicit mode returns mode_required.

## Your first session

Source: https://www.trydreamstate.com/docs/guides/first-win

Build a first workbook from workspace context and a sourcing plan.

Your first session turns a new workspace into two inspectable things: Context that explains the business and a small, scored worksheet of the right people. It is for a founder or GTM operator who needs evidence that Dreamstate understands the business before they invest in outreach, publishing, or a larger data run. This is the day-one play. It connects Context with workbooks and worksheets, and it ends by recommending a later play rather than starting one.

The first-win skill keeps this session narrow: one accurate business description and one well-read sample beat a tour, a large list, or contact data. Architect reads the named skills, finds the needed tables and knowledge capabilities through the catalog, and follows their result state. The visible outputs are saved Context pages and a worksheet you can open from Workbooks.

## Needs and produces

Begin with the company website and the workspace you intend to use. If more than one workspace is available, establish which one is the target before writing or running anything. The first session can still build Context and the worksheet when a later account connection is missing. That connection only blocks the run or outward action that actually needs it.

The play produces revisioned Context pages, a workbook named for the ideal customer profile, one worksheet with a row source for the scarcest criterion, an evidence column, and a fit score. It also produces a small sample with read rows and score reasons. It does not produce a started sequence, published post, sent email, DM, or contact-data lookup.

Keep the first spend small
The paid portion is the sample, not a full audience. Inspect the estimate and row count before a live run, then read the resulting rows. Contact data comes only after the operator agrees that the sample contains the right people.
## Build the business context first

Architect uses the knowledge skill to inspect the saved business information and determine which core pages are empty or incomplete. When the workspace needs the foundation, it creates or updates Product Information, Ideal Customer, Competitor Analysis, and Tone of Voice from the company website and competitor research, then reads those pages back. Context is the shared knowledge store, so later list qualification, message writing, and social drafts can refer to the same persisted facts.

Ask one question only when two readings of the ideal customer profile would return materially different people. Otherwise, state the interpretation in plain language and build from it. The useful check in the app is not that an update was requested. It is that the Context pages show their saved content and revisions, with the Ideal Customer page ready to ground the sample.
ArchitectRun my first session in this workspace. Confirm the workspace, read the saved Context, and create or update the Product Information, Ideal Customer, Competitor Analysis, and Tone of Voice pages only where evidence supports them. Read the saved pages back, then build one small scored worksheet for the ideal customer profile. Do not start outreach or publish anything.

## Build and read one small worksheet
Architect then loads the list-building skill. It chooses a row source that carries the scarcest qualification criterion, attaches that source to a single worksheet, and exposes the source fields a reviewer needs to see. A list lives in a workbook: one worksheet has one row source, columns enrich and judge its rows, and a score is optional. Nothing searches or previews people outside the worksheet.

The sample begins at ten to twenty rows in the first-win practice. State the row count and estimate, run the sample, wait for the run to finish, and read real rows rather than treating a returned total as proof. Add one evidence column and a fit score, but do not add contact data. The score should explain why a row does or does not fit. When a required answer is missing, it is unknown rather than false.

Review the top five rows with their score reasons in Workbooks. If fewer than half look right, adjust the source filter and run another small sample. Do not compensate by adding more columns to a weak source. A missing account does not prevent worksheet construction, but Architect should identify the account needed before a future provider-backed run.

- 1
### Confirm identity and workspace
Architect confirms the active user and workspace, then uses the knowledge skill to read the saved business facts before using them.
- 2
### Read and save Context
Create only the Context pages supported by research, then read their revisions back. Check the Context screen, especially the Ideal Customer page, before sourcing rows.
- 3
### Attach one source
Use the list-building skill to choose a source for the hardest criterion and attach it to one worksheet. The workbook is the visible boundary for the list.
- 4
### Run a small scored sample
Add one evidence column and a fit score, state the sample size and estimate, then run the sample. Read the rows and score reasons after the run completes.
- 5
### Recommend, do not launch
Use the plays skill to select three plays from the workspace state. Recommend one and name its prerequisites, but do not start it for the user.
## Credits, leading metric, and next play

The leading metric is the proportion of sampled rows that look right when read against the saved ideal customer profile. The completion report names rows landed, rows that fit, top scored examples and reasons, credits charged, the source and filters, and the evidence column and score rule. It also identifies any account still to connect. This turns the result into a decision, rather than a generic onboarding summary.

The plays skill selects a next play from actual workspace conditions. Warm network first fits when LinkedIn is connected. A 50-lead outbound pilot fits when a sender exists. A founder posting system fits when Tone of Voice is strong. The first session should explain why one option matches the state and what it will produce, not automatically run an unrelated motion.

No outward action in this play
A first session does not start a sequence, publish a post, or send email or DMs. Its paid work remains a bounded sample. The readback is what establishes that Context and the worksheet exist.
## When it goes wrong

When the ideal customer profile has two plausible readings that would land different people, ask the narrow business question before sourcing. When the Context page lacks support for a claim, leave the claim out and record the missing evidence instead of filling the page from a similar business. A missing connected account is a prerequisite to record, not a reason to abandon Context or worksheet authoring.

If the sample is weak, change the source filter and resample. If a cell is empty or failed, distinguish the two states, read the column and its upstream inputs, and use Find out why something failed before attempting a larger run. If a run is queued or still working, follow its status and do not report the worksheet as complete from a request or an incomplete count.

If the requested work has already produced a suitable Context page or worksheet, read that result, revise it only where evidence or the operator's request warrants a change, and use the existing object in the report. The goal is a trusted first result, not duplicate workspace objects.

## Warm network first

Source: https://www.trydreamstate.com/docs/guides/post-engagers-to-warm-sequence

Turn post engagement into a worksheet and a sequence.

Warm network first turns a real LinkedIn engagement signal into a scored worksheet and, only for the qualified slice, a capped Sequence. Use it when watched profiles post at least weekly, the ideal customer profile is filled, and one connected LinkedIn account can handle a paced warm motion. It follows workbooks and worksheets and leads into sequences and enrollment without treating a reaction, follow, or comment as permission to contact someone.

The play captures the evidence before it writes a message. Architect uses linkedin-warm-signals to choose one signal, list-building to make the signal inspectable in a worksheet, and outreach to build the sequence. The operator sees source evidence, fit decisions, and the final copy before any delivery state changes.

## Needs and produces

You need a connected LinkedIn account, a saved Ideal Customer page, and a Tone of Voice page or another defensible writing reference. Choose one signal type for the worksheet: engagement with your own posts, profile viewers and new followers, or public engagement with a competitor or peer post. Connected-account material and third-party public research are different sources and should not be mixed in the same worksheet.

The play produces one signal worksheet, evidence of the post or comment that put each person there, an AI fit judgment with a supporting quote, a fit score, and a warm sequence limited to qualified rows. It does not produce outreach to the whole engager table, a second parallel motion to the same audience, or an assertion that engagement itself establishes product fit.

Public engagement is evidence, not consent
Refer only to a captured public signal. Quote the captured comment or leave it out. Never claim to have watched a person, and never use engagement as the reason to enroll every captured row.
## Capture one signal and qualify it

Architect starts with Context and the selected account. It records the signal on the row: which post, what the person said, or the observed engagement event. The worksheet has one row source. If competitor research is also useful, create its own worksheet, then read it separately. This keeps the signal, source boundary, and later qualification understandable in Workbooks.

Add a fit judgment that compares the row with the ideal customer profile and includes the supporting quote, then add a fit score. Exclude the author's team, existing customers, and people already in an open conversation through score conditions rather than hand edits. Contact data belongs after the fit score and should run only for rows that passed the qualification rule.

Run a bounded sample and read individual results in every score band. The leading metric is qualified warm rows with evidence, not the raw number of likes or comments. Capture and qualification may be runtime-priced and capped per cycle, so the run result, not a request, establishes its actual cost.
ArchitectBuild a warm-network worksheet from engagers on this LinkedIn account. Read my Ideal Customer and Tone of Voice first. Keep one signal source, preserve the post or comment evidence on every row, add a supported fit judgment and score, exclude existing customers and open conversations through the qualification rule, then run a bounded sample and read results in each score band.

## Draft, validate, and enroll the qualified slice
The outreach skill reads the worksheet fields that contain the genuine signal before drafting. The first LinkedIn message names that signal in one line, adds one relevant point, and asks a light question. The message must remain grounded in the row. A generic line about finding someone in a search is not personalization, and an invented fact is not a valid substitute for an empty evidence field.

Build a short sequence, no more than three steps for warm people. Preview rendered messages for several real rows, including a thin-evidence row, and correct unresolved variables or weak fallback copy. A LinkedIn connection request is separate from a DM. A DM step sends only after connection acceptance, and every step needs copy that is safe when a row value is empty.

Publishing, enrollment, starting delivery, and a delivered message are separate states. Publish the reviewed sequence, enroll only the frozen qualified slice, and read the result. Starting delivery happens only when the user expressly asks to start. One person uses one sender and one sequence. A reply, decline, or unsubscribe ends their run across channels.

- 1
### Read the audience context
Use linkedin-warm-signals to confirm the account, saved ideal customer profile, and one signal type. The operator checks the selected source and its window before capture.
- 2
### Build evidence in a worksheet
Use list-building to create a single-source signal worksheet with evidence, fit judgment, score, and a gated contact-data stage. Read a bounded sample in Workbooks.
- 3
### Draft warm copy
Use outreach to write from the captured evidence. Preview the sender, recipient rows, and final text, including safe fallbacks, before publishing.
- 4
### Enroll only qualified rows
Publish the sequence and enroll the qualified selection. Check enrolled and excluded counts. Do not confuse enrollment with a started or delivered message.
- 5
### Read the live state
When a start was explicitly requested, read the sequence state and its sender pacing. Report the state proved by the last result and the worksheet and sequence links.
## Credits and leading metric

The play's paid work is capture and qualification, which are bounded per cycle. The catalog describes them as runtime-priced and hard-capped. Publishing is free. Enrollment and start happen only after a cap. Inspect the current estimate before a paid live run and record the charged credits from the finished result. Do not copy a standing credit number into the play.

Track qualified warm rows with an evidence-backed reason, then review reply quality after delivery has started. A raw engager count can grow while fit is poor, so it is not the outcome to optimize. Report the signal, window, rows captured, qualified count, examples of reasons, sender, daily cap, expected pace, and current state: built, enrolled, started, or delivered.

Starting reaches real people
Before a start, show the final copy, sender, qualified audience count, and expected pace. Read the result afterwards. A delayed or capped send is pacing, not proof that the sequence is broken.
## When it goes wrong

If the captured audience is mostly peers, recruiters, vendors, or existing customers, adjust the qualification rule and resample. Do not enroll the whole table to discover fit later. If the row lacks a usable signal, either create a grounded evidence column or use fallback copy that remains truthful on its own. Never invent the missing personal detail.

When the sequence is enrolled but silent, read whether it was started, whether the sender is connected, whether sending hours apply, and whether a cap has been reached. A reply should stop the lead's run. If that state is unclear, read the conversation and sequence before retrying any external action. For an empty or failed worksheet value, diagnose its column and run through Find out why something failed.

Do not route third-party research through a connected account to avoid provider cost. Connected accounts read material they own; third-party profile and competitor-post research stays public research. A capped capture cell or a delayed send identifies pacing, not a reason to run an unbounded retry.

## Run a 50-lead outbound pilot

Source: https://www.trydreamstate.com/docs/guides/outbound-pilot-50

Build a worksheet, validate a sequence, and prepare a small outbound pilot.

Run a 50-lead outbound pilot when you can describe the target titles, segment, and geography in one sentence and want a reviewed, limited motion this week. The play starts with 25 leads and stops at 50, so the team can inspect relevance and draft quality before it considers scale. It connects Context, workbooks, sequences, and Senders without allowing sourcing to start delivery.

Architect uses the list-building skill to make a qualified audience and the outreach skill to create a sequence. The catalog sequence is: confirm the business, preflight a shipped system, install it disabled, source a capped batch, verify and draft, then keep publishing, enrollment, and delivery as distinct later states. The operator sees real rows and rendered messages before any message reaches a person.

## Needs and produces

You need a non-empty company description, offering, and ideal customer profile, plus an available sender for eventual delivery. You also need exclusions such as competitors, customers, and open deals. Do not use this play for cold email from a primary domain without warmup, an undefined customer profile, or an unreviewed scale beyond 50. A missing sender does not block building and validating the sequence, but it does block actual delivery.

The result is 50 qualified rows at most, a previewed three to five step sequence, a clear record of what is drafted, validated, published, enrolled, or started, and the held-back count. It is not an uncapped prospecting campaign. A workbook remains the audience boundary, so enrollment reads qualified worksheet rows rather than creating contacts one at a time.

Pilot scope is deliberately small
The catalog starts the source at 25, not 50. Read this batch before widening. The catalog's current credit posture describes roughly 40 to 75 credits for the first 25 leads and roughly 2 to 3 credits per sourced, verified, and drafted lead for a full 50. Treat those figures as pilot guidance, then use the live estimate and finished run for the actual charge.
## Preflight the system and source the first batch

Architect first reads Context to confirm the company, offering, and ideal customer profile. It then finds a shipped outbound system, preflights it for a 25-lead pilot, and installs the system with automation disabled. Preflight and installation are free in the catalog posture. The tables work begins with a row source that can carry the specific target criteria, not a broad people search that forces expensive cleanup later.

The list-building skill attaches one source to the worksheet, puts every stated title, geography, and other supported criterion into that source, and runs a capped sample. Read the actual landed rows. An apparently successful filter can still return the wrong people, and a count alone does not prove relevance. Add the inexpensive and selective qualification evidence before contact data, then read the score or judgment for every criterion the operator named.
ArchitectRun a 50-lead outbound pilot. Read our Context, offering, ideal customer profile, exclusions, and sender state. Find and preflight the shipped outbound system for 25 leads, install it disabled, source a capped batch in one worksheet, verify the rows and drafts, and show me the qualified rows and rendered sequence copy before any publish, enrollment, or start.

## Validate the audience and message before delivery
Use the outreach skill to write one complete preview for a real qualified prospect. Every sending message should use the worksheet field that explains why this person is relevant: a hiring role, post text, company evidence, or another visible signal. The signal is about the recipient, not the method used to find them. First-name greetings use a first-name field, and every row-field value needs fallback copy that remains real when the evidence is empty.

Validate after every change and preview several rows, including a row with thin evidence. A LinkedIn cold sequence has a connection-request step and a separate DM step, whose body sends only after acceptance. Use the channels the qualified rows can actually receive. A row with a profile and no email supports LinkedIn steps, while email requires a populated email field. Review the final copy, sender, audience count, and pace in the sequence view before moving state forward.

- 1
### Confirm the pilot boundary
Load list-building and outreach, inspect Context and exclusions, then preflight the 25-row system. Check the preflight scope and estimate.
- 2
### Source and qualify 25 rows
Attach one source in a worksheet, run a capped sample, and read the rows. Add evidence and qualification before any contact lookup, then inspect qualified and excluded counts.
- 3
### Draft real-row messages
Write from source evidence and worksheet fields. Preview several rendered messages, including fallbacks, and validate every requested Sequence step.
- 4
### Publish and enroll separately
After review, publish the sequence and enroll a reviewed selection. The app result should show its saved state and the exact enrolled and held-back counts.
- 5
### Start only when asked
A start is a separate action. If explicitly requested, start under the chosen cap and read back the result. Otherwise report the Sequence as published and enrolled, not sent.
## Credits and leading metric

Preflight and install do not spend credits according to the play catalog. The source and verification work can spend under their cap. Record the estimate before each live paid run and the charged credits from its completed result. The catalog calls a trial safe only a live run that stays below an explicit cap. Enrollment does not itself create provider charges, but delivery is still an outward action with a capped sender pace.

Track reviewed qualification rate for the first 25, then the quality of the 50-row set and the reply rate only after a start. Report the source filters, worksheet link, sample size, qualification rate, credits, sequence steps and channels, and the exact state proved by the final read. Do not claim delivery from a draft, publish, or enroll response.

Starting reaches real recipients
Show final copy and recipient scope before starting. One person uses one sender and one sequence. A reply stops that person's run, and the company pause on reply can stop enrolled colleagues from receiving further messages.
## When it goes wrong

If fewer than half of sampled rows match the intended audience, tighten or correct the source input, then rerun a small sample. Do not add layers of enrichment to a weak source. If a column is empty, failed, or waiting on an upstream field, read the column and its run, correct the binding or gate, and continue only the affected rows. Use Find out why something failed for a state that remains unclear.

If a sequence is silent, distinguish draft, validated, published, enrolled, and started. Also inspect sender connection, sending hours, and caps. Never retry an unknown external outcome until the sequence and conversation state have been read. If the sender is missing, finish the draft, preview, and validation, then record the connection needed rather than duplicating the Sequence.

For a published correction, read the saved steps before editing. Change only the requested copy or field binding. Validate again, then read several rendered rows. Do not create a near-duplicate sequence for the same audience. A completed step with a receipt is not run again. A pending state is not a failure and is not zero. A paced or capped state identifies a delivery limit. It does not justify widening the recipient scope. Report the observed state, the bounded repair, and the readback.

## Build a founder posting system

Source: https://www.trydreamstate.com/docs/guides/founder-posting-system

Create a social drafting and scheduling system from workspace context.

Build a founder posting system when the workspace needs a repeatable set of social drafts, rather than one isolated post. It turns saved Context and an account voice into dated LinkedIn or X drafts that an operator can inspect in Calendar. It follows Context and supports social posts and publishing. This play drafts and schedules only. It does not publish a post.

Architect uses the social skill plus the channel skill for every selected channel: linkedin-posts for LinkedIn and x-posts for X. A single post is one draft even when it has several channels or accounts. The app result is a set of saved drafts with their channel payloads and optional planned dates, not a separate weekly-plan object.

## Needs and produces

You need a Tone of Voice page or an existing account brand voice, business context that supports any claims, and a clear topic or audience. A missing connected account does not block drafting. When the account lacks a saved voice, draft from the Tone of Voice page and say so. Before adding a topic, inspect the existing drafts so a revision is used for the same topic rather than a near duplicate.

The play produces two weeks of dated drafts with a call to action, channel-specific copy, and a visible review surface. It can bind more than one named account for a channel, or every connected account when the request explicitly says all accounts. It does not produce a provider delivery receipt, a published post, or a promise that every channel has the same character limit.

Scheduling and publishing are different
Scheduling happens only when asked. Publishing is outward delivery. Read the saved draft or schedule result before reporting it. This play remains at the draft and scheduling stage.
## Ground each draft in Context and channel rules

Read workspace knowledge before writing: the audience, business facts, and tone. Claims about the business need saved workspace evidence or a dated source. A social draft should not invent a customer number, a result, or a named company to make a hook land. For an existing topic, open and revise the saved draft, preserving copy and formatting that were not requested to change.

Read the channel registry before writing. It holds the actual maximum content length for the account. X counts weighted characters, including links, and each thread post must be checked on its own. LinkedIn has a three-thousand-character limit and its final line normally opens with an ask verb or asks the reader a real question. A LinkedIn close that fails that rule is refused with linkedin_cta_required.

LinkedIn's first roughly 210 characters need to earn the feed click with a specific claim, scene, question, or tension and a bridge to the payoff. X needs a strong first five to eight words. Write one core idea per post. Use actual facts, varied sentence length, and line breaks that clarify a turn. Do not add hashtags or emojis unless asked, and resolve every mention before scheduling.
ArchitectBuild a two-week founder posting system from our Context and existing social drafts. Read the Tone of Voice and channel rules for LinkedIn and X before writing. Create or revise one shared draft per idea with channel-specific copy and planned dates. Check each LinkedIn hook and CTA, each X character limit, and every mention. Save drafts for review in Calendar. Do not publish.

## Draft a reviewable calendar
Build the content plan as a set of individual drafts. Each draft can carry several channels and several accounts, with the LinkedIn body, X post or thread, and any other channel payload in that one object. When a request covers LinkedIn and X, do not create parallel drafts with the same idea. Bind only the accounts named by the user, then inspect the saved result in Calendar.

A LinkedIn post uses short paragraphs, specific evidence, and a closing ask that gives something back. An X thread exists only when the idea has sequential beats. Its first post carries the whole promise, the later posts add a distinct point, and the close resolves the opening tension. A one-post idea stays one post. The channel skills prohibit filler phrases and unsupported numbers, so editing tightens an existing draft instead of replacing its voice with generic copy.

- 1
### Read Context and existing drafts
Use social to inspect saved business facts, voice, and draft state. Check Calendar for a same-topic draft before creating another.
- 2
### Load each channel skill
Use linkedin-posts or x-posts for the selected channels. Architect reads the channel registry instead of assuming a length limit.
- 3
### Create one shared draft per idea
Add the named channels and account bindings to one draft. Put each channel's copy in its payload and give the draft a planned date only when scheduling was requested.
- 4
### Review rendered copy
Read hook, CTA, character limit, mentions, and formatting. The operator sees saved drafts in Calendar and can revise an individual channel without rewriting the others.
- 5
### Read back the saved state
Report the draft links, channels, accounts, dates, and what remains: review, schedule, or a separately requested publish action.
## Credits and leading metric

This catalog play uses social draft and schedule work only, never publication. Drafting needs no system review step. A planned date is an optional field on a draft, not a hidden posting action. If a later action involves an external provider or paid operation, inspect its current estimate and execution result rather than inferring a standing cost from the content plan.

The leading metric is a two-week calendar of saved drafts that fit the voice and have a channel-valid hook, clear core idea, and appropriate close. Report drafts created or revised, channel and account bindings, planned dates, unresolved facts, and whether the result is only drafted or also scheduled. Calendar is the visible checkpoint for this play.

## When it goes wrong

If a claim is not in Context or a dated source, omit it and name the missing evidence. If a LinkedIn draft fails with linkedin_cta_required, revise the final line into an ask verb or a question addressed to the reader, then save and read back the draft. If X copy exceeds the account's current limit, cut support or split a genuine sequential idea into numbered posts rather than padding or guessing.

An unresolved mention must be resolved before scheduling. Do not send it to a provider as literal text. When an edit to one channel appears to alter another, read the saved draft, compare every channel payload, restore the unchanged copy if needed, and read again. A missing account blocks publishing, not drafting. Keep the draft and report the connection needed.

If a request says publish, that is a new delivery request outside this play. Show the final channel copy and read the delivery result after it occurs. Do not call a draft published because it has a date, a Calendar entry, or a completed writing task.

Read the current draft before a revision. Preserve its unrequested formatting and channel payloads. Keep the named title or topic intact. Report what the saved result proves. A request is not a delivery receipt. A schedule is not a published post. A publish result needs its own readback. This separation prevents accidental duplicate public content.

## Turn replies into meetings

Source: https://www.trydreamstate.com/docs/guides/reply-to-meeting

Use Inbox context and CRM records to draft follow-up work.

Use this ongoing play when an outbound motion has produced inbound messages that need an answer. It helps a founder or operator work from the existing conversation, classify what the person meant, and draft a useful next step without restarting the original pitch. Read Inbox for the conversation model and CRM records for the durable facts that belong with a person, company, or deal.

The play uses the inbox-replies skill. That skill teaches Architect to treat a reply as part of the same thread, to inspect the full exchange before writing, and to read the thread again after sending. A suitable outcome is a meeting request or another concrete next step, but an unsubscribe, decline, referral, or out-of-office reply has a different correct outcome.

## Needs and produces

Start with a bounded set of unanswered threads, meaning threads whose last message is inbound, for one channel and a defined time window. You also need the conversation's channel and sender account, the person or worksheet row when it exists, and the Context pages needed to support a factual answer. The skill names Product Information as the source for business facts and Tone of Voice as the source for register.

The output is a per-thread decision, not a bulk message. It includes the person, channel, classification, the quoted line that supports that classification, the sequence stop state, a reply draft, and the Context pages used for its claims. When a message is sent, the final result also confirms that it appears in the original conversation and gives the conversation link when available.

This play does not create a new outreach sequence for a person who replied. A new conversation with a person who has never been contacted is a sequence, even when it contains only one message. Existing threads stay in Inbox, while lasting relationship facts may be filed in CRM after the conversation has been understood.

## Read the conversation before drafting

In the Inbox screen, open each selected thread and read every message in both directions. Architect uses the inbox-replies skill with Inbox reads to locate the active conversation and the sequence state. It then reads the person's worksheet row and only the Context pages the answer depends on. This keeps a question about a feature from being answered with a general sales summary or a guessed date.

Classify the latest inbound message from the words and conversation context, not from a keyword. The skill distinguishes interested, question, objection, not now, wrong person, referral, unsubscribe, and out of office. If the thread supports more than one interpretation, keep that uncertainty visible instead of choosing a category merely to move the thread forward.

Before drafting, check whether the lead's sequence run is stopped. A reply ends that person's run on every channel. If the run is still active, stop it before preparing the response. This check prevents a reply from being followed by another step from the earlier cadence while a person is trying to have a direct conversation.
ArchitectReview unanswered email threads from the last seven days for the selected sender account. Read the full conversation, the linked worksheet row, and only the Context pages needed for each answer. Classify the latest inbound message with the deciding quoted line. Check that every replied lead has a stopped sequence run before drafting.

## Draft for the actual reply
Architect applies the inbox-replies skill to the classification, then produces a short reply in the existing thread. For interest, the skill calls for one short paragraph, a concrete next step, and a specific way to book. For a factual question, it answers from Context, cites the page used, and makes one ask. An objection is acknowledged in the person's words, followed by one sourced proof point and one low-effort ask.

A "not now" answer should agree and ask permission to follow up at a stated time. A wrong-person or referral reply should thank the person and ask for, or confirm, the right name. An unsubscribe or decline gets no pitch, only confirmation of suppression. An out-of-office response is evidence about availability, not interest. These choices make the draft match the conversation rather than applying the same meeting request to every thread.

The screen check is specific: before an external action, verify the exact channel, sender account, recipient, conversation, and final copy. Use the visible thread as the source of truth for salutation and context. Do not promise a discount, feature, or date that the relevant Context page does not support. When Context does not contain the needed fact, ask the user instead of filling the gap with a plausible claim.

## Work a bounded slice and preserve the record

- 1
### Select unanswered threads
Ask Architect to use the inbox-replies skill for one channel and time window. In Inbox, confirm that each thread's last message is inbound before treating it as work for this play.
- 2
### Read evidence and stop state
Architect reads the complete thread, the related worksheet row, relevant Context pages, and sequence state. Check the quoted classification evidence and that the reply has ended the lead's run before moving to a draft.
- 3
### Draft by classification
Architect produces the thread-specific response using the inbox-replies practice. In Inbox, compare the copy with the actual message and confirm the recipient, channel, and sender account shown for the conversation.
- 4
### Capture lasting facts carefully
Use CRM only for durable record truth such as a new objection pattern or a competitor named in the thread. Keep the conversation itself in Inbox and link the record work to the evidence rather than treating a draft as a confirmed fact.
- 5
### Read back the sent thread
After an external reply, Architect reads the conversation again. Check that the new message appears in the same thread, then report the confirmed state and link instead of assuming a send response proves delivery.
## Credits and external effects

Inbox reads, classification, and draft preparation are different from the external effect of replying. Search for the Inbox capability needed for the current task, read its delivered schema when necessary, and inspect any estimate before a paid live action. A priced live call returns a quote, then the same call runs under the supplied maximum-credit ceiling. Above the server's row or provider-spend limit the server answers approval_required and the user must say yes first.

Keep the slice small enough that every draft receives a conversation-level review. A bulk archive or tag change must state its count first. The finished conversation readback is what establishes the outcome. It also prevents a second send when a client returned an unclear result or the thread took time to refresh.

Replies reach real people
A reply is an external message. Review the channel, sender account, recipient, conversation, and final copy in Inbox before it is sent. If the outcome is unclear, read the conversation before attempting another send.
## When it goes wrong

If a thread's classification is ambiguous, do not force it into interested or objection. Return the quoted line, explain the uncertainty, and ask the user for the intended interpretation. If a question needs a product, pricing, feature, or timing claim that Context does not support, pause the draft and ask for the fact. That is safer than making an unsupported promise in a conversation that may become a record.

If the sequence is not stopped after an inbound reply, correct the stop state before drafting or sending. Never create a new enrollment to answer the reply, and never reach the same person through another sender or channel after that stop. If a prior send result is unclear, a conversation status alone does not prove delivery. Read the thread and look for the message before retrying, so the person does not receive it twice.

If the thread belongs to the wrong sender account, recipient, or channel, do not move it to a different conversation just to continue a draft. Read the correct thread and repeat the bounded-slice check. For a failing workflow or sequence state that cannot be explained from the thread, continue with Find out why something failed and report the state already proven.

## Leading metric and next play

The leading metric is replies converted into booked meetings. Interpret it alongside the classifications and stop checks, because an unsubscribe or a well-handled "not now" reply is not a failed draft. The immediate proof of this play is a bounded set of threads with their classification evidence, correct stop state, grounded draft, and readback where a reply was sent.

Use Weekly review to compare reply outcomes with runs, sequence analytics, worksheet qualification, and the credit ledger. When the issue is a workbook input rather than a conversation, use Clean up a worksheet before asking a live motion to work around bad source evidence.

## Run a visibility sprint

Source: https://www.trydreamstate.com/docs/guides/visibility-sprint

Measure visibility evidence and save useful findings in Context.

Use this month-one play to understand how a site appears in traditional search and generative answers, then turn measured gaps into saved long-form content. It is for a team with a site and a decision to make about visibility, not a generic request for more traffic. Read AI visibility and analytics for the evidence model and Context for the business facts that a resulting article may claim.

The play combines the visibility skill, which measures and prioritizes evidence, with the writing skill, which creates a grounded brief and saves an article. Visibility does not write content from a metric, and Writing does not repeat ranking research from memory. The result is a baseline, prioritized gaps, two evidence-backed briefs, and one saved article that can be read back.

## Needs and produces

Start with the workspace site, its brand, audience, conversion goal, competitor context, locale, decision, and measurement window. For a performance question, check the Search Console connection before using its data. Preserve the selected property, date range, ingestion time, freshness, and completeness. A missing or expired connection is a typed blocker, not evidence that a page has no performance.

The baseline keeps traditional-search evidence separate from answer-engine evidence. Search evidence is scoped by query, country or language, property, device when known, date window, and source. Answer-engine evidence keeps each prompt's stable id and text, engine, locale, run time, mentions, citations, cited domains, sentiment when available, and source evidence. These records answer different questions and are not combined into one health score.

The sprint produces a report that identifies the site or property, observation window, source freshness and completeness, measured findings, assumptions, prioritized actions, query-set scope, provider coverage, completed versus expected runs, exact denominators, weak prompts, and limitations. It then produces two briefs with target query and intent, evidence line, destination, conversion goal, and content track, plus one article saved to the article surface.

## Establish a baseline before recommending work

In the AI Visibility analytics screen, select the site and exact observation window. Architect uses the visibility skill to inspect existing evidence before any refresh, scan, or probe. For movement claims, it uses the current window and an immediately preceding window of equal length. A missing search row can mean no impressions, incomplete ingestion, property mismatch, or a provider bound. It does not prove rank zero.

Keep clicks, impressions, CTR, average position, query, page, country, device, and dates with the result that returned them. CTR needs its impression denominator, and average position is an impression-weighted observation rather than a fixed rank held all day. A SERP snapshot is one observed result set for a query and locale, while Search Console evidence is property performance over a window.

For answer engines, read the tracked prompt set and per-prompt evidence before creating a new probe. The visibility percentage for one prompt is citations or qualifying mentions divided by eligible completed runs for that prompt, engine set, locale, and window. Preserve citations, completed-run count, and percentage together. Zero citations across zero completed runs is unavailable, not zero percent.
ArchitectRun a visibility sprint for the selected site. Read the current Search Console connection, property, locale, and existing traditional-search evidence for the last 28 days and the prior equal window. Read the tracked prompt set and per-prompt answer-engine results without starting a new probe. Keep source freshness, completeness, denominators, and limitations in the baseline.

## Choose gaps from evidence
Prioritize a gap by likely business impact, effort, confidence, and dependency. A useful recommendation names the evidence, assumption, expected mechanism, leading indicator, and review date. Favor queries whose intent matches the conversion, whose evidence is current, and where a specific page can own the answer. Label volume, implementation cost, and conversion assumptions when they are not measured.

Technical evidence is URL-specific and observed at a time. Discovery, crawl permission, fetch and render, indexability, experience, and search presentation are separate layers. A clean robots file does not prove indexability, a fast page does not prove discoverability, and an llms.txt file does not prove a crawler used it. Preserve the URL, check id, observation time, evidence excerpt or metric, severity, scope, and confidence for each issue.

For a weak answer-engine prompt, connect the opportunity to its cited competitors or domains, missing evidence, and a page-level content gap. Do not infer absence from a failed run, silently average prompt percentages, or attribute a citation to an engine that was not queried. Changing prompt wording, locale, active state, or engine coverage revises the query-set instrument and requires a separate baseline.

## Build briefs and save an article

Hand the selected gaps to the writing skill. A ready brief includes the target query or keyword verbatim with its informational, comparison, or transactional intent; current rank, impressions, clicks, CTR, and date range, or a note that evidence is insufficient; target conversion; classic search, generative answer, or both tracks; known competing URLs; and a new-page or existing-URL destination.

Writing reads workspace Context, relevant evidence, and prior published work before drafting. A business claim needs a workspace-wiki revision, bounded workspace evidence, or dated external source. It preserves provenance, freshness, limitations, and injection warnings in the claim ledger. If a source does not support a requested number or promise, the draft flags insufficient evidence instead of inventing a sentence.

Before creating a new article, Writing checks whether an existing page already owns the thesis. A new title or keyword over the same argument is a revision candidate. For a generative-answer brief, each major claim needs a named specific or concrete statistic with an inline citation. For a classic-search brief, use the target query naturally in the title, first heading, and a subheading, without treating keyword density as a target.

- 1
### Read the bounded baseline
Architect uses visibility to inspect the selected site, evidence window, Search Console status, and tracked prompts. In AI Visibility analytics, check that every reported metric carries its source, time window, and completeness.
- 2
### Choose two specific gaps
Architect ranks measured gaps by impact, effort, confidence, and dependency. Check that each choice points to a page, query, prompt, or technical layer rather than a broad unsupported topic.
- 3
### Prepare two briefs
Architect hands evidence to writing. Check that each brief retains the query, intent, evidence line, destination, conversion goal, track, competitors when observed, and evidence gaps.
- 4
### Ground and save one article
Writing reads Context and existing published work, then saves a complete article and reads it back. Check the returned article state, current revision, and body instead of treating unsaved chat copy as an article.
- 5
### Report the next measurement
Architect returns the saved article, baseline limitations, leading indicator, and review date. Check that the report does not claim a rank or citation improvement before an equal-scope later measurement exists.
## Credits and completion

Existing evidence can be enough for a decision. Do not start a probe merely because a cached timestamp exists. Refreshes, scans, readiness runs, SERP snapshots, and probes can mutate state, spend credits, or run asynchronously, so inspect the exact current contract, scope, and expected cost first. A queued scan is not an audit result, and a probe start is not a new baseline.

For a paid live measurement, use the returned estimate and maximum-credit ceiling. Preserve the batch id after a new probe, then poll its status or the current run ledger without launching another batch. Completion means expected and completed terminal runs reconcile, or the provider reports a bounded or partial terminal state. Read per-prompt results only after that terminal evidence exists.

Measurement can spend credits
A refresh, scan, snapshot, or probe can be a paid or asynchronous operation. Check its current scope and estimate, run within the stated credit ceiling, and wait for terminal evidence before calling it a baseline.
## When it goes wrong

If Search Console is disconnected, expired, or bound to a different property, report that typed limitation and retain the exact site, property, and requested window. Do not estimate performance or treat missing rows as zero. If evidence is stale, read the existing observation first and refresh only when the decision needs newer evidence. If a scan is queued or partially complete, report that state and wait for its terminal read.

If prompt coverage is empty, preserve the empty denominator and say that visibility is unavailable. If a provider-bounded or failed run exists, do not infer that an engine failed to cite the site. Continue pagination when the question needs full coverage. If the prompt set changed, label the comparison as a new baseline or restrict it to unchanged prompts rather than merging incompatible windows.

If Writing lacks a traceable business fact, it should retain the saved draft work and ask for the missing source rather than fill the gap. A stale revision, failed destination, or missing authority also requires an exact read and repair path. For a failed run that the visibility screen cannot explain, continue with Find out why something failed and keep the run identifiers and returned state.

## Leading metric and next play

The leading metric is priority gaps resolved with saved, evidence-grounded content. The near-term proof is a complete baseline, two reviewable briefs, and one saved article with a readback. Rank, traffic, and citation gains are later observations that need an equal-scope comparison; they are not promised by completing this sprint.

Use Build a founder posting system when the evidence establishes themes that should become short-form drafts. Use Weekly review to keep the finished runs, credit ledger, and measurement limitations visible across active work.

## Speed to lead

Source: https://www.trydreamstate.com/docs/guides/speed-to-lead

Build a workflow that connects worksheet, sequence, and trigger work.

Use this month-one play when new worksheet rows need a timely, repeatable next action. It turns a real row source into a small workflow that evaluates new rows and can enroll qualified ones, while keeping authoring, validation, publishing, activation, and delivery as separate facts. Start with Workbooks and worksheets for the trigger data and read Workflows and triggers for the execution model.

The workflows skill is for automation that is not an outreach cadence to people. It teaches Architect to find an existing workflow first, build the smallest graph that meets the stated outcome, and validate after every change. A workflow can be built and checked before an email, Slack, or other connection exists, because a missing connection blocks activation rather than authoring.

## Needs and produces

You need a trigger source, usually a worksheet whose rows represent the subjects of the automation, plus a clear answer to what should happen, what it may change, how often it should run, and when it stops. Before building, Architect frames those facts and searches existing workflows and sequences by the named purpose. If a matching automation exists, change that match instead of creating a duplicate.

The result is a saved workflow graph with its requested trigger, nodes, explicit branch outcomes, and validation result. When the graph is ready, publishing stores the version that will run and activation turns its trigger on. The play produces a workflow that can score new rows and enroll qualified rows, but it does not treat a draft or a successful validation as evidence that any row has been delivered to a destination.

A worksheet trigger remains valid when the worksheet is empty or still filling. Rows can enroll as they land after an active trigger is in place. This lets you check the workflow now while accurately reporting that it is waiting for rows, rather than treating an empty source as an error.

## Frame the job and inspect the workspace

In the Workflows screen, look for an existing automation with the requested name and inspect its current graph before editing. The skill tells Architect to search workflows and sequences first, because a named object might already be an automation. Only when both searches return empty should it consider whether the named thing is a task, record, or worksheet instead.

State the trigger, subjects, effects, cost, exits, and recurrence in plain language. Use a template when one fits the goal, otherwise use the smallest graph that produces the outcome. A request to enroll rows is not missing information: use the workflow whose table trigger is the visible worksheet, or build a draft for that worksheet with appropriate steps and a follow-up task per person by default.

Every node must use its real settings and actual workspace options. Before writing a node, Architect reads the node type settings and relevant choice fields such as channel, worksheet, and account. A value that changes on each run belongs in a runtime input. When a trigger, record, or earlier node should supply that value, Architect lists the graph variables and uses only a listed token instead of inventing variable syntax or saving an empty value.
ArchitectCreate or update the workflow for new qualified rows in this worksheet. First search existing workflows and sequences with the requested purpose. Read the selected worksheet, real node settings, workspace options, and available graph variables. Build the smallest graph with explicit paths for qualified, unqualified, and missing values. Validate after every change, then show the saved graph and activation preview.

## Build and validate the graph
Build the entire graph in one pass when every node is known. When the design needs exploration, add one node at a time and read the saved result before adding the next. For an existing workflow, change only the named node or setting and leave the rest of the graph untouched. Removing a node means removing that node, not recreating a graph that risks dropping an unrelated branch.

Conditions should point at real worksheet columns, and every branch needs an explicit result, including the case where a value is missing. This avoids dead ends and orphan nodes. The requested graph should visibly distinguish a qualified row from a row that lacks evidence, so the workflow does not convert uncertainty into a silent enrollment decision.

Validation happens after each change. A workflow is ready only when validation is clean and the saved graph contains every requested node and path. In the Workflows screen, compare the saved graph with the original outcome statement, then inspect the validation messages rather than assuming a successful save proves the graph can run.

- 1
### Resolve the existing system
Architect uses the workflows skill to search existing workflows and sequences. In Workflows, confirm whether the request is an edit to a live system or a new draft tied to the selected worksheet.
- 2
### Read triggers, settings, and variables
Architect reads the worksheet trigger, node schemas, workspace options, and graph variables before writing. Check that every condition names an actual worksheet column and that changing values are runtime inputs.
- 3
### Save the smallest complete graph
Architect adds the requested nodes and explicit branch outcomes. In the graph view, check qualified, unqualified, and missing-value paths instead of accepting a graph with an unconnected branch.
- 4
### Validate and repair
The workflow skill validates after every change and fixes each real error before validating again. Check the returned validation result and the saved graph together before calling the draft ready.
- 5
### Preview lifecycle state
Architect previews activation and reads the required maximum-credit ceiling from that preview. Check whether the workflow is draft, published, active, running, or finished, because those labels describe different states.
## Publish, activate, and observe

The lifecycle is ordered: build or edit the draft, validate it, fix errors, publish, then activate. Publishing stores the version that will run. Activation turns the trigger on. Enrollment and delivery happen later and need their own result reads. Do not report an active trigger as a completed action on a particular row.

A missing email, Slack, or other connection does not stop you from building, saving, or validating. It does block activation, so name the exact connection still required and leave the checked draft available. An active worksheet trigger snapshots its saved view on periodic ticks and idempotently enrolls rows that land later. A draft, paused, or inactive workflow does not refill from later rows.

Use the activation preview before a live activation. The workflow skill specifies that the activation call needs the params.max_credits value shown by the preview's required_caps.max_credits. Send that value unchanged. It is a ceiling supplied to the call, not a substitute for reading the preview, and it must never be guessed. Live enrollment has no send cap in this workflow lifecycle guidance: every eligible selected row is enrolled.

Activation can change live workflow state
Confirm the validated graph, its trigger, the activation preview, and the maximum-credit ceiling before a live activation. After activation, read the resulting state. A missing connection is a real blocker for this step, even though it did not block the draft.
## Credits and leading metric

The play's leading metric is qualified rows enrolled within minutes. Measure it from a completed run or observed enrollment result, not from the number of nodes in the graph. Reads and validation establish the design; preview establishes the activation scope and required ceiling; live effects establish themselves only through the resulting run and destination state.

Show the cost scope before a priced live action and keep any repair narrow. The activation ceiling comes from the current preview. If the workflow is waiting for rows, record that state rather than spending on a fabricated test subject. If a real row later enters the workflow, follow its run to terminal state and check the expected path in the graph and the destination it reached.

## When it goes wrong

If validation reports an error, read the real setting or variable that caused it, correct that bounded node, and validate again. Do not invent a node id, field name, or variable token to silence a validation failure. If a condition references a missing column, either use the real available column or report that the required data is absent. A clean saved graph is required before the workflow is called ready.

If activation is blocked by a missing connection, keep the validated draft and report the exact connection to add. Do not rebuild the workflow or claim an empty worksheet is the blocker. If the worksheet is empty, an active valid trigger waits for new rows. If an activation result is unclear, read current state before retrying so a trigger or enrollment is not applied twice.

For a failed run, start from the run history and then inspect the trace for the specific node's state, attempt, output, receipt, and error. Retry a failed node only when the effect did not occur. A succeeded node with a receipt must not run again. A timeout, lost connection, or missing receipt is an unknown outcome: check the outside system or trace before retrying. Continue a paused or checkpointed run from its checkpoint instead of restarting it. Use Find out why something failed for that evidence path.

## Next play

Use Weekly review after the workflow has real activity, so you can compare runs, qualification, sequence analytics where relevant, and credits from finished work. If the worksheet used by the trigger has unclear source evidence or a broken score, use Clean up a worksheet before adding more workflow paths.

## Weekly review

Source: https://www.trydreamstate.com/docs/guides/weekly-review

Review runs, sequence activity, worksheets, and credit activity every week.

Use this weekly play when at least one motion is live and you need one evidence-based change, rather than a broad retrospective. It reads completed work across runs, sequences, worksheets, and the credit ledger so an operator can distinguish a process that is waiting from one that is failing. Read Runs for execution evidence and Find out why something failed when one object needs a deeper, bounded investigation.

The diagnostics skill supplies the evidence order, while the plays skill supplies the weekly outcome: qualification rate, reply rate, credits per qualified lead, and one change per motion. A weekly review reads real workspace state first. It does not infer delivery from a requested action, treat an empty list as zero, or retry an external effect before checking whether it happened.

## Needs and produces

You need an active or recently completed motion and a question that can be answered from its records. The review starts with the object a person sees in the app, such as a worksheet, sequence, workflow, or Inbox conversation, and keeps its link. It then follows that object to the owning run, preserving state, attempt, provider, credits charged, structured error, and any receipt returned by the actual run.

The output is a short review per motion: the question, a one or two sentence evidence-backed answer, the object link, run state, and quoted error when one exists. It states the proposed bounded change, whether it spends credits or repeats anything external, and its result if applied. It also reports the leading metrics: qualification rate, reply rate, credits per qualified lead, and one change selected for each motion.

The review is not a permission to re-run a whole campaign. A succeeded step with a receipt is finished. A completed run can be measured, while a queued, paced, capped, unknown, or upstream-waiting item needs its own classification. This distinction keeps the weekly pass from turning normal timing and safety limits into avoidable spend.

## Read the visible object and its run

Open the object in its owning screen before looking at aggregate metrics. A worksheet cell question starts with the cell, its column, and the run that settled it. A sequence question starts with sequence state, enrollment, sender, sending hours, and caps. A workflow question starts with the workflow and its run. A cost question starts with finished runs and charged credits. The minimum evidence that settles the question is better than a dump of every log.

Architect uses the diagnostics skill to classify the result as running, queued, paced by a cap or sending hours, waiting on an upstream column, missing a connection, empty provider answer, failed with an error, or a likely product defect. Pending, queued, paced, capped, and unknown are not failures, and none of them is zero. Quote the state or error that supports the explanation.

Metrics summarize finished runs. They do not repair a run or prove that a particular effect happened. Use a trace for the one run in question when the review needs node-level evidence. The trace is the source for each node's state, attempt, output, receipt, and error. Take identifiers from the object and trace you inspected, never from a remembered name or a guessed identifier.
ArchitectRun a weekly review for active motions. For each worksheet, sequence, workflow, or Inbox motion, open the visible object and read its owning run or trace. Report qualification rate, reply rate, credits per qualified lead, object link, state, attempt, provider, charged credits, and any structured error. Classify waiting, queued, paced, capped, unknown, and failed states separately. Propose one bounded change per motion and read it back if applied.

## Interpret qualification, replies, and cost
Read qualification from the worksheet's actual evidence and score, not from an assumed row count. A column empty on every row can mean its gate reads a column that has not settled, or that it was added after rows landed and never ran on them. A score that appears stuck can be waiting on an evidence column that failed or is still running. A daily cell limit is workspace pacing, not a worksheet defect.

Read reply rate from the sequence and conversation state, not from a delivery request. A sequence that is enrolled but silent may not have started, may lack a connected sender, may be outside sending hours, or may be at a cap. A reply ends the lead's sequence run, so review the stop state as well as the conversation itself. A conversation status is not proof of delivery when a send result is unclear.

Read credits from finished runs and charged-credit records. Higher-than-expected credits can result from a column rerun from the top that billed a sample twice, contact data running before a selective fit gate, or an expensive column placed before a cheaper filter. These are testable explanations. They are not reasons to claim that a cost is wrong without inspecting the responsible runs and row scope.

## Choose one bounded change per motion

A useful weekly review turns one proven issue into one bounded change. It may be a retry of failed rows, a continuation of remaining rows instead of a full column rerun, a named connection to add, a moved gate, or a workflow-node repair. Say whether the change can spend credits or repeat an external effect. Show scope and estimate before a retry that spends credits, then follow it to a final result.

Do not hide a defect by changing providers or writing a manual cell value. Name the defect and retain the object and run identifiers needed to report it. Cancel only a run the user wants stopped, then read its final state. When a play output already exists, skip that step or reorder later work rather than rebuilding it. A play teaches the order of work, but each skill and tool keeps its normal operating rules.

- 1
### Pick one live motion
Ask Architect to apply plays and diagnostics to a named motion. In the owning app screen, confirm the visible object and link before treating an aggregate number as the subject of review.
- 2
### Read evidence in order
Architect reads the object, its owning run, and the specific trace if needed. Check the state, attempt, provider, charged credits, receipt, and structured error, then classify the state rather than calling every delay a failure.
- 3
### Calculate the leading signals
Architect reports qualification from worksheet evidence, reply outcomes from sequence and conversation state, and cost from finished runs. Check that empty, queued, paced, and unknown outcomes have not been converted into zeroes.
- 4
### Propose one narrow repair
Architect identifies the least action that addresses the proven issue. Check its affected rows or node, whether it spends credits or repeats an external effect, and the estimate when a priced run is involved.
- 5
### Read back and schedule the next check
Architect follows any accepted change to final state and returns the result. Check the object again in its owning screen, then record the leading metric and review date rather than declaring success from the request alone.
## Credits and review scope

The review begins with reads, but a repair can have a price. Keep paid work tied to the exact rows, node, or action that failed. Inspect the current capability contract and estimate before a live call, and use the stated maximum-credit ceiling. The completed run, not a preview or a planned change, establishes the charge and final state.

Work through the review one motion at a time. The plays skill says that two plays should not run against the same audience, because the same person could be touched twice. Final external copy is shown before a send, but the weekly review still begins by reading the object and run. The weekly completion report names the chosen play, skill, outputs, missing accounts, credit estimates for paid steps, and the next leading metric.

## When it goes wrong

If a run has succeeded with a receipt, do not run it again. If it failed before any effect, retry the failed node rather than the whole run. If the effect definitely did not apply, retry with the same idempotency identity. An accepted retry is not a finished result: follow it to terminal state before putting it in the next weekly metric.

A timeout, lost connection, or missing receipt means the outcome is unknown. Check the outside system or the trace before retrying. A paused or checkpointed run continues from its checkpoint, not from the beginning. When an external effect cannot safely repeat and its outcome remains unknown, stop and report the evidence already collected. Never retry an email, direct message, or post just because the client did not return a delivery confirmation.

If a sequence is enrolled but silent, inspect start state, sender connection, sending hours, and caps before changing copy or enrollment. If a column is blank, inspect the gate, upstream settlement, and whether the column ran for existing rows before entering values by hand. If the review cannot settle one question from the available object and run evidence, continue with Find out why something failed and report the exact state, link, and quoted error instead of guessing.

## Leading metric and next play

Track qualification rate, reply rate, and credits per qualified lead with the evidence window and finished runs that produced them. The immediate success condition is one real, read-back change per motion, not a blanket assertion that all systems are healthy. Keep the next review focused on whether that specific change altered the measured condition without creating a duplicate effect.

Continue with Keep the CRM clean when relationship records need a weekly evidence pass, or Clean up a worksheet when the review establishes that source, column, score, or provenance structure is blocking qualification.

## Set up cold email infrastructure

Source: https://www.trydreamstate.com/docs/guides/email-infra-setup

Prepare a separate sending domain, two mailboxes, DNS readiness, and warm-up checks before outbound.

Use this day_1 play before cold email when no two warmed mailboxes exist on a separate sending domain. Do not use it for a primary company domain, immediate cold sends, or a purchase without exact approved quote.

## Needs and produces

Needs: separate sending domain, sender name, first-month budget. Prerequisites: real sender name, budget for first domain and mailbox month, and separate sending domain, never primary company domain.

Produces quoted and approved sending domain, two mailboxes, DNS readiness, and warm-up checks before outbound. Leading metric: two mailboxes ready for safe outbound after warm-up.

## Ordered steps

- 1
### Check existing mailbox state
Use senders.mailboxes.list to check for two already warmed mailboxes on separate sending domain.
- 2
### Quote domain and mailbox capacity
Use senders.mailboxes.purchase_domains_suggest to quote look-alike sending domains without buying one. Use senders.mailboxes.purchase_capacity to quote capacity for two mailboxes before purchase.
- 3
### Add approved domain and plan DNS
Use senders.domains.sending.add to add approved separate sending domain only after explicit purchase approval. Use senders.domains.sending.dns_plan to plan SPF, DKIM, and DMARC records, then senders.domains.sending.apply to apply approved DNS plan.
- 4
### Purchase and check mailboxes
Use senders.mailboxes.purchase to purchase approved two mailboxes only after explicit purchase approval. Use senders.domains.sending.readiness_get for DNS and sending readiness, senders.mailboxes.health_get for health and warm-up status, and senders.mailboxes.placement_test for placement before cold email.
## Credits and controls

Inspection, domain suggestions, capacity, DNS planning, readiness, health, and placement checks are quoted or read first. Domain and mailbox purchase spend only after named approval control. infra-purchase controls steps 4 and 7 because adding sending domain and purchasing mailboxes create paid external commitments.

Paid external commitments
Adding sending domain and purchasing mailboxes create paid external commitments.

## Migrate one Clay table

Source: https://www.trydreamstate.com/docs/guides/migrate-from-clay

Import one Clay table, rebuild columns, review ten pilot rows, and compare per-row cost.

Use this week_1 play when moving one Clay people or company table into Dreamstate worksheet. Do not use it for copying Clay formulas or provider settings, or running every rebuilt enrichment before 10-row parity review.

## Needs and produces

Needs Clay CSV export and ICP context. Prerequisites: CSV export of one Clay table, ICP context for rebuilt fit score, and stated maximum credit budget for 10-row pilot.

Produces imported table, rebuilt enrichment columns, 10-row parity review, and per-row cost comparison. Leading metric: ten pilot rows match Clay values before fanout.

## Ordered steps

- 1
### Preview and import
Use tables.clay_migrations.preview to read Clay export and propose rebuild for formulas, AI and research prompts, email waterfall, and HTTP. This is free, writes nothing, and lists manual questions. Create CSV upload, stage Clay CSV rows without making them live, attach CSV source with every Clay header as raw column, and land every imported row in bounded chunks.
- 2
### Create and quote rebuild
Use tables.clay_migrations.apply to create rebuilt columns in dependency order, switched off, with run conditions on inputs. Use tables.table_runs.preview_cost to quote each rebuilt paid column on 10 pilot rows before running.
- 3
### Run, compare, then fan out
Use tables.columns.run on exactly 10 pilot rows. Use tables.clay_migrations.compare to compare rebuilt values with original Clay values and show credits per row beside Clay's. Use tables.columns.run_remaining only after comparison is accepted.
## Credits and controls

CSV mapping and import are free. Rebuilt enrichment, verification, and scoring are priced per row, starting with capped 10-row pilot before fanout.

Credit controls
enrich-pilot controls step 8 because 10-row rebuild can spend credits for enrichment and verification. enrich-fanout controls step 10 because running rebuilt columns beyond reviewed pilot can spend credits per row.

## Prioritize identified website visitors

Source: https://www.trydreamstate.com/docs/guides/website-visitor-outreach

Add identified visitors to CRM context and read a daily ranked contact queue.

Use this ongoing play when RB2B website visits are provisioned as push-only source and visitors need CRM context before outreach. Do not use it for sending automatically, treating every visit as fit, or attempting to run push-only visitor source on demand.

## Needs and produces

Needs provisioned RB2B website-visitor source and ICP context. Prerequisites: RB2B website visitor source provisioned for workspace, ICP context for company-fit scoring, and CRM record definition for promoted visitor records.

Produces visitor companies and people in CRM, company-fit scores, and daily ranked contact queue. Leading metric: qualified identified visitors worked from daily queue.

## Ordered steps

- 1
### Create visitor workspace data
Use tables.workbooks.create to create visitor-intent workbook. Use tables.worksheets.create to create identified visitor worksheet.
- 2
### Attach visitor source
Use tables.table_sources.attach to attach provisioned RB2B website-visits push source. Do not run this push-only source.
- 3
### Score and promote
Use tables.columns.add to add company-fit and daily-rank columns. Use tables.columns.run to score visitor companies for ICP fit under per-row credit cap. Use crm.records.promote to promote qualified visitor people and companies into CRM with visit context.
- 4
### Read daily queue
Use tasks.tasks.list to read daily ranked visitor queue and choose next contacts manually.
## Credits and controls

RB2B bills separately. Source attachment and daily queue are non-sending setup steps. Company-fit scoring and optional enrichment are priced under explicit cap.

Signal and credit controls
signals-arm controls step 3 because attaching provisioned source arms visitor signal flow. crm-enrichment controls step 5 because company-fit scoring can invoke paid enrichment under credit cap.

## 30-day GTM review

Source: https://www.trydreamstate.com/docs/guides/day-30-review

Review monthly spend, campaign results, failed-run causes, and one verdict per live motion.

Use this month_1 play after 30 days of activity to decide whether to scale, change, or stop each live GTM motion. Do not use it for empty workspace with no runs or campaigns in review window.

## Needs and produces

Needs at least one started campaign or run in last 30 days. Prerequisites: at least one run or started campaign in last 30 days, sequence analytics and worksheet evidence, and credit history for same review window.

Produces monthly spend split, campaign results, failed-run causes, and one scale, change, or stop decision per live motion. Leading metric: every live motion has one recorded monthly verdict.

## Ordered steps

- 1
### Read runs and campaign evidence
Use runs.list to read completed and failed runs from last 30 days with causes. Use sequence.sequences.analytics_get to read campaign results and delivery metrics. Use tables.cells.read_page to read qualification and outcome evidence from campaign worksheets.
- 2
### Read monthly spend
Use workspace.usage.history_list to read monthly credit and spend split.
- 3
### Synthesize and record verdicts
Use tables.columns.run to optionally synthesize evidence under explicit credit cap. Use tasks.tasks.review to record one scale, change, or stop decision for each live motion.
## Credits and controls

Run, analytics, worksheet, ledger, and task reads are free. Optional synthesis uses bounded table-column run and must state credit cap before execution.

Controlled actions
synthesis-run controls step 5 because optional AI synthesis can spend credits and must stay inside approved cap. apply-verdicts controls step 6 because recording scale, change, or stop decisions changes shared operating queue.

## Launch a client workspace

Source: https://www.trydreamstate.com/docs/guides/client-workspace-launch

Set up client context, review three plays, and quote first paid step.

Use this day_1 play when agency operator needs separate client workspace before installing client GTM plays. Do not use it for workspace-bound key that cannot create or select another workspace, or paid execution before client approves quote.

## Needs and produces

Needs user able to create and switch workspaces, client website or brief, and client budget. Prerequisites: user session with permission to create and select workspaces, client website or brief with offering, ICP, and exclusions, and client approval authority and budget for first paid step.

Produces client workspace selected, client context installed, three reviewed plays, and first paid step quoted. Leading metric: client workspace ready with first paid step priced.

## Ordered steps

- 1
### Create and select workspace
Use workspace.create to create separate client workspace only after client-launch approval. Use workspace.session.select to select client workspace so later setup is correctly scoped.
- 2
### Establish client context
Use knowledge.context.resolve to read and establish client positioning context from brief and website.
- 3
### Choose, quote, and install plays
Use workspace.blueprints.list to choose three shipped plays appropriate to client motion. Quote selected client play and identify first paid step. Use workspace.apply to install reviewed client systems with automation disabled.
## Credits and controls

Workspace creation, selection, context setup, and blueprint preflight are free. Installation stays disabled. First paid source or column run is quoted before execution.

Shared operating boundary
client-workspace-create controls step 1 because creating client workspace establishes separate shared operating boundary.

## Clean up a worksheet

Source: https://www.trydreamstate.com/docs/guides/clean-up-a-worksheet

Use worksheet state and provenance to clean up working rows.

Use this guide when a worksheet no longer makes its reasoning easy to inspect: it has duplicate answers, columns in the wrong order, stale formatting, or scores that no longer separate useful rows. It is for an operator who already has a workbook and wants to improve it without stripping away the source evidence that makes a row trustworthy. Start in Workbooks and worksheets, then use Find out why something failed when a cell or run needs diagnosis rather than a structural cleanup.

A tidy worksheet reads from left to right as an explanation: identity, derived facts, evidence, score, then contact data. The worksheet-tidy skill treats cleanup as a reversible change first. It reads the live worksheet before changing it, reports the evidence behind each finding, and reads the result again after any change or run.

## Needs and produces

You need an existing workbook, its worksheet, and a clear answer to three questions: what one row represents, which criteria qualify that row, and which column identifies a duplicate. A worksheet has one live row source. If the request needs another kind of search, create another worksheet in the same workbook instead of adding a second source to the current one.

The result is not simply a nicer column list. It is a worksheet whose source, column dependencies, qualification rule, duplicate identity, and uncertain cells can be understood from the screen. The final readback names category findings, reversible edits, destructive options left untouched, credits charged by any rerun, and the link to the worksheet.

Protect source evidence
Do not remove source evidence to make the worksheet look cleaner. Hide a helper column before considering archiving it, add a cleaned column beside a raw value instead of overwriting it, and delete only a target the user explicitly named. A hidden feeder column can still supply a derived column. Archiving that feeder can break its dependents.
## Inspect the worksheet before changing it

Open the worksheet in the Workbooks screen and read its source, every column type, each column's inputs and readers, its score rule, and a page of real rows. Architect uses the worksheet-tidy skill and the tables pack's worksheet and column reads for this inspection. It should classify findings by category and show a few example rows, rather than inferring that a count alone proves the worksheet is sound.

Look for overlapping columns, copy columns that only mirror source fields, and columns ordered before the values they depend on. Check type and formatting problems such as numbers stored as text, inconsistent dates, URLs without a scheme, or mixed casing. Also check helper columns that no one reads, raw payloads that feed a derived answer, score parts that never vary, evidence columns that are unsure on nearly every row, and gates that pass everyone or no one.

Read rows instead of relying on a total. A source run still computing a count does not establish zero rows. Empty and failed cells are separate states, and neither is zero or a false qualification answer. For a clean completion check, read duplicate counts for the identifying field, empty cells in each key column, and at least three complete rows against the stated qualification rule.
ArchitectClean up the worksheet in this workbook. First read its row source, columns, dependencies, score, and a page of real rows. Group duplicate, ordering, formatting, empty-column, and qualification findings with example rows. Do not remove source evidence. Propose reversible fixes first, then read the worksheet back after each change.

## Make the smallest reversible fixes
The normal cleanup sequence is reorder, rename, hide, retype, or add a cleaned column next to the raw one. Read the current column state immediately before changing it. That avoids overwriting another member's newer edit. When the request says to tidy the worksheet, apply the reversible fixes and list archive, delete, and overwrite options separately for the user to name.

Preserve the dependency order. Place identity and profile information first, then derived facts, evidence for each criterion, a score when several criteria need weighing, and contact data last. Each required criterion should have a visible yes or no answer. Missing evidence remains unknown, not a failed criterion. A score is optional and should return a reason as well as a value when the worksheet needs to weigh several evidence columns together.

A column should answer one question. Source-owned facts remain authoritative, while labels and keyword matches are approximate and deserve independent evidence. Do not add a manual copy of a source field merely to expose it. After the source is attached, its projected fields are available as source-managed columns. Manual cell values bypass the evidence trail and should not replace a column run that can settle the cell.

- 1
### Read the source and rows
Use the worksheet-tidy skill to establish what the source returned and which row identity field can expose duplicates. Check real rows in Workbooks before treating a filter or count as evidence.
- 2
### Map each finding to a column
Use the tables pack's column discovery and read capabilities to see current types, bindings, and dependencies. Separate a harmless hidden helper from an archived feeder that would break downstream work.
- 3
### Apply reversible structure edits
Reorder identity, evidence, score, and contact data; rename unclear labels; hide helpers; or add a cleaned value beside the raw field. Keep destructive choices as options rather than applying them.
- 4
### Rerun only the affected work
If a change needs cells settled on existing rows, use the tables pack to preview the affected row count and estimate before a live run. Do not rerun completed sample rows merely to continue the remainder.
- 5
### Read the result in the app
Return to the Workbooks screen. Confirm column order, visible evidence, duplicate identity, required-column completeness, and several complete rows. The readback, not the edit request, proves the cleanup happened.
## Credits and completion checks

Structural reads and edits are different from provider-backed work. Adding a column can be free, while an AI normalization or an external enrichment can spend credits when it runs. A paid cleanup is a new column with its own estimate, not an overwrite of a raw value. Architect should use a small selection first, read the binding preview and its resolved row inputs, then follow the finished run before reporting a charge.

Credits shown before the run finishes are an estimate ceiling, not the amount charged. The finished run is the source for the charge. Use an inexpensive, selective qualification column before contact data so that rows that fail the test do not spend contact credits. If new rows need the same treatment later, use the worksheet's existing auto-run policy rather than rebuilding an equivalent manual field.

A live rerun can spend credits
Before a provider-backed column runs on existing rows, inspect the row count and the estimate. Keep the run limited to the rows affected by the cleanup. The finished run and worksheet readback show what actually changed and what was charged.
## When it goes wrong

An empty column on every existing row usually means it never ran for those rows, or its gate reads a column that has not settled. Do not fill cells by hand. Read the upstream field and column binding, fix the missing input or dependency, and run only the necessary selection. An empty cell is unknown; a failed cell needs its own diagnosis.

A source attachment can return a repair with kind: fix_input and a repair hint. Use that hint to correct the payload, then retry the corrected input before calling the worksheet blocked. A missing connected account can prevent a source from running, but it does not prevent authoring the worksheet or attaching the planned source. Record the connection or binding still needed.

If rows look successful but do not fit the intended person, company, title, or place, treat the source filter as too loose or missing. Tighten one source input or add the missing evidence column, rerun a small sample, and read the landed rows. A daily limit on a cell is the workspace pacing cap, not a worksheet defect. If a result remains empty or wrong after the source and inputs are verified, use Find out why something failed before retrying.

## Next play and leading metric

The leading signal is a worksheet where every required criterion is visible and the operator can state the qualified-row count, duplicate count, missing key-cell count, and the evidence behind three sampled rows. For a workbook model refresher, read Workbooks and worksheets. When the worksheet is clean but a run is still failing, move to Find out why something failed rather than masking the failure with a manual value.

## Keep the CRM clean

Source: https://www.trydreamstate.com/docs/guides/keep-the-crm-clean

Maintain saved records and their relationships in the workspace.

Use this guide for a recurring CRM hygiene pass when people, companies, deals, and their next actions need to remain credible to the whole team. CRM is shared operating memory for customer relationships, not a place to make a database look full. Read CRM records for the record model, and use Find out why something failed when an object or run needs a specific diagnosis instead of a normal hygiene decision.

The crm skill teaches Architect to preserve evidence, identity, and human judgment. It reads the relationship before changing it, then places each confirmed fact in the right kind of record history. A clean CRM makes future action safer because a teammate can see who someone is, what happened, what is next, and why a pipeline stage says what it says.

## Needs and produces

You need a defined record scope, such as recently created records, suspected duplicate pairs, open deals, or records changed since the last pass. Before a change, inspect each candidate's full name, employer, title, verified work email or profile URL, relationship to a company record, current owner, pipeline stage, expected value when applicable, next step, recent timeline activity, source evidence, and open work.

The result is a readback of records reviewed, relationship purpose, pipeline impact, evidence examined, changes made, and why each change belongs in a field, note, or timeline. It reports two leading hygiene measures: suspected duplicate-pair count and open deals with no activity in 21 or more days. Zero is a reported result, not an assumption made because a list was not inspected.

This guide does not turn every thread or worksheet result into a record. A record represents a real relationship entity with identity evidence and a purpose. For conversation-specific work, start in Inbox. For source rows and qualification evidence, start in Workbooks and worksheets and promote only durable, supported facts.

## Read the relationship before changing it

In the Records screen, open the current record and related people, company, timeline, open deals, tasks, and source evidence before proposing an edit. Architect uses the crm skill with CRM reads to search for existing matches by verified email, profile URL, company, name variants, and recent activity. It reads each record again immediately before a mutation because another teammate may have changed it while the pass was in progress.

Separate information by its role. A stable, reusable, queryable fact belongs in a field, such as verified title, lifecycle stage, owner, company domain, explicit qualification, or consent state. A note holds reasoning, uncertainty, meeting detail, and context that is not yet trusted enough for a field. A timeline activity records an event at a time, such as a call, email, meeting, reply, stage change, or completed task. A one-time narrative should not become a permanent field just because it is useful today.

Human-entered values are owned judgment. Do not overwrite one with an enrichment guess. When evidence conflicts, keep both sources and dates visible, identify which field is in conflict, and request resolution when the difference is material. Add a new verified fact only when the available evidence supports it. This lets the CRM retain uncertainty without turning it into a false claim.
ArchitectRun a CRM hygiene pass for records created this week and open deals without activity for 21 days. Read each record, related company and people, timeline, ownership, open work, and source evidence before proposing changes. Identify duplicate candidates using identity evidence, separate field, note, and timeline recommendations, and read every candidate again immediately before any update. Report the duplicate-pair count and stale-deal count.

## Protect identity and provenance
Create a person, company, or deal record deliberately. One record represents one real relationship entity. Link a person to a company only when the evidence supports the connection, and add a source, owner, and next action when they are known. A record without identity evidence or a purpose is a lead-shaped duplicate, not progress.

Merge only when at least two independent signals identify the same entity. The skill gives examples: the same verified work email plus the same profile, the same profile URL plus matching employment, or a confirmed correction from the user. Before any merge, compare the timelines, field provenance, linked records, owner, open work, and deal state. Preserve conflicting claims rather than erasing evidence to make a pair look simpler.

Weak similarity does not establish identity. A shared public email domain, similar company, similar first name, or a guessed enrichment match alone is not enough to combine records. When signals conflict, leave the pair separate and show it for review. That outcome is useful because merging two distinct people or companies can damage both timeline history and the team's future judgment.

## Keep pipeline state true

A pipeline is true when every open deal represents active, evidenced customer work: the right person and company, a credible stage, a clear owner, recent activity, and a concrete next step. Value or a late-stage label does not make an inactive deal healthy. Review the relationship context before changing a stage, then record the evidence and next step that support any stage change.

Stages advance because a customer action or documented qualification meets the workspace's stage definition. They do not advance because time passed, enrichment improved, or a forecast would look better. If the stage criteria are unclear, preserve the current stage and propose the decision that remains. This protects the difference between observed customer work and a desired pipeline outcome.

A weekly pass reads recently created records, suspected duplicates, conflicts or stale evidence, open deals without activity in 21 or more days, deals without a next step or owner, and recently changed stages. Fix low-risk evidence-backed field gaps, then read back sampled records and the two headline counts. The sample establishes that the reported changes match the live records rather than only a prepared list.

- 1
### Bound the review set
Ask Architect to use the crm skill for a specific age, ownership, or pipeline scope. In Records, confirm the count and the records included before treating the set as a hygiene result.
- 2
### Read relationship evidence
Architect reads identity, related records, timeline, source evidence, owner, next step, and open work. Check that each proposed stable fact has evidence and that uncertain reasoning remains a note rather than a field.
- 3
### Resolve only strong duplicates
Architect compares independent identity signals and preserves conflicts. In the record view, check the timelines, linked records, owner, and deal state before any merge decision is made.
- 4
### Repair low-risk gaps
Architect updates supported field gaps and records event history in the timeline. Check that human-entered values were not replaced by an enrichment guess and that a stage change carries customer evidence and a next step.
- 5
### Read back the CRM state
Architect reads changed records and the duplicate-pair and inactive-deal counts. Check the sampled records in Records before reporting the weekly pass complete.
## Credits and scope

The skill says CRM reads, duplicate review, and timeline inspection are free and come before enrichment. Enrichment can have a cost, so keep it separate from routine cleanup. When an enrichment is relevant, state the target records, fields sought, expected coverage, current estimate, and how the result will be reviewed. Do not enrich records merely to fill every blank field.

For paid live work, inspect the delivered capability schema and returned estimate, then run under the stated maximum-credit ceiling. The scope should be a list of named records and fields, not an implied expansion from a duplicate search. Finished results and record readbacks establish what changed and what credits were charged. A proposed result is not proof that a field value is now present.

A merge can hide relationship history
Merging changes the record structure and can combine timelines, fields, and linked work. Use strong identity evidence, inspect both records immediately before the change, and read the resulting record afterward. Leave uncertain pairs separate and report the evidence still needed.
## When it goes wrong

If the checks cannot establish identity or intent, return the findings and ask one narrow question. Do not create a speculative record to make the list look complete, and do not merge on a public domain, similar name, company similarity, or a guessed enrichment result. Record the conflicting signals and leave the pair visible for future review.

If an enrichment result conflicts with a human-entered field, do not overwrite the human judgment. Preserve source and date, name the conflict, and request a resolution for material differences. If a record changed between the initial read and the intended update, read it again and re-evaluate the bounded change. A staged update based on stale record state should not be applied blindly.

If a deal appears inactive, inspect its owner, activity, and next step before downgrading a stage. If the requested work is a failing row, send, or automation run rather than a relationship decision, use Find out why something failed. Keep the record link and any run evidence in the report so the next investigation begins from what the team actually sees.

## Leading metric and next play

Watch the duplicate-pair count and the count of open deals without activity in 21 or more days. Pair those counts with sampled record readbacks, because a decreasing number is meaningful only when identity evidence, ownership, timeline, and next step remain intact. The completed hygiene pass should say what was reviewed, what was changed, what was left separate, and when the next weekly pass should happen.

Use Weekly review to compare CRM hygiene with live motion, qualification, sequence analytics, and credits. Use Turn replies into meetings when a conversation yields durable relationship evidence that belongs in the CRM record.

## Find out why something failed

Source: https://www.trydreamstate.com/docs/guides/find-out-why

Inspect workflow, worksheet, and sequence evidence to diagnose a failed run.

Use this guide when a worksheet cell, Sequence, Workflow, or provider-backed run has an outcome you cannot explain. It is a diagnosis play, not a retry button. The diagnostics skill starts from the object an operator can see, follows it to the owning run, and separates queued, paced, unknown, and genuinely failed states. It connects runs to the relevant worksheet cell, Sequence, or Workflow.

Architect uses diagnostics and the owning pack's reads. It asks one question with the least evidence that settles it, rather than dumping every log or switching providers. The useful result is a plain-language answer backed by an object link, run state, structured error when present, a bounded repair, and a readback of the repair.

## Needs and produces

Start with the specific object: a cell, a column, a source run, a sequence enrollment, a sender, or a workflow graph. Keep its link and identify the question: where did this value come from, which rows failed, why has a sequence not sent, or why did work cost more than expected. Reads establish the evidence before a mutation. Pending, queued, paced, capped, and unknown are not failures and none means zero.

The outcome is a diagnosis that distinguishes state from defect. It names the current run, attempt, provider, charged credits, and structured error when the result supplies them. It also says whether the repair can repeat an external action or spend credits. A good diagnosis never claims a retry is safe merely because the original request returned without an obvious error.

Unknown delivery is not safe to repeat
Never retry an email, DM, or post whose external outcome is unknown. Read the conversation, post, or sequence state first. A duplicate send cannot be repaired by deleting a local record.
## Follow the object to its evidence

Open the object the user sees, then read the owning run. Classify it as running, queued, paced by a cap or sending hours, waiting on an upstream column, blocked by a missing connection, an empty provider answer, failed with an error, or a likely product defect. Quote the state or error that establishes this classification. A run still computing a count cannot establish that count as zero.

For a worksheet value, read the cell, its column, and the run that settled it. A column empty on every row often was added after rows landed and never ran on them, or its gate reads a column that has not settled. A score stuck in place often waits on an evidence column that failed or remains running. Empty and failed cells are different answers. Missing provider data is unknown, not false evidence.

For an outbound issue, read Sequence state, enrollment, sender connection, sending hours, and caps. An enrolled but silent Sequence might not be started. For a cost question, read finished runs and charged credits. A sample run repeated from the top can bill the sample twice, and contact data before a fit gate can spend on rows that never qualified.
ArchitectFind out why this result did not happen. Start from the object I can see, read its owning run and events, classify it as queued, running, paced, missing connection, empty provider result, failed, or defective, and quote the state or error that proves it. Propose the smallest repair, say whether it can spend credits or repeat an external action, apply it only when safe, and read the result back.

## Repair only the failed scope
The repair follows the classification. Continue remaining rows instead of rerunning a completed sample. Retry only failed rows or a failed workflow node. Move a gate when it reads an unsettled input. Connect the named account when the run explicitly needs it. A source attachment can return a repair whose kind is fix_input with a hint. Correct that input and retry the corrected payload before reporting a block.

Do not hide a defect with a manual cell edit or another provider. A manual value bypasses provenance when a column run should settle the value. A daily cell limit is workspace pacing, not a worksheet defect. Cancel a run only when the user wants it stopped, then read its final state. A succeeded step with a receipt should not run again.

- 1
### Name one question
Use diagnostics to state the object and the exact unknown. The operator checks the visible object link before the investigation broadens.
- 2
### Read the owning run
Inspect state, attempt, provider, charge, events, and structured error. Distinguish queued, running, paced, empty, failed, and unknown before choosing a repair.
- 3
### Find the upstream cause
For cells, read column inputs and gates. For Sequences, read enrollment and sender state. For Workflows, read graph validation and the failed node.
- 4
### Apply the narrow repair
Retry failed rows or one node, correct a returned input hint, attach a missing connection, or wait and read a still-running result. State any new credit scope first.
- 5
### Read back and report
Read the repaired object and its final run. Report only what that result proves, including identifiers needed to report a likely defect.
## Credits and leading metric

Diagnosis starts with reads. A repair that reruns a provider-backed source or column can spend credits, so limit it to the failed selection and inspect its estimate. The finished run supplies the charge. Do not infer cost from a queued result or repeat a whole column when only the remaining rows need work.

The leading metric is an answer supported by an object link, state, and a bounded next action. For a worksheet, report duplicate and empty counts separately from failed cells. For a sequence, report draft, validated, published, enrolled, started, or delivered as distinct facts. For a workflow, report the validated graph and current run state rather than treating creation as execution.

## When it goes wrong

If a status read times out, it changed nothing and says nothing about the run. Read again and follow a queued or running run to a terminal result. If a provider answer is empty, preserve that finding rather than substituting a similar row. If an upstream column is unresolved, fix or wait for it before asking a dependent score or gate to decide anything.

When the state points to a product defect, keep the object and run identifiers, the exact quoted error, and the failed scope. Do not run an unbounded workaround. When a sequence has an unknown send result, read the conversation and delivery state before any retry. When no repair is supported by the evidence, report the limitation, what was checked, and the one next read or connection that unblocks the work.

Do not keep reading after the question has an answer. Do not replace a bounded repair with a broad rerun. A run that is still queued may be working normally. A paced run identifies a workspace or sender limit. A missing account identifies a connection dependency. A failed cell identifies a distinct error state. An empty provider answer records an unknown fact. A receipt proves a completed external step. A saved object does not prove its downstream run completed. A user-visible link makes the evidence reviewable. These distinctions keep a diagnostic report actionable. They also prevent repeat charges and duplicate delivery. Preserve the exact state when escalation is necessary. Read the final state after cancellation or repair.

## Web app and deep links

Source: https://www.trydreamstate.com/docs/surfaces/web-app

Use web links in results to open exact Dreamstate objects in the app.

The web app is where you inspect and work with the objects in a Dreamstate workspace. Use it to review Context, rows, drafts, messages, runs, and settings with the people who share the workspace. It is also the practical companion to Architect, because a state-bearing agent result can link back to the exact app object it created or read.

The app does not create a different data model from the CLI, MCP, or REST. Those doors use the same contract and workspace boundary. Start here when you want to see the output, then use What is Dreamstate when you want an agent or script to repeat an inspected workflow.

## Find the screen that owns the work

The sidebar groups each object by the job it owns. Home is the workspace starting point. Inbox is for an existing conversation, while Sequences is for net-new outreach cadence and enrollment. Workbooks contain working row sets and their sourcing or enrichment work. Context contains the knowledge an agent should read before it writes, sources, or plans.

| Sidebar label | Path | Use it for |

| Home | /dashboard/workspace | Workspace home and starting point. |

| Inbox | /dashboard/unibox | All inboxes and My inbox views for existing conversations. |

| Tasks | /dashboard/tasks | Assigned work, queues, due dates, and completion. |

| Calendar | /dashboard/calendar | Social post scheduling and publishing work. |

| Workbooks | /dashboard/workbooks | Workbooks, worksheets, row sources, columns, and cells. |

| Context | /dashboard/context | Revisioned workspace knowledge documents. |

| Sequences | /dashboard/automations/sequences | Outreach sequences, steps, and enrollment state. |

| Workflows | /dashboard/automations/workflows | Automation graphs, triggers, and workflow runs. |

| Settings | /dashboard/settings | Integrations, mailboxes, members, roles, and workspace settings. |

Analytics has Outreach, Social, AI Visibility, and Credits views under the dashboard analytics route. Records use the records route family. Agency workspaces use /agency. The Architect surface opens in an in-app drawer rather than a separate sidebar destination.

## Inspect saved state, not a copy

A state-bearing response can include web_url. That URL points to the exact object in the web app, such as a saved workbook, workflow, draft, or run. The JSON identifier remains the source of truth, but the URL provides a direct handoff from an agent conversation to the screen where a person can read the fields, result, and history.

Use that handoff after any meaningful change. For a workbook, inspect the worksheet's row source, columns, and score. For a workflow, inspect the graph and its run history. For an Inbox action, inspect the existing thread rather than treating outreach and a reply as interchangeable. For a social outcome, inspect the saved draft or calendar record before deciding whether a separate publish action is appropriate.
Architect
Open the saved worksheet from this result and summarize the row source, evidence column, score, and run state.A link is not evidence that the requested work succeeded. Read the status and output on the linked screen. If the row set is empty, the workflow failed, or the saved object is not the intended one, use the run record and error details to correct the input or configuration before moving to a live effect.

## Use the app for shared review

Dreamstate keeps shared workspace work visible. Context documents are revisioned and attributed to the member and client that wrote them. Workbooks put a row source, columns, cell state, and score in one place. Tasks own assigned work, due dates, delegation, saved views, and closing completed assignments. These screens let a team see the durable result of an agent turn instead of relying on a transcript.

Use Settings for workspace-level administration, including members, roles, integrations, reports, mailboxes, do-not-contact rules, outreach settings, playbooks, and workspace settings. Reply playbooks live at /dashboard/settings/playbooks. A provider connection or mailbox can block a send or a provider-backed run, but it does not block drafting a sequence, building a workbook, or saving other work.

Treat these UI labels as the ownership map. A saved CRM record belongs in Records, while a working sourcing list belongs in Workbooks. A reply belongs in Inbox, while a cadence belongs in Sequences. Choosing the correct screen makes it easier to check the correct state and avoids applying a change to a nearby but different object.

Use Calendar for social scheduling, and use Analytics for the reports that describe outreach, social, AI visibility, or credits. These views expose the workspace result after the object has been created. They do not replace the object-specific screen when you need to inspect a row, a draft, a sender policy, or a run event.

## When it goes wrong

If an agent cannot find a capability, have it search for the outcome and retrieve the returned contract. A run can fail with capability_not_fetched when the exact contract was not delivered in the current turn. It can fail with mode_required when a mutating request omits its mode. These are contract failures, not instructions to repeat a guessed request.

Use dry run when you need validation against the real workspace without business writes, provider spend, or outward action. A live paid call can return quote_required; inspect its estimate and rerun unchanged parameters with a max_credits ceiling. When a connected account is missing, save the build work, name the connection that is needed, and connect it before the affected step.

If a run has already started, inspect it through Runs before retrying. The run record, events, result state, and any receipt show what Dreamstate recorded. Do not assume that a cancellation removed an external effect. Check the saved object and returned state, then decide whether a corrective action is needed.

When a response includes a repair, follow the repair's stated next action. It can point to a missing schema, a legal field, an expected input shape, or a retry condition. That is more reliable than copying an earlier request into the app, because contracts and workspace state can differ between otherwise similar jobs.

Preserve the error code and trace information when you ask a teammate or Architect to diagnose the result.

## Architect

Source: https://www.trydreamstate.com/docs/surfaces/architect

Architect works in the app with packs, skills, and the same controls used by other surfaces.

Architect is the in-app agent for planning and carrying out workspace work. Use it when the request is easier to express as an outcome than as a capability identifier, such as building a worksheet sample, reviewing Context, or diagnosing a run. It works against the same contract as the CLI, MCP, and REST, then directs you to the saved object in the web app when a result has state.

Architect opens in an in-app drawer. It can keep a long turn connected and stream progress while it works. Use the visible plan and the returned output to follow the work, then inspect the linked workbook, run, workflow, or draft before asking for a new live effect.

## Ask for the outcome and constraints

A good request names the desired workspace result, the relevant business context, and any boundary that matters. For example, ask for a small scored worksheet sample rather than a generic people search. Lists only exist in a workbook, so the agent can create or use a workbook, attach one row source to a worksheet, and add columns that provide evidence or scoring.

Tell Architect what should not happen in the same request. A first session can build Context and a worksheet sample without sending, enrolling, publishing, or looking up contact data. A missing sender or LinkedIn account does not block that building work; it blocks the later step that needs the connection.
Architect
Confirm this workspace, read Context, create a small worksheet sample for our ideal customer, and do not send, enroll, publish, or look up contact data.Use the app's Context screen to review facts before the agent treats them as a premise. Context is revisioned Markdown knowledge attributed to the member and client that wrote it. This is the place to keep product, ideal-customer, competitor, and tone facts that a sourcing or writing task needs.

Ask one clarifying question only when two reasonable readings would produce different saved work. Otherwise, prefer a small first result that you can inspect. This keeps discovery concrete and gives the next prompt a workspace object, source, result, or error to refer to.

## Architect routes, searches, and checks contracts

Architect first identifies the pack that owns the job, then may load a skill that teaches the practice. A pack routes work and defines its boundary. A skill teaches an operating method, but neither a pack nor a skill grants authority. The exact capability contract controls the inputs, execution mode, cost policy, and scopes.

It uses the thirteen shared controls: identity, packs, skills, tool search, exact tool lookup, execution, and run inspection or cancellation. Search returns a turn token and matching runnable contracts. If a matching contract was already fetched, it can be run in that turn; otherwise Architect retrieves the exact contract before execution.

This is why a vague job can still become a precise action. It also prevents an earlier identifier from being treated as valid for a new request. The server returns capability_not_fetched if the contract was not delivered in the current turn, with repair information that tells the caller to search or get the schema.

## Follow the plan and progress

Architect shows its plan as a checklist while it works. The checklist control is named plan_update inside Architect only. It is not part of the thirteen shared controls, so it does not add an extra CLI, MCP, or REST endpoint. Treat it as a visible progress aid rather than a separate execution authority.

Check each saved object after the relevant step. For a worksheet, inspect the source filters, evidence column, score rule, sample rows, and their reasons. If fewer than half of a first sample look right, change the source filter and run another small sample rather than adding more columns. For an asynchronous operation, inspect the run, its events, state, and receipt before you ask for a retry or cancellation.
Architect
Show the checklist, the saved worksheet, its sample rows, and the run result. If the sample is wrong, adjust only the source filter and validate another small sample.State-bearing responses can include web_url. Follow it to the exact object in the web app, while retaining the JSON id as the source of truth. The link lets you review the same workspace result with a teammate instead of re-creating a copy from the conversation.

A completed checklist is not the final check. Read back what was created or changed and use a preview, test, or run output where it is available. Report the concrete result and any remaining blocker rather than only reporting that a capability call was made.

## When it goes wrong

Mutating work must name a mode. Architect uses smoke_test for static schema and policy inspection, dry_run for validation against workspace state without business writes, provider spend, or outward action, and live to execute. A missing mode returns mode_required, so state the desired validation or live outcome rather than assuming the agent will choose one.

A live paid operation can return quote_required with an estimate. Architect can rerun the unchanged parameters with a max_credits ceiling. Within the server's row and provider-spend limit that ceiling is the only gate. Above it, or for a recurring trigger, the server answersapproval_required and the person approves on the proposal card in the app; Architect never sets approved. MCP and CLI callers send approved: trueonly after the user says yes. Use dry run when you need a real-state check without an outward effect.

Check sensitive and irreversible outcomes
Read the estimate and inspect the prepared result before a live request can spend credits or reach a real person. Owner actions for members, money, keys, and credentials follow separate signed-in security rules.
Preserve the error code, message, repair, and trace details in a follow-up request. Ask Architect to inspect the failed run or the missing condition, correct the specific input, and verify the saved result. See Runs for run inspection and Owner actions for the security exception.

Do not try to compensate for an error by switching to another door. Architect, CLI, MCP, and REST share the same contract, workspace boundary, and capability rules. A repair found in Architect therefore describes the same missing schema, mode, or quote condition that a script would need to fix.

Keep the prompt attached to the workspace object you inspected. That gives the next turn a clear subject.

Open the saved object before you continue.

## CLI

Source: https://www.trydreamstate.com/docs/surfaces/cli

Use the dreamstate CLI to authenticate, select workspaces, and discover capabilities.

The Dreamstate CLI is the dreamstate binary from the @trydreamstate/cli package. Use it when terminal work needs the same workspace identity, pack routing, skill discovery, capability contracts, and run records available in Architect and the MCP server. It is a client of the shared contract, not a separate catalog of terminal-only actions.

The normal terminal flow is identity, discovery, contract read, then execution. This keeps a script or agent from constructing a request from a remembered identifier. For every available subcommand and flag, use CLI reference. For the protocol fields behind the capability controls, see MCP reference.

## Sign in and choose a workspace

Install Node.js 22 or newer, then install @trydreamstate/cli and run dreamstate login. The CLI opens browser sign-in. For an SSH or remote machine, create a session in the app and run dreamstate login --token <token>.

Successful login installs every hosted Dreamstate skill for each detected Claude Code, Codex, and Cursor installation. Use dreamstate login --no-skills to skip that installation. If no supported agent is detected, or skill installation fails, login still succeeds and prints Run dreamstate skills install to install Dreamstate skills.
ArchitectCLIMCP
Tell me which workspace I am operating in, then route my request to the right pack before we make any changes.A workspace belongs to a particular actor and has its own scopes and spend policy. Selecting a workspace makes later terminal requests explicit rather than accidental. If the identity output does not match the intended workspace, stop before discovery. Logging out deletes the stored credentials file, which is useful on a shared or temporary machine after terminal work is complete.

## Discover the work before running it

Packs route a goal to a domain such as tables, knowledge, workflow, or workspace. They are metadata, not authority. Start with packs list to see pack definitions, packs get for one exact pack, or packs route --goal for a plain-language outcome. A pack scope on tool search narrows discovery, but it does not make a result runnable without its contract.

Skills teach an agent or operator how to approach the work. The CLI lists skills with an optional query and numeric limit, reads a skill by identifier, searches skill text, installs selected skill files, and runs a doctor check for local installations. A skill may guide a workbook-building task, but the capability catalog remains the authority for the callable input, output, mode, cost policy, and effect policy.
ArchitectCLIMCP
Route a workbook-building goal, show the matching skill, then search the catalog for the actual capability contract.Tool search requires a goal, query terms, or JSON query fields. It can accept terms, a numeric limit, and a toolset pack. The response can include tool_turn_token and contracts already marked runnable. Preserve that token for the current turn. For a search result whose contract was not returned, call dreamstate tools get with the exact capability id before a run.

## Run and inspect work

The CLI separates search, get, and run because a capability's exact schema is selected at runtime. tools get returns the contract to verify before creating a request. tools run takes either --params for a parameter object or --json for the complete request. The parser refuses attempts to supply both forms together.

A mutating execution must name a mode: smoke_test, dry_run, or live. The server owns the mode refusal, so the CLI lets a request through and the service can return its structured repair. The CLI validates conflicting mode flags locally. Its default run wait is 120 seconds, while --no-wait returns the immediate response and --wait-timeout selects a non-negative wait length.
ArchitectCLIMCP
Find the capability for a workbook named Trial accounts, inspect its exact contract, run a dry run, and show the run result.The command supports JSON output where the usage text says --json-output or --json. Use structured output in an automation that must carry a run identifier to a later command. Run commands list records, get one record, stream or page events, and cancel. A state version protects a cancellation from acting on a run that changed after it was read. Generic run resume is retired. A table run checkpoint uses dreamstate tools run tables.table_runs.resume.

Quoted work and outward effects

A live request that needs a price can return a quote. Review the estimate, retain the same request parameters, and set --max-credits and --quote-hash when repeating it. Pass --approval-id when a recorded approval already exists. A capability contract, not the command name, tells you whether the work can spend credits or reach an external recipient.

## Install skills and import a worksheet file

Login installs skills automatically for detected Claude Code, Codex, and Cursor agents. To install them later or for chosen agents, run dreamstate skills install --agents claude-code codex cursor --skill '*'. The onboarding skill installs as dreamstate-first-win, with skill id first-win.

The CLI also imports a local worksheet file with tables import. It requires a worksheet identifier and a file path. It accepts csv, json, jsonl, or xlsx as an explicit format, although an omitted format is derived from the file. Preview, upsert key, row kind, and keep-unmapped-columns are optional controls. This command is specific to importing a file, so use catalog search for other workbook actions.
ArchitectCLIMCP
Inspect the local skill installation for Codex and Cursor. Then show me the contract for importing trial accounts into a worksheet.Use the CLI reference before scripting specialized sequence or workflow verbs. Those command groups pass a verb, arguments, and flags through to their domain operation, so their exact accepted fields vary. The shared discovery flow still applies to ordinary catalog capabilities and remains the safest way to learn a current schema.

## When it goes wrong

If sign-in or discovery fails, check the selected identity with dreamstate whoami. Machine keys are only for CI and clients without OAuth. Do not add a machine key to shell history, a prompt, or checked-in configuration. Use logout to remove stored CLI credentials when a machine should no longer retain them.

If search fails, provide --goal, --terms, or a JSON query containing a goal or query terms. If a run returns capability_not_fetched, search again in the current turn and get the missing contract before retrying. If it returns mode_required, add exactly one mode flag or mode field. If it returns quote_required, use the returned quote with unchanged parameters and a credit ceiling.

If the parser reports a usage error, read the usage shown by the command rather than adding guessed flags. Numeric skill limits must be non-negative integers. The importer rejects an unsupported format, and a tool run rejects both --params and --json together. For a stale cancellation, read the run again, take its current state version, then retry the cancellation.

## CLI reference

Source: https://www.trydreamstate.com/docs/surfaces/cli-reference

Review Dreamstate CLI commands and their documented syntax.

The dreamstate CLI is the terminal door to Dreamstate. Use it when an agent or an operator needs the same packs, skills, capability contracts, and runs available in Architect and MCP.

Start with discovery before a run: identify the workspace, search for a capability, read its contract, and then supply the required mode. For the shared controls, see MCP reference; this page covers the command syntax implemented by the CLI.

## Session and workspace
CLI
dreamstate --help
dreamstate --version
npm install -g @trydreamstate/cli
dreamstate login
dreamstate login [--profile <name>] --token <ds_user_...|ds_live_...>
dreamstate login --no-skills
dreamstate logout
dreamstate install [--agents <claude codex grok>]
dreamstate status
dreamstate profiles <list|use|current|remove|env> [name]
dreamstate whoami
dreamstate credits
dreamstate auth login [--api-key-file <path>] [--no-skills]
dreamstate auth whoami
dreamstate workspaces list
dreamstate workspaces use <id|slug>Node.js 22 or newer is required. Run login for browser sign-in, or create a session in the app and pass its token to the same command on a remote or SSH machine. Successful login installs every hosted Dreamstate skill for each detected Claude Code, Codex, and Cursor installation. Use login --no-skills to skip skill installation. If no supported agent is detected or installation fails, login still succeeds and prints Run dreamstate skills install to install Dreamstate skills. logout deletes the stored credentials file. whoami shows the authenticated identity, and credits prints workspace usage and remaining credits, while workspaces list lists workspaces available to it and workspaces use selects one by identifier or slug. Use identity commands before discovery when a shell session could point at more than one workspace.

| Command | Arguments | Meaning |

| login | Optional --token or --no-skills | Starts browser sign-in, accepts a session token, and installs skills unless skipped. |

| logout | None | Clears the CLI session. |

| whoami | None | Shows the authenticated identity. |

| credits | None | Shows workspace usage and remaining credits. |

| workspaces list | None | Lists workspaces available to the identity. |

| workspaces use | ID or slug | Selects a workspace for later commands. |

| status | None | Prints cli_version, server_version, release_sha, minimum_cli_version and skew. Exits 8 when this CLI is below the server minimum. |

| install | Optional --agents claude, codex, grok | Installs the Dreamstate plugin (skills plus the hosted MCP server) for the named agents. |

| profiles | list, use, current, remove, or env, plus an optional name | Lists, selects, prints, removes, or prints env for a local credential profile. |

| auth login | Optional --api-key-file and --no-skills | Stores a key from a file. whoami and auth whoami both show the authenticated identity. |

## Packs and skills

Packs help route a goal to an area of work. Skills give the agent operating guidance, and can be searched, inspected, installed, or checked from the CLI.
CLI
dreamstate packs list
dreamstate packs get <pack_id>
dreamstate packs route --goal <text>
dreamstate skills list [--query <query>] [--limit <n>]
dreamstate skills get <skill_id> [--file <path>]
dreamstate skills search <query> [--limit <n>]
dreamstate skills install [--skill <skill_id|*>] [--agents <codex claude-code cursor>] [--project] [--copy]
dreamstate skills doctor [--agents <codex claude-code cursor>] [--project]
dreamstate commands search <term>packs list and packs get read pack metadata. packs route --goal accepts a plain-language goal and returns the relevant domain route. A pack is not an authority grant. It guides discovery, while the selected capability contract still defines the accepted parameters, execution mode, cost policy, and effect policy. The --json-output flag is available on the pack commands shown in the CLI usage text.

skills list accepts an optional query and non-negative integer limit. skills get requires the skill id and can select a supporting file with --file. skills search treats the remaining positionals as the search phrase and also accepts a numeric limit. These reads help an agent learn the practice for a task, but they do not create a workspace object or make a capability executable.

skills install defaults its skill selection to * when --skill is absent. Its accepted agent values are codex, claude-code, and cursor. The parser accepts repeated, comma-separated, or space-separated agent values and refuses a value outside that list. --project and --copy change installation behavior. skills doctor checks the selected agent installation and accepts the same agent and project options.

Login installs hosted skills automatically for detected Claude Code, Codex, and Cursor agents. To install them later, run dreamstate skills install --agents claude-code codex cursor --skill '*'. The onboarding skill installs as dreamstate-first-win, with skill id first-win.

## Tools and runs

Tool discovery returns candidates. tools get returns the exact input contract, which is the contract to check before composing a run. Runs are the durable record for work that continues or needs inspection.
CLI
dreamstate tools search --goal <goal> [--terms <csv>] [--limit <n>] [--toolset <pack_id>]
dreamstate tools get <capability_id>
dreamstate tools run <capability_id> [--params <object>|--json <body>] [--turn-token <token>] (--live | --dry-run | --mode <smoke_test|dry_run|live>) [--approved] [--approval-id <uuid>] [--approved-effect-unknown] [--max-credits <n>] [--max-live-sends <n>] [--quote-hash <sha256:...>] [--idempotency-key <key>] [--wait-timeout <seconds>] [--no-wait] [--open]
dreamstate runs list [--limit <n>] [--cursor <cursor>] [--json <query>]
dreamstate runs get <run_id>
dreamstate runs status <run_id>
dreamstate runs wait <run_id> [--wait-timeout <seconds>]
dreamstate runs events <run_id>
dreamstate runs cancel <run_id> [--state-version <n>] [--reason <text>] [--json <body>] [--idempotency-key <key>]The search parser requires --goal, --terms, or a JSON query containing a goal or query terms. --terms is parsed as comma-separated values, trims every value, removes duplicates, and rejects an empty resulting list. --limit is parsed as a non-negative integer before the request is sent. --toolset is forwarded as the discovery scope field, which narrows a search but does not change the installed CLI commands or the MCP roster.

tools get requires one capability identifier after the command. The CLI passes that identifier to the tool route, whose returned contract is the authoritative place to learn parameter names, output shape, available modes, and policy. A script should not derive a body from a suffix such as create or run, because the schema is resolved from the active catalog and workspace rather than from the CLI grammar.

tools run accepts exactly one parameter form. Use --params for the capability parameter object, or use --json for a complete request body. The parser rejects both flags together. If the JSON body already contains an execution-envelope field such as params, mode, agent_session_id, approved_effect_unknown, or max_credits, it is treated as the complete request. Otherwise, the object is placed under params.

The mode switches are mutually exclusive. --live, --dry-run, and --mode can select a mode, but more than one selected value produces a CLI usage error. --mode accepts only smoke_test, dry_run, or live. The server, rather than the parser, returns mode_required for a mutation with no mode so its structured repair stays identical across terminal, MCP, REST, and Architect calls.

Use --turn-token to send the token returned by discovery, --max-credits for a non-negative execution ceiling, and --idempotency-key for a replay-safe request. --approved is sent only with --live. --approval-id must be the uuid of a recorded approval. A bad value throws --approval-id must be the uuid of a recorded approval. --quote-hash must be the sha256: plus 64 hex quote a dry run returned. A bad value throws --quote-hash must be the sha256:<64 hex> quote_hash a dry run returned. --approved-effect-unknown forwards the literal approved_effect_unknown: true. tools run --max-live-sends <n> maps to params.max_live_sends (integer >= 1), never a top-level run field. A top-level max_live_sends throws max_live_sends is a capability parameter. Put it in params.max_live_sends or pass --max-live-sends. Use this flag only when the fetched capability schema declares it, such as a one-contact workflow run. Sequence lifecycle and enrollment calls do not accept it and have no lifetime send ceiling. A live external send above the paid-run row threshold needs --approved, a matching --quote-hash, and, when declared by that capability, params.max_live_sends at least the recipient count. The server error code is live_sends_require_approval. The CLI waits for a terminal run status by default for 120 seconds. --no-wait returns immediately, and --wait-timeout accepts a non-negative numeric override. On timeout, the CLI prints the latest run envelope rather than fabricating a terminal result.

## Specialized commands

The CLI also exposes dedicated sequence, workflow, knowledge, unibox, and worksheet import commands. Their subcommands are passed through as verbs and flags; check their command help before using a write action.
CLI
dreamstate sequences <verb> [args] [flags]
dreamstate workflows <verb> [args] [flags]
dreamstate knowledge <verb> [args] [flags]
dreamstate unibox <verb> [args] [flags]
dreamstate tables import --table-id <uuid> --file <path> [--format <csv|json|jsonl|xlsx>] [--preview] [--upsert-key <header>] [--row-kind <person|company>] [--keep-unmapped-columns <true|false>]
| Import flag | Required | Meaning | Default |

| --table-id | Required | Worksheet identifier that receives the import. | None |

| --file | Required | Path to the local import file. | None |

| --format | Optional | One of csv, json, jsonl, or xlsx. | Inferred when omitted |

| --preview | Optional | Previews the import. | Off |

| --upsert-key | Optional | Header used to match existing rows. | None |

| --row-kind | Optional | person or company. Anything else is a usage error. | None |

| --keep-unmapped-columns | Optional | true or false. false is forwarded as keepUnmappedColumns false. | Omitted |
The sequences, workflows, knowledge, and unibox command groups take a domain verb followed by arguments and flags. The top-level help does not define a universal argument list for those verbs, so use each command's help and the discovered contract before using a write. This keeps a terminal script aligned with the domain operation instead of assuming the worksheet-import grammar applies to a sequence, a workflow, a knowledge verb, or a unibox verb.

knowledge verbs call customer knowledge capabilities. Graph verbs cover nodes (create, get, update, archive, restore, delete) and relations (create, get, update, archive, delete), plus edges-list, search, traverse, export, and contract-get. compose-document calls knowledge.brain.knowledge.compose_document. A positional id maps to node_id or relation_id. unibox verbs call customer inbox capabilities: list, get, messages, status, snooze, unsnooze, triage, drafts, draft-edit, draft-approve, labels, analytics, analyze, resync, sync-status, and comment threads. Both groups take the same run flags as tools run, require an authenticated session, and read remote fields from tools get for that capability.

The importer requires both --table-id and --file. Its table id is the worksheet receiving the data, and file is the local source path. --format is an override rather than a requirement: csv, json, jsonl, and xlsx are the only accepted values, while an omitted format is not forwarded and is derived from the local file. An unsupported format produces a CLI usage error before an import request is made.

--preview is a boolean import control, as is the global JSON-output option. --background was removed in 1.3.3: dreamstate tables import always runs to completion in this process. Run the same command without it. --upsert-key is a trimmed header name used to match existing rows. When it is empty after trimming, the CLI does not forward it. --row-kind accepts only person or company. --keep-unmapped-columns accepts only true or false. Importing a file is a specialized operation. Use the tables pack and tool search when you need a different workbook action, a current capability contract, or a clear execution mode.

Run commands are kept separate from capability commands because they operate on an existing durable run. runs list accepts --limit (integer 1 to 500), --cursor, and a JSON query object. runs get and runs events require a run id. runs resume was retired: the server has no generic run resume. A table run checkpoint resumes with: dreamstate tools run tables.table_runs.resume --params '{...}' --live. Start a new run for anything else. runs cancel accepts either a JSON body or the state-version and reason flags, never both. The state version is parsed as a non-negative integer.

A run cancellation may need its current state version even when the operator already has a run id. The CLI can read it from a run response when possible, but it refuses to invent zero if the run response does not contain a safe integer state version. In that situation, pass --state-version explicitly after reading the current run. The server can then detect whether another worker changed the run before the cancellation request arrived.

## MCP server

Source: https://www.trydreamstate.com/docs/surfaces/mcp

Connect an MCP client to Dreamstate and use the canonical controls.

The Dreamstate MCP server gives an MCP-capable agent the same thirteen shared controls as Architect, the CLI, and the REST API. Use it when an agent client needs to work with a Dreamstate workspace through a small, stable control surface. It does not expose a separate roster for each pack, and it does not let an agent run a guessed capability name.

Connect the client, identify the workspace, route or search the work, read the current contract, and then run it in an explicit mode. This page explains the operating flow. MCP reference lists every control and its exact input fields, while Agent clients covers Claude Code, Codex, Cursor, and skill installation.

## Connect and identify the workspace

The hosted server URL is https://mcp.trydreamstate.com/mcp. OAuth is the first authentication choice, so no key is needed. Use a workspace machine key only for CI or a client without OAuth. The credential and principal are authenticated by the server rather than supplied in a tool input object.

After the client connects, call whoami before a capability request. It returns authenticated workspace and principal identity. This verifies the client is operating in the intended workspace and makes a wrong identity visible before it searches or runs work. A workspace boundary includes the actor, explicit scopes, and that workspace's spend policy.
ArchitectCLIMCP
Confirm my current workspace and explain the catalog-first flow for building a workbook.The connection provides transport and identity. It does not select a pack, install a skill, or authorize a particular effect. Keep keys and bearer tokens out of prompts, repositories, and tool arguments. If an MCP client cannot use remote HTTP transport, use the CLI or direct REST instead of inventing a local server configuration.

The CLI needs Node.js 22 or newer. Run npm install -g @trydreamstate/cli, then dreamstate login. A successful login installs hosted Dreamstate skills for each detected Claude Code, Codex, or Cursor installation. Use dreamstate login --no-skills to skip skills, or dreamstate skills install --agents claude-code codex cursor --skill '*' to install them explicitly.

## Route a goal and read skills

Use packs_list to read available pack definitions, packs_get to read one exact definition, and packs_route with a goal to select the work domain. Packs are metadata, not authority. A tables route helps an agent find workbook work, but it neither changes the MCP control roster nor bypasses the search and get steps.

Use skills_list to find workspace skills and skills_get to read one. Skills teach practice. They do not grant authority or bind a capability. For example, a workbook-building skill can explain the task sequence while the current tool contract still determines required inputs, available modes, cost policy, and output shape.
ArchitectCLIMCP
Route a workbook goal, read the list-building skill, then search for a current capability contract.The MCP search control calls the scope field toolset. Architect uses pack_id for the equivalent scoped discovery field. These names are intentionally different by transport, so preserve the MCP spelling in an MCP request. No server URL parameter changes the toolset, and a pack scope applies only to the discovery request that carries it.

## Search, get, then run

Every capability execution begins with tools_search. Search accepts a plain-language goal or query terms and can include a pack scope, output needs, input context, side-effect needs, a cursor, and a limit. The search response can include tool_turn_token and runnable_contracts. A contract marked fetched: true was delivered with the search response and can be run in that turn.

For any candidate not already fetched, call tools_get with the exact capability_id and the turn token. The get control can also read a batch through capability_ids, with a maximum of ten identifiers. It accepts compact or full detail. Compact is the model-facing form containing the input schema, required fields, modes, policies, and an example.

Call tools_run only after the contract is available. Pass its capability identifier, an object of parameters matching that schema, a current turn token, and an explicit mode when the capability mutates state. The run control supports smoke_test, dry_run, and live. The server never chooses live by default for a mutation.
ArchitectCLIMCP
Search for the contract that creates a workbook called Trial accounts. Use dry run and show the result before any live call.A successful result uses the canonical envelope. It states whether the call was executed, its effect count and return kind, and can include data, changed values, a receipt, execution metadata, reversibility, and budget values. A state-bearing result can include a web_url for the matching app object. Use that deep link for a human view, but carry the JSON identifier for subsequent tool calls.

Quoted live work

A priced live request can return a quote. Keep the parameters unchanged, use the returned quote hash, and provide a non-negative max_credits ceiling when you repeat it. Search and skill reads do not replace checking the fetched capability's cost policy.

## Inspect progress with runs

Use runs_list to page durable work, runs_get to inspect one run, runs_events to page its ordered event snapshots, and runs_cancel to request cancellation. Run list and events accept a cursor and a limit. The server returns next_cursor and has_more, so a client should pass the returned cursor back unchanged when another page exists.

A run read reports the durable run, state version, progress snapshots, partial results, exhaustion reason, retry frontier, degradation state, permitted operations, and timestamps. It also carries decision hints, a web URL, a UI URI, item counts, credit fields, terminal state, and failed-item repair hints. This HTTP get waits from zero through 20 seconds. An Architect streaming runs_get may wait up to 120 seconds in one call and returns as soon as the run is terminal. An unsettled response can be HTTP 202 with the same run id.
ArchitectCLIMCP
Inspect this run, page its events if needed, and show the current state version before taking a cancellation action.Cancellation requires the state version from a prior read because the run may change between the read and the action. If a worker has moved it, read the new state and reconcile it. The full field and result-shape reference is on MCP reference.

## When it goes wrong

If connection fails, confirm the hosted URL and OAuth sign-in. Use a workspace machine key only for CI or a client without OAuth, then call whoami after reconnecting. If the identity or workspace is wrong, stop and select the intended credential or workspace. The client should never place credentials in a tool input because the server authenticates them outside the MCP schema.

If a run returns capability_not_fetched, search again in the current turn, retain the new tool_turn_token, call get for the missing contract, and retry. If it returns mode_required, set one of the three documented modes. If a strict schema rejects a field, use the published field list rather than translating a CLI or REST spelling into MCP.

If a run control reports a changed state, call runs_get and use its latest state version. If a page says has_more: true, pass its cursor to the next request. If a live request returns quote_required, retain the same parameters and include the quote's credit ceiling when repeating it. For the error-envelope structure, see Envelope and errors.

## MCP reference

Source: https://www.trydreamstate.com/docs/surfaces/mcp-reference

Review the controls exposed by the Dreamstate MCP server.

The Dreamstate MCP server has thirteen shared controls: six metadata controls, three capability controls, and four run controls. Use this reference when an MCP client must send exact field names and limits instead of guessing from a workflow. The server at https://mcp.trydreamstate.com/mcp is the same contract used by Architect, the CLI, and the REST API.

The controls are intentionally small. A pack and a skill describe and route work, while a capability contract determines the input, execution policy, and output for the work itself. Call tools_search, keep the returned turn token, call tools_get for any contract not delivered as runnable, then call tools_run. See MCP server for connection and turn-flow guidance.

## Connect to the MCP server

Use https://mcp.trydreamstate.com/mcp for every MCP client. OAuth is first, so no key is needed. Use a workspace machine key only for CI or a client without OAuth, with Authorization: Bearer <machine key>.

Read controls declare readOnlyHint, so they do not need confirmation. Write controls declare their own annotations. ChatGPT confirms write actions.

## Identity, packs, and skills

Metadata controls are strict objects. whoami and packs_list accept an empty object. packs_get needs the exact pack_id, while packs_route needs a non-empty goal. A pack is metadata rather than authority. Routing a goal to the tables pack does not alter the MCP tool list or make a capability safe to call without its contract.

Skills are also metadata. skills_list accepts a query and a numeric limit from 1 through 10. skills_get requires the skill identifier and can select a supporting file. Read a skill for practice, then use the capability controls for the action. The server authenticates the credential and principal, so neither is a field in these tool inputs.

| Control | Arguments | Result |

| whoami | None | Authenticated workspace and principal identity. |

| packs_list | None | Available capability-pack definitions. |

| packs_get | pack_id: string, required | One pack definition. |

| packs_route | goal: non-empty string, required | The pack route for a goal. |

| skills_list | query: string, optional; limit: integer 1 to 10, optional | Workspace skill metadata. |

| skills_get | id: non-empty string, required; file: non-empty string, optional | One skill or a selected supporting file. |
ArchitectMCP
Identify my workspace, route a workbook goal, then show the list-building skill before searching for a capability.The example returns metadata rather than a workbook. That separation is useful: the client can show the intended workspace and relevant practice before it prepares an execution request. If a skill has a supporting file, pass its exact relative file value to skills_get. Do not invent an input that resembles a capability identifier, because each metadata schema rejects unrecognized keys.

## Search, get, and run

tools_search requires a goal, query terms, or both. Its limit accepts 1 through 50 and the HTTP route builds a default limit of 25 when one is omitted. Search can scope discovery to one pack through toolset. This is a discovery filter, not a persistent MCP server setting. The same pack field is called pack_id by Architect, but MCP uses toolset for search.

tools_get needs exactly one identifier form. Use capability_id for one record or capability_ids for a batch of up to ten. Supplying both forms or neither is invalid. The compact detail is the normal model-facing contract: inputs, required fields, modes, policies, and an example. Full detail asks for the whole catalog record.

tools_run uses the fetched capability identifier and an object of capability parameters. Its params default is an empty object, but that is not a substitute for required fields in the underlying schema. A mutation must name a mode. The route returns mode_required when mode is absent and names smoke_test, dry_run, and live as repairs.

| Field | Required | Meaning | Default |

| tools_search.goal | Goal or query_terms | A non-empty goal, maximum 2,000 characters. | None |

| tools_search.query_terms | Goal or query_terms | One to 50 non-empty search terms. A comma-separated REST value becomes terms. | None |

| tools_search.version | Optional | Contract version. Only 1 is accepted. | Omitted |

| tools_search.domains | Optional | Up to 50 domain terms used to narrow discovery. | Omitted |

| tools_search.kinds | Optional | Up to 20 search kinds from the published kind enum. | Omitted |

| tools_search.available_inputs | Optional | Up to 50 input terms already available to the caller. | Omitted |

| tools_search.desired_outputs | Optional | Up to 50 output terms the caller needs. | Omitted |

| tools_search.required_side_effects | Optional | Up to 50 effect terms that the work must include. | Omitted |

| tools_search.excluded_side_effects | Optional | Up to 50 effect terms that the work must avoid. | Omitted |

| tools_search.toolset | Optional | One pack identifier that scopes discovery. MCP uses toolset here. | Omitted |

| tools_search.tool_turn_token | Optional | A token returned by an earlier search in the same turn. | Omitted |

| tools_search.agent_session_id | Optional | A UUID identifying an agent session. | Omitted |

| tools_search.table_action_mode | Optional | Either source or column for table-action suggestions. | Omitted |

| tools_search.cursor | Optional | A non-empty cursor returned by a previous search page. | Omitted |

| tools_search.limit | Optional | An integer from 1 through 50. | Server search defaults to 25 |

| tools_get.capability_id | Exactly one id form | One exact capability identifier, maximum 240 characters. | None |

| tools_get.capability_ids | Exactly one id form | A batch of 1 through 10 exact capability identifiers. | None |

| tools_get.workspace_id | Optional | A workspace UUID. | Omitted |

| tools_get.tool_turn_token | Optional | The token from the current discovery turn. | Omitted |

| tools_get.agent_session_id | Optional | A UUID identifying an agent session. | Omitted |

| tools_get.detail | Optional | compact returns contract information; full requests the full catalog record. | compact |

| tools_run.capability_id | Required | One exact capability identifier, maximum 240 characters. | None |

| tools_run.params | Optional | An object that must match the fetched capability input schema. | Empty object |

| tools_run.mode | Capability dependent | smoke_test, dry_run, or live. A mutating call with no mode is refused. | Read behavior depends on the capability |

| tools_run.max_credits | Optional | A non-negative credit ceiling for the execution envelope. | Omitted |

| tools_run.quote_hash | Optional | The quote hash returned by a priced earlier call. | Omitted |

| tools_run.tool_turn_token | Optional | The current discovery-turn token. | Omitted |

| tools_run.idempotency_key | Live write dependent | A replay-safety key. The server requires it only when the live write needs it. | Omitted |

| tools_run.agent_session_id | Optional | A UUID identifying an agent session. | Omitted |

| tools_run.workflow_id | Optional | A workflow UUID. | Omitted |
ArchitectMCP
Find the contract for creating a workbook called Trial accounts. Use dry run and show the returned state before a live call.A successful canonical execution envelope can contain ok, executed, effect_count, returns, data, changed, receipt, meta, reversibility, and budget fields. The execution metadata contains a capability identifier plus nullable run, idempotency, and grant-evaluation identifiers. A state-bearing result can also provide a web_url in its published response so a person can open the result in the web app.

For a priced live call, use the quote returned by the server and keep the same parameters when repeating the call with a non-negative max_credits value. A quote hash is a transport field beside params, not a capability parameter. For a live write that needs replay safety, send idempotency_key at the top level. A dry run and a smoke test never need that write-specific key.

## Inspect and control runs

Run controls operate on durable work after a capability returns a run identifier. runs_list is paged with a cursor and a limit. Its result has runs, next_cursor, and has_more. Each listed run includes its identifier, capability or run kind, status, and start time. Pass the returned cursor back unchanged rather than constructing one.

runs_get includes a required path-style run_id and optionally waits for zero through 20 seconds on this HTTP call. An Architect streaming runs_get may wait up to 120 seconds and returns as soon as the run is terminal. Omit wait_seconds for an immediate snapshot; a zero also requests no wait. An unsettled run can return HTTP 202 with the same run identifier. The response exposes the durable run, next decision hints, item counts, credit estimates and actuals, terminal state, and failed items.

runs_events adds an ordered event page to the run read. runs_cancel requires the last observed expected_state_version. Read the run first, then provide its state version so the server can reject a cancellation that races with a changed run. A reason is optional and is limited to 1,000 characters. Version is constrained to 1 and defaults to 1.

| Control | Arguments | Result shape |

| runs_list | cursor: string or null, optional; limit: integer 1 to 500, default 100 | runs, next_cursor, has_more |

| runs_get | run_id: non-empty string, required; wait_seconds: integer 0 to 20 on this HTTP call (Architect streaming runs_get accepts 0 to 120), optional | run, decision hints, item counts, cost fields, terminal state, failed items |

| runs_events | run_id: non-empty string, required; cursor: string or null, optional; limit: integer 1 to 500, default 100 | runs_get result plus ordered events |

| runs_cancel | run_id: non-empty string, required; version: 1, default 1; expected_state_version: non-negative integer, required; reason: string up to 1,000 characters, optional | Updated run resource |
ArchitectMCP
Inspect my latest run. If it is still active, show its events. If it has failed, show the exact repair hint before taking another action.The durable run includes run_id, run_kind, status, state_version, completed and incomplete steps, partial results, paging values, an exhaustion reason, retry frontier, degradation information, and permitted run operations. It also includes creation and update timestamps. The run-read result adds a web URL and UI URI, plus a decision hint and its kind. Treat these fields as the current state, not as a promise that the next worker transition will succeed.

## When it goes wrong

A malformed MCP input is rejected by the strict published schema. For a search, provide a goal or query terms. For a get, provide exactly one of capability_id and capability_ids. For a run, correct the input to the published schema and retry. The REST implementation returns invalid_request for invalid inputs and includes a repair whose kind is fix_input.

If the gateway answers capability_not_fetched, start over with search in the current client turn. Keep its tool_turn_token, use get for the missing contract, then retry the same capability. Do not reuse a token from an unrelated conversation turn. If the gateway answers mode_required, choose the required mode deliberately rather than relying on a live default.

If a cancellation fails because the run changed, call runs_get again and use the new state_version. If a list or events response has has_more: true, call the same control with its next_cursor. If the response reports provider degradation, use its retry information and decision hint instead of launching a duplicate request. For a priced call that returns quote_required, preserve the quoted request parameters and add a credit ceiling when repeating it.

## Connect Claude

Source: https://www.trydreamstate.com/docs/surfaces/connect-claude

Connect Claude to Dreamstate MCP with a browser OAuth sign-in.

Connect Claude to Dreamstate so Claude can work with the selected Dreamstate workspace. Dreamstate uses OAuth, so you do not need a key.

Once connected, you can ask Claude to:

- Build a scored lead list in a workbook.
- Enrich workbook rows with work emails.
- Draft and launch a sequence.
- Schedule a LinkedIn post.
- Check AI visibility or read why a run failed.
## Before you start

You need a Dreamstate workspace and a Claude plan that supports custom connectors. Team and Enterprise members need an Owner to add the shared connector.

## Step-by-step setup

- 1
### Open Connectors
In Claude, open Customize > Connectors > Add custom connector.
- 2
### Add Dreamstate
Paste https://mcp.trydreamstate.com/mcp, then select Add and Connect.
- 3
### Sign in
Sign in to Dreamstate and pick a workspace.Remote MCP server URL
https://mcp.trydreamstate.com/mcp
## Authenticate with Dreamstate
Claude opens the Dreamstate sign-in flow. Sign in and pick a workspace, then return to Claude.

## Test the connection
Agent promptRun whoami and tell me which Dreamstate workspace you are connected to.
If it returns your workspace name, setup is complete.

## For team or organization setups

A Team or Enterprise Owner adds the shared connector from Organization settings > Connectors > Add > Custom > Web. Use the same URL. In Advanced settings, Use Claude's published identity is recommended, and Register automatically also works. Members then select Connect and sign in to Dreamstate.

## What to do next

Read Quickstart, MCP reference, or Your first session.

## When it goes wrong

- I do not see the Connectors option. Confirm that your Claude plan supports custom connectors. On Team or Enterprise, ask an Owner to add Dreamstate in Organization settings > Connectors.
- The sign-in window opened but nothing happens. Start the connection again from Claude, complete sign-in in that browser window, and allow the browser to return to Claude. A redirect refused error means the connection must begin in Claude.
- Claude cannot find Dreamstate tools. Select + > Connectors in the active chat and turn on Dreamstate.
- It connected to the wrong workspace. Ask Claude to run whoami, then reconnect and pick the intended workspace. A 401 Missing Bearer response means that OAuth sign-in must be completed again.
## Best practices

- Test the connection immediately with whoami.
- Enable Dreamstate for each conversation where Claude requires it.
- Read tools do not need confirmation. Claude confirms write actions when required.

## Connect Claude Code

Source: https://www.trydreamstate.com/docs/surfaces/connect-claude-code

Connect Claude Code to Dreamstate MCP from the terminal.

Connect Claude Code to Dreamstate so Claude Code can work with the selected Dreamstate workspace. Dreamstate uses OAuth, so you do not need a key.

Once connected, you can ask Claude Code to:

- Build a scored lead list in a workbook.
- Enrich workbook rows with work emails.
- Draft and launch a sequence.
- Schedule a LinkedIn post.
- Check AI visibility or read why a run failed.
## Before you start

You need a Dreamstate workspace and Claude Code with remote HTTP MCP server support.

## Step-by-step setup

- 1
### Open a terminal
Open the terminal where the claude command is available.
- 2
### Add Dreamstate
Run the command below. It registers a remote HTTP server named dreamstate.
- 3
### Open MCP controls
Start Claude Code, then type /mcp to see the active MCP servers and authenticate Dreamstate.Claude CodeRemote MCP server URL
claude mcp add --transport http dreamstate https://mcp.trydreamstate.com/mcp
## Authenticate with Dreamstate
Claude Code opens the Dreamstate sign-in flow. Sign in and pick a workspace, then return to Claude Code.

## Test the connection
Agent promptRun whoami and tell me which Dreamstate workspace you are connected to.
If it returns your workspace name, setup is complete.

## What to do next

Read Quickstart, MCP reference, or Your first session.

## When it goes wrong

- I do not see Dreamstate in MCP controls. Run the add command again, then type /mcp and confirm that dreamstate is listed.
- The sign-in window opened but nothing happens. Run /mcp and authenticate again from the same local Claude Code session. A redirect refused error means the browser flow must start from that local client.
- Claude Code cannot find Dreamstate tools. Use /mcp to confirm that the dreamstate server is active for this session.
- It connected to the wrong workspace. Run whoami, then authenticate again and pick the intended workspace. A 401 Missing Bearer response means that OAuth sign-in must be completed again.
## Best practices

- Test the connection immediately with whoami.
- Use /mcp to confirm Dreamstate is active before a new task.
- Read tools do not need confirmation.

## Connect ChatGPT

Source: https://www.trydreamstate.com/docs/surfaces/connect-chatgpt

Connect ChatGPT to Dreamstate MCP through a custom connector.

Connect ChatGPT to Dreamstate so ChatGPT can work with the selected Dreamstate workspace. Dreamstate uses OAuth, so you do not need a key.

Once connected, you can ask ChatGPT to:

- Build a scored lead list in a workbook.
- Enrich workbook rows with work emails.
- Draft and launch a sequence.
- Schedule a LinkedIn post.
- Check AI visibility or read why a run failed.
## Before you start

You need a Dreamstate workspace. A managed ChatGPT workspace may control custom MCP server access.

## Step-by-step setup

- 1
### Open plugins
Open chatgpt.com/plugins, then select + and Add custom MCP server.
- 2
### Create Dreamstate
Enter Name: Dreamstate and URL: https://mcp.trydreamstate.com/mcp. Choose OAuth, review the warning, select I understand and want to continue, then select Create as a plugin.
- 3
### Sign in
Sign in to Dreamstate and pick a workspace.Remote MCP server URL
https://mcp.trydreamstate.com/mcp
## Authenticate with Dreamstate
ChatGPT opens the Dreamstate sign-in flow. Sign in and pick a workspace, then return to ChatGPT.

## Test the connection
Agent promptRun whoami and tell me which Dreamstate workspace you are connected to.
If it returns your workspace name, setup is complete.

## For team or organization setups

Some older Enterprise and Edu workspaces use Settings > Apps > Advanced settings > Developer mode instead. A workspace administrator may control access. After Dreamstate ships new tools, open the connection and select Refresh.

## What to do next

Read Quickstart, MCP reference, or Your first session.

## When it goes wrong

- I do not see the custom MCP server option. Open chatgpt.com/plugins. In an older Enterprise or Edu workspace, turn on Developer mode under Settings > Apps > Advanced settings.
- The sign-in window opened but nothing happens. Start OAuth again from the Dreamstate app in ChatGPT, finish sign-in in the browser, and return to the same conversation. A redirect refused error means the flow must start from ChatGPT.
- ChatGPT cannot find Dreamstate tools. Open the Dreamstate connection and select Refresh.
- It connected to the wrong workspace. Run whoami, then reconnect and pick the intended workspace. A 401 Missing Bearer response means that OAuth sign-in must be completed again.
## Best practices

- Test the connection immediately with whoami.
- Open the connection and select Refresh after Dreamstate ships new tools.
- ChatGPT confirms write actions. Read tools do not need confirmation.

## Connect Codex

Source: https://www.trydreamstate.com/docs/surfaces/connect-codex

Connect Codex to Dreamstate MCP with config.toml and OAuth.

Connect Codex to Dreamstate so Codex can work with the selected Dreamstate workspace. Use OAuth first, so there is no key to copy.

Once connected, you can ask Codex to:

- Build a scored lead list in a workbook.
- Enrich workbook rows with work emails.
- Draft and launch a sequence.
- Schedule a LinkedIn post.
- Check AI visibility or read why a run failed.
## Before you start

You need a Dreamstate workspace and Codex with remote MCP server support.

## Step-by-step setup

- 1
### Open Codex configuration
Open ~/.codex/config.toml. For a trusted project, you can instead use .codex/config.toml.
- 2
### Add Dreamstate
Add the server block below. The server name is dreamstate.
- 3
### Sign in
Run codex mcp login dreamstate. In the Codex TUI, use /mcp to inspect active MCP servers.config.tomlLoginRemote MCP server URL
[mcp_servers.dreamstate]
url = "https://mcp.trydreamstate.com/mcp"
## Authenticate with Dreamstate
A browser window opens after codex mcp login dreamstate. Sign in with your Dreamstate account, choose the workspace, then return to Codex. Use a workspace machine key only for CI and clients without OAuth.

## Test the connection
Agent promptRun whoami and tell me which Dreamstate workspace you are connected to.
If it returns your workspace name, setup is complete.

## What to do next

Read Quickstart, MCP reference, or Your first session.

## When it goes wrong

- I do not see Dreamstate in MCP controls. Check the server block in ~/.codex/config.toml, then run /mcp in Codex to confirm that dreamstate is listed.
- The sign-in window opened but nothing happens. Run codex mcp login dreamstate again and finish sign-in in the browser opened by Codex. A redirect refused error means the flow must start from the local Codex client.
- Codex cannot find Dreamstate tools. Use /mcp to confirm that dreamstate is active for the current session.
- It connected to the wrong workspace. Run whoami, then log in again and choose the intended workspace. A 401 Missing Bearer response means login needs to be completed again.
## Best practices

- Test the connection immediately with whoami.
- Use /mcp to confirm Dreamstate is active before a new task.
- Read tools do not need confirmation because MCP tools declare readOnlyHint.

## Connect Cursor

Source: https://www.trydreamstate.com/docs/surfaces/connect-cursor

Connect Cursor to Dreamstate MCP as a remote MCP server.

Connect Cursor to Dreamstate so Cursor can work with the selected Dreamstate workspace. Use OAuth first, so there is no key to copy.

Once connected, you can ask Cursor to:

- Build a scored lead list in a workbook.
- Enrich workbook rows with work emails.
- Draft and launch a sequence.
- Schedule a LinkedIn post.
- Check AI visibility or read why a run failed.
## Before you start

You need a Dreamstate workspace and a Cursor installation where remote MCP servers are allowed.

## Step-by-step setup

- 1
### Open MCP setup
In Cursor, open Settings > MCP, or open the mcp.json configuration file.
- 2
### Add Dreamstate
Add a remote server named dreamstate using the URL below, then save the settings or file.
- 3
### Log in
Select Dreamstate in Cursor's MCP settings and follow the browser login prompt when Cursor asks you to authenticate.mcp.jsonRemote MCP server URL
{
"mcpServers": {
"dreamstate": {
"url": "https://mcp.trydreamstate.com/mcp"
}
}
}
## Authenticate with Dreamstate
A browser window opens from Cursor. Sign in with your Dreamstate account, choose the workspace, then return to Cursor. Use a workspace machine key only for CI and clients without OAuth.

## Test the connection
Agent promptRun whoami and tell me which Dreamstate workspace you are connected to.
If it returns your workspace name, setup is complete.

## For team or organization setups

Cursor team administrators can control which MCP servers are available. Share the Dreamstate server name and URL with the team, then have each member sign in, choose a workspace, and verify it with whoami.

## What to do next

Read Quickstart, MCP reference, or Your first session.

## When it goes wrong

- I do not see the MCP option. Update Cursor or open its mcp.json configuration from the MCP setup area. Your organization may also restrict remote MCP servers.
- The sign-in window opened but nothing happens. Start login again from Cursor's MCP settings, complete sign-in in that browser window, and return to Cursor. A redirect refused error means the flow must start from Cursor.
- Cursor cannot find Dreamstate tools. Return to Settings > MCP, confirm Dreamstate is connected, then enable it for the active Cursor chat or agent session.
- It connected to the wrong workspace. Run whoami, then reconnect and choose the intended workspace. A 401 Missing Bearer response means OAuth sign-in needs to be completed again.
## Best practices

- Test the connection immediately with whoami.
- Enable Dreamstate for each chat or agent session where Cursor requires it.
- Read tools do not need confirmation because MCP tools declare readOnlyHint.

## Other MCP clients

Source: https://www.trydreamstate.com/docs/surfaces/connect-other-clients

Connect another MCP client to Dreamstate with OAuth or an API key header.

Connect another MCP client to Dreamstate so it can work with the selected Dreamstate workspace. OAuth is first, so you do not need a key when the client supports OAuth.

Once connected, you can ask the client to:

- Build a scored lead list in a workbook.
- Enrich workbook rows with work emails.
- Draft and launch a sequence.
- Schedule a LinkedIn post.
- Check AI visibility or read why a run failed.
## Before you start

You need a Dreamstate workspace and a remote HTTP MCP server setting. OAuth clients need public-client OAuth with Dynamic Client Registration, Client ID Metadata Documents, and PKCE S256. A client without OAuth needs a secure setting for an Authorization bearer header.

## Step-by-step setup

- 1
### Add a remote MCP server
Open your client's custom, remote, or HTTP MCP server setting. The menu name differs by client.
- 2
### Enter Dreamstate
Set Name: Dreamstate and Remote MCP server URL: https://mcp.trydreamstate.com/mcp. Do not add another path or query parameter.
- 3
### Choose authentication
Choose OAuth when the client offers it. Use a workspace machine key only for CI or a client without OAuth, then configure the bearer header below in the client's secure credential setting.Remote MCP server URLMachine key header
https://mcp.trydreamstate.com/mcp
## Authenticate with Dreamstate
For OAuth, the client opens the Dreamstate sign-in flow. Sign in and pick a workspace, then return to the client. Dreamstate publishes OAuth discovery at /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server. If the client cannot complete OAuth, use a workspace machine key only for CI or that client.

## Test the connection
Agent promptRun whoami and tell me which Dreamstate workspace you are connected to.
If it returns your workspace name, setup is complete.

## What to do next

Read Quickstart, MCP reference, or Your first session.

## When it goes wrong

- I do not see an MCP option. Look for a custom, remote, or HTTP MCP server setting in the client. If it has no remote MCP support, it cannot connect to Dreamstate this way.
- The sign-in window opened but nothing happens. Start the OAuth flow again from the client, finish sign-in in the browser, and return to that client. If its callback is not supported, use a workspace machine key only for CI or that client.
- The client cannot find Dreamstate tools. Confirm the server is connected and enable it for the active conversation or session if the client requires that step.
- It connected to the wrong workspace. Run whoami, then reconnect and pick the intended workspace. A 401 Missing Bearer response means that OAuth sign-in must be completed again or a workspace machine key is missing.
## Best practices

- Test the connection immediately with whoami.
- Enable Dreamstate for each conversation where the client requires it.
- Read tools do not need confirmation.

## REST API

Source: https://www.trydreamstate.com/docs/surfaces/rest-api

Use the REST API to search tools, read schemas, run tools, and inspect runs.

The Dreamstate REST API is at https://api.trydreamstate.com. Use it when your application needs direct HTTP access to the same capability discovery and execution contract used by Architect, the CLI, and MCP. It is not a list of stable business endpoints for each product feature. Search finds the current capability, get returns its exact schema, and run executes that specific contract.

Authenticate the request for the intended workspace, then begin with tool discovery. State-bearing results can provide a web_url to the corresponding object in the web app, while JSON identifiers remain the source of truth for later API requests. This page documents the shared tool routes and run resources. The complete control-field view is in MCP reference.

## Search the catalog

GET /api/v1/tools searches the customer capability catalog. The request needs a goal, query terms, or both. Query values are parsed by the same canonical search schema used by the other doors. A search response can include a tool_turn_token and runnable_contracts. A runnable contract marked fetched can be used in the same turn without a separate get call.

Use toolset to restrict discovery to one customer pack. It is a filter for this request, not a persistent API setting. The route rejects an unknown toolset with invalid_request and names the customer pack identifiers available for the repair. It also validates a table-action search against the caller's table-write scope when table_action_mode is present.

| Query field | Type | Required | Meaning | Default |

| goal | string | Goal or query_terms | A trimmed goal from 1 through 2,000 characters. | None |

| query_terms | string[] | Goal or query_terms | One through 50 trimmed terms, each up to 160 characters. | None |

| domains | string[] | Optional | Terms that narrow discovery by domain. | Omitted |

| kinds | enum[] | Optional | Up to 20 published search kinds. | Omitted |

| available_inputs | string[] | Optional | Inputs already available to the caller. | Omitted |

| desired_outputs | string[] | Optional | Outputs requested by the caller. | Omitted |

| required_side_effects | string[] | Optional | Effects the caller requires. | Omitted |

| excluded_side_effects | string[] | Optional | Effects the caller excludes. | Omitted |

| toolset | string | Optional | A customer pack identifier used to scope discovery. | Omitted |

| tool_turn_token | string | Optional | A token from an earlier search in the current turn. | Omitted |

| agent_session_id | UUID | Optional | An agent session identifier. | Omitted |

| table_action_mode | source | column | Optional | Requests a table-action suggestion mode. | Omitted |

| cursor | string | Optional | A cursor returned by an earlier page. | Omitted |

| limit | integer | Optional | A value from 1 through 50. | 25 in ordinary search |
ArchitectREST
Search the tables pack for a capability that creates a workbook, then show the exact contract before running it.The response is a discovery result, not a mutation. Read the goal, returned candidates, route information, turn token, and runnable contracts before deciding which item to fetch. A caller that has only a remembered capability name should still search first because catalog availability, schema, execution policy, and workspace scope are resolved for the active request.

## Get the exact contract

GET /api/v1/tools/:id reads an exact capability contract. The path supports one id or a comma-separated batch of ids because capability identifiers never contain a comma. Query fields are workspace_id, tool_turn_token, agent_session_id, and detail. Detail accepts compact or full, with compact as the ordinary model-facing contract.

Use compact detail to inspect the input schema, required fields, modes, policies, and an example. Use full detail only when your application needs the full catalog record. For a batch get, the response has contracts whose capabilities are projected using the requested detail. For one get, the response has the capability contract using that detail. Keep the search token when the search delivered one, because the gateway uses it to keep discovery and execution in the same turn.
ArchitectREST
Retrieve the compact contract for the workbook capability found in this turn. Tell me which inputs are required and which modes it supports.Do not substitute a client alias such as tool_id for the capability path. The REST route has the capability id in its path, while MCP exposes the same concept as capability_id. The output contract is what should determine the next HTTP body, not a copied example from this page.

## Run a capability

POST /api/v1/tools/:id/run accepts a strict execution envelope. The selected capability id is in the path. The params object belongs to the selected capability schema, while mode, credits, quote, turn token, and idempotency are execution-envelope controls. The API returns invalid_request if the body fails the published schema and includes a fix_input repair.

Mutating calls must explicitly include smoke_test, dry_run, or live. Smoke test inspects static schema and policy without writing or creating an audit entry. Dry run validates and previews against workspace state without business writes, provider spend, or outward actions. Live executes the selected capability. The route returns mode_required for a mutation with no mode and says that it never defaults to live.

| Body field | Type | Required | Meaning | Default |

| params | object | Optional | Capability parameters matching the fetched input schema. | Empty object |

| mode | smoke_test | dry_run | live | Mutating capability | The execution mode. The server never defaults a mutation to live. | Capability dependent for reads |

| max_credits | number | Optional | A non-negative execution-envelope credit ceiling. | Omitted |

| quote_hash | quoted hash | Optional | A quote from a prior priced request. | Omitted |

| tool_turn_token | string | Optional | A current discovery-turn token. | Omitted |

| idempotency_key | string | Live write dependent | A replay-safety key, 1 through 255 characters. | Omitted |

| agent_session_id | UUID | Optional | An agent session identifier. | Omitted |

| workflow_id | UUID | Optional | A workflow identifier. | Omitted |
ArchitectREST
Use dry run for the fetched workbook contract with the name Trial accounts. Show the returned envelope and any run identifier.A successful envelope has ok: true, an executed boolean, effect_count, a return kind, optional data and changed values, optional receipt and execution metadata, optional reversibility, and budget fields. Canonical execution metadata includes capability, run, idempotency, and grant-evaluation identifiers. An error envelope has ok: false, a code, message, repair, optional metadata, budget fields, and optional details.

Credit quotes and live requests

A priced live call can return quote_required with an estimate. Repeat the same request parameters with the quote data and a non-negative max_credits ceiling. Treat a live external effect according to the fetched capability policy, not according to a generic route name.

## Inspect runs and pages

The run routes support list, get, events, and cancel. Run list and events use the canonical paging fields: a returned cursor and a limit from 1 through 500, defaulting to 100. Run get accepts an optional wait from zero through 20 seconds on this HTTP call. An Architect streaming runs_get may wait up to 120 seconds by repeating this read. An omitted wait returns the current snapshot immediately, while an unsettled request can return HTTP 202 with the same run id.

A run resource carries the durable run envelope, an exact next decision hint, its kind, a web URL, and a UI URI. The run itself includes status, state version, completed and incomplete snapshots, partial results, cursor state, exhaustion reason, retry frontier, degradation state, permitted operations, and timestamps. A run get additionally reports item counts, credit estimate and actual values, terminal status, and failed items with repair hints.
ArchitectREST
List active runs, inspect this run, then show event details and the next decision hint if it needs attention.Cancellation is a stateful write. Read the run, then send its current expected_state_version with an optional reason to the cancel operation. If another worker moved the run first, read again and reconcile the new state instead of reusing an old state version. The CLI offers the same run operations when a terminal workflow is more convenient than direct HTTP.

## When it goes wrong

An unauthorized response means the request lacks usable authentication. A missing_scope response on a table-action search means the caller needs table-editor access. An invalid_request response means a path, query, or body failed a strict schema. Use the returned repair and legal field names. Do not silently drop a value that carries scope, token, or mode meaning.

If execution returns capability_not_fetched, search again in the current turn, preserve its tool_turn_token, get the missing contract, and retry. If it returns mode_required, supply the mode before retrying. If an idempotency header and body key differ, the API returns idempotency_conflict because it does not pick a winner. Send one key or the same key in both places.

If a result has has_more: true, pass the returned cursor into the next list or events request. If a provider reports degradation, use the run response's retry information and decision hint before opening another request. If a quote is required, keep the original parameters unchanged and add the expected credit ceiling. For detailed error-envelope fields, use Envelope and errors.

## Agent clients

Source: https://www.trydreamstate.com/docs/surfaces/agent-clients

Choose a Dreamstate MCP connection guide for Claude, ChatGPT, Codex, Cursor, or another client.

Connect Dreamstate to the AI client you already use. Each guide uses the same remote MCP server URL and uses OAuth to sign you in to the right workspace. Start with whoami.

## Choose your client

Choose the guide for the product where you will use Dreamstate. All guides use https://mcp.trydreamstate.com/mcp. OAuth is first. Use a workspace machine key only for CI or a client without OAuth.

- Claude
- Claude Code
- ChatGPT
- Codex
- Cursor
- Other MCP clients
## After the connection

Start with whoami and confirm the workspace before asking for work. Read MCP reference for the MCP controls and Your first session for a first workflow.

Use the client guide that matches where you work, then keep the server URL and its connection in the client settings instead of a prompt. A successful whoami result confirms the workspace, not that every conversation has the connector enabled. For paid work, read tools do not need confirmation. If a sign-in page stalls, start the connection again from that client so it can receive the OAuth return. If a client cannot use OAuth, the Other MCP clients guide explains the workspace machine key header option. For Claude, ChatGPT, Claude Code, Codex, Cursor, or Grok, use the CLI to install Dreamstate skills automatically.

## Install the CLI and skills

Open CLI and MCP at /dashboard/settings/api for the Claude, ChatGPT, and CLI tabs. The Claude and ChatGPT tabs include a Copy first prompt button.

The CLI needs Node.js 22 or newer. Install it, then run dreamstate login. The browser approval signs you in and installs every hosted Dreamstate skill for each detected Claude Code, Codex, or Cursor installation. Use dreamstate login --no-skills to skip that installation.
CLIInstall skills
npm install -g @trydreamstate/cli
dreamstate loginOn a remote or SSH box, create a session in the app and run dreamstate login --token <token>. If no agent is detected, or skill installation fails, login still succeeds and prints Run dreamstate skills install to install Dreamstate skills. to standard error.

## Workspaces, members and roles

Source: https://www.trydreamstate.com/docs/workspace/organizations

A workspace defines membership, permissions, billing, and the data boundary for work.

A workspace is the boundary for the people, settings, credits, and work your team shares. Use it when you need to add a collaborator, understand who can work in the organization, or confirm which workspace holds a setting.

Context belongs to the knowledge store, while tags, comments, and saved views stay with the workspace. API keys are also scoped to one workspace, as described in API keys and scopes.

## What the workspace contains

The workspace pack owns collaborators, membership, organization settings, credit information, agency, tags, comments, and saved views. This boundary prevents a workspace setting or credential from silently applying to another workspace.

| Area | What belongs here |

| Members | Collaborators and their membership in this workspace. |

| Organization settings | The settings that apply to this workspace. |

| Credits and billing | The workspace credit balance, allowance, spending ledger, and billing. |

| Agency and views | Agency work, tags, comments, and saved views that belong to the workspace. |

## Manage members and roles

Open /dashboard/settings and choose the members area to review collaborators and their roles. Check the active workspace before you make a change, because membership belongs to that workspace rather than to a global team list.
ArchitectShow the members in this workspace. Explain each available role change before I make one.

## Check before changing access
Start by confirming the collaborator, the active workspace, and the role you intend to change. Then return to Settings and verify that the member list shows the expected result. A workspace may hold billing, credits, and integrations alongside membership, so changing access has consequences beyond a single screen.
ArchitectIdentify the active workspace and list its members. Do not change anyone. Tell me what I should verify before changing a role.

## Operate within the workspace boundary
Workspace controls apply to one organization at a time. The notes below describe the boundaries and failure results that matter when a team reads settings, changes membership, or transfers ownership.

A workspace is not only a label in the sidebar. It is the boundary that carries collaborators, settings, credits, billing, tags, comments, saved views, portable snapshots, notification delivery, callback URLs, and event webhooks.

Open Settings with the intended workspace active. The application has separate Members, Workspace, Roles, and workspace-notifications settings areas, so a change in one area should not be assumed to have changed another.

Read the current workspace settings immediately before changing a workspace setting. The returned updated_at value is the optimistic-concurrency value required by the settings update operation.

A settings update changes only fields sent in the request. Omitted fields remain untouched, and a workspace settings update cannot change ownership, membership, plan, or seats.

If the settings row changed after it was read, the write is refused with state_version_conflict and nothing changes. Read the current row again, compare the intended change with the current state, then resubmit only the fields still intended.

Member roles are owner, admin, member, and client. An admin can update workspace settings, invite and cancel invitations, and view billing; a member or client has a different workspace role and must not be described as an owner.

Changing a member role applies to an existing non-support membership in this workspace. The operation cannot make a member an owner and cannot change the publishing role.

A role change refuses invalid_member_role_change when the target is the caller, the workspace owner, or an unsupported role. It refuses member_not_found when no matching non-support membership exists.

Removing a member deletes the membership row, which removes that person’s workspace access immediately. It does not delete the person’s user account, their authored work, or a subscription seat.

A removal refuses invalid_member_removal when the target is the caller or the workspace owner. It refuses member_not_found when there is no matching non-support membership, and adding the person back requires a new invitation and acceptance.

Ownership transfer is separate from role editing. It makes the selected member the owner, demotes the previous owner to member, and repoints the workspace owner in one transaction.

Ownership transfer is not a reversible workspace operation. It refuses invalid_new_owner when the target is the current owner, is not a non-support workspace member, or is absent, and it refuses owner_authority_changed if the caller stopped being owner during the operation.

Workspace keys, membership, and spending policy are scoped to the workspace. A machine key cannot switch workspaces, so an automation should use a key belonging to the workspace where it is meant to operate.

Context is deliberately outside the workspace pack’s durable-state boundary. Store a product decision or buyer finding in Context, then use workspace tags, comments, or a saved view to organize the operational work around it.
ArchitectRead the active workspace settings and members. Identify which requested change is a settings update, a member-role update, a removal, or an ownership transfer. Do not make the change.

## Verify the change in the app
Agency work is also owned by the workspace pack, while external provider credentials belong to Integrations. This distinction keeps a workspace management task from being confused with a provider connection change.

Architect can inspect workspace state using the same canonical controls available through other doors. It should search for the active capability and fetch its schema before a run, then report the returned workspace or membership result.

A read-only workspace inspection is free when its capability cost policy says zero credits. A mutation still requires an explicit mode, because the server never defaults a mutating call to live.

Check the visible member list or Settings result after a change. The result should identify the affected member or workspace state, and the app should show the active workspace that received the change.

Do not use a workspace settings write to repair a credit, billing, ownership, or membership issue that belongs to a distinct capability. Read the specific state first, then choose the operation that owns that state.

When you are unsure which workspace contains the work, stop before a mutation. The correct repair is to inspect the active workspace and membership, not to duplicate the setting in several workspaces.

Use the workspace result and the Settings screen together. A response object is the record of the capability result, while the app confirms that the intended workspace now displays the expected collaborators or settings.

| Requested change | Check before moving on |

| Settings update | Read updated_at, submit intended fields, and confirm the resulting workspace settings. |

| Member role | Confirm target membership, selected role, and the returned member role. |

| Member removal | Confirm the target is not the caller or owner, then confirm the member is absent. |

| Ownership transfer | Confirm the new owner is an eligible member and inspect the returned owner state. |

## When it goes wrong

If a role change or removal is refused, read the current member list and confirm the target is an eligible non-support member in the active workspace. For a stale settings write, read settings again and use the fresh updated_at value. For an ownership-transfer refusal, inspect membership and caller authority before trying again.

If the work belongs in Context, a provider connection, or billing rather than membership or settings, use the page and capability that owns that subject. Do not solve a boundary error by broadening a workspace member’s role without checking the actual need.

## API keys and scopes

Source: https://www.trydreamstate.com/docs/workspace/api-keys

Use workspace API keys with explicit scopes and workspace boundaries.

An API key lets a program act within one workspace and as one actor. Use a key when you connect the CLI, MCP server, or REST API to the workspace you intend to operate.

Keys have explicit scopes and a spend policy. They do not cross the workspace boundary, so choose the active workspace before you create one and use workspace settings for membership and roles.

## Find the API key screen

Open Settings and select the api tab. The screen can list keys, create a key, reveal its value, and revoke a key.
ArchitectShow me where API keys are managed for the active workspace. Do not create or reveal a key.

## Scope each key to its job

| Property | Meaning |

| Workspace | The key belongs to one workspace. |

| Actor | The key is associated with one actor. |

| Scopes | The key has explicit permissions. |

| Spend policy | The key has its own spending policy. |
Keep separate keys for separate integrations when their scopes or spending needs differ. This makes the key list easier to audit and limits which workspace each connection can reach.

## Create, reveal, and revoke

Create a key only after checking its workspace and scopes. Store the revealed value in the system that needs it, then return to the API key screen to confirm the key appears in the list. Revoke a key when the connection should no longer act for this workspace.

A key can reach your workspace
Treat a revealed key as a credential. Do not put it in a document, a skill, or a shared message.ArchitectExplain the active workspace, the available API key scopes, and what I should verify before creating a key.

## Choose the right credential
Machine keys are tokens bound to the current workspace for CI and shared runners. A machine key cannot switch workspaces, so create it only after selecting the workspace that the runner must operate.

Sessions are different from machine keys. The settings screen says sessions work in every workspace the user belongs to, begin in a selected workspace, and expire after 90 days of inactivity.

The MCP connection screen says connections work across a user’s workspaces. An agent can switch workspace, while the CLI can receive a workspace selection through its own supported command interface.

A key’s scopes are explicit permissions. Name a key for the integration that uses it and grant only the scopes that integration needs, rather than using one broad credential for unrelated systems.

A key also has its own spend policy. Credit limits are consent for paid work, so a caller should keep an appropriate max-credits ceiling when a discovered capability returns a quote requirement.

The API key screen lists keys for the active workspace. Verify the workspace name shown by the screen before interpreting a key row or deciding that a credential is missing.

Creating a key is an owner action because it changes who can reach workspace resources. Use the signed-in settings flow, not an API key, and keep the action tied to the workspace whose access is intended.

Revealing a key exposes a credential value. Copy it only to the secret store or runtime that needs it, because a Context page, skill, comment, or shared chat transcript is not a credential store.

Revoking a key ends that key’s access. Check the key name, prefix, workspace, and dependent integration before revocation, then confirm the revoked row or status in Settings.

A revoked session stops terminals and connections using that session in every workspace immediately. The settings screen states that this cannot be undone, so use a new login or session rather than expecting a revoked session to resume.
ArchitectInspect the active workspace API key and session settings. Explain whether this integration needs a workspace machine key or a user session, the scope it needs, and the effect of revoking it. Do not create, reveal, or revoke anything.

## Connect a client carefully
For an interactive CLI login, use the documented Dreamstate login flow, which opens browser approval. For a remote machine, the documented token login is intended for SSH and remote environments.

The documented CLI environment names are DREAMSTATE_API_URL and DREAMSTATE_API_KEY. Set them only in the execution environment that owns the credential and avoid placing their values in product documents.

A credential gives access within the workspace boundary, not global product authority. It does not make the key holder an owner, and it cannot grant a scope that was not assigned to the key.

After a client authenticates, it still discovers a capability’s exact schema before execution. Authentication does not bypass tool search, fetched contracts, explicit modes, or max-credit limits.

Every mutating capability must name a mode. The server does not default mutations to live, which lets a client choose smoke_test, dry_run, or live only where the selected capability supports that mode.

Use separate keys when two integrations need different scopes, workspace boundaries, or spend policies. The resulting key list makes it possible to identify which connection should be revoked when its purpose ends.

Before a client runs work, check its workspace, scopes, and spend policy. Then search for the capability, fetch its exact contract, choose a supported mode, and inspect the result in the client or Dreamstate app.

## When it goes wrong

If an integration reports an authentication failure, first verify that it is using an unrevoked key from the intended workspace. Then inspect whether the key’s scopes cover the discovered capability instead of issuing a new key without understanding the failure.

If a revealed secret is lost, do not search Context or shared messages for a copy. Revoke the exposed key and create a replacement for the same workspace and narrow scope after updating the dependent integration.

If a machine runner needs another workspace, create or use a key bound to that workspace. A machine key cannot switch, and changing an unrelated workspace key would broaden access without solving the boundary problem.

A successful setup is visible in two places: the intended key or session is listed on the API key screen, and the client can authenticate only within the workspace and scopes assigned to it.

Do not treat an access failure as a reason to reveal a secret again or grant broader access. Identify the workspace, credential type, key status, scope, and caller first, then apply the smallest credential change that addresses the verified issue.

## Agency workspaces

Source: https://www.trydreamstate.com/docs/workspace/agency

Use Agency to manage client workspace work.

Agency is the workspace area for an agency workspace and its client workspaces. Use it at /agency when you need to see clients, create a client workspace, claim an existing workspace, or move into a client workspace.

Agency work stays inside the active workspace boundary. It is separate from Context, which stores revisioned workspace knowledge, and from workspaces, members and roles, where you manage the organization that contains the work.

## What the Agency screen shows

The Agency screen is available from the sidebar only when the current workspace is an agency parent. Its main view is named Clients. It reports the number of clients and the number that need attention, and it gives you a Search clients field when the roster is not empty.

Each client entry represents a client workspace. Opening a client switches the active workspace to that client workspace, so subsequent work is performed in the selected client boundary rather than in the agency parent. Check the current workspace after switching before creating data, changing a setting, or starting an execution.

| Screen state | What it means | What to do |

| Clients | The agency roster is available for the active agency workspace. | Review the count, search by client name, or open a listed client. |

| No clients | The roster has no client workspaces yet. | Use Create new client or Claim existing workspace after checking the workspace you intend to add. |

| This workspace is not an agency | The active workspace is not an agency parent. | Switch to the agency workspace before managing clients. |

| No clients match | The roster loaded, but the search text found no client name. | Correct or clear the search text and check the roster again. |
ArchitectOpen the Agency area for the active workspace. List the visible client workspaces and attention count. Do not create, claim, unlink, or switch a workspace.

## Read client status before switching
Each visible client row contains the client name and a LinkedIn token health label. The available labels are Connected, Expiring, Expired, and Not connected. The screen pairs the label with a visible marker, so the status is not conveyed by color alone.

A roster row can also be marked as needing attention. That is a triage signal, not a statement that work has been completed or that a message was delivered. Open the client workspace and inspect its current state before deciding how to respond to a token or publishing signal.

The roster response includes the client workspace identifier, client status, token health, a pending count, a last-published timestamp, a posts-this-week value, a cadence update timestamp, and the needs-attention flag. The Agency screen itself is deliberately a lightweight roster and launcher, so use it to choose the client workspace and then inspect the relevant client surface.

| Token health label | What the label reports | Check before acting |

| Connected | The client row reports a connected LinkedIn token. | Confirm the active client workspace before relying on that connection. |

| Expiring | The client row reports a token that is expiring. | Open the client workspace and inspect the connection state. |

| Expired | The client row reports an expired token. | Do not assume an action can reach LinkedIn until the connection state is resolved. |

| Not connected | The client row reports no LinkedIn connection. | Treat connection-dependent work as unavailable until the client connects it. |

Posts this week is a trailing seven-day value in the roster data. It can be stale for up to seven days, and the cadence update time indicates when that status was updated. Use the value as a prompt to inspect the client’s current publishing state, not as a substitute for the client’s own records.
ArchitectIn the active agency workspace, inspect the client roster. Identify clients with Expiring, Expired, or Not connected token health and clients marked as needing attention. Explain what I should verify in each client workspace. Do not change any connection.

## Add or claim a client workspace
The empty state offers two distinct actions. Create new client provisions a new client workspace. Claim existing workspace adds an already existing client workspace to the agency roster. They should not be treated as interchangeable because one creates a workspace and the other changes the relationship of an identified workspace.

The app asks for a client name when you create a client. When you claim an existing workspace, identify the target client workspace and enter the confirmation name required by the claim form. The roster is refreshed after either change, so the visible client list is the first place to verify the result.

- 1
### Open an agency workspace
Select Agency in the sidebar and confirm that the workspace is an agency workspace. The screen shows a Clients heading and the current client and attention counts.
- 2
### Inspect the client roster
Use Search clients when the roster already has entries. Open a client only after checking its displayed name, then confirm the active workspace after the switch.
- 3
### Create or claim the intended client
Use Create new client for a new workspace. Use Claim existing workspace only when you have identified the existing client workspace that should join the agency roster.
- 4
### Check the receipt in the app
Return to Clients and confirm that the roster shows the expected client. If provisioning is incomplete, keep the client name and workspace identity available for follow-up rather than treating a missing row as a completed change.
Changing the client roster affects workspace access
Creating, claiming, or unlinking a client changes which workspace is managed through the agency roster. Confirm the active agency workspace and the target client identity before using those controls.ArchitectI need to add Acme Consulting as a client workspace. First inspect the active agency workspace and roster. Explain whether I should create a new client or claim an existing workspace, and show me the target before any change.

## Confirm the roster change
A successful new-client operation returns a client workspace identifier and a provisioning state. The provisioning states are provisioning, billing_pending, and active. A client can appear in the roster while provisioning is still progressing, so the name alone is not evidence that every client service is ready.

The Add Client dialog disables the create control until a non-empty client name is supplied. It disables the claim control until both a client workspace identifier and the exact workspace name are supplied. These checks prevent an empty form submission, but they do not identify the correct workspace for you.

After a create or claim action, the app refreshes the roster. Check the returned client workspace against the row that appears. If you intended to manage an existing workspace, confirm that the target workspace identifier and the typed name refer to the same workspace before you submit the claim.

| Operation | What the app collects | What confirms the result |

| Create new client | A non-empty client name. | A client workspace identifier, provisioning state, and refreshed roster row. |

| Claim existing workspace | The target client workspace identifier and its exact workspace name. | A client workspace identifier and refreshed roster row for that workspace. |

| Open client | A selected client roster row. | The active workspace switches to the selected client workspace. |

Creating a client provisions it under the agency and bills it on the agency plan. Claiming an existing workspace immediately cancels that workspace’s current subscription and re-bills it under the agency. Read the dialog text, target identifier, and target name carefully because this effect cannot be undone from the claim flow.

## Work across client boundaries carefully

An agency plan groups client workspaces under one account. The Agency screen is a roster and switching surface, not a shared store for every client fact. A client workspace remains the place where its workspace work is visible after you open it.

Keep durable positioning, decisions, and source-backed knowledge in that workspace’s Context. Keep provider credentials in Integrations. Keep membership and organization configuration in workspace settings. This separation makes it clear which client owns a fact, a connection, or a collaborator relationship.

| Need | Use this area | Reason |

| Find, create, claim, or open a client workspace | Agency | The roster is the agency view of client workspaces. |

| Save a durable client fact or decision | Context | Context is the revisioned workspace knowledge store. |

| Manage members, roles, or workspace configuration | Workspace settings | Those controls belong to workspace organization management. |

| Connect an external provider | Integrations | Provider connections are separate from agency roster management. |
ArchitectI am working for the Acme Consulting client workspace. Confirm the active workspace, then explain whether this item belongs in Agency, Context, workspace settings, or Integrations. Do not move or change anything.

## Keep agency triage separate from client work
The roster gives an agency operator a compact way to find client workspaces. It does not merge the underlying client records into a single workspace. A client’s Context, connections, and work remain scoped to the client workspace after you open it.

The attention count is useful for choosing where to look first. It does not explain the cause of the signal. An expired LinkedIn token, a publishing gap, and a client workflow question need different checks in the selected client workspace.

Search filters the loaded roster by client name. It does not discover workspaces outside the agency roster. If a client workspace is not in the roster, use the agency relationship controls only after you have identified the intended workspace.

The roster can show a last-published timestamp or no timestamp when a client has never published. Treat that absence as an observed roster value. It does not establish why no post exists, whether a draft is scheduled, or whether a provider is connected.

When you need to work on a client result, open that client first and use the product surface for the result itself. For example, use Context for durable knowledge and the client’s connection settings for provider state.

## When it goes wrong

If the app says This workspace is not an agency, switch to the agency parent workspace. The roster does not load for a non-agency workspace. If the client list fails to load, the screen shows the returned error instead of a roster. Preserve the active workspace identity and retry after the workspace connection is available.

If Search clients returns No clients match, it means the loaded roster has no client name matching the entered text. Clear the query or use the spelling shown in the roster. Do not create a second client merely because a search has no result.

If a client row is absent after a create or claim action, treat the result as incomplete until the roster refresh shows the workspace. The client service also treats a completion without a client workspace receipt as an error. Check the workspace identity and client name before retrying, so a retry does not attach the wrong workspace.

Use workspaces, members and roles when the problem is organizational access rather than the client roster. Use Context when the missing item is a client fact or decision rather than a client workspace relationship.

## Tags, comments and saved views

Source: https://www.trydreamstate.com/docs/workspace/tags-comments-views

Use workspace tags, comments, and saved views to organize shared work.

Tags, comments, and saved views are workspace-owned ways to keep shared work understandable. Use them when collaborators need a common label, a note attached to the work, or a reusable view of workspace information.

They belong to the workspace pack alongside membership, organization settings, credit information, agency work, event webhooks, callback URLs, and notification delivery. They are not Context documents, and they are not external provider connections.

## Choose the right workspace object

Start with the job, not the label. A tag identifies something across shared work. A comment records the reason, question, or handoff that collaborators need beside the work. A saved view preserves a perspective that the workspace needs to return to.

These objects remain in the workspace boundary. Before adding or changing one, check the active workspace. The same label or saved perspective can mean different things in different workspaces, so a correct name in one workspace is not evidence that it belongs in another.

| Workspace object | Use it for | Do not use it for | Check first |

| Tag | A workspace-owned label for shared work. | A durable knowledge document or an external-provider connection. | Confirm the active workspace and the item you intend to label. |

| Comment | A workspace-owned note that keeps collaboration attached to the work. | A replacement for a revisioned Context document. | Read the existing work and any current discussion before adding a note. |

| Saved view | A workspace-owned saved perspective on shared work. | A copy of the underlying workspace data or a personal external bookmark. | Confirm that the view describes the workspace and audience that need it. |
ArchitectFor the active workspace, explain whether this should be a tag, a comment, a saved view, or a Context document. Read the existing work first. Do not create or change anything.

## Keep durable knowledge in Context
Context is the workspace knowledge store. It uses Markdown documents, revisions, and attribution to the member and client that wrote a change. Put a durable positioning decision, customer fact, process rule, or source-backed conclusion there when the workspace needs to preserve the knowledge itself.

A tag can point people toward a category. A comment can explain why a specific item matters. A saved view can make a recurring perspective easier to return to. None of those roles replaces a Context revision when the team needs a durable, attributed statement of knowledge.

Use the distinction to reduce ambiguity. If a colleague needs to understand the source and current version of a decision, write or revise a Context document. If the colleague needs to find a class of work, use a tag. If the colleague needs the discussion around one item, use a comment. If the colleague needs the same workspace perspective again, use a saved view.

Context is available at /dashboard/context. Read Context for the document and revision model before moving a durable fact out of a comment or a saved view description.
ArchitectReview this workspace note. Separate a durable fact that belongs in Context from a short collaboration comment, a tag, and a saved view need. Preserve the source of any fact. Do not write or move anything.

## Make shared work readable
Use a tag for a stable shared label, not as a substitute for an explanation. A label such as “needs review” can help people locate a set of work, but it does not say who observed the issue, what evidence supports it, or what decision was made. Put that explanation in the relevant comment or Context document.

Use a comment for the local collaboration record. Before writing it, read the work it refers to and the existing conversation. State what you observed, what the team should check, and what remains unresolved. This gives the next collaborator a reason to act without forcing them to infer it from a tag alone.

Use a saved view when a recurring workspace perspective is valuable. Name the view for the question it helps answer. A saved view helps people return to the same perspective, but it does not change ownership, create durable knowledge, or connect an external provider.

When several tools seem useful, use more than one with distinct roles. For example, a team can use a tag to group work, a comment to explain an exception, a saved view to return to that group, and Context to preserve the decision rule. Each item should still be understandable when opened on its own.

| Question | Place the information in | Why |

| How do we group this shared work? | A tag | The workspace owns labels for shared work. |

| Why did the team make this local choice? | A comment | The note stays attached to the collaboration context. |

| How do we return to this perspective? | A saved view | The workspace owns saved views. |

| What is the durable sourced rule or decision? | Context | Context is the revisioned knowledge store. |

## Work with the active workspace

The workspace pack owns collaborators, membership, organization settings, credits, agency, tags, comments, saved views, event webhooks, callback URLs, and notification delivery. This ownership boundary is useful because it tells you that a workspace object belongs to the workspace that contains the collaborators and work.

The knowledge pack owns durable workspace knowledge and Context. The integrations pack owns external provider connections. Do not use a tag, comment, or saved view to imply that an outside provider is connected or that a workspace fact has been stored as Context.

Architect can use the workspace pack to understand this boundary, then discover the exact capability contract before it performs a supported action. A skill teaches practice but does not grant authority. When the exact contract is not in the current turn, Architect must search and fetch it before it can run it.

Tags, comments, and saved views do not have a documented independent credit price on this page. If a later action selects a capability, its catalog entry defines its cost policy and credit class. Check that exact capability rather than assigning a cost from the workspace label alone.
ArchitectConfirm the active workspace. Describe the workspace boundary for tags, comments, and saved views, then tell me which exact capability contract you would need before making a requested change. Do not run it.

## Prepare a clear workspace change
Before you create a label, write a comment, or preserve a view, name the collaboration question. For a tag, name the category that teammates need to recognize. For a comment, name the observation or decision that must remain beside the work. For a saved view, name the perspective that someone will return to.

Then identify the active workspace and the object that the change concerns. This avoids a common category mistake: a comment about an external provider connection belongs beside the relevant workspace work, but it does not create the connection. A Context document can explain a decision, but it does not replace the workspace object being discussed.

Finally, check for an existing tag, comment, or saved view with the same purpose. Reusing a clear shared object is usually easier for collaborators than creating a second object with nearly identical wording. If the existing object is wrong, document the distinction in Context when it represents a durable policy or decision.

| Before you change anything | Why it matters |

| Name the collaboration question. | The question distinguishes a label, a note, a recurring perspective, and durable knowledge. |

| Confirm the active workspace. | Workspace objects are scoped to the workspace that owns them. |

| Read the current work. | A tag or comment should describe the real item rather than a guess about it. |

| Check for an existing shared object. | Duplicates make a workspace less understandable for the next collaborator. |

| Separate a provider fact from a provider connection. | Integrations owns connections, while the workspace owns its collaboration objects. |

| Separate an explanation from durable knowledge. | Context owns revisioned workspace knowledge. |

A useful comment can link people to a Context document when the full decision is durable. A useful tag can identify the work that needs that decision. A useful saved view can bring the recurring work back into view. These relationships help a workspace remain navigable without pretending that all three are the same kind of record.
ArchitectBefore I organize this workspace item, identify the active workspace, the item, the collaboration question, and any existing tag, comment, saved view, or Context document that covers it. Explain the smallest appropriate change. Do not make the change.

## Use the contract before an action
Architect, the CLI, and the MCP server use the same controls for discovery and execution. An agent does not receive authority merely by recognizing a workspace term in this page.

It searches for the requested capability, reads the exact contract, and then runs only a contract delivered in the current turn. This matters for workspace organization because the exact action, inputs, mode, and result shape come from the capability contract, not from a broad label.

Search can be scoped to the workspace pack when the request concerns a workspace-owned object. The pack helps route the request, but it does not add a separate list of tools or make an unsupported action valid.

A mutating action must name a mode and the server never defaults to live. Use the returned contract to see whether the selected action supports a dry run, a live action, or another documented mode.

The result may carry a web_url for the exact object in the app. Keep the returned identifier as the source of truth, then use the link to inspect the workspace object in its app context.

## When it goes wrong

If collaborators cannot find a tag, comment, or saved view, first check the active workspace. These objects belong to a workspace, so changing workspace context can make a correct object appear absent. Do not recreate it until you have checked the intended workspace and the item it should describe.

If a comment has become the only place where a durable customer fact or decision exists, move the conclusion and its source into Context. Keep the comment focused on the local collaboration history. The resulting Context revision gives the workspace an attributed knowledge record instead of a fragile note attached to one item.

If a saved view is unclear, improve the shared question it represents before creating another one. A second view with nearly the same purpose makes the workspace harder to navigate. Check whether the existing view, tag, or comment already answers the collaboration need.

If the work actually depends on a provider connection, use the integrations surface instead of documenting the connection in a tag or comment. If it depends on membership or an organization setting, use workspaces, members and roles. Those distinctions keep workspace labels from becoming misleading operational state.

## Context

Source: https://www.trydreamstate.com/docs/knowledge/context

Context stores revisioned Markdown documents attributed to the member and client that wrote them.

Context is Dreamstate's workspace knowledge store. It keeps ordinary Markdown documents for facts about the product, buyers, competitors, and voice, so people and agents work from visible shared material rather than an invisible private memory.

Open Context at /dashboard/context when a decision or source should guide later work. Use a workbook for working rows and use tags, comments, and saved views for workspace organization, not as a replacement for a documented business fact.

## What Context holds

Each Context item is a document in a workspace wiki tree. A document has a stable identity, Markdown content, revisions, and a logical path. The application exposes Files for creating, organizing, reading, and editing visible documents, and Graph for traversing the same accessible documents and their authored Markdown links.

Write a document when the statement is meant to survive a single task: a current positioning decision, an ideal customer profile, a competitor observation, a research-backed claim, or a voice rule. Do not treat a run receipt, provider response, schedule, or analytics result as Context by itself. Those are operational evidence; Context is where the team records the conclusion it wants future work to use.

Architect uses the knowledge skill to find and use this material. The skill teaches the practice, but it does not grant authority or bind a tool. The actual work is performed through the knowledge capabilities, and every listed Context capability is free: its credit class is free and its cost policy has zero credits.

| Surface | Use it for | What you can inspect |

| Files | Writing and organizing ordinary Markdown documents. | Documents and folders that are visible to the workspace. |

| Graph | Following authored document links. | Bounded nodes and edges that use the same references as Files. |

| Search | Finding a business fact before creating another page or starting web research. | Context documents you are permitted to read, by title and logical path. |

## Find the current document before you write

Search Context before creating a page about the business. The Context search capability exists specifically for titles and logical paths, and its catalog description directs agents to search before duplicating a document or researching product, buyers, competitors, or voice. In the app, first check the document title and the revision shown on the page. That check keeps a new claim connected to the team's existing language and evidence.

Ask Architect to locate the relevant page, read its current revision, and identify what is absent. Architect uses the knowledge skill and read-only knowledge controls for this step. A read is free, has no business side effect, and is successful when it returns the permitted canonical revision with typed claims and exact source spans.
ArchitectCLISearch Context for our positioning and buyer documents. Read the current permitted revisions, summarize only what those documents say, and identify the exact document that needs a new decision.
The CLI commands above intentionally begin with tools get. The canonical surface requires discovery before execution, so the returned schema, not a guessed payload, defines the parameters for the search or read. A successful search does not mean that a document has been edited; it only confirms that the current material was found.

## Create a document and its first revision

knowledge.brain.knowledge.create_document creates a Context document and its first revision for the signed-in editor. Pass null for parent_folder_id to create the document at the workspace root. If you provide a folder id instead, it must identify an existing folder. Context documents belong in this wiki tree, not in a growth-profile Brain section.

The create call is an internal, reversible draft write. It has no provider call, no spend, and no approval system step. Use mode: "live" because a mutating call must name a mode and the server never defaults a mutation to live. The idempotency key makes a retry identifiable as the same requested creation, rather than a reason to manufacture another Positioning page.
ArchitectCLICreate a root Context document named Positioning. Record only the current product statement and its source. Use the saved document id in your result, then read the document back.
Check the Files view after the call. You should see the document at the intended root or folder path, then use its stable document id rather than its title for later reads and revisions. The operation is free, and the useful completion signal is the saved document and revision receipt, not merely a generated paragraph.

## Save against the revision you read

knowledge.brain.knowledge.save_revision saves a new revision only when its expected_document_revision matches the current document. This is how you save attributed revisions safely: read the exact revision, make a focused update, then save against that revision instead of silently replacing an intervening editor's work.

The history capability reads bounded revision metadata for one document. The revision comparison capability compares two revision coordinates, including revision number, content object, and content digest, but it does not compute a text diff. Use that distinction when investigating a change: history tells you which revisions exist, while a comparison checks their coordinates.
ArchitectCLIRead the current Positioning revision. Add the buyer decision with its source, preserve the existing content, save against the revision you read, then read the resulting revision and report its number.
Architect should use the knowledge skill for the writing practice and the context read and save capabilities for the change. In the app, verify the revised Markdown and revision number before relying on it in a workbook, sequence, or visibility analysis. Saving a revision is free and internally reversible, but it changes the shared document, so accuracy matters more than speed.

## Organize documents and recover a removed page

Folders are editable workspace objects. You can create a folder at the root by omitting its parent, passing null, or passing an empty string. Move operations use exact folders and current revisions. Renaming a document preserves its stable identity and revision bindings; renaming a folder rewrites its logical path and every descendant path.

Removing a document is recoverable. knowledge.brain.context.remove_document moves a document into its removed lifecycle state, and list_removed lists documents still inside retention for restoration. restore_document restores an archived document against its current revision. This gives a team a recovery path when a page was moved aside by mistake.

Permanent delete cannot be undone
knowledge.brain.context.delete_document irreversibly deletes an already archived document against its current revision. A folder delete is also irreversible and only applies to an editable folder with no child folders or live documents. Inspect the archived object and its revision before using either destructive operation.
These operations remain free, but the permanent-delete effect is not reversible. When a document should continue to guide work, prefer a new revision or a recoverable removal. When it should move, use a move operation with the document's current folder and revision rather than recreating it elsewhere.

## Read links, revisions, and permitted exports

Context has separate read operations because each answers a different question. get reads one permitted canonical revision, including typed claims and exact source spans. history reads bounded revision metadata for one document. diff_revisions compares revision coordinates, while backlinks reads committed incoming wiki links to one destination.

Use graph when the question is about a bounded relationship between Context nodes and edges. It uses the same node references as Files. Use browse when the question is what persisted nodes sit under one exact parent. Neither read operation fabricates children or links that are absent from the workspace.

The export operation produces the Context documents you are permitted to read as canonical Markdown with source attribution. It is a read-only, side-effect-free operation. An export never grants a caller access to a document they are not permitted to read, and it should not be treated as a substitute for reading the current revision before editing.

| Question | Context operation | Result |

| What does this document currently say? | knowledge.brain.context.get | One permitted canonical revision with typed claims and source spans. |

| Which revisions exist? | knowledge.brain.context.history | Bounded metadata for one document node. |

| Which pages link here? | knowledge.brain.context.backlinks | Permission-filtered incoming links with stable keyset pagination. |

| What can leave as Markdown? | knowledge.brain.context.export | Permitted documents with source attribution. |

All four reads are free. In the app, start with Files when you know the page and use Graph when the relationship matters. In Architect, ask for the question you need answered and name the document or folder; it should choose the read capability whose result matches that question, then report the returned document identity or revision.
ArchitectCLIRead the current Positioning document, list the revisions available for it, then report which Context documents link to it. Do not change any Context document.

## When it goes wrong
If the needed page appears to be missing, search by title and logical path before creating a replacement. If it exists in a different folder, move it against its current revision. If another editor saved a newer revision, read the current document again, preserve the newer content, and save a merged revision against the revision you just read. Do not use a stale expected revision as if it were current.

If a linked page cannot be understood, inspect the graph or read the document directly. Backlinks answer which committed incoming wiki links point to one Context document, while knowledge.vault.link_resolve is the distinct operation for changing one unresolved wiki link to a chosen record. If an export omits a page, it exports only the Context documents the caller is permitted to read with source attribution, so check the document's access and publication state rather than assuming the Markdown was lost.

If removal was accidental, list removed documents and restore the correct archived document against its current revision. If someone needs permanent deletion, confirm that the document is already archived and that the selected revision is the intended one. Context has no credit charge for these actions, but the irreversible delete behavior makes verification essential.

A document that was renamed retains its stable identity and revision bindings, so use its document id when troubleshooting a link or a stale title. A moved folder can change logical paths for every descendant. Check the Files location after either change, then read the document again before using it as evidence in another workflow.

Do not repair a broken reference by inventing a replacement page. The documented recovery path is to search, browse, read the current revision, and restore an archived document when appropriate. These reads are free and side-effect-free, so they are the safe first response to uncertainty.

If Context is empty, report the fact that is missing and its needed source. Do not substitute a generated statement for verified workspace knowledge. A later editor can create the document once there is a source worth recording.
ArchitectCLIThe Positioning update did not save because the document changed. Read the current revision and history, preserve the other editor’s changes, write a merged revision against the current revision, and report what changed.

## Skills

Source: https://www.trydreamstate.com/docs/knowledge/skills

Skills teach practice and do not grant authority or bind tools.

Skills are editable Markdown playbooks for people and agents. Use a skill when you need a repeatable practice, such as research, workbook building, writing, or diagnosing a failed run.

A skill is guidance, not authority or permission. It grants nothing, binds no tool, and does not change permissions, so an agent still discovers the exact capability schema before it runs work.

## Skills in the catalog

The catalog contains these skill ids. Start with skill-authoring when you need to create or edit a workspace skill.

| Skill id | Use |

| knowledge | Guidance for this named practice. |

| list-building | Guidance for this named practice. |

| outreach | Guidance for this named practice. |

| social | Guidance for this named practice. |

| linkedin-posts | Guidance for this named practice. |

| x-posts | Guidance for this named practice. |

| reddit-posts | Guidance for this named practice. |

| visibility | Guidance for this named practice. |

| workflows | Guidance for this named practice. |

| writing | Guidance for this named practice. |

| inbox-replies | Guidance for this named practice. |

| plays | Guidance for this named practice. |

| first-win | Guidance for this named practice. |

| diagnostics | Guidance for this named practice. |

| worksheet-tidy | Guidance for this named practice. |

| crm | Guidance for this named practice. |

| linkedin-warm-signals | Guidance for this named practice. |

| skill-authoring | Create and edit a workspace skill. |

## Read a skill before editing it

Search the catalog before you create a new skill. Read the matching skill, its Markdown, frontmatter, supporting pages, and current revision. A supporting page is only needed when the task needs that detail.
ArchitectFind the skill that best covers qualifying a worksheet. Read it and summarize its practice. Do not edit it.

## Write a useful skill
A useful skill has one thesis line, an invariant, a short numbered practice, guardrails, and a clear return. Keep SKILL.md near 5 KB and place detail, examples, and edge cases in supporting pages when needed.

Before saving an edit, read the current revision. Change only what was requested, preserve the required frontmatter, then read the saved result. If another editor saved first, re-read and merge rather than sending the older text over their revision.
ArchitectSearch for an existing skill about pricing objections. If none covers it, explain the proposed skill id, thesis, guardrails, and verification before creating anything.

## When it goes wrong
If a search finds an existing skill, add the needed section there instead of duplicating the practice. If an edit descriptor is unavailable for a starter skill, wait for its workspace copy to appear and read the catalog again. If a revision conflicts, re-read the current text and merge the requested change.

Architect should use skills_list or skills_get to inspect guidance, then use tools_search and tools_get to find exact schemas. Search can return runnable contracts, and a run is refused as capability_not_fetched if the contract was not delivered in the current turn.

If a skill changed after it was read, re-read the current Markdown and merge the requested update. Do not overwrite a collaborator’s revision with an older local copy or create a duplicate practice.

A good skill update is visible in the skill catalog or workspace copy, retains required frontmatter, names a concrete practice and guardrails, and points the user to actual evidence for verification.

If a skill names an old pack or stale workflow, use the current product pack and canonical capability contract. The catalog is the authority for executable work, while the skill remains a source of practice guidance.

Read the current source before correcting guidance. Preserve the task-specific practice and link it to the current capability authority.

## Choose guidance, not permission

The declared catalog has eighteen skill ids. A skill is a Markdown practice with its SKILL.md and, where needed, supporting Markdown pages served through skills_list and skills_get.

Skills describe how to work, not what an account may do. A skill neither grants permission nor binds a tool, and capability authority remains in the active customer-facing catalog.

The knowledge skill covers the practice of durable workspace knowledge. It should direct an agent toward visible Context documents rather than an undocumented private memory.

list-building is named Workbook building in the skill catalog. Lists happen only inside a workbook, with worksheets, one row source per worksheet, enrichment and judging columns, and an optional score.

The outreach skill teaches sequence building. Sequence steps are separate from sending: a sequence can be drafted, validated, published, enrolled, started, delivered, and replied in distinct stages.

The social, linkedin-posts, x-posts, and reddit-posts skills support social practice. They do not turn a draft into a publish action or bypass the relevant social capability contract.

The visibility skill teaches measurement discipline. It keeps citation and rank evidence, provider coverage, windows, and completeness separate rather than treating a bounded result as a universal score.

The workflows skill concerns deterministic automation graphs, triggers, conditional actions, runs, failures, replay, and metrics. It is distinct from sequence cadence and authoring.

The writing skill helps an agent shape content. It does not promise a system spending confirmation or publish authority, because credit limits and explicit capability choices govern paid work and effects.

inbox-replies guides a reply in an existing conversation. It is distinct from net-new outreach, and a draft reply does not send an external message.
ArchitectList the skills that match this task. Read the best matching skill and explain its practice, boundaries, evidence to check, and the capability pack that owns the actual work. Do not run a capability.

## Use a skill with the contract
The plays skill points users to the blueprint catalog play list. Choose by stage and needs against real workspace state, then inspect every ordered capability rather than treating the skill as a second catalog.

first-win focuses on setting up Context, sourcing, a workbook, a worksheet, a sampled row-source run, evidence, and a score. It is a practice for early work, not an automatic campaign.

diagnostics helps investigate a failure from actual receipts, state, and capability results. It should not invent a cure when the evidence only shows a missing credential, connection, or prerequisite.

worksheet-tidy focuses on repairing worksheet quality. The workbook remains the home of list work, while canonical CRM truth belongs to the CRM surface.

The crm skill concerns canonical CRM records. It must not describe a system confirmation for spend, because credit ceilings and runtime quotes are the product mechanism for consent to paid work.

linkedin-warm-signals supports a warm-network practice. It should not call a non-existent pack; the corresponding product pack ids have defined boundaries.

skill-authoring is the featured practice for creating or editing a workspace skill. It directs the author to inspect current content, frontmatter, supporting files, and revisions before saving focused changes.

Before work changes shared state, check the current app object, exact capability schema, mode, credit policy, and result. The skill gives the method; the discovered contract determines the call.

## Notes, inspiration and bookmarks

Source: https://www.trydreamstate.com/docs/knowledge/research

Use research screens for notes, inspiration, and bookmarks.

Research is the working area for notes, inspiration, and bookmarks. Open Notes at /dashboard/ideas when you need to capture an early idea, revisit a shared idea, or gather material before turning it into a post.

Research is adjacent to, but different from, Context. Context holds durable workspace knowledge with revisions and attribution. Research holds the working material that helps you decide what belongs in Context, what should remain an idea, and what is ready to become a draft.

## Use the research surfaces

The sidebar groups Notes, Inspiration, and Bookmarks under Research. Notes opens the Ideas screen. Inspiration has Discover and Templates entries. Bookmarks has Posts and Channels entries. These areas serve different kinds of working material, so choose one based on what you are trying to inspect.

The Ideas screen has My ideas and Team library tabs. My ideas is your working list. Team library contains ideas shared with the workspace. A private idea does not appear in the team list until it is shared, and an idea shared with the workspace remains an idea rather than becoming a draft or a published artifact.

| Research area | Where you see it | Use it for | Check before moving on |

| Notes | /dashboard/ideas | Create and shape ideas before converting them into posts. | Open My ideas and read the idea row before turning it into another artifact. |

| Team library | /dashboard/ideas | Read ideas that were shared with the workspace. | Check the sharer, shared time, stage, and current workspace. |

| Inspiration | Research navigation | Open Discover or Templates from the Inspiration menu. | Treat inspiration as input to a decision or draft, not as a sourced company fact. |

| Bookmarks | Research navigation | Open saved Posts or Channels. | Read the original saved material before carrying a conclusion into Context or a draft. |
ArchitectInspect the active workspace research areas. Tell me whether this material is an idea, shared team research, inspiration, a bookmark, or durable Context knowledge. Do not save, share, draft, or publish anything.

## Capture and shape an idea
The Ideas screen is labeled “Create and shape ideas before converting them into posts.” Use Add idea to capture an early draft that is not in the posting calendar. The My ideas table shows an idea name, campaign, status, labels, and creator. Opening a row takes you to that idea’s detail route.

Adding an idea is a workspace action with no model call and no publish time. The capability social.content.ideas_add saves a content idea to the ideas list. It is not a draft generator and does not itself schedule or publish content.

Use social.content.ideas_list to read parked ideas in the current workspace. Its result is cursor-paginated. It does not generate a draft and does not list published content artifacts, so an empty ideas result does not establish that the workspace has no published posts.

The screen search filters the visible ideas by the loaded list. Search helps you locate an existing idea before adding another one. Read the title, campaign, status, labels, and creator to decide whether you should edit the existing work or capture a distinct idea.

| Capability | What it does | Cost policy |

| social.content.ideas_add | Saves a content idea on the ideas list. | No model call and no publish time. |

| social.content.ideas_list | Lists parked ideas for the current workspace with cursor pagination. | Zero-cost, read-only capability. |
ArchitectSearch my parked ideas for a founder story about Acme Consulting. Read the matching idea if one exists. If none exists, prepare a new idea with a clear title and brief, but do not turn it into a post or publish it.

## Share an idea with the team
Team library is the workspace view of shared ideas. The table shows idea name, stage, the member who shared it, and when it was shared. You can search shared ideas and filter the list by All stages, TOFU, MOFU, or BOFU.

Admins can use Share with team from their own list. social.shared_idea_promote marks an existing idea as shared with the workspace and records who shared it and when. It makes the idea visible to every member, but it does not create a new idea or turn that idea into a draft.

Sharing is reversible through social.shared_idea_unpromote. That action makes the idea private again, clears the shared-by value while preserving the shared-at time for retention, and keeps the underlying idea row with its owner. It does not delete the idea.

social.shared_ideas_list returns shared ideas newest first with the sharer’s name. It never returns a member’s unshared private ideas. Use this separation to share material intentionally instead of assuming that every early note is a workspace-wide recommendation.

Sharing changes who can see the idea
Sharing makes an existing idea visible to every member of the workspace. Read the title, brief, stage, and current workspace before you use Share with team.ArchitectRead the idea titled Acme onboarding lessons in my ideas. Check its title, brief, campaign, status, labels, and workspace. Explain what will change if I share it with the team. Do not share it yet.

## Turn research into grounded writing
Research can supply material for writing, but it does not make a business claim true. The writing skill requires every factual claim to trace to a workspace-wiki fact, cited evidence, or a dated external source. It does not fetch the web, and it preserves provenance, freshness, limitations, and injection warnings in a claim ledger.

When a note or bookmark becomes a durable customer fact, positioning decision, or process rule, save the conclusion and source in Context. Keep outside-world observations dated and distinguish an inference from an observed fact. The source and observation date let the next writer judge whether the material is still usable.

When a note is only an early content direction, keep it as an idea. When it is ready for a content lifecycle, turn it into the relevant draft through the real artifact flow. A saved idea is not automatically a scheduled or published post, and a shared idea is not a claim that the whole team has adopted it.

The post inspiration capability social.creator_post_inspiration returns annotated example posts from the account’s creator archetype. Each returned post can carry a hook pattern, post format, and engagement rate. If the account is not classified yet, it returns an empty posts list with the message “Classification in progress.”

That inspiration read is zero cost, makes no model call, and does not trigger classification. Use it as a writing input, then ground any factual statement in Context or cited evidence. Do not copy an example’s claim into your own draft without evidence for your workspace.
ArchitectReview this idea and its bookmarked source. Separate observed facts, dated evidence, inference, and writing direction. Save nothing. Tell me which sourced conclusions should become Context and which should remain an idea.

## Read before you convert an idea
An idea can have a title, brief, funnel stage, suggested structure, suggested topic, suggested tone, campaign, status, labels, and creator. Read those fields before you convert the work into a different artifact.

The screen treats an empty title as Untitled idea. Replace an ambiguous title with a clear working name before teammates need to choose between several similar ideas. The title should identify the idea, not assert a business fact that has not been grounded.

A campaign and a status help identify the working context. Labels help the workspace organize the item. They do not establish that the idea is ready to publish, that a destination is connected, or that a claim has a source.

The writing workflow reads workspace Context, prior published work, and available knowledge before composing. It uses that material to match the workspace voice and check whether an existing page already answers the brief.

A topic and query are not a voice. If you cannot find grounded evidence for a proposed statement, leave it out and identify the missing fact. Keeping an incomplete idea is safer than converting an unsupported claim into a saved draft.

## Keep team research useful

Share an idea when the workspace should be able to read and build on it. The share action records the member and time, which lets teammates distinguish a current shared item from an owner’s private working list.

Use the funnel-stage filter only as a view of shared ideas. It supports All stages, TOFU, MOFU, and BOFU. It does not alter the idea or create a new draft.

Before sharing, remove material that should remain private to the idea owner or move durable claims into Context with their source. The team library makes the existing row visible; it does not create a separate redacted copy for the workspace.

When an idea should no longer be team-visible, unpromote it. The row is retained with its owner, while shared visibility and attribution fields are cleared. Check the team library and My ideas after the change.

Research becomes useful when a teammate can tell what the material is, who shared it, what evidence supports it, and which next lifecycle is appropriate. A list of titles without those checks is not a writing brief or a substitute for Context.

## When it goes wrong

If My ideas fails to load, the Ideas screen reports Failed to load ideas. If Team library fails, it reports Failed to load team library. Confirm the active workspace and retry the read when the workspace is available. Do not create a replacement idea merely because the list has not loaded.

If a search returns no result, the search only says that no loaded item matches its text. Clear the query, check the correct tab, and inspect the current workspace before deciding that the idea does not exist. Private ideas are absent from Team library by design.

If the Team library is empty, the screen says No shared ideas yet. That does not mean the workspace has no private ideas. It means no ideas have been promoted into the team-visible library. Use My ideas to inspect your own list, and share only an idea that the workspace should see.

If inspiration returns Classification in progress, wait for the account classification state instead of treating the empty example list as a content recommendation. If evidence for a business claim is missing, keep the claim out of the draft and identify the source needed for Context.

Use Context for durable facts and revisions. Use social posts and publishing when an idea is ready for the separate draft, schedule, or delivery lifecycle.

## AI visibility and analytics

Source: https://www.trydreamstate.com/docs/knowledge/visibility

Use AI visibility analytics to measure business content evidence.

AI visibility measures how your business content is seen in search and generative answer engines. Open the AI Visibility screen from the dashboard to inspect stored measurement evidence, then use Context for the business facts that explain the result.

Citation measurement and rank tracking answer different questions. Keep their source, date window, provider coverage, and completeness separate, rather than turning a partial measurement into one health score.

## Read stored evidence first

| Capability | Returns | Credits |

| visibility.overview | A bounded overview of visibility, citation coverage, rank, share of voice, engines, sentiment, brand, and evidence. | Free |

| visibility.citations | Cited domains, citation events, pages, competitor differences, source gaps, and evidence. | Free |

| visibility.refresh | A new asynchronous citation collection pass. | 0.31 credits per call |

The overview and citations reads are provider-bounded and truncated. Treat them as bounded samples, not a census, and use a refresh only when new collection is needed for the decision.
ArchitectRead the current AI visibility overview and citation evidence. Keep citations, ranking, sentiment, and referral evidence separate. Report the window, provider coverage, completeness, and limitations.

## Interpret the measurement
For one prompt, visibility is citations or qualifying mentions divided by eligible completed runs for that prompt, engine set, locale, and window. Preserve the completed-run count, citation count, and percentage together. Zero citations across zero completed runs means the measurement is unavailable, not zero percent.

Compare equal-length windows and do not silently merge engines, locales, or time windows. A recommendation is an inference until a later comparable measurement shows a change.

## Refresh only when you need new evidence

A refresh collects citation data for the workspace and returns an accepted asynchronous result with the workspace id, queued query count, credit ledger id, provider receipt, receipt, and graph effects. Read the terminal evidence after the queued work finishes before reporting a result.

Refreshing spends credits
The refresh reserves and settles geo-probe credits against the workspace budget. Check the current evidence before starting a new collection pass.ArchitectExplain whether the current visibility evidence is sufficient for this decision. If it is stale or incomplete, tell me that a refresh costs 0.31 credits and what result I should wait for.

## When it goes wrong
A missing connection, stale window, queued scan, empty denominator, or unavailable provider data is a limitation to report. Correct the scope, wait for terminal evidence when work is queued, or state what connection or evidence is missing. Do not claim that a recommendation improved visibility until a comparable later measurement shows it.

A recommendation becomes a measured change only after a later comparable run. Preserve equal-length windows and matching engine and locale scope, then state whether the later evidence actually changed.

If a scan is queued, wait for terminal evidence before reporting a result. An accepted queue receipt proves that collection was scheduled; it does not prove that the requested citations or rankings were found.

An empty or truncated response is a limitation to name. It may represent a bounded sample, provider coverage gap, incomplete collection, zero eligible runs, or a different scope from the question being asked.

A successful read has a result with evidence and its measurement bounds. A successful refresh has terminal evidence that can be read and compared, not only an asynchronous acceptance receipt.

When numbers disagree, re-read the result and compare prompt, engine set, locale, window, completed runs, citation count, provider coverage, and completeness before reporting an improvement or decline.

## Read before refreshing

The dashboard sidebar opens AI Visibility at /dashboard/aivisibility. Use the screen to inspect stored evidence before asking for new collection or turning an observation into a recommendation.

Visibility is a knowledge-layer pack. It owns analytics, attribution, SEO, share of voice, competitor evidence, brand presence, AI answer-engine citations, meetings, and feedback about how business content is seen.

Visibility does not own social post creation, provider connection setup, or a new people or company list. Use Social for posts, Integrations for credentials, and Tables for a working list.

The overview read is free and read-only. Its bounded result includes visibility, citation coverage, rank, share of voice, engines, sentiment, brand, and evidence, so it is useful for describing what was measured rather than making a promise.

The citations read is also free and read-only. It returns cited domains, citation events, pages, competitor differences, source gaps, and evidence, which makes the underlying observation inspectable.

A measurement needs its window, engine set, locale, completed-run count, and denominator. Do not compare a narrow provider window with a wider multi-engine window as if they are the same measurement.

For a prompt, visibility uses citations or qualifying mentions divided by eligible completed runs for the selected prompt, engines, locale, and window. A zero denominator means the result is unavailable, not a zero-percent performance claim.

Citation measurement and rank tracking answer different questions. Keep them separate together with source, date, provider coverage, and completeness, rather than flattening partial evidence into one health score.

A refresh is an asynchronous collection pass. Its accepted result carries the workspace id, queued query count, credit ledger id, provider receipt, receipt, and graph effects, but the useful evidence arrives only after the queued work reaches terminal state.

The refresh capability has a dynamic credit cost in the catalog and the current page documents 0.31 credits per call. Treat that number as a quoted credit effect for this capability, not as a price for every visibility operation.
ArchitectRead the current AI visibility overview and citations. Report the exact measurement window, engines, locale, coverage, completeness, and denominator. Do not refresh unless the current evidence cannot answer the decision.

## Cost and comparison
Paid live work uses a quote when the runtime needs a price. Keep the returned estimate and rerun the same parameters with an unchanged max_credits ceiling, because changing the request invalidates the quoted work.

A mutation must state its mode. smoke_test inspects static schema and policy without writes or audit records, dry_run previews against workspace state without business writes, provider spend, or outward action, and live executes.

Ask Architect to read the current overview and citations before it proposes a refresh. Architect uses the visibility skill for measurement practice and canonical discovery controls for the actual capabilities.

When evidence changes a durable claim about the business, record the conclusion and source in Context. Context is the workspace knowledge store; visibility evidence remains measurement material with its coverage and limitations.

A provider can require the workspace’s own connection or key. If provider evidence is unavailable, report the missing connection or unavailable data rather than inventing a citation, rank, or competitor result.

Check the evidence in the AI Visibility screen after a terminal result. A reading is useful only when its bounds travel with the number, and a paid refresh is useful only when it addresses a specific evidence gap.

## Workbooks and worksheets

Source: https://www.trydreamstate.com/docs/data/workbooks

A workbook contains worksheets, each with one row source, columns, and optional score.

A workbook groups the worksheets you use to make one operating decision, such as qualifying companies and then finding people at those companies. Use it when a list needs evidence, not just a search result. In the app, open Workbooks at /dashboard/workbooks; then use row sources to land rows, columns to evaluate them, and cells and provenance to check the outcome.

Architect uses the list-building skill for workbook work. It starts from the outcome, required and nice-to-have criteria, and disqualifiers, then builds and reads a small sample before it scales. That order keeps the workbook useful for a founder or GTM operator who must explain why every row belongs.

## Understand the workbook and worksheet model

A workbook is the container. A worksheet is the working surface inside it: it has one row source, rows from that source, columns that expose or derive evidence, and an optional score. A row source is not shared across worksheets. Keeping one source per worksheet makes the origin of a row inspectable when the source or its filters change.

Use separate worksheets when the row kinds are different. For example, a Companies worksheet can prove a hiring or funding signal, while a linked People worksheet can hold the people to contact at qualifying companies. Do not put a person name in a company cell. People are rows in the People worksheet, with a link to the company row that supplies the qualifying evidence.

| Part | What it holds |

| Workbook | Groups worksheets that support one operating decision. |

| Worksheet | Holds one row source, rows, columns, and an optional score. |

| Row source | Brings the base rows into one worksheet. |

| Column | Shows source data or answers one declared question for rows. |

| Cell | Carries a value, its state, and its evidence trail. |

Architect can read the current workbook and worksheet records before it changes anything. The workbook list returns headers rather than worksheets or row counts. The worksheet list is scoped to one workbook, returns worksheets in workbook_position order, and also does not return columns, rows, or counts. Those reads are free and read-only.
ArchitectRead my workbooks. For the Regional outbound pilot workbook, list its worksheets and explain which row set and decision each one supports. Do not create anything yet.

## Create the right starting shape
Creating a workbook always creates its first worksheet in the same operation. The first worksheet is required, so there is no empty workbook state. The operation can also create worksheet columns and rows in the same all-or-nothing call, but it attaches no row source and starts no run. Its policy is a free, internally reversible draft write.

The creation result includes workbook_id, worksheet_id, and table_id. The worksheet and table identifiers are the same UUID at this point. Keep the returned table_id: later column, row, and cell operations use it. The result also includes created column keys and ids, row ids, a default view id, and workbook and first-worksheet records.

To add a second worksheet, use the worksheet creation capability against the existing workbook. It creates only the worksheet, with no columns, source, or rows. The returned record includes its workbook position, name, row kind, description, timestamps, creator, and archive state. That is also a free, internally reversible draft write.
ArchitectCreate a workbook named Regional outbound pilot with a Companies worksheet. Add a People worksheet only because the contacts will be researched separately from company qualification. Leave both worksheets without sources until you show the sourcing plan.
Creation does not fetch or spend

Creating a workbook or empty worksheet does not attach a row source, fetch rows, or run enrichment. Source and column runs can have their own credit effects. Check the planned route and the finished run before claiming a charged amount.

## Design the data chain before running it

Start with four facts: the list purpose, what makes a row qualify, what disqualifies it, and which criteria are required rather than nice to have. Architect reads the request and saved company context, then turns intent into observable evidence. A vague term can have broad and narrow readings, so resolve that difference before choosing a source.

Choose the source that can carry the scarcest criterion or strongest signal. Put each stated criterion into the source input that supports it. A place belongs in a location filter, a title belongs in a title filter, and a size belongs in a size filter. A criterion left out of the inputs is not applied. A guessed filter value can still return rows, which is why a successful run is not proof that the rows are correct.

When the qualifying signal lives on a company but the outcome is outreach to people, plan both worksheets from the beginning. First sample companies that carry the signal. Then use the company rows to find people, preserving the company link. The title a company is hiring for belongs on the company search; the titles of people to contact belong on the people search. Mixing those roles can produce an apparently successful but incorrect result.

Build one layer at a time. Attach and sample the source first. Next add catalog enrichments and judgments that decide qualification. Add derived formulas, projections, or scores after the evidence they use exists. A derived column before its input has nothing to show and hides whether the earlier step worked.
ArchitectPlan the Companies and People worksheets for a regional outbound pilot. Show the required criteria, disqualifiers, source route for each worksheet, fields that prove each criterion, and the small sample to inspect before any wider run.

## Sample before you scale
A first batch is a sample to review, not a finished list. The list-building skill uses a small sample of about twenty-five rows, reads the entities, and can compare two or three parameter variants before retaining the most precise one. The goal is for most sampled rows to be right at the source, rather than relying on expensive downstream checks to repair a broad search.

After a source or column run starts, follow it until it finishes and read the cells it wrote before adding the next layer. A status read that times out does not change the run and does not prove failure. A queued or running run should be read again rather than restarted. When the sample is correct, scale the same source to the requested count. If no count was stated, the skill uses 100 rows as its default target.

Cost control comes from sequence. Use cheap and selective evidence before expensive contact data. Run paid lookups only for rows that passed the qualifying column. An estimate is a ceiling, while the amount charged is read from the finished run. A count observed before a run finishes is unknown, not zero.
ArchitectRun a small sample for the Companies worksheet. Read the landed rows, show which required criteria each row meets, and compare any imprecise filter values before proposing a larger run. Do not enrich contact data until the sample qualifies.

## Read the workbook back
A write is a request. A read back is the evidence that the request produced the intended result. Do not report a worksheet as landed, enriched, judged, or scored until the relevant run is finished and the worksheet has been read. Counts alone are insufficient because a computed count can still be unknown.

| Check | What to verify |

| Purpose | The worksheet name names a distinct row set and decision. |

| Criteria | Every required criterion is visible on the row. |

| Source | One attached source supplies the base rows. |

| Sample | Landed rows were read after a completed run. |

| Evidence | Empty, failed, and answered cells remain separate. |

Read representative rows in full. Report answered, empty, and failed cells separately. An empty or failed value is not zero, and a missing provider answer is unknown rather than false. Do not copy a value from a similar row to fill a missing one. Let the column run settle the cell so the evidence trail remains intact.

Before calling the work complete, confirm the source run, landed count, duplicate count, and enrichment runs. Read at least three rows in full, inspect empty cells in key columns, and check duplicates on the identifier that defines the entity, such as a company domain or person profile URL. If the user asked for people, confirm that the linked People worksheet exists and holds rows from qualifying companies.

Use the diagnostics skill when a result is unexpected. Queued, paced, capped, and unknown states are not automatically failures. An empty, failed, or unrelated cell can indicate a missing input, wrong field reference, or wrong setting. Correct that cause and recheck the sample, rather than claiming that a run alone proved the result.
ArchitectRead the completed sample in the Companies worksheet and the linked People worksheet. Report the exact landed and duplicate counts when available, three representative rows, empty cells, failed cells, and the next dependency that must be fixed before scaling.

## When the model does not match the work
If Architect cannot create a workbook because a required first-worksheet value is missing, correct the workbook request rather than retrying an unchanged call. The contract records an example refusal for an optional first_worksheet.declared_mixed_row_kinds value sent as null: optional values that are not being set should be omitted. A malformed request can also hide a later mode error, so fix the capability input first.

If a planned source cannot run because an account is missing, keep the workbook and source binding. Missing credentials block the run, not workbook or source authoring. If the rows are broad, wrong, or empty, inspect the source inputs and landed sample before adding columns. Do not create a duplicate worksheet merely to retry a filter.

If two worksheets carry the same entity and decision, consolidate the plan before continuing. A Companies worksheet and People worksheet are different because their rows and source chains are different. Two company worksheets with the same source and criteria create competing evidence trails and make later readback ambiguous.

Archive is not deletion. An archived workbook drops out of default lists, while its worksheets, columns, rows, and cells survive; a list with archived records included can still find it. There is no workbook unarchive capability in this family, so read the workbook before archive if you need its current state. Use archive only when retiring the whole workbook is the intended outcome.

- Read a workbook record when you need its metadata but not its worksheets or counts.
- Read the workbook overview when the workbook and its worksheets are both needed.
- Read the worksheet list before a worksheet-specific change resolves its identifier.
- Read cells after a finished run when the result, rather than the request, matters.ArchitectInspect this workbook request and its worksheets for missing required values, duplicate row sets, or an unbound source. Keep valid built objects. Tell me the smallest correction and then read the affected worksheet after it runs.

## Row sources

Source: https://www.trydreamstate.com/docs/data/sources

A worksheet uses one row source to provide its working rows.

A row source is the saved route that brings base rows into one worksheet. Use it after you can state what a row must prove, before you add columns that judge or enrich it. In Workbooks at /dashboard/workbooks, the source is the evidence boundary for how a row entered the worksheet.

Each worksheet has one row source. Put a different row type or search chain in another worksheet in the same workbook. A source brings rows in; cells record the values and states that result, which you inspect on cells and provenance.

## Choose and attach a source

Use tables.findable_catalog.list for the compact source list: id, label, produces, pricing, readiness, and when to use it. Pass definition_id to read one source's inputs and output fields, then add it with tables.table_sources.attach. When the user provides a LinkedIn search URL, attach provider.linkedin.people.search_by_url with raw_search_url set to that URL. Use provider.linkedin.people.search only when building a search from words. Do not pass columns to copy source fields; reference {{source_key.field}} in prompts and formulas.

Architect uses the list-building skill to begin with purpose, qualification evidence, disqualifiers, and the distinction between required and nice-to-have criteria. It chooses the route that can carry the scarcest criterion or strongest signal. Intent is not itself a source field, so Architect translates it into observable evidence before choosing a route.

Put every stated criterion into the source input that supports it. A location is a location filter, a title is a title filter, and a size is a size filter. A criterion omitted from source inputs is not applied. A guessed filter value may not fail, but it can return the wrong rows, so plan output and a landed sample both need inspection.

For hiring intent, the plan starts with qualifying company rows and then follows with people at those companies. The people follow-up projects current title, person location, and profile URL. Keep the company hiring role separate from the titles of people to contact. Passing person titles as a company hiring role can return companies hiring the wrong role.
ArchitectPlan a source for an Operations Leaders worksheet. The people must be in California and work at companies with an observable operations signal. Show every route, which request filters it applies or drops, required inputs, source fields, estimate, and the first sample to read. Do not attach or run a source.

## Attach the exact planned binding
tables.table_sources.attach binds one provider fetch, canonical producer, or CSV file to a worksheet. Attachment writes the binding row only. It fetches no rows and spends no credits. The operation is a free, internally reversible draft write, so a missing connection does not prevent you from authoring the worksheet and its source.

Attach the plan route's exact binding_spec, including its definition_id and input_bindings. Do not attach an empty binding. The attach response lists available_output_paths for every field. field_guidance names a few relevant {{source_column_key.field}} references. Pass paths in columns only when the caller wants them as their own formula columns. Omit columns and only the source column is created. project_fields does not add columns.

The response is the full source record, not a signal that rows landed. It includes source_id, workspace and table ids, source column and tool ids, output row kind, the canonical upsert key, binding, state, frontier, timestamps, and archive state. Use tables.table_sources.list, a free read-only capability, to inspect sources bound to one worksheet before replacing a binding.

| Returned field | What it lets you inspect |

| source_id | Identifier for the attached source record. |

| table_id | Worksheet table that owns the source. |

| binding | Saved executable definition and input bindings. |

| state | Current source state. |

| frontier | Revision, watermark, and last update time for progress. |

| canonical_upsert_key | Key used for canonical source upserts. |
ArchitectAttach the selected plan route to the Operations Leaders worksheet using the plan binding exactly. Project name, role, location, company evidence, and profile URL only when the route exposes them. Read the saved source record and stop before running it.

## Preserve the one-source boundary
A worksheet has one row source. When the current worksheet is named by the user or is the active canvas, treat it as the target and add requested columns there. Do not create an empty workbook or worksheet merely because a source needs more work. Create another worksheet only when the request needs a new list or a distinct row type.

For a companies-then-people plan, keep the source chain visible. The company worksheet receives the qualifying signal. The people worksheet uses the company input named by the plan, so every person can remain linked to the company evidence. For people at companies already on a company worksheet, use the find-people action on that worksheet rather than manually creating, attaching, and running a second source. It creates or reuses the linked People worksheet and binds the company input.

To continue a list, run the attached source again. A company-scoped people source resumes companies it has not searched yet. Re-attaching a source or changing its inputs starts it over, so do that only when the filters need to change. This distinction prevents an avoidable duplicate pass through rows that were already inspected.

Use real options offered by the source for locations, industries, companies, and schools. A source field can be narrow in meaning: a company-search location may mean headquarters, while a nested job location is the location of the matched job. Read the entities that landed before treating a route as a match for the user's place requirement.
ArchitectInspect the attached source and the workbook structure. If company evidence must qualify people, keep the company worksheet as the source of truth and use the company rows to create or reuse the linked People worksheet. Show the source chain before running it.

## Run a small source sample
tables.table_sources.run executes the bound source for real. It can call an external provider and spends variable credits. The executor reserves max_credits, or max_units, before dispatch. The capability applies a generic maximum of 25 credits per call, but that clamp is not the actual provider price. The actual cost belongs to the bound executable.

The run result returns run_id and status. On the authority path it also returns state_version, authority_version, authority_digest, policy_trigger_id, selection_snapshot_id, and replayed. A queued response confirms that execution was requested. It does not prove the source supplied the intended people or companies.

| Stage | What to verify |

| Plan | A ranked route, filter coverage, required inputs, estimate, and build steps. |

| Attach | A saved binding and projected source fields, without fetching rows. |

| Run | A real provider execution with a run id and status. |

| Read | A check of landed entities, projected fields, and run evidence. |

Run a small batch first. The list-building skill uses about twenty-five rows as a sample, reads the entities rather than only their count, and can compare two or three parameter variants. Keep the most precise variant. The sample should make most rows right at the source before you add expensive columns or request a larger run.

A live source run can spend credits

Read the plan estimate, pass the spend ceiling required for the run, and then read the finished run for the amount actually charged. The capability has no second human approval gate. Do not treat an estimate or queued status as a final charge or a finished result.
ArchitectRun a small sample from the attached Operations Leaders source with the plan estimate as the ceiling. Follow the run to completion, then read landed rows and projected fields. Stop before scale if the rows are outside California, lack the operations signal, or lack profile evidence.

## Read the landed rows before scale
Read rows, not only counts. A count that is still being computed is unknown, not zero. Check the selected entities, their locations, the proof for the qualifying signal, and fields needed by later columns. If the sample contains global companies because a company location meant headquarters, or it contains a keyword match without the requested meaning, the source filters are too broad or incomplete.

Try a corrected input on a small sample. Do not make the next step more expensive until the source entities are precise. When the sample reads correctly, scale the same source to the requested count. If no target was stated, the list-building skill uses 100 rows. Target qualified rows, not merely landed rows: a source that lands many near misses still needs a narrower route or filter.

Read the source result after the run finishes, then read the worksheet page. In the completion report, separate landed rows, duplicates, empty evidence, and failures. The next layer should be a column that changes the qualification decision. A source that produces the right raw rows does not remove the need to inspect the cells created by later columns.
ArchitectRead the completed Operations Leaders sample. Show representative rows, applied source fields, duplicates, and missing required evidence. Identify the one source input to tighten if the sample is imprecise; otherwise name the qualifying column to add next.

## When a source does not run
A missing account or credential blocks a run, not planning or attachment. Keep the planned binding, state that it can be attached now and connected or bound at run time, and do not switch to a weaker source merely to avoid a connection. Building every planned step while a connection is unavailable leaves the worksheet ready for a later run.

If the contract refuses the attachment with repair.kind set to fix_input, use repair.hint to correct the payload and retry the corrected binding. If a required criterion has no source filter, retain it for a column and score condition instead of claiming the source applied it. If a cell later reaches a daily limit, that is the workspace pacing cap, not a source defect.

Queued, paced, capped, and unknown are not automatically failures. Read the run state again and inspect the source record frontier before retrying. Do not re-attach a source to solve a temporary run state: reattachment changes the source chain and can start the list over. Diagnose the missing connection, input, or field reference, correct that cause, and read the next sample.

- Keep a missing credential separate from an invalid source binding.
- Keep an unsupported filter separate from a source-run state.
- Keep a queued run separate from a failed row result.
- Keep the source record as evidence for the next diagnosis.ArchitectDiagnose why this attached source did not land the expected rows. Read its binding, state, frontier, and most recent run. Apply a fix_input repair hint if present, otherwise identify the missing connection, unsupported filter, or pacing state. Preserve the current worksheet and verify the corrected sample.

## Columns

Source: https://www.trydreamstate.com/docs/data/columns

Columns enrich and judge rows in a worksheet.

A column answers one declared question for every row in a worksheet. Use columns after a row source has landed a sample, whether the answer comes from source data, a formula, AI judgment, a tool, or enrichment. In Workbooks at /dashboard/workbooks, columns make each qualification decision inspectable before the work reaches a Record or an execution workflow.

Architect uses the list-building skill to turn the user’s criteria into bounded questions. It reads source fields and existing columns first, then adds only the evidence needed to decide who qualifies. Read cells and provenance after each run because creating a column saves a definition, while a run is what settles its cells.

## Make one question per column

A column must state the value it will hold, what produces it, and which rows are worth spending on. One question per column keeps a failure legible. For example, one evidence column can answer whether a company has the requested operations signal and include the exact supporting text, while a later contact enrichment answers a different question: how to reach a person who passed that signal.

Every required criterion gets a yes-or-no column. Set configuration.qualification_requirement to required when creating that column. A false result or failed cell disqualifies the row, while an empty cell remains unknown. Nice-to-have criteria do not receive that setting. These checks describe worksheet criteria. Eligibility for outreach depends on the selected sequence’s explicit enrollment rules; a passing check or fit score alone does not establish eligibility.

Do not use a manual eligible flag in place of a qualification column. Manual text columns are appropriate only when the user explicitly wants a field they will type themselves, with behavior: "manual". A gate needs a settled, inspectable result so it can prevent paid work on rows that failed earlier evidence.
ArchitectRead the Operations Leaders worksheet. Turn each required qualification criterion into one yes-or-no evidence column with the source field or upstream column it needs. Mark required criteria as required. Do not add contact enrichment or run any column yet.

## Build columns in cost order
Order is cost control. Start with identity and profile fields, then derived facts and evidence for each named signal, then an optional score, and finally contact data. Each gate should read a column that has already settled. A gate that reads an unrun column lets no useful decision through, while a paid column placed before its gate spends on rows the gate would have skipped.

| Order | Column work | Why it comes now |

| 1 | Identity and source fields | Expose what the source already returned. |

| 2 | Derived facts and evidence | Test each qualification signal cheaply. |

| 3 | Score | Rank only after evidence values have settled. |

| 4 | Contact data | Spend only on rows that passed the gate. |

A score is an ordinary column, not a replacement for evidence. It reads the evidence columns after they all have values, returns a value from 0 to 100 with reasons, and is useful when several criteria need one ranking. Treat missing evidence as unsure. Do not add a score when a simpler required gate is enough to decide whether to contact the row.

Signals the source cannot filter become evidence columns. Those columns should return a short verdict and the exact text that proves it, or unsure. Contact data is never proof of a different signal. The most selective and least expensive evidence should settle before a provider-backed lookup is allowed to run.
ArchitectOrder the planned columns for this worksheet from free source evidence through qualification and optional scoring to contact data. Explain which settled column gates each later paid column. Leave out any column that would not change the decision to contact a row.

## Bind real row fields
Reference source fields and upstream columns exactly as the worksheet returns them. Do not guess a field name from a label, provider, or another worksheet, and do not add a copy column merely to reach a source field. Source output fields arrive from source attachment, not from workbook creation.

After the source lands, use tables.findable_catalog.list with the worksheet table_id to find available enrichment needs. The default list is compact. Pass definition_id when you need one definition's inputs. Choose the returned enrichment by data need, not provider name. Use the returned add_call unchanged because its binding_spec.input_bindings names existing column keys. Check maintained enrichment presets before writing a new prompt because a named template can already contain bindings, inputs, conditions, and an estimate.

tables.columns.add creates a manual, formula, AI, tool, or enrichment column. A general AI column binds row fields into its prompt and states what it should judge, such as interest, intent, hiring, fit, score, category, evidence, or another signal. A provider-backed enrichment uses binding_spec and maps provider inputs from sibling columns. Adding the binding is free, internally reversible, and does not compute cell values.

Before adding a related column, call tables.columns.list. It is a free, read-only listing of the columns actually present, their bindings, and editable state. The response has no dependency edges, so use the column graph when you need those edges. Read the binding state again before changing a column so an edit does not overwrite someone else’s newer work.

| List response | What to inspect |

| column | Column record and definition. |

| binding | Configured source, AI, tool, formula, or enrichment binding. |

| editable_state | Configuration, run condition, output fields, cost, revision, and last run. |

| binding_read_warnings | Warnings returned while reading the binding. |
ArchitectRead source fields and existing columns in this worksheet. Find the catalog enrichment for work email only after the required fit column settles. Use the catalog add call unchanged, bind only existing sibling fields, and show the new binding before any run.

## Run a bounded sample
tables.columns.run queues one column over a frozen row selection. It can call the provider named by the binding, has dynamic credit cost, and can spend real credits when a worker executes it. The operation is external and returns as soon as the run is enqueued, so no cell is filled merely because the queue response arrived.

The result includes run_id, status, state and authority versions and digests, outer-run identifiers, selection_snapshot_id, replay state, the effective maximum rows, and trial-cap fields. It runs one column rather than the full worksheet. Existing results follow the column’s existing-result policy unless force is true; force still preserves manual overrides and respects run_if and missing-dependency rules.

Use a one-row dry run first. Read its binding_preview for resolved real-row inputs, provider route, and credit estimate. Then make a live run with an explicit execution-envelope max_credits ceiling. The capability has a generic clamp of 25 credits per call, but the bound provider and volume determine actual cost.

Column runs can spend credits

Run only the selected column on a small frozen sample, read the estimate before the live run, and read the finished run for charged credits. A first sample run should continue remaining rows when scaling. Running the column from the top again can bill the sample twice.
ArchitectDry-run the new fit column on one representative row and show its resolved inputs, provider route, and estimate. Then run a small frozen selection with an explicit credit ceiling. When it finishes, read the cells before proposing a wider run.

## Read the run and cells
Use runs.column_get to read counters for one canonical enrichment run. It is free and read-only. Its result contains the API run id and status plus total, processed, succeeded, failed, and skipped row counts, charged credits, and structured error data. Follow the run to a finished state, then inspect the cells that it wrote.

| Run field | What it tells you |

| total_rows | Rows in the canonical enrichment run. |

| processed_rows | Rows the run has processed. |

| succeeded_rows | Rows whose work succeeded. |

| failed_rows | Rows with failed work. |

| skipped_rows | Rows the run skipped. |

| charged_credits | Credits charged by the run. |

| error_json | Structured error data for diagnosis. |

Check values, empty cells, failed cells, and the current run state. Empty, failed, and answered are distinct outcomes. A run that is still queued, pending, paced, capped, or unknown is not automatically a failure and is not zero. A completed queue request is not evidence that a row’s column value supports the qualification rule.

Read every sample row against the named criteria before scaling. If a value is empty, failed, or unrelated, locate the missing input, incorrect field reference, or wrong setting. Correct that specific cause and rerun only the affected scope. Do not hide a defect with a manual cell edit or a different provider, because the worksheet needs a traceable answer.
ArchitectRead the fit-column run and its cells. Report total, processed, succeeded, failed, skipped, and charged credits. Separate empty cells from failures, quote structured error data when present, and identify whether the next safe action is to continue remaining rows, fix a binding, or stop.

## When a column does not produce the expected value
Start with the cell the user sees, its column binding, and the run that attempted to settle it. A column empty on every row can mean its gate reads a column that has not settled, or that it was added after rows landed and was never run on them. A score can be waiting on evidence that failed or is still running.

When a column is refused, read the reason and fix that input rather than changing column kind. When credits are higher than expected, inspect finished runs and charged credits: a repeated sample, contact data before a fit gate, or an expensive column before a cheap selective one are real causes. A cell blocked by a daily limit is workspace pacing, not a product defect.

Use the diagnostics skill to answer one question with the least evidence that settles it. Read first and change second. It classifies the object as still working, paced, waiting on an upstream column, missing a connection, receiving an empty provider answer, failed with an error, or likely defective. A retry that spends credits should be scoped to failed rows or the failed node and followed to a final result.
ArchitectDiagnose why the qualification column has empty or failed cells. Start from one affected cell, read its binding and run, classify the state, and apply the smallest fix. Do not rerun successful sample rows. Tell me the credit effect before retrying any failed scope.

## Cells and provenance

Source: https://www.trydreamstate.com/docs/data/cells

Cells hold row values and their available run provenance.

A cell is the current result of one column on one row. It is where you check source evidence, enrichment output, and qualification instead of treating a worksheet as an unexplained count. Use cells after a column or source run has finished, and before you scale a list or act on a result.

Cells sit in a worksheet under a workbook at /dashboard/workbooks. Their provenance connects a displayed value to the row, column, and work that produced it. Architect uses the diagnostics skill when a result is unclear, because a successful request is not proof that the cell contains the expected evidence.

## Read a rectangle of real cells

Use tables.cells.read_page to read cells for the row ids and column ids you name. It is free and read-only. The read triggers no run and no provider call, which makes it the safe first step for checking a sample. It returns cells only, not row metadata and not per-cell diagnostics, so read the appropriate row or inspect capability when the question needs that context.

Each returned cell has a cell id, row id, column id, value, value type, nullable flag, status, run id, cost, provenance, observation time, update time, and history. Read a rectangle that contains representative rows and the columns that prove the qualification decision. This shows whether the worksheet has complete evidence rather than merely a favorable aggregate count.

| Cell field | What to inspect |

| cell_id | Identifier for this cell result. |

| row_id and column_id | The row and column that define the result. |

| value and value_type | Current result and its declared type. |

| nullable and status | Whether null is permitted and the current cell state. |

| run_id and cost | Run context and cost information for the value. |

| provenance | Evidence trail for how the value was produced. |

| observed_at, updated_at, history | Observation, update, and retained history context. |

Read the row values, not only an aggregate. If an exact count is still being computed, it is unknown rather than zero. A report that claims the worksheet is landed, enriched, judged, or scored needs the finished run and a page of actual cells as evidence.
ArchitectRead a rectangle covering three representative rows and every required evidence column in the Operations Leaders worksheet. For each result, show its value, status, provenance, run id, and cost when present. Do not change any cell.

## Separate cell states before acting
A worksheet can contain answered, empty, failed, and in-progress cells at the same time. These outcomes are not interchangeable. An empty cell means the answer is unknown. A missing provider answer is also unknown. Neither is false, neither is zero, and neither can be filled from a similar row just to make the worksheet look complete.

| State | Meaning and next check |

| Answered | A value exists and carries the row, column, run, cost, and provenance context. |

| Empty | No answer is known. Empty is not false, zero, or an answer copied from another row. |

| Failed | The work did not settle a value. Read the owning run and structured error first. |

| Queued or running | Work is still in progress. Read state again instead of treating it as a failure. |

| Paced or capped | A workspace limit may be delaying work rather than reporting a defect. |

Read empty, failed, and answered results separately in the completion report. A required column with no data remains unknown. A failed cell needs an error or binding investigation. An answered cell still needs a quality check: confirm that the value actually proves the requested criterion rather than merely matching a keyword or label.

Queued, pending, paced, capped, and unknown are not failures by themselves. A cell blocked by a daily limit is a workspace pacing cap, not a defect. Do not retry an in-progress or unknown external action before you read the current run, because the provider work may already be under way or may have completed without the first read seeing it.
ArchitectRead the qualification cells in this worksheet. Separate answered, empty, failed, queued, and paced states. For answered cells, quote the source evidence. For every non-answered cell, name the run or dependency to inspect next. Do not infer false from missing evidence.

## Keep the evidence trail with the value
Provenance is the evidence that explains how a cell reached its current value. A row source provides base data, and a column can project that data, derive it, judge it, or enrich it. Reading provenance alongside the value lets you distinguish a source-owned fact from a later judgment or provider response. When those pieces conflict, show both and investigate the binding or source route before deciding which result to use.

Let a column run settle cells whenever it can. Setting a value by hand bypasses the evidence trail and should be avoided when a column can produce the answer. A manual value is not a substitute for fixing a missing input, incorrect field reference, provider error, or wrong setting. The safest correction is at the source, binding, or run scope that caused the result.

Use links rather than copied evidence when a fact lives on another worksheet. In a company-and-people workbook, a person row should link to the company row that provides its qualifying signal. Re-typing a company’s evidence into a person cell makes the result stale when the source changes and makes it harder to trace the value back to its owner.

Check a representative sample against every named criterion. A row that matches a keyword but not the requested meaning, a person outside the named place, or a person not shown to work at the searched company is not a qualified row. Tighten the source or correct the column input, then read the next sample rather than changing the displayed cell manually.
ArchitectFor each required evidence cell in the People worksheet, trace the value to its source field, column binding, and company link. Highlight any value that conflicts with source evidence or lacks a traceable origin. Propose a source or column correction, not a manual replacement.

## Inspect the run that owns the result
Use runs.column_get to read counters attached to one canonical enrichment run. It is free and read-only. Its response wraps a run containing the API run id and status, total, processed, succeeded, failed, and skipped row counts, charged credits, and error_json. This is the record to inspect when cells have mixed results or a column appears to have stopped.

| Run field | How to use it |

| status | Current execution state for the column run. |

| total_rows | Rows in the canonical enrichment run. |

| processed_rows | Rows the run has processed. |

| succeeded_rows | Rows whose work succeeded. |

| failed_rows and skipped_rows | Rows that failed or did not run. |

| charged_credits | Credits charged by the run. |

| error_json | Structured error data for diagnosis. |

Start from the specific cell, then its column, then the owning run. Record the link, state, attempt, provider, charged credits, and structured error when they answer the question. Stop reading when the cause is clear. A larger log dump does not make a diagnosis better, and it can hide the only row that needs a bounded correction.

A successful step with a receipt should not run again. If only some rows failed, retry the failed rows or failed node rather than re-running the entire sample. Follow a retry to a final result and read the resulting cells. This keeps successful work, prevents duplicate spend, and produces a clear evidence trail for the exception.
ArchitectInspect the run behind these failed cells. Report its status, total, processed, succeeded, failed, skipped, charged credits, and error data. Identify the failed row scope only. Do not rerun completed sample rows or overwrite any manual value.

## Complete the worksheet readback
A worksheet is not complete because a run was started. Completion evidence includes a finished source run, known landed and duplicate counts, finished enrichment runs, and a worksheet page that was actually read. Read at least three rows in full, inspect empty cells in every key column, and check duplicates on the entity identifier, such as a company domain or person profile URL.

When the goal is outreach to people, check that the People worksheet exists, holds person rows, and links them to qualifying companies. Companies alone do not complete a people request. When a result is ready, report the workbook link, sample size, qualification rate, charged credits, accounts still needing connection, and the specific next work, such as scaling, enrollment, or a scheduled refresh.

Read before every claim. A source run can succeed while a later qualification column is empty. A column run can succeed while its output is not relevant to the criterion. A count can exist while the individual rows show near misses. The completed readback keeps those distinctions visible to the operator and to Architect.
ArchitectRead back the completed worksheet before reporting. Check source and enrichment run states, landed and duplicate counts, three full rows, empty key cells, failed cells, and company links for people rows. State what is proven, what remains unknown, charged credits, and the next safe action.

## When a cell does not show the expected result
Use the diagnostics skill to choose one question and follow the smallest evidence chain that answers it. For an empty cell, check whether the column gate reads a column that has not settled, whether the column was added after rows landed and never run on them, or whether the provider returned no answer. For a stuck score, inspect the evidence column that failed or is still running.

For a failed cell, read the structured error and the binding inputs. Correct a missing input, wrong field reference, wrong setting, or connection problem at that level. For unexpectedly high credits, compare completed runs: the sample may have been run twice, contact data may have run before a fit gate, or an expensive column may precede a cheap selective one.

State the fix, whether it repeats external work or spends credits, and the result after it is checked. Cancel only a run the user wants stopped, then read its final state. If evidence indicates a product defect, do not hide it with another provider or a manual edit: retain the object and run identifiers required to report it.
ArchitectDiagnose one unexpected cell. Read the cell, its provenance, column binding, and owning run. Classify it as in progress, paced, missing input, empty provider answer, failed with error, or likely defect. Apply only the bounded fix, state any credit effect, and read the cell again.

## CRM records

Source: https://www.trydreamstate.com/docs/data/crm-records

CRM stores canonical records already saved in the workspace.

CRM records hold durable relationship facts for people, companies, deals, and other workspace objects. Use a record when information should remain the workspace truth after a workbook has finished sourcing and qualification. Records are in the Records area at /dashboard/records/...; they preserve the relationship context that a temporary worksheet should not replace.

Architect uses the CRM skill to read a relationship before it changes it. Workbooks help you find and evaluate rows, while records keep verified facts, human judgment, notes, links, and dated activity together. This distinction matters when the same person or company returns in later work and the team needs to see what happened and why.

## Start with the record model

Use crm.record_objects.list to read object definitions the caller may see. It lists types rather than records, including built-in person, company, deal, and post types plus custom types. It is a free, read-only capability. Read the types first so a new fact belongs to the correct relationship object instead of becoming an unstructured duplicate.

Use crm.records.list to page through records the caller may read. You can narrow the result to one object type or a text query, and every response states its own ordering. It is also free and read-only. Search existing records before creating or changing one because an existing match can carry the identity, owner, timeline, and open work that a new record would miss.

Use crm.records.get for one CRM record or outreach contact id. It returns current values, revision history, associations, timeline, files, and the actions that the caller is allowed to take. Read this full context immediately before any mutation, since another teammate can have changed the record after an earlier list read.

| Single-record context | Why it matters |

| current values | The record’s present structured facts. |

| revision history | Change history needed to inspect the current state. |

| associations | Related people, companies, and other records. |

| timeline | Dated relationship activity. |

| files | Attached evidence available on the record. |

| allowed actions | Actions the current caller may take. |

A record is not a Row source and it is not a Worksheet. A worksheet supports a bounded data job. A record represents a durable relationship entity. In the app, check object type, associations, owner, recent activity, fields, and open work before you decide that a workbook result is new CRM information.
ArchitectList the CRM object definitions available in this workspace. Then search for Acme and Jordan Lee, open the likely records, and show object type, current values, associations, owner, recent timeline, files, and open work. Do not create or change records yet.

## Put information in the right place
The place where information lives changes how the team can reuse and interpret it. Put a stable, reusable, queryable fact in a field. Put reasoning, uncertainty, meeting detail, and information not trusted enough for a field in a note. Put an occurrence that happened at a specific time on the timeline. Do not put narrative in a field merely because it may be useful once.

| Place | Use it for |

| Field | A stable, reusable, queryable fact, such as a verified title or company domain. |

| Note | Context, reasoning, uncertainty, meeting detail, or information not trusted as a field. |

| Timeline activity | An event that occurred at a specific time, such as a call, reply, or stage change. |

Examples of stable facts include a verified title, lifecycle stage, owner, company domain, explicit qualification, or consent state. A call, email, meeting, reply, stage change, or task completion is a dated activity. A note can record the source, date, uncertainty, and conflicting claims when the available evidence does not support changing a stable field.

Do not turn an enrichment guess into a field. First compare it with the record’s existing evidence and the result in the originating workbook. Keep a conflict visible when it is material. Human-entered values are owned judgment, so an enrichment guess does not overwrite them. A verified fact can be added when evidence supports it.
ArchitectReview this record’s recent evidence. Classify each proposed change as a durable field, a note containing context or uncertainty, or a dated timeline activity. Preserve human-entered fields when enrichment conflicts, and show the source and date for every conflict.

## Review the relationship before change
Read before every CRM change. Start with the record, related company and people, activity timeline, open deals, tasks, source evidence, and likely duplicates. Check identity through full name, employer, title, verified work email or profile URL, and relationship to the relevant company. Existing matches can share an email, profile URL, company, name variant, or recent activity, so inspect those signals as a group rather than relying on one search result.

| Step | What to check |

| Read | Read the record, related records, timeline, ownership, and open work. |

| Compare | Compare human-entered facts with source and enrichment evidence. |

| Classify | Separate a stable fact, narrative context, and a dated event. |

| Change | Make the smallest supported update after checking identity and conflicts. |

| Read back | Inspect changed records and report the evidence that supports them. |

Check pipeline context where it applies: owner, stage, amount or expected value, next step, and timeline activity. A pipeline record is useful when it represents active, evidenced customer work with the right person and company, a credible stage, a clear owner, recent activity, and a concrete next step. A stronger enrichment result or the passage of time alone does not establish a stage change.

Do not create speculative records to make a list look complete. Create one record per real relationship entity when identity evidence and purpose are present. Link a person to a company when the evidence supports the link. Include source, owner, and next action when they are known, so the record adds operating memory rather than a lead-shaped duplicate.
ArchitectReview this CRM record, its related company and people, recent activity, open work, source evidence, and likely duplicates. Compare human-entered and enriched values. Show the smallest evidence-backed update, or explain why the current evidence is not enough to change the record.

## Treat identity as evidence
Merge only when at least two independent identity signals show the same entity. Strong combinations include a verified work email plus the same profile, a profile URL plus matching employment, or a confirmed user correction. Before merging, compare field provenance, associations, timeline, ownership, open work, and deal state. This preserves relationship context that can be lost when two superficially similar records are treated as one.

Name similarity, company similarity, a shared public email domain, a first name, or an enrichment guess alone is insufficient. If signals are weak or conflict, leave the records separate and surface the pair for review. Do not delete evidence to remove ambiguity. Preserve sources, dates, and conflicting claims so a later operator can resolve the identity with additional information.

crm.records.merge is a free destructive write. It folds the loser record into the winner: values, activity links, relationships, files, and worksheet rows move to the winner, and the loser stops existing separately. Live vault links at the loser are marked with resolution_status stale so backlinks visibly re-resolve. The result includes a snapshot_id; retain it with the merge evidence.

Merging changes the record graph

Read both records and their associations before merge. A merge moves values, activity links, relationships, files, and worksheet rows to the winning record. Keep the returned snapshot id and the two independent identity signals in the record of why this destructive action was taken.
ArchitectCompare these two records for a possible duplicate. List independent identity signals, conflicting fields and provenance, related records, owner, open work, deal state, and recent activity. Do not merge unless two independent signals identify the same entity. If a merge is supported, retain the returned snapshot id and read the winner afterward.

## Keep pipeline memory true
Pipeline is true when every open deal represents active, evidenced customer work. Review newly created records, suspected duplicate pairs, fields with conflicting or stale evidence, deals without a next step or owner, recently changed stages, and open deals with no activity in 21 or more days. A deal with a high value or late-stage label is not healthy merely because those fields exist.

Track duplicate-pair count and the count of deals with no activity in 21 or more days in each hygiene review. Report zero as a result, not as an assumption. Read representative records after low-risk, evidence-backed field corrections. This readback confirms that the new value appears on the right relationship and that notes, timeline, ownership, and open work still tell the same story.

Advance a stage only when a customer action or documented qualification meets the stage definition. Record the evidence and next step with the change. If the criteria are unclear, preserve the stage and state the decision needed. A CRM record should describe current relationship reality, not improve a forecast by hiding missing evidence.
ArchitectRun a read-only CRM hygiene review. Count suspected duplicate pairs and open deals with no activity in 21 or more days. For sampled records, check owner, next step, recent activity, conflicting evidence, and stage evidence. Report findings and leave uncertain stages unchanged.

## When CRM evidence conflicts
When enrichment conflicts with a human-entered value, preserve the human-entered value. Read the source evidence, retain the conflicting claim with source and date in context, and return to the originating workbook if the underlying row needs more qualification. Do not create a fresh record or overwrite a field merely because the enrichment looks more complete.

When identity is unclear, report the independent signals that exist and the signal that is missing. Do not merge on a public email domain, a name, a company match, or a guessed enrichment. When a stage lacks customer evidence, keep it where it is and identify the documented qualification or customer action needed to support a later change.

When a record change creates an unexpected result, read it back with crm.records.get. Check current values, revision history, associations, timeline, files, and allowed actions. Preserve the object and merge snapshot identifiers when relevant. This gives the team a factual path to investigate instead of masking a relationship conflict with another write.
ArchitectDiagnose this CRM conflict without changing the record first. Read the record and related records, compare human-entered and enriched values with sources and dates, inspect identity evidence, and state whether the correct next action is a note, more workbook qualification, a bounded field correction, or leaving records separate.

## Modes

Source: https://www.trydreamstate.com/docs/execution/modes

Mutating calls name a mode and the server does not default to live work.

A Mode tells Dreamstate whether you want to inspect a capability, preview it against your workspace, or execute it. Use a mode whenever a capability can change workspace data, call a provider, spend Credits, or reach someone outside the workspace. Architect, the CLI, MCP, and REST send the same mode value to the same execution contract.

Modes sit after discovery, not before it. First search the tool catalog, fetch the exact capability schema, and then choose a supported mode. After live work starts, use Runs to read the durable result rather than submitting the same operation again.

## Choose the execution mode

The server does not infer live execution for a mutating call. The fetched capability contract decides whether a particular mode is available, so a read can have different mode behavior from a create, send, or publish action. Use the smallest mode that answers the question you have now.

| Mode | What it does | What it does not do |

| smoke_test | Static schema and policy inspection | Writes nothing and creates no audit entry. |

| dry_run | Validation and preview against workspace state | Makes no business write, provider spend, or outward action. |

| live | Capability execution | Performs the operation described by the fetched contract. |

Use smoke_test when you need to inspect the static schema and policy before touching workspace state. Use dry_run when a preview needs the real selected workbook, Worksheet, sender, or other workspace context. Use live only when the returned contract and preview describe the result you intend to create or deliver.

A dry run is not a generic simulation of every downstream provider. It validates and previews from the available workspace state, while avoiding business writes, provider spend, and outward actions. Read the preview as a decision record, then correct its inputs before changing to live mode.

## Discover the contract, then preview

Ask Architect for an outcome, not an assumed capability id. Architect uses the catalog search control, fetches the returned contract, and chooses the capabilities that match the request. The same pattern applies in every surface: search identifies candidates, get supplies the current input schema, and run receives the selected mode.

For example, creating a Workbook is data work. The example below asks for a preview of a Workbook called October prospects. In the app, compare the returned preview with the intended name and destination before changing the call to live mode.
ArchitectCLIMCPRESTFind the workbook creation capability, fetch its current contract, and dry run a workbook named October prospects. Show me the preview and do not create it yet.
Keep the parameters from a successful preview when you move forward. If the task is paid, the execution response can return an estimate instead of starting live work. That response is information about this request, not proof that a later request with changed inputs has the same price or effect.

## Review cost and outward effect

Credits are the spend control for live work. When a paid live call needs a price, Dreamstate returns quote_required with its estimate. Rerun the same call with unchanged parameters, the returned quote binding, and a max_credits ceiling that covers the estimate.

Check the capability description and cost policy that discovery returned before you do this. A capability can be free, can use an action cost, or can have dynamic cost behavior. Do not substitute a ceiling copied from another capability, because the request and its estimate are part of the live execution contract.

Live work can create real effects
A dry run does not spend Credits or make an outward change. A live capability can create, send, publish, enroll, or activate work according to its contract. Check the affected object, recipient, platform, and credit estimate before you run live work.
Architect can ask about a sensitive effect as part of its judgment, but the operating control is still the requested mode and credit ceiling. In the CLI, retain the output with the run identifier. In the app, follow the returned web_url when it is present, while keeping JSON identifiers as the source of truth.

## Use live mode intentionally

Live mode executes the selected capability, but it does not turn a draft into every later state automatically. For example, a Sequence can be drafted, validated, published, enrolled, started, delivered, and replied to as separate stages. Review Sequences and enrollment before treating a completed create as delivery.

Live work can return immediately or create durable work for later inspection. When the result names a run, open the run rather than guessing from the original request whether all steps have completed. A state-bearing result can also include a direct app URL, which helps you inspect the object without replacing its JSON id in follow-up calls.

Connections affect execution, not preparation. You can build a draft when the required LinkedIn account, mailbox, or provider is not connected, but a contract that needs that connection can refuse the later live step. Keep the draft, resolve the connection in the relevant app settings, and then fetch the current contract again before retrying.

## When it goes wrong

A mutating request without a mode returns mode_required. Retry with smoke_test, dry_run, or live, after checking that the fetched schema supports the choice. The server explicitly says that it does not default to live mode.

If the service returns quote_required, do not alter fields and assume the old quote still applies. Preserve the parameters, use the returned quote information, and provide the matching max_credits value for the rerun. Search and get again when the capability contract was delivered on another turn.

A root capability attempted through an API key can return destructive_approval_required. Root actions change workspace ownership, reach, money, keys, credentials, or similar protected settings, so they run only from the current signed-in owner session with their required idempotency handling. This is a security rule for owner actions, not a mode or credit rule for ordinary execution.

## Runs

Source: https://www.trydreamstate.com/docs/execution/runs

Runs record execution work and can expose links to exact app objects.

A run is the durable record created when work is accepted. Use it after a live operation to see what completed, what remains, and whether the work can safely be cancelled. It connects the execution surface to the object state you inspect in the app.

Architect can inspect runs while it works, and the CLI, MCP, and REST expose the same read controls. Review modes before creating new work.

## Inspect the current run

runs.get reads one durable run and the first page of its steps. It returns the run envelope rather than starting the capability again. Check its status and state version before you take a follow-up action.

| Result field | Meaning |

| run_id | The durable identifier for this accepted operation. |

| status | The current lifecycle state of the run. |

| state_version | The current version required when cancelling a run. |

| completed and incomplete | The completed steps and work that is not yet complete in this page. |

| next_cursor | The cursor for the next page of the step graph. |
ArchitectCLIMCPRESTRead run 00000000-0000-0000-0000-000000000000, show incomplete steps, then get the next event page. Do not rerun the work.

## Read all step pages
runs.events returns another page from the same step graph. Its completed and incomplete arrays contain only that page, with next_cursor and has_more telling you whether to continue. This read is free, synchronous, and does not rerun or alter work.

## Cancel carefully

runs.cancel needs the state version from a run read. It stops queued and blocked steps from starting, but a step already executing finishes. Completed work remains completed and spent credits are not refunded. The returned status can still be running, reconciling, or partially completed.

Cancellation does not undo effects
Cancel before an outward step begins when possible. Read the run again after cancellation. There is no generic run resume. A table run checkpoint resumes with dreamstate tools run tables.table_runs.resume. Start a new run for anything else.
## Use the Run as the execution record

A Run is the durable record for accepted work that has a lifecycle beyond one response. It separates the request you made from steps that have completed, remain blocked, or can no longer start after cancellation. Use the Run when you need to report what happened without rerunning a capability and creating duplicate work.

Architect can read Runs while it works and presents its plan as a checklist in the app. The CLI, MCP, and REST use the same Runs controls, so a Run id and state version carry the same meaning across surfaces. A returned web_url can open an app object, but the Run id remains the identifier for the next Runs call.

Read the current Run before asking whether work succeeded. A capability can accept a request before every step finishes, especially when its contract records durable work. The status, completed array, incomplete array, and cursor fields are the evidence for the lifecycle rather than a guess based on the original command.

## Handle partial work deliberately

Cancellation stops queued and blocked steps from starting, but it does not reverse completed work or interrupt a step already executing. That is why the cancellation result can still show running, reconciling, or partially completed state. Read the Run again after cancellation and identify which steps completed before deciding what should happen next.

Credits already spent are not refunded by cancelling a Run. For a live action that can create a provider effect, inspect the target object or external result as well as the Run state. This distinction matters for Sequences, social publishing, and Inbox replies, where a completed step can have reached someone outside the workspace.

There is no generic run resume command. Do not invent a state version or retry a stale cancellation, because the Run read is the source for the version runs.cancel needs. A table run checkpoint is a different capability, tables.table_runs.resume, reached with dreamstate tools run.

## When it goes wrong

If a Run does not show every step in the first response, call runs.events with the same Run id and follow next_cursor while has_more is true. Do not interpret one page as the entire graph when the cursor says another page exists. The events read is free and synchronous, and it does not rerun work.

If cancellation cannot use the current version, fetch runs.get again before retrying. The CLI reads the state version from the Run response and tells you to pass it when it cannot find a valid value. This protects a newer Run state from an old cancellation request.

If a Run points to an external operation, inspect both the Run and the destination surface. A completed request does not tell you more than the capability result does about a later scheduled delivery or a separate provider state. Keep the Run id with the related Workbook, Sequence, post, or thread while you investigate.

## Sequences and enrollment

Source: https://www.trydreamstate.com/docs/execution/sequences

Sequences separate drafting, validation, publishing, enrollment, starting, delivery, and replies.

A sequence is an ordered outreach journey built from a worksheet view or a workflow. Use it when the same audience needs a paced set of steps, while keeping drafting, publication, enrollment, and delivery separate. The sequence builder is at /dashboard/automations/sequences; a worksheet supplies the rows it can enroll.

Build the audience first in a workbook, then use a workflow only when a trigger or graph should control enrollment.

## Build from a worksheet

sequence.sequences.create_from_worksheet creates a draft, binds exactly one worksheet view, validates it, and stages that view's rows. It is free and synchronous. It does not publish, start, or send, so you can inspect the sequence and its audience in the app before delivery exists.
ArchitectCLIMCPRESTCreate a draft sequence from worksheet ws_prospects, validate it, and stage the selected rows. Do not start delivery.

## Keep lifecycle states separate

| Stage | What happens |

| Draft and validate | Create or edit the sequence, then read structural errors without saving or sending. |

| Publish | Marks a draft version as published. It does not enroll people, call a provider, or send. |

| Enroll | Stages eligible worksheet rows as admission candidates. Starting is separate. |

| Start and deliver | The delivery stage that can reach real people, paced by sender settings. |
Enrollment can freeze up to 10,000 worksheet rows. A sequence without usable LinkedIn identities reports unresolved rows. A provider-bound LinkedIn journey with no connected LinkedIn sender returns sequence_no_senders and stages no rows. Email-only journeys can still be enrolled without a mailbox.

Starting delivery reaches real people
Publishing and enrollment do not send. Start is separate, and delivery follows each account's daily limits, sending hours, and maximum new enrollments. A reply ends that person's run.
## Use the current step palette

The canonical sequence model includes email, wait, condition, random split, action, and LinkedIn steps. Its action and LinkedIn arms cover the outreach actions used by the builder. The frozen spec says the intended eleven-step palette includes email, send DM, connection request, wait for connection, profile view, profile fetch, like, comment, wait, condition, and Slack message.

## Validate before publication

A Sequence should be structurally valid before it is published or enrolled. Ask Architect to use the outreach skill to check the journey order, then use the sequence validation capability to return structural errors without saving or sending. In the builder, check the Worksheet view, steps, and selected sender context before you move beyond the draft.

Validation is not delivery. A valid draft proves that the currently saved structure can be evaluated, while publication creates the published version and enrollment stages people from the selected Worksheet view. Starting and delivery remain later events, which means a published Sequence has not reached a prospect merely because it has been validated.

Inspect the Sequence in Automations after each meaningful change. Keep the returned Sequence identifier for the next capability call, and follow a returned web_url to the matching app object when one is available. The URL is a useful app shortcut, but the JSON id remains the durable reference in tool calls.

## Keep enrollment separate from delivery

Enrollment stages Rows from a Workbook view as admission candidates. It does not send them a message, and it does not silently turn a draft into a running journey. That boundary lets you inspect the audience before the explicit start action permits provider delivery.

The outreach skill treats publishing, enrollment, starting, delivery, and reply as separate facts. A reply ends the person’s run, and company pause on reply can apply where several people belong to one company. Check the Sequence state and related Run rather than assuming that one lifecycle event implies another.

Missing connections do not prevent building a Sequence. They can block a provider-bound execution step, such as a LinkedIn journey that needs a connected sender. Preserve the draft, connect the needed account in settings, then recheck the current sequence contract before retrying the blocked operation.

## When sequence work fails

sequence.sequences.validate returns structural errors without saving or sending. Use it before publishing. If enrollment is blocked by a missing sender, connect the sender for the provider-bound journey, then retry. Missing or invalid workbook, worksheet, saved view, or sort-column references appear in lint results as enrollment_workbook_not_found, enrollment_worksheet_not_found, enrollment_saved_view_not_found, or enrollment_sort_column_not_found.

A failed enrollment does not make the underlying Workbook disappear. Use the named error to inspect the source Workbook, Worksheet, saved view, or sort Column, then rerun validation before staging Rows again. If a live action starts durable work, inspect its Run instead of submitting the same enrollment request repeatedly.

## Workflows and triggers

Source: https://www.trydreamstate.com/docs/execution/workflows

Workflows organize automation graphs with scheduled and event triggers.

A Workflow is an automation graph with a Trigger, conditions, and actions. Use one when a saved Worksheet view is not enough to decide when work begins or which path it follows. Build and inspect Workflows at /dashboard/automations/workflows, then connect a Workflow to a Sequence only when the graph should control enrollment.

A Workflow is not an automatic send button. It starts as a draft graph, has a saved revision to check, and can be previewed before any execution is enabled. Read Modes for the difference between inspection, preview, and execution, and read Sequences for the separate enrollment and delivery lifecycle.

## Create a draft graph

Architect uses the workflows skill to turn an outcome into a draft graph. It searches the workflow pack, gets the current schemas, and selects the capability that matches the requested graph change. The app shows the resulting Workflow in Automations, where you can inspect the trigger, nodes, and revision before continuing.

workflow.automations.create creates the Workflow container. A new Workflow starts with exactly one Trigger node called trigger-root. Unlike a Sequence, a Workflow needs a Trigger subtype and configuration, because the Trigger establishes when the graph can begin.
ArchitectCLIMCPRESTCreate a workflow draft named New lead routing with this trigger. Add the action nodes, lint it, then preview the saved revision. Do not activate it.
The capability is not a replacement for discovery. Fetch the create contract for its required inputs, then keep the returned identifiers with the draft. The returned state can include a web_url that opens the exact app object, but its JSON identifier remains the value used in later calls.

## Add nodes to the current version

Add one node at a time with workflow.automations.node_add. Each call writes a new draft version and inserts exactly one node, so a caller provides a unique node id and uses the returned draft-version token for the next write. This versioning protects a later edit from silently applying to an earlier graph state.

Workflow node content is nested under data. The node id, type, and position stay at the root of the node shape. Keep those two levels separate when you construct a node, because moving a root field into data can leave the graph structurally incomplete.

Use a Workflow for workspace actions such as creating a Task, requesting manual review, or updating a Record when those actions belong to a graph. The Sequence palette is separate and is intended for delivery journey steps. This distinction keeps a Workflow’s automation decisions visible in the graph and keeps outreach cadence visible in the Sequence builder.

## Lint and preview the saved revision

Lint and preview are checks on the saved revision, not execution requests. Run them after creating or changing nodes, and look at their result in the Workflow screen before treating the graph as ready for a later action. Architect can perform these checks as part of its working checklist, while the fetched tool contracts remain the authority for each request.

| Check | Result | Meaning |

| Lint | { valid, issues } | A free structural report. Every issue has a path, code, message, and blocking or warning severity. |

| Preview | Saved revision effect summary | A free read of the executable revision. It does not create a run, invoke a node, spend Credits, or send. |

Preview reports the saved revision’s external step count, external write count, pinned connection ids when present, and billing floor fields. It does not create a Run, invoke a node, spend Credits, or send a message. A clean lint is useful evidence, but each later write and publish action validates independently against the current graph.

## Connect the graph to the next system

A Workflow can prepare or control work that another system carries out. For example, a Trigger can select the point at which a qualified Row reaches the graph, while a later Sequence action handles the separate enrollment lifecycle. The graph does not erase the Sequence boundary between draft, publication, enrollment, start, and delivery.

Build without waiting for a provider connection when the capability permits a draft. A missing LinkedIn account, mailbox, or other provider can block the later run or send step, but it does not prevent you from designing the graph and checking its structure. Resolve a missing connection in the app before retrying the capability that needs it.

Activation can lead to external work
A Triggered Workflow can create external writes or deliveries through its configured nodes. Inspect the saved revision, its previewed external counts, connected destinations, and credit behavior before you use a live activation action.
Keep the Workflow revision as the shared reference for collaborators. The graph and its validation result make the proposed behavior visible before a later run exists. This is especially useful when one person designs the Trigger and another person owns the connected delivery system. It also preserves the reason for each later execution decision.

## When it goes wrong

Start with lint output, not a guessed correction. The service can report workflow_graph_invalid, workflow_dynamic_branch_invalid, node_contract_unresolved, or node_unavailable when the graph or selected node cannot be accepted. Repair the returned path and rerun lint on the saved revision.

Content and variable failures have their own codes. message_copy_missing identifies missing message content, while template_token_unresolvable and variable_context_unavailable identify values the graph cannot resolve. Read the issue severity and message together, then change the relevant node rather than replacing unrelated parts of the graph.

node_blocker_unmet means a node’s prerequisite has not been met. Check the current node order, Trigger configuration, and referenced system, then fetch the schema again if the contract came from an earlier turn. Use the Run record after live work begins, because lint and preview report the revision rather than a completed execution.

## Social posts and publishing

Source: https://www.trydreamstate.com/docs/execution/social-publishing

Social work covers drafts, schedules, publish actions, accounts, and performance analytics.

Social publishing manages content from a draft through scheduling or publication. Use it when you want to prepare a post for a connected social account, then review the schedule in Calendar at /dashboard/calendar. It is separate from Context, which supplies workspace knowledge, and from sequences, which deliver outreach.

Architect uses the social, LinkedIn posts, X posts, and Reddit posts skills to plan the requested channel work. Those skills teach the practice, while the fetched social capability contract determines what the system can actually do.

## Create a social draft

social.content.article_create creates an article, its content artifact, and an empty body. It forces LinkedIn as the target, has no account binding, and cannot schedule regardless of supplied values. It is free, synchronous, and produces an article you can inspect before any delivery action.
ArchitectCLIMCPRESTCreate a LinkedIn article draft for the product launch. Show the empty draft and its web link. Do not schedule or publish it.

## Schedule or publish only after checking the contract
Search and fetch the exact schedule or publishing capability before running it. A connection can be needed for delivery, but missing connections do not prevent you from creating a draft. Use a dry run when that contract supports it, then examine the returned object and its web_url in Calendar.

Publication reaches an external audience
A live publishing action creates outward content. Verify the target platform and connected account before you run it.
## Review the draft in Calendar

A draft is the point where content can be checked without being delivered. Architect uses the social, LinkedIn posts, X posts, and Reddit posts skills to plan the requested work, but those skills do not grant a publishing capability. The fetched capability contract defines the account, content shape, and mode that an actual request can use.

The article-create capability creates an article, its content artifact, and an empty body. It forces LinkedIn as the target, has no account binding, and cannot schedule regardless of supplied values. The resulting object is a draft to inspect, rather than a request that has already selected a social destination.

Open Calendar after a state-bearing result provides a link. Check the visible draft, target platform, and intended content before you ask for a schedule or publication capability. JSON ids remain the source of truth for later calls, while web_url links to the matching app screen.

## Keep draft, schedule, and publication separate

Creating content, scheduling content, and publishing content are different operations. A draft can exist without a connected account, while a delivery action can require a connection to the requested provider. Missing connections block the later execution step, not the work of preparing the draft.

Use Modes to inspect the exact schedule or publishing contract. A smoke test inspects schema and policy, and a dry run validates and previews against workspace state without a business write, provider spend, or outward action. Live execution is the point at which the chosen contract can create its described effect.

When a paid live call returns quote_required, retain its parameters and rerun with the quote binding and a max_credits ceiling. The estimate belongs to that request. Do not infer a schedule or publication cost from a separate draft because their capability contracts can differ.

## Check delivery state after live work

A live publishing request can create durable work. If its result includes a Run, use Runs to see whether execution completed, remains incomplete, or exposes more event pages. Do not treat a request receipt as proof of later provider delivery.

Calendar is the app surface for reviewing planned content. It complements the Run record by showing the content object and its scheduling context. Check both when a post has a scheduled date or target account, because the Run is execution evidence and Calendar is the object view.

Context is separate from publication. Use Context to maintain workspace knowledge, then use the social contract to create and deliver a specific content object. A Sequence is also separate, because it controls outreach journeys rather than a social post lifecycle.

Keep these boundaries visible when you report status. A draft proves that content exists, a schedule describes planned timing, and a publication result describes a delivery action. Check each state in its own object or Run record.

## When publishing work fails

Keep status reports specific: a draft proves content exists, a schedule records planned timing, and a publication result records a delivery action. Check each state in its own object or Run record.

If discovery does not return a contract for the requested outcome, change the request or use the capability that was returned instead of guessing an id. If delivery needs an unavailable provider connection, retain the draft and resolve the connection in the app before retrying. Inspect its run when the call returns a run handle.

If a live request has an external audience, stop at the draft until the target platform and connected account are correct. Use the returned error repair information and refetch the current contract when it came from another turn. A failed delivery does not change the distinction between the draft object and the later provider action.

## Inbox

Source: https://www.trydreamstate.com/docs/execution/inbox

Inbox handles messages and replies inside existing conversations.

Inbox reads and replies to existing LinkedIn, email, WhatsApp, Instagram and X conversations. Open /dashboard/unibox for the same stored conversation view. Start a new message from an authorized CRM record, or use a Sequence for outreach cadence.

## Read thread context first

unibox.inbox.unified_list returns an authorized page in server order, with an exact filter cardinality and opaque next cursor. Omit date filters for the full stored history. All responses uses persisted inbound response evidence, even after an outbound reply.

| Conversation field | Meaning |

| conversation_id | The exact account-scoped conversation reference used for reads and actions. |

| channel and account | The channel and authorized sending account, including current read and reply authority. |

| participants | Selected stored identities and profile facts. CRM links may be null. |

| state | Persisted unread, response, status, label, assignment and completion facts. |

| capabilities | Current action availability, reasons and channel content limits. |
ArchitectCLIMCPRESTList conversations needing a reply across my connected channels, read the selected conversation, and draft a reply without sending it.

## Draft before sending
Read unibox.inbox.conversation_get with the returned conversation_id. Review the recipient, actual messages and sender account before drafting. A saved draft and an accepted send are separate states.

## Send a thread reply

unibox.context.thread_reply_send takes the exact conversation_id, shared content and a stable client_request_id. Content contains body, attachments and nullable voice; use only the operations and limits advertised by the conversation capabilities.

A reply reaches a real person
Review the message and account before live delivery. If the outcome is uncertain, recover the original request with the same identity and content.
## Use the full thread context

Conversation detail returns a stored message window and next_message_cursor for older pages. Read further pages when needed; do not infer full provider history from one window or an incomplete sync. Messages retain source, transport and native IDs, attachments, reactions and delivery state.

Select a participant to read its stored profile. Missing CRM links do not hide stored bio, phone or follower facts. Unknown facts stay null; opening a profile does not refresh the provider or promote a personal attendee into CRM.

## Draft without delivery

Ask Architect to prepare a draft without sending it. Use the returned draft revision for edits and approval. Fetch the current capability schema before a run; the live server still checks account assignment and sending policy.Sequences manage cadence separately from the conversation reply.

## Check the send result

The accepted reply result contains conversation, message, client_request_id and replayed. message_id is the stored source UUID; transport_message_id is the provider acknowledgement, while native_message_id is a distinct nullable platform ID. Acceptance is not proof of delivery or reading. If a run is still unresolved, inspect that run instead of creating a replacement send.

## When Inbox work fails

Preserve the draft and follow the returned action reason when an account, assignment or sending window blocks delivery. The sync status shows stored coverage and progress. An explicit sync request updates history separately; opening a conversation does not trigger a provider sync.

## Tasks

Source: https://www.trydreamstate.com/docs/execution/tasks

Tasks manage assigned work, due dates, delegation, and review state.

Tasks organize assigned work, due work, delegation, completion, and review state. Use the Tasks screen at /dashboard/tasks to see work needing attention, then use the tasks pack when an agent needs the matching review corpus. Tasks are different from Workflows, which automate a graph instead of organizing assigned work.

The app screen is the place to review task context and ownership. Architect discovers a current capability before it reads or changes task data, so it does not assume that every request for “my tasks” means the same task collection. Use Modes when a task action has a possible external effect.

## Read the task review work

tasks.tasks.list is a free, synchronous read of the campaign review corpus. It merges campaign items, pending outreach items, and engagement-gated inbound-reply tasks. That corpus is not a general to-do list, so start by describing the work you need reviewed instead of supplying an assumed task id.

Architect uses search to locate the task capability and get to obtain its exact schema before running the read. In the app, compare the returned items with the Task screen before you choose one for review. The capability contract, rather than the display label alone, determines which task attributes and actions the current request can use.
ArchitectCLIMCPRESTList the task review corpus, inspect the selected item, and explain what accepting or rejecting it would do. Do not review it yet.

## Inspect the item before review
Read the selected item’s task kind and displayed context before asking Architect to review it. A task can represent ordinary assigned work, a campaign decision, outreach work, an inbound-reply follow-up, or a publishing decision. The same review verb can have a different effect depending on that kind.

Ask Architect to explain the proposed state change in plain language. Check the audience, channel, scheduled content, or related object on the Task screen, then decide whether the action reflects the work you intend. This separates reading the review corpus from carrying out an action that could affect another system.

A task can point to work created elsewhere in Dreamstate. Follow the linked object when it is present, and use its JSON id for later calls when the returned data needs to identify it. A web_url can open the object in the app, but it does not replace an identifier in a capability request.

## Understand review effects

tasks.tasks.review is synchronous, but synchronous does not mean harmless. It can update task state and, for designated task kinds, pass content to an external social provider. Read the fetched review contract and the task’s effect before using it in live work.

| Review action | Result |

| List | Reads the campaign review corpus without changing an item. |

| Reject | Sets the reviewed item to rejected and does not publish content. |

| Accept an ordinary item | Changes task state for task kinds that do not carry a provider action. |

| Accept a publishing item | Can submit LinkedIn or X content for real scheduling or publication. |

Some task reviews reach an external audience
Reviewing schedule_post, post_tweet, or publish_content can submit content for real scheduling or publication on LinkedIn or X. Read the selected item, platform, account context, and effect before you use live review.
## Use Tasks with the other execution surfaces

Tasks help a person or agent decide what needs attention. A Workflow can create or route operational work, while a Sequence controls a prospect journey, and an Inbox thread is the place to read an existing conversation. Keep these concepts separate so that a review decision does not get mistaken for an automatic delivery action.

When the task concerns an outreach reply, inspect the conversation first in Inbox. When it concerns a post, inspect the draft and Calendar context described in Social posts and publishing. When it concerns a run already in progress, check its Run record rather than trying to reproduce the work through task review.

This separation also makes handoffs clearer. The Task identifies the decision, the destination surface shows the work itself, and the Run records durable execution when there is one. Use all three records when an outcome involves several teams or systems.

## When it goes wrong

Search and get before run, especially when the request says “my tasks.” The task review corpus and a personal to-do list are different reads, so a broad request can return the wrong kind of work for the decision you need to make. Ask for the related campaign, outreach, inbound reply, or publishing work when that is the intended scope.

If the selected task would create an outward effect, do not guess its kind or use the review action against an unfamiliar item. Preserve the item for later, inspect its displayed context, fetch the current review schema, and confirm the effect it describes. Rejection is the safe recorded state when the decision is not to submit the item.

If a result names a Run, open the Run and read its status instead of assuming the provider action has completed. A completed review request and a completed scheduled or published post are not the same fact. Use the returned object identifiers and app links to follow the state in the appropriate screen.

Keep the task visible until the corresponding destination surface shows the expected state. This avoids treating a request receipt as evidence that a later delivery or schedule has occurred. If the result is incomplete, use its related Run or object record for the next investigation.

## Packs

Source: https://www.trydreamstate.com/docs/providers/packs

Packs route work by domain and explain what each domain owns.

Packs divide Dreamstate into twelve ownership domains across data, knowledge, action, and control layers. Use a pack to narrow an outcome to the team of capabilities that owns it, then fetch the exact capability contract before you run anything.

Packs are metadata, not authority. Architect, MCP, and the CLI expose the same pack controls, while the live catalog supplies the schema, modes, cost policy, scopes, and effect of a capability. Start with Tool catalog after routing, and use Integrations or Senders and mailboxes when the outcome concerns a connection or outreach safety policy.

## Route work through four layers

The data layer contains tables and crm. Tables builds a scored working list from sources, columns, and row enrichment. CRM manages canonical records that are already saved in the workspace. This boundary means that an unsaved people search belongs in a workbook and a durable account, opportunity, or deal belongs in CRM.

The knowledge layer contains knowledge and visibility. Knowledge owns Context, documents, briefs, research notes, positioning, ideal customer profiles, personas, competitor intelligence, revisioned vault content, and governed knowledge changes. Visibility owns the evidence that shows how business content is seen, including attribution, SEO, AI answer-engine citations, share of voice, conversion measurement, meetings, and feedback.

The action layer contains sequence, social, workflow, unibox, and tasks. It covers work that changes a draft, a lifecycle, an assigned task, an automation, or an existing conversation. Publishing a social post and launching an outreach sequence are separate action outcomes.

The control layer contains integrations, senders, and workspace. It controls access and durable workspace policy: third-party provider connections, suppression and sender policy, and membership, credits, billing, notifications, and saved views. A control pack does not become the owner of the social, sequence, CRM, or knowledge result that uses it.

| Pack id | Layer | Owns | Not for |

| tables | Data | Working lists, worksheets, sources, enrichment, columns, scores, and row provenance. | Saved canonical CRM records. |

| crm | Data | Saved people, companies, accounts, opportunities, deals, relationships, and pipelines. | Unsaved discovery or provider connections. |

| knowledge | Knowledge | Context, documents, briefs, research, positioning, and governed knowledge changes. | Working row sets, CRM records, membership, or billing. |

| visibility | Knowledge | Attribution, SEO, AI answer-engine citations, share of voice, and measurement evidence. | Social creation, provider setup, or list building. |

| sequence | Action | Outreach cadence, templates, enrollment, follow-ups, launch, pause, and lifecycle state. | Existing-conversation replies, suppressions, or general automation. |

| social | Action | Social drafts, schedules, publish actions, accounts, and post performance. | Visibility measurement or provider credentials. |

| workflow | Action | Automation graphs, triggers, runs, failure diagnostics, replay, and metrics. | Outreach cadence or worksheet column runs. |

| unibox | Action | Existing threads, messages, replies, response state, and follow-up state. | Net-new outreach initiation and enrollment. |

| tasks | Action | Assigned work, queues, assignees, due dates, series, completion, and review. | Sequence automation or workflow graphs. |

| integrations | Control | Provider connection, OAuth, credentials, health, diagnostics, and synchronization. | CRM truth, calendar events, social publishing, or visibility results. |

| senders | Control | Suppression, mailbox health, rotation, sender identities, domains, and sender policy. | Provider OAuth, sequence selection, or conversation replies. |

| workspace | Control | Members, settings, credits, billing, webhooks, agency, grants, snapshots, tags, and saved views. | Knowledge or external provider connections. |

## Choose by the owned outcome

Ask what durable result is needed, not which familiar product noun appears in the request. A connection behind a record is integrations work, but the record remains CRM work. A suppression is sender-policy work, but the outreach sequence remains sequence work. A reply in an existing thread is Unibox work, while a first outreach attempt is sequence work.

The pack boundaries prevent several common routing errors. Do not use CRM as a disposable prospect list, because tables owns working lists and their sources. Do not use a social pack to measure citations or SEO, because visibility owns measurement. Do not use a workflow to create a cadence, because sequence owns outreach timing and lifecycle. Do not use a sender policy to authorize a provider connection, because integrations owns external provider OAuth and credentials.

A pack can name related capabilities that live under another prefix when the outcome requires them. That does not transfer ownership. For example, a social outcome can surface related auto-engagement controls whose ids begin with sequence.; the scoped search includes the relationship so an agent does not conclude that the feature is absent merely because its identifier uses a neighbouring pack prefix.

In the app, workbooks are under Workbooks, Context is under Knowledge, sequences and workflows are under Automations, Inbox holds existing conversations, Tasks holds assigned work, and connection or sender policy lives in Settings. These locations help a user check the right screen after Architect has routed a goal, but the capability catalog remains the authority for a runnable operation.
ArchitectCLIMCPREST
I need to stop future outreach to acme.example, then inspect the current sequence for its contacts. Route each outcome to its owning pack and show the exact capability contracts before changing anything.
## Pack control reference
packs_list is the index and packs_get is the full document. The list deliberately omits the complete capability array so the response foregrounds pack ids instead of burying routing metadata in a large catalog response. Use get after list when the agent needs the complete capabilities and skill briefs for one pack.

packs_route accepts one trimmed, non-empty goal. It returns an owning pack_id when the outcome has one, or a null route when no pack owns it. Route is a recommendation based on the current pack catalog, not an authorization decision and not a substitute for searching the capability catalog.

CLI commands are dreamstate packs list, dreamstate packs get <pack_id>, and dreamstate packs route --goal <text>. Each accepts optional --json-output or --json. The parser accepts no additional packs-specific flag. Its route form requires --goal, while get requires one positional pack id.

MCP uses strict empty input for packs_list, a strict object containing pack_id for packs_get, and a strict object containing goal for packs_route. Unknown fields are not part of these contracts. A missing pack responds with the canonical not_found error and a Pack not found message.

| Control | Arguments | Required | Result |

| packs_list | None | No | Summary of available pack cards without the full capability list. |

| packs_get | pack_id: non-empty string | Yes | One pack document, including capability detail and skill briefs. |

| packs_route | goal: non-empty string | Yes | Route with an owning pack id, or null when no pack owns the outcome. |

## Skills teach practice, capabilities grant authority

A skill is practical guidance for a job. It can explain how to build a workbook, inspect a conversation, or plan a workflow, but it grants no authority and binds no tool. A pack card can associate skills with a domain, yet the association is not a permission grant and does not turn every skill instruction into an executable.

A capability is the authorization and contract boundary. Search returns candidates, get returns the exact schema, and run executes only a contract delivered in the current turn. The fetched descriptor states its required scopes, action policy, cost policy, asynchronous policy, and supported input and output shapes. Keep the distinction clear when explaining what Architect can advise and what it can actually execute.

Scope a tool search with a pack when the owning domain is known. Architect and MCP use pack_id; REST and CLI tool search use toolset. Without a scope, a goal is ranked against every catalog capability and shared words can surface an unrelated domain. A pack route followed by scoped tool search gives the agent a narrow, explicit starting point.

Packs do not bypass execution safeguards. Mutating calls must name a mode, the server never defaults to live, and paid live work can require a quote and a max_credits ceiling. Owner actions such as provider credentials or billing changes have their separate signed-in security flow. Read the exact capability contract, then use Credits and billing or Owner actions for the relevant boundary.

## When it goes wrong

If packs_get returns not_found, call packs_list again and choose one id from the active response. Do not repair the error by guessing an old or human-friendly pack name. Pack ids are lowercase identifiers such as tables, sequence, and workspace.

If route returns no owner, describe the desired durable outcome more clearly and then search the catalog without pretending that an unowned request belongs to a neighbouring pack. A route is deliberately allowed to return null. It gives an agent evidence that it should refine the goal instead of executing the first loosely matching operation.

If a scoped tool search misses an expected result, verify the pack boundary and inspect related capabilities on the pack card. A capability prefix and an outcome owner can differ for a documented related capability. If the searched capability is not delivered in the current turn, search or get it again before run; otherwise the runtime returns capability_not_fetched with the required repair.

If the route is correct but execution fails, investigate the exact capability rather than changing packs. A missing provider connection belongs to integrations, a suppression belongs to senders, and an existing thread belongs to Unibox. A schema validation, cost quote, required mode, or required-scope failure belongs to the fetched contract and has to be repaired with the fields and state that contract names.

If a user asks for several outcomes at once, route them independently before combining them in a plan. A workbook can supply the audience for a sequence, a sequence can create work for tasks, and a workflow can coordinate an outcome, but those connections do not remove the ownership boundaries. Check each created object in its own app surface and keep each capability result with the run that returned it.

Use the pack id from the current response, then retain the returned result identifiers for later reads.

The result can also carry a web_url for the corresponding object in the app.

## The tool catalog

Source: https://www.trydreamstate.com/docs/providers/tool-catalog

Search the tool catalog, read an exact schema, then run a capability.

The tool catalog is the discovery path for work Architect, MCP, the CLI, and REST can perform. Use it when you know the outcome but do not have a current capability contract, and use it again when workspace state or a provider connection may have changed.

The catalog protects a run from stale or invented identifiers: search for candidates, inspect an exact contract, then run only the contract delivered in the current turn. Route a broad outcome through Packs first when its owner is known, and review Credits and billing before a live action can spend credits.

## Search, get, then run

Search is the normal entry point. Give it a goal in plain language or explicit query terms, and optionally scope the request to a pack. Search ranks the active workspace catalog and returns candidates, a turn token, and top runnable_contracts. A returned contract marked fetched: true is already available to run in that turn.

Get reads one exact capability contract by id. An exact get does not require a previous search, because a ranking response can omit a valid known capability. Both search and a get with no turn token mint the current tool turn. Architect remembers contracts delivered in the conversation so it can use their schema without treating a previously fetched contract as an invented tool.

Run receives the capability id, its parameter object, a required mode, and the bound tool-turn token. The gateway uses the fetched contract to validate the input, scopes, action policy, cost policy, and asynchronous handling. A caller does not manufacture a token or replace the returned schema with a guessed parameter list.

The response follows the canonical envelope. A successful result carries its result data and metadata. A state-bearing result can carry a web_url for the corresponding app object, while the JSON identifier is the durable reference for another capability, run, or agent turn.

| Control | Arguments | Required | Result |

| tools_search | goal or query_terms, optional pack scope, optional limit | goal or query_terms | Candidates, runnable_contracts, and tool_turn_token. |

| tools_get | capability_id | Yes | Exact capability schema and a tool-turn token. |

| tools_run | capability_id, params, mode, tool_turn_token; optional max_credits and quote fields | Contract and mode | Capability result or structured refusal with repair. |

## Scope discovery without changing authority

A pack scope narrows search, but it does not grant authority or change the thirteen shared door controls. Architect and MCP call the field pack_id. REST and the CLI call the same wire-level filter toolset. The server maps the REST and CLI filter back to the pack identity so a scoped response can explain that discovery was restricted to that pack.

Scope a known domain because an unscoped search ranks the goal against every capability in the catalog. Shared words, a job title, or a city can otherwise rank an unrelated record, inbox, or knowledge feature ahead of the intended workbook or sequence operation. A route followed by a scoped search is therefore a practical way to keep a multi-domain goal aligned with the result that owns it.

Search results can identify a preferred composite operation when one contract builds an entire object. This is discovery guidance, not an instruction to skip schema review. Read the fetched input and output shape, confirm the workspace and pack, and verify the action policy before choosing a composite capability over several smaller writes.

Capability availability is workspace-specific. A public provider profile or a capability name in another workspace is not evidence that the selected workspace can use it. If a task depends on a provider, inspect Integrations and rediscover the operation after a connection changes. The catalog result, not a remembered provider label, is the readiness source.
ArchitectCLIMCPREST
Find the capability that reads this workspace credit balance. Route the goal first if needed, fetch the exact input and output contract, then show the contract without running it.
## Read the contract and choose the mode
The exact descriptor is the source for input fields, output fields, required scopes, pack id, action policy, cost policy, and asynchronous policy. It can say whether an operation is read-only, internally reversible, sending, publishing, enrolling, activating, or test-running. Do not infer any of those facts from a capability prefix, a marketing profile, or a superficially similar operation.

Every mutating call must explicitly name a mode. The server does not default a call to live and returns mode_required when a mutation omits one. Some contracts support only dry-run and live, so the fetched schema remains the authority for the allowed choices on a particular operation.

Use smoke_test when a caller needs only static schema and policy inspection. Use dry_run when the caller needs real workspace validation and a preview without business writes, provider spend, or outward action. Use live only for a deliberate execution after the contract, recipient, sender, connection, and cost conditions have been checked. This ordering makes an agent's first action explanatory rather than irreversible.

A tool contract does not replace the owner-action security boundary. Provider credentials, billing, ownership, API keys, webhooks, and related root actions require a signed-in session, fresh approval at the applicable tier, and an idempotency key. An API key cannot perform that signed-in owner flow. See Owner actions for its separate requirements.

| Mode | What it does | Write policy |

| smoke_test | Static schema and policy inspection. | No business write and no audit entry. |

| dry_run | Validation against real workspace state. | No business write, provider spend, or outward action. |

| live | Execution of the fetched capability. | The fetched action policy determines the effect. |

## Credits, quotes, and run results

The catalog uses the credit classes free, action, and dynamic. Credit class is only one part of the decision: the returned action policy tells the client the consequence, and the cost policy tells it how the exact capability is priced. Fetch both before assuming that a provider-backed or mutation-like name has a particular cost.

A live call that needs pricing returns quote_required with an estimate. Re-run the same live call with unchanged parameters and a max_credits ceiling. The server binds the quote to that tool turn. Architect's adapter explicitly tells the model not to copy a quote hash, because the gateway retains that binding for the returned turn rather than asking the caller to invent it.

The CLI fetches a turn token for tools run when one was not supplied. It caches a token only while a quote is pending, then forgets it after a paid run is admitted. CLI output deliberately omits the tool-turn token, so a terminal transcript does not become a reusable catalog contract. Use --turn-token only when the caller already has the current token for the contract it is running.

A run can return immediately or represent asynchronous work according to its contract. Use the run controls to read state, events, or cancellation status when the result names a run. The CLI waits for a terminal run state by default with a 120-second timeout; --no-wait returns an immediate response instead. This behavior does not alter the capability contract or the state of the underlying run.

A live quote is a run ceiling
A quote binds only when the caller repeats the same live request with an appropriate credit ceiling. Do not change parameters to make an estimate look cheaper, and do not interpret a quote as permission to bypass the sender, provider, or owner-action conditions of the fetched contract.
## When it goes wrong

If a run returns capability_not_fetched, search or get the exact capability in the current turn and run the contract that response supplied. The refusal includes a repair that names the needed get call. Do not retry the same guessed id or attempt to create a tool-turn token locally.

If the gateway returns catalog_changed or tool_turn_expired, the previous tool turn is retired. Architect removes that stale token and starts a fresh search. Follow the same recovery on another surface: rediscover the operation, read the new schema, and then validate the new contract before retrying a mutation.

If input parsing returns invalid_request, read the published schema and correct the parameter object. A malformed tools-run request receives a repair with the instruction to match the published schema. If the mutation lacks a mode, use the supported mode instead of expecting the server to select live.

If live work returns quote_required, preserve the parameters and apply an intended maximum credit ceiling. If a provider is missing or an account is not connected, fix that external readiness in Integrations, then search again. If a recipient is suppressed or a sender is unavailable, investigate the sender policy and sequence state rather than re-running the capability unchanged.

If an exact get says the capability is already fetched, retain the schema it returned earlier in the same conversation. If the model context no longer contains that schema, the adapter can deliberately forget the remembered contract so get delivers it again. This protects a compacted conversation from running a capability whose required fields are no longer visible to the agent.

If a search appears too broad, obtain the pack route and retry with its scope. If it appears too narrow, confirm that the outcome really belongs to the pack instead of removing the scope without explanation.

If a result contains a run identifier, read its current state before issuing a new execution request. This avoids creating a second attempt merely because an asynchronous result was not immediately terminal.

Keep a search result and its descriptor together in the work record. The result records why the capability was selected, while the descriptor records the fields and policy used for the attempted run.

The capability id alone is never enough evidence to reconstruct an earlier contract.

Refresh discovery when contract state is uncertain.

Then inspect the fresh result.

## Integrations

Source: https://www.trydreamstate.com/docs/providers/integrations

Integrations manages third-party connections and connection diagnostics.

Integrations connect a workspace to third-party provider accounts and provider-backed product functions. Use this page before a run needs a connection, then return to the pack that owns the intended result, such as a workbook, a CRM record, a sequence, or a social post.

The integrations pack owns authorization, credentials, connection health, diagnostics, and synchronization. It does not own sender identity or suppression policy, which belong to Senders and mailboxes, and it does not own the external-provider marketplace, which is described in Marketplace.

## What integrations own

An integration is the connection boundary between one workspace and a third-party provider account. The integrations pack owns connecting and disconnecting provider accounts, connector authorization, OAuth credentials and refresh tokens, provider health, connection diagnostics, and synchronization of workspace records or rows with a connected system.

This division prevents a connection problem from being mistaken for a data problem. For example, the CRM pack owns durable record truth, while integrations owns the provider connection behind a CRM. Social owns publishing and audience results, while integrations owns the credential needed to reach a social provider. Visibility owns measurement results, while integrations owns the provider setup behind connected analytics.

In the app, connection handoffs point to Settings, including the Integrations tab. Provider-specific catalog entries can instead point to the relevant settings destination, such as the outreach or LinkedIn settings area. The returned web_url, when present, is the app location for the created or state-bearing result; the JSON identifier remains the durable value for an API client.

Architect uses the same capability catalog as the other product surfaces. It can search for the integration capability, retrieve the exact schema, and then run the discovered contract. Do not assume that a profile in the public marketplace is itself a runnable operation or proof that the current workspace has access.

| Connection kind | When it appears | What stays separate |

| OAuth connection | The provider opens its authorization flow. | The connection is scoped to the workspace and provider. |

| Provider credential | A provider requires a protected credential. | The credential travels through a secret lease, not a tool parameter. |

| Managed provider | Dreamstate supplies a provider-backed product function. | Availability still depends on workspace configuration. |

| Connection handoff | A catalog capability returns the settings destination. | The browser completes the provider-specific setup. |

## Discover connection readiness

Start with the provider catalog rather than naming an undocumented command or passing a guessed schema. The active catalog includes integrations.providers_list for the currently connectable providers and integrations.connect_start for a connection handoff. The handoff is synchronous, free, idempotent, and records an internal reversible connection-handoff result.

A connection handoff resolves the selected provider for the workspace and returns the settings URL where the browser flow continues. An unknown or unavailable provider is rejected as invalid_request with a message that its provider_id is not connectable in that workspace catalog. Treat that as a catalog and workspace-state problem, not a reason to invent a provider identifier.

The public integration registry currently distinguishes connection types such as OAuth, workspace API keys, provider credentials, Dreamstate-managed providers, mailbox OAuth, and source-specific setup. It lists profiles for LinkedIn, X, Google Search Console, Google Analytics 4, HubSpot, Slack, mailboxes, GitHub, WordPress, Framer, and other products. A profile states the intended product relationship, not an entitlement promise for every workspace.

Missing connections block the provider-backed execution that needs them, but they do not block building a workbook, sequence, workflow, or other workspace system. Build the structure and validate its local state first. Connect the account when the work reaches a provider-backed step, then re-run discovery so the agent reads the current contract rather than relying on an earlier readiness result.
Architect
Find the connection needed to synchronize this workspace with HubSpot. Show the current readiness and the Settings destination. If it is not connected, tell me which workbook and CRM preparation steps can proceed without it.
## Credentials and browser handoffs
Credentials are not ordinary capability parameters. Several root-action schemas accept a secret_lease_id, which refers to a pre-staged protected lease. The documentation in those schemas says that the credential itself never travels in parameters and is available only inside the lease callback. Keep passwords, access tokens, and API keys out of prompts, copied request JSON, and shell history.

OAuth starts can be provider-specific. The mailbox OAuth start accepts only gmail or outlook and returns a single-use authorization_reveal_path that is valid for 120 seconds; the mailbox is not usable until the consent callback completes. CRM OAuth setup supports HubSpot, Attio, and Salesforce, while a deployment missing its client credentials returns a provider-specific <provider>_oauth_not_configured error.

A LinkedIn native connection expects a protected lease and an uppercase two-letter ISO country code. Its account type defaults to member. If the provider asks for a checkpoint, the follow-up uses the returned pending identifier and another protected lease. An unknown or expired pending identifier returns linkedin_checkpoint_not_found, so restart the connection flow rather than trying to reuse an old checkpoint.

The scheduler connection can be scoped to a sender account or be workspace-wide. Slack connection setup has a default_mode that defaults to architect; using draft limits Slack to producing drafts. These are provider-specific contracts, so inspect the schema returned for the exact capability before choosing fields or defaults.

Protected connection data
A provider connection can change who can reach an external system. Complete the signed-in settings flow and use its returned status instead of sending a secret through a prompt or a capability parameter.
## Connection effects and cost

A catalog entry exposes its own action policy, cost policy, asynchronous policy, required scopes, and schema. Read that entry before a live run. The catalog uses only the credit classes free, action, and dynamic; connection setup is not a substitute for checking the cost of the later provider-backed action.

When a live capability needs a price, the system returns quote_required with its estimate. Re-run the same call with unchanged parameters and a max_credits ceiling. That ceiling applies to the run, while the provider's external billing relationship remains governed by the provider connection. See Credits and billing for the quote and run-budget model.

Connection, disconnection, credential, and other owner actions are security-sensitive. They run from a signed-in session, never from an API key, require a fresh approval at the applicable tier, and require an Idempotency-Key. This security exception controls access to workspace ownership and external reach. It is not a spend approval step. The exact tier may be fresh_owner, workspace_admin, or current_member for mailbox authorization.

A provider-backed run can be read-only, internally reversible, externally sending, publishing, enrolling, activating, or test-running according to its catalog policy. Read the specific contract before treating a provider call as safe to retry. A calendar event create or update, for example, can contact invitees through the connected Google calendar, while a local events list reads stored workspace rows without calling a provider.

## When it goes wrong

If discovery returns invalid_request for a provider identifier, search the current provider catalog and select only a provider that is connectable in this workspace. The provider may be absent because the workspace has no enabled catalog entry, not because a different spelling will work.

If an OAuth start reports <provider>_oauth_not_configured, the deployment lacks the client credentials for that provider. Stop the setup attempt and use a provider that the workspace actually exposes, or ask the workspace owner to resolve the provider configuration. Do not enter a secret in a tool argument as a workaround.

If a mailbox authorization path expires, start a new mailbox OAuth handoff. If LinkedIn returns linkedin_checkpoint_not_found, restart the native connection flow because the pending value is unknown or expired. If a protected lease is invalid, reacquire the lease through the authenticated flow instead of retrying the same identifier indefinitely.

If a provider call finishes externally but its local finalize step fails, the result can be reconciliation_required. For calendar writes, that response is a 409 and does not trigger an automatic retry. Inspect the provider state and the local result before retrying so a second action does not duplicate an external event or notification.

If the failure is a missing connection, return to the settings handoff, complete it, and rediscover the tool schema. If the failure is a recipient, sender, sequence, or suppression rule, leave the provider connection alone and investigate the owning pack. This boundary is the fastest way to avoid changing credentials when the real problem is in outreach policy or application data.

## Senders and mailboxes

Source: https://www.trydreamstate.com/docs/providers/senders

Senders manages suppression, mailbox health, sender identities, and sender policy.

Senders controls the identities and policy boundaries used for outbound work. Use it to inspect mailboxes, social accounts, sending domains, rotation, health, or do-not-contact rules before a sequence starts delivery.

Senders is a control pack. Sequences and enrollment owns cadence and lifecycle, while an existing conversation belongs to Inbox. A sender setting can block delivery without changing the sequence's draft or recipient-selection logic.

## Sender policy and identity

The senders pack owns suppression, do-not-contact rules, mailbox health, rotation, sender identities, sending domains, and sender policy. It is the right boundary for an answer to "can this workspace send to this person through this channel?" It is not the right boundary for provider OAuth, an outreach cadence, or a reply inside an existing thread.

Connected social-account identifiers are available from senders.social_accounts.list. Social draft, publish, comment, and analytics contracts refer to those identifiers when an operation needs a specific account. Some content contracts accept no account id when the workspace has exactly one connected account for a selected channel; when several accounts exist, the returned account list is the safe source for choosing the intended identity.

Mailboxes are distinct from social accounts. The sender pack supplies mailbox reads, mailbox health checks, mailbox updates, rotation configuration, and capacity or purchase operations. A mailbox or domain configuration can control whether a later sequence step can run, but configuring it does not itself compose, publish, or enroll a sequence.

Settings is the app location for sender policy. Keep the sender identity separate from the recipient record: the identifier identifies who sends, while the recipient's email or LinkedIn URL identifies whether the sequence can deliver on a chosen channel. This separation makes a failed delivery diagnosable without changing the wrong account.

| Sender area | What it covers |

| Sender identity | Mailboxes, connected social accounts, sending domains, and rotation. |

| Mailbox health | Readiness, health, capacity, and sender policy before an outbound run. |

| Suppression | An email, domain, phone, company, LinkedIn identity, or X handle blocked from future outbound contact. |

| Imported policy | A Dreamstate worksheet import or a CRM sync that adds new blocked members. |

## Suppression is a workspace policy

A suppression blocks a stored email address, email domain, phone number, company, LinkedIn identity, or X handle from all future sends and outbound channels. Use it when the policy needs to survive a particular sequence, mailbox, or campaign. Removing a person from one enrollment does not express the same workspace-wide no-contact policy.

The sender pack can import suppressions from a Dreamstate worksheet. CRM lists can also stay in sync so new members are blocked automatically. These integrations add to the sender-owned local ledger; the integrations pack still owns the third-party connection that may make a CRM source available. Read Do not contact for the identifier scopes, imports, and recovery rules before changing a suppression.

Suppression writes converge on one normalized row. Repeating a write does not create a duplicate policy row, and deleting an already absent row remains safe. The write controls are synchronous, free, and internally reversible according to their catalog policies, but the result matters because future outbound channels will use the rule when deciding who can be contacted.

A reply, bounce, unsubscribe, suppression, decline, wrong-person result, or finished conversation ends outreach to that person across channels. Do not work around such a stop by changing the sender, sequence, or channel. Read the current thread and suppression state before retrying a delivery or making a policy change.

## Check readiness before a live action

Before a live outreach action, read the intended sender identity, mailbox readiness, sender health, daily capacity, timing policy, and current suppression ledger. Then read the target recipient data and the selected sequence state. These checks establish whether the action has an eligible sender and a contactable recipient; they do not send a message or change the sequence.

A sequence delivery plan reports blockers with four real kinds: no_connected_sender, suppressed_or_do_not_contact, missing_email, and missing_linkedin_url. Each blocker also records whether the affected channel is email or LinkedIn. Treat a blocker as a specific repair instruction rather than a generic send failure.

A missing sender blocks running or sending the affected step, but it does not block creating a worksheet, drafting a sequence, validating its configuration, or preparing an audience. Build those local artifacts first, then connect or select the needed sender before the execution step. A missing recipient email or LinkedIn URL is a recipient-data problem, not a reason to change the sender account.

Architect can inspect sender readiness through the live catalog. It should route sender policy to the senders pack, retrieve the exact schema, and preserve the result identifiers for a later read. The agent should not infer a specific mailbox from a profile label or assume that an account in another workspace is available here.
Architect
Before this outreach runs, inspect the selected sender, mailbox health, and do-not-contact policy for the recipients. Report every delivery blocker and its channel. Do not send, enroll, or change a sender setting.
## Sequence and sender boundary
A sequence owns templates, cadence steps, sends, reminders, follow-ups, LinkedIn engagement actions, campaign planning, launch, pause, and lifecycle state. The sender pack owns the identity and policy checks that make a delivery eligible. Publishing or enrolling a sequence does not itself send; sending starts only with an explicit start action in the sequence lifecycle.

Send capacity is paced over days rather than minutes. A capped or delayed cell can be pacing rather than a delivery failure. Read daily limits, sender health, selected channel, recipient identity, and suppression state before changing a schedule. A sender policy never turns a reply into permission for a further outreach attempt, and a new channel never bypasses a workspace stop.

Use a sender read when you need evidence about a mailbox or social identity. Use a sequence read for cadence, enrollment, validation, launch, or outcome totals. Use Inbox for an existing conversation. This three-way boundary avoids treating a delivery status as a conversation reply or treating a conversation state as proof that a sender was eligible to deliver a message.

Sender actions can carry different effects. A list or health read is read-only. Rotation configuration is a synchronous, internally reversible write and requires idempotency. Mailbox purchase or cancellation reaches an external provider and uses an idempotency boundary. Fetch the exact capability before changing policy because the catalog, not this conceptual page, defines its input, cost, scopes, and result shape.

Live sending reaches people
Verify the sender and the suppression policy before an explicit sequence start. A connected mailbox or social account does not override a recipient's no-contact state.
## Cost, modes, and results

Sender catalog entries disclose their own credit class, action policy, cost policy, asynchronous policy, and required scopes. Catalog credit classes are free, action, and dynamic. A capability with a sender noun is not automatically free or read-only, so inspect the fetched descriptor before relying on a cost assumption.

Every mutating action must name a mode. smoke_test inspects schema and policy without writing or recording an audit entry. dry_run validates against workspace state without business writes, provider spend, or outward action. live executes only after the returned contract permits it. The server returns mode_required instead of defaulting a mutation to live.

Paid live work can return quote_required. Re-run the same request with unchanged parameters and a max_credits ceiling. This is the credit consent boundary for the run. It is distinct from owner actions, which are security-sensitive changes such as credentials and require a signed-in session, fresh approval at the applicable tier, and an Idempotency-Key.

State-bearing results can include a web_url for the related screen in the app. Keep returned JSON ids as the source of truth, then use the URL to inspect the mailbox, sender, suppression, or related object. A result identifier lets a later run or an agent turn refer to the same state instead of guessing which sender configuration changed.

## When it goes wrong

If a delivery reports no_connected_sender, inspect the intended channel and connect or select an eligible sender. Do not edit recipient data or remove a suppression. If it reports missing_email or missing_linkedin_url, correct the needed recipient field and keep the selected sender configuration intact.

If the blocker is suppressed_or_do_not_contact, read the matching policy row and identifier scope. Do not move the person to another channel or sender. Resolve the workspace's policy outside the send attempt, then verify the final ledger before attempting any future outreach.

If delivery is delayed, inspect caps, health, timing policy, and sequence state before calling it failed. If the recipient replied, bounced, unsubscribed, declined, or is the wrong person, do not restart the lead's run. Read the full conversation and sender evidence, because a reply ends outreach across channels.

If a mutation returns mode_required, use a supported mode from the fetched schema. If it returns quote_required, retain the same parameters and provide the intended credit ceiling. If the action is an owner change, use the signed-in owner flow and idempotency key rather than trying to perform the action with an API key.

## Data providers and costs

Source: https://www.trydreamstate.com/docs/providers/marketplace

Data providers can require a connection or your own key before they can run.

Marketplace is the public catalog of provider profiles used by Dreamstate workspace work. Use it to understand what category a provider serves and how it is usually connected, then use the live capability catalog to verify that the workspace can run a specific operation.

A marketplace profile is not an executable entitlement, input schema, or price. The related Integrations page explains connection ownership, while Tool catalog explains how an agent finds the current runnable contract.

## What the marketplace shows

Marketplace presents public product profiles rather than an execution catalog. Each profile has a name, category, optional category tags, an authentication type, a short description, setup guidance, limits, and examples. This helps a workspace choose the right provider family without claiming that a live operation is enabled for every workspace.

The profile categories include Agent/MCP, Social, CRM, Enrichment, Source, SEO, AI Visibility, Webhook, Analytics, Billing, CMS, Communication, and Outbound. A provider can have extra tags when it belongs to more than one category. LinkedIn, for example, is shown as Social with Source and Outbound tags, so the catalog describes its product roles without turning it into a generic source query outside a workbook.

In the Marketplace screen, the search field filters provider name, description, category, tags, provider aliases, source keys, column types, and configured search terms. The category controls show the current number of matching profiles, and sorting is by name in ascending or descending order. An empty search result is a marketplace filter result, not evidence that a provider cannot exist in the live workspace catalog.

Marketplace cards label each entry as a workspace product profile. That label is deliberate: public documentation has no authority to reveal capability availability, schemas, authorization, or run behavior. Use the active catalog after sign-in for those facts, because readiness depends on the selected workspace and its configured providers.

| Profile category | Examples shown | Profile connection type |

| Agent and workspace surfaces | Dreamstate One API, Dreamstate MCP, webhooks | Workspace API key, OAuth, or signed HTTPS delivery |

| Social and communication | LinkedIn, X, Slack, mailboxes | Connected account or provider OAuth |

| CRM and outbound | HubSpot, Attio, Salesforce, Instantly | Workspace-enabled connector, OAuth, or provider credentials |

| Measurement and sources | Google Search Console, Google Analytics 4, DataForSEO, sources | Google OAuth, Dreamstate-managed provider, or source-specific setup |

| Content destinations | GitHub, WordPress, Framer | Provider connector or CMS credentials |

## Read the connection label

The authentication label describes the connection model a profile uses. Dreamstate One API is labeled as a workspace API key, while Dreamstate MCP is labeled as OAuth or a workspace API key. Webhooks are labeled as signed HTTPS delivery. Those labels describe the connected product surface, not a capability identifier that can be passed directly to an agent.

LinkedIn uses a connected LinkedIn account. X uses OAuth. Google Search Console and Google Analytics 4 use Google OAuth. HubSpot uses HubSpot OAuth, Slack uses Slack OAuth, and mailboxes use mailbox OAuth. Instantly is marked as provider credentials, while DataForSEO is marked as a Dreamstate-managed provider. The profile for AI Visibility is marked as Dreamstate-managed measurement.

Some profiles intentionally remain more general. Attio and Salesforce say they can be connected where enabled for the workspace. Enrichment Waterfall says it uses methods currently available to the workspace. Sources and Imports uses source-specific setup, Signal Sources can use provider OAuth, an API key, or a webhook, and GitHub, WordPress, and Framer each show their own connector or CMS credential type.

Read those labels as a setup conversation starter. They do not disclose raw credentials, automatically authorize a new provider, or guarantee a price. For connection problems, use the Settings handoff described on Integrations. For sending identity, domain policy, and suppressions, use Senders and mailboxes instead.
Architect
Find the marketplace profiles relevant to CRM synchronization and Google analytics. For each one, show its connection label, then search the live catalog for the exact capability and readiness needed in this workspace.
## From a profile to a runnable contract
Architect does not run a marketplace card. It starts with the shared tool contract: search for the outcome, read the matching tool descriptor, and run only a contract delivered in the current turn. Tool search returns a tool_turn_token and can include fetched runnable contracts. A run that does not have its contract from that turn is refused with capability_not_fetched and a repair instruction.

Search is the correct place to learn whether a provider-specific operation exists and whether it belongs to a particular pack. Use pack_id in Architect and MCP, or toolset on the REST search endpoint and CLI, when the task belongs to one pack. The two names express the same scope boundary on different product surfaces.

The exact fetched descriptor contains the input schema, output schema, required scopes, action policy, cost policy, asynchronous policy, and pack id. A marketplace profile cannot replace any of those fields. For example, the public page may say a source needs source-specific setup, while the live descriptor tells the client the actual fields, valid modes, and workspace conditions for one specific provider operation.

All mutating calls must specify a mode. The server never defaults to live and returns mode_required when the caller omits it. Use smoke_test for static schema and policy inspection without a write or audit record, dry_run to validate against workspace state without business writes, provider spend, or outward action, and live only when the fetched contract permits the intended execution.

## Cost and provider effects

The catalog uses three credit classes only: free, action, and dynamic. The class is not a marketplace category and does not by itself describe the external consequence. Read the action policy and cost policy of the exact capability before deciding whether a provider-backed run is read-only, internally reversible, sending, publishing, enrolling, activating, or test-running.

A live run that needs a price returns quote_required and an estimate. Re-run the same request with unchanged parameters and a max_credits ceiling to bind the quote. The ceiling limits that Dreamstate run. A person's yes, when the server requires one, is the paid-run consent rule, not the ceiling. The ceiling does not erase any separate commercial relationship with the provider shown in the marketplace profile.

Provider connection and credential actions are owner actions because they change who can reach an external service. They require a signed-in session, a fresh approval at the applicable owner, workspace-admin, or current-member tier, and an Idempotency-Key. This security rule is distinct from the normal paid-run quote flow. See Owner actions for that boundary.

A missing provider connection can block only the provider-backed run. It does not stop a user from building a workbook, preparing a sequence, drafting a workflow, or saving another workspace system. Keep the draft work separate, finish it in the pack that owns it, then complete the provider connection before the external step is needed.

A provider profile is not a cost quote
Check the fetched capability estimate and set a run ceiling before a live provider-backed action. Do not infer credit use, provider billing, or external effect from a marketplace category or profile description.
## When it goes wrong

If marketplace search produces no card, clear the category filter or change the public-profile search. If the provider still does not appear, treat that as an absent public profile. It is not a license to claim a hidden capability, and it does not establish whether the active workspace can run the provider.

If the live catalog rejects a guessed provider or connection request with invalid_request, search the current capability catalog and use the returned provider identifier. A provider can be absent from the workspace catalog even when a similar public marketplace profile exists.

If a run is rejected with capability_not_fetched, search and get the exact contract again in the same turn, then run that returned capability. If the request is mutating and returns mode_required, choose the mode supported by the contract rather than assuming live.

If a live request returns quote_required, do not change its parameters while trying to accept the price. Reuse the request shape with a suitable max_credits ceiling. If the blocker is a connection, complete the authenticated Settings flow and rediscover the descriptor before retrying the provider-backed action.

If the task is actually outbound sending, a CRM record update, a social post, or a worksheet row operation, inspect the owning pack after connection readiness is confirmed. Marketplace helps classify a provider, while the owning pack is responsible for the result and its lifecycle.

## Plays

Source: https://www.trydreamstate.com/docs/templates/plays

A play is an advisory order of steps toward one outcome.

A play is a proven order of steps toward one outcome. It is advisory: it names ordered capability ids, but it does not install a system, run a capability, or spend credits by itself.

Choose a play by its stage and the workspace need it describes. A blueprint is installable, and a reply playbook guides Inbox replies.

## Choose a play from the catalog

| Play | Catalog id | Stage | Use it when |

| Intent to outreach | intent-to-outreach | Any time | Use when the ask names an intent signal (hiring, posting, engagement, funding, tech, or job change) and the motion is signal source, then people follow-up, then qualification, then sequence enroll. |

| Run a 50-lead outbound pilot | outbound-pilot-50 | Week 1 | Use when you can state titles, segment, and geography in one sentence and you want a reviewed outbound pilot this week, starting at 25 leads and stopping at 50. |

| Warm network first | post-engagers-to-warm-sequence | Week 1 | Use when watched profiles post at least weekly, the ICP page is filled, and you want engagers captured, qualified, and only the qualified slice put into a capped warm sequence. |

| Capture a competitor engaged audience | competitor-audience-capture | Any time | Use when one or more public LinkedIn profiles repeatedly attract the founders, revenue leaders, or practitioners you sell to, and you want that audience captured and qualified before any outreach. |

| Turn an ICP into a scored account map | icp-to-account-map | Any time | Use when you can state segment, geography, size, and who is excluded, and you want one sourced, scored account list reused by later motions. |

| A daily ranked queue of warm leads | daily-warm-lead-queue | Any time | Use when at least one warm signal source is already armed and delivering, the ICP can be stated in one sentence, and you want one morning queue instead of separate feeds. |

| First win | first-win | Day 1 | Use in a new workspace to confirm workspace knowledge and produce one small scored worksheet. |

| Founder posting system | founder-posting-system | Week 1 | Use when workspace knowledge includes a Tone of Voice page and founder posts need a reviewable cadence. |

| Reply to meeting | reply-to-meeting | Ongoing | Use when a live sequence has unanswered inbox threads that need a response toward a call. |

| Visibility sprint | visibility-sprint | Month 1 | Use when a site and Search Console are available for a month of visibility work. |

| Speed to lead | speed-to-lead | Month 1 | Use when a trigger source should move qualified rows through a workflow. |

| Weekly review | weekly-review | Weekly | Use each week to review live GTM motions before choosing one change per motion. |

| Research hiring signals | signal-hiring | Any time | Use when hiring for a target role is an account signal. |

| Research hiring companies by size | hiring-companies-by-size | Any time | Use when company size and open roles identify accounts for people research. |

| Qualify post engagers | signal-engaged-person-posts | Any time | Use when selected LinkedIn profiles attract ICP engagement. |

| Review multichannel drafts | multichannel-linkedin-email | Any time | Use when LinkedIn and email copy needs review together. |

| Build an account-based list | cold-company-employees | Any time | Use when named target accounts need decision maker research. |

| Set up cold email infrastructure | email-infra-setup | Day 1 | Use before cold email when no two warmed mailboxes exist on a separate sending domain. |

| Migrate one Clay table | migrate-from-clay | Week 1 | Use when moving a single Clay people or company table into a Dreamstate worksheet. |

| Prioritize identified website visitors | website-visitor-outreach | Ongoing | Use when RB2B website visits are provisioned as a push-only source and visitors need CRM context before outreach. |

| 30-day GTM review | day-30-review | Month 1 | Use after 30 days of activity to decide whether to scale, change, or stop each live GTM motion. |

| Launch a client workspace | client-workspace-launch | Day 1 | Use when an agency operator needs a separate client workspace before installing client GTM plays. |

The catalog is the source for the ordered steps. Read the workspace state first, then choose a play whose stage and needs fit what is actually present.
ArchitectInspect the workspace state and list the catalog plays that fit it. For each match, explain its stage, needs, produces, and ordered steps. Do not run a play.

## Run the steps deliberately
After choosing a play, inspect the exact capability schema for each step before running it. Check the result in the app after every state-changing step. A play does not grant authority, so credits, modes, and each capability contract still apply.

## Do not confuse it with workflow play list

workflow.plays_list is a read of workflow subjects, growth experiments, and campaigns. It is not the play catalog and should not be used to choose an advisory catalog play.

workflow.plays_list has a similar name but reads running workflow subjects, growth experiments, and campaigns. It is not the advisory play catalog and does not select catalog steps.

If a play’s stage, needs, or produces do not match current workspace facts, do not force it. Read the catalog again, choose another play, or use a blueprint or recipe when the requested outcome is an installable system or fixed worksheet kit.

If a capability refuses a play step, report its typed failure and repair the prerequisite identified by that contract. Do not change a play’s ordered ids or claim that its advisory plan performed an action.

## Read the catalog before running

The blueprint catalog is the authoritative play catalog. Each play has an id, ordered capability steps, a stage, needs, produces, skill ids, and a leading metric where the catalog supplies one.

Stages distinguish when a play fits: day_1, week_1, month_1, ongoing, or weekly. Choose the stage from actual workspace state rather than treating every play as a required setup sequence.

first-win is a day_1 play. Its ordered work covers Context, a sourcing plan, a workbook, a worksheet, a row source with sampled run, an evidence column, and a score.

post-engagers-to-warm-sequence is the catalog play titled Warm network first. It is intended for the week_1 stage and connects workbook work with a sequence only after real workspace evidence is available.

outbound-pilot-50 is titled Run a 50-lead outbound pilot. It is a week_1 play and should be treated as an ordered plan, not as an instruction to send or enroll a person.

founder-posting-system is a week_1 play. Its social steps draft and schedule content only; the catalog decision says these steps never publish content.

reply-to-meeting is an ongoing play. Its steps read an existing Inbox conversation, classify it, and draft a response; drafting does not send a message to a person.

visibility-sprint is a month_1 play. It uses visibility baseline reads and one writing save, which keeps its outcome grounded in measured evidence and documented business knowledge.

speed-to-lead is a month_1 play. It uses workflow creation, linting or validation, and activation preview rather than presenting a workflow as a hidden running automation.

weekly-review is a weekly, read-only play. It uses runs, sequence analytics, worksheet qualification, and the credit ledger to review current operating evidence.
ArchitectInspect the workspace and the blueprint catalog plays. Recommend only the play whose stage, needs, and produces match the current state. List each ordered capability step, its mode, expected app check, and credit policy. Do not run a step.

## Execute each step as a contract
A named skill teaches the practice for a play but grants no capability. Architect uses a skill as guidance and still searches, fetches, and follows the exact schema for every capability step.

A play capability id must be known to the catalog. Before running it, use canonical discovery to search, get the exact contract, and inspect whether the returned contract is already runnable in the current turn.

Every mutating step must supply a supported mode. smoke_test inspects schema and policy, dry_run previews against real workspace state without business writes or provider spend, and live executes the requested work.

A play itself has no credit effect because it does not run work. Each capability step has its own cost policy and credit class, and paid live work can require a quote and max_credits ceiling.

Publishing a sequence and enrolling people do not send messages. A sequence is drafted, validated, published, enrolled, started, delivered, and replied through separate states; sending begins only on an explicit start.

A missing LinkedIn or email connection can block running or sending a step, but it does not block building the workbook, draft, or sequence structure described by a play.

After a state-changing play step, inspect the resulting workbook, document, sequence, workflow, or draft in the app. JSON ids are the source of truth, while a web_url can take the user to the exact state-bearing object.

A play can make a complex goal legible, but it does not compress product controls. Treat each ordered step as its own capability request with its own schema, state result, provider conditions, and credit policy.

## When it goes wrong

Start with the play’s real catalog entry and the workspace’s real state. If a plan cannot satisfy a prerequisite, stop at the capability failure, correct that prerequisite or select a better-fitting catalog entry, then re-check the app state before continuing. A play is advisory even when every step is valid.

Record the returned object id, its state, and any web_url after a successful write. This makes a later weekly review able to distinguish an installed object, a draft, a validated plan, and work that actually ran.

## Blueprints and the marketplace

Source: https://www.trydreamstate.com/docs/templates/blueprints

A blueprint installs a workspace system and supports saved snapshots.

A blueprint is an installable workspace system. It can create worksheets, columns, and a disabled workflow, and it can also represent snapshots that you save, share, or list on the marketplace.

Blueprints are different from plays, which only describe an ordered outcome.

## Inspect before installing

| Capability | Purpose | Credits |

| workspace.blueprints.list | List shipped installable systems and their requirements. | Free |

| workspace.blueprints.describe | Read one shipped system or saved workspace snapshot. | Free |

| tables.workbooks.create | Create the workbook the agent will fill. Do not install a blueprint kit. | Free |

The list names required integrations, required Context keys, and the tables, columns, and disabled automation a system creates. An agent reads that list and then builds the workbook itself. It does not install the system.
ArchitectList shipped blueprints and describe the one that fits. Do not install it. Build the workbook, attach the source, and add each column yourself.

## Use the preflight result
Resolve every missing integration or Context key before you install. Check the proposed tables, columns, and disabled automation in the preflight output, then verify that the installed objects appear in the workspace. A disabled workflow is a draft, not a running automation.

## When it goes wrong

If preflight reports a missing integration or Context key, correct that prerequisite and run preflight again. If the proposed system does not match the job, choose a different blueprint or use a recipe for a fixed worksheet kit.

If preflight reports a missing integration, connect the provider only when the workspace intends to use it. Do not create a connection merely to make a catalog item appear complete when its provider action is not needed yet.

If preflight reports a missing Context key, write the underlying factual document with its source rather than inventing a value to satisfy the prerequisite. Then re-run the free preflight.

If the object plan conflicts with existing work, stop before installation. Compare another blueprint, use a fixed recipe, or choose an advisory play when the request is a workflow of decisions rather than an installed system.

If an install fails after state changed, read the returned receipt and current workspace objects before retrying. A retry should use the exact known contract and should not duplicate tables or columns without inspection.

A successful blueprint workflow has a reviewed preflight, fulfilled prerequisites, a deliberate installation, and visible resulting objects. It is not complete merely because an agent found a catalog title.

The preflight result is a concrete object plan, not a generic recommendation. Preserve it while resolving a prerequisite, then compare the refreshed result with the intended workspace outcome before installation.

If the object plan changes, review the tables, columns, and automation again. A preflight can only describe the current workspace state and selected catalog system.

## Inspect the system

A blueprint is an installable workspace system from the blueprint catalog. It can create worksheets and columns, and some systems include a disabled workflow rather than a running automation.

Blueprint operations also support saved workspace snapshots that can be shared or listed on the marketplace. A snapshot is not an advisory play and should be inspected as a concrete workspace system.

workspace.blueprints.list is a free read that lists shipped installable systems and their requirements. Read the catalog before selecting a system so its requirements are part of the decision.

workspace.blueprints.describe is a free read for one shipped system or saved workspace snapshot. Use it to see the selected system rather than inferring its created objects from its title.

The product UI installs a shipped blueprint. An agent does not. Build the workbook, source, and columns with tables.workbooks.create, tables.table_sources.attach, and tables.columns.add.

A blueprint can name required integrations and required Context keys. A missing integration or Context key is a prerequisite result, not evidence that the install operation or the system itself is broken.

Preflight identifies proposed tables, columns, and disabled automation. Check every proposed object against the workspace’s existing structure before installation, especially when a similar workbook or workflow already exists.

Context requirements refer to durable workspace knowledge. Record product, buyer, competitor, or voice facts in Context, then use the required keys supplied by the selected system.

External provider connections belong to Integrations. Building a blueprint can proceed until a connection is needed, but a provider-dependent run or send can be blocked until the workspace connects the required provider.

A disabled workflow is a draft. It does not begin running, sending, enrolling, publishing, or spending merely because the blueprint installed its configuration.
ArchitectList the available blueprints, describe the selected system, and run a preflight. Report every prerequisite and every workbook, worksheet, column, and disabled workflow it would create. Do not install it.

## Install and verify
Installation is a state-changing operation. Fetch the exact install schema, choose an explicit supported mode, and inspect its cost policy before a live run rather than assuming that a free preflight makes installation free.

smoke_test inspects static schema and policy without a write or audit record. dry_run previews against real workspace state without business writes, provider spend, or outward actions; live executes the selected supported operation.

A capability’s catalog cost policy and credit class determine cost. When a live call needs a quote, use the returned estimate and rerun unchanged parameters with the max_credits ceiling the caller accepts.

Architect can use a blueprint as a plan, but it must still search and fetch each exact capability contract. The blueprint does not grant permission or skip the workspace, mode, or credit checks.

After installation, inspect the created workbook, worksheets, columns, and disabled workflow in the app. Keep the returned ids as the source of truth and use a web_url, when present, to reach the precise object.

Use the preflight as a comparison artifact, then verify the actual workspace objects after installation. A disabled workflow remains a draft until a separately chosen activation action runs.

## Reply playbooks

Source: https://www.trydreamstate.com/docs/templates/playbook-cards

Reply playbooks provide Inbox guidance for scenarios and sequence rules.

A reply playbook is guidance for Inbox replies. It records a scenario, tone, value proposition, sequence rule, and enforcement rule so a team can handle a recurring reply situation consistently.

Manage Playbooks at /dashboard/settings/playbooks. A reply playbook is not a catalog play, blueprint, or recipe: it guides replies rather than installing a system or creating a worksheet kit.

## What a reply playbook contains

| Guidance | How it helps |

| Scenario | Identifies the reply situation. |

| Tone | Sets the voice of the response. |

| Value proposition | Keeps the intended value clear. |

| Sequence rule | Connects the guidance to sequence behavior. |

| Enforcement rule | States the rule the guidance should follow. |

## Inspect guidance before replying

Start with the incoming message and the reply playbook that matches its scenario. Check the tone, value proposition, sequence rule, and enforcement rule against the actual conversation before drafting a response.
ArchitectRead the matching reply playbook and this Inbox conversation. Draft a response that follows the card's scenario, tone, value proposition, sequence rule, and enforcement rule. Do not send it.

## When it goes wrong
If no card matches, do not force a nearby scenario onto the conversation. Record the gap for the team, then create or update guidance only after you have checked the current card and the intended rule.

A card can guide a reply only when its scenario still matches the real conversation. If the thread has changed, preserve the actual customer context and report the mismatch rather than using a rule written for a different situation. Review the selected card, sender identity, thread, and workspace policy before you retain, revise, or replace guidance. The saved card should explain the resulting rule clearly.

If no card matches, report the gap. Do not force a nearby scenario onto the conversation, because that makes a card look like evidence when it is only guidance for a different case.

Before changing a card, read the existing scenario, tone, value proposition, sequence rule, and enforcement rule. Save a focused change, then read the card again in Settings.

If another editor changed the guidance, preserve the current card and merge the requested rule deliberately. A duplicate card with almost the same scenario makes future selection less reliable.

If the conversation or sender identity is unavailable, state that limitation and read the relevant Inbox state. Do not claim a draft was delivered or that an external provider received a message.

A completed drafting workflow shows the selected card, conversation, and draft in the appropriate app surface. A completed send workflow has the separate send receipt and provider result.

When guidance and the thread conflict, follow the real conversation and workspace policy, then record the playbook gap for later review. Do not change a customer-facing message merely to make a stale card appear correct.

Review the card with the actual thread before saving a revision. The visible scenario and rule give the next teammate a reason for the guidance rather than an unexplained text template.

## Draft from the right card

A reply playbook is workspace-scoped Inbox guidance. It helps a team handle a recurring conversation situation consistently without turning guidance into an automatic send.

The scenario identifies the conversation situation. Read the actual incoming message before choosing a card, because a similar phrase can belong to a different customer context or sequence state.

Tone defines how the reply should sound. It guides a draft, but the existing thread and the workspace’s current Context remain the evidence for what the response can truthfully say.

The value proposition records the relevant promised value. Check it against the conversation and product facts instead of pasting it into every response regardless of the sender’s question.

The sequence rule keeps an Inbox reply connected to sequence behavior. A reply in an existing conversation is different from net-new outreach, and a reply ends the lead’s run.

The enforcement rule states the constraint the guidance should follow. Keep that rule visible while drafting so a helpful response does not quietly violate a workspace policy.

Manage Playbooks at /dashboard/settings/playbooks. Confirm the active workspace before changing a card, because playbook cards are not global personal notes.

A reply playbook is not a catalog play or blueprint. Catalog plays are advisory ordered capability plans, and blueprints are installable workspace systems.

Read the matching card and the message thread before drafting. The correct success signal is a draft that follows the card and conversation, not a generated sentence with no link to the scenario.

Drafting is an internal preparation action. It does not send a message, and it should leave the user able to inspect the text, recipient, conversation, and rule before any distinct send action.
ArchitectRead this Inbox conversation and the matching reply playbook. Explain the scenario, tone, value proposition, sequence rule, and enforcement rule, then draft a reply. Do not send it.

## Treat sending as separate
A live send reaches a real person and is irreversible. Treat the thread, sender identity, message text, and provider state as facts to check at the send surface rather than as implied by a card.

Architect can use the inbox-replies skill for practice, then discover the exact Unibox capability contract for reads, classification, drafting, or sending. A skill grants no tool authority.

A mutating capability names a mode; the server never defaults to live. Use dry_run where the exact capability supports it to inspect an action against workspace state without an outward effect.

Card guidance has no independent credit cost. The cost policy belongs to the selected capability, and a paid live capability can return a quote that must be rerun with unchanged parameters and max_credits.

Verify the draft before selecting a send capability. Guidance helps an agent prepare a reply, while a real delivery is a separate external effect with its own contract and result.

## Credits and billing

Source: https://www.trydreamstate.com/docs/safety/credits-and-billing

Credits and billing are managed at the workspace boundary.

Credits are the execution boundary for credit-bearing Dreamstate work. Use the fetched capability contract before a run because it supplies the capability’s cost policy, accepted mode, input shape, and whether a live request needs a ceiling.

A credit ceiling controls one execution request. It does not change a provider connection, a sender policy, or the workspace plan. For a specific request budget, read Spend caps and budgets. For changes to billing, membership, or API keys, read Owner actions.

## Read the catalog credit class

The catalog contains three credit classes: free, action, and dynamic. A class describes the catalog category. It is not a promise that every capability in a broad subject area has the same price or execution rule.

Search for the outcome first, fetch the exact capability contract, then read its cost policy. This is important for an agent as well as a person: a capability id without its current contract does not provide an input schema, an estimate, or a permission to invent a price.

| Credit class | Meaning | How to use it |

| free | A catalog credit class for work that does not consume credits. | Read the fetched contract before assuming a related action is free. |

| action | A catalog credit class for a fixed action cost policy. | Use the contract and returned execution controls for the specific action. |

| dynamic | A catalog credit class where the contract determines the cost policy. | Use the estimate and quote returned for the unchanged request. |

The available classes are deliberately a short list. Do not translate them into a made-up allowance, a per-seat balance, or a provider price. The capability contract and the returned estimate remain the source for the actual operation.

## Get a quote before a priced live run

A live call that needs a price returns quote_required with an estimate. The caller then reruns the same call with unchanged parameters, the returned quote, and a max_credits ceiling. The server binds the quote to that rerun.

This sequence keeps discovery and execution separate. A search response tells you what a capability is. A fetched contract tells you the input and policy. A priced live request supplies the estimate path. Do not substitute another capability, alter the parameters, or assume that a prior estimate applies to a changed request.

A priced live run can consume credits
Read the returned estimate, set the ceiling for the amount you intend this single run to spend, and rerun the unchanged request with its quote.ArchitectFind the capability for this provider-backed task. Show its cost policy and estimate. If it returns quote_required, rerun the unchanged request with the returned quote and a maximum of 200 credits.
Architect can use the same catalog path as the other doors. It should report the fetched contract and quote rather than state an unverified price. A person can then decide the ceiling to send in the execution envelope.

## Keep credits in the execution envelope

The ceiling and quote sit beside params in the canonical run input. They are execution-envelope controls. A capability’s own fields stay inside params, exactly as the fetched schema describes them.

| Field | Type | When required | Meaning |

| mode | Execution control | Required by a mutating call | Names the requested execution mode. The server does not default a mutation to live. |

| max_credits | Nonnegative number | When the fetched contract says live needs a credit ceiling | A run-wide ceiling beside params, not a capability parameter. |

| quote_hash | Quote value | For a priced live rerun after quote_required | The value minted by the prior dry run for the same unchanged request. |

| params | Capability-specific object | As published by the fetched contract | The operation input. Do not move execution controls into this object. |

Keeping these values outside params lets a caller reuse a published capability schema without adding budget fields that the capability does not own. It also means a contract can state when a ceiling is required for a live call without changing the operation’s business inputs.

For the server, max_credits is an optional finite nonnegative number. A caller should still only send it when the fetched capability contract calls for a live credit ceiling. A number is not evidence that a capability is priced.

## Workspace billing plans

Dreamstate lists Growth at $99 per month with a 3-day free trial. Pro is $249 per month. These are plan prices, not a statement of credit allowances, seats, provider usage, or a price for any individual catalog capability.

Billing checkout, seats, tier changes, cancellation, credit purchase, and overage affect the workspace’s money or access. They are root capabilities with the signed-in owner-session and fresh owner-action authorization rule. The rule is security for workspace ownership and billing changes, not a normal step for a priced run.

Do not try to perform a workspace billing change through a broad API key. Follow the owner-action route, retain its idempotency key for any retry, and inspect the resulting response before assuming the plan or billing state changed.

## Separate cost from provider setup

A provider can need a connected workspace account, a workspace credential, or the customer’s own provider key. That readiness is owned by the integrations domain. It can block provider-backed execution, but it does not rewrite the cost policy in a capability contract.

A missing LinkedIn or email account can block running or sending a step without blocking the work of drafting a workbook, sequence, or workflow. Build the workspace system, confirm the provider readiness, then discover and run the exact capability that performs the provider-backed task.

When a live request returns an error, use its stable code and repair data. quote_required asks for the quote flow. credentials_required identifies missing provider credentials. They are different conditions and need different repairs.

## When it goes wrong

If a priced live request returns quote_required, do not reinterpret it as a successful run. Preserve the intended capability and parameters, obtain the returned quote, set a ceiling, and rerun the unchanged request. If the request changed, start the quote flow again for the changed input.

If a provider says credentials_required, inspect the connection or credential state under integrations. Do not add a credential to a chat prompt or capability parameter. Connecting and disconnecting credentials are owner actions because they change who can reach an external system.

If you need to change the plan, checkout, seats, billing tier, cancellation, or credit purchase, do not present it as an ordinary credit run. Return to the signed-in workspace session and use the owner-action flow. For a request retry, preserve the idempotency key rather than starting a duplicate money or access change.

For every other refusal, inspect the envelope’s error code, message, details, and repair. The exact fetched contract is still the source of truth for whether the operation is available, which modes it accepts, and which execution controls it requires.

## Spend caps and budgets

Source: https://www.trydreamstate.com/docs/safety/spend-caps

Paid work can use a quote and a maximum credits ceiling.

Spend caps set the maximum Credits a fetched live run may consume. Use a cap after you have inspected the exact capability contract and its estimate, especially when a provider-backed operation can require a quoted price.

The cap belongs to the execution envelope, not the capability's params object. That keeps the whole-run limit visible while the fetched capability schema continues to define only its own inputs. Read Credits and billing for credit classes and Tool catalog for discovery and current-contract rules.

## Execution controls for a priced run

A run request separates capability parameters from execution controls. Parameters describe the particular action, such as a worksheet, provider, recipient, or content artifact. Mode, the credit ceiling, quote binding, and tool-turn token describe how the gateway may execute the fetched capability. Moving a ceiling into params changes neither the run policy nor the capability schema.

The fetched contract is the authority for whether a live ceiling is required. A client should not attach a random maximum to a read-only capability or infer that a similarly named capability uses the same price. The descriptor exposes the action policy, cost policy, credit class, scopes, supported input, and asynchronous policy for the capability actually selected in this workspace.

Mode is required for every mutating call. smoke_test inspects schema and policy without a write or audit entry. dry_run validates against real workspace state without business writes, provider spend, or outward action. live executes the fetched contract. Some capabilities support only dry_run and live, so always use the returned supported-mode list.

The tool-turn token ties the run to the contract delivered in discovery. It is not a credential, a quote, or a spend authorization. It proves that the caller is running a capability the current turn already delivered. A run without a delivered contract is refused with capability_not_fetched and a repair.

| Field | Type | Required | Meaning |

| mode | Execution enum | Mutating calls | The explicit smoke_test, dry_run, or live mode supported by the fetched contract. |

| max_credits | Nonnegative number | When a live credit ceiling is required | The execution-wide credit ceiling beside params. |

| quote_hash | Returned quote binding | Quoted priced live call | The quote minted for the same live request and bound by the server. |

| tool_turn_token | Turn token | When supplied by discovery | The current contract-discovery binding, not a credential or cap. |

## Reuse the quoted request

A live capability that needs a price returns quote_required with an estimate. The repair is to repeat the same live request with unchanged parameters and a max_credits ceiling. The server binds the quote to that tool turn, so a caller does not generate a quote hash or copy one from an unrelated request.

The ceiling limits that Dreamstate run. It is not the person's yes. When the server requires a yes, that is the paid-run consent rule. The ceiling does not change the third party's own billing relationship. A provider connection can still be required, and a provider-backed live action can still have an external effect according to its action policy. Check both before treating a quote as sufficient evidence that the call is ready.

Keep parameters unchanged when accepting a quote because a different worksheet, recipient, provider, or request body is a different execution decision. If the task needs a different target or amount, start from the fetched contract again and obtain a new estimate. A ceiling is not a way to turn a changed request into the earlier priced request.

Architect should first explain the estimate and the intended ceiling, then run the original request only when the user has already asked for that effect. Above the server's row or provider-spend limit, follow the paid-run consent rule. Owner actions have a separate security rule.
ArchitectREST
Run a dry run for this enrichment job. If it returns a quote, explain the estimate and rerun the unchanged request live with a maximum of 200 credits. Report the final result or machine-readable refusal.
## Credit classes and effects
The catalog has three credit classes, and only these values appear in the customer surface. A class tells a caller how the catalog categorizes cost, but it does not tell the caller whether the effect is a read, a reversible workspace change, an external send, a publish, an enrollment, or an activation. Read the action policy together with the cost policy.

A read-only capability can be free, but a free operation can still have a policy or state consequence that needs review. A dynamic or action-priced capability can be synchronous or asynchronous. The descriptor's asynchronous policy tells the client whether it should look for a run identifier and use run reads or events before judging the work terminal.

Use the returned output shape to record evidence. State-bearing results can include a web_url to the corresponding object in the app, but JSON ids remain the source of truth for later reads. A lost client connection does not prove that no credit-consuming run was admitted.

| Credit class | Meaning |

| free | A catalog credit class for an operation with no credit charge. |

| action | A catalog credit class for action-priced work. |

| dynamic | A catalog credit class whose charge is determined by its contract and run. |

## Caps are not owner approval

A spending ceiling is not a root-action approval. Root actions change who owns or can reach the workspace or its money, including billing, seats, API keys, integrations, credentials, webhooks, and ownership changes. They require a signed-in session, fresh approval at the applicable tier, and an Idempotency-Key, never an API key alone.

The owner-action security check is separate from ordinary capability cost. A run can have a credit ceiling and still need the owner path because it changes an external credential or workspace authority. Conversely, a quoted provider-backed action can need a maximum-credit ceiling without being a root action. Keep these two controls distinct in client code and operator explanations.

Before a live run, check the capability's effects, provider readiness, sender policy, recipient state, and mode. A ceiling only controls potential Dreamstate credit use. It cannot correct a suppressed recipient, a missing sender, a missing provider connection, a required idempotency key, or an invalid request schema.

A ceiling controls paid work
Inspect the returned estimate and action policy before live execution. Dry_run gives workspace-state validation without business writes, provider spend, or outward actions.
## When it goes wrong

If a mutation returns mode_required, choose a mode supported by the fetched contract. Do not rely on the server to select live. If a caller cannot decide between dry_run and live, run the static or workspace-state validation first and preserve the returned evidence for the later decision.

If live work returns quote_required, retain the same capability and parameters, then repeat the request with the estimate's bound quote and an intended maximum-credit ceiling. If the user wants different parameters, do not reuse the quote: rediscover the contract and get the estimate for the new work.

If the gateway returns capability_not_fetched, search or get the exact capability in the current tool turn. If the token is expired or the catalog changed, start fresh discovery. The ceiling does not make an unfetched or stale capability runnable.

If the action needs a connection, sender, or recipient field, repair that condition in its owning pack before retrying a paid live call. If the action is a root action, use the signed-in owner flow and idempotency key. Check the final run result or receipt before issuing another request after a network interruption.

## Sending safety

Source: https://www.trydreamstate.com/docs/safety/sending-safety

Sequence work keeps publishing, enrolling, starting, delivery, and replies separate.

Sending safety keeps sequence design separate from outward delivery. Use it when you are building a Sequence, selecting people for Enrollment, checking a Sender, or investigating why a person did not receive a message.

The Sequences and enrollment page explains the sequence lifecycle, while Senders and mailboxes explains the identity, health, rotation, and policy behind delivery. For a workspace-wide exclusion, use Do not contact.

## Separate the lifecycle

A sequence moves through distinct states: drafted, validated, published, enrolled, started, delivered, and replied. Building the sequence does not wait for a LinkedIn or email account. A missing account blocks the relevant send step, not the ability to draft or validate the plan.

Publishing and enrolling do not send. An explicit start is the event that begins delivery. This distinction lets you review the audience, steps, channel, and sender policy before any person is contacted, and it lets a team prepare the full system even while a connection is unavailable.

Each channel shares one contact history. Email and LinkedIn messages for the same person belong in one sequence, one view, and one launch. A channel is not a route around a stop in another channel.

| State | What happens | Delivery result |

| Drafted | The sequence and its steps are being prepared. | No delivery occurs. |

| Validated | The sequence is checked before it is used. | No delivery occurs. |

| Published | The sequence definition is made available for use. | No delivery occurs. |

| Enrolled | A person is included in the sequence. | No delivery occurs. |

| Started | The sequence is explicitly started. | Outbound delivery can begin. |

| Replied | A person has responded. | That person's run ends. |

## Check the recipient before delivery

Before starting a sequence, inspect the selected rows, the recipient data needed by each step, and the current do-not-contact ledger. The sender policy can block a recipient with suppressed_or_do_not_contact, and the enrollment result identifies the blocked channel as email or LinkedIn.

A reply, bounce, unsubscribe, suppression, decline, wrong-person response, or finished conversation ends outreach to that person on every channel. Do not use another sender, another sequence, or another channel to continue contact after one of those outcomes.

Existing conversations are handled in the existing conversation. Read the whole thread before drafting a response. If the person asks to unsubscribe or declines, do not pitch and confirm that the relevant suppression is present.

Company pause on reply can apply when several people work at one company. Treat it as a reason to inspect the company context and active outreach before extending a campaign to another contact.

## Check sender policy and capacity

The senders pack owns suppression, do-not-contact rules, mailbox health, rotation, sender identities, sending domains, and sender policy. The sequence pack owns the sequence, cadence steps, templates, sends, reminders, follow-ups, and lifecycle state. Keep those responsibilities separate when you investigate a delivery issue.

Before a live start, look at sender health, sending hours, cooldowns, daily caps, suppressions, and remaining headroom. Sends spread over days rather than minutes. A capped cell or delayed send is pacing, not a failure, so read the sender state before changing a sequence step.

Missing sender information produces a specific blocker. A missing email means the row lacks the email data for an email step. A missing LinkedIn URL means the row lacks the URL for a LinkedIn step. No connected sender means the channel lacks a usable sender connection.

Reaches a real person
Starting a sequence can create outward delivery. Check the selected recipients, sender policy, channel data, and current suppressions before starting it.
## Build and review without starting

Architect can build a sequence from the requested audience and outcome, then show the selected steps and sender constraints. It uses the outreach skill for sequence practice and the available capability contract for the exact action. The skill teaches the work but grants no tool authority.

Ask for a validation or a dry run when you need to inspect a plan against current workspace state without business writes, provider spend, or outward actions. Every mutating call names a Mode; the server never defaults a mutation to live.

A useful review has the recipient set, the intended channel, the sender identity, the sequence step order, suppression results, and the state that will start delivery. The app records outcome totals including enrolled, active, sent, replied, meetings, bounced, unsubscribed, and failed.
Architect
Validate this sequence, its selected recipients, sender policy, and do not contact results. Do not start delivery. Show every blocker and the channel it affects.
## When it goes wrong
If a result contains suppressed_or_do_not_contact, list the matching suppression entries and verify the recipient identity. Keep that person out of future outreach; changing a channel does not bypass the stop.

If a result contains no_connected_sender, connect or select a sender for the affected channel. If it contains missing_email or missing_linkedin_url, correct the recipient data. Those conditions block sending, but they do not block building the rest of the sequence.

If the send result is unclear, read the current conversation before retrying. A conversation status does not prove delivery. If a person replied, bounced, declined, or unsubscribed, their run has ended, so investigate the stop rather than re-enrolling them.

If delivery is delayed, inspect caps, cooldowns, sending hours, and headroom. Do not treat paced delivery as a reason to create duplicate recipients or add another sender for the same person.

If a sequence was published or people were enrolled but nothing was sent, inspect whether an explicit start happened. Those earlier lifecycle states intentionally do not create delivery. Record the state you found, then correct the missing setup or data and validate again before a live start. Keep the evidence with the sequence rather than relying on a memory of the last run.

## Do not contact

Source: https://www.trydreamstate.com/docs/safety/do-not-contact

Do not contact rules suppress future outbound messages across channels.

Do not contact is the workspace suppression ledger for outbound work. Use it when a person, a company, an email domain, a phone number, a LinkedIn identity, or an X handle must not receive a future outbound message.

The ledger belongs to the senders pack, while a Sequence determines the cadence and the Inbox holds an existing conversation. Read Senders and mailboxes before configuring sender capacity, and read Sequences and enrollment before starting outreach.

## What a stop means

A suppression stops future sends and outbound channels for the stored identifier. The sender policy covers an email address, an entire email domain, a phone number, a company, a LinkedIn identity, or an X handle, so the scope depends on the identifier you add.

This is not a mailbox pause and it is not a warmup setting. Listing suppressions never changes mailbox pause or warmup, which makes the list safe to inspect before changing any outreach plan.

A reply, bounce, unsubscribe, suppression, decline, wrong person, and a finished conversation each end outreach to that person across channels. Do not use another sender, another sequence, or another channel to work around one of those stops.

A stop also does not send a reply. When a send result or stop result is unclear, read the current conversation and the current sequence state before retrying. A conversation status alone is not evidence that a message was delivered.

Outbound effect
Adding a suppression changes who future outreach can reach. Check the identifier and its scope before adding a person, company, or domain to the ledger.
## Choose the right scope

Use an individual email address, phone number, LinkedIn identity, or X handle when one contact must be excluded. Use a domain when no address at that domain should receive outbound email, and use a company when every prospect at that company must remain excluded.

The workspace-wide list capability returns entries by email, domain, company, phone, or LinkedIn identity. The focused list capabilities separate email addresses, domains, companies, phones, LinkedIn identities, and X handles when you need to audit one kind of entry.

A company-level entry is broader than an individual contact entry. If only one person asked not to hear from you, a company block would exclude other prospects at that company too. If the whole organization has opted out, a company block matches that policy better than many individual rows.

The system normalizes do-not-contact rows. Writes converge on a unique normalized row, and a repeated delete remains safe when the row is already absent. That behavior helps an agent recover from a retry without creating duplicate blocks.

| Identifier | Use it when | Outbound consequence |

| Email address | One address must not receive email outreach. | Future outbound delivery is suppressed for that identifier. |

| Domain | Every address at one domain must be excluded. | Outbound email is stopped for addresses at that domain. |

| Company | The whole company must remain excluded. | Prospects at that company stay excluded. |

| Phone, LinkedIn, or X | A channel-specific identity must not receive outreach. | The matching outbound safety gate excludes that identity. |

## Add and import rows

Architect can add one identifier or prepare a review of the current ledger. It uses the same capability catalog that is available through the other product surfaces, so it first discovers the exact schema before it writes a row.

For a prepared list, import parsed CSV rows with senders.suppressions.import. One request adds up to 500 rows. For a worksheet, use senders.suppressions.import_from_worksheet to add normalized values from selected Dreamstate worksheet columns.

A CRM import copies selected list-member identifiers into the local ledger and does not write back to the CRM. A saved CRM sync can add new members automatically, and its controls can list sources, list saved syncs, create or update a sync, pause or resume it, request immediate processing, or stop the sync. Stopping a sync does not remove the entries it already blocked.

Use a worksheet import when the source of truth is a Dreamstate workbook. Use a CRM import or sync only after checking the connected list and filter. The sender pack owns the ledger, while the integrations pack owns a third-party connection behind a provider.
Architect
List the current do not contact entries for this workspace. Add jane@example.com as an email suppression, then show the result without changing any sender settings.
## Review before a send
Before a live outbound run, inspect sender health, sending hours, cooldowns, daily caps, suppressions, and remaining headroom. Drafting, previewing, and validating can happen without an email or LinkedIn account connected, but a missing account blocks sending on that channel.

Send capacity is paced over days rather than minutes. A capped cell or delayed send is pacing, not necessarily a failure. Check the intended channel and the stored suppression before changing a sequence, because changing channels cannot bypass a stop.

For a sequence plan, the useful evidence is the current suppression list, the recipient's existing thread, sender health, and the selected sequence state. A sequence's outcome reporting distinguishes sent, replied, bounced, unsubscribed, and failed totals, so use those states to investigate what happened rather than inferring delivery from a draft.

Do not contact writes are synchronous, have no credit charge, and make an internal reversible change. Listing entries is synchronous, read-only, and has no side effect. These properties do not make the policy unimportant: the write changes the people an outbound plan may reach.

## When it goes wrong

If an enrollment reports suppressed_or_do_not_contact, the recipient is blocked by the sender safety check. Read the matching suppression list, confirm the identity and scope, and keep the sequence stopped for that recipient while the workspace resolves the policy.

If the blocker is no_connected_sender, missing_email, or missing_linkedin_url, fix the sender or recipient data instead of changing the suppression record. A missing connection blocks running or sending the affected step, not the ability to build the sequence.

If an import is larger than 500 parsed CSV rows, split it into bounded requests. If a CRM sync is unexpectedly adding entries, list the saved sync and the available CRM source, then inspect the selected list or filter. Removing a saved sync leaves existing blocks in place, so review those rows separately when the policy changes.

If a person replies, declines, bounces, or unsubscribes after an earlier outreach attempt, do not restart the sequence through another channel. Read the full current thread. For an unsubscribe or decline, do not pitch and confirm that the relevant suppression is present.

## Owner actions

Source: https://www.trydreamstate.com/docs/safety/owner-actions

Owner actions use signed-in sessions, fresh approval, and idempotency keys for sensitive workspace changes.

Owner actions change who controls a workspace, who can reach it, what it costs, or where it can connect. Use this page before changing ownership, members, billing, keys, credentials, webhooks, triggers, or an external destination.

This security rule is separate from normal credit-bearing work. For the run credit boundary, read Spend caps and budgets. For provider connections, read Integrations.

## What owner actions cover

Root capabilities cover changes that affect workspace control or an external destination. The set includes deleting an account or workspace, transferring ownership, changing or removing members, and changing the workspace's billing state.

It also includes billing checkout, seat and tier changes, cancellation, credits purchase, overage actions, and API key creation, reveal, and revocation. A key belongs to one workspace, one actor, explicit scopes, and its own spend policy.

Connection work is included because credentials and destinations determine what the workspace can reach. The protected changes include LinkedIn, X, Slack, Google, scheduler, Stripe, mailboxes, signal sources, custom HTTP, pixel signing secrets, webhooks, workflow triggers, trigger secrets, and social content destinations.

| Purpose | Examples |

| Workspace and membership | Account or workspace deletion, ownership transfer, member changes, and role changes. |

| Billing and keys | Checkout, seats, tier, cancellation, credit purchase, overage, and API-key creation, reveal, or revocation. |

| Connections and destinations | Integration credentials, social destinations, mailboxes, webhooks, workflow triggers, and secrets. |

## Use a signed-in session

Root capabilities run only from a signed-in session. They never run from an API key. This keeps the security decision attached to the current person instead of a reusable programmatic key.

The server applies the tier that the root action defines: fresh_owner, workspace_admin, or current_member for mailbox authorization. The tier is a property of the action, not a client-selected request field.

A fresh signed-in session matters when a change can remove access, expose a secret, cancel a plan, or connect the workspace to an outside system. The current session is checked before the root action executes.

Security-sensitive change
Owner actions need the signed-in session and a fresh approval at the tier set for that action. They also need an Idempotency-Key so a retry has one stable identity.
## Prepare the request

First discover the exact capability contract. The tool catalog returns the input schema, action policy, required scopes, cost policy, and asynchronous policy for the selected capability. Do not infer fields from a similar workspace action.

Use one idempotency key for one intended mutation. The REST route accepts the key in the Idempotency-Key header or as the top-level idempotency_key field. A header and body value must match when both are present.

A mutating call also names a Mode. The server does not default mutations to live. Use a supported mode from the fetched contract, and use a dry run to validate against real workspace state without business writes, provider spend, or outward actions.
Architect
Explain the exact owner-action requirements for changing this workspace setting. Show the capability contract, the signed-in session tier, and the idempotency key requirement before making any change.
## Understand the result
A successful state-bearing result can include web_url, which points to the exact object in the app. Keep the JSON identifiers as the source of truth and use the link to inspect the object in the appropriate workspace screen.

The action can affect access, money, a credential, or an outside system. Record the returned identifiers, the final workspace state, and the destination that changed. This makes later investigation possible without guessing which request made the change.

An owner action is a security exception, not a general spend or sending control. Normal actions run under the quote and maximum-credits ceiling their fetched contract requires, and a paid run above the server's row or provider-spend limit also waits for the user's yes (see the spend caps page). Do not add owner-action security language to an ordinary sequence or provider run.

Before changing a connection or a destination, identify the workspace, the actor, the requested scope, and the external system affected. Before changing billing or membership, identify the current workspace state and the intended end state. Those checks make the confirmation specific: a user can see whether they are changing a mailbox, a social destination, a role, a plan, or a key, rather than receiving a generic warning about a write.

## When it goes wrong

If the route returns destructive_approval_required, the request is not coming from a current owner session at the required tier. Sign in to the workspace with the appropriate member session, then retry the intended action from that session.

If it returns idempotency_key_required, include an Idempotency-Key with one to 255 characters. Keep that exact key for a retry of the same intended action, rather than making a new key after a network interruption.

If it returns idempotency_conflict, the header and body key disagree. Send the same key in both places or send only one. The server does not select a winner between two different values.

Delegate execution is different: the approved step mints its key on the server. A caller key in the header, top level, or params is refused. Send the delegate step token without a caller idempotency key, because using the minted key preserves the already-created operation identity.

If a mutation has no mode, the route returns mode_required. Fetch the selected capability schema, choose one supported mode, and retry with the same action details. The server refuses to guess whether a security-sensitive change should be live.

If the requested capability is not the action you intended, stop before retrying. Search the catalog again, fetch the exact contract, and compare its description, scopes, and input fields with the workspace change you need. A nearby capability can affect a different destination or a different part of workspace access.

## Capability ids and naming

Source: https://www.trydreamstate.com/docs/reference/capability-ids

Capability ids identify catalog operations across the Dreamstate surfaces.

A capability id names one operation in the active Dreamstate catalog. Treat an id as a value returned by current discovery, not as a command constructed from a product noun, a pack name, or a remembered identifier.

Every customer-surface run uses the same search, get, and run contract. This protects a client from a renamed, unavailable, unfetched, or workspace-inapplicable operation, and it keeps the id connected to its real schema, effects, cost policy, and result shape.

## Discover the current identifier

Search starts from an outcome or query terms. It returns candidate capabilities from the active workspace catalog, a tool_turn_token, and top runnable contracts. When a candidate says fetched: true, the response already delivered that contract for this turn. Otherwise, get the chosen id before trying to execute it.

An exact get accepts an id and retrieves its contract even when a search ranking did not contain it. This is important because search is a ranking operation, not an exhaustive authorization decision. Get is the correct operation when a client has a current id from a prior documented result and needs to verify its schema again.

Scope a search when the outcome's pack is known. Architect and MCP use pack_id; REST and CLI use toolset for the same search boundary. Scope narrows discovery only. It does not grant permission, change a capability's action policy, or turn a skill instruction into an executable operation.

Use Packs to distinguish a workbook from a CRM record, a provider connection from a social outcome, or a suppression from an outreach cadence. Then use scoped discovery to obtain candidate ids. This prevents a shared word in a broad prompt from selecting a capability in an unrelated pack.

| Stage | Arguments | Required | Result |

| Search | goal or query_terms; optional pack scope and limit | goal or query_terms | Candidate ids, runnable contracts, and tool_turn_token. |

| Get | capability_id | Yes | Exact input and output contract with a current token. |

| Run | capability_id, params, mode, tool_turn_token | Fetched contract and mode | Capability result or structured error. |

## Read the contract attached to an id

An id is not enough to call an operation. The exact descriptor supplies the input schema, output schema, required scopes, pack id, action policy, cost policy, and asynchronous policy. Read those fields before a run because the identifier alone does not tell a caller whether the operation reads, writes a draft, sends, publishes, enrolls, activates, or starts an asynchronous job.

Capability input belongs in params when the run schema says so. Execution controls such as mode, max_credits, a quote binding, and the tool-turn token sit beside params in the execution envelope. Do not add an id suffix, an undocumented field, or a user value to an identifier in an attempt to reconstruct a capability schema.

The output schema is equally important. It tells a client which ids, status values, records, receipts, or run references it can safely read. A state-bearing result can also carry a web_url for its app location, but JSON ids remain the durable source of truth for later API calls.

Skills teach operational practice, but they do not grant authority and do not bind an id. Packs help a client route the outcome, but they do not create an id. Only the active catalog descriptor establishes a capability's executable identity and the rules for one particular run.

| Descriptor field | Why it is read with the id |

| id | The canonical catalog identifier returned by search or get. |

| pack_id | The pack that owns or scopes the capability in the active catalog. |

| input schema | The exact fields, types, required values, and validation rules for params. |

| output schema | The result shape the caller can interpret after ok is true. |

| action and cost policy | The consequence, credit policy, and other execution facts for this operation. |

| async policy | Whether the caller should expect a result immediately or track a run. |

## Run only a fetched id

Run requires the id, the exact parameter object, a required execution mode for mutations, and the current token that binds the delivered contract. The gateway refuses an id whose contract was not delivered in the current turn. This rule blocks a client from running a memorized identifier after its schema, policy, or workspace availability may have changed.

Use smoke_test for static schema and policy inspection without business writes or an audit entry. Use dry_run for real workspace-state validation without business writes, provider spend, or outward action. Use live only when the fetched contract permits the intended execution. The server returns mode_required rather than defaulting a mutation to live.

A live call that needs pricing returns quote_required. Repeat the same call with unchanged parameters and a max_credits ceiling. The quote binds to the tool turn, so a caller should not reuse a quote from another capability or alter the request in an attempt to accept the earlier estimate.

Root actions are a special security boundary. A capability that changes ownership, billing, credentials, integrations, API keys, webhooks, or other owner-controlled state requires a signed-in session, fresh approval at the applicable tier, and an idempotency key. Its id still comes from catalog discovery, but an API key alone cannot satisfy the owner-action path.
ArchitectCLIMCPREST
Search for the capability that lists available workspace integrations. Show the returned id, pack, action policy, input schema, and output schema. Do not run it until the fetched contract is visible.
## Store evidence, not guessed ids
Store the search result, descriptor, returned id, tool-turn token, and result identifiers together in the operation record. Search explains why the candidate was selected, the descriptor explains the submitted fields and policy, and the result explains what actually happened. A bare id lacks this decision trail.

The CLI automatically obtains a fresh token through tools get when a caller runs a capability without --turn-token. CLI output omits a tool-turn token, which prevents a terminal response from being treated as a reusable contract. A direct API client should pass a token only from current discovery and should refresh discovery when a token is retired or the contract is uncertain.

For an asynchronous capability, preserve the returned run id and use the run controls to inspect state and events. Do not infer failure merely because the initial response is not terminal, and do not issue a second request with a different id while the original run is still the relevant source of truth.

A public marketplace profile, app label, or capability-like string is not a source of executable ids. Those surfaces can explain a domain, but the current catalog determines whether a workspace may discover and run the matching operation. Return to Integrations when connection readiness is the blocking condition.

## When it goes wrong

capability_not_fetched means the gateway did not deliver the requested contract in the current turn. Search or get the id again, retain the returned token, and run the descriptor it supplied. Do not repair this refusal by copying an identifier from a different workspace, tool turn, or documentation page.

catalog_changed and tool_turn_expired retire the old token. Start a fresh search, then read the new descriptor before retrying. A stale token cannot be made current by changing its text or by resending it repeatedly, because the gateway will return the same retired-turn refusal.

invalid_request means the submitted input does not match the published schema. Use the error code, details, and fetched contract to correct fields. If a mutation returns mode_required, select one of the contract's supported modes; if it returns quote_required, preserve parameters and apply the intended credit ceiling.

If a scoped search finds no suitable id, confirm the pack boundary before broadening it. If an expected provider operation is missing, inspect provider readiness and rediscover after the connection is resolved. If a sender or recipient blocks delivery, repair sender policy or recipient data rather than searching for a different capability id to bypass the blocker.

If the client has lost the earlier schema, get the id again in a current turn. A capability id alone cannot reconstruct parameter names, defaults, effects, or result fields. The safety of the catalog flow comes from keeping the id attached to its actual contract until the run has a canonical result.

A current descriptor also identifies the active workspace boundary. Keep the workspace, capability id, and result id together when writing an audit record or handing work to another agent.

Do not use a search match as proof that an external effect completed. Search discovers a contract. Only a successful run envelope, its receipt, or its run status reports execution evidence.

The same rule applies to a description copied from a skill. A skill can name a recommended practice, but it cannot provide the current parameter list or replace the catalog's workspace-specific availability decision.

Read-only capabilities still benefit from discovery because their output schema determines the fields a client may safely use. An id is stable only as an identifier, never as a complete response contract.

Before a later run, refresh a descriptor when the previous response no longer provides its schema. This avoids executing with fields remembered from a contract that has since changed or left the current model context.

Discovery remains the source of executable identity.

Inspect the returned contract.

## Envelope and errors

Source: https://www.trydreamstate.com/docs/reference/envelope-and-errors

The canonical envelope communicates success and failure information.

Canonical API responses tell you whether the operation succeeded before you inspect its result. Use this envelope for capability discovery and runs, and use the fetched capability contract for the contents of data.

For cursor results, see Pagination. For request replay, see Idempotency.

## Read a successful response

{
"ok": true,
"data": {},
"meta": { "trace_id": "00000000-0000-0000-0000-000000000000" }
}Successful responses carry ok: true, capability-specific data, and metadata. State-bearing results can also carry web_url, which points to the related object in the app while the JSON id remains the source of truth.

## Read a refusal

{
"ok": false,
"error": {
"code": "mode_required",
"message": "A mutating call requires mode: smoke_test, dry_run, or live.",
"details": {}
}
}Failures carry an error object with code, message, and optional details. Handle the code in software and use the message and details to guide a person or agent to the repair.

| Field | When present | Meaning |

| ok | Always | Boolean outcome. Branch on this field before interpreting data. |

| data | Success | Capability-specific result. Its shape is defined by the fetched contract. |

| meta.trace_id | Success metadata | Trace identifier for the response. |

| error.code | Failure | Stable program-facing failure code. |

| error.message | Failure | Human-readable explanation. |

| error.details | Optional failure detail | Structured details when the refusal supplies them. |

## Repair by code, not message text

mode_required means that a mutating call needs an explicit mode. capability_not_fetched means you must search or get the capability in the current turn. quote_required means a priced live call needs its returned quote and a credit ceiling.
Architect
Show me the error code from this failed run, the repair in its details, and the exact request I should retry.
## Keep envelope fields separate from result fields
The envelope is common across catalog discovery and execution, while the contents of data are capability specific. Branch on ok before reading data. Then use the fetched output schema to interpret names, ids, status values, records, receipts, or run references inside the successful result.

Do not assume every success has the same data keys. A tool search can return candidates, runnable contracts, and a tool-turn token. A tool get returns an exact capability descriptor. A capability run can return a business result, a receipt, a run reference, or another output shape defined by that contract.

Metadata identifies the response and its gateway context. The trace id is useful when an operator needs to connect an observed response to support investigation. It is not a capability id, a retry identity, a credit quote, or a replacement for a state-bearing result identifier.

State-bearing data can include web_url. Use that app URL to inspect the object shown to a person, but preserve the returned JSON ids for programmatic reads. A web URL is navigation evidence, not the canonical identity of a workspace object.

| Envelope field | When present | Meaning |

| ok | Always | Boolean outcome. Branch on this field before interpreting data. |

| data | Success | Capability-specific result. Its shape is defined by the fetched contract. |

| meta.trace_id | Success metadata | Trace identifier for the response. |

| error.code | Failure | Stable program-facing failure code. |

| error.message | Failure | Human-readable explanation. |

| error.details | Optional failure detail | Structured details when the refusal supplies them. |

## Common error codes and repairs

A failure begins with ok: false. Read error.code as the stable program-facing branch, then use error.message and optional structured details to present the repair. Do not parse a human message to invent a new request, because the code distinguishes input repair, discovery repair, pricing, security, and provider-specific states.

mode_required means a mutating request omitted the execution mode. Select a mode supported by the fetched contract. The server never chooses live by default. Use smoke_test for static policy inspection, dry_run for real workspace validation without a business write, and live only for deliberate execution when the contract permits it.

capability_not_fetched means the current turn did not receive the contract for the id being run. Search or get the exact capability again, keep its returned turn token, and run the supplied schema. A remembered id, a marketplace profile, or a skill instruction is not a substitute for discovery.

quote_required means a priced live operation needs the estimate returned for the same request and a maximum-credit ceiling. Do not change the capability parameters while accepting the quote. If the intended work changed, fetch and price the changed contract rather than retrying an old quote.

invalid_request means the envelope or capability input failed the published schema. Use the details and the current descriptor to correct field names, types, or required values. A malformed tools-run body receives a repair instructing the caller to match its published schema before retrying.

not_found means the named current resource or metadata object was not found. For a pack, list the active packs before retrying get. For a state-bearing result, retain returned JSON ids and the selected workspace rather than constructing a path from a human label.

## Work through a response safely

First read ok. On success, preserve the data ids and trace id, then decide whether the result is final or points to an asynchronous run. On failure, preserve the code, message, details, trace id, and request identity so a person or client can make one evidence-based repair instead of sending a second ambiguous request.

For a search response, inspect the returned candidate id, pack, and runnable contract. For a get response, inspect the input and output schemas before creating params. For a run response, inspect the returned business result or run reference before interpreting a client timeout as failure.

If a response reports a run id, use run reads and events to learn its state. An asynchronous operation is not necessarily failed because its first envelope is not terminal. Preserve the run id and the original request identifiers instead of issuing a duplicate execution while the returned run remains the source of truth.

If an external provider change completed but its local finalization did not, a capability can return reconciliation_required. Inspect the provider state and the local result before retrying. The envelope reports the machine-readable condition, while the fetched capability contract explains its own reconciliation semantics.

Use idempotency for a retryable live mutation. The retry key is not the trace id or tool-turn token. See Idempotency for header and body placement, root-action rules, and durable receipt fields. Keep the same key when retrying the same uncertain execution.
ArchitectCLIMCPREST
Read this response envelope. Report ok, trace id, data ids or error code, the repair from details, and whether the result requires a run-status read. Do not retry until you identify the exact failure class.
## When it goes wrong
If the response has ok: false, do not read it as a successful data shape. Branch on error.code, retain trace id and details, and make the repair the code names. A 400 does not identify one universal cause: it can be malformed input, missing mode, missing idempotency, or another explicit refusal.

If a tool token is expired or the catalog changed, start new discovery and use the current descriptor. If a sender, provider connection, or recipient field is blocked, correct the condition in the owning pack before retrying. An envelope error is evidence about the failed request, not permission to bypass another policy.

If a live request needs a quote, preserve its parameters and add the intended credit ceiling. If it is an owner action, use the signed-in session and fresh approval path with an idempotency key. These are distinct repairs, and the envelope's code tells a client which one applies.

If a client lost the response after sending a mutation, inspect the returned run or durable receipt where the capability exposes one before retrying. Retrying with a new idempotency key because the response was lost can create a separate operation rather than recovering the earlier attempt.

Keep the envelope alongside the request context. The selected workspace, capability id, execution mode, and returned trace id make an error actionable without treating a generic message as evidence of another result.

A success envelope does not mean every downstream provider result is permanent. Read the capability-specific fields and any run state that it returns, particularly when a contract declares asynchronous execution.

A failure envelope does not expose a replacement capability. Return to discovery if the failure identifies a stale or unfetched contract, then validate the new descriptor rather than substituting a similar id.

The message is for people, while the code is for stable branching. Preserve both, because a user needs the explanation and a client needs a reliable classification for retry, recovery, or stop behavior.

Use structured details only as the response supplies them. Do not presume that every error includes the same nested fields, because details are optional and capability-specific evidence can differ by refusal class.

A response can help an agent choose the next read without authorizing a write. Search, get, and result state are evidence surfaces; a later mutation still needs its fetched contract and applicable execution controls.

For an ordinary live capability, credits and a maximum ceiling govern priced work. For owner changes, signed-in authority and a fresh approval govern security. The envelope reports which condition prevented execution.

If a server returns a provider-specific error, retain its code and returned details with the trace id. Then inspect the connected provider, recipient, or workspace state named by the fetched capability contract.

Never replace a failed response with a fabricated success record. The canonical envelope is the only response evidence a client has until a later read, receipt, or run-status response confirms the outcome.

## Pagination

Source: https://www.trydreamstate.com/docs/reference/pagination

Pagination uses cursors to traverse collections.

List and run results can be paginated. Use the cursor returned by a response as an opaque continuation value, process that response's items, and stop only when next_cursor is null.

Pagination belongs to the exact fetched output and input schema for a list operation. Read Envelope and errors before interpreting the enclosing result, and read Capability ids before using a list operation that has not been discovered in the current workspace.

## Pagination fields

A paginated result returns the current items array and continuation fields. The request can accept a cursor and limit only when its fetched schema defines them. A caller must not add cursor to a capability that does not publish it, because the exact input schema is the authority for supported request fields and their accepted ranges.

next_cursor is opaque. It is a value issued by one response for one operation and workspace context. Do not calculate, parse, trim, append to, or replace it. Pass it unchanged as the next request cursor only after the current page is processed and only while the response says another page exists.

has_more and next_cursor agree in the response contract: has_more is true exactly when next_cursor is not null. Treat next_cursor as the continuation value and has_more as a convenient boolean for UI and loop control. A final page has null next_cursor and false has_more, even when the final page still has items to process.

The item shape is capability-specific. A run list can return run records, a run-events read can return event records, and another list capability can return its own workspace objects. Do not assume that all item arrays have an id field with the same meaning. Read the fetched output schema before persisting or displaying rows.

| Field | Type | When present | Meaning | Default |

| limit | integer | Optional when a capability supports it | Maximum items to return, subject to the fetched schema range. | Capability-specific |

| cursor | opaque string | Optional after first page | Continuation returned by the preceding response for this operation. | None |

| items | array | Result field | The current page of capability-specific result records. | [] when no records |

| next_cursor | opaque string or null | Result field | Pass it as cursor for the next page, or stop when null. | null on final page |

| has_more | boolean | Result field | True exactly when next_cursor is not null. | false on final page |
Representative page shape
{
"items": [],
"next_cursor": "cursor_from_this_response",
"has_more": true
}
## Continue from the returned cursor
Start with a first request that omits cursor unless the fetched contract explicitly gives you a starting cursor. Process every item returned in that page. If next_cursor is a string, submit that same string in the next request. Repeat until the response returns next_cursor as null. This sequence is the only supported way to traverse a cursor result.

A limit is a request-size preference only when the contract supports it. Use the range in the current input schema, not a remembered default from another list. A smaller limit can make an interactive reader more responsive; a larger valid limit can reduce request count. Neither choice lets a caller skip cursor ordering or assume that the total result set is stable while other workspace changes occur.

Preserve the response that issued each cursor. It records the selected workspace, operation, current items, trace id, and continuation. A cursor copied from another operation or another workspace is not a generic page number. If client state loses the issuing response, restart discovery and list again rather than constructing a replacement cursor.

Architect can iterate a list page by page. It should report the current page's evidence, retain the returned continuation, and stop when it sees null. An agent should not claim that it processed every record after only seeing the first page, and it should not use a raw item count as proof that a later page does not exist.
ArchitectCLIMCPREST
List the current runs a page at a time. Process every item in each returned page, pass each next_cursor unchanged into the next read, and stop only when next_cursor is null. Report the final page count and run ids.
## Controls that expose cursors
The shared run controls include a list of canonical runs needing attention and an events read for one run. The events control takes a run id and can take a cursor and limit. Read the run id from an earlier response, then use the returned event cursor only for that run's event stream. A run id and an event cursor have different meanings and cannot substitute for each other.

Capability-specific list operations define their own fields and limits. The catalog descriptor exposes the exact input schema for a selected operation, including whether cursor and limit exist. Search or get the capability before sending a paginated request, especially when a provider connection, workspace scope, or feature availability can affect the live contract.

The CLI supports dreamstate runs list, dreamstate runs events <run_id>, and other canonical run commands. Architect and MCP expose runs_list and runs_events. These are shared controls, not capability ids, but their argument schemas remain the authority for cursor use and result shape.

A result may be synchronous while its items describe asynchronous work. A runs list page is a read of known run state; a listed run can still be active. Read its status or events before deciding that a run succeeded, failed, or needs cancellation. Pagination reads evidence, it does not change the lifecycle of the listed run.

| Control | Arguments | Page result |

| runs_list | optional cursor, optional limit | Current run page with its continuation fields. |

| runs_events | run_id, optional cursor, optional limit | Event page for one run with its continuation fields. |

| Capability list read | Contract-specific cursor and limit where supported | The schema-defined item page and continuation. |

## Use each response as the source of truth

Cursor pagination does not promise a hand-built snapshot across unrelated changes. Treat every returned page as the source of truth for that request. If records change while a client walks pages, retain the returned ids and trace data, then make a fresh read when the application needs a later view of the current workspace state.

Do not deduplicate, sort, or merge pages by an assumed identifier before you read the capability's output schema. A particular capability may expose a natural object id, an event id, a receipt id, or no universally named id at all. The output contract determines the safe merge key and the semantics of duplicate-looking records.

A paginated success still uses the canonical response envelope. Check ok before reading items. On failure, retain error.code, details, and trace id. A failed continuation does not authorize substituting a cursor from another operation, and a success page does not authorize a later mutation without its fetched contract.

When a response provides a web_url for a state-bearing object, use the URL for app navigation and preserve the JSON object id for later reads. Do not infer the next cursor from URL query text. Cursors are transport values produced by the API response, while web URLs are user-facing navigation destinations.

## When it goes wrong

If a continuation returns invalid_request, read the current request schema and error details. Check that cursor is exactly the value from the preceding response and that limit is within the published range. Do not repair the failure by trimming, decoding, or inventing a cursor value.

If the operation returns capability_not_fetched, search or get the list capability in the current turn before running it. If the tool turn expired or the catalog changed, begin fresh discovery and use the new descriptor. A cursor does not make an unfetched or stale contract runnable.

If a run read reports an active or asynchronous result, keep its run id and continue reading status or events instead of starting another run. If events are paginated, use each returned cursor only with the same run id. A later event page is evidence about that run, not a retry instruction for the original capability.

If a network failure occurs after a page response is received, persist the page and its next_cursor before making the following request. If the response itself was lost, make a fresh read and compare returned evidence; do not assume a guessed continuation recreates the lost page.

If a client must mutate an item selected from a list, fetch the mutation capability and validate its current contract separately. Listing an item does not deliver a mutation contract, does not establish a quote, and does not bypass sender, provider, idempotency, mode, or owner-action requirements for the later effect.

A cursor is scoped to its response sequence. Save it with the operation name and the selected workspace so a later process does not accidentally apply a valid-looking continuation to a different list.

Process the current items before requesting another page. This preserves the evidence trail between each batch of records and the continuation that produced the next batch.

Treat null next_cursor as completion, not an error. The final item page can contain records, so completion means there is no additional page, not that the current page was empty.

Limit controls page size, not the total scope of the operation. Continue only according to the returned cursor and stop condition rather than assuming a selected limit retrieves the complete collection.

Preserve trace ids with pages that need later investigation. They identify the response while item identifiers identify the returned business records or runs.

## Rate limits

Source: https://www.trydreamstate.com/docs/reference/rate-limits

Rate limits describe request limits for API use.

Rate limits protect Dreamstate API and MCP access from request bursts. Treat a 429 response as a request-level refusal, not as an empty catalog result, a missing provider record, or a completed capability run.

The active limit depends on the authenticated identity and on the capability family. Discovery, ordinary API work, externally effective work, and credential or root work can therefore receive different refusal codes even when they originate from the same workspace.

## Limit families and their scopes

The API-key middleware applies a per-key limiter, a workspace limiter, and additional family limiters for external-effect and credential or root capabilities. The pre-auth middleware runs before API-key lookup. It keys verified signed-in sessions by user id and other traffic by client IP.

All listed API and pre-auth limits use a 60,000 millisecond window. The table gives the actual families exported by the middleware, not a suggested client configuration. A client should read the returned refusal rather than assume that its next request used the ordinary per-key bucket.

| Family | Limit | Keyed by | Refusal code | Why this bucket exists |

| Per API key | 100 requests per minute | One authenticated API key | rate_limited | Prevents a single key from exhausting the standard request budget. |

| Per workspace | 120 requests per minute | All authenticated keys in one workspace | workspace_rate_limited | Key rotation does not multiply a workspace budget. |

| External effect | 20 requests per minute | A workspace calling a capability classified as external effect | external_effect_rate_limited | Calls that create an external effect use a lower family budget. |

| Credential or root | 10 requests per minute | A workspace calling a credential or root capability | credential_root_rate_limited | Credential and root capability requests use the lowest family budget. |

| Pre-auth IP | 300 requests per minute | Anonymous, invalid, or API-key-shaped traffic from one client IP | ip_rate_limited | The pre-auth path limits traffic before API-key lookup. |

| Pre-auth session | 2400 requests per minute | A verified signed-in session user | session_rate_limited | A verified session is keyed by user id instead of a shared network address. |

Two API keys in one workspace share the workspace budget. The middleware test sends seventy ordinary requests with one key and fifty with another, then verifies that the next workspace request receives workspace_rate_limited. A second key is not a way to continue after a workspace refusal.

An external-effect capability can be refused before the ordinary per-key or workspace ceiling. The middleware identifies external-effect ids from catalog effect classification, then applies the workspace family bucket. Credential and root capability ids use a separate family bucket with their own code.

## Read the 429 response

Every refusal from this middleware returns HTTP 429 and sets Retry-After. The JSON body carries the stable code, a readable message, the same retry interval in seconds, the window duration, and the limit that applied. Persist the code with your request telemetry so a client can distinguish a key issue from a workspace or family burst.
Representative API-key refusal
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
"error": {
"code": "rate_limited",
"message": "100 requests per minute per API key exceeded",
"retry_after_seconds": 60,
"window_ms": 60000,
"limit": 100
}
}
| Response field | Type | When present | Meaning | Default |

| HTTP status | number | Always on refusal | 429 identifies a rate-limit refusal. | Not applicable |

| Retry-After | HTTP response header, integer string | Always on refusal | The number of seconds before a retry can be attempted. | Not applicable |

| error.code | string | Always on refusal | The stable code for the limiter that refused the request. | Not applicable |

| error.message | string | Always on refusal | A readable explanation of the exceeded family budget. | Not applicable |

| error.retry_after_seconds | number | Always on refusal | The retry interval represented in the JSON response. | Not applicable |

| error.window_ms | number | Always on refusal | The window duration used by the limiter. | 60000 |

| error.limit | number | Always on refusal | The request count allowed for the family in that window. | Family-specific |
The retry interval is calculated from the limiter reset time when one exists, otherwise from the configured window. It is at least one second. In the API-key middleware test, a per-key refusal returns a 60 second JSON interval and a Retry-After: 60 response header.

Use the fields in the response instead of deriving an interval from local clock assumptions. The server may be shared across instances, and the middleware is designed so that its enforced budget is not only a local process counter.

The response limit names the bucket that stopped the request. Keep that number with the error code when you report an integration issue. A later request may reach a different bucket, so an earlier ordinary-read refusal does not prove that an external-effect call will receive the same code.

## Retry without changing the request

Wait for the returned retry interval before scheduling another request. Preserve the same capability parameters, mode, quote, turn token, and idempotency identity when the operation itself is a retry. Rate limiting changes when a request can be retried. It does not change the fetched contract for the capability.

If your client owns a queue, pause only the work that shares the refused bucket. A per-key refusal concerns that API key. A workspace or family refusal can affect other workers in the same workspace, so continuing those workers immediately can create more 429 responses.
ArchitectRESTThis run returned HTTP 429. Read its error code and retry_after_seconds, identify whether the key, workspace, external-effect, or credential/root family was limited, then wait for that interval before retrying the same request.
The example intentionally retries the same request after the server-provided interval. For a live mutation, pair this behavior with Idempotency so a request that was accepted before the network response is not treated as a new operation.

## Understand the classification

A reply through unibox.context.thread_reply_send is classified as an external effect; tables.contacts.list is standard. The middleware classifies workspace.api_keys.create and workspace.account.delete as credential or root work. These examples explain the family model, not a substitute for discovering the current capability contract before a run.

REST run paths expose the capability id in the path. MCP requests expose it inside a tools_run call body. The limiter extracts that id to classify the request family, which keeps the same family logic available through both doors.

External-effect requests can reach people or providers
A lower external-effect ceiling is independent of the credit policy and mode in a capability contract. On a refusal, wait for the interval. Do not resend rapidly with another key or reinterpret the response as a provider result.
## When it goes wrong

A 429 is recoverable after the stated interval. The correct repair is to use the returned code and retry data. Do not fall back to a guessed capability id, do not silently switch the workspace, and do not treat the refusal as a completed run.

If the code is rate_limited, reduce or queue requests made by the relevant API key. If it is workspace_rate_limited, coordinate work across keys in that workspace. If it is external_effect_rate_limited or credential_root_rate_limited, pause the respective family rather than ordinary read work.

If an unauthenticated or invalid credential request receives ip_rate_limited, wait before retrying from that client IP. A verified signed-in session uses session_rate_limited instead, because the pre-auth middleware can key the request by its verified session user. Authentication errors and capability input errors have their own responses, so retain the exact code.

After the interval, send one controlled retry and inspect its response. The test advances the clock beyond one window and verifies that the per-key request succeeds again. That is the client behavior to model: wait, retry the same intended operation, then decide from the new envelope.

## Idempotency

Source: https://www.trydreamstate.com/docs/reference/idempotency

Idempotency keys make owner action requests safe to retry.

Idempotency gives a retryable capability run one stable request identity. Use it when a network interruption leaves you unsure whether a live mutation reached Dreamstate, especially for a root action that changes workspace ownership, money, members, keys, credentials, or integrations.

The identity belongs to the execution envelope, not to a guessed capability schema. First search and fetch the capability contract, then send the exact same request and key when retrying. The result envelope and its capability-specific data are described in Envelope and errors.

## Choose one request identity

The REST gateway accepts a key in the Idempotency-Key header or in the top-level idempotency_key body field. Both are representations of one value. Sending the same value in both places is valid, but different values are not.

The gateway also checks a nested params.idempotency_key when a request is not delegated. A capability that explicitly declares that parameter owns it. For other capabilities, the gateway creates one accepted execution identity rather than allowing a top-level and nested value to drift apart.

| Argument or header | Type | Required | Meaning | Default |

| Idempotency-Key | HTTP header, string | Optional, required for root capabilities | A caller-supplied retry identity. It must contain 1 to 255 characters. | None |

| idempotency_key | JSON body, string | Optional | The body form of the same retry identity. If both locations are used, the values must match. | None |

| params.idempotency_key | Capability parameter, string | Only when the fetched capability schema declares it | A capability-owned field. Otherwise the gateway moves or rejects it so there is one request identity. | None |

| delegate_step_token | JSON body, string | Optional | An externally minted execution binding. It uses a server-minted key and refuses caller keys. | None |

| approval_id | JSON body, string | Root capability only | A fresh owner-action authorization identity. It cannot be combined with a delegate step token. | None |

| mode | JSON body, enum | For mutating calls | The explicit execution mode for the capability. | None |

| max_credits | JSON body, nonnegative number | When the fetched contract says a live credit ceiling is needed | A run-wide credit ceiling beside params, not a capability parameter. | None |

| quote_hash | JSON body, string | For a quoted priced live call | The quote minted by a prior dry run. The server binds it to the rerun. | None |

| tool_turn_token | JSON body, string | When supplied by tool discovery | A short-lived turn-binding value. It is not a credential and must be passed through unchanged. | None |

Do not generate a second key simply because the first response did not arrive. Reusing the identity is what lets the execution path associate a retry with the same operation. A new key asks the system to treat the request as a separate operation.

A stable request identity matters most when the request asks the service to create a durable run or reach an external provider. The route stores the identity in the canonical execution request, so it is available before the gateway dispatches the fetched capability.

## Root actions have an extra security rule

Root capabilities have a separate security boundary from ordinary spending and sending. They can change who owns or can reach the workspace or its money. The route requires a current signed-in owner session, a fresh owner-action authorization identity, and an idempotency key before it can execute a root capability.

API keys do not satisfy the signed-in-session requirement for root authority, even if they have broad scopes. This is why a key can be valid for ordinary catalog work but receive destructive_approval_required for a root capability. See Owner actions for the purpose groups and session rule.

Hard-to-reverse workspace changes
Use a stable key for every root-action retry. The route derives the canonical start operation from that key so a retry cannot create a second provider effect.
A fresh owner-action authorization id is only valid for a root capability. The route rejects an authorization id on a non-root capability, and it rejects a root capability that omits it. Keep the authorization and request identity in the same intended attempt, then retry with the same key if the connection fails.

## Delegated execution uses the server key

Delegate execution is the deliberate exception. A delegate step token binds an external credential caller to a particular approved step. The server mints the idempotency key for that step, so the caller must not add an Idempotency-Key header or body field.

If a delegated request supplies a caller key, the route returns invalid_request and identifies idempotency_key as the issue path. Remove both caller placements, retain the delegate step token, and resend the request. A delegate token bound to another capability is refused rather than being reused for a different capability.

The same route refuses a request that includes both a root approval_id and a delegate_step_token. These are different execution paths. Choose the path that the capability contract and authenticated caller actually use.

## Retry the same fetched run request

Architect can keep the retry identity on the intended live mutation while it uses the fetched capability schema. For a direct API caller, add the header to the run endpoint after discovery. The placeholder capability id below is intentional: replace it only with an id returned by the current tool search or tool get response.
ArchitectRESTRetry this live capability run with the same idempotency key. First show me the fetched input schema, confirm whether it is a root action or delegated step, and report the returned error code or receipt.
The run body contains the capability parameters under params, while execution controls such as mode, max_credits, quote_hash, the retry key, and the turn token sit beside params. Use a quoted live request only with the quote and ceiling returned for the unchanged call.
Representative durable receipt shape
{
"ok": true,
"data": {
"receipt": {
"capability_id": "<fetched-capability-id>",
"run_id": "00000000-0000-0000-0000-000000000000",
"run_step_id": "00000000-0000-0000-0000-000000000000",
"operation_request_key": "...",
"idempotency_key": "workbook-update-00000000-v1",
"replay_strategy": "durable_receipt"
}
},
"meta": { "trace_id": "00000000-0000-0000-0000-000000000000" }
}Receipt fields vary with the fetched capability output schema, but durable mutation receipts use the capability id, run id, run step id, operation request key, idempotency key, and durable_receipt replay strategy. Keep the JSON identifiers when you need to inspect the resulting run.

## When it goes wrong

Handle the machine-readable error code first, then use the repair detail and issue paths to rebuild the request. The gateway uses idempotency_conflict when values disagree and does not select one value silently. That protects a caller from retrying an operation whose intended identity is ambiguous.

| Code | HTTP status | What happened | Repair |

| idempotency_conflict | 400 | The header and body differ, or the top-level and params values differ. | Use one key, or repeat the same value in both locations. The server does not choose a winner. |

| invalid_request | 400 | A supplied key is shorter than 1 character or longer than 255 characters. | Send a key within the accepted length range. |

| idempotency_key_required | 400 | A root capability is called without a key. | Retry the exact root request with Idempotency-Key. |

| destructive_approval_required | 400 or 403 | A root action lacks the required current owner session or its owner-action authorization. | Use the signed-in session path described in Owner actions, then keep the request key stable. |

| invalid_request | 400 | Delegate execution receives a caller key. | Send its delegate step token without a header or body idempotency key. |

For a key-length refusal, do not trim or alter a key after the original request may have reached the service. Resolve whether the original request completed through its run or receipt where available. If you must send a new operation, treat it as a new request with a new deliberate key.

For a root-action refusal, return to the signed-in workspace session instead of trying to solve it by adding a broader API key. For a delegated-step refusal, remove the caller key instead of adding an authorization id. The route names these different repair paths so a retry does not cross the wrong security boundary.

A retry identity is not a replacement for the tool-turn token. The token proves the current turn received the capability contract, while the idempotency key identifies a repeat of one execution attempt. Preserve each field for its own purpose and do not use an earlier tool token as a retry key.

Idempotency does not make an arbitrary changed request equivalent to an earlier one. If a caller changes the capability, parameters, recipient, mode, or credit ceiling, it has created a different execution decision. Inspect the original receipt or run before choosing whether the changed request should be a new operation.

The route validates identity placement before it dispatches the capability. This gives a client a structured refusal before a provider-facing effect is attempted when keys conflict, when a root request omits its key, or when a delegate request supplies a caller-owned key.

For ordinary capability schemas, do not add params.idempotency_key merely because a root operation needs a header. The fetched schema determines whether that nested field belongs to the capability. The execution envelope remains the place for the header or top-level execution identity.

A root action is not simply an expensive tool. It changes authority, money, credentials, integrations, ownership, membership, keys, or another owner-controlled workspace boundary. That is why its retry identity works together with the signed-in session and fresh owner-action authorization rather than an API key.

The applicable root approval tier may be fresh owner, workspace admin, or current member for mailbox authorization. The caller should read the returned root contract and use the tier it names. The retry key does not elevate a member or an API client to a tier that the root action does not permit.

A successful retry can return a durable receipt rather than repeating an external effect. Read the receipt's run id and operation request key before issuing another request. Those identifiers are more reliable evidence of the attempted operation than a lost client connection or an ambiguous terminal transcript.

A connection timeout is not proof that the service did not receive the request. Preserve the key, inspect the run or receipt where the fetched contract exposes one, and only then repeat the same request identity. This is particularly important when the capability's action policy reaches an external provider.

The key length rule is one through 255 characters. Pick a stable, readable value that a client can store with the intended operation, but do not put a provider secret or a person’s private data in it. A retry key is an identifier, not an authorization credential and not a location for capability parameters.

A caller can send the same key in the HTTP header and top-level body when a client architecture requires both. The values must be equal. This rule makes intermediaries and direct callers converge on one execution identity without allowing the gateway to silently choose a value that the client did not intend.

When a capability returns a 409-style reconciliation situation after an external provider change, inspect the provider state and the local receipt before retrying. Idempotency helps prevent repeated execution, but it does not replace the application-specific reconciliation described by that capability's output and error contract.

Keep the request body and header alongside the returned trace id in client logs. The trace id is useful for support investigation, while the idempotency key is useful for repeat execution. Neither field should be treated as a substitute for the durable run, workspace object, or provider result identifiers.

Architect chooses an execution identity only after it has fetched the current schema and determined whether the operation mutates or requires idempotency. A user can ask Architect to report the receipt and error code, but the agent should not claim a retry succeeded until it receives the canonical response envelope.

For quote-bound live work, retain the idempotency key while repeating the same priced request with its allowed credit ceiling. The quote rule and retry rule work together: the unchanged capability parameters establish the price decision, while the stable identity establishes that a retry is the same intended execution.

If a client no longer knows whether it is repeating an earlier operation, stop and inspect the run history. Sending a new key is appropriate only when the workspace deliberately wants another operation. Sending a new key because of uncertainty defeats the protection that idempotency supplies.

The route's error envelope includes a machine-readable code, a message, and repair information. Let client code branch on the code, then present the human-readable repair. Do not parse a status message and invent a fallback key, because the route has different repairs for conflict, root security, and delegate execution.

## Webhooks

Source: https://www.trydreamstate.com/docs/reference/webhooks

Webhooks deliver signed workspace event callbacks.

Webhooks deliver signed workspace event callbacks.

## OpenAPI explorer

Source: https://www.trydreamstate.com/docs/reference/openapi

OpenAPI shows generated request and response schemas for Dreamstate operations.

OpenAPI shows generated request and response schemas for Dreamstate operations.