feat: release semantic-release workflow

Promote the validated release branch to main and trigger protected semantic-release publishing.

Author: jb-thery

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,6 +2,8 @@
 
 ## Validation
 
+- [ ] `pnpm validate`
+- [ ] `pnpm audit:security`
 - [ ] `pnpm check`
 - [ ] `pnpm test`
 - [ ] `pnpm build`

.github/workflows/ci.yml

@@ -4,7 +4,7 @@ on:
   pull_request:
     branches: [main, develop]
   push:
-    branches: [main, develop, "feature/**"]
+    branches: [main, develop, "feature/**", "release/**", "hotfix/**"]
   merge_group:
 
 permissions:
@@ -35,6 +35,9 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Security dependency audit
+        run: pnpm audit:security
+
       - name: Lint and format check
         run: pnpm lint
 

.github/workflows/codeql.yml

@@ -3,7 +3,7 @@ name: CodeQL
 on:
   pull_request:
   push:
-    branches: [main]
+    branches: [main, develop, "release/**", "hotfix/**"]
   schedule:
     - cron: "27 4 * * 1"
 

.github/workflows/npm-publish.yml

@@ -1,21 +1,23 @@
-name: Publish npm
+name: Release npm
 
 on:
+  push:
+    branches: [main]
   workflow_dispatch:
-    inputs:
-      version:
-        description: "Version already committed in package.json"
-        required: true
-        type: string
 
 permissions:
-  actions: read
-  contents: read
+  contents: write
+  issues: write
   id-token: write
+  pull-requests: write
+
+concurrency:
+  group: release-npm-${{ github.ref }}
+  cancel-in-progress: false
 
 jobs:
-  publish:
-    name: Publish to npm
+  release:
+    name: Semantic release
     runs-on: ubuntu-latest
     environment:
       name: npm-publish
@@ -24,15 +26,10 @@ jobs:
       - name: Verify main branch
         run: test "${GITHUB_REF}" = "refs/heads/main"
 
-      - name: Verify CI passed for this commit
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          conclusion="$(gh run list --repo jcode-works/jcode-mimir --workflow ci.yml --branch main --commit "$GITHUB_SHA" --json conclusion --jq '.[0].conclusion')"
-          test "$conclusion" = "success"
-
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
 
       - name: Set up Node
         uses: actions/setup-node@v4
@@ -45,50 +42,20 @@ jobs:
           corepack enable
           corepack prepare pnpm@11.9.0 --activate
 
-      - name: Verify version input
-        run: |
-          test "$(node -p "require('./packages/mimir-core/package.json').version")" = "${{ inputs.version }}"
-          test "$(node -p "require('./packages/mimir-tts/package.json').version")" = "${{ inputs.version }}"
-
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Lint and format check
-        run: pnpm lint
-
-      - name: Typecheck
-        run: pnpm check
-
-      - name: Test
-        run: pnpm test
-
-      - name: Build
-        run: pnpm build
-
-      - name: Smoke test production CLI and MCP
-        run: pnpm smoke
+      - name: Validate release gate
+        run: pnpm validate
 
-      - name: Verify generated dist is committed
-        run: git diff --exit-code -- packages/mimir-core/dist packages/mimir-tts/dist
-
-      - name: Verify npm package metadata
-        run: pnpm package:check
-
-      - name: Generate release verification artifacts
-        run: pnpm release:artifacts
+      - name: Semantic release
+        run: pnpm exec semantic-release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
       - name: Upload release verification artifacts
         uses: actions/upload-artifact@v4
         with:
-          name: mimir-release-${{ inputs.version }}
+          name: mimir-release-${{ github.sha }}
           path: release-artifacts/
-
-      - name: Publish Mimir TTS
-        run: pnpm --dir packages/mimir-tts publish --access public --provenance --no-git-checks
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Publish Mimir
-        run: pnpm --dir packages/mimir-core publish --access public --provenance --no-git-checks
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

AGENTS.md

@@ -151,11 +151,12 @@
   package/user testing only; never place real confidential documents there.
 - Use Context7 before changing dependencies or public APIs that rely on external libraries.
 - Run `pnpm validate` before opening a release pull request or publishing. It covers
-  Biome, TypeScript, Vitest, build output, production CLI/MCP smoke tests, and npm package
-  metadata.
+  Biome, dependency security audit, TypeScript, Vitest, build output, production CLI/MCP smoke
+  tests, npm package metadata, semantic-release wiring, and release artifacts.
 - Do not publish from a local machine or direct push to `main`. npm releases must go through
