@reunionstudio/airlock-mcp 0.1.8 → 0.1.9

package/.agents/skills/airlock-mcp/SKILL.md

@@ -229,6 +229,17 @@ Airlock:
 - `airlock.admin.*` performs administrative changes and operational mutations.
 - `airlock.agent.*` performs governed user or agent work in the actor's scope.
 
+Installed Airlock may also expose separate opt-in Snowflake-managed MCP
+endpoints for `app_agent` and `app_observer`. They are distinct from this local
+spec-workbench MCP server. Administrators manage them with
+`admin.enable_mcp_server`, `admin.disable_mcp_server`, and
+`observe.mcp_servers`. Their fixed allowlists contain five agent tools
+(`airlock_my_access_context`, work, safe spec description, spec states, and file
+state) and four observer tools (specs, work, spec states, and file state). They
+never expose mutation, governed payload rows, restricted-reference reads, or
+attachment bytes. Each client must authenticate as its own Snowflake principal;
+workspace identity is not Airlock authority.
+
 Treat every mutating human or automated agent as an attributable Snowflake
 principal. Direct work uses that principal's Airlock assignments. Work for
 another principal requires explicit Airlock delegation and

package/.cortex-plugin/activation.md

@@ -10,5 +10,11 @@ work, `airlock.observe.*` for read-only observation, and `airlock.admin.*` only
 for intentional administration. Use explicit Airlock delegation when the
 connected principal acts for another principal.
 
+Do not confuse this local spec-workbench MCP server with the optional
+Snowflake-managed MCP endpoints exposed by an installed Airlock Native App.
+Those role-separated agent and observer endpoints preserve Snowflake identity
+and expose only fixed read-only tools; they do not expose mutation or governed
+payload rows.
+
 Never store credentials in this plugin or its workspace files. Configure the
 Airlock MCP connection through the supported environment or connection setup.

package/.cortex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "airlock-mcp",
   "description": "Governed Airlock spec, observation, and commitment guidance for Snowflake principals.",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "author": {
     "name": "Reunion Studio",
     "url": "https://github.com/reunionstudio/airlock-mcp"
@@ -15,7 +15,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@reunionstudio/airlock-mcp@0.1.8",
+        "@reunionstudio/airlock-mcp@0.1.9",
         "server"
       ]
     }

package/README.md

@@ -54,6 +54,13 @@ Current Airlock separates procedure intent:
   specs, validating/loading data, workflow actions, attachments, delegations,
   and references.
 
+Installed Airlock can also expose a deliberately small read-only subset through
+separate Snowflake-managed Native App MCP servers for `app_agent` and
+`app_observer`. They are opt-in, preserve the authenticated Snowflake principal,
+and do not replace the public procedure API or this package's local workbench.
+See [Native App managed MCP](docs/native-app-managed-mcp.md) for the fixed tool
+allowlists, setup calls, identity proof, and security boundary.
+
 Every mutating human or automated agent should connect as its own attributable
 Snowflake principal. When it acts for another principal, use explicit Airlock
 delegation. Snowflake user type, chat identity, channel membership, workspace
@@ -78,18 +85,21 @@ current work, and
 `airlock.observe.activity(...)` for historical events. The older split work
 procedures are retired.
 
-Polling agents should call `airlock.agent.spec_state(...)` before retrieving a
-complete descriptor, file list, or governed dataset. Cache the
-authorization-scoped `STATE_TOKEN` and perform the heavier read only when it
-changes. Poll `airlock.agent.list_my_work(...)` independently because deadlines
-and expectation windows can change with time without rotating a spec token.
+Polling agents should call `airlock.agent.spec_state(...)` for one known spec,
+or `airlock.agent.spec_states(...)` for up to 100 known specs under one role
+lens, before retrieving complete descriptors, file lists, or governed datasets.
+Cache each authorization-scoped `STATE_TOKEN` and perform the heavier read only
+when it changes. Poll `airlock.agent.list_my_work(...)` independently because
+deadlines and expectation windows can change with time without rotating a spec
+token.
 After selecting a logical file, compare
 `airlock.agent.file_state(...).FILE_STATE_ID`; that UUID rotates when its data,
 workflow, attachments, exact source references, or retained version history
 change. Observer clients use
