Merge branch 'main' of https://git.stella-ops.org/stella-ops.org/git.stella-ops.org

docs/README.md

@@ -1,121 +1,130 @@
 # Stella Ops Suite Documentation
 
-**Stella Ops Suite** is a centralized, auditable release control plane for **non‑Kubernetes** container estates. It orchestrates environment promotions, gates releases using reachability-aware security and policy, and produces verifiable evidence for every decision.
+**Stella Ops Suite** is a centralized, auditable **release control plane** for **non-Kubernetes container estates**. It orchestrates environment promotions, gates releases using reachability-aware security and policy, and produces **verifiable evidence** for every decision.
 
-The platform combines:
-
-- **Release orchestration** — UI-driven promotion (Dev -> Stage -> Prod), approvals, policy gates, rollbacks, and step-graph execution (sequential/parallel) with per-step logs
-- **Security decisioning as a gate** — scan on build, evaluate on release, re-evaluate on vulnerability intel updates
-- **OCI-digest-first releases** — immutable digest-based release identity with authoritative "what is deployed where" tracking
-- **Toolchain-agnostic integrations** — plug into any SCM, CI, registry, secrets system, and host access method via plugins
-- **Auditability + standards** — evidence packets, SBOM/VEX/attestation support, deterministic replay and explainable decisions
+Stella is designed for teams who deploy containers via **Docker/Compose, hosts/VMs, and scripted automation** and need **certifiable security + auditable releases** without building a bespoke governance pipeline.
 
 ---
 
-## Verified vs Unverified Releases
+## What Stella delivers
 
-Stella supports two operational modes:
+### Evidence-grade release governance (outside Kubernetes)
+- **Environment promotions** (Dev -> Stage -> Prod) with explicit policy, approvals, and change control.
+- **Digest-first release identity**: deployments are tracked by immutable OCI digests so "what is deployed where" is unambiguous.
+- **Deterministic decision records**: every gate decision is explainable ("why blocked?") and replayable.
 
-- **Verified releases (recommended):** promotions require Stella evidence for each new digest (SBOM + reachability + policy decision record + approvals where configured). Intended for certifiable security and audit-grade releases.
-- **Unverified releases (CD-only):** orchestration is allowed with evidence gates bypassed. Still tracked and logged, but not intended for security certification.
+### Reachability-aware security decisioning
+- **Deep scanning** produces SBOM + findings + reachability and hybrid reachability evidence.
+- **VEX-first decisioning** with consensus and conflict handling across issuers (SBOM/VEX are part of the evidence chain, not a side export).
+- **Policy-as-code** with deterministic evaluation and traceable outcomes.
 
-This documentation emphasizes the **verified release** path as the primary product value.
+### Verifiability, attestability, and audit export
+- **Evidence packets / decision capsules**: hashable, immutable bundles that capture inputs, verdicts, and approvals.
+- **Attestations** (DSSE/in-toto, predicates for SBOM/VEX/verdict/reachability; optional Sigstore flows where configured).
+- **Audit exports** for compliance review, incident response, and forensic reconstruction.
+
+### Offline-first, sovereign operation
+- Built for **air-gapped** and restricted environments: local databases, offline kits/snapshots, and deterministic replay.
+- **Regional crypto profiles** (eIDAS/FIPS/GOST/SM and related plugin architecture) to avoid compliance lock-in.
+
+### Toolchain-agnostic integrations
+- Integrates with common SCM/CI/registries/secrets managers through **connectors and plugins**.
+- Works alongside existing pipelines: scan-on-build, gate-on-promotion, re-evaluate on advisory updates.
 
 ---
 
-## Licensing model (documentation-level summary)
+## Core differentiators (the "why Stella" set)
 
-Stella Ops Suite uses **no feature gating** across plans. Licensing limits apply only to:
+These concepts appear throughout the docs and are the suite's anchor points:
 
-- **Environments**
-- **New digests deep-scanned per month** (evidence-grade analysis of previously unseen OCI digests)
+- **Signed, replayable risk verdicts**: decisions can be re-run deterministically from the same evidence.
+- **Decision capsules**: evidence is packaged for audit, not scattered across logs and screenshots.
+- **Reachability with portable proofs**: exploitability is evidenced, not asserted.
+- **Smart-diff / semantic risk delta**: focus on what materially changed between releases.
+- **Unknowns as first-class state**: uncertainty is tracked and budgeted, not hidden.
+- **Non-Kubernetes-first**: orchestration and evidence for Compose/hosts/agentless targets as a primary use case.
+- **Digest-first release identity**: immutable artifacts, immutable accountability.
 
