sam/central_ai_llm_master
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Sam Rolfe
2026-10-10 15:46:49 +11:00
parent b3658132dd
commit a6d4d26b89
6 changed files with 286 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/outline/00-index.md
View File

@@ -13,6 +13,7 @@ Read this index to inject the exact file you need. Do not search all files.
| **Configuration & Env** | `docs/outline/02-config-and-env.md` | Lists services, ports, env vars, and secret paths. |
| **Code Structure Map** | `docs/outline/03-code-map.md` | Shows the planned folder layout and entry points. |
| **AI Agent Runbook** | `docs/outline/04-agent-runbook.md` | Gives steps to build, test, and restart Hub work. |
| **Ask Contract** | `docs/ask-contract.md` | The interface between the Hub and every data project. |
| **Design Brief** | `hub_brief.md` | The agreed design. This file is the source of truth. |
| **Project Rules** | `AGENTS.md` | Mission, rules, build order, and project relations. |

45
docs/outline/01-system-overview.md
View File

@@ -18,6 +18,17 @@ way in, the phone app, would repeat the same work. The Hub stops this repeat.
4. **Route** — send the request to one destination.
5. **Answer** — return a short reply in the right shape.
When the question is about another project's data, step 4 asks that project
through the `/ask` contract. See `docs/ask-contract.md`.
## Three Directions
Nothing here is ownership. These are directions of talk.
1. The Hub asks a project.
2. A project tells the Hub.
3. n8n triggers the project.
## Ways In
- Phone app (Kotlin) — wake word, voice, controls.
@@ -26,17 +37,32 @@ way in, the phone app, would repeat the same work. The Hub stops this repeat.
- dsh chat — per-person chat.
- Console portal — web dashboard.
## Destinations
## Peers and Destinations
| Destination | Job |
Every other project is a peer. Each has its own folder, repo, port, and
interface. Each works without the Hub.
| Peer | Talk direction |
|---|---|
| Home Assistant | Lights, switches, timers, calendar. |
| Speakers (Jervis) | Speak and announce. |
| Internet control | Parental limits on kids' devices. |
| Artemis | Operate the phone screen. |
| Paperclip | Slow, multi-step, recorded work. |
| Web search | Tavily search. |
| Apprise / NTFY | Notifications and email. |
| Email agent | Hub asks it. It tells the Hub. n8n scans it. |
| Compass / NHS | Hub asks it. It tells the Hub. n8n scans it. |
| Internet control | Hub asks it. Control goes through its own apps. |
| Artemis | Hub calls it to act. Nothing comes back. |
| Home Assistant | Hub calls it to act. |
| Speakers (Jervis) | Hub calls it to speak. |
| Paperclip | Hub files jobs. The answer returns. |
| Web search | Hub calls it. |
| Apprise / NTFY | Hub calls it to notify. |
## Query, Command, or Control
| Kind | Path | Confirm |
|---|---|---|
| Query | Hub asks a project (`/ask`) | No |
| Command | Hub calls Home Assistant | No |
| Control | Admin app calls internet control | Yes, on the phone |
A high-consequence control does not route through the Hub.
## Reply Shapes
@@ -57,3 +83,4 @@ The Hub asks one question: does this need a decision, or does it need to happen?
- Not a central brain. No single personality or memory.
- Not Paperclip. The Hub does not wait minutes for an answer.
- Not a destination. The Hub does not turn off the internet itself.
- Not an owner. The other projects are peers, not sub-projects.