@gapi/gcli 1.8.240 → 1.8.241

package/.agents/skills/cluster-targeting/SKILL.md

@@ -68,3 +68,26 @@ shared with or generated from gql-fission's copy.
 `jest.config.js` has no `moduleNameMapper` for the `~/` tsconfig path alias
 — new test files must use relative imports (e.g. `'../src/helpers'`), not
 `'~/helpers'`, or the test silently fails to resolve the module.
+
+## Managing a private cluster itself (scaling, topology, autoscale)
+
+The `cluster:*` commands that change or watch ONE cluster
+(`status`, `health`, `scale-events`, `cost`, `scale`,
+`scale:control-planes`, `multi-node`, `single-node`, `autoscale`,
+`load-balancer`) share `commands/cluster/helpers/cluster-change.ts`:
+`resolveClusterTarget` (`--cluster <id>` or `--clusterName <name>`,
+required), `parseIntOption`, and `runClusterChange` (mutate → print →
+`--wait` via `pollUntilReady`; ending in `error` exits non-zero). Their
+selections and types live in `commands/cluster/types.ts` (newer than the
+hand-kept `@introspection`).
+
+`cluster:apply` is the declarative path: the `cluster:` section of
+lambforge.yaml (`ClusterDesired` in `helpers/plan.ts`, also the type of
+`load-spec.ts`'s `cluster`). Keep `planClusterChanges` pure and ordered
+(create | topology → workers → control planes → load balancer →
+autoscale): each step is one background job and the cluster must be
+`ready` before the next. A new cluster setting = a key in `ClusterDesired`,
+a check in `validateDesired`, a step in the plan, a test in
+`test/cluster-apply.spec.ts`, and the README "Declarative clusters" block.
+The server merges partial autoscale input into the stored policy, so the
+plan sends only changed keys.

package/README-CLI.md

@@ -30,9 +30,20 @@ Commands:
   cron:delete [options]                                Delete cron
   cron:list [options]                                  List of all cron jobs for project
   cluster:create [options]                             Provision a private Talos cluster for a project (runs in the background - takes several minutes; use --wait to block)
+  cluster:apply [options]                              Make a private cluster match the `cluster:` section of lambforge.yaml: creates it if missing, then applies topology, workers, control planes, load balancer and autoscaling
   cluster:list [options]                               List every private cluster this project has (it may have several - dev/stage/prod, ...)
   cluster:teardown [options]                           Tear down one of a project's clusters (runs in the background - use --wait to block)
   cluster:kubeconfig [options]                         Print (or save) a cluster's raw kubeconfig YAML - only available once it's 'ready'
+  cluster:status [options]                             Every cluster's status, agent, nodes, CPU/memory load, autoscaling and open issues (or one with --cluster)
+  cluster:health [options]                             The latest health report of a cluster's agent, with every node
+  cluster:scale-events [options]                       Manual and autoscaler scale history, newest first
+  cluster:cost [options]                               Month-to-date cost and the monthly estimate of the project's private clusters
+  cluster:scale [options]                              Set the number of worker nodes (1-10) of a multi-node cluster - billed per node-hour
+  cluster:scale:control-planes [options]               Set the number of control-plane nodes (1, 3 or 5)
+  cluster:autoscale [options]                          Change the worker autoscaling policy - only the flags you pass change
+  cluster:multi-node [options]                         Convert a single-node cluster to dedicated worker nodes (required for autoscaling)
+  cluster:single-node [options]                        Convert a multi-node cluster back to a single node (removes the worker nodes)
+  cluster:load-balancer [options]                      Add or remove the cluster's load balancer (billed per hour while enabled)
   rabbitmq:create [options]                            Provision a RabbitMQ broker for a project (a project may have several)
   rabbitmq:list [options]                              List every RabbitMQ broker for a project
   rabbitmq:delete [options]                            Delete a RabbitMQ broker
@@ -508,6 +519,19 @@ Options:
   --wait                     Block until the cluster is ready (or errors)
   -h, --help                 display help for command
 
+--- Subcommand: cluster:apply ---
+Usage: gcli cluster:apply [options]
+
+Make a private cluster match the `cluster:` section of lambforge.yaml: creates it if missing, then applies topology, workers, control planes, load balancer and autoscaling
+
+Options:
+  -p, --project <project>
+  -spec, --spec <spec>     Spec file (default: lambforge.yaml / cluster.yaml)
+  --dry-run                Print the plan, change nothing
+  --yes                    Also apply steps that remove capacity or the load
+                           balancer IP
+  -h, --help               display help for command
+
 --- Subcommand: cluster:list ---
 Usage: gcli cluster:list [options]
 
@@ -539,6 +563,135 @@ Options:
   -o, --output <output>    Write to this file instead of stdout
   -h, --help               display help for command
 
+--- Subcommand: cluster:status ---
+Usage: gcli cluster:status [options]
+
+Every cluster's status, agent, nodes, CPU/memory load, autoscaling and open issues (or one with --cluster)
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  -h, --help                   display help for command
+
+--- Subcommand: cluster:health ---
+Usage: gcli cluster:health [options]
+
+The latest health report of a cluster's agent, with every node
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  -h, --help                   display help for command
+
+--- Subcommand: cluster:scale-events ---
+Usage: gcli cluster:scale-events [options]
+
+Manual and autoscaler scale history, newest first
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  --limit <limit>              How many events (default 20)
+  -h, --help                   display help for command
+
+--- Subcommand: cluster:cost ---
+Usage: gcli cluster:cost [options]
+
+Month-to-date cost and the monthly estimate of the project's private clusters
+
+Options:
+  -p, --project <project>
+  -h, --help               display help for command
+
+--- Subcommand: cluster:scale ---
+Usage: gcli cluster:scale [options]
+
+Set the number of worker nodes (1-10) of a multi-node cluster - billed per node-hour
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  --workers <workers>          Worker nodes, 1-10
+  --wait                       Block until the cluster settles
+  -h, --help                   display help for command
+
+--- Subcommand: cluster:scale:control-planes ---
+Usage: gcli cluster:scale:control-planes [options]
+
+Set the number of control-plane nodes (1, 3 or 5)
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  --count <count>              Control planes: 1, 3 or 5
+  --wait                       Block until the cluster settles
+  -h, --help                   display help for command
+
+--- Subcommand: cluster:autoscale ---
+Usage: gcli cluster:autoscale [options]
+
+Change the worker autoscaling policy - only the flags you pass change
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  --enable                     Turn autoscaling on (multi-node clusters only)
+  --disable                    Turn autoscaling off
+  --min <min>                  Minimum workers (1-10)
+  --max <max>                  Maximum workers (1-10)
+  --cpuUp <percent>            Scale up at this CPU % (1-100)
+  --memUp <percent>            Scale up at this memory % (1-100)
+  --cpuDown <percent>          Scale down below this CPU % (1-100)
+  --memDown <percent>          Scale down below this memory % (1-100)
+  --samples <n>                Consecutive readings before acting (1-20)
+  --cooldown <minutes>         Minutes between scale actions (1-1440)
+  -h, --help                   display help for command
+
+--- Subcommand: cluster:multi-node ---
+Usage: gcli cluster:multi-node [options]
+
+Convert a single-node cluster to dedicated worker nodes (required for autoscaling)
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  --workers <workers>          Worker nodes, 1-10
+  --wait                       Block until the cluster settles
+  -h, --help                   display help for command
+
+--- Subcommand: cluster:single-node ---
+Usage: gcli cluster:single-node [options]
+
+Convert a multi-node cluster back to a single node (removes the worker nodes)
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  --wait                       Block until the cluster settles
+  -h, --help                   display help for command
+
+--- Subcommand: cluster:load-balancer ---
+Usage: gcli cluster:load-balancer [options]
+
+Add or remove the cluster's load balancer (billed per hour while enabled)
+
+Options:
+  -p, --project <project>
+  -c, --cluster <cluster>      Cluster id (see cluster:list)
+  --clusterName <clusterName>  Cluster name instead of --cluster
+  --enable                     Add the load balancer
+  --disable                    Remove the load balancer
+  --wait                       Block until the cluster settles
+  -h, --help                   display help for command
+
 --- Subcommand: rabbitmq:create ---
 Usage: gcli rabbitmq:create [options]
 

package/README.md

@@ -11,6 +11,7 @@ Whether you are deploying scalable serverless functions, managing cloud environm
 - [Managing Infrastructure](#managing-infrastructure)
 - [Serverless Functions (Lambdas)](#serverless-functions-lambdas)
 - [AI Integration (Model Context Protocol)](#ai-integration-model-context-protocol)
+  - [AI agent skill](#ai-agent-skill)
 - [Local AI Models (Ollama runner)](#local-ai-models-ollama-runner)
 - [Build System](#build-system)
 - [Command Reference](#command-reference)
@@ -24,7 +25,7 @@ You can install `gcli` using a pre-built binary or via NPM.
 For a standalone installation without Node.js dependencies:
 
 ```bash
-curl -L "https://github.com/Stradivario/gapi/releases/download/v1.8.198/gcli-linux" -o ~/.local/bin/gcli
+curl -L "https://github.com/Stradivario/gapi/releases/latest/download/gcli-linux" -o ~/.local/bin/gcli
 chmod +x ~/.local/bin/gcli
 ```
 
@@ -95,6 +96,10 @@ gcli environment:get --name 'staging'
 # (omit --clusterId to use the shared cluster - the default). Immutable
 # after creation.
 gcli environment:create --name 'staging' --clusterId '<clusterId>'
+
+# Resize it, or remove it
+gcli environment:update --name 'staging' --maxCpu 800 --maxMemory 1024
+gcli environment:delete --name 'staging'
 ```
 
 ### Private Clusters
@@ -119,17 +124,79 @@ gcli cluster:kubeconfig --cluster '<clusterId>' --output ./kubeconfig.yaml
 gcli cluster:teardown --cluster '<clusterId>' --wait
 ```
 
-`cluster.yaml`:
+Scale, reshape and watch a cluster (the same operations as the dashboard's
+cluster page). Changes run in the background; `--wait` blocks until the
+cluster is `ready` again. `--clusterName <name>` works instead of
+`--cluster <id>` everywhere.
+
+```bash
+# Health, load, autoscaling and open issues of every cluster (or one)
+gcli cluster:status [--cluster '<clusterId>']
+gcli cluster:health --cluster '<clusterId>'        # latest agent report, per node
+gcli cluster:scale-events --cluster '<clusterId>'  # manual + autoscaler history
+gcli cluster:cost                                  # month-to-date + monthly estimate
+
+# Worker nodes (1-10, billed per node-hour) and control planes (1, 3 or 5)
+gcli cluster:scale --cluster '<clusterId>' --workers 3 --wait
+gcli cluster:scale:control-planes --cluster '<clusterId>' --count 3 --wait
+
+# Topology: dedicated workers (needed for autoscaling) or back to one node
+gcli cluster:multi-node --cluster '<clusterId>' --workers 2 --wait
+gcli cluster:single-node --cluster '<clusterId>' --wait
+
+# Autoscaling - only the flags you pass change
+gcli cluster:autoscale --cluster '<clusterId>' --enable --min 2 --max 6
+gcli cluster:autoscale --cluster '<clusterId>' --cpuUp 75 --cpuDown 25 --cooldown 20
+gcli cluster:autoscale --cluster '<clusterId>' --disable
+
+# Load balancer (billed per hour while enabled)
+gcli cluster:load-balancer --cluster '<clusterId>' --enable --wait
+```
+
+#### Declarative clusters (`cluster:apply`)
+
+Write the cluster you want in the `cluster:` section of `lambforge.yaml`
+(or a standalone `cluster.yaml`) and let `cluster:apply` make it so: it
+creates the cluster when it doesn't exist, then applies topology, workers,
+control planes, the load balancer and autoscaling - one change at a time,
+waiting for the cluster to be ready between them. Keys you leave out are
+left as they are.
 
 ```yaml
-name: prod
-imageId: <hcloud-image-id>
-serverType: cpx22
-location: nbg1
-workers: 2
-singleNode: false
+cluster:
+  name: prod
+  # needed only to create it
+  imageId: <hcloud-image-id>
+  serverType: cpx22
+  location: nbg1
+  # desired state
+  singleNode: false        # true = one node runs everything (cheapest, dev/stage)
+  workers: 3               # 1-10; only the initial size while autoscale is enabled
+  controlPlanes: 1         # 1, 3 or 5
+  loadBalancer: true
+  autoscale:
+    enabled: true          # needs singleNode: false
+    minWorkers: 2
+    maxWorkers: 6
+    cpuScaleUpPercent: 70  # scale up above this (of allocatable)
+    memScaleUpPercent: 70
+    cpuScaleDownPercent: 30
+    memScaleDownPercent: 30
+    samplesToScale: 3      # consecutive readings before acting
+    cooldownMinutes: 15
+```
+
+```bash
+gcli cluster:apply --dry-run     # print the plan, change nothing
+gcli cluster:apply               # apply it
+gcli cluster:apply --yes         # also steps that remove capacity or the LB IP
+gcli cluster:apply --spec cluster.yaml
 ```
 
+Steps that remove capacity or release the load balancer's IP (going back to
+`singleNode: true`, `loadBalancer: false`) are skipped unless you pass
+`--yes`. Nodes and the load balancer are billed per started hour.
+
 ### RabbitMQ Brokers
 
 A project may have several RabbitMQ brokers, each optionally scoped to one of its private clusters.
@@ -285,15 +352,25 @@ options:
     external: []
 ```
 
-The same file can also carry `cluster:`, `rabbitmq:`, and `plugin:` sections, read by `cluster:create`, `rabbitmq:create`, and `plugin:install` respectively (each also accepts its own dedicated `--spec` file, e.g. `cluster.yaml`, if you'd rather keep them separate):
+The same file can also carry `cluster:`, `rabbitmq:`, `plugin:` and `triggers:` sections, read by `cluster:apply` / `cluster:create`, `rabbitmq:create`, `plugin:install` and `cron:create` respectively (each also accepts its own dedicated `--spec` file, e.g. `cluster.yaml`, if you'd rather keep them separate):
 
 ```yaml
-cluster:
+cluster:          # every key: see "Declarative clusters" above
   name: prod
   imageId: <hcloud-image-id>
   serverType: cpx22
   location: nbg1
   workers: 2
+  loadBalancer: false
+  autoscale:
+    enabled: true
+    minWorkers: 2
+    maxWorkers: 5
+
+triggers:
+  time:
+    triggerName: nightly
+    cron: '0 2 * * *'   # cron syntax or @every 5m / @daily
 
 rabbitmq:
   name: events-broker
@@ -361,7 +438,7 @@ gcli lambda:create --project <projectId> --spec ./lambforge.yaml
 `--mcp` and `--mcpGraph <name>` are also available as CLI flags; the array fields
 (`mcpOperations`, `mcpHeaders`, `mcpForwardHeaders`) are spec-only. A full annotated example lives in
 [`example/mcp/lambforge.yaml`](./example/mcp/lambforge.yaml). Client connects at
-`https://<host>/<projectId>/<route>/mcp`.
+`https://<host>/<projectId>/<route>` (with `route: mcp`: `https://<host>/<projectId>/mcp`).
 
 ### Conditional Configuration (Environment-Aware Specs)
 
@@ -638,10 +715,23 @@ gcli environment:update
 
 ### Function Lifecycle
 
+- **List**: `gcli lambda:list` (`--clusterName <name>` for one cluster's lambdas)
 - **Update**: `gcli lambda:update --name 'my-function' --file ./new-index.ts`
 - **Delete**: `gcli lambda:delete --name 'my-function'`
 - **Get Details**: `gcli lambda:get --name 'my-function'`
 
+### Schedules (cron)
+
+One time trigger per lambda. The platform calls the lambda's root with a
+GET and an `X-Fission-Timer-Name` header.
+
+```bash
+gcli cron:create --lambdaName 'my-function' --triggerName nightly --cron '0 2 * * *'
+gcli cron:create                 # reads triggers.time (and function.name) from lambforge.yaml
+gcli cron:list
+gcli cron:delete --lambdaName 'my-function'
+```
+
 ### Monitoring & Testing
 
 Debug your functions directly from the terminal.
@@ -715,6 +805,33 @@ To use this with Claude Desktop or other MCP-compatible tools, add the following
 }
 ```
 
+### AI agent skill
+
+Give a coding agent (Claude Code and other agents that read skills) the
+whole platform. Paste this into the agent:
+
+```text
+Install the Lambforge skill from https://lambforge.com/skills/platform.md and follow its setup.
+```
+
+Or by hand for Claude Code:
+
+```bash
+mkdir -p ~/.claude/skills/lambforge && cd ~/.claude/skills/lambforge
+for f in $(curl -fsSL https://lambforge.com/skills/files.txt); do
+  curl -fsSLO "https://lambforge.com/skills/$f"
+done
+cp platform.md SKILL.md
+claude mcp add --scope user lambforge -- gcli mcp:start
+```
+
+`platform.md` covers setup (install gcli, the login command you run from
+Profile -> CLI - the agent never handles your token, `gcli mcp:start`) and
+the rules, and indexes topic files the agent reads on demand: gcli, MCP
+tools, deploy, REST code and testing, GraphQL and federation, websites,
+MCP servers, secrets, cron and queues, clusters and plugins, operations and
+costs, memory and plans. Source: gql-fission `src/skills/`.
+
 ## Local AI Models (Ollama runner)
 
 Use models running on your own machine in the Lambforge chat - including

package/docs/changelog.d/2026-10-19-dedicated-platform-cluster-cluster-scaling-topology-load-balancer-and-health-commands-c.md

@@ -0,0 +1,31 @@
+## 2026-10-19 - dedicated-platform-cluster: Cluster scaling, topology, load balancer and health commands (cluster:status, health, scale, autoscale, ...)
+
+**Feature:** dedicated-platform-cluster · **Type:** feat
+
+- New commands (the dashboard cluster page's actions, same
+  cluster-provisioner operations): `cluster:status`, `cluster:health`,
+  `cluster:scale-events`, `cluster:cost`, `cluster:scale --workers`,
+  `cluster:scale:control-planes --count`, `cluster:multi-node`,
+  `cluster:single-node`, `cluster:autoscale` (partial: only the given
+  flags change), `cluster:load-balancer --enable|--disable`. All take
+  `--cluster <id>` or `--clusterName <name>`; mutations take `--wait`
+  (polls until ready; ending in `error` exits non-zero with the reason).
+- `cluster:apply [--spec] [--dry-run] [--yes]`: the `cluster:` section of
+  lambforge.yaml / cluster.yaml is now a desired state (new keys
+  `controlPlanes`, `loadBalancer`, `autoscale.*`; `singleNode`, `workers`
+  as before). It creates the cluster when missing (in the desired shape)
+  and otherwise plans and applies topology → workers → control planes →
+  load balancer → autoscale, waiting for `ready` between jobs; destructive
+  steps need `--yes`. `cluster:create` also passes `controlPlanes` and
+  `loadBalancer` from the spec now.
+- Client-side checks mirror the server's bounds (workers 1-10, control
+  planes 1/3/5, autoscale ranges) so a bad value fails before any request.
+- `README.md` Private Clusters section, regenerated `README-CLI.md`.
+- **Test:** `npx jest --coverage=false` (71 tests; new
+  `test/cluster-scaling.spec.ts`, `test/cluster-apply.spec.ts` (the plan),
+  `test/cluster-apply-command.spec.ts` (dry-run, `--yes`, create, refusals)).
+- **Debug:** slice doc `docs/features/dedicated-platform-cluster.md`.
+- **Verification:** jest 71/71; the built binary's `cluster:apply` read a
+  real lambforge.yaml and rejected `controlPlanes: 2` before any request; tsc + eslint clean; `npm run build` and
+  `--help` checked for every command (`release/index.js` restored after,
+  not a release).

package/docs/changelog.d/2026-10-19-lambforge-agent-skill-readme-points-to-the-lambforge-agent-skill-gcli-mcp-start-fo.md

@@ -0,0 +1,17 @@
+## 2026-10-19 - lambforge-agent-skill: README points to the Lambforge agent skill (gcli + mcp:start for AI agents)
+
+**Feature:** lambforge-agent-skill · **Type:** docs
+
+- README.md "AI agent skill" (under AI Integration): the prompt to paste into
+  an agent (https://lambforge.com/skills/platform.md), the manual Claude Code
+  install (every file from `files.txt`, `platform.md` copied to `SKILL.md`,
+  `claude mcp add --scope user lambforge -- gcli mcp:start`), and what the
+  topic files cover. The skill lives in gql-fission `src/skills/` (canonical
+  doc there).
+- `docs/features/lambforge-agent-skill.md`: which gcli commands the skill
+  quotes - change them, update SKILL.md in the same change.
+- **Test:** none (docs); the commands it lists were checked with
+  `node release/index.js <command> --help`.
+- **Debug:** an agent runs a gcli command that fails → compare SKILL.md with
+  `gcli <command> --help`.
+- **Verification:** no code change.

package/docs/changelog.d/2026-10-19-repo-cron-create-honours-cron-triggername-readme-brought-up-to-da.md

@@ -0,0 +1,21 @@
+## 2026-10-19 - repo: cron:create honours --cron/--triggerName; README brought up to date with every command
+
+**Feature:** repo · **Type:** fix
+
+- `cron:create` declared `--cron` and `--triggerName` but only read them
+  from the spec (`triggers.time` of lambforge.yaml / cron.yaml), so the
+  documented `gcli cron:create --lambdaName x --triggerName nightly --cron
+  '0 2 * * *'` sent an empty schedule. Flags now win, the spec fills gaps,
+  and a missing schedule is a clear error before any request.
+- README: binary install from `releases/latest` (was pinned to v1.8.198);
+  `environment:update/delete`, `lambda:list` and a "Schedules (cron)"
+  section (the commands were missing); `triggers:` in the unified
+  lambforge.yaml; the MCP client URL is `https://<host>/<projectId>/<route>`
+  (the `/mcp` suffix was wrong - see example/mcp/lambforge.yaml); the
+  declarative cluster section. Every command registered in `src/commands`
+  now appears in README.md.
+- **Test:** `npx jest --coverage=false test/cron-create.spec.ts` (flags,
+  flags over yaml, missing schedule).
+- **Debug:** a cron with an empty schedule → an older gcli; upgrade.
+- **Verification:** jest 71/71; a script compared the commands registered in
+  `src/commands` against README.md (no command missing).

package/docs/features/README.md

@@ -31,3 +31,5 @@ Outline (drop sections that don't apply):
 | Feature | Doc | Notes |
 |---|---|---|
 | `local-ai-runners` | [local-ai-runners.md](local-ai-runners.md) | `runner:*` commands; canonical doc in graphql-server |
+| `lambforge-agent-skill` | [lambforge-agent-skill.md](lambforge-agent-skill.md) | The agent skill that teaches gcli + `mcp:start`; canonical doc in gql-fission |
+| `dedicated-platform-cluster` | [dedicated-platform-cluster.md](dedicated-platform-cluster.md) | `cluster:status/health/scale/autoscale/...` commands; canonical doc in lambforge-agent |

package/docs/features/dedicated-platform-cluster.md

@@ -0,0 +1,70 @@
+# dedicated-platform-cluster (gcli slice)
+
+**Canonical doc:** `lambforge-agent/docs/features/dedicated-platform-cluster.md`
+· **Since:** 2026-10-19 (cluster scaling and health commands)
+
+The cluster page's scaling, topology, load balancer and health actions as
+commands (cluster-provisioner operations, the same ones gql-fission's
+`core/services/cluster/*.graphql` use; every one is USER-enabled with
+`isMemberOrProjectOwner`):
+
+| Command | Operation |
+|---|---|
+| `cluster:status [--cluster]` | `projectClustersOverview` (status, agent, nodes, load, autoscale, issues) |
+| `cluster:health --cluster` | `clusterHealth(limit: 1)` - latest agent report + nodes |
+| `cluster:scale-events --cluster [--limit]` | `clusterScaleEvents` |
+| `cluster:cost` | `projectClustersOverview` (`monthToDate`, `estimatedMonthlyCostEur`) |
+| `cluster:scale --workers 1-10 [--wait]` | `scaleProjectCluster` |
+| `cluster:scale:control-planes --count 1/3/5 [--wait]` | `scaleControlPlanesProjectCluster` |
+| `cluster:multi-node --workers [--wait]` / `cluster:single-node [--wait]` | `migrateToMultiNodeProjectCluster` / `revertToSingleNodeProjectCluster` |
+| `cluster:autoscale [--enable/--disable] [--min --max --cpuUp --memUp --cpuDown --memDown --samples --cooldown]` | `updateProjectClusterAutoscale` - partial: the server merges it into the stored policy and validates (min <= max, scale-down below scale-up, single-node cannot autoscale) |
+| `cluster:load-balancer --enable/--disable [--wait]` | `enable/disableLoadBalancerProjectCluster` |
+| `cluster:apply [--spec] [--dry-run] [--yes]` | reconciles the `cluster:` section of lambforge.yaml: `projectClusters` (current) → plan → provision / topology / scale / control planes / load balancer / autoscale, one job at a time, waiting for `ready` between them |
+
+## Declarative clusters (`cluster:apply`)
+
+`cluster:` keys: `name` (identity), `imageId` / `serverType` / `location`
+(create only), `singleNode`, `workers` (1-10), `controlPlanes` (1/3/5),
+`loadBalancer`, `autoscale.{enabled,minWorkers,maxWorkers,cpuScaleUpPercent,
+memScaleUpPercent,cpuScaleDownPercent,memScaleDownPercent,samplesToScale,
+cooldownMinutes}`. Missing keys are left alone.
+
+- `helpers/plan.ts` `planClusterChanges(current, desired)` is pure (unit
+  tested): create in the desired shape (workers, control planes, load
+  balancer at provision time) then autoscale; otherwise topology → workers
+  → control planes → load balancer → autoscale (only the changed keys).
+- `workers` is skipped while `autoscale.enabled` (the autoscaler owns it);
+  converting to multi-node already creates the workers.
+- Destructive steps (to single-node, removing the load balancer) need
+  `--yes`; without it they are printed and skipped.
+- `validateDesired` mirrors the server's bounds; a cluster that is not
+  `ready` is refused (apply again once it settles).
+
+## Files
+
+| Path | Responsibility |
+|---|---|
+| `src/commands/cluster/index.ts` | registration (`--cluster` / `--clusterName` on every one) |
+| `src/commands/cluster/{status,health,scale-events,cost,scale,scale-control-planes,autoscale,multi-node,single-node,load-balancer}.ts` | actions |
+| `src/commands/cluster/helpers/cluster-change.ts` | target resolution, int validation, mutate → print → `--wait` (`pollUntilReady`; ends in `error` → non-zero exit) |
+| `src/commands/cluster/types.ts` | local types + selections (newer than `@introspection`) |
+| `src/services/gql-client.ts` | the API calls |
+
+## How to test
+
+`npx jest --coverage=false test/cluster-scaling.spec.ts`; manually against a
+project with a private cluster: `gcli cluster:status`, then
+`gcli cluster:scale --clusterName <n> --workers 2 --wait`.
+
+## How to debug
+
+| Symptom | Look at |
+|---|---|
+| "Pass --cluster <id> or --clusterName" | no cluster given; `gcli cluster:list` |
+| autoscale refused | the server's message: single-node clusters must `cluster:multi-node` first; external clusters cannot autoscale |
+| `--wait` ends in error | `gcli cluster:list` (status + error), the dashboard's cluster page |
+
+## Not in the CLI yet
+
+Resource migration between clusters (`migrateResourcesToCluster` + status /
+retry), Fission options, the cluster agent install/rotate - dashboard only.

package/docs/features/lambforge-agent-skill.md

@@ -0,0 +1,22 @@
+# lambforge-agent-skill (gcli slice)
+
+**Canonical doc:** `gql-fission/docs/features/lambforge-agent-skill.md` ·
+**Since:** 2026-10-19
+
+The Lambforge agent skill (entry https://lambforge.com/skills/platform.md,
+topic files next to it; source in gql-fission `src/skills/`) teaches AI
+agents to drive this CLI. `cli.md` lists every command, and `platform.md`,
+`deploy.md`, `events.md`, `clusters.md` and `agents.md` quote gcli exactly:
+
+- install: `npm i -g @gapi/gcli` (or `npx @gapi/gcli`);
+- login: the command from Profile -> CLI (`login --token --key --url
+  --uploadUrl`), run by the human;
+- `project:list` / `project:use`;
+- `mcp:start` without `--url` (proxy to `<login url>/mcp`, token refresh on
+  401/403) as the MCP server: `claude mcp add --scope user lambforge -- gcli mcp:start`;
+- the `lambda:*`, `environment:*`, `cron:*`, `cluster:*`, `rabbitmq:*`,
+  `plugin:*`, `build`, `start` commands and flags it lists.
+
+**When you change any of those commands, flags or `mcp:start`, update
+the skill files in gql-fission in the same change** - agents copy it verbatim.
+README.md "AI agent skill" points users to it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gapi/gcli",
-  "version": "1.8.240",
+  "version": "1.8.241",
   "repository": {
     "type": "git",
     "url": "https://github.com/Stradivario/gapi.git"