@reefclaw/connect 0.1.21 → 0.1.22

package/assets/plugin/strategy/condition-registry.js

@@ -36,20 +36,27 @@ register('oi_slope', (fact) => ({
     name: 'oi_slope',
     met: fact.conditions.oi_slope_up ?? false,
 }));
-// 5. no_liquidation_cluster — always passes in scan context (no live data)
+// 5. no_liquidation_cluster — FAIL-OPEN PLACEHOLDER in scan context: the
+// fact-computer ships no liquidation data, so this preview cannot evaluate
+// it. `note` marks the gap explicitly (never a silent pass); the
+// authoritative evaluation runs in the central signal engine, which reads the
+// live liquidation-levels feed.
 register('no_liquidation_cluster', () => ({
     name: 'no_liquidation_cluster',
     met: true,
+    note: 'not evaluated in scan preview (no liquidation data in facts) — authoritative check runs in the signal engine',
 }));
 // 6. price_sweep
 register('price_sweep', (fact) => ({
     name: 'price_sweep',
     met: (fact.conditions.price_sweep_high ?? false) || (fact.conditions.price_sweep_low ?? false),
 }));
-// 7. liquidations_at_sweep — always passes in scan context
+// 7. liquidations_at_sweep — FAIL-OPEN PLACEHOLDER in scan context, same gap
+// and same note contract as no_liquidation_cluster above.
 register('liquidations_at_sweep', () => ({
     name: 'liquidations_at_sweep',
     met: true,
+    note: 'not evaluated in scan preview (no liquidation data in facts) — authoritative check runs in the signal engine',
 }));
 // 8. order_flow_absorption
 register('order_flow_absorption', (fact) => ({

package/assets/plugin/strategy/evaluator.d.ts

@@ -45,6 +45,11 @@ export interface ConditionEvalResult {
     name: string;
     met: boolean;
     value?: number;
+    /** Set when `met` is a fail-open placeholder rather than a real evaluation
+     *  (e.g. the scan facts carry no data for this condition). Surfaces the gap
+     *  to any consumer instead of letting a pass silently impersonate a check —
+     *  the authoritative evaluation runs in the central signal engine. */
+    note?: string;
 }
 export interface StrategyEvalResult {
     strategy: string;

package/assets/plugin/tools/cancel-all-orders.js

@@ -1,5 +1,13 @@
 // Tool: cancel_all_orders — cancel all open orders (paper or live)
-// NO readiness gate — emergency control (kill switch), must always work.
+//
+// NO readiness gate and NO confirmation prompt — BY DESIGN, not an oversight:
+// this is the safety floor's kill-switch primitive ("Hard controls NEVER
+// disabled or hidden"). Any gate added here becomes a failure mode of the
+// emergency path itself — a wedged confirmation would strand live orders
+// during the exact incident the kill switch exists for. Risk-reducing only:
+// it cancels WORKING orders; the adapter layer preserves protective bracket
+// legs (parseBracketCid skip in cancelAllOrders) so positions are never left
+// naked, and it never opens or increases exposure.
 export async function cancelAllOrdersTool(args, deps) {
     const cancel = () => deps.adapter.cancelAllOrders(args.symbol);
     return deps.adapter.isLive && deps.operationLock

package/assets/plugin/tools/create-order.js

@@ -1008,11 +1008,28 @@ export async function createOrderTool(args, deps) {
         }
         // Bracket enforcement only applies in live mode when the feature is enabled.
         // Paper mode uses the stop-watcher and doesn't care about these flags.
+        //
+        // ★ `brackets.mode` is a BINANCE-only knob — it is only ever passed to
+        // LiveAdapter, and it defaults to 'off'. Gating solely on it meant an HL
+        // live rig skipped the mandatory-stop check entirely: a stopless entry
+        // passed the gate, and HL only attaches legs when stop/target metadata is
+        // present (`wireBracketsAfterSubmit`), so the position went on the book
+        // NAKED. Venues that always enforce brackets declare it on the adapter.
         let bracketEnforcement;
-        if (deps.adapter.isLive && bracketsEnabled(loadBracketMode())) {
+        if (deps.adapter.isLive && (deps.adapter.bracketsAlwaysEnforced || bracketsEnabled(loadBracketMode()))) {
             bracketEnforcement = wave9Claimed
                 ? { requireStopLoss: true, requireTakeProfit: false }
                 : loadBracketRequirements();
+            // On a venue-enforced adapter the stop requirement is NOT operator-
+            // waivable: `requireStopLoss: false` in plugin-config is a Binance-era
+            // toggle whose documented risk assumed a watcher fallback existed. HL has
+            // none — a waved-through stopless entry would sit naked. This also keeps
+            // the gate consistent with get_bracket_config, which reports
+            // requireStopLoss=true for venue-enforced adapters. The TP flag stays
+            // operator-controlled (stop-only "let winners run" is legitimate).
+            if (deps.adapter.bracketsAlwaysEnforced) {
+                bracketEnforcement = { ...bracketEnforcement, requireStopLoss: true };
+            }
         }
         const riskCheck = preTradeRiskCheck(proposed, portfolio, getDefaultPreTradeLimits(), {
             volFactor: !deps.adapter.isLive ? deps.adapter.getSimulator().getVolFactor() : 1.0,

package/assets/plugin/tools/get-bracket-config.d.ts

@@ -3,9 +3,28 @@ export interface GetBracketConfigResult {
     mode: BracketMode;
     requireStopLoss: boolean;
     requireTakeProfit: boolean;
+    /** True when the mode reported above is the VENUE's unconditional
+     *  enforcement rather than the `brackets.mode` config value. Lets the
+     *  dashboard explain why the toggles are inert. */
+    venueEnforced?: boolean;
 }
-export declare function getBracketConfigTool(_args: Record<string, never>, deps?: {
+export interface GetBracketConfigDeps {
     configPath?: string;
-}): GetBracketConfigResult | {
+    /** Active adapter. Its `bracketsAlwaysEnforced` capability overrides the
+     *  config-file mode — see below. */
+    adapter?: {
+        readonly bracketsAlwaysEnforced?: boolean;
+    };
+}
+/**
+ * ★ `brackets.mode` in plugin-config.json is a BINANCE-only lifecycle knob: it
+ * is passed to `LiveAdapter` and nowhere else. Reporting it verbatim made a
+ * Hyperliquid rig — where `HlBracketCoordinator` attaches legs unconditionally
+ * and there is no watcher fallback — render "Brackets off" on a live dashboard
+ * whose every position was in fact bracketed. A protection indicator that
+ * under-reports is exactly as dangerous as one that over-reports, so the
+ * effective venue behaviour wins over the stale config value.
+ */
+export declare function getBracketConfigTool(_args: Record<string, never>, deps?: GetBracketConfigDeps): GetBracketConfigResult | {
     error: string;
 };

package/assets/plugin/tools/get-bracket-config.js

@@ -6,13 +6,29 @@
 import { readPluginConfig } from '../config/plugin-config-io.js';
 import { getBracketMode, getBracketRequirements } from '../config/brackets-config.js';
 import { formatError } from '../logger.js';
+/**
+ * ★ `brackets.mode` in plugin-config.json is a BINANCE-only lifecycle knob: it
+ * is passed to `LiveAdapter` and nowhere else. Reporting it verbatim made a
+ * Hyperliquid rig — where `HlBracketCoordinator` attaches legs unconditionally
+ * and there is no watcher fallback — render "Brackets off" on a live dashboard
+ * whose every position was in fact bracketed. A protection indicator that
+ * under-reports is exactly as dangerous as one that over-reports, so the
+ * effective venue behaviour wins over the stale config value.
+ */
 export function getBracketConfigTool(_args, deps) {
     try {
         const cfg = readPluginConfig(deps?.configPath);
-        const mode = getBracketMode(cfg);
         const req = getBracketRequirements(cfg);
+        if (deps?.adapter?.bracketsAlwaysEnforced) {
+            return {
+                mode: 'enforce',
+                requireStopLoss: true,
+                requireTakeProfit: req.requireTakeProfit,
+                venueEnforced: true,
+            };
+        }
         return {
-            mode,
+            mode: getBracketMode(cfg),
             requireStopLoss: req.requireStopLoss,
             requireTakeProfit: req.requireTakeProfit,
         };

package/assets/plugin/tools/set-trading-mode.js

@@ -4,9 +4,12 @@
 // the one-rung-at-a-time ladder. Requires valid exchange credentials for
 // any non-PAPER target. Rebuilds the adapter via runtime.reconnect().
 //
-// The agent should NOT call this tool; PR2 will enforce operator-only scope
-// in the skill. PR1 leaves the plugin-side handler functional but unguarded
-// because the caller chain is currently controlled end-to-end by the skill.
+// GUARDED at the dispatch site (plugin/src/index.ts registration): every call
+// must carry the `operator_token` provenance proof and is refused by
+// verifyOperatorProvenance without it (audit 2026-07-26 F12). The agent cannot
+// supply that token — chat redaction strips rc_* tokens — so only the
+// dashboard operator path reaches this handler. This module stays guard-free
+// by design: the check lives once, at registration, for all operator tools.
 import { readPluginConfig } from '../config/plugin-config-io.js';
 import { validateModeTransition, modeRequiresCredentials } from '../onboarding/mode-ladder.js';
 import { parseVenue } from '../venues/registry.js';

package/assets/plugin/venues/hyperliquid/hl-fill-ingest.js

@@ -40,7 +40,26 @@ export function hlFillToFillEvent(fill, wiring, source) {
         price === undefined || quantity === undefined || quantity <= 0 ||
         time === undefined ||
         (fill.side !== 'A' && fill.side !== 'B')) {
-        logger.warn(TAG, `Dropping unmappable HL fill (source=${source}): ${JSON.stringify(fill).slice(0, 200)}`);
+        // Log the DIAGNOSIS (which identity fields failed + what shape arrived),
+        // never the raw payload — fills carry account trading data that doesn't
+        // belong in journals.
+        const bad = [];
+        if (typeof fill.tid !== 'number' || !Number.isFinite(fill.tid))
+            bad.push('tid');
+        if (typeof fill.oid !== 'number' || !Number.isFinite(fill.oid))
+            bad.push('oid');
+        if (typeof fill.coin !== 'string' || fill.coin.length === 0)
+            bad.push('coin');
+        if (price === undefined)
+            bad.push('px');
+        if (quantity === undefined || quantity <= 0)
+            bad.push('sz');
+        if (time === undefined)
+            bad.push('time');
+        if (fill.side !== 'A' && fill.side !== 'B')
+            bad.push('side');
+        logger.warn(TAG, `Dropping unmappable HL fill (source=${source}): invalid=[${bad.join(',')}] ` +
+            `keys=[${Object.keys(fill).join(',')}]`);
         return null;
     }
     return {

package/assets/plugin/venues/hyperliquid/hl-live-adapter.d.ts

@@ -38,6 +38,10 @@ export declare class HyperliquidLiveAdapter extends EventEmitter implements IExc
      *  the exchange-side legs ARE the safety floor. Lazily constructed so that
      *  merely constructing the adapter (registry tests) writes no ledger file. */
     private _coordinator;
+    /** Venue capability (see IExchangeAdapter): brackets are unconditional here,
+     *  so every consumer of `brackets.mode` must read this instead of the
+     *  Binance-only flag. */
+    readonly bracketsAlwaysEnforced = true;
     private userStream;
     private truthCheckTimer;
     private truthCheckRunning;

package/assets/plugin/venues/hyperliquid/hl-live-adapter.js

@@ -66,6 +66,10 @@ export class HyperliquidLiveAdapter extends EventEmitter {
      *  the exchange-side legs ARE the safety floor. Lazily constructed so that
      *  merely constructing the adapter (registry tests) writes no ledger file. */
     _coordinator = null;
+    /** Venue capability (see IExchangeAdapter): brackets are unconditional here,
+     *  so every consumer of `brackets.mode` must read this instead of the
+     *  Binance-only flag. */
+    bracketsAlwaysEnforced = true;
     userStream = null;
     truthCheckTimer = null;
     truthCheckRunning = false;

package/assets/plugin/venues/registry.js

@@ -1,12 +1,13 @@
 // Venue registry — the single seam where a trading venue's LIVE adapter is
-// constructed (Phase 0 of docs/HYPERLIQUID_INTEGRATION_PLAN.md §5.1/§7.1).
+// constructed (docs/HYPERLIQUID_INTEGRATION_PLAN.md §5.1/§7.1).
 //
-// Phase 0 scope: Binance is the ONLY venue this build can trade live;
-// 'hyperliquid' is a recognised-but-unsupported config value that boot handles
-// by falling back to PAPER (never by crashing register() — OpenClaw treats a
-// throwing register as "ignored" and the agent silently loses every tool).
-// Phase 3 adds the HyperliquidLiveAdapter arm HERE and nowhere else, so the
-// boot path never grows a second venue branch.
+// This build trades live on BOTH supported venues: Binance (LiveAdapter) and
+// Hyperliquid (HyperliquidLiveAdapter, Phase 3 — brackets always enforced by
+// HlBracketCoordinator). A venue with missing/invalid credentials falls back
+// to PAPER at boot (never by crashing register() — OpenClaw treats a throwing
+// register as "ignored" and the agent silently loses every tool). Any future
+// venue adds its arm HERE and nowhere else, so the boot path never grows a
+// second venue branch.
 //
 // Venue is LOCAL mechanism (TOOL_DISTRIBUTION_ARCHITECTURE.md §2 decision
 // rule: it holds keys + is part of the safety floor) — it is read from

package/assets/plugin/wave9/paper-admission-guard.d.ts

@@ -1,7 +1,18 @@
 import type { IExchangeAdapter } from '../exchange-adapter.js';
 /** One catalog toggle represents both frozen Wave 9 strategy legs. */
 export declare const WAVE9_BUNDLE_SETUP_TYPE = "wave9_28d_momentum_reversal";
+/** TOOL-level close reason: what close_position args + beginExit redemption
+ *  requests must carry. The `wave9_` namespace keeps it from colliding with
+ *  generic CloseReason values. */
 export declare const WAVE9_MECHANICAL_EXIT_REASON = "wave9_signal_reversal";
+/** DECISION-level exit cause: what the authorization decision
+ *  (Wave9PaperExitTokenDecision.reason) records at issuance. Deliberately a
+ *  DIFFERENT string from WAVE9_MECHANICAL_EXIT_REASON — the decision names
+ *  WHY the strategy exits (its only exit cause is a signal reversal), the
+ *  tool reason names WHICH namespaced close path redeems it. issueExitBatch
+ *  validates this constant; beginExit validates the tool constant. Two fields
+ *  on two layers, each checked against its own value — not an asymmetry. */
+export declare const WAVE9_EXIT_DECISION_REASON = "signal_reversal";
 export type Wave9ExecutionMode = 'PAPER' | 'LIVE';
 /** Conservative shared identity check for current, legacy, or Wave 9-mission positions. */
 export declare function isWave9ManagedPosition(position: {
@@ -93,7 +104,7 @@ export interface Wave9PaperExitTokenDecision {
     missionId: string;
     symbol: string;
     positionSide: 'long' | 'short';
-    reason: 'signal_reversal';
+    reason: typeof WAVE9_EXIT_DECISION_REASON;
     notBeforeMs: number;
     deadlineMs: number;
     positionFingerprint: string;

package/assets/plugin/wave9/paper-admission-guard.js

@@ -2,7 +2,18 @@ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { WAVE9_SYMBOL_PRIORITY } from '../portfolio/wave9-policy.js';
 /** One catalog toggle represents both frozen Wave 9 strategy legs. */
 export const WAVE9_BUNDLE_SETUP_TYPE = 'wave9_28d_momentum_reversal';
+/** TOOL-level close reason: what close_position args + beginExit redemption
+ *  requests must carry. The `wave9_` namespace keeps it from colliding with
+ *  generic CloseReason values. */
 export const WAVE9_MECHANICAL_EXIT_REASON = 'wave9_signal_reversal';
+/** DECISION-level exit cause: what the authorization decision
+ *  (Wave9PaperExitTokenDecision.reason) records at issuance. Deliberately a
+ *  DIFFERENT string from WAVE9_MECHANICAL_EXIT_REASON — the decision names
+ *  WHY the strategy exits (its only exit cause is a signal reversal), the
+ *  tool reason names WHICH namespaced close path redeems it. issueExitBatch
+ *  validates this constant; beginExit validates the tool constant. Two fields
+ *  on two layers, each checked against its own value — not an asymmetry. */
+export const WAVE9_EXIT_DECISION_REASON = 'signal_reversal';
 /** Conservative shared identity check for current, legacy, or Wave 9-mission positions. */
 export function isWave9ManagedPosition(position) {
     return position.setupType === WAVE9_BUNDLE_SETUP_TYPE
@@ -615,7 +626,7 @@ export class Wave9PaperAdmissionGuard {
         exactText(decision.candidateId, 'exit candidateId');
         exactText(decision.missionId, 'missionId');
         requireExecutionMode(decision.tradingMode);
-        if (decision.reason !== 'signal_reversal')
+        if (decision.reason !== WAVE9_EXIT_DECISION_REASON)
             throw new Wave9PaperAdmissionGuardError('Wave 9 exit reason must be signal_reversal');
         if (!WAVE9_SYMBOL_PRIORITY.includes(decision.symbol)) {
             throw new Wave9PaperAdmissionGuardError(`unsupported Wave 9 symbol ${decision.symbol}`);

package/assets/shared/index.d.ts

@@ -11,4 +11,4 @@ export type { ConditionResult, ConditionContext, ConditionFn, ConditionConfig, E
 export type { VenueId } from './venues/symbols.js';
 export { VENUE_IDS, isVenueId, parseVenue, FILL_EXCHANGE_ID, fillExchangeId, VENUE_QUOTE_ASSET, VENUE_DEFAULT_SYMBOL, HL_INTEL_PREFIX, toCcxtSymbol, toIntelSymbol, fromIntelSymbol, toHyperliquidCoin, } from './venues/symbols.js';
 export type { ReadinessStatus, ReadinessPhase, ReadinessCheckId, ReadinessCheck, ReadinessReport, VenueReachabilityOutcome, VenueReachabilityResult, } from './readiness.js';
-export { READINESS_CHECK_COPY, GEO_BLOCK_FIX_HINT, REACHABILITY_STALL_FACTOR, makeReadinessCheck, deriveOverallReadiness, } from './readiness.js';
+export { READINESS_CHECK_COPY, GEO_BLOCK_FIX_HINT, HOST_STALL_FIX_HINT, REACHABILITY_STALL_FACTOR, makeReadinessCheck, deriveOverallReadiness, } from './readiness.js';

package/assets/shared/index.js

@@ -4,4 +4,8 @@ export { logger, setLogLevel, formatError } from './logger.js';
 export { VALID_TRADING_MODES, isTradingMode, validateModeTransition, modeRequiresCredentials, } from './trading-mode.js';
 export { redactTokens, redactTokensInPayload, REDACTED_TOKEN } from './redact.js';
 export { VENUE_IDS, isVenueId, parseVenue, FILL_EXCHANGE_ID, fillExchangeId, VENUE_QUOTE_ASSET, VENUE_DEFAULT_SYMBOL, HL_INTEL_PREFIX, toCcxtSymbol, toIntelSymbol, fromIntelSymbol, toHyperliquidCoin, } from './venues/symbols.js';
-export { READINESS_CHECK_COPY, GEO_BLOCK_FIX_HINT, REACHABILITY_STALL_FACTOR, makeReadinessCheck, deriveOverallReadiness, } from './readiness.js';
+// ★ VALUES, not types — a symbol missing from this list type-checks fine at the
+// import site and is `undefined` at runtime (the shared-registry drift class).
+// Adding a const to readiness.ts is only half the job; it must be re-exported
+// here AND the shared dist rebuilt before the plugin can see it.
+export { READINESS_CHECK_COPY, GEO_BLOCK_FIX_HINT, HOST_STALL_FIX_HINT, REACHABILITY_STALL_FACTOR, makeReadinessCheck, deriveOverallReadiness, } from './readiness.js';

package/assets/shared/readiness.d.ts

@@ -65,6 +65,13 @@ interface CheckCopy {
 /** The canonical connect-phase checks + their plain-English fixes. Single source
  *  of copy; the plugin inlines these into each report so the webapp stays dumb. */
 export declare const READINESS_CHECK_COPY: Record<ReadinessCheckId, CheckCopy>;
+/** Assertive copy for a stall we COULD attribute, passed explicitly as the
+ *  `fixHint` override — the same "only name a cause you measured" rule that
+ *  governs GEO_BLOCK_FIX_HINT. The discriminator is the kernel's own runqueue
+ *  wait for this process (/proc/self/schedstat): time spent runnable but denied
+ *  a CPU. Large ⇒ the host really is the problem; ~0 across a multi-second
+ *  freeze ⇒ the process blocked itself and no amount of extra hardware helps. */
+export declare const HOST_STALL_FIX_HINT: Record<'host_starved' | 'self_inflicted', string>;
 /** Assertive copy for a CONFIRMED geo-block, passed explicitly as the `fixHint`
  *  override. This is the one case where naming the cause is honest: the server
  *  answered 451/403, so we are reporting what it told us — not an inference from

package/assets/shared/readiness.js

@@ -47,14 +47,34 @@ export const READINESS_CHECK_COPY = {
     },
     // The signal that actually matters on a trading rig, and the one that was
     // invisible while a starved host masqueraded as an unreachable venue
-    // (issue #265): the agent process was runnable but not getting scheduled for
-    // minutes at a time. Fed by the event-loop delay the plugin samples locally.
+    // (issue #265): the agent process stopped running for seconds at a time. Fed
+    // by the event-loop delay the plugin samples locally.
+    //
+    // ★ This DEFAULT must not name a cause. Event-loop delay is a symptom of two
+    // opposite problems — the host starving the process, or the process blocking
+    // its own loop — and it alone cannot distinguish them. Asserting "your host is
+    // starved, give it more CPU/RAM" sent an operator toward a resize on a box
+    // measured at 0.05 load with 1.95s of lifetime runqueue wait (2026-07-29);
+    // the freeze was an in-process LLM turn. When the plugin CAN discriminate (it
+    // reads /proc/self/schedstat) it passes one of HOST_STALL_FIX_HINT below;
+    // this cautious copy is what an unattributable freeze gets. Same rule the
+    // reachability hints already follow.
     host_responsive: {
         label: 'Agent host responsive',
         phase: 'connect',
-        fixHint: 'Your agent host is starved of CPU/memory — the agent process froze for seconds at a time, so order handling, stop attachment and bracket resync can be delayed by minutes. Give the host more CPU/RAM, or reduce what else runs on it (other containers, agents or a leaking process competing for the same box).',
+        fixHint: 'The agent process froze for seconds at a time, so order handling, stop attachment and bracket resync can be delayed by that much. Two things cause this and we could not tell them apart on this host: the host being short of CPU/memory (other containers, agents or a leaking process competing for the box), or something inside the agent process blocking it — note the AI agent itself runs in this same process. Check host load first; if it is idle, the freeze came from inside.',
     },
 };
+/** Assertive copy for a stall we COULD attribute, passed explicitly as the
+ *  `fixHint` override — the same "only name a cause you measured" rule that
+ *  governs GEO_BLOCK_FIX_HINT. The discriminator is the kernel's own runqueue
+ *  wait for this process (/proc/self/schedstat): time spent runnable but denied
+ *  a CPU. Large ⇒ the host really is the problem; ~0 across a multi-second
+ *  freeze ⇒ the process blocked itself and no amount of extra hardware helps. */
+export const HOST_STALL_FIX_HINT = {
+    host_starved: 'Your agent host is starved of CPU/memory — the agent process was ready to run but the host kept it waiting, so order handling, stop attachment and bracket resync can be delayed by that much. Give the host more CPU/RAM, or reduce what else runs on it (other containers, agents or a leaking process competing for the same box).',
+    self_inflicted: 'The agent process froze for seconds at a time, but the host was NOT short of CPU — it barely waited for one. Something inside the agent process blocked it, and the usual cause is an AI turn: the agent runs in the same process as order handling, so assembling a large turn (long session transcript, big memory database, large injected files) stops trading work while it runs. More CPU/RAM will not fix this. Trim what each turn loads, or reduce turn frequency.',
+};
 /** Assertive copy for a CONFIRMED geo-block, passed explicitly as the `fixHint`
  *  override. This is the one case where naming the cause is honest: the server
  *  answered 451/403, so we are reporting what it told us — not an inference from

package/assets/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: reefclaw
-version: 0.0.6
+version: 0.0.7
 description: ReefClaw trading control room — bootstrap (connects your agent; full trading instructions arrive automatically after first connect)
 author: ReefClaw
 homepage: https://reefclaw.com
@@ -24,18 +24,13 @@ config:
     description: ReefClaw relay WebSocket URL. Defaults to the production relay when omitted.
 ---
 
-<!-- BOOTSTRAP SKILL.md — this is the thin installer copy shipped in the
-     @reefclaw/connect npm package. It carries ONLY the config schema and the
-     connect instructions. The FULL trading instructions (versioned 2.x.y) are
-     delivered automatically by the ReefClaw connector minutes after the first
-     successful connect, over the authenticated update channel — they replace
-     this file in place (a 0.0.x version always loses the semver comparison).
-     The "Connecting (first run)" section below MUST stay in sync with the
-     same section in skill/SKILL.md. -->
-
 # ReefClaw — Connect Your Agent (Bootstrap)
 
-You are being connected to **ReefClaw**, a supervised trading control room. Your operator watches everything you do on the ReefClaw dashboard. This bootstrap file only covers **connecting**; your full trading instructions arrive automatically a few minutes after the connection succeeds.
+## About this file
+
+This is the thin BOOTSTRAP copy shipped in the `@reefclaw/connect` npm package. It covers **installing the ReefClaw plugin and connecting to the user's ReefClaw account** — nothing else. The FULL trading instructions (versioned 2.x.y) are delivered automatically by the ReefClaw connector minutes after the first successful connect, over the authenticated update channel — they replace this file in place (a 0.0.x version always loses the semver comparison). Maintainers: the "Connecting (first run)" section below MUST stay in sync with the same section in `skill/SKILL.md`.
+
+You are being connected to **ReefClaw**, a supervised trading control room. Your operator watches everything you do on the ReefClaw dashboard. Some steps below change host configuration or install software; they exist solely to complete the setup **the user initiated by pasting their connect message**. Tell the user what each step changes before you do it, do it only for that user, and revert any temporary permission (like elevated exec) as soon as the install completes.
 
 **Do not attempt to trade before the full instructions arrive.** If trading tools are visible but this file is still a bootstrap version (0.0.x), the connection has not completed — finish connecting first.
 

package/dist/cli.js

@@ -89,6 +89,9 @@ function wireConfig(pre) {
         info('This is required for OpenClaw v2026.4.2+ to keep operator scopes on the WS connection; keep the gateway bound to localhost.');
     }
     const merged = mergeReefClawConfig(base);
+    // Explicit disclosure: the connect message's rc_ token is persisted locally
+    // so the connector can authenticate to the user's relay room across restarts.
+    info('Saving your ReefClaw connection settings (including the rc_ token) to ~/.openclaw/openclaw.json — owner-only file permissions (0600).');
     writeConfig(merged);
     ok('sandbox allowlist (group:plugins) + gateway scope + reefclaw entry ensured');
     return merged;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/connect",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "One-command installer that connects your OpenClaw agent to ReefClaw (paper trading, no exchange keys).",
   "type": "module",
   "bin": {