chore: import upstream snapshot with attribution

docs/python/setup/chroma.mdx

@@ -0,0 +1,78 @@
+---
+title: Chroma
+icon: database
+description: Set up the Chroma resource in Python.
+---
+
+## Dependencies
+
+Install the Chroma extra:
+
+```bash
+cd python
+uv sync --extra chroma
+```
+
+The resource imports `chromadb` lazily when it first connects to a collection.
+
+For collection schema setup, see the [Chroma Setup](/home/setup/chroma) guide.
+
+## Configuration
+
+```python
+import os
+
+from mirage import MountMode, Workspace
+from mirage.resource.chroma import ChromaConfig, ChromaResource
+
+config = ChromaConfig(
+    host=os.environ.get("CHROMA_HOST", "localhost"),
+    port=int(os.environ.get("CHROMA_PORT", "8000")),
+    ssl=os.environ.get("CHROMA_SSL", "false").lower() == "true",
+    collection_name=os.environ["CHROMA_COLLECTION"],
+    slug_field=os.environ.get("CHROMA_SLUG_FIELD", "page_slug"),
+    chunk_index_field=os.environ.get("CHROMA_CHUNK_INDEX_FIELD", "chunk_index"),
+)
+resource = ChromaResource(config=config)
+ws = Workspace({"/knowledge/": resource}, mode=MountMode.READ)
+```
+
+Mirage connects via Chroma's `AsyncHttpClient` using `host`, `port`, and `ssl`.
+
+## Config Reference
+
+| Field | Required | Default | Description |
+| ----- | -------- | ------- | ----------- |
+| `collection_name` | Yes | | Chroma collection name |
+| `host` | No | `localhost` | Chroma HTTP host |
+| `port` | No | `8000` | Chroma HTTP port |
+| `ssl` | No | `False` | Use HTTPS for Chroma HTTP connections |
+| `slug_field` | No | `page_slug` | Chunk metadata field containing the virtual file path |
+| `chunk_index_field` | No | `chunk_index` | Chunk metadata field used to order file chunks |
+
+`collection_name`, `slug_field`, and `chunk_index_field` are trimmed and must
+not be empty.
+
+## Environment Example
+
+```bash
+# .env.development
+CHROMA_COLLECTION=knowledge
+CHROMA_HOST=localhost
+CHROMA_PORT=8000
+CHROMA_SSL=false
+CHROMA_SLUG_FIELD=page_slug
+CHROMA_CHUNK_INDEX_FIELD=chunk_index
+CHROMA_EXAMPLE_QUERY=getting started
+```
+
+## Run the Examples
+
+From the repository root:
+
+```bash
+./python/.venv/bin/python examples/python/chroma/chroma.py
+./python/.venv/bin/python examples/python/chroma/chroma_vfs.py
+```
+
+The examples load `.env.development` from the repository root.

docs/python/setup/databricks.mdx

@@ -0,0 +1,83 @@
+---
+title: Databricks Volume
+icon: folder-open
+description: Set up the Databricks Unity Catalog volume resource in Python.
+---
+
+## Dependencies
+
+```bash
+uv add 'mirage-ai[databricks]'
+```
+
+For credential setup, see the [Databricks Volume Setup](/home/setup/databricks)
+guide.
+
+## Configuration
+
+### Databricks Apps or SDK-default auth
+
+```python
+from mirage import Workspace, MountMode
+from mirage.resource.databricks_volume import (
+    DatabricksVolumeConfig,
+    DatabricksVolumeResource,
+)
+
+config = DatabricksVolumeConfig(
+    catalog="main",
+    schema="default",
+    volume="agent_files",
+)
+resource = DatabricksVolumeResource(config=config)
+ws = Workspace({"/dbx/": resource}, mode=MountMode.READ)
+```
+
+### Explicit host and token
+
+```python
+import os
+
+config = DatabricksVolumeConfig(
+    catalog="main",
+    schema="default",
+    volume="agent_files",
+    host=os.environ["DATABRICKS_HOST"],
+    token=os.environ["DATABRICKS_TOKEN"],
+    root_path="/reports",
+)
+resource = DatabricksVolumeResource(config=config)
+ws = Workspace({"/dbx/": resource}, mode=MountMode.READ)
+```
+
+### Profile-based auth
+
+```python
+config = DatabricksVolumeConfig(
+    catalog="main",
+    schema="default",
+    volume="agent_files",
+    profile="DEV",
+)
+resource = DatabricksVolumeResource(config=config)
+ws = Workspace({"/dbx/": resource}, mode=MountMode.READ)
+```
+
+## Config Reference
+
+| Field | Required | Default | Description |
+| --- | --- | --- | --- |
+| `catalog` | Yes |  | Unity Catalog catalog name. |
+| `schema` | Yes |  | Unity Catalog schema name. |
+| `volume` | Yes |  | Unity Catalog volume name. |
+| `root_path` | No | `/` | Subdirectory inside the volume to expose. |
+| `host` | No |  | Databricks workspace host. |
+| `token` | No |  | Databricks personal access token. Redacted in snapshots. |
+| `profile` | No |  | Databricks SDK profile name. |
+| `timeout` | No | `30` | Request timeout in seconds. |
+
+## Notes
+
+- Supports both read and write mount modes (`MountMode.READ` / `MountMode.WRITE`).
+- Auth falls through to the Databricks SDK defaults when `host`, `token`, and `profile` are omitted.
+- `root_path` is normalized and cannot contain `..`.

