| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 20 | 3 | 0% |
| Commands | 0 | 11 | 0 | 0% |
| Section tags | 2 | 10 | 0 | 17% |
What each file covers
Sections
0 shared · 20 only in A · 3 only in B- − Copilot Cloud Agent Instructions
- − What this repository is
- − Organization-wide agent guidance
- − Repository layout
- − Tech stack
- − ⚠️ macOS-only constraints for the cloud agent
- − Building and testing (what works on Linux)
- − Install JS/TS dependencies
- − Rust unit tests (no macOS SDK required for most)
- − TypeScript unit tests
- − Storybook component tests (needs Playwright + Chromium installed)
- − TS/JS lint
- − Type-check frontend
- − expands to: cargo test --manifest-path src-tauri/Cargo.toml && bun run test:unit
- − Code conventions
- − Rust
- − TypeScript / React
- − AI provider abstraction
- − Key domain concepts
- − Common pitfalls
- + Rust ↔ TypeScript IPC — use oRPC
- + Codegen (required after router changes)
- + Prefer React Query over `invoke()`
Commands
0 shared · 11 only in A · 0 only in B- − bun install
- − cargo test --manifest-path apps/native/src-tauri/Cargo.toml
- − bun run check
- − npm install
- − yarn
- − bun run desktop:build
- − cargo build
- − bun run test:unit
- − bun run …
- − npm
- − biome.json
Section tags
2 shared · 10 only in A · 0 only in B- − setup
- − build
- − test
- − lint-format
- − architecture
- − git-pr
- − dependencies
- − ui
- − do-not
- − agent-behaviour
- code-style
- types
Line diff
darkmatter/nixmac · .github/copilot-instructions.md
@@ −1 @@
1# Copilot Cloud Agent Instructions
2
3## What this repository is
4
5**nixmac** is a native macOS application (Tauri 2 + Rust backend, React 19 frontend) that puts an AI agent in front of a [nix-darwin](https://github.com/LnL7/nix-darwin) configuration. Users describe what they want in plain English and the app edits their Nix config files, builds the system, and applies it — including one-click rollback via git history.
6
7## Organization-wide agent guidance
8
9- Organization-wide Copilot instructions are maintained in the `darkmatter/skills` repository.
10- When reviewing pull requests for this repository, also apply and follow the PR review guidelines documented there.
11
12## Repository layout
13
14```
15nixmac/
16├── apps/native/ # The main deliverable: Tauri desktop app
17│ ├── src/ # React/TypeScript frontend (Vite)
18│ │ ├── components/widget/ # UI widgets (badges, controls, feedback, history,
19│ │ │ # layout, notifications, overlays, promptinput,
20│ │ │ # settings, steps)
21│ │ ├── hooks/ # React hooks (use-evolve.ts, use-apply.ts, …)
22│ │ ├── ipc/ # Tauri IPC bindings (api.ts, sqlite.ts, types.ts)
23│ │ ├── stores/ # Zustand state (widget-store.ts)
24│ │ └── stories/ # Storybook stories
25│ └── src-tauri/ # Rust backend
26│ └── src/
27│ ├── main.rs # App entry point; declares top-level modules only
28│ ├── ai/ # ChatCompletionProvider trait + provider impls
29│ │ └── providers/ # openai.rs, ollama.rs, cli.rs
30│ ├── evolve/ # The AI evolution loop (tool use, file edits, git)
31│ │ ├── mod.rs # Core agent loop
32│ │ ├── tools.rs # Tool definitions (think/read_file/edit_file/…)
33│ │ ├── file_ops.rs # Path-safe file helpers (join_in_dir, resolve_*)
34│ │ ├── edit_nix_file.rs # Semantic Nix AST editing (rnix/rowan)
35│ │ └── …
36│ ├── rebuild/ # darwin-rebuild build/apply/rollback wrappers
37│ ├── summarize/ # AI summarization pipeline
38│ ├── commands/ # Tauri command handlers
39│ ├── shared_types/ # Types shared between Rust and TypeScript via specta
40│ ├── storage/ # Tauri store + keyring credential storage
41│ ├── git/ # Git operations (exec, changes_from_diff)
42│ ├── state/ # App state (build state, watcher, evolve state)
43│ └── …
44├── packages/ui/ # Shared Radix UI + Tailwind component library
45├── nix/ # devenv modules and Nix helper files
46└── ops/ # Release scripts (scripts/) and SOPS-encrypted secrets (secrets/)
47```
48
49## Tech stack
50
51| Layer | Technologies |
52| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
53| Rust backend | Tauri 2, tokio, serde/serde_json, anyhow, thiserror, rusqlite + rusqlite_migration, specta (type export), rnix + rowan (Nix AST), clap (CLI), async-openai, tiktoken-rs |
54| TypeScript frontend | React 19, Vite 7, Zustand, Radix UI, TailwindCSS 3, Monaco Editor, Shiki, Sonner, motion |
55| Package manager | **Bun** (1.3.x) — use `bun install`, never `npm install` or `yarn` |
56| Linting | **oxlint** (TS/JS), **biome** (formatting) |
57| Testing | Vitest (unit + Storybook browser tests), Playwright (e2e web), WebdriverIO (e2e Tauri app) |
58| Build system | `bun run desktop:build` (Tauri) wraps `cargo build` + Vite |
59| CI | GitHub Actions — `.github/workflows/build.yaml` runs on `macos-latest` |
60| Secrets | SOPS + age (`ops/secrets/secrets.sops.json`) — never commit plaintext secrets |
61
62## ⚠️ macOS-only constraints for the cloud agent
63
64nixmac targets macOS exclusively. The cloud agent runs on Ubuntu Linux; keep the following in mind:
65
66- **The app cannot be fully built on Linux.** `tauri build` / `bun run desktop:build` requires macOS (Cocoa APIs, Apple signing). Do not attempt a production build in the agent environment.
67- **Most Rust unit tests can run on Linux** via `cargo test --manifest-path apps/native/src-tauri/Cargo.toml`. Tests that invoke `darwin-rebuild` or macOS system APIs are guarded by `#[cfg(target_os = "macos")]` or the `e2e_mock_system` flag and will be skipped.
68- **Frontend-only tests work fine** — `bun run test:unit` (Vitest/jsdom) runs on Linux.
69- `devenv up` and `nix` commands require a Nix installation; do not rely on them in the agent.
70
71## Building and testing (what works on Linux)
72
73```bash
74# Install JS/TS dependencies
75bun install
76
77# Rust unit tests (no macOS SDK required for most)
78cargo test --manifest-path apps/native/src-tauri/Cargo.toml
79
80# TypeScript unit tests
81cd apps/native && bun run test:unit
82
83# Storybook component tests (needs Playwright + Chromium installed)
84cd apps/native && bun run test:storybook
85
86# TS/JS lint
87bun run check # runs oxlint across the whole repo
88cd apps/native && bun run lint
89
90# Type-check frontend
91cd apps/native && bun run build # tsc + vite build (no macOS deps)
92```
93
94The canonical "full desktop test" command is:
95
96```bash
97cd apps/native && bun run desktop:test
98# expands to: cargo test --manifest-path src-tauri/Cargo.toml && bun run test:unit
99```
100
101## Code conventions
102
103### Rust
104
105- Top-level module declarations belong in `main.rs` only. Leaf modules are declared by their parent `mod.rs` files so rust-analyzer resolves them via Cargo.
106- All public `serde` structs use `#[serde(rename_all = "camelCase")]` to match JS/TS consumers.
107- Prefer `anyhow::Result` for fallible functions; define domain errors with `thiserror`.
108- Unused items are **denied** (`[lints.rust] unused = "deny"`); add `#[allow(dead_code)]` sparingly and only when the item is intentionally reserved.
109- **Path safety**: always use `file_ops::join_in_dir` or `file_ops::resolve_*_path_in_dir*` when constructing paths inside the user's config dir. Never concatenate strings or use `Path::new(user_input)` directly — this prevents path-traversal out of `config_dir`.
110- **External commands in the GUI app**: set `PATH` via `nix::get_nix_path()` (includes `/usr/local/bin` and `/opt/homebrew/bin`) so commands work when launched from Finder.
111- **Rust tests that mutate environment variables**: use `crate::test_support::e2e_env_lock()` and `EnvVarRestore::capture(keys)` to serialize env state and restore it after the test.
112- **Debug logs**: written under `dirs::data_local_dir()/nixmac/logs`. darwin-rebuild logs go to `~/Library/Logs/nixmac/`.
113
114### TypeScript / React
115
116- Use **Bun** for all package operations (`bun install`, `bun run …`).
117- Components live under `apps/native/src/components/widget/{subfolder}/` — subfolders include `badges`, `controls`, `feedback`, `history`, `layout`, `notifications`, `overlays`, `promptinput`, `settings`, `steps`.
118- The shared UI library is at `packages/ui/src`; import as `@nixmac/ui` or `@/components/ui`.
119- State management uses **Zustand** (`apps/native/src/stores/widget-store.ts`).
120- IPC with the Rust backend uses Tauri's `invoke` wrapped in `apps/native/src/ipc/api.ts`.
121- TypeScript types shared with Rust are generated by **specta** (`specta-typescript`); regenerate with the specta export command after changing `#[specta::Type]`-annotated structs.
122- Linting: **oxlint** + **biome** (extends `ultracite/core` + `ultracite/react`). Run `bun run check` from repo root.
123
124### AI provider abstraction
125
126The `ChatCompletionProvider` trait (`apps/native/src-tauri/src/ai/providers/mod.rs`) has two core methods:
127
128```rust
129async fn completion(&self, system_prompt, user_prompt, max_tokens, context_window_tokens, temperature, request_id) -> Result<(String, TokenUsage)>
130async fn json_completion(&self, ...) -> Result<(String, TokenUsage)>
131```
132
133- `max_tokens` — maximum output tokens (all providers).
134- `context_window_tokens` — optional override for the total context window. For **Ollama** this maps to `num_ctx`; OpenAI-compatible providers ignore it.
135- Supported providers: `openrouter` (default), `openai`, `ollama`, `openai_compatible`, `claude` (CLI), `codex` (CLI), `opencode` (CLI).
136
137## Key domain concepts
138
139| Concept | Description |
140| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
141| **Evolution** | One AI-driven config change cycle: prompt → tool use → file edits → `darwin-rebuild build` → `darwin-rebuild switch` → git commit |
142| **EvolutionState** | Enum: `Pending`, `Running`, `Complete`, `Failed`, `Cancelled` |
143| **SemanticFileEdit** | Structured Nix AST edit (`Add`, `Remove`, `Set`, `SetAttrs`) applied by `edit_nix_file.rs` via rnix/rowan |
144| **Tools available to the agent** | `think`, `read_file`, `write_file`, `edit_file`, `edit_nix_file`, `list_files`, `search_packages`, `search_docs`, `search_code`, `build_check`, `ask_user`, `ensure_secret`, `done` |
145| **Config dir** | The user's nix-darwin flake repo (default `~/.darwin`), always accessed through `file_ops` helpers |
146| **Summarization pipeline** | Batched AI calls that generate commit messages and UI labels; token-budgeted via `tiktoken-rs` |
147
148## Common pitfalls
149
1501. **Do not run `bun run desktop:build` or `tauri build`** in the agent — they require macOS.
1511. **Do not modify `ops/secrets/`** without sops; the files are encrypted with age.
1521. **Do not use `npm` or `yarn`** — this project uses Bun exclusively.
1531. **Do not add `unused` imports** — they are compile errors (`unused = "deny"`).
1541. When adding a new Rust source file, declare it with `mod` in its **parent `mod.rs`**, not in `main.rs` (unless it is a new top-level domain module).
1551. When adding or changing a Tauri command, update the corresponding TypeScript types in `apps/native/src/ipc/types.ts` (or regenerate via specta).
1561. The `biome.json` `files.includes` list is explicit — new `apps/**` and `packages/**` files are covered automatically, but files outside those paths need to be added manually.
157
darkmatter/nixmac · .cursor/rules/native-orpc.mdc
@@ +1 @@
1---
2description: oRPC and React Query for Rust ↔ TypeScript IPC in the native app
3globs: apps/native/**/*.ts,apps/native/**/*.tsx,apps/native/src-tauri/**/*.rs
4alwaysApply: false
5---
6
7# Rust ↔ TypeScript IPC — use oRPC
8
9All new Rust ↔ TypeScript communication must go through **oRPC** (fully typed end-to-end).
10
11## Codegen (required after router changes)
12
13```bash
14cd apps/native && bun run gen:orpc
15```
16
17- Rust procedures: `apps/native/src-tauri/src/orpc/`
18- Generated TS bindings: `apps/native/src/ipc/orpc-bindings.ts` (do not edit)
19- Client + TanStack Query helpers: `apps/native/src/lib/orpc.ts`
20
21## Prefer React Query over `invoke()`
22
23oRPC integrates with **TanStack Query** via `orpc` helpers. This is the default for data that is fetched, cached, polled, or invalidated.
24
25```tsx
26// ✅ GOOD — cached, deduplicated, lifecycle-aware
27import { useQuery } from "@tanstack/react-query";
28import { orpc } from "@/lib/orpc";
29
30const { data } = useQuery(orpc.github.listRepos.queryOptions({ input: undefined }));
31```
32
33```ts
34// ❌ BAD — new feature wired through legacy invoke()
35import { invoke } from "@tauri-apps/api/core";
36await invoke("some_new_command");
37```
38
39- **`client`** — direct async calls for one-off/imperative flows (no cache needed).
40- **`orpc` + hooks** — anything that should behave like server state in React.
41
42Do **not** add new Zustand stores for global fetchable data — React Query is the cache. Even global async state belongs in query cache, not a hand-rolled store.
43
44Legacy `invoke()` in `apps/native/src/ipc/api.ts` is deprecated; migrate callers to oRPC when touching them.
45
@@ −1 +1 @@
1−# Copilot Cloud Agent Instructions
1+---
2+description: oRPC and React Query for Rust ↔ TypeScript IPC in the native app
3+globs: apps/native/**/*.ts,apps/native/**/*.tsx,apps/native/src-tauri/**/*.rs
4+alwaysApply: false
5+---
26
3−## What this repository is
7+# Rust ↔ TypeScript IPC — use oRPC
48
5−**nixmac** is a native macOS application (Tauri 2 + Rust backend, React 19 frontend) that puts an AI agent in front of a [nix-darwin](https://github.com/LnL7/nix-darwin) configuration. Users describe what they want in plain English and the app edits their Nix config files, builds the system, and applies it — including one-click rollback via git history.
9+All new Rust ↔ TypeScript communication must go through **oRPC** (fully typed end-to-end).
610
7−## Organization-wide agent guidance
11+## Codegen (required after router changes)
812
9−- Organization-wide Copilot instructions are maintained in the `darkmatter/skills` repository.
10−- When reviewing pull requests for this repository, also apply and follow the PR review guidelines documented there.
11−
12−## Repository layout
13−
13+```bash
14+cd apps/native && bun run gen:orpc
1415 ```
15−nixmac/
16−├── apps/native/ # The main deliverable: Tauri desktop app
17−│ ├── src/ # React/TypeScript frontend (Vite)
18−│ │ ├── components/widget/ # UI widgets (badges, controls, feedback, history,
19−│ │ │ # layout, notifications, overlays, promptinput,
20−│ │ │ # settings, steps)
21−│ │ ├── hooks/ # React hooks (use-evolve.ts, use-apply.ts, …)
22−│ │ ├── ipc/ # Tauri IPC bindings (api.ts, sqlite.ts, types.ts)
23−│ │ ├── stores/ # Zustand state (widget-store.ts)
24−│ │ └── stories/ # Storybook stories
25−│ └── src-tauri/ # Rust backend
26−│ └── src/
27−│ ├── main.rs # App entry point; declares top-level modules only
28−│ ├── ai/ # ChatCompletionProvider trait + provider impls
29−│ │ └── providers/ # openai.rs, ollama.rs, cli.rs
30−│ ├── evolve/ # The AI evolution loop (tool use, file edits, git)
31−│ │ ├── mod.rs # Core agent loop
32−│ │ ├── tools.rs # Tool definitions (think/read_file/edit_file/…)
33−│ │ ├── file_ops.rs # Path-safe file helpers (join_in_dir, resolve_*)
34−│ │ ├── edit_nix_file.rs # Semantic Nix AST editing (rnix/rowan)
35−│ │ └── …
36−│ ├── rebuild/ # darwin-rebuild build/apply/rollback wrappers
37−│ ├── summarize/ # AI summarization pipeline
38−│ ├── commands/ # Tauri command handlers
39−│ ├── shared_types/ # Types shared between Rust and TypeScript via specta
40−│ ├── storage/ # Tauri store + keyring credential storage
41−│ ├── git/ # Git operations (exec, changes_from_diff)
42−│ ├── state/ # App state (build state, watcher, evolve state)
43−│ └── …
44−├── packages/ui/ # Shared Radix UI + Tailwind component library
45−├── nix/ # devenv modules and Nix helper files
46−└── ops/ # Release scripts (scripts/) and SOPS-encrypted secrets (secrets/)
47−```
4816
49−## Tech stack
17+- Rust procedures: `apps/native/src-tauri/src/orpc/`
18+- Generated TS bindings: `apps/native/src/ipc/orpc-bindings.ts` (do not edit)
19+- Client + TanStack Query helpers: `apps/native/src/lib/orpc.ts`
5020
51−| Layer | Technologies |
52−| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
53−| Rust backend | Tauri 2, tokio, serde/serde_json, anyhow, thiserror, rusqlite + rusqlite_migration, specta (type export), rnix + rowan (Nix AST), clap (CLI), async-openai, tiktoken-rs |
54−| TypeScript frontend | React 19, Vite 7, Zustand, Radix UI, TailwindCSS 3, Monaco Editor, Shiki, Sonner, motion |
55−| Package manager | **Bun** (1.3.x) — use `bun install`, never `npm install` or `yarn` |
56−| Linting | **oxlint** (TS/JS), **biome** (formatting) |
57−| Testing | Vitest (unit + Storybook browser tests), Playwright (e2e web), WebdriverIO (e2e Tauri app) |
58−| Build system | `bun run desktop:build` (Tauri) wraps `cargo build` + Vite |
59−| CI | GitHub Actions — `.github/workflows/build.yaml` runs on `macos-latest` |
60−| Secrets | SOPS + age (`ops/secrets/secrets.sops.json`) — never commit plaintext secrets |
21+## Prefer React Query over `invoke()`
6122
62−## ⚠️ macOS-only constraints for the cloud agent
23+oRPC integrates with **TanStack Query** via `orpc` helpers. This is the default for data that is fetched, cached, polled, or invalidated.
6324
64−nixmac targets macOS exclusively. The cloud agent runs on Ubuntu Linux; keep the following in mind:
25+```tsx
26+// ✅ GOOD — cached, deduplicated, lifecycle-aware
27+import { useQuery } from "@tanstack/react-query";
28+import { orpc } from "@/lib/orpc";
6529
66−- **The app cannot be fully built on Linux.** `tauri build` / `bun run desktop:build` requires macOS (Cocoa APIs, Apple signing). Do not attempt a production build in the agent environment.
67−- **Most Rust unit tests can run on Linux** via `cargo test --manifest-path apps/native/src-tauri/Cargo.toml`. Tests that invoke `darwin-rebuild` or macOS system APIs are guarded by `#[cfg(target_os = "macos")]` or the `e2e_mock_system` flag and will be skipped.
68−- **Frontend-only tests work fine** — `bun run test:unit` (Vitest/jsdom) runs on Linux.
69−- `devenv up` and `nix` commands require a Nix installation; do not rely on them in the agent.
70−
71−## Building and testing (what works on Linux)
72−
73−```bash
74−# Install JS/TS dependencies
75−bun install
76−
77−# Rust unit tests (no macOS SDK required for most)
78−cargo test --manifest-path apps/native/src-tauri/Cargo.toml
79−
80−# TypeScript unit tests
81−cd apps/native && bun run test:unit
82−
83−# Storybook component tests (needs Playwright + Chromium installed)
84−cd apps/native && bun run test:storybook
85−
86−# TS/JS lint
87−bun run check # runs oxlint across the whole repo
88−cd apps/native && bun run lint
89−
90−# Type-check frontend
91−cd apps/native && bun run build # tsc + vite build (no macOS deps)
30+const { data } = useQuery(orpc.github.listRepos.queryOptions({ input: undefined }));
9231 ```
9332
94−The canonical "full desktop test" command is:
95−
96−```bash
97−cd apps/native && bun run desktop:test
98−# expands to: cargo test --manifest-path src-tauri/Cargo.toml && bun run test:unit
33+```ts
34+// ❌ BAD — new feature wired through legacy invoke()
35+import { invoke } from "@tauri-apps/api/core";
36+await invoke("some_new_command");
9937 ```
10038
101−## Code conventions
39+- **`client`** — direct async calls for one-off/imperative flows (no cache needed).
40+- **`orpc` + hooks** — anything that should behave like server state in React.
10241
103−### Rust
42+Do **not** add new Zustand stores for global fetchable data — React Query is the cache. Even global async state belongs in query cache, not a hand-rolled store.
10443
105−- Top-level module declarations belong in `main.rs` only. Leaf modules are declared by their parent `mod.rs` files so rust-analyzer resolves them via Cargo.
106−- All public `serde` structs use `#[serde(rename_all = "camelCase")]` to match JS/TS consumers.
107−- Prefer `anyhow::Result` for fallible functions; define domain errors with `thiserror`.
108−- Unused items are **denied** (`[lints.rust] unused = "deny"`); add `#[allow(dead_code)]` sparingly and only when the item is intentionally reserved.
109−- **Path safety**: always use `file_ops::join_in_dir` or `file_ops::resolve_*_path_in_dir*` when constructing paths inside the user's config dir. Never concatenate strings or use `Path::new(user_input)` directly — this prevents path-traversal out of `config_dir`.
110−- **External commands in the GUI app**: set `PATH` via `nix::get_nix_path()` (includes `/usr/local/bin` and `/opt/homebrew/bin`) so commands work when launched from Finder.
111−- **Rust tests that mutate environment variables**: use `crate::test_support::e2e_env_lock()` and `EnvVarRestore::capture(keys)` to serialize env state and restore it after the test.
112−- **Debug logs**: written under `dirs::data_local_dir()/nixmac/logs`. darwin-rebuild logs go to `~/Library/Logs/nixmac/`.
113−
114−### TypeScript / React
115−
116−- Use **Bun** for all package operations (`bun install`, `bun run …`).
117−- Components live under `apps/native/src/components/widget/{subfolder}/` — subfolders include `badges`, `controls`, `feedback`, `history`, `layout`, `notifications`, `overlays`, `promptinput`, `settings`, `steps`.
118−- The shared UI library is at `packages/ui/src`; import as `@nixmac/ui` or `@/components/ui`.
119−- State management uses **Zustand** (`apps/native/src/stores/widget-store.ts`).
120−- IPC with the Rust backend uses Tauri's `invoke` wrapped in `apps/native/src/ipc/api.ts`.
121−- TypeScript types shared with Rust are generated by **specta** (`specta-typescript`); regenerate with the specta export command after changing `#[specta::Type]`-annotated structs.
122−- Linting: **oxlint** + **biome** (extends `ultracite/core` + `ultracite/react`). Run `bun run check` from repo root.
123−
124−### AI provider abstraction
125−
126−The `ChatCompletionProvider` trait (`apps/native/src-tauri/src/ai/providers/mod.rs`) has two core methods:
127−
128−```rust
129−async fn completion(&self, system_prompt, user_prompt, max_tokens, context_window_tokens, temperature, request_id) -> Result<(String, TokenUsage)>
130−async fn json_completion(&self, ...) -> Result<(String, TokenUsage)>
131−```
132−
133−- `max_tokens` — maximum output tokens (all providers).
134−- `context_window_tokens` — optional override for the total context window. For **Ollama** this maps to `num_ctx`; OpenAI-compatible providers ignore it.
135−- Supported providers: `openrouter` (default), `openai`, `ollama`, `openai_compatible`, `claude` (CLI), `codex` (CLI), `opencode` (CLI).
136−
137−## Key domain concepts
138−
139−| Concept | Description |
140−| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
141−| **Evolution** | One AI-driven config change cycle: prompt → tool use → file edits → `darwin-rebuild build` → `darwin-rebuild switch` → git commit |
142−| **EvolutionState** | Enum: `Pending`, `Running`, `Complete`, `Failed`, `Cancelled` |
143−| **SemanticFileEdit** | Structured Nix AST edit (`Add`, `Remove`, `Set`, `SetAttrs`) applied by `edit_nix_file.rs` via rnix/rowan |
144−| **Tools available to the agent** | `think`, `read_file`, `write_file`, `edit_file`, `edit_nix_file`, `list_files`, `search_packages`, `search_docs`, `search_code`, `build_check`, `ask_user`, `ensure_secret`, `done` |
145−| **Config dir** | The user's nix-darwin flake repo (default `~/.darwin`), always accessed through `file_ops` helpers |
146−| **Summarization pipeline** | Batched AI calls that generate commit messages and UI labels; token-budgeted via `tiktoken-rs` |
147−
148−## Common pitfalls
149−
150−1. **Do not run `bun run desktop:build` or `tauri build`** in the agent — they require macOS.
151−1. **Do not modify `ops/secrets/`** without sops; the files are encrypted with age.
152−1. **Do not use `npm` or `yarn`** — this project uses Bun exclusively.
153−1. **Do not add `unused` imports** — they are compile errors (`unused = "deny"`).
154−1. When adding a new Rust source file, declare it with `mod` in its **parent `mod.rs`**, not in `main.rs` (unless it is a new top-level domain module).
155−1. When adding or changing a Tauri command, update the corresponding TypeScript types in `apps/native/src/ipc/types.ts` (or regenerate via specta).
156−1. The `biome.json` `files.includes` list is explicit — new `apps/**` and `packages/**` files are covered automatically, but files outside those paths need to be added manually.
44+Legacy `invoke()` in `apps/native/src/ipc/api.ts` is deprecated; migrate callers to oRPC when touching them.
15745
