scoutline 0.1.0 → 0.6.0

package/README.md

@@ -21,6 +21,7 @@
 - **Repo** - Search and read GitHub repository code via ZRead
 - **Tools** - MCP tool discovery, schemas, and raw calls
 - **Code Mode** - TypeScript tool chaining for agent automation
+- **Provider selection** - Run shared capabilities through Z.AI or MiniMax Token Plan
 
 ## Quick Start
 
@@ -32,7 +33,14 @@ npx scoutline vision analyze ./screenshot.png "What errors do you see?"
 npx scoutline search "React 19 new features" --count 5
 ```
 
-Get your API key at: https://z.ai/manage-apikey/apikey-list
+Get your Z.AI API key at: https://z.ai/manage-apikey/apikey-list
+
+To use MiniMax instead:
+
+```bash
+export MINIMAX_API_KEY="your-minimax-key"
+npx scoutline --provider minimax search "latest LLM benchmarks"
+```
 
 ## Installation
 
@@ -63,6 +71,134 @@ Or use directly with npx:
 npx scoutline --help
 ```
 
+## Provider Selection
+
+Shared commands (`search`, `vision`, `quota`, `doctor`, `repo`) accept a global
+`--provider <zai|minimax>` flag. Resolution precedence:
+
+1. Explicit `--provider <zai|minimax>` on the command line
+2. `SCOUTLINE_PROVIDER` environment variable
+3. Compatibility default `zai`
+
+Examples:
+
+```bash
+# 1. Flag wins over everything
+scoutline --provider minimax search "React 19 features"
+
+# 2. Environment variable when no flag is supplied
+export SCOUTLINE_PROVIDER=minimax
+scoutline quota
+
+# 3. Default Z.AI when nothing is supplied
+scoutline search "TypeScript best practices"
+```
+
+Provider selection is **never** inferred from which credentials are present;
+empty credentials leave the Provider unconfigured and shared capabilities will
+fail with `AUTH_ERROR` or `CONFIGURATION_ERROR`. Unknown Provider IDs fail
+fast with `VALIDATION_ERROR`.
+
+`scoutline search`, `scoutline vision`, `scoutline quota`, `scoutline doctor`,
+**`scoutline repo`**, and **`scoutline read`** participate in Provider
+selection. `scoutline tools`, `scoutline tool`, `scoutline call`, and
+`scoutline code` accept the flag but ignore it; they remain Z.AI-only.
+MiniMax does not currently advertise the `repository-exploration` or `reader`
+Capabilities — selecting MiniMax (explicitly or via `SCOUTLINE_PROVIDER`) for
+any `repo` subcommand or for `read` returns `UNSUPPORTED_CAPABILITY` before
+descriptor configuration, Adapter creation, cache identity, or transport
+construction, with no Z.AI fallback.
+
+## Capability Matrix
+
+| Capability | Z.AI | MiniMax | Notes |
+| --- | --- | --- | --- |
+| `search` | Yes | Yes | MiniMax rejects domain/recency/content-size/location controls |
+| `vision.interpret-image` (analyze) | Yes | Yes | Provider-specific media limits; uncached |
+| `vision.ui-artifact` (ui-to-code) | Yes | Available | Live-attested; conformance-gated |
+| `vision.extract-text` | Yes | Pending | Implemented, pending live conformance |
+| `vision.diagnose-error` | Yes | Available | Live-attested; conformance-gated |
+| `vision.diagram` | Yes | Pending | Implemented, pending live conformance |
+| `vision.chart` | Yes | Pending | Implemented, pending live conformance |
+| `vision.diff` (image diff) | Yes | No | Z.AI-only (never MiniMax-claimable) |
+| `vision.video` | Yes | No | Z.AI-only (never MiniMax-claimable) |
+| `quota` | Yes | Yes | Normalized `QuotaDashboard` (ADR-0001) |
+| `diagnostics` (`doctor`) | Yes | Yes | Lists both Providers; probes configured |
+| `read` (Reader) | Yes | **No** (UNSUPPORTED_CAPABILITY) | Participates in selection; only Z.AI supplies `reader` |
+| `repo search` / `repo read` / `repo tree` | Yes | **No** (UNSUPPORTED_CAPABILITY) | Participates in selection; only Z.AI supplies `repository-exploration` |
+| `tools`, `tool`, `call` (Raw tools) | Yes | No | Z.AI-only; accepts but ignores `--provider` |
+| `code` (Code Mode) | Yes | No | Z.AI-only; accepts but ignores `--provider` |
+
+Media limits for general single-image interpretation:
+
+| Provider | Formats | Maximum |
+| --- | --- | --- |
+| Z.AI | JPG, JPEG, PNG | 5 MiB |
+| MiniMax | JPG, JPEG, PNG, WebP | 50 MiB |
+
+Vision results are never written to the local response cache.
+
+### Specialized MiniMax Vision Mappings
+
+The five specialized MiniMax Vision operations (`ui-artifact`,
+`extract-text`, `diagnose-error`, `diagram`, `chart`) are **implemented**
+in this release. Each operation has a dedicated prompt-composition Module
+under `packages/scoutline/src/providers/minimax/vision-mappings/` and a
+generated mapping revision committed to source.
+
+Runtime support for these operations is gated by the compiled conformance
+registry (`src/providers/minimax/vision-conformance.ts`). A specialized
+operation is only routable through MiniMax when **every** condition holds:
+
+- offline conformance state is `pass`,
+- live conformance state is `pass`,
+- a sanitized compiled attestation matches the operation, fixture version,
+  Implementation identity, and generated mapping revision.
+
+In the current release, `ui-artifact` and `diagnose-error` have offline
+`pass`, live `pass`, and compiled attestations — they are **supported at
+runtime** through MiniMax. The remaining three operations (`extract-text`,
+`diagram`, `chart`) have offline `pass` and live `pending`; they are
+**unsupported at runtime** through MiniMax. Selecting MiniMax explicitly
+for one of these operations fails closed with `UNSUPPORTED_CAPABILITY`
+before credentials, media, transport, cache, or any other Provider is
+touched (FR-023, FR-024). There is **no automatic Z.AI fallback** for an
+explicit MiniMax selection — call without `--provider minimax` (or unset
+`SCOUTLINE_PROVIDER`) to route through Z.AI instead.
+
+No environment variable, flag, or configuration value can promote a
+mapping to supported. Support is driven exclusively by the compiled
+registry state.
+
+#### Enabling live support
+
+Live support is gated on a per-operation live attestation. The
+attestation script requires explicit opt-in and `MINIMAX_API_KEY`:
+
+```bash
+SCOUTLINE_LIVE_TESTS=1 node scripts/attest-minimax-vision.mjs --operation chart
+```
+
+Replace `chart` with `ui-artifact`, `extract-text`, `diagnose-error`,
+or `diagram`. The script runs one fixture against the live Provider,
+evaluates the semantic assertions in memory, and either:
+
+- writes a sanitized attestation entry to
+  `src/providers/minimax/vision-attestations.ts`, flips the registry's
+  `live` state to `pass`, and verifies runtime support becomes `true`;
+  OR
+- sets the registry's `live` state to `fail` if the semantics do not
+  hold. No success attestation is written and the mapping remains
+  unsupported.
+
+The next `npm run build` recompiles the registry with the new
+attestation and the operation becomes routable through MiniMax.
+
+Help text, `doctor`, and the Adapter's descriptor metadata all derive
+from the same registry, so once a mapping is promoted it appears on
+every runtime surface automatically — there is no second support list
+to update.
+
 ## Usage
 
 The CLI is self-documenting. Use `--help` at any level:
@@ -72,11 +208,18 @@ scoutline --help              # All commands
 scoutline vision --help       # Vision commands
 scoutline search --help       # Search options
 scoutline repo --help         # GitHub repo commands
+scoutline doctor --help       # Provider diagnostics
+scoutline quota --help        # Plan usage
+scoutline cache --help        # Local cache inspection and clearing
 ```
 
 ### Examples
 
 ```bash
+# Provider selection
+scoutline --provider minimax search "AI policy news"
+scoutline --provider zai search "internal docs"
+
 # Vision - analyze images
 scoutline vision analyze ./image.png "Describe this"
 scoutline vision ui-to-code ./design.png --output code
@@ -98,9 +241,18 @@ scoutline repo read anthropics/anthropic-sdk-python README.md
 scoutline repo search openai/codex "config" --language en
 scoutline repo tree openai/codex --path codex-rs --depth 2
 
+# Quota - effective or all providers
+scoutline quota                       # effective Provider
+scoutline quota --all-providers       # every configured Provider
+
 # Doctor - check setup
-scoutline doctor
-scoutline doctor --no-vision
+scoutline doctor                      # full diagnostics
+scoutline doctor --no-tools           # metadata only, no transport
+scoutline doctor --provider minimax   # MiniMax connectivity
+
+# Cache - inspect or clear the local cache
+scoutline cache stats                 # show inventory of both subdirectories
+scoutline cache clear                 # delete every file under cache/ and tools/
 ```
 
 ## Output Format
@@ -115,14 +267,249 @@ Default output is **data-only** for token efficiency. Use `--output-format json`
 }
 ```
 
