@ferrflow/doc 7.17.0

package/docs-v6/configuration/formats.md

@@ -0,0 +1,206 @@
+---
+title: Supported formats
+description: Version file formats that FerrFlow can read and update.
+---
+
+<div class="ferr-tabs">
+  <div class="ferr-tab" data-label="JSON"><p class="ferr-tab__label">JSON</p><div class="ferr-tab__body"><p>Used by Node.js (<code>package.json</code>).</p>
+<p>FerrFlow updates the top-level <code>version</code> field.</p>
+<pre><code class="language-json">{
+  &quot;name&quot;: &quot;my-package&quot;,
+  &quot;version&quot;: &quot;1.2.3&quot;
+}
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="TOML"><p class="ferr-tab__label">TOML</p><div class="ferr-tab__body"><p>Used by Rust (<code>Cargo.toml</code>) and Python (<code>pyproject.toml</code>).</p>
+<p>FerrFlow updates the <code>version</code> field under <code>[package]</code>, <code>[project]</code>, or <code>[tool.poetry]</code>.</p>
+<pre><code class="language-toml">[package]
+name = &quot;my-crate&quot;
+version = &quot;1.2.3&quot;   # ← updated
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="XML"><p class="ferr-tab__label">XML</p><div class="ferr-tab__body"><p>Used by Java/Maven (<code>pom.xml</code>).</p>
+<p>FerrFlow updates the first <code>&lt;version&gt;</code> element it encounters.</p>
+<pre><code class="language-xml">&lt;project&gt;
+  &lt;groupId&gt;com.example&lt;/groupId&gt;
+  &lt;artifactId&gt;my-app&lt;/artifactId&gt;
+  &lt;version&gt;1.2.3&lt;/version&gt;   &lt;!-- updated --&gt;
+&lt;/project&gt;
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="Gradle"><p class="ferr-tab__label">Gradle</p><div class="ferr-tab__body"><p>Used by Java/Kotlin Gradle projects (<code>build.gradle</code>, <code>build.gradle.kts</code>).</p>
+<p>FerrFlow updates the <code>version = &quot;...&quot;</code> assignment.</p>
+<pre><code class="language-groovy">version = &quot;1.2.3&quot;   // updated
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="Plain text"><p class="ferr-tab__label">Plain text</p><div class="ferr-tab__body"><p>Used for simple version files (<code>VERSION</code>, <code>VERSION.txt</code>).</p>
+<p>FerrFlow replaces the entire file content with the version number.</p>
+<pre><code>1.2.3
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="Go"><p class="ferr-tab__label">Go</p><div class="ferr-tab__body"><p>Used by Go projects (<code>go.mod</code>).</p>
+<p>Go modules use git tags directly — FerrFlow does <strong>not</strong> modify <code>go.mod</code>. The version is derived entirely from the git tag (<code>v1.2.3</code> or <code>{name}@v1.2.3</code>).</p>
+<p>On a brand-new repo with no matching tag yet, FerrFlow v3+ bootstraps from the strategy&#39;s zero value (<code>0.0.0</code> for <code>semver</code>, <code>0</code> for <code>sequential</code>, …) and creates the first real tag itself — you do not need to run <code>git tag … v0.0.0</code> before the first release. See <a href="/docs/reference/cli#which-version-is-bumped-from">how <code>release</code> picks the baseline</a>.</p>
+</div></div>
+  <div class="ferr-tab" data-label="Helm"><p class="ferr-tab__label">Helm</p><div class="ferr-tab__body"><p>Used by Kubernetes Helm charts (<code>Chart.yaml</code>).</p>
+<p>FerrFlow updates the <code>version</code> field and, when present, keeps <code>appVersion</code> in sync.</p>
+<p>The newer <code>chartyaml</code> alias is functionally equivalent — use whichever reads more naturally in your config.</p>
+<pre><code class="language-yaml">apiVersion: v2
+name: my-app
+version: 1.2.3        # ← updated
+appVersion: &quot;1.2.3&quot;   # ← updated when present
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="Dart"><p class="ferr-tab__label">Dart</p><div class="ferr-tab__body"><p>Used by Dart and Flutter packages (<code>pubspec.yaml</code>).</p>
+<p>FerrFlow updates the top-level <code>version:</code> key, leaving dependency versions, anchors, and comments intact. SemVer build suffixes (<code>1.2.3+42</code>) are supported.</p>
+<pre><code class="language-yaml">name: my_app
+version: 1.2.3+42     # ← updated
+dependencies:
+  some_pkg:
+    version: 2.0.0    # untouched — this is a dep constraint
+</code></pre>
+<p>Config snippet:</p>
+<pre><code class="language-toml">[[package.versioned_files]]
+path   = &quot;pubspec.yaml&quot;
+format = &quot;pubspecyaml&quot;
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="Elixir"><p class="ferr-tab__label">Elixir</p><div class="ferr-tab__body"><p>Used by Elixir / Mix projects (<code>mix.exs</code>).</p>
+<p>FerrFlow updates the first <code>version: &quot;…&quot;</code> literal it finds — the canonical spot is inside <code>def project do [ ..., version: &quot;x.y.z&quot;, ... ] end</code>.</p>
+<pre><code class="language-elixir">def project do
+  [
+    app: :my_app,
+    version: &quot;1.2.3&quot;,   # ← updated
+    elixir: &quot;~&gt; 1.15&quot;,
+    deps: deps()
+  ]
+end
+</code></pre>
+<p>Config snippet:</p>
+<pre><code class="language-toml">[[package.versioned_files]]
+path   = &quot;mix.exs&quot;
+format = &quot;mixexs&quot;
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="Ruby"><p class="ferr-tab__label">Ruby</p><div class="ferr-tab__body"><p>Used by Ruby gems (<code>*.gemspec</code>).</p>
+<p>FerrFlow updates the <code>.version = &quot;…&quot;</code> assignment. Any receiver name works (<code>s</code>, <code>spec</code>, <code>gem</code>, …). Setting <code>version</code> from a constant (<code>s.version = MyGem::VERSION</code>) isn&#39;t covered — version the loaded <code>version.rb</code> file directly in that case.</p>
+<pre><code class="language-ruby">Gem::Specification.new do |s|
+  s.name    = &quot;my_gem&quot;
+  s.version = &quot;1.2.3&quot;  # ← updated
+end
+</code></pre>
+<p>Config snippet:</p>
+<pre><code class="language-toml">[[package.versioned_files]]
+path   = &quot;my_gem.gemspec&quot;
+format = &quot;gemspec&quot;
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="Swift"><p class="ferr-tab__label">Swift</p><div class="ferr-tab__body"><p>Used by Swift packages (<code>Package.swift</code>).</p>
+<p>Swift PM derives a package&#39;s version from git tags, so there&#39;s no canonical location inside <code>Package.swift</code> — FerrFlow updates the first <code>let &lt;name&gt;Version = &quot;…&quot;</code> declaration. Constant names must end with <code>Version</code> (e.g. <code>packageVersion</code>, <code>AppVersion</code>) or be literally <code>version</code>. Dependency <code>.package(url:..., from: &quot;…&quot;)</code> arguments are <strong>not</strong> touched.</p>
+<pre><code class="language-swift">import PackageDescription
+
+let packageVersion = &quot;1.2.3&quot; // ← updated
+
+let package = Package(
+name: &quot;MyPackage&quot;,
+dependencies: [
+.package(url: &quot;…&quot;, from: &quot;1.5.0&quot;), // untouched
+]
+)
+</code></pre>
+<p>Config snippet:</p>
+<pre><code class="language-toml">[[package.versioned_files]]
+path   = &quot;Package.swift&quot;
+format = &quot;packageswift&quot;
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="Haskell"><p class="ferr-tab__label">Haskell</p><div class="ferr-tab__body"><p>Used by Haskell packages (<code>*.cabal</code>).</p>
+<p>FerrFlow updates the top-level <code>version:</code> field. Field names are case-insensitive and top-level fields sit at column 0, so <code>cabal-version:</code> — which declares the file format, not the package version — is <strong>never</strong> touched, and neither is an indented <code>version:</code> inside a stanza.</p>
+<pre><code class="language-cabal">cabal-version:      2.4     &lt;-- untouched
+name:               my-package
+version:            1.2.3   &lt;-- updated
+</code></pre>
+<p>Config snippet:</p>
+<pre><code class="language-toml">[[package.versioned_files]]
+path   = &quot;my-package.cabal&quot;
+format = &quot;cabal&quot;
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="CMake"><p class="ferr-tab__label">CMake</p><div class="ferr-tab__body"><p>Used by C / C++ projects (<code>CMakeLists.txt</code>).</p>
+<p>FerrFlow updates the <code>VERSION</code> argument of the <code>project()</code> call, including the multi-line form. <code>cmake_minimum_required(VERSION …)</code> — the CMake tool floor — and any <code>set(&lt;name&gt;_VERSION …)</code> variable are <strong>not</strong> touched.</p>
+<pre><code class="language-cmake">cmake_minimum_required(VERSION 3.20)   // untouched
+
+project(MyProject
+VERSION 1.2.3 // updated
+LANGUAGES CXX)
+</code></pre>
+<p>Config snippet:</p>
+<pre><code class="language-toml">[[package.versioned_files]]
+path   = &quot;CMakeLists.txt&quot;
+format = &quot;cmake&quot;
+</code></pre>
+</div></div>
+</div>
+
+## File → format quick reference
+
+| File                               | `format`              | Selector / behaviour                       |
+| ---------------------------------- | --------------------- | ------------------------------------------ |
+| `Cargo.toml`                       | `toml`                | `package.version`                          |
+| `pyproject.toml`                   | `toml`                | `project.version` or `tool.poetry.version` |
+| `package.json`                     | `json`                | `version`                                  |
+| `composer.json`                    | `json`                | `version`                                  |
+| `pom.xml`                          | `xml`                 | first `<version>` tag                      |
+| `*.csproj`                         | `csproj`              | `<Version>` in `<PropertyGroup>`           |
+| `build.gradle`, `build.gradle.kts` | `gradle`              | `version = "…"`                            |
+| `Chart.yaml`                       | `helm` or `chartyaml` | top-level `version:`                       |
+| `pubspec.yaml`                     | `pubspecyaml`         | top-level `version:`                       |
+| `mix.exs`                          | `mixexs`              | `version: "…"` in project keyword list     |
+| `*.gemspec`                        | `gemspec`             | `<ident>.version = "…"`                    |
+| `Package.swift`                    | `packageswift`        | top-level `let <name>Version = "…"`        |
+| `*.cabal`                          | `cabal`               | top-level `version:` field                 |
+| `CMakeLists.txt`                   | `cmake`               | `VERSION` argument of `project()`          |
+| `go.mod`                           | `gomod`               | git tag only — no file write               |
+| `VERSION`, `VERSION.txt`           | `txt`                 | entire file content                        |
+
+## Multiple files per package
+
+A package can have as many versioned file entries as needed:
+
+<div class="ferr-tabs">
+  <div class="ferr-tab" data-label="JSON"><p class="ferr-tab__label">JSON</p><div class="ferr-tab__body"><pre><code class="language-json">{
+  &quot;package&quot;: [
+    {
+      &quot;versionedFiles&quot;: [
+        { &quot;path&quot;: &quot;Cargo.toml&quot;, &quot;format&quot;: &quot;toml&quot; },
+        { &quot;path&quot;: &quot;npm/package.json&quot;, &quot;format&quot;: &quot;json&quot; }
+      ]
+    }
+  ]
+}
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="TOML"><p class="ferr-tab__label">TOML</p><div class="ferr-tab__body"><pre><code class="language-toml">[[package.versioned_files]]
+path   = &quot;Cargo.toml&quot;
+format = &quot;toml&quot;
+
+[[package.versioned_files]]
+path = &quot;npm/package.json&quot;
+format = &quot;json&quot;
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="JSON5"><p class="ferr-tab__label">JSON5</p><div class="ferr-tab__body"><pre><code class="language-json5">{
+  package: [
+    {
+      versionedFiles: [
+        { path: &quot;Cargo.toml&quot;, format: &quot;toml&quot; },
+        { path: &quot;npm/package.json&quot;, format: &quot;json&quot; },
+      ],
+    },
+  ],
+}
+</code></pre>
+</div></div>
+</div>
+
+Both files will be updated to the same version before the git commit.

