@reunionstudio/airlock-mcp 0.1.2 → 0.1.4

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

@@ -1,13 +1,16 @@
 ---
 name: airlock-mcp
-description: Design, draft, review, and iterate Airlock specs in the Airlock MCP spec-building workbench. Use when Codex is helping a person choose a small starting spec, work through row grain and OODA-loop decisions, import reusable patterns such as posts or guest access setups, validate local draft files, or prepare an Airlock spec config before installed Airlock validation.
+description: Design, draft, review, and iterate Airlock specs in the Airlock MCP spec-building workbench, or help build apps and workflows that use existing Airlock specs safely. Use when Codex is helping a person choose a small starting spec, work through row grain and OODA-loop decisions, import reusable patterns such as posts or guest access setups, validate local draft files, prepare an Airlock spec config before installed Airlock validation, or code an app that reads from and submits through existing specs.
 ---
 
-# Airlock MCP Spec Builder
+# Airlock MCP
 
 Use this skill to help a human develop Airlock specs over multiple sessions.
-The repo is the workbench; Codex is the conversational interface; the CLI is
-the deterministic checker.
+Also use it when a human wants to build an app or workflow that uses existing
+Airlock specs. The specs repo is the durable workbench for spec drafts; an app
+repo is the right place for code that reads, orients, decides, and submits
+through existing specs. Codex is the conversational interface; the CLI is the
+deterministic checker for local spec drafts.
 
 ## Default Path
 
@@ -16,6 +19,13 @@ the deterministic checker.
    `sample.records.json`, and `review.md`.
 2. If the current repo is not yet an Airlock MCP specs repo, run or suggest:
    `airlock-mcp init-repo`.
+   Exception: if the user asks to build an app, dashboard, approval queue,
+   decision UI, agent workflow, or other code that uses existing specs, do not
+   bootstrap a specs repo just because the current repo lacks `workspaces/`.
+   Treat the current repo as an app repo unless the user asks to create specs.
+   Ask for the development mode, available specs, app goal, and read/write
+   contract instead. Use `airlock-mcp init-app-context` when the app repo needs
+   an `airlock/` folder with spec snapshots and an app manifest.
    When helping create that repo from scratch, ask for the project or
    organization name and suggest `<slug>-specs`; for example, `Home` becomes
    `home-specs`. Reserve `airlock-specs` for the canonical reusable spec
@@ -35,7 +45,9 @@ the deterministic checker.
    any workspace.
    If the user opened the public `airlock-mcp` workbench repo as the entry
    point, help them create a separate `<slug>-specs` project repo beside it.
-3. If no workspace exists, welcome the user and ask:
+3. If no workspace exists, welcome the user and ask which mode they want:
+   spec-first, app-first from existing specs, or co-development.
+   For spec-first or co-development, ask:
    `What process do you want to improve?`
    Explain that Airlock works best when we can identify the loop around that
    process:
@@ -62,19 +74,28 @@ the deterministic checker.
 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.
@@ -82,14 +103,14 @@ the deterministic checker.
    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
@@ -159,11 +180,110 @@ Use the observe-orient-decide-act loop as the product frame:
 - Act: controlled writes back to interfaces, commitments, follow-ups, outputs,
   and the next observations created by those actions.
 
