@kieransimkin/dance-rudiments 0.4.0 → 0.4.1

package/AGENTS.md

@@ -4,6 +4,7 @@
 - Use the relevant existing capabilities as fully as the task warrants. Always look for a useful improvement to this tool. Fix a reusable gap here rather than copying its engine or carrying a private workaround; record why no change is justified when that is the result.
 - Submit improvements as PRs to https://github.com/kieransimkin/DanceRudiments/pulls. Never leave a completed reusable improvement only in a local fork. Keep changes focused and preserve the tool's identity and compatibility contracts.
 - Add relevant regression coverage, documentation and a reproducible example when behaviour changes. Use tools/release_version.py and tools/check_release_version.py. Run the native and relevant binding tests from .github/workflows/ before packaging.
+- Run `python tools/check_package_docs.py` before packaging; every nested first-party `README.md` in the package input trees must retain the canonical author music link. Preserve third-party `sources/` attribution and keep the actual archive checks enabled.
 - Keep credentials, account data, private media and rights records out of source, fixtures, logs and packages. Use synthetic fixtures or explicitly authorised public examples and preserve their provenance/licences.
 - Use [CONTRIBUTING.md](CONTRIBUTING.md) for review. Maintainers publish accepted, validated improvements as a fresh matching GitHub release and verify configured registry destinations. Preserve existing tags and release assets; publication and deployment remain subject to applicable authorisation.
 - Website: https://kieransimkin.co.uk/danceflow/
@@ -33,6 +34,7 @@ Before every new workflow run, check the latest stable official release and obse
 - Read `docs/release-demo.md` and `docs/mesh-demos.md` before changing demo builds or deployment. Keep the root native visualizer and `meshes/` gallery together in `dist/pages`. `demo-release.yml` is the sole Pages publisher; main/PR `visualizer.yml` runs remain artifact-only and must not erase a released mesh route.
 - Build from the exact validated tag and commit. Use tag pushes or manual dispatch for an existing compatible published tag; do not depend on a `release.published` event created with `GITHUB_TOKEN`. Old tags without the gallery cannot be retrofitted, moved or overwritten.
 - Retain the `DANCERUDIMENTS_PAGES_ENABLED == 'true'` guard, `github-pages` environment, approvals and protections. Read Pages configuration without enabling or changing it. Only the latest stable official release may deploy, with a second latest-release check after waiting for the shared deployment concurrency slot. Older-tag attachment builds must report a Pages skip accurately.
+- A `main` branch deployment rule does not authorize version tags. If the environment rejects a tag, report the exact annotation and request the maintainer's explicit tag-rule authorization; do not bypass it. Once authorized, retry the failed deployment from the same run while its artifact remains available. Do not rebuild or overwrite completed release attachments to recover a deployment-only failure.
 - Keep original mesh geometry separate from captured source motion. The selected two-source builder may download only its explicitly requested, pinned files and must retain CMU/converter terms, hashes, units, axes and unverified musical timing. Optional motion files must remain outside the default catalogue and base package artifacts.
 - Run `npm test`, `test_mesh_demo_assets.py`, `test_release_pages.py`, the existing native visualizer/MIDI browser gates, and `tools/test_mesh_demo_browser.py` for the complete site before sealing release assets. Preserve the shared native 64-pip sampler, exact profile bindings, lazy scene loading and resource disposal. A `--gallery-only` receipt is local evidence and cannot seal a complete release site.
 - Bind browser evidence to every packaged site file and the exact release identity. Keep archives outside the Pages tree. Existing release assets are immutable: compare every collision before upload, retain identical bytes and refuse changed assets; never use `--clobber` for demo releases.

package/README.md

@@ -663,6 +663,19 @@ StemLab. Rebuild old generated pages to include the control. See
 
 ## Continuous integration and releases
 
+Run `python tools/check_package_docs.py` before packaging. Its source preflight
+checks nested first-party `README.md` files in the package input trees, including
+rig-motion examples and optional source-plan documentation, for the canonical
+author music link. Third-party `sources/` documentation retains its original
+attribution. Release jobs also check the actual archives; passing source checks
+does not establish package publication or registry availability.
+
+Tagged Pages deployments require an allowed **Tag** rule in the existing
+`github-pages` environment, in addition to any allowed `main` branch rule.
+A maintainer must explicitly authorize the intended release tags; the workflow
+does not change environment protections. See [release demo recovery](docs/release-demo.md#recovering-a-deployment-rejected-by-environment-rules)
+for retrying an already built site without rebuilding its immutable release assets.
+
 The additional `.github/workflows/csharp.yml` builds the shared C ABI and C# wrapper, tests actual installed NuGet packages, and publishes .NET packages only for release tags. Its NuGet.org setup is documented in [the C# guide](docs/csharp.md).
 
 `.github/workflows/ci.yml` builds and tests the C++ core on Linux, Windows, and macOS; builds and imports the Python package; compiles/tests the TypeScript and browser runtime; and creates a Conan package on every push to `main` and every pull request.

package/docs/release-demo.md

@@ -144,6 +144,41 @@ reported as a verified live site. See GitHub's
 [custom Pages workflow guide](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages)
 for the existing environment and artifact requirements.
 
+
+### Recovering a deployment rejected by environment rules
+
+GitHub evaluates the workflow's branch or tag against the `github-pages`
+environment's allowed deployment rules. An allowed **Branch** rule for `main`
+does not allow a run triggered by a `vMAJOR.MINOR.PATCH` tag. A rejected job may
+have no runner or step logs; inspect its check annotations for the exact reason.
+
+If the annotation says the release tag is not allowed, a maintainer must
+explicitly authorize the tag in **Settings → Environments → github-pages →
+Deployment branches and tags**. Retain the existing branch rules and other
+protections. Add a rule with ref type **Tag** for the exact release, or
+`v*.*.*` if the maintainer approves the ongoing versioned-release policy.
+The workflow never changes these rules or bypasses their approvals.
+
+When `render`, `attach`, and `pages-target` already succeeded, use **Re-run
+failed jobs** on that same workflow run after the rule is authorized. With the
+GitHub CLI, substitute the affected numeric run ID below:
+
+```sh
+gh run rerun RUN_ID --failed --repo kieransimkin/DanceRudiments
+```
+
+This preserves the original tested site and release attachments while retrying
+deployment. Confirm the original `github-pages` artifact is still available
+before retrying; its default retention is one day. The latest-stable-release
+check and live route/file checks still apply. A full rebuild can produce changed
+browser reports or toolchain output and must not overwrite immutable release
+attachments. If the original site artifact has expired, prepare a fresh release
+through the normal build and verification process.
+
+The [GitHub environment guide](https://docs.github.com/en/actions/reference/workflows-and-actions/deployments-and-environments)
+documents separate branch/tag rules. The [GitHub CLI manual](https://cli.github.com/manual/gh_run_rerun)
+documents the failed-job retry command.
+
 ## Local build
 
 Use a checkout with matching package versions and the native build tools,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kieransimkin/dance-rudiments",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Deterministic rhythmic position functions with C++, Python, TypeScript/WASM and C# bindings. https://kieransimkin.co.uk/my-songs/",
   "license": "MIT AND BSD-3-Clause AND CC0-1.0 AND CC-BY-4.0",
   "type": "module",