Building on Thea

Ask, do not prompt

5 principles · eight lessons, a round after each, a boss round at the end

1. You send a question in plain language, signed, and you get back three things: a written answer, the rows it used, and a receipt.
2. You never write a prompt. There is no system message to tune, no temperature, no model to pick. The question is the whole input.
3. The same question on the same data returns the same answer. If it does not, something changed in the data, and the receipt will show you what.
4. A follow-up is a follow-up. "Tell me more about that figure" reaches for the figure you were just shown, not for a fresh guess.
5. When a question could mean two things, you get a question back, not an answer to one of them. Answer it and ask again.

Declining beats guessing

5 principles · eight lessons, a round after each, a boss round at the end

1. An answer that cannot be traced to rows is not given. You will see a refusal with a reason instead.
2. A refusal is not an outage. It is the system telling you what it would need in order to answer, and the reason names the next step.
3. Build your screen so a refusal reads as what it is. A blank panel, a spinner that never stops, or a made-up default is the one thing you must never show.
4. If you find yourself writing code to "fill in" a number the answer did not contain, stop. That number would be indistinguishable from a real one.
5. The best demo of the system is typing something odd and watching it refuse out loud.

Every figure comes from the connected system

5 principles · eight lessons, a round after each, a boss round at the end

1. The only step that may produce a number is the read from your own system of record. Nothing understands, estimates or remembers a figure into existence.
2. Your data is read through your own connection, with your own credentials, and where your system applies a user's permissions, they are applied as that user. Thea does not re-implement them.
3. A figure you cannot map to a field in your system is a promise you cannot keep. Map the field first; then promise the figure.
4. Nothing is migrated. Your system stays in charge of its data; Thea reads and hands back.
5. When your procedure changes and nobody says so, the answers keep coming from what was true before. Everything carries a source, so the staleness is findable, but somebody still has to look.

Keep the receipt

5 principles · eight lessons, a round after each, a boss round at the end

1. Every answer carries a receipt: what was asked, what was read, what was computed, and who judged the result. Store it with the answer.
2. Receipts chain. A year later you can verify the whole chain and prove that what you showed a person is what the system said at the time.
3. Verify chains from the first entry to the last. One page of a chain is a window, not the chain; a partial walk always looks clean.
4. A refused request also carries a receipt: the fingerprint of the question and of the refusal, so a "we asked and it declined" is provable too.
5. The receipt is your audit story. Build the screen that shows it before the screen that hides it.

Stay connected

5 principles · eight lessons, a round after each, a boss round at the end

1. Anything you deploy works only while it is connected to the Thea API. There is no offline mode, and a copy that keeps working with the cable pulled has taken something it was not sold.
2. A deployment holds a lease: a short-lived grant it renews itself, in the background, long before it lapses. You do not manage it by hand.
3. When a lease lapses the deployment says so on its own surface — "this installation is not connected; reconnect to continue" — and refuses substantive requests until it is. It never degrades silently.
4. Your data stays in your tenancy. The reasoning happens on the other side of the wire. Both are true at once, and that is the point.
5. The connection is also what makes usage meterable, which is what makes the price honest.

Know what it may read

4 principles · eight lessons, a round after each, a boss round at the end

1. There are four settings, and you decide them before you build: structured (your tables), unstructured (your documents), trusted outside sources, or a closed ecosystem with nothing from outside at all.
2. A trusted source is a named list with an owner, a review schedule and a rule for what happens when it is wrong. It is never "the internet" and it is never a forum.
3. A number from a comment thread and a number from a statistics office look exactly the same once they are inside. The only place to tell them apart is the list you wrote before they came in.
4. Closing the ecosystem changes what a build is allowed to do, not just where it sits. Decide it early.

The meter

5 principles · eight lessons, a round after each, a boss round at the end

1. Usage is metered in Thea Tokens, a deterministic unit computed from the shape of the work — how much was asked, how much was answered, how wide the read was — never from any model provider's token count.
2. Every answer and every refusal carries its meter in the response headers: what it cost, and what it saved against market. Read them; reconcile against them.
3. Any tokens your own language-model provider reports are yours to pay that provider for. They are shown for visibility and never added to Thea Tokens.
4. The billed amount is a fixed fraction of the implied market value of the work. The fraction is public; the anchors behind it are not yours to know.
5. A price change is a new version of the rate table, dated, never an edit to an old one. Your history reconciles forever.

Speak the app in the language of the business

6 principles · eight lessons, a round after each, a boss round at the end

1. An app is specified by saying, in the business's own words: who it serves and what they get; which of five personas it is (educator, assistant, role support, models, reports); which sector it sits in; and the keywords it must know.
2. The sector is not decoration. It chooses the regulation the app sits under, the vocabulary it must cover, and which outside sources count as trusted.
3. Each keyword is a piece of knowledge the app has to hold. Coverage is measured against them before a single answer is shown, and the gaps are recorded in the app rather than discovered by a user.
4. Be able to draw one real question crossing the whole app: understood, located, fetched, calculated, judged. If you cannot draw it, the app is described, not specified.
5. The questions nobody has settled — what it may answer without a human, who sees which data, what happens when it cannot answer — are part of the specification. Name them before the build, not in month four.
6. An app is not real until it is registered, and it is not live until a person decides to publish it. A page with no record is a demo.

Coach with a next step

4 principles · eight lessons, a round after each, a boss round at the end

