acumatica-cli 0.14.0__tar.gz → 0.15.1__tar.gz

{acumatica_cli-0.14.0 → acumatica_cli-0.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acumatica-cli
-Version: 0.14.0
+Version: 0.15.1
 Summary: Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data
 Author: Konstantin Borovik
 Author-email: Konstantin Borovik <kb@lab5.ca>
@@ -88,7 +88,7 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 ├── state [--out DIR] [--diff] [--assert-unchanged] [--dry-run] [FILES...]
 │                                     capture derived state into state/ (not seed)
 ├── extract [--out DIR] [--only NAME]... [--force] [--dry-run]
-│                                     dump live tenant state as seed YAML (inverse of apply)
+│                                     inverse of apply into config/{bootstrap,baseline,setup,master}/
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
 │
 └── config                            configuration ops
@@ -101,6 +101,7 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 A path like `config/` expands nested seed dirs in that fixed order.
 `run` without FILES defaults to `scenario/`.
 `state` without FILES defaults to `config/views/`; writes go to `state/` (`--out`).
+`extract` always writes under `config/{bootstrap,baseline,setup,master}/` (catalog-driven; never root SEED_DIRS).
 `acu --completion` emits a completion script for bash, zsh, or fish — source it from your shell profile.
 Run `acu <command> --help` for details on any command.
 
@@ -112,7 +113,7 @@ Your configuration lives in its own git repo.
 | Path | What it holds |
 | ---- | ------------- |
 | `config/bootstrap/` | virgin-tenant config: features, company, credit terms, `project.xml` |
-| `config/baseline/` | reference data: subaccounts, COA, ledger, UOMs, packaging |
+| `config/baseline/` | reference data: subaccounts, COA, ledger, UOMs |
 | `config/setup/` | one-time actions: financial year, master calendar, open periods |
 | `config/master/` | inventory/distribution masters (prefs, warehouse, items, parties) |
 | `scenario/` | lifecycle txns for `acu run`: once capital, then buy, build, sell |
@@ -128,7 +129,18 @@ The scaffolded `.gitignore` keeps `.env` out of git — store it encrypted (for
 Commit `target.yaml` with the seeds so every clone knows the verified ERP line and Default API generation.
 
 Seed YAML is state: `apply` upserts it, `diff` proves it.
-Scenario YAML is different — it describes transactions that flow forward.
+`acu extract` is the inverse of `apply`: GET live tenant rows into seed YAML under `config/{bootstrap,baseline,setup,master}/` (hard-cut). Packaged `seed_catalog.yaml` is the sole extract registry (entity, endpoint, keys, file, strip/include, filter-split); the demo entity map in [docs/demo-seed.md](docs/demo-seed.md) mirrors those catalog paths. Features synthesize to `config/bootstrap/features.yaml`. Existing files skip unless `--force`; empty live sets skip; row failures continue (exit 1 only if any row failed — drift stays with `diff`).
+
+```sh
+acu --tenant DEV extract --out . --force   # refresh config/** from live tenant
+git diff config/                           # review extract delta before commit
+acu --tenant DEV apply config/             # replay extracted seed
+acu --tenant DEV diff config/              # expect exit 0
+```
+
+**Migration (T115–T120 extract hard-cut):** extract no longer writes root `bootstrap/` / `baseline/` / `setup/` / `master/`. Paths are always `config/…`. There is no `--layout`. Move any root-layout extract output under `config/`, or re-extract into a modern data repo. Catalog rename: `extract_manifest.yaml` becomes `seed_catalog.yaml` (package data only; operators do not author it).
+
+Scenario YAML is different — it describes transactions that flow forward (not extractable seed).
 `acu run` executes each step in order (`put`, `action`, `wait`, `get`), captures server-assigned document numbers into `${var}` references for later steps, and checks `expect:` assertions as deltas against a pre-run snapshot, so additive scenarios re-run safely on a warm tenant.
 `once: true` scenarios declare a `present` inquire-absolute gate; when the probe already holds, the CLI prints `skip <path> (once: already present)` and runs neither steps nor expects (Owner Capital does not restack).
 

{acumatica_cli-0.14.0 → acumatica_cli-0.15.1}/README.md

@@ -70,7 +70,7 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 ├── state [--out DIR] [--diff] [--assert-unchanged] [--dry-run] [FILES...]
 │                                     capture derived state into state/ (not seed)
 ├── extract [--out DIR] [--only NAME]... [--force] [--dry-run]
-│                                     dump live tenant state as seed YAML (inverse of apply)
+│                                     inverse of apply into config/{bootstrap,baseline,setup,master}/
 ├── schema [--out DIR]                dump the endpoint's OpenAPI schema (swagger.json)
 │
 └── config                            configuration ops
@@ -83,6 +83,7 @@ acu [--tenant NAME] [--url URL] [--ssh USER@HOST] [--api-version V]
 A path like `config/` expands nested seed dirs in that fixed order.
 `run` without FILES defaults to `scenario/`.
 `state` without FILES defaults to `config/views/`; writes go to `state/` (`--out`).
+`extract` always writes under `config/{bootstrap,baseline,setup,master}/` (catalog-driven; never root SEED_DIRS).
 `acu --completion` emits a completion script for bash, zsh, or fish — source it from your shell profile.
 Run `acu <command> --help` for details on any command.
 
@@ -94,7 +95,7 @@ Your configuration lives in its own git repo.
 | Path | What it holds |
 | ---- | ------------- |
 | `config/bootstrap/` | virgin-tenant config: features, company, credit terms, `project.xml` |
-| `config/baseline/` | reference data: subaccounts, COA, ledger, UOMs, packaging |
+| `config/baseline/` | reference data: subaccounts, COA, ledger, UOMs |
 | `config/setup/` | one-time actions: financial year, master calendar, open periods |
 | `config/master/` | inventory/distribution masters (prefs, warehouse, items, parties) |
 | `scenario/` | lifecycle txns for `acu run`: once capital, then buy, build, sell |
@@ -110,7 +111,18 @@ The scaffolded `.gitignore` keeps `.env` out of git — store it encrypted (for
 Commit `target.yaml` with the seeds so every clone knows the verified ERP line and Default API generation.
 
 Seed YAML is state: `apply` upserts it, `diff` proves it.
-Scenario YAML is different — it describes transactions that flow forward.
+`acu extract` is the inverse of `apply`: GET live tenant rows into seed YAML under `config/{bootstrap,baseline,setup,master}/` (hard-cut). Packaged `seed_catalog.yaml` is the sole extract registry (entity, endpoint, keys, file, strip/include, filter-split); the demo entity map in [docs/demo-seed.md](docs/demo-seed.md) mirrors those catalog paths. Features synthesize to `config/bootstrap/features.yaml`. Existing files skip unless `--force`; empty live sets skip; row failures continue (exit 1 only if any row failed — drift stays with `diff`).
+
+```sh
+acu --tenant DEV extract --out . --force   # refresh config/** from live tenant
+git diff config/                           # review extract delta before commit
+acu --tenant DEV apply config/             # replay extracted seed
+acu --tenant DEV diff config/              # expect exit 0
+```
+
+**Migration (T115–T120 extract hard-cut):** extract no longer writes root `bootstrap/` / `baseline/` / `setup/` / `master/`. Paths are always `config/…`. There is no `--layout`. Move any root-layout extract output under `config/`, or re-extract into a modern data repo. Catalog rename: `extract_manifest.yaml` becomes `seed_catalog.yaml` (package data only; operators do not author it).
+
+Scenario YAML is different — it describes transactions that flow forward (not extractable seed).
 `acu run` executes each step in order (`put`, `action`, `wait`, `get`), captures server-assigned document numbers into `${var}` references for later steps, and checks `expect:` assertions as deltas against a pre-run snapshot, so additive scenarios re-run safely on a warm tenant.
 `once: true` scenarios declare a `present` inquire-absolute gate; when the probe already holds, the CLI prints `skip <path> (once: already present)` and runs neither steps nor expects (Owner Capital does not restack).
 

{acumatica_cli-0.14.0 → acumatica_cli-0.15.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "acumatica-cli"
-version = "0.14.0"
+version = "0.15.1"
 description = "Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data"
 authors = [{ name = "Konstantin Borovik", email = "kb@lab5.ca" }]
 license = "PolyForm-Noncommercial-1.0.0"

{acumatica_cli-0.14.0 → acumatica_cli-0.15.1}/src/acumatica_cli/cli.py

@@ -864,9 +864,9 @@ def run_cmd(inst: Instance, files: tuple[Path, ...], dry_run: bool) -> None:
 def _complete_only(
     _ctx: click.Context, _param: click.Parameter, incomplete: str
 ) -> list[str]:
-    """--only value completion: entity names off the packaged manifest.
+    """--only value completion: entity names off the packaged seed catalog.
 
-    Fires per keystroke, so it stays local-only (V23): the manifest is
+    Fires per keystroke, so it stays local-only (V23): the catalog is
     package data - never REST, never SSH, never a live instance.
     """
     return [
@@ -888,7 +888,7 @@ def _complete_only(
     "--only",
     multiple=True,
     shell_complete=_complete_only,
-    help="Limit to matching manifest rows (entity name or file stem); repeatable",
+    help="Limit to matching catalog rows (entity name or file stem); repeatable",
 )
 @click.option("--force", is_flag=True, help="Overwrite existing files")
 @click.option(
@@ -902,16 +902,17 @@ def extract_cmd(
     force: bool,
     dry_run: bool,
 ) -> None:
-    """Extract live tenant state into seed YAML files (the inverse of apply).
-
-    Manifest-driven (the packaged extract manifest carries the verified
-    entity set): each entity is read from the live tenant and written as a
-    seed file under bootstrap/ or baseline/ that apply and diff consume
-    unchanged. Existing files are skipped unless --force; an entity with
-    no live records produces no file. A failing row is reported and the
-    run continues to the next (a virgin tenant extracts whole). Exit 0
-    when every row wrote or skipped clean, 1 when any row failed - drift
-    detection stays with diff.
+    """Extract live tenant state into seed YAML under config/ (inverse of apply).
+
+    Catalog-driven (packaged ``seed_catalog.yaml`` is the verified entity
+    registry): each row is read from the live tenant and written under
+    ``config/{bootstrap,baseline,setup,master}/`` (hard-cut; never root
+    SEED_DIRS; no ``--layout``). Apply and diff consume those files
+    unchanged. Features synthesize to ``config/bootstrap/features.yaml``.
+    Existing files are skipped unless --force; an entity with no live
+    records produces no file. A failing row is reported and the run
+    continues (a virgin tenant extracts whole). Exit 0 when every row
+    wrote or skipped clean, 1 when any row failed - drift stays with diff.
     """
     assert_target_compatible(inst)
     with AcumaticaClient(inst) as client:

{acumatica_cli-0.14.0 → acumatica_cli-0.15.1}/src/acumatica_cli/config.py

@@ -61,10 +61,6 @@ INIT_TEMPLATES = (
         "config/baseline/60-ledger-company.yaml",
     ),
     ("config/baseline/90-uoms.yaml", "config/baseline/90-uoms.yaml"),
-    (
-        "config/baseline/91-company-packaging.yaml",
-        "config/baseline/91-company-packaging.yaml",
-    ),
     ("config/setup/10-financial-year.yaml", "config/setup/10-financial-year.yaml"),
     ("config/setup/20-master-calendar.yaml", "config/setup/20-master-calendar.yaml"),
     ("config/setup/30-open-periods.yaml", "config/setup/30-open-periods.yaml"),

{acumatica_cli-0.14.0 → acumatica_cli-0.15.1}/src/acumatica_cli/extract.py

@@ -1,22 +1,25 @@
 """Live tenant state to seed YAML: the inverse of apply.
 
-Driven by the packaged extract_manifest.yaml - per entity: the source
-endpoint, key fields, destination file, an optional record filter, and a
-strip deny-list or include allow-list shaping the extracted records.
-Emitted files parse via seed.load_baseline by construction (V20:
-bootstrap-entity rows must carry an endpoint) and re-extract
-byte-identically: records sort by key tuple,
-fields order key-first then alphabetical, None and empty-string values
-are elided.
+Driven by the packaged seed_catalog.yaml - per entity: the source
+endpoint, key fields, destination file, an optional record filter, a
+strip deny-list or include allow-list shaping the extracted records, and
+optional detail_keys for list fields (T60 load_baseline).
+Hard-cut emit under config/{bootstrap,baseline,setup,master}/ (V30/V34):
+no root SEED_DIRS paths, no --layout. Emitted files parse via
+seed.load_baseline by construction (V20: bootstrap-entity rows must
+carry an endpoint) and re-extract byte-identically: records sort by key
+tuple, fields order key-first then alphabetical, None and empty-string
+values are elided.
 
 setup/ action files are synthesized, not dumped: an action leaves no
-keyed record to extract, so each manifest setup row's kind-dispatched
+keyed record to extract, so each catalog setup row's kind-dispatched
 synthesizer reads the live state the action created (the done_when
-surface) and derives the action file back. bootstrap/features.yaml is
-the feature closure (V22/B15): the built-in six plus the union of the
-manifest features: gates over record-producing entities - a live
-FeaturesSet read is not available over the contract API (keyless
-BqlDelegate view), so the closure derives from what the tenant serves.
+surface) and derives the action file back.
+config/bootstrap/features.yaml is the feature closure (V22/B15): the
+built-in six plus the union of the catalog features: gates over
+record-producing entities - a live FeaturesSet read is not available
+over the contract API (keyless BqlDelegate view), so the closure
+derives from what the tenant serves.
 
 Extract reads live state and writes local files only - drift stays diff's
 job (exit 2 never happens here).
@@ -42,13 +45,14 @@ from .client import (
 from .models import Model, validation_summary
 from .seed import active_bootstrap, resolve_endpoint
 
-# The one non-manifest destination: the feature-closure file (V22/B15).
-FEATURES_FILE = "bootstrap/features.yaml"
+# The one non-catalog destination: the feature-closure file (V22/B15).
+FEATURES_FILE = "config/bootstrap/features.yaml"
 _SYMBOLIC_BOOTSTRAP = "bootstrap"
+_CATALOG_NAME = "seed_catalog.yaml"
 
 
 class EntitySpec(Model):
-    """One manifest row: how a live entity becomes a seed file."""
+    """One catalog row: how a live entity becomes a seed file."""
 
     entity: str
     keys: list[str] = Field(min_length=1)
@@ -61,6 +65,9 @@ class EntitySpec(Model):
     strip: list[str] = Field(default_factory=list)
     include: list[str] = Field(default_factory=list)
     features: list[str] = Field(default_factory=list)
+    # {ListField: RowKeyField} — emitted into seed so load_baseline accepts
+    # detail arrays (T60); required when include/strip keeps a list field.
+    detail_keys: dict[str, str] | None = None
 
     @model_validator(mode="after")
     def _strip_include_exclusive(self) -> EntitySpec:
@@ -87,7 +94,7 @@ class SetupSynth(Model):
 
 
 class Manifest(Model):
-    """The parsed extract manifest: entity rows plus setup synthesis rows."""
+    """The parsed seed catalog: entity rows plus setup synthesis rows."""
 
     entities: list[EntitySpec]
     setup: list[SetupSynth] = Field(default_factory=list)
@@ -117,16 +124,89 @@ class Manifest(Model):
 
 
 def load_manifest() -> Manifest:
-    """Parse and validate the packaged extract manifest."""
+    """Parse and validate the packaged seed catalog."""
     raw = yaml.safe_load(
-        (resources.files("acumatica_cli") / "extract_manifest.yaml").read_text(
-            encoding="utf-8"
-        )
+        (resources.files("acumatica_cli") / _CATALOG_NAME).read_text(encoding="utf-8")
     )
     try:
         return Manifest.model_validate(raw)
     except ValidationError as exc:
-        raise RuntimeError(f"extract_manifest.yaml: {validation_summary(exc)}") from exc
+        raise RuntimeError(f"{_CATALOG_NAME}: {validation_summary(exc)}") from exc
+
+
+# V34 exclusions: features synthesis, contract XML, observer views — not seed.
+_TEMPLATE_SEED_EXEMPT_NAMES = frozenset({"features.yaml", "project.xml"})
+_TEMPLATE_SEED_EXEMPT_PREFIXES = ("config/views/",)
+
+
+def packaged_template_seed_files() -> frozenset[str]:
+    """Packaged ``templates/config/**`` seed paths that V34 requires catalog rows for.
+
+    Paths are data-repo relative (``config/...``). Excludes features synthesis,
+    ``project.xml``, and ``config/views/`` observer defs.
+    """
+    root = resources.files("acumatica_cli").joinpath("templates", "config")
+    out: set[str] = set()
+
+    def walk(node: Any, prefix: str) -> None:
+        for child in node.iterdir():
+            name = child.name
+            rel = f"{prefix}{name}" if not prefix else f"{prefix}/{name}"
+            path = f"config/{rel}"
+            if child.is_dir():
+                walk(child, rel)
+                continue
+            if not name.endswith(".yaml"):
+                continue
+            if name in _TEMPLATE_SEED_EXEMPT_NAMES:
+                continue
+            if any(path.startswith(p) for p in _TEMPLATE_SEED_EXEMPT_PREFIXES):
+                continue
+            out.add(path)
+
+    walk(root, "")
+    return frozenset(out)
+
+
+def catalog_seed_files(manifest: Manifest | None = None) -> frozenset[str]:
+    """Catalog entity + setup emit paths (features synthesis is not a catalog row)."""
+    m = manifest if manifest is not None else load_manifest()
+    return frozenset(s.file for s in m.entities) | frozenset(s.file for s in m.setup)
+
+
+def catalog_completeness_gap(
+    manifest: Manifest | None = None,
+) -> tuple[frozenset[str], frozenset[str]]:
+    """V34 completeness: (missing from catalog, extra in catalog).
+
+    Empty pair means template seed set equals catalog file set.
+    """
+    templates = packaged_template_seed_files()
+    catalog = catalog_seed_files(manifest)
+    return templates - catalog, catalog - templates
+
+
+def _expand_for(spec: EntitySpec) -> list[str]:
+    """``$expand`` paths the catalog row needs for details + linked entities.
+
+    Detail arrays travel only under ``$expand=<ListField>`` (T60); linked
+    entities under ``$expand=<Field>`` / nested slash paths (T65). Without
+    expand the plain list GET returns top-level scalars alone — extract
+    would drop ``Locations`` / ``MainContact`` and re-apply on a virgin
+    tenant 422s (Vendor ``Country`` cannot be empty) or loses warehouse
+    bins. Detail fields come from ``detail_keys``; ``MainContact`` is the
+    packaged linked-entity include (Address nested for Country write-path).
+    """
+    paths: list[str] = []
+    if spec.detail_keys:
+        paths.extend(spec.detail_keys)
+    for field in spec.include or ():
+        if field in (spec.detail_keys or {}):
+            continue
+        if field == "MainContact":
+            paths.append("MainContact")
+            paths.append("MainContact/Address")
+    return sorted(set(paths))
 
 
 def _fetch(client: AcumaticaClient, spec: EntitySpec) -> list[dict[str, Any]]:
@@ -138,39 +218,110 @@ def _fetch(client: AcumaticaClient, spec: EntitySpec) -> list[dict[str, Any]]:
     reads each record through the key-URL single-record GET, which skips
     the optimizer (V4: read-back must survive delegate-view entities).
 
-    A manifest filter rides both list reads, so the two paths serve the
+    A catalog filter rides both list reads, so the two paths serve the
     same record set and the per-key walk only visits filtered keys.
+    ``$expand`` rides both paths when the catalog claims detail lists or
+    linked entities (T60/T65) — same class of expand as seed.diff.
     """
     endpoint = resolve_endpoint(spec.endpoint, api_version=client.instance.api_version)
-    narrowed = {"$filter": spec.filter} if spec.filter else {}
+    params: dict[str, str] = {}
+    if spec.filter:
+        params["$filter"] = spec.filter
+    expand = _expand_for(spec)
+    if expand:
+        params["$expand"] = ",".join(expand)
     try:
-        return client.get_list(spec.entity, params=narrowed or None, endpoint=endpoint)
+        return client.get_list(spec.entity, params=params or None, endpoint=endpoint)
     except RuntimeError as err:
         if OPTIMIZATION_500 not in str(err):
             raise
     key_rows = client.get_list(
         spec.entity,
-        params={"$select": ",".join(spec.keys)} | narrowed,
+        params={"$select": ",".join(spec.keys)}
+        | ({"$filter": spec.filter} if spec.filter else {}),
         endpoint=endpoint,
     )
+    expand_params = {"$expand": ",".join(expand)} if expand else None
     records: list[dict[str, Any]] = []
     for row in key_rows:
         values = unwrap(row)
         record = client.get_record(
-            spec.entity, [values[k] for k in spec.keys], endpoint
+            spec.entity,
+            [values[k] for k in spec.keys],
+            endpoint,
+            params=expand_params,
         )
         if record is not None:
             records.append(record)
     return records
 
 
+# Server-assigned / audit fields that must never enter seed (B11 class).
+# Applied recursively under linked entities and detail rows after expand
+# (T65/T119): MainContact.ContactID and AllowedCashAccounts.LastModified*
+# would otherwise permanent-red-diff after re-apply on a fresh tenant.
+_SERVER_DERIVED = frozenset(
+    {
+        "ContactID",
+        "CreatedDateTime",
+        "LastModifiedDateTime",
+        "NoteID",
+        "tstamp",
+    }
+)
+
+
+def _elide_server_derived(value: Any) -> Any:
+    """Drop server-derived keys recursively; elide empty nested containers."""
+    if isinstance(value, dict):
+        cleaned = {
+            k: _elide_server_derived(v)
+            for k, v in value.items()
+            if k not in _SERVER_DERIVED
+            and v is not None
+            and v != ""
+            and not (isinstance(v, (dict, list)) and not v)
+        }
+        return cleaned
+    if isinstance(value, list):
+        return [_elide_server_derived(v) for v in value]
+    return value
+
+
+def _kept_fields(spec: EntitySpec, record: dict[str, Any]) -> dict[str, Any]:
+    """Apply include/strip + nested server-derived elision to one unwrapped row."""
+    keep: dict[str, Any] = {}
+    for field, value in record.items():
+        if field in spec.keys:
+            keep[field] = value
+            continue
+        if field in _SERVER_DERIVED:
+            continue
+        if spec.include:
+            if field not in spec.include:
+                continue
+        elif field in spec.strip:
+            continue
+        # Nested ContactID / LastModifiedDateTime under expand (T65/T119).
+        cleaned = _elide_server_derived(value)
+        if cleaned is None or cleaned == "":
+            continue
+        if isinstance(cleaned, (dict, list)) and not cleaned:
+            continue
+        keep[field] = cleaned
+    ordered = {k: keep[k] for k in spec.keys if k in keep}
+    ordered |= {k: keep[k] for k in sorted(keep.keys() - set(spec.keys))}
+    return ordered
+
+
 def _shape(spec: EntitySpec, live: list[dict[str, Any]]) -> list[dict[str, Any]]:
     """Live records -> byte-stable seed records.
 
     Unwrap, apply the strip deny-list or include allow-list (key fields
-    always survive), elide None and empty-string values, order fields key
-    fields first (manifest order) then alphabetical, and sort records by
-    key tuple - server order never leaks into the emitted bytes.
+    always survive), elide None and empty-string values, drop nested
+    server-derived fields (B11), order fields key fields first (catalog
+    order) then alphabetical, and sort records by key tuple - server
+    order never leaks into the emitted bytes.
 
     Records duplicating the declared key tuple are a hard error (V25): an
     under-keyed file diffs as permanent false drift and apply collapses
@@ -185,19 +336,7 @@ def _shape(spec: EntitySpec, live: list[dict[str, Any]]) -> list[dict[str, Any]]
             raise RuntimeError(
                 f"{spec.entity}: live record missing key field(s) {', '.join(missing)}"
             )
-        keep = {
-            field: value
-            for field, value in record.items()
-            if field in spec.keys
-            or (
-                (field in spec.include if spec.include else field not in spec.strip)
-                and value is not None
-                and value != ""
-            )
-        }
-        ordered = {k: keep[k] for k in spec.keys}
-        ordered |= {k: keep[k] for k in sorted(keep.keys() - set(spec.keys))}
-        shaped.append(ordered)
+        shaped.append(_kept_fields(spec, record))
     shaped.sort(key=lambda r: tuple(str(r[k]) for k in spec.keys))
     idents = [tuple(str(r[k]) for k in spec.keys) for r in shaped]
     for prev, cur in itertools.pairwise(idents):
@@ -218,6 +357,8 @@ def _render(spec: EntitySpec, records: list[dict[str, Any]]) -> str:
     }
     if spec.endpoint is not None:
         doc["endpoint"] = spec.endpoint
+    if spec.detail_keys:
+        doc["detail_keys"] = dict(spec.detail_keys)
     doc["records"] = records
     return yaml.safe_dump(doc, sort_keys=False, default_flow_style=False)
 
@@ -289,7 +430,7 @@ def _synth_open_periods(client: AcumaticaClient) -> dict[str, Any] | None:
         return None
     years = _years(live)
     # OrganizationID = the extracted Company's AcctCD: the reference
-    # resolves inside the emitted set (V22 - bootstrap/company.yaml
+    # resolves inside the emitted set (V22 - config/bootstrap/company.yaml
     # creates the organization the action names)
     companies = client.get_list("Company", endpoint=ep)
     if not companies:
@@ -316,7 +457,7 @@ def _synth_open_periods(client: AcumaticaClient) -> dict[str, Any] | None:
 
 
 # kind -> (synthesizer, skip reason when the live state is absent);
-# SetupSynth validates manifest kinds against this registry
+# SetupSynth validates catalog kinds against this registry
 type Synthesizer = Callable[[AcumaticaClient], dict[str, Any] | None]
 SYNTHESIZERS: dict[str, tuple[Synthesizer, str]] = {
     "financial-year": (_synth_financial_year, "no financial year setup"),
@@ -326,7 +467,7 @@ SYNTHESIZERS: dict[str, tuple[Synthesizer, str]] = {
 
 
 def render_features(gates: Iterable[str]) -> str:
-    """The feature-closure bootstrap/features.yaml: built-in six + gates.
+    """The feature-closure config/bootstrap/features.yaml: built-in six + gates.
 
     Deterministic order (byte-stable re-extract): the built-in six in
     their bootstrap.DEFAULT_FEATURES spelling, then the extra gates
@@ -368,6 +509,11 @@ class _Extraction:
         """The --only filter: row name (entity or kind) or file stem."""
         return not self.only or name in self.only or Path(file).stem in self.only
 
+    def _progress(self, target: Path, name: str) -> None:
+        """Per-row progress banner matching apply/diff (V9 / I.cmd extract)."""
+        inst = self.client.instance
+        output.data(f"{target} -> {inst.tenant} on {inst.base_url} ({name})")
+
     def _skip(self, target: Path, reason: str) -> None:
         """Report one clean per-file skip and tally it."""
         output.data(f"skip {target} ({reason})")
@@ -386,7 +532,7 @@ class _Extraction:
         A PXSetupNotEnteredException 500 is the virgin-tenant empty-state
         class — the screen has no data to extract, same answer as 200 [] —
         so it skips clean. Anything else is a reported row failure; the
-        run continues to the next manifest row either way.
+        run continues to the next catalog row either way.
         """
         if SETUP_NOT_ENTERED_500 in str(err):
             self._skip(target, "screen setup not entered")
@@ -412,6 +558,8 @@ class _Extraction:
             if not self._selected(spec.entity, spec.file):
                 continue
             target = self.out_dir / spec.file
+            # Banner before any outcome (write/skip/would write) — apply shape
+            self._progress(target, spec.entity)
             if self._skip_existing(target):
                 continue
             # Hybrid contract (T69/T81): a bootstrap-endpoint row for an
@@ -443,6 +591,7 @@ class _Extraction:
             if not self._selected(synth.kind, synth.file):
                 continue
             target = self.out_dir / synth.file
+            self._progress(target, synth.kind)
             if self._skip_existing(target):
                 continue
             synthesize, skip_reason = SYNTHESIZERS[synth.kind]
@@ -473,6 +622,7 @@ class _Extraction:
         if not self._selected("features", FEATURES_FILE):
             return
         target = self.out_dir / FEATURES_FILE
+        self._progress(target, "features")
         if self._skip_existing(target):
             return
         gates = [
@@ -492,11 +642,12 @@ def run(
     force: bool = False,
     dry_run: bool = False,
 ) -> int:
-    """Extract the manifest file set plus the feature closure under out_dir.
+    """Extract the catalog file set plus the feature closure under out_dir.
 
-    Per file: skip when it exists (--force overwrites), skip when the
-    tenant has no records, report-only under --dry-run. `only` filters
-    rows by entity name, synthesizer kind, or file stem.
+    Paths hard-cut under config/ SEED_DIRS (V30). Per file: skip when it
+    exists (--force overwrites), skip when the tenant has no records,
+    report-only under --dry-run. `only` filters rows by entity name,
+    synthesizer kind, or file stem.
 
     A failing row is reported and the run continues (V24) - the return
     value is the failed-row count, 0 when every row wrote or skipped clean