@i4ctime/q-ring 0.11.5 → 0.12.0

package/dist/mcp.js

@@ -32,13 +32,14 @@ import {
   registry,
   remember,
   removeHook,
+  setPolicyRoot,
   setSecret,
   tunnelCreate,
   tunnelDestroy,
   tunnelList,
   tunnelRead,
   verifyAuditChain
-} from "./chunk-MQM4DLPI.js";
+} from "./chunk-YWDKAZWS.js";
 
 // src/mcp.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -118,24 +119,28 @@ function generateSecret(opts2 = {}) {
     }
     case "password": {
       const len = opts2.length ?? 24;
-      let pw = randomString(PASSWORD_CHARS, len);
-      const hasUpper = /[A-Z]/.test(pw);
-      const hasLower = /[a-z]/.test(pw);
-      const hasDigit = /[0-9]/.test(pw);
-      const hasSpecial = /[^A-Za-z0-9]/.test(pw);
-      if (!hasUpper) pw = replaceAt(pw, randomInt(len), randomString("ABCDEFGHIJKLMNOPQRSTUVWXYZ", 1));
-      if (!hasLower) pw = replaceAt(pw, randomInt(len), randomString("abcdefghijklmnopqrstuvwxyz", 1));
-      if (!hasDigit) pw = replaceAt(pw, randomInt(len), randomString("0123456789", 1));
-      if (!hasSpecial) pw = replaceAt(pw, randomInt(len), randomString("!@#$%^&*()-_=+", 1));
-      return pw;
+      const classCharsets = [
+        "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+        "abcdefghijklmnopqrstuvwxyz",
+        "0123456789",
+        "!@#$%^&*()-_=+"
+      ];
+      const guaranteed = classCharsets.slice(0, Math.min(classCharsets.length, len)).map((cs) => randomString(cs, 1));
+      const remaining = Math.max(0, len - guaranteed.length);
+      const chars = [
+        ...guaranteed,
+        ...remaining > 0 ? randomString(PASSWORD_CHARS, remaining).split("") : []
+      ];
+      for (let i = chars.length - 1; i > 0; i--) {
+        const j = randomInt(i + 1);
+        [chars[i], chars[j]] = [chars[j], chars[i]];
+      }
+      return chars.join("");
     }
     default:
       return randomBytes(32).toString("hex");
   }
 }
