# Product Advisory: Interface Surfacing Strategy for “Hidden” Backend Capabilities
ID: ADVISORY-20260116-IFACE-SURFACING
Status: ACTIVE
Owner intent: Product-wide directive
Applies to: FEATURE_MATRIX.md, CLI, Web UI, Doctor, module dossiers, sprints

## 0) Why this advisory exists

The Feature Gaps Report shows a typical problem in fast-moving monorepos:
- capabilities exist in code,
- but are not surfaced in CLI/UI,
- and therefore are not usable, not supportable, and not credibly marketable.
This product advisory is based features discovered and documented on file FEATURE_GAPS_REPORT.md in code but not listed in FEATURE_MATRIX.md

Therefore, interface work must do two things:
1) reduce support burden (“Doctor-first operability”), and
2) strengthen the suite’s moat (evidence-grade decisions, explainability, determinism).

This advisory defines which backend capabilities should be surfaced via **CLI** and/or **UI**, and the minimal “how” to do it.

---

## 1) Non-negotiable principles (solo-scale rules)

### P1: No “capability theatre”
If a capability is claimed in FEATURE_MATRIX.md as “available”, it must have:
- a supported activation path (**UI or CLI or config + Doctor validation**), and
- documentation that explains how to use it.

If not, it must be marked as:
- **Automatic (always-on)**, or
- **Internal (not supported / not marketed)**, or
- **Planned**.

### P2: Prefer “exports” and “inspectors” over new UI pages
To avoid UI explosion, surface many capabilities as:
- **Export profiles** (downloadable artifacts)
- **Inspector views** (read-only detail panes)
- **Minimal admin actions** (rotate key, test connector, download SARIF)

Avoid building bespoke UI workflows unless they materially reduce operator labor.

### P3: CLI is the control plane for automation and air-gap
Anything used in:
- CI,
- offline operations,
- bulk admin,
- reproducibility / debugging,
must have a CLI path.

UI is for:
- day-to-day operator workflows,
- triage,
- explainability (“why blocked?”),
- visualizations.

### P4: Doctor-first for support reduction
If a feature is likely to generate tickets (connectors, crypto, queues, replay),
it must have:
- a Doctor check (and a Doctor bundle payload),
- deterministic “reason codes” for failures,
- a runbook entry.

### P5: Progressive disclosure
Don’t overwhelm users with advanced controls.
Expose:
- simple defaults in UI,
- advanced knobs in CLI/config,
- deep internals only in Doctor bundles.

---

## 2) Decision rubric: UI vs CLI vs Doc-only

Classify each discovered capability into exactly one of these:

### Class A — Automatic (Doc-only)
Use when the capability:
- runs implicitly as part of scan/policy/evidence workflows, and
- doesn’t require user input to be valuable.

Requirement:
- Document it in FEATURE_MATRIX.md as **Automatic**.
- Ensure its outcomes show up in existing UI/exports (e.g., findings detail, evidence packet).

Examples:
- Secrets detection that runs during scan
- OS package analyzers invoked implicitly
- Symlink/whiteout handling in layered filesystem

### Class B — CLI-first (automation/admin/offline)
Use when the capability:
- is primarily an operator/admin action,
- is needed in automation/CI,
- is needed offline,
- or is a bulk/advanced workflow.

Requirement:
- Add CLI commands with `--format json` and `--output`.
- Update docs with copy/paste examples.
- Add Doctor checks if it can fail due to environment dependencies.

Examples:
- SBOM convert/validate
- Key rotation, trust anchors
- Policy verdict export
- Timeline/HLC inspection

### Class C — UI-first (triage/explainability)
Use when the capability:
- improves human decision-making,
- reduces triage effort,
- is part of “why blocked/approved”.

Requirement:
- Add a minimal UI surface (read-only or download action).
- Provide deterministic “reason” traces and evidence links.

Examples:
- Path witness visualization for reachability
- SARIF download in the UI
- Connector status dashboard

