diff --git a/.claude/commands/composite.md b/.claude/commands/composite.md
new file mode 100644
index 0000000..ef8aa4b
--- /dev/null
+++ b/.claude/commands/composite.md
@@ -0,0 +1,159 @@
+# Composite Actions — Rules & Conventions
+
+Use these rules whenever creating or editing a composite action in `src/`.
+
+## Before you create anything
+
+**Step 1 — Check if it already exists in this repo**
+
+Search `src/` before starting. If a composite already covers the same capability:
+
+- Summarize what the existing composite does and which inputs it exposes
+- Identify the gap between the existing behavior and the new requirement
+- Propose an **adaptation plan** (add an input, extend steps, split into two) instead of creating a new file
+
+**Step 2 — Check the GitHub Actions Marketplace first**
+
+Before writing custom steps from scratch, search the [Marketplace](https://github.com/marketplace?type=actions) for an existing action that covers the need:
+
+- Prefer a well-maintained marketplace action over custom shell scripting for non-trivial logic
+- Wrap it in a composite if it needs input normalization or additional steps
+- Pin to a specific tag or SHA — never `@main` or `@master`
+- Document in the composite `README.md` why that action was chosen
+
+Only implement from scratch when no suitable action exists or when existing ones don't meet security or customization requirements.
+
+---
+
+## Directory layout
+
+Composite actions are grouped by capability inside `src/`:
+
+```
+src/
+├── setup/       ← language runtime setup (Go, Node, etc.)
+├── build/       ← build and artifact generation
+├── test/        ← test execution and coverage
+├── deploy/      ← deployment and release steps
+└── config/      ← repository configuration management
+```
+
+Each composite lives in `src/<capability>/<name>/` with exactly two files:
+
+```
+src/config/labels-sync/
+├── action.yml   ← required
+└── README.md    ← required
+```
+
+## action.yml structure
+
+```yaml
+name: Human-readable name
+description: One-line description.
+
+inputs:
+  github-token:
+    description: GitHub token with required permissions
+    required: true
+  some-option:
+    description: What this option controls
+    required: false
+    default: "default-value"
+
+runs:
+  using: composite
+  steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: Do the work
+      uses: some-owner/some-action@v1
+      with:
+        token: ${{ inputs.github-token }}
+        option: ${{ inputs.some-option }}
+```
+
+## Design rules
+
+- **5–15 steps maximum** — split if larger
+- **Single responsibility** — one composite, one capability
+- Must not define jobs or call other workflows
+- Must not contain pipeline control logic
+- Never combine multiple language runtimes in the same composite
+
+## Language-specific vs cross-language
+
+Specialize by runtime when toolchains differ:
+
+```
+src/setup/setup-go/     ← Go toolchain, GOPATH, module cache
+src/setup/setup-node/   ← Node.js, npm/yarn/pnpm, cache
+src/build/build-go/     ← go build, cross-compilation
+src/test/test-go/       ← go test, coverage upload
+```
+
+Cross-language composites stay language-agnostic:
+
+```
+src/build/docker-build/   ← any image
+src/deploy/helm-deploy/   ← any chart
+src/config/labels-sync/   ← any repo
+```
+
+## README.md requirements
+
+1. Logo header — HTML table layout (logo left, `h1` title right)
+2. Inputs table — `Input | Description | Required | Default`
+3. Usage as composite step (full YAML)
+4. Usage as reusable workflow (full YAML with `secrets: inherit`)
+5. Required permissions block
+
+### Usage example ref policy
+
+Examples in README.md must never use `@main`. Use the correct ref for each context:
+
+```yaml
+# ✅ Testing — point to develop or feature branch
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/labels-sync.yml@develop
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/labels-sync.yml@feat/my-branch
+
+# ✅ Production — always a pinned stable version
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/labels-sync.yml@v1.2.3
+
+# ❌ Never in examples
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/labels-sync.yml@main
+```
+
+## After creating a new composite
+
+- Update root `README.md` if the composite is meant to be used by external callers
+
+### Labels checklist
+
+Check `.github/labels.yml` for a label matching the composite's capability group. If it doesn't exist, add it:
+
+```yaml
+- name: <capability>           # e.g. "infrastructure", "notifications"
+  color: "0075ca"              # pick a distinct hex color
+  description: Changes to <capability> composite actions
+```
+
+After adding, run the `Sync Labels` workflow (`workflow_dispatch`) to create it in the repository.
+
+### Dependabot checklist
+
+For every third-party action used in the new composite (`uses: owner/action@vX`), check `.github/dependabot.yml`:
+
+- If `owner/*` already matches an existing group → no change needed
+- If not → add to the most appropriate group, or create a new one:
+
+```yaml
+new-tool-category:
+  patterns:
+    - "owner/new-action"
+  update-types:
+    - "minor"
+    - "patch"
+```
+
+Never add `LerianStudio/*` actions to dependabot — pinned to `@main` intentionally.
diff --git a/.claude/commands/gha.md b/.claude/commands/gha.md
new file mode 100644
index 0000000..90f1223
--- /dev/null
+++ b/.claude/commands/gha.md
@@ -0,0 +1,492 @@
+# GitHub Actions — Full Rules & Conventions
+
+Complete reference for this repository. Use `/workflow` or `/composite` for focused context.
+For refactoring existing files, use `/refactor`.
+
+---
+
+## Modifying an existing workflow or composite?
+
+Apply the refactoring protocol below **before making any change** to an existing file.
+
+Never apply changes directly. Always produce a plan, wait for explicit user confirmation, then apply one step at a time.
+
+### Protocol summary
+
+**Step 1 — Analyze the current state**
+
+Read the target file completely and produce a structured summary:
+
+```
+Current state of <file>:
+- Purpose        : what the workflow/composite does
+- Inputs         : list all current inputs and their defaults
+- Outputs        : list all current outputs
+- Jobs/Steps     : list jobs (workflow) or steps (composite)
+- Callers        : note any known repos or workflows that reference this
+- dry_run        : present / absent
+```
+
+**Step 2 — Produce the refactoring plan**
+
+Present the plan as a numbered step list. Each step must include:
+
+```
+Step N — [Label]
+  Change : <what will be modified>
+  Reason : <why>
+  Impact : additive | behavioral | breaking
+  Safe   : yes | no — <explanation>
+```
+
+**Step 3 — Flag attention points**
+
+- Input/output renamed, removed, or type-changed → **breaking**
+- New default that differs from old implicit behavior → **breaking**
+- Step order change affecting downstream outputs → **attention**
+- New required secret → **breaking for callers**
+- No `dry_run` and change applies state → propose adding `dry_run: false` input
+
+**Step 4 — Show breaking changes with migration guide**
+
+```
+⚠️ Breaking change in Step N
+
+Before:
+  with:
+    old_input: value
+
+After:
+  with:
+    new_input: value
+
+Migration: replace `old_input` with `new_input`.
+```
+
+**Step 5 — Propose test examples**
+
+For every behavioral change, provide a concrete test scenario using `dry_run: true` on `@develop`.
+
+**Step 6 — Confirm before applying**
+
+Ask the user to confirm each step explicitly. Do not apply any change until confirmed:
+
+```
+Ready to apply?
+
+  [ ] Step 1 — <label>
+  [ ] Step 2 — <label>
+
+Reply with step numbers, "all", or "cancel".
+```
+
+**Step 7 — Apply one step at a time**
+
+Show a diff summary after each step. Wait for confirmation before proceeding to independent steps.
+
+**Step 8 — Update documentation**
+
+Update `docs/<workflow-name>.md` or composite `README.md` to reflect all confirmed changes.
+
+### What must never change without explicit confirmation
+
+- Default values of existing inputs
+- Names of existing inputs or outputs
+- Behavior when optional inputs are omitted
+- Step ordering when downstream steps depend on earlier outputs
+- Required secrets — adding one is always a breaking change for callers
+
+---
+
+## Before you create anything
+
+These checks apply to **both reusable workflows and composite actions**.
+
+**Step 1 — Check if it already exists in this repo**
+
+- Workflows: search `.github/workflows/`
+- Composites: search `src/`
+
+If something already covers the same capability:
+
+- Summarize what the existing implementation does (jobs/steps, inputs, secrets)
+- Identify the gap between the existing behavior and the new requirement
+- Propose an **adaptation plan** (add an input, add a job, extend steps) instead of creating a new file
+
+**Step 2 — Check the GitHub Actions Marketplace first**
+
+Before writing custom steps from scratch, search the [Marketplace](https://github.com/marketplace?type=actions):
+
+- Prefer a well-maintained marketplace action over custom shell scripting for non-trivial logic
+- If the action needs wrapping, create a composite in `src/` — don't inline complex shell directly in a workflow
+- Pin to a specific tag or SHA — never `@main` or `@master`
+- Document in the README or `docs/` why that action was chosen
+
+Only implement from scratch when no suitable action exists or when existing ones don't meet security or customization requirements.
+
+---
+
+# Reusable Workflows — Rules & Conventions
+
+Use these rules whenever creating or editing a reusable workflow in `.github/workflows/`.
+
+## Architecture model
+
+```
+Caller repository workflow         ← minimal entrypoint: triggers + secrets only
+         ↓
+Reusable workflow                  ← orchestrates jobs, runners, secrets
+(.github/workflows/*.yml)
+         ↓
+Composite action                   ← encapsulates reusable steps
+(src/<capability>/<name>/action.yml)
+```
+
+**Rules:**
+- Caller workflows must contain only triggers and job references — no business logic
+- Reusable workflows must orchestrate jobs and route secrets
+- Composite actions must encapsulate steps for a single responsibility
+
+**Example: Go CI pipeline**
+
+```
+caller: .github/workflows/ci.yml  (on: push)
+    ↓
+reusable: go-ci.yml
+    ↓ job: ci
+        → src/setup/setup-go      (install Go, restore cache)
+        → src/build/build-go      (compile, vet)
+        → src/test/test-go        (run tests, upload coverage)
+        → src/build/docker-build  (build and push image)
+```
+
+## When to use each
+
+| Need | Use |
+|---|---|
+| Standardize a full CI/CD pipeline across repos | Reusable workflow |
+| Reuse a group of steps inside a job | Composite action |
+| Share setup / build / lint / test logic | Composite action |
+| Manage multiple jobs or runners | Reusable workflow only |
+| Route secrets to jobs | Reusable workflow only |
+
+## self-* workflows (entrypoints for this repo)
+
+Files prefixed with `self-` are **thin entrypoints** for this repository's own automation — not reusable workflows.
+
+- **Must NOT have `workflow_call`** — not offered to external callers
+- **`dry_run` is not required** — omit it unless the workflow performs destructive operations
+- **When `dry_run` is present**, it must be: `type: boolean`, `required: false`, `default: true` for destructive ops (delete, purge) or `default: false` for non-destructive ops (sync, notify)
+- Must call the corresponding reusable workflow via local path (`./.github/workflows/<name>.yml`)
+- Triggers are repo-specific: `push`, `schedule`, `pull_request`, `workflow_dispatch`
+- Must not contain business logic
+
+```yaml
+# ✅ Correct self-* structure
+name: Self — Labels Sync
+on:
+  push:
+    branches: [main]
+    paths: [".github/labels.yml"]
+  workflow_dispatch:
+jobs:
+  sync:
+    uses: ./.github/workflows/labels-sync.yml
+    secrets: inherit
+```
+
+---
+
+## Workflow structure
+
+Every reusable workflow must:
+- support `workflow_call` (for external callers)
+- support `workflow_dispatch` (for manual testing)
+- expose explicit `inputs` — never rely on implicit context
+- **always include a `dry_run` input** (`type: boolean`, `default: false`)
+
+```yaml
+on:
+  workflow_call:
+    inputs:
+      environment:
+        required: true
+        type: string
+      dry_run:
+        description: Preview changes without applying them
+        required: false
+        type: boolean
+        default: false
+    secrets:
+      DEPLOY_TOKEN:
+        required: true
+  workflow_dispatch:
+    inputs:
+      environment:
+        required: true
+        type: string
+      dry_run:
+        description: Preview changes without applying them
+        type: boolean
+        default: false
+```
+
+## dry_run pattern
+
+| Mode | Goal | Log style |
+|---|---|---|
+| `dry_run: true` | Validate before applying | Verbose — print everything |
+| `dry_run: false` | Apply cleanly | Silent — only errors and summaries |
+
+```yaml
+# dry_run: true — verbose, annotated, tool debug flags on
+- name: Dry run summary
+  if: ${{ inputs.dry_run }}
+  run: |
+    echo "::notice::DRY RUN — no changes will be applied"
+    echo "  environment : ${{ inputs.environment }}"
+    echo "  target      : ${{ steps.resolve.outputs.target }}"
+    echo "  version     : ${{ steps.resolve.outputs.version }}"
+
+- name: Preview (dry run)
+  if: ${{ inputs.dry_run }}
+  run: helm upgrade --install --dry-run --debug ...
+
+# dry_run: false — clean, no extra echo, output only on failure
+- name: Apply
+  if: ${{ !inputs.dry_run }}
+  run: helm upgrade --install ...
+```
+
+**Dry run (`true`):** use `::notice::` annotations, print all resolved values, enable tool-native flags (`--dry-run --debug`, `--check`, `--plan`, `--diff`), never skip silently.
+
+**Real run (`false`):** no extra `echo`, no debug flags, let failures surface via exit codes, one `::notice::` summary on success at most.
+
+## Local path rule (critical)
+
+```yaml
+uses: ./src/setup/setup-go      # ✅ composite version matches workflow version
+uses: LerianStudio/...@main     # ❌ breaks versioning for callers on older tags
+```
+
+## Secrets management
+
+```yaml
+# Caller
+jobs:
+  deploy:
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/deploy.yml@v1.2.3
+    secrets:
+      DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }}
+
+# Reusable workflow — declare but never set a value
+on:
+  workflow_call:
+    secrets:
+      DOCKER_TOKEN:
+        required: true
+```
+
+## Naming conventions
+
+```
+✅  go-ci.yml   build-node.yml   labels-sync.yml   helm-deploy.yml
+❌  workflow.yml   pipeline.yml   ci.yml   action.yml
+```
+
+Always use `.yml` extension — never `.yaml`:
+
+```
+✅  go-ci.yml   action.yml   labels.yml   dependabot.yml
+❌  go-ci.yaml  action.yaml  labels.yaml
+```
+
+## Documentation naming
+
+The doc file in `docs/` must have the **exact same name** as the workflow file, with `.md` extension, and must start with the Lerian branding header:
+
+```markdown
+<table border="0" cellspacing="0" cellpadding="0">
+  <tr>
+    <td><img src="https://github.com/LerianStudio.png" width="72" alt="Lerian" /></td>
+    <td><h1>workflow-name</h1></td>
+  </tr>
+</table>
+```
+
+```
+.github/workflows/go-ci.yml        → docs/go-ci.md          ✅
+.github/workflows/go-ci.yml        → docs/go-ci-workflow.md  ❌
+.github/workflows/labels-sync.yml  → docs/labels-sync.md    ✅
+```
+
+Every new reusable workflow must have a corresponding `docs/<workflow-name>.md`.
+
+### Usage example ref policy
+
+Examples in `docs/` and `README.md` must never use `@main`. Use the correct ref for each context:
+
+```yaml
+# ✅ Testing — point to develop or feature branch
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@develop
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@feat/my-branch
+
+# ✅ Production — always a pinned stable version
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@v1.2.3
+
+# ❌ Never in examples
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@main
+```
+
+## Anti-patterns
+
+```yaml
+# ❌ Monolithic composite — does setup + build + test + deploy in one action
+src/go-ci/action.yml
+
+# ❌ Multi-language composite — couples runtimes
+src/build/build-all/action.yml
+
+# ❌ Orchestration inside composite
+runs:
+  using: composite
+  jobs:          # invalid — composites have steps, not jobs
+    build: ...
+
+# ❌ External ref for composite inside a reusable workflow
+uses: LerianStudio/github-actions-shared-workflows/src/setup-go@main
+
+# ❌ Mutable ref on third-party actions
+uses: some-action/tool@main
+```
+
+## Security rules
+
+- Pin all third-party actions to a specific tag or SHA — Dependabot keeps them updated
+- Never use `@main` or `@master` for third-party actions
+- Never interpolate untrusted user input directly into `run:` commands
+- Never print secrets via `echo`, env dumps, or step summaries
+- Complex conditional logic belongs in the workflow, not in composites
+
+---
+
+# Composite Actions — Rules & Conventions
+
+Use these rules whenever creating or editing a composite action in `src/`.
+
+## Directory layout
+
+Composite actions are grouped by capability inside `src/`:
+
+```
+src/
+├── setup/       ← language runtime setup (Go, Node, etc.)
+├── build/       ← build and artifact generation
+├── test/        ← test execution and coverage
+├── deploy/      ← deployment and release steps
+└── config/      ← repository configuration management
+```
+
+Each composite lives in `src/<capability>/<name>/` with exactly two files:
+
+```
+src/config/labels-sync/
+├── action.yml   ← required
+└── README.md    ← required
+```
+
+## action.yml structure
+
+```yaml
+name: Human-readable name
+description: One-line description.
+
+inputs:
+  github-token:
+    description: GitHub token with required permissions
+    required: true
+  some-option:
+    description: What this option controls
+    required: false
+    default: "default-value"
+
+runs:
+  using: composite
+  steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: Do the work
+      uses: some-owner/some-action@v1
+      with:
+        token: ${{ inputs.github-token }}
+        option: ${{ inputs.some-option }}
+```
+
+## Design rules
+
+- **5–15 steps maximum** — split if larger
+- **Single responsibility** — one composite, one capability
+- Must not define jobs or call other workflows
+- Must not contain pipeline control logic
+- Never combine multiple language runtimes in the same composite
+
+## Language-specific vs cross-language
+
+Specialize by runtime when toolchains differ:
+
+```
+src/setup/setup-go/     ← Go toolchain, GOPATH, module cache
+src/setup/setup-node/   ← Node.js, npm/yarn/pnpm, cache
+src/build/build-go/     ← go build, cross-compilation
+src/test/test-go/       ← go test, coverage upload
+```
+
+Cross-language composites stay language-agnostic:
+
+```
+src/build/docker-build/   ← any image
+src/deploy/helm-deploy/   ← any chart
+src/config/labels-sync/   ← any repo
+```
+
+## README.md requirements
+
+1. Logo header — HTML table layout (logo left, `h1` title right)
+2. Inputs table — `Input | Description | Required | Default`
+3. Usage as composite step (full YAML)
+4. Usage as reusable workflow (full YAML with `secrets: inherit`)
+5. Required permissions block
+
+## After creating a new composite
+
+- Update root `README.md` if the composite is meant to be used by external callers
+
+### Labels checklist
+
+Check `.github/labels.yml` for a label matching the composite's capability group. If it doesn't exist, add it:
+
+```yaml
+- name: <capability>           # e.g. "infrastructure", "notifications"
+  color: "0075ca"              # pick a distinct hex color
+  description: Changes to <capability> composite actions
+```
+
+After adding, run the `Sync Labels` workflow (`workflow_dispatch`) to create it in the repository.
+
+### Dependabot checklist
+
+For every third-party action used in the new composite (`uses: owner/action@vX`), check `.github/dependabot.yml`:
+
+- If `owner/*` already matches an existing group → no change needed
+- If not → add to the most appropriate group, or create a new one:
+
+```yaml
+new-tool-category:
+  patterns:
+    - "owner/new-action"
+  update-types:
+    - "minor"
+    - "patch"
+```
+
+Never add `LerianStudio/*` actions to dependabot — pinned to `@main` intentionally.
diff --git a/.claude/commands/refactor.md b/.claude/commands/refactor.md
new file mode 100644
index 0000000..efbcf67
--- /dev/null
+++ b/.claude/commands/refactor.md
@@ -0,0 +1,173 @@
+# Refactoring Protocol
+
+Apply this protocol **before making any refactoring or additive change** to an existing reusable workflow or composite action.
+
+Never apply changes directly. Always produce a plan first, wait for explicit user confirmation, then apply one step at a time.
+
+---
+
+## Step 1 — Analyze the current state
+
+Before proposing any change, read the target file(s) completely and produce a structured summary:
+
+```
+Current state of <file>:
+- Purpose        : what the workflow/composite does
+- Inputs         : list all current inputs and their defaults
+- Outputs        : list all current outputs
+- Jobs/Steps     : list jobs (workflow) or steps (composite)
+- Callers        : note any known repos or workflows that reference this
+- dry_run        : present / absent
+```
+
+---
+
+## Step 2 — Produce the refactoring plan
+
+Present the plan as a numbered step list. Each step must describe:
+
+- **What changes** (file, section, input, job, step)
+- **Why** (the reason for the change)
+- **Impact** (additive, behavioral, breaking)
+- **Backward compatible?** (yes / no / conditional)
+
+Format:
+
+```
+Refactoring plan — <workflow or composite name>
+
+Step 1 — [Label]
+  Change : <what will be modified>
+  Reason : <why>
+  Impact : additive | behavioral | breaking
+  Safe   : yes | no — <explanation>
+
+Step 2 — [Label]
+  ...
+```
+
+---
+
+## Step 3 — Flag attention points
+
+After the plan, list explicitly:
+
+### Inputs and outputs
+- Any input being renamed, removed, or changing type → **breaking**
+- Any input with a new default that differs from the old implicit behavior → **breaking**
+- Any output being removed or renamed → **breaking**
+
+### Behavior
+- Any step order change that could affect downstream steps → **attention**
+- Any conditional logic that changes when a step runs → **attention**
+- Any new required secret → **breaking for callers**
+
+### dry_run
+- If the workflow/composite does not have a `dry_run` input and the change involves applying state (deploy, create, update, delete), propose adding it as part of the plan:
+
+```yaml
+dry_run:
+  description: Preview changes without applying them
+  required: false
+  type: boolean
+  default: false
+```
+
+---
+
+## Step 4 — Show breaking changes explicitly
+
+If any step is breaking, present it separately with a migration guide:
+
+```
+⚠️ Breaking change in Step N
+
+Before (callers must update):
+  with:
+    old_input: value
+
+After:
+  with:
+    new_input: value
+
+Migration: replace `old_input` with `new_input`. Default behavior is preserved
+when `new_input` is omitted.
+```
+
+---
+
+## Step 5 — Propose test examples
+
+For every behavioral change, provide a concrete test scenario:
+
+```yaml
+# Test scenario: <what is being tested>
+# Expected result: <what should happen>
+
+jobs:
+  test:
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/<workflow>.yml@develop
+    with:
+      <input>: <test value>
+      dry_run: true   # validate before applying
+```
+
+If the change affects a composite action, show how to invoke it via a calling workflow:
+
+```yaml
+- name: Test <composite>
+  uses: ./src/<capability>/<name>
+  with:
+    <input>: <test value>
+```
+
+---
+
+## Step 6 — Confirm before applying
+
+After presenting the full plan, attention points, breaking changes, and test examples, ask:
+
+```
+Ready to apply?
+
+Please confirm each step:
+  [ ] Step 1 — <label>
+  [ ] Step 2 — <label>
+  ...
+
+Reply with the step numbers you want applied, or "all" to apply everything.
+Reply with "cancel" to abort.
+```
+
+**Do not apply any change until the user explicitly confirms.**
+
+---
+
+## Step 7 — Apply one step at a time
+
+Apply only the confirmed steps. After each one:
+
+- Show a diff summary of what changed
+- Note if the next step depends on this one
+- Wait for confirmation before proceeding to the next step if they are independent
+
+---
+
+## Step 8 — Update documentation
+
+After all confirmed steps are applied, update:
+
+- `docs/<workflow-name>.md` — reflect any changed inputs, outputs, or behavior
+- Composite `README.md` — update the inputs table and usage examples
+- `CHANGELOG.md` — do **not** edit manually; semantic-release generates it from commits
+- If a breaking change was applied, note the migration path in the doc
+
+---
+
+## What must never change without explicit confirmation
+
+- Default values of existing inputs
+- Names of existing inputs or outputs
+- Behavior when optional inputs are omitted
+- Step ordering when downstream steps depend on earlier outputs
+- Required secrets — adding one is always a breaking change for callers
diff --git a/.claude/commands/workflow.md b/.claude/commands/workflow.md
new file mode 100644
index 0000000..6df0555
--- /dev/null
+++ b/.claude/commands/workflow.md
@@ -0,0 +1,266 @@
+# Reusable Workflows — Rules & Conventions
+
+Use these rules whenever creating or editing a reusable workflow in `.github/workflows/`.
+
+## Before you create anything
+
+**Step 1 — Check if it already exists in this repo**
+
+Search `.github/workflows/` before starting. If a workflow already covers the same pipeline:
+
+- Summarize what the existing workflow does, its jobs, inputs, and secrets
+- Identify the gap between the existing behavior and the new requirement
+- Propose an **adaptation plan** (add a job, add an input, expose a new secret) instead of creating a new workflow file
+
+**Step 2 — Check the GitHub Actions Marketplace first**
+
+Before implementing custom steps inside a workflow, search the [Marketplace](https://github.com/marketplace?type=actions) for actions that already solve the problem:
+
+- Prefer a well-maintained action over custom shell scripting for non-trivial logic
+- If the action needs wrapping (normalization, extra steps), create a composite in `src/` and call it from the workflow — don't inline complex shell in the workflow itself
+- Pin to a specific tag or SHA — never `@main` or `@master`
+- Document in `docs/<workflow-name>.md` why that action was chosen
+
+Only implement from scratch when no suitable action exists or when existing ones don't meet security or customization requirements.
+
+---
+
+## Architecture model
+
+```
+Caller repository workflow         ← minimal entrypoint: triggers + secrets only
+         ↓
+Reusable workflow                  ← orchestrates jobs, runners, secrets
+(.github/workflows/*.yml)
+         ↓
+Composite action                   ← encapsulates reusable steps
+(src/<capability>/<name>/action.yml)
+```
+
+**Rules:**
+- Caller workflows must contain only triggers and job references — no business logic
+- Reusable workflows must orchestrate jobs and route secrets
+- Composite actions must encapsulate steps for a single responsibility
+
+**Example: Go CI pipeline**
+
+```
+caller: .github/workflows/ci.yml  (on: push)
+    ↓
+reusable: go-ci.yml
+    ↓ job: ci
+        → src/setup/setup-go      (install Go, restore cache)
+        → src/build/build-go      (compile, vet)
+        → src/test/test-go        (run tests, upload coverage)
+        → src/build/docker-build  (build and push image)
+```
+
+## When to use each
+
+| Need | Use |
+|---|---|
+| Standardize a full CI/CD pipeline across repos | Reusable workflow |
+| Reuse a group of steps inside a job | Composite action |
+| Share setup / build / lint / test logic | Composite action |
+| Manage multiple jobs or runners | Reusable workflow only |
+| Route secrets to jobs | Reusable workflow only |
+
+## self-* workflows (entrypoints for this repo)
+
+Files prefixed with `self-` are **thin entrypoints** for this repository's own automation — not reusable workflows.
+
+- **Must NOT have `workflow_call`** — not offered to external callers
+- **`dry_run` is not required** — omit it unless the workflow performs destructive operations
+- **When `dry_run` is present**, it must be: `type: boolean`, `required: false`, `default: true` for destructive ops (delete, purge) or `default: false` for non-destructive ops (sync, notify)
+- Must call the corresponding reusable workflow via local path (`./.github/workflows/<name>.yml`)
+- Triggers are repo-specific: `push`, `schedule`, `pull_request`, `workflow_dispatch`
+- Must not contain business logic
+
+```yaml
+# ✅ Correct self-* structure
+name: Self — Labels Sync
+on:
+  push:
+    branches: [main]
+    paths: [".github/labels.yml"]
+  workflow_dispatch:
+jobs:
+  sync:
+    uses: ./.github/workflows/labels-sync.yml
+    secrets: inherit
+```
+
+---
+
+## Workflow structure
+
+Every reusable workflow must:
+- support `workflow_call` (for external callers)
+- support `workflow_dispatch` (for manual testing)
+- expose explicit `inputs` — never rely on implicit context
+- **always include a `dry_run` input** (`type: boolean`, `default: false`)
+
+```yaml
+on:
+  workflow_call:
+    inputs:
+      environment:
+        required: true
+        type: string
+      dry_run:
+        description: Preview changes without applying them
+        required: false
+        type: boolean
+        default: false
+    secrets:
+      DEPLOY_TOKEN:
+        required: true
+  workflow_dispatch:
+    inputs:
+      environment:
+        required: true
+        type: string
+      dry_run:
+        description: Preview changes without applying them
+        type: boolean
+        default: false
+```
+
+## dry_run pattern
+
+The two modes have opposite goals — design them accordingly:
+
+| Mode | Goal | Log style |
+|---|---|---|
+| `dry_run: true` | Validate before applying | Verbose — print everything |
+| `dry_run: false` | Apply cleanly | Silent — only errors and summaries |
+
+```yaml
+# dry_run: true — verbose, annotated, tool debug flags on
+- name: Dry run summary
+  if: ${{ inputs.dry_run }}
+  run: |
+    echo "::notice::DRY RUN — no changes will be applied"
+    echo "  environment : ${{ inputs.environment }}"
+    echo "  target      : ${{ steps.resolve.outputs.target }}"
+    echo "  version     : ${{ steps.resolve.outputs.version }}"
+
+- name: Preview (dry run)
+  if: ${{ inputs.dry_run }}
+  run: helm upgrade --install --dry-run --debug ...
+
+# dry_run: false — clean, no extra echo, output only on failure
+- name: Apply
+  if: ${{ !inputs.dry_run }}
+  run: helm upgrade --install ...
+```
+
+**Dry run (`true`):** use `::notice::` annotations, print all resolved values, enable tool-native flags (`--dry-run --debug`, `--check`, `--plan`, `--diff`), never skip silently.
+
+**Real run (`false`):** no extra `echo`, no debug flags, let failures surface via exit codes, one `::notice::` summary on success at most.
+
+## Local path rule (critical)
+
+```yaml
+uses: ./src/setup/setup-go      # ✅ composite version matches workflow version
+uses: LerianStudio/...@main     # ❌ breaks versioning for callers on older tags
+```
+
+## Secrets management
+
+```yaml
+# Caller
+jobs:
+  deploy:
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/deploy.yml@v1.2.3
+    secrets:
+      DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }}
+
+# Reusable workflow — declare but never set a value
+on:
+  workflow_call:
+    secrets:
+      DOCKER_TOKEN:
+        required: true
+```
+
+## Naming conventions
+
+```
+✅  go-ci.yml   build-node.yml   labels-sync.yml   helm-deploy.yml
+❌  workflow.yml   pipeline.yml   ci.yml   action.yml
+```
+
+Always use `.yml` extension — never `.yaml`:
+
+```
+✅  go-ci.yml   action.yml   labels.yml   dependabot.yml
+❌  go-ci.yaml  action.yaml  labels.yaml
+```
+
+## Documentation naming
+
+The doc file in `docs/` must have the **exact same name** as the workflow file, with `.md` extension, and must start with the Lerian branding header:
+
+```markdown
+<table border="0" cellspacing="0" cellpadding="0">
+  <tr>
+    <td><img src="https://github.com/LerianStudio.png" width="72" alt="Lerian" /></td>
+    <td><h1>workflow-name</h1></td>
+  </tr>
+</table>
+```
+
+```
+.github/workflows/go-ci.yml        → docs/go-ci.md          ✅
+.github/workflows/go-ci.yml        → docs/go-ci-workflow.md  ❌
+.github/workflows/labels-sync.yml  → docs/labels-sync.md    ✅
+```
+
+Every new reusable workflow must have a corresponding `docs/<workflow-name>.md`.
+
+### Usage example ref policy
+
+Examples in `docs/` must never use `@main`. Use the correct ref for each context:
+
+```yaml
+# ✅ Testing — point to develop or feature branch
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@develop
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@feat/my-branch
+
+# ✅ Production — always a pinned stable version
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@v1.2.3
+
+# ❌ Never in examples
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@main
+```
+
+## Anti-patterns
+
+```yaml
+# ❌ Monolithic composite — does setup + build + test + deploy in one action
+src/go-ci/action.yml
+
+# ❌ Multi-language composite — couples runtimes
+src/build/build-all/action.yml
+
+# ❌ Orchestration inside composite
+runs:
+  using: composite
+  jobs:          # invalid — composites have steps, not jobs
+    build: ...
+
+# ❌ External ref for composite inside a reusable workflow
+uses: LerianStudio/github-actions-shared-workflows/src/setup-go@main
+
+# ❌ Mutable ref on third-party actions
+uses: some-action/tool@main
+```
+
+## Security rules
+
+- Pin all third-party actions to a specific tag or SHA — Dependabot keeps them updated
+- Never use `@main` or `@master` for third-party actions
+- Never interpolate untrusted user input directly into `run:` commands
+- Never print secrets via `echo`, env dumps, or step summaries
+- Complex conditional logic belongs in the workflow, not in composites
diff --git a/.coderabbit.yml b/.coderabbit.yml
new file mode 100644
index 0000000..00dbadd
--- /dev/null
+++ b/.coderabbit.yml
@@ -0,0 +1,86 @@
+language: "en-US"
+
+tone_instructions: >
+  Be direct and technical. Focus on correctness, security, and maintainability.
+  Flag breaking changes to callers explicitly. Skip praise for routine changes.
+
+early_access: false
+
+reviews:
+  profile: "assertive"
+
+  high_level_summary: true
+  high_level_summary_in_walkthrough: false
+
+  review_status: true
+  review_details: false
+  collapse_walkthrough: false
+  changed_files_summary: true
+  sequence_diagrams: false
+
+  poem: false
+
+  suggested_labels: true
+  auto_apply_labels: false
+
+  suggested_reviewers: true
+  auto_assign_reviewers: false
+
+  request_changes_workflow: true
+
+  abort_on_close: true
+
+  path_filters:
+    - "!CHANGELOG.md"
+    - "!.releaserc.yml"
+
+  path_instructions:
+    - path: ".github/workflows/self-*.yml"
+      instructions: |
+        This is a self-use entrypoint for this repository — NOT a reusable workflow.
+        Do NOT flag missing `workflow_call` — these files intentionally omit it.
+        `dry_run` is not required; flag it only if it is marked `required: true` or lacks a default value.
+        When `dry_run` is present it must be: type boolean, required false, default true for destructive operations (delete, purge) or default false for non-destructive ones (sync, notify).
+        Must call the corresponding reusable workflow via local path and contain no business logic.
+
+    - path: ".github/workflows/*.yml"
+      instructions: |
+        This is a reusable workflow in a shared CI/CD library. Repo-specific rules:
+        - Both `workflow_call` and `workflow_dispatch` must be present (except self-* files)
+        - Workflows that apply state changes must have a `dry_run` boolean input (default: false)
+        - Composites must use local path only: `./src/<capability>/<name>` — never an external ref
+        - A `docs/<filename>.md` matching this workflow's name must exist or be added in this PR
+        - Flag any removed or renamed input/output as a breaking change for callers
+
+    - path: "src/**/action.yml"
+      instructions: |
+        This is a composite action in a shared CI/CD library. Repo-specific rules:
+        - Max 15 steps — flag if exceeded
+        - Single responsibility only — no multi-language runtimes, no job definitions
+        - Flag any removed, renamed, or retyped input/output as a breaking change for callers
+        - Flag any default value change as a potentially breaking change
+
+    - path: "src/**/README.md"
+      instructions: |
+        Composite action README. Verify inputs table matches `action.yml` exactly (name, required, default).
+        Flag any usage example that references `@main` — examples must use `@develop` or `@feat/<branch>` for testing and `@vX.Y.Z` for production.
+
+    - path: "docs/*.md"
+      instructions: |
+        Workflow documentation. Filename must exactly match the workflow file (e.g., `go-ci.yml` → `docs/go-ci.md`).
+        Flag if inputs table is out of sync with the corresponding workflow changes in this PR.
+        Flag any usage example that references `@main` — examples must use `@develop` or `@feat/<branch>` for testing and `@vX.Y.Z` for production.
+
+  auto_review:
+    enabled: true
+    drafts: false
+    base_branches:
+      - "develop"
+    ignore_title_keywords:
+      - "WIP"
+      - "wip"
+      - "[skip review]"
+    auto_pause_after_reviewed_commits: 0
+
+chat:
+  auto_reply: true
diff --git a/.cursor/rules/composite-actions.mdc b/.cursor/rules/composite-actions.mdc
new file mode 100644
index 0000000..fe8a453
--- /dev/null
+++ b/.cursor/rules/composite-actions.mdc
@@ -0,0 +1,173 @@
+---
+description: Structure, design rules, and conventions for composite actions in src/
+globs: src/**/*.yml,src/**/action.yml,src/**/README.md
+alwaysApply: false
+---
+
+# Composite Actions
+
+## Modifying an existing composite?
+
+Follow the **refactoring protocol** in `.cursor/rules/refactoring.mdc` before making any change. Always produce a plan and wait for confirmation.
+
+---
+
+## Before you create anything
+
+**Step 1 — Check if it already exists in this repo**
+
+Search `src/` before starting. If a composite already covers the same capability:
+
+- Summarize what the existing composite does and which inputs it exposes
+- Identify the gap between the existing behavior and the new requirement
+- Propose an **adaptation plan** (add an input, extend steps, split into two) instead of creating a new file
+
+**Step 2 — Check the GitHub Actions Marketplace first**
+
+Before writing custom steps from scratch, search the [Marketplace](https://github.com/marketplace?type=actions) for an existing action that covers the need:
+
+- Prefer a well-maintained marketplace action over custom shell scripting for non-trivial logic
+- Wrap it in a composite if it needs input normalization or additional steps
+- Pin to a specific tag or SHA — never `@main` or `@master`
+- Document in the composite `README.md` why that action was chosen
+
+Only implement from scratch when no suitable action exists or when existing ones don't meet security or customization requirements.
+
+---
+
+## Directory layout
+
+Composite actions are grouped by capability inside `src/`:
+
+```
+src/
+├── setup/       ← language runtime setup (Go, Node, etc.)
+├── build/       ← build and artifact generation
+├── test/        ← test execution and coverage
+├── deploy/      ← deployment and release steps
+└── config/      ← repository configuration management
+```
+
+Each composite lives in `src/<capability>/<name>/` with exactly two files:
+
+```
+src/config/labels-sync/
+├── action.yml   ← required
+└── README.md    ← required
+```
+
+> **File extension rule:** always use `.yml`, never `.yaml`. This applies to `action.yml`, workflow files, and any YAML configuration files in this repository.
+
+## action.yml structure
+
+```yaml
+name: Human-readable name
+description: One-line description.
+
+inputs:
+  github-token:
+    description: GitHub token with required permissions
+    required: true
+  some-option:
+    description: What this option controls
+    required: false
+    default: "default-value"
+
+runs:
+  using: composite
+  steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: Do the work
+      uses: some-owner/some-action@v1
+      with:
+        token: ${{ inputs.github-token }}
+        option: ${{ inputs.some-option }}
+```
+
+## Design rules
+
+- **5–15 steps maximum** — split if larger
+- **Single responsibility** — one composite, one capability
+- Must not define jobs or call other workflows
+- Must not contain pipeline control logic
+- Never combine multiple language runtimes in the same composite
+
+## Language-specific vs cross-language
+
+Specialize by runtime when toolchains differ:
+
+```
+src/setup/setup-go/     ← Go toolchain, GOPATH, module cache
+src/setup/setup-node/   ← Node.js, npm/yarn/pnpm, cache
+src/build/build-go/     ← go build, cross-compilation
+src/test/test-go/       ← go test, coverage upload
+```
+
+Cross-language composites stay language-agnostic:
+
+```
+src/build/docker-build/   ← any image
+src/deploy/helm-deploy/   ← any chart
+src/config/labels-sync/   ← any repo
+```
+
+## README.md requirements
+
+1. Logo header — HTML table layout (logo left, `h1` title right)
+2. Inputs table — `Input | Description | Required | Default`
+3. Usage as composite step (full YAML)
+4. Usage as reusable workflow (full YAML with `secrets: inherit`)
+5. Required permissions block
+
+### Usage example ref policy
+
+Examples in README.md must never use `@main`. Use the correct ref for each context:
+
+```yaml
+# ✅ Testing — point to develop or feature branch
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/labels-sync.yml@develop
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/labels-sync.yml@feat/my-branch
+
+# ✅ Production — always a pinned stable version
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/labels-sync.yml@v1.2.3
+
+# ❌ Never in examples
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/labels-sync.yml@main
+```
+
+## After creating a new composite
+
+- Update root `README.md` if the composite is meant to be used by external callers
+
+### Labels checklist
+
+Check `.github/labels.yml` for a label matching the composite's capability group. If it doesn't exist, add it:
+
+```yaml
+# Example: adding a new capability group label
+- name: <capability>           # e.g. "infrastructure", "notifications"
+  color: "0075ca"              # pick a distinct hex color
+  description: Changes to <capability> composite actions
+```
+
+After adding, run the `Sync Labels` workflow (`workflow_dispatch`) to create the label in the repository.
+
+### Dependabot checklist
+
+For every third-party action used in the new composite (`uses: owner/action@vX`), check `.github/dependabot.yml`:
+
+- If `owner/*` already matches an existing group pattern → no change needed
+- If the action doesn't match any group → add it to the most appropriate group, or create a new group:
+
+```yaml
+# Example: new group for a new tool category
+new-tool-category:
+  patterns:
+    - "owner/new-action"
+  update-types:
+    - "minor"
+    - "patch"
+```
+
+Never add `LerianStudio/*` actions to dependabot — they are pinned to `@main` intentionally.
diff --git a/.cursor/rules/refactoring.mdc b/.cursor/rules/refactoring.mdc
new file mode 100644
index 0000000..13a77a7
--- /dev/null
+++ b/.cursor/rules/refactoring.mdc
@@ -0,0 +1,179 @@
+---
+description: Refactoring and incremental change protocol for reusable workflows and composite actions
+globs: .github/workflows/*.yml,src/**/*.yml,src/**/action.yml
+alwaysApply: false
+---
+
+# Refactoring Protocol
+
+Apply this protocol **before making any refactoring or additive change** to an existing reusable workflow or composite action.
+
+Never apply changes directly. Always produce a plan first, wait for explicit user confirmation, then apply one step at a time.
+
+---
+
+## Step 1 — Analyze the current state
+
+Before proposing any change, read the target file(s) completely and produce a structured summary:
+
+```
+Current state of <file>:
+- Purpose        : what the workflow/composite does
+- Inputs         : list all current inputs and their defaults
+- Outputs        : list all current outputs
+- Jobs/Steps     : list jobs (workflow) or steps (composite)
+- Callers        : note any known repos or workflows that reference this
+- dry_run        : present / absent
+```
+
+---
+
+## Step 2 — Produce the refactoring plan
+
+Present the plan as a numbered step list. Each step must describe:
+
+- **What changes** (file, section, input, job, step)
+- **Why** (the reason for the change)
+- **Impact** (additive, behavioral, breaking)
+- **Backward compatible?** (yes / no / conditional)
+
+Format:
+
+```
+Refactoring plan — <workflow or composite name>
+
+Step 1 — [Label]
+  Change : <what will be modified>
+  Reason : <why>
+  Impact : additive | behavioral | breaking
+  Safe   : yes | no — <explanation>
+
+Step 2 — [Label]
+  ...
+```
+
+---
+
+## Step 3 — Flag attention points
+
+After the plan, list explicitly:
+
+### Inputs and outputs
+- Any input being renamed, removed, or changing type → **breaking**
+- Any input with a new default that differs from the old implicit behavior → **breaking**
+- Any output being removed or renamed → **breaking**
+
+### Behavior
+- Any step order change that could affect downstream steps → **attention**
+- Any conditional logic that changes when a step runs → **attention**
+- Any new required secret → **breaking for callers**
+
+### dry_run
+- If the workflow/composite does not have a `dry_run` input and the change involves applying state (deploy, create, update, delete), propose adding it as part of the plan:
+
+```yaml
+dry_run:
+  description: Preview changes without applying them
+  required: false
+  type: boolean
+  default: false
+```
+
+---
+
+## Step 4 — Show breaking changes explicitly
+
+If any step is breaking, present it separately with a migration guide:
+
+```
+⚠️ Breaking change in Step N
+
+Before (callers must update):
+  with:
+    old_input: value
+
+After:
+  with:
+    new_input: value
+
+Migration: replace `old_input` with `new_input`. Default behavior is preserved
+when `new_input` is omitted.
+```
+
+---
+
+## Step 5 — Propose test examples
+
+For every behavioral change, provide a concrete test scenario:
+
+```yaml
+# Test scenario: <what is being tested>
+# Expected result: <what should happen>
+
+jobs:
+  test:
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/<workflow>.yml@develop
+    with:
+      <input>: <test value>
+      dry_run: true   # validate before applying
+```
+
+If the change affects a composite action, show how to invoke it via a calling workflow:
+
+```yaml
+- name: Test <composite>
+  uses: ./src/<capability>/<name>
+  with:
+    <input>: <test value>
+```
+
+---
+
+## Step 6 — Confirm before applying
+
+After presenting the full plan, attention points, breaking changes, and test examples, ask:
+
+```
+Ready to apply?
+
+Please confirm each step:
+  [ ] Step 1 — <label>
+  [ ] Step 2 — <label>
+  ...
+
+Reply with the step numbers you want applied, or "all" to apply everything.
+Reply with "cancel" to abort.
+```
+
+**Do not apply any change until the user explicitly confirms.**
+
+---
+
+## Step 7 — Apply one step at a time
+
+Apply only the confirmed steps. After each one:
+
+- Show a diff summary of what changed
+- Note if the next step depends on this one
+- Wait for confirmation before proceeding to the next step if they are independent
+
+---
+
+## Step 8 — Update documentation
+
+After all confirmed steps are applied, update:
+
+- `docs/<workflow-name>.md` — reflect any changed inputs, outputs, or behavior
+- Composite `README.md` — update the inputs table and usage examples
+- `CHANGELOG.md` — do **not** edit manually; semantic-release generates it from commits
+- If a breaking change was applied, note the migration path in the doc
+
+---
+
+## What must never change without explicit confirmation
+
+- Default values of existing inputs
+- Names of existing inputs or outputs
+- Behavior when optional inputs are omitted
+- Step ordering when downstream steps depend on earlier outputs
+- Required secrets — adding one is always a breaking change for callers
diff --git a/.cursor/rules/reusable-workflows.mdc b/.cursor/rules/reusable-workflows.mdc
new file mode 100644
index 0000000..e2413c0
--- /dev/null
+++ b/.cursor/rules/reusable-workflows.mdc
@@ -0,0 +1,290 @@
+---
+description: Architecture, structure, conventions, and security rules for reusable workflows in .github/workflows/
+globs: .github/workflows/*.yml
+alwaysApply: false
+---
+
+# Reusable Workflows
+
+## Modifying an existing workflow?
+
+Follow the **refactoring protocol** in `.cursor/rules/refactoring.mdc` before making any change. Always produce a plan and wait for confirmation.
+
+---
+
+## Before you create anything
+
+**Step 1 — Check if it already exists in this repo**
+
+Search `.github/workflows/` before starting. If a workflow already covers the same pipeline:
+
+- Summarize what the existing workflow does, its jobs, inputs, and secrets
+- Identify the gap between the existing behavior and the new requirement
+- Propose an **adaptation plan** (add a job, add an input, expose a new secret) instead of creating a new workflow file
+
+**Step 2 — Check the GitHub Actions Marketplace first**
+
+Before implementing custom steps inside a workflow, search the [Marketplace](https://github.com/marketplace?type=actions) for actions that already solve the problem:
+
+- Prefer a well-maintained action over custom shell scripting for non-trivial logic
+- If the action needs wrapping (normalization, extra steps), create a composite in `src/` and call it from the workflow — don't inline complex shell in the workflow itself
+- Pin to a specific tag or SHA — never `@main` or `@master`
+- Document in `docs/<workflow-name>.md` why that action was chosen
+
+Only implement from scratch when no suitable action exists or when existing ones don't meet security or customization requirements.
+
+---
+
+## Architecture model
+
+```
+Caller repository workflow         ← minimal entrypoint: triggers + secrets only
+         ↓
+Reusable workflow                  ← orchestrates jobs, runners, secrets
+(.github/workflows/*.yml)
+         ↓
+Composite action                   ← encapsulates reusable steps
+(src/<capability>/<name>/action.yml)
+```
+
+**Rules:**
+- Caller workflows must contain only triggers and job references — no business logic
+- Reusable workflows must orchestrate jobs and route secrets
+- Composite actions must encapsulate steps for a single responsibility
+
+**Example: Go CI pipeline**
+
+```
+caller: .github/workflows/ci.yml  (on: push)
+    ↓
+reusable: go-ci.yml
+    ↓ job: ci
+        → src/setup/setup-go      (install Go, restore cache)
+        → src/build/build-go      (compile, vet)
+        → src/test/test-go        (run tests, upload coverage)
+        → src/build/docker-build  (build and push image)
+```
+
+## When to use each
+
+| Need | Use |
+|---|---|
+| Standardize a full CI/CD pipeline across repos | Reusable workflow |
+| Reuse a group of steps inside a job | Composite action |
+| Share setup / build / lint / test logic | Composite action |
+| Manage multiple jobs or runners | Reusable workflow only |
+| Route secrets to jobs | Reusable workflow only |
+
+## self-* workflows (entrypoints for this repo)
+
+Files prefixed with `self-` (e.g. `self-labels-sync.yml`, `self-branch-cleanup.yml`) are **thin entrypoints** for this repository's own automation. They are not reusable workflows.
+
+Rules for `self-*` files:
+- **Must NOT have `workflow_call`** — they are not offered to external callers
+- **`dry_run` is not required** — omit it unless the workflow performs destructive operations
+- **When `dry_run` is present**, it must be: `type: boolean`, `required: false`, `default: true` for destructive ops (delete, purge) or `default: false` for non-destructive ops (sync, notify)
+- Must call the corresponding reusable workflow via local path (`./.github/workflows/<name>.yml`)
+- Triggers are repo-specific: `push`, `schedule`, `pull_request`, `workflow_dispatch`
+- Must not contain business logic
+
+```yaml
+# ✅ Correct self-* structure
+name: Self — Labels Sync
+on:
+  push:
+    branches: [main]
+    paths: [".github/labels.yml"]
+  workflow_dispatch:
+jobs:
+  sync:
+    uses: ./.github/workflows/labels-sync.yml  # local path only
+    secrets: inherit
+```
+
+---
+
+## Workflow structure
+
+Every reusable workflow must:
+- support `workflow_call` (for external callers)
+- support `workflow_dispatch` (for manual testing)
+- expose explicit `inputs` — never rely on implicit context
+- **always include a `dry_run` input** (`type: boolean`, `default: false`) so the workflow can be safely tested before applying real changes
+
+```yaml
+on:
+  workflow_call:
+    inputs:
+      environment:
+        required: true
+        type: string
+      dry_run:
+        description: Preview changes without applying them
+        required: false
+        type: boolean
+        default: false
+    secrets:
+      DEPLOY_TOKEN:
+        required: true
+  workflow_dispatch:
+    inputs:
+      environment:
+        required: true
+        type: string
+      dry_run:
+        description: Preview changes without applying them
+        type: boolean
+        default: false
+```
+
+The two modes have opposite goals — design them accordingly:
+
+| Mode | Goal | Log style |
+|---|---|---|
+| `dry_run: true` | Validate before applying | Verbose — print everything |
+| `dry_run: false` | Apply cleanly | Silent — only errors and summaries |
+
+```yaml
+# dry_run: true — verbose, annotated, tool debug flags on
+- name: Dry run summary
+  if: ${{ inputs.dry_run }}
+  run: |
+    echo "::notice::DRY RUN — no changes will be applied"
+    echo "  environment : ${{ inputs.environment }}"
+    echo "  target      : ${{ steps.resolve.outputs.target }}"
+    echo "  version     : ${{ steps.resolve.outputs.version }}"
+    echo "  would run   : helm upgrade --install ${{ steps.resolve.outputs.release }} ..."
+
+- name: Preview (dry run)
+  if: ${{ inputs.dry_run }}
+  run: helm upgrade --install --dry-run --debug ...
+
+# dry_run: false — clean, no extra echo, output only on failure
+- name: Apply
+  if: ${{ !inputs.dry_run }}
+  run: helm upgrade --install ...   # no --debug, no extra echo
+```
+
+**Dry run (`true`) rules:**
+- Use `::notice::` annotations so the dry run state is visible in the Actions summary
+- Print every resolved input, computed variable, and environment value
+- Enable tool-native verbose/preview flags (`--dry-run --debug`, `--check`, `--plan`, `--diff`)
+- Never skip silently — always confirm what *would* have happened
+
+**Real run (`false`) rules:**
+- No extra `echo` statements beyond what the tool already outputs
+- No debug flags — use tool defaults
+- Let failures surface naturally via non-zero exit codes
+- Add a single `::notice::` summary line only after successful completion if useful
+
+## Local path rule (critical)
+
+Inside a reusable workflow, always reference composites with a local path:
+
+```yaml
+uses: ./src/setup/setup-go      # ✅ composite version matches workflow version
+uses: LerianStudio/...@main     # ❌ breaks versioning for callers on older tags
+```
+
+## Secrets management
+
+Secrets must always flow from the caller — never hardcoded inside reusable workflows:
+
+```yaml
+# Caller repository
+jobs:
+  deploy:
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/deploy.yml@v1.2.3
+    secrets:
+      DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }}
+
+# Reusable workflow — declare but never set a value
+on:
+  workflow_call:
+    secrets:
+      DOCKER_TOKEN:
+        required: true
+```
+
+## Naming conventions
+
+Descriptive, hyphenated names that reflect purpose and language when applicable:
+
+```
+✅  go-ci.yml   build-node.yml   labels-sync.yml   helm-deploy.yml
+❌  workflow.yml   pipeline.yml   ci.yml   action.yml
+```
+
+Always use `.yml` extension — never `.yaml`:
+
+```
+✅  go-ci.yml   action.yml   labels.yml   dependabot.yml
+❌  go-ci.yaml  action.yaml  labels.yaml
+```
+
+## Documentation naming
+
+The doc file in `docs/` must have the **exact same name** as the workflow file, with `.md` extension, and must start with the Lerian branding header:
+
+```markdown
+<table border="0" cellspacing="0" cellpadding="0">
+  <tr>
+    <td><img src="https://github.com/LerianStudio.png" width="72" alt="Lerian" /></td>
+    <td><h1>workflow-name</h1></td>
+  </tr>
+</table>
+```
+
+```
+.github/workflows/go-ci.yml        → docs/go-ci.md          ✅
+.github/workflows/go-ci.yml        → docs/go-ci-workflow.md  ❌
+.github/workflows/labels-sync.yml  → docs/labels-sync.md    ✅
+```
+
+Every new reusable workflow must have a corresponding `docs/<workflow-name>.md`.
+
+### Usage example ref policy
+
+Examples in `docs/` must never use `@main`. Use the correct ref for each context:
+
+```yaml
+# ✅ Testing — point to develop or feature branch
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@develop
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@feat/my-branch
+
+# ✅ Production — always a pinned stable version
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@v1.2.3
+
+# ❌ Never in examples
+uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@main
+```
+
+## Anti-patterns
+
+```yaml
+# ❌ Monolithic composite — does setup + build + test + deploy in one action
+src/go-ci/action.yml
+
+# ❌ Multi-language composite — couples runtimes
+src/build/build-all/action.yml
+
+# ❌ Orchestration inside composite — composites cannot have jobs
+runs:
+  using: composite
+  jobs:          # invalid — composites have steps, not jobs
+    build: ...
+
+# ❌ External ref for composite inside a reusable workflow
+uses: LerianStudio/github-actions-shared-workflows/src/setup-go@main  # breaks versioning
+
+# ❌ Mutable ref on third-party actions
+uses: some-action/tool@main    # use a specific tag or SHA
+```
+
+## Security rules
+
+- Pin all third-party actions to a specific tag or SHA — Dependabot keeps them updated
+- Never use `@main` or `@master` for third-party actions
+- Never interpolate untrusted user input directly into `run:` commands
+- Never print secrets via `echo`, env dumps, or step summaries
+- Complex conditional logic belongs in the workflow (not in composites) — full log visibility
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 8fd3876..fe0f4e4 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -5,6 +5,3 @@ contact_links:
     about: >
       Found a security issue? Please report it privately via GitHub Security Advisories —
       do NOT open a public issue. Read our SECURITY.md for details.
-  - name: DevOps Team Support
-    url: https://github.com/LerianStudio/github-actions-shared-workflows/discussions
-    about: Have a question or need help? Start a discussion instead of opening an issue.
diff --git a/.github/labeler.yml b/.github/labeler.yml
index 8bdfc9b..83d472b 100644
--- a/.github/labeler.yml
+++ b/.github/labeler.yml
@@ -4,22 +4,26 @@
 
 # ── Workflows ──────────────────────────────────────────────────────────────────
 
+# Any change to a reusable workflow file
 workflow:
   - changed-files:
     - any-glob-to-any-file: ".github/workflows/*.yml"
 
 # ── Ecosystems ─────────────────────────────────────────────────────────────────
 
+# Changes to Go-related workflows (go-ci, go-security, go-release, go-pr-analysis)
 golang:
   - changed-files:
     - any-glob-to-any-file: ".github/workflows/go-*.yml"
 
+# Changes to TypeScript or Frontend workflows
 typescript:
   - changed-files:
     - any-glob-to-any-file:
       - ".github/workflows/typescript-*.yml"
       - ".github/workflows/frontend-*.yml"
 
+# Changes to security workflows or the vulnerability reporting policy
 security:
   - changed-files:
     - any-glob-to-any-file:
@@ -29,6 +33,7 @@ security:
 
 # ── Change types ───────────────────────────────────────────────────────────────
 
+# Changes to docs/, any top-level markdown file, or markdown inside .github/
 documentation:
   - changed-files:
     - any-glob-to-any-file:
@@ -36,10 +41,13 @@ documentation:
       - "*.md"
       - ".github/**/*.md"
 
+# Changes to dependabot.yml (usually opened automatically by Dependabot itself)
 dependencies:
   - changed-files:
     - any-glob-to-any-file: ".github/dependabot.yml"
 
+# Changes to repository-level configuration: issue templates, PR template,
+# labeler, CODEOWNERS, release config, or gitignore
 github-config:
   - changed-files:
     - any-glob-to-any-file:
diff --git a/.github/labels.yml b/.github/labels.yml
new file mode 100644
index 0000000..cfb642e
--- /dev/null
+++ b/.github/labels.yml
@@ -0,0 +1,85 @@
+# Label definitions for github-actions-shared-workflows
+# Synced automatically by .github/workflows/labels-sync.yml
+# Run the workflow manually after adding or changing labels here.
+
+# ── Workflows ──────────────────────────────────────────────────────────────────
+
+- name: workflow
+  color: "0075ca"
+  description: Changes to one or more reusable workflow files
+
+- name: golang
+  color: "00ADD8"
+  description: Changes to Go-related workflows
+
+- name: typescript
+  color: "3178C6"
+  description: Changes to TypeScript or Frontend workflows
+
+- name: security
+  color: "e11d48"
+  description: Changes to security workflows or vulnerability reporting policy
+
+# ── Change types ───────────────────────────────────────────────────────────────
+
+- name: documentation
+  color: "0e8a16"
+  description: Improvements or additions to documentation
+
+- name: dependencies
+  color: "ededed"
+  description: Dependency updates (usually opened by Dependabot)
+
+- name: github-config
+  color: "f9d0c4"
+  description: Changes to repository configuration (templates, CODEOWNERS, labeler, etc.)
+
+- name: bug
+  color: "d73a4a"
+  description: Something is not working as expected
+
+- name: enhancement
+  color: "a2eeef"
+  description: New feature or improvement request
+
+# ── PR size ────────────────────────────────────────────────────────────────────
+
+- name: size/XS
+  color: "3CBF00"
+  description: "PR changes < 50 lines"
+
+- name: size/S
+  color: "5D9801"
+  description: "PR changes 50–199 lines"
+
+- name: size/M
+  color: "7F7203"
+  description: "PR changes 200–499 lines"
+
+- name: size/L
+  color: "A14C05"
+  description: "PR changes 500–999 lines"
+
+- name: size/XL
+  color: "C32607"
+  description: "PR changes ≥ 1000 lines — consider splitting"
+
+# ── Triage ─────────────────────────────────────────────────────────────────────
+
+- name: triage
+  color: "e4e669"
+  description: Needs initial assessment by the DevOps team
+
+- name: skip-changelog
+  color: "ffffff"
+  description: This change does not need a changelog entry
+
+- name: breaking-change
+  color: "b60205"
+  description: Callers must update their workflow configuration after this change
+
+# ── Capabilities ──────────────────────────────────────────────────────────────
+
+- name: config
+  color: "c5def5"
+  description: Changes to repository configuration composite actions (src/config/)
diff --git a/.github/workflows/branch-cleanup.yml b/.github/workflows/branch-cleanup.yml
new file mode 100644
index 0000000..7ef37a7
--- /dev/null
+++ b/.github/workflows/branch-cleanup.yml
@@ -0,0 +1,63 @@
+name: Branch Cleanup
+
+on:
+  workflow_call:
+    inputs:
+      stale_days:
+        description: Days without commits before a branch is considered stale
+        required: false
+        type: number
+        default: 30
+      dry_run:
+        description: Preview changes without applying them
+        required: false
+        type: boolean
+        default: false
+      protected_branches:
+        description: Comma-separated branch patterns to never delete
+        required: false
+        type: string
+        default: "main,master,develop,release/*,hotfix/*"
+      merged_branch:
+        description: Branch to delete (enables merged-branch mode)
+        required: false
+        type: string
+        default: ""
+    secrets:
+      GITHUB_TOKEN:
+        required: false
+  workflow_dispatch:
+    inputs:
+      stale_days:
+        description: Days without commits before a branch is considered stale
+        type: number
+        default: 30
+      dry_run:
+        description: Preview changes without applying them
+        type: boolean
+        default: false
+      protected_branches:
+        description: Comma-separated branch patterns to never delete
+        type: string
+        default: "main,master,develop,release/*,hotfix/*"
+
+permissions:
+  contents: write
+  pull-requests: read
+
+jobs:
+  cleanup:
+    name: Clean up branches
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run branch cleanup
+        uses: ./src/config/branch-cleanup
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          stale-days: ${{ inputs.stale_days }}
+          dry-run: ${{ inputs.dry_run || false }}
+          protected-branches: ${{ inputs.protected_branches || 'main,master,develop,release/*,hotfix/*' }}
+          merged-branch: ${{ inputs.merged_branch || '' }}
diff --git a/.github/workflows/labels-sync.yml b/.github/workflows/labels-sync.yml
new file mode 100644
index 0000000..99b5c3c
--- /dev/null
+++ b/.github/workflows/labels-sync.yml
@@ -0,0 +1,55 @@
+name: Sync Labels
+
+on:
+  workflow_call:
+    inputs:
+      config:
+        description: Path to the labels YAML definition file
+        type: string
+        required: false
+        default: .github/labels.yml
+      dry_run:
+        description: Preview changes without applying them
+        type: boolean
+        required: false
+        default: false
+      skip_delete:
+        description: Skip deletion of labels not present in the config file
+        type: boolean
+        required: false
+        default: false
+    secrets:
+      GITHUB_TOKEN:
+        required: false
+  workflow_dispatch:
+    inputs:
+      config:
+        description: Path to the labels YAML definition file
+        type: string
+        required: false
+        default: .github/labels.yml
+      dry_run:
+        description: Dry run — preview changes without applying them
+        type: boolean
+        default: false
+      skip_delete:
+        description: Skip deletion of labels not present in the config file
+        type: boolean
+        default: false
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  sync:
+    name: Sync labels to repository
+    runs-on: ubuntu-latest
+    steps:
+      - name: Sync labels
+        uses: ./src/labels-sync
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          config: ${{ inputs.config || '.github/labels.yml' }}
+          dry-run: ${{ inputs.dry_run || false }}
+          skip-delete: ${{ inputs.skip_delete || false }}
diff --git a/.github/workflows/self-branch-cleanup.yml b/.github/workflows/self-branch-cleanup.yml
new file mode 100644
index 0000000..85b205c
--- /dev/null
+++ b/.github/workflows/self-branch-cleanup.yml
@@ -0,0 +1,41 @@
+name: Self — Branch Cleanup
+
+on:
+  schedule:
+    - cron: "0 3 * * 1"  # every Monday at 03:00 UTC
+  pull_request:
+    types:
+      - closed
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Preview deletions without applying them
+        type: boolean
+        default: true
+      stale_days:
+        description: Days without commits before a branch is stale
+        type: number
+        default: 30
+
+permissions:
+  contents: write
+  pull-requests: read
+
+jobs:
+  stale:
+    name: Clean stale branches
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    uses: ./.github/workflows/branch-cleanup.yml
+    with:
+      stale_days: ${{ inputs.stale_days || 30 }}
+      dry_run: ${{ inputs.dry_run || false }}
+    secrets: inherit
+
+  merged:
+    name: Delete merged branch
+    if: github.event_name == 'pull_request' && github.event.pull_request.merged == true
+    uses: ./.github/workflows/branch-cleanup.yml
+    with:
+      merged_branch: ${{ github.head_ref }}
+      dry_run: false
+    secrets: inherit
diff --git a/.github/workflows/self-labels-sync.yml b/.github/workflows/self-labels-sync.yml
new file mode 100644
index 0000000..7ac8fbe
--- /dev/null
+++ b/.github/workflows/self-labels-sync.yml
@@ -0,0 +1,26 @@
+name: Self — Sync Labels
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/labels.yml"
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Preview changes without applying them
+        type: boolean
+        default: false
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  sync:
+    name: Sync labels
+    uses: ./.github/workflows/labels-sync.yml
+    with:
+      dry_run: ${{ inputs.dry_run || false }}
+    secrets: inherit
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3f9ab3c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,122 @@
+# Agent Guidelines — GitHub Actions Shared Workflows
+
+> Read this file before making any changes. It provides essential context for AI agents working in this repository.
+
+---
+
+## What this repository is
+
+A **public** monorepo of reusable GitHub Actions workflows and composite actions maintained by [Lerian](https://github.com/LerianStudio).  
+Every change here can affect all repositories in the organization that consume these workflows — treat it accordingly.
+
+Full documentation: [`README.md`](README.md) | Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md) | Security: [`SECURITY.md`](SECURITY.md)
+
+**Claude Code CLI commands** (load at session start for full context):
+- `/gha` — complete reference (workflows + composites + refactoring protocol)
+- `/workflow` — reusable workflow rules only
+- `/composite` — composite action rules only
+- `/refactor` — refactoring protocol for modifying existing workflows or composites
+
+---
+
+## Key conventions (read before editing)
+
+### Workflows vs composite actions
+
+| Type | Location | Purpose |
+|---|---|---|
+| Reusable workflow | `.github/workflows/*.yml` | Callable via `workflow_call` by other repos |
+| Composite action | `src/<capability>/<name>/` | Reusable step logic, called from reusable workflows |
+
+Composite actions are grouped by capability: `src/setup/`, `src/build/`, `src/test/`, `src/deploy/`, `src/config/`.  
+Each composite must have an `action.yml` and a `README.md`.
+
+Full rules:
+- Composite actions → `.cursor/rules/composite-actions.mdc` or `/composite`
+- Reusable workflows → `.cursor/rules/reusable-workflows.mdc` or `/workflow`
+- Modifying existing files → `.cursor/rules/refactoring.mdc` or `/refactor`
+
+### Local path rule for composites
+
+Inside a reusable workflow, always reference composite actions with a **local path**:
+
+```yaml
+uses: ./src/config/labels-sync      # ✅ version-safe
+uses: LerianStudio/...@main         # ❌ breaks versioning for callers on older tags
+```
+
+### dry_run
+
+Every reusable workflow must include a `dry_run` input (`boolean`, `default: false`).  
+`dry_run: true` must be verbose (print all resolved values, use tool debug flags). `dry_run: false` must be silent (no extra echo, no debug flags).
+
+### Branches and commits
+
+- PRs always target `develop` — never `main` directly
+- Follow [Conventional Commits](https://www.conventionalcommits.org/): `type(scope): subject`
+- See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full type/version-bump table and scope list
+
+### Files never to edit manually
+
+| File | Reason |
+|---|---|
+| `CHANGELOG.md` | Auto-generated by semantic-release on every release |
+| `.releaserc.yml` | Drives all release automation — changes need DevOps review |
+| `.github/CODEOWNERS` | Controls review routing — discuss with the team first |
+
+**File extension:** always use `.yml`, never `.yaml` — for workflows, composites, and any YAML config files.
+
+---
+
+## Opening issues
+
+Always use the structured templates in `.github/ISSUE_TEMPLATE/`. Choose the right one based on the nature of the request:
+
+| Template | File | When to use |
+|---|---|---|
+| Bug Report | `bug_report.yml` | Something in a workflow is broken or behaving unexpectedly |
+| Feature Request | `feature_request.yml` | New workflow, new input/output, or enhancement to an existing one |
+| Documentation | `documentation.yml` | Missing, incorrect, or unclear documentation |
+
+Read the chosen template file before drafting the issue to ensure all required fields are filled in correctly. Never open a blank issue — `blank_issues_enabled: false` is enforced by `config.yml`.
+
+For security vulnerabilities, **never open a public issue** — follow the process in [`SECURITY.md`](SECURITY.md).
+
+---
+
+## Opening pull requests
+
+Always read `.github/pull_request_template.md` before drafting a PR description. Fill in every section — do not leave placeholder comments in place.
+
+Key fields to always complete:
+
+- **Description** — what changed and why, specific to the affected workflow(s)
+- **Type of Change** — mark all that apply
+- **Breaking Changes** — if none, leave `None.`; if yes, describe what breaks and how to migrate
+- **Testing** — check off what was actually validated; add the caller repo / run link if a real run was triggered
+
+PR titles must follow Conventional Commits: `type(scope): subject` (lowercase, imperative, max 72 chars).  
+PRs always target `develop` — never `main` directly.
+
+---
+
+## Refactoring existing workflows or composites
+
+Before modifying any existing file, follow the refactoring protocol in `.cursor/rules/refactoring.mdc` (or run `/refactor` in Claude CLI):
+
+1. Summarize the current state of the file (inputs, outputs, jobs/steps, dry_run presence)
+2. Produce a numbered plan with impact classification for each change
+3. Flag breaking changes explicitly and provide a migration guide
+4. Propose test examples using `dry_run: true` on `@develop`
+5. **Ask the user to confirm each step before applying** — never apply changes without confirmation
+6. Apply one step at a time and update documentation after all confirmed steps
+
+**What must never change without explicit confirmation:** input/output names, default values, step ordering that affects downstream outputs, required secrets.
+
+---
+
+## Security rules
+
+- Never hardcode tokens, org names, or internal URLs — use `inputs` or `secrets`
+- Never print secrets via `echo`, `run` output, or step summaries
+- Vulnerability reports go through private channels only — see [`SECURITY.md`](SECURITY.md)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 398e760..0b1c82e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -12,6 +12,7 @@ Thank you for contributing to the Lerian shared workflows repository. Changes he
 ## Table of Contents
 
 - [Branch Strategy](#branch-strategy)
+- [Merge Strategy](#merge-strategy)
 - [Step-by-Step Contribution Flow](#step-by-step-contribution-flow)
 - [Commit Message Format](#commit-message-format)
 - [Testing Workflow Changes](#testing-workflow-changes)
@@ -45,6 +46,21 @@ This repository uses a two-branch model:
 
 ---
 
+## Merge Strategy
+
+The merge strategy varies by the type of PR. This is a **convention enforced by reviewers** — it is not locked at the settings level to allow flexibility for backmerges and releases.
+
+| PR type | Source → Target | Strategy | Why |
+|---|---|---|---|
+| Feature / fix / docs | `feature/*` → `develop` | **Squash and merge** | One clean commit per PR; drives semantic-release correctly |
+| Release | `develop` → `main` | **Merge commit** | Preserves individual PR commits so semantic-release can compute the version bump |
+| Hotfix | `hotfix/*` → `main` | **Squash and merge** | One clean commit for the fix; backmerge follows immediately |
+| Backmerge | `main` → `develop` | **Merge commit** | Preserves history; squash would collapse all of main into one commit |
+
+> **Reviewers:** before clicking Merge, confirm the correct strategy is selected in the GitHub UI. Do not use rebase.
+
+---
+
 ## Step-by-Step Contribution Flow
 
 This repository is public. The contribution flow differs slightly depending on whether you are a **Lerian team member** (write access) or an **external contributor** (no write access).
@@ -86,6 +102,7 @@ When opening the PR, target the `develop` branch of the **upstream** (`LerianStu
 ### 2. Make your changes
 
 - Edit only the workflow file(s) relevant to your change
+- Always use `.yml` extension — never `.yaml` (applies to workflows, composites, and any YAML config files)
 - Follow YAML best practices (2-space indent, quoted strings for expressions)
 - Add inline comments for non-obvious steps or conditions
 - Update the corresponding doc in `docs/` if behavior or inputs/outputs changed
@@ -321,7 +338,9 @@ uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@m
 
 - **Never** commit directly to `main` or `develop`
 - **Always** target `develop` in your PRs (not `main`)
+- **Always** use the correct merge strategy — squash for feature PRs, merge commit for releases and backmerges
 - **Always** use Conventional Commits — the message type controls the version bump
+- **Always** use `.yml` extension — never `.yaml` for any YAML file in this repository
 - **Never** hardcode org-specific values (tokens, org names, URLs) — use `inputs` or `secrets`
 - **Always** update `docs/` when you change inputs, outputs, or behavior
 - **Ensure** backward compatibility when possible; document breaking changes clearly
diff --git a/README.md b/README.md
index 8cf72e2..25284e2 100644
--- a/README.md
+++ b/README.md
@@ -1,131 +1,90 @@
-# GitHub Actions Shared Workflows
+<table border="0" cellspacing="0" cellpadding="0">
+  <tr>
+    <td><img src="https://github.com/LerianStudio.png" width="72" alt="Lerian" /></td>
+    <td><h1>GitHub Actions Shared Workflows</h1></td>
+  </tr>
+</table>
 
-Centralized repository for reusable GitHub Actions workflows used across the Lerian organization.
+Centralized reusable GitHub Actions workflows and composite actions for the Lerian organization.
 
-## Available Workflows
+## How it works
 
-### 1. [Go CI](docs/go-ci-workflow.md)
-Multi-version Go continuous integration with testing, linting, and optional cross-platform builds.
-
-**Key Features**: Multi-version testing, golangci-lint, cross-platform builds, coverage comments
-
-### 2. [Go Security](docs/go-security-workflow.md)
-Comprehensive security scanning for Go projects with 8 security tools.
-
-**Key Features**: Gosec, govulncheck, Nancy, Trivy, TruffleHog, license checks, SBOM generation
-
-### 3. [Go Release](docs/go-release-workflow.md)
-Automated release creation using GoReleaser with optional Docker and Homebrew publishing.
-
-**Key Features**: GoReleaser automation, multi-platform builds, Docker images, Homebrew formulas
-
-### 4. [GitOps Update](docs/gitops-update-workflow.md)
-Update GitOps repository with new image tags across multiple environments.
-
-**Key Features**: Multi-environment support, automatic environment detection, ArgoCD sync
-
-### 5. [API Dog E2E Tests](docs/api-dog-e2e-tests-workflow.md)
-Automated API testing using Apidog CLI with comprehensive reporting.
-
-**Key Features**: Auto environment detection, multiple output formats, configurable iterations
-
-### 6. [PR Validation](docs/pr-validation-workflow.md)
-Comprehensive pull request validation enforcing best practices and coding standards.
-
-**Key Features**: Semantic PR titles, size tracking, auto-labeling, changelog checks, source branch validation
-
-### 7. [PR Security Scan](docs/pr-security-scan-workflow.md)
-Comprehensive security scanning for pull requests with Trivy.
-
-**Key Features**: Secret scanning, vulnerability scanning, monorepo support, component-scoped scanning
-
-### 8. [Release Workflow](docs/release-workflow.md)
-Semantic versioning and automated release management with GPG signing.
-
-**Key Features**: Semantic versioning, GPG signing, hotfix support
-
-### 9. [Changed Paths](docs/changed-paths-workflow.md)
-Detect changed paths between commits for monorepo CI/CD optimization.
-
-**Key Features**: Path filtering, path level trimming, app name generation, matrix strategy support
-
-### 10. [Go PR Analysis](docs/go-pr-analysis-workflow.md)
-Comprehensive Go PR analysis for monorepos with change detection, linting, security, testing, and coverage.
-
-**Key Features**: Change detection, matrix execution, GolangCI-Lint, GoSec, coverage checks, private module support
-
-### 11. [Build](docs/build-workflow.md)
-Build and push Docker images with monorepo support and multi-platform builds.
-
-**Key Features**: Monorepo support, multi-registry (DockerHub/GHCR), smart platform builds, GitOps artifacts
-
-### 12. [Slack Notify](docs/slack-notify-workflow.md)
-Send Slack notifications from workflows with rich formatting and status-based colors.
-
-**Key Features**: Rich formatting, status colors, graceful degradation, PR support
-
-### 13. [Frontend PR Analysis](docs/frontend-pr-analysis-workflow.md)
-Comprehensive Frontend/Node.js PR analysis for monorepos with change detection, linting, type checking, security, testing, and coverage.
-
-**Key Features**: Change detection, matrix execution, ESLint, TypeScript, npm audit, coverage checks, npm/yarn/pnpm support
+```
+Your repository workflow
+         ↓
+Reusable workflow (.github/workflows/*.yml)   ← orchestrates jobs
+         ↓
+Composite action  (src/<capability>/<name>/)  ← encapsulates steps
+```
 
-### 14. [GPT Changelog](docs/gptchangelog-workflow.md)
-AI-powered changelog generation using OpenRouter API (GPT-4o) with consolidated output.
+Workflows are called via `workflow_call` and versioned with semantic tags. Pin to a specific tag in production — never use `@main`.
 
-**Key Features**: AI commit analysis, consolidated changelog, monorepo support, GitHub Release integration, GPG signing
+All YAML files in this repository use the `.yml` extension — never `.yaml`.
 
-## Documentation
+## Available workflows
 
-Individual workflow documentation is available in the [`docs/`](docs/) directory.
+See the [`docs/`](docs/) directory for the full list, inputs, outputs, and usage examples for each workflow.
 
 ## Quick Start
 
-> **Tip:** Pin to a specific release tag in production (e.g. `@v1.2.3`) instead of `@main` for stability. See [versioning](#versioning) for details.
-
 ```yaml
-# Example: Complete CI/CD Pipeline
 jobs:
-  security_scan:
+  security:
     uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@v1.2.3
 
   release:
     uses: LerianStudio/github-actions-shared-workflows/.github/workflows/release.yml@v1.2.3
 
-  update_gitops:
+  gitops:
     uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@v1.2.3
-
-  e2e_tests:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/api-dog-e2e-tests.yml@v1.2.3
 ```
 
-See the [`docs/`](docs/) directory for complete examples and configuration options for each workflow.
-
 ## Versioning
 
-This repository uses [Semantic Versioning](https://semver.org/) with automated releases via [semantic-release](https://github.com/semantic-release/semantic-release).
+Releases follow [Semantic Versioning](https://semver.org/) via [semantic-release](https://github.com/semantic-release/semantic-release):
+
+- Merges to `develop` → beta pre-release (`v1.2.3-beta.1`)
+- Merges to `main` → stable release (`v1.2.3`)
+
+## AI Assistant Support
 
-**Branches:**
-- `develop` — Development branch; merges here publish a beta pre-release (`v1.2.3-beta.1`)
-- `main` — Production branch; merges here publish a stable release (`v1.2.3`)
+Built-in guidance for AI assistants is included so they understand the architecture before making changes.
 
-**Commit types and version impact:**
+### Cursor IDE
 
-| Type | Version bump |
+Rules activate automatically based on the file open — no setup needed.
+
+| File | Rule loaded |
 |---|---|
-| `feat`, `perf`, `refactor`, `build` | Minor (`1.x.0`) |
-| `fix`, `docs`, `chore`, `ci`, `test` | Patch (`1.0.x`) |
-| `BREAKING CHANGE` (in footer) | Major (`x.0.0`) |
+| `src/**/*.yml` | Composite action conventions |
+| `.github/workflows/*.yml` | Reusable workflow architecture |
+
+### Claude Code CLI
+
+```bash
+claude
+> /workflow    # reusable workflow rules
+> /composite   # composite action rules
+> /gha         # everything at once
+```
+
+**Example:**
+```bash
+claude
+> /gha
+> Add a helm-deploy composite under src/deploy/ and wire it into release.yml
+```
 
-Follow [Conventional Commits](https://www.conventionalcommits.org/) format. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full reference.
+Commands live in `.claude/commands/`. Rules live in `.cursor/rules/`.
 
 ## Contributing
 
-This repository is open to contributions. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for branch strategy, commit conventions, and the pull request process.
+Read [CONTRIBUTING.md](CONTRIBUTING.md) for branch strategy, commit conventions, and the PR process.
 
 ## Security
 
-To report a security vulnerability, please follow the process described in [SECURITY.md](SECURITY.md). Do not open a public issue.
+Report vulnerabilities privately — see [SECURITY.md](SECURITY.md). Do not open public issues.
 
 ## License
 
-This project is licensed under the Apache License 2.0 — see the [LICENSE](LICENSE) file for details.
+Apache License 2.0 — see [LICENSE](LICENSE).
diff --git a/docs/api-dog-e2e-tests-workflow.md b/docs/api-dog-e2e-tests-workflow.md
index 6bec353..e53861d 100644
--- a/docs/api-dog-e2e-tests-workflow.md
+++ b/docs/api-dog-e2e-tests-workflow.md
@@ -18,7 +18,7 @@ Reusable workflow for automated API testing using Apidog CLI. Runs test scenario
 
 ```yaml
 api-tests:
-  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/api-dog-e2e-tests.yml@main
+  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/api-dog-e2e-tests.yml@v1.0.0
   with:
     test_iterations: "1"
     output_formats: "html,cli"
@@ -31,7 +31,7 @@ api-tests:
 
 ```yaml
 api-tests:
-  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/api-dog-e2e-tests.yml@main
+  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/api-dog-e2e-tests.yml@v1.0.0
   with:
     auto_detect_environment: true
     secrets: inherit
@@ -56,13 +56,13 @@ jobs:
 
   update_gitops:
     needs: build
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@v1.0.0
     with:
       # ... gitops configuration ...
 
   e2e_tests:
     needs: update_gitops
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/api-dog-e2e-tests.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/api-dog-e2e-tests.yml@v1.0.0
     with:
       auto_detect_environment: true
       test_iterations: "3"
@@ -203,7 +203,7 @@ jobs:
 
   e2e_tests:
     needs: update_gitops
-    uses: ./.github/workflows/api-dog-e2e-tests.yml@main
+    uses: ./.github/workflows/api-dog-e2e-tests.yml@v1.0.0
 ```
 
 Ensures tests run after deployment is complete.
@@ -280,7 +280,7 @@ on:
 
 jobs:
   api-tests:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/api-dog-e2e-tests.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/api-dog-e2e-tests.yml@v1.0.0
     secrets: inherit
 ```
 
@@ -302,7 +302,7 @@ jobs:
 
   e2e_tests:
     needs: build_and_deploy
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/api-dog-e2e-tests.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/api-dog-e2e-tests.yml@v1.0.0
     with:
       auto_detect_environment: true
       test_iterations: "3"
@@ -321,13 +321,13 @@ on:
 
 jobs:
   test_dev:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/api-dog-e2e-tests.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/api-dog-e2e-tests.yml@v1.0.0
     with:
       test_iterations: "2"
     secrets: inherit
 
   test_stg:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/api-dog-e2e-tests.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/api-dog-e2e-tests.yml@v1.0.0
     with:
       test_iterations: "2"
     secrets: inherit
diff --git a/docs/branch-cleanup.md b/docs/branch-cleanup.md
new file mode 100644
index 0000000..3cd9bce
--- /dev/null
+++ b/docs/branch-cleanup.md
@@ -0,0 +1,113 @@
+# branch-cleanup
+
+Reusable workflow that keeps repositories clean by automatically deleting stale branches and removing branches after PR merges.
+
+## What it does
+
+| Mode | Trigger | Behavior |
+|---|---|---|
+| **Stale cleanup** | Schedule / manual dispatch / `workflow_call` | Scans all branches, deletes those with no commits for N days and no open PRs |
+| **Merged branch** | `workflow_call` with `merged_branch` input | Deletes the specified branch after a PR merge |
+
+Protected branches (`main`, `master`, `develop`, `release/*`, `hotfix/*`) and branches with GitHub branch protection rules are never deleted.
+
+## Inputs
+
+| Input | Type | Required | Default | Description |
+|---|---|:---:|---|---|
+| `stale_days` | `number` | No | `30` | Days without commits before a branch is stale |
+| `dry_run` | `boolean` | No | `false` | Preview deletions without applying them |
+| `protected_branches` | `string` | No | `main,master,develop,release/*,hotfix/*` | Comma-separated patterns to never delete |
+| `merged_branch` | `string` | No | `""` | Branch to delete (enables merged mode) |
+
+## Secrets
+
+| Secret | Required | Description |
+|---|---|---|
+| `GITHUB_TOKEN` | No | Defaults to the automatic token; needs `contents:write` and `pull-requests:read` |
+
+## Usage
+
+### Scheduled stale branch cleanup
+
+```yaml
+# .github/workflows/branch-cleanup.yml
+name: Branch Cleanup
+
+on:
+  schedule:
+    - cron: "0 6 * * 1"   # Every Monday at 06:00 UTC
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        type: boolean
+        default: false
+
+jobs:
+  cleanup:
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/branch-cleanup.yml@v1.0.0
+    with:
+      stale_days: 30
+      dry_run: ${{ inputs.dry_run || false }}
+    secrets: inherit
+```
+
+### Delete branch on PR merge
+
+```yaml
+# .github/workflows/delete-merged-branch.yml
+name: Delete Merged Branch
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  cleanup:
+    if: ${{ github.event.pull_request.merged }}
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/branch-cleanup.yml@v1.0.0
+    with:
+      merged_branch: ${{ github.head_ref }}
+    secrets: inherit
+```
+
+### Both in a single caller file
+
+```yaml
+name: Branch Cleanup
+
+on:
+  schedule:
+    - cron: "0 6 * * 1"
+  pull_request:
+    types: [closed]
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        type: boolean
+        default: false
+
+jobs:
+  stale:
+    if: ${{ github.event_name != 'pull_request' }}
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/branch-cleanup.yml@v1.0.0
+    with:
+      stale_days: 30
+      dry_run: ${{ inputs.dry_run || false }}
+    secrets: inherit
+
+  merged:
+    if: ${{ github.event_name == 'pull_request' && github.event.pull_request.merged }}
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/branch-cleanup.yml@v1.0.0
+    with:
+      merged_branch: ${{ github.head_ref }}
+    secrets: inherit
+```
+
+## Permissions
+
+```yaml
+permissions:
+  contents: write
+  pull-requests: read
+```
diff --git a/docs/build-workflow.md b/docs/build-workflow.md
index f7d38ea..5d83dec 100644
--- a/docs/build-workflow.md
+++ b/docs/build-workflow.md
@@ -24,7 +24,7 @@ on:
 
 jobs:
   build:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/build.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/build.yml@v1.0.0
     with:
       runner_type: "firmino-lxc-runners"
       enable_dockerhub: true
@@ -44,7 +44,7 @@ on:
 
 jobs:
   build:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/build.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/build.yml@v1.0.0
     with:
       runner_type: "firmino-lxc-runners"
       filter_paths: |-
@@ -71,7 +71,7 @@ on:
 
 jobs:
   build:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/build.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/build.yml@v1.0.0
     with:
       filter_paths: |-
         components/api
@@ -84,7 +84,7 @@ jobs:
   update_gitops:
     needs: [build]
     if: contains(github.ref, '-beta') || contains(github.ref, '-rc')
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@v1.0.0
     with:
       gitops_repository: "MyOrg/gitops-repo"
       artifact_pattern: "gitops-tags-myapp-*"
diff --git a/docs/changed-paths-workflow.md b/docs/changed-paths-workflow.md
index 1bb4d0d..405ca4b 100644
--- a/docs/changed-paths-workflow.md
+++ b/docs/changed-paths-workflow.md
@@ -24,7 +24,7 @@ on:
 
 jobs:
   detect-changes:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/changed-paths.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/changed-paths.yml@v1.0.0
 
   build:
     needs: detect-changes
@@ -48,7 +48,7 @@ on:
 
 jobs:
   detect-changes:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/changed-paths.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/changed-paths.yml@v1.0.0
     with:
       filter_paths: '["components/api", "components/web", "components/worker"]'
       path_level: 2
@@ -77,7 +77,7 @@ on:
 
 jobs:
   detect-changes:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/changed-paths.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/changed-paths.yml@v1.0.0
     with:
       filter_paths: '["components/onboarding", "components/transaction", "components/ledger"]'
       path_level: 2
@@ -163,7 +163,7 @@ Detects changed files and extracts unique directories with optional filtering.
 ```yaml
 jobs:
   changes:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/changed-paths.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/changed-paths.yml@v1.0.0
 ```
 
 ### Microservices Monorepo
@@ -171,7 +171,7 @@ jobs:
 ```yaml
 jobs:
   changes:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/changed-paths.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/changed-paths.yml@v1.0.0
     with:
       filter_paths: '["services/auth", "services/users", "services/orders", "services/payments"]'
       path_level: 2
@@ -184,7 +184,7 @@ jobs:
 ```yaml
 jobs:
   changes:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/changed-paths.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/changed-paths.yml@v1.0.0
     with:
       filter_paths: '["packages/ui", "packages/utils", "apps/web", "apps/mobile"]'
       path_level: 2
@@ -195,7 +195,7 @@ jobs:
 ```yaml
 jobs:
   detect:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/changed-paths.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/changed-paths.yml@v1.0.0
     with:
       filter_paths: '["src/backend"]'
 
@@ -221,7 +221,7 @@ The `path_level` input trims paths to the first N segments:
 
 ## Tips
 
-1. **Pin to a version tag**: Use `@v1.0.0` instead of `@main` for production stability
+1. **Pin to a version tag**: Use `@v1.0.0` instead of `@v1.0.0` for production stability
 2. **Use `has_changes` output**: Skip downstream jobs when no relevant changes are detected
 3. **Path level for consistency**: Use `path_level` to normalize paths to component directories
 4. **Filter early**: Use `filter_paths` to focus on relevant directories and reduce noise
diff --git a/docs/frontend-pr-analysis-workflow.md b/docs/frontend-pr-analysis-workflow.md
index 840e7ec..b1a0647 100644
--- a/docs/frontend-pr-analysis-workflow.md
+++ b/docs/frontend-pr-analysis-workflow.md
@@ -27,7 +27,7 @@ on:
 
 jobs:
   analysis:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/frontend-pr-analysis.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/frontend-pr-analysis.yml@v1.0.0
     secrets: inherit
 ```
 
@@ -41,7 +41,7 @@ on:
 
 jobs:
   analysis:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/frontend-pr-analysis.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/frontend-pr-analysis.yml@v1.0.0
     with:
       filter_paths: '["apps/web", "apps/console", "packages/ui"]'
     secrets: inherit
@@ -57,7 +57,7 @@ on:
 
 jobs:
   analysis:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/frontend-pr-analysis.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/frontend-pr-analysis.yml@v1.0.0
     with:
       filter_paths: '["apps/web", "apps/admin", "packages/shared"]'
       path_level: 2
@@ -82,7 +82,7 @@ jobs:
 ```yaml
 jobs:
   analysis:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/frontend-pr-analysis.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/frontend-pr-analysis.yml@v1.0.0
     with:
       filter_paths: '["src"]'
       enable_typecheck: false
@@ -97,7 +97,7 @@ jobs:
 ```yaml
 jobs:
   analysis:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/frontend-pr-analysis.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/frontend-pr-analysis.yml@v1.0.0
     with:
       package_manager: "yarn"
       node_version: "20"
@@ -109,7 +109,7 @@ jobs:
 ```yaml
 jobs:
   analysis:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/frontend-pr-analysis.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/frontend-pr-analysis.yml@v1.0.0
     with:
       package_manager: "pnpm"
       node_version: "22"
@@ -251,7 +251,7 @@ The workflow automatically adapts commands based on `package_manager`:
 
 ## Tips
 
-1. **Pin to version tag**: Use `@v1.0.0` instead of `@main` for production stability
+1. **Pin to version tag**: Use `@v1.0.0` instead of `@v1.0.0` for production stability
 2. **Custom ESLint config**: Place `.eslintrc` or `eslint.config.js` in each app directory for app-specific rules
 3. **Coverage threshold**: Start with `fail_on_coverage_threshold: false` and enable once baseline is established
 4. **Test framework**: Works with Jest, Vitest, or any test runner that outputs `coverage-summary.json`
diff --git a/docs/gitops-update-workflow.md b/docs/gitops-update-workflow.md
index 9cf5bed..80d5d6c 100644
--- a/docs/gitops-update-workflow.md
+++ b/docs/gitops-update-workflow.md
@@ -24,7 +24,7 @@ Reusable workflow for updating GitOps repository with new image tags across mult
 update_gitops:
   needs: build_backend
   if: needs.build_backend.result == 'success'
-  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@main
+  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@v1.0.0
   with:
     yaml_key_mappings: '{"backend.tag": ".auth.image.tag"}'
   secrets: inherit
@@ -47,7 +47,7 @@ update_gitops:
 update_gitops:
   needs: build_backend
   if: needs.build_backend.result == 'success'
-  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@main
+  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@v1.0.0
   with:
     deploy_in_firmino: true
     deploy_in_clotilde: false
@@ -61,7 +61,7 @@ update_gitops:
 update_gitops:
   needs: build_backend
   if: needs.build_backend.result == 'success'
-  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@main
+  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@v1.0.0
   with:
     deploy_in_firmino: false
     deploy_in_clotilde: true
@@ -75,7 +75,7 @@ update_gitops:
 update_gitops:
   needs: build
   if: needs.build.result == 'success'
-  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@main
+  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@v1.0.0
   with:
     app_name: "midaz"
     artifact_pattern: "gitops-tags-midaz-*"
@@ -243,7 +243,7 @@ This prevents unnecessary errors when an app hasn't been created in ArgoCD yet f
 **Before (single server):**
 ```yaml
 update_gitops:
-  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@main
+  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@v1.0.0
   with:
     gitops_server: 'firmino'
     gitops_file_dev: gitops/environments/firmino/helmfile/applications/dev/my-app/values.yaml
@@ -256,7 +256,7 @@ update_gitops:
 **After (multi-server):**
 ```yaml
 update_gitops:
-  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@main
+  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@v1.0.0
   with:
     app_name: 'my-app'
     deploy_in_firmino: true
diff --git a/docs/go-ci-workflow.md b/docs/go-ci-workflow.md
index 74d5908..4eaad11 100644
--- a/docs/go-ci-workflow.md
+++ b/docs/go-ci-workflow.md
@@ -28,7 +28,7 @@ on:
 
 jobs:
   ci:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@v1.0.0
 ```
 
 ### Custom Configuration
@@ -39,7 +39,7 @@ on: [push, pull_request]
 
 jobs:
   ci:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@v1.0.0
     with:
       go_versions: '["1.22", "1.23"]'
       operating_systems: '["ubuntu-latest", "macos-latest"]'
@@ -59,7 +59,7 @@ on: [push, pull_request]
 
 jobs:
   ci:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@v1.0.0
     with:
       enable_cross_platform_build: true
       build_path: './cmd/myapp'
@@ -125,7 +125,7 @@ Aggregate status check that fails if any required job fails.
 ```yaml
 jobs:
   ci:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@v1.0.0
 ```
 
 ### Only Latest Go Version
@@ -133,7 +133,7 @@ jobs:
 ```yaml
 jobs:
   ci:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@v1.0.0
     with:
       go_versions: '["1.23"]'
       operating_systems: '["ubuntu-latest"]'
@@ -144,14 +144,14 @@ jobs:
 ```yaml
 jobs:
   ci:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-ci.yml@v1.0.0
     with:
       check_docs: false
 ```
 
 ## Tips
 
-1. Pin to a version tag: Use `@v1.0.0` instead of `@main` for production stability
+1. Pin to a version tag: Use `@v1.0.0` instead of `@v1.0.0` for production stability
 2. golangci-lint config: Place `.golangci.yml` in your repo root for custom linting rules
 3. Custom build targets: Specify exact platforms you need to reduce build time
 4. Markdown link check: Add `.github/markdown-link-check-config.json` to configure link validation
diff --git a/docs/go-pr-analysis-workflow.md b/docs/go-pr-analysis-workflow.md
index f9ee72d..5ccc708 100644
--- a/docs/go-pr-analysis-workflow.md
+++ b/docs/go-pr-analysis-workflow.md
@@ -29,7 +29,7 @@ on:
 
 jobs:
   analysis:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-pr-analysis.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-pr-analysis.yml@v1.0.0
     secrets: inherit
 ```
 
@@ -43,7 +43,7 @@ on:
 
 jobs:
   analysis:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-pr-analysis.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-pr-analysis.yml@v1.0.0
     with:
       filter_paths: '["apps/api", "apps/worker", "apps/gateway"]'
     secrets: inherit
@@ -59,7 +59,7 @@ on:
 
 jobs:
   analysis:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-pr-analysis.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-pr-analysis.yml@v1.0.0
     with:
       filter_paths: '["apps/control-plane", "apps/agent", "apps/lambda-authorizer"]'
       path_level: 2
@@ -82,7 +82,7 @@ jobs:
 ```yaml
 jobs:
   analysis:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-pr-analysis.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-pr-analysis.yml@v1.0.0
     with:
       filter_paths: '["src/services"]'
       enable_security: false
@@ -115,7 +115,7 @@ jobs:
 ```yaml
 jobs:
   analysis:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-pr-analysis.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-pr-analysis.yml@v1.0.0
     with:
       filter_paths: '["components/api"]'
       go_private_modules: "github.com/MyOrg/*"
@@ -303,7 +303,7 @@ swagger.go
 
 ## Tips
 
-1. **Pin to version tag**: Use `@v1.0.0` instead of `@main` for production stability
+1. **Pin to version tag**: Use `@v1.0.0` instead of `@v1.0.0` for production stability
 2. **Custom linting**: Place `.golangci.yml` in each app directory for app-specific rules
 3. **Coverage threshold**: Start with `fail_on_coverage_threshold: false` and enable once baseline is established
 4. **Security findings**: GoSec results appear in GitHub Security tab when SARIF upload succeeds
diff --git a/docs/go-release-workflow.md b/docs/go-release-workflow.md
index 4ca0691..8733b1b 100644
--- a/docs/go-release-workflow.md
+++ b/docs/go-release-workflow.md
@@ -26,7 +26,7 @@ on:
 
 jobs:
   release:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@v1.0.0
 ```
 
 ### With Docker Publishing
@@ -40,7 +40,7 @@ on:
 
 jobs:
   release:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@v1.0.0
     with:
       enable_docker: true
       docker_registry: 'ghcr.io'
@@ -61,7 +61,7 @@ on:
 
 jobs:
   release:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@v1.0.0
     with:
       enable_homebrew: true
       homebrew_tap_repo: 'myorg/homebrew-tap'
@@ -81,7 +81,7 @@ on:
 
 jobs:
   release:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@v1.0.0
     with:
       go_version: '1.23'
       goreleaser_distribution: 'goreleaser'
@@ -146,7 +146,7 @@ Sends release notifications.
 ```yaml
 jobs:
   release:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@v1.0.0
 ```
 
 ### With GoReleaser Pro
@@ -154,7 +154,7 @@ jobs:
 ```yaml
 jobs:
   release:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@v1.0.0
     with:
       goreleaser_distribution: 'goreleaser-pro'
     secrets: inherit
@@ -167,7 +167,7 @@ jobs:
 ```yaml
 jobs:
   release:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@v1.0.0
     with:
       run_tests_before_release: false
 ```
@@ -186,7 +186,7 @@ jobs:
 ## Tips
 
 1. Test GoReleaser locally: `goreleaser release --snapshot --clean`
-2. Pin workflow version: Use `@v1.0.0` instead of `@main`
+2. Pin workflow version: Use `@v1.0.0` instead of `@v1.0.0`
 3. CHANGELOG: GoReleaser generates from commits and PRs
 4. Draft releases: Use GoReleaser's `draft: true` for manual approval
 5. Custom builds: Configure `.goreleaser.yml` for your needs
diff --git a/docs/go-security-workflow.md b/docs/go-security-workflow.md
index 52991f0..4259237 100644
--- a/docs/go-security-workflow.md
+++ b/docs/go-security-workflow.md
@@ -33,7 +33,7 @@ on:
 
 jobs:
   security:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-security.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-security.yml@v1.0.0
 ```
 
 ### Custom Configuration
@@ -44,7 +44,7 @@ on: [push, pull_request]
 
 jobs:
   security:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-security.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-security.yml@v1.0.0
     with:
       go_version: '1.23'
       enable_gosec: true
@@ -64,7 +64,7 @@ on: [push, pull_request]
 
 jobs:
   security:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-security.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-security.yml@v1.0.0
     with:
       # Only run critical scanners
       enable_gosec: true
@@ -135,7 +135,7 @@ Aggregate summary of all security scans.
 ```yaml
 jobs:
   security:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-security.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-security.yml@v1.0.0
 ```
 
 ### Critical Scanners Only
@@ -143,7 +143,7 @@ jobs:
 ```yaml
 jobs:
   security:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-security.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-security.yml@v1.0.0
     with:
       enable_gosec: true
       enable_govulncheck: true
@@ -159,7 +159,7 @@ jobs:
 ```yaml
 jobs:
   security:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-security.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-security.yml@v1.0.0
     with:
       fail_on_security_issues: false
 ```
@@ -177,12 +177,12 @@ on:
 
 jobs:
   security:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-security.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-security.yml@v1.0.0
 ```
 
 ## Tips
 
-1. Pin to version: Use `@v1.0.0` instead of `@main` for production
+1. Pin to version: Use `@v1.0.0` instead of `@v1.0.0` for production
 2. Scheduled scans: Run weekly to catch new vulnerabilities
 3. SARIF upload: Keep enabled to track issues in GitHub Security tab
 4. Selective scanning: Disable scanners you don't need to reduce run time
diff --git a/docs/gptchangelog-workflow.md b/docs/gptchangelog-workflow.md
index 769cbe6..2566ce3 100644
--- a/docs/gptchangelog-workflow.md
+++ b/docs/gptchangelog-workflow.md
@@ -57,7 +57,7 @@ permissions:
 jobs:
   changelog:
     if: github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success'
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@v1.0.0
     with:
       runner_type: "blacksmith-4vcpu-ubuntu-2404"
     secrets: inherit
@@ -82,7 +82,7 @@ permissions:
 
 jobs:
   changelog:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@v1.0.0
     with:
       runner_type: "blacksmith-4vcpu-ubuntu-2404"
     secrets: inherit
@@ -123,7 +123,7 @@ permissions:
 
 jobs:
   changelog:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@v1.0.0
     with:
       runner_type: "blacksmith"
       filter_paths: |-
@@ -178,12 +178,12 @@ on:
 
 jobs:
   release:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/release.yml@v1.0.0
     secrets: inherit
 
   changelog:
     needs: release
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@v1.0.0
     with:
       runner_type: "blacksmith"
     secrets: inherit
@@ -289,7 +289,7 @@ Run changelog generation after the release workflow:
 ```yaml
 changelog:
   needs: release
-  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@main
+  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@v1.0.0
   secrets: inherit
 ```
 
@@ -367,7 +367,7 @@ on:
 
 jobs:
   changelog:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@v1.0.0
     secrets: inherit
 ```
 
@@ -381,7 +381,7 @@ on:
 
 jobs:
   changelog:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@v1.0.0
     with:
       filter_paths: |-
         charts/agent
@@ -402,7 +402,7 @@ on:
 
 jobs:
   changelog:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@v1.0.0
     with:
       filter_paths: |-
         services/api
@@ -416,7 +416,7 @@ jobs:
 
 ```yaml
 changelog:
-  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@main
+  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gptchangelog.yml@v1.0.0
   with:
     openai_model: 'anthropic/claude-3.5-sonnet'
     max_context_tokens: '128000'
diff --git a/docs/labels-sync.md b/docs/labels-sync.md
new file mode 100644
index 0000000..9597bfc
--- /dev/null
+++ b/docs/labels-sync.md
@@ -0,0 +1,118 @@
+<table border="0" cellspacing="0" cellpadding="0">
+  <tr>
+    <td><img src="https://github.com/LerianStudio.png" width="72" alt="Lerian" /></td>
+    <td><h1>labels-sync</h1></td>
+  </tr>
+</table>
+
+Reusable workflow that syncs GitHub labels from a YAML definition file to a repository. Uses the [`src/config/labels-sync`](../src/config/labels-sync/README.md) composite action internally.
+
+## What it does
+
+Reads a `.github/labels.yml` file and applies its label definitions to the target repository — creating missing labels, updating colors and descriptions, and optionally deleting labels that are no longer in the file.
+
+## Inputs
+
+| Input | Type | Required | Default | Description |
+|---|---|:---:|---|---|
+| `config` | `string` | No | `.github/labels.yml` | Path to the labels YAML definition file |
+| `dry_run` | `boolean` | No | `false` | Preview changes without applying them |
+| `skip_delete` | `boolean` | No | `false` | Skip deletion of labels absent from the config |
+
+## Secrets
+
+| Secret | Required | Description |
+|---|---|---|
+| `GITHUB_TOKEN` | No | Defaults to the automatic token; needs `issues:write` |
+
+## Labels file format
+
+Create a `.github/labels.yml` in the caller repository:
+
+```yaml
+- name: bug
+  color: "d73a4a"
+  description: Something is not working as expected
+
+- name: enhancement
+  color: "a2eeef"
+  description: New feature or improvement request
+
+- name: documentation
+  color: "0e8a16"
+  description: Improvements or additions to documentation
+```
+
+## Usage
+
+### Sync on labels file change
+
+```yaml
+# .github/workflows/labels-sync.yml
+name: Sync Labels
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/labels.yml"
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        type: boolean
+        default: false
+
+jobs:
+  sync:
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/labels-sync.yml@v1.0.0
+    with:
+      dry_run: ${{ inputs.dry_run || false }}
+    secrets: inherit
+```
+
+### Dry run (preview only)
+
+```yaml
+# Use @develop or your feature branch to validate before releasing
+jobs:
+  preview:
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/labels-sync.yml@develop
+    with:
+      dry_run: true
+    secrets: inherit
+```
+
+### Sync without deleting unlisted labels
+
+```yaml
+jobs:
+  sync:
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/labels-sync.yml@v1.0.0
+    with:
+      skip_delete: true
+    secrets: inherit
+```
+
+### Custom labels file path
+
+```yaml
+jobs:
+  sync:
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/labels-sync.yml@v1.0.0
+    with:
+      config: ".github/custom-labels.yml"
+    secrets: inherit
+```
+
+## Permissions
+
+```yaml
+permissions:
+  issues: write
+  contents: read
+```
+
+## Self-use in this repository
+
+This repo uses `self-labels-sync.yml` as a thin entrypoint that calls this workflow via local path. Reusable workflows must not have autonomous push triggers — those belong in a dedicated `self-` file.
diff --git a/docs/pr-security-scan-workflow.md b/docs/pr-security-scan-workflow.md
index 24226b0..1034371 100644
--- a/docs/pr-security-scan-workflow.md
+++ b/docs/pr-security-scan-workflow.md
@@ -57,7 +57,7 @@ on:
 
 jobs:
   security-scan:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@v1.0.0
     with:
       runner_type: "blacksmith-4vcpu-ubuntu-2404"
       dockerhub_org: "lerianstudio"
@@ -74,7 +74,7 @@ on:
 
 jobs:
   security-scan:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@v1.0.0
     with:
       runner_type: "blacksmith-4vcpu-ubuntu-2404"
       filter_paths: |-
@@ -96,7 +96,7 @@ on:
 
 jobs:
   security-scan:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@v1.0.0
     with:
       runner_type: "blacksmith-4vcpu-ubuntu-2404"
       filter_paths: |-
@@ -125,7 +125,7 @@ on:
 
 jobs:
   security-scan:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@v1.0.0
     with:
       runner_type: "blacksmith-4vcpu-ubuntu-2404"
       enable_docker_scan: false
@@ -359,7 +359,7 @@ with:
 
 ```yaml
 security-scan:
-  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@main
+  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@v1.0.0
   with:
     dockerhub_org: "mycompany"
     docker_registry: "ghcr.io"
@@ -372,7 +372,7 @@ security-scan:
 
 ```yaml
 security-scan:
-  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@main
+  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@v1.0.0
   with:
     runner_type: "blacksmith-4vcpu-ubuntu-2404"
     filter_paths: |-
@@ -389,7 +389,7 @@ security-scan:
 
 ```yaml
 security-scan:
-  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@main
+  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@v1.0.0
   with:
     runner_type: "blacksmith-4vcpu-ubuntu-2404"
     filter_paths: |-
@@ -434,7 +434,7 @@ jobs:
         run: make test
 
   security-scan:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@v1.0.0
     with:
       runner_type: "blacksmith-4vcpu-ubuntu-2404"
       filter_paths: |-
diff --git a/docs/pr-validation-workflow.md b/docs/pr-validation-workflow.md
index 7de8e00..988503b 100644
--- a/docs/pr-validation-workflow.md
+++ b/docs/pr-validation-workflow.md
@@ -34,7 +34,7 @@ permissions:
 
 jobs:
   validate:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-validation.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-validation.yml@v1.0.0
 ```
 
 ### Custom Configuration
@@ -54,7 +54,7 @@ permissions:
 
 jobs:
   validate:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-validation.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-validation.yml@v1.0.0
     with:
       pr_title_types: |
         feat
@@ -80,7 +80,7 @@ jobs:
 ```yaml
 jobs:
   validate:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-validation.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-validation.yml@v1.0.0
     with:
       pr_title_scopes: |
         auth
@@ -262,7 +262,7 @@ Encourages linking PRs to issues using keywords:
 ```yaml
 jobs:
   validate:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-validation.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-validation.yml@v1.0.0
 ```
 
 ### Strict Validation
@@ -270,7 +270,7 @@ jobs:
 ```yaml
 jobs:
   validate:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-validation.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-validation.yml@v1.0.0
     with:
       require_scope: true
       min_description_length: 100
@@ -282,7 +282,7 @@ jobs:
 ```yaml
 jobs:
   validate:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-validation.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-validation.yml@v1.0.0
     with:
       enable_auto_labeler: false
 ```
@@ -294,7 +294,7 @@ Enforce that PRs to `main` only come from `develop`, `release-candidate`, or `ho
 ```yaml
 jobs:
   validate:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-validation.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-validation.yml@v1.0.0
     with:
       enforce_source_branches: true
       allowed_source_branches: 'develop|release-candidate|hotfix/*'
@@ -307,7 +307,7 @@ jobs:
 ```yaml
 jobs:
   validate:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-validation.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-validation.yml@v1.0.0
     with:
       pr_title_types: |
         feature
diff --git a/docs/release-workflow.md b/docs/release-workflow.md
index 13750d5..c7e3fc5 100644
--- a/docs/release-workflow.md
+++ b/docs/release-workflow.md
@@ -26,7 +26,7 @@ on:
 
 jobs:
   release:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/release.yml@v1.0.0
     secrets: inherit
 ```
 
@@ -36,7 +36,7 @@ jobs:
 
 ```yaml
 release:
-  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/release.yml@main
+  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/release.yml@v1.0.0
   with:
     runner_type: "blacksmith-4vcpu-ubuntu-2404"
     semantic_version: "23.0.8"
@@ -73,7 +73,7 @@ jobs:
 
   release:
     needs: tests
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/release.yml@v1.0.0
     secrets: inherit
 ```
 
@@ -399,7 +399,7 @@ on:
 
 jobs:
   release:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/release.yml@v1.0.0
     secrets: inherit
 ```
 
@@ -420,7 +420,7 @@ jobs:
 
   release:
     needs: test
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/release.yml@v1.0.0
     secrets: inherit
 
   build:
@@ -443,7 +443,7 @@ on:
 
 jobs:
   release:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/release.yml@v1.0.0
     secrets: inherit
 ```
 
diff --git a/docs/slack-notify-workflow.md b/docs/slack-notify-workflow.md
index 0d15ef5..fdc85e6 100644
--- a/docs/slack-notify-workflow.md
+++ b/docs/slack-notify-workflow.md
@@ -25,7 +25,7 @@ jobs:
   notify:
     needs: [build]
     if: always()
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/slack-notify.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/slack-notify.yml@v1.0.0
     with:
       status: ${{ needs.build.result }}
       workflow_name: "Build Pipeline"
@@ -49,7 +49,7 @@ jobs:
   notify:
     needs: [lint, test]
     if: always()
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/slack-notify.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/slack-notify.yml@v1.0.0
     with:
       status: ${{ needs.lint.result == 'failure' && 'failure' || needs.test.result }}
       workflow_name: "CI Pipeline"
@@ -61,7 +61,7 @@ jobs:
 
 ```yaml
 notify:
-  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/slack-notify.yml@main
+  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/slack-notify.yml@v1.0.0
   with:
     status: "success"
     workflow_name: "Release"
@@ -73,7 +73,7 @@ notify:
 
 ```yaml
 notify:
-  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/slack-notify.yml@main
+  uses: LerianStudio/github-actions-shared-workflows/.github/workflows/slack-notify.yml@v1.0.0
   with:
     status: ${{ needs.build.result }}
     workflow_name: "Build"
diff --git a/docs/typescript-release-workflow.md b/docs/typescript-release-workflow.md
index 51e9430..06558a6 100644
--- a/docs/typescript-release-workflow.md
+++ b/docs/typescript-release-workflow.md
@@ -51,7 +51,7 @@ permissions:
 jobs:
   release:
     name: Create Release
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/typescript-release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/typescript-release.yml@v1.0.0
     secrets: inherit
 ```
 
@@ -60,7 +60,7 @@ jobs:
 ```yaml
 jobs:
   release:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/typescript-release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/typescript-release.yml@v1.0.0
     with:
       runner_type: "blacksmith-4vcpu-ubuntu-2404"
       node_version: "22"
@@ -72,7 +72,7 @@ jobs:
 ```yaml
 jobs:
   release:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/typescript-release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/typescript-release.yml@v1.0.0
     with:
       dry_run: true
     secrets: inherit
@@ -85,7 +85,7 @@ This runs semantic-release without creating tags, GitHub releases, or pushing co
 ```yaml
 jobs:
   release:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/typescript-release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/typescript-release.yml@v1.0.0
     with:
       filter_paths: |
         apps/api
@@ -121,7 +121,7 @@ jobs:
 
   release:
     needs: test
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/typescript-release.yml@main
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/typescript-release.yml@v1.0.0
     with:
       runner_type: "blacksmith-4vcpu-ubuntu-2404"
       node_version: "20"
diff --git a/src/config/branch-cleanup/README.md b/src/config/branch-cleanup/README.md
new file mode 100644
index 0000000..e9cfd63
--- /dev/null
+++ b/src/config/branch-cleanup/README.md
@@ -0,0 +1,75 @@
+<table border="0" cellspacing="0" cellpadding="0">
+  <tr>
+    <td><img src="https://github.com/LerianStudio.png" width="72" alt="Lerian" /></td>
+    <td><h1>branch-cleanup</h1></td>
+  </tr>
+</table>
+
+Composite action that deletes stale branches (no commits for N days, no open PRs) and removes branches after PR merges. Protected branches and branches with GitHub protection rules are never deleted.
+
+## Inputs
+
+| Input | Description | Required | Default |
+|---|---|:---:|---|
+| `github-token` | GitHub token with `contents:write` and `pull-requests:read` | Yes | — |
+| `stale-days` | Days without commits before a branch is stale | No | `30` |
+| `dry-run` | Preview deletions without applying them | No | `false` |
+| `protected-branches` | Comma-separated branch patterns to never delete | No | `main,master,develop,release/*,hotfix/*` |
+| `merged-branch` | Branch to delete (enables merged-branch mode) | No | `""` |
+
+## Usage
+
+### As a composite action (stale scan)
+
+```yaml
+# Use @develop or your feature branch to test before releasing
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: LerianStudio/github-actions-shared-workflows/src/config/branch-cleanup@develop
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          stale-days: "30"
+          dry-run: "true"
+```
+
+### As a composite action (merged branch)
+
+```yaml
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: LerianStudio/github-actions-shared-workflows/src/config/branch-cleanup@v1.0.0
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          merged-branch: ${{ github.head_ref }}
+```
+
+### As a reusable workflow (recommended)
+
+```yaml
+jobs:
+  cleanup:
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/branch-cleanup.yml@v1.0.0
+    with:
+      stale_days: 30
+      dry_run: true
+    secrets: inherit
+```
+
+## Permissions required
+
+```yaml
+permissions:
+  contents: write
+  pull-requests: read
+```
diff --git a/src/config/branch-cleanup/action.yml b/src/config/branch-cleanup/action.yml
new file mode 100644
index 0000000..2b04c79
--- /dev/null
+++ b/src/config/branch-cleanup/action.yml
@@ -0,0 +1,164 @@
+name: Branch Cleanup
+description: Deletes stale branches with no open PRs, or a specific merged branch.
+
+inputs:
+  github-token:
+    description: GitHub token with contents:write and pull-requests:read permissions
+    required: true
+  stale-days:
+    description: Days without commits before a branch is considered stale
+    required: false
+    default: "30"
+  dry-run:
+    description: Preview deletions without applying them
+    required: false
+    default: "false"
+  protected-branches:
+    description: Comma-separated branch patterns to never delete
+    required: false
+    default: "main,master,develop,release/*,hotfix/*"
+  merged-branch:
+    description: Specific branch to delete (merged-branch mode — skips stale scan)
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    - name: Delete merged branch
+      if: ${{ inputs.merged-branch != '' }}
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.github-token }}
+        MERGED_BRANCH: ${{ inputs.merged-branch }}
+        DRY_RUN: ${{ inputs.dry-run }}
+        PROTECTED_BRANCHES: ${{ inputs.protected-branches }}
+      run: |
+        is_protected() {
+          local branch="$1"
+          IFS=',' read -ra patterns <<< "$PROTECTED_BRANCHES"
+          for pattern in "${patterns[@]}"; do
+            pattern=$(echo "$pattern" | xargs)
+            # shellcheck disable=SC2254
+            case "$branch" in $pattern) return 0 ;; esac
+          done
+          return 1
+        }
+
+        if is_protected "$MERGED_BRANCH"; then
+          echo "::warning::Branch '$MERGED_BRANCH' matches a protected pattern — skipping"
+          exit 0
+        fi
+
+        if [[ "$DRY_RUN" == "true" ]]; then
+          echo "::notice::DRY RUN — would delete merged branch '$MERGED_BRANCH'"
+          exit 0
+        fi
+
+        echo "Deleting merged branch '$MERGED_BRANCH'..."
+        gh api -X DELETE "repos/${{ github.repository }}/git/refs/heads/${MERGED_BRANCH}" \
+          && echo "::notice::Deleted merged branch '$MERGED_BRANCH'" \
+          || echo "::warning::Branch '$MERGED_BRANCH' not found or already deleted"
+
+    - name: Scan and delete stale branches
+      if: ${{ inputs.merged-branch == '' }}
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.github-token }}
+        STALE_DAYS: ${{ inputs.stale-days }}
+        DRY_RUN: ${{ inputs.dry-run }}
+        PROTECTED_BRANCHES: ${{ inputs.protected-branches }}
+      run: |
+        is_protected() {
+          local branch="$1"
+          IFS=',' read -ra patterns <<< "$PROTECTED_BRANCHES"
+          for pattern in "${patterns[@]}"; do
+            pattern=$(echo "$pattern" | xargs)
+            # shellcheck disable=SC2254
+            case "$branch" in $pattern) return 0 ;; esac
+          done
+          return 1
+        }
+
+        cutoff_date=$(date -u -d "$STALE_DAYS days ago" +%Y-%m-%dT%H:%M:%SZ)
+        echo "Cutoff date: $cutoff_date (branches with no commits after this are stale)"
+
+        deleted=0
+        skipped=0
+        protected_count=0
+        has_pr=0
+        page=1
+
+        while :; do
+          branches=$(gh api "repos/${{ github.repository }}/branches?per_page=100&page=${page}" \
+            --jq '.[].name' 2>/dev/null)
+          [[ -z "$branches" ]] && break
+
+          while IFS= read -r branch; do
+            if is_protected "$branch"; then
+              protected_count=$((protected_count + 1))
+              continue
+            fi
+
+            # Check if branch has GitHub branch protection rules
+            status_code=$(gh api -i "repos/${{ github.repository }}/branches/${branch}/protection" \
+              2>/dev/null | head -1 | awk '{print $2}')
+            if [[ "$status_code" == "200" ]]; then
+              protected_count=$((protected_count + 1))
+              [[ "$DRY_RUN" == "true" ]] && echo "  [protected-rule] $branch"
+              continue
+            fi
+
+            # Get last commit date
+            last_commit_date=$(gh api "repos/${{ github.repository }}/commits?sha=${branch}&per_page=1" \
+              --jq '.[0].commit.committer.date' 2>/dev/null)
+
+            if [[ -z "$last_commit_date" ]]; then
+              skipped=$((skipped + 1))
+              continue
+            fi
+
+            if [[ "$last_commit_date" > "$cutoff_date" ]]; then
+              skipped=$((skipped + 1))
+              [[ "$DRY_RUN" == "true" ]] && echo "  [active] $branch (last commit: $last_commit_date)"
+              continue
+            fi
+
+            # Check for open PRs using this branch as head
+            open_prs=$(gh api "repos/${{ github.repository }}/pulls?state=open&head=${{ github.repository_owner }}:${branch}&per_page=1" \
+              --jq 'length' 2>/dev/null)
+
+            if [[ "$open_prs" -gt 0 ]]; then
+              has_pr=$((has_pr + 1))
+              [[ "$DRY_RUN" == "true" ]] && echo "  [has-pr] $branch (last commit: $last_commit_date)"
+              continue
+            fi
+
+            if [[ "$DRY_RUN" == "true" ]]; then
+              echo "  [stale] $branch (last commit: $last_commit_date) — would delete"
+              deleted=$((deleted + 1))
+            else
+              if gh api -X DELETE "repos/${{ github.repository }}/git/refs/heads/${branch}" 2>/dev/null; then
+                echo "  Deleted: $branch (last commit: $last_commit_date)"
+                deleted=$((deleted + 1))
+              else
+                echo "::warning::Failed to delete branch '$branch'"
+              fi
+            fi
+          done <<< "$branches"
+
+          page=$((page + 1))
+        done
+
+        echo ""
+        echo "--- Summary ---"
+        echo "Protected : $protected_count"
+        echo "Active    : $skipped"
+        echo "Has PR    : $has_pr"
+        if [[ "$DRY_RUN" == "true" ]]; then
+          echo "To delete : $deleted"
+          echo "::notice::DRY RUN complete — $deleted branch(es) would be deleted"
+        else
+          echo "Deleted   : $deleted"
+          echo "::notice::Stale branch cleanup complete — $deleted branch(es) deleted"
+        fi
diff --git a/src/config/labels-sync/README.md b/src/config/labels-sync/README.md
new file mode 100644
index 0000000..ff0b9a0
--- /dev/null
+++ b/src/config/labels-sync/README.md
@@ -0,0 +1,108 @@
+<table border="0" cellspacing="0" cellpadding="0">
+  <tr>
+    <td><img src="https://github.com/LerianStudio.png" width="72" alt="Lerian" /></td>
+    <td><h1>labels-sync</h1></td>
+  </tr>
+</table>
+
+Composite action that syncs GitHub labels from a YAML definition file to a repository. Wraps [crazy-max/ghaction-github-labeler](https://github.com/crazy-max/ghaction-github-labeler).
+
+## Inputs
+
+| Input | Description | Required | Default |
+|---|---|:---:|---|
+| `github-token` | GitHub token with `issues:write` permission | Yes | — |
+| `config` | Path to the labels YAML definition file | No | `.github/labels.yml` |
+| `dry-run` | Preview changes without applying them | No | `false` |
+| `skip-delete` | Skip deletion of labels absent from the config | No | `false` |
+
+## Labels file format
+
+Create a `.github/labels.yml` in the target repository:
+
+```yaml
+- name: bug
+  color: "d73a4a"
+  description: Something is not working as expected
+
+- name: enhancement
+  color: "a2eeef"
+  description: New feature or improvement request
+
+- name: documentation
+  color: "0e8a16"
+  description: Improvements or additions to documentation
+```
+
+## Usage
+
+### As a composite action (inline step)
+
+```yaml
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      contents: read
+    steps:
+      - uses: LerianStudio/github-actions-shared-workflows/src/config/labels-sync@v1.0.0
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### As a reusable workflow (recommended)
+
+```yaml
+jobs:
+  sync:
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/labels-sync.yml@v1.0.0
+    with:
+      dry_run: false
+    secrets: inherit
+```
+
+### Dry run (preview only)
+
+```yaml
+# Use @develop or your feature branch to test before releasing
+- uses: LerianStudio/github-actions-shared-workflows/src/config/labels-sync@develop
+  with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    dry-run: "true"
+```
+
+### Sync without deleting unlisted labels
+
+```yaml
+- uses: LerianStudio/github-actions-shared-workflows/src/config/labels-sync@v1.0.0
+  with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    skip-delete: "true"
+```
+
+## Permissions required
+
+```yaml
+permissions:
+  issues: write
+  contents: read
+```
+
+## When to run
+
+The recommended trigger pattern is to run automatically on changes to the labels file, with a manual fallback for the initial setup:
+
+```yaml
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/labels.yml"
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        type: boolean
+        default: false
+```
diff --git a/src/config/labels-sync/action.yml b/src/config/labels-sync/action.yml
new file mode 100644
index 0000000..84bb8f6
--- /dev/null
+++ b/src/config/labels-sync/action.yml
@@ -0,0 +1,33 @@
+name: Labels Sync
+description: Syncs GitHub labels from a YAML definition file using crazy-max/ghaction-github-labeler.
+
+inputs:
+  github-token:
+    description: GitHub token with issues:write permission
+    required: true
+  config:
+    description: Path to the labels YAML definition file
+    required: false
+    default: .github/labels.yml
+  dry-run:
+    description: Preview changes without applying them
+    required: false
+    default: "false"
+  skip-delete:
+    description: Skip deletion of labels not present in the config file
+    required: false
+    default: "false"
+
+runs:
+  using: composite
+  steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Sync labels
+      uses: crazy-max/ghaction-github-labeler@v5
+      with:
+        github-token: ${{ inputs.github-token }}
+        config: ${{ inputs.config }}
+        dry-run: ${{ inputs.dry-run }}
+        skip-delete: ${{ inputs.skip-delete }}