docs(maproom-plugin): document AWS Bedrock as a supported provider

plugins/maproom/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "maproom",
-  "version": "0.10.0",
+  "version": "0.10.4",
   "description": "Semantic code search using the maproom CLI. Find code by concept, understand architecture, and explore relationships between code elements.",
   "author": {
     "name": "Daniel Bushman",

plugins/maproom/agents/maproom-researcher.md

@@ -303,6 +303,9 @@ When analyzing CLI output, recognize these patterns as **credential issues, not
 | "invalid_rapt" | Expired Google authentication token | Same as above — refresh ADC credentials |
 | "quota_project_id is required" | Missing GCP quota project configuration | Run: `gcloud auth application-default set-quota-project <project-id>` |
 | "OPENAI_API_KEY" in error when not using OpenAI | Wrong embedding provider configured | Check `MAPROOM_EMBEDDING_PROVIDER` env var; see embedding-providers.md |
+| "No AWS credentials found for the Bedrock embedding provider" | Bedrock configured but the AWS credential chain found nothing | The error lists every source tried; verify with `aws sts get-caller-identity`, or `aws sso login --profile NAME` |
+| "Access denied invoking ... in REGION" (Bedrock) | Model access not enabled, or missing `bedrock:InvokeModel` | Enable the model under Bedrock > Model access for that account+region, and grant the IAM action |
+| "was not found in region" (Bedrock) | Model not offered in that region | Set `MAPROOM_BEDROCK_REGION` to a region that has it |
 
 **IMPORTANT:** If the error matches any pattern above, do NOT:
 - Suggest filing a bug against the CLI
@@ -316,7 +319,7 @@ Instead:
 4. Reference the ADC setup guide for detailed instructions: `../skills/maproom-search/references/adc-setup.md`
 
 **Distinguishing credential errors from actual code bugs:**
-- **Credential issue:** Error message contains "ADC", "token provider", "invalid_rapt", "quota_project_id", or references an API key for a provider you are not using
+- **Credential issue:** Error message contains "ADC", "token provider", "invalid_rapt", "quota_project_id", "No AWS credentials found", "IAM Identity Center token", or references an API key for a provider you are not using
 - **Code bug:** Error message references code paths, panics, segfaults, or describes unexpected behavior that occurs even with valid, fresh credentials
 
 **Security:** Do not include actual credentials, access tokens, or project IDs in your findings output. Use placeholders like `YOUR_PROJECT_ID`.

plugins/maproom/skills/maproom-guide/references/concept-glossary.md

@@ -96,7 +96,9 @@ This is the score you see in vector search results. See [result-interpretation.m
 
 ### Provider Incompatibility
 
-Different embedding providers (Google Vertex AI, OpenAI, Ollama) produce vectors in different mathematical spaces. Embeddings from one provider **cannot be compared** with embeddings from another. If you switch providers, you must regenerate all embeddings with `maproom generate-embeddings`.
+Different embedding providers (Google Vertex AI, OpenAI, Ollama, AWS Bedrock) produce vectors in different mathematical spaces. Embeddings from one provider **cannot be compared** with embeddings from another. If you switch providers, you must regenerate all embeddings with `maproom generate-embeddings`.
+
+Matching dimensions do **not** imply compatibility. Bedrock's `amazon.titan-embed-text-v2:0` and Ollama's `mxbai-embed-large` are both 1024-dimensional, but their coordinates mean entirely different things — similarity scores between them are noise. Re-index on any provider or model change, even when the dimension is unchanged.
 
 ---
 

plugins/maproom/skills/maproom-guide/references/error-diagnosis.md

@@ -10,7 +10,7 @@ Every maproom error falls into one of five categories. Identifying the category
 
 | Category | Caused By | User-Actionable? | Examples |
 |---|---|---|---|
-| **Credential** | Expired tokens, missing API keys, wrong provider | Yes — refresh or configure | ADC expiry, missing OPENAI_API_KEY |
+| **Credential** | Expired tokens, missing API keys, wrong provider | Yes — refresh or configure | ADC expiry, missing OPENAI_API_KEY, expired AWS SSO session |
 | **Index** | Repo not scanned, stale data, missing embeddings | Yes — scan or regenerate | "No repositories indexed", stale results |
 | **CLI** | Binary missing, wrong version, invalid flags | Yes — install or fix syntax | "command not found", invalid flag value |
 | **Query** | Wrong search type, bad filters, special chars | Yes — reformulate query | Zero results, irrelevant results |
@@ -32,10 +32,11 @@ Every maproom error falls into one of five categories. Identifying the category
 
 ### Why Credentials Expire
 
-Maproom's vector search and embedding generation call external APIs (Google Vertex AI by default, or OpenAI). These APIs require authentication tokens that expire periodically as a security measure.
+Maproom's vector search and embedding generation call external APIs (Google Vertex AI by default, or OpenAI, or AWS Bedrock). These APIs require authentication tokens that expire periodically as a security measure.
 
 - **Google ADC tokens** expire after ~1 hour and are automatically refreshed — but the refresh token itself can expire after extended periods of inactivity
 - **OpenAI API keys** don't expire by time, but can be revoked or rate-limited
+- **AWS SSO sessions** expire after the session duration configured by the account (commonly 8-12 hours); `aws sso login --profile NAME` re-establishes them. Instance-role and IRSA credentials refresh automatically and rarely surface as errors.
 
 ### How to Recognize Credential Errors
 
@@ -46,6 +47,9 @@ Credential errors contain one of these patterns in the error message:
 - "invalid_rapt"
 - "quota_project_id is required"
 - References to `OPENAI_API_KEY` when you're not using OpenAI
+- "No AWS credentials found for the Bedrock embedding provider" (Bedrock; the message lists every source that was tried)
+- "No valid IAM Identity Center token cached" (Bedrock via SSO — run `aws sso login`)
+- "AWS profile 'NAME' not found" (Bedrock; the message lists the profiles that do exist)
 
 **Note:** The top-level error message is usually "Failed to create embedding service". The specific credential detail (ADC, token provider, etc.) appears in the `Caused by` chain below it. An agent scanning only the first line of error output should match on "Failed to create embedding service" as the primary pattern.
 
@@ -63,7 +67,29 @@ Credential errors contain one of these patterns in the error message:
 
 1. **Don't investigate maproom source code** — credential errors are expected operational events
 2. **Fall back to FTS** — `maproom search` works entirely locally, no credentials needed
-3. **Refresh credentials** when convenient — see [ADC setup guide](../../maproom-search/references/adc-setup.md)
+3. **Refresh credentials** when convenient — see [ADC setup guide](../../maproom-search/references/adc-setup.md) for Google, or `aws sso login --profile NAME` for AWS Bedrock
+
+### Bedrock-specific credential notes
+
+Bedrock has no maproom API key — it signs requests with the standard AWS
+credential chain. That changes diagnosis in two useful ways:
+
+- The "no credentials" error **enumerates every source it tried** (environment,
+  named profile, web identity, default profile, container endpoint, IMDSv2) and
+  why each failed. Read that list before investigating anything else.
+- `aws sts get-caller-identity` is an independent check. If it succeeds and
+  maproom still fails, the problem is authorization (IAM or model access), not
+  authentication.
+
+Two distinct gates cause `AccessDeniedException`, and both must be open:
+
+1. **Model access** — enable the model under **Bedrock > Model access** in the
+   AWS console, per account and per region.
+2. **IAM** — the caller needs `bedrock:InvokeModel` on the model ARN.
+
+A `ResourceNotFoundException` naming the region usually means the model is not
+offered there, not that the id is wrong — Bedrock model availability varies by
+region.
 
 ---
 

plugins/maproom/skills/maproom-search/references/embedding-providers.md

@@ -1,6 +1,6 @@
 # Embedding Provider Comparison
 
-Maproom supports three embedding providers for vector search: Google Vertex AI, OpenAI, and Ollama. This guide helps you choose the right provider and configure it for your environment.
+Maproom supports four embedding providers for vector search: Google Vertex AI, OpenAI, Ollama, and AWS Bedrock. This guide helps you choose the right provider and configure it for your environment.
 
 ## Overview
 
@@ -15,6 +15,7 @@ Embedding providers convert code chunks into numerical vectors (embeddings) that
 | Google Vertex AI | ADC or service account (`GOOGLE_APPLICATION_CREDENTIALS`) | [ADC setup guide](./adc-setup.md) | Free tier available, then per-character pricing ([pricing](https://cloud.google.com/vertex-ai/pricing)) | 768 (`text-embedding-004`) | High quality embeddings; free tier; Google ecosystem integration | Requires GCP project; ADC credentials expire and need refresh | Teams already using Google Cloud; production environments with GCP infrastructure |
 | OpenAI | API key (`OPENAI_API_KEY`) | Set environment variable | ~$0.02 per 1M tokens ([pricing](https://openai.com/api/pricing/)) | 1536 (`text-embedding-3-small`) | Simple API key setup; widely used; high quality | Requires paid API key; higher dimensions increase storage; network-dependent | Quick setup; teams already using OpenAI; when simplicity is preferred |
 | Ollama | None (local) | Install Ollama and pull model | Free (runs locally) | Varies by model (768 for `nomic-embed-text`, 1024 for `mxbai-embed-large`) | Free; fully offline; no credentials needed; data stays local | Requires local compute resources; quality varies by model; slower on CPU | Air-gapped environments; cost-sensitive workflows; local development without API keys |
+| AWS Bedrock | Standard AWS credential chain (no new secret) | Enable model access + `bedrock:InvokeModel` | ~$0.02 per 1M tokens ([pricing](https://aws.amazon.com/bedrock/pricing/)) | 1024 (`amazon.titan-embed-text-v2:0`) | No new API key to manage; works with SSO, EC2/EKS/ECS roles; traffic can stay in a VPC; cheapest cloud option | Requires an AWS account with Bedrock enabled in-region; Titan sends one request per chunk | Teams already on AWS; environments that forbid introducing new long-lived secrets |
 
 > **Pricing disclaimer:** Costs shown are approximate as of Feb 2026 and are subject to change. Always check the linked pricing pages for current rates.
 
@@ -92,6 +93,88 @@ export MAPROOM_EMBEDDING_DIMENSION=1536
 maproom generate-embeddings
 ```
 
+### AWS Bedrock
+
+**Model:** `amazon.titan-embed-text-v2:0` (default)
+**Dimensions:** 1024
+
+Titan v2 can also emit 512- and 256-dimensional vectors, but maproom stores
+embeddings in per-dimension tables and supports only 768, 1024, and 1536.
+Setting `MAPROOM_EMBEDDING_DIMENSION=512` is rejected at startup rather than
+after a full scan.
+**Endpoint:** `bedrock-runtime.REGION.amazonaws.com`
+
+Bedrock has **no maproom-specific API key**. Requests are signed with AWS
+Signature V4 using the same credential chain the `aws` CLI uses. If
+`aws sts get-caller-identity` works on the machine, maproom can resolve
+credentials the same way.
+
+That is an authentication check only. Model access and the
+`bedrock:InvokeModel` permission are separate gates — both must also be in
+place before an embedding call succeeds (see Prerequisites below).
+
+**Prerequisites:**
+
+1. Enable the model under **Bedrock > Model access** in the AWS console (one
+   time, per account, per region). Without this, every request returns
+   `AccessDeniedException` even when IAM is correct.
+2. Grant the caller `bedrock:InvokeModel` on the model ARN.
+
+**Environment variables:**
+
+```bash
+# Set the embedding provider ('aws' and 'aws-bedrock' also work)
+export MAPROOM_EMBEDDING_PROVIDER=bedrock
+
+# Optional: which AWS profile to use (falls back to AWS_PROFILE)
+export MAPROOM_AWS_PROFILE=my-profile
+
+# Optional: region (falls back to AWS_REGION, AWS_DEFAULT_REGION,
+# the profile's region, then us-east-1)
+export MAPROOM_BEDROCK_REGION=us-east-1
+
+# Optional: override model (default: amazon.titan-embed-text-v2:0)
+export MAPROOM_EMBEDDING_MODEL=cohere.embed-english-v3
+
+# Optional: override dimensions (inferred from the model otherwise)
+export MAPROOM_EMBEDDING_DIMENSION=1024
+```
+
+**Credential resolution order:**
+
+1. `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (+ `AWS_SESSION_TOKEN`)
+2. A named profile (`MAPROOM_AWS_PROFILE` or `AWS_PROFILE`)
+3. Web identity (`AWS_WEB_IDENTITY_TOKEN_FILE` + `AWS_ROLE_ARN`) — EKS IRSA
+4. The `default` profile
+5. ECS task role / EKS Pod Identity
+6. EC2 instance role (IMDSv2)
+
+Profiles may themselves use static keys, `credential_process`, IAM Identity
+Center (SSO), or `role_arn` + `source_profile` chaining.
+
+**Available models:**
+
+| Model | Dimensions | Texts per request |
+|-------|-----------:|------------------:|
+| `amazon.titan-embed-text-v2:0` | 1024 | 1 |
+| `amazon.titan-embed-text-v1` | 1536 | 1 |
+| `cohere.embed-english-v3` | 1024 | 96 |
+| `cohere.embed-multilingual-v3` | 1024 | 96 |
+
+Prefer a Cohere model for large repositories: Bedrock's `InvokeModel` embeds
+one document per call for Titan, so a 50,000-chunk scan is 50,000 requests
+versus roughly 520 with Cohere.
+
+**Generate embeddings:**
+
+```bash
+maproom generate-embeddings
+```
+
+**Private networking:** for VPC/PrivateLink endpoints or an egress proxy, set
+`MAPROOM_BEDROCK_ENDPOINT_URL`. For FIPS 140-3 endpoints, set
+`MAPROOM_BEDROCK_USE_FIPS=true`.
+
 ### Ollama
 
 **Models:** `nomic-embed-text` (768 dimensions), `mxbai-embed-large` (1024 dimensions), and others
@@ -148,7 +231,9 @@ maproom generate-embeddings
 
 Switching embedding providers requires regenerating all embeddings because:
 
-1. **Different dimensions:** Google produces 768-dimensional vectors, OpenAI produces 1536-dimensional vectors, and Ollama dimensions vary by model. These vectors cannot be compared.
+1. **Different dimensions:** Google produces 768-dimensional vectors, OpenAI produces 1536-dimensional vectors, Bedrock's default Titan v2 produces 1024, and Ollama dimensions vary by model. These vectors cannot be compared.
+
+   Note that matching dimensions is *not* sufficient — Bedrock Titan v2 and Ollama `mxbai-embed-large` are both 1024-dimensional but occupy unrelated vector spaces. Re-index when switching between them even though the dimension does not change.
 2. **Different vector spaces:** Even if dimensions matched, each provider's model maps concepts to different coordinates. Cosine similarity scores between vectors from different providers are meaningless.
 
 **To switch providers:**
@@ -171,14 +256,19 @@ maproom vector-search --repo YOUR_REPO --query "test query" --format agent
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `MAPROOM_EMBEDDING_PROVIDER` | Provider selection | `ollama`, `openai`, `google` |
+| `MAPROOM_EMBEDDING_PROVIDER` | Provider selection | `ollama`, `openai`, `google`, `bedrock` |
 | `MAPROOM_EMBEDDING_MODEL` | Model override | `text-embedding-004`, `text-embedding-3-small`, `nomic-embed-text` |
 | `MAPROOM_EMBEDDING_DIMENSION` | Dimension override | `768`, `1536`, `1024` |
 | `OPENAI_API_KEY` | OpenAI API key | `sk-...` (placeholder) |
 | `MAPROOM_OPENAI_API_KEY` | OpenAI API key (prefixed) | `sk-...` (placeholder) |
 | `GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON | `/path/to/key.json` |
 | `GOOGLE_PROJECT_ID` | Google Cloud project ID | `YOUR_PROJECT_ID` |
 | `MAPROOM_GOOGLE_PROJECT_ID` | Google Cloud project ID (prefixed) | `YOUR_PROJECT_ID` |
+| `MAPROOM_AWS_PROFILE` | AWS shared-config profile for Bedrock | `my-profile` |
+| `AWS_PROFILE` | AWS profile (fallback) | `my-profile` |
+| `MAPROOM_BEDROCK_REGION` | Bedrock region override | `us-east-1` |
+| `MAPROOM_BEDROCK_ENDPOINT_URL` | Bedrock endpoint override (VPC/proxy) | `https://vpce-...amazonaws.com` |
+| `MAPROOM_BEDROCK_USE_FIPS` | Use the region's FIPS endpoint | `true` |
 
 ## FAQ
 
@@ -199,6 +289,7 @@ No. Full-text search uses SQLite FTS5 indexes and does not involve embeddings at
 - If you have no API keys and want to get started quickly, use **Ollama** (free, local, no setup beyond installation).
 - If you already have an OpenAI API key, use **OpenAI** (simplest cloud setup).
 - If your team uses Google Cloud, use **Google Vertex AI** (best integration with GCP tooling).
+- If your team is on AWS, use **AWS Bedrock** — it is the cheapest cloud option and introduces no new secret, since it reuses whatever already authenticates the `aws` CLI.
 
 ### Do higher dimensions mean better search quality?
 
@@ -216,6 +307,8 @@ The `generate-embeddings` command will fail mid-process. Refresh your credential
 - [Google Vertex AI Pricing](https://cloud.google.com/vertex-ai/pricing) - Official Google Cloud pricing
 - [OpenAI API Pricing](https://openai.com/api/pricing/) - Official OpenAI pricing
 - [Ollama](https://ollama.com/) - Official Ollama website and documentation
+- [AWS Bedrock Pricing](https://aws.amazon.com/bedrock/pricing/) - Official AWS pricing
+- [AWS Bedrock model support by region](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html)
 
 ---