Generated from folio-assistant-core/processes/content/authoring-a-document.bpmn by gen-processes-viz.ts — do not edit here. All processes

Authoring a document

Process_DocumentAuthoring · advisory · 9 step(s)

How a document folio — structured prose and policy guidance, with no Lean and no required TeX — is authored, built and reviewed end to end. folio-assistant — authoring a document end to end (no Lean, no required TeX). 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. The shape is the paper process minus the Lean lane and plus one step, the profile check, which is what keeps a document folio publishable without either toolchain.

How it connects

• Called by: no call activity names this process
• Calls: none
• Presented on: Documents & policy guidance — Documents & policy guidance, Writing a document — What a document folio is

Lanes — who acts

lane	role	what it does here
Author (person)	author	The only place a person acts before the process becomes agent- and pipeline-driven: Task_Plan sets the chapters, the blocks each needs and which statements are normative, once, before Lane_WorkPlan seeds a bean and Lane_Agent takes over every later edit, including every iteration the review and profile-check loops send back.
Work plan — beans (shared by humans and agents)	work-plan	Touched exactly once in this process — Task_SeedPlan turns the plan into a bean right after Task_Plan, so a resumed session or a sibling agent can pick the authoring loop up without re-deriving what was decided at the top.
Authoring agent (system)	authoring-agent	Task_AuthorBlocks is where every loop in this process lands — a profile violation from Lane_Build and an iterate from Lane_Reviewer both come back here — so this lane, not either gate, is what actually turns a rejection into a fixed block; Task_Scaffold runs once, before either loop exists.
Build pipeline — validate · render · publish	build-pipeline	Owns the one gate this process has that the paper process does not — the profile check — so nothing with a math kind, a lean field or a .lean sibling reaches Task_Validate or Task_Render pretending to be document content; everything downstream of Gateway_ProfileClean assumes that profile.
Reviewer / subject-matter expert	reviewer	Owns the one gate that decides publish or iterate, and is deliberately unspecialised: this process relaxes the paper process’s clinical-SME lane into whichever reviewer a given document actually binds, because no single expertise fits every document the way it does a guideline.

Steps

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

step	lane	skill / sub-process	what it does
1 · Plan the document Task_Plan	Author (person)	content-plan	Scope it: chapters, the blocks each needs, which statements are normative.
2 · Seed the work plan Task_SeedPlan	Work plan — beans (shared by humans and agents)	shared step GT_SeedWorkPlan todo-manager	The plan becomes beans, so a resumed session or a sibling agent can pick it up. From here on, beans/ is the shared answer to ‘what is done, what is next’ — for humans and agents alike.
3 · Scaffold the folio [folio_init] Task_Scaffold	Authoring agent (system)	document-structure	folio_init writes content/, uploads/, library/, the manifests, the builder shim and AGENTS.md. Skipped when the folio already exists.
4 · Author blocks Task_AuthorBlocks	Authoring agent (system)	document-authoring normative-statements	Every block edit runs the HCI validation gate — see editing-hci-validation.bpmn. A normative statement is a recommendation block (bean 55ao), drafted through normative-statements: one statement per block, a folio-chosen label, and its strength as a code in a declared code list, so a reviewer signs off each one individually.
5 · Check the profile Task_ProfileCheck	Build pipeline — validate · render · publish	content-validate	content_profile_check: no math kind, no lean field, no .lean sibling. This is the step a paper folio does not have, and the reason a document folio never needs Lean or TeX to publish.
6 · Validate Task_Validate	Build pipeline — validate · render · publish	content-validate	Schema and constraint checks over every block.
7 · Render MD / HTML / PDF Task_Render	Build pipeline — validate · render · publish	document-publishing	Assemble to Markdown, then pandoc. The PDF goes through an HTML engine — never latexmk.
8 · Review and feedback Task_Review	Reviewer / subject-matter expert	content-review staging-review	The reviewer this folio binds. authoring-document relaxes the base SME step precisely because no single lane fits every document.
9 · Publish Task_Publish	Build pipeline — validate · render · publish	content-publish	See draft-to-publication.bpmn for the review and release path this expands into. Release authorisation is not relaxable.

Decisions

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

decision	what decides it	branches
Within the declared profile? Gateway_ProfileClean	Answered by the profile check (step 5): does every block stay within the folio’s declared content profile? violations sends the author back to step 4 to fix the blocks; clean goes on to validation.	violations → 4 · Author blocks clean → 6 · Validate
Ready to publish? Gateway_ReviewOutcome	The reviewer’s call after step 8. iterate returns to authoring with the feedback; approved goes to publish.	iterate → 4 · Author blocks approved → 9 · Publish