@reunionstudio/airlock-mcp 0.1.3 → 0.1.5

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

@@ -74,19 +74,28 @@ deterministic checker for local spec drafts.
 4. Create `posts` only when the user chooses a feedback loop, asks for humans
    and agents to provide feedback, or explicitly requests the posts pattern.
    If the user is unsure, continue process discovery before creating files.
-5. Use `airlock-mcp import-spec <json-file> <name>` when starting from a
+5. Create `okf-knowledge-bundle` when the user needs governed Markdown
+   knowledge, accepted agent context, policies, runbooks, metric definitions,
+   investigations, or other business context organized as an OKF-style bundle.
+   The spec must declare `core_config.payload_adapter =
+   "okf_knowledge_bundle"`. Installed Airlock loads validated bundles with
+   `airlock.admin.load_okf_bundle(...)`, can sync parsed metadata with
+   `airlock.admin.sync_okf_bundle_metadata(...)`, and exposes authoritative
+   accepted context through `AIRLOCK_DATA.ACTIVE.V_OKF_CONCEPT_METADATA`.
+   Draft and rejected bundles are not authoritative agent context.
+6. Use `airlock-mcp import-spec <json-file> <name>` when starting from a
    spec-library file, an exported `SPEC_CONFIG`, or an existing canonical config.
    If the source is from `airlock-specs`, treat it as a reusable draft pattern.
    Check actual API docs, CSV/Excel/JSON samples, schemas, or other artifacts
    before assuming the source fields match a live third-party system.
-6. Use `airlock-mcp clone <source-workspace> <name>` when creating a related
+7. Use `airlock-mcp clone <source-workspace> <name>` when creating a related
    draft from an existing workspace. Treat clone like the old Streamlit UI:
    preserve the shape but deliberately reset spec identity.
-7. Keep the draft small. Prefer one useful governed output over a large
+8. Keep the draft small. Prefer one useful governed output over a large
    speculative system, then keep a plan for later specs.
-8. On later sessions, run `airlock-mcp list-workspaces` when the target draft
+9. On later sessions, run `airlock-mcp list-workspaces` when the target draft
    is not obvious.
-9. Run `airlock-mcp summary <workspace>` and
+10. Run `airlock-mcp summary <workspace>` and
    `airlock-mcp next <workspace>` before editing so
    the current shape, sample count, access model, and local check status are
    visible.
@@ -94,14 +103,14 @@ deterministic checker for local spec drafts.
    core, file rules, attachments, guest access, column rules, samples, notes,
    and check status. Do not make the user infer the current spec from file
    links alone.
-10. Run `airlock-mcp check <workspace>` after changing draft config or sample
+11. Run `airlock-mcp check <workspace>` after changing draft config or sample
    records.
-11. Keep `sample.records.json` as the agent-friendly authoring shape. Use
+12. Keep `sample.records.json` as the agent-friendly authoring shape. Use
    `airlock-mcp export-csv <workspace>` when the same examples need to be
    reviewed or loaded through Airlock's CSV path.
-12. Use `airlock-mcp rename`, `archive`, and `restore` when organizing
+13. Use `airlock-mcp rename`, `archive`, and `restore` when organizing
    workspaces so spec identity changes remain deliberate.
-13. Use `airlock-mcp render-sql <workspace>` only as a validate-only review
+14. Use `airlock-mcp render-sql <workspace>` only as a validate-only review
    artifact. Installed Airlock validation remains authoritative.
 
 ## Spec Design Questions
@@ -199,6 +208,44 @@ Start by identifying:
    user's environment.
 6. Identity, evidence, timestamps, approval, and separation-of-duties rules.
 
