@ferrflow/doc 7.17.0

package/docs-v2/configuration/formats.md

@@ -0,0 +1,98 @@
+---
+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>
+</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>
+<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>
+
+## 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 class="ferr-tab" data-label="YAML"><p class="ferr-tab__label">YAML</p><div class="ferr-tab__body"><pre><code class="language-yaml">package:
+  versionedFiles:
+    - path: Cargo.toml
+      format: toml
+    - path: npm/package.json
+      format: json
+</code></pre>
+</div></div>
+</div>
+
+Both files will be updated to the same version before the git commit.

package/docs-v2/configuration/monorepo.md

@@ -0,0 +1,324 @@
+---
+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 automatically receives a patch bump — even if none of its own files changed. 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>
+
+<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>
+
+## 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-v2/installation.md

@@ -0,0 +1,48 @@
+---
+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 ferrflow
+# or as a dev dependency
+npm install -D 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@v2
+  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
+```

package/docs-v2/introduction.md

@@ -0,0 +1,40 @@
+---
+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.
+
+## 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.
+
+## 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
+- **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-v2/legal/telemetry.md

@@ -0,0 +1,66 @@
+---
+title: Telemetry
+description: What FerrFlow collects, how data is anonymized, and how to opt out.
+---
+
+FerrFlow collects anonymous usage telemetry to help improve the tool. This page explains exactly what is sent, how it is anonymized, and how to disable it.
+
+## What is collected
+
+Each time you run a command, FerrFlow may send a single event containing:
+
+| Field           | Description                                                         |
+| --------------- | ------------------------------------------------------------------- |
+| `event_type`    | The action performed: `check`, `release`, `version_bump`, or `init` |
+| `commits_count` | Number of commits since the last release                            |
+| `repo_hash`     | A SHA-256 hash of your git remote URL (see below)                   |
+
+Only fields relevant to the command are included. Empty fields are omitted.
+
+## How data is anonymized
+
+Your repository URL is **never sent in plain text**. FerrFlow computes a SHA-256 hash of the git remote URL and sends only the resulting hex digest. This lets us count unique repositories without knowing which repositories they are.
+
+No source code, file names, commit messages, branch names, package names, version numbers, IP addresses, or personal information are ever collected or stored.
+
+## Where data is sent
+
+Events are sent as a POST request to `https://api.ferrflow.com/events`. The request is asynchronous and non-blocking — it never slows down your workflow. If the request fails, it is silently discarded.
+
+## How to opt out
+
+You can disable telemetry entirely using either an environment variable or your config file.
+
+### Environment variable
+
+<div class="ferr-tabs">
+  <div class="ferr-tab" data-label="Linux / macOS"><p class="ferr-tab__label">Linux / macOS</p><div class="ferr-tab__body"><pre><code class="language-bash">export FERRFLOW_ANONYMOUS_TELEMETRY=false
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="Windows"><p class="ferr-tab__label">Windows</p><div class="ferr-tab__body"><pre><code class="language-powershell">$env:FERRFLOW_ANONYMOUS_TELEMETRY = &quot;false&quot;
+</code></pre>
+</div></div>
+</div>
+
+Accepted values to disable: `false`, `0`, `off`, `no` (case-insensitive).
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p><code>FERRFLOW_TELEMETRY=false</code> also works as a fallback.</p>
+</div></aside>
+
+### Config file
+
+<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;telemetry&quot;: false
+  }
+}
+</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]
+telemetry = false
+</code></pre>
+</div></div>
+</div>
+
+Either method is sufficient to disable telemetry. If the config file disables it, the environment variable cannot re-enable it, and vice versa.

package/docs-v2/quickstart.md

@@ -0,0 +1,63 @@
+---
+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>
+
+## 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)