First Week

Installation ends when the API reports healthy and the setup wizard has made you an admin. This page covers what comes next: the order in which a real shop's data has to go in, and why that order is not negotiable. Nothing here is Forge-specific ceremony — every ERP rollout hits the same dependency chain — but Forge models the chain explicitly, so you can ask the system what is still missing instead of keeping the list on a whiteboard.

Decide the shape before you load anything

Loading data into an install whose shape you are still arguing about means loading it twice. Three decisions belong before the first part number:

• Which capabilities are on. The discovery wizard (/admin/discovery) recommends a preset from a short interview, and /admin/presets lets you compare them. Applying a preset does more than flip flags — it can also seed roles and role templates, kanban track types and stages, workflow definitions and reference data, and rewrite the entity vocabulary. See Capability Gating for what each layer overwrites and what it leaves alone.
• Which accounting mode you are in. Built-in books and an external system of record are mutually exclusive, and switching later is a migration, not a setting. Read Accounting Modes first.
• What things are called. Terminology is configuration — whether the central object is a Job, a Work Order or a Project is a settings row. Changing it after everyone has learned the old word is the expensive version.

Reference data — roles, units of measure, the chart of accounts, the seeded readiness validators, carriers — is written on every boot and is idempotent, so it is there whether or not you asked for it. Demo business records (users, customers, jobs) are a separate, opt-in thing: they arrive only from a --seeded install, and the API refuses to boot if that switch is on in a Production environment. Do not evaluate on a seeded install and then load real data into it. Start clean.

The loading order

Each row depends on the rows above it. Skipping ahead does not error immediately — it leaves records that look fine and quietly fail to participate in planning, costing or the ledger.

Order	What	Why it has to be here
1	Units of measure	A starter set covering count, weight, length and volume is seeded, with ea as the base count unit and the default for new parts. Add or retire what your shop actually uses before parts exist: a part binds a stock UoM, and the part readiness gate resolves it by code
2	Parts	Everything downstream references a part. Parts are created in Draft
3	BOMs	A BOM line points at a part, so the component has to exist before the parent's BOM can name it
4	Work centers, working calendars, shifts	A routing operation names the work center it runs on; capacity and scheduling need the calendar behind it (/admin/working-calendars)
5	Routings	Operations in sequence against those work centers. Routings plus BOMs are what make a part costable and plannable
6	Customers and vendors	Plus the shared reference data they lean on — payment terms (/admin/terms), currencies, carriers. Vendor parts and price lists hang off vendors and are how bought-part costs get real
7	Opening inventory	Set on-hand per part per location. This is a deliberate administrative override, restricted to Admin/Manager and gated on the inventory-adjustment capability, distinct from the everyday receive/issue verbs
8	Open orders	Sales orders and purchase orders that were live on your cutover date, entered against the master data that now exists
9	Opening balances	The last step, and a hard prerequisite for the full ledger — see below

Two things are worth doing in parallel with all of it rather than after: decide who gets which role (Access and Roles — the role set is fixed and not all of it grants API access), and work through Hardening a Production Install before anyone outside the project logs in.

Forge keeps the readiness list for you

This is the mechanism worth knowing about, because it turns "did we finish the parts?" from a spreadsheet question into a query.

Readiness validators are data, not code. Each row targets an entity type and carries a JSON predicate — hasBasics, hasBom, hasRouting, hasCost, hasSourcing, hasInventory ship seeded for parts. A validator may also carry an applicability predicate, so it is skipped entirely for records it does not apply to rather than reported as missing. Admins can list and author rows through the entity-validators endpoints, and seeded rows are marked as such so the UI can protect them.

Promotion out of Draft is the gate. Asking to promote a part to Active runs its validators server-side. If any fail, the call is refused with a conflict carrying the machine-readable code workflow-readiness-missing and the list of what is missing — which is what renders as "Draft — missing BOM, Routing" with jump-to links, rather than a silent no-op. When a guided workflow run is in flight against the entity, the check narrows to that run's required steps, so a validator that does not apply to this part's make/buy combination cannot block it. The Mark Complete button in the workflow and the Promote button on the entity page go through the same handler, so the two paths cannot disagree.

Draft is not a cosmetic label. MRP plans only Active parts, and low-stock alerts and ABC classification only consider Active parts. A backlog of parts stuck in Draft is therefore invisible to planning — which is exactly the failure mode this page exists to prevent. Working the readiness list down to zero is the first week.

