Merge pull request #70 from jcode-works/develop

release: promote commercial desktop app and multilingual TTS

Author: jb-thery

.github/workflows/dependabot-auto-merge.yml

@@ -5,12 +5,7 @@ on:
     branches: [main]
   workflow_dispatch:
 
-permissions:
-  actions: write
-  contents: write
-  issues: write
-  id-token: write
-  pull-requests: write
+permissions: {}
 
 concurrency:
   group: release-npm-${{ github.ref }}
@@ -20,6 +15,11 @@ jobs:
   release:
     name: Semantic release
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      id-token: write
+      pull-requests: write
     environment:
       name: npm-publish
       url: https://www.npmjs.com/package/@jcode.labs/ragmir
@@ -74,6 +74,9 @@ jobs:
     runs-on: ubuntu-latest
     needs: release
     if: needs.release.outputs.version != ''
+    permissions:
+      actions: write
+      contents: read
     steps:
       - name: Trigger landing deploy with version
         uses: actions/github-script@v7

.github/workflows/npm-publish.yml

@@ -101,6 +101,16 @@
 - `packages/ragmir-app` is the cross-platform Tauri desktop/mobile shell. Root `pnpm build` validates
   the frontend bundle only; native `tauri build`, `tauri ios *`, and `tauri android *` commands stay
   explicit and are not part of npm release validation.
+- Desktop app config editing should use structured shadcn-style controls from
+  `@jcode.labs/ragmir-ui`. JSON remains the `.ragmir/config.json` file format, not the primary app
+  editing experience.
+- For Tauri app file and folder pickers triggered from the UI, prefer the official
+  `@tauri-apps/plugin-dialog` JavaScript `open(...)` API from the click handler. Do not add Rust
+  commands that call `blocking_*` dialog APIs for frontend-triggered picker flows; they can deadlock
+  the Tauri event loop and leave app loading state stuck. If a dedicated Rust picker command becomes
+  necessary, use the non-blocking `pick_*` callback APIs and validate the real `pnpm dev:app` flow by
+  clicking the control, opening the native picker, cancelling it, and confirming the loading state
+  clears.
 - Distribute the Ragmir app through direct downloads and sideloadable installers, not App Store or
   Play Store flows. Desktop installers and Android APK-style distribution are first-class; iOS stays
   deferred until a compliant non-store channel is chosen.
@@ -153,6 +163,28 @@
   Transformers.js text generation for `rgr chat`; `rgr chat setup` is the explicit one-command
   preload path for `.ragmir/models/chat`, and normal answers must keep remote model loading disabled
   unless the user opts into `--allow-remote-models`.
+- In `packages/ragmir-app`, keep model preloads explicit in the Tauri sidecar: setup/prepare flows
+  may pass `--allow-remote-models` only for one-time embedding/chat/TTS preload commands, while
+  normal chat answers and audio rendering must use offline/local modes after preload.
+- In `packages/ragmir-app`, chat UX must stay non-blocking: append the user message and a pending
+  assistant bubble before invoking native chat, show visible thinking/streaming/error states, render
+  assistant Markdown, keep recent thread context local and explicit, and run long native CLI work
+  through async Tauri commands or `spawn_blocking` so the webview does not freeze.
+- In `packages/ragmir-app`, distinguish Ragmir Chat from external coding agents. Local chat is the
+  only fully private in-app conversation path. Codex, Claude, Kimi, OpenCode, Cline, or generic MCP
+  modes should be presented as a handoff that generates/copies helper config and prompts for the
+  external agent; do not build a fake duplicate chat UI for agents that already have their own chat.
+  Always warn that prompts, retrieved snippets, and pasted confidential content may leave the
+  machine through cloud agents even though the Ragmir index and MCP server stay local.
+- In `packages/ragmir-app`, chat TTS belongs on assistant messages, not as a vague global export:
+  render the selected answer with `rgr audio --offline`, show per-message rendering/playing/error
+  states, read generated files through Tauri's scoped asset protocol, and keep TTS preload as an
+  explicit non-sensitive setup action.
+- In `packages/ragmir-app`, prepare direct-folder workspaces in bootstrap order: first write or
+  repair `.ragmir/config.json` with `sources: ["."]` and the safe `local-hash` provider, then run
+  `rgr models pull --enable`, then rebuild with Transformers. Do not set
+  `embeddingProvider: "transformers"` before the model preload exists, or `doctor --fix` can ingest
+  against a missing local model.
 - Keep report generation separate from core retrieval. The `ragmir-markdown-report` skill writes cited
   Markdown reports under ignored `.ragmir/reports/` by default and must distinguish evidence,
   inference, uncertainty, missing documents, and professional-review items.
