--- name: validate-config description: | Phase 3 of 3. Re-derive the connector from the provider's live documentation. **Triggers:** - "validate the connector" - "check [provider] against the docs" - Phase 3 of the connector flow, after build-connector **What it does:** 1. Re-reads the provider's live documentation, resource by resource 2. Re-checks every action against those pages — paths, parameters, enums, pagination 3. Records discrepancies, omissions and documentation gaps in per-resource reports 4. Runs `gates/validate.js` and repairs what it reports, until the gate passes or stops converging **Key feature:** validates against the provider's docs, never against the research artifact that produced the connector — an independent, adversarial re-derivation. sdkVersion: 3.18.1 features: stepFunctions: [ browser_use, call_action, code_execution_lambda, code_execution_lambda, download_file, emit_event, map_fields, mcp_request, paginated_request, request, sign_jwt, soap_paginated_request, static_values, typecast, upload_binary, upload_file ] expressionFunctions: [ asString, capitalize, decodeBase64, decodeUri, dedupe, deltaFromNowMs, encodeBase64, encodeUri, formatDate, groupBy, hasPassed, hmacSha256, includes, includesSome, isoToUnix, join, keys, lower, md5, min, missing, nextAnniversary, now, padStart, parseJson, pluck, pluckNested, present, reduce, regexMatch, replace, sha256, slice, split, truncate, unixToIso, upper, urlParam, values, webhookEventsUrl, wrapXmlArray, yearsElapsed, zipObject ] inputTypes: [ boolean, number, object, string ] authTypes: [ custom, oauth2 ] paginationModes: [] validationRules: [] --- # Validate Config Phase 3 of **Research → Build → Validate**. ## The one rule that defines this phase **Go back to the provider's documentation itself.** Do not validate against `{{provider}}_research.json`. That artifact is what produced this connector — comparing the two proves only that the build was faithful to a possibly incomplete input. Any endpoint or parameter research missed would be certified correct. Research is the hypothesis. This is the adversarial check on it. ## What to produce One report per resource: ``` .connector-dev/{{provider}}/validation/{{provider}}_{{resource}}_doc_comparison.json ``` ```bash node ${CLAUDE_PLUGIN_ROOT}/scripts/gates/validate.js --schema ``` | Field | Meaning | |---|---| | `docsRead[]` | Documentation URLs you actually opened for this resource. **A report with an empty `docsRead` is rejected** — it is the evidence the check was independent | | `actionsVerified[]` | `{action, docUrl}` objects — the actionId plus the documentation page its endpoint appears on. List one only after reading that page, not because it looked reasonable. The per-action `docUrl` is what lets `V9` reject an endpoint that no documentation page describes — the shape a hallucinated action takes, since it is otherwise indistinguishable from a real one | | `discrepancies[]` | Where connector and docs disagree. `expected` is what the docs say, `actual` is what the connector does. **When you fix one, set `resolved: ""` on its entry in the same edit** — the gate then ignores it and the record survives as the audit trail. Never delete entries, and never leave a fixed one without `resolved` (it still counts as open). A bare `resolved: true` gets no exemption — say what changed | | `missingFromConnector[]` | Endpoints the docs describe that the connector does not implement — the omissions research did not catch, and the main reason this phase exists. Every entry here blocks V4: this field is for genuine omissions only, never for scope decisions | | `outOfScope[]` | `{method, path, reason}` — documented endpoints deliberately excluded from this connector's scope. The `reason` is mandatory: an entry without one is treated by V4 exactly like `missingFromConnector`. This is the only sanctioned place for scope exclusions — recording them in `missingFromConnector` "with a note" still blocks | | `documentationGaps[]` | Where the provider's own docs are silent. Record rather than guess; these reach the customer as known unknowns | ## What to check per action Path and method match **on a page you can cite** (record it as the action's `docUrl`) · every documented parameter present with right type, requiredness and **full** enum list · no parameters the connector invented · description matches documented behaviour including defaults and exclusions · pagination configured as documented · every id parameter has a producing action. Additionally, once per auth block: every scenario the block's setup/config **guide** describes must have a matching implementation — a guide that explains token rotation while the config has no exchange or refresh step for it is a defect in the config, not the guide. A guide describing a flow the connector cannot perform is worse than no guide, because it reads as a promise the runtime will break. ## The loop ```bash node ${CLAUDE_PLUGIN_ROOT}/scripts/gates/validate.js --provider {{provider}} ``` Checks: `V1` structure · `V2` independent re-derivation complete · `V3` no parameter discrepancies · `V4` no endpoint omissions · `V5` descriptions accurate · `V6` dependency and pagination coherence · `V7` scope reconciliation · `V8` gap ledger clean · `V9` every action cites the doc page its endpoint appears on · `V10` every published version records what changed — `info.changelog` on every version (the initial 0.1.0 included: "Initial release covering X"), a 1-2 line customer-facing `summary` overwritten each bump, optional `labels` each one of `auth`/`downstream-change`/`bug-fix`/`new-actions`; `releaseStage: ga` below 1.0.0 is blocking. Where a discrepancy is unambiguous, fix the connector and record it resolved. Where the documentation is genuinely unclear, record it under `documentationGaps` rather than guessing. A coverage gap found here often means research missed an endpoint — the fix belongs upstream, so rewinding to research is legitimate, bounded by `policy.rewindBudget`. If two consecutive rounds resolve nothing the phase is **exhausted**: the run ends `partial`, delivering the connector plus the gap list. ## What this phase does not prove A connector passing every check is **documentation-complete**, not **proven working**. It has never been executed. If the provider's docs are wrong or incomplete, the connector inherits that — which is why `documentationGaps` exists and why the customer report says so in words. ## Anti-patterns - ❌ Comparing against the research report — the tautology this phase exists to break - ❌ Listing an action in `actionsVerified` without reading its docs - ❌ Recording an `actionsVerified` entry without its `docUrl` — an uncited endpoint may be hallucinated - ❌ Writing a report with an empty `docsRead` - ❌ Guessing at an undocumented parameter instead of recording a documentation gap - ❌ Describing the result as "tested" or "working"