@reunionstudio/airlock-mcp 0.1.0 → 0.1.2

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

@@ -20,6 +20,12 @@ the deterministic checker.
    organization name and suggest `<slug>-specs`; for example, `Home` becomes
    `home-specs`. Reserve `airlock-specs` for the canonical reusable spec
    library.
+   Recommend storing the specs project in a real version-controlled repo,
+   preferably a GitHub repo when the user already uses GitHub. Before creating
+   the directory, ask where the user wants the `<slug>-specs` repo to live. If
+   Codex can create the repo, offer to initialize git and create/push a GitHub
+   repo; otherwise ask the user to create the repo and open it in Codex before
+   running `airlock-mcp init-repo`.
    Public users should normally arrive through the single Airlock MCP install,
    then ask Airlock to help build and use specs. Treat spec-building as a
    capability inside that experience, not a second install.
@@ -29,28 +35,53 @@ 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 offer three starting paths
-   before creating files:
-   - brainstorm possible specs using the OODA loop
-   - start from a known process and create a blank workspace
-   - create a `posts` feedback loop where humans and agents can submit
-     requests, observations, and responses
+3. If no workspace exists, welcome the user and ask:
+   `What process do you want to improve?`
+   Explain that Airlock works best when we can identify the loop around that
+   process:
+   - what information comes in
+   - what context helps people or agents understand it
+   - what decision needs to be made
+   - what action happens after the decision
+   Give examples before naming the concept: apps, files, forms, people, emails,
+   calls, mail, websites, APIs, data feeds, or physical events. Then call these
+   places interfaces: where the process observes from or acts through.
+   Ask whether the user already has artifacts for the process, such as CSV or
+   Excel files, JSON samples, API docs, schemas, forms, screenshots, PDFs,
+   exports, message examples, or other content people already use. A small real
+   sample is often better than a long explanation. Remind the user to redact
+   secrets before attaching files or pasting content.
+   When relevant, look to the reusable `airlock-specs` library for starting
+   points, patterns, and ideas. Do not treat those library specs as guaranteed
+   descriptions of any third-party system. Prefer current API docs, real data
+   exports, samples, and user-provided artifacts when they conflict with the
+   library, and record the reason for the divergence.
+   Ask for the messy version. Help turn it into a small first Airlock spec and
+   a plan for more. Do not create the first workspace until the user chooses a
+   path.
 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, offer OODA brainstorming first.
+   If the user is unsure, continue process discovery before creating files.
 5. 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
    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
-   speculative system.
+   speculative system, then keep a plan for later specs.
 8. On later sessions, run `airlock-mcp list-workspaces` when the target draft
    is not obvious.
 9. 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.
+   Present the summary back to the user as a structured spec card when useful:
+   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
    records.
 11. Keep `sample.records.json` as the agent-friendly authoring shape. Use
@@ -63,7 +94,9 @@ the deterministic checker.
 
 ## Spec Design Questions
 
-Resolve these in order, and write the answers into `decisions.md`:
+Use these as an internal checklist. Do not dump the whole list into chat.
+Write resolved answers into `decisions.md` and ask the human only for missing
+or risky decisions:
 
 1. What is one row about?
 2. What systems, users, files, events, or reference data must be observed before
@@ -79,17 +112,52 @@ Resolve these in order, and write the answers into `decisions.md`:
 10. Which optional context can live in a validated `variant` field?
 11. Who submits, reviews, reads, delegates, and owns the process?
 
+## Interfaces
+
+Use interface to mean any place the process observes from or acts through.
+Do not lead with the word before examples. Interfaces can be apps, files, forms,
+people, emails, calls, mail, websites, APIs, data feeds, physical events,
+shared folders, payment tools, bank apps, or other systems.
+
+When a user names a process, map the interfaces both ways:
+
+- Observe: where information enters the loop.
+- Act: where a decision writes back to the world.
+
+Spot gaps gently. A user may have one dataset but need additional observations
+to orient well, or may rely on hard-to-automate interfaces such as phone calls
+or physical mail.
+
+## Artifacts And Libraries
+
+Start from artifacts whenever they exist. Useful design artifacts include CSV
+or Excel files, JSON samples, API docs, schemas, forms, screenshots, PDFs,
+exports, message examples, and other defined content that already carries the
+process shape.
+
+Use design artifacts to infer row grain, field names, durable identifiers,
+timestamps, evidence, variants, attachment needs, and edge cases. Distinguish
+design artifacts from Airlock attachments: design artifacts help draft the spec;
+attachments are evidence files later submitted with governed records.
+
+Use `airlock-specs` as a source of reusable starting points, patterns, and
+ideas. Do not promise that Airlock spec-library shapes reflect current
+third-party APIs, exports, or business objects. If a library shape looks
+outdated, overfit, underfit, or contradicted by current artifacts, override it
+with the best current evidence and explain the decision in `decisions.md` or
+`review.md`.
+
 ## OODA Loop
 
 Use the observe-orient-decide-act loop as the product frame:
 
-- Observe: source systems, human signals, files, screenshots, exports, APIs,
-  reference specs, and prior Airlock outputs.
-- Orient: row grain, field types, access model, evidence, workflow, references,
-  expectations, and risk.
-- Decide: the smallest governed output worth creating now.
-- Act: validate locally, create in Airlock, collect real records, then extend or
-  add the next spec based on feedback.
+- Observe: controlled interface ingestion and observation/reference specs.
+- Orient: context, proposals, scoring, exception queues, summaries, and gaps in
+  the observation set.
+- Decide: governed choices by people or agents, with identity, timestamp,
+  rationale, evidence, approval, and separation of duties.
+- Act: controlled writes back to interfaces, commitments, follow-ups, outputs,
+  and the next observations created by those actions.
 
 ## Pattern Guidance
 

