From 6cec88607614933c1db7cd54599d0ea51278dbc4 Mon Sep 17 00:00:00 2001 From: sirjmann92 Date: Mon, 14 Sep 2026 13:42:37 -0500 Subject: [PATCH 1/2] docs: require user-visible changes to ship with their documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a "Documentation Is Part of the Change" section to AGENTS.md stating that any change a user can observe must land in the same PR as its docs update, with a routing table mapping change type to the file that owns it. Explicitly exempts refactors, internal helpers, test-only changes, and dependency bumps — if a user cannot tell the difference, neither can the docs. Also carries over two conventions the repo already learned the hard way: keep the README summary and the docs/ detail from duplicating each other (duplicated prose drifts exactly like the Biome pins did), and document the rationale behind non-obvious opt-in defaults. --- AGENTS.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ce52fa2..ffa8c8e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -158,6 +158,47 @@ for a webhook to come back around. - **Prefer scoped lint globs over broad prefixes.** The Biome hook is scoped to source extensions rather than a bare `^frontend/`, because tools grow support for new file types and a broad prefix silently widens what they touch. +- **Ship user-visible changes with their docs.** See below — a change a user can + see is not finished until the page describing it says so. + +--- + +## Documentation Is Part of the Change + +`docs/` is user-facing reference, not a changelog or an afterthought. **Any +change a user can observe must land in the same PR as its documentation +update.** That includes: + +- a new feature, setting, toggle, page, button, modal, or job type +- a changed default, renamed setting, or altered behaviour of an existing one +- a removed or deprecated feature +- a new or changed API endpoint, request body, or response shape +- anything that changes what the UI shows or what a user has to do + +Pure refactors, internal helpers, test-only changes, and dependency bumps do +not need a docs change — if a user cannot tell the difference, neither can the +docs. + +### Where each change goes + +| Change | Update | +| --- | --- | +| New/changed setting or default | `docs/settings.md` (the settings tables are exhaustive — keep them that way) | +| Dashboard, Movies, Shows, Jobs, or Logs page behaviour | the matching `docs/.md` | +| Sonarr/Radarr integration, webhook triggers, workflow advice | `docs/integrations.md` | +| New API endpoint or changed payload | the `## API` section in `README.md` | +| New headline capability | the Features list in `README.md`, plus the relevant `docs/` page | +| New or changed screenshot-worthy UI | refresh the affected image in `images/` | + +Two further rules, both learned the same way version pins were: + +- **Don't duplicate.** `README.md` gets the one-line summary; `docs/` gets the + detail. Repeating the detail in both guarantees they drift apart, exactly as + a version pinned in five places does. +- **Document the *why* for anything non-obvious**, especially opt-in defaults. + `general.fix_container_mismatch` ships off because enabling it makes an *arr + recreate the file record and permanently lose `sceneName` — a user reading + only "corrects the file extension" would turn it on and be surprised. --- From 29f7e028c72879be5eae22e7eb3c9cd6a5a643b6 Mon Sep 17 00:00:00 2001 From: sirjmann92 Date: Mon, 14 Sep 2026 13:43:44 -0500 Subject: [PATCH 2/2] docs: acknowledge AI tooling's role in building remuXcode MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A short footnote under Acknowledgements, above the license — stated plainly rather than as a headline, and paired with the fact that everything shipped was still reviewed, tested, and run in production. --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index c2091c1..633c800 100644 --- a/README.md +++ b/README.md @@ -192,6 +192,13 @@ curl "http://localhost:7889/api/analyze?path=/share/movies/Movie/movie.mkv" --- +## Acknowledgements + +remuXcode was built with help from AI coding tools. They accelerated +the boring parts and made a project this size tractable for a one-person team. The application has been thoroughly tested, code-reviewed, audited, and operated by human hands and eyes. + +--- + ## License MIT