vault backup: 2026-04-17 13:21:24

99 Daily/2026-04-17.md

@@ -305,3 +305,9 @@ tags: [daily]
 - 13:20 | `Barclays-banner-builder`
   - **Asked:** Create an idempotent deployment script for Docker containers on Ubuntu with Apache reverse proxy and database migrations.
   - **Done:** Generated deploy.sh script with Docker build caching, database initialization, and Alembic migrations; committed changes and pushed to main branch.
+- 13:20 | `memory-compiler`
+  - **Asked:** Compile a new troubleshooting article into the wiki knowledge base with structured sections and cross-references.
+  - **Done:** Created `wiki/claude-code/troubleshooting.md` with quick-reference error table, platform-specific diagnostics, and wikilinks to related articles.
+- 13:21 (<1min) | `memory-compiler`
+  - **Asked:** Create and file a structured wiki article on the TypeScript V2 SDK interface into the knowledge base.
+  - **Done:** Wrote article covering V2 exports and usage patterns, then updated both the agent-sdk topic index and master index with new counts.

wiki/_master-index.md

@@ -30,9 +30,9 @@ This 3-hop pattern works for hundreds of articles without vector search.
 | [[wiki/web-agency/_index\|web-agency/]] | AI-assisted website building & selling: Claude Code, Nanobanana 2, Kling, LaunchPath MCP | 1 |
 | [[wiki/dotfiles/_index\|dotfiles/]] | Linux terminal ricing: Kitty, Fish, WezTerm CLI, modern Rust CLI tools, LazyVim, unified themes, Tabby | 19 |
 