@@ -237,6 +269,11 @@ any other), because several agents may run against this repo in parallel.
   protected-branch back-merge), name it clearly and delete it once merged.
 - **Respect other agents' work.** Before editing, run `git status` and check for other running agents
   or processes; never stage, commit, or discard uncommitted changes you did not make.
+- **Capture durable agent lessons in the repo.** When a bug, review, or user correction reveals a
+  repeatable AI-agent trap, update the nearest shared agent instructions in the same task:
+  `AGENTS.md` for cross-agent project rules, and `CLAUDE.md` only for Claude Code-specific behavior.
+  Keep the entry concise, factual, and tied to a reproducible workflow; do not rely on tool-local
+  memory as the only place for team-shared rules.
 
 ## Coding Conventions
 

AGENTS.md

@@ -21,7 +21,7 @@ Guardrails" in `AGENTS.md`.
 pnpm bootstrap          # mise install (pinned Node/Rust) && pnpm install
 pnpm build              # builds UI, app frontend, landing, TTS, chat, then Ragmir Core
 pnpm check              # typecheck UI/app/landing/TTS/chat/core
-pnpm dev:app            # run the Vite frontend for the Tauri shell
+pnpm dev:app            # run the Tauri desktop shell; requires Rust on PATH via mise
 pnpm dev:landing        # run the Astro landing locally
 pnpm example            # build core + run the library-API smoke against the local build (examples/library-api-demo)
 pnpm lint               # Biome CI (format + lint check, no writes)
@@ -41,6 +41,14 @@ Run only the chat package tests: `pnpm --filter @jcode.labs/ragmir-chat test`
 
 Tests are colocated as `packages/*/src/*.test.ts` and run on the TypeScript sources.
 
+## Claude memory and shared rules
+
+Claude Code has auto memory and `/memory`, but those notes are local to the machine and are not a
+replacement for committed project rules. When a user correction, review, or regression reveals a
+repeatable trap, add a concise shared rule to `AGENTS.md`; only add Claude-specific behavior here.
+Use `.claude/rules/` later only if the rule needs path-specific loading instead of every-session
+context.
+
 ## `dist/` is gitignored build output — critical
 
 All `packages/*/dist/` directories (`ragmir-core`, `ragmir-tts`, `ragmir-chat`, `ragmir-app`,
@@ -116,6 +124,18 @@ foundation, but with Ragmir tokens and no WorkoutGen product copy, analytics, CD
 Tauri v2 shell using the same UI package; root build validates its Vite frontend, while native Tauri
 desktop/mobile builds are explicit `pnpm --filter @jcode.labs/ragmir-app tauri:*` commands.
 
+Tauri dialog trap: for UI-triggered file/folder selection, use
+`@tauri-apps/plugin-dialog` `open(...)` from the frontend click handler. Do not add Rust commands
+that call `blocking_*` dialog APIs for these flows; they can deadlock the native event loop and leave
+React loading state stuck. Validate by running `mise exec rust -- pnpm dev:app`, clicking the picker
+button, cancelling the native dialog, and confirming the UI leaves its loading state.
+
+Tauri model-preload trap: when editing `packages/ragmir-app/src-tauri/src/lib.rs`, keep setup
+commands explicit about the network boundary. One-time model preloads may pass
+`--allow-remote-models`; normal chat/audio commands must stay offline after preload.
+For app `Prepare` flows, keep the bootstrap order from `AGENTS.md`: write direct-folder sources with
+`local-hash` first, preload semantic models second, then rebuild with Transformers.
+
 Key behaviors to keep in mind before editing:
 
 - **Config resolution is caller-relative.** `loadConfig` walks up from `cwd` looking for

CLAUDE.md

@@ -690,9 +690,11 @@ npx rgr-tts render /tmp/RAGMIR-SUMMARY-project.txt \
 ```
 
 The default standalone engine is `transformers` and the default language is `fr`. Pass
-`--lang en|es|fr` (or `RAGMIR_TTS_LANG`) to switch language: it selects the matching self-contained
-offline model (`Xenova/mms-tts-eng`, `Xenova/mms-tts-spa`, or `Xenova/mms-tts-fra`) and, on the Edge
-path, a native neural voice. Override the model directly with `--model` or `RAGMIR_TTS_MODEL`.
+`--lang en|es|fr|ja|th|zh` (or `RAGMIR_TTS_LANG`) to switch language. English, Spanish, and French
+select matching self-contained offline models (`Xenova/mms-tts-eng`, `Xenova/mms-tts-spa`, or
+`Xenova/mms-tts-fra`) and native Edge voices. Japanese, Thai, and Mandarin Chinese currently select
+native Edge voices; for offline rendering in those languages, pass a Transformers.js-compatible
+model directly with `--model` or `RAGMIR_TTS_MODEL`.
 
 See [`docs/offline-tts-preload.md`](./docs/offline-tts-preload.md) for the exact preload and
 offline-check workflow.

README.md

@@ -77,6 +77,7 @@ Useful result fields:
 | `ingested` | `IngestResult` when auto-ingest ran; otherwise `null`. |
 | `doctor` | Final readiness report. |
 | `nextSteps` | User-facing next actions. |
+| `configurationPrompt` | English copy-paste prompt for an AI assistant or local chat to tune repository-specific `sources` entries safely. |
 
 ### `loadConfig(start?)`
 

docs/api-reference.md

@@ -10,7 +10,7 @@ Ragmir ships three CLIs:
 
 | Command | Use it when |
 | --- | --- |
-| `rgr setup` | Initialize Ragmir, install the agent kit, run doctor, and ingest when safe. |
+| `rgr setup` | Initialize Ragmir, install the agent kit, run doctor, ingest when safe, and print a copyable AI prompt for source tuning. |
 | `rgr setup --semantic` | Run first setup and explicitly download the configured Transformers.js embedding model for higher-quality semantic retrieval. |
 | `rgr init` | Create `.ragmir/config.json` (with a `sources` array), `.ragmir/raw/`, and Git ignore rules. |
 | `rgr doctor` | Diagnose setup, index freshness, security warnings, and the next command to run. |
@@ -77,20 +77,24 @@ Ragmir ships three CLIs:
 | `--top-k <number>` | `search`, `ask`, `chat`, `research`, `evaluate` | Number of passages to return or keep. |
 | `--fail-under <recall>` | `evaluate` | Exit non-zero only when recall is below a threshold from `0` to `1`; without this option evaluation remains strict and fails on any miss. |
 | `--days <number>` | `usage-report` | Number of recent days to include in the metadata-only usage summary. |
-| `--json` | `doctor`, `ingest`, `search`, `ask`, `chat`, `research`, `route-prompt`, `evaluate`, `audit`, `usage-report`, `status`, `security-audit`, `audio --doctor`, `rgr-chat doctor`, `rgr-tts doctor` | Print machine-readable JSON. |
+| `--json` | `setup`, `doctor`, `ingest`, `search`, `ask`, `chat`, `research`, `route-prompt`, `evaluate`, `audit`, `usage-report`, `status`, `security-audit`, `audio --doctor`, `rgr-chat doctor`, `rgr-tts doctor` | Print machine-readable JSON. |
 | `--compact` | `search`, `research` | Return short snippets instead of full retrieved passages. |
 | `--no-code` | `research` | Skip the lightweight repository code scan. |
 | `--unsupported` | `audit` | List skipped file paths and reasons. |
 | `--strict` | `security-audit` | Exit non-zero when warnings exist. |
 | `--offline` | `chat`, `audio`, `rgr-chat answer`, `rgr-tts render` | Disable remote model downloads and force the local Transformers.js path. |
 | `--allow-remote-models` | `chat`, `audio`, `rgr-chat answer`, `rgr-tts render` | Explicitly allow model downloads for Transformers.js. |
 | `--engine edge` | `audio`, `rgr-tts render` | Use online Edge TTS for MP3 output. |
-| `--lang <en\|es\|fr>` | `audio`, `rgr-tts render` | Select the TTS language; picks the offline model and Edge voice. Default `fr`. |
+| `--lang <en\|es\|fr\|ja\|th\|zh>` | `audio`, `rgr-tts render` | Select the TTS language. `en`, `es`, and `fr` have default offline models; `ja`, `th`, and `zh` use Edge voices unless `--model` supplies a compatible offline model. Default `fr`. |
 
 See [`offline-chat-preload.md`](./offline-chat-preload.md) and
 [`offline-tts-preload.md`](./offline-tts-preload.md) before using `--offline` on a fully air-gapped
 machine.
 
+`rgr setup` ends with an English prompt between copy markers. Paste it into an AI assistant or local
+chat to ask for repository-specific `sources` recommendations while excluding secrets, generated
+files, dependency folders, caches, and unnecessary locale noise.
+
 ## External Text Extraction Configuration
 
 OCR and legacy binary extraction are intentionally configuration-based rather than default CLI flags.

docs/cli-reference.md

@@ -12,6 +12,8 @@ Use this workflow when you want confidential audio summaries to render without n
 - Render confidential narration only after the offline check succeeds.
 - Keep `.ragmir/models/tts/` and `.ragmir/audio/` untracked.
 - Do not use `--engine edge` for confidential content unless online TTS is explicitly acceptable.
+- Default offline models are configured for `en`, `es`, and `fr`. For `ja`, `th`, or `zh`, pass a
+  Transformers.js-compatible TTS model explicitly with `--model` before relying on offline rendering.
 
 The preload step downloads public model files. It should not need to send narration text to a remote
 TTS service, but using synthetic text keeps the operation easy to audit.

docs/offline-tts-preload.md

@@ -39,7 +39,7 @@
     "build": "pnpm --filter @jcode.labs/ragmir-ui build && pnpm --filter @jcode.labs/ragmir-app build && pnpm --filter @jcode.labs/ragmir-landing build && pnpm --filter @jcode.labs/ragmir-license-webhook build && pnpm --filter @jcode.labs/ragmir-tts build && pnpm --filter @jcode.labs/ragmir-chat build && pnpm --filter @jcode.labs/ragmir build",
     "check": "pnpm --filter @jcode.labs/ragmir-ui check && pnpm --filter @jcode.labs/ragmir-app check && pnpm --filter @jcode.labs/ragmir-landing check && pnpm --filter @jcode.labs/ragmir-license-webhook check && pnpm --filter @jcode.labs/ragmir-tts check && pnpm --filter @jcode.labs/ragmir-chat check && pnpm --filter @jcode.labs/ragmir check",
     "commitlint": "commitlint --from=HEAD~1 --to=HEAD --verbose",
-    "dev:app": "pnpm --filter @jcode.labs/ragmir-app dev",
+    "dev:app": "pnpm --filter @jcode.labs/ragmir-app tauri:dev",
     "dev:landing": "pnpm --filter @jcode.labs/ragmir-landing dev",
     "example": "pnpm --filter @jcode.labs/ragmir build && node packages/ragmir-core/examples/library-api-demo/run.mjs",
     "format": "biome format --write .",

package.json

@@ -8,7 +8,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json --noEmit && vite build",
     "check": "tsc -p tsconfig.json --noEmit",
-    "dev": "vite",
+    "dev": "tauri dev",
+    "dev:web": "vite",
     "license:from-lemonsqueezy": "node scripts/license-from-lemonsqueezy.mjs",
     "license:lemonsqueezy:smoke": "node scripts/license-from-lemonsqueezy-smoke.mjs",
     "license:issue": "node scripts/license-issue.mjs",
@@ -39,9 +40,11 @@
   "dependencies": {
     "@jcode.labs/ragmir-ui": "workspace:*",
     "@tauri-apps/api": "^2.10.0",
+    "@tauri-apps/plugin-dialog": "^2.7.1",
     "lucide-react": "^1.21.0",
     "react": "19.2.7",
-    "react-dom": "19.2.7"
+    "react-dom": "19.2.7",
+    "react-markdown": "^10.1.0"
   },
   "devDependencies": {
     "@tauri-apps/cli": "^2.10.0",