@noodleseed/agent-kit 0.99.1 → 0.101.0

package/skills/codex/executing-noodle-plans/SKILL.md

@@ -3,7 +3,7 @@ name: executing-noodle-plans
 description: "Use when the user asks to execute an approved, decision-complete implementation plan for a Noodle Seed project task by task with test-first changes, review, recovery, and final verification."
 ---
 
-<!-- noodle-skill version:0.99.1 hash:6a9f132ddb79352e -->
+<!-- noodle-skill version:0.101.0 hash:6a9f132ddb79352e -->
 
 # Execute a Noodle Seed implementation plan
 

package/skills/codex/publishing-mcp-integrations/SKILL.md

@@ -3,7 +3,7 @@ name: publishing-mcp-integrations
 description: "Use when preparing, reviewing, or submitting a Noodle Seed MCP integration to a host or app directory."
 ---
 
-<!-- noodle-skill version:0.99.1 hash:0ccafb222038f553 -->
+<!-- noodle-skill version:0.101.0 hash:0ccafb222038f553 -->
 
 # publishing-mcp-integrations
 

package/skills/codex/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/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/references/compile-errors.md

@@ -18,7 +18,7 @@ Run `noodle validate` (add `--json` for the machine-readable envelope, `--fix-pr
 | `invalid_shape` | A field has the wrong type or structure; match the shape the compiler reports under `path` against the SDK builder you used. |
 | `invalid_name` | Rename the identifier to match the allowed pattern (lowercase, no spaces/reserved characters) cited at `path`. |
 | `duplicate_name` | Two tools/components share a name; give each a unique name at the cited `path`. |
-| `reserved_name` | Rename the reserved identifier; `__noodleIntent` is platform-owned, while application context uses one explicit zero-input tool with `contextProvider: true`. |
+| `reserved_name` | Rename the reserved identifier; `__noodleIntent` and future managed-collection `submit_<name>` tools are platform-owned, while application context uses one explicit zero-input tool with `contextProvider: true`. |
 | `unsupported_manifest_version` | Update the SDK/CLI so the emitted manifest version is supported; do not pin an old manifest shape. |
 | `reserved_for_future_version` | The verb at `path` (currently `compute` as a flow step) is reserved for a future core version; express the step with `use` (a connector operation), `map` (a pure mapping), or the shipped `ctx.elicit` input primitive instead. |
 | `invalid_operation_ref` | Fix the connector operation reference to `alias.operation` for an operation that exists on that connector. |
@@ -58,6 +58,9 @@ Run `noodle validate` (add `--json` for the machine-readable envelope, `--fix-pr
 | `state_secret_field` | Remove the secret-shaped field from widget/handle state; secrets must never be stored in state or sent to widgets. |
 | `invalid_knowledge` | Fix the `knowledge()` declaration: documents must be existing UTF-8 `.md`/`.txt` files inside the project root (no symlinks), within the 100-file / 1 MiB / 25 MiB bounds, and sites need an exact HTTPS origin plus at least one include glob. |
 | `knowledge_unhashed` | Compile from the project root (`noodle validate`/`noodle dev`) so declared knowledge documents can be read and hashed. |
+| `invalid_managed_collection` | Fix the `managedCollection()` declaration: use a bounded, closed Zod object without credential, payment-card, government-identity, health, or biometric field names. |
+| `invalid_variable_declaration` | Fix the typed `variable()` declaration: use a bounded closed schema, a matching JSON default, plain Portal metadata, existing requiredFor tool names, and one consistent definition per key. |
+| `invalid_managed_collection_source` | Bind the declared source connector and select read-only scan operations whose closed normalized envelopes use the collection record schema exactly. |
 | `unknown_connector_alias` | The tool calls a connector alias not declared in `use`/`provides`; add it or fix the alias (see `suggestions`). |
 | `connector_not_in_catalog` | The referenced connector is not in the resolved catalog; add it to the project connectors or correct the reference. |
 | `unknown_operation` | The connector has no such operation; use an operation declared on that connector (see `didYouMean`/`suggestions`). |

package/skills/codex/references/sdk-surface.md

@@ -37,7 +37,7 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 ### Managed config
 
 - `secret("NAME")` — reference a managed secret (operated via `noodle secrets`).
-- `variable("NAME")` — reference a managed variable (operated via `noodle variables`).
+- `variable("NAME")` — reference managed configuration; add `{ schema, default?, portal?, requiredFor? }` and register in `server.variables` for typed business settings. Operate through `noodle variables` or authorized Portal settings.
 
 ### Customer auth
 
@@ -63,9 +63,11 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 - `firecrawl`
 - `gmailConnector`
 - `knowledge`
+- `managedCollection`
 - `managedSecret`
 - `meilisearch`
 - `noodleManaged`
+- `noodlePlatform`
 - `openAICompatible`
 - `publicWebsite`
 - `site`

package/skills/codex/reporting-noodle-feedback/SKILL.md

@@ -3,7 +3,7 @@ name: reporting-noodle-feedback
 description: "Use when a Noodle Seed bug, misleading instruction, missing capability, or concrete product improvement should be proposed to the user."
 ---
 
-<!-- noodle-skill version:0.99.1 hash:660cc6ad9469d90f -->
+<!-- noodle-skill version:0.101.0 hash:660cc6ad9469d90f -->
 
 # reporting-noodle-feedback
 

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

@@ -3,7 +3,7 @@ name: verifying-mcp-delivery
 description: "Use when proving a Noodle Seed MCP project works at a named compile, local, connector, App, host, deployment, or production evidence level."
 ---
 
-<!-- noodle-skill version:0.99.1 hash:292253cbaed9a3c5 -->
+<!-- noodle-skill version:0.101.0 hash:292253cbaed9a3c5 -->
 
 # verifying-mcp-delivery
 

package/skills/codex/wrapping-existing-applications/SKILL.md

@@ -3,7 +3,7 @@ name: wrapping-existing-applications
 description: "Use when an existing application has no stable usable API and needs a read-only, identity-first Noodle Seed integration plan before implementation."
 ---
 
-<!-- noodle-skill version:0.99.1 hash:379ab9f64878f1fe -->
+<!-- noodle-skill version:0.101.0 hash:379ab9f64878f1fe -->
 
 # wrapping-existing-applications
 

package/skills/codex/wrapping-existing-applications/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.