obsidian-yolo: Instructions file for Codex

Repository Guidelines

YOLO is an Obsidian plugin for AI chat, agent workflows, RAG, writing assistance, and independently shipped product modules such as FSRS-based Learning and the Whiteboard infinite canvas.

For a behavior ↔ code-location ↔ verification-path index (complements this file's directory-ownership rules, doesn't restate them), see FEATURE_MAP.md.

Commands

Verify what you touched: host code → type-check + relevant tests; module code → module typecheck, tests, npm --prefix modules/<id> run test:boundary when available, and module build; runtime component code → runtime typecheck, tests, build, and verify; host CSS → styles build (module CSS is rebuilt by the module build).

• npm run dev - Build runtime components and first-party modules, then watch the host app, host styles, and dev-vault artifacts
• npm run build - Production build with host, module, and runtime component type checking; run for changes affecting production bundling, module boundaries, runtime loading, or cross-platform behavior
• npm run type:check / npm run module:typecheck / npm run runtime:typecheck - Type-check the host, first-party modules, or runtime components
• npm run module:build - Rebuild first-party module artifacts and the bundled module catalog
• npm run runtime:build / npm run runtime:verify - Rebuild runtime component artifacts and their registry, or verify the host bundle doesn't statically pull in a runtime component's dependencies
• npm run lint:check / npm run lint:fix - Check or fix Prettier and ESLint
• npm test - Run the full Jest suite; use npx jest <test-file> --runInBand for serial debugging
• npm run styles:build - Regenerate the host styles.css from src/styles/**
• npm run deps:check - Enforce the circular-dependency ratchet; after removing cycles, tighten the baseline with npm run deps:baseline

Architecture

• src/main.ts owns the host plugin lifecycle. src/ChatView.tsx and src/components/chat-view/ own the main chat surface.
• src/core/modules/ owns module discovery, installation, loading, activation, lifecycle, and the versioned Host API. modules/host-sdk.d.ts is the module-facing API contract.
• modules/<id>/ owns everything in a product module: its UI, domain logic, host adapters, styles, assets, workers, and tests. modules/learning/ and modules/whiteboard/ hold the complete Learning and Whiteboard implementations.
• src/core/runtime-components/ owns discovery, download, and lifecycle of on-demand runtime components. runtime-components/<id>/ at the repo root owns each component's source and build output; runtime-components/sdk.d.ts is the component-facing contract.
• src/core/agent/ owns the shared native agent runtime, tool gateway, conversation service, subagents, and background tasks. Quick Ask, Sidebar Chat, and Agent Chat run through AgentService.run; permissions come from resolveChatModeRuntime.
• src/core/cli-runtime/ owns the external CLI agent runtimes the chat surface can switch to. They are a separate execution surface alongside AgentService, not a second orchestration of it, and are desktop-only — keep their implementations out of the mobile static graph.
• src/core/ai/single-turn.ts is the low-latency path for Sparkle (tab completion, selection rewrite, continuation). Do not route these features through the agent runtime.
• src/core/tools/ owns every built-in tool: capabilities/ is the single registration point, and the tool catalog, settings rows, approval policy, persisted keys, and the chat summary classification are all derived from it — never add a side table. dispatcher.ts is the only execution path. Deferred disclosure is the only mode: a tool outside the request's tools array is reached through the protocol-internal invoke_tool / load_tool_schemas, which carry no capability and never appear in settings. Evaluate approval and every other per-tool policy against the unwrapped call, never the wrapper.
• src/core/llm/, auth/, rag/, mcp/, and skills/ own shared model, provider, retrieval, and MCP capabilities.
• src/features/ contains host-shipped cross-cutting features. src/database/, src/settings/, and src/styles/ own host persistence, settings, and global styles.