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` |
| **Public cW\* mesh read tooling (`engine-kofi`)** | Gitea `https://gitea.d-bis.org/DBIS/engine-kofi.git` — read-only `mesh-snapshot` / `compare` / Infura gas; set `PROXMOX_ROOT` to this repo for deployment graph |
| Master reference — token / stablecoin launch (“Bible from Nathan”) | `docs/00-meta/BIBLE_FROM_NATHAN_TOKEN_LAUNCH_RESOURCE_COMPENDIUM.md` — cross-cutting institutional compendium (regulation, custody, banking, tooling, audits, listings, checklists); use with Chain 138 canonicals below |
| Master reference — MetaMask Money/mUSD ↔ GRU, provider cross-links, DefiLlama DODO `dfio_meta_main` TVL | `docs/00-meta/METAMASK_GRU_DEFILLAMA_CHAIN138_MASTER_REFERENCE.md` — replay steps, doc cross-links, DefiLlama-Adapters fork/PR **#19198**, touchpoints JSON maintenance |
| DefiLlama ↔ Chain 138 (TVL + optional metrics) | `docs/04-configuration/defillama/CHAIN138_DEFILLAMA_ECOSYSTEM_MAP.md`, `config/defillama-chain138-touchpoints.json`; methodology hub [docs.llama.fi](https://docs.llama.fi/) |
| Optional Cosmos / IBC / Noble / Osmosis / CosmWasm → Chain 138 | `docs/11-references/COSMOS_ECOSYSTEM_CHAIN138_OPTIONAL_INTEGRATIONS_RUNBOOK.md` (streams A–E); templates `config/cosmos-chain138-optional/`; **gaps audit** `docs/11-references/COSMOS_CHAIN138_GAPS_AND_INCONSISTENCIES.md` |
| Canonical ecosystem master plan | `docs/02-architecture/DBIS_ECOSYSTEM_TECHNICAL_MASTER_PLAN.md` — umbrella root; subordinate roots: `dbis_chain_138_technical_master_plan.md`, `docs/03-deployment/DBIS_RTGS_MASTER_PLAN_IMPLEMENTATION_TRACKER.md`, `docs/04-configuration/universal-resource-activation/URA_MANIFEST_AUTOMATION_IMPLEMENTATION_TRACKER.md` |
| Treasury / EMI / wallet / VA master plan | `docs/02-architecture/GOVERNMENT_TREASURY_EMI_WALLET_MASTER_PLAN.md` — government treasury, EMIs, digital wallets, virtual accounts (incl. Tatum-style), Rail vs RTGS gates |
| Universal resource activation (manifest, CI, Phoenix) | `UNIVERSAL_RESOURCE_WIRING.md`, `URA_MANIFEST_AUTOMATION_IMPLEMENTATION_TRACKER.md`, `URA_OPERATIONAL_READINESS_CHECKLIST.md` (under `docs/04-configuration/universal-resource-activation/`); `config/universal-resource-activation/{manifest.json,policy-profiles.json,integration/}`; `pnpm ura:ops-readiness` / `ura:ops-readiness:full`, `ura:production-ready` / `ura:production-ready:connectivity`, `ura:validate`, `ura:validate-profiles`, `ura:merge-manifest`, `ura:validate-ledger-mapping`, `ura:writer:ledger`, `ura:writer:settlement`, `ura:profile-hash`, `ura:validate-closure`, `ura:keccak`, `ura:smoke`; `URA_STRICT_CLOSURE` / Gitea `vars.URA_STRICT_CLOSURE`; `smom-dbis-138/contracts/universal-resource/PolicyProfileRegistry.sol` (scoped forge test); Phoenix `PUBLIC_V1_NO_PARTNER_KEY_PATHS` |
| Multi-jurisdiction compliance (matrices, onboarding) | `docs/04-configuration/compliance-matrices/README.md`, `INSTITUTION_ONBOARDING_CHARTER.md`, `INSTITUTION_ONBOARDING_PLAYBOOK.md`, `docs/04-configuration/jurisdictions/JURISDICTION_CATALOG.md`, `config/jurisdictions/catalog.v1.json`, `docs/dbis-rail/DBIS_RAIL_JURISDICTION_TRACEABILITY.md`, `docs/03-deployment/DBIS_RTGS_MASTER_PLAN_IMPLEMENTATION_TRACKER.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` |
| Live guest inventory + IPAM drift (LAN, seed **r630-01**) | `bash scripts/it-ops/export-live-inventory-and-drift.sh` → `reports/status/live_inventory.json`, `reports/status/drift.json` (exit **2** only on duplicate guest IPs). Collector parses QEMU **`ipconfig*`** and LXC **`net*`** via `scripts/lib/proxmox_guest_lan_ips.py`. |
| 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), **`runs-on: ubuntu-latest-heavy`** (CT **5700**). After deploy, optional **Cloudflare** `cloudflare-sync` (Phoenix + `PHOENIX_REPO_ROOT`; set `PHOENIX_CLOUDFLARE_SYNC=1` on that host) via `scripts/deployment/gitea-cloudflare-sync.sh`. 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 …]` |
| Gitea Actions runners (heavy vs standard pool) | `docs/04-configuration/GITEA_ACT_RUNNER_SETUP.md` — **5700** `ubuntu-latest-heavy`, **5701** `ubuntu-latest`; apply configs `bash scripts/dev-vm/apply-act-runner-config.sh`; snapshot `bash scripts/dev-vm/act-runner-resource-snapshot.sh` |
| 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` |
| Gov Portals (CT **7804** @ `IP_GOV_PORTALS_DEV`, r630-04): rebase from Gitea then build + sync | `./scripts/deployment/gov-portals-git-pull-rebase.sh` then `./scripts/deployment/sync-gov-portals-ct-7804-from-git.sh` — `GITEA_TOKEN` in `.env`; sync defaults to **pull --rebase** (use `--reset-hard` to mirror Gitea and discard local changes); optional `--skip-fetch`. Source-of-truth and Phoenix paths: `docs/04-configuration/GITEA_GOV_PORTALS_LIVE_SOURCE_OF_TRUTH.md`; ops template: `docs/04-configuration/GOV_PORTALS_XOM_DEV_DEPLOYMENT.md`. Optional Gitea tag: `scripts/deployment/gitea-tag-repo-release.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) |
| Solana native SOL (robust JSON-RPC submit) | `scripts/lib/solana_jsonrpc.py` (stdlib `sendTransaction`), `./scripts/deployment/solana-transfer-native.py` (sign with `solders`). Install: `pip install -r scripts/lib/requirements-solana-ops.txt`. Avoids solana-py `SendTransactionResp` parse failures on RPCs that return only a signature string. Env: `SOLANA_RPC_URL`, `SOLANA_KEYPAIR_PATH` via `source scripts/lib/load-project-env.sh`. |
| 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` |
| **EI matrix → mainnet cWUSDC transfer** | `./scripts/deployment/send-cwusdc-ei-matrix-wallets.sh` — `transfer` from signer to grid slice (`--send-raw` / `--total-send-raw`); resume: `continue-cwusdc-ei-matrix-wallets.sh`. |
| **EI matrix top-up TSV from audit** | `scripts/verify/build-ei-matrix-cwusdc-topup-tsv-from-audit-json.sh` — rebuilds `ei-matrix-cwusdc-topup-*.tsv` from `ei-matrix-readiness-audit-latest.json`. |
| **EI matrix → Multicall3 cWUSDC (preferred)** | `./scripts/deployment/send-cwusdc-ei-matrix-multicall-batches.sh` — Multicall3 `aggregate3` + `transferFrom`; `EI_MATRIX_MC_CHUNK` (default 200). Core: `scripts/lib/ei_matrix_multicall3_cwusdc_batch.py`. Fallback: `send-cwusdc-ei-matrix-targeted.sh` (1 tx/wallet). Pipeline: `pipeline-ei-matrix-remediate-cwusdc-from-audit.sh --multicall`. |
| **EI matrix → mainnet cWUSDC mint** | `./scripts/deployment/pipeline-ei-matrix-mint-cwusdc.sh` — mints `CWUSDC_MAINNET` to each wallet in `config/pmm-soak-wallet-grid.json` (see `docs/03-deployment/EI_MATRIX_CWUSDC_MINT_PIPELINE.md`). Core: `mint-cwusdc-ei-matrix-wallets.sh`; resume: `continue-mint-cwusdc-ei-matrix-wallets.sh`. Not a 138 bridge. |
| **EI matrix on-chain readiness (cWUSDC / 138 cUSDC)** | `./scripts/verify/run-ei-matrix-full-readiness-audit.sh` — full grid, sharded (`--shard-size`, env `EI_MATRIX_AUDIT_*`), writes JSON + gap index files. Ad hoc: `./scripts/verify/audit-ei-matrix-onchain-readiness.sh`. Optional CI: `EI_MATRIX_ONCHAIN_AUDIT_CI=1` in `scripts/verify/run-all-validation.sh`. Core: `scripts/lib/ei_matrix_onchain_readiness_audit.py`. |
| 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`) |
| Remote SSH to dev VM (5700 / `192.168.11.59`) for runner & deploy API | [DEV_VM_SSH_REMOTE_ACCESS.md](docs/04-configuration/DEV_VM_SSH_REMOTE_ACCESS.md); **move workstation `~/projects` → Dev VM:** [DEV_VM_WORKSTATION_MIGRATION_RUNBOOK.md](docs/04-configuration/DEV_VM_WORKSTATION_MIGRATION_RUNBOOK.md), `scripts/deployment/sync-local-projects-to-dev-vm.sh` (rsync code 23 on `--delete-remote`: `scripts/deployment/fix-dev-vm-srv-projects-ownership.sh`) |
| 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`.