-the authorization-scoped, read-only `observe.spec_state(...)` and
-`observe.file_state(...)` equivalents. A missing object or revoked observer
-grant returns no row, which is the terminal polling signal; authorized query
+the authorization-scoped, read-only `observe.spec_state(...)`,
+`observe.spec_states(...)`, and `observe.file_state(...)` equivalents. Missing
+or inaccessible specs are omitted from a batched result without disclosing the
+cause; that omitted row is the terminal polling signal. Authorized query
 failures remain procedure errors.
 
 ### Observer Access And Seats

package/SECURITY.md

@@ -12,8 +12,25 @@ operation surface.
 - Validates MCP server names before passing them to `codex mcp add`.
 - Passes npm or GitHub package specs as argv entries, never through a shell.
 - Rejects package specs with whitespace or control characters.
-- Exposes guidance only; it does not read local secrets, call Snowflake, mutate
-  files, or contact network services.
+- Does not read local secrets, call Snowflake, or contact network services.
+  Workbench tools write only the project files explicitly requested by the
+  caller.
+
+## Installed Native App MCP
+
+Installed Airlock can separately expose opt-in Snowflake-managed MCP endpoints.
+They are not hosted by this npm package and do not inherit local workspace
+identity. Their fixed agent and observer allowlists expose only read-only access
+context, work, safe spec discovery, and compact spec/file state. They exclude
+administrative or governed mutation, governed payload rows, restricted-reference
+reads, and attachment bytes.
+
+Each client must authenticate as its own Snowflake principal with a role that
+holds the matching Airlock application role and can use the configured
+warehouse. The endpoint adapters call Airlock's existing handlers, so procedure
+authorization, role lenses, observer scope, and license policy remain the
+security boundary. Only fixed adapters in the role-accessible versioned `mcp`
+schema are granted; Airlock's private `internal` schema remains ungranted.
 
 ## Production Rules
 

package/docs/architecture.md

@@ -36,10 +36,23 @@ product surface.
 
 ## MCP Surface
 
+There are two complementary MCP surfaces:
+
+- This package is a local bootstrap and spec-workbench server. It does not call
+  Snowflake or become an Airlock authorization layer.
+- Installed Airlock may expose optional Snowflake-managed Native App MCP
+  servers over nine fixed read-only adapters. Those endpoints execute inside
+  Snowflake as the authenticated principal and retain the existing `agent.*`
+  and `observe.*` policy checks.
+
+See [Native App managed MCP](native-app-managed-mcp.md) for the installed
+surface. The remainder of this section describes this package's local server.
+
 The bootstrap server exposes:
 
 - prompt: `airlock-start`
 - resource: `airlock://getting-started`
+- resource: `airlock://native-app-managed-mcp`
 - orientation tool: `airlock_start`
 - workbench tools: `airlock_doctor`, `airlock_init_repo`,
   `airlock_init_app_context`, `airlock_list_patterns`,

package/docs/native-app-managed-mcp.md

