cli

Overview ¶

`forge generate accept-fork <path>...` — DEPRECATED alias for `forge disown`.

The fork concept is gone: there is no forked-but-maybe-reconciled- later limbo any more, only forge-owned (Tier-1) and user-owned (Tier-2), with `forge disown` as the one-way door between them. accept-fork survives one release so existing scripts and muscle memory don't break overnight; it simply forwards to the disown flow (and therefore now REQUIRES --reason, like disown does).

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: read the service port from forge.yaml, 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.

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 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 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 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 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 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 — declarative cluster reconcile for `forge 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 up` (create-if-absent, no-op if present).

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.

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 delete service` — the inverse of `forge add service`.

Where `forge add service` scaffolds a handlers/<svc>/ dir, appends a component to components.json, and (after the user lists its serviceRow line) serves it, `forge delete service` walks that back:

1. Removes the component from components.json so forge stops treating it as part of the project shape.
2. Removes the handler scaffold directory (handlers/<svc>/).
3. 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, MCP tools, 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, per-tenant 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 — dev-mode forge/pkg replace handling.

Background: when forge is checked out alongside a project (sibling directories on disk), the project's go.mod commonly carries a

replace github.com/reliant-labs/forge/pkg => /absolute/host/path/forge/pkg

directive so the project can use forge/pkg subpackages that haven't been published yet. This works for `go build` on the host but breaks `docker build`, because the absolute host path isn't visible inside the build context.

The canonical fix in forge: detect such absolute-path replaces during `forge generate`, vendor the target into `<project>/.forge-pkg/`, and rewrite the replace to `./.forge-pkg`. The Dockerfile template emits a corresponding `COPY .forge-pkg/ ./.forge-pkg/` line whenever the vendored copy exists, so docker builds and host builds use the same replace target by construction.

This is a development affordance — production deploys want forge/pkg as a real go.mod requirement, not a vendored copy. The opt-in is implicit (presence of the host-absolute replace in go.mod) and can be disabled with `forge.yaml -> dev.vendor_local_forge_pkg: false`.

Release builds of forge skip this flow entirely: they scaffold a clean `require github.com/reliant-labs/forge/pkg vX.Y.Z` pin (no replace), and the sync below is contractually a no-op for such projects (TestSyncDevForgePkgReplace_CleanVersionPinUntouched). `forge doctor` warns when a project is still vendored even though the running forge release publishes a pkg version (doctor_pkgpin.go). Full model: docs/pkg-versioning.md.

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 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 up` renders the KCL, so it can start the host `reliant` process LISTENING on exactly the port the in-cluster controller will dial.

`forge 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 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 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 into .forge/friction.jsonl (area=disown) through the same append-only machinery as `forge friction add`; `forge audit --json` joins it back onto each disowned_files row.

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 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` forge/pkg dependency-mode check.

Generated projects can satisfy their github.com/reliant-labs/forge/pkg dependency two ways (docs/pkg-versioning.md):

• RELEASE flow: `require github.com/reliant-labs/forge/pkg vX.Y.Z` pinned against a published pkg/vX.Y.Z submodule tag, no replace.
• DEV flow: a replace directive pointing at ./.forge-pkg (a vendored copy synced from a forge checkout) or at a host-absolute checkout path.

