# Ysra Docs

> Documentation for Ysra, the autonomous software engineer: sessions, verification, autonomy policy, Knowledge, Workers and the HTTP API.

## Overview

- [Ysra documentation](https://docs.ysra.ai/index.md): Ysra plans, writes, runs and checks code in its own isolated workspace. Describe what you need, get back working code — with the evidence to trust it.

## Getting started

- [Introduction](https://docs.ysra.ai/getting-started/index.md): What Ysra is, where you use it, and the ideas the rest of the documentation builds on.
- [Quickstart](https://docs.ysra.ai/getting-started/quickstart.md): Sign in, connect a GitHub repository and run your first Ysra session — from the portal, the mobile app or the API.
- [A tour of Ysra](https://docs.ysra.ai/getting-started/tour.md): Where everything is in the Ysra portal — the sidebar, Build and Ask, sessions, the workspace pages — and the keyboard shortcuts that get you around.

## How it works

- [How Ysra works](https://docs.ysra.ai/concepts/how-ysra-works.md): Every job has the same shape — your outcome, your boundary, visible work, evidence, and your decision. Here is what happens inside each stage, and why you can trust the result.
- [Boundaries and safety](https://docs.ysra.ai/concepts/safety.md): The controls built into Ysra today — scope before action, isolated work, credential handling, exact-content approvals, budgets, recovery and audit — and where their limits are.

## Developer

- [Developer](https://docs.ysra.ai/developer/index.md): Ysra's autonomous software engineer — what it can start from, what a session is, how a session moves from goal to verified candidate, and what you can use it for.
- [Start a session](https://docs.ysra.ai/developer/start-a-session.md): Every control in the Build composer — repository, branch, mode, quality, budget, attachments and review options — and how to write a brief Ysra can hold itself to.
- [The workroom](https://docs.ysra.ai/developer/workroom.md): The session workroom — the conversation, the live canvas, and the Mission, Editor, Plan, Review, Checks, Shell and Audit panels — and how to read each one.
- [Steering and checkpoints](https://docs.ysra.ai/developer/steering.md): How to redirect a running session, answer its questions, pause, resume, cancel, extend the budget, change permissions, ask about its evidence, and rewind to an exact earlier version.
- [Plans and acceptance criteria](https://docs.ysra.ai/developer/plans.md): How Ysra turns a brief into a scope, acceptance criteria and a plan — what each one controls, what can and can't change it, and how progress is measured.
- [Review and verification](https://docs.ysra.ai/developer/review.md): How a candidate is judged — your repository's own checks, independent criterion-by-criterion review, a panel of specialist reviewers, browser proof, a clean-build check and a security floor — and how to read every verdict.
- [Previews](https://docs.ysra.ai/developer/previews.md): Run the exact candidate in its own environment and click through it before anything is merged — how previews start, what they include, how sign-in works, and when they expire.
- [Delivery and deployment](https://docs.ysra.ai/developer/delivery.md): What happens to a finished candidate — keep it, commit it, push a branch or open a pull request — and how going live on your hosting works as its own authorised step.
- [Reports and sharing](https://docs.ysra.ai/developer/reports.md): The build report — one receipt for one candidate — what's in it, how to share it safely with people outside your workspace, and the audit record behind it.
- [Projects](https://docs.ysra.ai/developer/projects.md): For work too big for one session — an approved architecture, milestones and a task graph, run as sessions and integrated into one final candidate, with you approving each decision.
- [Rules and instructions](https://docs.ysra.ai/developer/rules.md): Standing instructions every session reads before it touches code — conventions, preferences, the things you'd tell a new engineer on day one — with triggers, versions and a record of which task used which rule.
- [Playbooks](https://docs.ysra.ai/developer/playbooks.md): Repeatable briefs for common engineering jobs. Running one opens the Build composer with the brief filled in, ready to adjust and send.

## Knowledge

- [Knowledge](https://docs.ysra.ai/knowledge/index.md): Ysra's grounded assistant — ask about your own work, choose which sources it may use, get answers with a citation for every claim, and turn an answer into action.
- [Sources and citations](https://docs.ysra.ai/knowledge/sources.md): What Knowledge can read — workspace files, attachments, Slack, Jira, Gmail and the public web — how each source is kept private and permission-checked, and how citations work.
- [Experts](https://docs.ysra.ai/knowledge/experts.md): Knowledge coworkers you configure — a purpose, instructions, default sources, allowed capabilities and suggested questions — shared with colleagues and versioned so past answers stay explainable.
- [Memory](https://docs.ysra.ai/knowledge/memory.md): Long-term memory — the facts and preferences you want Ysra to carry across Knowledge conversations. Explicit, visible, scoped to an expert if you like, and deletable at any time.
- [Actions and approvals](https://docs.ysra.ai/knowledge/actions.md): How Knowledge proposes Slack messages and Jira changes, and why nothing runs until you approve the exact content — edit it, approve it, or reject it.
- [Sharing a conversation](https://docs.ysra.ai/knowledge/sharing.md): Share a Knowledge conversation as a frozen, read-only link — what the recipient sees, what is left out, how expiry works and how to revoke it.

## Workers

- [Workers](https://docs.ysra.ai/workers/index.md): Workers run on their own — on a schedule or when you ask — read what they're allowed to, do the job, and stop for your approval before anything leaves your account.
- [Create a worker](https://docs.ysra.ai/workers/create.md): Describe a worker in plain language and let Ysra draft it, then review its kind, grants, sources, credentials, approval rules and schedule before activating.
- [Schedules and triggers](https://docs.ysra.ai/workers/schedules.md): Run a worker manually, on a cron schedule in your time zone, or at a fixed interval — and how scheduled runs are made exactly once.
- [Runs and approvals](https://docs.ysra.ai/workers/runs.md): What happens during a worker run, every run state, cancellation and retries, and how approvals bind to the exact content of an email or Slack post.
- [Worker types](https://docs.ysra.ai/workers/types.md): General, research, mail and uptime workers in detail — what each can do, what it needs, and its safety limits.

## Integrations

- [Integrations](https://docs.ysra.ai/integrations/index.md): What Ysra connects to today — GitHub, Slack, Jira and Gmail — what each connection is used for, how syncing works, and what is planned but not available yet.
- [GitHub](https://docs.ysra.ai/integrations/github.md): Install the Ysra GitHub App to give Developer access to the repositories you choose — what it can do, which permissions it asks for, and how to change or revoke access.
- [Slack](https://docs.ysra.ai/integrations/slack.md): Connect Slack to give Knowledge and workers your channels as context, let them propose messages for approval, and start and steer Developer sessions from a Slack thread.
- [Jira](https://docs.ysra.ai/integrations/jira.md): Connect a Jira Cloud site to use issues as Knowledge context and let Ysra propose issue creation, updates, comments and transitions for your approval.
- [Gmail](https://docs.ysra.ai/integrations/gmail.md): Connect a Gmail mailbox as private, read-only Knowledge context for one workspace — and how mail workers use a separate connection to draft and send with approval.

## Workspace & account

- [Workspaces and files](https://docs.ysra.ai/workspace/index.md): Workspaces are where sessions, files, experts, workers and connections live together. How to create and manage them, and how workspace files are uploaded, indexed, searched and attached.
- [Wallet and usage](https://docs.ysra.ai/workspace/wallet.md): Your account wallet — available budget, reservations and spend — how session budgets draw on it, how to add credit or set a budget, and where to see what every session cost.
- [Autonomy policy](https://docs.ysra.ai/workspace/autonomy-policy.md): The twelve settings that bound what Ysra may do without asking, how account and repository policies combine, and why a running session keeps its snapshot.
- [Account settings](https://docs.ysra.ai/workspace/settings.md): Agent behaviour, verification, your account policy, provider connections, members and invitations — and the personal settings in the mobile app.

## Mobile app

- [Mobile app](https://docs.ysra.ai/mobile/index.md): The Ysra app for iOS and Android — start work in one sentence, follow it as a conversation, answer what needs you, review the output and ship it, from your phone.
- [Sessions on your phone](https://docs.ysra.ai/mobile/sessions.md): How a session reads on the phone — the conversation, grouped machine work, the output bar, previews, changes, reports and budget decisions.

## Guides

- [Walkthrough: a full-stack store](https://docs.ysra.ai/guides/walkthrough.md): One real Ysra session — a Moroccan lifestyle store with a customer storefront and a Medusa back office, built from one brief. What was asked, what was built, what it cost, and how the session reported its own result.
- [Change an existing repository](https://docs.ysra.ai/guides/existing-repository.md): A complete walkthrough — from a goal on an existing codebase to a draft pull request you can merge with confidence.
- [Triage a production bug](https://docs.ysra.ai/guides/production-bug.md): From a customer report to a proven fix — reproduce first, find the cause, fix it narrowly with a regression test, prove it in a browser, and deliver a draft pull request.
- [A weekday incident brief](https://docs.ysra.ai/guides/incident-brief.md): Set up a worker that reads your incident channel and Jira project every weekday morning, summarises what changed, and prepares a Slack update that waits for your approval.

## API reference

- [API overview](https://docs.ysra.ai/api/index.md): Base URL, authentication, the capability matrix and the conventions every Ysra API client should follow — decimal money, idempotency keys and optimistic versions.
- [Authentication](https://docs.ysra.ai/api/authentication.md): Exchange an email and password for a bearer token, and use it on every request to the Ysra API.
- [Errors](https://docs.ysra.ai/api/errors.md): The status codes the Ysra API returns and exactly what a well-behaved client should do about each one.

## API reference › Account

- [Wallet](https://docs.ysra.ai/api/account/wallet.md): Read the account wallet, set its budget, add credit and page through the ledger. Every amount is a decimal string.
- [Autonomy policy endpoints](https://docs.ysra.ai/api/account/policy.md): Read and write the account autonomy policy and per-repository overrides, with optimistic version checks.

## Resources

- [Troubleshooting](https://docs.ysra.ai/resources/troubleshooting.md): What to do when a session stops, a check fails for reasons unrelated to your change, a preview won't start, or the API refuses a request.
- [Glossary](https://docs.ysra.ai/resources/glossary.md): Every Ysra term in one place — from acceptance criteria to workers — with a link to where it's explained in full.
- [Changelog](https://docs.ysra.ai/resources/changelog.md): What changed in each Ysra release. Ysra follows semantic versioning; the API reports its exact build commit too.

## Contributing

- [Writing docs](https://docs.ysra.ai/contributing/index.md): How to add a page, put it in the navigation, preview it locally and get it through the build checks.
- [Components](https://docs.ysra.ai/contributing/components.md): Every documentation primitive available to authors — callouts, tabs, code, diagrams, cards, steps, badges and API reference blocks — with the Markdown that produces it.