Skip to content

Commit 5961996

Browse files
committed
docs(troubleshooting): lead with the diagnostic step, not a settings tour
The plugin now links here from a button in its Troubleshooting settings tab (s2b-dev/smart-second-brain#458), so a reader arriving on this page is already looking at that tab. "Start here" then opened by telling them where to find two controls sitting on screen behind the page they had just opened, and the closing section repeated the directions a second time. Reframe the opening around the one thing worth doing before reading further — turn on logging and reproduce — and mention the other controls as things that exist rather than as a place to navigate to. The closing section now assumes that logging is already on and asks for its output in the issue, instead of restating where the buttons live. Also fix the intro's count: it promised "four buckets" and then ran six symptom sections, since MCP and Mobile are not covered by the four named causes. The page is organised by symptom, not by cause, so say that instead of counting.
1 parent f513ac5 commit 5961996

1 file changed

Lines changed: 20 additions & 16 deletions

File tree

‎src/content/docs/help/troubleshooting.md‎

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -5,21 +5,28 @@ sidebar:
55
order: 1
66
---
77

8-
Most problems fall into one of four buckets: the provider can't be reached, the
9-
index isn't what you think it is, the agent lacks a tool, or a note is being
10-
filtered for privacy. This page walks each one.
8+
Most problems come down to one of a few causes: the provider can't be reached,
9+
the index isn't what you think it is, the agent lacks a tool, or a note is being
10+
filtered for privacy. The sections below are organised by what you're seeing
11+
rather than by cause, so start from the symptom.
1112

12-
## Start here
13+
## Before you start: turn on logging
1314

14-
**Settings → Smart Second Brain → Troubleshooting** has two things worth
15-
knowing about:
15+
Almost every diagnosis below reads better with verbose output. Turn on
16+
**Developer Console logging** in the plugin's Troubleshooting settings,
17+
reproduce the problem, and open the developer console (`Ctrl`/`Cmd` + `Shift` +
18+
`I`) to read the `[S2B]` lines.
1619

17-
- **Developer Console logging.** Turn this on to get verbose `[S2B]` output in
18-
the developer console (`Ctrl`/`Cmd` + `Shift` + `I`). Almost every diagnosis
19-
below starts here.
20-
- **Clean up plugin data.** Deletes plugin settings and generated index data.
20+
Two other things live on that same settings tab, worth knowing before you need
21+
them:
22+
23+
- **Clean up plugin data** deletes plugin settings and generated index data.
2124
Your secrets, skill files, and chat files inside the vault are **kept**. This
2225
is the "start clean without losing my work" button.
26+
- **View existing issues** and **Open new issue** go straight to the tracker,
27+
for when nothing on this page fits.
28+
29+
Then jump to whichever section matches your symptom.
2330

2431
## The agent won't respond
2532

@@ -190,11 +197,8 @@ phone. Consider indexing on desktop against a synced vault.
190197

191198
## Nothing above helped
192199

193-
Turn on **Developer Console logging**, reproduce the problem, and check the
194-
console for `[S2B]` lines.
195-
196-
Then search the
200+
Search the
197201
[existing issues](https://github.com/s2b-dev/smart-second-brain/issues) before
198202
opening a new one. If you do open one, include what you tried, any error
199-
messages, and the steps to reproduce. Both buttons are in the Troubleshooting
200-
settings tab.
203+
messages, the steps to reproduce, and the `[S2B]` console output from the
204+
logging you turned on at the top of this page.

0 commit comments

Comments
 (0)