-**Deployment targets are not licensed** (unlimited targets; fair use may apply only under abusive automation patterns).
-
-(See your offer/pricing document if present in the repo; commonly stored under `docs/product/`.)
+For exhaustive capability detail (including planned items), use the Feature Matrix referenced below.
 
 ---
 
-## Two Levels of Documentation
+## Two levels of documentation
 
 - **High-level (canonical):** curated guides in `docs/*.md`.
-- **Detailed (reference):** deep dives under `docs/**` (module dossiers, architecture notes, API contracts/samples, runbooks, schemas). Entry point: `docs/technical/README.md`.
+- **Detailed (reference):** deep dives under `docs/**` (module dossiers, architecture notes, API contracts/samples, runbooks, schemas).  
+  Entry point: `docs/technical/README.md`.
 
-This documentation set is internal and does not keep compatibility stubs for old paths. Content is consolidated to reduce duplication and outdated pages.
+This documentation set is intentionally consolidated and does not maintain compatibility stubs for old paths.
 
 ---
 
-## Start Here
+## Start here
 
-### Product Understanding
+### Product understanding
 
 | Goal | Open this |
 | --- | --- |
-| Understand the product in 2 minutes | [overview.md](overview.md) |
-| Browse capabilities | [key-features.md](key-features.md) |
-| Feature matrix | [FEATURE_MATRIX.md](FEATURE_MATRIX.md) |
-| Product vision | [product/VISION.md](product/VISION.md) |
-| Roadmap (priorities + definition of "done") | [ROADMAP.md](ROADMAP.md) |
-| Verified release model (concepts + evidence) | [VERIFIED_RELEASES.md](VERIFIED_RELEASES.md) |
+| Understand the suite quickly | `overview.md` |
+| Capability cards | `key-features.md` |
+| Full capability matrix | `FEATURE_MATRIX.md` |
+| Known documentation coverage gaps | `FEATURE_GAPS_REPORT.md` |
+| Product vision | `product/VISION.md` |
+| Roadmap (priorities + definition of "done") | `ROADMAP.md` |
 
-### Getting Started
+### Getting started
 
 | Goal | Open this |
 | --- | --- |
-| First run (minimal install) | [quickstart.md](quickstart.md) |
-| Run a first scan (CLI) | [quickstart.md](quickstart.md) |
-| Run a first verified promotion (Dev -> Stage -> Prod) | [RELEASE_PROCESS.md](releases/RELEASE_PROCESS.md) |
-| Ingest advisories (Concelier + CLI) | [CONCELIER_CLI_QUICKSTART.md](CONCELIER_CLI_QUICKSTART.md) |
-| Console (Web UI) operator guide | [UI_GUIDE.md](UI_GUIDE.md) |
-| Doctor / self-service diagnostics | [DOCTOR_GUIDE.md](doctor/README.md) |
-| Offline / air-gap operations | [OFFLINE_KIT.md](OFFLINE_KIT.md) |
+| First run and basic workflows | `quickstart.md` |
+| Ingest advisories (Concelier + CLI) | `CONCELIER_CLI_QUICKSTART.md` |
+| Console (Web UI) operator guide | `UI_GUIDE.md` |
+| Offline / air-gap operations | `OFFLINE_KIT.md` |
 
 ### Architecture
 
 | Goal | Open this |
 | --- | --- |
-| Architecture: high-level overview | [ARCHITECTURE_OVERVIEW.md](ARCHITECTURE_OVERVIEW.md) |
-| Architecture: full reference map | [ARCHITECTURE_REFERENCE.md](ARCHITECTURE_REFERENCE.md) |
-| Architecture: user flows (UML) | [technical/architecture/user-flows.md](technical/architecture/user-flows.md) |
-| Architecture: module matrix | [technical/architecture/module-matrix.md](technical/architecture/module-matrix.md) |
-| Architecture: data flows | [technical/architecture/data-flows.md](technical/architecture/data-flows.md) |
-| Architecture: schema mapping | [technical/architecture/schema-mapping.md](technical/architecture/schema-mapping.md) |
-| Release Orchestrator architecture | [modules/release-orchestrator/architecture.md](modules/release-orchestrator/architecture.md) |
-| Evidence and attestations | [modules/evidence/README.md](modules/evidence/README.md) |
+| Architecture: high-level overview | `ARCHITECTURE_OVERVIEW.md` |
+| Architecture: full reference map | `ARCHITECTURE_REFERENCE.md` |
+| Architecture: user flows (UML) | `technical/architecture/user-flows.md` |
+| Architecture: module matrix | `technical/architecture/module-matrix.md` |
+| Architecture: data flows | `technical/architecture/data-flows.md` |
+| Architecture: schema mapping | `technical/architecture/schema-mapping.md` |
+| Release Orchestration dossier | `modules/release-orchestrator/architecture.md` |
 
