feat: Enhance AWS SSM integration and add unit tests for storage functionality

- Updated `get_ssm_parameter` to accept optional AWS profile and region parameters.
- Introduced a new `tests/test_storage.py` file containing comprehensive unit tests for the storage backend, covering timestamp parsing, configuration resolution, and S3/SSM interactions.
- Implemented the `storage.py` module to manage environment store configurations, including reading and writing to S3 and SSM, with dual-backend support for reading the latest values.
- Added functions for handling AWS CLI commands and managing configurations, ensuring robust error handling and user prompts for configuration creation.

Author: nalbam

ARCHITECTURE.md

@@ -38,6 +38,7 @@ toast-cli/
           ├── prompt_plugin.py
           ├── region_plugin.py
           ├── ssm_plugin.py
+          ├── storage.py
           └── utils.py
 ```
 
@@ -102,10 +103,10 @@ Each plugin:
 | am | Show AWS caller identity |
 | cdw | Navigate to workspace directories |
 | ctx | Manage Kubernetes contexts (switch, add EKS clusters, delete) |
-| dot | Manage .env.local files with AWS SSM integration |
+| dot | Manage .env.local files with S3 env-store (SSM transition) |
 | env | Manage AWS profiles |
 | git | Manage Git repositories (clone, branch, pull, push, rm, mirror) |
-| prompt | Manage .prompt.md files with AWS SSM integration |
+| prompt | Manage .prompt.md files with S3 env-store (SSM transition) |
 | region | Set AWS region |
 | ssm | AWS SSM Parameter Store operations (get, put, delete, list) |
 
@@ -127,21 +128,34 @@ Each plugin:
 - Interactive selection of contexts and clusters
 
 #### DotPlugin (dot)
-- Manages .env.local files with AWS SSM Parameter Store
-- Default behavior: `sync` (compare local/remote, show diff, choose upload/download)
+- Manages .env.local files via the S3 env-store (`storage.py`)
+- Default behavior: `sync` (compare local/store, show diff, choose upload/download)
 - Commands: `sync` (default), `up` (upload), `down`/`dn` (download), `ls` (list)
-- Uploads/downloads environment variables as SecureString
-- SSM path: `/toast/local/{org}/{project}/env-local`
+- S3 key: `local/{org}/{project}/env-local` (SSE-KMS)
 - Validates workspace path structure (`workspace/github.com/{org}/{project}`)
 
 #### PromptPlugin (prompt)
-- Manages .prompt.md files with AWS SSM Parameter Store
-- Default behavior: `sync` (compare local/remote, show diff, choose upload/download)
+- Manages .prompt.md files via the S3 env-store (`storage.py`)
+- Default behavior: `sync` (compare local/store, show diff, choose upload/download)
 - Commands: `sync` (default), `up` (upload), `down`/`dn` (download), `ls` (list)
-- Uploads/downloads prompt files as SecureString
-- SSM path: `/toast/local/{org}/{project}/prompt-md`
+- S3 key: `local/{org}/{project}/prompt-md` (SSE-KMS)
 - Validates workspace path structure (`workspace/github.com/{org}/{project}`)
 
+#### Env-store backend (storage.py)
+- Shared storage layer for the dot/prompt plugins
+- Dual-backend during SSM → S3 transition: reads check both S3 and SSM and use
+  the newest copy (ties prefer S3); writes always go to S3
+- SSM is a read-only fallback and is harvested into S3 on the next upload
+- All access uses a dedicated AWS profile (`TOAST_ENV_STORE_PROFILE`, default
+  `{username}-admin`)
+- Profile defaults to the OS username + `-admin`; bucket defaults to
+  `env-store-{account-id}` of that profile (account id via
+  `aws sts get-caller-identity`)
+- Configurable via env vars (`TOAST_ENV_STORE_PROFILE`, `TOAST_ENV_STORE_BUCKET`,
+  `TOAST_ENV_STORE_KMS_KEY`, `TOAST_ENV_STORE_REGION`) or the config file
+  `~/.config/toast/config` (`KEY=VALUE`, created on first run by prompting the
+  user); precedence: env var > config file > default
+
 #### EnvPlugin (env)
 - Manages AWS profiles from `~/.aws/credentials`
 - Interactive selection of profiles

CLAUDE.md

@@ -73,13 +73,14 @@ class MyPlugin(BasePlugin):
 ### Key Components
 - **Helpers** (`toast/helpers.py`): Version handling, custom Click classes for UI
 - **Plugin Utils** (`toast/plugins/utils.py`): Common utilities for subprocess execution, fzf integration
+- **Env-store** (`toast/plugins/storage.py`): S3/SSM dual-backend storage for dot/prompt (newest-wins reads, S3 writes)
 - **Dynamic Loading**: No hardcoded plugin imports - all plugins discovered at runtime
 
 ### Plugin Categories
 - **AWS plugins**: `am_plugin.py` (identity), `env_plugin.py` (profiles), `region_plugin.py` (regions), `ssm_plugin.py` (SSM Parameter Store)
 - **Kubernetes**: `ctx_plugin.py` (context management)
 - **Git**: `git_plugin.py` (repository operations: clone, branch, pull, push, rm)
-- **Environment**: `dot_plugin.py` (SSM integration for .env.local files), `prompt_plugin.py` (SSM integration for .prompt.md files)
+- **Environment**: `dot_plugin.py` (.env.local files), `prompt_plugin.py` (.prompt.md files), backed by `storage.py` (S3 env-store with SSM transition)
 - **Navigation**: `cdw_plugin.py` (workspace directory navigation)
 
 ## Adding New Plugins
@@ -127,36 +128,61 @@ When working on git_plugin.py:
 - Handle subprocess calls properly - avoid mixing `capture_output=True` with explicit `stdout`/`stderr`
 - Supported commands: `clone` (cl), `rm`, `branch` (b), `pull` (p), `push` (ps) (with optional flags like `-b`, `-t`, `-r`, `-m`/`--mirror`)
 
-### SSM Parameter Store Integration
+### Env-store Integration (S3 with SSM transition)
 
-The `dot` and `prompt` plugins use AWS SSM Parameter Store for secure file storage:
+The `dot` and `prompt` plugins store secure files in an S3 env-store bucket.
+The backend logic lives in `toast/plugins/storage.py`; the plugins themselves
+are thin wrappers that call `run_file_sync(kind, filename, command)`.
 
 **Storage structure**:
 ```