-| [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 27 |
+| [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 28 |
 | [[wiki/llm-models/_index\|llm-models/]] | OpenAI model catalog — GPT-5.x, o-series reasoning, audio/realtime, embeddings, moderation | 1 |
-| [[wiki/claude-code/_index\|claude-code/]] | Claude Code product docs — install, capabilities, surfaces, MCP, hooks, scheduling, multi-agent, plugins, skills, channels, error recovery | 11 |
+| [[wiki/claude-code/_index\|claude-code/]] | Claude Code product docs — install, capabilities, surfaces, MCP, hooks, scheduling, multi-agent, plugins, skills, channels, error recovery | 12 |
 
 <!-- New topic folders added here automatically as they are created -->
 <!-- Format: | [[wiki/topic/_index\|topic/]] | One-line description | N articles | -->

wiki/agent-sdk/_index.md

@@ -41,3 +41,4 @@ Build production AI agents using the same tools, agent loop, and context managem
 | [[wiki/agent-sdk/subagents\|subagents]] | Spawn subagents programmatically or via filesystem; context isolation, parallelization, tool restrictions, resuming, detection | raw/Subagents in the SDK.md | 2026-04-17 |
 | [[wiki/agent-sdk/todo-tracking\|todo-tracking]] | Built-in TodoWrite tool: lifecycle states, automatic triggers, real-time progress display, activeForm field | raw/Todo Lists.md | 2026-04-17 |
 | [[wiki/agent-sdk/cost-tracking\|cost-tracking]] | Token usage tracking, deduplicating parallel tool calls, per-model cost breakdown, accumulating across sessions | raw/Track cost and usage.md | 2026-04-17 |
+| [[wiki/agent-sdk/typescript-v2-interface\|typescript-v2-interface]] | V2 preview: session-based send/stream pattern, no async generators, createSession/resumeSession/prompt, cleanup | raw/TypeScript SDK V2 interface (preview).md | 2026-04-17 |

wiki/agent-sdk/typescript-v2-interface.md

@@ -0,0 +1,150 @@
+---
+title: "TypeScript SDK V2 Interface (Preview)"
+aliases: [typescript-v2, sdk-v2, agent-sdk-v2]
+tags: [agent-sdk, typescript, v2, preview, sessions, multi-turn]
+sources: [raw/TypeScript SDK V2 interface (preview).md]
+created: 2026-04-17
+updated: 2026-04-17
+---
+
+# TypeScript SDK V2 Interface (Preview)
+
+> **Unstable preview** — APIs may change before becoming stable. Session forking and some advanced streaming patterns remain V1-only.
+
+V2 removes async generators and yield coordination. Each conversation turn is a discrete `send()` / `stream()` cycle — no generator state to manage across turns.
+
+## Installation
+
+```sh
+npm install @anthropic-ai/claude-agent-sdk
+```
+
+Same package as V1; V2 is additive under `unstable_v2_*` exports.
+
+## Core API Surface
+
+Three concepts cover the full interface:
+
+| Concept | Function | Purpose |
+|---------|----------|---------|
+| Start session | `unstable_v2_createSession()` | New conversation |
+| Resume session | `unstable_v2_resumeSession(id)` | Continue a stored session |
+| One-shot | `unstable_v2_prompt()` | Single-turn, no session needed |
+
+### SDKSession Interface
+
+```typescript
+interface SDKSession {
+  readonly sessionId: string;
+  send(message: string | SDKUserMessage): Promise<void>;
+  stream(): AsyncGenerator<SDKMessage, void>;
+  close(): void;
+}
+```
+
+`send()` dispatches the message; `stream()` pulls the response. The explicit separation makes it easy to insert logic between turns.
+
+## Usage Patterns
+
+### One-shot prompt
+
+```typescript
+import { unstable_v2_prompt } from "@anthropic-ai/claude-agent-sdk";
+
+const result = await unstable_v2_prompt("What is 2 + 2?", {
+  model: "claude-opus-4-7"
+});
+if (result.subtype === "success") {
+  console.log(result.result);
+}
+```
+
+### Basic session (single turn)
+
+```typescript
+import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk";
+
+await using session = unstable_v2_createSession({ model: "claude-opus-4-7" });
+
+await session.send("Hello!");
+for await (const msg of session.stream()) {
+  if (msg.type === "assistant") {
+    const text = msg.message.content
+      .filter((b) => b.type === "text")
+      .map((b) => b.text)
+      .join("");
+    console.log(text);
+  }
+}
+```
+
+`await using` (TypeScript 5.2+) auto-closes the session when the block exits. Use `session.close()` manually on older TS.
+
+### Multi-turn conversation
+
+Call `send()` again on the same session — Claude retains prior context:
+
+```typescript
+await session.send("What is 5 + 3?");
+for await (const msg of session.stream()) { /* ... */ }
+
+await session.send("Multiply that by 2");  // references previous answer
+for await (const msg of session.stream()) { /* ... */ }
+```
+
+### Session resume (across restarts)
+
+Capture `msg.session_id` from any streamed message, close the session, then resume later:
+
+```typescript
+// Initial session
+const session = unstable_v2_createSession({ model: "claude-opus-4-7" });
+await session.send("Remember this number: 42");
+
+let sessionId: string | undefined;
+for await (const msg of session.stream()) {
+  sessionId = msg.session_id;
+}
+session.close();
+
+// Resume later
+await using resumed = unstable_v2_resumeSession(sessionId!, {
+  model: "claude-opus-4-7"
+});
+await resumed.send("What number did I ask you to remember?");
+for await (const msg of resumed.stream()) { /* ... */ }
+```
+
+## Cleanup
+
+| Method | When to use |
+|--------|------------|
+| `await using session = ...` | TypeScript 5.2+ — auto-closes on block exit |
+| `session.close()` | Older TS or explicit lifecycle control |
+
+## V1 Features Not Yet in V2
+
+- Session forking (`forkSession` option)
+- Some advanced streaming input patterns
+
+Use [[wiki/agent-sdk/typescript-api-reference|typescript-api-reference]] (V1) for these.
+
+## Key Takeaways
+
+- **No generators** — V2 replaces the async generator / yield pattern with explicit `send()` + `stream()` per turn
+- **Three exports** cover everything: `unstable_v2_createSession`, `unstable_v2_resumeSession`, `unstable_v2_prompt`
+- **Session ID** is available on every `SDKMessage` as `msg.session_id` — capture it to enable resume
+- **`await using`** (TS 5.2+) provides automatic resource cleanup; fall back to `.close()` otherwise
+- **Unstable prefix** signals the API is a preview — don't ship production code against it without pinning the version
+- **Same package** as V1 — no separate install; V1 and V2 coexist
+
+## Related Articles
+
+- [[wiki/agent-sdk/typescript-api-reference|TypeScript V1 API Reference]] — full stable API, session forking, advanced streaming
+- [[wiki/agent-sdk/streaming-input|Streaming Input]] — V1 AsyncGenerator vs string input modes
+- [[wiki/agent-sdk/streaming-output|Streaming Output]] — StreamEvent structure, text_delta, UI patterns
+- [[wiki/agent-sdk/agent-loop|Agent Loop]] — message lifecycle, turns, compaction, sessions
+
+## Sources
+
+- `raw/TypeScript SDK V2 interface (preview).md`

wiki/claude-code/_index.md

@@ -25,3 +25,4 @@ Claude Code is Anthropic's agentic coding assistant. Works across terminal, IDE,
 | [[wiki/claude-code/channels\|channels]] | Push events into a running session via MCP channels: Telegram/Discord/iMessage bridges, webhook receivers, security allowlist, enterprise controls | raw/Push events into a running session with channels.md | 2026-04-17 |
 | [[wiki/claude-code/headless-cli\|headless-cli]] | Run Claude Code non-interactively via `-p` flag: bare mode, structured output, streaming, tool approval, conversation resumption | raw/Run Claude Code programmatically.md | 2026-04-17 |
 | [[wiki/claude-code/scheduled-tasks\|scheduled-tasks]] | /loop, CronCreate/List/Delete tools, fixed vs dynamic intervals, loop.md, one-time reminders, jitter, 7-day expiry, scheduling options compared | raw/Run prompts on a schedule.md | 2026-04-17 |
+| [[wiki/claude-code/troubleshooting\|troubleshooting]] | Install errors quick-ref, PATH/proxy/TLS fixes, platform issues (Linux/macOS/Windows/WSL), auth problems, performance, IDE integration | raw/Troubleshooting.md | 2026-04-17 |

wiki/claude-code/troubleshooting.md

@@ -0,0 +1,273 @@
+---
+title: "Claude Code Troubleshooting"
+aliases: [claude-code-troubleshoot, claude-install-errors, claude-debug]
+tags: [claude-code, troubleshooting, installation, auth, windows, wsl, linux, macos]
+sources: [raw/Troubleshooting.md]
+created: 2026-04-17
+updated: 2026-04-17
+---
+
+# Claude Code Troubleshooting
+
+Quick-reference for installation failures, auth errors, performance problems, and IDE issues.
+
+---
+
+## Installation Error Quick-Reference
+
+| Symptom | Fix |
+|---------|-----|
+| `command not found: claude` | Add `~/.local/bin` to PATH |
+| `syntax error near unexpected token '<'` | Install script returned HTML (geo-block or network issue) |
+| `curl: (56) Failure writing output` | Network interrupted mid-download; retry or use Homebrew/WinGet |
+| `Killed` during install on Linux | OOM — add 2 GB swap |
+| `TLS connect error` / `SSL/TLS secure channel` | Update CA certs; set `NODE_EXTRA_CA_CERTS` for corporate proxy |
+| `Failed to fetch version` | `storage.googleapis.com` blocked; set `HTTPS_PROXY` |
+| `irm is not recognized` / `&& is not valid` | Wrong shell — use correct installer for CMD/PowerShell/Bash |
+| `Claude Code on Windows requires git-bash` | Install Git for Windows; set `CLAUDE_CODE_GIT_BASH_PATH` in settings |
+| `Error loading shared library` | musl/glibc mismatch — reinstall with correct binary |
+| `Illegal instruction` on Linux | CPU arch mismatch (ARM vs x86) — verify with `uname -m` |
+| `dyld: cannot load` / `Abort trap: 6` on macOS | macOS < 13.0 or binary incompatibility — update macOS |
+| `App unavailable in region` | Country not supported |
+
+---
+
+## Install Diagnostics
+
+### Network check
+```bash
+curl -sI https://storage.googleapis.com   # installer downloads from here
+```
+
+### Proxy setup (corporate networks)
+```bash
+export HTTP_PROXY=http://proxy.example.com:8080
+export HTTPS_PROXY=http://proxy.example.com:8080
+curl -fsSL https://claude.ai/install.sh | bash
+```
+
+### PATH fix (macOS/Linux)
+```bash
+# Zsh
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
+
+# Bash
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
+```
+
+### Conflicting installs
+```bash
+which -a claude                          # find all claude binaries
+npm uninstall -g @anthropic-ai/claude-code  # remove npm install
+brew uninstall --cask claude-code        # remove Homebrew install
+```
+
+### Directory permissions
+```bash
+test -w ~/.local/bin && echo "writable" || echo "not writable"
+sudo mkdir -p ~/.local/bin && sudo chown -R $(whoami) ~/.local
+```
+
+---
+
+## Platform-Specific Issues
+
+### Linux: Low-memory install failure (`Killed`)
+Claude Code requires ≥ 4 GB RAM. Add swap:
+```bash
+sudo fallocate -l 2G /swapfile
+sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile
+curl -fsSL https://claude.ai/install.sh | bash
+```
+
+### Linux: musl/glibc mismatch
+```bash
+ldd /bin/ls | head -1   # shows "linux-vdso" (glibc) or "musl"
+# On Alpine (musl):
+apk add libgcc libstdc++ ripgrep
+```
+
+### macOS: `dyld` errors
+- Requires macOS 13.0+. Check: Apple menu → About This Mac
+- Fallback: `brew install --cask claude-code`
+
+### Docker: Install hangs
+```dockerfile
+WORKDIR /tmp
+RUN curl -fsSL https://claude.ai/install.sh | bash
+```
+Add `--memory=4g` if using Docker Desktop.
+
+### Windows: Shell mismatch
+| Shell | Command |
+|-------|---------|
+| PowerShell | `irm https://claude.ai/install.ps1 \| iex` |
+| CMD | `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd` |
+| WinGet | `winget install Anthropic.ClaudeCode` |
+
+### Windows: Claude Desktop overrides CLI
+Update Claude Desktop to latest — older versions register `Claude.exe` that shadows the CLI.
+
+### Windows: Git Bash required
+Install from [git-scm.com](https://git-scm.com/downloads/win). If already installed:
+```json
+{ "env": { "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe" } }
+```
+
+### WSL2 Issues
+- **Node from Windows PATH**: `which npm` should point to `/usr/` not `/mnt/c/` — use nvm in Linux
+- **OAuth login**: `export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"`
+- **JetBrains not detected**: Add Windows Firewall rule for WSL2 subnet, or set `networkingMode=mirrored` in `.wslconfig`
+- **Sandboxing**: `sudo apt-get install bubblewrap socat`; WSL1 does not support sandboxing
+
+---
+
+## Authentication & Permissions
+
+### Repeated permission prompts
+Use `/permissions` to allowlist specific tools.
+
+### Auth flow reset
+```
+/logout → close → reopen claude → re-authenticate
+```
+If browser doesn't open: press `c` to copy OAuth URL.
+
+### OAuth: Invalid code
+Token expired or truncated — press Enter to retry quickly after browser opens.
+
+### 403 Forbidden
+- Claude Pro/Max: check subscription at claude.ai/settings
+- Console users: verify "Claude Code" or "Developer" role assigned
+- Proxy users: see [[wiki/claude-code/mcp-integration|MCP & network config]]
+
+### Model not found
+Check model setting priority (highest wins):
+1. `--model` flag
+2. `ANTHROPIC_MODEL` env var
+3. `.claude/settings.local.json`
+4. `.claude/settings.json`
+5. `~/.claude/settings.json`
+
+Run `/model` inside Claude to pick from available models.
+
+### Disabled org with active subscription
+Stale `ANTHROPIC_API_KEY` overriding subscription credentials:
+```bash
+unset ANTHROPIC_API_KEY
+claude
+# remove from ~/.zshrc or ~/.bashrc permanently
+```
+
+### macOS Keychain issues
+```bash
+claude doctor                             # check Keychain access
+security unlock-keychain ~/Library/Keychains/login.keychain-db
+```
+
+### Token expired frequently
+Check system clock accuracy — token validation is time-sensitive.
+
+---
+
+## Configuration Files
+
+| File | Purpose |
+|------|---------|
+| `~/.claude/settings.json` | User settings (permissions, hooks, model overrides) |
+| `.claude/settings.json` | Project settings (committed) |
+| `.claude/settings.local.json` | Local project settings (not committed) |
+| `~/.claude.json` | Global state (theme, OAuth, MCP servers) |
+| `.mcp.json` | Project MCP servers (committed) |
+
+### Full reset
+```bash
+rm ~/.claude.json && rm -rf ~/.claude/ && rm -rf .claude/ && rm .mcp.json
+```
+
+---
+
+## Performance & Stability
+
+### High CPU/memory
+- Run `/compact` regularly
+- Restart between major tasks
+- Add build dirs to `.gitignore`
+- Run `/heapdump` → inspect `.heapsnapshot` in Chrome DevTools
+
+### Auto-compaction thrashing
+`Autocompact is thrashing` = a single file keeps refilling context. Fix:
+- Ask Claude to read file in smaller chunks (line ranges, functions)
+- `/compact keep only the plan and the diff`
+- Move large-file work to a [[wiki/claude-code/custom-subagents|subagent]]
+- `/clear` to start fresh
+
+### Search not working (`@file`, custom skills)
+Install system ripgrep:
+```bash
+brew install ripgrep          # macOS
+winget install BurntSushi.ripgrep.MSVC  # Windows
+sudo apt install ripgrep      # Ubuntu/Debian
+apk add ripgrep               # Alpine
+```
+Then set `USE_BUILTIN_RIPGREP=0` in environment.
+
+### WSL: Slow / incomplete search
+Move project to Linux filesystem (`/home/`) instead of `/mnt/c/`.
+
+---
+
+## IDE Integration
+
+### JetBrains: Escape key not working
+Settings → Tools → Terminal → uncheck "Move focus to the editor with Escape"
+
+### JetBrains: Not detected on WSL2
+Option 1 — Windows Firewall rule:
+```powershell
+New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16
+```
+Option 2 — mirrored networking in `.wslconfig`:
+```ini
+[wsl2]
+networkingMode=mirrored
+```
+
+---
+
+## Markdown Formatting Issues
+
+- Code blocks missing language tags → ask: "Add appropriate language tags to all code blocks"
+- Use PostToolUse hooks to auto-run `prettier` on generated markdown
+- Document preferred style in `CLAUDE.md` (see [[wiki/claude-code/overview|overview]])
+
+---
+
+## Diagnostics Command
+
+```
+/doctor
+```
+Checks: install type, version, search, auto-update, settings JSON validity, MCP config errors, keybindings, context warnings, plugin loading.
+
+---
+
+## Key Takeaways
+
+- **`command not found`** almost always means `~/.local/bin` is not in PATH — add it to shell config
+- **Corporate networks**: set `HTTP_PROXY`/`HTTPS_PROXY` and `NODE_EXTRA_CA_CERTS` before installing
+- **Linux OOM**: add swap before installing on low-RAM VPS; Claude Code needs ≥ 4 GB
+- **macOS requires 13.0+**; use Homebrew as fallback install method on any platform
+- **Windows**: use the right installer for your shell (PowerShell vs CMD vs WSL)
+- **Auth problems**: try `/logout` → restart → re-auth; check for stale `ANTHROPIC_API_KEY` env var
+- **Model not found**: check all 5 config layers in priority order; use `/model` picker to verify access
+- **Performance**: `/compact` reduces context; `/heapdump` diagnoses memory growth
+- **Search broken**: install system `ripgrep` and set `USE_BUILTIN_RIPGREP=0`
+- **`/doctor`** is the first diagnostic to run for any unexplained issue
+
+---
+
+## Sources
+
+- [Troubleshooting — Claude Code Docs](https://code.claude.com/docs/en/troubleshooting)
+- See also: [[wiki/claude-code/error-reference|Error Reference]], [[wiki/claude-code/overview|Claude Code Overview]]