updates

Author: jszobody

docs/.vitepress/config.mjs

@@ -38,7 +38,6 @@ export default defineConfig({
           items: [
             { text: 'Vaults', link: '/guide/vaults' },
             { text: 'Stages', link: '/guide/stages' },
-            { text: 'Contexts', link: '/guide/contexts' },
             { text: 'Templates', link: '/guide/templates' }
           ]
         },

docs/guide/configuration.md

@@ -17,10 +17,9 @@ This command will:
 - Set up the basic directory structure for vault configurations
 
 You'll be prompted for:
-- **Project name**: A human-readable name for your project
-- **Namespace**: A unique identifier (letters, numbers, underscores, hyphens)
+- **Project name**: A friendly name for your project
+- **Namespace**: A unique identifier (typically a slug of your project name) used as the prefix for secrets
 - **Stages**: Environment names (e.g., `development`, `staging`, `production`)
-- **Default vault** (optional): The vault to use when none is specified
 
 ## Configuration Structure
 
@@ -45,8 +44,8 @@ The settings file contains your project configuration:
   "stages": ["development", "staging", "production"],
   "default_vault": "local",
   "version": "1.0",
-  "created_at": "2024-01-01T12:00:00+00:00",
-  "updated_at": "2024-01-01T12:00:00+00:00"
+  "created_at": "2025-01-01T12:00:00+00:00",
+  "updated_at": "2025-01-01T12:00:00+00:00"
 }
 ```
 

docs/guide/contexts.md

@@ -1,34 +1,24 @@
 # Introduction
 
-Keep is a toolkit for collaborative, secure management of secrets across applications, environments, and teams. It provides a consistent interface for managing secrets whether they're stored locally during development or in cloud services like AWS SSM Parameter Store or AWS Secrets Manager in production.
+Keep is a PHP toolkit for collaborative, secure management of secrets across applications, environments, and teams. It provides a consistent interface for managing secrets whether they're stored locally during development or in cloud services like AWS SSM Parameter Store or AWS Secrets Manager in production.
 
 ## What is Keep?
 
-Keep addresses the common challenge of managing environment variables and secrets across different stages of development and deployment. Instead of passing around `.env` files through insecure channels, Keep provides:
+Keep addresses the common challenge of managing environment variables and secrets across different stages of development and deployment, between team members and in deployment pipelines. 
 
 - **Centralized Secret Storage**: Store secrets in various backends (local, AWS SSM, AWS Secrets Manager)
 - **Environment Staging**: Organize secrets by stages (development, staging, production)
 - **Template-Based Generation**: Generate configuration files from templates with proper secret injection
 - **Team Collaboration**: Share access to secrets without exposing their values
 - **Laravel Integration**: Seamless integration with Laravel applications
 
-## Key Concepts
+## Vaults Supported
+
+Keep uses a driver-based architecture to support multiple vaults for storing secrets. Currently, it supports:
 
-### Vaults
-Vaults are storage backends for your secrets. Keep supports:
-- **Local Vault**: File-based storage for development
 - **AWS SSM**: AWS Systems Manager Parameter Store
 - **AWS Secrets Manager**: AWS managed secrets service
 
-### Stages
-Stages represent different environments like `development`, `staging`, and `production`. Each vault can store secrets for multiple stages, allowing you to promote secrets through your deployment pipeline.
-
-### Contexts
-A context combines a vault and stage, written as `vault:stage` (e.g., `myapp:production`). This tells Keep exactly where to find or store a secret.
-
-### Templates
-Templates are configuration files with placeholders that get replaced with actual secret values. This allows you to generate `.env` files, configuration files, or any text-based configuration.
-
 ## Getting Started
 
 Ready to start using Keep? Head over to the [Installation Guide](./installation) to set up Keep in your project.

docs/guide/index.md

@@ -2,40 +2,44 @@
 
 Keep can be installed globally as a standalone CLI tool or as a Composer dependency in your Laravel project.
 
-## Global Installation (Recommended)
+## Project Installation
 
-Install Keep globally using Composer:
+It's usually best to install Keep in your local project:
 
 ```bash
-composer global require stechstudio/keep
+composer require --dev stechstudio/keep
 ```
 
-Make sure your global Composer vendor bin directory is in your `$PATH`:
+Then run Keep commands using:
 
 ```bash
