fcode-ama

Factorial Code — platform guide (AMA)

Factorial Code (fcode) is Factorial's platform for building apps and automations against the Factorial Public API. This skill covers using the platform — the journey from requesting access to a published marketplace app — and how to behave when supporting users through it. For building the app itself (processes, modules, CLI, forms), route to the owning skills (see the routing table below).

The full stage-by-stage walkthrough is in references/journey.md; common problems and fixes are in references/troubleshooting.md.

Who you're helping

Three user roles use the platform. Establish which one you're talking to early — several flows diverge by role:

Role	Who	Key differences
Factorial internal	Developers at Factorial	Create their own OAuth apps in the Factorial Backoffice; create demo companies directly (using the Demo generator); Slack #factorial-code-users available
Partner	External companies building apps/integrations with Factorial	OAuth app preconfigured by an administrator; demo companies by request
Individual Contributor	Someone building their own app or automation (may be a customer, but not always — never call this role "end customer")	Same as Partner

All roles talk to Factorial through the Public API, and all belong to a development team: every app a team creates is shared by all its members. When someone requests access and an administrator sees their organization already has a team on the platform, they are added to that existing team.

Support-agent behavior rules

• Answer only from documented flows — this skill, its references, the other fcode-* skills, and the public docs. Never invent UI elements, URLs, commands, or policies. If it isn't covered, say so and escalate.
• Identify the user's role first when the answer differs by role.
• Describe flows by page and section name (e.g. "the Getting started checklist on the App detail page"), not by exact button pixels — labels change; flows are stable.
• Admin actions: outcome only. When a step is performed by an administrator (access approval, demo provisioning, OAuth preconfiguration, release review), tell the user what they will observe and what to do next. Never describe admin-side mechanics or how credentials are delivered.
• Answer in the user's language.
• Fetch before deep-diving. When you have web access, read the linked docs page before answering a detailed question; the live docs win over this skill on details. Without web access, answer from this skill and say which docs page has more.
• Escalate when needed — an admin action, a stuck request, or an uncovered question. Escalation paths are in the last section.

Platform map

Everything lives under https://code.factorialhr.com, split across three surfaces users often conflate:

• Docs (/docs/...) — public documentation, plus the landing page with the request-access form.
• App console (/dashboard/...) — apps, teams, demo companies, marketplaces, installations. Where the journey below happens.
• Workspace console (/platform/...) — inside a workspace: processes, executions, schedules, variables, versions, API credentials. The app console links into it — every such jump is labelled "Open on platform"; for a deploy- (installation) workspace it lands on the executions page.

App console areas (the sidebar groups them into Build, Operate, and Admin sections):

Area	What it's for
Apps	The team's apps; where a new app is created
App detail page	Per-app home: the Getting started checklist and the Development / Production / Publication / README tabs
App settings	Configuration (marketplace visibility, lifecycle) and OAuth (requested scopes plus the development and production credentials)
Demo companies	Demo Factorial companies for testing installs
Test marketplace	Simulation of the production marketplace, run against demo companies

Plus the self-describing Marketplace, Team, and Installations areas.

The journey at a glance

#	Stage	Where	What happens
1	Request access	Landing page → request-access form	An administrator reviews it and you're notified; joins an existing development team when one matches
2	Create an App	Apps → create	Name and purpose; language (JavaScript or Python); OAuth scopes; the integrations framework opt-in (decision rule in references/journey.md)
3	Getting started	App detail page checklist	Ordered setup steps: build locally, link the Factorial integration (framework apps only), configure OAuth (when scopes were requested), publish a release, add marketplace metadata
4	Configure OAuth	App settings → OAuth tab	Per-environment client credentials for the OAuth flow (per-role setup in references/journey.md)
5	Build locally	Your machine	Install the CLI, fcode clone the dev workspace (or fcode team:clone for every App of your team at once), code with your own agent + the fcode-* skills, test locally, fcode push
6	Demo company	Demo companies page	Internal: create directly. Partner/IC: request one; you're notified by email
7	Test installs	Test marketplace	Run the real OAuth flow with the demo company's credentials, install, exercise the appRole forms and any UI trigger buttons inside the demo company's Factorial
8	Release	App detail → Production tab	Request a release (semver + notes); after validation it's promoted to the prod workspace — self-service for a Factorial admin of the owning team, by an operator otherwise (references/journey.md §8)
9	Publish listing	App detail → Publication tab	Marketplace listing metadata: a linked DatoCMS record and/or the fallback fields
10	Production	Marketplace	Visible and installable; each install gets its own isolated workspace

Per-stage detail, per-role callouts, and lifecycle states: references/journey.md.

Workspaces behind the journey

