bitdynamics-ab · zheli · Sep 21, 2026 · Sep 21, 2026 · Sep 21, 2026
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -4,9 +4,9 @@ Canton DevKit is a single Go binary that orchestrates the Splice
 LocalNet Docker stack. It ships two ways:
 
 1. **DPM component** (primary) — install through the Daml Package
-   Manager and invoke as `dpm localnet <command>`.
+  Manager and invoke as `dpm localnet <command>`.
 2. **Standalone binary** (`canton-devkit`) — a self-contained
-   executable for users who don't run DPM (CI, DevOps, workshop
+  executable for users who don't run DPM (CI, DevOps, workshop
    facilitators), shipped as release archives. Invoke as
    `canton-devkit localnet <command>`.
 
@@ -19,14 +19,18 @@ tree**. Throughout the docs, `dpm localnet <cmd>` and
 > never changes host permissions. It orchestrates the existing Splice
 > LocalNet container stack.
 
+
+
 ## 1. Prerequisites
 
-| Requirement | Why | Check |
-|---|---|---|
-| Docker Engine / Desktop | DevKit runs LocalNet as containers | `docker version` |
-| Docker Compose **v2** | LocalNet is a compose project | `docker compose version` |
-| ~8 GB free RAM for Docker | Splice stack is memory-hungry | Docker Desktop → Settings → Resources |
-| ~20 GB free disk | Splice images + volumes | `df -h` |
+
+| Requirement               | Why                                | Check                                 |
+| ------------------------- | ---------------------------------- | ------------------------------------- |
+| Docker Engine / Desktop   | DevKit runs LocalNet as containers | `docker version`                      |
+| Docker Compose **v2**     | LocalNet is a compose project      | `docker compose version`              |
+| ~8 GB free RAM for Docker | Splice stack is memory-hungry      | Docker Desktop → Settings → Resources |
+| ~20 GB free disk          | Splice images + volumes            | `df -h`                               |
+
 
 Run the built-in host check at any time — it never modifies anything:
 
@@ -89,6 +93,7 @@ contains the `canton-devkit` binary plus `LICENSE` and `README.md`. Every
 release also publishes a single `SHA256SUMS` file covering all archives.
 
 ### Quick install (macOS arm64 / Linux amd64)
+
 ```bash
 curl -fsSL https://raw.githubusercontent.com/bitdynamics-ab/canton-devkit/main/install.sh | sh
 ```
@@ -119,18 +124,20 @@ Supported platforms:
 - macOS Apple Silicon (`darwin/arm64`)
 - Linux x86_64 (`linux/amd64`)
 
+
+
 ### Homebrew (macOS arm64 / Linux amd64)
 
 ```bash
 brew tap bitdynamics-ab/canton-devkit
 brew install bitdynamics-ab/canton-devkit/canton-devkit
 ```
 
-To upgrade after a new release is published:
+To upgrade after a new release is published, refresh the tap and then
+upgrade the formula:
 
 ```bash
-brew update
-brew upgrade canton-devkit
+brew update && brew upgrade canton-devkit
 ```
 
 The formula downloads platform-specific release tarballs from this
@@ -146,6 +153,8 @@ the tap only hosts the Homebrew formula.
 > `/etc/apt/sources.list.d/canton-devkit.list`, remove that file and use
 > the quick-install script, a release tarball, or Homebrew instead.
 
+
+
 ### Manual download — macOS (Apple Silicon)
 
 Download the binary for your platform from the
@@ -168,6 +177,8 @@ xattr -d com.apple.quarantine /usr/local/bin/canton-devkit 2>/dev/null || true
 canton-devkit version
 ```
 
+
+
 ### Manual download — Linux (amd64)
 
 ```bash
@@ -183,6 +194,8 @@ sudo mv canton-devkit /usr/local/bin/
 canton-devkit version
 ```
 
+
+
 ### Windows (amd64, PowerShell)
 
 ```powershell
