PB-078: Preview tags match the docs
State: Proposed. Not approved for implementation. Priority: P1 (mandatory: required). Owner when approved: Master product (unassigned).
1. PR title and ID#
Tag every docs-Preview feature in the app, or correct the docs (PB-078)
2. Business problem#
Organizations hide Preview features by policy (show_preview). Features the docs call Preview but
the app doesn't tag can't be hidden, so a locked-down organization still exposes them. AGENTS.md
requires untested Fabric integrations to keep Preview labeling.
3. Current verified behavior#
app/ui/features.jsPREVIEW_FEATUREShas 19 ids (fabricRun through workloads);previewTag()hides tagged nodes whenshow_previewis false.app/tests/ui.test.cjschecks Workloads is Preview.docs/metadata-guide.mdlabels as Preview: batches (batch_by, line 142), reliability objectives (line 243), release records (line 293), who can promote (line 319), column lineage (line 511). None has a Preview id. Batches, objectives and release records are engine behaviors with little or no UI; column lineage has no UI (FEAT-META-17).
4. Desired behavior#
For each docs-Preview capability: if it has a UI surface, that surface carries a Preview id and is
hidden with Preview off; if it has none, the engine respects show_preview (for example the
promote card's release-record note) or the docs say "engine behavior, not hideable" and why.
5. In scope and out of scope#
In scope: ids for surfaces that exist (promote card release note and role check, batch settings in the entity editor if present); docs wording; a UI test that keeps the two lists aligned. Out of scope: new screens for lineage or objectives (PB-081, PB-047).
6. Architecture and files#
app/ui/features.js, app/ui/meta.js (promote card), docs/metadata-guide.md,
app/tests/ui.test.cjs, docs/README.md features table if it lists Preview.
7. Functional requirements#
- New ids follow the existing naming (camelCase keys, plain names).
- With
show_previewfalse the tagged surfaces disappear, and promote still works without them. - The test parses
docs/*.mdfor "(Preview)" headings and fails when a heading has no id and no documented exception.
8. Nonfunctional requirements#
No new rail items (the rail is full at 8).
9. Dependencies#
None.
10. Security and compatibility#
Hiding a check from the UI must not skip the check itself: who-can-promote stays enforced when its note is hidden.
11. Acceptance criteria#
- Every docs-Preview feature has an id or a documented exception.
- With Preview off, none of the tagged surfaces shows; promote still runs its gates (test).
- UI tests pass.
12. Unit and integration tests#
Extend app/tests/ui.test.cjs: docs-vs-ids alignment, hidden-when-off for each new id.
13. Manual verification#
Settings > Preview features off, open an entity and the promote card, confirm tagged parts are gone.
14. Documentation#
docs/metadata-guide.md Preview wording; docs/README.md if it lists Preview features.
15. Rollback#
Revert; ids are additive.
16. Definition of Done#
Merged, UI tests green, FEAT-SHL-05 limitation removed in the inventory after review.
Need a hand?
Find a fix in troubleshooting, or share a reproducible issue with the community.
Get support ↗Improve this guide on GitHub ↗