[secrets] Read the plaintext value of a single secret from the q-ring keyring. Use when an agent needs the actual credential to call an external API or inject into a runtime; prefer inspect_secret to see metadata only, has_secret for presence-only checks, and exec_with_secrets to run a command without exposing the value to chat. Side effects: collapses superposition (selects the per-env state) and writes a 'read' event to the audit log (observer effect). Subject to project tool/key policy and may be denied with a 'Policy Denied' message. Returns JSON { ok, data: { key, value } } on success or an error message if missing/blocked.

[secrets] List secret keys and quantum metadata in the requested scope, never the values. Use to discover what secrets exist before reading or writing; pair with inspect_secret for full metadata on one key, analyze_secrets for usage trends, or health_check for decay/anomaly summaries. Read-only; safe to call repeatedly. Returns JSON { ok, data: { entries: [...] } } where each entry has scope, key, stateKeys (env names if superposed), expired, stale, lifetimePercent, timeRemaining, entangledCount, accessCount.

[secrets] Create or overwrite a single secret value, optionally with TTL/decay, per-env superposition, description, tags, and rotation hints. Use to add or update one key at a time; prefer import_dotenv for bulk .env ingest, generate_secret (with saveAs) to generate-and-store in one step, and entangle_secrets instead of duplicating the same value under two keys. Mutates the keyring (overwrites any existing value at the same key/scope), writes a 'write' event to the audit log, and triggers any matching hooks. Subject to tool policy. Returns a short confirmation text like '[scope] KEY saved' (or '[scope] KEY set for env:NAME' when env is provided).

[secrets] Permanently remove a secret value (and all its env states) from the keyring for the given scope. Use when a credential is being retired or was created in error; prefer disentangle_secrets to break a sync link without erasing values, remove_hook to detach lifecycle callbacks, and tunnel_destroy for ephemeral tunnels. Destructive and not undoable from q-ring (no built-in trash). Writes a 'delete' event to the audit log and fires matching hooks. Returns 'Deleted "KEY"' on success or a not-found error if the key did not exist in the requested scope. Subject to tool policy.

[secrets] Check whether a secret exists in the requested scope without reading the value. Use as a cheap precondition before reading or writing — for example, to skip prompting the user for a key that is already configured. Prefer inspect_secret when you also need metadata. Read-only; does not record a 'read' in the audit log. Decay-aware: returns 'false' for expired secrets even though the value is still in the store. Returns the literal text 'true' or 'false'.

[secrets] Render multiple secrets as a single .env or JSON document for piping into another tool or file. Use to materialize secrets for a one-off export or copy; prefer env_generate when you want output driven by the project's .q-ring.json manifest, and teleport_pack for an encrypted bundle to share between machines. Reads values (collapses superposition for the requested env) and writes one 'export' event per included secret to the audit log. Returns the rendered text directly (no JSON wrapper). Returns an error if no secrets matched the filters. Values are surfaced in plaintext — handle with care.

[secrets] Parse standard dotenv-formatted text and store each key/value pair into the keyring in one batch. Use when migrating an existing .env file into q-ring or onboarding a new project; prefer set_secret for a single key, and teleport_unpack to import an encrypted bundle. Mutates the keyring (one write per parsed key) and emits a 'write' audit event for each. Supports comments, single/double quotes, and \n escapes. Returns a multiline summary listing imported keys and any skipped (existing) keys; in dryRun mode no writes happen and the same summary is produced for review.

[secrets] Show full metadata for a single secret — env states, decay window, entanglement links, access counters — without ever revealing the value. Use when you need to understand the shape of a key before reading it or to debug 'why is this expired/stale'; prefer get_secret for the actual value, list_secrets for a many-key overview, and audit_log for the full access timeline. Read-only; does not write a 'read' event since the value is not exposed. Returns pretty-printed JSON with fields: key, scope, type ('superposition'|'collapsed'), created, updated, accessCount, lastAccessed, environments, defaultEnv, decay { expired, stale, lifetimePercent, timeRemaining }, entangled, description, tags. Errors with not-found if the key is absent.

