docs consolidation work

docs/modules/unknowns/README.md

@@ -0,0 +1,92 @@
+# Unknowns Registry
+
+**Status:** Implemented
+**Source:** `src/Unknowns/`
+**Owner:** Signals Guild, Policy Guild
+
+## Purpose
+
+The Unknowns Registry provides bitemporal ambiguity tracking for security scan gaps where reachability or applicability cannot be determined with confidence. It models Unknown-Reachable and Unknown-Unreachable states as first-class risk signals, enabling uncertainty-aware scoring and triage prioritization.
+
+## Components
+
+**Services:**
+- Unknowns registry and tracking service
+- Integration with Policy Engine for risk scoring
+- Signals correlation for unknowns decay
+
+**Libraries:**
+- `StellaOps.Policy.Unknowns` - Unknowns budget and scoring logic
+- Unknown state modeling and confidence tracking
+
+## Key Features
+
+- **First-class Unknown state:** Explicit modeling of uncertainty (not hidden as false negatives)
+- **Bitemporal tracking:** Valid-time and transaction-time for ambiguity windows
+- **Risk scoring integration:** `unknowns_pressure` factor in Policy Engine
+- **Decay heuristics:** Unknowns decay over time with configurable policies
+- **Triage queue:** Dedicated UI view for unknowns requiring investigation
+- **Confidence budgets:** Policy gates can enforce maximum acceptable unknowns
+
+## Configuration
+
+**Unknowns Budget Options** (`UnknownBudgetOptions.cs`):
+- Maximum unknowns threshold per finding
+- Decay policies and timeouts
+- Scoring weight multipliers
+
+**Unknowns Decay Options** (`UnknownsDecayOptions.cs`):
+- Decay curve parameters
+- Confidence floor values
+- Re-evaluation triggers
+
+**Unknowns Rescan Options** (`UnknownsRescanOptions.cs`):
+- Automatic rescan scheduling
+- Priority queue management
+
+## Integration Points
+
+**Policy Engine:**
+- Unknowns budget gate enforcement
+- Confidence-based disposition selection
+- Risk score adjustments based on unknowns count
+
+**Signals:**
+- Runtime signal correlation can resolve unknowns
+- Automatic unknowns decay on new evidence
+
+**UI:**
+- Unknowns chips in findings display
+- Dedicated triage queue for unknowns
+- Confidence meter visualization
+
+## Storage
+
+- **Schema:** Part of `policy` schema in PostgreSQL
+- **Tables:** Unknowns tracking, decay history, resolution events
+
+## Dependencies
+
+- PostgreSQL (unknowns tracking and audit)
+- Policy Engine (scoring integration)
+- Signals (runtime correlation)
+- Triage UI (operator workflows)
+
+## Related Documentation
+
+- Unknowns decay heuristics: `../../operations/unknowns-triage.md`
+- Policy gates: `../policy/gates.md`
+- Confidence model: `../policy/confidence-model.md`
+- UI triage guide: `../ui/triage-unknowns.md`
+
+## Implementation Status
+
+**Completed:**
+- Unknowns registry with bitemporal tracking
+- Policy Engine integration with budget gates
+- UI chips and triage queue
+- Decay heuristics and automatic resolution
+- Confidence-based scoring adjustments
+
+**Key Differentiator:**
+Unlike other scanners that hide uncertainty, StellaOps makes "what we don't know" visible and policy-addressable. This is critical for air-gapped deployments and zero-day scenarios where external validation is unavailable.