permaweb-deploy 4.0.0 → 5.0.0

package/README.md

@@ -1,361 +1,278 @@
 # Permaweb Deploy
 
-Inspired by the [cookbook github action deployment guide](https://cookbook.arweave.dev/guides/deployment/github-action.html), `permaweb-deploy` is a Node.js command-line tool designed to streamline the deployment of web applications to the permaweb using Arweave. It uploads your build folder or a single file, creates Arweave manifests, and can optionally update ArNS (Arweave Name Service) records via ANT (Arweave Name Token) with the transaction ID.
+`permaweb-deploy` uploads static sites, folders, or individual files to Arweave and can optionally update a Permaweb Name `~reference@1.0` ref value with the deployed transaction or manifest ID.
+
+The CLI uses legacy ANS-104 bundlers for the default upload path, supports HyperBEAM bundlers when selected explicitly, and publishes names updates through [`@permaweb/references`](https://www.npmjs.com/package/@permaweb/references).
+
+## Table of Contents
+
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Installation Options](#installation-options)
+- [Prerequisites](#prerequisites)
+- [CLI Usage](#cli-usage)
+- [Names Publishing](#names-publishing)
+- [Bundlers](#bundlers)
+- [Command Options](#command-options)
+- [Deduplication](#deduplication)
+- [Package Scripts](#package-scripts)
+- [GitHub Action](#github-action)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+- [Dependencies](#dependencies)
+- [License](#license)
 
 ## Features
 
-- **Turbo SDK Integration:** Uses Turbo SDK for fast, reliable file uploads to Arweave
-- **On-Demand Payment:** Pay with ARIO or Base-ETH tokens on-demand during upload
-- **Arweave Manifest v0.2.0:** Creates manifests with fallback support for SPAs
-- **Optional ArNS Updates:** Updates ArNS records via ANT with new transaction IDs and metadata
-- **Automated Workflow:** Integrates with GitHub Actions for continuous deployment
-- **Git Hash Tagging:** Automatically tags deployments with Git commit hashes
-- **404 Fallback Detection:** Automatically detects and sets 404.html as fallback
-- **Network Support:** Supports mainnet, testnet, and custom ARIO process IDs
-- **Flexible Deployment:** Supports deploying a folder or a single file
-- **Modern CLI:** Built with oclif for a robust command-line experience
-- **TypeScript:** Fully typed for better developer experience
+- **Arweave uploads:** Upload a folder or a single file.
+- **Names publishing:** Update a Permaweb Names reference-id's value after upload.
+- **Legacy bundler uploads:** Use legacy ANS-104 upload endpoints by default.
+- **HyperBEAM uploads:** Sign ANS-104 items and post them to a HyperBEAM bundler route.
+- **Arweave manifests:** Create manifest `0.2.0` documents for folder deployments, with SPA fallback detection.
+- **Dedupe cache:** Reuse unchanged uploads from `.permaweb-deploy/transaction-cache.json`.
+- **GitHub Action:** Deploy from CI and optionally update a namespace reference.
 
-## Installation
+## Quick Start
 
-Install the package using pnpm (recommended):
+Install the CLI in your project:
 
 ```bash
 pnpm add -D permaweb-deploy
 ```
 
-Or with npm:
+Make your Arweave JWK available with either `DEPLOY_KEY` or `--wallet`:
 
 ```bash
-npm install --save-dev permaweb-deploy
+export DEPLOY_KEY=$(base64 -i wallet.json)
 ```
 
-Or with yarn:
-
-```bash
-yarn add --dev permaweb-deploy
-```
-
-## Prerequisites
-
-1. **For Arweave signer (default):** Encode your Arweave wallet key in base64 format and set it as a GitHub secret:
-
-   ```bash
-   base64 -i wallet.json | pbcopy
-   ```
-
-2. **For Ethereum/Polygon/KYVE signers:** Use your raw private key (no encoding needed) as the `DEPLOY_KEY`.
-3. Ensure that the secret name for the encoded wallet or private key is `DEPLOY_KEY`.
-
-⚠️ **Important:** Use a dedicated wallet for deployments to minimize security risks. Ensure your wallet has sufficient Turbo Credits for uploads.
-
-## Usage
-
-### Interactive Mode (Easiest)
+If you prefer not to export a key, pass `--wallet ./wallet.json` to the commands below.
 
-**Command Menu:**
-
-Simply run the CLI for an interactive command selector:
+Upload a built static folder:
 
 ```bash
-permaweb-deploy
-# or explicitly
-permaweb-deploy interactive
+permaweb-deploy upload --deploy-folder ./dist
 ```
 
-This shows a menu with options:
-
-- **Deploy to Permaweb** - Start the deployment wizard
-- **Show Help** - Display help information
-- **Exit** - Exit the CLI
-
-**Interactive Deploy (Guided):**
-
-Run the deploy command without arguments to be guided through all deployment options:
+Deploy and update a Permaweb Name:
 
 ```bash
-permaweb-deploy deploy
+permaweb-deploy deploy --use-names --name my-app --deploy-folder ./dist
 ```
 
-This uploads to the permaweb by default. Use `--use-arns` or `--arns-name` to run the guided ArNS update flow, which will prompt you for:
-
-- ArNS name
-- Wallet method (file, string, or environment variable)
-- Signer type (Arweave, Ethereum, Polygon, KYVE)
-- What to deploy (folder or file)
-- Advanced options (optional: undername, TTL, network)
-
-### Direct Commands
-
-Use flags for faster, scriptable deployments:
+Or deploy and update a direct reference ID:
 
 ```bash
-# Basic deployment with wallet file
-permaweb-deploy deploy --wallet ./wallet.json
-
-# Deployment with ArNS update
-permaweb-deploy deploy --use-arns --arns-name my-app --wallet ./wallet.json
+permaweb-deploy deploy --use-names --reference-id REFERENCE_ID --deploy-folder ./dist
 ```
 
-Deploy using private key directly:
+For repeatable project scripts, add a build-and-deploy command:
 
-```bash
-permaweb-deploy deploy --arns-name my-app --private-key "$(cat wallet.json)"
+```json
+{
+  "scripts": {
+    "build": "vite build",
+    "deploy": "pnpm build && permaweb-deploy deploy --use-names --name my-app"
+  }
+}
 ```
 
-Deploy using environment variable:
+## Installation Options
 
 ```bash
-DEPLOY_KEY=$(base64 -i wallet.json) permaweb-deploy deploy --arns-name my-app
+pnpm add -D permaweb-deploy
 ```
 
-Deploy a specific folder:
-
 ```bash
-permaweb-deploy deploy --arns-name my-app --wallet ./wallet.json --deploy-folder ./build
+npm install --save-dev permaweb-deploy
 ```
 
-Deploy a single file:
-
 ```bash
-permaweb-deploy deploy --arns-name my-app --wallet ./wallet.json --deploy-file ./path/to/file.txt
+yarn add --dev permaweb-deploy
 ```
 
-### Upload/deploy without ArNS
+## Prerequisites
 
-`deploy` uploads without updating ArNS by default. You can also use the `upload` command explicitly for the same Turbo upload, dedupe cache, and payment options as deploy, minus ArNS flags:
+For the default Arweave signer, store your Arweave JWK as base64:
 
 ```bash
-permaweb-deploy deploy --wallet ./wallet.json --deploy-folder ./dist
-permaweb-deploy upload --wallet ./wallet.json --deploy-folder ./dist
-permaweb-deploy upload --wallet ./wallet.json --deploy-file ./dist/index.html
-DEPLOY_KEY=$(base64 -i wallet.json) permaweb-deploy upload --deploy-folder ./dist
+base64 -i wallet.json
 ```
 
-### Advanced Usage
+Set the encoded value as `DEPLOY_KEY`, or pass `--wallet ./wallet.json`.
 
-Deploy to an undername (subdomain):
+Names updates currently require `--sig-type arweave`, because reference updates are signed as ANS-104 data items and posted to the names bundler endpoint. Ethereum, Polygon, and KYVE signers remain supported for upload-only flows.
 
-```bash
-permaweb-deploy deploy --arns-name my-app --wallet ./wallet.json --undername staging
-```
+Use a dedicated deployment wallet and make sure it has enough upload credits/balance for the selected legacy bundler.
+
+## CLI Usage
 
-Deploy with a custom TTL:
+Upload only:
 
 ```bash
-permaweb-deploy deploy --arns-name my-app --wallet ./wallet.json --ttl-seconds 7200
+permaweb-deploy deploy --wallet ./wallet.json --deploy-folder ./dist
+permaweb-deploy upload --wallet ./wallet.json --deploy-file ./dist/index.html
+DEPLOY_KEY=$(base64 -i wallet.json) permaweb-deploy upload --deploy-folder ./dist
 ```
 
-Deploy using Ethereum wallet (file):
+Upload and update a reference-id pointed value using the namespace name:
 
 ```bash
-permaweb-deploy deploy --arns-name my-app --sig-type ethereum --wallet ./private-key.txt
+permaweb-deploy deploy --use-names --name my-app --wallet ./wallet.json
 ```
 
-Deploy using Ethereum wallet (direct key):
+Upload and update a direct reference ID:
 
 ```bash
-permaweb-deploy deploy --arns-name my-app --sig-type ethereum --private-key "0x1234..."
+permaweb-deploy deploy --use-names --reference-id REFERENCE_ID --wallet ./wallet.json
 ```
 
-### On-Demand Payment
-
-Use on-demand payment to automatically fund uploads with ARIO or Base-ETH tokens when your Turbo balance is insufficient:
-
-Deploy with ARIO on-demand payment:
+Advanced: use a custom namespace root reference or namespace manifest ID:
 
 ```bash
-permaweb-deploy deploy --arns-name my-app --wallet ./wallet.json --on-demand ario --max-token-amount 1.5
+permaweb-deploy deploy \
+  --use-names \
+  --name my-app \
+  --names-namespace NAMESPACE_ROOT_OR_MANIFEST_ID \
+  --wallet ./wallet.json
 ```
 
-Deploy with Base-ETH on-demand payment (using Ethereum signer):
+Deploy a specific target:
 
 ```bash
-permaweb-deploy deploy --arns-name my-app --sig-type ethereum --private-key "0x..." --on-demand base-eth --max-token-amount 0.1
+permaweb-deploy deploy --use-names --name my-app --wallet ./wallet.json --deploy-folder ./build
+permaweb-deploy deploy --use-names --name my-app --wallet ./wallet.json --deploy-file ./path/to/file.txt
 ```
 
-**On-Demand Payment Options:**
-
-- `--on-demand`: Token to use for on-demand payment (`ario` or `base-eth`)
-- `--max-token-amount`: Maximum token amount to spend (in native token units, e.g., `1.5` for 1.5 ARIO or `0.1` for 0.1 ETH)
+## Names Publishing
 
-**How it works:**
+`--name` resolves the name inside the configured namespace manifest and updates that reference. `--reference-id` bypasses namespace lookup and updates the reference directly.
 
-1. Checks your Turbo balance before upload
-2. If balance is insufficient, converts tokens to Turbo credits on-demand
-3. Automatically adds a 10% buffer (`topUpBufferMultiplier: 1.1`) for reliability
-4. Proceeds with upload once funded
+The default namespace is the phase-2 namespace exported by `@permaweb/references`. Override it with `--names-namespace` when you want to publish against another namespace root reference or manifest.
 
-**Token compatibility:**
+Useful flags:
 
-- **ARIO**: Works with Arweave signer
-- **Base-ETH**: Works with Ethereum signer (Base Network)
+- `--use-names`: update a Permaweb Names reference after upload.
+- `--name, -n`: namespace name to update.
+- `--reference-id`: reference ID to update directly.
+- `--names-namespace`: namespace root reference or manifest ID used to resolve `--name`.
+- `--names-gateway`: gateway for reference and namespace reads. Default: `https://arweave.net`.
+- `--names-graphql`: GraphQL endpoint for reference discovery. Default: `<names-gateway>/graphql`.
 
-### Bundler service
+## Bundlers
 
-Uploads go through a bundler service that accepts signed data items and posts them to Arweave. By default, permaweb-deploy uses the [Turbo](https://docs.ardrive.io/docs/turbo/) API and ArDrive’s production bundler (`https://upload.ardrive.io`). **`--uploader`** sets the **base URL** of the bundler service to use (scheme + host; typically no path).
-
-| When to use               | Example value                                                     |
-| ------------------------- | ----------------------------------------------------------------- |
-| **Default** (omit flag)   | ArDrive production bundler — same as Turbo CLI defaults           |
-| **Arweave bundler**       | `https://up.arweave.net`                                          |
-| **Development / staging** | `https://upload.ardrive.dev`                                      |
-| **Custom or self-hosted** | Your own base URL if it implements the selected uploader protocol |
-
-**Examples:**
+By default, uploads use the legacy ANS-104 endpoint at `https://up.arweave.net`. Pass `--uploader` to choose a different base URL.
 
 ```bash
-# Deploy using Arweave’s bundler service
-permaweb-deploy deploy --arns-name my-app --wallet ./wallet.json --uploader https://up.arweave.net
-
 permaweb-deploy upload --wallet ./wallet.json --deploy-folder ./dist --uploader https://up.arweave.net
 ```
 
-To upload through a HyperBEAM bundler, set `--uploader-type hyperbeam` and pass the node URL:
+HyperBEAM upload:
 
 ```bash
 permaweb-deploy upload \
   --wallet ./wallet.json \
   --deploy-folder ./dist \
-  --uploader-type hyperbeam \
-  --uploader https://hyperbeam.example.com
+  --uploader-type hyperbeam
+```
 
-permaweb-deploy deploy \
-  --wallet ./wallet.json \
-  --deploy-folder ./dist \
-  --uploader-type hyperbeam \
-  --uploader https://hyperbeam.example.com
+When `--uploader-type hyperbeam` is set and `--uploader` is omitted, the CLI discovers active [PermawebOS HyperBEAM](https://ao.arweave.net/#/stake/bundle) uploaders and randomly selects a usable node. HyperBEAM uploads always check that the selected or pinned node wallet has more than 0 AR before posting data, because the node must be able to seed data to Arweave. Pass `--uploader https://hyperbeam.example.com` to pin a specific node and bypass discovery.
+
+List discoverable HyperBEAM uploaders:
+
+```bash
+permaweb-deploy hyperbeam-uploaders
+permaweb-deploy hyperbeam-uploaders --json
 ```
 
-If the node follows the standard AO-paid HyperBEAM bundler flow, either command can fund the uploader wallet before uploading:
+HyperBEAM auto-fund:
 
 ```bash
 permaweb-deploy upload \
   --wallet ./wallet.json \
   --deploy-folder ./dist \
   --uploader-type hyperbeam \
-  --uploader https://hyperbeam.example.com \
   --hyperbeam-auto-fund
 ```
 
-**Notes:**
-
-- Turbo billing and signer behavior follow Turbo.
-- HyperBEAM uploads require an Arweave JWK signer. Before uploading, the CLI checks the node address from `/~meta@1.0/info/address` against `https://arweave.net/wallet/<address>/balance` and aborts if the bundler wallet has 0 AR. With `--hyperbeam-auto-fund`, the CLI signs each data item, asks the node's byte-pricing profile for a quote, sends AO to the node deposit address, imports that deposit through `/~ao-payment@1.0/ingest`, and waits for the uploader's balance at `/ledger~node-process@1.0/now/balance/<address>` before uploading. The default route is `/~bundler@1.0/item?codec-device=ans104@1.0`; override it with `--hyperbeam-upload-path` if your node exposes a different bundler route.
-- `--hyperbeam-fund-amount` is an optional override for the minimum local ledger balance to ensure, in AO base units. Without it, `--hyperbeam-auto-fund` uses the node's byte-pricing quote for the signed byte count. Use `--hyperbeam-token-id` only for a non-default AO token process, and `--hyperbeam-ledger-id` only for a non-default local ledger profile.
-- Use a **base URL only** (e.g. `https://up.arweave.net` or `https://hyperbeam.example.com`), not a path to a specific file or route.
-
-### Command Options
-
-**`deploy`** (upload by default, optional ArNS update):
-
-- `--use-arns`: Update an ArNS/ANT record after upload
-- `--arns-name, -n`: The ArNS name to update. Required when using `--use-arns`; also implies ArNS mode for backwards compatibility.
-- `--ario-process, -p`: ARIO process to use (`mainnet`, `testnet`, or a custom process ID). Default: `mainnet`
-- `--deploy-folder, -d`: Folder to deploy. Default: `./dist`
-- `--deploy-file, -f`: Deploy a single file instead of a folder
-- `--undername, -u`: ANT undername to update. Default: `@`
-- `--ttl-seconds, -t`: TTL in seconds for the ANT record (60-86400). Default: `60`
-- `--sig-type, -s`: Signer type for deployment. Choices: `arweave`, `ethereum`, `polygon`, `kyve`. Default: `arweave`
-- `--wallet, -w`: Path to wallet file (JWK for Arweave, private key for Ethereum/Polygon/KYVE)
-- `--private-key, -k`: Private key or JWK JSON string (alternative to `--wallet`)
-- `--on-demand`: Enable on-demand payment with specified token. Choices: `ario`, `base-eth`
-- `--max-token-amount`: Maximum token amount for on-demand payment (used with `--on-demand`)
-- `--no-dedupe`: Disable deduplication (do not cache or reuse previous uploads)
-- `--dedupe-cache-max-entries`: Maximum number of entries to keep in the dedupe cache (LRU). Default: `10000`
-- `--uploader`: Base URL of the bundler service to use. See [Bundler service](#bundler-service) above.
-- `--uploader-type`: Upload protocol to use (`turbo` or `hyperbeam`). Default: `turbo`
-- `--hyperbeam-upload-path`: HyperBEAM bundler route. Default: `/~bundler@1.0/item?codec-device=ans104@1.0`
-- `--hyperbeam-auto-fund`: Automatically fund the HyperBEAM local ledger before upload
-- `--hyperbeam-fund-amount`: Optional minimum HyperBEAM local ledger balance override, in token base units
-- `--hyperbeam-token-id`: Advanced AO token process ID override
-- `--hyperbeam-ledger-id`: Advanced local HyperBEAM ledger ID override
-- `--hyperbeam-ao-state-url`: AO state endpoint used while waiting for auto-fund transfer assignment. Default: `https://state.forward.computer`
+HyperBEAM uploads require an Arweave JWK signer. The default route is `/~bundler@1.0/item?codec-device=ans104@1.0`; override it with `--hyperbeam-upload-path` if your node exposes a different route.
 
-**`upload`** (explicit upload without ArNS): accepts `--deploy-folder`, `--deploy-file`, wallet/signer flags, uploader flags, `--on-demand` / `--max-token-amount`, and dedupe flags only.
+## Command Options
 
-### Deduplication
+`deploy` supports upload flags plus names publishing flags:
 
-By default, permaweb-deploy caches your deployment log to prevent uploading duplicate (unchanged) files. This saves both time and upload costs by reusing existing data on Arweave.
+- `--deploy-folder, -d`: folder to deploy. Default: `./dist`.
+- `--deploy-file, -f`: deploy a single file instead of a folder.
+- `--sig-type, -s`: signer type. Choices: `arweave`, `ethereum`, `polygon`, `kyve`. Default: `arweave`.
+- `--wallet, -w`: path to wallet file.
+- `--private-key, -k`: private key or JWK JSON string.
+- `--no-dedupe`: disable dedupe cache.
+- `--dedupe-cache-max-entries`: LRU cache size. Default: `10000`.
+- `--uploader`: bundler service base URL. Legacy uploads default to `https://up.arweave.net`; HyperBEAM uploads auto-discover an active PermawebOS uploader when omitted.
+- `--uploader-type`: upload protocol, `legacy` or `hyperbeam`. Default: `legacy`.
+- `--hyperbeam-upload-path`: HyperBEAM bundler route.
+- `--hyperbeam-auto-fund`: fund the HyperBEAM local ledger before upload.
+- `--hyperbeam-fund-amount`: optional minimum HyperBEAM local ledger balance override.
+- `--hyperbeam-token-id`: advanced AO token process ID override.
+- `--hyperbeam-ledger-id`: advanced local HyperBEAM ledger ID override.
+- `--hyperbeam-ao-state-url`: AO state endpoint used while waiting for auto-fund assignment.
+- `--use-names`, `--name`, `--reference-id`, `--names-namespace`, `--names-gateway`, `--names-graphql`: names publishing options.
 
-**How it works:**
+`upload` accepts upload, wallet, signer, bundler, and dedupe flags only.
 
-1. When you deploy, permaweb-deploy hashes each file in your build
-2. It checks the local cache for matching hashes from previous uploads
-3. Files that haven't changed are skipped - the existing transaction ID is reused
-4. Only new or modified files are uploaded to Arweave
-5. The cache is stored locally in `.permaweb-deploy/transaction-cache.json`
+## Deduplication
 
-**Disable deduplication:**
+The dedupe cache avoids re-uploading unchanged files. It hashes each deployed file and stores transaction IDs in `.permaweb-deploy/transaction-cache.json`.
 
-If you need to force a fresh upload of all files (e.g., for debugging or to ensure a completely new deployment):
+Disable dedupe:
 
 ```bash
-permaweb-deploy deploy --arns-name my-app --wallet ./wallet.json --no-dedupe
+permaweb-deploy deploy --use-names --name my-app --wallet ./wallet.json --no-dedupe
 ```
 
-**Limit cache size:**
-
-The dedupe cache uses an LRU (Least Recently Used) eviction strategy. By default, it keeps up to 10,000 entries. You can adjust this limit:
+Limit cache size:
 
 ```bash
-# Keep only the last 1000 file entries
-permaweb-deploy deploy --arns-name my-app --wallet ./wallet.json --dedupe-cache-max-entries 1000
+permaweb-deploy deploy --use-names --name my-app --wallet ./wallet.json --dedupe-cache-max-entries 1000
 ```
 
-**Cache location:**
-
-The cache file is stored at `.permaweb-deploy/transaction-cache.json` in your project root. You can:
-
-- Add it to `.gitignore` if you don't want to share cache across team members
-- Commit it to share cached transaction IDs with your team (reduces duplicate uploads)
-- Delete it to start fresh: `rm -rf .permaweb-deploy/`
-
-### Package.json Scripts
-
-Add deployment scripts to your `package.json`:
+## Package Scripts
 
 ```json
 {
   "scripts": {
     "build": "vite build",
-    "deploy": "pnpm build && permaweb-deploy deploy --arns-name <ARNS_NAME>",
-    "deploy:staging": "pnpm build && permaweb-deploy deploy --arns-name <ARNS_NAME> --undername staging",
-    "deploy:testnet": "pnpm build && permaweb-deploy deploy --arns-name <ARNS_NAME> --ario-process testnet",
-    "deploy:on-demand": "pnpm build && permaweb-deploy deploy --arns-name <ARNS_NAME> --on-demand ario --max-token-amount 1.5"
+    "deploy": "pnpm build && permaweb-deploy deploy --use-names --name <NAME>",
+    "deploy:ref": "pnpm build && permaweb-deploy deploy --use-names --reference-id <REFERENCE_ID>"
   }
 }
 ```
 
-Then deploy with:
-
 ```bash
 DEPLOY_KEY=$(base64 -i wallet.json) pnpm deploy
 ```
 
-Or with on-demand payment:
-
-```bash
-DEPLOY_KEY=$(base64 -i wallet.json) pnpm deploy:on-demand
-```
-
 ## GitHub Action
 
-The easiest way to integrate permaweb-deploy into your CI/CD pipeline is using our official GitHub Action.
+```yaml
+- uses: permaweb/permaweb-deploy@v1
+  with:
+    deploy-key: ${{ secrets.DEPLOY_KEY }}
+    name: myapp
+    deploy-folder: ./dist
+```
 
-### Basic Usage
+Use a direct reference ID:
 
 ```yaml
 - uses: permaweb/permaweb-deploy@v1
   with:
     deploy-key: ${{ secrets.DEPLOY_KEY }}
-    arns-name: myapp
+    reference-id: ${{ secrets.NAMES_REFERENCE_ID }}
     deploy-folder: ./dist
 ```
 
-### PR Preview Deployments
-
-Automatically deploy preview builds for each pull request. The `preview` mode auto-generates an undername from the PR number and posts a comment with the preview URL:
+PR preview names:
 
 ```yaml
 name: Deploy PR Preview
@@ -369,327 +286,73 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: '20'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Deploy Preview
-        uses: permaweb/permaweb-deploy@v1
+      - run: npm ci
+      - run: npm run build
+      - uses: permaweb/permaweb-deploy@v1
         with:
           deploy-key: ${{ secrets.DEPLOY_KEY }}
-          arns-name: myapp
           preview: 'true'
           github-token: ${{ secrets.GITHUB_TOKEN }}
           deploy-folder: ./dist
 ```
 
-When `preview` is enabled, the action will:
-
-- Auto-generate an undername like `pr-123` from the PR number
-- Post a comment on the PR with the preview URL
-- Update the comment on subsequent pushes instead of creating new ones
-
-### Production Deployment
-
-Deploy to your base ArNS name when pushing to main:
-
-```yaml
-name: Deploy to Production
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Deploy to Permaweb
-        uses: permaweb/permaweb-deploy@v1
-        with:
-          deploy-key: ${{ secrets.DEPLOY_KEY }}
-          arns-name: myapp
-          deploy-folder: ./dist
-```
-
-### With On-Demand Payment
-
-```yaml
-- name: Deploy with ARIO on-demand
-  uses: permaweb/permaweb-deploy@v1
-  with:
-    deploy-key: ${{ secrets.DEPLOY_KEY }}
-    arns-name: myapp
-    deploy-folder: ./dist
-    on-demand: ario
-    max-token-amount: '2.0'
-```
-
-### With HyperBEAM
-
-```yaml
-- name: Deploy through a HyperBEAM bundler
-  uses: permaweb/permaweb-deploy@v1
-  with:
-    deploy-key: ${{ secrets.DEPLOY_KEY }}
-    arns-name: myapp
-    deploy-folder: ./dist
-    uploader-type: hyperbeam
-    uploader: https://hyperbeam.example.com
-    hyperbeam-auto-fund: 'true'
-```
-
-### Disabling Deduplication
-
-By default, the action caches transaction IDs to avoid re-uploading unchanged files. To disable this:
-
-```yaml
-- name: Deploy without dedupe
-  uses: permaweb/permaweb-deploy@v1
-  with:
-    deploy-key: ${{ secrets.DEPLOY_KEY }}
-    arns-name: myapp
-    deploy-folder: ./dist
-    no-dedupe: 'true'
-```
-
-You can also limit the cache size:
-
-```yaml
-- name: Deploy with limited cache
-  uses: permaweb/permaweb-deploy@v1
-  with:
-    deploy-key: ${{ secrets.DEPLOY_KEY }}
-    arns-name: myapp
-    deploy-folder: ./dist
-    dedupe-cache-max-entries: '1000'
-```
-
----
-
-## CLI in GitHub Actions
-
-You can also use the CLI directly in your workflows:
-
-**Basic Workflow:**
-
-```yaml
-name: Deploy to Permaweb
-
-on:
-  push:
-    branches:
-      - main
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: pnpm/action-setup@v3
-        with:
-          version: 9
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: 'pnpm'
-
-      - run: pnpm install
-
-      - run: pnpm deploy
-        env:
-          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
-```
-
-**With On-Demand Payment:**
+When `preview` is enabled, the action generates a namespace name from the repository and PR number, deploys the content, updates that name, and posts or updates a PR comment.
 
-```yaml
-name: Deploy to Permaweb with On-Demand Payment
+Action inputs for names publishing:
 
-on:
-  push:
-    branches:
-      - main
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: pnpm/action-setup@v3
-        with:
-          version: 9
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: 'pnpm'
-
-      - run: pnpm install
-      - run: pnpm build
-
-      - name: Deploy with ARIO on-demand
-        run: permaweb-deploy deploy --arns-name my-app --on-demand ario --max-token-amount 2.0
-        env:
-          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
-
-      # Or deploy with Ethereum and Base-ETH:
-      # - name: Deploy with Base-ETH on-demand
-      #   run: |
-      #     permaweb-deploy deploy \
-      #       --arns-name my-app \
-      #       --sig-type ethereum \
-      #       --on-demand base-eth \
-      #       --max-token-amount 0.2
-      #   env:
-      #     DEPLOY_KEY: ${{ secrets.ETH_PRIVATE_KEY }}
-```
+- `name`: namespace name to update.
+- `reference-id`: reference ID to update directly.
+- `names-namespace`: namespace root reference or manifest ID.
+- `names-gateway`: gateway for reference and namespace reads.
+- `names-graphql`: GraphQL endpoint for reference discovery.
+- `auto-name`: generate a namespace name from PR number or branch name.
+- `preview`: enable `auto-name` and post a PR comment.
 
 ## Development
 
-### Setup
-
 ```bash
-# Install dependencies
 pnpm install
-
-# Build the project
 pnpm build
-
-# Run in development mode
-pnpm dev
-
-# Run tests
 pnpm test
-
-# Run linter
 pnpm lint
-
-# Format code
-pnpm format
 ```
 
-### Project Structure
+Project layout:
 
-```
+```text
 permaweb-deploy/
-├── src/
-│   ├── commands/        # oclif commands
-│   │   ├── deploy.ts
-│   │   └── upload.ts
-│   ├── types/           # TypeScript type definitions
-│   │   └── index.ts
-│   ├── utils/           # Utility functions
-│   │   ├── constants.ts
-│   │   ├── signer.ts
-│   │   ├── uploader.ts
-│   │   └── __tests__/   # Unit tests
-│   └── index.ts         # Main entry point
-├── bin/                 # Executable scripts
-│   ├── run.js
-│   └── dev.js
-├── .changeset/          # Changesets configuration
-├── .husky/              # Git hooks
-└── dist/                # Build output
+├── src/commands
+├── src/constants
+├── src/prompts
+├── src/types
+├── src/utils
+├── src/workflows
+├── tests
+└── bin
 ```
 
-## Security & Best Practices
-
-- **Dedicated Wallet:** Always use a dedicated wallet for deployments to minimize security risks
-- **Wallet Encoding:** Arweave wallets must be base64 encoded to be used in the deployment script
-- **ArNS Name:** Required only when updating an ANT/ArNS target undername or root record
-- **Turbo Credits:** Ensure your wallet has sufficient Turbo Credits, or use on-demand payment for automatic funding
-- **On-Demand Limits:** Set reasonable `--max-token-amount` limits to prevent unexpected costs
-- **Secret Management:** Keep your `DEPLOY_KEY` secret secure and never commit it to your repository
-- **Build Security:** Always check your build for exposed environmental secrets before deployment, as data on Arweave is permanent
-
 ## Troubleshooting
 
-- **Error: "DEPLOY_KEY environment variable not set":** Verify your base64 encoded wallet is set as the `DEPLOY_KEY` environment variable
-- **Error: "deploy-folder does not exist":** Check that your build folder exists and the path is correct
-- **Error: "deploy-file does not exist":** Check that your build file exists and the path is correct
-- **Error: "ArNS name does not exist":** Verify the ArNS name is correct and exists in the specified network
-- **Upload timeouts:** Files have a timeout for upload. Large files may fail and require optimization
-- **Insufficient Turbo Credits:** Use `--on-demand` with `--max-token-amount` to automatically fund uploads when balance is low
-- **On-demand payment fails:** Ensure your wallet has sufficient tokens (ARIO or Base-ETH) and the token type matches your signer (`ario` with Arweave, `base-eth` with Ethereum)
-
-## Contributing
-
-Contributions are welcome! Please follow these guidelines:
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Run tests and linter: `pnpm test && pnpm lint`
-5. Create a changeset: `pnpm changeset`
-6. Commit your changes using conventional commits
-7. Push and create a pull request
-
-### Conventional Commits
-
-This project uses [Conventional Commits](https://www.conventionalcommits.org/). Commit messages should follow this format:
-
-```
-type(scope): subject
-
-body (optional)
-```
-
-Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
-
-### Changesets
-
-We use [changesets](https://github.com/changesets/changesets) for version management. When making changes:
-
-```bash
-pnpm changeset
-```
-
-Follow the prompts to describe your changes.
+- **`DEPLOY_KEY environment variable not set`:** pass `--wallet`, pass `--private-key`, or set `DEPLOY_KEY`.
+- **`Names updates currently require --sig-type arweave`:** reference updates are signed as ANS-104 data items; use an Arweave JWK for names updates.
+- **`Name [...] does not exist in namespace ...`:** verify the namespace manifest contains the name or use `--reference-id`.
+- **`signer is not reference authority`:** use the wallet that controls the target reference.
+- **`deploy-folder does not exist`:** check the build output path.
+- **`deploy-file does not exist`:** check the file path.
+- **Legacy upload rejected:** check the upload endpoint response and retry with another legacy bundler if needed.
 
 ## Dependencies
 
-- **@ar.io/sdk** - For ANT operations and ArNS management
-- **@ardrive/turbo-sdk** - For fast file uploads to Arweave
-- **@permaweb/aoconnect** - For AO network connectivity
-- **@oclif/core** - CLI framework
-- **mime-types** - MIME type detection
+- **@permaweb/references** - namespace reference reads and writes.
+- **@dha-team/arbundles** - ANS-104 data item signing.
+- **@permaweb/aoconnect** - AO network connectivity.
+- **@permaweb/hyperbalance** - HyperBEAM auto-fund support.
+- **@oclif/core** - CLI framework.
+- **mime-types** - MIME type detection.
 
 ## License
 
 ISC
-
-## Author
-
-NickJ202
-
-## Links
-
-- [GitHub Repository](https://github.com/permaweb/permaweb-deploy)
-- [Issues](https://github.com/permaweb/permaweb-deploy/issues)
-- [Arweave Documentation](https://docs.arweave.org/)
-- [AR.IO Documentation](https://docs.ar.io/)