Upstream synchronization

Canonical branches

main is the only development and release source for this fork.
Upstream history is fetched from PaloAltoNetworks/docusaurus-openapi-docs as the upstream remote.
Shared main is never rebased onto upstream. Each accepted upstream tag is merged through a dedicated sync/upstream-vX.Y.Z pull request.

Upstream owns the original OpenAPI plugin, schema renderer, demo, and their package versions.
AEEI owns packages/docusaurus-theme/, examples/docs-starter/, Base Nova audits, visual tests, legal notices, and the @aeei/docusaurus-theme release boundary.
Root manifests, yarn.lock, shared workflows, and top-level documentation require explicit reconciliation.

Fetch upstream branches and tags.
Create sync/upstream-vX.Y.Z from current origin/main.
Verify the upstream repository and annotated release tag, then merge it with --no-ff.
Resolve source conflicts according to ownership. Regenerate yarn.lock from the combined manifests instead of choosing either side.
Run upstream tests plus the complete AEEI theme, docs-starter, package, and browser validation.
Compare the packed @aeei/docusaurus-theme artifact with the current release. If its bytes change, bump the package version and update every vendored consumer artifact; never reuse a version for a different archive.
Merge only after independent review and green CI.

Deck consumes a repository-owned tarball; npm is a secondary distribution channel.
npm publication is manual through .github/workflows/theme-release.yml and the protected theme-release environment.
npm trusted publishing must bind @aeei/docusaurus-theme to repository aeei/docusaurus-theme, workflow theme-release.yml, and environment theme-release.
A new publish requires publish @aeei/docusaurus-theme@X.Y.Z. The privileged job atomically reserves or verifies theme-vX.Y.Z for the exact source SHA before npm publication, so a competing tag aborts before publish. If npm fails after reservation, retry publish with that original 40-character commit as source_sha.
recover-tag is only for an npm version published outside this workflow without its source tag. It requires the original source_sha and recover theme-vX.Y.Z for @aeei/docusaurus-theme@X.Y.Z; recovery checks out that exact main ancestor and creates a tag only when its clean rebuild exactly matches npm dist.integrity.
The privileged release job receives only the prebuilt tarball, verifies its SHA-512 integrity and source tag, publishes only that file when needed, then verifies registry integrity.