Skip to content

docs(calibrations): document calibrations under Config Management - #269

Merged
ben-miru merged 35 commits into
mainfrom
claude/project-thread-d3dprn
Oct 26, 2026
Merged

ben-miru merged 35 commits into
mainfrom
claude/project-thread-d3dprn

Conversation

@bens-agent

@bens-agent bens-agent commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by bens-agent · project thread

Summary

Adds user-facing docs for calibrations (Linear ENG-1521, ENG-1694, ENG-1693) to the Config Management section, plus the Device API v0.2.3 reference:

  • Concepts > cfg-mgmt/concepts/components: what a component, role and aspect are, their properties, and how they're created on first report.
  • Concepts > cfg-mgmt/concepts/calibrations: what a calibration is, its properties, its append-only history, and where to view and report it.
  • Guides > cfg-mgmt/report-calibrations: an overview of reporting, components, roles and aspects, the POST /calibrations required and optional parameters, file formatting, the 200 { report_id, reported_at } response, and where to view a reported calibration.
  • Device API v0.2.3 reference: the published device/v0.2.3 spec as the new default dropdown, with a Calibrations group, and /references/device-api/latest now points at it. Curl and PowerShell samples come from api/add_unix_socket_curl.py and api/add_powershell_samples.py. Python samples are copied from v0.2.2 for existing operations. Event pages are the same as v0.2.2's. The calibration examples are hand-edited to the generic values from openapi#362.
  • Changelogs: Device API v0.2.3 (new POST /calibrations, upgrade to Python SDK v0.8.0) and Miru Agent v0.12.0 (October 25, 2026: calibrations, device time zone in uploads, resumable uploads, streamed upload bodies, stall and long-attempt retry fixes). The versions table and agent compatibility matrix include v0.2.3 → agent v0.12.0+, and the Python SDK table maps v0.2.3 → v0.8.x and above.
  • A DeviceApiLink helper, definition snippets for calibration and component, and new cspell words.

Sources

  • Device API spec device/v0.2.3 (mirurobotics/openapi), including openapi#352 for report_id and openapi#362 for generic examples.
  • Agent: #357, #379, #380 (calibrations), #356, #320, #321, #385, #391, #392, #393 (uploads), #398 (re-vendored device/v0.2.3), #400 (90-day calibration age limit).
  • Backend calsvc for what Miru rejects and the authz grants.
  • The Calibrations RFC for the dashboard design.

Before merging

  • Re-vendor the v0.2.3 reference once a device release includes openapi#362.
  • Upload the v0.2.3 spec to assets.mirurobotics.com/docs/openapi/device/v0.2.3.yaml so the changelog's download link works.
  • Run ./api/pull-stainless.sh to add the generated Python sample for POST /calibrations, now that Python SDK v0.8.0 is published.
  • Merge only once agent v0.12.0 ships, since this makes v0.2.3 the default and latest Device API reference.

Follow-ups

  • A product changelog entry at release.
  • config-types.mdx and upload-collections.mdx also say slugs can be up to 48 characters. They use the same 32-character check.

Test plan

  • ./scripts/lint.sh passes locally. mint validate needs network access it doesn't have here, so the Mintlify Deployment check covers the build.

https://claude.ai/code/session_01BZdUnBDLp2N3Xs78QCJPvD
https://claude.ai/code/session_01XYr7RpV2F8ueBW98eeY8W5


Generated by Claude Code

@bens-agent bens-agent changed the title docs(calibrations): add the Calibrations section docs(calibrations): document calibrations under Config Management Oct 23, 2026

Copy link
Copy Markdown
Collaborator Author

The audit check fails on a new advisory, not on this PR's changes. This PR only touches MDX, docs.json and cspell.json, and audit passed on the previous head at 19:16 UTC.

  • Advisory: GHSA-mrhx-c7xc-m3w5 (high), "Zod can exhaust memory while validating oversized constrained collections", via mint > @mintlify/cli > zod.
  • Why there's no simple override: every version below 4.6.6 is affected, and package.json pins zod to 3.24.0 through pnpm.overrides. Forcing zod 4 is a major-version change under the mint CLI.
  • No fix exists yet. Proposed patch for a separate PR on main, following the README's dependency-audit rules: add GHSA-mrhx-c7xc-m3w5 to pnpm.auditConfig.ignoreGhsas, or add its CVE to ignoreCves, then add a row to the README's "Ignored advisories" table: no patched 3.x release, local preview tooling only, remove once mint moves to zod ≥ 4.6.6. The other option is to override to zod >=4.6.6 if the Mintlify build still validates.

