code-context-control 2.92.3__tar.gz → 2.95.0__tar.gz

{code_context_control-2.92.3/code_context_control.egg-info → code_context_control-2.95.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.92.3
+Version: 2.95.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0
@@ -208,7 +208,7 @@ C3 exposes **21 tools** as a native MCP server. Your IDE calls them directly:
 | `c3_edits` | Edit-ledger queries, version diffs, restore points, per-branch filter, `verify` (did a failed `c3_edit` still land?) |
 | `c3_task` | Per-project PM — tasks, dependencies, milestones, time tracking (v2.53.0) |
 | `c3_artifacts` | Agent-config version history, diff & restore (v2.46.0) |
-| `c3_credentials` | Named-secret vault; values never enter model context (v2.58.0) |
+| `c3_credentials` | Named-secret vault; values never enter model context (v2.58.0). `import_env` bulk-imports a `.env` the agent still cannot read (v2.93.0) |
 | `c3_bitbucket` | Bitbucket Data Center — PRs, branches, builds, admin (v2.30.0) |
 | `c3_jira` | Jira Cloud + Data Center — JQL, issues, transitions (v2.56.0) |
 | `c3_project` | Cross-project discovery & operations; guarded writes (v2.31.0) |

{code_context_control-2.92.3 → code_context_control-2.95.0}/README.md

@@ -145,7 +145,7 @@ C3 exposes **21 tools** as a native MCP server. Your IDE calls them directly:
 | `c3_edits` | Edit-ledger queries, version diffs, restore points, per-branch filter, `verify` (did a failed `c3_edit` still land?) |
 | `c3_task` | Per-project PM — tasks, dependencies, milestones, time tracking (v2.53.0) |
 | `c3_artifacts` | Agent-config version history, diff & restore (v2.46.0) |
-| `c3_credentials` | Named-secret vault; values never enter model context (v2.58.0) |
+| `c3_credentials` | Named-secret vault; values never enter model context (v2.58.0). `import_env` bulk-imports a `.env` the agent still cannot read (v2.93.0) |
 | `c3_bitbucket` | Bitbucket Data Center — PRs, branches, builds, admin (v2.30.0) |
 | `c3_jira` | Jira Cloud + Data Center — JQL, issues, transitions (v2.56.0) |
 | `c3_project` | Cross-project discovery & operations; guarded writes (v2.31.0) |

{code_context_control-2.92.3 → code_context_control-2.95.0}/cli/c3.py

@@ -92,7 +92,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.92.3"
+__version__ = "2.95.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -6114,11 +6114,75 @@ def _bb_cmd_set_default(args, project_path: str) -> None:
     print(f"[OK] Default repo: {args.project}/{args.repo}")
 
 
+def cmd_tokens(args):
+    """Print token usage from the two local measurement logs.
+
+    Reads only; writes nothing. Counts come from .c3/tool_telemetry.jsonl
+    (what C3's tools returned) and .c3/session_stats.jsonl (what the whole
+    conversation cost, per the transcript).
+    """
+    from services import telemetry
+
+    project_path = getattr(args, "project_path", ".") or "."
+    days = max(0, int(getattr(args, "days", 30) or 0))
+    limit = max(1, int(getattr(args, "limit", 15) or 15))
+    tools = telemetry.aggregate_tool_telemetry(project_path, days=days)
+    sess = telemetry.aggregate_session_stats(project_path, days=days)
+
+    if getattr(args, "json", False):
+        print(json.dumps({"tools": tools, "sessions": sess}, indent=2))
+        return
+
+    window = "all history" if days == 0 else f"last {days}d"
+    print(f"\nToken usage — {window}")
+    print(f"  tool calls        {tools['total_calls']:>14,}")
+    print(f"  tool tokens       {tools['total_response_tokens']:>14,}")
+    print(f"  est. saved        {tools['estimated_saved_vs_full_read']:>14,}"
+          "   (vs full-read baseline)")
+    print(f"  session tokens    {sess['total_tokens']:>14,}"
+          f"   across {sess['session_count']} session(s)")
+    if sess["rows_seen"] and sess["all_zero_rows"] == sess["rows_seen"]:
+        # Do not let a log full of zeros read as "you used nothing".
+        print("  note: every session row is zero — these predate the v2.95.0 "
+              "Stop-hook fix; new sessions record real numbers.")
+
+    by = getattr(args, "by", "tool")
+    if by == "tool":
+        rows = sorted(({"name": k, **v} for k, v in tools["by_tool"].items()),
+                      key=lambda r: -r["response_tokens"])
+        head, cols = "tool", ("calls", "tokens", "avg")
+    elif by == "day":
+        rows, head, cols = tools["by_day"][::-1], "day", ("calls", "tokens", "avg")
+    elif by == "session":
+        rows, head, cols = tools["by_session"], "session", ("calls", "tokens", "avg")
+    else:
+        rows, head, cols = tools["by_target"], "file", ("calls", "tokens", "avg")
+
+    if not rows:
+        extra = ("  (no file attribution recorded yet — targets are logged "
+                 "from v2.95.0 onward)" if by == "file" else "  (nothing recorded)")
+        print(f"\n{extra}")
+        return
+
+    print(f"\n{head:<44}{cols[0]:>8}{cols[1]:>12}{cols[2]:>8}")
+    print("  " + "-" * 70)
+    for r in rows[:limit]:
+        calls = r.get("calls", 0)
+        toks = r.get("response_tokens", 0)
+        name = str(r.get("name", ""))
+        if len(name) > 43:
+            name = "…" + name[-42:]
+        print(f"{name:<44}{calls:>8}{toks:>12,}{toks // max(1, calls):>8}")
+    if len(rows) > limit:
+        print(f"  … {len(rows) - limit} more (use --limit)")
+    print()
+
+
 def cmd_creds(args):
     """Credential vault management (global + per-project scopes)."""
     sub = getattr(args, "creds_cmd", None)
     if not sub:
-        print("Usage: c3 creds {set,get,list,rm,import,usage} [args]")
+        print("Usage: c3 creds {set,get,list,rm,import,usage,audit} [args]")
         return
 
     project_path = getattr(args, "project_path", ".") or "."
@@ -6135,6 +6199,8 @@ def cmd_creds(args):
         _creds_cmd_import(args, project_path)
     elif sub == "usage":
         _creds_cmd_usage(args, project_path)
+    elif sub == "audit":
+        _creds_cmd_audit(args, project_path)
     else:
         print(f"Unknown creds subcommand: {sub}")
 
@@ -6321,6 +6387,25 @@ def _creds_cmd_rm(args, project_path: str) -> None:
         print(f"[error] no credential named '{args.name}' in {scope} scope")
 
 
+def _creds_import_table(rows: list) -> None:
+    """Print one line per parsed row: what it is, not what it holds.
+
+    Length and fingerprint are enough to tell two keys apart and to spot a
+    truncated paste; a value prefix would be part of the secret, so there
+    isn't one.
+    """
+    if not rows:
+        print("Nothing to import — no KEY=VALUE lines found.")
+        return
+    width = max(len(str(r["name"])) for r in rows)
+    print(f"{'NAME'.ljust(width)}  LINE  TYPE       LEN  FINGERPRINT  STATUS")
+    for r in rows:
+        status = r["detail"] or r["action"]
+        print(f"{str(r['name']).ljust(width)}  {str(r['line']).rjust(4)}  "
+              f"{r['ctype']:<9}  {str(r['value_len']).rjust(4)}  "
+              f"{(r['fingerprint'] or '-'):<11}  {status}")
+
+
 def _creds_cmd_import(args, project_path: str) -> None:
     from services import credential_store as cred_store
 
@@ -6328,20 +6413,126 @@ def _creds_cmd_import(args, project_path: str) -> None:
     if not env_path.exists():
         print(f"[error] file not found: {env_path}")
         return
+    only = [n.strip() for n in str(getattr(args, "only", "") or "").split(",")
+            if n.strip()] or None
+    dry_run = bool(getattr(args, "dry_run", False))
     try:
-        text = env_path.read_text(encoding="utf-8")
+        text = cred_store.read_env_file(env_path)
         result = cred_store.import_env(
             text, scope=_creds_scope(args), project_path=project_path,
             overwrite=bool(getattr(args, "overwrite", False)),
+            preview=dry_run, only=only,
+            source=str(env_path.resolve()), compare=dry_run,
         )
     except (cred_store.CredentialError, RuntimeError) as exc:
         print(f"[error] {exc}")
         return
+
+    if dry_run:
+        _creds_import_table(result["rows"])
+        print(f"\n[dry-run] {len(result['created'])} would be imported, "
+              f"{len(result['skipped'])} skipped. Nothing was written.")
+        return
+
     print(f"[OK] Imported {len(result['created'])} credential(s): "
           f"{', '.join(result['created']) or '-'}")
     if result["skipped"]:
-        print(f"Skipped {len(result['skipped'])}: {', '.join(result['skipped'])} "
-              "(use --overwrite to replace)")
+        # Reasons come off the rows, which already carry human text — the old
+        # output was a bare comma list that lumped four causes together.
+        detail = {r["name"]: r["detail"] for r in result["rows"] if r["reason"]}
+        print(f"Skipped {len(result['skipped'])}:")
+        for name in result["skipped"]:
+            print(f"  {name} - {detail.get(name, 'skipped')}")
+    notes = [r for r in result["rows"] if r["reason"] in ("no-assignment", "duplicate")]
+    if notes:
+        print(f"{len(notes)} line(s) ignored "
+              "(no KEY=VALUE, or redefined later in the file).")
+    if result["created"]:
+        _creds_audit_import(project_path, _creds_scope(args), result["created"],
+                            env_path)
+
+
+def _creds_audit_import(project_path: str, scope: str, created: list,
+                        env_path) -> None:
+    """The CLI import was the one credential mutation with no audit trail —
+    both REST paths logged and this did not. Names only, never values."""
+    try:
+        from services.edit_ledger import EditLedger
+        ledger = EditLedger(str(project_path))
+        ledger.log_edit(
+            file=f"cred://{len(created)} entries",
+            change_type="cred_import",
+            summary=f"import {len(created)} entries ({scope}) from "
+                    f"{Path(env_path).name} via c3 creds",
+            tags=["creds", "import"],
+            detail={"kind": "creds", "action": "import", "scope": scope,
+                    "names": list(created), "source": Path(env_path).name},
+        )
+        for name in created:
+            ledger.log_edit(
+                file=f"cred://{name}", change_type="cred_set",
+                summary=f"set {name} ({scope}) via c3 creds import",
+                tags=["creds", "set"],
+                detail={"kind": "creds", "action": "set", "name": name,
+                        "scope": scope},
+            )
+    except Exception:
+        pass
+    try:
+        from services.activity_log import ActivityLog
+        log = ActivityLog(str(project_path))
+        for name in created:
+            log.log("cred_action", {"kind": "creds", "action": "set",
+                                    "name": name, "scope": scope, "via": "cli"})
+    except Exception:
+        pass
+
+
+def _creds_cmd_audit(args, project_path):
+    """One timeline of every credential change and use.
+
+    Reads only. Prints names and command TEMPLATES — the logs never hold a
+    value, so there is nothing to redact on the way out.
+    """
+    from services import cred_audit
+
+    res = cred_audit.audit_events(
+        project_path,
+        name=getattr(args, "name", "") or "",
+        kind=getattr(args, "kind", "") or "",
+        action=getattr(args, "action", "") or "",
+        surface=getattr(args, "surface", "") or "",
+        q=getattr(args, "q", "") or "",
+        since=getattr(args, "since", "") or "",
+        limit=getattr(args, "limit", 40) or 40,
+    )
+    if getattr(args, "as_json", False):
+        print(json.dumps(res, indent=2))
+        return
+
+    counts = res["counts"]
+    print(f"\nCredential audit — {res['matched']} event(s): "
+          f"{counts['use']} use, {counts['change']} change"
+          + (f", {counts['exposing']} exposing" if counts["exposing"] else ""))
+    if not res["events"]:
+        print("  (nothing recorded for these filters)\n")
+        return
+
+    print(f"\n{'when':<20}{'kind':<8}{'action':<12}{'name':<24}{'where'}")
+    print("  " + "-" * 84)
+    for ev in res["events"]:
+        when = str(ev["ts"])[:19].replace("T", " ")
+        name = ev["name"] + (f".{ev['field']}" if ev["field"] else "")
+        where = ev["surface"] or "?"
+        if ev["scope"]:
+            where += f" ({ev['scope']})"
+        mark = " !" if ev["action"] in cred_audit.EXPOSING_ACTIONS else ""
+        print(f"{when:<20}{ev['kind']:<8}{ev['action']:<12}{name[:23]:<24}{where}{mark}")
+        if ev["cmd"]:
+            print(f"{'':<20}  cmd: {ev['cmd']}")
+    if res["truncated"]:
+        print(f"  … {res['matched'] - res['returned']} more (use --limit)")
+    print(f"\n  {res['note']}\n")
 
 
 def _creds_cmd_usage(args, project_path: str) -> None:
@@ -8769,6 +8960,7 @@ def main():
         "bitbucket": cmd_bitbucket,
         "jira": cmd_jira,
         "creds": cmd_creds,
+        "tokens": cmd_tokens,
         "access": cmd_access,
         "enforce": cmd_enforce,
         "override": cmd_override,

{code_context_control-2.92.3 → code_context_control-2.95.0}/cli/commands/parser.py

@@ -407,6 +407,21 @@ def build_parser(version: str, parse_cli_ide_arg):
     jr_default.add_argument("project_path", nargs="?", default=".")
 
     # ── Credential vault (v2.58.0) ──────────────────────────────────────
+    # ── Tokens ──────────────────────────────────────────────────────────
+    p_tokens = subparsers.add_parser(
+        "tokens",
+        help="Token usage — per tool, per day, per session, per file",
+    )
+    p_tokens.add_argument("--days", type=int, default=30,
+                          help="Window in days; 0 = all recorded history (default: 30)")
+    p_tokens.add_argument("--by", default="tool",
+                          choices=["tool", "day", "session", "file"],
+                          help="Which breakdown to print (default: tool)")
+    p_tokens.add_argument("--limit", type=int, default=15,
+                          help="Rows to show (default: 15)")
+    p_tokens.add_argument("--json", action="store_true",
+                          help="Emit the full aggregate as JSON")
+
     p_creds = subparsers.add_parser(
         "creds",
         help="Credential vault — named secrets for agents (global + per-project)",
@@ -452,6 +467,8 @@ def build_parser(version: str, parse_cli_ide_arg):
     cr_import.add_argument("env_file", help="Path to the .env file")
     cr_import.add_argument("--global", dest="use_global", action="store_true", help="Import into the global scope")
     cr_import.add_argument("--overwrite", action="store_true", help="Replace entries already registered in the target scope")
+    cr_import.add_argument("--dry-run", dest="dry_run", action="store_true", help="Show what would be imported; write nothing")
+    cr_import.add_argument("--only", default="", help="Comma-separated names to import (default: all)")
     cr_import.add_argument("--path", dest="project_path", default=".", help="Project directory (default: current)")
 
     cr_usage = creds_subs.add_parser(
@@ -461,6 +478,20 @@ def build_parser(version: str, parse_cli_ide_arg):
     cr_usage.add_argument("--json", dest="as_json", action="store_true", help="Emit raw JSON")
     cr_usage.add_argument("--path", dest="project_path", default=".", help="Project directory (default: current)")
 
+    cr_audit = creds_subs.add_parser(
+        "audit", help="Audit trail — every change AND use, on one timeline")
+    cr_audit.add_argument("name", nargs="?", default="", help="Limit to one credential (default: all)")
+    cr_audit.add_argument("--kind", default="", choices=["", "use", "change"],
+                          help="Show only uses or only changes (default: both)")
+    cr_audit.add_argument("--action", default="",
+                          help="Exact action: inject_env, template, reveal, cli_show, set, update, delete, import…")
+    cr_audit.add_argument("--surface", default="", help="Exact surface: shell, cli, mcp, ui, hub")
+    cr_audit.add_argument("--since", default="", help="ISO timestamp lower bound, e.g. 2026-08-01")
+    cr_audit.add_argument("-q", dest="q", default="", help="Free-text over name/field/cmd/project")
+    cr_audit.add_argument("--limit", type=int, default=40, help="Events to show (default: 40)")
+    cr_audit.add_argument("--json", dest="as_json", action="store_true", help="Emit raw JSON")
+    cr_audit.add_argument("--path", dest="project_path", default=".", help="Project directory (default: current)")
+
     # ── Agent Locks (docs/agent-locks.md) ───────────────────────────────
     # force-release is human-only: it bumps the fencing counter so a holder
     # that comes back is stale by construction. Agents get c3_locks instead,

{code_context_control-2.92.3 → code_context_control-2.95.0}/cli/guide/credentials.html

@@ -108,6 +108,7 @@
       <a href="#structured"      class="sidebar-link"><span class="icon">💳</span> Structured kinds</a>
       <a href="#exposure"        class="sidebar-link"><span class="icon">⚠️</span> Exposure flags</a>
       <a href="#hub-ui"          class="sidebar-link"><span class="icon">🖥️</span> Hub UI</a>
+      <a href="#bulk"            class="sidebar-link"><span class="icon">☑️</span> Filters &amp; bulk actions</a>
       <a href="#search"          class="sidebar-link"><span class="icon">🔎</span> Search &amp; qualifiers</a>
       <a href="#cli"             class="sidebar-link"><span class="icon">💻</span> CLI commands</a>
       <a href="#actions"         class="sidebar-link"><span class="icon">⚙️</span> Tool actions</a>
@@ -134,6 +135,7 @@
         <span class="pill pill-accent">v2.58.0 vault</span>
         <span class="pill pill-accent">v2.59.0 Hub tab</span>
         <span class="pill pill-accent">v2.61.0 search + drawer</span>
+        <span class="pill pill-accent">v2.94.0 filters + bulk + re-sync</span>
         <span class="pill pill-green">OS keyring</span>
         <span class="pill pill-purple">Injection-first</span>
         <span class="pill pill-amber">Write-only wire</span>
@@ -202,9 +204,12 @@
       <p>Anything shared across every project — a personal GitHub PAT, an OpenAI key — belongs in the global vault:</p>
       <pre><code>c3 creds set OPENAI_API_KEY --global</code></pre>
 
-      <p>Bulk-import an existing <code>.env</code> file (each line becomes an entry of type <code>env</code>):</p>
-      <pre><code>c3 creds import .env
-c3 creds import .env --global</code></pre>
+      <p>Bulk-import an existing <code>.env</code> file. A value spanning several lines inside one pair of quotes — a PEM key, a JSON service account — is imported whole and typed <code>multiline</code>; everything else becomes an entry of type <code>env</code>.</p>
+      <pre><code>c3 creds import .env --dry-run
+c3 creds import .env
+c3 creds import .env --global
+c3 creds import .env --only STRIPE_KEY,DB_URL</code></pre>
+      <p><code>--dry-run</code> prints a table of what would land — name, line, type, value length, fingerprint, and a reason for anything it will skip — and writes nothing. Skips are per-name and explained: <em>already exists</em>, <em>not a usable credential name</em>, <em>no value</em>, <em>quote never closes</em>, <em>redefined later in the file</em>.</p>
 
       <div class="callout callout-warn">
         <p><strong>Importing does not delete the source file.</strong> Once the values are in the vault, remove the <code>.env</code> (or confirm it is gitignored) — otherwise you have simply added a second copy.</p>
@@ -389,7 +394,11 @@ c3_shell(cmd=<span class="str">'terraform apply'</span>, env_creds=<span class="
     <section id="hub-ui" class="tool-section">
       <h2>Hub UI</h2>
 
-      <p>Run <code>c3 hub</code> and open the <strong>Credentials</strong> tab in the top bar. It manages the global vault and every registered project from one place. The same manager appears in each project's drill panel and in the per-project dashboard, so there is one interface to learn.</p>
+      <p>Run <code>c3 hub</code> and open the <strong>Credentials</strong> tab in the top bar. It manages the global vault and every registered project from one place. The same manager appears in each project's drill panel, so those two are one interface.</p>
+
+      <div class="callout">
+        <p><strong>The per-project dashboard is a lesser surface.</strong> The dashboard served by <code>c3 serve</code> has its own, older credentials panel: it can create, edit and delete entries and it has a page-level usage view the hub lacks, but it has no filters, no sort, no settings drawer, no context menu and no bulk actions. Everything below describes the <em>hub</em> manager. Use the hub, or a project's drill panel, for anything beyond a quick edit.</p>
+      </div>
 
       <h3>Two sub-tabs</h3>
       <table class="kv-table">
@@ -437,13 +446,76 @@ c3_shell(cmd=<span class="str">'terraform apply'</span>, env_creds=<span class="
           <tr><td class="grp-gated"><code>Delete credential…</code></td><td class="param-desc">Requires typing the credential name</td></tr>
         </tbody>
       </table>
+      <p>Four of these have bulk equivalents — see <a href="#bulk">Filters &amp; bulk actions</a>. The two that <em>enable</em> exposure deliberately do not.</p>
 
       <div class="callout callout-good">
         <p><strong>Destructive actions state their blast radius.</strong> Deleting shows where the value is stored, that anything resolving the name will start failing, and — for a global entry — how many projects override it locally and are therefore unaffected. The confirm button stays disabled until you type the credential's name.</p>
       </div>
 
       <h3>Importing a <code>.env</code></h3>
-      <p><strong>Import .env</strong> in the manager toolbar takes pasted <code>KEY=VALUE</code> lines. Comments and <code>export </code> prefixes are tolerated; each line becomes an entry of type <code>env</code>. Existing names are skipped rather than overwritten, and the response reports created and skipped counts by name.</p>
+      <p><strong>Import .env</strong> in the manager toolbar opens a chooser: pick a file, drop one on the panel, or paste <code>KEY=VALUE</code> lines. Comments and <code>export </code> prefixes are tolerated.</p>
+      <p>Nothing is written until you say so. <strong>Preview</strong> parses the file and shows a table of every row — name, line, type, value length, and a fingerprint — with anything it cannot import disabled and explained in place. Tick the rows you want and press <strong>Import</strong>. <em>Replace entries that already exist</em> is off by default, so a second import of the same file is a no-op rather than a silent overwrite.</p>
+      <p>Replacing an existing entry <strong>rotates its value and nothing else</strong>. The description you wrote, the custom env var, the type you chose, and the auto-inject and agent-read settings all survive. Before 2.93.0 an overwrite rebuilt the entry from scratch, which quietly turned auto-injection off.</p>
+      <p>If C3 read the file from a path on this machine, it remembers which file each entry came from — see <a href="#resync">Re-syncing a <code>.env</code></a>. A pasted body has no path to remember, so it records no source.</p>
+      <div class="callout callout-good">
+        <p><strong>The preview never shows a value, not even the first few characters.</strong> A prefix is part of the secret. Rows are identified by length and a <code>sha256</code> fingerprint, which is enough to tell two keys apart and to notice a truncated paste, and keeps the rule that a stored value never travels back to the browser.</p>
+      </div>
+
+      <h3 id="resync">Re-syncing a <code>.env</code></h3>
+      <p>A <code>.env</code> drifts all week; the first import is never the last one. When C3 imported entries from a path on this machine it records that path, and the manager grows an <strong>Imported from</strong> strip listing each remembered file with an entry count, when it was last synced, and a <strong>Re-sync</strong> button.</p>
+      <p>Re-sync re-reads the file <em>on the server</em> and compares every value against the stored one by digest, so it can tell you what changed without either value reaching the browser. Each row comes back as one of four answers:</p>
+      <table class="params-table">
+        <thead><tr><th>Row</th><th>Means</th></tr></thead>
+        <tbody>
+          <tr><td><code>unchanged</code></td><td class="param-desc">The vault already holds this exact value. Left unticked — rewriting it would be a keyring write and a ledger row for nothing.</td></tr>
+          <tr><td><code>changed</code></td><td class="param-desc">The file and the vault differ. Ticked by default.</td></tr>
+          <tr><td><code>new</code></td><td class="param-desc">In the file, not in the vault. Ticked by default.</td></tr>
+          <tr><td><code>no longer in the file</code></td><td class="param-desc">Imported from this file once, and the file has since dropped it. Listed separately and <strong>never deleted</strong>.</td></tr>
+        </tbody>
+      </table>
+      <div class="callout">
+        <p><strong>A key leaving a <code>.env</code> is not a signal to delete it.</strong> Plenty of credentials outlive the file that seeded them, so C3 reports the ones that vanished and stops there. If you do mean to remove them, select them in the list and delete them, where the confirmation can tell you what else that breaks.</p>
+      </div>
+      <div class="callout callout-warn">
+        <p><strong>Re-sync compares, it cannot adjudicate.</strong> It knows the file and the vault disagree; it does not know which one you changed. A value you edited in the vault by hand reads as <code>changed</code>, and re-syncing overwrites it with the file's. The file is the source of truth here — if the vault holds the newer value, update the file instead.</p>
+      </div>
+      <p>If the file changes between the preview and the import, the commit is refused rather than silently applying content you never saw: press <strong>Re-check</strong> to see the new answer.</p>
+    </section>
+
+    <hr class="divider">
+
+    <!-- ═══════════════════════════════════════ BULK ═══ -->
+    <section id="bulk" class="tool-section">
+      <h2>Filters &amp; bulk actions</h2>
+
+      <h3>Narrowing the list</h3>
+      <p>Above every credential list is a row of chips — <code>agent-readable</code>, <code>auto-inject</code>, <code>structured</code>, <code>shadowing</code>, <code>from .env</code>, <code>never used</code>, <code>stale &gt;30d</code> — each carrying a live count. Chips <strong>narrow</strong>: ticking two shows the rows matching both. They compose with the filter box and its <code>key:value</code> qualifiers, and <kbd>/</kbd> jumps to that box from anywhere on the page.</p>
+      <p>Sorting offers name, last used, most used, exposure and newest. <em>Exposure</em> floats the risky rows up: agent-readable counts double, auto-inject counts once.</p>
+
+      <h3>Selecting rows</h3>
+      <p><strong>Select</strong> in the toolbar turns on checkboxes. Click a row to tick it, <kbd>Shift</kbd>-click to extend a range, or use the header checkbox to take everything currently shown — which is what makes the chips useful: filter to <code>agent-readable</code>, select all, revoke.</p>
+
+      <table class="params-table action-table">
+        <thead><tr><th>Bulk action</th><th>Notes</th></tr></thead>
+        <tbody>
+          <tr><td class="grp-read"><code>Check resolution</code></td><td class="param-desc">Read-only. Confirms each value can still be decoded.</td></tr>
+          <tr><td class="grp-write"><code>Revoke agent read</code></td><td class="param-desc">Sets <code>agent_readable=false</code> on every selected entry.</td></tr>
+          <tr><td class="grp-write"><code>Disable auto-inject</code></td><td class="param-desc">Sets <code>inject=false</code> on every selected entry.</td></tr>
+          <tr><td class="grp-read"><code>Export CSV</code></td><td class="param-desc">Metadata only — name, scope, project, type, storage, env var, exposure, usage, source, description. <strong>No values</strong>, because none are in the browser to export.</td></tr>
+          <tr><td class="grp-gated"><code>Delete…</code></td><td class="param-desc">Requires typing <code>DELETE &lt;count&gt;</code>.</td></tr>
+        </tbody>
+      </table>
+
+      <div class="callout callout-warn">
+        <p><strong>Bulk can only ever reduce exposure.</strong> There is no bulk "allow agent read" and no bulk "enable auto-inject". Granting stays one entry at a time behind a confirmation that names it, because a bulk grant widens access to many secrets from a single checkbox and the one row you did not mean to include is exactly the one that matters. The server enforces this allowlist too — it is not merely a missing button.</p>
+        <p>Bulk rename, retype, storage migration and copy-to-global are absent for a different reason: each silently changes which credential a consumer resolves, and no dialog makes that visible after the fact.</p>
+      </div>
+
+      <div class="callout callout-good">
+        <p><strong>Bulk delete says what else it breaks.</strong> Deleting a project entry does not remove the name — it hands it back to the global vault, so the project starts resolving the <em>global</em> value instead of failing. The confirmation lists exactly which of the selected rows do that, before you type the count.</p>
+      </div>
+
+      <p>A partial run reports as partial: the toast reads <code>7 ok, 2 failed</code> and names the first failure, rather than claiming nine successes. Every mutation is logged to the ledger by <code>(scope, project, name)</code> — a name alone is ambiguous when the same name legitimately lives in the global vault and in several projects at once.</p>
     </section>
 
     <hr class="divider">
@@ -476,6 +548,7 @@ c3_shell(cmd=<span class="str">'terraform apply'</span>, env_creds=<span class="
           <tr><td class="param-name"><code>inject:</code></td><td class="param-desc">Auto-inject flag</td><td><code>inject:true</code></td></tr>
           <tr><td class="param-name"><code>agent:</code></td><td class="param-desc"><code>agent_readable</code> flag</td><td><code>agent:true</code></td></tr>
           <tr><td class="param-name"><code>shadow:</code></td><td class="param-desc">Involved in an override, either direction</td><td><code>shadow:true</code></td></tr>
+          <tr><td class="param-name"><code>source:</code></td><td class="param-desc">Which <code>.env</code> an import recorded; <code>source:none</code> for the hand-made ones</td><td><code>source:.env</code></td></tr>
         </tbody>
       </table>
 
@@ -506,7 +579,7 @@ c3_shell(cmd=<span class="str">'terraform apply'</span>, env_creds=<span class="
           <tr><td class="grp-read"><code>c3 creds list</code></td><td class="param-desc">Merged view — project entries plus the globals visible here. Names and metadata only.</td></tr>
           <tr><td class="grp-read"><code>c3 creds get NAME</code></td><td class="param-desc">Entry metadata, masked. <code>--show</code> prints the value to <em>your</em> terminal (not the agent's).</td></tr>
           <tr><td class="grp-write"><code>c3 creds rm NAME</code></td><td class="param-desc">Delete the value and the registry entry. <code>--global</code> to target the shared vault.</td></tr>
-          <tr><td class="grp-write"><code>c3 creds import FILE</code></td><td class="param-desc">Import <code>KEY=VALUE</code> lines. Names already registered in the target scope are skipped unless you pass <code>--overwrite</code>.</td></tr>
+          <tr><td class="grp-write"><code>c3 creds import FILE</code></td><td class="param-desc">Import <code>KEY=VALUE</code> lines, including values quoted across several lines. Names already registered in the target scope are skipped unless you pass <code>--overwrite</code>, and each skip is reported with its reason. <code>--dry-run</code> shows what would land and writes nothing; <code>--only NAME,...</code> imports a subset; <code>--global</code> targets the shared vault.</td></tr>
         </tbody>
       </table>
 
@@ -595,9 +668,44 @@ c3_shell(cmd=<span class="str">'terraform apply'</span>, env_creds=<span class="
         </tr>
       </table>
 
-      <p>To review what happened to one credential:</p>
+      <h3>The Audit view</h3>
+      <p>Those two logs answer different halves of the same question and, until v2.95.0, nothing joined them: <strong>changes</strong> live in the activity log, <strong>uses</strong> live in <code>.c3/cred_usage.jsonl</code>. <strong>Credentials &rarr; Audit</strong> in the hub merges them into one timeline, newest first, and every credential list has its own <strong>Audit</strong> button scoped to that vault.</p>
+
+      <table class="params-table">
+        <thead><tr><th>Column</th><th>What it tells you</th></tr></thead>
+        <tbody>
+          <tr><td><code>when</code></td><td class="param-desc">UTC timestamp of the event.</td></tr>
+          <tr><td><code>kind</code></td><td class="param-desc"><code>change</code> (created, edited, deleted, imported, bulk action) or <code>use</code>.</td></tr>
+          <tr><td><code>action</code></td><td class="param-desc"><code>inject_env</code>, <code>template</code>, <code>reveal</code>, <code>cli_show</code>, <code>set</code>, <code>update</code>, <code>delete</code>, <code>import</code>, <code>batch_*</code>.</td></tr>
+          <tr><td><code>name</code></td><td class="param-desc">The credential, with the field for a structured kind (<code>CARD.number</code>). Click it to filter the timeline to that one key.</td></tr>
+          <tr><td><code>where</code></td><td class="param-desc">Which project, or the global vault, plus the surface it came through — <code>shell</code>, <code>cli</code>, <code>mcp</code>, <code>ui</code>, <code>hub</code>.</td></tr>
+          <tr><td><code>cmd</code></td><td class="param-desc">For a shell use, the command that needed it — expandable.</td></tr>
+          <tr><td><code>exit</code></td><td class="param-desc">The command's exit code, so a credential used by a failing command is visible as such.</td></tr>
+        </tbody>
+      </table>
+
+      <div class="callout callout-warn">
+        <p><strong>The <code>exposing</code> filter is the one to reach for first.</strong> <code>reveal</code> and <code>cli_show</code> are the only two actions that put a plaintext value somewhere a person or a model can read it. Everything else hands the value to a subprocess and it is never surfaced. Those rows are badged and counted separately rather than left to be spotted in a list.</p>
+      </div>
+
+      <div class="callout callout-good">
+        <p><strong>There is nothing to redact in the trail.</strong> Neither log has ever stored a value. <code>cmd</code> is the <em>raw template</em> you typed &mdash; <code>{{cred:NPM_TOKEN}}</code> or <code>$NPM_TOKEN</code>, never the substitution &mdash; which is why the command is shown in full instead of masked. Masking it would imply there was something behind the mask.</p>
+      </div>
+
+      <p>A project's timeline includes the global vault, because a shared credential used from a project records into <code>~/.c3</code> rather than the project &mdash; reading only the project would lose exactly the entries a shared secret generates. The cross-project view reads that shared vault once, not once per project.</p>
+
+      <p>From the terminal:</p>
+      <pre><code>c3 creds audit                        <span class="cmt"># everything, newest first</span>
+c3 creds audit NPM_TOKEN              <span class="cmt"># one credential's whole history</span>
+c3 creds audit --kind change          <span class="cmt"># who changed what</span>
+c3 creds audit --action reveal        <span class="cmt"># every plaintext read</span>
+c3 creds audit --since 2026-08-01 --json</code></pre>
+
+      <p>Or, for the change half alone, through the edit ledger:</p>
       <pre><code>c3_edits(action=<span class="str">'history'</span>, file=<span class="str">'cred://NPM_TOKEN'</span>)</code></pre>
 
+      <p class="param-desc">Change rows come from the live activity log. Entries older than its last rotation are in the archive and are not merged into this view.</p>
+
       <div class="callout">
         <p><strong>The vault is excluded from the Oracle Discovery API.</strong> External LLMs reaching C3 over MCP/HTTP cannot see credential tools at all — not the metadata, not the names. The exclusion is a hard exclusion, not a permission check.</p>
       </div>