# 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.

A question about another project's data goes to that project's `/ask` endpoint.
See `docs/ask-contract.md`. The Hub never learns a project's data model.

## 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.
10. A data project answers `/ask` read-only. Never change state on a query.
11. High-consequence control does not route through the Hub. The admin app calls
    the service directly.
12. Route with the capability list, `routing.md`, and the LLM. Ask the user when
    unsure. Never route a control action.
13. Log every request. Append only. Cap the size. No secrets, no full personal
    data.
14. There is one identity: Sam. Keep the `asker` field for a future second person.

## Build order

0. **Agree the `/ask` contract.** Both sides build to `docs/ask-contract.md`.
   Nothing else starts until this is frozen.
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, against a fake project
   that speaks `/ask`. One real destination (speakers).
3. **Identity.** Decide how the Hub knows who is speaking.
4. **Approval flow.** "Did you ask for this?" on the admin app.
5. **One real data project** to the contract (email or school). Prove `/ask`.
6. **Internet control.** Separate service and portal. Control stays app-only.
7. **Artemis.** Separate service. Screen control only.
8. **Move Jervis's tools** into the Hub. Jervis becomes voice-only.
9. **Phone Kotlin app.** Wake word, voice to the Hub, replies and approvals.
10. **Remaining pipelines** 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 other projects.

Every other project is a **peer**. Each has its own folder, repo, port,
interface, and build. Each can be built and used without the Hub. The Hub is an
**extra** way in, not the only one.

| Project | Talk direction |
|---|---|
| Email agent | Hub asks it (`/ask`). It tells the Hub (`/notify`). n8n scans it. |
| Compass / NHS | Hub asks it (`/ask`). It tells the Hub (`/notify`). n8n scans it. |
| Internet use control | Hub **asks** it. **Control goes through its own apps, not the Hub.** |
| Artemis | Hub calls it to act. Nothing comes back. |
| Jervis | Becomes voice-only. Its tools move here. |
| dsh | Calls the Hub for actions. Keeps its own chat. |

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.