aw-spec-cli 0.1.23 → 0.1.25

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

@@ -57,6 +57,7 @@ Usage: aw-inventory.py <scan|concept|list-aggregates|validate> [options]
 
 import argparse
 import datetime
+import fnmatch
 import json
 import os
 import re
@@ -112,6 +113,29 @@ CONFIGS_RE = re.compile(
 )
 ADR_RE = re.compile(r"(^|/)(adr|adrs|decisions?|rfcs?)/|(^|/)(ADR|RFC)[-_0-9]", re.IGNORECASE)
 
+# --- the API surface and the data layer, as the scan's substrate lists them --
+# ROUTES_RE and DB_FILES_RE above match a role word ANYWHERE in a name, which is what
+# the flat-repo noun fallback wants and what a listing of the API surface cannot use:
+# `Identity` contains "entit", `ReviewService` contains "view", and a domain value
+# object called Route is not a route. These read a name by its WORDS (PascalCase,
+# camelCase, snake_case, kebab-case and dotted names split alike) and fall back to
+# what the file declares when the name says nothing.
+SCAN_SOURCE_RE = re.compile(r"\.(py|js|ts|mjs|go|rb|java|cs|php|kt|scala)$", re.IGNORECASE)
+NAME_WORD_RE = re.compile(r"[A-Z]+(?![a-z])|[A-Z]?[a-z]+|\d+")
+ROUTE_ROLE_WORDS = frozenset(("controller", "controllers", "endpoint", "endpoints", "route",
+                              "routes", "router", "routers", "routing", "urls", "views"))
+DATA_DIR_RE = re.compile(
+    r"(^|/)(persistence|repositor(?:y|ies)|dal|data[-_]?access|db|database|migrations?|"
+    r"alembic)(/|$)", re.IGNORECASE)
+DATA_NAME_RE = re.compile(r"(DbContext|DbContextFactory|Repository|Repositories|Repo|Dao|"
+                          r"Migration)$", re.IGNORECASE)
+# ORM configuration and mapped entities, across the common stacks.
+DATA_DECL_RE = re.compile(
+    r"\bDbSet\s*<|\b(?:IEntityTypeConfiguration|EntityTypeConfiguration)\s*<|"
+    r"\.Entity\s*<\s*\w+\s*>\s*\(|@Entity\b|@Table\b|@Repository\b|\bmodels\.Model\b|"
+    r"<\s*ApplicationRecord\b|ActiveRecord::Base|\b(?:from|import)\s+sqlalchemy\b|"
+    r"\bnew\s+Schema\s*\(|mongoose\.Schema")
+
 # --- frontend / UI detection (the lane signal) ------------------------------
 # Deterministic evidence that this repo has a USER INTERFACE, and where it lives.
 # The CODE is the whole oracle here: a lane is recognised from files that exist,
@@ -430,24 +454,159 @@ def git(root, *args):
         return ""
 
 
+def _git_ignored(root, rel):
+    """Whether git's own ignore rules exclude `rel` (a path under `root`)."""
+    try:
+        return subprocess.run(["git", "-C", root, "check-ignore", "-q", rel.rstrip("/")],
+                              capture_output=True).returncode == 0
+    except Exception:
+        return False
+
+
 def is_excluded(path, config_excludes):
     if DEFAULT_EXCLUDE.search(path):
         return True
     return any(rx.match(path) for rx in config_excludes)
 
 
-def list_files(root, config_excludes):
-    """Repo-relative-to-`root` file list, honoring .gitignore via git ls-files."""
+# The agent integrations the kit installs beside a project, and the agent-instruction
+# files at the repository root. Configuration for an assistant, never evidence of how
+# the project's code is built.
+KIT_AGENT_DIRS = (".claude", ".agents", ".kilocode")
+KIT_AGENT_FILES = ("CLAUDE.md", "AGENTS.md")
+
+
+def kit_excludes(root):
+    """Exclusions for the kit's own install footprint under `root`, as config_excludes
+    entries. The scan reads the repository as evidence of the PROJECT, and the kit
+    installs trees beside it — governance corpora, scaffold packs, agent integrations —
+    that otherwise read as the project's own folders, docs, endpoints and churn.
+
+    `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 root 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 ("projects", "technology", "domain")):
+        names.append("guardrails")
+    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:
+                dirnames[:] = []
+            if any(n.endswith(".pack.txt") for n in filenames):
+                names.append("foundations")
+                break
+    rxs = [re.compile("^" + re.escape(n) + "/") for n in names]
+    rxs += [re.compile("^" + re.escape(n) + "$") for n in KIT_AGENT_FILES]
+    return rxs
+
+
+# Directories that hold build output, dependencies or tool state and never source.
+# Pruned wherever the tree is read from disk rather than through git, because there
+# is no .gitignore standing in for this list on that path.
+WALK_PRUNE_DIRS = frozenset((
+    ".git", "node_modules", "bin", "obj", ".next", ".nuxt", ".svelte-kit", ".angular",
+    "dist", "target", "__pycache__", ".venv", "venv", ".vs", ".idea", ".gradle",
+    "coverage", "TestResults", ".turbo", ".parcel-cache",
+))
+
+
+def _ignore_rules(dirpath, base):
+    """The patterns one .gitignore contributes, as (dir_rel, pattern, dir_only, anchored).
+
+    Best-effort by design — negation, character classes and escaped spaces are not
+    honoured. It exists for the one case git cannot answer: a lane root the HOST
+    repository ignores wholesale, whose own nested .gitignore files still describe
+    what inside it is build output."""
+    rules = []
+    try:
+        with open(os.path.join(dirpath, ".gitignore"), encoding="utf-8") as fh:
+            lines = fh.read().splitlines()
+    except OSError:
+        return rules
+    rel = os.path.relpath(dirpath, base).replace(os.sep, "/")
+    rel = "" if rel == "." else rel
+    for ln in lines:
+        p = ln.strip()
+        if not p or p.startswith(("#", "!")):
+            continue
+        dir_only = p.endswith("/")
+        p = p.rstrip("/")
+        anchored = p.startswith("/") or "/" in p
+        rules.append((rel, p.lstrip("/"), dir_only, anchored))
+    return rules
+
+
+def _ignored_by(rules, rel_path, is_dir):
+    for d, pat, dir_only, anchored in rules:
+        if dir_only and not is_dir:
+            continue
+        if d and not (rel_path == d or rel_path.startswith(d + "/")):
+            continue
+        local = rel_path[len(d) + 1:] if d else rel_path
+        if anchored:
+            if fnmatch.fnmatch(local, pat) or fnmatch.fnmatch(local, pat + "/*"):
+                return True
+        elif any(fnmatch.fnmatch(seg, pat) for seg in local.split("/")):
+            return True
+    return False
+
+
+def _walk_tree(base, prefix=""):
+    """Every file under `base`, as `prefix` + its path relative to `base`, with build
+    output pruned and every .gitignore found INSIDE `base` applied."""
+    out, rules = [], []
+    for dirpath, dirnames, filenames in os.walk(base):
+        rules = rules + _ignore_rules(dirpath, base)
+        here = os.path.relpath(dirpath, base).replace(os.sep, "/")
+        here = "" if here == "." else here
+        keep = []
+        for d in sorted(dirnames):
+            rel = f"{here}/{d}" if here else d
+            if d in WALK_PRUNE_DIRS or _ignored_by(rules, rel, True):
+                continue
+            keep.append(d)
+        dirnames[:] = keep
+        for fn in filenames:
+            rel = f"{here}/{fn}" if here else fn
+            if fn == ".gitignore" or _ignored_by(rules, rel, False):
+                continue
+            out.append(prefix + rel)
+    return out
+
+
+def list_files(root, config_excludes, lane_roots=()):
+    """Repo-relative-to-`root` file list, honoring .gitignore via git ls-files.
+
+    TRACKED **AND** UNTRACKED. `git ls-files` alone lists only what is committed, and
+    the normal state of a brownfield target is source that has been copied or generated
+    into a workspace and not committed yet — for which the scan returned nothing, with
+    no way to tell 0% coverage caused by an empty listing from 0% caused by the code.
+    `--others` adds what is on disk but unstaged and `--exclude-standard` applies the
+    same ignore rules git itself would, including nested .gitignore files, so build
+    output (obj/, bin/, node_modules/) stays out exactly as before.
+
+    A DECLARED LANE ROOT IS READ EVEN WHEN THE HOST REPO IGNORES IT. A codebase under
+    assessment is often nested inside a repository that deliberately keeps it out of
+    version control — a test bed, a vendored drop, a legacy tree copied in for analysis.
+    git then answers "nothing here" for the one subtree select-stack said IS the code.
+    The declaration outranks the host's ignore rule: an ignored lane root is walked from
+    disk, with build output pruned and the lane's OWN nested .gitignore files applied.
+    """
     if git(root, "rev-parse", "--git-dir"):
-        raw = git(root, "ls-files")
-        files = raw.splitlines() if raw else []
+        tracked = git(root, "ls-files")
+        untracked = git(root, "ls-files", "--others", "--exclude-standard")
+        files = set((tracked or "").splitlines()) | set((untracked or "").splitlines())
+        for lr in lane_roots or ():
+            lr = _lane_prefix(lr)
+            if lr and os.path.isdir(os.path.join(root, lr)) and _git_ignored(root, lr):
+                files |= set(_walk_tree(os.path.join(root, lr), lr))
+        files = sorted(files)
     else:
-        files = []
-        for dirpath, dirnames, filenames in os.walk(root):
-            dirnames[:] = [d for d in dirnames if d != ".git"]
-            for fn in filenames:
-                rel = os.path.relpath(os.path.join(dirpath, fn), root)
-                files.append(rel.replace(os.sep, "/"))
+        files = _walk_tree(root)
     return [f for f in files if f.strip() and not is_excluded(f, config_excludes)]
 
 
@@ -654,6 +813,71 @@ def _dotted_module(seg):
     return (singularize(name) or name, kind) if name else (None, None)
 
 
+def _child_dirs(files):
+    """directory -> the names of the directories directly under it."""
+    out = {}
+    for f in files:
+        parts = f.split("/")[:-1]
+        for i in range(len(parts)):
+            out.setdefault("/".join(parts[:i]), set()).add(parts[i])
+    return out
+
+
+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}
+    return "domain" in kinds and len(kinds) >= 2
+
+
+def _is_module_dir(dirs, j, children):
+    """Whether dirs[:j+1] is a MODULE folder even when its name is a container word.
+
+    The container vocabulary is a prior about names, and a domain names its modules
+    freely — a project-tracking service has a Projects module beside Reports and Users.
+    Shape outranks the prior when the folder holds a domain layer plus another layer
+    AND either sits directly inside a project (a dotted assembly folder) or has a sibling
+    module of the same shape. A top-level src/ holding Domain/ and Features/ has
+    neither, which keeps a layer-major repo reading as one."""
+    path = "/".join(dirs[:j + 1])
+    if not _holds_layers(path, children):
+        return False
+    if not CONTAINER_DIR_RE.match(dirs[j]):
+        return True
+    if j and DOTTED_SEG_RE.match(dirs[j - 1]):
+        return True
+    parent = "/".join(dirs[:j])
+    return any(s != dirs[j] and not CONTAINER_DIR_RE.match(s)
+               and _holds_layers(f"{parent}/{s}" if parent else s, children)
+               for s in children.get(parent, set()))
+
+
+def _is_module_layer(dirs, i, children):
+    """Whether the slice container at dirs[i] is one LAYER of the module that holds it,
+    rather than a folder of modules.
+
+    Two layouts spell a slice container the same way and mean opposite things:
+
+      src/Features/Orders/Domain/Order.cs        Features holds MODULES — Orders is one
+      <Svc>/Care/Domain/Encounter.cs             Features is Care's feature LAYER, a
+      <Svc>/Care/Features/SignEncounter/…        sibling of its Domain layer; each child
+                                                 is ONE OPERATION of the Care module
+
+    The second is the layout the kit's own folder-structure rule generates — one folder
+    per bounded context holding Domain / Features / Persistence / Shared — so reading it
+    the first way turns every command and query handler into a module. Two tells, both
+    required: the container sits beside another layer folder, and none of its children
+    carries layer folders of its own — a child that does is a module, not an operation."""
+    if i == 0 or (CONTAINER_DIR_RE.match(dirs[i - 1]) and not _is_module_dir(dirs, i - 1, children)):
+        return False
+    here = "/".join(dirs[:i + 1])
+    siblings = children.get("/".join(dirs[:i]), set())
+    if not any(_layer_of(s) and not SLICE_CONTAINER_RE.match(s) for s in siblings):
+        return False
+    return not any(_layer_of(g)
+                   for c in children.get(here, set())
+                   for g in children.get(f"{here}/{c}", 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}
@@ -680,6 +904,7 @@ def _structure_rows(files):
     without bounding modules — without it those files reach no candidate at all."""
     proj_roots = _project_roots(files)
     product = _product_prefix(files)
+    children = _child_dirs(files)
 
     for f in files:
         parts = f.split("/")
@@ -688,10 +913,18 @@ def _structure_rows(files):
         dirs = parts[:-1]
         hit = None
 
-        # slice-major — a slice container names the module in its CHILD.
+        # 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
+        # case the module is its parent and the child is one operation of it.
         for i, seg in enumerate(dirs):
             if not SLICE_CONTAINER_RE.match(seg):
                 continue
+            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)
+                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:]
@@ -715,7 +948,7 @@ def _structure_rows(files):
                 if not kind:
                     continue
                 parent = dirs[i - 1] if i else ""
-                if i and not CONTAINER_DIR_RE.match(parent):
+                if i and (not CONTAINER_DIR_RE.match(parent) or _is_module_dir(dirs, i - 1, children)):
                     name = (_clean_project_name(parent, product)
                             if DOTTED_SEG_RE.match(parent) else singularize(parent) or parent)
                     hit = ("/".join(dirs[:i]), name, kind, "module-major")
@@ -725,6 +958,22 @@ def _structure_rows(files):
                         hit = ("/".join(dirs[:i] + [noun]), noun, kind, "layer-major")
                 break
 
+        # 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
+        # Shared/, Common/ or Helpers/ names none of them, and without this rule its files
+        # fall through to the enclosing project and leave the module. The deepest folder of
+        # 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):
+                    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")
+                    hit = ("/".join(dirs[:j + 1]), name, kind, "module-major")
+                    break
+
         # A dotted project segment bounds a module even with no layer anywhere in
         # it and no manifest tracked beside it — which is how a test project that
         # mirrors its subject (Acme.Billing.Tests) reaches the same candidate.
@@ -1156,8 +1405,26 @@ def strategy_reference(root, files, churn_map, graph=None):
 EF_DBSET_RE = re.compile(r"DbSet\s*<\s*([A-Za-z_]\w*)\s*>")
 EF_TABLE_RE = re.compile(r"\[Table\s*\(\s*\"([^\"]+)\"")
 EF_COLLECTION_RE = re.compile(
-    r"(?:ICollection|IList|List|IEnumerable|HashSet|ISet)\s*<\s*([A-Za-z_]\w*)\s*>")
+    r"(?:IReadOnlyCollection|IReadOnlyList|IReadOnlySet|ICollection|IList|List|IEnumerable|"
+    r"HashSet|ISet)\s*<\s*([A-Za-z_]\w*)\s*>")
 EF_FK_RE = re.compile(r"^\s*public\s+[\w?<>]+\s+([A-Za-z_]\w*)Id\s*\{", re.M)
+# What EF is TOLD it persists — the configuration class (EF Core and EF6) and the model
+# builder call; DbSet<T> and [Table] are the other two.
+EF_CONFIG_RE = re.compile(r"\b(?:IEntityTypeConfiguration|EntityTypeConfiguration)\s*<\s*([A-Za-z_]\w*)\s*>")
+EF_MODEL_ENTITY_RE = re.compile(r"\.Entity\s*<\s*([A-Za-z_]\w*)\s*>\s*\(")
+# A collection MEMBER — access modifier first — so a method's local list is not one.
+EF_MEMBER_COLLECTION_RE = re.compile(
+    r"\b(?:public|protected|internal|private)\s+(?:(?:readonly|virtual|static|required|"
+    r"override|new)\s+)*(?:IReadOnlyCollection|IReadOnlyList|IReadOnlySet|ICollection|IList|"
+    r"List|IEnumerable|HashSet|ISet)\s*<\s*([A-Za-z_]\w*)\s*>")
+CS_CLASS_ANY_RE = re.compile(r"\bclass\s+([A-Z]\w*)")
+TYPE_PARAM_RE = re.compile(r"^T(?:[A-Z]\w*)?$")
+# Names an application or host role, never a persisted entity: the request an endpoint
+# binds, the client that calls another service, the handler, the options class.
+APP_ROLE_NAME_RE = re.compile(
+    r"(Endpoint|Controller|Handler|Request|Response|Command|Query|Dto|DTO|ViewModel|"
+    r"Validator|Client|Service|Mapper|Profile|Extensions|Configuration|Factory|Module|"
+    r"Options|Settings|Exception|Middleware|Filter|Attribute)$")
 CSHARP_CLASS_RE = re.compile(r"^\s*(?:public|internal)\s+(?:abstract\s+|sealed\s+|partial\s+)*class\s+([A-Za-z_]\w*)", re.M)
 JPA_ENTITY_RE = re.compile(r"@Entity\b")
 JPA_ONE_MANY_RE = re.compile(r"@OneToMany[\s\S]{0,200}?(?:ICollection|List|Set)\s*<\s*([A-Za-z_]\w*)\s*>")
@@ -1182,7 +1449,7 @@ def persistence_entities(root, files):
     Four dialects, one shape. `owns` is a lifecycle edge (a collection navigation,
     a one-to-many, a list relation, a foreign key pointing IN); `refs` is a
     by-id reference that crosses an aggregate boundary without owning anything."""
-    ents = {}
+    ents, cs = {}, {}
 
     def ent(name):
         return ents.setdefault(_pascal_name(name),
@@ -1193,6 +1460,9 @@ def persistence_entities(root, files):
         lang = _lang_of(f)
         if lang not in ("cs", "java", "kt") and not low.endswith((".prisma", ".sql")):
             continue
+        # A test app's or a sample's DbContext persists ITS entities, not the product's.
+        if TEST_PATH_RE.search(f):
+            continue
         body = _read_source(root, f)
         if not body:
             continue
@@ -1220,19 +1490,7 @@ def persistence_entities(root, files):
                         ents[_pascal_name(tgt)]["owns"].add(_pascal_name(tables[0]))
                         owner["refs"].add(tgt)
         elif lang == "cs":
-            for m in EF_DBSET_RE.finditer(body):
-                ent(m.group(1))["files"].add(f)
-            cls = CSHARP_CLASS_RE.search(body)
-            if cls and (EF_TABLE_RE.search(body) or EF_COLLECTION_RE.search(body)
-                        or EF_FK_RE.search(body) or DOMAIN_DIR_RE.search(f)):
-                e = ent(cls.group(1))
-                e["files"].add(f)
-                for m in EF_COLLECTION_RE.finditer(body):
-                    if m.group(1) != cls.group(1):
-                        e["owns"].add(_pascal_name(m.group(1)))
-                for m in EF_FK_RE.finditer(body):
-                    if m.group(1) != cls.group(1):
-                        e["refs"].add(_pascal_name(m.group(1)))
+            cs[f] = _code_only(f, body)
         elif lang in ("java", "kt") and JPA_ENTITY_RE.search(body):
             cls = JAVA_CLASS_RE.search(body)
             if cls:
@@ -1242,9 +1500,97 @@ def persistence_entities(root, files):
                     e["owns"].add(_pascal_name(m.group(1)))
                 for m in JPA_MANY_ONE_RE.finditer(body):
                     e["refs"].add(_pascal_name(m.group(1)))
+    if cs:
+        _cs_entities(cs, ent)
     return ents
 
 
+def _cs_entities(cs, ent):
+    """The C# persistence model, into `ent`.
+
+    DECLARED BEATS INFERRED, as it does for aggregate roots. Where the code tells EF
+    which types it persists — a DbSet<T>, an IEntityTypeConfiguration<T> (or EF6's
+    EntityTypeConfiguration<T>), a modelBuilder.Entity<T>(), a [Table] — those types are
+    the entities, together with what they hold collections of, which is EF's own
+    discovery rule. Nothing else is: an endpoint whose request carries an EncounterId is
+    not a table.
+
+    Only a codebase that declares none of those is read by shape: a class with a
+    collection member, a foreign-key property, a [Table], or a home in a domain folder.
+    Even then an open generic (PagedResult<T>), a class named for an application role
+    (…Endpoint, …Request, …Client) and a local variable are not evidence."""
+    classes = {}
+    for f, body in cs.items():
+        for m in CS_CLASS_ANY_RE.finditer(body):
+            classes.setdefault(m.group(1), f)
+    declared, decl_files = set(), {}
+    for f, body in cs.items():
+        for rx in (EF_DBSET_RE, EF_CONFIG_RE, EF_MODEL_ENTITY_RE):
+            for m in rx.finditer(body):
+                # A generic base (BaseConfiguration<T> : IEntityTypeConfiguration<T>)
+                # declares a type PARAMETER, not an entity.
+                if m.group(1) not in classes and TYPE_PARAM_RE.match(m.group(1)):
+                    continue
+                declared.add(m.group(1))
+                decl_files.setdefault(m.group(1), set()).add(f)
+        cls = CSHARP_CLASS_RE.search(body)
+        if cls and EF_TABLE_RE.search(body):
+            declared.add(cls.group(1))
+
+    if declared:
+        seen, queue = set(), sorted(declared)
+        while queue:
+            n = queue.pop()
+            if n in seen:
+                continue
+            seen.add(n)
+            e = ent(n)
+            e["files"].update(decl_files.get(n, ()))
+            f = classes.get(n)
+            if not f:
+                continue
+            e["files"].add(f)
+            for m in EF_COLLECTION_RE.finditer(cs[f]):
+                t = m.group(1)
+                if t != n and t in classes and not APP_ROLE_NAME_RE.search(t):
+                    e["owns"].add(t)
+                    queue.append(t)
+            for m in EF_FK_RE.finditer(cs[f]):
+                if m.group(1) != n:
+                    e["refs"].add(_pascal_name(m.group(1)))
+        return
+
+    for f, body in cs.items():
+        cls = CSHARP_CLASS_RE.search(body)
+        if not cls:
+            continue
+        name = cls.group(1)
+        if body[cls.end():cls.end() + 20].lstrip().startswith("<") or APP_ROLE_NAME_RE.search(name):
+            continue
+        # A domain event, a specification or a declared value object has no lifecycle
+        # of its own to persist, and counting one as an entity makes it a ROOT (nothing
+        # owns it). Only the unambiguous cases are dropped — by name, folder or
+        # declaration — so a legacy model of plain POCOs is read as before.
+        if not EF_TABLE_RE.search(body):
+            brace = body.find("{", cls.end())
+            header = body[cls.end():brace if brace != -1 else cls.end() + 400][:400]
+            if (EVENT_NAME_RE.search(name) or SPEC_NAME_RE.search(name)
+                    or re.search(r"/(events|specifications)/", "/" + f.lower())
+                    or re.search(r"\bValueObject\b|IEquatable\s*<\s*" + re.escape(name) + r"\s*>",
+                                 header)):
+                continue
+        if (EF_TABLE_RE.search(body) or EF_MEMBER_COLLECTION_RE.search(body)
+                or EF_FK_RE.search(body) or DOMAIN_DIR_RE.search(f)):
+            e = ent(name)
+            e["files"].add(f)
+            for m in EF_MEMBER_COLLECTION_RE.finditer(body):
+                if m.group(1) != name:
+                    e["owns"].add(_pascal_name(m.group(1)))
+            for m in EF_FK_RE.finditer(body):
+                if m.group(1) != name:
+                    e["refs"].add(_pascal_name(m.group(1)))
+
+
 def strategy_persistence(root, files, churn_map, graph=None):
     """S3 — derive roots from what the schema says owns what.
 
@@ -1295,21 +1641,549 @@ def strategy_persistence(root, files, churn_map, graph=None):
     return _finish_candidates(cands, churn_map, "persistence")
 
 
+# ── S0: domain — the aggregate roots the code DECLARES ─────────────────────
+# The greenfield sequence writes the model down in two places that agree by
+# construction: `## Aggregate: <Root>` in specs/<Context>/domain-model.md, and a type
+# deriving from an aggregate-root base in <Module>/Domain/ — where <Module> is the
+# bounded context (folder-structure: "one folder per bounded context"). This strategy
+# reads the second back. A declared root is not a guess about a boundary; it is the
+# boundary, stated by whoever wrote the code, so where one exists this strategy is
+# chosen ahead of every measured one (see choose_strategy).
+#
+# Three levels, never conflated — the same three the spec side keeps apart:
+#   bounded context  the module folder that holds a Domain layer
+#   aggregate        a declared root + everything only it reaches in that module, and
+#                    the application-layer files named after it or used by it alone
+#   operation        one slice under the module's Features layer (Command/Query +
+#                    Handler + Endpoint + Validator), or a handler class elsewhere in
+#                    the lane — never a feature, never an aggregate, and not a user
+#                    story either: a story usually spans several operations
+# Features are not read here at all: a feature is a capability the developer chose,
+# 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")
+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*)")
+C_COMMENT_RE = re.compile(r"/\*.*?\*/|//[^\n]*", re.S)
+
+
+def _code_only(path, body):
+    """Source with comments removed, for the languages whose comments are C-style.
+    A type named in a doc comment is documentation, not a reference."""
+    return C_COMMENT_RE.sub("", body) if _lang_of(path) in ("cs", "java", "kt", "scala", "js",
+                                                            "go", "rs", "php") else body
+EVENT_NAME_RE = re.compile(r"(?:Event|Notification)$")
+SPEC_NAME_RE = re.compile(r"(?:Spec|Specification)$")
+# Code that exercises or demonstrates a model without being it: tests, samples, demos.
+# A sample app's Order aggregate is not the codebase's Order aggregate.
+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")
+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*")
+
+
+def _type_header(body, end):
+    """The declaration text between a type's name and its body — its base list, with
+    generic arguments and constraint clauses removed.
+
+    Stops at the body brace, a statement end, or Python's `):`. Not at a bare `:` —
+    C# and Kotlin open the base list with one, often at the end of the line.
+
+    Generic arguments and `where` clauses go because a marker named THERE says what a
+    type works WITH, not what it IS: `EfRepository<T> : IRepository<T> where T :
+    IAggregateRoot` is a repository of roots, and `AggregateRootBase<EncounterId>` is a
+    root whatever its id type."""
+    stop = len(body)
+    for tok in ("{", ";", "):", "=>"):
+        k = body.find(tok, end)
+        if k != -1:
+            stop = min(stop, k)
+    header = re.split(r"\bwhere\b", body[end:min(stop, end + 400)], maxsplit=1)[0]
+    prev = None
+    while prev != header:
+        prev, header = header, re.sub(r"<[^<>]*>", "", header)
+    return header
+
+
+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."""
+    if kind == "enum":
+        return "enum"
+    if kind == "interface":
+        return "contract"
+    if "AggregateRoot" not in name and (AGG_ROOT_MARKER_RE.search(header)
+                                        or AGG_ROOT_ANNOTATION_RE.search(pre)):
+        return "root"
+    if EVENT_NAME_RE.search(name) or "/events/" in "/" + path.lower():
+        return "event"
+    if SPEC_NAME_RE.search(name) or "/specifications/" in "/" + path.lower():
+        return "spec"
+    if ENTITY_MARKER_RE.search(header):
+        return "entity"
+    return "value"
+
+
+def _feature_layer_op(dirs, children, file_stem):
+    """(container index, operation name) when the file sits in a module's feature
+    LAYER, else (None, None). A slice folder names its operation; a file placed
+    directly in the layer names it by its stem, role suffix removed."""
+    for i, seg in enumerate(dirs):
+        if SLICE_CONTAINER_RE.match(seg) and _is_module_layer(dirs, i, children):
+            if i + 1 < len(dirs):
+                return i, dirs[i + 1]
+            stem = file_stem
+            prev = None
+            while prev != stem:
+                prev, stem = stem, ROLE_SUFFIX_RE.sub("", stem)
+            return i, stem or file_stem
+    return None, None
+
+
+def _spans_roots(referenced, types):
+    """Whether a file names two aggregate roots or more — code that spans the model."""
+    return sum(1 for tn in referenced if types[tn]["role"] == "root") > 1
+
+
+def _names_of(f, decl_of):
+    """The names a file answers to: the types it declares, and its own stem."""
+    return set(decl_of.get(f, ())) | {os.path.splitext(os.path.basename(f))[0]}
+
+
+def _named_after(names, members):
+    """The owner of the member these names are named after, or None.
+
+    A name is named after a member when it IS it or starts with it at a word boundary:
+    EncounterDto and EncounterMappingExtensions after Encounter, OrderLineDto after
+    OrderLine and not after Order, Orderly after nothing. An interface's leading I is
+    dropped first (IEncounterLookup). The longest member wins for each name, and names
+    that point at different owners are no answer at all."""
+    found = set()
+    for n in names:
+        if len(n) > 2 and n[0] == "I" and n[1].isupper() and n[2].islower():
+            n = n[1:]
+        best = ""
+        for m in members:
+            if len(m) > len(best) and n.startswith(m) and (
+                    len(n) == len(m) or not n[len(m)].islower()):
+                best = m
+        if best:
+            found.add(members[best])
+    return found.pop() if len(found) == 1 else None
+
+
+def _attribute_leftovers(modules, module_of, text, types, decl_of, refs, owner, shared, ops):
+    """Give each file the earlier passes left unplaced to the aggregate it serves, where
+    that is unambiguous, and record the rest of a module as its context's shared code.
+
+    Reach, references and operations place the model itself. What they leave is the
+    application layer around it — a DTO, an error catalogue, a mapping, a port — which
+    names no root, and so is reached by none, but is plainly one aggregate's: it is
+    named after one, or only one uses it.
+
+    Inside a module that declares roots, three rules in order:
+      1. NAMED AFTER one aggregate's member — its root, an entity or a value it owns;
+      2. REFERENCES one aggregate's types more than any other's — repeated, so a DTO
+         that nests a DTO placed a moment ago follows it;
+      3. USED BY one aggregate alone — a port only that aggregate's operations call.
+    Outside those modules (the Application and Api projects of a solution split one
+    project per layer) only the two strongest apply: named after a root or entity —
+    a value object's name is too generic to claim a file across the lane — or naming
+    exactly one root."""
+    in_model = set(modules)
+    op_files = {f for o in ops.values() for f in o["files"]}
+    members, identities = {}, {}
+    for tn, t in types.items():
+        o = owner.get(t["file"])
+        if t["module"] not in in_model or not o or t["file"] in op_files:
+            continue
+        if t["role"] in ("root", "entity", "value"):
+            members.setdefault(t["module"], {})[tn] = o
+        if t["role"] in ("root", "entity"):
+            identities[tn] = o
+    already_shared = {f for fs in shared.values() for f in fs}
+
+    for key, mod in modules.items():
+        left = [f for f in mod["files"] if f in text and f not in owner and f not in already_shared]
+        for f in left:
+            o = _named_after(_names_of(f, decl_of), members.get(key, {}))
+            if o:
+                owner[f] = o
+        changed = True
+        while changed:
+            changed = False
+            for f in left:
+                if f in owner or _spans_roots(refs.get(f, ()), types):
+                    continue
+                votes = {}
+                for tn in refs.get(f, ()):
+                    o = owner.get(types[tn]["file"])
+                    if o:
+                        votes[o] = votes.get(o, 0) + (3 if tn == o else 1)
+                top = sorted(votes.items(), key=lambda kv: -kv[1])
+                if top and (len(top) == 1 or top[0][1] > top[1][1]):
+                    owner[f] = top[0][0]
+                    changed = True
+            if changed:
+                continue
+            users = {}
+            for g in mod["files"]:
+                if owner.get(g):
+                    for tn in refs.get(g, ()):
+                        users.setdefault(types[tn]["file"], set()).add(owner[g])
+            for f in left:
+                if f not in owner and len(users.get(f, ())) == 1 \
+                        and not _spans_roots(refs.get(f, ()), types):
+                    owner[f] = next(iter(users[f]))
+                    changed = True
+        rest = [f for f in left if f not in owner]
+        if rest:
+            shared.setdefault(key, []).extend(rest)
+
+    roots = {tn for tn, t in types.items() if t["role"] == "root" and t["module"] in in_model}
+    for f, body in text.items():
+        if module_of[f] in in_model or f in owner:
+            continue
+        o = _named_after(_names_of(f, decl_of), identities)
+        if not o:
+            named = (set(IDENT_RE.findall(body)) - decl_of.get(f, set())) & roots
+            o = next(iter(named)) if len(named) == 1 else None
+        if o:
+            owner[f] = o
+
+
+_DOMAIN_MEMO = {}
+
+
+def parse_domain(root, files):
+    """The domain model as the code declares it, per module.
+
+    Returns {"modules": {key: {"context", "dir", "roots", "files"}},
+             "types": {name: {"file", "role", "module"}},
+             "owner": {file: root name},        every file an aggregate owns
+             "shared": {key: [file, …]},        module files no single aggregate owns
+             "operations": [op, …],
+             "root_edges": {root: {root, …}}}   A -> B: A's files reference B's types
+
+    Ownership is by REACH over type references inside one module: a root owns every
+    type it reaches without passing through another root, and a file that references
+    an owned type but is reached by nothing (a specification, a persistence
+    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."""
+    if root is None:
+        return {"modules": {}, "types": {}, "owner": {}, "shared": {},
+                "operations": [], "root_edges": {}}
+    memo_key = (root, hash(tuple(files)))
+    if memo_key in _DOMAIN_MEMO:
+        return _DOMAIN_MEMO[memo_key]
+
+    children = _child_dirs(files)
+    module_of = {f: key for key, _n, _k, f, _a in _structure_rows(files)}
+    text, types, decl_of = {}, {}, {}
+    for f in files:
+        if f not in module_of or not _lang_of(f) or TEST_PATH_RE.search(f):
+            continue
+        body = _code_only(f, _read_source(root, f))
+        if not body:
+            continue
+        text[f] = body
+        for m in TYPE_DECL_RE.finditer(body):
+            name = m.group(2)
+            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()])
+            types[name] = {"file": f, "role": role, "module": module_of[f]}
+            decl_of.setdefault(f, set()).add(name)
+
+    roots = {n: t for n, t in types.items() if t["role"] == "root"}
+    product = _product_prefix(files)
+    modules = {}
+    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
+        mod = modules.setdefault(key, {"context": ctx, "dir": key, "roots": [], "files": []})
+        mod["roots"].append(n)
+    for f, key in module_of.items():
+        if key in modules:
+            modules[key]["files"].append(f)
+
+    types_in = {}
+    for n, t in types.items():
+        types_in.setdefault(t["module"], set()).add(n)
+    refs = {}
+    for f, body in text.items():
+        if module_of.get(f) not in modules:
+            continue
+        refs[f] = (set(IDENT_RE.findall(body)) & types_in[module_of[f]]) - decl_of.get(f, set())
+
+    owner, shared, ops = {}, {}, {}
+
+    def _add_op(op, fs, in_scope, key=None):
+        """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."""
+        strong, weak = {}, {}
+        for f in fs:
+            for tn in IDENT_RE.findall(text.get(f, "")):
+                t = types.get(tn)
+                if not t or not in_scope(t["module"]):
+                    continue
+                o = tn if t["role"] == "root" else owner.get(t["file"])
+                if not o:
+                    continue
+                if tn == o or t["role"] == "spec":
+                    strong[o] = strong.get(o, 0) + 1
+                else:
+                    weak[o] = weak.get(o, 0) + 1
+        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 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, "")))
+        # 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]]
+        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",
+            "routes": sorted(set(routes)),
+        }
+        for f in fs:
+            if acts_on and f not in owner:
+                owner[f] = acts_on[0]
+
+    for key, mod in modules.items():
+        op_files, plain = {}, []
+        for f in mod["files"]:
+            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)
+            else:
+                plain.append(f)
+
+        # Forward reach from each root over the non-operation files.
+        best = {}
+        for r in mod["roots"]:
+            start = types[r]["file"]
+            dist, frontier = {start: 0}, [start]
+            while frontier:
+                nxt = []
+                for f in frontier:
+                    for tn in refs.get(f, ()):
+                        g = types[tn]["file"]
+                        if g in dist or g not in refs and g not in text:
+                            continue
+                        if types[tn]["role"] == "root" and tn != r:
+                            continue
+                        dist[g] = dist[f] + 1
+                        nxt.append(g)
+                frontier = nxt
+            for f, d in dist.items():
+                best.setdefault(f, []).append((d, r))
+        for f in plain:
+            claims = sorted(best.get(f, []))
+            if not claims:
+                continue
+            top = [r for d, r in claims if d == claims[0][0]]
+            stem = os.path.splitext(os.path.basename(f))[0]
+            named = [r for r in top if stem.startswith(r)]
+            if len(top) == 1:
+                owner[f] = top[0]
+            elif named:
+                owner[f] = max(named, key=len)
+
+        # Files nothing reaches uniquely take the owner of what they REFERENCE: a
+        # specification, a persistence configuration and a DTO mapping each name the
+        # type they serve. What still has no single answer is the module's shared
+        # kernel — an id or value two aggregates hold and neither owns. A file that
+        # names two roots or more (a DbContext, a unit of work, a seeder) spans the
+        # model rather than serving one aggregate of it, and is never voted onto one.
+        #
+        # A NAME outranks a reference here, as it does in the reach tie-break above:
+        # MedicationOrderErrors that mentions Encounter once is still MedicationOrder's.
+        members = {tn: owner[types[tn]["file"]] for tn in types_in.get(key, ())
+                   if types[tn]["role"] in ("root", "entity", "value")
+                   and types[tn]["file"] in owner}
+        for f in plain:
+            if f in owner:
+                continue
+            named = _named_after(_names_of(f, decl_of), members)
+            if named:
+                owner[f] = named
+                continue
+            if _spans_roots(refs.get(f, ()), types):
+                continue
+            votes = {}
+            for tn in refs.get(f, ()):
+                o = owner.get(types[tn]["file"])
+                if o:
+                    votes[o] = votes.get(o, 0) + (3 if tn == o else 1)
+            top = sorted(votes.items(), key=lambda kv: -kv[1])
+            if top and (len(top) == 1 or top[0][1] > top[1][1]):
+                owner[f] = top[0][0]
+            elif f in best:
+                shared.setdefault(key, []).append(f)
+
+        # Slice folders, plus handler classes outside any feature layer.
+        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 sorted(op_files.items()):
+            _add_op(op, fs, lambda m, key=key: m == key, key)
+
+    # 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.
+    in_model = set(modules)
+    outside = [f for f in text if module_of[f] not in in_model]
+    out_files = {}
+    for f in outside:
+        parts = f.split("/")
+        _i, op = _feature_layer_op(parts[:-1], children, os.path.splitext(parts[-1])[0])
+        if op:
+            out_files.setdefault(op, []).append(f)
+            continue
+        for m in HANDLER_CLASS_RE.finditer(text[f]):
+            out_files.setdefault(m.group(1), []).append(f)
+    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
+    # after the operation. The longest operation name a file is named after takes it,
+    # wherever the file sits: an Api project can share a module key with the Domain
+    # project it serves.
+    taken = {f for fs in out_files.values() for f in fs} | {f for o in ops.values() for f in o["files"]}
+    for f in text:
+        if f in taken:
+            continue
+        op = _named_after(_names_of(f, decl_of), {n: n for n in out_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)
+
+    # 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
+    # had — reach, references and operations — so a DTO naming another aggregate's DTO
+    # never makes one aggregate depend on another.
+    edge_owner = dict(owner)
+    _attribute_leftovers(modules, module_of, text, types, decl_of, refs, owner, shared, ops)
+
+    # A -> B when anything A owns names B or a type B owns — in the same context or in
+    # another one. Across contexts that reference is by id by construction, and it is
+    # exactly the dependency that orders the contexts' onboarding.
+    #
+    # READS DO NOT ORDER. A query operation or a specification that reads another
+    # aggregate needs that data to exist in order to return rows, not in order to be
+    # built; counting it turns every dashboard read into a dependency, and two contexts
+    # that merely display each other's data into a cycle.
+    #
+    # AN OPERATION'S OWN TARGETS ARE NOT EDGES. ReconcileMedications acts on Encounter
+    # AND MedicationOrder; that it names both says the operation spans them, not that
+    # one depends on the other — reading it as an edge makes every many-to-many
+    # operation a cycle. What such an operation needs is ordered at the feature level
+    # (its feature follows each target's creator). An operation still contributes an
+    # edge to an aggregate it merely LOOKS UP — another context's user it assigns to.
+    owner_of_type = {tn: (tn if t["role"] == "root" else edge_owner.get(t["file"]))
+                     for tn, t in types.items()}
+    read_files = {f for o in ops.values() if o["kind"] == "query" for f in o["files"]}
+    read_files |= {t["file"] for t in types.values() if t["role"] == "spec"}
+    targets_of = {f: set(o["acts_on"]) for o in ops.values() for f in o["files"]}
+    root_edges = {r: set() for r in roots}
+    for f, o in edge_owner.items():
+        if f in read_files:
+            continue
+        for tn in set(IDENT_RE.findall(text.get(f, ""))) - decl_of.get(f, set()):
+            b = owner_of_type.get(tn)
+            if b and b != o and b in roots and b not in targets_of.get(f, ()):
+                root_edges[o].add(b)
+
+    model = {"modules": modules, "types": types, "owner": owner, "shared": shared,
+             "operations": sorted(ops.values(), key=lambda o: (o["context"], o["name"])),
+             "root_edges": root_edges}
+    _DOMAIN_MEMO[memo_key] = model
+    return model
+
+
+def strategy_domain(root, files, churn_map, graph=None):
+    """S0 — one candidate per DECLARED aggregate root, in the bounded context that
+    holds it. Unavailable where the code declares no root."""
+    model = parse_domain(root, files)
+    if not model["modules"]:
+        return []
+    cands = {}
+    for key, mod in model["modules"].items():
+        for r in mod["roots"]:
+            c = cands.setdefault(r.lower(), _blank_candidate(key, r))
+            c["context"] = mod["context"]
+            c["root_file"] = model["types"][r]["file"]
+            c["confidence"] = "declared"
+            c["entities"] = {n for n, t in model["types"].items()
+                             if t["module"] == key and t["role"] in ("root", "entity")
+                             and model["owner"].get(t["file"]) == r}
+            c["operations"] = [o["name"] for o in model["operations"]
+                               if o["acts_on"][:1] == [r]]
+    for f, r in model["owner"].items():
+        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")
+        c[kind + "_files"].append(f)
+        c["churn"] += churn_map.get(f, 0)
+    return _finish_candidates(cands, churn_map, "domain")
+
+
 # ── Availability + the probe ───────────────────────────────────────────────
 # A strategy that would return nothing must never be offered: an empty pick is
-# the zero-candidate hard stop at require_aggregates, arrived at by choice.
+# the zero-candidate hard stop at require_proposal, arrived at by choice.
 
 STRATEGIES = {
+    "domain":      strategy_domain,
     "structure":   strategy_structure,
     "reference":   strategy_reference,
     "persistence": strategy_persistence,
 }
 
 
-def strategy_availability(root, files, graph_stats, ents_found):
+def strategy_availability(root, files, graph_stats, ents_found, roots_found=()):
     """(name -> {available, reason}) — measured, never assumed."""
     parseable = graph_stats.get("parseable_files", 0)
+    shown = ", ".join(sorted(roots_found)[:4]) + (" …" if len(roots_found) > 4 else "")
     return {
+        "domain": {"available": bool(roots_found),
+                   "reason": (f"{len(roots_found)} aggregate root(s) the code declares — {shown}"
+                              if roots_found else "no type declares itself an aggregate root")},
         "structure": {"available": True,
                       "reason": "every repository has a layout"},
         "reference": {"available": parseable >= 10,
@@ -1327,7 +2201,9 @@ def run_probe(root, files, churn_map):
     on the chosen result."""
     graph, gstats = build_reference_graph(root, files)
     ents = persistence_entities(root, files)
-    avail = strategy_availability(root, files, gstats, len(ents))
+    model = parse_domain(root, files)
+    avail = strategy_availability(root, files, gstats, len(ents),
+                                  [r for m in model["modules"].values() for r in m["roots"]])
     code_total = len([f for f in files if CODE_EXT_RE.search(f)])
 
     results = {}
@@ -1335,6 +2211,14 @@ def run_probe(root, files, churn_map):
         if not avail[name]["available"]:
             continue
         cands = fn(root, files, churn_map, graph)
+        # Evidence that a strategy COULD apply is not a result: `structure` is available
+        # in every repository, an empty one included. A run that found nothing is
+        # reported as unavailable, so it is never offered and never chosen.
+        if not cands:
+            avail[name] = {"available": False,
+                           "reason": f"ran over {code_total} code file(s) and found "
+                                     f"no candidate aggregates"}
+            continue
         covered = {f for c in cands for f in c.get("covered_code", [])}
         results[name] = {
             "candidates": cands,
@@ -1343,22 +2227,38 @@ def run_probe(root, files, churn_map):
             "singletons": sum(1 for c in cands if c.get("raw_file_count", 0) <= 1),
             "available": True,
             "reason": avail[name]["reason"],
+            "operations": sum(len(c.get("operations") or []) for c in cands),
         }
-    return results, avail, graph, gstats, ents
+    return results, avail, graph, gstats, ents, model
 
 
-# Preference when the measurements tie. Structure leads because it is the layer
-# the other two are named by, so a tied structure result is the one an operator
-# can predict and re-derive by eye from the folder tree.
-STRATEGY_PREFERENCE = ("structure", "persistence", "reference")
+# Preference when the measurements tie. Structure leads the measured three because it
+# is the layer the other two are named by, so a tied structure result is the one an
+# operator can predict and re-derive by eye from the folder tree.
+STRATEGY_PREFERENCE = ("domain", "structure", "persistence", "reference")
 
 
 def choose_strategy(results):
-    """The non-interactive default: highest coverage, ties broken by fewest
-    singletons, then by the standing preference so a re-run of the same tree
-    picks the same strategy."""
+    """The non-interactive default.
+
+    DECLARED BEATS MEASURED. Where the code declares aggregate roots AND operations act
+    on them, `domain` is chosen whatever the others score: a declaration is the
+    boundary itself, and coverage — the share of files some candidate claims — rewards
+    a strategy for bucketing every file by folder, not for drawing the boundary right.
+    On the kit's own greenfield output `structure` scores 100% by turning each command
+    handler into an aggregate, while the declared roots are the two the model has.
+
+    The operations condition is the model's own: an aggregate exists to be acted on.
+    A library that ships one aggregate type for its own storage and no operation over
+    it is not a domain model, and one declared root there must not hide the rest of the
+    code from the proposal — `domain` is still offered, it is just not the default.
+
+    Otherwise: highest coverage, ties broken by fewest singletons, then by the
+    standing preference so a re-run of the same tree picks the same strategy."""
     if not results:
         return ""
+    if results.get("domain", {}).get("operations", 0) > 0:
+        return "domain"
     return sorted(results, key=lambda n: (-results[n]["coverage_pct"],
                                           results[n]["singletons"],
                                           STRATEGY_PREFERENCE.index(n)))[0]
@@ -1378,38 +2278,126 @@ def choose_strategy(results):
 # them.
 # ═══════════════════════════════════════════════════════════════════════════
 
-ROUTE_ATTR_RE = re.compile(
-    r"""(?:\[Route\s*\(\s*["']([^"']+)|"""
-    r"""@(?:Request|Get|Post|Put|Delete|Patch)Mapping\s*\(\s*(?:value\s*=\s*)?["']([^"']+)|"""
-    r"""@(?:app|router)\.(?:get|post|put|delete|patch)\s*\(\s*["']([^"']+)|"""
-    r"""(?:app|router)\.(?:get|post|put|delete|patch)\s*\(\s*["']([^"']+)|"""
-    r"""Map(?:Get|Post|Put|Delete|Patch)\s*\(\s*["']([^"']+))""",
-    re.IGNORECASE)
+# (regex, verb group or None, path group). Each web framework declares a route its own
+# way; the verb is kept where the syntax carries it, because it is what tells the
+# operation that CREATES an aggregate (POST on the collection) from the ones that act
+# on an existing instance.
+ROUTE_DECL_RES = (
+    # FastEndpoints — Get("/x") inside Configure(). Unqualified and rooted at "/", which
+    # is what keeps a dictionary's Get("key") or a client's http.Get(...) out.
+    (re.compile(r"""(?<![\w.])(Get|Post|Put|Patch|Delete)\s*\(\s*"(/[^"]*)\""""), 1, 2),
+    (re.compile(r"""(?<![\w.])Routes\s*\(\s*"(/[^"]*)\""""), None, 1),
+    # ASP.NET MVC / Web API attributes, minimal APIs.
+    (re.compile(r"""\[Http(Get|Post|Put|Patch|Delete)\s*\(\s*"([^"]*)\""""), 1, 2),
+    (re.compile(r"""\[Route\s*\(\s*["']([^"']+)"""), None, 1),
+    (re.compile(r"""\bMap(Get|Post|Put|Patch|Delete)\s*\(\s*["']([^"']+)"""), 1, 2),
+    # Spring.
+    (re.compile(r"""@(Get|Post|Put|Patch|Delete)Mapping\s*\(\s*(?:value\s*=\s*|path\s*=\s*)?["']([^"']+)"""), 1, 2),
+    (re.compile(r"""@RequestMapping\s*\(\s*(?:value\s*=\s*|path\s*=\s*)?["']([^"']+)"""), None, 1),
+    # Express / FastAPI / Flask-style routers.
+    (re.compile(r"""@?(?:app|router)\.(get|post|put|patch|delete)\s*\(\s*["']([^"']+)"""), 1, 2),
+)
 HANDLER_NAME_RE = re.compile(r"(Command|Query)Handler$|^Handle")
 
 
-def _route_family(path_literal):
-    """The first meaningful segment of a route — the family a cutover switches.
+def _routes_in(body):
+    """Every route a source file declares, as ("VERB", "/path") — "" when the syntax
+    does not say which verb."""
+    out = []
+    for rx, vg, pg in ROUTE_DECL_RES:
+        for m in rx.finditer(body or ""):
+            path = m.group(pg)
+            if path:
+                out.append(((m.group(vg) or "").upper() if vg else "", path))
+    return out
+
+
+def _name_words(path):
+    """A file name's words, lower-cased: `RecordEncounterEndpoint.cs` → record,
+    encounter, endpoint; `order.controller.ts` → order, controller."""
+    stem = os.path.splitext(os.path.basename(path))[0]
+    return [w.lower() for w in NAME_WORD_RE.findall(re.sub(r"[._\-]+", " ", stem))]
+
 
-    /api/v2/orders/{id}/lines -> orders. Version and api prefixes are carried by
-    every route in the service and separate nothing."""
-    parts = [p for p in re.split(r"[/\\]", (path_literal or "").strip("/"))
-             if p and not p.startswith(("{", ":", "[", "<"))]
-    for p in parts:
+def api_and_data_files(root, files):
+    """The scan's `route_like_files` and `data_layer_files`: source that serves the API
+    surface, and source that persists the model.
+
+    A route file is named for its role — its LAST word is controller, endpoint, route,
+    router, urls, views… — or declares a route in its body (a minimal-API `MapGet`, an
+    attribute route, an Express or FastEndpoints call). A file in a domain-layer folder
+    is never one, whatever it is called. A data-layer file sits in a persistence folder,
+    is named for a persistence role (DbContext, Repository, Dao, Migration), is SQL or a
+    Prisma schema, or declares an ORM mapping. Tests and samples are neither: they
+    exercise the surface, they are not it."""
+    routes, data = [], []
+    for f in files:
+        low = f.lower()
+        is_src = bool(SCAN_SOURCE_RE.search(f))
+        if not (is_src or low.endswith((".sql", ".prisma"))) or TEST_PATH_RE.search(f):
+            continue
+        body = None
+        if is_src and not DOMAIN_DIR_RE.search(os.path.dirname(f) + "/"):
+            words = _name_words(f)
+            if words and words[-1] in ROUTE_ROLE_WORDS:
+                routes.append(f)
+            else:
+                body = _read_source(root, f)
+                if _routes_in(body):
+                    routes.append(f)
+        stem = os.path.splitext(os.path.basename(f))[0]
+        if (not is_src or DATA_DIR_RE.search(os.path.dirname(f) + "/")
+                or DATA_NAME_RE.search(stem)):
+            data.append(f)
+        elif is_src:
+            if body is None:
+                body = _read_source(root, f)
+            if DATA_DECL_RE.search(body or ""):
+                data.append(f)
+    return routes, data
+
+
+def _route_segments(path_literal, skip=()):
+    """A route's literal segments, with api/version prefixes, parameters and any
+    segment in `skip` removed. `skip` carries the bounded context's own name: the kit's
+    route convention is /<context>/<aggregate-plural>/{id}/<sub-resource>, and a context
+    prefix is carried by every route in that context and separates nothing inside it."""
+    skip = {_ui_norm(s) for s in skip}
+    out = []
+    for p in re.split(r"[/\\]", (path_literal or "").strip("/")):
+        if not p or p.startswith(("{", ":", "[", "<", "$")):
+            continue
         low = p.lower()
-        if low in ("api", "rest", "graphql", "v1", "v2", "v3", "internal", "public"):
+        if low in ("api", "rest", "graphql", "internal", "public") or re.fullmatch(r"v\d+", low):
             continue
-        if re.fullmatch(r"v\d+", low):
+        if _ui_norm(p) in skip and not out:
             continue
-        return singularize(p)
-    return ""
+        out.append(p)
+    return out
+
+
+def _route_family(path_literal, skip=()):
+    """The first meaningful segment of a route — the family a cutover switches.
+
+    /api/v2/orders/{id}/lines -> orders; /care/encounters/{id} -> encounter once
+    `care` is the context being skipped."""
+    segs = _route_segments(path_literal, skip)
+    return singularize(segs[0]) if segs else ""
 
 
-def seam_overlay(root, files, candidates, churn_map, ui_attribution=None):
+def seam_overlay(root, files, candidates, churn_map, ui_attribution=None, contexts=None):
     """Per-candidate seam signals. Two distinct route families on one aggregate
-    is the split candidate the feature proposal will surface with its evidence."""
+    is the split candidate the feature proposal will surface with its evidence.
+
+    `contexts` ({context: [candidate, …]}) names each candidate's bounded context so
+    its route prefix can be skipped — without it every route in a /care/… service
+    falls into one `care` family and no split is ever visible."""
     owner = _candidate_of_file(candidates)
     by_name = {c["name"]: c for c in candidates}
+    ctx_of = {n: ctx for ctx, names in (contexts or {}).items() for n in names}
+    for c in candidates:
+        if c.get("context"):
+            ctx_of[c["name"]] = c["context"]
     out = {c["name"]: {"route_families": {}, "command_groups": set(),
                        "ui_segments": set(), "churn": 0, "api_files": 0}
            for c in candidates}
@@ -1433,8 +2421,13 @@ def seam_overlay(root, files, candidates, churn_map, ui_attribution=None):
         body = _read_source(root, f)
         if not body:
             continue
-        for m in ROUTE_ATTR_RE.finditer(body):
-            fam = _route_family(next((g for g in m.groups() if g), ""))
+        # A handler is named by its CLASS, not its file: FooCommandHandler routinely
+        # lives in FooCommand.cs beside the command it handles.
+        for m in HANDLER_CLASS_RE.finditer(body):
+            out[name]["command_groups"].add(_entity_noun(m.group(1) + ".x") or m.group(1))
+        skip = (ctx_of[name],) if ctx_of.get(name) else ()
+        for _verb, path in _routes_in(body):
+            fam = _route_family(path, skip)
             if fam:
                 out[name]["route_families"][fam] = out[name]["route_families"].get(fam, 0) + 1
                 out[name]["api_files"] += 1
@@ -1503,6 +2496,20 @@ def derive_contexts(candidates, files):
             return part
         return ""
 
+    # 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.
+    declared = {}
+    for c in candidates:
+        if c.get("context"):
+            declared.setdefault(c["context"], []).append(c["name"])
+    candidates = [c for c in candidates if not c.get("context")]
+    if not candidates:
+        return {k: sorted(v) for k, v in sorted(declared.items())}
+
     groups = {}
     for c in candidates:
         # Voted across the candidate's own files rather than read off module_dir:
@@ -1528,6 +2535,8 @@ def derive_contexts(candidates, files):
             for k in singles:
                 merged.extend(groups.pop(k))
             groups.setdefault("Core", []).extend(merged)
+    for k, v in declared.items():
+        groups.setdefault(k, []).extend(v)
     return {k: sorted(v) for k, v in sorted(groups.items())}
 
 
@@ -1555,53 +2564,216 @@ def dependency_waves(nodes, edges):
     return waves, cycles
 
 
-def propose_features(candidates, seams, edges, contexts):
-    """Default 1:1 — one aggregate, one feature, same name.
-
-    A split is PROPOSED where Pass B found two or more distinct seams on one
-    aggregate, carrying the evidence that suggested it, and is never applied:
-    the operator confirms it by editing the proposal. Where a split is taken the
-    feature is named from the capability, not from a second copy of the noun."""
+def _creating_op(aggregate, ops, context):
+    """The operation that brings an instance of `aggregate` into existence, or None.
+
+    A POST on the aggregate's collection — no instance id in the path — is the
+    evidence; a creation verb in a name that carries the aggregate is the fallback
+    where the route is not declared. Whichever feature holds this operation is the
+    one every other feature on the aggregate has to follow: nothing can be amended,
+    signed or cancelled before something created it."""
+    mine = [o for o in ops if o["acts_on"][:1] == [aggregate] and o["kind"] == "command"]
+    for o in mine:
+        for verb, path in o["routes"]:
+            if verb == "POST" and len(_route_segments(path, (context,))) == 1 \
+                    and "{" not in path.rstrip("/").rsplit("/", 1)[-1]:
+                return o["name"]
+    for o in mine:
+        if CREATE_NAME_RE.match(o["name"]) and o["name"][CREATE_NAME_RE.match(o["name"]).end():] == aggregate:
+            return o["name"]
+    return None
+
+
+def propose_features(candidates, seams, edges, contexts, operations=None, ui_feats=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
+    acts on one or more aggregates of ONE bounded context, and several features may act
+    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:
+
+      1. every UI feature folder becomes a feature, named verbatim, holding the
+         operations it calls and acting on those operations' aggregates;
+      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
+         one feature per aggregate named after it — the documented default, labelled
+         as a default so the operator renames it to the capability it serves.
+
+    An operation is never a feature, and neither is a whole bounded context.
+
+    ORDER comes from creation: on each aggregate the feature holding its creating
+    operation goes first, every other feature on it depends on that one, and an
+    aggregate that references another by id depends on the other's creator. With no
+    operations at all the aggregate graph orders the defaults, as it always did.
+
+    A split is PROPOSED where Pass B found two or more distinct seams on a default
+    feature's aggregate, carrying the evidence that suggested it, and is never
+    applied."""
     ctx_of = {name: ctx for ctx, names in contexts.items() for name in names}
-    out = []
+    cand = {c["name"]: c for c in candidates}
+    ops = [o for o in (operations or []) if o["acts_on"] and o["acts_on"][0] in cand]
+    op_by_key = {_ui_norm(o["name"]): o for o in ops}
+
+    # Which aggregate a route family names, learned from the operations' own routes.
+    fam_to_agg = {}
+    for o in ops:
+        for _v, path in o["routes"]:
+            fam = _route_family(path, (ctx_of.get(o["acts_on"][0], ""),))
+            if fam:
+                fam_to_agg.setdefault(_ui_norm(fam), {}).setdefault(o["acts_on"][0], 0)
+                fam_to_agg[_ui_norm(fam)][o["acts_on"][0]] += 1
+
+    feats, claimed, unlinked = [], set(), []
+    for name, rec in sorted((ui_feats or {}).items()):
+        mine = []
+        for ident in sorted(rec["calls"]) + [name]:
+            k = _ui_norm(ident)
+            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)
+        aggs = []
+        for o in mine:
+            aggs += [a for a in o["acts_on"] if a not in aggs]
+        for lit in sorted(rec["routes"]):
+            for ctx in set(ctx_of.values()) or {""}:
+                fam = _route_family(lit, (ctx,))
+                hit = fam_to_agg.get(_ui_norm(fam), {})
+                if hit:
+                    a = max(sorted(hit), key=hit.get)
+                    if a not in aggs:
+                        aggs.append(a)
+        if not aggs:
+            unlinked.append(name)
+            continue
+        votes = {}
+        for a in aggs:
+            votes[ctx_of.get(a, "Core")] = votes.get(ctx_of.get(a, "Core"), 0) + 1
+        ctx = max(sorted(votes), key=votes.get)
+        claimed.update(o["name"] for o in mine)
+        feats.append({"feature": name, "context": ctx,
+                      "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"])})
+
+    # Shared reads join every feature already acting on their aggregate.
+    for o in ops:
+        if o["name"] in claimed or o["kind"] != "query":
+            continue
+        takers = [f for f in feats if o["acts_on"][0] in f["aggregates"]]
+        for f in takers:
+            f["operations"].append(o["name"])
+        if takers:
+            claimed.add(o["name"])
+
+    # The default: one feature per aggregate for what no capability claimed.
+    by_name = {f["feature"]: f for f in feats}
     for c in candidates:
-        sig = seams.get(c["name"], {})
+        a = c["name"]
+        on_a = [f for f in feats if a in f["aggregates"]]
+        rest = [o["name"] for o in ops if o["acts_on"][0] == a and o["name"] not in claimed]
+        if on_a and not rest:
+            continue
+        name = a if a not in by_name else f"{a}Operations"
+        f = {"feature": name, "context": ctx_of.get(a, "Core"), "aggregates": [a],
+             "references": [], "operations": rest, "source": "aggregate-default",
+             "ui_files": 0}
+        feats.append(f)
+        by_name[name] = f
+        claimed.update(rest)
+
+    # Creation order.
+    op_of = {o["name"]: o for o in ops}
+    creator = {}
+    for c in candidates:
+        mk = _creating_op(c["name"], ops, ctx_of.get(c["name"], ""))
+        holder = next((f["feature"] for f in feats if mk and mk in f["operations"]), None)
+        if not holder:
+            homes = [f["feature"] for f in feats if f["aggregates"][:1] == [c["name"]]]
+            holder = homes[0] if len(homes) == 1 else None
+        if holder:
+            creator[c["name"]] = holder
+
+    out = []
+    for f in feats:
+        primary = f["aggregates"][0]
+        deps = set()
+        for a in f["aggregates"]:
+            if creator.get(a) and creator[a] != f["feature"]:
+                deps.add(creator[a])
+            for b in edges.get(a, set()):
+                if creator.get(b) and creator[b] != f["feature"]:
+                    deps.add(creator[b])
+        sig = seams.get(primary, {})
         fams = sig.get("route_families", [])
