docs(adr): reconcile freshness, authority, and current state

.github/SECURITY.md

@@ -6,10 +6,10 @@ This repository is an **operator skill**: documentation and skill files that ins
 
 ## Security posture
 
-- **Non-custodial by construction.** Nodes are configured with a **public** wallet (rewards) address only. The skill never generates, stores, requests, logs, or transmits a private key, seed phrase, `SECRET_KEY`, or `AUTONOMI_WALLET_KEY` (ADR-0004). Any future spend/custody capability lives in an out-of-context substrate — never in the agent context, the skill, or this repo.
+- **Non-custodial by construction.** Nodes are configured with a **public** wallet (rewards) address only. The current skill generates, stores, requests, logs, and transmits no private key, seed phrase, `SECRET_KEY`, or `AUTONOMI_WALLET_KEY` (ADR-0004). Any future spend/custody capability requires a separately approved substrate that keeps secrets outside the agent context; ADR-0004 deliberately leaves that substrate's implementation location open.
 - **No secrets in the repo.** Never commit a private key or secret in code, examples, fixtures, or logs. If one is ever exposed, treat it as compromised: abandon/rotate the affected address and remove the secret from history.
-- **Source-bound, no invented surface.** Commands, flags, and install steps are pinned to upstream source (ADR-0006); installs are detect-first and non-mutating (ADR-0009). This limits the chance of the skill instructing an unsafe or fabricated action.
-- **Verified distribution.** Install steps and releases verify checksums and signatures before use (ML-DSA-65 / FIPS-204; `SHA256SUMS`), and the package is built to pass distribution-channel security scans (ADR-0008).
+- **Source-bound, no invented Autonomi surface.** Autonomi-specific commands, flags, constants, figures, and install behaviour carry explicit provenance under ADR-0006; ordinary operating-system/shell observation commands are not presented as Autonomi facts and **must be** reviewed for every claimed platform. The current Windows guidance has known unverified gaps recorded in `planning/HANDOFF.md`. Installs are detect-first and do not mutate an existing working setup by default (ADR-0009). This limits the chance of the skill instructing an unsafe or fabricated action.
+- **Distribution verification is a required target, not a current guarantee.** Upstream releases provide ML-DSA-65 / FIPS-204 signatures and `SHA256SUMS`, but the current script-based install route does not verify them before execution. Until every supported route performs and proves checksum/signature verification, contributors and documentation must not claim verified delivery (ADR-0008).
 
 ## Reporting a vulnerability
 

.github/pull_request_template.md

@@ -30,11 +30,11 @@ The aim: a reviewer — human or agent — can understand this PR and sanity-che
 
 - [ ] No secrets in the diff — no private key, seed phrase, `SECRET_KEY`, or `AUTONOMI_WALLET_KEY` in code, examples, or logs.
 - [ ] Non-custodial boundary intact — nodes take a public wallet (rewards) address only; nothing instructs putting a key on a node or in the repo (ADR-0004).
-- [ ] Install stays detect-first and non-mutating; any download/verify step is documented and source-bound (ADR-0009).
+- [ ] Install stays detect-first and does not mutate an existing working setup by default; any download/verify step is documented and source-bound (ADR-0009).
 
 ## Quality & verification
 
-- [ ] Every command, flag, constant, and figure is pinned to upstream source (repo / file / symbol / commit); nothing invented — anything unconfirmable is flagged, not guessed (ADR-0006).
+- [ ] Every Autonomi-specific command, flag, constant, figure, and install behaviour has explicit provenance; temporary team-confirmed exceptions are labelled pending upstream authority, and platform-specific shell/OS behaviour is checked rather than guessed (ADR-0006).
 - [ ] `python3 scripts/adr-governance.py` passes.
 - [ ] Gauntlet (for merge-candidate skill changes): clean-context test + adversarial review — <!-- done / not yet / N/A -->
 - [ ] Docs updated (DESIGN / README / references) if a surface or behaviour changed.
