feat: refine evidence workflows and local AI positioning

.gitignore

@@ -32,3 +32,25 @@ packages/ragmir-core/examples/**/.ragmir/models/
 packages/ragmir-core/examples/**/.ragmir/reports/
 packages/ragmir-core/examples/**/.ragmir/audio/
 .gitnexus
+
+# Ragmir
+.claude/skills/ragmir
+.claude/skills/ragmir-audio-summary
+.claude/skills/ragmir-markdown-report
+.claude/skills/ragmir-legal-dossier
+.agents/skills/ragmir
+.agents/skills/ragmir-audio-summary
+.agents/skills/ragmir-markdown-report
+.agents/skills/ragmir-legal-dossier
+.kimi/skills/ragmir
+.kimi/skills/ragmir-audio-summary
+.kimi/skills/ragmir-markdown-report
+.kimi/skills/ragmir-legal-dossier
+.opencode/skills/ragmir
+.opencode/skills/ragmir-audio-summary
+.opencode/skills/ragmir-markdown-report
+.opencode/skills/ragmir-legal-dossier
+.cline/skills/ragmir
+.cline/skills/ragmir-audio-summary
+.cline/skills/ragmir-markdown-report
+.cline/skills/ragmir-legal-dossier

AGENTS.md

@@ -15,6 +15,7 @@
 - `packages/ragmir-tts` is the optional local/offline audio add-on used by `rgr audio`.
 - `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.
+- 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
 
@@ -50,3 +51,48 @@ 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:start -->
+# 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, which execution flows it participates in — 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
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/jcode-ragmir/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/jcode-ragmir/clusters` | All functional areas |
+| `gitnexus://repo/jcode-ragmir/processes` | All execution flows |
+| `gitnexus://repo/jcode-ragmir/process/{name}` | Step-by-step execution trace |
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

CHANGELOG.md

@@ -1,68 +1,32 @@
 # Changelog
 
