proxcli 0.13.2__tar.gz → 0.15.0__tar.gz

{proxcli-0.13.2 → proxcli-0.15.0}/.github/workflows/ci.yml

@@ -3,6 +3,7 @@ name: CI
 on:
   push:
     branches: [main]
+    tags-ignore: ["v*"]
   pull_request:
     branches: [main]
   release:

{proxcli-0.13.2 → proxcli-0.15.0}/.gitignore

@@ -24,3 +24,9 @@ coverage.xml
 
 # Rust cache
 .ruff_cache/
+
+# Website build artifacts (node_modules are in docs/website/)
+docs/website/node_modules/
+docs/website/remotion-demos/node_modules/
+# Built docs subdir (markdown copies for the docs site)
+docs/docs/

{proxcli-0.13.2 → proxcli-0.15.0}/CHANGELOG.md

@@ -5,7 +5,72 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.15.0] - 2026-06-30
+
+### Added
+- **``proxmox vm set``**: update VM configuration keys. Wraps
+  ``PUT /nodes/{node}/qemu/{vmid}/config``. Supports ``--ipconfig0``–``--ipconfig3``,
+  ``--ciuser``, ``--cipassword``, ``--sshkeys``, ``--nameserver``,
+  ``--searchdomain``, ``--cicustom``, and arbitrary ``--option key=value`` pairs.
+  Complements ``vm clone`` and ``vm template`` for full cloud-init template workflows.
+- **``proxmox api``**: make raw authenticated API calls for endpoints not yet
+  covered by dedicated subcommands. Supports ``GET``, ``POST``, ``PUT``, ``DELETE``
+  with ``--data`` (inline JSON), ``--data-file`` (JSON file), or stdin piping.
+  Reuses the same authentication as the rest of proxcli — no more ``curl`` with
+  manual tokens.
+
+### Changed
+- **Docs deduplication**: ``docs/*.md`` is now the single source of truth.
+  Removed ``docs/website/public/docs/`` (stale duplicate) and the ``copyDocsPlugin``
+  from ``vite.config.js``. Added ``serveDocsPlugin`` middleware for dev mode.
+- **``docs/cloud-init.md``**: added "Reusable Cloud-Init Template" guide covering
+  the full workflow (upload → create → template → clone → customize) entirely
+  with proxcli commands.
+- **``docs/production-automation.md``**: replaced curl-based template conversion
+  with ``proxmox vm template``.
+- **``docs/quickstart.md``**: added "Raw API calls" section.
+
+## [0.14.0] - 2026-06-22
+
+### Added
+- **``proxmox vm clone``**: clone a QEMU VM to a new VMID. Supports ``--newid``
+  (required), ``--node``, ``--name``, ``--target-node``, ``--target-storage``,
+  ``--full`` (1=full, 0=linked), ``--description``, and ``--pool``.
+- **``proxmox vm migrate``**: migrate a QEMU VM to another node. Supports
+  ``--target`` (required), ``--node``, ``--online`` (live migration),
+  ``--with-local-disks``, and ``--target-storage``.
+- **``proxmox backup restore``**: restore a backup to a new VM or container.
+  Supports ``--vmid`` (required), ``--node``, ``--storage``, ``--unique``
+  (unique MACs/IDs), ``--pool``, and ``--start``. Auto-detects guest type
+  (qemu vs lxc) from the backup volume ID.
+- **``proxmox vm template``**: convert a VM into a template. Wraps
+  ``POST /nodes/{node}/qemu/{vmid}/template``.
+- **``proxmox vm iso attach/detach``**: attach or eject an ISO image from
+  a VM's virtual CD/DVD drive. ``attach --iso-volume`` accepts a full volid
+  or a bare filename (auto-resolved across node storages).
+- **``proxmox vm ip <vmid>``**: quick IP address lookup via guest agent.
+  Returns interface name, IP, and prefix; filters out loopback and
+  link-local addresses.
+- **``proxmox container ip <vmid>``**: IP address lookup for LXC containers.
+  Wraps ``GET /nodes/{node}/lxc/{vmid}/interfaces``, extracting inet/inet6
+  addresses; filters loopback and link-local.
+- **``proxmox vm disk resize``**: resize a VM disk. Wraps
+  ``PUT /nodes/{node}/qemu/{vmid}/resize`` with ``--disk`` and ``--size``.
+- **``proxmox vm agent`` new subcommands**: ``osinfo`` (guest OS details),
+  ``fsinfo`` (filesystem info), ``users`` (user accounts), and ``exec``
+  (execute a command inside the guest with base64 I/O decoding and result
+  polling).
+- **``proxmox vm disk detach/remove``**: detach (keep data) or remove
+  (delete image) a disk from a VM. Wraps ``PUT /nodes/{node}/qemu/{vmid}/config``.
+- **``proxmox task wait <upid>``**: block until a task completes. Polls
+  task status at configurable ``--poll`` intervals with ``--timeout``.
+
+### Fixed
+- **Test suite**: all 102 tests now pass reliably. Root cause was the `.venv`
+  referencing the old project path (`proxmox-cli` -> `proxcli`), causing
+  `pytest-httpx` plugin not to load and subprocess tests to fail with
+  `PackageNotFoundError`. Fixed by reinstalling dev dependencies into the
+  current `.venv` and re-registering the editable install.
 
 ## [0.13.1] - 2026-06-21
 
@@ -268,6 +333,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CSRF ticket auto-refresh on 401.
 - AI-agent-friendly: default JSON output, strict exit codes, `--dry-run` mode.
 
+[0.15.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.15.0
+[0.14.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.14.0
+[0.13.1]: https://github.com/xezpeleta/proxcli/releases/tag/v0.13.1
+[0.13.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.13.0
+[0.12.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.12.0
+[0.11.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.11.0
 [0.10.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.10.0
 [0.9.1]: https://github.com/xezpeleta/proxcli/releases/tag/v0.9.1
 [0.9.0]: https://github.com/xezpeleta/proxcli/releases/tag/v0.9.0

{proxcli-0.13.2 → proxcli-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxcli
-Version: 0.13.2
+Version: 0.15.0
 Summary: A CLI tool to interact with Proxmox VE nodes and clusters via the REST API
 Author-email: Xabi Ezpeleta <xezpeleta@gmail.com>
 License: MIT

proxcli-0.15.0/TODO.md

@@ -0,0 +1,213 @@
+# TODO
+
+Planned improvements for future releases. Items are roughly ordered by priority.
+
+Completed items are marked with a check. Implementation notes are preserved for context.
+
+---
+
+## ✅ Done
+
+- [x] **Firewall management** — cluster, node, VM, and container. Options, enable/disable, policy, rules (CRUD), aliases (cluster), ipsets with CIDR mgmt (cluster), refs.
+- [x] **Pool management** — `proxmox pool`: list, show, create, update, delete. Wraps `/pools`.
+- [x] **Shell completions** — `proxmox completion bash|zsh|fish`. Dynamic, introspects the parser tree.
+- [x] **VM snapshot management** — `proxmox vm snapshot`: list, create, show, rollback, delete. Wraps `/nodes/{node}/qemu/{vmid}/snapshot`.
+- [x] **QEMU guest agent interfaces** — `proxmox vm agent interfaces <vmid>`. Wraps `/nodes/{node}/qemu/{vmid}/agent/network-get-interfaces`.
+- [x] **Streaming task logs** — `proxmox task log <upid> [--follow]`. Polls `/nodes/{node}/tasks/{upid}/log`.
+- [x] **Global flag hint** — If user places `--output` / `--dry-run` / etc. after the resource, a hint suggests the correct order.
+- [x] **User & permission management** — `proxmox user` (list/show/create/update/delete), `proxmox role` (list/show/create/update/delete), `proxmox acl` (list/show/add/delete). Wraps `/access/users`, `/access/roles`, `/access/acl`. ACL write requires `Permissions.Modify` (Administrator).
+- [x] **VM cloud-init support** — `vm create` flags for citype, ciuser, cipassword, sshkeys, nameserver, searchdomain, cicustom + auto cloud-init drive creation. `vm cloudinit generate` for regeneration.
+- [x] **VM disk import** — `vm create --import-from <storage:path>` imports an existing disk image as VM boot disk.
+- [x] **Docs** — `docs/cloud-init.md` (cloud-init VM workflow), `docs/api-permissions.md` (minimum API privileges).
+- [x] **Network management** — `proxmox network` (list, show). Wraps `/nodes/{node}/network[/{iface}]`. Shows bridges, bonds, VLANs, physical NICs with config details. Type filtering support.
+- [x] **Backup (vzdump) management** — `proxmox backup` (list/show/create/delete/tasks/defaults). Wraps `/nodes/{node}/vzdump` and storage content endpoints. Supports snapshot/suspend/stop modes, compression, PBS.
+- [x] **Ceph & disk management** — `proxmox ceph` (status, osd, log, disks). Cluster health, OSD-to-disk mapping, wearout tracking, Ceph logs.
+- [x] **Config loader made read-only** — `auth login`/`auth clear` removed. `PROXMOX_CONFIG_DIR` env var for custom config path.
+- [x] **Node system info** — `proxmox node subscription/dns/time/services/pci/netstat/config`. Read-only node inspection.
+- [x] **Cluster log & options** — `proxmox cluster log [--limit N]` and `proxmox cluster options`.
+- [x] **Storage status** — `proxmox storage status <storage> [--node]` for usage stats.
+- [x] **API coverage doc** — `docs/api-coverage.md` tracking all implemented and remaining endpoints.
+
+## v1.1 — Polish & Usability
+
+- [x] **`--output table` column selection**
+  - ``proxmox --output table --columns vmid,name,status vm list`` picks which columns appear.
+
+- [x] **Color support in table output**
+  - Status/state values are styled: green for running/active/ok, red for stopped/error, yellow for paused/suspended.
+
+---
+
+## v1.2 — VM & Container Lifecycle Gaps
+
+High-impact VM/container workflows that exist in the Proxmox API but are missing from the CLI. Ordered by user value.
+
+### Priority: HIGH
+
+- [x] **VM clone**
+  - `proxmox vm clone <vmid> --newid <id> [--name <name>] [--target-node <node>] [--target-storage <storage>] [--full] [--description <text>]`
+  - Wraps `POST /nodes/{node}/qemu/{vmid}/clone`
+  - Cloning from templates or golden images is a core homelab/admin workflow.
+  - From piclaw: `vm.clone` workflow covers full/linked clone, target node/storage, optional description.
+
+- [x] **VM migrate**
+  - `proxmox vm migrate <vmid> --target <node> [--target-storage <storage>] [--online] [--with-local-disks]`
+  - Wraps `POST /nodes/{node}/qemu/{vmid}/migrate`
+  - Moving VMs between nodes is essential for maintenance and load balancing.
+  - From piclaw: `vm.migrate` workflow with online flag and local disk migration.
+
+- [x] **Backup restore**
+  - `proxmox backup restore <volid> --vmid <id> [--node <node>] [--storage <storage>] [--target-storage <storage>]`
+  - Wraps `POST /nodes/{node}/storage/{storage}/content` with archive restore.
+  - Currently proxcli can create/list/delete backups but not restore them — a glaring asymmetry.
+  - From piclaw: `backup.restore` workflow.
+
+### Priority: MEDIUM
+
+- [x] **VM template (convert to template)**
+  - `proxmox vm template <vmid> [--node <node>]`
+  - Wraps `POST /nodes/{node}/qemu/{vmid}/template`
+  - Small addition but unlocks the clone-from-template workflow.
+  - From piclaw: `vm.template.create` workflow.
+
+- [x] **VM ISO attach / detach**
+  - `proxmox vm iso attach <vmid> --iso-volume <volid> [--slot ide2] [--node <node>]`
+  - `proxmox vm iso detach <vmid> [--slot ide2] [--node <node>]`
+  - Wraps `PUT /nodes/{node}/qemu/{vmid}/config` with cdrom slot changes.
+  - Exposing this as first-class actions is much more intuitive than raw config editing.
+  - From piclaw: `vm.iso.attach` and `vm.iso.detach` workflows.
+
+- [x] **VM IP quick-lookup**
+  - `proxmox vm ip <vmid> [--node <node>]`
+  - Combines guest agent network-get-interfaces (already implemented) into a one-shot "give me the IPs" command. Filter out loopback/link-local.
+  - From piclaw: `vm.ip` and `lxc.ip` workflows.
+
+- [x] **LXC IP quick-lookup**
+  - `proxmox container ip <vmid> [--node <node>]`
+  - Wraps `GET /nodes/{node}/lxc/{vmid}/interfaces`, extracting IPv4/IPv6 addresses.
+  - From piclaw: `lxc.ip` workflow.
+
+### Priority: LOW
+
+- [x] **VM disk resize**
+  - `proxmox vm disk resize <vmid> --disk <disk> --size <+N or N> [--node <node>]`
+  - Wraps `PUT /nodes/{node}/qemu/{vmid}/resize`.
+  - From piclaw: `vm.disk.resize` workflow.
+
+- [x] **VM disk detach / remove**
+  - `proxmox vm disk detach <vmid> --disk <disk> [--node <node>]`
+  - `proxmox vm disk remove <vmid> --disk <disk> [--force] [--node <node>]`
+  - From piclaw: `vm.disk.detach` and `vm.disk.remove` workflows.
+
+- [x] **VM guest agent exec**
+  - `proxmox vm agent exec <vmid> --command <cmd> [--args ...] [--input-data ...] [--shell posix|powershell]`
+  - Extend the existing `vm agent` subcommand with an `exec` sub-action.
+  - Wraps `POST /nodes/{node}/qemu/{vmid}/agent/exec` + polling for result.
+  - From piclaw: `vm.agent.exec` workflow. Bounded command execution with base64 I/O decoding.
+
+- [x] **VM guest agent OS info / FS info / users**
+  - `proxmox vm agent osinfo <vmid>` — `GET /nodes/{node}/qemu/{vmid}/agent/get-osinfo`
+  - `proxmox vm agent fsinfo <vmid>` — `GET /nodes/{node}/qemu/{vmid}/agent/get-fsinfo`
+  - `proxmox vm agent users <vmid>` — `GET /nodes/{node}/qemu/{vmid}/agent/get-users`
+  - From piclaw: `vm.agent.osinfo`, `vm.agent.fsinfo`, `vm.agent.users` workflows.
+
+- [x] **Task wait (blocking poll)**
+  - `proxmox task wait <upid> [--timeout <ms>] [--poll <ms>]`
+  - Polls task status until completion, useful in scripts. pixlaw has both `task.wait` and `vm.wait_state`.
+
+---
+
+## v1.3 — Metrics & Monitoring
+
+The piclaw proxmox addon has a rich `metrics.*` workflow family. proxcli has zero metrics support. This would be a killer feature for a CLI.
+
+- [ ] **`proxmox metrics` top-level subcommand**
+  - Wraps the RRD data API endpoints (`/nodes/{node}/rrddata`, `/nodes/{node}/qemu/{vmid}/rrddata`, `/nodes/{node}/storage/{storage}/rrddata`).
+  - Common flags: `--timeframe hour|day|week|month|year` (default: `hour`), `--cf AVERAGE|MAX` (default: `AVERAGE`).
+
+- [ ] **`proxmox metrics node <node> [--metric <name>]`**
+  - Pulls node-level RRD series: CPU, memory, disk, network, load, etc.
+
+- [ ] **`proxmox metrics vm <vmid> [--node <node>] [--metric <name>]`**
+  - Pulls VM-level RRD series for a specific guest.
+
+- [ ] **`proxmox metrics storage <storage> --node <node> [--metric <name>]`**
+  - Pulls storage usage metrics over time.
+
+- [ ] **Metrics output: chart / CSV / JSON**
+  - `--output chart` could render a simple ASCII/Unicode sparkline in the terminal.
+  - `--output csv` for data export into external tools.
+  - `--output json` for programmatic consumers.
+
+- [ ] **Guest comparison chart** (inspired by piclaw skill `proxmox-guest-compare-chart`)
+  - A `proxmox compare` or `proxmox metrics compare` subcommand that fetches RRD series for two guests and renders an SVG chart or terminal comparison table.
+  - The piclaw skill uses a Bun script to render SVG/CSV/JSON from normalized input — we could do this purely in Python.
+
+---
+
+## v1.4 — Storage Gaps
+
+- [ ] **Storage create**
+  - `proxmox storage create <name> --type <type> [--config key=value ...]`
+  - Wraps `POST /storage`. Supports dir, nfs, lvmthin, zfspool, etc.
+  - From piclaw: `storage.create` workflow. Config fields passed as a flat dict for backend-specific options.
+
+- [ ] **Storage download-url** (server-side pull)
+  - `proxmox storage download-url --node <node> --storage <storage> --url <url> --filename <name> [--content iso|vztmpl|import] [--checksum <sha256:...>] [--verify-tls]`
+  - Wraps `POST /nodes/{node}/storage/{storage}/download-url`.
+  - Lets you pull ISOs/templates directly into storage without agent-side upload.
+  - From piclaw: `storage.download_url` workflow with checksum verification.
+
+---
+
+## v1.5 — Resource Coverage (existing TODO)
+
+- [ ] **SDN (Software-Defined Networking)**
+  - `proxmox sdn` subcommand: `zones`, `vnets`, `subnets`. Wraps `/cluster/sdn/*` endpoints.
+
+- [ ] **HA (High Availability)**
+  - `proxmox ha` subcommand: `status`, `groups`, `resources`. Wraps `/cluster/ha/*` endpoints.
+
+- [ ] **Node syslog**
+  - `proxmox node log <node> [--limit N]`
+  - Wraps `GET /nodes/{node}/syslog`. Read node-level syslog entries (currently only `ceph log` exists).
+
+---
+
+## v2.0 — Multi-Cluster & Advanced
+
+- [ ] **Multi-profile / multi-cluster support**
+  - Support `--profile <name>` global flag to switch between multiple saved Proxmox endpoints. Config file format extended from single endpoint to a profiles dict. `proxmox auth login --profile homelab` and `proxmox auth login --profile work` coexist.
+
+- [ ] **Batch / bulk operations**
+  - `proxmox vm start --all-on-node pve01` (start all VMs on a node). `proxmox vm snapshot --vmid 100,101,102` (apply to multiple IDs).
+
+- [x] **Config file templating**
+  - ``vm create --file spec.yaml`` for declarative VM specs.  File format
+    mirrors the native Proxmox VM config (flat key-value: ``name``,
+    ``memory``, ``cores``, ``net0``, ``scsi0``, ``ciuser``, etc.).
+  - ``vm show <id> --output yaml`` exports existing VM config in the
+    same flat format (strips internal fields like ``digest``, ``vmgenid``).
+    Export → edit → recreate loop.
+
+- [ ] **Plugin system for custom commands**
+  - Allow users to extend the CLI with custom subcommands via a plugins directory.
+
+- [ ] **Dry-run diff mode**
+  - `--dry-run` that shows what *would change* on the Proxmox side (e.g., before/after VM config diff) rather than just the HTTP request.
+
+---
+
+## Ideas (not yet scheduled)
+
+- [ ] **Interactive mode / TUI**
+  - A `proxmox tui` command that opens a terminal UI (like `htop` but for Proxmox resources). Low priority — the CLI is designed for automation first.
+
+- [ ] **Webhook / event listener**
+  - Subscribe to Proxmox cluster events and pipe them to a webhook or stdout for external monitoring.
+
+- [ ] **Proxmox Backup Server (PBS) integration**
+  - Separate subcommand or a companion tool (`proxbackup`?) for managing PBS instances via their API.
+
+- [ ] **Terraform / Pulumi bridge**
+  - Export current Proxmox state as Terraform HCL or Pulumi Python/TypeScript, enabling import into IaC.

proxcli-0.15.0/docs/DESIGN.md

@@ -0,0 +1,165 @@
+---
+name: proxcli
+version: "1.0"
+colors:
+  primary: "#0F172A"
+  secondary: "#334155"
+  tertiary: "#3B82F6"
+  on-tertiary: "#FFFFFF"
+  surface: "#F8FAFC"
+  surface-variant: "#E2E8F0"
+  on-surface: "#1E293B"
+  border: "#CBD5E1"
+  muted: "#94A3B8"
+  success: "#10B981"
+  warning: "#F59E0B"
+  error: "#EF4444"
+  code-bg: "#1E293B"
+  code-fg: "#E2E8F0"
+typography:
+  heading:
+    fontFamily: "Inter, system-ui, sans-serif"
+    fontWeight: 700
+  body:
+    fontFamily: "Inter, system-ui, sans-serif"
+    fontWeight: 400
+  mono:
+    fontFamily: "'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace"
+    fontWeight: 400
+  label-caps:
+    fontFamily: "Inter, system-ui, sans-serif"
+    fontWeight: 600
+    letterSpacing: "0.05em"
+rounded:
+  sm: 4px
+  md: 8px
+  lg: 12px
+  xl: 16px
+  full: 9999px
+spacing:
+  xs: 4px
+  sm: 8px
+  md: 16px
+  lg: 24px
+  xl: 32px
+  "2xl": 48px
+  "3xl": 64px
+  "4xl": 96px
+components:
+  button-primary:
+    backgroundColor: "{colors.tertiary}"
+    textColor: "{colors.on-tertiary}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.sm} {spacing.lg}"
+    typography: "{typography.label-caps}"
+  button-primary-hover:
+    backgroundColor: "#2563EB"
+  code-block:
+    backgroundColor: "{colors.code-bg}"
+    textColor: "{colors.code-fg}"
+    rounded: "{rounded.lg}"
+    padding: "{spacing.lg}"
+  hero-section:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.on-tertiary}"
+  card:
+    backgroundColor: "{colors.surface}"
+    borderColor: "{colors.border}"
+    rounded: "{rounded.lg}"
+    padding: "{spacing.lg}"
+---
+
+## Overview
+
+**proxcli** is a developer-first CLI tool for Proxmox VE infrastructure.
+The visual identity balances terminal minimalism with modern SaaS polish —
+dark slate foundation, a single electric-blue accent, and crisp monospaced
+code surfaces.
+
+The brand sits at the intersection of **infrastructure professionalism**
+and **developer joy**. Clean, confident, utilitarian — but never cold.
+The blue accent (`#3B82F6`) provides the energy and forward momentum
+of a tool that makes infrastructure feel fast, responsive, and under
+control.
+
+## Colors
+
+- **Primary (`#0F172A`):** Deep navy-slate. Used for hero sections,
+  the nav bar, and as a grounding dark surface. Conveys infrastructure
+  seriousness and reliability.
+- **Secondary (`#334155`):** Medium slate. Used for subheadings,
+  muted text on light backgrounds, and secondary UI chrome.
+- **Tertiary (`#3B82F6`):** Electric blue. The sole interactive accent —
+  buttons, links, active states, code highlights. High-energy without
+  being aggressive. Hover darkens to `#2563EB`.
+- **Surface (`#F8FAFC`):** Near-white with a hint of cool gray. Primary
+  page background. Softer than pure white for long-form reading.
+- **Surface variant (`#E2E8F0`):** Light gray for alternating sections,
+  card borders, and subtle visual separation.
+- **Code background (`#1E293B`):** Dark slate for code blocks and
+  terminal emulation. Paired with off-white `#E2E8F0` for code text.
+
+## Typography
+
+- **Headings:** Inter, bold weight. Clean and geometric for section
+  titles. Large sizes (`4xl`, `3xl`, `2xl`) for hero and section heads.
+- **Body:** Inter, regular weight. Optimized for screen reading at
+  `16px` base size (1rem).
+- **Mono:** JetBrains Mono for all code, terminal output, and
+  command examples. Fallback stack: Fira Code → Cascadia Code → monospace.
+- **Label/Caps:** Inter Semibold with 0.05em letter-spacing for button
+  text, badges, and navigation items.
+
+## Layout
+
+- **Max content width:** 1280px centered, with generous horizontal
+  padding (`2xl`) on wider screens.
+- **Sections stack vertically** with `3xl` or `4xl` spacing between them.
+- **Two-column grids** for feature cards, comparison tables, and
+  use-case highlights.
+- **Terminal/Code blocks** are full-width within content, with
+  `lg` rounded corners and `lg` internal padding.
+
+## Elevation & Depth
+
+- Flat design with minimal shadow usage. Cards use a 1px border
+  instead of box-shadow to maintain a crisp, editor-like aesthetic.
+- Code blocks sit on the dark `code-bg` surface with no shadow —
+  they feel "cut into" the page.
+- Only the sticky navigation bar gets a subtle shadow on scroll.
+
+## Shapes
+
+- All interactive elements use `md` border radius (8px).
+- Code blocks and terminal surfaces use `lg` (12px).
+- Buttons use `md` (8px) — rounded enough to feel modern but not pill-shaped.
+- Full-radius (`full`) reserved for badges and tags.
+
+## Components
+
+- **button-primary:** Electric blue background with white text, Inter semibold.
+  Hover darkens to `#2563EB`. Used for primary CTAs.
+- **code-block:** Dark slate surface (`#1E293B`) with off-white monospaced text.
+  Used for all command examples, terminal output, and YAML samples.
+- **hero-section:** Full-width dark slate background with centered white text.
+  Features the proxcli logo/title, a one-line value prop, and a "Get Started"
+  button.
+- **card:** White surface with a subtle border, rounded corners, and internal
+  padding. Used for feature tiles and documentation sections.
+
+## Do's and Don'ts
+
+### Do
+- Use the single accent (`#3B82F6`) sparingly for interactive elements only
+- Keep code examples concise — show the command and its output
+- Use Inter for all prose, JetBrains Mono for all code
+- Maintain generous whitespace around sections for readability
+- Use the dark hero to ground the page immediately on landing
+
+### Don't
+- Don't introduce additional colors beyond the defined palette
+- Don't use box-shadows on cards — use borders instead
+- Don't use the accent color for non-interactive text
+- Don't clump multiple code blocks without prose between them
+- Don't use the dark surface (`#0F172A`) for large text blocks —
+  it's reserved for hero sections and navigation