From 7159204edefcc9dfde3d961c928a1056e08b12fb Mon Sep 17 00:00:00 2001
From: Speculator55005 <50082482+fas89@users.noreply.github.com>
Date: Sat, 23 May 2026 16:17:39 +0200
Subject: [PATCH] perf(demos): defer CliCast SVG fetch; docs: scaffold examples
 accuracy pass
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CliCast now mounts a CSS-only placeholder until the visitor clicks Play —
the 14 large animated SVGs on /demos/ are no longer fetched or decoded on
initial load. Cold transfer for the page drops from ~3.8 MB to ~0.8 MB
(measured: 803 KB / 80 ms / 0 SVGs fetched before interaction; ~150 KB per
cast on Play click). The IntersectionObserver-driven poster <img> and its
state are removed; a 920/560 aspect-ratio on the viewport keeps layout
stable when the live <object> mounts.

Replaced numeric AWS account-ID placeholders with GCP project examples in
the three SDK docs pages where they appeared (your-own-scaffolding,
your-own-ci, gitlab-ci-scaffold).

Rewrote the gitlab-ci-scaffold example to match the actual SDK source
(verified against Agenticstiger/forge-cli-sdk main): the page previously
documented a fabricated "Pick your cloud" AWS/GCP/Snowflake taxonomy that
didn't exist in the plugin. The real plugin is provider-agnostic and reads
two flat string labels (cloud.accountId, cloud.region) off
environments.<env>.metadata.labels. Both renderers (_render_ci with the
when: manual prod gate, _render_env_config with the structured cloud
block) and the test excerpts now match the upstream code byte-for-byte.

Also adds .claude/ to .gitignore (local tooling state).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .gitignore                                    |   3 +
 docs/.vuepress/components/CliCast.vue         |  87 ++---
 .../examples/gitlab-ci-scaffold.md            | 335 ++++++++----------
 docs/sdk-and-plugins/journeys/your-own-ci.md  |   6 +-
 .../journeys/your-own-scaffolding.md          |   2 +-
 5 files changed, 179 insertions(+), 254 deletions(-)

diff --git a/.gitignore b/.gitignore
index d753f6a..56a1e9d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,6 +16,9 @@ Thumbs.db
 *.swo
 *~
 
+# Claude Code local tooling (launch.json, scheduled_tasks.lock)
+.claude/
+
 # Logs
 *.log
 npm-debug.log*
diff --git a/docs/.vuepress/components/CliCast.vue b/docs/.vuepress/components/CliCast.vue
index b42f32a..87b3084 100644
--- a/docs/.vuepress/components/CliCast.vue
+++ b/docs/.vuepress/components/CliCast.vue
@@ -8,8 +8,8 @@
   The svg-term output already includes the macOS three-dot title
   bar. This component adds:
     - the surrounding browser-window-style frame
-    - a click-to-play overlay (so the heavy SVG only animates after
-      the visitor opts in)
+    - a click-to-play overlay (so the heavy SVG is only fetched
+      after the visitor opts in)
     - a replay button
     - an optional caption row beneath
 
@@ -22,19 +22,20 @@
       width="900"
     />
 
-  All props are optional except `src`. The SVG itself is loaded
-  lazily (intersection-observer) so an off-screen cast doesn't burn
-  bandwidth until you scroll near it.
+  All props are optional except `src`. The SVG is NOT fetched until
+  the visitor clicks Play — index pages with many casts pay zero
+  network cost on first paint. The placeholder uses an aspect-ratio
+  box so layout doesn't shift when the animation mounts.
   ============================================================
 -->
 
 <template>
   <figure
     class="ff-cast"
-    :class="{ 'ff-cast--playing': playing, 'ff-cast--loaded': loaded }"
+    :class="{ 'ff-cast--playing': playing }"
     :style="{ '--ff-cast-w': widthPx }"
   >
-    <div class="ff-cast__frame" ref="frameRef">
+    <div class="ff-cast__frame">
       <header class="ff-cast__chrome" v-if="title">
         <span class="ff-cast__dot ff-cast__dot--red"></span>
         <span class="ff-cast__dot ff-cast__dot--yellow"></span>
@@ -43,25 +44,14 @@
       </header>
 
       <div class="ff-cast__viewport">
