@sacho/sacho 0.1.0-dev.9 → 0.2.0

package/README.md

@@ -1,6 +1,27 @@
 Sacho: an opinionated changelog manager
 =======================================
 
+[![GitHub Releases][GitHub Releases badge]][GitHub Releases]
+[![crates.io][crates.io badge]][crates.io]
+[![npm][npm badge]][npm]
+[![GitHub Actions][GitHub Actions badge]][GitHub Actions]
+[![License: GPL-3.0-only][GPL-3.0 badge]][GPL-3.0]
+[![GitHub Sponsors][GitHub Sponsors badge]][GitHub Sponsors]
+
+[GitHub Releases badge]: https://img.shields.io/github/v/release/dahlia/sacho?logo=github
+[GitHub Releases]: https://github.com/dahlia/sacho/releases
+[crates.io badge]: https://img.shields.io/crates/v/sacho?logo=rust
+[crates.io]: https://crates.io/crates/sacho
+[npm badge]: https://img.shields.io/npm/v/@sacho/sacho?logo=npm
+[npm]: https://www.npmjs.com/package/@sacho/sacho
+[GitHub Actions badge]: https://github.com/dahlia/sacho/actions/workflows/main.yaml/badge.svg
+[GitHub Actions]: https://github.com/dahlia/sacho/actions/workflows/main.yaml
+[GPL-3.0 badge]: https://img.shields.io/github/license/dahlia/sacho
+[GPL-3.0]: https://www.gnu.org/licenses/gpl-3.0.html
+[GitHub Sponsors badge]: https://img.shields.io/github/sponsors/dahlia?logo=githubsponsors
+[GitHub Sponsors]: https://github.com/sponsors/dahlia
+
+
 Motivation
 ----------
 
@@ -18,7 +39,7 @@ towncrier assumes Python; changesets assumes an npm monorepo. Sacho is a single
 static binary with no runtime dependencies, usable in any repository regardless
 of language, and it does not even assume Git.
 
-[Sacho is opinionated.](./PHILOSOPHY.md) It enforces one fragment format,
+[*Sacho is opinionated.*](./PHILOSOPHY.md) It enforces one fragment format,
 one output style, and one set of invariants. Configuration exists to describe
 your repository, not to customize the philosophy.
 
@@ -52,7 +73,51 @@ Without mise, npm, or Cargo, download the archive for your platform from
 *sacho* (*sacho.exe* on Windows) into a directory on your `PATH`.
 
 [mise]: https://mise.jdx.dev/
-[GitHub Releases]: https://github.com/dahlia/sacho/releases
+
+
+Agent Skill
+-----------
+
+Sacho ships an [Agent Skill] that teaches AI coding agents, such as Claude Code,
+how to adopt and operate Sacho: writing fragments for users, cutting releases,
+and forward-porting fixes across maintenance branches.
+
+In Claude Code, install it as a plugin. Add this repository as a plugin
+marketplace, then install the `sacho` plugin:
+
+~~~~ text
+/plugin marketplace add dahlia/sacho
+/plugin install sacho@sacho
+~~~~
+
+For other agents, or to install the skill without the plugin system, use the
+[`skills`] CLI, which reads the skill straight from this repository:
+
+~~~~ sh
+npx skills add dahlia/sacho
+~~~~
+
+Add `-a claude-code` to target one agent, `-g` to install it globally, and
+`--skill sacho` to select the skill by name.
+
+The skill is also bundled inside the `@sacho/sacho` npm package, following the
+[`skills-npm`] layout. In a project that depends on that package, run
+`npx skills-npm setup` once to link bundled skills from *node\_modules* into
+your agent on every install.
+
+[Agent Skill]: https://agentskills.io/
+[`skills`]: https://github.com/vercel-labs/skills
+[`skills-npm`]: https://github.com/antfu/skills-npm
+
+
+Documentation
+-------------
+
+The [*Sacho documentation*] walks through adoption, everyday use, releases,
+CI, and version-control integration. It also explains Sacho's core concepts and
+provides complete command and configuration references.
+
+[*Sacho documentation*]: https://sacho.dev/guide/getting-started
 
 
 How it works
@@ -82,21 +147,37 @@ state that never shipped.
 Basic workflow
 --------------
 
