Architecture Decision Records
Immutable once accepted; superseding requires a new ADR that links back. Format: Context → Decision → Consequences → Alternatives considered.
Older records retain the package and type names used when accepted. ADR-0054 records the domain extraction and renaming; Modules is the current ownership and import reference.
| # | Title | Status |
|---|---|---|
| 0001 | On-device inference via MLX (mlx-swift-lm) | Superseded by 0008 |
| 0002 | SwiftUI-first, @Observable MV, actor domain | Accepted |
| 0003 | GRDB/SQLite for persistence | Accepted |
| 0004 | XcodeGen + xcodebuild CLI builds | Accepted |
| 0005 | Pluggable memory: wiki default, Hindsight optional | Accepted · Hindsight runtime superseded by 0036; refined by 0031, 0033, 0035, and 0037 |
| 0006 | MCP via official Swift SDK | Accepted |
| 0007 | No App Sandbox; Hardened Runtime at ship | Accepted · signing refined by 0078 |
| 0008 | Inference delegated to a local oMLX server | Accepted |
| 0009 | ~/.goat home; file-based Claude-Desktop-compatible MCP config | Accepted |
| 0010 | The Paddock: artifact previews; custom transcript reaffirmed over SwiftyChat | Accepted |
| 0011 | Liquid Glass primitives + AppKit hook for true window alpha | Accepted |
| 0012 | Engine API key in ~/.goat file (0600), not the Keychain | Accepted |
| 0013 | Themes are ThemeSpec data; custom themes from ~/.goat | Accepted · refined by 0022 and 0030 |
| 0014 | Bottom panel is a read-only activity log, not a shell | Accepted |
| 0015 | Herd Guarantee split from preview network access; off-grid toggle | Accepted |
| 0016 | Chat pipeline: normalize at the engine, typed parts in the UI | Accepted |
| 0017 | Engine-agnostic OpenAI-dialect client; oMLX recommended | Accepted |
| 0018 | Monorepo layout (apps/web/docs) + CI/release/Pages tooling | Accepted · web/ refined by 0041 |
| 0019 | Pens (projects) are folders in ~/.goat/projects; OKLCH colour, AGENTS.md | Accepted |
| 0020 | Engine presets (oMLX/vMLX/Ollama/LM Studio/llama.cpp) + Custom URL; engine-aware model management | Accepted · refined by 0021 |
| 0021 | Engines are a managed list (engines.json) sharing the MCP servers' UX; one active at a time | Accepted |
| 0022 | GOAT Theme Format; community themes as folders; built-ins read-only; System → Light/Midnight | Accepted · refines 0013, refined by 0030 |
| 0023 | One active turn app-wide; revisioned engine lifecycle commits; M6 gate | Accepted |
| 0024 | Deterministic prompt budget; capability-gated model setup and atomic trimming | Accepted |
| 0025 | Progressive single-flight startup; local state before concurrent services | Accepted |
| 0026 | MainActor publishes Sendable worker results; generation and file I/O stay off-main | Accepted |
| 0027 | Fail-closed local stores; bounded transports and generation-bound MCP authority | Accepted |
| 0028 | Measured bounded rendering; transition-safe fullscreen backing | Accepted |
| 0029 | Chat/Image/Video workspaces; Tether is the capability-driven media inspector | Proposed |
| 0030 | Corporate System default; About-unlocked 1337 experience pack ships in Kid | Accepted · refines 0011, 0013, and 0022 |
| 0031 | Provider-aware LLM Wiki Pages/Map/Connections browser; desktop memory map | Accepted · refines 0005 |
| 0032 | Optional user-owned Pen workspaces; local Git status and opt-in initialization | Accepted · refines 0019 and 0026 |
| 0033 | Exclusive Global and Pen memory scopes; non-destructive chat moves | Accepted · refines 0005 |
| 0034 | Hindsight as a bank-scoped server provider | Superseded by 0036 |
| 0035 | Hindsight as one managed connection lifecycle | Accepted · refines 0005 and 0034 |
| 0036 | GOATed extensions, native skills, and Hindsight lifecycle | Accepted · supersedes Hindsight runtime and scope in 0034 |
| 0037 | App-wide memory provider and explicit Pen banks | Accepted · refines provider routing in 0005, 0033, and 0036 |
| 0038 | Local presentation gate and professional interface | Accepted · refines 0030 |
| 0039 | Preview and extension lifetime boundaries | Accepted |
| 0040 | Single-source release identity | Accepted |
| 0041 | Public website as a Vite + Vue SPA on GitHub Pages | Accepted · refines 0018 |
| 0042 | GOATed Kid capability and lifetime contract | Accepted |
| 0043 | App-owned local Hitch and CLI | Accepted |
| 0044 | Docs site as VitePress over docs/, beside the landing page | Accepted · extends 0041 |
| 0045 | JUDAS central connection policy and security activity | Accepted · refines 0015, 0024 and 0042 |
| 0046 | Scoped recent memory, Pen tabs and native Hindsight map | Accepted · refines 0031 and 0037 |
| 0047 | Native graph controls and session charts | Accepted · refines 0031 and 0046 |
| 0048 | Spatial memory and knowledge graph | Accepted · refines 0046 and 0047 |
| 0049 | Native map input ownership | Accepted · refines 0047 and 0048 |
| 0050 | Map zoom and connector motion | Accepted · refines 0047 and 0049 |
| 0051 | Typed memory relationship direction | Accepted · refines 0048 and 0050 |
| 0052 | Pens overview and visible legend help | Accepted · refines 0051 |
| 0053 | Local reading font preferences | Accepted |
| 0054 | First-class domain modules | Accepted |
| 0055 | Local-network service authority | Accepted |
| 0056 | Bounded rendering caches and responsive I/O | Accepted |
| 0057 | Foreground engine connection recovery | Accepted |
| 0058 | Stable transcript reflow and scroll ownership | Accepted |
| 0059 | Project context and tool execution guidance | Accepted |
| 0060 | Bounded rich-list measurement | Accepted |
| 0061 | Native GOATed Pen file tools | Accepted |
| 0062 | Declarative GOATed packages | Accepted |
| 0063 | Chat and Pen scopes for native file permissions | Accepted · refines 0061 |
| 0064 | Composer and Pen file-permission controls | Accepted · refines 0063 |
| 0065 | Bounded recovery for unexecuted tool-call text | Accepted |
| 0066 | Lead, early titles, and continuous tool work | Accepted · refines 0023; supersedes the round cap in 0006 and 0065 |
| 0067 | Lead waits for the current action and approval | Accepted · refines 0066 |
| 0068 | Honest edit feedback and visible interruption recovery | Accepted · refines 0003, 0061, and 0066 |
| 0069 | Coding navigation, context excerpts and accurate Stop results | Accepted · refines 0024, 0061 and 0068 |
| 0070 | Confined Pen command jobs and separate owner whitelist | Accepted · implements command direction in 0061 |
| 0071 | Optional built-ins and Herder settings | Accepted |
| 0072 | Tool-generation telemetry and coder recovery | Accepted |
| 0073 | Owner-managed command whitelist | Accepted |
| 0074 | Grouped transcript tool activity | Accepted · refines 0058 |
| 0075 | Chat file attachments and inline artifact presentation | Accepted · refines 0056 and 0074 |
| 0076 | Hindsight health and session ownership | Accepted · refines 0035 |
| 0077 | Host coordination and resource lifetimes | Accepted · refines 0025, 0056 and 0076 |
| 0078 | Owner-approved release signing | Accepted · refines 0007 |
New session? Start with ../../AGENT.md, then the roadmap.