Merge pull request #131 from jcode-works/release/v2.18.1-docs

fix(release): improve public documentation and release communication

Author: jb-thery

AGENTS.md

@@ -37,12 +37,22 @@
 - Package READMEs are brief npm entrypoints that link to the root README.
 - 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 a positive workflow: shared sources and configuration, one local ingest per
+  developer, then a corpus-fingerprint check. Keep low-level safeguards in the team and
+  configuration guides rather than turning team collaboration into the dominant public section.
 
 ## 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.
 
 ## Code conventions
 

CLAUDE.md

@@ -11,7 +11,7 @@ pnpm example
 
 Use `pnpm --filter @jcode.labs/ragmir <script>` for Core-only work. The pinned Node version lives in
 `mise.toml`; activate mise in your shell or run local workspace commands with that pinned version.
-Published packages retain their documented Node.js 20 compatibility.
+Published packages require Node.js 22 or later, matching their manifests and release gate.
 
 ## Workspace
 
@@ -26,6 +26,16 @@ commit them. The root README is the canonical documentation entrypoint; keep pac
 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 a positive workflow: shared sources and configuration, one local ingest per
+developer, then a corpus-fingerprint check. Keep low-level safeguards in focused guides.
+
+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 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.
 
 ## Boundaries
 

README.md

@@ -11,7 +11,7 @@ Do not publish from a local machine.
    release pull request into `main`.
 4. Let the `Release npm` workflow run on `main`, or dispatch it manually from `main`.
 5. Approve the protected `npm-publish` environment when GitHub asks for review.
-6. Verify all three npm packages, GitHub release notes, and release artifacts.
+6. Verify all three npm packages, the curated GitHub release notes, and release artifacts.
 7. Build and deploy the static landing through the external deployment process, then verify the
    published package version and canonical site URL.
 
@@ -25,6 +25,35 @@ does not deploy the site. The external deployment must build with the released v
 `PUBLIC_RAGMIR_VERSION`. Production must use `PUBLIC_RAGMIR_LANDING_URL=https://ragmir.com`; staging
 must use its own public URL so canonical and robots metadata cannot fall back to production.
 
+## Release Notes Contract
+
+The promotion commit on `main` is the public source for the GitHub release. Its body must contain
+these exact sections, each with at least one concise bullet:
+
+```text
+fix(release): improve public documentation and release communication
+
+Release highlights:
+- make Ragmir easier to understand and adopt without hiding its technical guarantees
+
+Release details:
+- **Documentation:** shorten every README and route advanced behavior to focused guides
+- **Landing:** present one clear hero statement and keep SEO/GEO metadata aligned
+- **Release automation:** publish curated notes with highlights, details, verification, and install links
+
+Verification:
+- pass pnpm validate and the Linux x64 and macOS ARM64 CI matrix
+- verify the English and French production pages in a browser
+```
+
+`scripts/semantic-release-notes.mjs` converts those sections into a GitHub release with highlights,
+grouped changes, verification evidence, install commands, package links, artifacts, and a full
+changelog link. Semantic release stops before publishing if a release commit omits the contract.
+
+Write the body from the complete `develop` to `main` delta. Mention user-visible outcomes and the
+substantial engineering work behind them, not file counts, implementation trivia, or a raw list of
+commit subjects. Keep each line within the repository's commitlint limit.
+
 ## Versioning Notes
 
 - `feat:` creates a minor release.

RELEASING.md

@@ -34,7 +34,7 @@
     "Run `rgr doctor --fix` after upgrading or misconfiguration to repair scaffolding, `.gitignore` entries, and the agent skill install.",
     "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.",
-    "Ragmir has no built-in cloud sync. Teams synchronize one source-of-truth folder with an existing tool, version stable directory or glob contracts instead of generated machine-specific file lists, align the Ragmir version, configuration, embedding provider, and model, then ingest and audit separate local indexes. Compare corpusFingerprint only when both indexes are ready with no missing or stale files; matching values identify the same indexed relative paths and source bytes. Use sourceFingerprintMode strict when a sync tool can preserve metadata while replacing content. Older manifests expose a null fingerprint until the next successful ingestion.",
+    "Teams synchronize one source-of-truth folder with Git, Drive, or their existing file workflow, commit stable source globs and Ragmir configuration, then ingest locally per developer. Align the Ragmir version and embedding settings; compare corpusFingerprint only after each index is ready with no missing or stale files. Use sourceFingerprintMode strict when synchronization can replace content without changing metadata, and 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.",

