@catladder/cli 0.0.0-next-50ef07e9 → 0.0.0-next-b0a6c782

package/dist/bundles/catenv/index.js

@@ -5588,7 +5588,7 @@ Object.defineProperty(exports, "__esModule", ({
   value: true
 }));
 exports.DOCKER_REGISTRY = exports.PIPELINE_IMAGE_TAG = void 0;
-exports.PIPELINE_IMAGE_TAG = "next-50ef07e9" || 0;
+exports.PIPELINE_IMAGE_TAG = "next-b0a6c782" || 0;
 exports.DOCKER_REGISTRY = "git.panter.ch:5001/catladder/catladder" || 0;
 
 /***/ }),

package/dist/bundles/cli/index.js

@@ -11636,7 +11636,7 @@ Object.defineProperty(exports, "__esModule", ({
   value: true
 }));
 exports.DOCKER_REGISTRY = exports.PIPELINE_IMAGE_TAG = void 0;
-exports.PIPELINE_IMAGE_TAG = "next-50ef07e9" || 0;
+exports.PIPELINE_IMAGE_TAG = "next-b0a6c782" || 0;
 exports.DOCKER_REGISTRY = "git.panter.ch:5001/catladder/catladder" || 0;
 
 /***/ }),

package/dist/bundles/skills/catladder-builds/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: catladder-builds
+description: Configuring how a component is built in a catladder project — the `build` config in catladder.ts (build types node / rails / meteor / custom, build & start commands, artifacts, caching, lint/test/audit jobs, the Docker image, and shared workspace builds). Use when adding or changing a component's build, choosing a build type, wiring a Dockerfile/nginx image, tuning the build/test/lint jobs, or setting up a monorepo workspace build. Triggers on "build config", "buildCommand", "build type", "Dockerfile", "docker image", "rails build", "monorepo build", "artifacts".
+---
+
+# Component builds with catladder
+
+Each component in `catladder.ts` has a `build` config that catladder
+turns into the setup/lint/test/build CI jobs and the deployable Docker
+image. Change the build in `catladder.ts` and regenerate
+(`yarn catenv`) — never hand-edit generated pipeline files (see the
+`catladder-config` skill).
+
+```ts
+components: {
+  www: {
+    dir: "frontend",
+    build: {
+      type: "node",           // node | rails | meteor | custom (+ deprecated node-static/storybook)
+      buildCommand: "yarn build",
+      startCommand: "yarn start",
+    },
+    deploy: { /* see catladder-deploys */ },
+  },
+}
+```
+
+Set `build: false` to disable building for a component (e.g. a
+deploy-only or docker-tag component).
+
+## Build types
+
+| Type | Use for | Notes |
+|---|---|---|
+| `node` | Node/JS apps (Next.js, Vite, plain node) | default `yarn build` + `yarn start`; `docker` selects the runtime image |
+| `rails` | Ruby on Rails apps | Cloud Native Buildpacks when there is no `Dockerfile`; Postgres test DB |
+| `meteor` | Meteor apps | starts `node main.js` |
+| `custom` | anything else | you provide the `jobImage` and `docker` config (both required) |
+| `node-static`, `storybook` | *deprecated* | use `type: "node"` + `docker: { type: "nginx" }` |
+
+A component can also **reuse a shared workspace build** instead of a
+type: `build: { from: "web" }` (see workspace builds below).
+
+## Common options (all standalone build types)
+
+- `buildCommand` — the build step (`string | string[] | null | false`;
+  `false`/`null` skips building).
+- `startCommand` — how the app is started at runtime.
+- `postInstall` — commands run after `yarn install` (node family; needed
+  e.g. for Yarn PnP where `package.json` postinstall won't run).
+- `lint` / `test` / `audit` — customize (`{ command, jobImage, … }`) or
+  set to `false` to disable that job.
+- `artifactsPaths` / `artifactsExcludePaths` — extra build artifacts
+  (`dist` and `.next` are always included).
+- `cache` — build caching (see the `catladder-pipelines` skill for the
+  caching model).
+- `jobImage`, `jobTags`, `jobVars`, `runnerVariables` — the CI image,
+  runner tags, build-only env vars, and extra runner variables.
+- `docker` — the image build strategy: a built-in
+  (`{ type: "nginx" | "node" | "meteor" }`) or
+  `{ type: "custom" }` (expects a `Dockerfile`).
+
+## Workspace builds (monorepos)
+
+For a shared build across several components, declare it once at the top
+level under `builds` and reference it from each component:
+
+```ts
+builds: {
+  web: { type: "node", dir: "packages/web", buildCommand: "yarn build" },
+},
+components: {
+  www: { dir: "packages/web", build: { from: "web" }, deploy: { /* … */ } },
+}
+```
+
+Only `type: "node"` workspace builds exist today.
+
+## Full option reference
+
+See [references/build-types.md](references/build-types.md) for every
+build type's options, the `docker` sub-config, and the exact defaults.
+
+## Related skills
+
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-deploys` — the matching `deploy` config
+- `catladder-pipelines` — how build jobs, caching and job images work
+- `catladder-secrets` — env vars available at build time

package/dist/bundles/skills/catladder-builds/references/build-types.md

@@ -0,0 +1,72 @@
+# catladder build config reference
+
+Full options for `components.<name>.build` (and top-level `builds`).
+Fix build problems in `catladder.ts` and regenerate — never edit the
+generated pipeline files.
+
+## Shared base options (all standalone build types)
+
+| Option | Type | Purpose / default |
+|---|---|---|
+| `buildCommand` | `string \| string[] \| null \| false` | build step; `false`/`null` skips it |
+| `startCommand` | `string` | runtime start command |
+| `postInstall` | `string \| string[]` | runs after `yarn install` (node family) |
+| `lint` / `test` / `audit` | `false \| TestJobCustom` | customize or disable the job |
+| `artifactsPaths` | `string[]` | extra artifacts (`dist`, `.next` always included) |
+| `artifactsExcludePaths` | `string[]` | artifact excludes |
+| `artifactsReports` | `{ junit?: string[] }` | CI test report paths |
+| `cache` | `CacheConfig \| CacheConfig[]` | build caching (`jobCache` is deprecated) |
+| `jobVars` | `EnvVars` | env vars only in build jobs |
+| `runnerVariables` | `Record<string,string>` | extra runner vars (also for `services:`) |
+| `jobTags` | `string[]` | runner tags |
+| `jobImage` | `GitlabJobImage` | custom CI image for the build |
+| `docker` | see below | the deployable image strategy |
+
+`TestJobCustom` (for `lint`/`test`/`audit`): `command`, `jobImage`,
+`artifactsReports`, `artifacts`, `runnerVariables`, `allowFailure`
+(`allowFailure` defaults to `true` for `audit`).
+
+## Per-type options & defaults
+
+### `node`
+- `docker?` — built-in node image `{ type: "node", yarnRebuildEnabled?: boolean (default true), additionsBegin?: string[], additionsEnd?: string[] }`, or a custom docker config.
+- Defaults: `buildCommand: "yarn build"`, `startCommand: "yarn start"`, artifacts `["dist", ".next"]`, excludes `[".next/cache/**/*"]`.
+
+### `rails`
+- `test?.databaseImage?` — test DB container image (Postgres only; default `docker.io/postgres:latest`).
+- `cnbBuilder?` — Cloud Native Buildpacks config, used only when there is **no `Dockerfile`**:
+  - `image?` — builder image. **Actual runtime default `heroku/builder:24`** (the type's JSDoc saying `heroku/buildpacks:20` is stale).
+  - `packVersion?` — pack CLI version. **Actual runtime default `0.36.4`** (JSDoc `0.28.0` is stale).
+  - `packExtraArgs?: string[]` — extra args passed to `pack`.
+  - `buildVars?: Record<string, string | undefined>` — Bundler / Rails asset-precompile vars (`undefined` inherits from the component's env vars).
+
+### `meteor`
+- `installScripts?: boolean` — run `yarn install` inside the source folder in the image (only needed with custom image scripts).
+- `docker?` — meteor built-in or custom. Default `startCommand: "node main.js"`.
+
+### `custom`
+- `type: "custom"` — **required**.
+- `jobImage: GitlabJobImage` — **required** CI image.
+- `docker: BuildConfigDocker` — **required** image build config.
+- `jobServices?: Services` — services for lint/test/audit/build jobs.
+- `lint?` / `test?` / `audit?: TestJobCustom` — disabled unless set.
+
+### `node-static` / `storybook` — deprecated
+Use `type: "node"` with `docker: { type: "nginx" }` (and
+`startCommand: ""` for a purely static app). `storybook` previously
+defaulted `buildCommand: "yarn build-storybook --quiet -o ./dist"`.
+
+## `docker` sub-config
+
+`BuildConfigDocker` is either:
+
+- **built-in**: `{ type: "nginx" | "node" | "meteor", additionsBegin?: string[], additionsEnd?: string[] }` — `additionsBegin`/`additionsEnd` inject Dockerfile lines before/after the standard steps.
+- **custom**: `{ type: "custom", buildContextLocation?: "root" | "component" (default "root"), dockerfileContent?: string[] }` — expects a `Dockerfile`. `dockerfileContent` is experimental and supports the `$DOCKER_COPY_WORKSPACE_FILES` / `$DOCKER_COPY_AND_INSTALL_APP` placeholders.
+
+## Workspace builds (`builds`)
+
+Top-level `builds: Record<string, WorkspaceBuildConfig>`. Only
+`type: "node"` is supported.
+
+- Node workspace build: `dir?`, `buildCommand?` (default `yarn build`), `dockerDefaults?: { yarnRebuildEnabled }`, plus shared `lint?` (default `{ command: "yarn lint" }`), `test?` (default `{ command: "yarn test" }`), `audit?`, `runnerVariables?`, `artifactsReports?`, `jobImage?`, `jobTags?`, `cache?`.
+- A component references it via `build: { from: "<name>", docker?, startCommand?, artifactsPaths?, artifactsExcludePaths?, cache? }` — the per-component overrides layer on top of the shared build.

package/dist/bundles/skills/catladder-cli/SKILL.md

@@ -49,5 +49,8 @@ it matches the installed version).
 ## Related skills
 
 - `catladder-config` — catladder.ts structure and regeneration
+- `catladder-builds` — the component `build` config
+- `catladder-deploys` — the component `deploy` config
 - `catladder-secrets` — env vars and secret management
+- `catladder-releases` — releasing (semantic-release / changesets)
 - `catladder-pipelines` — pipeline behavior and CI debugging

package/dist/bundles/skills/catladder-config/SKILL.md

@@ -37,8 +37,8 @@ const config = {
     www: {
       dir: "frontend",          // working directory of this component
       vars: { public: {}, secret: [] },  // env vars (see catladder-secrets skill)
-      build: { type: "node" },  // build types: node | rails | base
-      deploy: { type: "kubernetes" }, // kubernetes | google-cloudrun | dockerTag | custom
+      build: { type: "node" },  // node | rails | meteor | custom — see catladder-builds
+      deploy: { type: "kubernetes" }, // kubernetes | google-cloudrun | dockerTag | custom — see catladder-deploys
       env: {                    // enable/customize per environment
         review: {},
         dev: {},
@@ -77,6 +77,9 @@ Key concepts:
 
 ## Related skills
 
+- `catladder-builds` — the component `build` config (build types, Docker)
+- `catladder-deploys` — the component `deploy` config (k8s, Cloud Run, …)
 - `catladder-secrets` — env vars and secret management
+- `catladder-releases` — releasing (semantic-release / changesets)
 - `catladder-pipelines` — how the generated pipelines work, debugging CI
 - `catladder-cli` — non-interactive CLI usage and command reference

package/dist/bundles/skills/catladder-deploys/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: catladder-deploys
+description: Configuring how a component is deployed in a catladder project — the `deploy` config in catladder.ts (deploy types kubernetes / google-cloudrun / dockerTag / custom, manual vs auto deploy, resources, autoscaling, health checks, CloudSQL/MongoDB, Cloud Run services/jobs/worker pools, cron jobs). Use when adding or changing a component's deploy, choosing a deploy target, setting resources/replicas/autoscaling, wiring a database, adding cron/scheduled jobs, or making a deploy manual. Triggers on "deploy config", "deploy type", "kubernetes", "cloud run", "cloudrun", "autoscale", "resources", "replicas", "cloudsql", "mongodb", "cronjob", "manual deploy".
+---
+
+# Component deploys with catladder
+
+Each component in `catladder.ts` has a `deploy` config that catladder
+turns into the deploy (and stop) CI jobs and the cloud resources. Change
+the deploy in `catladder.ts` and regenerate (`yarn catenv`) — never
+hand-edit generated files (see the `catladder-config` skill). Cloud
+resources themselves are provisioned separately with
+`yarn catladder project setup` (see the `catladder-cli` skill).
+
+```ts
+components: {
+  api: {
+    dir: "backend",
+    build: { /* see catladder-builds */ },
+    deploy: {
+      type: "kubernetes",         // kubernetes | google-cloudrun | dockerTag | custom
+      cluster: { type: "gcloud", name: "…", projectId: "…", region: "…" },
+      values: { application: { replicas: 2 } },
+    },
+  },
+}
+```
+
+## Deploy types
+
+| Type | Deploys to | Requires |
+|---|---|---|
+| `kubernetes` | a GKE cluster via Helm | `cluster` |
+| `google-cloudrun` | Google Cloud Run | `projectId`, `region` |
+| `dockerTag` | tags an image (no runtime) | `tag` — rarely used, not generally recommended |
+| `custom` | your own script | `requiresDocker`, `script` |
+
+## Manual vs automatic deploys
+
+`when: "manual" | "auto"` controls whether the deploy job runs
+automatically. **Default: `prod` is `manual`, every other environment
+is `auto`.** Set per component or per environment (`env.<name>.deploy`).
+
+`waitFor: ["otherComponent"]` (experimental) makes a deploy wait for
+another component to deploy first.
+
+## Kubernetes essentials
+
+`cluster` is required: `{ type: "gcloud", name, projectId, region, domainCanonical? }`.
+Everything app-level lives under `values`:
+
+- `application` — `replicas`, `autoscale` (`minReplicas`/`maxReplicas`/`metrics`),
+  `resources` (cpu/memory limits & requests), `healthRoute`,
+  `startupProbe`/`readinessProbe`/`livenessProbe`, `command`,
+  `redirects`, `worker` (a separate background deployment). Set
+  `application: false` for a component with no long-running deployment.
+- `cloudsql` — attach an (unmanaged) CloudSQL Postgres instance.
+- `mongodb` — a Bitnami MongoDB (`standalone` or `replicaset`).
+- `jobs` — Helm post-install/upgrade jobs; `cronjobs` — scheduled jobs.
+
+## Cloud Run essentials
+
+`projectId` and `region` are required. Then:
+
+- `service` — the main service (`minInstances`, `maxInstances`, `cpu`,
+  `memory`, `timeout`, `allowUnauthenticated`, `ingress`, `healthCheck`,
+  …). `service: false` disables it (job-only deployments).
+- `additionalServices`, `jobs`, `workerPools` — extra services, run-to-
+  completion jobs, and always-on background worker pools.
+- `cloudSql` — attach an (unmanaged) CloudSQL instance; choose the
+  connection-string format (`prisma` default, `rails`, `jdbc`).
+- `execute` — run a script/job/HTTP call at a deploy lifecycle point
+  (`preDeploy`/`postDeploy`/`preStop`/`postStop`) or on a `schedule`.
+  Prefer this over the deprecated `when`/`schedule` fields on `jobs`.
+
+## Full option reference
+
+See [references/deploy-types.md](references/deploy-types.md) for every
+deploy type's options, required fields, and defaults.
+
+## Related skills
+
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-builds` — the matching `build` config
+- `catladder-pipelines` — how deploy jobs, environments and review apps work
+- `catladder-cli` — `project setup` (provision cloud resources) and `project doctor`
+- `catladder-secrets` — env vars available at runtime

package/dist/bundles/skills/catladder-deploys/references/deploy-types.md

@@ -0,0 +1,62 @@
+# catladder deploy config reference
+
+Full options for `components.<name>.deploy` (and per-env
+`env.<name>.deploy`). Fix deploy problems in `catladder.ts` and
+regenerate — never edit generated files. Provision the underlying cloud
+resources with `yarn catladder project setup`; detect drift with
+`yarn catladder project doctor`.
+
+## Shared base (all deploy types)
+
+| Option | Type | Purpose / default |
+|---|---|---|
+| `when` | `"manual" \| "auto"` | prod → `manual`, other envs → `auto` |
+| `waitFor` | `string[]` | EXPERIMENTAL; wait for other components first |
+| `jobTags` | `string[]` | runner tags |
+| `jobVars` | `EnvVars` | env vars only in the deploy job |
+| `runnerVariables` | `Record<string,string>` | extra runner vars |
+
+(Cloud Run defines its own `execute`; otherwise the base applies to all.)
+
+## `kubernetes`
+
+- `cluster` — **required**: `{ type: "gcloud", name, projectId, region, domainCanonical? }`.
+- `debug?: boolean` — pass `--debug` to Helm.
+- `additionalHelmArgs?: string[]`.
+- `chartName?: string` — custom chart location (not recommended).
+- `values?` — app configuration (unknown props allowed, forwarded to the chart):
+  - `application?: false | { command?, enabled? (default true), redirects?, hostAliases?, replicas?, autoscale?: { minReplicas, maxReplicas, metrics[] }, updateStrategy?, resources?: { limits/requests: { cpu, memory } }, healthRoute?, startupProbe? / readinessProbe? / livenessProbe? (httpGet shape), worker?, jobDefaults? }`.
+  - `cloudsql?: { type: "unmanaged", enabled, instanceConnectionName, dbUser?, dbNamePrefix?, dbBaseName? }`.
+  - `mongodb?: { enabled?, dbName?, persistence?, resources?, tolerations? } & ({ architecture: "standalone" } | { architecture: "replicaset", replicaCount? (default 2) })`.
+  - `mailhog?: { enabled }` — dev mail catcher (injects `MAIL_URL`).
+  - `jobs?: Record<string, false | { command, hook? }>` — Helm hook jobs (default hook `post-install,post-upgrade`).
+  - `cronjobs?: Record<string, false | { schedule, command, concurrencyPolicy?, timeZone? }>`.
+  - `secretsFromOtherComponent?: { [envVar]: string }` — load secrets from another component in the same cluster.
+  - `mapServiceUrlToEnv?: { [envVar]: string }` — map another service's internal endpoint to an env var.
+
+## `google-cloudrun`
+
+- `projectId` — **required**.
+- `region` — **required** (`Gcloudregion` enum, e.g. `europe-west6`).
+- `service?: boolean | DeployConfigCloudRunService` (default enabled):
+  - `command?`, `args?`, `image?`, `minInstances?` (0), `maxInstances?` (100), `cpu?` (1|2|4|6|8), `memory?` (512MB), `timeout?` (5min), `noCpuThrottling?`, `allowUnauthenticated?` (true), `ingress?` (`all` | `internal` | `internal-and-cloud-load-balancing`, default `all`), `executionEnvironment?` (`gen1`|`gen2`), `http2?`, `gpu?`/`gpuType?`, `sessionAffinity?`, `healthCheck?` (`true` or `{ startupProbe, livenessProbe }`), plus cloud-storage volumes and VPC network config.
+- `additionalServices?: Record<string, service | false | null>`.
+- `jobs?: Record<string, DeployConfigCloudRunJob | false | null>` — `{ command, args?, image?, cpu?, memory? (512Mi), timeout? (10min), parallelism? (1), maxRetries? (0) }`. The per-job `when`/`schedule`/`waitForCompletion` fields are **deprecated** — use `execute`.
+- `workerPools?: Record<string, DeployConfigCloudRunWorkerPool | false | null>` — always-on background work, no endpoint, no autoscaling: `{ command, instances? (1), cpu?, memory?, image?, args?, gpu?/gpuType? }`.
+- `cloudSql?: DeployConfigCloudRunCloudSql | false` — `{ type: "unmanaged", instanceConnectionName, dbUser?, dbNamePrefix?, dbBaseName?, deleteDatabaseOnStop?, dbConnectionStringFormat? ("prisma" default | "rails" | "jdbc"), dbConnectionStringVariablesMode? ("environment" default | "embedded"), dbAdditionalQueryParams? }`.
+- `execute?: Record<string, DeployConfigCloudRunExecute | null>` — run a script / job / HTTP call at a lifecycle point (`when`: `preDeploy` | `postDeploy` | `preStop` | `postStop`) or on a `schedule`.
+- `debug?: boolean`.
+
+## `dockerTag`
+
+- `type: "dockerTag"`, `tag: string` — **required**. Adds a custom tag on the image repo to deploy it. Only used in one project historically; not generally recommended (runtime env vars must be coordinated manually).
+
+## `custom`
+
+- `type: "custom"` — **required**.
+- `requiresDocker: boolean` — **required**; whether the deploy needs a built Docker image.
+- `script: string[]` — **required**; the deploy script.
+- `requiresYarnInstall?: boolean` — whether the script needs `yarn install`.
+- `stopScript?: string[]` — script to stop/tear down the environment.
+- `jobImage?: GitlabJobImage`.
+- Also accepts `cache` (via `WithCacheConfig`).

package/dist/bundles/skills/catladder-pipelines/SKILL.md

@@ -49,7 +49,8 @@ not in the YAML.
 
 With `releases` configured, tagged releases are created by a release
 job (method: `semantic-release` or `changesets`). The release job also
-runs a dependency security audit via catci.
+runs a dependency security audit that gates the release. See the
+`catladder-releases` skill for the full flow.
 
 ## Debugging CI
 
@@ -68,5 +69,8 @@ Useful CLI commands (see the `catladder-cli` skill for invocation):
 ## Related skills
 
 - `catladder-config` — catladder.ts structure and regeneration
+- `catladder-builds` — build jobs and Docker images
+- `catladder-deploys` — deploy jobs, environments and review apps
+- `catladder-releases` — the `taggedRelease` flow and security-audit gate
 - `catladder-secrets` — env vars and secret management
 - `catladder-cli` — non-interactive CLI usage and command reference

package/dist/bundles/skills/catladder-releases/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: catladder-releases
+description: How releases work in a catladder project — the `releases` config in catladder.ts (manual vs automatic releasing, and the release method: semantic-release from conventional commits, or changesets from `.changeset/*.md` files), the version/tag/changelog flow, and the security-audit gate that every release must pass. Use when enabling or changing releases, deciding between semantic-release and changesets, writing changesets, cutting or debugging a release, or when a release job fails on the security audit. Triggers on "release", "releases config", "semantic-release", "changesets", "changeset", "version bump", "tag a release", "security audit", "release failed".
+---
+
+# Releases with catladder
+
+A release is what produces a `vX.Y.Z` git tag (with a changelog), which
+in turn triggers the `taggedRelease` pipeline that deploys to `stage`
+and `prod` (see the `catladder-pipelines` skill). Enable it in
+`catladder.ts`:
+
+```ts
+releases: {
+  when: "auto",              // "manual" (default) | "auto"
+  method: "semantic-release", // "semantic-release" (default) | "changesets"
+}
+```
+
+Change `catladder.ts` and regenerate (`yarn catenv`) — the release jobs
+are generated, never hand-edited.
+
+## `when` — who triggers the release
+
+- **`manual`** (default) — the `create release` job on the main branch
+  is manual; someone runs it to cut a release.
+- **`auto`** — the release job runs automatically on every main-branch
+  pipeline (it still no-ops when there is nothing to release).
+
+There is always also a manual **`⚠️ force create release`** job as an
+escape hatch.
+
+## `method` — how the version is decided
+
+### `semantic-release` (default)
+The version is derived automatically from **conventional commit
+messages** since the last release (`fix:` → patch, `feat:` → minor,
+`BREAKING CHANGE` → major). Nothing to declare by hand — just write
+conventional commits.
+
+### `changesets`
+Developers declare changes intentionally as **`.changeset/*.md` files**
+(the official changesets format: a bump type + a human-written summary).
+The release job consumes all pending changesets, takes the highest bump,
+computes the next version from the last `v*` git tag, writes the
+changelog, commits `chore(release): <version>`, and pushes the tag. An
+empty `.changeset/` folder means there is nothing to release.
+
+Add a changeset by creating `.changeset/<name>.md`:
+
+```md
+---
+"my-app": minor
+---
+
+Add the new export endpoint.
+```
+
+## The security-audit gate
+
+**Both methods gate on a dependency security audit before releasing.**
+The release entrypoint runs the audit first; only if it passes does it
+create the version, changelog and tag. On GitLab, if the audit document
+is missing or invalid the job opens a merge request with a security-audit
+template and **fails** — resolve that MR, then re-run the release. See
+the `security` commands in the `catladder-cli` reference.
+
+## Debugging a failed release
+
+- Fails immediately on the audit → handle the security-audit gate above.
+- `changesets` released nothing → no `.changeset/*.md` files were
+  pending.
+- Wrong version bump → check commit types (semantic-release) or the bump
+  levels in the changeset files (changesets).
+- Inspect the job with `yarn catladder project ci job-log` (see the
+  `catladder-cli` skill).
+
+## Related skills
+
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-pipelines` — the `taggedRelease` trigger and stage/prod deploys
+- `catladder-cli` — `project ci` and `security` commands

package/dist/bundles/skills/catladder-secrets/SKILL.md

@@ -70,5 +70,7 @@ suspecting anything else.
 ## Related skills
 
 - `catladder-config` — general catladder.ts structure and regeneration
+- `catladder-builds` — build-time vars (`jobVars`) and build config
+- `catladder-deploys` — runtime deploy config
 - `catladder-pipelines` — how the generated pipelines work
 - `catladder-cli` — non-interactive CLI usage and command reference

package/dist/pipeline/src/constants.js

@@ -4,5 +4,5 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.DOCKER_REGISTRY = exports.PIPELINE_IMAGE_TAG = void 0;
-exports.PIPELINE_IMAGE_TAG = "next-50ef07e9" || "latest";
+exports.PIPELINE_IMAGE_TAG = "next-b0a6c782" || "latest";
 exports.DOCKER_REGISTRY = "git.panter.ch:5001/catladder/catladder" || "git.panter.ch:5001/catladder/catladder";

package/dist/skills/catladder-builds/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: catladder-builds
+description: Configuring how a component is built in a catladder project — the `build` config in catladder.ts (build types node / rails / meteor / custom, build & start commands, artifacts, caching, lint/test/audit jobs, the Docker image, and shared workspace builds). Use when adding or changing a component's build, choosing a build type, wiring a Dockerfile/nginx image, tuning the build/test/lint jobs, or setting up a monorepo workspace build. Triggers on "build config", "buildCommand", "build type", "Dockerfile", "docker image", "rails build", "monorepo build", "artifacts".
+---
+
+# Component builds with catladder
+
+Each component in `catladder.ts` has a `build` config that catladder
+turns into the setup/lint/test/build CI jobs and the deployable Docker
+image. Change the build in `catladder.ts` and regenerate
+(`yarn catenv`) — never hand-edit generated pipeline files (see the
+`catladder-config` skill).
+
+```ts
+components: {
+  www: {
+    dir: "frontend",
+    build: {
+      type: "node",           // node | rails | meteor | custom (+ deprecated node-static/storybook)
+      buildCommand: "yarn build",
+      startCommand: "yarn start",
+    },
+    deploy: { /* see catladder-deploys */ },
+  },
+}
+```
+
+Set `build: false` to disable building for a component (e.g. a
+deploy-only or docker-tag component).
+
+## Build types
+
+| Type | Use for | Notes |
+|---|---|---|
+| `node` | Node/JS apps (Next.js, Vite, plain node) | default `yarn build` + `yarn start`; `docker` selects the runtime image |
+| `rails` | Ruby on Rails apps | Cloud Native Buildpacks when there is no `Dockerfile`; Postgres test DB |
+| `meteor` | Meteor apps | starts `node main.js` |
+| `custom` | anything else | you provide the `jobImage` and `docker` config (both required) |
+| `node-static`, `storybook` | *deprecated* | use `type: "node"` + `docker: { type: "nginx" }` |
+
+A component can also **reuse a shared workspace build** instead of a
+type: `build: { from: "web" }` (see workspace builds below).
+
+## Common options (all standalone build types)
+
+- `buildCommand` — the build step (`string | string[] | null | false`;
+  `false`/`null` skips building).
+- `startCommand` — how the app is started at runtime.
+- `postInstall` — commands run after `yarn install` (node family; needed
+  e.g. for Yarn PnP where `package.json` postinstall won't run).
+- `lint` / `test` / `audit` — customize (`{ command, jobImage, … }`) or
+  set to `false` to disable that job.
+- `artifactsPaths` / `artifactsExcludePaths` — extra build artifacts
+  (`dist` and `.next` are always included).
+- `cache` — build caching (see the `catladder-pipelines` skill for the
+  caching model).
+- `jobImage`, `jobTags`, `jobVars`, `runnerVariables` — the CI image,
+  runner tags, build-only env vars, and extra runner variables.
+- `docker` — the image build strategy: a built-in
+  (`{ type: "nginx" | "node" | "meteor" }`) or
+  `{ type: "custom" }` (expects a `Dockerfile`).
+
+## Workspace builds (monorepos)
+
+For a shared build across several components, declare it once at the top
+level under `builds` and reference it from each component:
+
+```ts
+builds: {
+  web: { type: "node", dir: "packages/web", buildCommand: "yarn build" },
+},
+components: {
+  www: { dir: "packages/web", build: { from: "web" }, deploy: { /* … */ } },
+}
+```
+
+Only `type: "node"` workspace builds exist today.
+
+## Full option reference
+
+See [references/build-types.md](references/build-types.md) for every
+build type's options, the `docker` sub-config, and the exact defaults.
+
+## Related skills
+
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-deploys` — the matching `deploy` config
+- `catladder-pipelines` — how build jobs, caching and job images work
+- `catladder-secrets` — env vars available at build time

package/dist/skills/catladder-builds/references/build-types.md

@@ -0,0 +1,72 @@
+# catladder build config reference
+
+Full options for `components.<name>.build` (and top-level `builds`).
+Fix build problems in `catladder.ts` and regenerate — never edit the
+generated pipeline files.
+
+## Shared base options (all standalone build types)
+
+| Option | Type | Purpose / default |
+|---|---|---|
+| `buildCommand` | `string \| string[] \| null \| false` | build step; `false`/`null` skips it |
+| `startCommand` | `string` | runtime start command |
+| `postInstall` | `string \| string[]` | runs after `yarn install` (node family) |
+| `lint` / `test` / `audit` | `false \| TestJobCustom` | customize or disable the job |
+| `artifactsPaths` | `string[]` | extra artifacts (`dist`, `.next` always included) |
+| `artifactsExcludePaths` | `string[]` | artifact excludes |
+| `artifactsReports` | `{ junit?: string[] }` | CI test report paths |
+| `cache` | `CacheConfig \| CacheConfig[]` | build caching (`jobCache` is deprecated) |
+| `jobVars` | `EnvVars` | env vars only in build jobs |
+| `runnerVariables` | `Record<string,string>` | extra runner vars (also for `services:`) |
+| `jobTags` | `string[]` | runner tags |
+| `jobImage` | `GitlabJobImage` | custom CI image for the build |
+| `docker` | see below | the deployable image strategy |
+
+`TestJobCustom` (for `lint`/`test`/`audit`): `command`, `jobImage`,
+`artifactsReports`, `artifacts`, `runnerVariables`, `allowFailure`
+(`allowFailure` defaults to `true` for `audit`).
+
+## Per-type options & defaults
+
+### `node`
+- `docker?` — built-in node image `{ type: "node", yarnRebuildEnabled?: boolean (default true), additionsBegin?: string[], additionsEnd?: string[] }`, or a custom docker config.
+- Defaults: `buildCommand: "yarn build"`, `startCommand: "yarn start"`, artifacts `["dist", ".next"]`, excludes `[".next/cache/**/*"]`.
+
+### `rails`
+- `test?.databaseImage?` — test DB container image (Postgres only; default `docker.io/postgres:latest`).
+- `cnbBuilder?` — Cloud Native Buildpacks config, used only when there is **no `Dockerfile`**:
+  - `image?` — builder image. **Actual runtime default `heroku/builder:24`** (the type's JSDoc saying `heroku/buildpacks:20` is stale).
+  - `packVersion?` — pack CLI version. **Actual runtime default `0.36.4`** (JSDoc `0.28.0` is stale).
+  - `packExtraArgs?: string[]` — extra args passed to `pack`.
+  - `buildVars?: Record<string, string | undefined>` — Bundler / Rails asset-precompile vars (`undefined` inherits from the component's env vars).
+
+### `meteor`
+- `installScripts?: boolean` — run `yarn install` inside the source folder in the image (only needed with custom image scripts).
+- `docker?` — meteor built-in or custom. Default `startCommand: "node main.js"`.
+
+### `custom`
+- `type: "custom"` — **required**.
+- `jobImage: GitlabJobImage` — **required** CI image.
+- `docker: BuildConfigDocker` — **required** image build config.
+- `jobServices?: Services` — services for lint/test/audit/build jobs.
+- `lint?` / `test?` / `audit?: TestJobCustom` — disabled unless set.
+
+### `node-static` / `storybook` — deprecated
+Use `type: "node"` with `docker: { type: "nginx" }` (and
+`startCommand: ""` for a purely static app). `storybook` previously
+defaulted `buildCommand: "yarn build-storybook --quiet -o ./dist"`.
+
+## `docker` sub-config
+
+`BuildConfigDocker` is either:
+
+- **built-in**: `{ type: "nginx" | "node" | "meteor", additionsBegin?: string[], additionsEnd?: string[] }` — `additionsBegin`/`additionsEnd` inject Dockerfile lines before/after the standard steps.
+- **custom**: `{ type: "custom", buildContextLocation?: "root" | "component" (default "root"), dockerfileContent?: string[] }` — expects a `Dockerfile`. `dockerfileContent` is experimental and supports the `$DOCKER_COPY_WORKSPACE_FILES` / `$DOCKER_COPY_AND_INSTALL_APP` placeholders.
+
+## Workspace builds (`builds`)
+
+Top-level `builds: Record<string, WorkspaceBuildConfig>`. Only
+`type: "node"` is supported.
+
+- Node workspace build: `dir?`, `buildCommand?` (default `yarn build`), `dockerDefaults?: { yarnRebuildEnabled }`, plus shared `lint?` (default `{ command: "yarn lint" }`), `test?` (default `{ command: "yarn test" }`), `audit?`, `runnerVariables?`, `artifactsReports?`, `jobImage?`, `jobTags?`, `cache?`.
+- A component references it via `build: { from: "<name>", docker?, startCommand?, artifactsPaths?, artifactsExcludePaths?, cache? }` — the per-component overrides layer on top of the shared build.

package/dist/skills/catladder-cli/SKILL.md

@@ -49,5 +49,8 @@ it matches the installed version).
 ## Related skills
 
 - `catladder-config` — catladder.ts structure and regeneration
+- `catladder-builds` — the component `build` config
+- `catladder-deploys` — the component `deploy` config
 - `catladder-secrets` — env vars and secret management
+- `catladder-releases` — releasing (semantic-release / changesets)
 - `catladder-pipelines` — pipeline behavior and CI debugging

package/dist/skills/catladder-config/SKILL.md

@@ -37,8 +37,8 @@ const config = {
     www: {
       dir: "frontend",          // working directory of this component
       vars: { public: {}, secret: [] },  // env vars (see catladder-secrets skill)
-      build: { type: "node" },  // build types: node | rails | base
-      deploy: { type: "kubernetes" }, // kubernetes | google-cloudrun | dockerTag | custom
+      build: { type: "node" },  // node | rails | meteor | custom — see catladder-builds
+      deploy: { type: "kubernetes" }, // kubernetes | google-cloudrun | dockerTag | custom — see catladder-deploys
       env: {                    // enable/customize per environment
         review: {},
         dev: {},
@@ -77,6 +77,9 @@ Key concepts:
 
 ## Related skills
 
+- `catladder-builds` — the component `build` config (build types, Docker)
+- `catladder-deploys` — the component `deploy` config (k8s, Cloud Run, …)
 - `catladder-secrets` — env vars and secret management
+- `catladder-releases` — releasing (semantic-release / changesets)
 - `catladder-pipelines` — how the generated pipelines work, debugging CI
 - `catladder-cli` — non-interactive CLI usage and command reference

package/dist/skills/catladder-deploys/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: catladder-deploys
+description: Configuring how a component is deployed in a catladder project — the `deploy` config in catladder.ts (deploy types kubernetes / google-cloudrun / dockerTag / custom, manual vs auto deploy, resources, autoscaling, health checks, CloudSQL/MongoDB, Cloud Run services/jobs/worker pools, cron jobs). Use when adding or changing a component's deploy, choosing a deploy target, setting resources/replicas/autoscaling, wiring a database, adding cron/scheduled jobs, or making a deploy manual. Triggers on "deploy config", "deploy type", "kubernetes", "cloud run", "cloudrun", "autoscale", "resources", "replicas", "cloudsql", "mongodb", "cronjob", "manual deploy".
+---
+
+# Component deploys with catladder
+
+Each component in `catladder.ts` has a `deploy` config that catladder
+turns into the deploy (and stop) CI jobs and the cloud resources. Change
+the deploy in `catladder.ts` and regenerate (`yarn catenv`) — never
+hand-edit generated files (see the `catladder-config` skill). Cloud
+resources themselves are provisioned separately with
+`yarn catladder project setup` (see the `catladder-cli` skill).
+
+```ts
+components: {
+  api: {
+    dir: "backend",
+    build: { /* see catladder-builds */ },
+    deploy: {
+      type: "kubernetes",         // kubernetes | google-cloudrun | dockerTag | custom
+      cluster: { type: "gcloud", name: "…", projectId: "…", region: "…" },
+      values: { application: { replicas: 2 } },
+    },
+  },
+}
+```
+
+## Deploy types
+
+| Type | Deploys to | Requires |
+|---|---|---|
+| `kubernetes` | a GKE cluster via Helm | `cluster` |
+| `google-cloudrun` | Google Cloud Run | `projectId`, `region` |
+| `dockerTag` | tags an image (no runtime) | `tag` — rarely used, not generally recommended |
+| `custom` | your own script | `requiresDocker`, `script` |
+
+## Manual vs automatic deploys
+
+`when: "manual" | "auto"` controls whether the deploy job runs
+automatically. **Default: `prod` is `manual`, every other environment
+is `auto`.** Set per component or per environment (`env.<name>.deploy`).
+
+`waitFor: ["otherComponent"]` (experimental) makes a deploy wait for
+another component to deploy first.
+
+## Kubernetes essentials
+
+`cluster` is required: `{ type: "gcloud", name, projectId, region, domainCanonical? }`.
+Everything app-level lives under `values`:
+
+- `application` — `replicas`, `autoscale` (`minReplicas`/`maxReplicas`/`metrics`),
+  `resources` (cpu/memory limits & requests), `healthRoute`,
+  `startupProbe`/`readinessProbe`/`livenessProbe`, `command`,
+  `redirects`, `worker` (a separate background deployment). Set
+  `application: false` for a component with no long-running deployment.
+- `cloudsql` — attach an (unmanaged) CloudSQL Postgres instance.
+- `mongodb` — a Bitnami MongoDB (`standalone` or `replicaset`).
+- `jobs` — Helm post-install/upgrade jobs; `cronjobs` — scheduled jobs.
+
+## Cloud Run essentials
+
+`projectId` and `region` are required. Then:
+
+- `service` — the main service (`minInstances`, `maxInstances`, `cpu`,
+  `memory`, `timeout`, `allowUnauthenticated`, `ingress`, `healthCheck`,
+  …). `service: false` disables it (job-only deployments).
+- `additionalServices`, `jobs`, `workerPools` — extra services, run-to-
+  completion jobs, and always-on background worker pools.
+- `cloudSql` — attach an (unmanaged) CloudSQL instance; choose the
+  connection-string format (`prisma` default, `rails`, `jdbc`).
+- `execute` — run a script/job/HTTP call at a deploy lifecycle point
+  (`preDeploy`/`postDeploy`/`preStop`/`postStop`) or on a `schedule`.
+  Prefer this over the deprecated `when`/`schedule` fields on `jobs`.
+
+## Full option reference
+
+See [references/deploy-types.md](references/deploy-types.md) for every
+deploy type's options, required fields, and defaults.
+
+## Related skills
+
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-builds` — the matching `build` config
+- `catladder-pipelines` — how deploy jobs, environments and review apps work
+- `catladder-cli` — `project setup` (provision cloud resources) and `project doctor`
+- `catladder-secrets` — env vars available at runtime

package/dist/skills/catladder-deploys/references/deploy-types.md

@@ -0,0 +1,62 @@
+# catladder deploy config reference
+
+Full options for `components.<name>.deploy` (and per-env
+`env.<name>.deploy`). Fix deploy problems in `catladder.ts` and
+regenerate — never edit generated files. Provision the underlying cloud
+resources with `yarn catladder project setup`; detect drift with
+`yarn catladder project doctor`.
+
+## Shared base (all deploy types)
+
+| Option | Type | Purpose / default |
+|---|---|---|
+| `when` | `"manual" \| "auto"` | prod → `manual`, other envs → `auto` |
+| `waitFor` | `string[]` | EXPERIMENTAL; wait for other components first |
+| `jobTags` | `string[]` | runner tags |
+| `jobVars` | `EnvVars` | env vars only in the deploy job |
+| `runnerVariables` | `Record<string,string>` | extra runner vars |
+
+(Cloud Run defines its own `execute`; otherwise the base applies to all.)
+
+## `kubernetes`
+
+- `cluster` — **required**: `{ type: "gcloud", name, projectId, region, domainCanonical? }`.
+- `debug?: boolean` — pass `--debug` to Helm.
+- `additionalHelmArgs?: string[]`.
+- `chartName?: string` — custom chart location (not recommended).
+- `values?` — app configuration (unknown props allowed, forwarded to the chart):
+  - `application?: false | { command?, enabled? (default true), redirects?, hostAliases?, replicas?, autoscale?: { minReplicas, maxReplicas, metrics[] }, updateStrategy?, resources?: { limits/requests: { cpu, memory } }, healthRoute?, startupProbe? / readinessProbe? / livenessProbe? (httpGet shape), worker?, jobDefaults? }`.
+  - `cloudsql?: { type: "unmanaged", enabled, instanceConnectionName, dbUser?, dbNamePrefix?, dbBaseName? }`.
+  - `mongodb?: { enabled?, dbName?, persistence?, resources?, tolerations? } & ({ architecture: "standalone" } | { architecture: "replicaset", replicaCount? (default 2) })`.
+  - `mailhog?: { enabled }` — dev mail catcher (injects `MAIL_URL`).
+  - `jobs?: Record<string, false | { command, hook? }>` — Helm hook jobs (default hook `post-install,post-upgrade`).
+  - `cronjobs?: Record<string, false | { schedule, command, concurrencyPolicy?, timeZone? }>`.
+  - `secretsFromOtherComponent?: { [envVar]: string }` — load secrets from another component in the same cluster.
+  - `mapServiceUrlToEnv?: { [envVar]: string }` — map another service's internal endpoint to an env var.
+
+## `google-cloudrun`
+
+- `projectId` — **required**.
+- `region` — **required** (`Gcloudregion` enum, e.g. `europe-west6`).
+- `service?: boolean | DeployConfigCloudRunService` (default enabled):
+  - `command?`, `args?`, `image?`, `minInstances?` (0), `maxInstances?` (100), `cpu?` (1|2|4|6|8), `memory?` (512MB), `timeout?` (5min), `noCpuThrottling?`, `allowUnauthenticated?` (true), `ingress?` (`all` | `internal` | `internal-and-cloud-load-balancing`, default `all`), `executionEnvironment?` (`gen1`|`gen2`), `http2?`, `gpu?`/`gpuType?`, `sessionAffinity?`, `healthCheck?` (`true` or `{ startupProbe, livenessProbe }`), plus cloud-storage volumes and VPC network config.
+- `additionalServices?: Record<string, service | false | null>`.
+- `jobs?: Record<string, DeployConfigCloudRunJob | false | null>` — `{ command, args?, image?, cpu?, memory? (512Mi), timeout? (10min), parallelism? (1), maxRetries? (0) }`. The per-job `when`/`schedule`/`waitForCompletion` fields are **deprecated** — use `execute`.
+- `workerPools?: Record<string, DeployConfigCloudRunWorkerPool | false | null>` — always-on background work, no endpoint, no autoscaling: `{ command, instances? (1), cpu?, memory?, image?, args?, gpu?/gpuType? }`.
+- `cloudSql?: DeployConfigCloudRunCloudSql | false` — `{ type: "unmanaged", instanceConnectionName, dbUser?, dbNamePrefix?, dbBaseName?, deleteDatabaseOnStop?, dbConnectionStringFormat? ("prisma" default | "rails" | "jdbc"), dbConnectionStringVariablesMode? ("environment" default | "embedded"), dbAdditionalQueryParams? }`.
+- `execute?: Record<string, DeployConfigCloudRunExecute | null>` — run a script / job / HTTP call at a lifecycle point (`when`: `preDeploy` | `postDeploy` | `preStop` | `postStop`) or on a `schedule`.
+- `debug?: boolean`.
+
+## `dockerTag`
+
+- `type: "dockerTag"`, `tag: string` — **required**. Adds a custom tag on the image repo to deploy it. Only used in one project historically; not generally recommended (runtime env vars must be coordinated manually).
+
+## `custom`
+
+- `type: "custom"` — **required**.
+- `requiresDocker: boolean` — **required**; whether the deploy needs a built Docker image.
+- `script: string[]` — **required**; the deploy script.
+- `requiresYarnInstall?: boolean` — whether the script needs `yarn install`.
+- `stopScript?: string[]` — script to stop/tear down the environment.
+- `jobImage?: GitlabJobImage`.
+- Also accepts `cache` (via `WithCacheConfig`).

package/dist/skills/catladder-pipelines/SKILL.md

@@ -49,7 +49,8 @@ not in the YAML.
 
 With `releases` configured, tagged releases are created by a release
 job (method: `semantic-release` or `changesets`). The release job also
-runs a dependency security audit via catci.
+runs a dependency security audit that gates the release. See the
+`catladder-releases` skill for the full flow.
 
 ## Debugging CI
 
@@ -68,5 +69,8 @@ Useful CLI commands (see the `catladder-cli` skill for invocation):
 ## Related skills
 
 - `catladder-config` — catladder.ts structure and regeneration
+- `catladder-builds` — build jobs and Docker images
+- `catladder-deploys` — deploy jobs, environments and review apps
+- `catladder-releases` — the `taggedRelease` flow and security-audit gate
 - `catladder-secrets` — env vars and secret management
 - `catladder-cli` — non-interactive CLI usage and command reference

package/dist/skills/catladder-releases/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: catladder-releases
+description: How releases work in a catladder project — the `releases` config in catladder.ts (manual vs automatic releasing, and the release method: semantic-release from conventional commits, or changesets from `.changeset/*.md` files), the version/tag/changelog flow, and the security-audit gate that every release must pass. Use when enabling or changing releases, deciding between semantic-release and changesets, writing changesets, cutting or debugging a release, or when a release job fails on the security audit. Triggers on "release", "releases config", "semantic-release", "changesets", "changeset", "version bump", "tag a release", "security audit", "release failed".
+---
+
+# Releases with catladder
+
+A release is what produces a `vX.Y.Z` git tag (with a changelog), which
+in turn triggers the `taggedRelease` pipeline that deploys to `stage`
+and `prod` (see the `catladder-pipelines` skill). Enable it in
+`catladder.ts`:
+
+```ts
+releases: {
+  when: "auto",              // "manual" (default) | "auto"
+  method: "semantic-release", // "semantic-release" (default) | "changesets"
+}
+```
+
+Change `catladder.ts` and regenerate (`yarn catenv`) — the release jobs
+are generated, never hand-edited.
+
+## `when` — who triggers the release
+
+- **`manual`** (default) — the `create release` job on the main branch
+  is manual; someone runs it to cut a release.
+- **`auto`** — the release job runs automatically on every main-branch
+  pipeline (it still no-ops when there is nothing to release).
+
+There is always also a manual **`⚠️ force create release`** job as an
+escape hatch.
+
+## `method` — how the version is decided
+
+### `semantic-release` (default)
+The version is derived automatically from **conventional commit
+messages** since the last release (`fix:` → patch, `feat:` → minor,
+`BREAKING CHANGE` → major). Nothing to declare by hand — just write
+conventional commits.
+
+### `changesets`
+Developers declare changes intentionally as **`.changeset/*.md` files**
+(the official changesets format: a bump type + a human-written summary).
+The release job consumes all pending changesets, takes the highest bump,
+computes the next version from the last `v*` git tag, writes the
+changelog, commits `chore(release): <version>`, and pushes the tag. An
+empty `.changeset/` folder means there is nothing to release.
+
+Add a changeset by creating `.changeset/<name>.md`:
+
+```md
+---
+"my-app": minor
+---
+
+Add the new export endpoint.
+```
+
+## The security-audit gate
+
+**Both methods gate on a dependency security audit before releasing.**
+The release entrypoint runs the audit first; only if it passes does it
+create the version, changelog and tag. On GitLab, if the audit document
+is missing or invalid the job opens a merge request with a security-audit
+template and **fails** — resolve that MR, then re-run the release. See
+the `security` commands in the `catladder-cli` reference.
+
+## Debugging a failed release
+
+- Fails immediately on the audit → handle the security-audit gate above.
+- `changesets` released nothing → no `.changeset/*.md` files were
+  pending.
+- Wrong version bump → check commit types (semantic-release) or the bump
+  levels in the changeset files (changesets).
+- Inspect the job with `yarn catladder project ci job-log` (see the
+  `catladder-cli` skill).
+
+## Related skills
+
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-pipelines` — the `taggedRelease` trigger and stage/prod deploys
+- `catladder-cli` — `project ci` and `security` commands

package/dist/skills/catladder-secrets/SKILL.md

@@ -70,5 +70,7 @@ suspecting anything else.
 ## Related skills
 
 - `catladder-config` — general catladder.ts structure and regeneration
+- `catladder-builds` — build-time vars (`jobVars`) and build config
+- `catladder-deploys` — runtime deploy config
 - `catladder-pipelines` — how the generated pipelines work
 - `catladder-cli` — non-interactive CLI usage and command reference

package/package.json

@@ -53,7 +53,7 @@
     }
   ],
   "license": "MIT",
-  "version": "0.0.0-next-50ef07e9",
+  "version": "0.0.0-next-b0a6c782",
   "scripts": {
     "lint": "eslint \"src/**/*.ts\"",
     "lint:fix": "eslint \"src/**/*.ts\" --fix",