feat(pi): add qmd package

Author: edmundmiller

config/pi/settings.jsonc

@@ -65,6 +65,8 @@
     "~/.config/dotfiles/pi-packages/pi-dcp",
     // Agentic context management (/acm, /context, context_* tools) - https://github.com/ttttmr/pi-context
     "npm:pi-context",
+    // Repo-local QMD workflow (/qmd, /qp) and qmd-cli-first guidance
+    "~/.config/dotfiles/pi-packages/pi-qmd",
     // Secure web fetch – HTML→markdown via mdream, secret scanning, injection detection
     "~/.config/dotfiles/pi-packages/pi-scurl",
     // Auto-load direnv env at session start

modules/shell/pi/default.nix

@@ -284,6 +284,41 @@ in
           ''
         );
 
+        # QMD depends on native modules (better-sqlite3/sqlite-vec), so install
+        # its local package deps in the mutable repo instead of a Nix-store
+        # node_modules symlink.
+        home.activation.pi-qmd-deps = lib.hm.dag.entryAfter [ "writeBoundary" ] ''
+          pkg_dir="$HOME/.config/dotfiles/pi-packages/pi-qmd"
+          lock_file="$pkg_dir/package-lock.json"
+          stamp_file="$pkg_dir/.node-modules-lock-sha256"
+          npm_bin="${pkgs.nodejs}/bin/npm"
+          node_bin_dir="${pkgs.nodejs}/bin"
+          sha_bin="${pkgs.coreutils}/bin/sha256sum"
+
+          if [ -f "$lock_file" ] && [ -x "$npm_bin" ]; then
+            current_sha="$($sha_bin "$lock_file" | ${pkgs.coreutils}/bin/cut -d' ' -f1)"
+            saved_sha="$(cat "$stamp_file" 2>/dev/null || true)"
+            needs_install=0
+
+            if [ ! -d "$pkg_dir/node_modules/@tobilu/qmd" ]; then
+              needs_install=1
+            elif [ "$current_sha" != "$saved_sha" ]; then
+              needs_install=1
+            fi
+
+            if [ -L "$pkg_dir/node_modules" ]; then
+              rm -f "$pkg_dir/node_modules"
+              needs_install=1
+            fi
+
+            if [ "$needs_install" -eq 1 ]; then
+              echo "Installing pi-qmd npm deps..."
+              (cd "$pkg_dir" && PATH="$node_bin_dir:$PATH" "$npm_bin" ci --workspaces=false --omit=dev) || echo "Warning: pi-qmd npm install failed."
+              printf '%s\n' "$current_sha" > "$stamp_file"
+            fi
+          fi
+        '';
+
         # Pi binary now provided by pkgs.llm-agents.pi (nix-managed).
         # Pi-package deps now provided via Nix-built node_modules (home.file symlinks above).
         # This activation handles remaining bun-dependent extras only.

pi-packages/.gitignore

@@ -1 +1,2 @@
 node_modules/
+.node-modules-lock-sha256

pi-packages/pi-qmd/README.md