### Class D — Both (high-value + frequent usage)
Use when the capability:
- is used in pipelines (CLI), and
- is also used in investigations/audits (UI).

Examples:
- Audit bundle export
- VEX consensus/verification
- Evidence packs

### Class E — Internal (do not surface yet)
Use when the capability:
- is not stable enough to support,
- would multiply permutations,
- or is not aligned with current product focus.

Requirement:
- Do not list as a primary feature in FEATURE_MATRIX.md.
- It may remain in a “Known internal capabilities” appendix for engineering only.

---

## 3) Priority: what to surface first (P0/P1/P2)

### P0 (must surface) — Moat + Support reduction
These directly improve “why blocked?”, auditability, operability, and adoption.

#### P0-1: Exports and evidence surfaces
- Add/standardize CLI:
  - `stella export audit ...`
  - `stella export lineage ...`
  - `stella export risk ...`
  - `stella export evidence-pack ...`
- UI: ensure Export Center supports:
  - download audit bundles,
  - download lineage evidence packs,
  - download risk bundles.

Acceptance:
- Export outputs are deterministic, versioned, and include a manifest with hashes.
- Doctor validates export prerequisites (storage, permissions, disk space).

#### P0-2: “Why blocked?” explainability completeness
- CLI:
  - `stella score explain <digest|runId> --format json`
  - `stella reachability witness <digest> --vuln <cve> --format mermaid|json`
  - `stella reachability guards <digest> --format json`
- UI:
  - add “Witness Path” view for reachable findings (Mermaid/GraphViz render),
  - show confidence breakdown (path/guard/runtime components),
  - link to evidence URIs (`stella://...`) and replay manifests where available.

Acceptance:
- For any blocked decision, UI can show:
  - which gate blocked,
  - what evidence triggered it,
  - and at least one witness or explanation trace.

#### P0-3: SARIF in UI (high adoption win)
- UI: add “Download SARIF” for a scan run and/or digest.
- CLI already exists (`stella scan sarif`).

Acceptance:
- UI downloads match CLI outputs (same schema/version).
- Exports include metadata (digest, scan time, policy profile id).

#### P0-4: Concelier connector truth (reduce ticket load)
- Docs: update FEATURE_MATRIX.md to reflect connector reality (33+ connectors).
- UI: add a “Feeds & Connectors Status” page:
  - list connectors, last success, last error, next scheduled run (if applicable),
  - link to logs and Doctor bundle instructions.
- CLI:
  - `stella db status`
  - `stella db connectors list`
  - `stella db connectors test <name>`

Acceptance:
- Any ingestion failure has a reason code and remediation hint.

---

### P1 (next) — Admin confidence + advanced workflows
These increase operational safety and enterprise readiness without large UI build.

#### P1-1: SBOM lineage CLI parity (UI already exists)
- Add:
  - `stella sbom lineage list`
  - `stella sbom lineage show <id>`
  - `stella sbom lineage export <id> --format json|spdx|cdx`

#### P1-2: VEX operational completeness
- CLI:
  - `stella vex verify <doc>`
  - `stella vex evidence export <digest|component>`
  - `stella vex webhooks list/add/remove`
  - `stella issuer keys list/create/rotate/revoke`
- UI:
  - minimal webhook management screen (list + add/remove),
  - issuer keys page can remain UI-only if already present, but CLI needed for automation.

#### P1-3: Policy debug and portability
- CLI:
  - `stella policy lattice explain ...`
  - `stella policy verdicts export ...`
  - `stella policy promote ...` (if promotion pipeline exists)
- UI:
  - add “download verdict” and “download decision capsule” actions in policy and release views.

#### P1-4: Auth/admin CLI coverage
- Add CLI wrappers for UI-only admin tasks:
  - `stella auth clients list/create/...`
  - `stella auth roles ...`
  - `stella auth scopes list`
  - `stella auth token inspect`
  - `stella auth api-keys ...`

---

### P2 (later) — Nice-to-have / heavy UI
These can be strong, but risk expanding support and UI scope.

