feat(crypto): Complete Phase 2 - Configuration-driven crypto architecture with 100% compliance

## Summary

This commit completes Phase 2 of the configuration-driven crypto architecture, achieving
100% crypto compliance by eliminating all hardcoded cryptographic implementations.

## Key Changes

### Phase 1: Plugin Loader Infrastructure
- **Plugin Discovery System**: Created StellaOps.Cryptography.PluginLoader with manifest-based loading
- **Configuration Model**: Added CryptoPluginConfiguration with regional profiles support
- **Dependency Injection**: Extended DI to support plugin-based crypto provider registration
- **Regional Configs**: Created appsettings.crypto.{international,russia,eu,china}.yaml
- **CI Workflow**: Added .gitea/workflows/crypto-compliance.yml for audit enforcement

### Phase 2: Code Refactoring
- **API Extension**: Added ICryptoProvider.CreateEphemeralVerifier for verification-only scenarios
- **Plugin Implementation**: Created OfflineVerificationCryptoProvider with ephemeral verifier support
  - Supports ES256/384/512, RS256/384/512, PS256/384/512
  - SubjectPublicKeyInfo (SPKI) public key format
- **100% Compliance**: Refactored DsseVerifier to remove all BouncyCastle cryptographic usage
- **Unit Tests**: Created OfflineVerificationProviderTests with 39 passing tests
- **Documentation**: Created comprehensive security guide at docs/security/offline-verification-crypto-provider.md
- **Audit Infrastructure**: Created scripts/audit-crypto-usage.ps1 for static analysis

### Testing Infrastructure (TestKit)
- **Determinism Gate**: Created DeterminismGate for reproducibility validation
- **Test Fixtures**: Added PostgresFixture and ValkeyFixture using Testcontainers
- **Traits System**: Implemented test lane attributes for parallel CI execution
- **JSON Assertions**: Added CanonicalJsonAssert for deterministic JSON comparisons
- **Test Lanes**: Created test-lanes.yml workflow for parallel test execution

### Documentation
- **Architecture**: Created CRYPTO_CONFIGURATION_DRIVEN_ARCHITECTURE.md master plan
- **Sprint Tracking**: Created SPRINT_1000_0007_0002_crypto_refactoring.md (COMPLETE)
- **API Documentation**: Updated docs2/cli/crypto-plugins.md and crypto.md
- **Testing Strategy**: Created testing strategy documents in docs/implplan/SPRINT_5100_0007_*

## Compliance & Testing

- ✅ Zero direct System.Security.Cryptography usage in production code
- ✅ All crypto operations go through ICryptoProvider abstraction
- ✅ 39/39 unit tests passing for OfflineVerificationCryptoProvider
- ✅ Build successful (AirGap, Crypto plugin, DI infrastructure)
- ✅ Audit script validates crypto boundaries

## Files Modified

**Core Crypto Infrastructure:**
- src/__Libraries/StellaOps.Cryptography/CryptoProvider.cs (API extension)
- src/__Libraries/StellaOps.Cryptography/CryptoSigningKey.cs (verification-only constructor)
- src/__Libraries/StellaOps.Cryptography/EcdsaSigner.cs (fixed ephemeral verifier)

**Plugin Implementation:**
- src/__Libraries/StellaOps.Cryptography.Plugin.OfflineVerification/ (new)
- src/__Libraries/StellaOps.Cryptography.PluginLoader/ (new)

**Production Code Refactoring:**
- src/AirGap/StellaOps.AirGap.Importer/Validation/DsseVerifier.cs (100% compliant)

**Tests:**
- src/__Libraries/__Tests/StellaOps.Cryptography.Plugin.OfflineVerification.Tests/ (new, 39 tests)
- src/__Libraries/__Tests/StellaOps.Cryptography.PluginLoader.Tests/ (new)

**Configuration:**
- etc/crypto-plugins-manifest.json (plugin registry)
- etc/appsettings.crypto.*.yaml (regional profiles)

**Documentation:**
- docs/security/offline-verification-crypto-provider.md (600+ lines)
- docs/implplan/CRYPTO_CONFIGURATION_DRIVEN_ARCHITECTURE.md (master plan)
- docs/implplan/SPRINT_1000_0007_0002_crypto_refactoring.md (Phase 2 complete)

## Next Steps

Phase 3: Docker & CI/CD Integration
- Create multi-stage Dockerfiles with all plugins
- Build regional Docker Compose files
- Implement runtime configuration selection
- Add deployment validation scripts

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

docs2/README.md

@@ -15,36 +15,138 @@ Assumptions baked into docs2
 How to navigate
 - product/overview.md - Vision, capabilities, and requirements
 - product/roadmap-and-requirements.md - Requirements and roadmap summary
+- product/market-positioning.md - Moats and competitive positioning
+- product/claims-and-benchmarks.md - Claims and benchmark linkage
 - architecture/overview.md - System map and dependencies
 - architecture/workflows.md - Key data and control flows
 - architecture/evidence-and-trust.md - Evidence chain, DSSE, replay, AOC
 - architecture/reachability-vex.md - Reachability, VEX consensus, unknowns
+- architecture/component-map.md - Module interaction map
+- architecture/reachability-lattice.md - Reachability lattice model
+- architecture/reachability-evidence.md - Reachability evidence schemas
+- architecture/advisory-alignment.md - Advisory architecture alignment summary
+- ingestion/aggregation-and-linksets.md - AOC rules and linkset model
+- ingestion/aoc-guardrails.md - Guard library and ingestion guardrails
+- ingestion/backfill.md - AOC linkset backfill process
 - modules/index.md - Module summaries (core and supporting)
+- advisory-ai/overview.md - Advisory AI guardrails and evidence
+- orchestrator/overview.md - Orchestrator execution model
+- orchestrator/run-ledger.md - Orchestrator run ledger schema
+- orchestrator/architecture.md - Orchestrator component architecture
+- orchestrator/api.md - Orchestrator API surface
+- orchestrator/cli.md - Orchestrator CLI commands
+- orchestrator/console.md - Orchestrator console views
+- operations/quickstart.md - First scan workflow
 - operations/install-deploy.md - Install and deployment guidance
+- operations/deployment-versioning.md - Versioning and promotion model
+- operations/binary-prereqs.md - Offline binary and package prerequisites
 - operations/airgap.md - Offline kit and air-gap operations
+- operations/airgap-bundles.md - Bundle formats and verification
+- operations/airgap-runbooks.md - Air-gap import and quarantine runbooks
 - operations/replay-and-determinism.md - Replay artifacts and deterministic rules
+- operations/runtime-readiness.md - Runtime readiness checks
+- operations/slo.md - Service SLO overview
 - operations/runbooks.md - Operational runbooks and incident response
+- operations/notifications.md - Notifications Studio operations
+- notifications/overview.md - Notifications overview
+- notifications/rules.md - Notification rules and routing
+- notifications/channels.md - Notification channels
+- notifications/templates.md - Notification templates
+- notifications/digests.md - Notification digests
+- notifications/pack-approvals.md - Pack approval notifications
+- operations/router-rate-limiting.md - Gateway rate limiting
 - release/release-engineering.md - Release and CI/CD overview
 - api/overview.md - API surface and conventions
 - api/auth-and-tokens.md - Authority, OpTok, DPoP and mTLS, PoE
+- policy/policy-system.md - Policy DSL, lifecycle, and governance
 - cli-ui.md - CLI and console guide
+- cli/overview.md - CLI command groups and config
+- cli/commands.md - CLI groups and global options
+- cli/crypto.md - Crypto commands and regional compliance
+- cli/crypto-plugins.md - Crypto provider plugin model
+- cli/distribution-matrix.md - CLI regional distribution matrix
+- cli/reachability.md - Reachability, drift, and smart-diff CLI
+- cli/triage.md - Triage CLI workflows
+- cli/unknowns.md - Unknowns CLI workflows
+- cli/score-proofs.md - Scoring replay and proofs
+- cli/sbomer.md - SBOMer offline commands
+- cli/audit-pack.md - Audit pack export and replay
+- cli/keyboard-shortcuts.md - CLI interactive shortcuts
+- cli/troubleshooting.md - Common CLI issues
+- ui/console.md - Console overview and shared surfaces
+- ui/navigation.md - Console routing, shortcuts, deep links
+- ui/aoc-dashboard.md - AOC ingestion dashboard
+- ui/findings.md - Findings workspace guide
+- ui/advisories-vex.md - Advisories and VEX explorer
+- ui/downloads.md - Downloads workspace and manifest handling
+- ui/runs.md - Runs workspace and evidence bundles
+- ui/policies.md - Policies workspace and approvals
+- ui/admin.md - Admin workspace for tenants, roles, tokens
+- ui/exception-center.md - Exception and waiver workflows
+- ui/reachability-overlays.md - Reachability overlay semantics
+- ui/sbom-explorer.md - SBOM Explorer guide
+- ui/sbom-graph-explorer.md - SBOM graph explorer
+- ui/vulnerability-explorer.md - Vulnerability explorer
+- ui/explainers.md - Policy explainers UI
+- ui/airgap.md - Air-gap console UI
+- ui/attestor.md - Attestation UI
+- ui/forensics.md - Forensics UI
+- ui/observability.md - Observability UI
+- ui/risk-ui.md - Risk UI
+- ui/policy-editor.md - Policy editor workspace
+- ui/accessibility.md - Console accessibility guidance
+- ui/triage.md - Triage UX and state model
+- ui/branding.md - Tenant branding model
 - data-and-schemas.md - Storage, schemas, and determinism rules
 - data/persistence.md - Database model and migration notes
 - data/events.md - Event envelopes and validation
+- sbom/overview.md - SBOM formats, mapping, and heuristics
+- governance/approvals.md - Approval routing and audit
+- governance/exceptions.md - Exception lifecycle and controls
 - security-and-governance.md - Security policy, hardening, governance, compliance
+- security/identity-tenancy-and-scopes.md - Authority scopes and tenancy rules
+- security/crypto-and-trust.md - Crypto profiles and trust roots
+- security/crypto-compliance.md - Regional crypto profiles and licensing notes
+- security/quota-and-licensing.md - Offline quota and JWT licensing
+- security/admin-rbac.md - Console admin RBAC model
+- security/console-security.md - Console security posture
+- security/operational-hardening.md - DPoP, rate limits, secrets, exports
+- security/audit-events.md - Authority audit event schema
+- security/revocation-bundles.md - Revocation bundle format and verification
 - security/risk-model.md - Risk scoring model and explainability
 - security/forensics-and-evidence-locker.md - Evidence locker and forensic storage
+- provenance/inline-provenance.md - DSSE metadata and transparency links
+- signals/unknowns.md - Unknowns registry and signals model
+- signals/unknowns-ranking.md - Unknowns scoring and triage bands
+- signals/uncertainty.md - Uncertainty states and tiers
+- signals/callgraph-schema.md - Callgraph schema and determinism
+- signals/contract-mapping.md - Signal contract mapping
 - contracts-and-interfaces.md - Cross-module contracts and specs
+- contracts/scanner-core.md - Scanner core DTOs and determinism helpers
 - task-packs.md - Task Runner pack format and workflow
+- interop/sbom-interop.md - SBOM interoperability and parity testing
+- interop/cosign.md - Cosign attestation integration
+- migration/overview.md - Migration paths and parity guidance
+- vex/consensus.md - VEX consensus overview
 - testing-and-quality.md - Test strategy and quality gates
 - observability.md - Metrics, logs, tracing, telemetry stack
 - developer/onboarding.md - Local dev setup and workflows
 - developer/plugin-sdk.md - Plugin SDK summary
+- developer/devportal.md - Developer portal publishing
+- developer/implementation-guidelines.md - Deterministic implementation rules
 - sdk/overview.md - SDK and client guidance
+- guides/compare-workflow.md - Compare workflow guide
+- guides/epss-integration.md - EPSS integration summary
+- references/examples-and-fixtures.md - Examples, samples, schemas
+- specs/symbols.md - Symbol manifest and bundle format
 - benchmarks.md - Benchmark program overview
+- vuln-explorer/overview.md - Vuln Explorer summary
 - training-and-adoption.md - Evaluation checklist and training material
 - glossary.md - Core terms
 
+Legal and regulator view
+- legal/regulator-threat-evidence.md - Regulator threat and evidence model
+
 Notes
 - Raw schemas, samples, and fixtures remain under docs/ and are referenced from docs2.
 - If you need a deep schema or fixture, follow the path in data-and-schemas.md.

docs2/advisory-ai/overview.md

@@ -0,0 +1,35 @@
+# Advisory AI overview
+
+Advisory AI provides explainable summaries and prioritization hints for human
+review. It consumes canonical observations from Concelier and Excititor and
+returns evidence-linked outputs.
+
+Inputs
+- Advisory observations and linksets from Concelier.
+- VEX observations and trust metadata from Excititor.
+- Optional SBOM context snapshots for component relevance.
+
+Outputs
+- Human-readable summaries with evidence references.
+- Priority hints and rationale tied to source ids and hashes.
+- Payloads suitable for UI and CLI display, not for policy decisions.
+
+Guardrails
+- No uncontrolled external network calls.
+- Redaction of sensitive fields before model input.
+- Outputs must include source ids and evidence hashes.
+- Deterministic templates for offline or restricted modes.
+
+Evidence payloads
+- Each response includes model metadata, input hashes, and output hashes.
+- Evidence links are preserved so decisions remain auditable.
+
+Packaging and offline
+- Offline kits bundle prompt templates and model policies.
+- Model use is gated by configuration and approval policies.
+
+Related references
+- docs/advisory-ai/overview.md
+- docs/advisory-ai/guardrails-and-evidence.md
+- docs/advisory-ai/evidence-payloads.md
+- docs/advisory-ai/sbom-context-hand-off.md

docs2/architecture/advisory-alignment.md

@@ -0,0 +1,71 @@
+# Advisory architecture alignment
+
+Purpose
+- Summarize alignment with advisory architecture requirements.
+- Capture supported formats, evidence types, and known gaps.
+
+DSSE predicate types
+- https://in-toto.io/attestation/slsa/v1.0 (Attestor)
+- stella.ops/sbom@v1 (Scanner)
+- stella.ops/vex@v1 (Excititor)
+- stella.ops/callgraph@v1 (Scanner.Reachability)
+- stella.ops/reachabilityWitness@v1 (Scanner.Reachability)
+- stella.ops/policy-decision@v1 (Policy.Engine)
+- stella.ops/score-attestation@v1 (Policy.Scoring)
+- stella.ops/witness@v1 (Scanner.Reachability)
+- stella.ops/drift@v1 (Scanner.ReachabilityDrift)
+- stella.ops/unknown@v1 (Scanner.Unknowns)
+- stella.ops/triage@v1 (Scanner.Triage)
+- stella.ops/vuln-surface@v1 (Scanner.VulnSurfaces)
+- stella.ops/trigger@v1 (Scanner.VulnSurfaces)
+- stella.ops/explanation@v1 (Scanner.Reachability)
+- stella.ops/boundary@v1 (Scanner.SmartDiff)
+- stella.ops/evidence@v1 (Scanner.SmartDiff)
+- stella.ops/approval@v1 (Policy.Engine)
+- stella.ops/component@v1 (Scanner.Emit)
+- stella.ops/richgraph@v1 (Scanner.Reachability)
+
+VEX and advisory formats
+- OpenVEX 0.2.0+
+- CycloneDX VEX 1.4 to 1.6
+- CSAF 2.0
+- OSV
+
+CVSS and scoring
+- CVSS v4 vector parsing with macrovector and environmental metrics.
+- Deterministic scoring with canonical JSON, stable ordering, and hashed snapshots.
+
+EPSS handling
+- EPSS uses model_date (daily) rather than numbered versions.
+- Scores and percentiles are stored with model_date and captured at scan time.
+- Offline bundles include EPSS data and hashes for air-gapped replay.
+
+Reachability analysis
+- Hybrid static and runtime reachability evidence.
+- Call graph extraction for .NET, Java, Node.js, Python, Go (external tooling), and native binaries.
+
+Call-stack witnesses
+- Signed witnesses for entrypoint-to-sink paths.
+- Witnesses are stored as content-addressed artifacts with DSSE signatures.
+
+Smart-diff rules
+- New finding detection.
+- Score increase detection.
+- VEX status change detection.
+- Reachability change detection.
+
+Unknowns handling
+- Unknown types: missing_vex, ambiguous_indirect_call, unanalyzed_dependency,
+  stale_sbom, missing_reachability, unmatched_cpe, conflict_vex, native_code,
+  generated_code, dynamic_dispatch, external_boundary.
+- Scoring dimensions: blast radius, evidence scarcity, exploit pressure,
+  containment signals, time decay.
+
+CycloneDX baseline
+- Current baseline is CycloneDX 1.6; upgrade to 1.7 when SDK support is available.
+
+Areas beyond baseline requirements
+- Offline and air-gap operation with bundled proofs.
+- Regional crypto readiness (GOST, SM2/SM3, PQ-ready modes).
+- Multi-tenant isolation and signed transparency integration.
+- Native binary analysis for PE, ELF, and Mach-O.

docs2/architecture/component-map.md