-## Unreleased
+Ragmir publishes its canonical version history through
+[GitHub Releases](https://github.com/jcode-works/jcode-ragmir/releases). Each release is generated
+by semantic-release from the Conventional Commits merged into `main`, after the repository
+validation workflow passes.
 
-- Rename the public CLI commands to `rgr` and `rgr-tts`.
-- Keep `ragmir`, `kb`, and `ragmir-tts` as deprecated compatibility bins that warn users to migrate
-  to `rgr` / `rgr-tts`.
-- Add deterministic prompt routing through `rgr route-prompt` and MCP `ragmir_route_prompt`.
+This file is intentionally a stable entrypoint instead of a second, manually maintained copy of
+the version history.
 
-## 0.4.2 - 2026-06-29
+## Release history
 
-- Add `rgr doctor` to diagnose initialization, index freshness, security posture, and next steps.
-- Make `rgr audio` and `rgr-tts` default to the offline/confidential Transformers.js WAV path;
-  Edge MP3 now requires an explicit `--engine edge` command.
-- Stop indexing the generated `private/README.md` helper file created by `rgr init`.
-- Improve onboarding output from `rgr init` and `rgr install-skill`.
+- [Latest release](https://github.com/jcode-works/jcode-ragmir/releases/latest)
+- [All releases and version comparisons](https://github.com/jcode-works/jcode-ragmir/releases)
+- [Current TypeScript API reference](./docs/api-reference.md)
 
-## 0.4.1 - 2026-06-29
+Each GitHub release contains generated feature, fix, and compatibility notes plus the verification
+artifacts produced by the release workflow.
 
-- Add an Edge-compatible Ragmir TTS engine so `rgr audio` can match the global Voice Forge quality
-  path with `edge-tts`, `fr-FR-DeniseNeural`, and MP3 output.
-- Keep Transformers.js WAV rendering as the explicit offline/confidential path.
-- Remove duplicated governance documents from package directories; root project docs are the single
-  source of truth.
+## API compatibility
 
-## 0.4.0 - 2026-06-28
+Ragmir follows Semantic Versioning:
 
-- Reposition Ragmir as sovereign local RAG for confidential datasets and AI agents.
-- Expand default ingestion to common text, Office/OpenDocument, data, config, log, and source-code
-  file types.
-- Add `includeExtensions` / `RAGMIR_INCLUDE_EXTENSIONS` for custom UTF-8 text file extensions.
-- Add the optional `ragmir-audio-summary` bundled skill for confidential audio summaries.
-- Install both the main Ragmir skill and optional audio-summary skill with `rgr install-skill`.
-- Improve agent guidance for deep multi-query retrieval before synthesis.
-- Make Ragmir core retrieval-only: `rgr ask` now returns cited context for external agents or LLMs
-  instead of generating answers internally.
-- Add optional Transformers.js semantic embeddings through `embeddingProvider: "transformers"`.
-- Remove Ollama providers and keep `embeddingProvider: "local-hash"` as the no-model default.
-- Move the repository to a simple pnpm workspace monorepo without adding Turbo.
-- Move the core `@jcode.labs/ragmir` package into `packages/ragmir-core`.
-- Add `@jcode.labs/ragmir-tts` for plug-and-play JS/ONNX WAV rendering without Python or ffmpeg.
-- Add `rgr audio` and update the audio-summary skill to use Ragmir TTS before advanced fallback
-  engines.
+- `fix` commits produce patch releases.
+- `feat` commits produce minor releases.
+- commits with a `BREAKING CHANGE` footer produce major releases and surface the compatibility
+  change in the generated release notes.
+- documentation commits produce patch releases so the npm documentation stays current.
+- landing-only commits do not publish the library packages.
 
-## 0.3.0 - 2026-06-28
-
-- Add confidentiality hardening defaults: built-in redaction before indexing, metadata-only access
-  logs, and bounded MCP retrieval.
-- Add `rgr security-audit` for zero-telemetry, provider, redaction, gitignore, storage, and
-  MCP posture checks.
-- Add `rgr destroy-index --yes` to remove generated vector indexes.
-- Add release verification artifacts: npm tarball, SHA256 checksums, SBOM, and manifest.
-- Document air-gapped operation, threat model, MCP hardening, and secure deletion limits.
-
-## 0.2.1 - 2026-06-28
-
-- Add maintainer positioning for Jean-Baptiste Thery and JCode Labs in the README.
-- Make `rgr init` and `rgr install-skill` automatically keep `.ragmir/` ignored by Git.
-
-## 0.2.0 - 2026-06-28
-
-- Rename public product branding to Ragmir while keeping the JCode Labs npm scope.
-- Add the bundled portable `ragmir` agent skill.
-- Add the MCP stdio server with `ragmir_status`, `ragmir_search`, `ragmir_ask`, and
-  `ragmir_audit`.
-- Add production smoke coverage for the built CLI and MCP server.
-- Add Biome, commitlint, publint, CodeQL, Dependabot grouping, protected npm publishing,
-  and open-source contribution/security documentation.
+Check the release notes for the version you plan to install, then compare the
+[API reference](./docs/api-reference.md) when upgrading across a major version.

CLAUDE.md

@@ -30,3 +30,50 @@ verify both surfaces and leave them unchanged when no update is needed.
 Ragmir stores and retrieves local cited context. It has no hosted document store, account system,
 native desktop shell, or cloud-vendor deployment configuration. Keep OCR optional and
 local, remote model downloads explicit, and normal confidential retrieval offline.
+Describe Core as model-agnostic: users can connect their preferred AI or automation, or keep the
+consumer local. Qwen and Gemma are optional Chat profiles, never Core or MCP requirements.
+
+<!-- gitnexus:start -->
+# 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, which execution flows it participates in — 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
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/jcode-ragmir/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/jcode-ragmir/clusters` | All functional areas |
+| `gitnexus://repo/jcode-ragmir/processes` | All execution flows |
+| `gitnexus://repo/jcode-ragmir/process/{name}` | Step-by-step execution trace |
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

README.md

@@ -13,6 +13,10 @@ files you choose, stores the index inside the project, and returns source-backed
 CLI, TypeScript API, or local MCP server. The default path needs no account, hosted document store,
 or model download.
 
+Bring the AI or automation you already use. Ragmir Core does not call a model. If no retrieved
+passage may leave the machine, connect a local CLI or MCP consumer, or add Ragmir Chat for cited
+answer generation from a verified local model.
+
 [Website](https://ragmir.com) · [npm](https://www.npmjs.com/package/@jcode.labs/ragmir) ·
 [CLI reference](./docs/cli-reference.md) · [Examples](#runnable-examples)
 
@@ -41,8 +45,8 @@ Using npm instead of pnpm? Replace `pnpm add -D` with `npm install --save-dev` a
 | --- | --- | --- |
 | `rgr` CLI | Setup, ingest, search, audit, and maintenance | Human-readable or JSON output |
 | TypeScript API | Embed retrieval in a Node.js application | Typed results with citations |
-| Local MCP server | Give coding agents bounded project context | Read-focused retrieval tools |
-| Ragmir Chat | Generate an answer with a local GGUF model | Cited local synthesis |
+| Local MCP server | Give your preferred AI bounded project context | Read-focused retrieval tools |
+| Ragmir Chat | Keep answer generation on the workstation | Cited offline synthesis |
 | Ragmir TTS | Turn a text brief into audio | Local WAV or explicit online MP3 |
 
 Ragmir Core stays retrieval-first. `ask()` returns cited context without calling an LLM. Local chat
@@ -58,7 +62,7 @@ flowchart LR
     C --> D["Cited search results"]
     D --> E["CLI"]
     D --> F["TypeScript API"]
-    D --> G["MCP agents"]
+    D --> G["AI and automation over MCP"]
     D -. optional .-> H["Local GGUF chat"]
     B -. blank PDF pages .-> I["Configured local OCR"]
 ```
@@ -69,7 +73,7 @@ from the installed npm package.
 
 ## Common workflows
 
-### Give an agent cited project context
+### Connect the AI or automation you already use
 
 ```bash
 pnpm exec rgr setup --agents claude,codex,kimi,opencode,cline
@@ -82,6 +86,11 @@ Agents can request compact evidence first, then expand one returned citation
 without opening a second index or reading arbitrary files. MCP clients can read `ragmir://context`
 for a compact base, readiness, freshness, and capability overview before choosing a tool.
 
+Core is model-agnostic: any compatible CLI, TypeScript, or MCP consumer can use the returned
+citations. A hosted AI receives the passages you return to it under that provider's data policy. A
+local consumer keeps the handoff on the workstation, and the optional Chat package adds local
+answer generation when the whole workflow must remain offline.
+
 ### Route knowledge in a monorepo
 
 ```bash
@@ -176,9 +185,10 @@ Core also exports `previewChunks`, `ask`, `research`, `audit`, `doctor`, `securi
 | Capability | Default behavior | Network boundary |
 | --- | --- | --- |
 | Core retrieval | Local files, local index, `local-hash` retrieval | No network service required |
+| Preferred AI or automation | Receives only the passages the integration requests | The consumer's data policy applies; use a local consumer when passages must not leave |
 | Semantic embeddings | Disabled until explicitly enabled | Model download is explicit; inference can then stay local |
 | PDF and image OCR | Disabled until a local command is configured | No cloud OCR integration |
-| Ragmir Chat | Local inference from a verified GGUF file | Setup may download the selected model |
+| Ragmir Chat | Local inference from a verified GGUF profile | Setup may download the selected profile; answer generation then stays local |
 | Ragmir TTS | Local Transformers.js WAV rendering | Edge MP3 mode sends narration text when explicitly selected |
 
 Redaction reduces accidental exposure but is not a compliance certification. Review the
@@ -218,6 +228,8 @@ outside Git or under ignored local state.
 | --- | --- |
 | [CLI reference](./docs/cli-reference.md) | Commands, options, and JSON output |
 | [API reference](./docs/api-reference.md) | TypeScript exports and result shapes |
+| [Release history](https://github.com/jcode-works/jcode-ragmir/releases) | Generated notes, compatibility changes, and verification artifacts |
+| [Changelog](./CHANGELOG.md) | Semantic Versioning and API compatibility policy |
 | [Configuration](./docs/configuration.md) | Sources, privacy profiles, models, limits, and extractors |
 | [Agent integration](./docs/agent-integration.md) | Native helpers and MCP clients |
 | [Troubleshooting](./docs/troubleshooting.md) | Empty indexes, OCR, retrieval, or local-model problems |
@@ -236,7 +248,8 @@ pnpm example
 
 Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request. Report vulnerabilities
 through [SECURITY.md](./SECURITY.md), not a public issue. Release history is available in
-[CHANGELOG.md](./CHANGELOG.md).
+[GitHub Releases](https://github.com/jcode-works/jcode-ragmir/releases), with compatibility policy
+in [CHANGELOG.md](./CHANGELOG.md).
 
 ## License