1. Every refusal your app shows should carry the next step in the user's own words: what to add, what to connect, who to ask.
2. Do not explain how the system decided. Explain what the user can do now. The first is not yours to give; the second is the whole job.
3. Point people at the lesson, not at the internals. The developer school exists so that "why did it refuse?" always has a place to go.
4. A business lead and one integration person are the useful first pair. The business lead drives the specification; the developer owns the connection and anything that writes back.

Measure before you claim

5 principles · eight lessons, a round after each, a boss round at the end

1. Empty and unreadable are different facts. Absence is not failure, and a read that failed is not "no rows".
2. A number that never changes is a window that never moved. Check the window before you theorise about the number.
3. "Live" is reach, not relevance. That something answered proves it was reachable, not that it was right.
4. Before you build a thing, ask whether the platform already does it. It usually does, and the answer is a route, not a feature request.
5. Verify the path from the door to the effect, not the presence of the code. Wiring that goes nowhere is the commonest defect in software that looks finished.

Build an app

7 principles · eight lessons, a round after each, a boss round at the end

1. You do not write the app first. You say it first: who it serves and what they get; which persona; which sector; the keywords it must know; what it may read; the question you would type on day one.
2. That brief is the whole input. The platform plans from it — persona, sector, the blocks it will be built from, the connectors it needs — and seals a receipt for the plan.
3. A plan comes back with its open decisions listed. Those are not gaps in the platform; they are the questions your business has not answered yet. Answer them and plan again.
4. A brief too thin to plan from is declined, with the reason. Say who uses it, what they do with it, and the sector, and it will plan.
5. A plan that is not in the roster does not exist. Read the roster back and find yours before you show anyone a screen.
6. The platform never publishes. A person does, and the record says who.
7. A page with no record behind it is a demo. Nothing wrong with a demo, as long as it is called one.

Talk to it

6 principles · eight lessons, a round after each, a boss round at the end

1. A conversation is a sequence of signed questions with a shared session. The platform keeps the turns; you do not resend the history.
2. "Tell me more about that figure" reaches for the figure it just showed you. "The previous answer" is the previous answer. A party named earlier stays the party until you name another.
3. "How did you get that?" is answered in five steps — understood, located, fetched, calculated, judged — and every step names what it used.
4. A follow-up that cannot be resolved against the session is answered with a question, not with a guess about what you meant.
5. Every turn carries its own receipt and its own meter. A conversation is a chain of them.
6. Build the ask box so a person can keep going. One question per screen, the answer where they are looking, the next question a keystroke away.

Asking a question

2 routes

• GET /v1/health — Liveness check
• POST /v1/query — Ask a question

Your workspace: usage, roles, readiness

14 routes

• GET /v1/workspaces/{workspaceId}/renderer/{provider}/credentials — Is a renderer key set
• POST /v1/workspaces/{workspaceId}/renderer/{provider}/credentials — Set a renderer key
• DELETE /v1/workspaces/{workspaceId}/renderer/{provider}/credentials — Remove a renderer key
• GET /v1/workspaces/{workspaceId}/adapters/{adapterType} — Read an adapter's configuration
• PUT /v1/workspaces/{workspaceId}/adapters/{adapterType} — Set an adapter's configuration
• PATCH /v1/workspaces/{workspaceId}/adapters/{adapterType} — Update part of an adapter configuration
• GET /v1/workspaces/{workspaceId} — Read a workspace
• PATCH /v1/workspaces/{workspaceId} — Change a workspace setting
• GET /v1/workspaces/{workspaceId}/roles — List workspace role definitions
• POST /v1/workspaces/{workspaceId}/roles/{slug} — Create a workspace role definition
• PATCH /v1/workspaces/{workspaceId}/roles/{slug} — Update a workspace role definition
• DELETE /v1/workspaces/{workspaceId}/roles/{slug} — Delete a workspace role definition
• GET /v1/workspaces/{workspaceId}/usage — Usage for a workspace
• GET /v1/workspaces/{workspaceId}/usage/events — Itemised usage events for a workspace

Connecting your system

4 routes

• POST /v1/workspaces/{workspaceId}/adapters/{adapterType}/test — Test a connection
• GET /v1/workspaces/{workspaceId}/adapters/health — Read scheduled connector health
• GET /v1/workspaces/{workspaceId}/adapters/{adapterType}/credentials — Check whether a credential is stored
• POST /v1/workspaces/{workspaceId}/adapters/{adapterType}/credentials — Store or rotate a credential

Workspaces

1 route

• GET /v1/workspaces/{workspaceId}/readiness — Check whether this workspace can answer questions about your data

Your own atoms

3 routes

• GET /v1/atoms — List data-source definitions
• POST /v1/atoms — Add or update a data-source definition
• DELETE /v1/atoms/{atomId} — Soft-delete a data-source definition

Receipts and the seal

3 routes

• GET /v1/receipts — List receipts
• POST /v1/audit/seal — Get a receipt anchor
• POST /v1/audit/verify — Verify a chain

The lease routes: issue and verify

2 routes

• POST /v1/lease — Issue a lease to an installation
• POST /v1/lease/verify — Verify a lease

Memory

3 routes

• GET /v1/memory — List memory items
• POST /v1/memory — Store a memory item
• DELETE /v1/memory/{key} — Delete one memory item

Keys

4 routes

• GET /v1/keys — List API keys
• POST /v1/keys — Issue another API key
• POST /v1/keys/{keyId}/rotate — Rotate a key secret
• POST /v1/keys/{keyId}/revoke — Revoke a key