Deployed 8e33ef2 with MkDocs version: 1.6.1

cli-reference.html

@@ -620,6 +620,17 @@
     <nav class="md-nav" aria-label="studyctl">
       <ul class="md-nav__list">
 
+          <li class="md-nav__item">
+  <a href="#health-updates" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Health &amp; Updates
+      
+    </span>
+  </a>
+  
+</li>
+        
           <li class="md-nav__item">
   <a href="#confidence-levels" class="md-nav__link">
     <span class="md-ellipsis">
@@ -982,6 +993,17 @@
     <nav class="md-nav" aria-label="studyctl">
       <ul class="md-nav__list">
 
+          <li class="md-nav__item">
+  <a href="#health-updates" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Health &amp; Updates
+      
+    </span>
+  </a>
+  
+</li>
+        
           <li class="md-nav__item">
   <a href="#confidence-levels" class="md-nav__link">
     <span class="md-ellipsis">
@@ -1113,6 +1135,46 @@ <h2 id="studyctl">studyctl<a class="headerlink" href="#studyctl" title="Permanen
 studyctl<span class="w"> </span>tui<span class="w">                             </span><span class="c1"># Launch interactive TUI dashboard</span>
 studyctl<span class="w"> </span>docs<span class="w"> </span><span class="nb">read</span><span class="w"> </span>PAGE<span class="w">                  </span><span class="c1"># Read a page aloud via study-speak</span>
 </code></pre></div>
+<h3 id="health-updates">Health &amp; Updates<a class="headerlink" href="#health-updates" title="Permanent link">&para;</a></h3>
+<p>Check your installation and keep it current:</p>
+<div class="highlight"><pre><span></span><code>studyctl<span class="w"> </span>doctor<span class="w">                          </span><span class="c1"># Full health check (Rich table)</span>
+studyctl<span class="w"> </span>doctor<span class="w"> </span>--json<span class="w">                   </span><span class="c1"># JSON output (for AI agents and CI)</span>
+studyctl<span class="w"> </span>doctor<span class="w"> </span>--quiet<span class="w">                  </span><span class="c1"># One-line summary</span>
+studyctl<span class="w"> </span>doctor<span class="w"> </span>--category<span class="w"> </span>core<span class="w">          </span><span class="c1"># Check specific category only</span>
+studyctl<span class="w"> </span>update<span class="w">                          </span><span class="c1"># Check for available updates (no changes)</span>
+studyctl<span class="w"> </span>update<span class="w"> </span>--json<span class="w">                   </span><span class="c1"># Machine-readable update info</span>
+studyctl<span class="w"> </span>upgrade<span class="w">                         </span><span class="c1"># Apply all available updates</span>
+studyctl<span class="w"> </span>upgrade<span class="w"> </span>--dry-run<span class="w">               </span><span class="c1"># Preview what would change</span>
+studyctl<span class="w"> </span>upgrade<span class="w"> </span>--component<span class="w"> </span>packages<span class="w">    </span><span class="c1"># Upgrade only packages</span>
+studyctl<span class="w"> </span>upgrade<span class="w"> </span>--component<span class="w"> </span>database<span class="w">    </span><span class="c1"># Run DB migrations only</span>
+studyctl<span class="w"> </span>upgrade<span class="w"> </span>--component<span class="w"> </span>agents<span class="w">      </span><span class="c1"># Update agent definitions only</span>
+studyctl<span class="w"> </span>upgrade<span class="w"> </span>--force<span class="w">                 </span><span class="c1"># Upgrade even if already current</span>
+</code></pre></div>
+<p><strong>Exit codes for <code>studyctl doctor</code>:</strong></p>
+<table>
+<thead>
+<tr>
+<th>Code</th>
+<th>Meaning</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>0</code></td>
+<td>All checks pass — installation is healthy</td>
+</tr>
+<tr>
+<td><code>1</code></td>
+<td>Warnings or failures that can be fixed — run <code>studyctl upgrade</code></td>
+</tr>
+<tr>
+<td><code>2</code></td>
+<td>Core failure — a fundamental component is broken (e.g. wrong Python version)</td>
+</tr>
+</tbody>
+</table>
+<p><strong>Check categories:</strong> <code>core</code> (Python, packages, config), <code>database</code> (review DB, sessions DB), <code>config</code> (Obsidian vault, review dirs, pandoc), <code>deps</code> (optional packages), <code>agents</code> (AI tool definitions), <code>updates</code> (PyPI versions).</p>
+<p><strong>AI-guided setup:</strong> The install-mentor agent at <code>agents/shared/install-mentor.md</code> uses <code>studyctl doctor --json</code> to walk users through setup conversationally. It works with any AI coding tool (Claude Code, Kiro, Gemini CLI, OpenCode, Amp).</p>
 <h3 id="confidence-levels">Confidence Levels<a class="headerlink" href="#confidence-levels" title="Permanent link">&para;</a></h3>
 <p>Used with <code>studyctl progress</code>:</p>
 <table>