context7.json

@@ -1,11 +1,9 @@
 # Ragmir
 
-Ragmir is an open-source local-first retrieval toolkit for Node.js. It indexes files selected by the
-project, keeps generated state under ignored local `.ragmir/` folders, and returns source-backed
-passages through CLI, TypeScript, or a read-focused MCP server. It does not provide a hosted document
-store.
-
-Public subtagline: **Stop sending confidential documents directly to the cloud.**
+Ragmir is an open-source confidential local RAG for coding agents, scripts, and Node.js
+applications. It turns selected project files into cited evidence indexed and retrieved locally
+through CLI, TypeScript, or a read-focused MCP server. Core works offline by default, never uploads
+the corpus, and calls no model.
 
 ## Core facts
 
@@ -66,15 +64,13 @@ Public subtagline: **Stop sending confidential documents directly to the cloud.*
   vector, full-text, and relative-path index coverage.
 - Monorepos: the nearest configured base is active, nested indexes remain isolated, and generated MCP
   helpers pin a distinct base root.
-- Team use: Ragmir has no built-in cloud sync. Synchronize the same source-of-truth folder with an
-  existing tool such as Google Drive or a team script, align the version, configuration, embedding
-  provider, and model, then ingest and audit on each workstation. Missing, partial, or extra files
-  produce different local indexes. Version stable directory or glob contracts instead of generated
-  machine-specific file lists. Compare `corpusFingerprint` only when both indexes are ready with no
-  missing or stale files; matching values prove the same indexed relative paths and source bytes.
-  Use `sourceFingerprintMode: "strict"` when a sync tool can preserve metadata while replacing
-  content. Never treat `.ragmir/storage/` as a shared database. Older manifests expose a `null`
-  fingerprint until the next successful ingestion.
+- Team use: synchronize one source-of-truth folder with Git, Drive, or the team's existing file
+  workflow, commit stable source globs and Ragmir configuration, then ingest locally per developer.
+  Align the version and embedding settings, and compare `corpusFingerprint` only when each index is
+  ready with no missing or stale files. Matching values confirm the same relative paths and source
+  bytes. Use `sourceFingerprintMode: "strict"` when synchronization can preserve metadata while
+  replacing content, and keep actively written `.ragmir/storage/` directories local to each
+  workstation.
 - MCP resources: `ragmir://context` gives bounded readiness and capability context;
   `ragmir://sources` gives capped source detail with complete totals.
 - MCP safety: all ten tools advertise non-destructive behavior; every tool and resource JSON

llms.txt

