feat: v0.11.7 — Glama TDQS overhaul for all 44 MCP tools

.cursor-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "qring",
       "source": "cursor-plugin",
       "description": "Quantum keyring for AI agents — manage secrets, scan for leaks, rotate keys, and enforce policy directly from Cursor.",
-      "version": "0.11.5",
+      "version": "0.11.7",
       "keywords": [
         "secrets",
         "keyring",

CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.11.7] — 2026-04-27
+
+### Changed
+- **MCP tool descriptions overhauled for Glama TDQS** — every one of the 44 MCP tools now ships a 3-sentence description hitting all six [Tool Definition Quality Score](https://glama.ai/blog/2026-04-03-tool-definition-quality-score-tdqs) dimensions (purpose, when-to-use vs. siblings, side effects/audit/network, parameter semantics, conciseness, returns). Common parameter schemas (`scope`, `projectPath`, `env`, `teamId`, `orgId`) and per-tool Zod `.describe()` strings now include formats, defaults, and concrete examples to lift the per-tool minimum score (which dominates the server-level grade at 60% mean / 40% min). README MCP tables resynced with the new one-liners.
+- **`feature-docs-sync.mdc` rule rewritten** — drops stale `web/components/...` globs (the marketing site was extracted to its own repo in 0.11.5) and replaces them with an explicit `quantum_ring` ↔ `qring.i4c.studio` cross-repo file mapping covering `lib/data/{features,mcp-tools,cli-commands,cli-reference,changelog,version}.ts`.
+- **`release-process.mdc` rule** — `Downstream Sync` table now lists the marketing site, Cursor plugin, Kiro plugin, and Claude Code plugin alongside Glama, with explicit commands and a note that the marketing-site sync is not enforced by `quantum_ring` CI.
+
+### Notes
+- No runtime / MCP wire-format changes — this is a documentation-quality release. Existing agents and integrations will see longer, clearer tool descriptions and richer parameter help when they next refresh `tools/list`, but tool names, parameter names, and return shapes are unchanged.
+- After publish, trigger a Glama re-sync from the admin panel so the new descriptions feed the next TDQS scoring run.
+
 ## [0.11.5] — 2026-04-27
 
 ### Added

README.md

@@ -663,95 +663,95 @@ q-ring includes a full MCP server with 44 tools for AI agent integration.
 
 | Tool | Description |
 |------|-------------|
-| `get_secret` | Retrieve with superposition collapse + observer logging |
-| `list_secrets` | List keys with quantum metadata, filterable by tag/expiry/pattern |
-| `set_secret` | Store with optional TTL, env state, tags, rotation format |
-| `delete_secret` | Remove a secret |
-| `has_secret` | Boolean check (respects decay) |
-| `export_secrets` | Export as .env/JSON with optional key and tag filters |
-| `import_dotenv` | Parse and import secrets from .env content |
-| `check_project` | Validate project secrets against `.q-ring.json` manifest |
-| `env_generate` | Generate .env content from the project manifest |
+| `get_secret` | Read a secret value (collapses superposition, audits the read) |
+| `list_secrets` | List keys + metadata in scope (values never exposed); filter by tag, expiry, glob |
+| `set_secret` | Create or overwrite a single secret with optional TTL, per-env state, tags, rotation format |
+| `delete_secret` | Permanently remove a secret value (not undoable from q-ring) |
+| `has_secret` | Boolean existence check that respects decay (no audit read) |
+| `export_secrets` | Render multiple secrets as `.env` or JSON for one-off export |
+| `import_dotenv` | Parse `.env` text and bulk-store every key/value pair |
+| `check_project` | Compare `.q-ring.json` manifest against the keyring for missing/expired/stale keys |
+| `env_generate` | Render a complete `.env` body from the project manifest, with warnings for gaps |
 
 ### Quantum Tools
 
 | Tool | Description |
 |------|-------------|
-| `inspect_secret` | Full quantum state (states, decay, entanglement, access count) |
-| `detect_environment` | Wavefunction collapse — detect current env context |
-| `generate_secret` | Quantum noise — generate and optionally save secrets |
-| `entangle_secrets` | Link two secrets for synchronized rotation |
-| `disentangle_secrets` | Remove entanglement between two secrets |
+| `inspect_secret` | Show metadata for one key (states, decay, entanglement, access count) without revealing the value |
+| `detect_environment` | Resolve which env slug should drive superposition collapse for the current context |
+| `generate_secret` | Generate a CSPRNG-backed value in a chosen format and optionally store it |
+| `entangle_secrets` | Link two keys so future writes/rotations propagate the same value |
+| `disentangle_secrets` | Break the sync link between two keys (does not delete values) |
 
 ### Tunneling Tools
 
 | Tool | Description |
 |------|-------------|
-| `tunnel_create` | Create ephemeral in-memory secret |
-| `tunnel_read` | Read (may self-destruct) |
-| `tunnel_list` | List active tunnels |
-| `tunnel_destroy` | Immediately destroy |
+| `tunnel_create` | Stash a value in process memory and return an opaque ID (never touches disk) |
+| `tunnel_read` | Fetch a tunneled value by ID — may self-destruct on read |
+| `tunnel_list` | Enumerate active tunnels with remaining read budget and TTL (IDs only) |
+| `tunnel_destroy` | Immediately remove a tunnel from memory before its TTL/reads run out |
 
 ### Teleportation Tools
 
 | Tool | Description |
 |------|-------------|
-| `teleport_pack` | Encrypt secrets into a portable bundle |
-| `teleport_unpack` | Decrypt and import a bundle |
+| `teleport_pack` | Encrypt selected secrets into a passphrase-protected AES-256-GCM bundle |
+| `teleport_unpack` | Decrypt a teleport bundle and import each secret (with optional dry-run) |
 
 ### Validation Tools
 
 | Tool | Description |
 |------|-------------|
-| `validate_secret` | Test if a secret is valid with its target service (OpenAI, Stripe, GitHub, etc.) |
-| `list_providers` | List all available validation providers |
+| `validate_secret` | Hit the upstream service (OpenAI/Stripe/GitHub/AWS/HTTP) to confirm a single key is still live |
+| `list_providers` | Enumerate built-in validation providers and their auto-detect prefixes |
 
 ### Hook Tools
 
 | Tool | Description |
 |------|-------------|
-| `register_hook` | Register a shell/HTTP/signal callback on secret changes |
-| `list_hooks` | List all registered hooks with match criteria and status |
-| `remove_hook` | Remove a registered hook by ID |
+| `register_hook` | Register a shell/HTTP/signal side-effect that fires on write/delete/rotate |
+| `list_hooks` | Show every registered hook with match criteria, type, and enabled flag |
+| `remove_hook` | Detach a single hook by ID without touching any secrets |
 
 ### Execution & Scanning Tools
 
 | Tool | Description |
 |------|-------------|
-| `exec_with_secrets` | Run a shell command securely with secrets injected, auto-redacted output, and exec profile enforcement |
-| `scan_codebase_for_secrets` | Scan a directory for hardcoded secrets using regex heuristics and entropy analysis |
-| `lint_files` | Lint specific files for hardcoded secrets with optional auto-fix |
+| `exec_with_secrets` | Run a child command with secrets injected as env vars and any leaked values redacted from output |
+| `scan_codebase_for_secrets` | Walk a directory tree and flag hardcoded secrets via regex + entropy heuristics |
+| `lint_files` | Inspect a specific file list for hardcoded secrets with optional auto-fix to `process.env.KEY` |
 
 ### AI Agent Tools
 
 | Tool | Description |
 |------|-------------|
-| `get_project_context` | Safe, redacted overview of project secrets, environment, manifest, and activity |
-| `agent_remember` | Store a key-value pair in encrypted agent memory (persists across sessions) |
-| `agent_recall` | Retrieve from agent memory, or list all stored keys |
-| `agent_forget` | Delete a key from agent memory |
-| `analyze_secrets` | Usage analytics: most accessed, stale, unused, and rotation recommendations |
+| `get_project_context` | Single redacted snapshot of secrets, env, manifest, hooks, and recent audit activity |
+| `agent_remember` | Persist a non-secret note in encrypted agent memory across sessions |
+| `agent_recall` | Read a memory value, or list every stored key when no key is supplied |
+| `agent_forget` | Permanently delete a key from agent memory |
+| `analyze_secrets` | Usage profile: most-accessed, stale, never-accessed, no-rotation candidates |
 
 ### Observer & Health Tools
 
 | Tool | Description |
 |------|-------------|
-| `audit_log` | Query access history |
-| `detect_anomalies` | Scan for unusual access patterns |
-| `verify_audit_chain` | Verify tamper-evident hash chain integrity |
-| `export_audit` | Export audit events in jsonl, json, or csv format |
-| `health_check` | Full health report |
-| `status_dashboard` | Launch the quantum status dashboard (SSE) — live KPIs, health, secrets table, manifest, policy, approvals, hooks, agent memory, anomalies, and audit feed |
-| `agent_scan` | Run autonomous agent scan |
+| `audit_log` | Query the tamper-evident audit log filtered by key, action, and limit |
+| `detect_anomalies` | Surface burst-read and off-hours findings from audit history |
+| `verify_audit_chain` | Recompute the audit hash chain and report the first break point if tampered |
+| `export_audit` | Export audit events as jsonl, json, or csv for archival/SIEM |
+| `health_check` | Read-only scope sweep: decay/stale/expired counts plus current anomalies |
+| `status_dashboard` | Start a local SSE dashboard with live KPIs, secrets, hooks, and audit feed |
+| `agent_scan` | Multi-project health pass with optional `autoRotate` for expired secrets |
 
 ### Governance & Policy Tools
 
 | Tool | Description |
 |------|-------------|
-| `check_policy` | Check if an action (tool use, key read, exec) is allowed by project policy |
-| `get_policy_summary` | Get a summary of the project's governance policy configuration |
-| `rotate_secret` | Attempt issuer-native rotation via detected or specified provider |
-| `ci_validate_secrets` | CI-oriented batch validation of all secrets with structured pass/fail report |
+| `check_policy` | Dry-run a tool/key/exec action against `.q-ring.json` policy without performing it |
+| `get_policy_summary` | High-level overview of policy rule counts and approval/rotation requirements |
+| `rotate_secret` | Ask the upstream provider to issue a new credential and store it back in the keyring |
+| `ci_validate_secrets` | Batch-validate every accessible secret in scope and return a structured pass/fail report |
 
 ### Cursor / Kiro Configuration
 

cursor-plugin/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "qring",
   "description": "Quantum keyring for AI agents — manage secrets, scan for leaks, rotate keys, and enforce policy directly from Cursor.",
-  "version": "0.11.5",
+  "version": "0.11.7",
   "author": {
     "name": "I4cTime"
   },

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4ctime/q-ring",
-  "version": "0.11.5",
+  "version": "0.11.7",
   "mcpName": "io.github.I4cTime/q-ring",
   "description": "Quantum keyring for AI coding tools — Cursor, Kiro, Claude Code. Secrets, superposition, entanglement, MCP.",
   "type": "module",

server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/I4cTime/quantum_ring",
     "source": "github"
   },