package/docs-v6/configuration/monorepo.md

@@ -0,0 +1,390 @@
+---
+title: Monorepo
+description: Version multiple packages independently in a single repository.
+---
+
+FerrFlow treats a repository as a monorepo when the config defines more than one package. Each package is versioned independently based on its own git history.
+
+## Package isolation
+
+FerrFlow uses path prefixes to determine which commits belong to which package. Only commits that touch files under `path` (or `sharedPaths`) trigger a release for that package.
+
+<div class="ferr-tabs">
+  <div class="ferr-tab" data-label="JSON"><p class="ferr-tab__label">JSON</p><div class="ferr-tab__body"><pre><code class="language-json">{
+  &quot;package&quot;: [
+    {
+      &quot;name&quot;: &quot;api&quot;,
+      &quot;path&quot;: &quot;packages/api&quot;
+    },
+    {
+      &quot;name&quot;: &quot;site&quot;,
+      &quot;path&quot;: &quot;packages/site&quot;
+    }
+  ]
+}
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="TOML"><p class="ferr-tab__label">TOML</p><div class="ferr-tab__body"><pre><code class="language-toml">[[package]]
+name = &quot;api&quot;
+path = &quot;packages/api&quot;
+
+[[package]]
+name = &quot;site&quot;
+path = &quot;packages/site&quot;
+</code></pre>
+
+</div></div>
+  <div class="ferr-tab" data-label="JSON5"><p class="ferr-tab__label">JSON5</p><div class="ferr-tab__body"><pre><code class="language-json5">{
+  package: [
+    {
+      name: &quot;api&quot;,
+      path: &quot;packages/api&quot;,
+    },
+    {
+      name: &quot;site&quot;,
+      path: &quot;packages/site&quot;,
+    },
+  ],
+}
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="YAML"><p class="ferr-tab__label">YAML</p><div class="ferr-tab__body"><pre><code class="language-yaml">package:
+  - name: api
+    path: packages/api
+  - name: site
+    path: packages/site
+</code></pre>
+</div></div>
+</div>
+
+## Shared dependencies
+
+If you have code shared between packages (e.g., a `packages/shared/` library), declare it as a `sharedPaths` entry. A change to any shared path triggers a release for every package that lists it:
+
+<div class="ferr-tabs">
+  <div class="ferr-tab" data-label="JSON"><p class="ferr-tab__label">JSON</p><div class="ferr-tab__body"><pre><code class="language-json">{
+  &quot;package&quot;: [
+    {
+      &quot;name&quot;: &quot;api&quot;,
+      &quot;path&quot;: &quot;packages/api&quot;,
+      &quot;sharedPaths&quot;: [&quot;packages/shared/&quot;]
+    },
+    {
+      &quot;name&quot;: &quot;site&quot;,
+      &quot;path&quot;: &quot;packages/site&quot;,
+      &quot;sharedPaths&quot;: [&quot;packages/shared/&quot;]
+    }
+  ]
+}
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="TOML"><p class="ferr-tab__label">TOML</p><div class="ferr-tab__body"><pre><code class="language-toml">[[package]]
+name = &quot;api&quot;
+path = &quot;packages/api&quot;
+shared_paths = [&quot;packages/shared/&quot;]
+
+[[package]]
+name = &quot;site&quot;
+path = &quot;packages/site&quot;
+shared_paths = [&quot;packages/shared/&quot;]
+</code></pre>
+
+</div></div>
+  <div class="ferr-tab" data-label="JSON5"><p class="ferr-tab__label">JSON5</p><div class="ferr-tab__body"><pre><code class="language-json5">{
+  package: [
+    {
+      name: &quot;api&quot;,
+      path: &quot;packages/api&quot;,
+      sharedPaths: [&quot;packages/shared/&quot;],
+    },
+    {
+      name: &quot;site&quot;,
+      path: &quot;packages/site&quot;,
+      sharedPaths: [&quot;packages/shared/&quot;],
+    },
+  ],
+}
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="YAML"><p class="ferr-tab__label">YAML</p><div class="ferr-tab__body"><pre><code class="language-yaml">package:
+  - name: api
+    path: packages/api
+    sharedPaths:
+      - packages/shared/
+  - name: site
+    path: packages/site
+    sharedPaths:
+      - packages/shared/
+</code></pre>
+</div></div>
+</div>
+
+## Package dependencies
+
+Use `dependsOn` to declare that a package depends on another. When a dependency is released, the dependent package is bumped too — even if none of its own files changed — with the same bump type by default. This cascades transitively: if `app` depends on `cli` and `cli` depends on `core`, bumping `core` bumps both `cli` and `app`.
+
+<div class="ferr-tabs">
+  <div class="ferr-tab" data-label="JSON"><p class="ferr-tab__label">JSON</p><div class="ferr-tab__body"><pre><code class="language-json">{
+  &quot;package&quot;: [
+    {
+      &quot;name&quot;: &quot;core&quot;,
+      &quot;path&quot;: &quot;packages/core&quot;
+    },
+    {
+      &quot;name&quot;: &quot;cli&quot;,
+      &quot;path&quot;: &quot;packages/cli&quot;,
+      &quot;dependsOn&quot;: [&quot;core&quot;]
+    },
+    {
+      &quot;name&quot;: &quot;app&quot;,
+      &quot;path&quot;: &quot;packages/app&quot;,
+      &quot;dependsOn&quot;: [&quot;cli&quot;]
+    }
+  ]
+}
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="TOML"><p class="ferr-tab__label">TOML</p><div class="ferr-tab__body"><pre><code class="language-toml">[[package]]
+name = &quot;core&quot;
+path = &quot;packages/core&quot;
+
+[[package]]
+name = &quot;cli&quot;
+path = &quot;packages/cli&quot;
+depends_on = [&quot;core&quot;]
+
+[[package]]
+name = &quot;app&quot;
+path = &quot;packages/app&quot;
+depends_on = [&quot;cli&quot;]
+</code></pre>
+
+</div></div>
+  <div class="ferr-tab" data-label="JSON5"><p class="ferr-tab__label">JSON5</p><div class="ferr-tab__body"><pre><code class="language-json5">{
+  package: [
+    {
+      name: &quot;core&quot;,
+      path: &quot;packages/core&quot;,
+    },
+    {
+      name: &quot;cli&quot;,
+      path: &quot;packages/cli&quot;,
+      dependsOn: [&quot;core&quot;],
+    },
+    {
+      name: &quot;app&quot;,
+      path: &quot;packages/app&quot;,
+      dependsOn: [&quot;cli&quot;],
+    },
+  ],
+}
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="YAML"><p class="ferr-tab__label">YAML</p><div class="ferr-tab__body"><pre><code class="language-yaml">package:
+  - name: core
+    path: packages/core
+  - name: cli
+    path: packages/cli
+    dependsOn:
+      - core
+  - name: app
+    path: packages/app
+    dependsOn:
+      - cli
+</code></pre>
+</div></div>
+</div>
+
+### Propagation policy
+
+Write an entry as an object to choose how the upstream bump translates:
+
+```json
+{
+  "name": "cli",
+  "path": "packages/cli",
+  "dependsOn": [{ "name": "core", "propagate": "patch" }]
+}
+```
+
+| Policy           | A major in the dependency becomes     | A minor becomes | A patch becomes |
+| ---------------- | ------------------------------------- | --------------- | --------------- |
+| `same` (default) | major                                 | minor           | patch           |
+| `major-on-major` | major                                 | patch           | patch           |
+| `patch`          | patch                                 | patch           | patch           |
+| `none`           | nothing — the dependent is not bumped | nothing         | nothing         |
+
+A bare string is shorthand for `same`, so `"dependsOn": ["core"]` and `{ "name": "core", "propagate": "same" }` are identical. When several dependencies move at once under different policies, the strongest resulting bump wins.
+
+### Updating dependents' manifests
+
+Set `workspace.updateDependents` to `true` to rewrite the version constraint each dependent declares for the bumped package, staged in the same release commit:
+
+```
+● core  1.0.0 → 1.1.0  (minor)
+● cli   2.3.0 → 2.4.0  (minor, dependency: core)
+  ↳ core → 1.1.0 in cli/package.json
+```
+
+`cli/package.json` goes from `"core": "^1.0.0"` to `"core": "^1.1.0"`. Only `json` and `toml` manifests are rewritten, and only plain operator + version constraints — the operator is preserved. A `workspace:*`, `file:`/`git:` spec, `1.x` or a multi-part range carries intent a version pin would destroy, so it is left for you to handle.
+
+<aside class="ferr-aside ferr-aside--note"><div class="ferr-aside__body"><p><code>dependsOn</code> differs from <code>sharedPaths</code>. Shared paths trigger a bump when files in the shared directory change. <code>dependsOn</code> triggers a bump when another <strong>package</strong> is released, regardless of which files changed.</p>
+</div></aside>
+
+### Dependency cycles
+
+`dependsOn` must describe a directed acyclic graph. If two packages depend on each other — directly or transitively — there is no order in which to release them, so FerrFlow stops with error `E8003` and names the loop:
+
+```
+cycle detected: api → web → api
+```
+
+The check runs before any version is written, so a cyclic configuration never produces a partial release. Break the loop by removing one of the `dependsOn` edges. Otherwise the graph is released dependencies-first: a package is always released after the packages it depends on.
+
+## Linked and fixed version groups
+
+Sometimes packages must share a version number, not just cascade a bump. `linked` and `fixed` list groups of packages that move in lockstep:
+
+```toml
+[workspace]
+linked = [["react", "react-dom"]]
+fixed  = [["@scope/a", "@scope/b", "@scope/c"]]
+```
+
+When **any** member of a group has a releasable commit, every member is bumped to the same version — the highest version the group would reach. A `feat` on one member and a `fix` on another release the whole group on the minor. Package names stay distinct; only the version is shared, and members with no commits of their own are pulled into the release at the shared version.
+
+- **`linked`** — packages share a version line when they are released together (e.g. `react` and `react-dom` both go `1.2.3 → 1.2.4`).
+- **`fixed`** — packages are locked to an identical version forever. It behaves like `linked`, and `ferrflow validate` additionally warns when a fixed group's versions have already drifted apart, so you catch a manual edit before the next release realigns them.
+
+Each group must list at least two packages, and a package may appear in only one `linked` or `fixed` group. Naming a package that isn't defined in `package[]`, or listing one in two groups, stops the release with a clear error before anything is written — the same pre-flight guarantee as [dependency cycles](#dependency-cycles).
+
+`linked`/`fixed` and `dependsOn` compose: a package that depends on a grouped package still receives its cascade bump after the group is aligned.
+
+## Git tag format
+
+By default, monorepo tags use the `{name}@v{version}` format:
+
+```
+api@v1.2.0
+site@v0.4.1
+```
+
+Configure this with the `tagTemplate` field:
+
+<div class="ferr-tabs">
+  <div class="ferr-tab" data-label="JSON"><p class="ferr-tab__label">JSON</p><div class="ferr-tab__body"><pre><code class="language-json">{
+  &quot;workspace&quot;: {
+    &quot;tagTemplate&quot;: &quot;{name}@v{version}&quot;
+  }
+}
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="TOML"><p class="ferr-tab__label">TOML</p><div class="ferr-tab__body"><pre><code class="language-toml">[workspace]
+tag_template = &quot;{name}@v{version}&quot;
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="JSON5"><p class="ferr-tab__label">JSON5</p><div class="ferr-tab__body"><pre><code class="language-json5">{
+  workspace: {
+    tagTemplate: &quot;{name}@v{version}&quot;,
+  },
+}
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="YAML"><p class="ferr-tab__label">YAML</p><div class="ferr-tab__body"><pre><code class="language-yaml">workspace:
+  tagTemplate: &quot;{name}@v{version}&quot;
+</code></pre>
+</div></div>
+</div>
+
+For a single-package repo, the default is `v{version}` (no name prefix).
+
+FerrFlow looks for the most recent tag matching the template to determine what commits are new.
+
+## Independent cadences
+
+Packages release independently. In a single `ferrflow release` run:
+
+- `api` may bump from `1.2.0` → `1.3.0` (new `feat:` commit)
+- `site` may bump from `0.4.0` → `0.4.1` (only `fix:` commits)
+- `shared` may not release at all (only `chore:` commits)
+
+## Per-package overrides
+
+Each package can override the workspace-level `versioning` strategy and `tagTemplate`:
+
+<div class="ferr-tabs">
+  <div class="ferr-tab" data-label="JSON"><p class="ferr-tab__label">JSON</p><div class="ferr-tab__body"><pre><code class="language-json">{
+  &quot;workspace&quot;: {
+    &quot;versioning&quot;: &quot;semver&quot;,
+    &quot;tagTemplate&quot;: &quot;{name}@v{version}&quot;
+  },
+  &quot;package&quot;: [
+    {
+      &quot;name&quot;: &quot;api&quot;,
+      &quot;path&quot;: &quot;packages/api&quot;,
+      &quot;versioning&quot;: &quot;calver&quot;
+    },
+    {
+      &quot;name&quot;: &quot;site&quot;,
+      &quot;path&quot;: &quot;packages/site&quot;,
+      &quot;tagTemplate&quot;: &quot;site-v{version}&quot;
+    }
+  ]
+}
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="TOML"><p class="ferr-tab__label">TOML</p><div class="ferr-tab__body"><pre><code class="language-toml">[workspace]
+versioning = &quot;semver&quot;
+tag_template = &quot;{name}@v{version}&quot;
+
+[[package]]
+name = &quot;api&quot;
+path = &quot;packages/api&quot;
+versioning = &quot;calver&quot;
+
+[[package]]
+name = &quot;site&quot;
+path = &quot;packages/site&quot;
+tag_template = &quot;site-v{version}&quot;
+</code></pre>
+
+</div></div>
+  <div class="ferr-tab" data-label="JSON5"><p class="ferr-tab__label">JSON5</p><div class="ferr-tab__body"><pre><code class="language-json5">{
+  workspace: {
+    versioning: &quot;semver&quot;,
+    tagTemplate: &quot;{name}@v{version}&quot;,
+  },
+  package: [
+    {
+      name: &quot;api&quot;,
+      path: &quot;packages/api&quot;,
+      versioning: &quot;calver&quot;,
+    },
+    {
+      name: &quot;site&quot;,
+      path: &quot;packages/site&quot;,
+      tagTemplate: &quot;site-v{version}&quot;,
+    },
+  ],
+}
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="YAML"><p class="ferr-tab__label">YAML</p><div class="ferr-tab__body"><pre><code class="language-yaml">workspace:
+  versioning: semver
+  tagTemplate: &quot;{name}@v{version}&quot;
+
+package:
+
+- name: api
+  path: packages/api
+  versioning: calver
+- name: site
+  path: packages/site
+  tagTemplate: &quot;site-v{version}&quot;
+  </code></pre>
+
+</div></div>
+</div>
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Use <code>ferrflow check</code> to preview exactly which packages would be released and at what version before committing to a release.</p>
+</div></aside>

