@takara-ai/miru-code 1.6.0 → 1.7.2

package/README.md

@@ -57,6 +57,7 @@ Interactive TUI — **↑↓** move, **space** toggle, **a** all, **enter** conf
 | Cursor rules                  | Always-on `.cursor/rules/miru-code.mdc` (Cursor only)               |
 | Search hooks *(experimental)* | Block built-in Grep/Glob and redirect to Miru MCP                   |
 | Caveman *(experimental)*      | On-demand chat compression skill (`/caveman`)                       |
+| STE writing *(experimental)*  | On-demand clear technical English for docs (`/ste`)                 |
 
 
 Restart the IDE when done.
@@ -68,18 +69,19 @@ miru uninstall   # remove miru config
 **Supported:** Cursor · Claude Code · Gemini CLI · Kiro · OpenCode · GitHub Copilot · Codex · VS Code · Visual Studio (Windows) · Windsurf / Devin Desktop
 
 
-| IDE            | MCP                                   | Instructions / rules            | Hooks *(experimental)*                            | Caveman *(experimental)*              |
-| -------------- | ------------------------------------- | ------------------------------- | ------------------------------------------------- | ------------------------------------- |
-| Cursor         | `~/.cursor/mcp.json`                  | `~/.cursor/rules/miru-code.mdc` | `~/.cursor/hooks.json`                            | `~/.cursor/skills/caveman/SKILL.md`   |
-| Claude Code    | `~/.claude.json`                      | `~/.claude/CLAUDE.md`           | `~/.claude/settings.json`                         | `~/.claude/skills/caveman/SKILL.md`   |
-| Gemini CLI     | `~/.gemini/settings.json`             | `~/.gemini/GEMINI.md`           | `~/.gemini/settings.json` (`BeforeTool`)          | —                                     |
-| Kiro           | `~/.kiro/settings/mcp.json`           | `~/.kiro/steering/miru.md`      | `~/.kiro/settings/hooks.json`                     | —                                     |
-| OpenCode       | `~/.config/opencode/opencode.json(c)` | `~/.config/opencode/AGENTS.md`  | `~/.config/opencode/plugins/miru-search-guard.ts` | —                                     |
-| GitHub Copilot | `~/.copilot/mcp-config.json`          | —                               | `~/.copilot/hooks/miru-search.json`               | —                                     |
-| Codex          | `~/.codex/config.toml`                | `~/.codex/AGENTS.md`            | `~/.codex/hooks.json`                             | —                                     |
-| VS Code        | `…/Code/User/mcp.json`                | —                               | `~/.copilot/hooks/miru-search.json`               | —                                     |
-| Visual Studio  | `%USERPROFILE%\.mcp.json`             | —                               | `~/.copilot/hooks/miru-search.json`               | —                                     |
-| Windsurf       | —                                     | —                               | `~/.codeium/windsurf/hooks.json`                  | —                                     |
+| IDE            | MCP                                   | Instructions / rules            | Hooks *(experimental)*                            | Caveman *(experimental)*                            | STE *(experimental)*                         |
+| -------------- | ------------------------------------- | ------------------------------- | ------------------------------------------------- | --------------------------------------------------- | -------------------------------------------- |
+| Cursor         | `~/.cursor/mcp.json`                  | `~/.cursor/rules/miru-code.mdc` | `~/.cursor/hooks.json`                            | `~/.agents/skills/caveman/SKILL.md`                 | `~/.agents/skills/ste/SKILL.md`              |
+| Claude Code    | `~/.claude.json`                      | `~/.claude/CLAUDE.md`           | `~/.claude/settings.json`                         | `~/.claude/skills/caveman/SKILL.md`                 | `~/.claude/skills/ste/SKILL.md`              |
+| Gemini CLI     | `~/.gemini/settings.json`             | `~/.gemini/GEMINI.md`           | `~/.gemini/settings.json` (`BeforeTool`)          | `~/.agents/skills/caveman/SKILL.md`                 | `~/.agents/skills/ste/SKILL.md`              |
+| Kiro           | `~/.kiro/settings/mcp.json`           | `~/.kiro/steering/miru.md`      | `~/.kiro/settings/hooks.json`                     | `~/.kiro/skills/caveman/SKILL.md`                   | `~/.kiro/skills/ste/SKILL.md`                |
+| OpenCode       | `$XDG_CONFIG_HOME/opencode/opencode.json(c)` *(else `~/.config/opencode/…`)* | `…/AGENTS.md` | `…/plugins/miru-search-guard.ts` | `~/.agents/skills/caveman/SKILL.md` | `~/.agents/skills/ste/SKILL.md` |
+| GitHub Copilot | `~/.copilot/mcp-config.json`          | —                               | `~/.copilot/hooks/miru-search.json`               | `~/.agents/skills/caveman/SKILL.md`                 | `~/.agents/skills/ste/SKILL.md`              |
+| Codex          | `~/.codex/config.toml`                | `~/.codex/AGENTS.md`            | `~/.codex/hooks.json`                             | `~/.agents/skills/caveman/SKILL.md`                 | `~/.agents/skills/ste/SKILL.md`              |
+| VS Code        | `…/Code/User/mcp.json`                | —                               | `~/.copilot/hooks/miru-search.json`               | `~/.agents/skills/caveman/SKILL.md`                 | `~/.agents/skills/ste/SKILL.md`              |
+| Visual Studio  | `%USERPROFILE%\.mcp.json`             | —                               | `~/.copilot/hooks/miru-search.json`               | `~/.agents/skills/caveman/SKILL.md`                 | `~/.agents/skills/ste/SKILL.md`              |
+| Windsurf       | —                                     | —                               | `~/.codeium/windsurf/hooks.json`                  | `~/.agents/skills/caveman/SKILL.md`                 | `~/.agents/skills/ste/SKILL.md`              |
+
 
 ### Plugin packaging
 
