From d801c9972c7ab4b533f17622cc2b59dc71fe8e91 Mon Sep 17 00:00:00 2001
From: "arunim2@gmail.com" <arunim2@gmail.com@users.noreply.github.com>
Date: Thu, 22 Oct 2026 10:34:24 +0000
Subject: [PATCH] chore: sync skills from sg-clickhouse-mcp@ed30e3c

---
 skills/sg-manage-roles/SKILL.md               | 148 +++++
 .../SKILL.md                                  | 178 ++++++
 .../examples/README.md                        |  23 +
 .../examples/approvals.tf                     |  63 ++
 .../examples/config_rules.tf                  | 109 ++++
 .../examples/network_guardrails.tf            |  64 ++
 .../examples/no_public_s3.tf                  |  68 ++
 .../examples/opa_and_marketplace.tf           |  70 +++
 .../examples/required_tags.tf                 |  61 ++
 .../examples/versions.tf                      |  17 +
 .../references/schema.md                      |  57 ++
 .../references/sources-and-lifecycle.md       | 212 +++++++
 .../references/tirith.md                      | 197 ++++++
 .../SKILL.md                                  | 124 ++++
 .../examples/groups.tf                        |  54 ++
 .../examples/versions.tf                      |  17 +
 .../SKILL.md                                  | 217 +++++++
 .../examples/README.md                        |  21 +
 .../examples/automation_opentofu.tf           |  98 +++
 .../examples/custom_steps.tf                  | 148 +++++
 .../examples/git_terraform.tf                 |  94 +++
 .../examples/git_vcs_triggers.tf              |  51 ++
 .../examples/outputs_and_references.tf        |  75 +++
 .../examples/own_template.tf                  | 130 ++++
 .../examples/versions.tf                      |  17 +
 .../references/automation-and-outputs.md      | 189 ++++++
 .../references/discovery.md                   |  59 ++
 .../references/execution.md                   | 244 ++++++++
 .../references/lifecycle.md                   | 163 +++++
 .../references/schema.md                      | 588 ++++++++++++++++++
 .../references/sources-and-templates.md       | 234 +++++++
 31 files changed, 3790 insertions(+)
 create mode 100644 skills/sg-manage-roles/SKILL.md
 create mode 100644 skills/sg-writing-stackguardian-policy-terraform/SKILL.md
 create mode 100644 skills/sg-writing-stackguardian-policy-terraform/examples/README.md
 create mode 100644 skills/sg-writing-stackguardian-policy-terraform/examples/approvals.tf
 create mode 100644 skills/sg-writing-stackguardian-policy-terraform/examples/config_rules.tf
 create mode 100644 skills/sg-writing-stackguardian-policy-terraform/examples/network_guardrails.tf
 create mode 100644 skills/sg-writing-stackguardian-policy-terraform/examples/no_public_s3.tf
 create mode 100644 skills/sg-writing-stackguardian-policy-terraform/examples/opa_and_marketplace.tf
 create mode 100644 skills/sg-writing-stackguardian-policy-terraform/examples/required_tags.tf
 create mode 100644 skills/sg-writing-stackguardian-policy-terraform/examples/versions.tf
 create mode 100644 skills/sg-writing-stackguardian-policy-terraform/references/schema.md
 create mode 100644 skills/sg-writing-stackguardian-policy-terraform/references/sources-and-lifecycle.md
 create mode 100644 skills/sg-writing-stackguardian-policy-terraform/references/tirith.md
 create mode 100644 skills/sg-writing-stackguardian-workflow-group-terraform/SKILL.md
 create mode 100644 skills/sg-writing-stackguardian-workflow-group-terraform/examples/groups.tf
 create mode 100644 skills/sg-writing-stackguardian-workflow-group-terraform/examples/versions.tf
 create mode 100644 skills/sg-writing-stackguardian-workflow-terraform/SKILL.md
 create mode 100644 skills/sg-writing-stackguardian-workflow-terraform/examples/README.md
 create mode 100644 skills/sg-writing-stackguardian-workflow-terraform/examples/automation_opentofu.tf
 create mode 100644 skills/sg-writing-stackguardian-workflow-terraform/examples/custom_steps.tf
 create mode 100644 skills/sg-writing-stackguardian-workflow-terraform/examples/git_terraform.tf
 create mode 100644 skills/sg-writing-stackguardian-workflow-terraform/examples/git_vcs_triggers.tf
 create mode 100644 skills/sg-writing-stackguardian-workflow-terraform/examples/outputs_and_references.tf
 create mode 100644 skills/sg-writing-stackguardian-workflow-terraform/examples/own_template.tf
 create mode 100644 skills/sg-writing-stackguardian-workflow-terraform/examples/versions.tf
 create mode 100644 skills/sg-writing-stackguardian-workflow-terraform/references/automation-and-outputs.md
 create mode 100644 skills/sg-writing-stackguardian-workflow-terraform/references/discovery.md
 create mode 100644 skills/sg-writing-stackguardian-workflow-terraform/references/execution.md
 create mode 100644 skills/sg-writing-stackguardian-workflow-terraform/references/lifecycle.md
 create mode 100644 skills/sg-writing-stackguardian-workflow-terraform/references/schema.md
 create mode 100644 skills/sg-writing-stackguardian-workflow-terraform/references/sources-and-templates.md

