@noodleseed/agent-kit 0.99.1 → 0.101.0

package/skills/codex/connecting-apis-to-mcp/references/authoring-workflow.md

@@ -17,6 +17,7 @@
 - Tests
 - Secrets and variables
 - Embedded assistant
+- Managed collections
 - Boundaries
 
 ## Input paths
@@ -41,9 +42,9 @@ Author in `server.ts`, then `noodle validate` → fix cited errors (see `compile
 
 ## Connectors
 
-Declare connectors as data, not imperative code:
+Declare typed connectors:
 
-- **HTTP**: `connector("id").version("1.0.0").http({ baseUrl, allowedOrigins, auth, operations })` with per-operation `request`/`response` mapping using `${args...}` / `${response...}` expressions.
+- **HTTP**: `connector("id").version("1.0.0").http({ baseUrl, allowedOrigins, auth, operations })`; map request/response with `${args...}` / `${response...}`. Use `${execution.id}` for provider idempotency, never model input. Optional `evidence: { outcome: "${response.execution_outcome}", reference: "${response.id}" }` classifies completed/rejected/accepted/unknown; reference is a bounded opaque ID, never a bearer URL or payload. No automatic action retry.
 - **MCP**: `connector("id").version("1.0.0").mcp({ endpoint, allowedOrigins, auth?, operations })` where each operation freezes the separate upstream `tool` wire name plus input/output schema. Import with `noodle import mcp`; do not hand-copy a live surface or call `tools/list` at runtime.
 - **Compute**: `connector("id").version("1.0.0").compute(name, { input, output, calls?, run })` — a self-contained, sandboxed function (no imports/closure capture) that may call allowlisted operations via `callOperation`.
 
@@ -57,6 +58,7 @@ not imported or forwarded. The runtime opens one guarded session for one operati
 credential, and closes it; it does not act as an agent for upstream sampling, roots, or elicitation.
 
 HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `clientCredentials`, `delegatedOAuth`, `delegatedSessionCookie`, and `delegatedTokenExchange` (per-user calls to your own API — see "Delegated downstream auth" below). Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
+An application-owned adapter may require its own service credential in addition to the operator account credential. Declare `http.transportAuth: { kind: "apiKey", header: "X-Adapter-Key", secret: secret("ADAPTER_SERVICE_KEY") }` alongside bound account credential profiles; the credential broker supplies the two independently. Never put either credential in tool arguments or ordinary headers, and never reuse an inbound MCP bearer. This capability does not imply a provider requires two credentials.
 
 When one connector needs independently selectable accounts, declare catalog `credentialProfiles` plus each operation’s accepted `credentials.profiles`, then bind each `server.use` alias with `bind(connector, { profile, connection: connection("logical_id", managedSecret(secret("NAME"), { scopes, audience })) })`. The alias is the stable account boundary; never put provider account ids, labels, or credential values in it. `gmailConnector()` is the curated Gmail catalog helper; reuse it under independent aliases and accept canonical `accounts` arrays in tools (one account for writes, or an explicitly ordered supported combination for reads). See the bundled `gmail-multi-account` flagship. Bound managed secrets are supported by hosted execution. For deployed-server access to Google APIs, use `googleWorkloadIdentity({ provider: variable("GOOGLE_WIF_PROVIDER"), access: { kind: "direct" } })`, or add `serviceAccountImpersonation` with a managed service-account email. This is keyless Google Workload Identity Federation: exact Google scopes/audience come from the catalog operation, while `noodle auth google prepare|status|doctor|revoke` owns operator lifecycle. See the bundled `google-bigquery` flagship. `externalExchange()` is runnable only when the deployment operator injects an exact HTTPS provider endpoint/origin/audience and durable shared subject-pin store through service ports; Noodle sends a short-lived platform-signed deployment workload assertion and accepts only a bounded bearer response. Provider implementations must consume assertion replay ids through durable shared atomic storage across instances and restarts. There is intentionally no hosted enrollment or provider CRUD surface yet. The provider wire contract is public, but its conformance kit is workspace/source-only and is not an installable npm package. Bound `clientCredentials(...)` remains fail-closed until its provider slice lands.
 
@@ -407,6 +409,12 @@ Adapt the representative arguments and assertions when business contracts change
 
 Author managed config as `secret("NAME")` / `variable("NAME")` and operate it with `noodle secrets set` / `noodle variables set` (scoped org/app/env). Never inline secret values in `server.ts`, tests, or generated files.
 
+For business-editable configuration, declare `const notice = variable("SERVICE_NOTICE", { schema: z.string().max(500), default: "Welcome", portal: { label: "Service notice", group: "Guest experience" }, requiredFor: ["show_menu"] })` and register it in `server(..., { variables: [notice], ... }, tools)`. Use the same ref in ordinary fulfilment/connector arguments. The default is reusable safe intent; each business supplies its own values without editing source. Only explicit `portal` metadata exposes a setting. Name-only references and declared variables without `portal` remain technical configuration; secrets remain credential slots. See the bundled `acme-bistro` source.
+
+Business schemas must be bounded: booleans, finite bounded numbers, bounded text, string enums, bounded arrays, and closed objects. Put defaults in the declaration, not inside Zod schema defaults; custom transforms/refinements and arbitrary schema code cannot run in the shared runtime. `requiredFor` names existing tools whose invocation needs the value; unresolved settings must leave only dependent capabilities unavailable. Publisher compilation does not require a future buyer’s values. Application code enforces business rules server-side; exposing a control or placing the rule in a prompt is insufficient.
+
+For an installed application, use the same `noodle variables list|resolve|set|delete` family with `--installation <id> --org <org> --runtime cloud|other`; do not combine it with app/env/scope flags or secrets. Inspection shows schema metadata, provenance, readiness and revision without saved values. Set inputs are JSON (including quotes for strings), read the current projection and save atomically; `--expected-revision <digest>` pins an explicit prior inspection. Delete resets to the current declared default or unset state. Business-administrator permission is required for mutations, conflicts never retry writes, and mutation output excludes values.
+
 ## Embedded assistant
 
 To place the same server tools inside a SaaS web app, declare `assistant: embeddedAssistant(...)` alongside the one server-level brand kit. Read `embedded-assistant.md` before integrating: it owns the HTTPS-origin rule, managed model configuration, required deploy-before-client sequence, customer-backend exchange, browser mount, and verification checklist.
@@ -441,6 +449,17 @@ The compiler validates and hashes every document at build time (bad extensions,
 
 The managed crawler and managed index are the defaults and need no configuration. A component may instead bring its own crawler (`crawler: firecrawl({ apiKey: secret('FIRECRAWL_API_KEY') })` or `tavily(...)`) and/or its own index (`index: algolia({ appId: variable('ALGOLIA_APP_ID'), apiKey: secret('ALGOLIA_API_KEY') })` or `meilisearch({ host: variable(...), apiKey: secret(...) })`). The code declares only config names; operators supply values with `noodle secrets set` / `noodle variables set`, and deploy preflight fails closed naming any unset reference.
 
+## Managed collections
+
+Use `managedCollection(name, { title, description, schemaVersion, record })` when an application needs reusable typed intent for business records that Noodle may later hold. Pass it through `server(..., { collections: [...] }, definitions)`. `record` is one bounded, closed Zod object; names use lowercase letters, numbers, and underscores. Keep payment-card, credentials, passport/government identity, health, and biometric fields out of this surface.
+Native record controls are independent: `management: { assignment: true }`, `{ notes: true }`, both, or neither. Status is an ordinary application field such as `progress: z.enum(["received", "reviewing", "handled"]).default("received")`; no framework transition graph exists. Declare `publicFields` explicitly (default empty), `editableFields` for authorized staff (default all schema properties), optional field labels/help, `summaryFields`, `filterFields` and `sortFields`. References must name actual fields and filters/sorts select scalars. Public callers cannot set staff-only fields; a required private field needs a valid creation default. Staff updates merge only admitted fields and revalidate the complete record. See the notes-only `acme-bistro` collection.
+Operator record queries use `noodle solutions records list --filters '[{"field":"progress","value":"received"}]' --sort-field progress`. Only declared scalar equality/sort fields apply. Payload queries scan at most 10,000 candidates; narrow `--created-at-from`/`--created-at-to` if the API returns `query_limit_exceeded`. Ordinary listing/export has no such scan cap. Cursor reuse requires unchanged query/schema and anchor revision. An administrator can explicitly migrate an eligible historical request with `records migrate-schema ... --expected-revision N`; never implement read-time rewrites.
+
+Omitting `source` makes Noodle authoritative for the collection. To project a read-only collection from an outside system, bind an HTTP connector in `server(..., { use: [...] })` and add `source: { connector: connector.ref(), scan: "scan_operation" }`. The compiler requires the exact normalized scan contract and the same record schema. Noodle ingests a one-way replica; create, update, and delete in the outside system remain ordinary application tools with their own confirmation and policy.
+
+For an explicitly authored native operation, bind `use: { records: noodlePlatform.records.v1 }` and call `connectors.records.submitRecord({ collection: "guest_requests", payload: input })` from an ordinary confirmed tool. Submission accepts only public fields and returns a receipt. `createRecord`, `getRecord`, `listRecords`, `updateRecord`, and `deleteRecord` require a verified platform caller with a live business grant; updates/deletes require the current revision. `updateRecord({ collection, id, expectedRevision, patch, unset: ["optional_field"] })` removes named optional editable fields; omitted keys stay unchanged, `null` is data, and overlap with `patch`, required fields or undeclared fields is rejected. Runtime identity supplies write idempotency and admission; never accept those controls as model arguments. An uninstalled collection is unavailable, including during local tool execution.
+A collection declaration does not create a submit tool, grant access, select retention or residency, provision storage, or expose records to MCP or an embedded assistant. Operators activate the definition and configure lifecycle, access, and any external binding. A connector does not become a collection unless the app explicitly supplies the source contract, and an external collection never becomes a writable mirror.
+
 ## Boundaries
 
 Import public app authoring only from `@noodleseed/one` (and its documented `/react` or `/platform` subpaths). Packages and subpaths under `@noodle-borg/*` are runtime implementation details, including `/portable` boundaries, and must never appear in customer `server.ts` code. Do not hand-author manifest JSON/YAML, runtime artifacts, connector IR, or hosted asset metadata. Do not read or copy secrets, bearer tokens, refresh tokens, static access keys, `.env`, `.env.noodle`, or `~/.noodle/config.json`. Hosted access is identity-based — do not add static data-plane credential paths.

package/skills/codex/creating-product-agent-guides/SKILL.md

@@ -3,7 +3,7 @@ name: creating-product-agent-guides
 description: "Use when a Noodle Seed MCP server needs a new or revised product agent guide, App Package skill, or explicit product-skill regeneration."
 ---
 
-<!-- noodle-skill version:0.99.1 hash:0e06e11254563b6a -->
+<!-- noodle-skill version:0.101.0 hash:0e06e11254563b6a -->
 
 # creating-product-agent-guides
 

package/skills/codex/debugging-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: debugging-mcp-delivery
 description: "Use when an existing Noodle Seed MCP project has a concrete validation, runtime, connector, App, host, deployment, or production failure."
 ---
 
-<!-- noodle-skill version:0.99.1 hash:8d75ad13f4b3120a -->
+<!-- noodle-skill version:0.101.0 hash:8d75ad13f4b3120a -->
 
 # debugging-mcp-delivery
 

package/skills/codex/deploying-mcp-services/SKILL.md

@@ -3,7 +3,7 @@ name: deploying-mcp-services
 description: "Use when the user explicitly requests a Noodle Seed hosted link, configuration write, deployment, access change, rollback, or connection write."
 ---
 
-<!-- noodle-skill version:0.99.1 hash:3a1e14ff9b98ddbd -->
+<!-- noodle-skill version:0.101.0 hash:3a1e14ff9b98ddbd -->
 
 # deploying-mcp-services
 

package/skills/codex/deploying-mcp-services/references/cli-commands.md

@@ -61,6 +61,7 @@ Developer-facing `noodle` commands, grouped by area. Local authoring commands (`
 | `noodle deployments` | List or inspect individual deployments (`deployments list`/`deployments inspect <id>`). |
 | `noodle distributions` | Publish immutable host archives, record their lifecycle, and operate bounded delivery. |
 | `noodle service` | Query hosted service capabilities. |
+| `noodle solutions` | Install managed solutions and operate their grants, records, activity, exports, and deletion. |
 | `noodle login` | Authenticate with Noodle Seed Cloud. |
 | `noodle logout` | Clear saved credentials. |
 | `noodle whoami` | Print the current authenticated user. |

package/skills/codex/designing-mcp-products/SKILL.md

@@ -3,7 +3,7 @@ name: designing-mcp-products
 description: "Use when a Noodle Seed MCP product idea needs conversational fit, user benefit, scope, interaction, or evidence design before implementation."
 ---
 
-<!-- noodle-skill version:0.99.1 hash:a21b2ed9997f9454 -->
+<!-- noodle-skill version:0.101.0 hash:a21b2ed9997f9454 -->
 
 # designing-mcp-products
 

package/skills/codex/designing-mcp-products/references/authoring-workflow.md

@@ -17,6 +17,7 @@
 - Tests
 - Secrets and variables
 - Embedded assistant
+- Managed collections
 - Boundaries
 
 ## Input paths
@@ -41,9 +42,9 @@ Author in `server.ts`, then `noodle validate` → fix cited errors (see `compile
 
 ## Connectors
 
-Declare connectors as data, not imperative code:
+Declare typed connectors:
 
-- **HTTP**: `connector("id").version("1.0.0").http({ baseUrl, allowedOrigins, auth, operations })` with per-operation `request`/`response` mapping using `${args...}` / `${response...}` expressions.
+- **HTTP**: `connector("id").version("1.0.0").http({ baseUrl, allowedOrigins, auth, operations })`; map request/response with `${args...}` / `${response...}`. Use `${execution.id}` for provider idempotency, never model input. Optional `evidence: { outcome: "${response.execution_outcome}", reference: "${response.id}" }` classifies completed/rejected/accepted/unknown; reference is a bounded opaque ID, never a bearer URL or payload. No automatic action retry.
 - **MCP**: `connector("id").version("1.0.0").mcp({ endpoint, allowedOrigins, auth?, operations })` where each operation freezes the separate upstream `tool` wire name plus input/output schema. Import with `noodle import mcp`; do not hand-copy a live surface or call `tools/list` at runtime.
 - **Compute**: `connector("id").version("1.0.0").compute(name, { input, output, calls?, run })` — a self-contained, sandboxed function (no imports/closure capture) that may call allowlisted operations via `callOperation`.
 
@@ -57,6 +58,7 @@ not imported or forwarded. The runtime opens one guarded session for one operati
 credential, and closes it; it does not act as an agent for upstream sampling, roots, or elicitation.
 
 HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `clientCredentials`, `delegatedOAuth`, `delegatedSessionCookie`, and `delegatedTokenExchange` (per-user calls to your own API — see "Delegated downstream auth" below). Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
+An application-owned adapter may require its own service credential in addition to the operator account credential. Declare `http.transportAuth: { kind: "apiKey", header: "X-Adapter-Key", secret: secret("ADAPTER_SERVICE_KEY") }` alongside bound account credential profiles; the credential broker supplies the two independently. Never put either credential in tool arguments or ordinary headers, and never reuse an inbound MCP bearer. This capability does not imply a provider requires two credentials.
 
 When one connector needs independently selectable accounts, declare catalog `credentialProfiles` plus each operation’s accepted `credentials.profiles`, then bind each `server.use` alias with `bind(connector, { profile, connection: connection("logical_id", managedSecret(secret("NAME"), { scopes, audience })) })`. The alias is the stable account boundary; never put provider account ids, labels, or credential values in it. `gmailConnector()` is the curated Gmail catalog helper; reuse it under independent aliases and accept canonical `accounts` arrays in tools (one account for writes, or an explicitly ordered supported combination for reads). See the bundled `gmail-multi-account` flagship. Bound managed secrets are supported by hosted execution. For deployed-server access to Google APIs, use `googleWorkloadIdentity({ provider: variable("GOOGLE_WIF_PROVIDER"), access: { kind: "direct" } })`, or add `serviceAccountImpersonation` with a managed service-account email. This is keyless Google Workload Identity Federation: exact Google scopes/audience come from the catalog operation, while `noodle auth google prepare|status|doctor|revoke` owns operator lifecycle. See the bundled `google-bigquery` flagship. `externalExchange()` is runnable only when the deployment operator injects an exact HTTPS provider endpoint/origin/audience and durable shared subject-pin store through service ports; Noodle sends a short-lived platform-signed deployment workload assertion and accepts only a bounded bearer response. Provider implementations must consume assertion replay ids through durable shared atomic storage across instances and restarts. There is intentionally no hosted enrollment or provider CRUD surface yet. The provider wire contract is public, but its conformance kit is workspace/source-only and is not an installable npm package. Bound `clientCredentials(...)` remains fail-closed until its provider slice lands.
 
@@ -407,6 +409,12 @@ Adapt the representative arguments and assertions when business contracts change
 
 Author managed config as `secret("NAME")` / `variable("NAME")` and operate it with `noodle secrets set` / `noodle variables set` (scoped org/app/env). Never inline secret values in `server.ts`, tests, or generated files.
 
+For business-editable configuration, declare `const notice = variable("SERVICE_NOTICE", { schema: z.string().max(500), default: "Welcome", portal: { label: "Service notice", group: "Guest experience" }, requiredFor: ["show_menu"] })` and register it in `server(..., { variables: [notice], ... }, tools)`. Use the same ref in ordinary fulfilment/connector arguments. The default is reusable safe intent; each business supplies its own values without editing source. Only explicit `portal` metadata exposes a setting. Name-only references and declared variables without `portal` remain technical configuration; secrets remain credential slots. See the bundled `acme-bistro` source.
+
+Business schemas must be bounded: booleans, finite bounded numbers, bounded text, string enums, bounded arrays, and closed objects. Put defaults in the declaration, not inside Zod schema defaults; custom transforms/refinements and arbitrary schema code cannot run in the shared runtime. `requiredFor` names existing tools whose invocation needs the value; unresolved settings must leave only dependent capabilities unavailable. Publisher compilation does not require a future buyer’s values. Application code enforces business rules server-side; exposing a control or placing the rule in a prompt is insufficient.
+
+For an installed application, use the same `noodle variables list|resolve|set|delete` family with `--installation <id> --org <org> --runtime cloud|other`; do not combine it with app/env/scope flags or secrets. Inspection shows schema metadata, provenance, readiness and revision without saved values. Set inputs are JSON (including quotes for strings), read the current projection and save atomically; `--expected-revision <digest>` pins an explicit prior inspection. Delete resets to the current declared default or unset state. Business-administrator permission is required for mutations, conflicts never retry writes, and mutation output excludes values.
+
 ## Embedded assistant
 
 To place the same server tools inside a SaaS web app, declare `assistant: embeddedAssistant(...)` alongside the one server-level brand kit. Read `embedded-assistant.md` before integrating: it owns the HTTPS-origin rule, managed model configuration, required deploy-before-client sequence, customer-backend exchange, browser mount, and verification checklist.
@@ -441,6 +449,17 @@ The compiler validates and hashes every document at build time (bad extensions,
 
 The managed crawler and managed index are the defaults and need no configuration. A component may instead bring its own crawler (`crawler: firecrawl({ apiKey: secret('FIRECRAWL_API_KEY') })` or `tavily(...)`) and/or its own index (`index: algolia({ appId: variable('ALGOLIA_APP_ID'), apiKey: secret('ALGOLIA_API_KEY') })` or `meilisearch({ host: variable(...), apiKey: secret(...) })`). The code declares only config names; operators supply values with `noodle secrets set` / `noodle variables set`, and deploy preflight fails closed naming any unset reference.
 
+## Managed collections
+
+Use `managedCollection(name, { title, description, schemaVersion, record })` when an application needs reusable typed intent for business records that Noodle may later hold. Pass it through `server(..., { collections: [...] }, definitions)`. `record` is one bounded, closed Zod object; names use lowercase letters, numbers, and underscores. Keep payment-card, credentials, passport/government identity, health, and biometric fields out of this surface.
+Native record controls are independent: `management: { assignment: true }`, `{ notes: true }`, both, or neither. Status is an ordinary application field such as `progress: z.enum(["received", "reviewing", "handled"]).default("received")`; no framework transition graph exists. Declare `publicFields` explicitly (default empty), `editableFields` for authorized staff (default all schema properties), optional field labels/help, `summaryFields`, `filterFields` and `sortFields`. References must name actual fields and filters/sorts select scalars. Public callers cannot set staff-only fields; a required private field needs a valid creation default. Staff updates merge only admitted fields and revalidate the complete record. See the notes-only `acme-bistro` collection.
+Operator record queries use `noodle solutions records list --filters '[{"field":"progress","value":"received"}]' --sort-field progress`. Only declared scalar equality/sort fields apply. Payload queries scan at most 10,000 candidates; narrow `--created-at-from`/`--created-at-to` if the API returns `query_limit_exceeded`. Ordinary listing/export has no such scan cap. Cursor reuse requires unchanged query/schema and anchor revision. An administrator can explicitly migrate an eligible historical request with `records migrate-schema ... --expected-revision N`; never implement read-time rewrites.
+
+Omitting `source` makes Noodle authoritative for the collection. To project a read-only collection from an outside system, bind an HTTP connector in `server(..., { use: [...] })` and add `source: { connector: connector.ref(), scan: "scan_operation" }`. The compiler requires the exact normalized scan contract and the same record schema. Noodle ingests a one-way replica; create, update, and delete in the outside system remain ordinary application tools with their own confirmation and policy.
+
+For an explicitly authored native operation, bind `use: { records: noodlePlatform.records.v1 }` and call `connectors.records.submitRecord({ collection: "guest_requests", payload: input })` from an ordinary confirmed tool. Submission accepts only public fields and returns a receipt. `createRecord`, `getRecord`, `listRecords`, `updateRecord`, and `deleteRecord` require a verified platform caller with a live business grant; updates/deletes require the current revision. `updateRecord({ collection, id, expectedRevision, patch, unset: ["optional_field"] })` removes named optional editable fields; omitted keys stay unchanged, `null` is data, and overlap with `patch`, required fields or undeclared fields is rejected. Runtime identity supplies write idempotency and admission; never accept those controls as model arguments. An uninstalled collection is unavailable, including during local tool execution.
+A collection declaration does not create a submit tool, grant access, select retention or residency, provision storage, or expose records to MCP or an embedded assistant. Operators activate the definition and configure lifecycle, access, and any external binding. A connector does not become a collection unless the app explicitly supplies the source contract, and an external collection never becomes a writable mirror.
+
 ## Boundaries
 
 Import public app authoring only from `@noodleseed/one` (and its documented `/react` or `/platform` subpaths). Packages and subpaths under `@noodle-borg/*` are runtime implementation details, including `/portable` boundaries, and must never appear in customer `server.ts` code. Do not hand-author manifest JSON/YAML, runtime artifacts, connector IR, or hosted asset metadata. Do not read or copy secrets, bearer tokens, refresh tokens, static access keys, `.env`, `.env.noodle`, or `~/.noodle/config.json`. Hosted access is identity-based — do not add static data-plane credential paths.

package/skills/codex/embedding-mcp-assistants/SKILL.md

@@ -3,7 +3,7 @@ name: embedding-mcp-assistants
 description: "Use when embedding a Noodle assistant into an existing SaaS or web application with browser, identity, session, and credential boundaries."
 ---
 
-<!-- noodle-skill version:0.99.1 hash:d554d661ed7ac7be -->
+<!-- noodle-skill version:0.101.0 hash:d554d661ed7ac7be -->
 
 # embedding-mcp-assistants
 

package/skills/codex/embedding-mcp-assistants/references/authoring-workflow.md

@@ -17,6 +17,7 @@
 - Tests
 - Secrets and variables
 - Embedded assistant
+- Managed collections
 - Boundaries
 
 ## Input paths
@@ -41,9 +42,9 @@ Author in `server.ts`, then `noodle validate` → fix cited errors (see `compile
 
 ## Connectors
 
-Declare connectors as data, not imperative code:
+Declare typed connectors:
 
-- **HTTP**: `connector("id").version("1.0.0").http({ baseUrl, allowedOrigins, auth, operations })` with per-operation `request`/`response` mapping using `${args...}` / `${response...}` expressions.
+- **HTTP**: `connector("id").version("1.0.0").http({ baseUrl, allowedOrigins, auth, operations })`; map request/response with `${args...}` / `${response...}`. Use `${execution.id}` for provider idempotency, never model input. Optional `evidence: { outcome: "${response.execution_outcome}", reference: "${response.id}" }` classifies completed/rejected/accepted/unknown; reference is a bounded opaque ID, never a bearer URL or payload. No automatic action retry.
 - **MCP**: `connector("id").version("1.0.0").mcp({ endpoint, allowedOrigins, auth?, operations })` where each operation freezes the separate upstream `tool` wire name plus input/output schema. Import with `noodle import mcp`; do not hand-copy a live surface or call `tools/list` at runtime.
 - **Compute**: `connector("id").version("1.0.0").compute(name, { input, output, calls?, run })` — a self-contained, sandboxed function (no imports/closure capture) that may call allowlisted operations via `callOperation`.
 
@@ -57,6 +58,7 @@ not imported or forwarded. The runtime opens one guarded session for one operati
 credential, and closes it; it does not act as an agent for upstream sampling, roots, or elicitation.
 
 HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `clientCredentials`, `delegatedOAuth`, `delegatedSessionCookie`, and `delegatedTokenExchange` (per-user calls to your own API — see "Delegated downstream auth" below). Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
+An application-owned adapter may require its own service credential in addition to the operator account credential. Declare `http.transportAuth: { kind: "apiKey", header: "X-Adapter-Key", secret: secret("ADAPTER_SERVICE_KEY") }` alongside bound account credential profiles; the credential broker supplies the two independently. Never put either credential in tool arguments or ordinary headers, and never reuse an inbound MCP bearer. This capability does not imply a provider requires two credentials.
 
 When one connector needs independently selectable accounts, declare catalog `credentialProfiles` plus each operation’s accepted `credentials.profiles`, then bind each `server.use` alias with `bind(connector, { profile, connection: connection("logical_id", managedSecret(secret("NAME"), { scopes, audience })) })`. The alias is the stable account boundary; never put provider account ids, labels, or credential values in it. `gmailConnector()` is the curated Gmail catalog helper; reuse it under independent aliases and accept canonical `accounts` arrays in tools (one account for writes, or an explicitly ordered supported combination for reads). See the bundled `gmail-multi-account` flagship. Bound managed secrets are supported by hosted execution. For deployed-server access to Google APIs, use `googleWorkloadIdentity({ provider: variable("GOOGLE_WIF_PROVIDER"), access: { kind: "direct" } })`, or add `serviceAccountImpersonation` with a managed service-account email. This is keyless Google Workload Identity Federation: exact Google scopes/audience come from the catalog operation, while `noodle auth google prepare|status|doctor|revoke` owns operator lifecycle. See the bundled `google-bigquery` flagship. `externalExchange()` is runnable only when the deployment operator injects an exact HTTPS provider endpoint/origin/audience and durable shared subject-pin store through service ports; Noodle sends a short-lived platform-signed deployment workload assertion and accepts only a bounded bearer response. Provider implementations must consume assertion replay ids through durable shared atomic storage across instances and restarts. There is intentionally no hosted enrollment or provider CRUD surface yet. The provider wire contract is public, but its conformance kit is workspace/source-only and is not an installable npm package. Bound `clientCredentials(...)` remains fail-closed until its provider slice lands.
 
@@ -407,6 +409,12 @@ Adapt the representative arguments and assertions when business contracts change
 
 Author managed config as `secret("NAME")` / `variable("NAME")` and operate it with `noodle secrets set` / `noodle variables set` (scoped org/app/env). Never inline secret values in `server.ts`, tests, or generated files.
 
+For business-editable configuration, declare `const notice = variable("SERVICE_NOTICE", { schema: z.string().max(500), default: "Welcome", portal: { label: "Service notice", group: "Guest experience" }, requiredFor: ["show_menu"] })` and register it in `server(..., { variables: [notice], ... }, tools)`. Use the same ref in ordinary fulfilment/connector arguments. The default is reusable safe intent; each business supplies its own values without editing source. Only explicit `portal` metadata exposes a setting. Name-only references and declared variables without `portal` remain technical configuration; secrets remain credential slots. See the bundled `acme-bistro` source.
+
+Business schemas must be bounded: booleans, finite bounded numbers, bounded text, string enums, bounded arrays, and closed objects. Put defaults in the declaration, not inside Zod schema defaults; custom transforms/refinements and arbitrary schema code cannot run in the shared runtime. `requiredFor` names existing tools whose invocation needs the value; unresolved settings must leave only dependent capabilities unavailable. Publisher compilation does not require a future buyer’s values. Application code enforces business rules server-side; exposing a control or placing the rule in a prompt is insufficient.
+
+For an installed application, use the same `noodle variables list|resolve|set|delete` family with `--installation <id> --org <org> --runtime cloud|other`; do not combine it with app/env/scope flags or secrets. Inspection shows schema metadata, provenance, readiness and revision without saved values. Set inputs are JSON (including quotes for strings), read the current projection and save atomically; `--expected-revision <digest>` pins an explicit prior inspection. Delete resets to the current declared default or unset state. Business-administrator permission is required for mutations, conflicts never retry writes, and mutation output excludes values.
+
 ## Embedded assistant
 
 To place the same server tools inside a SaaS web app, declare `assistant: embeddedAssistant(...)` alongside the one server-level brand kit. Read `embedded-assistant.md` before integrating: it owns the HTTPS-origin rule, managed model configuration, required deploy-before-client sequence, customer-backend exchange, browser mount, and verification checklist.
@@ -441,6 +449,17 @@ The compiler validates and hashes every document at build time (bad extensions,
 
 The managed crawler and managed index are the defaults and need no configuration. A component may instead bring its own crawler (`crawler: firecrawl({ apiKey: secret('FIRECRAWL_API_KEY') })` or `tavily(...)`) and/or its own index (`index: algolia({ appId: variable('ALGOLIA_APP_ID'), apiKey: secret('ALGOLIA_API_KEY') })` or `meilisearch({ host: variable(...), apiKey: secret(...) })`). The code declares only config names; operators supply values with `noodle secrets set` / `noodle variables set`, and deploy preflight fails closed naming any unset reference.
 
+## Managed collections
+
+Use `managedCollection(name, { title, description, schemaVersion, record })` when an application needs reusable typed intent for business records that Noodle may later hold. Pass it through `server(..., { collections: [...] }, definitions)`. `record` is one bounded, closed Zod object; names use lowercase letters, numbers, and underscores. Keep payment-card, credentials, passport/government identity, health, and biometric fields out of this surface.
+Native record controls are independent: `management: { assignment: true }`, `{ notes: true }`, both, or neither. Status is an ordinary application field such as `progress: z.enum(["received", "reviewing", "handled"]).default("received")`; no framework transition graph exists. Declare `publicFields` explicitly (default empty), `editableFields` for authorized staff (default all schema properties), optional field labels/help, `summaryFields`, `filterFields` and `sortFields`. References must name actual fields and filters/sorts select scalars. Public callers cannot set staff-only fields; a required private field needs a valid creation default. Staff updates merge only admitted fields and revalidate the complete record. See the notes-only `acme-bistro` collection.
+Operator record queries use `noodle solutions records list --filters '[{"field":"progress","value":"received"}]' --sort-field progress`. Only declared scalar equality/sort fields apply. Payload queries scan at most 10,000 candidates; narrow `--created-at-from`/`--created-at-to` if the API returns `query_limit_exceeded`. Ordinary listing/export has no such scan cap. Cursor reuse requires unchanged query/schema and anchor revision. An administrator can explicitly migrate an eligible historical request with `records migrate-schema ... --expected-revision N`; never implement read-time rewrites.
+
+Omitting `source` makes Noodle authoritative for the collection. To project a read-only collection from an outside system, bind an HTTP connector in `server(..., { use: [...] })` and add `source: { connector: connector.ref(), scan: "scan_operation" }`. The compiler requires the exact normalized scan contract and the same record schema. Noodle ingests a one-way replica; create, update, and delete in the outside system remain ordinary application tools with their own confirmation and policy.
+
+For an explicitly authored native operation, bind `use: { records: noodlePlatform.records.v1 }` and call `connectors.records.submitRecord({ collection: "guest_requests", payload: input })` from an ordinary confirmed tool. Submission accepts only public fields and returns a receipt. `createRecord`, `getRecord`, `listRecords`, `updateRecord`, and `deleteRecord` require a verified platform caller with a live business grant; updates/deletes require the current revision. `updateRecord({ collection, id, expectedRevision, patch, unset: ["optional_field"] })` removes named optional editable fields; omitted keys stay unchanged, `null` is data, and overlap with `patch`, required fields or undeclared fields is rejected. Runtime identity supplies write idempotency and admission; never accept those controls as model arguments. An uninstalled collection is unavailable, including during local tool execution.
+A collection declaration does not create a submit tool, grant access, select retention or residency, provision storage, or expose records to MCP or an embedded assistant. Operators activate the definition and configure lifecycle, access, and any external binding. A connector does not become a collection unless the app explicitly supplies the source contract, and an external collection never becomes a writable mirror.
+
 ## Boundaries
 
 Import public app authoring only from `@noodleseed/one` (and its documented `/react` or `/platform` subpaths). Packages and subpaths under `@noodle-borg/*` are runtime implementation details, including `/portable` boundaries, and must never appear in customer `server.ts` code. Do not hand-author manifest JSON/YAML, runtime artifacts, connector IR, or hosted asset metadata. Do not read or copy secrets, bearer tokens, refresh tokens, static access keys, `.env`, `.env.noodle`, or `~/.noodle/config.json`. Hosted access is identity-based — do not add static data-plane credential paths.

package/skills/codex/examples/acme-bistro/README.md

@@ -1,51 +1,22 @@
-# Acme Bistro — end-to-end ordering with payment-only handoff
+# Acme Bistro — ordering with payment handoff
 
-A Noodle MCP App for **Acme Bistro**, a fictional restaurant. It is the flagship for the **end-to-end
-transaction** pattern: the customer browses the menu and builds the order *in chat*, and the order
-completes in chat — only **payment** hands off, via a signed checkout deep link (the card never touches
-the app). It pairs a view-backed `tool` menu/cart with app-only `tool` cart helpers and a model-visible
-`create_checkout` tool backed by `handoff.allowedDomains`.
+Fictional [`menu/cart`](src/server.ts) with off-app payment: card data stays outside the app.
 
-Capability slot: **end-to-end in-chat transaction + payment-only handoff**, plus a worked **design-first**
-deliverable set (`design/` — a UX Document, a single-file HTML wireframe with an embedded OpenAI Apps SDK
-compliance audit, and a Recommended API contract). It sets the quality bar the `noodle-seed` skill's
-`references/experience-design.md` and `references/app-directory-compliance.md` teach. (Distinct from
-`food-ordering`, which is the broad widget-composition proof; this one owns the design-first end-to-end +
-compliance exemplar.)
+`SERVICE_NOTICE` settings and native `guest_requests` demonstrate status, field exposure and notes. `submit_guest_request` requires an authorized installation and returns a receipt
+for staff review. The installed skill's `references/authoring-workflow.md` owns setup and source contracts.
+External collections declare a bounded connector scan; provider changes remain ordinary tools.
 
-## Design deliverables (the standard to match)
+Staff can clear optional `guestReference` in Portal or an authored
+`connectors.records.updateRecord({ collection: 'guest_requests', id, expectedRevision, patch: {}, unset: ['guestReference'] })`.
+Required fields cannot be removed; `null` is a value, not deletion.
 
-- [`design/UX-Document.md`](design/UX-Document.md) — the house-style UX Document.
-- [`design/wireframe.html`](design/wireframe.html) — the single-file wireframe (open in a browser) with the
-  embedded OpenAI Apps SDK compliance audit.
-- [`design/api-contract.md`](design/api-contract.md) — the Recommended API shapes for the partner's kitchen/
-  ordering backend.
+## Design deliverables
 
-## Local author loop
+- [UX Document](design/UX-Document.md)
+- [Browser wireframe and compliance audit](design/wireframe.html)
+- [Partner API contract](design/api-contract.md)
 
-```sh
-noodle validate
-noodle test
-noodle dev
-```
+## Run
 
-In another terminal:
-
-```sh
-noodle tools list
-noodle tools call show_menu --args '{"customer":"Asha"}'
-noodle tools call create_checkout --args '{"customer":"Asha","cartToken":"cart_1","total":36}'
-noodle check --target chatgpt
-```
-
-## Deploy
-
-```sh
-noodle link --org demo --app acme-bistro
-noodle deploy --access owner-only
-noodle open
-```
-
-This example has no connector secrets and does not include tokens, caller-key mechanisms, or
-`.env.noodle` values. The menu, prices, and URLs are fictional; payment is handled off-app on
-`acme.example`, never in chat.
+Use `noodle validate`, `noodle test`, and `noodle dev` for the local menu/cart.
+Native submission requires installed storage, grants and public intake.

package/skills/codex/examples/acme-bistro/src/server.ts

@@ -1,15 +1,14 @@
-import { annotations, server, tool, z } from '@noodleseed/one';
+import {
+  annotations,
+  managedCollection,
+  noodlePlatform,
+  server,
+  tool,
+  variable,
+  z,
+} from '@noodleseed/one';
 
-// Acme Bistro is a fictional restaurant. This app is deliberately END-TO-END: the customer browses the
-// menu and builds the order in chat, and the order completes in chat — only *payment* hands off, via a
-// checkout deep link (the card never touches the app). It is the flagship for the end-to-end pattern.
-//
-// Authoring notes:
-// - A tool `fulfil` is *recorded*, not run as live JS. Inline inputs directly as `${input.x}` into
-//   output strings; do not transform them (no arithmetic/encode/filter) or substitution breaks. The
-//   cart total is summed in the widget (live React), not in a `fulfil`. The menu below is static data.
-// - Tool inputs stay business-facing. `__noodleIntent` is reserved for Noodle's optional serve-time
-//   analytics adapter and is removed before `fulfil`, so applications never declare or handle it.
+// Fictional ordering app. Payment uses a checkout link; native guest requests require installation.
 
 const menu = [
   { id: 'stone_pizza', name: 'Stone-baked Margherita', price: 14, kind: 'Mains' },
@@ -21,6 +20,14 @@ const menu = [
 
 const itemId = z.enum(['stone_pizza', 'roast_bowl', 'house_salad', 'lemon_tart', 'sparkling']);
 
+// A business administrator may change this notice; the reusable application stays the same.
+const serviceNotice = variable('SERVICE_NOTICE', {
+  schema: z.string().max(500),
+  default: 'Ask us about dietary requirements before placing your order.',
+  portal: { label: 'Service notice', group: 'Guest experience' },
+  requiredFor: ['show_menu'],
+});
+
 const menuItemOutput = z.object({
   id: z.string(),
   name: z.string(),
@@ -28,6 +35,30 @@ const menuItemOutput = z.object({
   kind: z.string(),
 });
 
+const guestRequestRecord = z.object({
+  locationReference: z.string().min(1).max(120),
+  requestType: z.enum(['reservation_help', 'accessibility', 'dietary_question', 'other']),
+  summary: z.string().min(1).max(1000),
+  guestReference: z.string().max(120).optional(),
+  progress: z.enum(['received', 'reviewing', 'handled']).default('received'),
+});
+
+const guestRequests = managedCollection('guest_requests', {
+  title: 'Guest requests',
+  description: 'Guest service requests that restaurant staff can review and resolve.',
+  schemaVersion: 1,
+  // No source is declared, so Noodle is authoritative. Outside-owned records would name an exact
+  // connector scan contract here; changes in that outside system would remain ordinary tools.
+  record: guestRequestRecord,
+  management: { notes: true },
+  publicFields: ['locationReference', 'requestType', 'summary'],
+  editableFields: ['locationReference', 'requestType', 'summary', 'guestReference', 'progress'],
+  fields: { progress: { label: 'Progress' }, summary: { label: 'Guest request' } },
+  summaryFields: ['requestType', 'summary', 'progress'],
+  filterFields: ['progress'],
+  sortFields: ['progress'],
+});
+
 // Tool annotations for host planners: the menu read is read-only; cart edits are local writes; checkout
 // opens an external (payment) link.
 const readOnly = annotations.readOnly();
@@ -52,8 +83,30 @@ export default server(
     handoff: {
       allowedDomains: ['https://pay.acme.example', 'https://acme.example'],
     },
+    // Reusable business-record intent. Storage, lifecycle, access, and public intake bind separately.
+    collections: [guestRequests],
+    use: { records: noodlePlatform.records.v1 },
+    variables: [serviceNotice],
   },
   [
+    tool('submit_guest_request', {
+      title: 'Submit a guest request',
+      description: 'Record a guest request for staff review; this does not confirm a reservation.',
+      annotations: annotations.localAction({ destructive: false, confirm: true }),
+      input: guestRequestRecord.pick({ locationReference: true, requestType: true, summary: true }),
+      output: z.object({ recordId: z.string() }),
+      fulfil: ({ input, connectors }) => {
+        const receipt = connectors.records.submitRecord({
+          collection: 'guest_requests',
+          payload: {
+            locationReference: input.locationReference,
+            requestType: input.requestType,
+            summary: input.summary,
+          },
+        });
+        return { recordId: receipt.recordId };
+      },
+    }),
     tool('show_menu', {
       title: 'Show the menu',
       description: 'Show the Acme Bistro menu and render the ordering widget.',
@@ -62,6 +115,7 @@ export default server(
       output: z.object({
         status: z.string(),
         customer: z.string(),
+        serviceNotice: z.string().max(500),
         // Bounded list: the menu is a fixed catalog, so the ceiling is declared on the shape rather
         // than taken as a pagination input. `noodle check` reports `tool_design_output_bounds`.
         items: z.array(menuItemOutput).max(50),
@@ -69,6 +123,7 @@ export default server(
       fulfil: ({ input }) => ({
         status: `Acme Bistro menu is ready for ${input.customer}. Build the order here; pay at checkout.`,
         customer: input.customer,
+        serviceNotice,
         items: menu,
       }),
       viewTitle: 'Order at Acme Bistro',

package/skills/codex/examples/acme-bistro/test/server.test.ts

@@ -18,4 +18,14 @@ describe('acme-bistro example', () => {
     expect(text).toContain('add_to_cart');
     expect(text).toContain('create_checkout');
   });
+
+  it('declares guest records and explicitly authors the native submission tool', async () => {
+    const manifest = await app.toManifest();
+    expect(manifest.server.collections).toEqual([
+      expect.objectContaining({ name: 'guest_requests', schemaVersion: 1 }),
+    ]);
+    expect(
+      manifest.tools.find((tool) => tool.name === 'submit_guest_request')?.fulfilment.steps,
+    ).toMatchObject([{ use: 'records.submit_record' }]);
+  });
 });

package/skills/codex/examples/acme-tasks/README.md

@@ -1,16 +1,11 @@
 # Acme Tasks — designed around its top-3 prioritized user flows
 
-A Noodle MCP App for **Acme Tasks**, a fictional productivity tool. It is the flagship for
-**designing an app around its prioritized user flows**: a two-way (read + write) experience where the
-top-3 flows — **Capture, Prioritize, Complete** — all happen in chat, each mapped to a tool and surfaced
-in one `TaskList` widget. It shows the "identify and prioritize the flows first, then build" discipline
-the `noodle-seed` skill's `references/experience-design.md` teaches.
-
-Capability slots: prioritized multi-flow app design, a two-way (read + write) in-chat pattern, a task-list
-widget with `tool` helpers, and a worked **design-first** artifact (the flow spec + wireframe
-below). A real deployment would connect the user's account with the end-user auth pattern — see
-[`../customer-auth/README.md`](../customer-auth/README.md); this example seeds a list so the focus stays
-on the flows.
+A fictional productivity MCP App demonstrating three prioritized flows: **Capture, Prioritize, Complete**.
+Each maps to a tool and the shared `TaskList` widget. The design spec and wireframe demonstrate the
+`noodle-seed` skill's `references/experience-design.md` workflow: prioritize user flows before building.
+
+This read/write example uses fictional seed data. A real deployment connects the user's account through
+[customer authentication](../customer-auth/README.md).
 
 ## Design spec (write this before the code)
 
@@ -150,3 +145,8 @@ do not introduce a second lockfile.
 
 This example has no connector secrets and does not include tokens, caller-key mechanisms, or
 `.env.noodle` values. All tasks are fictional seed data.
+
+## Collection scope
+
+Schema compilation is not hosted activation. External systems are changed through application tools;
+a local read-only replica does not create a second writable authority.

package/skills/codex/examples/gmail-multi-account/README.md

@@ -1,31 +1,15 @@
 # Gmail multi-account automation
 
-**Owns:** The flagship proof that one reusable connector can be bound to multiple independently
-authenticated accounts inside one MCP server.
+**Owns:** One reusable connector bound to independently authenticated accounts in one MCP server.
 
-This fictional example binds `gmailConnector()` twice through separate `externalExchange()` logical
-connections. Public tools always accept `accounts: [...]`; reads accept either account or the canonical
-personal-then-work pair, while mutations accept exactly one account and require runtime confirmation.
+[`src/server.ts`](src/server.ts) binds `gmailConnector()` twice using `externalExchange()`. Its
+`accounts` input selects either account or the ordered personal/work pair for reads. Mutations select
+one account and require confirmation against that binding. The displayed email labels are fictional;
+operators supply real authorization through the credential provider.
 
-Capability slot: **reusable connector + independently authenticated multi-account bindings**. It is distinct
-from `customer-auth`, which owns authentication of the MCP caller rather than downstream connector accounts.
-
-The labels `personal@example.com` and `work@example.com` are static display labels, not provider identities.
-The deployment-owned credential provider maps each logical connection to its real Google authorization.
-No Google client, provider account id, token, or real email address belongs in this project.
-
-## Safety and API boundary
-
-- Search, message/thread reads, draft reads, and vacation-setting reads may target one or both accounts.
-- Draft creation/update/send, label changes, archive, raw send, trash, and vacation updates target one account.
-- Every mutation is prepared against the exact selected binding and must be confirmed before dispatch.
-- `send_message.raw` and draft `raw` are RFC 2822 MIME bytes encoded with base64url. This example does not
-  pretend that `to`/`subject`/`body` strings are sufficient to encode Unicode MIME correctly.
-- Vacation `startTime`/`endTime` schemas enforce only digit-shaped 1–19 character epoch-millisecond strings.
-  When both are supplied, Gmail's backend remains authoritative for the required `startTime < endTime`
-  relationship; this example does not claim cross-field JSON Schema validation.
-- Trash is reversible. Permanent message/thread/draft deletion, delegation, forwarding/sharing settings,
-  and unrestricted raw HTTP requests are intentionally absent.
+- Message/draft `raw` values are base64url-encoded RFC 2822 MIME, not separate address/body fields.
+- Vacation timestamps validate digit shape; Gmail enforces the start-before-end relationship.
+- Trash is reversible. Permanent deletion, sharing/delegation and arbitrary HTTP requests are absent.
 
 ## Local checks
 
@@ -34,13 +18,51 @@ noodle validate
 noodle test
 ```
 
-The committed tests compile hermetic fake connector responses. They never contact Gmail or load OAuth
-credentials. A real deployment additionally needs an operator-provided external credential exchange
-endpoint for each logical connection.
+Tests use fake responses; they do not prove live Gmail authorization. Hosted execution requires an
+operator-provided external credential exchange for each logical connection. The installed skill's
+`references/authoring-workflow.md` owns binding and credential setup guidance.
+
+## Optional application-owned gateway
+
+The executable example calls Gmail directly. An application-owned gateway may additionally require a
+service key. Gmail does not require this key, and this example supplies no gateway implementation:
+
+```ts
+import {
+  bind, connection, connector, externalExchange, secret, variable, z,
+} from '@noodleseed/one';
+
+const gateway = connector('mail_gateway').version('1.0.0').http({
+  baseUrl: variable('MAIL_GATEWAY_URL'),
+  allowedOrigins: ['https://gateway.example.com'],
+  transportAuth: {
+    kind: 'apiKey',
+    header: 'X-Gateway-Key',
+    secret: secret('MAIL_GATEWAY_KEY'),
+  },
+  credentialProfiles: { account: { kind: 'bearer' } },
+  operations: {
+    inspect: {
+      type: 'read', method: 'POST', path: '/inspect',
+      credentials: { profiles: ['account'] },
+      input: z.object({}),
+      output: z.object({ available: z.boolean() }),
+    },
+  },
+});
+
+// Register this binding under server(..., { use: { mail: mailGateway } }, ...).
+const mailGateway = bind(gateway, {
+  profile: 'account',
+  connection: connection('work_mail', externalExchange()),
+});
+```
+
+The operator configures the gateway URL/key and account separately. The broker resolves both credentials;
+neither belongs in tool arguments or ordinary headers. The authored compile test checks this composition,
+not live gateway access. See the installed skill's `references/authoring-workflow.md` for transport rules.
 
 ## Personal automation skill
 
-The source skill is [`skills/personal-email-automation/SKILL.md`](skills/personal-email-automation/SKILL.md).
-Validate it with the standard skill validator before distribution. The source skill is shipped as part of
-this example; canonical export of an app and its skill as an installable Codex plugin remains roadmap work
-and is not currently provided by Noodle Seed.
+[`skills/personal-email-automation/SKILL.md`](skills/personal-email-automation/SKILL.md) is the source skill;
+validate it before distribution. Canonical app-plus-skill plugin export remains roadmap work.