docs consolidation, big sln build fixes, new advisories and sprints/tasks

2026-01-05 18:37:04 +02:00
parent d0a7b88398
commit d7bdca6d97
175 changed files with 10322 additions and 307 deletions
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -0,0 +1,257 @@
+# StellaOps Documentation Index
+
+> **Master index of all StellaOps documentation.**
+> Last updated: 2026-01-05 (Post-consolidation)
+
+This index provides a complete map of documentation organized by audience and topic. The documentation follows a two-level hierarchy:
+- **Canonical guides** (`docs/*.md`) - High-level entry points
+- **Detailed references** (`docs/**/*`) - Module dossiers, API contracts, runbooks
+
+---
+
+## Quick Navigation by Audience
+
+| Audience | Start Here |
+|----------|------------|
+| **New Users** | [quickstart.md](quickstart.md), [overview.md](overview.md) |
+| **Developers** | [DEVELOPER_ONBOARDING.md](DEVELOPER_ONBOARDING.md), [CODING_STANDARDS.md](CODING_STANDARDS.md) |
+| **Architects** | [ARCHITECTURE_OVERVIEW.md](ARCHITECTURE_OVERVIEW.md), [ARCHITECTURE_REFERENCE.md](ARCHITECTURE_REFERENCE.md) |
+| **Operators/SREs** | [SECURITY_HARDENING_GUIDE.md](SECURITY_HARDENING_GUIDE.md), [OFFLINE_KIT.md](OFFLINE_KIT.md) |
+| **Plugin Developers** | [PLUGIN_SDK_GUIDE.md](PLUGIN_SDK_GUIDE.md), [dev/](dev/) |
+
+---
+
+## Canonical Guides (docs/*.md)
+
+### Getting Started
+| Document | Purpose |
+|----------|---------|
+| [README.md](README.md) | Documentation overview and navigation |
+| [overview.md](overview.md) | 2-minute product summary |
+| [quickstart.md](quickstart.md) | First scan walkthrough |
+| [DEVELOPER_ONBOARDING.md](DEVELOPER_ONBOARDING.md) | Developer setup guide |
+| [CONCELIER_CLI_QUICKSTART.md](CONCELIER_CLI_QUICKSTART.md) | Advisory ingestion quickstart |
+
+### Architecture
+| Document | Purpose |
+|----------|---------|
+| [ARCHITECTURE_OVERVIEW.md](ARCHITECTURE_OVERVIEW.md) | 10-minute architecture tour |
+| [ARCHITECTURE_REFERENCE.md](ARCHITECTURE_REFERENCE.md) | Full architecture index/map |
+| [technical/architecture/](technical/architecture/) | Detailed architecture views |
+
+### Features & Capabilities
+| Document | Purpose |
+|----------|---------|
+| [key-features.md](key-features.md) | Capability cards with evidence |
+| [FEATURE_MATRIX.md](FEATURE_MATRIX.md) | Tier-by-tier feature availability |
+| [full-features-list.md](full-features-list.md) | Complete capability catalog |
+
+### Operations & Security
+| Document | Purpose |
+|----------|---------|
+| [SECURITY_HARDENING_GUIDE.md](SECURITY_HARDENING_GUIDE.md) | Deployment security guide |
+| [SECURITY_POLICY.md](SECURITY_POLICY.md) | Security incident policy |
+| [OFFLINE_KIT.md](OFFLINE_KIT.md) | Air-gapped operation guide |
+| [UI_GUIDE.md](UI_GUIDE.md) | Console operator guide |
+
+### Development
+| Document | Purpose |
+|----------|---------|
+| [CODING_STANDARDS.md](CODING_STANDARDS.md) | Code quality rules |
+| [PLUGIN_SDK_GUIDE.md](PLUGIN_SDK_GUIDE.md) | Plugin development guide |
+| [VEX_CONSENSUS_GUIDE.md](VEX_CONSENSUS_GUIDE.md) | VEX consensus and trust |
+
+### Reference
+| Document | Purpose |
+|----------|---------|
+| [API_CLI_REFERENCE.md](API_CLI_REFERENCE.md) | API and CLI reference hub |
+| [GLOSSARY.md](GLOSSARY.md) | Platform terminology |
+| [ROADMAP.md](ROADMAP.md) | Product roadmap |
+
+---
+
+## Module Documentation (docs/modules/)
+
+Module dossiers contain architecture, operations, and API documentation per component.
+
+> **Naming Convention:** Module directories use kebab-case (e.g., `binary-index`, `sbom-service`)
+
+### Core Platform
+| Module | Directory | Description |
+|--------|-----------|-------------|
+| Authority | [authority/](modules/authority/) | OAuth/OIDC, DPoP authentication |
+| Gateway | [gateway/](modules/gateway/) | API gateway, routing |
+| Router | [router/](modules/router/) | Transport-agnostic messaging |
+| Platform | [platform/](modules/platform/) | Console backend aggregation |
+
+### Data Ingestion
+| Module | Directory | Description |
+|--------|-----------|-------------|
+| Concelier | [concelier/](modules/concelier/) | Advisory ingestion |
+| Excititor | [excititor/](modules/excititor/) | VEX document ingestion |
+| VexLens | [vex-lens/](modules/vex-lens/) | VEX consensus computation |
+| VexHub | [vex-hub/](modules/vex-hub/) | VEX distribution hub |
+| IssuerDirectory | [issuer-directory/](modules/issuer-directory/) | Issuer trust registry |
+| Feedser | [feedser/](modules/feedser/) | Backport detection evidence |
+
+### Scanning & Analysis
+| Module | Directory | Description |
+|--------|-----------|-------------|
+| Scanner | [scanner/](modules/scanner/) | Container scanning, SBOM generation |
+| BinaryIndex | [binary-index/](modules/binary-index/) | Binary fingerprinting |
+| AdvisoryAI | [advisory-ai/](modules/advisory-ai/) | AI-assisted analysis |
+| Symbols | [symbols/](modules/symbols/) | Symbol resolution |
+| ReachGraph | [reach-graph/](modules/reach-graph/) | Reachability graphs |
+
+### Artifacts & Evidence
+| Module | Directory | Description |
+|--------|-----------|-------------|
+| Attestor | [attestor/](modules/attestor/) | DSSE/in-toto attestations |
+| Signer | [signer/](modules/signer/) | Cryptographic signing |
+| SbomService | [sbom-service/](modules/sbom-service/) | SBOM storage, lineage |
+| EvidenceLocker | [evidence-locker/](modules/evidence-locker/) | Sealed evidence storage |
+| ExportCenter | [export-center/](modules/export-center/) | Batch export |
+| Provenance | [provenance/](modules/provenance/) | SLSA attestation |
+
+### Policy & Risk
+| Module | Directory | Description |
+|--------|-----------|-------------|
+| Policy | [policy/](modules/policy/) | K4 lattice policy engine |
+| RiskEngine | [risk-engine/](modules/risk-engine/) | Risk scoring |
+| VulnExplorer | [vuln-explorer/](modules/vuln-explorer/) | Vulnerability triage |
+| Unknowns | [unknowns/](modules/unknowns/) | Unknown component tracking |
+| FindingsLedger | [findings-ledger/](modules/findings-ledger/) | Findings tracking |
+
+### Operations
+| Module | Directory | Description |
+|--------|-----------|-------------|
+| Scheduler | [scheduler/](modules/scheduler/) | Job scheduling |
+| Orchestrator | [orchestrator/](modules/orchestrator/) | Workflow orchestration |
+| TaskRunner | [taskrunner/](modules/taskrunner/) | Task pack execution |
+| Notify | [notify/](modules/notify/) | Notifications |
+| Notifier | [notifier/](modules/notifier/) | Notifications Studio |
+| PacksRegistry | [packs-registry/](modules/packs-registry/) | Task packs registry |
+| TimelineIndexer | [timeline-indexer/](modules/timeline-indexer/) | Event indexing |
+| Replay | [replay/](modules/replay/) | Deterministic replay |
+
+### Integration
+| Module | Directory | Description |
+|--------|-----------|-------------|
+| CLI | [cli/](modules/cli/) | Command-line interface |
+| Zastava | [zastava/](modules/zastava/) | Registry webhooks |
+| Web/UI | [ui/](modules/ui/), [web/](modules/web/) | Frontend SPA |
+
+### Infrastructure
+| Module | Directory | Description |
+|--------|-----------|-------------|
+| Cryptography | [cryptography/](modules/cryptography/) | Crypto profiles |
+| Telemetry | [telemetry/](modules/telemetry/) | Observability |
+| Graph | [graph/](modules/graph/) | Call graph structures |
+| Signals | [signals/](modules/signals/) | Runtime signals |
+| AirGap | [airgap/](modules/airgap/) | Air-gap support |
+| AOC | [aoc/](modules/aoc/) | Append-Only Contract |
+
+### Cross-Cutting Concepts
+| Concept | Directory | Description |
+|---------|-----------|-------------|
+| Snapshot | [snapshot/](modules/snapshot/) | Point-in-time captures |
+| Triage | [triage/](modules/triage/) | Vulnerability triage workflows |
+| Provcache | [prov-cache/](modules/prov-cache/) | Provenance cache (library) |
+| Benchmark | [benchmark/](modules/benchmark/) | Competitive benchmarking |
+| Bench | [bench/](modules/bench/) | Performance benchmarks |
+
+---
+
+## Specialized Documentation Areas
+
+### API Documentation
+| Area | Path | Description |
+|------|------|-------------|
+| API Overview | [api/overview.md](api/overview.md) | API conventions |
+| Gateway APIs | [api/gateway/](api/gateway/) | Gateway endpoints |
+| Console APIs | [api/console/](api/console/) | Console endpoints |
+| Signal Contracts | [api/signals/](api/signals/) | Signal contracts |
+
+### Air-Gap Operations
+| Area | Path | Description |
+|------|------|-------------|
+| Overview | [airgap/overview.md](airgap/overview.md) | Air-gap overview |
+| Operations | [airgap/operations.md](airgap/operations.md) | Operational guides |
+| Bundles | [airgap/](airgap/) | Bundle formats |
+
+### Database
+| Area | Path | Description |
+|------|------|-------------|
+| Specification | [db/SPECIFICATION.md](db/SPECIFICATION.md) | Database spec |
+| Migrations | [db/tasks/](db/tasks/) | Migration phases |
+| Schemas | [db/schemas/](db/schemas/) | Schema definitions |
+
+### CLI Reference
+| Area | Path | Description |
+|------|------|-------------|
+| Command Reference | [cli/command-reference.md](cli/command-reference.md) | Complete CLI reference |
+| Admin Commands | [cli/admin-reference.md](cli/admin-reference.md) | Admin commands |
+| Crypto Commands | [cli/crypto-commands.md](cli/crypto-commands.md) | Crypto operations |
+
+### End-to-End Flows
+| Area | Path | Description |
+|------|------|-------------|
+| Flow Index | [flows/README.md](flows/README.md) | All workflow flows |
+| Scan Flow | [flows/02-scan-submission-flow.md](flows/02-scan-submission-flow.md) | Scan submission |
+| Policy Flow | [flows/04-policy-evaluation-flow.md](flows/04-policy-evaluation-flow.md) | Policy evaluation |
+| CI/CD Flow | [flows/10-cicd-gate-flow.md](flows/10-cicd-gate-flow.md) | CI/CD gating |
+
+### Technical Deep Dives
+| Area | Path | Description |
+|------|------|-------------|
+| Architecture Index | [technical/architecture/](technical/architecture/) | Architecture views |
+| User Flows | [technical/architecture/user-flows.md](technical/architecture/user-flows.md) | UML diagrams |
+| Module Matrix | [technical/architecture/module-matrix.md](technical/architecture/module-matrix.md) | 46-module matrix |
+
+### Contracts & ADRs
+| Area | Path | Description |
+|------|------|-------------|
+| Contracts | [contracts/](contracts/) | Technical contracts |
+| ADRs | [adr/](adr/) | Architecture decisions |
+
+### Development Guides
+| Area | Path | Description |
+|------|------|-------------|
+| Plugin Development | [dev/](dev/) | Plugin guides & templates |
+| Scanner Engine | [dev/scanning-engine.md](dev/scanning-engine.md) | Scanner internals |
+
+### Benchmarks & Testing
+| Area | Path | Description |
+|------|------|-------------|
+| Benchmarks | [benchmarks/](benchmarks/) | Performance & accuracy |
+| Ground Truth | [benchmarks/ground-truth-corpus.md](benchmarks/ground-truth-corpus.md) | Test datasets |
+
+### Risk Scoring
+| Area | Path | Description |
+|------|------|-------------|
+| Risk Samples | [risk/samples/](risk/samples/) | Risk scoring examples |
+
+---
+
+## Implementation Planning
+
+| Area | Path | Description |
+|------|------|-------------|
+| Sprint Files | [implplan/](implplan/) | Active implementation sprints |
+| Archived Sprints | [../docs-archived/implplan/](../docs-archived/implplan/) | Completed sprints |
+
+---
+
+## External References
+
+- **CLAUDE.md** (repository root) - Claude Code instructions and module table
+- **src/__Tests/AGENTS.md** - Test infrastructure guidance
+- **Module AGENTS.md files** - Per-module development instructions
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-01-05 | Created index; renamed module directories to kebab-case; updated CLAUDE.md with missing modules |