From 47fb066f1d110612d14f38ed1a773bb2532820e2 Mon Sep 17 00:00:00 2001
From: Vantz Stockwell <vstockwell@predator-mini.local>
Date: Tue, 17 Mar 2026 16:40:49 -0400
Subject: [PATCH] =?UTF-8?q?docs:=20Phase=207=20complete=20=E2=80=94=20CLAU?=
 =?UTF-8?q?DE.md=20+=20Go=20migration=20checklist?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CLAUDE.md for future XOs: tech stack, architecture, commands,
key design decisions, lineage from Go version.

GO_MIGRATION.md: step-by-step checklist for deploying v2,
archiving Go repo, configuring CI secrets, first release.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .gitea/workflows/build-release.yml |  2 +-
 CLAUDE.md                          | 72 ++++++++++++++++++++++++++++++
 docs/GO_MIGRATION.md               | 67 +++++++++++++++++++++++++++
 src-tauri/tauri.conf.json          |  2 +-
 4 files changed, 141 insertions(+), 2 deletions(-)
 create mode 100644 CLAUDE.md
 create mode 100644 docs/GO_MIGRATION.md

diff --git a/.gitea/workflows/build-release.yml b/.gitea/workflows/build-release.yml
index d910978..79bca73 100644
--- a/.gitea/workflows/build-release.yml
+++ b/.gitea/workflows/build-release.yml
@@ -208,6 +208,6 @@ jobs:
             -H "Authorization: token ${{ secrets.GIT_TOKEN }}" \
             -H "Content-Type: application/json" \
             -d "{\"tag_name\": \"v${VERSION}\", \"name\": \"Wraith v${VERSION}\", \"body\": \"Wraith Desktop v${VERSION} — Tauri v2 build.\"}" \
