Core concepts

This page defines the objects you'll see everywhere in Forginate and how they relate to each other.

Organization

The organization is the billable tenant. It owns everything: projects, members, provider credentials, deploy targets, invoices, and the audit log. You can belong to several organizations and switch between them in the app; each has its own plan and billing.

Project

A project is one product moving through the factory. It bundles:

• the product's documents (the versioned plan),
• its requests (units of work),
• its runs (individual agent executions),
• its Git repository,
• its Improve board (post-delivery iteration),
• its deployments.

Access to a project is granted per person, separately from org membership — see Teams and roles.

Request

A request is a unit of work you file: a new project, an import of an existing repo, or an adoption of a production app. A request travels through the pipeline phases (Intake → Define → Plan → Build → Integrate → Deliver → Improving) that you see on the Pipeline board.

Features, changes, and bug fixes against an already-shipped product are not top-level requests — they're improvement requests on the product's Improve board, which have their own smaller lifecycle (submitted → triaging → recommended → approved → building → QA → awaiting merge → merged).

Document

Documents are the heart of Forginate. Everything the factory builds is defined by planning documents first: architecture, requirements, designs, acceptance criteria, and more, organized in a tree per product.

Key properties:

• Versioned. Every edit — by you, by the vibe editor, or by an agent — creates a new version. The full history is always available.
• Approval-gated. A document version can be approved or sent back with request changes notes. Downstream pipeline stages wait on approvals; an unapproved plan does not get built.
• Editable three ways. Direct editing, conversational editing via the vibe editor, or regeneration by the original agent.

Pending edits proposed by the vibe editor appear as patches you accept or discard before they become a version.

Run

A run is one execution of an AI agent — a planning-document generation, a build task, an audit, a QA pass. Each run records:

• which stage it belongs to,
• its live token usage and cost in dollars, updated as it executes,
• its artifacts and event log.

Runs have budget caps. If a run's spend approaches its cap, it stops rather than continuing to spend; during integration you can raise the live budget envelope mid-grind if you want the work to continue.

Delayed, not dead

If a model provider is overloaded or rate-limits the platform, a run doesn't fail — it waits and retries in place, shown in the UI with a "delayed but still running" badge. No progress or money is lost to the wait.

Agent

Forginate ships a roster of factory agents — the reader, planner, build agent, auditor, and others — each with a default prompt. You can view an agent's effective prompt and override it at the user or project level from the Agents screen, with a full version history of your overrides.

Deployment and deploy target

A deploy target is a place your software can run: your own Kubernetes cluster (via a lightweight agent you install) or a dedicated AWS account Forginate provisions. A deployment is one app running on a target, with its own lifecycle (planning → awaiting approval → deploying → running, plus stop/upgrade/teardown states). See Deployments and Deploy targets.

Share

A share is a read-only, link-based portal to a product's approved documents, served from share.forginate.com. Recipients don't need a Forginate account; they accept a review agreement, read approved documents, and leave comments that flow back to your feedback stream. See Sharing.

Activity and audit

• The Activity feed shows what's happening across a project — document versions, approvals, run completions, comments.
• The org audit log records administrative actions (member changes, provider changes, billing events) for owners and admins.

Putting it together

Organization
├── Members (viewer / member / admin / owner)
├── Providers (platform or bring-your-own model keys)
├── Deploy targets (Kubernetes agent · AWS account)
├── Billing (plan + metered usage + invoices)
└── Projects
    ├── Team (per-project roles + invites)
    ├── Requests → pipeline phases → Runs
    ├── Documents → versions → approvals
    ├── Improve board (improvement requests)
    ├── Shares (external read-only portals)
    └── Deployments (on deploy targets)