@wildo-ai/saas-models 1.1.4 → 1.1.6

package/dist/esm/requests/manual-controllers-routes-documentation.js

@@ -227,8 +227,8 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         methods: [HttpMethod.POST],
         summary: 'Register a new account',
         description: 'Creates an account from the sign-up details the application asks for. Whether the new account can sign in immediately, '
-            + 'must verify its email address first, or must complete organization onboarding depends on how this application is '
-            + 'configured; the answer says which of those applies.',
+            + 'must verify its email address first, must enroll a second factor before it can sign in, or must complete organization '
+            + 'onboarding depends on how this application is configured; the answer says which of those applies.',
         authentication: PUBLIC,
         authenticationSummary: NO_CREDENTIAL,
         successStatus: ok('The account, and what it must do before it can sign in.'),
@@ -282,11 +282,29 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         group: AUTH,
         methods: [HttpMethod.POST],
         summary: 'Complete organization onboarding',
-        description: 'For applications that defer organization creation past sign-up: creates the caller\'s organization and finishes putting '
-            + 'them into it. Only meaningful for an account the register step left in that state.',
-        authentication: BEARER,
-        authenticationSummary: BEARER_CREDENTIAL,
-        successStatus: ok('The organization exists and the caller belongs to it.'),
+        description: 'For applications that name an account\'s organization at onboarding: creates the organization and makes the account '
+            + 'its owner, on an authentication session parked at `ONBOARDING_PENDING` — by registration, by email verification or '
+            + 'enrollment, or by a sign-in answered `nextStep: onboarding` because the account still owes its organization. It '
+            + 'signs the account in when nothing else is owed; when another onboarding obligation remains (the person\'s names, for '
+            + 'a user type that collects them at onboarding), the session stays parked and the response names what is still owed. '
+            + 'A sign-in response carries the access token; the refresh token is set only as the HttpOnly refresh cookie.',
+        authentication: PUBLIC,
+        authenticationSummary: 'No credential. The parked session id in the body is what authorizes the completion, and it is consumed by it.',
+        successStatus: ok('The organization exists and the account owns it; the account is signed in unless another obligation remains.'),
+    },
+    [ManualControllerRouteKey.AUTH_COMPLETE_PROFILE_ONBOARDING]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: AUTH,
+        methods: [HttpMethod.POST],
+        summary: 'Complete profile onboarding',
+        description: 'For user types that collect a person\'s first and last name at onboarding rather than on the sign-up form: writes the '
+            + 'account\'s profile with those names, on an authentication session parked at `ONBOARDING_PENDING` that owes them. It '
+            + 'signs the account in when nothing else is owed; when the organization is still owed, the session stays parked and '
+            + 'the response names what remains. A sign-in response carries the access token; the refresh token is set only as the '
+            + 'HttpOnly refresh cookie.',
+        authentication: PUBLIC,
+        authenticationSummary: 'No credential. The parked session id in the body is what authorizes the completion.',
+        successStatus: ok('The profile carries the names; the account is signed in unless another obligation remains.'),
     },
     // ─── Invitations ─────────────────────────────────────────────────────────────────────────────
     [ManualControllerRouteKey.AUTH_INVITATION_INFO]: {
@@ -306,12 +324,13 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         group: AUTH,
         methods: [HttpMethod.POST],
         summary: 'Accept an invitation with its token',
-        description: 'Consumes an invitation token, joins the invited organization and signs the person in. For somebody arriving from the '
-            + 'invitation email with no session. A signed-in user acting on their own pending invitations uses **Accept one of my '
+        description: 'Consumes an invitation token and joins the invited organization. It then signs the person in, emails them a sign-in '
+            + 'link when they chose one, or, for an existing account whose policy does not allow signing in from an emailed link, '
+            + 'answers `nextStep: sign_in_required` and signs nobody in. For somebody arriving from the invitation email with no session. A signed-in user acting on their own pending invitations uses **Accept one of my '
             + 'invitations** instead, which needs no token.',
         authentication: PUBLIC,
         authenticationSummary: 'No credential. The single-use invitation token is what authorizes the join.',
-        successStatus: ok('Membership is created and the caller is signed in.'),
+        successStatus: ok('Membership is created; the caller is signed in, sent a sign-in link, or told to sign in.'),
     },
     [ManualControllerRouteKey.AUTH_REJECT_INVITATION]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
