feat(production): add big screen dashboard API

[shark0F0497]

Pull Request Checklist

Please ensure your PR meets the following requirements:

• Code follows the style guidelines
• Tests pass locally
• Code is formatted
• Documentation updated if needed
• Commit messages follow conventional commits
• PR description is complete and clear

---

Summary

This PR adds the Keystone backend support for the Synapse production big-screen dashboard, including the overview aggregate API, dashboard display-token access, MCAP preview presign support, and supporting tests and design documentation.

---

Motivation

• Provide a backend contract for the production big-screen dashboard to render task totals, trends, quality metrics, device health, station summaries, recent tasks, and MCAP previews.
• Allow controlled read-only dashboard display access without requiring a full admin JWT session.
• Keep dashboard metrics aligned across admin and display views by tightening task scope and aggregation behavior.
• Document the expected dashboard layout, branding, task feed, and MCAP playback requirements for frontend/backend alignment.

---

Changes

Modified Files

• docker/.env.example - Documents the optional KEYSTONE_DASHBOARD_DISPLAY_TOKEN environment variable.
• internal/api/handlers/episode.go - Allows valid dashboard display tokens to presign MCAP preview files while rejecting sidecar presigns for display-token requests.
• internal/api/handlers/production_dashboard.go - Adds the production dashboard overview contract, display-role scoping, preview metadata, production totals, task trends, quality metrics, device/station summaries, recent tasks, and refined task aggregation behavior.
• internal/api/handlers/production_dashboard_test.go - Extends tests for dashboard query validation, display-role scoping, overview contracts, device/station distribution, preview URLs, task scope, and SQL generation.
• internal/config/config.go - Loads the optional dashboard display token from KEYSTONE_DASHBOARD_DISPLAY_TOKEN.
• internal/config/config_test.go - Covers the new auth configuration field.
• internal/middleware/jwt_auth.go - Adds DashboardAuth, display-token detection, constant-time token comparison, and display-role claims.
• internal/server/server.go - Wires recorder/transfer hubs into the dashboard handler and mounts dashboard routes behind DashboardAuth.

Added Files

• docs/designs/synapse-admin-brand-palette.md - Documents the Synapse admin brand palette.
• docs/designs/synapse-production-big-screen-tasks.md - Documents big-screen task feed and lifecycle display requirements.
• docs/designs/synapse-production-big-screen.md - Documents the production big-screen dashboard layout, metrics, scaling, and playback requirements.
• internal/middleware/jwt_auth_test.go - Adds tests for display-token validation and DashboardAuth display-token acceptance.

Deleted Files

• None.

---

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update (documentation changes only)
• Refactoring (code improvement without functional changes)
• Performance improvement (code changes that improve performance)
• Test changes (adding, modifying, or removing tests)

---

Impact Analysis

Breaking Changes

None.

Backward Compatibility

Fully backward compatible. Existing JWT-based admin and data-collector dashboard access remains supported, and display-token access is additive and optional.

---

Testing

Test Environment

• Local Keystone worktree: keystone-worktree2
• Go: go1.24.13

Test Cases

• Unit tests pass locally
• Integration tests pass locally
• E2E tests pass (if applicable)
• Manual testing completed

Commands Run

• gofmt -l internal/api/handlers/episode.go internal/api/handlers/production_dashboard.go internal/api/handlers/production_dashboard_test.go internal/config/config.go internal/config/config_test.go internal/middleware/jwt_auth.go internal/middleware/jwt_auth_test.go internal/server/server.go
• go test ./internal/middleware -v
• go test ./internal/config -v
• go test ./internal/api/handlers -run 'Test(ParseProductionDashboard|Dashboard|ProductionDashboard)' -v
• go test ./internal/api/handlers -run TestResolveProductionDashboardScopeAllowsDisplayRole -v
• go test -cover -race -v ./...

Manual Testing Steps

• Not performed in this change set.

Test Coverage

• New tests added
• Existing tests updated
• Coverage maintained or improved

Known Local Test Limitation

go test -cover -race -v ./... was attempted locally but failed during setup/build in the current environment with:

package archebase.com/keystone-edge/cmd/keystone-edge: cannot find package

The targeted tests covering this PR's new dashboard, config, and middleware behavior passed.

---

Screenshots / Recordings

Not applicable for this backend change.

---

Performance Impact

• Memory usage: No measured regression.
• CPU usage: No measured regression; dashboard queries use bounded limits for trend, distribution, active, recent, and preview data.
• Throughput: No backend write-path impact expected; this adds read-focused dashboard aggregation routes.
• Lock contention: No change.

---

Documentation

• README.md updated
• ARCHITECTURE.md updated
• CONTRIBUTING.md updated
• API documentation updated
• Design docs updated in docs/designs/
• No documentation changes needed

---

Related Issues

• N/A

---

Additional Notes

• KEYSTONE_DASHBOARD_DISPLAY_TOKEN is optional. Leaving it empty disables display-token access.
• Display-token requests are limited to production dashboard routes and MCAP preview presigns.
• The token comparison hashes both values and uses constant-time comparison.

---

Reviewers

N/A

---

Notes for Reviewers

• Please review internal/api/handlers/production_dashboard.go, internal/middleware/jwt_auth.go, and internal/api/handlers/episode.go closely.
• Focus on display-token authorization boundaries, dashboard scope filtering, and the overview response contract consumed by Synapse.
• Verify that MCAP preview presign access is limited to kind=mcap for display-token callers.

---

Checklist for Reviewers

• Code changes are correct and well-implemented
• Tests are adequate and pass
• Documentation is updated and accurate
• No unintended side effects
• Performance impact is acceptable
• Backward compatibility maintained (if applicable)