HT-012 — Nova Workspace Structure

Purpose

Documents the folder taxonomy, Git/SSH configuration, repo clone patterns, and expansion strategy for Nova-Alpha's WSL workspace. This is the reference for where things live, why they live there, and how to add new capabilities.

If you're wondering "where does this go?" or "how do I add a new service to Nova?" — start here.

Workspace Root

Nova's workspace lives entirely inside WSL (Ubuntu) at:

/home/shane/nova/

Shorthand: ~/nova/

This is NOT on the Windows file system. It lives inside WSL's ext4 virtual disk. You can access it from Windows via:

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

Or from a Windows Terminal Nova profile (see HT-011).

Current Folder Structure

~/nova/
├── agents/              # AI agent scripts (Discord bots, automation agents)
├── atlantis-ops/        # Command Center dashboard (Next.js, cloned from GitHub)
├── logs/                # Centralized logging for all Nova services
├── services/            # Background services (n8n connectors, NTFY bridge, etc.)
└── ui/                  # Additional UI projects and dashboards

Subfolder Purposes

agents/ — Home for all AI agent code that runs under PM2.

This includes Discord bots (Ozzy, Scout, Jimmy, Mercy) and any future automation agents. Each agent gets its own subfolder:

agents/
├── ozzy-bot/            # Claude-powered Discord bot
│   ├── ozzy_bot.py
│   └── .env
├── scout-bot/           # Grok-powered Discord bot
│   ├── scout_bot.py
│   └── .env
├── jimmy-bot/           # Gemini-powered Discord bot (planned)
└── mercy-bot/           # ChatGPT-powered Discord bot (planned)

Current status: bots still live at D:\Data\AtlantisITS\discord-bots\ on Windows. Migration to ~/nova/agents/ is planned once PM2 persistence is fully configured.

atlantis-ops/ — The Command Center dashboard.

Cloned from git@github.com:Golboni/atlantis-ops.git. Runs under PM2 as atlantis-ops on port 3000. This is the primary UI showing mission status, weather, Nova-Alpha telemetry, and local app status.

Do NOT manually create files here — this is a Git-managed repo. Always git pull for updates.

logs/ — Centralized log storage.

PM2 handles its own logs at ~/.pm2/logs/, but this folder is for custom logging, runbook entries, and audit trails. Future use: Nova's self-monitoring logs, security scan results, performance baselines.

services/ — Background service configurations and scripts.

For services that aren't full apps or agents but need to run persistently. Examples: n8n bridge scripts, NTFY relay, cron-style automation, health check monitors.

ui/ — Additional frontend projects.

For UI experiments, dashboards, or tools that aren't the main Command Center. Keep separate from atlantis-ops/ to avoid polluting the production dashboard repo.

Planned Expansion

As Nova grows, new folders are added for new capabilities:

~/nova/
├── agents/              # (existing)
├── atlantis-ops/        # (existing)
├── logs/                # (existing)
├── services/            # (existing)
├── ui/                  # (existing)
├── security/            # Kali tools, red/blue team scripts, scan results
├── brain/               # Ollama models, RAG database, memory files
└── forge/               # Local Forgejo data or mirror/cache

security/ — Red/Blue Team Workspace

For offensive and defensive security tooling. OpenClaw-orchestrated pen tests, Kali tool outputs, vulnerability scan logs, honeypot analysis.

Important: Kali Linux itself should be installed as a separate WSL distro (not inside Ubuntu). The security/ folder holds scripts, configs, and results — not the Kali OS itself. See "Kali Architecture" section below.

brain/ — AI/ML Workspace

For Ollama model storage, RAG database files (ChromaDB/LanceDB), and cached copies of ATLANTIS_AI_MEMORY.md pulled from Forgejo. This becomes Nova's local intelligence layer.

forge/ — Forgejo Local Cache

For local clones of Forgejo repos, mirror scripts, and sync tooling. When Forgejo is deployed on VPS, this folder holds the local working copies of internal repos.

Python Virtual Environment

Separate from the workspace tree, the Python venv lives at:

~/nova-env/

Activate before running any Python-based agents:

source ~/nova-env/bin/activate

Deactivate when done:

deactivate

This keeps Python dependencies isolated from system packages. All Discord bots and Python agents should run within this venv (or their own if they need conflicting deps).

Git Configuration

Identity

Git is configured globally in WSL:

git config --global user.name "Golboni"
git config --global user.email "<your-email>"

SSH Keys

Nova-Alpha uses separate SSH keys per Git provider for clean routing:

~/.ssh/
├── id_github              # Private key for GitHub
├── id_github.pub          # Public key → registered at GitHub
├── id_forgejo             # Private key for Forgejo (when deployed)
├── id_forgejo.pub         # Public key → registered at Forgejo
└── config                 # SSH routing config

Generate keys (if not already done):

ssh-keygen -t ed25519 -C "shane@github" -f ~/.ssh/id_github
ssh-keygen -t ed25519 -C "shane@forgejo" -f ~/.ssh/id_forgejo

SSH Config File

~/.ssh/config routes connections to the correct key:

Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_github

Host forgejo.atlantisits.ai
    HostName forgejo.atlantisits.ai
    User git
    IdentityFile ~/.ssh/id_forgejo

Test connectivity:

ssh -T git@github.com
# Expected: Hi Golboni! You've successfully authenticated...

ssh -T git@forgejo.atlantisits.ai
# Expected: similar success message (once Forgejo is deployed)

Clone Patterns

How Nova Gets New Repos

