Windows/Linux System Upgrade

Goal

Improve design of Windows/Linux system
- Minimize friction of using and maintaining separate OS environments
- optimize results and workflows in the medium and long-term

Background

I am a solopreneur power user with decades of Windows experience and very little using Linux/WSL2
I recognize that Linux is the preferred environment for development of websites (Astro monorepo), web apps, and AI tools like Claude Code, Cursor, Antigravity, etc
My current Windows system setup strategically has all operating system and apps on the C drive, and all created content on the D drive, making backups clean and simple (except for app config files, on C:)
- ALL installed apps are Windows-based.
- Obsidian is critical infrastructure for business and personal knowledge base (KB) efforts. Its markdown system communicates very well with AI.
- Use Git extensively, for dev and KB versioning
- Most system utils created by me are Python based, and a little AutoHotKey
I am willing to learn a practical amount of Linux
Already experienced Windows/Linux issues with
- node_modules binaries
- LF/CRLF issues, in Git commits and web deployment of Obsidian KB
- path separators (/ vs )
- Windows versions of AI tools inefficiently invoking WSL commands
- issues trying to link config files within same OS and Windows/Linux sharing
additional background in attached Tech Stack and Web Tech Stack notes. Note that some of these are current, and some are future intentions.

WSL Migration Plan

TC config for efficient WSL
setup WSL environment/structure
- ~/projects, or better?
- ~/utils
- …
centralized AI config
- for multiple AI tools
- for AGENTS/CLAUDE/GEMINI.md, etc
- for SKILLS
- more
update my_backup, to capture all WSL data, not binaries, …
migrate monorepo
migrate existing utils
- my_backup also, if no Windows dependencies?
create all new utils in ~/utils/

from Claude chat

Phase 1: Total Commander Configuration for Efficient WSL - DONE

1.1 Create WSL Bookmarks

In Total Commander:
1. Ctrl+D (Add bookmark)
2. Add these locations:

Name: "WSL Home"
Path: \\wsl$\Ubuntu\home\talbot

Name: "WSL Projects"
Path: \\wsl$\Ubuntu\home\talbot\projects

Name: "WSL Utils"
Path: \\wsl$\Ubuntu\home\talbot\utils

Name: "WSL AI Config"
Path: \\wsl$\Ubuntu\home\talbot\config-ai

1.3 Optional: Map WSL as Network Drive

powershell

# In PowerShell (run once, persists across reboots if WSL auto-starts)
net use W: \\wsl$\Ubuntu

Phase 2: Setup WSL Environment/Structure - STARTED

2.1 Directory Structure (Optimal)

bash

# In WSL Ubuntu
cd ~

# Create primary structure
mkdir -p projects/{monorepo,kb-online,sandbox}
mkdir -p utils/{deployment,kb-processing,financial,automation}
mkdir -p config-ai/{skills,agents,prompts}
mkdir -p .local/bin  # For custom scripts in PATH
mkdir -p backup-staging  # Temporary area for backup prep

# Create convenience symlinks
ln -s /mnt/d/FSS/KB/Business ~/.kb-source
ln -s /mnt/d/FSS/Backups ~/.backups-windows
```

**Final structure:**
```
/home/talbot/
├── projects/              # All web development
│   ├── monorepo/         # Your Astro sites
│   ├── kb-online/        # KB publishing
│   └── sandbox/          # Experimental/learning projects
│
├── utils/                # All Python utilities (AI-generated)
│   ├── deployment/       # Deploy scripts
│   ├── kb-processing/    # KB sync, transform, etc.
│   ├── financial/        # SMART DEBT analysis, portfolio
│   └── automation/       # n8n, Crew AI orchestration
│
├── config-ai/            # Centralized AI configuration
│   ├── CLAUDE.md         # Claude-specific context
│   ├── AGENTS.md         # Agent role definitions
│   ├── GEMINI.md         # Gemini-specific context
│   ├── skills/           # Skill definitions
│   │   ├── deployment/
│   │   ├── kb-sync/
│   │   └── financial/
│   └── prompts/          # Reusable prompt templates
│
├── .local/bin/           # Custom scripts in PATH
├── backup-staging/       # Temp area for backup operations
├── .kb-source -> /mnt/d/FSS/KB/Business  # Symlink
└── .backups-windows -> /mnt/d/FSS/Backups  # Symlink

