From a3dfa73fef7873339816021cbb9f8226a7a94d0c Mon Sep 17 00:00:00 2001
From: "Snow Lee (Sungwon)" <snow@runbear.io>
Date: Tue, 18 Aug 2026 15:08:44 -0700
Subject: [PATCH] Catch a credential when it syncs, not only when you share it
 (#162)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* refactor(secrets): lift the share-time credential rules into internal/secrets

The rules only ever ran on the rarest path a file takes. Moving them out of
internal/webapp is what lets internal/syncer run the same six rules on the
path every file takes, without inverting the dependency.

Pure move plus one addition: Label(), the six human strings that until now
lived only in the frontend's SECRET_LABELS — so 'bdrive share' stops printing
a bare rule id where the web dialog says 'an AWS access key'. Rule ids and the
rule/line JSON tags are unchanged: Browser.tsx keys off them, so they are a
wire contract.

* feat(sync): warn when a synced file looks like it holds a credential

The six share-time rules now run on the path every file takes. A file with an
AWS key in it used to ride a normal sync to the hub, to every teammate's disk
and into every future agent's context with no badge and no warning — while the
Share dialog one click later blocked that exact file.

Warn, never block: the op is journaled and pushed exactly as before. A hold arm
would mean a false positive silently parks someone's changes, and it would
break the cycle's degrade-to-offline posture.

- scan() reads the blob PutBlobFile just wrote (the bytes that were actually
  journaled), only on the branches that wrote one — an unchanged file is still
  never re-read.
- Findings persist per path in secrets-<mount>.json, merged rather than
  replaced: nearly every cycle scans zero files, and a whole-set rewrite would
  erase the warning seconds after it appeared. Fixing the file clears it.
- bdrive status grows a secrets block; the agent hook appends one advisory
  sentence. Rule ids and line numbers only, never the matched bytes.
- SaveSecrets failing logs and continues: advisory telemetry never gets a veto
  over convergence.

* docs: the credential check now runs on sync, not only on share

README, the CLI reference and project-files get the new bdrive status block
and the warn-never-block posture, with the three limits stated (checked when
it changes, first 1 MiB, writing device only). Diagrams: internal/secrets is a
package of its own in the overview, secretLog joins the sync engine, and the
share-gate class notes that it no longer owns the rules.

* test(sync): assert an unchanged file is never re-read for credentials

The check must ride the branch that already reads the file. Clearing the record
by hand and cycling proves it: a scan that re-read unchanged files would put the
finding back, and the daemon's 3-second tick would pay for it on every file.
---
 README.md                                     |  25 +++-
 architecture/cli-sync.md                      |  14 ++
 architecture/overview.md                      |   4 +
 architecture/webapp-server.md                 |   9 +-
 cmd/bdrive/cmds.go                            |  36 +++++
 cmd/bdrive/hooksync.go                        |  54 +++++++-
 cmd/bdrive/hooksync_test.go                   |  81 ++++++++++++
 cmd/bdrive/migrate.go                         |   6 +-
 cmd/bdrive/share.go                           |   6 +-
 internal/secrets/secrets.go                   |  99 ++++++++++++++
 internal/secrets/secrets_test.go              |  78 +++++++++++
 internal/store/secrets.go                     |  57 ++++++++
 internal/store/secrets_test.go                |  84 ++++++++++++
 internal/store/store.go                       |  19 ++-
 internal/syncer/secrets.go                    |  95 ++++++++++++++
 internal/syncer/syncer.go                     |  36 ++++-
 internal/syncer/syncer_test.go                | 124 ++++++++++++++++++
 internal/webapp/cli_e2e_test.go               |  69 ++++++++++
 internal/webapp/secrets.go                    |  74 -----------
 internal/webapp/secrets_test.go               |  63 ---------
 internal/webapp/shares.go                     |   6 +-
 internal/webapp/shares_test.go                |  12 +-
 web/docs/src/content/docs/reference/cli.md    |  32 ++++-
 .../content/docs/reference/project-files.md   |   4 +-
 24 files changed, 913 insertions(+), 174 deletions(-)
 create mode 100644 internal/secrets/secrets.go
 create mode 100644 internal/secrets/secrets_test.go
 create mode 100644 internal/store/secrets.go
 create mode 100644 internal/store/secrets_test.go
 create mode 100644 internal/syncer/secrets.go
 delete mode 100644 internal/webapp/secrets.go
 delete mode 100644 internal/webapp/secrets_test.go

diff --git a/README.md b/README.md
index 278f916..55e66b9 100644
--- a/README.md
+++ b/README.md
@@ -258,7 +258,7 @@ hub's own storage, never something a syncing client points at directly:
 | `bdrive sync [folder]` | Run one sync cycle now. `--note <text>` stamps session context (e.g. an agent session id) onto changes — shown in `bdrive log` and hub history; keeps applying to daemon-committed changes until `--note-ttl` (default 30m) expires. `--prune` also removes from the hub what `.bdriveignore` now excludes (files stay on disk everywhere). `--hook <label>` is agent-hook plumbing: event JSON on stdin, sync + note, gated-link formula (Claude Code hook JSON) on stdout |
 | `bdrive hooks [install\|uninstall]` | Register turn-boundary sync hooks in each agent platform's user config (Claude Code, Codex, Gemini CLI, Hermes) — pull each turn, push after edits, session-note stamping, agent-read tracking. Once per machine, covering every session; run automatically by `bdrive init`; idempotent (`--agent` overrides detection) |
 | `bdrive read-log [folder]` | Hook plumbing: queue agent file reads from a hook event (JSON on stdin) for the hub's read heatmap — native reads, grep matches, and files named in shell commands; drained on the next sync. Registered by `bdrive hooks install` |
-| `bdrive status [folder]` | Projects, daemon state, pending changes |
+| `bdrive status [folder]` | Projects, daemon state, pending changes, and any synced files that looked like they held credentials when they last changed |
 | `bdrive log [folder] [-p path] [-n N]` | Change history: account, device, time, file — newest first by the time shown, which is when the file was written (ops recorded before this was tracked, and deletes, show their sync time instead) |
 | `bdrive restore <file> [version]` | Put an earlier version of a file back, as a new change (`--list` shows the versions; no version = the previous one). Nothing is erased and it syncs everywhere like any edit. To un-create a file a run *created*, use **undo — remove file** on that row in the hub's History view — or **undo this run** in the run card's header to put back every file that run touched at once |
 | `bdrive export [folder]` | Export the whole project — every device's journal, all blobs, full history — from its hub to a portable `.tar.gz` (`-o` names the file) |
@@ -546,8 +546,8 @@ line, never the matched text, and nothing is shared:
 ```
 $ bdrive share deploy.md
 Error: deploy.md looks like it contains credentials (checked at the moment you shared it):
-  line 12   aws_access_key_id
-  line 40   private_key
+  line 12   an AWS access key (aws_access_key_id)
+  line 40   a private key (private_key)
 Nothing was shared. Re-run with --force if that is intentional.
 ```
 
@@ -558,6 +558,25 @@ forever — so a key committed into an already-shared file is never caught —
 and it only reads the first 1 MiB. It shortens the odds; it is not a
 promise that a file is clean.
 
+The same six rules also run **on every file as it syncs**, which is the path
+every file takes rather than the rare one. They only ever warn: the change is
+journaled and pushed exactly as it would be otherwise, and the finding shows up
+in `bdrive status` and in the agent's context at the start of its next turn.
+
+```
+$ bdrive status
+  secrets: 1 file(s) looked like they contain credentials when they last changed
+             deploy.md:12  an AWS access key
+```
+
+Nothing is blocked, held, or un-pushed — a false positive costs a line of text,
+never a stalled file. Fixing the file is the whole remedy: the next sync cycle
+reads it again and the line goes away, with no command and no flag. Same limits
+as above — a file is checked **when it changes**, and only its first 1 MiB, so
+this never says a file is clean. It runs on the device that made the change:
+a file another device synced before its version had this check stays unflagged
+until it next changes here.
+
 ### Agent integration
 
 Setup is conversational — one paste and the agent does the rest, hooks
diff --git a/architecture/cli-sync.md b/architecture/cli-sync.md
index ef49371..0b8c239 100644
--- a/architecture/cli-sync.md
+++ b/architecture/cli-sync.md
@@ -132,11 +132,23 @@ classDiagram
         +LogRead(rel, session) read spool
         +PendingReads dedup on path+session
         +LogInbound / DrainInbound
+        +LoadSecrets / SaveSecrets mountID
         +Lock() flock
     }
+    note for Store "secrets-mount-id.json is the credential-finding record: what `bdrive status` prints and what the agent hook appends a sentence about. Like the inbound spool it outlives the cycle that wrote it — the daemon scans the write seconds before the turn starts — but unlike it, it is STATE and is never drained: a finding stands until the file changes without it"
     note for Store "internal/store — ~/.bdrive/volumes/mount-id: content-addressed blobs, per-device journal copies, state cache, paused marker (free funcs Paused/SetPaused, no flock)"
     note for Store "inbound.jsonl is the read spool's twin, running the other way: materialize appends every path it wrote or removed for a peer, and `sync --hook` drains it into the turn's context (re-read before editing). A spool and not a Result field because the daemon usually materializes the change seconds before the turn starts, so the hook's own cycle sees nothing. Capped, best-effort, never fails a cycle. Result.Inbound now carries the SAME events for the post_sync hook and is not a duplicate to delete: that consumer fires from the cycle itself, and a second drainer would silently empty the agent hook's context"
 
