HT-011 — Nova-Alpha Quick Access

Purpose

Reduce friction accessing Nova-Alpha services. Out of the box, checking on WSL-side services from Windows requires multiple steps: open PowerShell, try a command, get "not recognized," type wsl, run the command, open File Explorer separately, navigate to \\wsl.localhost\..., and so on.

This document configures four productivity layers that collapse those steps into single clicks or keystrokes.

Goal: From any fresh Windows session, reach any Nova service in one action.

Overview

Four layers are configured:

Each layer is independent. Install what you want. Order does not matter.

Layer 1 — Windows Terminal Profile

Drops you directly into ~/nova inside Ubuntu with a single click.

1.1 Open Windows Terminal Settings

1. Open Windows Terminal
2. Click the ∨ dropdown arrow next to the + tab button
3. Select Settings
4. In the left sidebar, scroll to the bottom and click Add a new profile
5. Choose New empty profile

1.2 Configure the Profile

Fill in the following:

1.3 Appearance (Optional)

Under the Appearance tab for this profile:

• Color scheme: One Half Dark or Campbell Powershell both read well
• Font face: Cascadia Code or Consolas

1.4 Save and Test

Click Save. Open a new tab via the ∨ dropdown and pick Nova (WSL).

You should land directly at:

shane@Trunks:~/nova$

No PowerShell, no wsl command, no cd ~/nova. One click.

1.5 Make It the Default (Optional)

If you want every new Terminal tab to default to Nova:

• Settings → Startup → Default profile → select Nova (WSL)

Layer 2 — PowerShell Aliases

Run WSL-side commands like pm2 list from any PowerShell window without having to wsl first.

2.1 Open PowerShell Profile

From a PowerShell window:

notepad $PROFILE

If Notepad says the file does not exist, click Yes to create it.

2.2 Add Nova Aliases

Paste the following into the profile file:

# ─── Nova-Alpha Quick Access ────────────────────────────

# Raw passthrough to WSL pm2
function pm2 { wsl pm2 $args }

# Shortcuts for common checks
function nova-status   { wsl pm2 list }
function nova-restart  { wsl pm2 restart atlantis-ops }
function nova-logs     { wsl pm2 logs atlantis-ops --lines 50 }
function nova-monit    { wsl pm2 monit }

