aw-spec-cli 0.1.31 → 0.1.32

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

@@ -1,19 +1,17 @@
 #!/usr/bin/env python3
 """aw-inventory.py — brownfield repository inventory for the aw-spec pipeline.
 
-The deterministic, model-free substrate for the Brownfield-Pipeline B0
-(Inventory) phase (see Brownfield-Pipeline.md).
-It scans an existing ("brownfield") codebase and emits a factual JSON substrate
-that the /appweaver inventory workflow's enrichment agent turns into an
-aggregate-organized OKF v0.1 knowledge bundle. The agent uses this so it never
-has to guess the repo layout.
-
-Ported from Reference/okf-inventory.sh (which was ~90% embedded python already)
-into a single cross-platform python core, with two brownfield additions:
+The deterministic, model-free reader behind /appweaver inventory and the scan
+/appweaver onboard runs (see Brownfield-Pipeline.md). It reads an existing
+("brownfield") codebase and reports what the code shows: the boundary map inventory
+proposes and applies, and the JSON substrate onboard builds a bounded context's OKF
+knowledge from. It never authors specs, governance or knowledge, and never modifies
+source. What the substrate carries:
 
   * aggregate_signals — candidate DDD aggregate roots derived from domain /
-    entity / model / route file clustering, ranked by churn + evidence. These
-    are SIGNALS, not decisions: the workflow's agent draws the real aggregate
+    entity / model / route file clustering, ranked by churn + evidence; on a
+    project with a UI lane and no service lane, the API resources the UI calls
+    (ui_reading), as the map was proposed from. These are SIGNALS, not decisions: the workflow's agent draws the real aggregate
     boundaries. This is the "inventory following aggregate root" the pipeline
     needs — one aggregate ≈ one candidate specs/<Feature>/ vertical slice.
   * frontend_signals — candidate FRONTEND lane root folders derived from component /
@@ -36,23 +34,46 @@ orchestrator's execute_script can bind it); human-readable summaries go to STDER
 so they never corrupt the JSON contract:
 
   scan     [--root <dir>] [--out <path>] [--bundle <dir>] [--config <yml>]
-           -> writes the full substrate JSON to --out; prints a compact summary
-              object {inventory_json, file_count, head, branch, aggregate_count,
+           [--service-root <p>] [--ui-root <p>] [--map <json>]
+           -> writes the full substrate JSON to --out, each lane's signals read from its
+              declared lane root folder only and the aggregates read with the strategy
+              the map was built from; prints a compact summary object
+              {inventory_json, file_count, head, branch, aggregate_count,
               frontend_present, frontend_separable, frontend_root_count,
               frontend_roots, bundle_dir, bundle_present, bundle_md_count}
+  propose  [--root <dir>] [--config <yml>] [--service-root <p>] [--ui-root <p>]
+           [--strategy <request>] [--out <md>] [--map <json>]
+           -> Pass A+B+C: writes the editable specs/proposed-inventory.md and the
+              machine map onboard reads; prints {strategy, strategy_options,
+              forced_option, feature/context/aggregate/operation/wave counts,
+              contexts_ordered, coverage_pct, …}. --strategy is the operator's request:
+              its first word forces a strategy when it names one
+  apply    [--root <dir>] [--proposal <md>] [--map <json>]
+           -> validates the operator's edits to the proposal and regenerates the
+              machine map; prints its counts and contexts_ordered, or the rows it
+              cannot resolve in {problems}
+  context-state [--root <dir>] [--context <Name>] [--map <json>] [--bundle <dir>]
+           -> what onboard needs before touching one bounded context (default: the
+              first not yet onboarded): its features and aggregates, whether it is
+              onboarded already, and the contexts it waits on {blocked_by, …}
+  scaffold-context --context <Name> [--root <dir>] [--map <json>]
+           -> creates specs/<Context>/<Feature>/ for every feature the map assigns to
+              that context — directories only, no documents
   concept  --bundle <dir> --aggregate <name>
            -> resolves ONE aggregate's OKF concept + source_files (the code that
               IS the slice) — the index adopt reverse-engineers a feature from
-  list-aggregates --bundle <dir>
-           -> enumerates the bundle's Aggregate concepts (the brownfield feature
-              map) → {aggregates[{name,title,slug,concept_path,...}], count} — the
-              selectable feature list select-feature offers in a brownfield repo
+  list-aggregates --bundle <dir> [--context <Name>] [--root <dir>] [--map <json>]
+           -> enumerates the bundle's Aggregate concepts, each offered as the
+              features the map puts on it → {aggregates[{name,title,slug,
+              concept_path,...}], count} — the selectable feature list
+              select-feature offers in a brownfield repo
   validate --bundle <dir> [--repo-root <dir>]
            -> runs the OKF v0.1 conformance checker (validate_okf.py, beside
               this file) and re-emits {concepts, errors[], warnings[], result,
               conformant}
 
-Usage: aw-inventory.py <scan|concept|list-aggregates|validate> [options]
+Usage: aw-inventory.py <scan|propose|apply|context-state|scaffold-context|concept|
+                        list-aggregates|validate> [options]
 """
 
 import argparse
@@ -347,15 +368,22 @@ def frontend_signals(files, churn_map):
 
 # Directory / filename hints that a file participates in a domain aggregate.
 DOMAIN_DIR_RE = re.compile(r"(^|/)(domain|aggregates?|entit(y|ies)|models?)(/|$)", re.IGNORECASE)
-# Layer folders inside a vertical slice. The PARENT of any of these is an
+# Layer folders inside a module. The PARENT of any of these is an
 # aggregate-module candidate (e.g. .../MedicinalProducts/Domain/... -> the
-# aggregate module is MedicinalProducts). This mirrors the aw-spec
-# MinimalMonolith vertical-slice layout and is the strongest, lowest-noise
-# aggregate signal — far better than clustering on file basenames.
+# aggregate module is MedicinalProducts). The words are each stack's own names
+# for a layer: the vertical-slice layout the kit generates, n-tier and clean
+# architecture, Go's http/transport/delivery, hexagonal adapters and ports
+# (inbound/outbound), and the rest/grpc/graphql/routes/routers/schemas folders
+# an API keeps. Words that are as often a project, UI or container folder (web,
+# views, services, resources) are not layers here: they would split a module.
+# This is the strongest, lowest-noise aggregate signal — far better than
+# clustering on file basenames.
 LAYER_DIR_RE = re.compile(
     r"^(domain|features?|application|use[-_]?cases?|handlers?|persistence|"
     r"infrastructure|infra|data|repositor(y|ies)|api|endpoints?|controllers?|"
-    r"aggregates?|entit(y|ies)|models?|dtos?|contracts?)$",
+    r"aggregates?|entit(y|ies)|models?|dtos?|contracts?|"
+    r"http|transport|delivery|rest|grpc|graphql|routes|routers?|schemas|"
+    r"adapters?|ports?|inbound|outbound)$",
     re.IGNORECASE,
 )
 # Which bucket a layer folder maps to, for grouping a candidate's files.
@@ -371,7 +399,16 @@ LAYER_KIND = {
     "api": "api", "endpoint": "api", "endpoints": "api",
     "controller": "api", "controllers": "api",
     "dto": "api", "dtos": "api", "contract": "api", "contracts": "api",
+    "http": "api", "transport": "api", "delivery": "api", "rest": "api",
+    "grpc": "api", "graphql": "api", "routes": "api", "router": "api",
+    "routers": "api", "schemas": "api", "inbound": "api",
+    "adapter": "infra", "adapters": "infra", "outbound": "infra",
+    "port": "feature", "ports": "feature",
 }
+# Hexagonal edge folders. They bound a module like any layer, but say only that a
+# file sits on the edge, not what it does: the next layer folder below one names the
+# file's bucket (adapter/in/controller -> api, adapter/out/persistence -> infra).
+EDGE_LAYER_NAMES = frozenset(("adapter", "adapters", "port", "ports"))
 # Type-role suffixes stripped to recover the underlying aggregate/entity noun
 # (used only for the secondary within-aggregate "entities" hint, and for the
 # flat-repo fallback when there are no layer folders).
@@ -381,11 +418,12 @@ ROLE_SUFFIX_RE = re.compile(
     r"Factory|Spec|Specification|View)$"
 )
 # Verb prefixes on CQRS command/use-case names, stripped so RegisterMedicinal…
-# resolves toward its aggregate rather than becoming its own candidate.
+# resolves toward its aggregate rather than becoming its own candidate. Only a whole
+# PascalCase word is a verb: Address, Settings and Listing are nouns.
 VERB_PREFIX_RE = re.compile(
     r"^(Register|Create|Add|Update|Modify|Change|Delete|Remove|Get|List|Find|"
     r"Fetch|Set|Assign|Approve|Reject|Cancel|Submit|Publish|Archive|Restore|"
-    r"Enable|Disable|Activate|Deactivate|Send|Generate)"
+    r"Enable|Disable|Activate|Deactivate|Send|Generate)(?=[A-Z])"
 )
 CODE_EXT_RE = re.compile(r"\.(py|js|ts|go|rs|rb|java|cs|php|kt|scala|sql|prisma)$", re.IGNORECASE)
 
@@ -491,9 +529,10 @@ def kit_excludes(root):
 
     `guardrails/` and `foundations/` are ordinary names a project may use for its own
     code, so each is excluded only when it has the kit's shape: `guardrails/` holding
-    one of the kit's rule tiers, `foundations/` holding a scaffold pack (a directory with
-    a `*.pack.txt`). The agent directories and agent instruction files are excluded
-    whenever present."""
+    one of the kit's rule tiers, `foundations/` holding what the kit puts there — a
+    scaffold pack (`*.pack.txt`), a spec foundation (`*.spec.txt`), a component runbook
+    (`<ecosystem>/components/<Name>/integration.md`) or the spec template at its root.
+    The agent directories and agent instruction files are excluded whenever present."""
     names = [d for d in KIT_AGENT_DIRS if os.path.isdir(os.path.join(root, d))]
     g = os.path.join(root, "guardrails")
     if any(os.path.isdir(os.path.join(g, t)) for t in ("project-specific", "technology", "domain")):
@@ -501,9 +540,12 @@ def kit_excludes(root):
     f = os.path.join(root, "foundations")
     if os.path.isdir(f):
         for dirpath, dirnames, filenames in os.walk(f):
-            if dirpath[len(f):].count(os.sep) >= 3:
+            rel = os.path.relpath(dirpath, f).split(os.sep)
+            if len(rel) >= 3:
                 dirnames[:] = []
-            if any(n.endswith(".pack.txt") for n in filenames):
+            if (any(n.endswith((".pack.txt", ".spec.txt")) for n in filenames)
+                    or (dirpath == f and "foundation.spec.template.txt" in filenames)
+                    or (len(rel) == 3 and rel[1] == "components" and "integration.md" in filenames)):
                 names.append("foundations")
                 break
     rxs = [re.compile("^" + re.escape(n) + "/") for n in names]
@@ -658,17 +700,33 @@ def matching(files, rx):
     return [f for f in files if rx.search(f)]
 
 
+# File names that say what a file is to the program, not which noun it serves: an entry
+# point or a module's wiring. Compared lower-case, before any suffix is stripped. Each is
+# also a noun some domain uses (a university's Program, a loan Application), so a file in
+# a domain layer folder keeps its name.
+ENTRY_POINT_NAMES = frozenset((
+    "main", "__main__", "index", "app", "application", "server", "program", "startup",
+    "bootstrap", "init", "__init__", "mod", "lib", "setup", "wsgi", "asgi", "manage", "urls",
+))
+
+
 def _entity_noun(path):
-    """Recover the domain noun from a file basename (role suffixes + a CQRS verb
-    prefix stripped): RegisterMedicinalProductCommandHandler -> MedicinalProduct.
-    Signal-grade; returns None for non-nouny names."""
-    base = os.path.splitext(os.path.basename(path))[0]
-    base = re.split(r"[._-]", base)[0]
+    """Recover the domain noun from a file basename, in PascalCase and singular: the name
+    up to its first dot, its snake_case or kebab-case words joined, then an interface's
+    leading I, role suffixes and a CQRS verb prefix stripped. medication_order.py and
+    medication-orders.routes.ts give MedicationOrder, IPatientRepository.cs gives Patient,
+    RegisterMedicinalProductCommandHandler.cs gives MedicinalProduct.
+    Signal-grade; returns None for an entry point outside a domain layer and for
+    non-nouny names."""
+    stem = os.path.splitext(os.path.basename(path))[0].split(".")[0]
+    if stem.lower() in ENTRY_POINT_NAMES and _bucket_of(path.split("/")[:-1], "") != "domain":
+        return None
+    base = re.sub(r"^I(?=[A-Z][a-z])", "", _pascal(stem))
     prev = None
     while prev != base:
         prev = base
         base = ROLE_SUFFIX_RE.sub("", base)
-    base = VERB_PREFIX_RE.sub("", base)
+    base = singularize(VERB_PREFIX_RE.sub("", base))
     return base if base and base[:1].isalpha() and len(base) > 2 else None
 
 
@@ -704,6 +762,10 @@ DOTTED_SEG_RE = re.compile(r"^[A-Za-z_]\w*(\.[A-Za-z_]\w*)+$")
 # Organisation/product prefixes that lead a dotted project name without naming
 # a module. Dropped from the left before the module segment is read.
 VENDOR_PREFIX_RE = re.compile(r"^(com|org|net|io|co|inc|ltd)$", re.IGNORECASE)
+# Source folders whose code sits in a package path that starts with a reverse domain
+# (src/main/java/com/acme/clinic/). Below one, a vendor folder and the folders that only
+# lead from it to the base package name the organisation and the product, never a module.
+JVM_SOURCE_DIRS = frozenset(("java", "kotlin", "scala", "groovy"))
 
 
 # Folders that hold ONE vertical slice per child. These are also members of
@@ -743,6 +805,21 @@ PROJECT_ROLE_RE = re.compile(
 )
 
 
+# Folders too generic to bound a module alone — web/ is as often a project or a UI, every
+# project has a services/ — that ARE a layer beside a domain layer: care/{domain,web} is
+# one module's two layers, and io/clinic/{domain,web} one application's.
+PAIRED_LAYER_KIND = {"web": "api", "service": "feature", "services": "feature"}
+
+
+def _paired_layer(parent, seg, children):
+    """The layer bucket a generic folder names where a sibling folder is a domain layer,
+    else None. `parent` is the folder holding `seg`."""
+    kind = PAIRED_LAYER_KIND.get((seg or "").lower())
+    if kind and any(_layer_of(c) == "domain" for c in children.get(parent, ())):
+        return kind
+    return None
+
+
 def _layer_of(seg, soft=False):
     """The layer bucket a path segment names, or None when it names no layer.
 
@@ -754,6 +831,18 @@ def _layer_of(seg, soft=False):
     return SOFT_LAYER_KIND.get(s) if soft else None
 
 
+def _bucket_of(dirs, default, soft=True):
+    """The bucket of the first layer folder in `dirs`, else `default`. A hexagonal edge
+    folder defers to the next layer folder below it."""
+    for i, p in enumerate(dirs):
+        kind = _layer_of(p, soft=soft)
+        if kind:
+            if p.lower() in EDGE_LAYER_NAMES:
+                return _bucket_of(dirs[i + 1:], kind, soft)
+            return kind
+    return default
+
+
 def _project_roots(files):
     """Directories a build manifest calls a project. This is the one module
     boundary in a repo that is EVIDENCED rather than inferred from a folder
@@ -832,7 +921,8 @@ def _child_dirs(files):
 
 def _holds_layers(path, children):
     """Whether a directory holds a domain layer plus at least one other layer folder."""
-    kinds = {_layer_of(c) for c in children.get(path, set())} - {None}
+    kinds = {_layer_of(c) or _paired_layer(path, c, children)
+             for c in children.get(path, set())} - {None}
     return "domain" in kinds and len(kinds) >= 2
 
 
@@ -885,9 +975,56 @@ def _is_module_layer(dirs, i, children):
                    for g in children.get(f"{here}/{c}", set()))
 
 
+def _noun_words(path):
+    """A file name's words, each singular: AppointmentsApiController -> Appointment, Api,
+    Controller. The name is read up to its first dot, an interface's leading I dropped."""
+    stem = os.path.basename(path).split(".")[0]
+    name = re.sub(r"^I(?=[A-Z][a-z])", "", _pascal(stem))
+    return [singularize(w) for w in re.findall(r"[A-Z][a-z0-9]*|[A-Z]+(?![a-z])", name)]
+
+
+def _anchored_noun(path, domain_nouns, fallback=True):
+    """The domain noun a file serves in a tree read by noun: the longest noun of the
+    domain layer whose words run together in the file's name (RecordEncounterUseCase,
+    EncounterJpaRepository -> Encounter), else — with `fallback` — the file's own noun."""
+    words = _noun_words(path)
+    hits = [noun for noun, nw in domain_nouns.items()
+            if any(words[i:i + len(nw)] == nw for i in range(len(words) - len(nw) + 1))]
+    if hits:
+        return max(hits, key=lambda n: (len(domain_nouns[n]), len(n), n))
+    return _entity_noun(path) if fallback else None
+
+
+def _app_roots(files, proj_roots):
+    """Folders that hold an application: its entry point, or the build manifest of the
+    lane's only project. A manifest beside others marks a component, which is a module."""
+    entry = {f.rsplit("/", 1)[0] for f in files if "/" in f
+             and os.path.basename(f).split(".")[0].lower() in ENTRY_POINT_NAMES}
+    return entry | (set(proj_roots) if len(proj_roots) == 1 else set())
+
+
+def _is_app_root(dirs, j, children, app_roots):
+    """Whether dirs[:j+1] is the APPLICATION rather than one module of it: an app root
+    (_app_roots) that is no test, sample or demo code, with no sibling folder holding
+    layers of its own. Its layer folders are then the app's top level — a layer-first
+    tree, read by noun."""
+    path = "/".join(dirs[:j + 1])
+    if path not in app_roots or TEST_PATH_RE.search(path):
+        return False
+    parent = "/".join(dirs[:j])
+    return not any(_layer_of(g)
+                   for s in children.get(parent, set()) if s != dirs[j]
+                   for g in children.get(f"{parent}/{s}" if parent else s, set()))
+
+
 # How much a rule's naming is trusted when two rules land files in one group.
 AXIS_RANK = {"slice-major": 0, "project-major": 1, "module-major": 2,
              "layer-major": 3, "project-root": 4, "flat": 5}
+# Folders that hold code every module shares — never a module of their own. Compared
+# with case and separators removed. `core` is left out: it is often a real context.
+SHARED_CODE_NAMES = frozenset((
+    "shared", "common", "commons", "kernel", "sharedkernel", "buildingblock",
+    "buildingblocks", "crosscutting"))
 
 
 def _structure_rows(files):
@@ -912,13 +1049,24 @@ def _structure_rows(files):
     proj_roots = _project_roots(files)
     product = _product_prefix(files)
     children = _child_dirs(files)
+    app_roots = _app_roots(files, proj_roots)
+    domain_nouns = {}
+    for f in files:
+        dirs = f.split("/")[:-1]
+        if TEST_PATH_RE.search(f) or not (
+                _bucket_of(dirs, "") == "domain"
+                or any(_dotted_module(d)[1] == "domain" for d in dirs)):
+            continue
+        n = _entity_noun(f)
+        if n:
+            domain_nouns[n] = _noun_words(n)
 
     for f in files:
         parts = f.split("/")
         if len(parts) < 2:
             continue
         dirs = parts[:-1]
-        hit = None
+        hit, unplaced = None, False
 
         # slice-major — a slice container names the module in its CHILD, unless the
         # container is itself one LAYER of a module (see _is_module_layer), in which
@@ -929,14 +1077,13 @@ def _structure_rows(files):
             if _is_module_layer(dirs, i, children):
                 parent = dirs[i - 1]
                 name = (_clean_project_name(parent, product)
-                        if DOTTED_SEG_RE.match(parent) else singularize(parent) or parent)
+                        if DOTTED_SEG_RE.match(parent) else _pascal(singularize(parent) or parent))
                 hit = ("/".join(dirs[:i]), name, "feature", "module-major")
                 break
             nxt = dirs[i + 1] if i + 1 < len(dirs) else ""
             if nxt and not _layer_of(nxt) and not SLICE_CONTAINER_RE.match(nxt):
-                kind = next((_layer_of(p, soft=True) for p in dirs[i + 2:]
-                             if _layer_of(p, soft=True)), "feature")
-                name = singularize(nxt) or nxt
+                kind = _bucket_of(dirs[i + 2:], "feature")
+                name = _pascal(singularize(nxt) or nxt)
                 hit = ("/".join(dirs[:i + 2]), name, kind, "slice-major")
             break
 
