wayfinder-paths 0.1.2__tar.gz → 0.1.4__tar.gz

{wayfinder_paths-0.1.2 → wayfinder_paths-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wayfinder-paths
-Version: 0.1.2
+Version: 0.1.4
 Summary: Wayfinder Path: strategies and adapters
 Author: Wayfinder
 Author-email: dev@wayfinder.ai
@@ -42,8 +42,9 @@ curl -sSL https://install.python-poetry.org | python3 -
 poetry install
 
 # ⚠️ Generate test wallets FIRST (required!)
-# This creates wallets.json with live wallets for local testing
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+# This creates wallets.json with a main wallet for local testing
+just create-wallets
+# Or manually: poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
 
 # Copy and configure
 cp wayfinder_paths/config.example.json config.json
@@ -167,7 +168,9 @@ cd wayfinder-paths
 poetry install
 
 # 3. Generate test wallets (required before testing!)
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+# Creates a main wallet (or use 'just create-strategy' which auto-creates wallets)
+just create-wallets
+# Or manually: poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
 
 # 4. Create a new strategy (recommended - automatically creates wallet)
 just create-strategy "My Strategy Name"
@@ -230,7 +233,7 @@ Adapter manifests declare the capabilities an adapter provides and the clients i
 **Schema:**
 ```yaml
 schema_version: "0.1"
-entrypoint: "vaults.adapters.my_adapter.adapter.MyAdapter"
+entrypoint: "adapters.my_adapter.adapter.MyAdapter"
 capabilities:
   - "pool.read"
   - "pool.analytics"
@@ -248,7 +251,7 @@ dependencies:
 **Example** (`vaults/adapters/pool_adapter/manifest.yaml`):
 ```yaml
 schema_version: "0.1"
-entrypoint: "vaults.adapters.pool_adapter.adapter.PoolAdapter"
+entrypoint: "adapters.pool_adapter.adapter.PoolAdapter"
 capabilities:
   - "pool.read"
   - "pool.analytics"
@@ -268,7 +271,7 @@ Strategy manifests declare permissions and required adapters with their capabili
 **Schema:**
 ```yaml
 schema_version: "0.1"
-entrypoint: "vaults.strategies.my_strategy.strategy.MyStrategy"
+entrypoint: "strategies.my_strategy.strategy.MyStrategy"
 permissions:
   policy: "(wallet.id == 'FORMAT_WALLET_ID') && (eth.tx.to == '0x...')"
 adapters:
@@ -290,7 +293,7 @@ adapters:
 **Example** (`vaults/strategies/stablecoin_yield_strategy/manifest.yaml`):
 ```yaml
 schema_version: "0.1"
-entrypoint: "vaults.strategies.stablecoin_yield_strategy.strategy.StablecoinYieldStrategy"
+entrypoint: "strategies.stablecoin_yield_strategy.strategy.StablecoinYieldStrategy"
 permissions:
   policy: "(wallet.id == 'FORMAT_WALLET_ID') && ((eth.tx.data[0..10] == '0x095ea7b3' && eth.tx.data[34..74] == 'f75584ef6673ad213a685a1b58cc0330b8ea22cf') || (eth.tx.to == '0xF75584eF6673aD213a685a1B58Cc0330B8eA22Cf'))"
 adapters:
@@ -328,7 +331,7 @@ The `validate_manifests.py` script performs multi-stage validation:
 1. **Schema Validation** (via Pydantic models):
    - Loads YAML file and validates against `AdapterManifest` or `StrategyManifest` schema
    - Checks required fields, types, and basic constraints (e.g., capabilities cannot be empty)
-   - Validates entrypoint format (must be full import path like `"vaults.adapters.pool_adapter.adapter.PoolAdapter"`)
+   - Validates entrypoint format (must be full import path like `"adapters.pool_adapter.adapter.PoolAdapter"`)
 
 2. **Entrypoint Verification**:
    - **For Adapters**: Imports the entrypoint class and verifies it's a subclass of `BaseAdapter`
@@ -385,7 +388,7 @@ For backend services and automated systems with higher rate limits:
 
 **Option A: Pass to Strategy Constructor**
 ```python
-from wayfinder_paths.vaults.strategies.stablecoin_yield_strategy.strategy import StablecoinYieldStrategy
+from wayfinder_paths.strategies.stablecoin_yield_strategy.strategy import StablecoinYieldStrategy
 
 strategy = StablecoinYieldStrategy(
     config={...},
@@ -411,7 +414,9 @@ export WAYFINDER_API_KEY="sk_live_abc123..."
 }
 ```
 
-**Priority Order:** Constructor parameter > `config.json` > `WAYFINDER_API_KEY` environment variable
+**Priority Order:** Constructor parameter > `config.json` (user.api_key or system.api_key) > `WAYFINDER_API_KEY` environment variable
+
+**Note:** API keys in `config.json` are loaded directly by `WayfinderClient` via `_load_config_credentials()`, not through the `UserConfig` or `SystemConfig` dataclasses. This allows flexible credential loading.
 
 #### 2. Personal Access Authentication (OAuth)
 For standalone SDK users with username/password:
@@ -431,6 +436,7 @@ For standalone SDK users with username/password:
 - When an API key is available, it's used for all API requests (including public endpoints) for rate limiting
 - If no API key is found, the system falls back to OAuth authentication
 - All clients created by adapters automatically inherit the API key discovery mechanism
+- API keys in `config.json` are loaded directly by `WayfinderClient._load_config_credentials()` from `user.api_key` or `system.api_key`, not stored in the `UserConfig` or `SystemConfig` dataclasses
 
 See [CONFIG_GUIDE.md](wayfinder_paths/CONFIG_GUIDE.md) for detailed authentication documentation.
 
@@ -472,7 +478,7 @@ Strategies implement trading logic using adapters and the unified client system.
 # wayfinder_paths/vaults/strategies/my_strategy/strategy.py
 from wayfinder_paths.core.services.web3_service import DefaultWeb3Service
 from wayfinder_paths.core.strategies.Strategy import StatusDict, StatusTuple, Strategy
-from wayfinder_paths.vaults.adapters.balance_adapter.adapter import BalanceAdapter
+from wayfinder_paths.adapters.balance_adapter.adapter import BalanceAdapter
 
 
 class MyStrategy(Strategy):
@@ -546,7 +552,9 @@ Each strategy manifest declares which adapters it needs and which capabilities i
 
 ```bash
 # 1. Generate test wallets (required!)
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+# Creates a main wallet (or use 'just create-strategy' which auto-creates wallets)
+just create-wallets
+# Or manually: poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
 
 # 2. Run smoke tests
 poetry run pytest -k smoke -v
@@ -577,7 +585,9 @@ cd wayfinder-paths
 poetry install
 
 # Generate test wallets (essential!)
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+# Creates a main wallet (or use 'just create-strategy' which auto-creates wallets)
+just create-wallets
+# Or manually: poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
 
 # Copy and configure
 cp wayfinder_paths/config.example.json config.json
@@ -598,14 +608,17 @@ poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --de
 **Before running any strategies, generate test wallets.** This creates `wallets.json` in the repository root with throwaway wallets for local testing:
 
 ```bash
-# Essential: Create default and vault wallets for testing
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+# Essential: Create main wallet for testing
+just create-wallets
+# Or manually: poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
 ```
 
 This creates:
-- `default` wallet - your main wallet for testing
+- `main` wallet - your main wallet for testing (labeled "main" in wallets.json)
 - `wallets.json` - wallet addresses and private keys for local testing
 
+**Note:** Strategy-specific wallets are automatically created when you use `just create-strategy "Strategy Name"`. For manual creation, use `just create-wallet "strategy_name"` or `poetry run python wayfinder_paths/scripts/make_wallets.py --label "strategy_name"`.
+
 **Important:** These wallets are for testing only. Never use them with real funds or on mainnet.
 
 **Per-Strategy Wallets:** Each strategy should have its own dedicated wallet. When you create a new strategy using `just create-strategy`, a wallet is automatically generated with a label matching the strategy directory name. The system automatically uses this wallet when running the strategy. See [CONFIG_GUIDE.md](wayfinder_paths/CONFIG_GUIDE.md) for details.
@@ -613,14 +626,14 @@ This creates:
 Additional options:
 
 ```bash
-# Add 3 extra unlabeled wallets for multi-account testing
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault -n 3
+# Add 3 extra wallets for multi-account testing
+poetry run python wayfinder_paths/scripts/make_wallets.py -n 3
 
-# Generate keystore files (for geth/web3 compatibility)
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault --keystore-password "my-password"
+# Create a wallet with a specific label (e.g., for a strategy)
+poetry run python wayfinder_paths/scripts/make_wallets.py --label "my_strategy_name"
 
-# Replace existing wallets (if you need fresh test wallets)
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault --override
+# Generate keystore files (for geth/web3 compatibility)
+poetry run python wayfinder_paths/scripts/make_wallets.py -n 1 --keystore-password "my-password"
 ```
 
 ### Configuration
@@ -645,6 +658,65 @@ cp wayfinder_paths/config.example.json config.json
 poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --config config.json
 ```
 
+## 📦 Versioning
+
+This package follows [Semantic Versioning](https://semver.org/) (SemVer) and is published to PyPI as a public package.
+
+### Version Format: MAJOR.MINOR.PATCH
+
+- **MAJOR** (X.0.0): Breaking changes that require code updates
+- **MINOR** (0.X.0): New features, backward compatible
+- **PATCH** (0.0.X): Bug fixes, backward compatible
+
+### Version Bumping Rules
+
+- **PATCH**: Bug fixes, security patches, documentation updates
+- **MINOR**: New adapters, new strategies, new features (backward compatible)
+- **MAJOR**: Breaking API changes, removed features, incompatible changes
+
+### Important Notes
+
+- **Versions are immutable**: Once published to PyPI, a version cannot be changed or deleted
+- **Versions must be unique**: Each release must have a new, unique version number
+- **Publishing is restricted**: Only publish from the `main` branch to prevent accidental releases
+
+### Publishing Workflow and Order of Operations
+
+**Critical**: Changes must follow this strict order:
+
+1. **Merge to main**: All changes must be merged to the `main` branch first
+2. **Publish to PyPI**: The new version must be published to PyPI from `main` branch
+3. **Dependent changes**: Only after publishing can dependent changes be merged in other applications
+
+**Why this order matters:**
+- Other applications depend on this package from PyPI
+- They cannot merge changes that depend on new versions until those versions are available on PyPI
+- Publishing from `main` ensures the published version matches what's in the repository
+- This prevents dependency resolution failures in downstream applications
+
+**Example workflow:**
+```bash
+# 1. Make changes in a feature branch
+git checkout -b feature/new-adapter
+# ... make changes ...
+git commit -m "Add new adapter"
+
+# 2. Merge to main
+git checkout main
+git merge feature/new-adapter
+
+# 3. Bump version in pyproject.toml (e.g., 0.1.3 → 0.2.0)
+# Edit pyproject.toml: version = "0.2.0"
+git commit -m "Bump version to 0.2.0"
+git push origin main
+
+# 4. Publish to PyPI (must be on main branch)
+just publish
+
+# 5. Now dependent applications can update their dependencies
+# pip install wayfinder-paths==0.2.0
+```
+
 ## 📦 Publishing
 
 Publish to PyPI:
@@ -654,6 +726,12 @@ export PUBLISH_TOKEN="your_pypi_token"
 just publish
 ```
 
+**Important:**
+- ⚠️ **Publishing is only allowed from the `main` branch** - the publish command will fail if run from any other branch
+- ⚠️ **Versions must be unique** - ensure the version in `pyproject.toml` has been bumped and is unique
+- ⚠️ **Follow the order of operations** - see [Versioning](#-versioning) section above for the required workflow
+- ⚠️ **Versions are immutable** - once published, a version cannot be changed or deleted from PyPI
+
 Install the published package:
 
 ```bash

{wayfinder_paths-0.1.2 → wayfinder_paths-0.1.4}/README.md

@@ -20,8 +20,9 @@ curl -sSL https://install.python-poetry.org | python3 -
 poetry install
 
 # ⚠️ Generate test wallets FIRST (required!)
-# This creates wallets.json with live wallets for local testing
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+# This creates wallets.json with a main wallet for local testing
+just create-wallets
+# Or manually: poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
 
 # Copy and configure
 cp wayfinder_paths/config.example.json config.json
@@ -145,7 +146,9 @@ cd wayfinder-paths
 poetry install
 
 # 3. Generate test wallets (required before testing!)
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+# Creates a main wallet (or use 'just create-strategy' which auto-creates wallets)
+just create-wallets
+# Or manually: poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
 
 # 4. Create a new strategy (recommended - automatically creates wallet)
 just create-strategy "My Strategy Name"
@@ -208,7 +211,7 @@ Adapter manifests declare the capabilities an adapter provides and the clients i
 **Schema:**
 ```yaml
 schema_version: "0.1"
-entrypoint: "vaults.adapters.my_adapter.adapter.MyAdapter"
+entrypoint: "adapters.my_adapter.adapter.MyAdapter"
 capabilities:
   - "pool.read"
   - "pool.analytics"
@@ -226,7 +229,7 @@ dependencies:
 **Example** (`vaults/adapters/pool_adapter/manifest.yaml`):
 ```yaml
 schema_version: "0.1"
-entrypoint: "vaults.adapters.pool_adapter.adapter.PoolAdapter"
+entrypoint: "adapters.pool_adapter.adapter.PoolAdapter"
 capabilities:
   - "pool.read"
   - "pool.analytics"
@@ -246,7 +249,7 @@ Strategy manifests declare permissions and required adapters with their capabili
 **Schema:**
 ```yaml
 schema_version: "0.1"
-entrypoint: "vaults.strategies.my_strategy.strategy.MyStrategy"
+entrypoint: "strategies.my_strategy.strategy.MyStrategy"
 permissions:
   policy: "(wallet.id == 'FORMAT_WALLET_ID') && (eth.tx.to == '0x...')"
 adapters:
@@ -268,7 +271,7 @@ adapters:
 **Example** (`vaults/strategies/stablecoin_yield_strategy/manifest.yaml`):
 ```yaml
 schema_version: "0.1"
-entrypoint: "vaults.strategies.stablecoin_yield_strategy.strategy.StablecoinYieldStrategy"
+entrypoint: "strategies.stablecoin_yield_strategy.strategy.StablecoinYieldStrategy"
 permissions:
   policy: "(wallet.id == 'FORMAT_WALLET_ID') && ((eth.tx.data[0..10] == '0x095ea7b3' && eth.tx.data[34..74] == 'f75584ef6673ad213a685a1b58cc0330b8ea22cf') || (eth.tx.to == '0xF75584eF6673aD213a685a1B58Cc0330B8eA22Cf'))"
 adapters:
@@ -306,7 +309,7 @@ The `validate_manifests.py` script performs multi-stage validation:
 1. **Schema Validation** (via Pydantic models):
    - Loads YAML file and validates against `AdapterManifest` or `StrategyManifest` schema
    - Checks required fields, types, and basic constraints (e.g., capabilities cannot be empty)
-   - Validates entrypoint format (must be full import path like `"vaults.adapters.pool_adapter.adapter.PoolAdapter"`)
+   - Validates entrypoint format (must be full import path like `"adapters.pool_adapter.adapter.PoolAdapter"`)
 
 2. **Entrypoint Verification**:
    - **For Adapters**: Imports the entrypoint class and verifies it's a subclass of `BaseAdapter`
@@ -363,7 +366,7 @@ For backend services and automated systems with higher rate limits:
 
 **Option A: Pass to Strategy Constructor**
 ```python
-from wayfinder_paths.vaults.strategies.stablecoin_yield_strategy.strategy import StablecoinYieldStrategy
+from wayfinder_paths.strategies.stablecoin_yield_strategy.strategy import StablecoinYieldStrategy
 
 strategy = StablecoinYieldStrategy(
     config={...},
@@ -389,7 +392,9 @@ export WAYFINDER_API_KEY="sk_live_abc123..."
 }
 ```
 
-**Priority Order:** Constructor parameter > `config.json` > `WAYFINDER_API_KEY` environment variable
+**Priority Order:** Constructor parameter > `config.json` (user.api_key or system.api_key) > `WAYFINDER_API_KEY` environment variable
+
+**Note:** API keys in `config.json` are loaded directly by `WayfinderClient` via `_load_config_credentials()`, not through the `UserConfig` or `SystemConfig` dataclasses. This allows flexible credential loading.
 
 #### 2. Personal Access Authentication (OAuth)
 For standalone SDK users with username/password:
@@ -409,6 +414,7 @@ For standalone SDK users with username/password:
 - When an API key is available, it's used for all API requests (including public endpoints) for rate limiting
 - If no API key is found, the system falls back to OAuth authentication
 - All clients created by adapters automatically inherit the API key discovery mechanism
+- API keys in `config.json` are loaded directly by `WayfinderClient._load_config_credentials()` from `user.api_key` or `system.api_key`, not stored in the `UserConfig` or `SystemConfig` dataclasses
 
 See [CONFIG_GUIDE.md](wayfinder_paths/CONFIG_GUIDE.md) for detailed authentication documentation.
 
@@ -450,7 +456,7 @@ Strategies implement trading logic using adapters and the unified client system.
 # wayfinder_paths/vaults/strategies/my_strategy/strategy.py
 from wayfinder_paths.core.services.web3_service import DefaultWeb3Service
 from wayfinder_paths.core.strategies.Strategy import StatusDict, StatusTuple, Strategy
-from wayfinder_paths.vaults.adapters.balance_adapter.adapter import BalanceAdapter
+from wayfinder_paths.adapters.balance_adapter.adapter import BalanceAdapter
 
 
 class MyStrategy(Strategy):
@@ -524,7 +530,9 @@ Each strategy manifest declares which adapters it needs and which capabilities i
 
 ```bash
 # 1. Generate test wallets (required!)
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+# Creates a main wallet (or use 'just create-strategy' which auto-creates wallets)
+just create-wallets
+# Or manually: poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
 
 # 2. Run smoke tests
 poetry run pytest -k smoke -v
@@ -555,7 +563,9 @@ cd wayfinder-paths
 poetry install
 
 # Generate test wallets (essential!)
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+# Creates a main wallet (or use 'just create-strategy' which auto-creates wallets)
+just create-wallets
+# Or manually: poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
 
 # Copy and configure
 cp wayfinder_paths/config.example.json config.json
@@ -576,14 +586,17 @@ poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --de
 **Before running any strategies, generate test wallets.** This creates `wallets.json` in the repository root with throwaway wallets for local testing:
 
 ```bash
-# Essential: Create default and vault wallets for testing
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+# Essential: Create main wallet for testing
+just create-wallets
+# Or manually: poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
 ```
 
 This creates:
-- `default` wallet - your main wallet for testing
+- `main` wallet - your main wallet for testing (labeled "main" in wallets.json)
 - `wallets.json` - wallet addresses and private keys for local testing
 
+**Note:** Strategy-specific wallets are automatically created when you use `just create-strategy "Strategy Name"`. For manual creation, use `just create-wallet "strategy_name"` or `poetry run python wayfinder_paths/scripts/make_wallets.py --label "strategy_name"`.
+
 **Important:** These wallets are for testing only. Never use them with real funds or on mainnet.
 
 **Per-Strategy Wallets:** Each strategy should have its own dedicated wallet. When you create a new strategy using `just create-strategy`, a wallet is automatically generated with a label matching the strategy directory name. The system automatically uses this wallet when running the strategy. See [CONFIG_GUIDE.md](wayfinder_paths/CONFIG_GUIDE.md) for details.
@@ -591,14 +604,14 @@ This creates:
 Additional options:
 
 ```bash
-# Add 3 extra unlabeled wallets for multi-account testing
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault -n 3
+# Add 3 extra wallets for multi-account testing
+poetry run python wayfinder_paths/scripts/make_wallets.py -n 3
 
-# Generate keystore files (for geth/web3 compatibility)
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault --keystore-password "my-password"
+# Create a wallet with a specific label (e.g., for a strategy)
+poetry run python wayfinder_paths/scripts/make_wallets.py --label "my_strategy_name"
 
-# Replace existing wallets (if you need fresh test wallets)
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault --override
+# Generate keystore files (for geth/web3 compatibility)
+poetry run python wayfinder_paths/scripts/make_wallets.py -n 1 --keystore-password "my-password"
 ```
 
 ### Configuration
@@ -623,6 +636,65 @@ cp wayfinder_paths/config.example.json config.json
 poetry run python wayfinder_paths/run_strategy.py stablecoin_yield_strategy --config config.json
 ```
 
+## 📦 Versioning
+
+This package follows [Semantic Versioning](https://semver.org/) (SemVer) and is published to PyPI as a public package.
+
+### Version Format: MAJOR.MINOR.PATCH
+
+- **MAJOR** (X.0.0): Breaking changes that require code updates
+- **MINOR** (0.X.0): New features, backward compatible
+- **PATCH** (0.0.X): Bug fixes, backward compatible
+
+### Version Bumping Rules
+
+- **PATCH**: Bug fixes, security patches, documentation updates
+- **MINOR**: New adapters, new strategies, new features (backward compatible)
+- **MAJOR**: Breaking API changes, removed features, incompatible changes
+
+### Important Notes
+
+- **Versions are immutable**: Once published to PyPI, a version cannot be changed or deleted
+- **Versions must be unique**: Each release must have a new, unique version number
+- **Publishing is restricted**: Only publish from the `main` branch to prevent accidental releases
+
+### Publishing Workflow and Order of Operations
+
+**Critical**: Changes must follow this strict order:
+
+1. **Merge to main**: All changes must be merged to the `main` branch first
+2. **Publish to PyPI**: The new version must be published to PyPI from `main` branch
+3. **Dependent changes**: Only after publishing can dependent changes be merged in other applications
+
+**Why this order matters:**
+- Other applications depend on this package from PyPI
+- They cannot merge changes that depend on new versions until those versions are available on PyPI
+- Publishing from `main` ensures the published version matches what's in the repository
+- This prevents dependency resolution failures in downstream applications
+
+**Example workflow:**
+```bash
+# 1. Make changes in a feature branch
+git checkout -b feature/new-adapter
+# ... make changes ...
+git commit -m "Add new adapter"
+
+# 2. Merge to main
+git checkout main
+git merge feature/new-adapter
+
+# 3. Bump version in pyproject.toml (e.g., 0.1.3 → 0.2.0)
+# Edit pyproject.toml: version = "0.2.0"
+git commit -m "Bump version to 0.2.0"
+git push origin main
+
+# 4. Publish to PyPI (must be on main branch)
+just publish
+
+# 5. Now dependent applications can update their dependencies
+# pip install wayfinder-paths==0.2.0
+```
+
 ## 📦 Publishing
 
 Publish to PyPI:
@@ -632,6 +704,12 @@ export PUBLISH_TOKEN="your_pypi_token"
 just publish
 ```
 
+**Important:**
+- ⚠️ **Publishing is only allowed from the `main` branch** - the publish command will fail if run from any other branch
+- ⚠️ **Versions must be unique** - ensure the version in `pyproject.toml` has been bumped and is unique
+- ⚠️ **Follow the order of operations** - see [Versioning](#-versioning) section above for the required workflow
+- ⚠️ **Versions are immutable** - once published, a version cannot be changed or deleted from PyPI
+
 Install the published package:
 
 ```bash

{wayfinder_paths-0.1.2 → wayfinder_paths-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "wayfinder-paths"
-version = "0.1.2"
+version = "0.1.4"
 description = "Wayfinder Path: strategies and adapters"
 readme = "README.md"
 authors = ["Wayfinder <dev@wayfinder.ai>"]
@@ -63,7 +63,7 @@ ignore = [
 known-first-party = ["wayfinder_paths"]
 
 [tool.pytest.ini_options]
-testpaths = ["tests", "wayfinder_paths/vaults"]
+testpaths = ["tests", "wayfinder_paths/strategies/", "wayfinder_paths/adapters/"]
 python_files = ["test_*.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]

{wayfinder_paths-0.1.2 → wayfinder_paths-0.1.4}/wayfinder_paths/CONFIG_GUIDE.md

@@ -6,7 +6,9 @@ This guide explains how to configure your vault strategies for local testing.
 
 ```bash
 # 1. Generate test wallets (required!)
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+# Creates a main wallet (or use 'just create-strategy' which auto-creates wallets)
+just create-wallets
+# Or manually: poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
 
 # 2. Create your config file
 cp wayfinder_paths/config.example.json config.json
@@ -25,11 +27,11 @@ cp wayfinder_paths/config.example.json config.json
     "username": "your_username",      // OPTIONAL: For OAuth authentication
     "password": "your_password",      // OPTIONAL: For OAuth authentication
     "refresh_token": null,            // OPTIONAL: Alternative to username/password
-    "api_key": "sk_live_abc123..."    // OPTIONAL: For service account authentication
+    "api_key": "sk_live_abc123..."    // OPTIONAL: For service account authentication (loaded directly by clients, not stored in UserConfig)
   },
   "system": {
     "api_base_url": "https://wayfinder.ai/api/v1",
-    "api_key": "sk_live_abc123...",   // OPTIONAL: System-level API key (alternative to user.api_key)
+    "api_key": "sk_live_abc123...",   // OPTIONAL: System-level API key (alternative to user.api_key, loaded directly by clients)
     "wallets_path": "wallets.json"    // Path to your generated wallets.json
   },
   "strategy": {
@@ -48,11 +50,13 @@ cp wayfinder_paths/config.example.json config.json
 **Authentication (choose one method):**
 
 **Option 1: Service Account (API Key) - Recommended for Production**
-- `user.api_key` - Your Wayfinder API key for service account authentication
-- OR `system.api_key` - System-level API key (alternative location)
+- `user.api_key` - Your Wayfinder API key for service account authentication (loaded directly by clients from config.json)
+- OR `system.api_key` - System-level API key (alternative location, loaded directly by clients)
 - OR set `WAYFINDER_API_KEY` environment variable
 - OR pass `api_key` parameter to strategy constructor
 
+**Note:** API keys in `config.json` are loaded directly by `WayfinderClient` via `_load_config_credentials()`, not through the `UserConfig` or `SystemConfig` dataclasses. This is intentional to allow flexible credential loading.
+
 **Option 2: Personal Access (OAuth) - For Development**
 - `user.username` - Your Wayfinder backend username
 - `user.password` - Your Wayfinder backend password
@@ -93,24 +97,24 @@ Individual strategies may have their own configuration parameters. Check the str
 Use the built-in script to generate test wallets for local development:
 
 ```bash
-# Generate default and vault wallets (recommended)
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault
+# Generate main wallet (recommended for initial setup)
+poetry run python wayfinder_paths/scripts/make_wallets.py -n 1
 
 # Add additional wallets for multi-account testing
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault -n 3
+poetry run python wayfinder_paths/scripts/make_wallets.py -n 3
 
-# Replace existing wallets
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault --override
+# Create a wallet with a specific label (e.g., for a strategy)
+poetry run python wayfinder_paths/scripts/make_wallets.py --label "my_strategy_name"
 
 # Generate keystore files (for geth/web3 compatibility)
-poetry run python wayfinder_paths/scripts/make_wallets.py --default --vault --keystore-password "your-password"
+poetry run python wayfinder_paths/scripts/make_wallets.py -n 1 --keystore-password "your-password"
 ```
 
 This creates `wallets.json` in the repository root with:
-- **default** wallet - your main wallet for testing
-- Additional unlabeled wallets if specified
+- **main** wallet - your main wallet for testing (labeled "main")
+- Additional wallets with labels if specified
 
-**Note:** Generated wallets are for testing only. Wallet addresses are automatically loaded from `wallets.json` when not explicitly set in config.
+**Note:** Generated wallets are for testing only. Wallet addresses are automatically loaded from `wallets.json` when not explicitly set in config. Strategy-specific wallets are automatically created when you use `just create-strategy "Strategy Name"`.
 
 ## Per-Strategy Wallets
 
@@ -147,7 +151,7 @@ Wallets in `wallets.json` are stored with labels that match strategy directory n
   {
     "address": "0x...",
     "private_key_hex": "...",
-    "label": "default"
+    "label": "main"
   },
   {
     "address": "0x...",
@@ -235,7 +239,7 @@ No code changes are required - existing strategies continue to work.
 To use a custodial wallet provider (e.g., Privy, Turnkey), inject it directly into adapters:
 
 ```python
-from vaults.adapters.evm_transaction_adapter.adapter import EvmTransactionAdapter
+from adapters.evm_transaction_adapter.adapter import EvmTransactionAdapter
 from my_privy_integration import PrivyWalletProvider
 
 # Create your custom wallet provider
@@ -270,7 +274,7 @@ API keys provide service account authentication and are automatically discovered
 
 #### Option A: Strategy Constructor (Programmatic)
 ```python
-from wayfinder_paths.vaults.strategies.stablecoin_yield_strategy.strategy import StablecoinYieldStrategy
+from wayfinder_paths.strategies.stablecoin_yield_strategy.strategy import StablecoinYieldStrategy
 
 strategy = StablecoinYieldStrategy(
     config={...},
@@ -301,10 +305,11 @@ export WAYFINDER_API_KEY="sk_live_abc123..."
 - When a strategy receives an `api_key`, it sets `os.environ["WAYFINDER_API_KEY"]`
 - All clients created by adapters automatically discover the API key from:
   - Constructor parameter (if passed)
-  - `config.json` (via `_load_config_credentials()`)
+  - `config.json` (via `WayfinderClient._load_config_credentials()` which reads `user.api_key` or `system.api_key`)
   - `WAYFINDER_API_KEY` environment variable
 - API keys are included in **all** API requests (including public endpoints) for rate limiting
 - No need to pass API keys explicitly to adapters or clients—they auto-discover it
+- **Note:** API keys in `config.json` are loaded directly by clients, not stored in the `UserConfig` or `SystemConfig` dataclasses
 
 ### 2. Personal Access Authentication (OAuth)