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