docs: finalize release package notes, link integrity, and dashboard validator alignment

rwilliamspbg-ops · web-flow · commit 58f2d6ccc26d · 2026-03-26T15:35:57.000Z
diff --git a/README.md b/README.md
@@ -24,6 +24,8 @@ Production-grade federated learning platform that combines Byzantine-resilient a
 [![Open Ecosystem](https://img.shields.io/badge/Open%20Ecosystem-Sprint%203%20Local--First-0ea5e9?style=flat-square)](docs/OPEN_ECOSYSTEM_FIRST_10_MINUTES.md)
 [![Marketplace Alerts](https://img.shields.io/badge/Alerts-Marketplace%20Guardrails-f97316?style=flat-square)](marketplace_alerts.yml)
 
+Documentation entrypoint: [docs/README.md](docs/README.md)
+
 ## Mobile Shield Update March 2026
 
 The mobile hardening and store packaging track is now implemented in-repo.
diff --git a/SDK_API_STABILITY.md b/SDK_API_STABILITY.md
@@ -0,0 +1,7 @@
+# SDK API Stability Policy
+
+Canonical policy location:
+
+- [docs/archive/reports/SDK_API_STABILITY.md](docs/archive/reports/SDK_API_STABILITY.md)
+
+This top-level file is maintained as a stable reference target for changelog and security links.
diff --git a/SDK_RELEASE_GUIDE.md b/SDK_RELEASE_GUIDE.md
@@ -0,0 +1,7 @@
+# SDK Release Guide
+
+Canonical release guide location:
+
+- [docs/archive/reports/SDK_RELEASE_GUIDE.md](docs/archive/reports/SDK_RELEASE_GUIDE.md)
+
+This top-level file is maintained as a stable reference target for security and release documentation links.
diff --git a/docs/COMPRESSION_DEPLOYMENT.md b/docs/COMPRESSION_DEPLOYMENT.md
@@ -508,4 +508,4 @@ console.log(engine.getCalibrationBounds());
 For issues or questions:
 - GitHub Issues: [sovereignty-map-federated-learning/issues](https://github.com/sovereign-map/sovereign-map-federated-learning/issues)
 - Documentation: [docs/](../)
-- Examples: [examples/compression/](../../examples/compression/)
+- Examples: [packages/compression/](../packages/compression/)
diff --git a/docs/DATA_COMPRESSION_GUIDE.md b/docs/DATA_COMPRESSION_GUIDE.md
@@ -395,8 +395,8 @@ data:
 
 ## Contributing
 
-See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for development guidelines.
 
 ## License
 
-Apache 2.0 - See [LICENSE](../../LICENSE)
+Apache 2.0 - See [LICENSE](../LICENSE)
diff --git a/docs/FEATURE_ARTIFACTS_2026-03-21.md b/docs/FEATURE_ARTIFACTS_2026-03-21.md
@@ -7,9 +7,10 @@ This manifest captures deliverables completed in the PySyft + dashboard consolid
 - [examples/pysyft-integration/README.md](../examples/pysyft-integration/README.md)
 - [examples/pysyft-integration/pysyft_mohawk_poc.py](../examples/pysyft-integration/pysyft_mohawk_poc.py)
 - [examples/pysyft-integration/pysyft_mohawk_poc.ipynb](../examples/pysyft-integration/pysyft_mohawk_poc.ipynb)
-- [examples/pysyft-integration/docker-compose.pysyft-demo.yml](../examples/pysyft-integration/docker-compose.pysyft-demo.yml)
 - [examples/pysyft-integration/requirements-pysyft-demo.txt](../examples/pysyft-integration/requirements-pysyft-demo.txt)
 
+Note: legacy PySyft demo compose file was removed during stack consolidation; run the demo via script and requirements listed above.
+
 ## Canonical STARRED Live Dashboards
 
 - [grafana/provisioning/dashboards/operations_overview.json](../grafana/provisioning/dashboards/operations_overview.json)
@@ -19,15 +20,9 @@ This manifest captures deliverables completed in the PySyft + dashboard consolid
 
 ## Compose Profiles Updated
 
-- [docker-compose.1000nodes.yml](../docker-compose.1000nodes.yml)
-- [docker-compose.200nodes.yml](../docker-compose.200nodes.yml)
-- [docker-compose.dev.yml](../docker-compose.dev.yml)
 - [docker-compose.full.yml](../docker-compose.full.yml)
-- [docker-compose.large-scale.yml](../docker-compose.large-scale.yml)
-- [docker-compose.monitoring.tpm.yml](../docker-compose.monitoring.tpm.yml)
-- [docker-compose.monitoring.yml](../docker-compose.monitoring.yml)
-- [docker-compose.production.yml](../docker-compose.production.yml)
-- [monitoring/docker-compose.monitoring.yml](../monitoring/docker-compose.monitoring.yml)
+
+Legacy compose profiles referenced in older notes were consolidated; use `docker-compose.full.yml` as the canonical stack entrypoint.
 
 ## Validation Snapshot
 
diff --git a/docs/GPU_NPU_ACCELERATION.md b/docs/GPU_NPU_ACCELERATION.md
@@ -308,7 +308,7 @@ if (stats?.device === 'cuda') {
 
 ## References
 
-- [SGP-001 Privacy Specification](../docs/SGP-001.md)
+- [Privacy engine integration overview](../README.md)
 - [Differential Privacy: A Survey of Results](https://arxiv.org/abs/1908.01756)
 - [Box-Muller Transform](https://en.wikipedia.org/wiki/Box%E2%80%93Muller_transform)
 - [CUDA Random Number Generation](https://docs.nvidia.com/cuda/curand/)
diff --git a/docs/GPU_NPU_QUICK_START.md b/docs/GPU_NPU_QUICK_START.md
@@ -294,7 +294,7 @@ console.log(`Avg: ${avg.toFixed(2)}ms, P99: ${p99.toFixed(2)}ms, P99.9: ${p99_9.
 
 ## Next Steps
 
-- Read [Complete GPU/NPU Acceleration Guide](docs/GPU_NPU_ACCELERATION.md)
+- Read [Complete GPU/NPU Acceleration Guide](./GPU_NPU_ACCELERATION.md)
 - Run benchmarks: `npm --prefix packages/privacy run bench`
 - Explore examples in `packages/privacy/src/index.test.ts`
 - Monitor performance in production
diff --git a/docs/PR_READY_PHASE3D_OVERHAUL.md b/docs/PR_READY_PHASE3D_OVERHAUL.md
@@ -21,55 +21,55 @@ It upgrades the training runtime from MNIST-only CPU assumptions to a production
 
 ### Training and API runtime
 
-- [packages/training/phase3d_training.py](packages/training/phase3d_training.py)
+- [packages/training/phase3d_training.py](../packages/training/phase3d_training.py)
   - Added dataset switch (`cifar10`, `mnist`)
   - Added device selection (`auto`, `cpu`, `cuda`)
   - Added multi-GPU support via DataParallel
   - Added per-client data partitioning and richer training metrics
-- [packages/training/api.py](packages/training/api.py)
+- [packages/training/api.py](../packages/training/api.py)
   - Added config persistence fix
   - Added dataset/device/multi_gpu fields to config and status surfaces
 
 ### Frontend integration
 
-- [frontend/src/BrowserFLDemo.jsx](frontend/src/BrowserFLDemo.jsx)
+- [frontend/src/BrowserFLDemo.jsx](../frontend/src/BrowserFLDemo.jsx)
   - Stabilized real training mode
   - Real mode now starts with `dataset=cifar10`, `device=cuda`, `multi_gpu=true`
   - Preserved simulation mode and existing chart behavior
 
 ### Deployment automation
 
-- [deploy/production/deploy-phase3d-production.sh](deploy/production/deploy-phase3d-production.sh)
+- [deploy/production/deploy-phase3d-production.sh](../deploy/production/deploy-phase3d-production.sh)
   - Build training image
   - Create/login/push to ECR
   - Apply CPU/GPU Kubernetes manifest
   - Wait for rollout health
-- [deploy/kubernetes/phase3d-training.yaml](deploy/kubernetes/phase3d-training.yaml)
+- [deploy/kubernetes/phase3d-training.yaml](../deploy/kubernetes/phase3d-training.yaml)
   - CPU deployment profile
-- [deploy/kubernetes/phase3d-training-gpu.yaml](deploy/kubernetes/phase3d-training-gpu.yaml)
+- [deploy/kubernetes/phase3d-training-gpu.yaml](../deploy/kubernetes/phase3d-training-gpu.yaml)
   - GPU deployment profile (2x NVIDIA GPUs)
-- [packages/training/Dockerfile](packages/training/Dockerfile)
+- [packages/training/Dockerfile](../packages/training/Dockerfile)
   - Container image for Phase3D backend service
 
 ### CI/CD workflow expansion
 
-- [ .github/workflows/phase3d-production-deploy.yml](.github/workflows/phase3d-production-deploy.yml)
+- [.github/workflows/phase3d-production-deploy.yml](../.github/workflows/phase3d-production-deploy.yml)
   - Manual production Phase3D rollout workflow
-- [ .github/workflows/deploy.yml](.github/workflows/deploy.yml)
+- [.github/workflows/build.yml](../.github/workflows/build.yml)
   - Added optional post-production jobs for:
     - Phase3D EKS rollout
     - Frontend CDN publish
-- [deploy/production/publish-frontend-cdn.sh](deploy/production/publish-frontend-cdn.sh)
+- [deploy/production/publish-frontend-cdn.sh](../deploy/production/publish-frontend-cdn.sh)
   - S3 publish
   - Asset cache policy split (`index.html` no-cache vs static immutable)
   - Optional CloudFront invalidation
 
 ### Documentation and PR hygiene
 
-- [docs/PHASE_3D_PRODUCTION_DEPLOYMENT.md](docs/PHASE_3D_PRODUCTION_DEPLOYMENT.md)
-- [PHASE_3D_QUICK_START.md](PHASE_3D_QUICK_START.md)
-- [README.md](README.md)
-- [ .github/pull_request_template.md](.github/pull_request_template.md)
+- [docs/PHASE_3D_PRODUCTION_DEPLOYMENT.md](./PHASE_3D_PRODUCTION_DEPLOYMENT.md)
+- [PHASE_3D_QUICK_START.md](../PHASE_3D_QUICK_START.md)
+- [README.md](../README.md)
+- [CONTRIBUTING.md](../CONTRIBUTING.md)
 
 ## Validation Performed
 
@@ -105,24 +105,24 @@ bash -n deploy/production/publish-frontend-cdn.sh
 - [ ] Confirm GPU manifest resource limits align with cluster policy
 - [ ] Confirm deploy script works in target AWS account (ECR/EKS permissions)
 - [ ] Confirm CDN script bucket policy + CloudFront distribution ID are correct
-- [ ] Confirm optional jobs in [ .github/workflows/deploy.yml](.github/workflows/deploy.yml) skip safely when secrets are absent
+- [ ] Confirm optional jobs in [.github/workflows/build.yml](../.github/workflows/build.yml) skip safely when secrets are absent
 - [ ] Confirm docs match runtime defaults and secret names
 - [ ] Confirm no secrets are committed and workflow `uses:` refs remain SHA pinned
 
 ## Rollout Plan
 
 1. Merge PR to `main`
-2. Run manual [ .github/workflows/phase3d-production-deploy.yml](.github/workflows/phase3d-production-deploy.yml) (or rely on optional hook in [ .github/workflows/deploy.yml](.github/workflows/deploy.yml))
+2. Run manual [.github/workflows/phase3d-production-deploy.yml](../.github/workflows/phase3d-production-deploy.yml) (or run release steps via [.github/workflows/build.yml](../.github/workflows/build.yml))
 3. Validate Phase3D health endpoint and training start/status flow
 4. Publish frontend CDN assets and invalidate CloudFront
 5. Monitor errors, rollout status, and latency for 30-60 minutes
 
 ## Rollback Plan
 
-1. Re-deploy previous image tag using [deploy/production/deploy-phase3d-production.sh](deploy/production/deploy-phase3d-production.sh)
+1. Re-deploy previous image tag using [deploy/production/deploy-phase3d-production.sh](../deploy/production/deploy-phase3d-production.sh)
 2. Switch to CPU manifest if GPU scheduling fails
 3. Re-publish previous frontend bundle to S3 and invalidate CloudFront
-4. Disable optional Phase3D/CDN jobs in [ .github/workflows/deploy.yml](.github/workflows/deploy.yml) if needed
+4. Disable optional Phase3D/CDN jobs in [.github/workflows/build.yml](../.github/workflows/build.yml) if needed
 
 ## Suggested PR Description Body
 
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,30 @@
+# Documentation Index
+
+This directory contains the active operator and integration documentation.
+
+## Start Here
+
+- [Open Ecosystem First 10 Minutes](OPEN_ECOSYSTEM_FIRST_10_MINUTES.md)
+- [API HTTP Examples](api/http-examples.md)
+- [Alert Runbooks](ALERT_RUNBOOKS.md)
+
+## Operations and Deployment
+
+- [Phase 3D Production Deployment](PHASE_3D_PRODUCTION_DEPLOYMENT.md)
+- [Release Candidate Phase3D Secrets Runbook](RELEASE_CANDIDATE_PHASE3D_SECRETS_RUNBOOK.md)
+- [Compression Deployment](COMPRESSION_DEPLOYMENT.md)
+
+## Roadmaps
+
+- [Open Ecosystem Sprint 1 Roadmap](OPEN_ECOSYSTEM_SPRINT1_ROADMAP.md)
+- [Open Ecosystem Sprint 2 Roadmap](OPEN_ECOSYSTEM_SPRINT2_ROADMAP.md)
+
+## Performance and Hardware
+
+- [GPU/NPU Quick Start](GPU_NPU_QUICK_START.md)
+- [GPU/NPU Acceleration](GPU_NPU_ACCELERATION.md)
+- [Data Compression Guide](DATA_COMPRESSION_GUIDE.md)
+
+## Notes
+
+- Historical and archived material lives under [docs/archive](archive).
diff --git a/docs/RELEASE_CANDIDATE_PHASE3D_SECRETS_RUNBOOK.md b/docs/RELEASE_CANDIDATE_PHASE3D_SECRETS_RUNBOOK.md
@@ -6,10 +6,10 @@ This document is the operator-facing release-candidate checklist for production
 
 Ensure all required secrets and environment wiring exist before running:
 
-- [deploy/production/deploy-phase3d-production.sh](deploy/production/deploy-phase3d-production.sh)
-- [deploy/production/publish-frontend-cdn.sh](deploy/production/publish-frontend-cdn.sh)
-- [ .github/workflows/phase3d-production-deploy.yml](.github/workflows/phase3d-production-deploy.yml)
-- Optional post-production jobs in [ .github/workflows/deploy.yml](.github/workflows/deploy.yml)
+- [deploy/production/deploy-phase3d-production.sh](../deploy/production/deploy-phase3d-production.sh)
+- [deploy/production/publish-frontend-cdn.sh](../deploy/production/publish-frontend-cdn.sh)
+- [.github/workflows/phase3d-production-deploy.yml](../.github/workflows/phase3d-production-deploy.yml)
+- Optional post-production jobs in [.github/workflows/build.yml](../.github/workflows/build.yml)
 
 ## Required GitHub Secrets
 
@@ -88,7 +88,7 @@ cd packages/training && python -m py_compile phase3d_training.py api.py && cd ..
 
 ### Path A: Manual workflow
 
-1. Run [ .github/workflows/phase3d-production-deploy.yml](.github/workflows/phase3d-production-deploy.yml)
+1. Run [.github/workflows/phase3d-production-deploy.yml](../.github/workflows/phase3d-production-deploy.yml)
 2. Choose inputs:
    - `image_tag` = commit SHA (recommended)
    - `enable_gpu` = `true` if cluster has GPU nodes
@@ -103,7 +103,7 @@ curl http://localhost:5001/health
 
 ### Path B: main deploy workflow with optional jobs
 
-1. Trigger or merge into [ .github/workflows/deploy.yml](.github/workflows/deploy.yml)
+1. Trigger or merge into [.github/workflows/build.yml](../.github/workflows/build.yml)
 2. Ensure optional jobs are not skipped due to missing secrets
 3. Confirm post-production jobs complete:
    - `deploy-phase3d-k8s`
diff --git a/docs/RELEASE_PACKAGE_2026-03-26.md b/docs/RELEASE_PACKAGE_2026-03-26.md
@@ -0,0 +1,47 @@
+# Release Package 2026-03-26
+
+## Scope
+
+This package finalizes the open ecosystem and marketplace upgrade track with:
+
+- Marketplace, governance, and network expansion API/documentation updates.
+- Frontend browser flow controls and default-view wiring.
+- Observability hardening updates for dashboard query compatibility.
+- Prometheus marketplace alert additions and test coverage.
+- Documentation cleanup (link integrity and organization index).
+
+## Included Documentation Updates
+
+- docs/README.md
+- docs/OPEN_ECOSYSTEM_FIRST_10_MINUTES.md
+- docs/OPEN_ECOSYSTEM_SPRINT1_ROADMAP.md
+- docs/OPEN_ECOSYSTEM_SPRINT2_ROADMAP.md
+- docs/RELEASE_CANDIDATE_PHASE3D_SECRETS_RUNBOOK.md
+- docs/PR_READY_PHASE3D_OVERHAUL.md
+- docs/FEATURE_ARTIFACTS_2026-03-21.md
+- docs/COMPRESSION_DEPLOYMENT.md
+- docs/DATA_COMPRESSION_GUIDE.md
+- docs/GPU_NPU_ACCELERATION.md
+- docs/GPU_NPU_QUICK_START.md
+- README.md
+- SDK_API_STABILITY.md
+- SDK_RELEASE_GUIDE.md
+
+## Verification Checklist
+
+Completed checks during package validation:
+
+1. make lint
+2. make alerts-test
+3. make observability-smoke
+4. npm --prefix frontend run build
+5. python tests/scripts/python/test_marketplace_local_contracts.py
+6. python tests/scripts/python/test_marketplace_negative_paths.py
+7. make check
+8. active docs link audit (0 active-doc broken links)
+
+## Notes
+
+- Canonical docs entrypoint is now docs/README.md.
+- Root-level SDK policy and release guide files are retained as stable reference targets.
+- Archive documentation was intentionally left as historical and not rewritten.
diff --git a/grafana/provisioning/dashboards/operations_overview.json b/grafana/provisioning/dashboards/operations_overview.json
@@ -704,7 +704,7 @@
       "targets": [
         {
           "refId": "A",
-          "expr": "avg(tpm_node_trust_score{node_id!=\"\"}) or max(((clamp_max(100 * (tpm_certificates_verified_total / clamp_min(tpm_certificates_total, 1)), 100) and (tpm_certificates_total > 0)) or (100 * tpm_ca_certificate_valid))) or vector(0)"
+          "expr": "avg(tpm_node_trust_score) or max(((clamp_max(100 * (tpm_certificates_verified_total / clamp_min(tpm_certificates_total, 1)), 100) and (tpm_certificates_total > 0)) or (100 * tpm_ca_certificate_valid))) or vector(0)"
         }
       ],
       "fieldConfig": {
