Improve vault extension documentation and configSchema field descriptions

vault/1password/extensions/vaults/onepassword.ts

@@ -19,11 +19,6 @@
 
 import { z } from "npm:zod@4.3.6";
 
-const configSchema = z.object({
-  op_vault: z.string().min(1, "1Password vault name is required"),
-  op_account: z.string().optional(),
-});
-
 interface VaultProvider {
   get(secretKey: string): Promise<string>;
   put(secretKey: string, secretValue: string): Promise<void>;
@@ -264,12 +259,15 @@ export const vault = {
   name: "1Password",
   description:
     "1Password vault provider. Uses the 1Password CLI (op) for secret operations.",
-  configSchema,
+  configSchema: z.object({
+    op_vault: z.string().min(1).describe("The 1Password vault to use"),
+    op_account: z.string().optional().describe("Account shorthand or UUID"),
+  }),
   createProvider(
     name: string,
     config: Record<string, unknown>,
   ): VaultProvider {
-    const parsed = configSchema.parse(config);
+    const parsed = vault.configSchema.parse(config);
     return new OnePasswordVaultProvider(name, parsed);
   },
 };

vault/1password/manifest.yaml

@@ -1,7 +1,33 @@
 manifestVersion: 1
 name: "@swamp/1password"
-version: "2026.03.17.1"
-description: "1Password vault provider — uses the op CLI for secret operations"
+version: "2026.03.18.5"
+description: |
+  Read and write secrets stored in 1Password using the `op` CLI.
+
+  ## Prerequisites
+
+  - [1Password CLI](https://developer.1password.com/docs/cli/get-started/) installed and in `PATH`
+  - Authenticated via one of:
+    - **Service account**: `export OP_SERVICE_ACCOUNT_TOKEN=<token>`
+    - **Desktop app**: enable CLI integration in 1Password settings
+    - **Connect Server**: `export OP_CONNECT_HOST=<url>` and `export OP_CONNECT_TOKEN=<token>`
+
+  ## Usage
+
+  ```bash
+  swamp vault create @swamp/1password my-1password \
+    --config '{"op_vault": "Private"}' --json
+
+  swamp vault get my-1password my-api-key --json
+  swamp vault put my-1password my-api-key "s3cr3t" --json
+  swamp vault list-keys my-1password --json
+  ```
+
+  ## Secret Key Format
+
+  - `item-name` — reads the `password` field of the named item
+  - `item-name/field` — reads a specific field
+  - `op://vault/item/field` — full 1Password URI (passthrough)
 repository: "https://github.com/systeminit/swamp-extensions"
 vaults:
   - onepassword.ts

vault/aws-sm/extensions/vaults/aws_sm.ts

@@ -27,10 +27,6 @@ import {
   SecretsManagerClient,
 } from "npm:@aws-sdk/client-secrets-manager@3.1010.0";
 
-const configSchema = z.object({
-  region: z.string().min(1, "AWS region is required"),
-});
-
 interface VaultProvider {
   get(secretKey: string): Promise<string>;
   put(secretKey: string, secretValue: string): Promise<void>;
@@ -115,12 +111,15 @@ export const vault = {
   name: "AWS Secrets Manager",
   description:
     "AWS Secrets Manager vault provider. Uses the default AWS credential chain for authentication.",
-  configSchema,
+  configSchema: z.object({
+    // deno-fmt-ignore
+    region: z.string().min(1).describe("AWS region where the Secrets Manager secrets are stored e.g. us-east-1"),
+  }),
   createProvider(
     name: string,
     config: Record<string, unknown>,
   ): VaultProvider {
-    const parsed = configSchema.parse(config);
+    const parsed = vault.configSchema.parse(config);
     return new AwsSmVaultProvider(name, parsed);
   },
 };

vault/aws-sm/manifest.yaml

@@ -1,7 +1,39 @@
 manifestVersion: 1
 name: "@swamp/aws-sm"
-version: "2026.03.17.1"
-description: "AWS Secrets Manager vault provider"
+version: "2026.03.18.1"
+description: |
+  Read and write secrets stored in AWS Secrets Manager.
+
+  ## Authentication
+
+  Uses the default AWS credential chain — no credentials in config. Provide
+  credentials via one of:
+  - Environment variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
+  - AWS profile: `~/.aws/credentials`
+  - IAM role attached to the instance or task
+
+  ## Required IAM Permissions
+
+  - `secretsmanager:GetSecretValue`
+  - `secretsmanager:PutSecretValue`
+  - `secretsmanager:CreateSecret`
+  - `secretsmanager:ListSecrets`
+
+  ## Usage
+
+  ```bash
+  swamp vault create @swamp/aws-sm my-aws-sm \
+    --config '{"region": "us-east-1"}' --json
+
+  swamp vault get my-aws-sm my/secret/name --json
+  swamp vault put my-aws-sm my/secret/name "s3cr3t" --json
+  swamp vault list-keys my-aws-sm --json
+  ```
+
+  ## Secret Key Format
+
+  Secret keys map directly to AWS Secrets Manager secret names, including
+  path-style names such as `myapp/production/db-password`.
 repository: "https://github.com/systeminit/swamp-extensions"
 vaults:
   - aws_sm.ts

vault/azure-kv/extensions/vaults/azure_kv.ts

@@ -21,11 +21,6 @@ import { z } from "npm:zod@4.3.6";
 import { DefaultAzureCredential } from "npm:@azure/identity@4.13.0";
 import { SecretClient } from "npm:@azure/keyvault-secrets@4.10.0";
 
-const configSchema = z.object({
-  vault_url: z.string().url("Azure Key Vault URL is required"),
-  secret_prefix: z.string().optional(),
-});
-
 interface VaultProvider {
   get(secretKey: string): Promise<string>;
   put(secretKey: string, secretValue: string): Promise<void>;
@@ -107,12 +102,17 @@ export const vault = {
   name: "Azure Key Vault",
   description:
     "Azure Key Vault vault provider. Uses DefaultAzureCredential for authentication.",
-  configSchema,
+  configSchema: z.object({
+    // deno-fmt-ignore
+    vault_url: z.string().url("Azure Key Vault URL is required").describe("Full URL of the Azure Key Vault e.g. https://my-vault.vault.azure.net"),
+    // deno-fmt-ignore
+    secret_prefix: z.string().optional().describe("Optional prefix to namespace secrets within the vault e.g. swamp- to scope all reads and writes"),
+  }),
   createProvider(
     name: string,
     config: Record<string, unknown>,
   ): VaultProvider {
-    const parsed = configSchema.parse(config);
+    const parsed = vault.configSchema.parse(config);
     return new AzureKvVaultProvider(name, parsed);
   },
 };

vault/azure-kv/manifest.yaml

@@ -1,7 +1,34 @@
 manifestVersion: 1
 name: "@swamp/azure-kv"
-version: "2026.03.17.1"
-description: "Azure Key Vault vault provider"
+version: "2026.03.18.1"
+description: |
+  Read and write secrets stored in Azure Key Vault.
+
+  ## Authentication
+
+  Uses `DefaultAzureCredential` — no credentials in config. Provide
+  credentials via one of:
+  - Environment variables: `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`
+  - Azure CLI: `az login`
+  - Managed Identity attached to the VM or container
+
+  ## Usage
+
+  ```bash
+  swamp vault create @swamp/azure-kv my-azure-kv \
+    --config '{"vault_url": "https://my-vault.vault.azure.net"}' --json
+
+  swamp vault get my-azure-kv my-secret --json
+  swamp vault put my-azure-kv my-secret "s3cr3t" --json
+  swamp vault list-keys my-azure-kv --json
+  ```
+
+  ## Secret Key Format
+
+  Secret keys map to Azure Key Vault secret names. Slashes and underscores are
+  converted to hyphens (Azure only allows alphanumeric characters and hyphens).
+  Use `secret_prefix` to namespace secrets when sharing a vault across multiple
+  swamp instances.
 repository: "https://github.com/systeminit/swamp-extensions"
 vaults:
   - azure_kv.ts