@ferrflow/doc 7.17.0

package/docs-en/introduction.md

@@ -0,0 +1,56 @@
+---
+title: Introduction
+description: What FerrFlow is and why it exists.
+---
+
+FerrFlow is a single binary that automates semantic versioning for any repository: monorepo or classic, any language.
+
+It reads your commit history, determines the right version bump, updates your version files, writes a changelog, creates a git tag, and publishes a release. Zero runtime dependencies.
+
+<div class="ferr-card-group" data-cols="2">
+  <div class="ferr-card"><p class="ferr-card__title">CLI-first</p><div class="ferr-card__body"><p>Everything happens from your terminal or your CI. No UI to click, no config server to babysit.</p>
+</div></div>
+  <div class="ferr-card"><p class="ferr-card__title">Multi-forge</p><div class="ferr-card__body"><p>GitHub, GitLab, self-hosted: FerrFlow adapts to your forge. One tool, any platform.</p>
+</div></div>
+  <div class="ferr-card"><p class="ferr-card__title">Conventional commits</p><div class="ferr-card__body"><p>Reads commit history to determine version bumps automatically. No manual changelog maintenance.</p>
+</div></div>
+  <div class="ferr-card"><p class="ferr-card__title">Zero infra</p><div class="ferr-card__body"><p>A single binary with no daemon, no server, no database. Runs wherever your CI runs.</p>
+</div></div>
+</div>
+
+## Why not semantic-release or changesets?
+
+Most versioning tools are coupled to a specific ecosystem or require Node.js to be present in your CI.
+
+| Tool             | Monorepo    | Multi-language | Runtime  |
+| ---------------- | ----------- | -------------- | -------- |
+| semantic-release | via plugins | JS/Node only   | Node.js  |
+| changesets       | manual bump | JS only        | Node.js  |
+| release-please   | limited     | partial        | Node.js  |
+| cargo-release    | no          | Rust only      | Rust     |
+| **FerrFlow**     | **native**  | **any**        | **none** |
+
+FerrFlow ships as a compiled binary. Drop it in any CI environment without installing a runtime. A WASM build (`@ferrflow/wasm`) is also available for browser-side usage.
+
+For side-by-side latency, peak memory and install size against the JS ecosystem release tools, see [Performance](/performance): numbers refresh on every FerrFlow release.
+
+<aside class="ferr-aside ferr-aside--note"><p class="ferr-aside__title">Heads up</p><div class="ferr-aside__body"><p>FerrFlow is versioning only. Issue tracking, secrets, and AI agents live in separate FerrLabs products.</p>
+</div></aside>
+
+## How it works
+
+1. **Reads commits** since the last git tag for each package
+2. **Determines the bump** from [Conventional Commits](/docs/reference/conventional-commits) (`feat` → minor, `fix` → patch, breaking → major)
+3. **Updates version files**: `Cargo.toml`, `package.json`, `pom.xml`, etc.
+4. **Writes the changelog** in Keep a Changelog format
+5. **Creates a git tag** (`api@v1.2.0`) and pushes
+6. **Publishes a GitHub/GitLab release** with the changelog as release notes
+
+In a monorepo, FerrFlow only releases packages that have changed, and understands shared dependency paths.
+
+## Key features
+
+- **Pre/post-release hooks**: run scripts at every lifecycle stage (bump, commit, publish, failure)
+- **Query commands**: `ferrflow version`, `ferrflow tag`, and `ferrflow status` for CI scripting, plus `ferrflow why` to explain a package's release decision
+- **Any version file**: Cargo.toml, package.json, pom.xml, build.gradle, Chart.yaml, plain text, and more
+- **Browser support**: `@ferrflow/wasm` brings commit parsing, bump computation, and changelog generation to the browser

package/docs-en/quickstart.md

