docs: revamp provider docs

Author: domenkozar

docs/astro.config.mjs

@@ -48,6 +48,7 @@ export default defineConfig({
 					items: [
 						{ label: 'Configuration', slug: 'reference/configuration' },
 						{ label: 'CLI Commands', slug: 'reference/cli' },
+						{ label: 'Providers', slug: 'reference/providers' },
 						{ label: 'Adding Providers', slug: 'reference/adding-providers' },
 					],
 				},

docs/src/content/docs/index.mdx

@@ -45,7 +45,7 @@ SecretSpec separates these concerns:
 	/>
 	<LinkCard
 		title="WHERE secrets are stored"
-		href="/concepts/providers/"
+		href="/reference/providers/"
 		description="Configured via providers"
 	/>
 </CardGrid>
@@ -77,7 +77,7 @@ This separation enables portable applications, early validation, better tooling,
 	/>
 	<LinkCard
 		title="Multiple Providers"
-		href="/concepts/providers/"
+		href="/reference/providers/"
 		description="Support for Keyring, dotenv, 1Password, LastPass, and more"
 	/>
 	<LinkCard

docs/src/content/docs/reference/cli.md

@@ -124,20 +124,6 @@ secretspec run [OPTIONS] -- <COMMAND>
 $ secretspec run --profile production -- npm run deploy
 ```
 
-## Provider URIs
-
-```bash
-# Simple provider names
---provider keyring
---provider dotenv
---provider env
-
-# URIs with configuration
---provider dotenv:/path/to/.env
---provider 1password://vault
---provider "1password://account@vault"
-```
-
 ## Environment Variables
 
 | Variable | Description |

docs/src/content/docs/reference/providers.md

@@ -0,0 +1,99 @@
+---
+title: Providers Reference
+description: Complete reference for SecretSpec storage providers and their URI configurations
+---
+
+SecretSpec supports multiple storage backends for secrets. Each provider has its own URI format and configuration options.
+
+## DotEnv Provider
+
+**URI**: `dotenv://[path]` - Stores secrets in `.env` files
+
+```bash
+dotenv://                    # Uses default .env
+dotenv:///config/.env        # Custom path
+dotenv://config/.env         # Relative path
+```
+
+**Features**: Read/write, profiles, human-readable, no encryption
+
+## Environment Provider
+
+**URI**: `env://` - Read-only access to system environment variables
+
+```bash
+env://                       # Current process environment
+```
+
+**Features**: Read-only, no setup required, no persistence
+
+## Keyring Provider
+
+**URI**: `keyring://` - Uses system keychain/keyring for secure storage
+
+```bash
+keyring://                   # System default keychain
+```
+
+**Features**: Read/write, secure encryption, profiles, cross-platform
+**Storage**: Service `secretspec/{project}`, username `{profile}:{key}`
+
+## LastPass Provider
+
+**URI**: `lastpass://[folder]` - Integrates with LastPass via `lpass` CLI
+
+```bash
+lastpass://work              # Store in work folder
+lastpass:///personal/projects # Nested folder
+lastpass://localhost         # Root (no folder)
+```
+
+**Features**: Read/write, cloud sync, profiles via folders, auto-sync
+**Prerequisites**: `lpass` CLI, authenticated with `lpass login`
+**Storage**: Item name `{folder}/{profile}/{project}/{key}`
+
+## 1Password Provider
+
+**URI**: `1password://[account@]vault` or `1password+token://user:token@vault`
+
+```bash
+1password://MyVault                           # Default account
+1password://work@CompanyVault                 # Specific account
+1password+token://user:op_token@SecureVault   # Service account
+```
+
+**Features**: Read/write, cloud sync, profiles via vaults, service accounts
+**Prerequisites**: `op` CLI, authenticated with `op signin`
+**Storage**: Item name `{project}/{key}`, tags `automated`, `{project}`
+
+## Provider Selection
+
+### Command Line
+```bash
+# Simple provider names
+secretspec get API_KEY --provider keyring
+secretspec get API_KEY --provider dotenv
+secretspec get API_KEY --provider env
+
+# URIs with configuration
+secretspec get API_KEY --provider dotenv:/path/to/.env
+secretspec get API_KEY --provider 1password://vault
+secretspec get API_KEY --provider "1password://account@vault"
+```
+
+### Environment Variables
+```bash
+export SECRETSPEC_PROVIDER=keyring
+export SECRETSPEC_PROVIDER="dotenv:///config/.env"
+```
+
+
+## Security Considerations
+
+| Provider | Encryption | Storage Location | Network Access |
+|----------|------------|------------------|----------------|
+| DotEnv | ❌ Plain text | Local filesystem | ❌ No |
+| Environment | ❌ Plain text | Process memory | ❌ No |
+| Keyring | ✅ System encryption | System keychain | ❌ No |
+| LastPass | ✅ End-to-end | Cloud (LastPass) | ✅ Yes |
+| 1Password | ✅ End-to-end | Cloud (1Password) | ✅ Yes |