+Quota output is a schema-version-1 `QuotaDashboard`:
+
+```json
+{
+  "schemaVersion": 1,
+  "effectiveProvider": "zai",
+  "providers": [
+    {
+      "provider": "zai",
+      "status": "ok",
+      "categories": [
+        { "name": "requests", "unit": "requests", "current": { "remainingPercent": 87.5 } },
+        { "name": "tokens",   "unit": "tokens",   "current": { "remainingPercent": 64.2 } }
+      ]
+    }
+  ]
+}
+```
+
+Doctor output is a schema-version-1 `DiagnosticsReport` listing every built-in
+Provider with its configured state, declared capabilities, probe status, and a
+one-line cache summary under the `cache` field.
+
 ## Notes
 
 - `repo search` defaults to English results. Use `--language zh` for Chinese.
 - `repo tree` supports `--path` (directory scope) and `--depth` (expand subtrees).
-- `tools`, `tool`, `call`, `doctor` accept `--no-vision` to speed startup when vision tools are not needed.
-- `read` supports `--with-images-summary`, `--no-gfm`, and `--keep-img-data-url` for richer parsing control.
+- `quota --all-providers` exits 1 if any configured Provider fails; successful
+  entries are still reported.
+- `doctor` exits 1 when the effective Provider is unconfigured or any
+  configured probe fails; successful entries are still reported.
+- `read` returns a schema-version-1 envelope (content read or extract read) in every output mode. `--with-images-summary`, `--no-gfm`, and `--keep-img-data-url` are passed through to the Provider request. `--max-chars` is ignored on extract reads; `--full-envelope` is silently deprecated.
 - Vision tool calls automatically retry transient 5xx/network errors (default: 2 retries). Configure with `ZAI_MCP_VISION_RETRY_COUNT` (or `ZAI_MCP_RETRY_COUNT` for all tools).