-  the protected manual `Publish npm` GitHub Actions workflow after `main` has green CI. The workflow
-  publishes `@jcode.labs/mimir-tts` first, then `@jcode.labs/mimir`.
+  the protected `Release npm` GitHub Actions workflow on `main`; semantic-release derives the
+  version from Conventional Commits, prepares both package tarballs, publishes
+  `@jcode.labs/mimir-tts` first, then publishes `@jcode.labs/mimir`.
 - Use Git Flow locally: `main` is production, `develop` is integration, feature work starts from
   `develop` under `feature/*`. Do not deploy or publish from feature branches.
 
@@ -201,8 +202,9 @@ General principles (KISS, DRY, YAGNI, SOLID) as applied in this codebase. Match
   local LanceDB table. Normal ingest is incremental and reuses rows whose checksum/provider/model
   still match; `--rebuild` forces a full re-index.
 - `packages/mimir-core/src/parsing.ts` uses proven parsers for high-risk Office formats:
-  Mammoth for `.docx` and SheetJS for `.xlsx`. Keep the lightweight XML ZIP parser for
-  `.pptx`, OpenDocument, and EPUB unless tests show fidelity gaps.
+  Mammoth for `.docx` and read-excel-file for `.xlsx`. Keep the lightweight XML ZIP parser for
+  `.pptx`, OpenDocument, and EPUB unless tests show fidelity gaps. Legacy `.xls` workbooks are not
+  supported by default; convert them to `.xlsx`, CSV, PDF, HTML, or text before ingesting.
 - `packages/mimir-core/src/query.ts` performs hybrid retrieval (vector candidates plus bounded lexical
   BM25 scoring) and returns cited retrieval context; LLM synthesis belongs outside Mimir core.
 - `packages/mimir-core/src/mcp.ts` exposes Mimir as an MCP stdio server for agents.
