From 0d471c6a5c405b48d84aec2d86f791f975f3f431 Mon Sep 17 00:00:00 2001 From: bubbapang Date: Fri, 4 Sep 2026 11:08:06 +0800 Subject: [PATCH 1/3] mining-skill: correct the "current releases are pre-auth" claim Line 19 stated that GitHub releases/latest are pre-auth (node v0.9.0-endless-sky, miner v3.3.1). That has been false since node v0.10.0 (2026-08-13) and miner v4.0.2 (2026-09-01), both of which require miner QUIC auth. An agent following the skill as written would expect a pre-auth pair and skip waiting for miner-auth-token. The probe logic is unchanged; only the factual claim about what "latest" is today is corrected, and dated so it cannot silently rot the same way. Line 52's "(today's latest)" label on the both-no branch is renamed "(pre-auth pair)" for the same reason. Co-Authored-By: Claude Sonnet 5 --- static/skills/mining-skill.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/static/skills/mining-skill.md b/static/skills/mining-skill.md index 3383253..c587856 100644 --- a/static/skills/mining-skill.md +++ b/static/skills/mining-skill.md @@ -16,7 +16,7 @@ Mining commands and flags are aligned with chain MINING.md (https://github.com/Q **Critical architecture:** The node is the QUIC server (listens on port 9833 via `--miner-listen-port`). The external miner is the QUIC client (connects via `--node-addr`). Start the node first; wait for it to log that the miner server is listening before starting the miner. Node and miner versions must be a matching pair. -**Miner protocol -- probe the binaries you actually downloaded.** Current GitHub `releases/latest` are pre-auth (node `v0.9.0-endless-sky`, miner `v3.3.1`). Do **not** wait for `miner-auth-token` or pass `--auth-token-file` unless **both** binaries advertise those flags. +**Miner protocol -- probe the binaries you actually downloaded.** As of 2026-09-03, GitHub `releases/latest` are auth-era (node `v0.10.0`, miner `v4.0.2`); node `v0.9.0-endless-sky` / miner `v3.3.1` and earlier are pre-auth. Do **not** wait for `miner-auth-token` or pass `--auth-token-file` unless **both** binaries advertise those flags. Capture `--help` exit status first. A non-zero exit is a broken, quarantined, or wrong-architecture binary -- **stop** and fix it. Do **not** treat a failed probe as pre-auth (`*_auth=no`). Do not pipe `--help` into `grep` until the command itself exits 0. @@ -49,7 +49,7 @@ echo "node_auth=${node_auth} miner_auth=${miner_auth}" Replace `./quantus-node` / `./quantus-miner` with the actual downloaded filenames. `/usr/bin/false` (or any failed `--help`) must exit 1 here and must not print `node_auth=no`. -- **Both no, after successful `--help` (today's latest):** wait only for "miner server listening"; start the miner with `--node-addr` only. +- **Both no, after successful `--help` (pre-auth pair):** wait only for "miner server listening"; start the miner with `--node-addr` only. - **Both yes:** wait for `miner-auth-token` and `miner-tls-cert-sha256` under the chain directory, then pass `--auth-token-file` and `--tls-cert-sha256-file`. ALPN is `quantus-miner/2`. - **Mixed:** stop. Pin a matching pair (`NODE_VERSION` / `MINER_VERSION` in `mining.conf`, then `setup --force`); do not mix independent `releases/latest` tags. From 9b2e07dc91668d908e5e389c1429b39284838684 Mon Sep 17 00:00:00 2001 From: bubbapang Date: Fri, 4 Sep 2026 16:55:02 +0800 Subject: [PATCH 2/3] mining guide: a Windows path without WSL2, and a one-command skill install Two additions at the top of the guide, no existing instructions changed. The guide says it works on "macOS and Linux (including WSL2 on Windows)", and the setup script does need WSL2. A Windows user without it finishes the intro with nothing to run, even though the Miner App already covers that case and is the most-downloaded artifact of miner-v0.6.1 (21 Windows downloads, against 8 Linux and 3 macOS). Added a pointer to it. It links the GitHub release rather than docs/guides/miner-app.md because that page is draft: true and currently 404s. If the flag lifts, the link should move to the guide. The guide also tells agent users to press Copy Context and paste. For Claude Code the skill can just be installed, which is faster and persists across sessions. Verified against an isolated HOME: exit 0, 323 lines, frontmatter intact. Co-Authored-By: Claude Sonnet 5 --- docs/guides/mining.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/guides/mining.md b/docs/guides/mining.md index 67f110e..e76acc1 100644 --- a/docs/guides/mining.md +++ b/docs/guides/mining.md @@ -5,10 +5,20 @@ title: Mining and Running a Node # Mining and Running a Node -This guide covers connecting to the Quantus Planck testnet and mining. Works on macOS and Linux (including WSL2 on Windows). +This guide covers connecting to the Quantus Planck testnet and mining. The setup script below runs on macOS and Linux, including WSL2 on Windows. + +**On Windows without WSL2?** Use the [Miner App](https://github.com/Quantus-Network/quantus-apps/releases/latest) (`quantus_miner_windows.zip`) instead. It is a desktop app that downloads the node for you and handles identity, mining, and rewards in one window, with no terminal. Use the **Copy Context** button at the top of this page to copy everything as Markdown -- the full guide plus an AI mining skill. Paste it to an agent like Claude Code to be walked through setup interactively, or keep it as an offline reference. +If you use Claude Code, install the skill from disk in one command instead of pasting: + +```bash +mkdir -p ~/.claude/skills/mining && curl -fsSL https://docs.quantus.com/skills/mining-skill.md -o ~/.claude/skills/mining/SKILL.md +``` + +Then run `/mining`. The skill walks the same steps as this guide, and it probes the binaries you actually downloaded before starting anything, so it will not hand you a mismatched node and miner pair. + ## Prerequisites Before starting, you will need: From ff2a6f00cbd580ad73d1f3656722e5df3d30ef10 Mon Sep 17 00:00:00 2001 From: bubbapang Date: Fri, 4 Sep 2026 17:10:01 +0800 Subject: [PATCH 3/3] mining guide: give the skill install a PowerShell variant that actually runs The one-command install was bash only. On Windows PowerShell 5.1, still the default shell on Windows, it fails twice: && is a parser error there, and curl is an alias for Invoke-WebRequest, which does not accept -fsSL. A Windows reader following the guide in the shell they already have open hits a parser error before anything downloads. Tested on this machine, writing to an explicit path each time: Git Bash bash line exit 0, 16508 bytes PowerShell 5.1 bash line parser error at &&, then curl alias PowerShell 5.1 PowerShell line exit 0, 16508 bytes PowerShell 7.6 PowerShell line exit 0 The PowerShell version invokes curl.exe explicitly and separates statements with a semicolon, so it runs on both 5.1 and 7. The note under the block records why, so nobody later collapses the two blocks back into one that only works in bash. Co-Authored-By: Claude Sonnet 5 --- docs/guides/mining.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/guides/mining.md b/docs/guides/mining.md index e76acc1..4119c70 100644 --- a/docs/guides/mining.md +++ b/docs/guides/mining.md @@ -11,12 +11,22 @@ This guide covers connecting to the Quantus Planck testnet and mining. The setup Use the **Copy Context** button at the top of this page to copy everything as Markdown -- the full guide plus an AI mining skill. Paste it to an agent like Claude Code to be walked through setup interactively, or keep it as an offline reference. -If you use Claude Code, install the skill from disk in one command instead of pasting: +If you use Claude Code, install the skill from disk in one command instead of pasting. + +macOS, Linux, or Git Bash on Windows: ```bash mkdir -p ~/.claude/skills/mining && curl -fsSL https://docs.quantus.com/skills/mining-skill.md -o ~/.claude/skills/mining/SKILL.md ``` +Windows PowerShell: + +```powershell +New-Item -ItemType Directory -Force "$HOME\.claude\skills\mining" | Out-Null; curl.exe -fsSL https://docs.quantus.com/skills/mining-skill.md -o "$HOME\.claude\skills\mining\SKILL.md" +``` + +The PowerShell version is not a style preference. Windows PowerShell 5.1, still the default on Windows, treats `&&` as a parser error and aliases `curl` to `Invoke-WebRequest`, which does not accept `-fsSL`. Calling `curl.exe` explicitly and separating with `;` works on both 5.1 and PowerShell 7. + Then run `/mining`. The skill walks the same steps as this guide, and it probes the binaries you actually downloaded before starting anything, so it will not hand you a mismatched node and miner pair. ## Prerequisites