@@ -0,0 +1,67 @@
+# Native App Managed MCP
+
+Installed Airlock can optionally expose separate Snowflake-managed MCP servers
+for agent-scoped and observer-scoped reads. The stored procedures remain the
+authoritative API; MCP is a small transport adapter over existing policy checks.
+
+This is distinct from the local `airlock-mcp` package. The package helps agents
+design specs and build Airlock-aware software. It does not automatically query
+Snowflake. The Native App endpoints run in the consumer account and require an
+independently authenticated Snowflake principal.
+
+## Enablement
+
+Airlock does not create MCP objects during installation. An app administrator
+must opt in and name a usable warehouse:
+
+```sql
+CALL airlock.admin.enable_mcp_server('agent', 'AGENT_WH');
+CALL airlock.admin.enable_mcp_server('observer', 'OBSERVER_WH');
+CALL airlock.observe.mcp_servers();
+```
+
+Use `validate_only => TRUE` to check the fixed plan without DDL. Disable an
+endpoint with `airlock.admin.disable_mcp_server('agent')` or `'observer'`.
+Disable and re-enable to change its warehouse or refresh its specification
+after an Airlock upgrade.
+
+The authenticated Snowflake role needs warehouse access and the matching
+Airlock application role. Each mutating human or automated agent must retain
+its own Snowflake principal; never use a shared MCP credential as a
+meta-permission layer.
+
+## Fixed Read-Only Tools
+
+The agent endpoint exposes:
+
+- `airlock_my_access_context`
+- `airlock_list_my_work`
+- `airlock_describe_spec`
+- `airlock_spec_states`
+- `airlock_file_state`
+
+The observer endpoint exposes:
+
+- `airlock_observe_specs`
+- `airlock_observe_work`
+- `airlock_observe_spec_states`
+- `airlock_observe_file_state`
+
+Neither endpoint exposes mutation, `admin.*`, governed row reads,
+restricted-reference reads, or attachment bytes. Agent calls retain ordinary
+assignment, role-lens, and named-license checks. Observer calls retain
+assignment-scoped observer access and do not claim a named license.
+
+Snowflake's managed SQL transport requires scalar `VARIANT` results, so the
+servers target fixed adapters in Airlock's versioned `mcp` schema. Those
+adapters invoke the same handlers as the public read procedures. Only the fixed
+adapters are granted; Airlock's private `internal` schema remains ungranted.
+
+## Principal Proof
+
+Before relying on a new PAT-based client, run Airlock's
+`scripts/run_batch62_mcp_identity_probe.py` with two independently issued,
+role-restricted Snowflake programmatic access tokens. The proof must return two
+distinct matching `USER_ID` values from `airlock_my_access_context`. External
+workspace, channel, bot, or public-key identifiers are provenance only and
+never confer Airlock authority.

package/docs/principal-workspace-interoperability.md

@@ -26,12 +26,12 @@ or chat approvals as Snowflake authority.
 
 Use state tokens before larger reads:
 
-- `agent.spec_state(...).STATE_TOKEN` for the actor's visible contract, data,
-  and access state;
+- `agent.spec_state(...).STATE_TOKEN` for one actor-visible spec, or
+  `agent.spec_states(...)` for up to 100 known specs under one role lens;
 - `agent.file_state(...).FILE_STATE_ID` for one visible file's data, workflow,
   attachment, reference, and retained-version state;
-- `observe.spec_state` and `observe.file_state` for a scoped observer principal;
-  and
+- `observe.spec_state`, `observe.spec_states`, and `observe.file_state` for a
+  scoped observer principal; and
 - `agent.list_my_work` or `observe.work` on a separate cadence for deadlines
   and current work.
 
@@ -39,6 +39,11 @@ A missing state row is the terminal result for that cursor. Return to discovery
 instead of inferring whether the object was deleted, retired, or became
 inaccessible.
 
+Plural spec polling preserves first-request order after case-insensitive
+deduplication and omits missing or inaccessible targets without identifying the
+cause. Use it for one logical multi-spec polling cycle; keep the singular call
+for one target.
+
 ## Commitment receipts
 
 After every supported `agent.*` or intentional `admin.*` mutation, store a

package/docs/workflows.md

@@ -209,17 +209,18 @@ confirm the principal no longer needs `agent.*` or Streamlit before calling
 `admin.unassign_license(...)`. Never share one Snowflake username across
 channels merely to simplify setup; that collapses attribution and revocation.
 
-Watcher loops should call `agent.spec_state` before larger reads. Cache its
-authorization-scoped `STATE_TOKEN` and retrieve descriptors, file lists, or
-governed data only when it changes. Poll `agent.list_my_work` independently
-because deadlines and expectation windows can change without rotating the spec
-token. Once the app tracks one logical file,
+Watcher loops should call `agent.spec_state` for one known spec or
+`agent.spec_states` for up to 100 known specs under one role lens before larger
+reads. Cache each authorization-scoped `STATE_TOKEN` and retrieve descriptors,
+file lists, or governed data only when it changes. Poll `agent.list_my_work`
+independently because deadlines and expectation windows can change without
+rotating a spec token. Once the app tracks one logical file,
 compare `agent.file_state(...).FILE_STATE_ID` to detect data replacement,
 workflow movement, attachment changes, exact-reference changes, or retained
 version-history changes. Observer principals use the authorization-scoped,