[secrets] Generate a cryptographically random secret using Node's CSPRNG and optionally store it in the keyring in one step. Use to create new credentials that you control (signing keys, internal tokens, passwords); for issuer-issued credentials (Stripe/OpenAI etc.) use rotate_secret to ask the upstream provider for a fresh key, and use set_secret for values you already have in hand. If saveAs is provided this mutates the keyring (one 'write' event) and returns a summary like 'Generated and saved as "KEY" (FORMAT, ~N bits entropy)'. Without saveAs the call is read-only and returns JSON { ok, data: { value } } containing the freshly generated string.

[secrets] Link two keys (across the same or different scopes) so future writes/rotations of either propagate the same value to the other. Use when one logical credential lives under multiple names (e.g. STRIPE_SECRET_KEY global and project) and should never drift; prefer set_secret for unrelated values, and reverse the link with disentangle_secrets (does not delete values). Mutates only the metadata of both envelopes — the values themselves are not changed by this call. Idempotent: re-running on an already-entangled pair is a no-op. Subject to tool policy. Returns a short confirmation: 'Entangled: SOURCE <-> TARGET'.

[secrets] Break the sync link between two previously entangled keys so future rotations no longer propagate. Use when one of the keys is being retired or should diverge intentionally; pair with delete_secret if you also want to erase one of the values, and use entangle_secrets to recreate the link. Mutates only metadata; the current values remain untouched. Safe and idempotent — running on a pair that was never linked returns success without effect. Subject to tool policy. Returns 'Disentangled: SOURCE </> TARGET'.

[project] Compare the keys declared in the project's .q-ring.json manifest against what is actually present in the keyring. Use as the canonical 'is this project ready to run' gate before starting a dev server, deploying, or onboarding a teammate; prefer health_check for a scope-wide decay sweep (no manifest), and agent_scan for multi-project scans with optional auto-rotation. Read-only; does not mutate the keyring or audit log materially beyond a 'list' read. Returns JSON { total, present, missing, expired, stale, ready, secrets: [...] } where ready is true only when nothing is missing or expired. Errors with 'No secrets manifest found in .q-ring.json' if the project has no manifest.

[project] Render a complete .env file body from the project's .q-ring.json manifest, resolving each declared key from the keyring. Use when a build step or local runtime needs a real .env materialized on disk and you want exactly the keys the manifest declares; prefer export_secrets when you want every key in scope (manifest-agnostic) and exec_with_secrets to inject secrets into a child process without writing them to a file. Reads values (records 'read' audit events) and collapses superposition for the requested env. Returns the raw .env text, with # MISSING (required): KEY / # EXPIRED: KEY / # STALE: KEY warnings appended as comments. Missing keys appear as commented-out # KEY= placeholders so the file remains a valid drop-in.

[project] Resolve which environment slug (e.g. 'dev', 'staging', 'prod') the current invocation should collapse to. Use before reading secrets when you want to mirror the same env q-ring would auto-pick (e.g. to log it, or to pass through to another tool); prefer passing an explicit env to get_secret/env_generate when you already know which env you want. Read-only; checks the QRING_ENV env var, NODE_ENV, the project's .q-ring.json, and the current git branch in priority order. Returns JSON { env, source } (e.g. { env: 'dev', source: 'NODE_ENV' }), or a plain message indicating that no env could be detected.

[agent] Return a single redacted snapshot of everything an AI agent typically wants to know about this project: secrets present (keys + metadata only), detected env, manifest declarations, configured providers, registered hooks, and recent audit activity. Use this as the very first call in a session to orient the agent before it asks for any individual secret; prefer list_secrets for a flat key listing, check_project for manifest-vs-keyring drift, and audit_log for a deeper access trail. Read-only and value-safe — no plaintext secret values are ever included. Returns a single pretty-printed JSON document; shape is intentionally broad and may grow over time, so read defensively.

[tunnel] Stash a one-shot or short-lived secret in the q-ring server's process memory and return an ID that can be used to read it back. Use for handing a one-time value to another tool/process without persisting it (npm OTP codes, magic-link tokens, copy/paste between machines via a relay); prefer set_secret with ttlSeconds when you actually want a tracked, auditable secret. Mutates only in-memory state — the value never touches disk and is lost on server restart. Subject to tool policy. Returns JSON { ok, data: { id } } where id is an opaque string to pass to tunnel_read/tunnel_destroy.

[tunnel] Fetch the value stashed by a prior tunnel_create call by its ID. Use exactly once per intended consumer; the value is destructive-by-design and may self-delete after this call. Increments the read counter and may auto-destroy the tunnel if maxReads was set. Returns JSON { ok, data: { id, value } } on success, or an error 'Tunnel "..." not found or expired' if the tunnel has been destroyed, hit its TTL, or never existed.

