docs(m109-004): operator-UI scope migration — changelog + retire UZ-AUTH-021

[indykish]

Documents the M109_004 operator-UI scope migration (product repo branch feat/m109-004-cross-surface-hygiene).

Changes

• changelog.mdx — new Jul 03, 2026 entry: the operator dashboard (runner fleet + model catalogue) is now gated on the same resource:action scopes the API enforces, not a separate platform-admin flag; UZ-AUTH-021 retired → UZ-AUTH-022 (Insufficient scope); downward scope hierarchy (model:admin ⊇ model:read, runner:write ⊇ runner:read) applies on the dashboard as at the API.
• api-reference/error-codes.mdx — retire the UZ-AUTH-021 row (the backend registry never defined it; §4 removed the last minter, the dashboard's platform_admin gate) with a note pointing to UZ-AUTH-022.

Notes

• Changelog voice: headline states the change, load-bearing facts (error codes, scope names) kept, internal refactor (route method-check dedup) trimmed to one line.
• Pairs with product PR for feat/m109-004-cross-surface-hygiene (operator UI gates on scopes, platform_admin boolean removed).

🤖 Generated with Claude Code

Greptile Summary

Documents the M109_004 operator-UI scope migration: the runner fleet and model catalogue surfaces now enforce the same resource:action scopes as the API, replacing the old independent platform_admin boolean flag.

• changelog.mdx — inserts a Jul 03 2026 entry describing the scope-gated dashboard, the UZ-AUTH-021 → UZ-AUTH-022 transition, and the downward scope hierarchy; also closes a pre-existing missing </Update> tag on the earlier Jul 03 UI block.
• api-reference/error-codes.mdx — converts the UZ-AUTH-021 table row to a visible struck-through historical record with a redirect note to UZ-AUTH-022, which is already defined at line 67.

Confidence Score: 5/5

Documentation-only change with no runtime code; safe to merge.

Both files are purely documentation. The error-codes table correctly uses strikethrough to preserve discoverability of the retired code while redirecting readers to UZ-AUTH-022. The changelog entry accurately matches the stated product behaviour. The only structural fix (closing the missing </Update> tag) is a corrective improvement.

No files require special attention.

Important Files Changed

Filename	Overview
api-reference/error-codes.mdx	Retires the UZ-AUTH-021 row in-place with strikethrough formatting and a historical redirect note pointing to UZ-AUTH-022; UZ-AUTH-022 is already defined at line 67 in the Bearer-auth section.
changelog.mdx	Adds a Jul 03 2026 "Improvements / API" entry documenting the operator-UI scope migration and UZ-AUTH-021 retirement; also closes a pre-existing missing </Update> tag on the preceding Jul 03 UI entry.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Operator dashboard request] --> B{Before M109_004}
    A --> C{After M109_004}

    B --> D{platform_admin flag set?}
    D -- No --> E[403 UZ-AUTH-021\nPlatform-admin privileges required]
    D -- Yes --> F[Access granted\n- runner fleet\n- model catalogue]

    C --> G{Token has required\nresource:action scope?}
    G -- No --> H[403 UZ-AUTH-022\nInsufficient scope\ndetail: Requires scope X]
    G -- Yes --> I[Access granted\nmodel:admin ⊇ model:read\nrunner:write ⊇ runner:read]

    style E fill:#f88,color:#000
    style H fill:#faa,color:#000
    style F fill:#8f8,color:#000
    style I fill:#8f8,color:#000

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Operator dashboard request] --> B{Before M109_004}
    A --> C{After M109_004}

    B --> D{platform_admin flag set?}
    D -- No --> E[403 UZ-AUTH-021\nPlatform-admin privileges required]
    D -- Yes --> F[Access granted\n- runner fleet\n- model catalogue]

    C --> G{Token has required\nresource:action scope?}
    G -- No --> H[403 UZ-AUTH-022\nInsufficient scope\ndetail: Requires scope X]
    G -- Yes --> I[Access granted\nmodel:admin ⊇ model:read\nrunner:write ⊇ runner:read]

    style E fill:#f88,color:#000
    style H fill:#faa,color:#000
    style F fill:#8f8,color:#000
    style I fill:#8f8,color:#000

Loading

_{Reviews (3): Last reviewed commit: "docs(api): keep retired UZ-AUTH-021 visi..." | Re-trigger Greptile}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
agentsfleet	🟢 Ready	View Preview	Jul 3, 2026, 4:01 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.