Every repo Nova needs access to gets cloned into the appropriate subfolder:

# Command Center
cd ~/nova
git clone git@github.com:Golboni/atlantis-ops.git

# Discord bot (future — when migrating from D:\)
cd ~/nova/agents
git clone git@github.com:Golboni/discord-bots.git ozzy-bot

# Internal repo from Forgejo (future)
cd ~/nova/services
git clone git@forgejo.atlantisits.ai:atlantis/n8n-bridge.git

Pattern Rules

1. Always clone into the correct subfolder — don't dump everything at ~/nova/ root
2. Name the clone folder descriptively — use git clone <url> <folder-name> to override defaults when needed
3. Never clone sensitive repos to Windows paths — WSL paths only for anything touching API keys, secrets, or internal code
4. Always use SSH URLs — not HTTPS. SSH keys are already configured for passwordless auth
5. After cloning, register with PM2 if it's a service — then pm2 save to persist

Dual-Remote Pattern (GitHub + Forgejo)

For repos that need to exist on both GitHub (public visibility) and Forgejo (internal/private):

cd ~/nova/atlantis-ops

# Check current remote
git remote -v
# origin  git@github.com:Golboni/atlantis-ops.git (fetch)
# origin  git@github.com:Golboni/atlantis-ops.git (push)

# Add Forgejo as second remote
git remote add forgejo git@forgejo.atlantisits.ai:atlantis/atlantis-ops.git

# Push to both
git push origin main
git push forgejo main

# Or push to both at once (add a push URL to origin)
git remote set-url --add --push origin git@github.com:Golboni/atlantis-ops.git
git remote set-url --add --push origin git@forgejo.atlantisits.ai:atlantis/atlantis-ops.git

# Now `git push` hits both

Adding a New Capability to Nova

When Nova needs a new power (new bot, new service, new tool), follow this pattern:

Step 1 — Choose the Right Subfolder

Step 2 — Create or Clone

# New project from scratch
mkdir -p ~/nova/agents/my-new-bot
cd ~/nova/agents/my-new-bot
git init

# Or clone existing
cd ~/nova/agents
git clone git@github.com:Golboni/my-new-bot.git

Step 3 — Install Dependencies

cd ~/nova/agents/my-new-bot
npm install          # for Node.js projects
# or
source ~/nova-env/bin/activate
pip install -r requirements.txt   # for Python projects

Step 4 — Register with PM2

# Node.js
pm2 start app.js --name my-new-bot

# Python
pm2 start bot.py --name my-new-bot --interpreter python3

# npm script
pm2 start npm --name my-new-bot -- run start

Step 5 — Save PM2 State

pm2 save

This ensures the new service survives reboots. See HT-013 for full PM2 reference.

Step 6 — Document

Update this document (HT-012) and the V18+ memory file with the new subfolder and its purpose.

Kali Architecture

Kali Linux is deployed as a separate WSL distro, not inside the Ubuntu instance that hosts Nova.

Why Separate

1. Package isolation — Kali's repos conflict with Ubuntu's. Mixing them breaks both.
2. Security boundary — Offensive tools should never share the same environment as production services.
3. Snapshot/reset — You can wipe and rebuild Kali without touching Nova's Ubuntu.
4. Clean audit trail — Security work happens in a dedicated environment.

Installation

# From PowerShell (Administrator)
wsl --install -d kali-linux

Workspace Bridge

Kali can access Nova's workspace via WSL interop if needed, but the preferred pattern is:

• Kali stores its own tools and results in its own filesystem
• Results that need to be shared get copied to ~/nova/security/ in Ubuntu
• Nova's Command Center can read from ~/nova/security/ for dashboarding

PM2 Does NOT Manage Kali

PM2 runs inside Ubuntu. Kali services (if any) are managed separately within the Kali distro. Keep lifecycles independent.

Windows-Side Files (Not in Nova Workspace)

Some files live on the Windows filesystem by necessity:

These are documented in SOP-004 Section 6. The hardware API will always live on Windows. The Discord bots will migrate to ~/nova/agents/ once PM2 persistence is solid.

File Explorer Access

From WSL terminal:

cd ~/nova
explorer.exe .

This opens Windows File Explorer at \\wsl.localhost\Ubuntu\home\shane\nova\.

Or use the desktop shortcut (see HT-011, Layer 3).

Troubleshooting

"Permission denied" When Cloning

SSH key not loaded or not registered:

ssh -T git@github.com    # test connection
ssh-add ~/.ssh/id_github  # load key if needed

Clone Succeeds but PM2 Can't Start the App

Check that you're in the right directory and dependencies are installed:

cd ~/nova/agents/my-bot
ls                        # confirm files exist
npm install               # or pip install
pm2 start ...

WSL Path Shows as Empty in Windows File Explorer

WSL must be running. Open any WSL terminal first, then the \\wsl.localhost\ path resolves.

"Which Python?" Confusion

Always activate the venv before running Python agents:

which python3
# should show: /home/shane/nova-env/bin/python3

# If it shows /usr/bin/python3, activate the venv:
source ~/nova-env/bin/activate

Related Documents

• HT-011 — Nova-Alpha Quick Access (Terminal profiles, shortcuts)
• HT-013 — PM2 Process Manager (service lifecycle)
• HT-014 — Windows Service Management (Windows-side services)
• HT-015 — WSL ↔ Windows Bridge (cross-ecosystem networking)
• SOP-004 — Nova-Alpha Desktop Build & Recovery

Revision History

End of HT-012 — Nova Workspace Structure