-read-only `observe.spec_state` and `observe.file_state` equivalents. A missing
-object or revoked grant returns no row as the terminal polling signal;
-authorized query failures remain procedure errors.
+read-only `observe.spec_state`, `observe.spec_states`, and `observe.file_state`
+equivalents. Missing or inaccessible specs are omitted from a plural result as
+the terminal polling signal; authorized query failures remain procedure errors.
 
 Every mutating human or automated agent should connect as an attributable
 Snowflake principal. When it acts for another principal, use explicit Airlock

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reunionstudio/airlock-mcp",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Single-install MCP interface for Airlock agents.",
   "type": "module",
   "repository": {

package/setup.py

@@ -27,7 +27,7 @@ def data_files():
 
 setup(
     name="airlock-mcp",
-    version="0.1.8",
+    version="0.1.9",
     description="Codex-first workbench and CLI for drafting Airlock specs.",
     packages=find_packages("src"),
     package_dir={"": "src"},

package/src/airlock_mcp/__init__.py

@@ -1,3 +1,3 @@
 """Airlock MCP CLI package."""
 
-__version__ = "0.1.8"
+__version__ = "0.1.9"

package/src/airlock_mcp/app_context.py

@@ -42,6 +42,14 @@ Installed Airlock separates procedure intent:
 - `agent.*`: governed agent work in the actor's scope.
 - `admin.*`: administrative mutation and operational changes.
 
+Installed Airlock may separately expose opt-in Snowflake-managed MCP endpoints
+for `app_agent` and `app_observer`. They use fixed read-only tool allowlists,
+preserve each client's authenticated Snowflake principal, and never expose
+mutation, governed payload rows, restricted-reference reads, or attachment
+bytes. They are distinct from the local Airlock MCP spec workbench. Manage them
+with `admin.enable_mcp_server`, `admin.disable_mcp_server`, and
+`observe.mcp_servers`.
+
 Use `agent.list_my_work` for the actor's unified current-work inbox,
 `observe.work` for account-wide current work, and `observe.activity` for
 historical events. The older split workflow/expectation work calls are retired.
@@ -139,6 +147,12 @@ Installed Airlock procedure grammar:
 - `admin.*` is administrative mutation. Do not use retired admin read wrappers;
   use observe list/detail procedures instead.
 
+An installed Airlock app may also provide separate opt-in Snowflake-managed MCP
+endpoints for `app_agent` and `app_observer`. Their fixed tools are read-only,
+retain the authenticated Snowflake principal, and exclude mutation and governed
+payload reads. Do not confuse those endpoints with the local Airlock MCP spec
+workbench or treat workspace identity as Airlock authority.
+
 Use `agent.list_my_work` for the current actor's unified work inbox. Use
 `observe.work` for account-wide current work and `observe.activity` for event
 history.
@@ -224,6 +238,7 @@ def _manifest(mode: str, entries: list[dict[str, Any]]) -> dict[str, Any]:
             "required_source_references": "load Draft, list eligible sources, pin exact manifest rows, then advance; SOURCE_REFERENCE_REQUIRED blocks missing evidence",
             "spec_migration": "immutable two-version lifecycle; list with observe.spec_migrations, run bounded admin migration batches, inspect observe.spec_migration evidence, cancel only before activation, and retire only after the source is drained",
             "admin": "administrative mutation and operational changes",
+            "native_mcp": "optional role-separated Snowflake-managed read-only endpoints; fixed agent and observer tools preserve Snowflake principal identity and never expose mutation or governed payload rows",
             "restricted_reference": "one-record reference lookup through agent.get_reference_record; do not enumerate protected reference paths",
             "attachment_preview": "governed Streamlit preview emits metadata-only ATTACHMENT_PREVIEW; MCP clients do not get direct stage access",
             "application_surface": "built-in Streamlit is a generic operating/fallback surface; purpose-built apps own domain UI and use Airlock as the governed backend",

package/src/airlock_mcp/bootstrap.py

@@ -126,6 +126,15 @@ Installed Airlock separates procedure intent:
 - `agent.*`: governed agent work in the actor's scope.
 - `admin.*`: administrative mutation and operational changes.
 
+Installed Airlock may also expose separate opt-in Snowflake-managed MCP
+endpoints for `app_agent` and `app_observer`. They are distinct from this local
+spec-workbench MCP server and contain only fixed read-only tools for access
+context, work, safe spec discovery, and compact spec/file state. They preserve
+the authenticated Snowflake principal and never expose mutation, governed
+payload rows, restricted-reference reads, or attachment bytes. Administrators
+manage them through `admin.enable_mcp_server`, `admin.disable_mcp_server`, and
+`observe.mcp_servers`.
+
 Use `agent.list_my_work` for the actor's unified current-work inbox,
 `observe.work` for account-wide current work, and `observe.activity` for
 historical events. The older split workflow/expectation work calls are retired.

package/src/mcp.mjs

@@ -1,9 +1,15 @@
 import readline from "node:readline";
 
-import { PROTOCOL_VERSION, airlockPrompt, gettingStartedText } from "./text.mjs";
+import {
+  PROTOCOL_VERSION,
+  airlockPrompt,
+  gettingStartedText,
+  nativeAppManagedMcpText,
+} from "./text.mjs";
 import { WORKBENCH_TOOLS, callWorkbenchTool } from "./workbench.mjs";
 
 const GETTING_STARTED_URI = "airlock://getting-started";
+const NATIVE_APP_MANAGED_MCP_URI = "airlock://native-app-managed-mcp";
 
 const START_TOOL = {
   name: "airlock_start",
@@ -44,10 +50,10 @@ export function handleMcpRequest(message) {
       },
       serverInfo: {
         name: "airlock",
-        version: "0.1.8",
+        version: "0.1.9",
       },
       instructions:
-        "Airlock MCP helps agents improve processes with Airlock specs and build apps or workflows that use existing specs. Use airlock_start for orientation or the airlock_* tools to bootstrap, draft, check, summarize, export, and render specs.",
+        "Airlock MCP is the local spec workbench and app-context bootstrap server. Use airlock_start for orientation or the airlock_* tools to bootstrap, draft, check, summarize, export, and render specs. Installed Airlock can separately expose opt-in Snowflake-managed read-only MCP endpoints; read airlock://native-app-managed-mcp for their fixed tools and security boundary.",
     });
   }
 