- BinaryIndex corpus ingestion UI
- Fingerprint visualization UI
- Evidence holds (legal hold) management UI
- Incident mode workflows and dashboards beyond a basic toggle + export hooks
- Full timeline UI (unless needed for core workflows)

---

## 4) Mapping: discovered gaps -> recommended surfacing

This section is the “agent checklist”.

### Batch 1: SBOM & ingestion
- SPDX 3.0 Build Attestation
  - Class: D (Both) if used for audits; otherwise B (CLI-first)
  - CLI: `stella attest build --format spdx3 --output ...`
  - UI: Export Center adds “Build Attestation (SPDX 3.0)”
- CycloneDX CBOM Support
  - Class: B (CLI-first) + Doc
  - CLI: `stella sbom export --type cbom --format cdx`
- Layer SBOM composition
  - Class: B (CLI-first) + Doc
  - Ensure docs explain when/why layer SBOM is useful (base image triage, provenance).
- SBOM advisory matching
  - Class: A (Automatic) + UI visibility
  - UI: show “matched advisory sources” in SBOM/finding details; doc-only if already visible.
- Graph lineage service (UI exists)
  - Class: B (CLI-first) to match UI
  - CLI: `stella graph lineage show <digest|purl>`
- SBOM validation pipeline / format conversion
  - Class: B (CLI-first)
  - CLI: `stella sbom validate`, `stella sbom convert`
- Trivy DB export (offline)
  - Class: B (CLI-first) + optional UI under Offline Kit
  - UI: optional “download trivy db” action if it reduces ticket load.

### Batch 2: scanning & detection
- Secrets detection, OS analyzers
  - Class: A (Automatic) + Document
  - Update FEATURE_MATRIX.md: “runs during scan; shown in findings”.
- Symbol-level vulnerability matching
  - Class: C (UI-first) if it materially improves triage
  - UI: “Symbol match” tab in finding detail (no heavy workflow).
- SARIF export
  - Class: D (Both)
  - Add UI download.
- Concurrent worker config
  - Class: B (CLI-first)
  - CLI: `stella scanner workers set/get` or `stella scan run --workers N`.

### Batch 3: reachability analysis
- Confidence calculator / EWS explanation
  - Class: D (Both)
  - CLI: `stella score explain`, `stella reachability explain`
  - UI: confidence breakdown and witness.
- Path witness generation
  - Class: C (UI-first) + keep CLI support
  - UI: render witness (Mermaid/GraphViz).
- Runtime signal correlation
  - Class: B (CLI-first) to complement UI
  - CLI: `stella signals inspect <digest|runId>`
- Gate detection (guards)
  - Class: B (CLI-first) + UI is already present
  - CLI: `stella reachability guards <digest>`.

### Batch 4: binary analysis
- Keep CLI-first; avoid UI until demanded.
- Add minimal doc + optional UI download links (export fingerprint result) later.

### Batch 5: advisory sources / Concelier
- Primary action: documentation correction + connector status.
- UI: Feeds & Connectors Status page (P0).
- CLI: connector list/status/test.

### Batch 6: VEX processing
- P1: CLI for verify/evidence export/webhooks/issuer keys.
- UI: minimal webhook mgmt + improve “consensus rationale” explainability.

### Batch 7: policy engine
- P1: CLI lattice explain, verdict export, risk provider config exposure (at least in docs + config validation + Doctor).
- UI: provide download actions; avoid building policy authoring wizard.

### Batch 8: attestation & signing
- Key rotation and trust anchors:
  - Class: B (CLI-first), optionally UI later
  - CLI: `stella keys rotate`, `stella trust-anchors add/list/remove`
- Predicate registry browser:
  - Class: B (CLI-first)
  - CLI: `stella attest predicates list`
- Signer audit logs:
  - Class: B (CLI-first)
  - CLI: `stella sign audit export`.