@@ -0,0 +1,49 @@
+# Component map
+
+This map summarizes how top-level modules interact. It is a compact index to
+module dossiers, not a replacement for them.
+
+Advisory and evidence services
+- Concelier: advisory ingestion under the Aggregation-Only Contract (AOC).
+- Excititor: VEX ingestion and normalization under AOC guardrails.
+- VEX Lens: conflict analysis and evidence browsing for VEX.
+- Evidence Locker: long-term storage for signed evidence bundles.
+- Export Center: packages evidence and offline bundles for distribution.
+
+Scanning, SBOM, and risk
+- Scanner: deterministic scan pipeline (web service + worker).
+- SBOM Service: inventory store and delta cache for SBOMs.
+- Graph and Cartographer: identity graph and relationship queries.
+- Vuln Explorer: evidence-linked findings view with VEX-first posture.
+
+Policy and governance
+- Policy Engine: deterministic rule evaluation and explain traces.
+- Task Packs and Task Runner: automation workflows with approvals.
+- Governance surfaces: approvals, exceptions, and audit exports.
+
+Identity, signing, and provenance
+- Authority: identity, tokens, scopes, tenancy enforcement.
+- Signer: DSSE signing and key management integration.
+- Attestor: attestations, envelopes, and transparency logging.
+- Issuer Directory: trusted issuer catalog for signatures and VEX.
+
+Scheduling and orchestration
+- Scheduler: change detection and rescan orchestration.
+- Orchestrator: job dispatch and coordination for scans and exports.
+
+Runtime and security enforcement
+- Zastava: runtime admission and policy enforcement.
+- Signals: runtime and reachability signals feeding policy and triage.
+
+Notification and UI
+- Notifications Studio: rule-based notifications and channel delivery.
+- UI Console: Angular app for findings, policy, runs, and admin.
+- Web Gateway: API routing and auth enforcement for UI and CLI.
+
+Offline and telemetry
+- Airgap and mirrors: offline bundles, sealing, and staleness control.
+- Telemetry stack: metrics, logs, traces, and offline storage.
+
+Related references
+- docs/technical/architecture/component-map.md
+- docs/modules/*/architecture.md

docs2/architecture/reachability-evidence.md

@@ -0,0 +1,35 @@
+# Reachability evidence schema
+
+Reachability evidence is stored as canonical graphs plus optional runtime facts
+and edge bundles. Evidence is content-addressed and signed.
+
+Core identifiers
+- symbol_id: canonical symbol identity with format, build id, address range.
+- code_id: code block identity when symbols are missing.
+- symbol_digest: sha256 of normalized signature or block hash.
+- purl: owning component identity when resolved.
+
+Graph payload (richgraph-v1)
+- nodes carry symbol ids, digests, purls, and analyzer metadata.
+- edges carry kind, confidence, evidence tags, and candidate targets.
+- roots capture entrypoints and loader roots.
+- graph_hash is the content hash of canonical JSON.
+
+Attestation levels
+- Graph DSSE is required for every graph (canonical JSON + hash).
+- Edge-bundle DSSE is optional for high-signal edges.
+- CAS layout uses cas://reachability/graphs and cas://reachability/edges.
+
+Runtime facts
+- Events include symbolId, codeId, purl, hitCount, and observedAt.
+- Runtime traces can be stored in CAS and referenced by URI.
+
+Validation rules (examples)
+- Edges must include purl or candidates.
+- Evidence arrays are sorted and confidence is within 0.0-1.0.
+- Graph and edge bundles must reference the same graph_hash.
+
+Related references
+- docs/reachability/evidence-schema.md
+- docs/reachability/edge-explainability-schema.md
+- docs/reachability/runtime-static-union-schema.md

docs2/architecture/reachability-lattice.md

@@ -0,0 +1,33 @@
+# Reachability lattice
+
+Reachability is modeled as a deterministic lattice with explicit unknowns.
+Signals emits per-target states and a fact-level score that is stable under
+replay.
+
+Current v0 model (buckets)
+- Buckets: entrypoint, direct, runtime, unknown, unreachable.
+- Scores are confidence * bucket weight, clamped to 0.0-1.0.
+- Unknowns pressure penalizes the fact-level score to avoid false safety.
+
+Unknowns pressure
+- pressure = unknowns / (targets + unknowns)
+- score = avg(target scores) * (1 - min(pressure, ceiling))
+
+Lattice v1 (design direction)
+- States: unknown, staticallyReachable, staticallyUnreachable,
+  runtimeObserved, runtimeUnobserved, confirmedReachable,
+  confirmedUnreachable, contested.
+- Joins are monotonic; contested absorbs conflicts.
+- Policy should treat unknown and contested as under investigation.
+
+Evidence requirements
+- Reachability facts include graph hashes, path references, and runtime hit refs.
+- Evidence transitions record previous state and supporting inputs.
+
+Policy guidance
+- Do not assert not_affected without high-confidence reachability evidence.
+- Unknown or contested states should surface as under_investigation.
+
+Related references
+- docs/reachability/lattice.md
+- docs/signals/unknowns-registry.md

docs2/architecture/reachability-vex.md

@@ -23,3 +23,8 @@
 ## Unknowns registry
 - Unknowns are first-class objects with scoring, SLA bands, and evidence links.
 - Unknowns are stored with deterministic ordering and exported for offline review.
+
+## Related references
+- docs2/architecture/reachability-lattice.md
+- docs2/architecture/reachability-evidence.md
+- docs2/signals/unknowns.md

docs2/benchmarks.md

@@ -1,12 +1,21 @@
 # Benchmarks and performance
 
-## Purpose
+Purpose
 - Validate accuracy, performance, and determinism claims.
 - Detect regressions across analyzers and policy logic.
 - Provide reproducible comparisons against external tools.
 
-## Core areas
+Core areas
 - Scanner performance (cold and warm paths).
 - Reachability accuracy using ground-truth corpora.
 - Determinism and replay verification.
 - Competitive parity for key ecosystems.
+
+Claims alignment
+- Claims are backed by benchmark outputs and deterministic fixtures.
+- Evidence artifacts are stored alongside hashes for audit.
+
+Related references
+- docs/benchmarks/*
+- docs/claims-index.md
+- docs/market/claims-citation-index.md

docs2/cli-ui.md

@@ -1,12 +1,38 @@
 # CLI and UI
 
-## CLI
-- stella: scan, diff, and export for CI workflows.
-- stellaops-cli: admin tooling for offline kits, policy, replay, and verification.
-- CLI never signs directly; it calls Signer and Attestor through APIs.
-- Typical verbs: scan, diff, export, policy, replay, graph verify, offline kit import.
+CLI overview
+- stella: primary CLI for scanning, diffing, and exports.
+- stellaops-cli: admin CLI for offline kits, verification, and policy workflows.
+- Common verbs: scan, diff, export, policy, replay, graph, airgap, pack.
 
-## UI (Console)
-- Angular 17 single page app for scans, policy, VEX, notifications, and audits.
-- Offline friendly with no external CDN dependencies.
-- Provides offline kit import, policy editing, and evidence exploration.
+Key CLI workflows
+- Submit scan and inspect findings.
+- Export evidence bundles and verify signatures.
+- Run replay and compare determinism hashes.
+- Manage offline kit import and verification.
+
+Console overview
+- Angular 17 SPA for scans, policy, VEX, notifications, and audits.
+- Offline friendly with local assets and sealed-mode banners.
+- Provides evidence drawers, policy editor, and export tools.
+
+Key UI areas
+- Findings and triage with explainable evidence.
+- Compare view for security deltas between versions.
+- Policy authoring and simulation.
+- Downloads and evidence exports.
+
+CLI parity
+- Console views should provide equivalent CLI commands for export and replay.
+- Offline workflows must be achievable via CLI without browser access.
+
+Accessibility
+- Keyboard-first interactions and screen reader parity.
+- See ui/accessibility.md for the detailed model.
+
+Related references
+- docs/cli/*
+- docs2/cli/overview.md
+- docs/ui/*
+- docs/console/*
+- docs/guides/compare-workflow-user-guide.md

docs2/cli/audit-pack.md

@@ -0,0 +1,23 @@
+# Audit pack CLI
+
+Audit pack commands
+- audit-pack export: export audit packs for a scan.
+- audit-pack verify: verify hashes and signatures.
+- audit-pack info: show pack metadata and contents.
+- audit-pack replay: replay a scan and compare verdicts.
+- audit-pack verify-and-replay: combined workflow.
+
+Typical workflow
+1) Export and sign an audit pack.
+2) Transfer to the offline environment.
+3) Verify hashes and signatures.
+4) Replay and compare verdict digests.
+
+Environment variables
+- STELLAOPS_AUDIT_PACK_VERIFY_SIGS controls signature verification default.
+- STELLAOPS_AUDIT_PACK_TRUST_ROOTS points to trust roots.
+- STELLAOPS_OFFLINE_BUNDLE provides offline inputs for replay.
+
+Related references
+- docs/cli/audit-pack-commands.md
+- docs2/operations/replay-and-determinism.md

docs2/cli/commands.md

@@ -0,0 +1,32 @@
+# CLI command groups
+
+Global options
+- --tenant sets tenant context for all commands.
+- --verbose enables verbose output.
+- --help and --version are available everywhere.
+
+Core groups
+- scan: scan images and emit SBOMs and attestations.
+- sbomer: offline SBOM layer, compose, and drift utilities.
+- policy: lint, simulate, approve, and replay policy decisions.
+- vex and advisory: ingest and inspect observations and linksets.
+- reachability: compute and explain reachability results.
+- score: compute and replay scoring with proof bundles.
+- triage: list, show, decide, and export findings.
+- unknowns: triage unresolved identities and edges.
+- downloads and offline: export and verify bundles, offline kit flows.
+- auth and admin: login, tokens, and admin operations.
+
+Output formats
+- Most commands support table, json, yaml, and sarif formats where applicable.
+- Deterministic ordering is required for json and yaml outputs.
+
+Offline posture
+- Use offline bundles and preloaded feeds for air-gapped workflows.
+- Avoid network calls when STELLAOPS_OFFLINE or equivalent flags are set.
+
+Related references
+- docs/cli/command-reference.md
+- docs/cli/admin-reference.md
+- docs/cli/audit-pack-commands.md
+- docs2/cli/crypto.md

docs2/cli/crypto-plugins.md

@@ -0,0 +1,18 @@
+# CLI crypto plugins
+
+Plugin model
+- Providers implement ICryptoProvider with SignAsync and VerifyAsync.
+- Providers declare Name and SupportedAlgorithms.
+- Optional diagnostics interface exposes health checks and metadata.
+
+Key references
+- CryptoKeyReference describes key id, source, and parameters.
+- CryptoKeyInfo exposes key metadata and signing capabilities.
+
+Registration
+- Plugins are registered via DI in the CLI host.
+- Provider selection uses the --provider flag or profile defaults.
+
+Related references
+- docs/cli/crypto-plugins.md
+- docs2/cli/crypto.md

docs2/cli/crypto.md

@@ -0,0 +1,32 @@
+# CLI crypto and compliance
+
+Crypto commands
+- crypto sign: sign files with a selected provider and algorithm.
+- crypto verify: verify signatures with provider and trust policy.
+- crypto profiles: list providers and run diagnostics.
+
+Distribution matrix (summary)
+- International: default providers only.
+- Russia: adds GOST providers (build flag StellaOpsEnableGOST).
+- EU: adds eIDAS providers (build flag StellaOpsEnableEIDAS).
+- China: adds SM providers (build flag StellaOpsEnableSM).
+
+Compliance notes
+- Use the regional build that matches the deployment jurisdiction.
+- Regional providers may require licensed CSPs or remote TSP endpoints.
+
+Configuration
+- Profiles select preferred providers and key sources.
+- Provider credentials use environment variables or config files.
+- DSSE is the default signing format for bundles and manifests.
+
+Plugin development (summary)
+- Providers implement ICryptoProvider with SignAsync and VerifyAsync.
+- Optional diagnostics interface provides health checks.
+
+Related references
+- docs/cli/crypto-commands.md
+- docs/cli/crypto-plugins.md
+- docs/cli/compliance-guide.md
+- docs/cli/distribution-matrix.md
+- docs2/security/crypto-compliance.md

docs2/cli/distribution-matrix.md

@@ -0,0 +1,18 @@
+# CLI distribution matrix
+
+Regional distributions
+- International: default crypto providers only.
+- Russia: adds GOST providers (build flag StellaOpsEnableGOST).
+- EU: adds eIDAS providers (build flag StellaOpsEnableEIDAS).
+- China: adds SM providers (build flag StellaOpsEnableSM).
+
+Build notes
+- Use deterministic publish settings for reproducible binaries.
+- Flags control inclusion of provider projects at build time.
+
+Supported platforms (typical)
+- linux-x64, linux-arm64, osx-x64, osx-arm64, win-x64.
+
+Related references
+- docs/cli/distribution-matrix.md
+- docs2/cli/crypto.md

docs2/cli/keyboard-shortcuts.md

@@ -0,0 +1,22 @@
+# CLI keyboard shortcuts
+
+Interactive triage shortcuts
+- j/k: next/previous finding.
+- a/n/w/f: mark affected, not affected, wont_fix, false_positive.
+- e: toggle evidence view.
+- g: toggle graph view.
+- /: search.
+- q: save and quit.
+
+Batch mode shortcuts
+- PageUp/PageDown: skip blocks of findings.
+- u: undo last decision.
+- ?: help.
+
+Accessibility
+- All actions have non-shortcut menu equivalents.
+- Shortcuts can be disabled in config.
+
+Related references
+- docs/cli/keyboard-shortcuts.md
+- docs2/ui/accessibility.md

docs2/cli/overview.md

@@ -0,0 +1,36 @@
+# CLI overview
+
+The stella CLI is the primary command-line interface for scans, evidence export,
+policy workflows, and offline operations.
+
+Core command groups
+- scan and sbom: scanning, SBOM generation, and attestations.
+- policy: lint, simulate, approve, and replay policy decisions.
+- vex and advisory: ingest and inspect observations and linksets.
+- reachability and smart-diff: reachability evidence and change detection.
+- downloads and offline: bundle export, verify, and import.
+- auth and admin: login, tokens, and administrative operations.
+
+Authentication
+- Interactive login uses OAuth and DPoP when configured.
+- Offline tokens are supported for air-gapped operations.
+
+Configuration
+- Config files load in order: system, user, project, then env vars.
+- STELLAOPS_* environment variables override file settings.
+
+Offline usage
+- Export bundles and verify hashes before transfer.
+- Use offline kits for feeds, policies, and revocation bundles.
+
+Related references
+- docs/cli/README.md
+- docs/cli/command-reference.md
+- docs/cli/reachability-cli-reference.md
+- docs/cli/unknowns-cli-reference.md
+- docs/cli/triage-cli.md
+- docs2/cli/commands.md
+- docs2/cli/crypto.md
+- docs2/cli/reachability.md
+- docs2/cli/triage.md
+- docs2/cli/unknowns.md

docs2/cli/reachability.md

@@ -0,0 +1,31 @@
+# Reachability, drift, and smart-diff CLI
+
+Reachability commands
+- reachability compute: compute reachability for a scan or graph snapshot.
+- reachability findings: list reachability findings with filters.
+- reachability explain: explain a finding and show paths.
+- reachability summary and job status/logs for batch workflows.
+
+Common options
+- --scan-id selects the scan.
+- --offline uses local bundles and caches.
+- --output-format supports table, json, yaml, sarif.
+
+Drift commands
+- drift compare: compare reachability between base and head scans.
+- drift show: display a saved drift result.
+- Filters include severity, risk increases only, and output format.
+
+Smart-diff commands
+- smart-diff compares two artifacts and reports material risk changes.
+- Output supports table, json, yaml, and sarif plus bundle output.
+- Options include min-priority, tier filters, and offline feed dirs.
+
+Proofs and verification
+- smart-diff verify validates proof bundles and signatures.
+- Use public keys or trust policy for verification.
+
+Related references
+- docs/cli/reachability-cli-reference.md
+- docs/cli/drift-cli.md
+- docs/cli/smart-diff-cli.md

docs2/cli/sbomer.md

@@ -0,0 +1,20 @@
+# SBOMer CLI
+
+SBOMer commands
+- sbomer layer: emit deterministic SBOM per layer.
+- sbomer compose: merge layer SBOMs with stable ordering.
+- sbomer drift: compute SBOM drift with ordered diffs.
+- sbomer verify: validate SBOM hash and signatures.
+
+Determinism rules
+- Stable sort keys for components and edges.
+- Fixed timestamps unless overridden.
+- UTF-8, LF line endings, no BOM.
+
+Offline posture
+- Preload images and registries.
+- Use STELLA_SBOMER_OFFLINE to block network pulls.
+
+Related references
+- docs/cli/sbomer.md
+- docs2/sbom/overview.md

docs2/cli/score-proofs.md

@@ -0,0 +1,19 @@
+# Score proofs CLI
+
+Score commands
+- score compute: compute scores for a scan.
+- score replay: replay scoring with specified feed or policy snapshots.
+- score show: show score breakdown and evidence refs.
+- score diff: compare score runs.
+- score manifest and score inputs: inspect inputs and manifests.
+
+Determinism
+- Deterministic mode is default; optional fixed seed supported.
+- Replay with original snapshots yields reproducible outputs.
+
+Offline workflows
+- Use --offline and --bundle for air-gapped replay.
+
+Related references
+- docs/cli/score-proofs-cli-reference.md
+- docs2/security/risk-model.md

docs2/cli/triage.md

@@ -0,0 +1,19 @@
+# Triage CLI
+
+Triage commands
+- triage list: list findings with status and priority filters.
+- triage show: show details with evidence and history.
+- triage decide: record a decision with justification.
+- triage batch: interactive batch triage mode.
+- triage export: export findings for offline review.
+
+Offline workflows
+- Use --workspace to point to offline bundles.
+- Export bundles with evidence and graph data for air-gapped review.
+
+Interactive shortcuts
+- j/k for navigation, a/n/w/f for decisions, e for evidence, q to save.
+
+Related references
+- docs/cli/triage-cli.md
+- docs2/cli/keyboard-shortcuts.md

docs2/cli/troubleshooting.md

@@ -0,0 +1,26 @@
+# CLI troubleshooting
+
+Authentication issues
+- Verify Backend.BaseUrl and Authority reachability.
+- Re-login when tokens expire or scopes are missing.
+- Use API key auth for headless automation when allowed.
+
+Crypto provider issues
+- Ensure the correct regional build is installed.
+- Verify provider configuration and key container paths.
+- Use crypto profiles diagnostics to test provider health.
+
+Build and distribution issues
+- Confirm the expected build flags for regional plugins.
+- Validate distribution metadata using stella --version.
+
+Scanning and network issues
+- Confirm registry access and offline cache settings.
+- Use offline bundles when network is restricted.
+
+Permissions and scopes
+- Ensure the token includes required scopes for admin or policy commands.
+
+Related references
+- docs/cli/troubleshooting.md
+- docs2/cli/crypto.md

docs2/cli/unknowns.md

@@ -0,0 +1,19 @@
+# Unknowns CLI
+
+Unknowns commands
+- unknowns list: list unknowns with filters and pagination.
+- unknowns show: show details for an unknown id.
+- unknowns summary: aggregate by status and category.
+- unknowns escalate, resolve, suppress: update status with rationale.
+- unknowns export and import: move triage results offline.
+
+Filters and categories
+- Filter by status, category, score, age, and purl patterns.
+- Categories include unmapped_purl, checksum_miss, parsing_failure, language_gap.
+
+Offline posture
+- Export unknowns for offline triage and re-import results.
+
+Related references
+- docs/cli/unknowns-cli-reference.md
+- docs2/signals/unknowns.md

docs2/contracts-and-interfaces.md

@@ -28,3 +28,4 @@ Related references
 - docs/contracts/*.md
 - docs/adr/*
 - docs/specs/*
+- docs2/contracts/scanner-core.md

docs2/contracts/scanner-core.md

@@ -0,0 +1,32 @@
+# Scanner core contracts
+
+Scanner core provides shared DTOs, identifiers, and observability helpers for the
+Scanner web service, workers, and analyzers.
+
+Canonical DTOs
+- ScanJob and ScanJobStatus for job metadata and lifecycle.
+- ScanProgressEvent for stage-level progress updates.
+- ScannerError for structured error taxonomy and retry hints.
+- ScanJobId for stable identifiers.
+
+Determinism helpers
+- ScannerIdentifiers generates job and correlation ids from normalized inputs.
+- ScannerTimestamps normalizes to UTC and fixed precision.
+- ScannerJsonOptions enforces consistent serialization.
+
+Observability primitives
+- ActivitySource and Meter with deterministic tags.
+- Log scopes carry job and stage metadata for consistent tracing.
+
+Security utilities
+- Authority token caching for short-lived OpToks.
+- DPoP proof validation with replay protection.
+- Restart-only plugin guard for sealed deployments.
+
+Testing expectations
+- Golden fixtures validate JSON shape and determinism.
+- Identifier and timestamp normalization tests run in CI.
+
+Related references
+- docs/scanner-core-contracts.md
+- docs/modules/scanner/architecture.md

docs2/developer/devportal.md

@@ -0,0 +1,16 @@
+# Developer portal publishing
+
+The developer portal is a static site built from docs and API specs. Publishing
+must remain deterministic for offline use.
+
+Build and publish
+- Use a pinned Node and pnpm version.
+- Generate a static site bundle and record SHA256 checksums.
+- Optionally publish a container image for deployment.
+
+Offline operation
+- Bundle site artifacts with checksums and a manifest.
+- Serve from local storage without external CDN dependencies.
+
+Related references
+- docs/devportal/publishing.md

docs2/developer/implementation-guidelines.md

@@ -0,0 +1,21 @@
+# Implementation guidelines
+
+These guidelines keep implementations deterministic, offline friendly, and
+aligned with module boundaries.
+
+Core rules
+- Determinism: stable ordering, pinned seeds, UTC timestamps.
+- Offline posture: no live network calls in tests or fixtures.
+- Provenance: sign evidence and keep tenant scope explicit.
+- Boundaries: work within module directories and allowed shared libs.
+- Versioning: bump schema versions for breaking changes.
+
+Quality gates
+- Add or update tests for every change.
+- Keep fixtures and inputs.lock files in sync with outputs.
+- Document contract changes in docs2 and module docs.
+
+Related references
+- docs/process/implementor-guidelines.md
+- docs/18_CODING_STANDARDS.md
+- docs/19_TEST_SUITE_OVERVIEW.md

docs2/developer/onboarding.md

@@ -1,15 +1,27 @@
-# Developer onboarding (summary)
+# Developer onboarding
 
-## Prerequisites
+Prerequisites
 - .NET 10 SDK
 - Node and npm for UI development
 - Docker for local infrastructure
 
-## Local stack
+Local stack
 - PostgreSQL, Valkey, and RustFS are required.
 - Services use layered configuration (env, appsettings, YAML).
 
-## Common workflows
+Common workflows
 - Run the stack with compose or Helm profiles.
 - Debug a single service by running it locally and pointing others to localhost.
 - Use deterministic fixtures for replay and policy validation.
+
+Contribution basics
+- Follow coding standards and test suite overview.
+- Keep outputs deterministic and offline friendly.
+- Update docs when contracts or workflows change.
+
+Related references
+- docs/DEVELOPER_ONBOARDING.md
+- docs/onboarding/dev-quickstart.md
+- docs/onboarding/contribution-checklist.md
+- docs/18_CODING_STANDARDS.md
+- docs/19_TEST_SUITE_OVERVIEW.md

docs2/governance/approvals.md

@@ -0,0 +1,26 @@
+# Approvals and routing
+
+Approval routing ensures high-risk actions are reviewed and auditable. The
+routing model is tenant and environment aware.
+
+Routing principles
+- Route by tenant, environment, and resource type.
+- Enforce least privilege with scoped approvals.
+- Require reason and ticket metadata for audit.
+
+MFA and fresh auth
+- Sensitive approvals require fresh authentication.
+- MFA can be enforced per routing template.
+
+Audit trail
+- Record approver identity, scope, timestamp, and rationale.
+- Store immutable approval records with hashes.
+
+Offline posture
+- Export approvals for air-gapped review.
+- Import approval bundles with signature verification.
+- Keep deterministic ordering for approval lists.
+
+Related references
+- docs/governance/approvals-and-routing.md
+- docs/security/authority-scopes.md

docs2/governance/exceptions.md

@@ -0,0 +1,27 @@
+# Exception governance
+
+Exceptions provide controlled, auditable overrides for policy or workflow
+gates. They are time-bound and reversible.
+
+Lifecycle
+- Create request with scope, reason, and TTL.
+- Route for approval based on tenant and environment.
+- Record signed approval or rejection.
+- Revoke or expire with audit trail.
+
+Scope patterns
+- Tenant and environment are required.
+- Resource scope targets assets, findings, or policy gates.
+- Exceptions do not mutate evidence; they annotate decisions.
+
+Compliance notes
+- Exceptions must include reason codes and approvals.
+- All records are retained for audit and replay.
+
+Offline posture
+- Export and import exception bundles with signatures.
+- Use deterministic ordering for exports.
+
+Related references
+- docs/governance/exceptions.md
+- docs/security/authority-scopes.md

docs2/guides/compare-workflow.md

@@ -0,0 +1,35 @@
+# Compare workflow guide
+
+Compare highlights the security delta between two images or scans so teams
+focus on material risk changes rather than full lists.
+
+When to use
+- Evaluate a new release before deploy.
+- Investigate why a policy gate blocked a build.
+- Audit security posture changes between versions.
+
+Core UI layout
+- Baseline selector: last green build, previous release, main branch, custom.
+- Delta summary: counts for added, removed, and changed items.
+- Categories: SBOM changes, reachability, VEX status, policy, findings, unknowns.
+- Evidence pane: witness path, VEX merge, policy rule, envelope hashes.
+
+Trust indicators
+- Determinism hash and policy version.
+- Feed snapshot age and signature status.
+- Warnings for stale feeds or policy drift.
+
+Exports
+- JSON for evidence and automation.
+- PDF for audit packets.
+- SARIF for CI integrations.
+
+Workflow examples
+1) Pre-release review: use last green baseline, inspect new critical findings.
+2) Blocked release: filter policy category to see blocking rule and evidence.
+3) Audit: verify signatures and run replay command from the UI.
+
+Related references
+- docs/guides/compare-workflow-user-guide.md
+- docs/cli/smart-diff-cli.md
+- docs/replay/DETERMINISTIC_REPLAY.md

docs2/guides/epss-integration.md

@@ -0,0 +1,43 @@
+# EPSS integration guide
+
+EPSS is a probabilistic exploit signal used alongside CVSS and KEV to
+prioritize vulnerabilities. StellaOps stores EPSS at scan time for replay
+and can also track live EPSS for triage.
+
+Key signals
+- epss_score: probability 0.0 to 1.0 of exploitation within 30 days.
+- epss_percentile: rank against all scored CVEs.
+- model_date: date of the EPSS model snapshot.
+- EPSS does not use numbered versions; model_date is the canonical identifier.
+
+Versioning clarification
+- EPSS does not have numbered versions like CVSS; references to "EPSS v4" are shorthand.
+- model_date is the authoritative identifier for a daily EPSS snapshot.
+- model_version in EPSS CSV headers refers to the ML model architecture, not a public EPSS version.
+
+Risk scoring (simple profile)
+- risk_score = clamp01((cvss / 10) + kev_bonus + epss_bonus)
+- epss_bonus by percentile:
+  - >= 99th: +0.10
+  - >= 90th: +0.05
+  - >= 50th: +0.02
+  - < 50th: 0.00
+
+At-scan evidence
+- epss_at_scan is immutable and used for deterministic replay.
+- epss_current can be used for live triage but does not alter past decisions.
+
+Offline bundles
+- EPSS data is packaged in risk bundles for air-gapped imports.
+- Bundle includes epss_scores and metadata with hashes and model_date.
+
+Staleness guidance
+- Online: update daily.
+- Air-gapped: import weekly minimum.
+- If stale, fall back to CVSS and KEV only.
+
+Related references
+- docs/guides/epss-integration.md
+- docs/guides/epss-integration-v4.md
+- docs/architecture/epss-versioning-clarification.md
+- docs/risk/overview.md

docs2/ingestion/aggregation-and-linksets.md

@@ -0,0 +1,104 @@
+# Ingestion, aggregation, and linksets
+
+StellaOps ingestion is governed by the Aggregation-Only Contract (AOC). The
+rules enforce deterministic, policy-neutral collection of advisory and VEX data.
+
+AOC core rules
+- Ingestion writes raw facts only. No derived severity, consensus, or policy hints.
+- No merges. Each upstream document is stored independently.
+- Provenance is mandatory: source metadata, content hashes, signature fields.
+- Idempotent writes keyed by vendor + upstream id + content hash.
+- Append-only revisions via supersedes pointers.
+- Deterministic output: canonical JSON, UTC timestamps, stable ordering.
+
+Ingestion pipeline (high level)
+1) Fetch upstream payload.
+2) Validate signature and schema.
+3) Normalize metadata (timestamps, ids, content hash).
+4) Persist raw document (append-only).
+5) Emit observation (immutable record).
+6) Build linksets (deterministic correlation).
+7) Expose via API and Offline Kit snapshots.
+
+Advisory observations (Concelier)
+- observationId format: {tenant}:{source.vendor}:{upstreamId}:{revision}.
+- Key fields: tenant, source, upstream, content.raw, identifiers, linkset hints.
+- Supersedes pointer links revisions without mutation.
+
+VEX observations (Excititor)
+- observationId format: {tenant}:{providerId}:{upstreamId}:{revision}.
+- Raw VEX payload plus normalized statement tuples.
+- Linkset hints include purls, cpes, aliases, references.
+
+Linksets and conflicts
+- Linksets correlate observations by product identity while preserving sources.
+- Deterministic ids are hashes of sorted identifiers and observation references.
+- Conflicts are recorded, not resolved. Common conflict types:
+  - severity mismatch
+  - affected range divergence
+  - status or justification mismatch
+  - alias inconsistency
+  - metadata gap (missing provenance)
+
+Observation example (short)
+```json
+{
+  "observationId": "tenant-a:redhat:CVE-2025-0001:1",
+  "tenant": "tenant-a",
+  "source": { "vendor": "redhat", "stream": "csaf" },
+  "upstream": {
+    "upstreamId": "CVE-2025-0001",
+    "documentVersion": "2025-01-10",
+    "contentHash": "sha256:1111...",
+    "signature": { "present": true }
+  },
+  "identifiers": { "cve": "CVE-2025-0001", "aliases": ["RHSA-2025:1234"] },
+  "linkset": { "purls": ["pkg:rpm/redhat/openssl@1.1.1w-12"] }
+}
+```
+
+Deterministic linkset id
+- Build a canonical string with sorted identifiers and observation ids.
+- linksetId = sha256(tenant + "|" + join(sorted(purls)) + "|" + join(sorted(observationIds)))
+
+Linkset example (short)
+```json
+{
+  "linksetId": "tenant-a:sha256:2222...",
+  "observations": ["tenant-a:redhat:CVE-2025-0001:1", "tenant-a:nvd:CVE-2025-0001:3"],
+  "purls": ["pkg:rpm/redhat/openssl@1.1.1w-12"],
+  "conflicts": [{ "type": "severity-mismatch" }]
+}
+```
+
+Idempotency and supersedes
+- Same content hash results in a no-op.
+- New content hash creates a new observation with supersedes set.
+- Supersedes chains are append-only and acyclic.
+
+AOC error model
+- ERR_AOC_001: forbidden derived fields detected.
+- ERR_AOC_002: merge attempt detected.
+- ERR_AOC_003: idempotency violation.
+- ERR_AOC_004: missing provenance.
+- ERR_AOC_005: signature or checksum mismatch.
+- ERR_AOC_006: derived findings write attempt.
+- ERR_AOC_007: schema violation.
+
+Downstream consumers
+- Policy Engine applies rules and produces effective findings.
+- Console and CLI render evidence panels and conflicts.
+- Offline Kit bundles observations and linksets for air-gapped parity.
+
+Validation and tests
+- Schema validators and guard libraries enforce AOC rules.
+- Unit and integration tests validate idempotency and linkset hashes.
+- CLI verifier and offline kit checks confirm determinism.
+
+Related references
+- docs/ingestion/aggregation-only-contract.md
+- docs/aoc/aoc-guardrails.md
+- docs2/ingestion/aoc-guardrails.md
+- ingestion/backfill.md
+- docs/advisories/aggregation.md
+- docs/vex/aggregation.md

docs2/ingestion/aoc-guardrails.md

@@ -0,0 +1,33 @@
+# AOC guardrails
+
+AOC guardrails enforce deterministic, policy-neutral ingestion in Concelier and
+Excititor. Ingestion writes raw facts only and never computes precedence,
+severity, or policy hints.
+
+Guardrail rules
+- Ingestion writes immutable observations and linksets only.
+- Derived semantics belong to Policy Engine and downstream views.
+- Provenance metadata is mandatory for every ingested record.
+- Outputs must be deterministic for identical inputs.
+- CI and analyzers should fail builds that violate these rules.
+
+Guard library (StellaOps.Aoc)
+- IAocGuard validates payloads and returns structured violations.
+- AocGuardOptions toggles signature and tenant requirements.
+- AocError carries machine-readable error codes for APIs and CLI.
+- AspNetCore filters enforce guardrails on Minimal API endpoints.
+
+Allowed fields and validation
+- Top-level allowlist enforces schema boundaries.
+- Required fields are configurable for staged schema changes.
+- Unknown fields produce ERR_AOC violations.
+
+Usage guidance
+- Register the guard in ingestion services before repositories.
+- Validate payloads before any persistence.
+- Use RFC 7807 problem responses for consistent errors.
+
+Related references
+- docs/aoc/aoc-guardrails.md
+- docs/aoc/guard-library.md
+- docs/ingestion/aggregation-only-contract.md

docs2/ingestion/backfill.md

@@ -0,0 +1,40 @@
+# AOC linkset backfill
+
+Purpose
+- Safely backfill advisory linksets and observations under Aggregation-Only rules.
+- Preserve offline kit integrity and determinism during data migrations.
+
+Inputs
+- Deterministic NDJSON dataset (gzip) for linksets and observations.
+- Target database and collections for advisory linksets and observations.
+- Offline kit bundle mirroring the backfill dataset.
+
+Preparation
+- Run a dry-run import to validate schema and guardrails.
+- Backup target collections before any import.
+- Stage rollback scripts and confirm indexes are reproducible.
+- Set ingestion flags for backfill windows (link-not-merge enabled, aggregation-only disabled if required for rehearsal).
+
+Execution
+- Import the NDJSON dataset with deterministic ordering.
+- Record import metrics and structured logs.
+- Run a determinism probe test that compares golden hashes.
+
+Rollback
+- Restore from backup and reapply deterministic indexes.
+- Re-run determinism probes and confirm guard flags are reset.
+
+Evidence to capture
+- Backup hash or archive checksum.
+- Import logs with counts and zero merge counters.
+- Determinism test results and hashes.
+- Offline kit bundle hash.
+
+Dataset generation
+- Export from staging with a pinned tenant and stable ordering.
+- Verify determinism by hashing the NDJSON output twice; hashes must match.
+- Publish a .sha256 alongside the dataset.
+
+Offline posture
+- Backfill datasets are mirrored into offline kits for air-gap verification.
+- Exports and evidence are stored as content-addressed artifacts.

docs2/interop/cosign.md

@@ -0,0 +1,28 @@
+# Cosign interoperability
+
+StellaOps can verify Cosign DSSE attestations, extract SBOMs, and ingest them
+for scanning in both online and air-gapped environments.
+
+Capabilities
+- Verify Cosign-signed SBOM attestations.
+- Extract SPDX or CycloneDX payloads from DSSE envelopes.
+- Verify signatures offline using bundled trust roots and checkpoints.
+
+Supported predicate types
+- SPDX (3.0.1 and 2.3)
+- CycloneDX (1.4 to 1.7)
+- SLSA provenance (metadata only)
+
+Common flows
+- Keyless signing via Fulcio for public registries.
+- Key-based signing for private or air-gapped environments.
+- Verify then extract; do not extract without verification.
+
+Offline trust
+- Use local trust roots and Rekor checkpoints.
+- Refresh checkpoints on a schedule appropriate to risk.
+
+Related references
+- docs/interop/cosign-integration.md
+- docs/24_OFFLINE_KIT.md
+- docs/modules/attestor/architecture.md

docs2/interop/sbom-interop.md

@@ -0,0 +1,22 @@
+# SBOM interoperability
+
+Interop tests validate that StellaOps SBOMs are consumable by common tools and
+that findings parity stays within an acceptable range.
+
+Supported formats
+- CycloneDX 1.6+
+- SPDX 3.0.1
+
+Parity expectations
+- Target parity is 95%+ against reference tools on shared corpora.
+- Acceptable differences include VEX application and feed coverage variance.
+- Package identity differences are tolerated when functionally equivalent.
+
+Operational notes
+- Interop tests run in CI and nightly schedules.
+- Offline mode uses bundled corpora and pinned tool versions.
+
+Related references
+- docs/interop/README.md
+- docs/interop/cosign-integration.md
+- docs/benchmarks/*

docs2/legal/regulator-threat-evidence.md

@@ -0,0 +1,41 @@
+# Regulator-grade threat and evidence model
+
+This summary captures the regulator-facing threat and evidence model for the
+platform without project-specific schedules or delivery notes.
+
+Threat model goals
+- Preserve decision integrity, evidence integrity, confidentiality, and
+  availability across online and air-gapped deployments.
+- Ensure non-repudiation for approvals and decisions.
+- Keep evidence replayable and deterministic.
+
+Evidence principles
+- Integrity: content-addressed and immutable storage.
+- Authenticity: signed artifacts and verified trust roots.
+- Traceability: decisions link to all inputs and transformations.
+- Reproducibility: decisions are replayable with frozen inputs.
+- Confidentiality: redaction profiles and scoped access.
+- Known unknowns are captured explicitly.
+
+Evidence taxonomy (high level)
+- Input artifacts: SBOM, VEX, provenance, scan outputs.
+- Normalization artifacts: identity resolution and mapping logs.
+- Analysis artifacts: reachability, diffs, scoring traces.
+- Governance artifacts: policies, approvals, exceptions.
+- Decision artifacts: verdicts, explanations, signatures.
+
+Controls and audit expectations
+- Strong auth and scoped tokens for ingestion and admin flows.
+- Signed manifests and optional transparency anchors.
+- Rate limiting and size guards for ingestion DoS protection.
+- Least privilege and separation of duties for policy changes.
+- Audit packages with hashes, signatures, and policy versions.
+
+Offline and export
+- Offline bundles carry signed manifests and dataset snapshots.
+- Exports include redaction profiles and integrity metadata.
+
+Related references
+- docs/28_LEGAL_COMPLIANCE.md
+- docs/security-and-governance.md
+- docs2/architecture/evidence-and-trust.md

docs2/migration/overview.md

@@ -0,0 +1,22 @@
+# Migration overview
+
+This section summarizes common migration paths with an emphasis on determinism
+and auditability. Detailed steps live in the source migration docs.
+
+Key migrations
+- No-merge migration to Link-Not-Merge (LNM) observations and linksets.
+- Enable reachability signals and graph parity.
+- Policy parity and exception governance alignment.
+- CycloneDX 1.6 to 1.7 data model transitions.
+
+Common principles
+- Use feature flags and shadow modes before cutover.
+- Record deterministic backfill outputs and checksum reports.
+- Verify parity with golden corpora and CI tests.
+
+Related references
+- docs/migration/no-merge.md
+- docs/migration/enable-reachability.md
+- docs/migration/graph-parity.md
+- docs/migration/policy-parity.md
+- docs/migration/cyclonedx-1-6-to-1-7.md

docs2/notifications/channels.md

@@ -0,0 +1,26 @@
+# Notification channels
+
+Supported types
+- Slack and Teams via webhooks.
+- Email via SMTP or relay.
+- Generic webhook and escalation webhook.
+- Console in-app delivery.
+
+Channel schema (summary)
+- id, tenant, type, endpoint, secretRef, labels.
+- throttle and quietHours.
+- enabled flag and createdUtc timestamp.
+
+Security and determinism
+- No secrets stored in Notify DB; use secretRef.
+- Endpoints must be allowlisted.
+- Webhook payloads use HMAC-SHA256 with nonce and timestamp.
+- Deterministic channel ids for manifest-based creation.
+
+Offline posture
+- Offline kits include placeholder channel manifests.
+- Operators replace endpoints and secretRefs before deployment.
+
+Related references
+- docs/notifications/channels.md
+- docs/notifications/architecture.md

docs2/notifications/digests.md

@@ -0,0 +1,20 @@
+# Notification digests
+
+Digests coalesce matching events into scheduled summaries to reduce noise.
+
+Digest lifecycle
+- Rule action selects digest window (instant, 5m, 15m, 1h, 1d).
+- Worker aggregates events per tenant and action.
+- Window flush renders a digest template and emits a delivery.
+
+Storage and audit
+- Digest documents store window metadata and items.
+- Delivery ledger links to digest ids for traceability.
+
+Safety and determinism
+- Idempotent digest delivery ids per window.
+- Throttles and quiet hours are respected.
+- Workers resume open windows after restart.
+
+Related references
+- docs/notifications/digests.md

docs2/notifications/overview.md

@@ -0,0 +1,24 @@
+# Notifications overview
+
+Notifications Studio turns platform events into tenant-scoped alerts with
+explainable routing and deterministic outputs.
+
+Core capabilities
+- Rules engine for event matching, VEX gating, throttles, and digests.
+- Channel connectors (Slack, Teams, Email, Webhook, Console).
+- Deterministic templates and locale-aware rendering.
+- Delivery ledger for audit and replay.
+
+Operational model
+- Notify.Worker evaluates rules per event and tenant.
+- Actions are idempotent; throttles and digests are recorded.
+- API access uses notify.viewer, notify.operator, notify.admin scopes.
+
+Offline posture
+- Offline kits ship rules, templates, and plugins.
+- No external SaaS required for core delivery.
+
+Related references
+- docs/notifications/overview.md
+- docs/notifications/architecture.md
+- docs2/operations/notifications.md

docs2/notifications/pack-approvals.md

@@ -0,0 +1,33 @@
+# Pack approvals notifications
+
+Purpose
+- Ingest pack approval events from Task Runner.
+- Persist approval state and notify approvers.
+- Provide acknowledgement and resume hooks.
+
+Event contract
+- approval requested and approval updated events.
+- Fields include runId, approvalId, plan hash, tenant, required grants,
+  step identifiers, and resume callback metadata.
+
+Ingestion and persistence
+- Secure endpoint validates scopes and tenant header.
+- Approval records stored with idempotent keys (runId + approvalId).
+- Audit records capture delivery attempts and correlation ids.
+
+Routing and templates
+- Rules match event.kind = pack.approval.
+- Templates include plan metadata and approval links.
+- Policy hold notifications are surfaced as incidents.
+
+Ack and resume
+- Ack endpoint records decision metadata and forwards resume callback.
+- Idempotent updates based on decision hash.
+
+Security and observability
+- HMAC or mTLS between Task Runner and Notify.
+- Metrics for queued, sent, and pending approvals.
+
+Related references
+- docs/notifications/pack-approvals-integration.md
+- docs/notifications/pack-approvals-contract.md

docs2/notifications/rules.md

@@ -0,0 +1,28 @@
+# Notification rules
+
+Rule lifecycle
+- Create and update via Notify API or UI.
+- Worker evaluates rules per tenant and event.
+- Actions are queued with idempotency keys.
+- Delivery ledger references ruleId and actionId.
+
+Rule schema (summary)
+- ruleId, tenantId, name, enabled.
+- match filters for eventKinds, namespaces, labels, severity, verdicts.
+- VEX gates can include or exclude justifications.
+- actions define channel, template, digest window, throttle, locale.
+
+Match filters
+- eventKinds, namespaces, repositories, digests, labels.
+- minSeverity and kevOnly gates.
+- VEX justification allowlists when present.
+
+Actions, throttles, digests
+- actionId and channel are required.
+- digest windows: instant, 5m, 15m, 1h, 1d.
+- throttles prevent repeat deliveries for identical events.
+
+Related references
+- docs/notifications/rules.md
+- docs2/notifications/digests.md
+- docs2/notifications/templates.md

docs2/notifications/templates.md

@@ -0,0 +1,25 @@
+# Notification templates
+
+Templates define deterministic payloads per channel and locale.
+
+Template lifecycle
+- Create templates via API or UI.
+- Rule actions reference template keys.
+- Worker renders templates with a safe helper set.
+
+Template schema (summary)
+- templateId, tenantId, channelType, key, locale.
+- body, renderMode, format, metadata.
+- schemaVersion is normalized on persistence.
+
+Template context
+- event, scope, payload, rule, action, policy.
+- topFindings and digest metadata when available.
+
+Attestation lifecycle templates
+- Dedicated template keys for attestation failures, expiries,
+  key rotation, and transparency anomalies.
+- Templates must include subject, signer, and evidence links.
+
+Related references
+- docs/notifications/templates.md

docs2/operations/airgap-bundles.md

@@ -0,0 +1,46 @@
+# Air-gap bundles and formats
+
+Air-gapped deployments use signed bundles with deterministic manifests. Bundles
+are verified before import and tracked by mirror generation.
+
+Bundle types
+- Mirror and bootstrap bundles (images, charts, plugins).
+- Advisory and VEX bundles with AOC guardrails.
+- Risk and EPSS bundles for scoring.
+- Symbol bundles for reachability overlays.
+- Evidence bundles for findings and decisions.
+- Revocation bundles for Authority token and key revocations.
+
+Bundle format (offline bundles)
+- Archive: .stella.bundle.tgz with deterministic tar settings.
+- manifest.json lists entries with sha256 hashes and sizes.
+- DSSE envelope signs the manifest payload.
+- Optional receipt.json records import verification and audit metadata.
+
+Manifest rules
+- Sorted keys and stable ordering.
+- SHA-256 digests for every entry.
+- root_hash over all entries for quick validation.
+
+Time anchors and staleness
+- Time anchors are signed snapshots of time source state.
+- Staleness checks gate use of bundles in sealed mode.
+- Offline bundles should include time anchor and staleness metadata.
+
+Sealed mode expectations
+- Deny-all egress; only registered bundles are accepted.
+- Imports emit audit events and are tracked by mirrorGeneration.
+- UI displays sealed-mode banner with manifest hash and time anchor status.
+
+Verification workflow
+- Verify archive hash and DSSE signature.
+- Validate manifest and any schema-specific entries.
+- Reject bundles with missing provenance or invalid hashes.
+
+Related references
+- docs/airgap/overview.md
+- docs/airgap/offline-bundle-format.md
+- docs/airgap/staleness-and-time.md
+- docs/airgap/portable-evidence.md
+- docs/airgap/symbol-bundles.md
+- docs/security/revocation-bundle.md

docs2/operations/airgap-runbooks.md

@@ -0,0 +1,27 @@
+# Air-gap runbooks (summary)
+
+Core runbooks
+- Import and verify: unpack bundle, validate manifest, verify DSSE signatures.
+- AV scan: scan bundle contents before import if required by policy.
+- Quarantine: isolate bundles with hash or signature mismatches.
+- Sealed startup diagnostics: confirm egress block and time anchor validity.
+
+Import and verify
+- Validate bundle hash, manifest entries, and schema checks.
+- Record import receipt with operator, time anchor, and manifest hash.
+- Reject and log any mismatches or missing provenance.
+
+Quarantine handling
+- Preserve the original bundle and verification logs.
+- Open an incident if mismatches indicate tampering.
+- Re-import only after a new bundle is signed and verified.
+
+Operational notes
+- Keep previous mirror generation as rollback baseline.
+- Use deterministic tools and fixed ordering for all checks.
+
+Related references
+- docs/airgap/runbooks/import-verify.md
+- docs/airgap/runbooks/av-scan.md
+- docs/airgap/runbooks/quarantine-investigation.md
+- docs/airgap/sealed-startup-diagnostics.md

docs2/operations/airgap.md

@@ -32,3 +32,7 @@
 - DSSE envelopes and cached transparency proofs enable local verification.
 - Reachability and replay bundles can be verified without network access.
 - Keep analyzer manifests and policy hashes with the replay bundle.
+
+## Related references
+- docs2/operations/airgap-bundles.md
+- docs2/operations/airgap-runbooks.md

docs2/operations/binary-prereqs.md

@@ -0,0 +1,17 @@
+# Binary prerequisites
+
+StellaOps supports offline operation by pinning binaries and packages in
+local mirrors with deterministic manifests.
+
+Layout
+- local-nugets/ for NuGet packages and cache.
+- vendor/ for pinned third-party binaries.
+- offline/feeds/ for air-gap bundles.
+
+Rules
+- Update manifest files when adding binaries.
+- Prefer source builds when possible.
+- Enforce offline builds with local sources first.
+
+Related references
+- docs/ops/binary-prereqs.md

docs2/operations/deployment-versioning.md

@@ -0,0 +1,28 @@
+# Deployment versioning
+
+StellaOps uses environment-specific version tags and promotion steps to keep
+deployments reproducible and auditable.
+
+Version tags
+- Release tags follow semver (X.Y.Z).
+- Environment variants add suffixes (for example, airgap).
+- Immutable deployments use digests instead of tags.
+
+Promotion model
+- Dev to staging: unit and integration tests are green.
+- Staging to prod: end-to-end, security, and performance gates pass.
+- Prod to airgap: offline validation and bundle verification complete.
+
+Naming conventions
+- registry/<service>:<version>
+- registry/<service>:<version>-<variant>
+- registry/<service>@sha256:<digest>
+
+Operational guidance
+- Keep version matrices in sync with release bundles.
+- Use pinned digests for air-gapped imports.
+- Record promotion metadata with evidence bundles.
+
+Related references
+- docs/deployment/VERSION_MATRIX.md
+- docs/13_RELEASE_ENGINEERING_PLAYBOOK.md

docs2/operations/notifications.md

@@ -0,0 +1,40 @@
+# Notifications Studio
+
+Notifications Studio turns platform events into tenant-scoped alerts that are
+explainable, deterministic, and offline friendly.
+
+Core capabilities
+- Rules engine for filtering by event kind, severity, and context.
+- Channel connectors for chat, email, and webhook delivery.
+- Templates with deterministic rendering and safe helpers.
+- Digests to coalesce bursts into scheduled summaries.
+- Delivery ledger for audit and troubleshooting.
+
+Operational model
+- Notify.Worker evaluates rules per tenant.
+- Connectors deliver rendered payloads and report outcomes.
+- Notify.WebService exposes API endpoints for UI and CLI.
+
+Security and governance
+- Tenancy enforced on all rules and deliveries.
+- Secrets are referenced via secretRef, not stored in config.
+- Ack tokens are DSSE signed and authority scoped.
+- Webhook deliveries are HMAC-SHA256 signed with nonce or timestamp.
+- Outbound allowlists block public egress in sealed deployments.
+
+Offline posture
+- Offline kits bundle default rules, templates, and plugins.
+- Deterministic rendering keeps hashes stable across environments.
+
+Related references
+- docs/notifications/overview.md
+- docs/notifications/rules.md
+- docs/notifications/templates.md
+- docs/notifications/digests.md
+- docs/modules/notify/architecture.md
+- docs2/notifications/overview.md
+- docs2/notifications/rules.md
+- docs2/notifications/channels.md
+- docs2/notifications/templates.md
+- docs2/notifications/digests.md
+- docs2/notifications/pack-approvals.md

docs2/operations/quickstart.md

@@ -0,0 +1,35 @@
+# Quickstart
+
+This quickstart covers a minimal first scan in a local or lab environment.
+It assumes container runtime access and a basic Docker or Kubernetes setup.
+
+Prerequisites
+- Linux host with container runtime and Compose or Kubernetes.
+- Local PostgreSQL and Valkey or bundled containers.
+- Sufficient disk for SBOM caches and bundles.
+
+Baseline steps
+1) Prepare configuration
+- Set admin credentials and service endpoints.
+- Use local or bundled database and cache for first run.
+
+2) Start core services
+- Bring up Authority, Scanner, Concelier, Policy, and UI services.
+- Confirm health endpoints are ready.
+
+3) Run first scan
+- Authenticate CLI with Authority.
+- Submit a scan for a known image or SBOM.
+
+4) Verify results
+- Open the Console to inspect findings and evidence.
+- Export a DSSE bundle and verify signatures.
+
+Offline and sovereign notes
+- Offline kits bundle feeds, plugins, and config for sealed installs.
+- Crypto profiles can be applied without rebuilding services.
+
+Related references
+- docs/quickstart.md
+- docs/21_INSTALL_GUIDE.md
+- docs/24_OFFLINE_KIT.md

docs2/operations/router-rate-limiting.md

@@ -0,0 +1,26 @@
+# Router rate limiting
+
+Router rate limiting is enforced at the gateway to avoid per-service throttling.
+It supports instance-local and environment-wide limits.
+
+Behavior
+- Denied requests return 429 with Retry-After and rate limit headers.
+- Response includes a JSON body with limit and window details.
+
+Scopes
+- Instance: in-memory sliding window per router instance.
+- Environment: Valkey-backed fixed window across instances.
+
+Configuration
+- rate_limiting.process_back_pressure_when_more_than_per_5min gates Valkey use.
+- rules support multiple windows with AND semantics.
+- microservice overrides replace default rules.
+- route overrides apply per service route name.
+
+Failover
+- Environment limiting is fail-open when Valkey is unavailable.
+- Instance limits remain active for baseline protection.
+
+Related references
+- docs/router/rate-limiting.md
+- docs/router/rate-limiting-routes.md

docs2/operations/runtime-readiness.md

@@ -0,0 +1,20 @@
+# Runtime readiness
+
+Runtime readiness ensures services expose the metadata required by downstream
+consumers and operations tooling.
+
+Core checks
+- Event schemas and samples are up to date.
+- Signed report payloads include required summary fields.
+- Scan progress events include stable data keys.
+- Health and readiness endpoints reflect dependency checks.
+
+Validation
+- Validate event payloads against JSON schemas.
+- Capture canonical samples for replay and regression tests.
+- Verify DSSE signatures on report artifacts.
+
+Related references
+- docs/runtime/SCANNER_RUNTIME_READINESS.md
+- docs/events/README.md
+- docs/09_API_CLI_REFERENCE.md

docs2/operations/slo.md

@@ -0,0 +1,18 @@
+# Service SLOs
+
+Service level objectives define availability, latency, and queue health
+expectations for core services.
+
+Typical SLOs (example)
+- API availability target per month.
+- P95 run duration target for standard workflows.
+- Queue backlog thresholds per tenant.
+- Event delivery success targets.
+
+Operational practice
+- Track error budgets over a rolling window.
+- Alert on burn rates and sustained backlog.
+- Keep dashboards aligned with SLO definitions.
+
+Related references
+- docs/slo/orchestrator-slo.md

docs2/orchestrator/api.md

@@ -0,0 +1,42 @@
+# Orchestrator API
+
+Scope and headers
+- Base path: /api/v1/orchestrator.
+- Headers: Authorization Bearer token, X-Stella-Tenant, Idempotency-Key for POSTs.
+- traceparent is recommended for tracing.
+- Error envelope follows api/overview.md.
+
+DAG management
+- POST /dags: create or publish a DAG version with steps, edges, metadata, signature.
+- GET /dags: list DAGs sorted by dagId then version desc; filter by dagId or active.
+- GET /dags/{dagId}/{version}: fetch DAG definition.
+- POST /dags/{dagId}/{version}:disable: disable a version (admin scope).
+
+Runs
+- POST /runs: start a run with dagId, optional version, inputs, and runToken.
+- GET /runs: list runs with filters for dagId, status, from, to; sorted by startedUtc desc.
+- GET /runs/{runId}: run details with step hashes and status.
+- POST /runs/{runId}:cancel: request cancellation (best-effort).
+
+Steps and artifacts
+- GET /runs/{runId}/steps: list step executions.
+- GET /runs/{runId}/steps/{stepId}: step details with attempts and outputs hash.
+- GET /artifacts/{hash}: retrieve content-addressed artifacts owned by the tenant.
+
+WebSocket stream
+- GET /runs/stream?dagId=&status=: NDJSON events for run and step updates.
+- Event types: run.started, run.updated, step.updated, run.completed, run.failed, run.cancelled.
+
+Admin and ops
+- POST /admin/warm: warm caches for DAGs and plugins.
+- GET /admin/health: readiness with queue depth by tenant.
+- GET /admin/metrics: Prometheus scrape endpoint.
+
+Determinism and offline
+- List endpoints return deterministic ordering; pagination uses page_token and page_size.
+- Hashes are lower-case hex; timestamps UTC ISO-8601.
+- No remote fetches; DAGs and plugins are preloaded in offline bundles.
+
+Security
+- Scopes: orchestrator:read, orchestrator:write, orchestrator:admin.
+- Tenant isolation enforced on every endpoint.

docs2/orchestrator/architecture.md

@@ -0,0 +1,43 @@
+# Orchestrator architecture
+
+Runtime components
+- WebService: REST and WebSocket API for DAG definitions, runs, and admin actions.
+- Scheduler: cron and timer triggers that enqueue run intents.
+- Worker: executes DAG steps, enforces resource limits, and reports telemetry.
+- Plugin host: loads task plugins from signed offline bundles.
+
+Data model
+- DAG: directed acyclic graph with deterministic topological ordering.
+- Run: immutable record with runId, dagVersion, tenant, inputsHash, status, traceId, startedUtc, endedUtc.
+- Step execution: stepId, inputsHash, outputsHash, status, attempt, durationMs, logsRef, metricsRef.
+
+Execution flow
+- Run creation is idempotent on runToken, dagId, and inputsHash.
+- Scheduler enqueues run intent to a tenant queue.
+- Worker reconstructs DAG order, executes steps, applies retries and backoff.
+- WebSocket streams run and step status updates.
+
+Storage and queues
+- PostgreSQL stores DAG specs, versions, and run history.
+- Queues are per-tenant FIFO in PostgreSQL or Valkey-backed lists.
+- Artifacts are content-addressed and stored in object storage or large objects.
+
+Security and AOC alignment
+- Tenant header required on every request; cross-tenant DAGs are forbidden.
+- Scopes: orchestrator:read, orchestrator:write, orchestrator:admin.
+- AOC alignment: orchestrator schedules and records only; no policy decisions.
+- Step sandboxing enforces CPU and memory limits; network egress deny by default.
+
+Determinism
+- Step ordering uses topological order with lexical tie-breaks.
+- Retries preserve traceId and reuse the same runToken.
+- Timestamps UTC; hashes lower-case hex.
+
+Offline posture
+- DAG specs and plugins are loaded from offline bundles with signatures.
+- Exports of runs, steps, and logs are available as NDJSON.
+
+Observability
+- Traces: orchestrator.run and orchestrator.step with tenant, dagId, runId, stepId.
+- Metrics: orchestrator_runs_total, orchestrator_run_duration_seconds, orchestrator_queue_depth.
+- Logs: structured JSON with trace_id, tenant, dagId, runId, stepId.

docs2/orchestrator/cli.md

@@ -0,0 +1,26 @@
+# Orchestrator CLI
+
+Commands
+- stella orch dag list: list DAGs sorted by dagId then version desc.
+- stella orch dag publish --file dag.yaml --signature sig.dsse: publish a DAG version.
+- stella orch dag disable --dag-id <id> --version <ver>: disable a DAG version.
+- stella orch run start --dag-id <id> --inputs inputs.json --run-token <uuid>: start a run.
+- stella orch run list: list runs with filters for dagId, status, from, to.
+- stella orch run cancel --run-id <id>: request cancellation.
+- stella orch run logs --run-id <id> --step-id <step>: fetch logs or artifacts.
+- stella orch run stream --dag-id <id>: stream NDJSON run events.
+
+Global flags
+- --tenant, --api-url, --token, --traceparent, --output json|table.
+- --page-size and --page-token for list pagination.
+
+Determinism and offline
+- CLI preserves API ordering and fixed table columns.
+- Timestamps print UTC; hashes lower-case hex.
+- Works against local WebService without external downloads.
+
+Exit codes
+- 0 success.
+- 1 validation or HTTP error.
+- 2 auth or tenant missing.
+- 3 cancellation rejected.

docs2/orchestrator/console.md

@@ -0,0 +1,27 @@
+# Orchestrator console
+
+Views
+- Run list sorted by startedUtc desc then runId.
+- Run detail with step graph, attempts, duration, logs links, and outputs hash.
+- DAG catalog with signatures and enable or disable state.
+- Queue health with per-tenant depth, age, and worker availability.
+
+Actions
+- Start run with DAG version, inputs JSON, and optional run token.
+- Cancel run with rationale.
+- Download artifacts and logs.
+- Stream live updates via WebSocket.
+
+Accessibility and UX
+- Shortcuts: f for filter, r for refresh, s for start run.
+- Timestamps are UTC; durations show raw ms in tooltips.
+- Status badges include icons and text; empty states show retry guidance.
+
+Determinism and offline
+- Client sorting mirrors API order; pagination uses stable page tokens.
+- Works against local WebService with bundled fonts and assets.
+- Exports for runs and steps are available as NDJSON.
+
+Safety
+- Tenant scope enforced; cross-tenant DAGs hidden.
+- Logs are redacted server-side; secrets never rendered in the UI.

docs2/orchestrator/overview.md

@@ -0,0 +1,41 @@
+# Orchestrator overview
+
+Mission
+- Coordinate deterministic job execution across modules.
+- Provide reproducible DAG runs with tenant isolation and auditability.
+
+Runtime shape
+- WebService for REST and WebSocket APIs and UI status.
+- Scheduler creates runs from schedules and enqueues intents.
+- Worker executes DAG steps from per-tenant queues.
+- Plugin host loads signed task plugins from offline bundles.
+
+Determinism
+- Stable DAG evaluation order with lexical tie-breaks.
+- Idempotency keys per run and step hash.
+- UTC timestamps and ordered NDJSON exports.
+
+AOC alignment
+- Orchestrator runs declared steps and records outcomes.
+- It does not derive policy verdicts or merge advisory data.
+
+State and storage
+- Run metadata stored in PostgreSQL with tenant scoping.
+- Queues stored in PostgreSQL or Valkey-backed FIFO per tenant.
+- Artifacts referenced by content hash in object storage or large objects.
+- Optional Valkey locks for throttles and backpressure.
+
+Offline posture
+- DAG specs and plugins are loaded from offline bundles.
+- Network egress is deny by default unless a task declares an allowlist.
+
+Observability
+- Metrics for runs, durations, and queue depth.
+- Structured logs with tenant, dagId, runId, and status.
+
+Related references
+- orchestrator/architecture.md
+- orchestrator/api.md
+- orchestrator/cli.md
+- orchestrator/console.md
+- orchestrator/run-ledger.md

docs2/orchestrator/run-ledger.md

@@ -0,0 +1,26 @@
+# Orchestrator run ledger
+
+Purpose
+- Immutable record of DAG runs and step executions for audit and replay.
+
+Core fields
+- tenant, runId, dagId, dagVersion, runToken, traceId.
+- status and timestamps (startedUtc, endedUtc, durationMs).
+- inputsHash and outputsHash at run and step levels.
+
+Step records
+- stepId, attempt, status, timing, errorCode, retryable.
+- logsRef and metricsRef point to content-addressed artifacts.
+
+Storage and exports
+- Tenant-scoped PostgreSQL tables with indexes on tenant, status, and time.
+- Append-only updates; status transitions are monotonic.
+- NDJSON exports are sorted by startedUtc then runId.
+ - Artifacts are content-addressed; hashes point to object storage or large objects.
+
+Governance
+- Runs are never deleted; cancellation is recorded as an event.
+- Admin queries require orchestrator:admin scope.
+
+Related references
+- orchestrator/overview.md

docs2/policy/policy-system.md

@@ -0,0 +1,108 @@
+# Policy system
+
+The policy system turns evidence into deterministic findings and explanations.
+Policies are authored in the Stella Policy DSL, compiled to canonical IR, and
+executed in the Policy Engine.
+
+Purpose and scope
+- Convert raw evidence into effective findings with explainability.
+- Keep decisions deterministic and reproducible across environments.
+- Support offline execution with content-addressed inputs.
+
+Inputs and signals
+- SBOM inventory and usage data from Scanner.
+- Advisory observations and linksets from Concelier.
+- VEX observations and linksets from Excititor.
+- Reachability graphs and runtime traces from Signals.
+- Trust, entropy, and uncertainty signals.
+
+DSL structure (stella-dsl@1)
+- metadata: optional descriptive fields surfaced in UI and CLI.
+- profile blocks: maps and scalar adjustments for severity or trust.
+- rule blocks: when-then logic with optional priority.
+- settings: evaluation toggles (shadow, defaults).
+
+Example (short)
+```dsl
+policy "Baseline" syntax "stella-dsl@1" {
+  metadata { description = "VEX first" }
+  profile severity { map vendor_weight { source "OSV" => 0.0; } }
+  rule vex_override priority 10 {
+    when vex.any(status == "not_affected")
+    then status := "not_affected"
+    because "VEX claim"
+  }
+}
+```
+
+Evaluation model
+- The engine evaluates tuples of (component, advisory, vex[]).
+- Rules execute by ascending priority; ties resolve by lexical order.
+- Actions set status, severity, and annotations; missing evidence yields unknown.
+- Suppressions and overrides must be explicit and explained.
+
+Outputs and explainability
+- effective findings with status, severity, and confidence fields.
+- explain trace with rule id, because text, and evidence hashes.
+- policy hash and input hashes recorded for replay and audit.
+
+Lifecycle and gates
+1) Draft with shadow mode enabled.
+2) Lint and simulate with coverage fixtures.
+3) Review and approve with Authority scopes.
+4) Publish with attestation and optional ledger anchor.
+5) Promote to environments and activate runs.
+6) Archive and retain audit history.
+
+Minimum gates for publish
+- Lint is clean.
+- Simulation diff is reviewed and attached.
+- Coverage fixtures pass in CI and shadow runs exist.
+- Reason and ticket metadata are provided for approvals.
+
+Fixtures and simulation
+- Fixtures live under tests/policy/<policyId>/cases/.
+- Each case includes inputs and expected status or severity.
+- Fixtures must include unknown reachability and VEX conflict cases.
+
+Fixture example (short)
+```json
+{
+  "caseId": "vex-not-affected",
+  "sbom": { "components": [{ "purl": "pkg:npm/lodash@4.17.21" }] },
+  "advisories": [{ "id": "CVE-2024-1234", "purl": "pkg:npm/lodash@4.17.21" }],
+  "vex": [{ "status": "not_affected", "justification": "component_not_present" }],
+  "signals": { "reachability": { "state": "unknown" } },
+  "expect": { "status": "not_affected" }
+}
+```
+
+Simulation output (summary)
+- policyHash: canonical hash of the policy IR.
+- inputsHash: canonical hash of inputs and fixtures.
+- findingsCount: total findings produced.
+- determinismHash: stable hash for replay comparisons.
+
+Governance
+- Scopes include policy:author, policy:review, policy:approve, policy:publish,
+  policy:promote, policy:operate, policy:audit.
+- Two-person approval is recommended for publish and promote.
+- Authors should not approve their own submissions.
+- Approval evidence and run history are immutable and exportable.
+- Offline governance follows the same workflow with signed bundles.
+
+Determinism and offline
+- Canonical JSON and stable ordering for IR and outputs.
+- No network calls or non-deterministic functions in evaluation.
+- Offline kits bundle policies, attestations, and fixtures.
+
+Testing
+- stella policy lint, simulate, and test must run in CI.
+- Coverage fixtures should include reachability unknown and VEX conflicts.
+
+Related references
+- docs/policy/overview.md
+- docs/policy/dsl.md
+- docs/policy/lifecycle.md
+- docs/policy/exception-effects.md
+- docs/60_POLICY_TEMPLATES.md

docs2/product/claims-and-benchmarks.md

@@ -0,0 +1,23 @@
+# Claims and benchmarks
+
+Claims are tied to reproducible evidence and benchmark results. Benchmarks
+provide the verification data for deterministic, reachability, and performance
+statements.
+
+Claim categories (examples)
+- Determinism and replay
+- Reachability accuracy
+- VEX handling and explainability
+- Offline and air-gap capability
+- SBOM fidelity and ecosystem coverage
+- Performance and scale
+
+Verification approach
+- Claims reference specific benchmark outputs and test fixtures.
+- Evidence is stored alongside deterministic inputs and hashes.
+- Claims are re-verified during releases and major changes.
+
+Related references
+- docs/claims-index.md
+- docs/market/claims-citation-index.md
+- docs/benchmarks/*

docs2/product/market-positioning.md

@@ -0,0 +1,26 @@
+# Market positioning
+
+StellaOps positions around determinism, evidence, and sovereign operation.
+The focus is audit-grade proof rather than opaque scanning.
+
+Moats
+- Deterministic replay with frozen inputs.
+- Signed reachability graphs and optional edge attestations.
+- Lattice VEX with explainable conflict resolution.
+- Sovereign crypto profiles and offline operation.
+- Evidence chain linking SBOM, VEX, and policy decisions.
+
+Competitive gaps (high level)
+- Most tools lack deterministic replay and signed reachability.
+- VEX handling is often boolean or bolt-on.
+- Offline and regional crypto requirements are rarely first-class.
+
+Use cases
+- Regulated environments needing replayable evidence.
+- Air-gapped deployments requiring bundled feeds and trust roots.
+- Teams prioritizing exploitability over enumeration.
+
+Related references
+- docs/market/competitive-landscape.md
+- docs/market/moat-strategy-summary.md
+- docs/marketing/*

docs2/provenance/inline-provenance.md

@@ -0,0 +1,32 @@
+# Provenance and transparency
+
+Inline provenance captures DSSE and ledger metadata alongside event records so
+replay and audits can verify evidence without external lookups.
+
+Inline DSSE fields (summary)
+- envelope digest and payload type
+- key id, issuer, algorithm
+- optional Rekor log index and uuid
+- trust block with verifier and verified flag
+
+Write flow
+- CI publishes DSSE and ledger metadata.
+- Authority verifies signatures and records trust results.
+- Events store provenance and trust fields inline.
+
+Backfill and verification
+- Backfill service resolves attestations for older events.
+- Queries detect missing or unverified provenance.
+
+Indexes and queries
+- Index by subject digest, kind, and rekor log index.
+- Query for unproven events to close compliance gaps.
+
+UI and policy usage
+- UI shows provenance chips and filters.
+- Policy gates can block decisions without verified provenance.
+
+Related references
+- docs/provenance/inline-dsse.md
+- docs/forensics/provenance-attestation.md
+- docs/modules/attestor/architecture.md

docs2/references/examples-and-fixtures.md

@@ -0,0 +1,21 @@
+# Examples, samples, and fixtures
+
+Examples and fixtures provide deterministic inputs for tests, demos, and audits.
+This page indexes key locations without duplicating data.
+
+Examples
+- Policy examples: docs/examples/policies/
+- UI tour examples: docs/examples/ui-tours.md
+
+Samples
+- Evidence bundles and NDJSON samples: docs/samples/
+- Events and schemas samples: docs/events/samples/
+
+Schemas
+- JSON schemas: docs/schemas/
+- OpenAPI specs: docs/api/ and docs/modules/*/openapi/
+
+Related references
+- docs/examples/README.md
+- docs/samples/
+- docs/schemas/

