API - CODEX AGENTS: persistence and lifecycle endpoints

README.md

@@ -18,3 +18,40 @@
 External Codex instances never receive Plane session cookies, raw Tasker API tokens, database access, or a generic HTTP proxy into Tasker.
 
 All writes go through NODE.DC Agent Gateway, are scoped by agent grants, and are recorded as actions of a dedicated agent identity owned by a human platform user.
+
+## Current implementation
+
+- Fastify service with `/healthz`, `/readyz`, and capability metadata.
+- Postgres migrations for agents, grants, token hashes, pairing codes, audit events, and idempotency keys.
+- Internal REST endpoints for agent profile, grant, and token lifecycle.
+- Opaque agent tokens are generated once and stored only as SHA-256 hashes.
+- MCP and Tasker write execution are documented but not implemented yet.
+
+## Local development
+
+```bash
+cp .env.example .env
+docker compose --env-file .env -f docker-compose.local.yml up -d postgres
+npm install
+npm run migrate
+npm run dev
+```
+
+Useful checks:
+
+```bash
+npm run check
+npm run build
+curl http://127.0.0.1:4100/readyz
+curl http://127.0.0.1:4100/api/v1/meta/capabilities
+```
+
+Create a local test agent:
+
+```bash
+curl -X POST http://127.0.0.1:4100/api/v1/agents \
+  -H 'Content-Type: application/json' \
+  -d '{"owner_user_id":"local-user","owner_email":"local@example.test","display_name":"Local Codex"}'
+```
+
+Do not expose these lifecycle endpoints publicly before the Launcher/internal auth layer is added.