Engineering plans
How Garage is going to change, written down before the code. Each plan records the problem, the measurements or research behind it, the design, the milestones and the decisions still open, and keeps a status line as the work lands. They live in docs/plans/ in the repository; the way to discuss one is an issue or a pull request that edits it.
Parser isolation
Read every document in a helper process, behind a validation layer, so a file that crashes or hangs a parser costs that file and nothing else, never the app or its database.
Read the plan →The garage_rag Python Package over Rust
How the garage_rag package on PyPI keeps its name and the 1.5.0 API while the code underneath becomes Garage's Rust. The 1.5.0 surface module by module, what each name maps to in the Rust crates, the console scripts that ship first, the version, and the Python layer that will carry the library API.
Read the plan →Swift and Rust Interop
How the XPC services call their Rust workers and how Rust calls Swift-only APIs. UniFFI for the hosts' wide, callback-heavy APIs; a cbindgen-generated C ABI for the reader plugins; swift-rs for Rust calling Swift. A pilot on the embed worker.
Read the plan →OCR for the Rust Ingester
Which engine reads text from pictures once the image reader leaves Python. Apple Vision in-process on the Mac, Tesseract linked statically for the Windows CLI, and a vision model over XPC as an opt-in later, all behind one engine trait in rust/garage-ocr.
Read the plan →Access hooks
The seams an extension needs to decide which search results each caller sees, whether the caller is the app, an MCP assistant or a remote client. Garage itself ships no policy, and with no extension installed nothing changes.
Read the plan →Rust Components and Reader Plugins
Moving the ingester's components from Python to Rust one at a time, starting with the text reader, behind a new gRPC contract between the ingester and its reader plugins that Swift, .NET and Python all speak.
Read the plan →Rust Hot Paths — Native Kernels for Ingest
Moving the ingest pipeline's measured CPU hot spots (the quality gate, the text splitters and the walker's per-file pass) into one Rust library loaded through ctypes, with the Python code kept as the reference implementation and the golden tests as the conformance suite.
Read the plan →1.5 Beta — IPC Hardening
Moving Garage's gRPC, llama.cpp and Postgres endpoints off loopback TCP onto Unix sockets in the App Group container, requiring a same-team code signature from every XPC peer, and turning the MCP HTTP server off by default.
Read the plan →v1.5 Plan — Salient Facts, Memory, Categories, Triples, Providers, Dreaming
Engineering plan for salient facts, generic memory, document categories, triples, a provider registry and a dreaming worker. Written for 1.5, which shipped without it; now the direction for 1.6.
Read the plan →v1.5 Research — Papers Informing the Plan
Literature survey behind the v1.5 plan, with each paper mapped to a concrete design change and a triage decision.
Read the plan →Windows Plan — A Native Garage for Windows
Engineering plan for a native Windows Garage — a WinUI 3 app on .NET that embeds CPython the way the Mac app does with PythonKit, per-user service processes in place of XPC, and Windows design idioms.
Read the plan →Windows UI Plan — The Garage App Window, Tray and Pages on WinUI 3
Implementation plan for the Windows Garage user interface — a WinUI 3 app on .NET 10 with the Mac app's pages in Windows idioms, built against the existing gRPC contract.
Read the plan →Simplification and robustness plan
Engineering plan to make the gRPC server the one facade, give extraction a media-type contract, and tighten the schema.
Read the plan →Middle-Layer SFT — LoRA Adapters Trained with MLX, Served by llama.cpp
Design for fine-tuning the middle layers of an open-weight model on the Garage corpus with MLX on the Mac, exported as a LoRA adapter GGUF that the app's llama.cpp engine loads beside the quantized base model.
Read the plan →GarageKit — the app's service layer, apart from the UI
Moving the gRPC client, the backend lifecycle and the corpus state into a UI-free GarageKit.
Read the plan →How a plan is written
A plan is a Markdown file in docs/plans/ with front matter the index above reads:
---
layout: default
title: Short name of the plan
description: One sentence on what it changes and why.
date: 2026-10-04 # when it was written; the index sorts on it
status: Proposed # the current state, in a few words
status_kind: proposed # proposed | active | landed | deferred | reference
---
The body opens with a status note when the state has moved on from the text below it, as the v1.5 plan does. Measurements come with the command that produced them, so they can be re-run. Line numbers go stale; file paths and function names last longer.