# Hardware API quick check (Windows side)
function nova-hw       { curl http://localhost:5002/api/hardware }

# Jump straight into WSL Nova workspace
function nova-cd       { wsl -d Ubuntu --cd ~/nova }

# Print current Nova status summary
function nova {
    Write-Host "─── Nova-Alpha Status ───" -ForegroundColor Cyan
    Write-Host "`nWSL Processes (PM2):" -ForegroundColor Yellow
    wsl pm2 list
    Write-Host "`nHardware API (Windows):" -ForegroundColor Yellow
    try {
        $hw = Invoke-RestMethod -Uri "http://localhost:5002/api/hardware" -TimeoutSec 2
        Write-Host "  Status: ONLINE" -ForegroundColor Green
        Write-Host "  CPU Load: $($hw.cpuLoad)% | GPU Load: $($hw.gpuLoad)% | RAM: $($hw.ramUsed) GB"
    } catch {
        Write-Host "  Status: OFFLINE or NOT REACHABLE" -ForegroundColor Red
    }
}

# ─── End Nova-Alpha ─────────────────────────────────────

2.3 Save and Reload

Save the file in Notepad (Ctrl+S). Reload the profile in your current PowerShell:

. $PROFILE

Or just close and reopen PowerShell.

2.4 Test

From any PowerShell window:

pm2 list              # works, routes through WSL
nova-status           # full PM2 table
nova-restart          # restart atlantis-ops
nova-logs             # tail last 50 log lines
nova-hw               # hardware API response
nova                  # full status summary (WSL + Windows)

Layer 3 — Desktop Shortcut to Nova Workspace

One-click File Explorer access to ~/nova/.

3.1 Create the Shortcut

1. Right-click anywhere on the Desktop
2. New → Shortcut
3. In the location field, paste:

\\wsl.localhost\Ubuntu\home\shane\nova

1. Click Next
2. Name it Nova
3. Click Finish

3.2 Optional — Custom Icon

1. Right-click the new shortcut → Properties
2. Click Change Icon...
3. Browse to any .ico file (a green or blue icon separates it visually)
4. Click OK → Apply

3.3 Pin to Taskbar or Start

Right-click the shortcut → Pin to taskbar (or Pin to Start) for even faster access.

Layer 4 — VS Code WSL Integration

Unified dev environment where Windows runs VS Code but the file system, terminal, and running processes are all inside WSL.

4.1 Install VS Code on Windows

If not already installed, from PowerShell:

winget install --id Microsoft.VisualStudioCode -e

4.2 Install the WSL Extension

1. Open VS Code
2. Press Ctrl+Shift+X to open Extensions
3. Search for WSL (publisher: Microsoft)
4. Click Install

4.3 Open Nova in VS Code via WSL

From the WSL terminal (either the Nova profile from Layer 1 or any WSL window):

cd ~/nova
code .

VS Code opens with:

• File tree showing ~/nova/ contents
• Integrated terminal already in WSL
• Git integration working against the cloned repo
• Status bar bottom-left shows WSL: Ubuntu confirming connection

4.4 VS Code Workspace File (Optional)

For even faster project switching, create ~/nova/nova.code-workspace:

{
  "folders": [
    { "path": "atlantis-ops" },
    { "path": "agents" },
    { "path": "services" },
    { "path": "ui" }
  ],
  "settings": {
    "terminal.integrated.defaultProfile.linux": "bash"
  }
}

Then from WSL:

code ~/nova/nova.code-workspace

Each folder is browsable from one VS Code window with one terminal.

Workflow Comparison

Before Quick Access Setup

Checking on atlantis-ops status:

1. Open PowerShell (Start menu → PowerShell)
2. Try pm2 list → "not recognized"
3. Type wsl and press Enter
4. Wait for WSL to start
5. Type pm2 list
6. Open File Explorer (Win+E)
7. Navigate Network → wsl.localhost → Ubuntu → home → shane → nova

Total: 7 steps, 2 windows, ~30–45 seconds

After Quick Access Setup

Checking on atlantis-ops status:

1. Open any PowerShell window → type nova

Total: 1 step, ~2 seconds

Opening Nova workspace in VS Code:

1. Double-click Nova (WSL) Terminal profile → type cd atlantis-ops && code .

Total: 2 steps, ~5 seconds

Troubleshooting

wsl Command Hangs

If wsl or any Layer 2 alias hangs:

wsl --shutdown

Then try again. WSL occasionally needs a restart after Windows updates.

Alias Not Recognized After Profile Edit

Confirm the profile loaded:

echo $PROFILE            # shows path
Get-Content $PROFILE     # shows contents
. $PROFILE               # reload manually

If still missing, close ALL PowerShell windows and reopen.

Nova Terminal Profile Doesn't Open to ~/nova

Verify the command line in Windows Terminal Settings → Profiles → Nova (WSL):

wsl.exe -d Ubuntu --cd ~/nova

The --cd flag must be lowercase and the path cannot have a trailing slash.

File Explorer Shortcut Shows "Path not found"

WSL must be running for the \\wsl.localhost\ path to resolve. Open any WSL window first, then the shortcut works.

code . Not Recognized in WSL

The VS Code WSL extension injects the code command into WSL's PATH when VS Code opens at least once with the extension installed. If it's missing:

1. Close all VS Code windows
2. From Windows, open VS Code normally
3. Press F1 → type WSL: Connect to WSL
4. Pick Ubuntu
5. Close and reopen WSL terminal → code . should now work

Related Documents

• HT-012 — Nova Workspace Structure (what lives at ~/nova/)
• HT-013 — PM2 Process Manager (what the aliases control)
• HT-014 — Windows Service Management (Windows-side auto-start)
• HT-015 — WSL ↔ Windows Bridge (networking layer)
• SOP-004 — Nova-Alpha Desktop Build & Recovery

Revision History

End of HT-011 — Nova-Alpha Quick Access