@@ -951,19 +1098,31 @@ def _structure_rows(files):
         # module-major / layer-major — a layer FOLDER, read through its parent.
         if not hit:
             for i, seg in enumerate(dirs):
-                kind = _layer_of(seg)
+                kind = _layer_of(seg) or _paired_layer("/".join(dirs[:i]), seg, children)
                 if not kind:
                     continue
+                kind = _bucket_of(dirs[i:], kind, soft=False)
                 parent = dirs[i - 1] if i else ""
-                if i and (not CONTAINER_DIR_RE.match(parent) or _is_module_dir(dirs, i - 1, children)):
+                if i and (not CONTAINER_DIR_RE.match(parent) or _is_module_dir(dirs, i - 1, children)) \
+                        and not _is_app_root(dirs, i - 1, children, app_roots):
                     name = (_clean_project_name(parent, product)
-                            if DOTTED_SEG_RE.match(parent) else singularize(parent) or parent)
+                            if DOTTED_SEG_RE.match(parent) else _pascal(singularize(parent) or parent))
                     hit = ("/".join(dirs[:i]), name, kind, "module-major")
                 else:
-                    noun = _entity_noun(f)
+                    # Where the domain layer names the nouns, an infrastructure or unbucketed
+                    # file naming none of them (a DbContext, an interceptor, a helper) serves
+                    # every aggregate rather than being one, and stays unplaced. A controller,
+                    # handler or use case keeps its own noun, so its operations keep an
+                    # aggregate (ReportsController -> Report).
+                    hosting = bool(domain_nouns) and kind in ("infra", "other")
+                    noun = _anchored_noun(f, domain_nouns, fallback=not hosting)
                     if noun:
                         hit = ("/".join(dirs[:i] + [noun]), noun, kind, "layer-major")
+                    elif hosting:
+                        unplaced = True
                 break
+        if unplaced:
+            continue
 
         # A MODULE folder owns everything beneath it, whatever its sub-folders are called.
         # The layer vocabulary names the folders that bound a module; a module's own
@@ -972,12 +1131,11 @@ def _structure_rows(files):
         # module SHAPE wins (see _is_module_dir), so a layer-major src/ is never one.
         if not hit:
             for j in range(len(dirs) - 1, -1, -1):
-                if _is_module_dir(dirs, j, children):
+                if _is_module_dir(dirs, j, children) and not _is_app_root(dirs, j, children, app_roots):
                     parent = dirs[j]
                     name = (_clean_project_name(parent, product)
-                            if DOTTED_SEG_RE.match(parent) else singularize(parent) or parent)
-                    kind = next((_layer_of(p, soft=True) for p in dirs[j + 1:]
-                                 if _layer_of(p, soft=True)), "other")
+                            if DOTTED_SEG_RE.match(parent) else _pascal(singularize(parent) or parent))
+                    kind = _bucket_of(dirs[j + 1:], "other")
                     hit = ("/".join(dirs[:j + 1]), name, kind, "module-major")
                     break
 
@@ -989,8 +1147,7 @@ def _structure_rows(files):
                 if DOTTED_SEG_RE.match(seg):
                     name = _clean_project_name(seg, product)
                     if name:
-                        kind = next((_layer_of(p, soft=True) for p in dirs[i + 1:]
-                                     if _layer_of(p, soft=True)), "other")
+                        kind = _bucket_of(dirs[i + 1:], "other")
                         hit = ("/".join(dirs[:i] + [name]), name, kind, "project-major")
                     break
 
@@ -999,8 +1156,7 @@ def _structure_rows(files):
             for i in range(len(dirs), 0, -1):
                 d = "/".join(dirs[:i])
                 if d in proj_roots:
-                    kind = next((_layer_of(p, soft=True) for p in dirs[i:]
-                                 if _layer_of(p, soft=True)), "other")
+                    kind = _bucket_of(dirs[i:], "other")
                     hit = (d, _clean_project_name(dirs[i - 1], product), kind, "project-root")
                     break
 
@@ -1095,12 +1251,9 @@ def _finish_candidates(cands, churn_map, strategy, min_files=1):
     return out
 
 
-def strategy_structure(root, files, churn_map, graph=None):
-    """S1 — cluster on the repo's own organising axis.
-
-    Always available: every repo has a layout. Where no layer vocabulary appears
-    at all, the noun fallback still clusters the domain/route/api files on their
-    basename, so a flat repo is not a zero-candidate repo."""
+def _structure_groups(files, churn_map):
+    """The groups _structure_rows draws, as candidates keyed by group, and how many files
+    each axis placed."""
     cands, axes, naming = {}, {}, {}
     for key, name, kind, f, axis in _structure_rows(files):
         axes[axis] = axes.get(axis, 0) + 1
@@ -1117,6 +1270,41 @@ def strategy_structure(root, files, churn_map, graph=None):
             n = _entity_noun(f)
             if n:
                 c["entities"].add(n)
