docs: update dead links

docs/content/adr/0006-http-framework.md

@@ -27,7 +27,7 @@ Use **gin-gonic/gin** (v1.9.1+) as the HTTP framework.
 - Easy route grouping (useful for modules)
 - Good OpenTelemetry integration support
 - Widely used and well-documented
-- Recommended in playbook-golang.md
+- Recommended in playbook.md
 
 ## Consequences
 

docs/content/adr/0010-ci-cd-platform.md

@@ -26,7 +26,7 @@ Use **GitHub Actions** for CI/CD pipeline.
 - Rich ecosystem of actions
 - Easy to configure with YAML
 - Good documentation and community support
-- Recommended in playbook-golang.md
+- Recommended in playbook.md
 
 ## Consequences
 

docs/content/adr/0013-database-orm.md

@@ -27,7 +27,7 @@ Use **entgo.io/ent** as the primary ORM for the platform.
 - Strong relationship modeling
 - Good performance (no reflection at runtime)
 - Active development and good documentation
-- Recommended in playbook-golang.md
+- Recommended in playbook.md
 - Easy to integrate with OpenTelemetry
 
 ## Consequences

docs/content/adr/0016-opentelemetry-observability.md

@@ -29,7 +29,7 @@ Use **OpenTelemetry (OTEL)** for all observability:
 - Excellent Go SDK support
 - Integrates with major observability tools
 - Supports metrics, traces, and logs
-- Recommended in playbook-golang.md
+- Recommended in playbook.md
 - Future-proof (not locked to specific vendor)
 
 ## Consequences

docs/content/architecture/service-orchestration.md

@@ -398,6 +398,6 @@ This service orchestration integrates with:
 - [Module Integration Patterns](module-integration-patterns.md) - Module service integration
 - [Operational Scenarios](operational-scenarios.md) - Service interaction scenarios
 - [Architecture Overview](architecture.md) - System architecture
-- [ADR-0029: Microservices Architecture](adr/0029-microservices-architecture.md) - Architecture decision
+- [ADR-0029: Microservices Architecture](../adr/0029-microservices-architecture.md) - Architecture decision
-- [ADR-0030: Service Communication Strategy](adr/0030-service-communication-strategy.md) - Communication patterns
+- [ADR-0030: Service Communication Strategy](../adr/0030-service-communication-strategy.md) - Communication patterns
 

docs/content/index.md

@@ -20,17 +20,16 @@ Go Platform is a modular, extensible platform designed to support multiple busin
 - **[Playbook](playbook.md)**: Detailed implementation guide and best practices
 
 ### 🏛️ Architecture
-- **[Architecture Overview](architecture.md)**: System architecture with diagrams
+- **[Architecture Overview](architecture/architecture.md)**: System architecture with diagrams
-- **[Module Architecture](architecture-modules.md)**: Module system design and integration
+- **[Module Architecture](architecture/architecture-modules.md)**: Module system design and integration
-- **[Module Requirements](module-requirements.md)**: Detailed requirements for each module
+- **[Module Requirements](architecture/module-requirements.md)**: Detailed requirements for each module
-- **[Component Relationships](component-relationships.md)**: Component interactions and dependencies
+- **[Component Relationships](architecture/component-relationships.md)**: Component interactions and dependencies
-
+- **System Specifications**
-### 📐 System Specifications
+  - **[System Behavior Overview](architecture/system-behavior.md)**: How the system behaves end-to-end
-- **[System Behavior Overview](system-behavior.md)**: How the system behaves end-to-end
+  - **[Service Orchestration](architecture/service-orchestration.md)**: How services work together
-- **[Service Orchestration](service-orchestration.md)**: How services work together
+  - **[Module Integration Patterns](architecture/module-integration-patterns.md)**: How modules integrate with the platform
-- **[Module Integration Patterns](module-integration-patterns.md)**: How modules integrate with the platform
+  - **[Operational Scenarios](architecture/operational-scenarios.md)**: Common operational flows and use cases
-- **[Operational Scenarios](operational-scenarios.md)**: Common operational flows and use cases
+  - **[Data Flow Patterns](architecture/data-flow-patterns.md)**: How data flows through the system
-- **[Data Flow Patterns](data-flow-patterns.md)**: How data flows through the system
 
 ### 🏗️ Architecture Decision Records (ADRs)
 All architectural decisions are documented in [ADR records](adr/README.md), organized by implementation epic:

docs/content/plan.md

@@ -2,7 +2,7 @@
 
 **"Plug‑in‑friendly SaaS/Enterprise Platform – Go Edition"**
 
-> This document outlines a complete, epic-based implementation plan for building the Go platform boilerplate based on the requirements from `playbook.md` and `playbook-golang.md`.
+> This document outlines a complete, epic-based implementation plan for building the Go platform boilerplate based on the requirements from `playbook.md`.
 
 ---
 
@@ -1649,7 +1649,6 @@ The platform is considered complete when:
 ## References
 
 - [playbook.md](./playbook.md) - General platform playbook
-- [playbook-golang.md](./playbook-golang.md) - Go-specific playbook
 - [Go Modules Documentation](https://go.dev/doc/modules)
 - [Ent Documentation](https://entgo.io/docs/getting-started)
 - [Uber FX Documentation](https://github.com/uber-go/fx)

docs/content/stories/COMPLETE_TASK_LIST.md

@@ -8,39 +8,76 @@ Tasks are organized by epic and section. Each task file follows the naming conve
 
 ## Epic 0: Project Setup & Foundation
 
-### 0.1 Repository Bootstrap
+### Epic 0 Stories
-- [0.1.1 - Initialize Go Module](./epic0/0.1.1-initialize-go-module.md)
+- [0.1 Project Initialization and Repository Structure](./epic0/0.1-project-initialization.md)
-- [0.1.2 - Create Directory Structure](./epic0/0.1.2-create-directory-structure.md)
+- [0.2 Configuration Management System](./epic0/0.2-configuration-management-system.md)
-- [0.1.3 - Add Gitignore](./epic0/0.1.3-add-gitignore.md)
+- [0.3 Structured Logging System](./epic0/0.3-structured-logging-system.md)
-- [0.1.4 - Create Initial README](./epic0/0.1.4-create-initial-readme.md)
+- [0.4 CI/CD Pipeline and Development Tooling](./epic0/0.4-cicd-pipeline.md)
+- [0.5 Dependency Injection and Application Bootstrap](./epic0/0.5-di-and-bootstrap.md)
 
-### 0.2 Configuration System
+## Epic 1: Core Kernel & Infrastructure
-- [0.2.1 - Install Configuration Dependencies](./epic0/0.2.1-install-config-dependencies.md)
+- [1.1 Enhanced DI Container](./epic1/1.1-enhanced-di-container.md)
-- [0.2.2 - Create Config Interface](./epic0/0.2.2-create-config-interface.md)
+- [1.2 Database Layer](./epic1/1.2-database-layer.md)
-- [0.2.3 - Implement Config Loader](./epic0/0.2.3-implement-config-loader.md)
+- [1.3 Health & Metrics System](./epic1/1.3-health-metrics-system.md)
-- [0.2.4 - Create Configuration Files](./epic0/0.2.4-create-configuration-files.md)
+- [1.4 Error Handling](./epic1/1.4-error-handling.md)
+- [1.5 HTTP Server](./epic1/1.5-http-server.md)
+- [1.6 OpenTelemetry](./epic1/1.6-opentelemetry.md)
+- [1.7 Service Client Interfaces](./epic1/1.7-service-abstraction-layer.md)
+- [Epic 1 Overview](./epic1/README.md)
 
-### 0.3 Logging Foundation
+## Epic 2: Authentication & Authorization
-- [0.3.1 - Install Logging Dependencies](./epic0/0.3.1-install-logging-dependencies.md)
+- [2.1 JWT Authentication System](./epic2/2.1-jwt-authentication.md)
-- See [Epic 0 README](./epic0/README.md) for remaining tasks
+- [2.2 Identity Management System](./epic2/2.2-identity-management.md)
+- [2.3 RBAC System](./epic2/2.3-rbac-system.md)
+- [2.4 Role Management API](./epic2/2.4-role-management.md)
+- [2.5 Audit Logging System](./epic2/2.5-audit-logging.md)
+- [2.6 Database Seeding and Initialization](./epic2/2.6-database-seeding.md)
+- [Epic 2 Overview](./epic2/README.md)
 
-### 0.4 Basic CI/CD Pipeline
+## Epic 3: Module Framework
-- See [Epic 0 README](./epic0/README.md) for tasks
+- [3.1 Module System Interface](./epic3/3.1-module-system-interface.md)
+- [3.2 Permission Code Generation](./epic3/3.2-permission-code-generation.md)
+- [3.3 Module Loader](./epic3/3.3-module-loader.md)
+- [3.4 Module CLI](./epic3/3.4-module-cli.md)
+- [3.5 Service Registry and Discovery](./epic3/3.5-service-registry.md)
+- [Epic 3 Overview](./epic3/README.md)
 
-### 0.5 Dependency Injection Setup
+## Epic 4: Sample Feature Module (Blog)
-- See [Epic 0 README](./epic0/README.md) for tasks
+- [4.1 Complete Blog Module](./epic4/4.1-blog-module.md)
+- [Epic 4 Overview](./epic4/README.md)
 
-## Epic 1-8 Tasks
+## Epic 5: Infrastructure Adapters
+- [5.1 Cache System](./epic5/5.1-cache-system.md)
+- [5.2 Event Bus](./epic5/5.2-event-bus.md)
+- [5.3 Blob Storage](./epic5/5.3-blob-storage.md)
+- [5.4 Email Notification](./epic5/5.4-email-notification.md)
+- [5.5 Scheduler & Jobs](./epic5/5.5-scheduler-jobs.md)
+- [5.6 Secret Store](./epic5/5.6-secret-store.md)
+- [5.7 gRPC Service Definitions and Clients](./epic5/5.7-grpc-services.md)
+- [Epic 5 Overview](./epic5/README.md)
 
-Detailed task files for Epics 1-8 are being created. See individual epic README files:
+## Epic 6: Observability & Production Readiness
-- [Epic 1 README](./epic1/README.md) - Core Kernel & Infrastructure
+- [6.1 Enhanced Observability](./epic6/6.1-enhanced-observability.md)
-- [Epic 2 README](./epic2/README.md) - Authentication & Authorization
+- [6.2 Error Reporting](./epic6/6.2-error-reporting.md)
-- [Epic 3 README](./epic3/README.md) - Module Framework
+- [6.3 Grafana Dashboards](./epic6/6.3-grafana-dashboards.md)
-- [Epic 4 README](./epic4/README.md) - Sample Feature Module (Blog)
+- [6.4 Rate Limiting](./epic6/6.4-rate-limiting.md)
-- [Epic 5 README](./epic5/README.md) - Infrastructure Adapters
+- [6.5 Security Hardening](./epic6/6.5-security-hardening.md)
-- [Epic 6 README](./epic6/README.md) - Observability & Production Readiness
+- [6.6 Performance Optimization](./epic6/6.6-performance-optimization.md)
-- [Epic 7 README](./epic7/README.md) - Testing, Documentation & CI/CD
+- [Epic 6 Overview](./epic6/README.md)
-- [Epic 8 README](./epic8/README.md) - Advanced Features & Polish
+
+## Epic 7: Testing, Documentation & CI/CD
+- [7.1 Testing Suite](./epic7/7.1-testing-suite.md)
+- [7.2 Documentation](./epic7/7.2-documentation.md)
+- [7.3 CI/CD Enhancement](./epic7/7.3-cicd-enhancement.md)
+- [7.4 Docker Deployment](./epic7/7.4-docker-deployment.md)
+- [Epic 7 Overview](./epic7/README.md)
+
+## Epic 8: Advanced Features & Polish
+- [8.1 OIDC Support](./epic8/8.1-oidc-support.md)
+- [8.2 GraphQL API](./epic8/8.2-graphql-api.md)
+- [8.3 Additional Modules](./epic8/8.3-additional-modules.md)
+- [8.4 Final Polish](./epic8/8.4-final-polish.md)
+- [Epic 8 Overview](./epic8/README.md)
 
 ## Task Status Tracking
 

docs/content/stories/TASK_TEMPLATE.md

@@ -31,7 +31,7 @@ Use this template for creating new task files.
 - [ ] {Criterion 3}
 
 ## Related ADRs
-- [ADR-XXXX: {ADR Title}](../../adr/XXXX-adr-title.md)
+- [ADR-XXXX: {ADR Title}](../adr/XXXX-adr-title.md)
 
 ## Implementation Notes
 - {Note 1}

docs/content/stories/generate_tasks.py

@@ -14,7 +14,7 @@ def parse_plan(plan_path):
         content = f.read()
     
     tasks = []
-    current_phase = None
+    current_epic = None
     current_section = None
     subtask_num = 1
     
@@ -23,11 +23,12 @@ def parse_plan(plan_path):
     while i < len(lines):
         line = lines[i].rstrip()
         
-        # Phase header
+        # Epic header (supports legacy Phase headers for compatibility)
-        phase_match = re.match(r'^## Phase (\d+):', line)
+        epic_match = re.match(r'^## Epic (\d+):', line)
-        if phase_match:
+        legacy_phase_match = re.match(r'^## Phase (\d+):', line)
-            current_phase = int(phase_match.group(1))
+        if epic_match or legacy_phase_match:
-            subtask_num = 1  # Reset subtask counter for new phase
+            current_epic = int((epic_match or legacy_phase_match).group(1))
+            subtask_num = 1  # Reset subtask counter for new epic
             i += 1
             continue
         
@@ -41,7 +42,7 @@ def parse_plan(plan_path):
         
         # Task item (checkbox) - must match exactly
         task_match = re.match(r'^- \[ \] (.+)', line)
-        if task_match and current_phase is not None and current_section is not None:
+        if task_match and current_epic is not None and current_section is not None:
             task_desc = task_match.group(1).strip()
             
             # Handle tasks that end with colon (might have code block or list following)
@@ -64,10 +65,10 @@ def parse_plan(plan_path):
             else:
                 i += 1
             
-            # Only add if we have valid phase and section
+            # Only add if we have valid epic and section
-            if current_phase is not None and current_section is not None:
+            if current_epic is not None and current_section is not None:
                 tasks.append({
-                    'phase': current_phase,
+                    'epic': current_epic,
                     'section': current_section,
                     'subtask': subtask_num,
                     'description': task_desc,
@@ -82,14 +83,14 @@ def parse_plan(plan_path):
 
 def create_task_file(task, output_dir):
     """Create a task markdown file"""
-    phase_dir = output_dir / f"phase{task['phase']}"
+    epic_dir = output_dir / f"epic{task['epic']}"
-    phase_dir.mkdir(exist_ok=True)
+    epic_dir.mkdir(exist_ok=True)
     
     task_id = f"{task['section']}.{task['subtask']}"
     # Create safe filename
     safe_desc = re.sub(r'[^\w\s-]', '', task['description'])[:50].strip().replace(' ', '-').lower()
     filename = f"{task_id}-{safe_desc}.md"
-    filepath = phase_dir / filename
+    filepath = epic_dir / filename
     
     # Generate content
     content = f"""# Task {task_id}: {task['description']}
@@ -97,7 +98,7 @@ def create_task_file(task, output_dir):
 ## Metadata
 - **Task ID**: {task_id}
 - **Title**: {task['description']}
-- **Phase**: {task['phase']} - {get_phase_name(task['phase'])}
+- **Epic**: {task['epic']} - {get_epic_name(task['epic'])}
 - **Section**: {task['section']}
 - **Status**: Pending
 - **Priority**: High
@@ -142,9 +143,9 @@ go test ./...
     
     return filepath
 
-def get_phase_name(phase_num):
+def get_epic_name(epic_num):
-    """Get phase name from number"""
+    """Get epic name from number"""
-    phases = {
+    epics = {
         0: "Project Setup & Foundation",
         1: "Core Kernel & Infrastructure",
         2: "Authentication & Authorization",
@@ -155,7 +156,7 @@ def get_phase_name(phase_num):
         7: "Testing, Documentation & CI/CD",
         8: "Advanced Features & Polish"
     }
-    return phases.get(phase_num, "Unknown")
+    return epics.get(epic_num, "Unknown")
 
 def main():
     script_dir = Path(__file__).parent
@@ -182,13 +183,13 @@ def main():
                 task_id = f"{task['section']}.{task['subtask']}"
                 
                 # Determine filepath before creating
-                phase_dir = output_dir / f"phase{task['phase']}"
+                epic_dir = output_dir / f"epic{task['epic']}"
-                phase_dir.mkdir(exist_ok=True)
+                epic_dir.mkdir(exist_ok=True)
                 
                 # Create safe filename
                 safe_desc = re.sub(r'[^\w\s-]', '', task['description'])[:50].strip().replace(' ', '-').lower()
                 filename = f"{task_id}-{safe_desc}.md"
-                filepath = phase_dir / filename
+                filepath = epic_dir / filename
                 
                 # Check if file already exists (skip if so)
                 if filepath.exists() and filepath.stat().st_size > 100:

docs/content/versions.json

@@ -0,0 +1,9 @@
+[
+  {
+    "version": "latest",
+    "title": "Latest",
+    "aliases": ["stable"],
+    "default": true
+  }
+]
+

docs/mkdocs.yml

@@ -80,17 +80,17 @@ nav:
     - Implementation Plan: plan.md
     - Playbook: playbook.md
   - Architecture:
-    - Architecture Overview: architecture.md
+    - Architecture Overview: architecture/architecture.md
-    - Module Architecture: architecture-modules.md
+    - Module Architecture: architecture/architecture-modules.md
-    - Module Requirements: module-requirements.md
+    - Module Requirements: architecture/module-requirements.md
-    - Component Relationships: component-relationships.md
+    - Component Relationships: architecture/component-relationships.md
-  - System Specifications:
+    - System Specifications:
-    - System Behavior Overview: system-behavior.md
+      - System Behavior Overview: architecture/system-behavior.md
-    - Service Orchestration: service-orchestration.md
+      - Service Orchestration: architecture/service-orchestration.md
-    - Module Integration Patterns: module-integration-patterns.md
+      - Module Integration Patterns: architecture/module-integration-patterns.md
-    - Operational Scenarios: operational-scenarios.md
+      - Operational Scenarios: architecture/operational-scenarios.md
-    - Data Flow Patterns: data-flow-patterns.md
+      - Data Flow Patterns: architecture/data-flow-patterns.md
-  - Architecture Decision Records:
+  - Decisions:
     - ADR Overview: adr/README.md
     - "Epic 0: Project Setup & Foundation":
       - "ADR-0001: Go Module Path": adr/0001-go-module-path.md
@@ -130,7 +130,7 @@ nav:
     - "Architecture & Scaling":
       - "ADR-0029: Microservices Architecture": adr/0029-microservices-architecture.md
       - "ADR-0030: Service Communication Strategy": adr/0030-service-communication-strategy.md
-  - Implementation Tasks:
+  - Implementation:
     - Tasks Overview: stories/README.md
     - "Epic 0: Project Setup & Foundation": stories/epic0/README.md
     - "Epic 1: Core Kernel & Infrastructure": stories/epic1/README.md
@@ -153,9 +153,7 @@ extra_css:
 extra:
   social:
     - icon: fontawesome/brands/github
-      link: https://github.com/yourorg/platform
+      link: https://git.dcentral.systems/toolz/goplt
-  version:
-    provider: mike
 
 # Copyright
 copyright: Copyright © 2024 Go Platform Team