fix(cli): diagnose native service plans in manager context

docs/faq.html

@@ -131,8 +131,9 @@
               <h2>Tools are failing, node is not found, or Pi cannot find commands</h2>
               <p>
                 The shell environment needs to be set up so login shells have the required PATH entries for PI WEB, Pi,
-                and any tools your agents need. PI WEB services run commands through a non-interactive login shell, so
-                an interactive terminal can work while services fail.
+                and any tools your agents need. PI WEB services run commands through a non-interactive login shell owned
+                by systemd or launchd, so an interactive terminal—or even a caller-invoked login shell—can work while the
+                native service fails.
               </p>
               <div class="code-card">
                 <div class="copy-row">
@@ -156,14 +157,17 @@
             <article id="doctor-fails" class="faq-item">
               <h2>What does <code>pi-web doctor</code> check?</h2>
               <p>
-                It checks whether the service shell and native service environment can find Node 22+, npm, Pi, and the Pi
-                Web binaries. It also prints installed and running PI WEB versions when available, reports optional ripgrep
-                availability for faster all-file <code>@</code>-mention suggestions, uses a bounded filesystem fallback when
-                ripgrep is unavailable, and reports user service lingering when relevant for server-style installs.
+                It keeps two kinds of checks separate. General login-shell readiness covers Node 22+, npm, Pi, and optional
+                ripgrep. Native-service diagnostics validate only the exact prerequisites of the selected service plan in
+                the real systemd user-manager or launchd <code>gui/&lt;uid&gt;</code> context. Development installs follow their
+                installed checkout plan; production checks are clearly labelled prospective when the installed executable
+                strategy cannot be reconstructed safely.
               </p>
               <p>
-                If something works in your terminal but fails in doctor, treat that as a login-shell PATH mismatch and
-                move the setup earlier in your shell startup chain.
+                Missing plan requirements fail doctor and include login-file guidance. Manager, timeout, malformed-output,
+                and cleanup failures are reported as probe infrastructure problems rather than being mislabeled as PATH
+                drift. On unsupported/manual-only platforms, native-service drift checks are skipped. Doctor also prints
+                installed and running PI WEB versions and reports systemd lingering when relevant.
               </p>
             </article>
 

docs/index.html

@@ -138,8 +138,8 @@
 # laptop, phone, tablet — same live sessions
 
 <span class="prompt">$</span> pi-web doctor
-✓ login shell can find node >= 22
-✓ native service shell can find pi
+✓ caller login shell can find node >= 22
+✓ native-service plan requirements pass in manager context
 ✓ ready for persistent agent work</code></pre>
           </aside>
         </div>

docs/install.html

@@ -112,8 +112,10 @@
               </ul>
               <div class="callout warning">
                 <strong>Important PATH detail:</strong>
-                PI WEB services run through your login shell with <code>-lc</code>. Setup that only lives in interactive shell
-                files or prompt hooks may not be visible to services. Run <code>pi-web doctor</code> after installing.
+                PI WEB services run through a non-interactive login shell with <code>-lc</code>. Setup that only lives in
+                interactive shell files or prompt hooks may not be visible to the systemd or launchd manager. The installer
+                probes the exact candidate plan in that manager context before changing config or replacing services; run
+                <code>pi-web doctor</code> later to repeat plan-specific diagnostics.
               </div>
             </section>
 
@@ -134,6 +136,7 @@
 <span class="prompt">$</span> pi-web doctor</code></pre>
               </div>
               <p>Then open <a href="http://127.0.0.1:8504">http://127.0.0.1:8504</a>.</p>
+              <p>If preflight fails, no config or existing services are changed. Follow the detected shell guidance: zsh services read <code>~/.zprofile</code>, not interactive-only <code>~/.zshrc</code>; bash uses <code>~/.bash_profile</code> or <code>~/.profile</code>.</p>
               <p>On Linux servers, also consider <code>sudo loginctl enable-linger "$USER"</code> so user services survive logout/reboot.</p>
             </section>