coulomb/the-custodian
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(state-hub): decouple embedded service tree

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-17 20:16:30 +02:00
parent 260b6e8ebd
commit 0375e57626
277 changed files with 52 additions and 46475 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
AGENTS.md
View File

@@ -4,7 +4,7 @@ This file provides guidance to Codex (Codex.ai/code) when working with code in t
## What This Repository Is
**The Custodian** is a *transgenerational cognitive infrastructure* — a local-first, sovereignty-preserving agent system for co-creating and stewarding knowledge across seven project domains. v0.1 is a governance and schema skeleton; `state-hub/` is the first live implementation layer.
**The Custodian** is a *transgenerational cognitive infrastructure* — a local-first, sovereignty-preserving agent system for co-creating and stewarding knowledge across seven project domains. v0.1 is a governance and schema skeleton; State Hub is the first live implementation layer and now lives in the standalone repo at `/home/worsch/state-hub`.
## Repository Structure
@@ -24,13 +24,7 @@ memory/ # Operational logs — append-only, never silently rew
working/ # Session notes (scoped, time-bounded)
episodic/ # Immutable event archive
state-hub/ # Live state service (PostgreSQL + FastAPI + MCP + dashboard)
api/ # FastAPI app (models, schemas, routers)
mcp_server/ # FastMCP stdio server for Codex
migrations/ # Alembic migrations
dashboard/ # Observable Framework telemetry dashboard
infra/ # docker-compose.yml (postgres + optional pgadmin)
scripts/ # seed.py — inserts 6 canonical topics
state-hub/ # Pointer only; service source lives at /home/worsch/state-hub
runtime/ # Agent runtime scaffolding (policies, prompts, tool adapters)
infra/ # Deployment, backups, encryption scaffolding
@@ -47,7 +41,7 @@ Each project under `canon/projects/` follows a consistent three-file pattern:
### State Hub (primary active service)
```bash
cd state-hub
cd /home/worsch/state-hub
# One-time setup
cp .env.example .env # edit POSTGRES_PASSWORD
@@ -96,7 +90,7 @@ Every Codex session in this repository must follow this ritual:
3. If decisions were made, record them with `record_decision()`
4. If API routers or models were changed, run the test suite as a gate:
```bash
cd state-hub && make test
cd /home/worsch/state-hub && make test
```
Requires postgres running (`make db`) and `custodian_test` database to exist.
Create it once with: `psql -U custodian -c "CREATE DATABASE custodian_test"`
@@ -109,7 +103,7 @@ Every Codex session in this repository must follow this ritual:
local copy is up to date, then run the consistency sync:
```bash
git -C <repo_path> pull --ff-only
cd state-hub && make fix-consistency REPO=the-custodian
cd /home/worsch/state-hub && make fix-consistency REPO=the-custodian
```
This syncs task blocks → DB and updates task statuses. Without this step, the
"Open Workstreams by Domain" chart will show 0 progress even for completed work.
@@ -124,13 +118,13 @@ Every Codex session in this repository must follow this ritual:
For repos where work runs on a remote machine, prefer the combined target:
```bash
cd state-hub && make fix-consistency-remote REPO=<slug>
cd /home/worsch/state-hub && make fix-consistency-remote REPO=<slug>
```
**On a machine where the checkout path differs from what's in the DB**, use
`--here` to auto-detect the slug from the git root-commit fingerprint:
```bash
cd state-hub && make fix-consistency-here REPO_PATH=/path/to/repo
cd /home/worsch/state-hub && make fix-consistency-here REPO_PATH=/path/to/repo
```
This also auto-registers `host_paths[hostname]` so subsequent runs need no override.