chore: prerelease v1.1016.0

.claude/guidelines/beads-rules.md

@@ -0,0 +1,22 @@
+## Beads Rules
+
+Use `bd` as the default workflow for complex multi-step work.
+
+### Priority
+- For complex tasks, always prefer beads tracking before implementation.
+- Keep bead status current as work progresses (`in_progress`, then `closed`).
+- Keep beads sync in your normal completion flow.
+
+### Commands
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --status in_progress  # Claim work
+bd close <id>         # Complete work
+bd sync               # Sync with git
+```
+
+### Session Completion Integration
+- Include beads updates in session completion.
+- Before final push, ensure bead state is consistent with delivered work.

.claude/guidelines/global-rules.md

@@ -0,0 +1,59 @@
+## Global Programming Rules
+
+### Code Quality & Style
+- Look for opportunities to use existing code rather than creating new code
+- Follow existing code conventions in each file/project
+- Use existing libraries and utilities already present in the codebase
+- Never assume a library is available - always check imports/package.json first
+- Prefer composition over inheritance
+- Write self-documenting code with clear variable and function names
+- Keep functions small and focused on a single responsibility
+- Avoid deep nesting - use early returns instead
+- Prefer procedural and easy to understand code
+- Avoid useEffect where practical - use it only when necessary and following best practices
+- Choose the most straightforward approach that accomplishes the task
+- Avoid "any" types - use specific type annotations instead
+- For default values with user overrides, use computed values (useMemo) instead of useEffect - pattern: `userSelected ?? smartDefault ?? fallback`
+- When function parameters are unused due to interface requirements, refactor the interface or implementation to remove them rather than prefixing with underscore
+
+### Security & Best Practices
+- Never expose, log, or commit secrets, API keys, or credentials
+- Validate all inputs, especially user inputs
+- Use parameterized queries to prevent SQL injection
+- Sanitize data before displaying to prevent XSS
+- Follow principle of least privilege
+- Use HTTPS and secure communication protocols
+
+### Error Handling
+- Handle errors gracefully with meaningful messages
+- Don't silently catch and ignore exceptions
+- Log errors appropriately for debugging
+- Provide fallback behavior when possible
+- Use proper HTTP status codes in APIs
+
+### Performance
+- Avoid premature optimization, but be mindful of performance
+- Use appropriate data structures for the task
+- Minimize database queries and API calls
+- Implement proper caching strategies
+- Optimize images and assets for web delivery
+
+### Testing
+- Write tests for critical business logic
+- Test edge cases and error conditions
+- Use descriptive test names that explain behavior
+- Keep tests isolated and independent
+- Mock external dependencies appropriately
+
+### Documentation & Communication
+- Never add code comments unless explicitly requested
+- When modifying code, do not add comments that reference previous implementations or explain what changed. Comments should only describe the current logic and functionality.
+- Write clear commit messages explaining the "why"
+- Use meaningful names for branches, variables, and functions
+- Keep README files updated with setup and usage instructions
+
+### Rule Management
+- When user says "add that to the project rules": take previous guidance, form a rule, and add it to `.claude/guidelines/project-rules.md`
+- When user says "add that to the global rules": take previous guidance, form a rule, and add it to `.claude/guidelines/global-rules.md`
+
+---

.claude/guidelines/pr-rules.md

@@ -0,0 +1,6 @@
+## PR-Specific Rules
+
+### xstate PRs
+- When a PR includes xstate state machines, the PR description MUST include a Mermaid `stateDiagram-v2` visualization of the machine's states and transitions
+- Generate the diagram from the machine definition - show states, events, guards, and error/retry flows
+- This serves as living documentation for both product and engineering reviewers

.claude/guidelines/project-rules.md

@@ -0,0 +1,153 @@
+## Project-Specific Rules: ShapeShift
+
+### Project Overview
+- **Project**: Decentralized crypto exchange platform
+- **Main branch**: `develop` (not main/master)
+- **Package manager**: pnpm
+- **State management**: Redux Toolkit with redux-persist
+- **Architecture**: Plugin-based for blockchain support
+
+### Code Quality & Standards
+- Always run `pnpm run lint --fix` and `pnpm run type-check` after making changes
+- Keep changes surgical where possible - minimize changes to make code reviews easier
+- Make targeted, focused modifications rather than broad refactors unless specifically requested
+- Never create documentation files unless explicitly requested
+- Prefer editing existing files over creating new ones
+- Memoize aggressively - wrap component variables in `useMemo` and callbacks in `useCallback` where possible
+- Avoid `let` variable assignments - prefer `const` with inline IIFE switch statements or extract to functions for conditional logic
+- For static JSX icon elements (e.g., `<TbCopy />`) that don't depend on state/props, define them as constants outside the component to avoid re-renders instead of using useMemo
+
+### CLI Tool Preferences
+- Prefer `rg` (ripgrep) over `grep` for searching - it's faster and respects .gitignore
+- Use `jq` for querying and manipulating JSON files instead of reading entire files into context
+  - Example: `jq '.yieldXYZ | keys' src/assets/translations/en/main.json` to list keys
+  - Example: `jq '.someKey.nested' file.json` to extract specific values
+- This is especially important for large JSON files (like generated data or translation files) to avoid context bloat and improve performance
+
+### Git & Version Control
+- Never commit changes unless explicitly requested
+- When creating commits, follow the Git Safety Protocol (see session notes)
+- **Before pushing**: always run `pnpm run lint --fix`, and if there are lint fixes, commit them before pushing. Never push without verifying lint passes first.
+- Main branch is `develop` - use this for PRs
+- Branch naming: Use descriptive names (e.g., `feat_gridplus`, `fix_wallet_connect`)
+- Prefer pushing new feature/fix branches to `origin` when permissions allow.
+- If a PR branch already exists on `fork`, continue pushing to that existing `fork` branch and do not recreate it on `origin`.
+- When opening PRs (via `gh`, Aviator `av`, or any CLI tool), ALWAYS use the `.github/PULL_REQUEST_TEMPLATE.md` template as the base for the PR body
+- **Editing PR descriptions**: `gh pr edit --body` fails on this repo due to a deprecated Projects Classic GraphQL error. Use the REST API instead: `gh api repos/shapeshift/web/pulls/<number> -X PATCH -F "body=@/path/to/body.md"` (write the body to a temp file first)
+
+### UI/UX Standards
+- Account for light/dark mode using `useColorModeValue` hook
+- Account for responsive mobile designs in all UI components
+- When applying styles, use the existing standards and conventions of the codebase
+- Use Chakra UI components and conventions
+
+### Internationalization (i18n)
+- All copy/text must use translation keys - never hardcode strings
+- Add English copy to `src/assets/translations/en/main.json` (find appropriate section)
+- Ignore other language translation files - only update English
+- Use the translation hook: `useTranslate()` from `react-polyglot`
+- **Both steps required**: Translations must be (1) added to `en/main.json` AND (2) consumed via `translate('key')` - missing either step results in untranslated strings showing raw keys
+
+### Feature Flags
+- Feature flags are stored in Redux state under `preferences.featureFlags`
+- Feature flags are NOT persisted between sessions (blacklisted in redux-persist)
+- Default values always come from environment variables prefixed with `VITE_FEATURE_`
+
+**To add a new feature flag:**
+1. Add to `FeatureFlags` type in `src/state/slices/preferencesSlice/preferencesSlice.ts`
+2. Add environment variable validation in `src/config.ts` (e.g., `VITE_FEATURE_MY_FLAG: bool({ default: false })`)
+3. Add to initial state in `preferencesSlice.ts` (e.g., `MyFlag: getConfig().VITE_FEATURE_MY_FLAG`)
+4. Add to test mock in `src/test/mocks/store.ts`
+5. Set appropriate values in `.env`, `.env.development`, and `.env.production`
+
+**Usage:**
+- Use `useFeatureFlag('FlagName')` hook to access feature flag values in components
+- The `/flags` route provides a hidden UI for toggling feature flags at runtime (click settings modal header 5 times)
+- Use `.env.development` for dev-only features and `.env.production` for prod settings
+
+### Redux State Management
+- Uses Redux Toolkit with createSlice
+- State is persisted with redux-persist (localforage)
+- Migrations are required when changing persisted state structure (see `src/state/migrations/`)
+- When adding new slices:
+  1. Create slice in `src/state/slices/<sliceName>/`
+  2. Add to `src/state/reducer.ts` (both `slices` and `sliceReducers`)
+  3. Add to `src/state/store.ts` `clearState()` function
+  4. Add persist config if needed
+  5. Export selectors from slice using `selectors` property
+
+### Contracts (Enforceable Integration Specs)
+
+Contracts live in `.claude/contracts/` (project) and `~/.claude/contracts/` (global, fallback).
+They define the authoritative checklist of integration points for a feature type.
+
+**When building:** If a contract exists for the feature type being implemented, load it
+and use it as your todo list. Every item must be addressed.
+
+**When reviewing:** If a contract exists for the feature type being reviewed, load it
+and perform gap analysis against the PR diff. Flag missing items with severity prefixes.
+
+**Discovery:** Check `.claude/contracts/` first, then `~/.claude/contracts/`.
+
+Current contracts:
+- `second-class-evm-chain.md` - All integration points for adding a new second-class EVM chain
+- `swapper-integration.md` - Registration, testing, and completion checklist for new swappers
+
+### Type Definitions
+- Prefer `type` over `interface` for type definitions
+- Use strict typing - avoid `any`
+- Use `Nominal` types for domain identifiers (e.g., `WalletId`, `AccountId`)
+- Import types from `@shapeshiftoss/caip` for chain/account/asset IDs
+
+### Common Patterns
+
+**Selectors:**
+- Use `createDeepEqualOutputSelector` from `@/state/selector-utils` for deep equality checks
+- Use `createCachedSelector` from `re-reselect` for parameterized selectors
+- Export selectors from slice using inline `selectors` property
+
+**Components:**
+- Use `useAppSelector` for Redux state
+- Use `useAppDispatch` for Redux actions
+- Memoize expensive computations with `useMemo`
+- Memoize callbacks with `useCallback`
+
+**BigAmount (Precision-Aware Numeric Type):**
+- See `docs/bigamount.md` for full API documentation
+- Use `BigAmount.fromBaseUnit({ value, precision })` for constructing from raw blockchain values (preferred, lossless)
+- Use `BigAmount.fromPrecision({ value, precision })` only when a precision-scale value is all that's available
+- Call `.toPrecision()` / `.toBaseUnit()` directly on BigAmount for string extraction — no wrapper aliases
+- Never cast `as BigAmount` — fix types as needed
+- Naming: `CryptoBaseUnit` = raw integer, `CryptoPrecision` = human-readable (NOT "HumanBalance")
+
+**Wallet Integration:**
+- Wallets are managed via `WalletProvider` context
+- Each wallet has unique `walletId` (e.g., `metamask:0x123`, `ledger:ABC`)
+- Portfolio state is filtered by active `walletId`
+- Account discovery runs per wallet on connection
+
+### Session Completion
+
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+
+**MANDATORY WORKFLOW:**
+
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   git pull --rebase
+   bd sync
+   git push
+   git status  # MUST show "up to date with origin"
+   ```
+5. **Clean up** - Clear stashes, prune remote branches
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+- Work is NOT complete until `git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds

.claude/programming-guidelines.md

@@ -0,0 +1,15 @@
+# Programming And Project Rules (TOC)
+
+This file is the TOC entrypoint for coding, project, and PR-specific rules.
+
+## Read Order
+
+1. [.claude/guidelines/global-rules.md](.claude/guidelines/global-rules.md)
+2. [.claude/guidelines/beads-rules.md](.claude/guidelines/beads-rules.md)
+3. [.claude/guidelines/project-rules.md](.claude/guidelines/project-rules.md)
+4. [.claude/guidelines/pr-rules.md](.claude/guidelines/pr-rules.md)
+
+@.claude/guidelines/global-rules.md
+@.claude/guidelines/beads-rules.md
+@.claude/guidelines/project-rules.md
+@.claude/guidelines/pr-rules.md

.claude/test-scenarios/README.md

@@ -2,6 +2,12 @@
 
 This directory contains automated test scenarios for the ShapeShift Web application. These scenarios are used by the `/test-agent` slash command to validate features and ensure quality.
 
+## Scope Clarification
+
+- This directory is for `@neomaking`'s `/test-agent` workflow and related scenario docs.
+- This is not `qabot` testing.
+- `qabot` has its own fixture-based flow and instructions at `.claude/skills/qabot/SKILL.md`.
+
 ## Directory Structure
 
 ```

.codex/config.toml

@@ -0,0 +1 @@
+model_instructions_file = "AGENTS.md"

.codex/skills

@@ -0,0 +1 @@
+../.claude/skills

.railwayignore

@@ -1,49 +1,31 @@
-# Railway snapshot ignore - reduce repo snapshot size for public-api builds
+# Railway snapshot ignore - reduce repo snapshot size for Railway builds
 # The Dockerfile.dockerignore handles Docker build context separately;
 # this file reduces what Railway snapshots from GitHub before the build starts.
 
-# Frontend source (not needed for public-api server build)
+# Frontend source (not needed for server builds)
 src/
-cypress/
 e2e/
 
-# Large generated/static assets already copied explicitly in Dockerfile
-public/generated/generatedAssetData.json.gz
-public/generated/generatedAssetData.json.br
-public/generated/relatedAssetIndex.json
+# Static assets
+public/
+!public/generated/generatedAssetData.json
 
-# Images and static assets
-src/assets/
-*.png
-*.jpg
-*.jpeg
-*.svg
-*.gif
-*.ico
-*.webp
-
-# Development/IDE files
-.vscode/
-.idea/
+# Development tooling
+.github/
+.cursor/
 .claude/
 .agents/
-.beads/
-.playwright-mcp/
-coverage/
-*.log
-.DS_Store
-
-# Yarn state (not needed for pnpm builds)
-.yarn/
+prds/
+scripts/
+headers/
+__mocks__/
 
 # Documentation
+docs/
 *.md
 !packages/public-api/*.md
 !packages/swap-widget/*.md
-docs/
 
 # Test files
-**/*.test.ts
-**/*.test.tsx
-**/*.spec.ts
-**/*.spec.tsx
+**/*.test.*
+**/*.spec.*

AGENTS.md

@@ -0,0 +1,40 @@
+# Agent Instructions (Source of Truth)
+
+This file is the canonical instruction entrypoint for local agent tooling in this repo.
+
+## Read Order
+
+1. This file (high-signal defaults and routing)
+2. [.claude/guidelines/beads-rules.md](.claude/guidelines/beads-rules.md)
+3. [.claude/programming-guidelines.md](.claude/programming-guidelines.md)
+4. [.claude/contracts](.claude/contracts)
+5. [.claude/skills](.claude/skills)
+6. [.claude/test-scenarios/README.md](.claude/test-scenarios/README.md)
+7. [.github/PULL_REQUEST_TEMPLATE.md](.github/PULL_REQUEST_TEMPLATE.md)
+
+## Must-Follow Defaults
+
+- Use `develop` as the base branch.
+- Use `pnpm`.
+- Keep changes surgical and focused.
+- For complex multi-step tasks, prefer `bd` tracking before implementation.
+- Prefer `origin` for new feature/fix branch pushes when permissions allow.
+- If a PR branch is already on `fork`, keep using that existing `fork` branch.
+- Run `pnpm run lint --fix` and `pnpm run type-check` after code changes.
+- Use `.github/PULL_REQUEST_TEMPLATE.md` for PR bodies.
+
+## Routing
+
+- New second-class EVM chain work: [.claude/contracts/second-class-evm-chain.md](.claude/contracts/second-class-evm-chain.md)
+- New swapper integration work: [.claude/contracts/swapper-integration.md](.claude/contracts/swapper-integration.md)
+- Test scenarios (`/test-agent`, @neomaking flow): [.claude/test-scenarios/README.md](.claude/test-scenarios/README.md)
+- QA automation (`qabot`, fixture-based flow): [.claude/skills/qabot/SKILL.md](.claude/skills/qabot/SKILL.md)
+- Translation workflow: [.claude/skills/translate/SKILL.md](.claude/skills/translate/SKILL.md)
+
+## Tooling Notes
+
+- Claude compatibility is provided by `CLAUDE.md` importing this file.
+- Codex compatibility is pinned via `.codex/config.toml`.
+- Full legacy `CLAUDE.md` policy content was moved to `.claude/programming-guidelines.md` to avoid loss while keeping top-level entrypoints compact.
+- Repo-local skills live in `.claude/skills`.
+- Additional user-level skills/config may exist in `~/.agents`, `~/.codex/skills`, and `~/.openclaw`.