docs: Mintlify documentation site

README.md

@@ -32,7 +32,7 @@ open-index ui    --brain my-brain
 ```
 
 Prefer containers, or need a brain several agents share? →
-**[`docs/deployment.md`](./docs/deployment.md)** (`docker compose --profile sqlite up`).
+**[`docs/deployment.mdx`](./docs/deployment.mdx)** (`docker compose --profile sqlite up`).
 
 ### Commands
 
@@ -200,7 +200,7 @@ Then `open-index index` (loads file-backed entities) and `open-index validate`.
 4. **Agent write-back** — a Stop hook that records learnings via `put_entity` (the
    "continuously improving" loop).
 
-See [Entity Management](./entity-management.md) for guidance on cadence and decay.
+See [Entity Management](./docs/guides/entity-management.mdx) for guidance on cadence and decay.
 
 ### 4. Explore
 
@@ -244,7 +244,7 @@ building legal, marketing, support, or other specialized agents on Open Index.
 
 ## Using the brain from a cloud agent (production)
 
-📖 **[Full deployment guide → `docs/deployment.md`](./docs/deployment.md)** — local,
+📖 **[Full deployment guide → `docs/deployment.mdx`](./docs/deployment.mdx)** — local,
 remote (with and without Docker), TLS/proxying, and exactly what to paste into
 Claude Code, Claude Desktop, or Cursor.
 
@@ -324,7 +324,7 @@ cluster (or `brain.db`), so give it a persistent home and a backup. Rule of thum
 
 # Controlling search
 
-📖 **[Full configuration reference → `docs/configuration.md`](./docs/configuration.md)** —
+📖 **[Full configuration reference → `docs/guides/search-configuration.mdx`](./docs/guides/search-configuration.mdx)** —
 decision tables for `storage: file | index`, SQLite vs OpenSearch, and every search knob.
 
 **Schema** (per field): data `type` (string/number/boolean/timestamp), `processing`
@@ -391,7 +391,7 @@ are missing.
 3. Add tests under `tests/` for behaviour changes, and run `pytest`.
 4. If you touched a brain in `examples/`, run `open-index validate --brain examples/<name>`
    so schemas and entities stay consistent.
-5. Update the README / `entity-management.md` when you change user-facing behaviour.
+5. Update the README / the docs under `docs/` when you change user-facing behaviour.
 6. Open a PR describing *what* changed and *why*, and link the issue. CI runs the
    test suite on Python 3.10 and 3.13 and validates every brain in `examples/`.
 

docker-compose.yml

@@ -25,7 +25,7 @@ x-brain-service: &brain-service
     # are written back on put_entity.
     #
     # The container runs as uid 10001, so this directory must be writable by
-    # it — otherwise indexing fails on a bind mount. See docs/deployment.md.
+    # it — otherwise indexing fails on a bind mount. See docs/deployment.mdx.
     - ${BRAIN_DIR:-./brain}:/brain
     # The local embedding model (~90MB) is downloaded on first use. fastembed
     # otherwise caches it under a temp directory, which a container throws away

docs/README.md

@@ -0,0 +1,35 @@
+# Open Index docs
+
+The documentation site, built with [Mintlify](https://mintlify.com). Content lives
+in `.mdx` files; navigation and theme are configured in [`docs.json`](./docs.json).
+
+## Preview locally
+
+```bash
+npm i -g mint          # install the Mintlify CLI once
+cd docs
+mint dev               # serve at http://localhost:3000
+```
+
+## Check for broken links
+
+```bash
+cd docs
+mint broken-links
+```
+
+## Structure
+
+| Path | Contents |
+|---|---|
+| `index.mdx` | Landing page |
+| `quickstart.mdx` | Install + first brain |
+| `concepts.mdx` | The four primitives |
+| `use-cases.mdx` | Example domains |
+| `guides/` | Creating a brain, populating entities, entity management, search config |
+| `agents/` | MCP context layer, connectors |
+| `deployment.mdx` | Local / remote / Docker deployment |
+| `reference/cli.mdx` | Every `open-index` command |
+
+Deploy by connecting this repo in the Mintlify dashboard (root directory `docs`);
+pushes to the default branch publish automatically.

docs/agents/connectors.mdx

@@ -0,0 +1,62 @@
+---
+title: Connectors
+description: Pull entities from someone else's MCP server into your brain on a schedule.
+---
+
+Everything in [Open Index as a context layer](/agents/mcp) is about exposing **your
+brain** over MCP. A *connector* is the reverse: a script in
+`<brain>/connectors/*.py` that calls **someone else's** MCP server and turns the
+results into entities.
+
+```python
+from open_index.connectors import Connector, EntitySpec
+
+
+class LinearConnector(Connector):
+    name = "linear-issues"
+
+    # Where the source MCP server lives. ${ENV} refs are resolved at run time,
+    # so the URL and token stay out of git.
+    mcp_url = "${LINEAR_MCP_URL}"
+    mcp_auth_headers = {"Authorization": "Bearer ${LINEAR_TOKEN}"}
+
+    schedule = "daily"          # manual | hourly | daily | weekly | 6h | 30m | 1w
+
+    def extract_issues(self):
+        for item in self.paginate("list_issues", result_key="issues"):
+            yield EntitySpec(
+                doc_type="issue",
+                id=f"issue:{item['id']}",
+                name=item["title"],
+                fields={"status": item["state"]},
+                related_to=[(f"product:{item['project']}", "belongs to product")],
+            )
+```
+
+## Where do you get `mcp_url`?
+
+From whoever runs that server:
+
+- A hosted vendor MCP server — from their docs (e.g. `https://mcp.vendor.com/mcp`).
+- Another Open Index brain — its `open-index serve` URL, i.e. `http://host:8080/mcp`.
+- A local stdio-only MCP server — **not supported here.** Connectors speak
+  streamable HTTP/SSE over `httpx` only. It needs an HTTP endpoint.
+
+<Note>
+The URL must be the full endpoint path — the same one an agent would use.
+</Note>
+
+## Running connectors
+
+```bash
+export LINEAR_MCP_URL=https://mcp.linear.app/mcp
+export LINEAR_TOKEN=...
+
+open-index list-connectors                  # what's discovered, and its URL
+open-index ingest linear-issues             # run it now
+open-index run                              # run everything whose schedule is due
+open-index run --loop 3600                  # or wire `open-index run` into cron/CI
+```
+
+`open-index run` tracks last-run times in a gitignored `.open_index_state.json`, so
+it decides *whether* a connector is due — your cron drives the clock.

docs/agents/mcp.mdx

@@ -0,0 +1,75 @@
+---
+title: Open Index as your agent's context layer
+description: Expose a brain over MCP so agents can read domain context and keep it current.
+---
+
+`open-index mcp` runs an MCP server (stdio) exposing the brain to any MCP client —
+**read and write by default**.
+
+## The tools
+
+- The server publishes dynamic, brain-specific instructions as part of the agent
+  prompt so supporting hosts can navigate the domain before the first tool call.
+
+<CardGroup cols={2}>
+  <Card title="navigation_guidelines()" icon="compass">
+    Refresh the domain guide after the index or schema changes — reports doc_types,
+    fields, and the relationship vocabulary of *your* brain.
+  </Card>
+  <Card title="search_brain(query, doc_types, limit)" icon="magnifying-glass">
+    Retrieve domain context by query, optionally scoped to doc_types.
+  </Card>
+  <Card title="get_entity(id)" icon="cube">
+    Fetch a single entity by its `<doc_type>:<slug>` id.
+  </Card>
+  <Card title="put_entity(...) / put_entities([...])" icon="pen">
+    Add or update entities — validated, honoring the storage policy. `put_entities`
+    writes a whole batch in one call with a shared `provenance` block.
+  </Card>
+  <Card title="create_doc_type(...)" icon="shapes">
+    Define a new concept from the agent side.
+  </Card>
+</CardGroup>
+
+## Read-only mode
+
+Use `open-index mcp --read-only` (or `open-index serve --read-only`) to opt out when
+an agent should retrieve domain context but never maintain it.
+
+```bash
+open-index mcp --brain ./my-brain                 # read + write (default)
+open-index mcp --brain ./my-brain --read-only     # retrieval only
+```
+
+## Local context-fetch analytics
+
+CLI and MCP searches, entity fetches, and navigation-guide reads are recorded in the
+user's local state directory (`~/.local/state/open-index/`), outside the brain
+checkout. The Analytics tab shows fetch counts by client/operation, frequently
+fetched queries or entity IDs, latency, failures, zero-result searches, and recent
+activity.
+
+<Note>
+This file stays local and is never sent to Open Index's creators.
+</Note>
+
+## Claude Code conveniences
+
+`open-index init` includes optional Claude Code conveniences: `.mcp.json`, a
+`CLAUDE.md` describing durable editing workflows (not runtime navigation), and an
+**`edit-brain` skill**. They are one client integration, not a requirement for
+building legal, marketing, support, or other specialized agents on Open Index.
+
+## Portable agent setup skill
+
+`skills/setup-open-index/SKILL.md` follows the portable Agent Skills `SKILL.md`
+format used by agent runtimes including OpenClaw, Hermes, and Claude Code. Give or
+install this skill in the selected runtime when the agent should set up Open Index
+itself. It covers installation, domain-brain initialization, generic MCP wiring,
+default read/write verification, the `--read-only` opt-out, and production
+guardrails.
+
+## Connecting a client
+
+For the exact config block per client (Claude Code, Claude Desktop, Cursor) and the
+remote HTTP path, see [Deployment → Connecting your agent](/deployment#5-connecting-your-agent).

docs/concepts.mdx

@@ -0,0 +1,98 @@
+---
+title: Core concepts
+description: The four primitives a brain is built from, and how entities link into a graph.
+---
+
+A brain is built from four primitives. Everything else in Open Index is a way to
+create, store, search, or maintain them.
+
+<CardGroup cols={2}>
+  <Card title="doc_type" icon="shapes">
+    A concept you want to track and maintain — `service`, `customer`, `issue`.
+  </Card>
+  <Card title="doc_schema" icon="table-list">
+    The fields stored for a given doc_type, plus how each is searched and weighted.
+  </Card>
+  <Card title="entity" icon="cube">
+    One instance of a doc_type, stored per its schema and linked to others.
+  </Card>
+  <Card title="connector" icon="plug">
+    An optional source you extract entities from, e.g. an MCP server.
+  </Card>
+</CardGroup>
+
+## doc_type
+
+A **doc_type** is an empirical representation of the kind of object you want to
+store in your brain. Sample doc_types by domain:
+
+- **infra** — `service`, `datastore`, `dashboard`, `runbook`, `alert`
+- **sales** — `lead`, `deal`, `account`
+- **lending** — `loan`, `borrower`, `application`
+- **personal** — `goal`, `project`, `person`, `area`, `note`
+
+Each doc_type is one YAML file in `doc_types/`. It declares a schema, an optional
+display config, and an optional relationship vocabulary.
+
+## doc_schema
+
+The **schema** lists the fields a doc_type stores. Per field you set the data
+`type`, how it's searched (`syntactic`, `semantic`, or `none`), and a ranking
+`boost`. See [Search configuration](/guides/search-configuration) for the full
+field reference.
+
+## entity
+
+An **entity** is one instance of a doc_type. Its `id` must be `<doc_type>:<slug>`
+(e.g. `service:checkout`).
+
+Every entity carries the reserved **`related_to`** field — the correlation field
+present on all entities. It defines the graph edges: each edge is a `target` plus a
+free-text `relationship_edge_meaning`.
+
+```json
+{
+  "doc_type": "service",
+  "id": "service:checkout",
+  "name": "Checkout",
+  "related_to": [
+    { "target": "datastore:postgres-main",   "relationship_edge_meaning": "writes to" },
+    { "target": "dashboard:checkout-latency", "relationship_edge_meaning": "is monitored by" }
+  ]
+}
+```
+
+This is how you say "this ticket is about that service" without any graph database.
+The explorer's **Map** tab renders these edges directly.
+
+## connector
+
+A **connector** is an optional ingestion script in `<brain>/connectors/*.py` that
+pulls from someone else's MCP server on a schedule and turns the results into
+entities. See [Connectors](/agents/connectors).
+
+## Where entities live: `storage: file | index`
+
+Each doc_type declares its source of truth, so curated and machine-generated data
+don't fight over git.
+
+<Tabs>
+  <Tab title="storage: file">
+    JSON files under `entities/<doc_type>/` are the source of truth — git-tracked
+    and PR-reviewable. Right for curated, human- or agent-authored entities.
+    `open-index index` reconciles these from disk on each run.
+  </Tab>
+  <Tab title="storage: index (default)">
+    The search DB owns these entities; they are **not** written to files. Right for
+    connector-pulled, high-volume, or temporal data (hundreds of services, memories,
+    alerts) that would otherwise churn the repo.
+  </Tab>
+</Tabs>
+
+<Warning>
+`open-index index` reconciles **file**-backed types from disk and leaves
+**index**-backed entities untouched. Match how a type is written to how it's
+declared, or the next `index` run will wipe DB-written entities on a `file` type.
+</Warning>
+
+See [Search configuration](/guides/search-configuration) for the decision table.