[tunnel] Enumerate all currently-active tunnels in the q-ring server with their remaining read budget and time-to-live. Use to audit what is still in memory or to look up an ID you forgot; values are never included in the output. Read-only. Returns one line per tunnel formatted as id | reads:N | max:N | expires:Ns, or the literal text 'No active tunnels' when the list is empty.

[tunnel] Immediately remove a tunnel from memory, regardless of remaining reads or TTL. Use when a tunneled value should be cancelled before delivery (e.g. wrong recipient, secret already rotated); prefer letting maxReads/TTL handle cleanup for normal flows. Mutates in-memory state only. Returns 'Destroyed ID' on success or a not-found error if the ID is unknown or already gone.

[teleport] Encrypt one or more secrets into a single AES-256-GCM bundle string that can be safely transferred between machines. Use to hand off a curated set of credentials to another developer or environment; prefer export_secrets for plaintext .env output (single machine, trusted) and tunnel_create for ephemeral one-shot delivery on the same machine. Reads each secret value (records 'export' audit events) and produces a base64-encoded ciphertext. The bundle is unreadable without the same passphrase via teleport_unpack. Returns the bundle string directly. Errors with 'No secrets to pack' if the filter matched zero secrets.

[teleport] Decrypt a bundle produced by teleport_pack and import each contained secret into the local keyring. Use on the receiving machine after a packer hands you the bundle and passphrase out-of-band; prefer dryRun=true first to preview what will be written. When dryRun is false this mutates the keyring (one 'write' event per imported secret) at the requested scope. Bad passphrase or tampered bundle returns JSON { ok: false, error: { message } } with isError: true. On success returns 'Imported N secret(s) from teleport bundle'; in dryRun mode returns 'Would import N secrets:' followed by a KEY [scope] listing.

[audit] Query the q-ring audit log — a tamper-evident record of every read/write/delete touching a secret. Use to investigate 'who accessed KEY recently?' or to feed an agent the access timeline for a specific credential; prefer detect_anomalies for automated unusual-pattern detection and health_check for decay-state-plus-anomalies in one call. Read-only. Returns one line per event in chronological order, formatted timestamp | action | key | [scope] | env:NAME | detail. Returns 'No audit events found' when the filter matches nothing.

[audit] Scan the audit history for suspicious access patterns — burst reads of the same key, off-hours access, and other heuristics. Use as a quick triage signal when investigating a single key or before letting an agent rotate credentials; prefer health_check for a scope-wide decay+anomaly summary, and agent_scan for multi-project JSON reports with optional auto-rotation. Read-only; never mutates secrets or the audit log. Returns one line per finding formatted [type] description, or 'No anomalies detected' when the log looks clean.

[health] Run a single read-only sweep over every secret in the requested scope and report counts of healthy/stale/expired secrets plus any current audit anomalies. Use as the default 'is everything OK?' command for an agent or operator; prefer check_project to validate manifest compliance specifically, detect_anomalies for audit-only triage, and agent_scan for multi-project JSON output or optional auto-rotation. Read-only — never writes. Returns a multi-line text summary: header counts (Total / Healthy / Stale / Expired / No decay / Anomalies), then per-secret EXPIRED: / STALE: issue lines, then per-anomaly [type] description lines.

[audit] Recompute the SHA-256 hash chain over the audit log and confirm no event has been mutated, deleted, or reordered. Use periodically as a tamper-evidence check, or whenever you suspect the audit log has been touched outside q-ring; the result is informational — this tool does not repair the chain if it is broken. Read-only. Returns JSON { ok, valid, brokenAt? } where valid is true for an intact chain and brokenAt (when present) names the first event whose hash did not match.

[audit] Export the audit log as a portable text artifact suitable for archiving or feeding into another SIEM/analyzer. Use for compliance exports, after-the-fact investigations, or to hand the trail to a non-MCP consumer; prefer audit_log for an in-conversation tail and verify_audit_chain to confirm integrity before exporting. Read-only. Returns the rendered text directly (no JSON wrapper). 'jsonl' is one event per line; 'json' is a single array; 'csv' is a header row plus events. Time filters are applied to the event timestamps before formatting.

