Skip to content

docs: search steering feature page; 1Password encrypted-only posture - #77176

Open
andrexibiza wants to merge 1 commit into
NousResearch:mainfrom
andrexibiza:docs/secrets-posture-and-search-steering
Open

docs: search steering feature page; 1Password encrypted-only posture#77176
andrexibiza wants to merge 1 commit into
NousResearch:mainfrom
andrexibiza:docs/secrets-posture-and-search-steering

Conversation

@andrexibiza

@andrexibiza andrexibiza commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

What's in this PR

Two public-docs changes, both QA'd by independent critique agents before shipping.

1. New feature page: search steering

website/docs/user-guide/features/search-steering.md (registered in sidebars.ts) presents zero-match search steering + multi-path recovery as a product feature:

  • A bare zero-match search is a dead turn for an agent. Hermes now runs cheap count-only probes and attaches actionable hints — case-insensitive matches (casing may be wrong), literal matches (regex metacharacters need escaping), hidden/gitignored matches.
  • Multi-path recovery: space- or comma-separated paths are searched and merged; missing paths are skipped with a note; a single missing path keeps the "Path not found" behavior.
  • Engine support: ripgrep primary, grep fallback — identical hints on both.

2. 1Password: the security posture is the feature

website/docs/user-guide/secrets/onepassword.md now leads with the posture section (mirroring the Bitwarden doc) and documents the hardened reality:

  • Encrypted-only disk cache — resolved values persist only in op_cache.enc.json under AES-GCM; a plaintext cache is never written. Legacy plaintext op_cache.json is migrated and removed on first read.
  • cache_ttl_seconds: 0 disables cache reuse entirely — every fetch resolves fresh, nothing read from or written to disk (this corrects an earlier draft that wrongly said values were "reused in process memory"; is_fresh(0) → False, so both cache layers are off).
  • Child-process hygieneOP_SERVICE_ACCOUNT_TOKEN, OP_CONNECT_TOKEN, and OP_SESSION_* are stripped from every spawned child; the op child receives them explicitly through its own allowlisted env.

Verification

  • Independent re-QA (separate critique agent): SAFE TO SHIP — the "memory-only / reused for the TTL" false claim is confirmed absent (grep 0 matches), all three corrected ttl=0 statements trace to CachedFetch.is_fresh() semantics, every other behavioral claim traces to the code (_is_hermes_internal_secret strip contract, _op_child_env allowlist), the sibling doc is accurate, sidebar wiring resolves.
  • npm run build (Docusaurus production build): exit 0, 0 errors — the search-steering doc id resolves.
  • Claims were traced to executable code before shipping (the QA discipline rule): is_fresh(0) → False, probe hint strings, and the strip contract were all checked against the actual source.

Related #77168 #77157

Two public-docs changes:

1. New feature page (user-guide/features/search-steering.md, registered in
   sidebars.ts): zero-match search steering + multi-path recovery presented
   as a product feature — case-insensitive/literal/hidden-file probe hints
   on zero-match content searches, space/comma-separated path recovery,
   ripgrep primary with grep fallback.

2. onepassword.md: the 1Password integration is documented with the
   security posture as the feature — encrypted-only AES-GCM disk cache
   (op_cache.enc.json, legacy plaintext migrated+removed), cache_ttl_seconds:
   0 disables cache reuse entirely (fresh fetch, nothing on disk),
   OP_SERVICE_ACCOUNT_TOKEN/OP_CONNECT_TOKEN/OP_SESSION_* stripped from all
   spawned children (op child receives them via its explicit allowlist).

Both docs QA'd by independent critique agents before commit; behavioral
claims traced to the actual code (is_fresh(0) -> False, _is_hermes_internal_secret
strip contract, probe hint strings); npm run build passes.
@alt-glitch alt-glitch added type/docs Documentation improvements P3 Low — cosmetic, nice to have area/auth Authentication, OAuth, credential pools tool/file File tools (read, write, patch, search) labels Aug 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/auth Authentication, OAuth, credential pools P3 Low — cosmetic, nice to have tool/file File tools (read, write, patch, search) type/docs Documentation improvements

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants