Azure · Lei Jiang (lionelc) · Jul 31, 2026 · Jul 6, 2026 · Jul 6, 2026 · Jul 6, 2026
diff --git a/.gitignore b/.gitignore
@@ -7,3 +7,11 @@ build/
 *.log
 .vscode/
 .idea/
+
+# Regression test framework
+testing-venv/
+__pycache__/
+.pytest_cache/
+
+# Generated benchmark output (regenerate via scenarios/contoso/scaling-benchmark/)
+scenarios/contoso/scaling-benchmark/results.tsv
diff --git a/AGENTS.md b/AGENTS.md
@@ -12,7 +12,31 @@ This repository is an **Agent Skills** pack for **Azure DocumentDB (with MongoDB
 
 ## How agents should use this kit
 
-### Skill routing (do this first)
+This kit has **two routes**. Decide the route *first*, from what the user said:
+
+| The user says… | Route | What the agent does |
+|---|---|---|
+| **"use toolbox"** (explicit), or clearly asks to *run the diagnostic scripts* against a live database | **Route A — Diagnostic toolbox** | Use the knowledge-base router to pick and run a **read-only** diagnostic script against the user's *local* DocumentDB container, then report the findings. |
+| **anything else** (the default) | **Route B — Text skills** | Route to the best `skills/*/SKILL.md` and answer from guidance. |
+
+**Default to Route B.** Only take Route A when the user **explicitly** says *"use toolbox"* (or unambiguously asks to run the diagnostic scripts / inspect a live local database). Do not run any script on Route B.
+
+### Route A — Diagnostic toolbox (only when the user says "use toolbox")
+
+Deterministic, **read-only** scripts that inspect a *local* DocumentDB container (both the MongoDB API and the PostgreSQL engine underneath) and emit findings. They never modify data; no cloud, no API keys. Steps:
+
+1. **Prerequisites:** a running container (default name `documentdb-local`) and a password exported as `DB_PASSWORD` (or passed via `--password`); `db-config-advisor` is PG-only and needs no password. See [`docs/DIAGNOSTICS.md`](docs/DIAGNOSTICS.md) for the one-line `docker run` and seeding.
+2. **Route the question to the exact script** with the knowledge-base router — deterministic keyword scoring, needs no LLM and no container:
+   ```bash
+   bash knowledge-base/kb-route.sh --db <db> "<the user's question>"
+   ```
+   It prints the matching tool and the exact command (append `--json` for machine-readable output). See [`knowledge-base/README.md`](knowledge-base/README.md).
+3. **Run the recommended command** (all scripts are read-only) and interpret the findings/insights for the user. Present the fix as a recommendation — applying it (e.g. a schema split or dropping an index) is the user's decision.
+4. **If the router is not confident** (no match / low score), fall back to Route B.
+
+Tools available on this route: `document-bloat-advisor`, `index-redundancy-finder`, `db-config-advisor`, `perf-advisor`, `data-integrity-check` — catalog in [`README.md`](README.md#the-tools-scripts). Regression-guarded by [`testing/`](testing/README.md).
+
+### Route B — Text skills (default): skill routing (do this first)
 
 This kit ships **17+ skills**, which is too many to reliably pick from a flat table. Agents should route in this order:
 
@@ -58,6 +82,10 @@ These skills walk the user (or another agent) through a task end-to-end.
 
 ## Routing hints for agents
 
+These map a task to the best **Route B (text) skill**. (On **Route A** — when the
+user said *"use toolbox"* — route the same task through `knowledge-base/kb-route.sh`
+to a diagnostic script instead.)
+
 - **Writing / generating a query** → `documentdb-natural-language-querying`
 - **"Why is this query slow / how do I index this?"** → `documentdb-query-optimizer`
 - **"Which index type should I use / design this index"** → `documentdb-indexing`

diff --git a/README.md b/README.md
@@ -15,6 +15,60 @@ Skills follow the [Agent Skills](https://agentskills.io/) format and the kit shi
 
 👉 **Capabilities and skill catalog:** [`docs/SKILLS.md`](docs/SKILLS.md)
 
+## Diagnostic Toolbox — Quickstart
+
+Beyond the text skills, the kit ships **deterministic diagnostic scripts** and a
+**knowledge-base router** that inspect a *local* DocumentDB container and return
+evidence-based answers (reading both the MongoDB API and the PostgreSQL engine
+underneath). They need only `docker`, `bash`, and `python3` — no MCP server, no
+cloud, no API keys. Full guide: [`docs/DIAGNOSTICS.md`](docs/DIAGNOSTICS.md).
+
+### The tools (`scripts/`)
+
+All are **read-only** (they never modify data) and **cross-layer** (MongoDB API +
+PostgreSQL engine). Each takes `--db <name>`; add `--json` for a compact
+machine-readable result (what the router consumes).
+
+| Script | Answers | `--json` |
+|--------|---------|:--:|
+| `document-bloat-advisor.sh` | Which collections have large text TOASTed and detoasted on every scan; which field to split out. | ✅ |
+| `index-redundancy-finder.sh` | Redundant (prefix/duplicate/reverse) or unused indexes safe to drop. | ✅ |
+| `db-config-advisor.sh` | Working set vs cache, TOAST share, cache-hit ratios — evidence-based config review. | ✅ |
+| `perf-advisor.sh` | Overall health: collection-scan audit, query timing, PG I/O / locks / config. | ✅ |
+| `data-integrity-check.sh` | Orphaned foreign-key references and mixed-type fields (hard structural integrity). | ✅ |
+
+Common flags: `--container NAME`, `--password PASS`, `--port`, `--pg-port`; env
+vars `DB_USER` / `DB_PASSWORD` / `PORT` / `PG_PORT` are also honored. **No password
+is baked in** — set `DB_PASSWORD` (or pass `--password`).
+
+### Quickstart
+
+```bash
+# 0. start a local DocumentDB container (choose any password; the scripts read it)
+docker run -dt --name documentdb-local -p 10260:10260 \
+  -e USERNAME=docdbadmin -e PASSWORD=Test1234 \
+  ghcr.io/microsoft/documentdb/documentdb-local:latest
+export DB_PASSWORD=Test1234          # the scripts require this (or --password)
+
+# 1. seed demo data
+bash scenarios/ecommerce/seed.sh           # -> "ecommerce"
+bash scenarios/contoso/seed.sh             # -> "contoso" (TOAST demo)
+
+# 2. diagnose (read-only; add --json for machine output)
+bash scripts/document-bloat-advisor.sh --db contoso
+bash scripts/index-redundancy-finder.sh --db ecommerce
+
+# 3. or ask in natural language — the router picks the tool (no LLM, no container)
+bash knowledge-base/kb-route.sh --db contoso "why are my aggregations slow even though I have indexes"
+```
+
+Demo datasets are seeders under [`scenarios/`](scenarios/) (they plant the
+problems the tools find). The regression suite in [`testing/`](testing/README.md)
+guards the scripts.
+
+- **Router:** [`knowledge-base/README.md`](knowledge-base/README.md) · **Demo datasets:** [`scenarios/`](scenarios/)
+- **Regression tests:** [`testing/README.md`](testing/README.md) · **Token study:** [`token-tests/RESULTS.md`](token-tests/RESULTS.md)
+
 ## Repo Structure
 
 ```
@@ -25,6 +79,12 @@ skills/
   <skill>/               # standalone skill (mcp-setup, query-optimizer, …)
     SKILL.md             # agent-facing activation + instructions
     references/          # reference docs the skill loads at runtime
+scripts/                 # diagnostic toolbox — read-only analyzers + seeders
+knowledge-base/          # NL → script router (kb.json + kb_route.py) + demo
+scenarios/contoso/       # ready-to-run TOAST demo dataset (+ optional scaling-benchmark/)
+testing/                 # fixture-first regression suite for the scripts (pytest)
+token-tests/             # measured token savings of scripts vs text-skill workflows
+docs/                    # SKILLS.md (catalog) + DIAGNOSTICS.md (toolbox guide)
 ```
 
 ## Installation

diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,42 @@
+# Security Policy
+
+Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations.
+
+## Reporting Security Vulnerabilities
+
+**Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.**
+
+Instead, report them to the Microsoft Security Response Center (MSRC):
+
+- Report a vulnerability: https://msrc.microsoft.com/create-report
+- MSRC vulnerability reporting guidance: https://www.microsoft.com/msrc
+
+If you prefer to submit without logging in, use:
+
+- https://www.microsoft.com/msrc/report-a-vulnerability
+
+You should receive a response within 24 hours. If you do not receive a response, please follow up via the reporting portal.
+
+Please include as much information as possible to help us reproduce and investigate the issue:
+
+- Type of issue
+- Full paths of affected files or components
+- Steps to reproduce
+- Proof-of-concept code (if available)
+- Potential impact assessment
+
+## Supported Versions
+
+As this project is under active development, security fixes are typically provided in the latest version of the repository.
+
+Users are encouraged to:
+- Use the latest released version.
+- Keep dependencies up to date.
+- Follow Azure and Microsoft security best practices when deploying solutions based on this repository.
+
+## Additional Resources
+
+For more information about Microsoft's vulnerability disclosure process, see:
+
+- Microsoft Security Response Center: https://www.microsoft.com/msrc
+- Coordinated Vulnerability Disclosure: https://www.microsoft.com/msrc/cvd
diff --git a/docs/DIAGNOSTICS.md b/docs/DIAGNOSTICS.md
@@ -0,0 +1,137 @@
+# Diagnostic Toolbox — end-to-end guide
+
+The kit ships **deterministic diagnostic scripts** plus a **knowledge-base router**
+for a *local* DocumentDB container. They complement the text skills: where a skill
+tells an agent *what to consider*, these tools **measure the live database** and
+return an evidence-based answer — reading both the MongoDB API (`mongosh`) and the
+PostgreSQL engine underneath (`psql`).
+
+Everything here runs against a Docker container and needs only `docker`, `bash`,
+and `python3` on the host — no MCP server, no cloud, no API keys.
+
+| Piece | Path | What it is |
+|-------|------|-----------|
+| Diagnostic scripts | [`scripts/`](../scripts/) | 5 read-only analyzers (TOAST/bloat, index redundancy, config/cache, perf, data integrity). |
+| Knowledge-base router | [`knowledge-base/`](../knowledge-base/README.md) | Deterministic NL question → exact script (no LLM at routing time). |
+| Demo datasets | [`scenarios/ecommerce/`](../scenarios/ecommerce/), [`scenarios/contoso/`](../scenarios/contoso/README.md) | Seeders that plant the problems the tools find. |
+| Regression tests | [`testing/`](../testing/README.md) | Fixture-first contracts that guard the scripts. |
+| Token study | [`token-tests/`](../token-tests/README.md) | Measured token savings of scripts vs text-skill workflows. |
+
+---
+
+## 0. Start a local DocumentDB container
+
+Use the open-source Gateway image. Name it `documentdb-local` and pick a
+password; the scripts read it from `DB_USER` (default `docdbadmin`) and
+`DB_PASSWORD` — **nothing is baked in**:
+
+```bash
+docker run -dt --name documentdb-local \
+  -p 10260:10260 \
+  -e USERNAME=docdbadmin \
+  -e PASSWORD=Test1234 \
+  ghcr.io/microsoft/documentdb/documentdb-local:latest
+
+# the scripts require a password — export it once (or pass --password each time)
+export DB_PASSWORD=Test1234
+
+# preflight: confirm the engine answers (should print "1")
+docker exec documentdb-local psql -h localhost -p 9712 -U documentdb -d postgres -tAc "SELECT 1"
+```
+
+The scripts `docker exec` into this container (MongoDB API on 10260, PostgreSQL on
+9712 internally), so **publishing ports is optional**. If you use different
+credentials or a different container name, pass `--container` / `--password` or set
+`DB_USER` / `DB_PASSWORD` / `PORT` / `PG_PORT` env vars — every script honors them.
+
+## 1. Seed demo data
+
+```bash
+bash scenarios/ecommerce/seed.sh           # -> database "ecommerce"
+bash scenarios/contoso/seed.sh             # -> database "contoso"  (TOAST demo)
+```
+
+## 2. Run the diagnostics
+
+```bash
+# Large-document / TOAST detoast tax (analysis only — no data changes)
+bash scripts/document-bloat-advisor.sh   --db contoso
+
+# Redundant / unused indexes you can drop
+bash scripts/index-redundancy-finder.sh  --db ecommerce
+
+# Working set vs cache, TOAST share, cache-hit ratios
+bash scripts/db-config-advisor.sh        --db contoso
+
+# Overall health: collection-scan audit, query timing, PG I/O / locks / config
+bash scripts/perf-advisor.sh             --db ecommerce
+
+# Orphaned foreign keys + mixed field types (hard structural integrity)
+bash scripts/data-integrity-check.sh     --db ecommerce
+```
+
+Add `--json` to any of them for a compact machine-readable result (what the router
+and agents consume):
+
+```bash
+bash scripts/document-bloat-advisor.sh --db contoso --json
+```
+
+## 3. Natural-language routing (optional)
+
+Don't know which tool you need? Ask in plain language — the router maps it to the
+exact script, deterministically, **without a container or an LLM**:
+
+```bash
+bash knowledge-base/kb-route.sh --db contoso "why are my aggregations slow even though I have indexes"
+#   → document-bloat-advisor  ·  run: bash scripts/document-bloat-advisor.sh --db contoso [--json]
+
+# see the scoring walkthrough
+python3 knowledge-base/kb_route_demo.py "which indexes can I drop"
+```
+
+## 4. See the TOAST fix in action (optional)
+
+```bash
+# apply the schema split the advisor recommends, then re-run the advisor
+docker cp scenarios/contoso/contoso-split-fix.js documentdb-local:/tmp/fix.js
+docker exec -e CONTOSO_DB=contoso documentdb-local mongosh \
+  "localhost:10260/contoso" -u docdbadmin -p Test1234 \
+  --authenticationMechanism SCRAM-SHA-256 --tls --tlsAllowInvalidCertificates \
+  --quiet --file /tmp/fix.js
+bash scripts/document-bloat-advisor.sh --db contoso     # opportunities now clean
+```
+
+## 5. Run the regression tests (optional)
+
+```bash
+bash testing/run.sh          # fixture-first contracts; auto-creates a venv
+```
+
+## 6. Reproduce the token study (optional)
+
+```bash
+cd token-tests
+bash token-ab-measure.sh | python3 summarize.py     # see RESULTS.md for the table
+```
+
+---
+
+## Connection defaults
+
+| Setting | Default | Override |
+|---|---|---|
+| container | `documentdb-local` | `--container` |
+| Mongo port | `10260` | `--port` / `PORT` |
+| PG port | `9712` | `--pg-port` / `PG_PORT` |
+| Mongo user | `docdbadmin` | `DB_USER` |
+| password | *(required)* | `--password` / `DB_PASSWORD` |
+| PG user | `documentdb` | `PG_USER` |
+
+## Notes
+
+- The scripts are **read-only** — they never modify data. The only script that
+  changes data is the explicit, opt-in `contoso-split-fix.js` demo in step 4.
+- The scaling benchmark under
+  [`scenarios/contoso/scaling-benchmark/`](../scenarios/contoso/scaling-benchmark/README.md)
+  is **optional/advanced** (multi-scale x1…x16) and is **not** part of this quickstart.
diff --git a/docs/SKILLS.md b/docs/SKILLS.md
@@ -42,6 +42,30 @@ Single-purpose skills the agent loads when its trigger description matches.
 | [`query-optimizer/`](../skills/query-optimizer/) | "Why is this query slow?", index review, `explain()`-driven tuning (indexing deep-dive lives in its `references/`) |
 | [`connection/`](../skills/connection/) | Connection pool / timeout / retry tuning; serverless vs OLTP vs OLAP patterns |
 
+## Diagnostic toolbox (scripts + router)
+
+Beyond the text skills, the kit ships **deterministic, read-only diagnostic
+scripts** that inspect a *local* DocumentDB container across both layers (MongoDB
+API + PostgreSQL engine), plus a **knowledge-base router** that maps a natural-
+language question to the exact script — no LLM at routing time. Full guide:
+[`DIAGNOSTICS.md`](DIAGNOSTICS.md); catalog: [`../README.md`](../README.md#the-tools-scripts).
+
+| Tool | Answers |
+|---|---|
+| [`document-bloat-advisor.sh`](../scripts/document-bloat-advisor.sh) | Which collections have large text TOASTed and detoasted on every scan; which field to split out. |
+| [`index-redundancy-finder.sh`](../scripts/index-redundancy-finder.sh) | Redundant (prefix/duplicate/reverse) or unused indexes safe to drop. |
+| [`db-config-advisor.sh`](../scripts/db-config-advisor.sh) | Working set vs cache, TOAST share, cache-hit ratios (evidence-based). |
+| [`perf-advisor.sh`](../scripts/perf-advisor.sh) | Overall health: collection-scan audit, query timing, PG I/O / locks / config. |
+| [`data-integrity-check.sh`](../scripts/data-integrity-check.sh) | Orphaned foreign keys + mixed-type fields (hard structural integrity). |
+| [`knowledge-base/`](../knowledge-base/README.md) | NL question → exact script (deterministic keyword scoring, zero deps). |
+
+Companion to the toolbox: the `data-modeling` skill's
+[`model-large-field-split`](../skills/data-modeling/model-large-field-split.md)
+rule explains the TOAST anti-pattern, and its analyzer
+[`scripts/toast-split-advisor.sh`](../scripts/toast-split-advisor.sh) measures it.
+The scripts are guarded by the regression suite in [`../testing/`](../testing/README.md),
+and their token efficiency is measured in [`../token-tests/RESULTS.md`](../token-tests/RESULTS.md).
+
 ## Use when
 
 - Designing document schemas for Azure DocumentDB