CLI Reference
=============

Top-Level Command
-----------------

.. code-block:: text

   python -m femic [OPTIONS] COMMAND [ARGS]...

Options
-------

- ``--version``: Show version and exit.
- ``--debug``: Enable rich tracebacks.
- ``--help``: Show help and exit.

Commands
--------

- ``run``
- ``prep``
- ``vdyp``
- ``tsa``
- ``tipsy``
- ``fansier``
- ``data``
- ``doc``
- ``pipelines``
- ``tsr``
- ``export``
- ``patchworks``
- ``instance``

Run
---

.. code-block:: text

   python -m femic run [OPTIONS]

- ``--data-root PATH`` (default: ``data``)
- ``--output-root PATH`` (default: ``outputs``)
- ``--tsa TEXT`` (repeatable; legacy FMU/code selector name)
- ``--resume``
- ``--dry-run``
- ``--verbose`` / ``-v``
- ``--skip-checks``
- ``--debug-rows INTEGER``
- ``--run-id TEXT``
- ``--log-dir PATH`` (default: ``runtime/logs``)
- ``--run-config PATH`` (YAML/JSON run profile)
- ``--instance-root PATH`` (optional; defaults to CWD or ``FEMIC_INSTANCE_ROOT`` env)

Document Ingestion
------------------

.. code-block:: text

   python -m femic doc [OPTIONS] COMMAND [ARGS]...

Subcommands

- ``figures``: optional figure-recovery workflow helpers.

``doc figures`` subcommands

- ``preflight``: report whether optional ``figrecover`` dependencies are
  importable.
- ``prepare-corpus``: initialize an ignored document-ingestion corpus, render
  selected PDFs through ``figrecover``, write ``source_manifest.yaml``, and
  optionally summarize a figrecover figure manifest.
- ``register-table``: register a recovered CSV/JSON table with FEMIC
  provenance, checksums, calibration metadata, review status, and downstream
  use classification.

Common examples:

.. code-block:: bash

   python -m femic doc figures preflight

   python -m femic doc figures prepare-corpus tfl6-mp11-pilot \
     --pdf /path/to/TFL6_MP_11_202606_w_Appendices_Web-compressed.pdf \
     --pages 82-86,91,98-100,103,116,123 \
     --dpi 150 \
     --output-root runtime/document_ingestion/tfl6-mp11-pilot

   python -m femic doc figures register-table tfl6-mp11-pilot recovered.csv \
     --document-title "TFL 6 Management Plan 11" \
     --page 82 \
     --figure-id "Figure 2" \
     --series-name "base case" \
     --visual-selection-rule "blue harvest-flow line" \
     --calibration-spec calibration/figure-2.json \
     --extraction-method deterministic_line_mask \
     --source-url https://www.westernforest.com/wp-content/uploads/2026/06/TFL6_MP_11_202606_w_Appendices_Web-compressed.pdf \
     --review-status accepted_for_comparison \
     --downstream-use comparison_evidence \
     --reviewer "Reviewer Name"

See :doc:`../guides/document-figure-recovery` for the workflow and review
gates.

Pipelines
---------

.. code-block:: text

   python -m femic pipelines [OPTIONS] COMMAND [ARGS]...

Subcommands

- ``run``: ``python -m femic pipelines run --runbook PATH [--instance-root PATH]``

``pipelines run`` resolves one machine-readable runbook, loads the built-in +
optional user + optional instance-local named-pipeline registries, and runs
the first proof-oriented named pipeline surface.
Validation contracts are extension-owned: FEMIC core dispatches contract kinds
through installed ``femic.named_pipeline_contracts`` handlers rather than
hardcoding example-instance semantics. For example, TSA29's
``tsa29_locked_chain_strict`` contract is available only when the TSA29
instance package is installed in the active environment.

Current proof-runner scope:

- primary product pipeline id: ``tsr.thlb_strict``
- legacy scaffold pipeline id: ``tsr.thlb_reviewed``
- seams: ``scratch``, ``aflb``, ``aflb_yield_ready``, and ``lhlb_curve_ready``
- delegation into the existing strict reconstructed TSR THLB lane rather than a new
  execution engine

``pipelines run`` options

- ``--runbook PATH`` (required; typically under ``runbooks/pipelines/``)
- ``--instance-root PATH`` (optional; defaults to CWD or ``FEMIC_INSTANCE_ROOT`` env)

Example proof-runner invocation

.. code-block:: text

   python -m femic pipelines run ^
     --runbook runbooks/pipelines/tsa29.tsr.thlb_strict.aflb_yield_ready.yaml ^
     --instance-root external/femic-tsa29-instance

Prep
----

.. code-block:: text

   python -m femic prep [OPTIONS] COMMAND [ARGS]...

Subcommands

- ``run``: ``python -m femic prep run [OPTIONS]``
- ``arbutus-auth-status``: ``python -m femic prep arbutus-auth-status [OPTIONS]``
- ``arbutus-auth-init``: ``python -m femic prep arbutus-auth-init [OPTIONS]``
- ``validate-case``: ``python -m femic prep validate-case [OPTIONS]``
- ``geospatial-preflight``: ``python -m femic prep geospatial-preflight [OPTIONS]``
- ``glb-build``: ``python -m femic prep glb-build [OPTIONS]``
- ``arcgis-review-project``: ``python -m femic prep arcgis-review-project [OPTIONS]``

``prep run`` options

- ``--data-root PATH`` (default: ``data``)
- ``--output-root PATH`` (default: ``outputs``)
- ``--tsa TEXT`` (repeatable; legacy FMU/code selector name)
- ``--resume``
- ``--dry-run``
- ``--verbose`` / ``-v``

``prep arbutus-auth-status`` options

- ``--profile TEXT`` (optional named Arbutus profile)
- ``--dataset PATH`` (optional dataset path for ``git annex enableremote`` validation)
- ``--remote TEXT`` (optional remote override)

Use ``prep arbutus-auth-status`` as the non-mutating Windows auth/profile/marker
probe. It reports:

- whether the user-local auth files exist;
- whether the current shell is loaded with the shared Arbutus env values;
- whether the selected bucket passes ``HeadBucket``; and
- whether the saved non-secret known-working marker is current or stale.

When ``--dataset`` is supplied, the command can also validate
``git annex enableremote <remote>`` for that dataset.

``prep arbutus-auth-init`` options

- ``--profile TEXT`` (optional named profile to create or refresh)
- ``--bucket TEXT`` (optional bucket name for the selected profile)
- ``--dataset PATH`` (optional dataset path for ``git annex enableremote`` validation)
- ``--remote TEXT`` (default: ``arbutus-s3``)
- ``--force-refresh-loaders``

Use ``prep arbutus-auth-init`` to scaffold and validate the Windows local
workflow under ``%USERPROFILE%\.config\femic``. The command:

- creates missing local auth/profile/status files;
- prompts interactively for missing shared values when the session allows it;
- validates ``HeadBucket`` for the selected profile; and
- writes a non-secret known-working marker only after validation succeeds.

``prep validate-case`` options

- ``--run-config PATH`` (default: ``config/run_profile.case_template.yaml``)
- ``--tipsy-config-dir PATH`` (default: ``config/tipsy``)
- ``--strict-warnings``
- ``--instance-root PATH``

On Windows, ``prep validate-case`` now also performs the low-noise
annex/Arbutus checks needed for FEMIC's Arbutus-backed public-data workflow
when that mirror is in play. It can fail fast on:

- unusable ``git-annex`` / DataLad runtime;
- quoted credential values in ``%USERPROFILE%\.config\femic\arbutus.env``;
- missing loaded Arbutus auth vars when a local Arbutus env-file workflow is
  already in use; and
- failed visibility probes for the known public-data Arbutus bucket; and
- unreadable canonical ``data/bc/tsa/FADM_TSA.gdb`` inputs that are more likely
  annex materialization/unlock problems than generic Windows GDAL ghosts.

``prep validate-case`` is no longer the primary auth/bootstrap workflow.
Use:

- ``prep arbutus-auth-status`` for current-vs-stale Windows auth state; and
- ``prep arbutus-auth-init`` to scaffold or refresh the local workflow.

For the canonical Windows auth/bootstrap runbook and publication sequence, see
``docs/guides/windows-arbutus-auth-workflow.rst`` and
``docs/guides/public-data-mirror-runbook.rst``.

``prep geospatial-preflight`` remains the generic Fiona/GDAL/shapefile smoke
check. On Windows, use ``prep validate-case`` to prove that the active FEMIC
case can actually read the annex-backed canonical TSA/FileGDB inputs.

``prep geospatial-preflight`` options

- ``--strict-warnings``
- ``--skip-shapefile-smoke``

``prep glb-build`` options

- ``--tsa TEXT`` (required; TSA code, ``tsa_<code>``, or TSA name)
- ``--instance-root PATH``
- ``--output-dir PATH`` (optional explicit output directory for the GLB bundle)
- ``--source-zip-path PATH`` (optional explicit raw VRI zip override)
- ``--boundary-path PATH`` (optional explicit TSA boundary layer override)
- ``--force-rebuild-glb`` (ignore an existing local stashed GLB and rebuild)
- ``--no-stash-public-data-glb`` (disable the default local public-data stash)
- ``--force-update-public-data-glb`` (overwrite an existing local stashed GLB)

