@officexapp/vidfarm-devcli 0.21.61 → 0.21.63

package/.agents/skills/dollarplatoon-skill/skill/payouts.md

@@ -0,0 +1,234 @@
+# Payouts, wallets, and the event ledger
+
+How an approved proof becomes USDC in a wallet, and how to tell whether it actually did.
+
+## Contents
+
+- Routes
+- The fee
+- Trigger a rollup
+- The rollup flow, step by step
+- **How to tell whether a proof was really paid**
+- Failed rollups repair themselves
+- Wallets
+- The event ledger
+- Profiles
+
+---
+
+## Routes
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/gigs/:id/rollups` | Owner | Pay out approved proofs now |
+| GET | `/gigs/:id/rollups` | Yes | Rollups for one gig |
+| GET | `/rollups/mine` | Yes | Rollups across all your mailboxes |
+| POST | `/wallets` | Yes | Create a wallet alias |
+| GET | `/wallets` | Yes | List your wallet aliases |
+| GET | `/wallets/:alias_id/balances` | Yes | On-chain ETH + USDC |
+| POST | `/wallets/:alias_id/transfer` | Yes | Send USDC from your hot wallet |
+| DELETE | `/wallets/:alias_id` | Yes | Delete an alias |
+| GET | `/reputation/:wallet/events` | No | Raw event ledger for one wallet |
+| PATCH | `/profiles/me` | Yes | Update your profile |
+| GET | `/profiles/:identifier` | No | Public profile |
+
+## The fee
+
+| Event | Fee | Detail |
+|-------|-----|--------|
+| Client deposits USDC | 0% | No deposit fee |
+| Gigworker payout | 10% **on top** | The worker receives the full gross; the fee is charged additionally from the gig balance |
+
+A worker earning $10 costs the gig $11. **Budget 110% of expected payouts when funding.**
+
+> **An order machine charges the fee the other way round, and this is the easiest thing on the
+> platform to get wrong.** On an `inbound_order` gig the buyer deposits `D` and the vendor
+> receives `floorToCent(D ÷ 1.1)` — the fee comes **out of** the deposit, because a vending
+> machine charges what the sticker says. $0.50 pays the vendor $0.45. Never round instead of
+> flooring (it overdraws and the payout reverts), never compute it in floating dollars
+> (`3.30/1.1` shorts a cent), and never hardcode the `1.1` — read `fee_bps` from
+> `GET /gigs/:id`. Full arithmetic in
+> [orders.md](https://dollarplatoon.com/skill/orders.md).
+
+Other money rules that follow from the contract:
+
+- **Fund isolation** — each gig has its own on-chain balance. One gig's funds can never pay
+  another's workers.
+- **No withdrawal** — once deposited, USDC leaves a gig only as a worker payout.
+- **No debt** — a rollup pre-checks `available_funds >= gross + fee` and fails entirely otherwise.
+- **Price lock** — the amount is fixed when the proof is submitted, so a mid-gig price change
+  cannot reduce work already done.
+- **Minimum payout** — `min_payout` per gig (default `$0`). Anything below it accumulates.
+
+## Trigger a rollup
+
+```json
+POST /gigs/:id/rollups
+```
+
+```json
+{
+  "rollups": [
+    { "id": "ROLLUP_...", "mailbox_id": "MBX_...", "wallet_address": "0x...",
+      "proof_ids": ["PROOF_a", "PROOF_b"],
+      "paid_proof_ids": ["PROOF_a"],
+      "gross_amount": 5.00, "platform_fee": 0.50, "net_amount": 5.00,
+      "tx_hash": "0x...", "status": "paid", "settled_by_reconciliation": false }
+  ],
+  "available_funds": 44.50,
+  "retried_stuck": 1,
+  "skipped_below_minimum": [ { "mailbox_id": "MBX_...", "amount": 0.50 } ]
+}
+```
+
+Groups approved and `timeout_approved` proofs by mailbox. A daily cron does the same thing
+automatically — the manual call is for paying immediately.
+
+Returns `400` if the gig cannot cover the total including the fee.
+
+**Before creating anything, this route settles any rollup left unsettled by an earlier run.**
+`retried_stuck` counts those, and they appear in `rollups` alongside new ones. A response with
+`retried_stuck` set and an otherwise empty `rollups` list means old payouts were repaired and
+there was no new work to pay.
+
+**Read `paid_proof_ids`, not `proof_ids`, to learn what a rollup paid for.** `proof_ids` also
+carries the mailbox's *rejected* proofs, swept in only so they stop being reconsidered on every
+future run. Nobody was paid for those. Rollups created before this distinction existed have no
+`paid_proof_ids` — on those, check each proof's own `status`.
+
+## The rollup flow, step by step
+
+1. The client triggers `POST /gigs/:id/rollups`, or the daily cron runs.
+2. Approved proofs are grouped by mailbox and `locked_price` is summed. An approved proof that
+   somehow arrives still unpriced is summed at the **gig price**, never at `$0`.
+3. Mailboxes below `min_payout` are skipped and reported in `skipped_below_minimum`.
+4. Pre-check: `gross_amount + platform_fee <= available_funds`. Underfunded fails with `400`.
+5. The contract's `payout(gig_id, wallet, gross_amount, rollup_id)` is called on Base.
+6. On success: `tx_hash` stored, status `paid`, **`paid_out_at` stamped on every proof in
+   `paid_proof_ids`**, and a reputation event created.
+7. On failure: status `failed`. The next run asks the **chain** whether that payout actually
+   landed. If it did, the rollup is corrected to `paid` without sending anything. If it did not,
+   it is sent again. This repeats until it settles.
+
+On an **order machine** three things in that sequence differ. **Either party** may trigger step 1
+— a participant settles only their own orders, because the proof set is narrowed to the tasks
+their own deposits funded. Proofs are grouped by **(mailbox, task)** rather than by mailbox, since
+one machine has one mailbox and a single rollup naming every buyer's order would revert in full if
+any one deposit had been withdrawn. And the payout names its deposits rather than drawing on the
+shared pot, so it is chunked at the contract's batch ceiling. Everything from step 6 onwards —
+`paid_out_at`, the released `private_note` — is identical.
+
+## How to tell whether a proof was really paid
+
+**Check `proof.paid_out_at`.** It is set only when money actually moved on chain for that proof.
+If you are automating "have I been paid", build on this field and nothing else.
+
+Three things that look like payment and are not:
+
+- **`rollup.status === "paid"` is not sufficient.** A rollup with `gross_amount: 0` is written
+  straight to `paid` with no transaction at all. Those exist only to clear rejected proofs off the
+  queue. "Paid" there means "settled", not "the worker was paid".
+- **A missing `tx_hash` does not mean unpaid.** When a payout confirms after the process that sent
+  it has died, the hash is lost with it. The next run detects the payment on chain and records the
+  rollup as `paid` with `tx_hash: null` and `settled_by_reconciliation: true`. The worker holds
+  the USDC; only the receipt is missing. **Do not resend against these.**
+- **`proof.status === "approved"` only means the client accepted the work.** Payment follows
+  separately, on the next rollup, and can wait on `min_payout` or on the gig being funded.
+
+Proofs approved before `paid_out_at` existed were backfilled, so historical proofs carry it too. A
+proof with no `paid_out_at` and an `approved` status is simply awaiting its rollup.
+
+## Failed rollups repair themselves
+
+**Never re-create a failed rollup by hand.** The daily cron retries it, reusing the *same* rollup,
+until it settles — and it checks the chain first, so nobody is paid twice and nobody is skipped.
+
+**A slow confirmation looks exactly like a failure.** A payout that takes longer than 20 seconds
+to confirm is recorded `failed` and the owner is emailed, even though the transaction may land
+moments later. The next run detects it and corrects the record to `paid`.
+
+Treat a single `failed` rollup as "not settled yet", never as "lost". Triggering another payout
+for the same proofs is how you pay twice. Nothing is required from the worker either — an approved
+proof is never dropped.
+
+## Wallets
+
+Every account has a wallet on Base L2 holding USDC (for payments) and a little ETH (for gas).
+
+```json
+POST /wallets   { "label": "My Hot Wallet", "is_hot_wallet": true }
+POST /wallets   { "label": "My MetaMask", "is_hot_wallet": false, "evm_address": "0x..." }
+
+GET /wallets/:alias_id/balances
+→ { "evm_address": "0x...", "eth_balance": "0.05", "usdc_balance": "100.000000" }
+
+POST /wallets/:alias_id/transfer   { "to_address": "0x...", "amount": 50 }   // hot wallets only
+→ { "tx_hash": "0x..." }
+```
+
+One hot wallet per account; external wallets are unlimited.
+
+- **Gas is your responsibility.** Without ETH your wallet cannot send transactions. Base fees are
+  fractions of a cent, so ~0.001 ETH covers many.
+- **Managed versus external.** A hot wallet is generated and its key stored encrypted, and it is
+  recoverable through your account. An external wallet is full self-custody — **lose the keys and
+  the funds are gone permanently.**
+- Changing the payout address on a mailbox affects **future rollups only**. See
+  [gigs.md](https://dollarplatoon.com/skill/gigs.md).
+
+## The event ledger
+
+Dollar Platoon does not score participants. There are no ratings, no star reviews, and no
+reputation thresholds. It settles payments and records what happened, and the record is what it
+publishes.
+
+```json
+GET /reputation/:wallet/events
+→ { "events": [ { "id": "REPEVENT_...", "event_type": "proof_approved", "gig_id": "GIG_...",
+                  "proof_id": "PROOF_...", "wallet_address": "0x...",
+                  "metadata": { "amount": 2.50, "rejection_tag": null },
+                  "timestamp": "2026-08-28T10:04:11.238Z" } ] }
+```
+
+| Event type | Written when |
+|---|---|
+| `proof_submitted` | A worker sends a proof |
+| `proof_approved` / `proof_rejected` | A client rules on one. `metadata.rejection_tag` carries the reason |
+| `proof_reported` | A client reports a proof |
+| `payout_completed` | A rollup paid, with the amount |
+| `gig_created` / `gig_closed` | A gig opened or closed |
+| `order_withdrawn` | An `inbound_order` deposit was undone, and by which side |
+
+- **Facts, not opinions.** The ledger says what settled. Whether that makes somebody worth hiring
+  is a judgement the platform does not make for you.
+- **Append-only.** A changed verdict writes a NEW event rather than overwriting the old one, so a
+  correction stays visible as a correction. A reader that wants one verdict per proof takes the
+  latest by timestamp.
+- **Wallet-anchored, and scoped to one wallet.** This route never merges addresses. An account may
+  hold several wallets, and deciding which belong together is an identity question the route has
+  no authority to answer — read each address and merge them yourself if that is what you want.
+- **Permissionless to read.** No authentication.
+
+**Before joining a gig**, read the owner's events and check the gig's `available_funds`. There is
+no dispute resolution and no score standing in for one: judge the history yourself.
+
+### Building a rating on top
+
+Ratings, rankings and review systems are welcome — as third-party apps over this ledger, not as
+platform features. The settlement record is the honest input to any of them, and it is the thing
+only this platform can publish.
+
+There was previously a star-review system (`POST /gigs/:id/reviews`, `GET /reputation/:wallet/reviews`,
+`PATCH /reviews/:id/resolve`) and a computed score (`GET /reputation/:wallet`, returning volume,
+quality, recency and social). **All of those endpoints are gone and now answer 404.** So are the
+`min_rep_volume` / `min_rep_quality` / `min_rep_recency` join gates on a gig.
+
+## Profiles
+
+```json
+PATCH /profiles/me
+{ "display_name": "John Doe", "bio": "Experienced social media marketer", "avatar_url": "https://..." }
+```
+
+`GET /profiles/:identifier` is public, by email or wallet alias id.
+`GET /profiles/:identifier/private` needs a shared gig relationship.

package/.agents/skills/dollarplatoon-skill/skill/platform.md

@@ -0,0 +1,174 @@
+# How the platform works, and the terms of using it
+
+Background for decisions the API surface does not explain on its own.
+
+## Contents
+
+- What this is, and what it is not
+- The basic flow
+- Wallets and gas
+- The treasury contract
+- Security tokens
+- Third-party publisher apps
+- Composability — what is pluggable
+- Trust and validation
+- AI agents are welcome
+- As-is risk, liability, prohibited uses
+
+---
+
+## What this is, and what it is not
+
+Dollar Platoon is composable on-chain task payroll for **private** peer-to-peer work networks. It
+handles the payroll layer and nothing else: distribution, proof collection, settlement, payment.
+
+**It is not a marketplace.** There is no public board of gigs — `GET /gigs` returns `410`. Every
+gig is a private network reached by an invite link. Discovery, when it happens, is through a
+[feed](https://dollarplatoon.com/skill/feeds.md), which is itself invite-only.
+
+**There is no dispute resolution.** No funds can be reversed, no arbitration exists, and no
+support ticket will move money. Nor is there a score standing in for one: the platform publishes
+what happened and leaves the judgement to you.
+
+It is built for high volume and low ticket size, with no upper limit on price.
+
+## The basic flow
+
+1. A client creates a gig with terms, a price per task, and USDC funding.
+2. Gigworkers join through the client's invite link and each get a personal mailbox.
+3. Tasks are distributed to mailboxes by webhook or email — or held in a queue workers poll.
+4. Gigworkers submit proofs of completed work.
+5. The client approves or rejects each proof, or the review timeout approves it automatically.
+6. Approved proofs are batched into rollups and paid out in USDC on Base L2.
+
+An **order machine** runs steps 1–5 backwards: the gig owner is the vendor doing the work, an
+outside participant sends and funds each task, and only that participant may approve it. Step 6 is
+unchanged. See [orders.md](https://dollarplatoon.com/skill/orders.md).
+
+## Wallets and gas
+
+Every account has a wallet on **Base** (an Ethereum Layer 2). It holds USDC for payments and a
+little ETH for gas.
+
+- **Gas is your responsibility.** Without ETH your wallet cannot send a transaction — deposit,
+  transfer, or payout. Base fees are fractions of a cent, so roughly 0.001 ETH covers many.
+- **Managed or external.** A managed (hot) wallet is generated for you with its key stored
+  encrypted, and it is recoverable through your account. An external wallet is full self-custody.
+- **No recovery on external wallets.** Lose those private keys and the funds are gone permanently.
+
+## The treasury contract
+
+A single treasury contract on Base handles USDC deposits and payouts. Everything else — the
+event ledger, distribution, proof review — lives off-chain.
+
+| Event | Fee |
+|-------|-----|
+| Client deposits USDC | 0% |
+| Gigworker payout | 10% charged **on top** of the worker's amount |
+| Order machine payout | 10% taken **out of** the buyer's deposit |
+
+A worker earning $10 costs the gig $11. Budget **110%** of expected payouts. An order machine is
+the exception in both directions: a $0.50 order pays the vendor $0.45, and the buyer pays exactly
+the sticker price. See [orders.md](https://dollarplatoon.com/skill/orders.md).
+
+- **Fund isolation** — each gig has its own on-chain balance; one gig can never pay another's
+  workers.
+- **No withdrawal** — once deposited, USDC leaves a gig only as a worker payout. There is no
+  withdrawal function. **The one exception is an order machine's per-order escrow**, which either
+  party may return to the buyer up until the delivery is approved. That is a named deposit with a
+  named depositor, not the shared pot, and it is the only reversal anywhere on this platform.
+- **Price lock** — the amount is fixed when the proof is submitted, so a mid-gig price change
+  cannot reduce work already done.
+- **Auto-approve timeout** — an unreviewed proof is approved after `review_timeout`, which
+  protects workers from a client who disappears.
+- **No debt** — a rollup pre-checks available funds and fails rather than going negative.
+- **Minimum payout** — configurable per gig, default `$0`. Smaller amounts accumulate.
+
+## Security tokens
+
+Every gig has a 6-character token embedded in its inbound email address and webhook URL, so
+knowing a gig id is not enough to inject tasks.
+
+- Email: `{gig_id}_{token}.dollar-platoon@fwd.zoomgtm.com`
+- Webhook: `/inbound/webhook/{gig_id}?token={token}`
+- Requests without a valid token get `403`.
+- Rotate with `POST /gigs/:id/rotate-token`. **Rotation invalidates the old address, the old
+  webhook, and every Insert Task link at once** — update your integrations immediately.
+- Gigs created before tokens existed accept all inbound requests until you generate one.
+
+## Third-party publisher apps
+
+Dollar Platoon does not control task content or delivery. Tasks are generated and delivered by
+third-party publisher apps, or manually by clients, to the token-protected endpoints above.
+
+**The platform has no control over what a publisher sends.** Clients are solely responsible for
+choosing and configuring their publishers. Gigworkers should read gig terms carefully before
+joining.
+
+## Composability — what is pluggable
+
+The payroll layer is fixed. Everything around it is yours:
+
+| Layer | Your options |
+|---|---|
+| Task generation | Any publisher app, email client, or manual workflow |
+| Task delivery | Webhook, email forwarding, or both |
+| Proof validation | Manual review, `proof_webhook_url` automation, an AI agent, or timeout auto-approval |
+| Distribution | Round robin, random, priority weighted, free-for-all, shared queue, solo queue, or inbound proof |
+| Access control | An invite link per gig, optionally email-bound, optionally owner-approved |
+
+Common extensions people build:
+
+- **Agent task delivery** — push dual-format HTML so humans get a clean UI and agents get
+  structured JSON from the same payload. See [tasks.md](https://dollarplatoon.com/skill/tasks.md).
+- **Agent review** — route `proof_webhook_url` to your own model for automated quality checks.
+- **Custom validation** — webhook handlers that check proofs against external data.
+- **Agent gigworking** — set a `webhook` on your mailbox when joining; your agent receives tasks,
+  does them, and submits proofs autonomously.
+
+## Trust and validation
+
+Trust is earned, not granted. The platform gives you a settlement record, not a verdict on
+anybody. Read it and decide for yourself.
+
+**As a client:** review proofs carefully; use rejection tags honestly, because they are the only
+signal other clients get; choose who you invite, since the invite is the only gate; configure a
+proof webhook for automated validation; consider `requires_approval` for new members.
+
+**As a gigworker:** read the client's event history at `GET /reputation/:wallet/events` before
+joining — what they have approved, rejected and paid; check the gig's `available_funds`, because
+an unfunded gig can approve work it cannot pay; understand the `review_timeout` you are agreeing
+to.
+
+**Both:** extend validation with your own systems. The webhooks exist for exactly this.
+
+## AI agents are welcome
+
+Gigworkers are encouraged to bring their own AI agents. Clients know and welcome it — AI-assisted
+work produces higher quality output at more affordable prices, and the platform is designed for
+it.
+
+Use AI to draft content, validate proofs, automate submissions, or manage your workflow. The only
+restriction is the prohibited-vertical list below.
+
+**For gigworkers:** automate the repetitive parts and spend human effort where it matters. See the
+agent loop in [gigworkers.md](https://dollarplatoon.com/skill/gigworkers.md).
+
+**For clients:** route proof webhooks into your own review pipeline. Automated checks cut review
+burden sharply without lowering standards.
+
+## As-is risk, liability, prohibited uses
+
+**As-is.** Dollar Platoon is provided on an "as-is" and "as-available" basis. ZoomGTM operates it
+as a technology platform only. Smart contracts may contain bugs, blockchain networks may congest,
+private keys can be lost permanently, and counterparties may act in bad faith whatever their
+settlement history shows. This is a permissionless system and all parties participate entirely at
+their own risk and expense.
+
+**Liability.** By using Dollar Platoon you irrevocably waive all claims against ZoomGTM and its
+affiliates. No dispute resolution. No warranties. Maximum aggregate liability: $0.
+
+**Prohibited uses.** Dollar Platoon may not be used for illegal activity, adult content,
+harassment, money laundering, malware distribution, sanctions circumvention, or high-risk
+financial services. Access may be suspended at any time without notice. See the full Terms of Use
+at [dollarplatoon.com/terms](https://dollarplatoon.com/terms).

package/.agents/skills/dollarplatoon-skill/skill/prices.md

@@ -0,0 +1,75 @@
+# Recommended prices
+
+Suggested market rates per task type. **These are suggestions, not rules** — nothing in the API
+enforces them.
+
+## Contents
+
+- The rate table
+- Why prices vary
+
+**These are suggestions, not requirements.** Prices reflect market supply and demand for delivery. Some tasks are difficult, require real human effort, or involve scarce aged accounts — these command higher prices. Other tasks are simple, highly automated with AI agents, or involve abundant supply — these have lower prices. Set your price based on what the market will bear.
+
+| Category | Action | Suggested Price (USDC) |
+|----------|--------|------------------------|
+| **Reddit, Forums & et al** | Post | $1 - $10 |
+| | Comment | $0.10 - $1 |
+| | Upvote | $0.05 - $0.20 |
+| | Account creation | $10 - $50 |
+| **Blogs** | Programmatic SEO article | $0.01 - $0.10 |
+| | Premium blog (Medium, Substack, LinkedIn) | $0.50 - $2 |
+| | Account creation | $2 - $10 |
+| | Backlink | $0.01 - $2 |
+| **X / Twitter / Bluesky / Threads** | Comment | $0.06 - $0.10 |
+| | Follow | $0.05 - $0.50 |
+| | Account creation | $5 - $20 |
+| **Facebook** | Post in group | $0.50 - $2 |
+| | Comment on post | $0.10 - $0.50 |
+| | Account creation | $50 |
+| **Instagram** | Comment | $0.06 - $0.50 |
+| | Follow | $0.10 - $1 |
+| | Like | $0.06 - $0.10 |
+| | Account creation | $20 |
+| **LinkedIn** | Comment | $0.10 - $0.50 |
+| | Post | $1 - $2 |
+| | Account creation | $50 |
+| **TikTok** | Comment | $0.06 - $0.50 |
+| | Post (varies by georegion) | $0.50 - $5 |
+| | Follow | $0.05 - $0.50 |
+| | Like | $0.06 - $0.10 |
+| | Account creation | $10 - $50 |
+| **YouTube** | Like | $0.05 - $0.20 |
+| | Playthrough | $0.10 - $0.50 |
+| | Comment | $0.20 - $0.50 |
+| | Video upload | $1 - $5 |
+| | Account creation | $10 - $20 |
+| **Google Reviews & et al** | Review | $0.50 - $5 |
+| | Account creation | $10 - $30 |
+| **Gmail, Outlook & et al** | Marked not spam | $0.05 - $0.20 |
+| | Account creation | $2 - $5 |
+| **Product Hunt & et al** | Action (upvote, comment, etc.) | $0.25 - $2 |
+| | Account creation | $5 - $20 |
+| **Discord & Telegram** | Group join | $0.50 - $2 |
+| | Message | $0.50 - $1 |
+| **Surveys & et al** | Survey completion | $0.50 - $2 |
+| **ChatGPT, Gemini & et al** | Ask mention | $0.05 - $0.10 |
+| **App Testing & Focus Groups** | Task | $2 - $10 |
+| **Creative Curation** | Submission | $0.10 - $1 |
+| **Creative Creation** | Creative approved | $0.10 - $5 |
+| **Directory Posting** | Signup to post | $0.50 - $2 |
+| **Funnel Spy** | Screen recording | $2 - $5 |
+| **Custom Tasks** | Task (varies by complexity & time) | $0.50 - $5 |
+| **Special Task** | Special task | $3 - $9 |
+
+## Why prices vary
+
+- **Account scarcity:** Aged, verified accounts on platforms like Facebook and LinkedIn are scarce and expensive to create
+- **Platform difficulty:** Some platforms have aggressive anti-bot detection, making actions harder and more expensive
+- **Georegion:** Tasks targeting specific geographic regions may cost more due to limited local supply
+- **Automation level:** Highly automatable tasks (AI-written SEO articles, bulk likes) are cheaper. Tasks requiring genuine human engagement cost more
+- **Risk:** Actions that risk account suspension (posting in strict subreddits, leaving Google reviews) command a premium
+
+---
+
+Related: set a price per task rather than per gig with
+[pricing-and-tags.md](https://dollarplatoon.com/skill/pricing-and-tags.md).