claude-setup

Fix for webhook authorization failures caused by Base64 padding character (=) being dropped when copying secrets between systems. Use when: (1) Webhook returns "Unauthorized" or "Server Error" but the secret looks correct, (2) INTERNAL_API_SECRET, WEBHOOK_SECRET, or similar auth tokens fail validation between Railway/Vercel and Convex/database, (3) Secret comparison fails despite values appearing identical, (4) CLI tools display truncated environment variables. Common with Railway CLI, Vercel CLI, and other deployment platforms that may not display trailing = characters.

Search through Claude Code session memories and learned skills. Use when: (1) you need to find how a similar problem was solved before, (2) looking for relevant skills or knowledge, (3) checking if there's existing context about a project or technology, (4) the user asks "have we done this before?" or "what do you remember about X?". Triggers on: memory search, recall, remember, past sessions, history, previous work.

Understanding Convex + Better Auth dual-database architecture. Use when: (1) "User not found" errors during login/password reset but user appears to exist, (2) users exist in app's users table but can't authenticate, (3) need to create admin users in production, (4) debugging auth flows in Convex + Better Auth setup. Better Auth stores users in component tables separate from app tables.

Manage Better Auth user data in Convex component tables. Use when: (1) need to manually verify user email in development, (2) "Email not verified" error blocking login, (3) need to modify Better Auth user/session/account data directly, (4) can't write mutations to access component tables, (5) debugging auth issues in Convex + Better Auth setup. Covers CLI data access, export/import workflow, and common gotchas.

Fix for "Unauthorized" errors in Convex mutations called from Next.js API routes when using internal API secrets for authentication. Use when: (1) Convex mutation throws "Unauthorized" even though secret is set in .env.local, (2) webhook handlers fail with 500 status and "Unauthorized" in Convex function, (3) internal API calls work locally in Next.js but fail when calling Convex mutations. The fix is to set the secret in BOTH Next.js .env.local AND Convex environment variables.

Fix for expo-file-system migration errors when upgrading to Expo SDK 52+. Use when: (1) TypeScript error "Property 'cacheDirectory' does not exist on type", (2) "Module has no exported member 'EncodingType'" error, (3) "Property 'deleteAsync' does not exist" or similar FileSystem function errors, (4) file.info returns a function instead of file info object, (5) Upgrading Expo SDK and expo-file-system code breaks. Covers migration from legacy function-based API (FileSystem.deleteAsync, getInfoAsync) to new class-based API (File, Directory, Paths classes).

Fix for Ghost Admin API posts created with empty content when using HTML. Use when: (1) Ghost posts are created successfully but have no body content, (2) HTML field is sent in POST request but post appears empty, (3) title appears but html/body is blank, (4) implementing Ghost Admin API integration with HTML content. The fix is to use source=html as a QUERY PARAMETER, not in the JSON request body.

Fix for Next.js OG image build errors with invalid CSS display values. Use when: (1) Build fails with "Invalid value for CSS property display", (2) error mentions allowed values "flex" | "block" | "none" | "-webkit-box", (3) using display: inline-block or other CSS display values in next/og ImageResponse components. The fix is to use display: flex with alignSelf: flex-start instead of inline-block.

Fix for NextResponse.redirect going to wrong host (localhost:8080) on Railway, Vercel, or containerized deployments. Use when: (1) redirects work locally but go to localhost in production, (2) console shows ERR_CONNECTION_REFUSED to localhost:8080 or similar internal URL, (3) using `new URL(path, request.url)` for redirects in Next.js API routes or middleware. The fix is to use NEXT_PUBLIC_APP_URL environment variable instead of request.url as the base URL.

Build multi-model AI orchestrators using OpenRouter with Aider. Use when: (1) "No endpoints found" or "Missing API Key" errors with OpenRouter models, (2) "Argument list too long" when passing large files to Aider, (3) JSON parsing fails due to line-wrapped output from Aider, (4) building cost-effective agent systems with model routing, (5) git merge fails with "untracked working tree files would be overwritten" for .aider.* files. Covers model naming conventions, litellm prefix requirements, --read flag for large files, JSON cleaning for programmatic output extraction, and worktree merge handling.

Fix for OpenRouter image generation with Gemini/Nano Banana models returning 404 or 400 errors. Use when: (1) OpenRouter API returns 404 Not Found for image generation, (2) getting 400 Bad Request with "Invalid option" for aspect_ratio, (3) response parsing fails with "error decoding response body", (4) using /images/generations endpoint with Nano Banana or Gemini image models. The fix is to use /chat/completions endpoint with modalities parameter instead of the images endpoint.

Fix for OpenRouter image generation response parsing. Use when: (1) using OpenRouter API with image generation models like google/gemini-2.5-flash-image, (2) response doesn't contain expected image data, (3) looking for base64 image in wrong location. Images are returned in message.images array, not in standard OpenAI format. Covers correct endpoint, response parsing, and base64 extraction.

