{
  "$type": "site.standard.document",
  "content": {
    "$type": "site.standard.content.markdown",
    "text": "Data engineering is mostly context gathering. Tons of moments of going though code, docs, specs, issues, conversations to figure out how stakeholders want active users to be counted. [`qmd`](https://github.com/tobi/qmd) turns that pile of documents into something you can actually query without worrying about setup, which makes it useful for both me and my agents. I wanted to share that indexed knowledge with colleagues without forcing them to run CLI commands like `qmd embed`.\n\nI ended up with a setup I like: **the index is managed declaratively in git, and a daily CI job publishes a SQLite database with the embeddings**.\n\n## Making It Declarative\n\nI wrote a [tiny ~10 line wrapper](https://github.com/davidgasquez/dotfiles/commit/5de0ae7112ecc4c3377083ce3485477dc860894c) so that if the current folder has a `.qmd/` directory, `qmd` points to that local config and index. Within a project, `qmd` only sees that project's index and collections.\n\nThat also makes [`index.yml`](https://raw.githubusercontent.com/tobi/qmd/refs/heads/main/example-index.yml) easy to version control. Instead of living in my machine and memory, the index definition lives in the repo.\n\n## Making It Shared\n\nOnce I wanted to share this with the team, I had two obvious options.\n\n### 1. Share the `index.yml`\n\nThis works for technical folks but is not smooth for everyone else (even in the age of clankers, you need to know the right spells!). Consumers need the source code, need to run `qmd update`, need to run `qmd embed`, and need to keep everything fresh over time. Not great.\n\n### 2. Host an MCP server\n\nThe \"correct and boring\" option. `qmd` supports MCP already, and you can even host MCP servers for free with [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces-mcp-servers).\n\nI decided **not** to go this route. I prefer my infrastructure local-friendly and I don't like managing servers.\n\n## Making It Accessible\n\nInstead, I distribute a prebuilt index, similar to how I [distribute datasets](/barefoot-data-platforms). I put together the [`filecoin-docs-qmd`](https://github.com/davidgasquez/filecoin-docs-qmd) repo to package a curated Filecoin docs index and publish it.\n\nThe flow is simple:\n\n1. A curated list of sources lives on GitHub.\n2. Every day, a GitHub Action runs `qmd update` and `qmd embed`, compresses the SQLite DB, and publishes it.\n3. Users run a small installation script that downloads the latest database (<50MB) and sets up `qmd`.\n\nAfter that, anyone can do:\n\n```bash\nqmd --index filecoin query \"how does lotus handle deal onboarding\"\n```\n\nA good middle ground:\n\n- Source of truth is declarative and version controlled.\n- The artifact is self-contained and easy to install.\n- UX stays local and CLI-friendly.\n- No MCP forced on anyone.\n\n## Making It Smooth\n\nSomething I have not gotten to yet: forking `qmd` to support remote indexes. The entire process could be simplified to:\n\n```bash\nqmd --index https://awesomedomain.io/qmd.sqlite query \"how do we count active users\"\n```",
    "version": "1.0"
  },
  "description": "Data engineering is mostly context gathering. Tons of moments of going though code, docs, specs, issues, conversations to figure out how stakeholders want active users to be counted. qmd turns that pile of documents into something you can actually query without worrying about...",
  "path": "/sharing-a-qmd-index-with-a-team",
  "publishedAt": "2026-04-17T00:00:00.000Z",
  "site": "at://did:plc:4z5i7njrld66ew36htufcwry/site.standard.publication/3mo43d2tmt2ov",
  "textContent": "Data engineering is mostly context gathering. Tons of moments of going though code, docs, specs, issues, conversations to figure out how stakeholders want active users to be counted. qmd turns that pile of documents into something you can actually query without worrying about setup, which makes it useful for both me and my agents. I wanted to share that indexed knowledge with colleagues without forcing them to run CLI commands like qmd embed.\n\nI ended up with a setup I like: the index is managed declaratively in git, and a daily CI job publishes a SQLite database with the embeddings.\n\nMaking It Declarative\n\nI wrote a tiny ~10 line wrapper so that if the current folder has a .qmd/ directory, qmd points to that local config and index. Within a project, qmd only sees that project's index and collections.\n\nThat also makes index.yml easy to version control. Instead of living in my machine and memory, the index definition lives in the repo.\n\nMaking It Shared\n\nOnce I wanted to share this with the team, I had two obvious options.\nShare the index.yml\n\nThis works for technical folks but is not smooth for everyone else (even in the age of clankers, you need to know the right spells!). Consumers need the source code, need to run qmd update, need to run qmd embed, and need to keep everything fresh over time. Not great.\nHost an MCP server\n\nThe \"correct and boring\" option. qmd supports MCP already, and you can even host MCP servers for free with Hugging Face Spaces.\n\nI decided not to go this route. I prefer my infrastructure local-friendly and I don't like managing servers.\n\nMaking It Accessible\n\nInstead, I distribute a prebuilt index, similar to how I distribute datasets. I put together the filecoin-docs-qmd repo to package a curated Filecoin docs index and publish it.\n\nThe flow is simple:\nA curated list of sources lives on GitHub.\nEvery day, a GitHub Action runs qmd update and qmd embed, compresses the SQLite DB, and publishes it.\nUsers run a small installation script that downloads the latest database (<50MB) and sets up qmd.\n\nAfter that, anyone can do:\n\nA good middle ground:\nSource of truth is declarative and version controlled.\nThe artifact is self-contained and easy to install.\nUX stays local and CLI-friendly.\nNo MCP forced on anyone.\n\nMaking It Smooth\n\nSomething I have not gotten to yet: forking qmd to support remote indexes. The entire process could be simplified to:",
  "title": "Indexing and Sharing Organizational Context with qmd"
}