# By Dawn Docs

> Help for everyone who uses By Dawn, the agentic workspace that plans work, hands it to coding agents and ships it: product docs (Docs), the public API (Developers) and how to work well with agents (Learn). Every page below is Markdown; the same page as HTML is at the same path without `.md`.

## Docs

### Getting started

- [Start guide](https://docs.bydawn.com/start.md): Set up your first project, write your first ticket and watch an agent take it from a plan to a merged pull request.
- [Concepts](https://docs.bydawn.com/concepts.md): The handful of things By Dawn is made of, from organizations and projects to tickets, missions and agents, and how they fit together.
- [Download By Dawn](https://docs.bydawn.com/download.md): Install the By Dawn desktop app on macOS, Windows or Linux, keep it up to date, and install the agent on another machine.
- [Sign in](https://docs.bydawn.com/sign-in.md): Sign in to By Dawn with an email code, a passkey, GitHub, Google or your company's single sign-on, then choose, create or join an organization.
- [How By Dawn is organised](https://docs.bydawn.com/how-saw-is-organised.md): Organizations, projects, columns and tickets, how they fit together, and what that means for your code.
- [Words we use](https://docs.bydawn.com/glossary.md): The By Dawn words you'll meet in these docs and the API, each explained in a sentence or two.

### Intake

- [Tickets and sub-tickets](https://docs.bydawn.com/tickets.md): Create a ticket, read and change it in the ticket view, break it into sub-tickets, link it to other tickets, and follow its comments and activity.
- [Questions](https://docs.bydawn.com/questions.md): Ask how your project's code works, pick how technical the answer should be, keep and share the conversation, and turn it into a ticket.
- [Email intake](https://docs.bydawn.com/email-intake.md): Give a project a forwarding address, choose who may forward to it, and see how forwarded emails and their replies land on the board.
- [GitHub issues](https://docs.bydawn.com/github-issues.md): How By Dawn reads, opens and comments on GitHub issues in your repos, and how a ticket links to them.
- [Customers](https://docs.bydawn.com/customers.md): Keep a list of the companies you work for, record which of them asked for each ticket, and filter and sort the board by who's asking.
- [Customers settings and privacy](https://docs.bydawn.com/customers-settings.md): Turn Customers on, set up customer statuses, tiers and revenue, choose which requests never match a customer, and clear a requester's details for a data-subject request.

### Plan

- [Board and columns](https://docs.bydawn.com/board-and-columns.md): How a project's board works, what each column's role means, how cards move between columns, what a card shows, and how to search, filter and save views.
- [Epics and milestones](https://docs.bydawn.com/epics-and-milestones.md): Group a project's tickets into epics, split an epic into milestones, follow its progress, launch its tickets and mark it done.
- [Cycles](https://docs.bydawn.com/cycles.md): Turn on cycles for a project, plan tickets into them against your velocity, follow a cycle as it runs, and complete it.
- [Estimates](https://docs.bydawn.com/estimates.md): Choose a project's estimate scale, size tickets in points, and see how points add up in cycles, velocity and capacity.
- [Releases and the project changelog](https://docs.bydawn.com/releases.md): Group the tickets that ship together into a release, write its notes, check it's ready, ship it, publish it to GitHub, and keep the project's changelog.

### Agents & missions

- [Start a ticket](https://docs.bydawn.com/start-a-ticket.md): Hand a ticket to By Dawn's agent to plan, to build, or to plan and then build, and choose the steps its work is held to.
- [Missions and templates](https://docs.bydawn.com/missions.md): What a mission is, how its steps are checked, and how a team sets the step library, mission templates and defaults that every new ticket starts from.
- [Checkpoints and debriefs](https://docs.bydawn.com/mission-checkpoints.md): Answer By Dawn's agent when a mission step stops for you, from approving a plan to signing off a pull request, and read the debrief a finished mission leaves.
- [The agent browser](https://docs.bydawn.com/agent-browser.md): Watch the browser an agent uses on a ticket, take it over when it needs a hand, and review the screenshots it leaves behind.
- [Terminals](https://docs.bydawn.com/terminals.md): Open a terminal on your computer or a paired machine, answer a waiting agent from the board, and step into a ticket's own terminal.
- [Transcripts](https://docs.bydawn.com/transcripts.md): Decide whether By Dawn keeps a log of each agent session, for how long, and how you read a past run on a ticket.
- [Routines and schedules](https://docs.bydawn.com/routines-and-schedules.md): Run agent work on a timetable with routines, and set a one-off follow-up on a ticket that wakes its agent, reminds you or moves the card.
- [Models and runtimes](https://docs.bydawn.com/models-and-runtimes.md): Choose the machine, runtime, model and effort a ticket's agent runs with, and set the defaults for a project or the whole organization.
- [Remote agents and machines](https://docs.bydawn.com/remote-agents.md): Pair a Mac or Linux machine so it runs your tickets, choose whose work it takes, and keep it healthy from the Remote Agents settings.
- [The local agent](https://docs.bydawn.com/local-agent.md): Let the By Dawn desktop app run tickets on your own computer, check that its agent is healthy, and choose whose work it takes.
- [Claude accounts, sign-in and seats](https://docs.bydawn.com/claude-accounts.md): Sign your machines in to Claude from By Dawn, manage accounts across machines, require your company's Claude organization, and choose which seat may run a job.
- [Skills & Tools](https://docs.bydawn.com/skills-and-tools.md): Give every agent in your organization the same skills, subagents, slash commands and shared tools, and choose per project which ones its agents get.
- [Personas](https://docs.bydawn.com/personas.md): Describe the people your work affects, so an agent hears their objections to its plan before it builds anything.
- [Secrets](https://docs.bydawn.com/secrets.md): Give By Dawn's agents the API keys, tokens and credentials they need, encrypted so only your own machines can read them.

### Code & review

- [Repos](https://docs.bydawn.com/repos.md): Add the code repositories a project's tickets work in, check By Dawn can reach them, set their branches, and choose which repos each ticket works in.
- [Worktrees](https://docs.bydawn.com/worktrees.md): Where an agent does a ticket's work, how it carries over between runs and machines, and when By Dawn clears it to free disk space.
- [Changes and the code view](https://docs.bydawn.com/changes-and-code-view.md): Read what a worker changed on a ticket, browse and edit its code, and leave a line comment for the agent or the pull request.
- [Pull requests](https://docs.bydawn.com/pull-requests.md): Follow every pull request in a project, see which need you, review one inside By Dawn, and know what By Dawn does with a pull request from draft to merge.
- [Branching and CI](https://docs.bydawn.com/branching-and-ci.md): How By Dawn names ticket branches, where they start and open into, and how to make your CI build them.
- [Repo bootstrap](https://docs.bydawn.com/repo-bootstrap.md): Give a GitHub repo a default-branch ruleset, CODEOWNERS and README templates, Actions variables, and Actions and Dependabot secrets in one step.
- [Actions variables](https://docs.bydawn.com/actions-variables.md): Let a By Dawn agent create and update the GitHub Actions variables a repo's workflows read, on one repo or shared across your project's repos.

### Tests

- [Test results](https://docs.bydawn.com/tests.md): How By Dawn reads the test results your own CI and machines produce, the three ways to send them, and what the Tests panel, the worker and flaky-test handling do with them.
- [Results from the worker's runs](https://docs.bydawn.com/tests-worker-runs.md): What By Dawn records when a ticket's worker runs your tests at its Tests and build pass step, which runners it works with, and how to make sure yours does.
- [Pick up results from GitHub Actions](https://docs.bydawn.com/tests-github-artifacts.md): Let By Dawn read the test results and coverage your GitHub Actions workflows already upload as artifacts, including the last 30 days, with no CI change.
- [Set up your CI](https://docs.bydawn.com/tests-ci.md): Get test results into By Dawn from GitLab CI, Azure Pipelines, Jenkins, CircleCI and Buildkite, connect the CI systems that need a token, and get each pipeline ready for By Dawn to launch a suite on it.
- [Build your test library](https://docs.bydawn.com/test-library.md): Have By Dawn build a project's first test case library from what its repos already have — automated tests, CI jobs and QA files — review the proposal, and keep it in step on every merge.
- [Test cases](https://docs.bydawn.com/test-cases.md): Organise a project's test case library in By Dawn — folders, writing a case with its steps, history and restore, linking cases to tickets, automation coverage, and the case changes agents propose.
- [Run tests by hand](https://docs.bydawn.com/test-runs.md): Run a project's test cases by hand in By Dawn — start a manual run against a build, assign the cases, record each step from the keyboard, file a bug from a failure, retest, and close the run.
- [Exploratory sessions](https://docs.bydawn.com/test-sessions.md): Explore a feature without a script in By Dawn — set a charter and a timebox, log notes, issues and screenshots as you go, file bugs from them, and close with a debrief.
- [Move from Testmo or TestRail](https://docs.bydawn.com/tests-migrate.md): Bring your manual test cases from Testmo, TestRail or a spreadsheet into By Dawn's test case library, check the result with a dry run first, and import again safely.
- [Plan testing for a release or cycle](https://docs.bydawn.com/test-plans.md): Plan the testing that signs off a release or a cycle in By Dawn — have By Dawn draft the plan from linked cases, regression suites and last time's failures, edit it, start its runs and launches, and follow its progress and pass rate.
- [Launch test runs](https://docs.bydawn.com/tests-launch.md): Run a test suite on your own GitHub Actions from By Dawn — save the suite, allow its workflow, accept the inputs By Dawn sends, press Run tests, and follow the launch until its results are in.

### Insights

- [Insights](https://docs.bydawn.com/insights.md): See how work flows through By Dawn, how your agents are doing and what they cost, for one project or every project you can see.
- [Lenses and metrics](https://docs.bydawn.com/insights-metrics.md): What every number on every Insights lens counts, from Shipped and Cycle time to run outcomes, retries, review latency and estimated cost.

### Working in By Dawn

- [Inbox](https://docs.bydawn.com/inbox.md): See what needs you across your tickets, from an agent's question to a plan waiting for approval, and clear it.
- [Command palette and search](https://docs.bydawn.com/command-palette.md): Find any ticket, Docs page or Memory note with ⌘K, and search or filter the screen you're on from the top bar.
- [Keyboard shortcuts](https://docs.bydawn.com/keyboard-shortcuts.md): Every keyboard shortcut in By Dawn, from moving between screens to copying a ticket's ID, on the desktop and in the browser.
- [Notifications and preferences](https://docs.bydawn.com/notifications.md): Choose which alerts By Dawn sends you on the desktop, in the browser, in chat and by email, and set your theme and other preferences.
- [Docs](https://docs.bydawn.com/docs-wiki.md): Write and organise your team's pages in By Dawn, review the edits agents propose, and start pages from templates.

### Integrations

- [Chat integrations](https://docs.bydawn.com/chat.md): What By Dawn does in Slack, Discord and Microsoft Teams, who may do what from chat, and what By Dawn reads and keeps.
- [Connect your chat account](https://docs.bydawn.com/chat-accounts.md): Link your Slack, Discord or Teams account to By Dawn, choose what By Dawn may do as you from chat, and unlink it.
- [Bind a channel](https://docs.bydawn.com/chat-channels.md): Bind a Slack, Discord or Teams channel to a By Dawn project, choose who can file requests there, subscribe it to updates, and sync its threads with tickets.
- [Slack](https://docs.bydawn.com/chat-slack.md): Connect a Slack workspace to By Dawn, what the app asks Slack for and why, private channels, Slack Connect, the App Home, and disconnecting.
- [Discord](https://docs.bydawn.com/chat-discord.md): Add By Dawn to a Discord server, the permissions the bot asks for, what works in Discord today, and disconnecting.
- [Chat command reference](https://docs.bydawn.com/chat-commands.md): Every By Dawn command, shortcut, mention, reaction and button in Slack, Discord and Microsoft Teams, who can use each one, and what By Dawn answers.
- [Intercom](https://docs.bydawn.com/intercom.md): Connect an Intercom workspace to By Dawn, choose the projects it files into and what By Dawn posts back, what By Dawn stores and for how long, and disconnecting.
- [The By Dawn sidebar in Intercom](https://docs.bydawn.com/intercom-sidebar.md): File a customer's request as a By Dawn ticket from an Intercom conversation, link one you already have, see where that customer's requests stand, and what By Dawn posts back.
- [AI agents (MCP)](https://docs.bydawn.com/ai-agents.md): Let members connect their own AI agent, such as Claude Code, Claude Desktop, claude.ai or Cursor, to manage their team's tickets in By Dawn, and turn it on for your organization.

### Import & sync

- [Import and sync](https://docs.bydawn.com/import-and-sync.md): Bring your work into By Dawn from Jira, Linear, Azure DevOps, GitHub Issues, GitLab, Asana, Trello or a CSV/JSON export, once or kept in sync until a date you pick.
- [Import from Jira](https://docs.bydawn.com/import-jira.md): Connect a Jira Cloud site to By Dawn through By Dawn's Atlassian app, pick a project or a JQL query, and check how its statuses, priorities and epics map.
- [Import from Linear](https://docs.bydawn.com/import-linear.md): Connect Linear to By Dawn through By Dawn's Linear app, pick a team, and check how its workflow states, projects and cycles map.
- [Import from Azure DevOps Boards](https://docs.bydawn.com/import-azure-devops.md): Bring Azure DevOps work items into By Dawn through your organization's existing Azure DevOps connection, by project, area path or WIQL query.
- [Import from GitHub Issues](https://docs.bydawn.com/import-github-issues.md): Bring GitHub issues into By Dawn through your organization's GitHub App, from one or more repos, with milestones and sub-issues.
- [Import from GitLab](https://docs.bydawn.com/import-gitlab.md): Connect gitlab.com through By Dawn's GitLab app, or a self-managed GitLab through an OAuth application you add on it, pick a group or project, and check how its labels, epics and iterations map.
- [Import from Asana](https://docs.bydawn.com/import-asana.md): Connect Asana to By Dawn through By Dawn's Asana app, pick a project, and check how its sections, completed tasks and subtasks map.
- [Import from Trello](https://docs.bydawn.com/import-trello.md): Connect Trello to By Dawn through By Dawn's Trello Power-Up, pick a board, and check how its lists, checklists and members map.
- [Import from a CSV or JSON file](https://docs.bydawn.com/import-file.md): Import any tracker's CSV or JSON export into By Dawn, and get its columns recognised so titles, statuses, people and parents land in the right place.

### Administration

- [Organizations](https://docs.bydawn.com/organizations.md): What a By Dawn organization is, how to create one and switch between them, its General settings, and what owners, admins and members can each do.
- [Members and invites](https://docs.bydawn.com/members.md): Invite people to your By Dawn organization, accept an invitation, change someone's role, put them on projects, and remove them.
- [Teams](https://docs.bydawn.com/teams.md): Group people into teams that own work, attach them to the projects they work in, file and filter tickets by team, and see how By Dawn's teams compare with Linear's.
- [Project members and access](https://docs.bydawn.com/project-access.md): Decide who can open a By Dawn project, give people a project role and run access, and invite people from outside your organization.
- [Agent access](https://docs.bydawn.com/agent-access.md): Let agents from other projects read, write or start tickets in your By Dawn project, and choose what a project's own agents may do beyond their ticket.
- [Security](https://docs.bydawn.com/security.md): Choose how people may sign in to your By Dawn organization, require a passkey, decide how By Dawn staff access is approved, and keep or delete session transcripts.
- [API keys](https://docs.bydawn.com/api-keys.md): Create, look after and revoke your By Dawn organization's API keys, which let scripts and services use the board API.
- [Single sign-on](https://docs.bydawn.com/sso.md): How By Dawn signs your people in through your company's identity provider, what to set up first, and how a first sign-in works.
- [Verify a domain](https://docs.bydawn.com/sso-domains.md): Prove your organization owns an email domain with a DNS TXT record, so By Dawn can send its people to your single sign-on.
- [Okta](https://docs.bydawn.com/sso-okta.md): Connect By Dawn to Okta with OIDC (recommended) or SAML, so your people sign in to By Dawn with their Okta account.
- [Microsoft Entra ID](https://docs.bydawn.com/sso-entra-id.md): Connect By Dawn to Microsoft Entra ID (formerly Azure AD) with OIDC (recommended) or SAML, so your people sign in with their Microsoft work account.
- [Google Workspace](https://docs.bydawn.com/sso-google-workspace.md): Connect By Dawn to Google Workspace with OIDC (recommended) or SAML, so your people sign in with their Google work account.
- [Other identity providers](https://docs.bydawn.com/sso-generic-saml.md): Connect By Dawn to any SAML 2.0 identity provider, such as ADFS, PingFederate, OneLogin or JumpCloud, or to any OpenID Connect provider.
- [SCIM provisioning](https://docs.bydawn.com/scim.md): Let your identity provider add, update and remove the members of your By Dawn organization, and map its groups to By Dawn roles.
- [Plans and billing](https://docs.bydawn.com/billing.md): What By Dawn bills for today, which features depend on your organization's plan, and what the "not on your plan" cards mean.

## Developers

### Get started

- [Quickstart](https://docs.bydawn.com/developers/quickstart.md): Make your first By Dawn API call in about five minutes, in TypeScript, Python, Java, C#, Go or cURL.
- [Authentication](https://docs.bydawn.com/developers/authentication.md): How API keys and access tokens work together, what a key is allowed to do, and how to keep keys safe.
- [Connect an AI agent (MCP)](https://docs.bydawn.com/developers/mcp.md): Connect Claude Code, Claude Desktop, claude.ai, Cursor or any MCP client to By Dawn, so your agent can read and manage your team's tickets as you.

### Work with tickets

- [List and filter tickets](https://docs.bydawn.com/developers/recipes/list-tickets.md): Read every open ticket in a project, a page at a time, to report on a board or mirror it elsewhere.
- [Create a ticket](https://docs.bydawn.com/developers/recipes/create-ticket.md): Turn an alert, a form or an email into a ticket on the right board.
- [Update and move a ticket](https://docs.bydawn.com/developers/recipes/update-ticket.md): Change a ticket's title, priority, description and other fields, or move it to another column.
- [Comment on a ticket](https://docs.bydawn.com/developers/recipes/comments.md): Post updates on a ticket from another system, and read its discussion.
- [Organize work by team](https://docs.bydawn.com/developers/organize-work-by-team.md): Find the teams that work in a project and their names, file and move tickets by team, and list each team's work.
- [Group work into epics](https://docs.bydawn.com/developers/epics.md): List a project's epics, create one with a lead team, close it when it's done, and file tickets into it.

### Work with customers

- [Customers API](https://docs.bydawn.com/developers/customers.md): Keep By Dawn's customers in step with your CRM or support tool, and record which customer asked for which ticket.

### Send test results

- [Send test results from CI](https://docs.bydawn.com/developers/tests-submit.md): Add one step to any CI job so By Dawn records its test results and coverage as a test run, with saw-agent tests submit.
- [Make your test runner write reports](https://docs.bydawn.com/developers/test-reports.md): The flags that make Vitest, Jest, Bun, Playwright, pytest, Go, .NET, Java and Ruby write the test results and coverage files By Dawn reads.

### Build reliably

- [Responses and errors](https://docs.bydawn.com/developers/responses-and-errors.md): The one response shape every By Dawn API call uses, the error slugs to branch on, and when to retry.
- [Pagination and rate limits](https://docs.bydawn.com/developers/pagination-and-rate-limits.md): Read long lists a page at a time, and stay comfortably inside the API's rate limits.
- [Try it in your browser](https://docs.bydawn.com/developers/try-it.md): Make live API calls and run the recipes from this site with your own API key, and how the recipes are written.

### API reference

- [API changelog](https://docs.bydawn.com/changelog.md): Every change to the public By Dawn API, newest first.

## Learn

### Start here

- [Intro to By Dawn](https://docs.bydawn.com/learn/intro-to-saw.md): What By Dawn is for, and the loop every piece of work goes through, followed once from a one-line ticket to a merged pull request.
- [Coming from Linear or Jira](https://docs.bydawn.com/learn/coming-from-linear-or-jira.md): How Linear's and Jira's words map to By Dawn's, what works differently once agents do the building, and how to bring your team's work over.

### Working with agents

- [Writing tickets an agent can finish](https://docs.bydawn.com/learn/writing-tickets.md): What a ticket needs so an agent can finish it without guessing, a weak ticket rewritten, when to split one, and which mode to start it in.
- [Planning a feature as an epic](https://docs.bydawn.com/learn/planning-an-epic.md): Take a feature too big for one ticket from an idea to an epic of ordered tickets, let an agent propose the split, and launch it so the tickets start as their blockers finish.
- [Running a cycle with agents](https://docs.bydawn.com/learn/running-a-cycle.md): Plan a cycle around what you can review, start its tickets in one go, keep up with what needs you each day, and close it with unfinished work carried over.
- [Reviewing agent work](https://docs.bydawn.com/learn/reviewing-agent-work.md): What the mission has already proved when a ticket reaches Review, what only you can judge, how to read the evidence, and how to send work back with a note the agent can act on.

## API

- [By Dawn API index](https://docs.bydawn.com/llms-api.txt): the public API's own llms.txt, with one Markdown page per resource
- [By Dawn API, in full](https://docs.bydawn.com/llms-full.txt): every public operation in one file
- [OpenAPI document](https://docs.bydawn.com/openapi/public.openapi.yaml): the public API as OpenAPI