Skip to content

docs(api): make the reference examples internally consistent - #248

Merged
ysyneu merged 5 commits into
feat/api-review-auto-fix-20260806from
docs/api-example-fixes
Aug 6, 2026
Merged

docs(api): make the reference examples internally consistent#248
ysyneu merged 5 commits into
feat/api-review-auto-fix-20260806from
docs/api-example-fixes

Conversation

@ysyneu

@ysyneu ysyneu commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

Every item here is a contradiction a reader can see on the rendered page.

Example Was Now
ServiceMap fleet request filters degraded/stale; response returns one active host, while coverage says returned: 2 and counts one degraded + one stale two hosts, one degraded and one stale — matching both the filter and every count
preset-severity create returns priority: 3 for a rule the list example shows at priority: 1 priority: 2, and list now orders by creation, so priority and creation order agree
preset-severity history/list total: 4 beside 2 items; the version=1 "empty" snapshot is timestamped after a rule that already existed three snapshots on one timeline (two creates, then a disable), total: 3, each snapshot holding the state its own call was about to change
error-ingestion history/list total: 3 beside 1 item; the snapshot already carried the update it was supposed to precede two snapshots, total: 2, the pre-update state where it belongs
resource/info order_id encodes 2026-06-15 for a resource created_at 2025-06-15; billing window not anchored at created_at order id matches the creation date; window is the 30-day span from created_at the field descriptions promise
example addresses private-range RFC 5737 documentation range, as this corpus already uses elsewhere

No downstream release needed. Examples feed no code generation: the CLI reads only request-side examples (internal/cmd/cligen/main.go:461) and none of those change here. Verified by regenerating the SDK against this spec — only the vendored JSON differs, zero generated Go changes — and the SDK's spec-example round-trip test passes against the new payloads.

Structural verification is unchanged and green: 12 specs parse, EN/ZH operation and schema key sets equal, nav allow-list agrees with the specs both ways, 654 catalog links match their x-mint.href, and counts stay 327 across the declared total, per-module sums, table rows, and the specs themselves.

ysyneu added 5 commits August 6, 2026 02:19
Covers product changes from the past five days across AI SRE, Monitors and RUM.

- ai-sre/artifacts: document public (anonymous) artifact sharing — account-only
  vs public-link visibility, the content-snapshot model, update/revoke, and the
  16 MiB cap; broaden publishable file types well beyond HTML/Markdown; correct
  the card type icon and title truncation
- ai-sre/environments: add the degraded Runner status, its two detection
  signals and recovery paths, and note that degraded Runners stay selectable
- ai-sre/knowledge: replace the extension allowlist with the content-based
  UTF-8 text rule; narrow the document-conversion list to the modern Office
  formats and call out legacy .doc/.xls/.ppt rejection
- ai-sre/sessions: subagent/A2A child sessions are viewable read-only through a
  shared root link (no fork); forked dispatches always show as interrupted;
  HTML attachments
- ai-sre/insight: entry kind scheduled -> automation, matching sessions.mdx
- monitors/targets: new ServiceMap page (topology canvas, node/dependency
  detail fields, unresolved endpoints, host list, evidence quality)
- monitors/quickstart: the data source type picker lists only configured types
- rum/error-tracking: the Issue count on an application card deep-links into
  the error tracking list with the card's own scope
- changelog: new 2026-08-06 entry covering the artifact public-link sharing
  mode (snapshot semantics, update/revoke, 16 MiB cap), the broadened set of
  publishable artifact types, and the ServiceMap topology feature
- monitors/targets/servicemap: mark the page as Beta and state the
  monit-agent eBPF dependency up front
…0806-014513

docs: sync doc-review findings (2026-08-06)
…0260806

docs(api): publish ServiceMap and RUM rule endpoints
Each of these contradicted itself on the rendered page:

- ServiceMap fleet: the response showed a single `active` host for a request
  filtering on `degraded`/`stale`, while `coverage` claimed two returned and
  counted one of each. Now two hosts that match both the filter and the counts.
- Preset-severity: the rule returned by `create` carried a priority the `list`
  example contradicted, and the history example's "empty" snapshot was
  timestamped after a rule that already existed. Rebuilt as one timeline — two
  creates and a disable, three snapshots, each holding the state the call that
  wrote it was about to change.
- History `total` now equals the number of items returned, in both the
  preset-severity and error-ingestion examples.
- Resource info: the order id encoded a date a year after the `created_at` of
  the resource it provisioned, and the billing window was not the 30-day span
  anchored at `created_at` that the field descriptions promise.
- Example addresses now use the RFC 5737 documentation range, which the rest of
  the corpus already uses, instead of private-range ones.

Examples feed no code generation — only the request-side ones reach the CLI, and
none of those change here — so the generated SDK and CLI are unaffected.
@ysyneu
ysyneu merged commit 332fac9 into feat/api-review-auto-fix-20260806 Aug 6, 2026
1 check passed
@ysyneu
ysyneu deleted the docs/api-example-fixes branch August 6, 2026 15:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant