feat: release mise toolchain, MCP agent targets, and Context7/skills docs (#33)

* feat: generalize MCP agent targets and refresh app icon (#31)

* feat: refresh app icon to the Mimir monogram mark

Replace the placeholder favicon with the black/purple Mimir square
mark used across brand surfaces, in both the Tauri app and the
landing package.

* feat(core): support custom MCP agent targets in setup and install-skill

Generalize the previously hardcoded Claude/Codex/Kimi/OpenCode/Cline
MCP helper generation into a configurable agentHelpers list. Add
--agents, --mcp-name, --mcp-command, and --mcp-arg to `mimir setup`
and `mimir install-skill` so an arbitrary MCP-compatible agent can be
targeted without a source change.

* feat: pin Node toolchain with mise and add LLM/skills discovery docs (#32)

* feat: pin Node.js toolchain with mise

Replace the Node version hardcoded across CI workflows with a single
mise.toml pin, installed via jdx/mise-action in ci.yml and
native-app-build.yml. npm-publish.yml keeps actions/setup-node since
it also wires npm registry auth. pnpm stays pinned via Corepack's
packageManager field, not duplicated in mise.toml.

* docs: add llms.txt and context7.json for LLM-facing discovery

Prepare the repo to be indexed by Context7: llms.txt follows the
llmstxt.org convention and links the docs relevant to consuming Mimir
as a library/CLI/MCP server (excludes Tauri app, landing, and
licensing docs, which aren't part of that surface). context7.json
scopes the crawler away from generated/private directories and adds a
few correctness rules. Also documents the direct skills.sh install
path for the bundled mimir skill.

* fix(ci): install mise via curl instead of jdx/mise-action

jdx/mise-action is blocked by this repo's Actions permissions policy
(allowed_actions: selected, restricted to actions/*,
github/codeql-action/*, and verified creators), which caused a
startup_failure on every workflow run. Install mise with the official
curl script in a plain run: step instead, which isn't subject to the
uses: allowlist.

Author: jb-thery

.github/workflows/ci.yml

@@ -22,10 +22,14 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6
 
-      - name: Set up Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
+      - name: Install mise
+        run: |
+          curl https://mise.run | sh
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          echo "$HOME/.local/share/mise/shims" >> "$GITHUB_PATH"
+
+      - name: Install pinned Node via mise
+        run: mise install
 
       - name: Set up pnpm
         run: |
@@ -72,10 +76,14 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Set up Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
+      - name: Install mise
+        run: |
+          curl https://mise.run | sh
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          echo "$HOME/.local/share/mise/shims" >> "$GITHUB_PATH"
+
+      - name: Install pinned Node via mise
+        run: mise install
 
       - name: Set up pnpm
         run: |

.github/workflows/native-app-build.yml

@@ -35,10 +35,14 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf
 
-      - name: Set up Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
+      - name: Install mise
+        run: |
+          curl https://mise.run | sh
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          echo "$HOME/.local/share/mise/shims" >> "$GITHUB_PATH"
+
+      - name: Install pinned Node via mise
+        run: mise install
 
       - name: Set up pnpm
         run: |
@@ -78,10 +82,14 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6
 
-      - name: Set up Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
+      - name: Install mise
+        run: |
+          curl https://mise.run | sh
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          echo "$HOME/.local/share/mise/shims" >> "$GITHUB_PATH"
+
+      - name: Install pinned Node via mise
+        run: mise install
 
       - name: Set up pnpm
         run: |
@@ -121,10 +129,16 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6
 
-      - name: Set up Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
+      - name: Install mise
+        shell: bash
+        run: |
+          curl https://mise.run | sh
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          echo "$HOME/.local/share/mise/shims" >> "$GITHUB_PATH"
+
+      - name: Install pinned Node via mise
+        shell: bash
+        run: mise install
 
       - name: Set up pnpm
         shell: bash

AGENTS.md

@@ -49,6 +49,16 @@
   under real Mimir domains, private documents, generated `.pid` files, committed secrets, internal
   GTM/pricing ledgers, or wording that presents tracked MIT source as proprietary or closed source.
   `pnpm public:smoke` enforces the cheap checks.
+- Root `llms.txt` (the [llms.txt](https://llmstxt.org/) convention) and `context7.json` are the
+  LLM/Context7-facing doc index for this repository. Update `llms.txt` when adding or removing a
+  top-level `docs/*.md` file worth surfacing to agents, and keep `context7.json`'s
+  `excludeFolders`/`excludeFiles` in sync with new generated-output or private-data directories.
+  Registering the repo on context7.com (so it resolves through `resolve-library-id`) is a manual
+  step on their site; these files only prepare the repo for that step.
+- The bundled `mimir` skill is directly installable from this monorepo's nested path with the
+  [skills.sh](https://skills.sh) CLI (`npx skills add <repo-url>/tree/main/packages/mimir-core/skills/mimir`),
+  since that CLI supports a direct subdirectory path. If `packages/mimir-core/skills/` moves, update
+  the command documented in the README's "Agent Skills And MCP" section.
 - `packages/mimir-ui` is the shared UI/style foundation adapted from the WorkoutGen landing/UI
   approach. It provides the common Tailwind theme and React primitives for both the landing and the
   Tauri app; do not import WorkoutGen product copy, assets, analytics, or secrets.
@@ -144,6 +154,15 @@
   `KB_PDF_OCR_COMMAND` and `KB_IMAGE_OCR_COMMAND` remain legacy aliases only.
 - Keep the repository as a simple pnpm workspace monorepo. Add Turbo only if multiple packages or
   apps start needing task caching/orchestration beyond `pnpm --filter`.
+- The Node.js version is pinned once, in `mise.toml` (via [mise](https://mise.jdx.dev/)). Bump the
+  version there only, not as a hardcoded `node-version` in individual workflow steps. CI
+  (`ci.yml`, `native-app-build.yml`) installs mise with the official `curl https://mise.run | sh`
+  script in a plain `run:` step, not the `jdx/mise-action` marketplace action — this repo's Actions
+  permissions are restricted to `actions/*`, `github/codeql-action/*`, and verified creators, and
+  `jdx/mise-action` does not qualify. `npm-publish.yml` keeps `actions/setup-node` instead, because
+  that step also wires the npm registry `.npmrc` for publishing; keep its `node-version` in sync
+  with `mise.toml` by hand. pnpm stays pinned via Corepack through `packageManager` in
+  `package.json`, not duplicated in `mise.toml`.
 - Keep Mimir core free of Ollama. `embeddingProvider: "local-hash"` supports ingestion, search, MCP,
   and cited retrieval without a model server, but it must not be described as equivalent to semantic
   retrieval. `embeddingProvider: "transformers"` is the optional semantic embedding path.
@@ -233,10 +252,14 @@ General principles (KISS, DRY, YAGNI, SOLID) as applied in this codebase. Match
 - `packages/mimir-core/skills/mimir-audio-summary/SKILL.md` is the optional bundled audio-summary skill.
 - `packages/mimir-core/skills/mimir-markdown-report/SKILL.md` is the optional bundled Markdown-report
   skill.
-- `mimir setup` must keep generating agent-specific MCP helpers for easy local use:
+- `mimir setup` must keep generating agent-specific MCP helpers for easy local use by default:
   `.mimir/claude-mcp-server.json` for `claude mcp add-json`, `.mimir/codex-mcp.toml` for Codex
   config layers, `.mimir/kimi-mcp.json` for Kimi, `.mimir/opencode.jsonc` for OpenCode, and
-  `.mimir/cline-mcp.json` for Cline.
+  `.mimir/cline-mcp.json` for Cline. Keep `--agents` available on setup/install-skill so a target
+  repository can generate only the helpers it uses and remove stale unselected helpers.
+- Keep `--mcp-name`, `--mcp-command`, and repeatable `--mcp-arg` available on setup/install-skill
+  so repositories can generate MCP helper files for a stable server name or local wrapper script
+  without post-processing `.mimir/`.
 - `mimir install-agent` owns native skill discovery for the main supported coding agents. Keep
   `--agents claude|codex|kimi|opencode|cline` targeted so a user can install only the agent they use,
   with project scope by default and user scope available through `--scope user`.

CONTRIBUTING.md

@@ -4,13 +4,17 @@ Mimir is an open-source project under the MIT License. Issues and pull requests
 
 ## Development
 
-Use Node.js 20+ and pnpm:
+This repo pins its Node.js version with [mise](https://mise.jdx.dev/) (see `mise.toml`), the same
+version CI uses. Install mise, then:
 
 ```bash
+mise install
 pnpm install
 pnpm validate
 ```
 
+Without mise, any Node.js 20+ and pnpm install works too.
+
 `pnpm validate` runs Biome, a dependency security audit, TypeScript, Vitest, the production CLI/MCP
 smoke test, and npm package metadata checks.
 

README.md

@@ -269,6 +269,12 @@ Fresh setup keeps local state under one ignored `.mimir/` folder:
 
 It detects the repository package manager and writes the MCP helper files with the right command:
 `pnpm exec mimir serve-mcp`, `npx mimir serve-mcp`, `yarn exec mimir serve-mcp`, or `bunx mimir serve-mcp`.
+When a repository needs a wrapper script or only a subset of agent helpers, make that explicit during
+setup:
+
+```bash
+pnpm exec mimir setup --agents claude,codex --mcp-name project-docs --mcp-command ./scripts/serve-mcp.sh
+```
 
 For the usual agent-first workflow, expose Mimir to the coding assistants used in the repository:
 
@@ -467,9 +473,17 @@ Use `mimir setup` for the normal path, or install only the agent layer later:
 
 ```bash
 pnpm exec mimir install-skill
+pnpm exec mimir install-skill --agents claude,codex --mcp-command ./scripts/serve-mcp.sh
 pnpm exec mimir install-agent --agents claude,codex,kimi,opencode,cline
 ```
 
+The bundled skill is also directly installable from this repository with the
+[skills.sh](https://skills.sh) CLI, without adding Mimir as a dependency first:
+
+```bash
+npx skills add https://github.com/jcode-works/jcode-mimir/tree/main/packages/mimir-core/skills/mimir
+```
+
 Main agent examples:
 
 ```bash
@@ -905,6 +919,8 @@ pnpm --dir packages/mimir-core pack
   checkout, webhook, and local-license architecture for future commercial app distribution.
 - [`docs/ux-dx-audit.md`](./docs/ux-dx-audit.md): current UX/DX findings, fixes, and remaining
   product risks.
+- [`llms.txt`](./llms.txt): LLM-oriented index of this repository's documentation, following the
+  [llms.txt](https://llmstxt.org/) convention; consumed by tools like Context7.
 
 ## License
 

context7.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://context7.com/schema/context7.json",
+  "projectTitle": "Mimir",
+  "description": "Open-source, sovereign local RAG for confidential datasets and AI agents. TypeScript CLI, library, MCP server, and portable agent skills that index local files, store vectors with LanceDB, and return cited retrieval context.",
+  "excludeFolders": [
+    "node_modules",
+    "packages/mimir-core/dist",
+    "packages/mimir-tts/dist",
+    "packages/mimir-app/dist",
+    "packages/mimir-app/src-tauri/target",
+    "packages/mimir-app/src-tauri/gen",
+    "packages/mimir-landing/dist",
+    "packages/mimir-landing/.astro",
+    "packages/mimir-core/examples",
+    "release-artifacts",
+    "private",
+    ".mimir",
+    ".gitnexus",
+    ".git"
+  ],
+  "excludeFiles": ["CHANGELOG.md", "pnpm-lock.yaml"],
+  "rules": [
+    "Mimir Core returns cited retrieval context only; it does not synthesize answers itself.",
+    "The `local-hash` embedding provider (default) is a lexical sha256 embedding, not semantic; use `transformers` for semantic retrieval.",
+    "Switching `embeddingProvider` requires `mimir ingest --rebuild`, since the two providers produce incompatible vectors.",
+    "Run `mimir doctor --fix` after upgrading or misconfiguration to repair scaffolding, `.gitignore` entries, and the agent skill install.",
+    "Config resolves from the caller's working directory (`.mimir/config.json`), never from the package install path."
+  ]
+}

docs/agent-integration.md

@@ -8,6 +8,21 @@ If `mimir setup` was not used, install the agent kit into a repository:
 pnpm exec mimir install-skill
 ```
 
+By default this writes helper files for every supported agent. To keep a repository focused on only
+the agents it uses, pass a comma-separated target list:
+
+```bash
+pnpm exec mimir setup --agents claude,codex
+pnpm exec mimir install-skill --agents claude,codex
+```
+
+If an agent must launch Mimir through a repository wrapper, generate the MCP helpers with that
+command:
+
+```bash
+pnpm exec mimir setup --agents claude,codex --mcp-name project-docs --mcp-command ./scripts/serve-mcp.sh
+```
+
 This creates:
 
 ```plain text
@@ -25,6 +40,10 @@ This creates:
 .mimir/README.md
 ```
 
+When `--agents` is used, Mimir keeps `.mimir/mcp.json`, the skill folders, and the shared guides, but
+only writes the selected agent helper files. Previously generated unselected helper files are
+removed from `.mimir/`.
+
 Agents that support skill folders can load `.mimir/skills/mimir/` for deep local RAG usage. Load
 `.mimir/skills/mimir-audio-summary/` only when an optional spoken summary is needed. Load
 `.mimir/skills/mimir-markdown-report/` when the user asks for a cited Markdown report, dossier,
@@ -85,7 +104,7 @@ usage summaries and uses the returned citations.
 From the target repository root:
 
 ```bash
-pnpm exec mimir setup
+pnpm exec mimir setup --agents claude
 pnpm exec mimir install-agent --agents claude
 claude mcp add-json --scope local mimir "$(cat .mimir/claude-mcp-server.json)"
 ```
@@ -100,7 +119,7 @@ config.
 From the target repository root:
 
 ```bash
-pnpm exec mimir setup
+pnpm exec mimir setup --agents codex
 pnpm exec mimir install-agent --agents codex
 cat .mimir/codex-mcp.toml
 ```
@@ -114,7 +133,7 @@ skills.
 From the target repository root:
 
 ```bash
-pnpm exec mimir setup
+pnpm exec mimir setup --agents kimi
 pnpm exec mimir install-agent --agents kimi
 kimi --mcp-config-file .mimir/kimi-mcp.json
 ```
@@ -129,7 +148,7 @@ Kimi's global MCP file if you intentionally want a global setup. If you prefer n
 From the target repository root:
 
 ```bash
-pnpm exec mimir setup
+pnpm exec mimir setup --agents opencode
 pnpm exec mimir install-agent --agents opencode
 cat .mimir/opencode.jsonc
 ```
@@ -141,7 +160,7 @@ Copy or merge the generated snippet into the OpenCode config layer you use for t
 From the target repository root:
 
 ```bash
-pnpm exec mimir setup
+pnpm exec mimir setup --agents cline
 pnpm exec mimir install-agent --agents cline
 cat .mimir/cline-mcp.json
 ```

docs/api-reference.md

@@ -57,6 +57,18 @@ import { setupProject } from "@jcode.labs/mimir"
 const result = await setupProject({ cwd: "/path/to/workspace", ingest: true })
 ```
 
+Use `agents`, `mcpServerName`, `mcpCommand`, and `mcpArgs` when setup should generate only selected
+agent helpers or launch MCP through a repository wrapper:
+
+```ts
+await setupProject({
+  cwd: "/path/to/workspace",
+  agents: ["claude", "codex"],
+  mcpServerName: "project-docs",
+  mcpCommand: "./scripts/serve-mcp.sh",
+})
+```
+
 Useful result fields:
 
 | Field | Meaning |
@@ -294,6 +306,9 @@ import { installSkill } from "@jcode.labs/mimir"
 const result = await installSkill({ cwd: "/path/to/workspace" })
 ```
 
+Pass the same `agents`, `mcpServerName`, `mcpCommand`, and `mcpArgs` options to refresh a targeted
+agent kit without re-running full setup.
+
 The installed skills are:
 
 - `mimir`

docs/cli-reference.md

@@ -32,6 +32,7 @@ Mimir ships two CLIs:
 | Command | Use it when |
 | --- | --- |
 | `mimir install-skill` | Copy portable agent skills and an MCP config snippet into `.mimir/`. |
+| `mimir install-agent --agents <list>` | Expose Mimir skills in native Claude, Codex, Kimi, OpenCode, or Cline discovery folders. |
 | `mimir skill-path` | Print the package-bundled skill path for agents that load installed package skills. |
 | `mimir serve-mcp` | Start the MCP stdio server for compatible agents. |
 
@@ -58,6 +59,10 @@ Mimir ships two CLIs:
 | Option | Applies to | Meaning |
 | --- | --- | --- |
 | `--project-root <path>` | all project-scoped `mimir` commands | Run against a specific local workspace instead of the current directory. |
+| `--agents <list>` | `setup`, `install-skill`, `install-agent` | Select agent helpers or native skill folders: `all`, `claude`, `codex`, `kimi`, `opencode`, `cline`, or a comma-separated list. |
+| `--mcp-name <name>` | `setup`, `install-skill` | Set the MCP server name used in generated helper files. |
+| `--mcp-command <command>` | `setup`, `install-skill` | Use a repository wrapper or custom executable as the generated MCP stdio command. |
+| `--mcp-arg <arg>` | `setup`, `install-skill` | Add one argument to `--mcp-command`; repeat for multiple arguments. Use `--mcp-arg=--flag` for dash-prefixed values. |
 | `--top-k <number>` | `search`, `ask`, `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. |

llms.txt

@@ -0,0 +1,29 @@
+# Mimir
+
+> Open-source, sovereign local RAG for confidential datasets and AI agents: a TypeScript CLI,
+> library, MCP server, and portable agent skills that index local files, store vectors with
+> LanceDB, and return cited retrieval context to the calling coding agent.
+
+Mimir Core (`@jcode.labs/mimir`, npm) ingests local files from the target repository, redacts
+secrets and PII before anything is embedded, and serves cited passages through a CLI (`mimir ...`),
+an MCP server (`mimir serve-mcp`), a TypeScript library, and portable skills for Claude Code, Codex,
+Kimi Code CLI, OpenCode, and Cline. It does not perform LLM answer synthesis itself; `mimir ask`
+returns cited passages only, and synthesis stays with the calling agent or model. Mimir TTS
+(`@jcode.labs/mimir-tts`, npm) renders offline audio summaries.
+
+## Docs
+
+- [README](https://raw.githubusercontent.com/jcode-works/jcode-mimir/main/README.md): overview, install, quick start, developer use cases, full CLI walkthrough
+- [CLI reference](https://raw.githubusercontent.com/jcode-works/jcode-mimir/main/docs/cli-reference.md): every `mimir` command and flag
+- [API reference](https://raw.githubusercontent.com/jcode-works/jcode-mimir/main/docs/api-reference.md): library exports and MCP tools
+- [Agent integration](https://raw.githubusercontent.com/jcode-works/jcode-mimir/main/docs/agent-integration.md): wiring Mimir into Claude Code, Codex, Kimi Code CLI, OpenCode, Cline
+- [Troubleshooting](https://raw.githubusercontent.com/jcode-works/jcode-mimir/main/docs/troubleshooting.md)
+- [Contributing](https://raw.githubusercontent.com/jcode-works/jcode-mimir/main/CONTRIBUTING.md): dev setup (mise-pinned Node.js toolchain), pull request and Git Flow conventions
+
+## Optional
+
+- [Source boundary](https://raw.githubusercontent.com/jcode-works/jcode-mimir/main/docs/source-boundary.md): open-core split between Mimir Core and add-ons
+- [Offline TTS preload](https://raw.githubusercontent.com/jcode-works/jcode-mimir/main/docs/offline-tts-preload.md)
+- [FR/EU sovereign positioning](https://raw.githubusercontent.com/jcode-works/jcode-mimir/main/docs/fr-eu-sovereign-positioning.md)
+- [Security hardening](https://raw.githubusercontent.com/jcode-works/jcode-mimir/main/SECURITY-HARDENING.md)
+- [Security policy](https://raw.githubusercontent.com/jcode-works/jcode-mimir/main/SECURITY.md)