cli

Overview ¶

Package cli — `forge project annotations`: dump forge's authoritative entity-authoring annotation spec as structured data.

The command answers "what annotations does forge understand, and what do they do?" from forge's OWN definitions rather than from prose that drifts:

• markers the `// forge:*` comment markers the proto scanner reads (forge:entity, forge:soft-delete, forge:append-only, forge:read-only, forge:computed, forge:generated, forge:secret, …).
• field_types the proto→column mapping an entity birth applies, iterated from the real scaffold.ProtoSQLMappings (whose scalar half is projected from the renderer's scalarSQL).
• validate_rules the projected protovalidate subset, DISCOVERED by probing forge's own recognizer (codegen.ParseRawValidateOptions) with every rule protovalidate itself declares, and whose db/zod effects are COMPUTED by forge's own projection functions (codegen.FieldConstraints.SQLChecks / .ZodChain).
• service_options / method_options the (forge.v1.service) / (forge.v1.method) proto options, enumerated from the compiled forgepb descriptors.

Everything sourced from an iterable structure is derived, not transcribed, so the dump tracks the code. The genuinely descriptive fields (a marker's effect/example, an option's default) are thin literals whose source is cited at the definition site; a package test pins their names against the real recognizers/descriptors so a rename can never silently drift the dump.

Package cli — `forge api` command surface.

`forge api curl <service.method>` prints a copy-pasteable curl invocation for a Connect RPC endpoint. Connect handlers already speak plain HTTP/1.1 POST with application/json — no gRPC tooling needed — but the URL shape and Content-Type rules are undocumented in most projects. This command removes the discovery friction: look up the method's input message in forge_descriptor.json and emit a curl command with a request-body skeleton populated from zero values for each field, addressed to the conventional local listener (--port overrides).

Streaming RPCs are flagged but still printed — the body shape is the same; only the Content-Type changes to application/connect+json. We surface the difference rather than reject the command so users can hit streaming endpoints too (curl will get the first frame; this is enough to verify reachability and auth).

Package cli — `forge project audit` external-builds category (Phase 3 of the build_cmd / external-build escape-hatch refactor).

Surfaces every KCL service whose effective build is a ShellBuild. For each such service the category emits:

• the resolved build_cwd state (exists / missing on disk),
• the last build state from buildtarget.ReadState (image, tag, pushed_at) for every env that recorded one,
• any build_env keys that conflict with a built-in substitution token (IMAGE / TAG / SERVICE / PROJECT_DIR / REGISTRY / TARGETARCH / BUILD_CWD).

Sub-agents and CI dashboards can branch on `.external_builds.status == "warn"` (or "error") directly. The category honours the additive-extension contract from the audit-json skill — a new field on the per-service detail map is additive; consumers that don't read the new key are unaffected.

We render the dev env to enumerate services (matching auditIngress's approach) because that's the only env every project is guaranteed to have. The per-service ReadState loop walks every env declared under deploy/kcl/<env>/main.k so the snapshot reflects what each env last built, not just dev.

Status semantics:

• ok — no services declare a ShellBuild, OR every service has a present build_cwd, no env-key conflicts, and at least one env has recorded state (or no envs at all).
• warn — at least one service has a missing build_cwd on disk, OR at least one service declares a build_env key that collides with a built-in token. Neither blocks a build — skip-with-warn for cwd is the documented contract, and the built-in wins on conflict — but both are surface-up worthy.
• error — KCL render itself failed AND we know features.build is on (project intends to build something; we can't see whether external builds are configured). Degrades to warn when the failure is environmental (kcl not on PATH, no deploy/kcl/dev dir).

Package cli — `forge project audit` ingress category (KCL-entity-typed half).

auditIngress / ingressBackendNames / crossCheckIngress stay in package cli because they depend on the KCL render + entity structs (GatewayEntity / HTTPRouteEntity / GRPCRouteEntity) shared by ~12 cli files (build/deploy/dev/doctor). The audit command group (internal/cli/audit) reaches auditIngress through factory.AuditAPI.Ingress, so it never touches these entity types. They return the neutral audittype.Category the group consumes.

Package cli — `forge project audit` prerequisites category.

Surfaces the env's DECLARED external prerequisites (forge.ExternalSecret / forge.DNSRecord on Bundle.required_secrets / required_dns) — the out-of-band facts a deploy depends on but forge does NOT create. Today these prereqs live only in KCL docstrings, so `forge env deploy` renders green and THEN cert-manager's ACME challenge or the workspace-proxy DNS hangs silently because the prereq was never satisfied. Modeling them as first-class entities turns the docstring into:

• a render-time CHECKLIST (this audit category + the deploy banner),
• a deploy PREFLIGHT block on a declared-required-but-absent ExternalSecret (see cluster.Preflight / RequiredSecrets), and
• a cross-secret BYTE-MATCH consistency check: ExternalSecrets sharing a `value_group` carry the SAME logical value; this category reports the group membership (the KCL schema already blocks a group whose members declare different key sets, and the live byte-compare runs in the preflight).

Like auditIngress this renders the dev env (the only env every project is guaranteed to have) purely to ENUMERATE the declarations; the category is informational (status ok/warn), never an error — a declared prereq is a good thing, and whether it's SATISFIED is a live-cluster question the deploy preflight answers, not a static audit.

build_external.go is the SINGLE dispatcher for KCL Services whose effective build is a ShellBuild (`build = forge.ShellBuild { cmd, cwd, env }`) — the one shell escape hatch. Mirrors the deploytarget/External provider on the build side — same `sh -c` shape, same ${X} substitution, same fail-when-cwd-missing contract. See internal/buildtarget for the runner + spec types.

The dispatcher's responsibilities are deliberately narrow:

• Iterate KCL services whose effective build is a ShellBuild (EffectiveBuildCmd != "").
• Build a Spec from KCL fields + the build-loop's resolved tag / registry / target arch.
• Run Spec through buildtarget.Runner.Build.
• Persist per-service state when the build succeeded so a subsequent `forge env deploy <env>` can pin the same tag.

Build-side ownership boundary: the user's BuildCmd owns BOTH the build AND the push (the user composes `docker build … && docker push …` into one string). Forge does NOT run docker push afterwards. This matches the External (deploy) provider's "user owns the CLI" contract — one mental model across both escape hatches.

Package cli — `forge project capabilities`: everything forge can do for you, in one call, derived from forge itself.

WHY THIS EXISTS. A dogfood run measured "researching how forge wants things done" as the single largest time bucket on the way to a green gate. The surface is not hidden — every verb is under some `--help` — but reaching it costs one invocation per command group, so an agent that does not already suspect `forge scaffold rpc` exists writes the handler stub by hand. This command answers "what does forge already do?" in one call, which is the only shape that competes with guessing.

Everything here is ENUMERATED, never transcribed:

• commands the real cobra tree (cli.NewRootCmd), walked depth-first with each command's own Short. A verb that is added, renamed or removed changes this dump with no edit here.
• analyzers every flag on `forge lint`, INCLUDING the maintainer flags hidden from --help — a hidden analyzer is still a capability, and `--wire-coverage` / `--scaffolds` are documented nowhere else an agent will look.
• markers markerSpecs(), which a package test pins against the real recognizers in the proto scanner.

The deliberate omission is prose about WHEN to reach for each verb. That is what the skills are for; a transcribed opinion here would be the hand-maintained list this command exists to avoid.

Package cli — declarative cluster reconcile for `forge env up`.

This file generalizes the dev-only, single-cluster ensureDevCluster bootstrap into a declarative LIST: an env declares `Bundle.clusters = [forge.Cluster {...}, ...]` and forge ensures each exists at the head of `forge env up` (create-if-absent, no-op if present).

This file IS the k3d ClusterProvider's implementation (see cluster_provider.go for the registry that dispatches to it per-entity by Cluster.provider). Everything below — ensureDeclaredCluster, the create/start/heal seams, the node-level docker shell-outs — is k3d- specific; a "vcluster" or "gke" provider is a SEPARATE ClusterProvider implementation with its own file, not a branch added here.

Multi-cluster ownership is a REFERENCE. There is no "primary" cluster: a secondary cluster names its `owner` Cluster, and the KCL render layer DERIVES the joined docker network (Cluster.Network = `k3d-<owner.name>`) and the registry-inherit flag (Cluster.RegistryInherit = true) from that one edge. The owner cluster projects neither — k3d creates its own network/registry. There is no most-X heuristic. `owner` is meaningful for k3d only — see the Cluster schema doc (kcl/schema.k) for why a vcluster's host relationship is a distinct `host?` edge instead.

Package cli — the cluster-provisioning provider registry.

This mirrors internal/deploytarget's Provider/Registry shape (deploytarget.go), one level earlier in the pipeline: deploytarget dispatches a rendered SERVICE to the pipeline that ships it somewhere (k8s-cluster / external / compose / host-infra); this dispatches a declared CLUSTER to the pipeline that ensures it exists in the first place, before any service can be deployed into it.

Package cli — standalone k3d registry lifecycle for declared clusters.

A k3d "Simple" config can reference a registry in two ways:

• registries.create — k3d creates a registry container OWNED BY the cluster. `k3d cluster delete` destroys it. Every cold recreate then rebuilds + re-pushes every image (the fat ones especially).
• registries.use — k3d references an EXISTING registry container. A standalone registry (`k3d registry create`) is owned by NO cluster, so it survives `cluster delete` and its pushed images persist across cold recreates.

This file makes the persistent path zero-glue: when a declared cluster's k3d config references a registry via `registries.use`, forge ensures that standalone registry exists BEFORE `k3d cluster create` runs. Idempotent — an already-present registry is a no-op; an absent one is created with the declared host port so host pushes keep resolving to the same `localhost: <port>` ref.

Package cli — `forge project delete service` — the inverse of `forge scaffold service`.

Where `forge scaffold service` scaffolds a handlers/<svc>/ dir and (after the user lists its serviceRow line) serves it, `forge project delete service` walks that back:

1. Removes the handler scaffold directory (handlers/<svc>/).
2. Leaves a TYPES-ONLY tombstone comment in pkg/app/services.go in place of the serviceRow line. The comment is load-bearing: the registry treats any mention of the service name in that file as "deliberately not served here", so the proto types / Connect client / frontend hooks keep generating for callers while the handler scaffold, wiring, and auth registration are gated off. (See generate_serve.go's package doc for the registry semantics.)

This addresses the orphan-stub hazard (FORGE_SHAPE_REDESIGN §7f): a service added but never implemented previously had no inverse command, so it lingered as an Unimplemented CRUD stub with no consumers. Delete is the explicit retirement path.

Destructive (it removes a directory), so it confirms before acting unless --yes; --dry-run prints the plan and changes nothing.

Package cli — bridge from declared platform deps (forge.HelmChart) to the cluster apply pipeline's helm-as-a-RENDERER path.

The KCL layer projects each forge.HelmChart into the `output.helm_charts` contract (HelmChartEntity). This file turns those declarations into internal/cluster.HelmChartSpec values — fetching the forge-supplied CRD bundle each chart needs (the pinned standard Gateway API CRDs for Envoy Gateway; cert-manager's CRDs at the chart version) so cluster.Apply can apply CRDs-first/Established-gated before the chart's --skip-crds controllers.

The CRD-fetch REUSES the existing pinned-CRD machinery (dev_cluster_ingress.go: ingressPinnedVersions + the cached fetch) that the k3d `forge cluster up` path already owns — keeping internal/cluster free of the templates/cache dependency (cli imports cluster, not the reverse).

Package cli — `forge cluster` command tree.

The `cluster` subtree consolidates the universal local-cluster lifecycle mechanics every k8s-targeting forge project would otherwise hand-write in bash, plus the dev-state introspection commands:

• up/down/reset/reload (k3d cluster lifecycle)
• status (dynamic: cluster up/down, pods, ingress URLs)
• urls (ingress URL table for the env)
• logs / info / instances (per-namespace introspection)

kubectl port-forward isn't wrapped here — the Gateway API ingress path (forge cluster urls) is the canonical "reach a service from the host" entry point. Ad-hoc port-forwards for stateful workloads (database shells, debug metrics endpoints) are `kubectl port-forward` directly.

Project-specific orchestration (sibling-repo deploys, helm bootstraps, Stripe webhook listeners, project-specific seeds) is NOT owned by forge — projects keep those in scripts/ and Taskfile.yml, composed with the forge cluster primitives. See the `dev` skill for the boundary doc.

Package cli — `forge cluster` k3d lifecycle subcommands.

This file consolidates the k3d cluster lifecycle that every k8s-targeting forge project would otherwise hand-write in bash (~30-50 lines of idempotent create / delete / wait-for-rollout / context-pin logic).

k3d itself is the source of truth for cluster state — we shell out to `k3d cluster create/delete/list` rather than reinvent. The value forge adds is:

• read deploy/k3d.yaml as the canonical config (no hand-written --servers/--no-lb/--registry-create flags scattered across scripts)
• idempotent up/down semantics (`up` no-ops if the cluster exists, `down` no-ops if it doesn't)
• kubectl context pinning so `forge cluster reload` can't accidentally apply to staging or prod
• one-command reload that re-renders KCL + applies + waits for rollout (the inner loop during local dev)

Package cli — `forge cluster up` ingress install plumbing.

forge is OPINIONATED on ONE Gateway API controller everywhere: Envoy Gateway (controllerName gateway.envoyproxy.io/gatewayclass-controller, GatewayClass `eg`). The local k3d bring-up installs the SAME helm chart the cloud envs (staging/preprod/prod) run, so a Gateway that renders `gatewayClassName: eg` behaves identically on a laptop and in the cloud. Envoy Gateway serves HTTPRoute AND GRPCRoute natively, so one controller covers every forge route shape — no second controller for gRPC.

Three pieces, run in order after the k3d cluster is created and kubectl context pinned:

1. Fetch + apply the upstream Gateway API standard-channel CRDs (version pinned via internal/templates/ingress/envoy/VERSION). Cached under ~/.cache/forge/ingress/ so subsequent cluster-up runs are offline-capable. The gateway-helm chart bundles the CRDs it needs, but we apply the pinned standard channel explicitly first (server-side) so the CRD surface matches the cloud install and so `kubectl wait` on Established gates the GatewayClass apply.
2. `helm upgrade --install --skip-crds` the Envoy Gateway controller from the pinned gateway-helm chart version into envoy-gateway-system, the SAME release the cloud envs run. `--skip-crds` is required: the chart bundles an OLDER, experimental-channel copy of the Gateway API CRDs that the safe-upgrades ValidatingAdmissionPolicy (shipped by the standard CRDs applied in step 1) would DENY — see helmInstallEnvoyGateway. Envoy Gateway provisions a managed Envoy proxy per Gateway with listener sockets derived dynamically from Gateway.spec.listeners — no static per-listener entrypoint config to template (unlike the old Traefik install). The proxy's LoadBalancer Service ports follow the Gateway listeners; on k3d the bundled klipper servicelb binds those node ports and the k3d serverlb forwards the host ports mapped from deploy/k3d-ports.yaml.
3. Apply the vendored `eg` GatewayClass (idempotent).

Idempotency comes from `helm upgrade --install` + `kubectl apply` semantics — re-running against a cluster that already has them noops. We block on CRD establishment between (1) and (3) so the GatewayClass apply doesn't race the CRD install.

Also: k3d config merging — `forge generate` writes `deploy/k3d-ports.yaml` derived from the dev env's KCL gateway listeners. At cluster-up time we read deploy/k3d.yaml + deploy/k3d-ports.yaml, merge their ports blocks in memory, and hand a temp file to `k3d cluster create`. Keeps deploy/k3d.yaml user-owned while keeping host ports in lockstep with the project's declared Gateway listeners.

Package cli — `forge cluster up` mkcert TLS provisioning.

Why this exists: in dev, cert-manager's only stand-alone option is a self-signed Issuer whose CA isn't in the host trust store, so every browser shows a warning and every curl needs `-k`. mkcert installs a CA into the OS trust store once (`mkcert -install`) and signs leaf certs the host already trusts. The cluster-side shape stays identical to prod (Gateway carries `tls:`, listener is HTTPS, Secret is referenced normally); only the cert origin differs.

This file walks the dev env's rendered KCL, finds Gateways whose tls.mode == "mkcert", and provisions a kubernetes.io/tls Secret per (hostname, secret_name) pair. Re-running just refreshes the Secret.

Package cli — `forge cluster info` command.

Diagnostic dump of the dev-loop config: which cluster, which context, which namespace, which service ports. Replaces the small bash recipe every project would otherwise hand-write to debug "why is my ingress URL hitting the wrong service?"

Package cli — `forge cluster instances` command.

Lists every forge-managed dev namespace on every reachable k3d cluster. Supports the multi-worktree workflow where each worktree runs in its own namespace and we need a host-wide view to find what's running.

Package cli — `forge cluster logs` command.

Streams kubectl logs for one or all services in the dev namespace. Replaces a small bash recipe (resolve namespace, look up the right label selector for a service deployment) that every project would otherwise hand-write.

Package cli — `forge cluster status` command.

Renders a human- or machine-readable snapshot of the dev cluster, running pods, and ingress URLs derived from rendered KCL. Replaces a 30-line bash recipe every k8s-targeting forge project would otherwise hand-write.

Package cli — `forge cluster urls` command.

Reads the rendered dev-env KCL and prints the ingress URL table — one row per HTTPRoute/GRPCRoute, grouped by gateway + listener. Lets users (and sub-agents) discover "what URL do I hit" without reading deploy/kcl/dev/ingress.k by hand.

Package cli — `forge env devstack` command tree.

The parallel-dev-stack primitives (ADR 0003) live in internal/devstack: the raw git facts pushed into KCL as options, and the memoized forge.allocate_port(base, key) block allocator. Those primitives are resolved INSIDE a KCL render (under the up/deploy activation path). But a host launcher — a Taskfile target, a bootstrap script — needs the SAME allocated host port BEFORE `forge env up` renders the KCL, so it can start the host `reliant` process LISTENING on exactly the port the in-cluster controller will dial.

`forge env devstack port <base>` is that single source of truth: it resolves the current worktree key (devstack.Worktree) and returns allocate_port(base, key) — base + block(key)*100 — through the SAME lock-guarded block registry (.forge/blocks.json) the KCL builtin uses, so the launcher and the render can never disagree on the port. On the PRIMARY checkout the key is "" ⇒ block 0 ⇒ the base is returned unchanged (no registry/lock touch), so the default dev loop is byte-identical to today.

`forge project disown <path>... --reason <text>` — one-way ownership transfer.

The file lifecycle has exactly two states and one door:

• forge-owned (Tier-1): regenerated on every `forge generate`; hand-edits are a hard drift error.
• user-owned ("yours"): never touched after emission.
• `forge project disown` is the one-way door from the first to the second.

There is deliberately NO fork limbo (forked-but-maybe-reconciled- later). A fleet-wide audit of every long-lived fork found zero that were justified — each was a bug, a missing API, a mis-tier, or staleness — while the limbo state produced the worst incidents (silently frozen wire_gen.go). Disowning is final by design; the documented re-adoption path is equally simple: delete the file and run `forge generate` — the emitter re-emits the pristine render and the entry returns to Tier-1.

--reason is REQUIRED. A disown means the generated code couldn't express what the user needed — that's design feedback, and the reason is the payload. It is recorded per path in .forge/disowned.json; `forge project audit --json` joins it back onto each disowned_files row.

`forge project disown <path>... --absent --reason <text>` — decline a scaffold-once file: forge never writes it in this project.

WHY. A scaffold-once file is yours from birth, and deleting it is the ordinary way to say "not this one": the birth ledger records the birth, so "recorded + absent" reads as deliberately absent and forge leaves it so. That only works for a birth that SURVIVES its run. Reliant moved its cobra tree to cmd/reliant/cmd/, forge scaffolded serve.go there, serve.go's presence switched internal/app composition on, composition failed on 104 missing providers, and the rollback removed serve.go together with its birth record — correctly, since a record for a file the rollback deleted would have consumed the path's only birth. Every later generate repeated the cycle, so there was never a record to delete the file against; the only way out was hand-writing JSON into .forge/scaffolded.json.

So declining is a first-class, declared act: a ledger entry carrying the reason (ScaffoldEntry.Declined), written by this command OUTSIDE generate. Every scaffold-once writer already asks the ledger before a birth (checksums.ScaffoldOnceDecision), so the decline is honored everywhere with no list for a writer to forget, and a failed generate — whose rollback restores the ledger to its pre-run bytes — keeps it.

Why the ledger and not a forge.yaml list: forge.yaml declares what the project IS, and scaffold ownership is already the ledger's subject — a second list in forge.yaml would be a second answer to "may forge write this path?", consulted by some writers and not others. The ledger is committed and human-readable, so the decline is still a reviewed line in a file under version control; this command is the safe way to write it.

Why `disown`: it is already the verb for "this path is mine, forge keep off". Without --absent it takes a forge-generated file as it stands; with it, it takes a scaffold's absence.

Package cli — Docker daemon reachability preflight for the cluster phase.

Every k3d operation IS a docker operation: k3d nodes are containers, the k3d registry is a container, the cluster network is a docker network. When the daemon is unreachable, each downstream shell-out fails on its own timeout with its own idiosyncratic wording — `k3d cluster list` reports "runtime failed to list nodes: ... 500 Internal Server Error", `docker build` reports something else again — and the user reads N cryptic cascading failures instead of one true cause.

Docker reachability is a genuine PRECONDITION of the cluster phase and it is cheap to test, so it is tested up front. This mirrors the argument the doctor tool checks make in their own package doc: surface the gap before the failure cascades.

The eager probe also SAVES wall-clock in the failure case. Docker Desktop's host-side apiproxy sits in front of a VM; when the VM is gone the proxy keeps dialing and only surfaces a 500 after its own ~20s deadline, once per call. One bounded probe replaces that repeated stall.

Package cli — `forge doctor` Docker daemon HTTP(S)-proxy check.

When the Docker daemon is configured with an HTTP/HTTPS proxy, ALL container egress — including image pulls and registry TLS handshakes — is routed through that proxy. A well-behaved forward proxy tunnels the registry's CONNECT request straight through and pulls work fine. But a TLS-intercepting proxy (Proxyman, Charles, mitmproxy, a corporate MITM box) terminates the CONNECT and re-originates TLS with its own cert. The container runtime, which has no trust path to that cert, sees the pull fail mid-stream — surfacing as ImagePullBackOff, "unexpected EOF", or "connection reset by peer" on the image layer. The proxy is invisible to the user (Docker Desktop silently inherits the macOS system proxy, commonly `http://http.docker.internal:3128`), so the failure is notoriously hard to trace back to its cause.

Doctor surfaces the proxy as a WARN, not a fail: a proxy can be perfectly legitimate (a transparent corporate egress proxy, a pull- through cache). We can't tell from `docker info` alone whether it intercepts TLS — only that one is present and that, IF it does, image pulls will break in a way that looks like everything except a proxy. The message names the symptom and the fix so a user staring at an ImagePullBackOff can connect the two.

The decision core (dockerProxyCheck) is pure — it takes the already- extracted proxy strings — so unit tests cover every branch without shelling out to docker.

Package cli — `forge doctor` external-builds checks (Phase 3 of the build_cmd refactor).

For every KCL service whose Service.BuildCmd is non-empty doctor emits three observations:

• warn when the resolved build_cwd (or projectDir when BuildCwd is unset) is missing on disk. Build-side semantics already skip-with-warn at run time; doctor surfaces the gap up-front so the user can fix it before invoking `forge build`.
• warn when the first token of BuildCmd (split on whitespace, take index 0) isn't on PATH. Heuristic — skipped when the command opens with `cd ` or contains a `KEY=value` env-var assignment, because those need a real parse pass that's out of scope for v1.
• info recording the substituted BuildCmd against a synthetic Spec, so the user can spot ${X} substitution errors before running build.

All three observations live under one doctor check per service (Name="external-build: <service>") so the report stays compact even for projects with many external-build services. The check status rolls up: any warn beats pass; the heuristic-skipped paths still emit the info line so the substituted command is always visible.

The decision core (buildExternalBuildDoctorChecks) is pure — it takes the resolved KCL service set + a PATH lookup function + a stat function. Production passes exec.LookPath / os.Stat; unit tests pass map-backed stubs. Mirrors doctor_tools.go's seam.

Package cli — `forge doctor` ingress checks (Phase 4 of the Gateway API ingress refactor).

Two new check categories layered on top of the standard doctor signal-based checks:

• GatewayClass present — for each unique gateway_class_name declared across every env's rendered KCL, verify a matching `GatewayClass` resource exists in the active cluster context.
• cert-manager ClusterIssuer present — for each Gateway with tls.cert_issuer set in any env's KCL, verify a `ClusterIssuer` resource with that name exists.

Both checks are best-effort observation: they degrade to "skipped" with a clear reason when kubectl isn't on PATH, the cluster isn't reachable, the CRD itself isn't installed, or KCL can't be evaluated. Doctor must never fail-loud on environmental gaps the user hasn't fixed yet.

The cross-check logic is factored into a pure helper (buildIngressDoctorChecks) that takes already-collected class / issuer names plus a kubectl-resource-checker interface, so unit tests can exercise every status outcome without a live cluster.

Package cli — `forge doctor parity <svc>` subcommand.

Detects when a service's effective env+config diverges between host-mode (`forge run <svc>`) and cluster-mode (`forge env deploy <env>`) projection — the "local wasn't representative of prod" class of bug that surfaces as a deploy failure on Friday afternoon.

The check is static: we compute what each mode WOULD see by composing the same inputs the real loaders compose (forge.yaml environments[<env>].config + KCL host env_vars on the host side; KCL cluster env_vars on the cluster side), then diff. No process is spawned, no manifest applied, no Secret read — just a structured report of where the two modes disagree.

Three categories of divergence:

1. value_mismatch — same key set on both sides with different inline values. Always a bug (exit 1).
2. missing_in_<side> — key set in one mode, absent in the other. Bug (exit 1) UNLESS the cluster side projects from a Secret (host's secrets_file is the documented counterpart but we don't load it — see secret_channel_divergence below).
3. secret_channel_divergence — same key is sourced from secrets_file on host and `secretRef` on cluster (or one side references a ${SECRET_REF} placeholder). EXPECTED — the channels differ by design. Reported so the model can verify the key names line up, but does NOT fail the exit code.

The diff core (diffParity) is pure: it operates on two side-input structs the cobra path assembles from real loaders and tests assemble in-memory. Filesystem touches stay in the cobra path.

Package cli — `forge doctor` host-tool checks.

Forge shells out to a handful of third-party binaries (kcl, kubectl, docker, go, buf, k3d, git, npm, mkcert, ...). When one of those is missing the user sees a cryptic `exec: "kcl": not found` from wherever the binary was first invoked — usually deep inside a multi-phase pipeline that has already partially run. Doctor's job is to surface the gap up front with an OS-specific install hint so the user can fix the toolchain before the failure cascades.

The check decision core (runToolChecks) is pure: it takes function values for "is binary on PATH" and "run version command" so unit tests cover every status branch without exec-ing real processes.

The set of tools required for a given project depends on which `features.*` blocks are enabled (deploy needs kcl + kubectl; frontend needs npm; ingress with mkcert TLS needs mkcert host-side; etc.). Each toolCheck carries a Required(cfg, projectDir) predicate so the report skips tools the project doesn't actually use rather than emitting "missing optional tool" noise.

Package cli — `forge env`: the environment noun.

File: internal/cli/env_render.go

`forge env render <env>` — print the Kubernetes objects an environment renders, and the cluster each one lands on, without touching a cluster.

The question this answers is "what does this environment actually own", and until now forge had no way to ask it. `kcl run` on a real project fails, because a forge project's KCL calls kcl_plugin.forge.* and only forge registers that namespace. `forge doctor` renders every environment internally and then reports a COUNT ("5 env(s), 341 manifest(s)") — the objects it read never leave the check. `forge env deploy --dry-run` does print manifests, but it is the deploy command: it resolves a kubectl context, runs the declared-cluster guard, may stand up a k3d cluster and push images, and refuses outright when the recorded build is behind HEAD. None of that is available to someone who only wants to LOOK.

So the answer got reconstructed by hand, and the reconstruction is where the damage happens. An audit of which objects an environment owns read 1,886 lines of KCL and inferred each workload's target lexically — HOST from the presence of a `host = forge.HostOverrides` block, cluster from a per-service `k8s = K8sOverrides{cluster = ...}` override a thousand lines further down. One misread there deletes the wrong object out of the wrong cluster.

CLUSTER ATTRIBUTION is therefore not decoration, it is the point. An environment renders ONE manifest stream but may deploy it to SEVERAL clusters (control-plane's dev puts most workloads on k3d-control-plane and workspace-proxy on k3d-cp-daemon), and which document goes where is decided by internal/cluster.ScopeManifestsToGroup at apply time. This command calls THAT function, one document at a time, rather than modelling its rules again — a printer that disagrees with the router would describe a deploy that never happens, which is the failure mode it exists to prevent.

SIDE EFFECTS: forge cannot promise this is a pure read, and does not. KCL's `file.write` runs during evaluation, so a project whose deploy KCL generates a file (control-plane's dev main.k calls `nats.write_conf`, which materialises deploy/nats/nats.conf) writes it every time anything renders — `forge doctor` and this command included. forge has no hook to suppress a project's own writes: the write happens inside the embedded KCL runtime, which offers no read-only mode, and the alternatives (rendering from a copy of the tree, sandboxing the process) are neither portable nor cheap. What forge CAN do it does: it reverts its own render-state writes (the resolve_port store), and it watches the tree so the report is evidence rather than a promise. See renderWriteScan.

File: internal/cli/env_render_charts.go

Platform dependencies (forge.HelmChart) in `forge env render`.

A chart's objects are not in the env's KCL stream: KCL only DECLARES the chart, and `forge env deploy` expands it with `helm template` at apply time (internal/cluster.renderSelectedCharts). So a render that printed only the KCL stream showed 0 objects for flux, cert-manager and envoy-gateway while the deploy applied hundreds — the render was not a preview of the deploy, and no command could show a chart's manifests without contacting a cluster.

The fix renders charts through the deploy's OWN function (cluster.RenderChartStreams wraps renderSelectedCharts), with the deploy's own spec resolution (resolveDeployHelmSpecs: target selection, the declared- cluster refusal, the pinned CRD bundles) and the deploy's own choice of the cluster a chart without `cluster` lands on (helmPrimaryContext). Nothing here models what a chart renders; it only labels and attributes it.

File: internal/cli/env_shape.go

`forge env shape <env>` — the env's rendered DECLARATION, as a value.

This is the projection half of `forge env render`. Where render prints the manifests themselves — two megabytes of YAML for control-plane's prod — this prints what they ARE: the env's kind, what runs where, which secrets it needs, which domains it binds, and one hash per object. Small enough to store per environment, read per view, and diff as a set.

WHY IT IS A COMMAND AND NOT ONLY AN INTERNAL STEP. Three callers need the same answer, and all three must get the same bytes:

• `forge env build` and `forge env deploy` RECORD it on the control plane, which is what lets the Live view answer "what kind, which secrets, which provider" with no checkout and no daemon running;
• the reliant daemon exposes this command as `forge.env_shape`, which is what Preview's "Register" sends to EnsureEnvironment to bootstrap an env the control plane has never heard of;
• F7's `forge env diff` compares this projection against the recorded one.

They share internal/bundle.ProjectShape, so a shape a user read, a shape the control plane stored, and a shape a bundle sealed cannot disagree about the same render.

READ-ONLY, AND WATCHED RATHER THAN PROMISED. Like `forge env render`, this cannot guarantee purity — KCL evaluates `file.write` during evaluation and forge has no hook to suppress a project's own writes. So it does what render does and goes one step further: it scans the tree before and after, and a render that wrote anything is an ERROR naming the paths, not a warning. A caller registering an environment from this output is making a durable record, and a record derived from an impure render is a record nobody can reproduce.

Frontend source resolution — the bridge between a DECLARED cross-repo source and a directory a build can shell into.

A frontend declares its code one of two ways: a `path` (a directory in this repository) or a `source` (another repository, pinned to a ref). Every command that shells into a frontend — build, deploy, install, typecheck — needs a real directory, so this file resolves the second form to the first and leaves the first untouched.

The design constraint that shapes everything here: existing projects must be byte-identical. A project with no `source:` anywhere never constructs a resolver, never touches the cache, and never changes behavior — resolveFrontendSources returns immediately when nothing declares a source.

See internal/gitsource for the cache, the fetch, and the .forge/source-overrides.yaml local-override rules.

Frontend discovery for the CI workflow generator.

CI workflows need one fact about frontends: which directories in THIS repository hold a Node app, so the workflows can point setup-node at a package.json and run npm there.

That fact used to be read from forge.yaml's `frontends:` key. The key is retired — frontend topology moved to deploy/kcl/<env>/main.k, and `forge generate` strips a leftover block rather than honouring it — so the read silently returned an empty list on every real project. Empty meant HasFrontends=false and FrontendPath="", which the templates render as "no frontend jobs at all". Because the CI workflows are write-once scaffolds, nothing overwrote the stale blocks a previous forge had emitted while the key still existed, and the workflows froze pointing at whatever the frontend was called then. A rename (control-plane's admin-web → internal-console) left `frontends/admin-web` in e2e.yml, e2e CI broke, and no amount of regenerating could fix it: forge was reading a key that is always absent. The hand-edit that unbroke CI then failed the Tier-1 self-certification guard forever.

So discovery reads the KCL, the same source `forge build` and `forge env deploy` resolve a --target against.

Marker-driven stale-artifact cleanup.

Forge's pre-2026-06-05 cleanup walked generated-artifact directories and removed anything whose name didn't match a re-derived "expected" set computed from forge.yaml — and deleted user code when the re-derivation disagreed with on-disk snake_case proto layouts. The manifest era fixed that by deleting only manifest-recorded paths; the self-certifying era keeps the same safety property without the manifest: only files that carry a forge:hash certification marker are candidates. The marker IS forge's authorship record, embedded in the file itself — paths without one are user content and forge doesn't get to delete them.

A candidate is a marker-bearing file the current run did NOT re-emit (per the WrittenThisRun set). Guardrails before deletion:

• Owner-step gate. The tier1OwnerRegistry in generate_tier1_scope.go maps generated paths back to the step that emits them. A path whose owning step is gated off this run is left in place; that step wasn't going to write it regardless, so missing-from- WrittenThisRun is uninformative.
• Upgrade-managed paths. `forge project upgrade` is their emitter; `forge generate` deliberately leaves them alone.
• Scaffold-once paths. A path in the scaffold ledger is the user's, marker or not.
• Verification. A PRISTINE marker (certified machine output) is deleted: those bytes are exactly what forge rendered, so nothing of the user's goes with them. A file whose marker fails verification was hand-edited — the bytes are the user's now, so it is reported and kept unless --force-cleanup asks for it too.
• Disowned paths are never candidates.

Deletion is the default because a report nobody acts on leaves a stale file in the build: a factories test for an entity forge no longer generates keeps compiling against helpers that are gone, and the only way out used to be a flag --help did not show. Every delete is journaled, so a run that fails later rewinds it; and the sweep runs only in a full pipeline (no --steps preset or --templates-only run includes it) after every emitter, so "not written this run" means no emitter writes the path any more. The caller (stepCleanupStale) skips the sweep when a step failed as a warning: that step's outputs are unwritten for a reason other than staleness.

Scoped-fallback entries (.forge/hashes.json, comment-incapable formats) get the same treatment keyed off the recorded hash.

Config vs. filesystem cross-check — the "loud-by-default" guard.

Pre-2026-06-07 the generate pipeline silently skipped declared entities that had no on-disk backing, and silently ignored on-disk entities that weren't declared in forge.yaml. The asymmetry was the #1 source of "I added a service but generate did nothing" friction:

• forge.yaml declares services[].name=foo but proto/services/foo/ doesn't exist → generate runs, emits nothing for foo, exits 0.
• proto/services/foo/ exists on disk but forge.yaml lacks an entry → generate sees the proto but skips bootstrap wiring for it.

This file walks forge.yaml's declarations and the on-disk trees in parallel and collects every mismatch into a single batched report. stepLoadConfig calls validateConfigVsFilesystem after a successful LoadProject so the user sees the asymmetry the moment they run generate, not three steps deeper at a confusing "missing import" error.

Only what forge.yaml still DECLARES can be cross-checked here. Services and internal packages are discovered from their real sources, so there is no second list for them to disagree with — the declaration is the code.

Opt-out: --skip-config-check. We expose an opt-out (not opt-in) so the default path is loud — new adopters get the check unconditionally, and scripted callers in pathological setups (e.g. mid-migration where a proto dir exists transiently with no forge.yaml entry yet) can pass the flag to bypass without changing the steady-state default.

Reporting for contract_test.go scaffolds forge declined to write.

contract_test.go.tmpl emits exactly one call — `_, err := pkg.New(pkg.Deps{})` — which compiles only for the canonical single-`Service`, two-result-`New` package. Three package shapes are therefore declined rather than scaffolded, because writing the file anyway hands back a package that does not build.

Each decline used to print its own line, unconditionally. In control-plane that was ~25 lines on every run, describing 25 packages whose shape is a deliberate choice and is not going to change. They split into two kinds, and the two deserve opposite treatment:

• A multi-interface package, or one whose interface is not named Service, is simply a package forge does not scaffold tests for. There is no advice in it — "write tests manually" is what the author is already doing. ROUTINE: behind -v.

• A single-result `New` is different: `func New(Deps) (Service, error)` IS the shape forge's own conventions ask for, and polishing to it turns the auto-scaffold back on. That is real advice, so it survives at default verbosity — but as ONE line with a count, not one line per package. The per-package list is what -v is for.

The distinction that keeps this honest: a line stays at default verbosity when acting on it CHANGES something. "This package has two interfaces" does not; "these four packages would get scaffolded tests if you polished their constructor" does.

Disowned-sibling dangling-reference detection.

FRICTION 2026-06-04 (cp-forge layer-6 workers lane, fork era): the user had frozen `pkg/app/bootstrap.go` and `pkg/app/wire_gen.go` out of regeneration. After adding a worker, `forge generate` happily re-emitted `pkg/app/app_gen.go` — and the freshly regenerated `app_gen.go` declared `Workers *Workers`. But the `Workers` TYPE was defined inside the frozen `bootstrap.go`, still at its pre-workers content. `go build` then failed with `pkg/app/app_gen.go:42:13: undefined: Workers` — a silent build break far from its cause.

The same hazard exists for DISOWNED files (the frozen-file mechanics are identical: forge never re-emits them, even with `--force`), so the check survives the fork removal with disowned entries as its subject. Resolution: after codegen finishes, scan the regenerated forge-owned Tier-1 files inside the same package as any disowned sibling. For each referenced package-local type name that is NOT defined in either

• the file doing the reference, or
• any forge-owned sibling in the same package, or
• any disowned sibling in the same package,

surface a loud, actionable error listing the type, the call site, the disowned sibling that probably ought to have defined it, and the concrete escape hatches (hand-add the missing declaration to the disowned file — it's yours — or re-adopt it by deleting it and re-running `forge generate`).

The scan is restricted to the same Go package as the disowned file because that's where Go's package-local resolution applies — a dangling unqualified type name `Workers` in `app_gen.go` can only be resolved by a sibling .go file with the same `package app` clause. Cross-package references (e.g. `foo.Workers`) are qualified and would be flagged by `go build` with a different error class; they're out of scope here.

Per-file extension-point hints for Tier-1 drift.

When the stomp guard catches a hand-edited Tier-1 file, the worst thing the error can do is lead with `forge project disown`: agents take the path of least resistance, disown the file, and permanently lose regeneration (the failure chain this whole subsystem exists to prevent). The right answer is almost always "your customization has a designated user-owned home" — these hints name that home, per file shape, so the error message teaches the extension point first and the disown one-way door last.

── Why the hint must be TOTAL ────────────────────────────────────────

An audit of every disown in the fleet found ZERO that were deliberate, permanent ownership choices. Every one was a forge gap wearing an ownership hat: a missing extension point (the whole Connect interceptor / CORS / extra-route edge has no user-owned surface at all), a migration shield, or a gap that has since been closed and left the disown behind as dead weight.

The mechanism that produced that outcome is this function returning "". A blank hint reads as "forge has no opinion, do what you like", and the only remedy left on screen is the one-way door. So the hint is TOTAL: every Tier-1 path resolves to exactly one of two answers.

SEAM EXISTS  → name the user-owned file and the hook. Editing the
               generated file is simply the wrong move.
NO SEAM      → say so, in those words, and name the seam that is
               missing. A file with no extension point is a FORGE
               DEFECT, not a project problem; the user's next action
               is to report the named gap, not to quietly fork.

The NO-SEAM branch is the feature that replaces `forge project disown`. Disown's real payload was always the `--reason` string — the design feedback saying "forge could not express this". Naming the gap at the moment of friction captures that payload without also suppressing regeneration forever.

Fresh-render rescue for the Tier-1 stomp guard.

The guard reports a Tier-1 file as hand-edited when its bytes disagree with forge's record of them: the embedded forge:hash marker, or for a comment-incapable output (JSON) its .forge/hashes.json entry. That record can be stale while the bytes are exactly forge's own render:

• `forge generate` killed during "Validating generated code" had already rewritten three observability dashboards, but saves hashes.json only at the end of a run. The next generate refused all three as hand-edited Tier-1 files.
• A merge that takes one side's generated file and the other side's ledger, or merges a stamped file's body under one side's marker.

Forge must never let its own outputs and its record of them disagree in a way that blocks the next run. Writing the ledger earlier only narrows the window, and does nothing for a merge. Comparing against the truth does both: the guard quarantines each in-scope drifted path (its writes go to a side render, the on-disk file is untouched), every emitter runs, and stepAdjudicateTier1Drift — after the emitters, BEFORE validation, so a run that will fail does not pay for a build first — re-records every file whose bytes are this run's render (checksums.RescueFreshRender). Only what is left is a hand-edit, reported exactly as the guard used to, and the run rolls back.

The cost is rendering, which is cheap beside validation: a run with a genuine hand-edit now renders before it reports, where it used to stop at the guard.

Package cli — `forge generate --explain` provenance log.

Explain mode runs the normal generate pipeline and then prints a per-file traceability log: for each forge-tracked output, which source files / proto descriptors / contract.go inputs drove its generation, plus a "reason" field saying whether the file was rewritten or skipped because the input was unchanged.

Implementation choice: rather than instrument every individual generator (mock_gen, middleware_gen, crud_gen, …) with a callback, we read the post-generate state from forge_descriptor.json, the project filesystem, and the embedded forge:hash markers. The derived provenance is "approximate but useful" — exactly what the LLM caller wants. We can tighten it later by threading a callback through the codegen package, but we don't need to pay that cost up front to ship the most-useful 80%.

`forge generate --explain-drift` — show what regeneration would change before the user picks an escape hatch.

The Tier-1 stomp guard knows a file drifted (hash mismatch) but only has hashes for prior renders, not content — so it can't show the user WHAT changed. The actionable comparison is on-disk content vs a fresh render of the *current* templates: that diff is simultaneously "what did I hand-edit" and "what would --force destroy".

Mechanism: instead of aborting at the guard, --explain-drift marks every drifted path side-render-only (checksums.AddSideRenderOnly) and lets the pipeline proceed. The emitters render normally, but writes for drifted paths land at .forge/render/<path>; the user's on-disk content and the checksum entries stay untouched (the entries are snapshot-restored at the end because stepRehashTracked would otherwise re-stamp the drifted on-disk hash and silently bless the drift). After the step loop, each drifted file is diffed against its parked render via `git diff --no-index`, bounded, and the run still FAILS with the standard drift report — the flag explains, it does not approve.

Kept out of generate_pipeline.go (a parallel-edit hotspot): the pipeline file gains only the ctx fields and a three-line branch in stepCheckTier1Drift.

One-time pipeline migration off the legacy .forge/checksums.json global manifest onto self-certifying files (forge:hash markers).

The conversion rules live in internal/checksums/migrate.go. This file owns the pipeline integration:

• stepMigrateLegacyManifest runs between state load and the Tier-1 stomp guard. Pristine legacy entries get stamped; disowned ones convert to .forge/disowned.json; entries whose bytes match NOTHING the manifest recorded (kalshi fr-9a54388f0b: a manifest committed from a different work lane) are quarantined on ctx.LegacyUnverified with their writes side-render redirected.
• finishLegacyMigration runs after the step loop: each quarantined path whose fresh side render matches the on-disk bytes is proven pristine and stamped; everything else is stamped with the unverified-legacy sentinel and reported through the standard drift error (guard semantics: --force regenerates exactly the named files, `forge project disown` keeps them).

The legacy manifest is deleted by the migration itself — durable even when the run later aborts. The unverified sentinel keeps the guard honest across runs until the user resolves each file.

Missing scaffold-once artifact reporting.

FRICTION (measured dogfood run, 2026-07): an agent scaffolded a project, reviewed the born migrations, and correctly found three real schema defects in them (a nullable column that should be NOT NULL, an FK with no referential action, an index whose column order did not match the query). It fixed all three. That corrected schema invalidated the fixtures in the already-born internal/handlers/library/handlers_crud_test.go, whose literals were derived from the schema AS IT WAS AT BIRTH.

So it deleted the file, expecting `forge generate` to re-derive it against the schema as it now stood. Generate did not — correctly, because the birth ledger records that forge has already scaffolded that path and deleting a scaffold is an act of ownership (see internal/checksums/scaffoldledger.go). But generate also said NOTHING. It printed its success banner over a project that had silently lost a test file, and the author spent roughly fourteen further tool calls and an hour trying to reproduce the birth condition by hand — copying the project to a scratch directory, stripping the CRUD rpcs out of the proto, deleting db/migrations, deleting the handler directory — none of which could work, because the one thing that brought the file back was an edit to .forge/scaffolded.json that nothing in forge's output had ever named. That edit is now a command, `forge project rescaffold <path>` (rescaffold.go), and this notice names it.

The bug is not the suppression. The suppression is the feature, and this file does not touch it: forge still never resurrects a file the user removed. The bug is that the suppression was INVISIBLE, and an invisible correct decision is indistinguishable from a malfunction.

So generate now reports it, once per absent path, naming the FILE and the exact ACTION that restores it. Deliberately GENERAL over the ledger rather than special-cased to the CRUD lifecycle test: forge scaffolds many one-shot files (internal/app/auth.go, cmd/<bin>/main.go, the frontend pages, the per-RPC handler stubs), every one of them can be deleted for the same reason, and a check that knew only about handlers_crud_test.go would be overfitted to the single instance that happened to be measured.

It is a NOTICE, not a warning, and it does not route through warnOrFail: an intentionally deleted scaffold is a supported end state — the author who does not want forge's lifecycle test removes it and is done — so this must never be promotable into a --strict failure that punishes a project for a legitimate choice. What the author needs is the sentence they could not find, not a build that stops.

Package cli — typed step plan for `forge generate`.

Pre-2026-05-06, runGeneratePipeline was a 584-line procedural function holding 25 numbered ordered steps gated by 93 Features.*Enabled() checks. New steps were 30 lines of boilerplate appended to a numbered-comment sequence (Step 0a, 0b, 0b.1, ..., 8d-iii, 8f.1) — the numbering itself pleaded for a data structure (FORGE_REVIEW_CODEBASE.md Tier 1.1).

This file replaces that procedural blob with a typed []GenStep plan. Each step is a small named function operating on a shared pipelineContext. The pipeline becomes a loop over the slice that:

• calls step.Gate(ctx) — pure, side-effect-free predicate; false skips
• calls step.Run(ctx) — the action, returning an error to abort

The shape unblocks several downstream wins documented in the codebase review:

• --plan / --explain print the plan without executing it
• a watch loop re-runs only steps whose Tag matches changes
• per-step unit tests against a synthetic pipelineContext
• one-time parse of services/entities into ctx (avoids re-parsing ParseEntityProtos 3× — see Tier 2.5)

As of 2026-05-07 the entire pre-refactor pipeline is now flat: every numbered legacy step has a dedicated stepXxx entry below, and runMidPipelineLegacy is gone. The single remaining shared-state hop (parse services + module path once for steps 4-6) is its own GenStep.

(2026-05-06 polish-phase, completed 2026-05-07) — closes FORGE_REVIEW_CODEBASE.md Tier 1.1.

`forge generate --plan` and the loud-by-default helpers.

The plan mode complements --explain (provenance log after the run) and --check (drift detector that runs the pipeline) by inspecting the pipeline WITHOUT running anything: it prints the step list with a [RUN] / [SKIP] annotation per step, derived from each step's Gate(ctx) against the configured project state, then exits.

This is the diagnostic that answers "what would forge generate do here?" without the side-effects of actually doing it — useful when planning a big refactor, debugging "why didn't generate touch X?", and writing CI guards that need to know whether a pipeline change would alter the step set for a given project shape.

The warnOrFail helper lives here too because it shares the loud-by- default thesis: a step that routes its failure through it lets the run continue with the steps that do not need it, and the run still exits non-zero; --strict stops the run at that step instead.

Rename detection for Tier-1 Go emitters.

FRICTION 2026-06-02 (cp-forge dogfood pass): when `forge generate` renames a public symbol in a Tier-1 Go file (e.g. `db/embed.go` flipping `var Migrations` to `var MigrationsFS`), hand-written callers elsewhere in the project keep referencing the old name and the build breaks two runs later — long after the codegen step that did the rename has scrolled out of the user's terminal.

Resolution: a two-step pre/post pass around the codegen body of the pipeline. Pre-codegen we snapshot the public exports of every tracked Tier-1 Go file; post-codegen we re-extract exports from the freshly written files and diff. Names that disappear are candidates for stale references — we grep the project (skipping generated files and the renamed file itself) for `pkg.Name` and `Name` patterns and surface each call site as a warning.

The warnings are advisory by default. Future work: --strict-renames converts them to a hard pipeline error.

Auto-retire obsolete disowns.

`forge project disown` is a last-resort one-way escape hatch: it tells forge "stop regenerating this Tier-1 file, the bytes are mine now". Needing it routinely means a missing extension point. A disown that has become OBSOLETE — forge no longer Tier-1-owns that path — is dead weight: it protects against an overwrite that can no longer happen, and it misleads users into thinking disown is normal.

The canonical case: a project disowned a frontend page.tsx under an OLD forge that regenerated page.tsx as Tier-1. The current forge makes page.tsx Tier-2 (scaffold-once: written if absent, NEVER overwritten). The disown is now meaningless — forge would never overwrite a Tier-2 file anyway — yet it lingered across version migrations and had to be hand-dropped.

THE FIX: during `forge generate`, after every Tier-1 emitter has run, detect disowns whose path is NO LONGER a current Tier-1 emit target and auto-retire them (remove from .forge/disowned.json) with a loud per-path notice. A disown is:

• STILL VALID when its path IS a current Tier-1 emit target — forge WOULD regenerate it but for the disown. The target set (checksums.Tier1TargetSet) records every path a Tier-1 writer touched this run, BEFORE the disown-skip, so a disowned-but-live Tier-1 path is still in the set. Leave it alone.
• OBSOLETE when its path is NOT a current Tier-1 emit target — it became a Tier-2 scaffold-once file, or forge stopped emitting it. Retire it.

Conservatism: a disowned path can be absent from the target set for a reason unrelated to tiering — the emitter that WOULD own it was gated OFF this run (e.g. a frontend file under features.frontend=false). In that case absence is uninformative and we must NOT retire. The `targetable` predicate below gates retirement on "an emitter that could own this path as Tier-1 actually ran this run", so a gated-off subsystem never sheds its legitimate disowns.

What a binary serves is CODE, not config.

The serving decision lives in the user-owned pkg/app/services.go: RegisteredServices lists one generated serviceRow<X> call per service this binary serves. forge scaffolds that file once (listing every current service — zero semantic change for existing projects) and never rewrites it; from then on the row list is the single source of truth, and this file derives the served-set from it by AST-parsing the registration file (the same user-file-parsing posture as codegen.ParseServiceDeps and the setup.go scans).

Classification per service (see serviceRegistry.state):

REGISTERED — a serviceRow<X> identifier matching the service is
  referenced in services.go. Full treatment: handlers scaffold,
  CRUD/mocks, wire/diagnostics,
  auth-middleware skip-list, bootstrap row (via the user's list).
UNLISTED — the service name appears NOWHERE in services.go. Treated
  as newly added (forge scaffold service / hand-edited forge.yaml): the
  handlers scaffold and row constructor still generate so the user
  can implement-then-register, but the service is NOT served — no
  auth skip-list entries, `forge env up` skips it, and
  `forge project audit` warns that the row constructor is unreferenced.
  The registration line is written by the USER (or their agent) —
  forge prints it but never edits the file. That's the design: the
  LLM writes the one decision line; forge generates the guardrails.
TOMBSTONED — the service name appears in services.go only in a
  comment (the scaffold instructs: delete the row, leave a comment
  naming the binary that serves it). Types-only: proto types,
  Connect client, frontend hooks, and descriptor entries still
  generate (callers need them); the handlers/<svc>/ scaffold, row
  constructor, wire/diagnostics, and auth registration
  are gated off. The comment is load-bearing — without any mention
  the service reverts to UNLISTED and its scaffold regenerates.

Fallbacks: a missing services.go means "everything registered" (pre-migration projects keep today's behavior; the generate pipeline then scaffolds the file with exactly that meaning). A services.go that does not PARSE is a hard error in the generate pipeline (the build would fail anyway; better to name the file) and fail-open (everything registered) for read-only commands like audit/graph, which must not die on a broken tree.

Retirement of a pre-existing handlers/<svc>/ scaffold reuses the manifest-driven stale sweep (generate_cleanup.go): the gated emitters stop writing the tracked Tier-1 files, so they fall out of WrittenThisRun and are removed (the hand-edited ones only under --force-cleanup); Tier-2 user-owned files in the same dir are never candidates. `forge project audit` surfaces both halves via the codegen category's unregistered_services finding.

`forge generate` step: retire previously delivered agent skills.

Forge never writes skills into a project. Reliant reads forge's skills straight from the binary (`forge skill list|search|load`), and an on-disk render is a second, staler copy that can shadow the live catalog. Older forge versions did render `.claude/skills/<flat>/SKILL.md`; this step removes those forge-owned copies on the next generate. It never deletes a user-authored or user-modified file (see gcRetiredAgentSkills).

Harnesses without reliant's binary-backed catalog get a thin pointer skill (.claude/skills/forge/SKILL.md) written once by `forge project new`. It carries no banner or hash marker, which is what keeps this sweep from treating it as a retired render.

This sweep can be deleted once no project is likely to still carry delivered copies from a pre-retirement forge.

Stale scaffold-test detection.

FRICTION (front-door P0, 2026-06): the scaffold proto explicitly instructs renaming Item to the real entity. Following that instruction leaves handlers/<svc>/handlers_scaffold_<rpc>_test.go — ONE-SHOT, user-owned file rendered from internal/templates/service/unit_test.go.tmpl, never regenerated, no checksum entry — referencing deleted pb types (pb.CreateItemRequest, …). `forge generate` succeeds because the final validate step is `go build`, which does not compile _test.go files; the user then hits an immediate `go test` / `go vet` failure pointing at a file forge wrote, with no hint that the file is theirs to fix.

Resolution: NO auto-regen of user-owned files. After codegen has refreshed gen/, scan each handlers/<svc>/handlers_scaffold_*_test.go (and only those — keep scope tight), resolve its `pb "<module>/gen/…"` import to the on-disk generated package, and cross-check every `pb.<Ident>` reference against the names that package actually declares. Any referenced-but-undeclared ident → one one-line warning naming the file and telling the user the file is theirs: delete it or update the rows. Default is a warning (generate still succeeds); --strict promotes it via the standard ctx.warnOrFail helper.

Tier-1 stomp-guard scoping.

The pre-pipeline stomp guard (stepCheckTier1Drift) used to fail on ANY drifted Tier-1 file the scan found, even when the current `forge generate` invocation would never re-emit that file. In multi-lane migrations that hard-failed the guard for sibling work (e.g. agent A is porting internal/proxy/ and the guard rejected because agent B left pkg/app/migrate.go drifted in a separate changeset). FRICTION 2026-06-02: cp-forge dogfood pass.

Resolution: the guard now filters drift to the set of paths whose owning emitter step would actually run for this pipelineContext. A drifted file emitted by a step whose Gate returns false this run is silently ignored — that step wouldn't touch the file, so its drift cannot manifest as a stomp.

The path → owning-gate registry is intentionally explicit (small map at the bottom of this file). Adding a new Tier-1 emitter SHOULD add an entry here so the scoping logic stays accurate; the registry is fail-open (an unmapped path falls through to "in scope" so missing entries err on the safe side of preserving the loud-fail behavior).

The registry is keyed by exact path, trailing-slash prefix, or suffix-glob (path/segment pattern with a leading '*' wildcard). The matcher walks the entries in declaration order and returns the first match, so order from most-specific to least-specific.

Tier-2 (user-owned-after-scaffold) exemption for the drift scan.

Some forge-certified files are deliberately NOT stomp-guarded even though they carry a forge:hash marker: the upgrade-managed "checksum-protected" starters (Dockerfile, Taskfile.yml, .golangci.yml, …) and the one-shot .github scaffolds. The marker's job there is to let `forge project upgrade` distinguish "still the pristine scaffold" (auto-update on version bumps) from "user customized it" (skip) — editing them is SANCTIONED, so a failed verification must not abort `forge generate`.

The probe itself lives in internal/generator (drift.go), next to Tier2ManagedPaths — the registry that defines the exemption — so that every gate that reports hand-edited generated files (this stomp guard, `forge lint`'s generated-file drift gate, `forge project audit`, `forge ci verify-generated`) reads one set and tells one story. This file is the pipeline-side handle on it.

(Historical note: this file used to flip stale tier=1 manifest entries to tier=2. The manifest is gone — the reclassification story is now: the legacy-manifest migration never stamps Tier-2-managed paths, the Tier-2 writer un-stamps reclassified pipeline outputs on their next scaffold pass, and this exemption covers the rest.)

Run-scoped verbosity for `forge generate`.

The default output of `forge generate` is PROGRESS plus things that need ACTION. Everything else is available on demand behind `-v/--verbose`, which the command already has.

The measurement that motivated this: control-plane on a clean tree, exit 0, zero files changed, printed 269 lines of which 58 were notices — 22 "Skipped internal/handlers/X/ (all handlers up to date)" lines, ~25 "Skipped contract_test.go scaffold for internal/X/" lines, and a "Preserved 15 existing CRUD page(s)" line. Every one of them reports that forge correctly did nothing, and every one of them is identical on the next run. Output that is always present carries no information: the reader learns to skim the whole block, including the two lines in it that did need an answer.

Why a package-level variable rather than threading a flag through: these lines are printed by helpers several layers below the pipeline context (generateServiceStubs, birthContractTest, writeCIScaffold), and they print to stdout via fmt.Printf rather than to a writer anyone owns. Threading a bool through every signature to reach a global stdout is ceremony around a value that is already global. The pipeline sets this once per run, under the same lock that serializes runs (generateMu plus the cross-process file lock in runGeneratePipelineFlags), so concurrent mutation is not reachable.

Package cli — `forge project introspect` command group.

Introspect surfaces "what the binary will actually register" without requiring the binary to be running. The current leaf is `handlers`, which walks the project's proto services and prints every RPC path in the canonical Connect form `/<package>.<service>/<method>`.

Use case: you wired a new service and want to confirm at a glance that every RPC will be reachable at the expected URL — catches "this service isn't wired" issues in seconds rather than via curl-debugging a running server.

File: internal/cli/kcl_eval.go

`forge kcl eval <file> [-S <path>]…` — evaluate ONE KCL file of this project and print a field out of it.

Why this command exists ¶

forge #277 made the `forge` KCL module come from the forge binary, so that the binary rendering a project IS the module version it renders against. A consequence, and an intended one, is that `kcl run` on a project file that says `import forge` cannot work: there is no dependency to fetch and no copy on disk. Nothing but forge evaluates a forge project's KCL.

That left a real gap. A project keeps plain declarative constants in library files — control-plane's deploy/kcl/lib/kata_pool.k declares the GKE node-pool inputs its build scripts need, lib/daemon_placement.k declares which cluster each env's daemon pods land in — and those files are read by scripts and tests, never deployed. `forge env render` evaluates an ENVIRONMENT into Kubernetes objects, which is not that. So there was no forge command for "evaluate this file, give me this field".

What filled the gap went around forge, which is the thing that must not happen. control-plane grew scripts/lib/kcl-forge-module.sh: make forge materialize its module into FORGE_KCL_MODULE_CACHE, dig the directory out of the cache, then run `kcl run <file> -S <field> -E forge=<dir>` — forge's own render setup, reconstructed from outside, pinned to the cache layout and the module name, and needing `kcl` on PATH that forge itself has not needed since it embedded the runtime. The same reconstruction sat in a Go test (internal/operators/shared/daemon_placement_test.go). Every one of those is a forge defect that got worked around instead of reported, and the fix is a forge command, not a better script.

Why `forge kcl eval` and not `forge env render --file` ¶

Because it is not a render of an environment, and every flag `env render` has says so. That command resolves an image tag from build state, applies digests, templates declared helm charts, and attributes each object to the cluster `forge env deploy` would apply it to — `--tag`, `--cluster`, `--kind`, `--target`, `--no-digest`, `--no-charts` are all meaningless for a library file that declares seven strings. Hanging `--file` off it would put the whole env surface in front of callers who want one constant, and would have to answer what `--cluster` means for a file with no workloads.

A `kcl` group also says the true thing about scope: the unit is a KCL file, and the group is where a future `forge kcl fmt` or `forge kcl options` belongs. `env render` remains the way to evaluate an environment.

Read-only ¶

The evaluation claims nothing. The read-only halves of the render context are armed (see armReadOnlyKCLContext): fp.allocate_port resolves keys to blocks they already hold, fp.resolve_port reads its store without writing it, and fp.write_file is disarmed. A read-only command never claims a port block (#272). KCL's own `file.write` is not forge's to suppress — see `env render`'s note on the same subject — so a file that generates a file on evaluation still does, and that is reported on stderr.

File: internal/cli/kcl_imports.go

`forge kcl imports` — print where each forge project this project's KCL imports ([forge_projects] in deploy/kcl/kcl.mod) resolves to.

A render reads an imported project's KCL from wherever go.mod resolves its module: a replace directory, a go.work use, or the module cache at the required version (internal/kclprojects). That location is a fact a person debugging a render needs ("which reliant did this import?"), and one a Go test that renders through a forge child process needs too: the child's reads are invisible to Go's test cache, so a cache-sound render test stats the imported files itself, and this is how it learns where they are.

MAX-PUBLIC-STRUCTS IS SUPPRESSED HERE, AND IT IS RECORDED DEBT, NOT A NIT.

revive counts exported structs per PACKAGE and reports them on whichever file it reaches first, which is this one. So the finding is not about the types below in particular: package cli declared 68 exported structs against a ceiling of 40 before this branch existed, and it has been over the line for a long time. Nothing added here could bring it under 40 — the 13 types this branch adds would have to become -28 — so a suppression is the only thing that makes the gate report the truth rather than attribute 28 pre-existing declarations to the commit that happened to touch the file.

The types are exported for ONE reason: they are encoding/json unmarshal targets for the JSON the sibling KCL deploy module emits, and json.Unmarshal can only populate exported FIELDS. Go requires no exported type for that, but the fields must be exported, and the house convention here keeps the type and its fields at the same visibility so a reader is not left wondering why a lowercase type has uppercase members. Verified before suppressing: none of the types this branch adds (RemoteBuild, RemoteBuildSource, ControlPlaneEntity, FrontendRuntime, BucketRuntime, FirebaseRuntime, StaticSiteCDN, CacheRule, BundleDir) is referenced outside package cli, so every one of them is package-private in practice.

THE REAL FIX IS A PACKAGE SPLIT, and this comment is the note that says so. The KCL entity schema — every *Entity, every deploy/build variant, roughly 50 of the 68 — is a self-contained JSON contract with no dependency on cobra or on any command, and it belongs in its own package (internal/kclentity or similar) that owns it. That lands package cli under the ceiling honestly and lets this directive be deleted. It is a mechanical but wide move that would bury this branch's diff, so it is deliberately not done here.

Package cli — forge KCL module migration.

A project's env main.k files `import forge`. forge supplies that module from the binary that is rendering (internal/kclvendor → internal/kclrender), so the project's deploy/kcl/kcl.mod declares NO forge dependency and the project holds no copy of the module.

Older forge versions declared it — first as an unpublished `kcl-vX.Y.Z` git tag, then as `forge = { path = "../../.forge-kcl" }` over a project-local copy — and this step migrates those projects forward: it removes the declaration (and the marker block forge maintained around it), strips the forge entry from kcl.mod.lock, and deletes `.forge-kcl/`. See docs/adr/0003-kcl-module-from-the-binary.md.

Package cli — cross-cluster kubeconfig minting (forge.KubeconfigSecret).

In a multi-k3d-cluster dev/e2e env, a workload in cluster A may need to talk to cluster B's API server. A kubeconfig with B's serverlb IP baked in goes stale every time B is recreated (k3d hands the container a fresh docker-network IP). This file mints that kubeconfig FRESH each `forge up` — resolving the endpoint at mint time, never persisting the IP — and stores it as a k8s Secret the workload mounts.

The "in-network" reachability seam is the dev/e2e path: the target's API server is only reachable by its serverlb container IP on the shared docker network. That IP isn't in the serving cert's SANs, but the container's NAME is, so the minted kubeconfig dials https://<ip>:6443 and verifies the certificate against the cluster CA as tls-server-name k3d-<name>-serverlb (see rewriteInNetworkKubeconfig — verification is never skipped). "endpoint" (prod) uses the kubeconfig's own endpoint verbatim — a stable reachable address with a valid cert.

Package cli — minting a POD-USABLE kubeconfig for any cluster forge can reach (forge defect F1b).

The sibling file kubeconfig_secret.go mints a kubeconfig by COPYING the operator's own credential for the target cluster. That works for k3d, whose kubeconfig holds a client certificate usable from anywhere, and it does not work at all for a managed cluster. A GKE kubeconfig authenticates through an `exec` plugin:

users:
- name: gke_p_us-central1_prod
  user:
    exec: {command: gke-gcloud-auth-plugin, ...}

which is an instruction to run a binary on the operator's machine using the operator's application-default credentials. Copied into a Secret and mounted into a pod it is inert — no plugin binary, no credentials, no authentication. That is why a hub kubeconfig had to be hand-made out-of-band, and it is what this file removes.

The fix is to stop copying and start MINTING. forge converges a ServiceAccount, the declared permissions, and a long-lived token Secret ON THE TARGET CLUSTER, then assembles a kubeconfig whose only credential is that token, inline. Nothing in the result refers to the operator: it is usable by any pod holding the Secret, which is the entire requirement.

Package cli — `forge project libraries`: where forge/pkg actually is on THIS machine, and what each subpackage is for.

WHY THIS EXISTS. A dogfood run caught three independent agents running a full-disk `find / -path "*forge/pkg/svcerr*"` in the same session, hunting for library source. Every one of them already knew the package name; what they could not answer was "where is it, and what else is in there". The existing answer — a `forge-libraries` skill — was loaded by nobody, and its hand-written table had drifted anyway: it listed a `pkg/dialects` that does not exist and omitted nine packages that do. A stale index nobody opens is not a routing mechanism.

Everything here is ENUMERATED, never transcribed:

• the DIRECTORY comes from `go list -m`, so it is the go toolchain's own answer for the pkg version THIS project resolves — a go.work replace in a dev tree, the module cache in a release build, without this code knowing which.
• the PACKAGE SET is the subdirectories of that directory.
• each PURPOSE is the package's own doc comment, read from that source.

So the output cannot drift from the packages, and it describes the version the project actually compiles against rather than whatever the forge binary was built beside.

File: internal/cli/libraries_signatures.go

The deep half of `forge project libraries`: not just which forge/pkg packages exist, but what each one EXPORTS, with real signatures.

WHY THIS EXISTS. The one-line-per-package inventory answers "does svcerr exist" — a question nobody was asking. A measured ten-unit fan-out wave issued 36 `go doc` calls out of 53 total unit bash calls: `go doc .../svcerr` in four separate threads, `go doc .../tdd RPCCase` in three, `go doc .../orm Context` in three. Every one of those threads had already been handed the inventory. They went to the toolchain because a synopsis cannot answer "what are svcerr.WithReason's parameters" or "what are the fields of tdd.Case" — and because the inventory's closing paragraph told them to go run exactly that command.

The web-runtime half of this same verb has always listed symbols, and pasting THAT half into a unit brief demonstrably worked. This is the Go half catching up to a shape the command already proved.

Everything here is ENUMERATED, never transcribed, on the same rule the rest of this verb follows:

• the DIRECTORY is still `go list -m`'s answer (resolveForgePkgDir), so these are the signatures of the pkg version this project compiles against, not of whatever the forge binary was built beside.
• the DECLARATIONS are parsed out of that directory's own .go files and re-printed by go/printer, so a signature here IS the signature in the source — not a summary of one, and not a copy of one.
• the FILTER is Go's own export rule (ast.IsExported), so a package that gains an exported symbol gains a line here with no edit anywhere, and one that unexports a symbol stops advertising it.

There is deliberately no curated symbol list and no curated package list. A hand-maintained API digest is a lie with a timestamp: the hand-written `forge-libraries` skill this verb replaced listed a `pkg/dialects` that never existed while omitting nine packages that did.

What IS cut is prose. The parse mode below excludes comments outright, so no doc text can reach this output even by accident — the synopsis line the inventory already prints above each block is the package's description, and the signatures are its API. `go doc` on the five packages the wave actually hammered is ~17,000 characters, the large majority of it doc comments.

Package cli — `forge project map` command.

Map is a tree-shaped view of the project with ownership annotations on every leaf. The annotations come from cross-referencing:

• The embedded forge:hash certification marker (verifies = forge-space pristine; fails = forge-space drifted), plus the scoped .forge/hashes.json fallback for comment-incapable formats.
• File-name conventions (*_gen.go = forge-regenerated).
• Forge banner check (`Code generated by forge` first line).
• FORGE_SCAFFOLD marker presence (scaffolded but not finalized).
• Health flags: hand-edits to forge-space files (drift), proto/db entities not represented in migrations, etc.

Filtering and depth control mirror the spec: --depth N, --filter <subtree>, --json. The non-JSON output is plain-text indented tree (no box-drawing chars in the source — we render them at print time so the file stays grep-friendly).

Package cli — shared helpers for `forge project map` (and formerly `forge project audit`, which moved to the internal/cli/audit group). These walk the project tree to classify migrations and forge-generated files. They stay in package cli because map.go consumes them directly; the audit group keeps its own copy of isForgeGeneratedBanner (it's a five-line stdlib wrapper, duplicated per cmdutil's policy rather than shared through a leaf package).

Package cli — `forge project`: the project-structure noun.

Package cli — the shared reconcile spine under `forge env up` and `forge env deploy`.

Both commands bring an environment toward its declared end-state. WHICH entity kinds each acts on is structural, not a value threaded through the call:

forge env deploy — the cluster apply (in-cluster workloads, compose
                   deploy targets, the External dispatch) plus the
                   Firebase frontend publish.
forge env up     — that same cluster apply, plus the concurrent infra
                   pre-warm, plus the host-process and frontend
                   dev-server phases. It always runs the whole loop.

`up` used to carry a `scope` value masking phases off per --cluster-only / --host-only. Those flags are gone: `--target <name>` scopes a run by naming the entities it acts on, which narrows the work inside each phase without forge deciding that a cluster-declared service is "really" a host process. Placement stays where it is declared — a service that should run on the host during dev says so with a `host` block in its KCL.

What remains genuinely variable is:

lifecycle — what a run does once everything is started:
              * once      — reconcile and RETURN. `forge env deploy` is
                            always `once`; so is the non-TTY `forge env up`
                            (start host/frontend processes, persist
                            their PIDs, print the summary, return —
                            stop later via `forge env down`).
              * supervise — start the long-lived host/frontend
                            processes, HOLD on a signal channel, and
                            cascade-teardown on Ctrl-C. The interactive
                            `forge env up` lifecycle.
              * auto      — defer the once-vs-supervise choice to a
                            TTY check at runtime (resolveUpLifecycle).
                            `forge env up`'s default when neither --watch
                            nor --background is given.

In this vocabulary:

forge env deploy <env> = lifecycle=once, opts=<from flags>
forge env up <env>     = lifecycle=auto, opts={skipFrontend: true}

The surgical knobs (tag / prune / dry-run / context override / targets / skip-frontend) live on deployOptions — the cluster reconcile's option surface, shared by both commands. `up`'s cluster step passes its deployOptions through the SAME named entry point deploy uses (reconcileCluster), so there is no blank-`deployOptions{}` literal standing in for "deploy with no options."

`forge project rescaffold <path>...` — have forge write a scaffold-once file again.

A scaffold-once ("yours") file is written exactly once and then belongs to the user. The birth ledger (.forge/scaffolded.json, committed) is what makes that true across deletion: an absent file with a birth record was deleted on purpose, and `forge generate` leaves it deleted in every clone. That is a feature — a repo that runs its own CI deletes forge's workflows and they stay gone — and it is not negotiable here.

What was false is the way back. Every scaffolded workflow said "`forge generate` re-creates it only if you delete it first", and generate did no such thing; it even printed "exists — leaving it untouched" about a file that was gone. The real reset was a hand edit of the ledger, and for the files only `forge project new` writes (the pre-commit config and workflow, the devcontainer, ...) there was no renderer left to run at all.

This command is the one supported reset. For each ABSENT path it drops the birth record and writes the file the way forge would scaffold it today, then records the birth again — so the file is the user's once more, and a later deletion sticks as before. A PRESENT path is refused: overwriting a file the user owns is `forge project upgrade --force <path>`, which shows the diff first.

Which renderer answers a path, in order:

1. The CI mapper (generator.CIWorkflows) for .github/workflows/* and dependabot.yml — THE decision about which workflows a project has. Rendered through `forge generate`'s own CI step, so a rescaffolded workflow is what generate would have written — that step alone, not the whole pipeline, when CI files are all the batch needs generated.
2. The rest of the `forge generate` pipeline, for scaffolds it births (the command tree, internal/app, frontend pages, config.k, ...).
3. The upgrade renderer, for files `forge project upgrade` manages (Taskfile.yml, Dockerfile, .golangci.yml, ...) and the scaffold-once advisory rows — rendered against the live project.
4. The `forge project new` scaffold itself, rendered for this project's forge.yaml into a staging directory (generator.ScaffoldProjectInto) — the only renderer for the DX set, and the one that makes "every file forge scaffolds can be re-emitted" true without a list to maintain.

`forge project scaffolded` — list the scaffold-once files forge has written in this project, and which of them are currently absent.

This is the on-demand half of a trade. `forge generate` used to print the absent set on EVERY run: in control-plane, the same 38 paths plus five lines of explanation, on a clean tree with nothing changed. That is a standing fact rendered as a recurring notice, and a recurring notice is one the reader stops seeing. Generate now reports only the MOMENT the set changes (see generate_missing_scaffold.go); the standing fact moved here, where it is answered when someone asks.

Why a `forge project <noun>` verb rather than a flag on rescaffold: this is a QUESTION about the project, and it sits with the other questions — `forge project map`, `shapes`, `graph`, `features`, `capabilities`. A `--list` flag on rescaffold would put the read behind a write verb, which is both harder to find and easier to run by accident.

Package cli — `forge start`: the greenfield brief, in one call.

WHY THIS EXISTS. A measured dogfood run spent six documentation calls (`forge --help`, `forge project --help`, `forge skill --help`, `forge skill list`, `forge skill load forge`, `forge project new --help`, `forge project annotations`, `forge skill load proto`) before authoring its first proto. Every one of those surfaces is correct and none is hidden; the cost is that reaching the four facts an agent actually needs first — how to lay out the project, how an entity is marked, that custom rpcs are never injected, and how a FK diamond is declared — takes one invocation per surface.

Concatenating those sources is not an option: measured together they run past the consumer's 24 KB output ceiling, so the tail (the pointers onward) would be cut. This command is therefore a CURATION — the pre-first-proto subset, and nothing else.

NOTHING HERE IS TRANSCRIBED. A second hand-written copy of the greenfield prose would drift from the skill that owns it, so every section is composed at run time from the source that already owns it:

• the sequence, the three authoring rules and the shape the embedded skills/forge/SKILL.md, extracted by heading. A retitled or deleted heading is a hard error, never a silent omission.
• the `project new` flags looked up on the real cobra command, so a renamed flag fails loudly instead of advertising one that is gone.
• the proto→column vocabulary scaffold.ProtoSQLMappings(), the same iteration `forge project annotations` publishes.
• the entity markers markerSpecs(), whose names come from the registries the proto scanner spells its markers from.

The deliberate omissions are everything an agent does not need before its first proto: the scaffold tree, the component catalog, deploy, ports, project kinds, and the skill catalog itself. Each is named, not inlined.

Package cli — zero-touch activation of the machine storage policy.

The storage machinery under internal/storage was complete and did nothing, because activation was imperative: `forge storage register` and `forge storage install` had to be run by hand, in order, and never were. A protection that must be switched on is a protection that is off.

This file closes that. Every command that creates or uses a local cache already knows the facts the policy wants, so each one CONVERGES the policy as a side effect of the work it was doing anyway:

ensureDeclaredCluster  → contexts + registry container + aliases (cluster phase)
registerBuildStorage   → repositories + ledger pins + project (forge build)

Neither is allowed to fail the user's command. A policy that cannot be written is a missed cleanup opportunity, not a reason a cluster does not come up, so every path here warns and returns.

Package cli — `forge env up <env>` orchestrator.

One command brings the whole loop up:

1. Render the env's KCL → typed entity set.
2. Build phase: docker build (per-platform) and push every cluster service / operator / cronjob image; go build each declared build-only variant binary.
3. Deploy phase: kubectl apply the cluster manifests + wait operator rollouts + wait one-shot Jobs.
4. Host phase: start every host-mode service as a host process, dispatching on deploy.Host.Runner (go-run / air / binary / delve).
5. Frontend phase: start every declared frontend in its path dir.
6. Wait Ctrl-C → cascade cleanup → exit.

Reaching cluster services from the host is the Gateway API ingress path (see `forge cluster urls`); ad-hoc shells against stateful workloads stay available via `kubectl port-forward` directly.

Replaces the dev-loop bash script every forge project would otherwise hand-write to coordinate build + deploy + run.

Package cli — the machine-local record of which stacks `forge env up` / `forge env up` started, and the teardown that acts on it.

Three files are written per (project, env), under $HOME/.cache/forge/up/<project-id>/:

project.json     the project DIRECTORY <project-id> hashes from
<env>.pids       what this run started: "<name>\t<pid>" per line
<env>.env.json   the resolved discovery facts (live ports + DATABASE_URL)

The <project-id> segment (see projectIDForDir) is what scopes every record to ONE checkout, so two projects bringing up the same env name never read each other's. Until project.json it was also ALL that was recorded — and a hash cannot be inverted. A stack whose project directory had since been deleted was therefore unreachable by every forge verb: `forge env down` derives the id from the forge.yaml above the working directory, and there was no forge.yaml left to derive it from. Eight rounds of the dogfood loop ended that way, leaving 38 orphaned processes, 7.5 GB resident and 15 listening ports that nothing could name. Recording the path is what makes that set enumerable (`forge env ps`) and stoppable (`forge env down --all`).

These files are a RECORD, never an authority. Teardown proves ownership from the LIVE process markers (up_reclaim.go) and signals nothing else: a ledger drifts — a crashed run never persisted one, air re-execs under a new pid, and a pid the OS has since recycled belongs to a stranger — so "this file remembers pid 4242" is not proof that pid 4242 is ours to kill.

`forge project upgrade`'s scaffold-once report.

The engine — which files are in the tier, and how a difference is classified — lives in internal/generator/upgrade_advisory.go. What lives here is the report, because "here is what you are missing, and here is what taking it would cost you" is a human-facing judgement rather than a generator concern.

The whole section is advisory: nothing in it is written unless the user named that exact path after --force.

`forge project upgrade --check <path>` — the detail half of the report.

The summary (upgrade_report.go) deliberately prints no diffs: at 91 reported files, inline diffs were 14,000 of the 14,244 lines emitted and were the reason the check went unread. Suppressing them is only honest if the diff is one command away, and this file is that command.

It spans BOTH lanes on purpose. The user reading the summary sees one list of paths; making them know whether a path is a Tier-2 managed file or a scaffold-once advisory row before they can ask about it would leak forge's internal tiering into the one gesture that should be trivial. The lane still decides what the footer says, because the remedies really are different — that difference is information, the lookup is not.

The presentation layer shared by both lanes of `forge project upgrade`.

── Why this file exists ──────────────────────────────────────────────

The report was correct and unusable. Run against a mature project (control-plane: two customized Next.js frontends) it emitted 14,244 lines over 91 files, because every reported file dumped its full unified diff inline. Every finding in it was genuine. Nobody reads 14,000 lines, so in practice the check reported nothing — and the two findings that were cheap to act on (.github/CODEOWNERS two lines behind, a newly-reportable eslint.config.mjs) were invisible among the frontend files whose divergence is simply what a customized frontend LOOKS like.

So the split this file implements:

--check          SUMMARIZES — what differs, and by how much
--check <path>   DETAILS    — that one file's diff
--check --all    every row, still without inline diffs

── Ranking is the product ────────────────────────────────────────────

The ordering is not cosmetic; it is the only part of the report that does the reader's triage for them. A pristine file two lines behind is a one-command adopt. A file carrying forty local lines is a merge somebody performs by hand, and forge cannot know which of those lines matter. Presenting the two at equal volume is what buried the cheap ones. So rows are grouped by what adopting them COSTS, cheapest group first, and sorted within a group by the same measure.

── What is capped, and the promise that makes capping honest ─────────

A group prints at most maxRowsPerGroup rows and then says how many it withheld and how to see them. Nothing is dropped from the report: every withheld row is one `--all` away, and every suppressed diff is one `--check <path>` away. Both escape hatches are printed next to the truncation that needs them, because a cap whose escape hatch is documented elsewhere is just a lie with a footnote.