aw-spec-cli 0.1.26 → 0.1.28

package/assets/.appweaver/scripts/python/aw-stack.py

@@ -2,42 +2,66 @@
 """
 aw-stack — the lane model's deterministic core.
 
-Backs seven aw-spec-actions subcommands, called identically by the bash and the
+Backs ten aw-spec-actions subcommands, called identically by the bash and the
 powershell twin so the two stay in parity by construction rather than by review:
 
     list      enumerate .appweaver/stack-profiles/ — the candidate list
     detect    match the repo's own files against those profiles — the BROWNFIELD
               candidate list, since an existing repo already answered the question
-    declare   upsert a lane into .appweaver/stacks.json — THE SOLE WRITER
+    declare   upsert a lane into .appweaver/stacks.json — the writer of WHOLE lanes
+    set       change named keys on a lane already declared — the writer of SETTINGS
     resolve   read .appweaver/stacks.json — for every downstream reader; with
               --feature-dir, narrowed to the lanes that feature has a surface in
     verify    is the declaration USABLE for the phase about to run — the gate
     run-phase run a phase's command for EVERY declared lane, not just the first
     probe     is there evidence of a lane of this kind — read-only, never fatal
-
-`declare` is the sole writer and has exactly one caller — `select-stack`, where a
-person picks — so the rule is a grep rather than a convention. The `origin` key
-stays optional in the schema for a future caller that proposes a lane without a
+    contract-export  start the service lane, fetch its API document, stop it
+    contract-check   the operation ids a frontend plan cites vs that document
+
+This file is the only code that writes stacks.json, through two subcommands with
+different jobs. `declare` creates or replaces a whole lane and has exactly one caller —
+`select-stack`, where a person picks. `set` changes only the keys in CONTRACT_KEYS on a lane that is
+already there, and never its root, profile or phase commands: `foundation` records the
+API-export settings the pack it unpacked carries, and `implement` records the client
+command a developer supplies. Re-declaring a lane to change one key would reset every
+other command to the profile's default, which is why the two are separate. The `origin`
+key stays optional in the schema for a future caller that proposes a lane without a
 person in the loop; a reader that branches on it keeps working either way.
 
+THE API CONTRACT BETWEEN THE LANES. The service lane publishes an API document and the
+frontend lane generates its client from it. Three lane keys carry that, each read from
+the lane first and from its stack profile when the lane does not set it, so a lane
+declared before the keys existed answers them too:
+
+    contract_run  (backend)  the command that starts the service for the export
+    contract      (backend)  the URL the running service serves its document at
+    client        (frontend) the command that generates the client; `{{contract}}` in
+                             it is the exported document, as seen from where it runs
+
+The document is written to CONTRACT_DOC under the service lane root folder, so it is
+committed with the service that publishes it.
+
 A person editing stacks.json in a text editor is the other way a lane arrives,
-and it is supported: the kit ships the file holding `{"lanes": []}` for exactly
-that. It is the one path that does not pass the writer's checks, which is why
+and it is supported: the kit ships the file with an empty `lanes` array for exactly
+that, plus a `_lane_format` key holding one sample lane of each kind with every field
+filled in. Nothing reads `_lane_format`; it is there to copy from. It is the one path that does not pass the writer's checks, which is why
 `verify` re-checks the roots-disjoint invariant rather than trusting that
 `declare` already did. `resolve` can never write, which is why these are two
 subcommands and not one with a mode flag.
 
-A lane's `root` IS its source path — the subtree the lane owns and the only place
+A lane's `root` IS the lane root folder — the subtree the lane owns and the only place
 its implement phase may write. The two words name one field, and `--source-path`
 is accepted wherever `--root` is.
 
-WHERE THE COMMANDS RUN is a separate question, because for most stacks the answer
-is a different directory: `dotnet build` wants the solution file at the top while
-the lane owns `src/`, and `npm run build` wants the package.json at the top while
-the lane owns `web/`. `run_from` carries that answer — "repo" (the default, and
-the shape of every lane written before the key existed) or "root". A stack whose
-manifest lives INSIDE its subtree needs "root" and cannot work without it: a Maven
-wrapper at backend/<app>/mvnw is unreachable from the repository root.
+WHERE THE COMMANDS RUN is a separate question, because the answer can be a different
+directory: a classic .NET repository keeps its solution file at the top while the
+lane owns `src/`. `run_from` carries that answer — "repo" (the default, and the shape
+of every lane written before the key existed) or "root". A stack whose build file
+lives INSIDE its subtree needs "root" and cannot work without it: a Maven wrapper at
+backend/<app>/mvnw is unreachable from the repository root. A NEW project is one
+self-contained folder per lane — every profile defaults to `backend/` or `frontend/`
+with `run_from: "root"` — while `declare` answers for code that already exists from
+where its build file actually sits (see `build_files_at`).
 
 WHERE THE PATH IS CHECKED AGAINST THE DISK. `declare` records a path; it does not
 require the path to exist, because in a greenfield project it does not exist yet —
@@ -61,6 +85,14 @@ import sys
 STACKS_REL = ".appweaver/stacks.json"
 PROFILES_REL = ".appweaver/stack-profiles"
 
+# Where the exported API document lands, relative to the service lane root folder.
+CONTRACT_DOC = "contracts/openapi.json"
+
+# The API-contract keys: the only ones `set` may change, and the ones read from the
+# stack profile when the lane does not set them (lane_value). Everything else on a lane
+# is the declaration itself and changes only through `declare`.
+CONTRACT_KEYS = ("contract_run", "contract", "client")
+
 # A lane id names the ROLE in the project; the profile names the technology.
 # Keeping them separate is what lets a project re-stack a lane without renaming
 # the paths, rules and constitution half that hang off the lane id.
@@ -270,6 +302,11 @@ def detect_profiles(repo, kind=None, exclude_roots=()):
         files_for_prof = scoped if prof.get("kind") != "frontend" else files
         evidence, matched, anchored_hits = [], 0, 0
         prof_root = norm_root(prof.get("root") or "")
+        # The `detect` patterns are written against the layout an EXISTING repository of
+        # this stack usually has (`src/**/*.csproj`, `web/next.config.*`), which is the
+        # profile's `conventional_root` — not its `root`, the folder a NEW project gets.
+        conv_root = norm_root(prof.get("conventional_root") or "")
+        bases = [b for b in (prof_root, conv_root) if b and b != REPO_ROOT]
         for pat in patterns:
             rx = _glob_rx(pat)
             rx_any = _glob_rx("**/" + pat)
@@ -278,8 +315,8 @@ def detect_profiles(repo, kind=None, exclude_roots=()):
                 anchored_hits += 1
             else:
                 hits = [f for f in files_for_prof if rx_any.match(f)]
-            if not hits and prof_root and pat.startswith(prof_root) \
-                    and os.path.basename(pat) not in ambiguous:
+            base = next((b for b in bases if pat.startswith(b)), "")
+            if not hits and base and os.path.basename(pat) not in ambiguous:
                 # RELOCATED, with the profile's own root segment substituted rather than
                 # prefixed. Prefixing alone only ever finds the profile's own folder name
                 # deeper in the tree — `apps/portal/web/angular.json` — so a UI in
@@ -288,7 +325,7 @@ def detect_profiles(repo, kind=None, exclude_roots=()):
                 # Restricted to names only one kind claims, so substitution widens where a
                 # stack may live without widening what counts as evidence for it.
                 hits = [f for f in files_for_prof
-                        if _glob_rx("**/" + pat[len(prof_root):]).match(f)]
+                        if _glob_rx("**/" + pat[len(base):]).match(f)]
             if not hits:
                 continue
             matched += 1
@@ -298,20 +335,21 @@ def detect_profiles(repo, kind=None, exclude_roots=()):
         dirs = sorted({os.path.dirname(f) for f in evidence}, key=lambda d: (d.count("/"), len(d)))
         # WHERE THE SOURCE LIVES, which is not always where the evidence sits. A manifest
         # at the repo root — `App.sln`, a workspace `package.json` — marks the repository,
-        # not the subtree: the code it describes is under the profile's own root. So repo-
-        # root evidence defers to that root when the directory is really there, and only
+        # not the subtree: the code it describes is under one of the profile's roots. So
+        # repo-root evidence defers to that root when the directory is really there, and only
         # falls back to the repo root itself when it is not, which is the case for the
         # single-package layouts (`create-next-app`, a UI checked out at the top level)
-        # whose files genuinely are at the top.
+        # whose files genuinely are at the top. The conventional root is tried first:
+        # repo-root evidence (`App.sln`) is the classic layout, whose code sits under
+        # `src/` — not under the `backend/` a new project would get.
         prof_default = norm_root(prof.get("root") or "")
         if not dirs:
             root = prof_default
         elif dirs[0]:
             root = norm_root(dirs[0])
-        elif prof_default and os.path.isdir(os.path.join(repo, prof_default)):
-            root = prof_default
         else:
-            root = REPO_ROOT
+            root = next((r for r in (conv_root, prof_default)
+                         if r and os.path.isdir(os.path.join(repo, r))), REPO_ROOT)
         out.append({
             "id": prof["id"],
             "kind": prof.get("kind", ""),
@@ -404,7 +442,7 @@ def cmd_list(args):
     repository looks like. Two subcommands would walk the file tree twice and add
     two steps to a workflow whose whole value is being short. One call returns the
     options, the profile the files point at, and the directory the evidence sits
-    in — which is the source path the operator is about to be asked to confirm.
+    in — which is the lane root folder the operator is about to be asked to confirm.
 
     HOW A DETECTED STACK IS PROPOSED, and why it is not preselected. Detection
     moves its match to the FRONT of the option list; it never fills `preselect`.
@@ -448,10 +486,10 @@ def cmd_list(args):
     preselect = resolve_preselect(args.preselect, profiles, args.include_none, args.kind)
     preselect_source = "argument" if preselect else ""
 
-    # Candidate SOURCE PATHS for the follow-up question, best first. Labelled with why
+    # Candidate LANE ROOT FOLDERS for the follow-up question, best first. Labelled with why
     # each is offered, because the operator picking from this list is choosing the
     # subtree a generator will be allowed to write into. Free text is always
-    # accepted — a repo that matches no profile still has a source path.
+    # accepted — a repo that matches no profile still has a lane root folder.
     #
     # WITH --profile the stack is already chosen, and the list answers for it alone:
     # where THAT stack's evidence sits, then its own default, then where another
@@ -460,7 +498,7 @@ def cmd_list(args):
     # operator did not choose.
     #
     # WITHOUT --profile the list is built before any choice, and a default root is
-    # usually shared (six frontend profiles default to web/), so its label names every
+    # usually shared (every frontend profile defaults to frontend/), so its label names every
     # profile that proposes it rather than whichever one sorts first.
     chosen = None
     if args.profile:
@@ -541,16 +579,16 @@ def strip_root_label(value):
     return (value or "").split(ROOT_LABEL_SEP, 1)[0].strip()
 
 
-# The repository root as a source path. A single-module project — a Maven, Cargo, Go
+# The repository root as a lane root folder. A single-module project — a Maven, Cargo, Go
 # or Node repo whose manifest sits at the top — has no subdirectory to name, and the
-# empty string cannot carry it: `verify` reads an empty root as "no source path
+# empty string cannot carry it: `verify` reads an empty root as "no lane root folder
 # declared". "./" is the one spelling that survives being normalised twice, which is
 # what makes it usable as a STORED value rather than only as typed input.
 REPO_ROOT = "./"
 
 
 def norm_root(root):
-    """Canonicalise a source path, IDEMPOTENTLY.
+    """Canonicalise a lane root folder, IDEMPOTENTLY.
 
     Idempotence is a correctness requirement, not tidiness: `declare` normalises what it
     writes and `verify` normalises what it reads, so a value that changes on the second
@@ -575,7 +613,7 @@ def norm_root(root):
 
 
 def root_on_disk(repo, root):
-    """Does the lane's source path exist as a directory?
+    """Does the lane root folder exist as a directory?
 
     Reported everywhere a root is reported and enforced only by `verify`. A false
     here is an ordinary state before any code is written and a hard error once a
@@ -588,14 +626,15 @@ def root_on_disk(repo, root):
 def lane_workdir(repo, lane):
     """The directory a lane's commands run in.
 