docs2/sbom/overview.md

@@ -0,0 +1,28 @@
+# SBOM handling
+
+SBOMs are the primary evidence record for scans. StellaOps supports SPDX and
+CycloneDX and keeps outputs deterministic for replay.
+
+Formats and inputs
+- SPDX 3.0.1 and CycloneDX 1.6+ are supported for ingestion and export.
+- SBOMs may be full or delta (layer-based) for faster rescans.
+
+Mapping and resolution
+- CPE and PURL mappings are normalized to canonical forms.
+- VEX mapping ties vulnerability statements to SBOM components.
+- Version range handling uses ecosystem-native semantics.
+
+Remediation heuristics
+- Prefer fixed version guidance when present.
+- Track component removal or replacement as remediation.
+- Record justification when remediation is deferred.
+
+Determinism rules
+- Stable ordering of components and dependencies.
+- Canonical JSON before hashing and signing.
+- Content-addressed references in evidence bundles.
+
+Related references
+- docs/sbom/remediation-heuristics.md
+- docs/sbom/vex-mapping.md
+- docs/sbom/vuln-resolution.md

docs2/security-and-governance.md

@@ -1,22 +1,30 @@
 # Security and governance
 
-## Security policy
+Security policy
 - Coordinated disclosure with a defined SLA and published keys.
 - Security fixes are prioritized for supported release lines.
 
