.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
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 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: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 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. 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 minimalservices.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 for details on this path.