@@ -97,7 +99,18 @@ Current limitation:
 
 ### Search hooks
 
-Sub-agent files are also written where supported (see `miru install` plan). Windsurf hooks only *(experimental)* — no MCP entry yet. Caveman is an on-demand Agent Skill (default off): invoke with `/caveman` or “talk like caveman”; stop with “normal mode”.
+Sub-agent files are also written where supported (see `miru install` plan). Windsurf hooks only *(experimental)* — no MCP entry yet. Caveman is an on-demand Agent Skill (default off): invoke with `/caveman` or “talk like caveman”; stop with “normal mode”. Invocation UI varies by IDE (`/caveman`, `$caveman`, `@caveman`, etc.). Most IDEs share `~/.agents/skills/caveman/SKILL.md` (including Copilot / VS Code / Visual Studio); Claude Code and Kiro keep vendor-native skill dirs. Ownership is tracked on the shared path so uninstalling one IDE keeps the skill while another still owns it; selecting all owners removes it once. STE is an on-demand Agent Skill (default off): invoke with `/ste` or “de-slop this”; keep articles and complete sentences. Most IDEs share `~/.agents/skills/ste/` the same way (ownership via `miru-owners.json`); Claude Code and Kiro keep vendor-native STE dirs.
+
+<details>
+<summary>STE writing <em>(experimental)</em></summary>
+
+STE helps write **clear technical English** for docs, runbooks, errors, and release notes (pragmatic ASD-STE100-inspired rules). Invoke with `/ste` or “de-slop this”. Keep articles and complete sentences — not telegraph-style omission.
+
+**Not ASD-certified.** Full dictionary compliance needs the official standard at [asd-ste100.org](https://www.asd-ste100.org). Miru does not ship the copyrighted ASD dictionary.
+
+Not for marketing or brand copy. Off by default; enable STE in the installer for any supported IDE. Restart the IDE (or reload skills) after install. For Codex, install also sets `[features] skills = true` in `~/.codex/config.toml` (same as Caveman).
+
+</details>
 
 <details>
 <summary>Caveman mode <em>(experimental)</em></summary>
@@ -106,7 +119,7 @@ Caveman compresses **live chat replies** (less filler, max meaning). Intensities
 
 Security / destructive warnings use clear normal prose (auto-clarity) — brevity never hides risk. Session token savings vary; the skill itself costs input tokens. No guaranteed %.
 
-Off by default at install time. Enable Caveman in the installer for Cursor and/or Claude Code.
+Off by default at install time. Enable Caveman in the installer for any supported IDE. Restart the IDE (or reload skills) after install. For Codex, the installer also sets `[features] skills = true` in `~/.codex/config.toml` (required for Codex to load skills).
 
 </details>
 
@@ -222,6 +235,8 @@ Set `MIRU_AST_CHUNKING=0` to disable AST and use structural → lines only.
 
 ## CLI reference
 
+Run `miru -h` for the command list, or `miru <command> -h` for details.
+
 | Command                                  | Purpose                                                                           |
 | ----------------------------------------- | --------------------------------------------------------------------------------- |
 | `miru setup`                             | Authenticate and store credentials                                                |
@@ -392,7 +407,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for pre-commit hooks, commit message conv
 
 Local MCP: `"command": "bun", "args": ["/path/to/miru-code/src/cli.ts"]`
 
-`miru help` / setup print a framed wordmark on color terminals (`MIRU_QUIET=1` for subtitle only). Crane art lives in `src/brand-banner.ts`; regenerate with `bun run scripts/render-crane-art.ts` (ImageMagick). The crane is a registered mark of Takara.ai Ltd.
+`miru -h` / setup print a framed wordmark on color terminals (`MIRU_QUIET=1` for subtitle only). Crane art lives in `src/brand-banner.ts`; regenerate with `bun run scripts/render-crane-art.ts` (ImageMagick). The crane is a registered mark of Takara.ai Ltd.
 
 ## Codex plugin in this repo
 
@@ -404,6 +419,15 @@ This repo includes a repo-local Codex plugin:
 
 The plugin intentionally launches the published package with `bunx @takara-ai/miru-code` instead of the checked-out source tree, so local source edits here do not affect the Codex plugin until a new package version is published.
 
+## Credits
+
+Miru uses work by [MinishLab](https://github.com/MinishLab). Thank you to its authors.
+
+- **[semble](https://github.com/MinishLab/semble)** (MIT). Miru ports parts of semble. These parts include the file walker, the index layout, the BM25 tokenizer, the hybrid search pipeline, and the ranking signals.
+- **[potion-code](https://huggingface.co/minishlab/potion-code-16M)** and **[Model2Vec](https://github.com/MinishLab/model2vec)** (MIT). The WordPiece tokenizer in `tokenizer/tokenizer.json` comes from potion-code.
+
+See [NOTICE](./NOTICE) for the licence text and the Model2Vec citation.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takara-ai/miru-code",
-  "version": "1.6.0",
+  "version": "1.7.2",
   "description": "Miru (見る) — hybrid code search for agents. Bun, TypeScript, Takara embeddings.",
   "type": "module",
   "license": "MIT",

package/src/auth/device.ts

@@ -1,4 +1,5 @@
 import { envFirstString } from "../env.ts";
+import { CredentialsError } from "./errors.ts";
 import type { StoredDeviceCodeCredentials } from "./types.ts";
 
 const DEFAULT_AUTH_BASE_URL = "https://auth.takara.ai";
@@ -239,7 +240,7 @@ export async function refreshDeviceAuthorization(
   options?: { config?: DeviceAuthConfig; fetchImpl?: typeof fetch },
 ): Promise<DeviceAuthorizationTokens> {
   if (!credentials.refresh_token?.trim()) {
-    throw new Error(
+    throw new CredentialsError(
       "Stored device credentials cannot be refreshed because no refresh token exists.",
     );
   }
@@ -256,12 +257,14 @@ export async function refreshDeviceAuthorization(
   const payload = text ? (JSON.parse(text) as OAuthTokenSuccess | OAuthTokenError) : {};
 
   if (!response.ok) {
-    throw new Error(`Device token refresh failed: ${parseTokenError(payload as OAuthTokenError)}`);
+    throw new CredentialsError(
+      `Device token refresh failed: ${parseTokenError(payload as OAuthTokenError)}`,
+    );
   }
 
   const success = payload as OAuthTokenSuccess;
   if (!success.access_token?.trim()) {
-    throw new Error("Token refresh succeeded but did not return an access token.");
+    throw new CredentialsError("Token refresh succeeded but did not return an access token.");
   }
 
   return normalizeTokenSuccess({
@@ -289,8 +292,13 @@ export function openBrowserForDeviceLogin(url: string): boolean {
         ? ["cmd", "/c", "start", "", url]
         : ["xdg-open", url];
   try {
-    const proc = Bun.spawn(command, { stdout: "ignore", stderr: "ignore" });
-    void proc.exited;
+    const proc = Bun.spawn(command, {
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    // Detach so the spinner's event loop / process lifecycle can't kill `open`.
+    proc.unref();
     return true;
   } catch {
     return false;

package/src/auth/errors.ts

@@ -0,0 +1,24 @@
+/**
+ * Signals that Miru has no usable credentials — missing, expired, or revoked.
+ * Callers that can recover (the MCP `auth` tool, `miru setup`) branch on this
+ * instead of matching error text.
+ */
+export class CredentialsError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "CredentialsError";
+  }
+}
+
+/** True when `error`, or anything in its `cause` chain, is a CredentialsError. */
+export function isCredentialsError(error: unknown): boolean {
+  let current: unknown = error;
+  // Bounded so a self-referencing cause chain cannot spin forever.
+  for (let depth = 0; depth < 10 && current instanceof Error; depth++) {
+    if (current instanceof CredentialsError) {
+      return true;
+    }
+    current = current.cause;
+  }
+  return false;
+}

package/src/auth/providers.ts

@@ -1,4 +1,4 @@
-import { hint, info, warn, writeStderr } from "../cli-ui.ts";
+import { dim, warn, writeStderr } from "../cli-ui.ts";
 import { validateEmbeddingApiKey } from "../embeddings/validate.ts";
 import { promptConfirm } from "../installer/prompt.ts";
 import { promptHidden } from "../prompt.ts";
@@ -35,16 +35,10 @@ async function resolveAuthMode(options: AuthenticateOptions): Promise<AuthMode>
   if (options.apiKey) {
     return "api_key";
   }
-  if (options.device) {
+  if (options.device || options.interactive) {
     return "device_code";
   }
-  if (!options.interactive) {
-    throw new Error("Choose an auth mode with `miru setup --device` or `miru setup --key TOKEN`.");
-  }
-  writeStderr("");
-  info("Choose how to authenticate.");
-  const useDevice = await promptConfirm("Use device code login?", true);
-  return useDevice ? "device_code" : "api_key";
+  throw new Error("Choose an auth mode with `miru setup --device` or `miru setup --key TOKEN`.");
 }
 
 async function authenticateWithApiKey(
@@ -67,24 +61,26 @@ async function authenticateWithApiKey(
 async function authenticateWithDeviceCode(
   options: AuthenticateOptions,
 ): Promise<AuthenticatedCredentials> {
-  const start = await startDeviceAuthorization();
-  const verificationUrl = start.verificationUriComplete ?? start.verificationUri;
   writeStderr("");
-  hint(`Visit ${verificationUrl}`);
-  if (!start.verificationUriComplete) {
-    hint(`Code: ${start.userCode}`);
-  }
-
-  const shouldOpenBrowser =
-    options.interactive &&
-    (process.env.MIRU_OPEN_BROWSER === undefined || process.env.MIRU_OPEN_BROWSER === "1");
-  if (shouldOpenBrowser) {
-    openBrowserForDeviceLogin(verificationUrl);
-  }
-
-  const spinner = new Spinner("Waiting for authentication");
+  const spinner = new Spinner("Authenticating");
   spinner.start();
   try {
+    const start = await startDeviceAuthorization();
+    const verificationUrl = start.verificationUriComplete ?? start.verificationUri;
+
+    const shouldOpenBrowser =
+      options.interactive &&
+      (process.env.MIRU_OPEN_BROWSER === undefined || process.env.MIRU_OPEN_BROWSER === "1");
+    if (shouldOpenBrowser) {
+      openBrowserForDeviceLogin(verificationUrl);
+    }
+
+    let visit = dim(`  Visit ${verificationUrl}`);
+    if (!start.verificationUriComplete) {
+      visit += `\n${dim(`  Code: ${start.userCode}`)}`;
+    }
+    spinner.follow(visit);
+
     const tokens = await pollDeviceAuthorization(start);
     spinner.succeed("");
     return {

package/src/cli.ts

@@ -21,8 +21,9 @@ import {
   AGENT_IDS,
   formatUnknownAgent,
   printCommandHelp,
-  printFullHelp,
+  printEnvironmentHelp,
   printMainHelp,
+  printSageMakerHelp,
 } from "./help.ts";
 import { getBenchmarkModeStatus, setBenchmarkMode } from "./installer/benchmark-mode.ts";
 import { runSearchGuardFromStdin } from "./installer/hooks/search-guard.ts";
@@ -81,6 +82,8 @@ const CLI_COMMANDS = new Set([
   "setup",
   "clear",
   "benchmark",
+  "env",
+  "environment",
   "hook-guard",
   "help",
   "-h",
@@ -415,7 +418,7 @@ async function runCli(argv: string[]): Promise<void> {
   }
 
   if (command === "-h" || command === "--help") {
-    printFullHelp();
+    printMainHelp();
     return;
   }
 
@@ -426,7 +429,7 @@ async function runCli(argv: string[]): Promise<void> {
 
   if (command === "help") {
     const topic = rest[0];
-    if (!topic) {
+    if (!topic || topic === "-h" || topic === "--help") {
       printMainHelp();
       return;
     }
@@ -434,6 +437,25 @@ async function runCli(argv: string[]): Promise<void> {
     return;
   }
 
+  if (command === "setup" && (rest.includes("-h") || rest.includes("--help"))) {
+    if (rest.includes("--sagemaker")) {
+      printSageMakerHelp();
+    } else {
+      printCommandHelp("setup");
+    }
+    return;
+  }
+
+  if (command === "env" || command === "environment") {
+    printEnvironmentHelp();
+    return;
+  }
+
+  if (rest[0] === "-h" || rest[0] === "--help") {
+    printCommandHelp(command);
+    return;
+  }
+
   if (command === "hook-guard") {
     process.exit(await runSearchGuardFromStdin());
   }

package/src/env.ts

@@ -1,3 +1,5 @@
+import { CredentialsError } from "./auth/errors.ts";
+
 export function envInt(name: string, fallback: number, min = 1): number {
   const raw = process.env[name];
   if (!raw) {
@@ -59,7 +61,7 @@ export function hasTakaraApiKeyInEnv(): boolean {
 export function resolveEmbeddingApiKey(): string {
   const key = process.env[TAKARA_API_KEY_ENV]?.trim() ?? "";
   if (!isUsableTakaraApiKey(key)) {
-    throw new Error(
+    throw new CredentialsError(
       "Takara credentials required. If you're an agent with Miru MCP tools available, call the " +
         "`auth` tool to sign in. Otherwise run `miru setup`, or set TAKARA_API_KEY in your MCP " +
         "server env or .env.local.",

package/src/help.ts

@@ -37,24 +37,23 @@ export function printMainHelp(): void {
   commandRow("locate", "Exact substring location in the index");
   commandRow("expand", "Adjacent chunks in the same file as a hit");
   commandRow("find-related", "Find chunks related to a file:line");
-  commandRow("setup", "Authenticate with Takara and save local credentials");
+  commandRow("setup", "Authenticate with Takara");
   commandRow("install", "Configure miru across coding agents");
   commandRow("uninstall", "Remove miru agent configuration");
   commandRow("benchmark", "Turn MCP benchmark mode on or off");
   commandRow("init", "Write a project-local sub-agent file");
   commandRow("clear", "Remove cached index for a path");
-  commandRow("help", "Show help for a command");
   divider();
 
   section("Quick start");
   writeStdout("  miru setup && miru install");
   writeStdout('  miru search "auth middleware" ./src');
   writeStdout("");
-  hint("miru help <command>  ·  miru -h for environment variables  ·  miru -v for version");
+  hint("miru <command> -h  ·  miru -v for version");
   writeStdout("");
 }
 
-export function printEnvHelp(): void {
+export function printEnvironmentHelp(): void {
   section("Environment");
   writeStdout(`  ${TAKARA_API_KEY_ENV}`);
   writeStdout("      Takara bearer token for embeddings");
@@ -67,6 +66,9 @@ export function printEnvHelp(): void {
   writeStdout("  MIRU_TOKENIZER_JSON");
   writeStdout("      Path to tokenizer.json (default: <package>/tokenizer/tokenizer.json)");
   writeStdout("");
+}
+
+export function printSageMakerHelp(): void {
   section("Self-hosted (AWS SageMaker)");
   writeStdout("  MIRU_SAGEMAKER_ENDPOINT_ARN");
   writeStdout("      arn:aws:sagemaker:<region>:<account-id>:endpoint/<name> — set this to");
@@ -90,13 +92,17 @@ export function printEnvHelp(): void {
   writeStdout("");
 }
 
-export function printFullHelp(): void {
-  printMainHelp();
-  printEnvHelp();
+export function printEnvHelp(): void {
+  printEnvironmentHelp();
+  printSageMakerHelp();
 }
 
 export function printCommandHelp(command: string): void {
   switch (command) {
+    case "env":
+    case "environment":
+      printEnvironmentHelp();
+      return;
     case "search":
       commandHeader("search", "Hybrid semantic + keyword search.");
       section("Usage");
@@ -172,17 +178,23 @@ export function printCommandHelp(command: string): void {
     case "install":
       commandHeader("install", "Interactive global agent setup.");
       writeStdout("Configures MCP server, instructions, sub-agent files, and optional");
-      writeStdout("experimental integrations (search hooks, Caveman skill) under");
+      writeStdout("experimental integrations (search hooks, Caveman, STE writing) under");
       writeStdout("your user config (~/.claude, ~/.cursor, etc.).");
       writeStdout("");
-      writeStdout("Caveman = on-demand chat compression (/caveman). Off by default.");
+      writeStdout(
+        "Caveman = chat compression (/caveman). STE = clear docs (/ste). Off by default.",
+      );
+      writeStdout("Caveman is supported on all Miru installer IDEs (shared path for most IDEs).");
+      writeStdout(
+        "STE is supported on all Miru installer IDEs (same shared-path ownership model).",
+      );
       writeStdout("Run miru setup first, or set TAKARA_API_KEY for MCP env expansion.");
       writeStdout("");
       return;
     case "uninstall":
       commandHeader("uninstall", "Remove miru configuration from agents.");
       writeStdout("Removes MCP entries, marked instruction blocks, global sub-agents,");
-      writeStdout("and selected optional integrations (hooks, Caveman skill).");
+      writeStdout("and selected optional integrations (hooks, Caveman, STE skills).");
       writeStdout("Also deletes the global benchmark report from Miru's state directory.");
       writeStdout("");
       return;