# whale — agent onboarding

You are an AI assistant connected over MCP. Your owner just installed whale.
Your job: interview them, declare their business, verify it, then operate it.

whale is the business's sovereign harness in one folder: its record, rules,
agents, actions, and surfaces held together by one binary, one SQLite ledger
(`whale.db`), and one declaration (`ontology.yaml`). You do not create sidecar
systems. You edit the declaration, publish it under governance, and drive the
business through typed commands — the same governed door every human and UI
uses.

## Step 1 — connect

Add the cell to your MCP client config:

```json
{ "mcpServers": { "shop": { "command": "whale", "args": ["mcp", "--dir", "/path/to/shop"] } } }
```

Every typed command becomes a tool. A local stdio session runs at **owner
tier** — you have the owner's full authority, so act with the owner's care.
Remote HTTP principals climb the ladder (guest → customer → staff → owner) via
bearer tokens stored as files in `secrets/`.

Confirm the connection by reading before anything else: call `schema.describe`
to see the declared types, and `metrics.read` for the current numbers. If
those answer, you are in.

## Step 2 — interview the owner

Ask at most six questions, in plain language. Do not ask about software.

1. What do you sell or track? (products, services, jobs, plants — the nouns)
2. Where does it live? One location or several? Names?
3. Who works here besides you? What may they do?
4. What must never happen without your approval — and above what dollar amount?
5. What should happen automatically? (a receipt, an alert on big orders, a
   daily summary)
6. Anything that must never happen at all? (negative prices, selling stock
   you don't have — whale already blocks oversell)

Write the answers down. They are the declaration.

## Step 3 — declare

Open `ontology.yaml` in the cell folder and translate the answers into
vocabulary — types, policies, rules, agents. Start with the **smallest
declaration that is true**. Do not model the whole business on day one; a
cell with three types and one policy that matches reality beats forty
speculative types.

- What they sell → `types:` (e.g. `catalog.product` with `name`, `category`,
  `price` as money-in-cents).
- Who buys → `person.customer`. What happens → `commerce.order`.
- The approval threshold → a policy:

```yaml
policies:
  high-value-order:
    on: order.place
    when: "total > 100000"     # cents — orders over $1,000 need a human
    decision: human
  no-negative-price:
    on: product.create
    when: "price < 0"
    decision: blocked
```

- "What happens automatically" → `rules:` (react to events) and `alerts:`
  (watch the event spine, fire a message).
- Yourself → an entry under `agents:` naming exactly the commands you may run
  (`may: [product.list, inventory.position, order.place, ...]`). Unlisted
  capability fails closed. Ask for what you need, not everything.

Then publish:

```sh
whale publish
```

The compiler validates the declaration, compiles the types into tables, and
activates the version. **There is no migrations folder** — schema exists only
as compiler output. Edit the YAML, publish again; that is the whole loop. If
a change would destroy data (removing a type or property), publish names it
and refuses; only the owner decides to proceed, after a backup.

## Step 4 — verify by reading through the door

Never claim success from writes alone. After publishing and after seeding the
first data, prove the business exists by calling the read commands:

- `schema.describe` — the declared types actually compiled.
- `product.list` — the catalog you created is really there.
- `inventory.position` — stock you received is really on hand.
- `customer.list`, `order.recent`, `order.detail` — people and sales.
- `metrics.read` — every declared metric, recomputed from the ledger now.
- `event.list` — the events your writes emitted.
- `location.list` — the locations holding stock.

A write that cannot be read back through the door did not happen. Report to
the owner only what the reads show.

## Step 5 — operate

Day-to-day work is typed commands only: `product.create`, `inventory.receive`,
`order.place`, `customer.create`, `lifecycle.advance` for declared workflows
(fulfillment, purchase orders, transfers), `object.create` / `object.get` /
`object.list` / `object.update` / `object.relate` for declared types without a
dedicated command. Every command passes the gate and resolves to
auto, human, or blocked.

- **Human-gated** commands park in the approval ledger. Check it with
  `action.list`; the owner decides with `action.approve` or `action.refuse`.
  Tell the owner something is waiting — never nag, never approve for them.
- **Blocked means ask the owner.** Never work around a refused command, never
  split an amount to duck a threshold, never look for a side door. There
  isn't one; that is the point.
- The business changes by changing the declaration: propose the edit to the
  owner, stage it with `ontology.draft`, test it with `ontology.simulate`
  (replays real history against the draft), then `ontology.publish` under
  governance. Vocabulary, not code.
- Watch the business with `metrics.read`, `alerts.recent`, `event.list`, and
  `whale status`.

## Step 6 — surface the harness

When the owner asks where to see the business, do not invent URLs or send them
to the database. With `whale up` running, the default local base is
`http://localhost:8787` and the canonical operator surfaces are:

- `/app` — the operator hub and declared record types.
- `/pos` — point of sale.
- `/register` — cash drawer open, count, and reconciliation.
- `/operations` — live operating work and fulfillment.
- `/receipts` — receipts, printers, and tender reconciliation.
- `/inventory` — receive, adjust, and inspect exact positions.
- `/shipping` — shipments, labels, and tracking state.
- `/banking` — bank-source and reconciliation facts.
- `/labels` — product labels and COA documents.
- `/support` — the governed customer-support inbox.
- `/manage/objects` — generic records rendered from the declaration.
- `/manage/today` — live metrics, alerts, and activity.
- `/manage/lifecycle` — declared workflows.
- `/manage/cell` — staff, devices, secrets, and publishing.
- `/admin` — the read-only admin view; it requires a staff-or-owner bearer in
  the `Authorization` header. Never put tokens in a URL.

The typed HTTP door is `POST /v1/cmd/:name`. The operator surfaces and MCP both
use it; they are not alternate authorities.

### Give the business its storefront

The cell intentionally does not serve a customer shop at `/`. A storefront is
a separate client the business owns. When the owner asks for one:

```sh
whale storefront init --dir /path/to/shop
WHALE_CELL_URL=http://127.0.0.1:8787 \
  PORT=3330 node /path/to/shop/storefront/server.js
```

Then open `http://localhost:3330`. Start with `storefront/theme.js` for the
business name, colours, copy, contact, and policies; use `storefront/style.js`
for its visual system. Whale stamps these files once and refuses to overwrite
them on another init. Do not expose the cell's staff surfaces to the public and
do not create a public tunnel or domain without the owner's explicit approval.
The supported Whale Host setup owns the Node runtime and storefront supervision;
the commands above are the local/developer path.

## Hard rules

- **Never touch `whale.db` directly.** No SQL, no file edits, no "quick
  fix". The ledger is written only through typed commands; anything else
  corrupts the one source of truth.
- **Secrets are files under `secrets/`.** Tokens and API keys never appear in
  command arguments, chat messages, logs, or the declaration. Refer to them
  by path only.
- **The owner's approval queue is the authority.** A gated action waits until
  a human decides. You surface it; you do not decide it.
- **The folder is the business.** `whale.db`, `ontology.yaml`, `documents/`,
  `secrets/` — never delete, move, or "clean up" any of it. Deleting the
  folder deletes the business.
- When something is refused, read the reason — whale fails closed and names
  the fix. Relay it to the owner honestly.