-    `run_from: "root"` runs them in the lane's own source path; anything else — including
+    `run_from: "root"` runs them in the lane root folder; anything else — including
     the key being ABSENT, which is the shape of every lane written before this key
-    existed — runs them at the repository root. That default is not laziness: a .NET
-    solution file, a go.mod or a package.json at the top is what `dotnet build`,
-    `go build ./...` and `npm run build` need to find, and those profiles declare a `root`
-    that is their SOURCE directory rather than their build directory. The two coincide for
-    a stack whose manifest lives inside the subtree — a Maven wrapper at
-    backend/orderservice/mvnw cannot be reached from the repo root at all.
+    existed — runs them at the repository root. That default is not laziness: in a
+    classic repository a .NET solution file, a go.mod or a package.json at the top is what
+    `dotnet build`, `go build ./...` and `npm run build` need to find, while the lane is
+    the SOURCE directory under it. The two coincide for a stack whose build file lives
+    inside the subtree — a Maven wrapper at backend/orderservice/mvnw cannot be reached
+    from the repo root at all — and for every new project, which is one self-contained
+    folder per lane.
 
     Falls back to the repo root when the declared root is not on disk, so the phase
     reports the command's own failure instead of a chdir error.
@@ -608,30 +647,148 @@ def lane_workdir(repo, lane):
     return repo
 
 
