Documentation that describes code which no longer exists

Problem

Every claim in the 25 documentation pages, the OpenAPI document and the README was checked against the source. These are the ones that are no longer true: dead API names, an override the docs tell implementers to write that silently does nothing, a plugin that has never existed, and examples using a task type the module does not ship.

26 findings: 3 high, 16 med, 7 low.

High severity

The OpenAPI document names the wrong permission, so an integrator following the spec cannot write

Where: docs/openapi.yaml:38-40 and :66

There are two permissions, and the three write operations the spec documents require the other one. In modules/orchestra_server_api/orchestra_server_api.routing.yml, start, signal and set-variable all require drive orchestra api; only the three reads require access orchestra api. The string drive orchestra api does not occur once in the OpenAPI document, and no 401 or 403 response is documented on any operation, so nothing else in the spec hints at it either. A consumer provisioned exactly as the document says gets 403 on every write with nothing pointing at the cause.

The variable audience plugin does not exist; the shipped ids are users_variable and roles_variable

Where: docs/concepts.md:398-406 and :424, docs/maestro.md:200, docs/timers.md:246 and :252

src/Plugin/Audience/ holds exactly six plugins: users, roles, users_variable, roles_variable, which are the four that can staff a task, plus email and email_variable, which are notify-only. There is no plugin with id variable. So both the count, "three staffing audiences" where there are four, and the id are wrong. docs/human-tasks.md:157-166, docs/notifications.md:70-79 and docs/roadmap.md:110-118 all get this right, which is what makes these five spots stale rather than a convention.

docs/extending.md tells implementers to write explain(); the interface method is summary(), and a renamed override fails silently

Where: docs/extending.md:127-135

src/FlowConditionInterface.php:58 declares summary(). There is no explain() anywhere in the module. The engine calls summary() at src/FlowEvaluator.php:115, and the composite base plus both shipped conditions all override summary(). A contrib author who follows the documentation writes a method that overrides nothing: the parent answers, no error is raised anywhere, and their condition's incident diagnostic quietly degrades to the generic rendering. This is the renamed-override failure mode, introduced through the documentation rather than through a rename, which no static check can catch.

The rest

One line each: what it is, and where. The failing scenario and the fix for each are carried by its own commit.

• med README.md Status describes alpha releases and an unfrozen API, which contradicts docs/extending.md's 1.x compatibility promise and cannot both be true at beta. README.md:166-173, docs/roadmap.md:305-308, against docs/extending.md:3-13
• med docs/incidents.md says Resume is available "through the API" only; it is one of the five links on the instance page. :135-137
• med The external-interaction reference tables name a controller method and a config key that do not exist. docs/external-interaction-internals.md:398,401,410,415
• med docs/human-tasks.md's migration section documents a mechanism with zero occurrences in the codebase. :288-305
• med Three pages claim the quorum example's ballots demonstrate the flat assignee fields; all three use the structured form. docs/concepts.md:417-419, docs/roadmap.md:118-120, docs/integrations.md:100
• med docs/interaction.md cites an inbox access method that does not exist. :74-79
• med docs/architecture.md presents an incomplete plugin-type list and an incomplete "these ship today" submodule table. :11-21 and :33-70
• med Subprocesses have no page and no nav entry, and six of their seven config keys are documented nowhere. mkdocs.yml:9-42; the only substantive coverage is docs/concepts.md:60-66
• med The OpenAPI documents no limit on set-variable although two rules reject a request, and documents no 403 or 500 anywhere. docs/openapi.yaml:236-271 and :339-345
• med docs/notification-delivery.md's event shape omits a field, and never names the reader a channel must call for attachments. :14-24 and :88-136
• med An incidents code sample calls a retry method that does not exist under that name. docs/incidents.md:159-162
• med docs/concepts.md's asynchronous-advancement section states the opposite of the shipped default, and docs/troubleshooting.md:3 repeats the premise. :42-49
• med docs/audit.md says "everything is on by default", which is false, and two shipped settings are undocumented, which makes two safety claims on the page untrue. :23-26, :57-63, :73-79
• med Four config examples use a script task type and one uses task; neither exists. docs/joins-splits.md:196,246,288,333, docs/variables.md:19, docs/modeling.md:214
• med docs/views.md documents four Views base tables where five entities are exposed, three times, and docs/incidents.md:164-166 sends readers to the missing one. :23-32, :112, :390
• med docs/views.md calls a durable audit log "a separate, future step"; that submodule ships and has its own page. :150-154
• low docs/index.md says timers are a submodule; they are in the kernel. :22-24
• low docs/concepts.md says the kernel ships five task-type primitives; it ships seven. :51-66
• low docs/concepts.md attributes the cards library and status palette to the base module; they are in orchestra_presentation. :290-296
• low docs/concepts.md gives the read-access permission a title it does not have. :203-205
• low docs/interaction-chains.md contradicts itself on the milestone flag and on the token field name. :97-108, :196-215, :259-283
• low docs/integrations.md lists 5 of the 11 shipped example workflows. :92-100
• low docs/versioning.md points at the roadmap for a plan the roadmap does not contain. :110-113

Remaining tasks

• Correct the findings above, one commit per page where they are independent.
• Decide the README and extending.md contradiction as part of the beta-preparation issue rather than here, since it is a stage decision rather than a documentation error.
• Run cspell and the docs build before pushing.

This issue summary was drafted with the assistance of an AI agent (Claude). The analysis and the wording were reviewed by me before posting, and accountability for the content is mine.