+        op_files = {x for n in f["operations"] for x in op_of.get(n, {}).get("files", [])}
+        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']} "
+                        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 "
+                        "to the capability they serve, or move them to a feature above")
+        else:
+            evidence = sig.get("evidence", "") or "aggregate default — no operations found"
         feature = {
-            "feature": c["name"],
-            "aggregate": c["name"],
-            "context": ctx_of.get(c["name"], "Core"),
-            "files": c.get("raw_file_count", c.get("file_count", 0)),
-            "churn": c.get("churn", 0),
+            "feature": f["feature"],
+            "aggregate": primary,
+            "aggregates": f["aggregates"],
+            "context": f["context"],
+            "files": (cand[primary].get("raw_file_count", cand[primary].get("file_count", 0))
+                      if sole else len(op_files)) + f["ui_files"],
+            "churn": cand[primary].get("churn", 0) if sole else 0,
             "seam": sig.get("seam", ""),
             "seam_count": sig.get("seam_count", 0),
-            "evidence": sig.get("evidence", ""),
-            "depends_on": sorted(edges.get(c["name"], set())),
+            "evidence": evidence,
+            "depends_on": sorted(deps),
+            "operations": f["operations"],
+            "source": f["source"],
+            "references_by_id": f["references"],
             "split_proposed": [],
         }