@@ -506,8 +525,13 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         group: AUTH,
         methods: [HttpMethod.POST],
         summary: 'Begin passkey authentication',
-        description: 'Returns the WebAuthn request options — challenge and allowed credentials — to hand to '
-            + '`navigator.credentials.get()` when signing in with a passkey.',
+        description: 'Returns `{ sessionId, options, expiresInSeconds }`: the WebAuthn request options to hand to '
+            + '`navigator.credentials.get()`, the authentication session their challenge is bound to, and how long that '
+            + 'challenge can still be redeemed — a waiting autofill request should be restarted before then. Without a `sessionId` it opens a sign-in '
+            + 'before any email is known (passkey autofill, or a sign-in-with-a-passkey button). For a sign-in the '
+            + 'options list no credentials, so the device offers every account the person holds for this site and '
+            + 'the answer is the same whatever email was entered; for a second factor they list the signed-in '
+            + 'account\'s own passkeys.',
         authentication: PUBLIC,
         authenticationSummary: NO_CREDENTIAL,
         successStatus: ok('WebAuthn request options for the browser.'),
@@ -517,7 +541,9 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         group: AUTH,
         methods: [HttpMethod.POST],
         summary: 'Complete passkey authentication',
-        description: 'Presents the assertion the authenticator produced; on success the answer carries the access token.',
+        description: 'Presents the assertion the authenticator produced, with the `sessionId` its options were issued for. '
+            + 'The account is the one the passkey belongs to, whatever email was entered. On success the answer '
+            + 'carries the access token; `passkeyCredentialUnknown` marks a passkey this application no longer holds.',
         authentication: PUBLIC,
         authenticationSummary: 'No credential. The WebAuthn assertion is the proof.',
         successStatus: ok('An access token and the caller\'s session.'),
@@ -609,13 +635,51 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         authenticationSummary: 'A bearer access token plus a fresh re-authentication token.',
         successStatus: ok('The identity is unlinked.'),
     },
+    [ManualControllerRouteKey.GOVERNED_DOCUMENT_ACCEPTANCES_OWED]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.GET],
+        summary: 'List the documents I owe an acceptance of',
+        description: 'The governed documents in force that the caller has never accepted, or that changed materially since they last '
+            + 'did — each with every in-force variant (one per locale and jurisdiction). Empty for an application that asks '
+            + 'for no acceptance.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The documents the caller owes an acceptance of.'),
+    },
+    [ManualControllerRouteKey.GOVERNED_DOCUMENT_ACCEPTANCES_ACCEPT]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.POST],
+        summary: 'Accept governed documents',
+        description: 'Records that the caller accepted the named in-force releases. Only release IDS are sent: which version, which '
+            + 'document and how the application asked are all read from the application\'s own configuration, so a caller '
+            + 'cannot choose the terms they are recorded as having agreed to. An id naming nothing in force is ignored.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The acceptances are recorded; the response lists what is still owed.'),
+    },
+    [ManualControllerRouteKey.GOVERNED_DOCUMENT_NOTICE_DELIVERED]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.POST],
+        summary: 'Record that a governed document was delivered to me',
+        description: 'Records that the caller was shown the named governed document. Only the document REF is sent: the exact release '
+            + 'version in force is resolved from the application\'s own configuration, never from the request. A document '
+            + 'whose in-force release does not permit recording a delivery is silently a no-op.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The delivery is recorded, or silently skipped when nothing in force permits it.'),
+    },
     [ManualControllerRouteKey.AUTH_REAUTH]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
         group: AUTH,
         methods: [HttpMethod.POST],
         summary: 'Re-authenticate for a sensitive operation',
         description: 'Proves the person at the keyboard is still the account holder, and returns the single-use step-up token that sensitive '
-            + 'operations require in their step-up header. This is the endpoint those operations point at.',
+            + 'operations require in their step-up header. This is the endpoint those operations point at. `purpose` says what the '
+            + 'proof is for: `step_up` (the default) must use a factor the account\'s step-up policy accepts; `bind_authenticator`, '
+            + 'asked for when adding a way to sign in, accepts any factor the account holds and is accepted only by those doors.',
         authentication: BEARER,
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: ok('A single-use step-up token.'),
@@ -631,6 +695,44 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: ok('WebAuthn request options for the step-up.'),
     },
