sdr-visualizer 1.2.0__tar.gz → 1.2.2__tar.gz

{sdr_visualizer-1.2.0 → sdr_visualizer-1.2.2}/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to `sdr-visualizer` will be documented here. The format foll
 
 ## [Unreleased]
 
+## [1.2.2] - 2026-09-21
+
+### Changed
+
+- Advance the tested-through generator markers to `cja_auto_sdr` 3.12.4 and
+  `aa_auto_sdr` 1.21.15. Both were qualified with a fresh production snapshot
+  and the full historical private corpus, so snapshots from those versions no
+  longer raise a newer-than-tested warning.
+- Carry the streamlined README into the published package so the PyPI project
+  description matches the repository.
+
+## [1.2.1] - 2026-09-21
+
+### Fixed
+
+- Handle a Workspace worker exit race during process-group cleanup on macOS.
+  A rejected signal is accepted only after the child exits within the existing
+  two-second wait; a still-running child retains the original error.
+- Accept the exactly qualified `cja_auto_sdr` 3.12.2 and 3.12.4 executables for
+  CJA lineage discovery. Other unqualified versions continue to fail closed
+  before live acquisition.
+
+### Changed
+
+- Correct README and Workspace onboarding guidance for saved snapshots, live
+  collection, authentication, supported output, and safe sharing.
+- Add a reusable release-evidence template for exact-candidate qualification,
+  publication authorization, public verification, and announcement decisions.
+- Document the repository's current maintainer review model and preserve required
+  checks and pre-release settings inspection.
+
 ## [1.2.0] - 2026-09-12
 
 ### Added
@@ -682,7 +713,9 @@ The following are explicitly internal and may change without notice:
 - Workspace project visualization (v0.4)
 - Schema map view (v0.5)
 
-[Unreleased]: https://github.com/brian-a-au/sdr-visualizer/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/brian-a-au/sdr-visualizer/compare/v1.2.2...HEAD
+[1.2.2]: https://github.com/brian-a-au/sdr-visualizer/releases/tag/v1.2.2
+[1.2.1]: https://github.com/brian-a-au/sdr-visualizer/releases/tag/v1.2.1
 [1.2.0]: https://github.com/brian-a-au/sdr-visualizer/releases/tag/v1.2.0
 [1.1.7]: https://github.com/brian-a-au/sdr-visualizer/releases/tag/v1.1.7
 [1.1.6]: https://github.com/brian-a-au/sdr-visualizer/releases/tag/v1.1.6

{sdr_visualizer-1.2.0 → sdr_visualizer-1.2.2}/CONTRIBUTING.md

@@ -61,6 +61,10 @@ Every PR needs: tests for behavior changes, a green suite, clean
 coverage from the non-browser Python suite, and green browser/perf gates when
 the change could plausibly affect them.
 
+Current repository settings permit maintainer self-review and require zero
+independent approvals. Required checks still apply. Maintainers re-inspect these
+settings before each release and record the result in the release evidence.
+
 Release artifacts are not considered usable merely because `uv build`
 succeeds. The package smoke check installs the wheel and source distribution
 independently into temporary environments outside the checkout, then verifies

