> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tatara.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

> Brains, documents, folders, titles and slugs, wikilinks, tags, and deletion: the rules that govern how a Tatara brain is structured.

## Brains

A brain is the container for one company's knowledge. Every document, folder, and tag belongs to exactly one brain.

Your workspace is the account your teammates and billing belong to. It contains exactly one brain, created when you first sign in and name it. There is no brain switcher and no way to create a second brain. An account belongs to only one workspace.

The same boundary applies to agents. An agent is scoped to the brain of the account whose credential it holds, and it cannot address another one. No tool takes a brain as an argument. Connecting an agent to your workspace gives it your brain and nothing else.

## Documents

A document is a title and a body, plus a small set of fields that make it findable later:

* **Owner**: the person a document is assigned to. Set in the app only; no agent tool reads or writes it.
* **Type**: a free-form label for what kind of document this is, such as `spec`, `decision`, or `research`. Types are not a fixed list; a brain's types are whatever its documents have used.
* **Tags**: up to five flat labels. See [tags and the taxonomy](#tags-and-the-taxonomy).
* **Description**: one plain sentence saying what the document is. It is what an agent sees when listing documents, and it often decides whether the agent opens the document at all.
* **Folder**: where the document lives.
* **Created and updated timestamps**, maintained for you.
* **Custom frontmatter**: any other keys the document carries.

Descriptions and tags are optional when you write in the app. They are required when an agent writes over MCP: an agent-created document must carry a description and one to five tags.

Every document is one of two file types: markdown or HTML. Almost everything is markdown. A document body may be up to 5 MB. A markdown document can also declare a render format, which turns it into a board, a tracker, a table, or a saved view instead of prose. See [Document formats](/formats/overview).

<Note>
  There is no status field. Tatara has no draft, published, or archived state, and nothing is hidden from search or listing because of where it sits in a lifecycle. A document either exists in the brain or it does not.
</Note>

### The four universal keys

Four fields are universal. Every document has them, and they mean the same thing in every brain:

| Key           | What it holds                          |
| ------------- | -------------------------------------- |
| `title`       | The document's name, and its identity. |
| `type`        | What kind of document it is.           |
| `tags`        | Up to five flat labels.                |
| `description` | One sentence on what the document is.  |

These are first-class fields, not entries inside the document's frontmatter. Each one has a single home, so there is never a second, contradicting copy to reconcile.

`source` works differently again. It records what wrote the document and is stamped from the credential used to write it. A writer cannot supply it, override it, or forge it. An agent's writes are always attributed to the agent.

### Custom frontmatter

Any key that is not universal and not system-managed is preserved exactly as supplied. Custom frontmatter survives writes, imports, and edits, and appears in a read-only **Custom** section of the document's properties.

Use it for anything your own conventions need: a status of your own, a review date, a customer name. Tatara stores and displays it without interpreting it, with one exception: wikilinks inside frontmatter values are indexed as real links.

## Titles, slugs, and paths

The title is the document's identity. Everything else about how the document is addressed derives from it.

Each document has a slug, derived from the title, and a path built from its folder and its slug. When the title changes, the slug is re-derived and the path is rewritten in the same operation, so title, slug, and path can never drift apart. Rename a document and its address follows it; links pointing at it are rewritten too.

The slug is a URL-friendly form of the title: lowercased, with punctuation collapsed to hyphens.

```text Slugs derived from titles theme={null}
Pricing Page Spec (v2)   ->  pricing-page-spec-v2
Q3 OKRs — Growth         ->  q3-okrs-growth
```

If that slug is already taken where the document is going, Tatara appends a number: `pricing-page-spec-2`, then `-3`, and so on.

A title must contain at least one letter or digit, and may not contain `/`, `#`, `|`, `[`, `]`, or a line break. Each of those means something in link syntax, so a title containing one would generate links that can never resolve. Tatara rejects it at write time rather than quietly mangling it.

Two different uniqueness rules apply:

* A **slug** is unique within its folder. `product` and `marketing` can each hold a document whose slug is `roadmap`.
* A **path** is unique within the brain. The full address is what identifies a document.

## Folders

Folders group documents, and their slugs are what paths are made of.

A folder path is the chain of folder slugs from the top of the brain down, joined by slashes. A document's path is its folder's path plus its own slug:

```text Anatomy of a path theme={null}
product/pricing                          <- a folder
product/pricing/pricing-page-spec        <- a document in it
```

Folder slugs are derived from folder names by the same rule as document slugs, and they are unique among siblings rather than across the brain. Two different parents can each contain a folder called `notes`.

This is why a bare folder name can be ambiguous: two folders called `notes` are only told apart by their full paths. Tools that write refuse an ambiguous name rather than guess.

A path may be at most 12 segments deep.

## Wikilinks

Documents link to each other with wikilinks, and Tatara indexes those links in both directions: a document knows what it points at and what points at it.

Five forms are recognized:

| Syntax                                           | What it does                                   |
| ------------------------------------------------ | ---------------------------------------------- |
| `[[Pricing page spec]]`                          | Links by name.                                 |
| `[[product/pricing/pricing-page-spec]]`          | Links by path (any target containing a slash). |
| `[[Pricing page spec\|the spec]]`                | Links with display text.                       |
| `![[Pricing page spec]]`                         | Embeds, and counts as a link.                  |
| `[the spec](/product/pricing/pricing-page-spec)` | A markdown link with a leading slash.          |

### How a link resolves

* A target without a slash resolves by case-insensitive title match. `[[pricing page spec]]` finds the document titled "Pricing Page Spec".
* A target with a slash resolves by exact path.

An `#anchor` on the end of a target is stripped before resolving, so `[[Pricing page spec#Tiers]]` points at the document. Links inside fenced code blocks and inline code are deliberately never indexed, because a link shown inside code documents the syntax rather than connecting two documents.

### Unresolved links heal themselves

A link to a document that does not exist yet is not an error. The link is kept, shown dimmed, and resolves by itself the moment a document with a matching title or path is created. You can write toward a document you have not written yet, and the graph closes when you get to it.

Deletion works the same way in reverse: deleting a document dims the links pointing at it rather than dropping them, and restoring it re-resolves them.

## Tags and the taxonomy

Documents carry flat tag strings, with no nesting and no prefixes, and at most five per document.

Separately, each brain has a tag registry that gives every tag one of three tiers:

| Tier      | Question it answers                   |
| --------- | ------------------------------------- |
| **Area**  | Which part of the business owns this? |
| **Topic** | What specifically is it about?        |
| **Goal**  | What is it trying to move?            |

The three tiers are **independent**. This is not a hierarchy: a topic does not belong to an area, and any topic or goal can be applied to a document in any area. A pricing-page spec might be area `product`, topic `pricing`, goal `acquisition`: three separate answers rather than a path through a tree.

<Note>
  The registry is advisory. Tags on documents are not validated against it. A tag that is not in the registry is accepted, and it appears in a review queue on the tags page where you can promote it into a tier or merge it into an existing tag. Coining a tag never fails a write.
</Note>

The registry's own guidance is one area, up to two topics, and up to two goals per document. That is guidance for you and your agents to follow, not a rule the product enforces. The only hard limit is five tags per document. See [Organizing with tags](/app/tags) for managing the registry and working the review queue.

## Deletion and recovery

Deleting is soft. Tatara retains the content rather than destroying it, which is what makes recovery possible.

<Warning>
  The web app has no trash and no undo. Nothing in it lists deleted documents or brings one back, so a delete made there is effectively permanent.
</Warning>

Recovery is possible only through a connected agent. A restored document works around a name collision by taking the next free name; a folder restore refuses instead, and a folder whose parent is also deleted has to be recovered by restoring the parent. See [Deleting documents and folders](/app/deleting).

## Where to go next

<Columns cols={2}>
  <Card title="Document formats" icon="table" href="/formats/overview">
    Boards, trackers, tables, and saved views over the documents you already have.
  </Card>

  <Card title="MCP tools" icon="wrench" href="/mcp/overview">
    Every tool an agent can call against a brain.
  </Card>
</Columns>