-def lane_command(lane, phase):
-    """The command for one phase, with `{{root}}` standing for the lane's root.
+def build_files_at(repo, root, build_files):
+    """Where a stack's build file already sits for a lane at `root`: "root" when one is
+    directly inside the lane root folder, "repo" when one is only at the repository root,
+    "" when neither — nothing is on disk yet, so the caller falls back to the profile.
+
+    This is what lets one profile serve both kinds of repository. A new project is one
+    self-contained folder per lane (`backend/api.sln`), and its commands run inside it; a
+    classic .NET repository keeps `api.sln` at the top with the code under `src/`, and its
+    commands have to run at the top. Reading the answer off the disk at declare time gives
+    each its own, where a fixed profile default would break one of them.
+    """
+    if not build_files:
+        return ""
+    r = norm_root(root)
+    lane_dir = repo if (not r or r == REPO_ROOT) else os.path.join(repo, r.rstrip("/"))
+
+    def has(d):
+        return any(os.path.isfile(p) for pat in build_files
+                   for p in glob.glob(os.path.join(d, pat)))
+
+    if os.path.isdir(lane_dir) and has(lane_dir):
+        return "root"
+    if has(repo):
+        return "repo"
+    return ""
+
+
+# Folders a runnable project is never looked for in: build output, dependencies, tests.
+HOST_SKIP_DIRS = {"bin", "obj", "node_modules", ".git", ".vs", "packages", "tests", "test"}
+
 
-    A profile command sometimes has to NAME the source path — `dotnet run --project
-    src/`, `python -m compileall app`. Written literally, that is the profile's
-    default root frozen into the command, and it stays frozen when the lane declares
-    a different one: a service at `Services/Api/` runs the project at `src/`, or
-    fails looking for it. The placeholder lets the profile say "the root this lane
-    declares" and be right on every layout.
+def lane_host(repo, lane):
+    """The lane's runnable project folder, which `{{host}}` in a command stands for.
+
+    A lane root folder often holds several projects and only one of them is the thing to
+    run — a .NET solution's Aspire AppHost, or its API when there is no AppHost. The
+    profile's `host_patterns` say where that project sits, best first, as paths relative
+    to the lane root folder (`**/` for any depth, case ignored). The first pattern that
+    matches exactly ONE file names the project; its folder is returned as seen from where
+    the lane's commands run. None when the profile has no patterns, the lane root folder is
+    not on disk, or no pattern has a single match — the caller then uses the lane root folder.
+    """
+    if not repo:
+        return None
+    patterns = [p.lower() for p in profile_of(repo, lane).get("host_patterns") or []]
+    r = norm_root(lane.get("root"))
+    lane_dir = repo if (not r or r == REPO_ROOT) else os.path.join(repo, r.rstrip("/"))
+    if not patterns or not os.path.isdir(lane_dir):
+        return None
+    leaves = {p.rsplit("/", 1)[-1] for p in patterns}
+    files = []
+    for dirpath, dirnames, filenames in os.walk(lane_dir):
+        dirnames[:] = [d for d in dirnames if d.lower() not in HOST_SKIP_DIRS]
+        for name in filenames:
+            if any(fnmatch.fnmatchcase(name.lower(), leaf) for leaf in leaves):
+                rel = os.path.relpath(os.path.join(dirpath, name), lane_dir).replace("\\", "/")
+                files.append(rel)
+    for pat in patterns:
+        bare = pat[3:] if pat.startswith("**/") else pat
+        hits = [f for f in files
+                if fnmatch.fnmatchcase(f.lower(), pat) or fnmatch.fnmatchcase(f.lower(), bare)]
+        if len(hits) == 1:
+            project_dir = os.path.join(lane_dir, os.path.dirname(hits[0]))
+            rel = os.path.relpath(project_dir, lane_workdir(repo, lane)).replace("\\", "/")
+            return rel
+    return None
+
+
+def lane_command(lane, phase, repo=None):
+    """The command for one phase, with `{{root}}` standing for the lane root folder and
+    `{{host}}` for the lane's runnable project inside it (see lane_host).
+
+    A profile command sometimes has to NAME the lane root folder — `python -m
+    compileall app`. Written literally, that is the profile's default root frozen into
+    the command, and it stays frozen when the lane declares a different one: a service
+    at `Services/Api/` compiles the code at `app/`, or fails looking for it. The
+    placeholder lets the profile say "the root this lane declares" and be right on
+    every layout.
 
     Expanded at RUN time, not at declare time, so editing `root` in stacks.json by
     hand keeps the command consistent with it. A command with no placeholder is
     returned untouched, so every literal command already on disk is unaffected.
+
+    The root is named as seen from where the command RUNS: a `run_from: "root"` lane
+    runs inside its root, so there `{{root}}` is `.` — the repository-relative path
+    would point at `backend/backend`.
+
+    `{{host}}` exists because the lane root folder is not always runnable: `dotnet run
+    --project <folder>` needs exactly one project in that folder, and a solution has
+    several. It is looked up when the command is read, so a project scaffolded after the
+    lane was declared is found; with no single match it falls back to `{{root}}`.
+
+    `{{contract}}` is the service lane's exported API document (contract_doc), named as
+    seen from where THIS lane's command runs — what a frontend lane's `client` command
+    generates from. With no service lane it is left as written.
     """
-    cmd = (lane.get(phase) or "").strip()
+    if phase in CONTRACT_KEYS:
+        cmd = lane_value(repo, lane, phase)
+    else:
+        cmd = (lane.get(phase) or "").strip()
+    if "{{contract}}" in cmd and repo:
+        doc = contract_doc(repo)
+        if doc:
+            rel = os.path.relpath(os.path.join(repo, doc), lane_workdir(repo, lane))
+            cmd = cmd.replace("{{contract}}", rel.replace("\\", "/"))
+    if "{{host}}" in cmd:
+        cmd = cmd.replace("{{host}}", lane_host(repo, lane) or "{{root}}")
     if "{{root}}" not in cmd:
         return cmd
     r = norm_root(lane.get("root"))
     # `./` is the repo root: a bare `./` reads as noise in a command line, and the
     # only sensible substitution for "the root, which is here" is the cwd itself.
-    sub = "." if (r == REPO_ROOT or not r) else r.rstrip("/")
+    runs_inside = (lane.get("run_from") or "repo") == "root"
+    sub = "." if (r == REPO_ROOT or not r or runs_inside) else r.rstrip("/")
     return cmd.replace("{{root}}", sub)
 
 
+def lane_value(repo, lane, key):
+    """A lane's value for one key, or its stack profile's when the lane sets none.
+
+    Only CONTRACT_KEYS fall back. The phase commands are written onto the lane when it
+    is declared; these are read from the profile at run time, so a lane declared before
+    they existed answers them, and a value set on the lane — by a pack or a developer —
+    overrides the profile's.
+    """
+    value = (lane.get(key) or "").strip() if lane else ""
+    if not value and lane and repo and key in CONTRACT_KEYS:
+        value = (profile_of(repo, lane).get(key) or "").strip()
+    return value
+
+
+def contract_doc(repo, lanes=None):
+    """The service lane's exported API document, repo-relative; "" with no service lane."""
+    if lanes is None:
+        lanes = (read_stacks(repo) or {}).get("lanes") or []
+    lane = next((l for l in lanes if l.get("kind") == "backend"), {})
+    r = norm_root(lane.get("root"))
+    if not r:
+        return ""
+    return CONTRACT_DOC if r == REPO_ROOT else r + CONTRACT_DOC
+
+
 def roots_overlap(a, b):
     """Roots own their subtree, so containment either way is an overlap.
 
@@ -654,7 +811,7 @@ def lane_test_path(repo, lane, prof=None):
 
     Most backend stacks keep tests BESIDE the source rather than in it: .NET's `tests/`
     next to `src/`, Maven's `src/test/java/` next to `src/main/java/`, pytest's `tests/`
-    next to `app/`. A lane that owned only its source path could not hold its own tests.
+    next to `app/`. A lane that owned only its lane root folder could not hold its own tests.
 
     Answered at READ time, like `ecosystem`, so a lane declared before this existed has
     one without being re-declared:
@@ -662,8 +819,11 @@ def lane_test_path(repo, lane, prof=None):
         does not describe;
       - else the profile's `test_root`, which pairs with the profile's default `root`. A
         lane at that root takes it as is; a lane whose root ends with it takes it under
-        the same prefix (`backend/src/` ⇒ `backend/tests/`);
-      - else the tests live inside the source path. That is right for every frontend
+        the same prefix (`apps/backend/` ⇒ `apps/backend/tests/`);
+      - else the profile's `conventional_test_root`, which pairs the same way with its
+        `conventional_root` — the classic layout an existing repository has (`src/` ⇒
+        `tests/`), so a lane declared at it keeps the test path it always had;
+      - else the tests live inside the lane root folder. That is right for every frontend
         profile, for Go's colocated `_test.go` files, and for a Maven lane rooted at the
         directory holding its pom.xml.
     """
