@reunionstudio/airlock-mcp 0.1.1 → 0.1.3

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,12 +82,18 @@ 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
-   the loop around the process, and proposes a small first spec plus a plan for
-   more.
+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 and asks which delivery mode the user wants:
+   spec-first, app-first from existing specs, or co-development.
+7. For spec-first or co-development, Airlock MCP 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.
+8. For app-first or co-development, Airlock MCP identifies the app goal,
+   available specs, read specs, write specs, runtime, and approved access path.
 
 `init-repo` creates `AGENTS.md`, `.agents/skills/airlock-mcp/SKILL.md`, and
 `workspaces/`. That is what lets Codex understand prompts such as
@@ -98,9 +119,101 @@ 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.
 
+## Build An App From Existing Specs
+
+Use this when the user already has access to specs and wants to build an app,
+dashboard, approval queue, decision UI, analysis workflow, scheduled agent, or
+other code that reads from and submits through Airlock.
+
+Do not bootstrap or edit a specs workspace by default. Work in the app repo
+unless the user asks to change specs. Start by asking for:
+
+- the app goal and decision the app should support
+- the specs the user can access
+- read specs, such as budgets, expenses, requests, forecasts, observations,
+  payouts, or reference data
+- write specs, such as decisions, approvals, comments, commitments, actions, or
+  follow-ups
+- where the app should run, such as Streamlit, web app, CLI, notebook,
+  scheduled agent, or an existing framework
+- the available Airlock/Snowflake access path
+- identity, evidence, timestamp, approval, and separation-of-duties needs
+
+The app should follow the loop:
+
+1. Observe/read governed records through approved Airlock or Snowflake surfaces.
+2. Orient with summaries, comparisons, ranked options, recommendations,
+   exception queues, dashboards, or proposals.
+3. Decide by capturing the human or agent choice with rationale and evidence.
+4. Act/write by submitting the decision, approval, action, comment, or follow-up
+   through an Airlock spec contract.
+
+Keep the boundary explicit: do not write directly to Airlock-owned tables,
+stages, generated views, or generated tables. Do not bypass spec workflow just
+because the app can connect to Snowflake. If no suitable decision or action spec
+exists, explain the gap and propose a small spec-design step.
+
+If the app repo needs local context for coding, seed it with spec snapshots and
+a manifest:
+
+```bash
+airlock-mcp init-app-context . --mode app-first --spec ../home-specs/workspaces/expenses
+```
+
+Use `--mode co-development` when the app and specs will evolve together. Repeat
+`--spec` for each workspace or spec JSON file the app should know about. The
+command creates:
+
+```text
+airlock/
+  AGENTS.md
+  README.md
+  specs.manifest.json
+  spec-snapshots/
+  sample-records/
+  generated/
+    types/
+    sql/
+```
+
+The app repo can import or generate helper code from these snapshots, but the
+snapshots are not canonical. Canonical specs remain in the specs repo or
+installed Airlock. Mark each manifest spec as read, write, or read_write for
+the app before building data access and submission flows.
+
+## Co-Develop Specs And App
+
+Use this when the app surface and the Airlock contracts need to shape each
+other. This is common when a dashboard, queue, approval flow, or agent workflow
+reveals which observations, proposals, decisions, or actions need governed
+records.
+
+Keep two tracks visible:
+
+- Spec track: row grain, columns, samples, attachments, access, validation,
+  workflow, and installed Airlock validation.
+- App track: screens, reads, summaries, ranked options, decision capture,
+  governed writes, runtime, and tests.
+
+Start with the smallest useful contract. The app may expose a thin prototype
+against samples while the spec is being drafted, but live submissions should
+wait for installed Airlock validation and the approved read/write path.
+
 ## Start From Feedback
 
 Use this when the user chooses a shared feedback loop for humans and agents.
@@ -144,6 +257,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 +305,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.3",
   "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.3",
     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.3"

