@i4ctime/q-ring 0.11.0 → 0.11.7

package/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
 
@@ -811,21 +811,66 @@ Add to `~/.claude/claude_desktop_config.json`:
 }
 ```
 
-## Cursor Plugin
+## Editor Plugins
+
+The q-ring repo ships three first-party editor packs — each one adds rules/steering, agents, commands, skills, hooks, and the MCP connector to its host editor.
+
+| Plugin | Editor | Highlights |
+|--------|--------|-----------|
+| [`cursor-plugin/`](cursor-plugin/README.md) | [Cursor](https://cursor.com) | 3 rules, 5 skills, 2 agents, 8 slash commands, 3 hooks, MCP autoconnect |
+| [`kiro-plugin/`](kiro-plugin/README.md) | [Kiro](https://kiro.dev) | Official [Power](https://kiro.dev/docs/powers/create/) layout: `POWER.md`, root `mcp.json`, `steering/`, `hooks/`; or flatten with `plugin:sync:kiro` |
+| [`claude-code-plugin/`](claude-code-plugin/README.md) | [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) | `CLAUDE.md` memory, project `.mcp.json`, 2 subagents, 8 slash commands, 5 skills, 3 hook scripts |
+
+### Cursor Plugin
 
 The **q-ring Cursor Plugin** brings quantum secret management directly into your IDE with rules, skills, agents, commands, hooks, and a built-in MCP connector.
 
 | Component | What it does |
 |-----------|-------------|
 | **3 Rules** | Always-on guidance: never hardcode secrets, use q-ring for all ops, warn about `.env` files |
-| **4 Skills** | Auto-triggered by context: secret management, scanning, rotation, project onboarding |
+| **5 Skills** | Auto-triggered by context: secret management, scanning, rotation, project onboarding, exec-with-secrets |
 | **2 Agents** | `security-auditor` (proactive monitoring) and `secret-ops` (day-to-day assistant) |
-| **5 Commands** | `/qring:scan-secrets`, `/qring:health-check`, `/qring:rotate-expired`, `/qring:setup-project`, `/qring:teleport-secrets` |
-| **2 Hooks** | `afterFileEdit` (lint scan), `sessionStart` (project context) |
+| **8 Commands** | `/qring:scan-secrets`, `/qring:health-check`, `/qring:rotate-expired`, `/qring:setup-project`, `/qring:teleport-secrets`, `/qring:dashboard`, `/qring:exec-safe`, `/qring:analyze` |
+| **3 Hooks** | `afterFileEdit` (lint scan), `sessionStart` (project context), `beforeShellExecution` (`.env` guard) |
 | **MCP Connector** | Auto-connects to `qring-mcp` via stdio — all 44 tools available |
 
 Install from the Cursor marketplace or see [`cursor-plugin/README.md`](cursor-plugin/README.md) for manual setup.
 
+### Kiro Plugin (Power)
+
+The [`kiro-plugin/`](kiro-plugin/) directory is a Kiro **Power** per [Create powers](https://kiro.dev/docs/powers/create/): `POWER.md` (metadata, onboarding, steering map), root [`mcp.json`](kiro-plugin/mcp.json) (MCP server must match the server name referenced in the power), and [`steering/`](kiro-plugin/steering/) for workflows. Install from Kiro → **Powers** → **Add power from Local Path** and select `kiro-plugin`, or publish the folder on GitHub and use **Add power from GitHub**.
+
+Always-on steering blocks hardcoded secrets and routes everything through q-ring; `manual` steering files act as agent personas (`#qring-secret-ops`, `#qring-security-auditor`), skill packs, and slash-style commands (`#qring-cmd-scan-secrets`, etc.). Optional hooks live in `hooks/` for copy into `.kiro/hooks/`.
+
+```bash
+# Alternative: flatten into ~/.kiro (settings + steering + hooks)
+pnpm run plugin:sync:kiro
+
+# Or scope to a single project
+pnpm run plugin:sync:kiro -- /path/to/your/project/.kiro
+```
+
+See [`kiro-plugin/README.md`](kiro-plugin/README.md) for the full breakdown.
+
+### Claude Code Plugin
+
+For [Claude Code](https://docs.claude.com/en/docs/claude-code/overview), q-ring ships a `CLAUDE.md` memory file, a project-scoped `.mcp.json`, two [subagents](https://docs.claude.com/en/docs/claude-code/sub-agents) (`secret-ops`, `security-auditor`), eight [slash commands](https://docs.claude.com/en/docs/claude-code/slash-commands) (`/qring-scan-secrets`, `/qring-health-check`, …), five [skills](https://docs.claude.com/en/docs/claude-code/skills), and three [hooks](https://docs.claude.com/en/docs/claude-code/hooks) (post-edit lint reminder, pre-Bash `.env` guard, session-start context primer).
+
+```bash
+# Install into the current project ($PWD)
+pnpm run plugin:sync:claude
+
+# Install agents/commands/skills/hooks at user scope (~/.claude)
+pnpm run plugin:sync:claude -- --user
+
+# Or target a specific project
+pnpm run plugin:sync:claude -- /path/to/your/project
+```
+
+Existing `CLAUDE.md`, `.mcp.json`, or `.claude/settings.json` files are never silently overwritten — the script writes a `<filename>.qring-template` next to them so you can merge by hand. Pass `--force` to overwrite.
+
+See [`claude-code-plugin/README.md`](claude-code-plugin/README.md) for the full breakdown.
+
 ## Architecture
 
 ```
@@ -900,7 +945,11 @@ Optional per-project configuration:
 - Run **`pnpm run lint`**, **`pnpm run typecheck`**, and **`pnpm run test:ci`** before opening a PR.
 - Tests or sandboxes can point the audit log elsewhere with **`QRING_AUDIT_DIR`** (directory is created if missing); default is `~/.config/q-ring/audit.jsonl`.
 - Optional local pre-commit: **`qring hook:install`** (uses this package’s `precommit` hook when `qring` is on your `PATH`).
-- After changing the Cursor plugin under **`cursor-plugin/`**, run **`pnpm run plugin:sync`** to copy it to `~/.cursor/plugins/local/my-plugin` (or pass a custom path). See also [docs/cli-mcp-parity.md](docs/cli-mcp-parity.md).
+- After changing one of the editor plugins:
+  - **Cursor:** `pnpm run plugin:sync` copies `cursor-plugin/` to `~/.cursor/plugins/local/my-plugin` (or pass a custom path).
+  - **Kiro:** `pnpm run plugin:sync:kiro` copies `kiro-plugin/mcp.json` → `~/.kiro/settings/mcp.json`, plus `steering/` and `hooks/` (or pass a project `.kiro` path). Prefer adding `kiro-plugin/` as a [Power](https://kiro.dev/docs/powers/create/) from the Powers panel instead.
+  - **Claude Code:** `pnpm run plugin:sync:claude` copies `claude-code-plugin/` into the current directory (or pass a project path; add `--user` to install at `~/.claude/`).
+- See also [docs/cli-mcp-parity.md](docs/cli-mcp-parity.md).
 
 ## 📜 License