+    return cands, axes
+
+
+def _hosting_keys(groups):
+    """The groups that are no module and stay unplaced, as the domain strategy leaves them:
+    a shared-code folder (shared/, common/, a shared kernel), and a project root that holds
+    modules of its own — its manifest, entry point and loose helpers are the host of those
+    modules, not one more. Shared code is set aside first, so a project root holding only a
+    shared folder is the module, and stays."""
+    shared = {k for k, c in groups.items()
+              if {_ui_norm(k.rsplit("/", 1)[-1]), _ui_norm(c["name"])} & SHARED_CODE_NAMES}
+    rest = [k for k in groups if k not in shared]
+    return shared | {k for k in rest if groups[k].get("axis") == "project-root"
+                     and any(o != k and o.startswith(k + "/") for o in rest)}
+
+
+def _hosting_files(files):
+    """The files of the _hosting_keys groups: what `structure` leaves unplaced."""
+    groups, _axes = _structure_groups(files, {})
+    return {f for k in _hosting_keys(groups) for lk in LAYER_KEYS for f in groups[k][lk]}
+
+
+def strategy_structure(root, files, churn_map, graph=None, name_only=False):
+    """S1 — cluster on the repo's own organising axis.
+
+    Always available: every repo has a layout. Where no layer vocabulary appears
+    at all, the noun fallback still clusters the domain/route/api files on their
+    basename, so a flat repo is not a zero-candidate repo.
+
+    `name_only` is the call S2 and S3 make to name their clusters: every group is kept,
+    shared code and a module-holding project root included, so each file has a name."""
+    cands, axes = _structure_groups(files, churn_map)
+    if not name_only:
+        for key in _hosting_keys(cands):
+            del cands[key]
 
     if not cands:
         for f in (matching(files, DB_FILES_RE) + [x for x in files if DOMAIN_DIR_RE.search(x)]
@@ -1320,7 +1508,7 @@ def strategy_reference(root, files, churn_map, graph=None):
     high-fan-in cluster it is. Clusters arrive UNNAMED — S1 names them, which is
     why it is the layer underneath rather than a competing option."""
     graph = graph if graph is not None else build_reference_graph(root, files)[0]
-    named = strategy_structure(root, files, churn_map)
+    named = strategy_structure(root, files, churn_map, name_only=True)
     owner = _candidate_of_file(named)
 
     # In-degree first: the files everything imports are the shared kernel, and
@@ -1382,8 +1570,7 @@ def strategy_reference(root, files, churn_map, graph=None):
         key = os.path.commonprefix([os.path.dirname(f) + "/" for f in group]).rstrip("/")
         c = cands.setdefault(name.lower(), _blank_candidate(key, name))
         for f in group:
-            kind = next((_layer_of(p, soft=True) for p in f.split("/")[:-1]
-                         if _layer_of(p, soft=True)), "other")
+            kind = _bucket_of(f.split("/")[:-1], "other")
             c[kind + "_files"].append(f)
             c["churn"] += churn_map.get(f, 0)
             if kind == "domain":
@@ -1392,12 +1579,15 @@ def strategy_reference(root, files, churn_map, graph=None):
                     c["entities"].add(n)
 
     # Files no import touches are still part of the repo; S1 places them so the
-    # strategy's coverage is comparable with the others'.
+    # strategy's coverage is comparable with the others'. What S1 itself leaves unplaced
+    # (_hosting_keys: shared code, a module-holding project root's manifest and entry
+    # point) stays unplaced here too, rather than becoming a cluster named after its folder.
     placed = {f for grp in clusters.values() for f in grp}
+    hosting = _hosting_files(files)
     for c in named:
         for k in LAYER_KEYS:
             for f in c[k]:
-                if f not in placed:
+                if f not in placed and f not in hosting:
                     tgt = cands.setdefault(c["name"].lower(), _blank_candidate(c["module_dir"], c["name"]))
                     tgt[k].append(f)
     return _finish_candidates(cands, churn_map, "reference")
@@ -1611,7 +1801,7 @@ def strategy_persistence(root, files, churn_map, graph=None):
     owned = {t for e in ents.values() for t in e["owns"] if t in ents}
     roots = [n for n in sorted(ents) if n not in owned]
 
-    named = strategy_structure(root, files, churn_map)
+    named = strategy_structure(root, files, churn_map, name_only=True)
     owner = _candidate_of_file(named)
     cands = {}
     for r in roots:
@@ -1633,8 +1823,7 @@ def strategy_persistence(root, files, churn_map, graph=None):
                                         if t in ents and t not in closure})
         c["confidence"] = "high"
         for f in sorted(member_files):
-            kind = next((_layer_of(p, soft=True) for p in f.split("/")[:-1]
-                         if _layer_of(p, soft=True)), "domain")
+            kind = _bucket_of(f.split("/")[:-1], "domain")
             c[kind + "_files"].append(f)
             c["churn"] += churn_map.get(f, 0)
 
@@ -1669,12 +1858,22 @@ def strategy_persistence(root, files, churn_map, graph=None):
 # and its only trace in code is the UI lane's features/<Feature>/ folder (see
 # ui_features) — which is why features are proposed in Pass C, not found in Pass A.
 
-AGG_ROOT_MARKER_RE = re.compile(r"\b(?:I?AggregateRoot\w*|AbstractAggregateRoot)\b")
-AGG_ROOT_ANNOTATION_RE = re.compile(r"@AggregateRoot\b")
+# Any base type whose name carries AggregateRoot — AggregateRoot<T>, IAggregateRoot,
+# AbstractAggregateRoot, BaseAggregateRoot, AggregateRootBase: no stack's rules fix what
+# the abstraction is called. The marker annotation may be written fully qualified.
+AGG_ROOT_MARKER_RE = re.compile(r"\b\w*AggregateRoot\w*\b")
+AGG_ROOT_ANNOTATION_RE = re.compile(r"@(?:[\w.]+\.)?AggregateRoot\b")
 ENTITY_MARKER_RE = re.compile(r"\b(?:I?Entity(?:Base)?|IAggregateChild|BaseEntity)\b")
 # Upper-case names only: every supported language names its types that way, and prose
 # does not — "this record avoids…" in a doc comment would otherwise declare `avoids`.
 TYPE_DECL_RE = re.compile(r"\b(class|record|struct|interface|enum)\s+([A-Z]\w*)")
+# Go: `type Name struct {…}`, `type Name interface {…}`, `type Name <type>`, each alone or
+# in a grouped `type ( … )` block, type parameters allowed. A struct says what it IS by
+# the types it embeds — a field with no name — where other languages use a base list.
+GO_TYPE_RE = re.compile(r"^[ \t]*type\b[ \t]*(\()?", re.M)
+GO_TYPE_SPEC_RE = re.compile(
+    r"[ \t]*([A-Z]\w*)(?:\[[^\]\n]*\])?[ \t]*(?:=[ \t]*)?(?:(struct|interface)(?!\w))?")
+GO_EMBED_RE = re.compile(r"[ \t]*\*?(?:\w+\.)?([A-Za-z_]\w*)(?:\[[^\]\n]*\])?[ \t]*(?:`[^`\n]*`)?[ \t]*$")
 C_COMMENT_RE = re.compile(r"/\*.*?\*/|//[^\n]*", re.S)
 
 
@@ -1691,7 +1890,9 @@ TEST_PATH_RE = re.compile(
     r"(^|/)(tests?|__tests__|samples?|examples?|demos?|"
     r"[^/]*\.(?:Unit|Integration|Functional|Acceptance)?Tests?)(/|$)",
     re.IGNORECASE)
-HANDLER_CLASS_RE = re.compile(r"\bclass\s+([A-Za-z_]\w*?)(Command|Query)Handler\b")
+# A handler class, or a Go struct named the same way.
+HANDLER_CLASS_RE = re.compile(
+    r"\b(?:class|type(?=\s+\w+Handler\s+struct\b))\s+([A-Za-z_]\w*?)(Command|Query)Handler\b")
 QUERY_NAME_RE = re.compile(r"^(Get|List|Find|Search|Fetch|Query|Read|Lookup|Count|Export|Browse)[A-Z]")
 CREATE_NAME_RE = re.compile(r"^(Create|Register|Record|Start|Open|New|Add|Submit|Place|Book|Schedule)")
 IDENT_RE = re.compile(r"[A-Za-z_]\w*")
@@ -1720,6 +1921,49 @@ def _type_header(body, end):
     return header
 
 
+def _go_lines(body, a, z):
+    """(offset, line) for each line of body[a:z] that starts outside every brace opened
+    in that span — a grouped block's declarations, a struct's own fields."""
+    depth, i = 0, a
+    while i < z:
+        j = body.find("\n", i, z)
+        j = z if j == -1 else j
+        line = body[i:j]
+        if depth == 0:
+            yield i, line
+        depth += line.count("{") - line.count("}")
+        i = j + 1
+
+
+def _type_decls(path, body):
+    """Every type a file declares, as (kind, name, header, start, end): `header` is what
+    the declaration says the type IS (see _type_header) and `end` where its body is
+    looked for. A Go struct's header is the types it embeds, its fields read at its own
+    level; a Go type that is neither a struct nor an interface has kind `type`."""
+    if _lang_of(path) != "go":
+        for m in TYPE_DECL_RE.finditer(body):
+            yield m.group(1), m.group(2), _type_header(body, m.end()), m.start(), m.end()
+        return
+    for m in GO_TYPE_RE.finditer(body):
+        if m.group(1):
+            close = _close_bracket(body, m.end() - 1)
+            specs = [i for i, ln in _go_lines(body, m.end(), close) if ln.strip()]
+        else:
+            specs = [m.end()]
+        for at in specs:
+            s = GO_TYPE_SPEC_RE.match(body, at)
+            if not s:
+                continue
+            header = ""
+            if s.group(2) == "struct":
+                brace = body.find("{", s.end())
+                if brace != -1 and not body[s.end():brace].strip():
+                    header = " ".join(e.group(1) for _i, ln in _go_lines(
+                        body, brace + 1, _close_bracket(body, brace))
+                        for e in [GO_EMBED_RE.fullmatch(ln)] if e)
+            yield s.group(2) or "type", s.group(1), header, at, s.end()
+
+
 def _type_role(kind, name, header, path, pre):
     """What a declared type is in the domain model: root, entity, value, event, spec,
     enum or contract. Read from its declaration, never from its folder alone."""
@@ -1867,6 +2111,835 @@ def _attribute_leftovers(modules, module_of, text, types, decl_of, refs, owner,
             owner[f] = o
 
 
+# ═══════════════════════════════════════════════════════════════════════════
+# Operations the code PUBLISHES — endpoints and use cases, in any stack.
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# A slice folder and a CQRS handler class are two ways code writes an operation down.
+# Two more are read here, the same way whatever the language:
+#
+#   ENDPOINT  a route declaration that names its HTTP verb: an attribute ([HttpPost]),
+#             an annotation (@PostMapping, JAX-RS @POST, NestJS @Post()), a decorator
+#             (@router.post, @app.route(methods=…)) or a router call (router.post("/x",
+#             h), r.Post("/x", h), app.MapPost("/x", …), mux.HandleFunc("POST /x", h)).
+#             A controller with no route declaration at all is read by convention, one
+#             endpoint per public action. Endpoints that resolve to one name — an MVC
+#             Create's GET form and its POST submit — are one operation.
+#   USE CASE  an application-layer type named for one thing the system does
+#             (RecordEncounterUseCase, PlaceOrderInteractor) that declares one public
+#             operation. A type declaring several is a service, not an operation: the
+#             endpoints calling it are the operations.
+#
+# An endpoint is NAMED by the operation id the code publishes for it — the name the API
+# document carries and the frontend lane binds to — else by the operation it invokes (a
+# use case, command or handler found already), else by its handler's own name with the
+# resource noun added where the handler name lacks it (EncounterController.record →
+# RecordEncounter). An endpoint that invokes a known operation IS that operation: it adds
+# its routes and its controller to it rather than standing beside it.
+#
+# Routes are JOINED the way the framework joins them: a class-level prefix
+# (@RequestMapping, @Path, [Route], [RoutePrefix], @Controller), a router value made with
+# one (Group, MapGroup, APIRouter(prefix=), Blueprint(url_prefix=), new Router({prefix}),
+# a same-file app.use("/x", router)), or a routing block (r.Route("/x", func…)).
+
+# Declarations that sit on the method or function they route: (languages, pattern, role).
+ANNOT_DECLS = (
+    ({"java", "kt"}, re.compile(r"@(Get|Post|Put|Patch|Delete)Mapping\b(?:\s*\(([^)]*)\))?"), "verb"),
+    ({"java", "kt"}, re.compile(r"@RequestMapping\b(?:\s*\(([^)]*)\))?"), "request"),
+    ({"java", "kt"}, re.compile(r"@(GET|POST|PUT|PATCH|DELETE)\b(?!\s*\()"), "jaxrs"),
+    ({"java", "kt"}, re.compile(r"@Path\s*\(([^)]*)\)"), "path"),
+    ({"cs"}, re.compile(r"[\[,]\s*Http(Get|Post|Put|Patch|Delete)(?:Attribute)?\b(?:\s*\(([^)]*)\))?"), "verb"),
+    ({"cs"}, re.compile(r"[\[,]\s*(?:Route|RoutePrefix)(?:Attribute)?\s*\(([^)]*)\)"), "path"),
+    ({"js"}, re.compile(r"@(Get|Post|Put|Patch|Delete)\s*\(([^)]*)\)"), "verb"),
+    ({"js"}, re.compile(r"@Controller\s*\(([^)]*)\)"), "path"),
+    ({"py"}, re.compile(r"@\s*(\w+)\.(get|post|put|patch|delete)\s*\(([^)]*)\)"), "pyverb"),
+    ({"py"}, re.compile(r"@\s*(\w+)\.(?:route|api_route)\s*\(([^)]*)\)"), "pyroute"),
+)
+# Declarations that are calls on a router value, the handler passed as an argument.
+CALL_DECLS = (
+    ({"cs"}, re.compile(r"(?:\b(\w+)\s*\.\s*)?\bMap(Get|Post|Put|Patch|Delete)\s*\(\s*\"([^\"]*)\""), "map"),
+    ({"cs"}, re.compile(r"(?<![\w.])(Get|Post|Put|Patch|Delete)\s*\(\s*\"(/[^\"]*)\"\s*\)"), "fastendpoints"),
+    ({"js", "go"}, re.compile(r"\b(\w+)\s*\.\s*(get|post|put|patch|delete|Get|Post|Put|Patch|Delete|"
+                              r"GET|POST|PUT|PATCH|DELETE)\s*\(\s*([\"'`])(/[^\"'`\n]*|)\3\s*,"), "router"),
+    ({"go"}, re.compile(r"\b(\w+)\s*\.\s*Handle(?:Func)?\s*\(\s*\"(?:(GET|POST|PUT|PATCH|DELETE)\s+)?"
+                        r"(/[^\"]*)\"\s*,"), "mux"),
+)
+# A router call's receiver that is an HTTP CLIENT or a request/response value, never a
+# router: axios.post("/x", body) sends a request, it does not serve one.
+CLIENT_RECV_RE = re.compile(
+    r"^(?:https?|axios|fetch|got|ky|superagent|requests?|httpx|session|req|res|ctx|"
+    r"\w*client|resttemplate|webclient|map|cache|headers|params|query)$", re.IGNORECASE)
+# Router values created with a prefix: (pattern, groups = var[, parent], path).
+PREFIX_VAR_RES = (
+    ({"go", "cs"}, re.compile(r"\b(\w+)\s*:?=\s*(\w+)\s*\.\s*(?:Group|MapGroup)\s*\(\s*\"([^\"]*)\"")),
+    ({"py"}, re.compile(r"\b(\w+)\s*=\s*APIRouter\s*\([^)]*?\bprefix\s*=\s*[\"']([^\"']*)[\"']")),
+    ({"py"}, re.compile(r"\b(\w+)\s*=\s*Blueprint\s*\([^)]*?\burl_prefix\s*=\s*[\"']([^\"']*)[\"']")),
+    ({"js"}, re.compile(r"\b(\w+)\s*=\s*new\s+Router\s*\(\s*\{[^}]*?\bprefix\s*:\s*[\"'`]([^\"'`]*)[\"'`]")),
+)
+JS_MOUNT_RE = re.compile(r"\b\w+\s*\.\s*use\s*\(\s*([\"'`])(/[^\"'`\n]*)\1\s*,\s*(\w+)\s*\)")
+GO_ROUTE_BLOCK_RE = re.compile(r"\b\w+\s*\.\s*Route\s*\(\s*\"([^\"]*)\"\s*,\s*func\s*\(")
+# The operation id an endpoint publishes, in the dialects that let code set it.
+# The id an endpoint is published under in the API document, as each stack declares it
+# beside the endpoint. Captured verbatim — the contract is checked against this string.
+OPID_RES = (
+    re.compile(r"\boperationId\s*[=:]\s*[\"'`]([\w.\-]+)[\"'`]"),  # springdoc / swagger-core @Operation, NestJS @ApiOperation
+    re.compile(r"\bOperationId\s*=\s*\"([\w.\-]+)\""),              # Swashbuckle [SwaggerOperation]
+    re.compile(r"\boperation_id\s*=\s*[\"']([\w.\-]+)[\"']"),       # FastAPI, drf-spectacular
+    re.compile(r"\.WithName\s*\(\s*\"([\w.\-]+)\"\s*\)"),            # ASP.NET Core minimal APIs
+    re.compile(r"\[EndpointName\s*\(\s*\"([\w.\-]+)\"\s*\)"),        # ASP.NET Core [EndpointName]
+    re.compile(r"@OperationId\s*\(\s*[\"'`]([\w.\-]+)[\"'`]"),      # tsoa
+    re.compile(r"^\s*operationId\s*:\s*[\"']?([\w.\-]+)[\"']?\s*$", re.M),  # YAML in a docstring
+)
+# Function definitions a router call can name as its handler, in the languages whose
+# routers take a function rather than annotate one.
+FUNC_DEF_RES = {
+    "js": (re.compile(r"\bfunction\s+(\w+)\s*\("),
+           re.compile(r"\b(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?"
+                      r"(?:function\b|\([^)]*\)\s*(?::[^=;{]+)?=>|\w+\s*=>)")),
+    "go": (re.compile(r"\bfunc\s+(?:\([^)]*\)\s*)?(\w+)\s*\("),),
+}
+CLASS_DECL_RE = re.compile(r"\bclass\s+([A-Z]\w*)")
+CS_CONTROLLER_BASE_RE = re.compile(r"\b(?:Api)?Controller(?:Base)?\b")
+CS_ACTION_RE = re.compile(
+    r"^[ \t]*public\s+(?!static\b)(?:(?:async|virtual|override|new|sealed)\s+)*"
+    r"(?:Task\s*<\s*)?(?:I?ActionResult(?:\s*<[^>]*>)?|\w*Result|IHttpActionResult|"
+    r"HttpResponseMessage)\s*>?\s+(\w+)\s*\(", re.M)
+USECASE_NAME_RE = re.compile(r"^I?([A-Z]\w*?)(?:UseCase|Interactor)$")
+# A name a variable is declared with, per language family: (pattern, type group, var group).
+VAR_TYPE_RES = {
+    "java": (re.compile(r"\b([A-Z]\w*)(?:\s*<[^<>;()]*>)?\??\s+([a-z_]\w*)\s*[;,)=]"), 1, 2),
+    "js":   (re.compile(r"\b([a-z_]\w*)\s*\??:\s*(?:\w+\.)?([A-Z]\w*)"), 2, 1),
+    "go":   (re.compile(r"\b([a-z_]\w*)\s+\*?(?:\w+\.)?([A-Z]\w*)\b"), 2, 1),
+}
+for _l in ("cs", "scala"):
+    VAR_TYPE_RES[_l] = VAR_TYPE_RES["java"]
+for _l in ("kt", "py"):
+    VAR_TYPE_RES[_l] = VAR_TYPE_RES["js"]
+_HANDLER_SKIP = frozenset((
+    "if", "for", "foreach", "while", "switch", "catch", "return", "new", "typeof", "nameof",
+    "sizeof", "await", "using", "lock", "throw", "function", "def", "func", "fun", "async",
+    "super", "this", "base", "default", "when", "constructor"))
+# Handler names that say nothing about WHAT is done; the verb and the noun name it instead.
+GENERIC_HANDLER = frozenset((
+    "handle", "handler", "handleasync", "execute", "executeasync", "invoke", "call", "run",
+    "process", "serve", "servehttp", "endpoint", "action", "apply"))
+# MVC's conventional action names, read as the operation they stand for.
+MVC_ACTION_ALIAS = {"index": "List", "details": "Get", "detail": "Get", "show": "Get",
+                    "edit": "Update", "new": "Create", "store": "Create", "destroy": "Delete"}
+VERB_WORD = {"POST": "Create", "PUT": "Update", "PATCH": "Update", "DELETE": "Delete"}
+NOUN_ROLE_RE = re.compile(
+    r"(?:RestController|Controller|Resource|Endpoints?|Routes?|Router|Handlers?|Api|Views?|"
+    r"Rest|Service)$")
+NOUN_STOP_WORDS = frozenset((
+    "controller", "controllers", "endpoint", "endpoints", "route", "routes", "router", "routers",
+    "routing", "handler", "handlers", "api", "apis", "rest", "resource", "resources", "view",
+    "views", "urls", "http", "web", "server", "index", "main", "app"))
+
+
+def _close_bracket(body, i):
+    """Index of the bracket closing the one at body[i], or len(body)."""
+    depth = 0
+    for j in range(i, min(len(body), i + 50_000)):
+        ch = body[j]
+        if ch in "([{":
+            depth += 1
+        elif ch in ")]}":
+            depth -= 1
+            if depth == 0:
+                return j
+    return len(body)
+
+
+def _top_args(s):
+    """A call's argument text split at its top-level commas."""
+    out, depth, cur = [], 0, []
+    for ch in s:
+        if ch in "([{":
+            depth += 1
+        elif ch in ")]}":
+            depth -= 1
+        if ch == "," and depth == 0:
+            out.append("".join(cur))
+            cur = []
+        else:
+            cur.append(ch)
+    out.append("".join(cur))
+    return [a.strip() for a in out if a.strip()]
+
+
+def _path_arg(args):
+    """The route template a declaration's arguments carry, or ""."""
+    m = re.search(r"\b(?:value|path)\s*[=:]\s*\{?\s*([\"'`])([^\"'`\n]*)\1", args or "")
+    if m:
+        return m.group(2)
+    m = re.match(r"\s*\{?\s*([\"'`])([^\"'`\n]*)\1", args or "")
+    return m.group(2) if m else ""
+
+
+def _join_route(*parts):
+    segs = [s for p in parts if p for s in p.strip().split("/") if s]
+    return "/" + "/".join(segs)
+
+
+def _handler_after(body, pos):
+    """The method or function an annotation block ending at `pos` sits on."""
+    seg = body[pos:pos + 1500]
+    for m in re.finditer(r"([A-Za-z_]\w*)\s*(?:<[^<>()]*>)?\s*\(", seg):
+        before = seg[:m.start()].rstrip()[-1:]
+        if before in ("@", "[", ",", ".", "(") or m.group(1) in _HANDLER_SKIP:
+            continue
+        return m.group(1)
+    return None
+
+
+def _call_handler(body, open_paren):
+    """The handler a router call is given — its last argument, when that is a name."""
+    args = _top_args(body[open_paren + 1:_close_bracket(body, open_paren)])
+    last = args[-1] if len(args) > 1 else ""
+    if not re.fullmatch(r"[\w.$]+", last):
+        return None
+    segs = last.split(".")
+    if len(segs) > 1 and segs[-1].lower() in GENERIC_HANDLER:
+        return segs[-2]
+    return segs[-1]
+
+
+def _resource_noun(class_name, path, route):
+    """The resource an endpoint serves: its class named for its role, else its file, else
+    the first segment of its route."""
+    base, prev = class_name or "", None
+    while prev != base:      # AppointmentsApiController → Appointments
+        prev, base = base, NOUN_ROLE_RE.sub("", base)
+    if base:
+        return singularize(base)
+    words = [w for w in _name_words(path) if w not in NOUN_STOP_WORDS]
+    if words:
+        return singularize("".join(_pascal_name(w) for w in words))
+    segs = _route_segments(route)
+    return _pascal(singularize(segs[-1] if len(segs) > 1 and segs[-1] else (segs or [""])[0]))
+
+
+def _endpoint_name(handler, noun, routes):
+    """An endpoint's operation name from its handler, the noun added where it is missing:
+    record → RecordEncounter, getById → GetEncounterById, Index → ListPatient."""
+    words = [w[:1].upper() + w[1:]
+             for w in NAME_WORD_RE.findall(re.sub(r"[_\-\s]+", " ", handler or ""))]
+    low = "".join(words).lower()
+    if not words or low in GENERIC_HANDLER:
+        verb = next((v for v, _p in routes if v), "")
+        last = (routes[0][1] if routes else "").rstrip("/").rsplit("/", 1)[-1]
+        words = [VERB_WORD.get(verb) or
+                 ("Get" if last.startswith(("{", ":", "<")) else "List" if verb == "GET" else "Handle")]
+    elif len(words) == 1 and low in MVC_ACTION_ALIAS:
+        words = [MVC_ACTION_ALIAS[low]]
+    name = "".join(words)
+    if noun and _ui_norm(noun) not in _ui_norm(name):
+        name = words[0] + noun + "".join(words[1:])
+    return name
+
+
+def _verb_kind(routes):
+    """query when every verb an operation is served on reads, command when one writes,
+    "" when no route names its verb."""
+    verbs = {v for v, _p in routes if v}
+    return ("query" if verbs == {"GET"} else "command") if verbs else ""
+
+
+def _block_start(lang, body, pos):
+    """Where the annotation block holding the declaration at `pos` begins: just after
+    the previous member ends, or — Python — at the first decorator of the run."""
+    if lang == "py":
+        start = body.rfind("\n", 0, pos) + 1
+        while start > 0:
+            prev = body.rfind("\n", 0, start - 1) + 1
+            if not body[prev:start].strip().startswith("@"):
+                break
+            start = prev
+        return start
+    return max(body.rfind(c, 0, pos) for c in "{};") + 1
+
+
+def _file_endpoints(path, body, mounts=None):
+    """Every endpoint one source file declares:
+    [{"routes": [(VERB, path)], "handler", "opid", "noun", "region", "class"}].
+
+    VERB is "" where the declaration serves any verb. The region is the text that is
+    THIS endpoint's — its annotation block and its handler — so a controller declaring
+    several endpoints is read one endpoint at a time. `mounts` is the prefix each router
+    value is mounted under in ANOTHER file (app.use("/x", encounterRouter))."""
+    lang = _lang_of(path)
+    if not lang or not body:
+        return []
+    decls = []
+    for langs, rx, role in ANNOT_DECLS:
+        if lang not in langs:
+            continue
+        for m in rx.finditer(body):
+            d = {"pos": m.start(), "end": m.end(), "style": "annot", "recv": "", "opid": ""}
+            if role == "verb":
+                args = m.group(2) or ""
+                d.update(verbs=[m.group(1).upper()], path=_path_arg(args))
+                n = re.search(r"\bName\s*=\s*\"([\w.\-]+)\"", args) if lang == "cs" else None
+                d["opid"] = n.group(1) if n else ""
+            elif role == "request":
+                args = m.group(1) or ""
+                verbs = re.findall(r"RequestMethod\.(GET|POST|PUT|PATCH|DELETE)", args)
+                d.update(verbs=verbs or None, path=_path_arg(args))
+            elif role == "jaxrs":
+                d.update(verbs=[m.group(1)], path="")
+            elif role == "path":
+                d.update(verbs=None, path=_path_arg(m.group(1)))
+            elif role == "pyverb":
+                d.update(recv=m.group(1), verbs=[m.group(2).upper()], path=_path_arg(m.group(3)))
+            else:   # pyroute
+                verbs = re.findall(r"[\"'](GET|POST|PUT|PATCH|DELETE)[\"']", m.group(2), re.I)
+                d.update(recv=m.group(1), verbs=[v.upper() for v in verbs] or ["GET"],
+                         path=_path_arg(m.group(2)))
+            decls.append(d)
+    for langs, rx, role in CALL_DECLS:
+        if lang not in langs:
+            continue
+        for m in rx.finditer(body):
+            d = {"pos": m.start(), "end": m.end(), "style": "call", "opid": ""}
+            if role == "map":
+                d.update(recv=m.group(1) or "", verbs=[m.group(2).upper()], path=m.group(3))
+            elif role == "fastendpoints":
+                d.update(recv="", verbs=[m.group(1).upper()], path=m.group(2), style="class")
+            elif role == "router":
+                if CLIENT_RECV_RE.match(m.group(1)):
+                    continue
+                d.update(recv=m.group(1), verbs=[m.group(2).upper()], path=m.group(4))
+            else:   # mux
+                d.update(recv=m.group(1), verbs=[m.group(2) or ""], path=m.group(3))
+            d["open"] = body.find("(", m.start())
+            decls.append(d)
+    if not decls and lang != "cs":
+        return []
+    decls.sort(key=lambda d: d["pos"])
+
+    brace_lang = lang in ("java", "kt", "cs", "js", "scala")
+    classes = [(m.start(), m.group(1), m.end()) for m in CLASS_DECL_RE.finditer(body)] \
+        if brace_lang else []
+
+    def class_at(pos):
+        return next((c for c in reversed(classes) if c[0] < pos), None)
+
+    def class_end(pos):
+        return next((c[0] for c in classes if c[0] > pos), len(body))
+
+    def clean(a, b):
+        """No member boundary between two offsets: both sit in one annotation block."""
+        return not re.search(r"[{};]", body[min(a, b):max(a, b)])
+
+    # A controller with no route declaration at all is routed by CONVENTION: every public
+    # action is an endpoint at /<controller>/<action> (/api/<controller> for Web API).
+    conventional = []
+    if lang == "cs":
+        for start, name, end in classes:
+            stop = class_end(start)
+            header = _type_header(body, end)
+            if not name.endswith("Controller") or not CS_CONTROLLER_BASE_RE.search(header):
+                continue
+            routed = any(d["path"] or d["verbs"] is None for d in decls
+                         if start - 400 < d["pos"] < stop and
+                         (d["pos"] > start or clean(d["end"], start)))
+            if not routed:
+                conventional.append((start, stop, name, "ApiController" in header))
+    in_conv = lambda pos: any(a <= pos < b for a, b, _n, _w in conventional)   # noqa: E731
+
+    cls_prefix = {}
+    for d in decls:
+        if d["style"] != "annot" or d["verbs"] is not None:
+            continue
+        nxt = next((c for c in classes if c[0] > d["pos"]), None)
+        if nxt and clean(d["end"], nxt[0]):
+            cls_prefix.setdefault(nxt[0], []).append(d["path"])
+            d["class_level"] = True
+    for d in decls:
+        if d["style"] != "annot" or d["verbs"] is not None or d.get("class_level"):
+            continue
+        near = [v for v in decls if v["style"] == "annot" and v["verbs"] is not None
+                and clean(v["pos"], d["pos"])]
+        if near:
+            min(near, key=lambda v: abs(v["pos"] - d["pos"]))["sub"] = d["path"]
+            d["attached"] = True
+        else:
+            d["verbs"] = [""]
+
+    var_prefix = {}
+    for langs, rx in PREFIX_VAR_RES:
+        if lang in langs:
+            for m in rx.finditer(body):
+                g = m.groups()
+                var_prefix[g[0]] = _join_route(var_prefix.get(g[1], ""), g[2]) if len(g) == 3 else g[1]
+    if lang == "js":
+        for m in JS_MOUNT_RE.finditer(body):
+            var_prefix[m.group(3)] = _join_route(m.group(2), var_prefix.get(m.group(3), ""))
+        for var, p in (mounts or {}).items():
+            if var not in var_prefix:
+                var_prefix[var] = p
+    blocks = []
+    if lang == "go":
+        for m in GO_ROUTE_BLOCK_RE.finditer(body):
+            brace = body.find("{", _close_bracket(body, m.end() - 1))
+            if brace != -1:
+                blocks.append((brace, _close_bracket(body, brace), m.group(1)))
+
+    # One endpoint per annotation block (stacked declarations route one handler), one per
+    # router call.
+    groups = []
+    for d in decls:
+        if d["verbs"] is None or d.get("class_level") or d.get("attached") or in_conv(d["pos"]):
+            continue
+        bs = _block_start(lang, body, d["pos"]) if d["style"] == "annot" else d["pos"]
+        if groups and d["style"] == "annot" and groups[-1]["bs"] == bs:
+            groups[-1]["decls"].append(d)
+        else:
+            groups.append({"bs": bs, "decls": [d]})
+
+    out = []
+    for i, g in enumerate(groups):
+        first, last = g["decls"][0], g["decls"][-1]
+        cls = class_at(first["pos"])
+        stop = min(groups[i + 1]["bs"] if i + 1 < len(groups) else len(body),
+                   class_end(first["pos"]) if brace_lang else len(body))
+        # An endpoint CLASS (FastEndpoints) is the whole endpoint, its base type included.
+        region = body[cls[0]:class_end(cls[0])] if first["style"] == "class" and cls \
+            else body[g["bs"]:stop]
+        if first["style"] == "annot":
+            handler = _handler_after(body, last["end"])
+        elif first["style"] == "class":
+            handler = NOUN_ROLE_RE.sub("", cls[1]) if cls else None
+        else:
+            handler = _call_handler(body, first["open"])
+            g["called"] = handler
+        cname = cls[1] if cls else ""
+        ctrl = re.sub(r"Controller$", "", cname)
+        routes = []
+        for d in g["decls"]:
+            own = (d.get("sub") or "") + ("/" if d.get("sub") and d["path"] else "") + d["path"] \
+                if d.get("sub") else d["path"]
+            prefix = [] if (lang == "cs" and own.startswith(("/", "~/"))) else \
+                list(cls_prefix.get(cls[0], [])) if cls else []
+            prefix.append(var_prefix.get(d["recv"], ""))
+            prefix += [p for a, b, p in sorted(blocks) if a < d["pos"] < b]
+            full = _join_route(*prefix, own.lstrip("~"))
+            if lang == "cs":
+                full = full.replace("[controller]", ctrl).replace("[action]", handler or "")
+            routes += [(v, full) for v in d["verbs"]]
+        opid = next((d["opid"] for d in g["decls"] if d["opid"]), "") or \
+            next((m.group(1) for rx in OPID_RES for m in [rx.search(region)] if m), "")
+        out.append({"routes": routes, "handler": handler, "opid": opid, "class": cname,
+                    "noun": _resource_noun(cname, path, routes[0][1] if routes else ""),
+                    "region": region, "called": g.get("called")})
+
+    for start, stop, name, webapi in conventional:
+        ctrl = re.sub(r"Controller$", "", name)
+        for m in CS_ACTION_RE.finditer(body, start, stop):
+            bs = _block_start(lang, body, m.start())
+            block = body[bs:m.start()]
+            if re.search(r"\bNonAction\b", block):
+                continue
+            action = m.group(1)
+            verbs = re.findall(r"\bHttp(Get|Post|Put|Patch|Delete)\b", block)
+            if not verbs and webapi:
+                verbs = [v for v in ("Get", "Post", "Put", "Patch", "Delete") if action.startswith(v)][:1]
+            route = f"/api/{ctrl}" if webapi else f"/{ctrl}/{action}"
+            end = body.find("{", m.end())
+            region = body[bs:_close_bracket(body, end) + 1 if end != -1 else m.end()]
+            routes = [(v.upper(), route) for v in (verbs or ["Get"])]
+            opid = next((x.group(1) for rx in OPID_RES for x in [rx.search(block)] if x), "")
+            out.append({"routes": routes, "handler": action, "opid": opid, "class": name,
+                        "noun": _resource_noun(name, path, route), "region": region})
+    # An infrastructure route (_infra_route) is no operation, so it is dropped here, the one
+    # reader every stack's endpoints pass through; an endpoint left with no route goes too.
+    kept = []
+    for ep in out:
+        routes = [r for r in ep["routes"] if not _infra_route(r[1])]
+        if routes or not ep["routes"]:
+            kept.append(dict(ep, routes=routes))
+    return kept
+
+
+def _type_body(lang, body, start):
+    """The text of the type whose declaration header ends at `start`."""
+    if lang == "py":
+        nl = body.find("\n", start)
+        lines = []
+        for ln in (body[nl + 1:] if nl != -1 else "").split("\n"):
+            if ln.strip() and not ln[:1].isspace():
+                break
+            lines.append(ln)
+        return "\n".join(lines)
+    i, j = body.find("{", start), body.find(";", start)
+    if i == -1 or (j != -1 and j < i):
+        return ""
+    return body[i + 1:_close_bracket(body, i)]
+
+
+def _public_operations(lang, kind, name, tbody, source=""):
+    """How many public operations a type declares — a use case declares one. A Go
+    struct's methods are declared outside it, on a receiver, so they are read from the
+    `source` of its file."""
+    if lang == "go":
+        names = set(re.findall(r"^[ \t]*([A-Z]\w*)\s*\(", tbody, re.M)) if kind == "interface" \
+            else set(re.findall(rf"\bfunc\s*\(\s*\w*\s*\*?{re.escape(name)}(?:\[[^\]\n]*\])?\s*\)"
+                                rf"\s*([A-Z]\w*)\s*[\[(]", source))
+    elif lang == "py":
+        defs = re.findall(r"^([ \t]+)(?:async\s+)?def\s+([A-Za-z]\w*)", tbody, re.M)
+        depth = min((len(i) for i, _n in defs), default=0)
+        names = {n for i, n in defs if len(i) == depth}
+    elif lang == "kt":
+        names = set(re.findall(r"^\s*(?!private\b|protected\b|internal\b)(?:\w+\s+)*fun\s+(\w+)",
+                               tbody, re.M))
+    elif kind == "interface":
+        names = set(re.findall(r"\b(\w+)\s*(?:<[^<>]*>)?\s*\([^(){};]*\)\s*(?::\s*[^;{}=]+?)?"
+                               r"\s*(?:throws\s+[\w.,\s]+)?;", tbody))
+    elif lang == "js":
+        names = set(re.findall(r"^\s*(?:public\s+)?(?:async\s+)?([a-zA-Z]\w*)\s*\([^)]*\)\s*"
+                               r"(?::[^{;]+)?\{", tbody, re.M))
+    else:
+        names = set(re.findall(r"\bpublic\s+(?:(?:async|virtual|override|final|synchronized|"
+                               r"abstract)\s+)*[\w<>\[\],.?\s]*?\b(\w+)\s*\(", tbody))
+    return len(names - _HANDLER_SKIP - {name, "toString", "equals", "hashCode", "ToString",
+                                         "Equals", "GetHashCode"})
+
+
+def _published_operations(text, children):
+    """The use cases and endpoints a lane declares, each endpoint resolved to the
+    operation it is.
+
+    `text` is {file: source} for the lane's code. Returns
+      {"usecases":  {op: [file, …]},  single-operation use-case types: the declaring
+                                       file, its implementations, files named after it
+       "uc_decl":   {op: file},
+       "endpoints": {op: {"files", "regions", "routes", "ids"}}}    ids: the published
+                                       operation ids its endpoints declare, verbatim
+    An endpoint op that is also a slice, a handler or a use case is that operation; the
+    rest are operations of their own."""
+    slice_of, handler_ops, handled = {}, set(), {}
+    for f, body in text.items():
+        parts = f.split("/")
+        _i, op = _feature_layer_op(parts[:-1], children, os.path.splitext(parts[-1])[0])
+        if op:
+            slice_of[f] = op
+        for m in HANDLER_CLASS_RE.finditer(body):
+            if not op:
+                handler_ops.add(m.group(1))
+            # The message a handler declares it takes names the operation too —
+            # IQueryHandler<ListOrdersQuery, …> — whatever the handler class is called.
+            brace = body.find("{", m.end())
+            head = body[m.end():brace if brace != -1 else m.end() + 400][:400]
+            for msg in re.findall(r"\b\w*Handler\s*<\s*([A-Z]\w*)", head):
+                handled.setdefault(msg, op or m.group(1))
+
+    decl_of, tinfo = {}, {}
+    for f, body in text.items():
+        for kind, n, header, _start, end in _type_decls(f, body):
+            decl_of.setdefault(f, set()).add(n)
+            tinfo.setdefault(n, (f, kind, header, end))
+
+    uc_type_op, usecases, uc_decl = {}, {}, {}
+    for n, (f, kind, _h, end) in sorted(tinfo.items()):
+        m = USECASE_NAME_RE.match(n)
+        # A use case named after a type (MedicationOrderUseCase) is that type's service,
+        # like one declaring several operations: its callers are the operations.
+        if not m or f in slice_of or m.group(1) in tinfo:
+            continue
+        lang = _lang_of(f)
+        if _public_operations(lang, kind, n, _type_body(lang, text[f], end), text[f]) > 1:
+            continue
+        op = m.group(1)
+        uc_type_op[n] = op
+        usecases.setdefault(op, [f])
+        uc_decl.setdefault(op, f)
+    for n, (f, _k, header, _e) in tinfo.items():
+        for t in set(IDENT_RE.findall(header)) & set(uc_type_op):
+            if f not in usecases[uc_type_op[t]] and f not in slice_of:
+                usecases[uc_type_op[t]].append(f)
+
+    # Functions by name, for a router call that is handed one defined elsewhere:
+    # router.post("/", recordEncounter) and r.Post("/", h.RecordEncounter) are read
+    # through the body of the function they name.
+    func_body = {}
+    for f, body in text.items():
+        for rx in FUNC_DEF_RES.get(_lang_of(f), ()):
+            for m in rx.finditer(body):
+                brace = body.find("{", m.end())
+                fb = body[brace:_close_bracket(body, brace) + 1] if brace != -1 else ""
+                func_body.setdefault(m.group(1), (f, fb))
+
+    def model_file(f):
+        return bool(DOMAIN_DIR_RE.search(os.path.dirname(f) + "/")) or any(
+            AGG_ROOT_MARKER_RE.search(tinfo[n][2]) or ENTITY_MARKER_RE.search(tinfo[n][2])
+            for n in decl_of.get(f, ()) if tinfo[n][0] == f)
+    taken = {f for fs in usecases.values() for f in fs}
+    for f in sorted(text):
+        if f in slice_of or f in taken or model_file(f):
+            continue
+        names = set(decl_of.get(f, ())) | {os.path.splitext(os.path.basename(f))[0]}
+        op = _named_after(names, {o: o for o in usecases})
+        if op:
+            usecases[op].append(f)
+
+    known = set(slice_of.values()) | handler_ops | set(usecases)
+    index = dict(uc_type_op)
+    for n in sorted(known):
+        for form in (n, n + "Command", n + "Query", n + "Request", n + "UseCase", "I" + n + "UseCase",
+                     n + "Interactor", n + "Handler", n + "CommandHandler", n + "QueryHandler"):
+            index.setdefault(form, n)
+    index.update(handled)
+
+    # A router mounted in another file — app.use("/care/encounters", encounterRouter) in
+    # app.ts — prefixes the routes declared on that router where it is defined. Taken only
+    # for a router the mounting file imports rather than defines, and mounted under one
+    # prefix lane-wide: a name mounted twice says nothing about either.
+    mounted = {}
+    for f, body in text.items():
+        if _lang_of(f) != "js":
+            continue
+        for m in JS_MOUNT_RE.finditer(body):
+            var = m.group(3)
+            if not re.search(rf"\b(?:const|let|var)\s+{re.escape(var)}\s*=", body):
+                mounted.setdefault(var, set()).add(m.group(2))
+    mounts = {v: next(iter(p)) for v, p in mounted.items() if len(p) == 1}
+
+    renamed, endpoints = {}, {}
+    for f in sorted(text):
+        if f in slice_of:
+            continue
+        eps = _file_endpoints(f, text[f], mounts)
+        if not eps:
+            continue
+        rx, tg, vg = VAR_TYPE_RES.get(_lang_of(f), (None, 0, 0))
+        file_types = {}
+        for m in rx.finditer(text[f]) if rx else ():
+            file_types.setdefault(m.group(vg), m.group(tg))
+        for ep in eps:
+            called = func_body.get(ep.get("called") or "")
+            if called and called[1] not in ep["region"]:
+                ep["region"] += "\n" + called[1]
+            # A variable has the type its endpoint declares it with, else the type its
+            # file does: two actions that each take a `command` take two commands.
+            var_type = dict(file_types)
+            own = {}
+            for m in rx.finditer(ep["region"]) if rx else ():
+                own.setdefault(m.group(vg), m.group(tg))
+            var_type.update(own)
+            # What the handler CALLS outranks what it merely names: a variable bound to a
+            # use case or handler first, then a command, query or use-case type named in
+            # the body — a request DTO in the signature can name another operation.
+            words = IDENT_RE.findall(ep["region"])
+            invoked = next((index[var_type[w]] for w in words
+                            if w in var_type and var_type[w] in index), None) or \
+                next((index[w] for w in words if w in index), None)
+            # The published id names the operation where it is an identifier, in the
+            # PascalCase every operation name wears (recordEncounter, record_encounter →
+            # RecordEncounter); a kebab or dotted id is recorded, never made a name. The id
+            # itself is kept verbatim in "ids".
+            opid = _pascal(ep["opid"]) if re.fullmatch(r"\w+", ep["opid"]) else ""
+            if opid and (opid in known or opid in index):
+                op = index.get(opid, opid)
+            elif invoked:
+                op = invoked
+                if opid and invoked in usecases and invoked not in slice_of.values() \
+                        and invoked not in handler_ops:
+                    renamed.setdefault(invoked, opid)
+            else:
+                op = opid or _endpoint_name(ep["handler"], ep["noun"], ep["routes"])
+            rec = endpoints.setdefault(op, {"files": [], "regions": [], "routes": [], "evidence": [],
+                                            "ids": []})
+            if f not in rec["files"]:
+                rec["files"].append(f)
+            if ep["opid"] and ep["opid"] not in rec["ids"]:
+                rec["ids"].append(ep["opid"])
+            rec["regions"].append(ep["region"])
+            rec["routes"] += [r for r in ep["routes"] if r not in rec["routes"]]
+            if not invoked and op not in known:
+                for w in set(IDENT_RE.findall(ep["region"])):
+                    t = tinfo.get(var_type.get(w, w))
+                    if t and t[0] != f and not model_file(t[0]):
+                        rec["evidence"].append(text[t[0]])
+
+    # An operation the code publishes under an id is known by that id.
+    for old, new in renamed.items():
+        if new in usecases or new in known:
+            continue
+        usecases[new] = usecases.pop(old)
+        uc_decl[new] = uc_decl.pop(old)
+        if old in endpoints:
+            endpoints[new] = endpoints.pop(old)
+    for ep in endpoints.values():
+        ep["regions"] += ep.pop("evidence")
+    return {"usecases": usecases, "uc_decl": uc_decl, "endpoints": endpoints}
+
+
+# A route Name on an ASP.NET attribute is the id Swashbuckle publishes the action under.
+CS_ROUTE_NAME_RE = re.compile(r"\[Http\w+\s*\([^)\]]*\bName\s*=\s*\"([\w.\-]+)\"")
+
+
+def _declared_ids(sources):
+    """The published operation ids that [(file, source), …] declares beside its endpoints,
+    in the order they appear."""
+    out = []
+    for f, body in sources:
+        rxs = OPID_RES + ((CS_ROUTE_NAME_RE,) if _lang_of(f) == "cs" else ())
+        for _p, i in sorted((m.start(), m.group(1)) for rx in rxs for m in rx.finditer(body)):
+            if i not in out:
+                out.append(i)
+    return out
+
+
+# ── Ids published BY ROUTE: an API document, or doc comments that generate one ──
+#
+# Some stacks keep an operation's id away from its endpoint: in an OpenAPI or Swagger
+# document checked in beside the code, or in doc comments a generator reads
+# (swagger-jsdoc, swag). Each declares a verb, a path and an id; the id belongs to the
+# operation serving that route (_route_key), whatever the operation is called.
+API_DOC_RE = re.compile(r"\.(?:json|ya?ml)$", re.IGNORECASE)
+API_DOC_HEAD_RE = re.compile(r"""^[\s{]*["']?(?:openapi|swagger)["']?\s*:\s*["']?\d""", re.M)
+API_DOC_CAP = 8_000_000
+HTTP_VERBS = ("get", "post", "put", "patch", "delete", "head", "options")
+JSDOC_API_RE = re.compile(r"/\*\*((?:(?!\*/).)*?@(?:openapi|swagger)\b.*?)\*/", re.S)
+SWAG_ID_RE = re.compile(r"@ID\s+(\S+)")
+SWAG_ROUTER_RE = re.compile(r"@Router\s+(\S+)\s+\[(\w+)\]")
+SWAG_BASE_RE = re.compile(r"^\s*//\s*@BasePath\s+(\S+)", re.M)
+
+
+def _api_document(root, rel):
+    """The text of an OpenAPI or Swagger document — known by its own top-level key,
+    whatever the file is called — or "" when the file is not one."""
+    try:
+        p = os.path.join(root, rel)
+        if os.path.getsize(p) > API_DOC_CAP:
+            return ""
+        with open(p, "r", encoding="utf-8", errors="replace") as fh:
+            head = fh.read(4096)
+            return head + fh.read() if API_DOC_HEAD_RE.search(head) else ""
+    except OSError:
+        return ""
+
+
+def _yaml_operation_ids(text, under_paths=True):
+    """(VERB, path, id) for each operation a block-style OpenAPI YAML declares — under its
+    `paths:` key, or at the top of a fragment (`under_paths=False`) as a doc comment
+    writes it. Only an operation's own operationId counts, never one a link nested in it
+    names."""
+    out = []
+    paths_ind = None if under_paths else -1
+    path_ind = path = vlevel = verb = olevel = None
+    for raw in text.splitlines():
+        t = raw.strip()
+        if not t or t.startswith("#"):
+            continue
+        ind = len(raw) - len(raw.lstrip())
+        if paths_ind is None:
+            if re.fullmatch(r"paths\s*:", t):
+                paths_ind = ind
+            continue
+        if ind <= paths_ind:
+            break
+        if path_ind is None:
+            path_ind = ind
+        if ind < path_ind:
+            break
+        if ind == path_ind:
+            m = re.fullmatch(r"""["']?(/[^"']*?)["']?\s*:""", t)
+            path, vlevel, verb = (m.group(1) if m else None), None, None
+            continue
+        if path is None:
+            continue
+        if vlevel is None:
+            vlevel = ind
+        if ind == vlevel:
+            m = re.fullmatch(r"(\w+)\s*:", t)
+            verb = m.group(1).upper() if m and m.group(1).lower() in HTTP_VERBS else None
+            olevel = None
+            continue
+        if verb is None or ind < vlevel:
+            continue
+        if olevel is None:
+            olevel = ind
+        if ind == olevel:
+            m = re.match(r"""operationId\s*:\s*["']?([\w.\-]+)""", t)
+            if m:
+                out.append((verb, path, m.group(1)))
+    return out
+
+
+def _doc_base(doc):
+    """The path every route of an API document sits under: Swagger 2's basePath, or the
+    path of OpenAPI 3's first server url."""
+    if isinstance(doc, dict):
+        servers = doc.get("servers") or [{}]
+        base = doc.get("basePath") or (servers[0].get("url", "") if isinstance(servers[0], dict) else "")
+    else:
+        m = re.search(r"""^basePath\s*:\s*["']?([^"'\s]+)""", doc, re.M) or \
+            re.search(r"""^servers\s*:\s*\n\s*-\s*url\s*:\s*["']?([^"'\s]+)""", doc, re.M)
+        base = m.group(1) if m else ""
+    return re.sub(r"^\w+://[^/]*", "", str(base or ""))
+
+
+def published_ids(root, files):
+    """(in_code, in_docs) — each {route key: [id, …]} — for the ids the lane publishes by
+    route rather than beside the endpoint (see the section comment above): `in_code` from
+    the doc comments in its source, `in_docs` from the API documents it keeps. Test files
+    are not read."""
+    in_code, in_docs = {}, {}
+
+    def add(verb, path, oid, base="", out=in_code):
+        lst = out.setdefault(_route_key(verb, _join_route(base, path)), [])
+        if oid not in lst:
+            lst.append(oid)
+
+    swag, swag_base = [], ""
+    for f in files:
+        if TEST_PATH_RE.search(f):
+            continue
+        if API_DOC_RE.search(f):
+            text = _api_document(root, f)
+            if not text:
+                continue
+            if f.lower().endswith(".json"):
+                try:
+                    doc = json.loads(text)
+                except ValueError:
+                    continue
+                base = _doc_base(doc)
+                for path, item in (doc.get("paths") or {}).items() if isinstance(doc, dict) else ():
+                    for verb, o in (item.items() if isinstance(item, dict) else ()):
+                        if verb.lower() in HTTP_VERBS and isinstance(o, dict) and o.get("operationId"):
+                            add(verb, path, str(o["operationId"]), base, in_docs)
+            else:
+                base = _doc_base(text)
+                for verb, path, oid in _yaml_operation_ids(text):
+                    add(verb, path, oid, base, in_docs)
+            continue
+        lang = _lang_of(f)
+        if lang == "js":
+            for m in JSDOC_API_RE.finditer(_read_source(root, f)):
+                frag = "\n".join(re.sub(r"^\s*\*\s?", "", ln) for ln in m.group(1).splitlines())
+                frag = re.sub(r"^.*@(?:openapi|swagger)\b.*$", "", frag, flags=re.M)
+                for verb, path, oid in _yaml_operation_ids(frag, under_paths=False):
+                    add(verb, path, oid)
+        elif lang == "go":
+            body = _read_source(root, f)
+            swag_base = swag_base or next((m.group(1) for m in [SWAG_BASE_RE.search(body)] if m), "")
+            block = []
+            for ln in body.splitlines() + [""]:
+                if ln.strip().startswith("//"):
+                    block.append(ln)
+                    continue
+                ids = [m.group(1) for b in block for m in [SWAG_ID_RE.search(b)] if m]
+                if ids:
+                    swag += [(m.group(2), m.group(1), ids[0])
+                             for b in block for m in [SWAG_ROUTER_RE.search(b)] if m]
+                block = []
+    for verb, path, oid in swag:
+        add(verb, path, oid, swag_base)
+    return in_code, in_docs
+
+
 _DOMAIN_MEMO = {}
 
 
@@ -1886,8 +2959,9 @@ def parse_domain(root, files):
     configuration, a DTO mapping) belongs to the owner of what it references. A type
     two roots reach at the same distance, with neither's name as its prefix, is the
     module's shared kernel — PatientId in a context that only references Patient.
-    Operations are read in the module and, for a solution split one project per layer,
-    across the lane; what is left is placed by _attribute_leftovers."""
+    Operations — slices, handler classes, use cases and endpoints — are read in the
+    module and, for a solution split one project per layer, across the lane; what is
+    left is placed by _attribute_leftovers."""
     if root is None:
         return {"modules": {}, "types": {}, "owner": {}, "shared": {},
                 "operations": [], "root_edges": {}}
@@ -1905,12 +2979,10 @@ def parse_domain(root, files):
         if not body:
             continue
         text[f] = body
-        for m in TYPE_DECL_RE.finditer(body):
-            name = m.group(2)
+        for kind, name, header, start, _end in _type_decls(f, body):
             if name in types:
                 continue
-            role = _type_role(m.group(1), name, _type_header(body, m.end()), f,
-                              body[max(0, m.start() - 200):m.start()])
+            role = _type_role(kind, name, header, f, body[max(0, start - 200):start])
             types[name] = {"file": f, "role": role, "module": module_of[f]}
             decl_of.setdefault(f, set()).add(name)
 
@@ -1920,7 +2992,7 @@ def parse_domain(root, files):
     for n, t in sorted(roots.items()):
         key = t["module"]
         seg = key.rsplit("/", 1)[-1]
-        ctx = _clean_project_name(seg, product) if DOTTED_SEG_RE.match(seg) else seg
+        ctx = _clean_project_name(seg, product) if DOTTED_SEG_RE.match(seg) else _pascal(seg)
         mod = modules.setdefault(key, {"context": ctx, "dir": key, "roots": [], "files": []})
         mod["roots"].append(n)
     for f, key in module_of.items():
@@ -1937,15 +3009,28 @@ def parse_domain(root, files):
         refs[f] = (set(IDENT_RE.findall(body)) & types_in[module_of[f]]) - decl_of.get(f, set())
 
     owner, shared, ops = {}, {}, {}
+    pub = _published_operations(text, children) if modules else \
+        {"usecases": {}, "uc_decl": {}, "endpoints": {}}
 