+## Apps And Workflows Using Existing Specs
+
+Use this path when the user wants to vibe-code an app, dashboard, queue,
+decision UI, analysis workflow, or agent workflow that uses specs they already
+have access to. This is not spec editing by default.
+
+Use three delivery modes:
+
+- Spec-first: design governed specs, samples, access, and validation before
+  building the app surface.
+- App-first: use existing specs to build an app, dashboard, queue, or workflow.
+- Co-development: develop the app and specs together, keeping the contract and
+  experience visible side by side.
+
+Start by identifying:
+
+1. The app goal: what the user needs to orient around or decide.
+2. Read specs: existing specs the app reads from, such as budgets, expenses,
+   requests, forecasts, observations, payouts, or reference data.
+3. Write specs: existing specs the app submits to, such as decisions,
+   approvals, comments, commitments, actions, or follow-ups.
+4. The app surface: Streamlit, web app, CLI, notebook, scheduled agent, or
+   other runtime.
+5. The Airlock access path: installed Airlock procedures, approved MCP tools,
+   generated read surfaces, stages, or documented SQL helpers available in the
+   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.
+
+Help the app follow the loop:
+
+- Observe/read: fetch existing governed data through approved Airlock or
+  Snowflake surfaces.
+- Orient: summarize, compare, rank, flag exceptions, propose options, or build
+  dashboards and queues.
+- Decide: capture human or agent choices with rationale and evidence.
+- Act/write: submit the decision, approval, action, or follow-up through an
+  Airlock spec contract.
+
+Keep the boundary clear:
+
+- Do not edit specs unless the user asks for spec changes.
+- Do not write directly to Airlock-owned tables, stages, generated views, or
+  generated tables.
+- Do not treat Snowflake as an unrestricted database just because the app can
+  connect to it.
+- Prefer existing Airlock contracts for reads and writes. If no suitable write
+  spec exists, explain the gap and propose a small decision/action spec as a
+  separate spec-design step.
+- Keep secrets and credentials out of repo files. Use the app's existing secret
+  management pattern.
+
+### App Context Seeding
+
+Use `airlock-mcp init-app-context` in an app repo when the app needs local
+Airlock context. The command creates:
+
+```text
+airlock/
+  AGENTS.md
+  README.md
+  specs.manifest.json
+  spec-snapshots/
+  sample-records/
+  generated/
+    types/
+    sql/
+```
+
+The manifest and snapshots help the app develop against stable local references.
+They are not canonical. Canonical specs live in the specs repo or installed
+Airlock. When seeding from draft workspaces, pass `--spec <workspace>` for each
+spec to copy `spec.config.json` and `sample.records.json` into the app context.
+
+In co-development mode, keep two tracks visible:
+
+- Spec track: row grain, columns, samples, access, validation, workflow.
+- App track: screens, reads, decisions, writes, user actions, runtime.
+
 ## Pattern Guidance
 
 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/.agents/skills/airlock-mcp/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Airlock MCP"
-  short_description: "Improve a process with Airlock specs and OODA loop planning."
-  default_prompt: "Use $airlock-mcp to ask what process I want to improve, gather any existing artifacts, identify the loop around it, draft a small first Airlock spec, and keep a plan for more specs."
+  short_description: "Design specs or build apps that use Airlock specs."
+  default_prompt: "Use $airlock-mcp to ask whether I want to design specs, improve an OODA loop, or build an app/workflow that uses existing specs; then gather artifacts or available specs and help me move safely."

package/README.md

@@ -8,18 +8,47 @@ It covers the full Airlock loop:
 - design specs with the bundled spec-building workbench
 - map the process a person wants to improve into observe, orient, decide, and act
 - use specs for governed data movement, decisions, actions, and feedback loops
+- build apps and workflows that read from and submit through existing specs
 - validate, create, and revise specs against installed Airlock
 
-Spec building is not a second thing users install. It is bundled inside
-Airlock MCP.
+Spec building and spec-using app guidance are not second things users install.
+They are bundled inside Airlock MCP.
 
-Airlock MCP gives agents two kinds of Airlock expertise:
+Airlock MCP gives agents four kinds of Airlock help:
 
 1. Spec design: draft, check, revise, import, clone, and prepare specs for
    installed Airlock validation.
 2. Airlock operating patterns: use specs to organize observations, orientation,
    governed decisions, controlled actions, separation of duties, and feedback
    loops.
+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
 
@@ -50,7 +79,8 @@ codex mcp add airlock -- npx -y github:reunionstudio/airlock-mcp server
 
 The server exposes bootstrap guidance for starting a specs repo, coaching a
 person through process discovery, and entering the bundled spec-building
-workbench when a first spec is ready to draft.
+workbench when a first spec is ready to draft. It also guides agents building
+apps or workflows that use specs the user already has access to.
 
 Workspace summaries are structured spec cards. They present the current spec
 core, file rules, attachment policy, guest access, column rules, sample record
@@ -90,8 +120,11 @@ The server exposes orientation plus local spec-building tools:
 - `airlock_start`: return setup guidance for a project.
 - `airlock_doctor`: verify bundled workbench assets.
 - `airlock_init_repo`: bootstrap a Git-backed specs repo.
+- `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.
@@ -127,13 +160,48 @@ The intended user flow is:
 4. If Codex is creating the repo, choose where the `home-specs` directory should
    live before files are written.
 5. Ask Codex to use Airlock MCP to help improve a process with Airlock specs.
-6. Let Airlock MCP bootstrap the project, ask what process the user wants to
-   improve, and propose a small first spec plus a plan for more.
+6. Choose a delivery mode: spec-first, app-first from existing specs, or
+   co-development of specs and app together.
+7. Let Airlock MCP bootstrap the project, ask what process the user wants to
+   improve when specs are involved, and propose a small first spec plus a plan
+   for more.
+
+The first workspace should not be created automatically. Airlock MCP should
+first ask whether the user wants spec-first, app-first from existing specs, or
+co-development of specs and app together. For spec-building work, it should ask
+for the messy process, identify where information comes in and actions go out,
+then choose a small observation, orient, decision, or action spec.
+
+For app-building work, Airlock MCP should identify the app goal, read specs,
+write specs, orienting views, decision capture, and approved Airlock/Snowflake
+access paths. The app should submit decisions, approvals, actions, comments, or
+follow-ups through Airlock spec contracts. It should not write directly to
+Airlock-owned tables or bypass spec workflow.
+
+When an app repo needs local Airlock context, use:
 
-The first workspace should not be created automatically. The spec-building
-workbench should first ask for the messy process, identify where information
-comes in and actions go out, then choose a small observation, orient, decision,
-or action spec.
+```bash
+airlock-mcp init-app-context . --mode app-first --spec ../home-specs/workspaces/expenses
+```
+
+That creates:
+
+```text
+airlock/
+  AGENTS.md
+  README.md
+  specs.manifest.json
+  spec-snapshots/
+  sample-records/
+  generated/
+    types/
+    sql/
+```
+
+The snapshots are for coding, tests, and UI planning. They are not canonical.
+Canonical specs live in the specs repo or installed Airlock. In
+co-development, keep a visible spec track and app track so changes to row
+grain, access, workflow, screens, reads, and governed writes stay aligned.
 
 When the user already has artifacts, Airlock MCP should ask for them early:
 CSV or Excel files, JSON samples, API docs, schemas, forms, screenshots, PDFs,
@@ -146,3 +214,17 @@ 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.
+
+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/architecture.md

@@ -30,8 +30,9 @@ The spec-building workbench lives in this repo under `src/airlock_mcp`,
 `patterns`, `workspaces`, `schemas`, and `.agents/skills/airlock-mcp`.
 Airlock operating patterns live in the same MCP experience: real use cases,
 controlled interface ingestion, OODA loops, governed decisions, separation of
-duties, controlled actions, output review, and improvement capture. This is not
-a second install or separate product surface.
+duties, controlled actions, output review, improvement capture, and app/workflow
+implementation against existing specs. This is not a second install or separate
+product surface.
 
 ## MCP Surface
 
@@ -41,14 +42,24 @@ The bootstrap server exposes:
 - resource: `airlock://getting-started`
 - orientation tool: `airlock_start`
 - workbench tools: `airlock_doctor`, `airlock_init_repo`,
-  `airlock_list_patterns`, `airlock_show_pattern`, `airlock_init_workspace`,
-  `airlock_list_workspaces`, `airlock_check_workspace`, `airlock_summary`,
-  `airlock_next`, `airlock_export_csv`, and `airlock_render_sql`
+  `airlock_init_app_context`, `airlock_list_patterns`,
+  `airlock_show_pattern`, `airlock_init_workspace`, `airlock_list_workspaces`,
+  `airlock_check_workspace`, `airlock_summary`, `airlock_next`,
+  `airlock_export_csv`, and `airlock_render_sql`
 
 These give the agent enough context to start a Git-backed `<project>-specs`
 repo in a user-chosen location, ask what process the user wants to improve,
 enter the spec-building workbench when a first spec is ready to draft, and
-avoid creating a first workspace until the user chooses a path.
+avoid creating a first workspace until the user chooses a path. They also give
+the agent enough product guidance to work in an app repo when the user wants to
+build software that reads from existing specs and submits governed decisions or
+actions through Airlock contracts.
+
+`airlock_init_app_context` is the bridge for app-first and co-development work.
+It creates an app-local `airlock/` folder with spec snapshots, sample records,
+generated helper placeholders, and `specs.manifest.json`. Those files support
+coding, tests, and UI planning, but they are not canonical. Canonical specs
+remain in the specs repo or installed Airlock.
 
 Workbench tools call the bundled Python package with argument arrays and a
 controlled `PYTHONPATH`. They do not expose update commands over MCP. Tool

package/docs/install-surface.md

@@ -16,12 +16,21 @@ Then the user opens Codex, creates or opens a Git-backed `<project>-specs`
 repo, and starts chatting with Airlock. GitHub is the recommended default when
 available. If Codex is creating the repo, it should ask where the directory
 should live before writing files. Airlock MCP should start by asking what
-process the user wants to improve, then help design specs and operating
-patterns around observe, orient, decide, and act.
+delivery mode the user wants: spec-first, app-first from existing specs, or
+co-development of specs and app together. Then it should help design specs and
+operating patterns around observe, orient, decide, and act, or help code an app
+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.
+
 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.
@@ -116,6 +125,37 @@ 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:
+
+1. install connector
+2. open the app repo in Codex
+3. ask for the app goal and available specs
+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. 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
+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:
+
+1. open the app repo or specs repo in Codex
+2. choose co-development explicitly
+3. keep a spec track for row grain, columns, access, samples, validation, and
+   workflow
+4. keep an app track for screens, reads, orienting summaries, decision capture,
+   governed writes, runtime, and tests
+5. seed the app repo with `airlock/` snapshots and a manifest when the app needs
+   local contract context
+6. treat app snapshots as development references while canonical specs remain
+   in the specs repo or installed Airlock

package/docs/spec-workbench-architecture.md

@@ -14,6 +14,8 @@ Airlock MCP is intentionally small:
 - `art.py`: small terminal identity and about text.
 - `bootstrap.py`: specs-repo bootstrap files, including `AGENTS.md` and the
   repo-scoped Codex skill.
+- `app_context.py`: app-repo Airlock context seeding for spec snapshots,
+  sample records, generated helper placeholders, and `specs.manifest.json`.
 - `manage.py`: workspace discovery, archive, restore, rename, and next-action
   helpers.
 - `project.py`: checkout discovery and environment override handling.
@@ -55,6 +57,8 @@ The old Airlock Streamlit editor used mode-specific hydration:
 Airlock MCP maps that to files:
 
 - `init-repo`: prepare a separate specs repo for Codex and Airlock MCP
+- `init-app-context`: prepare an app repo `airlock/` folder for app-first or
+  co-development work against existing specs
 - `init`: create from a pattern
 - `import-spec`: edit/import an existing canonical or spec-library config in a
   new workspace
@@ -68,6 +72,12 @@ Airlock MCP maps that to files:
 This repo does not try to be the installed Airlock editor. It gives Codex and
 humans a careful drafting surface before Airlock receives the final config.
 
+`init-app-context` does not make app-local snapshots canonical. It gives an app
+repo stable development references for coding, tests, UI planning, and generated
+helpers. Canonical specs remain in the specs repo or installed Airlock. Use
+`--force` to refresh snapshots from canonical workspace files after the spec
+changes.
+
 ## Update Boundary
 
 `self-update` supports two intentionally simple paths:
@@ -119,9 +129,10 @@ npx @reunionstudio/airlock-mcp install
 
 The connector implementation belongs in `reunionstudio/airlock-mcp`. Airlock
 MCP is the single installed interface for agents working with Airlock: building
-specs, using specs to pull and push governed data, and capturing improvements
-from real use cases. This workbench owns the spec-building implementation:
-patterns, bootstrap, workspace files, local checks, and the Codex skill.
+specs, using specs to pull and push governed data, building apps or workflows
+that use existing specs, and capturing improvements from real use cases. This
+workbench owns the spec-building implementation: patterns, bootstrap, workspace
+files, local checks, and the Codex skill.
 
 That command is the agent connector/setup entry point, not the user's spec
 workspace. After installing or registering the connector, the user still creates

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