+Use the current installed Airlock procedure grammar when the app talks to
+Airlock:
+
+- `airlock.observe.*` is read-only and is the first-class governance
+  observation surface for `app_admin` and `app_observer`.
+- `airlock.admin.*` performs administrative changes and operational mutations.
+- `airlock.agent.*` performs governed user or agent work in the actor's scope.
+
+For app-first work, prefer `observe.procedures`, `observe.specs`,
+`observe.spec`, `observe.governance_map`, `observe.explain_access`,
+`observe.health`, `observe.activity`, `observe.admin_activity`,
+`observe.spec_admin_activity`, `observe.billing`, `observe.billing_events`, and
+the relevant context packets before inventing
+custom read paths. Do not tell agents to call retired admin read wrappers such
+as `admin.list_specs`, `admin.describe_role`, `admin.get_spec`, or
+`admin.list_events`; use the matching observe list/detail procedure instead.
+Use `admin.*` only when the app is intentionally changing Airlock setup or
+running an admin operation.
+
+Restricted references are one-record interaction contracts for read-only
+reference specs. If `agent.describe_spec`, `observe.spec`,
+`observe.spec_config`, or `observe.reference_context` shows
+`restricted_reference` or `reference_config.restricted_reference`, do not
+enumerate the protected reference, build a populated picker, or use broad
+`agent.select_reference_data` for that object path. Get the lookup value from
+the user's case/work context, then call `agent.get_reference_record` with the
+configured `object_key`, lookup value, purpose, and role lens. The procedure
+returns at most one `RECORD`, applies reference row filters, checks active
+`action_limit` Expectations before returning data, and records the safe
+`REFERENCE_READ` event used for usage budgeting. Branch on stable codes such
+as `OK`, `NOT_FOUND`, `NON_UNIQUE_LOOKUP_KEY`, `PURPOSE_REQUIRED`,
+`USAGE_LIMIT_BLOCKED`, and `REFERENCE_READ_EVENT_FAILED`; expose
+`USAGE_CONTEXT` fields such as `action_limit_used` and `action_time_period`.
+For read-only planning and audit, use `observe.reference_context`,
+`observe.usage_limits`, `observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+without querying raw reference rows.
+
 Help the app follow the loop:
 
 - Observe/read: fetch existing governed data through approved Airlock or
@@ -254,6 +301,8 @@ In co-development mode, keep two tracks visible:
 Read only the relevant pattern files:
 
 - `patterns/starter-posts/` when the user needs a first feedback loop.
+- `patterns/okf-knowledge-bundle/` when the user needs governed Markdown
+  business context for people or agents.
 - `patterns/guest-access/` when isolation or sharing is the hard part.
 - `patterns/spec-types/` when choosing observation, commitment,
   reconciliation, or reference/master-data shape.

package/README.md

@@ -14,7 +14,7 @@ It covers the full Airlock loop:
 Spec building and spec-using app guidance are not second things users install.
 They are bundled inside Airlock MCP.
 
-Airlock MCP gives agents three kinds of Airlock help:
+Airlock MCP gives agents four kinds of Airlock help:
 
 1. Spec design: draft, check, revise, import, clone, and prepare specs for
    installed Airlock validation.
@@ -24,6 +24,31 @@ Airlock MCP gives agents three kinds of Airlock help:
 3. App and workflow implementation: build dashboards, queues, decision UIs,
    analyses, and agent workflows that use existing specs through Airlock
    contracts.
+4. Governance observation: use installed Airlock's read-only `observe.*`
+   procedures to inspect setup, access, activity, billing events, health,
+   context packets, and governance maps before deciding what an app or agent
+   should do.
+
+## Installed Airlock Contract
+
+Current Airlock separates procedure intent:
+
+- `airlock.observe.*` is the read-only governance observation surface. It is
+  available to `app_admin` and `app_observer` and is the preferred path for
+  discovery, health checks, access explanation, governance maps, activity,
+  billing event context, and list/detail context packets.
+- `airlock.admin.*` is for admin changes and operational actions such as
+  creating specs, changing roles, loading OKF bundles, rerunning setup, or
+  deleting purge candidates.
+- `airlock.agent.*` is for governed agent work such as listing my
+  specs, validating/loading data, workflow actions, attachments, delegations,
+  and references.
+
+When building an app or workflow, prefer `observe.*` for read-only setup and
+monitoring questions, `agent.*` for governed submissions in the actor's scope,
+and `admin.*` only for intentional administrative mutation. Do not use retired
+admin read wrappers such as `admin.list_specs`, `admin.describe_role`, or
+`admin.list_events`; use the matching observe procedures instead.
 
 ## Install
 
@@ -98,7 +123,8 @@ The server exposes orientation plus local spec-building tools:
 - `airlock_init_app_context`: seed an app repo with spec snapshots, sample
   records, generated helper folders, and an app manifest.
 - `airlock_list_patterns` and `airlock_show_pattern`: inspect starter patterns.
-- `airlock_init_workspace`: create a workspace from `blank` or `posts`.
+- `airlock_init_workspace`: create a workspace from `blank`, `posts`, or
+  `okf-knowledge-bundle`.
 - `airlock_list_workspaces`: inspect active or archived drafts.
 - `airlock_check_workspace`, `airlock_summary`, and `airlock_next`: validate and re-enter a draft.
 - `airlock_export_csv`: render `sample.records.json` as Airlock-ready CSV.
@@ -188,3 +214,36 @@ points, patterns, and ideas. Those library specs are not guaranteed to reflect
 the current shape of any third-party system. Current API docs, real exports,
 samples, schemas, and user-provided artifacts should override library shapes
 when they conflict.
+
+For app-first work against installed Airlock, start with `observe.procedures`,
+`observe.specs`, `observe.spec`, `observe.governance_map`,
+`observe.explain_access`, `observe.health`, and the relevant context packet
+before designing direct SQL helpers. These payloads are intended to be useful
+to agents as well as humans.
+
+Restricted references are one-record interaction contracts. When
+`observe.reference_context`, `observe.spec_config`, or `agent.describe_spec`
+shows `restricted_reference` or `reference_config.restricted_reference`, agents
+must not call broad
+`agent.select_reference_data` for that object path and must not enumerate values
+or build a populated picker from the protected reference. The agent should get
+the lookup value from the user's case/work context, then call
+`agent.get_reference_record` with the configured `object_key`, lookup value,
+purpose, and role lens. The procedure applies configured reference row filters,
+checks active `action_limit` Expectations before returning a record, always
+records the safe `REFERENCE_READ` event used for budgeting, and returns at most
+one `RECORD`. Branch on codes such as `OK`, `NOT_FOUND`,
+`NON_UNIQUE_LOOKUP_KEY`, `PURPOSE_REQUIRED`, `USAGE_LIMIT_BLOCKED`, and
+`REFERENCE_READ_EVENT_FAILED`, and report `USAGE_CONTEXT` fields such as
+`action_limit_used` and `action_time_period`. Auditors and planning agents can
+inspect `observe.usage_limits`, `observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+without reading raw reference rows.
+
+For governed Markdown knowledge, use the `okf-knowledge-bundle` pattern. It
+sets `core_config.payload_adapter` to `okf_knowledge_bundle` so installed
+Airlock can load locally validated bundles through
+`airlock.admin.load_okf_bundle(...)`, sync parsed metadata through
+`airlock.admin.sync_okf_bundle_metadata(...)`, and expose accepted concept
+metadata from `AIRLOCK_DATA.ACTIVE.V_OKF_CONCEPT_METADATA`. Draft and rejected
+bundles are not authoritative agent context.

