docs: Avocado Connect API reference; remove legacy web API remnants

[nicksinas]

Description

Replaces the last remnants of the deprecated console.peridio.com web API and documents the new Avocado Connect API under Developer Reference.

Removed (legacy web API):

• Old OpenAPI specs (peridio-admin-openapi*.yaml, peridio-device-openapi.yaml) — the only remaining console.peridio.com references — plus redocly.yaml
• Redocly lint steps from CI and scripts/checks.sh; unused redocusaurus / @redocly/cli deps (~95 packages) and leftover .redocusaurus CSS
• Adds yaml as an explicit dependency (previously only installed transitively via the removed redoc packages, but required by sync-references.js)

Added (Avocado Connect API):

• New Avocado Connect API section at /developer-reference/avocado-connect-api/ — overview + 10 resource-group pages covering all 76 endpoints, expanding in the sidebar like the Varlink API section
• Pages are generated from the committed OpenAPI spec (src/openapi/avocado-connect-openapi.json, sourced from the connect monorepo) via npm run build-connect-api
• Each endpoint documents parameters, request-body fields, and responses, plus a sample curl request and a synthesized JSON response body (spec-provided examples win; enums/formats/property-name hints fill the rest)
• All pages opt into the Copy for LLM button

[jasontwong]

Automated review found a confirmed data-loss bug in the doc generator plus a CI gap. Details inline.

[Copilot]

Pull request overview

This PR migrates the Developer Reference docs away from the legacy console.peridio.com web API/OpenAPI tooling and adds a new generated reference section for the Avocado Connect API under /developer-reference/avocado-connect-api/.

Changes:

• Removes deprecated Redocly/Redocusaurus configuration, specs, and CI linting steps associated with the legacy web API.
• Adds a committed Avocado Connect OpenAPI spec plus a generator script (npm run build-connect-api) that produces endpoint + schema reference pages.
• Integrates the new Avocado Connect API docs into the Developer Reference sidebar and adds a CI drift-check to ensure generated pages stay in sync.

Reviewed changes

Copilot reviewed 19 out of 23 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/src/css/custom.css	Removes leftover Redocusaurus table styling now that Redoc-based pages are gone.
src/sidebars-guides.js	Adds “Avocado Connect API” category with autogenerated items under Developer Reference.
src/scripts/build-connect-api.js	New generator that turns the committed Connect OpenAPI spec into Docusaurus pages (per-tag grouping, examples, object references).
src/openapi/avocado-connect-openapi.json	Committed source OpenAPI spec used to generate the Connect API docs.
src/docs-guides/avocado-connect-api/overview.md	New hand-maintained overview for auth, conventions, pagination, and errors.
src/docs-guides/avocado-connect-api/authentication-tokens.md	Generated Connect API reference page for authentication/token endpoints.
src/docs-guides/avocado-connect-api/devices.md	Generated Connect API reference page for device management endpoints.
src/docs-guides/avocado-connect-api/projects-cohorts.md	Generated Connect API reference page for projects/cohorts and access-control endpoints.
src/docs-guides/avocado-connect-api/runtimes.md	Generated Connect API reference page for runtime/artifact endpoints.
src/docs-guides/avocado-connect-api/deployments.md	Generated Connect API reference page for deployments and rollout tracking endpoints.
src/docs-guides/avocado-connect-api/remote-access.md	Generated Connect API reference page for WireGuard tunnel policy/tunnel endpoints.
src/docs-guides/avocado-connect-api/provisioning.md	Generated Connect API reference page for claim token provisioning endpoints.
src/docs-guides/avocado-connect-api/signing-trust.md	Generated Connect API reference page for TUF signing/trust management endpoints.
src/docs-guides/avocado-connect-api/events-webhooks.md	Generated Connect API reference page for events aggregates + webhooks endpoints.
src/docs-guides/avocado-connect-api/administration.md	Generated Connect API reference page for admin/organization management endpoints.
src/redocly.yaml	Removes legacy Redocly configuration (no longer needed).
src/openapi/peridio-device-openapi.yaml	Removes legacy Peridio Device API OpenAPI spec.
src/package.json	Drops Redocly/Redocusaurus deps, adds yaml as a direct dependency, and adds the build-connect-api script.
scripts/checks.sh	Replaces OpenAPI linting with a generator + drift check to ensure committed Connect API docs match the spec.
.github/workflows/build-and-deploy.yml	Removes the Redocly lint step from CI workflow.

Files not reviewed (1)

