@reunionstudio/airlock-mcp 0.1.1 → 0.1.3

package/src/airlock_mcp/cli.py

@@ -5,6 +5,7 @@ import sys
 from pathlib import Path
 
 from . import __version__
+from .app_context import APP_CONTEXT_MODES, format_app_context_result, init_app_context
 from .art import about_text
 from .bootstrap import bootstrap_repo, format_bootstrap_result
 from .jsonio import read_json
@@ -64,6 +65,17 @@ def init_repo(args: argparse.Namespace) -> int:
     return 0
 
 
+def init_app(args: argparse.Namespace) -> int:
+    result = init_app_context(
+        Path(args.path),
+        mode=args.mode,
+        spec_sources=[Path(source) for source in args.spec],
+        force=args.force,
+    )
+    print(format_app_context_result(result))
+    return 0
+
+
 def init_workspace(args: argparse.Namespace) -> int:
     patterns = load_patterns(repo_root())
     pattern = patterns[args.pattern]
@@ -303,11 +315,31 @@ 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)
 
+    init_app_parser = subparsers.add_parser(
+        "init-app-context",
+        help="Prepare an app repo airlock/ context with spec snapshots and a manifest.",
+    )
+    init_app_parser.add_argument("path", nargs="?", default=".", help="App repo path. Defaults to current directory.")
+    init_app_parser.add_argument(
+        "--mode",
+        choices=APP_CONTEXT_MODES,
+        default="app-first",
+        help="Development mode. Defaults to app-first.",
+    )
+    init_app_parser.add_argument(
+        "--spec",
+        action="append",
+        default=[],
+        help="Spec workspace directory or spec JSON file to snapshot. Repeat for multiple specs.",
+    )
+    init_app_parser.add_argument("--force", action="store_true", help="Overwrite app context files.")
+    init_app_parser.set_defaults(func=init_app)
+
     init_parser = subparsers.add_parser("init", help="Create a spec workspace.")
     init_parser.add_argument("name", help="Workspace folder name.")
     init_parser.add_argument(

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

@@ -7,7 +7,7 @@ const GETTING_STARTED_URI = "airlock://getting-started";
 
 const START_TOOL = {
   name: "airlock_start",
-  description: "Return Airlock MCP setup guidance for building and using Airlock specs.",
+  description: "Return Airlock MCP setup guidance for specs and apps that use specs.",
   inputSchema: {
     type: "object",
     properties: {
@@ -44,10 +44,10 @@ export function handleMcpRequest(message) {
       },
       serverInfo: {
         name: "airlock",
-        version: "0.1.1",
+        version: "0.1.3",
       },
       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.",
+        "Airlock MCP helps agents improve processes with Airlock specs and build apps or workflows that use existing specs. Use airlock_start for orientation or the airlock_* tools to bootstrap, draft, check, summarize, export, and render specs.",
     });
   }
 
@@ -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 or choose an Airlock app/spec 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 specs or apps that use Airlock specs.",
       messages: [
         {
           role: "user",

package/src/text.mjs

@@ -21,23 +21,52 @@ 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,
-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.`;
+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. If I am in an app repo and want to build software that
+uses existing specs, or develop the app and specs together, do not bootstrap a
+specs repo unless I ask for spec edits.
+
+Welcome me by asking whether I want spec-first, app-first, or co-development:
+spec-first designs governed specs before the app, app-first builds from existing
+specs, and co-development evolves the app and specs together. For spec-first or
+co-development, ask 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.
+
+If I want app-first or co-development, ask for the app goal, the specs I can
+access, which specs are read sources, which spec records decisions or actions,
+and where the app should run. Offer to run \`airlock-mcp init-app-context\` in
+the app repo to seed \`airlock/specs.manifest.json\`, spec snapshots, sample
+records, and generated helper folders. Help code the app using approved
+Airlock/Snowflake access paths. Do not write directly to Airlock-owned tables
+or bypass spec workflow.`;
 }
 
 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")
@@ -46,11 +75,16 @@ ${airlockPrompt(project)
 
 Airlock MCP will offer:
   - process discovery before choosing a spec pattern
+  - spec-first, app-first, and co-development planning
   - spec design with the bundled workbench
   - Airlock operating patterns for OODA loops and separation of duties
+  - app context seeding with spec snapshots and manifests
+  - app and workflow coding against existing Airlock specs
   - observe specs for controlled interface ingestion
   - orient specs for proposals, context, scoring, or exception queues
-  - decision specs and action specs for governed follow-through`;
+  - 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) {
@@ -58,26 +92,37 @@ export function gettingStartedText(project) {
 
 Airlock MCP is the single installed interface for AI agents working with
 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.
+specs, using specs for governed data movement, planning OODA loops, and building
+apps or workflows that read from and submit through existing specs.
 
-Airlock MCP gives agents two kinds of Airlock expertise:
+Airlock MCP gives agents three kinds of Airlock help:
 
 1. Spec design: draft, check, revise, import, clone, and prepare specs for
    installed Airlock validation.
 2. Airlock operating patterns: use specs to organize observations, orientation,
    governed decisions, controlled actions, separation of duties, and feedback
    loops.
+3. App and workflow implementation: build dashboards, queues, decision UIs,
+   analyses, and agent workflows that use existing specs without bypassing
+   Airlock contracts.
 
-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)}
 
-First ask: What process do you want to improve?
+First ask which delivery mode the user wants:
+
+1. Spec-first: design governed specs before building the app surface.
+2. App-first: build an app or workflow from existing specs.
+3. Co-development: develop the app and specs together.
+
+For spec-first and co-development work, ask: What process do you want to improve?
 
 Airlock works best when we can identify the loop around a process:
 
@@ -91,8 +136,26 @@ 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.`;
+into a small first Airlock spec and a plan for more.
+
+For app-first and co-development work, give Codex the app goal and available
+specs. Airlock MCP should identify read specs, write specs, orienting views,
+decision capture, and safe Airlock/Snowflake access paths. It can seed an app
+repo with \`airlock/specs.manifest.json\`, spec snapshots, sample records, and
+generated helper folders. The app should submit decisions, approvals, actions,
+comments, or follow-ups through Airlock spec contracts, not direct table writes.
+In co-development mode, keep the spec track and app track visible side by side.`;
 }
 
 export function helpText() {
@@ -117,5 +180,7 @@ Airlock MCP is the single installed interface for agents working with Airlock.
 Spec building is bundled inside that experience.
 Airlock operating patterns help connect specs into OODA loops, separation of
 duties, governed decisions, controlled actions, and feedback loops.
+Airlock MCP can also help build apps and workflows that use existing specs for
+approved reads and governed submissions.
 `;
 }

package/src/workbench.mjs

@@ -23,6 +23,8 @@ const workspaceProperty = {
   maxLength: MAX_ARG_LENGTH,
 };
 
+const appModeValues = ["spec-first", "app-first", "co-development"];
+
 export const WORKBENCH_TOOLS = [
   {
     name: "airlock_doctor",
@@ -31,7 +33,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",
@@ -42,6 +44,32 @@ export const WORKBENCH_TOOLS = [
       cwd: cwdProperty,
     }),
   },
+  {
+    name: "airlock_init_app_context",
+    description: "Seed an app repo with airlock/ spec snapshots, samples, generated placeholders, and a manifest.",
+    inputSchema: objectSchema({
+      path: {
+        type: "string",
+        description: "App repo path to initialize. Defaults to the current directory.",
+        maxLength: MAX_ARG_LENGTH,
+      },
+      mode: {
+        type: "string",
+        enum: appModeValues,
+        description: "Development mode. Defaults to app-first.",
+      },
+      specs: {
+        type: "array",
+        items: {
+          type: "string",
+          maxLength: MAX_ARG_LENGTH,
+        },
+        description: "Spec workspace directories or spec JSON files to snapshot.",
+      },
+      force: forceProperty,
+      cwd: cwdProperty,
+    }),
+  },
   {
     name: "airlock_list_patterns",
     description: "List bundled Airlock spec starter patterns.",
@@ -230,6 +258,28 @@ function optionalEnum(args, name, allowed, fallback) {
   return value;
 }
 
+function optionalStringArray(args, name) {
+  const value = args?.[name];
+  if (value === undefined || value === null) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${name} must be an array`);
+  }
+  return value.map((entry, index) => {
+    if (typeof entry !== "string") {
+      throw new Error(`${name}[${index}] must be a string`);
+    }
+    if (entry.length > MAX_ARG_LENGTH || /[\u0000-\u001f\u007f]/.test(entry)) {
+      throw new Error(`${name}[${index}] must be ${MAX_ARG_LENGTH} characters or fewer with no control characters`);
+    }
+    if (entry.startsWith("-")) {
+      throw new Error(`${name}[${index}] must not start with '-'`);
+    }
+    return entry;
+  });
+}
+
 function requiredEnum(args, name, allowed) {
   const value = optionalEnum(args, name, allowed, undefined);
   if (value === undefined) {
@@ -264,6 +314,19 @@ function cliArgsForTool(name, args = {}) {
       if (force) cliArgs.push("--force");
       return { cwd, cliArgs };
     }
+    case "airlock_init_app_context": {
+      const cliArgs = [
+        "init-app-context",
+        optionalString(args, "path", "."),
+        "--mode",
+        optionalEnum(args, "mode", appModeValues, "app-first"),
+      ];
+      for (const spec of optionalStringArray(args, "specs")) {
+        cliArgs.push("--spec", spec);
+      }
+      if (force) cliArgs.push("--force");
+      return { cwd, cliArgs };
+    }
     case "airlock_list_patterns":
       return { cwd, cliArgs: ["list-patterns"] };
     case "airlock_show_pattern": {