# 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.

## 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

Ask these no matter who you are working with. An engineer wiring a backend has most of the answers already; someone starting cold has none of them, and you are going to find them together.

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.

## 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 — a Brain that stages every write answers nothing on its first day: `{"name":"…","mode":"open"}`.

Bringing your own model, declare what you filter on and nothing else: `{"name":"…","mode":"reviewed","schema":{"extends":"nicia-core","kinds":[{"name":"company","fields":[{"name":"plan","type":"string"},{"name":"ownerEmail","type":"string"}]}]}}`. 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, so there is nothing to gain from inventing a schema before there are records to filter.

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.** Ask five to ten questions about what the team keeps re-explaining: who owns what, which decisions keep getting relitigated, what a new hire always gets wrong. 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 to filter on something.

## 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. 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.
3. Offer review when it starts to matter: `PATCH /v1/brains/{handle}` with `{"mode":"reviewed"}`, typically as soon as an agent nobody on the team wrote starts producing knowledge, or a customer will see the answers.

## Success checks

- Provisioning the same handle twice addresses one Brain.
- An inline `company` schema declaring `plan` and `ownerEmail` makes those fields queryable without changing the source-of-truth records.
- 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.
- 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`.