@takara-ai/miru-code 1.7.8 → 1.8.1

package/README.md

@@ -18,7 +18,27 @@ Miru returns the best **chunks** (path, lines, snippet) for questions like *"whe
 Miru replaces the grep/glob-style search agents fall back on today. Install once, and every connected agent gets `search` and `find_related` MCP tools automatically.
 
 
-## Install
+## Install via a plugin marketplace
+
+Prefer this when your IDE has a plugin marketplace — no `bun add -g` step, and updates go through the IDE's own plugin flow. Run `miru setup` first if you have not authenticated yet (see [Set up credentials](#set-up-credentials)).
+
+**Claude Code:**
+
+```
+/plugin marketplace add takara-ai/miru-code
+/plugin install miru
+```
+
+Restart Claude Code (or reload plugins) when prompted. Update: `/plugin marketplace update miru` then reinstall. Remove: `/plugin uninstall miru`.
+
+**Cursor:**
+
+1. Dashboard → Plugins → Team Marketplaces → **Add Marketplace** → Import from Repo → `takara-ai/miru-code`
+2. Customize (sidebar) → find `miru` → **Install** → choose project or user scope
+
+**Any other IDE, or if marketplace install isn't available:** use the CLI install below.
+
+## Install (CLI)
 
 ```bash
 bun add -g @takara-ai/miru-code
@@ -282,6 +302,7 @@ const results = await index.search({ query: "BM25 tokenize", topK: 10 });
 | `MIRU_MCP_WATCH`              | Set `0` to disable MCP file watch                                        |
 | `MIRU_AST_CHUNKING`           | Set `0` to disable tree-sitter AST chunking                              |
 | `MIRU_BENCHMARK_HISTORY_PATH` | Override; see [Benchmark mode](#benchmark-mode)                          |
+| `MIRU_CACHE_HOME`             | Override the platform cache root (see [How it works](#how-it-works))    |
 | `MIRU_QUIET`                  | Set `1` to skip the framed CLI banner (subtitle only on color terminals) |
 | `NO_COLOR`                    | Disable CLI colors                                                       |
 
@@ -409,16 +430,6 @@ Local MCP: `"command": "bun", "args": ["/path/to/miru-code/src/cli.ts"]`
 
 `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
-
-This repo includes a repo-local Codex plugin:
-
-- `.codex-plugin/plugin.json`
-- `.mcp.json`
-- `.agents/plugins/marketplace.json`
-
-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.

package/docs/kiro-transform-research-synopsis.md

