From 47b55970d6e905f4cda792c68f58b818a63fb319 Mon Sep 17 00:00:00 2001
From: I4cDeath <publiclasstewart@gmail.com>
Date: Tue, 24 Mar 2026 18:56:50 +0800
Subject: [PATCH 1/6] docs(web): expand /docs with full CLI and MCP reference

Add a complete CLI command/options reference with practical examples and include one-sentence prompt examples for every MCP tool to make the docs directly usable in agent workflows.

Made-with: Cursor
---
 web/app/docs/page.tsx | 506 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 506 insertions(+)

diff --git a/web/app/docs/page.tsx b/web/app/docs/page.tsx
index d3fbfe6..88a9b42 100644
--- a/web/app/docs/page.tsx
+++ b/web/app/docs/page.tsx
@@ -18,6 +18,435 @@ const installCmds = [
   { pm: "bun", cmd: "bun add -g @i4ctime/q-ring" },
 ];
 
+const cliReference = [
+  {
+    command: "set <key> [value]",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--team <id>",
+      "--org <id>",
+      "--project-path <path>",
+      "-e, --env <env>",
+      "--ttl <seconds>",
+      "--expires <iso>",
+      "--description <desc>",
+      "--tags <tags>",
+      "--rotation-format <format>",
+      "--rotation-prefix <prefix>",
+      "--requires-approval",
+      "--jit-provider <provider>",
+    ],
+    examples: [
+      'qring set OPENAI_API_KEY "sk-..." --project --env dev --tags ai,backend',
+      "qring set DB_PASSWORD --ttl 3600 --rotation-format password --requires-approval",
+    ],
+  },
+  {
+    command: "get <key>",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--team <id>",
+      "--org <id>",
+      "--project-path <path>",
+      "-e, --env <env>",
+    ],
+    examples: ['qring get OPENAI_API_KEY --project --env prod'],
+  },
+  {
+    command: "delete <key> (alias: rm)",
+    options: ["-g, --global", "-p, --project", "--project-path <path>"],
+    examples: ["qring delete LEGACY_TOKEN --project"],
+  },
+  {
+    command: "list (alias: ls)",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--team <id>",
+      "--org <id>",
+      "--project-path <path>",
+      "--show-decay",
+      "-t, --tag <tag>",
+      "--expired",
+      "--stale",
+      "-f, --filter <pattern>",
+    ],
+    examples: ['qring list --project --tag payments --filter "STRIPE_*" --show-decay'],
+  },
+  {
+    command: "inspect <key>",
+    options: ["-g, --global", "-p, --project", "--project-path <path>"],
+    examples: ["qring inspect OPENAI_API_KEY --project"],
+  },
+  {
+    command: "export",
+    options: [
+      "-f, --format <format>",
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+      "-e, --env <env>",
+      "-k, --keys <keys>",
+      "-t, --tags <tags>",
+    ],
+    examples: ['qring export --format env --project --env prod --keys OPENAI_API_KEY,STRIPE_KEY'],
+  },
+  {
+    command: "import <file>",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+      "-e, --env <env>",
+      "--skip-existing",
+      "--dry-run",
+    ],
+    examples: ["qring import .env --project --skip-existing"],
+  },
+  {
+    command: "check",
+    options: ["--project-path <path>"],
+    examples: ["qring check --project-path ."],
+  },
+  {
+    command: "validate [key]",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+      "--provider <name>",
+      "--all",
+      "--manifest",
+      "--list-providers",
+    ],
+    examples: [
+      "qring validate OPENAI_API_KEY --project",
+      "qring validate --all --manifest --project",
+    ],
+  },
+  {
+    command: "exec <command...>",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+      "-e, --env <env>",
+      "-k, --keys <keys>",
+      "-t, --tags <tags>",
+      "--profile <name>",
+    ],
+    examples: ['qring exec --project --profile restricted --keys OPENAI_API_KEY -- node "scripts/smoke.js"'],
+  },
+  {
+    command: "scan [dir]",
+    options: ["--fix", "-g, --global", "-p, --project", "--project-path <path>"],
+    examples: ["qring scan src --fix --project"],
+  },
+  {
+    command: "lint <files...>",
+    options: ["--fix", "-g, --global", "-p, --project", "--project-path <path>"],
+    examples: ["qring lint src/config.ts src/client.ts --fix --project"],
+  },
+  {
+    command: "context (alias: describe)",
+    options: ["-g, --global", "-p, --project", "--project-path <path>", "--json"],
+    examples: ["qring context --project --json"],
+  },
+  {
+    command: "remember <key> <value>",
+    options: [],
+    examples: ['qring remember deployment_note "rotate Stripe key after release"'],
+  },
+  {
+    command: "recall [key]",
+    options: [],
+    examples: ["qring recall deployment_note", "qring recall"],
+  },
+  {
+    command: "forget <key>",
+    options: ["--all"],
+    examples: ["qring forget deployment_note"],
+  },
+  {
+    command: "approve <key>",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+      "--for <seconds>",
+      "--reason <text>",
+      "--revoke",
+      "--list",
+    ],
+    examples: ['qring approve OPENAI_API_KEY --project --for 1800 --reason "temporary agent read"'],
+  },
+  {
+    command: "approvals",
+    options: [],
+    examples: ["qring approvals"],
+  },
+  {
+    command: "hook:install",
+    options: ["--project-path <path>"],
+    examples: ["qring hook:install --project-path ."],
+  },
+  {
+    command: "hook:uninstall",
+    options: ["--project-path <path>"],
+    examples: ["qring hook:uninstall --project-path ."],
+  },
+  {
+    command: "hook:run",
+    options: [],
+    examples: ["qring hook:run"],
+  },
+  {
+    command: "wizard <name>",
+    options: [
+      "--keys <keys>",
+      "--provider <provider>",
+      "--tags <tags>",
+      "--hook-exec <cmd>",
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+    ],
+    examples: ['qring wizard stripe --keys STRIPE_KEY,STRIPE_WEBHOOK_SECRET --provider stripe --tags payments,prod'],
+  },
+  {
+    command: "analyze",
+    options: ["-g, --global", "-p, --project", "--project-path <path>"],
+    examples: ["qring analyze --project"],
+  },
+  {
+    command: "env",
+    options: ["--project-path <path>"],
+    examples: ["qring env --project-path ."],
+  },
+  {
+    command: "generate (alias: gen)",
+    options: [
+      "-f, --format <format>",
+      "-l, --length <n>",
+      "--prefix <prefix>",
+      "-s, --save <key>",
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+    ],
+    examples: ["qring generate --format api-key --prefix sk- --save OPENAI_API_KEY --project"],
+  },
+  {
+    command: "entangle <sourceKey> <targetKey>",
+    options: ["-g, --global", "--source-project <path>", "--target-project <path>"],
+    examples: ["qring entangle API_KEY API_KEY_BACKUP --source-project . --target-project ../worker"],
+  },
+  {
+    command: "disentangle <sourceKey> <targetKey>",
+    options: ["-g, --global", "--source-project <path>", "--target-project <path>"],
+    examples: ["qring disentangle API_KEY API_KEY_BACKUP --source-project . --target-project ../worker"],
+  },
+  {
+    command: "tunnel create <value>",
+    options: ["--ttl <seconds>", "--max-reads <n>"],
+    examples: ['qring tunnel create "temp-token" --ttl 300 --max-reads 1'],
+  },
+  {
+    command: "tunnel read <id>",
+    options: [],
+    examples: ["qring tunnel read tu_abc123"],
+  },
+  {
+    command: "tunnel destroy <id>",
+    options: [],
+    examples: ["qring tunnel destroy tu_abc123"],
+  },
+  {
+    command: "tunnel list (alias: tunnel ls)",
+    options: [],
+    examples: ["qring tunnel list"],
+  },
+  {
+    command: "teleport pack",
+    options: [
+      "-k, --keys <keys>",
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+    ],
+    examples: ['qring teleport pack --project --keys OPENAI_API_KEY,STRIPE_KEY > bundle.qring'],
+  },
+  {
+    command: "teleport unpack [bundle]",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+      "--dry-run",
+    ],
+    examples: ["qring teleport unpack \"$(cat bundle.qring)\" --project --dry-run"],
+  },
+  {
+    command: "audit",
+    options: ["-k, --key <key>", "-a, --action <action>", "-n, --limit <n>", "--anomalies"],
+    examples: ["qring audit --key OPENAI_API_KEY --action read --limit 50"],
+  },
+  {
+    command: "audit:verify",
+    options: [],
+    examples: ["qring audit:verify"],
+  },
+  {
+    command: "audit:export",
+    options: ["--since <date>", "--until <date>", "--format <fmt>", "-o, --output <file>"],
+    examples: ["qring audit:export --since 2026-03-01 --format json -o audit.json"],
+  },
+  {
+    command: "health",
+    options: ["-g, --global", "-p, --project", "--project-path <path>"],
+    examples: ["qring health --project"],
+  },
+  {
+    command: "hook add",
+    options: [
+      "--key <key>",
+      "--key-pattern <pattern>",
+      "--tag <tag>",
+      "--scope <scope>",
+      "--action <actions>",
+      "--exec <command>",
+      "--url <url>",
+      "--signal-target <target>",
+      "--signal-name <signal>",
+      "--description <desc>",
+    ],
+    examples: [
+      'qring hook add --key DB_PASSWORD --action write,rotate --exec "pnpm restart:api"',
+      "qring hook add --tag payments --url https://hooks.example.com/qring --action rotate",
+    ],
+  },
+  {
+    command: "hook list (alias: hook ls)",
+    options: [],
+    examples: ["qring hook list"],
+  },
+  {
+    command: "hook remove <id> (alias: hook rm)",
+    options: [],
+    examples: ["qring hook remove hk_abc123"],
+  },
+  {
+    command: "hook enable <id>",
+    options: [],
+    examples: ["qring hook enable hk_abc123"],
+  },
+  {
+    command: "hook disable <id>",
+    options: [],
+    examples: ["qring hook disable hk_abc123"],
+  },
+  {
+    command: "hook test <id>",
+    options: [],
+    examples: ["qring hook test hk_abc123"],
+  },
+  {
+    command: "env:generate",
+    options: ["--project-path <path>", "-o, --output <file>", "-e, --env <env>"],
+    examples: ["qring env:generate --project-path . --env prod -o .env"],
+  },
+  {
+    command: "status",
+    options: ["--port <port>", "--no-open"],
+    examples: ["qring status --port 9876 --no-open"],
+  },
+  {
+    command: "agent",
+    options: [
+      "-i, --interval <seconds>",
+      "--auto-rotate",
+      "-v, --verbose",
+      "--project-path <paths>",
+      "--once",
+    ],
+    examples: ["qring agent --once --auto-rotate --project-path .,../worker"],
+  },
+  {
+    command: "rotate <key>",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+      "--provider <name>",
+    ],
+    examples: ["qring rotate OPENAI_API_KEY --project --provider openai"],
+  },
+  {
+    command: "ci:validate",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+      "--json",
+    ],
+    examples: ["qring ci:validate --project --json"],
+  },
+  {
+    command: "policy",
+    options: ["--json"],
+    examples: ["qring policy --json"],
+  },
+] as const;
+
+const mcpToolPrompts = [
+  ["get_secret", "Retrieve `OPENAI_API_KEY` from project scope for `prod` and return just the raw value."],
+  ["list_secrets", "List project secrets tagged `payments` and show only stale entries matching `STRIPE_*`."],
+  ["set_secret", "Set `STRIPE_SECRET_KEY` in project scope with tags `payments,prod` and a TTL of 86400 seconds."],
+  ["delete_secret", "Delete `LEGACY_TOKEN` from global scope and confirm whether it existed."],
+  ["has_secret", "Check whether `GITHUB_TOKEN` exists in project scope and return true/false."],
+  ["export_secrets", "Export only `OPENAI_API_KEY` and `STRIPE_KEY` as `.env` for `prod`."],
+  ["import_dotenv", "Import this `.env` content into project scope in dry-run mode and report what would change."],
+  ["check_project", "Validate `.q-ring.json` at this path and show missing, stale, and expired required keys."],
+  ["env_generate", "Generate `.env` content from the project manifest for `staging` without writing files."],
+  ["inspect_secret", "Inspect `DB_PASSWORD` and summarize scope, decay state, tags, and entanglement metadata."],
+  ["detect_environment", "Detect current environment for this project path and include the detection source."],
+  ["generate_secret", "Generate an `api-key` with prefix `sk-` and save it as `OPENAI_API_KEY` in project scope."],
+  ["entangle_secrets", "Entangle `API_KEY` in this project with `API_KEY_BACKUP` in another project path."],
+  ["disentangle_secrets", "Remove entanglement between `API_KEY` and `API_KEY_BACKUP` and confirm success."],
+  ["tunnel_create", "Create an ephemeral tunnel value with TTL 300 and maxReads 1, then return the tunnel ID."],
+  ["tunnel_read", "Read tunnel `tu_abc123` once and return value or not-found/expired status."],
+  ["tunnel_list", "List all active tunnels with read counts and time remaining."],
+  ["tunnel_destroy", "Destroy tunnel `tu_abc123` immediately and confirm whether it existed."],
+  ["teleport_pack", "Pack keys `OPENAI_API_KEY` and `STRIPE_KEY` into an encrypted bundle using this passphrase."],
+  ["teleport_unpack", "Unpack this teleport bundle in dry-run mode and list keys and scopes that would be imported."],
+  ["audit_log", "Return last 100 `read` audit events for `OPENAI_API_KEY` in reverse chronological order."],
+  ["detect_anomalies", "Detect anomalies for `OPENAI_API_KEY` and include recommendations."],
+  ["health_check", "Run a project-scope health check and summarize healthy/stale/expired plus anomaly count."],
+  ["validate_secret", "Validate `OPENAI_API_KEY` with provider auto-detection and return provider + latency."],
+  ["list_providers", "List available validation providers with descriptions and known key prefixes."],
+  ["register_hook", "Register an HTTP hook for `DB_PASSWORD` rotate events to this URL with a clear description."],
+  ["list_hooks", "List all registered hooks and include type, match criteria, and enabled status."],
+  ["remove_hook", "Remove hook `hk_abc123` and return a not-found error if it does not exist."],
+  ["exec_with_secrets", "Run `node scripts/smoke.js` with only `OPENAI_API_KEY` injected using restricted profile."],
+  ["scan_codebase_for_secrets", "Scan `./src` for hardcoded secrets and return file, line, key name, and entropy."],
+  ["get_project_context", "Return redacted project context for this path including manifest and recent actions."],
+  ["agent_remember", "Remember the note `rotated Stripe keys after release` under key `release_notes`."],
+  ["agent_recall", "Recall key `release_notes`; if omitted, list all memory keys and update times."],
+  ["agent_forget", "Forget memory key `release_notes` and report whether it was present."],
+  ["lint_files", "Lint these files for hardcoded secrets in fix mode and return structured fix results."],
+  ["analyze_secrets", "Analyze project secrets for unused keys, stale entries, and top read frequency."],
+  ["status_dashboard", "Start dashboard on port 9876 and return the local URL to open in a browser."],
+  ["agent_scan", "Run one agent scan with auto-rotate enabled across these project paths and return report JSON."],
+  ["verify_audit_chain", "Verify audit hash-chain integrity and show first break location if tampering is detected."],
+  ["export_audit", "Export audit events as JSON from 2026-03-01 until now."],
+  ["rotate_secret", "Attempt provider-native rotation for `OPENAI_API_KEY` and store the new value if rotated."],
+  ["ci_validate_secrets", "Run CI batch validation for project scope and return pass/fail summary JSON."],
+  ["check_policy", "Check whether command `npm publish` is allowed by exec policy for this project path."],
+  ["get_policy_summary", "Return governance policy summary for this project, including tool and secret lifecycle rules."],
+] as const;
+
 export default function DocsPage() {
   return (
     <>
@@ -162,7 +591,84 @@ export default function DocsPage() {
             </section>
           </FadeIn>
 
+          <FadeIn delay={0.35}>
+            <section className="mb-16 border-t border-border pt-10">
+              <h2 className="text-3xl font-bold mb-4 text-text-primary">
+                CLI Complete Reference
+              </h2>
+              <p className="text-text-secondary mb-6">
+                Every CLI command and option is listed below with at least one real invocation example.
+              </p>
+              <div className="space-y-5">
+                {cliReference.map((item) => (
+                  <div
+                    key={item.command}
+                    className="rounded-md border border-border bg-bg-card p-5"
+                  >
+                    <h3 className="text-lg font-semibold text-text-primary mb-3 font-[family-name:var(--font-mono)]">
+                      qring {item.command}
+                    </h3>
+                    <div className="mb-3">
+                      <p className="text-sm text-text-dim mb-2">Options</p>
+                      {item.options.length === 0 ? (
+                        <p className="text-sm text-text-secondary">No command-specific options.</p>
+                      ) : (
+                        <div className="flex flex-wrap gap-2">
+                          {item.options.map((opt) => (
+                            <span
+                              key={opt}
+                              className="rounded border border-border px-2 py-1 text-xs font-[family-name:var(--font-mono)] text-accent-bright bg-accent-dim"
+                            >
+                              {opt}
+                            </span>
+                          ))}
+                        </div>
+                      )}
+                    </div>
+                    <CopyableTerminal title={`qring ${item.command}`} maxWidth="100%">
+                      <pre>
+                        {item.examples.map((ex, idx) => (
+                          <span key={ex}>
+                            <span className="text-green font-bold">$</span>{" "}
+                            <span className="text-accent-bright font-medium">{ex}</span>
+                            {idx < item.examples.length - 1 ? "\n" : ""}
+                          </span>
+                        ))}
+                      </pre>
+                    </CopyableTerminal>
+                  </div>
+                ))}
+              </div>
+            </section>
+          </FadeIn>
+
           <FadeIn delay={0.4}>
+            <section className="mb-16 border-t border-border pt-10">
+              <h2 className="text-3xl font-bold mb-4 text-text-primary">
+                MCP Prompt Cookbook
+              </h2>
+              <p className="text-text-secondary mb-6">
+                Every MCP tool in q-ring with a one-sentence prompt example you can paste into an agent chat.
+              </p>
+              <div className="space-y-3">
+                {mcpToolPrompts.map(([tool, prompt]) => (
+                  <div
+                    key={tool}
+                    className="rounded-md border border-border bg-bg-card p-4"
+                  >
+                    <p className="text-sm mb-2">
+                      <span className="font-[family-name:var(--font-mono)] text-accent-bright">
+                        {tool}
+                      </span>
+                    </p>
+                    <p className="text-sm text-text-secondary">{prompt}</p>
+                  </div>
+                ))}
+              </div>
+            </section>
+          </FadeIn>
+
+          <FadeIn delay={0.45}>
             <div className="border-t border-border pt-8 text-center">
               <p className="text-text-secondary mb-4">
                 Ready to explore more features?

From 82123c2fb86d9b73ec06ab813556217e32aaafdf Mon Sep 17 00:00:00 2001
From: I4cDeath <publiclasstewart@gmail.com>
Date: Tue, 24 Mar 2026 19:01:09 +0800
Subject: [PATCH 2/6] fix(web): ensure docs content is visible on first render

Made-with: Cursor
---
 web/app/docs/page.tsx            | 8 ++------
 web/components/motion/FadeIn.tsx | 2 +-
 2 files changed, 3 insertions(+), 7 deletions(-)

diff --git a/web/app/docs/page.tsx b/web/app/docs/page.tsx
index 88a9b42..ea02333 100644
--- a/web/app/docs/page.tsx
+++ b/web/app/docs/page.tsx
@@ -591,8 +591,7 @@ export default function DocsPage() {
             </section>
           </FadeIn>
 
-          <FadeIn delay={0.35}>
-            <section className="mb-16 border-t border-border pt-10">
+          <section className="mb-16 border-t border-border pt-10">
               <h2 className="text-3xl font-bold mb-4 text-text-primary">
                 CLI Complete Reference
               </h2>
@@ -640,10 +639,8 @@ export default function DocsPage() {
                 ))}
               </div>
             </section>
-          </FadeIn>
 
-          <FadeIn delay={0.4}>
-            <section className="mb-16 border-t border-border pt-10">
+          <section className="mb-16 border-t border-border pt-10">
               <h2 className="text-3xl font-bold mb-4 text-text-primary">
                 MCP Prompt Cookbook
               </h2>
@@ -666,7 +663,6 @@ export default function DocsPage() {
                 ))}
               </div>
             </section>