### Batch 9: regional crypto
- Crypto profiles and plugin health:
  - Class: B (CLI-first)
  - CLI: `stella crypto profiles list/select`, `stella crypto plugins status`
  - Doctor checks required (HSM/PKCS#11 availability, cert chains, etc.)

### Batch 10: evidence & findings
- Audit bundle export:
  - Class: D (Both)
  - CLI: `stella export audit`
  - UI: ensure it’s a first-class export action.
- Evidence holds / incident mode:
  - Class: P2 unless required by early customers; keep as internal or config-only with docs.

### Batch 11: determinism & replay
- HLC inspection, timeline query, scoring explanation:
  - Class: B (CLI-first) for diagnostics
  - CLI: `stella hlc status`, `stella timeline query`, `stella score explain`.

### Batch 12: operations
- Where UI exists but CLI missing:
  - Class: B (CLI-first)
  - Add:
    - `stella orchestrator jobs list/show/retry/cancel`
    - `stella orchestrator deadletter list/show/replay`
    - `stella scheduler preview`

### Batch 13: release orchestration
- (When release orchestration is shipped)
  - Class: D (Both)
  - CLI parity required:
    - `stella release create/promote/rollback`
    - `stella release hooks ...`
    - `stella agent status`

### Batch 14: auth & access control
- Class: B (CLI-first)
- Add admin CLI wrappers for: scopes, clients, roles, api-keys, token inspect.

### Batch 15: notifications & integrations
- UI exists; add CLI for automation/testing:
  - `stella notify channels list/test`
  - `stella notify templates list/render`
  - `stella integrations test`
  - `stella notify preferences export/import`

---

## 5) Documentation requirements (must be done alongside surfacing)

When surfacing a capability:
1) Update FEATURE_MATRIX.md (and the correct category).
2) Update the relevant module dossier (`docs/modules/<module>/architecture.md` or a dedicated guide).
3) Add examples (copy/paste) for CLI usage and for UI navigation paths.
4) If the capability is automatic, document where its output appears.

Also: do not claim “UI support” if it is “API-only”.

---

## 6) Implementation pattern (avoid interface sprawl)

### Preferred UI patterns
- “Download” button for exportable artifacts (SARIF, audit bundle, evidence pack).
- “Inspector” panels inside existing pages (Findings detail, VEX detail, Policy detail).
- One consolidated “Ops” section for status dashboards.
- One consolidated “Integrations” section for connectors and tests.

### Preferred CLI patterns
- Command groups match product nouns:
  - `stella sbom ...`
  - `stella export ...`
  - `stella vex ...`
  - `stella policy ...`
  - `stella auth ...`
  - `stella keys ...`
  - `stella reachability ...`
  - `stella orchestrator ...`
- Every new CLI command must support:
  - `--format json` (machine use)
  - `--output <path>` (CI use)
  - deterministic ordering and stable schemas

---

## 7) Definition of Done (interface surfacing)

For any interface surfacing task:

DOD-1: Feature matrix updated with correct classification (A/B/C/D/E)
DOD-2: CLI/UI path implemented (as required by classification)
DOD-3: Docs updated with copy/paste examples and screenshots where appropriate
DOD-4: Doctor coverage added if failures are environment-dependent
DOD-5: Determinism tests added if outputs are exported/signed/hashed
DOD-6: Reason codes and explainability exist for decision-related features

---

## 8) Immediate next sprints (recommended)

1) P0 exports completeness: Export Center + `stella export ...` standardization
2) P0 explainability: witness path UI + `stella score explain`
3) P0 SARIF UI download
4) P0 Feeds/connectors status UI + CLI
5) P1 SBOM lineage CLI parity
6) P1 VEX verify/evidence export + webhooks mgmt
7) P1 Policy debug + verdict export
8) P1 Admin CLI (auth/keys/crypto profiles)

Archive this advisory only when superseded by a newer interface strategy directive.


---
Here’s a tight UX spec you can drop into Stella Ops to make “proof‑first” triage obvious and quiet by default.

# Triage Card (Signed Evidence Card)

