@sacho/sacho-aarch64-apple-darwin 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-aarch64-apple-darwin",
-  "version": "0.1.0-dev.9+eaee87c",
+  "version": "0.2.0",
   "description": "The Sacho binary for aarch64-apple-darwin",
   "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"