@@ -122,20 +128,30 @@ export function handleMcpRequest(message) {
           description: "How to start building and using Airlock specs with Codex.",
           mimeType: "text/markdown",
         },
+        {
+          uri: NATIVE_APP_MANAGED_MCP_URI,
+          name: "Installed Airlock Native App MCP",
+          description: "Opt-in Snowflake-managed read-only endpoints exposed by an installed Airlock Native App.",
+          mimeType: "text/markdown",
+        },
       ],
     });
   }
 
   if (method === "resources/read") {
-    if (params?.uri !== GETTING_STARTED_URI) {
+    if (params?.uri !== GETTING_STARTED_URI && params?.uri !== NATIVE_APP_MANAGED_MCP_URI) {
       return makeError(id, -32602, `unknown resource: ${params?.uri || ""}`);
     }
+    const text =
+      params.uri === NATIVE_APP_MANAGED_MCP_URI
+        ? nativeAppManagedMcpText()
+        : gettingStartedText("Home");
     return makeResponse(id, {
       contents: [
         {
           uri: params.uri,
           mimeType: "text/markdown",
-          text: gettingStartedText("Home"),
+          text,
         },
       ],
     });

package/src/text.mjs

@@ -56,20 +56,28 @@ access, which specs are read sources, which spec records decisions or actions,
 and where the app should run. Teach the installed Airlock procedure split:
 \`airlock.observe.*\` is read-only governance observation,
 \`airlock.agent.*\` is governed agent work, and \`airlock.admin.*\` is
-administrative mutation. Prefer observe payloads such as
+administrative mutation. Installed Airlock may also expose separate opt-in
+Snowflake-managed MCP endpoints for the agent and observer application roles.
+Those endpoints have fixed read-only tool allowlists and preserve the
+authenticated Snowflake principal; they are not this local spec-workbench MCP
+server. They never expose mutation, governed payload rows, restricted-reference
+reads, or attachment bytes. Prefer observe payloads such as
 \`observe.procedures\`, \`observe.specs\`, \`observe.spec\`,
 \`observe.governance_map\`, \`observe.explain_access\`, \`observe.health\`,
 \`observe.activity\`, \`observe.admin_activity\`, \`observe.spec_admin_activity\`,
 and \`observe.billing_events\` before inventing custom read paths. For \`alter_spec\`
 activity, use \`CHANGED_SECTIONS\` and \`CHANGED_FIELDS\` to triage what changed
-before fetching version snapshots. For polling loops, cache the role-scoped
-\`agent.spec_state(...).STATE_TOKEN\` and do larger reads only when it changes.
+before fetching version snapshots. For polling loops, use
+\`agent.spec_state(...).STATE_TOKEN\` for one known spec or
+\`agent.spec_states(...)\` for up to 100 known specs under one role lens, and
+do larger reads only when a token changes.
 After selecting one logical file, compare
 \`agent.file_state(...).FILE_STATE_ID\` to detect data, workflow, attachment,
 exact-reference, or retained version-history changes. Observer principals may use
-the authorization-scoped \`observe.spec_state\` and \`observe.file_state\`
-equivalents. A missing object or revoked observer grant returns no row as the
-terminal polling signal; authorized query failures remain errors. Holding
+the authorization-scoped \`observe.spec_state\`, \`observe.spec_states\`, and
+\`observe.file_state\` equivalents. Missing or inaccessible specs are omitted
+from a plural result without disclosing the cause; that omitted row is the
+terminal polling signal. Authorized query failures remain errors. Holding
 \`app_observer\` opens only the read-only procedure family; Airlock
 assignments plus \`observer_access.observer_roles\` determine spec visibility,
 and account-wide observation requires \`app_admin\` or the locked Airlock role
@@ -164,6 +172,7 @@ Airlock MCP will offer:
   - spec design with the bundled workbench
   - Airlock operating patterns for OODA loops and separation of duties
   - read-only observe procedures for governance maps, health, access explanation, activity, billing events, and context packets
+  - the optional role-separated Snowflake-managed MCP endpoints exposed by installed Airlock
   - scoped spec and file state tokens for efficient polling
   - app context seeding with spec snapshots and manifests
   - app and workflow coding against existing Airlock specs
@@ -175,6 +184,78 @@ Airlock MCP will offer:
   - airlock-specs library patterns as starting points, checked against current artifacts`;
 }
 
+export function nativeAppManagedMcpText() {
+  return `# Installed Airlock Native App MCP
+
+This npm package runs a local spec workbench and app-context bootstrap MCP
+server. An installed Airlock Native App can separately expose two opt-in,
+Snowflake-managed MCP endpoints for governed operational discovery. Enabling
+those endpoints does not turn this local server into a Snowflake client.
+
+## Enable And Inspect
+
+An Airlock administrator selects a warehouse and enables each interface
+explicitly. Replace \`airlock\` with the installed application object name when
+it differs:
+
+\`\`\`sql
+CALL airlock.admin.enable_mcp_server('agent', 'AGENT_WH', TRUE);
+CALL airlock.admin.enable_mcp_server('agent', 'AGENT_WH');
+CALL airlock.admin.enable_mcp_server('observer', 'OBSERVER_WH');
+CALL airlock.observe.mcp_servers();
+\`\`\`
+
+The first call is validate-only. Use
+\`airlock.admin.disable_mcp_server('agent')\` or \`'observer'\` to remove an
+endpoint. Disable and re-enable an endpoint to change its warehouse or refresh
+its fixed tool specification after an Airlock upgrade. The client principal's
+Snowflake role must be able to use the selected warehouse and hold the matching
+Airlock application role.
+
+## Fixed Tool Allowlists
+
+The agent endpoint, \`core.airlock_agent_mcp\`, exposes only:
+
+- \`airlock_my_access_context\`
+- \`airlock_list_my_work\`
+- \`airlock_describe_spec\`
+- \`airlock_spec_states\`
+- \`airlock_file_state\`
+
+The observer endpoint, \`core.airlock_observer_mcp\`, exposes only:
+
+- \`airlock_observe_specs\`
+- \`airlock_observe_work\`
+- \`airlock_observe_spec_states\`
+- \`airlock_observe_file_state\`
+
+Neither endpoint exposes \`admin.*\`, governed or administrative mutation,
+governed payload rows, restricted-reference reads, or attachment bytes. Existing
+Airlock procedure authorization remains the policy boundary. Except for the
+non-claiming \`airlock_my_access_context\` tool, agent tools retain ordinary
+named-license enforcement and may auto-assign a license when consumer policy
+allows it. Observer tools neither require nor assign a named license.
+
+## Identity And Transport Boundary
+
+Every MCP client should authenticate as its own Snowflake principal. A shared
+token, workspace role, channel identity, or external agent id does not create
+Airlock authority. Treat external identity metadata as provenance only; use
+Airlock delegation when one authenticated principal acts for another.
+
+The endpoint specifications target scalar \`VARIANT\` adapters in Airlock's
+role-accessible, versioned \`mcp\` transport schema because Snowflake's managed
+MCP SQL API consumes JSONV2 rather than Arrow table results. The adapters call
+the same read-only handlers and retain the same authorization, role-lens,
+observer-scope, and license checks as the public procedures. Only the fixed
+adapters are granted from \`mcp\`; Airlock's private \`internal\` schema remains
+ungranted.
+
+Use \`airlock_my_access_context\` first when validating a new agent connection,
+and require that independently issued credentials return their exact distinct
+\`USER_ID\` values.`;
+}
+
 export function gettingStartedText(project) {
   return `# Airlock MCP
 
@@ -198,6 +279,13 @@ Airlock MCP gives agents four kinds of Airlock help:
    context packets, and governance maps before deciding what an app or agent
    should do.
 
+Installed Airlock can also expose separate opt-in, role-separated,
+Snowflake-managed read-only MCP endpoints. They preserve the authenticated
+Snowflake principal and use fixed agent and observer tool allowlists. They are
+distinct from this local spec-workbench server. Read
+\`airlock://native-app-managed-mcp\` for the exact tools, lifecycle procedures,
+licensing behavior, and security boundary.
+
 Start in a Git-backed specs repo such as ${specsRepoName(project)}. GitHub is
 the recommended default when the user has it set up, but any normal repository
 works. If Codex is creating the repo, ask where the directory should live before
@@ -258,13 +346,16 @@ read-side discovery with observe payloads such as \`observe.procedures\`,
 \`observe.explain_access\`, \`observe.health\`, \`observe.activity\`,
 \`observe.admin_activity\`, \`observe.spec_admin_activity\`, and \`observe.billing_events\`;
 for \`alter_spec\` activity, use \`CHANGED_SECTIONS\` and \`CHANGED_FIELDS\` to
-triage what changed before fetching version snapshots. For polling loops, poll
-\`agent.spec_state\` and compare its scoped \`STATE_TOKEN\` before larger reads;
+triage what changed before fetching version snapshots. For polling loops, use
+\`agent.spec_state\` for one known spec or \`agent.spec_states\` for up to 100
+known specs under one role lens, and compare scoped \`STATE_TOKEN\` values before
+larger reads;
 compare \`agent.file_state(...).FILE_STATE_ID\` for one selected file. Observer
-principals use \`observe.spec_state\` and \`observe.file_state\` for
-authorization-scoped read-only state. File-state UUIDs include retained
-version-history changes. A missing object or revoked grant returns no row as
-the terminal polling signal; authorized query failures remain errors.
+principals use \`observe.spec_state\`, \`observe.spec_states\`, and
+\`observe.file_state\` for authorization-scoped read-only state. File-state
+UUIDs include retained version-history changes. Missing or inaccessible specs
+are omitted from a plural result as the terminal polling signal; authorized
+query failures remain errors.
 \`app_observer\` grants access to the
 read-only procedure family; Airlock assignments and
 \`observer_access.observer_roles\` grant spec visibility. Observe-only calls do