Add documentation: root README and state-hub/README
Root README covers: architecture, domain table with topic IDs, quick start, project registration, Claude Code integration, governance summary, roadmap, and design principles. state-hub/README covers: full setup guide, Makefile targets, DB schema with governance constraints, API summary (incl. /state/summary shape), MCP server config, custodian CLI reference, dashboard pages, and WSL2 known issues. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
201
README.md
201
README.md
@@ -2,31 +2,192 @@ Confidential and Proprietary. Authorized Use Only. Subject to NDA & Contractual
|
||||
|
||||
# The Custodian
|
||||
|
||||
Transgenerational Cognitive Infrastructure
|
||||
**Transgenerational Cognitive Infrastructure** — a local-first, sovereignty-preserving agent system for co-creating and stewarding knowledge across six project domains.
|
||||
|
||||
# Custodian Repo Skeleton (v0.1)
|
||||
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.
|
||||
|
||||
This repository is an initial, local-first canon + governance skeleton for the Custodian project and its top-level domains:
|
||||
---
|
||||
|
||||
- Railiance
|
||||
- Markitect
|
||||
- Coulomb.social
|
||||
- Foerster Capabilities
|
||||
- Personhood
|
||||
- Custodian
|
||||
## Architecture
|
||||
|
||||
## Structure
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
- `canon/` — curated, reviewable knowledge substrate (identity lives here)
|
||||
- `memory/` — working and episodic logs (operational + append-only history)
|
||||
- `eval/` — policy and regression tests (future automation)
|
||||
- `runtime/` — policies/prompts/tool adapters (agent runtime scaffolding)
|
||||
- `infra/` — deployment, backups, encryption scaffolding
|
||||
The **dependency chain** across domains runs bottom-up:
|
||||
|
||||
## Workflow (suggested)
|
||||
```
|
||||
Railiance → Markitect → Coulomb.social → Personhood / Foerster → Custodian
|
||||
(ops) (canon) (interaction) (rights/agency) (integration)
|
||||
```
|
||||
|
||||
1. Edit canon artifacts in `canon/`
|
||||
2. Propose changes via PR/patch workflow
|
||||
3. Tag and sign periodic `Canon Releases`
|
||||
---
|
||||
|
||||
> v0.1 focuses on schemas, governance, and initial charters/roadmaps/concepts.
|
||||
## 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 start # db + migrate + api (all in one)
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
Reference in New Issue
Block a user