• src/package-lock.json: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 23 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• src/package-lock.json: Generated file

Suppressed comments (2)

src/scripts/build-connect-api.js:291

• The generated curl examples set an Authorization header value that omits/obscures the required Bearer scheme (rendered as Authorization: ****** in the generated docs). The examples should clearly show the Authorization: Bearer <token> shape so users copy a valid header without leaking any real secret.

  if (requestSample === null) {
    lines.push('  -H "Authorization: Bearer $AVOCADO_TOKEN"')
  } else {
    lines.push('  -H "Authorization: Bearer $AVOCADO_TOKEN" \\')
    lines.push('  -H "Content-Type: application/json" \\')

src/scripts/build-connect-api.js:267

• sampleFromSchema() currently emits all object properties in synthesized examples. That causes response examples to include fields explicitly documented in the OpenAPI schema as “returned only on create” (e.g., ClaimToken.token, OrgApiToken.token, WebhookEndpoint.secret), which contradicts the spec text and makes list/show examples look like they return sensitive values.

      const out = {}
      for (const [key, prop] of Object.entries(resolved.properties || {})) {
        const value = sampleFromSchema(prop, seen, depth + 1, key)
        if (value !== null) out[key] = value
      }

[nicksinas]

Re: the two suppressed comments in Copilot's latest review:

1. curl Authorization header rendered as ****** — not reproducible; appears to be Copilot's own secret-masking of its context. The generated markdown and the built HTML both render -H "Authorization: Bearer $AVOCADO_TOKEN" verbatim (see any Example request block).

2. Create-only secrets in non-create examples — valid, fixed in 3ac6513. ClaimToken.token, OrgApiToken.token, and WebhookEndpoint.secret are documented "returned only on create"; synthesized response examples now include such fields only for 201 create responses (all creates in this spec return 201, nothing else does).

[Copilot]

Pull request overview

Copilot reviewed 19 out of 23 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• src/package-lock.json: Generated file

Suppressed comments (1)

src/scripts/build-connect-api.js:147

• After removing the unused requiredByParent parameter from flattenProperties, this call site still passes an extra [] argument and will no longer match the function signature.

  flattenProperties(schema, '', [], linkable, rows, 0)

[Copilot]

Pull request overview

Copilot reviewed 19 out of 23 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• src/package-lock.json: Generated file

Suppressed comments (1)

src/scripts/build-connect-api.js:121

• requiredByParent is never read inside flattenProperties(), and the recursive calls pass values that are also unused. This makes the signature misleading and suggests required-ness is being propagated when it isn't.

Either remove the parameter entirely (and update call sites) or, if it’s intentionally reserved for future use, prefix it with _ to make the intent explicit.

// Flatten an object schema into table rows with dotted field paths.
function flattenProperties(schema, prefix, requiredByParent, linkable, rows, depth) {
  if (!schema || depth > 4) return

[Copilot]

Pull request overview

Copilot reviewed 19 out of 23 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• src/package-lock.json: Generated file

Suppressed comments (2)

src/scripts/build-connect-api.js:33

• deref() assumes every $ref is a resolvable local ref. If a ref is malformed or missing (or a non-#/... ref ever appears), the current loop will fail with a generic Cannot read properties of undefined error, which makes it harder to identify the broken ref when generation fails in CI. Consider validating local refs and throwing a descriptive error that includes the original $ref.

function deref(node) {
  if (node && node.$ref) {
    const parts = node.$ref.replace(/^#\//, '').split('/')
    let target = spec
    for (const part of parts) target = target[part]

scripts/checks.sh:18

• git status pathspecs are safer when separated from revisions via -- (prevents edge-case ambiguity if a path looks like a rev). This also matches common Git scripting practice.

if [ -n "$(git status --porcelain docs-guides/avocado-connect-api)" ]; then
  echo "error: generated Connect API docs are out of sync with the spec." >&2
  echo "Run 'npm run build-connect-api' in src/ and commit the result:" >&2
  git status --porcelain docs-guides/avocado-connect-api >&2

[jasontwong]

LGTM — no blocking issues found. The allOf field-drop bug and the missing CI validation (both flagged in the prior review) are fixed: checks.sh now regenerates the docs and fails on drift, and I independently ran the generator against the committed spec and confirmed the output is byte-identical. Remaining findings (union-type array label edge case, heading-slug collision guard, minor re-traversal in collectSchemaRefs) are latent/dormant — not triggered by the current spec — so treating them as non-blocking suggestions.