docs(claude): split CLAUDE.md into BOOTSTRAP + CATALOG + PATTERNS (Phase C)

.claude/BOOTSTRAP.md

@@ -0,0 +1,80 @@
+# PMOVES.AI Bootstrap
+
+**Flat foundation. Load this always. Load deeper context only when your task needs it.**
+
+You are on a PMOVES.AI node (Z890 / 5090 / 4090 / KVM4-1 / KVM4-2 / KVM2 / Jetson / SPARK / Cloudflare Edge). Per PR #1378 MOF Architecture: **every node is a pore in the lattice — capacity-class, not expertise-lane.** Run PMOVES to your physical capacity. Delegate across nodes via the paths below when a task exceeds your local reach.
+
+## Emperor-CHIT-Humility — disclose at session start
+
+Before editing or non-trivial work, state which you have vs missing:
+
+- [ ] **Cipher MCP** reachable (`http://localhost:8105/health`)
+- [ ] **A2A** reachable (`GET /.well-known/agent-card.json` on Agent Zero)
+- [ ] **Known Roads** loaded (table below)
+- [ ] **CHIT passphrase** set (`$CHIT_PASSPHRASE`; unsigned fallback is acceptable in dev)
+- [ ] **Node-peer visibility** (`make -C pmoves fleet-status`)
+- [ ] **MCP/service catalog** loaded (see CATALOG.md when needed)
+
+Missing items are not failures — they are operational facts. Disclose them. Never bluff awareness.
+
+## Known Roads — dangerous ops route through Make targets
+
+| Need | Known Road |
+|------|------------|
+| Start / restart services | `make -C pmoves up-<service>` (never `docker compose up` raw) |
+| Apply secrets | `make -C pmoves secrets-funnel` (before any service start after env change) |
+| Read-only health | `make -C pmoves health-quick` / `health-check-all` |
+| Fleet view | `make -C pmoves fleet-status` (never raw `tailscale status` for public IPs) |
+| CHIT-sign provenance | `make -C pmoves sign-trail SUMMARY=... AGENT=...` |
+| Refresh living docs | `make -C pmoves docs-reconcile` |
+
+Full Known Roads catalog lives in `.claude/PATTERNS.md § Known Roads`. When the damage-control hook converts a raw `docker` / `netsh` / `gh workflow run` command to an `ask` prompt, that means a Make target already exists — use it.
+
+## MCP Entrypoints (configured in `.claude/mcp.json`)
+
+| Server | Transport | Purpose |
+|--------|-----------|---------|
+| `pmoves-cipher` | SSE `http://localhost:8105/sse` | Persistent agent memory lookups + writes |
+| `docker` | `mcp/docker` | Container inspection via local Docker socket |
+| `hostinger-mcp` | stdio | Hostinger VPS API via `HOSTINGER_API_KEY` |
+| `tailscale` | stdio | Tailnet inventory, stale-node cleanup, ACL operations |
+
+## Cross-node delegation — three paths
+
+| Path | When to use |
+|------|-------------|
+| **Agent Zero MCP** `POST http://localhost:8080/mcp/command` | Orchestration, task delegation, subordinate agent spawn |
+| **A2A** `GET /.well-known/agent-card.json` (plumbing wired via PR #1293; activate via `A0_SET_a2a_server_enabled=true`) | Peer discovery, task submission across nodes |
+| **NATS** `agent.peer.heartbeat.v1` (Phase D, pending mutual-watching skill) | Continuous peripheral observation of peer nodes |
+
+No task requires all three — pick the narrowest path that delivers. When A2A is disabled (default), say so in your disclosure; don't pretend cross-node delegation is available.
+
+## Where to look next
+
+| You want | Load |
+|----------|------|
+| Service ports, URLs, health endpoints | [`CATALOG.md`](./CATALOG.md) |
+| Full Known Roads, dev patterns, CHIT, skill pairings | [`PATTERNS.md`](./PATTERNS.md) |
+| Who's working on what right now | `pmoves/docs/AGENTS/AGNOTE4482PHI.t1.md` § Active Claim Register |
+| Cold-start orientation | `pmoves/docs/AGENTS/AGNOTE4482_SITREP.md` |
+| Gateway pointers (audits, waves, Three-Body) | `pmoves/docs/AGENTS/AGNOTE4482.md` |
+| Architecture-level thesis | `pmoves/docs/architecture/PMOVES_MOF_ARCHITECTURE.md` + `PMOVES_GRAND_CONVERGENCE.md` |
+| Submodule-specific context | That submodule's `CLAUDE.md` — opt-in only, not auto-loaded |
+
+## Rules that survive every session
+
+1. **Leverage existing services, don't rebuild.** Hi-RAG v2 for retrieval, NATS for events, MinIO via Presign for artifacts, Agent Zero `/mcp/*` for orchestration. The catalog exists.
+2. **Test before PR.** `/test:pr` + document the Testing section. Docstring coverage ≥80% on new Python.
+3. **Never raw docker / tailscale CLI** for operations with Make-target equivalents. The hooks will block and redirect.
+4. **Village Rule.** No agent operates alone in production validation. Claim (AGNOTE4482PHI.t1), work, sign, release.
+5. **Signing is optional locally, never skipped for session-end provenance.** `sign-trail` emits unsigned if `CHIT_PASSPHRASE` unset — that's fine in dev, still run it.
+6. **Prefer the minimum task scope.** If you find adjacent cleanups, open a follow-up; don't expand the current claim.
+
+## When context feels heavy
+
+If this file is all you remember, you can still do the right thing:
+- Ask "is there a Make target for this?" — if yes, use it.
+- Ask "is this file in `CATALOG.md` or `PATTERNS.md`?" — if yes, load it.
+- Ask "have I disclosed what I don't know?" — if no, do that first.
+
+The rest is scaffolding.

.claude/CATALOG.md

@@ -0,0 +1,111 @@
+# PMOVES.AI Service Catalog
+
+**Ports, URLs, health endpoints. Load this on demand when you need a specific service address.**
+
+All services expose `/healthz` for liveness and `/metrics` for Prometheus.
+
+## Core Infrastructure
+
+**TensorZero Gateway** `:3030` — **[PRIMARY MODEL PROVIDER & OBSERVABILITY]**
+- Centralized LLM gateway for all providers (OpenAI, Anthropic, Venice, Ollama)
+- ClickHouse-backed observability, request/response logging, token tracking
+- UI dashboard at `:4000`
+- Chat API: `http://localhost:3030/v1/chat/completions`
+- Embedding API: `http://localhost:3030/openai/v1/embeddings` (**NOT** `/v1/embeddings` — returns 404)
+- Embedding model format: `tensorzero::embedding_model_name::<model_name>` (e.g., `qwen3_embedding_4b_local`)
+- Qwen3-Embedding-4B = **2560d** (not 3072); Qwen3-Embedding-8B = 4096d
+- **Use for:** all LLM calls, embeddings, provider routing, usage analytics
+- Detail: `.claude/context/tensorzero.md`
+
+**TensorZero ClickHouse** `:8123` — Observability metrics storage. `curl http://localhost:8123/ping`.
+
+**TensorZero UI** `:4000` — Metrics dashboard, request inspection.
+
+## Agent Coordination & Orchestration
+
+**Agent Zero** `:8080` API, `:8081` UI — Control-plane orchestrator. MCP API at `/mcp/*`. Subscribes to NATS. Health: `GET http://localhost:8080/healthz`. **Use for:** orchestration, MCP commands, task delegation.
+
+**Mesh Agent** (no HTTP) — Distributed node announcer; publishes host presence/capabilities on NATS every 15s.
+
+**Archon** `:8091` API, `:3737` UI — Supabase-driven agent service, prompt/form management. Connects to Agent Zero MCP. Health: `GET http://localhost:8091/healthz`.
+
+**Channel Monitor** `:8097` — External content watcher (YouTube channels). Posts to PMOVES.YT `/yt/ingest`.
+
+**Cipher Memory** `:8105` — Knowledge-graph memory (Neo4j backend). MCP bridge at `pmoves-cipher-mcp/` (stdio). API: `POST /api/memory`, `GET /api/memory/search?q=...`. Health: `GET /health`. MCP tools: `pmoves_cipher_store`, `pmoves_cipher_search`, `pmoves_cipher_store_reasoning`, `pmoves_cipher_reasoning_patterns`.
+
+## Retrieval & Knowledge Services
+
+**Hi-RAG Gateway v2** `:8086` CPU, `:8087` GPU **[PREFERRED]** — Hybrid RAG with cross-encoder reranking. Combines Qdrant (vectors) + Neo4j (graph) + Meilisearch (full-text). API: `POST /hirag/query` with `{"query": "...", "top_k": 10, "rerank": true}`.
+
+**Hi-RAG Gateway v1** `:8089` CPU, `:8187` GPU **[LEGACY]** — Use v2 for new features.
+
+**DeepResearch** `:8098` — LLM-based research planner (Alibaba Tongyi). NATS worker on `research.deepresearch.request.v1`. Auto-publishes results to Open Notebook.
+
+**SupaSerch** `:8099` — Multimodal holographic deep research orchestrator. Coordinates DeepResearch + Archon/Agent Zero MCP. NATS: `supaserch.request.v1` / `supaserch.result.v1`. Metrics: `GET /metrics`.
+
+**Open Notebook** (external, SurrealDB) — Accessed via `$OPEN_NOTEBOOK_API_URL` + token.
+
+## Voice & Speech
+
+**Flute-Gateway** `:8055` HTTP, `:8056` WebSocket — Multimodal voice communication with Pipecat. Prosodic TTS. API: `POST /v1/voice/synthesize/prosodic`. Health: `GET /healthz`. Detail: `.claude/context/flute-gateway.md`.
+
+**Ultimate-TTS-Studio** `:7860` native, `:7861` Docker — 14-engine TTS (KittenTTS, Kokoro, F5, IndexTTS/2, Fish Speech S1/S2 Pro, VoxCPM, Higgs Audio, Chatterbox variants, Qwen Voice Design, VibeVoice). Gradio UI. **GPU-accelerated, runs natively via Pinokio (NOT Docker).** Health: `GET /gradio_api/info`.
+
+## Media Ingestion & Processing
+
+**PMOVES.YT** `:8077` — YouTube ingestion. Downloads to MinIO, retrieves transcripts. API: `POST /yt/ingest`.
+
+**FFmpeg-Whisper** `:8078` — Media transcription with Faster-Whisper (small model). GPU. Reads/writes MinIO.
+
+**Media-Video Analyzer** `:8079` — YOLOv8 frame analysis. Every 5th frame, conf 0.25. Outputs to Supabase.
+
+**Media-Audio Analyzer** `:8082` — Emotion/speaker detection. Model: `superb/hubert-large-superb-er`.
+
+**Extract Worker** `:8083` — Text embedding + indexing. Qdrant (vectors) + Meilisearch (FTS). Model: `all-MiniLM-L6-v2`. API: `POST /ingest`.
+
+**PDF Ingest** `:8092` — Document ingestion orchestrator. Reads PDFs from MinIO, sends to extract-worker.
+
+**LangExtract** `:8084` — Language detection + NLP preprocessing. Used by notebook sync.
+
+**Notebook Sync** `:8095` — SurrealDB Open Notebook synchronizer. Poll interval 300s. Calls LangExtract + Extract Worker.
+
+## Utility & Integration
+
+**Presign** `:8088` — MinIO URL presigner for short-lived downloads. Requires `$PRESIGN_SHARED_SECRET`. Allowed buckets: `assets`, `outputs`.
+
+**Render Webhook** `:8085` — ComfyUI render callback handler. Requires `$RENDER_WEBHOOK_SHARED_SECRET`. Writes to Supabase, stores to MinIO.
+
+**Publisher-Discord** `:8094` — Discord notification bot. Listens on `ingest.file.added.v1`, `ingest.transcript.ready.v1`, summary/chapter events.
+
+**Jellyfin Bridge** `:8093` — Jellyfin metadata webhook + helper. Syncs Jellyfin events to Supabase.
+
+## Monitoring Stack
+
+**Prometheus** `:9090` — Metrics scrape from all services (all expose `/metrics`).
+**Grafana** `:3000` — Dashboards, datasources Prometheus + Loki. Pre-configured "Services Overview".
+**Loki** `:3100` + **Promtail** — Centralized log aggregation. All services configured with Loki labels.
+**cAdvisor** `:8080` — Container metrics for Prometheus.
+
+## Data Storage
+
+**NATS** `:4222`, `:9222` WS (standalone DoX), `:9223` WS (docked via compose) — JetStream event broker. **Always authenticated:** `nats://nats:pmoves@nats:4222`. Subject catalog: `.claude/context/nats-subjects.md`.
+
+**Supabase** — 13-service self-hosted stack (profile `supabase-local`). Kong `:8000`, PostgREST `:3000`, Studio `:54323`. Canonical consumer URL: `http://supabase-kong:8000/rest/v1`. Standard vars: `JWT_SECRET`, `ANON_KEY`, `SERVICE_ROLE_KEY` (`SUPABASE_*` aliases for compat). Services: DB (Postgres 17.6.1), GoTrue, PostgREST v14.3, Kong 3.7.1, Realtime v2.72.0, Storage v1.37.1, Studio, imgproxy, pg-meta, Edge Functions, Analytics (Logflare), Vector, Supavisor.
+
+**Neo4j** `:7474` HTTP, `:7687` Bolt — Graph DB for CHIT consciousness taxonomy, agent memory. Profile: `make -C pmoves neo4j-local-up`. API: `POST http://localhost:7474/db/neo4j/tx/commit`. Submodule: `PMOVES-Neo4j`.
+
+**Qdrant** `:6333` — Vector embeddings. Primary collection: `pmoves_chunks_qwen3` (2560d, Qwen3-Embedding-4B). Legacy: `pmoves_chunks` (384d, MiniLM — do not use). **CRITICAL:** `QDRANT_RECREATE_ON_DIM_MISMATCH` defaults to true; **will delete all data** if dims change — always `false` in production. Hi-RAG v2 requires `EMBEDDING_BACKEND=tensorzero` in compose env.
+
+**Meilisearch** `:7700` — Full-text keyword search, typo-tolerant.
+
+**MinIO** `:9000` API, `:9001` Console — S3-compatible. Buckets: `assets`, `outputs`.
+
+## Integration Rule — Leverage, Don't Duplicate
+
+- **DO** use Hi-RAG v2 for knowledge retrieval
+- **DO** publish to NATS for event coordination
+- **DO** store artifacts in MinIO via Presign
+- **DO** call Agent Zero MCP API for orchestration
+- **DON'T** build new RAG, search, or monitoring systems
+- **DON'T** create new event buses or message brokers
+- **DON'T** duplicate existing embeddings or indexing