@reunionstudio/airlock-mcp 0.1.1 → 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.
@@ -40,6 +46,16 @@ the deterministic checker.
    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.
@@ -48,6 +64,9 @@ the deterministic checker.
    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.
@@ -59,6 +78,10 @@ the deterministic checker.
    `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
@@ -105,6 +128,25 @@ 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:

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, identify the loop around it, draft a small first Airlock spec, and keep a plan for more specs."
+  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

@@ -52,6 +52,11 @@ 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
 validating specs, loading records, handling attachments, reading outputs, and
@@ -84,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.
@@ -117,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 improve a process with Airlock specs.
-5. Let Airlock MCP bootstrap the project, ask what process the user wants to
+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 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

@@ -45,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,
-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.
+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,10 +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 start by asking what process the user
-wants to improve, then help design specs and operating patterns around observe,
-orient, decide, and act.
+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.
@@ -107,8 +109,13 @@ packaging pressure appears.
 The first release should optimize the user journey:
 
 1. install connector
-2. create blank `<project>-specs` Codex project
-3. ask what process the user wants to improve
-4. map where information comes in and actions go out
-5. create the first workspace only after the user chooses a small first spec
-6. keep a plan for later specs that improve the full loop
+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

@@ -8,6 +8,16 @@ 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 interfaces, evidence, and signals that matter:
@@ -15,6 +25,7 @@ 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

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,13 +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. 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 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.
+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,
@@ -53,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:
 
@@ -67,10 +82,12 @@ 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 improve a process with specs.`
-5. Airlock MCP welcomes, asks what process the user wants to improve, explains
+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.
 
@@ -98,6 +115,18 @@ 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.
 
@@ -144,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
@@ -187,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.1",
+  "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.1",
+    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.1"
+__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
@@ -55,6 +62,18 @@ 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.
+
+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.
+
 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
@@ -91,6 +110,9 @@ Resolve these before final JSON:
 - 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
 
@@ -168,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. Start with: What process do you want to improve?",
+            "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/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,7 +44,7 @@ export function handleMcpRequest(message) {
       },
       serverInfo: {
         name: "airlock",
-        version: "0.1.1",
+        version: "0.1.2",
       },
       instructions:
         "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,23 +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. 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,
+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 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.`;
+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")
@@ -50,7 +67,9 @@ Airlock MCP will offer:
   - 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`;
+  - 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) {
@@ -69,11 +88,13 @@ Airlock MCP gives agents two kinds of Airlock expertise:
    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)}
 
@@ -91,6 +112,16 @@ 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.`;
 }

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",