``prep glb-build`` is the clean raw-source GLB workflow for one named TSA. It
uses the canonical 2024 provincial VRI zip by default, clips it with the
active TSA boundary row, writes a clipped GLB artifact plus JSON/Markdown
summary, and reports the clipped stand geometry area directly. Checkpoints are
not accepted as the source baseline for this command.

By default, successful runs also stash a reusable zipped GLB snapshot plus
summary JSON into the local ``external/femic-public-data`` DataLad repo under a
deterministic TSA/VRI path. That stash is local only in v1:

- no auto-commit;
- no auto-push; and
- no Arbutus/GitHub publication.

Use ``--no-stash-public-data-glb`` to disable the default stash or
``--force-update-public-data-glb`` to replace an existing stored snapshot.
When a local stashed GLB already exists, ``prep glb-build`` now reuses that
confirmed-valid snapshot by default instead of rebuilding from raw source; use
``--force-rebuild-glb`` to bypass the stash and run the raw clip again.

``prep arcgis-review-project`` options

- ``--instance-root PATH``
- ``--output-dir PATH`` (optional; defaults to ``workbench/arcgis_review`` under the instance root)
- ``--project-name TEXT`` (optional explicit `.aprx` name stem)

``prep arcgis-review-project`` is a Windows/ArcGIS Pro inspection aid, not a
new FEMIC GIS-processing backend. It discovers instance-local vector layers
already on disk (for example downloaded BCDC GeoPackages plus local shapefile
context layers such as stands or fragments), emits a ready-to-open `.aprx`,
writes a manifest JSON, and keeps all loaded layers off by default at launch.
When GeoPackage layers need ArcGIS-friendly staging, the emitted bundle also
includes helper shapefile copies under the chosen output directory.

Use it when a human needs to inspect an instance visually in ArcGIS Pro
without hand-loading dozens of layers. It depends on a local ArcGIS Pro
installation and the same path-resolved ``propy.bat`` / ArcGIS Pro Python seam
already used by the Windows SiteProd fallback.

VDYP
----

.. code-block:: text

   python -m femic vdyp [OPTIONS] COMMAND [ARGS]...

Subcommands

- ``run``: ``python -m femic vdyp run [OPTIONS]``
- ``report``: ``python -m femic vdyp report [OPTIONS]``

``vdyp run`` options

- ``--data-root PATH`` (default: ``data``)
- ``--output-root PATH`` (default: ``outputs``)
- ``--tsa TEXT`` (repeatable; legacy FMU/code selector name)
- ``--resume``
- ``--dry-run``
- ``--verbose`` / ``-v``

``vdyp report`` options

- ``--curve-log PATH`` (default: ``vdyp_io/logs/vdyp_curve_events.jsonl``)
- ``--run-log PATH`` (default: ``vdyp_io/logs/vdyp_runs.jsonl``)
- ``--expected-first-age FLOAT`` (default: ``1.0``)
- ``--expected-first-volume FLOAT`` (default: ``1e-06``)
- ``--tolerance FLOAT`` (default: ``1e-12``)
- ``--mismatch-limit INTEGER`` (default: ``10``)
- ``--max-curve-warnings INTEGER``
- ``--max-first-point-mismatches INTEGER``
- ``--max-curve-parse-errors INTEGER``
- ``--max-run-parse-errors INTEGER``
- ``--min-curve-events INTEGER``
- ``--min-run-events INTEGER``

TSA
---

.. code-block:: text

   python -m femic tsa [OPTIONS] COMMAND [ARGS]...

Compatibility note:

- ``tsa`` remains the command-group name for historical/runtime compatibility.
  In generic FEMIC usage, read it as "FMU/code-targeted legacy pipeline
  commands" unless the case is literally a BC Timber Supply Area.

Subcommands

- ``run``: ``python -m femic tsa run [OPTIONS]``
- ``post-tipsy``: ``python -m femic tsa post-tipsy [OPTIONS]``
- ``btc-post-tipsy``: ``python -m femic tsa btc-post-tipsy [OPTIONS]``

``tsa run`` options

- ``--data-root PATH`` (default: ``data``)
- ``--output-root PATH`` (default: ``outputs``)
- ``--tsa TEXT`` (repeatable; selected FMU/code values)
- ``--resume``
- ``--dry-run``
- ``--verbose`` / ``-v``

``tsa post-tipsy`` options

- ``--tsa TEXT`` (repeatable, required; selected FMU/code values)
- ``--verbose`` / ``-v``
- ``--run-id TEXT``
- ``--log-dir PATH`` (default: ``runtime/logs``)
- ``--run-config PATH`` (optional; load FMU/code selection and managed-curve mode defaults)
- ``--yield-assumptions-path PATH`` (optional instance-local post-TIPSY yield assumptions YAML)
- ``--instance-root PATH``

``tsa btc-post-tipsy`` options

- ``--tsa TEXT`` (repeatable, required; selected FMU/code values)
- ``--verbose`` / ``-v``
- ``--run-id TEXT``
- ``--log-dir PATH`` (default: ``runtime/logs``)
- ``--run-config PATH`` (optional; load FMU/code selection and managed-curve mode defaults)
- ``--yield-assumptions-path PATH`` (optional instance-local post-TIPSY yield assumptions YAML)
- ``--btc-exe PATH`` (optional explicit ``TIPSYbtc.exe`` override)
- ``--scratch-dir PATH`` (optional scratch root for copied BTC installs and staged run files)
- ``--report-preset TEXT`` (default: ``tsr-unattended-default``)
- ``--instance-root PATH``

TIPSY
-----

.. code-block:: text

   python -m femic tipsy [OPTIONS] COMMAND [ARGS]...

Use this command group when you want direct control of the BTC/TIPSY runtime
boundary rather than the broader Stage 01a/01b orchestration. The current
operator-facing default is the unattended BTC `/TSR` seam through the live
user-overlay ``TimberSupply.rpt`` path.

Data
----

.. code-block:: text

   python -m femic data [OPTIONS] COMMAND [ARGS]...

Subcommands

- ``bcdc-resolve``: ``python -m femic data bcdc-resolve [OPTIONS] [QUERY]...``
- ``bcdc-fetch``: ``python -m femic data bcdc-fetch [OPTIONS] [QUERY]...``
- ``bcdc-order``: ``python -m femic data bcdc-order [OPTIONS] [QUERY]...``
- ``bcdc-order-followup``: ``python -m femic data bcdc-order-followup [OPTIONS] ORDER_MANIFEST``

``data bcdc-resolve`` options

