Add /ask contract; clarify peers, query vs control, identity gap

hub_brief.md

@@ -33,13 +33,16 @@ These stay. The hub is added, not a replacement.
 
 ## What is new
 
-- The **Hub** (this brief).
-- **Email agent** — its own pipeline.
-- **School (Compass / Teams)** — its own pipeline.
-- **Internet use control** — a destination the hub calls.
-- **Artemis** — a destination the hub calls.
-- **Kotlin phone app** — a new way in (wake word, voice, controls).
-- **Admin app + kids app** — parental control, admin only.
+Each of these is a **separate project**. Each has its own folder, repo, port,
+interface, and build. The Hub never owns them.
+
+- The **Hub** (this brief) — a shared way in and a router. Not a brain.
+- **Email agent** — scans and logs the inbox. Answers questions. Own pipeline.
+- **School (Compass / Teams)** — scans school data. Answers questions. Own pipeline.
+- **Internet use control** — its own service and information portal. Enforces limits.
+- **Artemis** — its own service. Operates the phone screen.
+- **Kotlin phone app** — a new way in (wake word, voice).
+- **Admin app + kids app** — control and confirmation, admin only.
 
 ---
 
@@ -57,6 +60,22 @@ The reply can be **text**, **spoken audio (TTS)**, **Artemis commands**, **a pho
 notification**, **an email**, or a mix. TTS can play on the **house speakers** or
 on the **phone**.
 
+When a question is about another project's data, the Hub **asks that project** and
+returns the answer. See `docs/ask-contract.md`.
+
+## Three directions
+
+Nothing here is ownership. These are directions of talk.
+
+1. **The Hub asks a project.** "What is important in my inbox?", "What does Harry
+   have on today?", "How long have the kids been on screens?"
+2. **A project tells the Hub.** "Overdue homework found.", "3 emails need a
+   decision."
+3. **n8n triggers the project.** Scan the inbox. Scan the school. Enforce the
+   schedule.
+
+The projects keep their own interfaces. The Hub is an **extra** way in.
+
 ### What the Hub is NOT
 
 - **Not a central brain.** It does not hold one personality or one memory.
@@ -77,22 +96,36 @@ One question sorts every request:
 **Paperclip is the work bench, not the switchboard.** It is never in the path of
 a fast or high-consequence command.
 
+### Query, command, or control
+
+| Kind | Example | Path | Confirm? |
+|---|---|---|---|
+| **Query** (read) | "What does Harry have on today?" | Hub → project (`/ask`) | No |
+| **Command** (do it now) | "Turn on the lounge light." | Hub → Home Assistant | No |
+| **Control** (high consequence) | "Cut the kids' internet." | Admin app → internet control | **Yes, on the phone** |
+
+A query goes through the Hub. A high-consequence control does **not**. The admin
+app talks to the internet control service directly. Voice may start it. Only the
+admin app confirms.
+
 ---
 
 ## Where each system fits
 
-| System | Role | With the Hub |
+Each project is a **peer**. These are talk directions, not ownership.
+
+| System | Relation | Talk direction |
 |---|---|---|
-| **Jervis** | House voice | Becomes the **voice** (speak / announce), not a list of tools. Its action tools move into the Hub over time. |
-| **dsh** | Chat | Calls the Hub for actions instead of keeping its own copies. |
-| **Console portal** | Login + dashboard | Unchanged. May show Hub status and approvals. |
-| **Front Door Cam** | Visitor intercom | Stays separate. May use the Hub only to speak. |
-| **Email agent** | Own pipeline (n8n) | Standalone. May report results through the Hub. |
-| **School agent** | Own pipeline (n8n) | Standalone. May report results through the Hub. |
-| **Internet control** | Destination | The Hub calls its API. Enforcement happens on the kids' devices. |
-| **Artemis** | Destination | The Hub calls its API. Artemis touches the phone screen. |
-| **Paperclip** | Work bench | The Hub files jobs and hears the answer back. |
-| **Phone app** | Way in | Sends voice to the Hub. Shows replies, notifications, approvals. |
+| **Jervis** | House voice. Peer. | Becomes voice-only. Its tools move into the Hub over time. |
+| **dsh** | Chat. Peer. | Calls the Hub for actions. Keeps its own chat. |
+| **Console portal** | Login and dashboard. Peer. | Unchanged. May show Hub status and approvals. |
+| **Front Door Cam** | Visitor intercom. Peer. | Separate. May use the Hub to speak. |
+| **Email agent** | Separate pipeline. Peer. | Hub asks it (`/ask`). It tells the Hub (`/notify`). n8n scans it. |
+| **School agent** | Separate pipeline. Peer. | Hub asks it (`/ask`). It tells the Hub (`/notify`). n8n scans it. |
+| **Internet control** | Separate service and portal. Peer. | Hub **asks** it. **Control goes through its own apps, not the Hub.** |
+| **Artemis** | Separate service. Peer. | Hub calls it to act. Nothing comes back. |
+| **Paperclip** | Work bench. Peer. | The Hub files jobs and hears the answer. |
+| **Phone app** | Way in. | Sends voice to the Hub. Shows replies and approvals. |
 
 ---
 
@@ -113,6 +146,9 @@ a fast or high-consequence command.
    exes may only obey and report.
 9. **New work registers with the Hub.** A capability is added once, and every way
    in gets it.
+10. **A data project answers `/ask` read-only.** It never changes state on a query.
+11. **High-consequence control does not route through the Hub.** The admin app
+    calls the service directly.
 
 ---
 
@@ -123,28 +159,40 @@ a fast or high-consequence command.
 - **A spoken keycode is not the lock.** It can be overheard and misheard. Voice
   may *ask*; the admin app **confirms** with "Did you ask for this?".
 - **Approval is required** for parental controls and Paperclip jobs.
+- **Identity is not solved yet.** Voice has no identity. Personal data (inbox,
+  school, screen time) needs it. See open items.
 
 ---
 
 ## 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, and get the result announced back. Proves the round trip.
-2. **Hub skeleton.** Hear → understand → route → answer, with one destination
-   (HA or speakers) working.
-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 and connect when ready.
+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.
 
 ---
 
 ## What is still open
 
-- Exact API contract for a job (title, brief, project, agent).
-- How Artemis receives voice (stream vs file) and when phone TTS is used.
-- Which Paperclip company / projects to use.
-- Identity: how the Hub knows which family member is speaking.
+1. **Identity.** How does the Hub know who is speaking? Voice has none. This is
+   the top gap, because personal data now flows.
+2. **Routing.** How does the Hub pick the project to ask? A small capability
+   registry, or an LLM choice.
+3. **Overlap.** "What do I have on today?" may match several projects. Ask one,
+   or ask all and merge?
+4. **Approval service.** One shared mechanism, or one per project?
+5. **Service tokens.** One bearer token per project, stored in `environment.d`.
+6. **Job contract.** Exact fields for a Paperclip job (title, brief, project, agent).
+7. **Artemis voice.** Stream or file. When does phone TTS get used?
+8. **Paperclip layout.** One company or several. Which projects.