Capture OAuth authorization codes when localhost redirect fails in Playwright browser automation. Use when: (1) OAuth flow redirects to localhost but "localhost refused to connect" appears, (2) authorization code in URL is lost before you can copy it, (3) automating OAuth flows where no local server is running to receive the callback, (4) desktop app OAuth flows with redirect_uri=http://localhost. Uses Playwright's route interception to capture the URL before the request fails.

Fix for "X cannot be used as a JSX component" TypeScript errors in pnpm monorepos. Use when: (1) Build fails with "ForwardRefExoticComponent is not a valid JSX element type", (2) Component worked before but now fails type checking after adding a new package, (3) Error mentions ReactNode or ReactElement type incompatibility, (4) Multiple packages in monorepo have different @types/react versions. The fix uses pnpm overrides to force a single React types version across all packages.

Fix for Polar SDK subscription cancellation. Use when: (1) TypeScript error "Property 'cancel' does not exist on type 'Subscriptions'", (2) trying to cancel a Polar subscription via SDK, (3) build failure with polar.subscriptions.cancel(). The correct method is revoke() not cancel().

Fix for "no method named `form` found" or "use of unresolved method `form`" errors when using reqwest in Rust. Use when: (1) reqwest `.form()` method not found at compile time, (2) sending URL-encoded form data to APIs like OAuth token endpoints, (3) upgrading from older reqwest versions where form worked without feature flag. The `form` feature must be explicitly enabled in Cargo.toml for reqwest 0.11+.

Fix for "let chains are only allowed in Rust 2024 or later" errors when downgrading Cargo.toml edition from 2024 to 2021. Use when: (1) changing edition = "2024" to edition = "2021", (2) compilation fails with let chain errors across multiple files, (3) need to systematically refactor `if let ... && let ...` patterns to nested if-let. Covers the refactoring patterns for converting let chains to 2021-compatible code.

Comprehensive methodology for conducting technical reviews of Rust projects. Use when: (1) reviewing unfamiliar Rust codebases, (2) conducting project health assessments, (3) evaluating code quality and architecture, (4) preparing project audits or due diligence. Covers structure analysis, code quality assessment, security review, and documentation evaluation.

Fix Rust audio compilation and runtime issues on WSL2 using rodio/cpal. Use when: (1) Build fails with "The system library 'alsa' required by crate 'alsa-sys' was not found", (2) Cannot install libasound2-dev without sudo access, (3) Runtime error "Unknown PCM default" or "cannot find card '0'" even after successful compilation. Covers compilation workaround using manual .deb extraction AND runtime fix using ALSA-to-PulseAudio routing.

Fix infinite loops in demo/showcase modes for scene stack architectures. Use when: (1) Demo mode gets stuck repeating the same scene, (2) scene cycling doesn't progress through all scenes, (3) orchestrator scene's on_resume isn't being called, (4) pushed scenes bypass the demo controller. Applies to game engines, UI frameworks, and any stack-based state machine with automated testing or demo modes.

Meta-skill for creating, updating, and managing Claude Code skills. Use when: (1) discovering reusable knowledge that should be preserved as a skill, (2) an existing skill needs updating with new information or corrections, (3) user explicitly asks to "save as skill", "create a skill", or "update skill", (4) after debugging sessions that revealed non-obvious solutions, (5) when patterns emerge that would help in future similar situations. This skill handles the full lifecycle: creation, updates, and organization.

Discover all actionable tasks in the current project and add them to the task list

Fix for Tauri app not loading .env file with dotenvy. Use when: (1) Environment variables return "not set" errors in Tauri commands, (2) dotenvy::from_filename() fails with relative paths like "../../.env", (3) API keys or config work locally but not in Tauri app, (4) GhostClient::from_env() or similar fails with missing env vars. The fix is that `cargo tauri dev` runs with CWD at project root, not at ui/src-tauri, so use ".env" not "../../.env".

Pattern for real-time streaming from CLI tools to Tauri GUI by watching JSONL files. Use when: (1) building a Tauri app that needs to display output from a CLI tool, (2) need real-time updates in GUI from an external process, (3) bridging Rust backend events to React/TypeScript frontend. Covers file polling with position tracking, Tauri event emission, and frontend event listeners with type mapping.

Tauri IPC commands fail silently when testing via browser at localhost. Use when: (1) Tauri invoke() calls return no data or fail silently in Playwright/browser tests, (2) window.__TAURI__ is undefined when accessing localhost:port directly, (3) App works in Tauri window but not when tested via browser automation, (4) React Query or other data fetching shows empty results for Tauri commands. The fix is to test in the actual Tauri webview or mock the Tauri API for browser tests.

Fix for Tauri v2 app crashing on startup in WSL2 with gdk-pixbuf panic: "data.len() must fit the width, height, and row_stride". Use when: (1) Tauri app panics immediately on launch in WSL2/Linux, (2) error occurs in gdk-pixbuf crate at pixbuf.rs, (3) crash happens before window renders, (4) app works on Windows/macOS but fails on Linux/WSL2. The fix is to use an empty icon array in tauri.conf.json to bypass icon loading issues with GTK.