the-custodian/README.md

Confidential and Proprietary. Authorized Use Only. Subject to NDA & Contractual Penalty.

# The Custodian

**Transgenerational Cognitive Infrastructure** — a local-first, sovereignty-preserving agent system for co-creating and stewarding knowledge across six project domains.

The Custodian acts as co-creator and steward, not authority. Humans approve all irreversible decisions. The system is designed to still be coherent decades from now.

---

## Architecture

```
the-custodian/
├── canon/              # Curated, reviewable knowledge substrate
│   ├── constitution/   # Governance rules (v0.1)
│   ├── values/         # Nine foundational principles
│   └── projects/       # Six domain charters, concept seeds, roadmaps
├── memory/             # Operational logs — append-only, never rewritten
│   ├── working/        # Session notes (scoped, time-bounded)
│   └── episodic/       # Immutable event archive
├── state-hub/          # Live state service (the operational brain)
│   ├── api/            # FastAPI (PostgreSQL-backed REST + /state/summary)
│   ├── mcp_server/     # FastMCP stdio — Claude Code's native interface
│   ├── migrations/     # Alembic schema migrations
│   ├── dashboard/      # Observable Framework telemetry dashboard
│   ├── infra/          # docker-compose.yml (postgres + optional pgadmin)
│   └── scripts/        # seed.py, register_project.sh, custodian CLI
├── runtime/            # Agent runtime scaffolding (policies, prompts, adapters)
├── infra/              # Deployment, backups, encryption scaffolding
└── eval/               # Policy and regression test placeholders
```

The **dependency chain** across domains runs bottom-up:

```
Railiance → Markitect → Coulomb.social → Personhood / Foerster → Custodian
(ops)        (canon)     (interaction)     (rights/agency)        (integration)
```

---

## Project Domains

| Domain | Purpose | Topic ID |
|--------|---------|----------|
| **Custodian** | Master agent system; integrates all layers | `cee7bedf-2b48-46ef-8601-006474f2ad7a` |
| **Railiance** | Sovereign DevOps and operational reliability | `ca369340-a64e-442e-98f1-a4fa7dc74a38` |
| **Markitect** | Knowledge artifact management: authoring, versioning, retrieval | `5571d954-0d30-4950-980d-7bcaaad8e3e2` |
| **Coulomb.social** | Co-creation marketplace and governance experiment | `36c7421b-c537-4723-bf75-42a3ebc6a1dc` |
| **Personhood** | Rights and obligations framework for mixed-intelligence societies | `084430ab-c630-48dc-9e1d-d07d1e8fce3c` |
| **Foerster Capabilities** | Agency capability taxonomy (Foerster's Non-Trivial Machines) | `64418556-3206-457a-ba29-6884b5b12cf3` |

Each domain has three canon artifacts under `canon/projects/<domain>/`:
- `project_charter_v0.1.md` — purpose, problem, scope, success criteria
- `concepts_seed_v0.1.md` — ten foundational concepts
- `roadmap_v0.1.md` — multi-phase implementation plan

---

## State Hub — Quick Start

The State Hub is the live operational layer: a PostgreSQL database, a FastAPI REST service, an MCP server for Claude Code, and an Observable dashboard.

### Prerequisites

- Docker Engine (WSL2: see `CLAUDE.md` → Docker Setup)
- Python 3.12+ with `uv` (`pip install uv`)
- Node.js 18+ (for dashboard only)

### First-time setup

```bash
cd state-hub

cp .env.example .env          # set POSTGRES_PASSWORD
make install                  # uv sync → Python deps + custodian CLI in .venv
make install-cli               # symlink custodian to ~/.local/bin
make db                       # start postgres on 127.0.0.1:5432
make migrate                  # alembic upgrade head
make seed                     # insert 6 canonical topics
make api                      # uvicorn on 127.0.0.1:8000
```

API docs: http://127.0.0.1:8000/docs
Health check: `make check`

### Shortcut

```bash
make api  # db + migrate + api (restarts if already running)
```

### Dashboard

```bash
cd state-hub
make dashboard    # Observable Framework dev server on :3000
```

---

## Connecting a Project

Any repository can be registered as a Custodian project in one command:

```bash
cd /path/to/your-project
custodian register-project --domain railiance
```

This will:
1. Verify the API is running
2. Look up the topic ID for the domain
3. Check that the MCP server is registered in `~/.claude.json`
4. Write a `CLAUDE.md` into the project root
5. Post a progress event to the State Hub

Domain is auto-detected from `project_charter_v*.md` frontmatter if `--domain` is omitted.

```bash
custodian status              # health + summary totals + blocking decisions
custodian register-project    # full registration from cwd
```

---

## Claude Code Integration

The `state-hub` MCP server is registered at user scope in `~/.claude.json`.
It exposes 11 tools and 5 resources directly in every Claude Code session.

**Session protocol** (enforced via `~/.claude/CLAUDE.md`):
- Start: `get_state_summary()` — orientation snapshot
- End: `add_progress_event()` — append to the immutable log

Tool reference: `state-hub/mcp_server/TOOLS.md`

If the MCP server is missing from a session: check `~/.claude/CLAUDE.md` → MCP Server Registration.

---

## Governance

The constitution (`canon/constitution/custodian_constitution_v0.1.md`) defines hard boundaries:

**The Custodian may without approval:**
- Draft documents, plans, and structured artifacts
- Read/search canon and approved repositories
- Propose canon updates as PRs/patches (never direct writes)
- Create working-memory notes and session summaries

**Never permitted (v0.1):**
- Financial transactions or legal commitments
- External publication under Bernd's identity
- Storing secrets/credentials in plaintext
- Writing directly to `canon/` without a review gate

**Must escalate when:**
- Actions affect money, legal status, security, or external reputation
- Instructions conflict with values or the constitution
- Consent is unclear, especially in family-scoped data

### Canon Promotion Workflow

```
Custodian proposes → run gates (attribution, consistency, clarity, sensitivity, reversibility)
                   → human approves → merge
```

All canon changes carry provenance metadata. Episodic memory is append-only.

---

## Roadmap

| Phase | Focus | Status |
|-------|-------|--------|
| 0 | Canon + constitution + State Hub v0.1 | **done** |
| 1 | RAG over canon, drafting pipelines, consistency checks | planned |
| 2 | Stewardship automation (health checks, drift detection) | planned |
| 3 | Sovereign appliance (local inference on dedicated hardware) | future |
| 4 | Family custodianship (consent model, vault, succession) | future |

---

## Key Design Principles

- **Local-first, degrade-gracefully** — no vendor lock-in; can operate offline
- **Auditability and reversibility** — explicit gates; proposals precede changes
- **Safety by design** — Custodian is co-creator, not authority; humans approve irreversible decisions
- **Targeted information processing** — narrow, high-leverage work over general intelligence
- **Long timescale stewardship** — designed for multi-year and eventual multi-generational continuity