-## Hardening guidance
+Hardening guidance
 - Non-root containers and read-only filesystems.
 - TLS for all external traffic, optional mTLS internally.
 - DPoP or mTLS sender constraints for tokens.
 - Signed artifacts and verified plugin signatures.
 - No mandatory outbound traffic for core verification paths.
 
-## Governance
-- Lazy consensus with maintainer review for non-trivial changes.
+Governance
+- Maintainer review for non-trivial changes.
 - Explicit security review for sensitive changes.
-- Contribution rules and code of conduct apply to all repos.
+- Code of conduct applies across all contributions.
 
-## Compliance and evidence
+Compliance and evidence
 - Evidence is content-addressed, signed, and replayable.
 - Audit packages include decision traces, inputs, and signatures.
 - Unknowns are preserved and surfaced, not hidden.
+
+Related references
+- docs/13_SECURITY_POLICY.md
+- docs/17_SECURITY_HARDENING_GUIDE.md
+- docs/11_GOVERNANCE.md
+- docs/12_CODE_OF_CONDUCT.md
+- docs/28_LEGAL_COMPLIANCE.md
+- docs2/legal/regulator-threat-evidence.md

docs2/security/admin-rbac.md

@@ -0,0 +1,63 @@
+# Console admin RBAC
+
+Purpose
+- Provide a unified Authority-backed admin surface for tenants, users, roles, clients, tokens, and audit.
+- Keep browser admin flows DPoP-based while reserving mTLS-only endpoints for automation.
+- Normalize scope and role bundles so UI, CLI, and APIs align across modules.
+
+Admin API tiers
+- /admin: mTLS + authority.admin for automation and ops tooling.
+- /console/admin: DPoP + ui.admin and authority scopes for browser and CLI admin flows.
+- Both tiers share the same data model and audit stream.
+
+Authority-owned entities
+- Tenant: display name, status, isolation mode, default roles.
+- Installation: tenant binding and bootstrap metadata.
+- Role: scopes, audiences, flags (interactive-only, fresh-auth required).
+- User: subject, status, tenant assignments, role bindings.
+- Client: grant types, auth method, scopes, audiences, tenant hint.
+- Token record: access and refresh metadata with revocation state.
+- Audit events: immutable admin and auth events.
+
+Fresh-auth window
+- Required for tenant suspend/resume, token revocation, role edits, client rotation, branding apply.
+- Authority enforces auth_time within a short TTL (five minutes default).
+
+Admin scopes (core)
+- authority:tenants.read|write
+- authority:users.read|write
+- authority:roles.read|write
+- authority:clients.read|write
+- authority:tokens.read|revoke
+- authority:audit.read
+- authority:branding.read|write
+- ui.admin
+
+Module role bundle pattern
+- Roles follow role/<module>-viewer, role/<module>-operator, role/<module>-admin.
+- Viewer maps to read scopes, operator adds run or mutate, admin adds write and admin.
+- Scanner scopes are scanner:read, scanner:scan, scanner:export, scanner:write.
+- Scheduler scopes are scheduler:read, scheduler:operate, scheduler:admin.
+- Policy roles separate author, reviewer, approver, operator, and auditor scopes.
+- Notify, Export Center, Graph, Signals, Attestor, Signer, SBOM, Release, Airgap, and Task Packs
+  follow the same read/run/admin naming pattern with module-specific scopes.
+
+Console admin endpoints (subset)
+- GET/POST /console/admin/tenants
+- PATCH /console/admin/tenants/{tenantId}
+- POST /console/admin/tenants/{tenantId}/suspend|resume
+- GET/POST /console/admin/users and PATCH /console/admin/users/{userId}
+- GET/POST /console/admin/roles and PATCH /console/admin/roles/{roleId}
+- GET/POST /console/admin/clients and POST /console/admin/clients/{clientId}/rotate
+- POST /console/admin/tokens/revoke
+- GET /console/admin/audit
+
+Offline-first administration
+- Admin changes can be exported as signed bundles for air-gapped import.
+- Console surfaces pending status when Authority is offline.
+- Authority applies bundles through /admin/bundles/apply (mTLS).
+
+Related references
+- docs/architecture/console-admin-rbac.md
+- docs/security/scopes-and-roles.md
+- docs/security/authority-scopes.md

