secret-management

name	secret-management
description	Manage secrets stored in q-ring — store, retrieve, list, inspect, import, export, and configure superposition, decay, entanglement, and tags. Use when the user mentions secrets, API keys, tokens, credentials, environment variables, .env files, or asks to store/retrieve/delete a value securely.

Secret Management

When to Use

Activate when the user:

• Asks to store, retrieve, delete, or list secrets
• Mentions API keys, tokens, passwords, credentials, or environment variables
• Wants to import from or export to .env files
• Needs superposition (per-environment values) or entanglement (linked secrets)
• Asks about secret expiry, TTL, tags, or access history

Workflow

1. Understand the landscape

Call get_project_context to get a redacted overview of existing secrets, scopes, manifest status, and recent activity.

2. CRUD operations

Task	MCP Tool
Store a secret	set_secret with optional ttlSeconds, tags, description, env (superposition), rotationFormat
Retrieve a secret	get_secret — collapses superposition automatically
Check existence	has_secret — never reveals the value
Delete a secret	delete_secret
List all secrets	list_secrets — filter with tag, expired, stale, filter
Inspect metadata	inspect_secret — shows decay, entanglement, access history (no value)
Usage / optimization	analyze_secrets — JSON report on secret usage patterns

get_secret, list_secrets, and related tools return JSON text payloads (not raw unwrapped strings) for predictable agent parsing.

3. Import and export

• Import: import_dotenv to bulk-load from .env content
• Export: export_secrets with format env or json, optional key/tag filters

4. Superposition (multi-environment)

Store per-environment values with the env parameter on set_secret:

• set_secret(key="DB_URL", value="...", env="dev")
• set_secret(key="DB_URL", value="...", env="prod")
• get_secret collapses to the detected environment automatically

5. Entanglement

Link secrets so rotating one updates the other:

• entangle_secrets(sourceKey, targetKey) — bidirectional link
• disentangle_secrets(sourceKey, targetKey) — remove link

6. Scopes

Secrets resolve through a cascade: project -> team -> org -> global. Use the scope parameter to target a specific level.

Best Practices

• Always add a description when storing secrets for discoverability
• Use tags to group related secrets (e.g., database, api, auth)
• Set ttlSeconds for credentials that expire (forces rotation awareness)
• Use generate_secret to create high-entropy values instead of inventing them