@@ -0,0 +1,135 @@
+# QMD Extension
+
+Repo-local QMD infrastructure for Pi.
+
+## What it does
+
+- Detects whether the current repo is indexed by QMD
+- Tracks repo freshness via `.pi/qmd.json`
+- Adds a quiet footer for indexed repos only
+- Injects short guidance so the agent knows when to use `qmd query/search/get` via `bash`
+- Provides an interactive split-pane TUI panel (`/qmd`, `/qp`, `Ctrl+Alt+Q`) with:
+  - Persistent collection sidebar (left) — always visible, navigate with `j/k`, filter with `/`
+  - Context-sensitive main pane (right) — overview, files, or search view
+  - Interactive search with debounced lex results and hybrid mode (`ctrl+t`)
+  - File browser with NERDTree-style tree and index toggle
+  - In-panel update (`u`, bound only) and init (`i`) actions
+  - `tab` switches focus between sidebar and main pane
+- Provides subcommands: `/qmd status`, `/qmd update`, `/qmd init`
+
+## What it does not do
+
+- It does **not** expose an always-on search tool
+- It does **not** intercept or rewrite search queries automatically
+- It does **not** mirror QMD config into repo files
+
+The extension owns infra and workflow. The agent still uses the QMD CLI directly for retrieval.
+
+## Source of truth
+
+- **QMD store** — collections and path contexts
+- **`.pi/qmd.json`** — repo binding and freshness marker only
+
+## Commands
+
+### `/qmd` (no args) · `/qp` · `Ctrl+Alt+Q`
+
+Opens the QMD index dashboard as a split-pane panel. Left pane shows all collections; right pane shows overview, files, or search for the selected collection. Use `tab` to switch focus, `s` to search, `f` for files. See `docs/panel.md` for full keyboard shortcuts and layout.
+
+When `hasUI` is false, prints a plain-text summary instead.
+
+### `/qmd status`
+
+Shows current repo state only:
+
+- indexed / not indexed / unavailable
+- repo root
+- collection key
+- freshness state
+- repair notes when marker/store drift is detected
+
+### `/qmd update`
+
+Updates the **current repo collection only**.
+It never reindexes all collections by default.
+
+### `/qmd init`
+
+Starts a deterministic onboarding flow:
+
+1. scan repo
+2. build draft proposal
+3. let the agent refine it with the user
+4. execute `qmd_init` only after explicit confirmation
+
+## Setup
+
+This repo currently expects the local QMD fork to be linked via Bun:
+
+- package: `@tobilu/qmd`
+- local fork: `~/git/qmd-fork`
+- link style: `bun link`
+
+## File layout
+
+```
+extensions/qmd/
+├── index.ts                    # Extension entry point
+├── core/
+│   ├── errors.ts               # Agent-legible typed errors
+│   ├── qmd-store.ts            # SDK wrapper with lazy lifecycle
+│   └── types.ts                # Zod schemas + TypeBox tool params
+├── domain/
+│   ├── freshness.ts            # Git-based markdown freshness
+│   ├── onboarding.ts           # Deterministic init pipeline
+│   └── repo-binding.ts         # Repo root, collection key, marker I/O
+├── extension/
+│   ├── command.ts              # Slash commands, alias, shortcut, panel lifecycle
+│   ├── runtime.ts              # Session hooks, footer, prompt injection
+│   └── tool.ts                 # Workflow-scoped qmd_init tool
+├── ui/
+│   ├── constants.ts            # Panel constants (width, shortcuts, icon)
+│   ├── data.ts                 # Snapshot builder, file tree, helpers
+│   ├── panel.ts                # Split-pane TUI panel (sidebar + main: overview/files/search)
+│   └── plain-text.ts           # Non-TUI fallback summary
+├── diy/
+│   ├── README.md               # How to copy/paste this blueprint into another repo
+│   ├── qmd-extension-snapshot-spec.md
+│   ├── qmd-extension-diy-execution-plan.md
+│   ├── agent-prompt-template.md
+│   └── references.md
+├── docs/
+│   ├── architecture.md         # Layer diagram and responsibilities
+│   ├── freshness.md            # Freshness model and footer behavior
+│   ├── onboarding.md           # Init flow steps and caveats
+│   └── panel.md                # Panel states, keyboard shortcuts, data flow
+└── __tests__/
+    ├── core/
+    │   ├── qmd-store.test.ts
+    │   └── types.test.ts
+    ├── domain/
+    │   ├── freshness.test.ts
+    │   ├── onboarding.test.ts
+    │   └── repo-binding.test.ts
+    ├── extension/
+    │   └── runtime.test.ts
+    └── ui/
+        └── data.test.ts
+```
+
+## DIY blueprint
+
+If you want to recreate this extension in another repo without installing this package, use:
+
+- `diy/README.md` — copy/paste usage instructions
+- `diy/qmd-extension-snapshot-spec.md` — current behavior blueprint
+- `diy/qmd-extension-diy-execution-plan.md` — implementation milestones
+- `diy/references.md` — internal docs + agent-memory raw links
+- `diy/agent-prompt-template.md` — copy/paste prompt for rebuilding elsewhere
+
+## Docs
+
+- `docs/architecture.md` — layers, dependency direction, file responsibilities
+- `docs/onboarding.md` — init flow steps and caveats
+- `docs/freshness.md` — freshness model and footer behavior
+- `docs/panel.md` — panel states, keyboard shortcuts, data flow