package/docs/install-surface.md

@@ -24,6 +24,20 @@ that reads and submits through Airlock contracts.
 The install command is not the spec workspace. It is the connector/setup entry
 point. The specs repo is still the durable memory.
 
+For installed Airlock access, teach the current procedure split:
+`airlock.observe.*` is the read-only governance observation surface,
+`airlock.agent.*` is governed agent work, and `airlock.admin.*` is
+administrative mutation. App-first and audit-style workflows should use
+observe payloads for discovery, context, health, access explanation, activity,
+billing events, and governance maps before considering custom SQL helpers.
+When a read-only reference spec declares `restricted_reference` or
+`reference_config.restricted_reference`, agents should avoid broad
+`agent.select_reference_data` reads and use `agent.get_reference_record` for a
+known lookup value and purpose, with `observe.reference_context`,
+`observe.usage_limits`, `observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+for planning and audit.
+
 The connector package and MCP server live in `reunionstudio/airlock-mcp`.
 This workbench provides the spec-building implementation inside that one
 installed Airlock MCP experience.
@@ -118,9 +132,11 @@ The first release should optimize the user journey:
    forms, screenshots, PDFs, exports, or message examples
 6. use `airlock-specs` library patterns as starting points when useful, while
    preferring current artifacts over library shapes when they conflict
-7. map where information comes in and actions go out
-8. create the first workspace only after the user chooses a small first spec
-9. keep a plan for later specs that improve the full loop
+7. use the `okf-knowledge-bundle` pattern when the useful artifact is governed
+   Markdown knowledge for accepted agent context
+8. map where information comes in and actions go out
+9. create the first workspace only after the user chooses a small first spec
+10. keep a plan for later specs that improve the full loop
 
 For users who already have specs and want to build software, optimize a second
 journey:
@@ -131,10 +147,11 @@ journey:
 4. identify read specs and write specs
 5. seed app-local Airlock context with `airlock-mcp init-app-context` when the
    app needs spec snapshots, samples, generated helpers, and a manifest
-6. build orienting views, dashboards, queues, proposals, or recommendations
-7. capture decisions, approvals, actions, comments, or follow-ups through
+6. inspect installed setup with read-only `observe.*` procedures when available
+7. build orienting views, dashboards, queues, proposals, or recommendations
+8. capture decisions, approvals, actions, comments, or follow-ups through
    Airlock spec contracts
-8. avoid direct writes to Airlock-owned tables and avoid bypassing spec workflow
+9. avoid direct writes to Airlock-owned tables and avoid bypassing spec workflow
 
 For users who are developing the app and specs together, optimize a third
 journey:

package/docs/spec-workspace.md

@@ -22,6 +22,11 @@ Use `airlock-mcp rename`, `archive`, and `restore` to organize draft folders.
 `rename` retitles spec identity by default; pass `--keep-spec-identity` for a
 pure folder move.
 
+For `okf-knowledge-bundle` workspaces, `sample.records.json` is only a small
+metadata sample for the draft spec. The governed payload is a locally validated
+Markdown directory or `.zip` bundle loaded through installed Airlock's
+`airlock.admin.load_okf_bundle(...)` path.
+
 `review.md` should identify the workspace source mode:
 
 - `create`: started from an Airlock MCP pattern

package/docs/workflows.md

@@ -154,6 +154,39 @@ unless the user asks to change specs. Start by asking for:
 - the available Airlock/Snowflake access path
 - identity, evidence, timestamp, approval, and separation-of-duties needs
 
+Use the installed Airlock procedure grammar:
+
+- `airlock.observe.*` is read-only and should answer discovery, governance,
+  audit, health, activity, billing-event, and access-explanation questions.
+- `airlock.agent.*` is for governed work by the current actor, including
+  validation, loading, workflow actions, attachments, references, and
+  delegations.
+- `airlock.admin.*` is for administrative mutation and operational changes.
+
+For app-first work, start with 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`, `observe.billing`, and
+`observe.billing_events`. For `alter_spec` activity, use `CHANGED_SECTIONS` and
+`CHANGED_FIELDS` to triage what changed before fetching version snapshots. Do not use retired admin read
+wrappers such as `admin.list_specs`, `admin.describe_role`, `admin.get_spec`,
+or `admin.list_events`; use observe list/detail procedures instead.
+
+Restricted references are one-record interaction contracts for read-only
+reference specs. When `observe.reference_context`, `observe.spec_config`, or
+`agent.describe_spec` shows `restricted_reference` or
+`reference_config.restricted_reference`, do not enumerate the protected
+reference, build a populated picker, or use broad `agent.select_reference_data`
+for that object path. Get the lookup value from the user's case/work context,
+then call `agent.get_reference_record` with the configured `object_key`, lookup
+value, purpose, and role lens. The procedure returns at most one `RECORD`,
+applies reference row filters, checks active `action_limit` Expectations before
+returning data, and records the safe `REFERENCE_READ` event used for usage
+budgeting. Use `observe.reference_context`, `observe.usage_limits`,
+`observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+for planning and audit without reading raw reference rows.
+
 The app should follow the loop:
 
 1. Observe/read governed records through approved Airlock or Snowflake surfaces.
@@ -228,6 +261,28 @@ airlock-mcp check workspaces/feedback-loop
 Then ask Codex to help decide what the posts should observe, who responds, and
 what next spec should grow from the feedback.
 
+## Start From Governed Knowledge
+
+Use this when the user wants accepted Markdown business context for people or
+agents: policies, runbooks, metric definitions, investigations, decisions, or
+operating notes.
+
+```bash
+airlock-mcp init sales-context --pattern okf-knowledge-bundle
+airlock-mcp check workspaces/sales-context
+```
+
+This pattern sets `core_config.payload_adapter` to `okf_knowledge_bundle`.
+Installed Airlock loads locally validated bundles with
+`airlock.admin.load_okf_bundle(...)`, can refresh parsed metadata with
+`airlock.admin.sync_okf_bundle_metadata(...)`, and exposes authoritative
+accepted concept metadata through
+`AIRLOCK_DATA.ACTIVE.V_OKF_CONCEPT_METADATA`.
+
+Do not treat draft or rejected Markdown bundles as authoritative agent context.
+The MCP local checker validates the spec workspace; bundle validation belongs
+to Airlock's OKF validator and installed procedures.
+
 ## Start From A Known Process
 
 Use this when the process is known but the data shape is not.

package/package.json

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

package/patterns/manifest.json

@@ -11,6 +11,12 @@
       "title": "Posts feedback loop",
       "summary": "Small governed feedback stream for discovering what to build next.",
       "directory": "starter-posts"
+    },
+    {
+      "name": "okf-knowledge-bundle",
+      "title": "OKF knowledge bundle",
+      "summary": "Governed Markdown knowledge bundles for accepted agent context.",
+      "directory": "okf-knowledge-bundle"
     }
   ]
 }

package/patterns/okf-knowledge-bundle/README.md

@@ -0,0 +1,64 @@
+# Starter Pattern: OKF Knowledge Bundle
+
+Use `okf-knowledge-bundle` when the team wants governed Markdown knowledge for
+people and agents to use as accepted business context.
+
+This pattern is for Airlock's `okf_knowledge_bundle` payload adapter. It is
+inspired by Google's Open Knowledge Format, but Airlock applies a narrower
+profile so accepted bundles can become governed context instead of loose wiki
+content.
+
+## Use When
+
+- Policies, runbooks, metrics, definitions, decisions, investigations, or
+  operating context need a governed place to land.
+- Agents need business context that can be accepted, audited, and queried from
+  Snowflake.
+- The team has useful Markdown knowledge, but needs Airlock workflow, PDP,
+  Expectations, evidence, and acceptance boundaries around it.
+
+## Bundle Shape
+
+- Bundle source is a directory or `.zip` archive of UTF-8 Markdown files.
+- Root `index.md` may contain bundle frontmatter such as `okf_version`,
+  `bundle_name`, `bundle_version`, `domain`, `owner`, and `purpose`.
+- Every non-reserved Markdown file is a concept document with YAML frontmatter.
+- Concept documents require `type`.
+- Recommended concept fields are `title`, `description`, `resource`, `tags`,
+  `timestamp`, and `source_links`.
+- `index.md` and `log.md` are reserved at every hierarchy level.
+
+## Airlock Contract
+
+The spec must declare:
+
+```json
+{
+  "core_config": {
+    "payload_adapter": "okf_knowledge_bundle"
+  }
+}
+```
+
+Installed Airlock provides two admin procedures for this adapter:
+
+- `airlock.admin.load_okf_bundle(...)`: load a locally validated bundle into
+  Airlock stage storage and `FILE_MANIFEST`, then project concept metadata.
+- `airlock.admin.sync_okf_bundle_metadata(...)`: project parsed concept
+  metadata for an existing active manifest row.
+
+Use `validate_only => TRUE` before writing. Treat accepted context as
+authoritative only from:
+
+```sql
+AIRLOCK_DATA.ACTIVE.V_OKF_CONCEPT_METADATA
+```
+
+Draft and rejected bundles are not authoritative agent context.
+
+## Local Workbench Notes
+
+`airlock-mcp check` validates the Airlock spec draft and sample metadata. It
+does not validate a Markdown bundle. Bundle validation currently lives in the
+Airlock source repo's `airlock.okf_knowledge_bundle.validate_okf_bundle`
+helper and the installed Airlock OKF procedures.

package/patterns/okf-knowledge-bundle/sample.records.json

@@ -0,0 +1,16 @@
+{
+  "spec_name": "okf_knowledge",
+  "filename": "okf_knowledge_sample.csv",
+  "records": [
+    {
+      "concept_path": "runbooks/monthly-close",
+      "concept_type": "Runbook",
+      "bundle_version": "2026.06"
+    },
+    {
+      "concept_path": "metrics/net-revenue",
+      "concept_type": "Metric",
+      "bundle_version": "2026.06"
+    }
+  ]
+}

package/patterns/okf-knowledge-bundle/spec.config.json

@@ -0,0 +1,64 @@
+{
+  "core_config": {
+    "spec_name": "okf_knowledge",
+    "spec_alias": "OKF Knowledge",
+    "description": "Governed OKF-style Markdown knowledge bundles for accepted agent context.",
+    "owner_role": "app_admin",
+    "current_mode": "append",
+    "is_published": false,
+    "is_locked": false,
+    "is_archived": false,
+    "is_multi_role": false,
+    "file_workflow": false,
+    "workflow_steps": [],
+    "materialize_as_table": false,
+    "payload_adapter": "okf_knowledge_bundle"
+  },
+  "column_config": [
+    {
+      "name": "concept_path",
+      "type": "string",
+      "description": "Stable normalized Markdown concept path without the .md suffix.",
+      "tests": ["not_null", "unique"]
+    },
+    {
+      "name": "concept_type",
+      "type": "string",
+      "description": "Concept type from OKF frontmatter.",
+      "tests": ["not_null"]
+    },
+    {
+      "name": "bundle_version",
+      "type": "string",
+      "description": "Bundle version containing the concept.",
+      "tests": ["not_null"]
+    }
+  ],
+  "rules": [],
+  "file_rules": {
+    "file_format": {
+      "file_type": "csv",
+      "record_delimiter": "\n",
+      "field_delimiter": ",",
+      "field_optionally_enclosed_by": "\"",
+      "escape_unenclosed_field": "\\",
+      "encoding": "UTF8",
+      "parse_header": true,
+      "save_header": true
+    },
+    "filename_rules": {
+      "enforce_filename_pattern": false,
+      "filename_pattern": null,
+      "sample_filenames": null
+    }
+  },
+  "sample_data": {
+    "sample_data_acknowledged": true,
+    "sample_rows": [],
+    "edited_sample_data": "concept_path,concept_type,bundle_version\nrunbooks/monthly-close,Runbook,2026.06\nmetrics/net-revenue,Metric,2026.06\n"
+  },
+  "attachment_policy": {
+    "attachments_enabled": true,
+    "attachment_required": false
+  }
+}

package/patterns/starter-posts/sample.records.json

@@ -5,7 +5,7 @@
     {
       "post_id": "POST-001",
       "reply_to_post_id": "",
-      "submitted_by": "agent.deb",
+      "submitted_by": "agent.csmith",
       "posted_at": "2026-06-13 09:00:00",
       "body": "Please make reimbursements easier to prepare and submit.",
       "tags": "#request #finance #reimbursements",
@@ -19,7 +19,7 @@
           "desired_outcome": "An approved agent can prepare a draft reimbursement with receipt evidence."
         },
         "agent": {
-          "name": "Deb"
+          "name": "csmith"
         }
       }
     }

package/setup.py

@@ -27,7 +27,7 @@ def data_files():
 
 setup(
     name="airlock-mcp",
-    version="0.1.3",
+    version="0.1.5",
     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.3"
+__version__ = "0.1.5"

package/src/airlock_mcp/app_context.py

@@ -28,6 +28,32 @@ Use:
 - `generated/types/` for generated application types.
 - `generated/sql/` for reviewed SQL helpers or query templates.
 
+Installed Airlock separates procedure intent:
+
+- `observe.*`: read-only governance observation for discovery, health, access
+  explanation, activity, admin activity, billing events, governance maps, and
+  context packets.
+- `agent.*`: governed agent work in the actor's scope.
+- `admin.*`: administrative mutation and operational changes.
+
+Prefer `observe.*` for app read-side setup and monitoring questions. Use
+`observe.admin_activity` for broad admin mutation and maintenance audit
+questions, and `observe.spec_admin_activity` for one spec's definition-change
+timeline. For `alter_spec` activity, use `CHANGED_SECTIONS` and
+`CHANGED_FIELDS` to triage what changed before fetching version snapshots.
+Do not use retired admin read wrappers such as `admin.list_specs`,
+`admin.describe_role`, or `admin.list_events`; use the matching observe procedure.
+
+Restricted references are one-record interaction contracts. If a reference
+spec declares `restricted_reference` or `reference_config.restricted_reference`,
+do not enumerate values or use broad `agent.select_reference_data` for that
+object path. Get the lookup value from the user's case/work context and call
+`agent.get_reference_record` with the configured `object_key`, lookup value,
+purpose, and role lens. Use `observe.reference_context`,
+`observe.usage_limits`, `observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+for planning and audit without reading raw reference rows.
+
 Do not store credentials here. Do not write directly to Airlock-owned tables,
 stages, generated views, or generated tables. Use approved Airlock/Snowflake
 access paths and submit governed decisions or actions through spec contracts.