2.2 Configure Shell Environment - DONE

bash

# Add to ~/.bashrc
cat >> ~/.bashrc << 'EOF'

# === Custom Paths ===
export PATH="$HOME/.local/bin:$PATH"

# === Project Aliases ===
alias proj='cd ~/projects'
alias mono='cd ~/projects/monorepo'
alias kb='cd ~/projects/kb-online'
alias utils='cd ~/utils'
alias ai='cd ~/config-ai'

# === Quick Navigation ===
alias kbsource='cd ~/.kb-source'
alias bak='cd ~/.backups-windows'

# === Development Shortcuts ===
alias build-template='cd ~/projects/monorepo/sites/Template && pnpm build'
alias deploy-template='cd ~/projects/monorepo/sites/Template && pnpm build && pnpm deploy'
alias dev-template='cd ~/projects/monorepo/sites/Template && pnpm dev'

# === Git Shortcuts ===
alias gs='git status'
alias gp='git pull'
alias gc='git commit -m'

EOF

# Reload
source ~/.bashrc

2.3 Configure Git (Critical for Line Endings)

bash

git config --global core.autocrlf input
git config --global core.eol lf
git config --global user.name "Talbot Stevens"
git config --global user.email "your@email.com"

# Optional but useful
git config --global pull.rebase false
git config --global init.defaultBranch main

Phase 3: Centralized AI Configuration

3.1 Create Base Configuration Files

bash

cd ~/config-ai

# CLAUDE.md - Claude-specific context
cat > CLAUDE.md << 'EOF'
# Claude AI Configuration

## Project Context
- Primary focus: Astro monorepo development, SMART DEBT mission
- Location: ~/projects/monorepo
- KB Source: ~/.kb-source (symlink to /mnt/d/FSS/KB/Business)

## Development Standards
- Framework: Astro with native components (default to Astro over Svelte)
- Styling: Tailwind CSS with custom component library
- Design: Fluid typography/spacing with breakpoint constraints
- Testing: Responsively App for multi-device preview

## File Locations
- Monorepo: ~/projects/monorepo
- KB Online: ~/projects/kb-online
- Utilities: ~/utils
- Skills: ~/config-ai/skills

## Key Documentation References
- Web Tech Stack: ~/.kb-source/03_Processes/Website Dev/Web Tech Stack.md
- Template Lessons: ~/.kb-source/03_Processes/Website Dev/Template/Lessons-Template-Dev.md
- Component Library: ~/projects/monorepo/sites/Template/docs/COMPONENT_LIBRARY.md

