Rewrite thirteen shorter pages in plain English
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lxo4MXbp6VPoDkUrTBNXJ1
docs: the adapter page points at the ladder instead of retelling it
The levels are explained on the workflow module page. The extension
section told the same story a third time, so it names the section now
and keeps only what is the extension's own: it reads both halves of the
ladder, which is where the eight positions come from, and the level is
asked before the adapter inside it.
Checked against ExtensionSettingsResolutionTest and SettingsLevel in
adapter-platform-integration: same resolution as an adapter setting, a
level beats the adapter section above it, and an adapter section beats
the general section of its own level.
Story 601.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0168Fox39crp8dfWkZ9W84Ub
docs: one word for the reader, and eight places for a setting
The glossary now names both words for the same thing: the core calls it an
extension, its own documentation calls it an adapter sitting next to the BPMS
adapter. The migration page says adapter and points at the glossary.
The configuration paragraph said two places. There are eight: four levels, each
of them again for one adapter. Checked against
MigrationAdapterProperties#resolveForExtension, migration-adapter/README.md and
decision 53. It also says now that the core reads from the general towards the
specific, and that an extension without a section of its own has nothing to do
for it, which leaves the Business Cockpit's own section as the exception it is.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RYPiyZ32jQQhqYKx44cw23
docs: the flattening rule links on to what each BPMS makes of it
Every adapter wiki now carries a page "What becomes of a shared value",
answering the same four questions in the same order. This wiki keeps the rule
which is the same everywhere and points at the three pages instead of
repeating them.
Workflow-aggregates: the sharing rule links on to the three pages, and the
serialization-format link of the Camunda 7 adapter follows the chapter which
moved out of its configuration page.
Choosing-a-BPMS gains the row a reader comparing two BPMS was missing, what
becomes of a value the engine has no type of its own for, and BPMS-adapters
names the new page among what an adapter wiki carries.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RYPiyZ32jQQhqYKx44cw23
Say that the Business Cockpit's keys stayed where version 1 had them
The migration page told applications that every cockpit key had moved into the extension section.
It did not stay that way: the cockpit reads `vanillabp.cockpit.*` and the `cockpit` sections of a
workflow module, of a single workflow and of one of its user tasks, which is where version 1 read
them, so an upgrade is a dependency and not a rewritten configuration file.
The page about extensions gains what makes that possible. The two locations the core reserves are
still the ones an extension uses by default, and an extension which owns a section outside them
binds that section itself, with the same overlay a BPMS adapter uses for keys of its own. VanillaBP
neither reads those keys nor knows them, and on Quarkus the overlay is what keeps a key below
`vanillabp` from ending the startup.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YU73krA4jKHuWYB155np2X
Document extensions and the Business Cockpit upgrade
The extensions section of the BPMS adapter page now says what an extension
does from an application's point of view: when it joins the deployment, that
it may bring annotations of its own, that its reports travel through the
outbox, and the two configuration locations the core reserves for it. The
Business Cockpit is named as the extension to look at, with its three BPMS
repositories and the platform-neutral half in the cockpit's own repository.
The migration page gains a Business Cockpit section: the renamed artifacts,
the keys moving into the extension's section, the refused version attribute,
reports arriving after the commit, and the two things which differ per BPMS -
a new process version on Camunda 8 and a history level on Camunda 7.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YU73krA4jKHuWYB155np2X
docs: the guide is linked, the boundary is named
Two answers existed and were not reachable from where the question comes up. Somebody weighing an
adapter for another BPMS found the adapter guide only by browsing the repository, so the adapter
page and the glossary link it and say who it is written for. And no page said who may complete a
user task or read the viewer API, which is a question VanillaBP does not answer at all: it
authorizes nothing and publishes no endpoint, the connection an adapter opens to its BPMS being
the one security surface it does own.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XjxJNwTRcKzTmXCwLU7Wi4
docs: every page opens with what to do and carries a table of contents
A reader who has never used VanillaBP met the reasoning for a rule before the rule
itself, and had no way of telling how far to read before writing a first workflow.
The pages now start with the sentence somebody can act on and keep the background
where it belongs, further down. Nothing was deleted; what explains a rule moved
behind it.
Every page gained a numbered table of contents in the shape Home and the Spring Boot
page already used, so a reader sees the sections and what each of them answers before
scrolling. Where a first heading only repeated the title GitHub shows above the page,
it is gone and the page starts with its first sentence.
Home is now ordered the way a newcomer needs it, and what VanillaBP is sized for
became a page of its own: it answers a question somebody asks before they start, not
one they trip over in the middle of the introduction. The architecture picture from
the repository's diagrams folder is embedded there, linking to its Excalidraw source.
The horizontal rules of the workflow-module pages are gone, the heading is the
separator everywhere else. Hints are written as sentences rather than marked with a
label, headings sit at one depth per page, and the paragraphs written by hand over
the last months were brought to the tone of the rest without changing a single
statement they make.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
docs: a rule says where its decision is written down
Five decision logs hold 61 entries, the wikis linked none of them, and 22 of the 42
objections an outside review raised were already answered in one. A reader who wondered why
a rule is what it is had no way there short of reading source repositories.
So a rule carries a (why) link now, pointing at the numbered entry which decided it. Home
says once what the links are and where the logs live, and the form is the same on every page
of every wiki: an inline link at the end of the sentence stating the rule. Numbers are handed
out once and never reused, so the links keep resolving.
The rules the review named are linked first - the outbox on Camunda 7, probing per operation,
the two retentions, sharing aggregate values, the Camunda 8 correlation key - and the
remaining entries follow wherever a page states their rule. BPMS-adapters also says in one
sentence what the module migration-adapter is, which it linked without explaining.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CvgyhjwTEh834mwbptZZxh
docs: a page for readers who have to pick an engine first
The comparison a newcomer needs existed twice, in the contributor skills and in the review
guide, and neither is published. Choosing-a-BPMS carries it now: one row per property, one
column per adapter, plus what the review found missing - when the shared values reach the
BPMS and what a crash between commit and command leaves behind, what identifies a delivery,
whether the age of an open task is measured at all, and whether the adapter can tell that a
workflow is unknown to it or has to guess. Three of those rows decide how much an
application has to carry itself, so they are repeated below the table in prose.
Underneath it, one short section per question somebody arrives with: a Camunda 7 in
production, a Camunda 8 cluster, or nothing to run an engine on yet.
Home links it from the adapters entry and BPMS-adapters from the top, both in the words a
reader without a BPMS would use.
Home also gets the glossary the wiki was missing. It defines the terms a user meets while
reading it - adapter id, election, the outbox, the delivery log - and stays out of the
contributor vocabulary, which the repositories document.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CvgyhjwTEh834mwbptZZxh
docs: what Quarkus reports when the core extension itself is missing
Story 81's message about a missing BPMS adapter comes from the core extension, so an
application without that extension gets Quarkus' unsatisfied-dependency error for
'ProcessService' instead, and nothing of VanillaBP can reach the reader: the support
library is a plain JAR on purpose, because a workflow module stays free of platform
infrastructure and Quarkus extensions belong to the application.
Both pages now name that error, so searching for it finds which dependency belongs where.
Story 82.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Jss55UjjvxYcLQPVFUFe25
docs: the artifacts of every adapter, and where the messages point
The startup message about a missing BPMS adapter no longer lists the adapters - it links
here, so this page has to carry the list: Spring Boot artifact and Quarkus extension per
adapter, and that the version is not managed by the VanillaBP BOM.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Jss55UjjvxYcLQPVFUFe25
docs: what happens if you forget the BPMS adapter
Story 81 gives that case a message of VanillaBP's own, naming the artifacts to add.
The page a newcomer lands on now carries it, plus the note that an application without
a workflow module is not reported.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Jss55UjjvxYcLQPVFUFe25
docs: a phase-two failure repeating cannot fix blocks the entry at once
Story 55: point at what an adapter wiki still carries
An adapter wiki is now configuration plus deviations, so the pages delegating
BPMS specifics have to name the page which answers them: the wiring conventions
and correlation mechanics sit on the adapter's Configuration page, what a BPMS
cannot serve on its Deviations page.
"What is documented in the adapter's wiki?" listed six kinds of content, four
of which the adapters no longer keep.
Also says that Camunda 7's table-prefix does not start an engine, where the
version-1 migration table offers it as the successor of camunda.bpm.*.
Unify the wording of all pages
Two passes over the wiki:
1. The pages written earlier (workflow modules, workflow aggregates, the
platform integration intros) were aligned with the wording of the newer
ones: grammar and typo fixes, consistent terminology (process = the BPMN
model, workflow = one execution; message names instead of event names)
and active voice instead of impersonal constructions.
2. All pages were revised to read less like generated text: em dashes in
prose replaced by proper punctuation, promotional phrasing and filler
removed, boldface and inline-header lists reduced to where they aid
scanning.
Two corrections found on the way: the Quarkus workflow-module page pointed
at the "main Spring Boot application module", and the property precedence
lists of the two platform pages are sorted in opposite directions, which is
now stated (Spring Boot: highest first, Quarkus: lowest first, matching the
config source ordinals 250/251/255/256).
No configuration key, behavior or example was changed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Extensions belong to contributor documentation (story 29 follow-up)
The Extensions page documented a mechanism only someone BUILDING an integration needs -
that is contributor documentation and now lives in migration-adapter/README.md.
BPMS-adapters gained a short section instead: besides the adapter, an extension may take
part in deploying workflow modules (the VanillaBP Business Cockpit as the example), users
only add its dependency, and building one is documented in the migration adapter's README.
The Home entry is gone with the page.
Document the viewing API (story 26)
New page 'Viewing workflows': the three read-only ProcessService methods, the
call-activity drill-down via the secondary history context, the opaque
(adapter-namespaced) process definition ids and the guiding errors - linked
from Home.
Move BPMS-specific content into the adapter wikis
The main wiki now documents only what is identical across all BPMS.
Everything specific to Camunda 7, Camunda 8 or the Process-Engine-API
moved into the respective adapter wiki.
Where such content stood, the pages now carry a list of the available
adapters linking directly to the matching page of the adapter's wiki.
The new page 'Available BPMS adapters' holds the full list and is
linked from Home. A custom footer with the VanillaBP logo and the
license notice was added.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>