@@ -60,6 +86,22 @@ Use approved Airlock/Snowflake access paths. Do not bypass spec workflow or
 write directly to Airlock-owned tables, stages, generated views, or generated
 tables. If the app needs to submit a decision or action and no suitable write
 spec exists, propose a small spec-design step.
+
+Installed Airlock procedure grammar:
+
+- `observe.*` is read-only governance observation. Use it for discovery,
+  health, access explanation, governance maps, activity, billing events, and
+  context packets.
+- `agent.*` is governed agent work in the actor's scope.
+- `admin.*` is administrative mutation. Do not use retired admin read wrappers;
+  use observe list/detail procedures instead.
+
+For restricted reference specs, do not enumerate protected object paths or use
+broad `agent.select_reference_data`. Use `agent.get_reference_record` for a
+known lookup value and purpose, and use `observe.reference_context`,
+`observe.usage_limits`, `observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+for planning and audit.
 """
 
 
@@ -115,6 +157,12 @@ def _manifest(mode: str, entries: list[dict[str, Any]]) -> dict[str, Any]:
         "mode": mode,
         "canonical_source": "specs repo or installed Airlock",
         "snapshot_policy": "Snapshots are app-local development references, not canonical specs.",
+        "installed_airlock_contract": {
+            "observe": "read-only governance observation, context, activity, health, billing events, and access explanation",
+            "agent": "governed agent work in the actor scope",
+            "admin": "administrative mutation and operational changes",
+            "restricted_reference": "one-record reference lookup through agent.get_reference_record; do not enumerate protected reference paths",
+        },
         "specs": entries,
         "tracks": {
             "spec_track": "row grain, columns, samples, access, validation, workflow",
@@ -134,6 +182,7 @@ def _merge_manifest(existing: Any, new_manifest: dict[str, Any]) -> dict[str, An
             "mode": new_manifest["mode"],
             "canonical_source": new_manifest["canonical_source"],
             "snapshot_policy": new_manifest["snapshot_policy"],
+            "installed_airlock_contract": new_manifest["installed_airlock_contract"],
             "tracks": new_manifest["tracks"],
         }
     )
@@ -265,7 +314,8 @@ def format_app_context_result(result: AppContextResult) -> str:
             "next:",
             "1. Treat spec snapshots as app-local references, not canonical specs.",
             "2. Mark each manifest spec as read, write, or read_write for the app.",
-            "3. Build app reads and governed submissions through approved Airlock/Snowflake access paths.",
+            "3. Use observe.* for read-only governance discovery and agent.* for governed actor work.",
+            "4. Build governed submissions through approved Airlock/Snowflake access paths.",
         ]
     )
     return "\n".join(lines)

package/src/airlock_mcp/bootstrap.py

@@ -111,6 +111,34 @@ Identify:
 - the Airlock access path available in this environment
 - identity, evidence, timestamp, approval, and separation-of-duties rules
 
+Installed Airlock separates procedure intent:
+
+- `observe.*`: read-only governance observation for discovery, health, access
+  explanation, governance maps, activity, billing events, and context packets.
+- `agent.*`: governed agent work in the actor's scope.
+- `admin.*`: administrative mutation and operational changes.
+
+For app-first work, use 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. Do not call retired admin read wrappers such as `admin.list_specs`, `admin.describe_role`,
+or `admin.list_events`; use the matching observe list/detail procedure.
+
+Restricted references are one-record interaction contracts for read-only
+reference specs. If `agent.describe_spec`, `observe.spec_config`, or
+`observe.reference_context` shows `restricted_reference` or
+`reference_config.restricted_reference`, do not enumerate the protected
+reference, build a populated picker, or use broad `agent.select_reference_data`
+for that object path. Get the lookup value from the user's case/work context,
+then call `agent.get_reference_record` with the configured `object_key`, lookup
+value, purpose, and role lens. Use `observe.usage_limits`,
+`observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+for planning and audit without reading raw reference rows.
+
 The app may orient the user with summaries, comparisons, rankings, exception
 queues, proposals, or dashboards. It should submit governed choices back
 through an Airlock spec contract. Do not write directly to Airlock-owned tables,

