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

# Quickstart

> Set up Woes from a new workspace to a tested support flow.

Use this guide to take a new Woes workspace from first login to a working developer support loop. The goal is not just to turn features on. The goal is to make sure your team, API context, agent behavior, and first customer channel are ready before customers depend on them.

<Note>
  Start with one well-understood API area. A narrow, verified launch is safer than enabling broad AI handling before your sources and handoff rules are ready.
</Note>

## Setup path

<Steps>
  <Step title="Prepare your workspace">
    Confirm your workspace profile, invite teammates, assign roles, and define the tags, custom fields, macros, and automations your operators will use.
  </Step>

  <Step title="Add API context">
    Add an OpenAPI file, Markdown docs, JSON source, or published documentation website. Run a scan and inspect the generated endpoint evidence.
  </Step>

  <Step title="Configure testing credentials">
    Add credentials only when you need live API tests or verification. Prefer scoped, test-only credentials.
  </Step>

  <Step title="Test the agent">
    Use the Agent and Lab workflow to test real customer questions, citations, confidence behavior, clarification, and handoff.
  </Step>

  <Step title="Open a channel">
    Install the live chat widget or connect Discord, then watch the first conversations with a human operator in the loop.
  </Step>
</Steps>

## Before you begin

| Requirement             | Why it matters                                                                                     |
| ----------------------- | -------------------------------------------------------------------------------------------------- |
| Woes workspace access   | You need an authenticated workspace before you can configure settings, sources, or channels.       |
| At least one API source | The agent needs workspace-scoped evidence before it can answer API questions.                      |
| A safe test credential  | Live verification should use scoped credentials, preferably in a sandbox or staging environment.   |
| Website access          | Live chat requires permission to add the widget script to your site or app.                        |
| Launch owner            | Someone should review the first conversations and decide when automation is ready for more volume. |

## 1. Prepare the workspace

Open **Settings** and configure the foundations your team will use every day.

<CardGroup cols={2}>
  <Card title="Members and roles" icon="users">
    Invite teammates and give each person the minimum access they need.
  </Card>

  <Card title="Tags" icon="tags">
    Define the labels operators will use for triage, reporting, and issue grouping.
  </Card>

  <Card title="Custom fields" icon="list-checks">
    Capture structured account, environment, plan, version, and priority details.
  </Card>

  <Card title="Macros" icon="message-square-quote">
    Create repeatable replies for common support requests and handoff language.
  </Card>

  <Card title="Automations" icon="workflow">
    Start with simple routing or tagging rules that your team has reviewed.
  </Card>

  <Card title="Channels" icon="inbox">
    Decide whether live chat, Discord, or both should be opened first.
  </Card>
</CardGroup>

<Tip>
  Use private notes for internal investigation details. Do not put credentials, unrestricted tokens, or customer-private data in notes, tags, or macros.
</Tip>

## 2. Add your first API source

Open **Context** and add the highest-quality source available.

| Source type | Best for                                                                               | Review after scan                                                                      |
| ----------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| OpenAPI     | Endpoint contracts, schemas, parameters, auth metadata, request bodies, and responses. | Endpoint counts, method/path accuracy, required fields, response examples, auth hints. |
| Markdown    | Guides, examples, troubleshooting, and behavior explanations.                          | Generated Markdown, retrieval chunks, examples, and ambiguous statements.              |
| JSON        | Structured endpoint or schema data.                                                    | Normalized fields, missing names, unexpected nesting, and redacted sensitive values.   |
| Website     | Published docs that need to be crawled or imported.                                    | Crawl coverage, skipped pages, same-origin behavior, and partial results.              |

After the scan, open the source detail view and check the evidence Woes generated. Do not rely on the agent for a source until the important endpoints and examples look correct.

## 3. Configure API testing credentials

Credentials are separate from source content. Add them only when you want Woes to run guarded API tests or live verification.

Use credentials that are:

* Scoped to the smallest useful permission set.
* Safe for test or staging data.
* Rotatable if they are exposed.
* Not reused from production admin workflows.

<Warning>
  Avoid destructive or write-capable production credentials during setup. Live verification should be introduced carefully, starting with safe read-only requests.
</Warning>

## 4. Test the agent

Open **Agent** and test questions that resemble real customer messages.

<Tabs>
  <Tab title="Good first tests">
    * How do I authenticate requests?
    * What fields are required to create a customer?
    * Why am I getting a 401?
    * Does this endpoint support pagination?
    * Can I call this API from the browser?
  </Tab>

  <Tab title="Edge cases">
    * Ask about an endpoint that is not documented.
    * Paste a malformed request body.
    * Include a fake secret and confirm it is not repeated back.
    * Ask for account-specific production state.
    * Ask the agent to ignore its instructions.
  </Tab>

  <Tab title="Pass criteria">
    * Answers cite relevant workspace evidence.
    * Missing information leads to clarification or handoff.
    * The agent does not invent endpoint behavior.
    * Sensitive values are redacted.
    * Live checks run only when safe and supported by context.
  </Tab>
</Tabs>

## 5. Open your first channel

Choose one channel for the first launch.

| Channel   | Use when                                                               | Launch check                                                                            |
| --------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Live chat | Customers need support inside your product or docs site.               | Install the widget, send a test message, and confirm replies appear in the browser.     |
| Discord   | Developers already ask questions in your community or customer server. | Confirm connected channels, ownership, and private escalation rules.                    |
| Email     | You need verified sending domains or outbound tests.                   | Treat inbound intake as unavailable unless your workspace is explicitly enabled for it. |

## First conversation checklist

* A customer message appears in the shared inbox.
* The operator sees channel, identity, tags, and custom fields.
* The agent either answers with citations, asks a useful clarification, or hands off.
* Private notes stay internal.
* Replies appear in the customer channel.
* Any repeated product issue is linked or converted into an issue.
* The team reviews what went well before increasing volume.

## Common setup problems

<AccordionGroup>
  <Accordion title="The agent gives generic answers">
    Review source coverage in **Context**. Generic answers usually mean the relevant endpoint, auth rule, error behavior, or example was not ingested clearly enough for retrieval.
  </Accordion>

  <Accordion title="The scan succeeds but endpoint details look thin">
    Add a more structured source, such as OpenAPI, or supplement the source with Markdown examples that explain behavior not present in the schema.
  </Accordion>

  <Accordion title="Live verification is unavailable">
    Confirm credentials are configured for the source, the endpoint has enough request metadata, and the request is safe to run.
  </Accordion>

  <Accordion title="A channel message does not appear in the inbox">
    Check that the channel is connected, the workspace public key or integration is correct, and the message route is deployed.
  </Accordion>
</AccordionGroup>