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

# The .sureops/ Repo Layout

> How to structure your service contract repository so sureops agents understand your environment.

The `.sureops/` directory in your knowledge base repository is where you define how sureops understands your environment. Agents read this during incident diagnosis, post-incident analysis, and fix-PR generation. The better you fill it in, the more grounded and accurate the AI output.

## Directory structure

```
.sureops/
├── services.yaml          # Service catalog: ownership, dependencies, runbook pointers
├── policy.yaml            # Operational policy: PR behavior, postmortem routing
├── runbooks/              # Markdown runbooks, one per issue type or service
│   ├── payments.md
│   ├── auth-service.md
│   └── checkout.md
├── postmortems/           # Written by sureops after incidents close (do not edit manually)
│   └── 2026-05-12-PRB-0042-checkout-timeout.md
└── README.md              # Auto-generated by sureops; explains the repo to new readers
```

The files you author and maintain are `services.yaml`, `policy.yaml`, and `runbooks/`. The `postmortems/` directory is written by sureops via pull requests after incident closure — you review and merge those PRs.

***

## services.yaml

**Who reads it**: Diagnosis Specialist, Incident Commander, Fix-PR Agent, Problem Investigator

Defines the service catalog: what services exist, who owns them, what tier they are, how they depend on each other, and where their runbooks live.

This is the single most impactful file. If you only author one file, make it this one.

See [services.yaml reference](/next/your-rules/services-yaml) for the full field-by-field guide.

***

## policy.yaml

**Who reads it**: Fix-PR Agent, Problem Investigator (postmortem PR)

Controls operational policy: whether fix PRs open automatically, draft vs. ready-for-review, which teams to request review from, and per-environment and per-service overrides.

Example structure:

```yaml theme={null}
# .sureops/policy.yaml
version: 1

defaults:
  source_fix_pr:
    auto_open: false
    draft: true
    reviewers: ["@sre-team"]
  postmortem_pr:
    auto_open: true
    reviewers: ["@sre-team"]

environments:
  prod:
    source_fix_pr:
      auto_open: false
      reviewers: ["@sre-prod-oncall"]
    postmortem_pr:
      reviewers: ["@sre-prod-oncall", "@compliance"]
```

Resolution order for `policy.yaml` (most specific wins):

1. Per-service, per-environment setting
2. Per-service setting
3. Per-environment setting
4. Default setting

***

## runbooks/

**Who reads it**: Diagnosis Specialist, Incident Commander

A collection of Markdown files describing how to diagnose and resolve known issue patterns. sureops uses vector search to find the most relevant runbooks for each incident automatically.

See [Runbooks & Knowledge Base](/next/your-rules/runbooks-and-knowledge-base) for authoring best practices.

***

## postmortems/

This directory is written by sureops, not by you. After an incident closes, the Problem Investigator agent generates a root cause analysis and opens a pull request with a new file in this directory.

The filename format is: `YYYY-MM-DD-{problem-id}-{slug}.md`

You review the PR and merge when satisfied. The postmortem becomes part of your historical record and is indexed for future incident grounding.

***

## Where to put the .sureops/ directory

### Single-repo per service

Put the `.sureops/` directory in a dedicated knowledge base repository — a repo that holds documentation and configuration, separate from your application code. Connect this repo in **Settings → Knowledge Base**.

This is the recommended layout for most teams. It gives you a single place to manage ownership, runbooks, and policies, with CODEOWNERS controlling who reviews changes.

### Monorepo

For teams with a monorepo, put `.sureops/` at the root of the monorepo. sureops reads it from the default branch (`main` unless you configure otherwise).

***

## Which branch does sureops read from?

sureops reads from your configured knowledge base branch (default: `main`). Changes take effect the next time the contract is ingested after a push to that branch.

Ingestion happens automatically on push via a webhook. You can also trigger a manual re-sync from **Settings → Knowledge Base → Sync now**.

***

## Creating .sureops/ for the first time

Two paths:

**Author it yourself**: Create the directory and files following the schemas documented in this section. Start with a minimal `services.yaml` (5 fields per service) and expand from there.

**Accept a sureops-generated starter PR**: From **Settings → Knowledge Base**, click "Generate starter contract." sureops reads your observed telemetry, Kubernetes deployments, and repository CODEOWNERS to produce a best-effort scaffold. You review the PR, edit anything incorrect, and merge. See [Customer Landscape](/next/your-rules/customer-landscape) for details on this path.

***

## Editing .sureops/

All edits go through pull requests to your knowledge base repository. sureops does not provide a form-based editor for these files — the YAML is the source of truth, and your normal code review process governs changes.

The Settings UI shows the current state of your contract (last sync timestamp, active services, runbook count) and deep-links to GitHub for editing.