package/.agents/skills/airlock-mcp/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Airlock MCP"
-  short_description: "Draft and review Airlock specs with Codex."
-  default_prompt: "Use $airlock-mcp to help me draft a small Airlock spec, choose a starting pattern, and check the local workspace."
+  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."

package/README.md

@@ -5,18 +5,21 @@ Airlock.
 
 It covers the full Airlock loop:
 
-- build specs with the bundled spec-building workbench
-- use specs to pull and push governed data with the Airlock Star capability
+- 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
 - validate, create, and revise specs against installed Airlock
-- capture real use cases and improvements so specs get better over time
 
 Spec building is not a second thing users install. It is bundled inside
 Airlock MCP.
 
-Airlock Star is not a second thing users install either. It is the capability
-inside Airlock MCP for working through real Airlock use cases,
-pulling and pushing data through specs, reading outputs, and turning experience
-back into better specs.
+Airlock MCP gives agents two kinds of Airlock expertise:
+
+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.
 
 ## Install
 
@@ -26,7 +29,7 @@ Dogfood directly from GitHub:
 npx -y github:reunionstudio/airlock-mcp install --package github:reunionstudio/airlock-mcp
 ```
 
-After the npm package is published, use:
+Install from npm:
 
 ```bash
 npx @reunionstudio/airlock-mcp install
@@ -45,9 +48,14 @@ The GitHub dogfood command registers:
 codex mcp add airlock -- npx -y github:reunionstudio/airlock-mcp server
 ```
 
-The server exposes bootstrap guidance for starting a specs repo and entering
-the bundled spec-building workbench or the Airlock Star use-and-improve
-capability.
+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.
+
+Workspace summaries are structured spec cards. They present the current spec
+core, file rules, attachment policy, guest access, column rules, sample record
+shape, note-file status, and local check status so Codex can reflect the draft
+back to the user before asking for decisions.
 
 This install shape uses Node because `npx` runs npm package binaries. MCP itself
 does not require Node. Once Airlock MCP does real operational work, such as
@@ -81,7 +89,7 @@ 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 blank specs repo.
+- `airlock_init_repo`: bootstrap a Git-backed specs repo.
 - `airlock_list_patterns` and `airlock_show_pattern`: inspect starter patterns.
 - `airlock_init_workspace`: create a workspace from `blank` or `posts`.
 - `airlock_list_workspaces`: inspect active or archived drafts.
@@ -114,13 +122,27 @@ The intended user flow is:
 
 1. Run `npx @reunionstudio/airlock-mcp install` once for the agent environment.
 2. Open Codex.
-3. Create a blank project repo named for the org or project, such as
-   `home-specs`.
-4. Ask Codex to use Airlock MCP to help build specs and use specs with
-   Airlock Star.
-5. Let Airlock MCP bootstrap the project, welcome the user, and offer the next
-   useful path before creating the first workspace.
+3. Create or open a Git-backed specs repo named for the org or project, such as
+   `home-specs`. GitHub is the recommended default when available.
+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.
 
 The first workspace should not be created automatically. The spec-building
-workbench should offer OODA brainstorming, a known-process draft, or a shared
-`posts` feedback loop.
+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.
+
+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,
+exports, message examples, or other defined content people already use. These
+are design artifacts for drafting the spec; later Airlock attachments are
+evidence files submitted with governed records.
+
+Airlock MCP can also consult the reusable `airlock-specs` library for starting
+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.

package/docs/architecture.md

@@ -28,9 +28,10 @@ heavier operational tools mature.
 
 The spec-building workbench lives in this repo under `src/airlock_mcp`,
 `patterns`, `workspaces`, `schemas`, and `.agents/skills/airlock-mcp`.
-Airlock Star is the use-and-improve capability inside Airlock MCP: real use
-cases, governed pull/push through specs, output review, and improvement capture.
-It is also not a second install.
+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.
 
 ## MCP Surface
 
@@ -44,10 +45,10 @@ The bootstrap server exposes:
   `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 blank `<project>-specs` repo,
-enter the spec-building workbench when specs need drafting, enter Star when
-specs need to be used or improved, and avoid creating a first workspace until
-the user chooses a path.
+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.
 
 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