pi-packages/pi-qmd/__tests__/core/handelize.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { handelize_path } from "../../core/qmd-store.js";
+
+describe("handelize_path", () => {
+  it("lowercases paths", () => {
+    expect(handelize_path("docs/ARCHITECTURE.md")).toBe("docs/architecture.md");
+  });
+
+  it("strips leading dots from directory segments", () => {
+    expect(handelize_path(".pi/tracks/summary.md")).toBe("pi/tracks/summary.md");
+  });
+
+  it("replaces non-alphanumeric chars with hyphens", () => {
+    expect(handelize_path("docs/my file (1).md")).toBe("docs/my-file-1.md");
+  });
+
+  it("preserves file extension", () => {
+    expect(handelize_path("README.md")).toBe("readme.md");
+    expect(handelize_path("notes.mdx")).toBe("notes.mdx");
+  });
+
+  it("collapses multiple special chars into single hyphen", () => {
+    expect(handelize_path("docs/a---b___c.md")).toBe("docs/a-b-c.md");
+  });
+
+  it("strips leading/trailing hyphens from segments", () => {
+    expect(handelize_path("-docs-/--file--.md")).toBe("docs/file.md");
+  });
+
+  it("handles deeply nested paths", () => {
+    expect(handelize_path(".pi/tracks/agent-memory/workstreams/notes.md")).toBe(
+      "pi/tracks/agent-memory/workstreams/notes.md"
+    );
+  });
+
+  it("filters out empty segments", () => {
+    expect(handelize_path("docs//nested/file.md")).toBe("docs/nested/file.md");
+  });
+});

pi-packages/pi-qmd/__tests__/core/qmd-store.test.ts

@@ -0,0 +1,65 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+beforeEach(() => {
+  vi.resetModules();
+});
+
+describe("core/qmd-store", () => {
+  it("lists collections through the SDK wrapper", async () => {
+    vi.doMock("@tobilu/qmd", () => ({
+      createStore: vi.fn(async () => ({
+        listCollections: async () => [
+          {
+            name: "demo",
+            pwd: "/tmp/demo",
+            glob_pattern: "**/*.md",
+            doc_count: 1,
+            active_count: 1,
+            last_modified: null,
+            includeByDefault: true,
+          },
+        ],
+        close: async () => {},
+      })),
+    }));
+
+    const module = await import("../../core/qmd-store.js");
+    const collections = await module.list_collections();
+    expect(collections[0]?.name).toBe("demo");
+    await module.close_store();
+  });
+
+  it("normalizes SDK status collection counts", async () => {
+    vi.doMock("@tobilu/qmd", () => ({
+      createStore: vi.fn(async () => ({
+        getStatus: async () => ({
+          totalDocuments: 3,
+          needsEmbedding: 0,
+          hasVectorIndex: true,
+          collections: [
+            { name: "agents", path: "/repo", pattern: "**/*.md", documents: 3 },
+            { name: "legacy", path: "/repo", pattern: "**/*.md", documentCount: 2 },
+            { name: "snake", path: "/repo", pattern: "**/*.md", doc_count: 1 },
+          ],
+        }),
+        close: async () => {},
+      })),
+    }));
+
+    const module = await import("../../core/qmd-store.js");
+    const status = await module.get_status();
+    expect(status.collections.map((c) => c.documentCount)).toEqual([3, 2, 1]);
+    await module.close_store();
+  });
+
+  it("translates SDK failures into QmdUnavailableError", async () => {
+    vi.doMock("@tobilu/qmd", () => ({
+      createStore: vi.fn(async () => {
+        throw new Error("boom");
+      }),
+    }));
+
+    const module = await import("../../core/qmd-store.js");
+    await expect(module.list_collections()).rejects.toThrow("QMD is unavailable");
+  });
+});

pi-packages/pi-qmd/__tests__/core/types.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { qmd_init_params_schema, qmd_repo_marker_schema } from "../../core/types.js";
+
+describe("qmd_repo_marker_schema", () => {
+  it("accepts a valid marker", () => {
+    const result = qmd_repo_marker_schema.parse({
+      schema_version: 1,
+      repo_root: "/tmp/repo",
+      collection_key: "p_L3RtcC9yZXBv",
+      last_indexed_at: "2026-03-13T12:00:00.000Z",
+      last_indexed_commit: "abc123",
+      created_at: "2026-03-13T11:00:00.000Z",
+    });
+
+    expect(result.collection_key).toBe("p_L3RtcC9yZXBv");
+  });
+
+  it("rejects the wrong schema version", () => {
+    const result = qmd_repo_marker_schema.safeParse({
+      schema_version: 2,
+      repo_root: "/tmp/repo",
+      collection_key: "p_x",
+      last_indexed_at: "now",
+      last_indexed_commit: "abc123",
+      created_at: "now",
+    });
+
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("qmd_init_params_schema", () => {
+  it("accepts valid onboarding input", () => {
+    const result = qmd_init_params_schema.parse({
+      root: "/tmp/repo",
+      glob_pattern: "**/*.md",
+      paths: [{ path: "docs", annotation: "Documentation" }],
+    });
+
+    expect(result.paths).toHaveLength(1);
+  });
+
+  it("requires a non-empty root", () => {
+    const result = qmd_init_params_schema.safeParse({
+      root: "",
+      paths: [],
+    });
+
+    expect(result.success).toBe(false);
+  });
+});