feat(docs): suggest enabling docs once per repo at SessionStart

[efenocchi]

What & why

Onboarding for the docs feature, so a user actually learns Hivemind can keep per-repo docs in sync — in two complementary places.

1. Install-time hint (visible to the user)

hivemind install runs on a TTY, so it is the honest place to TELL the user. docsInstallLines() prints a block in the install summary (right before "Done. Restart") covering BOTH directions:

• Enable in a repo: hivemind docs sync
• Turn off later: hivemind docs auto off
• Status: hivemind docs list

So the user is never stuck after opting in.

2. SessionStart note (visible to the model)

Inverse gate of the existing docsWikiContextNote: for a logged-in session in an indexed repo with docs off and no prior suggestion, inject a one-time, descriptive note so the agent can surface hivemind docs sync if the user asks. Deduped per (org, project) via ~/.deeplake/docs-suggested.json; wording is non-imperative to stay clear of prompt-injection heuristics.

Note: the SessionStart note is model-facing (not shown in the terminal) — the install-time hint is the user-visible channel. Kept both; happy to drop the hook note if we want a single mechanism.

Verification

• tsc clean; unit tests for both helpers; full suite green.
• Real hivemind install (sandbox HOME) prints the docs block in the series with enable/disable/status.
• Real claude -p loading the plugin quotes the SessionStart note back verbatim; second run same registry → suppressed (dedup).

Files

• src/docs/install-hint.ts (new) + wired into src/cli/index.ts (runInstallAll)
• src/docs/docs-suggest.ts (new) + wired into src/hooks/session-start.ts
• tests/shared/docs-install-hint.test.ts, tests/shared/docs-suggest.test.ts (new)

Session Context

Session transcript

Summary by CodeRabbit

• New Features

  • Added a Session Start reminder that nudges users to configure documentation context when a local project graph is detected and docs aren’t enabled (shown once per project).
  • Added documentation onboarding hint lines to the install terminal output.

• Bug Fixes

  • Made the suggestion history handling robust: missing, corrupt, or unreadable history no longer disrupts session start.
  • Ensured the reminder is deduplicated per project and safely updated without partial writes.

• Tests

  • Added coverage for reminder gating, persistence behavior, and install-hint output.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a persistent, deduplicated docs setup suggestion selected during SessionStart, with fail-closed registry handling, atomic writes, install-time onboarding hints, and tests covering gating, persistence, idempotency, corrupt files, and hint output.

Changes

Docs onboarding

Layer / File(s)	Summary
Suggestion registry persistence src/docs/docs-suggest.ts, tests/shared/docs-suggest.test.ts	Defines registry data shapes, resilient reads, (orgId, project) lookup, idempotent updates, atomic-ish persistence, and persistence tests.
Suggestion selection src/docs/docs-suggest.ts, tests/shared/docs-suggest.test.ts	Returns the docs setup note only when a local graph exists, docs are not auto-enabled, and no prior suggestion is recorded; tests cover gating and fail-closed behavior.
Session-start integration src/hooks/session-start.ts	Evaluates the suggestion for authenticated sessions, records emitted suggestions, and appends the note to additionalContext.
Install-time docs guidance src/docs/install-hint.ts, src/cli/index.ts, tests/shared/docs-install-hint.test.ts	Adds enable, disable, and status guidance to the install completion output and validates the generated lines.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: kaghni

Sequence Diagram(s)

sequenceDiagram
  participant SessionStart
  participant docsSuggestNote
  participant isAutoEnabled
  participant wasSuggested
  participant markSuggested
  SessionStart->>docsSuggestNote: evaluate docs suggestion inputs
  docsSuggestNote->>isAutoEnabled: check docs auto-enabled state
  docsSuggestNote->>wasSuggested: check org/project registry entry
  docsSuggestNote-->>SessionStart: return note or empty string
  SessionStart->>markSuggested: persist emitted suggestion
  SessionStart-->>SessionStart: append suggestNote to additionalContext

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	Description covers the changes and verification, but it does not follow the required template and omits the Version Bump/test-plan checklist fields.	Add the template sections (Summary, Version Bump, Test plan) and explicitly state whether package.json was bumped or no release is needed.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	Title clearly matches the main change: one-time docs suggestion at SessionStart.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/docs-onboarding-suggest

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Coverage Report

Scope: files changed in this PR. Enforced threshold: 90% per metric (per file via vitest.config.ts).

Status	Category	Percentage	Covered / Total
🟢	Lines	91.14% (🎯 90%)	319 / 350
🟢	Statements	91.28% (🎯 90%)	377 / 413
🟢	Functions	100.00% (🎯 90%)	36 / 36
🔴	Branches	88.16% (🎯 90%)	283 / 321

File Coverage — 4 files changed

File	Stmts	Branches	Functions	Lines
src/cli/index.ts	🔴 87.9%	🔴 85.1%	🟢 100.0%	🔴 87.0%
src/docs/docs-suggest.ts	🟢 97.0%	🟢 96.0%	🟢 100.0%	🟢 100.0%
src/docs/install-hint.ts	🟢 100.0%	🟢 100.0%	🟢 100.0%	🟢 100.0%
src/hooks/session-start.ts	🟢 99.0%	🟢 92.1%	🟢 100.0%	🟢 98.9%

_{Generated for commit 9d824cd.}