+    [ManualControllerRouteKey.AUTH_REAUTH_METHODS]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: AUTH,
+        methods: [HttpMethod.GET],
+        summary: 'List the factors that can re-authenticate you',
+        description: 'Which of the signed-in person\'s own factors can produce a re-authentication proof for the given `purpose`, strongest '
+            + 'first. For `step_up`, only factors the account\'s step-up policy accepts are listed; for `bind_authenticator` (adding a '
+            + 'way to sign in), every factor the account holds is. Also lists the linked identities whose provider can '
+            + 're-authenticate the person (`identityLinks`). Both empty means the account must add an accepted factor first.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The factors, strongest first, and the re-provable linked identities.'),
+    },
+    [ManualControllerRouteKey.AUTH_REAUTH_FEDERATED_AUTHORIZE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: AUTH,
+        methods: [HttpMethod.POST],
+        summary: 'Re-authenticate through a linked identity provider',
+        description: 'Starts a re-authentication at the identity provider behind one of the signed-in person\'s own linked accounts, for the '
+            + 'given `purpose`. Answers the provider URL to open (in a popup). The provider is asked to sign the person in afresh '
+            + '(OIDC `prompt=login` + `max_age=0`, SAML `ForceAuthn`), and the proof is minted only if its signed answer (the ID '
+            + 'token\'s `auth_time`, or the assertion\'s `AuthnInstant`) shows a sign-in newer than this request. Refused for a link whose '
+            + 'provider or connection has not enabled re-authentication.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The identity provider URL to open.'),
+    },
+    [ManualControllerRouteKey.AUTH_REAUTH_FEDERATED_EXCHANGE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: AUTH,
+        methods: [HttpMethod.POST],
+        summary: 'Redeem a federated re-authentication',
+        description: 'Exchanges the one-time code a federated re-authentication returned for its single-use re-authentication token. The code '
+            + 'is redeemable only by the account it was minted for, with that account\'s own bearer.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('A single-use re-authentication token.'),
+    },
     // ─── Signing in through somebody else's identity provider ────────────────────────────────────
     [ManualControllerRouteKey.AUTH_OAUTH2_AUTHORIZE]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
@@ -660,12 +762,14 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         publication: ManualControllerRoutePublication.PUBLISHED,
         group: AUTH,
         methods: [HttpMethod.POST],
-        summary: 'Exchange a one-time code for tokens',
+        summary: 'Exchange a one-time code for tokens or the onboarding step',
         description: 'Turns the single-use code a redirect flow handed back into the access token and session. Single-use: the code is '
-            + 'consumed, so it cannot be replayed if it leaks into a browser history or a referrer header.',
+            + 'consumed, so it cannot be replayed if it leaks into a browser history or a referrer header. When the account '
+            + 'still has to name its organization, the answer is instead the onboarding step and the session to complete it '
+            + 'with — no token and no session cookie until the organization is named.',
         authentication: PUBLIC,
         authenticationSummary: 'No credential. The single-use code is the proof.',
-        successStatus: ok('An access token and the caller\'s session.'),
+        successStatus: ok('An access token and the caller\'s session, or the organization-onboarding step still owed.'),
     },
     [ManualControllerRouteKey.AUTH_ENTERPRISE_SSO_AUTHORIZE]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
@@ -975,9 +1079,13 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         group: CONNECTIONS,
         methods: [HttpMethod.POST],
         summary: 'Start connecting a third-party account',
-        description: 'Begins an outbound connection to the named provider so this application can later act as the connected account. The '
-            + 'opposite direction from social sign-in, which uses a vendor to identify a person. An application that declares no '
-            + 'connectable provider answers with a "not connectable" error rather than a missing route, which names why.',
+        description: 'Begins an outbound connection so this application can later act as the connected account. The path names a '
+            + 'provider ref, and the grant belongs to that ref\u2019s CONNECTION: a ref the application declares as a member of a '
+            + 'shared connection (`providers.sharedConnections`) connects the one connection its base ref owns, so connecting '
+            + 'through any member and through the base produce the same single grant. With `addScopes` it grows the stored '
+            + 'connection instead of connecting afresh. The opposite direction from social sign-in, which uses a vendor to '
+            + 'identify a person. An application that declares no connectable provider answers with a "not connectable" error '
+            + 'rather than a missing route, which names why.',
         authentication: BEARER,
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: ok('The provider authorization URL to navigate to.'),
@@ -1014,7 +1122,8 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         group: CONNECTIONS,
         methods: [HttpMethod.POST],
         summary: 'Store a typed credential for a provider',