docs2/security/audit-events.md

@@ -0,0 +1,30 @@
+# Audit events
+
+Authority emits structured audit records for all credential and bootstrap flows.
+Records are deterministic and safe for offline export.
+
+Core fields
+- eventType: canonical name such as authority.password.grant.
+- occurredAt: UTC timestamp.
+- correlationId: stable identifier for tracing.
+- outcome: success, failure, lockedOut, rateLimited, error.
+- subject: identity fields marked as PII.
+- client: OAuth client identity and provider.
+- scopes: sorted list of granted or requested scopes.
+- network: remote address and user agent (PII).
+- properties: additional context such as lockout or tamper flags.
+
+Data classification
+- Fields are tagged as None, Personal, or Sensitive.
+- Downstream sinks can redact or isolate PII and sensitive fields.
+
+Event naming
+- Use authority.<surface>.<action> naming for determinism.
+- Examples: authority.token.tamper, authority.bootstrap.invite.created.
+
+Persistence and export
+- Stored in Authority login attempt collections with summary fields.
+- Exports must honor classification tags and redact PII as required.
+
+Related references
+- docs/security/audit-events.md

docs2/security/console-security.md

@@ -0,0 +1,46 @@
+# Console security posture
+
+Identity and token flow
+- OAuth 2.1 authorization code with PKCE.
+- DPoP-bound access tokens with short TTL; refresh tokens rotate when enabled.
+- DPoP keypair stored as non-exportable WebCrypto key (IndexedDB) and never in localStorage.
+- All API calls include Authorization and DPoP proof headers; gateway enforces tenant header.
+
+Fresh-auth gating
+- Sensitive operations require a fresh-auth window (default five minutes).
+- UI disables guarded actions when the window expires.
+- Authority emits audit events for fresh-auth start, success, and expiry.
+
+Session handling
+- Tokens remain in memory; metadata stored in sessionStorage only.
+- Idle timeout defaults to 15 minutes; failed refresh requires re-auth.
+- Device binding through DPoP prevents token replay across devices.
+
+Scopes and separation of duties
+- ui.admin is required for admin workspace access.
+- Policy approvals and promotions require policy:approve or policy:operate plus fresh-auth.
+- Do not combine ui.admin and policy:approve for the same human role without SOC review.
+
+Transport and browser hardening
+- TLS 1.2+ with HSTS and strict forward headers.
+- CSP defaults to self-only with explicit connect-src allowlists.
+- Enable COOP and COEP when WASM-based previews are required.
+- Deny framing and disable cache for JSON API responses.
+
+Evidence and data handling
+- Console surfaces digests and signatures but does not cache evidence bundles.
+- Downloads require CLI parity; the UI only brokers metadata.
+- Logs redact tokens, emails, and attachment paths.
+
+Offline posture
+- Offline mode uses pre-issued tokens and shows staleness banners.
+- Fresh-auth prompts are replaced with CLI guidance in sealed mode.
+- Unsigned offline assets block startup until verified.
+
+Monitoring expectations
+- Track DPoP failures, tenant mismatches, and fresh-auth prompts.
+- Correlate UI logs with Authority audit events using shared correlation IDs.
+
+Related references
+- docs/security/console-security.md
+- docs/architecture/console-admin-rbac.md

docs2/security/crypto-and-trust.md

@@ -0,0 +1,34 @@
+# Crypto profiles and trust
+
+StellaOps supports regional crypto profiles and offline trust roots. Profiles
+control signing algorithms, verification rules, and provider selection.
+
+Crypto profiles
+- Compliance profile id: world, fips, gost, sm, kcmvp, eidas.
+- Provider registry selects preferred crypto implementations.
+- Simulation mode provides a remote signer for pre-certification testing.
+
+Trust and signing
+- DSSE is the default for bundle manifests and attestations.
+- Trust roots are distributed in RootPack snapshots for offline validation.
+- Optional TUF metadata can be bundled in sealed environments.
+
+Signed time anchors
+- Offline time anchors include issuedAt, notAfter, and signature.
+- Time anchors are verified locally against trust roots.
+
+Rotation
+- Rotate roots with overlapping validity windows.
+- Ship new roots in the next offline bundle and re-sign manifests.
+- Maintain audit logs for rotation events.
+
+Evidence expectations
+- JWKS exports for active providers.
+- Fixed-message sign and verify logs for audit trails.
+
+Related references
+- docs/security/crypto-profile-configuration.md
+- docs/security/trust-and-signing.md
+- docs/security/crypto-simulation-services.md
+- docs/security/crypto-compliance.md
+- docs/airgap/staleness-and-time.md

docs2/security/crypto-compliance.md

@@ -0,0 +1,33 @@
+# Crypto compliance
+
+Profiles
+- world (default), fips, gost, sm, kcmvp, eidas, pq (software only).
+- Each profile selects hash and signing algorithms by purpose.
+- Profiles are mutually exclusive per deployment.
+
+Profile selection
+- Crypto:ProfileId in config or STELLAOPS_CRYPTO_PROFILE environment variable.
+
+Algorithm mapping highlights
+- Graph hashing uses BLAKE3 only in world profile; others use SHA-256 or regional hashes.
+- Interop hashes and webhook HMACs always use SHA-256 for external compatibility.
+- Password hashing uses Argon2id by default; PBKDF2-SHA256 is used for FIPS profile.
+
+Provider gating
+- Software providers are allow-listed and flagged non-certified until hardware modules are attached.
+- Regional profiles (gost, sm, kcmvp, eidas) require explicit enablement gates.
+- PQ profile uses software primitives only; certified PQ hardware is not assumed.
+
+Distribution and licensing notes
+- GOST support is distributed in a separate RootPack_RU variant.
+- CryptoPro CSP is customer-provided and not redistributed by StellaOps.
+- Operators must accept vendor EULAs and provide licensed binaries when required.
+
+Export control posture
+- Default distributions ship with widely available algorithms.
+- Regional algorithms are opt-in and documented as customer responsibility.
+
+Related references
+- docs/security/crypto-compliance.md
+- docs/legal/crypto-compliance-review.md
+- docs/security/crypto-profile-configuration.md

docs2/security/forensics-and-evidence-locker.md

@@ -30,4 +30,5 @@ Minimum bundle layout
 Related references
 - docs/forensics/evidence-locker.md
 - docs/forensics/provenance-attestation.md
+- docs/forensics/timeline.md
 - docs/evidence-locker/evidence-pack-schema.md

docs2/security/identity-tenancy-and-scopes.md