## Deployment Targets
- Cloudflare Pages (primary)
- All sites in monorepo/sites/*

## Utility Development
- All new utilities created in ~/utils
- Use Python 3.12+ with uv for dependency management
- Can access Windows files via /mnt/d/FSS/...
- Focus on cross-platform compatibility (avoid Windows-specific libs)
EOF

# AGENTS.md - Agent role definitions
cat > AGENTS.md << 'EOF'
# AI Agent Roles & Responsibilities

## Development Agent
**Role:** Component development, site building, debugging
**Context:**
- Astro monorepo structure
- Custom component library
- Fluid design system
**Primary Skills:**
- astro-development
- component-architecture
- responsive-design

## Deployment Agent
**Role:** Build orchestration, Cloudflare deployments, CI/CD
**Context:**
- Multi-site monorepo
- Cloudflare Pages configuration
- Build optimization
**Primary Skills:**
- cloudflare-deployment
- build-optimization
- ci-cd

## Utility Agent
**Role:** Python utility creation, automation scripts
**Context:**
- ~/utils structure
- Cross-platform compatibility
- Windows file access via /mnt/d/
**Primary Skills:**
- python-automation
- file-processing
- cross-platform-development

## KB Agent
**Role:** Knowledge base sync, content transformation, publishing
**Context:**
- Obsidian vault at ~/.kb-source
- Astro Starlight for publishing
- Privacy filtering
**Primary Skills:**
- obsidian-to-astro
- markdown-processing
- content-filtering

## Financial Agent
**Role:** SMART DEBT analysis, portfolio calculations, investment modeling
**Context:**
- Python-based analysis
- Data from /mnt/d/FSS/Finances/
- PDF report generation
**Primary Skills:**
- financial-modeling
- debt-analysis
- data-visualization
EOF

# GEMINI.md - Gemini-specific context
cat > GEMINI.md << 'EOF'
# Gemini AI Configuration

## Primary Use Cases
- Strategic planning (deep research mode)
- Architecture decisions
- Long-form documentation
- Complex coding challenges

## Context Sharing
Gemini can reference:
- AGENTS.md for role definitions
- CLAUDE.md for project structure
- Skills in ~/config-ai/skills/

## Preferred Interaction Style
- Provide comprehensive analysis
- Include trade-offs and alternatives
- Suggest "or better" solutions
- Reference multiple sources
EOF

3.2 Create Skills Directory Structure

bash

mkdir -p ~/config-ai/skills/{deployment,kb-sync,financial,component-dev}

# Example skill: Deployment
cat > ~/config-ai/skills/deployment/SKILL.md << 'EOF'
# Deployment Skill

## Purpose
Automate Cloudflare Pages deployments for monorepo sites

## Tools Required
- wrangler CLI
- pnpm
- Git

## Workflow
1. Build site: `pnpm build`
2. Verify dist/ directory
3. Deploy: `wrangler pages deploy dist --project-name=<site>`
4. Verify deployment URL

## Common Issues
- Missing environment variables → Check Cloudflare dashboard
- Build failures → Check node_modules, pnpm lockfile
- 404 on routes → Check Astro routing config
EOF

# Example skill: KB Sync
cat > ~/config-ai/skills/kb-sync/SKILL.md << 'EOF'
# Knowledge Base Sync Skill

## Purpose
Sync Obsidian vault to Astro Starlight site with privacy filtering

## Source & Destination
- Source: ~/.kb-source (→ /mnt/d/FSS/KB/Business)
- Destination: ~/projects/kb-online/src/content/docs

## Process
1. Read Obsidian markdown files
2. Filter by frontmatter: `private: true` excludes
3. Transform wikilinks to relative links
4. Convert Obsidian callouts to Starlight admonitions
5. Generate sidebar.json from folder structure

## Tools
- Deno runtime (for TypeScript scripts)
- Remark/Rehype plugins
EOF

3.3 Configure AI Tools to Use Centralized Config

For Claude Code:

bash

# Create .claudeconfig in project roots
cd ~/projects/monorepo
cat > .claudeconfig << 'EOF'
{
  "rules": [
    "Read ~/config-ai/CLAUDE.md for project context",
    "Reference ~/config-ai/AGENTS.md for role clarity",
    "Check ~/config-ai/skills/ for specialized workflows"
  ]
}
EOF

For Cursor:

bash

# Add to Cursor settings (Ctrl+, in Cursor)
# Settings → Cursor Settings → Indexed Docs
# Add these paths:
~/config-ai/CLAUDE.md
~/config-ai/AGENTS.md
~/config-ai/skills/
~/.kb-source/03_Processes/Website Dev/
~/projects/monorepo/sites/Template/docs/

Phase 4: Update my_backup to Capture WSL Data - DONE

4.1 Update config.yaml

Add to your existing D:\FSS\Software\Utils\PythonUtils\my_backup\config.yaml:

yaml

snapshots:
  # ... existing snapshots (FSS, etc.) ...

  # NEW: WSL Development Projects
  - name: "WSL-Projects"
    path: "\\\\wsl$\\Ubuntu\\home\\talbot\\projects"
    description: "Web development projects (Astro monorepo, kb-online)"
    excludes:
      - "**/.git/lfs/**"
      - "**/node_modules/**"
      - "**/.next/**"
      - "**/.astro/**"
      - "**/.turbo/**"
      - "**/dist/**"
      - "**/build/**"
      - "**/.cache/**"
      - "**/.venv/**"
      - "**/coverage/**"
      - "**/__pycache__/**"

  # NEW: WSL Python Utilities
  - name: "WSL-Utils"
    path: "\\\\wsl$\\Ubuntu\\home\\talbot\\utils"
    description: "Python utilities and automation scripts"
    excludes:
      - "**/.venv/**"
      - "**/__pycache__/**"
      - "**/.pytest_cache/**"

  # NEW: WSL AI Configuration (critical!)
  - name: "WSL-config-ai"
    path: "\\\\wsl$\\Ubuntu\\home\\talbot\\config-ai"
    description: "Centralized AI tool configurations"
    # No excludes - backup everything

  # NEW: WSL User Scripts
  - name: "WSL-Scripts"
    path: "\\\\wsl$\\Ubuntu\\home\\talbot\\.local\\bin"
    description: "Custom user scripts in PATH"

Phase 5: Migrate Monorepo

5.1 Backup Current State (Safety) - DONE

powershell

# In PowerShell on Windows
# Create dated backup
Copy-Item -Recurse D:\FSS\Websites\monorepo D:\FSS\Websites\monorepo-BACKUP-$(Get-Date -Format 'yyyyMMdd')

5.2 Migrate to WSL - DONE

bash

# In WSL
cd ~/projects

# Use rsync to preserve git history and permissions
rsync -av --progress /mnt/d/FSS/Websites/monorepo/ ~/projects/monorepo/

# Verify git repository intact
cd ~/projects/monorepo
git status
git log --oneline -10

# Verify all files present
ls -la sites/

5.3 Initial Build Test

bash

cd ~/projects/monorepo

# Install dependencies (notice the speed!)
time pnpm install
# Should be 5-15 seconds vs 45-90 on Windows

# Test build
pnpm build

# Test dev server
pnpm dev
# Open browser to http://localhost:4321

5.4 Configure for WSL

bash

# Ensure line endings are LF
cd ~/projects/monorepo
find . -type f -name "*.js" -o -name "*.ts" -o -name "*.astro" -o -name "*.md" | \
  xargs dos2unix 2>/dev/null || true

# Verify git sees no changes (if line endings were already correct)
git status
```

### 5.5 Update Total Commander Bookmark
```
In TC:
Update "Monorepo" bookmark to:
\\wsl$\Ubuntu\home\talbot\projects\monorepo

Phase 6: Migrate Existing Utilities

6.1 Identify Utilities to Migrate

bash

# List current Windows utilities
ls /mnt/d/FSS/Software/Utils/PythonUtils/

# Candidates for migration (NO Windows dependencies):
# - KB sync scripts
# - Deployment automation
# - Data processing utilities
# - Financial analysis scripts

# Keep on Windows (Windows dependencies):
# - my_backup (Task Scheduler, Robocopy)
# - notify_manager (companion to my_backup)
# - Any AutoHotKey scripts (Windows-only)

6.2 Migration Template (Example: deploy-template.py) - DONE

bash

# Copy utility to WSL
mkdir -p ~/utils/deployment
cp /mnt/d/FSS/Software/Utils/PythonUtils/deploy-template.py ~/utils/deployment/

# Create uv project structure
cd ~/utils/deployment
cat > pyproject.toml << 'EOF'
[project]
name = "deployment-utils"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "rich>=13.0.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
EOF

# Test utility
uv run python deploy-template.py --help

# Update any Windows-specific paths
# Change: D:\FSS\... → /mnt/d/FSS/...
# Or better: Use relative paths from project root

6.3 Create Utility Index

bash

# Track what's where
cat > ~/utils/README.md << 'EOF'
# Utility Index

## Deployment (`~/utils/deployment/`)
- `deploy-template.py` - Deploy Template site to Cloudflare
- `deploy-all-sites.py` - Deploy all monorepo sites

## KB Processing (`~/utils/kb-processing/`)
- `sync-kb-content.py` - Sync Obsidian to Astro
- `generate-sidebar.py` - Auto-generate site navigation

## Financial (`~/utils/financial/`)
- `analyze-portfolio.py` - Investment portfolio analysis
- `debt-optimizer.py` - SMART DEBT calculations

## Automation (`~/utils/automation/`)
- (Future: n8n workflows, Crew AI agents)

## Windows-Only (D:\FSS\Software\Utils\PythonUtils\)
- `my_backup/` - Backup orchestration (Task Scheduler, Robocopy)
- `notify_manager/` - Notification system (companion to backup)
EOF

Phase 7: Create All New Utilities in ~/utils/

7.1 Utility Creation Workflow

bash

# Template for new utility
cd ~/utils

# Create new utility (example: financial analysis)
mkdir -p financial/portfolio-analyzer
cd financial/portfolio-analyzer

# Create uv project
cat > pyproject.toml << 'EOF'
[project]
name = "portfolio-analyzer"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "pandas>=2.0.0",
    "matplotlib>=3.7.0",
    "reportlab>=4.0.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
EOF

# Spec for AI
cat > SPEC.md << 'EOF'
# Portfolio Analyzer

## Goal
Analyze investment portfolio CSV files and generate PDF report

## Inputs
- CSV file: /mnt/d/FSS/Finances/portfolio.csv
- Columns: Date, Symbol, Shares, Price, Value

## Outputs
- PDF report: ~/utils/financial/portfolio-analyzer/reports/portfolio-YYYYMMDD.pdf
- Charts: Asset allocation, performance over time

## Requirements
- Use pandas for data processing
- matplotlib for charts
- reportlab for PDF generation
- Handle missing data gracefully
EOF

# Use Claude Code or Cursor to generate
# AI reads SPEC.md and creates portfolio_analyzer.py

7.2 AI Tool Configuration for Utility Development

bash

# In Claude Code or Cursor, when in ~/utils/
# AI automatically reads:
# - ~/config-ai/AGENTS.md (sees "Utility Agent" role)
# - ~/config-ai/CLAUDE.md (understands project context)
# - SPEC.md in current directory

Success Metrics & Validation

After Each Phase, Verify:

Phase 1 (TC Config):

Can navigate WSL directories in Total Commander
TC buttons execute WSL commands successfully

Phase 2 (WSL Setup):

All directories created
Symlinks work (test: ls ~/.kb-source)
Aliases work (test: mono, utils, ai)

Phase 3 (AI Config):

AI tools can read ~/config-ai/CLAUDE.md
Skills directory accessible to AI
Cursor indexes config-ai paths

Phase 4 (Backup Update):

Dry-run shows WSL snapshots
Live backup completes without errors
Can verify snapshots in KopiaUI

Phase 5 (Monorepo Migration):

Git history intact (git log)
pnpm install completes in <15s
pnpm dev starts successfully
Can deploy to Cloudflare

Phase 6 (Utility Migration):

Utilities run from ~/utils/
Can access Windows files via /mnt/d/
No Windows-specific errors

Phase 7 (New Utility Creation):

AI tools generate code faster (6x improvement)
Utilities are cross-platform compatible
README.md tracks all utilities

Timeline Estimate

Phase	Duration	Can Pause?
1. TC Config	30 min	✅ Yes
2. WSL Setup	1 hour	✅ Yes
3. AI Config	2 hours	✅ Yes (per file)
4. Backup Update	30 min	⚠️ Test fully
5. Monorepo Migration	2 hours	✅ Yes (parallel run)
6. Utility Migration	1-4 hours	✅ Yes (per utility)
7. New Utils (ongoing)	As needed	✅ Yes

Total active time: ~7-10 hours spread over 2-4 weeks
Safety period: 2 weeks parallel operation recommended