docs: releasing flow + monorepo split rationale

Author: gabepri

CLAUDE.md

@@ -79,6 +79,13 @@ When changing Masker behavior, prefer adding a shared fixture (so both ports sta
 
 Update the relevant package README whenever the public API or config changes, or when documentation becomes ambiguous or untrue.
 
+## Releasing
+
+See the [Releasing section in the root README](README.md#releasing) for the per-package recipes. Two non-obvious things:
+
+- `npm version` in `packages/js/` only bumps files in a monorepo — it doesn't auto-commit/tag. The README recipe handles this explicitly.
+- The PHP package publishes via a read-only mirror at `gabepri/auto-html-i18n-php` because Packagist requires `composer.json` at the repo root. The mirror is auto-rebuilt by [.github/workflows/split-php.yml](.github/workflows/split-php.yml) using an SSH deploy key (secret name `PHP_SPLIT_DEPLOY_KEY`). Never push to the mirror directly — always edit `packages/php/` here.
+
 ## Git Conventions
 
 - Keep commit messages very short (under 100 chars preferred)

README.md

@@ -20,6 +20,38 @@ packages/
 fixtures/    Shared JSON test cases (Masker behavior parity)
 ```
 
+This monorepo is the source of truth for both packages. There's also a read-only mirror at [`gabepri/auto-html-i18n-php`](https://github.com/gabepri/auto-html-i18n-php) that contains only `packages/php/` at the repo root — it exists because Packagist requires `composer.json` at the root of a repo and doesn't support monorepo subdirectories. The mirror is auto-rebuilt on every push to `main` and on every `v*` tag by [.github/workflows/split-php.yml](.github/workflows/split-php.yml). **Don't push to the mirror directly** — it'll be overwritten on the next split.
+
+## Releasing
+
+Each package versions independently.
+
+### JS (npm)
+
+```bash
+cd packages/js
+npm version <patch|minor|major>           # bumps package.json + package-lock.json
+cd ../..
+VER=$(node -p "require('./packages/js/package.json').version")
+git add packages/js/package.json packages/js/package-lock.json
+git commit -m "$VER"
+git tag "v$VER"
+git push origin main "v$VER"
+gh release create "v$VER" --generate-notes
+```
+
+In a monorepo, `npm version` only bumps the file — it doesn't auto-commit/tag, so the steps above do that explicitly. The release-creation event triggers [.github/workflows/publish.yml](.github/workflows/publish.yml), which publishes to npm via OIDC trusted publishing (no token in repo). First-time publishing of a new package name requires `--access public` in the workflow and a trusted-publisher entry on npmjs.com.
+
+### PHP (Composer / Packagist)
+
+```bash
+git tag v1.0.1 && git push origin v1.0.1
+```
+
+That's it. The split workflow mirrors `packages/php/` to `auto-html-i18n-php` with the new tag, and Packagist's webhook on the mirror auto-syncs within a minute.
+
+The split uses an SSH deploy key — public key on the mirror repo, private key as the `PHP_SPLIT_DEPLOY_KEY` secret on this repo. Rotate by regenerating the keypair (`ssh-keygen -t ed25519`) and updating both sides.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).