# SwiftCNS Docs (/docs)



Before you start [#before-you-start]

SwiftCNS is decision infrastructure for teams building with AI. You describe an idea in your AI tool (Claude, ChatGPT, Cursor, Claude Code, Codex or any MCP client). SwiftCNS finds the assumptions it rests on, designs the experiment and holds you to success criteria you approved before it ran. You call the result and make the decision; SwiftCNS keeps it as a **Decision Record**, so your next decision starts from your last one.

You need a SwiftCNS account and an AI tool that supports MCP. MCP is included on every plan.

Steps [#steps]

<Steps>
  <Step title="Install">
    Create your workspace and connect your AI tool. [Install SwiftCNS](/docs/get-started/install).
  </Step>

  <Step title="Test">
    Describe your idea. SwiftCNS proposes assumptions and experiments; you choose, approve the success criteria, run the experiment and log the evidence. [Your first test](/docs/get-started/first-test).
  </Step>

  <Step title="Decide">
    You call the result (**Met**, **Not met** or **Unclear**), write what you learned, and choose: **Move forward**, **Change course**, **Test again** or **Drop it**. SwiftCNS keeps the record.
  </Step>
</Steps>

Who does what [#who-does-what]

| SwiftCNS                                                 | You                                        |
| -------------------------------------------------------- | ------------------------------------------ |
| Proposes assumptions, scored for importance and evidence | Choose what to test                        |
| Designs experiments with success criteria                | Choose one, assign it, approve it          |
| Suggests how to track the evidence                       | Run it and log the results                 |
| Drafts observations and insights from the evidence       | Call the result and write what you learned |
| Keeps the record, linked end to end                      | Make the decision, and say why             |

Work in two windows: ask in your AI tool, and keep SwiftCNS open beside it to watch each step land. [Best practices](/docs/agents/mcp-best-practices).

What you get [#what-you-get]

A Decision Record your team and your AI tools can read later. Here is the one from the example used throughout these docs:

Decision Record (sample data):
- Question: Should we build the $79/month Team plan?
- Assumption: Trial teams that try to invite a teammate will pay $79 a month for a shared workspace.
- Experiment: Paid Team offer at invite: when a trial team clicks invite, offer the first month of a shared workspace for $79 through a payment link, and set up sharing by hand for teams that pay.
- Success criteria: At least 3 of the first 15 trial teams that see the offer pay $79 within 7 days of seeing it.
- Evidence: 4 of 15 teams paid within 7 days; a fifth paid on day 10. Every team that paid had invited 3 or more teammates.
- Result: Met
- Learning: Trial teams will pay to share. Teams of three or more are the ones paying; two-person teams said $79 is too much for two people.
- Decision: Move forward. Build a minimal billing path for the $79 Team plan and keep setting up sharing by hand until it's automated. Track whether paying teams renew after the first month, and test a lower price for two-person teams separately.

Done when [#done-when]

* [ ] You know where to start: [Install](/docs/get-started/install), then [your first test](/docs/get-started/first-test).
* [ ] You know where to look things up: [the method](/docs/method), [using the app](/docs/use-the-app/projects-and-home), and [working with your AI tool](/docs/agents/mcp-best-practices).

<ForAgents>
  - Every page has a Markdown version at `/llms.mdx/docs/<slug>/content.md`; the full site is at `/llms.txt` and `/llms-full.txt`.
  - Start with `list_workspaces`, then `list_projects`. Workflow authority is in tool results (`get_conversation_progress`), not in prose.
  - SwiftCNS proposes; the user chooses. Never set a Learning result or record a Decision unless the user tells you to.
</ForAgents>

Next [#next]

[Install SwiftCNS](/docs/get-started/install).


# Best practices with MCP and the app (/docs/agents/mcp-best-practices)



Before you start [#before-you-start]

* SwiftCNS [installed](/docs/get-started/install) and connected to your AI tool.

Steps [#steps]

<Steps>
  <Step title="Work in two windows">
    Ask in your AI tool, because it already knows what you're working on. Keep SwiftCNS open beside it: every record your tool creates appears there live, the **Now** tab shows the next step, and you decide with the whole lineage in view.
  </Step>

  <Step title="Describe the idea, not the method">
    Say what you want to do and why, with the facts you have. Name SwiftCNS so your tool uses it.

    <AgentPrompt>
      Use SwiftCNS to test this: \[the idea]. Context: \[numbers, quotes, constraints].
    </AgentPrompt>

    Don't ask your tool to list assumptions or design an experiment itself. SwiftCNS does that, scores the options and keeps them on the record.
  </Step>

  <Step title="Make each choice explicitly">
    Tell your tool what you chose; it submits the choice for you.

    <AgentPrompt>
      Select the assumption about \[topic] and the hypothesis tested at \[moment]. Show me the experiment options; I'll choose.
    </AgentPrompt>

    <AgentPrompt>
      Choose the \[design] experiment, assign it to me, due \[date], and approve it.
    </AgentPrompt>
  </Step>

  <Step title="Bring evidence from where it lives">
    Paste rows, point to a CSV, or ask your tool to pull results from a source it can read.

    <AgentPrompt>
      Add these results to the SwiftCNS tracker, one row per \[unit]: \[rows]. Then show me the totals against the success criteria.
    </AgentPrompt>

    When the sample is in: "Complete the tracker."
  </Step>

  <Step title="Keep the two calls that matter">
    The result and the decision are yours. Make them in the app, or dictate them:

    <AgentPrompt>
      Set the Learning result to \[Met / Not met / Unclear], write: "\[what I learned]", and publish it. Then prepare a decision review for \[question], citing the Learning, without a recommendation.
    </AgentPrompt>

    <AgentPrompt>
      Record my decision: \[Move forward / Change course / Test again / Drop it]. Why and next: "\[reasons and next step]".
    </AgentPrompt>
  </Step>

  <Step title="Pick up later">
    Days later, ask: "Where does my SwiftCNS test on \[topic] stand?" Your tool reads the current step and carries on from there.
  </Step>
</Steps>

<InSwiftCNS>
  Your tool only continues to the next SwiftCNS step when you ask. Replies take about 20 to 60 seconds; your tool checks back until they're ready. One step can't be done over MCP: creating a workspace.
</InSwiftCNS>

What you get [#what-you-get]

Your AI tool does the typing; SwiftCNS does the drafting and keeps the record; you make the calls. In the running example, the whole cycle took about 20 minutes of tool time, and every step appeared in the app as it happened.

Done when [#done-when]

* [ ] You ran a step from your AI tool and saw it land in SwiftCNS.
* [ ] Your tool's instructions include [the SwiftCNS rule](/docs/agents/teach-your-agent).

Common mistakes [#common-mistakes]

* **"Just run the whole thing."** Your tool will stop at each choice, or make choices you meant to make. Say which steps it may take for you.
* **Asking for a recommendation before you decide.** Make your own call first; it keeps your judgment and your record honest.
* **Losing the thread.** Keep one question per conversation; start a new one for the next idea.

<ForAgents>
  - Read `get_conversation_progress` before acting: `activeActionRequests`, `actionOperations`, `permittedTransitionIds`, `continuationMode`.
  - `send_message` (with a stable `requestKey`) returns an `assistantMessageId`; poll `get_message` until `execution.status` is `SUCCEEDED`, then reload progress.
  - Pass `continueConversation: true` with a branch-leaf `parentMessageId` only when the user asked to continue.
  - Submit only what the user chose or explicitly delegated. Never set a Learning result or record a Decision on your own judgment.
</ForAgents>

Next [#next]

[Permissions](/docs/agents/permissions): what your tool may do, and how to revoke it.


# Permissions (/docs/agents/permissions)



Before you start [#before-you-start]

* A [connected AI tool](/docs/get-started/install). The permissions it asked for are listed under **Settings → MCP client access**.

Steps [#steps]

<Steps>
  <Step title="Know what SwiftCNS drafts">
    SwiftCNS drafts the assumptions, hypotheses, experiment designs and their success criteria, the tracker's row unit, and the Learning's observations and insights. Your tool needs **Read CNS** and **Update CNS** to ask for these.
  </Step>

  <Step title="Know what commits you">
    Every step that commits you is a choice on a card: selecting assumptions, a hypothesis and an experiment; assigning and approving it; setting up and completing the tracker; publishing the Learning; recording the decision. Submitting these needs **Make decisions**.
  </Step>

  <Step title="Choose how much to delegate">
    With **Make decisions**, your tool can submit those choices when you tell it to. Without it, your tool asks and you act in the app. Either way, SwiftCNS records who did what. The result and the decision should always be your own call.
  </Step>

  <Step title="Disconnect a tool">
    In **Settings → MCP client access**, find it under **Authorized applications** and remove it. Access tokens may stay usable for up to 5 minutes.
  </Step>
</Steps>

<InSwiftCNS>
  Choices arrive as **action cards** (Action Requests): one card per choice, with the options and what it will save, such as **Select assumptions** or **Approve experiment**.
</InSwiftCNS>

What you get [#what-you-get]

| Permission                 | Lets your AI tool                                                                                                          |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Read CNS**               | Read projects, conversations, experiments and Learnings you may access.                                                    |
| **Update CNS**             | Provide documents and record observations. Sending a message also requires Read CNS.                                       |
| **Make decisions**         | Submit authorized selections, workflow decisions and Learning publication.                                                 |
| **Read connected sources** | Retrieve information through permitted connected sources. Continuing a conversation also requires Read CNS and Update CNS. |

Your tool never sees more than you can. Access is checked per workspace, project and conversation. See [Security and data](/docs/reference/security-and-data).

Done when [#done-when]

* [ ] You know which steps you'll take yourself and which you'll delegate.
* [ ] Your tool's permissions match that choice.

Common mistakes [#common-mistakes]

* **Delegating the success criteria.** Approve those yourself. They're what your result will be judged against.
* **Assuming a recorded decision is carried out.** Recording doesn't execute anything. Your team still does the work.

<ForAgents>
  - Scopes: `cns:read`, `cns:write`, `cns:decide`, `cns:sources:read`. Each step lists its scope in `actionOperations[].requiredScopes`.
  - Submit with the active `actionRequestId` and `contractVersion`. On an uncertain response, replay with identical input; changed input conflicts.
  - If `browserRequired` is true, send the user to `browserUrl`.
</ForAgents>

Next [#next]

[Teach your AI tool when to use SwiftCNS](/docs/agents/teach-your-agent).


# Pick up where you left off (/docs/agents/pick-up-later)



Before you start [#before-you-start]

* A project with at least one conversation. Everything lives in SwiftCNS, not in your agent's chat history, so any AI tool you connect can continue.

Steps [#steps]

<Steps>
  <Step title="Continue an experiment">
    <AgentPrompt>
      In SwiftCNS, where are we on \[project]? What's waiting for me?
    </AgentPrompt>

    Your AI tool reads the project and tells you the current step and anything waiting for you.
  </Step>

  <Step title="Start the next idea from the last decision">
    <AgentPrompt>
      Before we test \[new idea], check SwiftCNS for past decisions and Learnings on this. Start a new conversation that builds on them.
    </AgentPrompt>

    Earlier Learnings become context for the new conversation. They aren't proof that the new idea will work.
  </Step>

  <Step title="Replace a decision when the facts change">
    <AgentPrompt>
      We have new evidence on \[question]. Prepare a SwiftCNS decision review that replaces the last one, without a recommendation. I'll choose.
    </AgentPrompt>

    Both decisions stay on record, linked, so anyone can see what changed and why.
  </Step>
</Steps>

What you get [#what-you-get]

A history your team and your AI tools can follow. In the running example, the next conversation (a lower price for two-person teams) starts from the **Move forward** decision and the Learning behind it.

Done when [#done-when]

* [ ] Your AI tool can tell you the current step of any project without you re-explaining it.
* [ ] Each new decision links back to the one it replaces.

Common mistakes [#common-mistakes]

* **Starting from zero.** Ask for past decisions first; it's one line.
* **Editing history.** Don't rewrite an old decision. Replace it with a new one.

<ForAgents>
  - Find work: `list_projects`, `list_conversations`, `list_decisions`, `list_learnings`, `search_project_sources`.
  - Resume an experiment: `open_experiment_conversation`. Current position: `get_conversation_progress`.
  - New conversation: `generate_resource_id` (`CONVERSATION`), `create_conversation` (optional `parentConversationId`, which links but doesn't copy), then `attach_sources_to_conversation` for the artifacts the user chose.
  - Supersede: `prepare_decision_review` with `supersedesDecisionId`.
  - Prompts: `continue_experiment`, `import_experiment_evidence`.
</ForAgents>

Next [#next]

[The Decision Record](/docs/concepts/decision-record).


# Teach your AI tool when to use SwiftCNS (/docs/agents/teach-your-agent)



Before you start [#before-you-start]

* A [connected AI tool](/docs/get-started/install).
* Access to your AI tool's instruction file: `CLAUDE.md`, a Cursor rule, or `AGENTS.md`.

Steps [#steps]

<Steps>
  <Step title="Copy the rule for your tool">
    <Tabs items="['CLAUDE.md', 'Cursor rule', 'AGENTS.md']">
      <Tab value="CLAUDE.md">
        Add to `CLAUDE.md` in your project, or `~/.claude/CLAUDE.md` for every project:

        ```markdown
        ## Decisions

        Before we commit to a consequential decision (a pricing change, a launch, a roadmap item, a hire, a large send or a budget move), use SwiftCNS first:
        - Check SwiftCNS for past decisions on the same idea, and say what was already tested.
        - Ask SwiftCNS to test it, and show me the assumptions and experiments it proposes. I choose and approve.
        - Don't call the result or decide for me, and don't recommend a choice. Bring back the evidence; I'll call it and decide.
        ```
      </Tab>

      <Tab value="Cursor rule">
        Save as `.cursor/rules/swiftcns.mdc`:

        ```markdown
        ---
        description: Test consequential decisions with SwiftCNS before committing
        alwaysApply: true
        ---

        Before we commit to a consequential decision (a pricing change, a launch, a roadmap item, a hire, a large send or a budget move), use SwiftCNS first:
        - Check SwiftCNS for past decisions on the same idea, and say what was already tested.
        - Ask SwiftCNS to test it, and show me the assumptions and experiments it proposes. I choose and approve.
        - Don't call the result or decide for me, and don't recommend a choice. Bring back the evidence; I'll call it and decide.
        ```
      </Tab>

      <Tab value="AGENTS.md">
        For Codex and other agents that read `AGENTS.md`:

        ```markdown
        ## Decisions

        Before we commit to a consequential decision (a pricing change, a launch, a roadmap item, a hire, a large send or a budget move), use SwiftCNS first:
        - Check SwiftCNS for past decisions on the same idea, and say what was already tested.
        - Ask SwiftCNS to test it, and show me the assumptions and experiments it proposes. I choose and approve.
        - Don't call the result or decide for me, and don't recommend a choice. Bring back the evidence; I'll call it and decide.
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Adjust the list to your work">
    Swap in the decisions that matter for your team: a feature, a partnership, a hiring plan. Keep the last line. It's what keeps the decision yours.
  </Step>

  <Step title="Test it">
    <AgentPrompt>
      I'm thinking of raising our price by 20% next month.
    </AgentPrompt>

    Your AI tool should check SwiftCNS for past decisions and offer to test the idea when it's still open.
  </Step>
</Steps>

What you get [#what-you-get]

An AI tool that brings evidence to big calls by default, and leaves the calls to you.

Done when [#done-when]

* [ ] A consequential request triggers a SwiftCNS check without you naming it.

Common mistakes [#common-mistakes]

* **A list so broad it fires on everything.** Keep it to decisions that are costly to reverse.
* **Dropping the last line.** Without it, a tool with **Make decisions** may approve steps, call results or record decisions you meant to own.

<ForAgents>
  When this rule triggers: `list_decisions` and `search_project_sources` first, then `send_message` to start a test. Never set a Learning result, pass a `recommendation`, or call `submit_decision` without the user's explicit instruction.
</ForAgents>

Next [#next]

[Pick up where you left off](/docs/agents/pick-up-later).


# The Decision Record (/docs/concepts/decision-record)



Before you start [#before-you-start]

A Decision Record is what SwiftCNS produces. It's the answer to "why did we do that?", written at the time by the people who decided, linked to the evidence they had.

Steps [#steps]

<Steps>
  <Step title="The question">
    The choice being made, as a question: "Should we build the $79/month Team plan?"
  </Step>

  <Step title="The basis">
    The assumption that was tested, the experiment, the success criteria (fixed when the experiment was approved), the evidence snapshot and the Learning with its result. Each is linked, not copied, so you can open the original.
  </Step>

  <Step title="The decision">
    The choice (**Move forward**, **Change course**, **Test again** or **Drop it**), why and what happens next in the recorder's own words, who recorded it and when.
  </Step>

  <Step title="The history">
    If a later decision replaces it, both stay on record and link to each other.
  </Step>
</Steps>

<InSwiftCNS>
  The record is a **Decision** with references to a **Learning**, **Insights**, an **Experiment**, a **Hypothesis**, **Assumptions** and **Documents**. It's listed under the project's **Decisions**.
</InSwiftCNS>

What you get [#what-you-get]

Decision Record (sample data):
- Question: Should we build the $79/month Team plan?
- Assumption: Trial teams that try to invite a teammate will pay $79 a month for a shared workspace.
- Experiment: Paid Team offer at invite: when a trial team clicks invite, offer the first month of a shared workspace for $79 through a payment link, and set up sharing by hand for teams that pay.
- Success criteria: At least 3 of the first 15 trial teams that see the offer pay $79 within 7 days of seeing it.
- Evidence: 4 of 15 teams paid within 7 days; a fifth paid on day 10. Every team that paid had invited 3 or more teammates.
- Result: Met
- Learning: Trial teams will pay to share. Teams of three or more are the ones paying; two-person teams said $79 is too much for two people.
- Decision: Move forward. Build a minimal billing path for the $79 Team plan and keep setting up sharing by hand until it's automated. Track whether paying teams renew after the first month, and test a lower price for two-person teams separately.

Who reads it:

* **Your team**, months later, before re-testing the same idea.
* **Your agents**, before proposing the next experiment.
* **People outside the team** (investors, partners, a new hire) who need the reasoning, not the meeting.

Done when [#done-when]

* [ ] Someone who wasn't there can tell what was decided, on what evidence, and why.

Common mistakes [#common-mistakes]

* **Recording only the decision.** "We're not building it" without the evidence is a memo, not a record.
* **Recording a decision with no evidence cited.** Allowed, but then it's an opinion on the record, not a tested call.

<ForAgents>
  - Read: `get_decision`, `list_decisions`; resource `swiftcns://projects/{projectId}/decisions/{decisionId}`.
  - Write: `prepare_decision_review` then `submit_decision` (`operation: "record"` or `"cancel"`). Recording doesn't execute the chosen action.
</ForAgents>

Next [#next]

[Evidence and the snapshot](/docs/concepts/evidence-snapshot).


# Evidence and the snapshot (/docs/concepts/evidence-snapshot)



Before you start [#before-you-start]

Two things get fixed, at two moments: the **success criteria** when you approve the experiment, and the **evidence** when you complete the tracker. Fixing them is what makes the result trustworthy later.

Steps [#steps]

<Steps>
  <Step title="Criteria are fixed on approval">
    Once the experiment is approved, the success criteria can't move. The result can only be read against the criteria you set before you saw any data.
  </Step>

  <Step title="Evidence is saved as a snapshot">
    **Complete tracker** saves the rows as a fixed snapshot and completes the experiment. The Learning, its insights and the decision all point at that snapshot, so anyone can check exactly what you were looking at.
  </Step>

  <Step title="You call the result">
    SwiftCNS drafts observations from the snapshot. Then you say whether the result **Met** the criteria, did **Not met**, or is **Unclear**. If the evidence is thin, say so: Unclear, followed by **Test again**, is an honest record.
  </Step>
</Steps>

<InSwiftCNS>
  The snapshot is stored as a document linked to the experiment and the Learning. A completed tracker opens read-only, from the **Data tracker** tab and **Lineage**.
</InSwiftCNS>

What you get [#what-you-get]

In the running example, 15 rows were saved. The success criteria were 3 of 15 paying within 7 days; 4 did. SwiftCNS also noted that one more or one fewer payment would flip the result, and that a late payer (day 10) fell outside the window. The team called it **Met** and said in the Learning that the margin was small.

A Not met result is a result too. It tells you where not to spend the next quarter.

Done when [#done-when]

* [ ] You can point to the approved criteria and the snapshot behind any decision.

Common mistakes [#common-mistakes]

* **Wanting to edit rows after completing.** Run a follow-up experiment instead; the old snapshot stays.
* **Calling Not met a failure.** The failure is spending the quarter without knowing.

<ForAgents>
  - `complete_experiment` saves the snapshot; its id appears as `snapshotDocumentId` on `get_data_tracker` and `get_learning`.
  - `list_evidence_assessments` returns history from the retired sufficiency step only.
  - An upload or attachment alone never approves or publishes evidence.
</ForAgents>

Next [#next]

[MCP server reference](/docs/reference/mcp-server).


# Your first test (/docs/get-started/first-test)



Before you start [#before-you-start]

* [SwiftCNS installed](/docs/get-started/install) and your AI tool connected.
* An idea you're working on that would cost real time or money if it's wrong.
* SwiftCNS open in the browser beside your AI tool. You'll watch each step land there.
* Any plan. Free is enough to take one idea to a decision ([Plans and usage](/docs/use-the-app/plans-and-usage)).

Steps [#steps]

<Steps>
  <Step title="Describe the idea">
    <AgentPrompt>
      Use SwiftCNS to evaluate the riskiest idea we've been working on. Tell me which idea you picked and why, then show me what it rests on.
    </AgentPrompt>

    Your AI tool picks the idea from what it knows about your work. If it picks the wrong one, describe yours in two or three sentences: what you want to do, for whom, and the numbers you have. The running example started like this:

    > Use SwiftCNS to test this: we want to launch a $79/month Team plan. About 50 new trial teams a month, and a third of them try to invite a teammate. We want to know whether teams will pay for sharing before we spend on billing.

    SwiftCNS replies in about half a minute with the assumptions the idea rests on, each scored for **importance** and **evidence**.

    <Figure src="/images/docs/first-test/01-assumptions.webp" alt="Select assumptions card listing four assumptions with evidence and importance scores" caption="Sample data" />
  </Step>

  <Step title="Choose what to test">
    Pick the riskiest assumption: high importance, low evidence. SwiftCNS turns it into a hypothesis with provisional success criteria, then proposes experiment designs scored for setup, run time, cost and data reliability. Choose one. Tell your AI tool which, or click it in the app.

    <Figure src="/images/docs/first-test/03-experiments.webp" alt="Select an experiment card: Paid Team offer at invite, with scores and success criteria" caption="Sample data" />
  </Step>

  <Step title="Assign and approve">
    Give the experiment an owner and, if you like, a due date. Then approve it. Approving commits you to the design and its success criteria; they can't change after this.

    <Figure src="/images/docs/first-test/05-approve.webp" alt="Approve experiment card, with the Now panel showing owner, due date and success criteria" caption="Sample data" />
  </Step>

  <Step title="Run it and log the evidence">
    Set up the tracker (one row per thing you count), run the experiment in the real world, and log rows as results come in: type them, paste them, import a CSV, or ask your AI tool to add them. When you're done, choose **Complete tracker**. It saves the rows as a fixed snapshot and completes the experiment.

    <Figure src="/images/docs/first-test/07c-tracker-grid.webp" alt="Log evidence sheet with 15 rows and Add row, Paste rows and Import CSV file buttons" caption="Sample data" />
  </Step>

  <Step title="Call the result and write what you learned">
    SwiftCNS drafts observations and insights from the snapshot. You decide whether the result **Met**, did **Not met** or is **Unclear** against the success criteria, and write what you learned in your own words. Then **Publish Learning**.

    <Figure src="/images/docs/first-test/08-learning-draft.webp" alt="Learning editor with the Result choice (Met, Not met, Unclear) and the What did you learn field" caption="Sample data" />
  </Step>

  <Step title="Record the Decision">
    Nothing prompts this step, so ask for it:

    <AgentPrompt>
      Prepare a SwiftCNS decision review for this experiment. Cite the Learning. Don't recommend a choice; I'll decide.
    </AgentPrompt>

    Choose **Move forward**, **Change course**, **Test again** or **Drop it**, write why and what happens next, then **Record decision**.

    <Figure src="/images/docs/first-test/09-decision-form.webp" alt="Record your decision form with four choices and a required rationale field" caption="Sample data" />
  </Step>
</Steps>

What you get [#what-you-get]

A Decision Record: the question, the assumption, the experiment and its criteria, the evidence, your Learning and your decision, linked together.

Decision Record (sample data):
- Question: Should we build the $79/month Team plan?
- Assumption: Trial teams that try to invite a teammate will pay $79 a month for a shared workspace.
- Experiment: Paid Team offer at invite: when a trial team clicks invite, offer the first month of a shared workspace for $79 through a payment link, and set up sharing by hand for teams that pay.
- Success criteria: At least 3 of the first 15 trial teams that see the offer pay $79 within 7 days of seeing it.
- Evidence: 4 of 15 teams paid within 7 days; a fifth paid on day 10. Every team that paid had invited 3 or more teammates.
- Result: Met
- Learning: Trial teams will pay to share. Teams of three or more are the ones paying; two-person teams said $79 is too much for two people.
- Decision: Move forward. Build a minimal billing path for the $79 Team plan and keep setting up sharing by hand until it's automated. Track whether paying teams renew after the first month, and test a lower price for two-person teams separately.

SwiftCNS's part took about 20 minutes; the experiment itself takes as long as it takes.

Done when [#done-when]

* [ ] The experiment shows under **Decided** on the project's **Experiments** board.
* [ ] Your Learning is under **Learnings**, and your decision under **Decisions**.

Common mistakes [#common-mistakes]

* **Stopping at the Learning.** A published Learning doesn't record a decision. Ask for the decision review.
* **Letting your AI tool call the result.** The result and the decision are yours. Your tool should only do them if you explicitly tell it to.

<ForAgents>
  - Setup: `generate_resource_id` (`PROJECT`), `create_project`, `generate_resource_id` (`CONVERSATION`), `create_conversation` (a `title` is required, such as the question). Every write takes a stable `requestKey`; reuse it only to retry identical input.
  - After each `send_message` or continuation, poll `get_message` until `execution.status` is `SUCCEEDED` (the message `status` may read `requires-action` when a card is waiting), then reload `get_conversation_progress`.
  - Flow: `send_message` → `select_assumptions` → `select_hypothesis` → `select_experiment` → `assign_experiment` → `approve_experiment` → `configure_data_tracker` → `add_data_tracker_rows` → `complete_experiment` (with `continueConversation: true`) → `update_learning_draft` → `publish_learning` → `prepare_decision_review` → `submit_decision`.
  - Each step's step-by-step detail is in [the method](/docs/method).
</ForAgents>

Next [#next]

[The method](/docs/method): why each step works, and how to do it well.


# Install SwiftCNS (/docs/get-started/install)



Before you start [#before-you-start]

* An AI tool that supports MCP: Claude, ChatGPT, Cursor, Claude Code, Codex or another MCP client. MCP is included on every plan, Free too.
* Free covers one person and one project. To bring teammates in, you need Team. See [Plans and usage](/docs/use-the-app/plans-and-usage).
* Nothing to install on a server. SwiftCNS runs in the browser; your AI tool talks to it over MCP.

Steps [#steps]

<Steps>
  <Step title="Sign up and set up your workspace">
    Open [SwiftCNS](https://app.swiftcns.ai/setup) and sign in. On **Set up your workspace**, enter a workspace name, your role and your team size, then choose **Create workspace**.

    This is the one step your AI tool can't do for you: no MCP tool creates a workspace.

    <Figure src="/images/docs/install/01-set-up-workspace.webp" alt="Set up your workspace form with workspace name, role and team size" />
  </Step>

  <Step title="Pick the AI tool you already use">
    On **Connect the AI tool you already use**, choose your tool. SwiftCNS shows setup steps for that tool only. You can also choose **I'll connect later** and come back from **Settings → MCP client access**.

    <Figure src="/images/docs/install/02-connect-your-ai.webp" alt="Connect the AI tool you already use: a list of tools beside a preview of how a test runs" />
  </Step>

  <Step title="Add SwiftCNS to your tool">
    Not sure which? If you use Claude or ChatGPT in the browser, pick that.

    <Tabs items="['Claude', 'ChatGPT', 'Cursor', 'Claude Code', 'Codex', 'Other']">
      <Tab value="Claude">
        In Claude, add a custom connector and paste the server URL: https://api.swiftcns.ai/mcp.
      </Tab>

      <Tab value="ChatGPT">
        In ChatGPT, turn on developer mode and create an MCP app with the server URL: https://api.swiftcns.ai/mcp. Availability depends on your ChatGPT plan and workspace settings.
      </Tab>

      <Tab value="Cursor">
        Choose **Add to Cursor** on the setup page. It opens Cursor with the server and its sign-in settings filled in. Then, in Cursor's MCP settings, enable **swiftcns** and sign in.

        Prefer to paste? The setup page has **Copy config** for `~/.cursor/mcp.json`. Use that copy rather than writing your own: it carries the sign-in settings Cursor needs.
      </Tab>

      <Tab value="Claude Code">
        ```bash
        claude mcp add --transport http --scope user swiftcns 'https://api.swiftcns.ai/mcp'
        claude mcp login swiftcns
        ```
      </Tab>

      <Tab value="Codex">
        ```bash
        codex mcp add swiftcns --url 'https://api.swiftcns.ai/mcp'
        ```

        Adding the server usually starts sign-in. If it doesn't, run `codex mcp login swiftcns`. Then start `codex` and enter `/mcp` to check.
      </Tab>

      <Tab value="Other">
        Add a remote MCP server with the URL https://api.swiftcns.ai/mcp. Choose HTTP if your client asks for a transport.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Sign in and approve permissions">
    Your tool opens a SwiftCNS sign-in page. Use the same account as your workspace and review the permissions. Approve **Make decisions** too, or your AI tool can read but can't select, assign or record anything for you.
  </Step>

  <Step title="Check the connection">
    Go back to the setup page and choose **Check connection**. It updates when your tool first contacts SwiftCNS. Then copy the starter prompt into your tool:

    <AgentPrompt>
      Use SwiftCNS to find the most important idea I should be testing right now, based on what I'm working on. What am I assuming, and what should I test first?
    </AgentPrompt>

    <Figure src="/images/docs/install/04-connection-confirmed.webp" alt="Connection confirmed page with the starter prompt and Open workspace" />
  </Step>
</Steps>

<Figure src="/images/docs/app/settings-mcp-client-access.webp" alt="Settings, MCP client access: the server URL with Copy URL, setup instructions, and the permissions an agent can request" caption="Settings → MCP client access. The URL shown is the one for your environment." />

What you get [#what-you-get]

* A workspace, with you as its owner.
* Your AI tool connected, limited to the permissions you approved. It can only reach work you can reach. See [Security and data](/docs/reference/security-and-data).

Keep SwiftCNS open beside your AI tool. Records your tool creates appear in the app as they happen. See [how to work with both](/docs/agents/mcp-best-practices).

Done when [#done-when]

* [ ] The setup page says your tool is connected.
* [ ] Asking your tool "list my SwiftCNS workspaces" names your workspace.

Troubleshooting [#troubleshooting]

* **"Invalid credentials" or 401.** Sign in again from your tool (`claude mcp login swiftcns`, `codex mcp login swiftcns`, or reconnect the connector). A removed authorization needs a fresh sign-in.
* **Your tool can't select or approve anything.** You didn't grant **Make decisions**. Remove the authorization under **Settings → MCP client access** and connect again.
* **No workspaces listed.** You signed in to your tool with a different account than the one that owns the workspace.
* **The server URL differs from this page.** Use the one on **Settings → MCP client access**; it is always right for your account.

<ForAgents>
  - Transport: streamable HTTP; auth: OAuth 2 with scopes `cns:read`, `cns:write`, `cns:decide`, `cns:sources:read`.
  - Start with `list_workspaces`, then `list_projects`. A user with no workspace must create one in the browser first.
</ForAgents>

Next [#next]

[Your first test](/docs/get-started/first-test): one idea, from question to recorded Decision.


# 1. Find the assumption (/docs/method/1-find-the-assumption)



Before you start [#before-you-start]

* An idea, stated as a choice: "should we build X?", "should we charge Y?".
* The facts you already have: usage numbers, churn reasons, tickets, customer quotes. More context gives sharper assumptions.

Steps [#steps]

<Steps>
  <Step title="List what has to be true">
    <Tabs items="['In your AI tool', 'In the app']">
      <Tab value="In your AI tool">
        <AgentPrompt>
          Use SwiftCNS to test this: \[the idea]. Context: \[facts]. What does it rest on?
        </AgentPrompt>
      </Tab>

      <Tab value="In the app">
        Open your project and describe the idea in the box on **Project home**, or choose **New conversation**. The card **Select assumptions** appears in the thread.
      </Tab>
    </Tabs>

    SwiftCNS replies with a handful of assumptions, each scored 1 to 5 for **importance** (does the idea fail without it?) and **evidence** (how much do you already know?). It may ask a clarifying question first.
  </Step>

  <Step title="Pick the riskiest one">
    Choose high importance and low evidence. One is usually enough. If two tie, pick the one the others depend on, or whose failure would cost you most. Be specific: "teams will pay $79 a month to share", not "pricing".
  </Step>

  <Step title="Pick the prediction to test">
    SwiftCNS turns your assumption into one or two hypotheses: a prediction plus provisional success criteria that could prove it wrong. Pick the one you can test soonest and most directly.
  </Step>
</Steps>

<Figure src="/images/docs/first-test/02-hypotheses.webp" alt="Select a hypothesis card with two viability hypotheses, and the chosen assumption in the Now panel" caption="Sample data" />

<InSwiftCNS>
  The testable prediction is a **Hypothesis**, tagged with a theme such as viability. The project's stage reads **Exploring** until you choose an experiment.
</InSwiftCNS>

What you get [#what-you-get]

In the running example, four assumptions came back. The team picked the one scored importance 5, evidence 1:

* *Trial teams that try to invite a teammate will pay $79 a month for a shared workspace.*

The hypothesis they chose: *trial teams that try to invite a teammate will pay $79 for the first month of a shared workspace when it's offered at that moment. We're right if at least 3 of the first 15 such teams pay within 7 days.*

Done when [#done-when]

* [ ] One assumption is written specifically enough that a result could prove it false.
* [ ] You picked it because it's risky, not because it's easy to test.

Common mistakes [#common-mistakes]

* **Testing the fix before the cause.** If you don't know why something happens, testing a solution tells you little.
* **Picking what you already believe.** High evidence means low learning.
* **Vague wording.** "Users want it" can't be missed, so it can't be tested.

<ForAgents>
  - Create the conversation first: `generate_resource_id` (`CONVERSATION`), then `create_conversation`.
  - `send_message`, then poll `get_message`. Read `get_conversation_progress`: the active Action Request is `assumption_selection`; submit with `select_assumptions` (`selectedAssumptionIds`).
  - Clarifying questions arrive as `question_answer` (`answer_clarifying_questions`).
  - Then `hypothesis_selection` via `select_hypothesis`. Pass `continueConversation: true` and a branch-leaf `parentMessageId` to get the next turn.
  - Choose only what the user chose, or what they explicitly delegated.
</ForAgents>

Next [#next]

[Step 2: Set the success criteria](/docs/method/2-set-success-criteria).


# 2. Set the success criteria (/docs/method/2-set-success-criteria)



Before you start [#before-you-start]

* A chosen hypothesis from [step 1](/docs/method/1-find-the-assumption).
* The person who will make the decision. They should agree the criteria now, not after the results.

Steps [#steps]

<Steps>
  <Step title="Compare the experiment designs">
    <Tabs items="['In your AI tool', 'In the app']">
      <Tab value="In your AI tool">
        <AgentPrompt>
          Show me the SwiftCNS experiment options with their scores and success criteria. I'll choose.
        </AgentPrompt>
      </Tab>

      <Tab value="In the app">
        The card **Select an experiment** lists the designs. Open **Approach and measurements** on each to see how it runs and what it measures.
      </Tab>
    </Tabs>

    Each design is scored 1 to 5 for **setup**, **run time**, **cost** and **data reliability** (lower is simpler, faster, cheaper, more reliable) and comes with success criteria and key metrics.
  </Step>

  <Step title="Check the criteria before you choose">
    Would a miss change your mind? If not, raise the criteria or pick another design. Check the sample size and how long it will take. Don't choose on cost alone: a cheap design that measures what people say is weaker than one that measures what they do.

    The experiment's **success criteria** are what you'll call the result against. They can differ from the provisional criteria in the hypothesis; make sure the two agree before you approve. Provisional criteria are a starting point. To change them, choose **Edit experiment** below the thread (or tell your AI tool) and describe the change.
  </Step>

  <Step title="Assign and approve">
    Choose an owner and, if you like, a due date, then approve. **Approving commits you to this design and these success criteria.** They can't be edited afterwards.
  </Step>
</Steps>

<Figure src="/images/docs/first-test/04-assign.webp" alt="Assign experiment card with owner and optional due date, and the experiment's approach and criteria in the Now panel" caption="Sample data" />

<InSwiftCNS>
  Each option is an **Experiment** with a type (for example "pre-order / paid pilot"), four scores, success criteria and key metrics. The stage reads **Designing** until you approve. Approval needs an owner who is a project editor.
</InSwiftCNS>

What you get [#what-you-get]

The running example offered two designs for the same hypothesis:

| Design                     | Trade-off                                                               |
| -------------------------- | ----------------------------------------------------------------------- |
| Paid Team offer at invite  | Shows whether teams actually pay; needs a payment link and manual setup |
| Team plan fake-door button | Cheaper; shows interest at the price, not payment                       |

The team chose the paid offer, because only real payment answers the question. The criterion they approved:

> At least 3 of the first 15 trial teams that see the offer pay $79 within 7 days of seeing it.

Two more metrics explain the result without deciding it: where teams drop off, and why they don't pay.

Done when [#done-when]

* [ ] The criterion is a number to reach, with a sample and a time window.
* [ ] The decision-maker agreed it before the experiment started.
* [ ] The experiment is approved and has an owner.

Common mistakes [#common-mistakes]

* **No number.** "We'll see what people say" can't be missed.
* **Criteria you'd ignore.** If 1 in 15 would still make you build it, 3 in 15 isn't your real criterion.
* **Measuring interest when you need commitment.** Clicks and "I'd pay" are weaker than payment.

<ForAgents>
  - `experiment_card_selection` via `select_experiment` (`selectedExperimentCardId`).
  - Then `assign_experiment` (`assigneeUserPublicId`, optional `dueAt` in RFC 3339 with an offset, in the future). Find eligible people with `list_eligible_experiment_assignees`.
  - Then `approve_experiment` (empty submission). All three need `cns:decide` and return `continuationMode: NONE`.
  - Edits before approval: `send_message` describing the change, then `apply_field_edit_proposal` with a `toolCallId` from `get_message` → `fieldEditProposals`. Edits are refused once the experiment leaves draft.
</ForAgents>

Next [#next]

[Step 3: Run the smallest experiment](/docs/method/3-run-the-experiment).


# 3. Run the smallest experiment (/docs/method/3-run-the-experiment)



Before you start [#before-you-start]

* An approved experiment with fixed success criteria ([step 2](/docs/method/2-set-success-criteria)).
* A way to reach the people or data the experiment needs, and a source for the evidence: a payment system, a form, a spreadsheet, interview notes.

Steps [#steps]

<Steps>
  <Step title="Set up the tracker">
    <Tabs items="['In your AI tool', 'In the app']">
      <Tab value="In your AI tool">
        <AgentPrompt>
          Set up the SwiftCNS data tracker for this experiment: one row per \[thing you count], with columns that let us check the success criteria directly. Show me the columns before you create it.
        </AgentPrompt>
      </Tab>

      <Tab value="In the app">
        The card **Set up data tracker** proposes the columns. Review them, then choose **Create tracker**.
      </Tab>
    </Tabs>

    Decide first what one row is: one team, one customer, one interview. Then make sure the success criterion can be counted straight from the columns.

    <Figure src="/images/docs/first-test/06-setup-tracker.webp" alt="Set up data tracker card: each row is a trial team shown the offer, with ten suggested columns" caption="Sample data" />
  </Step>

  <Step title="Run it and log evidence as it comes in">
    Run the experiment in the real world. Log rows as they happen: **Add row**, **Paste rows**, **Import CSV file**, or ask your AI tool to add them. Keep the people who never answered as rows too.
  </Step>

  <Step title="Complete the tracker">
    When the sample is in or the time is up, choose **Complete tracker**. It saves the rows as a fixed snapshot and completes the experiment. Rows can't be added or edited after this.
  </Step>
</Steps>

<Figure src="/images/docs/first-test/07-complete-tracker.webp" alt="Complete tracker card showing 15 evidence rows logged, with the tracker preview in the Data tracker tab" caption="Sample data" />

<InSwiftCNS>
  The tracker lives in the workbench's **Data tracker** tab; **Open tracker** opens the full grid (**Log evidence**). The stage reads **Collecting evidence** until you complete it, then **Learning**. Over MCP, the app's column suggestions aren't available yet, so describe the row and columns you want.
</InSwiftCNS>

What you get [#what-you-get]

The running example tracked one row per trial team that saw the offer, with columns for teammates invited, whether the team opened the payment link, the amount paid, whether it paid within 7 days, the furthest step reached, and the reason for not paying.

15 rows: 4 teams paid within 7 days, a fifth paid on day 10, 5 opened the link without paying, and 5 only saw the offer.

<Figure src="/images/docs/first-test/07c-tracker-grid.webp" alt="Log evidence grid with 15 trial teams and their payment results" caption="Sample data" />

Done when [#done-when]

* [ ] Every row maps to one unit of the success criterion.
* [ ] Non-responses and late results are recorded, not dropped.
* [ ] The tracker is completed.

Common mistakes [#common-mistakes]

* **Columns that don't match the criterion.** If you can't count the result from the tracker, you'll argue about it later.
* **Dropping the awkward rows.** Non-replies and late payers are evidence too.
* **Logging rows you didn't observe.** SwiftCNS counts what's in the tracker. It may point out evidence that looks backfilled, but it can't tell sample rows from real ones.

<ForAgents>
  - `setup_tracker` via `configure_data_tracker` with `columns` (`id`, `header`, `type`: text, longText, number, date, select, multiSelect, url, attachment; `options` for selects). The request carries no proposed columns over MCP.
  - Rows: `add_data_tracker_rows` with a `requestKey`; keys are column ids, dates as `YYYY-MM-DD`, select values as the option label. CSV: upload with `begin_document_upload` / `complete_document_upload`, then `preview_data_tracker_import` and `import_data_tracker_rows`.
  - Once rows exist the active request is `mark_complete` (it appears in `activeActionRequests`, not in `permittedTransitionIds`); submit `complete_experiment` with `continueConversation: true` to start drafting the Learning (no separate tool).
</ForAgents>

Next [#next]

[Step 4: Decide, and record why](/docs/method/4-decide-and-record).


# 4. Decide, and record why (/docs/method/4-decide-and-record)



Before you start [#before-you-start]

* A completed tracker ([step 3](/docs/method/3-run-the-experiment)).
* The decision-maker, ready to make two calls: the result, and what happens next.

Steps [#steps]

<Steps>
  <Step title="Read the evidence">
    After **Complete tracker**, SwiftCNS drafts a Learning: factual observations from the rows, insights tied to each key metric, and its own assessment. Read them against the success criteria. They inform your call; they don't make it. Some insights may say what they think the evidence justifies; make your own call first.
  </Step>

  <Step title="Call the result and write what you learned">
    <Tabs items="['In your AI tool', 'In the app']">
      <Tab value="In your AI tool">
        <AgentPrompt>
          Show me the SwiftCNS Learning draft's observations. Set the result to \[Met / Not met / Unclear] and the narrative to: "\[what you learned]". Then publish it.
        </AgentPrompt>
      </Tab>

      <Tab value="In the app">
        In the Learning card, choose **Met**, **Not met** or **Unclear** under **Result**, write **What did you learn?**, then **Publish Learning**.
      </Tab>
    </Tabs>

    Write what the data taught you and what you noticed beyond it. Unclear is a valid result. A published Learning can't be edited.
  </Step>

  <Step title="Record the decision">
    <AgentPrompt>
      Prepare a SwiftCNS decision review for: \[the question]? Cite the Learning. Don't recommend a choice; I'll decide.
    </AgentPrompt>

    Choose **Move forward** (act on what you learned), **Change course** (keep the goal, change the approach), **Test again** (run another experiment first) or **Drop it**. Write why, and what happens next. Then **Record decision**.
  </Step>
</Steps>

<Figure src="/images/docs/first-test/09-decision-form.webp" alt="Record your decision form with Move forward, Change course, Test again and Drop it, and the required rationale" caption="Sample data" />

<InSwiftCNS>
  A **Learning** holds your result and narrative, plus the generated observations and **Insights**; it's listed under **Learnings**. The **Decision** holds the question, your choice, your reasons and the sources it cites; it's listed under **Decisions**. Neither choice has a default, and no recommendation is shown. Recording a decision doesn't carry it out.
</InSwiftCNS>

What you get [#what-you-get]

In the running example the team called the result **Met** (4 of 15 paid, against success criteria of 3) and wrote that teams of three or more were the ones paying. Then they chose **Move forward**: build a minimal billing path, keep setting up sharing by hand, track renewals, and test a lower price for two-person teams separately.

Decision Record (sample data):
- Question: Should we build the $79/month Team plan?
- Assumption: Trial teams that try to invite a teammate will pay $79 a month for a shared workspace.
- Experiment: Paid Team offer at invite: when a trial team clicks invite, offer the first month of a shared workspace for $79 through a payment link, and set up sharing by hand for teams that pay.
- Success criteria: At least 3 of the first 15 trial teams that see the offer pay $79 within 7 days of seeing it.
- Evidence: 4 of 15 teams paid within 7 days; a fifth paid on day 10. Every team that paid had invited 3 or more teammates.
- Result: Met
- Learning: Trial teams will pay to share. Teams of three or more are the ones paying; two-person teams said $79 is too much for two people.
- Decision: Move forward. Build a minimal billing path for the $79 Team plan and keep setting up sharing by hand until it's automated. Track whether paying teams renew after the first month, and test a lower price for two-person teams separately.

Done when [#done-when]

* [ ] The Learning is published with a result and your own words.
* [ ] The decision is recorded with its reasons and appears under **Decisions**.

Common mistakes [#common-mistakes]

* **Reading the result against new criteria.** Compare to the approved criteria first, then discuss.
* **Treating Not met as failure.** It tells you where not to spend the next quarter.
* **Stopping at the Learning.** Nothing prompts the decision; without one, the next person doesn't know what you did about it.
* **Letting someone else's take decide.** Make your call, then compare.

<ForAgents>
  - After `complete_experiment` with `continueConversation: true`, SwiftCNS prepares the draft and a `learning_card` request appears; `publish_learning` submits it. `get_learning` returns `version` and `resultAgentSummary` (SwiftCNS's assessment). Don't show the assessment to the user before they call the result.
  - `update_learning_draft`: JSON Patch, first `{"op":"test","path":"/version"}`, then replace `/result` (`MET`, `NOT_MET`, `UNCLEAR`) and `/narrative`. Set only what the user said.
  - `publish_learning` with `confirmed: true` needs a non-blank narrative.
  - Then `prepare_decision_review` (`question`, `references` such as `{type:"learning", id}`; leave `recommendation` out) and `submit_decision` with `{operation:"record", choice, rationale}`. `choice`: `MOVE_FORWARD`, `CHANGE_COURSE`, `TEST_AGAIN`, `DROP_IT`. Use `supersedesDecisionId` to replace a decision.
</ForAgents>

Next [#next]

[Best practices](/docs/method/best-practices) for testing ideas well.


# Best practices (/docs/method/best-practices)



Before you start [#before-you-start]

Read [the four steps](/docs/method) first. These practices sharpen them; they don't replace them.

Steps [#steps]

<Steps>
  <Step title="Pick the assumption that scares you">
    Test the belief that would sink the idea, not the one you're surest of. If you'd be relieved to skip it, that's the one. Write it with a number in it: "pay $79 a month", not "pay for it".
  </Step>

  <Step title="Agree the success criteria before anything runs">
    Settle the success criteria with whoever makes the decision, before the first result. Ask: "if we hit only half of this, would we still build it?" If yes, the criteria are too high or too vague. Never move them afterwards; run a new experiment instead.
  </Step>

  <Step title="Measure commitment, not compliments">
    Payment beats a pre-order, a pre-order beats a sign-up, and a sign-up beats "I'd use it". Choose the strongest signal you can afford to collect within weeks, not months.
  </Step>

  <Step title="Size the sample so one row can't flip it">
    If one more or one fewer result would change the call, treat the result as a first read, not a final answer. Give the experiment an end date and an owner.
  </Step>

  <Step title="Keep every row, including the awkward ones">
    Log non-replies separately from "no". Record late results with a note rather than dropping them. Add the one column the hypothesis depends on (in the example: how many teammates were invited). Use real data, logged as it arrives.
  </Step>

  <Step title="Make your own call first">
    Call the result and choose the decision on your own judgment before you ask anyone, including your AI tool, what they think. That's why no result is chosen for you and the decision form shows no recommendation. Read SwiftCNS's assessment and insights as input, then compare notes.
  </Step>

  <Step title="Write down why, and what happens next">
    A decision without reasons can't be reviewed or built on. Name the next step and how you'll know it worked.
  </Step>
</Steps>

<InSwiftCNS>
  **Unclear** is a valid result, and **Test again** is a real decision. A **Not met** result still produces a Learning and a Decision; it tells you where not to spend.
</InSwiftCNS>

What you get [#what-you-get]

In the running example, these habits paid off:

* The team chose the **paid offer** over a cheaper fake-door button, so the result measured payment, not interest.
* They kept the late payer (day 10) and the two non-replies in the tracker, which surfaced that approval slows some teams down.
* The teammate column showed that every paying team had invited 3 or more people, which shaped the decision: build for teams, test a lower price for pairs.

Done when [#done-when]

* [ ] Your criteria were agreed before the first result.
* [ ] A single result couldn't flip your call, or you said so in the Learning.
* [ ] Your decision says what happens next.

Common mistakes [#common-mistakes]

* **One question, many experiments in one conversation.** Keep one question per conversation so the record stays readable.
* **Treating earlier Learnings as proof.** Reuse them as context for the next test, not as evidence of demand.
* **Optimising the experiment instead of the decision.** The goal is a better decision, not a perfect test.

<ForAgents>
  - Never pre-select a Learning result or pass a `recommendation` to `prepare_decision_review` unless the user explicitly asks.
  - Prior Learnings are context: attach them with `attach_sources_to_conversation`; don't present them as proof.
</ForAgents>

Next [#next]

[Working with your AI tool](/docs/agents/mcp-best-practices): how to run these steps from Claude, ChatGPT, Cursor or Codex.


# How to test an idea (/docs/method)



Before you start [#before-you-start]

You're probably testing already: a pricing page, an onboarding change, an outreach channel, a pilot. What breaks is usually around the test, not the test itself:

* Success criteria get set after the results come in.
* Tests live in docs, spreadsheets and chat, so nobody can see what's running.
* Nobody remembers why a call was made, and the same idea comes back a quarter later.

This method gives every test the same four steps. They work with a spreadsheet; SwiftCNS drafts each step, you make every call, and it keeps the record. Use it when an idea would cost real time or money: a feature, a price, a channel, a quarter's roadmap. Skip it for choices that are cheap to reverse.

Steps [#steps]

<Steps>
  <Step title="Find the assumption">
    Every idea depends on something being true. Write down the one that would sink the idea if it turned out false. [Read more](/docs/method/1-find-the-assumption).
  </Step>

  <Step title="Set the success criteria">
    Decide what result counts as success, a number to reach in a set sample and time, before anything runs. Don't change it once results come in. [Read more](/docs/method/2-set-success-criteria).
  </Step>

  <Step title="Run the smallest experiment">
    Test the assumption on a slice: a few customers, one market, a few weeks. Cheap enough to run now, real enough that a miss would change your mind. [Read more](/docs/method/3-run-the-experiment).
  </Step>

  <Step title="Decide, and record why">
    Say whether the result met the criteria and what you learned. Then a person decides what happens next, and writes down why. [Read more](/docs/method/4-decide-and-record).
  </Step>
</Steps>

Who does what [#who-does-what]

| Step                           | SwiftCNS proposes                                                                                    | You decide                                                                           |
| ------------------------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| 1. Find the assumption         | Assumptions scored for importance and evidence; hypotheses with provisional success criteria         | Which assumption and which hypothesis to test                                        |
| 2. Set the success criteria    | Experiment designs scored for setup, run time, cost and data reliability, each with success criteria | Which design, who owns it, by when; approving it fixes the criteria                  |
| 3. Run the smallest experiment | What one tracker row should be, and its columns                                                      | Running it, logging the evidence, completing the tracker                             |
| 4. Decide, and record why      | Observations and insights from the evidence                                                          | The result (**Met**, **Not met** or **Unclear**), what you learned, and the decision |

SwiftCNS suggests where to start when it proposes options, and drafts an assessment of the evidence. It never sets the result or the decision for you: neither is chosen until you choose it, and the decision form shows no recommendation. Your AI tool is where you ask; it acts on your behalf only for what you tell it to do.

<InSwiftCNS>
  * Step 1: **Assumptions** and a **Hypothesis**, the testable version.
  * Step 2: an **Experiment** with success criteria and key metrics.
  * Step 3: the **Data tracker**; **Complete tracker** saves the evidence snapshot.
  * Step 4: a **Learning** (your result and what you learned, plus generated insights) and a **Decision**: **Move forward**, **Change course**, **Test again** or **Drop it**.
</InSwiftCNS>

What you get [#what-you-get]

One worked example runs through every step page: a SaaS company deciding whether to build a $79/month Team plan. It's sample data from a real SwiftCNS run. The result was **Met**, and the team chose **Move forward**.

Done when [#done-when]

* [ ] You can name the four steps and what each one produces.
* [ ] You know which step your current idea is stuck on.

Common mistakes [#common-mistakes]

* **Testing the comfortable assumption.** The one you're sure of teaches you nothing.
* **"We shipped it" as evidence.** Shipping is an activity, not a result.
* **No end date.** Experiments without one drift into "still running".

More in [Best practices](/docs/method/best-practices).

<ForAgents>
  * Workflow stages as reported by `get_conversation_progress`: `DISCOVERY`, `DRAFT`, `TRACKER`, `LEARNING` (`RUNNING` only in edge cases).
  * The Decision is recorded separately with `prepare_decision_review` and `submit_decision`; after `publish_learning` no transition prompts it.
</ForAgents>

Next [#next]

[Step 1: Find the assumption](/docs/method/1-find-the-assumption).


# Glossary (/docs/reference/glossary)



Before you start [#before-you-start]

These docs use plain words for the method and SwiftCNS names only where you'll see them. This page connects the two.

Steps [#steps]

Find the word you saw, then read across.

| Method word           | In SwiftCNS                             | What it is                                                                                                                                          |
| --------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Idea                  | **Project**, **Conversation**           | The choice you're testing. A project holds its work; a conversation is one thread of it.                                                            |
| Assumption            | **Assumption**                          | Something that must be true for the idea to work. Rated 1 to 5 for importance and for evidence you already have.                                    |
| (testable assumption) | **Hypothesis**                          | The assumption rewritten as a prediction a test could prove wrong.                                                                                  |
| Experiment            | **Experiment**                          | The smallest test that could prove the prediction wrong. Has an owner, optional due date and status: Draft, Approved, Running, Completed.           |
| Success criteria      | **Success criteria**, **Key metrics**   | The number, sample and time window that count as success, set before the experiment runs and fixed on approval.                                     |
| Evidence              | **Data tracker**, **Evidence snapshot** | Results logged as rows. **Complete tracker** saves them as a snapshot that can't change.                                                            |
| Result                | **Met**, **Not met**, **Unclear**       | Your call on whether the evidence met the success criteria. Part of the Learning.                                                                   |
| What you learned      | **Learning**                            | Your result and narrative, plus the observations and **Insights** SwiftCNS drafted from the snapshot. Fixed once published.                         |
| Decision              | **Decision**                            | The question, your choice (**Move forward**, **Change course**, **Test again**, **Drop it**), why and what happens next, and links to the evidence. |
| Record                | **Decision Record**                     | The decision together with everything behind it. Listed under the project's **Decisions**.                                                          |

Other terms:

| Term                                   | Meaning                                                                                                                                          |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Workspace**                          | Your team's space in SwiftCNS. Holds projects and members. Created in the app.                                                                   |
| **MCP**                                | Model Context Protocol, the open standard your AI tool uses to connect to SwiftCNS.                                                              |
| **MCP client access**                  | The settings page where you copy the MCP URL, open setup instructions and remove authorized applications.                                        |
| **Action card**                        | A choice waiting in the thread, such as **Select assumptions** or **Complete tracker**. Over MCP it's an Action Request.                         |
| **Now**, **Data tracker**, **Lineage** | The workbench's right-hand tabs: the next step, the evidence, and the full record.                                                               |
| **Permissions**                        | Read CNS, Update CNS, Make decisions, Read connected sources. Granted per client when it signs in.                                               |
| **Plugins**                            | Connections to Google Drive, GitLab and Atlassian that SwiftCNS can search and import from as project documents (context, not tracker evidence). |
| **Replace (supersede)**                | Record a new decision that replaces an earlier one, keeping both on record.                                                                      |

What you get [#what-you-get]

One vocabulary across the method, the app and your AI tool.

Done when [#done-when]

* [ ] You can map any word your AI tool uses back to a step of the [method](/docs/method).

<ForAgents>
  Public IDs are prefixed by type: `wks_` workspace, `prj_` project, `cnv_` conversation, `asm_` assumption, `hyp_` hypothesis, `exp_` experiment, `dtk_` data tracker, `ins_` insight, `lrn_` learning, `dec_` decision, `doc_` document, `usr_` user. Reference types for decisions: `learning`, `insight`, `experiment`, `hypothesis`, `assumption`, `document`, `decision`.
</ForAgents>

Next [#next]

[Your first test](/docs/get-started/first-test).


# MCP server reference (/docs/reference/mcp-server)



Before you start [#before-you-start]

* Endpoint: https://api.swiftcns.ai/mcp (streamable HTTP). The app shows the URL for your environment under **Settings → MCP client access**.
* Auth: OAuth 2. Your client opens a sign-in page; access tokens last up to 5 minutes and refresh automatically.
* Scopes: `cns:read` (Read CNS), `cns:write` (Update CNS), `cns:decide` (Make decisions), `cns:sources:read` (Read connected sources).

Steps [#steps]

How an agent should drive a conversation:

<Steps>
  <Step title="Find scope">
    `list_workspaces`

    , 

    `list_projects`

    . To start: 

    `generate_resource_id`

    , 

    `create_project`

    , 

    `create_conversation`

    .
  </Step>

  <Step title="Read the position">
    `get_conversation_progress`

     returns the stage, active Action Requests, 

    `actionOperations`

     (ready-to-submit tools), 

    `permittedTransitionIds`

     and 

    `nextTransitionId`

    .
  </Step>

  <Step title="Talk or submit">
    Ordinary input: 

    `send_message`

     with a stable 

    `requestKey`

     (no 

    `parentMessageId`

     on the first message), then poll 

    `get_message`

     until 

    `execution.status`

     is no longer queued or running. The message 

    `status`

     may be 

    `requires-action`

     when a card is waiting. Decisions: the tool named in 

    `actionOperations`

    , with 

    `actionRequestId`

     and 

    `contractVersion`

    .
  </Step>

  <Step title="Continue">
    Add 

    `continueConversation: true`

     and 

    `parentMessageId`

     (the request's 

    `messageId`

    ; for workflow-surface requests, the latest assistant leaf) to get the next agent turn. The receipt's 

    `continuationMode`

     says whether one is needed: 

    `NONE`

     means the next request is already waiting.
  </Step>

  <Step title="Recover">
    If 

    `execution.status`

     is 

    `FAILED`

     and 

    `retryable`

     is true, call 

    `retry_response`

    .
  </Step>

  <Step title="Reload">
    After every action, read progress again. Tool results, not prose, are the authority.
  </Step>
</Steps>

What you get [#what-you-get]

Tools by method step:

| Step                | Tools                                                                                                                                                                                                                                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Setup               | `list_workspaces`, `list_projects`, `get_project`, `create_project`, `generate_resource_id`                                                                                                                                                                                                                                  |
| Conversation        | `create_conversation`, `open_experiment_conversation`, `list_conversations`, `get_conversation`, `get_conversation_progress`, `list_conversation_messages`, `list_conversation_option_sets`, `send_message`, `get_message`, `retry_response`, `stop_response`, `attach_sources_to_conversation`, `apply_field_edit_proposal` |
| 1. Assumption       | `answer_clarifying_questions`, `select_assumptions`, `select_hypothesis`, `get_assumption`, `get_hypothesis`                                                                                                                                                                                                                 |
| 2. Success criteria | `select_experiment`, `assign_experiment`, `list_eligible_experiment_assignees`, `approve_experiment`, `get_experiment`, `list_experiments`                                                                                                                                                                                   |
| 3. Experiment       | `configure_data_tracker`, `get_data_tracker`, `list_data_tracker_rows`, `add_data_tracker_rows`, `update_data_tracker_row`, `preview_data_tracker_import`, `import_data_tracker_rows`, `get_data_tracker_import`, `complete_experiment`                                                                                      |
| 4. Decide           | `get_learning`, `list_learnings`, `update_learning_draft`, `publish_learning`, `get_insight`, `prepare_decision_review`, `submit_decision`, `get_decision`, `list_decisions`, `list_evidence_assessments` (history only)                                                                                                     |
| Documents           | `list_documents`, `get_document`, `begin_document_upload`, `complete_document_upload`, `import_document`, `search_project_sources`                                                                                                                                                                                           |

Resources: `swiftcns://projects/{projectId}` (project context), `.../experiments/{experimentId}` (experiment brief), `.../learnings/{learningId}` (published Learning), `.../decisions/{decisionId}` (Decision Record).

Prompts: `continue_experiment`, `import_experiment_evidence`.

Workflow stages reported by `get_conversation_progress`: `DISCOVERY`, `DRAFT`, `TRACKER`, `LEARNING` (`RUNNING` only in edge cases).

Action Requests, in order: `question_answer` (any time), `assumption_selection`, `hypothesis_selection`, `experiment_card_selection`, `assign_experiment`, `approve_experiment`, `setup_tracker`, `mark_complete`, `learning_card`, and `decision_record` (separate slot). Learning results: `MET`, `NOT_MET`, `UNCLEAR`. Decision choices: `MOVE_FORWARD`, `CHANGE_COURSE`, `TEST_AGAIN`, `DROP_IT`.

Done when [#done-when]

* [ ] Your agent can go from `list_workspaces` to `submit_decision` using only the tools above.

Troubleshooting [#troubleshooting]

* **No tool drafts the Learning.** Submit `complete_experiment` with `continueConversation: true`. If you didn't, call `send_message` with that action's `actionRequestId` and a returned `parentMessageId`.
* **Tracker set up, but no complete request.** The stage waits on `log_evidence`; add rows first, then `mark_complete` appears.
* **`setup_tracker` has no proposed columns.** Ask the user what one row is and propose columns; submit them with `configure_data_tracker`.
* **`update_learning_draft` conflicts.** Read `get_learning` for the current `version` and test that value first.
* **Nothing offered after `publish_learning`.** Call `prepare_decision_review` yourself.
* **Conflict on resubmit.** Replay with the original identity and identical input; never a new key.

<ForAgents>
  Create IDs with `generate_resource_id` and reuse them on retry. `create_conversation` needs a `title`. Writes that take a `requestKey` (`send_message`, `add_data_tracker_rows`, imports) treat the same key as the same request. `continueConversation: true` on an action requests the next agent turn; it needs `cns:read` and `cns:write`.
</ForAgents>

Next [#next]

[Troubleshooting and FAQ](/docs/reference/troubleshooting-faq).


# Security and data (/docs/reference/security-and-data)



Before you start [#before-you-start]

* This page is the short version. The [privacy policy](https://swiftcns.ai/privacy-policy/) and [terms of service](https://swiftcns.ai/terms-of-service/) are the full ones.
* Questions or a security report: [security@swiftcns.ai](mailto:security@swiftcns.ai).

Steps [#steps]

<Steps>
  <Step title="Check who can see your work">
    Everything lives in a workspace. People reach it in one of three ways:

    * **Workspace members**, added under **Settings → Team access**, can open and edit every project in the workspace. Only the owner manages members and billing.
    * **Shares** give one signed-in account **Viewer** or **Editor** access to a conversation, a project or the whole workspace. You share by email; there are no public links.
    * **Viewers** can read everything they were given, including trackers and the record, and change nothing.

    See [Team and roles](/docs/use-the-app/team-and-roles).
  </Step>

  <Step title="Check what your AI tool can reach">
    Your AI tool signs in as you and can only reach what you can reach. It holds only the permissions you approved when you connected it ([Permissions](/docs/agents/permissions)), and its access tokens last five minutes at most before they refresh. An AI tool can't add people, change shares or manage its own access.

    To disconnect it, go to **Settings → MCP client access**, find it under **Authorized applications** and remove it.
  </Step>

  <Step title="Check what connected tools can reach">
    Each plugin connection (Google Drive, GitLab, Jira and Confluence) belongs to one person in one workspace. SwiftCNS only searches and reads; it never writes back. It reads when you browse or import, or when you ask it in chat to look for evidence there. Google Drive asks for read access to your Drive files.

    What you import becomes a project document that your project's members can read. Disconnecting stops new imports; documents already imported stay in their projects until you delete them. See [Documents and plugins](/docs/use-the-app/documents-and-plugins).
  </Step>

  <Step title="Export or delete your work">
    Export any time: **Export PDF** gives the experiment brief, **Export CSV** gives the tracker rows, and documents download as uploaded. For a full export of a workspace, or to have it deleted, email [security@swiftcns.ai](mailto:security@swiftcns.ai) from the owner's address.
  </Step>
</Steps>

<InSwiftCNS>
  **How AI uses your content.** We don't use your content to train AI models. We use it to run and improve SwiftCNS. Your conversations, trackers, Learnings and Decisions stay until you delete them.
</InSwiftCNS>

What you get [#what-you-get]

* You own everything you create.
* Access follows people: a person's AI tool and connected tools never reach more than that person can.
* A clear way out: export what you need, disconnect what you connected, and ask for deletion.

Done when [#done-when]

* [ ] You know who in your workspace can edit, and who only reads.
* [ ] You've removed any AI tool you no longer use under **Authorized applications**.

Common mistakes [#common-mistakes]

* **Adding a stakeholder as a workspace member to let them read.** Members can edit every project. Share as **Viewer** instead.
* **Connecting a shared or admin account to a plugin.** Connect your own account, so imports reflect what you're allowed to see.

<ForAgents>
  - No MCP tool manages members, shares, plugin connections or agent access. Send the user to **Settings**.
  - Every call is checked against the signed-in user's access to the workspace, project and conversation. A 403 means the user lacks access, not that the tool is broken.
</ForAgents>

Next [#next]

[Troubleshooting and FAQ](/docs/reference/troubleshooting-faq).


# Troubleshooting and FAQ (/docs/reference/troubleshooting-faq)



Before you start [#before-you-start]

Most problems are one of three things: your AI tool isn't signed in, it lacks a permission, or a step is waiting for you.

Steps [#steps]

<Steps>
  <Step title="Ask where things stand">
    <AgentPrompt>
      In SwiftCNS, what's the current step on \[project], and is anything waiting for me?
    </AgentPrompt>
  </Step>

  <Step title="Match the symptom below" />
</Steps>

What you get [#what-you-get]

**Connection**

* *401 or "invalid credentials".* Sign in again from your client. A removed authorization needs a fresh sign-in.
* *No workspaces listed.* You signed in with a different account, or you haven't [created a workspace](/docs/get-started/install).

**Workflow**

* *Nothing happens after a choice.* Ask your AI tool to continue, or check **Now** in the app. After assigning or approving, the next card is already waiting. After setting up the tracker, add rows; **Complete tracker** appears once there are rows.
* *No Learning draft after completing the tracker.* Ask your tool to continue the conversation. If it says the evidence isn't available yet, wait a minute and ask again.
* *The Learning is published but no decision was offered.* Expected today. Ask for a decision review.
* *Your tool can't select or approve.* It lacks **Make decisions**. Reconnect and grant it, or act in the app.
* *Replies take 20 to 60 seconds.* Normal; each step runs SwiftCNS's own agents.
* *The Learning result already reads Unclear.* Some versions of the app show Unclear until you choose. It isn't a judgment; choose your own.

**FAQ**

* *Do I need SwiftCNS to use the method?* No. The [method](/docs/method) works with a spreadsheet.
* *Which AI tools work?* Claude, ChatGPT (developer mode, depending on your plan), Cursor, Claude Code, Codex, and any MCP client with remote HTTP servers and OAuth.
* *Can my AI tool see other teams' work?* No. It sees only what you can.
* *Does recording a decision change anything?* No. It records the choice; your team carries it out.
* *Can I change a Learning or a decision?* No; both are fixed once published or recorded. Record a new decision that replaces the old one; both stay on record.
* *Is MCP included in my plan?* Yes, on every plan, Free included. The app and MCP share usage.
* *What happens when I run out of usage?* The chat says **You've used this month's usage**. Upgrade under **Manage plan**, or continue when usage resets with your billing cycle. Nothing recorded is lost. See [Plans and usage](/docs/use-the-app/plans-and-usage).
* *Do you train AI models on my content?* No. We use it to run and improve SwiftCNS. See [Security and data](/docs/reference/security-and-data).
* *How do I disconnect my AI tool?* **Settings → MCP client access**, under **Authorized applications**.

Done when [#done-when]

* [ ] Your AI tool can name the current step and what's waiting for you.

Troubleshooting [#troubleshooting]

Still stuck? Open the conversation in the app (your AI tool can give you the link) and check the **Now** tab.

<ForAgents>
  `get_conversation_progress` returns `browserUrl` for the conversation. If `execution.retryable` is true after a failure, call `retry_response`.
</ForAgents>

Next [#next]

[Glossary](/docs/reference/glossary).


# Documents and plugins (/docs/use-the-app/documents-and-plugins)



Before you start [#before-you-start]

* Editor access to the project. Viewers can read documents but can't add them.
* For plugins: the Team or Programs & Studios plan ([Plans and usage](/docs/use-the-app/plans-and-usage)), and your own account in the tool you're connecting.

Steps [#steps]

<Steps>
  <Step title="Upload a document">
    Open the project's **Documents** page and choose **Upload**. SwiftCNS accepts PDF, TXT, MD, CSV, LOG, HTML, XML and CSS files up to 10 MB each. Each document shows where it came from: **Upload**, **MCP**, **Connected app** or **Generated in SwiftCNS**.

    To log tracker rows from a spreadsheet, don't upload it here: use **Import CSV file** in the tracker ([Track experiments](/docs/use-the-app/track-experiments)).
  </Step>

  <Step title="Connect a plugin">
    Open **Plugins** from the sidebar and choose **Connect** on Google Drive, GitLab or Atlassian (Jira and Confluence). Sign in to that tool with your own account, then choose **Add to project** for the projects that should use it.

    <Figure src="/images/docs/app/plugins-hub.webp" alt="Plugins page listing Atlassian, GitLab and Google Drive, each with a Connect button" />

    The connection is yours: teammates connect their own accounts. Google Drive asks for read access to your Drive files; SwiftCNS only searches and reads, and never writes back ([Security and data](/docs/reference/security-and-data)).
  </Step>

  <Step title="Import what matters">
    Choose **Browse**, open folders or search, select the items you need and choose **Import**. Imported items become project documents that everyone on the project can use.

    <Figure src="/images/docs/app/import-from-connected-app.webp" alt="Import from connected app dialog with two Drive files selected for import" caption="Sample data" />
  </Step>

  <Step title="Use it in a conversation">
    In a conversation, open **Context** and choose **Add sources**: **Project sources** lists documents already in the project, and **Apps** browses a connected tool (**Import & attach**). The **+** menu in the message box does the same with **Upload files** and **Add project context**. Cite a source in chat with **@**.

    You can also ask without attaching first, for example "Browse my Google Drive for evidence about our pilot". Results only become project documents when you import or attach them.
  </Step>

  <Step title="Disconnect">
    Open the plugin under **Plugins** and disconnect it. Documents already imported into projects remain available.
  </Step>
</Steps>

<InSwiftCNS>
  Documents are **sources**. SwiftCNS reads the ones attached to a conversation as context, and a reply that used them lists them under **Sources consulted**. A document is input to your judgment, not a substitute for the tracker: evidence that decides the result still goes in the tracker as rows.
</InSwiftCNS>

What you get [#what-you-get]

For the running example, that would mean importing the trial team interviews and the payment links export from Drive as project documents. They give SwiftCNS context, while the 15 tracker rows decide whether the success criteria were met.

Done when [#done-when]

* [ ] The documents your team argues from are in the project, not only in someone's Drive.
* [ ] Each conversation has the sources it needs attached.

Common mistakes [#common-mistakes]

* **Importing a whole folder "just in case".** Bring what bears on the idea you're testing; extra sources make drafts vaguer.
* **Treating a document as evidence for the result.** Log what you observed in the tracker. Documents give context.

<ForAgents>
  - `import_document` takes a public HTTPS URL. For a local file, use `begin_document_upload`, upload, then `complete_document_upload`.
  - `attach_sources_to_conversation` attaches 1 to 50 sources. Plugin connections can't be made over MCP; send the user to **Plugins**.
</ForAgents>

Next [#next]

[Plans and usage](/docs/use-the-app/plans-and-usage).


# Learnings and Decisions (/docs/use-the-app/learnings-and-decisions)



Before you start [#before-you-start]

* A completed tracker, for a Learning ([step 3](/docs/method/3-run-the-experiment)).
* A question to settle, for a Decision. A Decision can also stand alone, without a Learning.

Steps [#steps]

<Steps>
  <Step title="Write the Learning">
    After **Complete tracker**, the workbench shows the Learning draft: observations and insights SwiftCNS drafted from the evidence, then two parts that are yours:

    * **Result**: did the result meet the success criteria? **Met**, **Not met** or **Unclear**.
    * **What did you learn?**: what running this taught you, from the data and beyond it (up to 5,000 characters).

    Choose **Save draft** to come back later, or **Publish Learning**. Publishing puts it on the record; it can't be edited afterwards.

    <Figure src="/images/docs/first-test/08c-learning-filled.webp" alt="Learning editor with the result set to Met and the narrative written" caption="Sample data" />
  </Step>

  <Step title="Record a Decision">
    Ask your AI tool to prepare a decision review, or start one from the conversation. The form shows **What you tested**, **What happened** and **What you learned**, then asks you to choose **Move forward**, **Change course**, **Test again** or **Drop it**, and to write **Why this decision, and what happens next?** (required). Choose **Record decision**, or **Cancel review**.

    <Figure src="/images/docs/first-test/09c-decision-filled.webp" alt="Record your decision form with Move forward chosen and the reasons written" caption="Sample data" />
  </Step>

  <Step title="Find them later">
    **Learnings** lists every Learning in the project, filterable by **published** and **draft**. **Decisions** lists recorded decisions, filterable by choice and grouped **by day** or **by experiment**, with the Learning results they cite. Choose a row to open it in its workbench, in **Lineage**.

    <Figure src="/images/docs/app/decisions.webp" alt="Decisions register with filters for each choice and one Move forward decision" caption="Sample data" />
  </Step>

  <Step title="Replace a Decision">
    Recorded decisions can't be edited. If things change, ask your AI tool to prepare a new decision review that replaces the earlier one. The old one stays on the record, marked as replaced.
  </Step>
</Steps>

<InSwiftCNS>
  No result or choice is pre-selected and no recommendation is shown, so the call is your own. Recording a decision doesn't start any work; that's still your team's job.
</InSwiftCNS>

What you get [#what-you-get]

A record anyone in the workspace can read: what you believed, what you tested, what happened, what you concluded and what you chose. In the running example, **Learnings** shows one published Learning (**Met**) and **Decisions** one **Move forward**.

Done when [#done-when]

* [ ] Each completed experiment has a published Learning.
* [ ] Each question you settled has a recorded Decision with reasons.

Common mistakes [#common-mistakes]

* **Copying the drafted insights as your Learning.** Write what *you* concluded; the insights are input.
* **Recording "Move forward" with no next step.** Say what happens next and how you'll know.

<ForAgents>
  - `list_learnings`, `get_learning`, `update_learning_draft`, `publish_learning`.
  - `list_decisions` (filter by `conversationId`, `experimentId`, `learningId`, `status` CURRENT or SUPERSEDED), `get_decision`, `prepare_decision_review`, `submit_decision`. Replace with `supersedesDecisionId`.
</ForAgents>

Next [#next]

[Team and roles](/docs/use-the-app/team-and-roles).


# Plans and usage (/docs/use-the-app/plans-and-usage)



Before you start [#before-you-start]

* A SwiftCNS workspace. The plan belongs to the workspace, and only its owner can change it.
* Current prices are on [swiftcns.ai/pricing](https://swiftcns.ai/pricing/). If this page and the pricing page disagree, the pricing page is right.

Steps [#steps]

<Steps>
  <Step title="Pick the plan that fits how you work">
    |                 | Free                                      | Team                                           | Programs & Studios                                          |
    | --------------- | ----------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------- |
    | Price           | $0                                        | $79 USD a month, or 20% off paid yearly        | Custom                                                      |
    | Who it's for    | A founder testing their first idea        | A team deciding what to build, together        | Accelerators, venture studios, companies running many teams |
    | Usage           | 1×: enough to take one idea to a decision | 10×: sized for a team testing ideas every week | Shared across your cohort, sized with you                   |
    | Members         | 1                                         | Up to 20                                       | Unlimited                                                   |
    | Projects        | 1                                         | 15                                             | Unlimited                                                   |
    | Connected tools | Not included                              | Included                                       | Included                                                    |
    | Workspaces      | 1                                         | 1                                              | One per team, plus a cohort view                            |
    | Support         | Docs                                      | Priority, plus an onboarding call              | Dedicated, with invoice billing                             |

    Connected tools are the [plugins](/docs/use-the-app/documents-and-plugins) for Google Drive, GitLab, and Jira and Confluence.
  </Step>

  <Step title="Know how usage works">
    Usage is shown as a multiple of Free. How far it goes depends on how you work: long documents, connected tools and heavy agent use draw more. The app and your AI tool share the same usage, and it resets each billing cycle.
  </Step>

  <Step title="If usage runs out">
    The chat shows **You've used this month's usage**: "Upgrade your plan to keep going, or continue when your usage resets." Choose **Manage plan** to see your options. Nothing you've recorded is lost; your projects, trackers, Learnings and Decisions stay readable.
  </Step>

  <Step title="Change plan">
    Open **Billing** from the settings sidebar, under your workspace, and choose a plan under **Plans**. For Programs & Studios, [book a call](https://swiftcns.ai/pricing/).
  </Step>
</Steps>

<InSwiftCNS>
  Every plan includes the full loop (assumption, experiment, success criteria, evidence, decision), Decision Records, the SwiftCNS MCP and unlimited viewers. You can export any time: PDF briefs, CSV tracker data and your documents, with a full export on request. You own everything you create.
</InSwiftCNS>

What you get [#what-you-get]

A plan that matches how many people test with you and how often. Viewers don't count as members on any plan, so share the record with co-founders, advisors and investors freely ([Team and roles](/docs/use-the-app/team-and-roles)).

Done when [#done-when]

* [ ] Everyone who runs experiments is a member, and everyone who only reads is a viewer.
* [ ] Your plan has room for the projects you're running this quarter.

Common mistakes [#common-mistakes]

* **Adding readers as members.** Viewers are free and read-only; save member seats for people who run tests.
* **Running a team on Free.** Free has one member, so teammates can only read. When more than one person runs tests, move to Team.

<ForAgents>
  - No MCP tool reads or changes the plan. When a request fails because usage ran out, tell the user and point them to **Billing**; don't retry in a loop.
  - Never quote token amounts. Describe usage as a multiple of Free.
</ForAgents>

Next [#next]

[Security and data](/docs/reference/security-and-data): who can see your work, and what your AI tool can do.


# Workspace and projects (/docs/use-the-app/projects-and-home)



Before you start [#before-you-start]

* A workspace ([install](/docs/get-started/install)). Workspace members can see and edit every project in it; people you share with as viewers can only read.

Steps [#steps]

<Steps>
  <Step title="Start from the dashboard">
    The dashboard is your workspace home. Describe something to test in the box at the top, or open a project.

    * **Waiting on you** lists steps you can act on now: experiments to assign or approve, trackers to complete.
    * **Recent projects** lists projects, with search. Choose **New project** to add one.

    <Figure src="/images/docs/app/dashboard.webp" alt="Workspace dashboard with the composer, Waiting on you, and Recent projects" caption="Sample data" />
  </Step>

  <Step title="Open a project">
    A project holds one area of work, such as pricing or onboarding. Its **Project home** shows:

    * **Work**: every conversation in the project, grouped by where it stands (exploring, designing, collecting evidence, learning, decided). Filter by **your move**, **overdue** or search.
    * **At a glance**: where work sits, what needs attention (overdue, unassigned, quiet for 7+ days), how long a learning cycle takes, and what's on the record.

    <Figure src="/images/docs/app/project-home.webp" alt="Project home with the Work list and the At a glance panel" caption="Sample data" />
  </Step>

  <Step title="Use the sidebar">
    Inside a project, the sidebar has **Project home**, **Experiments**, **Learnings**, **Decisions** and **Documents**. **Workspace recents** reopens your latest conversations. **New conversation** starts a fresh question; **Plugins** connects outside sources; **Docs** opens this site.
  </Step>
</Steps>

<InSwiftCNS>
  Workspace → project → conversation. One conversation usually follows one question to a Decision. Learnings and Decisions belong to the project, so later conversations can cite them.
</InSwiftCNS>

What you get [#what-you-get]

A place for each question, and one view of everything in flight. In the running example, the project "\[Docs example] Team plan pricing" holds one conversation, now under **Decided**.

Done when [#done-when]

* [ ] You can find a project's experiments, Learnings and Decisions from the sidebar.
* [ ] You check **Waiting on you** to see what needs you next.

Common mistakes [#common-mistakes]

* **One giant project.** Split by area of work so the record stays readable.
* **Many questions in one conversation.** Start a **New conversation** per question.

<ForAgents>
  - `list_workspaces`, `list_projects`, `get_project`; create with `generate_resource_id` (`PROJECT`) then `create_project`.
  - `list_conversations` finds existing work; `get_conversation_progress` returns its stage and `browserUrl` to open it in the app.
</ForAgents>

Next [#next]

[The workbench](/docs/use-the-app/workbench): where each conversation happens.


# Team and roles (/docs/use-the-app/team-and-roles)



Before you start [#before-you-start]

* The person you're adding needs a SwiftCNS account. Adding them sends no email, so tell them.
* How many members you can add depends on your plan ([Plans and usage](/docs/use-the-app/plans-and-usage)). Viewers are unlimited.

Steps [#steps]

<Steps>
  <Step title="Add someone to the whole workspace">
    Go to **Settings → Team access**. Under **Add someone to** your workspace, enter their email and choose **Add**. They join as a member who can open and edit every project in the workspace.

    <Figure src="/images/docs/app/settings-team-access.webp" alt="Team access settings with the add-by-email form and the list of people with access" caption="Sample data" />
  </Step>

  <Step title="Or share one project or conversation">
    Open the project and choose **Share**, or choose **Share** from a conversation's menu. Enter the email they sign in with, pick a role, then **Grant access**:

    * **Editor**: can start conversations, act on cards, log evidence, publish Learnings and record decisions.
    * **Viewer**: can open everything, including trackers, but can't change anything.

    <Figure src="/images/docs/app/share-dialog.webp" alt="Share project dialog with the owner, email field and role selector" caption="Sample data" />
  </Step>

  <Step title="Assign work">
    Assign each experiment to an owner (an editor on the project) with a due date. The owner sees it under **Waiting on you** and **assigned to me** on the Experiments board.
  </Step>
</Steps>

<InSwiftCNS>
  Sharing works by email to signed-in accounts; there are no public links. Access inherited from the workspace isn't listed in a project's share dialog. Removing a direct share doesn't remove workspace access. Each person's AI tool can only reach what that person can reach ([Security and data](/docs/reference/security-and-data)).
</InSwiftCNS>

What you get [#what-you-get]

| Who                           | Can                                                  |
| ----------------------------- | ---------------------------------------------------- |
| Workspace owner               | Everything, plus team access and billing             |
| Workspace member              | View and edit every project in the workspace         |
| Project editor                | Work in that project                                 |
| Project viewer                | Read that project, including trackers and the record |
| Conversation editor or viewer | The same, for one conversation                       |

Done when [#done-when]

* [ ] Your teammates can open the project.
* [ ] Each running experiment has an owner who is an editor.

Common mistakes [#common-mistakes]

* **Sharing with the wrong account.** Add the email they sign in with.
* **Making a stakeholder a member or editor to let them read.** Members can edit everything. Share as **Viewer**; it's enough to follow the record.

<ForAgents>
  - `list_eligible_experiment_assignees` returns the people an experiment can be assigned to.
  - No MCP tool manages members or shares; direct the user to **Settings → Team access** or **Share**.
</ForAgents>

Next [#next]

[Working with your AI tool](/docs/agents/mcp-best-practices).


# Track experiments (/docs/use-the-app/track-experiments)



Before you start [#before-you-start]

* At least one selected experiment ([step 2 of the method](/docs/method/2-set-success-criteria)).

Steps [#steps]

<Steps>
  <Step title="Open the Experiments board">
    In a project, choose **Experiments**. The **board** groups experiments by where they stand: **designing**, **collecting evidence**, **learning** and **decided**. Switch to **list** for a compact view. Filter by **all** or **assigned to me**, or search.

    <Figure src="/images/docs/app/experiments-board.webp" alt="Experiments board with designing, collecting evidence, learning and decided columns" caption="Sample data" />

    Each card shows the experiment type, its hypothesis, owner and due date. Open one to go to its workbench.
  </Step>

  <Step title="Keep owner and due date current">
    Owner and due date are set when you assign the experiment, and shown in the workbench's **Now** tab. The owner must be an editor on the project. Overdue experiments show on **Project home** under **Needs attention**.
  </Step>

  <Step title="Log evidence in the tracker">
    Open the experiment's workbench, then **Data tracker** → **Open tracker**. In **Log evidence**:

    * **Add row** to type one result.
    * **Paste rows** from a spreadsheet.
    * **Import CSV file** for a batch; map its headers to the tracker's columns.
    * **Columns** to review the structure; **Export CSV** to take the data out.

    Or ask your AI tool: "Add these results to the SwiftCNS tracker: \[rows]".

    <Figure src="/images/docs/first-test/07c-tracker-grid.webp" alt="Log evidence grid with Add row, Paste rows, Import CSV file, Columns and Export CSV" caption="Sample data" />
  </Step>

  <Step title="Complete the tracker">
    When the sample is in or time is up, choose **Complete tracker** on the card or in **Now**. It saves a fixed snapshot of the rows and moves the experiment to **learning**. You can still open the tracker to read it.
  </Step>
</Steps>

<InSwiftCNS>
  Experiment statuses: **Draft** → **Approved** → **Running** → **Completed**. The tracker starts when you create it and becomes read-only when completed. Viewers can open everything but can't change it.
</InSwiftCNS>

What you get [#what-you-get]

A live picture of what your team is testing, who owns each test and what's late, with evidence for each kept in one place. In the running example, "Paid Team offer at invite" sits under **decided**, owned by the person who ran it.

Done when [#done-when]

* [ ] Every running experiment has an owner and a due date.
* [ ] Evidence goes into the tracker as it arrives, not at the end.

Common mistakes [#common-mistakes]

* **Collecting in a side spreadsheet and importing at the end.** You lose the timeline of when evidence arrived.
* **Completing early to "see what it says".** Completing is final; finish the sample first.

<ForAgents>
  - `list_experiments`, `get_experiment` (status, owner, `dueAt`, metrics).
  - `get_data_tracker`, `list_data_tracker_rows`, `add_data_tracker_rows`, `update_data_tracker_row`; CSV via `preview_data_tracker_import` then `import_data_tracker_rows`.
  - `complete_experiment` submits the `mark_complete` request.
</ForAgents>

Next [#next]

[Learnings and Decisions](/docs/use-the-app/learnings-and-decisions).


# The workbench (/docs/use-the-app/workbench)



Before you start [#before-you-start]

* A conversation in a project. Start one from **Project home**, **New conversation**, or by asking your AI tool.

Steps [#steps]

<Steps>
  <Step title="Work in the thread">
    The thread shows SwiftCNS's replies and **action cards**: choices to make, such as **Select assumptions**, **Select an experiment**, **Assign experiment** or **Complete tracker**. Act on a card in the app, or tell your AI tool what you chose. Either way, the card turns into a receipt (for example **Experiment approved**) with a timestamp.

    Use the box at the bottom to ask a question or describe a change. **Quick actions** offers the step that's ready now.
  </Step>

  <Step title="Check the Now tab">
    The right-hand panel opens on **Now**: the stage, owner and due date, the one step that's waiting (for example "Approve the experiment"), and what it's about: hypothesis, success criteria, key metrics. After the decision, **Now** shows the recorded Decision.
  </Step>

  <Step title="Open the Data tracker tab">
    Once a tracker exists, **Data tracker** previews its rows. **Open tracker** opens the full grid to add, paste or import rows. A completed tracker opens read-only.
  </Step>

  <Step title="Follow the Lineage">
    **Lineage** lists everything on the record for this question, in order: assumptions, hypothesis, experiment, data tracker, insights, Learning and Decision. Choose any entry to read it; **Explore full graph** shows how they connect.
  </Step>
</Steps>

<Figure src="/images/docs/app/workbench-lineage.webp" alt="Workbench with the thread of receipts on the left and the Lineage tab listing seven stages on the right" caption="Sample data" />

<InSwiftCNS>
  Stages shown in **Now**: **Exploring**, **Designing**, **Collecting evidence**, **Learning** and **Decided**. The header has **Activity** (what happened and when), **Share**, and **Export PDF**: a brief of the assumptions, hypothesis, experiment and measurement plan. The Learning and Decision aren't in it.
</InSwiftCNS>

What you get [#what-you-get]

One screen per question with the conversation, the next step and the full record together. Changes your AI tool makes over MCP appear here live; keep it open beside your tool.

Done when [#done-when]

* [ ] You can tell from **Now** what the next step is and who owns it.
* [ ] You can trace a Decision back to its assumption in **Lineage**.

Common mistakes [#common-mistakes]

* **Hunting for the next step in the thread.** **Now** always shows it.
* **Editing in two places at once.** If your AI tool is acting on a card, let it finish before clicking the same card.

<ForAgents>
  - `get_conversation_progress` mirrors **Now**: `currentStage`, `activeActionRequests`, `actionOperations` (tool to call, required scopes), `browserUrl`.
  - A card a tool can't complete has `browserRequired: true`; send the user to `browserUrl`.
</ForAgents>

Next [#next]

[Track experiments](/docs/use-the-app/track-experiments).