-            "${GITEA_URL}/api/v1/repos/vstockwell/wraith-v2/releases"
+            "${GITEA_URL}/api/v1/repos/vstockwell/wraith/releases"
           echo ""
           echo "Release created."
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..d25a57d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,72 @@
+# CLAUDE.md — Wraith Desktop v2
+
+## Project Overview
+
+Wraith is a native desktop SSH/SFTP/RDP client — a MobaXTerm replacement. Rust backend (Tauri v2) + Vue 3 frontend (WebView2). Single binary, no Docker, no sidecar processes.
+
+**Name:** Wraith — exists everywhere, all at once.
+
+## Tech Stack
+
+- **Runtime:** Tauri v2 (stable)
+- **Backend:** Rust with `russh` (SSH/SFTP), `ironrdp` (RDP), `rusqlite` (SQLite), `aes-gcm` + `argon2` (vault), `dashmap` (concurrent session registry)
+- **Frontend:** Vue 3 (Composition API, `<script setup>`), TypeScript, Vite, Pinia, Tailwind CSS v4, xterm.js 6, CodeMirror 6
+- **Distribution:** Tauri bundler (NSIS installer), auto-updater with code signing
+
+## Project Structure
+
+```
+src-tauri/                  # Rust backend
+  src/
+    main.rs                 # Entry point
+    lib.rs                  # App state, module declarations, Tauri setup
+    ssh/                    # SSH service (russh), host keys (TOFU), CWD tracker
+    sftp/                   # SFTP operations (russh-sftp)
+    rdp/                    # RDP service (ironrdp), scancode mapping
+    vault/                  # Encryption (Argon2id + AES-256-GCM)
+    db/                     # SQLite (rusqlite), migrations
+    connections/            # Connection CRUD, groups, search
+    credentials/            # Credential CRUD, encrypted storage
+    settings/               # Key-value settings
+    theme/                  # Terminal themes (7 built-in)
+    session/                # Session manager (DashMap)
+    workspace/              # Workspace snapshots, crash recovery
+    commands/               # Tauri command wrappers
+
+src/                        # Vue 3 frontend
+  layouts/                  # MainLayout, UnlockLayout
+  components/               # UI components
+  composables/              # useTerminal, useSftp, useRdp, useTransfers
+  stores/                   # Pinia stores (app, session, connection)
+  assets/                   # CSS, images
+```
+
+## Commands
+
+```bash
+npm install                 # Install frontend deps
+npm run dev                 # Vite dev server only
+cargo tauri dev             # Full app (Rust + frontend)
+cargo tauri build           # Production build
+cd src-tauri && cargo test  # Run Rust tests (52 tests)
+cd src-tauri && cargo build # Build Rust only
+```
+
+## Architecture
+
+- **Sessions use DashMap** — lock-free concurrent access, no deadlocks during tab detach
+- **Drop trait for cleanup** — SSH/SFTP/RDP connections close automatically when sessions drop
+- **CWD following via exec channel** — polls `pwd` on a separate SSH channel every 2 seconds. Never touches the terminal data stream. This avoids ANSI escape sequence corruption.
+- **RDP runs in dedicated thread** — ironrdp's trait objects aren't Send, so each RDP session gets its own tokio runtime in a std::thread
+- **xterm.js font handling** — `document.fonts.ready.then(() => fitAddon.fit())` prevents cell width miscalculation
+
+## Key Design Decisions
+
+1. **No terminal stream processing.** The Go version's CWD tracker parsed OSC 7 from the terminal output and corrupted ANSI sequences. Never again.
+2. **Tauri v2 over Wails v3.** Wails v3 is alpha with breaking changes. Tauri v2 is stable with built-in multi-window, auto-updater, and active community.
+3. **ironrdp over FreeRDP FFI.** Pure Rust, no DLL dependency, memory safe. FreeRDP is the fallback discussion if ironrdp can't hit performance targets.
+4. **Fresh vault, no Go migration.** 6 connections — faster to re-enter than engineer format compatibility.
+
+## Lineage
+
+This is a ground-up Rust rewrite of `wraith` (Go/Wails v3). The Go version is archived at `wraith-go-legacy`. The original design spec is at `docs/superpowers/specs/2026-03-17-wraith-desktop-design.md` in the Go repo.
diff --git a/docs/GO_MIGRATION.md b/docs/GO_MIGRATION.md
new file mode 100644
index 0000000..774e799
--- /dev/null
+++ b/docs/GO_MIGRATION.md
@@ -0,0 +1,67 @@
+# Go → Rust Migration Checklist
+
+## Pre-Migration (Before Deploying Wraith v2)
+
+- [ ] Test Wraith v2 on Windows — SSH to all 6 hosts, SFTP browse/upload/download, RDP to Hyper-V
+- [ ] Verify vault creation + credential storage works
+- [ ] Verify auto-updater finds releases
+- [ ] Test code signing on installer
+- [ ] Set up 6 connections manually (no import needed)
+
+## Migration Steps
+
+### 1. Create Gitea Repo
+```bash
+# Create wraith repo on Gitea (or rename current wraith to wraith-go-legacy)
+# Push wraith codebase
+cd /path/to/wraith
+git remote add origin ssh://git.command.vigilcyber.com:3021/vstockwell/wraith.git
+git push -u origin main
+```
+
+### 2. Configure CI Secrets
+Add these secrets to the wraith repo on Gitea:
+- `AZURE_TENANT_ID`
+- `AZURE_CLIENT_ID`
+- `AZURE_CLIENT_SECRET`
+- `AZURE_KEY_VAULT_URL`
+- `AZURE_CERT_NAME`
+- `GIT_TOKEN`
+- `TAURI_SIGNING_PRIVATE_KEY` (generate with `npx tauri signer generate`)
+- `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`
+
+### 3. First Release
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+### 4. Uninstall Go Version
+- Use a software uninstaller (the Go NSIS uninstaller is broken)
+- Or manually delete: `C:\Program Files\Wraith\` and `%APPDATA%\Wraith\`
+- Note: deleting `%APPDATA%\Wraith\wraith.db` removes Go version credentials (you're re-entering them anyway)
+
+### 5. Archive Go Repository
+On Gitea:
+1. Rename `wraith` repo to `wraith-go-legacy`
+2. Set repo to archived/read-only
+3. Rename `wraith` to `wraith`
+4. Update auto-updater endpoint in tauri.conf.json to new repo path
+5. Delete old Gitea packages (Go-built versions)
+
+### 6. Clean Up Local
+```bash
+# Remove old Go repo (keep backup if desired)
+mv ~/repos/wraith ~/repos/wraith-go-legacy-backup
+mv ~/repos/wraith ~/repos/wraith
+```
+
+## What Was NOT Migrated
+
+| Component | Reason |
+|---|---|
+| AI Copilot (8 Go files + 4 Vue files) | Claude Code over SSH replaces this |
+| MobaXTerm importer | 6 connections — entered by hand |
+| Plugin system | Not needed |
+| Go test suite (90 tests) | Replaced by 52 Rust tests |
+| wraith.db data | Fresh vault, fresh credentials |
diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json
index 5b44e48..1e579b6 100644
--- a/src-tauri/tauri.conf.json
+++ b/src-tauri/tauri.conf.json
@@ -44,7 +44,7 @@
   "plugins": {
     "updater": {
       "endpoints": [
-        "https://git.command.vigilcyber.com/api/v1/repos/vstockwell/wraith-v2/releases/latest"
+        "https://git.command.vigilcyber.com/api/v1/repos/vstockwell/wraith/releases/latest"
       ],
       "windows": {
         "installMode": "passive"