context7.json

{
  "$schema": "https://context7.com/schema/context7.json",
  "projectTitle": "Ragmir",
  "description": "Confidential local retrieval and evidence for agentic RAG workflows, with offline cited retrieval. The TypeScript CLI, library, read-focused MCP server, and portable skills keep the corpus and index under ignored local state. Optional local Chat and TTS remain separate packages.",
  "excludeFolders": [
    "node_modules",
    "packages/ragmir-core/dist",
    "packages/ragmir-tts/dist",
    "packages/ragmir-chat/dist",
    "packages/ragmir-landing/dist",
    "packages/ragmir-landing/.astro",
    "packages/ragmir-core/examples",
    "coverage",
    "release-artifacts",
    "private",
    ".ragmir",
    ".gitnexus",
    ".git"
  ],
  "excludeFiles": ["CHANGELOG.md", "pnpm-lock.yaml"],
  "rules": [
    "Ragmir v3.0.0 and later are licensed under AGPL-3.0-only, with a separate commercial licensing option from JCode Works for proprietary use. Earlier releases keep their published license.",
    "Use the canonical English setup prompt in docs/quick-start.md for a repository-aware installation; it detects the package manager and existing state, asks before changes or downloads, and verifies retrieval.",
    "Ragmir Core is the local retrieval and evidence layer for agentic RAG workflows. It is not an autonomous agent, planner, or action runtime; planning, tool use, and action authority stay in the host.",
    "Any compatible coding agent, script, CLI, TypeScript application, or MCP client can consume Core results; use a local consumer when no passage may leave the machine.",
    "Use `rgr portable export` to create a frozen relocatable folder containing the active index, any required local embedding model, a restricted launcher, portable skills, MCP adapters, and a SHA-256 inventory. Raw source files and access logs are excluded, but indexed passages remain sensitive. Verify the folder after moving it and keep action authority in the host agent or automation.",
    "Use one `createRagmirClient()` per project root for repeated work in a stateful Node.js process; it caches one immutable read snapshot until atomic generation replacement and flushes metadata-only access logs during close. Use top-level functions for one-shot scripts.",
    "Ragmir does not open an HTTP port; a network-facing host owns its transport, authentication, authorization, and rate limits.",
    "`rgr chat` is optional add-on generation via @jcode.labs/ragmir-chat; the core remains retrieval-only.",
    "@jcode.labs/ragmir-chat exposes lite (Qwen2.5 0.5B), default fast (Gemma 4 E2B), and explicit quality (Gemma 4 E4B) profiles; setup, doctor, and generation should use the same profile, and none is required by Core or MCP.",
    "@jcode.labs/ragmir-tts selects a language-specific offline MMS model for en, fr, or es; explicit online Edge mode also supports ja, th, and zh, and its default voice follows the selected language.",
    "The `local-hash` embedding provider (default) is a lexical sha256 embedding, not semantic; use `transformers` for semantic retrieval.",
    "The local-hash path does not resolve Transformers.js, ONNX Runtime, or Sharp. Bundled Transformers profiles use pinned model commits; explicit pull records a canonical artifact digest.",
    "Switching `embeddingProvider`, embedding model, revision, or artifact digest requires a rebuild because those identities produce incompatible vectors and fingerprints. Use `rgr upgrade` for the staged safe path.",
    "Ingestion commits resumable file batches under ignored `.ragmir/storage/` state; use `rgr status --json` for progress, and expect `--rebuild` to preserve the active index until a staged generation is validated.",
    "Use `rgr ingest --metrics --json` or `collectMetrics: true` for optional local phase and throughput observability. The bounded `ragmir:ingestion` event excludes project roots, source paths, raw queries, and source text; timers and RSS sampling stay disabled without a request or subscriber.",
    "Run `rgr upgrade --check` after updating the package and before retrieval with the new runtime. `rgr upgrade` refreshes managed helpers and safely stages any required rebuild without deleting the active index first; a long-running host can cut over after status=current and ready=true. `rgr doctor --fix` uses the same repair path.",
    "Config resolves from the caller's working directory (`.ragmir/config.json`), never from the package install path.",
    "In a monorepo, the nearest configured ancestor is active; use `rgr bases --json` or explicit `--project-root` to verify routing.",
    "Git-backed teams run `rgr team sync`: Ragmir fetches the current branch upstream, applies only a clean non-divergent fast-forward, then refreshes the private local index. `--no-pull` disables branch updates and `--check` previews. Dirty, ahead, diverged, detached, offline, and no-upstream states never rewrite history. Advanced snapshots remain available for exact or non-Git drift diagnostics; keep actively written .ragmir/storage directories local to each workstation.",
    "Use `rgr preview` to inspect redacted chunks without writing an index, and `search(..., { explain: true })` only when rank diagnostics are needed.",
    "Explained searches expose a ranking-policy fingerprint, deterministic vector and lexical contributions, FTS or complete-fallback activation and reason, candidate budgets, and lexical coverage; truncated fallback scans are rejected.",
    "The bounded primary FTS pool uses structural context and body text. Exact file paths use a bounded scalar variant. Controlled phrase, identifier, and rare-term queries expand only an insufficient primary pool. Diversification selects distinct sources first, then backfills ranked non-duplicate, non-overlapping chunks to topK.",
    "Search, embedding, and ingestion use separate bounded process-local queues per project root. Saturation returns retryable OVERLOADED, queue expiry returns TIMEOUT, caller cancellation removes queued work, and explained searches expose workloadQueueMs.",
    "Research uses language-aware query variants and deterministic weighted cross-query RRF; it reads manifest health by default, makes a full source audit explicit, and reports its timeout, code-scan, and result budgets.",
    "Generated PDF OCR setup batches up to 16 blank pages and stores private content-addressed page cache entries keyed by source, engine version, language, DPI, parser policy, and command identity. Ingest and preview report only OCR counts and timing.",
    "Vector search is exact below 100,000 rows and uses the compatible IVF-PQ policy stored in the manifest at larger sizes; set `vectorSearchMode: \"exact\"` or use `--exact-vector-search` for diagnostic comparison.",
    "Run `rgr storage optimize --dry-run --json` to inspect full-text, vector, and relative-path index coverage before applying maintenance.",
    "MCP resources `ragmir://context` and `ragmir://sources` are bounded agent-orientation surfaces; retrieval still happens through the read-focused tools. Search, ask, and research start with at most three compact document citations by default; research may add three code matches. Expand one selected citation or request `compact: false` explicitly.",
    "All ten MCP tools advertise non-destructive behavior and every tool or resource JSON response is byte-bounded. Budget pressure selects typed summaries with exact scalar values, omission counters, and the best search citation instead of shortening identifiers or paths. Search, ask, research, and evaluation conservatively advertise open-world behavior because explicitly enabled semantic models may download public weights. Tools that can initialize local state or append metadata-only logs use conservative read-only and idempotency hints. Each server refreshes its lazy client after effective configuration changes and closes it during shutdown.",
    "MCP `ragmir_evaluate` accepts only an existing project-relative golden file and rejects absolute paths, traversal, and symlinks outside the project. Strict mode returns that relative path, replaces evaluation errors with a generic message, and masks configured model, storage, source, and access-log paths in diagnostic responses."
  ]
}