-        if sig.get("split_candidate"):
+        if f["source"] == "aggregate-default" and sig.get("split_candidate"):
             feature["split_proposed"] = [
-                {"feature": _capability_name(c["name"], f),
-                 "seam": f,
-                 "why": f"a second route family `{f}` cuts over independently of `{fams[0]}`"}
-                for f in fams[1:4]
+                {"feature": _capability_name(primary, fm),
+                 "seam": fm,
+                 "why": f"a second route family `{fm}` cuts over independently of `{fams[0]}`"}
+                for fm in fams[1:4]
             ]
         out.append(feature)
     out.sort(key=lambda x: (x["context"], -x["files"], x["feature"]))
-    return out
+    # 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.
+    capab = {a for f in feats if f["source"] == "ui-feature" for a in f["aggregates"]}
+    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,
+    }
+    return out, notes
 
 
-def aggregate_signals(files, churn_map):
-    """Derive CANDIDATE aggregate roots — the base unit the inventory and onboard
-    workflows turn into a specs/<Feature>/ slice.
+def aggregate_signals(files, churn_map, root=None):
+    """Derive CANDIDATE aggregate roots — the unit onboard writes one OKF concept for.
 
-    Delegates to Pass A's structure strategy, which reads the repo's organising
-    axis (module-major, project-major, vertical slice, n-tier, or the build
-    manifest) instead of assuming one. Every caller of this function gets the
-    same candidate shape it always did, with the strategy's extra keys added.
+    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.
 
     Signals only — the workflow's agent draws the real boundaries. Empty for a
     repo with no recognizable structure at all."""
+    if root:
+        declared = strategy_domain(root, files, churn_map)
+        if any(c.get("operations") for c in declared):
+            return declared
     return strategy_structure(None, files, churn_map)
 
 
@@ -1660,7 +2832,88 @@ def _ui_name_tokens(name):
     return out
 
 
-def attribute_ui_files(signals, fe_files, churn_map, ui_roots):
+# A UI feature folder: features/<Feature>/ under the UI lane. Lower-case on purpose —
+# 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)
+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_\-/${}.:]*)[`'"]""")
+
+
+def ui_features(root, fe_files, ui_prefix):
+    """The CAPABILITIES the UI lane records: {Feature: {"files", "calls", "routes"}}.
+
+    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
+    whole repo, and a backend's Features/ folders are not capabilities."""
+    if not ui_prefix:
+        return {}
+    feats = {}
+    for f in fe_files:
+        if not f.startswith(ui_prefix) or not UI_SOURCE_RE.search(f):
+            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()})
+        rec["files"].append(f)
+        body = _read_source(root, f)
+        for names, mod in API_IMPORT_RE.findall(body):
+            if API_MODULE_RE.search(mod):
+                rec["calls"].update(n.strip().split(" as ")[0].strip()
+                                    for n in names.split(",") if n.strip())
+        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["routes"].update(UI_ROUTE_LITERAL_RE.findall(body))
+    return feats
+
+
+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."""
+    children = _child_dirs(files)
+    owner = _candidate_of_file(candidates)
+    op_files = {}
+    for f in files:
+        if not _lang_of(f) or TEST_PATH_RE.search(f):
+            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(
+                (".cs", ".java", ".kt", ".ts", ".py")) else ""):
+            op_files.setdefault(m.group(1), []).append(f)
+    ops = []
+    for op, fs in sorted(op_files.items()):
+        votes = {}
+        for f in fs:
+            if owner.get(f):
+                votes[owner[f]] = votes.get(owner[f], 0) + 1
+        routes = []
+        for f in fs:
+            routes.extend(_routes_in(_read_source(root, f)))
+        ops.append({"name": op, "context": "", "module": "", "files": sorted(set(fs)),
+                    "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))})
+    return ops
+
+
+def attribute_ui_files(signals, fe_files, churn_map, ui_roots, feature_aggs=None):
     """Attribute each frontend file to the aggregate it serves.
 
     WHY THIS EXISTS. scope_to_lanes splits the substrate so the backend and frontend
@@ -1669,7 +2922,14 @@ def attribute_ui_files(signals, fe_files, churn_map, ui_roots):
     serves it. adopt then reverses that slice with no UI source within reach, so the
     frontend lane's design has nothing to be derived from.
 
-    The match is by NAME with both sides normalised: a DIRECTORY SEGMENT named for the
+    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.
+
+    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
     matches once its UI role suffix is stripped. Where several aggregates match, the
     LONGEST name wins, so `MedicinalProduct` takes a file that `Product` would also
@@ -1714,19 +2974,37 @@ def attribute_ui_files(signals, fe_files, churn_map, ui_roots):
     for c, _ in token_map:
         c.setdefault("ui_files", [])
 
-    unattributed = []
+    # {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:
-        segments = {_ui_norm(p) for p in os.path.dirname(f).split("/") if p}
-        stem = _ui_stem(f)
-        for c, tokens in token_map:
-            if (segments & tokens) or (stem and stem in tokens):
-                c["ui_files"].append(f)
-                c["churn"] += churn_map.get(f, 0)
-                break
+        owners = mapped(f)
+        if owners:
+            by_map += 1
         else:
+            segments = {_ui_norm(p) for p in os.path.dirname(f).split("/") if p}
+            stem = _ui_stem(f)
+            owners = next(([c] for c, tokens in token_map
+                           if (segments & tokens) or (stem and stem in tokens)), [])
+        if not owners:
             unattributed.append(f)
+            continue
+        attributed_files.add(f)
+        for c in owners:
+            c["ui_files"].append(f)
+            c["churn"] += churn_map.get(f, 0)
 
-    attributed = 0
     with_ui = 0
     for c, _ in token_map:
         c["ui_files"] = sorted(set(c["ui_files"]))[:CAP]
@@ -1734,15 +3012,71 @@ def attribute_ui_files(signals, fe_files, churn_map, ui_roots):
         # aggregate ranking is backend evidence and a UI-heavy slice must not
         # outrank a domain-heavy one on component count.
         c["ui_file_count"] = len(c["ui_files"])
-        attributed += c["ui_file_count"]
         if c["ui_file_count"]:
             with_ui += 1
 