-function replaceAt(str, index, char) {
-  return str.slice(0, index) + char + str.slice(index + 1);
-}
 function estimateEntropy(secret) {
   const charsets = [
     { regex: /[a-z]/, size: 26 },
@@ -173,8 +178,11 @@ function parseDotenv(content) {
       '"': '"'
     };
     value = value.replace(/\\([nrt"\\])/g, (_, ch) => escapeMap[ch] ?? ch);
-    if (value.includes("#") && !line.includes('"') && !line.includes("'")) {
-      value = value.split("#")[0].trim();
+    if (!line.includes('"') && !line.includes("'")) {
+      const commentMatch = value.match(/\s#/);
+      if (commentMatch && commentMatch.index !== void 0) {
+        value = value.slice(0, commentMatch.index).trim();
+      }
     }
     if (key) result.set(key, value);
   }
@@ -182,9 +190,14 @@ function parseDotenv(content) {
 }
 function importDotenv(filePathOrContent, options = {}) {
   let content;
-  try {
-    content = readFileSync(filePathOrContent, "utf8");
-  } catch {
+  const source = options.source ?? "cli";
+  if (source === "cli") {
+    try {
+      content = readFileSync(filePathOrContent, "utf8");
+    } catch {
+      content = filePathOrContent;
+    }
+  } else {
     content = filePathOrContent;
   }
   const pairs = parseDotenv(content);
@@ -246,11 +259,21 @@ function enforceToolPolicy(toolName, projectPath8) {
   return null;
 }
 var commonSchemas = {
-  teamId: z.string().optional().describe("Team identifier for team-scoped secrets"),
-  orgId: z.string().optional().describe("Org identifier for org-scoped secrets"),
-  scope: z.enum(["global", "project", "team", "org"]).optional().describe("Scope: global, project, team, or org"),
-  projectPath: z.string().optional().describe("Project root path for project-scoped secrets"),
-  env: z.string().optional().describe("Environment for superposition collapse (e.g., dev, staging, prod)")
+  teamId: z.string().optional().describe(
+    "Team identifier for team-scoped secrets. Required only when scope='team'. Example: 'acme-platform'."
+  ),
+  orgId: z.string().optional().describe(
+    "Organization identifier for org-scoped secrets. Required only when scope='org'. Example: 'acme-corp'."
+  ),
+  scope: z.enum(["global", "project", "team", "org"]).optional().describe(
+    "Where the secret lives. 'global' = user keyring (default if omitted on reads), 'project' = scoped to projectPath, 'team' = team-shared (needs teamId), 'org' = org-shared (needs orgId)."
+  ),
+  projectPath: z.string().optional().describe(
+    "Absolute path to the project root for project-scoped secrets and policy resolution. Defaults to the MCP server's current working directory when omitted."
+  ),
+  env: z.string().optional().describe(
+    "Environment slug used to collapse superposition when a secret has multiple per-env states. Examples: 'dev', 'staging', 'prod'. If omitted, the secret's defaultEnv is used."
+  )
 };
 
 // src/mcp/tools/secrets.ts
@@ -258,9 +281,15 @@ var { teamId, orgId, scope, projectPath, env } = commonSchemas;
 function registerSecretTools(server2) {
   server2.tool(
     "get_secret",
-    "[secrets] Retrieve a secret by key. Collapses superposition if the secret has multiple environment states. Records access in audit log (observer effect).",
+    [
+      "[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."
+    ].join(" "),
     {
-      key: z2.string().describe("The secret key name"),
+      key: z2.string().describe(
+        "Exact secret key name as stored in the keyring (case-sensitive). Example: 'OPENAI_API_KEY'."
+      ),
       scope,
       projectPath,
       env,
@@ -291,14 +320,26 @@ function registerSecretTools(server2) {
   );
   server2.tool(
     "list_secrets",
-    "[secrets] List all secret keys with quantum metadata (scope, decay status, superposition states, entanglement, access count). Values are never exposed. Supports filtering by tag, expiry state, and key pattern.",
+    [
+      "[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."
+    ].join(" "),
     {
       scope,
       projectPath,
-      tag: z2.string().optional().describe("Filter by tag"),
-      expired: z2.boolean().optional().describe("Show only expired secrets"),
-      stale: z2.boolean().optional().describe("Show only stale secrets (75%+ decay)"),
-      filter: z2.string().optional().describe("Glob pattern on key name (e.g., 'API_*')"),
+      tag: z2.string().optional().describe(
+        "Return only secrets that include this exact tag (case-sensitive). Example: 'production'."
+      ),
+      expired: z2.boolean().optional().describe(
+        "If true, return only secrets whose decay TTL has elapsed (lifetimePercent >= 100)."
+      ),
+      stale: z2.boolean().optional().describe(
+        "If true, return only secrets in the stale window (lifetimePercent >= 75 and not yet expired)."
+      ),
+      filter: z2.string().optional().describe(
+        "Glob pattern matched against the key name. Supports `*` and `?`. Examples: 'API_*', 'STRIPE_?_KEY'."
+      ),
       teamId,
       orgId
     },
@@ -338,18 +379,32 @@ function registerSecretTools(server2) {
   );
   server2.tool(
     "set_secret",
-    "[secrets] Create or overwrite a secret value plus optional metadata (TTL/decay, per-env superposition, description, tags). Overwrites existing values for the same key/scope; records access in the audit log. Use import_dotenv for bulk .env ingest. Subject to tool policy; no external rate limits beyond provider calls when validating elsewhere.",
+    [
+      "[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)."
+    ].join(" "),
     {
-      key: z2.string().describe("The secret key name"),
-      value: z2.string().describe("The secret value"),
+      key: z2.string().describe(
+        "Secret key name (UPPER_SNAKE_CASE recommended). Example: 'STRIPE_SECRET_KEY'."
+      ),
+      value: z2.string().describe(
+        "The secret value to store. Stored as-is; never logged or echoed. May be empty only when `env` is provided to register a new env without a default."
+      ),
       scope: scope.default("global"),
       projectPath,
       env: z2.string().optional().describe(
-        "If provided, sets the value for this specific environment (superposition)"
+        "If set, writes this value to the named per-env state (superposition) instead of the default slot. Existing default value is preserved as state 'default'. Example: 'prod'."
+      ),
+      ttlSeconds: z2.number().optional().describe(
+        "Quantum decay window in seconds. After this many seconds the secret is marked expired (still readable, but `has_secret` returns false and `health_check` flags it). Omit for no decay."
+      ),
+      description: z2.string().optional().describe(
+        "Free-text human-readable description shown in `inspect_secret` and the dashboard."
+      ),
+      tags: z2.array(z2.string()).optional().describe(
+        "Tag list for filtering and hook matching. Example: ['production', 'payments']."
       ),
-      ttlSeconds: z2.number().optional().describe("Time-to-live in seconds (quantum decay)"),
-      description: z2.string().optional().describe("Human-readable description"),
-      tags: z2.array(z2.string()).optional().describe("Tags for organization"),
       rotationFormat: z2.enum([
         "hex",
         "base64",
@@ -358,8 +413,12 @@ function registerSecretTools(server2) {
         "api-key",
         "token",
         "password"
-      ]).optional().describe("Format for auto-rotation when this secret expires"),
-      rotationPrefix: z2.string().optional().describe("Prefix for auto-rotation (e.g. 'sk-')"),
+      ]).optional().describe(
+        "Format used by `agent_scan --autoRotate` and `rotate_secret` when this secret expires. Pick the format that matches the upstream service's accepted shape."
+      ),
+      rotationPrefix: z2.string().optional().describe(
+        "Literal prefix prepended on auto-rotation (only used with rotationFormat 'api-key' or 'token'). Example: 'sk-'."
+      ),
       teamId,
       orgId
     },
@@ -401,9 +460,13 @@ function registerSecretTools(server2) {
   );
   server2.tool(
     "delete_secret",
-    "[secrets] Permanently remove a secret value from the keyring for the given scope/path (not recoverable from q-ring). Does not remove hooks, tunnels, or entanglement metadata alone\u2014use remove_hook, tunnel_destroy, or disentangle_secrets respectively. Returns success or not-found text; subject to tool policy.",
+    [
+      "[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.`
+    ].join(" "),
     {
-      key: z2.string().describe("The secret key name"),
+      key: z2.string().describe("Exact secret key name to delete. Example: 'OLD_API_KEY'."),
       scope,
       projectPath,
       teamId,
@@ -421,9 +484,13 @@ function registerSecretTools(server2) {
   );
   server2.tool(
     "has_secret",
-    "[secrets] Check if a secret exists. Returns boolean. Never reveals the value. Respects decay \u2014 expired secrets return false.",
+    [
+      "[secrets] Check whether a secret exists in the requested scope without reading the value.",
+      "Use as a cheap precondition before reading or writing \u2014 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'."
+    ].join(" "),
     {
-      key: z2.string().describe("The secret key name"),
+      key: z2.string().describe("Exact secret key name. Example: 'GITHUB_TOKEN'."),
       scope,
       projectPath,
       teamId,
@@ -437,11 +504,21 @@ function registerSecretTools(server2) {
   );
   server2.tool(
     "export_secrets",
-    "[secrets] Export secrets as .env or JSON format. Collapses superposition. Supports filtering by specific keys or tags.",
+    [
+      "[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 \u2014 handle with care."
+    ].join(" "),
     {
-      format: z2.enum(["env", "json"]).optional().default("env").describe("Output format"),
-      keys: z2.array(z2.string()).optional().describe("Only export these specific key names"),
-      tags: z2.array(z2.string()).optional().describe("Only export secrets with any of these tags"),
+      format: z2.enum(["env", "json"]).optional().default("env").describe(
+        `'env' renders KEY="value" lines suitable for a .env file; 'json' renders an object keyed by secret name. Defaults to 'env'.`
+      ),
+      keys: z2.array(z2.string()).optional().describe(
+        "Whitelist of exact key names to include. If omitted, every key in scope is considered (subject to `tags`)."
+      ),
+      tags: z2.array(z2.string()).optional().describe(
+        "Include only secrets tagged with at least one of these tags. Combined with `keys` as an AND filter when both are supplied."
+      ),
       scope,
       projectPath,
       env,
@@ -463,13 +540,23 @@ function registerSecretTools(server2) {
   );
   server2.tool(
     "import_dotenv",
-    "[secrets] Import secrets from .env file content. Parses standard dotenv syntax (comments, quotes, multiline escapes) and stores each key/value pair in q-ring.",
+    [
+      "[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."
+    ].join(" "),
     {
-      content: z2.string().describe("The .env file content to parse and import"),
+      content: z2.string().describe(
+        "Raw .env file content as a single string (newline-separated KEY=VALUE lines, comments allowed)."
+      ),
       scope: scope.default("global"),
       projectPath,
-      skipExisting: z2.boolean().optional().default(false).describe("Skip keys that already exist in q-ring"),
-      dryRun: z2.boolean().optional().default(false).describe("Preview what would be imported without saving")
+      skipExisting: z2.boolean().optional().default(false).describe(
+        "If true, leave already-present keys untouched and add them to the 'skipped' list instead of overwriting."
+      ),
+      dryRun: z2.boolean().optional().default(false).describe(
+        "If true, parse and report what would happen but do not write to the keyring. Useful for previewing imports before committing."
+      )
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("import_dotenv", params.projectPath);
@@ -495,9 +582,13 @@ function registerSecretTools(server2) {
   );
   server2.tool(
     "inspect_secret",
-    "[secrets] Show full quantum state of a secret: superposition states, decay status, entanglement links, access history. Never reveals the actual value.",
+    [
+      "[secrets] Show full metadata for a single secret \u2014 env states, decay window, entanglement links, access counters \u2014 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."
+    ].join(" "),
     {
-      key: z2.string().describe("The secret key name"),
+      key: z2.string().describe("Exact secret key name to inspect. Example: 'OPENAI_API_KEY'."),
       scope,
       projectPath,
       teamId,
@@ -542,7 +633,11 @@ function registerSecretTools(server2) {
   );
   server2.tool(
     "generate_secret",
-    "[secrets] Generate a cryptographic secret (quantum noise). Formats: hex, base64, alphanumeric, uuid, api-key, token, password. Optionally save directly to the keyring.",
+    [
+      "[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."
+    ].join(" "),
     {
       format: z2.enum([
         "hex",
@@ -552,10 +647,18 @@ function registerSecretTools(server2) {
         "api-key",
         "token",
         "password"
-      ]).optional().default("api-key").describe("Output format"),
-      length: z2.number().optional().describe("Length in bytes or characters"),
-      prefix: z2.string().optional().describe("Prefix for api-key/token format"),
-      saveAs: z2.string().optional().describe("If provided, save the generated secret with this key name"),
+      ]).optional().default("api-key").describe(
+        "Output shape. 'hex' / 'base64' / 'alphanumeric' = raw random string of `length` characters; 'uuid' = RFC4122 v4; 'api-key' / 'token' = random alphanumeric with optional `prefix`; 'password' = mixed-case alphanumeric with symbols. Defaults to 'api-key'."
+      ),
+      length: z2.number().optional().describe(
+        "Number of characters (or bytes for hex/base64) to generate. Ignored for 'uuid'. Defaults to a sensible per-format value (e.g. 32 for api-key)."
+      ),
+      prefix: z2.string().optional().describe(
+        "Literal prefix prepended to the random portion. Only meaningful for 'api-key' and 'token'. Example: 'sk-' or 'svc_'."
+      ),
+      saveAs: z2.string().optional().describe(
+        "If provided, store the generated value at this key name in the keyring (one mutation). Omit to just return the value without persisting."
+      ),
       scope: scope.default("global"),
       projectPath,
       teamId,
@@ -584,14 +687,22 @@ function registerSecretTools(server2) {
   );
   server2.tool(
     "entangle_secrets",
-    "[secrets] Link two keys so source updates/rotations propagate the same value to the target (mutates metadata; future writes sync). Reverse with disentangle_secrets without deleting values; do not confuse with set_secret (single-key write). Subject to tool policy.",
+    [
+      "[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 \u2014 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'."
+    ].join(" "),
     {
-      sourceKey: z2.string().describe("Source secret key"),
-      targetKey: z2.string().describe("Target secret key"),
+      sourceKey: z2.string().describe("First secret key in the pair. Example: 'STRIPE_SECRET_KEY'."),
+      targetKey: z2.string().describe("Second secret key to keep in lockstep with the source."),
       sourceScope: scope.default("global"),
       targetScope: scope.default("global"),
-      sourceProjectPath: z2.string().optional(),
-      targetProjectPath: z2.string().optional()
+      sourceProjectPath: z2.string().optional().describe(
+        "Project root for sourceKey when sourceScope='project'. Defaults to the server cwd."
+      ),
+      targetProjectPath: z2.string().optional().describe(
+        "Project root for targetKey when targetScope='project'. Defaults to the server cwd."
+      )
     },
     async (params) => {
       const toolBlock = enforceToolPolicy(
@@ -618,14 +729,18 @@ function registerSecretTools(server2) {
   );
   server2.tool(
     "disentangle_secrets",
-    "[secrets] Remove the sync link between two keys so rotations stop propagating. Does not delete either secret\u2014use delete_secret to erase values. Contrast entangle_secrets (creates link). Safe if the link was already absent; updates metadata; subject to tool policy.",
+    [
+      "[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 \u2014 running on a pair that was never linked returns success without effect. Subject to tool policy. Returns 'Disentangled: SOURCE </> TARGET'."
+    ].join(" "),
     {
-      sourceKey: z2.string().describe("Source secret key"),
-      targetKey: z2.string().describe("Target secret key"),
+      sourceKey: z2.string().describe("First key in the previously linked pair."),
+      targetKey: z2.string().describe("Second key in the previously linked pair."),
       sourceScope: scope.default("global"),
       targetScope: scope.default("global"),
-      sourceProjectPath: z2.string().optional(),
-      targetProjectPath: z2.string().optional()
+      sourceProjectPath: z2.string().optional().describe("Project root for sourceKey when sourceScope='project'."),
+      targetProjectPath: z2.string().optional().describe("Project root for targetKey when targetScope='project'.")
     },
     async (params) => {
       const toolBlock = enforceToolPolicy(
@@ -934,7 +1049,11 @@ var { teamId: teamId2, orgId: orgId2, scope: scope2, projectPath: projectPath2,
 function registerProjectTools(server2) {
   server2.tool(
     "check_project",
-    "[project] Validate project secrets against the .q-ring.json manifest. Returns which required secrets are present, missing, expired, or stale. Use this to verify project readiness.",
+    [
+      "[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."
+    ].join(" "),
     {
       projectPath: projectPath2
     },
@@ -1001,7 +1120,11 @@ function registerProjectTools(server2) {
   );
   server2.tool(
     "env_generate",
-    "[project] Generate .env file content from the project manifest (.q-ring.json). Resolves each declared secret from q-ring, collapses superposition, and returns .env formatted output. Warns about missing or expired secrets.",
+    [
+      "[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."
+    ].join(" "),
     {
       projectPath: projectPath2,
       env: env2
@@ -1048,7 +1171,11 @@ ${warnings.map((w) => `# ${w}`).join("\n")}` : output;
   );
   server2.tool(
     "detect_environment",
-    "[project] Detect the current environment context (wavefunction collapse). Returns the detected environment and its source (NODE_ENV, git branch, project config, etc.).",
+    [
+      "[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."
+    ].join(" "),
     {
       projectPath: projectPath2
     },
@@ -1071,7 +1198,11 @@ ${warnings.map((w) => `# ${w}`).join("\n")}` : output;
   );
   server2.tool(
     "get_project_context",
-    "[agent] Get a safe, redacted overview of the project's secrets, environment, manifest, providers, hooks, and recent audit activity. No secret values are ever exposed. Use this to understand what secrets exist before asking to read them.",
+    [
+      "[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 \u2014 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."
+    ].join(" "),
     {
       scope: scope2,
       projectPath: projectPath2,
@@ -1095,11 +1226,21 @@ import { z as z3 } from "zod";
 function registerTunnelTools(server2) {
   server2.tool(
     "tunnel_create",
-    "[tunnel] Create an ephemeral secret that exists only in memory (quantum tunneling). Never persisted to disk. Optional TTL and max-reads for self-destruction.",
+    [
+      "[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 \u2014 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`."
+    ].join(" "),
     {
-      value: z3.string().describe("The secret value"),
-      ttlSeconds: z3.number().optional().describe("Auto-expire after N seconds"),
-      maxReads: z3.number().optional().describe("Self-destruct after N reads")
+      value: z3.string().describe(
+        "The plaintext value to tunnel. Held only in process memory; never logged."
+      ),
+      ttlSeconds: z3.number().optional().describe(
+        "Auto-destroy the tunnel after this many seconds. Omit for no time limit (then a `maxReads` is highly recommended)."
+      ),
+      maxReads: z3.number().optional().describe(
+        "Self-destruct after this many successful `tunnel_read` calls. Use 1 for true one-shot delivery."
+      )
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("tunnel_create");
@@ -1113,9 +1254,15 @@ function registerTunnelTools(server2) {
   );
   server2.tool(
     "tunnel_read",
-    "[tunnel] Read an ephemeral tunneled secret by ID. May self-destruct if max-reads is reached.",
+    [
+      "[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."
+    ].join(" "),
     {
-      id: z3.string().describe("Tunnel ID")
+      id: z3.string().describe(
+        "The opaque tunnel ID returned by `tunnel_create`. Case-sensitive."
+      )
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("tunnel_read");
@@ -1131,7 +1278,11 @@ function registerTunnelTools(server2) {
   );
   server2.tool(
     "tunnel_list",
-    "[tunnel] List active tunneled secrets (IDs and metadata only, never values).",
+    [
+      "[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."
+    ].join(" "),
     {},
     async () => {
       const toolBlock = enforceToolPolicy("tunnel_list");
@@ -1156,9 +1307,13 @@ function registerTunnelTools(server2) {
   );
   server2.tool(
     "tunnel_destroy",
-    "[tunnel] Immediately destroy a tunneled secret.",
+    [
+      "[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."
+    ].join(" "),
     {
-      id: z3.string().describe("Tunnel ID")
+      id: z3.string().describe("The opaque tunnel ID to destroy.")
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("tunnel_destroy");
@@ -1187,7 +1342,8 @@ var ALGORITHM = "aes-256-gcm";
 var KEY_LENGTH = 32;
 var IV_LENGTH = 12;
 var SALT_LENGTH = 32;
-var PBKDF2_ITERATIONS = 1e5;
+var PBKDF2_ITERATIONS = 21e4;
+var LEGACY_PBKDF2_ITERATIONS = 1e5;
 var TeleportBundleSchema = z4.object({
   v: z4.literal(1),
   data: z4.string(),
@@ -1195,7 +1351,8 @@ var TeleportBundleSchema = z4.object({
   iv: z4.string(),
   tag: z4.string(),
   createdAt: z4.string(),
-  count: z4.number()
+  count: z4.number(),
+  iter: z4.number().optional()
 });
 var TeleportPayloadSchema = z4.object({
   secrets: z4.array(
@@ -1208,8 +1365,8 @@ var TeleportPayloadSchema = z4.object({
   exportedAt: z4.string(),
   exportedBy: z4.string().optional()
 });
-function deriveKey(passphrase, salt) {
-  return pbkdf2Sync(passphrase, salt, PBKDF2_ITERATIONS, KEY_LENGTH, "sha512");
+function deriveKey(passphrase, salt, iterations = PBKDF2_ITERATIONS) {
+  return pbkdf2Sync(passphrase, salt, iterations, KEY_LENGTH, "sha512");
 }
 function teleportPack(secrets, passphrase) {
   const payload = {
@@ -1219,7 +1376,7 @@ function teleportPack(secrets, passphrase) {
   const plaintext = JSON.stringify(payload);
   const salt = randomBytes2(SALT_LENGTH);
   const iv = randomBytes2(IV_LENGTH);
-  const key = deriveKey(passphrase, salt);
+  const key = deriveKey(passphrase, salt, PBKDF2_ITERATIONS);
   const cipher = createCipheriv(ALGORITHM, key, iv);
   const encrypted = Buffer.concat([
     cipher.update(plaintext, "utf8"),
@@ -1233,7 +1390,8 @@ function teleportPack(secrets, passphrase) {
     iv: iv.toString("base64"),
     tag: tag.toString("base64"),
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-    count: secrets.length
+    count: secrets.length,
+    iter: PBKDF2_ITERATIONS
   };
   return Buffer.from(JSON.stringify(bundle)).toString("base64");
 }
@@ -1261,7 +1419,7 @@ function teleportUnpack(encoded, passphrase) {
   const iv = Buffer.from(bundle.iv, "base64");
   const tag = Buffer.from(bundle.tag, "base64");
   const encrypted = Buffer.from(bundle.data, "base64");
-  const key = deriveKey(passphrase, salt);
+  const key = deriveKey(passphrase, salt, bundle.iter ?? LEGACY_PBKDF2_ITERATIONS);
   const decipher = createDecipheriv(ALGORITHM, key, iv);
   decipher.setAuthTag(tag);
   let decrypted;
@@ -1293,10 +1451,18 @@ var { teamId: teamId3, orgId: orgId3, scope: scope3, projectPath: projectPath3 }
 function registerTeleportTools(server2) {
   server2.tool(
     "teleport_pack",
-    "[teleport] Pack secrets into an AES-256-GCM encrypted bundle for sharing between machines (quantum teleportation).",
+    [
+      "[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."
+    ].join(" "),
     {
-      keys: z5.array(z5.string()).optional().describe("Specific keys to pack (all if omitted)"),
-      passphrase: z5.string().describe("Encryption passphrase"),
+      keys: z5.array(z5.string()).optional().describe(
+        "Whitelist of exact key names to include. Omit to pack every secret in the requested scope."
+      ),
+      passphrase: z5.string().describe(
+        "Symmetric passphrase used to derive the AES-256-GCM key. The receiver must supply the same string to `teleport_unpack`. Pick something high-entropy and share it out-of-band."
+      ),
       scope: scope3,
       projectPath: projectPath3,
       teamId: teamId3,
@@ -1322,15 +1488,25 @@ function registerTeleportTools(server2) {
   );
   server2.tool(
     "teleport_unpack",
-    "[teleport] Decrypt and import secrets from a teleport bundle.",
+    [
+      "[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."
+    ].join(" "),
     {
-      bundle: z5.string().describe("Base64-encoded encrypted bundle"),
-      passphrase: z5.string().describe("Decryption passphrase"),
+      bundle: z5.string().describe(
+        "Base64-encoded ciphertext returned by `teleport_pack`. Pass through whitespace untouched if possible."
+      ),
+      passphrase: z5.string().describe(
+        "The same passphrase that was used to pack this bundle. Bad passphrases return an authentication error rather than wrong plaintext."
+      ),
       scope: scope3.default("global"),
       projectPath: projectPath3,
       teamId: teamId3,
       orgId: orgId3,
-      dryRun: z5.boolean().optional().default(false).describe("Preview without importing")
+      dryRun: z5.boolean().optional().default(false).describe(
+        "If true, decrypt and report what would be written but do not mutate the keyring. Useful for verifying bundle contents before commit."
+      )
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("teleport_unpack", params.projectPath);
@@ -1365,9 +1541,15 @@ var { teamId: teamId4, orgId: orgId4, scope: scope4, projectPath: projectPath4 }
 function registerAuditTools(server2) {
   server2.tool(
     "audit_log",
-    "[audit] Query the audit log for secret access history (observer effect). Shows who accessed what and when.",
+    [
+      "[audit] Query the q-ring audit log \u2014 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."
+    ].join(" "),
     {
-      key: z6.string().optional().describe("Filter by key"),
+      key: z6.string().optional().describe(
+        "Limit to events touching this exact key. Omit for the full log."
+      ),
       action: z6.enum([
         "read",
         "write",
@@ -1379,8 +1561,12 @@ function registerAuditTools(server2) {
         "tunnel",
         "teleport",
         "collapse"
-      ]).optional().describe("Filter by action"),
-      limit: z6.number().optional().default(20).describe("Max events to return")
+      ]).optional().describe(
+        "Limit to a single action verb (e.g. 'read' to see only reads). Omit for all actions."
+      ),
+      limit: z6.number().optional().default(20).describe(
+        "Maximum events to return, newest first. Defaults to 20. Increase for deeper investigations."
+      )
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("audit_log");
@@ -1404,9 +1590,15 @@ function registerAuditTools(server2) {
   );
   server2.tool(
     "detect_anomalies",
-    "[audit] Read-only scan of audit history for burst reads and unusual-hour access (text lines per finding). Optional key filter. Use health_check for full decay inventory + anomaly count in scope; use agent_scan for multi-project JSON reports or optional auto-rotation. Does not mutate secrets.",
+    [
+      "[audit] Scan the audit history for suspicious access patterns \u2014 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."
+    ].join(" "),
     {
-      key: z6.string().optional().describe("Check anomalies for a specific key")
+      key: z6.string().optional().describe(
+        "If provided, narrow the scan to this exact key. Omit to scan across every key in the audit log."
+      )
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("detect_anomalies");
@@ -1419,7 +1611,11 @@ function registerAuditTools(server2) {
   );
   server2.tool(
     "health_check",
-    "[health] Read-only scoped pass: decay/stale/expired counts, per-secret issue lines, plus audit-derived anomalies. No writes. Use check_project for .q-ring.json manifest compliance; use detect_anomalies for audit-pattern-only triage; use agent_scan for multi-project JSON or optional autoRotate credential replacement.",
+    [
+      "[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 \u2014 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."
+    ].join(" "),
     {
       scope: scope4,
       projectPath: projectPath4,
@@ -1473,7 +1669,11 @@ function registerAuditTools(server2) {
   );
   server2.tool(
     "verify_audit_chain",
-    "[audit] Verify the tamper-evident hash chain of the audit log. Returns integrity status and the first break point if tampered.",
+    [
+      "[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 \u2014 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."
+    ].join(" "),
     {},
     async () => {
       const toolBlock = enforceToolPolicy("verify_audit_chain");
@@ -1484,11 +1684,21 @@ function registerAuditTools(server2) {
   );
   server2.tool(
     "export_audit",
-    "[audit] Export audit events in a portable format (jsonl, json, or csv) with optional time range filtering.",
+    [
+      "[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."
+    ].join(" "),
     {
-      since: z6.string().optional().describe("Start date (ISO 8601)"),
-      until: z6.string().optional().describe("End date (ISO 8601)"),
-      format: z6.enum(["jsonl", "json", "csv"]).optional().default("jsonl").describe("Output format")
+      since: z6.string().optional().describe(
+        "Inclusive lower bound on event timestamp, ISO 8601. Example: '2026-04-01T00:00:00Z'. Omit for no lower bound."
+      ),
+      until: z6.string().optional().describe(
+        "Inclusive upper bound on event timestamp, ISO 8601. Omit for now/no upper bound."
+      ),
+      format: z6.enum(["jsonl", "json", "csv"]).optional().default("jsonl").describe(
+        "Output format. 'jsonl' (default) is most stream-friendly; 'json' is a single array; 'csv' is spreadsheet-friendly."
+      )
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("export_audit");
@@ -1509,10 +1719,18 @@ var { teamId: teamId5, orgId: orgId5, scope: scope5, projectPath: projectPath5 }
 function registerValidationTools(server2) {
   server2.tool(
     "validate_secret",
-    "[validation] Test if a secret is actually valid with its target service (e.g., OpenAI, Stripe, GitHub). Uses provider auto-detection based on key prefixes, or accepts an explicit provider name. Never logs the secret value.",
+    [
+      "[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)."
+    ].join(" "),
     {
-      key: z7.string().describe("The secret key name"),
-      provider: z7.string().optional().describe("Force a specific provider (openai, stripe, github, aws, http)"),
+      key: z7.string().describe(
+        "The exact key whose value should be tested upstream. Example: 'OPENAI_API_KEY'."
+      ),
+      provider: z7.string().optional().describe(
+        "Force a specific provider id. Built-ins include 'openai', 'stripe', 'github', 'aws', 'http'. Omit to auto-detect from the value's prefix or the secret's stored provider hint."
+      ),
       scope: scope5,
       projectPath: projectPath5,
       teamId: teamId5,
@@ -1531,7 +1749,11 @@ function registerValidationTools(server2) {
   );
   server2.tool(
     "list_providers",
-    "[validation] List all available validation providers for secret liveness testing.",
+    [
+      "[validation] Enumerate the secret-validation providers q-ring knows how to call (OpenAI, Stripe, GitHub, \u2026) 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."
+    ].join(" "),
     {},
     async () => {
       const toolBlock = enforceToolPolicy("list_providers");
@@ -1546,10 +1768,16 @@ function registerValidationTools(server2) {
   );
   server2.tool(
     "rotate_secret",
-    "[validation] Attempt issuer-native rotation of a secret via its detected or specified provider. Returns rotation result.",
+    [
+      "[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."
+    ].join(" "),
     {
-      key: z7.string().describe("The secret key to rotate"),
-      provider: z7.string().optional().describe("Force a specific provider"),
+      key: z7.string().describe("Exact key to rotate. Must already exist in the keyring."),
+      provider: z7.string().optional().describe(
+        "Force a specific provider id (see `list_providers`). Omit to auto-detect from the current value or the secret's stored provider hint."
+      ),
       scope: scope5,
       projectPath: projectPath5,
       teamId: teamId5,
@@ -1573,7 +1801,11 @@ function registerValidationTools(server2) {
   );
   server2.tool(
     "ci_validate_secrets",
-    "[validation] CI-oriented batch validation: validates all accessible secrets against their providers and returns a structured pass/fail report.",
+    [
+      "[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."
+    ].join(" "),
     {
       scope: scope5,
       projectPath: projectPath5,
@@ -1613,19 +1845,45 @@ import { z as z8 } from "zod";
 function registerHookTools(server2) {
   server2.tool(
     "register_hook",
-    "[hooks] Register a webhook/callback that fires when a secret is updated, deleted, or rotated. Supports shell commands, HTTP webhooks, and process signals.",
+    [
+      "[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 \u2014 calls without any return an error. Returns JSON of the registered hook entry including its assigned `id` (use that `id` with `remove_hook`)."
+    ].join(" "),
     {
-      type: z8.enum(["shell", "http", "signal"]).describe("Hook type"),
-      key: z8.string().optional().describe("Trigger on exact key match"),
-      keyPattern: z8.string().optional().describe("Trigger on key glob pattern (e.g. DB_*)"),
-      tag: z8.string().optional().describe("Trigger on secrets with this tag"),
-      scope: z8.enum(["global", "project"]).optional().describe("Trigger only for this scope"),
-      actions: z8.array(z8.enum(["write", "delete", "rotate"])).optional().default(["write", "delete", "rotate"]).describe("Which actions trigger this hook"),
-      command: z8.string().optional().describe("Shell command to execute (for shell type)"),
-      url: z8.string().optional().describe("URL to POST to (for http type)"),
-      signalTarget: z8.string().optional().describe("Process name or PID (for signal type)"),
-      signalName: z8.string().optional().default("SIGHUP").describe("Signal to send (for signal type)"),
-      description: z8.string().optional().describe("Human-readable description")
+      type: z8.enum(["shell", "http", "signal"]).describe(
+        "Hook delivery mechanism. 'shell' runs a local command, 'http' POSTs JSON to a URL, 'signal' sends an OS signal to a named process."
+      ),
+      key: z8.string().optional().describe(
+        "Trigger only on this exact key name. Pick at most one of `key` / `keyPattern` / `tag` (or combine for stricter matching)."
+      ),
+      keyPattern: z8.string().optional().describe(
+        "Trigger on any key matching this glob pattern. Examples: 'DB_*', 'STRIPE_*'."
+      ),
+      tag: z8.string().optional().describe(
+        "Trigger on any secret carrying this exact tag. Combinable with key/keyPattern as an AND filter."
+      ),
+      scope: z8.enum(["global", "project"]).optional().describe(
+        "Restrict the hook to secrets in this scope. Omit to fire across both global and project secrets."
+      ),
+      actions: z8.array(z8.enum(["write", "delete", "rotate"])).optional().default(["write", "delete", "rotate"]).describe(
+        "Which lifecycle actions trigger this hook. Defaults to all three."
+      ),
+      command: z8.string().optional().describe(
+        "Required when type='shell'. The literal shell command to run; q-ring exposes the matching key as $QRING_HOOK_KEY and action as $QRING_HOOK_ACTION."
+      ),
+      url: z8.string().optional().describe(
+        "Required when type='http'. Full URL to POST a JSON body `{ id, key, scope, action, timestamp }` to (the value itself is never sent)."
+      ),
+      signalTarget: z8.string().optional().describe(
+        "Required when type='signal'. Either a numeric PID or a process name resolvable via `ps`."
+      ),
+      signalName: z8.string().optional().default("SIGHUP").describe(
+        "Signal name to send (e.g. 'SIGHUP', 'SIGUSR1'). Defaults to SIGHUP, which most daemons treat as 'reload config'."
+      ),
+      description: z8.string().optional().describe(
+        "Free-text human-readable description, surfaced by `list_hooks` and the dashboard."
+      )
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("register_hook");
@@ -1656,7 +1914,11 @@ function registerHookTools(server2) {
   );
   server2.tool(
     "list_hooks",
-    "[hooks] List all registered secret change hooks with their match criteria, type, and status.",
+    [
+      "[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."
+    ].join(" "),
     {},
     async () => {
       const toolBlock = enforceToolPolicy("list_hooks");
@@ -1668,9 +1930,15 @@ function registerHookTools(server2) {
   );
   server2.tool(
     "remove_hook",
-    "[hooks] Remove a lifecycle hook entry by id from the hook registry only (stops callbacks; does not touch secret values). Call list_hooks first for ids. Contrast delete_secret (credential removal) or tunnel_destroy (ephemeral tunnel). Returns success or not-found; subject to tool policy.",
+    [
+      "[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 \u2014 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."
+    ].join(" "),
     {
-      id: z8.string().describe("Hook ID to remove")
+      id: z8.string().describe(
+        "Hook id returned by `register_hook` or visible in `list_hooks` (opaque string)."
+      )
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("remove_hook");
@@ -1920,7 +2188,8 @@ async function execCommand(opts2) {
       "dig",
       "nslookup"
     ]);
-    if (profile.allowNetwork === false && networkTools.has(opts2.command)) {
+    const commandBase = opts2.command.split(/[\\/]/).pop() ?? opts2.command;
+    if (profile.allowNetwork === false && networkTools.has(commandBase)) {
       const msg = `[QRING] Execution blocked: network access is disabled for profile "${profile.name}", command "${opts2.command}" is considered network-related`;
       if (opts2.captureOutput) {
         return resolve({ code: 126, stdout: "", stderr: msg });
@@ -2203,13 +2472,27 @@ var { teamId: teamId6, orgId: orgId6, scope: scope6, projectPath: projectPath6 }
 function registerToolingTools(server2) {
   server2.tool(
     "exec_with_secrets",
-    "[exec] Run a shell command securely. Project secrets are injected into the environment, and any secret values in the output are automatically redacted to prevent leaking into transcripts.",
+    [
+      "[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 \u2014 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."
+    ].join(" "),
     {
-      command: z9.string().describe("Command to run"),
-      args: z9.array(z9.string()).optional().describe("Command arguments"),
-      keys: z9.array(z9.string()).optional().describe("Only inject these specific keys"),
-      tags: z9.array(z9.string()).optional().describe("Only inject secrets with these tags"),
-      profile: z9.enum(["unrestricted", "restricted", "ci"]).optional().default("restricted").describe("Exec profile: unrestricted, restricted, or ci"),
+      command: z9.string().describe(
+        "Executable name or full command to run. Example: 'pnpm', 'node', '/usr/bin/env'. Must be allowed by exec policy."
+      ),
+      args: z9.array(z9.string()).optional().describe(
+        "Positional arguments passed to `command`. Example: ['run', 'db:migrate']. Each element is passed verbatim with no extra shell parsing."
+      ),
+      keys: z9.array(z9.string()).optional().describe(
+        "Whitelist of exact key names to inject. Omit to inject every secret in scope (subject to `tags`)."
+      ),
+      tags: z9.array(z9.string()).optional().describe(
+        "Inject only secrets carrying at least one of these tags. Combinable with `keys` as an AND filter."
+      ),
+      profile: z9.enum(["unrestricted", "restricted", "ci"]).optional().default("restricted").describe(
+        "Exec sandbox profile. 'restricted' (default) limits PATH and inheritable env vars; 'ci' is restricted plus CI-friendly defaults (no TTY); 'unrestricted' inherits the full server environment \u2014 only pick this when you understand the leak risk."
+      ),
       scope: scope6,
       projectPath: projectPath6,
       teamId: teamId6,
@@ -2251,9 +2534,15 @@ ${result.stderr}`);
   );
   server2.tool(
     "scan_codebase_for_secrets",
-    "[scan] Scan a directory for hardcoded secrets using regex heuristics and Shannon entropy analysis. Returns file paths, line numbers, and the matched key/value to help migrate legacy codebases into q-ring.",
+    [
+      "[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 \u2014 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 \u2014 review before treating as ground truth."
+    ].join(" "),
     {
-      dirPath: z9.string().describe("Absolute or relative path to the directory to scan")
+      dirPath: z9.string().describe(
+        "Directory to scan, absolute or relative to the server cwd. The scan recurses into subdirectories."
+      )
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("scan_codebase_for_secrets");
@@ -2274,10 +2563,18 @@ ${result.stderr}`);
   );
   server2.tool(
     "lint_files",
-    "[scan] Scan specific files for hardcoded secrets. Optionally auto-fix by replacing them with process.env references and storing the values in q-ring.",
+    [
+      "[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.'."
+    ].join(" "),
     {
-      files: z9.array(z9.string()).describe("File paths to lint"),
-      fix: z9.boolean().optional().default(false).describe("Auto-replace and store secrets"),
+      files: z9.array(z9.string()).describe(
+        "Absolute or relative paths to lint. Non-existent paths surface as scan errors."
+      ),
+      fix: z9.boolean().optional().default(false).describe(
+        "If true, rewrite the source files to read `process.env.KEY` and store the extracted value in the keyring. If false (default), only report findings."
+      ),
       scope: scope6,
       projectPath: projectPath6,
       teamId: teamId6,
@@ -2306,7 +2603,11 @@ ${result.stderr}`);
   );
   server2.tool(
     "analyze_secrets",
-    "[agent] Analyze secret usage patterns and provide optimization suggestions including most accessed, stale, unused, and rotation recommendations.",
+    [
+      "[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."
+    ].join(" "),
     {
       scope: scope6,
       projectPath: projectPath6,
@@ -2339,32 +2640,46 @@ ${result.stderr}`);
   let dashboardInstance = null;
   server2.tool(
     "status_dashboard",
-    "[dashboard] Launch the quantum status dashboard \u2014 a local SSE-driven web page showing live KPIs (secrets, env, protected, approvals, hooks, 24h reads, anomalies), health summary, environment, .q-ring.json manifest gaps, governance policy summary, sortable searchable secrets table, decay/superposition/entanglement/tunnel cards, active approvals & hooks, agent memory, anomaly alerts, and a filterable 24h audit feed. Returns the URL to open in a browser. Never exposes secret values.",
+    [
+      "[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 \u2014 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."
+    ].join(" "),
     {
-      port: z9.number().optional().default(9876).describe("Port to serve on")
+      port: z9.number().optional().default(9876).describe(
+        "TCP port to listen on (default 9876). Pick another port if 9876 is already in use; the call fails if binding errors."
+      )
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("status_dashboard");
       if (toolBlock) return toolBlock;
       if (dashboardInstance) {
         return text(
-          `Dashboard already running at http://127.0.0.1:${dashboardInstance.port}`
+          `Dashboard already running at ${dashboardInstance.url}`
         );
       }
-      const { startDashboardServer } = await import("./dashboard-FSCJDLJX.js");
+      const { startDashboardServer } = await import("./dashboard-HHJY73JX.js");
       dashboardInstance = startDashboardServer({ port: params.port });
       return text(
-        `Dashboard started at http://127.0.0.1:${dashboardInstance.port}
-Open this URL in a browser to see live quantum status.`
+        `Dashboard started at ${dashboardInstance.url}
+Open this URL in a browser to see live quantum status. The token is required for access.`
       );
     }
   );
   server2.tool(
     "agent_scan",
-    "[agent] Multi-project health pass: decay, staleness, audit anomalies, manifest gaps; returns JSON. Prefer health_check for a read-only scoped decay/anomaly text summary (no writes). Prefer detect_anomalies for audit-pattern spikes on one key. With autoRotate=true, overwrites expired secret values in the keyring (credential change\u2014not undoable); leave false unless intentional rotation. Same policy gates as other MCP tools; no separate external auth.",
+    [
+      "[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 \u2014 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."
+    ].join(" "),
     {
-      autoRotate: z9.boolean().optional().default(false).describe("Auto-rotate expired secrets with generated values"),
-      projectPaths: z9.array(z9.string()).optional().describe("Project paths to monitor")
+      autoRotate: z9.boolean().optional().default(false).describe(
+        "If true, replace expired secrets with newly generated values (using each secret's `rotationFormat`/`rotationPrefix`). Only enable when intentional rotation is desired \u2014 this is destructive on the upstream side."
+      ),
+      projectPaths: z9.array(z9.string()).optional().describe(
+        "List of absolute project roots to scan. Defaults to `[server.cwd]` when omitted."
+      )
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("agent_scan");
@@ -2383,10 +2698,18 @@ import { z as z10 } from "zod";
 function registerAgentTools(server2) {
   server2.tool(
     "agent_remember",
-    "[agent] Store a key-value pair in encrypted agent memory that persists across sessions. Use this to remember decisions, rotation history, or project-specific context.",
+    [
+      "[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 \u2014 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.`
+    ].join(" "),
     {
-      key: z10.string().describe("Memory key"),
-      value: z10.string().describe("Value to store")
+      key: z10.string().describe(
+        "Memory key (free-form string). Convention: lowercase dotted namespaces, e.g. 'project.lastDeploy'."
+      ),
+      value: z10.string().describe(
+        "Plain-string value to store. JSON-stringify structured data on the caller side if needed."
+      )
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("agent_remember");
@@ -2397,9 +2720,15 @@ function registerAgentTools(server2) {
   );
   server2.tool(
     "agent_recall",
-    "[agent] Retrieve a value from agent memory, or list all stored keys if no key is provided.",
+    [
+      "[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'."
+    ].join(" "),
     {
-      key: z10.string().optional().describe("Memory key to recall (omit to list all)")
+      key: z10.string().optional().describe(
+        "Memory key to read. Omit to list every stored key (without values)."
+      )
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("agent_recall");
@@ -2419,9 +2748,13 @@ function registerAgentTools(server2) {
   );
   server2.tool(
     "agent_forget",
-    "[agent] Delete a key from agent memory.",
+    [
+      "[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.`
+    ].join(" "),
     {
-      key: z10.string().describe("Memory key to forget")
+      key: z10.string().describe("Memory key to delete.")
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("agent_forget");
@@ -2441,12 +2774,24 @@ var { projectPath: projectPath7 } = commonSchemas;
 function registerPolicyTools(server2) {
   server2.tool(
     "check_policy",
-    "[policy] Check if an action is allowed by the project's governance policy. Returns the policy decision and source.",
+    [
+      "[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."
+    ].join(" "),
     {
-      action: z11.enum(["tool", "key_read", "exec"]).describe("Type of policy check"),
-      toolName: z11.string().optional().describe("Tool name to check (for action=tool)"),
-      key: z11.string().optional().describe("Secret key to check (for action=key_read)"),
-      command: z11.string().optional().describe("Command to check (for action=exec)"),
+      action: z11.enum(["tool", "key_read", "exec"]).describe(
+        "Which policy surface to query. 'tool' = MCP tool gate (needs `toolName`); 'key_read' = secret read gate (needs `key`); 'exec' = exec_with_secrets command gate (needs `command`)."
+      ),
+      toolName: z11.string().optional().describe(
+        "Tool id to evaluate, e.g. 'rotate_secret'. Required when `action` is 'tool'."
+      ),
+      key: z11.string().optional().describe(
+        "Secret key name to evaluate. Required when `action` is 'key_read'."
+      ),
+      command: z11.string().optional().describe(
+        "Command to evaluate against the exec allowlist/denylist. Required when `action` is 'exec'."
+      ),
       projectPath: projectPath7
     },
     async (params) => {
@@ -2470,7 +2815,11 @@ function registerPolicyTools(server2) {
   );
   server2.tool(
     "get_policy_summary",
-    "[policy] Get a summary of the project's governance policy configuration.",
+    [
+      "[policy] Return a high-level summary of the project's `.q-ring.json` governance policy \u2014 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."
+    ].join(" "),
     {
       projectPath: projectPath7
     },
@@ -2502,6 +2851,7 @@ function registerMcpTools(server2) {
 
 // src/mcp/server.ts
 function createMcpServer() {
+  setPolicyRoot(process.cwd());
   const server2 = new McpServer({
     name: "q-ring",
     version: PACKAGE_VERSION