.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
README.md at the top: it’s scaffolded at the repo root, not inside .sureops/ — only runbooks/README.md and postmortems/README.md (per-directory usage notes) are auto-scaffolded inside .sureops/. skills/ isn’t scaffolded at all — if you want custom agent skills, you create the directory and files yourself; sureops still reads .sureops/skills/*.md at ingest, there’s just no starter content for it.
Today’s Generate starter contract flow creates exactly six files: .sureops/services.yaml, .sureops/policy.yaml, .sureops/runbooks/README.md, .sureops/runbooks/_example.md, .sureops/postmortems/README.md, and the repo-root README.md. Everything else shown above — operating-context.md, skills/, and any runbook beyond the example — is something you add yourself.
The files you author and maintain are services.yaml, policy.yaml, operating-context.md, skills/, and runbooks/. The postmortems/ directory is written by sureops via pull requests when an incident close creates a Problem Record — not every incident close does; a policy gate on severity and closure reason decides whether one is created at all — you review and merge those PRs. sureops can also open a second, separate kind of PR under the same condition: one adding a new file to .sureops/runbooks/, when the Problem Commander judges the incident revealed a reusable diagnosis/remediation pattern worth capturing as a runbook. See Skills for what goes in .sureops/skills/*.md.
services.yaml
Who reads it: Diagnosis Specialist, Incident Commander, Fix PR Agent, Problem Commander Defines the service catalog: what services exist, who owns them, 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 for the full field-by-field guide.policy.yaml
Who reads it: Fix PR Agent, Problem Commander (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:policy.yaml (most specific wins):
- Per-service, per-environment setting
- Per-service setting
- Per-environment setting
- Default setting
runbooks/
Who reads it: Diagnosis Specialist, Incident Commander, Resolution Specialist, Verification Specialist 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 for authoring best practices.postmortems/
This directory is written by sureops, not by you. When an incident close creates a Problem Record, the Problem Commander agent generates a root cause analysis and opens a pull request with a new file in this directory. Not every incident close creates a Problem Record — a policy gate on severity and closure reason decides whether one is created at all, so a low-severity or self-recovered incident may close without ever reaching this directory. The filename format is:{problem_external_id}.md — no date prefix, no slug. problem_external_id is the PRB-YYYY-NNNN external ID (e.g. PRB-2026-0042.md).
Separately, if you use the manual export feature on a problem’s detail page, that export writes its own file with a date-prefixed name — {date}-{problem_external_id}.md (e.g. 2026-05-12-PRB-2026-0042.md) — in a different pull request, distinct from the automatic post-closure PR above.
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
Dedicated knowledge base repo (recommended)
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.
Monorepo
For teams with a monorepo, put.sureops/ at the root of the monorepo — then, just as with a dedicated repo, you still need to designate that repo as your organization’s knowledge base repo in Settings → Knowledge Base. Ingest only ever reads from the one designated KB repo; putting .sureops/ in a repo you haven’t designated has no effect. 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). New services, new runbooks, and policy changes take effect the next time the contract is ingested after a push to that branch.
Editing a field on a service that’s already in your contract is a different story: once a service node is contract-locked, a re-ingest doesn’t update its declared fields (owner, tags, depends_on, identifiers.*, image.*, deploy.*, health) even though the push succeeds and ingest reports success — only the node’s “last seen” timestamp refreshes. See Customer Landscape for why, and what to do if you need to correct an existing service’s fields.
Ingestion happens automatically on push via a webhook. You can also trigger a manual re-ingest from the Advanced section of Settings → Knowledge Base using the Force re-ingest button — it re-pulls the contract from the KB repo’s current head, ignoring the last-seen commit; the same contract-lock caveat above still applies to it.
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 minimalservices.yaml (2 required fields per service: name and git_repo) and expand from there.
Accept a sureops-generated starter PR: From Settings → Knowledge Base, click “Generate starter contract.” sureops composes a scaffold from whatever’s available — a Backstage catalog you provide, telemetry/Kubernetes discovery already in your landscape graph, or auto-discovered GitHub repos — falling back to an empty starter if none of those yield anything. You review the PR, edit anything incorrect, and merge. See Customer Landscape for details on this path.