@@ -12,9 +12,12 @@ npx @reunionstudio/airlock-mcp install
 ```
 
 Airlock MCP is the single installed interface for agents working with Airlock.
-Then the user opens Codex, creates a blank `<project>-specs` repo, and starts
-chatting with Airlock. Airlock MCP should cover building specs, using specs to
-pull and push governed data, and capturing improvements from real use cases.
+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.
 
 The install command is not the spec workspace. It is the connector/setup entry
 point. The specs repo is still the durable memory.
@@ -106,7 +109,13 @@ packaging pressure appears.
 The first release should optimize the user journey:
 
 1. install connector
-2. create blank `<project>-specs` Codex project
-3. bootstrap the spec-building capability when specs need drafting
-4. help the user use specs to validate, load, read, push, and pull data
-5. create the first workspace only after the user chooses a path
+2. create or open a Git-backed `<project>-specs` Codex project
+3. ask where the repo directory should live if Codex is creating it
+4. ask what process the user wants to improve
+5. ask for existing artifacts such as CSV, Excel, JSON, API docs, schemas,
+   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

package/docs/ooda-loop.md

@@ -1,21 +1,38 @@
 # OODA Loop For Airlock Specs
 
-Airlock specs should support a business loop, not just a table.
+Airlock specs should support a process loop, not just a table.
+
+Airlock works best when we can identify where information comes in and where
+actions go out. Those places might be apps, files, forms, people, emails, calls,
+mail, websites, APIs, data feeds, physical events, payment tools, bank apps, or
+shared folders. After those examples are clear, call them interfaces: where the
+process observes from or acts through.
+
+Start from existing artifacts when they exist: CSV or Excel files, JSON samples,
+API docs, schemas, forms, screenshots, PDFs, exports, message examples, or other
+defined content people already use. A real sample often reveals identifiers,
+timestamps, optional fields, and edge cases faster than chat can.
+
+The reusable `airlock-specs` library can provide starting points, patterns, and
+ideas. It is not a guarantee of the current shape of any third-party API,
+export, or business object. Current docs and actual samples should override the
+library when they conflict.
 
 ## Observe
 
-Name the evidence and systems that matter:
+Name the interfaces, evidence, and signals that matter:
 
 - human entries
 - agent observations
 - screenshots, PDFs, receipts, exports, or source files
+- CSV, Excel, JSON, API docs, schemas, forms, or message examples
 - source APIs or app objects
 - existing Airlock specs or reference data
 - downstream system state
 
 ## Orient
 
-Turn observations into a governed shape:
+Turn observations into context that can support a decision:
 
 - one row grain
 - durable identifiers
@@ -27,14 +44,20 @@ Turn observations into a governed shape:
 - workflow
 - references
 - expectations
+- missing observations or quality gaps
 
 ## Decide
 
-Choose the smallest governed output worth creating now. If uncertainty is high,
-start with `posts` and let real feedback shape the next spec.
+Capture the governed choice. A decision spec should identify who or what made
+the choice, when it happened, which option was selected, what evidence or
+rationale mattered, and what separation of duties applies.
 
 ## Act
 
-Create the spec in Airlock only after local drafting is coherent. Then collect
-records, review them, and decide whether to revise the spec or add the next
-small spec.
+Model the action that follows the decision: send an email, submit payment,
+update a website, change a price, open a ticket, trigger outreach, produce a
+filing, request more evidence, or create another governed output. The action
+creates new observations and the loop spins again.
+
+Start with one small useful spec, then keep a plan for the next specs that
+complete or improve the loop.

package/docs/spec-workbench-architecture.md

@@ -125,8 +125,9 @@ 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
-a separate `<project>-specs` repo and works there with Codex. Users should ask
-for Airlock, not install a separate spec-building tool.
+or opens a separate Git-backed `<project>-specs` repo in a user-chosen location
+and works there with Codex. GitHub is the recommended default when available.
+Users should ask for Airlock, not install a separate spec-building tool.
 
 For Codex, the install command should use the platform MCP manager rather than
 editing config files directly:

package/docs/workflows.md

@@ -2,7 +2,7 @@
 
 ## Start A New Specs Repo
 
-Use this when a person opens a blank Codex project and wants to start working
+Use this when a person opens a new Codex project and wants to start working
 with real Airlock specs. The project repo is where they work. Public users
 should come through the single Airlock MCP install; this repo provides the
 spec-building capability behind that experience.
@@ -10,6 +10,11 @@ spec-building capability behind that experience.
 Ask for the project or organization name first, then lowercase it, replace
 spaces with hyphens, and append `-specs`. For example, `Home` becomes
 `home-specs`. Reserve `airlock-specs` for the canonical reusable spec library.
+Recommend a real Git repo for the specs project. GitHub is the recommended
+default when the user already has GitHub set up, but any normal repository host
+is acceptable. If Codex is creating the repo, ask where the `<slug>-specs`
+directory should live before making files, then offer to initialize git and
+create or push the GitHub repo.
 Airlock itself does not create this repo; Codex can create it locally while
 helping the user start an Airlock specs project.
 Start in Codex, not Snowflake Cortex. Snow CLI or Cortex only matters later when
@@ -20,10 +25,22 @@ The preferred Codex prompt is:
 ```text
 I want to use Airlock MCP to start working with Airlock specs for Home.
 