[validation] Test whether a stored secret is still accepted by its upstream service (OpenAI, Stripe, GitHub, AWS, generic HTTP, etc.) by making a minimal authenticated request. Use to confirm liveness before relying on a credential or as the verification step after rotate_secret; prefer ci_validate_secrets for a batch run across every key in scope. Side effects: makes one outbound network request per call (may incur tiny provider-side rate-limit cost). Records 'read' for the underlying secret value in the audit log; the value itself is never logged. Returns JSON { valid, provider, status?, message?, rateLimit?, ... } (provider-specific shape).

[validation] Enumerate the secret-validation providers q-ring knows how to call (OpenAI, Stripe, GitHub, …) along with their auto-detect prefixes. Use to discover what provider string to pass to validate_secret/rotate_secret, or to check whether your custom provider is registered. Read-only. Returns JSON array of { name, description, prefixes } objects. prefixes are the literal key-value prefixes (e.g. 'sk-' for OpenAI) used for auto-detection.

[validation] Ask the upstream provider to issue a fresh credential for this secret and store the new value back into the keyring. Use when a secret is expiring, leaked, or part of a scheduled rotation; prefer generate_secret for self-managed values you fully control, and agent_scan --autoRotate for sweep-style rotation across multiple expired keys. Mutates the keyring with the newly-issued value if rotation succeeds (one 'write' audit event), and makes outbound network requests against the provider's rotation API. Returns JSON { rotated, newValue?, message?, ... }. If rotated is false, the existing value is left untouched.

[validation] Validate every accessible secret in the requested scope against its detected provider in a single batch and return a structured pass/fail report. Use as a CI gate ('do all our credentials still work before deploy?') or as a pre-rotation health pass; prefer validate_secret for a single key. Side effects: one outbound request per validatable secret (cost scales with N). Reads each secret value (records 'read' audit events). Returns JSON { total, valid, invalid, results: [...] } listing per-key status, provider, and error messages where applicable. Returns 'No secrets to validate' if nothing in scope has a provider mapping.

[hooks] Register a side-effect (shell command, HTTP webhook, or process signal) that fires automatically when a matching secret is written, deleted, or rotated. Use to keep external systems in sync (restart a service after rotation, post to Slack on delete, kick a build); prefer agent_remember for storing facts an agent should recall later, and register_hook is not the right tool for time-based scheduled rotation (use agent_scan for that). Mutates the hook registry on disk. At least one match criterion (key, keyPattern, or tag) is required — calls without any return an error. Returns JSON of the registered hook entry including its assigned id (use that id with remove_hook).

[hooks] Enumerate every registered lifecycle hook with its match criteria, delivery type, enabled flag, and description. Use to find a hook's id before calling remove_hook, audit what side effects are wired up, or diagnose why a hook did not fire. Read-only. Returns pretty-printed JSON array of hook entries, or 'No hooks registered' when the registry is empty.

[hooks] Detach a single lifecycle hook by its registry id so it stops firing. Use to retire a specific webhook/command without touching any secrets; prefer delete_secret to remove a credential and tunnel_destroy for ephemeral tunnels. Mutates the hook registry only — does not touch secret values, audit log, or env states. Idempotent in spirit: removing an already-absent id returns a not-found error rather than partial work. Returns 'Removed hook ID' on success.

[exec] Run a child shell command with project secrets injected as environment variables and any leaked secret values redacted from captured stdout/stderr before they return to the agent. Use to let an agent run a script that needs credentials (npm run db:migrate, terraform plan, vercel deploy) without ever putting plaintext values in the chat; prefer env_generate if you need to write a .env file to disk and validate_secret for upstream liveness checks. Spawns a real child process — has whatever side effects the command itself causes (writes, network, exec). Subject to BOTH tool policy and exec policy (allowlist/denylist). Returns a text body with Exit code: N then STDOUT: and STDERR: blocks; both streams are scrubbed against the secret values that were injected.

[scan] Walk a directory tree and flag plausible hardcoded secrets using regex heuristics plus Shannon-entropy scoring on string literals. Use as a one-shot 'is anything leaking in this repo?' audit before commit/release; prefer lint_files when you already know the specific files to check (and want optional auto-fix). Read-only — never modifies source files. Honors .gitignore. Returns JSON array of { file, line, key, value, kind } findings, or 'No hardcoded secrets found in the specified directory.' when clean. False positives are possible — review before treating as ground truth.

[scan] Inspect a specific list of files for hardcoded secrets and, when fix is true, replace each finding with process.env.KEY while storing the extracted value into the keyring. Use to migrate a known set of files (e.g. just-changed files in a pre-commit hook) into q-ring; prefer scan_codebase_for_secrets for a whole-tree audit and import_dotenv to ingest an existing .env. With fix: false this is read-only. With fix: true this MUTATES the listed source files in place (review with git diff!) and writes one new secret per finding to the keyring. Returns a JSON array of { file, line, key, value, kind } findings, or 'No hardcoded secrets found in the specified files.'.

[agent] Cross-reference the secrets in scope with recent audit events to produce a usage profile and rotation/retirement suggestions. Use as a quarterly hygiene check or as input to a planner that decides what to rotate or delete; prefer health_check for decay-only triage and audit_log to inspect access timelines for one key. Read-only; uses the most recent ~500 audit events. Returns JSON { total, expired, stale, neverAccessed: [...], noRotationFormat: [...], mostAccessed: [{ key, reads }] }. neverAccessed and noRotationFormat are good candidates for cleanup or for adding rotation hints.

[dashboard] Start a local web dashboard (http://127.0.0.1:PORT) that streams live KPIs, secret tables, manifest gaps, hooks, audit events, and anomalies via Server-Sent Events. Use when an operator (or an agent on behalf of one) wants a richer visual surface than chat output; prefer health_check / analyze_secrets for one-shot text summaries inside the conversation. Side effect: binds an HTTP server on the requested port (one process-wide instance — re-running returns the existing URL instead of starting a second server). Never exposes secret values. Returns the URL string to open in a browser.

[agent] Run a multi-project health pass that gathers decay status, audit anomalies, and .q-ring.json manifest gaps across one or more project paths and (optionally) auto-rotates expired secrets with freshly generated values. Use as the canonical 'agent maintenance loop' across a portfolio of repos; prefer health_check for a single read-only scope, detect_anomalies for audit-only triage, and check_project for a single-project manifest check. With autoRotate=false (default) this is read-only. With autoRotate=true it OVERWRITES expired secret values in the keyring with generated replacements — credential changes that may break upstream integrations until they are propagated. Subject to tool policy. Returns a JSON report of per-project findings and any rotations performed.

[agent] Persist a non-secret key/value note in encrypted, on-disk agent memory that survives across MCP sessions. Use to record stable agent context — last rotation date for a key, the user's deployment preferences, decisions taken in earlier sessions; do NOT use this to store secrets (use set_secret instead) and prefer chat scratchpad for purely transient state. Mutates the encrypted memory store. Idempotent: rewriting the same key with a new value simply overwrites. Returns 'Remembered "KEY"' on success.

[agent] Read a value from encrypted agent memory, or list every stored key when no specific key is supplied. Use at the start of an agent loop to rehydrate prior context, or to look up a single remembered fact; prefer get_project_context for a redacted overview of secrets and get_secret for actual credential values. Read-only. With a key argument: returns JSON { ok, data: { key, value } } or a not-found error. Without key: returns a JSON listing of every stored key (no values), or 'Agent memory is empty'.

[agent] Permanently delete a single key from encrypted agent memory. Use to retract obsolete or misremembered context; prefer overwriting via agent_remember when you just want to update the value, and use delete_secret for actual credentials (which never live in agent memory). Destructive: there is no recycle bin. Returns 'Forgot "KEY"' on success or a not-found error if the key was already absent.

[policy] Ask whether a single intended action would be allowed by the project's .q-ring.json policy without actually performing it. Use as a dry-run before calling a potentially-blocked tool, attempting to read a sensitive key, or invoking exec_with_secrets with a non-trivial command; prefer get_policy_summary for a one-shot overview of the entire policy. Read-only. Returns JSON { allowed, reason?, policySource } describing the decision. Returns an error 'Missing required parameter for the selected action type' if the matching argument for the chosen action is not supplied.

[policy] Return a high-level summary of the project's .q-ring.json governance policy — counts of allow/deny rules for tools, key reads, exec commands, plus approval and rotation requirements. Use to orient an agent (or the user) on what guardrails are active before attempting policy-restricted actions; prefer check_policy for a precise per-action verdict. Read-only. Returns pretty-printed JSON; missing policy file returns an empty/default summary rather than an error so callers can branch on the counts.