neuralvault

This skill should be used when modifying api/internal/retrieval/ (query, streaming answers, chunk hydration), or when asked "how does retrieval work", "why re-filter after Qdrant already filtered", "add a new caller of loadChunks", "why does Retrieve query Postgres full-text too". Documents four non-obvious invariants in the retrieval pipeline that look redundant or arbitrary but aren't.

This skill should be used when modifying api/internal/auth/ (login, session, RequireUser middleware), or when asked "how does login work here", "how are sessions handled", "add a protected route". Documents the three login surfaces and the custom session scheme, since neither is a standard JWT/OIDC-library setup.

This skill should be used automatically before finishing a nontrivial NeuralVault diff, or when asked to "review this", "check this against conventions", "does this follow the codebase style" — without requiring the explicit /review command. Checks a diff against NeuralVault's own layering and terminology rules.

This skill should be used when adding or modifying a feature domain under api/internal/ (auth, health, retrieval, sources, workspaces, or a new one), or when asked "how do I add a new endpoint/domain", "where does this logic go", "how are Go tests structured here". Documents the three-file domain layout, its justified exceptions, and the testing conventions.

This skill should be used when adding a new backend to embedding, llm, vectorstorage, objectstorage, or storage (e.g. "add an OpenAI provider", "add a new LLM backend", "swap the vector database"), or when asked how NeuralVault's pluggable-provider pattern works. Documents the interface-package shape, the fail-fast startup convention, and two known exceptions that look like bugs but aren't.

This skill should be used when modifying api/internal/embedding/ollama/ or api/internal/llm/ollama/, or when asked "why did the server fail to start over Ollama", "how does streaming work here", "add timeout handling to the LLM client". Documents the fail-fast model check and why the LLM client has no HTTP timeout.

This skill should be used when adding a database migration, or when asked "add a column/table", "why isn't the schema updated", "how do I run migrations here". Documents that migrations are a fully separate binary from the API server and are never run automatically.

This skill should be used when modifying api/internal/vectorstorage/, or when asked "how is the vector store abstracted here", "why does the interface use Qdrant types directly", "swap the vector database". Documents that the Client interface is intentionally typed against Qdrant's own protobuf types, not neutral domain types.

This skill should be used when the user asks to "run NeuralVault", "start the app", "start the API", "start the frontend", "launch the stack", "sign in locally", or wants to see a change working end-to-end in the running application. Provides NeuralVault's actual local launch sequence (Docker infra + Go API + Next.js frontend), overriding generic app-launch guidance.

This skill should be used when adding, customizing, or theming a UI component under web/ (e.g. "add a dialog", "add a shadcn button", "set up a form", "change the color palette", "add dark mode"), or when asked how shadcn/ui works in this project. Documents the official shadcn/ui CLI and conventions only — no third-party registries or paid services.

This skill should be used when modifying api/internal/sources/ (upload, ingest, indexing, SSE status) or api/internal/sourcereader/, or when asked "how does ingestion work", "why is a source stuck indexing", "add a new source type". Documents the in-process background indexing model and its concurrency/recovery safeguards.

This skill should be used when adding or changing a handler's swaggo annotations, or when asked "why did CI fail on swagger docs", "regenerate the API docs", "add Swagger annotations to this endpoint". Documents the annotation → make swag → CI drift-check flow and the constraint on running it automatically.

This skill should be used before committing a nontrivial NeuralVault change, or when asked "verify this works", "check this end-to-end", "does this pass CI". Mirrors NeuralVault's actual CI gates (ci-api.yml, ci-web.yml, the swagger-drift check, test-coverage-web.yml) and describes how to exercise the affected flow live, not just run tests.

This skill should be used when adding a new API call, hook, or component under web/, or when asked "how do I fetch data in the frontend here", "where does this API call go", "add a new page". Documents the fetch-wrapper -> TanStack Query hook -> component layering, which is real and consistent in the codebase but not written down in web/README.md.

This skill should be used when modifying api/internal/workspaces/ or adding a new workspace-scoped route, or when asked "how is tenant isolation enforced", "why isn't EnsureMember middleware", "add role-based permissions". Documents why the membership guard is a manual function call, not middleware, and that roles exist but aren't enforced yet.