-### Development & Operations
+### Development and operations
 
 | Goal | Open this |
 | --- | --- |
-| Engineering rules (determinism, security, docs discipline) | [code-of-conduct/CODE_OF_CONDUCT.md](code-of-conduct/CODE_OF_CONDUCT.md) |
-| Testing standards and evidence expectations | [code-of-conduct/TESTING_PRACTICES.md](code-of-conduct/TESTING_PRACTICES.md) |
-| Develop plugins/connectors | [PLUGIN_SDK_GUIDE.md](PLUGIN_SDK_GUIDE.md) |
-| Security deployment hardening | [SECURITY_HARDENING_GUIDE.md](SECURITY_HARDENING_GUIDE.md) |
-| VEX consensus and issuer trust | [VEX_CONSENSUS_GUIDE.md](VEX_CONSENSUS_GUIDE.md) |
-| Vulnerability Explorer guide | [VULNERABILITY_EXPLORER_GUIDE.md](VULNERABILITY_EXPLORER_GUIDE.md) |
+| Develop plugins/connectors | `PLUGIN_SDK_GUIDE.md` |
+| Security deployment hardening | `SECURITY_HARDENING_GUIDE.md` |
+| VEX consensus and issuer trust | `VEX_CONSENSUS_GUIDE.md` |
+| Vulnerability Explorer guide | `VULNERABILITY_EXPLORER_GUIDE.md` |
+| Engineering standards (for implementers) | `code-of-conduct/CODE_OF_CONDUCT.md` |
+| Testing standards (for QA/automation) | `code-of-conduct/TESTING_PRACTICES.md` |
 
 ---
 
-## Detailed Indexes
+## Detailed indexes
 
-- **Technical index (everything):** [docs/technical/README.md](/docs/technical/)
-- **End-to-end workflow flows:** [docs/flows/](/docs/flows/)
-- **Module dossiers:** [docs/modules/](/docs/modules/)
-- **API contracts and samples:** [docs/api/](/docs/api/)
-- **Architecture notes / ADRs:** [docs/technical/architecture/](/docs/technical/architecture/), [docs/technical/adr/](/docs/technical/adr/)
-- **Operations and deployment:** [docs/operations/](/docs/operations/)
-- **Air-gap workflows:** [docs/modules/airgap/guides/](/docs/modules/airgap/guides/)
-- **Security deep dives:** [docs/security/](/docs/security/)
-- **Benchmarks and fixtures:** [docs/benchmarks/](/docs/benchmarks/), [docs/assets/](/docs/assets/)
-- **Product advisories:** [docs/product/advisories/](/docs/product/advisories/)
+- Technical index (everything): `docs/technical/README.md`
+- End-to-end workflow flows: `docs/flows/`
+- Module dossiers: `docs/modules/`
+- API contracts and samples: `docs/api/`
+- Architecture notes / ADRs: `docs/technical/architecture/`, `docs/technical/adr/`
+- Operations and deployment: `docs/operations/`
+- Air-gap workflows: `docs/modules/airgap/guides/`
+- Security deep dives: `docs/security/`
+- Benchmarks and fixtures: `docs/benchmarks/`, `docs/assets/`
+- Product advisories: `docs/product/advisories/`
 
 ---
 
-## Design Principles
+## Design principles (non-negotiable)
 
-- **Offline-first**: core operations work in air-gapped environments
-- **Deterministic replay**: same inputs yield same outputs (stable ordering, canonical hashing)
-- **Evidence-linked decisions**: every verified release decision links to concrete evidence artifacts
-- **Digest-first release identity**: releases are immutable OCI digests, not mutable tags
-- **Pluggable everything**: integrations are plugins; core orchestration is stable
-- **No feature gating**: all plans include all features; licensing limits are environments + new digests deep-scanned per month; deployment targets are not licensed
+- **Offline-first:** core operations must work in restricted/air-gapped environments.
+- **Deterministic replay:** same inputs yield the same outputs (stable ordering, canonical hashing).
+- **Evidence-linked decisions:** every decision links to concrete evidence artifacts.
+- **Digest-first identity:** releases are immutable OCI digests, not mutable tags.
+- **Pluggable integrations:** connectors and steps are extensible; the core evidence chain stays stable.