# Build with Nicia

Agents don't need memory. They need a Brain.

This is a single bootstrap procedure for a coding agent, not an installable Agent Skill. Use it to stand up Brains for the first time, to migrate Brains you keep somewhere else, or to add per-customer Brains to a product you ship. Nicia becomes the system of record for what you know about each tenant. It does not replace the database that owns your tenants, your customers, or your billing.

If the person already has their knowledge in a folder, a wiki export, or pages in Notion or Drive and simply wants it moved, use [the import procedure](https://nicia.ai/import.md) instead.

## Choose the execution context

- **Inside the Nicia Brain Agent:** do not provision another Brain or ask for API credentials. You are already bound to the new Brain. Follow the discovery and Path A rules below with your `knowledge_*` tools. On a reviewed Brain, most agent writes stage for Review; on an open Brain, ordinary writes land and destructive changes still wait. Whenever a write stages, tell the person exactly what is waiting in Review.
- **On the person's machine:** follow the HTTP sequence below. Use only credentials the person supplies through environment variables. Never ask them to paste a secret into chat or write one into their repository.

## Read in this order

1. [Docs overview](https://nicia.ai/docs/)
2. [Detailed activation guide](https://nicia.ai/docs/start/add-a-brain/)
3. [Start with your agent](https://nicia.ai/docs/start/with-your-agent/)
4. [Authentication](https://nicia.ai/docs/start/authentication/) and [Brain keys](https://nicia.ai/docs/scale/brain-keys/)
5. [Errors](https://nicia.ai/docs/api/errors/) and [idempotency](https://nicia.ai/docs/api/idempotency/)
6. [Scalar API reference](https://nicia.ai/docs/reference/)
7. [Generated OpenAPI JSON](https://nicia.ai/docs/openapi.json)

## Discovery, before you call anything

Resolve these before you create anything. Use facts already present in the request or source material. Ask only for what is missing, one concise question at a time; do not force a person through a four-question form when their request already answers it.

1. **What is this Brain for, in one sentence?** A Brain holds what an organization **knows**: decisions, standards, current answers. It is not a store for operational data. If what they describe is invoices, deals, or ledger rows, say so and stop.
2. **How many Brains?** One for the team, or one per customer, project, or employee. If it is one per customer, the handle is `tenant:${stableTenantId}` using a stable non-human id, never a mutable display slug.
3. **What already exists?** A database of records, a pile of documents, or nothing at all. This decides which path below you take.
4. **Who will be trusted to change it?** People, your own pipeline, agents you did not write, or your end customers. This decides whether the Brain runs `open` or `reviewed`.

Confirm the handle out loud before creating anything. It is permanent and every future call addresses the Brain by it.

### Decide whether to act, ask, or stop

- **Act:** the purpose, scope, and trustworthy source are clear enough to create the first useful page or record. Start; do not ask for an exhaustive plan.
- **Ask:** one missing fact would materially change the Brain you create. Ask exactly one question and wait.
- **Stop truthfully:** the request is for operational rows rather than knowledge, the required source or credential is unavailable, or the source is too ambiguous to represent without invention. Name the blocker and the smallest thing the person can provide. Never manufacture a plausible answer to keep the procedure moving.

## Create the Brain

Call `PUT https://api.nicia.ai/v1/brains/{handle}` with `x-api-key: $MANAGEMENT_KEY`, `x-organization-id: $ORGANIZATION_ID`, and a body. Repeat the same request safely after a timeout.

Starting cold, keep it minimal and open — ordinary writes are admitted by default, while destructive changes still wait for approval: `{"name":"…","mode":"open"}`.

Bringing your own model, declare fields whose meaning you want governed and returned: `{"name":"…","mode":"reviewed","schema":{"extends":"nicia-core","kinds":[{"name":"company","fields":[{"name":"plan","type":"string"},{"name":"ownerEmail","type":"string"}]}]}}`. Declaration preserves and describes those values; it does not make arbitrary fields queryable yet. Today `/query` resolves exact `slug` equality only; predicates on `plan`, `ownerEmail`, or any other non-slug field return `400 index_not_ready`. Kept inline and compact on purpose: this payload must stay byte-identical to the one in [the activation guide](https://nicia.ai/docs/start/add-a-brain/), and a fenced block gets reflowed by the formatter.

Do not guess at an ontology. Undeclared keys are stored and round-trip, and declaring a field later is retroactive for returned/governed shape. There is nothing to gain from inventing a schema before there are records to hold — and declaration still does not unlock non-slug `/query` filters until a property index ships.

Then mint keys with `POST https://api.nicia.ai/v1/brains/{handle}/keys`: a sync key with `write` and `review`, and an agent key with `read` and `write` but never `review`. Each secret is returned once, so store it on receipt. Use the management credential only from a backend, with both `x-api-key` and `x-organization-id` on management-plane requests.

## Path A — nothing is written down yet

1. **Interview, do not invent.** Work toward five to ten useful answers about what the team keeps re-explaining: who owns what, which decisions keep getting relitigated, what a new hire always gets wrong. Ask one question at a time and write down their answers, not your own guesses. If you do not know something, leave it out rather than filling it in.
2. Write each answer as a document with `POST /v1/brains/{handle}/documents`, one subject per document, using a deterministic id derived from its title so a second pass updates rather than duplicates.
3. Skip the schema entirely for now. Revisit it once they want governed typed fields on records (filtering non-slug fields still waits on a property index).

## Path B — your product already owns the data

1. Sync application-owned records with deterministic ids. Use `PATCH /v1/brains/{handle}/records/{id}` for addressed merges; use `POST /v1/brains/{handle}/batch` with a stable `Idempotency-Key` for atomic groups.
2. When a reviewed sync response returns a `change` id, approve only `POST /v1/brains/{handle}/changes/{changeId}/approve` using the review-capable sync key. Do not scan the queue.
3. Add non-empty, deterministically addressed documents with `POST /v1/brains/{handle}/documents`. Documents provide cited context independently of arbitrary custom-kind extraction. Empty record or source collections are successful no-ops; an empty document or malformed request fails validation, and no empty input implies deletion.
4. If you are migrating Brains from somewhere else, treat the old store as read-only for the whole migration and cut over deliberately once the answers match. Running both as writers is how two stores start disagreeing.

## Verify, both paths

1. Query typed state with `POST /v1/brains/{handle}/query`; request prompt-shaped context with `POST /v1/brains/{handle}/context`; pass through citations and the receipt. Read one citation back to the person by name.
2. Before testing an agent write, switch to reviewed mode: `PATCH /v1/brains/{handle}` with `{"mode":"reviewed"}`. Offer review when it starts to matter, typically as soon as an agent nobody on the team wrote starts producing knowledge, or a customer will see the answers.
3. Have an agent submit a write with its agent key. Confirm the write is staged, accepted state is unchanged, and the agent key cannot approve it. Settle the exact change later with the sync key or a human.

## Success checks

- Provisioning the same handle twice addresses one Brain.
- An inline `company` schema declares `plan` and `ownerEmail`, but only the record slug is queryable today; a non-slug predicate returns `400 index_not_ready`.
- Replaying a batch with the same idempotency key creates no duplicate change.
- A document contributes a citation to `/context`.
- A typed query returns the synced record after settlement.
- An agent write is staged and an agent-key approval returns `403 forbidden`.
- Empty record or source collections are successful no-ops. Empty documents and malformed requests fail visibly without partial state; missing sync rows never imply deletion.
- On Path A, every page traces to something the person actually said.
- A vague request produces one material clarification question, not guessed content or a questionnaire.
- An out-of-bounds or inaccessible request stops with a concrete blocker and recovery step.
- Test credentials are revoked in cleanup, even if Brain deletion reports an error.

## Recovery rules

- Retry only `429` and `5xx`; honor `Retry-After` and cap attempts.
- Repeat a timed-out addressed write at the same address. Repeat a batch with the same idempotency key.
- Stop on other `4xx` responses and report the parsed error and request id.
- An empty source collection is a successful no-op. An empty document is validation failure.
- If a one-time key secret was lost, do not expect replay to return it; rotate or mint a replacement and revoke the old key.

## Report back

Give the Brain handle, what you created or synced, and the one question you verified with, quoting the citation it returned. Then say their knowledge is not captive: exporting a Brain returns plain markdown with frontmatter, a catalog, a greppable activity log, the full revision history, and an `AGENTS.md` that teaches any agent how to read it.

Machine-readable companions: [llms.txt](https://nicia.ai/llms.txt), [llms-full.txt](https://nicia.ai/llms-full.txt), [OpenAPI JSON](https://nicia.ai/docs/openapi.json), [API reference](https://nicia.ai/docs/reference/). `/skills` is reserved for future directories containing `SKILL.md`.