A second, separate mechanism answers a different question: entity completeness asks whether a record is complete enough to participate in a given capability, rather than whether it may leave Draft. It shows up as a chip on customer, part and vendor records, filtered to the capabilities your install actually has on, so a requirement belonging to a switched-off feature never raises a false alarm. Be aware that the completeness rule catalog ships empty — the rows are authored per install at /admin/entity-completeness, deliberately, because what a vendor needs before it can go on a purchase order is a policy question your shop answers, not one the product answers for you. The readiness validators above are the seeded, working half; treat completeness as the extension point.

The underlying pattern — validators, workflow definitions, gates and runs — is documented in docs/workflow-pattern.md, and the wiki's orientation is Workflow Gates and Approvals.

Opening balances unlock the ledger, not the other way round

The full general ledger ships off, and it will not turn on until the books are opened. The enable path is deliberate and ordered:

1. Enable the accounting migration capability, which exists so the conversion tooling is reachable while the ledger itself is still dark.
2. Import the opening journal for each book — one balanced entry per book, sourced as a conversion, as of your cutover date. It must balance; unbalanced input is rejected, and re-running the import for a book returns the entry already posted rather than doubling it.
3. Tie out: compare the native opening trial balance against your legacy system's closing trial balance.
4. Enable the full-GL capability. The toggle evaluates every active book first and refuses with a conflict if any book has no posted opening journal.

There is a matching guard in the other direction — once a book's opening balances are loaded, the ledger cannot simply be switched back off by toggling the capability. The read-only ledger view stays enabled when posting is disabled, so history remains viewable and exportable.

Honest limitation: the opening-balance and tie-out steps are API surfaces today. There is no admin screen that walks the conversion, so this step runs through the API (see API Access) or with help. Everything else in the loading order has a screen. Chart of accounts, books, determination rules and the current fiscal periods are seeded on a clean install, so the ledger has something to post into once you unlock it.

Then hand the floor the user guide

Once the data is in and the roles are assigned, the people who will use Forge daily need something that is not this page. The repo ships one: docs/new-user-guide.md. It is short, plain-language, and organised by role — where an engineer, a PM, an office manager and a production worker each land, what the dashboard shows, what the search and chat surfaces do, and the handful of first tasks each role has.

Note what it assumes: it is written for employees who have already been set up by an administrator, with an account and a role already in place. It is the second document your users read, not the first, and it is not a substitute for the administrator work described above. App Surfaces covers which front end each of those people is actually looking at.

Getting bulk data in

Typing a thousand parts is not a plan. Three master-data types have a bulk-intake path with the same two-phase shape — paste or upload CSV, get a per-row preview that classifies every row as new, duplicate within the batch, duplicate against an existing record, or invalid, then commit only the new ones:

• Parts at /parts/import. Column aliases are generous (part number, MPN, SKU and external id all land in the same field), make/buy and inventory class are parsed leniently from free text, and part numbers are server-issued on commit rather than taken from your file.
• Customers at the equivalent import page.
• Leads, for sales pipeline migration.

Vendors have no bulk importer — nor do BOMs, routings or work centers. Vendor pricing does have its own import paths (vendor parts and price lists, both with a preview step). For everything else, the API is the bulk path: it is the same surface the UI uses, it enforces the same capability gates and validators, and it is the honest answer for a one-off migration script. See API Access.

One caution before you script a migration: applying a preset afterwards can seed and reshape things you have already touched. Settle the shape first, load second.

What "week one done" looks like

• The capability set and accounting mode are decided, and nobody is still arguing about terminology.
• No part you intend to plan, cost or stock is still in Draft, and the readiness list on the ones that remain is deliberate rather than forgotten.
• Opening inventory reconciles to a physical count, not to what the old system believed.
• Open orders are in, against master data that exists.
• If you are running the built-in ledger: opening balances are posted, tied out, and the ledger is on.
• A backup has been taken and restored somewhere else — proving the restore is the point, see Backup and Restore.
• The integration readiness report has no gaps you did not choose; a stock install answers with canned data for several integrations, and believing otherwise is the classic week-two surprise. See Configuration and Integrations.

Terms used above that are not obvious are defined in Glossary; what each module actually does is Feature Reference.