tegwick
b19896a9a9
Documents the dashboard's architecture, framework choice rationale, data-fetching strategies (static loaders + live polling), component library, page inventory, and key features including the Workstream Health Index and entity modals. Also registers the new page in the Reference nav and adds runbook section for node overload / runaway agent process (INC-002) with hardening checklist. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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 seven 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 criteriaconcepts_seed_v0.1.md— ten foundational conceptsroadmap_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
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
make api # db + migrate + api (restarts if already running)
Dashboard
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:
cd /path/to/your-project
custodian register-project --domain railiance
This will:
- Verify the API is running
- Look up the topic ID for the domain
- Check that the MCP server is registered in
~/.claude.json - Write a
CLAUDE.mdinto the project root - Post a progress event to the State Hub
Domain is auto-detected from project_charter_v*.md frontmatter if --domain is omitted.
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