fix: Fix pnpm clean, add troubleshooting docs and reorganize docs/ (#973)

Author: charlesvien

README.md

@@ -40,6 +40,8 @@ pnpm dev:agent  # Run agent in watch mode
 pnpm dev:twig   # Run twig app
 ```
 
+> **Want to connect to a local PostHog instance?** See [docs/LOCAL-DEVELOPMENT.md](./docs/LOCAL-DEVELOPMENT.md) for OAuth setup and connecting to localhost:8010.
+
 ### Utility Scripts
 
 Scripts in `scripts/` for development and debugging:
@@ -54,59 +56,29 @@ Scripts in `scripts/` for development and debugging:
 ```
 twig/
 ├── apps/
-│   ├── twig/       # Electron desktop app (React, Vite)
-│   ├── mobile/     # React Native mobile app (Expo)
-│   └── cli/        # CLI for stacked PRs
+│   ├── twig/            # Electron desktop app (React, Vite)
+│   ├── mobile/          # React Native mobile app (Expo)
+│   └── cli/             # CLI for stacked PRs
 ├── packages/
-│   ├── agent/      # TypeScript agent framework
-│   ├── core/       # Shared business logic
-│   ├── electron-trpc/  # tRPC for Electron IPC
-│   └── shared/     # Shared utilities (Saga pattern, etc.)
+│   ├── agent/           # TypeScript agent framework
+│   ├── core/            # Shared business logic
+│   ├── electron-trpc/   # tRPC for Electron IPC
+│   └── shared/          # Shared utilities (Saga pattern, etc.)
 ```
 
 ## Documentation
 
 | File | Description |
 |------|-------------|
-| [CLAUDE.md](./CLAUDE.md) | Code style, patterns, and testing guidelines |
-| [UPDATES.md](./UPDATES.md) | Release versioning and git tagging |
 | [apps/twig/README.md](./apps/twig/README.md) | Desktop app: building, signing, distribution, and workspace configuration |
 | [apps/twig/ARCHITECTURE.md](./apps/twig/ARCHITECTURE.md) | Desktop app: dependency injection, tRPC, state management, and events |
 | [apps/mobile/README.md](./apps/mobile/README.md) | Mobile app: Expo setup, EAS builds, and TestFlight deployment |
 | [apps/cli/README.md](./apps/cli/README.md) | CLI: stacked PR management with Jujutsu |
+| [CLAUDE.md](./CLAUDE.md) | Code style, patterns, and testing guidelines |
+| [docs/LOCAL-DEVELOPMENT.md](./docs/LOCAL-DEVELOPMENT.md) | Connecting Twig to a local PostHog instance |
+| [docs/UPDATES.md](./docs/UPDATES.md) | Release versioning and git tagging |
+| [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) | Common issues and fixes |
 
 ## Troubleshooting
 
-### Electron failed to install correctly
-
-If you see this error when running `pnpm dev`:
-
-```
-Error: Electron failed to install correctly, please delete node_modules/electron and try installing again
-```
-
-The electron binary didn't download during install. Fix it by running the install script manually:
-
-```bash
-cd node_modules/electron && node install.js
-```
-
-Or nuke it and reinstall:
-
-```bash
-rm -rf node_modules/electron && pnpm install && cd node_modules/electron && node install.js
-```
-
-### Native module crash (libc++abi / Napi::Error)
-
-If the app crashes with something like:
-
-```
-libc++abi: terminating due to uncaught exception of type Napi::Error
-```
-
-Native modules (like node-pty) need to be rebuilt for your Electron version:
-
-```bash
-pnpm --filter twig exec electron-rebuild
-```
+See [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) for common issues (black screen, Electron install failures, native module crashes, etc.).

apps/mobile/package.json

@@ -10,7 +10,8 @@
     "prebuild": "expo prebuild",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
-    "format": "biome format --write ."
+    "format": "biome format --write .",
+    "clean": "rm -rf .turbo .expo"
   },
   "dependencies": {
     "@expo/ui": "0.2.0-beta.9",

apps/twig/package.json

@@ -27,7 +27,8 @@
     "test:e2e:headed": "playwright test --config=tests/e2e/playwright.config.ts --headed",
     "postinstall": "cd ../.. && npx @electron/rebuild -f -m node_modules/node-pty || true && bash apps/twig/scripts/patch-electron-name.sh && node apps/twig/scripts/download-binaries.mjs",
     "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build"
+    "build-storybook": "storybook build",
+    "clean": "rm -rf .vite .turbo out node_modules/.vite"
   },
   "keywords": [
     "posthog",

apps/twig/scripts/update-openapi-client.ts

@@ -14,7 +14,7 @@ if (!POSTHOG_API_HOST) {
 
 const SCHEMA_URL = `${POSTHOG_API_HOST}/api/schema/`;
 const TEMP_SCHEMA_PATH = "temp-openapi.yaml";
-const OUTPUT_PATH = "src/api/generated.ts";
+const OUTPUT_PATH = "src/renderer/api/generated.ts";
 
 const INCLUDED_ENDPOINT_PREFIXES = [
   "/api/projects/{project_id}/tasks",