@@ -0,0 +1,75 @@
+# Identity, tenancy, and scopes
+
+Authority issues short-lived tokens bound to tenants and scopes. Tenancy is
+enforced at every service boundary.
+
+Token model
+- tenant: required for all tenant-scoped APIs.
+- scopes: list of granted permissions.
+- service_identity: required for privileged write scopes.
+- auth_time: used for fresh auth enforcement.
+- reason and ticket fields: required for sensitive operations.
+- act claim: present for delegated service accounts.
+
+Tenancy propagation
+- Gateways attach the tenant claim to a header (X-StellaOps-Tenant or configured).
+- Services reject missing or mismatched tenant headers.
+- All audit events record tenant and scope for traceability.
+
+Scope categories (examples)
+- Ingestion: advisory:ingest, vex:ingest.
+- Verification: aoc:verify (required with advisory:read or vex:read).
+- Signals: signals:read, signals:write.
+- Policy: policy:author, policy:approve, policy:publish, policy:promote.
+- Findings: effective:write (Policy Engine only), findings:read.
+- Observability: obs:read, timeline:read, timeline:write, evidence:read.
+- Ops: airgap:status:read, airgap:import, airgap:seal.
+- Automation: packs.read, packs.run, packs.approve.
+- Notifications: notify.viewer, notify.operator, notify.admin.
+
+Scope enforcement rules
+- advisory:read and vex:read require aoc:verify.
+- effective:write requires service_identity = policy-engine.
+- graph:write requires service_identity = cartographer.
+- Ingest scopes must not be combined with effective:write.
+
+Scope matrix (examples)
+| Module | Typical roles | Scopes |
+| --- | --- | --- |
+| Concelier | concelier-ingest | advisory:ingest, advisory:read, aoc:verify |
+| Excititor | excititor-ingest | vex:ingest, vex:read, aoc:verify |
+| Policy Engine | policy-engine | effective:write, findings:read |
+| Scanner | scanner-operator | scanner:read, scanner:scan, scanner:export |
+| Graph | cartographer-service | graph:write, graph:read |
+| Notify | notify-operator | notify.viewer, notify.operator |
+| Export Center | export-operator | export.viewer, export.operator |
+| Airgap | airgap-operator | airgap:status:read, airgap:import |
+| Observability | obs-investigator | obs:read, timeline:read, timeline:write, evidence:read |
+| Task Runner | packs-runner | packs.read, packs.run |
+
+Role bundles
+- Roles group scopes for common workflows (scanner, policy, notify, export).
+- Policy author role: policy:author, policy:read, policy:simulate.
+- Policy approver role: policy:approve, policy:review, policy:read.
+- Pack runner role: packs.read, packs.run.
+- Observability incident commander role: obs:read, obs:incident, timeline:write.
+
+Fresh auth and MFA
+- Policy publish and promote require fresh auth (auth_time window).
+- Exception approvals can require MFA when routing templates demand it.
+- Sensitive scopes require reason and ticket metadata for audit.
+
+Delegation and service accounts
+- Delegated accounts mint limited tokens for automation.
+- Authority enforces per-tenant quotas and allowedScopes lists.
+- Delegated tokens include act and service account identifiers.
+
+Offline notes
+- Offline kits can include scoped tokens with short expirations.
+- Rotate tokens and trust roots on a fixed schedule.
+- Avoid long-lived admin scopes in sealed environments.
+
+Related references
+- docs/security/authority-scopes.md
+- docs/architecture/console-admin-rbac.md
+- docs/modules/authority/architecture.md

docs2/security/operational-hardening.md

@@ -0,0 +1,42 @@
+# Security hardening
+
+Sender constraints (DPoP and mTLS)
+- DPoP is required for browser tokens; proofs are nonce protected.
+- Authority stores cnf.jkt and validates it on introspection.
+- mTLS-bound tokens are required for high-assurance tenants and automation.
+- Emergency bypass is logged and should be time-boxed.
+
+Rate limiting and lockout
+- Fixed-window limits on /token and /authorize protect against brute force.
+- Retry-After headers and structured logs are required for audit.
+- Lockout policies complement rate limiting and should remain enabled.
+
+Password hashing
+- Argon2id is the default for Authority identity providers.
+- PBKDF2-SHA256 remains supported for legacy hashes and FIPS profile.
+- Successful legacy verification rehashes to Argon2id.
+
+Secrets handling
+- Services store secretRef only; secret values are never persisted.
+- Secrets must not appear in logs, traces, or exports.
+- Rotation is handled through Authority and refreshed by workers at step start.
+
+Notifications hardening
+- Tenant isolation enforced on rules and delivery ledger.
+- Webhook deliveries are signed with HMAC-SHA256 and include nonce or timestamp.
+- Outbound allowlists default to block public internet in air-gapped kits.
+
+Export hardening
+- Exports include content hashes and optional DSSE manifests.
+- Export endpoints enforce tenant scoping and export-specific scopes.
+- Redaction rules default to exclude secrets and sensitive fields.
+
+Related references
+- docs/security/dpop-mtls-rollout.md
+- docs/security/password-hashing.md
+- docs/security/secrets-handling.md
+- docs/security/rate-limits.md
+- docs/security/notifications-hardening.md
+- docs/security/export-hardening.md
+- docs/security/audit-events.md
+- docs/security/revocation-bundle.md

docs2/security/quota-and-licensing.md

@@ -0,0 +1,29 @@
+# Quota and offline licensing
+
+Offline deployments use a signed JWT to enforce a daily scan quota. The token
+is verified locally and does not require a network call.
+
+Token claims (summary)
+- sub: licensee id
+- iat and exp: issuance and expiry times
+- tier: max scans per UTC day
+- tid: token id
+- pkg: product edition
+
+Enforcement
+- Counters are tracked per UTC day.
+- Invalid or expired tokens fall back to the anonymous quota.
+- Optional policy can hard-fail on invalid tokens.
+
+Supply paths
+- Docker secret or bind-mounted file is preferred.
+- Environment variable is supported with restart.
+
+Threat model notes
+- Optional host binding to prevent token reuse.
+- Hash chain and monotonic clock guard against rollback.
+
+Related references
+- docs/license-jwt-quota.md
+- docs/30_QUOTA_ENFORCEMENT_FLOW1.md
+- docs/33_333_QUOTA_OVERVIEW.md

docs2/security/revocation-bundles.md

@@ -0,0 +1,30 @@
+# Revocation bundles
+
+Authority exports revocation data as an offline-friendly JSON bundle with a
+detached JWS signature. Bundles are mirrored with other offline feeds.
+
+Bundle contents
+- revocation-bundle.json: canonical JSON payload.
+- revocation-bundle.json.jws: detached signature (RFC 7797).
+- revocation-bundle.json.sha256: optional digest for mirroring.
+
+Deterministic formatting
+- UTF-8 JSON with stable key ordering.
+- Arrays sorted by category, id, and revokedAt.
+- Timestamps use UTC ISO-8601 with Z.
+
+Revocation categories
+- token, subject, client, key.
+- reason codes include compromised, rotation, policy, lifecycle.
+
+Verification flow
+- Validate schema, recompute sha256, then verify detached JWS.
+- Key resolution uses JWKS or offline key bundles.
+
+Operational notes
+- Bundles are monotonic by sequence and issuedAt.
+- Export a fresh bundle after key rotation.
+
+Related references
+- docs/security/revocation-bundle.md
+- docs/security/revocation-bundle-example.json

docs2/security/risk-model.md

@@ -9,6 +9,12 @@ Core concepts
 - Profiles define weights, thresholds, and overrides.
 - Formulas aggregate factors into scores and severity.
 
+Signal sources (examples)
+- CVSS severity and vectors (v4 supported).
+- KEV flags and exploit history.
+- EPSS percentiles for exploit likelihood.
+- Reachability and runtime evidence.
+
 Lifecycle
 1. Job submit with tenant, profile, and findings.
 2. Evidence ingestion from scanners, reachability, and VEX.
@@ -33,3 +39,4 @@ Related references
 - docs/risk/formulas.md
 - docs/risk/profiles.md
 - docs/risk/api.md
+- docs/guides/epss-integration.md

docs2/signals/callgraph-schema.md

@@ -0,0 +1,48 @@
+# Callgraph schema (stella.callgraph.v1)
+
+Purpose
+- Represent static and runtime call graphs for reachability.
+- Preserve provenance, entrypoints, and explainable edge reasons.
+
+Top-level fields
+- schema: fixed string stella.callgraph.v1.
+- nodes: symbol nodes with ids, names, and metadata.
+- edges: call edges between nodes.
+- entrypoints: entry nodes and routes.
+- artifacts: optional artifacts list for mapping nodes to binaries.
+- metadata: graph-level info (language, component, version, ingestedAt).
+- graphHash: sha256 of canonical content for deduplication.
+
+Core enumerations (examples)
+- Language: DotNet, Java, Node, Python, Go, Rust, Binary.
+- EdgeKind: static, heuristic, runtime.
+- EdgeReason: directCall, virtualCall, reflectionString, dynamicImport, runtimeMinted.
+- EntrypointKind: http, grpc, cli, job, event, timer, main.
+
+Node shape (key fields)
+- id, name, kind, namespace, file, line.
+- symbolKey: canonical signature for the symbol.
+- visibility: public, internal, protected, private.
+- isEntrypointCandidate: boolean.
+- attributes: extra metadata such as http method and route.
+
+Edge shape (key fields)
+- sourceId, targetId.
+- kind, reason, weight, isResolved.
+- candidates for unresolved dynamic dispatch.
+
+Determinism rules
+- Sort nodes by id, edges by sourceId then targetId, entrypoints by order.
+- Enums serialize as camelCase strings.
+- Timestamps use UTC ISO-8601.
+- graphHash uses SHA-256 over canonical JSON.
+
+Validation rules
+- Node ids are unique.
+- Edge endpoints reference existing nodes.
+- Entrypoint nodeIds reference existing nodes.
+- Edge weights are within 0.0 to 1.0.
+
+Related references
+- docs/signals/callgraph-formats.md
+- docs/reachability/README.md

docs2/signals/contract-mapping.md

@@ -0,0 +1,34 @@
+# Signal contract mapping
+
+StellaOps implements advisory signal contracts using domain-specific models.
+The signals align to five core concepts:
+
+Mapping summary
+| Advisory signal | StellaOps equivalent | Purpose |
+| --- | --- | --- |
+| Signal-10 (SBOM intake) | SBOM ingestion + callgraph ingest | Normalize SBOMs and call graphs with tenant and source metadata. |
+| Signal-12 (Evidence) | in-toto statements + DSSE envelopes | Signed attestations and evidence bundles. |
+| Signal-14 (Triage fact) | Triage finding, reachability, risk, and VEX entities | Aggregated facts for a vuln and component. |
+| Signal-16 (Diff delta) | Triage snapshot + smart-diff + drift causes | Deterministic change detection between runs. |
+| Signal-18 (Decision) | Triage decision + policy decision attestation | Final decision with rationale and signatures. |
+
+Evidence references
+- DSSE envelopes are addressed by sha256 of the envelope payload.
+- CAS URIs reference content-addressed evidence blobs (graphs, traces).
+
+Idempotency
+- Event envelopes include explicit idempotency keys.
+- Findings use stable identifiers derived from CVE and subject context.
+
+API surface alignment
+- SBOM ingest endpoints map to scanner and signals ingest.
+- Decision and diff endpoints map to triage and smart-diff APIs.
+
+Key equivalence guarantees
+- Subject digests and PURLs are preserved across ingestion and triage.
+- Reachability and VEX evidence is attached to findings, not rewritten.
+- Decisions carry rationale and policy references suitable for audit.
+
+Related references
+- docs/architecture/signal-contract-mapping.md
+- docs/07_HIGH_LEVEL_ARCHITECTURE.md

docs2/signals/uncertainty.md

@@ -0,0 +1,30 @@
+# Uncertainty and entropy
+
+Uncertainty captures missing or untrusted evidence as first-class signals.
+It prevents silent false negatives and feeds risk scoring and policy gates.
+
+Core states (examples)
+- U1: MissingSymbolResolution
+- U2: MissingPurl
+- U3: UntrustedAdvisory
+- U4: Unknown (no analysis yet)
+
+Tiers and scoring
+- Tiers group states by entropy ranges.
+- The aggregate tier is the maximum severity present.
+- Risk score adds an entropy-based modifier.
+
+Policy guidance
+- High uncertainty blocks not_affected claims.
+- Lower tiers allow decisions with caveats.
+- Remediation hints are attached to findings.
+
+Determinism rules
+- Stable ordering of uncertainty states.
+- UTC timestamps and fixed precision for entropy values.
+- Canonical JSON for hashing and replay.
+
+Related references
+- docs/uncertainty/README.md
+- docs/reachability/lattice.md
+- docs/policy/dsl.md

docs2/signals/unknowns-ranking.md

@@ -0,0 +1,30 @@
+# Unknowns ranking
+
+Unknowns are prioritized using a deterministic, multi-factor score and
+assigned to triage bands that drive rescan scheduling.
+
+Scoring formula
+- Score = wP*P + wE*E + wU*U + wC*C + wS*S (clamped to 0.0-1.0).
+- Factors: Popularity (P), Exploit potential (E), Uncertainty density (U),
+  Centrality (C), Staleness (S).
+- Default weights: P 0.25, E 0.25, U 0.25, C 0.15, S 0.10.
+
+Band thresholds
+- HOT: score >= 0.70 (immediate rescan, 15-minute cadence).
+- WARM: 0.40 <= score < 0.70 (scheduled rescan, 12-72 hours).
+- COLD: score < 0.40 (weekly batch).
+
+Determinism and replay
+- Each scored unknown stores a normalization trace with raw values,
+  normalized values, weights, and computed score.
+- Replaying the trace yields the same score and band.
+
+Configuration (Signals:UnknownsScoring)
+- WeightPopularity, WeightExploitPotential, WeightUncertainty,
+  WeightCentrality, WeightStaleness.
+- HotThreshold, WarmThreshold, HotRescanMinutes, WarmRescanHours,
+  ColdRescanDays.
+
+Related references
+- docs/signals/unknowns-ranking.md
+- docs/signals/unknowns-registry.md

docs2/signals/unknowns.md

@@ -0,0 +1,40 @@
+# Signals and unknowns
+
+Unknowns are first-class signals that capture gaps in identity, reachability,
+or evidence mapping. They prevent silent false negatives.
+
+Unknowns registry model
+- Deterministic id based on type, scope, and evidence.
+- Includes provenance, scope, unknown_type, evidence, and status.
+- Stores confidence metrics and exposure hints.
+
+Producers
+- Scanner: unresolved symbols or missing mappings.
+- Signals: runtime hits without graph linkage.
+- SbomService: conflicting versions or hash mismatches.
+- Policy: undecidable cases due to missing evidence.
+
+Consumers
+- Risk and reachability scoring uses unknowns pressure.
+- Policy gates can block not_affected when unknowns are high.
+- UI and CLI provide triage and suppression workflows.
+
+Ranking and triage bands
+- Unknowns are scored using popularity, exploit potential, uncertainty, centrality, and staleness.
+- Bands: hot, warm, cold drive rescan cadence.
+
+API sketch
+- POST /unknowns/ingest for idempotent upserts.
+- GET /unknowns with filters by artifact and status.
+- POST /unknowns/{id}/triage to update status and labels.
+
+Storage
+- Append-only store with CAS references for large evidence blobs.
+- Tenant isolation and schema versioning for replay.
+
+Related references
+- docs/signals/unknowns-registry.md
+- docs/signals/unknowns-ranking.md
+- docs/uncertainty/README.md
+- docs2/signals/uncertainty.md
+- docs2/signals/unknowns-ranking.md

docs2/specs/symbols.md

@@ -0,0 +1,38 @@
+# Symbol manifest and bundles
+
+Purpose
+- Publish debug symbols and source maps for reachability and runtime overlays.
+- Keep symbol artifacts deterministic and offline friendly.
+
+Symbol manifest v1
+- schema: stellaops.symbols/manifest@v1
+- artifactDigest: build or container digest
+- entries: debug bundles with debugId, os, arch, format, hash, path, size
+- sourceMaps: optional sourcemap entries
+- toolchain and provenance metadata
+- Manifest JSON is canonicalized and DSSE-signed.
+
+DebugId derivation (examples)
+- ELF: build-id (or SHA-256 of .text fallback)
+- PE/COFF: pdbGuid:pdbAge
+- Mach-O: LC_UUID
+- JVM: jar SHA-256 + class and method signature
+- Node/TS: asset SHA-256 + sourceMap URL
+
+Packaging guidance
+- Deterministic tarball: stable ordering, mtime=0, uid=gid=0.
+- Include manifest.json and manifest.json.sha256.
+- Optional OCI artifact media type: application/vnd.stella.symbols.manifest.v1+json.
+
+Upload and resolve APIs
+- POST /v1/symbols/upload with signed manifest and blobs.
+- GET /v1/symbols/resolve for lookup by tenant, os, arch, debugId.
+- POST /v1/lookup/addresses for symbolization of addresses.
+
+Offline bundles
+- Bundle includes the signed manifest, blobs, and optional transparency proofs.
+- Content-addressed CAS prefixes are used for reproducibility.
+
+Related references
+- docs/specs/SYMBOL_MANIFEST_v1.md
+- docs/specs/symbols/bundle-guide.md

docs2/task-packs.md

@@ -14,6 +14,12 @@ Key features
 - Evidence bundles with plan hashes and artifacts
 - RBAC scopes for discover, run, and approve
 
+Signing and RBAC
+- Packs are signed with cosign and DSSE attestations.
+- Registry enforces trust policy (keyRef, issuer, threshold).
+- Scopes: packs.read, packs.write, packs.run, packs.approve.
+- Approvals include runId, gateId, and planHash and require fresh-auth.
+
 Determinism and validation
 - Canonical plan hash and inputs lock file
 - Stable ordering and fixed timestamps

docs2/topic-map.md

@@ -8,12 +8,33 @@ Product and positioning
   docs/04_FEATURE_MATRIX.md, docs/05_SYSTEM_REQUIREMENTS_SPEC.md, docs/05_ROADMAP.md
 - Docs2: product/overview.md, product/roadmap-and-requirements.md
 
+Market positioning and claims
+- Sources: docs/market/*, docs/marketing/*, docs/claims-index.md
+- Docs2: product/market-positioning.md, product/claims-and-benchmarks.md
+
 Architecture and system model
 - Sources: docs/07_HIGH_LEVEL_ARCHITECTURE.md, docs/high-level-architecture.md,
   docs/ARCHITECTURE_DETAILED.md, docs/40_ARCHITECTURE_OVERVIEW.md,
   docs/modules/platform/architecture-overview.md, docs/modules/*/architecture.md
 - Docs2: architecture/overview.md, architecture/workflows.md, modules/index.md
 