-    def _add_op(op, fs, in_scope, key=None):
+    def _add_op(op, fs, in_scope, key=None, served=None, require_target=False):
         """Record one operation: the roots its files name (a root by name, or a
         specification of one, is strong; a type a root owns is weak), filed under the
         module `key`, or — with none given — under the module of the root it acts on,
-        and dropped when it acts on no root at all."""
+        and dropped when it acts on no root at all.
+
+        `served` is what the operation's ENDPOINTS add (see _published_operations):
+        their files, which a controller shares with other operations and which are
+        therefore read through each endpoint's own region rather than whole, the
+        routes joined there, and the verbs that say whether it reads or writes. An
+        operation only an endpoint declares (`require_target`) is dropped when it acts
+        on no root, wherever it is filed."""
+        served = served or {}
+        shared = set(served.get("files", ()))
+        fs = list(fs) + [f for f in served.get("files", ()) if f not in fs]
+        scan = [text.get(f, "") for f in fs if f not in shared] + list(served.get("regions", ()))
         strong, weak = {}, {}
-        for f in fs:
-            for tn in IDENT_RE.findall(text.get(f, "")):
+        for body in scan:
+            for tn in IDENT_RE.findall(body):
                 t = types.get(tn)
                 if not t or not in_scope(t["module"]):
                     continue
@@ -1959,26 +3044,33 @@ def parse_domain(root, files):
         pick = strong or weak
         acts_on = sorted(pick, key=lambda r: (-pick[r], r)) if strong else \
             ([max(sorted(weak), key=weak.get)] if weak else [])
+        if not acts_on and (key is None or require_target):
+            return
         if key is None:
-            if not acts_on:
-                return
             key = types[acts_on[0]]["module"]
         ctx = modules[key]["context"]
         routes = []
         for f in fs:
-            routes.extend(_routes_in(text.get(f, "")))
+            if f not in shared:
+                routes.extend(_routes_in(text.get(f, "")))
+        routes += list(served.get("routes", ()))
         # An operation over two aggregates is FILED under the one its route names:
         # POST /access/appointments schedules an Appointment, whatever it loads.
         fams = {_ui_norm(_route_family(p, (ctx,))) for _v, p in routes}
         named = [r for r in acts_on if _ui_norm(r) in fams]
         if named:
             acts_on = named[:1] + [r for r in acts_on if r != named[0]]
+        ids = list(served.get("ids", ()))
+        ids += [i for i in _declared_ids([(f, text.get(f, "")) for f in fs if f not in shared])
+                if i not in ids]
         ops[op] = {
             "name": op, "context": ctx, "module": key,
             "files": sorted(set(fs)), "acts_on": acts_on,
-            "kind": "query" if QUERY_NAME_RE.match(op) or any(
-                re.search(r"Query\b", os.path.basename(f)) for f in fs) else "command",
+            "kind": _verb_kind(served.get("routes", ())) or (
+                "query" if QUERY_NAME_RE.match(op) or any(
+                    re.search(r"Query\b", os.path.basename(f)) for f in fs) else "command"),
             "routes": sorted(set(routes)),
+            "operation_ids": ids,
         }
         for f in fs:
             if acts_on and f not in owner:
@@ -2058,20 +3150,25 @@ def parse_domain(root, files):
             elif f in best:
                 shared.setdefault(key, []).append(f)
 
-        # Slice folders, plus handler classes outside any feature layer.
+        # Slice folders, plus handler classes outside any feature layer, plus the use
+        # cases this module declares. Each takes the endpoints that serve it.
         for f in plain:
             for m in HANDLER_CLASS_RE.finditer(text.get(f, "")):
                 op_files.setdefault(m.group(1), []).append(f)
+        for op, fs in pub["usecases"].items():
+            if module_of.get(pub["uc_decl"][op]) == key:
+                lst = op_files.setdefault(op, [])
+                lst += [f for f in fs if f not in lst]
         for op, fs in sorted(op_files.items()):
-            _add_op(op, fs, lambda m, key=key: m == key, key)
+            _add_op(op, fs, lambda m, key=key: m == key, key, pub["endpoints"].get(op))
 
     # Operations OUTSIDE every module that declares a root. A solution split into one
     # project per layer (Domain / Application / Infrastructure / Api) keeps its roots in
     # one project and its handlers in another, so a module-local search finds none —
     # and the model, which exists to be acted on, reads as having no operations. The
-    # same two shapes are read here (a feature-layer slice, a CQRS handler class), and
-    # an operation counts only when it acts on a declared root: a handler that touches
-    # no aggregate of the model is not one of its operations.
+    # same shapes are read here (a feature-layer slice, a CQRS handler class, a use
+    # case), and an operation counts only when it acts on a declared root: a handler
+    # that touches no aggregate of the model is not one of its operations.
     in_model = set(modules)
     outside = [f for f in text if module_of[f] not in in_model]
     out_files = {}
@@ -2083,6 +3180,10 @@ def parse_domain(root, files):
             continue
         for m in HANDLER_CLASS_RE.finditer(text[f]):
             out_files.setdefault(m.group(1), []).append(f)
+    for op, fs in pub["usecases"].items():
+        if module_of.get(pub["uc_decl"][op]) not in in_model:
+            lst = out_files.setdefault(op, [])
+            lst += [f for f in fs if f not in lst]
     out_files = {op: fs for op, fs in out_files.items() if op not in ops}
     # A layer-per-project solution files one operation across several projects — the
     # command, its validator and its endpoint beside the handler — and names each file
@@ -2097,7 +3198,14 @@ def parse_domain(root, files):
         if op:
             out_files[op].append(f)
     for op, fs in sorted(out_files.items()):
-        _add_op(op, fs, lambda m: m in in_model)
+        _add_op(op, fs, lambda m: m in in_model, served=pub["endpoints"].get(op))
+    # An endpoint that invokes none of the operations above declares one of its own —
+    # a controller action that does its work inline.
+    for op, served in sorted(pub["endpoints"].items()):
+        if op not in ops:
+            k = module_of.get(served["files"][0])
+            _add_op(op, [], lambda m: m in in_model, k if k in in_model else None, served,
+                    require_target=True)
 
     # Everything above decides what orders the aggregates; what follows only decides
     # which aggregate a file is LISTED under. Ordering is kept to the evidence it always
@@ -2164,8 +3272,7 @@ def strategy_domain(root, files, churn_map, graph=None):
         c = cands.get(r.lower())
         if not c:
             continue
-        kind = next((_layer_of(p, soft=True) for p in f.split("/")[:-1]
-                     if _layer_of(p, soft=True)), "domain")
+        kind = _bucket_of(f.split("/")[:-1], "domain")
         c[kind + "_files"].append(f)
         c["churn"] += churn_map.get(f, 0)
     return _finish_candidates(cands, churn_map, "domain")
@@ -2415,8 +3522,7 @@ def seam_overlay(root, files, candidates, churn_map, ui_attribution=None, contex
             continue
         # Application / API / UI only. Domain files say what must stay
         # consistent; they never say where traffic can be cut over.
-        kind = next((_layer_of(p, soft=True) for p in f.split("/")[:-1]
-                     if _layer_of(p, soft=True)), "other")
+        kind = _bucket_of(f.split("/")[:-1], "other")
         if kind == "domain":
             continue
         out[name]["churn"] += churn_map.get(f, 0)
@@ -2484,6 +3590,23 @@ def _capability_name(aggregate, seam):
     return _pascal_name(aggregate) + pascal
 
 
+def _common_dir(files):
+    """The directory every one of `files` sits under, '/'-terminated, or ''."""
+    common = None
+    for f in files:
+        d = f.split("/")[:-1]
+        if common is None:
+            common = d
+            continue
+        n = 0
+        while n < len(common) and n < len(d) and common[n] == d[n]:
+            n += 1
+        common = common[:n]
+        if not common:
+            break
+    return "/".join(common) + "/" if common else ""
+
+
 def derive_contexts(candidates, files):
     """Group candidates into bounded contexts, primed by the highest directory
     level that actually separates them.
@@ -2491,12 +3614,53 @@ def derive_contexts(candidates, files):
     A context is a grouping of aggregates that share a model. The top-level
     source directory is the best available prior — in a component monorepo those
     directories ARE the contexts — and the operator confirms or rewrites it.
-    Where the tree has no such level, the whole repo is one context."""
+    Where the tree has no such level, the whole repo is one context.
+
+    A directory every file sits under separates nothing — a declared lane's root
+    folder (`backend/`) is the common case — so it is never a context: the segments
+    are read below it."""
+    shared = _common_dir(files)
+    children = _child_dirs(files)
+    holds_files = {f.rsplit("/", 1)[0] for f in files if "/" in f}
+
     def context_segment(path):
-        """The first path segment that separates one context from another."""
-        for part in (path or "").split("/"):
-            if not part or CONTAINER_DIR_RE.match(part):
+        """The first folder that separates one context from another. A container folder
+        is read through, and so is a layer folder beside another layer folder: a tree
+        organised by layer at that level (src/controllers/ beside src/models/) names no
+        context there. Below such a layer, a folder is a context only when another of
+        those layers holds a folder of the same name (controllers/care/ beside
+        models/care/); any other is part of its one layer (adapter/in/, domain/model/).
+        A layer-named folder among modules (a Repository/ component) is read as one.
+
+        A JVM package's reverse-domain prefix is read through as well: below a JVM source
+        folder, the vendor folder (com/, io/) and each folder after it that is the only
+        folder in a parent holding no source file (acme/clinic/). The walk resumes at the
+        base package, so a single module folder below it is still read as one."""
+        path = path or ""
+        parent = ""
+        if shared and (path + "/").startswith(shared):
+            parent, path = shared.rstrip("/"), path[len(shared):]
+        parts = [p for p in path.split("/") if p]
+        prev, in_prefix = parent.rsplit("/", 1)[-1], False
+        for i, part in enumerate(parts):
+            kids = children.get(parent, ())
+            if (prev.lower() in JVM_SOURCE_DIRS and VENDOR_PREFIX_RE.match(part)) or (
+                    in_prefix and len(kids) == 1 and parent not in holds_files):
+                prev, in_prefix = part, True
+                parent = f"{parent}/{part}" if parent else part
                 continue
+            prev, in_prefix = part, False
+            if CONTAINER_DIR_RE.match(part):
+                parent = f"{parent}/{part}" if parent else part
+                continue
+            layers = [s for s in kids
+                      if s != part and (_layer_of(s) or _paired_layer(parent, s, children))]
+            if (_layer_of(part) or _paired_layer(parent, part, children)) and layers:
+                below = parts[i + 1] if i + 1 < len(parts) else ""
+                if below and any(below in children.get(f"{parent}/{s}" if parent else s, ())
+                                 for s in layers):
+                    return below
+                return ""
             if DOTTED_SEG_RE.match(part):
                 bits = part.split(".")
                 return bits[1] if len(bits) > 2 else bits[0]
@@ -2505,10 +3669,10 @@ def derive_contexts(candidates, files):
 
     # A DECLARED context — the module folder that holds a Domain layer, which the kit's
     # folder-structure rule makes one folder per bounded context — is taken as it
-    # stands: its name verbatim (it is the name specs/<Context>/ must carry for a slice
-    # to be traceable in both trees), and never folded for holding one aggregate. A
-    # context with one aggregate is a real and common shape; only an INFERRED path
-    # segment can be incidental.
+    # stands: the module folder's name in the PascalCase every name in specs/ carries
+    # (`care/` → Care, `Modules/Care/` → Care), and never folded for holding one
+    # aggregate. A context with one aggregate is a real and common shape; only an
+    # INFERRED path segment can be incidental.
     declared = {}
     for c in candidates:
         if c.get("context"):
@@ -2526,10 +3690,10 @@ def derive_contexts(candidates, files):
         votes = {}
         for k in LAYER_KEYS:
             for f in c[k]:
-                seg = context_segment(f)
+                seg = context_segment(f.rsplit("/", 1)[0] if "/" in f else "")
                 if seg:
                     votes[seg] = votes.get(seg, 0) + 1
-        seg = max(sorted(votes), key=votes.get) if votes else context_segment(c.get("module_dir"))
+        seg = max(sorted(votes), key=votes.get) if votes else ""
         groups.setdefault(_pascal_name(singularize(seg)) or "Core", []).append(c["name"])
 
     # A context holding one aggregate in a repo that has several is usually the
@@ -2591,7 +3755,8 @@ def _creating_op(aggregate, ops, context):
     return None
 
 
-def propose_features(candidates, seams, edges, contexts, operations=None, ui_feats=None):
+def propose_features(candidates, seams, edges, contexts, operations=None, ui_feats=None,
+                     ui_calls=None):
     """Features, proposed from the one kind of evidence that names a capability.
 
     GREENFIELD SHAPE, READ BACK. A feature is a capability the developer chose; it
@@ -2599,10 +3764,14 @@ def propose_features(candidates, seams, edges, contexts, operations=None, ui_fea
     on one aggregate. Its operations are what its user stories need done — several to a
     story as often as not, and a read may serve more than one feature. Code records a feature in
     exactly one place — the UI lane's features/<Feature>/ folder, named after the spec
-    feature verbatim — so:
+    feature verbatim, or a frontend's own feature folders where it has none (see
+    ui_features) — so:
 
       1. every UI feature folder becomes a feature, named verbatim, holding the
-         operations it calls and acting on those operations' aggregates;
+         operations it calls and acting on those operations' aggregates. A call
+         (`ui_calls`, see ui_api_calls) reaches the operation whose route it is, by
+         verb and path (_route_key) — whatever the API functions are called; an
+         imported function or the folder itself named after an operation links too;
       2. a read no feature calls is SHARED — it joins every feature acting on its
          aggregate, because reads are not what separates two capabilities;
       3. commands no feature calls, and aggregates no UI feature touches, fall back to
@@ -2633,6 +3802,18 @@ def propose_features(candidates, seams, edges, contexts, operations=None, ui_fea
                 fam_to_agg.setdefault(_ui_norm(fam), {}).setdefault(o["acts_on"][0], 0)
                 fam_to_agg[_ui_norm(fam)][o["acts_on"][0]] += 1
 
+    # The service lane's routes, as a UI call writes them. Every operation counts: a
+    # call to one that acts on nothing the scan placed is still served.
+    by_route = {}
+    for o in operations or []:
+        for v, p in o.get("routes") or []:
+            by_route.setdefault(_route_key(v, p), []).append(o)
+    live = {o["name"]: o for o in ops}
+
+    def served(c):
+        k = _route_key(c["verb"], c["path"])
+        return by_route.get(k) or by_route.get(("", k[1])) or []
+
     feats, claimed, unlinked = [], set(), []
     for name, rec in sorted((ui_feats or {}).items()):
         mine = []
@@ -2641,6 +3822,9 @@ def propose_features(candidates, seams, edges, contexts, operations=None, ui_fea
             o = op_by_key.get(k) or op_by_key.get(re.sub(r"action$", "", k))
             if o and o not in mine:
                 mine.append(o)
+        by_call = {o["name"] for c in _ui_reached(ui_calls or [], rec)
+                   for o in served(c) if o["name"] in live}
+        mine += [live[n] for n in sorted(by_call) if live[n] not in mine]
         aggs = []
         for o in mine:
             aggs += [a for a in o["acts_on"] if a not in aggs]
@@ -2652,8 +3836,9 @@ def propose_features(candidates, seams, edges, contexts, operations=None, ui_fea
                     a = max(sorted(hit), key=hit.get)
                     if a not in aggs:
                         aggs.append(a)
+        roots = rec.get("roots") or [f"features/{name}/"]
         if not aggs:
-            unlinked.append(name)
+            unlinked.append(roots)
             continue
         votes = {}
         for a in aggs:
@@ -2664,7 +3849,7 @@ def propose_features(candidates, seams, edges, contexts, operations=None, ui_fea
                       "aggregates": [a for a in aggs if ctx_of.get(a, "Core") == ctx],
                       "references": [a for a in aggs if ctx_of.get(a, "Core") != ctx],
                       "operations": [o["name"] for o in mine], "called": len(mine),
-                      "source": "ui-feature", "ui_files": len(rec["files"])})
+                      "source": "ui-feature", "ui_files": len(rec["files"]), "roots": roots})
 
     # Shared reads join every feature already acting on their aggregate.
     for o in ops:
@@ -2720,7 +3905,7 @@ def propose_features(candidates, seams, edges, contexts, operations=None, ui_fea
         sole = len([g for g in feats if primary in g["aggregates"]]) == 1
         if f["source"] == "ui-feature":
             shared_reads = len(f["operations"]) - f["called"]
-            evidence = (f"UI feature folder features/{f['feature']}/ calls {f['called']} "
+            evidence = (f"{_ui_where(f['roots'])} calls {f['called']} "
                         f"operation(s)" + (f" + {shared_reads} shared read(s)" if shared_reads else ""))
         elif f["operations"]:
             evidence = ("aggregate default — no UI feature calls these operations; rename it "
@@ -2754,29 +3939,51 @@ def propose_features(candidates, seams, edges, contexts, operations=None, ui_fea
         out.append(feature)
     out.sort(key=lambda x: (x["context"], -x["files"], x["feature"]))
     # What the operator must decide rather than accept: commands that fell to a default
-    # beside real capabilities on the same aggregate, and UI features that call nothing
-    # the scan could tie to an aggregate.
+    # beside real capabilities on the same aggregate, UI features that call nothing
+    # the scan could tie to an aggregate, and UI calls no service route serves — read
+    # only where the service lane declares routes at all.
     capab = {a for f in feats if f["source"] == "ui-feature" for a in f["aggregates"]}
+    unserved = {}
+    for c in (ui_calls or []) if by_route else []:
+        if not served(c):
+            u = unserved.setdefault((c["verb"], c["path"]), {"features": set(), "files": []})
+            if c["file"] not in u["files"]:
+                u["files"].append(c["file"])
+    for name, rec in (ui_feats or {}).items():
+        for c in _ui_reached(ui_calls or [], rec):
+            if (c["verb"], c["path"]) in unserved:
+                unserved[(c["verb"], c["path"])]["features"].add(name)
     notes = {
         "orphaned": [(f["feature"], n) for f in feats if f["source"] == "aggregate-default"
                      and f["aggregates"][0] in capab for n in f["operations"]],
         "unlinked_ui": unlinked,
+        "unserved_ui": [(f"{v} {p}", sorted(u["features"]), sorted(u["files"]))
+                        for (v, p), u in sorted(unserved.items(), key=lambda kv: (kv[0][1], kv[0][0]))],
     }
     return out, notes
 
 
-def aggregate_signals(files, churn_map, root=None):
+def aggregate_signals(files, churn_map, root=None, strategy=""):
     """Derive CANDIDATE aggregate roots — the unit onboard writes one OKF concept for.
 