@@ -5,20 +5,17 @@
 [![Node.js](https://img.shields.io/node/v/@jcode.labs/ragmir-chat)](https://www.npmjs.com/package/@jcode.labs/ragmir-chat)
 [![MIT](https://img.shields.io/npm/l/@jcode.labs/ragmir-chat)](https://github.com/jcode-works/jcode-ragmir/blob/main/LICENSE)
 
-Optional cited answer generation with a verified local GGUF model.
-
-*Stop sending confidential documents directly to the cloud.*
-
-Ragmir Chat accepts passages retrieved by Core, generates on the workstation, and validates the
-visible citation markers. It does not discover or index project files by itself.
+Optional cited answer generation with a verified local GGUF model. Ragmir Chat accepts passages
+retrieved by Core, generates on the workstation, and validates visible citation markers. It does
+not discover or index project files.
 
 [Project overview](https://github.com/jcode-works/jcode-ragmir#readme) ·
-[Offline chat guide](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/offline-chat-preload.md) ·
-[API reference](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/api-reference.md#chat-cited-local-generation)
+[Offline Chat guide](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/offline-chat-preload.md) ·
+[API](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/api-reference.md#chat-cited-local-generation)
 
-## Use Chat with Ragmir Core
+## Set up and answer
 
-Requires Node.js 20 or later and enough disk and memory for the selected model.
+Requires Node.js 22 or later and enough disk and memory for the selected model.
 
 ```bash
 npm install --save-dev @jcode.labs/ragmir @jcode.labs/ragmir-chat
@@ -29,19 +26,18 @@ npx rgr chat setup --profile fast
 npx rgr chat "What evidence supports this decision?" --profile fast --offline
 ```
 
-`rgr chat setup` downloads and verifies one model under `.ragmir/models/chat/<profile>`. Normal
-generation uses that local file and rejects remote model resolution.
+Setup downloads and verifies one model under `.ragmir/models/chat/<profile>`. Normal generation
+uses that local file and rejects remote model resolution.
 
-| Profile | Pinned model | Download | Thinking | Choose it when |
-| --- | --- | --- | --- | --- |
-| `lite` | Qwen2.5 0.5B Q4_K_M | ~0.49 GB | Off | Memory and startup time matter most |
-| `fast` | Gemma 4 E2B Q4_0 | ~3.35 GB | Standard or deep | You want the balanced default |
-| `quality` | Gemma 4 E4B Q4_0 | ~5.15 GB | Standard or deep | You accept a larger model for stronger answers |
+| Profile | Pinned model | Download | Choose it when |
+| --- | --- | --- | --- |
+| `lite` | Qwen2.5 0.5B Q4_K_M | about 0.49 GB | Memory and startup matter most; thinking stays off |
+| `fast` | Gemma 4 E2B Q4_0 | about 3.35 GB | You want the balanced default |
+| `quality` | Gemma 4 E4B Q4_0 | about 5.15 GB | You accept a larger model for stronger answers |
 
-Use the same profile for `setup`, `doctor`, and each answer. The `fast` profile is the default;
-`lite` always disables thinking. These are Chat profiles, not requirements of Ragmir Core, the CLI,
-API, or MCP server. Verify a prepared profile with
-`npx rgr chat doctor --profile fast --verify` before offline use.
+Use the same profile for setup, doctor, and generation. These are Chat profiles, not requirements
+of Ragmir Core, its CLI, API, or MCP server. Verify offline readiness with
+`npx rgr chat doctor --profile fast --verify`.
 
 ## TypeScript API
 
@@ -65,23 +61,14 @@ const result = await generateChatAnswer({
 console.log(result.answer, result.citationStatus)
 ```
 
-If no usable source is supplied, the package returns an insufficient-context result without loading
-a model. The result reports citation validity and model metadata; raw model thought is never
-returned or persisted. Model output still needs human review for high-impact decisions.
-
-Applications with their own retrieval layer can use `rgr-chat answer --context <file>`. The
-standalone `rgr-chat serve` command exposes a local line-delimited JSON process, not an HTTP server.
-
-## Privacy boundary
-
-Normal generation sends retrieved passages only to the local model process. The explicit setup step
-may download public model weights, never project documents. Keep model state and generated output
-under ignored `.ragmir/` paths. A hosted agent that displays or consumes the answer remains subject
-to that provider's data policy.
+No usable source returns an insufficient-context result without loading a model. Results include
+citation validity and model metadata; raw model thought is never returned or persisted. Human
+review remains necessary for high-impact decisions. Applications with another retrieval layer can
+use `rgr-chat answer --context <file>`; `rgr-chat serve` is a local line-delimited JSON process, not
+an HTTP server.
 
-Read the [project documentation](https://github.com/jcode-works/jcode-ragmir/wiki) and
-[troubleshooting guide](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/troubleshooting.md)
-for the complete workflow.
+Model setup may download public weights, never project documents. Normal generation sends retrieved
+passages only to the local model process. Keep models and outputs under ignored `.ragmir/` paths.
 
 Ragmir Chat is open source under the [MIT License](https://github.com/jcode-works/jcode-ragmir/blob/main/LICENSE).
-Selected GGUF models carry their own pinned license metadata.
+Selected GGUF models keep their own pinned license metadata.