cadastre: Instructions file for Codex

Cadastre agent and contributor guide

Cadastre records infrastructure facts and policy. It does not deploy workloads, mutate DNS/VPN/orchestrators, execute commands on hosts, or return secret values. The HTTP API, MCP server, and GUI are application interfaces over the same SQLite-backed catalog.

Using Cadastre

Use the networked MCP endpoint when one is supplied by the deployment. For clients that need stdio, install the published package extra and run the remote-only bridge. The ordinary HTTP API is useful for scripts and GUI integrations; /mcp is the MCP transport and must not be substituted with /brief.

MCP:  ${CADASTRE_MCP_URL}   (Streamable HTTP, normally ends in /mcp)
API:  ${CADASTRE_HTTP_URL}  (ordinary HTTP/API base, normally serves /brief)

The endpoint, TLS identity, and authentication method are deployment inputs. Never guess a hostname, port, network, or secret path. Tokens belong in a protected environment variable or file and never in URLs, argv, client JSON, catalog data, logs, or agent-facing output.

At the start of a session:

MCP:  call brief, then context_for(intent)
API:  GET  $CADASTRE_HTTP_URL/brief
      POST $CADASTRE_HTTP_URL/context-for  {"intent":"..."}

When you have words rather than an id, search instead of guessing one:

MCP:  lookup(query="komodo api key")          # ranked candidates
      credential_for(service="komodo", action="deploy")
      secret_describe(ref="NAME")             # shape and location, no value
      dns_chain(hostname="app.example.com")   # record -> edge -> node

Before committing a deployment artifact, run check through MCP or the API:

MCP:  check(artifact, kind)
API:  POST $CADASTRE_HTTP_URL/check

Read provenance and trust state on every answer. stale, unverified, and contested data must be reported before it influences a decision. Read the exclusions returned by context_for; do not route around a rejected candidate.

If the catalog is wrong, use the gated write operation (add, update, delete, or annotate) through the supported client/API. A catalog write changes the map only; it never changes the estate. Source-authoritative entities and observed evidence may be refused by design. A refusal is an answer, not an invitation to bypass the gate.