> ## 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.

# Customer Landscape

> Two paths to establishing your service topology — author .sureops/ yourself or accept a sureops-generated starter PR.

Your "customer landscape" is sureops's model of your environment: which services exist, who owns them, how they depend on each other, and where they run. It's built from two sources: your `.sureops/` contract (what you declare) and automatic telemetry discovery (what sureops observes).

## Two paths to get started

### Path 1: Generate a starter PR

From **Settings → Knowledge Base → Generate starter contract**, sureops will:

1. Read the services observed in your telemetry (OTel service names)
2. Read your Kubernetes deployments and pod labels
3. Read CODEOWNERS files from your connected repositories
4. Use an LLM to fill in tier, runbook hints, and dependency patterns
5. Open a pull request against your knowledge base repository with a draft `.sureops/services.yaml`

You review the PR (typically 5 fields per service), correct anything wrong, and merge. sureops re-syncs on the next push to your default branch.

**Good for**: teams with many services that would take a while to document manually, or teams that want to see what sureops already knows before deciding what to fill in.

### Path 2: Author .sureops/ yourself

Create the directory and files manually, following the schemas in this section:

* [The .sureops/ repo layout](/next/your-rules/repo-layout)
* [services.yaml reference](/next/your-rules/services-yaml)
* [Runbooks & knowledge base](/next/your-rules/runbooks-and-knowledge-base)

Start minimal — a `services.yaml` with name, repo, owner, runbook, tier, and dependsOn for your most critical services is enough to see a significant improvement in agent output.

**Good for**: teams with a small number of critical services, or teams that already have service documentation in another form and can adapt it quickly.

***

## How the landscape is built

### Layer 0: Telemetry discovery

sureops observes service names from your OTel traces, Kubernetes labels, and log sources. This runs automatically and provides a baseline — you don't need to configure anything for this layer.

Telemetry-discovered services appear in the landscape immediately but carry lower provenance. They're useful for blast-radius analysis and dependency mapping, but agents are less confident about ownership and runbooks for undeclared services.

### Layer 1: sureops-generated starter

When you request a starter PR, sureops combines telemetry discovery with CODEOWNERS and LLM-assisted inference to produce a structured `.sureops/services.yaml`. This is a scaffold — review and edit before merging.

### Layer 2: Customer-authored .sureops/

Your merged `.sureops/services.yaml` and runbooks provide high-confidence, customer-locked data. These entries take precedence over telemetry and auto-discovery for any field you declare.

The provenance ranking (highest wins): `manual > customer_contract > telemetry > kubernetes_scan`.

***

## Keeping the landscape in sync

### After merging your contract

sureops ingests the contract on every push to your knowledge base default branch. Changes to `services.yaml` or runbooks take effect on the next ingest, which typically completes within seconds of the push.

You can check the sync status in **Settings → Knowledge Base → Last sync**.

### When your architecture changes

When you add, rename, or retire a service:

1. Update `.sureops/services.yaml` via a PR to your knowledge base repository
2. sureops re-ingests on merge
3. The landscape graph is updated; agents use the new data on the next incident

### When telemetry adds a new service

If a new service name appears in your telemetry and isn't in your contract, it's added to the landscape as a telemetry-discovered service. You'll see it in **Settings → Knowledge Base → Services** with a "telemetry" provenance label. To promote it to a first-class entry, add it to `services.yaml`.

***

## Conflict resolution

When the same service appears in both your contract and an auto-discovered source, your contract wins for any field you specified. Auto-discovery fills in only what you haven't declared.

| Your contract says     | Telemetry says              | Result                                             |
| ---------------------- | --------------------------- | -------------------------------------------------- |
| `tier: P1`             | (not observed)              | `tier: P1` — from contract                         |
| (not declared)         | `namespace: prod-payments`  | `namespace: prod-payments` — from telemetry        |
| `owner: payments-team` | CODEOWNERS: `platform-team` | `owner: payments-team` — explicit declaration wins |

***

## Manual authoring vs. accepting future updates

After the initial setup, sureops may propose updates to your contract via pull requests as it observes new services or detects changes in your topology. These are always proposals — you review and merge (or reject) each one.

You are never required to accept sureops-proposed changes. Your `.sureops/` directory is your code, governed by your review process.

Fields you've explicitly declared (`customer_locked: true` in the internal model) are never overwritten by telemetry ingestors. Only fields you haven't specified can be filled in by auto-discovery.