fix: add build-complete sync point for docs pipeline ordering

The export-openapi step was running in parallel with component builds
because it had no explicit dependency. This could cause docs generation
to run before component services were fully built.

Changes:
- Add build-complete step with NO depends_on (waits for ALL prior steps)
- Make export-openapi depend on build-complete
- Complete docs pipeline: export-openapi → generate-docs → build-docs →
  build-docs-image → deploy-docs
- Update verify step label selector to use project= instead of app=

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

internal/adapter/templates/templates/skeleton/.woodpecker.yml.tmpl

@@ -37,11 +37,206 @@ steps:
   # COMPONENT_STEPS_BELOW
   # Do not remove the marker above - component steps are inserted here
 
+  # Sync point after all component builds complete
+  # This step has NO depends_on, so it waits for ALL previous steps
+  # (including any component steps inserted above) to complete
+  build-complete:
+    image: alpine:3.19
+    commands:
+      - echo "All component builds complete"
+    when:
+      branch: main
+      event: push
+
+  # Export OpenAPI specs from built services
+  # Runs after build-complete to ensure all services are ready
+  export-openapi:
+    depends_on: [build-complete]
+    image: golang:1.23
+    commands:
+      - |
+        echo "==> Exporting OpenAPI specs from services"
+        for svc_dir in services/*/; do
+          [ -d "$svc_dir" ] || continue
+          svc=$(basename "$svc_dir")
+          [ "$svc" = ".gitkeep" ] && continue
+
+          if [ -f "$svc_dir/cmd/server/main.go" ]; then
+            echo "    Exporting spec for $svc"
+            (cd "$svc_dir" && go run ./cmd/server --export-openapi > openapi.json) || {
+              echo "    WARNING: Failed to export spec for $svc"
+              continue
+            }
+            echo "    Generated $svc_dir/openapi.json"
+          fi
+        done
+    when:
+      branch: main
+      event: push
+
+  # Generate API documentation from OpenAPI specs
+  generate-docs:
+    image: node:20-slim
+    depends_on: [export-openapi]
+    commands:
+      - npm install -g widdershins
+      - |
+        echo "==> Generating Slate markdown from OpenAPI specs"
+        mkdir -p docs/source/includes
+        found_specs=0
+        for spec in services/*/openapi.json; do
+          if [ -f "$spec" ]; then
+            svc=$(dirname "$spec" | xargs basename)
+            echo "    Converting $svc"
+            widdershins \
+              --language_tabs 'shell:curl' 'go:Go' \
+              --summary \
+              --omitHeader \
+              --resolve \
+              --shallowSchemas \
+              "$spec" \
+              -o "docs/source/includes/_${svc}.md"
+            found_specs=$((found_specs + 1))
+          fi
+        done
+        echo "==> Converted $found_specs service specs"
+    when:
+      branch: main
+      event: push
+
+  # Build Slate static documentation (skipped if no docs infrastructure)
+  build-docs:
+    image: ruby:3.2-slim
+    depends_on: [generate-docs]
+    commands:
+      - |
+        if [ ! -d "docs" ] || [ ! -f "docs/Gemfile" ]; then
+          echo "==> No docs/ directory or Gemfile found, skipping Slate build"
+          exit 0
+        fi
+      - apt-get update && apt-get install -y build-essential nodejs
+      - cd docs && bundle install --jobs 4
+      - cd docs && bundle exec middleman build --clean
+      - echo "==> Docs built to docs/build/"
+    when:
+      branch: main
+      event: push
+
+  # Build and push docs-nginx image (skipped if no docs build output)
+  build-docs-image:
+    image: gcr.io/kaniko-project/executor:latest
+    depends_on: [build-docs]
+    commands:
+      - |
+        if [ ! -d "docs/build" ]; then
+          echo "==> No docs/build/ directory, skipping image build"
+          exit 0
+        fi
+      - /kaniko/executor --dockerfile=docs/Dockerfile.nginx --context=docs --destination=registry.threesix.ai/{{PROJECT_NAME}}-docs:latest --destination=registry.threesix.ai/{{PROJECT_NAME}}-docs:${CI_COMMIT_SHA:0:8}
+    when:
+      branch: main
+      event: push
+
+  # Deploy docs to docs.{{DOMAIN}} (skipped if no docs image was built)
+  deploy-docs:
+    image: bitnami/kubectl:latest
+    depends_on: [build-docs-image]
+    commands:
+      - |
+        # Check if docs image exists by trying to describe the deployment
+        # If this is the first build, the deployment won't exist yet
+        if [ ! -d "docs/build" ]; then
+          echo "==> No docs build output, skipping deployment"
+          exit 0
+        fi
+      - |
+        cat <<EOF | kubectl apply -f -
+        apiVersion: apps/v1
+        kind: Deployment
+        metadata:
+          name: {{PROJECT_NAME}}-docs
+          namespace: projects
+          labels:
+            app: {{PROJECT_NAME}}-docs
+            project: {{PROJECT_NAME}}
+        spec:
+          replicas: 1
+          selector:
+            matchLabels:
+              app: {{PROJECT_NAME}}-docs
+          template:
+            metadata:
+              labels:
+                app: {{PROJECT_NAME}}-docs
+                project: {{PROJECT_NAME}}
+            spec:
+              containers:
+              - name: nginx
+                image: registry.threesix.ai/{{PROJECT_NAME}}-docs:${CI_COMMIT_SHA:0:8}
+                ports:
+                - containerPort: 80
+                resources:
+                  requests:
+                    cpu: 10m
+                    memory: 16Mi
+                  limits:
+                    cpu: 100m
+                    memory: 64Mi
+        ---
+        apiVersion: v1
+        kind: Service
+        metadata:
+          name: {{PROJECT_NAME}}-docs
+          namespace: projects
+          labels:
+            app: {{PROJECT_NAME}}-docs
+            project: {{PROJECT_NAME}}
+        spec:
+          selector:
+            app: {{PROJECT_NAME}}-docs
+          ports:
+          - port: 80
+            targetPort: 80
+        ---
+        apiVersion: networking.k8s.io/v1
+        kind: Ingress
+        metadata:
+          name: {{PROJECT_NAME}}-docs
+          namespace: projects
+          labels:
+            app: {{PROJECT_NAME}}-docs
+            project: {{PROJECT_NAME}}
+          annotations:
+            cert-manager.io/cluster-issuer: letsencrypt-prod
+        spec:
+          ingressClassName: traefik
+          tls:
+          - hosts:
+            - docs.{{DOMAIN}}
+            secretName: docs-{{DOMAIN}}-tls
+          rules:
+          - host: docs.{{DOMAIN}}
+            http:
+              paths:
+              - path: /
+                pathType: Prefix
+                backend:
+                  service:
+                    name: {{PROJECT_NAME}}-docs
+                    port:
+                      number: 80
+        EOF
+      - kubectl rollout restart deployment/{{PROJECT_NAME}}-docs -n projects
+      - kubectl rollout status deployment/{{PROJECT_NAME}}-docs -n projects --timeout=120s
+    when:
+      branch: main
+      event: push
+
   verify:
     image: bitnami/kubectl:latest
     commands:
       - echo "Pipeline complete for {{PROJECT_NAME}}"
-      - kubectl get deployments -n projects -l app={{PROJECT_NAME}} --no-headers || true
+      - kubectl get deployments -n projects -l project={{PROJECT_NAME}} --no-headers || true
     when:
       branch: main
       event: push