Update documentation

Author: DylanBlakemore

CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.4]
+
+### Changed
+- **Environment Secret Storage**: Reverted to file-based storage for environment secrets
+  - Secrets are now stored in `.initiat/environments/<env>/secrets.env` files
+  - The `active` symlink points to the currently active environment directory
+  - Direnv automatically loads secrets from `.initiat/active/secrets.env`
+  - Removed in-memory loading approach that required `eval` commands
+  - Improved reliability and compatibility with direnv integration
+  - Secrets are stored in plaintext locally (for direnv compatibility) but remain encrypted on Initiat servers
+  - Files are protected with restrictive permissions (600) and automatically gitignored
+
+### Fixed
+- **Direnv Integration**: Fixed environment variable loading with direnv
+  - `.envrc` now uses `dotenv` to load secrets from the active environment's `secrets.env` file
+  - Environment variables now load automatically when switching environments
+  - No longer requires manual `eval` commands or shell function wrappers
+
 ## [0.7.3] - 2025-11-15
 
 ### Added

docs/COMMANDS.md

@@ -665,6 +665,8 @@ Switch to a specific environment and update the active environment tracking.
 - Updates the active environment tracking
 - Creates environment-specific directory if needed
 - Updates symlinks (Unix) or files (Windows) for environment tracking
+- Regenerates `.envrc` file for direnv integration
+- Triggers direnv reload to load environment variables
 - Shows confirmation of the switch
 
 **Examples:**
@@ -681,13 +683,14 @@ initiat env switch development
 
 **Output:**
 ```
-🔄 Switching to environment 'production'...
-✅ Switched to environment 'production'
-
-💡 Current environment: production
-💡 Sync secrets with: initiat env sync
+→ setting active -> environments/production
+→ refreshing .envrc
+→ direnv reload
+Switched to "production"
 ```
 
+**Note:** After switching, direnv will automatically load the environment variables from the local `secrets.env` file. Make sure to run `initiat env sync` first to download the latest secrets.
+
 ### `initiat env current`
 
 Show the currently active environment.
@@ -714,27 +717,37 @@ initiat env current
   • Sync secrets: initiat env sync
 ```
 
-### `initiat env sync`
+### `initiat env sync [--env <slug>]`
 
-Sync secrets from the remote project to the local environment.
+Sync secrets from the remote project to the local environment(s).
+
+**Options:**
+- `--env <slug>`: Sync a specific environment (optional, syncs all environments if not specified)
 
 **What it does:**
-- Fetches all secrets from the remote project
-- Stores them securely in the local environment directory
+- Fetches all secrets from the remote project for the specified environment(s)
+- Decrypts secrets using your local project key
+- Stores them securely in the local environment directory as `secrets.env`
 - Updates sync timestamps
 - Shows summary of synced secrets
 
 **Examples:**
 ```bash
 # Sync secrets to current environment
 initiat env sync
+
+# Sync secrets to a specific environment
+initiat env sync --env production
+
+# Sync all environments
+initiat env sync
 ```
 
 **Output:**
 ```
 🔄 Syncing secrets to environment 'production'...
 📡 Fetching secrets from remote project...
-🔒 Storing secrets securely in local environment...
+🔒 Decrypting and storing secrets securely...
 ✅ Synced 5 secrets to environment 'production'
 
 Synced secrets:
@@ -745,9 +758,15 @@ Synced secrets:
   • SMTP_PASSWORD
 
 💡 Environment is now up to date
-💡 Use 'initiat env current' to verify active environment
+💡 Switch to this environment with: initiat env switch production
 ```
 
+**Important:** Secrets are stored in plaintext in the local `secrets.env` file, but they are:
+- Encrypted when stored on Initiat servers
+- Stored locally with restrictive file permissions (600 - owner read/write only)
+- Automatically excluded from git via `.gitignore`
+- Only accessible to processes that can read the file (your user account)
+
 ### `initiat env unset`
 
 Clear the currently active environment and reload direnv.
@@ -789,35 +808,59 @@ The CLI creates the following directory structure for environment management:
 │   │   └── secrets.env
 │   └── development/
 │       └── secrets.env
-└── active
+└── active -> environments/production  (symlink on Unix, file on Windows)
 ```
 
+The `active` symlink (or file on Windows) points to the currently active environment directory. This allows direnv to automatically load the correct `secrets.env` file.
+
 ### Direnv Integration
 
 The CLI automatically generates `.envrc` files for seamless integration with direnv:
 
-**Generated `.envrc` content:**
+**Generated `.envrc` content (Unix):**
 ```bash
-# Generated by initiat env init
-# This file loads environment variables from the active environment
+if [ -e ".initiat/active" ]; then
+  dotenv ".initiat/active/secrets.env"
+  export INITIAT_ENV=$(basename "$(readlink .initiat/active 2>/dev/null || cat .initiat/active)")
+fi
+```
 
-if [ -f .initiat/environments/*/secrets.env ]; then
-  dotenv .initiat/environments/*/secrets.env
+**Generated `.envrc` content (Windows):**
+```bash
+if [ -e ".initiat/active" ]; then
+  dotenv ".initiat/active/secrets.env"
+  export INITIAT_ENV=$(cat .initiat/active)
 fi
 ```
 
+**How it works:**
+1. When you run `initiat env switch <env>`, it creates/updates the `.initiat/active` symlink
+2. The `.envrc` file checks if `.initiat/active` exists
+3. If it exists, direnv loads the `secrets.env` file from the active environment directory
+4. The `INITIAT_ENV` variable is set to the current environment name
+5. All secrets are automatically loaded into your shell environment
+
 **Benefits:**
 - Automatic environment variable loading when entering the project directory
 - Cross-platform compatibility (Unix and Windows)
-- Secure local storage of environment-specific secrets
+- Secure local storage of environment-specific secrets (encrypted on disk)
 - Integration with existing development workflows
+- No need to manually export variables or use eval
 
 ### Security Features
 
 - **Secure Storage**: All environment files use 600 permissions (owner read/write only)
-- **Git Integration**: Automatic `.gitignore` management to prevent accidental commits
+- **Git Integration**: Automatic `.gitignore` management to prevent accidental commits (`.initiat/active` is gitignored)
 - **Path Validation**: Protection against directory traversal vulnerabilities
 - **Cross-Platform**: Symlink support on Unix, file-based tracking on Windows
+- **Local Encryption**: While secrets are stored in plaintext locally for direnv compatibility, they remain encrypted on Initiat servers and require your device's private key to decrypt
+
+**Security Considerations:**
+- Secrets are stored in plaintext in `secrets.env` files locally to work with direnv
+- Files are protected by restrictive permissions (600) and excluded from git
+- If your device is compromised, an attacker with keychain access could decrypt secrets
+- This is the same risk level as in-memory storage (both require device compromise)
+- For maximum security, consider using `initiat secret get` to fetch secrets on-demand instead of syncing
 
 ## Secret Management