SQLite migration rules for the Ghost codebase. MUST READ before writing or modifying any file in migrations/. Covers: table recreation patterns, column ordering, CHECK constraint changes, NOT NULL safety, and the validation checklist. A faulty migration that ships breaks the production daemon on startup with no recovery path short of manual DB surgery — these rules are non-negotiable.
Read when you need to browse, traverse, or query the knowledge system beyond basic knowledge_search — graph traversal, tag exploration, orphan detection, reference browsing, topic listing, or direct SQL access.
Import and update external content in the knowledge base — git repos, web crawls, documents (PDF, DOCX), and books (EPUB). Use when the OPERATOR wants persistent, searchable reference material from a git repository, website, document, or book, or when existing references may be stale and need refreshing.
Ghost's Lua scripting layer internals. MUST READ before modifying anything in src/scripting/, prompts/stdlib/, prompts/agents/*/agent.lua, or agent hook logic. Covers: ScriptHost VM lifecycle, sandbox, host globals, ctx bindings, nudge library, template module, custom tools, type stubs, and the PreTurnState contract.
Use when reading or changing GHOST configuration (providers, models, timing, compaction, services, any config.toml key), adding or switching LLM providers, answering questions about GHOST's own features or capabilities, a CLI tool is missing or "not found", services need starting/stopping/debugging, updating GHOST to a newer version, managing the Nix shell environment, or troubleshooting GHOST setup.
Triage and fix issues reported via Ghost's /feedback command. MUST READ when the user points you to a feedback folder, mentions a feedback report, or asks you to investigate a bug that happened during a GHOST session. Covers: retrieving feedback from remote servers, reading transcripts and debug request dumps, root-cause categorization, and the fix workflow.
Read before first use of the browser tool in a session. Covers browser selection workflow (list → pick → connect), when to use headless vs operator browser, how to guide the OPERATOR to expose their browser with `ghost browsers serve`, tab management, element refs, and web_fetch session sharing.
Tracing, observability, and instrumentation conventions for the Ghost codebase. MUST READ before adding or modifying: tracing spans, #[tracing::instrument] attributes, tracing::info_span!() calls, OTel semantic convention fields (gen_ai.*), span hierarchy, or any observability-related code. Failure to follow these conventions produces inconsistent telemetry.