Prepare v3.6.0 release notes and publishing doc (#117)

Rename the Unreleased section to v3.6.0 with today's
date and add the matching tag link reference. Rewrite
the publishing how-to to use npm version (per the
Release Process in the Version Control Standard) and
add the GitHub Release step mandated by that standard.

Author: virtualian

RELEASE_NOTES.md

@@ -4,7 +4,7 @@ All notable user-visible changes to MARR are documented here. The format follows
 
 This file is the canonical, in-repo history. Each section is mirrored in a corresponding [GitHub Release](https://github.com/virtualian/marr/releases).
 
-## Unreleased
+## [v3.6.0] — 2026-05-10
 
 ### Added
 - `marr update --project` — refresh canonical standards into a previously-installed project. Hash manifest at `.claude/marr/.marr-version.json` distinguishes locally-edited files (prompted) from canonical advancement (silent refresh). Flags: `--check` (drift report, non-zero exit), `--prune` (remove orphans), `--dry-run`, `--force`. `marr init --project` now writes the manifest so first-time installs are tracked. (closes [#111](https://github.com/virtualian/marr/issues/111), partially addresses [#86](https://github.com/virtualian/marr/issues/86))
@@ -108,6 +108,7 @@ First public npm release as `@virtualian/marr`.
 ### Changed
 - Project rebranded from `repo-setup` to `marr` ([#9](https://github.com/virtualian/marr/pull/9))
 
+[v3.6.0]: https://github.com/virtualian/marr/releases/tag/v3.6.0
 [v3.5.0]: https://github.com/virtualian/marr/releases/tag/v3.5.0
 [v3.1.0]: https://github.com/virtualian/marr/releases/tag/v3.1.0
 [v3.0.0]: https://github.com/virtualian/marr/releases/tag/v3.0.0

docs/dev/how-to/publishing.md

@@ -1,34 +1,37 @@
 # Publishing MARR
 
-This guide covers how to publish a new MARR release to npm.
+This guide publishes a new MARR release to npm and GitHub.
+
+The Version Control Standard requires every tagged release to have **both** an updated section in `RELEASE_NOTES.md` and a published GitHub Release. This procedure produces both.
 
 ## Before Publishing
 
-1. **Run the test suite** — See [testing.md](./testing.md)
-2. **Verify all tests pass** in the testuser account
-3. **Check you're on main** with a clean working directory
+1. **All PRs for the release are merged to main**
+2. **Local main is up to date** — `git checkout main && git pull`
+3. **Working directory is clean** — `git status` shows nothing
+4. **Tests pass** — `npm test` (see [testing.md](./testing.md))
+5. **`RELEASE_NOTES.md` is up to date** — rename the `## Unreleased` heading to `## [vX.Y.Z] — YYYY-MM-DD` and add a matching `[vX.Y.Z]: https://github.com/virtualian/marr/releases/tag/vX.Y.Z` link reference at the bottom of the file
+6. **`KNOWN_ISSUES.md` reflects current state** — new issues added, resolved issues removed
+7. **You are logged in to npm** — `npm whoami` returns the publishing account; if not, run `npm login`
 
-## Release Process
+Steps 1–6 must be merged to main via PR before continuing. Do not run the release commands on a feature branch.
 
-### 1. Bump Version
+## Release Process
 
-Use the release script:
+### 1. Bump Version, Commit, and Tag
 
 ```bash
-./scripts/release.sh patch   # 2.0.0 → 2.0.1
-./scripts/release.sh minor   # 2.0.0 → 2.1.0
-./scripts/release.sh major   # 2.0.0 → 3.0.0
+npm version patch   # 3.6.0 → 3.6.1   (bug fixes only)
+npm version minor   # 3.6.0 → 3.7.0   (new features, backward-compatible)
+npm version major   # 3.6.0 → 4.0.0   (breaking changes)
 ```
 
-This script:
-- Updates version in package.json
-- Builds the TypeScript
-- Creates a git commit and tag
+`npm version` updates `package.json` and `package-lock.json`, creates a commit containing only the version bump, and creates an annotated tag — atomically.
 
-### 2. Push to GitHub
+### 2. Push Commit and Tag
 
 ```bash
-git push origin main --tags
+git push && git push --tags
 ```
 
 ### 3. Publish to npm
@@ -37,15 +40,25 @@ git push origin main --tags
 npm publish --access public
 ```
 
-### 4. Verify Publication
+The `prepublishOnly` hook re-runs the binary check, build, and tests as a final gate before the package is uploaded.
+
+### 4. Create the GitHub Release
+
+The Release body must mirror the new version's section in `RELEASE_NOTES.md`. Extract that section to a temporary file, then publish:
 
 ```bash
-# Check npm registry
-npm view @virtualian/marr
+# Replace vX.Y.Z with the tag you just pushed
+gh release create vX.Y.Z \
+  --title "vX.Y.Z" \
+  --notes-file <path-to-extracted-section.md>
+```
+
+### 5. Verify Publication
 
-# Test installation
-npm install -g @virtualian/marr
-marr --version
+```bash
+npm view @virtualian/marr version            # should match the new tag
+gh release view vX.Y.Z                       # should show the published Release
+npm install -g @virtualian/marr && marr --version
 ```
 
 ## Versioning Guidelines
@@ -54,14 +67,18 @@ Follow semantic versioning:
 
 | Change Type | Version Bump | Example |
 |-------------|--------------|---------|
-| Bug fixes, doc updates | patch | 2.0.0 → 2.0.1 |
-| New features (backward compatible) | minor | 2.0.0 → 2.1.0 |
-| Breaking changes | major | 2.0.0 → 3.0.0 |
+| Bug fixes, doc updates | patch | 3.6.0 → 3.6.1 |
+| New features (backward compatible) | minor | 3.6.0 → 3.7.0 |
+| Breaking changes | major | 3.6.0 → 4.0.0 |
 
 ## Troubleshooting
 
-**403 Forbidden** — Run `npm login` and verify with `npm whoami`
+**401 / 403 from npm** — Run `npm login` and verify with `npm whoami`
 
 **Package name taken** — MARR uses `@virtualian/marr` (scoped package)
 
-**Version already exists** — You cannot republish the same version; bump and try again
+**Version already exists on npm** — You cannot republish the same version; bump and try again
+
+**Tag pushed but `gh release create` fails** — The tag is on origin without a published Release. Re-run `gh release create vX.Y.Z` against the same tag.
+
+**`prepublishOnly` failed** — The build or tests failed inside `npm publish`. Fix the issue on a feature branch, merge, and re-tag with the next patch version. Never reuse a published or pushed tag.