package/src/airlock_mcp/summary.py

@@ -247,6 +247,7 @@ def workspace_summary(
         f"  owner_role: {_format_value(core.get('owner_role'))}",
         f"  published: {_format_value(core.get('is_published'))}",
         f"  archived: {_format_value(core.get('is_archived'))}",
+        f"  payload_adapter: {_format_value(core.get('payload_adapter'), default='default')}",
         f"  description: {_truncate(core.get('description')) or 'none'}",
         "",
         "file_rules:",

package/src/mcp.mjs

@@ -44,7 +44,7 @@ export function handleMcpRequest(message) {
       },
       serverInfo: {
         name: "airlock",
-        version: "0.1.3",
+        version: "0.1.5",
       },
       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.",

package/src/text.mjs

@@ -53,10 +53,36 @@ and a plan for more. Do not create the first workspace until I choose a path.
 
 If I want app-first or co-development, ask for the app goal, the specs I can
 access, which specs are read sources, which spec records decisions or actions,
-and where the app should run. Offer to run \`airlock-mcp init-app-context\` in
-the app repo to seed \`airlock/specs.manifest.json\`, spec snapshots, sample
-records, and generated helper folders. Help code the app using approved
-Airlock/Snowflake access paths. Do not write directly to Airlock-owned tables
+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
+\`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. Offer to run \`airlock-mcp init-app-context\`
+in the app repo to seed \`airlock/specs.manifest.json\`, spec snapshots, sample records, and
+generated helper folders. Help code the app using approved Airlock/Snowflake access paths.
+When a reference spec declares \`restricted_reference\` or
+\`reference_config.restricted_reference\`, do not enumerate values, build a
+populated picker, or call broad \`agent.select_reference_data\`. Get the lookup
+value from the user's case/work context and call
+\`agent.get_reference_record\` for the configured \`object_key\`, purpose, and
+role lens. It returns at most one record, applies reference row filters, checks
+\`action_limit\` before returning data, and always records the safe
+\`REFERENCE_READ\` event used for budgeting. Branch on \`OK\`, \`NOT_FOUND\`,
+\`NON_UNIQUE_LOOKUP_KEY\`, \`PURPOSE_REQUIRED\`, \`USAGE_LIMIT_BLOCKED\`, and
+\`REFERENCE_READ_EVENT_FAILED\`; report \`USAGE_CONTEXT\` fields such as
+\`action_limit_used\` and \`action_time_period\`. Use
+\`observe.reference_context\`, \`observe.usage_limits\`, \`observe.usage_limit\`,
+and \`observe.explain_access(action => 'get_reference_record', object_key => ...)\`
+for read-only planning and audit.
+
+Do not use retired admin read wrappers such as
+\`admin.list_specs\`, \`admin.describe_role\`, or \`admin.list_events\`; use
+the matching observe procedure. Do not write directly to Airlock-owned tables
 or bypass spec workflow.`;
 }
 