@@ -0,0 +1,79 @@
+# Miru, Kiro, and AWS Transform - Research Synopsis
+
+**Prepared by:** Paul Melvin (with research assistance)
+**Purpose:** Summarize findings on how well Miru integrates with AWS Kiro, and the opportunity presented by AWS Transform, for internal sharing.
+
+---
+
+## TL;DR
+
+- **Miru already integrates cleanly with Kiro today** - verified directly against the current Miru source code and Kiro's own documentation. No work needed here.
+- **AWS Transform is AWS's agentic enterprise modernization platform** (mainframe, VMware, Windows/.NET migration), and it recently opened a real door for partners: the **AWS Transform Agent Builder Toolkit**, a Kiro Power that lets AWS partners build and register custom agents for discovery inside AWS Transform.
+- **This is a genuine opportunity, not just a compatibility check.** Takara is already an AWS AI Partner; AWS explicitly names Migration and Modernization Competency Partners as the audience for this toolkit. Modernization work - making sense of large, unfamiliar, undocumented legacy codebases - is close to the exact problem Miru is built to solve.
+- **The audience this reaches is disproportionately security-conscious** (regulated industries, legacy enterprise systems), which lines up well with Miru's self-hosted SageMaker embedding mode, already shipped, but currently under-promoted in Miru's own documentation.
+- Two companion documents exist alongside this one: a concept sketch of what a Miru-powered AWS Transform agent could look like, and a formal first-pass spec for pursuing it.
+
+---
+
+## What is Kiro?
+
+Kiro (kiro.dev) is AWS's own AI-powered IDE, built on a familiar VS Code-like editor experience, with native Model Context Protocol (MCP) support, spec-driven development workflows, "steering files" (plain-markdown behavior instructions), hooks, and subagents. It supports multiple sign-in options (GitHub, Google, AWS Builder ID, IAM Identity Center, external identity providers) and is available in AWS GovCloud regions for elevated-compliance workloads.
+
+**Kiro Powers** are AWS's curated marketplace of pre-packaged MCP servers, steering files, and hooks, validated by Kiro partners, installable in one click from inside Kiro or from a public marketplace page. Examples already live: an AWS Observability power (bundling CloudWatch, Application Signals, CloudTrail, and AWS Documentation MCP servers) and, most relevantly, the AWS Transform Agent Builder Toolkit power described below.
+
+## How does Miru integrate with Kiro today?
+
+Verified directly against Miru's current installer source code and cross-checked against Kiro's own current documentation - every integration point matches exactly:
+
+| Integration point | Path / mechanism |
+|---|---|
+| MCP server config | `~/.kiro/settings/mcp.json` (`mcpServers` key) |
+| Steering / instructions | `~/.kiro/steering/miru.md` |
+| Search-hook interception | `~/.kiro/settings/hooks.json` |
+| Subagent registration | `~/.kiro/agents/miru-code.md` |
+| Native skill directories (Caveman, STE) | Kiro-native paths - one of only two supported IDEs (with Claude Code) that get this treatment rather than the shared cross-agent skills path |
+
+This is a deeper integration than most of Miru's other supported IDEs receive. No changes are needed for Miru to work well inside plain Kiro today.
+
+## What is AWS Transform?
+
+AWS Transform is described by AWS as a collaborative enterprise IT transformation workbench, powered by expert agents, that accelerates cloud migration, application modernization, and continuous technical-debt reduction - covering scenarios like mainframe, VMware, and Windows/.NET modernization. It's accessible three ways, with consistent state across all of them: through a Kiro Power, through agent plugins for other IDEs (Claude, Cursor, Codex), and through a dedicated AWS Transform MCP server directly.
+
+Supporting infrastructure includes **AWS Transform Connectors** (secure cross-account access to source systems, with IAM role assumption, KMS encryption, and CloudTrail-audited access) and a **customer-owned AWS Transform Artifact Store** (the customer's own S3 bucket) - both signal that this product is built for security-conscious enterprise buyers.
+
+## The specific opportunity: Agent Builder Toolkit
+
+On May 14, 2026, AWS announced general availability of the **AWS Transform Agent Builder Toolkit** as a Kiro Power. This lets AWS partners and customers build agents tailored to their own modernization needs, share them across teams or partner networks, and **register them with AWS Transform for discovery** in the marketplace. AWS explicitly names Migration and Modernization Competency Partners, ISVs, and enterprise customers encoding their own standards as the intended users.
+
+This is the mechanism that makes "a Miru-powered modernization agent, discoverable by AWS Transform customers" a real, buildable thing - not a hypothetical integration.
+
+## Why this pairing makes sense
+
+Modernization programs are dominated by the cost of understanding legacy systems well enough to migrate them safely - exactly the problem semantic code search exists to help with, and arguably a more compelling, easier-to-demonstrate use case than Miru's general "saves tokens for a coding agent" pitch, which has recently come under credible external scrutiny over how that claim is measured (see the separate benchmark-methodology review). "Help an engineer understand an undocumented mainframe module in minutes" is a different, more visceral, and more defensible claim for this specific audience.
+
+## What to check before committing further
+
+- The exact partner validation process for getting an agent listed in the marketplace is not fully documented publicly - worth a direct conversation with AWS, likely through Takara's existing AWS AI Partner relationship.
+- The Agent Builder Toolkit reached general availability very recently (May 2026); its integration surface (whether agents can read AWS Transform Connectors directly, or contribute structured findings back to a job) should be confirmed hands-on rather than assumed from documentation alone.
+
+---
+
+## Sources
+
+- [Kiro official site](https://kiro.dev)
+- [AWS Transform official site](https://aws.amazon.com/transform/)
+- [Kiro MCP documentation (kiro.dev)](https://kiro.dev/docs/mcp/)
+- [AWS Transform introduces the Agent Builder Toolkit Kiro Power (AWS "What's New," May 14, 2026)](https://aws.amazon.com/about-aws/whats-new/2026/05/aws-transform-agent-builder-toolkit/)
+- [AWS Transform agents now available in Kiro, Claude, Cursor, and Codex (AWS "What's New," May 14, 2026)](https://aws.amazon.com/about-aws/whats-new/2026/04/aws-transform-developer-tools/)
+- [Simplify how you build and publish Custom Agents with AWS Transform Agent Builder Toolkit (AWS Migration & Modernization Blog)](https://aws.amazon.com/blogs/migration-and-modernization/simplify-how-you-build-and-publish-custom-agents-with-aws-transform-agent-builder-toolkit/)
+- [AWS Transform is now available in Kiro and VS Code (AWS "What's New," April 14, 2026)](https://aws.amazon.com/about-aws/whats-new/2026/04/aws-transform-kiro-vscode/)
+- [AWS Observability now available as a Kiro power (AWS "What's New," Feb 24, 2026) - example of an existing, comparable Kiro Power](https://aws.amazon.com/about-aws/whats-new/2026/02/aws-observability-kiro-power/)
+- [Kiro is now available in AWS GovCloud (US) Regions (AWS "What's New," Feb 16, 2026)](https://aws.amazon.com/about-aws/whats-new/2026/02/kiro-launch-aws-govcloud-us)
+- [Agentic Cloud Modernization: Accelerating Modernization with AWS MCPs and Kiro (AWS Migration & Modernization Blog)](https://aws.amazon.com/blogs/migration-and-modernization/agentic-cloud-modernization-accelerating-modernization-with-aws-mcps-and-kiro/)
+- [Getting Started with Kiro and MCP Servers (AWS re:Post)](https://repost.aws/articles/ARuX8rkojgSx-TYCc65JyAOw/getting-started-with-kiro-and-mcp-servers-connect-your-ai-ide-to-real-world-tools)
+- [The AWS MCP Server is now generally available (AWS Blog)](https://aws.amazon.com/blogs/aws/the-aws-mcp-server-is-now-generally-available/)
+- [Kiro Powers for autonomous AI agents on AWS (PwC)](https://www.pwc.com/us/en/technology/alliances/library/kiro-powers-autonomous-ai-agents-aws.html) - useful background on how Kiro Powers work architecturally
+
+---
+
+*Companion documents: `miru-aws-transform-concept.md` (concept sketch), `miru-aws-transform-kiro-power-spec.md` (first-pass formal spec).*

package/docs/miru-aws-transform-concept.md

@@ -0,0 +1,74 @@
+# Concept Sketch: Miru as an AWS Transform Modernization Agent
+
+**Status:** Concept only - not a spec, not a commitment. Companion to the formal spec (`miru-aws-transform-kiro-power-spec.md`) and the research synopsis (`kiro-transform-research-synopsis.md`).
+
+---
+
+## The idea, in one line
+
+Package Miru's existing search capability as a custom agent, built with AWS Transform's Agent Builder Toolkit, so that modernization teams working in AWS Transform get fast, semantic understanding of the legacy codebase they're migrating - without leaving the workflow they're already in.
+
+---
+
+## The problem this addresses
+
+AWS Transform's whole premise is compressing multi-year modernization programs (mainframe, VMware, Windows/.NET) into months. The single biggest hidden cost in any of those programs is almost never the migration mechanics - it's the weeks or months spent by engineers just figuring out what a legacy codebase actually does, because the people who wrote it are long gone and the documentation, if it exists, is wrong. That's precisely the problem Miru already exists to solve, just not currently pointed at this specific audience or workflow.
+
+---
+
+## How it would work
+
+At its simplest, this doesn't require building new search technology - it requires wrapping what Miru already does (`search`, `locate`, `expand`, `find_related`) behind an agent shaped for modernization-specific tasks, registered so AWS Transform users can discover and install it the same way they'd install any other Transform capability.
+
+```
+Modernization engineer, inside Kiro or the AWS Transform web console
+        |
+        v
+AWS Transform job (e.g. "assess this mainframe codebase for migration")
+        |
+        v
+Miru-powered agent, invoked as part of the assessment/planning phase
+        |
+        v
+Miru MCP tools search the actual legacy codebase
+   - "where is the batch settlement logic?"
+   - "find everything related to this COBOL copybook"
+   - "what calls this subroutine, and from where?"
+        |
+        v
+Findings feed back into AWS Transform's assessment output -
+dependency maps, complexity scoring, migration risk areas -
+grounded in what the code actually does, not just static analysis
+```
+
+The mechanics of *how* code gets indexed don't change from what Miru already does today. What changes is the framing: instead of "help me code," the agent's steering/instructions would be shaped around "help me understand and assess this system for migration," and it would be discoverable from inside the tool modernization teams are already using.
+
+---
+
+## A concrete example workflow
+
+1. A migration engineer opens an AWS Transform job for a legacy mainframe application.
+2. As part of the assessment phase, they (or an orchestrating Transform agent) invoke the Miru-powered agent against the source repository.
+3. The agent runs a structured pass - "map the major modules," "find all external interface points," "identify the most-referenced shared utilities" - using Miru's semantic search rather than keyword grep, which matters enormously in codebases full of cryptic mainframe naming conventions where keyword search alone is close to useless.
+4. Results (module map, dependency graph, complexity hotspots) get attached to the AWS Transform job as assessment artifacts, informing the migration plan AWS Transform produces.
+5. During the actual migration/rewrite phase, the same agent stays available for ad hoc questions - "what does this routine actually do before I port it?"
+
+---
+
+## Why this pairing makes sense beyond "it's technically possible"
+
+- **The audience is already exactly who Miru's self-hosted mode was built for.** Legacy mainframe and enterprise systems undergoing modernization are disproportionately regulated, sensitive, or simply not something a customer will agree to send to a third-party API. The self-hosted SageMaker embedding path (already shipped) isn't a nice-to-have here - it's plausibly the only mode a real customer in this segment accepts. This should be the default configuration offered for this specific distribution channel, not an opt-in footnote.
+- **It's a distribution channel Takara doesn't currently have.** Takara is already an AWS AI partner; AWS Transform's Agent Builder Toolkit explicitly names Migration and Modernization Competency Partners as its intended audience for custom agent building. This is a route to the modernization-buyer segment that doesn't exist today.
+- **It reframes Miru's pitch away from the exact thing that's been under scrutiny.** The recent external feedback on Miru's benchmark claims was about "how many tokens does this save a general coding agent" - a claim that needs a rebuilt, rigorous harness to defend (see the separate engineering priority list). "Can an engineer understand an undocumented mainframe module in minutes instead of days" is a different, arguably easier claim to demonstrate credibly, and one this audience cares about more than token counts.
+
+---
+
+## What this deliberately doesn't try to be
+
+- Not a new modernization product - Miru doesn't need to learn anything about COBOL, VMware, or .NET specifically. It's a general semantic search tool; the value here is applying it to a specific, high-value context, not rebuilding it.
+- Not a replacement for AWS Transform's own migration logic - this sits alongside AWS Transform's existing assessment/planning agents as a capability they can call on, not a competing workflow.
+- Not a decision to build yet - this is the concept the formal spec exists to pressure-test before any engineering time is committed.
+
+---
+
+*See `miru-aws-transform-kiro-power-spec.md` for the concrete requirements and open questions involved in actually building and registering this.*

package/docs/miru-aws-transform-kiro-power-spec.md

@@ -0,0 +1,98 @@
+# Miru as an AWS Transform Kiro Power - Specification
+
+**Status:** Draft for review - first pass, not yet discussed with stakeholders
+**Owner:** Paul Melvin
+**Component/Area:** Miru - AWS Transform / Kiro Power distribution
+**Related:** Concept sketch (`miru-aws-transform-concept.md`); research synopsis (`kiro-transform-research-synopsis.md`); DS1 self-hosted container licensing spec (the self-hosted SageMaker embedding path this spec leans on already exists as of Miru v1.5.0)
+**Template version:** Takara Feature Spec Template v1
+
+---
+
+## 1. Purpose
+
+Register a Miru-powered custom agent with AWS Transform's Agent Builder Toolkit, so that migration and modernization teams using AWS Transform (via Kiro, the web console, or programmatically) can discover and use Miru's semantic code search as part of their modernization workflow - reaching a customer segment Takara does not currently have a distribution channel into, via a partner program Takara is already part of (AWS AI Partner).
+
+This is a first-pass spec. Unlike the other specs in this set, this one has not yet been through a stakeholder Q&A round - several sections below flag assumptions rather than settled decisions, and §8 is longer than usual as a result.
+
+---
+
+## 2. Decisions already made - please don't reopen these
+
+- None yet locked. This spec has not been reviewed with stakeholders. Treat every substantive choice below as a proposal, not a decision, until reviewed.
+
+---
+
+## 3. Scope
+
+### In scope
+- Packaging Miru's existing MCP tools (`search`, `locate`, `expand`, `find_related`) behind a custom agent built with AWS Transform's Agent Builder Toolkit.
+- Modernization-specific steering/framing for that agent (assessment and dependency-mapping oriented instructions, distinct from Miru's general-purpose coding-assistant framing).
+- Registering the resulting agent for discovery within the AWS Transform / Kiro Power marketplace.
+- Defaulting this specific distribution channel to the self-hosted SageMaker embedding path (already shipped in Miru v1.5.0) rather than Takara-hosted DS1, given the sensitivity profile of this audience.
+
+### Out of scope (for this phase)
+- Any new modernization-specific intelligence (COBOL parsing, VMware-specific analysis, etc.) - this wraps Miru's existing general-purpose search, it does not extend it.
+- Deep integration with AWS Transform's own assessment/planning agent internals beyond what the Agent Builder Toolkit's standard integration surface provides.
+- Any change to Miru's core product for non-Transform users - this is a packaging and distribution exercise, not a product change.
+
+---
+
+## 4. Functional requirements
+
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| MAT-1 | The agent exposes Miru's existing `search`, `locate`, `expand`, and `find_related` MCP tools without modification to their underlying behaviour. | Required |
+| MAT-2 | The agent's steering/instructions are written for a modernization-assessment use case (e.g. "map dependencies," "identify high-risk or high-complexity modules," "find all callers of this routine") rather than Miru's default general-purpose coding-assistant framing. | Required |
+| MAT-3 | The agent's default, documented configuration for this distribution channel uses the self-hosted SageMaker embedding backend, not Takara-hosted DS1 - given the sensitivity profile of legacy/regulated systems typical of this audience. Takara-hosted mode remains available but is not the default presented in onboarding for this specific channel. | Required |
+| MAT-4 | The agent can be pointed at a codebase already connected to an AWS Transform job (via whatever mechanism AWS Transform Connectors expose) without requiring a separate, manual repository setup step, if the Agent Builder Toolkit's integration surface supports this. **Open question - see §8.** | Recommended |
+| MAT-5 | Findings produced during a Miru-assisted assessment (e.g. a dependency map or complexity summary) can be attached to or referenced from the AWS Transform job as an artifact, if the toolkit supports agents contributing structured output back to a job. **Open question - see §8.** | Recommended |
+
+---
+
+## 5. Dependent / external system requirements
+
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| MAT-E1 | The agent must be built using AWS Transform's Agent Builder Toolkit (GA as of May 2026), available via the Kiro power marketplace. | Required |
+| MAT-E2 | Registering the agent for discovery requires whatever validation AWS applies to Migration and Modernization Competency Partners submitting custom agents - exact process not yet confirmed directly with AWS (see §8). | Required |
+| MAT-E3 | The agent must be compatible with the AWS Transform MCP server's expected integration contract (human-in-the-loop forms, status updates, job orchestration) as documented by AWS at the time of building - not assumed stable from this spec's research alone, given how recently (May 2026) this toolkit reached GA. | Required |
+
+---
+
+## 6. Interface / data design
+
+| ID | Requirement | Priority |
+|----|-------------|----------|
+| MAT-C1 | Agent manifest/listing metadata (name, description, capability summary) should clearly state the self-hosted-by-default configuration and the audience it's built for, consistent with the "lead with the SageMaker path" positioning already recommended for Miru generally. | Required |
+| MAT-C2 | No new credential type is introduced by this work - the agent uses Miru's existing credential/auth mechanisms (Takara token or SageMaker AWS credentials, per MAT-3) unchanged. | Required |
+
+---
+
+## 7. Non-functional requirements
+
+- **Security and positioning:** given the likely sensitivity of codebases in modernization programs (mainframe, legacy enterprise systems, often regulated industries), this channel should be held to at least the same security-communication bar as the rest of Miru's self-hosted story - clear, upfront, not buried (the exact criticism raised in the recent external feedback about the SageMaker docs being under-surfaced in the main README applies with extra force to this specific, more security-conscious audience).
+- **Maintenance burden:** an AWS Transform-specific agent is another surface to keep in sync with Miru's core MCP tool behaviour as it evolves - worth a lightweight owner/process decision (§8) so it doesn't quietly drift out of date the way generic multi-IDE support can be harder to notice breaking.
+
+---
+
+## 8. Open questions for engineering (and partnerships)
+
+1. **Exact partner validation/registration process** - what AWS actually requires to get a custom agent listed and discoverable via the Kiro power marketplace for AWS Transform. Needs direct confirmation with AWS, likely through Takara's existing AWS AI Partner relationship, rather than inferred from public documentation.
+2. **Agent Builder Toolkit's actual integration surface** - whether it supports agents reading from AWS Transform Connectors directly (MAT-4) and contributing structured artifacts back to a job (MAT-5), or whether those are done through a more manual/separate mechanism. The toolkit reached GA very recently (May 2026); this spec's research reflects what's publicly documented, not hands-on testing.
+3. **Ownership** - who maintains this integration once built, and what triggers a review (a Miru MCP tool change, an AWS Transform toolkit change, or both).
+4. **Naming and branding** - what this agent is actually called in the marketplace, and whether it's positioned as "Miru for modernization" or under different branding suited to the AWS Transform audience.
+5. **Commercial model** - whether this is a free/promotional distribution channel to build awareness, or tied to Miru's existing or planned commercial terms. Not addressed in this spec; likely a commercial/product decision, consistent with how commercial questions have been scoped out of engineering specs elsewhere in this body of work.
+6. **Timing relative to the benchmark rework** - whether it's worth sequencing this after the benchmark methodology work already prioritized, so that any efficacy claims made to this new, more technically sophisticated audience are made on solid footing from the start, rather than risk repeating the credibility problem raised by the recent external review.
+
+---
+
+## 9. Suggested acceptance criteria
+
+- [ ] A working custom agent, built with the Agent Builder Toolkit, exposes Miru's four core search tools inside an AWS Transform context.
+- [ ] The agent's default onboarding path configures the self-hosted SageMaker embedding backend, not Takara-hosted DS1.
+- [ ] The agent is discoverable in the Kiro power marketplace under an AWS Transform-relevant listing.
+- [ ] A real modernization-style query (e.g. "map dependencies for this module") against a representative legacy codebase produces a materially more useful result than the equivalent AWS Transform workflow without Miru - this needs a concrete before/after example, not just a capability checklist, before this is presented externally.
+
+---
+
+*This is a first-pass spec, not yet reviewed. Every item in §8 should be resolved, and this document revised, before any implementation work begins.*

package/docs/self-hosted-sagemaker-identity-center.md

@@ -0,0 +1,109 @@
+# SageMaker access via IAM Identity Center
+
+Use this page if your users are managed in Entra ID, Okta or another IdP and federated into AWS through IAM Identity Center. It replaces the invoke-only IAM user step of the [self-hosted SageMaker guide](self-hosted-sagemaker.md) - no IAM users or static access keys are created.
+
+Prerequisite: the endpoint is deployed (step 1 of that guide) and you have its ARN.
+
+## How it fits together
+
+| Identity | Where it lives | What it does |
+| -------- | -------------- | ------------ |
+| SageMaker execution role | Endpoint account | Lets the SageMaker service pull the container and write logs. No people use it. Created in step 1. |
+| `MiruInvoke` permission set | Identity Center | Grants `sagemaker:InvokeEndpoint` on one endpoint and nothing else. Assigned to a group. |
+| Developer | Your IdP | Logs in with `aws sso login`, receives short-lived credentials for `MiruInvoke`, runs Miru. |
+
+Joiner/leaver, MFA and Conditional Access stay in your IdP. Miru just uses the resulting session.
+
+## Platform team: one-time setup
+
+Work in the Identity Center region (it lives in exactly one region; the endpoint region does not need to match).
+
+**1. Create a permission set.** Identity Center → Permission sets → Create → Custom. Name it `MiruInvoke`, attach no managed policies, and set this inline policy:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": "sagemaker:InvokeEndpoint",
+      "Resource": "arn:aws:sagemaker:<region>:<account-id>:endpoint/<name>"
+    }
+  ]
+}
+```
+
+Session duration is your call; 1 hour is a reasonable default. The endpoint name in the policy must match the deployed endpoint exactly - a mismatch produces an AccessDenied that looks like an SSO problem.
+
+**2. Assign it.** Identity Center → AWS accounts → the account holding the endpoint → Assign users or groups → your developer group (e.g. `miru-users`) → `MiruInvoke` → Submit.
+
+**3. Check provisioning.** On the permission set's "AWS accounts" tab the endpoint account should show as provisioned / up to date. "Not provisioned" means the assignment was not applied - select the account there and choose Provision, or run:
+
+```bash
+aws sso-admin provision-permission-set \
+  --instance-arn <instance-arn> \
+  --permission-set-arn <permission-set-arn> \
+  --target-type AWS_ACCOUNT --target-id <account-id>
+```
+
+Provisioning creates a role named `AWSReservedSSO_MiruInvoke_<hash>` in the endpoint account. That role is what developers assume.
+
+### Or: deploy it with CloudFormation
+
+[`examples/sagemaker-marketplace/cloudformation/miru-identity-center.yml`](../examples/sagemaker-marketplace/cloudformation/miru-identity-center.yml) creates the permission set, the inline policy and the group assignment in one stack, and provisions the account as part of creation. Deploy it in the management (or delegated Identity Center admin) account, in the Identity Center region:
+
+```bash
+aws cloudformation deploy \
+  --region <identity-center-region> \
+  --stack-name miru-identity-center \
+  --template-file examples/sagemaker-marketplace/cloudformation/miru-identity-center.yml \
+  --parameter-overrides \
+    InstanceArn=arn:aws:sso:::instance/ssoins-xxxx \
+    GroupId=<group-id> \
+    EndpointAccountId=<account-id> \
+    EndpointArn=arn:aws:sagemaker:<region>:<account-id>:endpoint/<name>
+```
+
+The group must already exist in Identity Center (for federated setups, the group synced from your IdP). Deleting the stack removes the assignment and the permission set.
+
+## Developers: per-machine setup
+
+Requires the AWS CLI v2 and Miru 1.5.0 or later.
+
+```bash
+# Install or update Miru
+bun add -g @takara-ai/miru-code
+miru --version
+
+# Create an SSO profile. Choose the endpoint account and the MiruInvoke role.
+aws configure sso --profile miru
+
+# Log in as yourself when the browser opens.
+aws sso login --profile miru
+
+# Confirm you are the SSO role in the right account
+aws sts get-caller-identity --profile miru
+
+# Point Miru at the endpoint
+miru setup --sagemaker --arn <endpoint-arn> --profile miru
+```
+
+`aws configure sso` writes an `sso-session` block and a `[profile miru]` block to `~/.aws/config`. No long-lived access keys are stored; the AWS CLI caches short-lived SSO tokens locally.
+
+If the account does not appear in the picker, either you logged in as a user without the assignment, or the login pre-dates provisioning. Run `aws sso logout`, then `aws configure sso --profile miru` and `aws sso login --profile miru` again.
+
+## When the session expires
+
+Miru resolves credentials through the standard AWS SDK chain, so it behaves like the AWS CLI:
+
+- While the SSO session is valid, role credentials refresh automatically.
+- Once it expires, searches fail until you run `aws sso login --profile miru`. Nothing needs reconfiguring.
+- An MCP server (Claude Code, Cursor) that started while the session was expired needs a restart after logging in - in Claude Code, `/mcp` then reconnect.
+
+## CI and other non-interactive use
+
+Do not create an IAM user for CI. Use an IAM role in the endpoint account with the same `sagemaker:InvokeEndpoint` policy, trusted by your CI provider's OIDC identity (GitHub Actions, GitLab, etc.), and give Miru that profile via `AWS_PROFILE` or the environment variables in the main guide.
+
+## Keeping client traffic private
+
+Callers reach the endpoint through the SageMaker Runtime API. If developer or CI traffic must stay off the public internet, add a `sagemaker.runtime` interface endpoint in the VPC they connect through. Miru needs no changes; the SDK picks it up via DNS.

package/docs/self-hosted-sagemaker.md

@@ -1,6 +1,6 @@
 # Self-hosted embeddings (AWS SageMaker)
 
-Run Miru against your own SageMaker embedding endpoint instead of Takara’s hosted API (`infer.takara.ai`).
+Run Miru against your own SageMaker embedding endpoint instead of Takara's hosted API (`infer.takara.ai`).
 
 The embedding model is sold on AWS Marketplace:
 
@@ -8,15 +8,14 @@ The embedding model is sold on AWS Marketplace:
 
 ## Overview
 
+| Step | Who       | What                                                                          |
+| ---- | --------- | ------------------------------------------------------------------------------ |
+| 1    | AWS admin | Subscribe on Marketplace                                                       |
+| 2    | AWS admin | Deploy the endpoint with the CloudFormation/CDK template (below)               |
+| 3    | AWS admin | Create an invoke-only IAM user / profile or IAM Identity Center permission set |
+| 4    | Developer | `miru setup --sagemaker` — Miru validates and saves the endpoint               |
 
-| Step | Who       | What                                                             |
-| ---- | --------- | ---------------------------------------------------------------- |
-| 1    | AWS admin | Subscribe on Marketplace and deploy a SageMaker endpoint         |
-| 2    | AWS admin | Create an invoke-only IAM user / profile (runbook below)         |
-| 3    | Developer | `miru setup --sagemaker` — Miru validates and saves the endpoint |
-
-
-Miru **never** creates IAM users or writes `~/.aws`. It only inherits a profile you already have and checks that it can call the endpoint.
+Miru **never** creates IAM users, IAM roles, SageMaker resources, or writes `~/.aws`. It only inherits a profile you already have and checks that it can call the endpoint.
 
 ## One mode at a time
 
@@ -27,23 +26,109 @@ Miru stores **either** a Takara API key **or** a SageMaker endpoint — never bo
 
 You do not need `--clear` when switching; the other mode is purged automatically.
 
-## 1. Deploy the Marketplace endpoint
+## 1. Subscribe on AWS Marketplace
 
 1. Open the [Marketplace listing](https://aws.amazon.com/marketplace/pp/prodview-la5olwsicr6ue)
-2. Subscribe and deploy the model package as a SageMaker endpoint in your account
-3. Copy the endpoint ARN — it looks like:
+2. Subscribe to the DS1 model package for your region
+3. Copy the **model package ARN** for your region from the listing page — it looks like:
 
 ```text
-arn:aws:sagemaker:<region>:<account-id>:endpoint/<name>
+arn:aws:sagemaker:<region>:<account-id>:model-package/<name>
+```
+
+You'll pass this in as `ModelPackageArn` in step 2.
+
+## 2. Deploy the endpoint (CloudFormation or CDK)
+
+The supported way to deploy the endpoint is the template in
+[`examples/sagemaker-marketplace`](../examples/sagemaker-marketplace), from a clean AWS account with no
+prior SageMaker/Marketplace setup beyond the subscription above. Pick CloudFormation or CDK — both
+templates create the same resources and outputs.
+
+### Parameters
+
+| Parameter              | Required | Default          | Description                                                                                                                         |
+| ----------------------- | -------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `ModelPackageArn`       | Yes      | —                 | ARN of the subscribed DS1 Marketplace model package from step 1                                                                       |
+| `EndpointName`          | No       | `ds1-endpoint`    | Name for the SageMaker endpoint                                                                                                       |
+| `InstanceType`          | No       | `ml.c5.xlarge`    | SageMaker instance type for the endpoint                                                                                              |
+| `InitialInstanceCount`  | No       | `1`               | Number of instances for the production variant                                                                                       |
+| `Region`                | Yes      | —                 | Region you're deploying into. Doesn't change where the stack deploys — it's a cross-check that must match `ModelPackageArn`'s region and your `--region`/profile |
+
+### What it creates
+
+- **`SageMakerExecutionRole`** (IAM role) — assumed by the SageMaker service to run the endpoint; scoped
+  to writing its own CloudWatch log group only
+- **`Model`** — SageMaker model pointing at the Marketplace model package, with network isolation enabled
+- **`EndpointConfig`** — production variant using `InstanceType` / `InitialInstanceCount`
+- **`Endpoint`** — the running SageMaker real-time endpoint
+
+### Outputs
+
+| Output              | Use                                                                 |
+| -------------------- | -------------------------------------------------------------------- |
+| `EndpointArn`         | Pass to `miru setup --sagemaker --arn …` in step 4                  |
+| `ExecutionRoleArn`    | The endpoint's IAM role (informational; not used by `miru setup`)  |
+| `EndpointNameOut`     | Endpoint name                                                       |
+| `RegionOut`           | Region the stack deployed into — should match `Region`              |
+
+### Deploy with CloudFormation
+
+```bash
+aws cloudformation deploy \
+  --template-file examples/sagemaker-marketplace/cloudformation/sagemaker-marketplace-endpoint.yml \
+  --stack-name ds1-sagemaker-endpoint \
+  --region <region> \
+  --capabilities CAPABILITY_NAMED_IAM \
+  --parameter-overrides \
+    ModelPackageArn=arn:aws:sagemaker:<region>:<account-id>:model-package/<name> \
+    Region=<region>
+
+aws cloudformation describe-stacks \
+  --stack-name ds1-sagemaker-endpoint \
+  --region <region> \
+  --query "Stacks[0].Outputs"
+```
+
+### Deploy with CDK
+
+```bash
+cd examples/sagemaker-marketplace/cdk
+npm install
+npx cdk deploy \
+  --parameters ModelPackageArn=arn:aws:sagemaker:<region>:<account-id>:model-package/<name> \
+  --parameters Region=<region>
+```
+
+If CDK reports that the account/region is not bootstrapped, run `npx cdk bootstrap` once and retry.
+
+`CDK_DEFAULT_ACCOUNT` / `CDK_DEFAULT_REGION` are set automatically from your AWS credentials/profile —
+confirm they match the region your `ModelPackageArn` was issued for. Outputs are printed after deploy
+completes, or re-fetch them any time with:
+
+```bash
+aws cloudformation describe-stacks \
+  --stack-name SageMakerMarketplaceEndpointStack \
+  --region <region> \
+  --query "Stacks[0].Outputs"
 ```
 
+### Advanced: manual deployment
 
+If you can't use CloudFormation/CDK, you can create the execution role, model, endpoint config, and
+endpoint by hand (console or `aws sagemaker create-*` calls). It must accept Miru's embedding request and
+return embeddings; this path has less coverage, so prefer the template.
 
-## 2. Create an invoke-only AWS profile (admin runbook)
+## 3. Create an invoke-only AWS profile (admin runbook)
 
-You need an AWS identity that can call `sagemaker:InvokeEndpoint` on that ARN. The simplest path for a laptop / CI user is a **least-privilege IAM user** scoped to that one endpoint, installed as a named profile.
+This is separate from the endpoint's execution role above — it's the identity **you or your CI** use to
+call the endpoint from `miru setup` / indexing / search. You need an AWS identity that can call
+`sagemaker:InvokeEndpoint` on the endpoint ARN from step 2. The simplest path for a laptop / CI user is a
+**least-privilege IAM user** scoped to that one endpoint, installed as a named profile.
+Organizations using IAM Identity Center should use the [federated access guide](self-hosted-sagemaker-identity-center.md) instead. It avoids long-lived IAM users and access keys.
 
-From a checkout of this repo, with the [AWS CLI](https://docs.aws.amazon.com/cli/) available and **admin** credentials in your current shell:
+From a checkout of this repo, with the [AWS CLI](https://docs.aws.amazon.com/cli/) available and **admin**
+credentials in your current shell:
 
 ```bash
 bun run sagemaker:create-invoke-user -- \
@@ -59,7 +144,8 @@ That script (`scripts/create-sagemaker-invoke-user.ts`):
 
 Optional flags: `--user-name <name>`, `--profile <name>` (alias: `--arn` for the endpoint).
 
-Prefer SSO / IAM roles in production if your org requires it — the runbook script is the easy start with long-lived keys. Rotate or delete keys when someone leaves.
+Prefer SSO / IAM roles in production if your org requires it — the runbook script is the easy start with
+long-lived keys. Rotate or delete keys when someone leaves.
 
 Smoke-test invoke (optional):
 
@@ -67,9 +153,7 @@ Smoke-test invoke (optional):
 bun run sagemaker:auth-check -- --arn arn:aws:sagemaker:<region>:<account-id>:endpoint/<name>
 ```
 
-
-
-## 3. Point Miru at the endpoint
+## 4. Point Miru at the endpoint
 
 ```bash
 miru setup --sagemaker \
@@ -77,7 +161,8 @@ miru setup --sagemaker \
   --profile miru
 ```
 
-Or run `miru setup --sagemaker` and answer the prompts.
+Use the `EndpointArn` output from step 2 and the profile from step 3. Or run `miru setup --sagemaker` and
+answer the prompts.
 
 **What setup does**
 
@@ -103,14 +188,12 @@ Also unset any `MIRU_SAGEMAKER_*` variables if you set them in the environment o
 
 Prefer `miru setup --sagemaker` so auth is checked automatically. You can also set:
 
-
 | Variable                                                 | Purpose                                                   |
-| -------------------------------------------------------- | --------------------------------------------------------- |
+| --------------------------------------------------------- | ----------------------------------------------------------- |
 | `MIRU_SAGEMAKER_ENDPOINT_ARN`                            | `arn:aws:sagemaker:<region>:<account-id>:endpoint/<name>` |
 | `MIRU_SAGEMAKER_ENDPOINT_NAME` + `MIRU_SAGEMAKER_REGION` | Alternative to the ARN                                    |
 | `AWS_PROFILE` / `AWS_ACCESS_KEY_ID` / …                  | Standard AWS credential chain                             |
 
-
 Optional TEI-style knobs: `MIRU_SAGEMAKER_NORMALIZE`, `MIRU_SAGEMAKER_TRUNCATE`, `MIRU_SAGEMAKER_TRUNCATION_DIRECTION`, `MIRU_SAGEMAKER_PROMPT_NAME`.
 
 See `miru help setup` and `miru -h` for the same flags in the CLI.