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

[efenocchi]

What & why

Onboarding so a user actually learns Hivemind can keep per-repo docs in sync — and, crucially, how to turn it on and off.

The onboarding lives in the visible hivemind install output. An earlier iteration injected a SessionStart note, but that reaches only the model (invisible in the terminal), so it never told a human. That note was removed; the install hint is the single, user-facing mechanism.

Behaviour

On the first hivemind install (sentinel ~/.deeplake/.docs-hint-shown), the install summary prints, right before "Done. Restart":

Docs (optional): keep per-file and per-subsystem documentation in sync with your code on every commit.
  Enable in a repo:  hivemind docs sync    (one-time consent; opt into per-commit auto-sync when asked)
  Turn it off later: hivemind docs auto off
  Check status:      hivemind docs list

Re-running install stays quiet. Sentinel write is best-effort — a failure just reshows the hint, never breaks install.

Verification

• tsc clean; unit tests for the block + the first-install sentinel.
• Real hivemind install (sandbox HOME): run 1 prints the docs block; run 2 (same HOME) suppresses it; sentinel written.

Files

• src/docs/install-hint.ts (new) — docsInstallLines() + first-install sentinel helpers
• src/cli/index.ts — gated print in runInstallAll
• tests/shared/docs-install-hint.test.ts (new)
• Removed: src/docs/docs-suggest.ts + test, and its session-start.ts wiring

Session Context

Session transcript

Summary by CodeRabbit

• New Features
  • Added an installation-time onboarding message for the documentation feature.
  • The message includes guidance for enabling or disabling documentation support and provides a command for checking its status.
  • The onboarding message appears only after the first installation, keeping future installation output concise.
• Reliability
  • Recording whether the message was shown is handled safely and will not interrupt or block installation if it fails.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a one-time docs onboarding hint to the install completion flow, backed by a local sentinel file and best-effort persistence. The hint content, sentinel behavior, and failure handling are covered by tests.

Changes

Docs onboarding

Layer / File(s)	Summary
Install-time docs guidance src/docs/install-hint.ts, tests/shared/docs-install-hint.test.ts	Adds enable, disable, and status guidance; tracks display state with a local sentinel; validates content, state transitions, and non-throwing writes.
Install completion integration src/cli/index.ts	Prints the docs hint once during runInstallAll before the existing completion message and records it as shown.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Installer
  participant DocsHint
  participant LocalSentinel
  Installer->>DocsHint: check whether hint was shown
  DocsHint->>LocalSentinel: inspect sentinel file
  LocalSentinel-->>DocsHint: return existence state
  DocsHint-->>Installer: return shown status
  Installer->>DocsHint: request onboarding lines
  DocsHint-->>Installer: return hint lines
  Installer->>DocsHint: mark hint as shown
  DocsHint->>LocalSentinel: write timestamp sentinel

Loading

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title mentions a SessionStart suggestion, but the PR actually moves the docs hint into visible install output and removes SessionStart wiring.	Rename it to reflect the install-time docs onboarding change, e.g. 'feat(docs): show a one-time docs hint during install'.
Description check	⚠️ Warning	The description is detailed, but it does not follow the repository template and is missing the required Summary, Version Bump, and Test plan sections.	Add the template sections: Summary, Version Bump, and a Test plan checklist with local tests, new tests, and whether a release bump is needed.

✅ Passed checks (3 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.

✨ 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.}