@@ -221,24 +234,29 @@ the WSL 2 backend.
 go install github.com/bitdynamics-ab/canton-devkit/cmd/canton-devkit@latest
 ```
 
+
+
 ## 4. Compatibility matrix
 
+
+
 ### Platforms (released, tested)
 
-| OS | Arch | Status |
-|---|---|---|
-| macOS | arm64 (Apple Silicon) | ✅ Supported |
-| Linux | amd64 | ✅ Supported |
-| Windows | amd64 | ✅ Supported |
+
+| OS      | Arch                  | Status      |
+| ------- | --------------------- | ----------- |
+| macOS   | arm64 (Apple Silicon) | ✅ Supported |
+| Linux   | amd64                 | ✅ Supported |
+| Windows | amd64                 | ✅ Supported |
+
 
 Other OS/arch combinations may work (DevKit only orchestrates Docker)
 but are untested — `localnet doctor` prints a warning on unsupported
 platforms.
 
 ### Splice LocalNet versions
 
-DevKit pins a catalogue of tested Splice versions; `localnet up
---version <tag>` selects one. List them at runtime:
+DevKit pins a catalogue of tested Splice versions; `localnet up --version <tag>` selects one. List them at runtime:
 
 ```bash
 canton-devkit localnet versions
@@ -250,15 +268,17 @@ at your own risk via `up --version <tag> --allow-uncurated`.
 
 ## 5. Troubleshooting the install
 
