docs: clarify delegated connection feature and access maps (#17882)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The feature and agent access maps describe user journeys and their
permission boundaries.
> - PRs #17737 and #17739 added delegated connection setup across
several existing areas.
> - The maps include those operations, but some recipes and board-only
statements are stale.
> - This PR adds usable setup recipes and corrects the access
descriptions.
> - The benefit is a clearer verification path that preserves human and
agent authority boundaries.

## Linked Issues or Issue Description

Refs: #17737, #17739.

Related: #17862 changes connection setup advice and catalog choices.
This PR only clarifies the existing maps.

**Issue type**

Outdated and missing documentation.

**Where is the issue?**

The paired connection setup, app permissions, chat channels, model
accounts, and gateway maps under `maps/`.

**What's wrong?**

Delegated setup guidance sits under Gotchas without a matching driving
recipe. Some model-account text still groups supported account sign-in
with board-only host controls. A few callback, privacy, and native
admission descriptions omit important limits.

**Suggested fix**

Add the missing recipes. State the current route and service boundaries.
Keep existing capability IDs and distinguish source review, fixture
tests, and live provider proof.

## What Changed

- Add paired entry points and driving recipes for delegated setup,
permission changes, and managed AI sign-in.
- Describe Google consent restoration, GitHub requested credential
fields and saved rotation, and Vercel personal credential attribution.
- Correct the Vercel callback state checks and chat
conversation/test-status privacy scope. Name the separate GitHub
registration handoff endpoint.
- Replace blanket board-only AI login wording with the specific
managed-account and host/session boundaries.
- Link the five access maps to shared native admission and work-mode
limits. State the permitted self-targeted policy administration
boundary.

## Verification

- `node scripts/check-maps.mjs` passed: 35 paired areas and 192 stable
capability IDs. This checks structure and references.
- `node scripts/storybook-catalog.mjs` passed. Generated output remains
ignored.
- `git diff --check` passed.
- Eleven selected cases in
`server/src/__tests__/connection-management.integration.test.ts` passed
on source `db70c5acd9`, the unchanged base of this documentation commit.
They use a fresh PostgreSQL database, actual agent keys/run JWTs, human
sessions, and deterministic provider fixtures. The other 61 cases were
not selected.
- The selected cases cover connection/profile creation, Google saved
choices, native API entry points, Slack caller/target policy, GitHub
import and identity confirmation, durable gateway authority, AI
accounts/pools, saved human handoffs, revocation, scope, trust, and
Ask/Plan denial.
- Read-only source reviews checked all five areas. The disposable
database was removed after the run.
- Full workspace typecheck, build, and test sweep were not rerun for
this Markdown-only change. Live provider login and browser journeys were
not run. Per-operation source-only/not-run labels remain unchanged.

## Risks

Low risk. Incorrect documentation could misstate a permission boundary
or imply broader verification. The changes cite the owning routes and
services and retain fixture and live-provider limits. No runtime,
schema, lockfile, or workflow files change.

## Model Used

OpenAI Codex, GPT-6 family, with reasoning, repository tools, code
execution, and read-only source-review agents. The session does not
expose a more specific deployment ID or context-window size.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` /
`Closes: #` / `Refs: #` OR (b) described the issue in-PR following the
relevant issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable — existing fixtures
verify this documentation-only change
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green — CI is running and Paperclip
Review is queued on the current head
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups —
exact head `4d16f101968d6908f90f72b6ff6ecbb79037f168`
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

maps/agent-access-map/README.md

@@ -53,12 +53,19 @@ REST operations use the same route authorization as legacy agent REST. Dedicated
 tools remain optional for those operations; protocol endpoints still need their
 existing clients. Board-only routes remain restricted for agent identity.
 
-Native `search_api` / `call_api` requires operator rollout admission, a running
+Native `search_api` / `call_api` is enabled by default, but explicit server,
+company-allowlist and binding settings can narrow admission. It requires a running
 authorized native run, current task assignment and execution-run binding, company
 and budget authority, task privacy, and a permitted work mode. Ask and Plan retain
 mutation restrictions, and runs retain their admitted JWT scope during restart
 recovery even when task mode changes. A waiting
 agent does not gain independent native control just because a REST route exists.
+Connection-management reads support Standard, Ask and Plan; mutations require
+Standard. Skill-test runs and nonstandard task-bridge keys cannot administer
+connections. These gates supplement each operation's grants, resolved resource
+and target scope, and responsible-user authority. See the
+[rollout policy](../../server/src/services/native-runtime/runner-api-rollout.ts)
+and [connection authorization](../../server/src/services/connection-management.ts).
 
 Credential-bearing replies, including company exports and their legacy alias,
 stay inline under a 10 MiB limit and use encrypted mutation receipts. Other saved

maps/agent-access-map/app-permissions.md

@@ -4,6 +4,13 @@ Product map: [app-permissions](../feature-map/app-permissions.md).
 
 Feature ID: `app-permissions`.
 
+Delegated native entries inherit the [native admission and work-mode limits](README.md#native-rest-transport).
+Explicitly requested policy administration may target the acting agent when its
+management grants, resolved resources and responsible-user authority permit it.
+A denied tool call does not authorize silently relaxing policy. Governed-action
+self-approval and editing one's own principal permissions remain prohibited;
+see [shared guidance](../../packages/shared/src/connection-intent-guidance.ts).
+
 Review date: 2026-10-26. Source base: `a1f77821b9cd5c9c846fdf7a0fa5cc620ad2b6bb`; implementation: [#17737](https://github.com/paperclipai/paperclip/pull/17737).
 
 Connection operations reviewed in this working tree. The inventory was reconciled

maps/agent-access-map/chat-channels.md

@@ -4,6 +4,8 @@ Product map: [chat-channels](../feature-map/chat-channels.md).
 
 Feature ID: `chat-channels`.
 
+Delegated native entries inherit the [native admission and work-mode limits](README.md#native-rest-transport).
+
 Review date: 2026-10-26. Source base: `a1f77821b9cd5c9c846fdf7a0fa5cc620ad2b6bb`; implementation: [#17737](https://github.com/paperclipai/paperclip/pull/17737).
 
 Connection operations reviewed in this working tree. The inventory was reconciled
@@ -175,7 +177,7 @@ Gaps: This individual operation has source review but no recorded HTTP verificat
 ### `post-chat-endpoints-github-registration`
 
 API: `present` — `POST /api/chat-endpoints/{endpointId}/github/registration`; JSON REST.
-Agent access: `available` — agent REST and default native `search_api` / `call_api`.
+Agent access: `available` — agent REST and admitted native `search_api` / `call_api` return the saved `requiredUserAction` for human App registration and consent.
 Policy: `tools:manage_connections`; [shared management policy](../../doc/plans/2026-10-13-connection-api-parity.md#authorization-contract). Resolved resources and every affected target are checked; personal ownership remains the responsible user.
 Evidence: `verified` — [route](../../server/src/routes/chat-channels.ts); reviewed in the working tree based on the source commit above. [Authenticated fixtures](../../server/src/__tests__/connection-management.integration.test.ts) passed with database persistence and actual bearer/session middleware.
 Verification: `passed` — deterministic provider fixtures / local assembled server; no live provider qualification.
@@ -202,7 +204,7 @@ Gaps: This individual operation has source review but no recorded HTTP verificat
 ### `post-chat-endpoints-github-setup`
 
 API: `present` — `POST /api/chat-endpoints/{endpointId}/github/setup`; JSON REST.
-Agent access: `available` — agent REST and default native `search_api` / `call_api`.
+Agent access: `available` — agent REST and admitted native `search_api` / `call_api` advance saved setup. Install and identity steps return `requiredUserAction` for the addressed human. Registration returns `state: "create"` without that handoff; use [the registration operation](#post-chat-endpoints-github-registration) to obtain the saved human setup link.
 Policy: `tools:manage_connections`; [shared management policy](../../doc/plans/2026-10-13-connection-api-parity.md#authorization-contract). Resolved resources and every affected target are checked; personal ownership remains the responsible user.
 Evidence: `source-only` — [route](../../server/src/routes/chat-channels.ts); reviewed in the working tree based on the source commit above.
 Verification: `not-run` — individual operation not executed in this audit; shared authorization and representative family flows are exercised by the authenticated integration suite. Follow the route schema, inspect persistence/audit, and assert owner, scope and revoked-authority denial.
@@ -510,9 +512,9 @@ Gaps: Fixture evidence does not qualify live provider behavior or an empirical m
 
 API: `present` — `GET /api/chat-endpoints/{endpointId}/conversations`; JSON REST.
 Agent access: `available` — agent REST and default native `search_api` / `call_api`.
-Policy: `tools:manage_connections`; [shared management policy](../../doc/plans/2026-10-13-connection-api-parity.md#authorization-contract). Resolved resources and every affected target are checked; personal ownership remains the responsible user.
+Policy: `tools:manage_connections`; [shared management policy](../../doc/plans/2026-10-13-connection-api-parity.md#authorization-contract). Resolved resources and every affected target are checked; personal ownership remains the responsible user. Every conversation row is filtered by current access to its linked task, in addition to endpoint access.
 Evidence: `source-only` — [route](../../server/src/routes/chat-channels.ts); reviewed in the working tree based on the source commit above.
-Verification: `not-run` — individual operation not executed in this audit; shared authorization and representative family flows are exercised by the authenticated integration suite. Follow the route schema, inspect persistence/audit, and assert owner, scope and revoked-authority denial.
+Verification: `not-run` — list conversations with an actual agent that can manage the endpoint but cannot read one linked private task; omit that conversation while retaining readable rows. Revoke endpoint authority and assert denial.
 Gaps: This individual operation has source review but no recorded HTTP verification. Provider availability and live setup remain unqualified.
 
 ### `post-chat-endpoints-conversations-publications`
@@ -845,9 +847,9 @@ Gaps: This individual operation has source review but no recorded HTTP verificat
 
 API: `present` — `GET /api/chat-endpoints/{endpointId}/test-status`; JSON REST.
 Agent access: `available` — agent REST and default native `search_api` / `call_api`.
-Policy: `tools:manage_connections`; [shared management policy](../../doc/plans/2026-10-13-connection-api-parity.md#authorization-contract). Resolved resources and every affected target are checked; personal ownership remains the responsible user.
+Policy: `tools:manage_connections`; [shared management policy](../../doc/plans/2026-10-13-connection-api-parity.md#authorization-contract). Endpoint access remains required. The responsible human's linked external principals bound the result: only the earliest qualifying received timestamp since test start is returned, or null, with no message body. See [setup probes](../../server/src/services/chat-channels/setup-probes.ts).
 Evidence: `source-only` — [route](../../server/src/routes/chat-channels.ts); reviewed in the working tree based on the source commit above.
-Verification: `not-run` — individual operation not executed in this audit; shared authorization and representative family flows are exercised by the authenticated integration suite. Follow the route schema, inspect persistence/audit, and assert owner, scope and revoked-authority denial.
+Verification: `not-run` — check a permitted agent's responsible-human link, another user's received message, and no linked principal. Only the matching human's qualifying timestamp may appear; the other cases return null without content. Revoke endpoint access and assert denial.
 Gaps: This individual operation has source review but no recorded HTTP verification. Provider availability and live setup remain unqualified.
 
 ### `get-chat-endpoints-activity`

maps/agent-access-map/connection-setup.md

@@ -4,6 +4,8 @@ Product map: [connection-setup](../feature-map/connection-setup.md).
 
 Feature ID: `connection-setup`.
 
+Delegated native entries inherit the [native admission and work-mode limits](README.md#native-rest-transport).
+
 Review date: 2026-10-26. Source base: `a1f77821b9cd5c9c846fdf7a0fa5cc620ad2b6bb`; implementation: [#17737](https://github.com/paperclipai/paperclip/pull/17737).
 
 Connection operations reviewed in this working tree. The inventory was reconciled
@@ -247,9 +249,9 @@ Gaps: Agent invocation is denied by the stated policy. The authorized human or o
 
 API: `present` — `GET /api/tools/vercel-connect/callback`; browser/provider/MCP protocol.
 Agent access: `restricted` — browser authentication return.
-Policy: Provider state/signature or gateway-token verification, company and resource binding; browser returns require the configuring human. Agent-issued durable gateway tokens retain both issuer and responsible-user authority.
+Policy: Saved, unexpired Vercel OAuth state binds the company and connection to the addressed human or initiating actor/session. State is consumed once; expired, replayed and wrong-user returns fail. Personal grants require current active non-viewer company membership and retain the human creator. See [state validation](../../server/src/services/tool-access/oauth/state.ts) and [Vercel callback](../../server/src/services/tool-access/oauth/vercel-callback.ts).
 Evidence: `source-only` — [route](../../server/src/routes/tool-access.ts); reviewed in the working tree based on the source commit above.
-Verification: `not-run` — individual operation not executed in this audit; shared authorization and representative family flows are exercised by the authenticated integration suite. Follow the route schema, inspect persistence/audit, and assert owner, scope and revoked-authority denial.
+Verification: `not-run` — return as the addressed human, inspect the saved personal grant and creator, then reject wrong-user, expired, replayed and revoked-membership callbacks. This callback has source review, without live Vercel qualification.
 Gaps: Agent invocation is denied by the stated policy. The authorized human or operator must perform this step; this entry does not claim delegated execution.
 
 ### `get-tools-oauth-callback`

maps/agent-access-map/gateways-profiles.md

@@ -4,6 +4,8 @@ Product map: [gateways-profiles](../feature-map/gateways-profiles.md).
 
 Feature ID: `gateways-profiles`.
 
+Delegated native entries inherit the [native admission and work-mode limits](README.md#native-rest-transport).
+
 Review date: 2026-10-26. Source base: `a1f77821b9cd5c9c846fdf7a0fa5cc620ad2b6bb`; implementation: [#17737](https://github.com/paperclipai/paperclip/pull/17737).
 
 Connection operations reviewed in this working tree. The inventory was reconciled

maps/agent-access-map/runs-adapters.md

@@ -4,6 +4,8 @@ Product map: [runs-adapters](../feature-map/runs-adapters.md).
 
 Feature ID: `runs-adapters`.
 
+Delegated native entries inherit the [native admission and work-mode limits](README.md#native-rest-transport).
+
 Review date: 2026-10-26. Source base: `a1f77821b9cd5c9c846fdf7a0fa5cc620ad2b6bb`; implementation: [#17737](https://github.com/paperclipai/paperclip/pull/17737).
 
 Connection operations reviewed in this working tree. The inventory was reconciled
@@ -37,8 +39,11 @@ API: `present` — representative operation IDs:
 Agent access: `partial` — Agent company-model REST / native `call_api` discovery and
 bound runtime context; instance adapter inventory remains board-only; model-account management is enumerated below.
 
-Policy: Run/cost visibility and agent configuration policy; adapter installation/account
-login/session control require board/admin.
+Policy: Company model discovery requires company access; account-backed discovery
+also enforces its account/pool and target-agent rules. Instance adapter inventory
+and installation retain board/admin gates. Delegated managed
+AI-account login operations are enumerated under `model-accounts`; they do not
+grant raw host administration or execution-session reset.
 
 Evidence: `source-only` — [implementation](../../server/src/routes/agents.ts#L6608) at
 the reviewed commit above.
@@ -100,8 +105,9 @@ API: `present` — representative operation IDs:
 Agent access: `partial` — Permitted agent-creation validation through REST / native
 `call_api` / CLI; supported account-login initiation has the delegated path below.
 
-Policy: Run/cost visibility and agent configuration policy; adapter installation/account
-login/session control require board/admin.
+Policy: Environment tests follow agent creation/configuration authority. Supported
+managed-account login initiation follows `model-accounts` below; human codes and
+consent, raw host login and adapter installation retain their specific gates.
 
 Evidence: `source-only` — [implementation](../../server/src/routes/agents.ts#L6608) at
 the reviewed commit above.
@@ -240,9 +246,10 @@ Policy: Same company, company-scope read authority and run/task visibility still
 apply. Task-bound history and recovery records require task read authority.
 Each run-linked task is filtered by the caller's task-read predicate; a readable
 company run cannot expose inaccessible private task titles. Existing content
-and credential redaction apply. Adapter installation, account login, session
-control, recovery writes and raw provider-trace administration retain their
-existing board/admin or dedicated-tool gates.
+and credential redaction apply. Adapter installation, raw host login, execution
+session control, recovery writes and raw provider-trace administration retain
+their board/admin or dedicated-tool gates. Delegated managed AI-account setup
+is separately enumerated under `model-accounts`.
 
 Evidence: `source-only` — diagnostic scope reviewed at
 `f10210990a3c9cad1a4359318388f237de3169dd` in the
@@ -276,8 +283,9 @@ API: `present` — representative operation IDs:
 Agent access: `restricted` — Board session controls; native server-owned session
 continuation.
 
-Policy: Run/cost visibility and agent configuration policy; adapter installation/account
-login/session control require board/admin.
+Policy: Task-session listing and execution-context reset require board agent
+management at their HTTP routes. These controls are separate from delegated
+managed AI-account authentication attempts under `model-accounts`.
 
 Evidence: `source-only` — [implementation](../../server/src/routes/agents.ts#L6608) at
 the reviewed commit above.

maps/feature-map/app-permissions.md

@@ -4,7 +4,7 @@ navigation: {"section":"Apps, channels, and extensions","sectionOrder":50,"order
 
 # App access and action permissions
 
-After connecting an app, an operator decides which agents may use it and whether each action is off, requires approval, or is allowed. Activity and action tests help verify the resulting access.
+After connecting an app, an operator or authorized agent decides which agents may use it and whether each action is off, requires approval, or is allowed. Activity and action tests help verify the resulting access.
 
 Feature ID: `app-permissions`.
 
@@ -30,6 +30,13 @@ Open an app at `/apps/:connectionId/permissions`; this is the default connected-
 
 Use the action test control in Permissions, then the connection’s Activity and available account/advanced controls.
 
+### `delegated-permissions`
+
+Ask an agent to change access or action policy for a named connection through
+the existing APIs. The responsible person's current authority, the agent's
+management grants, resource scope and all affected targets bound the request.
+An explicitly requested, authorized policy change may target that same agent.
+
 ## Driving it
 
 Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Prepare a connection to a fixture or test provider, two agents, and a harmless action. Record provider and credential ownership.
@@ -91,6 +98,21 @@ changed actions. [Unikraft regressions](../../server/src/__tests__/unikraft-conn
 cover classification, Off policies, revocation and stale contracts with fixture
 provider responses.
 
+### `delegated-permissions`
+
+Automated: [production-authenticated integration](../../server/src/__tests__/connection-management.integration.test.ts)
+covers actual key/JWT policy edits, retained targets, caller/target test policies,
+human approval, scope and revocation using PostgreSQL and provider fixtures.
+
+Manual: Request a bounded access or policy change through an actual agent, reload
+Permissions, and verify the saved audience, action choice and agent audit actor.
+Include an explicitly requested self-targeted policy edit. Repeat with missing
+management grants, an excluded target/resource, and Ask or Plan mode; writes
+must be denied. A denied tool call must not cause an unsolicited policy relaxation.
+An Ask-first action still requires the authorized human's decision; the agent
+cannot approve its own governed action or edit its own principal permissions.
+Verify caller and target policies both apply when testing as another agent.
+
 ## Gotchas
 
 - Connected does not imply an agent has access or an action is allowed.

maps/feature-map/chat-channels.md

@@ -181,6 +181,15 @@ covers these views, pending/failure/success, mobile, and light theme with simula
 provider responses. Verify actual credential validity and restored delivery
 separately against GitHub; a Storybook success does not establish live recovery.
 
+For an agent-requested GitHub credential handoff, open the saved link as the
+addressed human and verify it asks for exactly the requested fields and all/any
+completion mode. A fresh App opens import; a configured App opens replacement
+through reconnect and retains credentials omitted from the request. Interrupt
+the response after a successful rotation, reload, and verify the saved rotation
+resumes without replacing the key again. Wrong-user access, unchanged credentials
+and missing verification must not complete the request. After OAuth, confirm the
+addressed user's exact endpoint identity before expecting task continuation.
+
 For GitHub, submit a disposable PR and verify the summary heading uses the bot's
 display name and the check remains **Paperclip Review**. For two separate bots on one PR, verify
 their App-scoped checks and comments remain independent.

maps/feature-map/connection-setup.md

@@ -74,6 +74,17 @@ or open `/apps/chat/connect`. Complete that provider's endpoint setup, then
 open its settings (`/apps/chat/:endpointId/settings`). Follow identity linking
 as the intended sender before messaging the agent externally.
 
+### `delegated-configuration`
+
+Ask a standard agent to configure a disposable app or account from its assigned
+task. The agent uses REST or admitted native `search_api` / `call_api`, reuses
+saved accounts and drafts, and returns the exact saved setup link when human
+authentication, consent, credential entry or identity confirmation is required.
+Open that link as the addressed person. Personal ownership stays with that
+person; audit attribution stays with the acting agent. Existing agents retain
+their explicit grants and restrictions. See the [access companion](../agent-access-map/connection-setup.md)
+and [native admission contract](../agent-access-map/README.md#native-rest-transport).
+
 ## Driving it with Playwright and the Paperclip CLI
 
 Preconditions: follow the [baseline](./README.md#before-driving-a-journey).
@@ -220,6 +231,35 @@ reply in the originating conversation. Inspect an unlinked sender's denial and
 the endpoint's pause behavior. Repeat independently for each provider at issue;
 Slack setup does not qualify Discord, Telegram, GitHub, email, or iMessage.
 
+### `delegated-configuration`
+
+Automated: [agent-authenticated integration](../../server/src/__tests__/connection-management.integration.test.ts)
+uses production agent creation, persistent keys, run JWTs, native tool bindings,
+human sessions, PostgreSQL and deterministic provider fixtures. It covers saved
+setup, ownership, attribution, scope, trust, work modes and revocation. The
+[Google service picker tests](../../ui/src/features/connections/GoogleWorkspaceServices.test.tsx)
+cover pending choices, consent precedence and failed grant loading with API mocks.
+These are separate from live provider setup and model success.
+
+Manual: Have the agent perform authorized setup, then open its saved handoff as
+the addressed person. Reload before completing the required human step; verify
+the same resource, saved access choices, human ownership and acting-agent audit
+remain. Complete the step, verify the exact task continues, and confirm that
+revoked authority or cancelled work prevents continuation. An ordinary bot-token
+repair or an unchanged credential must not complete a signing-key request.
+
+For Google, request a specific service set, leave and reopen setup, and inspect
+the addressed user's pending choices. Another user's or organization grant must
+not supply those choices. A newer actual consent supersedes the saved request;
+a token refresh does not. A failed grant read must not broaden the selection.
+For Vercel personal setup, verify the selected credential belongs to the
+responsible person and new bindings record the configuring human as creator.
+Agent-initiated API changes retain the acting agent in audit; the human callback
+retains its actual human actor.
+Use the [chat endpoint recipe](chat-channels.md#endpoint-management) for GitHub
+field-specific credential entry and saved rotation recovery, and the
+[model-account recipe](runs-adapters.md#managed-account-setup) for AI sign-in.
+
 ## Gotchas
 
 - For connecting an assistant to Paperclip itself, use [Assistant connections (MCP)](./assistant-connections.md). This recipe's MCP-link journey connects Paperclip to an external app server.
@@ -260,18 +300,3 @@ admission at those boundaries. Verify a served deployment and provider settings,
 not only the catalog action count. Vercel preview requires an existing deployment;
 its provider makes the first deployment production, so an empty-project preview
 must fail before submission and explain the explicit production prerequisite.
-### `delegated-configuration`
-
-A fresh standard agent can use the existing REST API and default native
-`search_api` / `call_api` to perform requested configuration within its responsible
-user's authority. Personal ownership stays with that user; audit attribution stays
-with the acting agent. Existing agents retain their explicit grants and restrictions.
-Human authentication and identity confirmation open the exact saved setup; local
-host administration and action approval retain their own boundaries. See the
-operation inventory in the companion and the [qualification record](../../doc/plans/2026-10-13-connection-api-parity.md).
-
-Automated: [agent-authenticated integration](../../server/src/__tests__/connection-management.integration.test.ts)
-uses normal creation defaults, persistent agent keys, run JWTs, native tool bindings,
-real database persistence, and deterministic provider fixtures. It separately checks
-user/agent revocation, trust, company/ownership scope, work modes and attribution.
-This is API reachability evidence, not a live provider setup or an LLM success rate.

maps/feature-map/runs-adapters.md

@@ -26,6 +26,13 @@ Agent access: [companion](../agent-access-map/runs-adapters.md).
 
 Open an agent’s model/adapter configuration or the instance adapter settings page when permitted.
 
+### `managed-account-setup`
+
+Ask an authorized agent to save or connect a managed AI account. Open its saved
+`aiLogin` setup link as the responsible human when sign-in or a code is required.
+The agent can inspect the saved attempt and manage authorized account/pool
+bindings; human authentication and raw host administration retain their gates.
+
 ### `run-history`
 
 Open an agent run at `/agents/:agentId/runs/:runId` from the agent or task activity.
@@ -50,6 +57,21 @@ turn; do not count a nested discovery interval twice.
 
 Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Record adapter, model, account, native/legacy runtime, and environment. Capabilities vary; one harness result is not a matrix-wide qualification.
 
+### `managed-account-setup`
+
+Automated: [actual-auth connection integration](../../server/src/__tests__/connection-management.integration.test.ts)
+exercises account/pool persistence, responsible-user ownership, agent attribution,
+saved local-login access and native secret-response protection with provider fixtures.
+[Saved handoff UI tests](../../ui/src/pages/apps/AppsConnect.test.tsx)
+exercise setup routing with mocked APIs. Neither establishes live provider sign-in.
+
+Manual: Start delegated managed-account setup, reload the exact saved human
+handoff, finish the required login, and inspect the saved account and original
+task continuation. Bind the account or pool only to authorized agents, reload
+their configuration, and verify the selected owner and account remain correct.
+Reject a different user's saved attempt, revoked management authority and Ask/Plan
+mutations. Qualify a useful model task separately from saving the account.
+
 ### `session`
 
 For `runs-adapters/session`, complete a task in a disposable warm sandbox and