@liquiditytech/rapidx-cli 1.0.28 → 1.0.30

package/dist/core/trading/preview.js

@@ -4,6 +4,7 @@ import { dirname, join, resolve } from "node:path";
 import { assertInputMatchesSchema } from "../contracts/input-schema.js";
 import { evaluateSafety, stableParamsHash } from "../safety/policy.js";
 import { ProductError } from "../errors/product-error.js";
+import { parseRapidXSymbol } from "../client/symbol.js";
 export function makePreviewStore() {
     return { records: new Map() };
 }
@@ -38,10 +39,11 @@ export function savePreviewStoreToFile(filePath, store) {
 }
 export function createTradePreview(capability, input, policy, state, store, ttlSeconds = 300) {
     assertInputMatchesSchema(capability.inputSchema, input, {
-        allowedExtraFields: ["explicitUserConsent", "acceptedRiskText"]
+        allowedExtraFields: ["explicitUserConsent", "acceptedRiskText", "automationMode", "automationConsentText", "automationScope"]
     });
     const tradeParams = normalizeTradeParams(input);
-    const previewDetails = makePreviewDetails(capability, tradeParams);
+    const automation = makeAutomationDetails(input, tradeParams);
+    const previewDetails = makePreviewDetails(capability, tradeParams, automation);
     const decision = evaluateSafety(capability, input, policy, state);
     if (!decision.allowed) {
         throw new ProductError({
@@ -59,7 +61,8 @@ export function createTradePreview(capability, input, policy, state, store, ttlS
         expiresAt: new Date(Date.now() + ttlSeconds * 1000).toISOString(),
         submitted: false,
         status: "PASS",
-        confirmation: makeSubmitConfirmation(previewId)
+        confirmation: makeSubmitConfirmation(previewId, automation),
+        ...(automation ? { automation } : {})
     };
     store.records.set(previewId, record);
     return record;
@@ -73,7 +76,10 @@ export function createTargetedTradePreview(targetCapability, input, policy, stat
             "acceptedRiskText",
             "mcpSchemaVersion",
             "skillsVersion",
-            "skillsSchemaVersion"
+            "skillsSchemaVersion",
+            "automationMode",
+            "automationConsentText",
+            "automationScope"
         ],
         ignoredRequiredFields: ["previewId", "continueConsentId"]
     });
@@ -92,7 +98,8 @@ export function createTargetedTradePreview(targetCapability, input, policy, stat
         });
     }
     const tradeParams = normalizeTradeParams(input);