-| Symptom | Cause | Fix |
-|---|---|---|
-| `doctor` says **Docker daemon** ✗ | Docker not running | Start Docker Desktop / `sudo systemctl start docker` |
-| `doctor` says **Compose v2** ✗ | Only Compose v1 present | Upgrade to Docker Compose v2 (`docker compose`, not `docker-compose`) |
-| `up` fails **PORTS_IN_USE** | Another process holds a port | Stop the conflicting process, or use a different `--name` |
-| `up` hangs at "waiting for healthy" | Insufficient Docker memory | Raise Docker memory to ≥ 8 GB; see [Known limitations](limitations.md) |
-| Linux: `permission denied` on the Docker socket | User not in `docker` group | `sudo usermod -aG docker $USER` then re-login |
-| macOS: "cannot be opened because the developer cannot be verified" | Gatekeeper quarantine | `xattr -d com.apple.quarantine $(which canton-devkit)` |
-| Web UI / Explorer shows stale ports after a restart | Docker re-assigned ephemeral ports | DevKit re-captures them within ~15 s; or run `localnet restart --name <n>` |
+
+| Symptom                                                            | Cause                              | Fix                                                                        |
+| ------------------------------------------------------------------ | ---------------------------------- | -------------------------------------------------------------------------- |
+| `doctor` says **Docker daemon** ✗                                  | Docker not running                 | Start Docker Desktop / `sudo systemctl start docker`                       |
+| `doctor` says **Compose v2** ✗                                     | Only Compose v1 present            | Upgrade to Docker Compose v2 (`docker compose`, not `docker-compose`)      |
+| `up` fails **PORTS_IN_USE**                                        | Another process holds a port       | Stop the conflicting process, or use a different `--name`                  |
+| `up` hangs at "waiting for healthy"                                | Insufficient Docker memory         | Raise Docker memory to ≥ 8 GB; see [Known limitations](limitations.md)     |
+| Linux: `permission denied` on the Docker socket                    | User not in `docker` group         | `sudo usermod -aG docker $USER` then re-login                              |
+| macOS: "cannot be opened because the developer cannot be verified" | Gatekeeper quarantine              | `xattr -d com.apple.quarantine $(which canton-devkit)`                     |
+| Web UI / Explorer shows stale ports after a restart                | Docker re-assigned ephemeral ports | DevKit re-captures them within ~15 s; or run `localnet restart --name <n>` |
+
 
 For anything else, attach the full `localnet doctor` output to a
 [GitHub issue](https://github.com/bitdynamics-ab/canton-devkit/issues) —
@@ -267,9 +287,10 @@ it includes OS/arch, Docker/Compose versions, and the check results.
 ## 6. Next steps
 
 - [HackCanton Season 3 starter](hackcanton-s3.md) — install, one
-  working example, and the breaks that eat day-one time.
+working example, and the breaks that eat day-one time.
 - [LocalNet lifecycle](localnet-lifecycle.md) — zero to a running
-  LocalNet, multiple instances, deterministic ports, and clean-up.
+LocalNet, multiple instances, deterministic ports, and clean-up.
 - [Tokens](tokens.md) — CIP-0112 token flows on LocalNet.
 - [Explorer](explorer.md) — browse the Active Contract Set and
-  recent transactions from the Web UI.
+recent transactions from the Web UI.
+
diff --git a/docs/homebrew.md b/docs/homebrew.md
@@ -31,13 +31,43 @@ brew install bitdynamics-ab/canton-devkit/canton-devkit
 
 ## Upgrade
 
-After a new release is published and the formula is updated:
+Homebrew separates refreshing formula metadata from installing a newer
+binary:
+
+- `brew update` — pulls the latest formula from this tap (and other taps)
+- `brew upgrade canton-devkit` — installs a newer release when the
+  formula version is ahead of what you have installed
+
+`brew update` does not take a formula name. Passing one (for example
+`brew update canton-devkit`) does not upgrade the package; Homebrew may
+remap that to `brew upgrade`, but only against whatever formula version
+your local tap already has.
+
+After a new release is published:
 
 ```sh
 brew update
 brew upgrade canton-devkit
 ```
 
+Or as one line:
+
+```sh
+brew update && brew upgrade canton-devkit
+```
+
+`brew upgrade canton-devkit` alone is often enough, because Homebrew may
+auto-refresh taps before upgrading. If it reports the installed version
+is already current right after a new release, run `brew update` first,
+then `brew upgrade canton-devkit` again.
+
+Confirm the installed version:
+
+```sh
+canton-devkit version
+brew info canton-devkit
+```
+
 ## How the formula stays in sync
 
 This is **automatic** on every release tag (`v*`). `.github/workflows/release.yml`:

diff --git a/website/docs-map.mjs b/website/docs-map.mjs
@@ -22,7 +22,7 @@ export const docsMap = [
   { src: 'observability.md', dest: 'guides/observability', description: 'Enable the observability profile for Prometheus + Grafana, understand the live Splice metric naming convention, and toggle the sidecars at runtime.' },
   { src: 'dashboard-customization.md', dest: 'guides/dashboard-customization', description: 'Extend, replace, or restore the bundled Grafana dashboard for a running LocalNet — panels, template variables, and persistence across down/up cycles.' },
   { src: 'tokens.md', dest: 'guides/tokens', description: 'Work with Canton Token Standard instruments on a live LocalNet — CIP-0056 assets and Token Standard V2 (CIP-0112) — from the CLI or the Web UI.' },
-  { src: 'homebrew.md', dest: 'guides/homebrew', description: 'Install canton-devkit via the Homebrew tap or direct formula, and how the formula is kept in sync on every release.' },
+  { src: 'homebrew.md', dest: 'guides/homebrew', description: 'Install and upgrade canton-devkit via the Homebrew tap, and how the formula is kept in sync on every release.' },
   { src: 'faq.md', dest: 'reference/faq', description: 'Common questions about canton-devkit: what it is, how the CLI and Web UI relate, versions, and day-to-day usage.' },
   { src: 'versions.md', dest: 'reference/versions', description: 'How DevKit pins tested Splice LocalNet versions by commit SHA and content hash, discovers upstream tags, and resolves uncurated versions on opt-in.' },
   { src: 'packaging.md', dest: 'reference/packaging', description: 'How canton-devkit ships — standalone binaries, the DPM component, and the Homebrew tap — and the current supply-chain integrity story.' },