Metadata-Version: 2.4
Name: cadastre
Version: 0.1.0
Summary: A map of an estate, and the policy for choosing within it.
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: pyyaml==6.0.3
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: manifest
Provides-Extra: mcp-client
Requires-Dist: mcp>=1.0; extra == 'mcp-client'
Provides-Extra: mcp-server
Requires-Dist: mcp>=1.0; extra == 'mcp-server'
Provides-Extra: serve
Requires-Dist: mcp>=1.0; extra == 'serve'
Description-Content-Type: text/markdown

# Cadastre

**Know what infrastructure you have, where things belong, and which rules apply.**

Cadastre is an address book and rulebook for your servers, services, networks,
domains, repositories, and deployment policies. It gives people and AI agents
one place to ask questions such as:

- Where can this application run?
- Must it stay private, or may it be public?
- Is the port or hostname already in use?
- Which pipeline and repository own it?
- Is the answer current, verified, or disputed?

Cadastre brings those facts together, explains where each answer came from, and
checks proposed deployment files against your rules.

It is a **map, not a control panel**. Cadastre does not deploy workloads, change
DNS or VPNs, operate containers, or reveal secret values. Updating Cadastre
updates the map only; it never changes your live infrastructure.

## Why use it?

Infrastructure knowledge is usually split across configuration files,
dashboards, tools, and people's memory. That works until someone new—or an AI
assistant—needs to make a safe decision.

Cadastre turns that scattered knowledge into answers with provenance and clear
warnings when information is stale, unverified, or contested. Instead of
guessing, a caller gets suitable choices, rejected choices, the rules involved,
and the evidence behind them.

Read [What Cadastre does](PRODUCT-GUIDE.md) for a plain-language walkthrough and
example.

## Quickstart with Docker

Create an empty persistent catalog with the project image:

```bash
docker run --rm \
  -v cadastre-data:/var/lib/cadastre \
  ghcr.io/thedancingdeveloper-org/cadastre:main \
  init --data-dir /var/lib/cadastre --empty
```

Then confirm it is ready:

```bash
docker run --rm \
  -v cadastre-data:/var/lib/cadastre \
  ghcr.io/thedancingdeveloper-org/cadastre:main \
  status --data-dir /var/lib/cadastre
```

The `main` image follows the latest successful main-branch build. Production
deployments should pin the signed immutable digest published by the release
pipeline. If the package is not visible to your Docker client, authenticate to
`ghcr.io` or [build the image locally](DEPLOYMENT.md#user-paths-published-artifacts-and-self-build).

To explore without creating a live catalog, clone the repository and query its
fictional example:

```bash
uv tool install cadastre
cadastre --catalog examples/catalog brief
cadastre --catalog examples/catalog context-for \
  "an internal application that needs a GPU"
```

Continue with [Using Cadastre](USING-CADASTRE.md) for catalog setup, common
commands, collectors, and remote access.

## Built for AI agents

**This repository and product are explicitly AI friendly.**

Cadastre offers structured MCP, HTTP, CLI JSON, JSON Schema, and OpenAPI
interfaces. Answers carry provenance and trust state, while `context-for`
returns the facts and exclusions relevant to one decision and `check` reviews a
proposed artifact before deployment. [`AGENTS.md`](AGENTS.md) provides
repository-level instructions for coding agents.

This design gives an agent useful ground truth without turning Cadastre into an
infrastructure control plane.

## Learn more

| Guide | What it covers |
|---|---|
| [What Cadastre does](PRODUCT-GUIDE.md) | Plain-language concepts, examples, boundaries, and trust signals |
| [Using Cadastre](USING-CADASTRE.md) | Installation, catalogs, commands, collection, and remote access |
| [Architecture](ARCHITECTURE.md) | Components, data ownership, and interface boundaries |
| [Deployment](DEPLOYMENT.md) | Containers, supported topologies, persistence, and operations |
| [Agent clients](AGENT-CLIENT.md) | Native MCP and the remote stdio bridge |
| [Plugin authoring](PLUGINS.md) | The read-only plugin contract and a single-file example |
| [Built-in plugins](BUILTIN_PLUGINS.md) | Configuration, credentials, outputs, and limits for shipped integrations |
| [Security](SECURITY.md) | Network identity and secure deployment profiles |
| [Design](DESIGN.md) | Detailed rationale and non-goals |
| [Testing](TESTING.md) | Test layers and local quality gates |
| [Examples](examples/README.md) | Fictional catalog and client configurations |
| [Contributing](contributing.md) | How changes are reviewed and merged through pull requests |

## License

Cadastre is available under the [MIT License](LICENSE).