-Set up this project as an Airlock specs repo. Use the Airlock MCP
-spec-building capability when we need to draft or revise specs. Welcome me,
-help me think through real Airlock use cases, and ask only for the missing
-decisions. Do not create the first workspace until I choose a path.
+Set up this project as an Airlock specs repo. If this project is not already a
+Git repo, recommend storing it in version control, preferably GitHub if
+available. If you are creating the repo for me, ask where the `home-specs`
+directory should live before making files.
+
+Welcome me by asking what process I want to improve. Explain that Airlock works
+best when we can identify the loop around that process: what information comes
+in, what context helps us understand it, what decision needs to be made, and
+what action happens after the decision. Ask whether I already have artifacts:
+CSV or Excel files, JSON samples, API docs, schemas, forms, screenshots, PDFs,
+exports, message examples, or other content people already use. When useful,
+check the reusable airlock-specs library for starting points, patterns, and
+ideas, but prefer current API docs, real exports, samples, and other artifacts
+when they conflict with a library shape. Ask for the messy version, then help
+turn it into a small first Airlock spec and a plan for more. Do not create the
+first workspace until I choose a path.
 ```
 
 When dogfooding this implementation repo before the MCP package is published,
@@ -50,9 +67,10 @@ The connector implementation lives in `reunionstudio/airlock-mcp`; this
 workbench keeps the Airlock MCP spec-building capability.
 
 That should install or register the Airlock MCP connector for the user's agent
-environment. After that, the user still creates a blank `<slug>-specs` project
-and starts chatting there. Airlock MCP covers building specs, using specs to
-pull and push governed data, and improving specs from real use cases.
+environment. After that, the user still creates or opens a Git-backed
+`<slug>-specs` project and starts chatting there. Airlock MCP covers building
+specs, using specs to pull and push governed data, and improving specs from real
+use cases.
 
 For Codex, the install command should register the server with:
 
@@ -64,28 +82,59 @@ The MCP-style flow should be:
 
 1. Run `npx @reunionstudio/airlock-mcp install` once for the agent environment.
 2. Open Codex.
-3. Create a new blank project named for the org or project, such as
+3. Create or open a Git-backed specs repo named for the org or project, such as
    `home-specs`.
-4. Tell Codex: `Use Airlock to help me build and use specs.`
-5. Airlock MCP welcomes, offers OODA brainstorming, a known-process draft, a
-   `posts` feedback loop, or installed-Airlock validation/use.
+4. If Codex is creating it, choose where the repo directory should live before
+   files are written.
+5. Tell Codex: `Use Airlock to help me improve a process with specs.`
+6. Airlock MCP welcomes, asks what process the user wants to improve, explains
+   the loop around the process, and proposes a small first spec plus a plan for
+   more.
 
 `init-repo` creates `AGENTS.md`, `.agents/skills/airlock-mcp/SKILL.md`, and
 `workspaces/`. That is what lets Codex understand prompts such as
 `Use $airlock-mcp` inside the specs repo.
 
-After bootstrap, offer three paths before creating a workspace:
+After bootstrap, do not start with a pattern picker. Ask:
 
-- brainstorm possible specs using the OODA loop
-- start from a known process and create a blank workspace
-- create a `posts` feedback loop for humans and agents to submit requests,
-  observations, and responses
+```text
+What process do you want to improve?
+```
+
+Then explain:
+
+- Airlock works best when we can identify what information comes in.
+- Airlock works best when we can identify what context helps people or agents
+  understand that information.
+- Airlock works best when we can identify what decision needs to be made.
+- Airlock works best when we can identify what action happens after the
+  decision.
+
+Information may come from apps, files, forms, people, emails, calls, mail,
+websites, APIs, data feeds, or physical events. Actions may go back through
+those same places. After giving examples, call these places interfaces: where
+the process observes from or acts through.
+
+Ask whether the user already has artifacts for the process: CSV or Excel files,
+JSON samples, API docs, schemas, forms, screenshots, PDFs, exports, message
+examples, or other content people already use. Treat these as design artifacts
+for drafting the spec. They are different from Airlock attachments, which are
+evidence files submitted later with governed records.
+
+When useful, point at the reusable `airlock-specs` library for starting points,
+patterns, and ideas. Do not treat those library specs as guaranteed to reflect
+the current shape of third-party systems. If current API docs, exports, samples,
+schemas, or user-provided artifacts disagree with the library, prefer the
+current artifacts and record the divergence.
+
+Ask for the messy version. Help turn it into a small first Airlock spec and a
+plan for more.
 
 ## Start From Feedback
 
 Use this when the user chooses a shared feedback loop for humans and agents.
-If they are not sure what to model yet, offer OODA brainstorming before creating
-this workspace.
+If they are not sure what to model yet, continue process discovery before
+creating this workspace.
 
 ```bash
 airlock-mcp init feedback-loop --pattern posts
@@ -124,6 +173,11 @@ Supported input shapes:
 - a raw canonical object with `core_config` or `column_config`
 - a legacy `{"specs": [{"config": ...}]}`
 
+Spec-library imports are starting points, not live system contracts. Before
+using one for a third-party system, compare it with current API docs, CSV or
+Excel exports, JSON samples, schemas, forms, and other real artifacts. Override
+outdated or mismatched fields when current evidence says the shape has changed.
+
 ## Clone A Workspace
 
 Use this when a related spec should preserve most design choices but needs a new
@@ -167,7 +221,10 @@ airlock-mcp next workspaces/team-posts
 
 The summary shows the current spec identity, required fields, variant fields,
 attachment posture, guest access model, sample record count, note-file status,
-and local check counts.
+and local check counts. It is organized as a structured spec card with sections
+for core, file rules, attachments, guest access, column rules, samples, notes,
+and check status so Codex can present the draft back to the user before asking
+for decisions.
 
 `next` prints the same recap plus a conservative next action: fix local errors,
 review warnings, fill open design prompts in `decisions.md`, add sample records,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reunionstudio/airlock-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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.0",
+    version="0.1.2",
     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.0"
+__version__ = "0.1.2"

package/src/airlock_mcp/bootstrap.py

@@ -29,6 +29,13 @@ Reserve `airlock-specs` for the canonical reusable Airlock spec library. A
 team, customer, domain, or project should use its own scoped repo name such as
 `home-specs`, `acme-finance-specs`, or `customer-onboarding-specs`.
 
+Specs work should live in a real version-controlled repo. Prefer GitHub when
+the user already uses GitHub, but any normal Git host is acceptable. Before
+creating a new `<slug>-specs` directory, ask where it should live. If Codex can
+create the repo, offer to initialize git and create or push the GitHub repo. If
+not, ask the user to create the repo and open it in Codex before bootstrapping
+Airlock MCP files.
+
 Airlock itself does not create this repo. Codex can create it locally while
 helping the user start an Airlock MCP project, then Airlock receives the
 finished spec later. Start in Codex, not Snowflake Cortex. Snow CLI or Cortex
@@ -37,23 +44,47 @@ installed Airlock app.
 
 ## Starting A Spec Project
 
-After bootstrap, welcome the user and orient before creating a workspace. Ask
-whether they want to:
+After bootstrap, welcome the user and orient before creating a workspace. Start
+with:
+
+What process do you want to improve?
+
+Explain that Airlock works best when we can identify the loop around that
+process:
+
+1. what information comes in
+2. what context helps people or agents understand it
+3. what decision needs to be made
+4. what action happens after the decision
+
+Information may come from apps, files, forms, people, emails, calls, mail,
+websites, APIs, data feeds, or physical events. Actions may go back through
+those same places. After giving examples, call these places interfaces: where
+the process observes from or acts through.
+
+Ask whether the user already has artifacts for the process: CSV or Excel files,
+JSON samples, API docs, schemas, forms, screenshots, PDFs, exports, message
+examples, or other defined content people already use. A small real sample is
+often better than a long explanation. Remind the user to redact secrets before
+attaching files or pasting content.
 