-  "version": "0.11.5",
+  "version": "0.11.7",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@i4ctime/q-ring",
-      "version": "0.11.5",
+      "version": "0.11.7",
       "transport": {
         "type": "stdio"
       }

src/mcp/tools/_shared.ts

@@ -52,21 +52,31 @@ export const commonSchemas = {
   teamId: z
     .string()
     .optional()
-    .describe("Team identifier for team-scoped secrets"),
+    .describe(
+      "Team identifier for team-scoped secrets. Required only when scope='team'. Example: 'acme-platform'.",
+    ),
   orgId: z
     .string()
     .optional()
-    .describe("Org identifier for org-scoped secrets"),
+    .describe(
+      "Organization identifier for org-scoped secrets. Required only when scope='org'. Example: 'acme-corp'.",
+    ),
   scope: z
     .enum(["global", "project", "team", "org"])
     .optional()
-    .describe("Scope: global, project, team, or org"),
+    .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("Project root path for project-scoped secrets"),
+    .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 for superposition collapse (e.g., dev, staging, prod)"),
+    .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.",
+    ),
 } as const;

src/mcp/tools/agent.ts

@@ -6,10 +6,22 @@ import { text, enforceToolPolicy } from "./_shared.js";
 export function registerAgentTools(server: McpServer): void {
   server.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 — 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: z.string().describe("Memory key"),
-      value: z.string().describe("Value to store"),
+      key: z
+        .string()
+        .describe(
+          "Memory key (free-form string). Convention: lowercase dotted namespaces, e.g. 'project.lastDeploy'.",
+        ),
+      value: z
+        .string()
+        .describe(
+          "Plain-string value to store. JSON-stringify structured data on the caller side if needed.",
+        ),
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("agent_remember");
@@ -22,9 +34,18 @@ export function registerAgentTools(server: McpServer): void {
 
   server.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: z.string().optional().describe("Memory key to recall (omit to list all)"),
+      key: z
+        .string()
+        .optional()
+        .describe(
+          "Memory key to read. Omit to list every stored key (without values).",
+        ),
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("agent_recall");
@@ -46,9 +67,13 @@ export function registerAgentTools(server: McpServer): void {
 
   server.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: z.string().describe("Memory key to forget"),
+      key: z.string().describe("Memory key to delete."),
     },
     async (params) => {
       const toolBlock = enforceToolPolicy("agent_forget");