The dev flow is a development affordance. Once the forge release a project tracks ships a published pkg version, staying on the vendored copy means the project silently stops receiving released pkg code and keeps a ~116-file copy committed in its tree. Doctor surfaces that "stuck on the dev path" state as a warning with the exact commands to switch over. The decision core (pkgPinCheck) is pure — it takes the go.mod contents and the published version string — so unit tests cover every branch without touching buildinfo or the filesystem.

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 friction` command.

Friction formalizes the downstream→upstream feedback loop: when an agent (or human) working in a forge project hits generator friction — a lint false-positive, a scaffold quirk, a missing helper — the observation is captured AT THE MOMENT OF FRICTION with one dumb, durable, local command:

forge friction add "wire_gen drops Deps fields added after scaffold" \
  --severity p1 --area codegen --source fix-validate-agent \
  --context pkg/app/wire_gen.go:42

Records land in `.forge/friction.jsonl` — append-only JSONL, one self-contained object per line. JSONL is deliberate:

• appends are atomic-ish (single O_APPEND write, no read-modify-write)
• merge-friendly (git unions lines; no rewrite conflicts)
• immune to the markdown-rewrite failure mode that lost ~65 findings in the field (an LLM batching prose appends got rate-limited mid-rewrite and dropped the batch)

No LLM, no network, no rewriting of existing lines, ever. Reading tolerates (skips + counts) malformed lines so a torn write can never brick the log.

`forge friction list` filters/renders the log, `forge friction export` renders FRICTION.md-style markdown to stdout (projects that want a checked-in FRICTION.md redirect it; forge does not own that file), and `forge audit --json` surfaces a summary under the additive `friction` category so standing friction is visible where agents already look.

Disown friction capture.

A disown is design feedback: when a user (or agent) runs `forge disown` (or the deprecated `forge generate --accept` alias) on a generated file, they are saying the generated API/abstraction couldn't express what they needed. That signal is worth exactly as much as it is durable — so we capture it AT THE MOMENT OF DISOWNING, through the same append-only .forge/friction.jsonl machinery `forge friction add` uses (one O_APPEND write per entry, never read-modify-write; see friction.go for the durability rationale).

Design constraints, in order:

• Never prompt. Agents drive these commands non-interactively; a blocking "why did you disown this?" prompt would hang every automated run. The commands require --reason up-front instead; the placeholder branch survives only as a backstop for callers that reach the recorder without one.
• Never block the disown. By the time we record, the checksum flip has already been persisted — failing the command over a friction- log write would leave the user with a succeeded disown and a failed exit code. Write failures warn loudly and continue.
• One entry per path. `forge friction list --area disown` and the audit disowned_files reason lookup both key on the per-path context, so a batched disown of N files must produce N independently-queryable records.

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 upgrade` is their emitter; `forge generate` deliberately leaves them alone.
• Verification. Only PRISTINE markers (certified machine output) are deleted. A file whose marker fails verification was hand-edited — stale or not, those bytes are the user's now, so it is reported but never removed.
• Disowned paths are never candidates.

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.
• packages[].name=foo but internal/foo/contract.go missing → bootstrap codegen emits a broken import the validate step fails on, pointing at generated code instead of the missing contract.

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

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.

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 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.

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 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.

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
• `forge dev` watch loops re-run 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: --strict promotes the historically-silent "Warning: ... failed" sites to hard errors via a single helper that every per-step body can opt into without per-site code changes beyond "use this helper instead of fmt.Fprintf + return nil".

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 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/authorizer/mocks, wire/diagnostics, MCP manifest tools,
  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 add 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
  MCP tools, no auth skip-list entries, `forge run` skips it, and
  `forge 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, MCP tools, 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 become report-only removal candidates (deleted under --force-cleanup); Tier-2 user-owned files in the same dir are never candidates. `forge audit` surfaces both halves via the codegen category's unregistered_services finding.

`forge generate` step: version-true delivery of forge-shipped skills.

Skills used to reach generated projects only as a scaffold-time copy (or a manual `forge skill write`), after which the on-disk SKILL.md files froze at scaffold-date and drifted from the project's pinned forge version. This step makes `.claude/skills/` a Tier-1 codegen output: every `forge generate` re-renders the forge-namespace skills from the embedded templates of the RUNNING forge binary, so the disk copies always match the binary that last generated the project.

Scope is strictly the forge-shipped skill set — the step only ever writes the exact `.claude/skills/<flat>/SKILL.md` paths derived from the embedded skill list. User-created skill directories under `.claude/skills/` are never touched (and never deleted).

Tier transition: projects that predate this step have skill files that carry no forge:hash certification marker — they froze as Tier-2/legacy scaffold output. Those entries migrate to Tier-1 on the first run: a differing on-disk copy is a stale scaffold-era render, NOT a precious user edit, so it is overwritten with a one-line notice per file. Once an entry is Tier-1, the standard pre-pipeline stomp guard (stepCheckTier1Drift) applies — hand-edits surface as drift and require --force / `forge disown` like any other Tier-1 file.

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_test.go — a 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 that filename — 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 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`.

generator.Tier2ManagedPaths is the registry of those paths. This file hosts the cached set plus the filter the drift consumers (stomp guard, audit, ci verify-generated) apply to the raw ScanTier1Drift result.

(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 filter exempts the rest.)

Package cli — `forge 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.

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, and that IP isn't in the serverlb cert SANs, so the minted kubeconfig points at https://<ip>:6443 with TLS verification disabled. "endpoint" (prod) uses the kubeconfig's own endpoint verbatim — a stable reachable address with a valid cert — and needs none of the insecure rewrite.

Package cli — `forge 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 map` (and formerly `forge 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 mcp` command surface.

`forge mcp serve` hosts gen/mcp/manifest.json as a live Model Context Protocol stdio server: every Connect RPC in the project becomes an MCP tool an agent can call. The manifest is a generated artifact (one tool per RPC) that, before this command existed, had no host — `forge mcp serve` is that host.

Transport: tools/call dispatches to the running Connect service over plain HTTP+JSON — exactly the shape `forge api curl` prints. The service port is resolved the same way `forge api curl` resolves it (forge.yaml services[].port, with the same fallbacks), so `--addr` only needs to be supplied when the default host/port don't match the running server (e.g. behind an ingress).

Auth: a forge dev server that is NOT in AUTH_DEV_MODE runs the auth interceptor, so a tokenless tools/call returns a clean Connect "unauthenticated" error (which itself proves the wiring). Pass a bearer token via --token or $FORGE_MCP_TOKEN to authenticate real calls. The same env var is the shared dev-token seam `forge api curl` can adopt for its own --token in future.

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

Both commands bring an environment toward its declared end-state; they differ on exactly two axes, made explicit here so the up-vs-deploy relationship is legible instead of buried in a blank-options call seam:

scope     — WHICH entity kinds a run acts on:
              * cluster      — kubectl-apply the in-cluster workloads
                               (Deployments / Jobs / operators), the
                               compose deploy targets, and (for deploy)
                               the External dispatch.
              * composeInfra — pre-warm the docker-compose infra
                               (postgres / nats / temporal) concurrent
                               with the build phase. up-only; deploy's
                               cluster apply already drives compose
                               targets through the same provider.
              * host         — start every `deploy: "host"` service as a
                               host process (go-run / air / binary /
                               delve). up-only.
              * frontend     — start every declared frontend's dev
                               server (`npm run dev`). up-only. (deploy
                               instead publishes Firebase frontends — a
                               fixed, structural step of the deploy
                               pipeline, not a scope field.)

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

In this vocabulary:

forge deploy <env>  = scope{cluster} (+ structural Firebase publish),
                      lifecycle=once, opts=<from flags>
forge up --env=<e>  = scope=all,                     lifecycle=auto,
                      opts={}

The surgical knobs (tag / rollback / 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 a scope-derived (today: zero-value) deployOptions through the SAME named entry point deploy uses (reconcileCluster), so there is no longer a blank-`deployOptions{}` literal standing in for "deploy with no options."

Package cli — `forge up --env=<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.