@@ -250,7 +252,7 @@ General principles (KISS, DRY, YAGNI, SOLID) as applied in this codebase. Match
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **jcode-mimir** (2537 symbols, 4246 relationships, 216 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **jcode-mimir** (2559 symbols, 4274 relationships, 218 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 

CLAUDE.md

@@ -18,7 +18,9 @@ pnpm lint:fix           # Biome auto-fix
 pnpm format             # Biome format --write
 pnpm test               # vitest run for packages/mimir-tts, then packages/mimir-core
 pnpm smoke              # build production CLI + MCP smoke test (scripts/smoke.mjs)
-pnpm validate           # full release gate: lint + check + test + build + smoke + package:check + release:artifacts
+pnpm audit:security     # dependency security audit at moderate severity and above
+pnpm release:semantic:smoke # checks semantic-release config and monorepo publish scripts without publishing
+pnpm validate           # full release gate: lint + audit + check + test + build + smoke + package:check + semantic release smoke + release:artifacts
 ```
 
 Run a single core test file: `pnpm --filter @jcode.labs/mimir exec vitest run src/config.test.ts`
@@ -118,13 +120,13 @@ Coding conventions (KISS, DRY, YAGNI, SOLID as applied here) live in `AGENTS.md`
   semicolons as-needed, trailing commas all.
 - Conventional Commits are enforced by commitlint in CI.
 
-Release policy (no local publish, no direct push to `main`, protected `Publish npm` workflow) lives
-in `AGENTS.md`. The workflow publishes `@jcode.labs/mimir-tts` before `@jcode.labs/mimir`.
+Release policy (no local publish, no direct push to `main`, protected semantic-release workflow)
+lives in `AGENTS.md`. The workflow publishes `@jcode.labs/mimir-tts` before `@jcode.labs/mimir`.
 
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **jcode-mimir** (2537 symbols, 4246 relationships, 216 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **jcode-mimir** (2559 symbols, 4274 relationships, 218 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 

CONTRIBUTING.md

@@ -11,17 +11,30 @@ pnpm install
 pnpm validate
 ```
 
-`pnpm validate` runs Biome, TypeScript, Vitest, the production CLI/MCP smoke test, and npm
-package metadata checks.
+`pnpm validate` runs Biome, a dependency security audit, TypeScript, Vitest, the production CLI/MCP
+smoke test, and npm package metadata checks.
+
+Run the security audit alone with:
+
+```bash
+pnpm audit:security
+```
 
 ## Pull Requests
 
-- Open pull requests against `main`.
+- Branch from `develop` for normal feature work, using `feature/<short-name>`.
+- Open feature pull requests against `develop`.
+- Use `release/<version-or-topic>` branches from `develop` when preparing a production release, then
+  open the release pull request against `main`.
+- Use `hotfix/<short-name>` branches from `main` for urgent production fixes, then back-merge the fix
+  into `develop`.
 - Keep changes focused and include tests or smoke coverage for behavior changes.
 - Do not commit private documents, generated vector stores, generated `.mimir/` state, environment
   files, tokens, credentials, customer ledgers, pricing tests, or interview notes.
 - Use conventional commit messages such as `feat: add source parser` or
   `fix: handle empty index`.
+- Non-release branches run CI only. npm publishing is restricted to the protected semantic-release
+  workflow from `main`; versions are derived from Conventional Commits, not manual package bumps.
 
 ## Security
 

README.md

@@ -32,6 +32,7 @@ spread across repositories, specifications, exports, and synced folders.
 | Work from a downloaded Google Drive folder | Point Mimir at files synced locally through Google Drive for desktop, then let the agent retrieve context without uploading the corpus to a hosted RAG service. |
 | Onboard to a legacy codebase | Ask where a flow is implemented, which modules own a responsibility, which docs explain a behavior, and what to read before changing risky code. |
 | Keep multiple agents on the same evidence | Install the same project skills and MCP server for Claude Code, Codex, Kimi Code CLI, OpenCode, and Cline so each tool retrieves from the same local index. |
+| Research before implementation | Run an audit-backed multi-query pass over specs, docs, and code references before asking an agent to plan a feature, migration, or review. |
 | Prepare implementation and review work | Generate cited task breakdowns, migration notes, release checklists, QA plans, and code-review context from the same local sources the team uses. |
 | Audit local knowledge coverage | Check which supported files were indexed, which formats were skipped, whether secrets are likely present, and whether golden queries still retrieve expected evidence. |
 
@@ -54,7 +55,7 @@ flowchart TD
 
   subgraph Mimir["Mimir Core"]
     Ingest["mimir ingest<br/>parse, redact, chunk"]
-    Retrieve["mimir search / ask<br/>rank cited passages"]
+    Retrieve["mimir search / ask / research<br/>rank cited evidence"]
     Audit["doctor, audit,<br/>security-audit, evaluate"]
   end
 
@@ -84,6 +85,7 @@ pnpm add -D @jcode.labs/mimir
 pnpm exec mimir setup
 pnpm exec mimir install-agent --agents claude,codex,kimi,opencode,cline
 pnpm exec mimir doctor --fix
+pnpm exec mimir research "release readiness and risks" --compact
 
 # Claude Code
 claude mcp add-json --scope local mimir "$(cat .mimir/claude-mcp-server.json)"
@@ -366,6 +368,12 @@ Return cited retrieval context for an agent or model:
 pnpm exec mimir ask "What evidence supports offline operation?"
 ```
 
+Run an audit-backed multi-query research pass before a broad synthesis or implementation task:
+
+```bash
+pnpm exec mimir research "release readiness and risks" --compact
+```
+
 Measure recall against a golden query file:
 
 ```bash
@@ -487,10 +495,11 @@ Start the MCP server from the repository root when a compatible agent needs tool
 pnpm exec mimir serve-mcp
 ```
 
-The MCP server exposes `mimir_status`, `mimir_search`, `mimir_ask`, `mimir_audit`,
-`mimir_evaluate`, `mimir_usage_report`, and `mimir_security_audit`. The LLM does not need to know
-about LanceDB or the raw file layout; it asks Mimir for ranked passages, cited context, local recall
-gates, or metadata-only usage summaries and uses the returned citations.
+The MCP server exposes `mimir_status`, `mimir_search`, `mimir_ask`, `mimir_research`,
+`mimir_audit`, `mimir_evaluate`, `mimir_usage_report`, and `mimir_security_audit`. The LLM does not
+need to know about LanceDB or the raw file layout; it asks Mimir for ranked passages, cited context,
+audit-backed research, local recall gates, or metadata-only usage summaries and uses the returned
+citations.
 
 Per-agent setup details live in [`docs/agent-integration.md`](./docs/agent-integration.md).
 
@@ -606,7 +615,8 @@ Mimir supports common text, document, data, config, log, and source-code files o
 - HTML: `.html`, `.htm`
 - EPUB: `.epub`
 - PDF: `.pdf`
-- Office/OpenDocument: `.docx`, `.pptx`, `.xls`, `.xlsx`, `.odt`, `.ods`, `.odp`
+- Office/OpenDocument: `.docx`, `.pptx`, `.xlsx`, `.odt`, `.ods`, `.odp`
+- Legacy Excel: convert `.xls` workbooks to `.xlsx`, CSV, PDF, HTML, or text before ingesting
 - Legacy Word: `.doc` only when an explicit local `legacyWordCommand` is configured
 - Rich text: `.rtf`
 - Notebook: `.ipynb`
@@ -740,10 +750,10 @@ Mimir ships two CLIs:
 - `mimir`: the main local RAG, MCP, skills, security, and audio command. `kb` remains a legacy alias for compatibility.
 - `mimir-tts`: the standalone text-to-speech renderer used by `mimir audio`.
 
-Most users start with `mimir setup`, `mimir doctor`, `mimir ingest`, `mimir search`, `mimir ask`, and
-`mimir security-audit`. Use `mimir models pull --enable` before semantic offline ingestion when
-remote model download is acceptable, and `mimir ingest --rebuild` after switching embedding provider
-or model.
+Most users start with `mimir setup`, `mimir doctor`, `mimir ingest`, `mimir search`, `mimir ask`,
+`mimir research`, and `mimir security-audit`. Use `mimir models pull --enable` before semantic
+offline ingestion when remote model download is acceptable, and `mimir ingest --rebuild` after
+switching embedding provider or model.
 
 The full command and option table lives in [`docs/cli-reference.md`](./docs/cli-reference.md).
 
@@ -788,7 +798,7 @@ core features:
 | LanceDB | Local vector storage and nearest-neighbor retrieval. |
 | MCP SDK | MCP server for compatible agents. |
 | fast-glob | Safe source-file discovery. |
-| unpdf, mammoth, xlsx, html-to-text, yaml, fflate | Document parsing for PDF, Office, HTML, YAML, OpenDocument, and EPUB files. |
+| unpdf, mammoth, read-excel-file, html-to-text, yaml, fflate | Document parsing for PDF, Office, HTML, YAML, OpenDocument, and EPUB files. |
 | commander, zod, picocolors | CLI, config validation, readable terminal output. |
 
 Removing more dependencies is possible only by dropping features or replacing them with smaller
@@ -851,8 +861,9 @@ pnpm validate
 CI checks that generated `dist/` files match the source.
 
 The root package is private and only orchestrates workspace tasks. npm publishing is handled by the
-protected `Publish npm` GitHub Actions workflow, which publishes `@jcode.labs/mimir-tts` before
-`@jcode.labs/mimir`.
+protected `Release npm` GitHub Actions workflow on `main`. semantic-release derives the version from
+Conventional Commits, prepares both package tarballs, publishes `@jcode.labs/mimir-tts` first, then
+publishes `@jcode.labs/mimir`.
 
 Build from source:
 

docs/agent-integration.md

@@ -69,15 +69,16 @@ MCP tools exposed:
 - `mimir_status`
 - `mimir_search`
 - `mimir_ask`
+- `mimir_research`
 - `mimir_audit`
 - `mimir_evaluate`
 - `mimir_usage_report`
 - `mimir_security_audit`
 
 This MCP layer is the recommended way to let any compatible LLM or agent query the same local
 knowledge base. The LLM does not need to know about LanceDB or the raw file layout; it asks Mimir for
-ranked passages, cited context, local recall gates, or metadata-only usage summaries and uses the
-returned citations.
+ranked passages, cited context, audit-backed research reports, local recall gates, or metadata-only
+usage summaries and uses the returned citations.
 
 ## Claude Code
 
@@ -156,9 +157,9 @@ when launching `mimir serve-mcp`.
 From a repository that already ran `mimir setup` and has Mimir wired into the current agent, ask:
 
 ```plain text
-Use Mimir to audit the local evidence. First run mimir_status and mimir_audit. Then search for
-"offline retrieval approval" and produce a cited Markdown report. Do not rely on memory if Mimir
-does not contain enough evidence.
+Use Mimir to audit the local evidence. First run mimir_status and mimir_audit. Then run
+mimir_research for "release readiness and risks" and produce a cited Markdown report. Do not rely on
+memory if Mimir does not contain enough evidence.
 ```
 
 Agents that support skill folders should also load: