Deployed 4ad808e with MkDocs version: 1.6.1

cli-reference.html

@@ -1144,6 +1144,8 @@ <h3 id="study-sessions">Study Sessions<a class="headerlink" href="#study-session
 studyctl<span class="w"> </span>study<span class="w"> </span><span class="s2">&quot;Spark Internals&quot;</span><span class="w"> </span>--mode<span class="w"> </span>co-study<span class="w">       </span><span class="c1"># User-driven co-study</span>
 studyctl<span class="w"> </span>study<span class="w"> </span><span class="s2">&quot;topic&quot;</span><span class="w"> </span>--timer<span class="w"> </span>pomodoro<span class="w">                </span><span class="c1"># Override default timer</span>
 studyctl<span class="w"> </span>study<span class="w"> </span><span class="s2">&quot;topic&quot;</span><span class="w"> </span>--agent<span class="w"> </span>claude<span class="w"> </span>--web<span class="w">            </span><span class="c1"># Explicit agent + web dashboard</span>
+studyctl<span class="w"> </span>study<span class="w"> </span><span class="s2">&quot;topic&quot;</span><span class="w"> </span>--lan<span class="w">                           </span><span class="c1"># Bind to 0.0.0.0, password-protected (implies --web)</span>
+studyctl<span class="w"> </span>study<span class="w"> </span><span class="s2">&quot;topic&quot;</span><span class="w"> </span>--lan<span class="w"> </span>--password<span class="w"> </span>SECRET<span class="w">         </span><span class="c1"># Explicit password for LAN auth</span>
 studyctl<span class="w"> </span>study<span class="w"> </span><span class="s2">&quot;topic&quot;</span><span class="w"> </span>--agent<span class="w"> </span>ollama<span class="w">                  </span><span class="c1"># Local LLM via Ollama + LiteLLM</span>
 studyctl<span class="w"> </span>study<span class="w"> </span><span class="s2">&quot;topic&quot;</span><span class="w"> </span>--agent<span class="w"> </span>lmstudio<span class="w">                </span><span class="c1"># Local LLM via LM Studio</span>
 studyctl<span class="w"> </span>study<span class="w"> </span>--resume<span class="w">                                </span><span class="c1"># Resume conversation (-r)</span>
@@ -1156,7 +1158,10 @@ <h3 id="study-sessions">Study Sessions<a class="headerlink" href="#study-session
 - Persistent session directory at <code>~/.config/studyctl/sessions/{name}/</code> — preserves AI conversation history (<code>.claude/</code>, <code>.kiro/</code>, etc.)
 - Sidebar shows timer, activity feed, counters (keyboard: <code>p</code> pause, <code>r</code> reset, <code>Q</code> end session)
 - IPC files for dashboard viewports
-- Optional web dashboard at <code>/session</code> via <code>--web</code></p>
+- Optional web dashboard at <code>/session</code> via <code>--web</code>
+- <code>--web</code> auto-opens a browser to the dashboard on startup
+- <code>--lan</code> binds the web server and ttyd to <code>0.0.0.0</code> with HTTP Basic Auth, prints dashboard URL and password (implies <code>--web</code>). Password is auto-generated if not set via <code>--password</code> or <code>lan_password</code> in config
+- <code>--password SECRET</code> sets the LAN authentication password (used with <code>--lan</code>)</p>
 <p><strong>Session lifecycle:</strong>
 - <strong>Start:</strong> <code>studyctl study "topic"</code> — creates tmux session, agent, sidebar
 - <strong>Exit:</strong> quit Claude normally (<code>/exit</code>, Ctrl+C) — auto-cleans up tmux, IPC files, switches back to previous session. Session directory preserved.
@@ -1293,9 +1298,16 @@ <h3 id="web-pwa">Web PWA<a class="headerlink" href="#web-pwa" title="Permanent l
 </tbody>
 </table>
 <p><strong>Features:</strong> Source/chapter filter, card count limiter (10/20/50/100/All), due cards badge, session history, 90-day study heatmap, Pomodoro timer (25min/5min), OpenDyslexic font toggle, dark/light theme, PWA installable.</p>
+<p><strong>Live session dashboard</strong> (<code>/session</code>): Real-time SSE activity feed, energy-adaptive timer, topic counters, and a <strong>terminal panel</strong> — an embedded ttyd iframe showing the tmux session live via same-origin proxy (<code>/terminal/</code>). The panel is draggable (stacked or side-by-side), has a layout toggle and panel-swap buttons, and can be popped out to a separate window (pop-out auto-closes when returning inline). ttyd is optional (<code>brew install ttyd</code>) but required for the terminal panel.</p>
 <p><strong>Voice:</strong> Uses Web Speech API (browser built-in). Two modes:
 - <strong>Read once</strong> — speaker icon on card or <code>T</code> key
 - <strong>Auto-voice</strong> — header toggle or <code>V</code> key (reads everything automatically)</p>
+<p><strong>Web + terminal config</strong> (<code>~/.config/studyctl/config.yaml</code>):</p>
+<div class="highlight"><pre><span></span><code><span class="nt">web_port</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">8567</span><span class="w">       </span><span class="c1"># web dashboard port (default 8567)</span>
+<span class="nt">ttyd_port</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">7681</span><span class="w">      </span><span class="c1"># ttyd web terminal port (default 7681)</span>
+<span class="nt">browser</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="w">          </span><span class="c1"># auto-open browser: chrome, safari, firefox, brave, or empty for system default</span>
+<span class="nt">lan_password</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="w">     </span><span class="c1"># persistent password for --lan mode (auto-generated if empty)</span>
+</code></pre></div>
 <hr />
 <h2 id="agent-session-tools">agent-session-tools<a class="headerlink" href="#agent-session-tools" title="Permanent link">&para;</a></h2>
 <p>AI session export, search, and cross-machine sync.</p>

roadmap.html

@@ -2039,11 +2039,19 @@ <h2 id="next-v220-remote-study-local-llms">Next: v2.2.0 — Remote Study + Local
 <p>Study from any device (iPad, laptop, phone) via ttyd + web dashboard, with optional local LLMs.</p>
 <h3 id="ttyd-integration-embedded-web-pane">ttyd Integration + Embedded Web Pane<a class="headerlink" href="#ttyd-integration-embedded-web-pane" title="Permanent link">&para;</a></h3>
 <ul>
-<li>[ ] <code>studyctl study --lan</code> starts ttyd alongside tmux session (port 7681)</li>
-<li>[ ] Embed ttyd as iframe in existing web dashboard</li>
-<li>[ ] "Open Study Agent Session" button — iframe split (default) + pop-out new window</li>
-<li>[ ] Doctor check for ttyd binary</li>
-<li>[ ] Config support for ttyd port</li>
+<li>[x] <code>studyctl study --lan</code> starts ttyd alongside tmux session (port 7681)</li>
+<li>[x] Embed ttyd as iframe in existing web dashboard</li>
+<li>[x] "Open Study Agent Session" button — iframe split (default) + pop-out new window</li>
+<li>[x] Doctor check for ttyd binary</li>
+<li>[x] Config support for ttyd port</li>
+<li>[x] Draggable split-pane layout (stacked/side-by-side)</li>
+<li>[x] Browser auto-open with configurable browser</li>
+<li>[x] Claude Code trust bypass (<code>hasTrustDialogAccepted</code>)</li>
+<li>[x] <code>window-size largest</code> tmux option for multi-client compatibility</li>
+<li>[x] Same-origin reverse proxy — ttyd proxied through FastAPI at <code>/terminal/</code> (HTTP + WebSocket)</li>
+<li>[x] Pop-out/return persistence — iframe stays in DOM (visibility CSS), pop-out auto-closes on return</li>
+<li>[x] LAN password protection — HTTP Basic Auth middleware, auto-generated or explicit <code>--password</code></li>
+<li>[x] <code>lan_password</code> config option for persistent password</li>
 </ul>
 <h3 id="local-llms-via-ollama-lm-studio">Local LLMs via Ollama / LM Studio<a class="headerlink" href="#local-llms-via-ollama-lm-studio" title="Permanent link">&para;</a></h3>
 <ul>

search/search_index.js

@@ -495,6 +495,17 @@
     </span>
   </a>
 
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#remote-study-ipad-on-the-bus" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Remote Study (iPad on the Bus)
+      
+    </span>
+  </a>
+  
 </li>
 
           <li class="md-nav__item">
@@ -556,6 +567,17 @@
     </span>
   </a>
 
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#web-terminal-settings" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Web Terminal Settings
+      
+    </span>
+  </a>
+  
 </li>
 
           <li class="md-nav__item">