@@ -676,24 +836,25 @@ def lane_test_path(repo, lane, prof=None):
     if own:
         return own
     prof = profile_of(repo, lane) if prof is None else prof
-    default_root = norm_root(prof.get("root"))
-    default_tests = norm_root(prof.get("test_root"))
-    if not default_root or not default_tests or REPO_ROOT in (default_root, default_tests):
-        return root
-    if root == default_root:
-        return default_tests
-    if root.endswith("/" + default_root):
-        return root[: -len(default_root)] + default_tests
+    for key_root, key_tests in (("root", "test_root"),
+                                ("conventional_root", "conventional_test_root")):
+        base, tests = norm_root(prof.get(key_root)), norm_root(prof.get(key_tests))
+        if not base or not tests or REPO_ROOT in (base, tests):
+            continue
+        if root == base:
+            return tests
+        if root.endswith("/" + base):
+            return root[: -len(base)] + tests
     return root
 
 
 def lane_owned_paths(repo, lane, prof=None):
-    """Every subtree a lane owns, labelled: its source path, and its test path when that
+    """Every subtree a lane owns, labelled: its lane root folder, and its test path when that
     is a different directory. Ownership checks compare these, so a test path can never
     land inside another lane's subtree."""
     root = norm_root(lane.get("root"))
     tests = lane_test_path(repo, lane, prof)
-    owned = [("source path", root)] if root else []
+    owned = [("lane root folder", root)] if root else []
     if tests and tests != root:
         owned.append(("test path", tests))
     return owned
@@ -768,7 +929,7 @@ def cmd_declare(args):
     lane_id = args.id or DEFAULT_LANE_ID.get(kind, kind)
     root = norm_root(args.root or (prof or {}).get("root") or "")
     if not root:
-        fail("lane-declare: lane '%s' has no source path. A lane without a root owns "
+        fail("lane-declare: lane '%s' has no lane root folder. A lane without a root owns "
              "nothing, so nothing can be built, run or written into it. Pass "
              "--source-path <dir> (the profile declares no default)." % lane_id)
 
@@ -777,7 +938,7 @@ def cmd_declare(args):
     # is about to read the code out of it.
     exists = root_on_disk(repo, root)
     if args.require_existing_root and not exists:
-        fail("lane-declare: source path '%s' for lane '%s' does not exist under %s. "
+        fail("lane-declare: lane root folder '%s' for lane '%s' does not exist under %s. "
              "Point the lane at the directory that actually holds this lane's source, "
              "or re-run /appweaver select-stack to correct it."
              % (root, lane_id, repo))
@@ -802,8 +963,12 @@ def cmd_declare(args):
         lane["migrate"] = migrate
     # WHERE this lane's commands run — see lane_workdir. Recorded only when it is not
     # the default, so a lane reads the same as it always did unless its stack needs the
-    # other answer.
-    run_from = getattr(args, "run_from", "") or (prof or {}).get("run_from", "")
+    # other answer. An explicit --run-from wins; else the stack's build file decides when
+    # it is on disk (build_files_at); else — a greenfield lane, nothing written yet — the
+    # profile's own answer, which for a new project is inside the lane.
+    run_from = (getattr(args, "run_from", "")
+                or build_files_at(repo, root, (prof or {}).get("build_files") or [])
+                or (prof or {}).get("run_from", ""))
     if run_from == "root":
         lane["run_from"] = "root"
     # What the code was found to be, when no shipped profile names it.
@@ -824,7 +989,7 @@ def cmd_declare(args):
             for theirs_label, theirs in lane_owned_paths(repo, other):
                 if roots_overlap(mine, theirs):
                     fail("lane-declare: %s '%s' for lane '%s' overlaps lane '%s''s %s '%s'. "
-                         "A lane owns its source path and its test path, and no two lanes "
+                         "A lane owns its lane root folder and its test path, and no two lanes "
                          "may share a subtree."
                          % (mine_label, mine, lane_id, other.get("id"), theirs_label, theirs))
 
@@ -880,6 +1045,53 @@ def write_stacks(repo, data):
         fh.write("\n")
 
 
+def cmd_set(args):
+    """Change CONTRACT_KEYS on a lane that is already declared, leaving the rest of it
+    as it is. `--set KEY=` with an empty value changes nothing, so a caller can pass every
+    key it might have; `--unset KEY` removes one, so the lane reads its profile's again."""
+    repo = args.repo
+    data = read_stacks(repo) or {"lanes": []}
+    lanes = data.get("lanes") or []
+    wanted = strip_root_label(args.id) if args.id else ""
+    lane = next((l for l in lanes if (l.get("id") == wanted if wanted
+                                      else l.get("kind") == args.kind)), None)
+    if lane is None:
+        fail("lane-set: no lane %s is declared in %s"
+             % ("'%s'" % wanted if wanted else "of kind '%s'" % (args.kind or "?"), STACKS_REL))
+
+    set_, removed = {}, []
+    for item in args.set or []:
+        key, sep, value = item.partition("=")
+        key = key.strip()
+        if not sep or key not in CONTRACT_KEYS:
+            fail("lane-set: '%s' is not KEY=VALUE with KEY one of %s"
+                 % (item, ", ".join(CONTRACT_KEYS)))
+        if value.strip():
+            set_[key] = value.strip()
+    for key in args.unset or []:
+        if key not in CONTRACT_KEYS:
+            fail("lane-set: --unset '%s' is not one of %s" % (key, ", ".join(CONTRACT_KEYS)))
+        if key not in set_ and key in lane:
+            removed.append(key)
+
+    lane.update(set_)
+    for key in removed:
+        del lane[key]
+    if set_ or removed:
+        data["lanes"] = lanes
+        write_stacks(repo, data)
+    emit({
+        "ok": True,
+        "lane_id": lane.get("id", ""),
+        "kind": lane.get("kind", ""),
+        "set": set_,
+        "removed": removed,
+        "lane": lane,
+        "path": STACKS_REL,
+        "written": bool(set_ or removed),
+    })
+
+
 def profile_of(repo, lane):
     """The stack profile a lane names, or {} when it names none the kit ships."""
     if not lane:
@@ -893,7 +1105,7 @@ def profile_of(repo, lane):
 def kind_block(repo, lanes, kind):
     """Every field a caller needs about ONE kind, flattened and prefixed.
 
-    A workflow that wants the service source path binds `$.backend_source_path`
+    A workflow that wants the service lane root folder binds `$.backend_source_path`
     and is done — no `--kind` argument, no second call, and no branch on which
     lane came back. Both kinds are always present in the payload, so the two-lane
     steps (a gate that needs backend, a report that names both) resolve one script
@@ -927,14 +1139,27 @@ def kind_block(repo, lanes, kind):
         kind + "_root": root,
         kind + "_source_path": root,
         kind + "_root_exists": root_on_disk(repo, root),
-        # Where the lane's paired tests go. Equal to the source path when the stack keeps
+        # Where the lane's paired tests go. Equal to the lane root folder when the stack keeps
         # its tests inside it; see lane_test_path.
         kind + "_test_path": test_path,
         kind + "_test_path_exists": root_on_disk(repo, test_path),
-        kind + "_build": lane_command(lane, "build"),
-        kind + "_test": lane_command(lane, "test"),
-        kind + "_run": lane_command(lane, "run"),
-        kind + "_migrate": lane_command(lane, "migrate") or prof.get("migrate", ""),
+        # Where the lane's commands run, as DECLARED — `./` for the repository root.
+        # Read from the declaration rather than from lane_workdir, which falls back to the
+        # repo root while the lane root folder is not on disk yet; a phase that creates the
+        # project has to be told where its build will run before that path exists.
+        kind + "_workdir": (norm_root(root) or REPO_ROOT)
+                           if lane and (lane.get("run_from") or "repo") == "root"
+                           else (REPO_ROOT if lane else ""),
+        kind + "_build": lane_command(lane, "build", repo),
+        kind + "_test": lane_command(lane, "test", repo),
+        kind + "_run": lane_command(lane, "run", repo),
+        kind + "_migrate": lane_command(lane, "migrate", repo) or prof.get("migrate", ""),
+        # The API-contract settings, the lane's own or its profile's (lane_value). A
+        # service lane uses the first two and a frontend lane the third; the others read
+        # empty on each.
+        kind + "_contract_run": lane_command(lane, "contract_run", repo),
+        kind + "_contract": lane_value(repo, lane, "contract"),
+        kind + "_client": lane_command(lane, "client", repo),
     }
 
 
@@ -956,7 +1181,7 @@ def lane_options(repo, lanes):
         title = (prof.get("title", "") or lane.get("stack", "")
                  or lane.get("profile", "") or "no stack declared")
         root = norm_root(lane.get("root"))
-        where = "the repo root" if root == REPO_ROOT else (root or "no source path")
+        where = "the repo root" if root == REPO_ROOT else (root or "no lane root folder")
         label = "%s %s at %s" % (lane.get("kind", "lane"), title, where)
         tests = lane_test_path(repo, lane, prof)
         if tests and tests != root:
@@ -1018,6 +1243,7 @@ def cmd_resolve(args):
             "lane_id": "", "root": "", "source_path": "", "test_path": "", "root_exists": False,
             "build": "", "test": "", "run": "", "migrate": "",
             "language": "", "ecosystem": "",
+            "contract_doc": "", "contract_doc_exists": False,
             "path": STACKS_REL,
         }
         payload.update(kind_block(args.repo, [], "backend"))
@@ -1029,12 +1255,13 @@ def cmd_resolve(args):
     lanes = data.get("lanes") or []
     match = {}
     # The id may arrive as a whole option line — `user_select` hands back the string it
-    # displayed, label and all — so strip it the way a source path is stripped.
+    # displayed, label and all — so strip it the way a lane root folder is stripped.
     wanted = strip_root_label(args.id) if args.id else ""
     if wanted:
         match = next((l for l in lanes if l.get("id") == wanted), {})
     elif args.kind:
         match = next((l for l in lanes if l.get("kind") == args.kind), {})
+    doc = contract_doc(args.repo, lanes)
 
     # `declared` is about LANES and `exists` about the file — they part company on
     # the shipped-but-unfilled seed, which is on disk and declares nothing.
@@ -1052,13 +1279,16 @@ def cmd_resolve(args):
         "source_path": match.get("root", ""),
         "test_path": lane_test_path(args.repo, match),
         "root_exists": root_on_disk(args.repo, match.get("root", "")),
-        "build": lane_command(match, "build"),
-        "test": lane_command(match, "test"),
-        "run": lane_command(match, "run"),
-        "migrate": lane_command(match, "migrate") or profile_of(args.repo, match).get("migrate", ""),
+        "build": lane_command(match, "build", args.repo),
+        "test": lane_command(match, "test", args.repo),
+        "run": lane_command(match, "run", args.repo),
+        "migrate": lane_command(match, "migrate", args.repo) or profile_of(args.repo, match).get("migrate", ""),
         "language": profile_of(args.repo, match).get("language", ""),
         "ecosystem": profile_of(args.repo, match).get("ecosystem", ""),
         "prototype": data.get("prototype", {}),
+        # The service lane's exported API document, and whether an export has written it.
+        "contract_doc": doc,
+        "contract_doc_exists": bool(doc) and os.path.isfile(os.path.join(args.repo, doc)),
         "path": STACKS_REL,
     }
     payload.update(kind_block(args.repo, lanes, "backend"))
@@ -1077,7 +1307,7 @@ def cmd_resolve(args):
 #   only for the kinds a caller asks for with --require, because "no frontend
 #   lane" is the correct and common state and must never fail a backend build.
 #
-#   BROKEN — a lane IS declared and its source path is empty or is not a directory.
+#   BROKEN — a lane IS declared and its lane root folder is empty or is not a directory.
 #   Checked for EVERY declared lane whether or not the caller asked about it. A
 #   stack named against a path that is not there is a mistake in every phase, and
 #   letting it through means discovering it as an empty build or a generator
@@ -1106,7 +1336,7 @@ def cmd_verify(args):
     issues = []
 
     # An empty file and an absent one are the SAME state. The kit ships
-    # stacks.json holding `{"lanes": []}` so a project can fill it in by hand, so
+    # stacks.json with an empty `lanes` array so a project can fill it in by hand, so
     # the file being there says nothing about whether a lane was declared — only
     # its contents do. Both cases report one issue naming which of the two it is.
     if not lanes:
@@ -1130,13 +1360,13 @@ def cmd_verify(args):
             root = lane.get("root", "")
             if not root:
                 issues.append(
-                    "lane '%s' (%s, stack %s) declares no source path. A lane owns a "
+                    "lane '%s' (%s, stack %s) declares no lane root folder. A lane owns a "
                     "subtree; without one nothing can be built, run or written into it. "
-                    "Re-run `/appweaver select-stack` and give it a source path."
+                    "Re-run `/appweaver select-stack` and give it a lane root folder."
                     % (lane_id, kind, lane.get("profile", "?")))
             elif not args.allow_missing_root and not root_on_disk(repo, root):
                 issues.append(
-                    "lane '%s' (%s, stack %s) declares source path '%s', which is not a "
+                    "lane '%s' (%s, stack %s) declares lane root folder '%s', which is not a "
                     "directory in this repository. Re-run `/appweaver select-stack` and "
                     "point the lane at the directory that holds its source."
                     % (lane_id, kind, lane.get("profile", "?"), root))
@@ -1144,7 +1374,7 @@ def cmd_verify(args):
         # hand-edited file — a supported way to fill this in, and the one path that
         # does not pass the writer. The invariant is worth a second check anywhere:
         # two lanes sharing a subtree means two generators can write one file. A lane
-        # owns its test path as well as its source path, so both are compared.
+        # owns its test path as well as its lane root folder, so both are compared.
         for i, first in enumerate(lanes):
             for second in lanes[i + 1:]:
                 clash = next(((fl, fp, sl, sp)
@@ -1154,7 +1384,7 @@ def cmd_verify(args):
                 if clash:
                     issues.append(
                         "lanes '%s' and '%s' claim overlapping subtrees: %s '%s' and %s '%s'. "
-                        "A lane owns its source path and its test path, and they must be "
+                        "A lane owns its lane root folder and its test path, and they must be "
                         "disjoint from every other lane's, or two generators can write the "
                         "same file. Give each lane paths outside the other's."
                         % (first.get("id", "?"), second.get("id", "?"),
@@ -1191,7 +1421,7 @@ def cmd_verify(args):
 # ────────────────────────────── run-phase ──────────────────────────────────
 # Execute a phase's project-supplied command for EVERY declared lane.
 #
-# This is the payoff of declaring a source path. Without a declaration, `build`
+# This is the payoff of declaring a lane root folder. Without a declaration, `build`
 # sniffs: it looks for a .sln, then for a package.json, and takes the first hit.
 # On a single-lane repo that is right. On a two-lane repo it is wrong in the worst
 # way available — it builds the backend, reports green, and never mentions that the
@@ -1256,21 +1486,21 @@ def cmd_run_phase(args):
     testlog = _testlog()
     ok, ran = True, False
     for lane in lanes:
-        cmd = lane_command(lane, args.phase)
+        cmd = lane_command(lane, args.phase, repo)
         lane_id, root = lane.get("id", "?"), lane.get("root", "")
         if not cmd:
             results.append({"lane": lane_id, "root": root, "cmd": "",
                             "ran": False, "ok": True, "skipped": "no %s command" % args.phase})
             continue
-        # The source path has to be there before a command is run against it.
+        # The lane root folder has to be there before a command is run against it.
         # Reported per lane rather than raised, so a two-lane run still reports
         # what the other lane did.
         if not root_on_disk(repo, root):
             ok = False
             results.append({"lane": lane_id, "root": root, "cmd": cmd, "ran": False, "ok": False,
-                            "error": "source path '%s' is not a directory" % root})
-            tails.append("[%s] source path '%s' is not a directory" % (lane_id, root))
-            excerpts.append("[%s] source path '%s' is not a directory — nothing ran"
+                            "error": "lane root folder '%s' is not a directory" % root})
+            tails.append("[%s] lane root folder '%s' is not a directory" % (lane_id, root))
+            excerpts.append("[%s] lane root folder '%s' is not a directory — nothing ran"
                             % (lane_id, root))
             failing.append(lane_id)
             continue
@@ -1337,6 +1567,329 @@ def cmd_run_phase(args):
     })
 
 
+# ─────────────────────────── contract-export ───────────────────────────────
+# The service lane's API document, taken from the service itself. A document served by a
+# running service is the one thing every web stack can produce the same way — Swagger,
+# springdoc, FastAPI and the rest all serve one — so the export starts the service with
+# the lane's `contract_run`, fetches `contract`, and stops it. How a stack (or the pack
+# the lane was scaffolded from) has to be started is the command's business, not this
+# code's.
+
+CONTRACT_HTTP_METHODS = ("get", "put", "post", "delete", "options", "head", "patch", "trace")
+
+
+def _fetch(url, timeout=5):
+    """(status, body bytes, error text). A local https service usually has a development
+    certificate, so certificate checks are skipped for localhost only."""
+    import ssl
+    import urllib.error
+    import urllib.parse
+    import urllib.request
+    ctx = None
+    if url.lower().startswith("https://"):
+        host = (urllib.parse.urlparse(url).hostname or "").lower()
+        if host in ("localhost", "127.0.0.1", "::1"):
+            ctx = ssl._create_unverified_context()
+    try:
+        with urllib.request.urlopen(url, timeout=timeout, context=ctx) as resp:
+            return resp.status, resp.read(), ""
+    except urllib.error.HTTPError as e:
+        return e.code, b"", "HTTP %d" % e.code
+    except Exception as e:  # refused, reset, timed out — the service is not up yet
+        return 0, b"", str(getattr(e, "reason", e))
+
+
+def _api_document(body):
+    """The parsed document, or None when the body is not an OpenAPI/Swagger document."""
+    try:
+        doc = json.loads(body.decode("utf-8-sig"))
+    except (ValueError, UnicodeDecodeError):
+        return None
+    if isinstance(doc, dict) and ("openapi" in doc or "swagger" in doc) \
+            and isinstance(doc.get("paths"), dict):
+        return doc
+    return None
+
+
+def _operations(doc):
+    """Every operation in a document: [{"id", "method", "path"}], in document order."""
+    ops = []
+    for path, item in (doc.get("paths") or {}).items():
+        if not isinstance(item, dict):
+            continue
+        for method in CONTRACT_HTTP_METHODS:
+            op = item.get(method)
+            if isinstance(op, dict):
+                ops.append({"id": str(op.get("operationId") or ""),
+                            "method": method.upper(), "path": path})
+    return ops
+
+
+def _start(cmd, cwd, log):
+    import subprocess
+    kw = {"shell": True, "cwd": cwd, "stdout": log, "stderr": subprocess.STDOUT}
+    if os.name == "nt":
+        kw["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        kw["start_new_session"] = True   # its own process group, so the stop reaches children
+    return subprocess.Popen(cmd, **kw)
+
+
+def _stop(proc):
+    """Stop the service and everything it started — `dotnet run` and `npm run` both run
+    the real server as a child, which outlives a kill of the parent alone."""
+    import signal
+    import subprocess
+    if proc.poll() is not None:
+        return
+    if os.name == "nt":
+        subprocess.run(["taskkill", "/F", "/T", "/PID", str(proc.pid)],
+                       stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    else:
+        try:
+            os.killpg(proc.pid, signal.SIGTERM)
+        except OSError:
+            pass
+        try:
+            proc.wait(timeout=15)
+        except subprocess.TimeoutExpired:
+            try:
+                os.killpg(proc.pid, signal.SIGKILL)
+            except OSError:
+                pass
+    try:
+        proc.wait(timeout=15)
+    except Exception:
+        pass
+
+
+def _tail(path, budget=LANE_TAIL):
+    try:
+        with open(path, "rb") as fh:
+            return fh.read().decode("utf-8", "replace")[-budget:].strip()
+    except OSError:
+        return ""
+
+
+def cmd_contract_export(args):
+    import tempfile
+    import time
+
+    repo = args.repo
+    lanes = (read_stacks(repo) or {}).get("lanes") or []
+    lane = next((l for l in lanes if l.get("kind") == "backend"), {})
+    doc_rel = contract_doc(repo, lanes)
+    doc_abs = os.path.join(repo, doc_rel) if doc_rel else ""
+    cmd = lane_command(lane, "contract_run", repo)
+    url = lane_value(repo, lane, "contract")
+    result = {
+        "ok": False, "ran": False, "lane": lane.get("id", ""), "cmd": cmd, "url": url,
+        "cwd": "", "doc": doc_rel, "doc_exists": bool(doc_abs) and os.path.isfile(doc_abs),
+        "operations": 0, "unnamed": 0, "seconds": 0, "already_running": False,
+        "reason": "", "log_tail": "",
+        # The placeholder a `client` command names the document by, spelled out for a
+        # prompt that asks for one — a workflow cannot write it literally, since the
+        # engine would read it as a variable.
+        "placeholder": "{{contract}}",
+    }
+
+    def done(**kw):
+        result.update(kw)
+        result["doc_exists"] = bool(doc_abs) and os.path.isfile(doc_abs)
+        # One line on which document a reader now has, for a prompt to quote.
+        if result["ok"]:
+            result["status"] = "%s, exported from the built service in this run" % doc_rel
+        elif result["doc_exists"]:
+            result["status"] = ("%s, from an earlier export — this run's failed, so it may "
+                                "be older than the code" % doc_rel)
+        else:
+            result["status"] = ""
+        emit(result)
+
+    if not lane:
+        return done(reason="no service lane is declared in %s" % STACKS_REL)
+    if not root_on_disk(repo, lane.get("root", "")):
+        return done(reason="the service lane root folder '%s' is not on disk yet"
+                    % lane.get("root", ""))
+    if not url:
+        return done(reason="the service lane has no `contract` URL — set it in %s, or in "
+                           "its stack profile" % STACKS_REL)
+
+    # A service already answering at the URL is used as it is: a second instance could
+    # not bind the port anyway. It may be running older code than this run built, which
+    # the caller is told.
+    status, body, _err = _fetch(url)
+    proc, log_path, started, exited = None, "", time.time(), None
+    if status != 200 or _api_document(body) is None:
+        if not cmd:
+            return done(reason="the service lane has no `contract_run` command to start it "
+                               "— set it in %s, or in its stack profile" % STACKS_REL)
+        workdir = lane_workdir(repo, lane)
+        result["cwd"] = os.path.relpath(workdir, repo).replace("\\", "/")
+        fd, log_path = tempfile.mkstemp(prefix="aw-contract-", suffix=".log")
+        log = os.fdopen(fd, "wb")
+        try:
+            proc = _start(cmd, workdir, log)
+            result["ran"] = True
+            deadline = started + args.timeout
+            status, body = 0, b""
+            while time.time() < deadline:
+                if proc.poll() is not None:
+                    exited = proc.returncode
+                    break
+                status, body, _err = _fetch(url)
+                if status == 200 and _api_document(body) is not None:
+                    break
+                time.sleep(2)
+        finally:
+            if proc is not None:
+                _stop(proc)
+            log.close()
+    else:
+        result["already_running"] = True
+
+    seconds = int(time.time() - started)
+    tail = _tail(log_path) if log_path else ""
+    if log_path:
+        try:
+            os.remove(log_path)
+        except OSError:
+            pass
+    doc = _api_document(body) if status == 200 else None
+    if doc is None:
+        if exited is not None:
+            why = "`%s` exited (code %s) before %s answered" % (cmd, exited, url)
+        elif status == 200:
+            why = "%s answered, but not with an OpenAPI or Swagger JSON document" % url
+        elif status:
+            why = "%s answered HTTP %d for %d s" % (url, status, seconds)
+        else:
+            why = "nothing answered at %s within %d s" % (url, args.timeout)
+        return done(seconds=seconds, log_tail=tail,
+                    reason=why + (" — the last exported document is kept" if result["doc_exists"] else ""))
+
+    os.makedirs(os.path.dirname(doc_abs), exist_ok=True)
+    with open(doc_abs, "w", encoding="utf-8") as fh:
+        json.dump(doc, fh, indent=2)
+        fh.write("\n")
+    ops = _operations(doc)
+    note = ("fetched from a service that was already running at %s — it may be older than "
+            "the code this run built" % url) if result["already_running"] else ""
+    done(ok=True, seconds=seconds, operations=len(ops),
+         unnamed=sum(1 for o in ops if not o["id"]), reason=note, log_tail="")
+
+
+# ─────────────────────────── contract-check ────────────────────────────────
+# Do the operation ids a frontend plan cites exist in the exported document? Read by
+# script, so the answer does not depend on a model reading two documents carefully.
+#
+# The ids are read from two table shapes, the two plan templates' own:
+#   - the master plan's §5, a table with an `Operation id` column;
+#   - a delta plan's ADDED/MODIFIED tables, where a row whose section is `Contract
+#     Binding` names the operation id as its element's first `code` span.
+
+_OP_ID = re.compile(r"^[A-Za-z_][A-Za-z0-9_.-]*$")
+_NOT_AN_ID = {"none", "tbd", "todo", "na"}
+
+
+def _cells(line):
+    s = line.strip()
+    if not s.startswith("|"):
+        return None
+    return [c.strip() for c in s.strip("|").split("|")]
+
+
+def _is_rule(cells):
+    return bool(cells) and all(re.fullmatch(r":?-{3,}:?", c or "") for c in cells)
+
+
+def _op_ids(text):
+    """The operation ids a cell names: `code` spans first, else bare words. Placeholders
+    (`[OperationId]`), dashes and anything with a space are not ids."""
+    spans = re.findall(r"`([^`]+)`", text)
+    tokens = [t.strip() for t in (spans if spans else re.split(r"[,·;]\s*|\s+", text))]
+    return [t for t in tokens if _OP_ID.match(t) and t.lower() not in _NOT_AN_ID]
+
+
+def plan_operation_ids(text):
+    """(cited ids in order, rows with a binding but no id)."""
+    lines = text.splitlines()
+    cited, uncited = [], 0
+    i = 0
+    while i < len(lines):
+        header = _cells(lines[i])
+        rule = _cells(lines[i + 1]) if i + 1 < len(lines) else None
+        if header is None or rule is None or not _is_rule(rule):
+            i += 1
+            continue
+        lowered = [h.lower() for h in header]
+        id_col = next((n for n, h in enumerate(lowered) if h.replace("-", " ") == "operation id"), -1)
+        section_col = next((n for n, h in enumerate(lowered) if h.startswith("section")), -1)
+        i += 2
+        while i < len(lines) and _cells(lines[i]) is not None:
+            row = _cells(lines[i])
+            i += 1
+            if id_col >= 0 and id_col < len(row):
+                ids = _op_ids(row[id_col])
+            elif section_col >= 0 and section_col < len(row) \
+                    and "contract binding" in row[section_col].lower() and section_col + 1 < len(row):
+                spans = re.findall(r"`([^`]+)`", row[section_col + 1])
+                ids = [s for s in spans[:1] if _OP_ID.match(s)]
+            else:
+                continue
+            if ids:
+                cited.extend(x for x in ids if x not in cited)
+            else:
+                uncited += 1
+    return cited, uncited
+
+
+def cmd_contract_check(args):
+    repo = args.repo
+    plan_abs = args.plan if os.path.isabs(args.plan) else os.path.join(repo, args.plan)
+    doc_rel = args.doc or contract_doc(repo)
+    doc_abs = (doc_rel if os.path.isabs(doc_rel) else os.path.join(repo, doc_rel)) if doc_rel else ""
+    result = {"ok": False, "plan": args.plan, "doc": doc_rel,
+              "doc_exists": bool(doc_abs) and os.path.isfile(doc_abs),
+              "cited": 0, "ids": [], "missing": [], "uncited": 0,
+              "doc_operations": 0, "doc_unnamed": 0, "reason": ""}
+    if not os.path.isfile(plan_abs):
+        result["reason"] = "the frontend plan %s is not on disk" % args.plan
+        return emit(result)
+    with open(plan_abs, encoding="utf-8", errors="replace") as fh:
+        cited, uncited = plan_operation_ids(fh.read())
+    result.update(cited=len(cited), ids=cited, uncited=uncited)
+    if not result["doc_exists"]:
+        result["reason"] = "no exported API document at %s" % (doc_rel or "(no service lane)")
+        return emit(result)
+    with open(doc_abs, "rb") as fh:
+        doc = _api_document(fh.read())
+    if doc is None:
+        result["reason"] = "%s is not an OpenAPI or Swagger JSON document" % doc_rel
+        return emit(result)
+    ops = _operations(doc)
+    known = {o["id"] for o in ops if o["id"]}
+    lower = {k.lower(): k for k in known}
+    missing = []
+    for x in cited:
+        if x not in known:
+            near = lower.get(x.lower())
+            missing.append(x + (" (the document has %s)" % near if near else ""))
+    result.update(missing=missing, doc_operations=len(ops),
+                  doc_unnamed=sum(1 for o in ops if not o["id"]))
+    parts = []
+    if missing:
+        parts.append("%d cited operation id(s) are not in %s: %s"
+                     % (len(missing), doc_rel, ", ".join(missing)))
+    if not cited:
+        parts.append("the plan cites no operation id")
+    if uncited:
+        parts.append("%d binding row(s) cite no operation id" % uncited)
+    result["reason"] = "; ".join(parts)
+    result["ok"] = bool(cited) and not missing
+    emit(result)
+
+
 # ──────────────────────────────── probe ────────────────────────────────────
 
 def profile_terms(prof):
@@ -1449,14 +2002,14 @@ def main():
                         "evidence there, so a service profile cannot relocate onto the UI's files")
     p.set_defaults(func=cmd_detect)
 
-    p = sub.add_parser("declare", help="upsert a lane into stacks.json (sole writer)")
+    p = sub.add_parser("declare", help="upsert a whole lane into stacks.json")
     p.add_argument("--profile", required=True,
                    help="profile id, a select_options label, 'none', or 'detected' "
                         "(a stack the kit ships no profile for — needs --stack and --root)")
     p.add_argument("--kind", choices=["backend", "frontend"])
     p.add_argument("--id", help="lane id (default: service for backend, web for frontend)")
     p.add_argument("--root", "--source-path", dest="root",
-                   help="the lane's SOURCE PATH — the subtree it owns, overriding the "
+                   help="the LANE ROOT FOLDER — the subtree it owns, overriding the "
                         "profile's default root. The two spellings are one field")
     p.add_argument("--run-from", dest="run_from", choices=["repo", "root"],
                    help="where this lane's build/test/run commands execute: 'repo' (default) "
@@ -1466,7 +2019,7 @@ def main():
                         "subtree (a Maven wrapper at backend/<app>/mvnw). Defaults to the "
                         "profile's own setting")
     p.add_argument("--require-existing-root", dest="require_existing_root", action="store_true",
-                   help="refuse a source path that is not a directory. For a caller about "
+                   help="refuse a lane root folder that is not a directory. For a caller about "
                         "to READ the subtree (onboard); greenfield declares a path that "
                         "implement has not created yet, and leaves this off")
     p.add_argument("--stack", default="",
@@ -1498,7 +2051,7 @@ def main():
                    help="a lane kind this phase cannot run without; repeatable. Omit to "
                         "check only that whatever IS declared is sound")
     p.add_argument("--allow-missing-root", dest="allow_missing_root", action="store_true",
-                   help="do not require the source paths to exist on disk yet — the "
+                   help="do not require the lane root folders to exist on disk yet — the "
                         "greenfield state, where select-stack declares a path implement "
                         "will create")
     p.add_argument("--command", default="",
@@ -1506,12 +2059,36 @@ def main():
     p.set_defaults(func=cmd_verify)
 
     p = sub.add_parser("run-phase", help="run a phase's command for every declared lane")
-    p.add_argument("--phase", required=True, choices=["build", "test", "run", "migrate"],
-                   help="which project-supplied command to run")
+    p.add_argument("--phase", required=True, choices=["build", "test", "run", "migrate", "client"],
+                   help="which project-supplied command to run; `client` is a frontend lane's "
+                        "client generator, with {{contract}} expanded")
     p.add_argument("--kind", choices=["backend", "frontend"],
                    help="restrict to one lane kind (default: every declared lane)")
     p.set_defaults(func=cmd_run_phase)
 
+    p = sub.add_parser("set", help="change API-contract keys on a declared lane")
+    p.add_argument("--id", default="", help="the lane id")
+    p.add_argument("--kind", choices=["backend", "frontend"],
+                   help="the lane of this kind, when --id is not given")
+    p.add_argument("--set", action="append", default=[], metavar="KEY=VALUE",
+                   help="repeatable; KEY is one of %s, and an empty VALUE changes nothing"
+                        % ", ".join(CONTRACT_KEYS))
+    p.add_argument("--unset", action="append", default=[], metavar="KEY",
+                   help="repeatable; remove KEY, so the lane reads its profile's value again")
+    p.set_defaults(func=cmd_set)
+
+    p = sub.add_parser("contract-export",
+                       help="start the service lane, save its API document, stop it")
+    p.add_argument("--timeout", type=int, default=180,
+                   help="seconds to wait for the document after starting the service")
+    p.set_defaults(func=cmd_contract_export)
+
+    p = sub.add_parser("contract-check",
+                       help="the operation ids a frontend plan cites vs the exported document")
+    p.add_argument("--plan", required=True, help="the frontend plan (master or delta)")
+    p.add_argument("--doc", default="", help="the API document (default: the exported one)")
+    p.set_defaults(func=cmd_contract_check)
+
     p = sub.add_parser("probe", help="evidence of a lane of this kind (file signals only)")
     p.add_argument("--kind", choices=["backend", "frontend"], default="frontend")
     p.add_argument("--hint", default="", help="free prose to scan for a stack name")