-/toast/local/{org}/{project}/env-local    # DotPlugin
-/toast/local/{org}/{project}/prompt-md    # PromptPlugin
+s3://{bucket}/local/{org}/{project}/env-local    # DotPlugin (kind=env-local)
+s3://{bucket}/local/{org}/{project}/prompt-md    # PromptPlugin (kind=prompt-md)
+
+/toast/local/{org}/{project}/{kind}              # legacy SSM (read-only fallback)
 ```
 
+**Transition semantics** (`storage.store_read` / `store_write`):
+- Reads check both S3 and SSM and use whichever copy is newest (by
+  `LastModified`); ties prefer S3
+- Writes always go to S3 (the bucket is the source of truth)
+- SSM copies are never written; they go stale and are harvested into S3 on the
+  next upload (`up`, or choosing upload in `sync`)
+
+**Configuration** (`storage.resolve_config`) — precedence: environment variable
+> config file > built-in default. The config file `~/.config/toast/config`
+(`KEY=VALUE`) is created on first run by prompting the user for values
+(`prompt_and_create_config`); skipped in non-interactive sessions.
+
+| Env variable | Config key | Default |
+|--------------|------------|---------|
+| `TOAST_ENV_STORE_PROFILE` | `ENV_STORE_PROFILE` | `{username}-admin` (`default_profile`) |
+| `TOAST_ENV_STORE_BUCKET` | `ENV_STORE_BUCKET` | `env-store-{account-id}` of the profile (`default_bucket`, via STS) |
+| `TOAST_ENV_STORE_KMS_KEY` | `ENV_STORE_KMS_KEY` | bucket/account default KMS key |
+| `TOAST_ENV_STORE_REGION` | `ENV_STORE_REGION` | profile's region |
+
 **Commands**:
 | Command | Description |
 |---------|-------------|
 | (none) | Default: same as `sync` |
-| `sync` | Compare local and SSM, then choose action (upload/download) |
-| `up` | Upload local file to SSM |
-| `down`/`dn` | Download from SSM to local |
-| `ls` | List all parameters in SSM |
+| `sync` | Compare local and env-store (newest), then choose action |
+| `up` | Upload local file to env-store (S3) |
+| `down`/`dn` | Download newest from env-store to local |
+| `ls` | List entries across S3 + SSM with current source |
 
 **Sync command features**:
-- Compares local file content with SSM parameter value
-- Displays SHA256 hash (first 12 chars) for both versions
+- Compares local file content with the newest env-store copy
+- Displays SHA256 hash (first 12 chars) for local, S3, and SSM, plus the
+  current (newest) source
 - Shows unified diff when contents differ
 - Interactive selection via fzf: Upload / Download / Cancel
 - Handles cases: identical, different, local_only, remote_only
 
 **Common patterns**:
 - Validate workspace path: `workspace/github.com/{org}/{project}`
-- Store as SecureString type for encryption
-- Use temporary files for large content uploads
+- All AWS calls use the env-store profile via `storage._aws()`
+- Write S3 objects with `--sse aws:kms`
+- Use temporary files for content upload/download
 - Include confirmation prompts before overwriting files
 
 ## Project Code Guidelines

README.md

@@ -24,7 +24,7 @@ Python-based CLI utility with plugin architecture for AWS, Kubernetes, and Git o
 * **Git**: Repository management (clone, branch, pull, push, rm, mirror), organization-specific GitHub hosts
 * **Workspace**: Directory navigation, environment file management (.env.local, .prompt.md)
 * **Interface**: FZF-powered interactive menus, formatted output with Rich
-* **Security**: AWS SSM SecureString storage for sensitive files
+* **Security**: S3 env-store with SSE-KMS for sensitive files (SSM fallback during transition)
 
 ## Architecture
 
@@ -94,16 +94,16 @@ toast ctx                  # Switch contexts
 # Select [Del...] to delete contexts (individual or all)
 
 # Environment Files (.env.local)
-toast dot                  # Compare local and SSM, choose action (default: sync)
-toast dot up               # Upload .env.local to SSM
-toast dot down             # Download .env.local from SSM (alias: dn)
-toast dot ls               # List all .env.local files in SSM
+toast dot                  # Compare local and env-store, choose action (default: sync)
+toast dot up               # Upload .env.local to env-store (S3)
+toast dot down             # Download .env.local from env-store (alias: dn)
+toast dot ls               # List all .env.local files in env-store (S3 + SSM)
 
 # Prompt Files (.prompt.md)
-toast prompt               # Compare local and SSM, choose action (default: sync)
-toast prompt up            # Upload .prompt.md to SSM
-toast prompt down          # Download .prompt.md from SSM (alias: dn)
-toast prompt ls            # List all .prompt.md files in SSM
+toast prompt               # Compare local and env-store, choose action (default: sync)
+toast prompt up            # Upload .prompt.md to env-store (S3)
+toast prompt down          # Download .prompt.md from env-store (alias: dn)
+toast prompt ls            # List all .prompt.md files in env-store (S3 + SSM)
 
 # SSM Parameter Store
 toast ssm                  # Interactive mode: browse and select parameters
@@ -183,16 +183,50 @@ Host myorg-github.com
 - Automatic host detection based on workspace location
 - Seamless switching between GitHub accounts
 
-### AWS SSM Storage Paths
+### Env-store (S3) Storage Paths
 
-Toast-cli stores files in AWS SSM Parameter Store with the following structure:
+The `dot` and `prompt` plugins store files in the S3 env-store bucket. During
+the transition from AWS SSM Parameter Store, reads check both backends and use
+whichever copy is newest; writes always go to S3 (the bucket is the source of
+truth), and SSM copies become stale and are harvested into S3 on the next
+upload.
 
 ```