{sdr_visualizer-1.2.0 → sdr_visualizer-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdr-visualizer
-Version: 1.2.0
+Version: 1.2.2
 Summary: Static-output visual catalog generator for Adobe Customer Journey Analytics and Adobe Analytics implementations.
 Project-URL: Homepage, https://brian-a-au.github.io/sdr-visualizer/
 Project-URL: Documentation, https://github.com/brian-a-au/sdr-visualizer#documentation
@@ -45,10 +45,10 @@ Static-output visual catalog generator for Adobe Customer Journey Analytics (CJA
 
 **Live examples:** [CJA report](https://brian-a-au.github.io/sdr-visualizer/cja-typical.html) · [AA report](https://brian-a-au.github.io/sdr-visualizer/aa-typical.html)
 
-The output is one HTML file: no server, no consumer-side build step, and no
-CDN dependencies. Its JSON, CSS, JavaScript, and D3 runtime are embedded, so it
-opens in a modern browser without an internet connection and makes no network
-requests.
+The output is one HTML file. There is no server, no consumer-side build step,
+and no CDN dependency. Its JSON, CSS, JavaScript, and D3 runtime are all
+embedded, so it opens in a modern browser with no internet connection and makes
+no network requests.
 
 Offline does not mean cleared for distribution. A report can contain
 implementation and component names, descriptions, segment and
@@ -57,6 +57,22 @@ Treat it as derived from the source snapshot. Move, email, post, or attach it
 only in authorized locations and in accordance with your organization's
 confidentiality and data-handling policy.
 
+## Public preview scope
+
+This project is in public preview. A report describes what is configured in a
+snapshot. It does not grade the implementation, and it does not confirm that a
+configuration is correct, complete, or working at runtime. Review the details
+against the source implementation before you act on them.
+
+The report embeds the supported normalized component catalog, not every
+platform-specific field. Optional Workspace project references are unverified
+candidates, and an empty result never means a component is unused. Keep the
+original generator snapshot for anything the report does not embed.
+
+The tool is verified on Ubuntu with Python 3.11, 3.12, and 3.14. Other platforms
+and later Python versions are not yet verified. The package installs on Python
+3.11 or newer.
+
 ## Install
 
 Install from PyPI with uv:
@@ -99,7 +115,7 @@ sdr-visualizer snapshot_new.json --compare-to snapshot_old.json
 sdr-visualizer ./snapshots/ --trend
 ```
 
-The output lands at `./visualize-{instance_id}-{timestamp}.html` by default. Open it in a browser — that's the whole experience.
+The output lands at `./visualize-{instance_id}-{timestamp}.html` by default. Open it in a browser. That is the whole experience.
 
 Standard input is also supported when another process already emits a complete
 compatible snapshot:
@@ -108,13 +124,16 @@ compatible snapshot:
 some-snapshot-command | sdr-visualizer -
 ```
 
-## Live CJA
+## Live modes
+
+Both live modes call a separate generator that you install and authenticate
+yourself. Follow that project's current setup, then confirm the executable is on
+your `PATH`. Either generator may require a newer Python version than
+sdr-visualizer's Python 3.11 minimum. The upstream repository is authoritative
+for credentials, permissions, and generator compatibility.
 
-Live CJA mode requires the separate
-[`cja_auto_sdr`](https://github.com/brian-a-au/cja_auto_sdr) executable. Follow
-that project's current installation, configuration, and authentication
-instructions, then confirm `cja_auto_sdr` is on your `PATH`. Its generator may
-require a newer Python version than sdr-visualizer's Python 3.11 minimum.
+Live CJA mode uses the
+[`cja_auto_sdr`](https://github.com/brian-a-au/cja_auto_sdr) executable:
 
 ```bash
 sdr-visualizer --dataview dv_prod_web
@@ -122,39 +141,37 @@ sdr-visualizer --dataview dv_prod_web
 
 sdr-visualizer runs the generator with JSON output, a temporary output
 directory, and `--include-all-inventory`, then selects the generated snapshot.
-The temporary source data is removed after the report is built. This is not a
-stdin pipeline: CJA's complete inventory is directory-backed.
+It removes the temporary source data after the report is built. This is not a
+stdin pipeline. CJA's complete inventory comes from a directory of files.
 
-## Live AA
-
-Live AA mode likewise requires the separate
-[`aa_auto_sdr`](https://github.com/brian-a-au/aa_auto_sdr) executable. Complete
-its current setup and authentication steps, and confirm `aa_auto_sdr` is on your
-`PATH`. The generator may require a newer Python version than sdr-visualizer.
+Live AA mode uses the
+[`aa_auto_sdr`](https://github.com/brian-a-au/aa_auto_sdr) executable:
 
 ```bash
 sdr-visualizer --rsid prod_us
 ```
 
-AA live mode reads the generator JSON snapshot from stdout and embeds the
-supported normalized component catalog in the report. Retain the original
+AA live mode reads the generator's JSON snapshot from stdout and embeds the
+supported normalized component catalog in the report. Keep the original
 generator snapshot when you need platform-specific details that the visualizer
-does not embed. For both live modes, the upstream repository is authoritative
-for credentials, permissions, and generator compatibility.
+does not embed.
 
 ## Optional Workspace project usage
 
 Add project-usage evidence while generating the HTML. Install the independent
-extra for your platform, then opt in to collection using an existing credential
-source:
+extra for your platform with uv, then opt in to collection using an existing
+credential source. The CJA and AA extras are independent; use the one that
+matches your snapshot:
 
 ```bash
-pip install 'sdr-visualizer[workspace-cja]'
+uv tool install 'sdr-visualizer[workspace-cja]'
 sdr-visualizer snapshots/cja.json --collect-workspace-usage \
   --workspace-usage-org 'EXAMPLE@AdobeOrg' \
   --workspace-usage-config ../credentials/adobe.json --output cja.html
+```
 
-pip install 'sdr-visualizer[workspace-aa]'
+```bash
+uv tool install 'sdr-visualizer[workspace-aa]'
 sdr-visualizer snapshots/aa.json --collect-workspace-usage \
   --workspace-usage-org 'EXAMPLE@AdobeOrg' --workspace-usage-company example-company \
   --workspace-usage-config ../credentials/adobe.json --output aa.html
@@ -164,7 +181,8 @@ Each command automatically writes HTML and `<html-stem>.workspace-usage.json`.
 Existing snapshots and live exporter modes work without exporter changes.
 The catalog shows possible project references separately from component
 dependencies, with check time and coverage limits. SDK matches remain
-unverified candidates; empty results never mean unused or safe to delete.
+unverified candidates. Empty results never mean a component is unused or safe
+to delete.
 Opening the HTML and replaying the saved usage file need no credentials or
 network access. See the
 [Workspace usage guide](https://github.com/brian-a-au/sdr-visualizer/blob/main/docs/WORKSPACE_USAGE.md)
@@ -176,6 +194,8 @@ for collection scopes, offline replay, identity binding, limits, and privacy.
 |---|---|
 | `--output PATH`           | Write HTML somewhere specific. |
 | `--json PATH`             | Also emit the embedded payload as a separate JSON file (useful for downstream tooling). |
+| `--collect-workspace-usage` | Collect optional Workspace project-usage evidence; see the [Workspace usage guide](https://github.com/brian-a-au/sdr-visualizer/blob/main/docs/WORKSPACE_USAGE.md). |
+| `--workspace-usage PATH`  | Replay saved Workspace usage evidence with the original snapshot. |
 | `--title TEXT`            | Override the document title. |
 | `--color-pack CODE`       | Select `default`, `ADBE`, `OMTR`, or `BLUE` for HTML presentation (case-sensitive). |
 | `--exclude-orphans`       | Default the catalog's references filter to "Referenced" — hides components nothing depends on. |
@@ -206,9 +226,9 @@ Color-pack selection changes HTML presentation only. It does not add to or
 alter the embedded JSON or a `--json` sidecar. The pack CSS, report data, and
 runtime remain embedded in the single offline HTML file.
 
-The named packs are palette-inspired alternatives, not official brand assets
-or claims of affiliation or endorsement, and they contain no company or
-product logos. Each pack is checked against the project's declared WCAG text
+The named packs are alternative palettes. They are not official brand assets or
+claims of affiliation or endorsement, and they contain no company or product
+logos. Each pack is checked against the project's declared WCAG text
 and essential-graphics contrast pairs. Text labels and other non-color cues
 continue to communicate state, and reviewed print colors keep reports legible
 when printed.
@@ -222,9 +242,14 @@ Every report has two base top-level views:
 
 Segment anatomy and calculated-metric anatomy are contextual detail content,
 not separate navigation destinations. They open from the Catalog detail panel.
-Segment anatomy renders nested containers and references; calculated-metric
+Segment anatomy renders nested containers and references. Calculated-metric
 anatomy renders operations, operands, and metric references.
 
+You can restore an exact view from its address. The catalog's filters, sort,
+view, and open detail panel are encoded in the URL hash, so within an
+authorized report location you can copy the address bar to reload the same
+filtered view.
+
 At most one conditional top-level view is added. With `--compare-to`, a
 **Changes** view appears, listing components
 added, removed, and modified relative to a baseline snapshot, with
@@ -237,18 +262,16 @@ per-interval change log. The window is capped at the 60 most recent
 snapshots.
 
 A trend directory must hold snapshots of a single implementation. If it mixes
-CJA and AA snapshots, pass `--platform cja|aa` to select one (or point at a
-single-platform directory); without it the run stops rather than guess. If it
-mixes data views or report suites, the run stops as well. This mirrors
-`--compare-to`, which refuses both a platform and an instance mismatch, so
+CJA and AA snapshots, pass `--platform cja|aa` to select one, or point at a
+single-platform directory. Without that, the run stops rather than guess. If it
+mixes data views or report suites, the run also stops. `--compare-to` behaves
+the same way and refuses both a platform mismatch and an instance mismatch, so
 neither view ever diffs unrelated inventories. To compare or chart across
-different data views or report suites on purpose (for example staging versus
-prod drift), pass `--allow-instance-mismatch`; the run then proceeds with a
+different data views or report suites on purpose, for example staging versus
+prod drift, pass `--allow-instance-mismatch`. The run then proceeds with a
 warning. Platform mismatches are always rejected. The report shown alongside
 the trend is the newest usable snapshot in the directory.
 
-- **Restorable report links** — the catalog's filters, sort, view, and open detail panel are encoded in the URL hash. Within an authorized report location, copy the address bar to restore the same filtered view.
-
 ## Performance budget
 
 The output is CI-gated against the budgets in
@@ -257,8 +280,8 @@ Build time and HTML size are enforced at every published tier (100 / 500 / 1,000
 components). Browser-measured budgets are enforced at the 1,000-component tier
 (initial render < 1s, filter/search < 150ms) and the 2,000-component tier
 (< 2s, < 300ms), plus a 700ms cap on the graph view's main-thread block.
-These guarantees cover up to 8,000 reference edges; denser valid reports use
-an explicit graph opt-in and sit outside the published size/latency envelope.
+These guarantees cover up to 8,000 reference edges. Denser valid reports use an
+explicit graph opt-in and sit outside the published size and latency limits.
 Functional browser tests cover Chromium and WebKit. A separate Chromium-only
 performance gate measures all four component tiers; this is not a timing
 guarantee for every branded browser.
@@ -302,8 +325,8 @@ the schema as loosely specified. Current-generator and private-corpus
 validation is a separate, recorded release gate; see
 [`docs/RELEASING.md`](https://github.com/brian-a-au/sdr-visualizer/blob/main/docs/RELEASING.md).
 
-**CJA lineage.** Starting with 1.1.0, `cja-lineage` adds a separate CJA-only
-command. Its documented arguments and exit codes are described in the
+**CJA lineage.** `cja-lineage` adds a separate CJA-only command. Its documented
+arguments and exit codes are described in the
 [lineage guide](https://github.com/brian-a-au/sdr-visualizer/blob/main/docs/LINEAGE.md).
 Its embedded payload and Python modules are internal and do not extend the
 catalog schema or JSON sidecar contract.
@@ -317,14 +340,15 @@ Warnings (snapshot generator newer than the tested version; 5,000+ component rep
 Requires Python 3.11+ and [uv](https://github.com/astral-sh/uv).
 
 ```bash
-uv sync --all-extras    # Set up environment, including optional SDK tests
-uv run pytest          # Run tests (auto-generates the large fixture on first run)
+uv sync --all-extras --dev --group browser  # Full test environment, including SDK tests
+uv run playwright install chromium webkit
+uv run pytest                               # Run tests (auto-generates the large fixture on first run)
 uv run ruff check      # Lint
 uv run ruff format     # Auto-format
 
 uv run python scripts/generate_examples.py   # Regenerate examples/
-uv run python scripts/check_color_pack_parity.py \\
-  --visualizer-sha <candidate-commit-sha> \\
+uv run python scripts/check_color_pack_parity.py \
+  --visualizer-sha <candidate-commit-sha> \
   --grader-root ../sdr-grader --grader-sha <linked-grader-commit-sha>
 uv run python scripts/perf_check.py          # Run the perf gate
 uv run python scripts/check_markdown_links.py
@@ -337,7 +361,7 @@ uv run python scripts/package_smoke_check.py dist/packages/
 
 See which Adobe Experience Platform (AEP) datasets feed your CJA Connections
 and which Data Views use those Connections. The **`cja-lineage`** command is
-included when you install `sdr-visualizer` (version 1.1.0 or later).
+included when you install `sdr-visualizer`.
 
 Start with a saved dataset discovery JSON file from
 `cja_auto_sdr --list-datasets --format json --output -`. This file lists datasets

{sdr_visualizer-1.2.0 → sdr_visualizer-1.2.2}/README.md

@@ -22,10 +22,10 @@ Static-output visual catalog generator for Adobe Customer Journey Analytics (CJA
 
 **Live examples:** [CJA report](https://brian-a-au.github.io/sdr-visualizer/cja-typical.html) · [AA report](https://brian-a-au.github.io/sdr-visualizer/aa-typical.html)
 
-The output is one HTML file: no server, no consumer-side build step, and no
-CDN dependencies. Its JSON, CSS, JavaScript, and D3 runtime are embedded, so it
-opens in a modern browser without an internet connection and makes no network
-requests.
+The output is one HTML file. There is no server, no consumer-side build step,
+and no CDN dependency. Its JSON, CSS, JavaScript, and D3 runtime are all
+embedded, so it opens in a modern browser with no internet connection and makes
+no network requests.
 
 Offline does not mean cleared for distribution. A report can contain
 implementation and component names, descriptions, segment and
@@ -34,6 +34,22 @@ Treat it as derived from the source snapshot. Move, email, post, or attach it
 only in authorized locations and in accordance with your organization's
 confidentiality and data-handling policy.
 
+## Public preview scope
+
+This project is in public preview. A report describes what is configured in a
+snapshot. It does not grade the implementation, and it does not confirm that a
+configuration is correct, complete, or working at runtime. Review the details
+against the source implementation before you act on them.
+
+The report embeds the supported normalized component catalog, not every
+platform-specific field. Optional Workspace project references are unverified
+candidates, and an empty result never means a component is unused. Keep the
+original generator snapshot for anything the report does not embed.
+
+The tool is verified on Ubuntu with Python 3.11, 3.12, and 3.14. Other platforms
+and later Python versions are not yet verified. The package installs on Python
+3.11 or newer.
+
 ## Install
 
 Install from PyPI with uv:
@@ -76,7 +92,7 @@ sdr-visualizer snapshot_new.json --compare-to snapshot_old.json
 sdr-visualizer ./snapshots/ --trend
 ```
 
-The output lands at `./visualize-{instance_id}-{timestamp}.html` by default. Open it in a browser — that's the whole experience.
+The output lands at `./visualize-{instance_id}-{timestamp}.html` by default. Open it in a browser. That is the whole experience.
 
 Standard input is also supported when another process already emits a complete
 compatible snapshot:
@@ -85,13 +101,16 @@ compatible snapshot:
 some-snapshot-command | sdr-visualizer -
 ```
 
-## Live CJA
+## Live modes
+
+Both live modes call a separate generator that you install and authenticate
+yourself. Follow that project's current setup, then confirm the executable is on
+your `PATH`. Either generator may require a newer Python version than
+sdr-visualizer's Python 3.11 minimum. The upstream repository is authoritative
+for credentials, permissions, and generator compatibility.
 
-Live CJA mode requires the separate
-[`cja_auto_sdr`](https://github.com/brian-a-au/cja_auto_sdr) executable. Follow
-that project's current installation, configuration, and authentication
-instructions, then confirm `cja_auto_sdr` is on your `PATH`. Its generator may
-require a newer Python version than sdr-visualizer's Python 3.11 minimum.
+Live CJA mode uses the
+[`cja_auto_sdr`](https://github.com/brian-a-au/cja_auto_sdr) executable:
 
 ```bash
 sdr-visualizer --dataview dv_prod_web
@@ -99,39 +118,37 @@ sdr-visualizer --dataview dv_prod_web
 
 sdr-visualizer runs the generator with JSON output, a temporary output
 directory, and `--include-all-inventory`, then selects the generated snapshot.
-The temporary source data is removed after the report is built. This is not a
-stdin pipeline: CJA's complete inventory is directory-backed.
+It removes the temporary source data after the report is built. This is not a
+stdin pipeline. CJA's complete inventory comes from a directory of files.
 
-## Live AA
-
-Live AA mode likewise requires the separate
-[`aa_auto_sdr`](https://github.com/brian-a-au/aa_auto_sdr) executable. Complete
-its current setup and authentication steps, and confirm `aa_auto_sdr` is on your
-`PATH`. The generator may require a newer Python version than sdr-visualizer.
+Live AA mode uses the
+[`aa_auto_sdr`](https://github.com/brian-a-au/aa_auto_sdr) executable:
 
 ```bash
 sdr-visualizer --rsid prod_us
 ```
 
-AA live mode reads the generator JSON snapshot from stdout and embeds the
-supported normalized component catalog in the report. Retain the original
+AA live mode reads the generator's JSON snapshot from stdout and embeds the
+supported normalized component catalog in the report. Keep the original
 generator snapshot when you need platform-specific details that the visualizer
-does not embed. For both live modes, the upstream repository is authoritative
-for credentials, permissions, and generator compatibility.
+does not embed.
 
 ## Optional Workspace project usage
 
 Add project-usage evidence while generating the HTML. Install the independent
-extra for your platform, then opt in to collection using an existing credential
-source:
+extra for your platform with uv, then opt in to collection using an existing
+credential source. The CJA and AA extras are independent; use the one that
+matches your snapshot:
 
 ```bash
-pip install 'sdr-visualizer[workspace-cja]'
+uv tool install 'sdr-visualizer[workspace-cja]'
 sdr-visualizer snapshots/cja.json --collect-workspace-usage \
   --workspace-usage-org 'EXAMPLE@AdobeOrg' \
   --workspace-usage-config ../credentials/adobe.json --output cja.html
+```
 
-pip install 'sdr-visualizer[workspace-aa]'
+```bash
+uv tool install 'sdr-visualizer[workspace-aa]'
 sdr-visualizer snapshots/aa.json --collect-workspace-usage \
   --workspace-usage-org 'EXAMPLE@AdobeOrg' --workspace-usage-company example-company \
   --workspace-usage-config ../credentials/adobe.json --output aa.html
@@ -141,7 +158,8 @@ Each command automatically writes HTML and `<html-stem>.workspace-usage.json`.
 Existing snapshots and live exporter modes work without exporter changes.
 The catalog shows possible project references separately from component
 dependencies, with check time and coverage limits. SDK matches remain
-unverified candidates; empty results never mean unused or safe to delete.
+unverified candidates. Empty results never mean a component is unused or safe
+to delete.
 Opening the HTML and replaying the saved usage file need no credentials or
 network access. See the
 [Workspace usage guide](https://github.com/brian-a-au/sdr-visualizer/blob/main/docs/WORKSPACE_USAGE.md)
@@ -153,6 +171,8 @@ for collection scopes, offline replay, identity binding, limits, and privacy.
 |---|---|
 | `--output PATH`           | Write HTML somewhere specific. |
 | `--json PATH`             | Also emit the embedded payload as a separate JSON file (useful for downstream tooling). |
+| `--collect-workspace-usage` | Collect optional Workspace project-usage evidence; see the [Workspace usage guide](https://github.com/brian-a-au/sdr-visualizer/blob/main/docs/WORKSPACE_USAGE.md). |
+| `--workspace-usage PATH`  | Replay saved Workspace usage evidence with the original snapshot. |
 | `--title TEXT`            | Override the document title. |
 | `--color-pack CODE`       | Select `default`, `ADBE`, `OMTR`, or `BLUE` for HTML presentation (case-sensitive). |
 | `--exclude-orphans`       | Default the catalog's references filter to "Referenced" — hides components nothing depends on. |
@@ -183,9 +203,9 @@ Color-pack selection changes HTML presentation only. It does not add to or
 alter the embedded JSON or a `--json` sidecar. The pack CSS, report data, and
 runtime remain embedded in the single offline HTML file.
 
-The named packs are palette-inspired alternatives, not official brand assets
-or claims of affiliation or endorsement, and they contain no company or
-product logos. Each pack is checked against the project's declared WCAG text
+The named packs are alternative palettes. They are not official brand assets or
+claims of affiliation or endorsement, and they contain no company or product
+logos. Each pack is checked against the project's declared WCAG text
 and essential-graphics contrast pairs. Text labels and other non-color cues
 continue to communicate state, and reviewed print colors keep reports legible
 when printed.
@@ -199,9 +219,14 @@ Every report has two base top-level views:
 
 Segment anatomy and calculated-metric anatomy are contextual detail content,
 not separate navigation destinations. They open from the Catalog detail panel.
-Segment anatomy renders nested containers and references; calculated-metric
+Segment anatomy renders nested containers and references. Calculated-metric
 anatomy renders operations, operands, and metric references.
 
+You can restore an exact view from its address. The catalog's filters, sort,
+view, and open detail panel are encoded in the URL hash, so within an
+authorized report location you can copy the address bar to reload the same
+filtered view.
+
 At most one conditional top-level view is added. With `--compare-to`, a
 **Changes** view appears, listing components
 added, removed, and modified relative to a baseline snapshot, with
@@ -214,18 +239,16 @@ per-interval change log. The window is capped at the 60 most recent
 snapshots.
 
 A trend directory must hold snapshots of a single implementation. If it mixes
-CJA and AA snapshots, pass `--platform cja|aa` to select one (or point at a
-single-platform directory); without it the run stops rather than guess. If it
-mixes data views or report suites, the run stops as well. This mirrors
-`--compare-to`, which refuses both a platform and an instance mismatch, so
+CJA and AA snapshots, pass `--platform cja|aa` to select one, or point at a
+single-platform directory. Without that, the run stops rather than guess. If it
+mixes data views or report suites, the run also stops. `--compare-to` behaves
+the same way and refuses both a platform mismatch and an instance mismatch, so
 neither view ever diffs unrelated inventories. To compare or chart across
-different data views or report suites on purpose (for example staging versus
-prod drift), pass `--allow-instance-mismatch`; the run then proceeds with a
+different data views or report suites on purpose, for example staging versus
+prod drift, pass `--allow-instance-mismatch`. The run then proceeds with a
 warning. Platform mismatches are always rejected. The report shown alongside
 the trend is the newest usable snapshot in the directory.
 
-- **Restorable report links** — the catalog's filters, sort, view, and open detail panel are encoded in the URL hash. Within an authorized report location, copy the address bar to restore the same filtered view.
-
 ## Performance budget
 
 The output is CI-gated against the budgets in
@@ -234,8 +257,8 @@ Build time and HTML size are enforced at every published tier (100 / 500 / 1,000
 components). Browser-measured budgets are enforced at the 1,000-component tier
 (initial render < 1s, filter/search < 150ms) and the 2,000-component tier
 (< 2s, < 300ms), plus a 700ms cap on the graph view's main-thread block.
-These guarantees cover up to 8,000 reference edges; denser valid reports use
-an explicit graph opt-in and sit outside the published size/latency envelope.
+These guarantees cover up to 8,000 reference edges. Denser valid reports use an
+explicit graph opt-in and sit outside the published size and latency limits.
 Functional browser tests cover Chromium and WebKit. A separate Chromium-only
 performance gate measures all four component tiers; this is not a timing
 guarantee for every branded browser.
@@ -279,8 +302,8 @@ the schema as loosely specified. Current-generator and private-corpus
 validation is a separate, recorded release gate; see
 [`docs/RELEASING.md`](https://github.com/brian-a-au/sdr-visualizer/blob/main/docs/RELEASING.md).
 
-**CJA lineage.** Starting with 1.1.0, `cja-lineage` adds a separate CJA-only
-command. Its documented arguments and exit codes are described in the
+**CJA lineage.** `cja-lineage` adds a separate CJA-only command. Its documented
+arguments and exit codes are described in the
 [lineage guide](https://github.com/brian-a-au/sdr-visualizer/blob/main/docs/LINEAGE.md).
 Its embedded payload and Python modules are internal and do not extend the
 catalog schema or JSON sidecar contract.
@@ -294,14 +317,15 @@ Warnings (snapshot generator newer than the tested version; 5,000+ component rep
 Requires Python 3.11+ and [uv](https://github.com/astral-sh/uv).
 
 ```bash
-uv sync --all-extras    # Set up environment, including optional SDK tests
-uv run pytest          # Run tests (auto-generates the large fixture on first run)
+uv sync --all-extras --dev --group browser  # Full test environment, including SDK tests
+uv run playwright install chromium webkit
+uv run pytest                               # Run tests (auto-generates the large fixture on first run)
 uv run ruff check      # Lint
 uv run ruff format     # Auto-format
 
 uv run python scripts/generate_examples.py   # Regenerate examples/
-uv run python scripts/check_color_pack_parity.py \\
-  --visualizer-sha <candidate-commit-sha> \\
+uv run python scripts/check_color_pack_parity.py \
+  --visualizer-sha <candidate-commit-sha> \
   --grader-root ../sdr-grader --grader-sha <linked-grader-commit-sha>
 uv run python scripts/perf_check.py          # Run the perf gate
 uv run python scripts/check_markdown_links.py
@@ -314,7 +338,7 @@ uv run python scripts/package_smoke_check.py dist/packages/
 
 See which Adobe Experience Platform (AEP) datasets feed your CJA Connections
 and which Data Views use those Connections. The **`cja-lineage`** command is
-included when you install `sdr-visualizer` (version 1.1.0 or later).
+included when you install `sdr-visualizer`.
 
 Start with a saved dataset discovery JSON file from
 `cja_auto_sdr --list-datasets --format json --output -`. This file lists datasets

{sdr_visualizer-1.2.0 → sdr_visualizer-1.2.2}/docs/LINEAGE.md

@@ -43,9 +43,14 @@ Alternatively use `--profile profile-name`, or omit both credential selectors
 to use the upstream default credential route. `--profile` and `--config-file`
 are mutually exclusive and apply only to `--live`. The executable and explicit
 configuration paths must be absolute. Live discovery currently accepts exactly
-`cja_auto_sdr` 3.11.8 and 3.12.0. Other versions fail closed pending compatibility
-qualification; saved discovery is validated by shape rather than generator
-version. No generator is installed automatically.
+`cja_auto_sdr` 3.11.8, 3.12.0, 3.12.2, and 3.12.4. Other versions fail closed pending
+compatibility qualification; saved discovery is validated by shape rather than
+generator version. Version 3.12.2 was qualified against the offline discovery
+contract with synthetic inventories and blocked network access. That compatibility
+check does not qualify credentials, network behavior, or a live release. No
+generator is installed automatically. Version 3.12.4 was qualified with fresh
+read-only dataset discovery and saved-shape validation; this does not imply
+complete visibility into every dataset or Connection.
 
 The command currently targets macOS and Linux, using POSIX process and
 owner-only output protections. Windows execution is not qualified. The generated

{sdr_visualizer-1.2.0 → sdr_visualizer-1.2.2}/docs/PRODUCT_CONTRACT.md

@@ -207,8 +207,8 @@ unusable, and capped-out members do not warn. The current markers are:
 
 | Platform | Warning threshold |
 |---|---:|
-| CJA (`cja_auto_sdr`) | 3.11.7 |
-| AA (`aa_auto_sdr`) | 1.21.10 |
+| CJA (`cja_auto_sdr`) | 3.12.4 |
+| AA (`aa_auto_sdr`) | 1.21.15 |
 
 A marker is evidence of exercised compatibility, not a promise about every
 possible snapshot produced by that version. It may advance only after a