* **Purpose:** Show one issue = one verifiable proof bundle.
* **Header:** vuln id + package@version + scope (image/layer/path). Right side: **Risk chip** (score + reason).
* **One‑click “Rekor Verify”:** Runs DSSE/Sigstore verify and expands to show:

  * ✅ signature subject/issuer, ✅ timestamp, ✅ Rekor index + raw entry (copyable), ✅ digest(s).
* **Evidence chips:** OpenVEX status (affected/not_affected), patch proof (binary/backport), reachability (stack path), EPSS band.
* **Actions:** “Explain” (AI note), “Create task,” “Mute (reasoned),” “Export evidence (.dsse)”.
* **Micro‑interactions:**

  * Hover on chips → mini‑tooltip with why.
  * Copy icons on digests/Rekor IDs.
  * Keyboard shortcuts: `v` verify, `e` export, `m` mute.

# Binary‑Diff Panel

* **Purpose:** Prove fixes at the **binary** level, not just SBOM claims.
* **Scope selector:** `file → section → function`.
* **Layers:** Base vs candidate (or pre‑ vs post‑patch) with inline diff.
* **Hashes:** Per‑file SHA‑256, per‑section, per‑function rolling hashes.
* **Context:** CWE + symbol names, addresses, and relocation notes.
* **Artifacts:**

  * **Export “Signed Diff”** → DSSE envelope (hash map + metadata + signer + timestamp).
  * Attach to the triage card as “Patch proof”.
* **Micro‑interactions:**

  * Click on symbol in call‑graph to jump to function diff.
  * Toggle opcodes ⇄ decompiled view (if available).
  * “Show only changed blocks” toggle.

# Quiet/Accessible Filter Strip

* **Purpose:** Deterministic, low‑noise prioritization—no casino lights.
* **Precedence toggles (left→right strongest to weakest):**

  1. **OpenVEX** (not_affected/affected)
  2. **Patch proof present**
  3. **Reachability** (call‑path to runtime)
  4. **EPSS** (≥ threshold)
* **Determinism:** When ties occur, sort by OCI digest, then path, then CVSS.
* **Controls:**

  * EPSS slider; “Only reachable” checkbox; “Only with patch proof” checkbox.
  * “Deterministic order” lock icon (on by default).
* **A11y:** High‑contrast theme, focus rings, full keyboard nav, prefers‑reduced‑motion honored; all chips have aria‑labels.
* **Micro‑interactions:** Filters update counts without reflow; announcement region reads changes.

---

## Why this matters

* **Trustable triage:** Users see cryptographic evidence (signatures, Rekor entries, per‑function hashes), not just scanner claims.
* **Noise‑free:** Precedence rules (OpenVEX → patch proof → reachability → EPSS) cut alert fatigue predictably.
* **Audit‑ready:** Every click can emit an exportable **DSSE‑signed** artifact for tickets, audits, and vendors.

---

## Minimal data model additions

* `EvidencePacket { sbom_ref, dsse_envelope, rekor_index, signer, timestamp }`
* `BinaryProof { file_hashes[], section_hashes[], function_hashes[], diff_summary }`
* `TriageMeta { openvex_status, reachability_path[], epss_score, precedence_tuple }`

---

## Done‑means‑Done checks

* Triage card verify shows **raw Rekor JSON** + signature details.
* Binary‑diff export produces a DSSE file that re‑verifies offline.
* Filter strip yields identical ordering given the same inputs (golden test).
* Keyboard‑only usage covers: open card, verify, export, toggle filters, navigate diffs.

Want me to turn this into three Figma‑ready wireframes (with exact layout specs and aria‑labels), or generate sample DSSE envelopes + Rekor verify outputs so your team can test end‑to‑end?

--
Here’s a tight, practical first pass for a **“doctor” setup wizard** that runs right after install and anytime from Settings → Diagnostics. It gives instant confidence that Stella Ops is wired correctly, without needing full integrations configured.

---

# What the “doctor” does (in plain terms)

It runs a few lightweight health checks to confirm your system can:

* talk to its database,
* reach its attestation store (for signed proofs),
* verify a sample artifact end‑to‑end (SBOM + VEX).