-/toast/local/{org}/{project}/env-local     # .env.local files
-/toast/local/{org}/{project}/prompt-md     # .prompt.md files
+s3://env-store-{account-id}/local/{org}/{project}/env-local   # .env.local files
+s3://env-store-{account-id}/local/{org}/{project}/prompt-md   # .prompt.md files
+
+/toast/local/{org}/{project}/env-local     # legacy SSM (read-only fallback)
+/toast/local/{org}/{project}/prompt-md     # legacy SSM (read-only fallback)
 ```
 
-Files are stored as SecureString type for encryption at rest.
+S3 objects are written with SSE-KMS encryption. All env-store access uses a
+dedicated AWS profile so it is decoupled from your current default profile.
+
+**Configuration** — precedence: environment variable > config file > default.
+
+Environment variables:
+
+```bash
+TOAST_ENV_STORE_PROFILE   # default: {username}-admin
+TOAST_ENV_STORE_BUCKET    # default: env-store-{account-id of the profile}
+TOAST_ENV_STORE_KMS_KEY   # default: bucket/account default KMS key
+TOAST_ENV_STORE_REGION    # default: profile's region
+```
+
+The profile defaults to your OS username + `-admin`, and the bucket defaults to
+`env-store-` + the AWS account id of that profile (looked up via
+`aws sts get-caller-identity`).
+
+Config file `~/.config/toast/config` (`KEY=VALUE` format). On first run, if it
+is missing, toast prompts for the values and saves them (interactive sessions
+only):
+
+```
+ENV_STORE_BUCKET=env-store-{account-id}
+ENV_STORE_PROFILE={username}-admin
+ENV_STORE_KMS_KEY=
+ENV_STORE_REGION=
+```
 
 ## Creating Plugins
 

VERSION

@@ -1 +1 @@
-v4.0.0.dev0
+v4.1.0.dev0