# knotless documentation

## Guides

How to do things with knotless, a task at a time.

- [Getting started](guide/getting-started.md): install, log in, push,
  clone, commit without a checkout, show who you are.
- [Collaborating](guide/collaborating.md): write access, protected
  branches, forks, pulls, reviews, merging, issues, moderation.
- [Private repositories](guide/private.md): create, share and browse them.
- [Agents](guide/agents.md): connect an MCP client, locally or over HTTP.
- [Review agents](guide/reviews.md): a bot account that reviews your
  pulls, with Claude Code or another model.
- [Running knotless-serve](guide/server.md): the cache, appview, gateway
  and web pages.
- [Workflows](guide/workflows.md): run CI with `knotless-run`.
- [Sites](guide/sites.md): deploy a repository's website, a single-page
  app or a 404 page, by hand or on every push.

## Reference

- [Actions](reference/actions.md): everything you can do, and its
  command, MCP tool, XRPC method and web page.
- [Commands](reference/cli.md): `knotless`, `knotless-serve`,
  `knotless-run`, `knotless-triage` and `knotless-agent`, their flags, and
  the environment.
- [MCP tools](reference/mcp.md).
- [HTTP and XRPC API](reference/api.md): what `knotless-serve` answers,
  route by route.
- [Workflow files](reference/workflows.md): the YAML, what a step sees, and
  the secrets file.
- [knotless-run internals](reference/runner-internals.md): the state
  file, caches on disk, containers and volumes.
- [Performance](reference/performance.md): round trips and benchmarks.
- [Lexicons](../lexicons/dev/knotless): the record and method schemas.
- [Deploying](../deploy/README.md): how knotless.dev runs, and monitoring.
- [Observability](observability.md): what serve and the runner log and
  count, and why.

## Design

How knotless works, and why. Start with the [overview](design/README.md).

- [Overview](design/README.md): goals, non-goals, the pieces, the PDS's
  limits.
- [Storage](design/storage.md): records, keys, push, fetch, compaction.
- [Naming and identity](design/identity.md): renames, redirects, transfers,
  commit authors.
- [Access](design/access.md): OAuth, scopes, private repositories.
- [Gateway](design/gateway.md): collaborators' writes, protected branches.
- [Pulls, issues and moderation](design/collaboration.md): the
  conversation, merging, forks.
- [knotless-serve](design/serve.md): the cache, appview, moderation service
  and web pages.
- [knotless-run](design/runner.md): deciding what to run, scheduling,
  caches, secrets, checks, the merge gate.
- [The merge queue](design/merge-queue.md): batches and bisection.
- [Integrity and trust](design/security.md): who can do what.
- [Prior art](design/prior-art.md).

## Contributing

- [Development](development.md): building, tests, screenshots, scenarios.
- [AGENTS.md](../AGENTS.md): how changes are made and checked here.