From e477928ab29e931aaffbd64370858c4962cd3894 Mon Sep 17 00:00:00 2001
From: K1-R1 <77465250+K1-R1@users.noreply.github.com>
Date: Sun, 15 Mar 2026 18:08:26 +0000
Subject: [PATCH] docs: add MAINTAINING.md with operational guide

Documents the release procedure, pinned dependency inventory (automated
vs manual), known deprecation timeline (Node.js 20, June 2026), periodic
check schedule, and GitHub UI settings not tracked in code.

Signed-off-by: K1-R1 <77465250+K1-R1@users.noreply.github.com>
---
 MAINTAINING.md | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 MAINTAINING.md

diff --git a/MAINTAINING.md b/MAINTAINING.md
new file mode 100644
index 0000000..f22d596
--- /dev/null
+++ b/MAINTAINING.md
@@ -0,0 +1,94 @@
+# Maintaining smoosh
+
+Operational guide for the maintainer. For contributor instructions, see
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Cutting a release
+
+1. **Bump the version** in `smoosh` (line 8: `readonly VERSION="X.Y.Z"`).
+2. **Update CHANGELOG.md** — move items from `[Unreleased]` into a new
+   `[X.Y.Z] - YYYY-MM-DD` section.
+3. **Commit**: `git commit -s -m "chore: prepare vX.Y.Z release"`.
+4. **Tag**: `git tag --no-sign vX.Y.Z`.
+5. **Push both**: `git push origin main && git push origin vX.Y.Z`.
+6. **Verify the release workflow**:
+   - Quality gate (ShellCheck, shfmt, bats) must pass.
+   - GitHub Release is created with `smoosh`, `smoosh.sha256`, and `install.sh`.
+   - Homebrew tap auto-updates (`update-tap` job).
+7. **Check the tap** — confirm the formula SHA256 and version match:
+   `brew update && brew info K1-R1/tap/smoosh`.
+
+If the `update-tap` job fails, update the formula manually:
+download the new tarball, compute `sha256sum`, and commit to
+[K1-R1/homebrew-tap](https://github.com/K1-R1/homebrew-tap).
+
+## Pinned dependencies
+
+Dependabot handles GitHub Actions (`uses:` entries) on a monthly cycle.
+Everything else needs manual bumping.
+
+### Automated (Dependabot)
+
+| Dependency | File | Current |
+|---|---|---|
+| `actions/checkout` | `ci.yml`, `release.yml` | v6.0.2 |
+| `actions/upload-artifact` | `ci.yml` | v7.0.0 |
+| `mislav/bump-homebrew-formula-action` | `release.yml` | v3.6 |
+
+### Manual
+
+| Dependency | File(s) | Current | Check |
+|---|---|---|---|
+| shfmt | `ci.yml:32`, `release.yml:48` | v3.13.0 | [Releases](https://github.com/mvdan/sh/releases) |
+| bats-core | `ci.yml:69,108`, `release.yml:56` | v1.13.0 | [Releases](https://github.com/bats-core/bats-core/releases) |
+| actionlint | `ci.yml:41` | 1.7.11 | [Releases](https://github.com/rhysd/actionlint/releases) |
+| zizmor | `ci.yml:48` | 1.23.1 | [PyPI](https://pypi.org/project/zizmor/) |
+| markdownlint-cli2 | `prek.toml` | v0.21.0 | [npm](https://www.npmjs.com/package/markdownlint-cli2) |
+| cspell | `prek.toml` | 9 | [npm](https://www.npmjs.com/package/cspell) |
+
+When bumping a manual dependency: update the version pin, run CI locally
+(`prek run && bats test/*.bats`), and commit with
+`chore: bump <tool> to vX.Y.Z`.
+
+## Known deprecation
+
+`mislav/bump-homebrew-formula-action` v3.6 uses the Node.js 20 runtime,
+which GitHub deprecates in **June 2026**. Watch for a v4 release or plan
+a replacement (a shell script in the release workflow that computes the
+SHA256 and commits to the tap directly).
+
+## Periodic checks
+
+**Quarterly — dependency audit**
+
+Check the manual dependencies table above for new releases. Bump, test,
+commit.
+
+**Semi-annually — README accuracy**
+
+Verify external claims haven't changed:
+
+- NotebookLM source limits (currently: 500k words/source, Free 50 / Plus
+  300 / Ultra 600 sources)
+- Installation URLs still resolve
+- Third-party integration steps (Claude Projects, ChatGPT) still match
+  their current UIs
+
+**On issue/PR activity**
+
+Aim to triage new issues within a week. For PRs: check CI passes, DCO is
+signed, and changes match the project's scope.
+
+## Repo configuration
+
+These settings are applied via the GitHub UI, not tracked in code:
+
+- **Branch ruleset on `main`**: require PR, block force push, require
+  status checks (lint, test, bash32).
+- **Tag ruleset**: require tag match `v*`, bypass actor: repository admin.
+- **Merge policy**: squash merge only, delete branch on merge.
+- **GitHub topics**: `bash`, `cli`, `rag`, `llm`, `notebooklm`,
+  `knowledge-base`, `developer-tools`, `context-window`.
+- **HOMEBREW_TAP_TOKEN**: fine-grained PAT scoped to `K1-R1/homebrew-tap`
+  (Contents: read+write). Stored in the `homebrew` environment on this
+  repo.