@ferrlabs/ferrflow-linux-x64 5.0.1

package/LICENSE

@@ -0,0 +1,373 @@
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in 
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.

package/README.md

@@ -0,0 +1,553 @@
+# FerrFlow
+
+[![Latest release](https://img.shields.io/github/v/release/FerrLabs/FerrFlow)](https://github.com/FerrLabs/FerrFlow/releases/latest)
+[![Coverage](https://codecov.io/gh/FerrLabs/FerrFlow/graph/badge.svg)](https://codecov.io/gh/FerrLabs/FerrFlow)
+[![License](https://img.shields.io/github/license/FerrLabs/FerrFlow)](LICENSE)
+[![Socket Badge](https://badge.socket.dev/npm/package/@ferrlabs/ferrflow/latest)](https://badge.socket.dev/npm/package/@ferrlabs/ferrflow/latest)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/FerrLabs/FerrFlow/badge)](https://scorecard.dev/viewer/?uri=github.com/FerrLabs/FerrFlow)
+
+Universal semantic versioning for monorepos and classic repos.
+
+FerrFlow reads your commit history, determines the right version bump, updates your version files, generates a changelog, and creates a tagged release — for any language, any repo layout.
+
+## Why FerrFlow?
+
+A single compiled binary with no runtime dependencies. Native monorepo support, multi-language versioning, and works with any repo layout.
+
+## Supported version files
+
+| Format | File | Ecosystem | Selector |
+|--------|------|-----------|----------|
+| `toml` | `Cargo.toml` | Rust | `package.version` |
+| `toml` | `pyproject.toml` | Python | `project.version` or `tool.poetry.version` |
+| `json` | `package.json` | Node.js | `version` |
+| `json` | `composer.json` | PHP | `version` |
+| `xml` | `pom.xml` | Java / Maven | first `<version>` that's a direct child of the root element (skips `<parent>` and dependencies) |
+| `csproj` | `*.csproj` | .NET (C#, F#) | `<Version>` in `<PropertyGroup>` |
+| `gradle` | `build.gradle`, `build.gradle.kts` | Java / Kotlin | `version = "…"` |
+| `helm` / `chartyaml` | `Chart.yaml` | Kubernetes / Helm | top-level `version:` |
+| `pubspecyaml` | `pubspec.yaml` | Dart / Flutter | top-level `version:` |
+| `mixexs` | `mix.exs` | Elixir | `version: "…"` in `def project` |
+| `gemspec` | `*.gemspec` | Ruby | `s.version = "…"` |
+| `packageswift` | `Package.swift` | Swift | top-level `let <name>Version = "…"` |
+| `gomod` | `go.mod` | Go | git tag only — no file write |
+| `txt` | `VERSION`, `VERSION.txt` | Any | entire file content |
+
+## Installation
+
+**Cargo**
+
+```bash
+cargo install ferrflow
+```
+
+**npm**
+
+```bash
+npm install -D @ferrlabs/ferrflow
+```
+
+**Docker**
+
+```bash
+docker run ghcr.io/ferrflow/ferrflow:latest check
+```
+
+**Pre-built binaries**
+
+Download from [Releases](https://github.com/FerrLabs/FerrFlow/releases).
+
+## Usage
+
+```bash
+# Preview what would be bumped
+ferrflow check
+
+# Run a release
+ferrflow release
+
+# Dry run
+ferrflow release --dry-run
+
+# Force a specific version (skips commit analysis)
+ferrflow release --force-version 2.0.0          # single repo
+ferrflow release --force-version api@3.0.0      # monorepo
+
+# Pre-release
+ferrflow release --channel beta
+
+# Scaffold a config file
+ferrflow init
+
+# Scaffold a config file in a specific format
+ferrflow init --format json5
+
+# Use a specific config file
+ferrflow check --config path/to/ferrflow.toml
+
+# Or set via environment variable
+FERRFLOW_CONFIG=path/to/ferrflow.toml ferrflow check
+
+# Print current version
+ferrflow version              # single repo
+ferrflow version api          # monorepo, specific package
+
+# Print last release tag
+ferrflow tag
+ferrflow tag api
+
+# JSON output (for scripting)
+ferrflow version --json
+ferrflow tag --json
+
+# Shell completions
+ferrflow completions bash >> ~/.bash_completion
+ferrflow completions zsh  > ~/.zfunc/_ferrflow
+ferrflow completions fish > ~/.config/fish/completions/ferrflow.fish
+```
+
+Pre-generated completion scripts are also available as `ferrflow-completions.tar.gz` in each [GitHub release](https://github.com/FerrLabs/FerrFlow/releases).
+
+## Configuration
+
+FerrFlow looks for a config file at the root of your repository, in this order:
+
+1. `ferrflow.json`
+2. `ferrflow.json5`
+3. `ferrflow.toml`
+4. `.ferrflow` (dotfile, JSON format)
+
+If multiple config files exist, FerrFlow exits with an error listing the conflicting files. Use `--config <path>` (or `FERRFLOW_CONFIG` env var) to specify which one to use. If no config file is found, FerrFlow auto-detects common version files in the current directory.
+
+Run `ferrflow init` to scaffold a config file interactively. Use `--format` to skip the format prompt:
+
+```bash
+ferrflow init                  # asks which format (default: json)
+ferrflow init --format json5
+ferrflow init --format toml
+ferrflow init --format dotfile # generates .ferrflow
+```
+
+### JSON Schema
+
+Add `$schema` to get autocompletion and validation in VS Code, WebStorm, and any JSON-aware editor:
+
+```json
+{
+  "$schema": "https://ferrflow.com/schema/ferrflow.json"
+}
+```
+
+### JSON (default)
+
+```json
+{
+  "$schema": "https://ferrflow.com/schema/ferrflow.json",
+  "workspace": {
+    "remote": "origin",
+    "branch": "main"
+  },
+  "package": [
+    {
+      "name": "my-app",
+      "path": ".",
+      "changelog": "CHANGELOG.md",
+      "versioned_files": [
+        { "path": "package.json", "format": "json" }
+      ]
+    }
+  ]
+}
+```
+
+### JSON5
+
+```json5
+{
+  workspace: {
+    remote: "origin",
+    branch: "main",
+  },
+  package: [
+    {
+      name: "my-app",
+      path: ".",
+      changelog: "CHANGELOG.md",
+      versioned_files: [
+        { path: "package.json", format: "json" },
+      ],
+    },
+  ],
+}
+```
+
+### TOML
+
+```toml
+[workspace]
+remote = "origin"
+branch = "main"
+
+[[package]]
+name = "my-app"
+path = "."
+changelog = "CHANGELOG.md"
+
+[[package.versioned_files]]
+path = "Cargo.toml"
+format = "toml"
+```
+
+### Monorepo
+
+<details>
+<summary>JSON</summary>
+
+```json
+{
+  "package": [
+    {
+      "name": "api",
+      "path": "services/api",
+      "changelog": "services/api/CHANGELOG.md",
+      "shared_paths": ["services/shared/"],
+      "versioned_files": [
+        { "path": "services/api/Cargo.toml", "format": "toml" }
+      ]
+    },
+    {
+      "name": "frontend",
+      "path": "frontend",
+      "changelog": "frontend/CHANGELOG.md",
+      "versioned_files": [
+        { "path": "frontend/package.json", "format": "json" }
+      ]
+    }
+  ]
+}
+```
+
+</details>
+
+<details>
+<summary>TOML</summary>
+
+```toml
+[[package]]
+name = "api"
+path = "services/api"
+changelog = "services/api/CHANGELOG.md"
+shared_paths = ["services/shared/"]
+
+[[package.versioned_files]]
+path = "services/api/Cargo.toml"
+format = "toml"
+
+[[package]]
+name = "frontend"
+path = "frontend"
+changelog = "frontend/CHANGELOG.md"
+
+[[package.versioned_files]]
+path = "frontend/package.json"
+format = "json"
+```
+
+</details>
+
+## Versioning Strategies
+
+Each package can use its own versioning strategy. Set a default at the workspace level and override per package:
+
+```toml
+[workspace]
+versioning = "semver"  # default for all packages
+
+[[package]]
+name = "api"
+path = "packages/api"
+# inherits semver from workspace
+
+[[package]]
+name = "site"
+path = "packages/site"
+versioning = "calver"  # override: date-based
+```
+
+| Strategy | Format | Example | Description |
+|----------|--------|---------|-------------|
+| `semver` | `MAJOR.MINOR.PATCH` | `1.4.2` | Default, driven by conventional commits |
+| `calver` | `YYYY.M.D` | `2025.3.28` | Date-based, ignores commit types |
+| `calver-short` | `YY.M.D` | `25.3.28` | Compact date-based |
+| `calver-seq` | `YYYY.M.SEQ` | `2025.3.3` | Date + daily sequence counter |
+| `sequential` | `N` | `42` | Simple incrementing build number |
+| `zerover` | `0.MINOR.PATCH` | `0.15.2` | Permanently unstable, never hits 1.0 |
+
+## Tag Template
+
+By default, FerrFlow tags single-repo releases as `v1.2.3` and monorepo releases as `api@v1.2.3`. Customize with `tag_template` at the workspace or package level using `{name}` and `{version}` placeholders.
+
+```toml
+[workspace]
+tag_template = "v{version}"  # all packages: v1.2.3
+
+[[package]]
+name = "api"
+path = "packages/api"
+tag_template = "{name}/v{version}"  # override: api/v1.2.3
+```
+
+| Layout | Default template | Example tag |
+|--------|-----------------|-------------|
+| Single repo | `v{version}` | `v1.2.3` |
+| Monorepo | `{name}@v{version}` | `api@v1.2.3` |
+| Custom | `release-{version}` | `release-1.2.3` |
+
+## Pre-release Channels
+
+Publish pre-release versions (alpha, beta, rc, dev) using the `--channel` flag or branch-based configuration. Pre-release versions follow the format `MAJOR.MINOR.PATCH-CHANNEL.IDENTIFIER`.
+
+### CLI flag
+
+```bash
+ferrflow release --channel beta       # 2.0.0-beta.1
+ferrflow check --channel rc           # preview pre-release version
+```
+
+### Branch-based configuration
+
+Map branches to channels automatically:
+
+```json
+{
+  "workspace": {
+    "branches": [
+      { "name": "main", "channel": false },
+      { "name": "develop", "channel": "dev", "prereleaseIdentifier": "timestamp" },
+      { "name": "release/*", "channel": "rc" }
+    ]
+  }
+}
+```
+
+Branch names support glob patterns. The first match wins. Wildcards match across
+`/` separators, so `*` matches branches like `fix/global` and `feature/*` matches
+`feature/auth/oauth`.
+
+### Identifier strategies
+
+| Strategy | Example | Description |
+|----------|---------|-------------|
+| `increment` | `-beta.3` | Auto-incrementing counter (default) |
+| `timestamp` | `-dev.20250402T1430` | UTC timestamp |
+| `short-hash` | `-dev.a1b2c3d` | Git short hash |
+| `timestamp-hash` | `-dev.20250402T1430-a1b2c3d` | Timestamp + hash |
+
+### Behavior
+
+- Floating tags (e.g. `v1`, `v1.2`) are never moved by pre-release versions
+- GitHub Releases are marked as pre-release
+- Stable releases include all commits since the last stable tag (skipping pre-release tags)
+- Hook environment includes `FERRFLOW_CHANNEL` and `FERRFLOW_IS_PRERELEASE`
+
+## Release Commit Mode
+
+Controls how FerrFlow commits version bumps and changelog updates after a release.
+
+```toml
+[workspace]
+release_commit_mode = "commit"  # default
+```
+
+| Mode | Description |
+|------|-------------|
+| `commit` | Push a release commit directly to the branch |
+| `pr` | Create a pull request with the release changes |
+| `none` | Skip committing entirely (useful when another tool handles it) |
+
+When using `pr` mode, `auto_merge_releases` controls whether the PR is automatically merged:
+
+```toml
+[workspace]
+release_commit_mode = "pr"
+auto_merge_releases = true  # default
+```
+
+### Release Commit Scope
+
+In monorepo mode, controls whether all package bumps go into a single commit or one commit per package:
+
+```toml
+[workspace]
+release_commit_scope = "grouped"  # default
+```
+
+| Scope | Description |
+|-------|-------------|
+| `grouped` | Single commit for all packages (e.g. `chore(release): api v1.0.0, site v2.1.0`) |
+| `per-package` | One commit per package (e.g. `chore(release): api v1.0.0`, then `chore(release): site v2.1.0`) |
+
+Per-package commits make it easier to revert a single package bump without affecting others. This works with both `commit` and `pr` release modes.
+
+### Skip CI
+
+By default, release commits in `commit` mode include `[skip ci]` in the message to avoid triggering a CI loop. Override with `skip_ci`:
+
+```toml
+[workspace]
+skip_ci = false  # force CI to run on release commits
+```
+
+In `pr` mode, `skip_ci` defaults to `false` since the PR merge triggers CI naturally.
+
+## Floating Tags
+
+Move abbreviated tags (e.g. `v1`, `v1.2`) to always point at the latest matching release:
+
+```toml
+[workspace]
+floating_tags = ["major"]  # creates/moves v1 when releasing v1.2.3
+```
+
+| Level | Tag | Points to |
+|-------|-----|-----------|
+| `major` | `v1` | Latest `v1.x.x` |
+| `minor` | `v1.2` | Latest `v1.2.x` |
+
+Floating tags are never moved by pre-release versions. Override per package:
+
+```toml
+[[package]]
+name = "api"
+path = "packages/api"
+floating_tags = ["major", "minor"]
+```
+
+## Orphaned Tag Strategy
+
+After a rebase + force-push, existing tags may point to commits that no longer exist on the branch. `orphaned_tag_strategy` controls how FerrFlow handles this:
+
+```toml
+[workspace]
+orphaned_tag_strategy = "warn"  # default
+```
+
+| Strategy | Description |
+|----------|-------------|
+| `warn` | Log a warning and skip the orphaned tag |
+| `treeHash` | Attempt recovery by matching the commit's tree hash |
+| `message` | Attempt recovery by matching the commit message |
+
+## Recover Missed Releases
+
+In monorepos, a package can miss a release if its files changed but FerrFlow wasn't run. Enable `recover_missed_releases` to compare files against the last tag instead of just the last commit:
+
+```toml
+[workspace]
+recover_missed_releases = true  # default: false
+```
+
+## Package Dependencies
+
+In a monorepo, use `depends_on` to automatically patch-bump a package when one of its dependencies is released:
+
+```json
+{
+  "package": [
+    { "name": "core", "path": "packages/core" },
+    {
+      "name": "cli",
+      "path": "packages/cli",
+      "depends_on": ["core"]
+    }
+  ]
+}
+```
+
+When `core` is bumped, `cli` gets a patch bump even if it had no direct commits.
+
+## Hooks
+
+Run shell commands at lifecycle points during a release. Hooks can be set at the workspace level (applies to all packages) or per package:
+
+```toml
+[workspace.hooks]
+pre_bump = "echo 'about to bump'"
+post_bump = "cargo check"
+pre_commit = "npm run build"
+pre_publish = "npm pack --dry-run"
+post_publish = "notify-slack.sh"
+on_failure = "abort"  # or "continue"
+```
+
+| Hook | When |
+|------|------|
+| `pre_bump` | After bump calculation, before writing version files |
+| `post_bump` | After writing version files, before changelog generation |
+| `pre_commit` | After changelog generation, before git commit |
+| `pre_publish` | After commit and tag, before push |
+| `post_publish` | After push and release creation |
+
+If a hook exits non-zero and `on_failure` is `abort` (default), the release is cancelled. Set `on_failure` to `continue` to ignore hook failures.
+
+Hook commands receive environment variables: `FERRFLOW_PACKAGE`, `FERRFLOW_VERSION`, `FERRFLOW_PREV_VERSION`, `FERRFLOW_CHANNEL`, `FERRFLOW_IS_PRERELEASE`.
+
+## Conventional Commits
+
+FerrFlow follows the [Conventional Commits](https://www.conventionalcommits.org/) spec.
+
+| Prefix | Bump |
+|--------|------|
+| `fix:`, `perf:`, `refactor:` | patch |
+| `feat:` | minor |
+| `feat!:`, `BREAKING CHANGE` | major |
+| `chore:`, `docs:`, `ci:` | none |
+
+## CI usage
+
+**GitLab CI**
+
+```yaml
+release:
+  image: ghcr.io/ferrflow/ferrflow:latest
+  script:
+    - ferrflow release
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+```
+
+**GitHub Actions**
+
+```yaml
+- name: Release
+  run: ferrflow release
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### Using the hosted bot (ferrflow[bot])
+
+Install the [FerrFlow GitHub App](https://github.com/apps/ferrflow) on your repo or org, then opt in with `bot: true`. Release commits, tags, and GitHub Releases are authored by `ferrflow[bot]` and downstream workflows triggered by those events run normally (unlike the default `GITHUB_TOKEN`, which suppresses them).
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+
+steps:
+  - uses: actions/checkout@v6
+    with:
+      fetch-depth: 0
+  - uses: FerrLabs/FerrFlow@v4
+    with:
+      bot: true
+```
+
+That's it — no `setup-node`, no extra dependencies. FerrFlow's Rust binary handles the OIDC exchange directly, so minimal self-hosted runners work out of the box.
+
+Three auth modes are supported: `bot: true` uses the hosted FerrFlow App (recommended); `token: <PAT>` uses a personal access token or your own GitHub App token (DIY); omitting both falls back to the workflow's `GITHUB_TOKEN` (simplest, but release events won't trigger downstream workflows).
+
+## License
+
+[MPL-2.0](LICENSE)
+

package/package.json

@@ -0,0 +1,16 @@
+{
+  "cpu": [
+    "x64"
+  ],
+  "description": "FerrFlow Linux x64 binary",
+  "license": "MPL-2.0",
+  "name": "@ferrlabs/ferrflow-linux-x64",
+  "os": [
+    "linux"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FerrLabs/FerrFlow.git"
+  },
+  "version": "5.0.1"
+}