-          </FadeIn>
 
           <FadeIn delay={0.45}>
             <div className="border-t border-border pt-8 text-center">
diff --git a/web/components/motion/FadeIn.tsx b/web/components/motion/FadeIn.tsx
index 7430f5c..4cef0d4 100644
--- a/web/components/motion/FadeIn.tsx
+++ b/web/components/motion/FadeIn.tsx
@@ -51,7 +51,7 @@ export default function FadeIn({
     <motion.div
       className={className}
       variants={variants}
-      initial="hidden"
+      initial={false}
       whileInView="visible"
       viewport={{ once, amount }}
     >

From 0439a237e1656ff54dffa587aa63b38d39cc585e Mon Sep 17 00:00:00 2001
From: I4cDeath <publiclasstewart@gmail.com>
Date: Tue, 24 Mar 2026 19:04:59 +0800
Subject: [PATCH 3/6] docs: improve README intro and add link to new
 documentation site

Made-with: Cursor
---
 README.md | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index ee78214..57a0f11 100644
--- a/README.md
+++ b/README.md
@@ -6,13 +6,20 @@
 
 **The first quantum-inspired keyring built specifically for AI coding agents.**
 
-Stop pasting API keys into plain-text `.env` files or struggling with clunky secret managers. **q-ring** securely anchors your credentials to your OS's native vault (macOS Keychain, GNOME Keyring, Windows Credential Manager), then supercharges them with mechanics from quantum physics. 
+[![NPM Version](https://img.shields.io/npm/v/@i4ctime/q-ring?style=flat-square&color=0ea5e9)](https://www.npmjs.com/package/@i4ctime/q-ring)
+[![Docs](https://img.shields.io/badge/docs-website-0ea5e9?style=flat-square)](https://i4ctime.github.io/quantum_ring/docs)
+[![qring-mcp MCP server](https://glama.ai/mcp/servers/I4cTime/quantum_ring/badges/badge.svg)](https://glama.ai/mcp/servers/I4cTime/quantum_ring)
 
-Experience **superposition** (multi-environment keys), **entanglement** (linked rotations), **tunneling** (in-memory ephemerality), and **teleportation** (encrypted sharing). 
+Stop pasting API keys into plain-text `.env` files or wrestling with clunky secret managers. **q-ring** securely anchors your credentials to your OS's native vault (macOS Keychain, Linux Secret Service, Windows Credential Vault) and supercharges them with mechanics from quantum physics.
 
-Seamlessly integrated with **Cursor**, **Kiro**, **Claude Code**, and the entire **MCP** ecosystem.
+> 📖 **[View the Official Documentation](https://i4ctime.github.io/quantum_ring/docs)** for a complete CLI reference, MCP prompt cookbooks, and architecture details.
 
-[![qring-mcp MCP server](https://glama.ai/mcp/servers/I4cTime/quantum_ring/badges/card.svg)](https://glama.ai/mcp/servers/I4cTime/quantum_ring)
+### Why q-ring?
+- **Superposition:** Store one key with multiple states (dev/staging/prod) that collapse based on context.
+- **Entanglement:** Link keys across projects so rotating one automatically updates them all.
+- **Tunneling:** Create ephemeral, in-memory secrets that self-destruct after a set time or read count.
+- **Teleportation:** Securely pack and share AES-256-GCM encrypted secret bundles.
+- **Seamless AI Integration:** 31 built-in MCP tools for native use in **Cursor**, **Kiro**, and **Claude Code**.
 
 ## 🚀 Installation
 

From ad9c4bcc6765f6dab0066fdb30197be5c3325f69 Mon Sep 17 00:00:00 2001
From: I4cDeath <publiclasstewart@gmail.com>
Date: Tue, 24 Mar 2026 19:06:23 +0800
Subject: [PATCH 4/6] chore: update funding configuration to include GitHub
 Sponsors username

Added 'i4cdeath' to the GitHub Sponsors section in the funding configuration file.
---
 .github/FUNDING.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
index 409bec4..bfce9d0 100644
--- a/.github/FUNDING.yml
+++ b/.github/FUNDING.yml
@@ -1,6 +1,6 @@
 # These are supported funding model platforms
 
-github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+github: [i4cdeath] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
 patreon: # Replace with a single Patreon username
 open_collective: # Replace with a single Open Collective username
 ko_fi: "i4cdeath"

From e94644796775b0cb4c2d41a5b4325bdcadbf725a Mon Sep 17 00:00:00 2001
From: I4cDeath <publiclasstewart@gmail.com>
Date: Tue, 24 Mar 2026 19:08:57 +0800
Subject: [PATCH 5/6] docs(web): expand docs with complete CLI and MCP examples
 (#11)

* docs(web): expand /docs with full CLI and MCP reference

Add a complete CLI command/options reference with practical examples and include one-sentence prompt examples for every MCP tool to make the docs directly usable in agent workflows.

Made-with: Cursor

* fix(web): ensure docs content is visible on first render

Made-with: Cursor

* docs: improve README intro and add link to new documentation site

Made-with: Cursor

* chore: update funding configuration to include GitHub Sponsors username

Added 'i4cdeath' to the GitHub Sponsors section in the funding configuration file.
---
 .github/FUNDING.yml              |   2 +-
 README.md                        |  15 +-
 web/app/docs/page.tsx            | 504 ++++++++++++++++++++++++++++++-
 web/components/motion/FadeIn.tsx |   2 +-
 4 files changed, 516 insertions(+), 7 deletions(-)

diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
index 409bec4..bfce9d0 100644
--- a/.github/FUNDING.yml
+++ b/.github/FUNDING.yml
@@ -1,6 +1,6 @@
 # These are supported funding model platforms
 
-github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+github: [i4cdeath] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
 patreon: # Replace with a single Patreon username
 open_collective: # Replace with a single Open Collective username
 ko_fi: "i4cdeath"
diff --git a/README.md b/README.md
index ee78214..57a0f11 100644
--- a/README.md
+++ b/README.md
@@ -6,13 +6,20 @@
 
 **The first quantum-inspired keyring built specifically for AI coding agents.**
 
-Stop pasting API keys into plain-text `.env` files or struggling with clunky secret managers. **q-ring** securely anchors your credentials to your OS's native vault (macOS Keychain, GNOME Keyring, Windows Credential Manager), then supercharges them with mechanics from quantum physics. 
+[![NPM Version](https://img.shields.io/npm/v/@i4ctime/q-ring?style=flat-square&color=0ea5e9)](https://www.npmjs.com/package/@i4ctime/q-ring)
+[![Docs](https://img.shields.io/badge/docs-website-0ea5e9?style=flat-square)](https://i4ctime.github.io/quantum_ring/docs)
+[![qring-mcp MCP server](https://glama.ai/mcp/servers/I4cTime/quantum_ring/badges/badge.svg)](https://glama.ai/mcp/servers/I4cTime/quantum_ring)
 
-Experience **superposition** (multi-environment keys), **entanglement** (linked rotations), **tunneling** (in-memory ephemerality), and **teleportation** (encrypted sharing). 
+Stop pasting API keys into plain-text `.env` files or wrestling with clunky secret managers. **q-ring** securely anchors your credentials to your OS's native vault (macOS Keychain, Linux Secret Service, Windows Credential Vault) and supercharges them with mechanics from quantum physics.
 
-Seamlessly integrated with **Cursor**, **Kiro**, **Claude Code**, and the entire **MCP** ecosystem.
+> 📖 **[View the Official Documentation](https://i4ctime.github.io/quantum_ring/docs)** for a complete CLI reference, MCP prompt cookbooks, and architecture details.
 
-[![qring-mcp MCP server](https://glama.ai/mcp/servers/I4cTime/quantum_ring/badges/card.svg)](https://glama.ai/mcp/servers/I4cTime/quantum_ring)
+### Why q-ring?
+- **Superposition:** Store one key with multiple states (dev/staging/prod) that collapse based on context.
+- **Entanglement:** Link keys across projects so rotating one automatically updates them all.
+- **Tunneling:** Create ephemeral, in-memory secrets that self-destruct after a set time or read count.
+- **Teleportation:** Securely pack and share AES-256-GCM encrypted secret bundles.
+- **Seamless AI Integration:** 31 built-in MCP tools for native use in **Cursor**, **Kiro**, and **Claude Code**.
 
 ## 🚀 Installation
 
diff --git a/web/app/docs/page.tsx b/web/app/docs/page.tsx
index d3fbfe6..ea02333 100644
--- a/web/app/docs/page.tsx
+++ b/web/app/docs/page.tsx
@@ -18,6 +18,435 @@ const installCmds = [
   { pm: "bun", cmd: "bun add -g @i4ctime/q-ring" },
 ];
 
+const cliReference = [
+  {
+    command: "set <key> [value]",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--team <id>",
+      "--org <id>",
+      "--project-path <path>",
+      "-e, --env <env>",
+      "--ttl <seconds>",
+      "--expires <iso>",
+      "--description <desc>",
+      "--tags <tags>",
+      "--rotation-format <format>",
+      "--rotation-prefix <prefix>",
+      "--requires-approval",
+      "--jit-provider <provider>",
+    ],
+    examples: [
+      'qring set OPENAI_API_KEY "sk-..." --project --env dev --tags ai,backend',
+      "qring set DB_PASSWORD --ttl 3600 --rotation-format password --requires-approval",
+    ],
+  },
+  {
+    command: "get <key>",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--team <id>",
+      "--org <id>",
+      "--project-path <path>",
+      "-e, --env <env>",
+    ],
+    examples: ['qring get OPENAI_API_KEY --project --env prod'],
+  },
+  {
+    command: "delete <key> (alias: rm)",
+    options: ["-g, --global", "-p, --project", "--project-path <path>"],
+    examples: ["qring delete LEGACY_TOKEN --project"],
+  },
+  {
+    command: "list (alias: ls)",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--team <id>",
+      "--org <id>",
+      "--project-path <path>",
+      "--show-decay",
+      "-t, --tag <tag>",
+      "--expired",
+      "--stale",
+      "-f, --filter <pattern>",
+    ],
+    examples: ['qring list --project --tag payments --filter "STRIPE_*" --show-decay'],
+  },
+  {
+    command: "inspect <key>",
+    options: ["-g, --global", "-p, --project", "--project-path <path>"],
+    examples: ["qring inspect OPENAI_API_KEY --project"],
+  },
+  {
+    command: "export",
+    options: [
+      "-f, --format <format>",
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+      "-e, --env <env>",
+      "-k, --keys <keys>",
+      "-t, --tags <tags>",
+    ],
+    examples: ['qring export --format env --project --env prod --keys OPENAI_API_KEY,STRIPE_KEY'],
+  },
+  {
+    command: "import <file>",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+      "-e, --env <env>",
+      "--skip-existing",
+      "--dry-run",
+    ],
+    examples: ["qring import .env --project --skip-existing"],
+  },
+  {
+    command: "check",
+    options: ["--project-path <path>"],
+    examples: ["qring check --project-path ."],
+  },
+  {
+    command: "validate [key]",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+      "--provider <name>",
+      "--all",
+      "--manifest",
+      "--list-providers",
+    ],
+    examples: [
+      "qring validate OPENAI_API_KEY --project",
+      "qring validate --all --manifest --project",
+    ],
+  },
+  {
+    command: "exec <command...>",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+      "-e, --env <env>",
+      "-k, --keys <keys>",
+      "-t, --tags <tags>",
+      "--profile <name>",
+    ],
+    examples: ['qring exec --project --profile restricted --keys OPENAI_API_KEY -- node "scripts/smoke.js"'],
+  },
+  {
+    command: "scan [dir]",
+    options: ["--fix", "-g, --global", "-p, --project", "--project-path <path>"],
+    examples: ["qring scan src --fix --project"],
+  },
+  {
+    command: "lint <files...>",
+    options: ["--fix", "-g, --global", "-p, --project", "--project-path <path>"],
+    examples: ["qring lint src/config.ts src/client.ts --fix --project"],
+  },
+  {
+    command: "context (alias: describe)",
+    options: ["-g, --global", "-p, --project", "--project-path <path>", "--json"],
+    examples: ["qring context --project --json"],
+  },
+  {
+    command: "remember <key> <value>",
+    options: [],
+    examples: ['qring remember deployment_note "rotate Stripe key after release"'],
+  },
+  {
+    command: "recall [key]",
+    options: [],
+    examples: ["qring recall deployment_note", "qring recall"],
+  },
+  {
+    command: "forget <key>",
+    options: ["--all"],
+    examples: ["qring forget deployment_note"],
+  },
+  {
+    command: "approve <key>",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+      "--for <seconds>",
+      "--reason <text>",
+      "--revoke",
+      "--list",
+    ],
+    examples: ['qring approve OPENAI_API_KEY --project --for 1800 --reason "temporary agent read"'],
+  },
+  {
+    command: "approvals",
+    options: [],
+    examples: ["qring approvals"],
+  },
+  {
+    command: "hook:install",
+    options: ["--project-path <path>"],
+    examples: ["qring hook:install --project-path ."],
+  },
+  {
+    command: "hook:uninstall",
+    options: ["--project-path <path>"],
+    examples: ["qring hook:uninstall --project-path ."],
+  },
+  {
+    command: "hook:run",
+    options: [],
+    examples: ["qring hook:run"],
+  },
+  {
+    command: "wizard <name>",
+    options: [
+      "--keys <keys>",
+      "--provider <provider>",
+      "--tags <tags>",
+      "--hook-exec <cmd>",
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+    ],
+    examples: ['qring wizard stripe --keys STRIPE_KEY,STRIPE_WEBHOOK_SECRET --provider stripe --tags payments,prod'],
+  },
+  {
+    command: "analyze",
+    options: ["-g, --global", "-p, --project", "--project-path <path>"],
+    examples: ["qring analyze --project"],
+  },
+  {
+    command: "env",
+    options: ["--project-path <path>"],
+    examples: ["qring env --project-path ."],
+  },
+  {
+    command: "generate (alias: gen)",
+    options: [
+      "-f, --format <format>",
+      "-l, --length <n>",
+      "--prefix <prefix>",
+      "-s, --save <key>",
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+    ],
+    examples: ["qring generate --format api-key --prefix sk- --save OPENAI_API_KEY --project"],
+  },
+  {
+    command: "entangle <sourceKey> <targetKey>",
+    options: ["-g, --global", "--source-project <path>", "--target-project <path>"],
+    examples: ["qring entangle API_KEY API_KEY_BACKUP --source-project . --target-project ../worker"],
+  },
+  {
+    command: "disentangle <sourceKey> <targetKey>",
+    options: ["-g, --global", "--source-project <path>", "--target-project <path>"],
+    examples: ["qring disentangle API_KEY API_KEY_BACKUP --source-project . --target-project ../worker"],
+  },
+  {
+    command: "tunnel create <value>",
+    options: ["--ttl <seconds>", "--max-reads <n>"],
+    examples: ['qring tunnel create "temp-token" --ttl 300 --max-reads 1'],
+  },
+  {
+    command: "tunnel read <id>",
+    options: [],
+    examples: ["qring tunnel read tu_abc123"],
+  },
+  {
+    command: "tunnel destroy <id>",
+    options: [],
+    examples: ["qring tunnel destroy tu_abc123"],
+  },
+  {
+    command: "tunnel list (alias: tunnel ls)",
+    options: [],
+    examples: ["qring tunnel list"],
+  },
+  {
+    command: "teleport pack",
+    options: [
+      "-k, --keys <keys>",
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+    ],
+    examples: ['qring teleport pack --project --keys OPENAI_API_KEY,STRIPE_KEY > bundle.qring'],
+  },
+  {
+    command: "teleport unpack [bundle]",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+      "--dry-run",
+    ],
+    examples: ["qring teleport unpack \"$(cat bundle.qring)\" --project --dry-run"],
+  },
+  {
+    command: "audit",
+    options: ["-k, --key <key>", "-a, --action <action>", "-n, --limit <n>", "--anomalies"],
+    examples: ["qring audit --key OPENAI_API_KEY --action read --limit 50"],
+  },
+  {
+    command: "audit:verify",
+    options: [],
+    examples: ["qring audit:verify"],
+  },
+  {
+    command: "audit:export",
+    options: ["--since <date>", "--until <date>", "--format <fmt>", "-o, --output <file>"],
+    examples: ["qring audit:export --since 2026-03-01 --format json -o audit.json"],
+  },
+  {
+    command: "health",
+    options: ["-g, --global", "-p, --project", "--project-path <path>"],
+    examples: ["qring health --project"],
+  },
+  {
+    command: "hook add",
+    options: [
+      "--key <key>",
+      "--key-pattern <pattern>",
+      "--tag <tag>",
+      "--scope <scope>",
+      "--action <actions>",
+      "--exec <command>",
+      "--url <url>",
+      "--signal-target <target>",
+      "--signal-name <signal>",
+      "--description <desc>",
+    ],
+    examples: [
+      'qring hook add --key DB_PASSWORD --action write,rotate --exec "pnpm restart:api"',
+      "qring hook add --tag payments --url https://hooks.example.com/qring --action rotate",
+    ],
+  },
+  {
+    command: "hook list (alias: hook ls)",
+    options: [],
+    examples: ["qring hook list"],
+  },
+  {
+    command: "hook remove <id> (alias: hook rm)",
+    options: [],
+    examples: ["qring hook remove hk_abc123"],
+  },
+  {
+    command: "hook enable <id>",
+    options: [],
+    examples: ["qring hook enable hk_abc123"],
+  },
+  {
+    command: "hook disable <id>",
+    options: [],
+    examples: ["qring hook disable hk_abc123"],
+  },
+  {
+    command: "hook test <id>",
+    options: [],
+    examples: ["qring hook test hk_abc123"],
+  },
+  {
+    command: "env:generate",
+    options: ["--project-path <path>", "-o, --output <file>", "-e, --env <env>"],
+    examples: ["qring env:generate --project-path . --env prod -o .env"],
+  },
+  {
+    command: "status",
+    options: ["--port <port>", "--no-open"],
+    examples: ["qring status --port 9876 --no-open"],
+  },
+  {
+    command: "agent",
+    options: [
+      "-i, --interval <seconds>",
+      "--auto-rotate",
+      "-v, --verbose",
+      "--project-path <paths>",
+      "--once",
+    ],
+    examples: ["qring agent --once --auto-rotate --project-path .,../worker"],
+  },
+  {
+    command: "rotate <key>",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+      "--provider <name>",
+    ],
+    examples: ["qring rotate OPENAI_API_KEY --project --provider openai"],
+  },
+  {
+    command: "ci:validate",
+    options: [
+      "-g, --global",
+      "-p, --project",
+      "--project-path <path>",
+      "--json",
+    ],
+    examples: ["qring ci:validate --project --json"],
+  },
+  {
+    command: "policy",
+    options: ["--json"],
+    examples: ["qring policy --json"],
+  },
+] as const;
+
+const mcpToolPrompts = [
+  ["get_secret", "Retrieve `OPENAI_API_KEY` from project scope for `prod` and return just the raw value."],
+  ["list_secrets", "List project secrets tagged `payments` and show only stale entries matching `STRIPE_*`."],
+  ["set_secret", "Set `STRIPE_SECRET_KEY` in project scope with tags `payments,prod` and a TTL of 86400 seconds."],
+  ["delete_secret", "Delete `LEGACY_TOKEN` from global scope and confirm whether it existed."],
+  ["has_secret", "Check whether `GITHUB_TOKEN` exists in project scope and return true/false."],
+  ["export_secrets", "Export only `OPENAI_API_KEY` and `STRIPE_KEY` as `.env` for `prod`."],
+  ["import_dotenv", "Import this `.env` content into project scope in dry-run mode and report what would change."],
+  ["check_project", "Validate `.q-ring.json` at this path and show missing, stale, and expired required keys."],
+  ["env_generate", "Generate `.env` content from the project manifest for `staging` without writing files."],
+  ["inspect_secret", "Inspect `DB_PASSWORD` and summarize scope, decay state, tags, and entanglement metadata."],
+  ["detect_environment", "Detect current environment for this project path and include the detection source."],
+  ["generate_secret", "Generate an `api-key` with prefix `sk-` and save it as `OPENAI_API_KEY` in project scope."],
+  ["entangle_secrets", "Entangle `API_KEY` in this project with `API_KEY_BACKUP` in another project path."],
+  ["disentangle_secrets", "Remove entanglement between `API_KEY` and `API_KEY_BACKUP` and confirm success."],
+  ["tunnel_create", "Create an ephemeral tunnel value with TTL 300 and maxReads 1, then return the tunnel ID."],
+  ["tunnel_read", "Read tunnel `tu_abc123` once and return value or not-found/expired status."],
+  ["tunnel_list", "List all active tunnels with read counts and time remaining."],
+  ["tunnel_destroy", "Destroy tunnel `tu_abc123` immediately and confirm whether it existed."],
+  ["teleport_pack", "Pack keys `OPENAI_API_KEY` and `STRIPE_KEY` into an encrypted bundle using this passphrase."],
+  ["teleport_unpack", "Unpack this teleport bundle in dry-run mode and list keys and scopes that would be imported."],
+  ["audit_log", "Return last 100 `read` audit events for `OPENAI_API_KEY` in reverse chronological order."],
+  ["detect_anomalies", "Detect anomalies for `OPENAI_API_KEY` and include recommendations."],
+  ["health_check", "Run a project-scope health check and summarize healthy/stale/expired plus anomaly count."],
+  ["validate_secret", "Validate `OPENAI_API_KEY` with provider auto-detection and return provider + latency."],
+  ["list_providers", "List available validation providers with descriptions and known key prefixes."],
+  ["register_hook", "Register an HTTP hook for `DB_PASSWORD` rotate events to this URL with a clear description."],
+  ["list_hooks", "List all registered hooks and include type, match criteria, and enabled status."],
+  ["remove_hook", "Remove hook `hk_abc123` and return a not-found error if it does not exist."],
+  ["exec_with_secrets", "Run `node scripts/smoke.js` with only `OPENAI_API_KEY` injected using restricted profile."],
+  ["scan_codebase_for_secrets", "Scan `./src` for hardcoded secrets and return file, line, key name, and entropy."],
+  ["get_project_context", "Return redacted project context for this path including manifest and recent actions."],
+  ["agent_remember", "Remember the note `rotated Stripe keys after release` under key `release_notes`."],
+  ["agent_recall", "Recall key `release_notes`; if omitted, list all memory keys and update times."],
+  ["agent_forget", "Forget memory key `release_notes` and report whether it was present."],
+  ["lint_files", "Lint these files for hardcoded secrets in fix mode and return structured fix results."],
+  ["analyze_secrets", "Analyze project secrets for unused keys, stale entries, and top read frequency."],
+  ["status_dashboard", "Start dashboard on port 9876 and return the local URL to open in a browser."],
+  ["agent_scan", "Run one agent scan with auto-rotate enabled across these project paths and return report JSON."],
+  ["verify_audit_chain", "Verify audit hash-chain integrity and show first break location if tampering is detected."],
+  ["export_audit", "Export audit events as JSON from 2026-03-01 until now."],
+  ["rotate_secret", "Attempt provider-native rotation for `OPENAI_API_KEY` and store the new value if rotated."],
+  ["ci_validate_secrets", "Run CI batch validation for project scope and return pass/fail summary JSON."],
+  ["check_policy", "Check whether command `npm publish` is allowed by exec policy for this project path."],
+  ["get_policy_summary", "Return governance policy summary for this project, including tool and secret lifecycle rules."],
+] as const;
+
 export default function DocsPage() {
   return (
     <>
@@ -162,7 +591,80 @@ export default function DocsPage() {
             </section>
           </FadeIn>
 
-          <FadeIn delay={0.4}>
+          <section className="mb-16 border-t border-border pt-10">
+              <h2 className="text-3xl font-bold mb-4 text-text-primary">
+                CLI Complete Reference
+              </h2>
+              <p className="text-text-secondary mb-6">
+                Every CLI command and option is listed below with at least one real invocation example.
+              </p>
+              <div className="space-y-5">
+                {cliReference.map((item) => (
+                  <div
+                    key={item.command}
+                    className="rounded-md border border-border bg-bg-card p-5"
+                  >
+                    <h3 className="text-lg font-semibold text-text-primary mb-3 font-[family-name:var(--font-mono)]">
+                      qring {item.command}
+                    </h3>
+                    <div className="mb-3">
+                      <p className="text-sm text-text-dim mb-2">Options</p>
+                      {item.options.length === 0 ? (
+                        <p className="text-sm text-text-secondary">No command-specific options.</p>
+                      ) : (
+                        <div className="flex flex-wrap gap-2">
+                          {item.options.map((opt) => (
+                            <span
+                              key={opt}
+                              className="rounded border border-border px-2 py-1 text-xs font-[family-name:var(--font-mono)] text-accent-bright bg-accent-dim"
+                            >
+                              {opt}
+                            </span>
+                          ))}
+                        </div>
+                      )}
+                    </div>
+                    <CopyableTerminal title={`qring ${item.command}`} maxWidth="100%">
+                      <pre>
+                        {item.examples.map((ex, idx) => (
+                          <span key={ex}>
+                            <span className="text-green font-bold">$</span>{" "}
+                            <span className="text-accent-bright font-medium">{ex}</span>
+                            {idx < item.examples.length - 1 ? "\n" : ""}
+                          </span>
+                        ))}
+                      </pre>
+                    </CopyableTerminal>
+                  </div>
+                ))}
+              </div>
+            </section>
+
+          <section className="mb-16 border-t border-border pt-10">
+              <h2 className="text-3xl font-bold mb-4 text-text-primary">
+                MCP Prompt Cookbook
+              </h2>
+              <p className="text-text-secondary mb-6">
+                Every MCP tool in q-ring with a one-sentence prompt example you can paste into an agent chat.
+              </p>
+              <div className="space-y-3">
+                {mcpToolPrompts.map(([tool, prompt]) => (
+                  <div
+                    key={tool}
+                    className="rounded-md border border-border bg-bg-card p-4"
+                  >
+                    <p className="text-sm mb-2">
+                      <span className="font-[family-name:var(--font-mono)] text-accent-bright">
+                        {tool}
+                      </span>
+                    </p>
+                    <p className="text-sm text-text-secondary">{prompt}</p>
+                  </div>
+                ))}
+              </div>
+            </section>
+
+          <FadeIn delay={0.45}>
             <div className="border-t border-border pt-8 text-center">
               <p className="text-text-secondary mb-4">
                 Ready to explore more features?
diff --git a/web/components/motion/FadeIn.tsx b/web/components/motion/FadeIn.tsx
index 7430f5c..4cef0d4 100644
--- a/web/components/motion/FadeIn.tsx
+++ b/web/components/motion/FadeIn.tsx
@@ -51,7 +51,7 @@ export default function FadeIn({
     <motion.div
       className={className}
       variants={variants}
-      initial="hidden"
+      initial={false}
       whileInView="visible"
       viewport={{ once, amount }}
     >

From 388363a93ef81a8e862ecb295b7aaf79d54fc790 Mon Sep 17 00:00:00 2001
From: I4cDeath <publiclasstewart@gmail.com>
Date: Tue, 24 Mar 2026 19:16:25 +0800
Subject: [PATCH 6/6] docs(web): add short explanations to all CLI commands in
 reference

Made-with: Cursor
---
 web/app/docs/page.tsx | 56 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 55 insertions(+), 1 deletion(-)

diff --git a/web/app/docs/page.tsx b/web/app/docs/page.tsx
index ea02333..00b27a4 100644
--- a/web/app/docs/page.tsx
+++ b/web/app/docs/page.tsx
@@ -21,6 +21,7 @@ const installCmds = [
 const cliReference = [
   {
     command: "set <key> [value]",
+    description: "Store a secret (with optional quantum metadata)",
     options: [
       "-g, --global",
       "-p, --project",
@@ -44,6 +45,7 @@ const cliReference = [
   },
   {
     command: "get <key>",
+    description: "Retrieve a secret (collapses superposition if needed)",
     options: [
       "-g, --global",
       "-p, --project",
@@ -56,11 +58,13 @@ const cliReference = [
   },
   {
     command: "delete <key> (alias: rm)",
+    description: "Remove a secret from the keyring",
     options: ["-g, --global", "-p, --project", "--project-path <path>"],
     examples: ["qring delete LEGACY_TOKEN --project"],
   },
   {
     command: "list (alias: ls)",
+    description: "List all secrets with quantum status indicators",
     options: [
       "-g, --global",
       "-p, --project",
@@ -77,11 +81,13 @@ const cliReference = [
   },
   {
     command: "inspect <key>",
+    description: "Show full quantum state of a secret",
     options: ["-g, --global", "-p, --project", "--project-path <path>"],
     examples: ["qring inspect OPENAI_API_KEY --project"],
   },
   {
     command: "export",
+    description: "Export secrets as .env or JSON (collapses superposition)",
     options: [
       "-f, --format <format>",
       "-g, --global",
@@ -95,6 +101,7 @@ const cliReference = [
   },
   {
     command: "import <file>",
+    description: "Import secrets from a .env file",
     options: [
       "-g, --global",
       "-p, --project",
@@ -107,11 +114,13 @@ const cliReference = [
   },
   {
     command: "check",
+    description: "Validate project secrets against .q-ring.json manifest",
     options: ["--project-path <path>"],
     examples: ["qring check --project-path ."],
   },
   {
     command: "validate [key]",
+    description: "Test if a secret is actually valid with its target service",
     options: [
       "-g, --global",
       "-p, --project",
@@ -128,6 +137,7 @@ const cliReference = [
   },
   {
     command: "exec <command...>",
+    description: "Run a command with secrets injected into its environment (output auto-redacted)",
     options: [
       "-g, --global",
       "-p, --project",
@@ -141,36 +151,43 @@ const cliReference = [
   },
   {
     command: "scan [dir]",
+    description: "Scan a codebase for hardcoded secrets",
     options: ["--fix", "-g, --global", "-p, --project", "--project-path <path>"],
     examples: ["qring scan src --fix --project"],
   },
   {
     command: "lint <files...>",
+    description: "Lint specific files for hardcoded secrets (with optional auto-fix)",
     options: ["--fix", "-g, --global", "-p, --project", "--project-path <path>"],
     examples: ["qring lint src/config.ts src/client.ts --fix --project"],
   },
   {
     command: "context (alias: describe)",
+    description: "Show safe, redacted project context for AI agents (no secret values exposed)",
     options: ["-g, --global", "-p, --project", "--project-path <path>", "--json"],
     examples: ["qring context --project --json"],
   },
   {
     command: "remember <key> <value>",
+    description: "Store a key-value pair in encrypted agent memory (persists across sessions)",
     options: [],
     examples: ['qring remember deployment_note "rotate Stripe key after release"'],
   },
   {
     command: "recall [key]",
+    description: "Retrieve a value from agent memory, or list all keys",
     options: [],
     examples: ["qring recall deployment_note", "qring recall"],
   },
   {
     command: "forget <key>",
+    description: "Delete a key from agent memory",
     options: ["--all"],
     examples: ["qring forget deployment_note"],
   },
   {
     command: "approve <key>",
+    description: "Grant a scoped, reasoned, HMAC-verified approval token for MCP secret access",
     options: [
       "-g, --global",
       "-p, --project",
@@ -184,26 +201,31 @@ const cliReference = [
   },
   {
     command: "approvals",
+    description: "List all approval tokens with verification status",
     options: [],
     examples: ["qring approvals"],
   },
   {
     command: "hook:install",
+    description: "Install a git pre-commit hook that scans for hardcoded secrets",
     options: ["--project-path <path>"],
     examples: ["qring hook:install --project-path ."],
   },
   {
     command: "hook:uninstall",
+    description: "Remove the q-ring pre-commit hook",
     options: ["--project-path <path>"],
     examples: ["qring hook:uninstall --project-path ."],
   },
   {
     command: "hook:run",
+    description: "Run the pre-commit secret scan (called by the git hook)",
     options: [],
     examples: ["qring hook:run"],
   },
   {
     command: "wizard <name>",
+    description: "Set up a new service integration with secrets, manifest, and hooks",
     options: [
       "--keys <keys>",
       "--provider <provider>",
@@ -217,16 +239,19 @@ const cliReference = [
   },
   {
     command: "analyze",
+    description: "Analyze secret usage patterns and provide optimization suggestions",
     options: ["-g, --global", "-p, --project", "--project-path <path>"],
     examples: ["qring analyze --project"],
   },
   {
     command: "env",
+    description: "Show detected environment (wavefunction collapse context)",
     options: ["--project-path <path>"],
     examples: ["qring env --project-path ."],
   },
   {
     command: "generate (alias: gen)",
+    description: "Generate a cryptographic secret (quantum noise)",
     options: [
       "-f, --format <format>",
       "-l, --length <n>",
@@ -240,36 +265,43 @@ const cliReference = [
   },
   {
     command: "entangle <sourceKey> <targetKey>",
+    description: "Link two secrets — rotating one updates the other",
     options: ["-g, --global", "--source-project <path>", "--target-project <path>"],
     examples: ["qring entangle API_KEY API_KEY_BACKUP --source-project . --target-project ../worker"],
   },
   {
     command: "disentangle <sourceKey> <targetKey>",
+    description: "Unlink two entangled secrets",
     options: ["-g, --global", "--source-project <path>", "--target-project <path>"],
     examples: ["qring disentangle API_KEY API_KEY_BACKUP --source-project . --target-project ../worker"],
   },
   {
     command: "tunnel create <value>",
+    description: "Create a tunneled secret (returns tunnel ID)",
     options: ["--ttl <seconds>", "--max-reads <n>"],
     examples: ['qring tunnel create "temp-token" --ttl 300 --max-reads 1'],
   },
   {
     command: "tunnel read <id>",
+    description: "Read a tunneled secret (may self-destruct)",
     options: [],
     examples: ["qring tunnel read tu_abc123"],
   },
   {
     command: "tunnel destroy <id>",
+    description: "Destroy a tunneled secret immediately",
     options: [],
     examples: ["qring tunnel destroy tu_abc123"],
   },
   {
     command: "tunnel list (alias: tunnel ls)",
+    description: "List active tunnels",
     options: [],
     examples: ["qring tunnel list"],
   },
   {
     command: "teleport pack",
+    description: "Pack secrets into an encrypted bundle",
     options: [
       "-k, --keys <keys>",
       "-g, --global",
@@ -280,6 +312,7 @@ const cliReference = [
   },
   {
     command: "teleport unpack [bundle]",
+    description: "Unpack and import secrets from an encrypted bundle",
     options: [
       "-g, --global",
       "-p, --project",
@@ -290,26 +323,31 @@ const cliReference = [
   },
   {
     command: "audit",
+    description: "View the audit log (observer effect)",
     options: ["-k, --key <key>", "-a, --action <action>", "-n, --limit <n>", "--anomalies"],
     examples: ["qring audit --key OPENAI_API_KEY --action read --limit 50"],
   },
   {
     command: "audit:verify",
+    description: "Verify the integrity of the audit hash chain",
     options: [],
     examples: ["qring audit:verify"],
   },
   {
     command: "audit:export",
+    description: "Export audit events in a portable format",
     options: ["--since <date>", "--until <date>", "--format <fmt>", "-o, --output <file>"],
     examples: ["qring audit:export --since 2026-03-01 --format json -o audit.json"],
   },
   {
     command: "health",
+    description: "Check the health of all secrets",
     options: ["-g, --global", "-p, --project", "--project-path <path>"],
     examples: ["qring health --project"],
   },
   {
     command: "hook add",
+    description: "Register a new hook",
     options: [
       "--key <key>",
       "--key-pattern <pattern>",
@@ -329,41 +367,49 @@ const cliReference = [
   },
   {
     command: "hook list (alias: hook ls)",
+    description: "List all registered hooks",
     options: [],
     examples: ["qring hook list"],
   },
   {
     command: "hook remove <id> (alias: hook rm)",
+    description: "Remove a hook by ID",
     options: [],
     examples: ["qring hook remove hk_abc123"],
   },
   {
     command: "hook enable <id>",
+    description: "Enable a hook",
     options: [],
     examples: ["qring hook enable hk_abc123"],
   },
   {
     command: "hook disable <id>",
+    description: "Disable a hook",
     options: [],
     examples: ["qring hook disable hk_abc123"],
   },
   {
     command: "hook test <id>",
+    description: "Dry-run a hook with a mock payload",
     options: [],
     examples: ["qring hook test hk_abc123"],
   },
   {
     command: "env:generate",
+    description: "Generate a .env file from the project manifest (.q-ring.json)",
     options: ["--project-path <path>", "-o, --output <file>", "-e, --env <env>"],
     examples: ["qring env:generate --project-path . --env prod -o .env"],
   },
   {
     command: "status",
+    description: "Launch the quantum status dashboard in your browser",
     options: ["--port <port>", "--no-open"],
     examples: ["qring status --port 9876 --no-open"],
   },
   {
     command: "agent",
+    description: "Start the autonomous agent (background monitor)",
     options: [
       "-i, --interval <seconds>",
       "--auto-rotate",
@@ -375,6 +421,7 @@ const cliReference = [
   },
   {
     command: "rotate <key>",
+    description: "Attempt issuer-native rotation of a secret via its provider",
     options: [
       "-g, --global",
       "-p, --project",
@@ -385,6 +432,7 @@ const cliReference = [
   },
   {
     command: "ci:validate",
+    description: "CI-oriented batch validation of all secrets (exit code 1 on failure)",
     options: [
       "-g, --global",
       "-p, --project",
@@ -395,6 +443,7 @@ const cliReference = [
   },
   {
     command: "policy",
+    description: "Show project governance policy summary",
     options: ["--json"],
     examples: ["qring policy --json"],
   },
@@ -604,9 +653,14 @@ export default function DocsPage() {
                     key={item.command}
                     className="rounded-md border border-border bg-bg-card p-5"
                   >
-                    <h3 className="text-lg font-semibold text-text-primary mb-3 font-[family-name:var(--font-mono)]">
+                    <h3 className="text-lg font-semibold text-text-primary mb-1 font-[family-name:var(--font-mono)]">
                       qring {item.command}
                     </h3>
+                    {item.description && (
+                      <p className="text-sm text-text-secondary mb-4">
+                        {item.description}
+                      </p>
+                    )}
                     <div className="mb-3">
                       <p className="text-sm text-text-dim mb-2">Options</p>
                       {item.options.length === 0 ? (