feat: AKS starterkit reusable modules

.github/copilot-instructions.md

@@ -36,6 +36,30 @@ modules/<cloud-provider>/<service-name>/
 └── meshstack_integration.tf   # Example wiring into a meshStack instance
 ```
 
+### `meshstack_integration.tf` as a single-file module
+
+Each `meshstack_integration.tf` is a **self-contained single-file Terraform module**. It must
+include `variable`, `output`, `terraform {}`, `locals`, and `resource` blocks all in one file —
+do **not** create separate `variables.tf`, `outputs.tf`, or `versions.tf` alongside it.
+This keeps the integration compact and easy to call as a sub-module from composition modules.
+
+### Building block logos / symbols
+
+Use `provider::meshstack::load_image_file()` (requires meshstack provider `>= 0.19.3`) to set
+the `symbol` attribute on `meshstack_building_block_definition` resources. Reference the
+`logo.png` already present in the `buildingblock/` directory:
+
+```hcl
+resource "meshstack_building_block_definition" "example" {
+  spec = {
+    symbol = provider::meshstack::load_image_file("${path.module}/buildingblock/logo.png")
+    # ...
+  }
+}
+```
+
+This keeps logo management inside the hub — callers don't need to provide their own assets.
+
 ---
 
 ## `meshstack_integration.tf` Conventions
@@ -103,6 +127,32 @@ module "backplane" {
 }
 ```
 
+### Cross-module references (composition modules)
+
+When a `meshstack_integration.tf` needs to call **another hub module** (e.g. the AKS starterkit
+calling `modules/github/repository`), use a **git URL** with a **hardcoded ref** — never a
+relative `../../` path. Relative upward traversal breaks when the module is sourced via a git URL
+from LCF/ICF/meshkube, because Terraform only downloads the specified subdirectory.
+
+```hcl
+# ✅ Cross-module reference — git URL with hardcoded ref
+module "github_repo_bbd" {
+  source = "github.com/meshcloud/meshstack-hub//modules/github/repository?ref=main"
+  # ...
+}
+```
+
+**Rules:**
+- `./backplane` → relative path (same module subtree, always works)
+- `../../other/module` → **git URL** with hardcoded `?ref=<tag-or-branch>` (cross-module)
+- `var.hub.git_ref` → used only in `implementation.terraform.ref_name` of BBD resources, NOT
+  in `source` arguments (Terraform does not support variable interpolation in `source`)
+
+**Ref management:** The hardcoded refs in git URL `source` lines default to `"main"` during
+development. A Go CI tool (planned) will walk the hub module dependency tree bottom-up and
+update these refs to specific tags on release. Leaf modules (no cross-module deps) are updated
+first, then composition modules.
+
 ### ❌ Avoid these patterns
 
 ```hcl
@@ -115,11 +165,16 @@ locals {
 # ❌ provider blocks inside mesh_integration.tf — the Hub UI renders these
 provider "meshstack" { ... }
 
-# ❌ absolute GitHub source URL in module block — use relative path instead
+# ❌ absolute GitHub source URL for backplane — use relative path instead
 module "backplane" {
   source = "github.com/meshcloud/meshstack-hub//modules/aws/s3_bucket/backplane?ref=main"
 }
 
+# ❌ relative path for cross-module refs — breaks when sourced via git URL
+module "github_repo_bbd" {
+  source = "../../github/repository"
+}
+
 # ❌ standalone meshstack_hub_git_ref variable — use variable "hub" { type = object({git_ref=string}) } instead
 variable "meshstack_hub_git_ref" { ... }
 

.github/workflows/update-module-refs.yml

@@ -0,0 +1,51 @@
+name: update-module-refs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'modules/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'modules/**'
+
+permissions:
+  contents: write
+
+jobs:
+  update-module-refs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history needed for git log to resolve commit SHAs
+          fetch-depth: 0
+          # On push to main, use a token that can push commits
+          token: ${{ github.event_name == 'push' && secrets.GITHUB_TOKEN || github.token }}
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: tools/update-module-refs/go.mod
+          cache-dependency-path: tools/update-module-refs/go.sum
+
+      - name: Build
+        working-directory: tools/update-module-refs
+        run: go build -o update-module-refs .
+
+      - name: Update module refs (dry-run)
+        if: github.event_name == 'pull_request'
+        working-directory: modules
+        run: ../tools/update-module-refs/update-module-refs -dry-run
+
+      - name: Update module refs
+        if: github.event_name == 'push'
+        working-directory: modules
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          ../tools/update-module-refs/update-module-refs
+
+      - name: Push ref updates
+        if: github.event_name == 'push'
+        run: git push

.gitignore

@@ -26,3 +26,7 @@ website/public/assets/building-block-logos/
 website/public/assets/logos/
 website/public/assets/*.json
 .worktrees/
+
+# Go
+.nix-go/
+tools/update-module-refs/update-module-refs