docs/python/setup/dify.mdx

@@ -0,0 +1,87 @@
+---
+title: Dify
+icon: /images/dify-logo.svg
+description: Set up the Dify Knowledge resource in Python.
+---
+
+## Dependencies
+
+No additional dependencies are required beyond the Python package. The Dify
+resource uses `httpx` for async API calls.
+
+For credential setup, see the [Dify Setup](/home/setup/dify) guide.
+
+## Configuration
+
+```python
+import os
+
+from mirage import MountMode, Workspace
+from mirage.resource.dify import DifyConfig, DifyResource
+
+config = DifyConfig(
+    api_key=os.environ["DIFY_API_KEY"],
+    base_url=os.environ.get("DIFY_BASE_URL", "https://api.dify.ai/v1"),
+    dataset_id=os.environ["DIFY_DATASET_ID"],
+    slug_metadata_name=os.environ.get("DIFY_SLUG_METADATA_NAME", "slug"),
+)
+resource = DifyResource(config=config)
+ws = Workspace({"/knowledge/": resource}, mode=MountMode.READ)
+```
+
+## Config Reference
+
+| Field                | Required | Default | Description |
+| -------------------- | -------- | ------- | ----------- |
+| `api_key`            | Yes      |         | Dify Knowledge API key |
+| `base_url`           | Yes      |         | Dify API base URL |
+| `dataset_id`         | Yes      |         | Dify Knowledge dataset |
+| `slug_metadata_name` | No       | `slug`  | Dify document metadata name used as the virtual path slug |
+
+`DifyConfig` normalizes `base_url` by removing a trailing slash and trims
+`slug_metadata_name`.
+
+## Environment Example
+
+```bash
+# .env.development
+DIFY_API_KEY=dataset-...
+DIFY_BASE_URL=https://api.dify.ai/v1
+DIFY_DATASET_ID=...
+DIFY_SLUG_METADATA_NAME=slug
+```
+
+## Metadata Setup
+
+For stable filesystem paths and scoped search, add a Dify document metadata
+field named by `slug_metadata_name`. The default field name is `slug`.
+
+```text
+name: slug
+value: guides/quickstart.md
+```
+
+If your Dify metadata field is named `path` instead, configure:
+
+```python
+config = DifyConfig(
+    api_key=os.environ["DIFY_API_KEY"],
+    base_url=os.environ.get("DIFY_BASE_URL", "https://api.dify.ai/v1"),
+    dataset_id=os.environ["DIFY_DATASET_ID"],
+    slug_metadata_name="path",
+)
+```
+
+Mirage maps that document to:
+
+```text
+/knowledge/guides/quickstart.md
+```
+
+If a document does not have the configured slug metadata field, Mirage uses the
+document name as the path. To make scoped `search` work for those name-based
+documents, enable Dify's Built-in Fields in the dataset metadata settings so
+`document_name` can be used as a metadata filter.
+
+See [Dify Setup](/home/setup/dify#document-metadata) for the full metadata
+checklist.

docs/python/setup/discord.mdx

@@ -0,0 +1,29 @@
+---
+title: Discord
+icon: discord
+description: Set up the Discord resource in Python.
+---
+
+## Dependencies
+
+No additional dependencies - uses `aiohttp` (included).
+
+For credential setup, see the [Discord Setup](/home/setup/discord) guide.
+
+## Configuration
+
+```python
+import os
+from mirage import Workspace, MountMode
+from mirage.resource.discord import DiscordConfig, DiscordResource
+
+config = DiscordConfig(token=os.environ["DISCORD_BOT_TOKEN"])
+resource = DiscordResource(config=config)
+ws = Workspace({"/discord/": resource}, mode=MountMode.READ)
+```
+
+## Config Reference
+
+| Field   | Required | Description       |
+| ------- | -------- | ----------------- |
+| `token` | Yes      | Discord Bot Token |

docs/python/setup/email.mdx

@@ -0,0 +1,57 @@
+---
+title: Email
+icon: envelope
+description: Set up the Email resource in Python.
+---
+
+## Dependencies
+
+```bash
+uv add aioimaplib aiosmtplib
+```
+
+For credential setup, see the [Email Setup](/home/setup/email) guide.
+
+## Configuration
+
+```python
+import os
+from mirage import Workspace, MountMode
+from mirage.resource.email import EmailConfig, EmailResource
+
+config = EmailConfig(
+    imap_host=os.environ["IMAP_HOST"],
+    smtp_host=os.environ["SMTP_HOST"],
+    username=os.environ["EMAIL_USERNAME"],
+    password=os.environ["EMAIL_PASSWORD"],
+)
+resource = EmailResource(config=config)
+ws = Workspace({"/email/": resource}, mode=MountMode.READ)
+```
+
+### Verify Connection
+
+```python
+import asyncio
+
+async def main():
+    r = await ws.execute("ls /email/")
+    print(await r.stdout_str())
+
+asyncio.run(main())
+```
+
+This should print your IMAP folder names (e.g., `INBOX`, `Sent`,
+`Drafts`, `Archive`).
+
+## Config Reference
+
+| Field       | Required | Default | Description              |
+| ----------- | -------- | ------- | ------------------------ |
+| `imap_host` | Yes      |         | IMAP server hostname     |
+| `imap_port` | No       | `993`   | IMAP port                |
+| `smtp_host` | Yes      |         | SMTP server hostname     |
+| `smtp_port` | No       | `587`   | SMTP port                |
+| `username`  | Yes      |         | Email address / login    |
+| `password`  | Yes      |         | Password or app password |
+| `use_ssl`   | No       | `True`  | Use SSL for IMAP         |

docs/python/setup/fuse.mdx

@@ -0,0 +1,101 @@
+---
+title: FUSE
+icon: hard-drive
+description: Set up FUSE support for MIRAGE in Python.
+---
+
+## Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) package manager (optional)
+
+## System FUSE
+
+Install the OS-level FUSE kernel extension first:
+
+- [macOS FUSE Setup](/home/setup/macos), macFUSE + kernel extension + Apple Silicon recovery mode steps.
+- [Linux FUSE Setup](/home/setup/linux), `fuse3` install and `/etc/fuse.conf`.
+
+## Install Mirage with the FUSE Extra
+
+```bash
+pip install "mirage-ai[fuse]"
+```
+
+Or with uv:
+
+```bash
+uv add "mirage-ai[fuse]"
+```
+
+## Verify
+
+```python
+from mirage import Mount, MountMode, Workspace
+from mirage.resource.ram import RAMResource
+
+with Workspace(
+    {"/data": Mount(RAMResource(), mode=MountMode.WRITE, fuse=True)}) as ws:
+    print("mountpoints:", ws.fuse_mountpoints)
+```
+
+If the printed path exists under `/tmp/mirage-*`, FUSE is wired up correctly.
+
+The `Workspace` constructor blocks until every `fuse` mount is live, so the
+mountpoint is ready to read as soon as the `with` block is entered, no sleep
+needed. (In TypeScript, where mounts are async, you `await ws.fuseReady()`
+instead.)
+
+## Per-mount FUSE
+
+FUSE is configured **per mount**. Each mount whose `fuse` is set is exposed at
+its own mountpoint, showing only that mount's subtree. The value is either
+`true` (mount at a fresh temp directory) or a path string (mount there,
+creating the directory if missing):
+
+```yaml
+mode: WRITE
+mounts:
+  /data:
+    resource: ram
+    fuse: /tmp/data-repo   # explicit path
+  /s3:
+    resource: s3
+    fuse: true             # temp directory
+  /logs:
+    resource: disk
+    # no fuse key, not FUSE-exposed
+```
+
+`ws.fuse_mountpoints` returns a `{prefix: path}` map of the live mountpoints.
+
+## Size semantics for API-backed files
+
+Some resources (Linear, Trello, Slack, ...) cannot report a file's size
+without fetching its content, so `stat` returns an unknown size. Over the
+FUSE mount these files behave like Linux `/proc` files: they stat as **0
+bytes until first open**, and become fully readable the moment anything opens
+them. Mirage mounts with `direct_io` (the kernel reads to EOF regardless of
+the reported size) and `attr_timeout=0` (post-open `fstat` returns the real
+size of the now-fetched content, kept warm in a 30-second cache).
+
+What that means per tool:
+
+| Tools | Behavior |
+| --- | --- |
+| `cat`, `grep`, `head`, `cp`, `md5sum`, `sed`, `sort` | correct content, always |
+| `wc -c`, `tail -c` | correct (they fstat after open, which serves the real size) |
+| `ls -l`, `du`, `find -size`, `test -s` | report 0 until the file has been opened recently |
+| `tar`, `rsync`, `scp` | see 0 at stat time and copy empty content, exactly like `tar` over `/proc`; read the file first or use `cat`/`cp` based flows |
+
+Mirage never reports a fake size and never fetches content during `stat`:
+returning real sizes eagerly would fire one API call per file on every
+`ls -l`.
+
+<Warning>
+  **macOS allows only one in-process FUSE mount.** macFUSE registers a
+  process-global signal source, so a second simultaneous mount in the same
+  process fails with `fuse: cannot register signal source`. Multiple per-mount
+  FUSE mounts work on Linux; on macOS, enable `fuse` on a single mount per
+  workspace (or run additional mounts in separate processes).
+</Warning>

docs/python/setup/github.mdx

@@ -0,0 +1,30 @@
+---
+title: GitHub
+icon: github
+description: Set up the GitHub resource in Python.
+---
+
+## Dependencies
+
+No additional dependencies - uses `aiohttp` (included).
+
+For credential setup, see the [GitHub Setup](/home/setup/github) guide.
+
+## Configuration
+
+```python
+import os
+from mirage import Workspace, MountMode
+from mirage.resource.github import GitHubConfig, GitHubResource
+
+config = GitHubConfig(token=os.environ["GITHUB_TOKEN"])
+resource = GitHubResource(
+    config=config, owner="my-org", repo="my-repo", ref="main")
+ws = Workspace({"/github": resource}, mode=MountMode.READ)
+```
+
+## Config Reference
+
+| Field   | Required | Description                  |
+| ------- | -------- | ---------------------------- |
+| `token` | Yes      | GitHub Personal Access Token |

docs/python/setup/github_ci.mdx

@@ -0,0 +1,36 @@
+---
+title: GitHub CI
+icon: circle-play
+description: Set up the GitHub CI resource in Python.
+---
+
+## Dependencies
+
+No additional dependencies - uses `aiohttp` (included).
+
+For credential setup, see the [GitHub CI Setup](/home/setup/github_ci) guide.
+
+## Configuration
+
+```python
+import os
+from mirage import Workspace, MountMode
+from mirage.resource.github_ci import GitHubCIConfig, GitHubCIResource
+
+config = GitHubCIConfig(
+    token=os.environ["GITHUB_TOKEN"],
+    owner="my-org",
+    repo="my-repo",
+)
+resource = GitHubCIResource(config=config)
+ws = Workspace({"/ci": resource}, mode=MountMode.READ)
+```
+
+## Config Reference
+
+| Field   | Required | Default | Description                         |
+| ------- | -------- | ------- | ----------------------------------- |
+| `token` | Yes      |         | GitHub Personal Access Token        |
+| `owner` | Yes      |         | Repository owner (user or org)      |
+| `repo`  | Yes      |         | Repository name                     |
+| `days`  | No       | 30      | Time window for listing recent runs |

docs/python/setup/google.mdx

@@ -0,0 +1,25 @@
+---
+title: Google Workspace
+icon: google
+description: Set up the Google Workspace resource in Python.
+---
+
+## Dependencies
+
+No additional dependencies - uses `aiohttp` (included).
+
+For credential setup, see the [Google Workspace Setup](/home/setup/google) guide.
+
+## Configuration
+
+```python
+import os
+from mirage.resource.googledocs import GoogleDocsConfig, GoogleDocsResource
+
+config = GoogleDocsConfig(
+    client_id=os.environ["GOOGLE_CLIENT_ID"],
+    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
+    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
+)
+resource = GoogleDocsResource(config=config)
+```

docs/python/setup/lancedb.mdx

@@ -0,0 +1,170 @@
+---
+title: LanceDB
+icon: database
+description: Set up the LanceDB resource in Python, including LanceDB OSS, object storage, LanceDB Cloud, and LanceDB Enterprise, with semantic search.
+---
+
+The LanceDB resource mounts a LanceDB table as a filesystem: group-by columns
+become folders, rows become files, and semantic search is the `search` command.
+See [LanceDB Resource](/python/resource/lancedb) for the full layout and command
+list.
+
+## Dependencies
+
+```bash
+uv add lancedb
+```
+
+`lancedb` ships the embedded engine and the async client Mirage uses. It pulls
+in `pyarrow`; no separate server is required.
+
+Semantic search needs an embedding function inside the table. For real
+multimodal (CLIP) embeddings, add the model deps to your **builder**
+environment only (Mirage core never imports them):
+
+```bash
+uv add open-clip-torch torch
+```
+
+## Where the data lives
+
+A LanceDB database is a directory of Lance files. The `uri` decides where it is
+stored, and the same `LanceDBConfig` works for every tier.
+
+### LanceDB OSS (local disk)
+
+```python
+from mirage import MountMode, Workspace
+from mirage.resource.lancedb import LanceDBConfig, LanceDBResource
+
+config = LanceDBConfig(
+    uri="/data/fashion.lancedb",
+    table="fashion",
+    group_by=["gender", "articleType", "baseColour"],
+    id_column="id",
+    title_column="productDisplayName",
+    blob_column="image_bytes",
+    blob_ext="jpg",
+    vector_column="vector",
+)
+ws = Workspace({"/fashion/": LanceDBResource(config)}, mode=MountMode.READ)
+```
+
+### Object storage (S3 / GCS / Azure)
+
+Point `uri` at a bucket. Credentials come from the environment by default, or
+pass them through `storage_options`.
+
+```python
+config = LanceDBConfig(
+    uri="s3://my-bucket/fashion.lancedb",
+    table="fashion",
+    group_by=["gender", "articleType", "baseColour"],
+    id_column="id",
+    vector_column="vector",
+    storage_options={"region": "us-east-1"},
+)
+```
+
+### LanceDB Cloud
+
+Use a `db://` URI plus an API key and region. The API key can also come from the
+`LANCEDB_API_KEY` environment variable.
+
+```python
+import os
+
+config = LanceDBConfig(
+    uri="db://my-database",
+    api_key=os.environ["LANCEDB_API_KEY"],
+    region="us-east-1",
+    table="fashion",
+    group_by=["gender", "articleType", "baseColour"],
+    id_column="id",
+    vector_column="vector",
+)
+ws = Workspace({"/fashion/": LanceDBResource(config)}, mode=MountMode.READ)
+```
+
+### LanceDB Enterprise
+
+Enterprise is the same as Cloud plus a custom endpoint via `host_override`.
+
+```python
+config = LanceDBConfig(
+    uri="db://my-database",
+    api_key=os.environ["LANCEDB_API_KEY"],
+    host_override="https://my-database.us-east-1.api.lancedb.com",
+    region="us-east-1",
+    table="fashion",
+    group_by=["gender", "articleType", "baseColour"],
+    id_column="id",
+    vector_column="vector",
+)
+```
+
+`region` and `host_override` are only applied for `db://` URIs; they are ignored
+for local and object-storage mounts.
+
+## Search setup
+
+Search is powered by the table's own embedding function, not by Mirage. The
+`search` command is available when `vector_column` is set; the table must have
+been created with an embedding function registered on a source field.
+
+A minimal CLIP-backed table (run once in your builder environment):
+
+```python
+import lancedb
+from lancedb.embeddings import get_registry
+from lancedb.pydantic import LanceModel, Vector
+
+func = get_registry().get("open-clip").create()
+
+class Product(LanceModel):
+    id: int
+    gender: str
+    articleType: str
+    baseColour: str
+    productDisplayName: str = func.SourceField()  # text the model embeds
+    image_bytes: bytes
+    vector: Vector(func.ndims()) = func.VectorField()
+
+db = lancedb.connect("/data/fashion.lancedb")
+table = db.create_table("fashion", schema=Product)
+table.add(rows)  # rows include image_bytes
+```
+
+Once mounted, querying is the `search` command. LanceDB embeds the query text
+with the same model and runs vector search, returning ranked rows as canonical
+file paths with a score, then their cards:
+
+```bash
+search "red running shoes" /fashion          # ranked <path>.md:score + card body
+cat /fashion/Men/Shoes/White/3.md             # follow a result to the real file
+```
+
+A runnable, dependency-free version (a lightweight keyword embedding instead of
+CLIP) lives in `examples/python/lancedb/`.
+
+## Config reference
+
+| Field            | Required | Default       | Description                                                        |
+| ---------------- | -------- | ------------- | ------------------------------------------------------------------ |
+| `uri`            | Yes      |               | Local path, `s3://`/`gs://`/`az://`/`hf://`, or `db://` (Cloud)    |
+| `api_key`        | No       |               | LanceDB Cloud/Enterprise API key (or `LANCEDB_API_KEY`)            |
+| `region`         | No       | `us-east-1`   | Cloud region (`db://` only)                                        |
+| `host_override`  | No       |               | Enterprise endpoint URL (`db://` only)                             |
+| `storage_options`| No       |               | Object-storage options/credentials                                |
+| `table`          | No       |               | Pin one table; the mount root becomes that table                  |
+| `group_by`       | No       | `[]`          | Columns that become nested folder levels                          |
+| `id_column`      | No       | `id`          | Column used to name row files                                     |
+| `title_column`   | No       |               | Column used as the card heading                                   |
+| `blob_column`    | No       |               | Column served as the raw blob/image file                         |
+| `blob_ext`       | No       | `bin`         | Extension for the blob file (`jpg`, `png`, ...)                   |
+| `vector_column`  | No       |               | Vector column; presence enables the `search` command            |
+| `search_limit`   | No       | `10`          | Default top-k returned by `search`                              |
+| `max_rows`       | No       | `1000`        | Cap on rows scanned per folder listing                           |
+
+The mount is read-only. See [LanceDB Resource](/python/resource/lancedb) for the
+filesystem layout and supported commands.

docs/python/setup/langfuse.mdx

@@ -0,0 +1,35 @@
+---
+title: Langfuse
+icon: chart-line
+description: Set up the Langfuse resource in Python.
+---
+
+## Dependencies
+
+No additional dependencies - uses `aiohttp` (included).
+
+For credential setup, see the [Langfuse Setup](/home/setup/langfuse) guide.
+
+## Configuration
+
+```python
+import os
+from mirage import Workspace, MountMode
+from mirage.resource.langfuse import LangfuseConfig, LangfuseResource
+
+config = LangfuseConfig(
+    public_key=os.environ["LANGFUSE_PUBLIC_KEY"],
+    secret_key=os.environ["LANGFUSE_SECRET_KEY"],
+    host=os.environ.get("LANGFUSE_HOST", "https://cloud.langfuse.com"),
+)
+resource = LangfuseResource(config=config)
+ws = Workspace({"/langfuse/": resource}, mode=MountMode.READ)
+```
+
+## Config Reference
+
+| Field        | Required | Default                      | Description             |
+| ------------ | -------- | ---------------------------- | ----------------------- |
+| `public_key` | Yes      |                              | Langfuse public API key |
+| `secret_key` | Yes      |                              | Langfuse secret API key |
+| `host`       | No       | `https://cloud.langfuse.com` | Langfuse API host URL   |

docs/python/setup/linear.mdx

@@ -0,0 +1,33 @@
+---
+title: Linear
+icon: chart-gantt
+description: Set up the Linear resource in Python.
+---
+
+## Dependencies
+
+No additional dependencies - uses `aiohttp` (included).
+
+For credential setup, see the [Linear Setup](/home/setup/linear) guide.
+
+## Configuration
+
+```python
+import os
+
+from mirage import MountMode, Workspace
+from mirage.resource.linear import LinearConfig, LinearResource
+
+config = LinearConfig(api_key=os.environ["LINEAR_API_KEY"])
+resource = LinearResource(config=config)
+ws = Workspace({"/linear/": resource}, mode=MountMode.READ)
+```
+
+## Config Reference
+
+| Field       | Required | Description                                 |
+| ----------- | -------- | ------------------------------------------- |
+| `api_key`   | Yes      | Linear personal API key                     |
+| `workspace` | No       | Workspace slug for URL/display usage        |
+| `team_ids`  | No       | Restrict the mounted tree to specific teams |
+| `base_url`  | No       | GraphQL endpoint, defaults to Linear Cloud  |

docs/python/setup/mongodb.mdx

@@ -0,0 +1,51 @@
+---
+title: MongoDB
+icon: database
+description: Set up the MongoDB resource in Python.
+---
+
+## Dependencies
+
+```bash
+uv add pymongo
+```
+
+The `pymongo` package provides async MongoDB driver support via `AsyncMongoClient`.
+
+For credential setup, see the [MongoDB Setup](/home/setup/mongodb) guide.
+
+## Configuration
+
+### Mount all databases
+
+```python
+import os
+from mirage import Workspace, MountMode
+from mirage.resource.mongodb import MongoDBConfig, MongoDBResource
+
+config = MongoDBConfig(uri=os.environ["MONGODB_URI"])
+resource = MongoDBResource(config=config)
+ws = Workspace({"/mongodb/": resource}, mode=MountMode.READ)
+```
+
+### Mount specific databases
+
+```python
+config = MongoDBConfig(
+    uri=os.environ["MONGODB_URI"],
+    databases=["sample_mflix", "sample_analytics"],
+)
+resource = MongoDBResource(config=config)
+ws = Workspace({"/mongodb/": resource}, mode=MountMode.READ)
+```
+
+The database directory always appears in the path, even when `databases`
+filters to a single entry. The full layout is documented under
+[MongoDB Resource](/python/resource/mongodb).
+
+## Config Reference
+
+| Field       | Required | Description                                |
+| ----------- | -------- | ------------------------------------------ |
+| `uri`       | Yes      | MongoDB connection URI                     |
+| `databases` | No       | List of database names (omit to mount all) |

docs/python/setup/notion.mdx

@@ -0,0 +1,31 @@
+---
+title: Notion
+icon: book
+description: Set up the Notion resource in Python.
+---
+
+## Dependencies
+
+No additional dependencies - uses `aiohttp` (included).
+
+For credential setup, see the [Notion Setup](/home/setup/notion) guide.
+
+## Configuration
+
+```python
+import os
+
+from mirage import MountMode, Workspace
+from mirage.resource.notion import NotionConfig, NotionResource
+
+config = NotionConfig(api_key=os.environ["NOTION_API_KEY"])
+resource = NotionResource(config=config)
+ws = Workspace({"/notion/": resource}, mode=MountMode.READ)
+```
+
+## Config Reference
+
+| Field      | Required | Description                            |
+| ---------- | -------- | -------------------------------------- |
+| `api_key`  | Yes      | Notion internal integration secret     |
+| `base_url` | No       | API endpoint, defaults to Notion Cloud |

docs/python/setup/onedrive.mdx

@@ -0,0 +1,39 @@
+---
+title: OneDrive
+icon: microsoft
+description: Set up the OneDrive resource in Python.
+---
+
+## Dependencies
+
+No additional dependencies - uses `aiohttp` (included).
+
+For credential setup, see the [OneDrive Setup](/home/setup/onedrive) guide.
+
+## Configuration
+
+```python
+import os
+from mirage import Workspace, MountMode
+from mirage.resource.onedrive import OneDriveConfig, OneDriveResource
+
+config = OneDriveConfig(
+    access_token=os.environ["ONEDRIVE_ACCESS_TOKEN"],
+    drive_id=os.environ.get("ONEDRIVE_DRIVE_ID"),  # omit for delegated /me/drive
+)
+resource = OneDriveResource(config=config)
+ws = Workspace({"/onedrive/": resource}, mode=MountMode.WRITE)
+```
+
+## Config Reference
+
+| Field          | Required | Description                                                              |
+| -------------- | -------- | ------------------------------------------------------------------------ |
+| `access_token` | Yes      | Microsoft Graph OAuth2 bearer token                                       |
+| `drive_id`     | No       | Target a specific drive. Required for app-only tokens (no `/me/drive`)    |
+| `site_id`      | No       | Resolve a SharePoint site's default drive instead of `/me/drive`         |
+| `key_prefix`   | No       | Mount a sub-folder of the drive as the root                              |
+| `timeout`      | No       | Request timeout in seconds (default `30`)                                |
+
+Drive resolution order: `drive_id` -> the `site_id` site's default drive ->
+`/me/drive`.

docs/python/setup/qdrant.mdx

@@ -0,0 +1,112 @@
+---
+title: Qdrant
+icon: database
+description: Set up the Qdrant resource in Python, including self-hosted Qdrant and Qdrant Cloud, with local or server-side semantic search.
+---
+
+The Qdrant resource mounts a [Qdrant](https://qdrant.tech/) collection as a filesystem: group-by payload
+fields become folders, points become files, and semantic search is the `search`
+command. See [Qdrant Resource](/python/resource/qdrant) for the full layout and
+command list.
+
+## Dependencies
+
+```bash
+uv add 'mirage-ai[qdrant]'
+```
+
+The `qdrant` extra installs `qdrant-client[fastembed]`. `fastembed` powers
+local, in-process query embedding for the `search` command; filesystem browsing
+(`ls`/`cat`/`find`/`grep`) needs only the base client.
+
+## Connection
+
+The same `QdrantConfig` works for self-hosted and cloud.
+
+### Self-hosted
+
+```python
+from mirage import MountMode, Workspace
+from mirage.resource.qdrant import QdrantConfig, QdrantResource
+
+config = QdrantConfig(
+    host="localhost",
+    port=6333,
+    collection="fashion",
+    group_by=["gender", "articleType", "baseColour"],
+    id_field="id",
+    text_field="productDisplayName",
+    blob_field="image_b64",
+    blob_ext="jpg",
+)
+ws = Workspace({"/fashion/": QdrantResource(config)}, mode=MountMode.READ)
+```
+
+### Qdrant Cloud
+
+Use `url` plus an `api_key`:
+
+```python
+import os
+
+config = QdrantConfig(
+    url="https://xyz.cloud.qdrant.io",
+    api_key=os.environ["QDRANT_API_KEY"],
+    collection="fashion",
+    group_by=["gender", "articleType", "baseColour"],
+    id_field="id",
+)
+ws = Workspace({"/fashion/": QdrantResource(config)}, mode=MountMode.READ)
+```
+
+## Search setup
+
+The `search` command embeds the query and runs Qdrant vector search. The
+collection must already store vectors produced by the same model
+(`embedding_model`, default `sentence-transformers/all-MiniLM-L6-v2`). Query
+embedding happens one of two ways:
+
+- **Local (default):** `fastembed` embeds the query in process.
+- **Server-side:** set `cloud_inference=True` to have an inference-enabled
+  Qdrant Cloud cluster embed the query. The query text is sent to the server
+  instead of being embedded locally.
+
+```python
+config = QdrantConfig(
+    url="https://xyz.cloud.qdrant.io",
+    api_key=os.environ["QDRANT_API_KEY"],
+    collection="fashion",
+    group_by=["gender"],
+    cloud_inference=True,
+    embedding_model="sentence-transformers/all-MiniLM-L6-v2",
+)
+```
+
+```bash
+search "red running shoes" /fashion          # ranked <path>.txt:score + content
+cat /fashion/Men/Shoes/White/3.txt            # follow a result to the real file
+```
+
+## Config reference
+
+| Field              | Required | Default                                     | Description                                                  |
+| ------------------ | -------- | ------------------------------------------- | ------------------------------------------------------------ |
+| `url`              | No       |                                             | Qdrant URL (Cloud or self-hosted); overrides `host`/`port`   |
+| `host`             | No       | `localhost`                                 | Host when `url` is unset                                     |
+| `port`             | No       | `6333`                                      | Port when `url` is unset                                     |
+| `https`            | No       | `false`                                     | Use TLS for `host`/`port` connections                        |
+| `api_key`          | No       |                                             | Qdrant Cloud API key                                         |
+| `collection`       | No       |                                             | Pin one collection; the mount root becomes that collection   |
+| `group_by`         | No       | `[]`                                        | Payload fields that become nested folder levels              |
+| `id_field`         | No       | `id`                                        | Field name shown for the point id; names point files         |
+| `text_field`       | No       |                                             | Payload field served as the `<id>.txt` embedded source text  |
+| `blob_field`       | No       |                                             | Payload field served as the raw blob/image file              |
+| `blob_ext`         | No       | `bin`                                       | Extension for the blob file (`jpg`, `png`, ...)              |
+| `vector_field`     | No       |                                             | Payload field holding a vector, omitted from `<id>.json`     |
+| `search_limit`     | No       | `10`                                        | Default top-k returned by `search`                           |
+| `max_rows`         | No       | `1000`                                      | Cap on points scanned per folder listing                     |
+| `embedding_model`  | No       | `sentence-transformers/all-MiniLM-L6-v2`    | Model used to embed the query                                |
+| `cloud_inference` | No       | `false`                                     | Embed the query server-side instead of with local fastembed  |
+
+The mount is read-only. See [Qdrant Resource](/python/resource/qdrant) for the
+filesystem layout and supported commands.

docs/python/setup/slack.mdx

@@ -0,0 +1,29 @@
+---
+title: Slack
+icon: slack
+description: Set up the Slack resource in Python.
+---
+
+## Dependencies
+
+No additional dependencies - uses `aiohttp` (included).
+
+For credential setup, see the [Slack Setup](/home/setup/slack) guide.
+
+## Configuration
+
+```python
+import os
+from mirage import Workspace, MountMode
+from mirage.resource.slack import SlackConfig, SlackResource
+
+config = SlackConfig(token=os.environ["SLACK_BOT_TOKEN"])
+resource = SlackResource(config=config)
+ws = Workspace({"/slack/": resource}, mode=MountMode.READ)
+```
+
+## Config Reference
+
+| Field   | Required | Description                             |
+| ------- | -------- | --------------------------------------- |
+| `token` | Yes      | Slack Bot User OAuth Token (`xoxb-...`) |

docs/python/setup/trello.mdx

@@ -0,0 +1,37 @@
+---
+title: Trello
+icon: table-columns
+description: Set up the Trello resource in Python.
+---
+
+## Dependencies
+
+No additional dependencies - uses `aiohttp` (included).
+
+For credential setup, see the [Trello Setup](/home/setup/trello) guide.
+
+## Configuration
+
+```python
+import os
+
+from mirage import MountMode, Workspace
+from mirage.resource.trello import TrelloConfig, TrelloResource
+
+config = TrelloConfig(
+    api_key=os.environ["TRELLO_API_KEY"],
+    api_token=os.environ["TRELLO_API_TOKEN"],
+)
+resource = TrelloResource(config=config)
+ws = Workspace({"/trello/": resource}, mode=MountMode.READ)
+```
+
+## Config Reference
+
+| Field          | Required | Description                                     |
+| -------------- | -------- | ----------------------------------------------- |
+| `api_key`      | Yes      | Trello API key                                  |
+| `api_token`    | Yes      | Trello API token                                |
+| `workspace_id` | No       | Restrict the mounted tree to a single workspace |
+| `board_ids`    | No       | Restrict the mounted tree to specific boards    |
+| `base_url`     | No       | REST endpoint, defaults to Trello Cloud         |