-export PATH="$PATH:$HOME/.composer/vendor/bin"
+./vendor/bin/keep [command]
 ```
 
-Add this line to your shell profile (`.bashrc`, `.zshrc`, etc.) to make it permanent.
+You might appreciate having an alias in your shell profile to make it easier:
+
+```bash
+alias keep="./vendor/bin/keep"
+```
 
-## Project-Specific Installation
+## Global Installation (Optional)
 
-If you prefer to install Keep per project:
+If you don't plan to use any framework integration, you can install Keep globally:
 
 ```bash
-composer require --dev stechstudio/keep
+composer global require stechstudio/keep
 ```
 
-Then run Keep commands using:
+Make sure your global Composer vendor bin directory is in your `$PATH`:
 
 ```bash
-./vendor/bin/keep [command]
-```
+export PATH="$PATH:$HOME/.composer/vendor/bin"
+````
 
-You might enjoy having an alias in your shell profile to make it easier:
+Then run Keep commands using:
 
 ```bash
-alias keep="./vendor/bin/keep"
+keep [command]
 ```
 
 ## Laravel Integration (Optional)
@@ -44,10 +48,7 @@ If you're using Keep with a Laravel application, you can publish the configurati
 
 ```bash
 # Publish configuration
-php artisan vendor:publish --provider="STS\Keep\KeepServiceProvider"
-
-# Configure Laravel integration
-keep configure --laravel
+php artisan vendor:publish --tag=keep-config
 ```
 
 ## Verify Installation

docs/guide/installation.md

@@ -1,10 +1,235 @@
 # AWS SSM Parameter Store
 
-*Documentation coming soon*
+AWS Systems Manager Parameter Store is a powerful, cost-effective solution for storing configuration data and secrets. It provides secure, hierarchical storage for configuration data management and secrets management.
 
-This page will cover the AWS SSM vault driver, including:
+## Why Choose SSM Parameter Store?
 
-- Parameter Store integration
-- Configuration and setup
-- Security and encryption
-- Cost considerations
+**Cost-Effective**: Standard parameters are free (up to 10,000), with Advanced parameters costing only $0.05 per 10,000 API interactions.
+
+**Hierarchical Organization**: Natural path-based organization (`/myapp/production/DB_PASSWORD`) that aligns perfectly with Keep's namespace system.
+
+**Encryption Built-In**: Native integration with AWS KMS for transparent encryption of sensitive values.
+
+**Fine-Grained Access Control**: Leverage AWS IAM for precise control over who can access which parameters in which environments.
+
+**Version History**: Automatic versioning of parameter changes with built-in rollback capabilities.
+
+**Cross-Service Integration**: Native integration with EC2, ECS, Lambda, and other AWS services.
+
+## Adding an SSM Vault
+
+Use the `vault:add` command to configure a new SSM vault:
+
+```bash
+keep vault:add
+```
+
+You'll be prompted for:
+
+**Driver**: Select "AWS Systems Manager Parameter Store" from the available vaults
+
+**Slug**: A friendly slug for this vault (e.g., `myapp-ssm`) that will be used in template placeholders
+
+**Friendly Name**: A reference name for the vault (e.g., `MyApp SSM Vault`)
+
+**AWS Region**: The AWS region where your parameters will be stored (e.g., `us-east-1`)
+
+**Parameter Prefix**: Optional base path for all parameters. If you specify `myapp`, your parameters will be stored as `/myapp/[namespace]/[stage]/[key]`
+
+**KMS Key ID**: Optional. Leave empty to use AWS managed key (`alias/aws/ssm`), or specify a custom KMS key for additional security
+
+## IAM Permission Scenarios
+
+Let's look at how to set up IAM permissions for different roles in your organization when using AWS SSM Parameter Store with Keep. These examples assume a namespace of "myapp" and use the default KMS key for SSM.
+
+### Full Developer Access
+
+For developers who need complete access to manage secrets across all environments in `myapp`:
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": [
+                "ssm:GetParameter",
+                "ssm:GetParameters",
+                "ssm:GetParametersByPath",
+                "ssm:GetParameterHistory",
+                "ssm:PutParameter",
+                "ssm:DeleteParameter",
+                "ssm:LabelParameterVersion",
+                "ssm:UnlabelParameterVersion"
+            ],
+            "Resource": "arn:aws:ssm:*:*:parameter/myapp/*"
+        },
+        {
+            "Effect": "Allow",
+            "Action": [
+                "kms:Decrypt",
+                "kms:Encrypt",
+                "kms:GenerateDataKey"
+            ],
+            "Resource": [
+                "arn:aws:kms:*:*:alias/aws/ssm"
+            ]
+        }
+    ]
+}
+```
+
+### Environment-Specific Developer Access
+
+For developers who should only access development and staging environments:
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": [
+                "ssm:GetParameter",
+                "ssm:GetParameters",
+                "ssm:GetParametersByPath",
+                "ssm:PutParameter",
+                "ssm:DeleteParameter",
+                "ssm:GetParameterHistory"
+            ],
+            "Resource": [
+                "arn:aws:ssm:*:*:parameter/myapp/development/*",
+                "arn:aws:ssm:*:*:parameter/myapp/staging/*"
+            ]
+        },
+        {
+            "Effect": "Allow",
+            "Action": [
+                "kms:Decrypt",
+                "kms:Encrypt",
+                "kms:GenerateDataKey"
+            ],
+            "Resource": [
+                "arn:aws:kms:*:*:alias/aws/ssm"
+            ]
+        }
+    ]
+}
+```
+
+### Production Deployment (Read-Only)
+
+For production deployment processes that only need to read production secrets:
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": [
+                "ssm:GetParameter",
+                "ssm:GetParameters",
+                "ssm:GetParametersByPath"
+            ],
+            "Resource": "arn:aws:ssm:*:*:parameter/myapp/production/*"
+        },
+        {
+            "Effect": "Allow",
+            "Action": [
+                "kms:Decrypt"
+            ],
+            "Resource": [
+                "arn:aws:kms:*:*:alias/aws/ssm"
+            ]
+        }
+    ]
+}
+```
+
+## Parameter Organization
+
+With the example configuration above, Keep will organize your parameters like this:
+
+```
+/myapp/
+├── development/
+│   ├── DB_PASSWORD
+│   ├── API_KEY
+│   └── NIGHTWATCH_TOKEN
+├── staging/
+│   ├── DB_PASSWORD
+│   ├── API_KEY
+│   └── NIGHTWATCH_TOKEN
+└── production/
+    ├── DB_PASSWORD
+    ├── API_KEY
+    └── NIGHTWATCH_TOKEN
+```
+
+## Security Best Practices
+
+**Use SecureString Type**: Keep automatically creates parameters as `SecureString` when you mark secrets as secure, ensuring they're encrypted at rest.
+
+**Custom KMS Keys**: For highly sensitive applications, use a custom KMS key instead of the AWS managed key for additional control.
+
+**Least Privilege Access**: Grant only the minimum IAM permissions needed for each role.
+
+**Parameter Naming**: Use consistent, descriptive parameter names that align with your application's configuration.
+
+**Regular Rotation**: Leverage Keep's versioning support to regularly rotate sensitive credentials.
+
+## Cost Considerations
+
+**Standard Parameters**: Free for up to 10,000 parameters, then $0.05 per 10,000 API interactions
+
+**Advanced Parameters**: $0.05 per 10,000 API interactions (allows larger values and parameter policies)
+
+**Storage**: No additional storage costs
+
+**Typical Usage**: Most applications will stay within the free tier for parameter storage, with minimal API interaction costs.
+
+## Common Usage Patterns
+
+### Basic Secret Management
+```bash
+# Set a production database password
+keep set DB_PASSWORD --stage=production
+
+# Retrieve for verification
+keep get DB_PASSWORD --stage=production
+
+# Export for deployment
+keep export --stage=production --output=.env
+```
+
+### Cross-Environment Workflows
+```bash
+# Copy staging secrets to production
+keep copy DB_PASSWORD --from=ssm:staging --to=ssm:production
+
+# Compare environments
+keep diff --stage=staging,production
+```
+
+### Template-Based Deployment
+```bash
+# Use secrets in templates
+keep merge env.template --stage=production --vault=ssm --output=.env
+```
+
+## Troubleshooting
+
+**Access Denied Errors**: Verify your IAM permissions include both SSM and KMS actions for the correct resource paths.
+
+**Parameter Not Found**: Check your parameter prefix and namespace configuration match your expected path structure.
+
+**Encryption Issues**: Ensure your IAM role has access to the KMS key being used (either AWS managed or custom).
+
+**Region Mismatch**: Verify you're operating in the same AWS region where your parameters are stored.
+
+## Next Steps
+
+- [AWS Secrets Manager](./aws-secrets-manager) - For more advanced secret rotation features
+- [Template System](../templates) - Learn how to use SSM parameters in templates
+- [Multi-Environment Setup](../../examples/multi-environment) - Best practices for organizing environments