@zackbart/connecta 0.37.1 → 0.39.0

package/documentation/README.md

@@ -8,19 +8,19 @@ For a new deployment, start with [Deploying Connecta](./deploying.md).
 
 ## Operator tasks
 
-| Task                                             | Self-contained procedure                                                                                                            |
-| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
-| Add or remove a connector                        | [Change the connector roster](./integrating.md#add-or-remove-a-connector)                                                           |
-| Set up a maintained provider                     | [Maintained provider setup](./providers.md)                                                                                         |
-| Inspect maintained API sources and tools         | [API sources and tool inventory](./providers.md#api-sources-and-tool-inventory)                                                     |
-| Organize an agent's pools and tiers              | [Organizing an agent's pools](./auth.md#organizing-an-agents-pools)                                                                 |
-| Add a person (maintainer or pool member)         | [Add a person](./auth.md#add-a-person), [member page](./operator-ui.md#use-the-member-page)                                         |
-| Connect Google hosted MCP with a service account | [Google tokens and shared-agent/personal-people setup](./auth.md#google-service-account-tokens-and-hosted-mcp)                      |
-| Connect a shared credential                      | [Connect a shared credential](./auth.md#connect-a-shared-credential)                                                                |
-| Issue, rotate, or revoke an agent token          | [Manage an agent token](./auth.md#issue-rotate-or-revoke-an-agent-token)                                                            |
-| Upgrade between versions                         | [Upgrade an existing deployment](./deploying.md#upgrade-an-existing-deployment), including [migration to 0.33](./migration-0.33.md) |
-| Diagnose with `connecta doctor`                  | [Verify and diagnose](./deploying.md#verify-and-diagnose)                                                                           |
-| Connect a client with tool search                | [Native tool surface](./meta-tools.md#native-tool-surface), [Eve agents](./meta-tools.md#eve-agents)                                |
+| Task                                             | Self-contained procedure                                                                                                                                                                      |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Add or remove a connector                        | [Change the connector roster](./integrating.md#add-or-remove-a-connector)                                                                                                                     |
+| Set up a maintained provider                     | [Maintained provider setup](./providers.md)                                                                                                                                                   |
+| Inspect maintained API sources and tools         | [API sources and tool inventory](./providers.md#api-sources-and-tool-inventory)                                                                                                               |
+| Organize an agent's pools and tiers              | [Organizing an agent's pools](./auth.md#organizing-an-agents-pools)                                                                                                                           |
+| Add a person (maintainer or pool member)         | [Add a person](./auth.md#add-a-person), [member page](./operator-ui.md#use-the-member-page)                                                                                                   |
+| Connect Google hosted MCP with a service account | [Google tokens and shared-agent/personal-people setup](./auth.md#google-service-account-tokens-and-hosted-mcp)                                                                                |
+| Connect a shared credential                      | [Connect a shared credential](./auth.md#connect-a-shared-credential)                                                                                                                          |
+| Issue, rotate, or revoke an agent token          | [Manage an agent token](./auth.md#issue-rotate-or-revoke-an-agent-token)                                                                                                                      |
+| Upgrade between versions                         | [Upgrade an existing deployment](./deploying.md#upgrade-an-existing-deployment), including [splitting mixed pools](./pool-membership-upgrade.md) and [migration to 0.33](./migration-0.33.md) |
+| Diagnose with `connecta doctor`                  | [Verify and diagnose](./deploying.md#verify-and-diagnose)                                                                                                                                     |
+| Connect a client with tool search                | [Native tool surface](./meta-tools.md#native-tool-surface), [Eve agents](./meta-tools.md#eve-agents)                                                                                          |
 
 For removed hosted presets and the former hosted modes of Stripe, Vercel,
 Cloudflare, and GitHub, use [Migrate hosted MCP presets](./hosted-mcp-migration.md).
@@ -36,20 +36,8 @@ The separate `@zackbart/connecta-eve` helper is available from 0.35.0. Its
 [package guide](https://github.com/zackbart/connecta/blob/main/packages/connecta-eve/README.md)
 owns installation, supported Node/Eve versions, and token-source setup.
 
-## Audience rule
-
-`documentation/`, `templates/`, and `examples/worker/` are written first for an
-agent operating a deployment from the installed package. The root `README.md`
-and `guides/` explain the product for people and also ship in the package;
-they own no operator contracts. Operator conventions must be self-contained rules plus a
-neutral example. Decision records and issues explain why; no operator task
-requires them, `spec/`, `.claude/`, or the Connecta source checkout. Those
-three directories do not ship. Contributor source maps, INV citations, and
-implementation/test evidence belong under clearly labeled contributor
-headings and are optional for operators. Use `assistant`, `alice`, `bob`,
-`crm`, `tickets`, `notes_alice`, and `alice@example.com` in examples; never
-real deployment, client, person, or organization names. Maintained provider
-product names stay.
+For pre-0.29 storage or OAuth grants, complete the [retired layout migrations](./migration-retired-layouts.md)
+on 0.37.1 before upgrading past that bridge release.
 
 ## Contract reference
 
@@ -61,6 +49,7 @@ product names stay.
 | [Architecture (contributor reference)](./architecture.md)        | Request lifetimes, routes, storage, configuration, import boundaries, and Effect implementation               |
 | [Operator UI](./operator-ui.md)                                  | Optional UI setup, scoped configuration and live-data contract, activity disclosure, and UI implementation    |
 | [Operator UI tests (contributor reference)](./operator-tests.md) | Browser state matrix, real-server flows, and snapshot maintenance                                             |
+| [Retired layout migrations](./migration-retired-layouts.md)      | Required 0.37.1 bridge for KV, JSON state, and OAuth layout-2 grants                                          |
 | [Migration to 0.33](./migration-0.33.md)                         | Upgrade actions from 0.32 options to maintainers, members, agents, agent endpoints, and pool owners           |
 | [Provider migration for 0.29](./provider-migration-0.29.md)      | Upgrade actions for Notion, Vercel, and Cloudflare; provider reconciliation tables supply exact name mappings |
 | [Provider migration for 0.35](./provider-migration-0.35.md)      | Provider upgrade actions for 0.35.0                                                                           |
@@ -72,34 +61,9 @@ implementation evidence.
 
 ## Contributor reference
 
-### Documentation ownership
-
-The root [README](../README.md) explains the product for people. It owns what
-Connecta offers and the setup handoff. The human guides explain
-[how it works](../guides/how-it-works.md), [connecting agents](../guides/connecting-agents.md),
-and [safety and trust](../guides/safety-and-trust.md). Keep their examples small
-and consistent with these contracts. Configuration references, complete setup
-procedures, migrations, and internal module maps belong here in agent documentation.
-
-[AGENTS.md](https://github.com/zackbart/connecta/blob/main/AGENTS.md) is the
-canonical repository policy, with `CLAUDE.md` as its symlink. Do not copy its
-verification, review, or release rules into another policy document.
-
-Deployment-local READMEs and agent instructions own runnable platform setup:
-[Node and Docker](../templates/node/README.md), [Workers](../examples/worker/README.md).
-Keep those aligned with their configuration and with this task router.
-Repository [skills](https://github.com/zackbart/connecta/tree/main/.claude/skills)
-own scoped change procedures. Each [provider folder](https://github.com/zackbart/connecta/tree/main/src/providers)
-owns its maintained `SKILL.md`, options, tests, fixtures, and review data.
-Use those details instead of copying provider catalogs into general guides.
-The provider list in the human README is generated; preserve its marker pair
-and run `pnpm run check:providers-generated` after edits.
-
-When changing behavior, update its owning contract and task guide in the same
-change. Check examples against current source and point to the tests that
-defend the contract. Published Markdown links to repo-only files must use
-canonical `https://github.com/zackbart/connecta/blob/main/…` or `tree/main/…`
-links. Keep `documentation/` flat, with Markdown files only.
+For source changes, follow [AGENTS.md](https://github.com/zackbart/connecta/blob/main/AGENTS.md).
+Contributor references describe implementation and test evidence; deployment
+operators can use the task procedures above without a source checkout.
 
 The [changelog](../CHANGELOG.md) records shipped releases.
 [Decisions](https://github.com/zackbart/connecta/tree/main/decisions) explain