fix(#185): align website guides with selected doc surface

docs/core-workflows.html

@@ -261,19 +261,29 @@ <h2>Reload safely after changes</h2>
                         inside a long-lived interactive PowerShell session, switch to the PowerShell view and do the
                         full remove/build/import loop.</p>
                 </div>
-                <div class="notice">
+                <div class="notice" data-command-visibility="powershell">
                     <strong>When local publish changes the story.</strong>
-                    <p><code>PS&gt; Publish-NovaModule -Local</code> and <code>% nova publish --local</code> reload the
-                        published
-                        module from the local install path after a successful publish. That is different from the normal
-                        build/import loop, which works from <code>dist/</code>.</p>
+                    <p><code>Publish-NovaModule -Local</code> reloads the published module from the local install path
+                        after a successful publish. That is different from the normal build/import loop, which works
+                        from <code>dist/</code>.</p>
                 </div>
-                <div class="notice">
+                <div class="notice" data-command-visibility="command-line" hidden>
+                    <strong>When local publish changes the story.</strong>
+                    <p><code>% nova publish --local</code> moves the module into the local install path so a fresh
+                        PowerShell session can resolve the published copy directly. That is different from the normal
+                        build/import loop, which still validates <code>dist/</code>.</p>
+                </div>
+                <div class="notice" data-command-visibility="powershell">
                     <strong>CI/self-hosting note.</strong>
                     <p>When a later command in the same session must switch back to the built <code>dist/</code> module,
-                        use <code>Invoke-NovaBuild -ContinuousIntegration</code> or <code>% nova build
-                            --continuous-integration</code>
-                        so Nova restores the built module state automatically.</p>
+                        use <code>Invoke-NovaBuild -ContinuousIntegration</code> so Nova restores the built module state
+                        automatically.</p>
+                </div>
+                <div class="notice" data-command-visibility="command-line" hidden>
+                    <strong>CI/self-hosting note.</strong>
+                    <p>When a later command in the same self-hosting session must switch back to the built
+                        <code>dist/</code> module, use <code>% nova build --continuous-integration</code> so Nova
+                        restores the built module state automatically.</p>
                 </div>
             </section>
 

docs/getting-started.html

@@ -123,10 +123,15 @@ <h2>2. Install the module</h2>
                         you
                         plan to use the standalone command-line launcher later.</p>
                 </div>
-                <p>After import, you can use the PowerShell cmdlets directly. If you explicitly need the routed Nova
-                    command surface from PowerShell, use <code>Invoke-NovaCli</code>.</p>
-                <p><strong>Expected result:</strong> commands such as <code>Get-NovaProjectInfo</code>, <code>Invoke-NovaBuild</code>,
-                    and <code>nova</code> resolve in your PowerShell session.</p>
+                <div class="surface-note" data-command-visibility="command-line" hidden>
+                    <p><strong>Command-line note:</strong> <code>Import-Module NovaModuleTools</code> does
+                        <strong>not</strong> create a <code>nova</code> command in your shell. On macOS/Linux, run
+                        <code>Install-NovaCli</code> before you expect <code>% nova ...</code> to resolve outside
+                        PowerShell.</p>
+                </div>
+                <p>After import, you can use the PowerShell cmdlets directly.</p>
+                <p><strong>Expected result:</strong> commands such as <code>Get-NovaProjectInfo</code> and
+                    <code>Invoke-NovaBuild</code> resolve in your PowerShell session.</p>
             </section>
 
             <section class="content-section" id="entrypoints">
@@ -145,18 +150,20 @@ <h2>3. Choose PowerShell or CLI entrypoints</h2>
                         <tr>
                             <td>PowerShell cmdlets in <code>pwsh</code></td>
                             <td>You are already inside <code>pwsh</code>.</td>
-                            <td>Import the module once, then use cmdlets directly. Use <code>Invoke-NovaCli</code>
-                                only when you explicitly want the routed CLI surface from PowerShell.
-                            </td>
+                            <td>Import the module once, then use cmdlets directly.</td>
                         </tr>
                         <tr>
                             <td>Standalone <code>nova</code> launcher</td>
                             <td>You want to run Nova from zsh or bash on macOS/Linux.</td>
-                            <td>Install the launcher once with <code>Install-NovaCli</code>.</td>
+                            <td>Install the launcher once with <code>Install-NovaCli</code> before you expect
+                                <code>nova</code> to resolve in your shell.</td>
                         </tr>
                         </tbody>
                     </table>
                 </div>
+                <p data-command-visibility="command-line" hidden><strong>Important:</strong>
+                    <code>Import-Module NovaModuleTools</code> loads cmdlets into PowerShell, but the standalone
+                    <code>nova</code> launcher is a separate install step on macOS/Linux.</p>
                 <h3>Install the standalone launcher on macOS/Linux</h3>
                 <pre><code>PS&gt; Install-NovaCli</code></pre>
                 <p>By default, the launcher is installed to <code>~/.local/bin/nova</code>. If that directory is not
@@ -233,8 +240,8 @@ <h2>5. Build and test the example</h2>
             </section>
 
             <section class="content-section" id="import-and-run">
-                <h2>6. Import the built module and run a command</h2>
-                <p>Now take the built module into the environment you want to use and run the example command.</p>
+                <h2>6. Run the example command from the built or locally published module</h2>
+                <p>Now take the generated module into the environment you want to use and run the example command.</p>
                 <div class="surface-example" data-command-example>
                     <div class="surface-example__meta">
                         <p class="surface-example__title">Use the built module</p>

docs/index.html

@@ -187,10 +187,12 @@ <h3>Concepts</h3>
                 <h2>Recommended first 15-minute path</h2>
                 <ol class="plain-list plain-list--ordered">
                     <li>Install the module and import it into PowerShell.</li>
-                    <li>Scaffold the packaged example with <code>PS&gt; Initialize-NovaModule -Example</code>.</li>
-                    <li>Build with <code>PS&gt; Invoke-NovaBuild</code>.</li>
-                    <li>Test with <code>PS&gt; Test-NovaBuild</code>.</li>
-                    <li>Import the built example module and run <code>PS&gt; Get-ExampleGreeting</code>.</li>
+                    <li>If you want the <code>nova</code> launcher on macOS/Linux, install it with
+                        <code>Install-NovaCli</code>.</li>
+                    <li>Open <a class="text-link" href="./getting-started.html">Getting Started</a> and keep the page
+                        on your chosen PowerShell or command-line surface.</li>
+                    <li>Scaffold the packaged example, then build and test it.</li>
+                    <li>Run the example command from the built or locally published module.</li>
                 </ol>
                 <p>This path proves the tool works, shows the real folder structure, and gives you a runnable module
                     before you start customizing anything.</p>

docs/troubleshooting.html

@@ -217,13 +217,14 @@ <h2>Build errors point into the generated <code>.psm1</code></h2>
                 <h2><code>Install-NovaCli</code> says it is for macOS/Linux only</h2>
                 <p><strong>Likely cause:</strong> that is the current intended behavior. The standalone launcher is for
                     macOS/Linux shell use.</p>
-                <p><strong>Fix:</strong> on Windows, import the module and use the PowerShell cmdlets directly. If you
-                    explicitly need the routed CLI surface from PowerShell, call <code>Invoke-NovaCli</code>.</p>
+                <p><strong>Fix:</strong> on Windows, import the module and use the PowerShell cmdlets directly. The
+                    standalone <code>nova</code> launcher is a separate macOS/Linux install path, not something that
+                    appears automatically after <code>Import-Module</code>.</p>
                 <pre><code>PS&gt; Import-Module NovaModuleTools
 PS&gt; Get-NovaProjectInfo
-PS&gt; Invoke-NovaCli version</code></pre>
-                <p><strong>Success looks like:</strong> you can run Nova commands from PowerShell on Windows without
-                    installing the standalone launcher.</p>
+PS&gt; Invoke-NovaBuild</code></pre>
+                <p><strong>Success looks like:</strong> the NovaModuleTools cmdlets work in your PowerShell session on
+                    Windows, and you do not need a separate launcher install for that workflow.</p>
                 <p><a class="text-link" href="./getting-started.html#entrypoints">See entrypoint guidance</a></p>
             </section>
 

docs/working-with-modules.html

@@ -199,11 +199,18 @@ <h2>Use local publish intentionally</h2>
                 </ul>
                 <p>Use local publish when you want to simulate a real installed-module experience. Use the normal
                     build/import loop when you just want fast iteration in <code>dist/</code>.</p>
-                <div class="notice notice--warning">
+                <div class="notice notice--warning" data-command-visibility="powershell">
                     <strong>Do not confuse local publish with local release.</strong>
-                    <p><code>Invoke-NovaRelease -Local</code> publishes locally too, but it
-                        does <strong>not</strong> import the published module into the current session afterward. That
-                        special import behavior belongs to <code>Publish-NovaModule -Local</code>.</p>
+                    <p><code>Publish-NovaModule -Local</code> reloads the published module into the current PowerShell
+                        session after success. <code>Invoke-NovaRelease -Local</code> publishes locally too, but it does
+                        <strong>not</strong> import the published module afterward.</p>
+                </div>
+                <div class="notice notice--warning" data-command-visibility="command-line" hidden>
+                    <strong>Do not confuse local publish with local release.</strong>
+                    <p><code>% nova publish --local</code> prepares a locally installed module that a fresh PowerShell
+                        session can resolve right away. <code>% nova release --local</code> also publishes locally, but
+                        it does <strong>not</strong> add the extra published-module import behavior described for the
+                        local publish workflow.</p>
                 </div>
             </section>