[esraagamal6]

In plain words

We are handing this generator over to the Hub team. The existing guides are long and written for the people who built the generator. This PR gives the Hub team one short page to start from, shortens the three Hub guides, and adds one rule about coverage floors.

What to look at

• docs/how-it-works.md (new): one page. What runs, what you will see in Slack and on PRs, a "when X happens, do Y" table, who owns what, and a glossary. The ownership split is a proposal: please check it first.
• README.md: the top box sends the Hub team to the new page and says the rest is for people changing the generator.
• The three Hub guides are shorter. PR check guide: about 3,975 to 2,645 words. The nightly and coverage guides shrank less, because most of what is in them is what a Hub engineer reads.
• AGENTS.md, configs/camunda-hub/coverage-floors.json (the $comment only), and the coverage and PR-check guides: a floor may be lowered by exactly what a deliberate skip for a tracked Hub bug removes, with the Hub issue linked. The PR that re-enables the test raises it back.

What changed

• Docs only. No code, workflow or config values change.
• Detail that only the people who built the generator need (how the PR check is built, the workflow dependencies, how the weekly report job runs) was removed from the guides. It is not moved to a docs/maintainers/ folder: an earlier version of this PR did that, and the folder was dropped on purpose.
• File names and the anchors used by code and tests are unchanged: #adding-or-changing-an-endpoint-in-hub-do-you-need-a-generator-pr, #keeping-track-of-pending-generator-fixes, #closing-a-gap.
• Review comments are addressed in the latest commit. The pings text still describes the routing as not yet switched; the follow-up PR feat: ping hub-medic for Hub and generator alerts, and add CODEOWNERS for Hub backend #718 switches it and updates the text, so merge them together.

Details

• I could not run vitest with the default config in my environment: its global spec-drift check fails there (pinned baseline mismatch), unrelated to Markdown. The tests that mention these docs only assert URL strings in code. I checked all anchors between the docs by script.
• The new rule on coverage floors comes from docs: allow lowering a coverage floor when a test is skipped for a Hub bug #721, which was folded into this branch.

🤖 Generated with Claude Code

https://claude.ai/code/session_01G3526HsTZMmihMi94p34Pr

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ esraagamal6
❌ claude
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Copilot]

🔵 Needs a closer look

The glossary still defines generator gaps too narrowly and contradicts its unmapped-operation entry.

2 open findings

• Specify Hub config to avoid updating the wrong pin
• Generator gap definition omits missing-test cases

🧠 Review effort: Balanced

[Copilot]

🔵 Needs a closer look

The proposed ownership handover and coordinated merge with PR #718 require final human confirmation.

0 open findings

2 resolved since last review

• Specify Hub config to avoid updating the wrong pin
• Generator gap definition omits missing-test cases

🧠 Review effort: Balanced

[Copilot]

🔵 Needs a closer look

The new overview contains two misleading statements about coverage gaps and spec-pin updates.

0 open findings

Previously missed (2)

In code that hasn't changed since last review

Clarify coverage gaps can fail invariants without failing API tests

docs/​how-it-works.md:79

This is too broad: an unmapped operation or a response/request coverage gap can fail this repository's response coverage does not regress invariant (and the PR-check job's coverage step), even though it does not fail a generated API test. Clarify that distinction so readers do not treat coverage gaps as incapable of affecting CI.

Clarify that alerts open bump PRs rather than moving pins directly

docs/​how-it-works.md:82

The alert itself does not move the pin. Clean drift opens a bump PR, and the pin changes only when that PR is merged; blocked or failed checks leave it unchanged. The current wording contradicts the three outcomes documented earlier on this page.

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Several handover instructions inaccurately describe coverage gates, pin updates, required labels, and on-demand invariant testing.

1 open finding

• Update suppress instructions to require all three labels · New

Previously missed (3)

In code that hasn't changed since last review

Clarify coverage gaps can fail checks without API-test failures

docs/​how-it-works.md:80