package/src/airlock_mcp/app_context.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .jsonio import read_json, write_json, write_text
+from .specs import extract_spec_config, spec_name
+
+
+APP_CONTEXT_MODES = ("spec-first", "app-first", "co-development")
+
+
+APP_README = """# Airlock App Context
+
+This folder is app-local context for building software that uses Airlock specs.
+
+The canonical specs live in the specs repo or installed Airlock. Files here are
+snapshots, samples, generated helpers, and planning context for app development.
+Refresh them when the canonical spec changes.
+
+Use:
+
+- `specs.manifest.json` to track which specs the app reads from or writes to.
+- `spec-snapshots/` for app-local copies of spec configs.
+- `sample-records/` for app-local sample records used in UI and test fixtures.
+- `generated/types/` for generated application types.
+- `generated/sql/` for reviewed SQL helpers or query templates.
+
+Do not store credentials here. Do not write directly to Airlock-owned tables,
+stages, generated views, or generated tables. Use approved Airlock/Snowflake
+access paths and submit governed decisions or actions through spec contracts.
+"""
+
+
+APP_AGENTS = """# Airlock App Guidance
+
+This repo may contain application code that uses Airlock specs.
+
+## Modes
+
+- Spec-first: design governed specs before building the app surface.
+- App-first: use existing specs to build an app, dashboard, queue, or workflow.
+- Co-development: evolve the app and specs together while keeping the contract
+  explicit.
+
+## App Context
+
+The `airlock/` folder is app-local. Its spec snapshots are references for
+development, not canonical specs. Canonical specs live in the specs repo or
+installed Airlock.
+
+Keep two tracks visible during co-development:
+
+- Spec track: row grain, columns, samples, access, validation, and workflow.
+- App track: screens, reads, decisions, writes, user actions, and runtime.
+
+Use approved Airlock/Snowflake access paths. Do not bypass spec workflow or
+write directly to Airlock-owned tables, stages, generated views, or generated
+tables. If the app needs to submit a decision or action and no suitable write
+spec exists, propose a small spec-design step.
+"""
+
+
+@dataclass(frozen=True)
+class AppContextResult:
+    root: Path
+    mode: str
+    created: tuple[Path, ...]
+    updated: tuple[Path, ...]
+    kept: tuple[Path, ...]
+    specs: tuple[str, ...]
+
+
+def _safe_name(value: str) -> str:
+    cleaned = re.sub(r"[^a-zA-Z0-9_.-]+", "_", value.strip())
+    cleaned = cleaned.strip("._-").lower()
+    return cleaned or "spec"
+
+
+def _write_text_if_needed(path: Path, text: str, *, force: bool) -> str:
+    if path.exists() and not force:
+        return "kept"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    write_text(path, text, force=True)
+    return "created"
+
+
+def _write_json_if_needed(path: Path, value: Any, *, force: bool) -> str:
+    if path.exists() and not force:
+        return "kept"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    write_json(path, value, force=True)
+    return "created"
+
+
+def _load_spec_source(source: Path) -> tuple[dict[str, Any], dict[str, Any] | None]:
+    if source.is_dir():
+        raw_spec = read_json(source / "spec.config.json")
+        if not isinstance(raw_spec, dict):
+            raise ValueError(f"invalid spec workspace: {source}")
+        raw_sample = read_json(source / "sample.records.json")
+        return raw_spec, raw_sample if isinstance(raw_sample, dict) else None
+
+    raw = read_json(source)
+    if raw is None:
+        raise FileNotFoundError(source)
+    return extract_spec_config(raw), None
+
+
+def _manifest(mode: str, entries: list[dict[str, Any]]) -> dict[str, Any]:
+    return {
+        "schema_version": 1,
+        "mode": mode,
+        "canonical_source": "specs repo or installed Airlock",
+        "snapshot_policy": "Snapshots are app-local development references, not canonical specs.",
+        "specs": entries,
+        "tracks": {
+            "spec_track": "row grain, columns, samples, access, validation, workflow",
+            "app_track": "screens, reads, decisions, writes, user actions, runtime",
+        },
+    }
+
+
+def _merge_manifest(existing: Any, new_manifest: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(existing, dict):
+        return new_manifest
+
+    merged = dict(existing)
+    merged.update(
+        {
+            "schema_version": new_manifest["schema_version"],
+            "mode": new_manifest["mode"],
+            "canonical_source": new_manifest["canonical_source"],
+            "snapshot_policy": new_manifest["snapshot_policy"],
+            "tracks": new_manifest["tracks"],
+        }
+    )
+
+    existing_entries = existing.get("specs")
+    by_name: dict[str, dict[str, Any]] = {}
+    if isinstance(existing_entries, list):
+        for entry in existing_entries:
+            if isinstance(entry, dict) and isinstance(entry.get("spec_name"), str):
+                by_name[entry["spec_name"]] = dict(entry)
+
+    for entry in new_manifest["specs"]:
+        previous = by_name.get(entry["spec_name"], {})
+        merged_entry = {**previous, **entry}
+        if previous.get("role") and entry.get("role") == "unknown":
+            merged_entry["role"] = previous["role"]
+        by_name[entry["spec_name"]] = merged_entry
+
+    merged["specs"] = list(by_name.values())
+    return merged
+
+
+def init_app_context(
+    target: Path,
+    *,
+    mode: str = "app-first",
+    spec_sources: list[Path] | None = None,
+    force: bool = False,
+) -> AppContextResult:
+    if mode not in APP_CONTEXT_MODES:
+        raise ValueError(f"mode must be one of: {', '.join(APP_CONTEXT_MODES)}")
+
+    root = target.expanduser().resolve()
+    if root.exists() and not root.is_dir():
+        raise NotADirectoryError(str(root))
+    root.mkdir(parents=True, exist_ok=True)
+
+    airlock_root = root / "airlock"
+    created: list[Path] = []
+    updated: list[Path] = []
+    kept: list[Path] = []
+
+    for directory in (
+        airlock_root,
+        airlock_root / "spec-snapshots",
+        airlock_root / "sample-records",
+        airlock_root / "generated",
+        airlock_root / "generated" / "types",
+        airlock_root / "generated" / "sql",
+    ):
+        if directory.exists():
+            kept.append(directory)
+        else:
+            directory.mkdir(parents=True)
+            created.append(directory)
+
+    entries: list[dict[str, Any]] = []
+    spec_names: list[str] = []
+    for source in spec_sources or []:
+        spec_config, sample_records = _load_spec_source(source.expanduser())
+        name = spec_name(spec_config)
+        safe = _safe_name(name)
+        snapshot_path = airlock_root / "spec-snapshots" / f"{safe}.spec.config.json"
+        bucket = created if _write_json_if_needed(snapshot_path, spec_config, force=force) == "created" else kept
+        bucket.append(snapshot_path)
+
+        sample_relative: str | None = None
+        if sample_records is not None:
+            sample_path = airlock_root / "sample-records" / f"{safe}.sample.records.json"
+            bucket = created if _write_json_if_needed(sample_path, sample_records, force=force) == "created" else kept
+            bucket.append(sample_path)
+            sample_relative = str(sample_path.relative_to(root))
+
+        core = spec_config.get("core_config")
+        core = core if isinstance(core, dict) else {}
+        entries.append(
+            {
+                "spec_name": name,
+                "spec_alias": core.get("spec_alias"),
+                "source": str(source),
+                "snapshot": str(snapshot_path.relative_to(root)),
+                "sample_records": sample_relative,
+                "role": "unknown",
+                "snapshot_only": True,
+            }
+        )
+        spec_names.append(name)
+
+    for path, content in (
+        (airlock_root / "README.md", APP_README),
+        (airlock_root / "AGENTS.md", APP_AGENTS),
+        (airlock_root / "generated" / "types" / ".gitkeep", ""),
+        (airlock_root / "generated" / "sql" / ".gitkeep", ""),
+    ):
+        bucket = created if _write_text_if_needed(path, content, force=force) == "created" else kept
+        bucket.append(path)
+
+    manifest_path = airlock_root / "specs.manifest.json"
+    manifest = _manifest(mode, entries)
+    if manifest_path.exists() and not force:
+        write_json(manifest_path, _merge_manifest(read_json(manifest_path), manifest), force=True)
+        updated.append(manifest_path)
+    else:
+        bucket = created if _write_json_if_needed(manifest_path, manifest, force=force) == "created" else kept
+        bucket.append(manifest_path)
+
+    return AppContextResult(
+        root=airlock_root,
+        mode=mode,
+        created=tuple(created),
+        updated=tuple(updated),
+        kept=tuple(kept),
+        specs=tuple(spec_names),
+    )
+
+
+def format_app_context_result(result: AppContextResult) -> str:
+    lines = [f"initialized app context {result.root}", f"mode: {result.mode}"]
+    for path in result.created:
+        lines.append(f"created {path.relative_to(result.root.parent)}")
+    for path in result.updated:
+        lines.append(f"updated {path.relative_to(result.root.parent)}")
+    for path in result.kept:
+        lines.append(f"kept {path.relative_to(result.root.parent)}")
+    lines.append("seeded_specs: " + (", ".join(result.specs) if result.specs else "none"))
+    lines.extend(
+        [
+            "",
+            "next:",
+            "1. Treat spec snapshots as app-local references, not canonical specs.",
+            "2. Mark each manifest spec as read, write, or read_write for the app.",
+            "3. Build app reads and governed submissions through approved Airlock/Snowflake access paths.",
+        ]
+    )
+    return "\n".join(lines)

package/src/airlock_mcp/art.py

@@ -21,6 +21,6 @@ def about_text() -> str:
     return f"""{MCP_MARK.rstrip()}
 
 version: {__version__}
-commands: init-repo, init, import-spec, clone, rename, archive, restore, list-workspaces, summary, next, check, export-csv, render-sql, self-update
+commands: init-repo, init-app-context, init, import-spec, clone, rename, archive, restore, list-workspaces, summary, next, check, export-csv, render-sql, self-update
 principle: Codex is the conversation; files are memory; Airlock is authority.
 """

package/src/airlock_mcp/bootstrap.py

@@ -16,8 +16,9 @@ This repo is an Airlock MCP workspace for drafting Airlock specs with Codex.
 The public install surface is Airlock MCP, for example
 `npx @reunionstudio/airlock-mcp install`. Airlock MCP is the single installed
 interface for building specs, using specs, pulling and pushing governed data,
-and discovering improvements from real use cases. This project repo remains
-the durable memory for the specs being drafted.
+building apps or workflows that use existing specs, and discovering
+improvements from real use cases. This project repo remains the durable memory
+for the specs being drafted.
 
 ## Repo Naming
 
@@ -29,6 +30,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
@@ -38,7 +46,13 @@ installed Airlock app.
 ## Starting A Spec Project
 
 After bootstrap, welcome the user and orient before creating a workspace. Start
-with:
+by asking which delivery mode they want:
+
+1. Spec-first: design governed specs before building the app surface.
+2. App-first: build from existing specs.
+3. Co-development: develop the app and specs together.
+
+For spec-first or co-development work, ask:
 
 What process do you want to improve?
 
@@ -55,15 +69,65 @@ 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
 asks for the posts pattern.
 
+## Building Apps With Existing Specs
+
+Use this path when the user wants to build an app, dashboard, approval queue,
+decision UI, analysis workflow, scheduled agent, or other code that uses specs
+they already have access to. Treat this as app/workflow implementation, not
+spec editing, unless the user explicitly asks to change specs.
+
+Use `airlock-mcp init-app-context` in an app repo when the app needs local
+Airlock context. It creates `airlock/specs.manifest.json`,
+`airlock/spec-snapshots/`, `airlock/sample-records/`, and generated helper
+folders. These files are app-local references, not canonical specs. Canonical
+specs live in the specs repo or installed Airlock.
+
+Identify:
+
+- the app goal and decision the app should support
+- read specs such as budgets, expenses, requests, forecasts, observations,
+  payouts, or reference data
+- write specs such as decisions, approvals, comments, commitments, actions, or
+  follow-ups
+- where the app should run, such as Streamlit, web app, CLI, notebook,
+  scheduled agent, or existing app framework
+- the Airlock access path available in this environment
+- identity, evidence, timestamp, approval, and separation-of-duties rules
+
+The app may orient the user with summaries, comparisons, rankings, exception
+queues, proposals, or dashboards. It should submit governed choices back
+through an Airlock spec contract. Do not write directly to Airlock-owned tables,
+stages, generated views, or generated tables. Do not bypass spec workflow just
+because the app can connect to Snowflake. If no suitable decision or action spec
+exists, explain the gap and propose a small spec-design step.
+
+In co-development mode, keep two tracks visible:
+
+- Spec track: row grain, columns, samples, access, validation, workflow
+- App track: screens, reads, decisions, writes, user actions, runtime
+
 ## Working Style
 
 - Use the repo-scoped `$airlock-mcp` skill for spec drafting, review, and
-  pattern selection.
+  pattern selection, or for app/workflow implementation that uses existing
+  Airlock specs.
 - Keep drafts small and concrete. Prefer one useful governed output over a
   large speculative process map, then keep a plan for later specs.
 - Preserve decisions in workspace files so future Codex sessions can resume
@@ -91,6 +155,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 +235,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)