-        <!-- Static poster — frame 0 of the cast. Rendered once the frame
-             scrolls into view; it sets the viewport height and is what
-             the visitor sees before (and behind) playback. -->
-        <img
-          v-if="visible"
-          :src="src"
-          :alt="alt || title || 'CLI demo'"
-          :aria-hidden="playing ? 'true' : null"
-          class="ff-cast__svg"
-          @load="loaded = true"
-          loading="lazy"
-        />
-
         <!-- Live animation. CSS @keyframes inside an SVG only run when the
              SVG loads as its own document — an <img> silently freezes it
              at frame 0 — so the cast is embedded via <object>. Mounted
-             only after the visitor clicks play; re-keyed by replay(). -->
+             (and fetched) only after the visitor clicks play; re-keyed by
+             replay(). Nothing on the page touches the network for this
+             cast until then — index pages with many casts cost ~0KB. -->
         <object
-          v-if="visible && playing"
+          v-if="playing"
           :key="reloadKey"
           :data="src"
           type="image/svg+xml"
@@ -72,7 +62,9 @@
           <span class="ff-cast__sr">{{ alt || title || 'CLI demo animation' }}</span>
         </object>
 
-        <!-- Click-to-play overlay (covers the poster until the visitor opts in) -->
+        <!-- Click-to-play placeholder. Pure CSS — no image fetched yet.
+             The viewport itself carries the aspect-ratio so layout doesn't
+             shift when the <object> mounts and the SVG loads. -->
         <button
           v-if="!playing"
           type="button"
@@ -123,7 +115,7 @@
 </template>
 
 <script setup lang="ts">
