.github/prompts/plan-homelabMCProadmap.prompt.md

@@ -0,0 +1,99 @@
+## Roadmap Plan: Homelab MCP Gateway Expansion
+
+### TL;DR
+Evolve the current MVP into a production-grade platform by adding shards, hardening the gateway, improving security, expanding observability, and introducing mesh-ready capabilities only when justified.  
+Estimated total roadmap effort: **8 to 14 weeks** (part-time homelab pace).
+
+### Planning Assumptions
+1. Work is done incrementally with validation after each phase.
+2. Existing Traefik shard and gateway baseline are already in place.
+3. Priority can shift based on incidents, new integrations, or time constraints.
+
+---
+
+## Phases, Tasks, and Time Estimates
+
+| Phase | Task | Time to Complete | Notes |
+|---|---|---:|---|
+| Phase 1: Foundation Hardening | Gateway health registry and shard auto-disable | 0.5-1 day | Prevents unhealthy shard routing |
+| Phase 1: Foundation Hardening | Standard error model and partial-failure handling | 1-2 days | Improves reliability and UX |
+| Phase 1: Foundation Hardening | Per-tool timeout/retry policy | 0.5-1 day | Fast resilience win |
+| Phase 1: Foundation Hardening | Basic rate limiting/per-client quotas | 1 day | Protects from accidental overload |
+|  | **Phase 1 Total** | **3-5 days** |  |
+
+| Phase | Task | Time to Complete | Notes |
+|---|---|---:|---|
+| Phase 2: Security Baseline | Bearer token auth for gateway and shards | 1-2 days | Start simple, internal tokens |
+| Phase 2: Security Baseline | Tool-level RBAC (read vs admin tools) | 1-2 days | Reduces blast radius |
+| Phase 2: Security Baseline | Audit logging for every tool invocation | 0.5-1 day | Supports incident review |
+| Phase 2: Security Baseline | Secret management pattern (env + vault-ready abstraction) | 1 day | Keeps migration easy later |
+|  | **Phase 2 Total** | **3.5-6 days** |  |
+
+| Phase | Task | Time to Complete | Notes |
+|---|---|---:|---|
+| Phase 3: Documentation Intelligence | Official-source allowlist for doc fetchers | 0.5 day | Limits bad sources |
+| Phase 3: Documentation Intelligence | Caching with TTL and source metadata | 1 day | Lower latency, fewer external calls |
+| Phase 3: Documentation Intelligence | Summarize-and-cite doc responses | 1 day | Better operator trust |
+| Phase 3: Documentation Intelligence | Upstream doc change detection (diff/check) | 1-2 days | Detects API drift |
+|  | **Phase 3 Total** | **3.5-4.5 days** |  |
+
+| Phase | Task | Time to Complete | Notes |
+|---|---|---:|---|
+| Phase 4: Additional Shards | Dozzle shard (logs, stats, search) | 3-5 days | Highest immediate value |
+| Phase 4: Additional Shards | Authentik shard (apps/flows/branding) | 4-6 days | IAM controls require care |
+| Phase 4: Additional Shards | Gitea shard (repo/webhook/deploy metadata) | 2-4 days | Useful for GitOps visibility |
+| Phase 4: Additional Shards | Komodo shard (status + guarded deploy actions) | 3-5 days | Add write guardrails early |
+|  | **Phase 4 Total** | **12-20 days** |  |
+
+| Phase | Task | Time to Complete | Notes |
+|---|---|---:|---|
+| Phase 5: Traefik Shard Maturity | Dry-run mode for route changes | 1 day | Safer ops |
+| Phase 5: Traefik Shard Maturity | Rollback snapshots/versioned configs | 1-2 days | Quick recovery path |
+| Phase 5: Traefik Shard Maturity | Conflict detection before writes | 1 day | Prevents route collisions |
+| Phase 5: Traefik Shard Maturity | Middleware preset library + validation | 1-2 days | Standardization |
+|  | **Phase 5 Total** | **4-6 days** |  |
+
+| Phase | Task | Time to Complete | Notes |
+|---|---|---:|---|
+| Phase 6: Test and Quality | Gateway↔shard contract tests | 1-2 days | Prevents integration regressions |
+| Phase 6: Test and Quality | Mock-based shard simulation tests | 1-2 days | Faster local testing |
+| Phase 6: Test and Quality | CI checks for templates/scaffolded shards | 1 day | Enforces consistency |
+| Phase 6: Test and Quality | Post-deploy smoke test command | 0.5-1 day | Faster validation loop |
+|  | **Phase 6 Total** | **3.5-6 days** |  |
+
+| Phase | Task | Time to Complete | Notes |
+|---|---|---:|---|
+| Phase 7: Observability and Ops | Structured logs with request IDs | 0.5-1 day | Better debugging |
+| Phase 7: Observability and Ops | Metrics: latency/error/utilization | 1-2 days | Capacity planning input |
+| Phase 7: Observability and Ops | Alerts for shard offline/state drift | 1 day | Operational guardrails |
+| Phase 7: Observability and Ops | Optional tracing across gateway/shards | 1-2 days | Add when needed |
+|  | **Phase 7 Total** | **3.5-6 days** |  |
+
+| Phase | Task | Time to Complete | Notes |
+|---|---|---:|---|
+| Phase 8: Mesh-Ready Evolution | Service discovery abstraction | 1-2 days | Remove hardcoded endpoints |
+| Phase 8: Mesh-Ready Evolution | mTLS-ready client/server wrappers | 2-3 days | Security prep |
+| Phase 8: Mesh-Ready Evolution | Inter-service policy model | 1-2 days | Zero-trust stepping stone |
+| Phase 8: Mesh-Ready Evolution | Full cross-node mesh pilot (optional) | 3-5 days | Only if justified |
+|  | **Phase 8 Total** | **7-12 days** |  |
+
+---
+
+## Suggested Execution Order (Pragmatic)
+1. Phase 1 Foundation Hardening  
+2. Phase 2 Security Baseline  
+3. Phase 4 Additional Shards (start with Dozzle first)  
+4. Phase 3 Documentation Intelligence  
+5. Phase 5 Traefik Maturity  
+6. Phase 6 Test and Quality  
+7. Phase 7 Observability and Ops  
+8. Phase 8 Mesh-Ready Evolution (optional trigger-based)
+
+---
+
+## Milestone Timing (High Level)
+1. **Milestone A (Week 1-2):** Foundation + Security done  
+2. **Milestone B (Week 3-6):** Dozzle + one additional shard operational  
+3. **Milestone C (Week 6-8):** Documentation intelligence + Traefik safety features  
+4. **Milestone D (Week 8-10):** Test harness + operational observability  
+5. **Milestone E (Week 10+):** Mesh-ready features or full mesh pilot if needed