Naming caution: a Factorial Code workspace is also called a "team" in the workspace console, in the platform API, and in a few CLI surfaces ("team variables", the parentTeams field) — that sense is unrelated to the development team of humans described above. The CLI's fcode team:* commands mean the development team: they operate on every App it owns (see fcode-cli).

Each app maps to workspaces (slugs carry an encoded token, not the raw id):

• dev-{appId} — the development workspace you clone and push to.
• prod-{appId} — production copy, created when the first release is requested. Treat its code as read-only — changes belong in dev and reach it through the release flow; only operators and the app's Factorial team admins can write to it at all. Its variables are live — shared defaults and credentials for all installations are managed there.
• deploy-{installationId} — one per company installation, inheriting from the app workspace: it holds only that company's variables and executions, fully isolated from other companies. A change in the parent workspace is automatically available in every installation workspace.
• base-app / base-integration-app (language-matched variants, -js/-py) — shared bases every app inherits: API clients, webhook/schedule/email/form helpers, and (for framework apps) the integration templates.

Released versions are pinned tags and the stable alias points at the current one (model in fcode-core-concepts). For a marketplace app, ship through the release flow (stage 8) — don't publish versions or move stable by hand.

Buttons inside Factorial — UI triggers

Besides forms and webhooks, an installed app can put its own buttons on Factorial's pages. Factorial teams declare locations in the product (a page header, an actions dropdown — e.g. calendar.header.admin); an app process that declares a uiTrigger for that location shows up there as a button, with the app's label and icon, for every company that installed the app. Clicking it runs the process with the page's context (the record on screen, the company), or opens the process's form when it has one — so a "Sync to Acme" action can live next to Factorial's native actions without Factorial shipping any integration-specific UI.

What to tell users:

• It works only for installed marketplace apps — the buttons are read from the company's deploy- workspace, so a trigger reaches customers through the release flow (stage 8) like any other change; in development, the demo company shows the dev workspace's triggers (stage 7).
• The location id comes from Factorial: there is no catalogue in the platform. A developer who wants a button on a page that has no location yet needs the owning Factorial team to add one — escalate as a product request.
• Some locations admit one app at a time; installing a second app that claims such a location fails with a message naming the first.
• Configuration lives on the process page (Trigger from Factorial, the section of a Factorial Action that also covers forms and, in later phases, Factorial One tools and backend jobs — fcode-factorial-actions) or in metadata.json; the developer-facing rules for the button are in fcode-ui-triggers.

Routing — where deep questions live

Question is about	Route to
Platform model: processes, modules, variables & inheritance, datastore/storage, versioning & stable	fcode-core-concepts
CLI commands, metadata.json / settings.json fields, appRole field reference, webhook auth, FACTORIAL_TOKEN	fcode-cli — docs: /docs/cli/
Writing process/module code	fcode-javascript / fcode-python — docs: /docs/processes/
Input-parameter schemas (forms definition)	fcode-json-schema
Embedding forms on webpages, themes, pre-fill	fcode-forms — docs: /docs/forms/
Exposing a process to Factorial (factorial block, Factorial One tool contract, lifecycle slugs)	fcode-factorial-actions — docs: /docs/factorial-actions/
Buttons inside Factorial (factorial.uiTrigger, locations, result envelope)	fcode-ui-triggers
Recommended agent working method, MCP tools	fcode-agent — docs: /docs/mcp-server/
Worked examples (integration, install/uninstall lifecycle)	fcode-examples
Executions, schedules, webhooks at runtime	docs: /docs/executions/
Integrations framework	docs: /docs/building-apps/integrations-framework/
OAuth & API tokens	docs: /docs/building-apps/oauth/
Workspace hierarchy	docs: /docs/building-apps/workspaces/
Roles & permissions: who can read/write/promote per workspace	references/journey.md §8 — docs: /docs/building-apps/permissions/
The end-to-end journey (public version)	docs: /docs/building-apps/developer-journey/

Doc paths are relative to https://code.factorialhr.com.

Escalation & admin actions

Need	What to do
Access request pending	It's under review; you'll be notified of the outcome
OAuth app for a Partner / Individual Contributor	Preconfigured by an administrator — visible on the App settings' OAuth tab once done
Demo company (Partner / IC)	"Request a demo company" on the Demo companies page; you're emailed when it's ready
Release review outcome	The release either deploys or you're notified of required changes; fix and request again with a higher version
Promote a release to production	A Factorial admin of the owning team does it themselves (the App detail page's "How to promote" dialog has the commands); everyone else's route is an operator — references/journey.md §8
Private app installed for a specific company	A production installation created from the App detail page — by an administrator or by a developer who provides the Factorial company ID (e.g. how Factorial's Forward Deployed Engineers roll out private apps)
Anything not covered	Internal Factorial users: Slack #factorial-code-users. Others: the in-platform request flows above