-import { ref, onMounted, onBeforeUnmount, computed } from 'vue'
+import { ref, computed } from 'vue'
 
 interface Props {
   /** Path to the rendered animated SVG (typically /demos/<name>.svg) */
@@ -169,42 +161,11 @@ const insightLines = computed<string[]>(() => {
     .filter(Boolean)
 })
 
-const frameRef = ref<HTMLElement | null>(null)
-const visible = ref(false)
 const playing = ref(false)
-const loaded = ref(false)
 const reloadKey = ref(0)
 
-let observer: IntersectionObserver | null = null
-
-onMounted(() => {
-  if (!frameRef.value || typeof IntersectionObserver === 'undefined') {
-    visible.value = true // SSR or older browsers — just show immediately
-    return
-  }
-  observer = new IntersectionObserver(
-    (entries) => {
-      for (const e of entries) {
-        if (e.isIntersecting) {
-          visible.value = true
-          observer?.disconnect()
-          break
-        }
-      }
-    },
-    { rootMargin: '200px' },
-  )
-  observer.observe(frameRef.value)
-})
-
-onBeforeUnmount(() => {
-  observer?.disconnect()
-  observer = null
-})
-
 function play() {
-  // Mount the cast even if the IntersectionObserver hasn't fired yet.
-  visible.value = true
+  // First mount of <object> — this is when the SVG is actually fetched.
   playing.value = true
 }
 
@@ -279,15 +240,15 @@ function onObjectLoad(e: Event) {
     position: relative;
     background: #0d1117;
     line-height: 0;
+    // svg-term casts render at 920 wide; observed heights span 477–651
+    // (median ~560). A fixed 920/560 ratio keeps the placeholder visually
+    // honest, and means at most one cast (the tallest) will scroll-jump
+    // slightly when the SVG mounts — instead of every cast on the page
+    // shifting after Play.
+    aspect-ratio: 920 / 560;
   }
 
-  &__svg {
-    display: block;
-    width: 100%;
-    height: auto;
-  }
-
-  // Live animated cast — overlays the poster, identical box.
+  // Live animated cast — fills the viewport box.
   &__object {
     position: absolute;
     inset: 0;
diff --git a/docs/sdk-and-plugins/examples/gitlab-ci-scaffold.md b/docs/sdk-and-plugins/examples/gitlab-ci-scaffold.md
index 300fdf6..d9f5534 100644
--- a/docs/sdk-and-plugins/examples/gitlab-ci-scaffold.md
+++ b/docs/sdk-and-plugins/examples/gitlab-ci-scaffold.md
@@ -1,6 +1,6 @@
 # Example: `gitlab-ci-scaffold` — generate a complete CI project
 
-A realistic `CustomScaffold` plugin: given any fluid contract, emit a full `README.md` + `.gitlab-ci.yml` + one `config/<env>.json` per declared environment. ~150 LOC, ~25 tests (20 inherited from the conformance harness + 5 plugin-specific).
+A realistic `CustomScaffold` plugin: given any fluid contract, emit a full `README.md` + `.gitlab-ci.yml` + one `config/<env>.json` per declared environment. ~140 LOC, 22 passing tests (15 inherited from the conformance harness + 5 plugin-specific).
 
 > **Source:** [`Agenticstiger/forge-cli-sdk` → `examples/gitlab-ci-scaffold/`](https://github.com/Agenticstiger/forge-cli-sdk/tree/main/examples/gitlab-ci-scaffold).
 
@@ -8,154 +8,73 @@ A realistic `CustomScaffold` plugin: given any fluid contract, emit a full `READ
 
 The contract is the source of truth. Change `environments` in the contract, regenerate, and the CI definition + config files adapt automatically — no per-env template editing.
 
-Given a contract that declares its environments and clouds, the plugin emits:
+Given a contract that declares its environments, the plugin emits:
 
 ```text
 README.md                                  ← project README with owner/domain/envs
-.gitlab-ci.yml                             ← 2-stage pipeline + 1 deploy job per env
-config/dev.json                            ← per-env cloud config (provider-shaped)
+.gitlab-ci.yml                             ← validate + 1 deploy job per env (prod is when: manual)
+config/dev.json                            ← per-env cloud config
 config/staging.json
 config/prod.json
 ```
 
 Add a fourth environment to the contract, regenerate, and a fourth deploy job + config appears. Drop one, and the CI shrinks. **The contract drives the pipeline.**
 
-### Pick your cloud
+### Contract shape
 
-The plugin reads `environments.<env>.cloud` from the contract. The exact field shape is provider-specific (AWS has `account`, GCP has `project`, Snowflake has `account` + `warehouse`, …). Pick the one that matches your deploy target:
+The plugin is **provider-agnostic**. It reads two free-form string labels from each environment:
 
+- `metadata.labels."cloud.accountId"` — your cloud's identifier (GCP project ID, AWS account number, Snowflake account name, …)
+- `metadata.labels."cloud.region"` — your cloud's region
 
-::: details AWS — accounts + regions
-```yaml
-# contract.fluid.yaml
-metadata:
-  id: order-events
-  name: Order Events
-  description: Realtime order event stream.
-  owner: { email: events-team@example.com }
-  domain: commerce
+That's it. The plugin doesn't know or care which cloud you're on — it just shells the two labels straight into the generated `config/<env>.json`. Use whatever values match your deploy target.
 
-environments:
-  dev:
-    cloud: { provider: aws, account: "111111111111", region: us-east-1 }
-  staging:
-    cloud: { provider: aws, account: "222222222222", region: us-east-1 }
-  prod:
-    cloud: { provider: aws, account: "333333333333", region: us-west-2 }
-```
-
-Generated `config/dev.json`:
-
-```json
-{
-  "cloud": "aws",
-  "account": "111111111111",
-  "region": "us-east-1"
-}
-```
-
-The plugin's `_render_env_config` reads `account` and `region` directly off the `cloud` block. The 12-digit string is the AWS account ID — quoted to keep YAML from interpreting it as a number.
-:::
-
-
-
-::: details GCP — project IDs + regions
 ```yaml
 # contract.fluid.yaml
+fluidVersion: "0.7.4"
+kind: DataProduct
+id: order-events
+name: Order Events
+description: Realtime order event stream.
+domain: commerce
 metadata:
-  id: order-events
-  name: Order Events
-  description: Realtime order event stream.
-  owner: { email: events-team@example.com }
-  domain: commerce
+  owner: { team: commerce, email: events-team@example.com }
 
 environments:
   dev:
-    cloud: { provider: gcp, project: "order-events-dev",     region: us-central1 }
+    metadata:
+      labels:
+        cloud.accountId: "order-events-dev"
+        cloud.region: us-central1
   staging:
-    cloud: { provider: gcp, project: "order-events-staging", region: us-central1 }
-  prod:
-    cloud: { provider: gcp, project: "order-events-prod",    region: us-east1 }
-```
-
-Generated `config/dev.json`:
-
-```json
-{
-  "cloud": "gcp",
-  "project": "order-events-dev",
-  "region": "us-central1"
-}
-```
-
-GCP-shaped contracts use `project` (the GCP project ID — kebab-case string), not `account`. Region names follow GCP's convention (`us-central1`, `us-east1`, `europe-west4`, …).
-
-> **Adapt the plugin**: the `gitlab-ci-scaffold` example in the SDK repo is written for AWS-shaped contracts (`account`). For GCP, change `_render_env_config` to emit `"project": env.get("project", "")` in place of `account`, or make the helper provider-aware. See the full source below — it's ~6 lines.
-:::
-
-
-
-::: details Snowflake — account + warehouse + role
-```yaml
-# contract.fluid.yaml
-metadata:
-  id: order-events
-  name: Order Events
-  description: Realtime order event stream.
-  owner: { email: events-team@example.com }
-  domain: commerce
-
-environments:
-  dev:
-    cloud:
-      provider: snowflake
-      account: "myorg-dev.us-east-1"
-      database: ORDERS_DEV
-      schema:   PUBLIC
-      warehouse: WH_XS
-      role:      DATA_ENGINEER
+    metadata:
+      labels:
+        cloud.accountId: "order-events-staging"
+        cloud.region: us-central1
   prod:
-    cloud:
-      provider: snowflake
-      account: "myorg-prod.us-east-1"
-      database: ORDERS_PROD
-      schema:   PUBLIC
-      warehouse: WH_M
-      role:      DATA_PRODUCT_OWNER
+    metadata:
+      labels:
+        cloud.accountId: "order-events-prod"
+        cloud.region: us-east1
 ```
 
 Generated `config/dev.json`:
 
 ```json
 {
-  "cloud": "snowflake",
-  "account": "myorg-dev.us-east-1",
-  "database": "ORDERS_DEV",
-  "warehouse": "WH_XS",
-  "role": "DATA_ENGINEER"
+  "cloud": {
+    "accountId": "order-events-dev",
+    "region": "us-central1"
+  },
+  "environment": "dev",
+  "product": {
+    "id": "order-events",
+    "owner": "events-team@example.com"
+  }
 }
 ```
 
-Snowflake contracts carry `database` / `schema` / `warehouse` / `role` in the `cloud` block — none of which apply to AWS or GCP. The plugin's `_render_env_config` should switch on `cloud.provider` and pick the relevant keys for each provider.
-:::
-
-
-
-::: details Multi-cloud — different clouds per environment
-```yaml
-# contract.fluid.yaml — dev runs in GCP, prod in AWS
-environments:
-  dev:
-    cloud: { provider: gcp, project: "order-events-dev", region: us-central1 }
-  prod:
-    cloud: { provider: aws, account: "333333333333",     region: us-west-2 }
-```
-
-A contract can declare different `provider:` values per environment — useful for "test on the cheap cloud, ship on the expensive one" patterns. Make sure your plugin's `_render_env_config` handles both shapes.
-:::
-
-
-The plugin and its tests in the SDK repo are written against the **AWS** shape; that's the canonical form throughout the rest of this page.
+> The label name `cloud.accountId` is generic — it's a string-keyed label, not a typed cloud-binding field. AWS folks would put `"111111111111"` in there; Snowflake folks would put `"myorg.us-east-1"`. The plugin doesn't validate the format, so it works the same for any provider. If your org needs richer per-cloud metadata (warehouse, role, project number, …), add more labels and extend `_render_env_config` to read them.
 
 ## Layout
 
@@ -166,8 +85,8 @@ gitlab-ci-scaffold/
 │   ├── __init__.py
 │   └── scaffold.py                ← ~140 lines, full source below
 ├── tests/
-│   └── test_scaffold.py           ← 97 lines, plugin-specific scenarios
-└── demo.py                        ← runnable demo against LOCAL_CONTRACT
+│   └── test_scaffold.py           ← 5 domain assertions on top of the conformance harness
+└── demo.py                        ← runnable demo against a 3-env CONTRACT
 ```
 
 ## `src/gitlab_ci_scaffold/scaffold.py`
@@ -268,34 +187,40 @@ def _render_readme(self, c: ContractHelper) -> str:
 
 
 
-::: details Renderer 2: _render_ci — produces .gitlab-ci.yml with one deploy job per env
+::: details Renderer 2: _render_ci — produces .gitlab-ci.yml with one deploy job per env (prod is when: manual)
 ```python
 def _render_ci(self, c: ContractHelper) -> str:
     envs = c.environment_names()
-    lines = [
-        f"# Auto-generated GitLab CI for {c.id}",
-        "# DO NOT EDIT BY HAND — regenerate via `fluid generate custom-scaffold`",
-        "",
-        "stages: [validate, deploy]",
-        "",
-        "validate:",
-        "  stage: validate",
-        "  script:",
-        "    - fluid validate contract.fluid.yaml",
-        "",
-    ]
-    for env_name in envs:
-        lines.extend([
-            f"deploy:{env_name}:",
-            "  stage: deploy",
-            "  script:",
-            f"    - fluid apply contract.fluid.yaml --env {env_name} --yes",
-            "  rules:",
-            "    - if: $CI_COMMIT_BRANCH == \"main\"",
-            "",
-        ])
+    lines: List[str] = []
+    lines.append(f"# Auto-generated GitLab CI for {c.id}")
+    lines.append("# DO NOT EDIT BY HAND — regenerate via `fluid generate custom-scaffold`")
+    lines.append("")
+    lines.append("stages:")
+    lines.append("  - validate")
+    lines.append("  - deploy")
+    lines.append("")
+    lines.append("validate:")
+    lines.append("  stage: validate")
+    lines.append("  script:")
+    lines.append("    - fluid validate")
+    lines.append("")
+    for env in envs:
+        lines.append(f"deploy:{env}:")
+        lines.append("  stage: deploy")
+        lines.append("  script:")
+        lines.append(f"    - fluid apply --env {env}")
+        if env == "prod":
+            lines.append("  when: manual")
+            lines.append("  only:")
+            lines.append("    - main")
+        else:
+            lines.append("  only:")
+            lines.append("    - main")
+        lines.append("")
     return "\n".join(lines)
 ```
+
+Note the `when: manual` branch — prod deploys are gated so they don't auto-run on merge to main. A reviewer has to click "Run" in the GitLab pipeline UI. This is the single most important production-safety convention this plugin enforces, and it's pinned by a test (`test_prod_deploy_is_manual`).
 :::
 
 
@@ -303,82 +228,118 @@ def _render_ci(self, c: ContractHelper) -> str:
 ::: details Renderer 3: _render_env_config — produces one config/&lt;env&gt;.json per environment
 ```python
 def _render_env_config(self, c: ContractHelper, env_name: str) -> str:
-    env = (c.environments.get(env_name) or {}).get("cloud", {})
-    return json.dumps({
-        "cloud": env.get("provider", "unknown"),
-        "account": env.get("account", ""),
-        "region": env.get("region", ""),
-    }, indent=2, sort_keys=True)
+    env = c.environments.get(env_name) or {}
+    env_meta = env.get("metadata") or {}
+    labels = env_meta.get("labels") or {}
+    config = {
+        "environment": env_name,
+        "cloud": {
+            "accountId": labels.get("cloud.accountId", "unknown"),
+            "region": labels.get("cloud.region", "unknown"),
+        },
+        "product": {
+            "id": c.id,
+            "owner": c.owner.get("email"),
+        },
+    }
+    return json.dumps(config, indent=2, sort_keys=True) + "\n"
 ```
 
-This is the AWS-shaped renderer. For GCP-shaped contracts (`project` instead of `account`), see the "Pick your cloud" collapsibles near the top of this page.
+Reads two flat string labels off `environments.<env>.metadata.labels` (`cloud.accountId`, `cloud.region`) and emits them under a structured `cloud` block, alongside `environment` and `product` identity. Both labels default to `"unknown"` if absent — the plugin never raises on a missing label, so a contract with no labels still produces a valid (if uninformative) config file.
 :::
 
 
 Two things to note about the design:
 
-- **`ContractHelper` is the only contract-shape dependency.** No raw dict-walking; the helper is version-tolerant across `fluidVersion 0.4` through `0.7.3` so your plugin doesn't break when the schema evolves.
+- **`ContractHelper` is the only contract-shape dependency.** No raw dict-walking against the contract root; the helper smooths over `fluidVersion` evolution so the plugin doesn't break when the schema moves. Per-env metadata (`env.get("metadata")`) is read directly as a plain dict — that shape (`environments.<env>.metadata.labels`) is stable across versions.
 - **The renderer is plain f-strings.** No template engine required — the SDK's role is enough for most scaffolds. For more complex output (loops, conditionals, partials), see the [your-own-CI journey](../journeys/your-own-ci.md) which uses the YAML+Jinja bundle pattern.
 
-## Tests — ~25 in total
+## Tests — 22 in total
 
-The conformance harness gives you 20 invariants for free (13 from `PluginTestHarness` + 7 from `CustomScaffoldTestHarness`). The 3 excerpts below show the plugin-specific scenarios; the upstream example adds ~5 more for full coverage:
+The `CustomScaffoldTestHarness` gives you 15 conformance invariants for free. The 5 plugin-specific assertions below are the full set in `tests/test_scaffold.py`:
 
 ```python
-# tests/test_scaffold.py (excerpts)
+# tests/test_scaffold.py
+
+MULTI_ENV_CONTRACT = {
+    "fluidVersion": "0.7.4",
+    "kind": "DataProduct",
+    "id": "my-data-product",
+    "name": "My Data Product",
+    "description": "A nightly aggregation of yesterday's events.",
+    "domain": "platform",
+    "metadata": {
+        "owner": {"team": "platform", "email": "platform@example.com"},
+    },
+    "environments": {
+        "dev":     {"metadata": {"labels": {"cloud.accountId": "111111111111", "cloud.region": "eu-west-1"}}},
+        "staging": {"metadata": {"labels": {"cloud.accountId": "222222222222", "cloud.region": "eu-west-1"}}},
+        "prod":    {"metadata": {"labels": {"cloud.accountId": "333333333333", "cloud.region": "eu-west-1"}}},
+    },
+    "exposes": [], "consumes": [], "builds": [],
+}
+
 
 class TestGitLabCIScaffold(CustomScaffoldTestHarness):
     plugin_class = GitLabCIScaffold
-    sample_contracts = [LOCAL_CONTRACT]
-
-    # === Scenarios specific to this plugin (added by you) ===
-
-    def test_emits_one_config_per_environment(self):
-        plugin = self._instantiate()
-        actions = plugin.plan(MULTI_ENV_CONTRACT)
-        config_paths = [a["params"]["path"] for a in actions
-                        if a["params"]["path"].startswith("config/")]
-        assert config_paths == ["config/dev.json", "config/staging.json", "config/prod.json"]
-
-    def test_no_environments_means_no_config_files(self):
-        plugin = self._instantiate()
-        actions = plugin.plan({"metadata": {"id": "x"}, "environments": {}})
-        assert all("config/" not in a["params"]["path"] for a in actions)
-
-    def test_ci_yaml_has_deploy_per_env(self):
-        plugin = self._instantiate()
-        actions = plugin.plan(MULTI_ENV_CONTRACT)
-        ci = next(a for a in actions if a["params"]["path"] == ".gitlab-ci.yml")
-        body = ci["params"]["content_b64"]  # base64-encoded bytes
-        import base64
-        decoded = base64.b64decode(body).decode()
-        assert "deploy:dev:" in decoded
-        assert "deploy:staging:" in decoded
-        assert "deploy:prod:" in decoded
+    sample_contracts = [MULTI_ENV_CONTRACT]
+
+    def _action_content(self, actions, path: str) -> str:
+        action = next(a for a in actions if a["params"]["path"] == path)
+        return base64.b64decode(action["params"]["content_b64"]).decode("utf-8")
+
+    def test_readme_includes_owner_and_envs(self):
+        readme = self._action_content(self.get_plugin().plan(MULTI_ENV_CONTRACT), "README.md")
+        assert "platform@example.com" in readme
+        assert "dev, prod, staging" in readme   # environment_names() returns sorted
+
+    def test_ci_has_one_deploy_per_env(self):
+        ci = self._action_content(self.get_plugin().plan(MULTI_ENV_CONTRACT), ".gitlab-ci.yml")
+        assert all(f"deploy:{e}:" in ci for e in ("dev", "staging", "prod"))
+
+    def test_prod_deploy_is_manual(self):
+        """Prod deploys must be gated `when: manual` so they don't auto-run."""
+        ci = self._action_content(self.get_plugin().plan(MULTI_ENV_CONTRACT), ".gitlab-ci.yml")
+        prod_idx = ci.index("deploy:prod:")
+        rest = ci[prod_idx + len("deploy:prod:"):]
+        next_deploy = rest.find("\ndeploy:")
+        end = prod_idx + len("deploy:prod:") + next_deploy if next_deploy != -1 else len(ci)
+        assert "when: manual" in ci[prod_idx:end]
+
+    def test_env_config_carries_account_id(self):
+        dev_config = json.loads(self._action_content(self.get_plugin().plan(MULTI_ENV_CONTRACT), "config/dev.json"))
+        assert dev_config["cloud"]["accountId"] == "111111111111"
+        assert dev_config["cloud"]["region"] == "eu-west-1"
+
+    def test_emits_correct_file_count(self):
+        # 1 README + 1 CI + 3 env configs = 5
+        assert len(self.get_plugin().plan(MULTI_ENV_CONTRACT)) == 5
 ```
 
+`test_prod_deploy_is_manual` is the one that's actually load-bearing: it pins the production-safety convention so a future refactor of `_render_ci` can't accidentally drop the gate.
+
 ## Run it
 
 ```bash
 # in the gitlab-ci-scaffold/ directory
 pip install -e ".[dev]"
 pytest
-# ============== 25 passed in 0.11s ===============
+# ============== 22 passed ===============
 ```
 
 End-to-end against a real contract:
 
 ```bash
-pip install data-product-forge data-product-forge-custom-scaffold
+pip install data-product-forge data-product-forge-custom-scaffold gitlab-ci-scaffold
 
 # In your project's contract.fluid.yaml:
 #   extensions:
 #     customScaffold:
 #       libraries:
 #         - id: ci
-#           source: { kind: entrypoint, name: gitlab-ci }
+#           source: { kind: pypi, package: gitlab-ci-scaffold, version: ">=0.1" }
 #       patterns:
-#         - use: ci:main
+#         - use: ci:gitlab-ci
 
 fluid generate custom-scaffold
 # ✓ 5 files written, 0 failed
@@ -391,8 +352,8 @@ fluid generate custom-scaffold
 
 ## You'll know it worked when
 
-- All ~25 tests pass under `pytest`.
-- The generated `.gitlab-ci.yml` has exactly one `deploy:<env>:` block per environment in your contract.
+- All 22 tests pass under `pytest`.
+- The generated `.gitlab-ci.yml` has exactly one `deploy:<env>:` block per environment in your contract, and the `deploy:prod:` block carries `when: manual`.
 - Adding a new `environments.staging-eu` entry to the contract and re-running `fluid generate custom-scaffold` produces a new `config/staging-eu.json` and a new `deploy:staging-eu:` block — without editing any plugin code.
 - `git diff` between two consecutive runs (no contract changes) is empty (determinism).
 
diff --git a/docs/sdk-and-plugins/journeys/your-own-ci.md b/docs/sdk-and-plugins/journeys/your-own-ci.md
index 94b93c1..ea95803 100644
--- a/docs/sdk-and-plugins/journeys/your-own-ci.md
+++ b/docs/sdk-and-plugins/journeys/your-own-ci.md
@@ -228,11 +228,11 @@ metadata:
 
 environments:
   dev:
-    cloud: { provider: aws, account: "111111111111", region: us-east-1 }
+    cloud: { provider: gcp, project: "order-events-dev",     region: us-central1 }
   staging:
-    cloud: { provider: aws, account: "222222222222", region: us-east-1 }
+    cloud: { provider: gcp, project: "order-events-staging", region: us-central1 }
   prod:
-    cloud: { provider: aws, account: "333333333333", region: us-west-2 }
+    cloud: { provider: gcp, project: "order-events-prod",    region: us-east1 }
 
 extensions:
   customScaffold:
diff --git a/docs/sdk-and-plugins/journeys/your-own-scaffolding.md b/docs/sdk-and-plugins/journeys/your-own-scaffolding.md
index eb9654b..4d698f6 100644
--- a/docs/sdk-and-plugins/journeys/your-own-scaffolding.md
+++ b/docs/sdk-and-plugins/journeys/your-own-scaffolding.md
@@ -53,7 +53,7 @@ metadata:
   productType: SDP
 environments:
   dev:
-    cloud: { provider: aws, account: "111111111111", region: us-east-1 }
+    cloud: { provider: gcp, project: "order-events-dev", region: us-central1 }
 extensions:
   customScaffold:
     libraries: