quackspace 0.1.0__tar.gz

quackspace-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marco Cassar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quackspace-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: quackspace
+Version: 0.1.0
+Summary: A DuckDB-backed knowledge layer over your local work that helps LLMs navigate everything
+Keywords: llm,mcp,rag,knowledge-base,search,duckdb,obsidian,markdown,notes,retrieval,agent
+Author: Marco Cassar
+Author-email: Marco Cassar <marcocassar@mdcusa.net>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Environment :: Console
+Requires-Dist: duckdb>=1.5.3
+Requires-Dist: mcp[cli]>=1.27.2
+Requires-Dist: python-frontmatter>=1.3.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/Ocramaru/quackspace
+Project-URL: Repository, https://github.com/Ocramaru/quackspace
+Project-URL: Issues, https://github.com/Ocramaru/quackspace/issues
+Description-Content-Type: text/markdown
+
+# quack
+
+A DuckDB-backed knowledge layer over your local work — any files: notes, docs,
+code, configs, assets — that helps LLMs navigate everything. It generates a
+cheap, precise meta layer from your files; you author metadata in one editable
+place (`.index.yaml`), and everything else is derived. Plays well with Obsidian
+but does not require it.
+
+PyPI package: `quackspace` · command: `quack`
+
+## Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Ocramaru/quackspace/main/install.sh | bash
+```
+
+This installs `uv` (if needed) and the `quack` CLI globally. Then create a space
+anywhere:
+
+```bash
+quack init my-workspace   # make & scaffold the folder (or `quack init` to use the current one)
+cd my-workspace
+quack mcp install         # connect an LLM (Claude Code, Kiro, …) over MCP
+```
+
+Prefer Python packaging? `uv tool install quackspace` (or `pipx install
+quackspace`) does the same as the one-liner's second step.
+
+### Releasing
+
+Releases publish to PyPI via GitHub Actions + Trusted Publishing (no stored
+token). One-time: add a PyPI *pending publisher* (project `quackspace`, owner
+`Ocramaru`, repo `quackspace`, workflow `publish.yml`, environment `pypi`) and a
+GitHub environment named `pypi`. Then bump `version` in `pyproject.toml`, tag,
+and publish a GitHub Release — the workflow builds and uploads. Manual fallback:
+`uv build && uv publish --token <pypi-token>`.
+
+## Architecture
+
+```
+<your-root>/                ← any directory; quack finds it by the .quack/ marker
+├── .quack/                 ← the toolkit (and the root marker)
+│   ├── GUIDE.md            hand-written: how an AI should search the tree
+│   ├── map.yaml            GENERATED: folder tree + folder descriptions
+│   ├── quack.duckdb        GENERATED: catalog (files, tags, links, FTS) — the queryable store
+│   ├── diagram.md          GENERATED: whole-graph Mermaid link diagram
+│   ├── config.yaml         your AI assistant choice
+│   └── src/quack/          the CLI + library
+├── .quackignore            optional: extra ignore patterns
+├── QUACK.md                visible navigation anchor for LLMs
+├── src/  docs/  notes/ …   ANY files: code, configs, markdown, assets
+│   ├── .index.yaml         EDITABLE: per-file description + tags (links derived)
+│   └── _diagrams.md        GENERATED: this folder's Mermaid link graph
+└── …
+```
+
+**One rule:** the only thing you edit is each folder's `.index.yaml`
+(description + tags per file; Markdown may also use frontmatter). `quack reindex`
+MERGES it — preserving your text — and regenerates every map, catalog, and
+diagram from the files + `[[wikilinks]]`, so the navigation layer can never
+drift. The root can be named anything; quack locates it by walking up for
+`.quack/` (like git finds `.git`).
+
+## The catalog (DuckDB)
+
+`quack reindex` builds `.quack/quack.duckdb`, a single embedded catalog of all
+metadata: `files` (name, rel, folder, ext, description, tags_csv, n_links,
+n_inbound, is_orphan, is_binary, file_modified, described_at, stale, body),
+`tags(name, tag)`, and `links(src, dst, dst_exists)`, plus a BM25 full-text
+index over name/description/body. (`stale` is true when a file changed after its
+description was written — see `quack generate --stale`.)
+
+It is the queryable store and **the graph lives here too**: the `links` table
+is the edge list, and multi-hop traversal is a recursive CTE behind
+`quack search` and `quack graph`. There is no separate graph.json: a query
+pulls only the relevant slice into context instead of loading the whole graph,
+which matters as the tree grows. The catalog is derived, never authoritative;
+delete it and `quack reindex` rebuilds it from the files.
+
+```bash
+quack sql "SELECT folder, count(*) FROM files GROUP BY folder"
+quack sql "SELECT rel FROM files WHERE stale"                 # descriptions to refresh
+quack sql "SELECT src, dst FROM links WHERE NOT dst_exists"   # broken links
+quack search "regex" --fts                                    # BM25 ranking
+quack graph path file-a file-b                                # shortest link path
+```
+
+## The `quack` command
+
+Once installed (see [Install](#install)), `quack` is on your PATH and finds the
+root from any directory inside it by walking up for `.quack/` — so commands work
+no matter where you invoke them. (Developing on a checkout instead? `uv run
+quack` inside `.quack/` is the equivalent.)
+
+```bash
+quack init [dir]       # create & scaffold a new space (dir, or the current folder)
+quack reindex          # regenerate everything (indexes, map, catalog, diagrams)
+quack reindex --no-diagrams
+quack diagram          # diagrams only
+quack doctor           # check files + MCP registration
+quack doctor --files   # only files;  --mcp only MCP;  --strict to fail on issues
+quack new "Title" -f projects -d "one-line description" -t tag,tag   # new markdown note
+quack describe PATH -d "…" -t tag,tag   # record a description + tags for any file
+quack setup            # choose the AI assistant (arrow-key menu)
+quack generate         # AI: write description + tags for files missing one
+quack generate --stale # also refresh descriptions whose file changed since
+quack search "terms"   # auto-hybrid: structural + FTS + semantic + graph
+quack search "terms" --fts        # force DuckDB BM25 full-text ranking
+quack search "terms" --semantic   # force vss semantic ranking
+quack embed            # build semantic embeddings (DuckDB vss)
+quack graph path|central|clusters # graph queries
+quack sql "SELECT ..." # query the catalog directly
+quack mcp install      # register the MCP server with clients
+quack where            # show root / toolkit / command paths
+```
+
+Root resolution: `--root` > walk up for `.quack/` > `$QUACK_ROOT` >
+`$OBSIDIAN_VAULT` > the package location.
+
+## LLM access (MCP)
+
+`quack mcp install` writes a project-root `.mcp.json` (the auto-discover
+convention Claude Code and others pick up) and offers to register with installed
+client CLIs (kiro-cli, claude). The server exposes typed tools, `map`, `search`,
+`get_file`, `sql`, `graph_path`, `central`, `clusters` (read), plus `describe`
+and `reindex` (write), each returning `root` so the LLM can join `root` +
+relative path. `QUACK.md` at the root is a visible anchor telling any LLM how to
+navigate even without MCP.
+
+**Seeding quack on a repo an agent already knows.** Point the MCP server at a
+codebase and ask the assistant to annotate it: for each relevant file it calls
+`describe(path, description, tags)` (writing into `.index.yaml` — the file
+itself is untouched), then `reindex()` once. No per-file model shell-out; the
+agent records what it already understands, and the catalog becomes searchable.
+
+## AI is optional
+
+The assistant is used for one thing: writing short descriptions + tags for your
+files (`quack generate`) so the search index is rich. quack works fully without
+it — you just author descriptions yourself by editing each folder's
+`.index.yaml`.
+
+- `quack setup` shows an arrow-key menu of assistants (kiro-cli, claude, a
+  custom command, or "use without AI"), probes which are installed, and writes
+  the choice to `.quack/config.yaml`. `quack init` is an alias that runs it.
+- `quack generate` fills in missing descriptions using that command. If none is
+  set up, it explains what the AI is for and offers to run setup.
+- Set `ai.skip: true` in `config.yaml` to use quack without AI permanently;
+  `generate` then stops offering to set one up.
+- Swap assistants anytime by editing `ai.command` (use `{prompt}` for the
+  prompt, or omit it to pipe on stdin) or re-running `quack setup`.
+
+## Keeping it in sync
+
+Run `quack reindex` after structural changes. To automate, wire it to one of:
+- Obsidian **Shell Commands** plugin (run on save),
+- a git **pre-commit** hook (`quack doctor --strict --files && quack reindex`),
+- a file-watcher,
+- `quack kiro install` (writes a Kiro reindex-on-save hook).

quackspace-0.1.0/README.md

@@ -0,0 +1,159 @@
+# quack
+
+A DuckDB-backed knowledge layer over your local work — any files: notes, docs,
+code, configs, assets — that helps LLMs navigate everything. It generates a
+cheap, precise meta layer from your files; you author metadata in one editable
+place (`.index.yaml`), and everything else is derived. Plays well with Obsidian
+but does not require it.
+
+PyPI package: `quackspace` · command: `quack`
+
+## Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Ocramaru/quackspace/main/install.sh | bash
+```
+
+This installs `uv` (if needed) and the `quack` CLI globally. Then create a space
+anywhere:
+
+```bash
+quack init my-workspace   # make & scaffold the folder (or `quack init` to use the current one)
+cd my-workspace
+quack mcp install         # connect an LLM (Claude Code, Kiro, …) over MCP
+```
+
+Prefer Python packaging? `uv tool install quackspace` (or `pipx install
+quackspace`) does the same as the one-liner's second step.
+
+### Releasing
+
+Releases publish to PyPI via GitHub Actions + Trusted Publishing (no stored
+token). One-time: add a PyPI *pending publisher* (project `quackspace`, owner
+`Ocramaru`, repo `quackspace`, workflow `publish.yml`, environment `pypi`) and a
+GitHub environment named `pypi`. Then bump `version` in `pyproject.toml`, tag,
+and publish a GitHub Release — the workflow builds and uploads. Manual fallback:
+`uv build && uv publish --token <pypi-token>`.
+
+## Architecture
+
+```
+<your-root>/                ← any directory; quack finds it by the .quack/ marker
+├── .quack/                 ← the toolkit (and the root marker)
+│   ├── GUIDE.md            hand-written: how an AI should search the tree
+│   ├── map.yaml            GENERATED: folder tree + folder descriptions
+│   ├── quack.duckdb        GENERATED: catalog (files, tags, links, FTS) — the queryable store
+│   ├── diagram.md          GENERATED: whole-graph Mermaid link diagram
+│   ├── config.yaml         your AI assistant choice
+│   └── src/quack/          the CLI + library
+├── .quackignore            optional: extra ignore patterns
+├── QUACK.md                visible navigation anchor for LLMs
+├── src/  docs/  notes/ …   ANY files: code, configs, markdown, assets
+│   ├── .index.yaml         EDITABLE: per-file description + tags (links derived)
+│   └── _diagrams.md        GENERATED: this folder's Mermaid link graph
+└── …
+```
+
+**One rule:** the only thing you edit is each folder's `.index.yaml`
+(description + tags per file; Markdown may also use frontmatter). `quack reindex`
+MERGES it — preserving your text — and regenerates every map, catalog, and
+diagram from the files + `[[wikilinks]]`, so the navigation layer can never
+drift. The root can be named anything; quack locates it by walking up for
+`.quack/` (like git finds `.git`).
+
+## The catalog (DuckDB)
+
+`quack reindex` builds `.quack/quack.duckdb`, a single embedded catalog of all
+metadata: `files` (name, rel, folder, ext, description, tags_csv, n_links,
+n_inbound, is_orphan, is_binary, file_modified, described_at, stale, body),
+`tags(name, tag)`, and `links(src, dst, dst_exists)`, plus a BM25 full-text
+index over name/description/body. (`stale` is true when a file changed after its
+description was written — see `quack generate --stale`.)
+
+It is the queryable store and **the graph lives here too**: the `links` table
+is the edge list, and multi-hop traversal is a recursive CTE behind
+`quack search` and `quack graph`. There is no separate graph.json: a query
+pulls only the relevant slice into context instead of loading the whole graph,
+which matters as the tree grows. The catalog is derived, never authoritative;
+delete it and `quack reindex` rebuilds it from the files.
+
+```bash
+quack sql "SELECT folder, count(*) FROM files GROUP BY folder"
+quack sql "SELECT rel FROM files WHERE stale"                 # descriptions to refresh
+quack sql "SELECT src, dst FROM links WHERE NOT dst_exists"   # broken links
+quack search "regex" --fts                                    # BM25 ranking
+quack graph path file-a file-b                                # shortest link path
+```
+
+## The `quack` command
+
+Once installed (see [Install](#install)), `quack` is on your PATH and finds the
+root from any directory inside it by walking up for `.quack/` — so commands work
+no matter where you invoke them. (Developing on a checkout instead? `uv run
+quack` inside `.quack/` is the equivalent.)
+
+```bash
+quack init [dir]       # create & scaffold a new space (dir, or the current folder)
+quack reindex          # regenerate everything (indexes, map, catalog, diagrams)
+quack reindex --no-diagrams
+quack diagram          # diagrams only
+quack doctor           # check files + MCP registration
+quack doctor --files   # only files;  --mcp only MCP;  --strict to fail on issues
+quack new "Title" -f projects -d "one-line description" -t tag,tag   # new markdown note
+quack describe PATH -d "…" -t tag,tag   # record a description + tags for any file
+quack setup            # choose the AI assistant (arrow-key menu)
+quack generate         # AI: write description + tags for files missing one
+quack generate --stale # also refresh descriptions whose file changed since
+quack search "terms"   # auto-hybrid: structural + FTS + semantic + graph
+quack search "terms" --fts        # force DuckDB BM25 full-text ranking
+quack search "terms" --semantic   # force vss semantic ranking
+quack embed            # build semantic embeddings (DuckDB vss)
+quack graph path|central|clusters # graph queries
+quack sql "SELECT ..." # query the catalog directly
+quack mcp install      # register the MCP server with clients
+quack where            # show root / toolkit / command paths
+```
+
+Root resolution: `--root` > walk up for `.quack/` > `$QUACK_ROOT` >
+`$OBSIDIAN_VAULT` > the package location.
+
+## LLM access (MCP)
+
+`quack mcp install` writes a project-root `.mcp.json` (the auto-discover
+convention Claude Code and others pick up) and offers to register with installed
+client CLIs (kiro-cli, claude). The server exposes typed tools, `map`, `search`,
+`get_file`, `sql`, `graph_path`, `central`, `clusters` (read), plus `describe`
+and `reindex` (write), each returning `root` so the LLM can join `root` +
+relative path. `QUACK.md` at the root is a visible anchor telling any LLM how to
+navigate even without MCP.
+
+**Seeding quack on a repo an agent already knows.** Point the MCP server at a
+codebase and ask the assistant to annotate it: for each relevant file it calls
+`describe(path, description, tags)` (writing into `.index.yaml` — the file
+itself is untouched), then `reindex()` once. No per-file model shell-out; the
+agent records what it already understands, and the catalog becomes searchable.
+
+## AI is optional
+
+The assistant is used for one thing: writing short descriptions + tags for your
+files (`quack generate`) so the search index is rich. quack works fully without
+it — you just author descriptions yourself by editing each folder's
+`.index.yaml`.
+
+- `quack setup` shows an arrow-key menu of assistants (kiro-cli, claude, a
+  custom command, or "use without AI"), probes which are installed, and writes
+  the choice to `.quack/config.yaml`. `quack init` is an alias that runs it.
+- `quack generate` fills in missing descriptions using that command. If none is
+  set up, it explains what the AI is for and offers to run setup.
+- Set `ai.skip: true` in `config.yaml` to use quack without AI permanently;
+  `generate` then stops offering to set one up.
+- Swap assistants anytime by editing `ai.command` (use `{prompt}` for the
+  prompt, or omit it to pipe on stdin) or re-running `quack setup`.
+
+## Keeping it in sync
+
+Run `quack reindex` after structural changes. To automate, wire it to one of:
+- Obsidian **Shell Commands** plugin (run on save),
+- a git **pre-commit** hook (`quack doctor --strict --files && quack reindex`),
+- a file-watcher,
+- `quack kiro install` (writes a Kiro reindex-on-save hook).

quackspace-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "quackspace"
+version = "0.1.0"
+description = "A DuckDB-backed knowledge layer over your local work that helps LLMs navigate everything"
+readme = "README.md"
+authors = [
+    { name = "Marco Cassar", email = "marcocassar@mdcusa.net" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "llm", "mcp", "rag", "knowledge-base", "search", "duckdb",
+    "obsidian", "markdown", "notes", "retrieval", "agent",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: POSIX",
+    "Operating System :: MacOS",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Text Processing :: Indexing",
+    "Environment :: Console",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "duckdb>=1.5.3",
+    "mcp[cli]>=1.27.2",
+    "python-frontmatter>=1.3.0",
+    "pyyaml>=6.0.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/Ocramaru/quackspace"
+Repository = "https://github.com/Ocramaru/quackspace"
+Issues = "https://github.com/Ocramaru/quackspace/issues"
+
+[project.scripts]
+quack = "quack.cli:main"
+quack-mcp = "quack.mcp_server:main"
+
+[build-system]
+requires = ["uv_build>=0.11.15,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "quack"

quackspace-0.1.0/src/quack/__init__.py

@@ -0,0 +1,3 @@
+"""quack, a knowledge layer over your local work that helps LLMs navigate it."""
+
+__version__ = "0.1.0"

quackspace-0.1.0/src/quack/catalog.py

@@ -0,0 +1,217 @@
+"""The meta collection: one DuckDB catalog of all file metadata.
+
+`quack reindex` rebuilds `.quack/quack.duckdb` from the files (+ the editable
+.index.yaml store). It is a derived artifact, never the source of truth, so it
+can be deleted and regenerated at any time. DuckDB is embedded (no server) and
+gives real SQL plus BM25 full-text search over everything, the fast metadata
+search `ls` can't do.
+
+Schema:
+    files(name, rel, folder, ext, title, description, tags_csv, n_links,
+          n_inbound, is_orphan, is_binary, file_modified, described_at, stale,
+          body)
+    tags(name, tag)                  -- one row per (file, tag)
+    links(src, dst, dst_exists)      -- one row per wikilink edge
+A DuckDB FTS index is built over files(name, description, body) for `match_bm25`.
+`stale` is true when the file changed after its description was written.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import Path
+
+import duckdb
+
+from .core import Space
+
+DB_NAME = "quack.duckdb"
+
+
+def db_path(space: Space) -> Path:
+    return space.root / ".quack" / DB_NAME
+
+
+def build(space: Space) -> dict:
+    """Rebuild the catalog from scratch over the loaded space. Returns a
+    summary. The space already carries effective metadata (authored .index.yaml
+    overlaid on each file)."""
+    path = db_path(space)
+    if path.exists():
+        path.unlink()  # rebuild clean; the files + .index.yaml are the truth
+
+    names = set(space.by_name)
+    inbound: dict[str, int] = defaultdict(int)
+    for e in space.entries:
+        for target in e.links:
+            if target in names:
+                inbound[target] += 1
+
+    con = duckdb.connect(str(path))
+    try:
+        _create_schema(con)
+        for e in space.entries:
+            con.execute(
+                "INSERT INTO files VALUES "
+                "(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                [
+                    e.name,
+                    e.rel,
+                    e.folder,
+                    e.ext,
+                    e.name,
+                    e.description,
+                    ",".join(e.tags),
+                    len(e.links),
+                    inbound.get(e.name, 0),
+                    inbound.get(e.name, 0) == 0 and len(e.links) == 0,
+                    e.is_binary,
+                    e.modified,
+                    e.described_at,
+                    e.stale,
+                    e.body,
+                ],
+            )
+            for tag in e.tags:
+                con.execute("INSERT INTO tags VALUES (?, ?)", [e.name, tag])
+            for dst in e.links:
+                con.execute(
+                    "INSERT INTO links VALUES (?, ?, ?)",
+                    [e.name, dst, dst in names],
+                )
+        _build_fts(con)
+        n_files = con.execute("SELECT count(*) FROM files").fetchone()[0]
+        n_tags = con.execute("SELECT count(*) FROM tags").fetchone()[0]
+        n_links = con.execute("SELECT count(*) FROM links").fetchone()[0]
+    finally:
+        con.close()
+
+    return {"db": str(path), "files": n_files, "tags": n_tags, "links": n_links}
+
+
+def _create_schema(con: duckdb.DuckDBPyConnection) -> None:
+    con.execute(
+        """
+        CREATE TABLE files (
+            name        VARCHAR,
+            rel         VARCHAR,
+            folder      VARCHAR,
+            ext         VARCHAR,
+            title       VARCHAR,
+            description VARCHAR,
+            tags_csv    VARCHAR,
+            n_links     INTEGER,
+            n_inbound   INTEGER,
+            is_orphan   BOOLEAN,
+            is_binary   BOOLEAN,
+            file_modified VARCHAR,
+            described_at  VARCHAR,
+            stale         BOOLEAN,
+            body        VARCHAR
+        );
+        CREATE TABLE tags  (name VARCHAR, tag VARCHAR);
+        CREATE TABLE links (src VARCHAR, dst VARCHAR, dst_exists BOOLEAN);
+        """
+    )
+
+
+def _build_fts(con: duckdb.DuckDBPyConnection) -> None:
+    """Create the BM25 full-text index over the searchable note fields."""
+    con.execute("INSTALL fts; LOAD fts;")
+    con.execute(
+        "PRAGMA create_fts_index('files', 'name', 'name', 'description', 'body', "
+        "overwrite=1);"
+    )
+
+
+def connect(explicit_root: str | None = None) -> duckdb.DuckDBPyConnection:
+    """Open the catalog read-only for querying. Caller closes it."""
+    space = Space.load(explicit_root)
+    path = db_path(space)
+    if not path.exists():
+        raise RuntimeError(
+            f"No catalog at {path}. Run `quack reindex` to build it."
+        )
+    return duckdb.connect(str(path), read_only=True)
+
+
+def query(sql: str, explicit_root: str | None = None) -> tuple[list[str], list[tuple]]:
+    """Run a SQL query against the catalog. Returns (column_names, rows)."""
+    con = connect(explicit_root)
+    try:
+        cur = con.execute(sql)
+        cols = [d[0] for d in cur.description] if cur.description else []
+        return cols, cur.fetchall()
+    finally:
+        con.close()
+
+
+def neighbours(
+    names: list[str], explicit_root: str | None = None, hops: int = 1
+) -> list[tuple[str, str, int, str]]:
+    """Graph traversal in SQL: notes within `hops` of any seed name, in either
+    link direction. Returns [(name, rel, distance, via_seed), ...], excluding
+    the seeds, where via_seed is one seed that reaches the note at min distance.
+
+    Uses a recursive CTE so only the relevant subgraph is materialized, the
+    whole point of keeping the graph in DuckDB instead of a flat file.
+    """
+    if not names:
+        return []
+    con = connect(explicit_root)
+    try:
+        placeholders = ",".join("?" for _ in names)
+        rows = con.execute(
+            f"""
+            WITH RECURSIVE
+            -- undirected edge view over existing notes only
+            edge(a, b) AS (
+                SELECT src, dst FROM links WHERE dst_exists
+                UNION ALL
+                SELECT dst, src FROM links WHERE dst_exists
+            ),
+            walk(name, dist, seed) AS (
+                SELECT name, 0, name FROM files WHERE name IN ({placeholders})
+                UNION
+                SELECT e.b, w.dist + 1, w.seed
+                FROM walk w JOIN edge e ON e.a = w.name
+                WHERE w.dist < ?
+            ),
+            ranked AS (
+                SELECT w.name, n.rel, w.dist, w.seed,
+                       row_number() OVER (PARTITION BY w.name ORDER BY w.dist) AS rn
+                FROM walk w JOIN files n ON n.name = w.name
+                WHERE w.dist > 0
+                  AND w.name NOT IN ({placeholders})  -- a seed is not its own neighbour
+            )
+            SELECT name, rel, dist, seed FROM ranked WHERE rn = 1
+            ORDER BY dist, name
+            """,
+            [*names, hops, *names],
+        ).fetchall()
+        return rows
+    finally:
+        con.close()
+
+
+def fts_search(
+    terms: str, explicit_root: str | None = None, limit: int = 10
+) -> list[tuple[str, str, float]]:
+    """BM25 full-text search. Returns [(rel, description, score), ...]."""
+    con = connect(explicit_root)
+    try:
+        rows = con.execute(
+            """
+            SELECT rel, description, score FROM (
+                SELECT rel, description,
+                       fts_main_files.match_bm25(name, ?) AS score
+                FROM files
+            ) WHERE score IS NOT NULL
+            ORDER BY score DESC
+            LIMIT ?
+            """,
+            [terms, limit],
+        ).fetchall()
+        return rows
+    finally:
+        con.close()