@@ -78,11 +104,13 @@ Airlock MCP will offer:
   - spec-first, app-first, and co-development planning
   - 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
   - app context seeding with spec snapshots and manifests
   - app and workflow coding against existing Airlock specs
   - observe specs for controlled interface ingestion
   - orient specs for proposals, context, scoring, or exception queues
   - decision specs and action specs for governed follow-through
+  - OKF-style Markdown knowledge bundles for accepted agent context
   - artifact-grounded drafts from CSV, Excel, JSON, API docs, schemas, forms, screenshots, PDFs, or exports
   - airlock-specs library patterns as starting points, checked against current artifacts`;
 }
@@ -95,7 +123,7 @@ Airlock. It helps a person and their agent improve processes by designing
 specs, using specs for governed data movement, planning OODA loops, and building
 apps or workflows that read from and submit through existing specs.
 
-Airlock MCP gives agents three kinds of Airlock help:
+Airlock MCP gives agents four kinds of Airlock help:
 
 1. Spec design: draft, check, revise, import, clone, and prepare specs for
    installed Airlock validation.
@@ -105,6 +133,10 @@ Airlock MCP gives agents three kinds of Airlock help:
 3. App and workflow implementation: build dashboards, queues, decision UIs,
    analyses, and agent workflows that use existing specs without bypassing
    Airlock contracts.
+4. Governance observation: use installed Airlock's read-only \`observe.*\`
+   procedures to inspect setup, access, activity, billing events, health,
+   context packets, and governance maps before deciding what an app or agent
+   should do.
 
 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
@@ -146,15 +178,36 @@ points, patterns, and ideas. Library specs are not guaranteed to match the
 current shape of any third-party system. Prefer current API docs, real exports,
 samples, and other artifacts when they conflict with the library.
 
+For governed Markdown knowledge, use the \`okf-knowledge-bundle\` pattern. It
+creates a spec with \`core_config.payload_adapter\` set to
+\`okf_knowledge_bundle\`. Installed Airlock loads locally validated bundles with
+\`airlock.admin.load_okf_bundle(...)\`, can sync parsed metadata with
+\`airlock.admin.sync_okf_bundle_metadata(...)\`, and exposes authoritative
+accepted context through \`AIRLOCK_DATA.ACTIVE.V_OKF_CONCEPT_METADATA\`.
+
 Give Codex the messy version of the process. Airlock MCP should help turn it
 into a small first Airlock spec and a plan for more.
 
 For app-first and co-development work, give Codex the app goal and available
 specs. Airlock MCP should identify read specs, write specs, orienting views,
-decision capture, and safe Airlock/Snowflake access paths. It can seed an app
-repo with \`airlock/specs.manifest.json\`, spec snapshots, sample records, and
-generated helper folders. The app should submit decisions, approvals, actions,
-comments, or follow-ups through Airlock spec contracts, not direct table writes.
+decision capture, and safe Airlock/Snowflake access paths. Installed Airlock
+uses \`observe.*\` for read-only governance observation, \`agent.*\` for
+governed agent work, and \`admin.*\` for administrative mutation. Start
+read-side discovery with 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\`;
+for \`alter_spec\` activity, use \`CHANGED_SECTIONS\` and \`CHANGED_FIELDS\` to
+triage what changed before fetching version snapshots. Do not use retired admin
+read wrappers such as \`admin.list_specs\`, \`admin.describe_role\`, or
+\`admin.list_events\`. If a reference spec declares \`restricted_reference\` or
+\`reference_config.restricted_reference\`, do not enumerate the protected
+reference; use \`agent.get_reference_record\` for a known lookup value and
+\`observe.usage_limits\` / \`observe.usage_limit\` for budget visibility. It can
+seed an app repo with \`airlock/specs.manifest.json\`, spec snapshots, sample
+records, and generated helper folders. The app should submit decisions,
+approvals, actions, comments, or follow-ups through Airlock spec contracts, not
+direct table writes.
 In co-development mode, keep the spec track and app track visible side by side.`;
 }
 

package/src/workbench.mjs

@@ -82,7 +82,7 @@ export const WORKBENCH_TOOLS = [
       {
         pattern: {
           type: "string",
-          enum: ["blank", "posts"],
+          enum: ["blank", "okf-knowledge-bundle", "posts"],
           description: "Pattern to inspect.",
         },
         files: {
@@ -106,7 +106,7 @@ export const WORKBENCH_TOOLS = [
         },
         pattern: {
           type: "string",
-          enum: ["blank", "posts"],
+          enum: ["blank", "okf-knowledge-bundle", "posts"],
           description: "Starting pattern. Defaults to blank.",
         },
         output: {