> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwiflow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted quickstart

> Publish the Development workflow, prepare a run, and follow its real human decisions and check reports.

Use this guide to create and follow a run in the hosted Kiwi app. Keep implementation in the tools you already use: Kiwi records work that people, agents, and CI explicitly report. To connect an agent environment using details from the signed-in app, start with [Set up your agent](https://docs.kiwiflow.io/ai-quickstart.md).

**1. Get started and choose a setup path**

From the public Kiwi site, choose **Get started**. Signed-out visitors continue through Clerk's hosted signup and return to `/app/get-started`; signed-in visitors go straight to that choice. Choose **Set up with an agent** to reveal a prompt for connecting your existing developer workspace, or **Continue manually** to open the project setup at `/app`. The public **Sign in** link continues to open the existing app path for returning users.

On first use, Kiwi initializes an organization using your profile name or email and a project named **My first project**. It does not publish a workflow automatically. After you paste and run the prompt and complete OAuth sign-in in the agent client, it asks the agent to verify the current organization, exact project, role, and published workflows through actual MCP responses, then update relevant existing workspace guidance. Any suitable published workflow, including a custom workflow, is valid. If a successful `list_workflows` response contains no published workflow, the prompt proposes one and gives an eligible Admin the project Workflows page to review and publish it; a failed read is a blocker, not an empty list. Organization invitations alone do not grant access to every project.

**2. Publish a workflow**

Open **Workflows** in the project. Publish the bundled [Development workflow definition](https://docs.kiwiflow.io/examples/development.v1.json) or import a valid definition. Kiwi validates the ordered chain and assigns a new immutable published revision. See [Workflows and gates](https://docs.kiwiflow.io/workflows.md) before changing the template.

**3. Prepare a run and its people**

In **Runs**, start a run with a request description or reference and choose the published workflow. Set the responsible person, designated owner, and designated reviewer. The responsible person receives reserved human handoffs; the owner decides Plan; the reviewer decides Human acceptance.

**4. Submit the Plan outputs**

For a bounded example, track a change in your own application that improves help-center search when a query has no matches. The Plan performer reports scope, acceptance\_criteria, and at least one required\_checks entry. Root output names are snake\_case; fields inside a check definition are camelCase. Replace the reporter placeholder with an actual eligible project user ID; a placeholder never grants authority.

```json theme={null}
{
  "scope": "Improve the help center's search results when a query has no matches.",
  "acceptance_criteria": [
    "A query with no matching help articles explains that no results were found and offers a way to revise the search.",
    "Queries with matching articles continue to show the matching results."
  ],
  "required_checks": [
    {
      "id": "help-search-results",
      "name": "Help search results QA",
      "expectedResult": "When a query has no matches, the help center explains that no results were found and offers a way to revise the search; matching results continue to display.",
      "permittedOrigins": ["human_attested"],
      "authorizedReporterIds": ["user_REPLACE_WITH_CURRENT_ELIGIBLE_PROJECT_USER_ID"]
    }
  ]
}
```

The designated owner must accept the submitted Plan in the app. A submitted output or tool receipt is not the decision. If a checker will report this check, use checker\_reported, the actual nonsecret checker reporterId, and allow the same check ID on that credential. See [CI reporting](https://docs.kiwiflow.io/ci-reporting.md).

**5. Report implementation and verification**

Implement in your existing tools and report the exact candidate reference, summary, and handoff notes. A human QA reporter or assigned checker then reports each required check against that candidate. A check must pass; fail, blocked, or not-applicable does not satisfy the gate.

**6. Complete review, acceptance, and handoff**

A distinct reviewer performer and session reviews the same candidate. The designated reviewer submits a Human acceptance decision in the app. Complete Handoff by recording the actual delivery reference, summary, and remaining limitations. The run completes only when the workflow records all required accepted steps.

## Confirm the current state

Open the run to see its current step, attempts, check evidence, actor provenance, and available actions. The run's nextActions are permission- and state-specific. A receipt confirms one command was recorded; it does not mean the whole run or current gate passed.

If a mutation's response is lost and its outcome is unknown, retry the same command with the same command ID and identical body. For a definitive stale-version or stale-attempt response, refresh the run and create a new command ID. See [Runs and history](https://docs.kiwiflow.io/runs-and-history.md) and [Retries and recovery](https://docs.kiwiflow.io/retries-and-recovery.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.