Generated from folio-assistant-core/processes/conduct/getting-started.bpmn by gen-processes-viz.ts — do not edit here. All processes

Getting started

Process_GettingStarted · strict · 13 step(s)

Somebody said “create a folio”: work out which request they meant, with the branch computed by a decision table that may answer “ask”, and what has to be true before anything is written. folio-assistant — getting started: from “create a folio” to a live site.

“Create a folio” is five different requests. Gateway_Intent computes which one from decisions/folio-intent.dmn rather than letting the agent assume, and ask is one of the outcomes the table can return. Gateway_Live applies the same construction to publication, with unknown kept distinct from not-yet.

Source of truth: this file. The SVG under docs/assets/img/workflows/ is generated from it by bun run cat render:bpmn — never hand-edit the SVG.

How it connects

• Called by: no call activity names this process
• Calls: none
• Presented on: no docs page section shows this diagram

Lanes — who acts

lane	role	what it does here
User (person)	user	Answers the one question Gateway_Intent cannot compute for itself — “ask” is one of five outcomes decisions/folio-intent.dmn can return — and, only on the overlay path, three further questions a repo scan cannot answer on its own: what to import, where it goes, and who does the importing.
Onboarding agent (system)	onboarding-agent	Every write in this diagram belongs to this lane, and each sits behind the non-relaxable read-first gate: nothing is created or scaffolded until Gateway_Intent has classified what was actually asked for, which is what stands between this lane and writing over somebody’s existing project.
Work plan (beans)	work-plan	Seeds one bean per top-level content object the author named, positioned after scaffolding but before the Pages probe — a work plan exists for a folio whose publication status is not yet known, rather than waiting on that answer.
Publish — GitHub Pages	publish-target	Provisions the gh-pages branch before Pages is switched on (Task_ProvisionGhPages, #2417), derives the URL, and holds the report that follows it: “unprovisioned” routes back to provisioning, and “live”, “not-yet” and “unknown” are reached by exclusive branches of one DMN-computed gateway, and this lane is what keeps a failed probe from being reported as the softer “not-yet” it would be tempting to default to.

Steps

Every one of the 13 step(s) is documented.

step	lane	skill / sub-process	what it does
Detect the interaction modality Task_DetectModality	Onboarding agent (system)	interaction-modality	Before the first question is asked, establish HOW to ask it: audio, ordinary chat, selectable options for a user with limited hand function, large-type for low vision. A user who finds the questions unusable never reaches the rest of this diagram.
Read the repository facts Task_ReadFacts	Onboarding agent (system)	getting-started	Mechanical, read-only: does the instance’s config (its index.config.json entry; a legacy <name>.config.json only as a fallback) declare a contentType, does the working tree hold somebody’s existing project, and what has the user actually said. These are the three inputs to folio-intent.dmn. Non-relaxable: scaffolding without looking first is how a folio gets written over somebody’s project.
Choose from the offered options Task_AskIntent	User (person)	interaction-modality getting-started	The question is presented as a short list of selectable options, never as free prose, and the list names the top-level content types the agent knows about. The answer becomes the statedIntent fact and the table is evaluated again — the user’s answer is read as evidence, like any other fact.
Scan the repo for content worth importing Task_ScanRepo	Onboarding agent (system)	repo-conversion document-intake	Read-only. Classifies candidates into library/ (external source) and content/ (authored here), and reports what it could not classify as its own bucket rather than forcing every file into one of the two.
Import what, where, and who does it Task_ConfirmImport	User (person)	repo-conversion dispatch-agent	Three questions the scan cannot answer: import these or not; library or content for each group; leave the files where they are or reorganize to declutter. Plus whether to dispatch one ingestion agent or a small swarm. Non-relaxable: nobody’s files are moved or imported on inference.
Create the repository Task_CreateRepo	Onboarding agent (system)	repo-conversion	Only on the new-repo branch, and only after the user has named it. An empty working directory is scaffolded in place instead.
Scaffold the folio (folio_init) Task_Scaffold	Onboarding agent (system)	getting-started	content/, uploads/, library/, the first manifests, .json and index.config.json (the instance's config inline in its entry; no .config.json, bean ymvt), the builder shim, AGENTS.md with its stubs, .mcp.json, the session-start hook and the beans store. Refuses rather than overwrites when a folio is already present.
Seed the work plan Task_SeedPlan	Work plan (beans)	todo-manager	The first beans: what the author said they want to get started on, one bean per top-level content object they named.
Provision gh-pages Task_ProvisionGhPages	Publish — GitHub Pages	getting-started	Before Pages is switched on, make sure the gh-pages branch exists — the semantics of A_Provision in bootstrap-tools’ render-kg-to-github-pages.bpmn, first half. git ls-remote --heads origin gh-pages; if absent, bun run cat-harness/scripts/pages-bootstrap.ts --provision pushes an orphan gh-pages holding a placeholder index.html and .nojekyll (idempotent; never forced; the script creates no remote branch without the flag). Then Settings → Pages → “Deploy from a branch: gh-pages, / (root)” — not “GitHub Actions” when the publish workflow pushes gh-pages. Every publishing path reaches this step: new-repo, overlay and add-folio, and an overlay or new repo that remote-mounts its dependencies (litlfred/test, provisioned at 860f9c2). Owner, 2026-10-01: “need to create gh-pages branch before can turn on”; 2026-10-07: “need to create gh-pages before can deploy” (#2417).
Start the Pages build and derive the URL Task_PagesBootstrap	Publish — GitHub Pages	getting-started	scripts/pages-bootstrap.ts: check the gh-pages branch first (absent is unprovisioned), derive the site URL from the git remote or the instance’s config (its index.config.json entry), report whether a publish workflow exists and the Pages source it needs, and optionally probe until the site answers.
Hand over the live link Task_ReportUrl	Publish — GitHub Pages	getting-started	Confirmed live. The link is given as a link, and the author is told what is on it.
Say where it will be Task_ReportPending	Publish — GitHub Pages	getting-started	A measured 404. The author is told the address and that the first build has not landed there yet — which is useful, and is not the same as being told it is live.
Say it could not be confirmed Task_ReportUnknown	Publish — GitHub Pages	getting-started	No URL, no probe, or a failed request. Reported as “could not check”, never as “not yet” and never as “live”.

Decisions

Every one of the 2 decision(s) is documented.

decision	what decides it	branches
What is the user asking for? Gateway_Intent	Computed, not chosen. decisions/folio-intent.dmn returns one of five branches from statedIntent, isFolio and repoHasContent. Non-relaxable: this gateway IS the fix.	ask → Choose from the offered options overlay → Scan the repo for content worth importing new-repo → Create the repository new-content → Handed to content authoring add-folio → Scaffold the folio (folio_init)
Is the site answering? Gateway_Live	Computed from decisions/pages-live-gate.dmn. Four outcomes: unprovisioned (no gh-pages branch — back to Task_ProvisionGhPages) is checked first, and unknown is not a softer not-yet.	live → Hand over the live link not-yet → Say where it will be unknown → Say it could not be confirmed unprovisioned → Provision gh-pages