+    class secretLog {
+        <<syncer/secrets.go>>
+        found map path to Findings
+        dirty bool
+        +scanBlob(store, rel, sum)
+        +set / drop per path
+    }
+    note for secretLog "internal/secrets' six rules, run on the path EVERY file takes. Only on the branches that just called PutBlobFile — the cheap size+mtime path never re-reads a file — and it reads the BLOB, i.e. the exact bytes that were hashed and journaled, so a line number can never describe content no op captured"
+    note for secretLog "WARN ONLY: the op is journaled and pushed exactly as before. Holding it would strand the file behind a false positive and break the cycle's degrade-to-offline posture. Merged PER PATH into secrets-mount-id.json and written in finish only when dirty — nearly every cycle scans zero files, so a whole-set rewrite would erase the warning seconds after it appeared. A save error is logged, never returned: advisory telemetry gets no veto over convergence"
+
     class Op {
         +Seq +Lamport +Time +Device
         +Author +User +UserName
@@ -181,6 +193,8 @@ classDiagram
     Explain --> Filter : own fresh instance
     Explain ..> Entry : not-synced lines
     walkFolder --> Filter : SkipUp / PruneDir / addNestedMount
+    Session --> secretLog : scan flags, finish persists
+    secretLog --> Store : reads the blob, writes secrets-mount-id.json
     Session ..> Op : commits, replays
     Session --> Result
     Store o-- Op : journal files
diff --git a/architecture/overview.md b/architecture/overview.md
index 35bc531..2b200d2 100644
--- a/architecture/overview.md
+++ b/architecture/overview.md
@@ -32,6 +32,8 @@ flowchart LR
 
     tpl["internal/templates<br/>go:embed'ed starting structures<br/>(docs, wiki, para, skills: skeleton + AGENTS.md)"]
 
+    sec["internal/secrets<br/>six credential rules, stdlib only<br/>shared by the share gate and the sync scan"]
+
     docs["web/docs — docs.beardrive.ai<br/>Astro/Starlight, deploys separately"]
     cloud["cloud/ (PRIVATE nested repo, gitignored)<br/>managed beardrive.ai: swaps AuthProvider,<br/>QuotaProvider, MetaStore seams"]
 
@@ -44,6 +46,8 @@ flowchart LR
     hooks -->|"bdrive sync --hook / --note, read-log<br/>gated: enrolled + not paused"| cli
     srv --> store
     srv --> meta
+    eng -->|"scan: warn, never hold"| sec
+    srv -->|"share mint: refuse"| sec
     cli -->|"init --template: seed locally"| tpl
     srv -->|"POST /api/projects template:<br/>seed as ops under the hub's device"| tpl
     fe -->|/api/config, /api/projects, viewer APIs| srv
diff --git a/architecture/webapp-server.md b/architecture/webapp-server.md
index ab7e009..b7924de 100644
--- a/architecture/webapp-server.md
+++ b/architecture/webapp-server.md
@@ -282,15 +282,18 @@ classDiagram
     note for ShareDB "A share is now re-checked at READ time, not only at mint time: shareCreatorStillBelongs refuses /s/&lt;token&gt; once its creator has left the project's org, so a link cannot outlive the access that justified it"
 
     class secretScan {
-        <<secrets.go>>
-        secretScanLimit = 1 MiB
+        <<internal/secrets>>
+        +ScanLimit = 1 MiB
         secretRules six anchored regexes
-        +scanSecrets(buf) []secretFinding
+        +Scan(buf) []Finding
+        +Label(rule) human words
     }
     class secretFinding {
+        <<secrets.Finding>>
         +Rule string
         +Line int
     }
+    note for secretScan "No longer a webapp file: internal/secrets is stdlib-only so internal/syncer can run the SAME rules on the path every file takes (the sync scan, warn-only — see cli-sync.md). The rule ids are a wire contract, keyed off by Browser.tsx's SECRET_LABELS and now by Label, whose test asserts it covers every rule"
     note for secretScan "Mint-time gate on handleShareCreate: the one place a member turns private bytes into a public URL is the one place the bytes are read first. It returns rule ids and LINE NUMBERS only — the matched text never reaches a response body, a log line, or a metric label, the same rule ReadLedger keeps for actor identity. Bypassed by confirm:true (bdrive share --force, the UI's Share anyway) and by Server.alreadyPublic, since a path that already has a live link is public already. Fails CLOSED: an unreadable blob is 503, not a silent pass"
 
     class sandboxInline {
diff --git a/cmd/bdrive/cmds.go b/cmd/bdrive/cmds.go
index 1bd04fa..cc96c70 100644
--- a/cmd/bdrive/cmds.go
+++ b/cmd/bdrive/cmds.go
@@ -2,6 +2,8 @@ package main
 
 import (
 	"fmt"
+	"maps"
+	"slices"
 	"strings"
 	"time"
 	"unicode"
@@ -11,6 +13,7 @@ import (
 	"github.com/runbear-io/beardrive/internal/config"
 	"github.com/runbear-io/beardrive/internal/daemon"
 	"github.com/runbear-io/beardrive/internal/journal"
+	"github.com/runbear-io/beardrive/internal/secrets"
 	"github.com/runbear-io/beardrive/internal/store"
 	"github.com/runbear-io/beardrive/internal/syncer"
 )
@@ -108,6 +111,7 @@ list in .bdrive/config.json is never pruned against either.`,
 					if h, ok := runHookSync(cmd, target, sessionID, hookLabel); ok {
 						link := hookLinkFor(folder, target, h.base)
 						link.paths = h.paths
+						link.secrets = h.secrets
 						links = append(links, link)
 					}
 				}
@@ -241,6 +245,11 @@ func statusCmd() *cobra.Command {
 					}
 					fmt.Printf("  files:    %d (%s)\n", len(cache), humanBytes(total))
 				}
+				// Read, never scanned: `status` runs no cycle, so what it
+				// reports is what the last cycle that read those bytes found.
+				if found, err := sess.Store.LoadSecrets(id); err == nil {
+					printSecrets(found)
+				}
 				st, err := sess.Store.LoadSync()
 				myOps, err2 := sess.Store.DeviceOps(dev.ID)
 				if err == nil && err2 == nil {
@@ -346,6 +355,33 @@ func logCmd() *cobra.Command {
 //
 // So: no C0 or DEL, one entry is one line, and each part is bounded — 50 rows
 // of log is also owned by one 40 KB entry that scrolls the rest away.
+// statusSecretsMax caps the block: a folder that trips the rules everywhere
+// would otherwise bury the rest of `status` under its own output.
+const statusSecretsMax = 20
+
+// printSecrets renders what the last cycle that read these files found. The
+// wording is the same contract the share gate has: each file was checked WHEN
+// IT CHANGED, which says nothing about a file that has not. Rule id and line
+// only — the matched bytes never leave internal/secrets.
+func printSecrets(found map[string][]secrets.Finding) {
+	if len(found) == 0 {
+		return
+	}
+	paths := slices.Sorted(maps.Keys(found))
+	fmt.Printf("  secrets: %d file(s) looked like they contain credentials when they last changed\n", len(paths))
+	for i, rel := range paths {
+		if i == statusSecretsMax {
+			fmt.Printf("             +%d more\n", len(paths)-i)
+			break
+		}
+		for _, f := range found[rel] {
+			// The path is a project member's string reaching a terminal,
+			// exactly like the rows above.
+			fmt.Printf("             %s:%d  %s\n", safeField(rel, 160), f.Line, secrets.Label(f.Rule))
+		}
+	}
+}
+
 func safeField(s string, max int) string {
 	s = strings.Map(func(r rune) rune {
 		switch {
diff --git a/cmd/bdrive/hooksync.go b/cmd/bdrive/hooksync.go
index 8832bf9..a720e5d 100644
--- a/cmd/bdrive/hooksync.go
+++ b/cmd/bdrive/hooksync.go
@@ -4,12 +4,15 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"maps"
 	"path/filepath"
+	"slices"
 	"strings"
 	"time"
 
 	"github.com/spf13/cobra"
 
+	"github.com/runbear-io/beardrive/internal/secrets"
 	"github.com/runbear-io/beardrive/internal/store"
 )
 
@@ -41,6 +44,11 @@ type hookLink struct {
 	base   string // https://hub/<project-id>[/<the run folder's subpath>]
 	sub    string // the run folder's mount-relative path, "" at or above the mount
 	paths  []store.InboundEvent
+	// secrets is what the last cycle that read these files found in them.
+	// Read from the store rather than the Result for the same reason paths
+	// is: the daemon usually scanned the agent's write seconds ago, so this
+	// cycle's own scan sees an unchanged file and finds nothing.
+	secrets map[string][]secrets.Finding
 }
 
 // hookChangedMax caps the changed-file list the turn pays for. Past it the
@@ -71,8 +79,9 @@ func eventSessionID(data []byte) string {
 // hookSync is one mount's contribution to the turn: where its files live on
 // the hub, and which of them moved since the last turn.
 type hookSync struct {
-	base  string
-	paths []store.InboundEvent
+	base    string
+	paths   []store.InboundEvent
+	secrets map[string][]secrets.Finding
 }
 
 // runHookSync syncs one mount and reports its hub base URL, if it has one,
@@ -107,12 +116,15 @@ func runHookSync(cmd *cobra.Command, target, sessionID, label string) (hookSync,
 	// nothing and the spool is where the record is. Errors are ignored — the
 	// links matter more than the list.
 	paths, _ := sess.Store.DrainInbound()
+	// Not drained: findings are state, not events. They stand until the file
+	// changes without them, so every turn sees the ones still true.
+	found, _ := sess.Store.LoadSecrets(sess.MountID)
 
 	server, projectID, err := splitHubRemote(proj.Remote)
 	if err != nil {
 		return hookSync{}, false // non-hub remote: nothing to link to
 	}
-	return hookSync{base: server + "/" + projectID, paths: paths}, true
+	return hookSync{base: server + "/" + projectID, paths: paths, secrets: found}, true
 }
 
 // hookLinkFor places one mount relative to the folder the hook ran in.
@@ -187,6 +199,9 @@ func emitHookContext(cmd *cobra.Command, links []hookLink) {
 	if changed := hookChanged(links); changed != "" {
 		context += " " + changed
 	}
+	if found := hookSecrets(links); found != "" {
+		context += " " + found
+	}
 
 	out := map[string]any{
 		"hookSpecificOutput": map[string]any{
@@ -254,3 +269,36 @@ func hookAgentPath(l hookLink, path string) (string, bool) {
 		return path, true
 	}
 }
+
+// hookSecrets tells the turn which synced files looked like they hold
+// credentials when they last changed. Advisory, exactly like hookChanged:
+// they have ALREADY synced, so there is nothing to block — the useful move is
+// telling the user, which is something an agent can do and a status line the
+// user never runs cannot. Rule labels and line numbers only; the matched
+// bytes never leave internal/secrets.
+func hookSecrets(links []hookLink) string {
+	var parts []string
+	over := 0
+	for _, l := range links {
+		for _, rel := range slices.Sorted(maps.Keys(l.secrets)) {
+			p, ok := hookAgentPath(l, rel)
+			if !ok {
+				continue
+			}
+			if len(parts) >= hookChangedMax {
+				over++
+				continue
+			}
+			f := l.secrets[rel][0]
+			parts = append(parts, fmt.Sprintf("`%s` (%s, line %d)", p, secrets.Label(f.Rule), f.Line))
+		}
+	}
+	if len(parts) == 0 {
+		return ""
+	}
+	s := "These synced files looked like they contain credentials when they last changed: " + strings.Join(parts, ", ")
+	if over > 0 {
+		s += fmt.Sprintf(", +%d more", over)
+	}
+	return s + ". They have already synced to the hub and to teammates, so this is not a blocker to work around — tell the user, and suggest rotating the credential and keeping it out of the folder."
+}
diff --git a/cmd/bdrive/hooksync_test.go b/cmd/bdrive/hooksync_test.go
index 8f6c768..6e945f5 100644
--- a/cmd/bdrive/hooksync_test.go
+++ b/cmd/bdrive/hooksync_test.go
@@ -10,6 +10,7 @@ import (
 	"testing"
 
 	"github.com/runbear-io/beardrive/internal/config"
+	"github.com/runbear-io/beardrive/internal/secrets"
 	"github.com/runbear-io/beardrive/internal/store"
 )
 
@@ -443,3 +444,83 @@ func TestSyncHookModeInboundSpoolUnreadable(t *testing.T) {
 		t.Fatalf("hook emitted invalid JSON: %v\n%s", err, got)
 	}
 }
+
+func seedSecrets(t *testing.T, proj config.Project, found map[string][]secrets.Finding) {
+	t.Helper()
+	vdir, err := config.VolumeDir(proj.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	st, err := store.Open(vdir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := st.SaveSecrets(proj.ID, found); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// The credential warning reaches the agent, whose own cycle found nothing:
+// the daemon scanned that write seconds ago, so — exactly like the inbound
+// spool — the record is what carries it. Advisory: the sentence says the file
+// has ALREADY synced, because it has.
+func TestSyncHookModeReportsSecrets(t *testing.T) {
+	t.Setenv("BDRIVE_HOME", t.TempDir())
+	root := t.TempDir()
+	root, _ = filepath.EvalSymlinks(root)
+	proj := mountAt(t, root, "wiki", "https://hub.example.com/p/p-12345678")
+	seedSecrets(t, proj, map[string][]secrets.Finding{
+		"deploy.md": {{Rule: "aws_access_key_id", Line: 12}},
+	})
+
+	got := runHook(t, filepath.Join(root, "wiki"))
+	for _, want := range []string{
+		"looked like they contain credentials when they last changed",
+		"`deploy.md` (an AWS access key, line 12)",
+		"tell the user",
+	} {
+		if !strings.Contains(got, want) {
+			t.Errorf("hook output missing %q:\n%s", want, got)
+		}
+	}
+	// Unlike the inbound spool, findings are state and are NOT drained: the
+	// file still holds the key on the next turn, so the next turn still says so.
+	if again := runHook(t, filepath.Join(root, "wiki")); !strings.Contains(again, "`deploy.md`") {
+		t.Errorf("the warning vanished after one turn:\n%s", again)
+	}
+}
+
+// Every path carries its own mount's prefix — a credential in one project must
+// never be reported as a path in another.
+func TestSyncHookModeSecretsMultipleMounts(t *testing.T) {
+	t.Setenv("BDRIVE_HOME", t.TempDir())
+	root := t.TempDir()
+	root, _ = filepath.EvalSymlinks(root)
+	a := mountAt(t, root, "projA", "https://hub.example.com/p/p-aaaaaaaa")
+	b := mountAt(t, root, "projB", "https://hub.example.com/p/p-bbbbbbbb")
+	seedSecrets(t, a, map[string][]secrets.Finding{"a.md": {{Rule: "private_key", Line: 1}}})
+	seedSecrets(t, b, map[string][]secrets.Finding{"b.md": {{Rule: "slack_token", Line: 2}}})
+
+	got := runHook(t, root)
+	for _, want := range []string{"`projA/a.md` (a private key, line 1)", "`projB/b.md` (a Slack token, line 2)"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("hook output missing %q:\n%s", want, got)
+		}
+	}
+}
+
+// The empty case is the common one, paid on every turn of every session: the
+// context must be byte-identical to what it was before this check existed.
+func TestSyncHookModeNoSecretsSaysNothing(t *testing.T) {
+	t.Setenv("BDRIVE_HOME", t.TempDir())
+	root := t.TempDir()
+	root, _ = filepath.EvalSymlinks(root)
+	mountAt(t, root, "wiki", "https://hub.example.com/p/p-12345678")
+
+	got := runHook(t, filepath.Join(root, "wiki"))
+	for _, unwanted := range []string{"credential", "secret"} {
+		if strings.Contains(strings.ToLower(got), unwanted) {
+			t.Errorf("a clean mount mentions %q on every turn:\n%s", unwanted, got)
+		}
+	}
+}
diff --git a/cmd/bdrive/migrate.go b/cmd/bdrive/migrate.go
index f8f60d9..912e0e7 100644
--- a/cmd/bdrive/migrate.go
+++ b/cmd/bdrive/migrate.go
@@ -274,9 +274,9 @@ func importStore(ctx context.Context, be remote.Backend, tr *tar.Reader, first *
 	// complete; importing it succeeded and the files were just gone on the
 	// destination. Import is the anti-lock-in door — it refuses loudly
 	// instead.
-	content := map[string]bool{}      // sha → present as blobs/ or manifests/
-	referenced := map[string]string{} // sha → a path that references it
-	chunks := map[string]bool{}       // chunk sha → present in the archive
+	content := map[string]bool{}       // sha → present as blobs/ or manifests/
+	referenced := map[string]string{}  // sha → a path that references it
+	chunks := map[string]bool{}        // chunk sha → present in the archive
 	manChunks := map[string][]string{} // manifest sha → chunk shas it names
 	hdr := first
 	for {
diff --git a/cmd/bdrive/share.go b/cmd/bdrive/share.go
index da33e84..7072cbe 100644
--- a/cmd/bdrive/share.go
+++ b/cmd/bdrive/share.go
@@ -14,6 +14,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/runbear-io/beardrive/internal/config"
+	"github.com/runbear-io/beardrive/internal/secrets"
 )
 
 // shareCmd mints public URLs for synced files: `bdrive share report.html`
@@ -143,7 +144,10 @@ func secretsFound(rel string, resp *http.Response) error {
 	var b strings.Builder
 	fmt.Fprintf(&b, "%s looks like it contains credentials (checked at the moment you shared it):\n", rel)
 	for _, f := range out.Findings {
-		fmt.Fprintf(&b, "  line %-4d %s\n", f.Line, f.Rule)
+		// Both: the web dialog has always said "an AWS access key" while the
+		// terminal said "aws_access_key_id", and the id is what someone greps
+		// for or quotes in a report.
+		fmt.Fprintf(&b, "  line %-4d %s (%s)\n", f.Line, secrets.Label(f.Rule), f.Rule)
 	}
 	b.WriteString("Nothing was shared. Re-run with --force if that is intentional.")
 	return fmt.Errorf("%s", b.String())
diff --git a/internal/secrets/secrets.go b/internal/secrets/secrets.go
new file mode 100644
index 0000000..22aaa84
--- /dev/null
+++ b/internal/secrets/secrets.go
@@ -0,0 +1,99 @@
+// Package secrets is the one credential-shaped-string rule set, shared by the
+// two places that look: the hub's share gate (internal/webapp/shares.go, which
+// refuses to mint) and the sync scan (internal/syncer, which only warns). It
+// imports the standard library and nothing else, so the syncer can use it
+// without depending on the server.
+//
+// Both callers say the same thing about time: the check ran when the bytes
+// were read — at the moment you shared it, or the moment the file last
+// changed. Neither one ever claims a file is clean.
+//
+// The matched text never leaves this package. Rule ids and line numbers only,
+// in a 409 body, in `bdrive status`, in an agent's context, in a log line.
+package secrets
+
+import (
+	"bytes"
+	"regexp"
+	"sort"
+)
+
+// ScanLimit is how much of a file the share gate reads. The boundary is
+// a decision, not an accident: a key past the first MiB mints silently, which
+// is asserted in shares_test.go so nobody "fixes" it by accident.
+const ScanLimit = 1 << 20
+
+// Finding is one credential-shaped string: which rule fired, and where.
+// Never the matched text — see Scan.
+type Finding struct {
+	Rule string `json:"rule"`
+	Line int    `json:"line"`
+}
+
+var secretRules = []struct {
+	id string
+	re *regexp.Regexp
+}{
+	{"aws_access_key_id", regexp.MustCompile(`AKIA[0-9A-Z]{16}`)},
+	// The bodies below are what keep the prefixes off prose: a bare `sk-` in a
+	// sentence is not a key. If one still fires on real docs, tighten the body
+	// rather than dropping the rule — `--force` and Share anyway are the
+	// escape hatch, which is why they ship in the same change.
+	{"openai_api_key", regexp.MustCompile(`sk-[A-Za-z0-9_-]{20,}`)},
+	{"github_pat", regexp.MustCompile(`ghp_[A-Za-z0-9]{36}`)},
+	{"slack_token", regexp.MustCompile(`xox[baprs]-[A-Za-z0-9-]{10,}`)},
+	{"private_key", regexp.MustCompile(`-----BEGIN [A-Z ]*PRIVATE KEY-----`)},
+	{"gitlab_pat", regexp.MustCompile(`glpat-[A-Za-z0-9_-]{20,}`)},
+}
+
+// labels are the rule ids in words. They existed only in the frontend
+// (SECRET_LABELS in Browser.tsx) while `bdrive share` printed the bare id, so
+// the same finding read as "an AWS access key" in the browser and
+// "aws_access_key_id" in a terminal. TestLabelCoversEveryRule is what stops a
+// seventh rule from shipping as a bare id again.
+var labels = map[string]string{
+	"aws_access_key_id": "an AWS access key",
+	"openai_api_key":    "an OpenAI API key",
+	"github_pat":        "a GitHub token",
+	"slack_token":       "a Slack token",
+	"private_key":       "a private key",
+	"gitlab_pat":        "a GitLab token",
+}
+
+// Label renders a rule id for a human. An id with no label renders as itself —
+// a bare id is ugly, but a rule that reports nothing is worse.
+func Label(rule string) string {
+	if l, ok := labels[rule]; ok {
+		return l
+	}
+	return rule
+}
+
+// Scan reports credential-shaped strings in buf, as rule ids and line
+// numbers ONLY. The matched text must never reach a response body, a log line,
+// or a metric label — the same argument reads.go:28-40 makes for actor
+// identity, and a 409 body is the easiest place in the codebase to leak it.
+//
+// Byte-oriented on purpose: a bufio.Scanner over a 1 MiB minified file with no
+// newline blows its 64 KiB token limit and returns nothing at all, which is a
+// check that silently passes everything.
+func Scan(buf []byte) []Finding {
+	seen := map[Finding]bool{}
+	var out []Finding
+	for _, rule := range secretRules {
+		for _, m := range rule.re.FindAllIndex(buf, -1) {
+			f := Finding{Rule: rule.id, Line: bytes.Count(buf[:m[0]], []byte("\n")) + 1}
+			if !seen[f] {
+				seen[f] = true
+				out = append(out, f)
+			}
+		}
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].Line != out[j].Line {
+			return out[i].Line < out[j].Line
+		}
+		return out[i].Rule < out[j].Rule
+	})
+	return out
+}
diff --git a/internal/secrets/secrets_test.go b/internal/secrets/secrets_test.go
new file mode 100644
index 0000000..d0d2ec6
--- /dev/null
+++ b/internal/secrets/secrets_test.go
@@ -0,0 +1,78 @@
+package secrets
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// Fabricated, structurally-valid-looking strings. None is a real credential.
+const (
+	fakeAWSKey    = "AKIAIOSFODNN7EXAMPLE"
+	fakeOpenAIKey = "sk-abcdefghijklmnopqrstuvwxyz0123456789"
+	fakeGitHubPAT = "ghp_" + "abcdefghijklmnopqrstuvwxyz0123456789ab"
+	fakeSlackTok  = "xoxb-1234567890-abcdefghij"
+	fakeGitLabPAT = "glpat-abcdefghij0123456789XY"
+	fakePrivKey   = "-----BEGIN RSA PRIVATE KEY-----"
+)
+
+func TestScanSecrets(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		buf  string
+		want []Finding
+	}{
+		{"clean", "# Notes\n\nnothing to see, sk- is just a prefix here\n", nil},
+		{"aws", "line1\nline2\nkey = " + fakeAWSKey + "\n", []Finding{{"aws_access_key_id", 3}}},
+		{"openai", "OPENAI=" + fakeOpenAIKey, []Finding{{"openai_api_key", 1}}},
+		{"github", "\n\n" + fakeGitHubPAT, []Finding{{"github_pat", 3}}},
+		{"slack", "token: " + fakeSlackTok, []Finding{{"slack_token", 1}}},
+		{"gitlab", "x\n" + fakeGitLabPAT, []Finding{{"gitlab_pat", 2}}},
+		{"private key", "a\nb\nc\n" + fakePrivKey + "\nMIIE...\n", []Finding{{"private_key", 4}}},
+		{
+			// One line, one rule, three keys: one finding, not three.
+			"multi key line deduped",
+			"a=" + fakeAWSKey + " b=AKIAZZZZZZZZZZZZZZZZ c=AKIAYYYYYYYYYYYYYYYY",
+			[]Finding{{"aws_access_key_id", 1}},
+		},
+		{
+			"two rules same line",
+			"env: " + fakeAWSKey + " " + fakeSlackTok,
+			[]Finding{{"aws_access_key_id", 1}, {"slack_token", 1}},
+		},
+		{
+			// A bufio.Scanner would blow its 64 KiB token limit here and report
+			// nothing at all — which is why Scan is byte-oriented.
+			"no newline in a big buffer",
+			strings.Repeat("x", 300_000) + fakeAWSKey,
+			[]Finding{{"aws_access_key_id", 1}},
+		},
+		{
+			"sorted by line then rule",
+			fakeSlackTok + "\n" + fakeAWSKey,
+			[]Finding{{"slack_token", 1}, {"aws_access_key_id", 2}},
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			got := Scan([]byte(tc.buf))
+			if !reflect.DeepEqual(got, tc.want) {
+				t.Fatalf("Scan = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+// A rule id reaches a human in three places (the share dialog, `bdrive share`,
+// `bdrive status`), and two of them go through Label. A new rule without a
+// label ships as `openai_api_key_v2` in a terminal, which is the failure this
+// catches at the only point that knows both lists.
+func TestLabelCoversEveryRule(t *testing.T) {
+	for _, r := range secretRules {
+		if Label(r.id) == r.id {
+			t.Errorf("rule %q has no human label", r.id)
+		}
+	}
+	if got := Label("not_a_rule"); got != "not_a_rule" {
+		t.Errorf("Label(unknown) = %q, want the id back", got)
+	}
+}
diff --git a/internal/store/secrets.go b/internal/store/secrets.go
new file mode 100644
index 0000000..bfadf53
--- /dev/null
+++ b/internal/store/secrets.go
@@ -0,0 +1,57 @@
+package store
+
+import (
+	"github.com/runbear-io/beardrive/internal/secrets"
+)
+
+// The secrets record is what a cycle's credential findings survive in. The scan
+// flags a file the moment it changes; the two surfaces that report it —
+// `bdrive status` and the agent hook — run minutes later, long after that file
+// stopped changing and the cheap size+mtime path stopped reading it. So the
+// record has to outlive the cycle that made it, for the same reason the inbound
+// spool does (see inbound.go).
+//
+// It is merged PER PATH, never replaced wholesale: nearly every cycle scans
+// zero changed files, so a whole-set rewrite would erase the warning three
+// seconds after it appeared. A finding stands until the file changes again
+// without it — which is what makes fixing the file the only thing needed to
+// clear the warning, no command and no flag.
+//
+// It is advisory telemetry about paths this device already journaled and
+// pushed. It must never be able to fail a cycle.
+
+// secretsPath names the per-mount findings file, validated exactly like
+// cachePath: the mount id comes from a folder's .bdrive/config.json, so a
+// separator in it would put this file wherever its author chose.
+func (s *Store) secretsPath(mountID string) (string, error) {
+	return s.mountStatePath("secrets-", mountID)
+}
+
+// LoadSecrets returns the findings recorded for each mount-relative path.
+func (s *Store) LoadSecrets(mountID string) (map[string][]secrets.Finding, error) {
+	p, err := s.secretsPath(mountID)
+	if err != nil {
+		return nil, err
+	}
+	out := map[string][]secrets.Finding{}
+	if err := readJSON(p, &out); err != nil {
+		return nil, err
+	}
+	// Same treatment as the cache's keys: plain JSON in $BDRIVE_HOME that
+	// anything running as the user can write, rendered into a terminal and
+	// joined against cache keys. An out-of-volume path is dropped, not shown.
+	for rel, f := range out {
+		if !cleanRel(rel) || len(f) == 0 {
+			delete(out, rel)
+		}
+	}
+	return out, nil
+}
+
+func (s *Store) SaveSecrets(mountID string, f map[string][]secrets.Finding) error {
+	p, err := s.secretsPath(mountID)
+	if err != nil {
+		return err
+	}
+	return WriteJSONAtomic(p, f)
+}
diff --git a/internal/store/secrets_test.go b/internal/store/secrets_test.go
new file mode 100644
index 0000000..6ccf306
--- /dev/null
+++ b/internal/store/secrets_test.go
@@ -0,0 +1,84 @@
+package store
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/runbear-io/beardrive/internal/secrets"
+)
+
+func TestSecretsRoundtripAndIsolation(t *testing.T) {
+	s, err := Open(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := map[string][]secrets.Finding{"deploy.md": {{Rule: "aws_access_key_id", Line: 12}}}
+	if err := s.SaveSecrets("m1", want); err != nil {
+		t.Fatal(err)
+	}
+	got, err := s.LoadSecrets("m1")
+	if err != nil || len(got["deploy.md"]) != 1 || got["deploy.md"][0].Line != 12 {
+		t.Fatalf("roundtrip = %+v, %v", got, err)
+	}
+	if other, err := s.LoadSecrets("m2"); err != nil || len(other) != 0 {
+		t.Fatalf("mounts must be isolated: %+v %v", other, err)
+	}
+	// A mount id with a separator would put the file wherever its author
+	// chose — .bdrive/config.json travels with the folder, so it is checked.
+	if _, err := s.LoadSecrets("../evil"); err == nil {
+		t.Fatal("LoadSecrets accepted a mount id with a separator")
+	}
+}
+
+// The record is plain JSON in $BDRIVE_HOME that anything running as the user
+// can write, and its keys are rendered into a terminal and matched against
+// cache keys. Same treatment as LoadCache's: an out-of-volume key is dropped
+// on the way in, not on the way out.
+func TestLoadSecretsDropsForeignKeys(t *testing.T) {
+	s, err := Open(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	p, err := s.secretsPath("m1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	const raw = `{
+	  "notes.md":        [{"rule":"private_key","line":1}],
+	  "../../secret.md": [{"rule":"private_key","line":1}],
+	  "/etc/shadow":     [{"rule":"private_key","line":1}],
+	  "empty.md":        []
+	}`
+	if err := os.WriteFile(p, []byte(raw), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	got, err := s.LoadSecrets("m1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 1 || len(got["notes.md"]) != 1 {
+		t.Fatalf("LoadSecrets = %+v, want only notes.md", got)
+	}
+
+	// A torn file starts the mount empty rather than wedging every later
+	// cycle: these findings are advisory, and the next scan rewrites them.
+	if err := os.WriteFile(p, []byte(`{"notes.md": [{"rule":`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := s.LoadSecrets("m1"); err == nil {
+		t.Fatal("a torn record must report its error to the caller that ignores it")
+	}
+
+	// And the file it wrote is 0600 — it lists a private project's paths.
+	if err := s.SaveSecrets("m1", map[string][]secrets.Finding{"notes.md": {{Rule: "private_key", Line: 1}}}); err != nil {
+		t.Fatal(err)
+	}
+	fi, err := os.Stat(filepath.Join(s.Dir(), "secrets-m1.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if fi.Mode().Perm() != 0o600 {
+		t.Fatalf("mode = %v, want 0600", fi.Mode().Perm())
+	}
+}
diff --git a/internal/store/store.go b/internal/store/store.go
index 22d8e3d..b22d069 100644
--- a/internal/store/store.go
+++ b/internal/store/store.go
@@ -179,16 +179,21 @@ type CachedFile struct {
 	MTimeNS int64  `json:"mtime_ns"`
 }
 
-// cachePath names the per-mount state file. The mount id comes from a folder's
-// .bdrive/config.json — a file that travels with the folder — so it is checked
-// here as well as where it is read: "state-"+mountID+".json" is joined onto the
-// volume dir, and a separator in it puts the cache (and everything keyed the
-// same way) wherever its author chose.
-func (s *Store) cachePath(mountID string) (string, error) {
+// mountStatePath names a per-mount state file. The mount id comes from a
+// folder's .bdrive/config.json — a file that travels with the folder — so it is
+// checked here as well as where it is read: prefix+mountID+".json" is joined
+// onto the volume dir, and a separator in it puts the cache (and everything
+// keyed the same way) wherever its author chose.
+func (s *Store) mountStatePath(prefix, mountID string) (string, error) {
 	if mountID == "" || mountID == "." || mountID == ".." || strings.ContainsAny(mountID, `/\`) {
 		return "", fmt.Errorf("invalid mount id %q", mountID)
 	}
-	return filepath.Join(s.dir, "state-"+mountID+".json"), nil
+	return filepath.Join(s.dir, prefix+mountID+".json"), nil
+}
+
+// cachePath names the per-mount materialization cache (state-<mount>.json).
+func (s *Store) cachePath(mountID string) (string, error) {
+	return s.mountStatePath("state-", mountID)
 }
 
 func (s *Store) LoadCache(mountID string) (map[string]CachedFile, error) {
diff --git a/internal/syncer/secrets.go b/internal/syncer/secrets.go
new file mode 100644
index 0000000..ebc2c17
--- /dev/null
+++ b/internal/syncer/secrets.go
@@ -0,0 +1,95 @@
+package syncer
+
+import (
+	"io"
+
+	"github.com/runbear-io/beardrive/internal/secrets"
+	"github.com/runbear-io/beardrive/internal/store"
+)
+
+// The credential check runs on the path every file takes — the sync scan —
+// and it only ever WARNS. The op is journaled and pushed exactly as it was
+// before this check existed; a hit adds a line to `bdrive status` and a
+// sentence to the agent hook's context, and nothing else. Holding the op back
+// would mean a false positive silently parks someone's changes, which costs
+// more trust than the check buys, and it would break the cycle's "degrade to
+// offline, never fail" posture. Warn keeps that; hold breaks it.
+//
+// It reads the BLOB the scan just wrote, not the working file again: those are
+// the exact bytes that were hashed and journaled, so a line number can never
+// describe content no op ever captured, and the read is the same page-cache
+// read the hash pass just did.
+//
+// Nothing here may fail a cycle. Every error path drops the finding.
+
+// secretsPerFile caps what one file contributes. A generated file full of
+// key-shaped strings would otherwise put thousands of lines into a status
+// report nobody can read, and the first few are what a person acts on.
+const secretsPerFile = 8
+
+// secretLog is one cycle's view of the mount's findings: loaded whole, merged
+// per path, written back only if the cycle actually touched it. Per-path merge
+// is the point — nearly every cycle scans zero changed files, and a whole-set
+// rewrite would erase the warning seconds after it appeared.
+type secretLog struct {
+	found map[string][]secrets.Finding
+	dirty bool
+}
+
+// scanBlob records what the blob just written for rel contains. Called only on
+// the branches that ran PutBlobFile, so an unchanged file is never re-read.
+func (l *secretLog) scanBlob(st *store.Store, rel, sum string) {
+	if l == nil {
+		return
+	}
+	f, err := st.OpenBlob(sum)
+	if err != nil {
+		return // unreadable: skipped like every other unreadable-file case
+	}
+	defer f.Close()
+	buf, err := io.ReadAll(io.LimitReader(f, secrets.ScanLimit))
+	if err != nil {
+		return
+	}
+	found := secrets.Scan(buf)
+	if len(found) > secretsPerFile {
+		found = found[:secretsPerFile]
+	}
+	l.set(rel, found)
+}
+
+// set records rel's current findings, dropping the entry when there are none —
+// which is how fixing the file clears the warning with no command and no flag.
+func (l *secretLog) set(rel string, found []secrets.Finding) {
+	if len(found) == 0 {
+		l.drop(rel)
+		return
+	}
+	if !sameFindings(l.found[rel], found) {
+		l.found[rel] = found
+		l.dirty = true
+	}
+}
+
+// drop forgets a path: its credential is gone, or the path is.
+func (l *secretLog) drop(rel string) {
+	if l == nil {
+		return
+	}
+	if _, ok := l.found[rel]; ok {
+		delete(l.found, rel)
+		l.dirty = true
+	}
+}
+
+func sameFindings(a, b []secrets.Finding) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}
diff --git a/internal/syncer/syncer.go b/internal/syncer/syncer.go
index bece628..c19cb70 100644
--- a/internal/syncer/syncer.go
+++ b/internal/syncer/syncer.go
@@ -40,6 +40,7 @@ import (
 	"github.com/runbear-io/beardrive/internal/config"
 	"github.com/runbear-io/beardrive/internal/journal"
 	"github.com/runbear-io/beardrive/internal/remote"
+	"github.com/runbear-io/beardrive/internal/secrets"
 	"github.com/runbear-io/beardrive/internal/store"
 )
 
@@ -267,6 +268,12 @@ func (s *Session) cycleLocked(ctx context.Context) (*Result, error) {
 	if err != nil {
 		return nil, fmt.Errorf("load sync state: %w", err)
 	}
+	// Advisory telemetry about files this cycle will journal and push anyway,
+	// so an unreadable record starts the cycle empty rather than failing it.
+	sec := &secretLog{found: map[string][]secrets.Finding{}}
+	if found, err := s.Store.LoadSecrets(s.mountID()); err == nil {
+		sec.found = found
+	}
 	myOps, err := s.Store.DeviceOps(s.Device.ID)
 	if err != nil {
 		return nil, fmt.Errorf("read own journal: %w", err)
@@ -309,7 +316,7 @@ func (s *Session) cycleLocked(ctx context.Context) (*Result, error) {
 	filter.AcceptRules(st.IgnoreAccepted)
 
 	// 1. Scan the working folder and journal any local changes.
-	localOps, err := s.scan(cache, &st, int64(len(myOps)), filter)
+	localOps, err := s.scan(cache, &st, int64(len(myOps)), filter, sec)
 	if err != nil {
 		return nil, fmt.Errorf("scan: %w", err)
 	}
@@ -366,7 +373,7 @@ func (s *Session) cycleLocked(ctx context.Context) (*Result, error) {
 			if cerr := commitLocal(); cerr != nil {
 				return nil, cerr
 			}
-			return res, s.finish(cache, st)
+			return res, s.finish(cache, st, sec)
 		case errors.Is(err, errBlobContent):
 			// Reported — it is the only signal a device ever gets that its hub
 			// is serving bytes that are not what they are addressed as — but
@@ -604,7 +611,7 @@ func (s *Session) cycleLocked(ctx context.Context) (*Result, error) {
 	// so a device the hub was refusing alternated between the two log lines
 	// forever and `bdrive status` reported healthy sync moments after the push
 	// it had just refused.
-	if err := s.finish(cache, st); err != nil {
+	if err := s.finish(cache, st, sec); err != nil {
 		return nil, err
 	}
 	return res, nil
@@ -613,10 +620,20 @@ func (s *Session) cycleLocked(ctx context.Context) (*Result, error) {
 // finish persists the two pieces of state a cycle mutates. Saving the cache
 // matters even on a cut-short cycle: the scan already journaled local edits,
 // and dropping the cache would make the next scan journal them all again.
-func (s *Session) finish(cache map[string]store.CachedFile, st store.SyncState) error {
+func (s *Session) finish(cache map[string]store.CachedFile, st store.SyncState, sec *secretLog) error {
 	if err := s.Store.SaveCache(s.mountID(), cache); err != nil {
 		return err
 	}
+	// Written only when the cycle changed it, so a quiet daemon tick every 3s
+	// still writes nothing — and an error is logged, never returned: this is
+	// advisory telemetry about ops that are already journaled and pushed, and
+	// giving it a veto over convergence is the one invariant this feature is
+	// close enough to break.
+	if sec != nil && sec.dirty {
+		if err := s.Store.SaveSecrets(s.mountID(), sec.found); err != nil {
+			log.Printf("beardrive: could not record credential findings: %v", err)
+		}
+	}
 	return s.Store.SaveSync(st)
 }
 
@@ -625,7 +642,7 @@ func (s *Session) finish(cache map[string]store.CachedFile, st store.SyncState)
 // are neither journaled nor deleted: a path that becomes ignored is dropped
 // from the cache without a delete op, so opting out locally never removes
 // the file from other devices.
-func (s *Session) scan(cache map[string]store.CachedFile, st *store.SyncState, seqBase int64, filter *Filter) ([]journal.Op, error) {
+func (s *Session) scan(cache map[string]store.CachedFile, st *store.SyncState, seqBase int64, filter *Filter, sec *secretLog) ([]journal.Op, error) {
 	seen := make(map[string]bool, len(cache))
 	var ops []journal.Op
 	note := s.Note
@@ -662,6 +679,11 @@ func (s *Session) scan(cache map[string]store.CachedFile, st *store.SyncState, s
 		if err != nil {
 			return nil // file vanished or unreadable; next cycle
 		}
+		// Below the cheap size+mtime return above, so only a file that actually
+		// changed is ever read for credentials — and covering both branches
+		// below means a file touched back to previously-flagged content still
+		// reports. Warn only: nothing here stops the op.
+		sec.scanBlob(s.Store, rel, sum)
 		if ok && c.Blob == sum {
 			// content unchanged, just touched
 			c.Size, c.MTimeNS, c.Mode = n, mt, mode
@@ -688,6 +710,10 @@ func (s *Session) scan(cache map[string]store.CachedFile, st *store.SyncState, s
 		// cache is a JSON file in $BDRIVE_HOME, not something the walk wrote.
 		// Same rule the peer-op side applies, so this device never signs and
 		// pushes a path it would refuse from anyone else.
+		// Every arm below stops tracking the path, so every arm forgets its
+		// findings too: a warning about a file this mount no longer syncs is
+		// one nothing can clear.
+		sec.drop(rel)
 		if unsafeRel(rel) || neverSync(rel) {
 			delete(cache, rel)
 			continue
diff --git a/internal/syncer/syncer_test.go b/internal/syncer/syncer_test.go
index 90a986a..b44e10c 100644
--- a/internal/syncer/syncer_test.go
+++ b/internal/syncer/syncer_test.go
@@ -10,6 +10,7 @@ import (
 	"maps"
 	"os"
 	"path/filepath"
+	"reflect"
 	"strings"
 	"sync"
 	"sync/atomic"
@@ -19,6 +20,7 @@ import (
 	"github.com/runbear-io/beardrive/internal/config"
 	"github.com/runbear-io/beardrive/internal/journal"
 	"github.com/runbear-io/beardrive/internal/remote"
+	"github.com/runbear-io/beardrive/internal/secrets"
 	"github.com/runbear-io/beardrive/internal/store"
 )
 
@@ -1003,3 +1005,125 @@ func TestInboundSpoolOutlivesItsCycle(t *testing.T) {
 		t.Fatalf("inbound = %+v, want notes/readme.md from the earlier cycle", evs)
 	}
 }
+
+// A fabricated, structurally-valid-looking AWS key. Not a real credential.
+const testAWSKey = "AKIAIOSFODNN7EXAMPLE"
+
+// TestSecretWarnsButStillSyncs is the whole posture of the credential check in
+// one test: the file with the key in it converges exactly as any other file
+// does — journaled, pushed, materialized on the peer — and the ONLY difference
+// is a record on the writing device naming the path, the rule and the line.
+// A regression that makes this hold the op fails here, not in production.
+func TestSecretWarnsButStillSyncs(t *testing.T) {
+	be := sharedRemote(t)
+	a := newDevice(t, "deva", be)
+	b := newDevice(t, "devb", be)
+
+	write(t, a.Folder, "deploy.md", "# Deploy\n\nrun it\n\nexport AWS_ACCESS_KEY_ID="+testAWSKey+"\n")
+	res := cycle(t, a)
+	if res.LocalOps != 1 {
+		t.Fatalf("LocalOps = %d, want the op journaled anyway (warn, never hold)", res.LocalOps)
+	}
+	if !res.Pushed {
+		t.Fatalf("Pushed = false, want the blob pushed anyway")
+	}
+	cycle(t, b)
+	if got := read(t, b.Folder, "deploy.md"); !strings.Contains(got, testAWSKey) {
+		t.Fatalf("peer content = %q, want the file to have synced normally", got)
+	}
+
+	found, err := a.Store.LoadSecrets(a.mountID())
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []secrets.Finding{{Rule: "aws_access_key_id", Line: 5}}
+	if !reflect.DeepEqual(found["deploy.md"], want) {
+		t.Fatalf("findings = %+v, want %+v for deploy.md", found, want)
+	}
+
+	// The record names the rule and the line and never the matched bytes —
+	// the same contract the share-time 409 has always had.
+	raw, err := os.ReadFile(filepath.Join(a.Store.Dir(), "secrets-"+a.mountID()+".json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(raw), testAWSKey) {
+		t.Fatalf("the persisted record echoes the key: %s", raw)
+	}
+
+	// The peer that only RECEIVED the file records nothing: v1 warns the
+	// device that wrote the credential, and materialize is not a scan.
+	if found, _ := b.Store.LoadSecrets(b.mountID()); len(found) != 0 {
+		t.Fatalf("peer findings = %+v, want none (the writing device only)", found)
+	}
+}
+
+// TestSecretClearsWhenFixed is the reason the record is merged per path rather
+// than rewritten whole. Nearly every cycle scans zero changed files, so a
+// whole-set rewrite erases the warning seconds after it appears — here the
+// quiet cycle must leave it standing, and only editing the key out clears it.
+func TestSecretClearsWhenFixed(t *testing.T) {
+	a := newDevice(t, "deva", sharedRemote(t))
+
+	write(t, a.Folder, "deploy.md", "key = "+testAWSKey+"\n")
+	cycle(t, a)
+
+	// A quiet cycle: nothing changed, so nothing was scanned.
+	cycle(t, a)
+	if found, _ := a.Store.LoadSecrets(a.mountID()); len(found["deploy.md"]) == 0 {
+		t.Fatalf("the warning vanished on a quiet cycle: %+v", found)
+	}
+
+	// Fixing the file is the whole remedy: no command, no flag.
+	write(t, a.Folder, "deploy.md", "key = read it from the environment\n")
+	cycle(t, a)
+	found, err := a.Store.LoadSecrets(a.mountID())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(found) != 0 {
+		t.Fatalf("findings = %+v, want empty once the key is gone", found)
+	}
+
+	// And a deleted file takes its warning with it.
+	write(t, a.Folder, "deploy.md", "key = "+testAWSKey+"\n")
+	cycle(t, a)
+	if err := os.Remove(filepath.Join(a.Folder, "deploy.md")); err != nil {
+		t.Fatal(err)
+	}
+	cycle(t, a)
+	if found, _ := a.Store.LoadSecrets(a.mountID()); len(found) != 0 {
+		t.Fatalf("findings = %+v, want empty once the file is gone", found)
+	}
+}
+
+// The check must ride the branch that already reads the file, never add a pass
+// of its own: an unchanged file is not re-read, so the daemon's 3-second tick
+// costs nothing on a quiet folder. Clearing the record by hand and cycling is
+// the direct test — a scan that re-read unchanged files would put it back.
+func TestSecretScanSkipsUnchangedFiles(t *testing.T) {
+	a := newDevice(t, "deva", sharedRemote(t))
+
+	write(t, a.Folder, "deploy.md", "key = "+testAWSKey+"\n")
+	cycle(t, a)
+	if found, _ := a.Store.LoadSecrets(a.mountID()); len(found) != 1 {
+		t.Fatalf("findings = %+v, want deploy.md flagged", found)
+	}
+	if err := a.Store.SaveSecrets(a.mountID(), map[string][]secrets.Finding{}); err != nil {
+		t.Fatal(err)
+	}
+
+	cycle(t, a) // nothing changed on disk
+	if found, _ := a.Store.LoadSecrets(a.mountID()); len(found) != 0 {
+		t.Fatalf("findings = %+v — an unchanged file was read again", found)
+	}
+	// Touching it back into the changed branch does report it again.
+	future := time.Now().Add(2 * time.Second)
+	if err := os.Chtimes(filepath.Join(a.Folder, "deploy.md"), future, future); err != nil {
+		t.Fatal(err)
+	}
+	cycle(t, a)
+	if found, _ := a.Store.LoadSecrets(a.mountID()); len(found) != 1 {
+		t.Fatalf("findings = %+v, want the touched file flagged again", found)
+	}
+}
diff --git a/internal/webapp/cli_e2e_test.go b/internal/webapp/cli_e2e_test.go
index 00392a5..ba3f049 100644
--- a/internal/webapp/cli_e2e_test.go
+++ b/internal/webapp/cli_e2e_test.go
@@ -862,6 +862,75 @@ func TestCLITemplateRefusals(t *testing.T) {
 	}
 }
 
+// The same six rules, on the path every file takes. `bdrive status` names a
+// synced file that looked like it held a credential when it last changed —
+// and the file synced anyway, which is the posture: warn, never block.
+func TestCLISecretsWarnOnSync(t *testing.T) {
+	e := newCLIEnv(t)
+	run := e.run
+
+	work := t.TempDir()
+	// Fabricated, AWS-shaped. Not a credential.
+	const plantedKey = "AKIAIOSFODNN7EXAMPLE"
+	if err := os.WriteFile(filepath.Join(work, "clean.md"), []byte("# Clean\n\nnothing here\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if out, err := run(work, "init", "--name", "secret-warn", "--yes"); err != nil {
+		t.Fatalf("init: %v\n%s", err, out)
+	}
+	defer run(work, "stop", work)
+
+	// Nothing planted yet: the block is absent entirely, not empty.
+	out, err := run(work, "status", work)
+	if err != nil {
+		t.Fatalf("status: %v\n%s", err, out)
+	}
+	if strings.Contains(out, "secrets:") {
+		t.Fatalf("status names credentials with none found:\n%s", out)
+	}
+
+	if err := os.WriteFile(filepath.Join(work, "deploy.md"), []byte(
+		"# Deploy\n\nexport AWS_ACCESS_KEY_ID="+plantedKey+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if out, err := run(work, "sync"); err != nil {
+		t.Fatalf("sync: %v\n%s", err, out)
+	}
+	out, err = run(work, "status", work)
+	if err != nil {
+		t.Fatalf("status: %v\n%s", err, out)
+	}
+	for _, want := range []string{"secrets:", "deploy.md:3", "an AWS access key", "when they last changed"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("status missing %q:\n%s", want, out)
+		}
+	}
+	if strings.Contains(out, plantedKey) {
+		t.Fatalf("status echoed the key back:\n%s", out)
+	}
+
+	// It synced anyway — warn, never hold. The hub has the file.
+	if out, err := run(work, "share", "deploy.md", "--force"); err != nil || !strings.Contains(out, "/s/") {
+		t.Fatalf("the flagged file did not reach the hub: %v\n%s", err, out)
+	}
+
+	// Fixing the file is the whole remedy: no command, no flag.
+	if err := os.WriteFile(filepath.Join(work, "deploy.md"), []byte(
+		"# Deploy\n\nread AWS_ACCESS_KEY_ID from the environment\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if out, err := run(work, "sync"); err != nil {
+		t.Fatalf("sync: %v\n%s", err, out)
+	}
+	out, err = run(work, "status", work)
+	if err != nil {
+		t.Fatalf("status: %v\n%s", err, out)
+	}
+	if strings.Contains(out, "secrets:") {
+		t.Fatalf("the warning outlived the credential:\n%s", out)
+	}
+}
+
 // `bdrive share` refuses a file that looks like it holds credentials, and
 // --force is the way past it. This is the flow BEA-111 exists for: the CLI
 // used to print the URL and nothing else.
diff --git a/internal/webapp/secrets.go b/internal/webapp/secrets.go
deleted file mode 100644
index 2c137d4..0000000
--- a/internal/webapp/secrets.go
+++ /dev/null
@@ -1,74 +0,0 @@
-package webapp
-
-import (
-	"bytes"
-	"regexp"
-	"sort"
-)
-
-// Minting a share link is the one place on the hub where a member turns private
-// bytes into a public URL, so it is the one place worth reading the bytes
-// first. The check is deliberately narrow: six anchored rules over the first
-// 1 MiB, at mint time only.
-//
-// It says nothing about the file tomorrow. A link serves the file's LATEST
-// content forever (see the package comment in shares.go), so every string a
-// user sees says the file was checked *at the moment you shared it* — never
-// that the file is clean.
-
-// secretScanLimit is how much of a file the share gate reads. The boundary is
-// a decision, not an accident: a key past the first MiB mints silently, which
-// is asserted in shares_test.go so nobody "fixes" it by accident.
-const secretScanLimit = 1 << 20
-
-// secretFinding is one credential-shaped string: which rule fired, and where.
-// Never the matched text — see scanSecrets.
-type secretFinding struct {
-	Rule string `json:"rule"`
-	Line int    `json:"line"`
-}
-
-var secretRules = []struct {
-	id string
-	re *regexp.Regexp
-}{
-	{"aws_access_key_id", regexp.MustCompile(`AKIA[0-9A-Z]{16}`)},
-	// The bodies below are what keep the prefixes off prose: a bare `sk-` in a
-	// sentence is not a key. If one still fires on real docs, tighten the body
-	// rather than dropping the rule — `--force` and Share anyway are the
-	// escape hatch, which is why they ship in the same change.
-	{"openai_api_key", regexp.MustCompile(`sk-[A-Za-z0-9_-]{20,}`)},
-	{"github_pat", regexp.MustCompile(`ghp_[A-Za-z0-9]{36}`)},
-	{"slack_token", regexp.MustCompile(`xox[baprs]-[A-Za-z0-9-]{10,}`)},
-	{"private_key", regexp.MustCompile(`-----BEGIN [A-Z ]*PRIVATE KEY-----`)},
-	{"gitlab_pat", regexp.MustCompile(`glpat-[A-Za-z0-9_-]{20,}`)},
-}
-
-// scanSecrets reports credential-shaped strings in buf, as rule ids and line
-// numbers ONLY. The matched text must never reach a response body, a log line,
-// or a metric label — the same argument reads.go:28-40 makes for actor
-// identity, and a 409 body is the easiest place in the codebase to leak it.
-//
-// Byte-oriented on purpose: a bufio.Scanner over a 1 MiB minified file with no
-// newline blows its 64 KiB token limit and returns nothing at all, which is a
-// check that silently passes everything.
-func scanSecrets(buf []byte) []secretFinding {
-	seen := map[secretFinding]bool{}
-	var out []secretFinding
-	for _, rule := range secretRules {
-		for _, m := range rule.re.FindAllIndex(buf, -1) {
-			f := secretFinding{Rule: rule.id, Line: bytes.Count(buf[:m[0]], []byte("\n")) + 1}
-			if !seen[f] {
-				seen[f] = true
-				out = append(out, f)
-			}
-		}
-	}
-	sort.Slice(out, func(i, j int) bool {
-		if out[i].Line != out[j].Line {
-			return out[i].Line < out[j].Line
-		}
-		return out[i].Rule < out[j].Rule
-	})
-	return out
-}
diff --git a/internal/webapp/secrets_test.go b/internal/webapp/secrets_test.go
deleted file mode 100644
index 8ea4ed9..0000000
--- a/internal/webapp/secrets_test.go
+++ /dev/null
@@ -1,63 +0,0 @@
-package webapp
-
-import (
-	"reflect"
-	"strings"
-	"testing"
-)
-
-// Fabricated, structurally-valid-looking strings. None is a real credential.
-const (
-	fakeAWSKey    = "AKIAIOSFODNN7EXAMPLE"
-	fakeOpenAIKey = "sk-abcdefghijklmnopqrstuvwxyz0123456789"
-	fakeGitHubPAT = "ghp_" + "abcdefghijklmnopqrstuvwxyz0123456789ab"
-	fakeSlackTok  = "xoxb-1234567890-abcdefghij"
-	fakeGitLabPAT = "glpat-abcdefghij0123456789XY"
-	fakePrivKey   = "-----BEGIN RSA PRIVATE KEY-----"
-)
-
-func TestScanSecrets(t *testing.T) {
-	for _, tc := range []struct {
-		name string
-		buf  string
-		want []secretFinding
-	}{
-		{"clean", "# Notes\n\nnothing to see, sk- is just a prefix here\n", nil},
-		{"aws", "line1\nline2\nkey = " + fakeAWSKey + "\n", []secretFinding{{"aws_access_key_id", 3}}},
-		{"openai", "OPENAI=" + fakeOpenAIKey, []secretFinding{{"openai_api_key", 1}}},
-		{"github", "\n\n" + fakeGitHubPAT, []secretFinding{{"github_pat", 3}}},
-		{"slack", "token: " + fakeSlackTok, []secretFinding{{"slack_token", 1}}},
-		{"gitlab", "x\n" + fakeGitLabPAT, []secretFinding{{"gitlab_pat", 2}}},
-		{"private key", "a\nb\nc\n" + fakePrivKey + "\nMIIE...\n", []secretFinding{{"private_key", 4}}},
-		{
-			// One line, one rule, three keys: one finding, not three.
-			"multi key line deduped",
-			"a=" + fakeAWSKey + " b=AKIAZZZZZZZZZZZZZZZZ c=AKIAYYYYYYYYYYYYYYYY",
-			[]secretFinding{{"aws_access_key_id", 1}},
-		},
-		{
-			"two rules same line",
-			"env: " + fakeAWSKey + " " + fakeSlackTok,
-			[]secretFinding{{"aws_access_key_id", 1}, {"slack_token", 1}},
-		},
-		{
-			// A bufio.Scanner would blow its 64 KiB token limit here and report
-			// nothing at all — which is why scanSecrets is byte-oriented.
-			"no newline in a big buffer",
-			strings.Repeat("x", 300_000) + fakeAWSKey,
-			[]secretFinding{{"aws_access_key_id", 1}},
-		},
-		{
-			"sorted by line then rule",
-			fakeSlackTok + "\n" + fakeAWSKey,
-			[]secretFinding{{"slack_token", 1}, {"aws_access_key_id", 2}},
-		},
-	} {
-		t.Run(tc.name, func(t *testing.T) {
-			got := scanSecrets([]byte(tc.buf))
-			if !reflect.DeepEqual(got, tc.want) {
-				t.Fatalf("scanSecrets = %v, want %v", got, tc.want)
-			}
-		})
-	}
-}
diff --git a/internal/webapp/shares.go b/internal/webapp/shares.go
index 3094158..1b97cb9 100644
--- a/internal/webapp/shares.go
+++ b/internal/webapp/shares.go
@@ -12,6 +12,8 @@ import (
 	"strings"
 	"sync"
 	"time"
+
+	"github.com/runbear-io/beardrive/internal/secrets"
 )
 
 // Share links make one file publicly readable at /s/<unguessable-token> —
@@ -289,13 +291,13 @@ func (s *Server) handleShareCreate(v *volume, w http.ResponseWriter, r *http.Req
 		// 1 MiB and close: source.Open streams from the object store, so this
 		// aborts the rest of the transfer rather than pulling a 500 MB file
 		// down to look at its first megabyte. Don't "fix" it into a ReadAll.
-		buf, err := io.ReadAll(io.LimitReader(rc, secretScanLimit))
+		buf, err := io.ReadAll(io.LimitReader(rc, secrets.ScanLimit))
 		rc.Close()
 		if err != nil {
 			storageErr(w, http.StatusServiceUnavailable, "could not read the file to check it for credentials", err)
 			return
 		}
-		if findings := scanSecrets(buf); len(findings) > 0 {
+		if findings := secrets.Scan(buf); len(findings) > 0 {
 			writeJSONStatus(w, http.StatusConflict, map[string]any{
 				"error":    "this file looks like it contains credentials",
 				"findings": findings,
diff --git a/internal/webapp/shares_test.go b/internal/webapp/shares_test.go
index b9cb56a..11fa776 100644
--- a/internal/webapp/shares_test.go
+++ b/internal/webapp/shares_test.go
@@ -15,6 +15,8 @@ import (
 	"strings"
 	"testing"
 	"time"
+
+	"github.com/runbear-io/beardrive/internal/secrets"
 )
 
 func httptestNewRequestBody(method, url string, data []byte) *http.Request {
@@ -729,11 +731,11 @@ func postShare(t *testing.T, srv *Server, h http.Handler, project string, body a
 	return doHTTP(h, req)
 }
 
-func decodeFindings(t *testing.T, rec *httptest.ResponseRecorder) []secretFinding {
+func decodeFindings(t *testing.T, rec *httptest.ResponseRecorder) []secrets.Finding {
 	t.Helper()
 	var out struct {
-		Error    string          `json:"error"`
-		Findings []secretFinding `json:"findings"`
+		Error    string            `json:"error"`
+		Findings []secrets.Finding `json:"findings"`
 	}
 	if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
 		t.Fatalf("decode 409 body %q: %v", rec.Body, err)
@@ -755,7 +757,7 @@ func TestShareSecretScan(t *testing.T) {
 	if rec.Code != http.StatusConflict {
 		t.Fatalf("share of a file holding a key: %d %s, want 409", rec.Code, rec.Body)
 	}
-	if got := decodeFindings(t, rec); !reflect.DeepEqual(got, []secretFinding{{"aws_access_key_id", 5}}) {
+	if got := decodeFindings(t, rec); !reflect.DeepEqual(got, []secrets.Finding{{Rule: "aws_access_key_id", Line: 5}}) {
 		t.Fatalf("findings = %v, want aws_access_key_id on line 5", got)
 	}
 	if n := len(srv.Shares.List(p.ID)); n != 0 {
@@ -795,7 +797,7 @@ func TestShareSecretScan(t *testing.T) {
 }
 
 // TestShareSecretNeverEchoed is the one rule that cannot bend: the matched
-// bytes never leave scanSecrets — not in the body, not in the log.
+// bytes never leave secrets.Scan — not in the body, not in the log.
 func TestShareSecretNeverEchoed(t *testing.T) {
 	srv, p, _, f, h := shareHub(t)
 	f.put("dev1", "creds.md", "key = "+planted+"\n")
diff --git a/web/docs/src/content/docs/reference/cli.md b/web/docs/src/content/docs/reference/cli.md
index 7784505..a939f7d 100644
--- a/web/docs/src/content/docs/reference/cli.md
+++ b/web/docs/src/content/docs/reference/cli.md
@@ -24,7 +24,7 @@ One binary, `bdrive` — the CLI, the sync daemon, and the web server.
 | `bdrive sync [folder]` | Run one sync cycle now. Refuses folders this device never `init`ed and folders paused by `bdrive stop`. `--note <text>` stamps session context onto changes; `--note-ttl` (default 30m) bounds it. `--prune` also removes from the hub what `.bdriveignore` now excludes (files stay on disk everywhere). `--hook <label>` is agent-hook plumbing: it also reports the files teammates changed since the agent's last turn |
 | `bdrive hooks [install\|uninstall]` | Register turn-boundary sync hooks in each detected agent platform's user config — once per machine, covering every folder. Run automatically by `bdrive init`; idempotent; `--agent` overrides detection. `uninstall` removes only BearDrive's own hook entries |
 | `bdrive read-log [folder]` | Hook plumbing: queue agent file reads for the hub's read heatmap. Registered by `bdrive hooks install` |
-| `bdrive status [folder]` | Projects, daemon state, pending changes |
+| `bdrive status [folder]` | Projects, daemon state, pending changes, and any synced files that looked like they held credentials when they last changed |
 | `bdrive log [folder] [-p path] [-n N]` | Change history: account, device, time, file — newest first by the time shown, which is when the file was written (ops recorded before this was tracked, and deletes, show their sync time instead) |
 | `bdrive restore <file> [version]` | Put an earlier version of a file back, as a new change. No version restores the previous one; `--list` shows the versions with their short hashes |
 | `bdrive export [folder]` | Export the whole project — all devices' history and content — to a portable `.tar.gz` (`-o` names the file) |
@@ -199,9 +199,10 @@ version wins and the path comes back. Run `--prune` again once they have synced.
 
 ### `bdrive status` — and the two degraded access states
 
-Alongside `pending`, `status` prints an `access:` line whenever the hub is
-refusing this device. Neither is the same as being offline, and neither ever
-touches your files:
+Alongside `pending`, `status` prints a `secrets:` block naming any synced file
+that looked like it held a credential when it last changed, and an `access:`
+line whenever the hub is refusing this device. Neither access state is the same
+as being offline, and neither ever touches your files:
 
 ```
   pending:  3 local change(s) not yet pushed
@@ -224,6 +225,29 @@ identity was never bound to your account, which is fixed by updating `bdrive`
 and running `bdrive login` on that machine, not in Project settings. Checking
 your permissions there will show `write` and tell you nothing.
 
+### The credential warning
+
+The six rules `bdrive share` checks at mint time also run on **every file as it
+syncs** — the path every file takes, rather than the rare one:
+
+```
+  secrets: 1 file(s) looked like they contain credentials when they last changed
+             deploy.md:12  an AWS access key
+```
+
+It **only ever warns**. The change is journaled and pushed exactly as it would
+be otherwise; the finding appears here and in an agent's context at the start
+of its next turn. Nothing is held, blocked, or un-pushed — a false positive
+costs one line of text, never a stalled file.
+
+Fixing the file is the whole remedy: the next cycle reads it again and the line
+goes away, with no command and no flag. Three limits worth knowing: a file is
+checked **when it changes** (so this never says a file is clean), only its
+first 1 MiB is read, and the check runs on the device that made the change — a
+file synced from elsewhere is not flagged here until it next changes here.
+Rule names and line numbers only; the matched text is never printed, logged, or
+stored.
+
 `bdrive sync` shows the same two as `remote: read-only (pull only)` /
 `remote: no access — sync paused` with the reason on the line below, and the
 daemon logs each once on transition rather than on every tick — including the
diff --git a/web/docs/src/content/docs/reference/project-files.md b/web/docs/src/content/docs/reference/project-files.md
index 90bf5a5..28e1e42 100644
--- a/web/docs/src/content/docs/reference/project-files.md
+++ b/web/docs/src/content/docs/reference/project-files.md
@@ -123,7 +123,9 @@ Nothing is keyed by folder path, which is why moves and renames are free.
 ├─ blobs/      content-addressed file content (sha256)
 ├─ journal/    one append-only op log per device
 ├─ state.json  what's materialized
-└─ sync.json   lamport clock + push cursor
+├─ sync.json   lamport clock + push cursor
+└─ secrets-<mount-id>.json  files that looked like they held credentials when
+                            they last changed (what `bdrive status` reports)
 ```
 
 Also here for a running project: `daemon.pid` and `daemon.log`.