-    Where the code DECLARES its roots and operations act on them (and `root` is given
-    so the source can be read), those are the candidates, each stamped with its
-    bounded context and its operations — the same rule choose_strategy applies.
-    Otherwise Pass A's structure strategy reads the repo's organising axis
-    (module-major, project-major, vertical slice, n-tier, or the build manifest)
-    instead of assuming one. Every caller gets the same candidate shape either way.
+    `strategy` is the Pass A strategy the feature map was built from. Read with it (and
+    `root` given so the source can be read), the candidates are the aggregates that map
+    names, each with its files, whichever strategy the operator chose.
+
+    Without one, or where it finds nothing: where the code DECLARES its roots and
+    operations act on them, those are the candidates, each stamped with its bounded
+    context and its operations — the same rule choose_strategy applies. Otherwise Pass
+    A's structure strategy reads the repo's organising axis (module-major,
+    project-major, vertical slice, n-tier, or the build manifest) instead of assuming
+    one. Every caller gets the same candidate shape either way.
 
     Signals only — the workflow's agent draws the real boundaries. Empty for a
     repo with no recognizable structure at all."""
+    if root and strategy in STRATEGIES:
+        graph = build_reference_graph(root, files)[0] if strategy == "reference" else None
+        cands = STRATEGIES[strategy](root, files, churn_map, graph)
+        if cands:
+            return cands
     if root:
         declared = strategy_domain(root, files, churn_map)
         if any(c.get("operations") for c in declared):
@@ -2843,80 +4050,450 @@ def _ui_name_tokens(name):
 # the service lane's PascalCase Features/<Operation>/ is a different thing (one
 # operation of a module) and must never be read as a capability.
 UI_FEATURE_SEG_RE = re.compile(r"(?:^|/)features/([^/]+)/")
-UI_SOURCE_RE = re.compile(r"\.(tsx?|jsx?|mjs|vue|svelte)$", re.IGNORECASE)
+UI_SOURCE_RE = re.compile(r"\.(tsx?|jsx?|mjs|vue|svelte|razor|astro)$", re.IGNORECASE)
 API_IMPORT_RE = re.compile(r"""import\s*(?:type\s+)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]""")
 API_NS_IMPORT_RE = re.compile(r"""import\s+\*\s+as\s+(\w+)\s+from\s*['"]([^'"]+)['"]""")
 API_MODULE_RE = re.compile(r"(?:^|[/@])apis?(?:/|$)")
 UI_ROUTE_LITERAL_RE = re.compile(r"""[`'"](/[A-Za-z][A-Za-z0-9_\-/${}.:]*)[`'"]""")
+# Where a frontend keeps its features when it has no features/ folder, in precedence
+# order: module folders; route-segment folders (Next.js app/, Angular src/app/); page
+# folders (React, Nuxt, Blazor Pages/); Vue views/; SvelteKit and Remix routes/.
+UI_FEATURE_CONTAINERS = ("modules", "app", "pages", "views", "routes")
+# A container's children that are its infrastructure, not a capability.
+UI_NOT_FEATURE = frozenset((
+    "shared", "common", "core", "components", "component", "ui", "lib", "libs", "utils",
+    "util", "helpers", "hooks", "composables", "layouts", "layout", "styles", "assets",
+    "api", "apis", "services", "service", "store", "stores", "state", "types", "models",
+    "interfaces", "config", "constants", "i18n", "locales", "test", "tests", "__tests__",
+    "mocks", "__mocks__", "fixtures", "providers", "guards", "interceptors", "pipes",
+    "directives", "environments", "index", "page", "error", "loading", "not-found",
+    "notfound", "404", "500", "_app", "_document", "_error", "root", "app", "main",
+    "home", "shell"))
+UI_PAGE_FILE_RE = re.compile(r"\.(tsx|jsx|vue|svelte|razor|astro)$", re.IGNORECASE)
+# Names a component brings in beside an ES import: Blazor's @inject, a constructor
+# parameter's type (Angular services).
+UI_INJECT_RE = re.compile(r"@inject\s+(?:[\w.]+\.)?([A-Z]\w*)")
+UI_CTOR_TYPE_RE = re.compile(r"\b[a-z_]\w*\s*\??:\s*(?:\w+\.)?([A-Z]\w*)")
+UI_DEFAULT_IMPORT_RE = re.compile(r"""import\s+([A-Za-z_$][\w$]*)\s*(?:,\s*\{[^}]*\})?\s*from\s*['"]""")
+
+
+def _ui_container_hit(rel, container):
+    """(feature, root) for a frontend file under one kind of container folder:
+    <container>/<Feature>/…, or a page file placed directly in the container. `root` is
+    where the feature was read from, from the container segment on: its folder
+    (`app/(clinic)/orders/`) or its page file (`views/OrdersView.vue`)."""
+    parts = rel.split("/")
+    for i, seg in enumerate(parts[:-1]):
+        if seg.lower() != container:
+            continue
+        rest, groups = parts[i + 1:], 0
+        while len(rest) > 1 and re.fullmatch(r"\(.*\)", rest[0]):    # Next.js route groups
+            rest, groups = rest[1:], groups + 1
+        if len(rest) == 1:
+            if not UI_PAGE_FILE_RE.search(rest[0]):
+                return None
+            stem = rest[0].split(".")[0]
+            name = re.sub(r"(?:View|Page|Screen)$", "", stem) or stem   # EncountersView.vue
+            root = "/".join(parts[i:])
+        else:
+            name = rest[0]
+            root = "/".join(parts[i:i + 2 + groups]) + "/"
+        if not name or name[0] in "[_+@(." or name.lower() in UI_NOT_FEATURE:
+            return None
+        return name, root
+    return None
 
 
-def ui_features(root, fe_files, ui_prefix):
-    """The CAPABILITIES the UI lane records: {Feature: {"files", "calls", "routes"}}.
+def ui_feature_layout(src):
+    """Where a UI lane keeps its features, read from its source files as (path,
+    lane-relative path) pairs: "features" when any sits in a features/<Feature>/ folder,
+    else the first of UI_FEATURE_CONTAINERS holding a feature outside its tests, else ""."""
+    if any(UI_FEATURE_SEG_RE.search(rel) for _f, rel in src):
+        return "features"
+    for container in UI_FEATURE_CONTAINERS:
+        if any(_ui_container_hit(rel, container) and not UI_TEST_FILE_RE.search(f)
+               for f, rel in src):
+            return container
+    return ""
+
+
+def ui_feature_of(rel, layout):
+    """(feature, root) for a lane-relative path under `layout` (see ui_feature_layout), or
+    None: a features/<Feature>/ folder's name verbatim, or a container's folder or page
+    made PascalCase. `root` is where the feature was read from — `features/<Feature>/`,
+    `app/(clinic)/orders/`, `views/OrdersView.vue`."""
+    if layout == "features":
+        m = UI_FEATURE_SEG_RE.search(rel)
+        return (m.group(1), f"features/{m.group(1)}/") if m else None
+    hit = _ui_container_hit(rel, layout) if layout else None
+    return (_pascal(hit[0]), hit[1]) if hit else None
+
+
+def _ui_where(roots):
+    """How the proposal names where a UI feature was read from: its folder or page, the
+    first of several with a count of the rest."""
+    first = (roots or [""])[0]
+    more = f" (+{len(roots) - 1} more)" if len(roots) > 1 else ""
+    return f"{'UI feature folder' if first.endswith('/') else 'UI page'} {first}{more}"
+
+
+def ui_features(root, fe_files, ui_prefix, declared=False):
+    """The CAPABILITIES the UI lane records:
+    {Feature: {"files", "roots", "calls", "routes", "imports", "idents"}}. `roots` is
+    where each was read from (see ui_feature_of).
 
     The frontend rules make features/<Feature>/ the spec feature's name verbatim —
     "that match is what makes a slice traceable in both lanes". It is therefore the
-    only place in code where a feature, as distinct from an aggregate or an
-    operation, is written down. `calls` are the API-client functions the feature
-    imports (the operations it invokes, by name); `routes` are the path literals it
-    builds, which name the aggregates it reads even where it imports nothing.
-
-    Runs only under a DECLARED UI root: without one scope_to_lanes hands back the
+    first place a feature, as distinct from an aggregate or an operation, is read.
+    `calls` are the API-client functions the feature imports (the operations it
+    invokes, by name); `routes` are the path literals it builds, which name the
+    aggregates it reads even where it imports nothing; `imports` is every name it
+    brings in — imported, injected or taken as a constructor parameter; `idents` is
+    every name its code uses, which says which methods of an imported client it calls.
+
+    A frontend not built to that rule keeps its features elsewhere. With no
+    features/ folder anywhere in the lane, the first container kind of
+    UI_FEATURE_CONTAINERS that holds any feature is read instead, each folder name
+    made PascalCase — those are route segments and module folders, not spec names.
+
+    Runs only under a DECLARED UI root — `declared` says so for a lane at the repo
+    root, whose prefix is empty. Without a declaration scope_to_lanes hands back the
     whole repo, and a backend's Features/ folders are not capabilities."""
-    if not ui_prefix:
+    if not ui_prefix and not declared:
         return {}
+    src = [(f, f[len(ui_prefix):]) for f in fe_files
+           if f.startswith(ui_prefix) and UI_SOURCE_RE.search(f)]
+    layout = ui_feature_layout(src)
+    owner = {}
+    for f, rel in src:
+        hit = ui_feature_of(rel, layout)
+        if hit and (layout == "features" or not UI_TEST_FILE_RE.search(f)):
+            owner[f] = hit
     feats = {}
-    for f in fe_files:
-        if not f.startswith(ui_prefix) or not UI_SOURCE_RE.search(f):
+    for f, _rel in src:
+        if f not in owner:
             continue
-        m = UI_FEATURE_SEG_RE.search(f[len(ui_prefix) - 1:])
-        if not m:
-            continue
-        rec = feats.setdefault(m.group(1), {"files": [], "calls": set(), "routes": set()})
+        name, where = owner[f]
+        rec = feats.setdefault(name, {"files": [], "roots": [], "calls": set(), "routes": set(),
+                                      "imports": set(), "idents": set()})
         rec["files"].append(f)
+        if where not in rec["roots"]:
+            rec["roots"].append(where)
         body = _read_source(root, f)
+        rec["idents"].update(IDENT_RE.findall(body))
         for names, mod in API_IMPORT_RE.findall(body):
+            named = {n.strip().split(" as ")[0].strip() for n in names.split(",") if n.strip()}
+            rec["imports"].update(named)
             if API_MODULE_RE.search(mod):
-                rec["calls"].update(n.strip().split(" as ")[0].strip()
-                                    for n in names.split(",") if n.strip())
+                rec["calls"].update(named)
         for ns, mod in API_NS_IMPORT_RE.findall(body):
             if API_MODULE_RE.search(mod):
                 rec["calls"].update(re.findall(rf"\b{re.escape(ns)}\.(\w+)\s*\(", body))
+        rec["imports"].update(UI_DEFAULT_IMPORT_RE.findall(body))
+        rec["imports"].update(UI_INJECT_RE.findall(body))
+        rec["imports"].update(UI_CTOR_TYPE_RE.findall(body))
         rec["routes"].update(UI_ROUTE_LITERAL_RE.findall(body))
     return feats
 
 
+# ═══════════════════════════════════════════════════════════════════════════
+# A project with NO service lane — its model is read from the calls its UI makes.
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# A front end whose API lives in another repository still works on aggregates: the
+# resources it calls. Each route family the lane calls (/care/encounters/… →
+# Encounter) is the UI's view of an aggregate another system owns; each distinct call
+# is an operation; the leading route segment is a bounded context where the API
+# carries one (/care/encounters, /care/medication-orders → Care), and one context named
+# after the project holds the rest. A feature acts on what it calls — in its own files,
+# or through a function, client or service it imports or is injected with.
+
+# Outgoing HTTP calls, as each frontend stack writes them.
+UI_CALL_RES = (
+    # client.get("/x"), axios.post(`/x`), this.http.get<T>("/x"), api.GET("/x"), ky.put(…)
+    (re.compile(r"\b(\w+)\s*\.\s*(get|post|put|patch|delete|GET|POST|PUT|PATCH|DELETE)\s*"
+                r"(?:<[^()]*?>)?\s*\(\s*([\"'`])([^\"'`\n]*)\3"), "member"),
+    # fetch("/x", { method: "POST" }) and the wrappers that keep its signature
+    (re.compile(r"(?<![\w.$])(?:fetch|\$fetch|useFetch|ofetch)\s*\(\s*([\"'`])([^\"'`\n]*)\1"), "fetch"),
+    # .NET HttpClient (Blazor): Http.GetFromJsonAsync<T>("api/x"), PostAsJsonAsync, DeleteAsync
+    (re.compile(r"\b(Get|Post|Put|Patch|Delete)(?:FromJson|AsJson)?Async\s*(?:<[^()]*?>)?"
+                r"\s*\(\s*\$?\"([^\"]*)\""), "dotnet"),
+)
+# A member call's receiver that is a map, a URL or a router rather than an HTTP client.
+UI_RECV_SKIP_RE = re.compile(
+    r"^(?:map|params|searchparams|headers|cookies?|storage|localstorage|sessionstorage|"
+    r"cache|store|formdata|url|query|router|route|res|req|response|config|env|object|"
+    r"reflect|weakmap|set|i18n|translate|translations?)$", re.IGNORECASE)
+UI_TEST_FILE_RE = re.compile(
+    r"\.(?:spec|test|stories|e2e)\.[cm]?[jt]sx?$|(?:^|/)(?:__)?mocks?(?:__)?/", re.IGNORECASE)
+# Where a call sits: the function or method enclosing it, for a feature that imports it.
+UI_FN_DEF_RES = (
+    re.compile(r"\bfunction\s*\*?\s*([A-Za-z_$][\w$]*)\s*\("),
+    re.compile(r"\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?"
+               r"(?:function\b|\([^)]*\)\s*(?::[^=;{]+)?=>|[A-Za-z_$][\w$]*\s*=>)"),
+    re.compile(r"^[ \t]*(?:(?:public|private|protected|internal|static|async|readonly|override|"
+               r"virtual)\s+)*(?:[\w<>\[\],.?]+\s+)?([A-Za-z_]\w*)\s*(?:<[^<>()]*>)?\s*\([^)]*\)"
+               r"\s*(?::\s*[^{;=]+)?\{", re.M),
+    # C# expression-bodied members: public Task<X> ListAsync() => Http.Get…
+    re.compile(r"^[ \t]*(?:(?:public|private|protected|internal|static|async|override|virtual)"
+               r"\s+)+[\w<>\[\],.?]+\s+([A-Za-z_]\w*)\s*\([^)]*\)\s*=>", re.M),
+)
+UI_OBJECT_DECL_RE = re.compile(
+    r"^export\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=;]+)?=\s*\{", re.M)
+# Function names that say nothing about the call: the verb and the resource name it.
+# A React hook (useEncounters) is one of them — it says what a component reads, not
+# what the API does.
+UI_HOOK_RE = re.compile(r"^use[A-Z]")
+UI_GENERIC_FN = GENERIC_HANDLER | frozenset((
+    "request", "fetcher", "send", "api", "http", "client", "get", "post", "put", "patch",
+    "delete", "load", "fetch", "query", "mutate", "mutation", "queryfn", "mutationfn",
+    "default", "init", "ngoninit", "useeffect", "oninitializedasync", "oninitialized",
+    "onparameterssetasync", "onsubmit", "submit", "save", "setup", "mounted", "created"))
+
+
+def _ui_code(f):
+    return bool((_lang_of(f) or f.lower().endswith((".razor", ".cshtml")))
+                and not TEST_PATH_RE.search(f) and not UI_TEST_FILE_RE.search(f))
+
+
+def _ui_api_path(raw):
+    """A called URL as a route template: base-URL variables and query strings dropped,
+    template-literal parameters made {name}. "" when it is no API path — a translation
+    key, an asset, a page."""
+    p = (raw or "").strip()
+    if "/" not in p:
+        return ""
+    p = re.sub(r"^\$\{[^}]*\}", "", p)
+    p = re.sub(r"^https?://[^/]+", "", p)
+    p = re.split(r"[?#]", p)[0]
+    p = re.sub(r"\$\{\s*(?:[\w$]+\.)*([\w$]+)\s*\}", r"{\1}", p)
+    if not p or not re.fullmatch(r"[\w\-{}/.:~]+", p):
+        return ""
+    if re.search(r"\.[A-Za-z]{2,5}$", p.rsplit("/", 1)[-1]):
+        return ""
+    return p if p.startswith("/") else "/" + p
+
+
+def _api_segments(path):
+    """A called route's segments with the api/version lead dropped, parameters kept."""
+    out = []
+    for s in [s for s in path.strip("/").split("/") if s]:
+        if not out and (s.lower() in ("api", "rest", "graphql", "internal", "public")
+                        or re.fullmatch(r"v\d+", s.lower())):
+            continue
+        out.append(s)
+    return out
+
+
+# Route words that name an endpoint serving the platform, not the domain: health,
+# liveness and readiness probes, a ping, a status or version report. `metrics` is not
+# here — an analytics product's /metrics is a domain resource.
+INFRA_ROUTE_WORDS = frozenset((
+    "health", "healthz", "healthcheck", "health-check", "health_check", "live", "livez",
+    "liveness", "ready", "readyz", "readiness", "ping", "status", "version"))
+
+
+def _infra_route(path):
+    """Whether a route is an infrastructure endpoint: every segment below the api/version
+    lead is an INFRA_ROUTE_WORDS word (/healthz, /api/health, /health/ready). A domain
+    resource's own /status is not: /care/encounters/{id}/status has other segments."""
+    segs = _api_segments(path or "")
+    return bool(segs) and all(s.lower() in INFRA_ROUTE_WORDS for s in segs)
+
+
+def _is_param(seg):
+    return seg.startswith(("{", ":", "[", "<", "$"))
+
+
+def _route_key(verb, path):
+    """A route as a UI call and an endpoint both write it: the verb, and the path's
+    segments lower-cased with the api/version lead dropped and every parameter one `{}`
+    — `GET /api/care/encounters/${id}` and `GET /care/encounters/{id:guid}` are one
+    route."""
+    return ((verb or "").upper(),
+            "/".join("{}" if _is_param(s) else s.lower() for s in _api_segments(path)))
+
+
+def _ui_reached(calls, rec):
+    """The calls a UI feature makes: in its own files, through a function it imports,
+    or through a client or service it imports or is injected with. Where the feature's
+    code names methods of that client, only those count, so a generated client holding
+    every call of the API does not hand all of them to each feature using it; where it
+    names none (they are called from a template the scan does not read), all do."""
+    mine, used = set(rec["files"]), rec.get("idents", set())
+    named = {c["cls"] for c in calls if c["cls"] in rec["imports"] and c["fn"] in used}
+    return [c for c in calls if c["file"] in mine
+            or (c["fn"] and c["fn"] in rec["imports"])
+            or (c["cls"] and c["cls"] in rec["imports"]
+                and (c["cls"] not in named or not c["fn"] or c["fn"] in used))]
+
+
+def ui_api_calls(root, fe_files):
+    """Every API call the UI lane makes: [{file, verb, path, fn, cls}]."""
+    calls = []
+    for f in fe_files:
+        if not _ui_code(f):
+            continue
+        body = _code_only(f, _read_source(root, f))
+        if not body:
+            continue
+        # What a call is a member of: a class (an Angular or Blazor service) or an
+        # exported object of functions (export const encounterApi = { list: … }).
+        classes = sorted([(m.start(), m.group(1)) for m in CLASS_DECL_RE.finditer(body)] +
+                         [(m.start(), m.group(1)) for m in UI_OBJECT_DECL_RE.finditer(body)])
+        # A class with a primary constructor reads like a method; it is not one.
+        cnames = {n for _p, n in classes}
+        defs = sorted((m.start(), m.group(1)) for rx in UI_FN_DEF_RES for m in rx.finditer(body)
+                      if m.group(1) not in _HANDLER_SKIP and m.group(1) not in cnames)
+        for rx, role in UI_CALL_RES:
+            for m in rx.finditer(body):
+                if role == "member":
+                    if UI_RECV_SKIP_RE.match(m.group(1)):
+                        continue
+                    verb, raw = m.group(2).upper(), m.group(4)
+                elif role == "fetch":
+                    opt = re.match(r"[^)]{0,300}?\bmethod\s*:\s*[\"'`](\w+)[\"'`]", body[m.end():])
+                    verb, raw = (opt.group(1).upper() if opt else "GET"), m.group(2)
+                else:
+                    verb, raw = m.group(1).upper(), m.group(2)
+                path = _ui_api_path(raw)
+                # A health or ping poll calls the platform, not an operation.
+                if not path or _infra_route(path):
+                    continue
+                calls.append({
+                    "file": f, "verb": verb, "path": path,
+                    "fn": next((n for p, n in reversed(defs) if p < m.start()), ""),
+                    "cls": next((n for p, n in reversed(classes) if p < m.start()), ""),
+                })
+    return calls
+
+
+def ui_model(root, fe_files, ufeats, churn_map):
+    """The map of a project with no service lane, from its UI lane alone:
+    (candidates, operations). Rewrites each feature's `calls` to the operations it
+    reaches, which is how propose_features ties a feature to what it acts on.
+
+    A call whose route carries no context segment (/api/encounters) belongs to `Core`,
+    the name every strategy gives a tree with no context level — never the checkout
+    folder's name, which differs from one clone to the next."""
+    calls = ui_api_calls(root, fe_files)
+    by_first = {}
+    for c in calls:
+        segs = _api_segments(c["path"])
+        if segs and not _is_param(segs[0]):
+            by_first.setdefault(segs[0].lower(), []).append(segs)
+    # A leading segment is a CONTEXT when every route under it goes on to a literal
+    # resource name: /care/encounters/{id} — never /encounters/{id}.
+    prefixes = {s for s, lists in by_first.items()
+                if all(len(x) > 1 and not _is_param(x[1]) for x in lists)}
+
+    ops, cands = {}, {}
+    for c in calls:
+        segs = _api_segments(c["path"])
+        if not segs or _is_param(segs[0]):
+            continue
+        ctx_seg = segs[0] if segs[0].lower() in prefixes else ""
+        res = segs[1] if ctx_seg else segs[0]
+        agg = _pascal(singularize(res))
+        ctx = _pascal(ctx_seg) if ctx_seg else "Core"
+        if not agg:
+            continue
+        routes = [(c["verb"], c["path"])]
+        fn = c["fn"]
+        name = (_endpoint_name(fn, agg, routes)
+                if fn and fn.lower() not in UI_GENERIC_FN and not UI_HOOK_RE.match(fn)
+                and _ui_norm(agg) in _ui_norm(fn)
+                else _endpoint_name(None, agg, routes))
+        op = ops.setdefault(name, {"name": name, "context": ctx, "module": "", "files": [],
+                                   "acts_on": [agg], "routes": [], "kind": ""})
+        if c["file"] not in op["files"]:
+            op["files"].append(c["file"])
+        if routes[0] not in op["routes"]:
+            op["routes"].append(routes[0])
+        cand = cands.setdefault(agg, dict(_blank_candidate(c["file"], agg), context=ctx,
+                                          confidence="called", strategy="ui"))
+        if c["file"] not in cand["api_files"]:
+            cand["api_files"].append(c["file"])
+            cand["churn"] += churn_map.get(c["file"], 0)
+        c["op"] = name
+    for op in ops.values():
+        op["kind"] = _verb_kind(op["routes"]) or "query"
+        op["routes"] = sorted(op["routes"])
+        op["files"] = sorted(op["files"])
+
+    for rec in ufeats.values():
+        rec["calls"] = {c["op"] for c in _ui_reached(calls, rec) if "op" in c}
+    out = []
+    for c in cands.values():
+        files = sorted(set(c["api_files"]))
+        c["api_files"] = files[:CAP]
+        c.update(raw_file_count=len(files), covered_code=files, file_count=len(c["api_files"]),
+                 evidence_count=len(files), entities=[])
+        out.append(c)
+    out.sort(key=lambda c: (c["evidence_count"], c["churn"]), reverse=True)
+    return out, sorted(ops.values(), key=lambda o: (o["context"], o["name"]))
+
+
+def ui_reading(root, fe_files, ui_prefix, churn_map):
+    """A project with no service lane, read from its UI lane: (feature folders,
+    candidates, operations). propose draws the map from it and scan hands onboard the
+    same candidates, so both name the project's contexts and aggregates alike."""
+    ufeats = ui_features(root, fe_files, ui_prefix, declared=True)
+    cands, ops = ui_model(root, fe_files, ufeats, churn_map)
+    return ufeats, cands, ops
+
+
 def detect_operations(root, files, candidates):
     """Operations for a repo whose code declares no aggregate root: the slices under a
-    module's feature layer, and CQRS handler classes wherever they are. Each acts on
-    the candidate that owns most of its files — the only link available without a
-    declared model."""
+    module's feature layer, CQRS handler classes wherever they are, use cases and
+    endpoints (see _published_operations). Each acts on the candidate that owns most of
+    its files — the only link available without a declared model; an operation only an
+    endpoint declares is kept when that link exists."""
     children = _child_dirs(files)
     owner = _candidate_of_file(candidates)
+    text = {f: _code_only(f, _read_source(root, f)) for f in files
+            if _lang_of(f) and not TEST_PATH_RE.search(f)}
     op_files = {}
     for f in files:
-        if not _lang_of(f) or TEST_PATH_RE.search(f):
+        if f not in text:
             continue
         parts = f.split("/")
         _i, op = _feature_layer_op(parts[:-1], children, os.path.splitext(parts[-1])[0])
         if op:
             op_files.setdefault(op, []).append(f)
             continue
-        for m in HANDLER_CLASS_RE.finditer(_code_only(f, _read_source(root, f)) if f.endswith(
+        for m in HANDLER_CLASS_RE.finditer(text[f] if f.endswith(
                 (".cs", ".java", ".kt", ".ts", ".py")) else ""):
             op_files.setdefault(m.group(1), []).append(f)
+    pub = _published_operations(text, children)
+    for op, fs in pub["usecases"].items():
+        lst = op_files.setdefault(op, [])
+        lst += [f for f in fs if f not in lst]
     ops = []
-    for op, fs in sorted(op_files.items()):
+    for op in sorted(set(op_files) | set(pub["endpoints"])):
+        fs = op_files.get(op, [])
+        served = pub["endpoints"].get(op, {})
+        shared = set(served.get("files", ()))
+        allf = sorted(set(fs) | shared)
         votes = {}
-        for f in fs:
+        for f in allf:
             if owner.get(f):
                 votes[owner[f]] = votes.get(owner[f], 0) + 1
+        if not fs and not votes:
+            continue
         routes = []
         for f in fs:
-            routes.extend(_routes_in(_read_source(root, f)))
-        ops.append({"name": op, "context": "", "module": "", "files": sorted(set(fs)),
+            if f not in shared:
+                routes.extend(_routes_in(_read_source(root, f)))
+        routes += list(served.get("routes", ()))
+        ids = list(served.get("ids", ()))
+        ids += [i for i in _declared_ids([(f, text[f]) for f in fs if f not in shared])
+                if i not in ids]
+        ops.append({"name": op, "context": "", "module": "", "files": allf,
                     "acts_on": [max(sorted(votes), key=votes.get)] if votes else [],
-                    "kind": "query" if QUERY_NAME_RE.match(op) else "command",
-                    "routes": sorted(set(routes))})
+                    "kind": _verb_kind(served.get("routes", ())) or
+                            ("query" if QUERY_NAME_RE.match(op) else "command"),
+                    "routes": sorted(set(routes)), "operation_ids": ids})
     return ops
 
 
@@ -2930,11 +4507,14 @@ def attribute_ui_files(signals, fe_files, churn_map, ui_roots, feature_aggs=None
     frontend lane's design has nothing to be derived from.
 
     THE CONFIRMED MAP FIRST. `feature_aggs` is {feature: [aggregates it acts on]} from
-    the feature map the operator confirmed. A file under a UI `features/<Feature>/`
-    folder the map names serves exactly those aggregates — every one of them, since a
-    feature may act on several — whatever the file is called. A capability is named for
-    what the user does (RecordEncounter, PlaceMedicationOrder), so matching its folder
-    against aggregate names alone leaves the lane's own feature folders unattributed.
+    the feature map the operator confirmed. A file in a UI feature the map names serves
+    exactly those aggregates — every one of them, since a feature may act on several —
+    whatever the file is called. A file belongs to the feature ui_features read it into:
+    its `features/<Feature>/` folder, or in a frontend without one its module, route or
+    page folder (`views/OrdersView.vue` → Orders). Every source file of such a feature
+    counts, its hooks, services and loaders included. A capability is named for what the
+    user does (RecordEncounter, PlaceMedicationOrder), so matching its folder against
+    aggregate names alone leaves the lane's own feature folders unattributed.
 
     Everything else is matched by NAME with both sides normalised: a DIRECTORY SEGMENT named for the
     concept (the strong signal — a feature folder), or a filename whose concept stem
@@ -2966,10 +4546,34 @@ def attribute_ui_files(signals, fe_files, churn_map, ui_roots, feature_aggs=None
     prefixes = [] if any(r in ("./", "/") for r in roots) else roots
     in_lane = fe_files if not prefixes else [
         f for f in fe_files if any(f.startswith(p) for p in prefixes)]
+
+    # {normalised feature: [candidates]} — only features whose aggregates the scan found.
+    by_name = {c["name"]: c for c in signals}
+    served_by = {}
+    for feat, aggs in (feature_aggs or {}).items():
+        cs = [by_name[a] for a in aggs if a in by_name]
+        if cs:
+            served_by[_ui_norm(feat)] = cs
+
+    # Which feature a file belongs to, by the rule ui_features read the lane with: its
+    # features/<Feature>/ folder, or the module, route or page folder of a frontend
+    # without one. Decided per search root, from that root's source files.
+    lane_src = [f for f in in_lane if UI_SOURCE_RE.search(f)]
+    layouts = {p: ui_feature_layout([(f, f[len(p):]) for f in lane_src if f.startswith(p)])
+               for p in (prefixes or [""])}
+
+    def mapped(f):
+        p = next((p for p in prefixes if f.startswith(p)), "")
+        hit = ui_feature_of(f[len(p):], layouts.get(p, ""))
+        return served_by.get(_ui_norm(hit[0])) if hit else None
+
+    # The UI files: the lane's components, markup, styles, routes and stores, and every
+    # source file of a feature the map names — its hooks, services, loaders and script
+    # components are that feature's surface as much as its templates.
     ui_files = sorted(set(
         matching(in_lane, UI_COMPONENT_RE) + matching(in_lane, UI_MARKUP_RE)
         + matching(in_lane, UI_STYLE_RE) + matching(in_lane, UI_ROUTE_RE)
-        + matching(in_lane, UI_STORE_RE)
+        + matching(in_lane, UI_STORE_RE) + [f for f in lane_src if mapped(f)]
     ))
     if not ui_files:
         return {"attributed_file_count": 0, "aggregates_with_ui": 0,
@@ -2981,19 +4585,6 @@ def attribute_ui_files(signals, fe_files, churn_map, ui_roots, feature_aggs=None
     for c, _ in token_map:
         c.setdefault("ui_files", [])
 
-    # {normalised feature: [candidates]} — only features whose aggregates the scan found.
-    by_name = {c["name"]: c for c in signals}
-    served_by = {}
-    for feat, aggs in (feature_aggs or {}).items():
-        cs = [by_name[a] for a in aggs if a in by_name]
-        if cs:
-            served_by[_ui_norm(feat)] = cs
-
-    def mapped(f):
-        p = next((p for p in prefixes if f.startswith(p)), "")
-        m = UI_FEATURE_SEG_RE.search(f[len(p):])
-        return served_by.get(_ui_norm(m.group(1))) if m else None
-
     unattributed, attributed_files, by_map = [], set(), 0
     for f in ui_files:
         owners = mapped(f)
@@ -3046,6 +4637,16 @@ def _feature_aggregates(map_path):
     return out
 
 
+def _map_strategy(map_path):
+    """The Pass A strategy a feature map was built from, or "" when there is no map."""
+    try:
+        with open(map_path, encoding="utf-8") as fh:
+            m = json.load(fh)
+    except (OSError, ValueError):
+        return ""
+    return (m.get("strategy") or "") if isinstance(m, dict) else ""
+
+
 # What each lane's steps do not need from the substrate. The service view drops the UI
 # lane's signals; the UI view drops the backend's aggregates and its API/data listings.
 _SERVICE_ONLY_KEYS = ("aggregate_signals", "route_like_files", "data_layer_files")
@@ -3134,13 +4735,32 @@ def scope_to_lanes(files, service_root, ui_root):
     return be, fe, svc, ui
 
 
+def built_lanes(root, service_root, ui_root):
+    """The lane roots to read: (service_root, ui_root, unbuilt).
+
+    A lane can be declared before it is built — a frontend planned beside a service that
+    exists, or the reverse — and its lane root folder holds nothing to read until then.
+    While another declared lane is on disk, a lane root folder that is not is read as
+    undeclared, and `unbuilt` names it as (kind, folder) so what was not read is said.
+    When no declared lane is on disk the roots are returned as declared, so the scan reads
+    nothing rather than the whole repository."""
+    svc, ui = (service_root or "").strip(), (ui_root or "").strip()
+    missing = [(kind, p) for kind, p in (("service", _lane_prefix(svc)), ("UI", _lane_prefix(ui)))
+               if p and not os.path.isdir(os.path.join(root, p))]
+    if len(missing) == bool(svc) + bool(ui):
+        return svc, ui, []
+    gone = {kind for kind, _ in missing}
+    return ("" if "service" in gone else svc), ("" if "UI" in gone else ui), missing
+
+
 def cmd_scan(args):
     root = os.path.abspath(args.root or os.getcwd())
     config_excludes = load_config_excludes(args.config) + kit_excludes(root)
     out = os.path.abspath(args.out) if args.out else os.path.join(root, ".appweaver", "inventory", "inventory.json")
     bundle_dir = os.path.abspath(args.bundle) if args.bundle else os.path.join(root, "knowledge")
 
-    files = list_files(root, config_excludes, (args.service_root, args.ui_root))
+    service_root, ui_root, _ = built_lanes(root, args.service_root, args.ui_root)
+    files = list_files(root, config_excludes, (service_root, ui_root))
     churn_list, commits_scanned = churn(root, config_excludes)
     churn_map = {c["file"]: c["commits"] for c in churn_list}
 
@@ -3177,9 +4797,23 @@ def cmd_scan(args):
         "config_files": category(CONFIGS_RE),
         "adr_docs": category(ADR_RE),
     }
-    be_files, fe_files, svc_prefix, ui_prefix = scope_to_lanes(
-        files, args.service_root, args.ui_root)
-    signals = aggregate_signals(be_files, churn_map, root)
+    be_files, fe_files, svc_prefix, ui_prefix = scope_to_lanes(files, service_root, ui_root)
+    # A lane declared at the repo root has the empty prefix and is declared all the same;
+    # its lane root folder is reported as `./`.
+    svc_shown = svc_prefix or ("./" if service_root else "")
+    ui_shown = ui_prefix or ("./" if ui_root else "")
+    mp = os.path.abspath(args.map) if args.map else os.path.join(
+        root, ".appweaver", "inventory", "feature-map.json")
+    # A UI lane and no service lane is read the way propose reads it: the candidates are
+    # the API resources the UI calls, and there is no backend. A UI lane at the repo root
+    # would otherwise have its components read as service code. A service lane is read
+    # with the strategy its map was built from, so the substrate names the aggregates
+    # the map does.
+    if ui_root and not service_root:
+        be_files = []
+        _, signals, _ = ui_reading(root, fe_files, ui_prefix, churn_map)
+    else:
+        signals = aggregate_signals(be_files, churn_map, root, _map_strategy(mp))
     fsig = frontend_signals(fe_files, churn_map)
 
     # A DECLARED UI lane is a lane. The strength test below UI_STRONG_MIN exists to
@@ -3188,13 +4822,13 @@ def cmd_scan(args):
     # evidence still decides is what goes IN the governance — and a declared root
     # holding no recognisable UI files is reported as exactly that, so onboard can
     # say so rather than quietly authoring a UI half out of nothing.
-    if ui_prefix:
-        fsig["declared_root"] = ui_prefix
+    if ui_root:
+        fsig["declared_root"] = ui_shown
         fsig["ui_evidence_found"] = bool(fsig.get("roots"))
         fsig["present"] = True
         fsig["separable"] = ui_prefix not in ("", "./") and not svc_prefix.startswith(ui_prefix)
         if not fsig.get("roots"):
-            fsig["roots"] = [{"root": ui_prefix, "kind": "declared", "confidence": "declared",
+            fsig["roots"] = [{"root": ui_shown, "kind": "declared", "confidence": "declared",
                               "counts": {"component": 0}, "framework_markers": [],
                               "component_files": [], "style_files": [], "markup_files": [],
                               "build_configs": [], "route_files": [], "store_files": []}]
@@ -3204,14 +4838,12 @@ def cmd_scan(args):
     # declaration the roots the scan actually found stand in, which keeps a repo whose
     # UI is server-rendered inside the service tree covered. With neither, this repo
     # has no frontend and the pass does not run at all.
-    if ui_prefix:
-        ui_search_roots = [ui_prefix]
+    if ui_root:
+        ui_search_roots = [ui_shown]
     elif fsig.get("present"):
         ui_search_roots = [r.get("root", "") for r in (fsig.get("roots") or [])]
     else:
         ui_search_roots = []
-    mp = os.path.abspath(args.map) if args.map else os.path.join(
-        root, ".appweaver", "inventory", "feature-map.json")
     ui_attr = attribute_ui_files(signals, fe_files, churn_map, ui_search_roots,
                                  _feature_aggregates(mp))
 
@@ -3234,8 +4866,8 @@ def cmd_scan(args):
         "cap": CAP,
         # The lane scoping this substrate was built under, so a reader can tell a
         # repo with no backend aggregates from one whose backend was scoped away.
-        "declared_service_root": svc_prefix,
-        "declared_ui_root": ui_prefix,
+        "declared_service_root": svc_shown,
+        "declared_ui_root": ui_shown,
         "scoped_file_counts": {"backend": len(be_files), "frontend": len(fe_files),
                                "repo": len(files)},
         "language_histogram": lang_hist,
@@ -3320,8 +4952,8 @@ def cmd_scan(args):
         # actually held any UI. A declared lane stays a lane either way; this is how
         # onboard tells "reverse-engineered from real UI source" from "declared, but
         # there is nothing here to reverse".
-        "declared_service_root": svc_prefix,
-        "declared_ui_root": ui_prefix,
+        "declared_service_root": svc_shown,
+        "declared_ui_root": ui_shown,
         "ui_evidence_found": "true" if fsig.get("ui_evidence_found", bool(fsig["roots"])) else "false",
         "backend_file_count": len(be_files),
         "frontend_file_count": len(fe_files),
@@ -3435,16 +5067,22 @@ def _names_preview(cands, limit=4):
     return ", ".join(names[:limit]) + (" …" if len(names) > limit else "")
 
 
-def _scanned_line(files, be, fe, svc, ui):
-    """What the scan read, lane by lane. The repository's own tooling, docs and kit files
+def _scanned_line(files, be, fe, svc, ui, ui_only=False, unbuilt=()):
+    """What the scan read, lane by lane, and each declared lane it did not read because its
+    lane root folder does not exist yet. The repository's own tooling, docs and kit files
     sit outside both lanes and are read by nothing here, so a repository-wide file count
     would overstate the scan."""
+    later = "".join(f" · {kind} lane `{p}` is declared and has no folder yet"
+                    for kind, p in unbuilt)
+    if ui_only:
+        return (f"UI lane `{ui or './'}` — {len(fe)} files, {sum(1 for f in fe if _ui_code(f))} "
+                f"source" + (later or " · no service lane is declared"))
     be_src = sum(1 for f in be if CODE_EXT_RE.search(f))
     if not svc and not ui:
-        return f"the whole repository — {len(files)} files, {be_src} source"
+        return f"the whole repository — {len(files)} files, {be_src} source" + later
     head = (f"service lane `{svc}` — {len(be)} files, {be_src} source" if svc else
             f"everything outside `{ui}` — {len(be)} files, {be_src} source")
-    return head + (f" · UI lane `{ui}` — {len(fe)} files" if ui else "")
+    return head + (f" · UI lane `{ui}` — {len(fe)} files" if ui else "") + later
 
 
 def _write_proposal(path, meta, contexts, features, waves, cycles, probe_rows,
@@ -3528,21 +5166,24 @@ def _write_proposal(path, meta, contexts, features, waves, cycles, probe_rows,
     operation_table = ""
     if operations:
         operation_table = _md_table(
-            ["Operation", "Kind", "Acts on", "Route", "Feature(s)"],
+            ["Operation", "Kind", "Acts on", "Route", "Published id", "Feature(s)"],
             [[o["name"], o["kind"], ", ".join(o["acts_on"]) or "—",
               " · ".join(f"{v} {p}".strip() for v, p in o["routes"][:2]) or "—",
+              ", ".join(f"`{i}`" for i in o.get("operation_ids") or []) or "—",
               ", ".join(o.get("features", [])) or "—"]
              for o in sorted(operations, key=lambda o: (o["context"], (o["acts_on"] or [""])[0],
                                                         o["name"]))])
     else:
-        operation_table = ("_No operations were found — no feature layer of slices and no "
-                           "command/query handler classes. Features below are one per "
-                           "aggregate by default._")
+        operation_table = ("_No operations were found — no feature layer of slices, no "
+                           "command/query handler classes, no use cases and no endpoints "
+                           "acting on an aggregate. Features below are one per aggregate "
+                           "by default._")
 
     review_section = ""
     orphaned = (notes or {}).get("orphaned") or []
     unlinked = (notes or {}).get("unlinked_ui") or []
-    if orphaned or unlinked:
+    unserved = (notes or {}).get("unserved_ui") or []
+    if orphaned or unlinked or unserved:
         lines = ["\n## Needs a decision\n"]
         if orphaned:
             lines.append("These commands act on an aggregate that has capability features, "
@@ -3552,9 +5193,27 @@ def _write_proposal(path, meta, contexts, features, waves, cycles, probe_rows,
                          "it is.\n")
             lines.append(_md_table(["Default feature", "Operation"], orphaned) + "\n")
         if unlinked:
-            lines.append("These UI feature folders call no operation the scan could tie to an "
-                         "aggregate, so no feature was proposed for them: "
-                         + ", ".join(f"`features/{u}/`" for u in unlinked) + ".\n")
+            folders = all(r.endswith("/") for roots in unlinked for r in roots)
+            lines.append(f"These UI {'feature folders' if folders else 'features'} call no "
+                         "operation the scan could tie to an aggregate, so no feature was "
+                         "proposed for them: "
+                         + ", ".join(f"`{roots[0]}`" + (f" (+{len(roots) - 1} more)"
+                                                       if len(roots) > 1 else "")
+                                     for roots in unlinked) + ".\n")
+        if unserved:
+            lines.append("These calls the UI lane makes match no route the service lane "
+                         "declares, so no operation was linked through them. A gateway or "
+                         "proxy prefix the scan did not strip, an endpoint not built yet, or "
+                         "an API served from somewhere else all look like this. Where a call "
+                         "does reach an operation above that its feature does not list yet, "
+                         "add the operation to that feature's Operations cell.\n")
+            lines.append(_md_table(
+                ["UI call", "Feature(s)", "Called in"],
+                [[f"`{call}`", ", ".join(fs) or "—",
+                  ", ".join(f"`{f}`" for f in files[:2]) + (" …" if len(files) > 2 else "")]
+                 for call, fs, files in unserved[:UNPLACED_ROWS]])
+                + (f"\n\n…and {len(unserved) - UNPLACED_ROWS} more."
+                   if len(unserved) > UNPLACED_ROWS else "") + "\n")
         review_section = "\n".join(lines)
 
     # Both trailing sections are conditional and carry their own leading blank line,
@@ -3639,62 +5298,173 @@ def _pascal(s):
     return "".join(w[:1].upper() + w[1:] for w in words if w)
 
 
-def _read_frontmatter(path):
-    """Return the concept's frontmatter dict (title/type/source_files), best-effort
-    without a YAML dependency. Only the fields adopt needs."""
-    try:
-        with open(path, encoding="utf-8") as f:
-            text = f.read()
-    except OSError:
-        return {}
+FM_KEY_RE = re.compile(r"^([A-Za-z0-9_]+):\s*(.*)$")
+FM_ITEM_RE = re.compile(r"^\s*-\s+")
+
+
+def _flow_list(text):
+    """The items of a YAML flow sequence (`[a, "b, c"]`, `[]`), or None when `text` is not
+    one whole sequence — `[draft] notes` is text, and so is a `[` that never closes. Items
+    are split on the commas outside quotes and unquoted; a trailing `# comment` after the
+    closing bracket is ignored."""
+    if not text.startswith("["):
+        return None
+    items, cur, quote, i = [], "", "", 1
+    while i < len(text):
+        ch = text[i]
+        if quote:
+            if ch == "\\" and quote == '"' and i + 1 < len(text):
+                cur, i = cur + text[i + 1], i + 2
+                continue
+            if ch == quote:
+                quote = ""
+            else:
+                cur += ch
+        elif ch in "'\"":
+            quote = ch
+        elif ch == ",":
+            items.append(cur.strip())
+            cur = ""
+        elif ch == "]":
+            rest = text[i + 1:].strip()
+            if rest and not rest.startswith("#"):
+                return None
+            items.append(cur.strip())
+            return [s for s in items if s]
+        else:
+            cur += ch
+        i += 1
+    return None
+
+
+def parse_frontmatter(text):
+    """(frontmatter dict, body) of a concept, without a YAML dependency. The one reader
+    every script that reads a concept uses (aw-xref loads it from here), so a concept's
+    lists read the same everywhere.
+
+    A list is read in either YAML form: block — `key:` then `  - item` lines, with the
+    `# group` comment lines between items skipped — or flow — `key: [a, b]`, `key: []`,
+    which may run over several lines to its closing `]`. Any other value is text with its
+    quotes removed, and a key with nothing after it is an empty list."""
     if not text.startswith("---"):
-        return {}
+        return {}, text
     lines = text.splitlines()
     end = next((i for i in range(1, len(lines)) if lines[i].strip() == "---"), None)
     if end is None:
-        return {}
-    data, key = {}, None
-    for ln in lines[1:end]:
-        m = re.match(r"^([A-Za-z0-9_]+):\s*(.*)$", ln)
+        return {}, text
+    fm_lines = lines[1:end]
+    data, key, i = {}, None, 0
+    while i < len(fm_lines):
+        ln = fm_lines[i]
+        i += 1
+        m = FM_KEY_RE.match(ln)
         if m:
             key = m.group(1)
             val = m.group(2).strip()
+            if val.startswith("["):
+                joined, j = val, i
+                while (_flow_list(joined) is None and "]" not in joined.split("#")[0]
+                       and j < len(fm_lines) and not FM_KEY_RE.match(fm_lines[j])):
+                    joined, j = joined + " " + fm_lines[j].strip(), j + 1
+                items = _flow_list(joined)
+                if items is not None:
+                    data[key], i = items, j
+                    continue
             data[key] = val.strip("'\"") if val else []
-        elif key and re.match(r"^\s*-\s+", ln):  # a list item under the last key
+        elif key and FM_ITEM_RE.match(ln):  # a list item under the last key
             if not isinstance(data.get(key), list):
                 data[key] = []
-            data[key].append(re.sub(r"^\s*-\s+", "", ln).strip().strip("'\""))
-    return data
+            data[key].append(FM_ITEM_RE.sub("", ln).strip().strip("'\""))
+    return data, "\n".join(lines[end + 1:])
+
+
+def fm_list(value):
+    """A frontmatter list field as its non-empty strings. A single value where a list
+    belongs (`source_files: src/a.cs`) is a one-item list, never its characters."""
+    if isinstance(value, list):
+        return [s for s in value if isinstance(s, str) and s.strip()]
+    return [value] if isinstance(value, str) and value.strip() else []
+
+
+def _read_frontmatter(path):
+    """A concept file's frontmatter dict (see parse_frontmatter), {} when unreadable."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            return parse_frontmatter(f.read())[0]
+    except OSError:
+        return {}
 
 
 def cmd_propose(args):
     """Pass A + B + C over the repo: write the editable boundary map, and the
-    machine map onboard reads until the operator edits the first one."""
+    machine map onboard reads until the operator edits the first one.
+
+    A project that declares a UI lane and no service lane — a front end whose API
+    lives in another repository — is read from the UI lane alone (`ui`, see
+    ui_model): there is no service source for Pass A to read, and reading the UI's
+    source as if it were would draw aggregates out of components. A declared lane whose
+    lane root folder does not exist yet is read as undeclared beside one that does (see
+    built_lanes), and the proposal names it."""
     root = os.path.abspath(args.root or os.getcwd())
     excludes = load_config_excludes(args.config) + kit_excludes(root)
-    files = list_files(root, excludes, (args.service_root, args.ui_root))
-    be_files, fe_files, svc_prefix, ui_prefix = scope_to_lanes(
-        files, args.service_root, args.ui_root)
+    service_root, ui_root, unbuilt = built_lanes(root, args.service_root, args.ui_root)
+    files = list_files(root, excludes, (service_root, ui_root))
+    be_files, fe_files, svc_prefix, ui_prefix = scope_to_lanes(files, service_root, ui_root)
     churn_list, _ = churn(root, excludes)
     churn_map = {c["file"]: c["commits"] for c in churn_list}
-
-    results, avail, graph, gstats, ents, model = run_probe(root, be_files, churn_map)
-    # The menu hands back the whole option line, numbers and all, so the first
-    # token is the strategy and the rest is what the operator was shown.
-    wanted = (args.strategy or "").strip().split()[0].strip("`*_-").lower() if args.strategy else ""
+    ui_only = bool(ui_root) and not service_root
+    no_service = next((f"the service lane `{p}` has no folder yet" for k, p in unbuilt
+                       if k == "service"), "no service lane is declared")
+
+    if ui_only:
+        ufeats, ui_cands, ui_ops = ui_reading(root, fe_files, ui_prefix, churn_map)
+        ui_code = [f for f in fe_files if _ui_code(f)]
+        covered = {f for r in ufeats.values() for f in r["files"]} | \
+            {f for c in ui_cands for f in c["covered_code"]}
+        why_not = f"{no_service} — the map is read from the UI lane"
+        avail = {n: {"available": False, "reason": why_not} for n in STRATEGY_PREFERENCE}
+        avail["ui"] = {"available": bool(ui_cands), "reason":
+                       f"{no_service}: the resources the UI lane calls are the "
+                       "aggregates it works on, its feature folders the capabilities"}
+        results = {"ui": {
+            "candidates": ui_cands, "count": len(ui_cands),
+            "coverage_pct": round(100.0 * len(covered & set(ui_code)) / max(1, len(ui_code)), 1),
+            "singletons": sum(1 for c in ui_cands if c["raw_file_count"] <= 1),
+            "available": True, "reason": avail["ui"]["reason"], "operations": len(ui_ops),
+        }} if ui_cands else {}
+        graph, gstats, model = {}, {}, None
+    else:
+        results, avail, graph, gstats, ents, model = run_probe(root, be_files, churn_map)
+    # --strategy carries the operator's request (`persistence focus on billing`), or the
+    # menu's whole option line, numbers and all. Its first word forces a strategy when it
+    # names one; any other first word forces nothing, and the strategy is chosen as if
+    # none were asked for.
+    words = (args.strategy or "").split()
+    wanted = words[0].strip("`*_-").lower() if words else ""
+    if wanted not in STRATEGY_PREFERENCE + ("ui",):
+        wanted = ""
     if wanted:
         if wanted not in results:
-            reason = avail.get(wanted, {}).get("reason", "not a known strategy")
+            # Every strategy but `ui` has an availability reason of its own.
+            reason = avail.get(wanted, {}).get("reason", "it reads a project with no service lane")
             print(json.dumps({"ok": "false", "error":
                               f"strategy '{wanted}' is not available here — {reason}"}))
             return 1
         picked = wanted
+    elif ui_only:
+        picked = "ui" if results else ""
     else:
         picked = choose_strategy(results)
 
     md = os.path.abspath(args.out) if args.out else os.path.join(root, "specs", "proposed-inventory.md")
     mp = os.path.abspath(args.map) if args.map else os.path.join(root, ".appweaver", "inventory", "feature-map.json")
-    code_total = len([f for f in be_files if CODE_EXT_RE.search(f)])
+    code_total = len(ui_code) if ui_only else len([f for f in be_files if CODE_EXT_RE.search(f)])
+    if not picked and ui_only:
+        return _nothing_to_propose(
+            root, mp, f"{no_service[:1].upper()}{no_service[1:]}, and the UI lane '{ui_prefix or './'}' "
+                      f"({len(fe_files)} file(s), {code_total} of them source) calls no API "
+                      f"route the scan could read, so it names no aggregate to propose "
+                      f"({len(ufeats)} feature folder(s) found).")
     if not picked:
         why = "; ".join(f"{n}: {avail[n]['reason']}" for n in STRATEGY_PREFERENCE)
         return _nothing_to_propose(
@@ -3703,20 +5473,40 @@ def cmd_propose(args):
                       f"source) — {why}.")
 
     candidates = results[picked]["candidates"]
-    contexts = derive_contexts(candidates, be_files)
-    # Declared aggregates are ordered by what their types reference, not by imports: in
-    # a namespace language every file of one Domain folder shares a namespace, so the
-    # import graph links each root to every other and reads as one cycle.
-    edges = (model["root_edges"] if picked == "domain"
-             else candidate_edges(candidates, graph))
-    seams = seam_overlay(root, be_files, candidates, churn_map, contexts=contexts)
-    operations = (model["operations"] if picked == "domain"
-                  else detect_operations(root, be_files, candidates))
+    if ui_only:
+        contexts = derive_contexts(candidates, fe_files)
+        edges, seams, operations = {}, {}, ui_ops
+    else:
+        contexts = derive_contexts(candidates, be_files)
+        # Declared aggregates are ordered by what their types reference, not by imports:
+        # in a namespace language every file of one Domain folder shares a namespace, so
+        # the import graph links each root to every other and reads as one cycle.
+        edges = (model["root_edges"] if picked == "domain"
+                 else candidate_edges(candidates, graph))
+        seams = seam_overlay(root, be_files, candidates, churn_map, contexts=contexts)
+        operations = (model["operations"] if picked == "domain"
+                      else detect_operations(root, be_files, candidates))
+        # Ids the lane publishes by route fill an operation whose endpoint declares none:
+        # its doc comments first, then the API documents it keeps. The code is what the
+        # service runs, and a checked-in document can be stale; documents that disagree
+        # with each other are all kept, so the conflict shows.
+        in_code, in_docs = published_ids(root, be_files)
+        for o in operations:
+            ids = o.setdefault("operation_ids", [])
+            for source in (in_code, in_docs):
+                if ids:
+                    break
+                for v, p in o["routes"]:
+                    ids += [i for i in source.get(_route_key(v, p), ()) if i not in ids]
     ctx_of = {n: ctx for ctx, names in contexts.items() for n in names}
     for o in operations:
         o["context"] = o["context"] or ctx_of.get((o["acts_on"] or [""])[0], "")
-    ufeats = ui_features(root, fe_files, ui_prefix)
-    features, notes = propose_features(candidates, seams, edges, contexts, operations, ufeats)
+    ui_calls = None
+    if not ui_only:
+        ufeats = ui_features(root, fe_files, ui_prefix)
+        ui_calls = ui_api_calls(root, fe_files) if ui_prefix else []
+    features, notes = propose_features(candidates, seams, edges, contexts, operations, ufeats,
+                                       ui_calls)
     for o in operations:
         o["features"] = [f["feature"] for f in features if o["name"] in f["operations"]]
     if not features:
@@ -3731,21 +5521,28 @@ def cmd_propose(args):
     wave_of = {m: w["wave"] for w in waves for m in w["members"]}
     features.sort(key=lambda f: (wave_of.get(f["feature"], 99), f["context"], f["feature"]))
 
-    lane_files = len(set(be_files) | set(fe_files)) if (svc_prefix or ui_prefix) else len(files)
+    lane_files = len(fe_files) if ui_only else \
+        len(set(be_files) | set(fe_files)) if (svc_prefix or ui_prefix) else len(files)
     meta = {"root": root, "head": git(root, "rev-parse", "--short", "HEAD") or "-",
             "date": datetime.date.today().isoformat(), "strategy": picked,
             "reason": results[picked]["reason"], "files": lane_files,
             "code": code_total, "coverage": results[picked]["coverage_pct"],
-            "scanned": _scanned_line(files, be_files, fe_files, svc_prefix, ui_prefix)}
+            "scanned": _scanned_line(files, be_files, fe_files, svc_prefix, ui_prefix, ui_only,
+                                     unbuilt)}
+    shown = STRATEGY_PREFERENCE + (("ui",) if ui_only else ())
     probe_rows = [[n, results[n]["count"], _names_preview(results[n]["candidates"]),
                    f"{results[n]['coverage_pct']}%",
                    results[n]["singletons"], "**yes**" if n == picked else "",
                    results[n]["reason"]] if n in results else
                   [n, "—", "—", "—", "—", "", f"unavailable — {avail[n]['reason']}"]
-                  for n in STRATEGY_PREFERENCE]
+                  for n in shown]
     covered = {f for c in candidates for f in c.get("covered_code", [])}
-    unplaced = sorted(f for f in be_files if CODE_EXT_RE.search(f) and f not in covered
-                      and not TEST_PATH_RE.search(f))
+    if ui_only:
+        covered |= {f for r in ufeats.values() for f in r["files"]}
+        unplaced = sorted(f for f in ui_code if f not in covered)
+    else:
+        unplaced = sorted(f for f in be_files if CODE_EXT_RE.search(f) and f not in covered
+                          and not TEST_PATH_RE.search(f))
     aggregate_detail = [
         {"name": c["name"], "context": ctx_of.get(c["name"], ""),
          "root_file": c.get("root_file", ""), "declared": picked == "domain",
@@ -3759,6 +5556,20 @@ def cmd_propose(args):
     _write_feature_map(mp, meta, contexts, features, waves, cycles, results, avail, gstats,
                        operations=operations, aggregate_detail=aggregate_detail)
 
+    # One option line per AVAILABLE strategy, each carrying its own numbers so the pick is
+    # made against evidence, the strategy this run used first: a run that cannot ask takes
+    # the first option, which is the proposal. A strategy that would return nothing is never
+    # offered — an empty pick is the zero-candidate stop by choice. A strategy the request
+    # named is also returned on its own, as `forced_option`, for the menu to take unasked.
+    options = [
+        f"{n} — {results[n]['count']} aggregates ({_names_preview(results[n]['candidates'])}), "
+        f"{results[n]['coverage_pct']}% coverage, {results[n]['singletons']} singleton(s)"
+        + ("  [declared by the code]" if n == "domain" else "")
+        + ("  [owns/references available]" if n == "persistence" else "")
+        + ("  [called by the UI lane]" if n == "ui" else "")
+        for n in sorted((n for n in shown if n in results), key=lambda n: n != picked)
+    ]
+
     print(f"Proposed inventory written to {md}", file=sys.stderr)
     print(f"  strategy: {picked}  contexts: {len(contexts)}  aggregates: {len(candidates)}  "
           f"features: {len(features)}  operations: {len(operations)}  waves: {len(waves)}",
@@ -3773,17 +5584,9 @@ def cmd_propose(args):
         "contexts_ordered": ", ".join(_ordered_contexts(contexts, features, waves)),
         "coverage_pct": results[picked]["coverage_pct"],
         "split_candidates": sum(1 for f in features if f["split_proposed"]),
-        # One option line per AVAILABLE strategy, each carrying its own numbers so
-        # the pick is made against evidence. A strategy that would return nothing
-        # is never offered — an empty pick is the zero-candidate stop by choice.
         "unplaced_count": len(unplaced),
-        "strategy_options": [
-            f"{n} — {results[n]['count']} aggregates ({_names_preview(results[n]['candidates'])}), "
-            f"{results[n]['coverage_pct']}% coverage, {results[n]['singletons']} singleton(s)"
-            + ("  [declared by the code]" if n == "domain" else "")
-            + ("  [owns/references available]" if n == "persistence" else "")
-            for n in STRATEGY_PREFERENCE if n in results
-        ],
+        "strategy_options": options,
+        "forced_option": options[0] if wanted else "",
     }))
     return 0
 
@@ -3854,6 +5657,7 @@ def _write_feature_map(path, meta, contexts, features, waves, cycles,
              "routes": [f"{v} {p}".strip() for v, p in o.get("routes", [])]
                        if o.get("routes") and isinstance(o["routes"][0], (list, tuple))
                        else list(o.get("routes", [])),
+             "operation_ids": list(o.get("operation_ids") or []),
              "files": len(o["files"]) if isinstance(o.get("files"), list) else o.get("files", 0),
              "features": [f["feature"] for f in features if o["name"] in f.get("operations", [])]}
             for o in operations]
@@ -4333,8 +6137,7 @@ def cmd_concept(args):
                 if not is_match:
                     continue
                 typ = fm.get("type") if isinstance(fm.get("type"), str) else ""
-                sf = [s for s in (fm.get("source_files") or []) if isinstance(s, str) and s.strip()]
-                usf = [s for s in (fm.get("ui_source_files") or []) if isinstance(s, str) and s.strip()]
+                sf, usf = fm_list(fm.get("source_files")), fm_list(fm.get("ui_source_files"))
                 score = (2 if "aggregate" in typ.lower() else 0) + (1 if _slug(base) == want else 0)
                 cand = {"concept_path": os.path.relpath(path, os.getcwd()),
                         "title": title or base, "type": typ, "source_files": sf,
@@ -4407,12 +6210,11 @@ def cmd_list_aggregates(args):
                 name = _pascal(title or base)
                 if not name:
                     continue
-                sf = [s for s in (fm.get("source_files") or []) if isinstance(s, str) and s.strip()]
+                sf = fm_list(fm.get("source_files"))
                 bc = fm.get("bounded_context") if isinstance(fm.get("bounded_context"), str) else ""
                 if want_ctx and bc and re.sub(r"[^a-z0-9]", "", bc.lower()) != want_ctx:
                     continue
-                listed = [s for s in (fm.get("features") or []) if isinstance(s, str) and s.strip()] \
-                    if isinstance(fm.get("features"), list) else []
+                listed = fm_list(fm.get("features"))
                 cand = {
                     "name": name,
                     "title": title or base,
@@ -4539,7 +6341,8 @@ def main():
                     help="The declared lane root folder of the UI lane. Frontend signals are derived "
                          "from this subtree only, and it is excluded from the backend's — "
                          "so neither lane's substrate carries the other's files.")
-    ps.add_argument("--map", help="Machine map whose features attribute UI feature folders "
+    ps.add_argument("--map", help="Machine map whose Pass A strategy the aggregate signals are "
+                                  "read with, and whose features attribute UI feature folders "
                                   "(default: <root>/.appweaver/inventory/feature-map.json, "
                                   "when present).")
     ps.set_defaults(func=cmd_scan)
@@ -4552,9 +6355,11 @@ def main():
     pp.add_argument("--ui-root", dest="ui_root", default="",
                     help="The declared lane root folder of the UI lane.")
     pp.add_argument("--strategy", default="",
-                    help="Pass A strategy: structure | reference | persistence. "
-                         "Default: the highest-coverage AVAILABLE strategy, ties "
-                         "broken by fewest singletons.")
+                    help="The request: a first word naming a Pass A strategy (domain | "
+                         "structure | reference | persistence | ui) forces it; any other "
+                         "first word forces nothing. Default: declared roots that "
+                         "operations act on, else the highest-coverage AVAILABLE "
+                         "strategy, ties broken by fewest singletons.")
     pp.add_argument("--out", help="Proposal markdown (default: <root>/specs/proposed-inventory.md).")
     pp.add_argument("--map", help="Machine map (default: <root>/.appweaver/inventory/feature-map.json).")
     pp.set_defaults(func=cmd_propose)