@@ -1535,6 +1557,17 @@
     </span>
   </a>
 
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#remote-study-ipad-on-the-bus" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Remote Study (iPad on the Bus)
+      
+    </span>
+  </a>
+  
 </li>
 
           <li class="md-nav__item">
@@ -1596,6 +1629,17 @@
     </span>
   </a>
 
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#web-terminal-settings" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Web Terminal Settings
+      
+    </span>
+  </a>
+  
 </li>
 
           <li class="md-nav__item">
@@ -1999,6 +2043,7 @@ <h2 id="prerequisites">Prerequisites<a class="headerlink" href="#prerequisites"
 <li><strong>Obsidian</strong> — for study notes (any vault structure works)</li>
 <li><strong>Optional</strong>: <code>notebooklm-py</code> for Google NotebookLM sync</li>
 <li><strong>Optional</strong>: <code>sentence-transformers</code> for semantic search</li>
+<li><strong>Optional</strong>: <code>ttyd</code> — enables web terminal access from browser or iPad (<code>brew install ttyd</code> on macOS, <code>apt install ttyd</code> on Linux)</li>
 </ul>
 <blockquote>
 <p><strong>tmux-resurrect / tmux-continuum users</strong>: studyctl automatically cleans up
@@ -2109,6 +2154,21 @@ <h3 id="web-pwa-recommended">Web PWA (recommended)<a class="headerlink" href="#w
 - <strong>Read once</strong> — tap the speaker icon on a card, or press <code>T</code>. Reads the current content once.
 - <strong>Auto-voice</strong> — toggle the header speaker icon, or press <code>V</code>. Reads everything automatically as you navigate.</p>
 <p><strong>Accessibility:</strong> The <code>Aa</code> button toggles <a href="https://opendyslexic.org">OpenDyslexic</a> font. The sun icon toggles light/dark theme. Both are persisted across sessions.</p>
+<h3 id="remote-study-ipad-on-the-bus">Remote Study (iPad on the Bus)<a class="headerlink" href="#remote-study-ipad-on-the-bus" title="Permanent link">&para;</a></h3>
+<p>Use <code>--lan</code> to make the web dashboard and terminal accessible from any device on your network — phone, iPad, second laptop:</p>
+<div class="highlight"><pre><span></span><code>studyctl<span class="w"> </span>study<span class="w"> </span><span class="s2">&quot;Python Decorators&quot;</span><span class="w"> </span>--energy<span class="w"> </span><span class="m">7</span><span class="w"> </span>--lan
+<span class="c1"># Auto-generates password and saves LAN info to session state:</span>
+<span class="c1">#   Dashboard: http://192.168.1.42:8567/session</span>
+<span class="c1">#   Password:  &lt;auto-generated&gt;</span>
+
+<span class="c1"># Or set a known password:</span>
+studyctl<span class="w"> </span>study<span class="w"> </span><span class="s2">&quot;Python Decorators&quot;</span><span class="w"> </span>--energy<span class="w"> </span><span class="m">7</span><span class="w"> </span>--lan<span class="w"> </span>--password<span class="w"> </span>mysecret
+</code></pre></div>
+<p>Access the live dashboard and embedded terminal from your iPad at <code>http://&lt;mac-ip&gt;:8567/session</code>. Enter any username and the displayed password when prompted. The terminal panel (ttyd iframe) is proxied through the web server on the same origin, so pop-out/return works seamlessly. ttyd must be installed for the terminal panel to work (<code>brew install ttyd</code>).</p>
+<p><strong>Password sources</strong> (checked in order):
+1. <code>--password</code> CLI flag
+2. <code>lan_password</code> in <code>~/.config/studyctl/config.yaml</code>
+3. Auto-generated (displayed in terminal output, saved to session state)</p>
 <h3 id="hosts-cross-machine-sync">Hosts — Cross-Machine Sync<a class="headerlink" href="#hosts-cross-machine-sync" title="Permanent link">&para;</a></h3>
 <h4 id="prerequisites-passwordless-ssh">Prerequisites: Passwordless SSH<a class="headerlink" href="#prerequisites-passwordless-ssh" title="Permanent link">&para;</a></h4>
 <p>Cross-machine sync uses SSH and rsync under the hood. <strong>Passwordless SSH must be configured</strong> between all machines before sync will work. If you're prompted for a password, sync will hang or fail.</p>