If these pass, your install is sound and you can add integrations later at your pace.

---

# Mandatory checks (first pass)

1. **DB connectivity + schema version**

* **Why**: If the DB is unreachable or the schema is outdated, nothing else matters.
* **Checks**:

  * TCP/connect to Postgres URI.
  * `SELECT 1;` liveness.
  * Read `schema_version` from `stella.meta` (or your flyway/liquibase table).
  * Compare to the app’s expected version; warn if migrations pending.
* **CLI sketch**:

  ```bash
  stella doctor db \
    --url "$STELLA_DB_URL" \
    --expect-schema "2026.01.0"
  ```
* **Pass criteria**: reachable + current (or actionable “run migrations” hint).

2. **Attestation store availability (Rekor/Cosign)**

* **Why**: Stella relies on signed evidence; if the ledger/store isn’t reachable, you can’t prove integrity.
* **Checks**:

  * Resolve/HTTP 200 for Rekor base URL (or your mirror).
  * Cosign key material present (KMS, keyless, or offline bundle).
  * Clock skew sanity (<5s) for signature verification.
* **CLI sketch**:

  ```bash
  stella doctor attest \
    --rekor-url "$STELLA_REKOR_URL" \
    --cosign-key "$STELLA_COSIGN_KEY" \
    --mode "online|offline"
  ```
* **Pass criteria**: ledger reachable (or offline bundle found) + keys valid.

3. **Artifact verification pipeline run (SBOM + VEX sample)**

* **Why**: Proves the *whole* trust path works—fetch, verify, evaluate policy.
* **Checks**:

  * Pull a tiny, known test artifact by **digest** (immutable).
  * Verify signature/attestations (DSSE in Rekor or offline bundle).
  * Fetch/validate **SBOM** (CycloneDX/SPDX) and a sample **VEX**.
  * Run policy engine: “no‑go if critical vulns without VEX justification.”
* **CLI sketch**:

  ```bash
  stella doctor verify \
    --artifact "oci://registry.example/test@sha256:deadbeef..." \
    --require-sbom \
    --require-vex
  ```
* **Pass criteria**: signature + SBOM + VEX validate; policy engine returns ✅.

---

# Output & UX

* **One‑screen summary** with green/yellow/red statuses and terse fixes.
* **Copy‑paste remediations** (DB URI example, Rekor URL, cosign key path).
* **Evidence links** (e.g., “View attestation entry” or “Open policy run”).
* **Export**: `stella doctor --json > doctor-report.json` for support.

---

# Where this fits in the installer/wizard

* **UI & CLI** both follow the same steps:

  1. DB setup → quick migration → **Doctor: DB**
  2. Choose attestation mode (Rekor/cosign keyless/offline bundle) → **Doctor: Attest**
  3. Minimal “verification pipeline” config (test registry creds or bundled sample) → **Doctor: Verify**
* Each step has **defaults** (Postgres + Rekor URL + bundled demo artifact) and a **“Skip for now”** with a reminder tile in Settings → Integrations.

---

# Failure → Suggested fixes (examples)

* **DB schema mismatch** → “Run `stella migrate up` to 2026.01.0.”
* **Rekor unreachable** → “Check DNS/proxy; or switch to Offline Attestations in Settings.”
* **Cosign key missing** → “Add key (KMS/file) or enable keyless; see Keys → Add.”
* **SBOM/VEX missing** → “Enable ‘Generate SBOM on build’ and ‘Collect VEX from vendors’, or load a demo bundle.”

---

# Next steps (beyond first pass)

* Optional checks the wizard can add later:

  * **Registry** reachability (pull by digest).
  * **Settings store** (Valkey cache reachability).
  * **Notifications** (send test webhook/email).
  * **SCM/Vault/LDAP** plugin stubs: ping + auth flow (but not required to pass install).

If you want, I can turn this into:

* a ready‑to‑ship **CLI command spec**,
* a **UI wireframe** of the three-step doctor,
* or **JSON schemas** for the doctor’s machine‑readable report.