jcode-ragmir

Imported from jcode-works/jcode-ragmir (AGENTS.md). Install upstream with npx skills add jcode-works/jcode-ragmir. Copyright stays with the author.

Ragmir

Working rules

• Speak with users in French. Keep code, identifiers, comments, file names, and commit messages in English.
• Keep the repository free of private documents, generated .ragmir/ state, credentials, and environment files.
• Ragmir is open source under AGPL-3.0-only, with a separate commercial licensing option from JCode Works. Keep manifest, package, documentation, landing, and release metadata aligned with that policy. Do not add activation, account, hosted-storage, native-shell, or cloud-vendor integrations.
• Do not merge an external code contribution unless the maintainer has confirmed the contributor grants the rights needed for both the AGPL and commercial licensing paths.
• The repository is a pnpm workspace. Use the pinned Node version from mise.toml; Rust is not part of this project.
• Start feature work from develop on feature/*, use pull requests into develop, and never publish or deploy without explicit confirmation.

Product boundary

• packages/ragmir-core provides @jcode.labs/ragmir: the rgr CLI, TypeScript library, MCP server, and portable skills.
• packages/ragmir-chat is the optional local GGUF synthesis add-on used by rgr chat.
• packages/ragmir-tts is the optional local/offline audio add-on used by rgr audio.
• Core must install and start without Chat or TTS. Keep both as optional peer integrations and load them only when their command is used.
• packages/ragmir-landing is a self-contained, telemetry-free Astro site. Keep it static, open-source focused, and free of vendor deployment configuration.
• Ragmir Core stays retrieval-first: local-hash supports offline retrieval, transformers is the explicit semantic option, and local chat remains a separate add-on.
• Long-running Node.js processes use one RagmirClient per project root and close it during shutdown. Keep the top-level API for one-shot scripts.
• Ragmir does not provide an HTTP server or fixed port. A network-facing host owns transport security, authentication, authorization, and rate limits.
• Index writers are serialized across local OS processes through a private lock under storageDir; do not claim a distributed or shared-network-filesystem lock.
• Git-backed team sync treats the current branch upstream as the declared authority. Fetch only that branch, fast-forward only a clean non-divergent history, then ingest incrementally. Never stash, reset, rebase, create a merge commit, or delete the active index. --no-pull keeps branch updates manual; fetch and ingest failures preserve the last valid local index when one exists.
• Metadata-only snapshots are advanced diagnostics for exact or non-Git drift. Never include source text or absolute project paths, choose an authoritative copy, or modify peer sources.
• Package upgrades must preserve the last validated index until an incompatible replacement passes staged-generation validation and activates atomically. Older configs keep safe defaults; never require deleting .ragmir/storage/ as the first repair step.
• Public copy must lead with model-agnostic Core and the choice between the user's preferred AI or automation and a fully local consumer. Qwen and Gemma are optional Chat profiles, never Core or MCP requirements.

Privacy and ingestion

• Resolve project data from the caller’s working directory or explicit configuration, never from the package installation path.
• Keep .ragmir/ ignored. Use local-hash retrieval by default, redact before indexing, keep access logs metadata-only, and bound MCP retrieval.
• Keep ingestion windows bounded independently by source bytes, estimated chunks, vector bytes, file count, and concurrency; commit durable progress per file.
• External extraction remains opt-in. OCR only runs for blank PDF pages through a configured local command, never a shell or cloud service.
• Emit line citations only when they map to source lines; use format-native page, slide, sheet/cell, and EPUB spine coordinates for transformed documents.
• Do not claim universal binary support, blanket compliance, legal advice, or certification.

Documentation

• The root README.md is the short canonical entrypoint: what Ragmir is, installation, first use, library API, MCP, and links to focused docs.
• Keep docs/ concise and task-oriented: CLI, API, configuration, agent integration, troubleshooting, local chat, and local TTS. Remove future plans and obsolete surfaces rather than documenting them.
• Package READMEs are brief npm entrypoints that link to the root README.
• Keep the English setup prompt identical across Core, the landing, root and package READMEs, docs/quick-start.md, and the wiki. The public-surface smoke test enforces repository copies.
• Keep llms.txt and context7.json aligned with public documentation and generated-output exclusions.
• When code changes public behavior, commands, configuration, supported formats, architecture, or product claims, update the relevant docs and landing in the same change. For internal-only changes, verify both surfaces and leave them unchanged when no update is needed.
• Lead public documentation with the value proposition, a working quick start, and the strongest guarantees. Move operational depth to focused guides instead of repeating it across READMEs.
• Present team use as one positive workflow: merge reviewed changes upstream, run rgr team sync, receive a ready private index. Keep snapshots and low-level safeguards in focused advanced guides.

Validation

• Run the smallest relevant check while editing and pnpm validate before a release pull request.
• Reconcile git status with the intended scope before staging. Never stage secrets or generated local state.
• Use Conventional Commits. Commit and push only when the user authorizes them.
• Every commit promoted to main that can trigger semantic-release must include these exact body sections with at least one bullet each: Release highlights:, Release details:, and Verification:. Highlights state user outcomes, details group the meaningful work by product area, and verification names the gates actually run. Never reduce a release to a generic subject line or raw commit list. Keep commit body lines within Commitlint's 100-character limit. When a release bullet wraps, indent every continuation line by at least two spaces; the release notes generator joins those lines into one complete public bullet.

Code conventions

• Keep responsibilities small and reuse the existing Core modules for discovery, parsing, redaction, chunking, embeddings, storage, and retrieval.
• Validate external inputs at boundaries with Zod or CLI parsers. Prefer type guards over casts and named exports over defaults.
• Only the CLI writes to stdout or stderr. Pipeline and library modules return values.

GitNexus

The repository is indexed as jcode-ragmir.

• Before editing a function, class, or method, run upstream impact analysis and report HIGH or CRITICAL risk before continuing.
• Run gitnexus_detect_changes() before committing and refresh the index once after the final commit.
• Use gitnexus_rename for symbol renames. If the index is stale, run npx gitnexus analyze before relying on it.

GitNexus: Code Intelligence

This project is indexed by GitNexus as jcode-ragmir (2005 symbols, 4448 relationships, 165 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.

Index stale? Run node .gitnexus/run.cjs analyze from the project root. It auto-selects an available runner. No .gitnexus/run.cjs yet? npx gitnexus analyze (npm 11 crash → npm i -g gitnexus; #1939).

Always Do

• MUST run impact analysis before editing any symbol. Before modifying a function, class, or method, run impact({target: "symbolName", direction: "upstream"}) and report the blast radius (direct callers, affected processes, risk level) to the user.
• MUST run detect_changes() before committing to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: detect_changes({scope: "compare", base_ref: "main"}).
• MUST warn the user if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
• When exploring unfamiliar code, use query({search_query: "concept"}) to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
• When you need full context on a specific symbol (callers, callees, and participating execution flows), use context({name: "symbolName"}).
• For security review, explain({target: "fileOrSymbol"}) lists taint findings (source→sink flows; needs analyze --pdg).

Never Do

• NEVER edit a function, class, or method without first running impact on it.
• NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
• NEVER rename symbols with find-and-replace. Use rename, which understands the call graph.
• NEVER commit changes without running detect_changes() to check affected scope.

Resources

CLI