-With `sacho` on your `PATH`, initialize it at the repository root and choose
-the version you are preparing:
+With `sacho` on your `PATH`, initialize it at the repository root:
 
 ~~~~ sh
 sacho init
-sacho next 1.2.0
 ~~~~
 
 Initialization creates *sacho.toml*, *changes.d/*, and *CHANGES.md*. It also
 sets up the merge integration supported by the detected version-control
 system. The interactive setup can infer an issue-link template from the
-repository URL and offer to install a Git pre-commit hook. Repository
+repository URL, offer headings found across an existing changelog as section
+configuration, and offer to install a Git pre-commit hook. Repository
 integrations use the executable that ran `init`; pass
 `--integration-executable PATH` to use another executable.
 
+If an existing *CHANGES.md* already has entries under `Unreleased` or
+`Version X`, import them before creating new fragments:
+
+~~~~ sh
+sacho import-unreleased
+~~~~
+
+Sacho shows any normalization diff before writing. The import creates one root
+fragment, or one fragment per populated configured section, records `X` as the
+next version when present, and leaves every released section unchanged.
+
+If the import did not infer a version, choose the version you are preparing:
+
+~~~~ sh
+sacho next 1.2.0
+~~~~
+
 Create one fragment for each user-visible change, then edit the path printed by
 the command:
 
@@ -116,6 +197,7 @@ before committing:
 
 ~~~~ sh
 sacho fmt
+sacho resolve-links  # optional: pin final redirected reference URLs
 sacho preview
 sacho check
 ~~~~
@@ -128,15 +210,27 @@ staged Git changes or `sacho check --base <revision>` in CI.
 
 When the version is ready, compile and consume its fragments. This command
 releases the version stored by `sacho next`, uses the current local date, and
-starts the next version:
+closes the materialized unreleased region:
 
 ~~~~ sh
-sacho release --next 1.3.0
+sacho release
 ~~~~
 
 If no next version has been set, pass the release version explicitly, for
 example `sacho release 1.2.0`. Use `--date YYYY-MM-DD` when the release date
-must be supplied rather than taken from the local clock.
+must be supplied rather than taken from the local clock. A repository with no
+released changelog sections can cut its first release without fragments. Later
+empty releases require an explicit `--allow-empty`.
+
+Commit and tag that released-only state. When development resumes, start the
+next cycle separately:
+
+~~~~ sh
+sacho next 1.3.0
+~~~~
+
+Pass `--next 1.3.0` to `sacho release` only when the release commit should also
+open the next cycle and retain its empty materialized region.
 
 After committing a release, print its frozen Markdown section with `show`:
 
@@ -161,7 +255,8 @@ Version-control integration
 ---------------------------
 
 Sacho can enforce that commits changing configured source paths also carry a
-changelog fragment. Select the repository's VCS in *sacho.toml*:
+changelog fragment. Select the repository's VCS and the paths to check in
+*sacho.toml*:
 
 ~~~~ toml
 [vcs]
@@ -176,41 +271,6 @@ Git also supports `sacho check --staged`. The `none` preset explicitly skips
 VCS-backed checks while leaving fragment validation and changelog consistency
 checks enabled.
 
-Each preset supplies three subprocess commands. Repositories can override one
-command without repeating the other two:
-
-~~~~ toml
-[vcs]
-preset = "git"
-
-[vcs.commands]
-message = ["my-vcs-wrapper", "message", "${commit}"]
-~~~~
-
-The first array element is the executable and every remaining element is one
-literal argument; Sacho never invokes a shell. The commits command uses
-`${base}`, while changed-paths and message use `${commit}`. An overridden query
-is the complete query and does not invoke commands from its preset behind the
-scenes. The built-in Mercurial preset handles parent comparisons internally.
-
-The query output contracts are:
-
- -  `commits` emits zero or more nonempty UTF-8 commit identifiers, oldest
-    first and one per line. The final line may end in LF; CRLF is also
-    accepted.
- -  `changed-paths` emits concatenated NUL-terminated name-status records.
-    Ordinary records are `A\0PATH\0`, `D\0PATH\0`, `M\0PATH\0`, or
-    `T\0PATH\0`, where `T` denotes a file type change. Copy and rename records
-    are `C[SIMILARITY]\0OLD_PATH\0NEW_PATH\0` and
-    `R[SIMILARITY]\0OLD_PATH\0NEW_PATH\0`, where the optional similarity is a
-    decimal percentage from 0 through 100. Status fields are UTF-8 and paths
-    are nonempty repository-relative platform paths; path bytes need not be
-    UTF-8 on Unix. Nonempty output ends in NUL. A copied or renamed fragment
-    counts as new content only when similarity is present and below 100;
-    omitting it does not satisfy fragment coverage.
- -  `message` emits the complete UTF-8 commit message verbatim. Sacho does not
-    trim it.
-
 `sacho init` installs Git merge attributes and drivers in Git repositories. In
 Mercurial repositories it installs an idempotent block in *.hg/hgrc* containing
 a successful-merge update hook and, when changelog materialization is enabled,
@@ -219,6 +279,12 @@ the changelog merge driver. These integrations invoke the executable that ran
 per-path merge-driver hook; after resolving a concurrent fragment merge, run
 `sacho sync --force`.
 
+See [*CI and hooks*] for fragment coverage and [*Version control*] for preset,
+merge-driver, and custom-query details.
+
+[*CI and hooks*]: https://sacho.dev/guide/ci-and-hooks
+[*Version control*]: https://sacho.dev/guide/version-control
+
 
 Etymology
 ---------
@@ -243,3 +309,13 @@ is the same insistence this tool makes against generating changelogs from
 commit messages after the fact.
 
 [1]: https://en.wikipedia.org/wiki/Veritable_Records_of_the_Joseon_Dynasty#Compilation_process
+
+
+License
+-------
+
+Copyright (C) 2026 Hong Minhee.
+
+Sacho is free software licensed under the GNU General Public License version 3
+only. It comes with no warranty, to the extent permitted by law. See
+[*LICENSE*](./LICENSE) for the full terms.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@sacho/sacho",
-  "version": "0.1.0-dev.9+eaee87c",
+  "version": "0.2.0",
   "description": "An opinionated changelog manager",
   "license": "GPL-3.0-only",
   "author": "Hong Minhee <hong@minhee.org>",
-  "homepage": "https://github.com/dahlia/sacho",
+  "homepage": "https://sacho.dev/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/dahlia/sacho.git"
@@ -17,18 +17,19 @@
   },
   "files": [
     "bin",
-    "lib"
+    "lib",
+    "skills"
   ],
   "engines": {
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@sacho/sacho-aarch64-apple-darwin": "0.1.0-dev.9+eaee87c",
-    "@sacho/sacho-aarch64-pc-windows-msvc": "0.1.0-dev.9+eaee87c",
-    "@sacho/sacho-aarch64-unknown-linux-musl": "0.1.0-dev.9+eaee87c",
-    "@sacho/sacho-x86_64-apple-darwin": "0.1.0-dev.9+eaee87c",
-    "@sacho/sacho-x86_64-pc-windows-msvc": "0.1.0-dev.9+eaee87c",
-    "@sacho/sacho-x86_64-unknown-linux-musl": "0.1.0-dev.9+eaee87c"
+    "@sacho/sacho-aarch64-apple-darwin": "0.2.0",
+    "@sacho/sacho-aarch64-pc-windows-msvc": "0.2.0",
+    "@sacho/sacho-aarch64-unknown-linux-musl": "0.2.0",
+    "@sacho/sacho-x86_64-apple-darwin": "0.2.0",
+    "@sacho/sacho-x86_64-pc-windows-msvc": "0.2.0",
+    "@sacho/sacho-x86_64-unknown-linux-musl": "0.2.0"
   },
   "publishConfig": {
     "access": "public",

package/skills/sacho/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: sacho
+description: >-
+  Help a maintainer adopt and operate Sacho, the opinionated changelog manager
+  that keeps user-facing release notes as one small Markdown fragment per change
+  under changes.d/ and compiles them into CHANGES.md at release time. Use this
+  skill whenever a repository has a sacho.toml, a changes.d/ directory, or a
+  CHANGES.md built from fragments; whenever the user wants to add Sacho to a
+  project, write or edit a changelog entry for a change they just made, cut a
+  release, publish release notes, or wire `sacho check` into CI or a pre-commit
+  hook; whenever forward-porting a bugfix release across maintenance branches or
+  resolving a changelog merge conflict; and whenever `sacho check` or the
+  changelog merge driver reports a problem. Also use it any time the user
+  mentions Sacho, changes.d fragments, or asks how to write a changelog entry
+  for users instead of generating one from commit messages.
+metadata:
+  type: reference
+---
+
+Managing changelogs with Sacho
+==============================
+
+Sacho keeps a project's release notes as one small Markdown file per change,
+called a fragment, under `changes.d/`. At release time it sorts and compiles the
+fragments into a dated section of `CHANGES.md`, then deletes the consumed
+fragments. It works in any repository regardless of language, ships as a single
+static binary, and does not even assume Git.
+
+The single most important thing to hold onto: Sacho never generates entries from
+commit messages, and neither should you. A commit message explains to
+collaborators why a change was made; a changelog entry tells users what changed
+and what to do when they upgrade. Those are different documents for different
+readers. When you draft an entry, do not transform a diff or a `git log` line
+into prose. Read the change, work out its effect on someone who only sees the
+public surface, and write that. When a change has no user-visible effect, the
+honest entry is no entry.
+
+
+Delegate the details to the live docs
+-------------------------------------
+
+The commands and flags below are a working map, not the source of truth. For the
+exact syntax of the version installed in this repository, trust `sacho --help`
+and `sacho <command> --help` over anything written here or online, because the
+docs track the latest release while a project may pin an older binary. Use the
+Markdown documentation for concepts, workflow, and reasoning; reach for `--help`
+before you depend on a specific flag or output format.
+
+ -  `https://sacho.dev/llms.txt` lists every page.
+    `https://sacho.dev/llms-full.txt` is the whole documentation in one file
+    when you want to read broadly.
+ -  Every page has a `.md` twin. Fetch these directly:
+     -  `https://sacho.dev/why-sacho.md` and `https://sacho.dev/philosophy.md`
+        for the reasoning, worth reading before you write entries for a project.
+     -  `https://sacho.dev/guide/getting-started.md` to adopt Sacho.
+     -  `https://sacho.dev/guide/everyday-workflow.md` for the per-change loop.
+     -  `https://sacho.dev/guide/releases.md` for cutting releases and
+        forward-porting.
+     -  `https://sacho.dev/guide/ci-and-hooks.md` for coverage enforcement.
+     -  `https://sacho.dev/guide/version-control.md` for merge drivers and
+        presets.
+     -  `https://sacho.dev/concepts/fragments.md`,
+        `https://sacho.dev/concepts/changelog-lifecycle.md`, and
+        `https://sacho.dev/concepts/sections.md` for the model.
+     -  `https://sacho.dev/reference/commands.md` and
+        `https://sacho.dev/reference/configuration.md` for exhaustive
+        references.
+     -  `https://sacho.dev/troubleshooting.md` when something misbehaves.
+
+
+Orient yourself before acting
+-----------------------------
+
+Check what the repository already has. Is there a `sacho.toml` at the root, a
+`changes.d/` directory, a `CHANGES.md`? Is `sacho` on the `PATH`
+(`sacho --version`)? A repository with `sacho.toml` is already set up, so skip
+adoption and go to the workflow that fits the request. A repository without it
+needs `sacho init` first, but only after confirming the maintainer wants to
+adopt Sacho rather than asking about it.
+
+If the binary is missing, the recommended install is
+`mise use -g github:dahlia/sacho`; `npm install -g @sacho/sacho` and
+`cargo install sacho` work too. Read `getting-started.md` for the full list.
+
+
+Adopting Sacho in a project
+---------------------------
+
+Run `sacho init` from the repository root. It creates `sacho.toml`,
+`changes.d/`, and `CHANGES.md`, and in a Git repository registers the merge
+drivers. Interactive setup infers issue-link templates from the remote and can
+install commit hooks. When an existing changelog is present, it also offers
+level-three headings found across the changelog as section candidates and
+suggests directories and source path globs. `sacho init --interactive` forces
+the questions and `--no-interactive` suppresses them.
+
+Leave old released sections exactly as they are. If the current `Unreleased` or
+`Version X` region contains entries, run `sacho import-unreleased` before
+creating fragments. Inspect and confirm its normalization diff; in a
+noninteractive workflow, review the diff from the refused run before using
+`--force`. The command creates deterministic *imported-unreleased.md* fragments
+and infers the next version from `Version X`. If there are no current entries,
+skip the import and set the version with `sacho next 1.2.0`.
+
+Two configuration decisions matter early, both covered in
+`reference/configuration.md`: whether to enforce fragment coverage
+(`[check].paths`), and, for a monorepo, whether to define `[[sections]]` so each
+package's changes require a fragment in that package's section.
+
+
+Writing a fragment for a change
+-------------------------------
+
+The everyday loop is four commands. Create the fragment, write it, format, and
+check:
+
+~~~~ sh
+sacho add clear-function      # add --section <id> <name> in a sectioned repo
+sacho fmt
+sacho preview
+sacho check
+~~~~
+
+`sacho add` creates `changes.d/<name>.md` holding an empty list item and prints
+the path. Name the file after the change itself (`clear-function`), never after
+an issue or PR number. Topic names make the right follow-up natural: when a
+later commit reworks the same feature, you edit the existing fragment instead of
+adding a second one that documents a state users never saw.
+
+Keep the fragment in the same commit series as the implementation. Stored in the
+repository, it travels with the change through merges, rebases, cherry-picks,
+and reverts for free. That coupling is the whole point of fragments, so never
+park changelog text in an issue, a wiki, or a draft release note.
+
+
+Writing entries users can actually read
+---------------------------------------
+
+This is the part no tool can do for the maintainer, and where you earn your
+keep. Fetch `philosophy.md` when you want the full argument; the working rules:
+
+Address the person upgrading, in the vocabulary of the public surface. A
+refactor that touches forty files but changes nothing users can observe is a
+real commit and a nonexistent entry. A one-line dependency bump that closes a
+vulnerability is a trivial commit and a critical entry.
+
+Write one entry per user-visible change. If a release adds `remove_all()` and a
+later commit in the same cycle renames it to `clear()`, the released changelog
+contains a single line, `Added clear() function`, not the two-step history. Edit
+the existing fragment; never narrate intermediate states that never shipped.
+
+Be concise, and keep internal names out. Private type names, module paths, and
+subsystem nicknames tell the reader this document is not for them. If a
+mechanism must be mentioned, describe what it does rather than naming a thing
+the reader cannot look up.
+
+Start each entry with a past-tense verb: Added, Changed, Deprecated, Fixed,
+Removed, Security. Sacho sorts by the entry text, so these verbs fall into the
+familiar Keep a Changelog order without any category metadata.
+
+Reference issues and PRs with shortcut links in trailing brackets, house style,
+at the end of the first paragraph: `[[#842], [#848]]`. Attribution is inline
+prose in the same bracket: `[[#857] by Lee Hoyeon]`. The compiler resolves the
+numbers into link definitions using the templates in `[links]`, and `check`
+fails on a reference no template can resolve.
+
+Because Sacho asks a human to write, present your drafts to the maintainer for
+approval rather than committing prose in their voice unreviewed. You are helping
+them write for their users, not automating the writing away.
+
+
+The fragment file format
+------------------------
+
+A fragment is a UTF-8 Markdown file whose body is exactly one top-level
+unordered list, with optional YAML frontmatter. Nothing else at the top level:
+no headings, no stray paragraphs, no second list. Inside a list item any block
+content is fine, including nested lists and fenced code. One item is usual;
+related changes from one pull request can share a fragment as several items.
+
+~~~~ markdown
+---
+priority: -10
+---
+
+ -  Added `clear()` to remove every entry at once.  The function accepts an
+    optional predicate to remove entries selectively.  [[#842], [#848]]
+~~~~
+
+`priority` (integer, default `0`) is the only frontmatter key; lower sorts
+earlier, and most fragments need no frontmatter at all. See
+`concepts/fragments.md` for the exact constraints.
+
+
+Cutting a release
+-----------------
+
+Read the compiled result as a user would before you freeze it:
+
+~~~~ sh
+sacho next 1.2.0
+sacho preview
+sacho check
+~~~~
+
+In the preview, merge entries that describe the same change, drop development
+history, and confirm each entry names public behavior. Then compile:
+
+~~~~ sh
+sacho release --next 1.3.0            # reads the version from changes.d/next
+sacho release 1.2.0 --next 1.3.0      # or state the version explicitly
+sacho release 1.2.0 --date 2026-07-19 --next 1.3.0   # when the date must be fixed
+~~~~
+
+`release` stamps the dated section, deletes the consumed fragments, and sets the
+next version. The first release may proceed without fragments when the changelog
+has no released version sections. Later releases refuse to proceed when the
+fragments compile to nothing unless `--allow-empty` is passed. Empty list items
+and HTML comments are scaffolding, not release notes, and scaffold-only
+fragments require the explicit option even on the first release. Commit the
+changed `CHANGES.md`, the removed fragments, and the updated `changes.d/next`
+together.
+
+
+Publishing release notes
+------------------------
+
+After the release commit, `sacho show` prints one frozen section:
+
+~~~~ sh
+sacho show 1.2.0
+sacho show 1.2.0 --skip-heading --output-file release-notes.md
+~~~~
+
+A tag-triggered GitHub Actions job can hand that file to the GitHub CLI:
+
+~~~~ sh
+version="${GITHUB_REF_NAME#v}"
+sacho show "$version" --skip-heading --output-file release-notes.md
+gh release create "$GITHUB_REF_NAME" --notes-file release-notes.md
+~~~~
+
+`show` reads only released sections; it never compiles current fragments.
+
+
+Enforcing coverage in CI and hooks
+----------------------------------
+
+Configure the paths whose changes require a fragment, then let a machine catch
+the omissions reviewers miss:
+
+~~~~ toml
+[check]
+paths = ["src/**", "packages/**"]
+~~~~
+
+Locally, `sacho check --staged` inspects the Git index;
+`sacho init --install-hook` installs a pre-commit hook chain. In CI, check a
+branch commit-by-commit against its base:
+
+~~~~ sh
+sacho check --base origin/main
+~~~~
+
+Make sure the checkout history includes the base revision; a shallow clone that
+omits it cannot support the comparison. A commit that genuinely needs no entry
+opts out with a `Changelog: none` trailer in its message (or the
+`[skip changelog]` family of substrings). The exemption applies only to the
+commit that carries it. Details in `guide/ci-and-hooks.md`.
+
+
+Forward-porting a bugfix release across maintenance branches
+------------------------------------------------------------
+
+The scenario: a fix lands on `1.1-maintenance`, `1.1.5` ships, and the fix needs
+to reach `1.2-maintenance` and `main`. Two paths, and which one you are on
+decides the work.
+
+Merge before releasing, and there is nothing to do. If you merge
+`1.1-maintenance` into `1.2-maintenance` while the fix's fragment still exists,
+the VCS carries the fragment along, and each branch later consumes its own copy.
+Prefer this ordering when you can; it needs no Sacho command.
+
+Merge the release tag, and the fragment arrives already consumed. The incoming
+`1.1.5` release commit deleted the fragment, so the merge brings only the frozen
+`1.1.5` section. The merge driver inserts that section at its version position
+in `CHANGES.md`, keeps the receiving branch's `changes.d/next`, and prints a
+`sacho carry` hint on stderr. Now it is policy, not mechanics: if the receiving
+branch's own next release should also list the fix, run `sacho carry 1.1.5` to
+decompile that section back into `carried-from-1.1.5.md` fragments, edit them
+if this branch presents the change differently, and treat them as ordinary
+unreleased entries. If the imported `1.1.5` section is enough, do nothing.
+
+`carry` is idempotent by design: it always writes the same
+`carried-from-<version>.md` name and overwrites any file already there. That is
+safe on a fresh carry, but if you have already edited those carried fragments,
+re-running `carry` discards your edits, so check for existing
+`carried-from-*.md` files before repeating it.
+
+Under Jujutsu there is no per-path merge driver, so after resolving a concurrent
+fragment merge run `sacho sync --force` and inspect the result.
+`guide/releases.md` and `guide/version-control.md` cover both.
+
+
+When something goes wrong
+-------------------------
+
+`sacho check` reports across three layers: fragment validity and formatting,
+agreement between the materialized unreleased region and the fragments, and
+fragment coverage for changed paths.
+
+A formatting or drift failure is mechanically repairable. `sacho check --fix`
+runs `fmt` and re-syncs the generated region; it will not write prose. If
+`CHANGES.md` was hand-edited, remember that fragments are the source of truth:
+move the edited text into a fragment, then `sacho sync`. Sacho asks before
+discarding hand edits, and `sacho sync --force` skips that prompt, so read the
+diff first.
+
+A missing-fragment failure names the affected section and suggests `sacho add`.
+Either write the entry or, if the commit truly has no user-visible effect, use
+the `Changelog: none` exemption. For anything stranger, fetch
+`troubleshooting.md`.