# Concepts and the laws that bind config

## Contents
- Words (one meaning each)
- How a stream runs
- The laws, and what each means for a config file
- Old names you will see in files

## Words

| Word | Means | In files |
|---|---|---|
| **Streamliner** | A white-label iPhone, iPad and Mac app: business processes as chats. | — |
| **Account** | An **organisation** (a company; members sign in, config is published by the owner) or a **personal** account (one person's own streamlines on their device). | `tenant.json`, `mode` |
| **Streamline** | A department's desk: one preset agent with its persona, tools, look and rules. Register, Approvals, Receiving. | an agent *kind*: `agents/<kind>.json` + `private/agents/<kind>.json` |
| **Stream** | One conversation in a streamline = **one job** (one sale, one PO, one offer). | a *chat*: `chat.set`, `chatTitle`, `newChatLabel` |
| **Connection** | One system a person signs in to, as themselves (OAuth, password, API key, none). | `connections[]`, `mcp[].connection` |
| **MCP server** | The organisation's own API, exposed as Model Context Protocol tools. The agent calls it **as the signed-in person**. | `mcp[]` |
| **Model relay** | Streamliner's back end that forwards an organisation's model calls: holds the provider key (by `credentialRef`), the private instructions, the tool allowlist, membership, network and budget checks. | `private/` files |
| **Template** | A small JSON tree of native views bound to a tool's result. Display only. | `templates/<id>.json` |
| **Sealed form / view** | A native form whose values go device → organisation endpoint, never to the model; a view that shows sensitive data without the model seeing it. | `forms/<id>.json` |
| **Owner / admin / member** | Access levels on a membership (who may manage the account). Separate from job **roles** (who may open which streamline). | invites, directory `access` |
| **Server key** | An Ed25519 key pair the **account** holds for automation (publishing, directory sync). Never an employee's sign-in. | `private/tenant.json` `serverKeys` (public half) |
| **Publisher key** | The Ed25519 key that signs the manifest. Devices pin it at enrolment; the back end never holds it. | `enrolment.json` `keys` |

## How a stream runs

1. The person opens a stream in a streamline and types (or taps a starter, a quick phrase, a scan).
2. The agent loop **runs on the device**. Model calls go to the model relay (organisations) or straight to the
   provider with the person's own key (personal accounts).
3. Tool calls go **device → the organisation's MCP server** with the person's own credential for that connection.
4. Results come back as `content` (what the model reads), `structuredContent` (what a template draws) and
   optional directives in `_meta["com.manolab.streamline/ui"]` (draw this card, refresh the overview, remember this
   id, end the job).
5. A confirm-gated tool waits for the person's tap on a confirmation card before it is sent.
6. A completing tool ends the job with a banner; the next stream is a new job.

## The laws, and what each means for config

1. **The enterprise configures, the employee converses.** Config decides persona, tools and look; the person never
   edits an organisation's streamline on the device.
2. **Every stream is one job.** Design each streamline around one repeatable job with an end (a completing tool).
   Refuse "a general assistant for everything": that is a different product.
3. **The API is the security boundary and the rulebook.** Price floors, approval limits, who may see what: the
   organisation's API enforces them for every call, as the signed-in person. Instructions are guidance, never a
   rule anyone relies on. The app's gates are UX; the API is the lock.
4. **Secrets never touch the model.** No SSN, date of birth, licence number, card number, password or API key in a
   prompt, an instruction, a tool argument, a transcript, a log or a test fixture. Sensitive input goes through a
   sealed form; card numbers through the processor's hosted page or the store's terminal. Provider keys are named by
   `credentialRef`, never written into config.
5. **Confirm before the irreversible.** Anything that moves money, completes a job or can't be undone is
   confirm-gated, with a read-only preview of the real state.
6. **Data, never pixels.** Servers send JSON; templates draw it natively. No HTML, CSS or scripts in config.
7. **Nothing client-specific is compiled in.** Everything an account needs is in its config folder.
8. **Fast feels honest.** Small, determined actions (pick a search result, scan a tag) can be `direct`: a button
   calls the tool with no model round trip.
9. **The cheapest model that can do the job.** Start desks on the smallest model; move up only on evidence.
10. **The agent says what it did.** Success is drawn only from tool results, never from the model's prose.
11. **A form when it is the honest tool.** Ask in the stream for ordinary data; use a form for secrets.

## Old names you will see in files

The prose says streamline / stream / account; the file format keeps its first names until a coordinated rename:
`kinds[]` and `agents/<kind>.json` (streamlines), `chat.*` (stream state), `tenant.json` and `t/<tenant>/`
(account), `gateway.url` (the back end's base URL), `user-token` (older spelling of `oauth` by token exchange).
Write the names exactly as the schema has them.