-        description: 'For a vendor whose credential is TYPED rather than granted. Takes one value per slot the provider declares as '
+        description: 'For a vendor whose credential is TYPED rather than granted. Stored under the ref\u2019s connection, like a granted '
+            + 'one. Takes one value per slot the provider declares as '
             + 'identifying an account, and refuses any name the provider did not declare — so a caller cannot invent a slot, '
             + 'and cannot write an account token into the slot holding the application\u2019s own registration. Values are '
             + 'sealed by the write door; the request is the only place they exist in plaintext.',
@@ -1027,7 +1136,9 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         group: CONNECTIONS,
         methods: [HttpMethod.GET],
         summary: 'What can be connected',
-        description: 'Lists the providers this application declares as connectable, with the owner scopes each one admits and whether it '
+        description: 'Lists what this application declares as connectable, ONE entry per connection: a shared connection\u2019s members '
+            + 'are folded into its base ref\u2019s entry, which names every ref it serves in `servesRefs`, and a ref declared in no '
+            + 'shared connection is its own connection. Each entry carries the owner scopes it admits and whether it '
             + 'carries an authorization flow. Answers the question the stored-credential list cannot: a person with nothing '
             + 'connected has an empty list and no way to learn what they might connect. Admissibility is a recorded decision per '
             + 'provider, so this reports a decision rather than inspecting a vendor.',
@@ -1040,7 +1151,8 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         group: CONNECTIONS,
         methods: [HttpMethod.GET],
         summary: 'A short-lived access token for your own connected account',
-        description: 'Resolves the caller\u2019s OWN grant for a provider and returns its access token, renewed if the vendor\u2019s expiry '
+        description: 'Resolves the caller\u2019s OWN grant for a provider \u2014 the grant of that ref\u2019s connection, so a member of a shared '
+            + 'connection answers with the one grant its base holds \u2014 and returns its access token, renewed if the vendor\u2019s expiry '
             + 'has passed \u2014 the one credential a browser may be handed, because a vendor\u2019s own picker authorizes as the '
             + 'signed-in user and cannot open without it. Never the refresh token; never another owner\u2019s account. Each '
             + 'hand-out is recorded as a USE of the credential, so revoking or erasing the connection is visible against '
@@ -1050,6 +1162,52 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: ok('The access token, with its expiry and granted scopes when the vendor stated them.'),
     },
