# Words we use > The By Dawn words you'll meet in these docs and the API, each explained in a sentence or two. These docs use a few words that mean something particular in By Dawn. Here they are in plain terms, with a link to where each one is explained in full. ## By Dawn and its board ### By Dawn The product these docs are about, and its public name. The app itself still says SAW in a few places until it is renamed: its window and menu, some buttons and messages, the `saw` command line, `saw-agent`, ticket ids such as `SAW-123`, and the `sawrun.com` addresses. They are the same product. Where a page quotes the app, it quotes it exactly, SAW included. ### Organization Your company or team in By Dawn. Everything belongs to one, and every API path starts with `/orgs/{orgId}`. See [How By Dawn is organised](https://docs.bydawn.com/how-saw-is-organised/). ### Project One board of work, with its own columns and its own ticket prefix (`SAW` in `SAW-123`). ### Status (column) A column on a project's board. The API calls columns statuses, so a ticket's `statusId` says which column it's in. See [Board and columns](https://docs.bydawn.com/board-and-columns/). ### Role A tag By Dawn puts on the few columns its workflow depends on: `backlog`, `todo`, `building`, `review` and `completed`. Teams rename columns, but the role stays, so look columns up by role. See [Projects and their boards](https://docs.bydawn.com/how-saw-is-organised/#projects-and-their-boards). ### Ticket One piece of work on a board. It sits in exactly one column. See [Tickets and sub-tickets](https://docs.bydawn.com/tickets/). ### `id` and identifier A ticket's two names. The `id` (`ticket-…`) is for your code and every API path. The identifier (`SAW-123`) is for people. ### Sub-ticket A ticket with a parent (`parentTicketId`), used to break work down. It shows as `SAW-123.1`. See [Break work into sub-tickets](https://docs.bydawn.com/tickets/#break-work-into-sub-tickets). ### Cycle A project's time-boxed iteration, like a sprint. See [Cycles](https://docs.bydawn.com/cycles/). ### Epic and milestone An epic groups the tickets of one deliverable, such as a feature. A milestone is an optional phase of one epic, with its own target date. See [Epics and milestones](https://docs.bydawn.com/epics-and-milestones/). ### Estimate A ticket's size in points, on the project's scale. Cycles add estimates up to measure velocity and capacity. See [Estimates](https://docs.bydawn.com/estimates/). ### Release The tickets that ship together, with their notes. Shipping a release adds it to the project's changelog. See [Releases and the project changelog](https://docs.bydawn.com/releases/). ### Agent run By Dawn's AI agent working on a ticket. Moving a ticket into the `building` column starts one, which is why an API key isn't allowed to make that move. ## Missions ### Mission The list of steps a ticket goes through while By Dawn's agent works on it, such as a plan a person approves, tests that pass and By Dawn merging the pull request. A team can turn missions off. See [Missions and templates](https://docs.bydawn.com/missions/). ### Mission step One item in a mission. By Dawn checks some steps itself, a person decides others, and By Dawn carries out a few on its own after the agent finishes. A ticket held at a step names it in `heldAt`. ### Phase A stage of a mission, such as Plan, Build or Ship. Steps run phase by phase, in order. ### Mission template A named list of ticked steps, written by a person, that a ticket's mission starts from. Each mode (planning or build) can have one default template, and a project's default beats the organization's. See [Templates and defaults](https://docs.bydawn.com/missions/#templates-and-defaults). ### Preset A ready-made way to tick a mission's steps: **Auto**, **Quick**, **Standard** or **Thorough**. Unlike a template, By Dawn works out a preset's ticks for each ticket. See [Choose the steps](https://docs.bydawn.com/start-a-ticket/#choose-the-steps). ### Checkpoint A mission step that waits for a person, such as approving a plan or picking a mockup. The agent stops until someone answers. See [Checkpoints and debriefs](https://docs.bydawn.com/mission-checkpoints/). ### Debrief What a finished mission leaves on its ticket: the steps it ran, the decisions people made and the proof for each step. See [The debrief](https://docs.bydawn.com/mission-checkpoints/#the-debrief). ## Agents and their setup ### Worker The app's name for By Dawn's agent while it works on a ticket. See [Start a ticket](https://docs.bydawn.com/start-a-ticket/). ### Run config The machine, runtime, model and effort a ticket's agent runs with. A ticket follows its project's run defaults unless someone changes it. See [Models and runtimes](https://docs.bydawn.com/models-and-runtimes/). ### Remote agent A machine paired with your organization that runs By Dawn's agent and picks up tickets. See [Remote agents and machines](https://docs.bydawn.com/remote-agents/). ### Seat One Claude sign-in on a machine. Each machine has a default seat and can hold more, each signed in to another Claude account. See [Claude accounts, sign-in and seats](https://docs.bydawn.com/claude-accounts/). ### Library The organization's skills, subagents, slash commands and shared tools, which every agent picks up when it starts. A project can switch items off for itself. See [Skills & Tools](https://docs.bydawn.com/skills-and-tools/). ### Persona A stakeholder the organization describes once, such as a compliance lead, who critiques an agent's plan in character. See [Personas](https://docs.bydawn.com/personas/). ### Secret A named value, such as an API key, that agents read as an environment variable. It's encrypted for your own machines, so nobody can view it once it's saved. See [Secrets](https://docs.bydawn.com/secrets/). ### Routine Work an agent runs on a timetable, each run as a new ticket. See [Routines](https://docs.bydawn.com/routines-and-schedules/#routines). ## Code and review ### Repo A git repository a project's tickets work in, on GitHub, Azure DevOps or another host. A project can have many, and a ticket can work in several. See [Repos](https://docs.bydawn.com/repos/). ### Worktree A ticket's own checkout of one repo, on the machine running its agent, on the ticket's branch. Every ticket gets one per repo, so agents never touch each other's files. See [Worktrees](https://docs.bydawn.com/worktrees/). ### Pull request The way a ticket's code reaches a repo: one per repo the ticket changes, opened from the ticket's branch. By Dawn opens it as a draft and watches its checks and reviews. See [Pull requests](https://docs.bydawn.com/pull-requests/). ### Line comment A comment on particular lines of a ticket's diff, sent to its agent, posted on its pull request, or both. See [Comment on a line](https://docs.bydawn.com/changes-and-code-view/#comment-on-a-line). ### Test run One set of test results By Dawn read from the reports a test runner wrote: a worker's **Tests and build pass** step, a CI pipeline run (all its jobs and shards together), or an uploaded file. It's tied to a commit, and through its branch to a pull request and ticket. By Dawn never runs the tests itself. See [Test results](https://docs.bydawn.com/tests/). A run people work through by hand is a [manual run](#manual-run). ### Test case One thing to test, in a project's case library: a title, preconditions and steps with what to expect, or an automated test in a repo, which By Dawn adds by itself. Every edit is a revision. See [Test cases](https://docs.bydawn.com/test-cases/). ### Manual run A set of test cases people work through by hand against one build, recording each step's result. By Dawn records what they did, and files a bug from a failure in one step. See [Run tests by hand](https://docs.bydawn.com/test-runs/). ### Exploratory session One person exploring a charter without a script, within a timebox, logging notes, issues and screenshots as they go. See [Exploratory sessions](https://docs.bydawn.com/test-sessions/). ### Test plan The testing that signs off one release or one cycle: suites launched on your own CI or machines, and cases people run by hand, each an item of the plan. By Dawn drafts it from the cases linked to the work, the regression suites and what failed last time, and you edit it. See [Plan testing for a release or cycle](https://docs.bydawn.com/test-plans/). ### Regression suite A suite marked **Regression suite**, so By Dawn drafts it into every release's and cycle's test plan. See [Mark your regression suites](https://docs.bydawn.com/test-plans/#mark-your-regression-suites). ### Test gate A project setting, off by default, that keeps a release from shipping until its test plan passes or a person signs off what's keeping it from passing. **Ship anyway** doesn't get past it. See [The test gate](https://docs.bydawn.com/test-plans/#the-test-gate). ### Flaky test A test that passed and failed on the same commit, or failed and then passed on a retry. By Dawn files one **Flaky:** ticket for it, and can re-run CI instead of waking the worker when only known-flaky tests failed. See [Flaky tests](https://docs.bydawn.com/tests/#flaky-tests). ## Insights ### Lens One Insights dashboard, looking at your work from one angle: Overview, Flow, Agents, People, Cost or Questions. See [Insights](https://docs.bydawn.com/insights/#the-lenses). ### Cycle time How long a ticket took from starting work to its first review. Insights gives the median, never the average. See [Lenses and metrics](https://docs.bydawn.com/insights-metrics/#overview). ## Import and sync ### Connection One import from another tracker, such as Jira or Trello, into one project. It holds the app grant, what to bring, the mapping and, for a sync, the end date. See [Import and sync](https://docs.bydawn.com/import-and-sync/). ### App grant The approval an org admin gives on a tracker's consent screen for By Dawn's app to read and write there. It's how every tracker connects, so there's no token to paste. By Dawn keeps the grant for one connection, and gives it up when the connection ends. See [Before you start](https://docs.bydawn.com/import-and-sync/#before-you-start). ### Sync window The period, up to 180 days, during which an imported project and its tracker keep each other up to date. When it ends, the tickets stay and stop updating. See [Ending a sync](https://docs.bydawn.com/import-and-sync/#ending-a-sync). ### Field owner The side, By Dawn or the tracker, whose value wins when a synced field was changed on both sides at once. The value that lost shows on the ticket as a sync conflict. See [When both sides change the same field](https://docs.bydawn.com/import-and-sync/#when-both-sides-change-the-same-field). ## Chat integrations ### Chat connection One Slack workspace, Discord server or Microsoft 365 tenant that an org admin added to By Dawn. Disconnecting it deletes everything By Dawn kept for it. See [Chat integrations](https://docs.bydawn.com/chat/#how-it-fits-together). ### Channel binding A chat channel tied to one project by a project admin. It says where the channel's requests go, who may file them and which updates post there. See [Bind a channel](https://docs.bydawn.com/chat-channels/). ### Linked chat account A member's chat identity, tied to their By Dawn account, with the scopes they chose. A button they click in chat then acts as them. See [Connect your chat account](https://docs.bydawn.com/chat-accounts/). ### Request A ticket filed from chat by someone who isn't acting as a linked member, such as a guest or someone from another organisation. It records their chat name and id, and never makes them a member. See [Who files what](https://docs.bydawn.com/chat-channels/#who-files-what). ## Administration ### Owner, admin and member The three roles someone can have in an organization. Admins manage people and most settings, and owners also decide how people sign in. See [Roles](https://docs.bydawn.com/organizations/#roles). ### Team A named group of people in an organization who own work together. A ticket can have one owning team, its `teamId`, and a team works in the projects it's attached to. A team can also be given access to a project or a Docs space. See [Teams](https://docs.bydawn.com/teams/), and [Organize work by team](https://docs.bydawn.com/developers/organize-work-by-team/) for the API. ### Restricted project A project only its own members, and the organization's owners and admins, can open. Other projects are open to everyone in the organization. See [Open or restricted](https://docs.bydawn.com/project-access/#open-or-restricted). ### Identity provider (IdP) The service that holds your company's accounts and checks passwords, such as Okta, Microsoft Entra ID or Google Workspace. See [Single sign-on](https://docs.bydawn.com/sso/). ### Verified domain An email domain, such as `acme.com`, that your organization has proved it owns with a DNS record. Single sign-on and SCIM only reach people at one. See [Verify a domain](https://docs.bydawn.com/sso-domains/). ### SSO connection The link between your organization and your identity provider, over OIDC or SAML, that lets people sign in through it. See [Add a connection](https://docs.bydawn.com/sso/#add-a-connection). ### SCIM The standard way an identity provider adds and removes an app's users for you. See [SCIM provisioning](https://docs.bydawn.com/scim/). ## Keys and tokens ### API key A long-lived secret (`saw_live_…`) that an owner or admin creates in **Settings › Organization › Security** ([API keys](https://docs.bydawn.com/api-keys/)). It belongs to one organization and lives on your server. See [Authentication](https://docs.bydawn.com/developers/authentication/). ### Access token A short-lived token (about 15 minutes) your code gets by exchanging the key, and sends with every request as `Authorization: Bearer …`. ### Scope What a key may do: read only (`tickets:read`), read and write (`tickets:write` as well), or only send test results (`tests:write`). See [Scopes](https://docs.bydawn.com/developers/authentication/#scopes). ## Responses ### Envelope The shape every response has: `{ "ok": true, "data": … }` when it worked, or `{ "ok": false, "error": "" }` when it didn't. See [Responses and errors](https://docs.bydawn.com/developers/responses-and-errors/). ### Slug The short, fixed error code in `error`, such as `ticket_not_found`. Write your error handling against it. ### Cursor A bookmark for the next page of a list (`nextCursor`). Pass it back as it is. See [Pagination](https://docs.bydawn.com/developers/pagination-and-rate-limits/#pagination). ### Correlation ID The `X-Correlation-Id` header on every response. Quote it if you ask us about a call. ## On this site ### Recipe A complete program, in one file, that does one job with the API, written in TypeScript, Python, Java, C#, Go and cURL. Our CI runs every one of them against the live API. See [How the recipes are written](https://docs.bydawn.com/developers/try-it/#how-the-recipes-are-written). ### Try it The console and the **Run** buttons that call the API from this site with your own key. See [Try it in your browser](https://docs.bydawn.com/developers/try-it/). Source: https://docs.bydawn.com/glossary/