proxmox/AGENTS.md

Proxmox workspace — agent instructions

Single canonical copy for Cursor/Codex. (If your editor also loads .cursor/rules, treat those as overlays.)

Scope

Orchestration for Proxmox VE, Chain 138 (smom-dbis-138/), explorers, NPMplus, and deployment runbooks.

Quick pointers

Need	Location
Doc index	docs/MASTER_INDEX.md
cXAUC/cXAUT unit	1 full token = 1 troy oz Au — docs/11-references/EXPLORER_TOKEN_LIST_CROSSCHECK.md (section 5.1)
PMM mesh 6s tick	smom-dbis-138/scripts/reserve/pmm-mesh-6s-automation.sh — docs/integration/ORACLE_AND_KEEPER_CHAIN138.md (PMM mesh automation)
VMID / IP / FQDN	docs/04-configuration/ALL_VMIDS_ENDPOINTS.md
Ops template + JSON	docs/03-deployment/PROXMOX_VE_OPERATIONAL_DEPLOYMENT_TEMPLATE.md, config/proxmox-operational-template.json
Live vs template (read-only SSH)	bash scripts/verify/audit-proxmox-operational-template.sh
Config validation	bash scripts/validation/validate-config-files.sh
pnpm lockfile vs workspace (prevents pnpm outdated / importer bugs)	bash scripts/verify/check-pnpm-workspace-lockfile.sh — also run as step 1b in run-all-validation.sh
CI validation (no LAN) + cW* mesh matrix	bash scripts/verify/run-all-validation.sh [--skip-genesis] — same gate as Gitea push/PR: run-all-validation in .gitea/workflows/deploy-to-phoenix.yml (push) and .gitea/workflows/validate-on-pr.yml (PR only). Steps: dependencies, pnpm workspace/lockfile check, config, cW* mesh (when pair-discovery exists), node cross-chain-pmm-lps/scripts/validate-deployment-status.cjs, optional genesis. Manual only: bash scripts/verify/build-cw-mesh-deployment-matrix.sh [--json-out …]
FQDN / NPM E2E verifier	bash scripts/verify/verify-end-to-end-routing.sh --profile=public — inventory: docs/04-configuration/E2E_ENDPOINTS_LIST.md. Gitea Actions URLs (no API): bash scripts/verify/print-gitea-actions-urls.sh
Submodule trees clean (CI / post-merge)	bash scripts/verify/submodules-clean.sh
Submodule + explorer remotes	docs/00-meta/SUBMODULE_HYGIENE.md — mcp-proxmox uses Gitea https://gitea.d-bis.org/d-bis/mcp-proxmox.git (not the old GitHub-only URL). cross-chain-pmm-lps-publish is a worktree of cross-chain-pmm-lps, not a submodule.
smom-dbis-138 .env in bash scripts	Prefer source smom-dbis-138/scripts/lib/deployment/dotenv.sh + load_deployment_env --repo-root "$PROJECT_ROOT" (trims RPC URL line endings). From an interactive shell: source smom-dbis-138/scripts/load-env.sh. Proxmox root scripts: source scripts/lib/load-project-env.sh (also trims common RPC vars).
Sankofa portal → CT 7801 (build + restart)	./scripts/deployment/sync-sankofa-portal-7801.sh (--dry-run first); sets NEXTAUTH_URL on CT via sankofa-portal-ensure-nextauth-on-ct.sh
CCIP relay (r630-01 host)	Unit: config/systemd/ccip-relay.service → /etc/systemd/system/ccip-relay.service; systemctl enable --now ccip-relay
TsunamiSwap VM 5010 check	./scripts/deployment/tsunamiswap-vm-5010-provision.sh (inventory only until VM exists)
The Order portal (https://the-order.sankofa.nexus)	OSJ management UI (secure auth); source repo the_order at ~/projects/the_order. NPM upstream defaults to order-haproxy CT 10210 (IP_ORDER_HAPROXY:80); use THE_ORDER_UPSTREAM_* to point at the Sankofa portal if 10210 is down. Provision HAProxy: scripts/deployment/provision-order-haproxy-10210.sh. www.the-order.sankofa.nexus → 301 apex (same as www.sankofa / www.phoenix).
Portal login + Keycloak systemd + .env (prints password once)	./scripts/deployment/enable-sankofa-portal-login-7801.sh (--dry-run first)
Completable (no LAN)	./scripts/run-completable-tasks-from-anywhere.sh
smom-dbis-138 root forge test	Uses foundry.toml [profile.default] skip for legacy Uniswap V2 vendor trees (0.5/0.6 solc); scoped work still uses bash scripts/forge/scope.sh …
cWUSDT Mainnet USD pricing (on-chain + runbook)	./scripts/deployment/price-cw-token-mainnet.sh — docs/03-deployment/CW_TOKEN_USD_PRICING_RUNBOOK.md
Deployer LP balances (mesh inventory)	python3 scripts/deployment/check-deployer-lp-balances.py — scans deployment-status.json + reports/extraction/promod-uniswap-v2-live-pair-discovery-latest.json; UniV2 lpToken = pair; DODO DVM LP shares = balanceOf(pool); on failure, probes _BASE_TOKEN_ / _BASE_CAPITAL_TOKEN_ / _QUOTE_CAPITAL_TOKEN_ + extra public RPCs (--no-resolve-dodo skips; --chain-id N for one chain). JSON: lpTokenAddress, lpResolution, lpBalances[]. Use --deployer / DEPLOYER_ADDRESS if no PRIVATE_KEY
Etherscan Value $0 for Mainnet cW*	Listing path (CoinGecko/CMC), not a contract toggle — docs/04-configuration/coingecko/ETHERSCAN_USD_VALUE_MAINNET_TOKENS.md
Verify contracts on explorers (all networks)	cd smom-dbis-138 && ./scripts/deployment/verify-all-networks-explorers.sh — Blockscout 138, Etherscan + multichain cW*, Avax/Arb bridges, optional Cronos/Wemix/CCIPLogger
Operator (LAN + secrets)	./scripts/run-all-operator-tasks-from-lan.sh (use --skip-backup if NPM_PASSWORD unset; backup also needs NPM_EMAIL in .env)
Cloudflare bulk DNS → PUBLIC_IP	./scripts/update-all-dns-to-public-ip.sh — use --dry-run and --zone-only=sankofa.nexus (or d-bis.org / mim4u.org / defi-oracle.io) to limit scope; see script header. Prefer scoped CLOUDFLARE_API_TOKEN (see .env.master.example).

Git submodules

Most submodules are pinned commits; git submodule update --init --recursive often leaves detached HEAD — that is normal. To change a submodule: check out a branch inside it, commit, push the submodule first, then commit and push the parent submodule pointer. Do not embed credentials in git remote URLs; use SSH or a credential helper. Explorer Gitea vs GitHub and token cleanup: docs/00-meta/SUBMODULE_HYGIENE.md.

Rules of engagement

• Review scripts before running; prefer --dry-run where supported.
• Do not run the full operator flow when everything is healthy unless the user explicitly wants broad fixes (NPM/nginx/RPC churn).
• Chain 138 deploy RPC: http://192.168.11.211:8545 (Core). Read-only / non-deploy checks may use public RPC per project rules.

Full detail: see embedded workspace rules and docs/00-meta/OPERATOR_READY_CHECKLIST.md.