# Import your team's work into a Brain

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

This is a single bootstrap procedure for a coding agent working on a person's machine, not an installable Agent Skill. It populates a Brain, which is the system of record for what a team knows: decisions, standards, current answers. It is not a system of record for operational data. Invoices stay in the accounting system and deals stay in the CRM.

The source can be a folder of markdown, a wiki export, or a docs directory in a repo. It can also be Notion, Google Drive, Confluence, or Slack: if you already hold the person's credentials for those tools, you are the connector. Read from them directly and populate the Brain the same way.

**This reads. It never writes back.** Nothing in the source is modified, moved, or deleted, no sync is established, and no credential of ours touches their systems. What you produce is a copy, which makes this a cheap thing to try and a cheap thing to abandon.

**A copy has a shelf life.** While the team keeps authoring in the old place, the Brain drifts away from it and the answers get worse. Tell the person this plainly: run both for a week or two, compare the answers, and then decide whether the Brain becomes the place they write. That cutover is their decision and their moment, not a side effect of running this.

If they have nothing written down yet, or you are adding Brains to a product you ship, or you are migrating Brains from somewhere else, stop here and use [the build procedure](https://nicia.ai/build.md).

## Decide whether to act, ask, or stop

- **Act:** one source root and a stable Brain handle are clear. Start with a faithful filesystem import; do not redesign the person's folder first.
- **Ask:** choosing between source roots, handles, or privacy scopes would materially change the result. Ask exactly one concise question and wait.
- **Stop truthfully:** the source cannot be read, credentials are unavailable, or the material is operational data rather than organizational knowledge. Name the blocker and the smallest recovery step. Never choose a folder silently, skip an unreadable entry, or invent missing text.

## Read in this order

1. [Bring your knowledge](https://nicia.ai/docs/team/bring-it/)
2. [Authentication](https://nicia.ai/docs/start/authentication/)
3. [Brain keys](https://nicia.ai/docs/scale/brain-keys/)
4. [Review](https://nicia.ai/docs/govern/review/)
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/) and [generated OpenAPI JSON](https://nicia.ai/docs/openapi.json)
7. [llms.txt](https://nicia.ai/llms.txt) and [llms-full.txt](https://nicia.ai/llms-full.txt)

## Runnable filesystem import

This is the same preview → confirm → durable import pipeline used by **New Brain → Bring existing knowledge** in the app.

1. Resolve the source root, Brain display name, and Brain handle. Use a stable, lowercase, human-meaningful handle such as `revops` or `support`; do not derive it from a directory name that may be renamed. Confirm the root and handle out loud before writing anything.
2. Enumerate the source without modifying it. Account for every entry as included, unsupported, ignored, unreadable, or failed. Create a temporary ZIP whose paths are relative to the confirmed root. Exclude `.git`, dependency caches, secrets, and files the person did not authorize. Delete the temporary ZIP in cleanup.
3. Provision the empty Brain with `PUT https://api.nicia.ai/v1/brains/{handle}`, sending `x-api-key: $MANAGEMENT_KEY`, `x-organization-id: $ORGANIZATION_ID`, and `{"name":"…","mode":"open"}`. Repeat the same request safely after a timeout. Record the returned `brain.id`; the importer uses the opaque id while the person keeps using the stable handle.
4. Preview the exact archive with multipart `POST https://api.nicia.ai/v1/knowledge-bundles/import-markdown?knowledgeGraphId={brain.id}`, sending the same two management headers and one form part named `file`. This commits nothing. Read `data.importMarkdown.jobId` and `data.importMarkdown.proposal`. Show the person page count, folders, links, malformed frontmatter, attachments, unsupported paths, and skipped entries. Do not continue until they confirm.
5. Commit the proposal with `POST https://api.nicia.ai/v1/knowledge-bundles/import-markdown/{jobId}/commit`, the management headers, and JSON containing the proposal's `flavor`, `corpusSlug`, and `corpusName`, plus `typeMappings` mapped to `{ "folder": "…", "kind": null }`. Filesystem import preserves evidence; it does not guess a schema.
6. Poll `GET https://api.nicia.ai/v1/knowledge-bundles/import-markdown/{jobId}` with the management headers until `succeeded`, `partial`, `failed`, or `cancelled`. A `partial` import is usable but not complete: report every conflict, unsupported path, skipped file, unresolved link, and indexing failure from the receipt. Retry only through the documented retry operation; never hide a partial result behind a success message.
7. Mint one Brain key with `read` and `write`, then verify with `POST https://api.nicia.ai/v1/brains/{handle}/context`. Confirm at least one citation and a receipt, and read the cited source path back to the person.
8. Only now offer to turn Review on with `PATCH https://api.nicia.ai/v1/brains/{handle}` and `{"mode":"reviewed"}`. Recommend it before an agent the team did not write starts proposing knowledge. Offer [the sharing guide](https://nicia.ai/docs/team/share-it/) next.

For Notion, Drive, Confluence, or Slack, first materialize the authorized pages into a temporary markdown tree with stable source ids and original URLs in frontmatter, then run this same importer. The source system remains read-only and no sync is implied.

## Success checks

- Running the same confirmed archive twice produces unchanged receipt entries, not duplicate pages.
- A `POST /context` question returns an answer with at least one citation and a receipt id.
- Nothing in the folder was rewritten, moved, or deleted.
- Every source entry is accounted for; there is no silent skip bucket.
- Ambiguous input produces one clarification question. Inaccessible or out-of-bounds input produces a truthful blocker and recovery step.

## Report back

Tell the person the Brain handle, the number of documents imported, the one question you verified with, and the exact citation it returned. If anything failed validation, name the file and the error rather than skipping it silently.

Then say the two things they need to decide next. First, that this is a copy until they choose to cut over, and that comparing answers for a week or two is the way to make that call. Second, that their knowledge is never captive: exporting a Brain returns plain markdown with their frontmatter intact, a catalog, a greppable activity log, the full revision history, and an `AGENTS.md` that teaches any agent how to read it. They arrived with a folder; they leave with a model. See [keeping it good](https://nicia.ai/docs/team/tend-it/).