-    return {"attributed_file_count": attributed, "aggregates_with_ui": with_ui,
+    return {"attributed_file_count": len(attributed_files), "aggregates_with_ui": with_ui,
+            "attributed_by_feature_map": by_map,
             "unattributed_count": len(unattributed),
             "unattributed": sorted(unattributed)[:CAP], "search_roots": roots}
 
 
+def _feature_aggregates(map_path):
+    """{feature: [aggregates it acts on]} from a feature map, or {} when there is none
+    or it cannot be read — the scan runs before any map exists, too."""
+    try:
+        with open(map_path, encoding="utf-8") as fh:
+            m = json.load(fh)
+    except (OSError, ValueError):
+        return {}
+    out = {}
+    for f in m.get("features", []) if isinstance(m, dict) else []:
+        name = f.get("feature") if isinstance(f, dict) else None
+        aggs = (f.get("aggregates") or ([f["aggregate"]] if f.get("aggregate") else [])) \
+            if name else []
+        if name and aggs:
+            out[name] = [a for a in aggs if isinstance(a, str)]
+    return out
+
+
+# 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")
+_UI_ONLY_KEYS = ("frontend_signals", "ui_attribution")
+_PATH_LIST_KEYS = ("dependency_manifests", "entrypoints", "api_definitions",
+                   "route_like_files", "data_layer_files", "ops_files", "docs",
+                   "config_files", "adr_docs")
+
+
+def lane_views(inv, ui_prefix):
+    """The substrate as each lane's authoring steps need it: (service_view, ui_view).
+
+    onboard inlines the substrate into every step that authors from it, and each of
+    those steps governs ONE lane. The full substrate hands the service lane's rule
+    author the UI's whole file inventory, and the UI lane's authors every backend
+    aggregate — material their prompts then tell them to ignore. Each view keeps the
+    repository-wide facts (git, manifests, CI, docs, top-level layout) and its own
+    lane's signals. Where a UI root is declared, the path lists and the churn are also
+    split at it: the service view keeps what lies outside it, the UI view what lies
+    inside. Without a declared UI root there is nothing to split them on."""
+    def split(view, keep):
+        for k in _PATH_LIST_KEYS:
+            if isinstance(view.get(k), list):
+                view[k] = [f for f in view[k] if keep(f)]
+        hist = dict(view["git"]["history"])
+        hist["churn"] = [c for c in hist.get("churn", []) if keep(c["file"])]
+        view["git"] = dict(view["git"], history=hist)
+        return view
+
+    svc = {k: v for k, v in inv.items() if k not in _UI_ONLY_KEYS}
+    ui = {k: v for k, v in inv.items() if k not in _SERVICE_ONLY_KEYS}
+    svc["view"], ui["view"] = "service", "ui"
+    if ui_prefix:
+        svc = split(svc, lambda f: not f.startswith(ui_prefix))
+        ui = split(ui, lambda f: f.startswith(ui_prefix))
+    return svc, ui
+
+
 def bundle_state(bundle_dir):
     """How many concept .md files a candidate bundle already holds (the OKF
     generate guard: a non-empty bundle means /appweaver inventory would
@@ -1795,11 +3129,11 @@ def scope_to_lanes(files, service_root, ui_root):
 
 def cmd_scan(args):
     root = os.path.abspath(args.root or os.getcwd())
-    config_excludes = load_config_excludes(args.config)
+    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)
+    files = list_files(root, config_excludes, (args.service_root, args.ui_root))
     churn_list, commits_scanned = churn(root, config_excludes)
     churn_map = {c["file"]: c["commits"] for c in churn_list}
 
@@ -1819,16 +3153,18 @@ def cmd_scan(args):
             topdirs[top] = topdirs.get(top, 0) + 1
     top_level_dirs = dict(sorted(topdirs.items(), key=lambda kv: kv[1], reverse=True)[:20])
 
-    def category(rx):
-        hits = matching(files, rx)
+    def category(rx_or_hits):
+        hits = (matching(files, rx_or_hits) if hasattr(rx_or_hits, "search")
+                else list(rx_or_hits))
         return {"items": hits[:CAP], "truncated": len(hits) > CAP}
 
+    route_files, data_files = api_and_data_files(root, files)
     cats = {
         "dependency_manifests": category(MANIFESTS_RE),
         "entrypoints": category(ENTRYPOINTS_RE),
         "api_definitions": category(API_DEFS_RE),
-        "route_like_files": category(ROUTES_RE),
-        "data_layer_files": category(DB_FILES_RE),
+        "route_like_files": category(route_files),
+        "data_layer_files": category(data_files),
         "ops_files": category(OPS_FILES_RE),
         "docs": category(DOCS_RE),
         "config_files": category(CONFIGS_RE),
@@ -1836,7 +3172,7 @@ def cmd_scan(args):
     }
     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)
+    signals = aggregate_signals(be_files, churn_map, root)
     fsig = frontend_signals(fe_files, churn_map)
 
     # A DECLARED UI lane is a lane. The strength test below UI_STRONG_MIN exists to
@@ -1867,7 +3203,10 @@ def cmd_scan(args):
         ui_search_roots = [r.get("root", "") for r in (fsig.get("roots") or [])]
     else:
         ui_search_roots = []
-    ui_attr = attribute_ui_files(signals, fe_files, churn_map, 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))
 
     present, md_count = bundle_state(bundle_dir)
 
@@ -1907,6 +3246,11 @@ def cmd_scan(args):
     os.makedirs(os.path.dirname(out), exist_ok=True)
     with open(out, "w", encoding="utf-8") as f:
         json.dump(inv, f, indent=2)
+    stem = os.path.splitext(out)[0]
+    out_service, out_ui = stem + ".service.json", stem + ".ui.json"
+    for path, view in zip((out_service, out_ui), lane_views(inv, ui_prefix)):
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(view, f, indent=2)
 
     # Human summary -> STDERR (must not pollute the JSON contract on stdout).
     print(f"Inventory written to {out}", file=sys.stderr)
@@ -1937,6 +3281,9 @@ def cmd_scan(args):
     # Machine contract -> LAST stdout line (bound by the orchestrator).
     print(json.dumps({
         "inventory_json": out,
+        # The same substrate cut per lane, for steps that author one lane's governance.
+        "inventory_service_json": out_service,
+        "inventory_ui_json": out_ui,
         "root": root,
         "file_count": inv["file_count"],
         "head": inv["git"]["head"],
@@ -1986,12 +3333,13 @@ PROPOSAL_FALLBACK = """# Proposed Inventory
 
 **Repository:** `{root}`  ·  **Commit:** `{head}`  ·  **Generated:** {date}
 **Pass A strategy:** `{strategy}` — {reason}
-**Scanned:** {files} files, {code} source files  ·  **Coverage:** {coverage}%
+**Scanned:** {scanned}  ·  **Coverage:** {coverage}%
 
 The boundary map for this codebase, and yours to change. Edit it, then run
 `/appweaver inventory apply` to validate the edits and regenerate the machine map
-onboard reads. The Aggregate column must name an aggregate the scan found;
-everything else is yours.
+onboard reads. The Aggregate column must name an aggregate the scan found, and an
+Operations cell only operations it found; everything else is yours. One row per
+feature per aggregate it acts on.
 
 ## Strategy probe
 
@@ -2001,10 +3349,18 @@ everything else is yours.
 
 {context_table}
 
+## Aggregates
+
+{aggregate_table}
+
 ## Features
 
 {feature_table}
-{splits_section}{cycles_section}"""
+{review_section}{splits_section}{cycles_section}
+## Operations
+
+{operation_table}
+{unplaced_section}"""
 
 PROPOSAL_TEMPLATE_NAME = "proposed-inventory-template.md"
 
@@ -2060,11 +3416,44 @@ def _parse_md_tables(text, section):
     return rows
 
 
-def _write_proposal(path, meta, contexts, features, waves, cycles, probe_rows):
+# Folders listed under Unplaced source before the rest are counted instead of shown.
+UNPLACED_ROWS = 25
+
+
+def _names_preview(cands, limit=4):
+    """The first few candidate names, so a strategy is judged by WHAT it found and not
+    only by how many: `structure` reporting 2 aggregates on a one-context codebase has
+    found the context and the host project, and the count alone does not say so."""
+    names = [c["name"] for c in cands]
+    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
+    sit outside both lanes and are read by nothing here, so a repository-wide file count
+    would overstate the scan."""
+    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"
+    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 "")
+
+
+def _write_proposal(path, meta, contexts, features, waves, cycles, probe_rows,
+                    operations=None, notes=None, candidates=None, unplaced=None):
     ctx_files, ctx_deps = {}, {}
     fmap = {f["feature"]: f for f in features}
+    # A context's files are its aggregates' files, which are disjoint. Adding up its
+    # features' counts instead misses the model files two features share and counts a
+    # shared read once per feature that joins it.
+    agg_ctx = {a: f["context"] for f in features for a in (f.get("aggregates") or [f["aggregate"]])}
+    for c in candidates or []:
+        ctx = agg_ctx.get(c["name"], c.get("context", ""))
+        ctx_files[ctx] = ctx_files.get(ctx, 0) + c.get("raw_file_count", 0)
     for f in features:
-        ctx_files[f["context"]] = ctx_files.get(f["context"], 0) + f["files"]
+        if not candidates:
+            ctx_files[f["context"]] = ctx_files.get(f["context"], 0) + f["files"]
         for d in f["depends_on"]:
             dctx = fmap.get(d, {}).get("context")
             if dctx and dctx != f["context"]:
@@ -2075,25 +3464,91 @@ def _write_proposal(path, meta, contexts, features, waves, cycles, probe_rows):
     for f in features:
         ctx_wave[f["context"]] = min(ctx_wave.get(f["context"], 99),
                                      wave_of.get(f["feature"], 99))
+    ctx_aggs = {}
+    for f in features:
+        ctx_aggs.setdefault(f["context"], set()).update(f.get("aggregates") or [f["aggregate"]])
 
     context_table = _md_table(
-        ["Order", "Bounded Context", "Depends On", "Features", "Files"],
+        ["Order", "Bounded Context", "Depends On", "Aggregates", "Features", "Files"],
         [[i + 1, ctx, ", ".join(sorted(ctx_deps.get(ctx, set()))) or "—",
-          len(names), ctx_files.get(ctx, 0)]
+          ", ".join(sorted(ctx_aggs.get(ctx, set()))) or "—",
+          len({f["feature"] for f in features if f["context"] == ctx}), ctx_files.get(ctx, 0)]
          for i, (ctx, names) in enumerate(
              sorted(contexts.items(), key=lambda kv: (ctx_wave.get(kv[0], 99), kv[0])))
          if names])
 
+    # ONE ROW PER (feature, aggregate) — the many-to-many relation written the way
+    # `apply` reads it back: two rows with one Feature name are one feature acting on
+    # two aggregates. The Operations cell lists what the feature does to THAT
+    # aggregate, and is editable: moving a name between rows moves the operation.
+    op_of = {o["name"]: o for o in (operations or [])}
     rows = []
     for f in sorted(features, key=lambda x: (wave_of.get(x["feature"], 99),
                                              x["context"], x["feature"])):
-        rows.append([f["feature"], f["context"], f["aggregate"],
-                     wave_of.get(f["feature"], "?"),
-                     ", ".join(f["depends_on"]) or "—",
-                     f["files"], f["churn"], f["seam"] or "—"])
+        aggs = f.get("aggregates") or [f["aggregate"]]
+        for i, a in enumerate(aggs):
+            ops_here = [n for n in f.get("operations", [])
+                        if (op_of.get(n, {}).get("acts_on") or [aggs[0]])[0] == a
+                        or (a == aggs[0] and not op_of.get(n, {}).get("acts_on"))]
+            rows.append([f["feature"], f["context"], a,
+                         wave_of.get(f["feature"], "?"),
+                         (", ".join(f["depends_on"]) or "—") if i == 0 else "—",
+                         f["files"] if i == 0 else "", f["churn"] if i == 0 else "",
+                         (f["seam"] or "—") if i == 0 else "—",
+                         ", ".join(ops_here) or "—"])
     feature_table = _md_table(
         ["Feature", "Bounded Context", "Aggregate", "Wave", "Depends On",
-         "Files", "Churn", "Seam"], rows)
+         "Files", "Churn", "Seam", "Operations"], rows)
+
+    # Read-only evidence: what the aggregates ARE and what each operation touches.
+    acting = {}
+    for f in features:
+        for a in f.get("aggregates") or [f["aggregate"]]:
+            acting.setdefault(a, []).append(f["feature"])
+    agg_rows = []
+    for c in sorted(candidates or [], key=lambda c: (c.get("context", ""), c["name"])):
+        agg_rows.append([c["name"], next((f["context"] for f in features
+                                          if c["name"] in (f.get("aggregates") or [f["aggregate"]])),
+                                         c.get("context", "—")),
+                         f"`{c['root_file']}`" if c.get("root_file") else "—",
+                         c.get("raw_file_count", 0),
+                         len([o for o in (operations or []) if o["acts_on"][:1] == [c["name"]]]),
+                         ", ".join(acting.get(c["name"], [])) or "—"])
+    aggregate_table = _md_table(
+        ["Aggregate", "Bounded Context", "Declared in", "Files", "Operations", "Acted on by"],
+        agg_rows) if agg_rows else "_No aggregates were identified._"
+
+    operation_table = ""
+    if operations:
+        operation_table = _md_table(
+            ["Operation", "Kind", "Acts on", "Route", "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(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._")
+
+    review_section = ""
+    orphaned = (notes or {}).get("orphaned") or []
+    unlinked = (notes or {}).get("unlinked_ui") or []
+    if orphaned or unlinked:
+        lines = ["\n## Needs a decision\n"]
+        if orphaned:
+            lines.append("These commands act on an aggregate that has capability features, "
+                         "but no UI feature calls them, so they fell to a per-aggregate "
+                         "default. Move each into the feature it belongs to — edit the "
+                         "Operations cells above — or rename the default to the capability "
+                         "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")
+        review_section = "\n".join(lines)
 
     # Both trailing sections are conditional and carry their own leading blank line,
     # so the template can sit them side by side and neither leaves a gap when absent.
@@ -2118,13 +3573,41 @@ def _write_proposal(path, meta, contexts, features, waves, cycles, probe_rows):
             "merging them in the Features table.\n\n"
             + "\n".join(f"- {' → '.join(c)} → {c[0]}" for c in cycles) + "\n")
 
+    # Informational: nothing here is editable, and most of it needs nothing. It is here
+    # so that what the map leaves out is seen rather than inferred from a percentage.
+    unplaced_section = ""
+    if unplaced:
+        by_dir = {}
+        for f in unplaced:
+            by_dir.setdefault(os.path.dirname(f) or ".", []).append(os.path.basename(f))
+        dirs = sorted(by_dir)
+        shown = dirs[:UNPLACED_ROWS]
+        unplaced_section = (
+            "\n## Unplaced source\n\n"
+            f"{len(unplaced)} source file(s) in the service lane that no aggregate owns — "
+            "the part of the code the Coverage figure leaves out. Hosting, dependency "
+            "wiring, infrastructure and cross-cutting helpers belong here and need nothing. "
+            "Look twice at a folder that plainly serves one aggregate (a convention the scan "
+            "did not recognise), code nothing in the product uses (a leftover template or "
+            "sample), and a whole project that is a bounded context of its own.\n\n"
+            + _md_table(["Folder", "Files", "Examples"],
+                        [[f"`{d}/`", len(by_dir[d]),
+                          ", ".join(sorted(by_dir[d])[:4]) + (" …" if len(by_dir[d]) > 4 else "")]
+                         for d in shown])
+            + (f"\n\n…and {len(dirs) - len(shown)} more folder(s)." if len(dirs) > len(shown) else "")
+            + "\n")
+
     values = dict(meta)
     values.update({
         "probe_table": _md_table(
-            ["Strategy", "Features", "Coverage", "Singletons", "Chosen", "Availability"],
+            ["Strategy", "Aggregates", "Names", "Coverage", "Singletons", "Chosen", "Availability"],
             probe_rows),
+        "unplaced_section": unplaced_section,
         "context_table": context_table,
         "feature_table": feature_table,
+        "aggregate_table": aggregate_table,
+        "operation_table": operation_table,
+        "review_section": review_section,
         "splits_section": splits_section,
         "cycles_section": cycles_section,
     })
@@ -2181,13 +3664,14 @@ 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."""
     root = os.path.abspath(args.root or os.getcwd())
-    files = list_files(root, load_config_excludes(args.config))
+    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)
-    churn_list, _ = churn(root, load_config_excludes(args.config))
+    churn_list, _ = churn(root, excludes)
     churn_map = {c["file"]: c["commits"] for c in churn_list}
 
-    results, avail, graph, gstats, ents = run_probe(root, be_files, churn_map)
+    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 ""
@@ -2200,40 +3684,83 @@ def cmd_propose(args):
         picked = wanted
     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)])
     if not picked:
-        print(json.dumps({"ok": "false", "feature_count": 0, "error":
-                          "no Pass A strategy produced candidates"}))
-        return 1
+        why = "; ".join(f"{n}: {avail[n]['reason']}" for n in STRATEGY_PREFERENCE)
+        return _nothing_to_propose(
+            root, mp, f"No candidate aggregates were found in the service lane "
+                      f"'{svc_prefix or '.'}' ({len(be_files)} file(s), {code_total} of them "
+                      f"source) — {why}.")
 
     candidates = results[picked]["candidates"]
-    edges = candidate_edges(candidates, graph)
-    seams = seam_overlay(root, be_files, candidates, churn_map)
     contexts = derive_contexts(candidates, be_files)
-    features = propose_features(candidates, seams, edges, contexts)
+    # 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))
+    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)
+    for o in operations:
+        o["features"] = [f["feature"] for f in features if o["name"] in f["operations"]]
+    if not features:
+        return _nothing_to_propose(
+            root, mp, f"`{picked}` found {len(candidates)} aggregate(s), but no feature "
+                      f"was proposed over them.")
     waves, cycles = dependency_waves([f["feature"] for f in features],
                                      {f["feature"]: set(f["depends_on"]) for f in features})
+    # The map lists features in the order the proposal's table does — dependency order —
+    # so a reader of the map that walks its list meets a creator before what needs it,
+    # and `apply` over an unedited proposal writes the same list back.
+    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"]))
 
-    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)])
+    lane_files = 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": len(files),
-            "code": code_total, "coverage": results[picked]["coverage_pct"]}
-    probe_rows = [[n, results[n]["count"], f"{results[n]['coverage_pct']}%",
+            "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)}
+    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']}"]
+                  [n, "—", "—", "—", "—", "", f"unavailable — {avail[n]['reason']}"]
                   for n in STRATEGY_PREFERENCE]
-    _write_proposal(md, meta, contexts, features, waves, cycles, probe_rows)
-    _write_feature_map(mp, meta, contexts, features, waves, cycles, results, avail, gstats)
+    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))
+    aggregate_detail = [
+        {"name": c["name"], "context": ctx_of.get(c["name"], ""),
+         "root_file": c.get("root_file", ""), "declared": picked == "domain",
+         "entities": list(c.get("entities") or []),
+         "operations": [o["name"] for o in operations if o["acts_on"][:1] == [c["name"]]],
+         "references_by_id": sorted(edges.get(c["name"], set()))}
+        for c in candidates]
+    _write_proposal(md, meta, contexts, features, waves, cycles, probe_rows,
+                    operations, notes, [dict(c, context=ctx_of.get(c["name"], "")) for c in candidates],
+                    unplaced)
+    _write_feature_map(mp, meta, contexts, features, waves, cycles, results, avail, gstats,
+                       operations=operations, aggregate_detail=aggregate_detail)
 
     print(f"Proposed inventory written to {md}", file=sys.stderr)