- ``QUERY`` argument (repeatable; BC Data Catalogue layer names or keywords)
- ``--query-file PATH`` (optional one-query-per-line text file; blank lines and ``#`` comments ignored)
- ``--summary-csv PATH`` (optional one-row-per-query CSV review export)
- ``--manifest-path PATH`` (optional JSON manifest output path)
- ``--download-direct / --no-download-direct`` (opt-in direct-downloads from the top-ranked package only)
- ``--download-root PATH`` (optional destination root for direct downloads)
- ``--limit INTEGER`` (default: ``5``)
- ``--instance-root PATH`` (optional instance root used to resolve default output paths)
- ``--plan-only`` (preview deduplicated direct-download activity without executing it)
- ``--allow-bulk / --no-allow-bulk`` (explicitly allow larger direct-download bursts that exceed FEMIC's default public-service threshold)

For working Windows examples, including quoted multi-word queries and
``--query-file`` batch usage, see
``docs/guides/bc-data-catalogue-discovery.rst``.

``data bcdc-fetch`` options

- ``QUERY`` argument (repeatable; BC Data Catalogue layer names or keywords)
- ``--query-file PATH`` (optional one-query-per-line text file; blank lines and ``#`` comments ignored)
- ``--manifest-path PATH`` (optional JSON manifest output path)
- ``--download-root PATH`` (optional destination root; defaults under ``data/downloads/bcdc``)
- ``--limit INTEGER`` (default: ``5``)
- ``--instance-root PATH`` (optional instance root used to resolve default output paths)
- ``--bbox minx,miny,maxx,maxy`` (required unless ``--geomark`` is supplied; interpreted in ``EPSG:3005``)
- ``--geomark TEXT`` (required unless ``--bbox`` is supplied; accepts a full Geomark URL or bare Geomark ID)
- ``--output-format [gpkg|geojson]`` (default: ``gpkg``)
- ``--plan-only`` (preview deduplicated WFS activity without executing it)
- ``--allow-bulk / --no-allow-bulk`` (explicitly allow larger WFS bursts that exceed FEMIC's default public-service threshold)

``data bcdc-fetch`` is the first automated geographic acquisition lane built on
top of the WFS service hints from ``bcdc-resolve``. Use it when the resolved
dataset exposes ``wfs_queryable`` and
``suggested_fetch_strategy=wfs_getfeature_bbox``. If a dataset exposes only
direct-download resources, use ``femic data bcdc-resolve --download-direct``
instead.

``data bcdc-order`` options

- ``QUERY`` argument (repeatable; BC Data Catalogue layer names or keywords)
- ``--query-file PATH`` (optional one-query-per-line text file; blank lines and ``#`` comments ignored)
- ``--manifest-path PATH`` (optional JSON manifest output path)
- ``--limit INTEGER`` (default: ``5``)
- ``--instance-root PATH`` (optional instance root used to resolve relative manifest paths)
- ``--bbox minx,miny,maxx,maxy`` (required unless ``--geomark`` is supplied; interpreted in ``EPSG:3005``)
- ``--geomark TEXT`` (required unless ``--bbox`` is supplied; accepts a full Geomark URL or bare Geomark ID)
- ``--output-format [fgdb|gpkg|geojson|shp]`` (default: ``fgdb``)
- ``--email TEXT`` (optional DWDS notification email; defaults to ``FEMIC_BCDC_DWDS_EMAIL`` when set, otherwise ``git config user.email``)
- ``--clip / --no-clip`` (default: ``--clip``)
- ``--plan-only`` (preview deduplicated DWDS order activity without executing it)
- ``--allow-bulk / --no-allow-bulk`` (explicitly allow larger DWDS order bursts that exceed FEMIC's default public-service threshold)

``data bcdc-order`` is the heavier BCGW fallback lane. Use it when a dataset
needs a DWDS order for richer outputs such as File Geodatabase or GeoPackage
instead of a simple direct file download or a WFS-backed subset fetch. The
current public DWDS seam can submit orders successfully, but the public
``/order/{id}`` status lookup may still report successful live orders as
missing, so FEMIC records that caveat in the manifest instead of pretending
the full end-to-end download path is already solved.

``data bcdc-order-followup`` options

- ``ORDER_MANIFEST`` argument (required; manifest written by ``data bcdc-order``)
- ``--manifest-path PATH`` (optional output manifest path; defaults to updating the input manifest in place)
- ``--download-root PATH`` (optional destination root for downloaded DWDS artifacts)
- ``--instance-root PATH`` (optional instance root used to resolve relative output paths)
- ``--download / --no-download`` (default: ``--download``; materialize the artifact when a follow-up probe exposes a download URL)
- ``--poll-status / --no-poll-status`` (default: ``--poll-status``; re-probe the public DWDS order seam before materialization)

``data bcdc-order-followup`` is FEMIC's recovery lane for orders that were
submitted successfully but did not immediately expose a downloadable artifact.
It reloads an existing DWDS manifest, retries the public status seam, and
downloads the artifact into the selected root if DWDS finally returns a
download URL. When the public ``/order/{id}`` seam still returns the known
false negative, FEMIC now also uses the saved ``order_guid`` to try the DWDS
``pickupByGUID`` launcher page and extract the real
``distribution.data.gov.bc.ca`` package URL.

All three BCDC acquisition commands now apply soft good-citizen guardrails:
duplicate queries are collapsed automatically, ``--plan-only`` previews the
deduplicated public-service activity, and larger batch runs require an
explicit ``--allow-bulk`` acknowledgement before FEMIC will execute them.

Subcommands

- ``validate``: ``python -m femic tipsy validate [OPTIONS]``
- ``write-btc-report-template``: ``python -m femic tipsy write-btc-report-template [OPTIONS]``
- ``run-btc``: ``python -m femic tipsy run-btc [OPTIONS]``

``tipsy validate`` options

- ``--config-dir PATH`` (default: ``config/tipsy``)
- ``--tsa TEXT`` (repeatable; selected FMU/code values)
- ``--instance-root PATH``

``tipsy write-btc-report-template`` options

- ``--preset TEXT`` (required; built-in report-template preset)
- ``OUTPUT`` argument (required)
- ``--source-rpt PATH`` (optional existing ``.rpt`` template to clone/adapt)
- ``--column TEXT`` (repeatable additional BTC output column token)
- ``--instance-root PATH``

``tipsy run-btc`` options

- ``INPUT_CSV`` argument (required)
- ``--output-csv PATH`` (optional; defaults beside input)
- ``--error-csv PATH`` (optional; defaults beside input)
- ``--btc-exe PATH`` (optional explicit ``TIPSYbtc.exe`` override)
- ``--mode TEXT`` (default: ``TSR``)
- ``--report-template PATH`` (optional vetted ``TimberSupply.rpt`` override)
- ``--report-preset TEXT`` (default: ``tsr-unattended-default`` for ``TSR``)
- ``--copy-install`` / ``--use-installed-btc``
- ``--scratch-dir PATH`` (optional writable scratch directory; defaults under ``tipsy_io/scratch``)
- ``--log-dir PATH`` (default: ``tipsy_io/logs``)
- ``--run-id TEXT``
- ``--instance-root PATH``

Operational note:

- runtime artifacts now default under ``tipsy_io/logs`` and
  ``tipsy_io/scratch`` so BTC supervision is visually separate from the VDYP
  runtime namespace.

FAN$IER
-------

.. code-block:: text

   python -m femic fansier [OPTIONS] COMMAND [ARGS]...

Use this command group when you want FEMIC to drive the tracked Windows
FAN$IER batch-extraction seam and optionally normalize the resulting long-report
text files into FEMIC-owned tables.

Subcommands

- ``run-batch``: ``python -m femic fansier run-batch [OPTIONS] RGM_PATH``
- ``parse-batch-output``:
  ``python -m femic fansier parse-batch-output [OPTIONS] REPORT_DIR``
- ``run-and-parse``:
  ``python -m femic fansier run-and-parse [OPTIONS] RGM_PATH``

``fansier run-batch`` options

- ``RGM_PATH`` argument (required)
- ``--out-dir PATH`` (default: ``tipsy_io/logs/fansier_batch``)
- ``--log-dir PATH`` (default: ``tipsy_io/logs``)
- ``--run-id TEXT`` (default: ``fansier_batch``)
- ``--fansier-exe PATH`` (default: installed ``Fansier.exe`` path)
- ``--discount-name TEXT`` (default: ``FEMIC Raw 0%``)
- ``--discount-dis-path PATH`` (optional; load `.dis` before selection)
- ``--report-type TEXT`` (default: ``txt``)
- ``--long-report`` / ``--short-report`` (default: short)
- ``--product-cols`` / ``--no-product-cols``
- ``--activity-cols`` / ``--no-activity-cols`` (default: off)
- ``--select-all-products``
- ``--select-all-ages``
- ``--product-name TEXT`` (used when not selecting all products)
- ``--age-name TEXT`` (used when not selecting all ages)

``fansier parse-batch-output`` options

- ``REPORT_DIR`` argument (required directory of FAN$IER ``.txt`` outputs)
- ``--out-dir PATH`` (default: ``tipsy_io/logs/fansier_parsed``)
- ``--report-glob TEXT`` (default: ``*.txt``)

``fansier run-and-parse`` options

- ``RGM_PATH`` argument (required)
- ``--out-dir PATH`` (default: ``tipsy_io/logs/fansier_batch``)
- ``--parsed-out-dir PATH`` (default: ``tipsy_io/logs/fansier_parsed``)
- ``--log-dir PATH`` (default: ``tipsy_io/logs``)
- ``--run-id TEXT`` (default: ``fansier_batch``)
- ``--fansier-exe PATH`` (default: installed ``Fansier.exe`` path)
- ``--discount-name TEXT`` (default: ``FEMIC Raw 0%``)
- ``--discount-dis-path PATH`` (optional; load `.dis` before selection)
- ``--report-type TEXT`` (currently must be ``txt`` for parsing)
- ``--long-report`` / ``--short-report`` (default: long)
- ``--product-cols`` / ``--no-product-cols``
- ``--activity-cols`` / ``--no-activity-cols`` (default: off)
- ``--select-all-products`` / ``--single-product`` (default: all)
- ``--select-all-ages`` / ``--single-age`` (default: all)
- ``--product-name TEXT`` (used when broad product selection is off)
- ``--age-name TEXT`` (used when broad age selection is off)

Operational notes:

- the parsing seam currently expects ``txt`` reports;
- the practical machine-ingest default is `0%` discount posture with product
  columns on and activity columns off.

Data
----

.. code-block:: text

   python -m femic data [OPTIONS] COMMAND [ARGS]...

Use this command group when you want FEMIC to help resolve BC Data Catalogue
records from explicit layer names or keywords copied from TSR source-data
lists.

Subcommands

- ``bcdc-resolve``: ``python -m femic data bcdc-resolve [OPTIONS] QUERY...``

``data bcdc-resolve`` options

- ``QUERY`` argument (repeatable; one or more layer names or keywords)
- ``--manifest-path PATH`` (optional JSON candidate-manifest output path)
- ``--download-direct / --no-download-direct`` (default: ``--no-download-direct``)
- ``--download-root PATH`` (optional; defaults under ``data/downloads/bcdc``
  for ``--instance-root`` workflows, otherwise ``./downloads/bcdc``)
- ``--limit INTEGER`` (default: ``5``)
- ``--instance-root PATH``

Operational notes:

- v1 resolves and classifies catalogue resources first; it does **not**
  automate indirect/custom-download BCGW flows;
- service-backed OpenMaps resources can now surface machine-readable WFS hints
  such as ``wfs_queryable``, ``wfs_typename``, and
  ``suggested_fetch_strategy`` in the manifest/summary outputs;
- ``--download-direct`` only downloads stable direct-access data resources from
  the top-ranked package match; and
- the intended promotion path is candidate manifest first, then manual review,
  then optional updates to ``metadata/required_datasets.yaml``.

TSR
---

.. code-block:: text

   python -m femic tsr [OPTIONS] COMMAND [ARGS]...

Subcommands

- ``index``: ``python -m femic tsr index [OPTIONS]``
- ``fetch``: ``python -m femic tsr fetch [OPTIONS]``
- ``extract``: ``python -m femic tsr extract [OPTIONS]``
- ``facts-report``: ``python -m femic tsr facts-report [OPTIONS]``
- ``recipe-init``: ``python -m femic tsr recipe-init [OPTIONS]``
- ``source-layers-build``: ``python -m femic tsr source-layers-build [OPTIONS]``
- ``source-layers-run``: ``python -m femic tsr source-layers-run [OPTIONS]``
- ``overlay-init``: ``python -m femic tsr overlay-init [OPTIONS]``
- ``overlay-report``: ``python -m femic tsr overlay-report [OPTIONS]``
- ``override-init``: ``python -m femic tsr override-init [OPTIONS]``
- ``override-report``: ``python -m femic tsr override-report [OPTIONS]``
- ``thlb-netdown-warmstart-build``: ``python -m femic tsr thlb-netdown-warmstart-build [OPTIONS]``
- ``thlb-reconstruction-compare``: ``python -m femic tsr thlb-reconstruction-compare [OPTIONS]``

``tsr index`` options

- ``--output-root PATH`` (optional; defaults to ``metadata/tsr`` under the
  active FEMIC checkout)

``tsr index`` crawls the public BC Timber Supply Review TSA document surfaces
and writes the canonical repo-tracked registry outputs:

- ``metadata/tsr/tsa_registry.json``
- ``metadata/tsr/tsa_documents.json``

This first slice indexes TSA folders, cycles, and linked document metadata
only. It does not download PDFs or extract candidate facts yet.

``tsr fetch`` options

- ``--documents-path PATH`` (optional; defaults to
  ``metadata/tsr/tsa_documents.json`` under the active FEMIC checkout)
- ``--corpus-root PATH`` (optional; defaults to the user-local
  ``~/.femic/tsr/corpus`` and can later be redirected to a separate
  DataLad-managed corpus root)
- ``--manifest-path PATH`` (optional; defaults to the user-local
  ``~/.femic/tsr/tsa_pdf_cache_manifest.json``)
- ``--tsa TEXT`` (repeatable optional TSA filter)
- ``--max-documents INTEGER`` (optional bounded smoke-test/fetch limit)

``tsr fetch`` downloads the indexed TSA PDF corpus into the chosen corpus root
and writes a canonical provenance manifest that stores repo-relative corpus
paths or stable user-local placeholders, checksums, fetch status, and source
URLs without requiring the PDFs themselves to live in the main FEMIC Git
history.

``tsr extract`` options

- ``--documents-path PATH`` (optional; defaults to
  ``metadata/tsr/tsa_documents.json`` under the active FEMIC checkout)
- ``--corpus-root PATH`` (optional; defaults to the user-local
  ``~/.femic/tsr/corpus``)
- ``--output-path PATH`` (optional; defaults to
  ``metadata/tsr/tsa_candidate_facts.json`` under the active FEMIC checkout)
- ``--tsa TEXT`` (repeatable optional TSA filter)
- ``--max-documents INTEGER`` (optional bounded smoke-test/extract limit)

``tsr extract`` reads cached TSR PDFs from the chosen corpus root and emits a
canonical candidate-fact JSON artifact:

- ``metadata/tsr/tsa_candidate_facts.json``

The extraction slice is intentionally review-oriented. It produces candidate
facts for source-layer tokens, AU snippets, THLB references, and TIPSY
assumption snippets with page/snippet provenance, but it does not adopt those
facts into live instance overlays yet.

``tsr facts-report`` options

- ``--tsa TEXT`` (required TSA code, ``tsa_<code>``, or TSA name)
- ``--fact-family TEXT`` (required, repeatable; currently supports at least
  ``source_layer_candidate`` and ``thlb_reference``)
- ``--fact-family [source_layer_candidate|thlb_reference]`` is the most useful
  current review slice for TSR netdown/THLB work
- ``--candidate-facts-path PATH`` (optional; defaults to
  ``metadata/tsr/tsa_candidate_facts.json``)
- ``--output-csv PATH`` (optional review CSV output path)
- ``--limit INTEGER`` (optional cap on sorted review rows)

``tsr facts-report`` renders a review-friendly table over the canonical TSR
candidate-fact pool. It does not mutate the canonical fact artifact or the
instance-local overlay. The first guided-review slice:

- filters by TSA and fact family;
- adds lightweight quality labels:
  - ``likely_useful``
  - ``needs_review``
  - ``likely_noise``;
- preserves provenance and source URLs; and
- can write a CSV that is easier to sort/filter than the raw JSON fact pool.

``tsr recipe-init`` options

- ``--tsa TEXT`` (required TSA code, ``tsa_<code>``, or TSA name)
- ``--instance-root PATH`` (instance root containing ``config/`` and ``data/``)
- ``--registry-path PATH`` (optional; defaults to
  ``metadata/tsr/tsa_registry.json``)
- ``--documents-path PATH`` (optional; defaults to
  ``metadata/tsr/tsa_documents.json``)
- ``--candidate-facts-path PATH`` (optional; defaults to
  ``metadata/tsr/tsa_candidate_facts.json``)
- ``--overlay-path PATH`` (optional; defaults to
  ``config/tsr/overlay.yaml`` under the instance root)
- ``--overrides-path PATH`` (optional; defaults to
  ``config/tsr/source_layer_overrides.yaml`` under the instance root)
- ``--source-layers-recipe-path PATH`` (optional; defaults to
  ``config/tsr/source_layers.recipe.yaml`` under the instance root)
- ``--thlb-netdown-recipe-path PATH`` (optional; defaults to
  ``config/tsr/thlb_netdown.recipe.yaml`` under the instance root)
- ``--overwrite`` (optional; replace existing recipe scaffold files)

``tsr recipe-init`` initializes the two instance-local reviewed working
recipes that later recipe build/run slices will own:

- ``config/tsr/source_layers.recipe.yaml``
- ``config/tsr/thlb_netdown.recipe.yaml``

These recipe files are intentionally distinct from:

- canonical shared TSR discovery JSON under ``metadata/tsr``;
- the reviewed/adopted overlay at ``config/tsr/overlay.yaml``; and
- the wall-moving escape hatch file at
  ``config/tsr/source_layer_overrides.yaml``.

``tsr source-layers-build`` options

- ``--instance-root PATH`` (instance root containing ``config/`` and ``data/``)
- ``--source-layers-recipe-path PATH`` (optional; defaults to
  ``config/tsr/source_layers.recipe.yaml`` under the instance root)
- ``--limit INTEGER`` (optional BCDC package-match cap; defaults to ``5``)

``tsr source-layers-build`` refreshes the reviewed source-layer recipe from:

- canonical TSR source-layer candidate facts;
- the existing guided review heuristics behind ``femic tsr facts-report``; and
- current BCDC resolution metadata.

The command records a deterministic reviewed acquisition plan instead of making
the user re-run the TSA29-style discovery sequence manually every time.

``tsr source-layers-run`` options

- ``--instance-root PATH`` (instance root containing ``config/`` and ``data/``)
- ``--source-layers-recipe-path PATH`` (optional; defaults to
  ``config/tsr/source_layers.recipe.yaml`` under the instance root)
- exactly one AOI input:
  - ``--bbox minx,miny,maxx,maxy`` in ``EPSG:3005``
  - ``--geomark TEXT``
- ``--limit INTEGER`` (optional BCDC package-match cap; defaults to ``5``)
- ``--allow-order`` (optional; permit **new** DWDS order submission for recipe
  entries that still require ``dwds_order``)

``tsr source-layers-run`` executes only the safe acquisition paths already
trusted elsewhere in FEMIC:

- WFS fetch via ``femic data bcdc-fetch``-equivalent logic;
- direct-download reuse via ``femic data bcdc-resolve --download-direct``-equivalent
  logic; and
- automatic DWDS manifest follow-up/materialization for ``dwds_order`` entries
  that already carry a saved ``order_manifest_path``; and
- explicit reviewed override mappings from
  ``config/tsr/source_layer_overrides.yaml``.

``tsr thlb-netdown-build`` options

- ``--instance-root PATH`` (instance root containing ``config/`` and ``data/``)
- ``--thlb-netdown-recipe-path PATH`` (optional; defaults to
  ``config/tsr/thlb_netdown.recipe.yaml`` under the instance root)

``tsr thlb-netdown-build`` refreshes the reviewed THLB netdown recipe from:

- canonical TSR ``thlb_reference`` facts;
- the current source-layer recipe so THLB steps can link to stable logical
  source ids instead of ad hoc filenames; and
- the latest preferred TSR data-package document for the target TSA when
  multiple cycles are present.

The command is intentionally about **what the TSR says to do**, not about
executing the netdown. It writes an ordered, reviewable
``config/tsr/thlb_netdown.recipe.yaml`` that preserves:

- raw TSR wording;
- explicit land-base stage semantics:
  - ``glb_to_aflb``
  - ``aflb_to_lhlb``
  - ``lhlb_to_thlb``
  - ``reference_target``
  - ``context``
- normalized action/subject/predicate hints where the extraction is confident;
- linked source-layer recipe entry ids when they can be derived conservatively;
- per-step readiness/blocking state; and
- the selected source TSR document paths used for the build.

The stage model is the guardrail that keeps the THLB recipe from confusing
universe definition, legal exclusions, projected operational deductions,
benchmark rows, and pure context.

For the full reconstruction-ladder and benchmark-comparison contract behind
those stage labels, see
:doc:`../guides/tsr-thlb-reconstruction-ladder`.

``tsr thlb-netdown-warmstart-build`` options

- ``--instance-root PATH`` (instance root containing ``config/`` and ``data/``)
- ``--thlb-netdown-recipe-path PATH`` (optional; defaults to
  ``config/tsr/thlb_netdown.recipe.yaml`` under the instance root)
- ``--output-markdown PATH`` (optional; defaults to
  ``workbench/tsr/thlb_netdown.warmstart.md`` under the instance root)
- ``--output-yaml PATH`` (optional; defaults to
  ``config/tsr/thlb_warmstart.yaml`` under the instance root)

``tsr thlb-netdown-warmstart-build`` generates a non-canonical no-LLM review
aid from the current reviewed THLB recipe:

- ``workbench/tsr/thlb_netdown.warmstart.md``
- ``config/tsr/thlb_warmstart.yaml``

The artifact is intentionally a warm-start checklist/template, not executable
THLB logic. Its job is to help a human analyst see:

- what FEMIC already knows about each parent step;
- which recurring THLB motif best matches the current row, if any; and
- which likely layers, fields, values, and review questions should be checked
  next.

The canonical executable surface remains:

- ``config/tsr/thlb_netdown.recipe.yaml``

``tsr thlb-reconstruction-compare`` options

- ``--instance-root PATH`` (instance root containing ``config/`` and ``data/``)
- ``--thlb-netdown-recipe-path PATH`` (optional; defaults to
  ``config/tsr/thlb_netdown.recipe.yaml`` under the instance root)
- ``--reconstructed-audit-path PATH`` (optional; defaults to
  ``config/tsr/thlb_reconstructed.audit.json`` under the instance root)
- ``--reviewed-status-path PATH`` (optional; defaults to
  ``config/tsr/thlb_netdown.status.md`` under the instance root)
- ``--output-markdown PATH`` (optional; defaults to
  ``config/tsr/thlb_reconstruction_comparison.md`` under the instance root)
- ``--output-json PATH`` (optional; defaults to
  ``config/tsr/thlb_reconstruction_comparison.json`` under the instance root)

``tsr thlb-reconstruction-compare`` is the explain-first comparison surface
for the still-open strict-reconstruction gap under ``#128``. It reads the
existing reviewed and reconstructed TSA29 artifacts and emits:

- ``config/tsr/thlb_reconstruction_comparison.md``
- ``config/tsr/thlb_reconstruction_comparison.json``

The command does **not** rerun THLB execution. Its job is to show, in plain
language:

- strict reconstructed THLB vs TSR-reported THLB as the primary benchmark;
- reviewed bridge THLB vs TSR-reported THLB as context for why the reviewed
  lane was accepted for practical exploratory use;
- strict reconstructed vs reviewed bridge deltas as explanatory context rather
  than the main score; and
- which parent steps should be treated as:
  - close enough to TSR;
  - real strict overcut/undercut seams;
  - missing-data seams;
  - or accepted reviewed bridges / aspatial fallback territory.

``tsr thlb-netdown-workbench-build`` options

- ``--instance-root PATH`` (instance root containing ``config/`` and ``data/``)
- ``--thlb-netdown-recipe-path PATH`` (optional; defaults to
  ``config/tsr/thlb_netdown.recipe.yaml`` under the instance root)
- ``--workbench-path PATH`` (optional; defaults to
  ``workbench/tsr/thlb_netdown.workbench.ipynb`` under the instance root)

``tsr thlb-netdown-workbench-build`` generates a Jupyter notebook bridge
artifact from the current reviewed THLB recipe. The notebook is intentionally
**not** the canonical source of truth. Instead it is a structured work surface
for:

- LLM-assisted piloting of the THLB review/execution process; and
- no-LLM human review when users need a warm-start workbench instead of raw
  YAML or JSON.

The notebook is generated from the same parent-step + draft-subrule structure
already captured in ``config/tsr/thlb_netdown.recipe.yaml`` and organizes the
workflow into a text -> code -> output -> interpretation ladder grouped by:

- ``GLB -> AFLB``
- ``AFLB -> LHLB``
- ``LHLB -> THLB``

The generated cells also respect the stage boundary in the underlying FEMIC
pipeline, but current TSA29 strict validation must stay on validated
``data/tsr/*.feather`` seam checkpoints rather than legacy
``ria_vri_vclr1p_checkpoint*.feather`` fallbacks.

``tsr thlb-netdown-workbench-lock`` options

- ``--instance-root PATH`` (instance root containing ``config/`` and ``data/``)
- ``--thlb-netdown-recipe-path PATH`` (optional; defaults to
  ``config/tsr/thlb_netdown.recipe.yaml`` under the instance root)
- ``--workbench-path PATH`` (optional; defaults to
  ``workbench/tsr/thlb_netdown.workbench.ipynb`` under the instance root)
- ``--lock-scope [aflb|thlb|all]`` (optional; defaults to ``all``)

``tsr thlb-netdown-workbench-lock`` freezes the current reviewed state into a
deterministic reproducibility bundle:

- ``workbench/tsr/thlb_netdown.locked.py``
- a frozen recipe copy
- a frozen Markdown status report copy
- a frozen audit JSON copy when one exists

Important lock contract:

- AFLB lock freezes the modeled universe definition
- THLB lock freezes the downstream harvest-eligibility logic
- THLB cannot lock unless AFLB is already locked or locked in the same pass
- cutting AFLB invalidates THLB because THLB is downstream from the AFLB
  universe definition

``tsr thlb-netdown-step-run`` options

- ``PARENT_STEP_ID`` (required parent-step id from
  ``config/tsr/thlb_netdown.recipe.yaml``)
- ``--instance-root PATH`` (instance root containing ``config/`` and ``data/``)
- ``--thlb-netdown-recipe-path PATH`` (optional; defaults to
  ``config/tsr/thlb_netdown.recipe.yaml`` under the instance root)
- ``--checkpoint-path PATH`` (optional; explicit inputs may be Feather or a
  readable vector dataset such as GeoPackage; current TSA29 strict validation
  should pass an explicit validated checkpoint path under ``data/tsr/``)
- ``--map-id TEXT`` (repeatable; optional explicit ``MAP_ID`` subset)
- ``--auto-map-id-smoke-subset / --no-auto-map-id-smoke-subset`` (default:
  ``--auto-map-id-smoke-subset``)

``tsr thlb-netdown-step-run`` executes one parent step cumulatively on the
small smoke subset and writes working artifacts under:

- ``runtime/logs/tsr/notebook_runs/``

This helper is the command-line twin of the generated notebook cells and keeps
the small-area proving-ground discipline explicit while the recipe shape is
still being refined.

``tsr thlb-netdown-run`` options

- ``--instance-root PATH`` (instance root containing ``config/`` and ``data/``)
- ``--thlb-netdown-recipe-path PATH`` (optional; defaults to
  ``config/tsr/thlb_netdown.recipe.yaml`` under the instance root)
- ``--checkpoint-path PATH`` (optional; explicit inputs may be Feather or a
  readable vector dataset such as GeoPackage; current TSA29 strict validation
  should pass an explicit validated checkpoint path under ``data/tsr/``)
- ``--output-path PATH`` (optional; defaults to
  ``data/tsr/thlb_netdown_checkpoint.feather`` under the instance root)
- ``--audit-path PATH`` (optional; defaults to
  ``config/tsr/thlb_netdown.audit.json`` under the instance root)
- ``--execution-mode [hybrid|reconstructed]`` (optional; defaults to
  ``hybrid``)
- ``--map-id TEXT`` (repeatable optional VRI mapsheet smoke subset)
- ``--auto-map-id-smoke-subset`` (optional bounded reconstructed smoke helper)
- ``--allow-stand-binary-fallback`` (optional non-default debug fallback for
  reconstructed mode only)
- ``--no-aflb-gpkg`` (optional; suppress the default
  ``data/tsr/aflb_checkpoint.gpkg`` companion export when a reconstructed run
  reaches the AFLB milestone)
- ``--no-lhlb-gpkg`` (optional; suppress the default
  ``data/tsr/lhlb_checkpoint.gpkg`` companion export when a reconstructed run
  reaches the LHLB milestone)
- ``--no-lhlb-curve-ready-gpkg`` (optional; suppress the default
  ``data/tsr/lhlb_curve_ready_checkpoint.gpkg`` companion export when a
  reconstructed run promotes the official LHLB checkpoint into the late-stage
  curve-ready restart surface)

``tsr thlb-netdown-run`` executes a bounded subset of the reviewed THLB recipe
into a stand-level checkpoint that carries ``thlb_fact`` for downstream export
and simulation flows.

Current v1 execution contract:

- ``use_land_base`` and ``no_deduction`` become explicit no-op audit rows;
- ``exclude`` steps with fetched polygon sources are applied as stand-level
  overlap deductions in ``EPSG:3005``;
- unsupported or low-confidence actions remain explicit as
  ``needs_review`` / ``unsupported`` / ``blocked_missing_source`` instead of
  being guessed silently; and
- the run writes both:
  - ``data/tsr/thlb_netdown_checkpoint.feather``
  - ``config/tsr/thlb_netdown.audit.json``
  - ``config/tsr/thlb_netdown.status.md``
  - plus a timestamped history copy under ``runtime/logs/tsr/``
- reconstructed runs that genuinely reach the AFLB milestone now also write:
  ``data/tsr/aflb_checkpoint.feather`` as the canonical downstream restart
  artifact, and ``data/tsr/aflb_checkpoint.gpkg`` by default as the GIS-facing
  companion export
- reconstructed runs that genuinely reach the LHLB milestone now also write:
  ``data/tsr/lhlb_checkpoint.feather`` as the canonical raw post-step-12
  restart artifact, and ``data/tsr/lhlb_checkpoint.gpkg`` by default as the
  GIS-facing companion export
- reconstructed runs that need strict ``LHLB -> THLB`` execution now also
  promote that raw LHLB restart into
  ``data/tsr/lhlb_curve_ready_checkpoint.feather`` as the canonical late-stage
  restart artifact for steps ``13+``, with
  ``data/tsr/lhlb_curve_ready_checkpoint.gpkg`` written by default as the
  GIS-facing companion export unless the caller disables it explicitly

This command is intentionally partial-success friendly: it should move the
recipe forward where FEMIC has enough trustworthy information while keeping the
remaining wall visible and reproducible.

The generated status report keeps benchmark ratios visible while the THLB logic
converges:

- a GLB/AFLB/LHLB/THLB backbone summary;
- input checkpoint area;
- AFLB / baseline managed area;
- final THLB area;
- current executable ratios such as the GLB:AFLB proxy and ``AFLB:THLB``; and
- TSR AFLB / THLB benchmark values when they can be parsed from the selected
  data package PDF.

It also groups the reviewed steps by:

- ``GLB -> AFLB``
- ``AFLB -> LHLB``
- ``LHLB -> THLB``
- ``Reference targets``
- ``Context / interpretation``

Important current boundary:

- ``--execution-mode hybrid`` is still the reviewed stand-level bridge from
  issue ``#126``;
- ``--execution-mode reconstructed`` is now the promoted fragment-first lane:
  for current TSA29 strict validation it must start from an explicit validated
  ``data/tsr/*.feather`` seam checkpoint, fragment the working land base where
  reviewed spatial exclusions intersect, and assign binary fragment-level THLB
  membership ``{0,1}``;
- reconstructed exact spatial steps now run LU-wise by default:
  FEMIC cuts one Landscape Unit chunk at a time instead of trying to build one
  full-TSA exact-overlay workload;
- reconstructed mode now supports two honest deduction types: exact fragment
  overlay where FEMIC has a reviewed spatial implementation, and explicit
  recipe-driven aspatial fallback where the reviewed recipe already carries a
  TSR target-area deduction;
- ``--checkpoint-path data/tsr/aflb_checkpoint.feather`` is now the supported
  downstream restart seam when analysts want to explore ``AFLB -> LHLB ->
  THLB`` logic without rebuilding the settled ``GLB -> AFLB`` ladder;
- ``--checkpoint-path data/tsr/lhlb_checkpoint.feather`` is now the supported
  raw post-step-12 restart seam when analysts want to inspect or rebuild the
  stage boundary itself;
- ``--checkpoint-path data/tsr/lhlb_curve_ready_checkpoint.feather`` is now the
  supported downstream restart seam when analysts want to explore only
  strict ``LHLB -> THLB`` logic without rebuilding the settled upstream ladder;
- this is an explicit recipe-driven aspatial fallback, not a silent substitute
  for blocked spatial logic;
- blocked exact-overlay rows still remain explicit instead of being silently
  converted into fallback; and
- the old coarse stand-binary approximation remains available only behind the
  explicit ``--allow-stand-binary-fallback`` debug flag.

For the conceptual distinction between those two modes, plus the comparison
contract against TSR-reported THLB, see
:doc:`../guides/tsr-thlb-reconstruction-ladder`.

``tsr overlay-init`` options

- ``--tsa TEXT`` (required TSA code, ``tsa_<code>``, or TSA name)
- ``--instance-root PATH`` (instance root containing ``config/`` and ``data/``)
- ``--registry-path PATH`` (optional; defaults to
  ``metadata/tsr/tsa_registry.json``)
- ``--documents-path PATH`` (optional; defaults to
  ``metadata/tsr/tsa_documents.json``)
- ``--candidate-facts-path PATH`` (optional; defaults to
  ``metadata/tsr/tsa_candidate_facts.json`` for canonical candidate facts)
- ``--overlay-path PATH`` (optional; defaults to
  ``config/tsr/overlay.yaml`` under the instance root)
- ``--overwrite`` (optional; replace an existing overlay)

``tsr overlay-init`` initializes the instance-local reviewed/adopted overlay:

- ``config/tsr/overlay.yaml``

The initialized overlay stores only TSA identity, canonical provenance
references, candidate-summary counts, and empty adopted sections. It does not
auto-promote unresolved candidate facts into live instance truth.

``tsr overlay-report`` options

- ``--instance-root PATH`` (instance root containing ``config/`` and ``data/``)
- ``--overlay-path PATH`` (optional; defaults to
  ``config/tsr/overlay.yaml`` under the instance root)

``tsr overlay-report`` compares the local reviewed overlay against the canonical
candidate summary already stored inside the overlay and reports adopted counts
per section without mutating the file.

``tsr override-init`` options

- ``--instance-root PATH`` (instance root containing ``config/`` and ``data/``)
- ``--overlay-path PATH`` (optional; defaults to
  ``config/tsr/overlay.yaml`` under the instance root)
- ``--overrides-path PATH`` (optional; defaults to
  ``config/tsr/source_layer_overrides.yaml`` under the instance root)
- ``--overwrite`` (optional; replace an existing override file)

``tsr override-init`` initializes an instance-local source-layer override file
from unresolved TSA rows already captured in the reviewed TSR overlay:

- ``config/tsr/source_layer_overrides.yaml``

Use it when the public BCDC resolver has hit an honest wall and you need to
record a reviewed escape hatch such as:

- a local filesystem path;
- a bespoke dataset URL;
- a FEMIC/DataLad-managed mirror path;
- a reviewed replacement layer; or
- an explicit ``private`` / ``unavailable`` marker with notes.

``tsr override-report`` options

- ``--instance-root PATH`` (instance root containing ``config/`` and ``data/``)
- ``--overlay-path PATH`` (optional; defaults to
  ``config/tsr/overlay.yaml`` under the instance root)
- ``--overrides-path PATH`` (optional; defaults to
  ``config/tsr/source_layer_overrides.yaml`` under the instance root)

The override workflow is for reviewed escape hatches only. ``override-init``
can now pre-populate ``replacement_family_candidates`` for a small number of
stale/public-facing wall cases, but those suggestions are not automatic
replacements and are never auto-fetched or auto-adopted.

``tsr override-report`` compares the override file against the unresolved rows
still present in the TSR overlay and reports:

- total override entries;
- how many are already resolved vs still pending; and
- which override kinds are currently in use.

For the full operator/agent workflow from TSR page to cached PDFs to reviewed
instance overlay, see ``docs/guides/tsr-intelligence-workflow.rst``.

Export
------

.. code-block:: text

   python -m femic export [OPTIONS] COMMAND [ARGS]...

Subcommands

- ``patchworks``: ``python -m femic export patchworks [OPTIONS]``
- ``woodstock``: ``python -m femic export woodstock [OPTIONS]``
- ``dual``: ``python -m femic export dual [OPTIONS]``
- ``release``: ``python -m femic export release [OPTIONS]``

``export patchworks`` options

- ``--tsa TEXT`` (repeatable, required; selected FMU/code values)
- ``--bundle-dir PATH`` (default: ``data/model_input_bundle``)
- ``--checkpoint PATH`` (default: ``data/ria_vri_vclr1p_checkpoint7.feather``)
- ``--output-dir PATH`` (default: ``output/patchworks``)
- ``--start-year INTEGER`` (default: ``2026``)
- ``--horizon-years INTEGER`` (default: ``300``)
- ``--cc-min-age INTEGER`` (default: ``0``)
- ``--cc-max-age INTEGER`` (default: ``1000``)
- ``--cc-transition-ifm TEXT`` (default: unset; no IFM transition assign)
- ``--fragments-crs TEXT`` (default: ``EPSG:3005``)
- ``--ifm-mode TEXT`` (default: ``proportional``; ``proportional`` keeps
  continuous THLB share via ``RETENTION``, ``legacy_binary`` preserves the
  older threshold/share-based stand snap)
- ``--ifm-source-col TEXT`` (optional; explicit checkpoint THLB signal column)
- ``--ifm-threshold FLOAT`` (optional; legacy-binary mode only; managed when
  source value > threshold)
- ``--ifm-target-managed-share FLOAT`` (optional; legacy-binary mode only;
  top-N managed by source value)
- ``--seral-stage-config PATH`` (optional; YAML per-AU seral-stage boundaries)
- ``--instance-root PATH``

``export woodstock`` options

- ``--tsa TEXT`` (repeatable, required; selected FMU/code values)
- ``--bundle-dir PATH`` (default: ``data/model_input_bundle``)
- ``--checkpoint PATH`` (default: ``data/ria_vri_vclr1p_checkpoint7.feather``)
- ``--output-dir PATH`` (default: ``output/woodstock``)
- ``--cc-min-age INTEGER`` (default: ``0``)
- ``--cc-max-age INTEGER`` (default: ``1000``)
- ``--fragments-crs TEXT`` (default: ``EPSG:3005``)
- ``--instance-root PATH``

``export dual`` options

- ``--tsa TEXT`` (repeatable, required; selected FMU/code values)
- ``--bundle-dir PATH`` (default: ``data/model_input_bundle``)
- ``--checkpoint PATH`` (default: ``data/ria_vri_vclr1p_checkpoint7.feather``)
- ``--patchworks-output-dir PATH`` (default: ``output/patchworks``)
- ``--woodstock-output-dir PATH`` (default: ``output/woodstock``)
- ``--with-ws3-smoke / --no-ws3-smoke`` (default: ``--no-ws3-smoke``)
- ``--ws3-command TEXT`` (optional shell command for ws3 simulation smoke)
- ``--ws3-workdir PATH`` (optional command working directory)
- ``--ws3-report PATH`` (default: ``evidence/ws3_smoke_report.latest.json``)
- ``--ws3-require-command / --ws3-allow-no-command`` (default: allow no command)
- ``--ws3-timeout-seconds INTEGER`` (default: ``600``)
- ``--ws3-repo-path PATH`` (optional local ws3 checkout path for builtin smoke)
- ``--ws3-builtin-smoke / --no-ws3-builtin-smoke`` (default: ``--no-ws3-builtin-smoke``)
- ``--ws3-bridge-dir PATH`` (optional output directory for generated ws3 section files)
- ``--instance-root PATH``

``export release`` options

- ``--case-id TEXT`` (default: ``case``)
- ``--output-root PATH`` (default: ``releases``)
- ``--bundle-dir PATH`` (default: ``data/model_input_bundle``)
- ``--patchworks-dir PATH`` (default: ``output/patchworks_k3z_validated``)
- ``--woodstock-dir PATH`` (optional)
- ``--logs-dir PATH`` (default: ``runtime/logs``)
- ``--run-id TEXT`` (optional)
- ``--strict / --no-strict`` (default: ``--strict``)
- ``--instance-root PATH``

Patchworks Runtime
------------------

.. code-block:: text

   python -m femic patchworks [OPTIONS] COMMAND [ARGS]...

Use this command group when you want FEMIC to inspect or launch registry-backed
Patchworks variants, scenarios, and scenario sets, while still preserving the
lower-level ``run-headless <pin>`` primitive seam.

Subcommands

- ``preflight``: ``python -m femic patchworks preflight [OPTIONS]``
- ``instances list``: ``python -m femic patchworks instances list [OPTIONS]``
- ``build-blocks``: ``python -m femic patchworks build-blocks [OPTIONS]``
- ``matrix-build``: ``python -m femic patchworks matrix-build [OPTIONS]``
- ``run-headless``: ``python -m femic patchworks run-headless [OPTIONS] PIN``
- ``run-default-scenario``: ``python -m femic patchworks run-default-scenario [OPTIONS] VARIANT_ID``
- ``run-default-scenario-set``: ``python -m femic patchworks run-default-scenario-set [OPTIONS] INSTANCE_ID``
- ``run-scenario``: ``python -m femic patchworks run-scenario [OPTIONS] VARIANT_ID SCENARIO_ID``
- ``run-variant``: ``python -m femic patchworks run-variant [OPTIONS] VARIANT_ID``
- ``scenarios list``: ``python -m femic patchworks scenarios list [OPTIONS] VARIANT_ID``
- ``scenario-sets list``: ``python -m femic patchworks scenario-sets list [OPTIONS]``
- ``scenario-sets show``: ``python -m femic patchworks scenario-sets show [OPTIONS] SCENARIO_SET_ID``
- ``variants list``: ``python -m femic patchworks variants list [OPTIONS]``
- ``variants register``: ``python -m femic patchworks variants register [OPTIONS] VARIANT_ID``
- ``variants remove``: ``python -m femic patchworks variants remove [OPTIONS] VARIANT_ID``
- ``variants show``: ``python -m femic patchworks variants show [OPTIONS] VARIANT_ID``
- ``variants update``: ``python -m femic patchworks variants update [OPTIONS] VARIANT_ID``

``patchworks preflight`` options

- ``--config PATH`` (default: ``config/patchworks.runtime.yaml``)

``patchworks instances list`` options

- ``--registry PATH`` (default: ``~/.femic/variants.yaml``; installed providers and user overlay loaded)

``patchworks matrix-build`` options

- ``--config PATH`` (default: ``config/patchworks.runtime.yaml``)
- ``--instance-root PATH``
- ``--log-dir PATH`` (default: ``runtime/logs``)
- ``--run-id TEXT``
- ``--interactive``
- ``--instance-root PATH``

``patchworks build-blocks`` options

- ``--config PATH`` (default: ``config/patchworks.runtime.yaml``)
- ``--model-dir PATH`` (optional; inferred from runtime config when omitted)
- ``--fragments-shp PATH`` (optional; defaults to runtime fragments ``.shp``)
- ``--topology-radius FLOAT`` (default: ``200.0``)
- ``--with-topology / --no-topology`` (default: ``--with-topology``)
- ``--instance-root PATH``

``patchworks run-headless`` options

- ``PIN`` argument (required)
- ``--config PATH`` (default: ``config/patchworks.runtime.yaml``)
- ``--log-dir PATH`` (default: ``runtime/logs``)
- ``--run-id TEXT`` (optional)
- ``--stage-label TEXT`` (optional)
- ``--iterations INTEGER`` (default: ``1``)
- ``--improvement FLOAT`` (default: ``0.0``)
- ``--scenario-mode TEXT`` (default: ``none``)
- ``--scenario-target TEXT`` (optional)
- ``--scenario-min-annual FLOAT`` (optional)
- ``--instance-root PATH``

``patchworks run-variant`` options

- ``VARIANT_ID`` argument (required)
- ``--registry PATH`` (default: ``~/.femic/variants.yaml``; installed providers and user overlay loaded)
- ``--log-dir PATH`` (default: ``runtime/logs``)
- ``--run-id TEXT`` (optional)
- ``--stage-label TEXT`` (optional)
- ``--iterations INTEGER`` (default: ``1``)
- ``--improvement FLOAT`` (default: ``0.0``)
- ``--scenario-mode TEXT`` (default: ``none``)
- ``--scenario-target TEXT`` (optional)
- ``--scenario-min-annual FLOAT`` (optional)
- ``--allow-large-download`` (skip the materialization confirmation prompt when
  known estimated downloads exceed the threshold)
- ``--materialization-threshold-mib INTEGER`` (default: ``100``)

``patchworks scenarios list`` options

- ``VARIANT_ID`` argument (required)
- ``--registry PATH`` (default: ``~/.femic/variants.yaml``; installed providers and user overlay loaded)

``patchworks scenario-sets list`` options

- ``--registry PATH`` (default: ``~/.femic/variants.yaml``; installed providers and user overlay loaded)
- ``--instance-id TEXT`` (optional instance id filter)

``patchworks scenario-sets show`` options

- ``SCENARIO_SET_ID`` argument (required)
- ``--registry PATH`` (default: ``~/.femic/variants.yaml``; installed providers and user overlay loaded)

``patchworks run-scenario`` options

- ``VARIANT_ID`` argument (required)
- ``SCENARIO_ID`` argument (required)
- ``--registry PATH`` (default: ``~/.femic/variants.yaml``; installed providers and user overlay loaded)
- ``--log-dir PATH`` (default: ``runtime/logs``)
- ``--run-id TEXT`` (optional)
- ``--stage-label TEXT`` (optional override; falls back to the registry scenario when set there)
- ``--allow-large-download`` (skip the materialization confirmation prompt when
  known estimated downloads exceed the threshold)
- ``--materialization-threshold-mib INTEGER`` (default: ``100``)

``patchworks run-default-scenario`` options

- ``VARIANT_ID`` argument (required)
- ``--registry PATH`` (default: ``~/.femic/variants.yaml``; installed providers and user overlay loaded)
- ``--log-dir PATH`` (default: ``runtime/logs``)
- ``--run-id TEXT`` (optional)
- ``--stage-label TEXT`` (optional override; falls back to the registry default scenario when set there)
- ``--allow-large-download`` (skip the materialization confirmation prompt when
  known estimated downloads exceed the threshold)
- ``--materialization-threshold-mib INTEGER`` (default: ``100``)

``patchworks run-default-scenario-set`` options

- ``INSTANCE_ID`` argument (required)
- ``--registry PATH`` (default: ``~/.femic/variants.yaml``; installed providers and user overlay loaded)
- ``--log-dir PATH`` (default: ``runtime/logs``)
- ``--run-id TEXT`` (optional; step runs derive ``_01``, ``_02``, ...)
- ``--stage-label TEXT`` (optional; per-step stage labels derive ``_01``,
  ``_02``, ...)
- ``--allow-large-download`` (skip the materialization confirmation prompt when
  known estimated downloads exceed the threshold)
- ``--materialization-threshold-mib INTEGER`` (default: ``100``)

``patchworks run-scenario-set`` options

- ``SCENARIO_SET_ID`` argument (required)
- ``--registry PATH`` (default: ``~/.femic/variants.yaml``; installed providers and user overlay loaded)
- ``--log-dir PATH`` (default: ``runtime/logs``)
- ``--run-id TEXT`` (optional; step runs derive ``_01``, ``_02``, ...)
- ``--stage-label TEXT`` (optional; per-step stage labels derive ``_01``,
  ``_02``, ...)
- ``--allow-large-download`` (skip the materialization confirmation prompt when
  known estimated downloads exceed the threshold)
- ``--materialization-threshold-mib INTEGER`` (default: ``100``)

``patchworks variants list`` options

- ``--registry PATH`` (default: ``~/.femic/variants.yaml``; installed providers and user overlay loaded)
- ``--instance-id TEXT`` (optional filter)

``patchworks variants register`` options

- ``VARIANT_ID`` argument (required)
- ``--label TEXT`` (required)
- ``--instance-id TEXT`` (required)
- ``--instance-label TEXT`` (optional)
- ``--instance-root PATH`` (required)
- ``--analysis-pin PATH`` (required)
- ``--runtime-config PATH`` (required)
- ``--variant-family TEXT`` (default: ``default``)
- ``--kind TEXT`` (default: ``patchworks``)
- ``--default / --no-default`` (default: ``--no-default``)
- ``--registry PATH`` (default: ``~/.femic/variants.yaml``; writes the user overlay)

``patchworks variants update`` options

- ``VARIANT_ID`` argument (required)
- ``--label TEXT`` (optional)
- ``--instance-id TEXT`` (optional)
- ``--instance-label TEXT`` (optional)
- ``--instance-root PATH`` (optional)
- ``--analysis-pin PATH`` (optional)
- ``--runtime-config PATH`` (optional)
- ``--variant-family TEXT`` (optional)
- ``--kind TEXT`` (optional)
- ``--default BOOL`` (optional explicit override: ``true`` or ``false``)
- ``--registry PATH`` (default: ``~/.femic/variants.yaml``; writes the user overlay)

``patchworks variants remove`` options

- ``VARIANT_ID`` argument (required)
- ``--registry PATH`` (default: ``~/.femic/variants.yaml``; removes only user-overlay entries)

``patchworks variants show`` options

- ``VARIANT_ID`` argument (required)
- ``--registry PATH`` (default: ``~/.femic/variants.yaml``; installed providers and user overlay loaded)
- ``--materialization-threshold-mib INTEGER`` (default: ``100``; used when
  summarizing registry-declared materialization)

``patchworks variants materialization-plan`` options

- ``VARIANT_ID`` argument (required)
- ``--registry PATH`` (default: ``~/.femic/variants.yaml``; installed providers and user overlay loaded)
- ``--materialization-threshold-mib INTEGER`` (default: ``100``; used when
  deciding whether the current plan would require confirmation)

Both ``patchworks variants show`` and
``patchworks variants materialization-plan`` now print:

- one aggregate materialization summary;
- one dataset-root grouped summary per touched dataset; and
- the supporting raw per-action detail lines.

Operational notes:

- installed instance-package providers are discovered through entry points;
- ``~/.femic/variants.yaml`` is a writable user overlay, not the only source
  of truth;
- launch-time materialization consent is driven by the grouped dataset summary
  before the raw per-action detail lines.

Instance Workspace
------------------

.. code-block:: text

   python -m femic instance [OPTIONS] COMMAND [ARGS]...

Subcommands

- ``init``: ``python -m femic instance init [OPTIONS]``
- ``config show``: ``python -m femic instance config show``
- ``config set-managed-external-root``:
  ``python -m femic instance config set-managed-external-root <path>``
- ``config set-user-instance-root``:
  ``python -m femic instance config set-user-instance-root <path>``
- ``catalog list``: ``python -m femic instance catalog list``
- ``catalog install``: ``python -m femic instance catalog install <instance-id|all>``
- ``builtins list``: compatibility alias for ``catalog list``
- ``builtins install``: compatibility alias for ``catalog install``
- ``rebuild``: ``python -m femic instance rebuild [OPTIONS]``
- ``validate-spec``: ``python -m femic instance validate-spec [OPTIONS]``
- ``promote-evidence``: ``python -m femic instance promote-evidence [OPTIONS]``
- ``refresh-reference-evidence``: ``python -m femic instance refresh-reference-evidence [OPTIONS]``
- ``account-surface``: ``python -m femic instance account-surface [OPTIONS]``
- ``ws3-smoke``: ``python -m femic instance ws3-smoke [OPTIONS]``

``instance init`` options

- ``--instance-root PATH`` (optional; defaults to CWD)
- ``--instance-name TEXT`` (optional; create under configured visible user
  instance root; mutually exclusive with ``--instance-root``)
- ``--overwrite`` (overwrite existing scaffold template files)
- ``--download-bc-vri / --no-download-bc-vri`` (default: ``--download-bc-vri``)
- ``--yes`` / ``-y`` (assume yes for prompts)

``instance config show`` output

- current config path
- whether ``user.yaml`` exists yet
- resolved managed registered-instance root
- resolved visible user-instance root
- the default values FEMIC would use if the config file is absent

``instance catalog list`` output

- registered instance id and label
- install status
- resolved install path
- standalone repo URL
- declared support-repo dependencies/notes

``instance catalog install`` behavior

- clones missing registered instance repos into the configured managed external root
- clones declared support repos if missing
- skips already-installed git worktrees
- does **not** run ``datalad get`` automatically
- prints next-step guidance for payload materialization instead

Operational notes:

- packaged-install config now lives at ``~/.femic/user.yaml`` (or the Windows
  equivalent);
- FEMIC uses that config for managed registered instances and the visible user workspace
  root;
- normal operational runtime precedence is still
  ``--instance-root`` -> ``FEMIC_INSTANCE_ROOT`` -> current working directory.

``instance rebuild`` options

- ``--spec PATH`` (default: ``config/rebuild.spec.yaml``)
- ``--run-config PATH`` (default: ``config/run_profile.case_template.yaml``)
- ``--tipsy-config-dir PATH`` (default: ``config/tipsy``)
- ``--log-dir PATH`` (default: ``runtime/logs``)
- ``--run-id TEXT`` (optional; defaults to UTC timestamp)
- ``--with-patchworks / --no-patchworks`` (default: ``--no-patchworks``)
- ``--dry-run`` (print planned step sequence without execution)
- ``--patchworks-config PATH`` (default: ``config/patchworks.runtime.yaml``)
- ``--baseline PATH`` (default: ``config/rebuild.baseline.json``)
- ``--write-baseline`` (write/update baseline snapshot before diff evaluation)
- ``--allowlist PATH`` (default: ``config/rebuild.allowlist.yaml``)
- ``--instance-root PATH``

``instance rebuild`` writes a machine-readable report to
``runtime/logs/instance_rebuild_report-<run_id>.json`` and records discovered
manifest/log artifact references under ``artifact_references``.
It also writes ``diagnostics.account_surface`` when ``tracks/accounts.csv`` is
available, including a deterministic
``total_ok_species_empty_signature`` flag and recommended next checks.
It also evaluates configured rebuild-spec invariants and appends measured
``metrics`` plus ``invariant_results`` to the report. Any invariant with
``severity: fatal`` that evaluates false causes command failure with a
remediation summary.
When a baseline snapshot is available, the report also includes a ``baseline``
section with table/XML structural diffs and aggregate ``baseline_match`` /
``baseline_diff_count`` metrics. If an allowlist file is present, rebuild also
computes ``baseline_allowlist_match`` and ``baseline_unexpected_diff_count``
for explicit intentional-delta tracking.
Rebuild exits non-zero when unexpected baseline diffs exceed
``runtime.baseline_unexpected_diff_threshold`` from ``rebuild.spec.yaml``
(default ``0``), and writes ``regression_gate`` details into the report.

``instance validate-spec`` options

- ``--spec PATH`` (default: ``config/rebuild.spec.yaml``)
- ``--instance-root PATH``

``instance promote-evidence`` options

- ``--report PATH`` (optional; defaults to latest rebuild report in ``--log-dir``)
- ``--output PATH`` (default: ``evidence/reference_rebuild_report.latest.json``)
- ``--log-dir PATH`` (default: ``runtime/logs``)
- ``--max-warn-increase INT`` (optional drift warning threshold)
- ``--max-baseline-diff-increase INT`` (optional drift warning threshold)
- ``--instance-root PATH``

Promoted evidence summary also includes:

- ``summary.account_surface_total_ok_species_empty_signature``
- ``summary.account_surface_species_count``

``instance refresh-reference-evidence`` options

- ``--report PATH`` (optional; defaults to latest report in reference ``runtime/logs``)
- ``--reference-root PATH`` (default: ``instances/reference``)
- ``--max-warn-increase INT`` (optional drift warning threshold)
- ``--max-baseline-diff-increase INT`` (optional drift warning threshold)

``instance account-surface`` options

- ``--config PATH`` (default: ``config/patchworks.runtime.yaml``)
- ``--output PATH`` (optional JSON output path for diagnostics summary)
- ``--instance-root PATH``

``instance account-surface`` reads ``tracks/accounts.csv`` from the configured
Patchworks matrix output folder and summarizes species-level account coverage
(``product.Yield.managed.*`` and ``product.HarvestedVolume.managed.*.CC``)
plus AU-level seral account coverage.
When ``tracks/products.csv`` and ``tracks/curves.csv`` are available it also
computes a deterministic diagnosis for the
``total OK, species-wise empty`` failure signature and prints recommended
next-check steps.

``instance ws3-smoke`` options

- ``--woodstock-dir PATH`` (default: ``output/woodstock``)
- ``--output PATH`` (default: ``evidence/ws3_smoke_report.latest.json``)
- ``--ws3-command TEXT`` (optional shell command for ws3 simulation smoke)
- ``--ws3-workdir PATH`` (optional command working directory)
- ``--require-command / --allow-no-command`` (default: allow no command)
- ``--timeout-seconds INTEGER`` (default: ``600``)
- ``--ws3-repo-path PATH`` (optional local ws3 checkout path for builtin smoke)
- ``--builtin-model-smoke / --no-builtin-model-smoke`` (default: ``--builtin-model-smoke``)
- ``--ws3-bridge-dir PATH`` (optional output directory for generated ws3 section files)
- ``--instance-root PATH``