neurolink: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code when working in this repository.

Critical Rules

These are non-negotiable. Violating them breaks the build or introduces bugs.

1. Dynamic imports only in registry — All providers must use dynamic imports inside factory functions in providerRegistry.ts. Static imports create circular dependencies.
2. Types in canonical location — All type definitions go in src/lib/types/. Never create type files inside feature subdirectories.
3. Gemini tools + JSON schema are mutually exclusive — Google AI Studio and Vertex Gemini models cannot use tools and structuredOutput with a JSON schema simultaneously (a Gemini API limitation). This does not apply to Vertex Claude models, which support both at once — the exclusion is gated on isGeminiProvider in structuredOutputPolicy.ts, not on the Vertex provider as a whole. Providers that reject the combination at runtime (e.g. Groq) are detected via isToolsSchemaConflictError and transparently retried without structured output. Regardless of provider, generate({ schema }) is guaranteed to return valid JSON in content plus a parsed structuredData object (see coerceJsonToSchema).
   • Huge-text / truncation: the native Claude paths (Vertex+Claude, direct Anthropic) must default max_tokens to the model's real output ceiling via resolveClaudeMaxTokens (Sonnet 4.x → 64K, Opus 4.x → 32K), never the legacy hard-coded 4096 that silently truncated large structured responses mid-JSON. The direct Anthropic non-streaming path also passes an explicit request timeout so the SDK's "streaming is required for long requests" pre-flight guard doesn't reject a large max_tokens. When output still hits the cap, truncation is surfaced — not silent: coerceJsonToSchema returns { repaired, truncated }, and GenerateResult exposes jsonRepaired / jsonTruncated (set when finishReason==="length" or the recovered JSON came from an unclosed span) plus a WARN log. A truncated response must still yield a partial object — never a raw string: coerceJsonToSchema prefers the candidate starting at the document's real root (so a bracket pair scraped from inside a string value can't win), and backs off to the last completed field when jsonrepair can't close the span. That recovered structuredData is a plain object, not necessarily a schema-valid one — when the response was cut short it may be partial — and jsonTruncated is set in exactly that case (jsonRepaired when the JSON had to be recovered), so a caller can distinguish a salvaged object from a complete one. A caller that needs schema-valid data must check jsonTruncated before trusting the object; a caller that wants best-effort data can use it as is. Only schema-rejected scalar roots (e.g. a raw string under an object schema) are suppressed via schemaAccepts, since they carry no recoverable structure.
4. CLI ≠ SDK — CLI can use manual MCP connections; the SDK cannot. Keep concerns separate.
5. Backward compatibility — Public SDK API must not break existing callers.
6. formatProviderError must return, never throw — Any provider error formatter must return the error object, not throw it.
7. Zero interface — always use type — Never use interface. Always use type X = { ... }. The only exception is declare global { interface Window { ... } } which TypeScript requires for declaration merging. Use intersection (&) instead of extends.
8. No "Types" suffix in type filenames — Files inside src/lib/types/ must not contain "Types" or "Type" in their name. The folder IS the types folder — mcp.ts not mcpTypes.ts, auth.ts not authTypes.ts.
9. Unique type names across all files — Every exported type name must be globally unique across all files in src/lib/types/. Use domain prefixes to disambiguate:
   • Client SDK types: Client* prefix (e.g., ClientAuthConfig, ClientToolInfo, ClientStreamResult)
   • CLI types: Cli* prefix (e.g., CliGenerateResult, CliStreamChunk)
   • Server types: Server* prefix (e.g., ServerAuthConfig)
   • Stream types: Stream* prefix (e.g., StreamToolCall, StreamToolResult)
   • Processor types: Processor* prefix (e.g., ProcessorRetryConfig)
   • Workflow judge types: Judge* prefix (e.g., JudgeScoreResult)
10. Barrel uses export * only — src/lib/types/index.ts must only contain export * from "./file.js" lines. No selective exports (export type { X, Y }), no aliases (X as Y). If adding export * causes a name collision, rename the type at the source with a domain prefix per rule 9.
11. No local types/ directories — There must be no types/ directory anywhere except src/lib/types/. No src/lib/observability/types/, no src/lib/workflow/core/types/, etc. Move those types into the canonical src/lib/types/ folder.
12. No type re-exports from non-type files — Files outside src/lib/types/ must not re-export types (export type { X } from). Consumers should import types from src/lib/types/ directly. Module index.ts files should only re-export runtime values (classes, functions, constants), never types.