skillpp 0.1.0

package/skills/binance/payment/send_extension/__init__.py

@@ -0,0 +1,43 @@
+"""
+Payment Extension Registry.
+
+Extensions are checked in order — first match wins.
+PIX is checked before C2C because C2C is the catch-all fallback.
+"""
+from .base import PaymentExtension
+from .c2c import C2cExtension
+from .pix import PixExtension
+
+# Ordered list: specific detectors first, fallback last
+EXTENSIONS = [PixExtension(), C2cExtension()]
+
+
+def detect_extension(raw_qr: str) -> PaymentExtension:
+    """Find the matching extension for a given QR code string."""
+    for ext in EXTENSIONS:
+        if ext.detect(raw_qr):
+            return ext
+    # Should never reach here since C2C is catch-all, but just in case
+    return C2cExtension()
+
+
+def get_extension_by_type(payment_type: str) -> PaymentExtension:
+    """Look up extension by payment_type string (e.g. 'C2C', 'PIX')."""
+    for ext in EXTENSIONS:
+        if ext.payment_type == payment_type:
+            return ext
+    return C2cExtension()
+
+
+def get_all_endpoints() -> dict:
+    """Merge endpoints from all extensions into one dict.
+
+    Keys are prefixed with payment_type to avoid collisions.
+    e.g. 'c2c_parse_qr', 'pix_parse_qr'
+    """
+    merged = {}
+    for ext in EXTENSIONS:
+        prefix = ext.payment_type.lower()
+        for key, path in ext.endpoints.items():
+            merged[f"{prefix}_{key}"] = path
+    return merged

package/skills/binance/payment/send_extension/base.py

