Onboarding

.beads/README.md

@@ -82,4 +82,4 @@ bd create "Try out Beads"
 
 ______________________________________________________________________
 
-*Beads: Issue tracking that moves at the speed of thought* ⚡
+_Beads: Issue tracking that moves at the speed of thought_ ⚡

.beads/config.yaml

@@ -53,4 +53,4 @@
 # - github.org
 # - github.repo
 
-sync.remote: "git+ssh://git@github.com/darkmatter/nixmac.git"
+sync.remote: "git+ssh://git@github.com/darkmatter/nixmac.git"

.beads/interactions.jsonl

@@ -0,0 +1,8 @@
+{"id":"int-0a0e5570c150d2f1712b3b57497d1fcf","kind":"field_change","created_at":"2026-06-20T20:02:41.998441Z","actor":"Cooper Maruyama","issue_id":"nixmac-0sv","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-1bc8c57f19929eb86a0d66063a7b4ae9","kind":"field_change","created_at":"2026-06-20T20:02:42.297705Z","actor":"Cooper Maruyama","issue_id":"nixmac-3jx","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Closed"}}
+{"id":"int-6fe5e079ea7f3365b16f66b80b41c6aa","kind":"field_change","created_at":"2026-06-20T20:02:42.601435Z","actor":"Cooper Maruyama","issue_id":"nixmac-35u","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Closed"}}
+{"id":"int-79e290bfce47778af1c1dc4a09ef8391","kind":"field_change","created_at":"2026-06-20T20:02:42.905668Z","actor":"Cooper Maruyama","issue_id":"nixmac-0zt","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Closed"}}
+{"id":"int-a874d144d08f413f9672a66d638ce378","kind":"field_change","created_at":"2026-06-20T20:02:43.194477Z","actor":"Cooper Maruyama","issue_id":"nixmac-cur","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Closed"}}
+{"id":"int-727e22cd82571ce56908dd4f8b15ce75","kind":"field_change","created_at":"2026-06-25T15:47:46.556063Z","actor":"Cooper Maruyama","issue_id":"nixmac-51i","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Migrated existing frontend ORPC-covered IPC calls and verified focused tests/build."}}
+{"id":"int-4160c3c1118857a49e7a02810af97a4a","kind":"field_change","created_at":"2026-06-26T04:03:50.131426Z","actor":"Cooper Maruyama","issue_id":"nixmac-yii","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Added a starter prompt archetype catalog, surfaced curated chips in PromptInput, and verified prompt seeding plus source refs."}}
+{"id":"int-8145c9da9c4a6df95bfb1ef7a619e4e0","kind":"field_change","created_at":"2026-06-26T06:39:10.511906Z","actor":"Cooper Maruyama","issue_id":"nixmac-txo","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Added Lucide icon keys to every starter prompt, rendered featured prompt icons in chips, and verified prompt-input behavior."}}

.beads/metadata.json

@@ -4,4 +4,4 @@
   "dolt_mode": "embedded",
   "dolt_database": "nixmac",
   "project_id": "be4f1249-4115-488c-a47d-ab8da35154e2"
-}
+}

.claude/settings.json

@@ -23,4 +23,4 @@
       }
     ]
   }
-}
+}

.cursor/rules/native-config-tiers.mdc

@@ -0,0 +1,30 @@
+---
+description: Three configuration tiers for the native app
+alwaysApply: true
+---
+
+# Configuration — use one of three tiers
+
+Any new configuration must land in exactly one of these places. Do not invent a fourth config file or hard-code values in components.
+
+## 1. Build profiles (environment variables)
+
+**Files:** `apps/native/env.development.json`, `apps/native/env.release.json` (and `env.e2e.json` for e2e)
+
+We call these **profiles** to distinguish them from runtime user settings. Anything that can be passed as an env var belongs here. Preferred over ad hoc env reads — each file references a generated JSON Schema (`src-tauri/resources/schemas/env.schema.json`) for intellisense.
+
+Read in app code via `apps/native/src/lib/env.ts`.
+
+## 2. User preferences (device-wide)
+
+**Path:** `$XDG_CONFIG_HOME/nixmac/settings.json`
+
+App settings at the **user** level — they apply across every project/config repo the user opens. Rust: `GlobalPreferences` / observable persistence in `src-tauri/src/state/`.
+
+## 3. Project level (repo-scoped)
+
+**Path:** `<config_dir>/.nixmac/settings.json`
+
+Settings that travel with the user's nix/darwin config **repository** (agent limits, per-repo defaults, etc.). Rust: repo-scoped configurable slices via `storage/configurable_scope.rs`.
+
+When unsure which tier: build-time constant → profile; follows the person → user prefs; follows the repo → project level.

.cursor/rules/native-env.mdc

@@ -0,0 +1,22 @@
+---
+description: Environment access — only through env.ts
+globs: apps/native/**/*.ts,apps/native/**/*.tsx
+alwaysApply: false
+---
+
+# Environment variables — `env.ts` only
+
+**Do not use `process.env` or `import.meta.env` anywhere except `apps/native/src/lib/env.ts`.**
+
+All app code reads deployment settings through exports from that module (`settings`, `nixmacEnvironment`, `getProfileValue`, etc.).
+
+Benefits: single validation path, typed profile JSON, no scattered env reads, and build-time profile baking stays consistent with Rust (`build.rs`).
+
+```typescript
+// ❌ BAD
+const key = import.meta.env.VITE_POSTHOG_KEY;
+
+// ✅ GOOD
+import { settings } from "@/lib/env";
+const key = settings.posthogKey;
+```

.cursor/rules/native-errors.mdc

@@ -0,0 +1,22 @@
+---
+description: TypeScript error handling with nostics in the native app
+globs: apps/native/**/*.ts,apps/native/**/*.tsx
+alwaysApply: false
+---
+
+# TypeScript errors — use `nostics`
+
+Define and report user-facing errors through **`nostics`** in `apps/native/src/lib/errors.ts`.
+
+- Add diagnostic codes, titles, suggestions, and `defineDiagnostics` entries there — not ad hoc strings in components.
+- Import `diagnostics` (or helpers like `getRebuildErrorTitle`) from `@/lib/errors` when surfacing errors in UI.
+- Rust-side errors exposed to the frontend should map to stable codes that have entries in `errors.ts`.
+
+```typescript
+// ❌ BAD — one-off error copy in a component
+toast.error("Something went wrong with the provider");
+
+// ✅ GOOD — structured diagnostic
+import { diagnostics, DIAGNOSTIC_CODES } from "@/lib/errors";
+diagnostics.report(DIAGNOSTIC_CODES.EVOLVE_NO_PROVIDER);
+```

.cursor/rules/native-orpc.mdc

@@ -0,0 +1,44 @@
+---
+description: oRPC and React Query for Rust ↔ TypeScript IPC in the native app
+globs: apps/native/**/*.ts,apps/native/**/*.tsx,apps/native/src-tauri/**/*.rs
+alwaysApply: false
+---
+
+# Rust ↔ TypeScript IPC — use oRPC
+
+All new Rust ↔ TypeScript communication must go through **oRPC** (fully typed end-to-end).
+
+## Codegen (required after router changes)
+
+```bash
+cd apps/native && bun run gen:orpc
+```
+
+- Rust procedures: `apps/native/src-tauri/src/orpc/`
+- Generated TS bindings: `apps/native/src/ipc/orpc-bindings.ts` (do not edit)
+- Client + TanStack Query helpers: `apps/native/src/lib/orpc.ts`
+
+## Prefer React Query over `invoke()`
+
+oRPC integrates with **TanStack Query** via `orpc` helpers. This is the default for data that is fetched, cached, polled, or invalidated.
+
+```tsx
+// ✅ GOOD — cached, deduplicated, lifecycle-aware
+import { useQuery } from "@tanstack/react-query";
+import { orpc } from "@/lib/orpc";
+
+const { data } = useQuery(orpc.github.listRepos.queryOptions({ input: undefined }));
+```
+
+```ts
+// ❌ BAD — new feature wired through legacy invoke()
+import { invoke } from "@tauri-apps/api/core";
+await invoke("some_new_command");
+```
+
+- **`client`** — direct async calls for one-off/imperative flows (no cache needed).
+- **`orpc` + hooks** — anything that should behave like server state in React.
+
+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.
+
+Legacy `invoke()` in `apps/native/src/ipc/api.ts` is deprecated; migrate callers to oRPC when touching them.

.cursor/rules/native-state-package.mdc

@@ -0,0 +1,13 @@
+---
+description: Where TypeScript state and data-fetching code lives
+globs: apps/native/**/*.ts,apps/native/**/*.tsx,packages/state/**/*
+alwaysApply: false
+---
+
+# State and data fetching — `packages/state`
+
+TypeScript code for **state, data fetching, storage, and cache** belongs in **`packages/state`** (import: `@nixmac/state`).
+
+- Query hooks, selectors, and client-side projections live here — not scattered in `apps/native/src/components/`.
+- Server/async data from Rust: use oRPC + React Query (see `native-orpc` rule); wire hooks in `packages/state` when shared across views.
+- Existing Zustand slices (`viewmodel`, `ui`, `onboarding`) hold **client-side** and **event-projected** state only — do not extend them for new IPC fetch paths.

.cursor/rules/ui-directory.mdc

@@ -0,0 +1,5 @@
+---
+alwaysApply: true
+---
+
+Components in packages/ui/src/components/ui are generated by shadcn - they must NEVER be modified. UI components should be place in the parent packages/ui/src/components/ instead.