-- Tool discovery can be cached to speed `tools`/`tool`/`doctor` (default: on, 24h TTL). Configure with `ZAI_MCP_TOOL_CACHE`, `ZAI_MCP_TOOL_CACHE_TTL_MS`, `ZAI_MCP_CACHE_DIR`.
+- Tool discovery can be cached to speed `tools`/`tool`/`doctor` (default: on, 24h TTL). The cache shares the unified root with the response cache; configure both via `SCOUTLINE_CACHE`, `SCOUTLINE_CACHE_TTL_MS`, `SCOUTLINE_CACHE_SIZE_MB`, and `SCOUTLINE_CACHE_DIR` (legacy aliases `ZAI_MCP_TOOL_CACHE*`, `ZAI_MCP_CACHE_DIR`, and `ZAI_CACHE*` are accepted silently).
+- The local cache lives at `~/.scoutline/` (`cache/` for responses, `tools/` for tool discovery) on every platform. Inspect or clear it with `scoutline cache stats` and `scoutline cache clear`.
+
+## Repository Exploration (P6)
+
+`scoutline repo search`, `scoutline repo read`, and `scoutline repo tree`
+participate in `--provider` selection. Z.AI advertises the
+`repository-exploration` Capability and supplies it through the Z.AI
+Repository Adapter. MiniMax does not advertise it; selecting MiniMax returns
+`UNSUPPORTED_CAPABILITY` before descriptor configuration, Adapter creation,
+credential resolution for use, cache identity, or transport construction
+with no fallback to Z.AI.
+
+### Breaking data-mode migration (v0.2 → v1)
+
+The three `repo` successes return **schema-version-1 structured values** in
+every output mode. This is an intentional breaking change from the v0.2 raw
+Search/File strings and the depth-dependent raw Tree shape:
+
+| Command | v0.2 (legacy, now obsolete) | v1 (current) |
+| --- | --- | --- |
+| `repo search` | Raw ZRead text with `<excerpt>` blocks | `{schemaVersion, repository, query, language, excerpts:[{text}], truncated, originalTextLength}` |
+| `repo read` | Raw `<file_content>…</file_content>` body | `{schemaVersion, repository, path, content, truncated, originalContentLength}` |
+| `repo tree` | `<structure>` block (depth 1 returned split/deep routes) | `{schemaVersion, repository, path, depth, snapshots:[{repository, path, entries:[{name, path, kind}]}]}` (structured at every depth, including depth 1) |
+
+`data` mode emits the exact object above. `json` and `pretty` wrap it through
+the standard success envelope. Text-oriented modes (`compact`, `markdown`,
+`refs`, `tty`) fall back to the JSON value because the command supplies no
+prose presentation override.
+
+**Scripting impact:** any consumer parsing v0.2 raw ZRead text or the v0.2
+split/deep `tree` shape must switch to the v1 structured fields. The raw
+`scoutline.zai.*` namespace remains available for callers that need the
+legacy grammar; it is not wrapped in the v1 envelope.
+
+### Canonical repository paths
+
+- Tree aliases omitted, empty, `/`, or `.` normalize to the root path `""`.
+- File paths must be non-root; the root is invalid for `repo read`.
+- Leading `./` and leading `/` are accepted on File; leading and trailing `/`
+  are stripped and repeated `/` collapses on both.
+- Actual `.`/`..` segments, backslashes, and ASCII control characters are
+  rejected. Percent escapes (`%XX`) are never decoded — they remain literal.
+
+### `--max-chars` (deterministic, local)
+
+`--max-chars` is **never** a summarization model call. It is presentation
+projection applied to the normalized result after caching.
+
+- Absent, zero, or negative → no truncation.
+- `repo read` → truncates `content` with the existing ellipsis rule; preserves
+  the original length in `originalContentLength` and sets `truncated: true`.
+- `repo search` → applies **one total budget** across `excerpts[].text` in
+  Provider order; the final retained excerpt is truncated and later excerpts
+  are omitted.
+- `repo tree` → never character-limited.
+- Metadata, JSON envelopes, and Tree snapshots are not part of the budget.
+
+### Empty results
+
+A future Provider Adapter may explicitly return an empty `excerpts`/`entries`
+array when its own contract distinguishes a valid empty state. The Z.AI
+Adapter requires at least one well-formed `<excerpt>` block per Search;
+unwrapped text is malformed and surfaces as a normalized `API_ERROR 502`, not
+as an empty success. An empty ZRead structure without `entries` is malformed
+the same way.
+
+### Cache continuity
+
+Repository results use a new key shape
+`v2.repository-exploration-<op>.<provider>.<credential-hash>.<request-hash>.json`.
+The credential hash is supplied by the Adapter (full lowercase SHA-256 hex
+digest of the active credential) and is never re-hashed by cache code.
+
+Legacy v0.2 Z.AI cache entries remain readable **read-only**: their key is
+reconstructed from the same Adapter-resolved credential using the exact v0.2
+algorithm, and a valid hit is written through to the new key. Old files are
+never rewritten, migrated, or deleted. `--no-cache` performs no reads or
+writes. Injected credentials drive the fingerprint and legacy-key
+construction; ambient `process.env` is never reread.
+
+### Errors and lifecycle
+
+Encoded MCP error envelopes are recognized before success parsing:
+`QUOTA_ERROR` 429 (exhausted ZRead quota, code `1310`) is terminal; transient
+429/5xx and a malformed envelope retry once; auth 401/403 and other 4xx are
+terminal. Raw Provider response bodies, reset metadata, and error texts are
+discarded.
+
+Transport close is best-effort and called once per constructed attempt. A
+successful operation does not become a failure when close rejects or times
+out, and a primary failure remains the outward failure when close also fails.
+Cache hits construct and close no transport.
+
+### Diagnostics inventory
+
+`sharedCapabilities` and `zaiOnlyCapabilities` are derived from descriptor
+metadata (intersection across built-in Providers; Z.AI minus the union of
+the others). `repository-exploration` is therefore `zaiOnlyCapabilities`
+while still participating in Provider selection. Doctor help names MiniMax
+as unsupported for `repo`.
+
+### Non-goals
+
+This release does not add MiniMax repository exploration, a Reader
+migration, automatic summarization, dynamic Provider loading, or an implicit
+Z.AI fallback for unsupported Providers. The P5 specialized Vision mappings
+remain independent and are not claimed complete here.
+
+## Reader (P7)
+
+`scoutline read` participates in `--provider` selection. Z.AI advertises the
+`reader` Capability and supplies it through the Z.AI Reader Adapter. MiniMax
+does not advertise it; selecting MiniMax returns `UNSUPPORTED_CAPABILITY`
+before descriptor configuration, Adapter creation, credential resolution for
+use, cache identity, or transport construction, with no fallback to Z.AI.
+
+### Breaking data-mode migration (v0.2 → v1)
+
+`scoutline read` returns **schema-version-1 structured values** in every
+output mode. This is an intentional breaking change from the v0.2 raw content
+string and the bare extract array:
+
+| Read shape | v0.2 (legacy, now obsolete) | v1 (current) |
+| --- | --- | --- |
+| Content read (default) | Raw content string | `{schemaVersion, url, finalUrl, title, content, contentFormat, truncated, originalContentLength}` |
+| Extract read (`--extract <mode>`) | Bare JSON array of items | `{schemaVersion, url, finalUrl, mode, items, truncated, originalItemCount}` |
+
+`url` is exactly what the caller passed; `finalUrl` is the URL the operation
+actually fetched, which differs only when a Provider-side rewrite occurred
+(e.g. `gist.github.com/<id>` → `gist.github.com/<id>/raw`). The v0.2 stderr
+rewrite notice is gone — the signal now lives in `finalUrl`.
+
+The four `--extract` modes (`code`, `links`, `tables`, `headings`) and the
+shape of each item are unchanged from v0.2. Only the outer envelope changed
+(bare array → schema-versioned object with `items`).
+
+#### Output-mode behavior
+
+| Mode | Content read | Extract read |
+| --- | --- | --- |
+| `data` | The content-read envelope object | The extract-read envelope object |
+| `json` | `{success: true, data: <envelope>, timestamp}` (indent 0) | same |
+| `pretty` | `{success: true, data: <envelope>, timestamp}` (indent 2) | same |
+| `compact` | The `content` string directly | JSON fallback (the envelope object) |
+| `markdown` | The `content` string directly | JSON fallback |
+| `refs` | The `content` string directly | JSON fallback |
+| `tty` | The `content` string directly | JSON fallback |
+
+`compact`, `markdown`, `refs`, and `tty` exist to give operators a prose form
+for human reading. A content read supplies one (the page body). An extract
+read does not — extracted items are data, not prose — so those modes fall
+back to JSON. This is the deliberate asymmetry from `repo`, whose results are
+always structured data.
+
+**Scripting impact:** any consumer that did `scoutline read URL > file.md`,
+`scoutline read URL | jq -r .content`, or `scoutline read URL --extract code |
+jq -c .[]` against v0.2 output must switch to the v1 envelope. `--max-chars`
+still truncates the content-read `content`; it is **ignored on extract reads**
+(extract reports `originalItemCount` instead). The deprecated
+`--full-envelope` flag is silently accepted and ignored — the envelope is
+always returned at v1.
+
+### URL rewrite as `finalUrl`
+
+A Provider-side URL rewrite (today: gist URLs to their raw form) is recorded
+as `finalUrl` in the v1 result. The rewrite is idempotent on URLs already
+ending in `/raw` and preserves fragments. The v0.2 stderr notice is removed.
+
+### Cache namespace
+
+Reader results share the partitioned cache namespace and use the
+`reader-fetch` operation suffix:
+
+```text
+v2.reader-reader-fetch.<provider>.<credential-hash>.<request-hash>.json
+```
+
+The Adapter resolves its credential once. The canonical request URL is the
+**rewritten** URL so two requests that normalize to the same fetched URL share
+one cache entry. Legacy v0.2 Z.AI entries are reconstructed from the same
+Adapter-resolved credential using the exact v0.2 args-order algorithm and
+remain read-only; a valid hit is written through to the new key; legacy files
+are never migrated, rewritten, or deleted. `--no-cache` performs no reads or
+writes. Injected credentials drive the fingerprint and legacy-key
+construction; ambient `process.env` is never reread.
+
+### Errors and lifecycle
+
+Encoded MCP error envelopes are recognized before success parsing. The same
+taxonomy that governs `repo` applies: exhausted WebReader quota (code `1310`
+or explicit exhausted-limit meaning) surfaces as a normalized `QUOTA_ERROR`
+429 and is terminal; transient 429/5xx and a malformed envelope retry once;
+auth 401/403 and other 4xx are terminal. Raw Provider body, reset metadata,
+and error-text strings are discarded. Transport close is best-effort and
+called once per constructed attempt; a close failure never masks a primary
+result. Cache hits construct and close no transport.
+
+### Diagnostics inventory
+
+`sharedCapabilities` and `zaiOnlyCapabilities` are derived from descriptor
+metadata. `reader` is therefore `zaiOnlyCapabilities` while still
+participating in Provider selection, and Doctor help names MiniMax as
+unsupported for `read`.
+
+### Non-goals
+
+This release does not add a MiniMax Reader Adapter, automatic summarization,
+removal of the deprecated `--full-envelope` flag, or a future `--max-items`
+truncation policy for extract reads.
 
 ## Contributing
 