-    print(f"  strategy: {picked}  features: {len(features)}  "
-          f"contexts: {len(contexts)}  waves: {len(waves)}", file=sys.stderr)
+    print(f"  strategy: {picked}  contexts: {len(contexts)}  aggregates: {len(candidates)}  "
+          f"features: {len(features)}  operations: {len(operations)}  waves: {len(waves)}",
+          file=sys.stderr)
     print(json.dumps({
         "ok": "true", "proposal_md": md, "feature_map": mp, "root": root,
         "strategy": picked, "feature_count": len(features),
+        "aggregate_count": len(candidates), "operation_count": len(operations),
+        "orphaned_count": len(notes["orphaned"]),
         "context_count": len(contexts), "wave_count": len(waves),
         "cycle_count": len(cycles),
         "contexts_ordered": ", ".join(_ordered_contexts(contexts, features, waves)),
@@ -2242,9 +3769,11 @@ def cmd_propose(args):
         # 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']} features, {results[n]['coverage_pct']}% coverage, "
-            f"{results[n]['singletons']} singleton(s)"
+            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
         ],
@@ -2252,6 +3781,24 @@ def cmd_propose(args):
     return 0
 
 
+def _nothing_to_propose(root, mp, message):
+    """A scan with nothing to propose writes nothing. feature-map.json is what onboard
+    reads, so an empty one would be onboarded as a project with no contexts, and a map
+    from an earlier run would be overwritten by it — that map is left as it was.
+
+    Exits 0: finding nothing is a result the workflow's gate reports, not a failure of
+    the script, so the propose step needs no `on_error` to reach that gate."""
+    kept = os.path.isfile(mp)
+    message += (" Nothing was written" + (f"; the map from an earlier run at {mp} is unchanged."
+                                         if kept else "."))
+    print(message, file=sys.stderr)
+    print(json.dumps({"ok": "false", "root": root, "feature_map": "",
+                      "feature_count": 0, "aggregate_count": 0,
+                      "existing_map_kept": "true" if kept else "false",
+                      "error": message}))
+    return 0
+
+
 def _ordered_contexts(contexts, features, waves):
     wave_of = {m: w["wave"] for w in waves for m in w["members"]}
     first = {}
@@ -2262,11 +3809,16 @@ def _ordered_contexts(contexts, features, waves):
 
 
 def _write_feature_map(path, meta, contexts, features, waves, cycles,
-                       results=None, avail=None, gstats=None, aggregates=None):
+                       results=None, avail=None, gstats=None, aggregates=None,
+                       operations=None, aggregate_detail=None, prior=None):
     """The machine contract onboard reads. Regenerated from the markdown on every
     apply, so the document stays the thing a person edits and this stays derived.
     `aggregates` is the registry of aggregates the scan found — what the Aggregate
-    column may name — and outlives any feature that stops listing one."""
+    column may name — and outlives any feature that stops listing one.
+
+    `operations` and `aggregate_detail` are the model below the features: which
+    operations exist, what each acts on, and which context declares each aggregate.
+    Every key a reader already relies on keeps its shape — these two are additions."""
     registry = aggregates if aggregates is not None else sorted(
         {a for f in features for a in (f.get("aggregates") or [f.get("aggregate")]) if a})
     payload = {
@@ -2278,6 +3830,8 @@ def _write_feature_map(path, meta, contexts, features, waves, cycles,
         "contexts": [
             {"name": c, "order": i,
              "features": [f["feature"] for f in features if f["context"] == c],
+             "aggregates": sorted({a for f in features if f["context"] == c
+                                   for a in (f.get("aggregates") or [f.get("aggregate")]) if a}),
              "onboarded": False}
             for i, c in enumerate(_ordered_contexts(contexts, features, waves))
         ],
@@ -2286,6 +3840,18 @@ def _write_feature_map(path, meta, contexts, features, waves, cycles,
         "waves": waves,
         "cycles": cycles,
     }
+    if operations is not None:
+        payload["operations"] = [
+            {"name": o["name"], "context": o.get("context", ""), "kind": o.get("kind", ""),
+             "acts_on": o.get("acts_on", []),
+             "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", [])),
+             "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]
+    if aggregate_detail is not None:
+        payload["aggregate_detail"] = aggregate_detail
     if results is not None:
         payload["probe"] = {
             n: {"count": results[n]["count"], "coverage_pct": results[n]["coverage_pct"],
@@ -2294,6 +3860,12 @@ def _write_feature_map(path, meta, contexts, features, waves, cycles,
         for n, a in (avail or {}).items():
             payload["probe"].setdefault(n, {"available": False, "reason": a["reason"]})
         payload["reference_graph"] = gstats or {}
+    else:
+        # A rewrite from the edited proposal keeps the scan's own record of how the
+        # boundaries were found; the edit changed the boundaries, not the evidence.
+        for k in ("probe", "reference_graph"):
+            if (prior or {}).get(k) is not None:
+                payload[k] = prior[k]
     os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
     with open(path, "w", encoding="utf-8") as fh:
         json.dump(payload, fh, indent=2)
@@ -2321,6 +3893,9 @@ def cmd_apply(args):
     known_aggs = set(prior.get("aggregates") or [])
     for f in prior.get("features", []):
         known_aggs.update(a for a in [f.get("aggregate")] + list(f.get("aggregates") or []) if a)
+    # The operations the SCAN found — what an Operations cell may name. A map written
+    # before operations were recorded has none, and its cells are then not checked.
+    known_ops = {o["name"] for o in prior.get("operations") or []}
 
     text = open(md, encoding="utf-8").read()
     rows = _parse_md_tables(text, "Features")
@@ -2344,6 +3919,17 @@ def cmd_apply(args):
             problems.append(f"feature '{name}' names aggregate '{agg}', which the scan "
                             f"did not find — use one of: {', '.join(sorted(known_aggs)[:8])}…")
             continue
+        # The Operations cell (9th) is optional: a file written before it existed has no
+        # such column, and then the operations carry over from the previous map.
+        ops = None
+        if len(cells) > 8:
+            ops = [o.strip() for o in re.split(r"[,;]", cells[8])
+                   if o.strip() and o.strip() != "—"]
+            unknown = [o for o in ops if known_ops and o not in known_ops]
+            if unknown:
+                problems.append(f"feature '{name}' lists operation(s) {', '.join(unknown)}, "
+                                f"which the scan did not find")
+                continue
         base = prior_by_feature.get(name) or prior_by_agg.get(agg) or {}
         if name in seen:
             # Same feature twice is ONE feature over several aggregates: combine them, the
@@ -2358,6 +3944,9 @@ def cmd_apply(args):
             if agg not in prev["aggregates"]:
                 prev["aggregates"].append(agg)
             prev["depends_on"] += [d for d in deps if d not in prev["depends_on"]]
+            if ops is not None:
+                prev["operations"] = prev.get("operations", []) + [
+                    o for o in ops if o not in prev.get("operations", [])]
             continue
         # The aggregates are what THIS file says, never what the previous map said: a row
         # removed here has to leave the feature, and a base borrowed from another feature
@@ -2365,6 +3954,12 @@ def cmd_apply(args):
         entry = dict(base)
         entry.update({"feature": name, "context": ctx, "aggregate": agg,
                       "aggregates": [agg], "depends_on": deps})
+        if ops is not None:
+            entry["operations"] = ops
+        elif base is not prior_by_feature.get(name):
+            # Borrowed from another feature over the same aggregate: its operations are
+            # that feature's, not this one's.
+            entry["operations"] = []
         entry.setdefault("files", 0)
         entry.setdefault("churn", 0)
         entry.setdefault("seam", "")
@@ -2400,13 +3995,20 @@ def cmd_apply(args):
     meta = {"date": datetime.date.today().isoformat(), "root": root,
             "head": prior.get("commit", "-"), "strategy": prior.get("strategy", "edited")}
     _write_feature_map(mp, meta, contexts, features, waves, cycles,
-                       aggregates=sorted(known_aggs) or None)
+                       aggregates=sorted(known_aggs) or None,
+                       operations=prior.get("operations"),
+                       aggregate_detail=prior.get("aggregate_detail"), prior=prior)
 
     print(f"Applied {md} -> {mp}", file=sys.stderr)
     print(f"  {len(features)} feature(s) across {len(contexts)} context(s), "
           f"{len(waves)} wave(s){', CYCLES PRESENT' if cycles else ''}", file=sys.stderr)
+    listed = {o for f in features for o in f.get("operations") or []}
     print(json.dumps({
         "ok": "true", "feature_map": mp, "feature_count": len(features),
+        "aggregate_count": len(known_aggs), "operation_count": len(known_ops),
+        # Scanned operations no feature lists any more: an edit that dropped one from
+        # every Operations cell has left it with nowhere to be reversed into.
+        "orphaned_count": len(known_ops - listed),
         "context_count": len(contexts), "wave_count": len(waves),
         "cycle_count": len(cycles),
         "contexts_ordered": ", ".join(_ordered_contexts(contexts, features, waves)),
@@ -2440,7 +4042,7 @@ def cmd_context_state(args):
 
     contexts = m.get("contexts", [])
     ordered = [c["name"] for c in contexts]
-    want = (args.context or "").strip()
+    want, concerns = split_concerns(args.context)
     match = next((c for c in contexts if c["name"].lower() == want.lower()), None)
     if want and not match:
         print(json.dumps({"ok": "false", "map_present": "true", "context_known": "false",
@@ -2458,12 +4060,7 @@ def cmd_context_state(args):
     def key(n):
         return re.sub(r"[^a-z0-9]", "", (n or "").lower())
 
-    present = set()
-    agg_dir = os.path.join(bundle, "aggregates")
-    if os.path.isdir(agg_dir):
-        for fn in os.listdir(agg_dir):
-            if fn.endswith(".md") and fn != "index.md":
-                present.add(key(os.path.splitext(fn)[0]))
+    present = aggregate_concept_keys(bundle, key)
 
     # A context is onboarded when every AGGREGATE its features act on has a concept. The
     # bundle is the project's knowledge and a concept is an aggregate: a context whose map
@@ -2492,6 +4089,7 @@ def cmd_context_state(args):
     if not target:
         print(json.dumps({"ok": "false", "map_present": "true", "context_known": "true",
                           "all_onboarded": "true", "contexts_ordered": ", ".join(ordered),
+                          "onboarded_contexts": ", ".join(onboarded),
                           "error": "every bounded context in the map is already onboarded"}))
         return 1
 
@@ -2559,10 +4157,62 @@ def cmd_context_state(args):
         "context_count": len(contexts),
         "feature_map": mp,
         "strategy": m.get("strategy", ""),
+        "all_onboarded": "false",
+        # The operator's "concerns:" clause, split off the context name, and the one
+        # line the rule-set authors are handed — never the raw input.
+        "concerns": ", ".join(concerns),
+        "concerns_line": (f"The operator asked you to look for these concerns: "
+                          f"{', '.join(concerns)}." if concerns else
+                          "The operator listed no concerns to look for."),
     }))
     return 0
 
 
+# A `concerns:` clause after the context name: "Billing; concerns: auditing, concurrency".
+CONCERNS_CLAUSE_RE = re.compile(r"[;,]?\s*\bconcerns?\s*:\s*(.*)$", re.IGNORECASE | re.S)
+
+
+def split_concerns(text):
+    """(context, [concerns]) from onboard's input. The concerns clause is a search hint
+    for the rule-set authors; the context is what the map is searched for, and leaving
+    the clause on it made every such input an unknown context."""
+    s = (text or "").strip()
+    m = CONCERNS_CLAUSE_RE.search(s)
+    if not m:
+        return s.strip(" ;,"), []
+    concerns = [c.strip(" .") for c in re.split(r"[,;]", m.group(1)) if c.strip(" .")]
+    return s[:m.start()].strip(" ;,"), concerns
+
+
+def aggregate_concept_keys(bundle, key):
+    """The keys of every aggregate concept in the bundle, wherever it sits.
+
+    A concept is found the way every other reader finds one (aw-xref's resolver,
+    `concept`, `list-aggregates`): by walking the whole bundle for a `type` naming an
+    aggregate, keyed on its title and its file name. onboard writes concepts under
+    aggregates/, while implement and adopt create them at <slug>/<slug>.md; reading one
+    folder only reported a context whose concepts came the other way as never
+    onboarded. A file under aggregates/ with no readable type still counts, as it did
+    before types were read."""
+    present = set()
+    if not os.path.isdir(bundle):
+        return present
+    for dirpath, dirnames, filenames in os.walk(bundle):
+        dirnames[:] = [d for d in dirnames if not d.startswith(".")]
+        in_aggs = os.path.basename(dirpath) == "aggregates"
+        for fn in filenames:
+            if not fn.endswith(".md") or fn in ("index.md", "log.md"):
+                continue
+            fm = _read_frontmatter(os.path.join(dirpath, fn))
+            typ = fm.get("type") if isinstance(fm.get("type"), str) else ""
+            if "aggregate" in typ.lower() or (in_aggs and not typ):
+                present.add(key(os.path.splitext(fn)[0]))
+                title = fm.get("title")
+                if isinstance(title, str) and title.strip():
+                    present.add(key(title))
+    return present
+
+
 def cmd_scaffold_context(args):
     """Create the SPECS directories one bounded context's features will live in:
     specs/<Context>/<Feature>/ for every feature the map assigns to it.
@@ -2882,6 +4532,9 @@ def main():
                     help="The UI lane's declared source path. 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 "
+                                  "(default: <root>/.appweaver/inventory/feature-map.json, "
+                                  "when present).")
     ps.set_defaults(func=cmd_scan)
 
     pp = sub.add_parser("propose", help="Pass A+B+C: write the editable Feature / Bounded Context map.")