package/docs-v6/installation.md

@@ -0,0 +1,56 @@
+---
+title: Installation
+description: How to install FerrFlow locally or in CI.
+---
+
+## Local installation
+
+<div class="ferr-tabs">
+  <div class="ferr-tab" data-label="Cargo"><p class="ferr-tab__label">Cargo</p><div class="ferr-tab__body"><pre><code class="language-bash">cargo install ferrflow
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="npm"><p class="ferr-tab__label">npm</p><div class="ferr-tab__body"><pre><code class="language-bash">npm install -g @ferrlabs/ferrflow
+# or as a dev dependency
+npm install -D @ferrlabs/ferrflow
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="WASM (browser)"><p class="ferr-tab__label">WASM (browser)</p><div class="ferr-tab__body"><pre><code class="language-bash">npm install @ferrflow/wasm
+</code></pre>
+<p>Use FerrFlow directly in the browser — parse commits, compute version bumps, and generate changelogs client-side without a backend.</p>
+</div></div>
+  <div class="ferr-tab" data-label="Binary"><p class="ferr-tab__label">Binary</p><div class="ferr-tab__body"><p>Download a pre-built binary from <a href="https://github.com/FerrLabs/FerrFlow/releases/latest">Releases</a>:</p>
+<pre><code class="language-bash"># Linux x86_64
+curl -L https://github.com/FerrLabs/FerrFlow/releases/latest/download/ferrflow-linux-x64.tar.gz | tar xz
+sudo mv ferrflow /usr/local/bin/
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="Docker"><p class="ferr-tab__label">Docker</p><div class="ferr-tab__body"><pre><code class="language-bash">docker run --rm -v $(pwd):/repo ghcr.io/ferrlabs/ferrflow:latest check
+</code></pre>
+</div></div>
+</div>
+
+## CI installation
+
+The recommended way to use FerrFlow in CI is the GitHub Action — no installation step needed:
+
+```yaml title=".github/workflows/release.yml"
+- uses: FerrLabs/ferrflow@v5
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+See [GitHub Actions](/docs/ci/github-actions) and [GitLab CI](/docs/ci/gitlab-ci) for complete examples.
+
+## Verify
+
+```bash
+ferrflow --version
+```
+
+## Upgrading from v4
+
+If you're following the documented GitHub Actions / GitLab CI setup (`GITHUB_TOKEN`/`CI_JOB_TOKEN` as an environment variable), no changes are required — just bump the action pin to `FerrLabs/ferrflow@v5` and the binary to v5.x.
+
+The only breaking change in v5.0 is internal: FerrFlow no longer injects tokens into the remote URL when pushing. It now uses the standard git credential-helper protocol (`GIT_ASKPASS`). This is invisible to anyone using the recommended setup, but if you had a custom workflow that relied on URL-injected tokens — for example, a self-hosted runner with a pre-seeded `https://x-access-token:$TOKEN@github.com/...` remote — switch to setting `GITHUB_TOKEN` (or `FERRFLOW_TOKEN`) as an environment variable instead and FerrFlow handles the rest.
+
+Releases since v5.2 are signed via Sigstore and ship a CycloneDX SBOM — see [Verifying releases](/docs/verifying-releases).