-    const previewDetails = makePreviewDetails(targetCapability, tradeParams);
+    const automation = makeAutomationDetails(input, tradeParams);
+    const previewDetails = makePreviewDetails(targetCapability, tradeParams, automation);
     const decision = evaluateSafety(targetCapability, input, policy, state);
     if (!decision.allowed) {
         throw new ProductError({
@@ -110,16 +117,19 @@ export function createTargetedTradePreview(targetCapability, input, policy, stat
         expiresAt: new Date(Date.now() + ttlSeconds * 1000).toISOString(),
         submitted: false,
         status: "PASS",
-        confirmation: makeSubmitConfirmation(previewId)
+        confirmation: makeSubmitConfirmation(previewId, automation),
+        ...(automation ? { automation } : {})
     };
     store.records.set(previewId, record);
     return record;
 }
-function makeSubmitConfirmation(previewId) {
+function makeSubmitConfirmation(previewId, automation) {
     return {
         submitToken: `confirm_${previewId}`,
         requiredFields: ["previewId", "continueConsentId"],
-        instruction: "Pass submitToken as continueConsentId only after the user has confirmed this exact preview."
+        instruction: automation
+            ? "Automation mode is enabled for this preview. The agent may pass submitToken as continueConsentId without asking for another per-order chat confirmation, within the authorized scope."
+            : "Pass submitToken as continueConsentId only after the user has confirmed this exact preview."
     };
 }
 export function verifyPreview(store, previewId, capability, input, now = new Date()) {
@@ -135,7 +145,7 @@ export function verifyPreview(store, previewId, capability, input, now = new Dat
         throw new ProductError({
             code: "RCORE20002",
             status: "BLOCKED",
-            message: "previewId was not found."
+            message: "previewId was not found or has expired. Re-run preview and submit within 5 minutes."
         });
     }
     if (new Date(record.expiresAt).getTime() < now.getTime()) {
@@ -172,16 +182,24 @@ function normalizeTradeParams(input) {
     const normalized = {};
     for (const [key, value] of Object.entries(input)) {
         if (!NON_TRADE_HASH_FIELDS.has(key) && value !== undefined) {
-            normalized[key] = value;
+            normalized[key] = key === "symbol" && typeof value === "string" ? canonicalSymbolOrOriginal(value) : value;
         }
     }
     return normalized;
 }
-function makePreviewDetails(capability, tradeParams) {
+function canonicalSymbolOrOriginal(value) {
+    try {
+        return parseRapidXSymbol(value).canonicalSymbol;
+    }
+    catch {
+        return value;
+    }
+}
+function makePreviewDetails(capability, tradeParams, automation) {
     return {
         businessParams: { ...tradeParams },
         requestSummary: makeRequestSummary(capability.capabilityId, tradeParams),
-        riskNotes: makeRiskNotes(capability.capabilityId, tradeParams)
+        riskNotes: makeRiskNotes(capability.capabilityId, tradeParams, automation)
     };
 }
 function makeRequestSummary(capabilityId, params) {
@@ -190,6 +208,7 @@ function makeRequestSummary(capabilityId, params) {
             action: "place_order",
             symbol: params.symbol,
             side: params.side,
+            positionSide: params.positionSide,
             orderType: params.orderType,
             price: params.price,
             quantity: params.quantity,
@@ -240,11 +259,18 @@ function makeRequestSummary(capabilityId, params) {
     }
     return compactRecord({ action: capabilityId, ...params });
 }
-function makeRiskNotes(capabilityId, params) {
+function makeRiskNotes(capabilityId, params, automation) {
     const notes = [];
+    if (automation) {
+        notes.push("Automation mode allows the agent to submit this preview with submitToken without asking for another per-order chat confirmation.");
+    }
     if (params.maxNotional !== undefined) {
         notes.push("maxNotional is a safety upper bound, not the target order size.");
     }
+    if (String(params.orderType ?? "").toUpperCase() === "MARKET") {
+        notes.push("MARKET orders may execute immediately.");
+        notes.push("MARKET order fill price is not guaranteed and may include slippage.");
+    }
     if (capabilityId === "position.close") {
         notes.push("Do not pass side or quantity for position.close; RapidX determines BUY or SELL from the current position and closes the target symbol/positionSide.");
         notes.push("position.close uses the RapidX close-position API and may execute as a market close with slippage.");
@@ -252,6 +278,51 @@ function makeRiskNotes(capabilityId, params) {
     }
     return notes;
 }
+function makeAutomationDetails(input, tradeParams) {
+    if (input.automationMode !== true) {
+        return undefined;
+    }
+    const acceptedRiskText = typeof input.automationConsentText === "string" ? input.automationConsentText.trim() : "";
+    const missing = automationConsentMissingFields(acceptedRiskText, tradeParams, input);
+    if (missing.length > 0) {
+        throw new ProductError({
+            code: "RCORE20003",
+            status: "BLOCKED",
+            message: `automationConsentText must include ${missing.join(", ")} for this exact automation scope.`
+        });
+    }
+    return {
+        enabled: true,
+        confirmationMode: "automation-preview",
+        scope: typeof input.automationScope === "string" && input.automationScope.trim().length > 0 ? input.automationScope.trim() : "single-preview",
+        ...(tradeParams.maxNotional !== undefined ? { maxNotional: String(tradeParams.maxNotional) } : {}),
+        acceptedRiskText
+    };
+}
+function automationConsentMissingFields(text, tradeParams, input) {
+    const missing = [];
+    const upperText = text.toUpperCase();
+    const lowerText = text.toLowerCase();
+    if (text.length < 20) {
+        missing.push("automationConsentText");
+    }
+    const symbol = typeof tradeParams.symbol === "string" ? tradeParams.symbol : undefined;
+    if (symbol && !upperText.includes(symbol.toUpperCase())) {
+        missing.push("symbol");
+    }
+    const maxNotional = tradeParams.maxNotional;
+    if (maxNotional !== undefined && !text.includes(String(maxNotional))) {
+        missing.push("maxNotional");
+    }
+    if (!lowerText.includes("automation") && !lowerText.includes("automated") && !text.includes("自动")) {
+        missing.push("automation intent");
+    }
+    const scope = typeof input.automationScope === "string" ? input.automationScope.trim() : "";
+    if (scope && scope !== "single-preview" && !lowerText.includes(scope.toLowerCase())) {
+        missing.push("automationScope");
+    }
+    return missing;
+}
 function estimateNotional(params) {
     if (params.amount !== undefined && params.amount !== null && params.amount !== "") {
         return String(params.amount);
@@ -314,7 +385,10 @@ const NON_TRADE_HASH_FIELDS = new Set([
     "acceptedRiskText",
     "mcpSchemaVersion",
     "skillsVersion",
-    "skillsSchemaVersion"
+    "skillsSchemaVersion",
+    "automationMode",
+    "automationConsentText",
+    "automationScope"
 ]);
 function isTradePreviewRecord(value) {
     if (!value || typeof value !== "object") {

package/dist/core/trading/trading-verification.js

@@ -13,7 +13,7 @@ export async function runTradingVerification(rawInput, probes = {}) {
     }
     catch (error) {
         if (error instanceof ProductError) {
-            return { submittedRealOrder: false, status: "FAIL", cleanupStatus: "NOT_VERIFIED", steps, errorCode: error.code, errorMessage: error.message, errorStage: "input-validation" };
+            return { submittedRealOrder: false, status: error.status, cleanupStatus: "NOT_VERIFIED", steps, errorCode: error.code, errorMessage: error.message, errorStage: "input-validation" };
         }
         throw error;
     }
@@ -39,7 +39,7 @@ export async function runTradingVerification(rawInput, probes = {}) {
             errorCode: "RCORE20001",
             errorMessage: consentProblem,
             errorStage: "user-consent",
-            recommendedAction: "Ask the human user to confirm the exact symbol, side, maxNotional, real-order risk, and cancel cleanup behavior before running verify-live."
+            recommendedAction: "Ask the human user to confirm the exact symbol, side, positionSide when provided, maxNotional, real-order risk, and cancel cleanup behavior before running verify-live."
         };
     }
     if (!probes.marketRules) {
@@ -48,8 +48,18 @@ export async function runTradingVerification(rawInput, probes = {}) {
     }
     const marketRules = await probes.marketRules(input);
     if (Number(marketRules.minNotional) > Number(input.maxNotional)) {
-        steps.push({ name: "market", status: "BLOCKED", toolOrCommandEvidence: `minNotional=${marketRules.minNotional};maxNotional=${input.maxNotional}` });
-        return { submittedRealOrder: false, status: "BLOCKED", cleanupStatus: "NOT_VERIFIED", steps, errorCode: "RCORE24001", errorStage: "market" };
+        const evidence = `minNotional=${marketRules.minNotional};maxNotional=${input.maxNotional}`;
+        steps.push({ name: "market", status: "BLOCKED", toolOrCommandEvidence: evidence });
+        return {
+            submittedRealOrder: false,
+            status: "BLOCKED",
+            cleanupStatus: "NOT_VERIFIED",
+            steps,
+            errorCode: "RCORE24001",
+            errorMessage: `Verification order blocked because ${evidence}.`,
+            errorStage: "market",
+            recommendedAction: `Increase maxNotional to at least ${marketRules.minNotional}, or choose a symbol whose minNotional is within the authorized maxNotional.`
+        };
     }
     steps.push({ name: "market", status: "PASS", toolOrCommandEvidence: `minNotional=${marketRules.minNotional};tickSize=${marketRules.tickSize}` });
     const capability = findCapabilityById("order.preview");
@@ -73,7 +83,7 @@ export async function runTradingVerification(rawInput, probes = {}) {
         return { submittedRealOrder: false, status: "NOT_VERIFIED", cleanupStatus: "NOT_VERIFIED", steps, previewId: preview.previewId, errorCode: "RCORE23001", errorStage: "place" };
     }
     const placed = await probes.placeOrder({ ...input, previewId: preview.previewId, orderType: "LIMIT", postOnly: true, price, quantity });
-    steps.push({ name: "place", status: "PASS", toolOrCommandEvidence: placed.requestId ?? placed.orderId });
+    steps.push({ name: "place", status: "PASS", toolOrCommandEvidence: [placed.requestId ?? placed.orderId, input.positionSide ? `positionSide=${input.positionSide}` : undefined].filter(Boolean).join(";") });
     if (!probes.queryOrder) {
         steps.push({ name: "query", status: "NOT_VERIFIED", toolOrCommandEvidence: "queryOrder probe missing" });
         return { submittedRealOrder: true, status: "NOT_VERIFIED", cleanupStatus: "NOT_VERIFIED", steps, previewId: preview.previewId, errorCode: "RCORE23001", errorStage: "query" };
@@ -93,7 +103,11 @@ export async function runTradingVerification(rawInput, probes = {}) {
         }
     }
     else {
-        steps.push({ name: "amend", status: "EXPECTED_ERROR", toolOrCommandEvidence: "amendOrder probe not supported" });
+        steps.push({
+            name: "amend",
+            status: "EXPECTED_ERROR",
+            toolOrCommandEvidence: "optional verify-live amend check skipped; order.amend remains available outside verify-live"
+        });
     }
     if (!probes.cancelOrder) {
         steps.push({ name: "cancel", status: "FAIL", toolOrCommandEvidence: "cancelOrder probe missing" });
@@ -110,12 +124,12 @@ export async function runTradingVerification(rawInput, probes = {}) {
         steps.push({ name: "cleanup-check", status: "NOT_VERIFIED", toolOrCommandEvidence: "cleanupCheck probe missing" });
         return { submittedRealOrder: true, status: "NOT_VERIFIED", cleanupStatus: "NOT_VERIFIED", steps, previewId: preview.previewId, errorCode: "RCORE24002", errorStage: "cleanup-check", recommendedAction: "Query order/list and position/list before retrying verify-live." };
     }
-    const cleanup = await probes.cleanupCheck(currentOrder);
-    if (cleanup.openOrders !== 0 || cleanup.unexpectedPositions !== 0) {
-        steps.push({ name: "cleanup-check", status: "FAIL", toolOrCommandEvidence: `openOrders=${cleanup.openOrders};unexpectedPositions=${cleanup.unexpectedPositions}` });
-        return cleanupFailureReport(steps, preview.previewId, "cleanup-check", currentOrder.status, `cleanup still shows openOrders=${cleanup.openOrders}; unexpectedPositions=${cleanup.unexpectedPositions}`);
+    const cleanupConfirmation = await confirmCleanup(currentOrder, probes);
+    if (!cleanupConfirmation.confirmed) {
+        steps.push({ name: "cleanup-check", status: "FAIL", toolOrCommandEvidence: cleanupConfirmation.evidence });
+        return cleanupFailureReport(steps, preview.previewId, "cleanup-check", currentOrder.status, `cleanup still shows ${cleanupEvidence(cleanupConfirmation.cleanup)}`);
     }
-    steps.push({ name: "cleanup-check", status: "PASS", toolOrCommandEvidence: "openOrders=0;unexpectedPositions=0" });
+    steps.push({ name: "cleanup-check", status: "PASS", toolOrCommandEvidence: cleanupConfirmation.evidence });
     return {
         submittedRealOrder: true,
         status: "PASS",
@@ -136,6 +150,9 @@ function normalizeTradingVerificationInput(input) {
     if (typeof input.acceptedRiskText === "string") {
         normalized.acceptedRiskText = input.acceptedRiskText;
     }
+    if (input.positionSide === "LONG" || input.positionSide === "SHORT") {
+        normalized.positionSide = input.positionSide;
+    }
     return normalized;
 }
 function validateParameterBoundConsent(input) {
@@ -155,6 +172,9 @@ function validateParameterBoundConsent(input) {
     if (!upperText.includes(input.side)) {
         missing.push("side");
     }
+    if (input.positionSide && !upperText.includes(input.positionSide)) {
+        missing.push("positionSide");
+    }
     if (!text.includes(input.maxNotional)) {
         missing.push("maxNotional");
     }
@@ -194,6 +214,31 @@ async function confirmCancel(order, probes) {
 function isSafeCancelTerminalState(status) {
     return status === "CANCELED" || status === "EXPIRED" || status === "REJECTED";
 }
+async function confirmCleanup(order, probes) {
+    const observations = [];
+    let current = await probes.cleanupCheck(order);
+    observations.push(cleanupEvidence(current));
+    if (isCleanupClean(current)) {
+        return { confirmed: true, cleanup: current, evidence: observations.join("->") };
+    }
+    const delays = probes.cleanupCheckDelaysMs ?? probes.cancelConfirmationDelaysMs ?? [100, 250, 500, 1_000, 2_000];
+    const wait = probes.wait ?? defaultWait;
+    for (const delay of delays) {
+        await wait(delay);
+        current = await probes.cleanupCheck(order);
+        observations.push(cleanupEvidence(current));
+        if (isCleanupClean(current)) {
+            return { confirmed: true, cleanup: current, evidence: observations.join("->") };
+        }
+    }
+    return { confirmed: false, cleanup: current, evidence: observations.join("->") };
+}
+function isCleanupClean(cleanup) {
+    return cleanup.openOrders === 0 && cleanup.unexpectedPositions === 0;
+}
+function cleanupEvidence(cleanup) {
+    return `openOrders=${cleanup.openOrders};unexpectedPositions=${cleanup.unexpectedPositions}`;
+}
 function defaultWait(milliseconds) {
     return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }

package/dist/core/version.js

@@ -1 +1 @@
-export const RAPIDX_VERSION = "1.0.28";
+export const RAPIDX_VERSION = "1.0.30";

package/dist/mcp/tool-runner.js

@@ -1,4 +1,4 @@
-import { consumePreview, createTargetedTradePreview, createTradePreview, defaultSafetyPolicy, executeRapidXCapability, findCapabilityById, getSchemaResult, makeEvidence, makePreviewStore, makeSafetyState, normalizeUnknownError, runSelfCheck, runTradingVerification, verifyPreview, buildLiveReadOnlySelfCheck, buildLiveTradingVerificationProbes, checkForUpdate, } from "../core/index.js";
+import { consumePreview, createTargetedTradePreview, createTradePreview, defaultSafetyPolicy, executeRapidXCapability, findCapabilityById, getSchemaResult, makeEvidence, makePreviewStore, makeSafetyState, normalizeUnknownError, publicErrorDetails, runSelfCheck, runPreviewPreflight, runTradingVerification, verifyPreview, buildLiveReadOnlySelfCheck, buildLiveTradingVerificationProbes, checkForUpdate, } from "../core/index.js";
 import { capabilityForTool, getMcpToolDefinitions } from "./tool-registry.js";
 import { writeMcpAudit } from "./audit.js";
 const previewStore = makePreviewStore();
@@ -6,8 +6,10 @@ const safetyState = makeSafetyState();
 export async function runMcpTool(toolName, input = {}) {
     try {
         if (toolName === "rapidx/tools") {
+            const schema = getSchemaResult();
             const data = {
-                schemaVersion: getSchemaResult().schemaVersion,
+                schemaVersion: schema.schemaVersion,
+                inputSchemas: schema.inputSchemas,
                 tools: getMcpToolDefinitions().map((tool) => ({
                     name: tool.name,
                     riskLevel: tool.capability.riskLevel,
@@ -55,6 +57,13 @@ export async function runMcpTool(toolName, input = {}) {
                 throw new Error("order.preview capability missing");
             }
             const preview = createTradePreview(previewCapability, input, { ...defaultSafetyPolicy(), tradingEnabled: true, readOnly: false }, safetyState, previewStore);
+            try {
+                Object.assign(preview, await runPreviewPreflight("order.place", input));
+            }
+            catch (error) {
+                previewStore.records.delete(preview.previewId);
+                throw error;
+            }
             const auditId = writeMcpAudit("trade-preview", "PASS", { toolName, capabilityId: capability.capabilityId, previewId: preview.previewId });
             return { ok: true, status: "PASS", data: preview, auditId, evidence: [makeEvidence(toolName)] };
         }
@@ -65,6 +74,13 @@ export async function runMcpTool(toolName, input = {}) {
                 throw new Error(`${concretePreviewTarget} capability missing`);
             }
             const preview = createTargetedTradePreview(targetCapability, input, { ...defaultSafetyPolicy(), tradingEnabled: true, readOnly: false }, safetyState, previewStore);
+            try {
+                Object.assign(preview, await runPreviewPreflight(concretePreviewTarget, input));
+            }
+            catch (error) {
+                previewStore.records.delete(preview.previewId);
+                throw error;
+            }
             const auditId = writeMcpAudit("trade-preview", "PASS", { toolName, capabilityId: targetCapability.capabilityId, previewId: preview.previewId });
             return { ok: true, status: "PASS", data: preview, auditId, evidence: [makeEvidence(toolName)] };
         }
@@ -78,6 +94,13 @@ export async function runMcpTool(toolName, input = {}) {
                 throw new Error("trade preview target must be a non-preview trade write capability.");
             }
             const preview = createTargetedTradePreview(targetCapability, input, { ...defaultSafetyPolicy(), tradingEnabled: true, readOnly: false }, safetyState, previewStore);
+            try {
+                Object.assign(preview, await runPreviewPreflight(targetCapability.capabilityId, input));
+            }
+            catch (error) {
+                previewStore.records.delete(preview.previewId);
+                throw error;
+            }
             const auditId = writeMcpAudit("trade-preview", "PASS", { toolName, capabilityId: targetCapability.capabilityId, previewId: preview.previewId });
             return { ok: true, status: "PASS", data: preview, auditId, evidence: [makeEvidence(toolName)] };
         }
@@ -101,11 +124,13 @@ export async function runMcpTool(toolName, input = {}) {
     }
     catch (error) {
         const productError = normalizeUnknownError(error, "RMCP12003");
+        const details = publicErrorDetails(productError);
         return {
             ok: false,
             status: productError.status,
             code: productError.code.replace(/^RCORE/, "RMCP"),
             message: productError.message,
+            ...(details ? { details } : {}),
             evidence: [makeEvidence(toolName)]
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liquiditytech/rapidx-cli",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "description": "RapidX CLI, MCP server mode, registry, and release assets.",
   "type": "module",
   "private": false,

package/packages/distribution/docs/cli.md

@@ -21,7 +21,9 @@ Supported conventions:
 - Use `rapidx order cancel-preview` for `order.cancel`.
 - Use `rapidx trade preview` with `targetCapabilityId` for non-order trade writes, including position, account, and algo writes.
 - `rapidx trade preview` input is flat JSON; do not wrap target parameters under `params`.
+- CLI preview ids are stored in the local CLI preview store. Do not submit MCP-created preview ids through CLI.
 - Treat `maxNotional` as a safety upper bound, not as the target order amount. Check symbol `minNotional` before increasing a requested amount.
+- Use `positionSide="LONG"` or `positionSide="SHORT"` for hedge-mode order placement or verification. Do not switch account position mode just to place a hedge-side order.
 
 Examples:
 
@@ -42,8 +44,16 @@ rapidx account set-position-mode --input @/absolute/path/set-position-mode.json
 
 `rapidx update check --json` reads the RapidX release manifest and caches the result locally. Use it during setup, review, or session startup. Trade submit paths should not perform a fresh network update check.
 
+`rapidx schema --json` returns `capabilities` plus `inputSchemas`. Agents should read the concrete input schema before constructing write inputs.
+
 `rapidx account balance` defaults to `mode=portfolio` and reads `/api/v1/trading/portfolio/assets`. `mode=account` reads `/api/v1/account/balance` and requires credentials with account-level permission.
 
-`rapidx account set-position-mode` is a trade write. It requires a matching preview token and a `continueConsentId` before execution.
+`rapidx account set-position-mode` is a trade write. Use it only when the user explicitly asks to change account position mode. It requires a matching preview token and a `continueConsentId` before execution.
+
+`rapidx order cancel` is asynchronous. A successful response can mean cancel accepted but not terminal. Poll `rapidx order get --json` when `terminalStateConfirmed=false`.
+
+When using `orderId`, pass the RapidX 16-digit numeric order id. Invalid `orderId` format is rejected locally as `INVALID_INPUT`. `clientOrderId` can be used instead and does not need to satisfy the `orderId` format. Preview commands for amend/cancel perform a RapidX readback after local format validation; valid-but-missing orders return `NOT_FOUND` or a blocked non-open state.
+
+Automation mode still uses preview. Pass `automationMode=true` and the user's exact `automationConsentText` to preview only when the user has enabled automation in chat for the current scope.
 
 `rapidx position close` is a close-position action. Do not pass `side` or `quantity`; RapidX determines BUY or SELL from the current position and closes the target symbol/positionSide. Use a reduce-only order flow for partial closes. Verify the final exposure with `rapidx position list --json`, and do not rely only on `order get` to interpret the close intent.

package/packages/distribution/docs/mcp.md

@@ -24,13 +24,18 @@ Public tool names use the `rapidx/` prefix.
 
 Key trading tools:
 
+- `rapidx/tools` returns the MCP tool list plus `inputSchemas`. Agents should read the concrete input schema before constructing write inputs.
 - `rapidx/update/check` reads the RapidX release manifest and returns current/latest CLI version, minimum write version, skills update advice, and upgrade commands.
 - `rapidx/self-check` can include update state when called with `{"checkUpdates": true}`.
 - `rapidx/order/preview` creates preview tokens for `order.place`.
 - `rapidx/order/place-preview`, `rapidx/order/amend-preview`, and `rapidx/order/cancel-preview` are concrete order preview aliases. Preview responses include `confirmation.submitToken`; pass it as `continueConsentId` when submitting the matching write tool.
 - `rapidx/trade/preview` creates preview tokens for non-place trade writes by `targetCapabilityId`, including position, account, and algo writes.
+- Preview ids are local to the running MCP server. Do not submit a CLI-created preview id through MCP, and do not submit an MCP-created preview id through CLI.
+- `rapidx/order/cancel` returns cancel acceptance plus terminal-state guidance. Poll `rapidx/order/get` when `terminalStateConfirmed=false`.
+- Automation mode still uses preview. Set `automationMode=true` and pass the user's exact `automationConsentText` only when the user has enabled automation in chat for the current scope.
 - `rapidx/position/history` reads historical positions.
-- `rapidx/account/set-position-mode` changes account position mode and requires preview plus explicit continuation consent.
-- `rapidx/trade/verify-live` runs the optional small real-trade verification flow with `explicitUserConsent` and parameter-bound `acceptedRiskText`; it creates its own internal preview and does not accept an external `previewId`. `rapidx/trading-verification` remains supported as a compatibility alias.
+- Hedge-mode order placement and verification use `positionSide="LONG"` or `positionSide="SHORT"` in the order or verify-live input. Do not use account mode switching as a substitute for order-level `positionSide`.
+- `rapidx/account/set-position-mode` changes account position mode and requires preview plus explicit continuation consent. Use it only when the user explicitly asks to change account position mode.
+- `rapidx/trade/verify-live` runs the optional small real-trade verification flow with `explicitUserConsent` and parameter-bound `acceptedRiskText`; it creates its own internal preview and does not accept an external `previewId`. If `positionSide` is provided, `acceptedRiskText` must include that position side. `rapidx/trading-verification` remains supported as a compatibility alias.
 
 Agents must discover the full tool list through `rapidx/tools` and must not invent tool names.

package/packages/distribution/docs/quickstart.md

@@ -113,6 +113,8 @@ rapidx schema --json
 
 For trade writes, create a preview before submit. Use `rapidx order place-preview` for `order.place`, `rapidx order amend-preview` for `order.amend`, and `rapidx order cancel-preview` for `order.cancel`. Use flat JSON with `rapidx trade preview` and `targetCapabilityId` for non-order writes such as `position.set-leverage`, `position.close`, or `account.set-position-mode`.
 
+`rapidx schema --json` and `rapidx/tools` return concrete `inputSchemas`. For hedge-mode orders, use `positionSide="LONG"` or `positionSide="SHORT"` in the order or verify-live input. Use `account.set-position-mode` only when the user explicitly asks to change account mode.
+
 For clearer order flows, prefer the explicit aliases:
 
 ```bash
@@ -124,6 +126,12 @@ rapidx trade preview --input '{"targetCapabilityId":"position.set-leverage","sym
 
 When submitting the actual write, pass the returned `previewId` and use `confirmation.submitToken` as `continueConsentId`.
 
+Preview ids are runtime-local. Submit MCP previews through the same MCP server runtime, and submit CLI previews through the same CLI preview store.
+
+`order.cancel` is asynchronous. If the cancel result says `terminalStateConfirmed=false`, poll `order get` until a terminal state before claiming that the order is cancelled.
+
+For automation, keep the preview-first flow. Use `automationMode=true` and the user's exact `automationConsentText` only after the user has enabled RapidX automation mode in chat for the current scope.
+
 `maxNotional` is a safety upper bound, not the target order amount. If a requested amount is below the symbol `minNotional`, ask the user to confirm the larger amount before submitting. For `position.close`, do not pass `side` or `quantity`; RapidX determines the close side from the current position and closes the target symbol/positionSide. Use a reduce-only order flow for partial closes, then check final exposure with `position list`.
 
-Use `rapidx trade verify-live --json` only when the user explicitly authorizes a small real-trade verification. Include `acceptedRiskText` that names the exact symbol, side, maxNotional, real-order risk, and cancel cleanup behavior. The older `rapidx self-check trade-verify --json` command remains supported for compatibility.
+Use `rapidx trade verify-live --json` only when the user explicitly authorizes a small real-trade verification. Include `acceptedRiskText` that names the exact symbol, side, positionSide when provided, maxNotional, real-order risk, and cancel cleanup behavior. The older `rapidx self-check trade-verify --json` command remains supported for compatibility.

package/packages/distribution/docs/tools.md

@@ -4,7 +4,7 @@ The canonical source is `rapidx schema --json` or `rapidx/tools`.
 
 ## Discovery And Update
 
-- `rapidx/tools`: returns the MCP tool surface and schema metadata.
+- `rapidx/tools`: returns the MCP tool surface and concrete `inputSchemas`.
 - `rapidx/self-check`: verifies discovery, schema, credentials, and optional read-only probes. Pass `checkUpdates=true` to include release manifest status.
 - `rapidx/update/check`: reads the RapidX release manifest, returns version status, minimum write version, skills update advice, and upgrade commands.
 
@@ -24,12 +24,48 @@ The canonical source is `rapidx schema --json` or `rapidx/tools`.
 - Position reads: list and position history.
 - Algo reads: list.
 
+## Symbol Format
+
+Use RapidX symbols in tool inputs:
+
+```text
+BINANCE_PERP_<BASE>_<QUOTE>
+```
+
+`OKX_PERP_<BASE>_<QUOTE>` is also supported for OKX perpetual instruments. `OKX_SWAP_<BASE>_<QUOTE>` is accepted as an input alias and is normalized to `OKX_PERP_<BASE>_<QUOTE>` in preview matching and outputs.
+
+Public market adapters may call venue APIs with official venue symbols such as `BTCUSDT` or `BTC-USDT-SWAP`. When the venue response uses a different symbol, RapidX returns canonical `symbol` plus `originalSymbol`.
+
 ## Write Tools
 
 - Order writes: place, amend, and cancel.
 - Position writes: close and set leverage.
 - Account writes: set position mode.
 - Algo writes: place, amend, and cancel.
-- Live verification: `rapidx/trade/verify-live` is the clearer alias for the small real-trade verification flow. It submits a real verification order and requires `acceptedRiskText` bound to the exact symbol, side, maxNotional, real-order risk, and cancel cleanup behavior. `rapidx/trading-verification` remains supported for compatibility.
+- Live verification: `rapidx/trade/verify-live` is the clearer alias for the small real-trade verification flow. It submits a real verification order and requires `acceptedRiskText` bound to the exact symbol, side, maxNotional, real-order risk, and cancel cleanup behavior. If `positionSide` is provided, `acceptedRiskText` must include it. `rapidx/trading-verification` remains supported for compatibility.
 
 All write tools require preview where the schema marks `previewRequired: true`.
+MARKET order writes are allowed after preview and consent. Preview includes immediate-execution and slippage risk notes; do not replace MARKET with a synthetic limit strategy unless the user explicitly asks for that order style.
+
+For hedge-mode order placement, pass `positionSide="LONG"` or `positionSide="SHORT"` on the order or verify-live input. Use `account.set-position-mode` only when the user explicitly asks to change the account position mode.
+
+Preview ids are runtime-local. A preview created by MCP must be submitted through the same MCP server runtime. A preview created by CLI must be submitted through the same CLI preview store. Do not mix MCP preview ids with CLI submit commands, or the reverse.
+
+`order.cancel` is asynchronous. A successful cancel response means the cancel request was accepted; it may not prove a terminal order state yet. The response includes `cancelAccepted`, `terminalStateConfirmed`, `lastObservedOrderState`, and `recommendedAction`. Poll `order.get` until `CANCELED`, `REJECTED`, `EXPIRED`, or timeout when `terminalStateConfirmed=false`.
+
+Order identifiers use two validation layers. If `orderId` is provided, RapidX validates it locally as a 16-digit numeric id and returns `INVALID_INPUT` before any upstream call when the format is wrong. If `clientOrderId` is provided instead, do not apply `orderId` validation. For `order.get`, `order.amend-preview`, and `order.cancel-preview`, a syntactically valid `orderId` or `clientOrderId` is checked through RapidX readback; missing or non-open orders return `NOT_FOUND` or `BLOCKED` depending on the observed state.
+
+For automation, keep preview-first execution. Set `automationMode=true` and pass the user's exact `automationConsentText` only when the user has explicitly enabled RapidX automation mode in chat. The preview response still returns `confirmation.submitToken`; automation mode only means the agent may use that submit token without asking for another per-order chat confirmation within the authorized scope.
+
+For TPSL or conditional algo orders, use `rapidx/trade/preview` with `targetCapabilityId="algo.place"`, then submit `rapidx/algo/place`. `conditionType="ENTIRE_CLOSE_POSITION"` may use `orderType="MARKET"` without `quantity` or `amount`; provide at least one take-profit or stop-loss trigger and verify with `rapidx/algo/list`.
+
+## Result Statuses
+
+- `PASS`: the tool or command completed successfully.
+- `INVALID_INPUT`: local schema or parameter validation failed. Fix the input before retrying.
+- `BLOCKED`: local preview, safety, compatibility, or policy checks rejected the action before submission.
+- `NOT_FOUND`: the requested order, position, or upstream resource was not found.
+- `PERMISSION_SCOPE_ERROR`: credentials are valid but do not cover the requested scope, such as account-level balance with portfolio-scoped credentials.
+- `BUSINESS_ERROR`: RapidX or venue business rules rejected the request.
+- `NOT_VERIFIED`: the tool could not prove the requested state.
+- `FAIL`: startup, auth, network, malformed response, or unexpected execution failure.

package/packages/distribution/manifests/offline-manifest.json

@@ -1,25 +1,25 @@
 {
-  "version": "1.0.28",
+  "version": "1.0.30",
   "artifacts": [
     {
       "name": "rapidx-mcp-registry",
       "path": "packages/distribution/registry/rapidx.mcp.json",
       "channel": "offline",
-      "checksum": "sha256:0e4bbf784d784442bd296e4ca6d490733ccd40e50f7b299b211b5fdb4dcb465d",
+      "checksum": "sha256:ad2ef7cf5eae5cadf3d6901574a93219a90dd2b53f0412ee354984ed30edf004",
       "status": "ready"
     },
     {
       "name": "rapidx-quickstart-doc",
       "path": "packages/distribution/docs/quickstart.md",
       "channel": "offline",
-      "checksum": "sha256:0f78bb814c60ec3f5ac1053cac49c1c1e768ff529b70b32e44a31f96ad8a1e95",
+      "checksum": "sha256:f1771cbc6e3da39b47afac839ca89fc063bede11ac9d8078b215145953c0145c",
       "status": "ready"
     },
     {
       "name": "rapidx-tools-doc",
       "path": "packages/distribution/docs/tools.md",
       "channel": "offline",
-      "checksum": "sha256:ab953a5e40024e9171ad7510bd37fef20e6aa9c6d89bfc219160cb33bb465712",
+      "checksum": "sha256:fc80e63eabc8407c74b01ed707187505c90497af53a25f201c07e13ef948bf18",
       "status": "ready"
     }
   ]

package/packages/distribution/registry/rapidx.mcp.json

@@ -1,7 +1,7 @@
 {
   "name": "rapidx",
   "packageName": "@liquiditytech/rapidx-cli",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "command": "rapidx",
   "args": ["mcp", "serve"],
   "launchCommand": "rapidx",