@@ -2272,6 +2332,13 @@ <h3 id="database-search-settings">Database &amp; Search Settings<a class="header
 - <code>DATABASE_PATH</code> — override database location
 - <code>LOG_LEVEL</code> — set logging level (DEBUG, INFO, WARNING, ERROR)
 - <code>EMBEDDING_MODEL</code> — override embedding model</p>
+<h3 id="web-terminal-settings">Web Terminal Settings<a class="headerlink" href="#web-terminal-settings" title="Permanent link">&para;</a></h3>
+<div class="highlight"><pre><span></span><code><span class="c1"># Web terminal (optional — requires ttyd installed)</span>
+<span class="nt">ttyd_port</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">7681</span><span class="w">      </span><span class="c1"># ttyd listens on this port (default 7681)</span>
+<span class="nt">web_port</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">8567</span><span class="w">       </span><span class="c1"># web dashboard port (default 8567)</span>
+<span class="nt">browser</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="w">          </span><span class="c1"># auto-open browser: chrome, safari, firefox, brave, or empty for system default</span>
+<span class="nt">lan_password</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="w">     </span><span class="c1"># persistent LAN password (auto-generated per session if empty)</span>
+</code></pre></div>
 <h3 id="tts-voice-settings">TTS Voice Settings<a class="headerlink" href="#tts-voice-settings" title="Permanent link">&para;</a></h3>
 <div class="highlight"><pre><span></span><code><span class="nt">tts</span><span class="p">:</span>
 <span class="w">  </span><span class="nt">voice</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">am_michael</span><span class="w">      </span><span class="c1"># kokoro voice (am_michael, af_heart, bf_emma, etc.)</span>

search/search_index.json

@@ -1031,6 +1031,9 @@ <h2 id="the-big-picture">The Big Picture<a class="headerlink" href="#the-big-pic
     TMUX --&gt; AGENT
     TMUX --&gt; SIDEBAR
     STUDY -.-&gt;|"--web"| DASH
+    STUDY -.-&gt;|"--lan"| TTYD["ttyd&lt;br/&gt;(port 7681)"]
+    TTYD -.-&gt;|"attaches to"| TMUX
+    DASH -.-&gt;|"/terminal/ proxy"| TTYD
     AGENT --&gt;|writes| IPC
     SIDEBAR --&gt;|polls| IPC
     DASH --&gt;|polls SSE| IPC
@@ -1129,11 +1132,17 @@ <h3 id="2-study-sessions-one-command-full-environment">2. Study Sessions — One
     U-&gt;&gt;CLI: studyctl study "Decorators" --energy 7
     CLI-&gt;&gt;DB: start_study_session()
     CLI-&gt;&gt;IPC: Write session-state.json + empty topics/parking
-    CLI-&gt;&gt;TMUX: Create session (cwd=sessions/study-decorators-xxx/)
+    CLI-&gt;&gt;TMUX: Create session (cwd=sessions/study-decorators-xxx/, window-size largest)
     CLI-&gt;&gt;TMUX: Split pane 75/25
     TMUX-&gt;&gt;AGENT: Main pane: claude --append-system-prompt-file persona.md
     TMUX-&gt;&gt;TUI: Sidebar pane: python -m studyctl.tui.sidebar
 
+    opt --lan flag
+        CLI-&gt;&gt;WEB: Start ttyd (attaches to tmux session, port 7681)
+        CLI-&gt;&gt;WEB: Start web with Basic Auth + ttyd proxy
+        Note over WEB: Web dashboard proxies ttyd at /terminal/&lt;br/&gt;(same-origin — pop-out/return preserves WS)&lt;br/&gt;HTTP Basic Auth protects all routes on LAN
+    end
+
     loop Every 2 seconds
         TUI-&gt;&gt;IPC: stat() mtime check
         IPC--&gt;&gt;TUI: Update timer, activity, counters
@@ -1542,6 +1551,11 @@ <h2 id="prerequisites">Prerequisites<a class="headerlink" href="#prerequisites"
 <td><code>brew install tmux</code> / <code>apt install tmux</code></td>
 </tr>
 <tr>
+<td>ttyd</td>
+<td>Optional — remote terminal (<code>--lan</code>)</td>
+<td><code>brew install ttyd</code> / <code>apt install ttyd</code></td>
+</tr>
+<tr>
 <td>Claude Code</td>
 <td>For AI study sessions</td>
 <td><code>npm install -g @anthropic-ai/claude-code</code></td>