Document keep iam command and onboarding flow updates

- Add full keep iam reference to CLI docs
- Update init docs to show complete setup flow (vault, workspace, IAM)
- Document shell auto-init on first run
- Add keep iam callouts to SSM and Secrets Manager IAM sections
- Update AWS authentication docs with keep iam generation
- Update vault:add docs to mention IAM offer

Author: jszobody

docs/guide/aws-authentication.md

@@ -204,7 +204,28 @@ deploy:
 
 ## IAM Permissions
 
-After setting up authentication, you need to configure IAM permissions for the AWS services Keep will access:
+After setting up authentication, you need to configure IAM permissions for the AWS services Keep will access.
+
+### Generate a Policy with `keep iam`
+
+The easiest way to get the right IAM policy is to let Keep generate it for you:
+
+```bash
+# Generate policy scoped to your workspace (active vaults and environments)
+keep iam
+
+# Generate policy for all vaults and environments
+keep iam --all
+
+# Generate and open the AWS IAM console
+keep iam --browser
+```
+
+The generated policy is scoped to your namespace, vault driver, region, and workspace environments — no manual editing needed.
+
+### Manual Policy Setup
+
+For manual configuration or custom policies, see the detailed IAM examples:
 
 - **For AWS SSM Parameter Store**: See [SSM IAM Permissions](/guide/vaults/aws-ssm#iam-permissions)
 - **For AWS Secrets Manager**: See [Secrets Manager IAM Permissions](/guide/vaults/aws-secrets-manager#iam-permissions)

docs/guide/cli/reference.md

@@ -4,12 +4,21 @@ Complete reference for all Keep CLI commands with their options and usage exampl
 
 ## `keep init`
 
-Initialize Keep settings and vault connections.
+Initialize Keep settings and vault connections. Walks you through the complete setup process.
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `--no-interaction` | boolean | `false` | Run without prompts using defaults |
 
+**Setup flow:**
+1. Application name and namespace
+2. Environment selection (local, staging, production, custom)
+3. First vault configuration (driver, region, KMS key)
+4. Workspace setup (select your active vaults and environments)
+5. IAM policy generation (ready-to-use JSON for AWS)
+
+Each step after vault setup is optional — you can skip and configure later with `keep vault:add`, `keep workspace`, or `keep iam`.
+
 **Examples:**
 ```bash
 # Interactive initialization
@@ -32,7 +41,8 @@ keep vault:add
 - Select vault driver (`ssm` or `secretsmanager`)
 - Choose a vault slug (short identifier for templates)
 - Configure driver-specific settings (region, KMS key, etc.)
-- Automatic permission testing after setup
+- Automatic credential check and permission testing
+- Option to generate IAM policy JSON for the new vault
 
 ## `keep vault:list`
 
@@ -146,6 +156,43 @@ keep workspace
 - Filtering is cosmetic only - doesn't affect permissions or access
 - Useful for focusing on specific environments or reducing clutter
 
+## `keep iam`
+
+Generate a ready-to-use IAM policy JSON based on your configured vaults, namespace, and workspace.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--vault` | string | *all workspace vaults* | Generate policy for a specific vault only |
+| `--all` | boolean | `false` | Include all vaults and environments, ignoring workspace |
+| `--browser` | boolean | `false` | Open the AWS IAM console to create a policy |
+
+**Examples:**
+```bash
+# Generate policy scoped to your workspace
+keep iam
+
+# Generate policy for all vaults and environments
+keep iam --all
+
+# Generate for a specific vault
+keep iam --vault=ssm
+
+# Generate and open the IAM console
+keep iam --browser
+```
+
+**Output:**
+- Shows a summary of namespace, environments, and vaults included
+- Outputs a complete IAM policy JSON document ready to paste into the AWS console
+- Policy is scoped to your workspace by default (active vaults and environments)
+
+**Notes:**
+- The generated policy includes all permissions needed for Keep operations (read, write, list, delete, history)
+- SSM policies use resource ARN scoping per environment
+- Secrets Manager policies use tag-based access control with environment conditions
+- Use `--all` when generating a policy for an admin or CI/CD role that needs access to everything
+- This command is offered during `keep init` and `keep vault:add` setup flows
+
 ## `keep verify`
 
 Verify vault configuration, authentication, and permissions by running a comprehensive test matrix.
@@ -371,6 +418,8 @@ Start an interactive shell for Keep commands with persistent context.
 | `--env` | string | *first configured env* | Initial env to use |
 | `--vault` | string | *default vault* | Initial vault to use |
 
+**First Run:** If Keep hasn't been initialized yet, running `keep shell` (or just `keep`) will automatically launch the setup wizard (`keep init`).
+
 ### Shell Mode Features
 
 The interactive shell provides:

docs/guide/shell/index.md

@@ -10,6 +10,8 @@ Launch the interactive shell with the `shell` command:
 keep shell
 ```
 
+If Keep hasn't been initialized yet, running `keep shell` (or just `keep` with no arguments) will automatically walk you through the setup process first.
+
 You can also start with a specific vault and env:
 
 ```bash

docs/guide/vaults/aws-secrets-manager.md

@@ -38,6 +38,8 @@ You'll be prompted for:
 
 ## IAM Permission Scenarios
 
+> **Quick start:** Run `keep iam` to generate a ready-to-use IAM policy based on your actual configuration. The examples below are for reference and custom setups.
+
 Keep uses **tag-based permissions** for Secrets Manager to provide fine-grained access control. All secrets are tagged with `ManagedBy=Keep`, `Namespace={namespace}`, `Env={env}`, and `VaultSlug={vault}` for precise permission boundaries.
 
 ### Full Developer Access

docs/guide/vaults/aws-ssm.md

@@ -40,6 +40,8 @@ You'll be prompted for:
 
 ## IAM Permission Scenarios
 
+> **Quick start:** Run `keep iam` to generate a ready-to-use IAM policy based on your actual configuration. The examples below are for reference and custom setups.
+
 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