@@ -44,7 +44,7 @@ The aim: a reviewer — human or agent — can understand this PR and sanity-che
 <!-- Only if this touches SKILL.md, the frontmatter, or the install manifest. -->
 
 - [ ] Frontmatter valid and complete — name, description, version, license, keywords.
-- [ ] Install manifest (`metadata.openclaw.install`) correct; install and clean-uninstall paths documented; signature/checksum verification intact (ADR-0008).
+- [ ] Install manifest (`metadata.openclaw.install`) correct; install and clean-uninstall paths documented; the current signature/checksum verification status is stated accurately, and any implemented verification remains intact (ADR-0008).
 - [ ] Won't break packaging, and should pass distribution-channel security scans (e.g. ClawHub).
 
 ## For reviewers

CONTRIBUTING.md

@@ -7,12 +7,12 @@ Contributors are humans and AI agents alike; these conventions keep the trail re
 ## Ground rules
 
 - **Never commit a secret.** No private key, seed phrase, `SECRET_KEY`, or `AUTONOMI_WALLET_KEY` in code, examples, or logs — nodes use a **public** wallet (rewards) address only (ADR-0004). See [`.github/SECURITY.md`](.github/SECURITY.md).
-- **Source-bind every claim.** Commands, flags, constants, and figures are pinned to upstream source (repo / file / symbol / commit). Don't invent — if it isn't confirmable in source, flag it rather than guess (ADR-0006).
+- **Bind every Autonomi claim to provenance.** Autonomi-specific commands, flags, constants, figures, and install behaviour normally pin to upstream source (repo / file / symbol / commit). Temporary team-confirmed exceptions are explicit and pending upstream authority. Ordinary operating-system/shell observation commands are not Autonomi claims, but platform-specific behaviour must still be checked rather than guessed (ADR-0006).
 - **Decisions go through ADRs.** Architectural, protocol, security, or storage changes add or update a **Proposed** ADR before merge; Accepted ADRs are immutable (supersede, don't edit). See [`docs/adr/README.md`](docs/adr/README.md).
 
 ## Branch & PR flow
 
-- `main` is protected and always stable. Do all work on a short-lived branch off `main`.
+- Project policy treats `main` as protected and stable: do all work on a short-lived branch off `main`. GitHub's configured ruleset is not technically enforced while this private repository is on the organisation's free plan; see `planning/HANDOFF.md` for the current enforcement state.
 - Branch names: `feat/…`, `fix/…`, `docs/…`, `chore/…` (or `name/topic` for personal / WIP branches).
 - Commits follow [Conventional Commits](https://www.conventionalcommits.org): `feat`, `fix`, `docs`, `chore`, `refactor`, `test` — e.g. `feat(tier1): add node preflight checklist`.
 - Open a PR into `main` using the [pull request template](.github/pull_request_template.md). Fill in what's relevant; delete what isn't.

README.md

@@ -8,14 +8,14 @@ This is the home for Autonomi's first-party skills. It holds one or more skills
 
 | Skill | What it's for | Status |
 | --- | --- | --- |
-| **`autonomi`** | Run and manage Autonomi nodes, and earn ANT (the Autonomi Network Token) for the storage they provide. Non-custodial. | **Available** |
+| **`autonomi`** | Run and manage Autonomi nodes, and earn ANT (the Autonomi Network Token) for the storage they provide. Non-custodial. | **Internal preview** |
 | `autonomi-developer` | Build applications *on* Autonomi (libraries, SDK). | Planned — currently at [`WithAutonomi/autonomi-developer-docs`](https://github.com/WithAutonomi/autonomi-developer-docs) |
 
 ## Install
 
 The skill is standards-compliant ([agentskills.io](https://agentskills.io)), so it isn't tied to one channel.
 
-### skills.sh (from GitHub)
+### skills.sh (from GitHub; repository access required while private)
 
 ```bash
 # Install the autonomi skill (it's the only one here, so a bare add installs it)
@@ -27,18 +27,21 @@ npx skills add WithAutonomi/skills --skill autonomi
 
 Useful flags: `--skill <name>` (pick a specific skill), `--all` (install all), `-a <agent>` (target agent, e.g. `opencode`, `claude`, or `*` for all), `-g` (install globally), `-l` (list without installing), `-y` (no prompts). When the repo holds more than one skill, a bare `add` opens an interactive picker keyed on each skill's name + description.
 
-### ClawHub / OpenClaw
+### ClawHub / OpenClaw (future; current installer metadata is unsupported)
 
 ```bash
+# Intended command once compatible metadata is shipped and the skill is listed
 openclaw skills install autonomi
 ```
 
-The skill carries an OpenClaw install manifest in its frontmatter (`metadata.openclaw`) describing how to fetch and verify the upstream `ant` binary.
+The frontmatter contains a legacy `metadata.openclaw` block, but its `shell` and `powershell` installer kinds and its `command` / `verifies` fields are not supported by OpenClaw's current [installer contract](https://github.com/openclaw/openclaw/blob/de2c4b1768d9babd158c49d83aa91b67eff50dbc/src/skills/types.ts#L4-L19) and are ignored by the [parser](https://github.com/openclaw/openclaw/blob/de2c4b1768d9babd158c49d83aa91b67eff50dbc/src/skills/loading/frontmatter.ts#L108-L121). No working OpenClaw installer or public ClawHub listing is claimed. The current script path also lacks checksum/signature verification; compatible metadata, publication, and secure-delivery proof remain open work.
 
 ### What gets installed
 
 The **skill bundle** — `skills/autonomi/SKILL.md` plus its bundled `references/`. The skill is agent-facing instructions; on first use it guides the agent to install the upstream **`ant`** CLI (the Autonomi tool) itself, non-custodially. Nothing here holds keys or moves funds.
 
+> **Platform status:** no platform has completed the full live release test. Windows remains unverified: most operational recipes are Bash-oriented, including disk checks and the read-only balance procedure, and provisioning, troubleshooting, and uninstall incorrectly say the Windows installer does not update `PATH`. Treat these as known examples, not an exhaustive Windows audit; see `planning/HANDOFF.md`.
+
 > **Heads-up — binary install in locked-down sandboxes.** The `ant` installer downloads its binary from GitHub's release CDN (`release-assets.githubusercontent.com`), which some AI-agent sandboxes block even when `github.com` is allowed. The skill detects this and tells you exactly what to allowlist rather than failing silently. Tracked as an upstream/release item in [`planning/release-endpoint-accessibility.md`](planning/release-endpoint-accessibility.md).
 
 ## Repo layout
@@ -52,7 +55,7 @@ skills/<name>/          # the installable skill bundle(s) — the ONLY thing tha
 docs/                   # repo-side, never ships
   adr/                  # architecture decision records
 planning/               # briefs, handoff, open threads
-source-bindings/        # provenance: every command/figure bound to upstream code (drives auto-update)
+source-bindings/        # provenance for commands/sourced figures; drives release regeneration
 scripts/                # maintenance / freshness automation
 ```
 

docs/CURRENT.md

@@ -1,12 +1,14 @@
-# GSD Checkpoint — Autonomi Operator Skill (current state)
+# GSD Checkpoint — Autonomi Operator Skill (2026-Jun-22 snapshot)
+
+> **Historical checkpoint.** This file preserves the state recorded on 22 June 2026 and is not the current entry point. Read `planning/HANDOFF.md` for current state and next actions.
 
 Date: 2026-06-22
 Project: Autonomi Operator Skill (`JimCollinson/autonomi-skill`)
 Slice/question: Design phase (engine, personas, grounding) complete and merged to `main`; Tier-1 operate-and-earn skill authored and merged. Next: the build round (apply the design to the skill content) + the Tier-1 verification gauntlet.
 Prepared by: Cowork (Claude) orchestration, on Jim's behalf
 Agents/tools used: Cowork (Claude); deep source-research subagents against `WithAutonomi/*` and `saorsa-labs/*`; GitHub; Autonomi canonical docs (`autonomi.com/llms.txt`).
 
-> **Read this first if you are the incoming agent.** Fetch the real `main` (tip below) before doing anything — design and docs were updated via reviewed PRs, so a stale local clone may be missing files. Follow the coordination protocol in `CONTRIBUTING.md` (lanes; branch + PR, never commit to `main` directly; fetch/rebase before a session and after each merge). Reading order: `README.md` → `docs/VISION.md` → `docs/DESIGN.md` (esp. §13) → `docs/adr/` → `docs/operating-doctrine.md` → `docs/skill-grounding.md` → `SKILL.md` + `references/` + `source-bindings/tier1-operate-and-earn.md` → `planning/ROADMAP.md`.
+> At this checkpoint, the reading order was: `README.md` → `docs/VISION.md` → `docs/DESIGN.md` (esp. §13) → `docs/adr/` → `docs/operating-doctrine.md` → `docs/skill-grounding.md` → `SKILL.md` + `references/` + `source-bindings/tier1-operate-and-earn.md` → `planning/ROADMAP.md`.
 
 ## Status
 
@@ -59,7 +61,7 @@ Adversarial review:
 
 - ADRs are **Proposed, not Accepted** — acceptance is a human gate (Jim decision-owner, after review). Never mark Accepted autonomously; supersede, don't edit.
 - **Tier 2/3 are gated** on the custody (ADR-0004) and gas (ADR-0005) team decisions — do not start them; the build round stays in **ungated operate-and-earn**.
-- `docs/SOURCE-MAP.md` has minor stale bits: it still calls the close-group size "5 and 7" (resolved to **7**) and says "evmlib not needed for Tier-1" (the key-free balance read does use evmlib as provenance). Tidy in a later pass.
+- The stale SOURCE-MAP orientation noted at this checkpoint (close-group size and Tier-1 `evmlib` provenance) is corrected in PR #12's current-state reconciliation.
 - The full source-research synthesis is held in Cowork's working notes (not the repo); the repo carries the conclusions (doctrine, manifest, DESIGN).
 
 ## Open questions / decisions for Jim

docs/DESIGN.md

@@ -1,6 +1,6 @@
 # Autonomi Operator Skill — Design
 
-> Canonical design, realigned to ADR-0001…0009. This supersedes the original pre-decision scaffold (which framed the work as a single "loop" and assumed a gas-abstraction path — both removed). Loose thinking lives in the vault (`Projects/Autonomi Skill`); this is the formal design. Volatile specifics (flags, constants, addresses, URLs) are **source-bound** to upstream per ADR-0006, not hardcoded here.
+> Canonical design target, not an exact inventory of the currently shipped files. Read `planning/HANDOFF.md` and `README.md` for implementation state. This supersedes the original pre-decision scaffold and is aligned with the repository's Proposed ADRs; none is Accepted autonomously. Volatile specifics (flags, constants, addresses, URLs) carry explicit provenance per ADR-0006: normally an upstream source binding, or a visibly provisional team-confirmed record pending upstream authority.
 
 ## 1. Purpose and shape
 
@@ -60,7 +60,7 @@ Three buckets the skill keeps distinct: **what the network enforces** (facts the
 
 ## 10. Staying current (ADR-0006)
 
-Every claim is **source-bound** to upstream (repo / file / symbol / commit) via a source-binding manifest; volatile facts are isolated and single-sourced; content is tagged mechanically-derived (auto-regenerable) vs judgement-derived (flag-for-review); per fact, a deliberate bake-with-pin vs fetch-live choice. An in-skill **version self-check** fetches a manifest from an Autonomi-controlled URL and warns if stale, continues if offline. Upstream repos signal operator-facing changes back to the skill (the cross-repo freshness contract, ADR-0006). The automation pipeline (upstream-sweep) is deferred; the regeneration-ready structure is mandatory now.
+Every Autonomi-specific factual claim carries explicit provenance in the source-binding manifest: normally an upstream repo / file / symbol / commit, or a visibly provisional team-confirmed record pending upstream source (ADR-0006). Ordinary operating-system/shell behaviour must use appropriate platform evidence outside that manifest before support is claimed. Volatile facts are isolated and single-sourced; content is tagged mechanically-derived (auto-regenerable) vs judgement-derived (flag-for-review); per fact, a deliberate bake-with-pin vs approved, bounded fetch-live choice. New skill versions are delivered by the channel that installed them, or by deliberate reinstall for a manual copy (ADR-0013). The skill does not make a network request to check its own version. A separate, optional live check may fetch only signed, typed volatile values within granted network/egress remit, falling back to the bundle otherwise (ADR-0013). Upstream repos signal operator-facing changes back to the skill (the cross-repo freshness contract, ADR-0006). The automation pipeline (upstream-sweep) is deferred; the regeneration-ready structure is mandatory now.
 
 ## 11. Metadata, licensing, provenance (ADR-0008)
 
@@ -113,7 +113,7 @@ The skill stays honest about the boundary at every tier: *it can operate nodes a
 
 ### Disclosure & division of labour
 
-Default to doing the work; surface outcomes and genuinely-human choices; keep mechanics and jargon out of the way. Minimise *operational* burden, never *authority* — spend / risk / recovery / consent are always surfaced (ADR-0004/0009 risk-based escalation). Escalate by exception, not for routine ops, and never on crypto-literacy.
+Default to doing the work; surface outcomes and genuinely authority-gated choices; keep mechanics and jargon out of the way. Minimise *operational* burden, never *authority* — but "authority" means **granting or widening an envelope**, not acting within one. A spend / risk / recovery / consent envelope is explicitly granted by, or its widening escalated to, the **authorised principal/delegator**; it is never inferred. **Acting within a granted envelope** needs no per-action approval (ADR-0004/0009), and reporting adapts to the available channel. Human-only gates remain human: in particular, ADR acceptance and ADR-0013's material live-value approval cannot be delegated to the running agent. Escalate by exception, not for routine ops, and never on crypto-literacy; where the authorised decision-maker can't be reached, **halt/defer** rather than cross the gate.
 
 ### Language register
 
@@ -131,11 +131,11 @@ Plain, not patronising — assume intelligence, not specialist knowledge. Lead w
 
 ## 14. Open questions (carried; mostly David/maintainer)
 
-- GitHub home/org and clean install URL; published skill name; version-manifest hosting URL.
+- Release/promotion mechanics and clean install/update verification for each supported channel.
 - Agent wallet custody substrate (where keygen/storage/recovery/signing live: assumed-host / signposted / skill-provided wrapper / upstream `ant`) — open team decision (relates to ADR-0004).
 - Gas / acquisition easing (DEX guidance, a paymaster if one returns) — escalate to David (ADR-0005).
 - Upstream watch-set and "material change" policy (for the deferred automation).
-- Pin volatile constants or fetch-live (e.g. the close-group size — read as both 5 and 7; resolve before authoring).
+- Publish the authoritative Recommended Node Resource Document and define ADR-0013 mechanism 4's detailed protocol/spec before implementing any bounded live-values fetch.
 
 ## Design History
 

docs/FEATURES.md

@@ -7,7 +7,7 @@
 - [ ] Install and run one or more nodes, referencing upstream binaries, per platform
 - [ ] Verify and monitor node health and earnings
 - [ ] Receive rewards to a non-custodial public wallet address (the node holds no key) and check balance
-- [ ] Channel-independent version self-check (manifest on an Autonomi-controlled URL)
+- [ ] Versioned releases and documented updates through each supported installation channel
 
 ## Should Have (V1)