Forgeplane onboarding

Use /setup as the permission-aware setup hub. It shows the next actions available to the signed-in user instead of assuming that every user can create platform resources.

Bootstrap the installation

The first installation needs an administrator account. Follow the loopback-only administrator bootstrap, then disable bootstrap access for normal operation.

The administrator creates or joins the first organization. Continue through the platform hierarchy:

1. Create a team in the organization.
2. Create a project owned by that team.
3. Create an environment in the project.
4. Register and publish a template version.
5. Create an instance that binds the template to the environment.
6. Queue a run on a worker pool that advertises the required tool capability.

Each level provides a scope for ownership, permissions, inputs, approvals, and execution. See Permissions and roles when an action is unavailable.

Use permission-aware actions

The setup hub links only to actions the current identity is allowed to perform. A user without organization or team administration rights can accept an invitation or ask an owner for access instead of entering a create flow they cannot complete.

Select an active team before using the project, environment, or workload onboarding steps. Without a selected team, only users allowed to create an organization can enter onboarding, and only the organization-creation step is eligible. Onboarding does not count resources across all teams when no team is selected. An invalid or inaccessible selection must be corrected rather than treated as an all-teams view.

Saved setup selections belong to the signed-in user. An administrator cannot read or change another user’s selections through setup, and a service account cannot act as its owning user. Saving requires access to the selected project, environment, and template or assembly; selected versions must belong to that target. When a saved target becomes unavailable, setup clears the stale selection without hiding operational failures.

If an action is missing:

• select a team the user can access;
• confirm the user’s organization membership;
• check the team role;
• check system-level permissions; and
• ask an organization or team owner to grant the required access when appropriate.

The setup hub is a navigator, not an authorization bypass. The service checks authorization again when each action is submitted.

Resolve a changed working context

Setup, instance creation, and assembly launch forms use the saved selection that was current when the form opened. If another tab changes that selection, the server rejects the stale save and keeps your submitted choices. Reload the latest context, or use the explicit replacement action to save your choices and continue. Another intervening change requires a new confirmation. A form from a different active team must be reloaded.

Replacement warnings remain visible through wizard navigation and validation errors. A conflict during assembly publication does not undo the published version; the warning tells you that the working context was not updated.

If the selected workload changes while onboarding checks readiness, retry with the new selection. Previously completed milestones remain complete.

Prepare the first run

Before queuing a plan, confirm:

• the template version is published and names the intended tool;
• the environment and instance reference that version;
• ordinary inputs match the template input schema;
• secret-marked fields use approved secret-catalog bindings; and
• a worker pool advertises the required capability and can reach the needed systems.

The Run operations guide explains plan promotion, approval, cancellation, requeue, logs, artifacts, and timeouts.

Prepare for production

A successful first run proves the control path, not the production topology. Before moving production workloads under control:

• configure external PostgreSQL and durable NATS JetStream storage;
• configure artifact storage and, when enabled, encrypted managed-state storage;
• back up the database, state blobs, and exact encryption keys together;
• create named worker pools with explicit tool capabilities and network placement;
• replace enrollment and bootstrap credentials used during initial setup; and
• review approvals, quotas, notification routes, audit export, and feature gates.

Continue with the Helm chart and Managed state contracts.