+    [ManualControllerRouteKey.PROVIDER_CONNECTION_LIST]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: CONNECTIONS,
+        methods: [HttpMethod.GET],
+        summary: 'The connections an owner holds',
+        description: 'One entry per CONNECTION the owner (`ownerScope` = USER for the caller\u2019s own, ORGANIZATION with `ownerId` for a '
+            + 'tenant the caller administers) has stored a credential under \u2014 never one per provider ref, because several refs '
+            + 'of one vendor share one grant. Each entry names the refs the connection serves, the scopes its consent has '
+            + 'accumulated (read from the sealed grant; no token is returned), its validation state, and the credential rows it '
+            + 'is made of. Disconnecting is the credential resource\u2019s own DELETE of those rows, which authorizes, may ask '
+            + 'for step-up, records who revoked, and withdraws the grant at a vendor that accepts a withdrawal. An organization\u2019s '
+            + 'connections are listed only for a caller holding the role the organization credential list itself requires.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The owner\u2019s connections, one entry each.'),
+    },
+    [ManualControllerRouteKey.PROVIDER_OPERATION_EXECUTE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: CONNECTIONS,
+        methods: [HttpMethod.POST],
+        summary: 'Run a provider operation this application lets your browser trigger',
+        description: 'Executes one operation of a connected third-party provider on the server and returns its parsed output. The '
+            + 'credential never reaches the browser: the body names whose account to spend (`connection`, defaulting to the '
+            + 'application\u2019s own), an optional catalogue `domain`, and the operation `input`. Only operations the '
+            + 'application declared browser-reachable can run, for the connections and roles it declared; anything else '
+            + 'answers 403 and the refusal is recorded. Every executed call is recorded too, successful or not, against the '
+            + 'person who asked.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The provider\u2019s HTTP status and the operation\u2019s output, parsed through its declared schema.'),
+    },
+    [ManualControllerRouteKey.PROVIDER_OPERATION_INPUT_OPTIONS]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: CONNECTIONS,
+        methods: [HttpMethod.POST],
+        summary: 'List the choices for one input of a provider operation',
+        description: 'Lists the values a person may pick for one input of a browser-reachable provider operation \u2014 a workspace, a '
+            + 'project \u2014 by running the input\u2019s declared options operation on the server, through the connection named in '
+            + 'the body. The list is exactly what that account can see, and the credential never reaches the browser. Both the '
+            + 'operation and its options operation must be declared browser-reachable for that connection; otherwise the answer is '
+            + '403 and the refusal is recorded. A choice the list depends on must be passed in `input`: without it the answer is '
+            + '400 naming it, rather than an empty list.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The options operation that answered, and each choice as a value and the vendor\u2019s own label.'),
+    },
     // ─── Agent interfaces ────────────────────────────────────────────────────────────────────────
     [ManualControllerRouteKey.MCP_ENDPOINT]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
@@ -1138,6 +1296,17 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: { code: '201', meaning: 'The share link and when it expires.' },
     },
+    [ManualControllerRouteKey.FILES_SHARES_REVOKE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: FILES,
+        methods: [HttpMethod.DELETE],
+        summary: 'Revoke every share link of a stored file',
+        description: 'Stops sharing this file: every link minted for it that is still live stops working at once, whoever minted it. '
+            + 'Anyone who may create a share link for the file may revoke them. Idempotent: with no live link it answers a count of zero.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('How many live share links were revoked.'),
+    },
     [ManualControllerRouteKey.FILES_UPLOAD_GRANT_STATUS]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
         group: FILES,
@@ -1184,6 +1353,20 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: ok('The caller\'s resolved feature set.'),
     },
+    [ManualControllerRouteKey.SUBMISSION_CHALLENGE_PROOF_OF_WORK]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.GET],
+        summary: 'Get a proof-of-work challenge for a public submission',
+        description: 'A signed, expiring SHA-256 puzzle. When the application protects a public form (the contact form) with a captcha, a '
+            + 'submission must carry an answer in the `x-submission-challenge-response` header: either a token from the consented '
+            + 'captcha vendor, or the solution to this challenge. Find the number whose SHA-256 of `salt + number` equals '
+            + '`challenge`, then send `{"kind":"proof_of_work","challenge":<this object>,"number":<n>}` as that header. A '
+            + 'solution is accepted once, before the salt\'s expiry. Nothing about the caller is stored or sent to a third party.',
+        authentication: PUBLIC,
+        authenticationSummary: 'No credential. A visitor who has not signed in needs a challenge to submit a public form.',
+        successStatus: ok('The challenge: algorithm, salt (carrying its expiry), challenge hash, the largest number to try, and its signature.'),
+    },
     [ManualControllerRouteKey.CHARTS_DATA]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
         group: RUNTIME,
@@ -1196,16 +1379,135 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: ok('The chart\'s data series.'),
     },
