# CLAUDE.md — Archipelago (Archy)

Archipelago is a **Bitcoin Node OS** — bootable, self-sovereign personal server. Flash to USB, install on hardware, manage via web UI.

**Stack**: Rust backend + Vue 3 + TypeScript (strict) + Vite 7 + Tailwind + Pinia + Podman on Debian 13
**Version**: 1.3.0 | **Target**: x86_64 and ARM64

## Beta Freeze (2026-03-18)

Phase 1: Feature Testing (internal). Feature set is locked.
Only: bug fixes, security hardening, ISO build fixes, UI polish, testing.
Track: `docs/BETA-PROGRESS.md` | Checklist: `docs/BETA-RELEASE-CHECKLIST.md`

## Quick Reference

```bash
cd neode-ui && npm start          # Local dev (mock backend :5959, Vite :8100)
cd neode-ui && npm run build      # Build (outputs to web/dist/neode-ui/)
./scripts/deploy-to-target.sh --live  # Deploy to live server (.228)
```

## Architecture

```
Debian 13
  ├── Podman (rootless, user archipelago)
  ├── Nginx (80/443 → backend, app proxies)
  ├── Rust Backend (core/) on 127.0.0.1:5678
  └── Vue.js UI (neode-ui/)
```

**Data paths**: `/var/lib/archipelago/{app-id}/` (data), `/opt/archipelago/web-ui/` (frontend), `/usr/local/bin/archipelago` (binary)

## Critical Rules

1. Do not build Rust on macOS — deploy script handles cross-compilation via rsync + remote build.
2. Always deploy after changes — `./scripts/deploy-to-target.sh --live`
3. Frontend builds to `web/dist/neode-ui/` — not `neode-ui/dist/`
4. Container images: `scripts/image-versions.sh` is the single source of truth. All scripts use `$*_IMAGE` variables, not hardcoded registry paths.
5. Type-check before committing — `cd neode-ui && npx vue-tsc -b --noEmit`

## App Integration Checklist

When adding/fixing apps, check all of these:
- `core/archipelago/src/api/rpc/package/` — config, capabilities, deps
- `neode-ui/src/views/marketplace/marketplaceData.ts` — marketplace entry
- `image-recipe/configs/nginx-archipelago.conf` — proxy rules (HTTP + HTTPS)
- `scripts/image-versions.sh` — pinned image version
- `scripts/first-boot-containers.sh` — first boot creation
- `scripts/deploy-to-target.sh` — deploy logic

## Git

Commits: `type: description` (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`, `perf:`)
Push to: `git push tx1138 main`

## Compact Instructions

When compacting, preserve: list of modified files, test results, deploy target state, current branch, infrastructure IPs.