+Component map
+- Sources: docs/technical/architecture/component-map.md
+- Docs2: architecture/component-map.md
+
+Ingestion and aggregation (AOC, linksets)
+- Sources: docs/ingestion/aggregation-only-contract.md, docs/aoc/*,
+  docs/advisories/aggregation.md, docs/vex/aggregation.md
+- Docs2: ingestion/aggregation-and-linksets.md
+
+AOC guardrails and library
+- Sources: docs/aoc/aoc-guardrails.md, docs/aoc/guard-library.md
+- Docs2: ingestion/aoc-guardrails.md
+
+AOC linkset backfill
+- Sources: docs/concelier/backfill/*
+- Docs2: ingestion/backfill.md
+
 Evidence and determinism
 - Sources: docs/replay/*, docs/contracts/*, docs/ingestion/*, docs/data/*,
   docs/11_DATA_SCHEMAS.md, docs/ARCHITECTURE_DETAILED.md
@@ -22,21 +43,75 @@ Evidence and determinism
 Reachability, VEX, unknowns
 - Sources: docs/reachability/*, docs/vex/*, docs/signals/*, docs/modules/signals/*,
   docs/modules/vex-lens/architecture.md, docs/modules/vexlens/architecture.md
-- Docs2: architecture/reachability-vex.md
+- Docs2: architecture/reachability-vex.md, signals/unknowns.md, signals/uncertainty.md
+
+Reachability lattice and evidence
+- Sources: docs/reachability/lattice.md, docs/reachability/evidence-schema.md,
+  docs/reachability/edge-explainability-schema.md, docs/reachability/runtime-static-union-schema.md
+- Docs2: architecture/reachability-lattice.md, architecture/reachability-evidence.md
+
+VEX consensus
+- Sources: docs/vex/consensus-overview.md, docs/vex/consensus-json.md
+- Docs2: vex/consensus.md
+
+Callgraph schema
+- Sources: docs/signals/callgraph-formats.md
+- Docs2: signals/callgraph-schema.md
+
+Signal contract mapping
+- Sources: docs/architecture/signal-contract-mapping.md
+- Docs2: signals/contract-mapping.md
+
+Unknowns ranking
+- Sources: docs/signals/unknowns-ranking.md
+- Docs2: signals/unknowns-ranking.md
 
 Modules and services
 - Sources: docs/modules/* (architecture, README, operations, runbooks)
 - Docs2: modules/index.md
 
+Advisory AI
+- Sources: docs/advisory-ai/*
+- Docs2: advisory-ai/overview.md
+
+Orchestrator detail
+- Sources: docs/orchestrator/*
+- Docs2: orchestrator/overview.md, orchestrator/architecture.md, orchestrator/api.md,
+  orchestrator/cli.md, orchestrator/console.md
+
+Orchestrator run ledger
+- Sources: docs/orchestrator/run-ledger.md
+- Docs2: orchestrator/run-ledger.md
+
 Operations and deployment
 - Sources: docs/21_INSTALL_GUIDE.md, docs/deploy/*, docs/install/*,
-  docs/operations/*, docs/runbooks/*
-- Docs2: operations/install-deploy.md
+  docs/operations/*, docs/runbooks/*, docs/quickstart.md
+- Docs2: operations/quickstart.md, operations/install-deploy.md
+
+Deployment versioning
+- Sources: docs/deployment/VERSION_MATRIX.md
+- Docs2: operations/deployment-versioning.md
+
+Binary prerequisites
+- Sources: docs/ops/binary-prereqs.md
+- Docs2: operations/binary-prereqs.md
+
+Runtime readiness
+- Sources: docs/runtime/SCANNER_RUNTIME_READINESS.md
+- Docs2: operations/runtime-readiness.md
+
+Service SLOs
+- Sources: docs/slo/*
+- Docs2: operations/slo.md
 
 Air-gap and offline kit
 - Sources: docs/24_OFFLINE_KIT.md, docs/10_OFFLINE_KIT.md, docs/airgap/*
 - Docs2: operations/airgap.md
 
+Air-gap bundles and runbooks
+- Sources: docs/airgap/overview.md, docs/airgap/offline-bundle-format.md, docs/airgap/runbooks/*
+- Docs2: operations/airgap-bundles.md, operations/airgap-runbooks.md
+
 Replay and determinism
 - Sources: docs/replay/*, docs/runbooks/replay_ops.md, docs/release/promotion-attestations.md
 - Docs2: operations/replay-and-determinism.md
@@ -45,6 +120,21 @@ Runbooks and incident response
 - Sources: docs/runbooks/*, docs/operations/*
 - Docs2: operations/runbooks.md
 
+Notifications
+- Sources: docs/notifications/*, docs/modules/notify/*
+- Docs2: operations/notifications.md
+
+Notifications details
+- Sources: docs/notifications/overview.md, docs/notifications/rules.md,
+  docs/notifications/channels.md, docs/notifications/templates.md,
+  docs/notifications/digests.md, docs/notifications/pack-approvals-integration.md
+- Docs2: notifications/overview.md, notifications/rules.md, notifications/channels.md,
+  notifications/templates.md, notifications/digests.md, notifications/pack-approvals.md
+
+Router rate limiting
+- Sources: docs/router/*
+- Docs2: operations/router-rate-limiting.md
+
 Release engineering and CI/DevOps
 - Sources: docs/13_RELEASE_ENGINEERING_PLAYBOOK.md, docs/ci/*, docs/devops/*,
   docs/release/*, docs/releases/*
@@ -55,16 +145,72 @@ API and contracts
   docs/contracts/*
 - Docs2: api/overview.md, api/auth-and-tokens.md, data-and-schemas.md
 
+Policy system
+- Sources: docs/policy/*, docs/60_POLICY_TEMPLATES.md
+- Docs2: policy/policy-system.md
+
 Contracts and interfaces
 - Sources: docs/contracts/*, docs/adr/*, docs/specs/*
 - Docs2: contracts-and-interfaces.md
 
+Scanner core contracts
+- Sources: docs/scanner-core-contracts.md
+- Docs2: contracts/scanner-core.md
+
+Symbols specification
+- Sources: docs/specs/SYMBOL_MANIFEST_v1.md, docs/specs/symbols/*
+- Docs2: specs/symbols.md
+
+SBOM handling
+- Sources: docs/sbom/*
+- Docs2: sbom/overview.md
+
 Security, governance, compliance
 - Sources: docs/13_SECURITY_POLICY.md, docs/17_SECURITY_HARDENING_GUIDE.md,
-  docs/11_GOVERNANCE.md, docs/12_CODE_OF_CONDUCT.md, docs/28_LEGAL_COMPLIANCE.md,
-  docs/29_LEGAL_FAQ_QUOTA.md, docs/33_333_QUOTA_OVERVIEW.md
+  docs/11_GOVERNANCE.md, docs/12_CODE_OF_CONDUCT.md, docs/28_LEGAL_COMPLIANCE.md
 - Docs2: security-and-governance.md
 
+Regulator threat and evidence model
+- Sources: docs/28_LEGAL_COMPLIANCE.md
+- Docs2: legal/regulator-threat-evidence.md
+
+Identity, tenancy, and scopes
+- Sources: docs/security/authority-scopes.md, docs/security/scopes-and-roles.md,
+  docs/architecture/console-admin-rbac.md
+- Docs2: security/identity-tenancy-and-scopes.md
+
+Console admin RBAC
+- Sources: docs/architecture/console-admin-rbac.md
+- Docs2: security/admin-rbac.md
+
+Crypto profiles and trust
+- Sources: docs/security/crypto-profile-configuration.md,
+  docs/security/trust-and-signing.md, docs/security/crypto-simulation-services.md
+- Docs2: security/crypto-and-trust.md
+
+Crypto compliance and licensing
+- Sources: docs/security/crypto-compliance.md, docs/legal/crypto-compliance-review.md
+- Docs2: security/crypto-compliance.md
+
+Security hardening
+- Sources: docs/security/dpop-mtls-rollout.md, docs/security/password-hashing.md,
+  docs/security/secrets-handling.md, docs/security/rate-limits.md,
+  docs/security/notifications-hardening.md, docs/security/export-hardening.md
+- Docs2: security/operational-hardening.md
+
+Audit events
+- Sources: docs/security/audit-events.md
+- Docs2: security/audit-events.md
+
+Revocation bundles
+- Sources: docs/security/revocation-bundle.md, docs/security/revocation-bundle-example.json
+- Docs2: security/revocation-bundles.md
+
+Quota and licensing
+- Sources: docs/license-jwt-quota.md, docs/30_QUOTA_ENFORCEMENT_FLOW1.md,
+  docs/33_333_QUOTA_OVERVIEW.md
+- Docs2: security/quota-and-licensing.md
+
 Risk model and scoring
 - Sources: docs/risk/*, docs/contracts/risk-scoring.md
 - Docs2: security/risk-model.md
@@ -73,6 +219,11 @@ Forensics and evidence locker
 - Sources: docs/forensics/*, docs/evidence-locker/*
 - Docs2: security/forensics-and-evidence-locker.md
 
+Provenance and transparency
+- Sources: docs/provenance/*, docs/security/trust-and-signing.md,
+  docs/modules/attestor/*, docs/modules/signer/*
+- Docs2: provenance/inline-provenance.md
+
 Database and persistence
 - Sources: docs/db/*, docs/adr/0001-postgresql-for-control-plane.md
 - Docs2: data/persistence.md
@@ -85,10 +236,81 @@ CLI and UI
 - Sources: docs/15_UI_GUIDE.md, docs/cli/*, docs/ui/*, docs/console/*, docs/ux/*
 - Docs2: cli-ui.md
 
+CLI reference
+- Sources: docs/cli/*
+- Docs2: cli/overview.md
+
+CLI command guides
+- Sources: docs/cli/command-reference.md, docs/cli/crypto-commands.md,
+  docs/cli/crypto-plugins.md, docs/cli/distribution-matrix.md,
+  docs/cli/reachability-cli-reference.md, docs/cli/drift-cli.md,
+  docs/cli/smart-diff-cli.md, docs/cli/triage-cli.md,
+  docs/cli/unknowns-cli-reference.md, docs/cli/score-proofs-cli-reference.md,
+  docs/cli/sbomer.md, docs/cli/audit-pack-commands.md,
+  docs/cli/keyboard-shortcuts.md, docs/cli/troubleshooting.md
+- Docs2: cli/commands.md, cli/crypto.md, cli/crypto-plugins.md,
+  cli/distribution-matrix.md, cli/reachability.md, cli/triage.md,
+  cli/unknowns.md, cli/score-proofs.md, cli/sbomer.md, cli/audit-pack.md,
+  cli/keyboard-shortcuts.md, cli/troubleshooting.md
+
+Console shell and navigation
+- Sources: docs/ui/console-overview.md, docs/ui/navigation.md
+- Docs2: ui/console.md, ui/navigation.md
+
+Console workspaces
+- Sources: docs/ui/console.md, docs/ui/findings.md, docs/ui/advisories-and-vex.md,
+  docs/ui/downloads.md, docs/ui/runs.md, docs/ui/policies.md
+- Docs2: ui/aoc-dashboard.md, ui/findings.md, ui/advisories-vex.md, ui/downloads.md,
+  ui/runs.md, ui/policies.md
+
+Console admin and governance
+- Sources: docs/ui/admin.md, docs/console/admin-tenants.md, docs/ui/exception-center.md
+- Docs2: ui/admin.md, ui/exception-center.md
+
+Console SBOM and vulnerability exploration
+- Sources: docs/ui/sbom-explorer.md, docs/ui/sbom-graph-explorer.md,
+  docs/ui/vulnerability-explorer.md, docs/ui/reachability-overlays.md
+- Docs2: ui/sbom-explorer.md, ui/sbom-graph-explorer.md,
+  ui/vulnerability-explorer.md, ui/reachability-overlays.md
+
+Console explainers
+- Sources: docs/ui/explainers.md
+- Docs2: ui/explainers.md
+
+Console air-gap and attestations
+- Sources: docs/console/airgap.md, docs/console/attestor-ui.md
+- Docs2: ui/airgap.md, ui/attestor.md
+
+Console forensics, observability, and risk
+- Sources: docs/console/forensics.md, docs/console/observability.md, docs/console/risk-ui.md
+- Docs2: ui/forensics.md, ui/observability.md, ui/risk-ui.md
+
+Console branding and accessibility
+- Sources: docs/ui/branding.md, docs/architecture/console-branding.md, docs/accessibility.md
+- Docs2: ui/branding.md, ui/accessibility.md
+
+Policy editor UI
+- Sources: docs/ui/policy-editor.md, docs/security/policy-governance.md
+- Docs2: ui/policy-editor.md
+
+Triage UX
+- Sources: docs/ux/TRIAGE_UX_GUIDE.md, docs/ux/TRIAGE_UI_REDUCER_SPEC.md
+- Docs2: ui/triage.md
+
+Console security
+- Sources: docs/security/console-security.md
+- Docs2: security/console-security.md
+
+Approvals and exceptions
+- Sources: docs/governance/approvals-and-routing.md, docs/governance/exceptions.md
+- Docs2: governance/approvals.md, governance/exceptions.md
+
 Developer and contribution
-- Sources: docs/DEVELOPER_ONBOARDING.md, docs/10_PLUGIN_SDK_GUIDE.md,
-  docs/18_CODING_STANDARDS.md, docs/contributing/*
-- Docs2: developer/onboarding.md, developer/plugin-sdk.md
+- Sources: docs/DEVELOPER_ONBOARDING.md, docs/onboarding/*,
+  docs/10_PLUGIN_SDK_GUIDE.md, docs/18_CODING_STANDARDS.md, docs/contributing/*,
+  docs/devportal/publishing.md, docs/process/implementor-guidelines.md
+- Docs2: developer/onboarding.md, developer/plugin-sdk.md, developer/devportal.md,
+  developer/implementation-guidelines.md
 
 SDKs and clients
 - Sources: docs/sdks/*
@@ -98,6 +320,18 @@ Task packs and automation
 - Sources: docs/task-packs/*
 - Docs2: task-packs.md
 
+Interoperability
+- Sources: docs/interop/*
+- Docs2: interop/sbom-interop.md, interop/cosign.md
+
+Migration guidance
+- Sources: docs/migration/*
+- Docs2: migration/overview.md
+
+Vuln Explorer overview
+- Sources: docs/vuln/*
+- Docs2: vuln-explorer/overview.md
+
 Testing and quality
 - Sources: docs/19_TEST_SUITE_OVERVIEW.md, docs/testing/*
 - Docs2: testing-and-quality.md
@@ -111,6 +345,14 @@ Benchmarks and performance
 - Sources: docs/benchmarks/*, docs/12_PERFORMANCE_WORKBOOK.md
 - Docs2: benchmarks.md
 
+Guides and workflows
+- Sources: docs/guides/*, docs/ci/sarif-integration.md
+- Docs2: guides/compare-workflow.md, guides/epss-integration.md
+
+Examples and fixtures
+- Sources: docs/examples/*, docs/samples/*, docs/schemas/*
+- Docs2: references/examples-and-fixtures.md
+
 Training and adoption
 - Sources: docs/training/*, docs/evaluate/*, docs/faq/*
 - Docs2: training-and-adoption.md

docs2/ui/accessibility.md

@@ -0,0 +1,31 @@
+# Console accessibility
+
+The console targets WCAG 2.2 AA and must remain usable with keyboard-only and
+screen-reader workflows in online and sealed environments.
+
+Core principles
+- Deterministic navigation and stable focus order.
+- Keyboard-first interaction with remappable shortcuts.
+- Assistive technology parity for status and progress updates.
+- Design tokens that maintain contrast targets.
+- Offline parity for banners, dialogs, and keyboard flows.
+
+Keyboard model
+- Global shortcuts for search, tenant switch, filters, and help.
+- Module shortcuts for findings, SBOM explorer, runs, and downloads.
+- Focus traps for dialogs and drawers with consistent return focus.
+
+Screen reader behavior
+- Polite live regions for background updates.
+- Assertive alerts for errors and blocking conditions.
+- Aria grid semantics for large tables.
+
+Testing
+- Automated axe checks in UI CI.
+- Playwright a11y sweeps on critical routes.
+- Manual screen reader spot checks before releases.
+
+Related references
+- docs/accessibility.md
+- docs/ui/*
+- docs/observability/ui-telemetry.md

docs2/ui/admin.md

@@ -0,0 +1,58 @@
+# Admin workspace
+
+Purpose
+- Centralize Authority-facing controls for tenants, roles, clients, tokens, integrations, and audit.
+
+Access and dependencies
+- Route: /console/admin with sub-routes for tenants, roles, users, clients, tokens, integrations, audit.
+- Scopes: ui.admin plus authority:* scopes for each tab.
+- Fresh-auth required for sensitive actions (revocations, key rotations, branding apply).
+- Depends on Authority admin APIs, revocation exports, JWKS, and licensing posture endpoints.
+
+Tenants
+- Create, edit, suspend, resume, and delete tenants (delete is gated and audited).
+- Tenant fields: slug, display name, status, isolation mode, default roles.
+- Offline snapshots show latest snapshot timestamp and checksum.
+- Export tenant bundle for air-gap distribution.
+- CLI parity: stella auth tenant create, stella auth tenant suspend.
+
+Roles and scopes
+- Table lists roles with mapped scopes and audiences.
+- Inline editor adds and removes scopes with validation and impact preview.
+- Role bundle catalog covers console, scanner, scheduler, policy, graph, observability.
+- CLI parity: stella auth role update.
+
+Users and tokens
+- User list includes roles, last login, and MFA status.
+- Token inventory lists access, refresh, and device tokens with status.
+- Token detail shows claims, sender constraint, issuance metadata, revocations.
+- Revoke and bulk revoke actions require fresh-auth and log audit events.
+- CLI parity: stella auth token revoke.
+
+Integrations
+- Client registrations list grant types, allowed scopes, DPoP or mTLS settings.
+- Bootstrap bundles provide templates for new clients and users.
+- External IdP connectors (SAML or OIDC) with metadata upload and test status.
+- Licensing posture panel is read-only.
+- Branding uploads are gated by fresh-auth.
+
+Audit
+- Timeline of admin events with filters (event type, actor, tenant, scope, correlation ID).
+- Export CSV or JSON for SOC ingestion.
+- Log pivot copies correlation ID search queries.
+
+Fresh-auth flow
+- Modal prompts for credential re-entry or hardware key touch.
+- Fresh-auth window lasts five minutes; sensitive buttons disabled outside the window.
+- Audit events recorded for fresh-auth start and success.
+
+Security guardrails
+- DPoP enforcement status and mTLS summaries for sensitive audiences.
+- Token policy checks for TTL and refresh rotation.
+- Revocation bundle export status with digest.
+- Signing key rotation panel with current kid and last rotation time.
+
+Offline behavior
+- Offline banner disables direct writes; UI generates offline apply scripts.
+- Token revocation and role changes produce bundles for offline Authority hosts.
+- Audit exports default to local paths with checksum output.

docs2/ui/advisories-vex.md

@@ -0,0 +1,75 @@
+# Advisories and VEX
+
+Purpose
+- Display Concelier advisories and Excititor VEX consensus without mutating upstream data.
+- Highlight provenance, conflicts, and verification status under Aggregation-Only rules.
+
+Access and dependencies
+- Routes: /console/advisories and /console/vex.
+- Scopes: advisory.read, vex.read; advisory.verify and vex.verify for verification actions; downloads.read for exports.
+- Depends on Concelier and Excititor aggregation APIs and Authority tenancy.
+- Feature flags: advisoryExplorer.enabled, vexExplorer.enabled, aggregation.conflictIndicators.
+
+Layout
+- Shared header with tenant badge, global filters, status ticker, and actions.
+- Tabs for Advisories and VEX; last view remembered per tenant.
+- Left rail includes saved views and provider filters.
+
+Advisory grid
+- Columns: vulnerability ID, title, source set, last merged, severity, KEV flag, affected count, merge hash.
+- Source chips list providers with precedence and timestamps.
+- Filters: ID search, provider, severity, KEV, affected count, time window.
+- Actions: open detail, compare sources, queue verify, copy CLI.
+
+Advisory detail drawer
+- Summary cards: title, timestamps, merge hash, total sources, exploited flag.
+- Sources timeline with signature status, precedence, and raw links.
+- Affected products table with semver or distro view toggle.
+- Conflict indicators for severity, fixed versions, affected sets.
+- References list and raw JSON viewer.
+- CLI parity for show, sources, and export commands.
+
+VEX explorer
+- Consensus table keyed by vulnerability and product.
+- Status badges: affected, not_affected, fixed, under_investigation.
+- Provider breakdown shows accepted or ignored claims with weights and justification.
+- Filters: product PURL, status, provider, justification code, confidence threshold.
+- Saved views for common triage scenarios.
+
+VEX detail drawer
+- Consensus summary with policy revision and confidence data.
+- Claims list grouped by provider tier with provenance and supersedes chains.
+- Conflict explainers show why claims were ignored.
+- Timeline events with correlation IDs.
+- Raw JSON viewer with CLI parity.
+
+Provenance and raw viewers
+- Provenance banner shows source URI, document digest, signature status, timestamps, collector version.
+- Raw documents are read-only and include DSSE bundle download when available.
+- Log pivot links copy correlation ID queries.
+
+Conflict indicators and AOC alignment
+- Conflicts are surfaced rather than merged in the UI.
+- Winning values and precedence are shown from Concelier metadata.
+- UI copy reminds users policy decisions happen elsewhere.
+
+Verification workflows
+- Verify actions call Concelier or Excititor endpoints scoped by tenant and filters.
+- Results summarize documents checked, signatures verified, and ERR_AOC codes.
+- Verification history is accessible from the status ticker.
+
+Exports and automation
+- Advisory exports: normalized advisory, affected products CSV, source bundle.
+- VEX exports: consensus snapshot, raw claims, provider deltas.
+- Export manifests include merge hash or consensus digest and signature state.
+- Webhook subscription snippets for export completion.
+
+Real-time updates
+- SSE refreshes advisory and VEX grids with delta badges.
+- Status ticker shows ingest lag and verification queue depth.
+
+Offline behavior
+- Snapshot banner shows staleness and disables live verification.
+- Raw downloads use local snapshot paths with checksum guidance.
+- Exports queue locally with removable media instructions.
+- Tenants missing from the snapshot are hidden.

docs2/ui/airgap.md

@@ -0,0 +1,25 @@
+# Console air-gap UI
+
+Purpose
+- Provide sealed-mode imports, staleness visibility, and guidance for offline operators.
+
+Surfaces
+- Air-gap status badge shows sealed state, mirrorGeneration, last import time, and staleness.
+- Import wizard uploads and verifies mirror bundles and records timeline events.
+- Staleness dashboard charts staleness by bundle and component.
+
+Staleness logic
+- Staleness = now minus bundle.createdAt using time anchors.
+- Color bands: green under 24h, amber 24h to 72h, red over 72h or missing anchor.
+
+Guidance banners
+- Sealed banner: egress denied, only registered bundles allowed.
+- Staleness red banner prompts import of the next bundle or time anchor refresh.
+
+Events
+- Successful import emits timeline event with bundleId, mirrorGeneration, manifest hash, actor.
+- Failed import emits error code without exposing stack traces.
+
+Security and guardrails
+- Admin scope required for imports; read-only users can view status only.
+- Hashes always include tenant and generation context.

docs2/ui/aoc-dashboard.md

@@ -0,0 +1,53 @@
+# AOC dashboard
+
+Purpose
+- Monitor Aggregation-Only Contract (AOC) ingestion guardrails across Concelier and Excititor sources.
+- Surface violations, verification results, and exportable evidence without mutating source data.
+
+Access and dependencies
+- Route: /console/sources.
+- Feature flag: aocDashboard.enabled.
+- Scopes: ui.read plus advisory.read and vex.read; aoc:verify for verify actions.
+- Depends on Concelier and Excititor guard endpoints and Authority tenant scoping.
+
+Layout
+- Source tiles for Concelier and Excititor feeds.
+- Violations and history table with filters.
+- Action bar: run verify, schedule verify, export evidence, open raw docs.
+
+Source tile fields
+- Status badge: healthy, warning, critical based on last ingest age and ERR_AOC violations.
+- Last ingest timestamp and relative age.
+- Violations in the last 24 hours grouped by ERR_AOC code.
+- Supersedes depth (average revision chain length).
+- Signature pass rate.
+- Ingestion latency P95.
+
+Violation drilldown
+- Filters by source, timeframe, ERR_AOC code, and severity.
+- Detail drawer shows provenance, signature status, supersedes chain, and redacted raw JSON.
+- Linked findings and policy overlays are shown as references only.
+- Annotations and acknowledgements are stored as structured audit notes.
+
+Verification and actions
+- Run verify posts to /aoc/verify with a since window; results include counts and top codes.
+- Schedule verify supports daily or weekly cadence with optional notifications.
+- Export evidence bundles include tile metrics, verification summaries, and annotations.
+- CLI parity: stella aoc verify --tenant <tenant> --since <window>.
+
+Observability
+- ingestion_write_total{source,tenant,result}
+- aoc_violation_total{source,tenant,code}
+- ingestion_signature_verified_total{source,result}
+- ingestion_latency_seconds{source,quantile}
+- advisory_revision_count{source}
+
+Security and tenancy
+- DPoP-bound tokens per tenant; data never crosses tenant boundaries.
+- Sensitive fields are redacted using Concelier rules.
+- Verify actions are rate limited and audited (action=aoc.verify.ui).
+
+Offline behavior
+- Offline snapshot banner shows snapshot time and bundle hash.
+- Verification requests queue for later execution and provide CLI guidance.
+- Evidence exports default to local paths for air-gap transfer.

docs2/ui/attestor.md

@@ -0,0 +1,19 @@
+# Attestor UI
+
+Purpose
+- View and verify attestations without deriving new verdicts.
+
+Surfaces
+- Attestation list and detail pages.
+- Verification status panel with raw results.
+
+Filters
+- Tenant, issuer, predicate type, verification status.
+
+Actions
+- Download DSSE bundle.
+- View transparency info when available.
+- Export verification record.
+
+Guardrails
+- UI displays raw verification state only; no derived judgments.

docs2/ui/branding.md

@@ -0,0 +1,42 @@
+# Console branding
+
+Purpose
+- Provide tenant-aware branding without rebuilding the UI.
+- Keep branding changes auditable, deterministic, and offline friendly.
+- Allow config defaults with per-tenant overrides after login.
+
+Branding record (Authority)
+- brandingId, tenantId, displayName
+- logo and favicon (data URI or asset reference)
+- themeTokens (CSS variable map for light, dark, high-contrast)
+- updatedBy, updatedAtUtc, hash (sha256 of canonical JSON)
+
+Constraints
+- Logo and favicon up to 256 KB each.
+- Allowed formats: image/svg+xml, image/png, image/jpeg.
+- Theme tokens limited to a whitelist; no arbitrary CSS.
+
+Configuration layering
+1) Static defaults from config.json.
+2) Tenant branding fetched after login.
+3) Session-only preview overrides (not persisted).
+- If Authority is unreachable, the UI uses static defaults.
+
+API surface
+- GET /console/branding (ui.read, authority:branding.read)
+- PUT /console/admin/branding (ui.admin, authority:branding.write, fresh-auth)
+- POST /console/admin/branding/preview (ui.admin, authority:branding.write)
+
+UI application
+- Branding service applies CSS variables to documentElement.
+- Updates header logo and document title.
+- Supports theme-specific tokens via data-theme selectors.
+
+Audit and offline
+- Branding updates emit authority.branding.updated events.
+- Branding bundles are exported with detached signatures for offline import.
+- Console displays the last applied branding hash for verification.
+
+Related references
+- docs/architecture/console-branding.md
+- docs/ui/branding.md

docs2/ui/console.md

@@ -0,0 +1,56 @@
+# Console overview
+
+Mission and principles
+- Single entry point for SBOMs, advisories, policies, runs, and admin controls.
+- Deterministic navigation with deep-linkable URLs.
+- Tenant isolation by default; explicit cross-tenant comparisons only.
+- Aggregation-only views for Concelier and Excititor outputs.
+- Offline parity for every view with visible staleness.
+
+Primary navigation
+- Dashboard: KPIs, feed age, queue depth, alerts.
+- Findings: policy verdicts, explain traces, and triage actions.
+- SBOM Explorer: catalog, components, overlays, exports.
+- Advisories and VEX: aggregated sources, provenance, conflicts.
+- Runs: scheduler runs, progress, evidence links.
+- Policies: editor, simulations, approvals.
+- Downloads: signed artifacts and offline kit parity.
+- Admin: tenants, roles, clients, tokens, branding.
+- Help: guides, tours, and release notes.
+
+Shared surfaces
+- Top bar: tenant picker, environment badge, offline status, user menu, notifications, command palette.
+- Global filter tray (Shift+F): tenant, time window, severity, tags, source providers, run status, policy view.
+- Context chips: active filters with one-click removal.
+- Status ticker: SSE-driven ingestion deltas and queue depth.
+
+Tenant model
+- Tenant list comes from Authority; switching issues a tenant-scoped, DPoP-bound token.
+- Cross-tenant comparisons are opt-in and render split panes with separate tokens.
+- Fresh-auth gates sensitive actions (admin changes, approvals).
+- Tenant switches emit audited events (ui.tenant.switch).
+
+Filters, presets, and deep links
+- Filters encoded in URLs (tenant, since/until, severity, view, panel, component).
+- Presets are saved per tenant and accessible via the command palette and Cmd/Ctrl+1..9.
+- Deep links map to CLI commands for deterministic offline replay.
+
+Aggregation-only alignment
+- Advisory and VEX pages read canonical aggregation endpoints.
+- Provenance badges show source lineage, precedence, and merge hashes.
+- UI does not reweight or rewrite aggregated data; actions route through guard endpoints.
+
+Performance and telemetry
+- LCP target under 2.5 seconds on a 4 vCPU offline runner with cached assets.
+- Route budget under 1.5 seconds after token resolution.
+- Telemetry signals: ui_route_render_seconds, ui_filter_apply_total, ui_tenant_switch_total, ui_offline_banner_seconds.
+
+Offline posture
+- Offline kits drive read-only views with snapshot ID and staleness banners.
+- Actions requiring Authority or verification show CLI guidance.
+- Tenants missing from the snapshot are hidden.
+
+Related references
+- ui/navigation.md
+- ui/downloads.md
+- ui/sbom-explorer.md

docs2/ui/downloads.md

@@ -0,0 +1,57 @@
+# Downloads workspace
+
+Purpose
+- Centralize signed artifacts, export bundles, and offline kit parity checks.
+- Provide CLI parity commands for reproducible artifact acquisition.
+
+Access and dependencies
+- Route: /console/downloads with /console/downloads/:artifactId detail drawer.
+- Scopes: downloads.read; downloads.manage for cancel or expire exports.
+- Depends on downloads manifest, offline kit metadata, and export orchestrator.
+- Feature flags: downloads.workspace.enabled, downloads.exportQueue, downloads.offlineParity.
+
+Workspace layout
+- Header shows manifest version, generatedAt, and signature status.
+- Cards for latest release, offline kit parity, export queue depth.
+- Tabs: artifacts, exports, offline kits, webhooks.
+- Filter bar: channel, kind, architecture, tags.
+
+Artifact catalog
+- Core containers, helm charts, compose bundles, offline kits, evidence exports, webhook configs.
+- Detail drawer shows metadata, provenance, commands, and history.
+- Digest-only pulls are the default; commands include arch hints.
+
+Manifest structure
+- version: monotonically increasing release integer.
+- generatedAt: ISO-8601 UTC timestamp.
+- signature: detached signature for manifest.json.
+- artifacts: ordered entries with id, kind, channel, version, digest, sizeBytes, downloadUrl, signatureUrl, sbomUrl, attestationUrl, docs, tags.
+- Console caches the manifest hash and highlights version changes.
+
+Download statuses
+- Ready: immutable artifacts with verified digests.
+- Pending export: queued bundles with owner and ETA.
+- Processing: stages collecting, compressing, signing.
+- Delivered: download links and resume tokens.
+- Expired: retention exceeded, regenerate via CLI.
+
+CLI parity
+- Copy buttons produce docker pull and oras copy commands with digests.
+- Helm and compose commands include values and env file hints.
+- Offline kit verification sequence includes cosign verify-blob.
+- Export entries include stella runs export or stella findings export commands.
+- Webhook tab provides curl subscription snippets.
+
+Offline and air-gap workflow
+- Offline users import offline-manifest.json with detached signature.
+- UI warns when offline manifest lags online by more than a week.
+- Mirror commands copy images to internal registries with custom trust roots.
+- Parity checks highlight diff between offline kit contents and manifest digests.
+- Audit logs record ui.download.commandCopied with artifact ID and digest.
+
+Observability and quotas
+- ui_download_manifest_refresh_seconds for manifest fetch and verify.
+- ui_download_export_queue_depth from the downloads API.
+- ui_download_command_copied_total from console logs.
+- downloads.export.duration histograms for export generation.
+- downloads.quota.remaining warns on quota saturation.

docs2/ui/exception-center.md

@@ -0,0 +1,24 @@
+# Exception center
+
+Purpose
+- Manage exception and waiver requests with explicit approval workflows.
+- Preserve Aggregation-Only and evidence-first expectations in every view.
+
+Core surfaces
+- List view with status, scope, owner, expiry, and evidence links.
+- Detail view with create, approve, reject actions and a full history timeline.
+- Badges for scope, risk level, and expiration status.
+
+Workflow expectations
+- Create requires reason, evidence references, and expiry.
+- Approve and reject actions are scope gated and audited.
+- Status changes emit timeline events with correlation IDs.
+
+Accessibility and offline
+- Keyboard shortcuts for list, filters, and detail drawer.
+- Offline mode shows snapshot ID and disables new approvals.
+- Exports default to local paths for transfer.
+
+Determinism and assets
+- Any captures or sample payloads must be stored locally with SHA256SUMS.
+- Exported views include filter and overlay metadata for replay.

docs2/ui/explainers.md

@@ -0,0 +1,34 @@
+# Policy explainers
+
+Purpose
+- Provide evidence-backed explanations for policy decisions.
+- Always show evidence hashes, signals, and rule rationale.
+
+Surfaces
+- Findings table links to the explainer drawer.
+- Explainer drawer shows rule stack, inputs, signals, and evidence hashes.
+- Timeline and runs tabs show policy events and run inputs.
+
+Drawer layout
+- Header: status, severity, policy version, shadow flag, AOC badge.
+- Evidence panel: SBOM digest, advisory snapshot, VEX IDs, reachability graph hash, runtime hit flag, attestation refs.
+- Rule hits: ordered list with because, signals snapshot, actions taken.
+- Reachability path: signed call path and edge bundle hash when available.
+- Signals: trust_score, reachability state and score, uncertainty level, runtime hits.
+
+Interactions
+- Verify evidence triggers the policy explain verify flow and shows DSSE status.
+- Toggle baseline compares against previous policy version.
+- Download exports JSON with evidence hashes for offline review.
+
+Accessibility
+- Keyboard navigation across header, evidence, rules, actions.
+- Screen reader labels include status, severity, reachability state, trust score.
+
+Offline behavior
+- Explainers work with offline bundles and embedded attestations.
+- If transparency logs are unavailable, show offline verify status with bundle digest.
+
+Error states
+- Missing evidence shows unknown chips and rerun guidance.
+- Attestation mismatch shows warning badge and governance links.

docs2/ui/findings.md

@@ -0,0 +1,72 @@
+# Findings workspace
+
+Purpose
+- Present materialized policy verdicts with explainability, filtering, and export support.
+- Preserve aggregation-only provenance while enabling triage and automation.
+
+Access and dependencies
+- Route: /console/findings with optional panel=explain.
+- Scopes: findings.read, policy:runs, policy:simulate, downloads.read.
+- Depends on Policy Engine effective findings, Concelier and Excititor provenance, SBOM service metadata.
+- Feature flags: findings.explain.enabled, findings.savedViews.enabled, findings.simulationDiff.enabled.
+
+Layout
+- Header with tenant badge, policy selector, global filters, and actions.
+- Summary cards: affected assets, critical count, KEV count.
+- Findings grid (virtualized) with right-side drawer for details.
+
+Filters and saved views
+- Status: affected, at_risk, quieted, fixed, not_applicable, mitigated.
+- Severity: critical, high, medium, low, informational, untriaged.
+- KEV toggle and exploitability hints.
+- Policy view: active, staged, simulation.
+- Component search by PURL or substring.
+- SBOM filter by image digest or SBOM ID.
+- Tags from policy outputs.
+- Run window and explain hints (rule ID, justification, VEX provider).
+- Saved views persist per tenant and policy; shared views appear in the rail.
+
+Grid columns and badges
+- Status badge with rationale and quieted expiry.
+- Severity with score tooltip.
+- Component PURL and SBOM link.
+- Policy name and revision digest.
+- Source signals (VEX, advisory, runtime overlays).
+- Age since last evaluation.
+- Row badges: KEV, override, simulation only, determinism alert.
+
+Bulk actions
+- Open explains (batch drawer).
+- Export CSV or JSON.
+- Copy CLI batch explain commands.
+- Create ticket using configured integrations.
+
+Explain drawer
+- Summary: status, severity, policy decision, rule ID, run ID, SBOM link.
+- Rule chain: ordered rule hits with actions and score contributions.
+- Evidence: advisory, VEX, runtime signals, overrides.
+- VEX impact: claims used, justification, acceptance.
+- History: state transitions with timestamps and operators.
+- Raw trace: canonical policy trace with CLI parity.
+
+Simulations and comparisons
+- Compare active vs staged or simulation snapshots with diff banners.
+- Side-by-side view highlights added, removed, and severity changes.
+- Simulation results expire after a retention window and prompt re-run.
+
+Exports and automation
+- Immediate CSV, JSON, and Markdown summary exports.
+- Scheduled exports produce full tenant reports with manifests.
+- Explain bundle export packages traces for audit.
+- Webhook subscription hints for export completion.
+
+Real-time updates
+- SSE stream updates new findings, status changes, and quieted expirations.
+- Metrics cards mirror findings_critical_total, findings_quieted_total, findings_kev_total.
+- Errors surface correlation IDs for logs.
+
+Offline behavior
+- Snapshot banner shows offline dataset and staleness.
+- Explain drawer notes cached evidence sources.
+- Exports default to local paths with transfer guidance.
+- Tenants missing in the snapshot are hidden.

docs2/ui/forensics.md

@@ -0,0 +1,20 @@
+# Forensics UI
+
+Purpose
+- Provide timeline exploration, evidence viewing, and attestation verification workflows.
+
+Core surfaces
+- Timeline explorer with filters and drilldowns.
+- Evidence viewer for attestations, signatures, and DSSE bundles.
+- Verifier steps with expected outputs and replay guidance.
+
+Determinism and assets
+- Captures and sample payloads must be stored locally with SHA256SUMS.
+- Tables and examples use UTC timestamps and stable ordering.
+
+Offline behavior
+- Evidence viewer works from offline bundles.
+- Verification steps prefer local bundles and recorded hashes.
+
+Troubleshooting
+- Error taxonomy, retry guidance, and deterministic repro steps.

docs2/ui/navigation.md

@@ -0,0 +1,61 @@
+# Console navigation
+
+Route map
+- /console/dashboard: KPIs, feed age, queue depth, alerts (min scope: ui.read).
+- /console/findings: policy verdicts, explain drawer, exports (min scope: findings.read).
+- /console/sbom: SBOM catalog, component graph, overlays (min scope: sbom.read).
+- /console/advisories: advisory aggregation with provenance (min scope: advisory.read).
+- /console/vex: VEX consensus and claims (min scope: vex.read).
+- /console/runs: scheduler runs, progress, evidence bundles (min scope: runs.read).
+- /console/policies: authoring, simulation, approvals (min scope: policy.read).
+- /console/downloads: artifacts and offline kit parity (min scope: downloads.read).
+- /console/admin: tenants, roles, clients, tokens, audit (min scope: ui.admin plus authority scopes).
+- /console/help: guides, tours, release notes (min scope: ui.read).
+
+Secondary navigation
+- Left rail: active route, quick metrics, saved views.
+- Breadcrumbs: Home / Module / Detail with shareable context.
+- Action shelf: context actions (export, verify, retry) gated by scopes.
+
+Command palette
+- Open with Cmd/Ctrl+K.
+- Jump to routes, saved views, tenants, and recent entities.
+- Actions apply stored filters without a full reload.
+- Offline mode restricts to cached routes and saved views.
+
+Global filter controls
+- Tenant picker (Cmd/Ctrl+T): requests a new Authority token and invalidates caches.
+- Filter tray (Shift+F): time window, severity, tags, source, status, policy view.
+- Component search: focus with / when tray is closed.
+- Time presets: Cmd/Ctrl+Shift+1..4 for 24h, 7d, 30d, custom.
+- Context chips: show active filters and allow one-click removal.
+
+Keyboard shortcuts
+- Cmd/Ctrl+K: command palette.
+- Cmd/Ctrl+T: tenant switcher.
+- Shift+F: filter tray.
+- Cmd/Ctrl+1..9: saved view presets.
+- ?: keyboard overlay with per-module shortcuts.
+- Module examples: Cmd/Ctrl+G (SBOM overlays), Cmd/Ctrl+R (runs refresh), Cmd/Ctrl+S (policy save).
+- Shortcuts are remappable and follow WCAG 2.2 guidance.
+
+Deep link schema
+- /console/<route>[/<id>]?tenant=<slug>&since=<iso>&until=<iso>&severity=<list>&view=<token>&panel=<drawer>&component=<purl>
+- tenant is required and matches Authority slugs.
+- panel selects drawers or tabs (panel=explain, panel=timeline).
+- Offline share links include snapshot=<hash>.
+- Share links map to CLI commands for parity and offline replay.
+
+Tenant switching lifecycle
+- User selects a tenant from the picker or palette.
+- UI requests a new tenant-scoped, DPoP-bound token from Authority.
+- Cache stores are invalidated; SSE streams reconnect with new headers.
+- Filters reapply where valid; incompatible presets prompt fallback selection.
+- Audit event ui.tenant.switch emitted with correlation ID.
+- Offline mode hides tenants missing from the snapshot.
+
+Focus and accessibility
+- Route changes move focus to the primary heading.
+- Drawers and modals trap focus until closed; Esc restores focus.
+- Tab lists are keyboard navigable and update the URL tab parameter.
+- Automated accessibility checks validate focus order and shortcut collisions.