+    [ManualControllerRouteKey.SUBJECT_ERASURE_LANE_EVIDENCE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.GET],
+        summary: "Summarize this application's subject-erasure lane over a window",
+        description: 'Counts, for a closed window, what the erasure lane did: how many requests arrived and who raised each, how many were '
+            + 'withdrawn, how many reached a terminal state, and how many of those are missing the requester, justification or outcome '
+            + 'their own record promises. It also reports whether the withdrawal door is reachable to a subject and what schedule drives '
+            + 'execution, both read from the lane the application declared. It returns NO row and NO identifier — an evidence reader '
+            + 'proving the lane works must not be handed every person who asked to be erased in order to count them. An application that '
+            + 'declares no erasure lane is told so explicitly, because a lane with no activity and no lane at all are the same zeroes.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The lane summary, or a statement that no lane is declared.'),
+    },
+    [ManualControllerRouteKey.PROVIDER_CALL_EVIDENCE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.GET],
+        summary: 'Count the model-provider calls this application made over a window',
+        description: 'Counts, for a closed window, every call the application made to a model provider: grouped by provider, model, kind of call '
+            + 'and outcome, with the tokens each group consumed. It also counts the records that are incomplete (no provider, no model, no '
+            + 'reported usage) separately, so a gap is visible rather than folded into the total. It returns NO row: the question is about '
+            + 'the population of calls, and a record names an agent and an instant an evidence reader has no need to hold.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The provider-call summary for the window.'),
+    },
+    [ManualControllerRouteKey.MODEL_COST_SUMMARY]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.POST],
+        summary: 'Summarize model cost per case, organization, agent or model over a window',
+        description: 'Totals, for a window, what the application\'s model calls cost: grouped by case, organization, agent or model, per currency, '
+            + 'with the tokens each group consumed and the exact cost rounded up once per total. Calls made outside any unit of work, and '
+            + 'calls no registered price covered, are counted apart so a gap is visible rather than folded into a total. A case summary '
+            + 'also reports the expert review time recorded on each case, or says that none is recorded. Application administrators only '
+            + '(super-administrator or billing manager): it is the application\'s internal cost data. A window covers at most a year. POST '
+            + 'because the case filter is a list of references. To invoice a month, list the model-cost period aggregates instead and link '
+            + 'the one the invoice bills.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The model-cost summary for the window.'),
+    },
+    [ManualControllerRouteKey.AGENT_WORK_OVERRIDE_RATE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.POST],
+        summary: 'Report how often experts overrode what an agent proposed, over a window',
+        description: 'Counts, for a window, the decisions people took on agents\' proposals, grouped by agent, tool, case or decider: accepted as '
+            + 'proposed, accepted after a change, and rejected. The override rate is the changed and rejected decisions over all three. '
+            + 'Decisions nobody took (the window lapsed, the work was withdrawn, or the requester lost their access) are counted apart and '
+            + 'never enter the rate. It reads the decision records only, never their content. An organization administrator reads their '
+            + 'own organization; an application super-administrator may read any, or all. A window covers at most a year.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The override rate per group for the window.'),
+    },
+    [ManualControllerRouteKey.AGENT_WORK_EVALUATION_EXPORT]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.POST],
+        summary: 'Export an organization\'s decisions on one agent\'s proposals as an evaluation dataset',
+        description: 'Exports, for one organization, one agent and a window, the decisions its people took on that agent\'s proposals, as JSON '
+            + 'Lines: one object per decision, with no decider and no organization. The record\'s own identifiers (the decision, the '
+            + 'case, the run, the task, the work product, the decider, the organization) are replaced by pseudonyms wherever they '
+            + 'appear, including inside kept content; any other value in the kept proposal or final version is exported as the '
+            + 'organization kept it. The proposal and the final version are included only when the organization kept them. Cases the organization walled off '
+            + 'are left out, and a case of a privileged kind goes only with its client\'s recorded consent. The export is refused, and '
+            + 'the refusal recorded, unless the organization holds an active export authorisation; every export is recorded on its '
+            + 'ledger and in the audit trail. An organization administrator for their own organization, or an application '
+            + 'super-administrator.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The dataset, and the id of its ledger entry.'),
+    },
+    [ManualControllerRouteKey.RETENTION_ENFORCEMENT_EVIDENCE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.GET],
+        summary: 'List the retention enforcement records of the sweep runs in a window',
+        description: 'Returns, for a closed window, every record the retention-class sweep wrote: one per run and per resource bound to a retention '
+            + 'class, with the class, the period the run applied, the cutoff, how many rows it deleted and the window of their retention '
+            + 'start, how many a legal hold kept, and whether the run completed, deferred work to the next run, failed or skipped the '
+            + 'resource. A failed run has a record too. The records hold counts and instants only, so the answer names no person and no '
+            + 'deleted row.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The retention enforcement records for the window.'),
+    },
+    [ManualControllerRouteKey.USAGE_FLUSH_EVIDENCE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.GET],
+        summary: 'Count where the metered-usage rows stand with respect to the provider flush',
+        description: 'Counts every usage row by flush state (pending, reported, unreportable), the unreportable rows by reason, and the '
+            + 'contradictions that must never exist: an unreportable row with no reason, one with no decision instant, and one also '
+            + 'marked reported. The window adds how many rows were decided unreportable inside it. It returns NO row: a usage row names '
+            + 'a customer and a quantity, which an evidence reader has no need to hold. An application with billing off measures no store, '
+            + 'and says so.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The usage flush summary.'),
+    },
+    [ManualControllerRouteKey.SCHEDULED_EVIDENCE_COVERAGE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.POST],
+        summary: 'Assess whether a scheduled run happened as often as it was scheduled to',
+        description: 'Compares the runs this application retained, and its live job history, against the schedule that was IN FORCE across the period — '
+            + 'supplied by the caller as historical segments, each naming the commit that set it. Reports coverage, missing occurrences, duplicate '
+            + 'runs, outcomes, unavailable results, deferral and timeliness separately, because a run that happened and failed, one that happened '
+            + 'late, and one that never happened are different findings. POST because the schedule basis is a body: the current cron cannot stand in '
+            + 'for what the schedule WAS, so a caller that supplies none gets a refusal rather than an assessment against today.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The coverage assessment for one scheduled target over the period.'),
+    },
     [ManualControllerRouteKey.FLOWS_ACTORS_FRONTEND_INFO]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
         group: RUNTIME,
         methods: [HttpMethod.GET],
         summary: 'Read the flow and actor systems a client may render',
         description: 'The metadata and renderable graph for every flow or actor system this application exposes to its frontends — what '