@@ -0,0 +1,66 @@
+---
+title: Quick start
+description: Go from zero to your first automated release in under 5 minutes.
+---
+
+<ol>
+<li><p><strong>Scaffold the config</strong></p>
+<p>Run <code>ferrflow init</code> at the root of your repository. It detects your version files and writes a <code>.ferrflow</code> config:</p>
+<pre><code class="language-bash">ferrflow init
+</code></pre>
+<p>For a Rust project this produces:</p>
+<pre><code class="language-json">{
+  &quot;$schema&quot;: &quot;https://ferrflow.com/schema/ferrflow.json&quot;,
+  &quot;workspace&quot;: {
+    &quot;tagTemplate&quot;: &quot;v{version}&quot;
+  },
+  &quot;package&quot;: [
+    {
+      &quot;name&quot;: &quot;my-app&quot;,
+      &quot;path&quot;: &quot;.&quot;,
+      &quot;changelog&quot;: &quot;CHANGELOG.md&quot;,
+      &quot;versionedFiles&quot;: [
+        { &quot;path&quot;: &quot;Cargo.toml&quot;, &quot;format&quot;: &quot;toml&quot; }
+      ]
+    }
+  ]
+}
+</code></pre>
+</li>
+<li><p><strong>Preview what would happen</strong></p>
+<p>Before touching anything, run a dry-run to see what FerrFlow would do:</p>
+<pre><code class="language-bash">ferrflow check
+</code></pre>
+<p>Output:</p>
+<pre><code>Scanning . ...
+→ feat: add user authentication
+→ fix: correct pagination offset
+
+Bump my-app 0.1.0 → 0.2.0
+Tag v0.2.0
+</code></pre>
+</li>
+<li><p><strong>Run the release</strong></p>
+<pre><code class="language-bash">ferrflow release
+</code></pre>
+<p>FerrFlow will:</p>
+<ul>
+<li>Update <code>Cargo.toml</code> to <code>0.2.0</code></li>
+<li>Append to <code>CHANGELOG.md</code></li>
+<li>Commit the changes</li>
+<li>Create and push <code>v0.2.0</code></li>
+<li>Create a GitHub release (if <code>GITHUB_TOKEN</code> is set)</li>
+</ul>
+</li>
+</ol>
+
+<aside class="ferr-aside ferr-aside--tip"><p class="ferr-aside__title">Starting from scratch</p><div class="ferr-aside__body"><p>No prior tag? FerrFlow v3 bootstraps from the strategy&#39;s zero value automatically: the first <code>feat:</code> lands at <code>0.1.0</code>, the first <code>fix:</code> at <code>0.0.1</code>. You don&#39;t need to create a <code>v0.0.0</code> tag by hand. See <a href="/docs/reference/cli#which-version-is-bumped-from">how the baseline is chosen</a>.</p>
+</div></aside>
+
+## Next steps
+
+- Set up [GitHub Actions](/docs/ci/github-actions) to run releases automatically on push to `main`
+- Configure a [monorepo](/docs/configuration/monorepo) if you have multiple packages
+- Add [pre/post-release hooks](/docs/configuration/config-file#hooks) for custom scripts during the release lifecycle
+- Use `ferrflow version` and `ferrflow tag` in CI scripts: see the [CLI reference](/docs/reference/cli)
+- Review the full [config reference](/docs/configuration/config-file)

package/docs-en/reference/api.md

@@ -0,0 +1,106 @@
+---
+title: FerrFlow API
+description: 'Hosted HTTP endpoints for FerrFlow: validate configs, preview version bumps, resolve the latest release, and fetch the config schema.'
+---
+
+The FerrFlow API exposes a small set of hosted HTTP endpoints under `https://api.ferrflow.com/v1/ferrflow/*`. They are backed by the same FerrFlow core the CLI runs, so `validate` and `preview` return results identical to `ferrflow validate` and `ferrflow check`. No second implementation to drift.
+
+Every endpoint is public (no authentication) and safe to call from CI, editors, or a browser. The machine-readable contract is served at [`/v1/ferrflow/openapi.json`](https://api.ferrflow.com/v1/ferrflow/openapi.json) (OpenAPI 3.1).
+
+`https://api.ferrlabs.com/v1/ferrflow/*` reaches the same endpoints and keeps working indefinitely. It is where the API was first published, and released CLI versions still call it. Prefer `api.ferrflow.com` in anything new.
+
+## `GET /v1/ferrflow/health`
+
+Liveness and version probe. Powers status dashboards.
+
+```json
+{ "status": "ok", "service": "ferrflow-api", "version": "10.17.0", "time": "2026-07-21T15:00:00Z" }
+```
+
+## `GET /v1/ferrflow/schema`
+
+Returns the config JSON Schema (`Content-Type: application/schema+json`), served from the schema bundled in the FerrFlow release: the same bytes the CLI validates against. Sends a strong `ETag` and `Cache-Control`, so point your editor's `$schema` here:
+
+```json
+{ "$schema": "https://api.ferrflow.com/v1/ferrflow/schema" }
+```
+
+`GET /v1/ferrflow/schema/v{major}` returns the schema frozen at a CLI major (e.g. `/schema/v5`). Only the current major is served today; older majors return `404` until per-major snapshots land.
+
+## `GET /v1/ferrflow/latest`
+
+Resolves the latest FerrFlow release from GitHub, cached server-side. Pass `platform` to get a single asset:
+
+```bash
+curl "https://api.ferrflow.com/v1/ferrflow/latest?platform=linux-x64"
+```
+
+```json
+{
+  "version": "5.48.0",
+  "tag": "v5.48.0",
+  "platform": "linux-x64",
+  "download_url": "https://github.com/FerrLabs/FerrFlow/releases/download/v5.48.0/ferrflow-linux-x64.tar.gz",
+  "bundle_url": "https://github.com/FerrLabs/FerrFlow/releases/download/v5.48.0/ferrflow-linux-x64.tar.gz.bundle",
+  "published_at": "2026-07-27T19:20:00Z"
+}
+```
+
+Releases are signed with [Sigstore](/verifying-releases/): verify the `.bundle` rather than a checksum (releases up to v5.47.4 carry a `.sig` + `.crt` pair instead). Without `platform`, the response lists `assets` for every platform. Valid platforms: `linux-x64`, `linux-arm64`, `linux-arm`, `darwin-x64`, `darwin-arm64`, `win32-x64`, `win32-arm64`.
+
+## `POST /v1/ferrflow/validate`
+
+Validates a config without a repo. You send the config text and, optionally, the contents of the versioned files it references so the file-existence and version-consistency checks run. The result is identical to `ferrflow validate --json`.
+
+```bash
+curl -X POST https://api.ferrflow.com/v1/ferrflow/validate \
+  -H 'content-type: application/json' \
+  -d '{
+    "config": "{\"package\":[{\"name\":\"app\",\"path\":\".\",\"versionedFiles\":[{\"path\":\"package.json\",\"format\":\"json\"}]}]}",
+    "files": { "package.json": "{\"version\":\"1.0.0\"}" }
+  }'
+```
+
+```json
+{
+  "valid": true,
+  "config_file": null,
+  "package_count": 1,
+  "errors": [],
+  "warnings": [],
+  "suggestions": []
+}
+```
+
+An invalid config is still a successful validation: the response is `200` with `"valid": false` and the offending entries. Only a malformed request body returns `400`. The optional `format` field (`json` | `json5` | `toml`) skips format inference.
+
+## `POST /v1/ferrflow/preview`
+
+Computes the version bumps and changelog for an explicit list of commits: the same logic as `ferrflow check`, as a service. No repo access; you pass the commits.
+
+```bash
+curl -X POST https://api.ferrflow.com/v1/ferrflow/preview \
+  -H 'content-type: application/json' \
+  -d '{
+    "config": "{\"package\":[{\"name\":\"api\",\"path\":\".\"}]}",
+    "commits": [{ "message": "feat(api): add endpoint", "hash": "a1b2" }],
+    "current_versions": { "api": "1.2.3" }
+  }'
+```
+
+```json
+{
+  "packages": [
+    {
+      "name": "api",
+      "current": "1.2.3",
+      "next": "1.3.0",
+      "bump": "minor",
+      "commits": [{ "hash": "a1b2", "type": "feat", "scope": "api", "breaking": false }],
+      "changelog": "### Features\n- ..."
+    }
+  ]
+}
+```
+
+In a monorepo config, each commit is assigned to a package when its `files` fall under that package's `path`. Packages with no releasable commit are omitted.