Initial Central AI Hub docs: brief, rules, README, outline context, architecture

AGENTS.md

@@ -0,0 +1,91 @@
+# Central AI Hub (`central_ai_llm_master`)
+
+## Mission
+
+Build the **Hub**. The Hub is one small service. Every way in reaches every
+ability through it. Build the ability once. All ways in get it.
+
+## Authority
+
+Read `hub_brief.md` in this folder first. It is the agreed design. If this file
+and the brief disagree, the brief wins.
+
+- `hub_brief.md` — the agreed brief (source of truth).
+- `README.md` — technical readme.
+- `docs/outline/` — AI context. Start with `00-index.md`.
+
+## What the Hub does
+
+Five steps, in order:
+
+1. **Hear** — take voice or text from any way in.
+2. **Understand** — the LLM works out what was asked.
+3. **Check** — is this person allowed to ask for this?
+4. **Route** — send it to the right destination.
+5. **Answer** — return a short reply in the right shape for the device.
+
+The reply can be text, spoken audio (TTS), Artemis commands, a notification, an
+email, or a mix. TTS can play on the house speakers or on the phone.
+
+## The dividing line
+
+> Does this need a decision, or does it need to happen?
+
+- **Happen** — fast and certain. Go straight to the destination. No LLM in the
+  path of the action.
+- **Decision** — slow, multi-step, worth recording. Send to Paperclip.
+
+**Paperclip is the work bench, not the switchboard.**
+
+## Rules
+
+1. All models go through **OmniRoute**. Never call a provider directly.
+2. All secrets come from **`environment.d`**. Never hard-code.
+3. Own service, own port, own folder.
+4. No LLM in the path of a fast or consequential action.
+5. Paperclip only for slow, multi-step, recorded work.
+6. Replies return to the source and stay short.
+7. Restricted actions need **tap-to-approve** on the admin app.
+8. Only the admin app changes parental controls.
+9. A new ability registers with the Hub. Build it once.
+
+## Build order
+
+1. **Thin slice, end to end.** Issue a Paperclip API key. File one job from a
+   script. Get the result announced back. Prove the round trip.
+2. **Hub skeleton.** Hear → understand → route → answer, with one destination.
+3. **Approval flow.** "Did you ask for this?" on the admin app.
+4. **Internet control.** Standalone service with a plain API. Device-side
+   enforcement. Admin-only.
+5. **Artemis.** Standalone service with a plain API. Screen control only.
+6. **Move Jervis's tools** into the Hub. Jervis becomes voice-only.
+7. **Phone Kotlin app.** Wake word, voice to the Hub, replies and approvals.
+8. **Email and school pipelines.** Stay independent. Connect when ready.
+
+## Definition of done (phase 1)
+
+- A Paperclip API key exists.
+- One job is filed by script and its result is spoken.
+- The round trip is recorded in `docs/outline/04-agent-runbook.md`.
+
+## How this project relates to the other projects
+
+This project owns the **shared Hub**. It does not own the destinations.
+
+| Project | Relation |
+|---|---|
+| Email agent | Own pipeline. Reports through the Hub when ready. |
+| Compass / NHS | Own pipeline. Reports through the Hub when ready. |
+| Internet use control | Destination. Exposes a plain API. The Hub calls it. |
+| Artemis | Destination. Exposes a plain API. The Hub calls it. |
+| Jervis | Becomes voice-only. Its tools move here. |
+| dsh | Calls the Hub for actions. |
+
+Each project writes its own docs. Do not copy theirs here. Link to them.
+
+## Do not
+
+- Do not build one central brain. No single personality or memory.
+- Do not put Paperclip in the path of a fast command.
+- Do not duplicate a destination inside the Hub.
+- Do not add a spoken keycode as the only lock for restricted actions.