Re-running the job once to confirm.


Generated by Claude Code

ben-miru pushed a commit that referenced this pull request Oct 24, 2026
#270)

<!-- claude-projects-attribution: {"github_login":"miru-agents"} -->
_Requested by **bens-agent** · [project
thread](https://claude.ai/code/project/chan_01RNCMaVSP1K69BTB8Xydgqo?thread=cmsg_01RNCMaVSP1K69BTB8XydgqoMH4RN553gB5vAkQuRoNjtW)_

## Summary

`audit` is red on every branch because of advisories published in the
last day. It first failed on #269, whose diff touches no dependencies.
All of them come through `mint`'s local preview and build tooling, not
anything published to readers.

**Overridden to patched releases** (lockfile regenerated):

- `body-parser` `>=2.3.0` → `>=2.4.0`:
[GHSA-27r3-jxmh-p828](GHSA-27r3-jxmh-p828)
(high), via `mint > @mintlify/cli > @mintlify/previewing > express`.
- `fast-uri` `>=3.1.5 <4` → `>=3.1.9 <4`:
[GHSA-w74x-v6f9-j3xg](GHSA-w74x-v6f9-j3xg),
[GHSA-wjr9-j795-jxcr](GHSA-wjr9-j795-jxcr),
[GHSA-xhq7-xmqj-769h](GHSA-xhq7-xmqj-769h)
and
[GHSA-333x-w4r6-6crp](GHSA-333x-w4r6-6crp),
via `@mintlify/common > @asyncapi/parser > ajv`. 3.1.9 stays within the
existing `<4` bound.

**Ignored:**
[GHSA-mrhx-c7xc-m3w5](GHSA-mrhx-c7xc-m3w5)
(zod, high), recorded in the README's **Ignored advisories** table:

- Every `zod` below `4.6.6` is affected.
- `@mintlify/validation` pins `zod` `3.24.0` exactly (with
`zod-to-json-schema` 3.20.4, a zod 3 API), in both the locked `0.1.916`
and the latest `0.1.943`. The repo's `"zod": "3.24.0"` override keeps
the tree on that version. Forcing zod 4 would put the code `pnpm run
validate` relies on onto a major version it doesn't support, so no
override clears it.
- The advisory has no CVE, so it goes in `pnpm.auditConfig.ignoreGhsas`
rather than `ignoreCves`. The README's audit paragraph now names both.

## Precedent

Follows the README's dependency-audit rules and the existing
`pnpm.overrides` / `auditConfig` entries. The lockfile was regenerated
with `pnpm install --lockfile-only` on pnpm 10.34.7, which keeps the
lockfile's existing `libc` fields. Running it on the pinned 10.17.0
drops them.

## Test plan

- CI: `audit` passes, and `lint` (including `pnpm run validate`) still
passes with the bumped `body-parser` and `fast-uri`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01BZdUnBDLp2N3Xs78QCJPvD

---------

Co-authored-by: Claude <noreply@anthropic.com>
Comment thread docs/cfg-mgmt/concepts/components.mdx
Comment thread docs/cfg-mgmt/concepts/calibrations.mdx Outdated
Comment thread docs/cfg-mgmt/concepts/calibrations.mdx Outdated
Comment thread docs/cfg-mgmt/concepts/calibrations.mdx Outdated
Comment thread docs/cfg-mgmt/concepts/calibrations.mdx Outdated

Copy link
Copy Markdown
Collaborator Author

The audit check failed on 2f188a4 before it audited anything. Corepack's download of pnpm 10.17.0 from registry.npmjs.org was cut off with ECONNRESET, so this is a runner network blip, not this PR. A local check of the lockfile against npm's advisories finds only the already-ignored zod advisory. I can't re-run jobs from here (403), so the check needs a manual re-run, or it will re-run on my next push.


Generated by Claude Code

Comment thread docs/cfg-mgmt/concepts/calibrations.mdx
Add a Calibrations section next to Data Uploads: an overview, concept
pages for components and calibrations, and guides for reporting
calibrations through the Device API and viewing them in the dashboard.
Screenshots and a few unreleased details are marked [PLACEHOLDER].

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BZdUnBDLp2N3Xs78QCJPvD
Move the calibration concept pages into Config Management > Concepts >
Calibrations, folding the section overview into the calibrations page,
and move the Report calibrations guide into the Config Management
guides. Drop the View calibrations guide.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BZdUnBDLp2N3Xs78QCJPvD
The backend validates slugs with core's ugc.SanitizeSlug, whose regex
allows at most 32 characters.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BZdUnBDLp2N3Xs78QCJPvD
Move components to cfg-mgmt/concepts/components and calibrations to
cfg-mgmt/concepts/calibrations, both directly under Config Management >
Concepts, per review.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BZdUnBDLp2N3Xs78QCJPvD
Per review.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BZdUnBDLp2N3Xs78QCJPvD
Per review.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BZdUnBDLp2N3Xs78QCJPvD
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BZdUnBDLp2N3Xs78QCJPvD
Regroup the concept pages to match the config type and config
instance pages: definition, properties, then one short section per
action. Cut repeated explanations and fold the guide's upload,
rejection and duplicate sections into Response, Errors and Dropped
calibrations.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BZdUnBDLp2N3Xs78QCJPvD
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XYr7RpV2F8ueBW98eeY8W5
ben-miru and others added 2 commits October 25, 2026 23:45
A 200 means the agent saved the calibration. It shows on the device's Calibrations page after the upload reaches Miru.

Co-authored-by: Cursor <cursoragent@cursor.com>
The entry no longer states the 1,000-calibration queue limit or the 30-minute retry-budget exception.

Co-authored-by: Cursor <cursoragent@cursor.com>
ben-miru and others added 2 commits October 25, 2026 23:50
The Calibrations page is the place to find a device's reports. The note that a 200 only means the agent saved it is already in the response section.

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Comment thread docs/cfg-mgmt/report-calibrations.mdx
Comment thread docs/cfg-mgmt/report-calibrations.mdx Outdated
Comment thread docs/cfg-mgmt/report-calibrations.mdx Outdated
Comment thread docs/cfg-mgmt/report-calibrations.mdx Outdated
Comment thread docs/changelog/device-api.mdx
Comment thread docs/docs.json
@github-actions

Copy link
Copy Markdown
Contributor

AI review: approve for 35d4f1d

This PR changes only documentation. It adds pages for components, calibrations and the report-calibrations guide, vendors the Device API v0.2.3 spec, adds changelog entries, and updates the nav, the latest redirect and cspell. Nothing touches code, CI, access control or data retention. The new DeviceApiLink helper uses the same pattern as PlatformApiLink. The v0.2.3 nav groups match the spec's tags, and the guide's request fields (component, role, aspect, serial_number, content.format/data) match CreateCalibrationRequest. I left six non-blocking inline comments: (1) the guide recommends the Python SDK, which can't report calibrations yet; (2) the "File formatting" section mentions an editor that nothing else explains; (3) and (4) two small grammar fixes; (5) Python SDK v0.8.0 in the migration steps looks like a guess; (6) merging moves /references/device-api/latest to v0.2.3 and lists it as released, so this should wait until agent v0.12.0 and the spec asset ship, as the PR's own "Before merging" list says. Earlier review threads are all addressed in the current code.

Review run

… nits

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XYr7RpV2F8ueBW98eeY8W5
Comment thread docs/cfg-mgmt/concepts/components.mdx Outdated
Comment thread docs/cfg-mgmt/concepts/calibrations.mdx
@github-actions

Copy link
Copy Markdown
Contributor

AI review: approve for 40e14fc

I'm approving 40e14fc. The PR only touches docs, the vendored Device API spec, nav, the latest redirect and cspell. It changes no code, CI, access control or data retention.

The fixes from the last round are in. The SDK compatibility table now maps API v0.2.3 to SDK v0.8.x and above, and API v0.2.2 to SDK v0.7.x. The guide names the Miru dashboard, and the grammar fixes are applied. The Python SDK recommendation is settled now that SDK v0.8.0 is published.

The guide's request fields match CreateCalibrationRequest: component, content.format, content.data, and the optional role, aspect and serial_number. Its response matches CreateCalibrationResponse. The new DeviceApiLink helper builds a link through the latest redirect, which now points at v0.2.3.

I left two non-blocking nits:

  1. The roles description on the components page has a grammar problem.
  2. The "View calibrations" section on the calibrations page links to the page itself.

A reminder about merge timing, as noted in the earlier thread: merging makes v0.2.3 the default and latest Device API reference. Wait until agent v0.12.0 and the v0.2.3 spec asset have shipped.

Review run

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XYr7RpV2F8ueBW98eeY8W5
@github-actions

Copy link
Copy Markdown
Contributor

AI review: approve for 1fe00a2

Approving 1fe00a2. Since 40e14fc, the only changes are the two nits from the last round, and both are fixed. The roles description on the components page now reads correctly. The "View calibrations" section on the calibrations page no longer links to itself. The PR still touches only docs, the vendored Device API v0.2.3 spec, nav, the latest redirect and cspell. It changes no code, CI, access control or data retention, and all earlier threads are settled. One minor point: the PR description still lists 401/413/422/507 error and dropped-calibration sections, but the guide no longer has them, so the description should be updated. As noted in an earlier thread, merging makes v0.2.3 the default and latest Device API reference. Wait until agent v0.12.0 and the spec asset have shipped.

Review run

@ben-miru ben-miru left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@ben-miru
ben-miru merged commit a9895b9 into main Oct 26, 2026
8 checks passed
@ben-miru
ben-miru deleted the claude/project-thread-d3dprn branch October 26, 2026 07:43
ben-miru pushed a commit that referenced this pull request Oct 26, 2026
## Summary

Fills the gaps left after the agent `v0.12.0` changelog entry
(#269), checked against every agent commit from
`v0.11.1` to `v0.12.0`.

- **Versions table** (`developers/agent/versions.mdx`): adds `v0.12.x`
as supported, released 2026-10-26. Earlier releases added their row the
same way (#246).
- **Changelog date**: `v0.12.0` was tagged on 2026-10-26
(mirurobotics/agent#404 merged then), not October 25.
- **Changelog items that were missing:**
- A failed upload attempt that ran 30 minutes or more is retried without
counting, so long uploads aren't dropped after about 30 hours
(mirurobotics/agent#393).
- The 7-day limit on a failing upload now applies to every error, not
only network errors (mirurobotics/agent#365).
- **Report calibrations guide**: documents the calibration queue limits:
up to 1,000 unsent reports, kept 90 days, and the `507 Insufficient
Storage` / `calibration_buffer_full` response apps need to handle when
it's full (mirurobotics/agent#357, mirurobotics/agent#400). Values are
from `agent/src/calibrations/` at `v0.12.0`.

## Reviewer notes

- Left out as not user-facing: the shared backend-anchored clock
(mirurobotics/agent#326, nothing reads it yet), the combined
SHA-256/CRC32C read (mirurobotics/agent#399, unused yet), and dropping
the unused `sigv4a` feature (mirurobotics/agent#387).
- The Device API reference spec
(`references/device-api/v0.2.3/api.yaml`) lists no error responses for
any endpoint, and it's vendored from `openapi`, so the `507` isn't added
there.
- No product changelog entry for calibrations: that's a product launch
covering the dashboard too, which I can't verify from here.
- No GitHub release exists yet for `v0.12.0`; the tag is pushed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_011jeeax7ma8kfs8CEyhk8Cj

---------

Co-authored-by: Claude <noreply@anthropic.com>
ben-miru pushed a commit that referenced this pull request Oct 29, 2026
… notes (#288)

<!-- claude-projects-attribution: {"github_login":"miru-agents"} -->
_Requested by **bens-agent** · [project
thread](https://claude.ai/code/project/chan_015imaa8aZrnubYZcZCvjeHx?thread=cmsg_015imaa8aZrnubYZcZCvjeHx6HTArhtGtMpoitqDXkyMq7)_

> [!IMPORTANT]
> **Do not merge yet.** This documents three releases that haven't
shipped: Miru Agent `v0.12.3`, Device API `v0.2.4` and the next Python
device SDK. Merge only after all three are out and the checklist under
**Before merging** is done. Merging early would make `v0.2.4` the
default and `latest` Device API reference before any agent serves it.

## Summary

Documents `reported_by` on calibration reports (mirurobotics/agent#409,
openapi#386 and openapi#395) and the `csv` calibration format that comes
with it.

- **Device API `v0.2.4`**: `POST /calibrations` takes an optional
free-text `reported_by` (at most 255 characters), and `content.format`
accepts `csv`. Those are the only schema changes between `device/v0.2.3`
and `device/v0.2.4`.
- **Agent `v0.12.3`**: serves Device API `v0.2.4`, forwards
`reported_by` to Miru and accepts `csv` calibrations. Calibrations
queued before the upgrade upload with no reporter.
- **Python SDK**: `v0.9.x` is listed as the SDK for API `v0.2.4`. **That
version number is an assumption** (see Before merging).

## Changes

- `docs/references/device-api/v0.2.4/api.yaml`: the `device/v0.2.4`
release asset (`device.yaml`), with the `x-codeSamples` from `v0.2.3`
carried over unchanged. It was first built from `device/v0.2.4-beta.2`;
the final tag differs only in its `x-git-commit` and `x-build` metadata,
which a later commit updates. The `component` example is hand-edited
from `arm` to `kuka-arm`, as `v0.2.3` already does, because the spec
still has `arm`.
- `docs/references/device-api/v0.2.4/events/`: copied from `v0.2.3`.
Events didn't change.
- `docs/docs.json`: new `v0.2.4` dropdown, the new default, and
`/references/device-api/latest` now redirects to `v0.2.4`.
- `docs/changelog/device-api.mdx`: `v0.2.4` entry covering the
`reported_by` and `csv` additive changes, plus migration steps (agent
`v0.12.3+`, Python SDK `v0.9.0+`).
- `docs/changelog/agent.mdx`: `v0.12.3` entry.
- `docs/developers/device-api/versions.mdx`: `v0.2.4` row in the
supported versions table. In the agent compatibility matrix, `v0.2.4`
maps to `v0.12.3+` and `v0.2.3` to `v0.12.0 - v0.12.2`.
- `docs/developers/device-api/sdks.mdx`: `v0.2.4` maps to `v0.9.x` and
above, and `v0.2.3` to `v0.8.x`.
- `docs/cfg-mgmt/report-calibrations.mdx`: adds the optional
`reported_by` parameter and lists `csv` in `content.format`. Both note
that they need agent `v0.12.3`.
- `docs/cfg-mgmt/concepts/calibrations.mdx`: adds a `reported by`
property and the `csv` format.

## Precedent

- The Device API reference, changelog and version tables follow
#269, the most recent device release (`v0.2.3`). Before
that, #246 (`v0.2.2`). The `v0.2.4` dropdown is a copy of `v0.2.3`'s
with the version swapped.
- The agent entry follows `v0.11.1` in #246, the last agent release that
upgraded the Device API: a one-line summary, the Device API changelog
link and **Features**. The versions table is unchanged, as in #281,
because `v0.12.x` is already listed.
- The vendored spec is built the way `v0.2.3`'s was: the release asset
is dumped with the same representer as `api/add_unix_socket_curl.py`.
Rebuilding `v0.2.3` from its release asset this way reproduces the
committed file byte for byte, apart from #269's hand edits to the
examples.

## Before merging

- [x] Tag `device/v0.2.4` in mirurobotics/openapi and re-vendor. Done:
the final `device.yaml` differs from beta.2 only in release metadata
(`x-git-commit` now `13405ec`, `x-build`), which this PR now carries.
- [ ] Release agent `v0.12.3`. It vendors the final `device/v0.2.4` once
mirurobotics/agent#410 merges.
- [ ] Release the Python device SDK for `v0.2.4`, confirm its version,
and fix `v0.9.0` / `v0.9.x` in `changelog/device-api.mdx` and
`developers/device-api/sdks.mdx` if it differs. PyPI's latest is
`0.8.1`.
- [ ] Replace the placeholder date **October 29, 2026** (`2026-10-29`)
with the real release dates in `changelog/device-api.mdx`,
`changelog/agent.mdx` and the `versions.mdx` table.
- [ ] Upload the `v0.2.4` spec to
`assets.mirurobotics.com/docs/openapi/device/v0.2.4.yaml` so the
changelog's download link works.
- [ ] Optionally, after the SDK ships, run `./api/pull-stainless.sh` to
add the generated Python sample for `POST /calibrations`. `v0.2.3`
doesn't have one either.

## Reviewer notes

- **`csv` is new in this release**: it isn't in `device/v0.2.3`, and
agent#409 adds `InstanceFormat::Csv`. #278 left calibrations out of the
csv docs for that reason.
- **Format check sentence**: the calibrations concept page said Miru
checks that `json`, `jsonc` and `yaml` content parses. Backend#1037, in
`v0.11.30`, also checks `xml` and `csv`, so the sentence now lists all
five. The `xml` part is a small correction outside this release.
- **External users aren't documented.** Miru records `reported_by` as an
external user of the workspace, which can be linked to a Miru user. No
public docs page or dashboard UI exists for that yet, so the docs only
say the field is free text that names the reporter.
- **Example value**: the docs use `Jane Doe`. The spec's example is
`Benjamin Smidt`, and it's left as is in the vendored YAML.
- **Code samples**: the curl and PowerShell samples for `POST
/calibrations` are `v0.2.3`'s, which don't set `reported_by`. That's
deliberate because the field is optional.
- No backend version is documented, since the docs don't track backend
versions.

## Test plan

- CI on the pushed head (lint, spelling, OpenAPI check, Mintlify build).
Nothing was run locally.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01XHScKYffhVuSntTMwJK7xK

---------

Co-authored-by: Claude <noreply@anthropic.com>

This branch was successfully deployed

1 active deployment
staging - docs — 1fe00a27 Deployed Oct 26, 2026 by mintlify[bot]
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.

3 participants