-- brainstorm possible specs with the OODA loop
-- start from a known process they already have in mind
-- create a shared `posts` feedback loop for humans and agents to submit
-  requests, observations, and responses
+Use `airlock-specs` as a reusable library of starting points, patterns, and
+ideas when it is available. Do not assume library specs match the current shape
+of a third-party API, export, or business object. Prefer current API docs, real
+data exports, samples, and user-provided artifacts when they conflict with the
+library, and record the reason for the divergence.
 
-Create `posts` only when the user chooses a feedback loop or explicitly asks
-for the posts pattern.
+Ask for the messy version. Help turn it into a small first Airlock spec and a
+plan for more. Do not create the first workspace until the user chooses a path.
+Create `posts` only when the user wants a shared feedback loop or explicitly
+asks for the posts pattern.
 
 ## Working Style
 
 - Use the repo-scoped `$airlock-mcp` skill for spec drafting, review, and
   pattern selection.
 - Keep drafts small and concrete. Prefer one useful governed output over a
-  large speculative process map.
+  large speculative process map, then keep a plan for later specs.
 - Preserve decisions in workspace files so future Codex sessions can resume
   without relying on chat memory.
 - Use `airlock-mcp list-workspaces` before guessing which draft to resume.
@@ -78,6 +109,11 @@ Resolve these before final JSON:
 - workflow and pushback
 - references and expectations
 - delegation and agent identity
+- interfaces observed from or acted through
+- existing artifacts such as CSV, Excel, JSON, API docs, schemas, exports,
+  forms, screenshots, PDFs, or message examples
+- whether an `airlock-specs` library pattern was used, changed, or rejected
+- likely gaps in observations, orientation, decisions, or actions
 - observe-orient-decide-act loop
 
 Do not encode Airlock lifecycle state, reviewer notes, approval status, or
@@ -154,8 +190,9 @@ def format_bootstrap_result(result: BootstrapResult) -> str:
             "",
             "next:",
             "1. Open this repo in Codex.",
-            "2. Ask: Use Airlock to help me build and use specs.",
-            "3. Choose OODA brainstorming, a known process, or a posts feedback loop.",
+            "2. Keep this specs project in git; GitHub is recommended when available.",
+            "3. Ask: Use Airlock to help me build and use specs.",
+            "4. Start with: What process do you want to improve?",
         ]
     )
     return "\n".join(lines)

package/src/airlock_mcp/cli.py

@@ -303,7 +303,7 @@ def build_parser() -> argparse.ArgumentParser:
     about_parser = subparsers.add_parser("about", help="Show the Airlock MCP mark and command map.")
     about_parser.set_defaults(func=about)
 
-    init_repo_parser = subparsers.add_parser("init-repo", help="Prepare a specs repo for Codex and Airlock MCP.")
+    init_repo_parser = subparsers.add_parser("init-repo", help="Prepare a Git-backed specs repo for Codex and Airlock MCP.")
     init_repo_parser.add_argument("path", nargs="?", default=".", help="Specs repo path. Defaults to current directory.")
     init_repo_parser.add_argument("--force", action="store_true", help="Overwrite AGENTS.md and the repo-scoped skill.")
     init_repo_parser.set_defaults(func=init_repo)

package/src/airlock_mcp/manage.py

@@ -233,8 +233,24 @@ def next_steps(workspace: Path) -> str:
         lines.append(f"2. Run `airlock-mcp summary {workspace}` to confirm the shape.")
         return "\n".join(lines)
     if _text_has_open_placeholders(workspace / "decisions.md"):
-        lines.append("1. Fill in decisions.md for row grain, identifiers, time, evidence, access, and OODA.")
-        lines.append(f"2. Run `airlock-mcp next {workspace}` when the design notes are current.")
+        spec_name = ""
+        if isinstance(spec, dict):
+            core_config = spec.get("core_config")
+            if isinstance(core_config, dict):
+                spec_name = str(core_config.get("spec_name") or "")
+        if spec_name == "posts":
+            lines.append("1. Record the starter assumptions in decisions.md, or change only what is wrong.")
+            lines.append(
+                "2. Defaults: one row is one post/request/observation/response; "
+                "submitters are the owner and approved agents; evidence is optional; "
+                "posted_at is authored or captured time."
+            )
+            lines.append("3. Use posts to collect messy process feedback, then plan the first observe, orient, decide, or act spec.")
+        else:
+            lines.append("1. Record the messy process goal and first-loop assumptions in decisions.md.")
+            lines.append("2. Identify what is observed, what helps orient, what decision is governed, and what action follows.")
+            lines.append("3. Keep the first spec small and note later specs in review.md.")
+        lines.append(f"4. Run `airlock-mcp next {workspace}` when the design notes are current.")
         return "\n".join(lines)
     records = sample.get("records") if isinstance(sample, dict) else []
     if not records:

package/src/airlock_mcp/summary.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 from pathlib import Path
 from typing import Any
 
@@ -30,6 +31,40 @@ def _variant_shape_fields(spec_config: dict[str, Any]) -> set[str]:
     return fields
 
 
+def _format_value(value: Any, *, default: str = "unknown") -> str:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (dict, list)):
+        text = json.dumps(value, sort_keys=True, separators=(",", ":"))
+    else:
+        text = str(value)
+    return text if text else default
+
+
+def _format_literal(value: Any, *, default: str = "unknown") -> str:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, str):
+        return json.dumps(value)
+    return str(value)
+
+
+def _join(values: list[str], *, default: str = "none") -> str:
+    cleaned = [value for value in values if value]
+    return ", ".join(cleaned) if cleaned else default
+
+
+def _truncate(value: Any, limit: int = 96) -> str:
+    text = _format_value(value, default="")
+    if len(text) <= limit:
+        return text
+    return text[: limit - 3] + "..."
+
+
 def _guest_access_summary(spec_config: dict[str, Any]) -> str:
     guest_access = spec_config.get("guest_access")
     if not isinstance(guest_access, dict):
@@ -50,6 +85,34 @@ def _guest_access_summary(spec_config: dict[str, Any]) -> str:
     return "shared public folder: " + (", ".join(enabled) if enabled else "no enabled subfolders")
 
 
+def _enabled_guest_subfolders(guest_access: dict[str, Any]) -> list[str]:
+    public_folder = guest_access.get("public_folder")
+    if not isinstance(public_folder, dict):
+        return []
+    subfolders = public_folder.get("subfolders")
+    if not isinstance(subfolders, dict):
+        return []
+    return [
+        str(name)
+        for name, value in subfolders.items()
+        if isinstance(value, dict) and value.get("enabled") is True
+    ]
+
+
+def _guest_role_lines(guest_access: dict[str, Any]) -> list[str]:
+    roles = guest_access.get("guest_roles")
+    if not isinstance(roles, list):
+        return []
+    lines: list[str] = []
+    for role in roles:
+        if not isinstance(role, dict):
+            continue
+        role_name = _format_value(role.get("role_name"))
+        access_level = _format_value(role.get("access_level"))
+        lines.append(f"{role_name} -> {access_level}")
+    return lines
+
+
 def _attachment_summary(spec_config: dict[str, Any]) -> str:
     policy = spec_config.get("attachment_policy")
     if not isinstance(policy, dict):
@@ -59,6 +122,86 @@ def _attachment_summary(spec_config: dict[str, Any]) -> str:
     return "required" if policy.get("attachment_required") is True else "optional"
 
 
+def _column_tests(column: dict[str, Any]) -> list[str]:
+    tests = column.get("tests")
+    return [str(test) for test in tests if isinstance(test, str)] if isinstance(tests, list) else []
+
+
+def _column_line(column: dict[str, Any], variant_shapes: set[str]) -> str:
+    name = _format_value(column.get("name"))
+    column_type = _format_value(column.get("type"))
+    tests = _column_tests(column)
+    attributes: list[str] = []
+    if "not_null" in tests:
+        attributes.append("required")
+    if "unique" in tests:
+        attributes.append("unique")
+    extra_tests = [test for test in tests if test not in {"not_null", "unique"}]
+    if extra_tests:
+        attributes.append("tests: " + ", ".join(extra_tests))
+    if column.get("type") == "variant":
+        attributes.append("variant shaped" if name in variant_shapes else "variant unshaped")
+    if column.get("format"):
+        attributes.append("format " + _format_value(column.get("format")))
+    description = column.get("description")
+    suffix = f" - {_truncate(description, 140)}" if isinstance(description, str) and description else ""
+    return f"  - {name}: {column_type}; {_join(attributes)}{suffix}"
+
+
+def _variant_rule_lines(spec_config: dict[str, Any]) -> list[str]:
+    rules = spec_config.get("rules")
+    if not isinstance(rules, list):
+        return []
+    lines: list[str] = []
+    for rule in rules:
+        if not isinstance(rule, dict) or rule.get("type") != "variant_shape":
+            continue
+        field = rule.get("field", rule.get("column"))
+        if not isinstance(field, str) or not field:
+            field = "unknown"
+        roots = rule.get("allowed_root_keys")
+        root_values = [str(value) for value in roots if isinstance(value, str)] if isinstance(roots, list) else []
+        paths = rule.get("paths")
+        path_count = len(paths) if isinstance(paths, list) else 0
+        required_count = (
+            len([path for path in paths if isinstance(path, dict) and path.get("required") is True])
+            if isinstance(paths, list)
+            else 0
+        )
+        lines.append(
+            f"  - {field}: roots {_join(root_values)}; paths {path_count}; required_paths {required_count}"
+        )
+    return lines
+
+
+def _ordered_record_fields(columns: list[dict[str, Any]], record: dict[str, Any]) -> list[str]:
+    ordered = [
+        str(column.get("name"))
+        for column in columns
+        if isinstance(column.get("name"), str) and column.get("name") in record
+    ]
+    extras = sorted(str(key) for key in record if str(key) not in ordered)
+    return ordered + extras
+
+
+def _sample_key(columns: list[dict[str, Any]], records: list[Any]) -> str:
+    if not records or not isinstance(records[0], dict):
+        return "none"
+    first = records[0]
+    preferred: list[str] = []
+    for test_name in ("unique", "not_null"):
+        preferred.extend(
+            str(column.get("name"))
+            for column in columns
+            if isinstance(column.get("name"), str) and test_name in _column_tests(column)
+        )
+    preferred.extend(str(column.get("name")) for column in columns if isinstance(column.get("name"), str))
+    for field in preferred:
+        if field in first and not isinstance(first[field], (dict, list)):
+            return f"{field}={_truncate(first[field])}"
+    return "none"
+
+
 def _text_status(workspace: Path, filename: str) -> str:
     path = workspace / filename
     if not path.exists():
@@ -82,34 +225,83 @@ def workspace_summary(
     variants = [str(column.get("name")) for column in columns if column.get("type") == "variant"]
     variant_shapes = _variant_shape_fields(spec_config)
     records = sample_records.get("records")
-    record_count = len(records) if isinstance(records, list) else 0
+    record_list = records if isinstance(records, list) else []
+    record_count = len(record_list)
+    first_record = record_list[0] if record_list and isinstance(record_list[0], dict) else {}
     file_rules = spec_config.get("file_rules")
     file_format = file_rules.get("file_format") if isinstance(file_rules, dict) else None
-    file_type = file_format.get("file_type") if isinstance(file_format, dict) else "unknown"
+    file_format = file_format if isinstance(file_format, dict) else {}
+    guest_access = spec_config.get("guest_access")
+    guest_access = guest_access if isinstance(guest_access, dict) else {}
+    attachment_policy = spec_config.get("attachment_policy")
+    attachment_policy = attachment_policy if isinstance(attachment_policy, dict) else {}
+    variant_rule_lines = _variant_rule_lines(spec_config)
 
     lines = [
         f"workspace: {workspace}",
         f"spec: {core.get('spec_name', 'unknown')} ({core.get('spec_alias', 'no alias')})",
-        f"owner_role: {core.get('owner_role', 'unknown')}",
-        f"columns: {len(columns)} total, {len(required)} required, {len(variants)} variant",
-        "required_fields: " + (", ".join(required) if required else "none"),
-        "variant_fields: "
-        + (
-            ", ".join(
-                f"{name}{' shaped' if name in variant_shapes else ' unshaped'}" for name in variants
-            )
-            if variants
-            else "none"
-        ),
-        f"sample_records: {record_count}",
-        f"file_type: {file_type}",
-        f"attachments: {_attachment_summary(spec_config)}",
-        f"guest_access: {_guest_access_summary(spec_config)}",
-        "notes: "
-        + "; ".join(
-            _text_status(workspace, filename)
-            for filename in ("brief.md", "decisions.md", "questions.md", "review.md")
-        ),
-        f"check: {len(result.errors)} error(s), {len(result.warnings)} warning(s)",
+        "",
+        "core:",
+        f"  spec_name: {_format_value(core.get('spec_name'))}",
+        f"  spec_alias: {_format_value(core.get('spec_alias'), default='none')}",
+        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"  description: {_truncate(core.get('description')) or 'none'}",
+        "",
+        "file_rules:",
+        f"  file_type: {_format_value(file_format.get('file_type'))}",
+        f"  parse_header: {_format_value(file_format.get('parse_header'))}",
+        f"  save_header: {_format_value(file_format.get('save_header'))}",
+        f"  field_delimiter: {_format_literal(file_format.get('field_delimiter'))}",
+        f"  record_delimiter: {_format_literal(file_format.get('record_delimiter'))}",
+        f"  encoding: {_format_value(file_format.get('encoding'))}",
+        "",
+        "attachments:",
+        f"  summary: {_attachment_summary(spec_config)}",
+        f"  enabled: {_format_value(attachment_policy.get('attachments_enabled'))}",
+        f"  required: {_format_value(attachment_policy.get('attachment_required'))}",
+        "",
+        "guest_access:",
+        f"  summary: {_guest_access_summary(spec_config)}",
+        f"  isolated_directories_enabled: {_format_value(guest_access.get('isolated_directories_enabled'))}",
+        f"  public_folder_enabled: {_format_value((guest_access.get('public_folder') or {}).get('enabled') if isinstance(guest_access.get('public_folder'), dict) else None)}",
+        f"  enabled_subfolders: {_join(_enabled_guest_subfolders(guest_access))}",
+        f"  guest_roles: {_join(_guest_role_lines(guest_access))}",
+        "",
+        "column_rules:",
+        f"  total: {len(columns)}",
+        f"  required_fields: {_join(required)}",
+        f"  variant_fields: {_join([f'{name} shaped' if name in variant_shapes else f'{name} unshaped' for name in variants])}",
+        "  columns:",
     ]
+    lines.extend(_column_line(column, variant_shapes) for column in columns)
+    lines.extend(
+        [
+            "  variant_shape_rules:",
+            *(variant_rule_lines if variant_rule_lines else ["  - none"]),
+            "",
+            "samples:",
+            f"  spec_name: {_format_value(sample_records.get('spec_name'))}",
+            f"  filename: {_format_value(sample_records.get('filename'))}",
+            f"  records: {record_count}",
+            f"  first_record_key: {_sample_key(columns, record_list)}",
+            f"  first_record_fields: {_join(_ordered_record_fields(columns, first_record))}",
+            "",
+            "notes:",
+            *(
+                f"  {_text_status(workspace, filename)}"
+                for filename in ("brief.md", "decisions.md", "questions.md", "review.md")
+            ),
+            "",
+            "check:",
+            f"  errors: {len(result.errors)}",
+            f"  warnings: {len(result.warnings)}",
+        ]
+    )
+    if result.findings:
+        lines.append("  findings:")
+        lines.extend(
+            f"  - {finding.level}: {finding.path}: {finding.message}" for finding in result.findings
+        )
     return "\n".join(lines)

package/src/mcp.mjs

@@ -44,10 +44,10 @@ export function handleMcpRequest(message) {
       },
       serverInfo: {
         name: "airlock",
-        version: "0.1.0",
+        version: "0.1.2",
       },
       instructions:
-        "Airlock MCP helps agents build and use Airlock specs. Use airlock_start for orientation or the airlock_* tools to bootstrap, draft, check, summarize, export, and render specs.",
+        "Airlock MCP helps agents improve processes with Airlock specs. Use airlock_start for orientation or the airlock_* tools to bootstrap, draft, check, summarize, export, and render specs.",
     });
   }
 
@@ -84,7 +84,7 @@ export function handleMcpRequest(message) {
         {
           name: "airlock-start",
           title: "Start Airlock",
-          description: "Bootstrap a blank specs repo and choose the first Airlock path.",
+          description: "Bootstrap a Git-backed specs repo and choose the first Airlock path.",
           arguments: [
             {
               name: "project",
@@ -103,7 +103,7 @@ export function handleMcpRequest(message) {
     }
     const project = params?.arguments?.project || "Home";
     return makeResponse(id, {
-      description: "Start building and using Airlock specs in a blank specs repo.",
+      description: "Start building and using Airlock specs in a Git-backed specs repo.",
       messages: [
         {
           role: "user",

package/src/text.mjs

@@ -21,18 +21,40 @@ export function airlockPrompt(project) {
   const repoName = specsRepoName(project);
   return `I want to use Airlock MCP to start working with Airlock specs for ${repoName}.
 
-Set up this project as an Airlock specs repo. Use Airlock MCP
-spec-building when we need to draft or revise specs. Welcome me,
-help me think through real Airlock use cases, and ask only for the missing
-decisions. Do not create the first workspace until I choose a path.`;
+Set up this project as an Airlock specs repo. If this project is not already a
+Git repo, recommend storing it in version control, preferably GitHub if that is
+available. If you are creating the repo for me, ask where the ${repoName}
+directory should live before making it, then offer to initialize git and create
+or push a GitHub repo.
+
+Welcome me by asking what process I want to improve. Explain that Airlock works
+best when we can identify the loop around that process: what information comes
+in, what context helps us understand it, what decision needs to be made, and
+what action happens after the decision. Information may come from apps, files,
+forms, people,
+emails, calls, mail, websites, APIs, data feeds, or physical events. Actions
+may go back through those same places. Ask whether I already have artifacts:
+CSV or Excel files, JSON samples, API docs, schemas, forms, screenshots, PDFs,
+exports, message examples, or other content people already use. Treat a small
+real sample as stronger evidence than a long explanation, and remind me to
+redact secrets.
+
+When useful, check the reusable airlock-specs library for starting points,
+patterns, and ideas, but do not assume those library specs match current
+third-party systems. Prefer current API docs, real exports, samples, and other
+artifacts when they conflict with a library shape.
+
+Ask for the messy version, then help turn it into a small first Airlock spec
+and a plan for more. Do not create the first workspace until I choose a path.`;
 }
 
 export function nextSteps(project) {
   const repoName = specsRepoName(project);
   return `Next:
   1. Open Codex.
-  2. Create a new blank project named ${repoName}.
-  3. Ask Codex:
+  2. Create or open a Git-backed specs repo named ${repoName}. GitHub is the recommended default when available.
+  3. If Codex is creating it, ask Codex where the ${repoName} directory should live before it makes files.
+  4. Ask Codex:
 
 ${airlockPrompt(project)
   .split("\n")
@@ -40,47 +62,68 @@ ${airlockPrompt(project)
   .join("\n")}
 
 Airlock MCP will offer:
-  - spec-building with the bundled workbench
-  - spec use and improvement loops with Airlock Star
-  - guidance for pulling and pushing governed data through specs
-  - OODA brainstorming for possible specs
-  - a blank workspace for a known process
-  - a posts feedback loop for shared human/agent feedback`;
+  - process discovery before choosing a spec pattern
+  - spec design with the bundled workbench
+  - Airlock operating patterns for OODA loops and separation of duties
+  - observe specs for controlled interface ingestion
+  - orient specs for proposals, context, scoring, or exception queues
+  - decision specs and action specs for governed follow-through
+  - 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`;
 }
 
 export function gettingStartedText(project) {
   return `# Airlock MCP
 
 Airlock MCP is the single installed interface for AI agents working with
-Airlock. It helps a person and their agent build specs, pull and push governed data
-through specs, and improve Airlock workflows from real use cases.
+Airlock. It helps a person and their agent improve processes by designing
+specs, using specs for governed data movement, and planning OODA loops that
+can be assisted by people or agents.
 
-The Airlock MCP spec-building workbench drafts, checks, revises, imports,
-clones, and prepares specs for installed Airlock validation.
+Airlock MCP gives agents two kinds of Airlock expertise:
 
-Airlock Star is the use-and-improve capability inside Airlock MCP. Use it when
-someone wants to pull or push governed data through specs, exercise real
-Airlock workflows, inspect outputs, or turn field experience into spec
-improvements.
+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.
 
-Start in a blank project specs repo such as ${specsRepoName(project)}. Do not
-work inside the Airlock MCP implementation repo unless you are changing the
-tools themselves.
+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
+making files. Do not work inside the Airlock MCP implementation repo unless you
+are changing the tools themselves.
 
-Use this prompt in the blank specs repo:
+Use this prompt in the specs repo:
 
 ${airlockPrompt(project)}
 
-After bootstrap, choose the next useful path:
+First ask: What process do you want to improve?
 
-1. Brainstorm possible specs using the OODA loop.
-2. Start from a known process and create a blank workspace.
-3. Create a posts feedback loop for humans and agents to submit requests,
-   observations, and responses.
-4. Use Airlock Star with an installed Airlock app to validate specs, load data,
-   read outputs, plan push/pull workflows, and capture improvements.
+Airlock works best when we can identify the loop around a process:
 
-Create posts only when the user chooses the feedback-loop path.`;
+1. Observe: what information comes in.
+2. Orient: what context helps people or agents understand it.
+3. Decide: what choice needs to be governed.
+4. Act: what happens after the decision.
+
+Information may come from apps, files, forms, people, emails, calls, mail,
+websites, APIs, data feeds, or physical events. Actions may go back through
+those same places. Airlock calls these places interfaces: where the process
+observes from or acts through.
+
+If you already have artifacts, attach or point Codex at them: CSV or Excel
+files, JSON samples, API docs, schemas, forms, screenshots, PDFs, exports,
+message examples, or other defined content people already use. A small real
+sample is often better than a long explanation. Redact secrets before sharing.
+
+Airlock MCP can also use the reusable airlock-specs library for starting
+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.
+
+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.`;
 }
 
 export function helpText() {
@@ -103,6 +146,7 @@ Options:
 
 Airlock MCP is the single installed interface for agents working with Airlock.
 Spec building is bundled inside that experience.
-Airlock Star is the use-and-improve capability inside that experience.
+Airlock operating patterns help connect specs into OODA loops, separation of
+duties, governed decisions, controlled actions, and feedback loops.
 `;
 }

package/src/workbench.mjs

@@ -31,7 +31,7 @@ export const WORKBENCH_TOOLS = [
   },
   {
     name: "airlock_init_repo",
-    description: "Bootstrap a specs repo with AGENTS.md, the Airlock MCP skill, and workspaces/.",
+    description: "Bootstrap a Git-backed specs repo with AGENTS.md, the Airlock MCP skill, and workspaces/.",
     inputSchema: objectSchema({
       path: {
         type: "string",