This is actually better than Option C as originally conceived. Komodo has a proper API client with a `DeployStack` execute endpoint — meaning the workflow doesn't need to construct webhook URLs at all. It can just call the Komodo API directly by stack name.

There's even a GitHub Marketplace action (`komodoactions`) that wraps this exact pattern — API key + secret + stack name → deploy. That's compatible with Gitea Actions.

Here's the plan document to commit before the Claude Code session:

---

**`documentation/plans/plan-autoDeployEnrichment.md`**

```markdown
# Plan: Auto-Deploy Enrichment (Option C — Komodo API)

## Status
Planned. Runner setup in progress. Do not start Claude Code session until 
the Gitea Actions runner is registered on Heimdall.

## Goal
When a PR is merged to main in the homelab repo, automatically trigger a 
redeploy in Komodo for each stack whose files changed — with no static 
webhook map to maintain.

## Approach
Use the Komodo REST API (DeployStack execute endpoint) instead of per-stack 
webhook URLs. The workflow detects changed stack folders, extracts the stack 
name, and calls Komodo directly by name. New stacks just work.

## Why not the static webhook map (Option A)
Every new stack requires a manual workflow edit and a new Komodo webhook URL 
to be copied. With ~30 stacks today and more coming, this is maintenance 
overhead that compounds over time.

## Why not the JSON secret (Option B)
Still manual — just moves the map from the workflow file into a Gitea secret. 
Doesn't eliminate the problem.

## Architecture

### Trigger
Push to main branch of the homelab repo.

### Path detection
Same logic as the existing workflow draft:
- Parse changed file paths for `nodes/{node}/{stack}/` pattern
- Extract stack name, deduplicate

### Komodo API call
Instead of POSTing to a webhook URL, the workflow calls:
```
POST https://komodo.castaldifamily.com/execute/DeployStack
Body: { "stack": "<stack-name>" }
Headers: X-Api-Key, X-Api-Secret
```

Stack name must exactly match the Komodo stack name. The folder name in the 
homelab repo is used as the stack name — these should stay in sync.

### Secrets required (Gitea repo settings)
| Secret | Value |
|---|---|
| KOMODO_URL | https://komodo.castaldifamily.com |
| KOMODO_API_KEY | From Komodo UI → Settings → Users → (service user) → Api Keys |
| KOMODO_API_SECRET | Same location — copy at creation, not shown again |

### Service user setup (Komodo)
Create a dedicated service user for CI with minimal permissions:
- Stack: Execute (Deploy only)
- No write/delete permissions
- Settings → Users → New User (type: Service)

## What the workflow replaces
The existing `.gitea/workflows/auto-deploy.yml` draft (static webhook map 
with TODO entries). That file should be replaced entirely.

## Claude Code session prompt

```
Read the following files before making any changes:
- .gitea/workflows/auto-deploy.yml  (the existing draft to replace)
- documentation/plans/plan-autoDeployEnrichment.md
- README.md

## Context
We are replacing the static webhook map workflow with one that calls the 
Komodo API directly using DeployStack. Stack name is inferred from the 
changed file path (nodes/{node}/{stack}/ → stack name).

## Task

### Step 1 — Confirm Komodo API endpoint
The expected endpoint is:
  POST https://komodo.castaldifamily.com/execute/DeployStack
  Body: { "stack": "<name>" }
  Headers: X-Api-Key: <key>, X-Api-Secret: <secret>

Before writing the workflow, confirm this matches the Komodo API docs 
by checking: https://komo.do/docs/ecosystem/api
Show me the exact curl command you'll use in the workflow.

### Step 2 — Rewrite the workflow
Replace .gitea/workflows/auto-deploy.yml with a new version that:
- Detects changed paths using the same nodes/{node}/{stack}/ logic
- Calls the Komodo DeployStack API for each changed stack by name
- Uses secrets: KOMODO_URL, KOMODO_API_KEY, KOMODO_API_SECRET
- Logs each stack triggered and its HTTP response code
- Fails with exit 1 if any API call returns non-2xx
- Handles the case where a stack name in the repo has no match in Komodo
  gracefully (warn, don't fail — the stack may not be registered yet)

### Step 3 — Update SOP-003
Update documentation/SOPs/SOP-003-Gitea-Actions-Runner-Setup.md to 
replace the KOMODO_WEBHOOK_SECRET secret with the three new secrets:
KOMODO_URL, KOMODO_API_KEY, KOMODO_API_SECRET.
Add a note on creating the Komodo service user with minimal permissions.

### Step 4 — Update README
Reflect the new secret names in the Auto-Deploy section.

## Constraints
- Do not touch compose files or .env files
- Show me the final workflow YAML before writing it to disk
- Run no tests (this repo has no test suite)
```

## Prerequisites before running Claude Code session
1. Gitea Actions runner registered on Heimdall (see SOP-003)
2. Komodo service user created with Stack Execute permissions
3. API key + secret copied and ready to add as Gitea secrets
4. Confirm stack names in homelab repo match stack names in Komodo UI
```

---

Commit that to `documentation/plans/plan-autoDeployEnrichment.md` and you're ready for the next session. The runner setup is still the blocker — nothing else can be tested until that's in place.