This overstates the meaning of a coverage gap. An unmapped operation makes _hub-suite-run.yml exit nonzero, and a floor regression fails the response coverage does not regress invariant, even though neither is a generated API-test failure. Distinguish the API-test result from the coverage gates so readers do not infer that gaps can never make checks red.

Clarify pin changes require merging the spec-bump PR

docs/​how-it-works.md:83

The alert does not move the pin itself. The spec-bump workflow opens or updates a draft PR, and the pin changes only after a person merges that PR, as the action table above correctly explains.

Correct hub-ondemand-test invariant validation claim

docs/​hub-pr-check-cookbook.md:86

hub-ondemand-test calls _hub-suite-run.yml, which generates and runs the live suites plus the unmapped-operation check; it never invokes the Layer-3 invariant tests. Claiming that this run validates invariants can make reviewers skip the separate CI/Vitest invariant check.

🧠 Review effort: Balanced

[Copilot]

🔵 Needs a closer look

Several operational instructions are inaccurate, including the local PR-image command and automation-label behavior.

0 open findings

1 resolved since last review

• Update suppress instructions to require all three labels

Previously missed (3)

In code that hasn't changed since last review

Account for Hub PRs missing the hub label

docs/​how-it-works.md:63

The parenthetical is not true for all bot-created Hub PRs: hub-reenable-check.sh adds only nightly-api-fix, while spec-bump-open-pr.sh adds spec-drift and auto-generated. Those Hub-scoped PRs can therefore lack hub, so the ownership checklist should tell the team to add it when automation did not.

Clarify tracked bugs may still count as nightly failures

docs/​hub-nightly-cookbook.md:14

A tracked Hub bug can still be a failing nightly test until its suppress PR is merged; the known-issue row below explicitly covers that case and may link a newly opened suppress PR. Only bugs already represented by a merged skip or partial-check entry are excluded from the failure count, so the blanket statement is misleading.

Use the full Hub PR image reference via HUB_IMAGE

docs/​hub-pr-check-cookbook.md:163

HUB_IMAGE_TAG is expanded by docker/start-hub.sh to camunda/hub:pr-<sha>, but Hub PR images are published as registry.camunda.cloud/team-hub/hub-restapi-self-managed:pr-<sha> (the same full ref used by hub-pr-check.yml). Following this command therefore pulls the wrong repository instead of the PR image. Pass the full image through HUB_IMAGE.

🧠 Review effort: Balanced

[Copilot]

🔵 Needs a closer look

Several operational statements conflict with the workflows, including invariant execution, spec-bump updates, and automated labeling.

0 open findings

Previously missed (3)

In code that hasn't changed since last review

Hub automation PRs and issues may lack the hub label

docs/​how-it-works.md:63

The automation does not consistently add hub: re-enable PRs are created with only nightly-api-fix (hub-reenable-check.sh:221-226), while Hub spec-bump PRs and issues receive spec-drift and auto-generated only (spec-bump-open-pr.sh:136-137, spec-bump-report.sh:116-120). As written, Hub work can be omitted from hub-label views unless someone adds the label manually.

Open bump PRs can become stale without an update

docs/​hub-nightly-cookbook.md:147

Later spec-bump runs do not update an open bump PR. spec-bump-open-pr.sh:43-62 explicitly leaves it unchanged to preserve reviewer edits, then considers fresh drift only after that PR is merged or closed. The current wording may make reviewers assume an old open PR contains the latest upstream changes.

On-demand Hub tests omit the Layer-3 invariant suite

docs/​hub-pr-check-cookbook.md:86

hub-ondemand-test does not run the Layer-3 invariant suite. Its reusable workflow generates and runs the live suites and checks coverage.json for unmapped operations (_hub-suite-run.yml:262-344); the invariant Vitest command exists only in CI (ci.yml:268-273). Saying this run validates invariants can lead reviewers to merge without that check.

🧠 Review effort: Balanced