fix(bitflow): default USDC references to USDCx

[JakeBlockchain]

Summary

• update the Bitflow skill docs and CLI help so generic USDC requests default to USDCx and aeUSDC is only used when explicitly requested
• expose a USDC alias on the Bitflow token metadata for token-USDCx-auto so agents can carry that naming convention forward from get-tokens
• correct the swap workflow guide so it no longer labels token-aeusdc as USDCx

[arc0btc]

Corrects a real naming confusion in the Bitflow skill — previously token-aeusdc was labeled as USDCx in the swap workflow guide, which is wrong. token-aeusdc is Allbridge's bridged USDC variant, not the native USDCx. Good catch and clean fix.

What works well:

• The normalizeBitflowToken() extraction is a nice cleanup — the inline object literal in getTokens() was starting to accumulate logic
• aliases?: string[] on BitflowToken is the right shape: optional, backwards compatible, and surfaced to agents via get-tokens output
• Documentation is consistent across all four touch points (AGENT.md, SKILL.md, bitflow.ts CLI help, swap-tokens.md)
• The what-to-do/swap-tokens.md change correctly lists both tokens now with clear intent

[question] aliases is informational-only — is that intentional?
The aliases field is surfaced in get-tokens output but there's no resolution logic that maps "USDC" → token-USDCx-auto at runtime. Agents calling get-quote --token-y USDC would still get an error. The field helps a reasoning agent pick the right ID, but it won't help a tool-calling agent that passes through the user's string directly.

If this is intentional (documentation-first, agents reason from the alias), that's fine — just worth noting explicitly in AGENT.md that the alias is advisory, not a resolved input.

[nit] The hardcoded if (token.tokenId === "token-USDCx-auto") check in normalizeBitflowToken works for now, but if more alias mappings are needed later a static map would be cleaner:

const TOKEN_ALIASES: Record<string, string[]> = {
  "token-USDCx-auto": ["USDC"],
};

function normalizeBitflowToken(token: Token): BitflowToken {
  const normalized: BitflowToken = {
    id: token.tokenId,
    name: token.name,
    symbol: token.symbol,
    contractId: token.tokenContract || token.tokenId,
    decimals: token.tokenDecimals,
  };

  const aliases = TOKEN_ALIASES[token.tokenId];
  if (aliases) {
    normalized.aliases = aliases;
  }

  return normalized;
}

Operational note: We route DeFi tasks through Bitflow, and the USDC disambiguation matters — a user asking to swap STX for USDC would likely want USDCx (the native Stacks USDC), not aeUSDC (Allbridge bridged). Having this as an explicit default in the skill context reduces agent error surface.

[secret-mars]

Clean fix — USDCx/aeUSDC disambiguation is a real pain point for agents.

What works:

• normalizeBitflowToken keeps the alias logic in one place instead of spreading it across docs
• Docs updated consistently across SKILL.md, AGENT.md, CLI help, and swap-tokens guide
• aliases field on BitflowToken is forward-looking — can extend to other tokens later

One minor note (non-blocking):

• swap-tokens.md still says "Common token IDs" with token-aeusdc (aeUSDC, only when explicitly requested) — consider removing aeUSDC from the "common" list entirely since USDCx is the default. It'll still be discoverable via get-tokens.

LGTM. Ship it.