search/search_index.js

@@ -799,6 +799,34 @@
       </ul>
     </nav>
 
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#verify-installation" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Verify Installation
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Verify Installation">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#ai-guided-setup" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        AI-Guided Setup
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
 
         <li class="md-nav__item">
@@ -813,6 +841,17 @@
     <nav class="md-nav" aria-label="Troubleshooting">
       <ul class="md-nav__list">
 
+          <li class="md-nav__item">
+  <a href="#first-step-run-studyctl-doctor" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        First step: run studyctl doctor
+      
+    </span>
+  </a>
+  
+</li>
+        
           <li class="md-nav__item">
   <a href="#studyctl-command-not-found" class="md-nav__link">
     <span class="md-ellipsis">
@@ -1805,6 +1844,34 @@
       </ul>
     </nav>
 
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#verify-installation" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Verify Installation
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Verify Installation">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#ai-guided-setup" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        AI-Guided Setup
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
 
         <li class="md-nav__item">
@@ -1819,6 +1886,17 @@
     <nav class="md-nav" aria-label="Troubleshooting">
       <ul class="md-nav__list">
 
+          <li class="md-nav__item">
+  <a href="#first-step-run-studyctl-doctor" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        First step: run studyctl doctor
+      
+    </span>
+  </a>
+  
+</li>
+        
           <li class="md-nav__item">
   <a href="#studyctl-command-not-found" class="md-nav__link">
     <span class="md-ellipsis">
@@ -2418,7 +2496,36 @@ <h3 id="obsidian-vault-path">Obsidian vault path<a class="headerlink" href="#obs
 <div class="highlight"><pre><span></span><code><span class="nt">obsidian_base</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/mnt/c/Users/YourName/Obsidian</span>
 </code></pre></div>
 <p>For better performance, consider keeping the vault inside WSL2's native filesystem (<code>~/Obsidian/</code>) and syncing with Obsidian Sync or Git.</p>
+<h2 id="verify-installation">Verify Installation<a class="headerlink" href="#verify-installation" title="Permanent link">&para;</a></h2>
+<p>After installing and configuring, run the health check to make sure everything is working:</p>
+<div class="highlight"><pre><span></span><code>studyctl<span class="w"> </span>doctor
+</code></pre></div>
+<p>This checks Python version, installed packages, config validity, databases, optional dependencies, and AI agent definitions. You'll see a colour-coded table:</p>
+<ul>
+<li>Green tick = healthy</li>
+<li>Yellow ! = warning (often auto-fixable)</li>
+<li>Red cross = failure (needs attention)</li>
+<li>Blue i = informational (optional)</li>
+</ul>
+<p>If issues are found:</p>
+<div class="highlight"><pre><span></span><code>studyctl<span class="w"> </span>upgrade<span class="w">              </span><span class="c1"># Fix auto-fixable issues (packages, DB, agents)</span>
+studyctl<span class="w"> </span>upgrade<span class="w"> </span>--dry-run<span class="w">    </span><span class="c1"># Preview changes first</span>
+</code></pre></div>
+<p>For machine-readable output (used by CI pipelines and AI agents):</p>
+<div class="highlight"><pre><span></span><code>studyctl<span class="w"> </span>doctor<span class="w"> </span>--json
+</code></pre></div>
+<h3 id="ai-guided-setup">AI-Guided Setup<a class="headerlink" href="#ai-guided-setup" title="Permanent link">&para;</a></h3>
+<p>If you're using an AI coding assistant, the <strong>install-mentor agent</strong> can guide you through the entire setup process conversationally. It automatically detects your environment, installs packages, runs <code>studyctl doctor</code>, and fixes issues.</p>
+<p>The prompt lives at <code>agents/shared/install-mentor.md</code> and works with any AI tool that can run shell commands — Claude Code, Kiro CLI, Gemini CLI, OpenCode, or Amp.</p>
+<p>To use it in Claude Code:
+<div class="highlight"><pre><span></span><code>Read agents/shared/install-mentor.md and follow its instructions to set up studyctl
+</code></pre></div></p>
 <h2 id="troubleshooting">Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permanent link">&para;</a></h2>
+<h3 id="first-step-run-studyctl-doctor">First step: run <code>studyctl doctor</code><a class="headerlink" href="#first-step-run-studyctl-doctor" title="Permanent link">&para;</a></h3>
+<p>Before investigating specific issues, always start with the health check:</p>
+<div class="highlight"><pre><span></span><code>studyctl<span class="w"> </span>doctor
+</code></pre></div>
+<p>This will identify most common problems and tell you how to fix them. If auto-fixable issues are found, run <code>studyctl upgrade</code> to resolve them.</p>
 <h3 id="studyctl-command-not-found"><code>studyctl: command not found</code><a class="headerlink" href="#studyctl-command-not-found" title="Permanent link">&para;</a></h3>
 <p>The package isn't on your PATH. Either:
 - Run via <code>uv run studyctl</code> instead