Record native-Windows-vs-WSL decision and LAN Ollama implication

Adds to handoff: rationale for choosing native Windows over WSL2
(global hotkey, OS notifications, clipboard image, tray, data path,
performance measurements all break under WSLg). Pre-flight
checklist updated so Ollama runs on a LAN server, not on the
Windows machine. Notes the one-line env-var change needed in Plan
Task 30 to wire LocalOllamaProvider to a LAN endpoint, and clarifies
that this is configuration (not a new Provider class).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-04-25 02:15:10 +00:00
parent ea8791848c
commit ccc166917a

View File

@@ -176,6 +176,53 @@ If the user already started a `git status` and there are local changes (e.g. `no
---
## Decision: Native Windows over WSL2 (2026-04-25)
User asked whether to use WSL Ubuntu 24.04 or native Windows. **Native Windows chosen.** Reasons:
1. **Global hotkey** — WSL Electron cannot register a Windows OS-level shortcut. `Ctrl+Shift+J` from real Windows apps (Chrome, Slack, Excel) won't reach WSL Electron. Spec §1.1 core feature broken; "3-second friction" hypothesis (Spec §0 hypothesis 1) untestable.
2. **OS native notifications** — WSLg cannot bridge libnotify to Windows action center. Strategy §4.1 immediate-reward toast invisible when user is in another app.
3. **Clipboard image paste** — WSLg image clipboard is unreliable. In-scope screenshot flow (Spec §1.1) breaks.
4. **Tray icon** — WSLg has no system tray API. Tray menu, close-to-hide, "구출한 메모 보기" entry path (Spec §5.5) gone.
5. **Data path**`\\wsl$\...` instead of `%APPDATA%\Inkling\`. User can't browse data via Explorer.
6. **Performance numbers** — "hotkey → window p95 < 100ms" measurement skewed by WSLg compositor.
Dev-DX cost (less Linux-shell familiarity) is single-session pain. Dogfood-hypothesis cost (WSL silently breaks the slice) is fatal.
**Hybrid recommendation:** core dev (npm/Electron) on Windows native; WSL allowed only as auxiliary for Linux utilities (`grep`/`find`/`jq`) when convenient.
### Pre-flight checklist for the Windows machine
1. Node 24.15.0 LTS via **nvm-windows** or **Volta**
2. **Visual Studio Build Tools 2022** + workload "Desktop development with C++" (required for `better-sqlite3` native compile)
3. **Ollama on a LAN server** (not on the Windows machine). User-defined IP, e.g. `http://192.168.x.y:11434`. Pre-pull `gemma4:9b` on that server. Confirm reachable from Windows: `curl http://<lan-ip>:11434/api/tags` should list `gemma4:9b`.
4. **Git for Windows**
5. Editor (VS Code, Cursor, etc.)
6. **Claude Code for Windows**
### Implication for slice plan/spec (LAN Ollama)
The slice plan currently wires `new LocalOllamaProvider()` with no args (defaults to `http://localhost:11434`) in **Plan Task 30 main entry**. Since the dogfood machine reaches Ollama over LAN, that one line needs adjustment. Two minimal-change paths:
- **Env var (recommended):** change the Task 30 instantiation to
```ts
const provider = new LocalOllamaProvider({
endpoint: process.env.INKLING_OLLAMA_ENDPOINT
});
```
`undefined` falls back to localhost (preserves Linux/local-Ollama dev). Set `INKLING_OLLAMA_ENDPOINT=http://192.168.x.y:11434` in Windows env (User-level Environment Variables) before running `npm run dev`.
- **Hardcode for dogfood:** pass the LAN URL directly during dogfood; revert before any commit. Simplest but not committable.
Spec §1.2 lists "LAN Ollama Provider" as deferred, but that meant a separate `LanOllamaProvider` *class*. `LocalOllamaProvider` already accepts a custom `endpoint`, so this is configuration, not new code. The Provider abstraction (Spec §2.2) was designed for exactly this.
The new session should ask the user whether to fold the env-var change into Task 30 (preferred) or treat it as a one-off dogfood hardcode.
Health-check expectations under LAN:
- LAN unreachable (server off, wrong IP, firewall) → OllamaBanner shows "Inkling 정리가 잠시 멈췄습니다. Ollama를 실행해주세요." Capture continues normally; pending notes accumulate. Spec §6.1 row 4 behavior unchanged.
- 120s generate timeout (Plan Task 12) is generous enough to absorb LAN latency on slow GPUs. No tuning needed initially.
---
## What this session did NOT do
- No code written