@@ -0,0 +1,48 @@
+"""
+PaymentExtension base class.
+
+Each payment type (C2C, PIX, ...) implements this interface.
+The main payment_skill.py dispatches to the matched extension.
+"""
+from typing import Dict, Any, Optional
+
+
+class PaymentExtension:
+    """Base class for payment type extensions."""
+
+    payment_type: str = ''   # e.g. 'C2C', 'PIX'
+    endpoints: Dict[str, str] = {}  # endpoint_key -> path
+
+    def detect(self, raw_qr: str) -> bool:
+        """Return True if this extension handles the given QR data."""
+        return False
+
+    def purchase(self, api: Any, raw_qr: str, state_helpers: Dict[str, Any]):
+        """
+        Step 1: Parse QR code and save order state.
+
+        Args:
+            api: PaymentAPI instance (for making HTTP requests)
+            raw_qr: Raw QR code string
+            state_helpers: Dict with helper functions:
+                - set_order_status(status, **fields)
+                - update_state(updates)
+                - OrderStatus enum
+        """
+        raise NotImplementedError
+
+    def build_confirm_params(self, state: Dict[str, Any], amount: str, currency: str) -> Dict[str, Any]:
+        """Build request params for confirmPayment API."""
+        raise NotImplementedError
+
+    def get_confirm_endpoint(self) -> str:
+        """Return the endpoint key for confirmPayment."""
+        raise NotImplementedError
+
+    def get_poll_endpoint(self) -> str:
+        """Return the endpoint key for queryPaymentStatus."""
+        raise NotImplementedError
+
+    def build_poll_params(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        """Build request params for queryPaymentStatus API."""
+        return {'payOrderId': state.get('pay_order_id', '')}

package/skills/binance/payment/send_extension/c2c.py

@@ -0,0 +1,193 @@
+"""
+C2C Payment Extension.
+
+Handles Binance C2C QR Code payments (URL-based QR codes).
+"""
+import json
+from typing import Dict, Any
+
+from .base import PaymentExtension
+
+# Payment type constant
+PAYMENT_TYPE_C2C = 'C2C'
+
+
+# ============================================================
+# Data Models
+# ============================================================
+class C2cParseQrResponse:
+    """Response from C2C parseQr API"""
+    def __init__(self, data: Dict[str, Any]):
+        self.checkout_id = data.get('checkoutId', '')
+        self.checkout_type = data.get('checkoutType', '')
+        self.biz_type = data.get('bizType', '')
+        self.nickname = data.get('nickname', '')
+        self.avatar_url = data.get('avatarUrl', '')
+        self.currency = data.get('currency', '')
+        self.currency_fixed = data.get('currencyFixed', False)
+        self.amount = data.get('amount')
+        self.has_preset_amount = data.get('hasPresetAmount', False)
+        self.description = data.get('description', '')
+        self.single_transaction_limit = data.get('singleTransactionLimit')
+        self.daily_limit = data.get('dailyLimit')
+
+
+class C2cConfirmPaymentResponse:
+    """Response from C2C confirmPayment API"""
+    def __init__(self, data: Dict[str, Any]):
+        self.pay_order_id = data.get('payOrderId', '')
+        self.status = data.get('status', '')
+        self.usd_amount = data.get('usdAmount')
+        self.daily_used_before = data.get('dailyUsedBefore')
+        self.daily_used_after = data.get('dailyUsedAfter')
+
+
+# ============================================================
+# C2C Extension
+# ============================================================
+class C2cExtension(PaymentExtension):
+    """C2C QR Code payment extension."""
+
+    payment_type = PAYMENT_TYPE_C2C
+
+    # OpenAPI endpoints
+    endpoints = {
+        'parse_qr': '/binancepay/openapi/user/c2c/parseQr',
+        'confirm_payment': '/binancepay/openapi/user/c2c/confirmPayment',
+        'query_payment_status': '/binancepay/openapi/user/c2c/queryPaymentStatus',
+    }
+
+    def detect(self, raw_qr: str) -> bool:
+        """C2C is the default/fallback — matches anything that isn't PIX."""
+        # C2C detection is intentionally broad; PIX is checked first in registry.
+        return True
+
+    def purchase(self, api, raw_qr: str, state_helpers: Dict[str, Any]):
+        """C2C purchase flow - Step 1: Parse C2C QR code"""
+        set_order_status = state_helpers['set_order_status']
+        update_state = state_helpers['update_state']
+        OrderStatus = state_helpers['OrderStatus']
+
+        print("🔍 [Step 1] Parsing QR code...")
+        parse_result = api.make_parsed_request(
+            self.endpoints['parse_qr'],
+            {'rawQr': raw_qr},
+            C2cParseQrResponse,
+            use_body=True
+        )
+
+        if not parse_result['success']:
+            error_status = parse_result.get('status', 'ERROR')
+            error_msg = parse_result.get('message', 'Parse QR failed')
+            error_hint = parse_result.get('hint', '')
+
+            print(f"❌ {error_msg}")
+            if error_hint:
+                print(f"💡 {error_hint}")
+
+            set_order_status(OrderStatus.FAILED, error_message=error_msg, error_code=parse_result.get('code'))
+            print(json.dumps({
+                'status': error_status,
+                'code': parse_result.get('code'),
+                'message': error_msg,
+                'hint': error_hint
+            }))
+            return
+
+        order_info = parse_result['order_info']
+
+        # Save order info to state
+        set_order_status(OrderStatus.QR_PARSED,
+            checkout_id=order_info.checkout_id,
+            biz_type=order_info.biz_type,
+            nickname=order_info.nickname,
+            avatar_url=order_info.avatar_url,
+            currency=order_info.currency or 'USDT',
+            currency_fixed=order_info.currency_fixed,
+            has_preset_amount=order_info.has_preset_amount,
+            preset_amount=str(order_info.amount) if order_info.amount else None,
+            description=order_info.description,
+            single_transaction_limit=str(order_info.single_transaction_limit) if order_info.single_transaction_limit else None,
+            daily_limit=str(order_info.daily_limit) if order_info.daily_limit else None
+        )
+
+        print(f"✅ QR Parsed Successfully")
+        print(f"   📝 Checkout ID: {order_info.checkout_id}")
+        print(f"   🏪 Payee: {order_info.nickname}")
+        print(f"   💱 Currency: {order_info.currency or 'Not specified'}")
+        if order_info.single_transaction_limit:
+            print(f"   📊 Single Limit: {order_info.single_transaction_limit} USD")
+        if order_info.daily_limit:
+            print(f"   📊 Daily Limit: {order_info.daily_limit} USD")
+        print()
+
+        # Output result based on preset amount
+        if order_info.has_preset_amount and order_info.amount:
+            currency = order_info.currency or 'USDT'
+            print("════════════════════════════════════════════════════")
+            print(f"💰 Preset Amount: {order_info.amount} {currency}")
+            print("════════════════════════════════════════════════════")
+            print()
+            print("💡 Reply 'y' to confirm payment, 'n' to cancel")
+            update_state({
+                'suggested_amount': float(order_info.amount),
+                'needs_amount_input': False,
+                'order_status': OrderStatus.AMOUNT_SET.value
+            })
+            print(json.dumps({
+                'status': 'AWAITING_CONFIRMATION',
+                'checkout_id': order_info.checkout_id,
+                'biz_type': order_info.biz_type,
+                'payment_type': PAYMENT_TYPE_C2C,
+                'payee': order_info.nickname,
+                'amount': str(order_info.amount),
+                'currency': currency,
+                'has_preset_amount': True,
+                'single_transaction_limit': str(order_info.single_transaction_limit) if order_info.single_transaction_limit else None,
+                'daily_limit': str(order_info.daily_limit) if order_info.daily_limit else None
+            }))
+        else:
+            currency = order_info.currency or 'USDT'
+            print("════════════════════════════════════════════════════")
+            print("📝 No preset amount")
+            print("════════════════════════════════════════════════════")
+            print()
+            print(f"💡 Please enter the amount (e.g., '100' or '100 USDT')")
+            update_state({
+                'needs_amount_input': True,
+                'order_status': OrderStatus.AWAITING_AMOUNT.value
+            })
+            print(json.dumps({
+                'status': 'AWAITING_AMOUNT',
+                'checkout_id': order_info.checkout_id,
+                'biz_type': order_info.biz_type,
+                'payment_type': PAYMENT_TYPE_C2C,
+                'payee': order_info.nickname,
+                'currency': currency,
+                'has_preset_amount': False,
+                'single_transaction_limit': str(order_info.single_transaction_limit) if order_info.single_transaction_limit else None,
+                'daily_limit': str(order_info.daily_limit) if order_info.daily_limit else None
+            }))
+
+    def build_confirm_params(self, state: Dict[str, Any], amount: str, currency: str) -> Dict[str, Any]:
+        """Build C2C confirmPayment params (includes bizType)."""
+        return {
+            'checkoutId': state.get('checkout_id', ''),
+            'bizType': state.get('biz_type', 'C2C_QR_CODE'),
+            'currency': currency,
+            'amount': float(amount),
+        }
+
+    def get_confirm_endpoint(self) -> str:
+        return self.endpoints['confirm_payment']
+
+    def get_poll_endpoint(self) -> str:
+        return self.endpoints['query_payment_status']
+
+    def build_poll_params(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        """C2C poll includes bizType."""
+        params = {'payOrderId': state.get('pay_order_id', '')}
+        biz_type = state.get('biz_type')
+        if biz_type:
+            params['bizType'] = biz_type
+        return params

package/skills/binance/payment/send_extension/pix.py

@@ -0,0 +1,316 @@
+"""
+PIX Payment Extension.
+
+Handles Brazilian PIX EMV QR code payments (BR Code / Copia e Cola).
+"""
+import json
+from typing import Dict, Any
+
+from .base import PaymentExtension
+
+# Payment type constant
+PAYMENT_TYPE_PIX = 'PIX'
+
+
+# ============================================================
+# Data Models
+# ============================================================
+class PixParseQrResponse:
+    """Response from Pix parseQr API"""
+    def __init__(self, data: Dict[str, Any]):
+        self.checkout_id = data.get('checkoutId', '')
+        self.status = data.get('status', '')
+        # Receiver info
+        self.receiver_name = data.get('receiverName', '')
+        self.receiver_psp = data.get('receiverPsp', '')
+        self.receiver_cnpj = data.get('receiverCnpj', '')
+        self.receiver_cpf = data.get('receiverCpf', '')
+        self.receiver_identifier = data.get('receiverIdentifier', '')
+        # Bill info
+        self.debtor_name = data.get('debtorName', '')
+        self.bill_due_date = data.get('billDueDate')
+        self.bill_amount = data.get('billAmount')
+        self.allow_amount_edit = data.get('allowAmountEdit', True)
+        # Limits (from Pix backend)
+        self.max_limit = data.get('maxLimit')
+        self.min_limit = data.get('minLimit')
+        self.limit_type = data.get('limitType', '')
+        self.limit_period_type = data.get('limitPeriodType', '')
+        # Limits (from Skills config)
+        self.single_transaction_limit = data.get('singleTransactionLimit')
+        self.daily_limit = data.get('dailyLimit')
+        # Additional info
+        self.additional_infos = data.get('additionalInfos', [])
+        self.allow_note_add = data.get('allowNoteAdd', False)
+
+    @property
+    def has_preset_amount(self) -> bool:
+        """Check if this QR has a preset amount (non-editable bill)"""
+        return (self.bill_amount is not None
+                and float(self.bill_amount) > 0
+                and not self.allow_amount_edit)
+
+    @property
+    def display_name(self) -> str:
+        """Get display name for the receiver"""
+        return self.receiver_name or self.debtor_name or 'Unknown'
+
+    @property
+    def display_document(self) -> str:
+        """Get masked document for display"""
+        if self.receiver_cnpj:
+            return f"CNPJ: {self.receiver_cnpj}"
+        if self.receiver_cpf:
+            return f"CPF: {self.receiver_cpf}"
+        return ''
+
+
+class PixConfirmPaymentResponse:
+    """Response from Pix confirmPayment API"""
+    def __init__(self, data: Dict[str, Any]):
+        self.pay_order_id = data.get('payOrderId', '')
+        self.status = data.get('status', '')
+        self.usd_amount = data.get('usdAmount')
+        self.daily_used_before = data.get('dailyUsedBefore')
+        self.daily_used_after = data.get('dailyUsedAfter')
+
+
+# ============================================================
+# PIX EMV QR Code Parser (local preview)
+# ============================================================
+def parse_pix_emv_qr(qr_string: str) -> Dict[str, Any]:
+    """
+    Parse PIX EMV QR code (TLV format) for local preview display.
+
+    This extracts merchant info from the QR data before calling the API.
+    The API response is authoritative; this is just for quick preview.
+
+    EMVCo TLV format: Tag(2) + Length(2) + Value(Length)
+
+    Key tags:
+    - 53: Transaction Currency (986=BRL)
+    - 54: Transaction Amount
+    - 58: Country Code
+    - 59: Merchant Name
+    - 60: Merchant City
+    - 26: Merchant Account Info (contains sub-TLV with br.gov.bcb.pix)
+    """
+    result = {
+        'currency': 'BRL',  # default for PIX
+        'country': 'BR',
+    }
+    try:
+        i = 0
+        while i + 4 <= len(qr_string):
+            tag = qr_string[i:i + 2]
+            length = int(qr_string[i + 2:i + 4])
+            if i + 4 + length > len(qr_string):
+                break
+            value = qr_string[i + 4:i + 4 + length]
+            i += 4 + length
+
+            if tag == '59':
+                result['merchant_name'] = value
+            elif tag == '60':
+                result['merchant_city'] = value
+            elif tag == '53':
+                result['currency_code'] = value
+                if value == '986':
+                    result['currency'] = 'BRL'
+            elif tag == '54':
+                try:
+                    result['amount'] = float(value)
+                except ValueError:
+                    result['amount_raw'] = value
+            elif tag == '58':
+                result['country'] = value
+    except Exception:
+        pass
+    return result
+
+
+# ============================================================
+# PIX Extension
+# ============================================================
+class PixExtension(PaymentExtension):
+    """PIX EMV QR Code payment extension."""
+
+    payment_type = PAYMENT_TYPE_PIX
+
+    endpoints = {
+        'parse_qr': '/binancepay/openapi/user/pix/parseQr',
+        'confirm_payment': '/binancepay/openapi/user/pix/confirmPayment',
+        'query_payment_status': '/binancepay/openapi/user/pix/queryPaymentStatus',
+    }
+
+    def detect(self, raw_qr: str) -> bool:
+        """PIX EMV QR codes contain 'br.gov.bcb.pix' as GUI identifier."""
+        if not raw_qr:
+            return False
+        return 'br.gov.bcb.pix' in raw_qr.lower()
+
+    def purchase(self, api, raw_qr: str, state_helpers: Dict[str, Any]):
+        """PIX purchase flow - Step 1: Parse PIX QR code"""
+        set_order_status = state_helpers['set_order_status']
+        update_state = state_helpers['update_state']
+        OrderStatus = state_helpers['OrderStatus']
+
+        # Show local preview from EMV data (before API call)
+        preview = parse_pix_emv_qr(raw_qr)
+        if preview.get('merchant_name') or preview.get('amount'):
+            print("📋 QR Preview (local decode):")
+            if preview.get('merchant_name'):
+                print(f"   🏪 Merchant: {preview.get('merchant_name', '')}", end='')
+                if preview.get('merchant_city'):
+                    print(f" ({preview['merchant_city']})", end='')
+                print()
+            if preview.get('amount'):
+                print(f"   💰 Amount: {preview['amount']} {preview.get('currency', 'BRL')}")
+            print()
+
+        # Call PIX parseQr API
+        print("🔍 [Step 1] Parsing PIX QR code...")
+        parse_result = api.make_parsed_request(
+            self.endpoints['parse_qr'],
+            {'rawQr': raw_qr},
+            PixParseQrResponse,
+            use_body=True
+        )
+
+        if not parse_result['success']:
+            error_status = parse_result.get('status', 'ERROR')
+            error_msg = parse_result.get('message', 'Parse QR failed')
+            error_hint = parse_result.get('hint', '')
+
+            print(f"❌ {error_msg}")
+            if error_hint:
+                print(f"💡 {error_hint}")
+
+            set_order_status(OrderStatus.FAILED, error_message=error_msg, error_code=parse_result.get('code'))
+            print(json.dumps({
+                'status': error_status,
+                'code': parse_result.get('code'),
+                'message': error_msg,
+                'hint': error_hint
+            }))
+            return
+
+        order_info = parse_result['order_info']
+
+        # Determine currency (PIX is typically BRL)
+        currency = 'BRL'
+
+        # Determine amount
+        amount = order_info.bill_amount
+        pix_has_amount = amount is not None and float(amount) > 0
+        pix_amount_locked = pix_has_amount  # True = amount from QR, cannot be changed
+
+        # Save order info to state
+        set_order_status(OrderStatus.QR_PARSED,
+            checkout_id=order_info.checkout_id,
+            biz_type='PIX',
+            nickname=order_info.display_name,
+            receiver_psp=order_info.receiver_psp,
+            receiver_document=order_info.display_document,
+            currency=currency,
+            currency_fixed=True,  # PIX is always BRL
+            has_preset_amount=pix_has_amount,
+            preset_amount=str(amount) if amount else None,
+            allow_amount_edit=not pix_amount_locked,
+            pix_amount_locked=pix_amount_locked,
+            single_transaction_limit=str(order_info.single_transaction_limit) if order_info.single_transaction_limit else None,
+            daily_limit=str(order_info.daily_limit) if order_info.daily_limit else None,
+            pix_max_limit=str(order_info.max_limit) if order_info.max_limit else None,
+            pix_min_limit=str(order_info.min_limit) if order_info.min_limit else None,
+            additional_infos=order_info.additional_infos,
+        )
+
+        print(f"✅ PIX QR Parsed Successfully")
+        print(f"   📝 Checkout ID: {order_info.checkout_id}")
+        print(f"   🏪 Receiver: {order_info.display_name}")
+        if order_info.receiver_psp:
+            print(f"   🏦 Bank: {order_info.receiver_psp}")
+        if order_info.display_document:
+            print(f"   📄 {order_info.display_document}")
+        print(f"   💱 Currency: {currency}")
+        if order_info.single_transaction_limit:
+            print(f"   📊 Single Limit: {order_info.single_transaction_limit} USD")
+        if order_info.daily_limit:
+            print(f"   📊 Daily Limit: {order_info.daily_limit} USD")
+        if order_info.additional_infos:
+            print(f"   📎 Additional Info:")
+            for info in order_info.additional_infos:
+                print(f"      {info.get('key', '')}: {info.get('value', '')}")
+        print()
+
+        # Output result based on whether QR has amount
+        if pix_has_amount:
+            print("════════════════════════════════════════════════════")
+            print(f"💰 Amount: {amount} {currency} (from QR, cannot be modified)")
+            print("════════════════════════════════════════════════════")
+            print()
+            print("💡 Reply 'y' to confirm payment, 'n' to cancel")
+            update_state({
+                'suggested_amount': float(amount),
+                'needs_amount_input': False,
+                'order_status': OrderStatus.AMOUNT_SET.value
+            })
+            print(json.dumps({
+                'status': 'AWAITING_CONFIRMATION',
+                'checkout_id': order_info.checkout_id,
+                'biz_type': 'PIX',
+                'payment_type': PAYMENT_TYPE_PIX,
+                'payee': order_info.display_name,
+                'receiver_psp': order_info.receiver_psp,
+                'amount': str(amount),
+                'currency': currency,
+                'has_preset_amount': True,
+                'pix_amount_locked': True,
+                'single_transaction_limit': str(order_info.single_transaction_limit) if order_info.single_transaction_limit else None,
+                'daily_limit': str(order_info.daily_limit) if order_info.daily_limit else None
+            }))
+        else:
+            print("════════════════════════════════════════════════════")
+            print("📝 No preset amount")
+            print("════════════════════════════════════════════════════")
+            print()
+            min_hint = f" (min: {order_info.min_limit})" if order_info.min_limit else ""
+            max_hint = f" (max: {order_info.max_limit})" if order_info.max_limit else ""
+            print(f"💡 Please enter the amount in {currency}{min_hint}{max_hint}")
+            update_state({
+                'needs_amount_input': True,
+                'order_status': OrderStatus.AWAITING_AMOUNT.value
+            })
+            print(json.dumps({
+                'status': 'AWAITING_AMOUNT',
+                'checkout_id': order_info.checkout_id,
+                'biz_type': 'PIX',
+                'payment_type': PAYMENT_TYPE_PIX,
+                'payee': order_info.display_name,
+                'receiver_psp': order_info.receiver_psp,
+                'currency': currency,
+                'has_preset_amount': False,
+                'pix_amount_locked': False,
+                'pix_min_limit': str(order_info.min_limit) if order_info.min_limit else None,
+                'pix_max_limit': str(order_info.max_limit) if order_info.max_limit else None,
+                'single_transaction_limit': str(order_info.single_transaction_limit) if order_info.single_transaction_limit else None,
+                'daily_limit': str(order_info.daily_limit) if order_info.daily_limit else None
+            }))
+
+    def build_confirm_params(self, state: Dict[str, Any], amount: str, currency: str) -> Dict[str, Any]:
+        """Build PIX confirmPayment params (no bizType needed)."""
+        return {
+            'checkoutId': state.get('checkout_id', ''),
+            'currency': currency,
+            'amount': float(amount),
+        }
+
+    def get_confirm_endpoint(self) -> str:
+        return self.endpoints['confirm_payment']
+
+    def get_poll_endpoint(self) -> str:
+        return self.endpoints['query_payment_status']
+
+    def build_poll_params(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        """PIX poll does NOT include bizType."""
+        return {'payOrderId': state.get('pay_order_id', '')}

package/skills/binance/square-post/README.md

@@ -0,0 +1,62 @@
+# Square Post Skill
+
+Publish text, image, article, and video posts to Binance Square through the
+local Node.js scripts in `scripts/`.
+
+## Dependencies
+
+### Runtime
+
+- Node.js 18 or newer. The scripts use native ES modules and the built-in
+  `fetch` API.
+- Bash-capable shell for running the scripts through the agent tool.
+
+### System Tools
+
+- `ffmpeg` is required for video posts. `scripts/post-video.mjs` extracts the
+  first frame from the source video and uploads it as the post cover.
+- `ffprobe` is required when the user does not provide a video duration. The
+  agent uses it to determine the duration before calling `post-video.mjs`.
+
+### External Services
+
+- Binance Square OpenAPI access through `BINANCE_SQUARE_OPENAPI_KEY` or the
+  local saved key file.
+- Network access to the Square OpenAPI endpoints and to presigned upload URLs
+  returned by the API.
+
+No npm package install is required for the current scripts; they only use
+Node.js built-in modules.
+
+## Authentication
+
+Scripts read the OpenAPI key in this order:
+
+1. `BINANCE_SQUARE_OPENAPI_KEY`
+2. The saved key file at `~/.config/binance-square/openapi-key`
+
+Do not pass API keys as CLI arguments. `--key` is rejected because command-line
+arguments can appear in process listings and shell history.
+
+To save a key for future runs, explicitly run:
+
+```bash
+BINANCE_SQUARE_OPENAPI_KEY=<apiKey> node scripts/save-key.mjs
+```
+
+The saved key file is written with `0600` permissions. To remove it, delete
+`~/.config/binance-square/openapi-key`.
+
+## Directory Structure
+
+```
+square-post/
+├── SKILL.md              # Skill instructions and publishing workflow
+├── README.md             # Directory overview
+├── scripts/
+│   ├── lib.mjs           # Shared API, upload, polling, and publish helpers
+│   ├── save-key.mjs      # Saves the OpenAPI key to a local private config file
+│   ├── post-text.mjs     # Text and article publishing script
+│   ├── post-image.mjs    # Image post and article-with-cover publishing script
+│   └── post-video.mjs    # Video publishing script with generated cover
+```