diff --git a/skills/sg-manage-roles/SKILL.md b/skills/sg-manage-roles/SKILL.md
new file mode 100644
index 0000000..8b0fe43
--- /dev/null
+++ b/skills/sg-manage-roles/SKILL.md
@@ -0,0 +1,148 @@
+---
+name: sg-manage-roles
+description: Guided flow for creating, changing and deleting StackGuardian custom roles with the create_role / update_role / delete_role tools — turning "let team X read/run workflows in group Y" into the right permission names and scopes. Use when the user wants a new role, wants to widen or narrow what a role can do, asks why a role grants nothing, or wants to retire a role.
+---
+
+# Manage Roles — Guided Flow
+
+A StackGuardian **role** is a named bundle of **permissions**. Each permission
+is one platform capability (`GetWorkflow`, `CreateWorkflowRun`, ...) plus a
+**scope**: for every placeholder the permission carries, a list of full-match
+regex **patterns** over resource IDS. Five **predefined roles** (ADMIN, DEV,
+SEC, OPS, READ_ONLY) are code and cannot be changed; everything else is a
+**custom role**. Roles are allow-only and additive — a user with several
+roles gets the union. Only ADMIN can manage roles. Follow the steps IN ORDER.
+Never surface parameter names like `resourceName` or `<wfGrp>` to the user;
+say "the role's name", "workflow group".
+
+**What these tools can't do — say so up front, before building anything:**
+they can't list users, look up a person, assign a role to anyone, or show a
+role's current permissions. "Give Alice read access to group X" ends with
+the user assigning the role in the dashboard's Access Management, and any
+change to an existing role needs its current patterns from the user.
+
+## The rules that make a role silently wrong
+
+1. **Patterns match IDS, not display names.** The scope is matched against
+   the URL segment, and an id can differ from the name: a group created in
+   the dashboard as `gitops` may have the id `gitops-y8pf2mb1`. A pattern
+   `gitops` would then save fine and grant nothing. Look every named group,
+   workflow, connector, policy or secret up with
+   `search_orchestrator_resources` and use the last segment of its
+   `ResourceId`. A NESTED group is its full id-path: the ids after each
+   `/wfgrps/` in its `ParentId`, then its own id, joined by `/`
+   (`company-x1/team-y2`). The bare leaf grants nothing on it, and would
+   match an unrelated top-level group of that id. Roles created by
+   `create_role` have id = name.
+2. **Patterns are full-match, anchors implicit.** `team-a` grants exactly
+   `team-a`; write `team-a-.*` for a prefix. Never `^` or `$` — the platform
+   strips them from anywhere, so `[^/]+` would invert. No inline flags
+   (`(?i)`), named groups, backreferences, nested repetition
+   (`(?:x+)+`) or big counted repeats (`a{5000}`): the tool refuses them.
+3. **GET on a group path grants every ancestor, no descendants.**
+   `company/team` also grants `company`, never `company/team/project`. The
+   platform splits a group pattern at each `/`, so a `/` may only separate
+   whole segments: not inside `[...]` or `(...)`, and not with a top-level
+   `|` (use one row per path).
+4. **Root-level Create* patterns match a NAME; CreateNestedWorkflowGroup
+   matches a PATH** (`parent/child-.*`).
+5. **User management matches a principal** via `<loginType>` (local|sso)
+   and `<principalId>` (an email pattern like `.*@example\.com`, or an SSO
+   group name). `<entityType>` must be `.*`: the platform ignores it, so
+   `group` would not keep email users out. It also needs `GetRole` scoped
+   to the roles the holder may assign — that scope IS the list of roles
+   they can hand out, so `.*` lets them invite admins.
+
+Scope lists are index-parallel rows: `{"<wfGrp>": ["prod", "dev"], "<wf>":
+[".*", "x-.*"]}` is two grants, (prod, all) and (dev, x-*). Use `a|b` inside
+one pattern for alternatives; all lists must be the same length. Any ONE row
+that is all `.*` makes the whole permission org-wide.
+
+## Step A — Translate the ask into permissions
+
+1. Check whether a role already does the job:
+   `search_orchestrator_resources(resourceTypes=['ROLE'])` (names and
+   descriptions only). Reusing one beats creating a near-duplicate.
+2. Ask what the holder should be able to DO and WHERE, then resolve every
+   WHERE to an id (rule 1):
+
+| User says | Permissions (scope the placeholders they named, `.*` for the rest) |
+| --- | --- |
+| see workflows in group G | `GetWorkflowGroup` {G}, `GetWorkflow` {G, .*}, `GetWorkflowRun` {G, .*, .*} |
+| run workflows in G | + `CreateWorkflowRun` {G, .*}, `GetWorkflowRunLogs` |
+| create workflows in G | + `CreateWorkflow` {G, .*} (pattern = the new workflow's name) |
+| manage a group's stacks | `GetStack`, `CreateStack`, `UpdateStack`, `CreateStackRun`, `GetStackRun` |
+| use connector C | `GetIntegration` {C} ("connector" is `Integration` on the wire) |
+| read secrets/policies | `GetSecret` {name}, `GetPolicy` {name} |
+| invite / remove users | `InviteUser`/`UpdateUser`/`DeleteUser` + `GetRole` {assignable roles} — privileged |
+| manage roles / API keys / billing | `CreateRole`… / `*APIAccess` (regenerating a key is `UpdateAPIAccess`) / `ManageBilling` — privileged |
+
+An unknown permission name returns the full catalog grouped by area
+(`availablePermissions`) with `didYouMean`; a missing placeholder returns
+`requiredPlaceholders`. There is no "everything" shorthand — an admin-like
+role lists every permission explicitly.
+
+## Step B — Create
+
+1. Ask for a name: letters, digits, `_`, `-` (it becomes the permanent id;
+   no rename). Not a predefined name.
+2. If any permission is privileged (roles, users, API access, billing, or
+   `GetRole` next to user management), tell the user plainly that holders
+   could change who can do what, and only on an explicit yes call with
+   `confirmPrivileged=true`. If a write permission (anything but Get*/List*)
+   is scoped to ALL resources, the tool asks for `confirmOrgWide=true`:
+   first try to narrow the scope to what the user actually said; confirm
+   only when "everything" is what they mean.
+3. Call `create_role(resourceName, permissions=[{permission, scope}, ...],
+   description?, tags?)`.
+4. Walk the user through the returned `permissions` table row by row, in
+   words ("workflow group prod, any workflow") — it is the only way they
+   catch a wrong pairing — and relay `warnings`.
+5. Assignment has no tool here: the user assigns the role to people or SSO
+   groups in the dashboard's Access Management. Changes apply on the
+   holder's next request.
+
+## Step C — Change
+
+1. Find the id: `search_orchestrator_resources(resourceTypes=['ROLE'])` or
+   the `availableRoles` list a tool error returns. Ids are case-sensitive.
+2. `setPermissions` REPLACES a stored entry of the same permission name in
+   full, and no tool shows the stored patterns. Before replacing one, ask
+   the user for its current patterns (the role's page in the dashboard's
+   Access Management) and resend them along with the change — otherwise
+   widening `prod` to `prod|dev` silently drops whatever else was there.
+   Adding a permission the role doesn't hold, `removePermissions`, and
+   `description`/`tags` need no read. Never use `delete_role` to read a role.
+3. `update_role(roleId, setPermissions=[...], removePermissions=[names],
+   description?, tags?)`. Untouched permissions are kept. Writing a
+   privileged permission (new or rewritten) needs `confirmPrivileged`; an
+   org-wide write scope needs `confirmOrgWide`. The response's
+   `permissions` is the full table after the write — show it.
+4. A V3.BETA role is rewritten as equivalent V4 rows on its first permission
+   edit (`migratedFromV3`); say so. A role stored with NO version grants
+   nothing today: ANY update turns all of its permissions on, so the tool
+   gates them all — tell the user that before confirming. An update that
+   would leave zero permissions is refused — use Step D.
+5. A stored permission with an EMPTY scope is an unrestricted grant; the tool
+   warns — offer to scope it.
+
+## Step D — Delete
+
+1. Call `delete_role(roleId)` WITHOUT `confirmDelete`. The error carries
+   `holders` (users and SSO groups bound to it, with their other roles),
+   `permissionsSnapshot` and the `cascade` note.
+2. Tell the user: deletion strips the role from every holder atomically, a
+   holder with no other role loses all access, API-key bindings are not
+   cleaned, and there is no undo (keep the snapshot to recreate).
+3. Only after an explicit yes, call `delete_role(roleId, confirmDelete=true)`.
+   Predefined names are refused outright.
+
+## Why does my role grant nothing?
+
+Ask the user to open the role in the dashboard and read you its permissions.
+Then check: a pattern is a display name where the id differs (rule 1); an
+exact name where a prefix was meant (rule 2); a GET on a child path was
+expected to cover descendants (rule 3); user management without `GetRole`
+(rule 5); the role was stored without a version (the gateway ignores it
+until an update rewrites it); the holder's token predates an SSO group
+change (needs a fresh login).
diff --git a/skills/sg-writing-stackguardian-policy-terraform/SKILL.md b/skills/sg-writing-stackguardian-policy-terraform/SKILL.md
new file mode 100644
index 0000000..d9bcbb5
--- /dev/null
+++ b/skills/sg-writing-stackguardian-policy-terraform/SKILL.md
@@ -0,0 +1,178 @@
+---
+name: sg-writing-stackguardian-policy-terraform
+description: Use when writing, reviewing or debugging Terraform/OpenTofu HCL for StackGuardian policies (stackguardian_policy, policies_config, enforced_on, Tirith JSON, OPA/Rego, marketplace policy templates, cost limits, approval gates, config-time workflow rules), attaching a policy to a workflow, group or connector — or when a policy applies but never blocks, blocks every plan, never asks for approval, or its scope silently disappears. Also covers resolving scopes and dependencies via the StackGuardian MCP server.
+---
+
+# Writing StackGuardian policy Terraform
+
+## Overview
+
+A `stackguardian_policy` is a list of rules (`policies_config`) plus a scope (`enforced_on`).
+**Attachment lives only on the policy** — workflows, groups and templates have no policy
+attribute. Rules are evaluated at two different moments:
+
+| `meta.required_provider` | Evaluated | Verdict effect |
+|---|---|---|
+| `stackguardian/terraform_plan`, `stackguardian/infracost`, OPA (`OPA_REGO`) | in the plan step of TERRAFORM/OPENTOFU runs (also CloudFormation/Pulumi steps), before `apply`; not on drift or `plan-without-policy` runs, not in Ansible/Kubernetes steps | FAIL errors the run; APPROVAL_REQUIRED pauses before the next step |
+| `stackguardian/json` (config rule) | when a workflow in scope is **created/updated** (also via Terraform) and when a run is **built** | FAIL = `403 Workflow policy (<policy>:<rule>) failed …` on create/update (live); at run build the run is refused or gated at step 0 |
+
+The provider validates nothing and the Tirith engine fails *open* on many mistakes, so a wrong
+rule usually applies cleanly and then passes everything. Provider **1.12.3**, Tirith **1.0.5**
+(core; the terraform step on `main` pins 1.0.7 with the same semantics). "(live)" = reproduced against a real org. Setup (source address,
+`api_uri`): **sg-writing-stackguardian-workflow-terraform**.
+
+## Discover scope and dependencies first (StackGuardian MCP)
+
+`enforced_on` entries are never validated, so a typo silently attaches nothing. **If the
+StackGuardian MCP server is connected, take scope strings and ids from it** (rows must carry
+`OrgId = "/orgs/<STACKGUARDIAN_ORG_NAME>"`; read tools only):
+
+| Need | MCP call | Value to use |
+|---|---|---|
+| group scope | `search_orchestrator_resources(resourceTypes=["WORKFLOW_GROUP"], searchQuery=…)` | `SubResourceId` as-is (`/wfgrps/PROD/GCP-4jc2fd3k`) — not `ResourceId` (leaf only) |
+| workflow / stack scope | `search_workflows(searchQuery=…)`, `search_stacks` | `SubResourceId` as-is (`/wfgrps/<g>/wfs/<w>`, `/wfgrps/<g>/stacks/<s>`) |
+| connector scope | `search_orchestrator_resources(resourceTypes=["INTEGRATION.CLOUD"])` | `ResourceId` (`/integrations/<id>`) |
+| blast radius before applying | `search_workflows(parentId="/orgs/<org>/wfgrps/<g>", count=true)`, `search_workflows(cloudIntegrationIds=[…])`, `cross_reference(targetKind="cloud_integration", targetId=…, count=true)` | how many workflows the policy will judge |
+| existing policies | `search_policies(searchQuery=…)`, `get_orchestrator_resource_by_id(parentId="/orgs/<org>", resourceId="/policies/<id>")` | name collisions, current rules and `Scope` |
+| marketplace policy template | `get_subscription(subscriptionTypes=["IAC_POLICY"])` | `/<owner>/<name>` + a revision that exists |
+| git repo auth (OPA / git Tirith) | `search_orchestrator_resources(resourceTypes=["INTEGRATION.VCS"])`, `["SECRET"]` | `auth` = `ResourceId` / `/secrets/<name>` |
+| config-rule key paths | `get_orchestrator_resource_by_id` on a real workflow | exact field names (`TerraformConfig`, `DeploymentPlatformConfig`, `RunnerConstraints`, …) |
+
+Without MCP: literal paths from the user plus data-source existence checks — never guessed.
+
+## Core template (runtime rule on the Terraform plan)
+
+```terraform
+resource "stackguardian_policy" "no_public_s3" {
+  resource_name = "no-public-s3"  # slug: it is the id, and approvals match on it
+  policy_type   = "GENERAL"       # the only value the provider can write
+  description   = "Block public S3 ACLs"
+  tags          = ["security"]
+  enforced_on   = ["/wfgrps/${stackguardian_workflow_group.payments.id}"] # ALWAYS declare (see rule 1)
+  approvers     = []                # declare, even when empty
+  number_of_approvals_required = 0
+
+  policies_config = [{
+    name    = "s3_acl_not_public"   # slug, unique in the policy
+    skip    = false
+    on_fail = "FAIL"                # FAIL | WARN | PASS | APPROVAL_REQUIRED
+    on_pass = "PASS"                # REQUIRED too: omitted -> 400 `onPass: "" is not a valid choice` (live)
+
+    policy_vcs_config = {
+      use_marketplace_template = false
+      custom_source = { source_config_kind = "SG_POLICY_FRAMEWORK", source_config_dest_kind = "INLINE" }
+    }
+
+    policy_input_data = {
+      schema_type = "TIRITH_JSON"
+      data = jsonencode({            # only meta, evaluators, eval_expression at the top level
+        meta = { version = "v1", required_provider = "stackguardian/terraform_plan" }
+        evaluators = [{
+          id = "acl_not_public"      # snake_case; never a prefix of another id
+          provider_args = {
+            operation_type               = "attribute"
+            terraform_resource_type      = "aws_s3_bucket_acl"
+            terraform_resource_attribute = "acl"
+          }
+          condition = {
+            type            = "NotContainedIn"   # found value must NOT be in this list
+            value           = ["public-read", "public-read-write", "authenticated-read"]
+            error_tolerance = 1                  # skip plans without aws_s3_bucket_acl (0 = FAIL them)
+          }
+        }]
+        eval_expression = "acl_not_public"       # && || ! ( ) only
+      })
+    }
+  }]
+}
+```
+
+## Rules that bite
+
+1. **Declare `enforced_on`, `tags`, `approvers`, `number_of_approvals_required`, `description` and
+   `policies_config` every time.** They are Optional+Computed without state carry-over: omit one
+   while changing anything else and the provider sends `null` (the live test wiped `enforced_on` to
+   `[]`, silently detaching the policy); an omitted `number_of_approvals_required` is sent as `0` —
+   *all* approvers. `enforced_on = []` or no attribute = attached to **nothing**; org-wide is `["*"]`.
+2. **Scope paths** are exact strings, never validated: `"*"`, `/wfgrps/<group-id>` (includes nested
+   groups, stacks, workflows), `/wfgrps/<g>/wfs/<wf>`, `/wfgrps/<g>/stacks/<s>[/wfs/<wf>]`,
+   `/integrations/<connector>` (every workflow deploying through it),
+   `/integrationgroups/<g>[/integrations/<c>]`. Nested group: `/wfgrps/parent/child`. No trailing `/`.
+3. **Condition direction:** `Contains` = found value contains yours; `ContainedIn` = found value is
+   in your list (allow-list); `NotContainedIn` = deny-list. Types are case-sensitive; an unknown
+   type (`In`, `Exists`, `StartsWith`, `NotRegexMatch`) fails every input.
+4. **`error_tolerance`** (inside `condition`): 0 fails plans that lack the resource type, 1 skips
+   them, 2 also skips resources missing the attribute. A fully skipped rule **passes**.
+5. **Terraform plan actions are `create`, `update`, `delete`, `no-op`, `read`** — never `apply` or
+   `destroy`. The provider docs' `NotEquals "apply"` approval example never fires.
+6. **APPROVAL_REQUIRED** needs `approvers` + `number_of_approvals_required` on the policy (`0` =
+   all approvers). A runtime approval pauses before the *next* step, so plan-only runs never pause.
+   Approvals match on the policy's id: keep `resource_name` a slug, don't set a different `id`, and
+   never rename a policy that uses APPROVAL_REQUIRED (the id stays, the match breaks).
+7. **Config rules** must be `stackguardian/json` + `operation_type = "get_value"` + a `key_path`
+   rooted at a workflow field (`TerraformConfig.managedTerraformState`, `Tags`, `WfType`,
+   `DeploymentPlatformConfig.*.config.integrationId`, …). Any other `required_provider`
+   (`sg_workflow`, `sg_stack`, `kubernetes`, none) ends in "Tirith run errored" → `on_fail` in the
+   terraform step — it **blocks every Terraform/OpenTofu run in scope**. `sg_workflow`/`sg_stack`
+   with a workflow `key_path` are also picked up at config time and always fail there (Tirith has no
+   `sg_stack` provider; `sg_workflow` ignores `key_path`): with `FAIL`, every workflow create/update gets 403.
+8. **OPA** needs `additional_config = jsonencode({ opaQuery = "<package>.<bool_rule>" })` (no `data.`
+   prefix) — without it every Rego policy passes. The provider cannot read it back: the first apply
+   ends in *inconsistent result* (tainted); `terraform untaint`, then use
+   `lifecycle { ignore_changes = all }` and change the policy only with `-replace`.
+   **Not** `ignore_changes = [policies_config]`: any later update then re-sends the rules from state
+   and wipes `opaQuery` server-side (live).
+9. **Only three top-level keys** in a Tirith document (`meta`, `evaluators`, `eval_expression`),
+   integers rather than floats, `jsonencode` for `data`, `schema_type = "TIRITH_JSON"` for inline Tirith.
+10. **A policy in scope also blocks Terraform:** a failing config rule makes `terraform apply` of
+    the affected `stackguardian_workflow_*` resources fail with 403.
+
+## Quick reference
+
+| Need | Use |
+|---|---|
+| Block a resource setting | `terraform_plan` / `attribute` + `NotContainedIn` / `NotEquals`, tolerance 1 |
+| Required tags | `attribute` on `tags` (or `tags_all`) + `Contains "<key>"` (key) or `Contains { K = "v" }` (pair) |
+| Restrict region | `provider_config`, `attribute = "region"`, `ContainedIn [...]` — one evaluator per registry (`registry.terraform.io/hashicorp/aws` for Terraform, `registry.opentofu.org/hashicorp/aws` for OpenTofu), tolerance 2, joined with `&&`; only literal regions are checked |
+| Count cap | `count` + `LessThanEqualTo N` |
+| Monthly cost cap | `stackguardian/infracost`, `total_monthly_cost`, `resource_type = ["*"]`, `LessThanEqualTo 500` |
+| Approval on deletes | `action`, type `"*"`, `NotContainedIn ["delete"]`, `on_fail = "APPROVAL_REQUIRED"` |
+| Config guardrail | `stackguardian/json`, `get_value`, `key_path`; e.g. managed state = `is_custom \|\| uses_managed_state` (tolerance 1 on the managed key — see `examples/config_rules.tf`) |
+| Scope an existing group/workflow | a literal/local path (`local.net = "platform/networking"` → `"/wfgrps/${local.net}"`), with `data "stackguardian_workflow_group" { id = local.net }` as a plan-time existence check. Don't use `data.<group>.id` in the path: it is only the leaf for nested groups (live) |
+| Marketplace rule | `policy_vcs_config = { use_marketplace_template = true, policy_template_id = "/<owner-org>/<name>:<n>" }` |
+| Git Tirith | `SG_POLICY_FRAMEWORK` + git kind; the file must be `<working_dir>/tirith.json`; runtime only |
+| Warn-only rollout / disable | `on_fail = "WARN"` / `skip = true` (there is no active flag) |
+| Import | `terraform import stackguardian_policy.x <policy-id>` |
+
+## Common mistakes
+
+| Mistake | What happens |
+|---|---|
+| `schema_type = "TIRITH_FORMAT"` / other invented enums | Apply error: `… is not a valid …` |
+| Org-wide by listing groups | Misses new groups; use `["*"]` |
+| `eval_expression = "a and b"` | Becomes an undefined symbol → **silent pass** |
+| Ids `acl-ok` and `acl-ok-2` | Prefix collision → `final_result = -1`, treated as a pass: the longer id's evaluator is silently ignored |
+| `error_tolerance = 0` on a type-specific rule, group-wide | Every plan without that type FAILS |
+| `on_fail = "APPROVAL_REQUIRED"` without approvers | The run pauses and anyone with approve permission can release it |
+| `required_provider = "stackguardian/sg_workflow"` (or `sg_stack`, `kubernetes`) | FAILs the terraform step of every run in scope; with a workflow `key_path` also 403s every workflow create/update (rule 7) |
+| Required tag as `terraform_resource_attribute = "tags.CostCenter"` with tolerance 2, or with type `"*"` | A missing key is "attribute not found" (severity 2): tolerance 2 skips it, so the rule never fails; with `"*"` and tolerance 1 every untaggable resource fails. Use one type per evaluator with tolerance 1, or `tags` + `Contains "CostCenter"` |
+| `policies_config { ... }` block, or a raw HCL object as `data` | Syntax / type error: `policies_config = [{ ... }]`, `data = jsonencode({ ... })` |
+| `stackguardian_policy { data = jsonencode({...}) }` (pre-1.x form, still in the provider's onboarding guide asset) | Unsupported argument; use the typed attributes |
+| `severity`, a stage (`PRE_PLAN`, `PRE_APPLY`), per-rule approvers, nested `all_of`/`any_of` | Not part of a policy: severity/stage keys are ignored, nested shapes are not read. Enforcement is only `on_fail`/`on_pass`; approvers are policy-level |
+| `{{ var.x }}` placeholders in the document | Never filled; the plan step crashes (even with `on_fail = "WARN"`) |
+| OPA `opaQuery = "data.main.allow"` or `main.deny` | KeyError / non-boolean → on_fail |
+| `policy_template_id = "/stackguardian/x:latest"` | Resolved per run; pin a number |
+| `policy_type = "FILTER.INSIGHT"` | Provider always writes GENERAL → inconsistent result |
+| `policies_config = []` (a policy without rules) | Inconsistent result, tainted (live) — a policy needs at least one rule; disable with `skip = true` |
+| `resource_name` of a policy that already exists | `409 Policy ID not unique` (from code) — `terraform import` it instead |
+| Floats like `value = 99.5` in the document | The create stores raw floats and can 409 (unverified); use integers |
+
+## References
+
+- `references/tirith.md` — Tirith 1.0.5: providers, operation types, conditions, tolerance and skip
+  semantics (incl. the skip-erasure bug), `eval_expression`, config-time key paths, verified recipes.
+- `references/sources-and-lifecycle.md` — inline / git / OPA / marketplace sources, scope
+  resolution, approvals, provider round-trip behaviour, import, destroy, error catalog.
+- `references/schema.md` — exact `stackguardian_policy` schema (provider 1.12.3).
+- `examples/*.tf` — validated with `terraform`/`tofu validate`, applied live, and every Tirith
+  document executed against Tirith 1.0.5 with passing and failing sample plans (`examples/README.md`).
diff --git a/skills/sg-writing-stackguardian-policy-terraform/examples/README.md b/skills/sg-writing-stackguardian-policy-terraform/examples/README.md
new file mode 100644
index 0000000..389f8db
--- /dev/null
+++ b/skills/sg-writing-stackguardian-policy-terraform/examples/README.md
@@ -0,0 +1,23 @@
+# Examples
+
+Every file pairs with `versions.tf` as a root module and passes `terraform validate` and
+`tofu validate` (provider 1.12.3). All were also applied against a real org with names prefixed
+and `enforced_on` pointed at an empty scope, re-planned with no changes (the OPA policy after the
+documented untaint), and destroyed. Every
+inline Tirith document was extracted from the Terraform plan and executed on Tirith 1.0.5 with
+passing, failing and skip inputs.
+
+| File | Rules | Where it runs |
+|---|---|---|
+| `no_public_s3.tf` | S3 ACL deny-list + public-access-block check; group + single-workflow scope | runtime (plan) |
+| `required_tags.tf` | CostCenter key and Environment=production on EC2/RDS | runtime (plan) |
+| `network_guardrails.tf` | no 0.0.0.0/0 ingress, EU regions via `provider_config`, instance-type allow-list | runtime (plan) |
+| `approvals.tf` | approval on any delete/replace, approval when monthly cost > 500; org-wide `["*"]`, shared approvers | runtime (plan / Infracost) |
+| `config_rules.tf` | managed state required (warn), approved connectors + private runners (fail), pinned Terraform version (warn) | config time (workflow create/update, run build) |
+| `opa_and_marketplace.tf` | Rego from private GitHub with `opaQuery` (+ the untaint / `ignore_changes = all` handling), connector scope; marketplace checkov bundle warn-only | runtime |
+
+The `terraform_version` rule in `config_rules.tf` was added later: it passes both validators and its
+document was run on Tirith 1.0.5 with passing and failing workflow payloads, but it was not applied
+live.
+
+Replace the placeholder ids (`acme`, connector names, repo URLs, approver emails) with yours.
diff --git a/skills/sg-writing-stackguardian-policy-terraform/examples/approvals.tf b/skills/sg-writing-stackguardian-policy-terraform/examples/approvals.tf
new file mode 100644
index 0000000..9f79f0e
--- /dev/null
+++ b/skills/sg-writing-stackguardian-policy-terraform/examples/approvals.tf
@@ -0,0 +1,63 @@
+# Two approval gates in one policy, org-wide: plans that delete anything, and plans whose
+# estimated monthly cost exceeds $500. Approvers are policy-level and shared by both rules.
+# Runtime approvals pause before apply; plan-only runs never pause.
+
+locals {
+  inline = {
+    use_marketplace_template = false
+    custom_source            = { source_config_kind = "SG_POLICY_FRAMEWORK", source_config_dest_kind = "INLINE" }
+  }
+}
+
+resource "stackguardian_policy" "change_approvals" {
+  resource_name = "change-approvals" # slug: runtime approvals match approvers on this name
+  policy_type   = "GENERAL"
+  description   = "Human approval for deletions and expensive plans"
+  tags          = ["governance"]
+  enforced_on   = ["*"] # whole organization — on its own, never combined
+
+  approvers                    = ["finops@acme.com", "cto@acme.com"] # lowercase emails or SSO groups
+  number_of_approvals_required = 1                                   # 0 would mean ALL of them
+
+  policies_config = [
+    {
+      name              = "approve_deletes"
+      skip              = false
+      on_fail           = "APPROVAL_REQUIRED"
+      on_pass           = "PASS"
+      policy_vcs_config = local.inline
+      policy_input_data = {
+        schema_type = "TIRITH_JSON"
+        data = jsonencode({
+          meta = { version = "v1", required_provider = "stackguardian/terraform_plan" }
+          evaluators = [{
+            id            = "no_deletes"
+            provider_args = { operation_type = "action", terraform_resource_type = "*" }
+            # plan actions are create/update/delete/no-op/read; a replace yields delete + create
+            condition = { type = "NotContainedIn", value = ["delete"], error_tolerance = 1 }
+          }]
+          eval_expression = "no_deletes"
+        })
+      }
+    },
+    {
+      name              = "approve_cost_over_500"
+      skip              = false
+      on_fail           = "APPROVAL_REQUIRED"
+      on_pass           = "PASS"
+      policy_vcs_config = local.inline
+      policy_input_data = {
+        schema_type = "TIRITH_JSON"
+        data = jsonencode({
+          meta = { version = "v1", required_provider = "stackguardian/infracost" }
+          evaluators = [{
+            id            = "monthly_cost_ok"
+            provider_args = { operation_type = "total_monthly_cost", resource_type = ["*"] }
+            condition     = { type = "LessThanEqualTo", value = 500 } # integers only
+          }]
+          eval_expression = "monthly_cost_ok"
+        })
+      }
+    },
+  ]
+}
diff --git a/skills/sg-writing-stackguardian-policy-terraform/examples/config_rules.tf b/skills/sg-writing-stackguardian-policy-terraform/examples/config_rules.tf
new file mode 100644
index 0000000..0405c29
--- /dev/null
+++ b/skills/sg-writing-stackguardian-policy-terraform/examples/config_rules.tf
@@ -0,0 +1,109 @@
+# Config-time rules (stackguardian/json): evaluated against the WORKFLOW DEFINITION when a workflow
+# in scope is created or updated (terraform apply of stackguardian_workflow_* gets a 403 on FAIL)
+# and again when each run is built.
+
+resource "stackguardian_workflow_group" "platform" {
+  id            = "platform"
+  resource_name = "platform"
+}
+
+locals {
+  inline = {
+    use_marketplace_template = false
+    custom_source            = { source_config_kind = "SG_POLICY_FRAMEWORK", source_config_dest_kind = "INLINE" }
+  }
+}
+
+resource "stackguardian_policy" "workflow_standards" {
+  resource_name                = "workflow-standards"
+  policy_type                  = "GENERAL"
+  description                  = "Managed state, approved connectors, private runners, pinned Terraform version"
+  tags                         = ["platform"]
+  enforced_on                  = ["/wfgrps/${stackguardian_workflow_group.platform.id}"]
+  approvers                    = []
+  number_of_approvals_required = 0
+
+  policies_config = [
+    {
+      name              = "managed_state"
+      skip              = false
+      on_fail           = "WARN" # roll out as a warning first
+      on_pass           = "PASS"
+      policy_vcs_config = local.inline
+      policy_input_data = {
+        schema_type = "TIRITH_JSON"
+        data = jsonencode({
+          meta = { version = "v1", required_provider = "stackguardian/json" }
+          evaluators = [
+            {
+              id            = "is_custom"
+              provider_args = { operation_type = "get_value", key_path = "WfType" }
+              condition     = { type = "Equals", value = "CUSTOM", error_tolerance = 2 }
+            },
+            {
+              id            = "uses_managed_state"
+              provider_args = { operation_type = "get_value", key_path = "TerraformConfig.managedTerraformState" }
+              # tolerance 1: a TERRAFORM/OPENTOFU workflow that omits the key (server default = unmanaged) fails too
+              condition = { type = "Equals", value = true, error_tolerance = 1 }
+            },
+          ]
+          eval_expression = "is_custom || uses_managed_state" # CUSTOM workflows have no Terraform state
+        })
+      }
+    },
+    {
+      name              = "approved_connectors"
+      skip              = false
+      on_fail           = "FAIL"
+      on_pass           = "PASS"
+      policy_vcs_config = local.inline
+      policy_input_data = {
+        schema_type = "TIRITH_JSON"
+        data = jsonencode({
+          meta = { version = "v1", required_provider = "stackguardian/json" }
+          evaluators = [
+            {
+              id            = "known_connector"
+              provider_args = { operation_type = "get_value", key_path = "DeploymentPlatformConfig.*.config.integrationId" }
+              condition     = { type = "ContainedIn", value = ["/integrations/aws-prod-oidc", "/integrations/aws-shared-rbac"], error_tolerance = 2 }
+            },
+            {
+              id            = "private_runner"
+              provider_args = { operation_type = "get_value", key_path = "RunnerConstraints.type" }
+              # tolerance 1: an omitted runner type (server default = shared) fails too
+              condition = { type = "Equals", value = "private", error_tolerance = 1 }
+            },
+          ]
+          eval_expression = "known_connector && private_runner"
+        })
+      }
+    },
+    {
+      name              = "terraform_version"
+      skip              = false
+      on_fail           = "WARN"
+      on_pass           = "PASS"
+      policy_vcs_config = local.inline
+      policy_input_data = {
+        schema_type = "TIRITH_JSON"
+        data = jsonencode({
+          meta = { version = "v1", required_provider = "stackguardian/json" }
+          evaluators = [
+            {
+              id            = "is_custom"
+              provider_args = { operation_type = "get_value", key_path = "WfType" }
+              condition     = { type = "Equals", value = "CUSTOM", error_tolerance = 2 }
+            },
+            {
+              id            = "tf_version_ok"
+              provider_args = { operation_type = "get_value", key_path = "TerraformConfig.terraformVersion" }
+              # HCL "\\." is a literal dot in the regex; tolerance 1: a workflow without a version fails
+              condition = { type = "RegexMatch", value = "^1\\.(5|9)\\.", error_tolerance = 1 }
+            },
+          ]
+          eval_expression = "is_custom || tf_version_ok"
+        })
+      }
+    },
+  ]
+}
diff --git a/skills/sg-writing-stackguardian-policy-terraform/examples/network_guardrails.tf b/skills/sg-writing-stackguardian-policy-terraform/examples/network_guardrails.tf
new file mode 100644
index 0000000..d653a35
--- /dev/null
+++ b/skills/sg-writing-stackguardian-policy-terraform/examples/network_guardrails.tf
@@ -0,0 +1,64 @@
+# Runtime rules: no world-open ingress (IPv4/IPv6), literal EU provider regions only (Terraform and
+# OpenTofu registries), approved instance types.
+
+resource "stackguardian_workflow_group" "apps" {
+  id            = "apps"
+  resource_name = "apps"
+}
+
+resource "stackguardian_policy" "network_guardrails" {
+  resource_name                = "network-guardrails"
+  policy_type                  = "GENERAL"
+  description                  = "Ingress, region and instance-type guardrails"
+  tags                         = ["security"]
+  enforced_on                  = ["/wfgrps/${stackguardian_workflow_group.apps.id}"]
+  approvers                    = []
+  number_of_approvals_required = 0
+
+  policies_config = [{
+    name    = "network_guardrails"
+    skip    = false
+    on_fail = "FAIL"
+    on_pass = "PASS"
+    policy_vcs_config = {
+      use_marketplace_template = false
+      custom_source            = { source_config_kind = "SG_POLICY_FRAMEWORK", source_config_dest_kind = "INLINE" }
+    }
+    policy_input_data = {
+      schema_type = "TIRITH_JSON"
+      data = jsonencode({
+        meta = { version = "v1", required_provider = "stackguardian/terraform_plan" }
+        evaluators = [
+          {
+            id            = "no_open_ipv4_ingress"
+            provider_args = { operation_type = "attribute", terraform_resource_type = "aws_vpc_security_group_ingress_rule", terraform_resource_attribute = "cidr_ipv4" }
+            # tolerance 1: a cidr unknown at plan time fails (tolerance 2 would let skips erase violations)
+            condition = { type = "NotEquals", value = "0.0.0.0/0", error_tolerance = 1 }
+          },
+          {
+            id            = "no_open_ipv6_ingress"
+            provider_args = { operation_type = "attribute", terraform_resource_type = "aws_vpc_security_group_ingress_rule", terraform_resource_attribute = "cidr_ipv6" }
+            condition     = { type = "NotEquals", value = "::/0", error_tolerance = 1 }
+          },
+          {
+            id            = "eu_region_terraform"
+            provider_args = { operation_type = "provider_config", terraform_provider_full_name = "registry.terraform.io/hashicorp/aws", attribute = "region" }
+            # only a literal region in the first matching provider block resolves; tolerance 2 skips the rest
+            condition = { type = "ContainedIn", value = ["eu-central-1", "eu-west-1"], error_tolerance = 2 }
+          },
+          {
+            id            = "eu_region_opentofu"
+            provider_args = { operation_type = "provider_config", terraform_provider_full_name = "registry.opentofu.org/hashicorp/aws", attribute = "region" }
+            condition     = { type = "ContainedIn", value = ["eu-central-1", "eu-west-1"], error_tolerance = 2 }
+          },
+          {
+            id            = "approved_instance_type"
+            provider_args = { operation_type = "attribute", terraform_resource_type = "aws_instance", terraform_resource_attribute = "instance_type" }
+            condition     = { type = "ContainedIn", value = ["t3.micro", "t3.small", "m6i.large"], error_tolerance = 1 }
+          },
+        ]
+        eval_expression = "no_open_ipv4_ingress && no_open_ipv6_ingress && eu_region_terraform && eu_region_opentofu && approved_instance_type"
+      })
+    }
+  }]
+}
diff --git a/skills/sg-writing-stackguardian-policy-terraform/examples/no_public_s3.tf b/skills/sg-writing-stackguardian-policy-terraform/examples/no_public_s3.tf
new file mode 100644
index 0000000..405aef1
--- /dev/null
+++ b/skills/sg-writing-stackguardian-policy-terraform/examples/no_public_s3.tf
@@ -0,0 +1,68 @@
+# Runtime rule: deny public canned ACLs on aws_s3_bucket_acl and require block_public_acls on declared
+# aws_s3_bucket_public_access_block resources. Not covered: buckets without a public access block
+# (a direct_references recipe exists, with limits: references/tirith.md §8), ACL grants via
+# access_control_policy, bucket policies.
+# Scope: a workflow group (incl. nested groups) plus one extra workflow elsewhere.
+
+resource "stackguardian_workflow_group" "payments" {
+  id            = "payments"
+  resource_name = "payments"
+}
+
+locals {
+  inline_tirith = {
+    use_marketplace_template = false
+    custom_source            = { source_config_kind = "SG_POLICY_FRAMEWORK", source_config_dest_kind = "INLINE" }
+  }
+}
+
+resource "stackguardian_policy" "no_public_s3" {
+  resource_name = "no-public-s3"
+  policy_type   = "GENERAL"
+  description   = "Deny public canned S3 ACLs; public access blocks must block public ACLs"
+  tags          = ["security", "s3"]
+  enforced_on = [
+    "/wfgrps/${stackguardian_workflow_group.payments.id}", # group + everything below it
+    "/wfgrps/platform/wfs/shared-dns",                     # one workflow: /wfgrps/<group>/wfs/<workflow>
+  ]
+  approvers                    = []
+  number_of_approvals_required = 0
+
+  policies_config = [{
+    name              = "s3_not_public"
+    skip              = false
+    on_fail           = "FAIL"
+    on_pass           = "PASS"
+    policy_vcs_config = local.inline_tirith
+    policy_input_data = {
+      schema_type = "TIRITH_JSON"
+      data = jsonencode({
+        meta = { version = "v1", required_provider = "stackguardian/terraform_plan" }
+        evaluators = [
+          {
+            id          = "acl_not_public"
+            description = "aws_s3_bucket_acl.acl must not grant public access"
+            provider_args = {
+              operation_type               = "attribute"
+              terraform_resource_type      = "aws_s3_bucket_acl"
+              terraform_resource_attribute = "acl"
+            }
+            # tolerance 1: plans without aws_s3_bucket_acl are skipped, not failed
+            condition = { type = "NotContainedIn", value = ["public-read", "public-read-write", "authenticated-read"], error_tolerance = 1 }
+          },
+          {
+            id          = "public_access_blocked"
+            description = "public access blocks must block public ACLs"
+            provider_args = {
+              operation_type               = "attribute"
+              terraform_resource_type      = "aws_s3_bucket_public_access_block"
+              terraform_resource_attribute = "block_public_acls"
+            }
+            condition = { type = "Equals", value = true, error_tolerance = 1 }
+          },
+        ]
+        eval_expression = "acl_not_public && public_access_blocked" # a skipped evaluator drops out of the expression
+      })
+    }
+  }]
+}
diff --git a/skills/sg-writing-stackguardian-policy-terraform/examples/opa_and_marketplace.tf b/skills/sg-writing-stackguardian-policy-terraform/examples/opa_and_marketplace.tf
new file mode 100644
index 0000000..037d946
--- /dev/null
+++ b/skills/sg-writing-stackguardian-policy-terraform/examples/opa_and_marketplace.tf
@@ -0,0 +1,70 @@
+# Rego from a private GitHub repo, scoped to every workflow deploying through one connector,
+# plus a StackGuardian marketplace policy template org-wide as warn-only.
+
+data "stackguardian_connector" "github" {
+  id = "github_com"
+}
+
+resource "stackguardian_policy" "opa_guardrails" {
+  resource_name                = "opa-guardrails"
+  policy_type                  = "GENERAL"
+  description                  = "Rego guardrails for production AWS"
+  tags                         = ["opa"]
+  enforced_on                  = ["/integrations/aws-prod-oidc"] # workflows whose deployment_platform_config uses it
+  approvers                    = []
+  number_of_approvals_required = 0
+
+  policies_config = [{
+    name    = "rego_allow"
+    skip    = false
+    on_fail = "FAIL"
+    on_pass = "PASS"
+    policy_vcs_config = {
+      use_marketplace_template = false
+      custom_source = {
+        source_config_kind      = "OPA_REGO"
+        source_config_dest_kind = "GITHUB_COM" # OPA is never INLINE
+        config = {
+          repo        = "https://github.com/acme/opa-policies"
+          ref         = "main"
+          working_dir = "terraform" # directory loaded with `opa eval --data`
+          is_private  = true
+          auth        = "/integrations/${data.stackguardian_connector.github.id}"
+        }
+        # package terraform.guardrails + `default allow = false` + allow rules
+        # (OPA 0.55: Rego v0 with `import future.keywords.if`; `import rego.v1` does not parse)
+        additional_config = jsonencode({ opaQuery = "terraform.guardrails.allow" }) # no "data." prefix
+      }
+    }
+  }]
+
+  # The provider cannot read additional_config back: the first apply reports
+  # "Provider produced inconsistent result" although the policy is stored correctly.
+  # Then: terraform untaint stackguardian_policy.opa_guardrails
+  # ignore_changes = all (NOT [policies_config]): any update would re-send the rules from state
+  # without opaQuery and silently disable the Rego check. Change this policy with -replace.
+  lifecycle {
+    ignore_changes = all
+  }
+}
+
+resource "stackguardian_policy" "aws_best_practices" {
+  resource_name                = "aws-best-practices"
+  policy_type                  = "GENERAL"
+  description                  = "StackGuardian AWS best practices (checkov), report only"
+  tags                         = ["aws"]
+  enforced_on                  = ["*"]
+  approvers                    = []
+  number_of_approvals_required = 0
+
+  policies_config = [{
+    name    = "aws_best_practices_all"
+    skip    = false
+    on_fail = "WARN"
+    on_pass = "PASS"
+    policy_vcs_config = {
+      use_marketplace_template = true
+      policy_template_id       = "/stackguardian/aws-best-practices-all:2" # numeric revision; not validated until a run
+    }
+  }]
+}
diff --git a/skills/sg-writing-stackguardian-policy-terraform/examples/required_tags.tf b/skills/sg-writing-stackguardian-policy-terraform/examples/required_tags.tf
new file mode 100644
index 0000000..16e1487
--- /dev/null
+++ b/skills/sg-writing-stackguardian-policy-terraform/examples/required_tags.tf
@@ -0,0 +1,61 @@
+# Runtime rule: EC2 instances and RDS databases must carry a CostCenter tag and Environment=production.
+# One evaluator per resource type and tag; tolerance 1 so plans without that type pass.
+
+resource "stackguardian_workflow_group" "prod" {
+  id            = "prod"
+  resource_name = "prod"
+}
+
+locals {
+  tag_attr = { operation_type = "attribute", terraform_resource_attribute = "tags" } # "tags_all" also counts default_tags
+}
+
+resource "stackguardian_policy" "required_tags" {
+  resource_name                = "required-tags"
+  policy_type                  = "GENERAL"
+  description                  = "Mandatory cost and environment tags"
+  tags                         = ["finops"]
+  enforced_on                  = ["/wfgrps/${stackguardian_workflow_group.prod.id}"]
+  approvers                    = []
+  number_of_approvals_required = 0
+
+  policies_config = [{
+    name    = "mandatory_tags"
+    skip    = false
+    on_fail = "FAIL"
+    on_pass = "PASS"
+    policy_vcs_config = {
+      use_marketplace_template = false
+      custom_source            = { source_config_kind = "SG_POLICY_FRAMEWORK", source_config_dest_kind = "INLINE" }
+    }
+    policy_input_data = {
+      schema_type = "TIRITH_JSON"
+      data = jsonencode({
+        meta = { version = "v1", required_provider = "stackguardian/terraform_plan" }
+        evaluators = [
+          {
+            id            = "ec2_cost_center"
+            provider_args = merge(local.tag_attr, { terraform_resource_type = "aws_instance" })
+            condition     = { type = "Contains", value = "CostCenter", error_tolerance = 1 } # tag key present
+          },
+          {
+            id            = "ec2_environment"
+            provider_args = merge(local.tag_attr, { terraform_resource_type = "aws_instance" })
+            condition     = { type = "Contains", value = { Environment = "production" }, error_tolerance = 1 } # key = value
+          },
+          {
+            id            = "rds_cost_center"
+            provider_args = merge(local.tag_attr, { terraform_resource_type = "aws_db_instance" })
+            condition     = { type = "Contains", value = "CostCenter", error_tolerance = 1 }
+          },
+          {
+            id            = "rds_environment"
+            provider_args = merge(local.tag_attr, { terraform_resource_type = "aws_db_instance" })
+            condition     = { type = "Contains", value = { Environment = "production" }, error_tolerance = 1 }
+          },
+        ]
+        eval_expression = "ec2_cost_center && ec2_environment && rds_cost_center && rds_environment"
+      })
+    }
+  }]
+}
diff --git a/skills/sg-writing-stackguardian-policy-terraform/examples/versions.tf b/skills/sg-writing-stackguardian-policy-terraform/examples/versions.tf
new file mode 100644
index 0000000..e0b7bdd
--- /dev/null
+++ b/skills/sg-writing-stackguardian-policy-terraform/examples/versions.tf
@@ -0,0 +1,17 @@
+terraform {
+  required_version = ">= 1.5"
+
+  required_providers {
+    stackguardian = {
+      # Full address so the same code works under OpenTofu (its registry has no copy).
+      source  = "registry.terraform.io/StackGuardian/stackguardian"
+      version = "~> 1.12.3"
+    }
+  }
+}
+
+# Credentials from the environment:
+#   STACKGUARDIAN_API_KEY   raw key (sgu_/sgo_...), no "apikey " prefix
+#   STACKGUARDIAN_ORG_NAME  org slug
+#   STACKGUARDIAN_API_URI   https://api.app.stackguardian.io (EU) or https://api.us.stackguardian.io (US) — there is no default
+provider "stackguardian" {}
diff --git a/skills/sg-writing-stackguardian-policy-terraform/references/schema.md b/skills/sg-writing-stackguardian-policy-terraform/references/schema.md
new file mode 100644
index 0000000..5ae326e
--- /dev/null
+++ b/skills/sg-writing-stackguardian-policy-terraform/references/schema.md
@@ -0,0 +1,57 @@
+# Provider 1.12.3 schema — `stackguardian_policy`
+
+Generated from `terraform providers schema -json` (StackGuardian/stackguardian 1.12.3).
+`= {...}` / `= [{...}]` are nested **attributes** (`name = …`), never blocks.
+`optional+computed` without state carry-over: omit it while changing anything else and it is
+sent as `null` (cleared) — declare every top-level attribute.
+
+Accepted values (parsed at apply, not at validate):
+
+| Attribute | Values |
+|---|---|
+| `policy_type` | `GENERAL` (the provider cannot write `FILTER.INSIGHT`) |
+| `policies_config[].on_fail`, `.on_pass` | `FAIL`, `WARN`, `PASS`, `APPROVAL_REQUIRED` — both required by the API |
+| `policy_input_data.schema_type` | `TIRITH_JSON` (inline Tirith), `FORM_JSONSCHEMA` (marketplace template inputs), `RAW_JSON`, `NONE` |
+| `custom_source.source_config_kind` | `SG_POLICY_FRAMEWORK` (Tirith), `OPA_REGO` |
+| `custom_source.source_config_dest_kind` | `INLINE` (Tirith only), `GITHUB_COM`, `GITHUB_APP_CUSTOM`, `GITLAB_COM`, `BITBUCKET_ORG`, `AZURE_DEVOPS`, `GIT_OTHER` |
+| `custom_source.additional_config` | JSON string, e.g. `jsonencode({ opaQuery = "pkg.allow" })` (not read back — see sources-and-lifecycle §1) |
+| `policy_vcs_config.policy_template_id` | `/<owner-org>/<template>:<revision>` |
+
+Data source `stackguardian_policy`: look up by `id` (`resource_name` input deprecated); returns the
+same attributes, all computed — except that its `id` output is always `""`.
+
+### resource stackguardian_policy
+```
+approvers: list(string)  [optional+computed]
+description: string  [optional+computed]
+enforced_on: list(string)  [optional+computed]
+id: string  [optional+computed]
+number_of_approvals_required: number  [optional+computed]
+policies_config = [{...}]  [optional+computed]
+  name: string  [REQUIRED]
+  on_fail: string  [optional]
+  on_pass: string  [optional]
+  policy_input_data = {...}  [optional]
+    data: string  [REQUIRED]
+    schema_type: string  [REQUIRED]
+  policy_vcs_config = {...}  [optional]
+    custom_source = {...}  [optional]
+      additional_config: string  [optional]
+      config = {...}  [optional+computed]
+        auth: string  [optional]
+        git_core_auto_crlf: bool  [optional+computed]
+        git_sparse_checkout_config: string  [optional]
+        include_submodule: bool  [optional]
+        is_private: bool  [optional]
+        ref: string  [optional]
+        repo: string  [optional]
+        working_dir: string  [optional]
+      source_config_dest_kind: string  [optional+computed]
+      source_config_kind: string  [REQUIRED]
+    policy_template_id: string  [optional]
+    use_marketplace_template: bool  [REQUIRED]
+  skip: bool  [optional]
+policy_type: string  [REQUIRED]
+resource_name: string  [REQUIRED]
+tags: list(string)  [optional+computed]
+```
diff --git a/skills/sg-writing-stackguardian-policy-terraform/references/sources-and-lifecycle.md b/skills/sg-writing-stackguardian-policy-terraform/references/sources-and-lifecycle.md
new file mode 100644
index 0000000..fb2b21d
--- /dev/null
+++ b/skills/sg-writing-stackguardian-policy-terraform/references/sources-and-lifecycle.md
@@ -0,0 +1,212 @@
+# Rule sources, scope, verdicts and provider behaviour
+
+"(live)" = reproduced with provider 1.12.3 against a real org; "(unverified)" = inferred from
+code. The rest was read in api / core / sg-run-controller / workflow-step-templates source.
+
+## 1. Where a rule's body comes from
+
+Each `policies_config[]` rule has exactly one source.
+
+### Inline Tirith (most rules)
+
+```terraform
+policy_vcs_config = {
+  use_marketplace_template = false
+  custom_source = { source_config_kind = "SG_POLICY_FRAMEWORK", source_config_dest_kind = "INLINE" }
+}
+policy_input_data = { schema_type = "TIRITH_JSON", data = jsonencode({ meta = {...}, evaluators = [...], eval_expression = "..." }) }
+```
+
+Omitting `policy_vcs_config` also works (the platform defaults to inline Tirith; live), but
+declaring it keeps config and state describing the same thing. Declare `skip = false` too: until
+September 2026 the platform silently skipped a config rule that lacked either the `skip` key or
+`policy_vcs_config`. Now only `skip = true` disables a rule (from code).
+
+### Tirith from git
+
+`source_config_kind = "SG_POLICY_FRAMEWORK"` + a git `source_config_dest_kind` + `config`. The file
+**must be named `tirith.json`** inside `working_dir`. Git-hosted Tirith is runtime-only: config
+rules (`stackguardian/json`) must be inline.
+
+### OPA / Rego from git
+
+```terraform
+custom_source = {
+  source_config_kind      = "OPA_REGO"
+  source_config_dest_kind = "GITHUB_COM"            # never INLINE
+  config = { repo = "https://github.com/acme/opa", ref = "main", working_dir = "terraform", is_private = true, auth = "/integrations/github_com" }
+  additional_config = jsonencode({ opaQuery = "terraform.guardrails.allow" })
+}
+```
+
+- The step runs `opa eval --data <working_dir> --input tf_plan.json data` with **OPA 0.55** (Rego v0:
+  use `import future.keywords.if` / `…contains`; `import rego.v1` needs OPA ≥ 0.59 and fails to parse). `input` is the plan JSON
+  (`input.resource_changes`, `input.planned_values`, `input.configuration`).
+- `opaQuery` is a dotted path relative to `data`, **without** `data.`: `package terraform.guardrails`
+  + rule `allow` → `terraform.guardrails.allow`. It must be a boolean (`default allow = false`);
+  `deny[msg]` sets, strings or an undefined rule → `on_fail`.
+- **No `opaQuery` → every Rego policy passes** unless OPA itself errors.
+- Provider bug (live): `additional_config` is stored but read back as null → first apply ends with
+  *Provider produced inconsistent result after apply* and the policy is tainted. Then:
+  `terraform untaint <address>` and `lifecycle { ignore_changes = all }`; change the policy only with
+  `terraform apply -replace=<address>` (and untaint again). Verify the stored `additionalConfig`
+  afterwards (MCP `get_orchestrator_resource_by_id` or the API).
+  - `ignore_changes = [policies_config]` is **unsafe** (live): the next change to description, tags,
+    scope or approvers PATCHes the rules from state (`additional_config = null`) and the server
+    drops `opaQuery` — the Rego policy silently passes everything from then on.
+  - Without any `ignore_changes`, every apply re-sends `opaQuery` and reports the inconsistent
+    result again (from code) — safe but noisy.
+  - Managing OPA policies outside Terraform (dashboard / MCP `create_policy`) until the provider is
+    fixed is a reasonable choice.
+- `policy_input_data` (optional) is written into the Rego directory, where OPA should load it
+  under `data` (unverified).
+
+### Git source rules (Tirith or OPA)
+
+- `is_private` is required (`{"isPrivate": ["required"]}`) and so is `repo`; private needs `auth`
+  (`/integrations/<connector>` or `/secrets/<name>` — nothing else matches its pattern);
+  `GIT_OTHER` accepts only `/secrets/`. A `working_dir` that is not a plain relative/absolute path
+  fails with `Invalid Linux file path for working directory.` (from code).
+- Kinds: `GITHUB_COM`, `GITHUB_APP_CUSTOM`, `GITLAB_COM`, `BITBUCKET_ORG`, `AZURE_DEVOPS`,
+  `GIT_OTHER`. The API also accepts `AZURE_DEVOPS_SP` since October 2026, but provider 1.12.3
+  rejects it before the request (`… is not a valid …`). A **private `GITHUB_APP_CUSTOM`** policy repo fails at run
+  (`No credentials exposed to authenticate against private repo …`).
+- The attribute is `include_submodule` here (workflows: `include_sub_module`). Leading/trailing
+  `/` in `working_dir` are stripped (`terraform/` = `terraform`).
+
+### Marketplace policy templates
+
+```terraform
+policy_vcs_config = {
+  use_marketplace_template = true
+  policy_template_id       = "/stackguardian/aws-best-practices-all:2"
+}
+```
+
+- Form `/<owner-org>/<template>:<revision>`, type `IAC_POLICY`. Pin a number (`:latest`/aliases are
+  resolved per run). The id is **not checked at create**: a wrong or deleted template breaks every
+  run in scope (`'<id>' not found. Make sure that it is registered in Marketplace`). Check the
+  revision exists first (e.g. `aws-best-practices-all` has revisions 1 and 2, not 3):
+  `curl -H "Authorization: apikey $KEY" -H "x-sg-orgid: <your-org>" "$STACKGUARDIAN_API_URI/api/v1/templatetypes/IAC_POLICY/stackguardian/aws-best-practices-all:2/"`.
+- No subscription is required; the template must be public, yours, or shared with you.
+- `use_marketplace_template = true` without `policy_template_id` → `{"policyTemplateId": ["required
+  when useMarketplaceTemplate"]}`; `false` without `custom_source` → `{"customSource": ["required
+  when not useMarketplaceTemplate"]}` (from code).
+- StackGuardian's bundles are checkov (`SG_INTERNAL_P2`) run on the plan; templates with an input
+  schema ignore your `policy_input_data`.
+- The dashboard also stores a `policyTemplate` field; the provider has no such attribute and does
+  not need it.
+
+## 2. Scope — `enforced_on`
+
+Resolved fresh at every workflow create/update and every run build, by **exact string match**
+(no validation, no existence check):
+
+| Entry | Matches |
+|---|---|
+| `"*"` | every workflow and stack of the org — use it alone |
+| `/wfgrps/<g>` | the group and everything under it (each ancestor prefix of a workflow's group path is tried) |
+| `/wfgrps/<parent>/<child>` | a nested group (flat path, not `/wfgrps/p/wfgrps/c`) |
+| `/wfgrps/<g>/wfs/<wf>` | one workflow |
+| `/wfgrps/<g>/stacks/<s>` / `…/stacks/<s>/wfs/<wf>` | a stack (with its workflows) / one stack workflow |
+| `/integrations/<c>` | workflows with that connector in any `deployment_platform_config[].config.integration_id` |
+| `/integrationgroups/<g>` or `/integrationgroups/<g>/integrations/<c>` | connector-group scopes |
+
+- Effective policies = union of all matches; a narrower scope cannot relax a broader one.
+- `[]` or no attribute → **nothing**. Legacy policies stored without the attribute appear to be
+  treated as org-wide until touched (from code).
+- A typo (`/wfgrps/platfrom`, trailing `/`, `/orgs/...`, a bare workflow name) matches nothing and
+  nobody tells you — build entries from resource ids.
+- Workflows in the internal `__SG_OWNED__` group are exempt.
+
+## 3. Verdicts
+
+- `on_fail` applies when the rule evaluates false; `on_pass` when it evaluates true **or is fully
+  skipped**. Values: `FAIL` (block), `WARN` (record, continue), `PASS`, `APPROVAL_REQUIRED`.
+  They are remappings, not severities: `on_pass = "FAIL"` inverts a rule, `on_fail = "PASS"`
+  disables it (use `skip = true` instead).
+- Both are required by the API: omitting `on_pass` → `400 PoliciesConfig[0].onPass: "" is not a
+  valid choice.` (live).
+- Within one rule, results combine as FAIL > WARN > APPROVAL_REQUIRED > PASS. Across rules: any
+  FAIL errors the run (before any approval is requested); otherwise any APPROVAL_REQUIRED pauses it —
+  a WARN elsewhere does not suppress the approval.
+- Runtime results land in the run's `PolicyEvalResults`; config-time results in
+  `PolicyEvalResults.configPoliciesEvaluated.<policy>.rules.<rule>` on the workflow (a config-time
+  `WARN` shows there as `warned`; the API/Terraform caller sees nothing).
+- Config-time 403 text: `Workflow policy (<policy>:<rule>) failed: Expression: <expr> | <evaluator
+  messages>`, or `requires approval` in place of `failed`; several rules are joined by newlines.
+  Stacks say `Stack policy (…)` (from code).
+- A crash inside Tirith (bad provider, bad document, unresolvable `${…}` reference) → `on_fail` at
+  runtime, a block at config time (`Tirith evaluation error: …`).
+
+## 4. Approvals
+
+- Policy-level: `approvers` + `number_of_approvals_required` are shared by every rule of the
+  policy. `N` = N distinct approvers; `0` = **all** listed approvers; a count larger than the list
+  never completes. Any rejection cancels the run.
+- Approvers: lowercase emails, `<userpool>/<idp>/<email>`, or SSO groups `<userpool>/group/<id>`.
+- Runtime `APPROVAL_REQUIRED` gates the **next** step (normally `apply`); if the plan step is the
+  last one (plan-only runs, PR plans) nothing pauses.
+- Config-time `APPROVAL_REQUIRED` is a 403 on workflow create/update and an approval gate before
+  step 0 at run time.
+- Without approvers the run still pauses; with an empty approver map anyone with approve permission
+  can release it (sg-run-controller main), and the executor is emailed. Always set approvers.
+- Runtime approvals match `/policies/<resource_name>` against the policy's id: keep `resource_name`
+  a slug, don't set a different `id`, and don't rename a policy that uses APPROVAL_REQUIRED — any of
+  these makes approvers never match.
+- The platform's own "approve before apply" for plans with changes is
+  `terraform_config.approval_pre_apply` on the workflow, not a policy.
+
+## 5. Provider behaviour (`stackguardian_policy`, 1.12.3)
+
+| Topic | Behaviour |
+|---|---|
+| Validation | none; enums are parsed at apply: `Fail to convert policyConfig terraform type to go type` / `<v> is not a valid …` |
+| `policy_type` | only `"GENERAL"` (hardcoded on create/update/read). `FILTER.INSIGHT` → inconsistent result |
+| Omitted `enforced_on`, `tags`, `approvers`, `description`, `policies_config` | sent as `null` whenever anything else changes → cleared server-side (live: scope wiped to `[]`). Always declare them |
+| `on_fail` / `on_pass` | optional in HCL, required by the API (400 when missing, live) |
+| `policy_input_data.data` | must be a JSON **object** string (`jsonencode`); invalid JSON fails at apply; read back re-marshalled with sorted keys |
+| `additional_config` | inconsistent result (see §1 OPA) |
+| Empty values | `tags = []`, `approvers = []`, `enforced_on = []`, `description = ""` round-trip (live); `policies_config = []` → inconsistent result (live) |
+| `id` | derived from `resource_name` (verbatim when it is a slug, else random-suffixed); renaming `resource_name` is in place and keeps the id; changing `id` forces replacement |
+| API limits (from code) | `resource_name` ≤ 100 chars, `description` ≤ 512 (the provider docs say 256), `tags` ≤ 10, `policies_config` ≤ 25 rules. A rule `name` must be a slug (`[-a-zA-Z0-9_]`, 1–100) or the API returns 400 — the 1.12.3 docs call it free-form |
+| `context_tags` | the API has `ContextTags` on a policy; the provider has no attribute for it. `${curr_workflow.attrs.ContextTags.<k>}` references read the *workflow's* context tags |
+| Import | `terraform import stackguardian_policy.x <policy-id>` |
+| Out-of-band delete | dropped from state on refresh |
+| Destroy | hard delete; new runs and workflow writes stop seeing it immediately (runs already built keep a snapshot). The dashboard refuses to delete a policy that still has scope; the API does not |
+
+## 6. Rolling out safely
+
+- A config rule in scope blocks `terraform apply` of the `stackguardian_workflow_*` resources it
+  judges (`403 Workflow policy (<policy>:<rule>) failed: Expression: … | …`, live) — including in
+  the same Terraform run that creates the policy. Create/fix workflows first (`depends_on` on the
+  policy makes it land after them in one apply; later updates are still judged), or roll out with
+  `on_fail = "WARN"`.
+- Existing groups/workflows: keep the path in a local, build the scope from it, and add a data source
+  on the same local as an existence check (a typo then fails at plan). Don't interpolate
+  `data.stackguardian_workflow_group.x.id` — for a nested group it is only the leaf (live).
+- Start narrow (`/wfgrps/<test-group>`), use `WARN`, read `PolicyEvalResults` on a few runs, then
+  switch to `FAIL` and widen the scope. `["*"]` hits every team's workflows.
+- There is no enable/disable flag: `skip = true` per rule, or `enforced_on = []`.
+
+## 7. Error catalog
+
+| Message | Cause | Fix |
+|---|---|---|
+| `PoliciesConfig[0].onPass: "" is not a valid choice.` | `on_pass` omitted | set both `on_fail`, `on_pass` |
+| `Fail to convert policyConfig terraform type to go type` | invented enum (`TIRITH_FORMAT`, `BLOCK`, …) | use the documented values |
+| `{"isPrivate": ["required"]}` / `auth required for isPrivate` / `only secrets are supported for GIT_OTHER` | git source config | §1 |
+| `{"sourceConfigDestKind": ["Invalid for OPA_REGO"]}` | OPA with `INLINE` | git kind |
+| `{"ResourceName": ["<x> cannot be used"]}` | reserved name, case-insensitive: any API path word (`orgs`, `wfgrps`, `stacks`, `wfs`, `wfruns`, `policies`, `secrets`, `integrations`, `templates`, `listall`, `logs`, `outputs`, `resume`, …) | rename |
+| `409 Policy ID not unique` | a policy with that id (= slug `resource_name`) already exists | `terraform import` it, or rename |
+| `{"policyTemplateId": ["required when useMarketplaceTemplate"]}` / `{"customSource": ["required when not useMarketplaceTemplate"]}` / `{"repo": ["required"]}` | incomplete `policy_vcs_config` | §1 |
+| `Invalid Linux file path for working directory.` | `working_dir` with unusual characters | plain path |
+| `Enter a valid "slug" …` on `PoliciesConfig[n].name` | rule name with spaces/dots | `[-a-zA-Z0-9_]` |
+| workflow apply: `403 Workflow policy (<p>:<r>) requires approval …` | config rule with `APPROVAL_REQUIRED` | approvals are only granted on runs; use `WARN`/`FAIL` for create/update |
+| `Tirith evaluation error: Failed to resolve reference: …` | a `${…}` reference in a config rule did not resolve | fix the reference (tirith.md §7) |
+| `Provider produced inconsistent result after apply` | `additional_config`, `policy_type` ≠ GENERAL | §1 / GENERAL |
+| workflow apply: `403 Workflow policy (<p>:<r>) failed …` | a config rule rejected the workflow | fix the workflow or the rule |
+| run: `Encountered noncompliant configuration during policy evaluation` | a runtime rule with `on_fail = "FAIL"` | read `PolicyEvalResults` |
+| run: `Tirith run errored during policy evaluation` | unusable provider (`sg_workflow`, `sg_stack`, `kubernetes`, missing), Infracost failure | fix the document |
+| run: `'<id>' not found. Make sure that it is registered in Marketplace` | bad `policy_template_id` | real `/<org>/<name>:<n>` |
+| run: `No match found for "<q>" in OPA results` | `opaQuery` names an undefined rule | package/rule path without `data.` |
diff --git a/skills/sg-writing-stackguardian-policy-terraform/references/tirith.md b/skills/sg-writing-stackguardian-policy-terraform/references/tirith.md
new file mode 100644
index 0000000..fc9f60e
--- /dev/null
+++ b/skills/sg-writing-stackguardian-policy-terraform/references/tirith.md
@@ -0,0 +1,197 @@
+# Tirith (the policy document)
+
+The platform runs **Tirith 1.0.5** in core (config rules); the terraform step template on `main`
+pins **1.0.7** (message/context changes only — same semantics; which image is deployed may lag). Everything below
+was read in that version's source, and the recipes were executed against it. The public GitHub
+`main` of tirith is older/newer than 1.0.5 in places — don't trust other versions' docs blindly.
+
+## 1. Document
+
+```json
+{
+  "meta": { "version": "v1", "required_provider": "stackguardian/terraform_plan" },
+  "evaluators": [
+    { "id": "some_check", "description": "optional",
+      "provider_args": { "operation_type": "attribute", "...": "..." },
+      "condition": { "type": "Equals", "value": "x", "error_tolerance": 0 } }
+  ],
+  "eval_expression": "some_check"
+}
+```
+
+- `meta` is required; an unknown or missing `required_provider` finds no input → **fail**.
+- Keep exactly these three top-level keys. The step only recognises a document whose first key is
+  `meta`, `evaluators` or `eval_expression`; the stored document's key order is not under your
+  control, so any extra top-level key (`description`, `author`, …) risks silently disabling the rule.
+- `error_tolerance` goes **inside** `condition` (default 0); on the evaluator it is ignored.
+- `evaluators` is a flat list: no `operator` key, no nested evaluators. Boolean logic lives only in
+  `eval_expression`. The older `schema_version: "V1.BETA"` / `all_of` / `any_of` / `none_of` shape
+  in some platform docs is not read by any current engine.
+- `meta.version` is echoed, not validated. Other `meta` keys (`name`, `severity`, `tags`) are
+  ignored: a policy has no severity.
+- No schema validation and no variables: `{{ var.x }}` placeholders are never filled → Tirith returns
+  no `final_result` and the terraform plan step crashes, whatever `on_fail` says.
+- Integers only (floats can break the policy create).
+
+## 2. Providers and where they run
+
+| `required_provider` | Input | Evaluated |
+|---|---|---|
+| `stackguardian/terraform_plan` | `terraform show -json` of the plan | runtime, after plan (not on drift runs, not on `plan-without-policy` runs) |
+| `stackguardian/infracost` | the Infracost breakdown | runtime, after plan (Infracost must work; if it fails the rule gets `on_fail`) |
+| `stackguardian/json` | the **workflow definition** | config time: workflow create/update and run build (§7). Also at run time in the **Ansible** step, against the playbook's variables/output — workflow key paths there hit severity 2 (use tolerance 2) |
+| `stackguardian/sg_workflow`, `stackguardian/kubernetes`, `stackguardian/sg_stack`, missing | — | ❌ in the terraform step these fall through to "Tirith run errored" → `on_fail`: with `FAIL` they block **every** Terraform/OpenTofu run in scope. With a `key_path` that names a workflow/stack field, `sg_workflow` and `sg_stack` are also treated as config rules (§7) and always fail there: Tirith 1.0.5 has no `sg_stack` provider ("Could not find input value"), and `sg_workflow` reads only `workflow_attribute`, never `key_path`. No platform step feeds the `kubernetes` provider. Write config rules with `stackguardian/json` |
+
+## 3. `terraform_plan` operation types
+
+| `operation_type` | `provider_args` | Yields |
+|---|---|---|
+| `attribute` | `terraform_resource_type` (or `"*"`), `terraform_resource_attribute` (`acl`, `tags.Env`, `ingress.*.cidr_blocks`), optional `exclude_resource_types` (with `"*"`) | one value per matching resource from `change.after`; values unknown until apply are absent |
+| `action` | `terraform_resource_type` (or `"*"`) | one value per action: `create`, `update`, `delete`, `no-op`, `read` (a replace yields `delete` + `create`). There is no `apply`/`destroy` |
+| `count` | `terraform_resource_type` | integer (0 when absent — no tolerance needed). Counts every change of the type, including deletes and no-ops |
+| `direct_dependencies` | `terraform_resource_type` | resource types in `depends_on` (root module) |
+| `direct_references` | `terraform_resource_type` + exactly one of `references_to` / `referenced_by` (both = severity 99) | `referenced_by`: one boolean per planned resource of the type — is some `referenced_by` resource's config expression referring to it. `references_to`: one boolean — do all resources of the type refer to that type. See the public-access-block recipe (§8) for the limits |
+| `terraform_version` | — | the plan's Terraform version string |
+| `provider_config` | `terraform_provider_full_name` (`registry.terraform.io/hashicorp/aws`; OpenTofu plans say `registry.opentofu.org/hashicorp/aws`), `attribute` = `region` \| `version_constraint` | value from the **first** matching provider config; `region` only when it is a literal there (a variable or aliased providers are skipped/missed) |
+
+`stackguardian/infracost`: `operation_type` `total_monthly_cost` / `total_hourly_cost`,
+`resource_type = ["*"]` (or a list of types; module resources are never matched by a type
+filter; only the first Infracost project is summed).
+
+`stackguardian/json`: only `operation_type = "get_value"` with `key_path` (dots, numeric indexes,
+`*` over lists/dicts). Not found → severity 2.
+
+## 4. Conditions (exact, case-sensitive; unknown type = fail)
+
+These 13 are the whole set. There is no `In`, `Exists`, `Matches`, `StartsWith` or
+`NotRegexMatch`: use `ContainedIn`, `IsNotEmpty`, `RegexMatch "^x"`, or `!` in `eval_expression`.
+
+| type | Passes when |
+|---|---|
+| `Equals` / `NotEquals` | equal / not equal (lists and dicts compared order-insensitively; no type coercion: `"true"` ≠ `true`) |
+| `Contains` / `NotContains` | the **found** value contains yours: substring, list element, dict key (scalar value) or dict subset (dict value). A list value is one element, not a subset |
+| `ContainedIn` / `NotContainedIn` | the found value is (not) in **your** list — allow-list / deny-list. A list-valued found value (e.g. `tags`, `ingress.*.cidr_blocks`) is one element, so `ContainedIn` is then always false; a string `value` means substring |
+| `GreaterThan`, `GreaterThanEqualTo`, `LessThan`, `LessThanEqualTo` | Python comparison (strings compare lexicographically, booleans as 0/1; None / type mismatch = fail) |
+| `IsEmpty` / `IsNotEmpty` | `None`, `""`, `[]`, `{}` count as empty; numbers and booleans are never "not empty" |
+| `RegexMatch` | Python `re.search` on strings (lists/dicts are stringified); numbers, booleans and None fail |
+
+## 5. Tolerance, skips and the verdict
+
+Each missing-data case has a severity; `severity > error_tolerance` → that input **fails**,
+otherwise it is **skipped**.
+
+| Severity | Meaning |
+|---|---|
+| 0 | nothing to check: empty plan, or the resource is being deleted (`after = null`) — always skipped |
+| 1 | resource type (or provider) not in the plan |
+| 2 | attribute / key_path missing |
+| 3 | config time only: the key_path's root is absent from the payload (forced skip) |
+| 99 | malformed rule — always fails |
+
+- A skipped evaluator is **removed** from `eval_expression` (`a && b` with `b` skipped → `a`). If
+  everything is skipped the rule's result is empty, which counts as a **pass** (so `on_pass` applies —
+  with `on_pass = "FAIL"` a fully skipped rule blocks).
+- **1.0.5 bug:** within one evaluator the *last* non-passing resource wins, so a tolerated skip
+  after a violation erases it (e.g. a violating ACL and a deleted ACL in the same plan, or
+  `error_tolerance = 2` over resources where some lack the attribute). `action` and `count` are
+  unaffected. Keep attribute rules type-specific with tolerance 1 where possible.
+
+## 6. `eval_expression`
+
+- Operators: `&&`, `||`, `!`, parentheses. Ids are substituted by word boundary, then all spaces are
+  removed.
+- `a and b` becomes an undefined symbol that is dropped → **silent pass**.
+- An id that is a hyphen-prefix of another (`acl-ok`, `acl-ok-2`) makes the expression evaluate to
+  `-1`, which the platform treats as a **pass**: the longer id's evaluator is silently ignored (at
+  run time and at config time). Use snake_case ids, none a prefix of another. (Dashboard-made policies use
+  `eval-id-1`, `eval-id-2`, … — fine as long as no id prefixes another.)
+- Every id referenced must exist (undefined ids are dropped silently); unreferenced evaluators are
+  ignored.
+
+## 7. Config-time documents (`stackguardian/json`)
+
+The rule is evaluated only if its `key_path` contains a workflow field name (the heuristic list:
+`ResourceName, Description, Tags, IsActive, WfStepsConfig, WfType, TerraformConfig, TerraformAction,
+EnvironmentVariables, DeploymentPlatformConfig, VCSConfig, UserSchedules, UserJobCPU, UserJobMemory,
+VCSTriggers, MiniSteps, Approvers, NumberOfApprovalsRequired, RunnerConstraints, ContextTags, …`).
+
+| Moment | Document |
+|---|---|
+| workflow create | the request: `ResourceName, Description, Tags, WfType, VCSConfig, TerraformConfig, EnvironmentVariables, DeploymentPlatformConfig, RunnerConstraints, MiniSteps, Approvers (strings), UserSchedules, ContextTags, …` |
+| workflow update | stored workflow merged with the patch |
+| run build | workflow + `TerraformAction = { action = apply\|plan\|destroy\|plan-destroy\|refresh }`; `Approvers` becomes a list of objects (`Approvers.*.email`) |
+
+Verified key paths: `TerraformConfig.managedTerraformState`, `TerraformConfig.terraformVersion`,
+`TerraformConfig.approvalPreApply`, `TerraformConfig.driftCheck`, `WfType`, `Tags`,
+`ContextTags.<key>`, `DeploymentPlatformConfig.*.config.integrationId`, `RunnerConstraints.type`,
+`VCSConfig.iacVCSConfig.iacTemplateId`, `VCSConfig.iacInputData.data.<var>`,
+`EnvironmentVariables.*.config.varName`, `TerraformAction.action` (run only).
+
+Choose the tolerance per rule: `2` skips workflows that lack the sub-key — which also skips a
+TERRAFORM workflow that merely omitted a setting whose server default is the unsafe value. When
+"missing" should count as a violation, use tolerance 1 and exempt the workflow types that
+legitimately lack the key in `eval_expression` (the managed-state recipe below). The forced skip
+(severity 3) only applies when the key's **root** (`TerraformConfig`) is absent from the payload.
+At config time `WARN` is recorded as `warned` in the workflow's
+`PolicyEvalResults.configPoliciesEvaluated` (visible in the dashboard, not to the API/Terraform caller); `APPROVAL_REQUIRED` is a 403 on create/update and an approval
+gate before the first step at run time.
+
+**Stacks** (from code): a `json` rule whose `key_path` names a stack field (`WorkflowsConfig`,
+`Actions`, `TemplateGroupId`, `TemplatesConfig`, `Operations`, `WorkflowRelationsMap`, …) is also
+evaluated at stack create and stack run. Fields both lists share (`ResourceName`, `Description`,
+`Tags`, `IsActive`, `EnvironmentVariables`, `DeploymentPlatformConfig`, `UserSchedules`,
+`MiniSteps`, `ContextTags`) make the rule judge workflows **and** stacks in scope.
+
+**References** (resolved by the platform before Tirith runs; from code, not executed here):
+
+| Syntax | Value |
+|---|---|
+| `${curr_workflow.attrs.<path>}` / `${curr_stack.attrs.<path>}` | a field of the workflow / stack being judged (in a `key_path` it limits the rule to workflows / stacks) |
+| `${workflow::<group>.<workflow>.attrs.<path>}` | a field of another workflow (nested group: `parent/child` before the dot) |
+| `${workflow::<group>.<stack>.<workflow>.attrs.<path>}` | a workflow inside a stack |
+| `${stack::<group>.<stack>.attrs.<path>}` | a field of a stack |
+
+- Allowed in `key_path` (with `get_value`; the resolved string becomes the *value* checked) and in
+  a string `condition.value`. Innermost `${…}` resolves first, so references nest.
+- An unresolvable reference, a missing workflow, or a falsy/non-string value raises `Tirith
+  evaluation error: Failed to resolve reference: …` → the rule **blocks** every workflow in scope.
+  Prefer plain key paths unless you need another resource's state.
+- In HCL escape the dollar: `"$${curr_workflow.attrs.ContextTags.env}"`. A bare `"${…}"` is a
+  Terraform interpolation and fails at plan.
+
+## 8. Verified recipes
+
+All executed on Tirith 1.0.5 with passing and failing inputs (`examples/`; the public-access-block
+and Terraform-version recipes against hand-built plan / workflow JSON only):
+
+| Goal | Evaluator |
+|---|---|
+| No public S3 ACL | `attribute`, `aws_s3_bucket_acl`, `acl`, `NotContainedIn ["public-read","public-read-write","authenticated-read"]`, tol 1 |
+| Public access block on | `attribute`, `aws_s3_bucket_public_access_block`, `block_public_acls`, `Equals true`, tol 1 |
+| Tag key present | `attribute`, `<type>`, `tags`, `Contains "CostCenter"`, tol 1 |
+| Tag key = value | `attribute`, `<type>`, `tags`, `Contains { Environment = "production" }`, tol 1 |
+| No world-open ingress | `attribute`, `aws_vpc_security_group_ingress_rule`, `cidr_ipv4` `NotEquals "0.0.0.0/0"` and `cidr_ipv6` `NotEquals "::/0"`, tol 1 (tol 2 lets the skip-erasure bug hide violations; a cidr unknown at plan then fails — safe side). Legacy inline rules: `aws_security_group`, `ingress.*.cidr_blocks`, `NotContains`. Not `aws_security_group_rule` `cidr_blocks`: it matches egress rules too, so the usual allow-all egress fails |
+| Every bucket has a public access block | `direct_references`, `aws_s3_bucket`, `referenced_by = "aws_s3_bucket_public_access_block"`, `Equals true`, tol 1. Only for single (no `count`/`for_each`) buckets: the plan address `aws_s3_bucket.b[0]` never matches the config reference `aws_s3_bucket.b`, so those always fail. Deleting a bucket fails too (1.0.5 skips `["destroy"]`, but plans say `delete`). Roll out with `on_fail = "WARN"` |
+| Pinned Terraform version | `json`: `is_custom` (`WfType`, `Equals "CUSTOM"`, tol 2) `\|\|` `tf_version_ok` (`TerraformConfig.terraformVersion`, `RegexMatch "^1\\.(5\|9)\\."` as written in HCL, tol 1) — a TERRAFORM/OPENTOFU workflow without a version fails |
+| EU regions only | `provider_config`, `region`, `ContainedIn [...]`, tol 2 — two evaluators, `registry.terraform.io/hashicorp/aws` and `registry.opentofu.org/hashicorp/aws`, joined with `&&` |
+| Allowed instance types | `attribute`, `aws_instance`, `instance_type`, `ContainedIn [...]`, tol 1 |
+| Max N buckets | `count`, `aws_s3_bucket`, `LessThanEqualTo N` (deletes and no-ops count too) |
+| Approval on any delete/replace | `action`, `"*"`, `NotContainedIn ["delete"]`, tol 1, `on_fail = "APPROVAL_REQUIRED"` |
+| Approval on any change | `action`, `"*"`, `ContainedIn ["no-op","read"]`, `on_fail = "APPROVAL_REQUIRED"` |
+| Monthly cost ≤ 500 | `infracost`, `total_monthly_cost`, `resource_type = ["*"]`, `LessThanEqualTo 500` |
+| Managed state required | `json`: `is_custom` (`WfType`, `Equals "CUSTOM"`, tol 2) `\|\|` `uses_managed_state` (`TerraformConfig.managedTerraformState`, `Equals true`, tol 1) — a TERRAFORM workflow that omits the key (server default: unmanaged) fails, CUSTOM passes |
+| Approved connectors only | `json`, `DeploymentPlatformConfig.*.config.integrationId`, `ContainedIn [...]`, tol 2 (workflows with no connector pass; add `DeploymentPlatformConfig` `IsNotEmpty` if every workflow must have one) |
+| Private runners only | `json`, `RunnerConstraints.type`, `Equals "private"`, tol 1 — a workflow that omits the runner (server default: shared) fails |
+| Approval before destroy runs | `json`, `TerraformAction.action`, `NotContainedIn ["destroy","plan-destroy"]`, **tol 2** (CUSTOM runs carry no action), `on_fail = "APPROVAL_REQUIRED"` (skipped at create/update, gates step 0 at run) |
+
+Test a document locally before shipping it (PyPI has no installable py-tirith files; install the
+tag the platform pins):
+
+```bash
+pip install "git+https://github.com/StackGuardian/tirith.git@1.0.5"
+terraform show -json tfplan > plan.json            # a real plan of the workflow's IaC
+tirith -policy-path policy.json -input-path plan.json --json
+```
+
+For config rules, pass a JSON file shaped like the workflow payload in §7 as `-input-path` (the
+CLI does not apply the platform's severity-3 forced skip or its "no result = allow" mapping).
diff --git a/skills/sg-writing-stackguardian-workflow-group-terraform/SKILL.md b/skills/sg-writing-stackguardian-workflow-group-terraform/SKILL.md
new file mode 100644
index 0000000..02a8d15
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-group-terraform/SKILL.md
@@ -0,0 +1,124 @@
+---
+name: sg-writing-stackguardian-workflow-group-terraform
+description: Use when writing, reviewing or debugging Terraform/OpenTofu HCL for StackGuardian workflow groups (stackguardian_workflow_group) — nested groups, group ids vs display names, referencing a group from workflows, policies, chaining or runtime references, importing existing groups — or when a group create fails with "Workflow Group ID not unique", a nested group fails to create, a group has a random suffix, or destroy fails with "Workflow Group not empty".
+---
+
+# Writing StackGuardian workflow group Terraform
+
+## Overview
+
+A workflow group is a folder for workflows and stacks and the usual unit of access control.
+Groups nest with `/`. Provider `StackGuardian/stackguardian` **1.12.3**; setup (source address,
+`api_uri`) is in **sg-writing-stackguardian-workflow-terraform**. Facts marked **(live)** were
+reproduced against a real org.
+
+## Core pattern
+
+```terraform
+resource "stackguardian_workflow_group" "platform" {
+  id            = "platform"                 # set it: the route id everything else uses
+  resource_name = "Platform"                 # display name, free text
+  description   = "Shared platform infrastructure" # <= 255
+  tags          = ["platform"]               # <= 10; never tags = [] on a group (inconsistent result)
+}
+
+resource "stackguardian_workflow_group" "networking" {
+  id            = "${stackguardian_workflow_group.platform.id}/networking" # nested: "platform/networking"
+  resource_name = "Networking"               # leaf display name (live)
+}
+
+resource "stackguardian_workflow_git" "vpc" {
+  workflow_group_id = stackguardian_workflow_group.networking.id # bare id, full path when nested
+  # ...
+}
+```
+
+## Discover existing groups first (StackGuardian MCP)
+
+If the StackGuardian MCP server is connected, list groups before creating or referencing one:
+`search_orchestrator_resources(resourceTypes=["WORKFLOW_GROUP"], searchQuery="<name>",
+fields=["ResourceId","ResourceName","SubResourceId","ParentId","OrgId"])`.
+
+- **`SubResourceId`** is the full path: `/wfgrps/PROD/GCP-4jc2fd3k` → `workflow_group_id =
+  "PROD/GCP-4jc2fd3k"`, import id `PROD/GCP-4jc2fd3k`, policy scope as-is. `ResourceId` is only the
+  leaf; `ResourceName` is the display name (ids often carry random suffixes).
+- An id you plan to create that already exists → import it instead (create would 409).
+- `search_workflows(parentId="/orgs/<org>/wfgrps/<path>")` shows what lives in a group before you
+  delete or re-scope it.
+- Check `OrgId = "/orgs/<STACKGUARDIAN_ORG_NAME>"`; use read tools only. Without MCP: ask for the id and
+  add a `data "stackguardian_workflow_group"` existence check.
+
+## Ids
+
+- `id` set → used verbatim (slug `^[A-Za-z0-9_-]+$`; a nested id is `parent/child`). Changing it
+  replaces the group **and every workflow referencing it**: `workflow_from_template` workflows are
+  destroyed and recreated (SG-managed state and run history lost), `workflow_git` ones end in
+  *inconsistent result* and keep the old group non-empty. Treat group ids as permanent.
+- `id` omitted → derived from `resource_name`: kept as-is when slug-shaped, otherwise lowercased
+  with a random suffix (`"Platform Team"` → `platform-team-x7k2lm9q4n1d`). Always set `id` when the
+  name is not a slug.
+- Nested without `id`: `resource_name = "${parent.id}/networking"` also works, but the full path
+  becomes the display name (live). Prefer the `id` + leaf `resource_name` form above. Without `id`,
+  any `/` in `resource_name` means nesting (`"Dev/Test"` looks for a parent `Dev` → 409); with `id`
+  set, the display name may contain `/`.
+- The parent must exist first; referencing `parent.id` orders creation. The dashboard stops at a
+  depth of 10.
+- Groups created in the dashboard often have ids like `gitops-y8pf2mb1` (name + random suffix):
+  look them up by id, never assume id = name.
+
+## How other resources reference a group
+
+| Where | Form |
+|---|---|
+| `workflow_group_id` on workflows | `stackguardian_workflow_group.x.id` → `platform/networking` (resource, or a literal/local full path — never `data.<group>.id` for a nested group, see below) |
+| `stackguardian_policy.enforced_on` | `"/wfgrps/${stackguardian_workflow_group.x.id}"` — covers nested groups, stacks and workflows below; no trailing slash |
+| `mini_steps.wf_chaining.*.workflow_group_id` | bare id (`platform/networking`) |
+| `${workflow::<group>.<wf>.outputs...}` run-time reference | bare id, `/` kept; in HCL escape the `$`: `"$${workflow::platform/networking.vpc.outputs.vpc_id.value}"` |
+| `data "stackguardian_workflow_outputs"` | `workflow_group = stackguardian_workflow_group.x.id` |
+| role `allowed_permissions` paths | group **ids** (full path when nested), not `/wfgrps/...` and not display names; the values are regexes full-matched against the group path, so `["platform"]` does not cover `platform/networking`: grant both `platform` and `platform/.*` (the form StackGuardian's own Terraform modules use, from code), or list the children. The lists are positional: `<wf>`, `<wfRun>` … lists in the same permission need one entry per `<wfGrp>` entry (pad with `".*"`) |
+| import id | `platform/networking` |
+
+A workflow whose `workflow_group_id` names a group that does not exist is **still created**: the
+server auto-creates a *top-level* group named after the last path segment (description
+`Automatically created by SG when creating a workflow`, tags `sg-created`, `workflow`), and for a
+nested path the workflow is stored under a parent path that has no group. If a top-level group of
+that name already exists, the create fails with 500 `Workflow Group does not exist and cannot be
+created.` Always reference the group resource (or a literal full path you know exists).
+
+## Lifecycle
+
+| Action | Behaviour |
+|---|---|
+| Create with an id that already exists | 409 `Workflow Group ID not unique` (live). The provider docs claim it adopts the group — it does not. Import it instead |
+| Create that fails with a **400** (description > 255, 11 tags, non-slug `id`, reserved name) | the provider reads the group named by `resource_name` and, if one exists, silently **adopts** it into state — a later destroy deletes a group you never created. Fix the 400 cause; check the plan when names may collide |
+| Reusing the id of a group moved in the dashboard | 409 `A resource used to exist with the same id but was moved to …` — the provider cannot pass `replace-moved-resource`; pick another id |
+| Change `resource_name` | in-place rename |
+| Change `id` | replace (the old group must be empty to delete) |
+| Omit `description`/`tags` while changing anything else | they are **cleared** (Optional+Computed without state carry-over; live plan) — removing them alone shows no diff until some other attribute changes. Keep them declared when the group has values; to clear tags, omit them and change another attribute in the same apply |
+| `tags = []` | *Provider produced inconsistent result after apply*, group tainted (live) — omit `tags` for a group without tags. `description = ""` is fine |
+| Delete | only when empty: `Workflow Group not empty` (400) while any workflow, stack or child group remains. Terraform orders children first within one config (live); workflows created outside Terraform block it. Right after deleting the children the check is eventually consistent — retry |
+| Move a workflow between groups | no in-place move: `terraform apply -replace` (new workflow, managed state lost) or move it in the dashboard and re-import at the new address (workflow skill, lifecycle §4) |
+| Group deleted outside Terraform | dropped from state on refresh and silently re-created on the next apply |
+| Import | `terraform import stackguardian_workflow_group.networking platform/networking`, or an `import` block + `terraform plan -generate-config-out=generated.tf` to get its current name/description/tags written for you |
+| Read an existing group | `data "stackguardian_workflow_group" "x" { id = "platform/networking" }` fails at plan with `Unable to read workflow group.` when it does not exist — use it as an **existence check**. It returns `description` and `tags`, but its `id` is only the **leaf** (`networking`) for nested groups and `resource_name` is null (live). Build references from the path you looked up (`local.net = "platform/networking"`), not from `data.x.id` |
+
+Limits: `resource_name` ≤100 (reserved names such as `wfgrps`, `policies`, `secrets`, `logs`,
+`outputs` are rejected; the check skips `id`, so `id = "listall"` is created but unreachable at
+its own route — from code), description ≤255, tags ≤10 (the dashboard strips every non-word character — `-`, `.`, `:` — from tags it edits;
+Terraform keeps them). The server has no nesting-depth limit; the dashboard stops at 10.
+
+## Common mistakes
+
+| Mistake | What happens |
+|---|---|
+| `resource_name = "Platform Team"` and no `id` | Random-suffixed id; every reference by name breaks |
+| `workflow_group_id = "/wfgrps/platform"` | Wrong: bare id only (`/wfgrps/` is the policy form) |
+| `enforced_on = ["/wfgrps/platform/"]` | Trailing slash: matches nothing |
+| `enforced_on = ["/wfgrps/platform/wfgrps/networking"]` | Not a scope (that shape is only the child-create URL / dashboard tree key): use `/wfgrps/platform/networking` |
+| `workflow_group_id = data.stackguardian_workflow_group.net.id` (nested) | Resolves to the leaf `networking`: wrong/auto-created top-level group (live data-source behaviour) |
+| Hard-coding `workflow_group_id = "platfrom"` | Server auto-creates a junk group `platfrom` |
+| Nested group before its parent exists | 409 `Workflow Group does not exist` — reference `parent.id` |
+| Deleting a group that still has dashboard-created workflows | 400 `Workflow Group not empty` |
+
+Worked example (validated with `terraform validate` and `tofu validate`, applied live):
+`examples/groups.tf`.
diff --git a/skills/sg-writing-stackguardian-workflow-group-terraform/examples/groups.tf b/skills/sg-writing-stackguardian-workflow-group-terraform/examples/groups.tf
new file mode 100644
index 0000000..e626ba7
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-group-terraform/examples/groups.tf
@@ -0,0 +1,54 @@
+# A small group hierarchy, a workflow inside it, and how policies / lookups address groups.
+
+resource "stackguardian_workflow_group" "platform" {
+  id            = "platform"
+  resource_name = "Platform"
+  description   = "Shared platform infrastructure"
+  tags          = ["platform"]
+}
+
+resource "stackguardian_workflow_group" "networking" {
+  id            = "${stackguardian_workflow_group.platform.id}/networking" # -> "platform/networking"
+  resource_name = "Networking"
+  description   = "VPCs, DNS, transit"
+}
+
+resource "stackguardian_workflow_group" "security" {
+  id            = "${stackguardian_workflow_group.platform.id}/security"
+  resource_name = "Security"
+  description   = "Guardrail tooling"
+  # no tags: omit the attribute — tags = [] on a group ends in "inconsistent result"
+}
+
+resource "stackguardian_workflow_git" "dns" {
+  id                = "dns"
+  resource_name     = "DNS zones"
+  workflow_group_id = stackguardian_workflow_group.networking.id # bare id, full nested path
+
+  wf_type = "TERRAFORM"
+  vcs_config = {
+    iac_vcs_config = {
+      custom_source = {
+        source_config_dest_kind = "GITHUB_COM"
+        config                  = { repo = "https://github.com/acme/dns", is_private = false }
+      }
+    }
+  }
+  terraform_config = {
+    terraform_version       = "1.5.7"
+    managed_terraform_state = true
+  }
+}
+
+# A group created elsewhere (dashboard ids often carry a random suffix): look it up by id.
+# data "stackguardian_workflow_group" "legacy" { id = "gitops-y8pf2mb1" }
+
+output "policy_scope_for_platform" {
+  description = "enforced_on form: covers platform, its nested groups and all workflows below"
+  value       = "/wfgrps/${stackguardian_workflow_group.platform.id}"
+}
+
+output "chaining_group_id" {
+  description = "wf_chaining / workflow_group_id / runtime-reference form: the bare id"
+  value       = stackguardian_workflow_group.networking.id
+}
diff --git a/skills/sg-writing-stackguardian-workflow-group-terraform/examples/versions.tf b/skills/sg-writing-stackguardian-workflow-group-terraform/examples/versions.tf
new file mode 100644
index 0000000..e0b7bdd
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-group-terraform/examples/versions.tf
@@ -0,0 +1,17 @@
+terraform {
+  required_version = ">= 1.5"
+
+  required_providers {
+    stackguardian = {
+      # Full address so the same code works under OpenTofu (its registry has no copy).
+      source  = "registry.terraform.io/StackGuardian/stackguardian"
+      version = "~> 1.12.3"
+    }
+  }
+}
+
+# Credentials from the environment:
+#   STACKGUARDIAN_API_KEY   raw key (sgu_/sgo_...), no "apikey " prefix
+#   STACKGUARDIAN_ORG_NAME  org slug
+#   STACKGUARDIAN_API_URI   https://api.app.stackguardian.io (EU) or https://api.us.stackguardian.io (US) — there is no default
+provider "stackguardian" {}
diff --git a/skills/sg-writing-stackguardian-workflow-terraform/SKILL.md b/skills/sg-writing-stackguardian-workflow-terraform/SKILL.md
new file mode 100644
index 0000000..4978b05
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-terraform/SKILL.md
@@ -0,0 +1,217 @@
+---
+name: sg-writing-stackguardian-workflow-terraform
+description: Use when writing, reviewing or debugging Terraform/OpenTofu HCL for StackGuardian workflows (stackguardian_workflow_git, stackguardian_workflow_from_template, workflow templates/revisions, CUSTOM Ansible/Helm/kubectl/CloudFormation steps) — vcs_config, terraform_config, connectors, secrets in env vars, runners and stackguardian_runner_group, schedules, VCS triggers, notifications, chaining, workflow outputs — or when a workflow applies but every run fails, or when migrating old `stackguardian_workflow` + `data = jsonencode(...)` code. Also covers looking up the org's connectors, secrets, runner groups and templates via the StackGuardian MCP server.
+---
+
+# Writing StackGuardian workflow Terraform
+
+## Overview
+
+Provider `StackGuardian/stackguardian` **1.12.3** (Terraform Plugin Framework). Every nested
+structure is an **attribute** (`x = {...}` / `x = [{...}]`), never a block. Facts were verified on
+1.12.3; on a newer provider re-check rules 11 and 12 first (they are provider bugs). The provider
+validates almost nothing, so mistakes show up as: a 400 at apply, *"Provider produced
+inconsistent result after apply"* (the resource is tainted when this happens on create), or a
+workflow that is created and then
+fails every run. Everything below was checked against provider, api, core, run-controller
+and step-template source, and the traps marked **(live)** were reproduced against a real org.
+
+Groups: **sg-writing-stackguardian-workflow-group-terraform**. Guardrails/approvals on plans:
+**sg-writing-stackguardian-policy-terraform**.
+
+## Setup
+
+```terraform
+terraform {
+  required_providers {
+    stackguardian = {
+      source  = "registry.terraform.io/StackGuardian/stackguardian" # full address: the OpenTofu registry has no copy
+      version = "~> 1.12.3"
+    }
+  }
+}
+provider "stackguardian" {} # STACKGUARDIAN_API_KEY, STACKGUARDIAN_ORG_NAME, STACKGUARDIAN_API_URI
+```
+
+`api_uri` has **no default** (live): set `https://api.app.stackguardian.io` (EU) or
+`https://api.us.stackguardian.io` (US). A key from the other region returns 401 (per the provider
+docs).
+
+## Which resource
+
+| Want | Resource |
+|---|---|
+| Workflow whose IaC is in your git repo | `stackguardian_workflow_git` (`wf_type` TERRAFORM / OPENTOFU / CUSTOM) |
+| Workflow from a template revision **owned by your org** | `stackguardian_workflow_from_template` (templates of other orgs, incl. the marketplace, fail — rule 11) |
+| Reusable definition many workflows share | `stackguardian_workflow_template` + `stackguardian_workflow_template_revision` |
+| Ansible / Helm / kubectl / CloudFormation / Terragrunt | `wf_type = "CUSTOM"` + `wf_steps_config` (there is no ANSIBLE/HELM wf_type) |
+| Read a workflow's Terraform outputs | `data "stackguardian_workflow_outputs"` |
+
+`stackguardian_workflow`, `wfgrp`, `data = jsonencode({...})`, `GitHubComSync`, `is_active`,
+`cache_config`, `tfvars_file_path` and `enforced_policies` do not exist in this provider.
+
+## Discover dependencies first (StackGuardian MCP)
+
+Connectors, secrets, runner groups, groups and other workflows must already exist, and wrong ids
+only fail at run time. **If the StackGuardian MCP server is connected, look every one up before
+writing HCL** and offer the user the real options (full mapping: `references/discovery.md`):
+
+| Dependency | MCP call | Value to use |
+|---|---|---|
+| cloud / VCS connector | `search_orchestrator_resources(resourceTypes=["INTEGRATION.CLOUD"])` / `["INTEGRATION.VCS"]` | `ResourceId` (`/integrations/<id>`) → `integration_id` / `auth`; `ResourceType` minus `INTEGRATION.` → `kind` / `source_config_dest_kind`. Never the `ResourceName` |
+| secret | `search_orchestrator_resources(resourceTypes=["SECRET"])` | `/secrets/<name>` → `"$${secret::<name>}"`; missing ones must be created first (`sg-manage-secrets` skill) |
+| private runner group | `search_orchestrator_resources(resourceTypes=["RUNNER"])` | last segment of `/runnergroups/<id>` → `runner_constraints.names` |
+| workflow group | `search_orchestrator_resources(resourceTypes=["WORKFLOW_GROUP"])` | `SubResourceId` minus `/wfgrps/` → `workflow_group_id` (`ResourceId` is only the leaf) |
+| other workflows, their outputs | `search_workflows`, `get_workflow_outputs` | `SubResourceId` `/wfgrps/<g>/wfs/<w>` → chaining, `${workflow::…}`, import id |
+| own / step templates | `search_marketplace_templates`, `get_marketplace_template_by_id`, `get_subscription` | `/<org>/<name>:<n>`, input schema defaults, draft status |
+
+Rows must carry `OrgId = "/orgs/<STACKGUARDIAN_ORG_NAME>"`; use read tools only (don't create via
+MCP what Terraform should own); keep the data sources in the HCL as the plan-time check. Without
+MCP: data sources + ask the user — never invent ids.
+
+## Core template
+
+```terraform
+data "stackguardian_connector" "github" { id = "github_com" } # GITHUB_COM connector id is always github_com
+data "stackguardian_connector" "aws"    { id = "aws-prod-oidc" }
+
+resource "stackguardian_workflow_git" "payments_api" {
+  id                = "payments-api"                           # REQUIRED slug; changing it replaces the workflow (new state!)
+  resource_name     = "Payments API"                           # display name; omit it and the server invents a random one
+  workflow_group_id = stackguardian_workflow_group.prod.id    # bare id, "payments/prod" when nested; never change in place
+  wf_type           = "TERRAFORM"                              # TERRAFORM | OPENTOFU | CUSTOM — immutable
+  description       = "Payments API infrastructure"            # "" fails validate; omit instead
+
+  vcs_config = {
+    iac_vcs_config = {
+      custom_source = {
+        source_config_dest_kind = "GITHUB_COM"                 # must equal the auth connector's kind
+        config = {
+          repo        = "https://github.com/acme/payments-infra"
+          ref         = "main"
+          working_dir = "envs/prod"
+          is_private  = true
+          auth        = "/integrations/${data.stackguardian_connector.github.id}"
+        }
+      }
+    }
+    iac_input_data = {                                         # becomes a .tfvars.json passed to plan
+      schema_type = "RAW_JSON"
+      data        = jsonencode({ region = "eu-central-1", instance_count = 3 })
+    }
+  }
+
+  deployment_platform_config = [{
+    kind   = "AWS_OIDC"                                        # = the connector's kind
+    config = { integration_id = "/integrations/${data.stackguardian_connector.aws.id}" }
+  }]
+
+  environment_variables = [
+    { kind = "PLAIN_TEXT", config = { var_name = "TF_LOG", text_value = "WARN" } },
+    { kind = "PLAIN_TEXT", config = { var_name = "DB_PASSWORD", text_value = "$${secret::payments-db-pass}" } }, # $$ = literal ${
+  ]
+
+  terraform_config = {
+    terraform_version       = "1.5.7"                          # always set; Terraform <= 1.5.7, OpenTofu e.g. "1.11.x"
+    managed_terraform_state = true                             # server default is FALSE; true requires NO backend block in the repo
+    approval_pre_apply      = true
+    drift_check             = true
+    drift_cron              = "0 2 * * ? *"                    # 6-field EventBridge cron, UTC
+  }
+
+  approvers                    = ["alice@acme.com", "bob@acme.com", "carol@acme.com"] # lowercase
+  number_of_approvals_required = 2                                                    # 0 = ALL approvers
+
+  runner_constraints = { type = "shared" }
+  tags               = ["payments", "prod"]
+}
+```
+
+## Rules that bite
+
+1. **Path vs bare ids.** `integration_id`, `auth`: `/integrations/<id>` (or `/secrets/<name>`).
+   `workflow_group_id`, `runner_constraints.names`, `wf_chaining.*`: bare ids. A bare connector id
+   applies fine and every run fails with `Connector <id> does not exist`. Kinds must match the
+   connector: `kind = data.stackguardian_connector.aws.settings.kind` guarantees it.
+2. **Secrets:** `PLAIN_TEXT` + `text_value = "$${secret::<name>}"` (the dashboard's form;
+   `VAULT_SECRET` + `secret_id = "/secrets/<name>"` also works at run, although the 1.12.3 docs
+   call `secret_id` "Not used"; `SECRET_VALUE` from older docs is a 400). The whole value must be the
+   reference. Nothing checks the secret at apply — a missing one fails the run. The provider has
+   no secret resource; create secrets out of band.
+3. **Terraform > 1.5.7** is rejected on create and update (`Terraform 1.9.0 is above the highest
+   managed version (1.5.7)`, live). OpenTofu has no cap. See `references/execution.md` for escape hatches.
+4. **Write every value the server normalizes** or you get *inconsistent result* (live):
+   `terraform_config = {}` (server stamps `1.5.7`), mixed-case approver emails (lowercased).
+   Nested typos (`is_privte`, `terraform_verison`) pass `terraform validate` and are silently
+   dropped (live) — copy attribute names from `references/schema.md`.
+5. **Workflows start inactive** and activate on their first run — including a drift or schedule
+   tick (billed). Outputs are unavailable until then. Creating a workflow never runs it.
+6. **Schedules auto-apply.** `user_schedules` cannot carry run inputs in this provider, so each
+   tick on a TERRAFORM/OPENTOFU workflow is a full `apply` unless `approval_pre_apply = true`.
+7. **Approvals:** `approval_pre_apply` with `approvers = []` lets *anyone* approve; `0` with a list
+   means *everyone*; a plan with no changes completes without asking; any rejection cancels the run.
+8. **Destroying the resource does not destroy infrastructure.** It deletes the workflow, its runs,
+   schedules and SG-managed state. Run a destroy run first (see `references/lifecycle.md`).
+9. **Clearing values on `workflow_git`:** removing `tags`/`approvers` *keeps* them (`[]` clears);
+   removing `description`, `environment_variables`, `mini_steps`, … clears them. **Never just delete
+   `user_schedules`** — the schedules keep firing: set it to `[]` and apply (server deletes them,
+   provider reports a one-time *inconsistent result*, live), then remove the attribute.
+10. **CUSTOM** needs a non-empty `wf_steps_config` (else 201 then every run: `Workflow Steps not set`)
+    and must not have `terraform_config`.
+11. **Provider 1.12.3 bug:** `workflow_from_template` with a template owned by *another* org (every
+    `/stackguardian/...` marketplace template) fails at apply with `Could not read template
+    revision … 401 Unauthorized` (live). Use an own-org copy of the template
+    (`examples/own_template.tf`) or `workflow_git` on the template's repo.
+12. **Template upgrades take two applies** when the new revision is created in the same config:
+    publish the revision first, then point `iac_template_id` at it (same apply → *inconsistent
+    final plan*, live).
+
+## Quick reference
+
+| Topic | Rule / value |
+|---|---|
+| Template id | `iac_template_id = "/<your-org>/<template>:<rev>"`; bare `name:rev` 404s, other orgs' templates 401 (live). The `stackguardian_workflow_template_revision` **data source** is the opposite: bare `<template>:<rev>` (a `/<org>/` prefix returns a misleading 403) |
+| Inherit from template | Omit the attribute. Suppress with top-level `[]`/`{}`; nested `terraform_config` lists/strings **cannot** be suppressed (live) |
+| VCS kinds | `GITHUB_COM`, `GITHUB_APP_CUSTOM`, `GITLAB_COM`, `BITBUCKET_ORG`, `AZURE_DEVOPS`, `AZURE_DEVOPS_SP`, `GIT_OTHER` (auth = `/secrets/<n>` only) |
+| Cloud kinds | `AWS_STATIC`, `AWS_RBAC`, `AWS_OIDC`, `AZURE_STATIC`, `AZURE_OIDC`, `GCP_STATIC`, `GCP_OIDC` — max 1 entry |
+| Private runner | `runner_constraints = { type = "private", names = ["<runner group id>"] }` (exactly one, no `/runnergroups/`) |
+| Step template ids | `/stackguardian/ansible:18`, `kubernetes:13`, `cloudformation:2`, `terragrunt:1`, `terraform:22` |
+| Cron | `min hour dom month dow year`, `?` in dom or dow, UTC. 5-field → 400 |
+| Engine | Terraform ≤ 1.5.7 → `wf_type = "TERRAFORM"`; newer → `wf_type = "OPENTOFU"` with an OpenTofu version ≥ 1.6 (`"1.10.x"`) — a bare version < 1.6 selects the Terraform binary whatever the `wf_type` |
+| Import | `terraform import stackguardian_workflow_git.x <group-id>/<workflow-id>` (nested group ok) |
+| Limits | tags 10, env vars 20, steps 10, lifecycle step lists 5 each, schedules 10, description 512 |
+| Outputs | `jsondecode(data.stackguardian_workflow_outputs.x.data["vpc_id"]).value` |
+
+## Common mistakes
+
+| Mistake | What happens |
+|---|---|
+| `stackguardian_workflow` + `data = jsonencode(...)` | Resource does not exist in 1.x |
+| `wf_group = "web"` / no `id` | Validate error: `workflow_group_id` and `id` are required |
+| `vcs_config { ... }` block syntax | Syntax error — attributes only |
+| `iac_vcs_config.use_marketplace_template` | Not an attribute; the resource type decides |
+| `iac_template_id = "my-tpl:1"` | 404 `Template my-tpl:1 of type IAC does not exist` |
+| `iac_template_id = "/stackguardian/aws-s3-demo-website:16"` | 401 at apply (provider bug, rule 11) |
+| `integration_id = data.stackguardian_connector.aws.id` | Applies; every run fails `Connector aws does not exist` |
+| `terraform_version = "1.9.0"` with `wf_type = "TERRAFORM"` | 400 `… above the highest managed version (1.5.7)` on create and on update |
+| Repo has `backend "s3"` and `managed_terraform_state = true` | Every plan fails `Found more than 1 terraform state backend blocks` |
+| `pre_plan_hooks = ["tflint"]` | No tflint/jq/cloud CLIs in the image (busybox `sh`), and hooks start outside the repo: `cd "$MOUNTED_IAC_SOURCE_CODE_DIR" && …`, install tools via curl or use a step |
+| Changing `workflow_group_id` of a `workflow_git` | Inconsistent result; workflow stays in the old group (live). Use `-replace` |
+| `terraform_config = {}` / `approvers = ["Bob@X.com"]` | Inconsistent result, resource tainted on create (live) |
+| Typo in a nested attribute (`is_privte = true`) | Passes validate, silently dropped → 400 `isPrivate required` or a server default (live) |
+| Deleting the `user_schedules` attribute | Schedules keep firing applies; set `[]` first (rule 9) |
+| `cmd_override` on a shared runner | The string is passed as the ECS container command, which expects a list — the run is expected to fail (unverified); use it on private runners |
+| `user_schedules` on a prod TERRAFORM workflow without approval | Unattended `apply` every tick |
+| `email.completed` / `email.cancelled` recipients | Stored, but the run controller only emails on errored, approval_required, drift_detected |
+| Step-level `environment_variables` in `wf_steps_config` | Stored, never injected — put variables at workflow level |
+| `terraform destroy` to tear down infra | Infra orphaned, state deleted |
+| Destroying a published (`is_public = "1"`) template revision | Refused until an applied `deprecation` has an `effective_date` in the past — epoch **milliseconds** as a string (live; `references/sources-and-templates.md` §3) |
+
+## References (read when needed)
+
+- `references/sources-and-templates.md` — VCS kinds/auth matrix, templates, inheritance, upgrades, own templates/revisions, custom runtime images.
+- `references/execution.md` — wf_type rules, versions, managed state, inputs, hooks, lifecycle steps, CUSTOM steps and their inputs, env vars and runtime references, connectors, runners (incl. managing connector / runner group resources), sizing, approvals.
+- `references/automation-and-outputs.md` — schedules, drift, VCS triggers, notifications, webhooks, chaining, outputs.
+- `references/lifecycle.md` — create/update/clear semantics, replacement, import, destroy, error catalog.
+- `references/schema.md` — exact attribute tree of every workflow-side resource and the runner group (provider 1.12.3).
+- `examples/*.tf` — validated with `terraform validate` and `tofu validate`; see `examples/README.md`.
diff --git a/skills/sg-writing-stackguardian-workflow-terraform/examples/README.md b/skills/sg-writing-stackguardian-workflow-terraform/examples/README.md
new file mode 100644
index 0000000..788ed02
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-terraform/examples/README.md
@@ -0,0 +1,21 @@
+# Examples
+
+Each file is a self-contained root module when combined with `versions.tf` (validate them one at a
+time: several files declare the same data source names). All pass `terraform validate` (1.14) and
+`tofu validate` (1.9) against provider 1.12.3 exactly; `~> 1.12.3` also accepts later 1.12.x
+patches, which these notes were not checked against. The ones marked
+**applied** were also applied against a real org (group/template names prefixed, connectors and
+runners swapped for existing ones, schedules disabled), re-planned with no changes, and destroyed.
+
+| File | Scenario | Verified |
+|---|---|---|
+| `git_terraform.tf` | Private GitHub repo via connector, AWS OIDC, managed state, 2-of-3 approval, `${secret::}` env var, nightly drift, hook, error/drift email, private runner, nested group | applied |
+| `git_vcs_triggers.tf` | GitLab push → apply with approval, PR → plan, file filters | validate only (registers a real webhook) |
+| `automation_opentofu.tf` | OpenTofu 1.11.x, weekday schedule, completion webhook with a secret HMAC key, error email, chaining to a CUSTOM workflow | applied |
+| `custom_steps.tf` | CUSTOM: Ansible (`ansible:18`), Helm (`kubernetes:13`) with step approval, CloudFormation change set (`cloudformation:2`) | applied |
+| `own_template.tf` | Own template + revision with input schema; one workflow inheriting everything, one overriding/suppressing | applied (+ upgrade to a 2nd revision). Its revision is published, so `terraform destroy` needs a `deprecation` with a past `effective_date` applied first (`references/sources-and-templates.md` §3) |
+| `outputs_and_references.tf` | `${workflow::…outputs…}` run-time reference; plan-time `stackguardian_workflow_outputs` | applied (data source verified to fail before the first run) |
+
+Replace the placeholder ids (`acme`, `aws-prod-oidc`, `prod-runners`, repo URLs) with yours.
+Connector and runner-group data sources fail at plan when the id does not exist — that is on
+purpose.
diff --git a/skills/sg-writing-stackguardian-workflow-terraform/examples/automation_opentofu.tf b/skills/sg-writing-stackguardian-workflow-terraform/examples/automation_opentofu.tf
new file mode 100644
index 0000000..152d62c
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-terraform/examples/automation_opentofu.tf
@@ -0,0 +1,98 @@
+# OpenTofu workflow from a public repo with a weekday schedule, a completion webhook,
+# error email, and a chained follow-up workflow that runs after every successful run.
+
+resource "stackguardian_workflow_group" "web" {
+  id            = "web"
+  resource_name = "web"
+}
+
+resource "stackguardian_workflow_git" "cdn_invalidate" {
+  id                = "cdn-invalidate"
+  resource_name     = "CDN invalidation"
+  workflow_group_id = stackguardian_workflow_group.web.id
+  wf_type           = "CUSTOM"
+
+  vcs_config = {
+    iac_vcs_config = {
+      custom_source = {
+        source_config_dest_kind = "GIT_OTHER"
+        config = {
+          repo       = "https://github.com/acme/web-scripts"
+          is_private = false # public repo: no auth needed
+        }
+      }
+    }
+  }
+
+  deployment_platform_config = [{
+    kind   = "AWS_RBAC"
+    config = { integration_id = "/integrations/aws-web" }
+  }]
+
+  wf_steps_config = [{
+    name                = "invalidate"
+    wf_step_template_id = "/stackguardian/sg-common-utils:1" # cloud CLIs + shell utils
+    cmd_override        = "aws cloudfront create-invalidation --distribution-id E123EXAMPLE --paths '/*'"
+  }]
+
+  # cmd_override is a plain string: private runners accept it; on shared runners it becomes the
+  # ECS container command, which expects a list.
+  runner_constraints = { type = "private", names = ["prod-runners"] }
+}
+
+resource "stackguardian_workflow_git" "site" {
+  id                = "static-site"
+  resource_name     = "Static site"
+  workflow_group_id = stackguardian_workflow_group.web.id
+  wf_type           = "OPENTOFU"
+
+  vcs_config = {
+    iac_vcs_config = {
+      custom_source = {
+        source_config_dest_kind = "GITHUB_COM"
+        config = {
+          repo        = "https://github.com/acme/static-site"
+          working_dir = "infra"
+          is_private  = false
+        }
+      }
+    }
+    iac_input_data = {
+      schema_type = "RAW_JSON"
+      data        = jsonencode({ bucket_name = "acme-site", region = "eu-west-1" })
+    }
+  }
+
+  terraform_config = {
+    terraform_version       = "1.11.x" # OpenTofu: any >= 1.6; ".x" = newest patch
+    managed_terraform_state = true
+    approval_pre_apply      = false
+  }
+
+  # Each tick is a full, unattended apply (the provider cannot attach plan-only run inputs) —
+  # acceptable for this static site; on prod infrastructure set approval_pre_apply = true.
+  user_schedules = [{
+    cron  = "0 8 ? * MON-FRI *" # 08:00 UTC Mon-Fri
+    state = "ENABLED"
+    desc  = "weekday refresh"
+  }]
+
+  mini_steps = {
+    notifications = {
+      email = { errored = [{ recipients = ["web-team@acme.com"] }] } # completed/cancelled emails are never sent
+    }
+    webhooks = {
+      completed = [{
+        webhook_name   = "deploy-done"
+        webhook_url    = "https://hooks.acme.com/stackguardian"
+        webhook_secret = "$${secret::sg-webhook-hmac}" # HMAC key; never inline (returned unmasked)
+      }]
+    }
+    wf_chaining = {
+      completed = [{
+        workflow_group_id = stackguardian_workflow_group.web.id          # bare ids
+        workflow_id       = stackguardian_workflow_git.cdn_invalidate.id # reference it so it exists first
+      }]
+    }
+  }
+}
diff --git a/skills/sg-writing-stackguardian-workflow-terraform/examples/custom_steps.tf b/skills/sg-writing-stackguardian-workflow-terraform/examples/custom_steps.tf
new file mode 100644
index 0000000..1867255
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-terraform/examples/custom_steps.tf
@@ -0,0 +1,148 @@
+# CUSTOM workflows built from StackGuardian's step templates:
+# an Ansible playbook, a Helm release (with approval) and a CloudFormation change set.
+
+resource "stackguardian_workflow_group" "ops" {
+  id            = "ops"
+  resource_name = "ops"
+}
+
+resource "stackguardian_workflow_git" "configure_servers" {
+  id                = "configure-servers"
+  resource_name     = "Configure servers"
+  workflow_group_id = stackguardian_workflow_group.ops.id
+  wf_type           = "CUSTOM" # no terraform_config on CUSTOM
+
+  vcs_config = {
+    iac_vcs_config = {
+      custom_source = {
+        source_config_dest_kind = "GIT_OTHER" # self-hosted GitLab without a connector
+        config = {
+          repo       = "https://gitlab.example.com/ops/playbooks"
+          ref        = "main"
+          is_private = false
+        }
+      }
+    }
+    iac_input_data = {
+      schema_type = "RAW_JSON"
+      data        = jsonencode({ app_version = "1.4.2" }) # passed to the playbook as --extra-vars
+    }
+  }
+
+  environment_variables = [ # workflow level: step-level env vars are never injected
+    { kind = "PLAIN_TEXT", config = { var_name = "ANSIBLE_HOST_KEY_CHECKING", text_value = "False" } },
+  ]
+
+  wf_steps_config = [{
+    name                = "ansible-playbook"
+    wf_step_template_id = "/stackguardian/ansible:18"
+    wf_step_input_data = {
+      schema_type = "FORM_JSONSCHEMA"
+      data = jsonencode({
+        playbookPath  = "site.yml"
+        ansibleAction = "run" # run | dry-run | check-diff
+        inventoryType = "hosts"
+        inventory     = "inventory/prod.ini"
+      })
+    }
+  }]
+
+  runner_constraints = { type = "shared" }
+}
+
+resource "stackguardian_workflow_git" "ingress" {
+  id                = "ingress-nginx"
+  resource_name     = "ingress-nginx (Helm)"
+  workflow_group_id = stackguardian_workflow_group.ops.id
+  wf_type           = "CUSTOM"
+
+  vcs_config = {
+    iac_vcs_config = {
+      custom_source = {
+        source_config_dest_kind = "GIT_OTHER"
+        config = {
+          repo       = "https://github.com/acme/k8s-charts"
+          is_private = false
+        }
+      }
+    }
+  }
+
+  deployment_platform_config = [{
+    kind   = "AWS_RBAC"
+    config = { integration_id = "/integrations/aws-eks" }
+  }]
+
+  environment_variables = [
+    { kind = "PLAIN_TEXT", config = { var_name = "K8S_CLUSTER_NAME", text_value = "prod-eks" } },
+    { kind = "PLAIN_TEXT", config = { var_name = "AWS_DEFAULT_REGION", text_value = "eu-central-1" } },
+  ]
+
+  wf_steps_config = [{
+    name                = "helm-upgrade"
+    wf_step_template_id = "/stackguardian/kubernetes:13"
+    approval            = true # pauses before this step
+    wf_step_input_data = {
+      schema_type = "FORM_JSONSCHEMA"
+      data = jsonencode({
+        cmdToExec        = "helm"
+        kubectlVersion   = "1.33"
+        workingNamespace = "ingress"
+        helmAction       = "upgrade"
+        helmReleaseName  = "ingress-nginx"
+        helmChartPath    = "charts/ingress-nginx"
+      })
+    }
+  }]
+
+  approvers                    = ["platform@acme.com"]
+  number_of_approvals_required = 1
+}
+
+resource "stackguardian_workflow_git" "cfn_bucket" {
+  id                = "cfn-bucket"
+  resource_name     = "Logs bucket (CloudFormation)"
+  workflow_group_id = stackguardian_workflow_group.ops.id
+  wf_type           = "CUSTOM"
+
+  vcs_config = {
+    iac_vcs_config = {
+      custom_source = {
+        source_config_dest_kind = "GIT_OTHER"
+        config = {
+          repo        = "https://github.com/acme/cfn-stacks"
+          working_dir = "logs-bucket"
+          is_private  = false
+        }
+      }
+    }
+  }
+
+  deployment_platform_config = [{
+    kind   = "AWS_RBAC"
+    config = { integration_id = "/integrations/aws-eks" }
+  }]
+
+  wf_steps_config = [
+    {
+      name                = "create-changeset"
+      wf_step_template_id = "/stackguardian/cloudformation:2"
+      wf_step_input_data = {
+        schema_type = "FORM_JSONSCHEMA"
+        data        = jsonencode({ cfAction = "create-changeset", cfStackName = "logs-bucket", cfTemplateFile = "template.yaml" })
+      }
+    },
+    {
+      name                = "apply-changeset"
+      wf_step_template_id = "/stackguardian/cloudformation:2"
+      approval            = true
+      wf_step_input_data = {
+        schema_type = "FORM_JSONSCHEMA"
+        data        = jsonencode({ cfAction = "apply-changeset", cfStackName = "logs-bucket" })
+      }
+    },
+  ]
+
+  approvers                    = ["platform@acme.com"]
+  number_of_approvals_required = 1
+}
diff --git a/skills/sg-writing-stackguardian-workflow-terraform/examples/git_terraform.tf b/skills/sg-writing-stackguardian-workflow-terraform/examples/git_terraform.tf
new file mode 100644
index 0000000..704996b
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-terraform/examples/git_terraform.tf
@@ -0,0 +1,94 @@
+# Terraform workflow from a private GitHub repo, deploying to AWS through an OIDC connector,
+# with SG-managed state, a 2-of-3 approval gate, a secret env var, nightly drift detection,
+# error/drift emails and a private runner.
+
+data "stackguardian_connector" "github" {
+  id = "github_com" # the GITHUB_COM connector is an org singleton with this id
+}
+
+data "stackguardian_connector" "aws" {
+  id = "aws-prod-oidc" # data sources fail at plan if the connector does not exist
+}
+
+data "stackguardian_runner_group" "prod" {
+  id = "prod-runners"
+}
+
+resource "stackguardian_workflow_group" "payments" {
+  id            = "payments"
+  resource_name = "payments"
+}
+
+resource "stackguardian_workflow_group" "payments_prod" {
+  id            = "${stackguardian_workflow_group.payments.id}/prod" # "payments/prod"
+  resource_name = "prod"                                             # leaf display name
+}
+
+resource "stackguardian_workflow_git" "payments_api" {
+  id                = "payments-api"
+  resource_name     = "Payments API"
+  workflow_group_id = stackguardian_workflow_group.payments_prod.id
+  wf_type           = "TERRAFORM"
+  description       = "Payments API infrastructure (prod)"
+  tags              = ["payments", "prod"]
+
+  vcs_config = {
+    iac_vcs_config = {
+      custom_source = {
+        source_config_dest_kind = "GITHUB_COM" # = the connector's kind
+        config = {
+          repo        = "https://github.com/acme/payments-infra"
+          ref         = "main"
+          working_dir = "envs/prod"
+          is_private  = true
+          auth        = "/integrations/${data.stackguardian_connector.github.id}"
+        }
+      }
+    }
+    iac_input_data = {
+      schema_type = "RAW_JSON"
+      data        = jsonencode({ region = "eu-central-1", instance_count = 3 }) # -> tfvars.json for plan
+    }
+  }
+
+  deployment_platform_config = [{
+    kind   = "AWS_OIDC"
+    config = { integration_id = "/integrations/${data.stackguardian_connector.aws.id}" } # path form, not the bare id
+  }]
+
+  environment_variables = [
+    {
+      kind   = "PLAIN_TEXT"
+      config = { var_name = "DB_PASSWORD", text_value = "$${secret::payments-db-pass}" } # only the reference is stored
+    },
+  ]
+
+  terraform_config = {
+    terraform_version       = "1.5.7" # Terraform <= 1.5.7 on managed runners
+    managed_terraform_state = true    # the repo must NOT declare a backend block
+    approval_pre_apply      = true    # plans with changes pause before apply
+    drift_check             = true
+    drift_cron              = "0 2 * * ? *" # 02:00 UTC every day (EventBridge, 6 fields)
+    pre_plan_hooks = [
+      # busybox sh, no tflint/jq in the image; hooks start outside the repo
+      "cd \"$MOUNTED_IAC_SOURCE_CODE_DIR\" && terraform fmt -check -recursive",
+    ]
+  }
+
+  approvers                    = ["alice@acme.com", "bob@acme.com", "carol@acme.com"] # lowercase
+  number_of_approvals_required = 2
+
+  mini_steps = {
+    notifications = {
+      email = {
+        errored        = [{ recipients = ["oncall@acme.com"] }]
+        drift_detected = [{ recipients = ["platform@acme.com"] }]
+      }
+    }
+  }
+
+  runner_constraints = {
+    type  = "private"
+    names = [data.stackguardian_runner_group.prod.id] # exactly one bare runner group id
+  }
+}
diff --git a/skills/sg-writing-stackguardian-workflow-terraform/examples/git_vcs_triggers.tf b/skills/sg-writing-stackguardian-workflow-terraform/examples/git_vcs_triggers.tf
new file mode 100644
index 0000000..cdba5b1
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-terraform/examples/git_vcs_triggers.tf
@@ -0,0 +1,51 @@
+# GitOps: plan on every PR into main, apply (after approval) on every push to main.
+# Triggers are registered by a second API call; if that fails the provider deletes the new workflow.
+
+data "stackguardian_connector" "gitlab" {
+  id = "gitlab-acme" # a GITLAB_COM connector
+}
+
+resource "stackguardian_workflow_group" "network" {
+  id            = "network"
+  resource_name = "network"
+}
+
+resource "stackguardian_workflow_git" "vpc" {
+  id                = "vpc"
+  resource_name     = "Shared VPC"
+  workflow_group_id = stackguardian_workflow_group.network.id
+  wf_type           = "TERRAFORM"
+
+  vcs_config = {
+    iac_vcs_config = {
+      custom_source = {
+        source_config_dest_kind = "GITLAB_COM"
+        config = {
+          repo       = "https://gitlab.com/acme/network" # https form: webhook events are matched on this URL
+          ref        = "main"
+          is_private = true # triggers need a private repo + connector auth
+          auth       = "/integrations/${data.stackguardian_connector.gitlab.id}"
+        }
+      }
+    }
+  }
+
+  terraform_config = {
+    terraform_version       = "1.5.7"
+    managed_terraform_state = true
+  }
+
+  approvers                    = ["netops@acme.com"]
+  number_of_approvals_required = 1
+
+  vcs_triggers = {
+    tracked_branch        = "main"
+    push                  = { createWfRun = { enabled = true } } # push to main -> apply
+    pull_request_opened   = { createWfRun = { enabled = true } } # PR into main -> plan
+    pull_request_modified = { createWfRun = { enabled = true } } # new commits on that PR -> plan
+    approval_pre_apply    = true                                 # push runs pause before apply
+    file_triggers_enabled = true                                 # GitLab: only when these files change
+    file_trigger_patterns = ["*.tf", "modules/*"]
+  }
+  # To stop triggering later, set every enabled = false. Removing vcs_triggers unregisters nothing.
+}
diff --git a/skills/sg-writing-stackguardian-workflow-terraform/examples/outputs_and_references.tf b/skills/sg-writing-stackguardian-workflow-terraform/examples/outputs_and_references.tf
new file mode 100644
index 0000000..c6b1369
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-terraform/examples/outputs_and_references.tf
@@ -0,0 +1,75 @@
+# Passing values between workflows.
+#  - At RUN time: a ${workflow::...} reference, resolved when the consumer runs.
+#  - At PLAN time: the stackguardian_workflow_outputs data source (only after the producer has
+#    completed an apply; it errors while the producer is inactive or has no outputs).
+
+resource "stackguardian_workflow_group" "platform" {
+  id            = "platform"
+  resource_name = "platform"
+}
+
+resource "stackguardian_workflow_git" "network" {
+  id                = "network"
+  resource_name     = "Network"
+  workflow_group_id = stackguardian_workflow_group.platform.id
+  wf_type           = "TERRAFORM"
+
+  vcs_config = {
+    iac_vcs_config = {
+      custom_source = {
+        source_config_dest_kind = "GITHUB_COM"
+        config                  = { repo = "https://github.com/acme/network", is_private = false }
+      }
+    }
+  }
+
+  terraform_config = {
+    terraform_version       = "1.5.7"
+    managed_terraform_state = true
+  }
+}
+
+resource "stackguardian_workflow_git" "app" {
+  id                = "app"
+  resource_name     = "App"
+  workflow_group_id = stackguardian_workflow_group.platform.id
+  wf_type           = "TERRAFORM"
+
+  vcs_config = {
+    iac_vcs_config = {
+      custom_source = {
+        source_config_dest_kind = "GITHUB_COM"
+        config                  = { repo = "https://github.com/acme/app-infra", is_private = false }
+      }
+    }
+    iac_input_data = {
+      schema_type = "RAW_JSON"
+      # The whole value must be the reference; ".value" unwraps Terraform's output envelope.
+      data = jsonencode({
+        vpc_id = "$${workflow::${stackguardian_workflow_group.platform.id}.${stackguardian_workflow_git.network.id}.outputs.vpc_id.value}"
+      })
+    }
+  }
+
+  terraform_config = {
+    terraform_version       = "1.5.7"
+    managed_terraform_state = true
+  }
+}
+
+# Plan-time read. The data source errors until "network" has completed an apply run, so gate it
+# and flip the variable once that has happened.
+variable "network_has_run" {
+  type    = bool
+  default = false
+}
+
+data "stackguardian_workflow_outputs" "network" {
+  count          = var.network_has_run ? 1 : 0
+  workflow_group = stackguardian_workflow_group.platform.id
+  workflow       = stackguardian_workflow_git.network.id
+}
+
+output "vpc_id" {
+  value = var.network_has_run ? jsondecode(data.stackguardian_workflow_outputs.network[0].data["vpc_id"]).value : null
+}
diff --git a/skills/sg-writing-stackguardian-workflow-terraform/examples/own_template.tf b/skills/sg-writing-stackguardian-workflow-terraform/examples/own_template.tf
new file mode 100644
index 0000000..c460652
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-terraform/examples/own_template.tf
@@ -0,0 +1,130 @@
+# Your own reusable template (container + published revision) and two workflows built from it:
+# one inheriting everything, one overriding and suppressing template values.
+#
+# provider 1.12.3: workflow_from_template works with templates owned by YOUR org only. For a
+# template owned by another org (every StackGuardian marketplace template) apply fails with
+# "Could not read template revision ... 401 Unauthorized" — copy it into your org like this.
+
+variable "org" {
+  type        = string
+  description = "Org slug that owns the template (same as STACKGUARDIAN_ORG_NAME)."
+  default     = "acme"
+}
+
+data "stackguardian_connector" "github" {
+  id = "github_com"
+}
+
+locals {
+  vpc_source = {
+    source_config_dest_kind = "GITHUB_COM"
+    config = {
+      repo       = "https://github.com/acme/tf-vpc"
+      ref        = "v1.4.0"
+      is_private = true
+      auth       = "/integrations/${data.stackguardian_connector.github.id}" # required for every kind but GIT_OTHER, even public repos
+    }
+  }
+}
+
+resource "stackguardian_workflow_template" "vpc" {
+  template_name      = "vpc-module" # becomes the template id
+  source_config_kind = "TERRAFORM"  # immutable
+  is_public          = "0"          # template level: "1" = listed for other orgs
+  description        = "Standard VPC"
+  runtime_source     = local.vpc_source
+}
+
+resource "stackguardian_workflow_template_revision" "vpc_v1" {
+  template_id        = stackguardian_workflow_template.vpc.id
+  source_config_kind = "TERRAFORM"
+  alias              = "v1"
+  notes              = "Initial release"
+  is_public          = "1" # revision level: "1" = published (frozen afterwards), "0" = draft
+  user_job_cpu       = 512 # required on revisions
+  user_job_memory    = 1024
+  runtime_source     = local.vpc_source # NOT inherited from the template — always repeat it
+  tags               = ["network"]
+  environment_variables = [
+    { kind = "PLAIN_TEXT", config = { var_name = "TF_LOG", text_value = "INFO" } },
+  ]
+
+  terraform_config = {
+    terraform_version       = "1.5.7"
+    managed_terraform_state = true
+    approval_pre_apply      = true
+  }
+
+  input_schemas = [{
+    type = "FORM_JSONSCHEMA"
+    encoded_data = base64encode(jsonencode({
+      type     = "object"
+      required = ["cidr"]
+      properties = {
+        cidr   = { type = "string", default = "10.0.0.0/16" }
+        az_cnt = { type = "number", default = 2 }
+      }
+    }))
+  }]
+}
+
+resource "stackguardian_workflow_group" "dev" {
+  id            = "dev"
+  resource_name = "dev"
+}
+
+resource "stackguardian_workflow_from_template" "vpc_dev" {
+  id                = "vpc-dev"
+  resource_name     = "VPC (dev)"
+  workflow_group_id = stackguardian_workflow_group.dev.id
+  wf_type           = "TERRAFORM"
+
+  vcs_config = {
+    iac_vcs_config = {
+      # Always org-qualified, also for your own org: "vpc-module:1" alone is a 404.
+      iac_template_id = "/${var.org}/${stackguardian_workflow_template_revision.vpc_v1.id}"
+    }
+    # iac_input_data omitted -> the schema defaults (cidr, az_cnt) are sent.
+  }
+  # To upgrade later, publish vpc_v2 and point iac_template_id at it: attributes you declared
+  # keep your values, everything you left out adopts the new revision.
+}
+
+resource "stackguardian_workflow_group" "prod" {
+  id            = "prod"
+  resource_name = "prod"
+}
+
+resource "stackguardian_workflow_from_template" "vpc_prod" {
+  id                = "vpc-prod"
+  resource_name     = "VPC (prod)"
+  workflow_group_id = stackguardian_workflow_group.prod.id
+  wf_type           = "TERRAFORM"
+
+  vcs_config = {
+    iac_vcs_config = {
+      iac_template_id = "/${var.org}/${stackguardian_workflow_template_revision.vpc_v1.id}"
+    }
+    iac_input_data = { # replaces the template inputs entirely: list every input you need
+      schema_type = "FORM_JSONSCHEMA"
+      data        = jsonencode({ cidr = "10.20.0.0/16", az_cnt = 3 })
+    }
+  }
+
+  deployment_platform_config = [{
+    kind   = "AWS_RBAC"
+    config = { integration_id = "/integrations/aws-prod" }
+  }]
+
+  tags                  = [] # suppress the template's tags (top-level [] works)
+  environment_variables = [] # suppress the template's env vars
+  terraform_config = {       # merged key by key with the template's terraform_config
+    terraform_version       = "1.5.7"
+    managed_terraform_state = true
+    approval_pre_apply      = true
+    # Template hooks/steps inside terraform_config cannot be removed from here:
+    # pre_plan_hooks = [] is ignored by the server and taints the resource.
+  }
+  approvers                    = ["netops@acme.com"]
+  number_of_approvals_required = 1
+}
diff --git a/skills/sg-writing-stackguardian-workflow-terraform/examples/versions.tf b/skills/sg-writing-stackguardian-workflow-terraform/examples/versions.tf
new file mode 100644
index 0000000..e0b7bdd
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-terraform/examples/versions.tf
@@ -0,0 +1,17 @@
+terraform {
+  required_version = ">= 1.5"
+
+  required_providers {
+    stackguardian = {
+      # Full address so the same code works under OpenTofu (its registry has no copy).
+      source  = "registry.terraform.io/StackGuardian/stackguardian"
+      version = "~> 1.12.3"
+    }
+  }
+}
+
+# Credentials from the environment:
+#   STACKGUARDIAN_API_KEY   raw key (sgu_/sgo_...), no "apikey " prefix
+#   STACKGUARDIAN_ORG_NAME  org slug
+#   STACKGUARDIAN_API_URI   https://api.app.stackguardian.io (EU) or https://api.us.stackguardian.io (US) — there is no default
+provider "stackguardian" {}
diff --git a/skills/sg-writing-stackguardian-workflow-terraform/references/automation-and-outputs.md b/skills/sg-writing-stackguardian-workflow-terraform/references/automation-and-outputs.md
new file mode 100644
index 0000000..55ee055
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-terraform/references/automation-and-outputs.md
@@ -0,0 +1,189 @@
+# Automation and outputs
+
+Schedules, drift detection, VCS triggers, notifications, webhooks, chaining, reading outputs.
+"(live)" = reproduced with provider 1.12.3; "(unverified)" = inferred from code.
+
+## 1. Schedules — `user_schedules`
+
+```terraform
+user_schedules = [{
+  cron  = "0 8 ? * MON-FRI *"   # EventBridge: min hour day-of-month month day-of-week year; UTC
+  state = "ENABLED"             # ENABLED | DISABLED
+  desc  = "weekday morning run" # <= 255 chars; "" fails validate — omit instead
+}]
+```
+
+- `name` is computed: the server generates `<org>-<group>-<workflow><random>` (live). Never set or
+  edit it; an unknown name on update makes the server drop that schedule.
+- 6 fields, `?` in day-of-month **or** day-of-week, always UTC. A 5-field cron fails the create
+  with `Invalid CRON expression provided for schedule: <name>`. ≤10 schedules.
+- **A scheduled run is a full run with default action `apply`.** The provider cannot attach run
+  inputs (plan-only, destroy, different variables), so on TERRAFORM/OPENTOFU workflows pair
+  schedules with `approval_pre_apply = true` or keep them on non-prod workflows.
+- **Removing schedules** (`workflow_git`): set `user_schedules = []` and apply — the server deletes
+  them, then the provider reports a one-time *inconsistent result* (live; not tainted); then delete
+  the attribute (clean plan). Deleting the attribute directly sends `null`, which drops the field
+  but leaves the EventBridge schedules firing (from code). To pause instead, `state = "DISABLED"`.
+- **Adding** a schedule to an existing workflow ends in a one-time *inconsistent result*
+  (`user_schedules[0].name` was null, now generated; live); re-plan — it is clean afterwards.
+- Schedules fire even on inactive workflows (and activate them).
+
+## 2. Drift detection
+
+```terraform
+terraform_config = {
+  terraform_version       = "1.5.7"
+  managed_terraform_state = true
+  drift_check             = true
+  drift_cron              = "0 */6 * * ? *" # always set it with drift_check = true (<= 20 chars)
+}
+mini_steps = { notifications = { email = { drift_detected = [{ recipients = ["platform@acme.com"] }] } } }
+```
+
+- A drift run happens only after the workflow has a **COMPLETED** run whose action was apply, plan
+  or refresh; it reuses that run's inputs. A new workflow never drifts until it has run.
+- Drift runs are an org entitlement (paid orgs); elsewhere they are silently skipped.
+- They run only `pre_plan`/`post_plan` steps (+ hooks when `run_*_hooks_on_drift = true`), no
+  policies, no chaining. A firing drift schedule re-activates a deactivated workflow.
+- Only real resource drift is reported (not code changes). `drift_check = false` deletes the drift
+  schedule (`workflow_from_template` also clears `drift_cron`; on `workflow_git` remove it yourself).
+  Without `drift_cron` the server schedules every 6 hours (`0 */6 * * ? *`) without writing it into
+  the config. CUSTOM workflows cannot drift-check.
+- A drift tick on a workflow that has never run activates it (billed) even though no drift run
+  happens.
+
+## 3. VCS triggers — `stackguardian_workflow_git.vcs_triggers`
+
+```terraform
+vcs_triggers = {
+  tracked_branch      = "main"                                    # default: config.ref, then repo default branch
+  push                = { createWfRun = { enabled = true } }      # push to tracked_branch -> apply
+  pull_request_opened = { createWfRun = { enabled = true } }      # PR into tracked_branch -> plan
+  pull_request_modified = { createWfRun = { enabled = true } }    # set together with pull_request_opened
+  approval_pre_apply  = true                                      # push/tag runs pause before apply
+}
+```
+
+| Key | Effect |
+|---|---|
+| `push` | a push to `tracked_branch` creates a run: `apply` (or `plan` with `plan_only = true`, apply-with-approval with `approval_pre_apply = true`) |
+| `pull_request_opened` / `pull_request_modified` | PR (opened / new commits) targeting `tracked_branch` → always `plan` on the PR branch |
+| `all_pull_requests` | any PR, ignores `tracked_branch` |
+| `create_tag` | a tag push → run with the tag as ref, action follows `plan_only`/`approval_pre_apply` |
+| `plan_only` | push/tag runs only plan (wins over `approval_pre_apply`) |
+| `file_triggers_enabled` + `file_trigger_patterns` | only run when a changed file matches an fnmatch glob (`["*.tf", "infra/**"]`); provider docs: GitLab only |
+| `gh_webhook_url` | computed |
+
+- The inner map key is literally `createWfRun`. There is no `type` key: the provider sends
+  `source_config_dest_kind` as the trigger type. Comment-back, check-run and tag-regex options
+  the API has are not exposed in 1.12.3.
+- Trigger runs carry the workflow's own `terraform_config`, so `terraform_config.approval_pre_apply
+  = true` gates push/tag applies too; `vcs_triggers.approval_pre_apply = true` additionally forces
+  the gate on push/tag runs when the workflow's own flag is false. PR runs only plan.
+- Requirements: git source only (no triggers on `workflow_from_template`), `repo` in https form
+  (the event's repo URL is compared as a string, SSH URLs never match), `is_private = true` with
+  a connector `auth` (needed to register GitLab / Bitbucket / Azure DevOps webhooks; GitHub
+  events arrive through the StackGuardian GitHub App, so the repo must be in that installation).
+  The provider documents `GITHUB_COM`, `GITHUB_APP_CUSTOM`, `GITLAB_COM`; the platform also
+  accepts `BITBUCKET_ORG`, `AZURE_DEVOPS`, `AZURE_DEVOPS_SP` (unverified through the provider).
+- Triggers are registered by a second API call after create. **If it fails, the provider deletes
+  the workflow it just created**: `VCS trigger registration failed: … The workflow was deleted …`.
+  On update a failure only errors.
+- **Stopping triggers:** keep the attribute and set every event's `enabled = false`. Removing
+  `vcs_triggers` unregisters nothing (the API has no removal path; the stored triggers are read back
+  into state, so later applies keep reporting a diff/inconsistent result — from code), and remote
+  webhooks are never deleted — clean them up in the VCS.
+- Adding `vcs_triggers` to an existing workflow can end in a one-time *inconsistent result*
+  (computed trigger fields planned as null; from code) — re-plan afterwards.
+- Changing the repo or kind clears stored triggers but leaves the remote webhook behind.
+- Org entitlement `GitRuns` must be enabled.
+
+## 4. Notifications — `mini_steps.notifications.email`
+
+```terraform
+mini_steps = {
+  notifications = {
+    email = {
+      errored           = [{ recipients = ["oncall@acme.com", "team@acme.com"] }] # one object, many recipients
+      approval_required = [{ recipients = ["approvers@acme.com"] }]
+    }
+  }
+}
+```
+
+- Email only (no Slack/Teams attribute exists). Keys: `approval_required`, `cancelled`,
+  `completed`, `drift_detected`, `errored` (sent upper-case to the API).
+- Only the **first** object of each list is read; put all addresses in its `recipients`.
+- Emails are actually sent for `errored`, `approval_required` and `drift_detected` (the run's
+  initiator is added). `completed` and `cancelled` are accepted and stored, but no email is sent —
+  use a webhook for those.
+- Approvers of a paused run are emailed by the platform automatically; `approval_required` is only
+  for extra recipients.
+
+## 5. Webhooks — `mini_steps.webhooks`
+
+```terraform
+mini_steps = {
+  webhooks = {
+    completed = [{
+      webhook_name   = "deploy-done"
+      webhook_url    = "https://hooks.acme.com/sg"
+      webhook_secret = "$${secret::sg-webhook-hmac}" # never inline: it is returned unmasked by the API and not sensitive in state
+    }]
+  }
+}
+```
+
+- Events: `approval_required`, `cancelled`, `completed`, `drift_detected`, `errored`.
+- POST body: org, workflow group, workflow, run ids, status, trigger details and a subset of
+  runtime parameters. Header `StackGuardian-Webhook-Signature` =
+  base64(HMAC-SHA256(body, secret)). No retries and no timeout — a hanging endpoint delays the
+  run's final status.
+
+## 6. Workflow chaining — `mini_steps.wf_chaining`
+
+```terraform
+mini_steps = {
+  wf_chaining = {
+    completed = [{
+      workflow_group_id    = stackguardian_workflow_group.web.id          # bare id, "parent/child" when nested
+      workflow_id          = stackguardian_workflow_git.cdn_invalidate.id # bare id
+      workflow_run_payload = jsonencode({ TerraformAction = { action = "apply" } })
+    }]
+    errored = [{ workflow_group_id = "ops", workflow_id = "page-oncall" }]
+  }
+}
+```
+
+- Only `completed` and `errored`. For a stack target set `stack_id` (+ `stack_run_payload`) and no
+  `workflow_id`.
+- Targets are not validated; reference the target resource so it exists first. A mistyped target
+  is created on the fly by the run API (`createIfNotExists` defaults to true) (unverified).
+- `workflow_run_payload`: JSON string of run overrides, typically `TerraformAction.action`
+  (`apply`, `destroy`, `plan`, `plan-destroy`, `refresh`). Omitted = the target's default (apply).
+- Chained runs are started as the parent run's executor (shared runners) or with the runner's
+  token (private runners); drift runs never chain; a failed chain start is only logged.
+
+## 7. Outputs
+
+```terraform
+data "stackguardian_workflow_outputs" "network" {
+  workflow_group = stackguardian_workflow_group.prod.id
+  workflow       = stackguardian_workflow_git.network.id
+}
+
+locals {
+  vpc_id = jsondecode(data.stackguardian_workflow_outputs.network.data["vpc_id"]).value
+}
+```
+
+- `data` is a map of JSON strings, one per Terraform output, each `{value, type, sensitive}`;
+  `data_json` is the whole file. CUSTOM steps write their own shape (no `.value` envelope).
+- It reads the **latest** outputs at plan time and fails until they exist: inactive workflow →
+  `Request failure to read workflow outputs` (live); no outputs yet → `Workflow output is not valid
+  JSON`. A config that creates a workflow cannot read its outputs in the same apply — gate the data
+  source with `count = var.<producer>_has_run ? 1 : 0` (`examples/outputs_and_references.tf`).
+- Sensitive Terraform outputs come back masked (`<sensitive>`).
+- If only the next run needs the value (not Terraform), use `$${workflow::<group>.<wf>.outputs.<key>.value}`
+  in an env var or input instead (`references/execution.md` §7).
+- Stacks: `stackguardian_stack_outputs`, `stackguardian_stack_workflow_outputs`.
diff --git a/skills/sg-writing-stackguardian-workflow-terraform/references/discovery.md b/skills/sg-writing-stackguardian-workflow-terraform/references/discovery.md
new file mode 100644
index 0000000..0ac4664
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-terraform/references/discovery.md
@@ -0,0 +1,59 @@
+# Discovering what exists in the org (StackGuardian MCP server)
+
+Every id a workflow or policy references — connectors, secrets, runner groups, groups, other
+workflows, templates — must already exist, and most mistakes (bare ids, display names instead of
+ids, typos) apply cleanly and only fail at run time. When the StackGuardian MCP server is
+connected (tools such as `search_orchestrator_resources`, `search_workflows`, `search_policies`,
+`get_subscription`; in Claude Code they appear as `mcp__stackguardian__<tool>`), **look the values up
+before writing HCL** and present the real options to the user instead of guessing or asking them
+to type ids from memory.
+
+## Ground rules
+
+1. **Same org.** The MCP server derives its org from its own login; the provider uses
+   `STACKGUARDIAN_ORG_NAME`. Check that result rows carry `OrgId = "/orgs/<that org>"` before using
+   any id; if they differ, stop and ask.
+2. **Read-only.** Use the search/get tools only. Don't create or change workflows, groups,
+   templates or policies through MCP write tools when Terraform is meant to own them (the resource
+   would then exist outside state and the apply fails with 409 or adopts it). Exception: **secrets**
+   — the provider has no secret resource, so a missing secret is created out of band (MCP
+   `create_secret`, see the `sg-manage-secrets` skill, or the dashboard); Terraform only references it.
+3. **Still guard at plan time.** Keep `data "stackguardian_connector"` / `data
+   "stackguardian_runner_group"` / `data "stackguardian_workflow_group"` lookups in the HCL: MCP
+   finds the value when you write the code, the data source fails the plan if it later disappears.
+4. **Search lags writes by ~20–30 s.** Something created a moment ago may not be listed yet.
+5. **Values vs names.** Rows have an id (`ResourceId` / `SubResourceId`) and a display
+   `ResourceName`; they often differ (`/integrations/deployment-role` is displayed as
+   `sg-nonprod-2`, groups get random suffixes like `GCP-4jc2fd3k`). Always use the id.
+6. **No MCP?** Fall back to data sources and ask the user for ids; never invent them.
+
+## Lookups
+
+Use `fields=[...]` on `search_orchestrator_resources` to keep responses small, `searchQuery` for a
+name/id substring, and `lastEvaluatedKey` to page.
+
+| Need (Terraform attribute) | Call | Map the row to HCL |
+|---|---|---|
+| Cloud connector → `deployment_platform_config` | `search_orchestrator_resources(resourceTypes=["INTEGRATION.CLOUD"], searchQuery="<hint>", fields=["ResourceId","ResourceName","ResourceType","ParentId","OrgId"])` | `integration_id = ResourceId` (already `/integrations/<id>`); `kind = ResourceType` without `INTEGRATION.` (e.g. `AWS_RBAC`). A child of a connector group (`ParentId = /orgs/<org>/integrationgroups/<g>`) is `/integrationgroups/<g>/integrations/<id>` |
+| VCS connector → `custom_source.config.auth`, `source_config_dest_kind` | same with `INTEGRATION.VCS` | `auth = ResourceId`; `source_config_dest_kind = ResourceType` without `INTEGRATION.` (`GITHUB_COM`, `GITHUB_APP_CUSTOM`, `GITLAB_COM`, …). None fits the repo host → `GIT_OTHER` + a secret |
+| Secret → env var, `auth` (GIT_OTHER), webhook secret | `search_orchestrator_resources(resourceTypes=["SECRET"], searchQuery="<hint>", fields=["ResourceId","ResourceName"])` | `ResourceId = /secrets/<name>` → `text_value = "$${secret::<name>}"` (or `secret_id = "/secrets/<name>"`). Values are never returned. Missing → have it created first (rule 2) |
+| Private runner group → `runner_constraints.names` | `search_orchestrator_resources(resourceTypes=["RUNNER"])`; or read `RunnerGroupId` off an existing workflow from `search_workflows` | `names = ["<id>"]` — the last segment of `/runnergroups/<id>`; check it is active and has connected runners |
+| Workflow group → `workflow_group_id`, policy `enforced_on` | `search_orchestrator_resources(resourceTypes=["WORKFLOW_GROUP"], searchQuery="<hint>", fields=["ResourceId","ResourceName","SubResourceId","ParentId","OrgId"])` | Use **`SubResourceId`** (`/wfgrps/PROD/GCP-4jc2fd3k`): `workflow_group_id = "PROD/GCP-4jc2fd3k"`, `enforced_on = ["/wfgrps/PROD/GCP-4jc2fd3k"]`. `ResourceId` is only the leaf for nested groups |
+| Existing workflow → chaining target, `${workflow::…}` reference, policy scope, import | `search_workflows(searchQuery="<hint>")` (filters: `parentId`, `workflowTypes`, `stackId=""` for standalone) | `SubResourceId = /wfgrps/<g>/wfs/<w>` → `enforced_on` entry as-is; `wf_chaining = { workflow_group_id = "<g>", workflow_id = "<w>" }`; import id `<g>/<w>`. Rows with a `StackId` belong to a stack — not a `workflow_git` import |
+| Output keys for `${workflow::<g>.<w>.outputs.<key>.value}` | `get_workflow_outputs(resourceId="<SubResourceId>")` | key names (Terraform outputs need `.value`) |
+| Own IaC template → `iac_template_id` | `search_marketplace_templates(templateType="IAC", searchQuery="<hint>")` then `get_marketplace_template_by_id(templateType="IAC", templateId="/<org>/<name>:<n>")` | `iac_template_id = "/<org>/<name>:<n>"` (pin a number); `IsPublic "0"` = draft; decode `InputSchemas[].encodedData` for the inputs and defaults; `RuntimeSource` shows repo/ref. Covers templates **owned by** the org only |
+| Step templates → `wf_step_template_id` | `get_subscription(subscriptionTypes=["WORKFLOW_STEP"], fields=["TemplateId","TemplateName","OwnerOrg"])`, `search_marketplace_templates(templateType="WORKFLOW_STEP")` for own ones | `/<owner>/<name>:<rev>`. StackGuardian's public steps (`/stackguardian/ansible:18`, …) work without a subscription and may not be listed |
+| Policy templates → `policy_template_id` | `get_subscription(subscriptionTypes=["IAC_POLICY"])` | `/<owner>/<name>:<n>`; pin a revision that exists |
+| Existing policies (names, scopes) | `search_policies(searchQuery="<hint>")`, then `get_orchestrator_resource_by_id(parentId="/orgs/<org>", resourceId="/policies/<id>")` | avoid name/id collisions; the row's `PoliciesConfig` and `Scope` show current rules and scope |
+| What would this change affect? | `search_workflows(parentId="/orgs/<org>/wfgrps/<g>")`, `search_workflows(cloudIntegrationIds=["/integrations/<c>"])`, `cross_reference(targetKind="cloud_integration" \| "git_integration" \| "runner_group" \| "iac_template" \| "policy_template", targetId=…)` | preview a policy scope's blast radius; find workflows depending on a template/connector before changing it |
+| Name already taken? | the searches above with the planned id as `searchQuery` | an existing id → import instead of create (409 otherwise) |
+
+## Worked flow (workflow from a private repo)
+
+1. `INTEGRATION.VCS` search → pick the connector whose kind matches the repo host →
+   `auth`, `source_config_dest_kind`.
+2. `INTEGRATION.CLOUD` search → user picks the account → `integration_id`, `kind`.
+3. `SECRET` search for every secret the code needs → `$${secret::<name>}`; list the missing ones.
+4. `WORKFLOW_GROUP` search → target group's `SubResourceId` (or create a new group resource).
+5. `search_workflows(searchQuery="<planned id>")` in that group → make sure the id is free.
+6. Write the HCL with those values plus the matching data sources, then `terraform plan`.
diff --git a/skills/sg-writing-stackguardian-workflow-terraform/references/execution.md b/skills/sg-writing-stackguardian-workflow-terraform/references/execution.md
new file mode 100644
index 0000000..f9e167d
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-terraform/references/execution.md
@@ -0,0 +1,244 @@
+# Execution: how a workflow actually runs
+
+What each attribute does when a run executes. "(live)" = reproduced with provider 1.12.3;
+"(unverified)" = inferred. The rest is read in api / core / sg-run-controller /
+workflow-step-templates source.
+
+## 1. `wf_type`
+
+| `wf_type` | Runs | Required | Forbidden |
+|---|---|---|---|
+| `TERRAFORM` | steps generated from `terraform_config` (plan → [approval] → apply) | non-null `terraform_config` | top-level `wf_steps_config` (400) |
+| `OPENTOFU` | same generated steps, OpenTofu binary | non-null `terraform_config` | top-level `wf_steps_config` |
+| `CUSTOM` | your `wf_steps_config`, in order | non-empty `wf_steps_config` (not enforced: 201, then `Workflow Steps not set`) | `terraform_config`, even `{}` (400 `not allowed for CUSTOM Workflow Type`) |
+
+`wf_type` is fixed at create: the server drops it on update. Treat a change as
+`terraform apply -replace=<addr>` (which loses managed state — see lifecycle).
+
+## 2. Terraform / OpenTofu versions — `terraform_config.terraform_version`
+
+- Write it **bare** and **always**: `"1.5.7"`, `"1.4.7"`, `"1.11.x"`, never `"TERRAFORM-1.5.7"`
+  (template revisions can carry that engine prefix; the provider strips it and compares bare values). Omitting it lets the server
+  stamp a default (`1.5.7` / `1.11.x`) that the provider did not plan → inconsistent result (live).
+- Org workflow defaults (org settings) fill `terraform_version`, `terraform_bin_path` and
+  `wf_step_template_revision_id` at create when the config omits them, and `runner_constraints`
+  when that is omitted (from code). Another reason to write them: an omitted value can come back
+  as the org's version or private runner.
+- **Terraform: ≤ 1.5.7** (last MPL release). `1.5.x`, `1.4.x`, `1.3.x` are pre-cached; other ≤1.5.7
+  patches are downloaded at run (needs egress on private runners). Above 1.5.7 on create or
+  update: `400 Terraform <v> is above the highest managed version (1.5.7). Set
+  wfStepTemplateRevisionId …` (live on create; the update path runs the same check).
+- **OpenTofu: any ≥ 1.6** (`1.11.x`, `1.10.x`, `1.9.x` cached). Core passes the version without an
+  engine prefix, and the step picks the binary from the number: a bare `0.x`–`1.5.x` runs
+  **Terraform** even with `wf_type = "OPENTOFU"`. `X.Y.x` = highest cached patch (else the newest
+  released). No ranges, no `~>`, no `latest`.
+- Escape hatches for newer Terraform:
+  1. `stackguardian_workflow_from_template` + `terraform_config.wf_step_template_revision_id =
+     "/<org>/<step-template>:<rev>"` (your own runtime image, sources-and-templates §4).
+  2. Private runner binary: `runner_constraints = { type = "private", names = [...] }`,
+     `terraform_bin_path = [{ source = "/opt/tf/terraform", target = "/opt/tf/terraform", read_only = true }]`
+     and `terraform_version = "/opt/tf/terraform"` (the mounted path; must be executable).
+  3. An org execution preset (runtime image) is applied server-side at **create** only; a later
+     update re-sends `terraform_config` without it, and the update-time version check then
+     rejects it. Prefer 1 or 2.
+- In OpenTofu workflows, hooks that call `terraform` get the image's Terraform 1.5.x; use `tofu`
+  or `"$SG_TF_BIN_PATH"`.
+
+## 3. `terraform_config` keys
+
+| Key | Behaviour |
+|---|---|
+| `managed_terraform_state` | Server/run default **false**. `true` = SG writes a `backend "local"` override and stores state for you — the repo must then have **no** `backend` block (`Found more than 1 terraform state backend blocks …`). `false` = the repo **must** have one (`No state backend is configured, nor StackGuardian-managed terraform state backend is used`). A `cloud {}` block does not count as a backend |
+| `approval_pre_apply` | pause after a plan **with changes**; no-change plans complete without apply or approval. See §10 |
+| `drift_check` / `drift_cron` | automation-and-outputs §2 |
+| `terraform_plan_options` / `terraform_init_options` | appended to the command, split on whitespace (no quoting: use `-var-file=x.tfvars`, not `-var 'a=b c'`). SG inputs win over `-var`/`-var-file` here |
+| `timeout` | seconds **per step** (default 2100 = 35 min). Ignored when a shared run falls back to Fargate (fixed 2 h there) |
+| `terraform_bin_path` | mount list, **private runners only** (400 `only works on private runners` otherwise) |
+| `pre_init_hooks` … `post_apply_hooks` | §5 |
+| `pre_plan/post_plan/pre_apply/post_apply_wf_steps_config` | §5 |
+| `run_pre_init/pre_plan/post_plan_hooks_on_drift` | run those hooks during drift runs too (default false) |
+| `wf_step_template_revision_id` | `workflow_from_template` only — custom runtime image |
+
+Not settable: `tfvarsFilePath`, `terraformApplyOptions`. For a tfvars file in the repo use
+`terraform_plan_options = "-var-file=env/prod.tfvars"` (only plan takes var files).
+`terraform_config` is replaced **whole** on every update, which the provider handles by always
+sending the full object.
+
+## 4. Inputs — `vcs_config.iac_input_data`
+
+- `data` is a JSON **string**: `jsonencode({...})`. Malformed JSON silently becomes `{}`.
+- It is written to a temporary `.tfvars.json` and passed to `plan` with `-var-file`; types are
+  kept (numbers, lists, maps). It overrides repo `*.tfvars` and `-var` in `terraform_plan_options`.
+  Keys the module does not declare produce warnings, not errors.
+- `schema_type`: `RAW_JSON` for git workflows, `FORM_JSONSCHEMA` for template workflows. The run
+  ignores it; it only matters for template upgrades. `NONE`, `RAW_HCL` and `NO_CODE_JSON` exist,
+  don't hand-write them. On `workflow_git` both `schema_type` and `data` are required once the
+  block is present; for "no inputs" omit `iac_input_data`.
+- String values that are exactly `"$${secret::name}"` are resolved at run (a missing secret fails
+  the run).
+
+## 5. Hooks and lifecycle steps (TERRAFORM / OPENTOFU)
+
+- `*_hooks`: lists of shell command strings. Each runs as `/bin/sh -c "<item>"` (busybox; **no bash,
+  jq, tflint or cloud CLIs**; python, git and curl exist). Non-zero exit fails the run.
+- Order: `pre_init` → init → `pre_plan` → plan → `post_plan` → policies/infracost; apply step:
+  `pre_apply` → apply → outputs → `post_apply`. `pre_init` runs before backend validation, so it can
+  generate files. Plan hooks and apply hooks run in **different containers**; share files through
+  the workspace (`/mnt/sg_workspace/...`), not `/tmp`.
+- Hooks start in the image's app directory, **not** the repo. Start with
+  `cd "$MOUNTED_IAC_SOURCE_CODE_DIR" && …` (repo checkout + `working_dir`, set on shared and
+  private runners; `LOCAL_IAC_SOURCE_CODE_DIR` is unset before hooks run).
+- Extra tools in a hook: download them (linux/amd64 image, egress needed) to `/tmp`, e.g. a sketch —
+  pin a release you have checked:
+  `"cd \"$MOUNTED_IAC_SOURCE_CODE_DIR\" && curl -sSLo /tmp/tflint.zip https://github.com/terraform-linters/tflint/releases/download/<version>/tflint_linux_amd64.zip && python -m zipfile -e /tmp/tflint.zip /tmp && chmod +x /tmp/tflint && /tmp/tflint --init && /tmp/tflint"`.
+  For anything heavier, bake the tools into a custom step image (sources-and-templates §4).
+- `*_wf_steps_config`: full steps (§6 shape) in their own container, ≤5 per phase. Don't set
+  both hooks and steps for the same phase (the dashboard treats them as exclusive).
+  `pre_apply_wf_steps_config` also runs on plan-only runs. `pre_init` has hooks only.
+- Drift runs skip hooks unless the matching `run_*_hooks_on_drift = true`, and never run apply-phase
+  hooks or steps.
+
+## 6. CUSTOM workflows
+
+```terraform
+wf_type = "CUSTOM"
+wf_steps_config = [{
+  name                = "run-playbook"                      # slug [A-Za-z0-9_-], unique; spaces break the container name
+  wf_step_template_id = "/stackguardian/ansible:18"         # /<owner-org>/<step-template>:<rev>
+  wf_step_input_data  = {
+    schema_type = "FORM_JSONSCHEMA"                         # the only value; anything else fails at apply
+    data        = jsonencode({ playbookPath = "site.yml", ansibleAction = "run" })
+  }
+  approval = false                                          # true pauses BEFORE this step
+  timeout  = 1800                                           # seconds
+}]
+```
+
+- ≤10 steps; `wf_step_template_id` and `data` are not validated at create (a wrong id: every run
+  fails `'<id>' required for '<name>' workflow step not found`). Two steps with the same `name`
+  → 400 `Duplicate workflow step names found: <name>` (from code).
+- **Step-level `environment_variables` are never injected**; use workflow-level ones (every step
+  gets them).
+- `mount_points` (and `terraform_bin_path`) only work on private runners (shared runners ignore
+  or reject them); `/var/run/docker.sock` is refused.
+- `cmd_override` replaces the container command. It is a string: private runners (Docker) accept
+  it; on shared runners it goes into the ECS task `command`, which expects a list, so it is expected
+  to fail there (from code, unverified at run time).
+- `approval = true` on a step pauses before it — also when it is the last step.
+- With `approvers` set, at least one step needs `approval = true`, otherwise nothing pauses.
+- `iac_input_data` is still passed to IaC-style steps (Ansible extra-vars file, CloudFormation
+  parameters).
+
+Built-in step templates (owner `stackguardian`, latest published revision on 2026-09-28):
+
+| Template | Required inputs (`data`) | Notable optional inputs |
+|---|---|---|
+| `/stackguardian/ansible:18` | `playbookPath` (`playbook.yml`), `ansibleAction` `run`\|`dry-run`\|`check-diff` | `ansibleOptions`, `inventoryType` `hosts`\|`script` + `inventory` (path or host list) / `inventoryScript`; `ANSIBLE_SSH_PRIVATE_KEY` env var |
+| `/stackguardian/kubernetes:13` | `cmdToExec` `kubectl`\|`helm`, `kubectlVersion` `1.36`…`1.33`\|`custom` (+`kubectlVersionCustom`), `workingNamespace` | kubectl: `kubectlAction` `apply`\|`delete`\|`get`, `kubeymlfile`; helm: `helmAction` `upgrade`\|`status`\|`uninstall`\|`list`, `helmReleaseName`, `helmChartPath`, `helmSet`; cluster via `KUBECONFIG_DATA` env or connector + `K8S_CLUSTER_NAME` |
+| `/stackguardian/cloudformation:2` | `cfAction` `create-changeset`\|`apply-changeset`\|`delete-stack`\|`drift-detection`, `cfStackName` | `cfTemplateFile` xor `cfS3TemplateURL`, `cfParamsFile`, `cfCapabilities`; region from `AWS_REGION` (default eu-central-1). Use two steps: create then apply the changeset |
+| `/stackguardian/terragrunt:1` | `terraformAction`, `terraformVersion` (≤1.5.7), `terragruntVersion` `0.62.0`; `managedTerraformState` for plan/plan-destroy/drift-detection | |
+| `/stackguardian/sg-common-utils:1` | none published | "cloud providers' cli tools and common shell utils" (its image contents are not documented) — drive it with `cmd_override` on a private runner |
+
+Older revisions (`ansible:14`, `kubernetes:3`, `cloudformation:1`) are what the dashboard still
+pins; their inputs differ (e.g. `kubernetes:3` offers kubectl 1.23–1.26). Inputs are never
+validated server-side, so check the revision you pin.
+
+## 7. Environment variables and runtime references
+
+```terraform
+environment_variables = [
+  { kind = "PLAIN_TEXT", config = { var_name = "API_TOKEN", text_value = "$${secret::api-token}" } },
+  { kind = "PLAIN_TEXT", config = { var_name = "VPC_ID", text_value = "$${workflow::network.vpc.outputs.vpc_id.value}" } },
+  { kind = "VAULT_SECRET", config = { var_name = "LEGACY", secret_id = "/secrets/legacy-token" } },
+]
+```
+
+- `var_name`: `^[A-Za-z_][A-Za-z0-9_]*$`, ≤80. `text_value`: non-empty, ≤4000. ≤20 variables.
+- `kind`: the API accepts only `PLAIN_TEXT` and `VAULT_SECRET` (`SECRET_VALUE`, `SECRET_REF`,
+  `TEXT` from older provider docs are a 400). The 1.12.3 docs list only `PLAIN_TEXT` and call
+  `secret_id` "Not used", but the run still resolves `VAULT_SECRET` + `secret_id =
+  "/secrets/<name>"` (≤80 chars), failing with `Secret specified for '<var>' does not exist` when
+  it is missing (from code). Prefer the `${secret::}` form.
+- References (write `$${` in HCL — `${` is Terraform interpolation):
+
+  | Reference | Resolves to |
+  |---|---|
+  | `${secret::<name>}` | org secret (double colon; a dot in the name → `Invalid secret interpolation syntax`) |
+  | `${ext-secret::azure-kv::<vault>.<secret>[.<version>]}` | Azure Key Vault; the workflow's connector must be an AZURE_* kind |
+  | `${workflow::<group>.<workflow>.outputs.<key>.value}` | latest output of a Terraform workflow (`.value` is Terraform's envelope; nested group: `parent/child`; in a stack: `<group>.<stack>.<wf>`) |
+
+  Resolved only when the **whole value** is the reference (`"pre-${secret::x}"` stays literal), and
+  only in `environment_variables[].config.text_value`, `iac_input_data.data` string values,
+  `wf_steps_config[].wf_step_input_data.data`, and webhook secrets. A missing workflow-level secret
+  fails the run; inside step input data it silently stays a literal.
+- The Terraform step runs `os.path.expandvars` on every value **after** secrets are resolved:
+  `$NAME` inside a value — including inside a secret's value — is replaced if `NAME` is an env var. Values with newlines (PEM keys) break shared-runner env files — base64
+  them.
+- Reserved names (set by the platform, don't reuse): `SG_*`, `LOCAL_*`, `MOUNTED_*`, `BASE64_*`,
+  `VCS_AUTH_CREDS`, `ORG_ID`, `WORKFLOW_GROUP_ID`, `WORKFLOW_ID`, `WORKFLOW_RUN_ID`, `STACK_ID`,
+  `AWS_WEB_IDENTITY_TOKEN_FILE`, `AWS_SHARED_CREDENTIALS_FILE`, `AWS_CONFIG_FILE`,
+  `GOOGLE_APPLICATION_CREDENTIALS`, `ARM_OIDC_TOKEN_FILE_PATH`, `ARM_USE_OIDC`. Special inputs:
+  `SG_OIDC_ENABLED` (issue an OIDC token), `SG_CONNECTOR_NAME` (use that connector when
+  `deployment_platform_config` is empty), `INFRACOST_API_KEY`.
+- Env var values are visible in state and to anyone who can read the workflow: never inline a
+  credential; reference it.
+
+## 8. Cloud credentials — `deployment_platform_config`
+
+- At most **one** entry: `{ kind, config = { integration_id = "/integrations/<connector>" } }`;
+  a connector inside a connector group: `/integrationgroups/<group>/integrations/<connector>`.
+- Nothing is checked at create. Wrong id → every run: `Connector <name> does not exist`.
+  Unconfigured connector → `AWS/Azure/GCP Integration '<id>' is not correctly configured.`
+- Set `kind` to the connector's kind. What each injects: `AWS_STATIC` keys + region;
+  `AWS_RBAC` assume-role session creds (**no region** — set `region` in your provider block);
+  `AWS_OIDC` role ARN + web-identity token; `AZURE_*` `ARM_*`; `GCP_*` `GOOGLE_CREDENTIALS`.
+  `AZURE_MANAGED_ID_OIDC` is accepted by the API but missing from the provider SDK enum
+  (unverified through the provider).
+- `profile_name` appears to be ignored at run (inferred from code): AWS credentials land in the
+  `default` profile. Don't set
+  `profile`, keys or `assume_role` in your AWS provider block.
+- Connector-scoped policies (`enforced_on = ["/integrations/<c>"]`) match this `integration_id`.
+- Managing the connector itself (`resource "stackguardian_connector"`, schema 1.12.3, details from
+  code): set `id` (otherwise derived from `resource_name`, random-suffixed when not a slug);
+  `settings = { kind = "AWS_RBAC", config = [{ role_arn = "…", external_id = "<org>:<random>",
+  duration_seconds = "3600" }] }` — `config` is a **list** of one object and `duration_seconds` a
+  string. In 1.12.3 the credential attributes (`aws_secret_access_key`, `arm_client_secret`,
+  `gitlab_creds`, …) are **not** marked sensitive and land in state: prefer RBAC/OIDC kinds, or
+  create key-based connectors outside Terraform and only look them up.
+
+## 9. Runners and job size
+
+- `runner_constraints = { type = "shared" }` (default) or
+  `{ type = "private", names = ["<runner group id>"] }` — exactly one name, the bare id
+  (= `resource_name` for slug names), ≤113 chars. Changing it while runs are active → 409.
+- Private runner problems surface as `Runner group <name> is not active`, a run stuck QUEUED
+  (workflow shows PAUSED) until an agent connects, or the opaque `Failed to build workflow run: Error 2`
+  (e.g. `/runnergroups/` prefix in `names`, or `type = "private"` without `names` — accepted at create, from code).
+- `runner_constraints` omitted → the org's workflow default runner if one is set, else shared
+  (from code).
+- Managing the group itself (`resource "stackguardian_runner_group"`, schema in
+  `references/schema.md`; behaviour from code): set `id` — it is what `names` takes, and without
+  it a non-slug `resource_name` gets a random suffix. `storage_backend_config` is required:
+  `{ type = "aws_s3", aws_region, s3_bucket_name, auth = { integration_id = "/integrations/<c>" } }`
+  or `{ type = "azure_blob_storage", azure_blob_storage_account_name, azure_blob_storage_access_key }`
+  (the key is not marked sensitive in 1.12.3). `max_number_of_runners` defaults to 1. A new group
+  has no runners: runs pause until an agent registers with the token from
+  `data "stackguardian_runner_group_token" { runner_group_id = "<bare id>" }` (not sensitive in
+  1.12.3 — wrap outputs in `sensitive()`). Deleting a group that is the org's default runner → 409.
+- `user_job_cpu` (ECS units, 1024 = 1 vCPU) / `user_job_memory` (MiB), defaults 512/1024. Use valid
+  Fargate pairs: 256→512–2048, 512→1024–4096, 1024→2048–8192, 2048→4096–16384, 4096→8192–30720.
+  On private runners memory is a hard limit (OOM = exit 137).
+
+## 10. Approvals
+
+- TERRAFORM/OPENTOFU: `terraform_config.approval_pre_apply = true` gates apply. CUSTOM: a step's
+  `approval = true`. `approvers` alone gates nothing.
+- `approvers`: lowercase emails (the server lowercases; mixed case → inconsistent result, live),
+  `<userpool>/<idp>/<email>`, or SSO groups `<userpool>/group/<groupId>`. API-key callers cannot
+  approve.
+- `number_of_approvals_required`: `N` = N distinct approvers; `0` with approvers = **all**; empty
+  `approvers` = **anyone** with approve permission. N > len(approvers) never completes.
+- Any rejection → run CANCELLED. Plan-approval and policy approvals gate the *next* step, so when
+  the plan step is the last one (plan-only runs without pre-apply steps) nothing pauses; a step's own
+  `approval = true` pauses even on the last step.
+- Approvers are emailed automatically when a run pauses (no notification config needed).
diff --git a/skills/sg-writing-stackguardian-workflow-terraform/references/lifecycle.md b/skills/sg-writing-stackguardian-workflow-terraform/references/lifecycle.md
new file mode 100644
index 0000000..15239fc
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-terraform/references/lifecycle.md
@@ -0,0 +1,163 @@
+# Lifecycle: create, update, replace, destroy, import
+
+"(live)" = reproduced with provider 1.12.3 against a real org; "(unverified)" = inferred.
+
+## 1. When a mistake surfaces
+
+| Stage | Catches |
+|---|---|
+| `terraform validate` | block syntax, unknown/missing **top-level** attributes, `""` in most strings (`description`, `desc`, `ref`, `working_dir`, env var fields, …). Misspelled keys **inside** nested objects pass and are dropped (live) |
+| `plan` | template-revision lookups (`workflow_from_template` upgrades), template/revision `runtime_source` auth rules and immutable fields |
+| `apply` (API 400/403/404) | enum values, Terraform > 1.5.7 on create, CUSTOM + `terraform_config`, `is_private` missing, private repo without auth, bare template id, reserved `resource_name`s, config-time policies (403) |
+| apply → *inconsistent result* | values the server rewrites (see §3) |
+| first run | connector/secret/runner/step-template/template-access problems, repo/backend layout, hooks |
+
+## 2. Create
+
+- New workflows are **inactive** (`IsActive "0"`) until any run (manual, schedule, trigger, drift)
+  activates them. Free-plan orgs without a payment method can hit 402 `Active workflow quota
+  exhausted` on that first run. Terraform cannot set activation.
+- `id`: slug `^[-a-zA-Z0-9_]+$`, used verbatim. `resource_name` is only a display name; omitted →
+  random 21 characters (live). Reserved names are rejected: `orgs, wfgrps, stacks, wfs, wfruns,
+  policies, secrets, integrations, runnergroups, templates, outputs, logs, listall, …`. The check
+  covers `resource_name` only: an `id` such as `listall` is accepted but shadowed by the API route
+  of the same name (from code). Keep reserved words out of ids too.
+- An `id` already used in the group → 409 `Workflow ID not unique`. A 409 from workflow create is
+  also the API's fallback status for other create failures, so read the message (from code).
+- A `workflow_group_id` that does not exist is **auto-created** by the server with a junk
+  description/tags (for nested paths a top-level group named after the leaf — from code). Always reference the
+  group resource.
+- Config-time policies in scope evaluate the new definition: a failing rule returns
+  `403 Workflow policy (<policy>:<rule>) failed: Expression: … | …` (live) and nothing is created.
+
+## 3. Update and clearing
+
+`stackguardian_workflow_git` (live):
+
+| Attribute class | Removing it from config |
+|---|---|
+| `tags`, `approvers` (Optional+Computed) | **keeps** the server value — set `[]` to clear |
+| `description`, `context_tags`, `environment_variables`, `mini_steps`, `deployment_platform_config`, `wf_steps_config`, `iac_input_data` (Optional) | clears it on the next apply. Don't write `[]`/`{}` for these: the server clears them but the provider reads null back → one-time *inconsistent result* (live) |
+| `user_schedules` | set `[]`, apply (schedules deleted, one-time inconsistent result), then remove it — deleting it directly leaves the schedules firing |
+| `vcs_triggers` | removing it unregisters nothing — keep it with every `enabled = false` (automation §3) |
+| `resource_name` | in-place rename (cosmetic) |
+
+`stackguardian_workflow_from_template`: every inherited attribute is Optional+Computed with
+UseStateForUnknown — removing one keeps its current value; suppress with an empty top-level value
+(`references/sources-and-templates.md` §2).
+
+**Write what the server stores**, or apply fails with *Provider produced inconsistent result
+after apply* (on create the resource is also tainted; live):
+- always set `terraform_config.terraform_version` (server stamps `1.5.7` / `1.11.x`), never `terraform_config = {}`;
+- approver emails in lowercase.
+
+Recovery: fix the config to the value the server holds; after a failed **create** also run
+`terraform untaint <address>`; the plan must be empty.
+
+Other update facts: the whole `terraform_config` and `vcs_config` are sent on every update;
+changing `runner_constraints` while a run is queued/running/awaiting approval → 409; the provider
+PATCHes `workflow_git` with `upgradeMode=PRESERVE_SETTINGS` and `workflow_from_template` without one.
+
+## 4. Replacement and immutable fields
+
+| Change | `workflow_git` | `workflow_from_template` |
+|---|---|---|
+| `id` | replace | replace |
+| `workflow_group_id` | **inconsistent result**; workflow stays in the old group, diff never goes away (live) | replace |
+| `wf_type` | sent, ignored by the server → inconsistent result (unverified) | same |
+
+Replacement = delete + create: the new workflow gets a new internal KSUID, so **SG-managed
+Terraform state, run history and artifacts do not carry over** — the new workflow plans from an
+empty state. To move or re-type a workflow that manages live infrastructure: destroy its
+infrastructure first (run), or move it in the dashboard and re-import at the new address, or keep
+managed state off and use your own backend.
+
+For a group move you really want, change the value and run
+`terraform apply -replace=stackguardian_workflow_git.<name>`.
+
+## 5. Destroy
+
+`terraform destroy` of a workflow resource:
+- deletes the workflow, its runs, schedules, drift schedule and artifacts — including
+  SG-managed state;
+- **never runs `terraform destroy`**: cloud resources are orphaned;
+- is refused while any run is not terminal (`Workflow <id> cannot be deleted as it is currently
+  running or queued.` / `… has workflow run(s) that are not in a terminal state (found
+  APPROVAL_REQUIRED)`), returned as 400; cancel or finish runs first;
+- does not remove VCS webhooks.
+
+Tear-down order for managed infrastructure: trigger a **destroy run** on the workflow (dashboard,
+API `POST …/wfs/<id>/wfruns/` with `TerraformAction.action = "destroy"`, or sg-cli), wait for it,
+then remove the resource. A group can only be deleted once it is empty. A published template
+revision can only be deleted after a passed deprecation date (sources-and-templates §3).
+
+Out-of-band deletes: `workflow_git`, `workflow_template` and `workflow_template_revision` have no
+404 handling — every later plan errors `Error reading workflow_git`; run
+`terraform state rm <address>`. `workflow_from_template` drops itself from state (and destroying
+one that is already gone succeeds).
+
+## 6. Import
+
+| Resource | Import id |
+|---|---|
+| `stackguardian_workflow_git`, `stackguardian_workflow_from_template` | `<workflow_group_id>/<workflow_id>` — nested group: `parent/child/wf` (split on the last `/`) |
+| `stackguardian_workflow_template` | template id |
+| `stackguardian_workflow_template_revision` | `<template>:<n>` — the first plan then fails `template_id cannot be changed` (import sets no `template_id`; from code). Avoid importing revisions; recreate or leave them unmanaged |
+| `stackguardian_workflow_step_template_revision` | `<template>:<n>` (the next plan replaces it: `template_id` is not read back) |
+
+```terraform
+import {
+  to = stackguardian_workflow_git.payments_api
+  id = "payments/prod/payments-api"
+}
+```
+
+Plan immediately after importing: expect diffs on server-normalized values (lowercased approvers,
+stamped `terraform_version`, schedule names) and write them into the config.
+`terraform plan -generate-config-out=generated.tf` (Terraform ≥ 1.5) writes the current values of
+every `import` block target for you — start from that file.
+
+## 7. Error catalog
+
+| Message (abridged) | Cause | Fix |
+|---|---|---|
+| `Missing Organization Name` … `unknown configuration value for the StackGuardian API URI` (or `API Key`) | no `api_uri` / `STACKGUARDIAN_API_URI` (or key); the summary says "Organization Name" for all three settings — read the detail | set the region URL / key |
+| `401 Unauthorized` | key from another org/region, or `apikey ` prefix added by hand | right region + org, raw key |
+| `Template <x> of type IAC does not exist` | bare or misspelled `iac_template_id` | `/<org>/<name>:<n>` |
+| `{"TerraformConfig": ["required for TERRAFORM/OPENTOFU"]}` | missing `terraform_config` | add it with `terraform_version` |
+| `not allowed for CUSTOM Workflow Type` | `terraform_config` on CUSTOM | remove it |
+| `Terraform <v> is above the highest managed version (1.5.7)` | Terraform ≥ 1.6 | ≤ 1.5.7, OpenTofu, or execution §2 escape hatches |
+| `{"isPrivate": ["required"]}` / `auth required for isPrivate` / `only secrets supported for GIT_OTHER` | source config | sources-and-templates §1 |
+| `{"ResourceName": ["<x> cannot be used"]}` | reserved name (also as an approver string) | rename |
+| `403 Workflow policy (<p>:<r>) failed …` | a config-time policy in scope | satisfy the rule or fix the policy |
+| `409 Cannot update RunnerConstraints while there are workflow runs …` | active runs | wait / cancel |
+| `409 Workflow ID not unique` | `id` taken in that group (from code) | import it or pick another id |
+| `404 Invalid GitHub repo` | `GITHUB_COM`/`GITHUB_APP_CUSTOM` repo URL without `<owner>/<repo>` (from code) | fix `repo` |
+| `400 Duplicate workflow step names found: <n>` | two steps share a `name` (from code) | rename |
+| `Invalid schema type` (apply) | `wf_step_input_data.schema_type` other than `FORM_JSONSCHEMA` (from code) | `FORM_JSONSCHEMA` |
+| `Published template cannot be deleted. Please deprecate the template first.` / `… until the deprecation effective date has passed` | destroying a published revision (live) | sources-and-templates §3 |
+| plan: `Unable to read workflow template revision.` (403) | revision data source given `/<org>/<name>:<n>` (live) | bare `<name>:<n>` |
+| run: `Template has no git repository in RuntimeSource` | template revision without `runtime_source` (from code) | set it on the revision |
+| `Provider produced inconsistent result after apply` | server-normalized value, `workflow_group_id` change on `workflow_git` | §3 / §4 |
+| run: `Connector <x> does not exist` | bare or wrong `integration_id` | `/integrations/<id>` |
+| run: `Secret specified for '<var>' does not exist` / `Failed to retrieve referenced secret: ${secret::x}` | missing secret | create it |
+| run: `Workflow Steps not set` | CUSTOM without steps | add `wf_steps_config` |
+| run: `'<id>' required for '<step>' workflow step not found` | wrong step template id/revision | fix `wf_step_template_id` |
+| run: `<id> is a private template and can only be used by its owner org …` | template not public/shared | publish / share |
+| plan: `Found more than 1 terraform state backend blocks` | repo backend + managed state | remove one |
+| plan: `No state backend is configured, nor StackGuardian-managed …` | no backend, managed state off | enable managed state or add a backend |
+| run: `Failed to build workflow run: Error 2` | opaque build error — often private runner `names` with a `/runnergroups/` prefix | bare runner group id |
+
+## 8. Migrating from the 0.x `stackguardian_workflow`
+
+Old: `resource "stackguardian_workflow" "x" { wfgrp = "…"; data = jsonencode({ ResourceName, WfType, VCSConfig, … }) }`.
+New: one attribute per API field in snake_case (`VCSConfig.iacVCSConfig.customSource.config.isPrivate`
+→ `vcs_config.iac_vcs_config.custom_source.config.is_private`), `wfgrp` → `workflow_group_id`,
+`ResourceName` → `id` (+ `resource_name`), template sources → `stackguardian_workflow_from_template`.
+Keep the existing workflows:
+1. With the **old** provider version still installed, `terraform state rm stackguardian_workflow.<name>`
+   (a type the new provider no longer has may not be decodable later; `moved` cannot change types).
+   Terraform ≥ 1.7 alternative: `removed { from = stackguardian_workflow.<name>  lifecycle { destroy = false } }`.
+2. Write the new resource plus an `import` block with `<group>/<workflow-id>`, `terraform init -upgrade`.
+3. Plan until it shows `1 to import, 0 to add, 0 to change, 0 to destroy`, then apply and drop the import block. Only `docs-guides-assets/onboarding/project-test` in
+the provider repo still shows the old style.
diff --git a/skills/sg-writing-stackguardian-workflow-terraform/references/schema.md b/skills/sg-writing-stackguardian-workflow-terraform/references/schema.md
new file mode 100644
index 0000000..56fd972
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-terraform/references/schema.md
@@ -0,0 +1,588 @@
+# Provider 1.12.3 schema — workflow side
+
+Generated from `terraform providers schema -json` (StackGuardian/stackguardian 1.12.3).
+`= {...}` single nested attribute, `= [{...}]` list of objects, `= {key={...}}` map of objects —
+all are **attributes** (`name = …`), never blocks. `REQUIRED` / `optional` / `optional+computed`
+(computed: the server or a template fills it when you omit it).
+
+Accepted values (not enforced by the provider — the API rejects others at apply):
+
+| Attribute | Values |
+|---|---|
+| `wf_type` | `TERRAFORM`, `OPENTOFU`, `CUSTOM` |
+| `custom_source.source_config_dest_kind` | `GITHUB_COM`, `GITHUB_APP_CUSTOM`, `GITLAB_COM`, `BITBUCKET_ORG`, `AZURE_DEVOPS`, `AZURE_DEVOPS_SP`, `GIT_OTHER` |
+| `iac_input_data.schema_type` | `RAW_JSON` (git), `FORM_JSONSCHEMA` (templates); also `NONE`, `RAW_HCL`, `NO_CODE_JSON` |
+| `wf_step_input_data.schema_type` | `FORM_JSONSCHEMA` only |
+| `environment_variables[].kind` | `PLAIN_TEXT` (`text_value`), `VAULT_SECRET` (`secret_id = "/secrets/<n>"`) |
+| `deployment_platform_config[].kind` | `AWS_STATIC`, `AWS_RBAC`, `AWS_OIDC`, `AZURE_STATIC`, `AZURE_OIDC`, `GCP_STATIC`, `GCP_OIDC` (API also: `AZURE_MANAGED_ID_OIDC`) |
+| `runner_constraints.type` | `shared`, `private` |
+| `user_schedules[].state` | `ENABLED`, `DISABLED` |
+| `mini_steps.notifications.email.*`, `mini_steps.webhooks.*` | `approval_required`, `cancelled`, `completed`, `drift_detected`, `errored` |
+| `mini_steps.wf_chaining.*` | `completed`, `errored` |
+| `vcs_triggers.<event>` map key | `createWfRun` |
+| template `source_config_kind` | `TERRAFORM`, `OPENTOFU`, `ANSIBLE_PLAYBOOK`, `HELM`, `KUBECTL`, `CLOUDFORMATION`, `CUSTOM` |
+| template / revision `is_public` | `"0"`, `"1"` (strings) |
+| `input_schemas[].type` | `FORM_JSONSCHEMA`, `RAW_JSON` |
+| runner group `storage_backend_config.type` | `aws_s3` (needs `auth.integration_id`), `azure_blob_storage` |
+
+Data source lookups (all fail at plan when the object does not exist, e.g. `Unable to read
+workflow group.`): `stackguardian_connector` (`id`; exposes `settings.kind`, useful for
+`kind = data.stackguardian_connector.x.settings.kind`), `stackguardian_runner_group`,
+`stackguardian_workflow_group` take `id` (`resource_name` is deprecated there; the group data source
+returns only the **leaf** as `id` for nested groups and a null `resource_name` — use it as an
+existence check, not to build paths);
+`stackguardian_workflow_git` takes the bare workflow `id` + `workflow_group_id` (use it to reference an
+existing workflow, e.g. a chaining target, so a typo fails at plan); `stackguardian_workflow_template`
+takes `id` but **always fails in 1.12.3** (schema/model mismatch — use
+`stackguardian_workflow_template_revision` instead); `stackguardian_workflow_template_revision` takes the bare `<template>:<n>` of your own
+org (a `/<org>/` prefix returns a misleading 403, live); `stackguardian_runner_group_token` takes `runner_group_id` (its token is **not** marked
+sensitive — mark outputs yourself).
+
+### resource stackguardian_workflow_git
+```
+approvers: list(string)  [optional+computed]
+context_tags: map(string)  [optional]
+deployment_platform_config = [{...}]  [optional]
+  config = {...}  [REQUIRED]
+    integration_id: string  [REQUIRED]
+    profile_name: string  [optional]
+  kind: string  [REQUIRED]
+description: string  [optional]
+environment_variables = [{...}]  [optional]
+  config = {...}  [REQUIRED]
+    secret_id: string  [optional]
+    text_value: string  [optional]
+    var_name: string  [REQUIRED]
+  kind: string  [REQUIRED]
+id: string  [REQUIRED]
+mini_steps = {...}  [optional]
+  notifications = {...}  [optional]
+    email = {...}  [optional]
+      approval_required = [{...}]  [optional]
+        recipients: list(string)  [optional]
+      cancelled = [{...}]  [optional]
+        recipients: list(string)  [optional]
+      completed = [{...}]  [optional]
+        recipients: list(string)  [optional]
+      drift_detected = [{...}]  [optional]
+        recipients: list(string)  [optional]
+      errored = [{...}]  [optional]
+        recipients: list(string)  [optional]
+  webhooks = {...}  [optional]
+    approval_required = [{...}]  [optional]
+      webhook_name: string  [REQUIRED]
+      webhook_secret: string  [optional]
+      webhook_url: string  [REQUIRED]
+    cancelled = [{...}]  [optional]
+      webhook_name: string  [REQUIRED]
+      webhook_secret: string  [optional]
+      webhook_url: string  [REQUIRED]
+    completed = [{...}]  [optional]
+      webhook_name: string  [REQUIRED]
+      webhook_secret: string  [optional]
+      webhook_url: string  [REQUIRED]
+    drift_detected = [{...}]  [optional]
+      webhook_name: string  [REQUIRED]
+      webhook_secret: string  [optional]
+      webhook_url: string  [REQUIRED]
+    errored = [{...}]  [optional]
+      webhook_name: string  [REQUIRED]
+      webhook_secret: string  [optional]
+      webhook_url: string  [REQUIRED]
+  wf_chaining = {...}  [optional]
+    completed = [{...}]  [optional]
+      stack_id: string  [optional]
+      stack_run_payload: string  [optional]
+      workflow_group_id: string  [REQUIRED]
+      workflow_id: string  [optional]
+      workflow_run_payload: string  [optional]
+    errored = [{...}]  [optional]
+      stack_id: string  [optional]
+      stack_run_payload: string  [optional]
+      workflow_group_id: string  [REQUIRED]
+      workflow_id: string  [optional]
+      workflow_run_payload: string  [optional]
+number_of_approvals_required: number  [optional+computed]
+resource_name: string  [optional+computed]
+runner_constraints = {...}  [optional+computed]
+  names: list(string)  [optional]
+  type: string  [REQUIRED]
+tags: list(string)  [optional+computed]
+terraform_config = {...}  [optional]
+  approval_pre_apply: bool  [optional]
+  drift_check: bool  [optional]
+  drift_cron: string  [optional]
+  managed_terraform_state: bool  [optional]
+  post_apply_hooks: list(string)  [optional]
+  post_apply_wf_steps_config = [{...}]  [optional]  # same shape as top-level wf_steps_config
+  post_plan_hooks: list(string)  [optional]
+  post_plan_wf_steps_config = [{...}]  [optional]  # same shape as top-level wf_steps_config
+  pre_apply_hooks: list(string)  [optional]
+  pre_apply_wf_steps_config = [{...}]  [optional]  # same shape as top-level wf_steps_config
+  pre_init_hooks: list(string)  [optional]
+  pre_plan_hooks: list(string)  [optional]
+  pre_plan_wf_steps_config = [{...}]  [optional]  # same shape as top-level wf_steps_config
+  run_post_plan_hooks_on_drift: bool  [optional+computed]
+  run_pre_init_hooks_on_drift: bool  [optional+computed]
+  run_pre_plan_hooks_on_drift: bool  [optional+computed]
+  terraform_bin_path = [{...}]  [optional]
+    read_only: bool  [optional]
+    source: string  [REQUIRED]
+    target: string  [REQUIRED]
+  terraform_init_options: string  [optional]
+  terraform_plan_options: string  [optional]
+  terraform_version: string  [optional]
+  timeout: number  [optional]
+user_job_cpu: number  [optional+computed]
+user_job_memory: number  [optional+computed]
+user_schedules = [{...}]  [optional]
+  cron: string  [REQUIRED]
+  desc: string  [optional]
+  name: string  [computed]
+  state: string  [REQUIRED]
+vcs_config = {...}  [REQUIRED]
+  iac_input_data = {...}  [optional]
+    data: string  [REQUIRED]
+    schema_id: string  [optional]
+    schema_type: string  [REQUIRED]
+  iac_vcs_config = {...}  [REQUIRED]
+    custom_source = {...}  [REQUIRED]
+      config = {...}  [REQUIRED]
+        auth: string  [optional]
+        git_core_auto_crlf: bool  [optional+computed]
+        git_sparse_checkout_config: string  [optional]
+        include_sub_module: bool  [optional]
+        is_private: bool  [optional]
+        ref: string  [optional]
+        repo: string  [REQUIRED]
+        working_dir: string  [optional]
+      source_config_dest_kind: string  [REQUIRED]
+vcs_triggers = {...}  [optional]
+  all_pull_requests = {key={...}}  [optional]
+    enabled: bool  [REQUIRED]
+  approval_pre_apply: bool  [optional+computed]
+  create_tag = {key={...}}  [optional]
+    enabled: bool  [REQUIRED]
+  file_trigger_patterns: list(string)  [optional]
+  file_triggers_enabled: bool  [optional+computed]
+  gh_webhook_url: string  [computed]
+  plan_only: bool  [optional+computed]
+  pull_request_modified = {key={...}}  [optional]
+    enabled: bool  [REQUIRED]
+  pull_request_opened = {key={...}}  [optional]
+    enabled: bool  [REQUIRED]
+  push = {key={...}}  [optional]
+    enabled: bool  [REQUIRED]
+  tracked_branch: string  [optional]
+wf_steps_config = [{...}]  [optional]
+  approval: bool  [optional]
+  cmd_override: string  [optional]
+  environment_variables = [{...}]  [optional]
+    config = {...}  [REQUIRED]
+      secret_id: string  [optional]
+      text_value: string  [optional]
+      var_name: string  [REQUIRED]
+    kind: string  [REQUIRED]
+  mount_points = [{...}]  [optional]
+    read_only: bool  [optional]
+    source: string  [REQUIRED]
+    target: string  [REQUIRED]
+  name: string  [REQUIRED]
+  timeout: number  [optional]
+  wf_step_input_data = {...}  [optional]
+    data: string  [optional]
+    schema_type: string  [optional]
+  wf_step_template_id: string  [REQUIRED]
+wf_type: string  [REQUIRED]
+workflow_group_id: string  [REQUIRED]
+```
+
+### resource stackguardian_workflow_from_template
+```
+approvers: list(string)  [optional+computed]
+context_tags: map(string)  [optional+computed]
+deployment_platform_config = [{...}]  [optional+computed]
+  config = {...}  [REQUIRED]
+    integration_id: string  [REQUIRED]
+    profile_name: string  [optional]
+  kind: string  [REQUIRED]
+description: string  [optional+computed]
+environment_variables = [{...}]  [optional+computed]
+  config = {...}  [REQUIRED]
+    secret_id: string  [optional]
+    text_value: string  [optional]
+    var_name: string  [REQUIRED]
+  kind: string  [REQUIRED]
+id: string  [REQUIRED]
+mini_steps = {...}  [optional+computed]
+  notifications = {...}  [optional]
+    email = {...}  [optional]
+      approval_required = [{...}]  [optional]
+        recipients: list(string)  [optional]
+      cancelled = [{...}]  [optional]
+        recipients: list(string)  [optional]
+      completed = [{...}]  [optional]
+        recipients: list(string)  [optional]
+      drift_detected = [{...}]  [optional]
+        recipients: list(string)  [optional]
+      errored = [{...}]  [optional]
+        recipients: list(string)  [optional]
+  webhooks = {...}  [optional]
+    approval_required = [{...}]  [optional]
+      webhook_name: string  [REQUIRED]
+      webhook_secret: string  [optional]
+      webhook_url: string  [REQUIRED]
+    cancelled = [{...}]  [optional]
+      webhook_name: string  [REQUIRED]
+      webhook_secret: string  [optional]
+      webhook_url: string  [REQUIRED]
+    completed = [{...}]  [optional]
+      webhook_name: string  [REQUIRED]
+      webhook_secret: string  [optional]
+      webhook_url: string  [REQUIRED]
+    drift_detected = [{...}]  [optional]
+      webhook_name: string  [REQUIRED]
+      webhook_secret: string  [optional]
+      webhook_url: string  [REQUIRED]
+    errored = [{...}]  [optional]
+      webhook_name: string  [REQUIRED]
+      webhook_secret: string  [optional]
+      webhook_url: string  [REQUIRED]
+  wf_chaining = {...}  [optional]
+    completed = [{...}]  [optional]
+      stack_id: string  [optional]
+      stack_run_payload: string  [optional]
+      workflow_group_id: string  [REQUIRED]
+      workflow_id: string  [optional]
+      workflow_run_payload: string  [optional]
+    errored = [{...}]  [optional]
+      stack_id: string  [optional]
+      stack_run_payload: string  [optional]
+      workflow_group_id: string  [REQUIRED]
+      workflow_id: string  [optional]
+      workflow_run_payload: string  [optional]
+number_of_approvals_required: number  [optional+computed]
+resource_name: string  [optional+computed]
+runner_constraints = {...}  [optional+computed]
+  names: list(string)  [optional]
+  type: string  [REQUIRED]
+tags: list(string)  [optional+computed]
+terraform_config = {...}  [optional+computed]
+  approval_pre_apply: bool  [optional+computed]
+  drift_check: bool  [optional+computed]
+  drift_cron: string  [optional+computed]
+  managed_terraform_state: bool  [optional+computed]
+  post_apply_hooks: list(string)  [optional+computed]
+  post_apply_wf_steps_config = [{...}]  [optional+computed]  # same shape as top-level wf_steps_config
+  post_plan_hooks: list(string)  [optional+computed]
+  post_plan_wf_steps_config = [{...}]  [optional+computed]  # same shape as top-level wf_steps_config
+  pre_apply_hooks: list(string)  [optional+computed]
+  pre_apply_wf_steps_config = [{...}]  [optional+computed]  # same shape as top-level wf_steps_config
+  pre_init_hooks: list(string)  [optional+computed]
+  pre_plan_hooks: list(string)  [optional+computed]
+  pre_plan_wf_steps_config = [{...}]  [optional+computed]  # same shape as top-level wf_steps_config
+  run_post_plan_hooks_on_drift: bool  [optional+computed]
+  run_pre_init_hooks_on_drift: bool  [optional+computed]
+  run_pre_plan_hooks_on_drift: bool  [optional+computed]
+  terraform_bin_path = [{...}]  [optional+computed]
+    read_only: bool  [optional]
+    source: string  [REQUIRED]
+    target: string  [REQUIRED]
+  terraform_init_options: string  [optional+computed]
+  terraform_plan_options: string  [optional+computed]
+  terraform_version: string  [optional+computed]
+  timeout: number  [optional+computed]
+  wf_step_template_revision_id: string  [optional+computed]
+user_job_cpu: number  [optional+computed]
+user_job_memory: number  [optional+computed]
+user_schedules = [{...}]  [optional+computed]
+  cron: string  [REQUIRED]
+  desc: string  [optional]
+  name: string  [computed]
+  state: string  [REQUIRED]
+vcs_config = {...}  [REQUIRED]
+  iac_input_data = {...}  [optional+computed]
+    data: string  [optional+computed]
+    schema_id: string  [optional+computed]
+    schema_type: string  [optional+computed]
+  iac_vcs_config = {...}  [REQUIRED]
+    iac_template_id: string  [REQUIRED]
+wf_steps_config = [{...}]  [optional+computed]
+  approval: bool  [optional]
+  cmd_override: string  [optional]
+  environment_variables = [{...}]  [optional]
+    config = {...}  [REQUIRED]
+      secret_id: string  [optional]
+      text_value: string  [optional]
+      var_name: string  [REQUIRED]
+    kind: string  [REQUIRED]
+  mount_points = [{...}]  [optional]
+    read_only: bool  [optional]
+    source: string  [REQUIRED]
+    target: string  [REQUIRED]
+  name: string  [REQUIRED]
+  timeout: number  [optional]
+  wf_step_input_data = {...}  [optional]
+    data: string  [optional]
+    schema_type: string  [optional]
+  wf_step_template_id: string  [REQUIRED]
+wf_type: string  [REQUIRED]
+workflow_group_id: string  [REQUIRED]
+```
+
+### resource stackguardian_workflow_template
+```
+context_tags: map(string)  [optional+computed]
+description: string  [optional+computed]
+id: string  [optional+computed]
+is_public: string  [optional+computed]
+owner_org: string  [computed]
+runtime_source = {...}  [optional+computed]
+  config = {...}  [optional]
+    auth: string  [optional]
+    git_core_auto_crlf: bool  [optional+computed]
+    git_sparse_checkout_config: string  [optional]
+    include_sub_module: bool  [optional]
+    is_private: bool  [optional+computed]
+    ref: string  [optional+computed]
+    repo: string  [REQUIRED]
+    working_dir: string  [optional]
+  source_config_dest_kind: string  [optional]
+shared_orgs_list: list(string)  [optional+computed]
+source_config_kind: string  [REQUIRED]
+tags: list(string)  [optional+computed]
+template_name: string  [REQUIRED]
+```
+
+### resource stackguardian_workflow_template_revision
+```
+alias: string  [optional]
+approvers: list(string)  [optional]
+context_tags: map(string)  [optional+computed]
+deployment_platform_config = [{...}]  [optional+computed]
+  config = {...}  [REQUIRED]
+    integration_id: string  [REQUIRED]
+    profile_name: string  [optional]
+  kind: string  [REQUIRED]
+deprecation = {...}  [optional]
+  effective_date: string  [optional]
+  message: string  [optional]
+description: string  [optional+computed]
+environment_variables = [{...}]  [optional+computed]
+  config = {...}  [REQUIRED]
+    secret_id: string  [optional]
+    text_value: string  [optional]
+    var_name: string  [REQUIRED]
+  kind: string  [REQUIRED]
+id: string  [computed]
+input_schemas = [{...}]  [optional+computed]
+  encoded_data: string  [optional]
+  name: string  [optional]
+  type: string  [REQUIRED]
+  ui_schema_data: string  [optional]
+is_public: string  [optional+computed]
+mini_steps = {...}  [optional]
+  notifications = {...}  [optional]
+    email = {...}  [optional]
+      approval_required = [{...}]  [optional]
+        recipients: list(string)  [optional]
+      cancelled = [{...}]  [optional]
+        recipients: list(string)  [optional]
+      completed = [{...}]  [optional]
+        recipients: list(string)  [optional]
+      drift_detected = [{...}]  [optional]
+        recipients: list(string)  [optional]
+      errored = [{...}]  [optional]
+        recipients: list(string)  [optional]
+  webhooks = {...}  [optional]
+    approval_required = [{...}]  [optional]
+      webhook_name: string  [REQUIRED]
+      webhook_secret: string  [optional]
+      webhook_url: string  [REQUIRED]
+    cancelled = [{...}]  [optional]
+      webhook_name: string  [REQUIRED]
+      webhook_secret: string  [optional]
+      webhook_url: string  [REQUIRED]
+    completed = [{...}]  [optional]
+      webhook_name: string  [REQUIRED]
+      webhook_secret: string  [optional]
+      webhook_url: string  [REQUIRED]
+    drift_detected = [{...}]  [optional]
+      webhook_name: string  [REQUIRED]
+      webhook_secret: string  [optional]
+      webhook_url: string  [REQUIRED]
+    errored = [{...}]  [optional]
+      webhook_name: string  [REQUIRED]
+      webhook_secret: string  [optional]
+      webhook_url: string  [REQUIRED]
+  wf_chaining = {...}  [optional]
+    completed = [{...}]  [optional]
+      stack_id: string  [optional]
+      stack_run_payload: string  [optional]
+      workflow_group_id: string  [REQUIRED]
+      workflow_id: string  [optional]
+      workflow_run_payload: string  [optional]
+    errored = [{...}]  [optional]
+      stack_id: string  [optional]
+      stack_run_payload: string  [optional]
+      workflow_group_id: string  [REQUIRED]
+      workflow_id: string  [optional]
+      workflow_run_payload: string  [optional]
+notes: string  [optional+computed]
+number_of_approvals_required: number  [optional+computed]
+runner_constraints = {...}  [optional]
+  names: list(string)  [optional]
+  type: string  [REQUIRED]
+runtime_source = {...}  [optional+computed]
+  config = {...}  [optional]
+    auth: string  [optional]
+    git_core_auto_crlf: bool  [optional+computed]
+    git_sparse_checkout_config: string  [optional]
+    include_sub_module: bool  [optional]
+    is_private: bool  [optional+computed]
+    ref: string  [optional+computed]
+    repo: string  [REQUIRED]
+    working_dir: string  [optional]
+  source_config_dest_kind: string  [optional]
+source_config_kind: string  [REQUIRED]
+tags: list(string)  [optional+computed]
+template_id: string  [REQUIRED]
+terraform_config = {...}  [optional+computed]
+  approval_pre_apply: bool  [optional+computed]
+  drift_check: bool  [optional+computed]
+  drift_cron: string  [optional+computed]
+  managed_terraform_state: bool  [optional+computed]
+  post_apply_hooks: list(string)  [optional+computed]
+  post_apply_wf_steps_config = [{...}]  [optional+computed]  # same shape as top-level wf_steps_config
+  post_plan_hooks: list(string)  [optional+computed]
+  post_plan_wf_steps_config = [{...}]  [optional+computed]  # same shape as top-level wf_steps_config
+  pre_apply_hooks: list(string)  [optional+computed]
+  pre_apply_wf_steps_config = [{...}]  [optional+computed]  # same shape as top-level wf_steps_config
+  pre_init_hooks: list(string)  [optional+computed]
+  pre_plan_hooks: list(string)  [optional+computed]
+  pre_plan_wf_steps_config = [{...}]  [optional+computed]  # same shape as top-level wf_steps_config
+  run_pre_init_hooks_on_drift: bool  [optional+computed]
+  terraform_bin_path = [{...}]  [optional+computed]
+    read_only: bool  [optional+computed]
+    source: string  [optional]
+    target: string  [optional]
+  terraform_init_options: string  [optional+computed]
+  terraform_plan_options: string  [optional+computed]
+  terraform_version: string  [optional+computed]
+  timeout: number  [optional+computed]
+user_job_cpu: number  [REQUIRED]
+user_job_memory: number  [REQUIRED]
+user_schedules = [{...}]  [optional]
+  cron: string  [REQUIRED]
+  desc: string  [optional]
+  name: string  [optional]
+  state: string  [optional]
+wf_steps_config = [{...}]  [optional+computed]
+  approval: bool  [optional]
+  cmd_override: string  [optional]
+  environment_variables = [{...}]  [optional]
+    config = {...}  [REQUIRED]
+      secret_id: string  [optional]
+      text_value: string  [optional]
+      var_name: string  [REQUIRED]
+    kind: string  [REQUIRED]
+  mount_points = [{...}]  [optional]
+    read_only: bool  [optional+computed]
+    source: string  [optional]
+    target: string  [optional]
+  name: string  [REQUIRED]
+  timeout: number  [optional]
+  wf_step_input_data = {...}  [optional]
+    data: string  [optional]
+    schema_type: string  [optional]
+  wf_step_template_id: string  [REQUIRED]
+```
+
+### resource stackguardian_workflow_step_template
+```
+context_tags: map(string)  [optional+computed]
+description: string  [optional+computed]
+id: string  [optional+computed]
+is_public: string  [optional+computed]
+latest_revision: number  [computed]
+next_revision: number  [computed]
+runtime_source = {...}  [REQUIRED]
+  additional_config: map(string)  [optional]
+  config = {...}  [REQUIRED]
+    auth: string  [optional+sensitive]
+    docker_image: string  [REQUIRED]
+    docker_registry_username: string  [optional]
+    is_private: bool  [optional+computed]
+    local_workspace_dir: string  [optional]
+  source_config_dest_kind: string  [optional+computed]
+shared_orgs_list: list(string)  [optional+computed]
+source_config_kind: string  [REQUIRED]
+tags: list(string)  [optional+computed]
+template_name: string  [REQUIRED]
+template_type: string  [computed]
+```
+
+### resource stackguardian_workflow_step_template_revision
+```
+alias: string  [optional+computed]
+context_tags: map(string)  [optional+computed]
+deprecation = {...}  [optional]
+  effective_date: string  [optional+computed]
+  message: string  [optional+computed]
+description: string  [optional+computed]
+id: string  [computed]
+is_public: string  [optional+computed]
+notes: string  [optional+computed]
+runtime_source = {...}  [REQUIRED]
+  additional_config: map(string)  [optional]
+  config = {...}  [REQUIRED]
+    auth: string  [optional+sensitive]
+    docker_image: string  [REQUIRED]
+    docker_registry_username: string  [optional]
+    is_private: bool  [optional+computed]
+    local_workspace_dir: string  [optional]
+  source_config_dest_kind: string  [REQUIRED]
+source_config_kind: string  [REQUIRED]
+tags: list(string)  [optional+computed]
+template_id: string  [REQUIRED]
+template_type: string  [computed]
+```
+
+### resource stackguardian_runner_group
+```
+description: string  [optional+computed]
+id: string  [optional+computed]
+max_number_of_runners: number  [optional+computed]
+resource_name: string  [REQUIRED]
+run_controller_runtime_source = {...}  [optional]
+  config = {...}  [optional+computed]
+    auth: string  [optional+computed]
+    docker_image: string  [optional]
+    docker_registry_username: string  [optional]
+    git_core_auto_crlf: bool  [optional+computed]
+    git_sparse_checkout_config: string  [optional+computed]
+    include_sub_module: bool  [optional+computed]
+    local_workspace_dir: string  [optional]
+    ref: string  [optional+computed]
+    repo: string  [optional+computed]
+    working_dir: string  [optional+computed]
+  source_config_dest_kind: string  [optional+computed]
+runner_token: string  [optional+computed]
+storage_backend_config = {...}  [REQUIRED]
+  auth = {...}  [optional]
+    integration_id: string  [REQUIRED]
+  aws_region: string  [optional]
+  azure_blob_storage_access_key: string  [optional]
+  azure_blob_storage_account_name: string  [optional]
+  s3_bucket_name: string  [optional]
+  type: string  [REQUIRED]
+tags: list(string)  [optional+computed]
+```
+
+### data stackguardian_workflow_outputs
+```
+data: map(string)  [computed]
+data_json: string  [computed]
+workflow: string  [REQUIRED]
+workflow_group: string  [REQUIRED]
+```
diff --git a/skills/sg-writing-stackguardian-workflow-terraform/references/sources-and-templates.md b/skills/sg-writing-stackguardian-workflow-terraform/references/sources-and-templates.md
new file mode 100644
index 0000000..e4ae8cd
--- /dev/null
+++ b/skills/sg-writing-stackguardian-workflow-terraform/references/sources-and-templates.md
@@ -0,0 +1,234 @@
+# Sources and templates
+
+Where a workflow's IaC comes from. "(live)" = reproduced against a real org with provider 1.12.3;
+"(unverified)" = inferred from code, not executed. Everything else was read in provider / api /
+core / sg-run-controller source.
+
+## 1. Git source — `stackguardian_workflow_git`
+
+Path: `vcs_config.iac_vcs_config.custom_source = { source_config_dest_kind, config = {...} }`.
+The provider always sends `useMarketplaceTemplate = false`; there is no attribute for it.
+
+| `source_config_dest_kind` | Use for | `auth` for a private repo |
+|---|---|---|
+| `GITHUB_COM` | github.com via the StackGuardian GitHub App connector | `/integrations/github_com` (singleton id) or `/secrets/<pat>` |
+| `GITHUB_APP_CUSTOM` | GitHub Enterprise / your own GitHub App | `/integrations/<connector>`; shared runners must reach the GHE API, else use a private runner |
+| `GITLAB_COM` | gitlab.com | `/integrations/<connector>` |
+| `BITBUCKET_ORG` | bitbucket.org | `/integrations/<connector>` (API-token connectors also need `bitbucketEmail` on the connector) |
+| `AZURE_DEVOPS` | dev.azure.com (PAT connector) | `/integrations/<connector>` |
+| `AZURE_DEVOPS_SP` | dev.azure.com via service principal | `/integrations/<connector>` |
+| `GIT_OTHER` | any other host (there is no AWS CodeCommit kind, from code), SSH URLs, self-hosted GitLab/GitHub without a connector | **only** `/secrets/<name>`: for https the secret value becomes the URL's user part, so store `user:token` (e.g. `oauth2:<token>` for GitLab; unverified per host); for `git@`/`ssh://` store a private key |
+
+Rules:
+
+- **Always set `is_private`.** The API rejects a missing value (`{"isPrivate": ["required"]}`).
+  Public repo: `is_private = false`, no `auth`, any kind. Private without auth:
+  `{"auth": ["auth required for isPrivate"]}`. Private `GIT_OTHER` with a connector:
+  `{"auth": ["only secrets supported for GIT_OTHER"]}`.
+- **The kind must equal the connector's kind** (the dashboard always copies it from the
+  connector). The provider does no host inference: a GitHub App connector on a github.com repo
+  needs `GITHUB_APP_CUSTOM`, not `GITHUB_COM`. Let Terraform copy it:
+  `source_config_dest_kind = data.stackguardian_connector.vcs.settings.kind`.
+- Other kind/auth mismatches (e.g. `/secrets/...` on `GITLAB_COM`) are accepted at create and fail
+  at clone: `Unsupported 'auth' for private repo of '<KIND>' sourceConfigDestKind`.
+- `repo`: `https://…` or SSH (`git@host:org/repo.git`, `ssh://…`). `http://` fails at run. For VCS
+  triggers use the plain https URL (no trailing slash): the webhook is matched by URL string.
+  With `GITHUB_COM` / `GITHUB_APP_CUSTOM` the server parses `<owner>/<repo>` out of the URL at
+  create; a URL it cannot parse fails with 404 `Invalid GitHub repo` (from code).
+- `ref`: branch, tag or commit; omitted = the remote default branch. Clones are `--depth=1`, so a
+  commit SHA works only if the git server allows fetch-by-SHA.
+- `working_dir`: path inside the repo; never checked at create. At run a missing directory fails
+  with `No such directory exists: <path>`, one without `.tf` files with `No OpenTofu/Terraform files
+  found in the working directory of the specified repository`.
+- `include_sub_module` is stored but **ignored at run** (depth-1 fetch, submodules stay empty).
+  Vendor submodules or use module sources instead.
+- `git_sparse_checkout_config`: newline-separated non-cone patterns; `working_dir` must be inside
+  them or the directory is empty.
+- Private Terraform module sources on the same VCS work: the run configures a git credential
+  helper from the workflow's `auth`.
+
+## 2. Template source — `stackguardian_workflow_from_template`
+
+```terraform
+vcs_config = {
+  iac_vcs_config = { iac_template_id = "/acme/vpc-module:3" } # /<owner-org>/<template>:<revision>
+  iac_input_data = { schema_type = "FORM_JSONSCHEMA", data = jsonencode({ cidr = "10.20.0.0/16" }) }
+}
+```
+
+### Template id
+
+| Form | Result |
+|---|---|
+| `/<owner-org>/<name>:<n>` | ✅ Use this, also for your own org (other orgs' templates hit the provider bug below) |
+| `<name>:<n>` (bare) | ❌ 404 `Template <name>:<n> of type IAC does not exist` (live) — the provider docs are wrong here. The provider's own revision lookup resolves a bare id against your org, so plan passes; the API create is what rejects it |
+| `/<org>/<name>:latest` or `:<alias>` | Works, but the **code** (repo/ref of the revision) is re-resolved on every run while the **settings** stay frozen from create; the provider never re-resolves on its own. Pin a number |
+| `/<org>/<name>` (no suffix) | Resolves to the parent skeleton, not a revision. Never |
+
+- Build it from a resource: `"/${var.org}/${stackguardian_workflow_template_revision.v1.id}"`
+  (the revision's `id` is `<template>:<n>`).
+
+### Provider 1.12.3: only templates owned by your org work
+
+The provider fetches the revision itself (on create, on every update, and at plan when
+`iac_template_id` changes) and sends the template's **owner** org as `x-sg-orgid`; the API answers
+401 unless that is the caller's org. So any template of another org — every `/stackguardian/…`
+marketplace template, templates shared with you — fails at apply (live):
+
+```
+Error: Error reading workflow template revision
+Could not read template revision "/stackguardian/aws-s3-demo-website:16" to resolve workflow defaults: 401: {"message":"Unauthorized"}
+```
+
+Workarounds until the provider is fixed:
+1. **Own-org copy** — `stackguardian_workflow_template` + `_revision` pointing at the same
+   repo/ref and inputs, then `workflow_from_template` on `/<your-org>/<copy>:<n>`
+   (`examples/own_template.tf`).
+2. **`stackguardian_workflow_git`** on the template's source repository, with the settings written
+   out (no template linkage or upgrades).
+3. Create that workflow outside Terraform (dashboard / API / MCP `create_workflow`). Importing it
+   does not help: every later update re-fetches the revision and 401s.
+
+Pick 1 when several workflows should share the definition and receive upgrades, 2 for a single
+workflow. Switching a workflow between `workflow_git` and `workflow_from_template` later is a new
+resource type, i.e. a replacement (managed state does not carry over).
+
+To see what a marketplace revision contains (repo, ref, working dir, inputs, Terraform settings),
+read it with **your** org in the header — this works although the provider's call does not:
+
+```bash
+curl -s -H "Authorization: apikey $STACKGUARDIAN_API_KEY" -H "x-sg-orgid: <your-org>" \
+  "$STACKGUARDIAN_API_URI/api/v1/templatetypes/IAC/stackguardian/aws-s3-demo-website:16/"
+# .msg.RuntimeSource = git source, .msg.InputSchemas[].encodedData = base64 JSON Schema
+```
+- **Platform access rules** (relevant once the provider bug below is fixed, and for the API): the
+  revision must be published (`is_public = "1"`), owned by your org (drafts are fine), or shared
+  with your org; otherwise create succeeds and every run fails `<id> is a private template and
+  can only be used by its owner org and orgs the template is shared with`. There is no
+  subscription check anywhere.
+- `wf_type` must fit the template: TERRAFORM/OPENTOFU templates → TERRAFORM or OPENTOFU (both
+  generate the same steps; OpenTofu on a Terraform template works if the code is OpenTofu-compatible,
+  unverified); step-based
+  (CUSTOM/ANSIBLE_PLAYBOOK/HELM/…) templates → `CUSTOM`. `CUSTOM` on a Terraform template is rejected: the provider merges the template's `terraform_config` into
+  the request → 400 `not allowed for CUSTOM Workflow Type` (from code).
+- A deleted, archived or unshared revision breaks every run of every workflow that uses it.
+
+### Inheritance (the provider merges the revision into your config at plan/create time)
+
+| You write | Result |
+|---|---|
+| attribute omitted | inherited from the revision (live) |
+| top-level `tags = []`, `approvers = []`, `environment_variables = []`, `deployment_platform_config = []`, `user_schedules = []`, `wf_steps_config = []`, `context_tags = {}`, `mini_steps = {}` | template value suppressed (live for tags/env vars) |
+| `description = ""` | suppressed |
+| `terraform_config = { pre_plan_hooks = [] }` (any `*_hooks`, `*_wf_steps_config`, `terraform_bin_path`) | **not** suppressed: server keeps the template's value → *inconsistent result*, resource tainted (live) |
+| `""` on `terraform_version`, `drift_cron`, `terraform_plan_options`, `terraform_init_options` | not suppressed → template value (inconsistent result if the template sets it) |
+| `terraform_config.wf_step_template_revision_id = ""` | the exception: sent as-is, so the template's runtime image is dropped and the platform default image is used (from code) |
+| `false` / `0` on `terraform_config` booleans / `timeout` | honoured |
+| `null` | same as omitted (inherits) |
+
+You cannot remove a template's nested `terraform_config` values from a `workflow_from_template`
+workflow. Publish a revision without them, or use `stackguardian_workflow_git`.
+
+- **`iac_input_data` omitted** → the provider sends the template's `FORM_JSONSCHEMA` defaults
+  (top-level `properties[].default`, recursively, but not inside `oneOf/anyOf/allOf`) (live).
+  Declared → it replaces the template's inputs **entirely** (no key merge), so repeat every
+  input you need. `data = "{}"` → no inputs. `data = ""` → inherits.
+- Removing an attribute from config later **keeps the value already in state**; it is only
+  re-inherited when the revision changes.
+- `resource_name` is never inherited: set it, or the server invents a random 21-character name.
+- `vcs_triggers` does not exist on this resource (the platform supports triggers only for git
+  sources).
+- `terraform_config.wf_step_template_revision_id` exists **only** on this resource (custom
+  runtime image, §4).
+
+### Upgrading to a new revision
+
+Change `…:1` → `…:2` and apply. Attributes you **declared** keep your values; attributes you
+**left out** adopt the new revision's values (defaults when the revision has none: approvals
+count 0, CPU 512, memory 1024, runner `{type = "shared"}`, from code). Live-verified: undeclared
+tags/CPU/memory moved to the new revision's values, declared ones stayed, and an undeclared
+`iac_input_data` was **dropped** because the new revision had no input schema.
+
+**Two applies** when you create the new revision in the same configuration: the revision id is
+unknown at plan time, so switching `iac_template_id` in the same apply fails with *Provider
+produced inconsistent final plan* (live). Apply the new revision first, then change the
+reference. A wrong id fails at *plan*:
+`Could not read template revision "<id>" to resolve workflow defaults`. The provider sends no
+`upgradeMode`, so this is not the dashboard's "Upgrade" (which reconciles inputs and can reset
+settings) — review the plan.
+
+## 3. Your own templates — `stackguardian_workflow_template` + `_revision`
+
+The template is a container; the revision holds the content. Minimal pair: `examples/own_template.tf`.
+
+- `template_name` becomes the template `id` when it is slug-shaped; otherwise the server
+  slugs it and appends a random suffix (live: `ZZ Skill Test 20261021` →
+  `zz-skill-test-20261021-gpuzsrbeas6u`). Set `id` to pin it. Revisions are
+  `<template>:1`, `:2`, … (the provider creates the template without a skeleton revision, so your
+  first revision is `:1`).
+- **Set `runtime_source` on every revision.** A revision holds exactly what you send: nothing is
+  copied from the template or the previous revision. A revision without it has an empty source
+  and every run fails with `Template has no git repository in RuntimeSource` (from code).
+- `user_job_cpu` and `user_job_memory` are **required** on a revision.
+- `source_config_kind`: `TERRAFORM`, `OPENTOFU`, `ANSIBLE_PLAYBOOK`, `HELM`, `KUBECTL`,
+  `CLOUDFORMATION`, `CUSTOM`. `wf_steps_config` on a TERRAFORM/OPENTOFU revision is a plan error.
+- Plan-time checks on `runtime_source`: every kind except `GIT_OTHER` needs `auth` starting with
+  `/integration` **even for a public repo**; `GIT_OTHER` auth must start with `/secrets/`
+  (`Invalid runtime_source Configuration`). Public repo without a connector → `GIT_OTHER` with
+  `is_private = false` and no `auth` (live).
+- Pin `runtime_source.config.ref` to a tag or commit in published revisions: a branch keeps moving
+  under every workflow that uses the revision.
+- Immutable, and a plan **error** rather than a replacement: `id`, `source_config_kind`,
+  `runtime_source.config.repo` (template); `template_id`, `source_config_kind`, `repo` (revision).
+  Create a new resource instead. Server-side a revision also refuses changes to
+  `runtime_source.source_config_dest_kind`, and once published or deprecated to
+  `runtime_source.config.auth` (`Cannot update <keys> for a template`, from code).
+- Terraform > 1.5.7 in a revision's `terraform_config` is rejected like on a workflow
+  (execution §2, from code).
+- `is_public` on a **revision**: `"1"` = published (afterwards only description, deprecation,
+  alias and notes can change — `Cannot update <keys> for a published template`); `"0"` = draft,
+  usable only by the owner org (live). On the **template**: `"1"` = listed publicly for other orgs
+  (400 `A template with private repo cannot be made public`); `shared_orgs_list` entries are
+  `/orgs/<org>` (a bare name never matches).
+- `input_schemas = [{ type = "FORM_JSONSCHEMA", encoded_data = base64encode(jsonencode(<JSON
+  Schema>)) }]` — the `default`s are what `workflow_from_template` inherits as inputs.
+- API-created templates are not subscribed to their own org, so the dashboard shows "Inactive".
+  Terraform-created workflows still use them.
+- Read has no 404 handling on both resources: after an out-of-band delete, `terraform state rm`.
+- Set `alias` on revisions (an unset alias may read back as `""` → inconsistent result; from code).
+  Rules (from code): not a pure integer, not `latest`, only `[A-Za-z0-9._-]`, unique within the
+  template; `""` removes it. `/<org>/<template>:<alias>` then works as an `iac_template_id`
+  (but pin a number, §2).
+- **Deprecation and delete** (live unless marked):
+  - `deprecation` cannot be set when the revision is created (`409 Deprecation cannot be set when
+    creating a template`): add it in a later apply. It is also refused on a draft (`Cannot set
+    Deprecation on a template revision that is not published`, from code).
+  - `effective_date` is epoch **milliseconds** as a string (`"1798675200000"` = 2026-12-31 UTC).
+    The server stores whatever string you send and compares it with the current time in ms, so a
+    seconds value lies in 1970 and the revision is deprecated at once.
+  - Once the date has passed, only the deprecation message and alias can change, and the date
+    cannot move later (`Cannot update effectiveDate for a template that has already been
+    deprecated`). Moving a future date earlier, into the past, works.
+  - Deleting a published revision (`terraform destroy`, or removing the resource) is refused
+    until it is deprecated and the date has passed: `Published template cannot be deleted. Please
+    deprecate the template first.` / `Published template cannot be deleted until the deprecation
+    effective date has passed`. To tear down: apply a `deprecation` with a past date, then
+    destroy. Drafts (`is_public = "0"`) delete freely.
+- Import: template `id`; revision `<template>:<n>`. The `stackguardian_workflow_template_revision`
+  **data source** takes the bare `<template>:<n>` of your own org only; a `/<org>/` prefix fails
+  with `Unable to read workflow template revision.` and a misleading `403: {"msg":""}` (live).
+
+## 4. Custom runtime image (Terraform > 1.5.7, extra CLIs)
+
+- `stackguardian_workflow_step_template` + `_revision` with
+  `source_config_kind = "DOCKER_IMAGE"` and `runtime_source = { source_config_dest_kind =
+  "CONTAINER_REGISTRY", config = { docker_image = "<registry>/<image>:<tag>" } }` (required on the
+  revision; write them on the template too). Private registries: `config.auth = "/secrets/<name>"`
+  plus `docker_registry_username`; shared runners cannot pull private non-ECR images.
+- Build `FROM public.ecr.aws/stackguardian/workflow-steps/iac-base:v5.0.0`, install as root, switch
+  back to `USER stackguardian`, keep ENTRYPOINT/CMD, don't modify `/usr/local/bin`.
+- Use it with `workflow_from_template.terraform_config.wf_step_template_revision_id =
+  "/<org>/<step-template>:<rev>"`, or as a CUSTOM step's `wf_step_template_id`.
+- `stackguardian_workflow_git` has no `wf_step_template_revision_id`. Newer Terraform there means:
+  switch to OpenTofu, an org-level execution preset (runtime image) applied server-side at create,
+  or a private runner binary (`references/execution.md` §2).