-            + 'exists, what it is called, and how it is shaped.',
+            + 'exists, what it is called, and how it is shaped — and the autonomous agents the application declares, by reference '
+            + 'and actor system: the only values an organization OAuth client may be bound to.',
         authentication: BEARER,
         authenticationSummary: BEARER_CREDENTIAL,
-        successStatus: ok('The visible flow and actor systems.'),
+        successStatus: ok('The visible flow and actor systems, and the declared autonomous agents.'),
     },
     [ManualControllerRouteKey.FLOWS_ACTORS_HISTORY]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
@@ -1218,6 +1520,44 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: ok('The caller\'s conversation, or confirmation that it was cleared.'),
     },
+    [ManualControllerRouteKey.FLOWS_ACTORS_DECISIONS]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.GET],
+        summary: 'List the decisions waiting on me',
+        description: 'The pending decisions an agent is waiting on that the caller may act on, across every conversation: their own, those '
+            + 'assigned to them, and those routed to a role they hold in the decision\'s organization. Each is a decision card — the '
+            + 'call being asked for, its deadline, its route and what the caller may do — and never the conversation behind it. '
+            + 'Every row is re-checked against the same rule an act is, so the list never shows a decision the caller could not act on.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The decision cards.'),
+    },
+    [ManualControllerRouteKey.FLOWS_ACTORS_DECISION_ACT]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.POST],
+        summary: 'Answer, reassign, claim, unclaim or escalate a decision',
+        description: 'Acts on one pending decision. `answer` approves or denies the call, optionally with edited arguments; the work then '
+            + 'runs as the person who raised it, with their access as it stands now. `reassign` and `escalate` move it to another '
+            + 'person, who must be able to answer it; `claim` takes a role-routed decision for yourself and `unclaim` gives it back. '
+            + 'A decision that does not exist, is settled, or is not routed to the caller all answer the same way.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('What the act came to.'),
+    },
+    [ManualControllerRouteKey.FLOWS_ACTORS_DECISION_CANDIDATES]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.GET],
+        summary: 'List who a decision may be moved to',
+        description: 'The people in the decision\'s organization who could answer it, for a caller who may reassign or escalate it. Each is '
+            + 'checked against the same rule a move is, so choosing one of them is never refused for who they are. A decision the '
+            + 'caller may not move answers the same way as one that does not exist.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The people it may be moved to.'),
+    },
     [ManualControllerRouteKey.ANALYTICS_EVENTS]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
         group: RUNTIME,