docs(m160): login saves a durable credential, one per computer

[indykish]

Intent

Records M160_002 and M136_001, merged as agentsfleet#600 (92589429b). Login used to save the browser session token it recovered, valid for about a minute; it now saves a durable afc_ credential minted through POST /v1/cli-credentials.

Every claim below was read from source on agentsfleet main, not from the specification or the Pull Request (PR) body.

Changelog

One <Update> for Aug 14, 2026, tagged Breaking / Security / What's new. Three breaking facts an operator must act on: agentsfleet login --token is gone along with piped input, agentsfleet logout no longer ends a dashboard session, and OIDC_PROVIDER=custom is refused at boot.

Pages corrected

Page	Was wrong	Source checked
cli/configuration.mdx	"The login command accepts --token, piped input, or browser approval"; the Uniform Resource Locator (URL) order named a .env.local rung	cli/src/cli.ts resolveGlobalApiUrl, cli/src/program/cli-tree.ts
cli/agentsfleet.mdx	login "or supplied token"; logout "revokes every active session"	cli/src/commands/auth-logout.ts
api-reference/introduction.mdx	"The login flow saves a short-lived JSON Web Token (JWT)"	cli/src/commands/login-exchange.ts
docs.json	the three /v1/cli-credentials operations were unregistered	public/openapi/paths/cli-credentials.yaml

cli/configuration.mdx gains the DEPLOYMENT_UNKNOWN refusal: a saved credential recording no server, dialed at a server nobody named, exits 1 before anything is sent. logout and doctor stay reachable.

Catch-up sweep

Regenerating api-reference/error-codes.mdx with make gen-error-codes pulled in more than this milestone's three rows, because the page had not been regenerated since 0.25.0:

• dropped UZ-FLEETKEY-001; added UZ-AGT-015, UZ-EXEC-017, UZ-REPAIR-013, UZ-REPAIR-014
• UZ-APIKEY-001 now points at POST /v1/api-keys instead of the retired POST /v1/workspaces/{ws}/fleet-keys
• UZ-GRANT-001 and the UZ-REPAIR-010/011/012 rows reworded to their current registry text

The retired fleet-key surface follows from the same read: fleetkey:read and fleetkey:write are absent from src/agentsfleetd/auth/scopes.zig, and agentsfleet fleet-key create|list|delete have no command, no route, and no OpenAPI path. Both were documented. approval:read is included by approval:resolve per scopes.zig, which the table said was None.

Verification

make lint — Documentation check passed, ✓ openapi drift check clean, link check clean. gitleaks clean.

Session notes

• product_version stays 0.25.0. scripts/check-documentation.py hardcodes EXPECTED_VERSION = "0.25.0" and rejects anything else, while make gen-error-codes stamps the agentsfleet repository version (0.26.2) into the generated front matter. Every regeneration will now fail this repository's own checker until the pin moves. Bumping it is a repository-wide decision across 25 pages, so it is left for Indy rather than folded in here. verified moves to 2026-08-14 on the five pages actually checked.
• One registry defect fixed upstream, not here. UZ-AUTH-024 told operators to run agentsfleet cli-credentials list, which is not a command in the client — only the Hypertext Transfer Protocol (HTTP) path exists. Its detail also broke DOC-02 (28-word sentence) and DOC-03. The wording fix belongs in src/agentsfleetd/errors/error_entries.zig; it is held as a patch and needs its own small PR against agentsfleet main, since #600 is already merged.
• Scope table is corrected, not completed. schedule:read, schedule:write, and stream:read exist in scopes.zig and are still absent from api-reference/scopes.mdx. Enumerating them wants its own verification pass over which routes each gates.
• agentsfleet#601 (M164) carries an Aug 13 changelog entry on chore/m164-delete-the-free-trial-changelog. Whichever merges second takes a small conflict at the top of changelog.mdx.

🤖 Generated with Claude Code

Greptile Summary

The PR updates the documentation for durable per-computer CLI credentials and aligns the documented product version with 0.26.2.

• Documents browser-only login, durable afc_ credentials, revised logout semantics, server affinity, and DEPLOYMENT_UNKNOWN.
• Registers CLI credential endpoints and refreshes API scopes and error-code documentation.
• Updates the documentation checker, its tests, and all linted page front matter to product version 0.26.2.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
cli/configuration.mdx	Documents browser-only authentication, durable credential storage, API URL precedence, and the unknown-deployment refusal.
cli/agentsfleet.mdx	Updates login and logout semantics and removes retired fleet-key commands from the command reference.
api-reference/introduction.mdx	Replaces the short-lived JWT description with the durable CLI credential lifecycle.
api-reference/error-codes.mdx	Regenerates the error registry for 0.26.2, including CLI credential and repository-repair errors.
api-reference/scopes.mdx	Removes retired fleet-key scopes and records that approval resolution includes approval read access.
docs.json	Adds the credential creation and deletion operations to API navigation.
scripts/check-documentation.py	Advances the required documentation product version to 0.26.2.
scripts/test-documentation.py	Updates the valid-page fixture to match the new required product version.
changelog.mdx	Adds the breaking, security, and operational details of durable per-computer CLI credentials.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Browser login] --> B[Short-lived session]
  B --> C[POST /v1/cli-credentials]
  C --> D[Durable afc_ credential]
  D --> E[Saved with issuing server]
  E --> F[Later CLI commands]
  F --> G[Logout or newer login revokes credential]

Loading

_{Reviews (4): Last reviewed commit: "docs: regenerate error-codes from the pl..." | Re-trigger Greptile}

Context used (4)

• Knowledge Base — API reference documentation
• Knowledge Base — The agentsfleet CLI
• Knowledge Base — Documentation validation tooling
• Knowledge Base — Onboarding: landing page, quickstart, changelog, and memory