@@ -143,4 +530,4 @@ MIT - see [LICENSE](https://github.com/vikasagarwal101/scoutline/blob/main/LICEN
 ## Links
 
 - [GitHub Repository](https://github.com/vikasagarwal101/scoutline)
-- [Documentation](https://github.com/vikasagarwal101/scoutline/tree/main/docs)
+- [Documentation](https://github.com/vikasagarwal101/scoutline/tree/main/docs)

package/bin/scoutline.js

@@ -1,17 +1,38 @@
 #!/usr/bin/env node
 
-import("../dist/index.js").catch((err) => {
-  console.error(
-    JSON.stringify(
-      {
-        success: false,
-        error: err.message,
-        code: "LOAD_ERROR",
-        help: 'Make sure to run "npm run build" before running scoutline',
-      },
-      null,
-      2,
-    ),
-  );
-  process.exit(1);
-});
+import("../dist/index.js")
+  .then(async ({ main }) => {
+    const { createNodeCommandInvocationAdapter } =
+      await import("../dist/node-command-invocation-adapter.js");
+    const adapter = createNodeCommandInvocationAdapter();
+    const status = await main(process.argv.slice(2), {
+      invocation: adapter,
+      env: process.env,
+    });
+    adapter.setExitCode(status);
+  })
+  .catch(async (err) => {
+    try {
+      const { formatLoadFailure } = await import(
+        "../dist/node-command-invocation-adapter.js"
+      );
+      console.error(formatLoadFailure(err));
+    } catch {
+      // If the dist module is unavailable for any reason, fall back to a
+      // best-effort envelope. We do not let a missing helper hide the
+      // original load error from the user.
+      console.error(
+        JSON.stringify(
+          {
+            success: false,
+            error: err && err.message ? err.message : String(err),
+            code: "LOAD_ERROR",
+            help: 'Make sure to run "npm run build" before running scoutline',
+          },
+          null,
+          2,
+        ),
+      );
+    }
+    process.exit(1);
+  });

package/dist/capabilities/diagnostics.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Diagnostics Capability Contract (DESIGN.md §14, P4-04, P6-06).
+ *
+ * Defines the schema-version-1 diagnostics report every `doctor`
+ * invocation returns, plus the capability contract each Provider
+ * Adapter implements so its connectivity can be probed without a
+ * generative request.
+ *
+ * The report is built by the doctor command from descriptor-derived
+ * inventory plus the success/failure of each configured Provider
+ * probe. Each Adapter performs exactly ONE connectivity attempt;
+ * shared execution owns the retry policy.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - Imports Provider identity and metadata types (`ProviderCapability`,
+ *     `ProviderDescriptor`, `ProviderId`) and shared errors. P6-06 keeps
+ *     the inventory descriptor-derived; no concrete Adapter, no
+ *     Provider transport, no production registry import lives here.
+ *   - Imports no Provider transport, no Provider Adapter, no Vision
+ *     operation→capability mapping, no MiniMax specialized-vision
+ *     conformance registry, no command presentation. The previous
+ *     hand-maintained inventory required those imports; the
+ *     descriptor-derived inventory does not.
+ *
+ * Inventory derivation (P6-06):
+ *   - `sharedCapabilities` is the intersection across every descriptor
+ *     passed to `buildDiagnosticsReport`, preserving deterministic
+ *     canonical order from the FIRST descriptor.
+ *   - `zaiOnlyCapabilities` is the Z.AI descriptor's capabilities
+ *     minus the union of every OTHER built-in descriptor's
+ *     capabilities, preserving Z.AI descriptor order. Values are
+ *     descriptor capability IDs only — no hand-maintained aliases.
+ *   - `repository-exploration` is excluded from shared while any
+ *     built-in lacks it, and included in Z.AI-only the moment Z.AI
+ *     advertises it and another built-in does not.
+ */
+import type { ProviderCapability, ProviderDescriptor, ProviderId } from "../providers/types.js";
+import { type ScoutlineErrorCode } from "../lib/errors.js";
+export interface DiagnosticOptions {
+    readonly probe: boolean;
+}
+export interface ProviderDiagnostic {
+    readonly provider: ProviderId;
+    readonly configured: boolean;
+    readonly capabilities: readonly ProviderCapability[];
+    readonly status: "ok" | "error" | "skipped";
+    readonly reason?: "not-configured" | "tools-disabled";
+    readonly error?: {
+        code: ScoutlineErrorCode;
+        message: string;
+        help?: string;
+    };
+}
+export interface DiagnosticsReport {
+    readonly schemaVersion: 1;
+    readonly effectiveProvider: ProviderId;
+    readonly sharedCapabilities: readonly ProviderCapability[];
+    readonly zaiOnlyCapabilities: readonly string[];
+    readonly node: {
+        readonly version: string;
+        readonly visionMcpCompatible: boolean;
+    };
+    readonly providers: readonly ProviderDiagnostic[];
+    /**
+     * One-line cache summary embedded by the CLI handler
+     * (`Cache: enabled, 47 response entries (12.3 MB), 1 tool entry
+     *  (8.2 KB), ~/.scoutline/`). Optional: present when the dispatcher
+     * passes a pre-formatted `cacheSummary` through
+     * `DoctorDiagnosticsDependencies`. The Doctor report builder NEVER
+     * formats this itself (L1 fix); it only embeds what the caller
+     * supplied. Older callers that omit the dependency produce a report
+     * without this field.
+     */
+    readonly cache?: {
+        readonly summary: string;
+    };
+}
+/**
+ * Capability each Provider Adapter implements for connectivity
+ * diagnostics. `invoke` resolves on a successful single connectivity
+ * attempt and throws a normalized {@link ScoutlineError} on failure;
+ * the doctor command catches the throw and records a redacted error
+ * entry. Returning `void` keeps the report builder the single owner of
+ * report shape.
+ */
+export interface DiagnosticsCapability {
+    invoke(options: DiagnosticOptions): Promise<void>;
+}
+/**
+ * Derive the shared Capabilities inventory: the intersection of every
+ * descriptor's `capabilities()` set, preserving deterministic
+ * canonical order from the FIRST descriptor in the list.
+ *
+ * Edge cases:
+ *   - Empty descriptor list: returns an empty array.
+ *   - Single descriptor: returns that descriptor's capabilities in
+ *     their declared order (the intersection of one set is itself).
+ *   - Two or more: keeps a capability from the first descriptor iff
+ *     every other descriptor also advertises it.
+ *
+ * The returned array is frozen so callers cannot mutate the cached
+ * derivation in place.
+ */
+export declare function deriveSharedCapabilities(descriptors: readonly ProviderDescriptor[]): readonly ProviderCapability[];
+/**
+ * Derive the Z.AI-only Capabilities inventory: capabilities advertised
+ * by the Z.AI descriptor minus the union of capabilities advertised by
+ * every OTHER descriptor in the list. Preserves Z.AI descriptor order.
+ *
+ * Edge cases:
+ *   - Empty descriptor list: returns an empty array.
+ *   - Z.AI absent from the list: returns an empty array.
+ *   - Z.AI present as the only descriptor: returns its capabilities
+ *     verbatim (the "minus nothing" case).
+ *   - Z.AI with other descriptors: each capability in Z.AI descriptor
+ *     order is kept iff no other descriptor advertises it.
+ *
+ * The returned values are descriptor capability IDs only. No
+ * hand-maintained aliases, no parallel base-release list, no
+ * invented names. `repository-exploration` lands here naturally the
+ * moment Z.AI advertises it and another built-in does not.
+ */
+export declare function deriveZaiOnlyCapabilities(descriptors: readonly ProviderDescriptor[]): readonly ProviderCapability[];
+/**
+ * Map a thrown error into a normalized diagnostic error entry. The
+ * caller is responsible for recursive redaction before the entry
+ * crosses an outward boundary (the doctor command does this in
+ * {@link buildDiagnosticsReport}).
+ */
+export declare function diagnosticErrorFromError(error: unknown): {
+    code: ScoutlineErrorCode;
+    message: string;
+    help?: string;
+};
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/capabilities/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/capabilities/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAM3E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,CAAC;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,kBAAkB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,iBAAiB,EAAE,UAAU,CAAC;IACvC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC3D,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;KACvC,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAClD;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAYD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,SAAS,kBAAkB,EAAE,GACzC,SAAS,kBAAkB,EAAE,CAc/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,SAAS,kBAAkB,EAAE,GACzC,SAAS,kBAAkB,EAAE,CAoB/B;AAMD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG;IACxD,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAYA"}