@acedatacloud/skills 2026.613.0 → 2026.614.0

package/AGENTS.md

@@ -26,6 +26,9 @@ Skills are located in the `skills/` directory (also mirrored to `.agents/skills/
 - **seedance-video** — Generate dance/motion videos with ByteDance Seedance
 - **wan-video** — Generate videos with Alibaba Wan
 
+### Video Production (workflow)
+- **marketing-video-factory** — Produce a short-form marketing/feature video end-to-end (orchestrates the media skills: generate assets → capture UI → assemble with FFmpeg → distribute)
+
 ### AI Chat & Tools
 - **ai-chat** — Unified LLM gateway — GPT, Claude, Gemini, Kimi, Grok (50+ models)
 - **google-search** — Search the web, images, news, maps, places, and videos via Google

package/README.md

@@ -42,6 +42,12 @@ Compatible with **30+ AI coding agents** via the [agentskills.io](https://agents
 | [hailuo-video](skills/hailuo-video/) | Generate videos with Hailuo / MiniMax |
 | [seedance-video](skills/seedance-video/) | Generate dance/motion videos with ByteDance Seedance |
 
+### Video Production (workflow)
+
+| Skill | Description |
+|-------|-------------|
+| [marketing-video-factory](skills/marketing-video-factory/) | Produce a short-form marketing/feature video end-to-end — generate assets + capture UI + assemble (FFmpeg) + distribute |
+
 ### AI Chat & Tools
 
 | Skill | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acedatacloud/skills",
-  "version": "2026.613.0",
+  "version": "2026.614.0",
   "description": "Agent Skills for AceDataCloud AI services — music, image, video generation, LLM chat, web search. Compatible with Claude Code, GitHub Copilot, Gemini CLI, OpenAI Codex, and 30+ AI coding agents.",
   "keywords": [
     "agent-skills",

package/skills/blogger/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: blogger
+description: Publish posts to your Blogger blog and read your blogs / posts via the Blogger API v3. Use when the user mentions Blogger, blogspot, publishing a post to their blog, listing their blogs, or updating an existing Blogger post.
+when_to_use: |
+  Trigger when the user wants to publish a post to their Blogger blog,
+  list their blogs, list / read posts on a blog, or update an existing
+  post. The connector grants the Blogger scope (read + write); confirm
+  before publishing publicly (you can insert as a draft first).
+connections: [google/blogger]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+Call the **Blogger API v3** with `curl + jq`. The user's OAuth bearer token is
+in `$GOOGLE_BLOGGER_TOKEN`; every call needs
+`Authorization: Bearer $GOOGLE_BLOGGER_TOKEN`. Base URL:
+`https://www.googleapis.com/blogger/v3`.
+
+Errors are `{"error": {"code": ..., "message": ...}}` — show them verbatim.
+`401` → token expired, re-connect the Blogger connector.
+
+**Always start by listing the user's blogs** to get a `blogId`:
+
+```bash
+curl -sS -H "Authorization: Bearer $GOOGLE_BLOGGER_TOKEN" \
+  "https://www.googleapis.com/blogger/v3/users/self/blogs" \
+  | jq '.items[] | {id, name, url}'
+```
+
+## Publish a post
+
+**Confirm before publishing publicly.** Use `?isDraft=true` to stage a draft.
+
+```bash
+BLOG_ID="1234567890"
+jq -n --arg t "My title" --arg c "<p>HTML content of the post…</p>" \
+  '{kind:"blogger#post", title:$t, content:$c, labels:["ai","video"]}' \
+| curl -sS -X POST \
+    "https://www.googleapis.com/blogger/v3/blogs/$BLOG_ID/posts/?isDraft=false" \
+    -H "Authorization: Bearer $GOOGLE_BLOGGER_TOKEN" \
+    -H "Content-Type: application/json" \
+    -d @- \
+| jq '{id, url, status}'
+```
+
+`content` is **HTML** (not Markdown) — convert Markdown to HTML first
+(e.g. with `pandoc -f markdown -t html` or a simple converter).
+
+- Publish a staged draft: `POST /blogs/{blogId}/posts/{postId}/publish`.
+- Update a post: `PUT /blogs/{blogId}/posts/{postId}` with the same shape.
+
+## List / read posts
+
+```bash
+curl -sS -H "Authorization: Bearer $GOOGLE_BLOGGER_TOKEN" \
+  "https://www.googleapis.com/blogger/v3/blogs/$BLOG_ID/posts?maxResults=20&status=live" \
+  | jq '.items[] | {id, title, url, published}'
+```
+
+## Gotchas
+
+- **Enable the Blogger API** on the Google Cloud project backing the OAuth
+  client, or calls 403 with `accessNotConfigured`.
+- `content` must be HTML; passing raw Markdown will render literally.
+- Paginate with `&pageToken=$PAGE_TOKEN` from the previous `.nextPageToken`.

package/skills/devto/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: devto
+description: Publish, update and read articles on DEV (dev.to) via the Forem API v1. Use when the user mentions dev.to / DEV Community, publishing a blog post to dev.to, cross-posting an article, updating a published post, or listing their dev.to articles and stats.
+when_to_use: |
+  Trigger when the user wants to publish a Markdown article to their
+  dev.to account, update a previously published article, or list /
+  inspect their own dev.to articles (views, reactions, comments). The
+  connector stores a DEV API Key with full account access — confirm
+  before publishing publicly (you can publish as a draft with
+  published=false first).
+connections: [devto]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+Call the **Forem API v1** (dev.to) with `curl + jq`. The user's API key is in
+`$DEVTO_API_KEY`; every call needs the headers `api-key: $DEVTO_API_KEY` and
+`Accept: application/vnd.forem.api-v1+json`. Base URL: `https://dev.to/api`.
+
+Errors come back as JSON with an `error` / `status` field — show them verbatim.
+`401` means the API key is invalid → the user must re-connect the DEV connector.
+
+**Always start by confirming the key** and learning the account:
+
+```bash
+curl -sS -H "api-key: $DEVTO_API_KEY" -H "Accept: application/vnd.forem.api-v1+json" \
+  "https://dev.to/api/users/me" | jq '{username, name}'
+```
+
+## Publish an article
+
+**Confirm with the user before publishing publicly.** Default to a draft
+(`published:false`) unless they explicitly say publish/now.
+
+```bash
+TITLE="My title"
+BODY_MD="$(cat article.md)"   # full Markdown body
+jq -n --arg t "$TITLE" --arg b "$BODY_MD" \
+  '{article:{title:$t, body_markdown:$b, published:false, tags:["ai","webdev"]}}' \
+| curl -sS -X POST "https://dev.to/api/articles" \
+    -H "api-key: $DEVTO_API_KEY" \
+    -H "Accept: application/vnd.forem.api-v1+json" \
+    -H "Content-Type: application/json" \
+    -d @- \
+| jq '{id, url, published}'
+```
+
+To publish a draft later (or edit), `PUT /api/articles/{id}` with the same
+shape (set `published:true`). Front-matter inside `body_markdown` (a `---`
+block) can also carry `title`, `tags`, `series`, `canonical_url`, `cover_image`.
+
+- **Canonical URL:** when cross-posting, set
+  `"canonical_url":"https://your-blog/original"` so DEV points SEO back to the
+  source — important for the article→video / cross-publishing flow.
+
+## List / inspect my articles
+
+```bash
+# My published + draft articles (paginated; per_page max 1000).
+curl -sS -H "api-key: $DEVTO_API_KEY" -H "Accept: application/vnd.forem.api-v1+json" \
+  "https://dev.to/api/articles/me/all?per_page=30" \
+  | jq '.[] | {id, title, published, page_views_count, public_reactions_count, comments_count}'
+
+# A single article's full content + stats.
+curl -sS -H "api-key: $DEVTO_API_KEY" -H "Accept: application/vnd.forem.api-v1+json" \
+  "https://dev.to/api/articles/ARTICLE_ID" | jq '{title, url, reactions: .public_reactions_count, views: .page_views_count}'
+```
+
+## Gotchas
+
+- **Tags:** max 4, lowercase, no spaces (e.g. `webdev`, `machinelearning`).
+- **Rate limit:** article create/update is throttled (a few per 30s); space out
+  bulk publishes or you'll get `429`.
+- `body_markdown` is the source of truth — if you put a `---` front-matter block
+  at the top, its fields override the JSON `article` fields.

package/skills/linkedin/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: linkedin
+description: Publish text / link posts to your LinkedIn personal feed via the LinkedIn Posts API. Use when the user mentions LinkedIn, sharing or posting an update to LinkedIn, or cross-posting an article / link to their LinkedIn feed.
+when_to_use: |
+  Trigger when the user wants to publish a text or link share to their
+  own LinkedIn feed. Posting is public on their profile — confirm the
+  text (and link, if any) before publishing. Requires the
+  w_member_social scope (granted by the connector at install).
+connections: [linkedin]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+Call the **LinkedIn API** with `curl + jq`. The user's bearer token is in
+`$LINKEDIN_TOKEN`; every call needs `Authorization: Bearer $LINKEDIN_TOKEN`.
+
+LinkedIn posts must be authored by the member's URN. Get the member id from the
+OpenID userinfo endpoint, then build `urn:li:person:{sub}`.
+
+```bash
+SUB=$(curl -sS -H "Authorization: Bearer $LINKEDIN_TOKEN" \
+  "https://api.linkedin.com/v2/userinfo" | jq -r .sub)
+AUTHOR="urn:li:person:$SUB"
+echo "$AUTHOR"
+```
+
+Errors are JSON with `message` / `serviceErrorCode` — show them verbatim.
+`401` → token expired (tokens last ~60 days), re-connect the LinkedIn connector.
+
+## Publish a post (Posts API)
+
+**Confirm the text with the user first.** Use the versioned Posts API; set the
+`LinkedIn-Version` header to a recent `YYYYMM` (LinkedIn requires a valid recent
+version — if you get `426`/version errors, bump to the current month).
+
+```bash
+jq -n --arg a "$AUTHOR" --arg t "My update text. Check out https://studio.acedata.cloud" \
+  '{author:$a, commentary:$t, visibility:"PUBLIC",
+    distribution:{feedDistribution:"MAIN_FEED", targetEntities:[], thirdPartyDistributionChannels:[]},
+    lifecycleState:"PUBLISHED", isReshareDisabledByAuthor:false}' \
+| curl -sS -X POST "https://api.linkedin.com/rest/posts" \
+    -H "Authorization: Bearer $LINKEDIN_TOKEN" \
+    -H "Content-Type: application/json" \
+    -H "LinkedIn-Version: 202401" \
+    -H "X-Restli-Protocol-Version: 2.0.0" \
+    -d @- -D - -o /dev/null | tr -d '\r' | awk '/^[Xx]-[Rr]estli-[Ii]d:|^[Ll]ocation:/{print}'
+```
+
+A successful create returns `201` with the post URN in the `x-restli-id`
+(or `Location`) response header — report that URN / the resulting post URL.
+
+> Link posts: put the URL inline in `commentary` (LinkedIn auto-unfurls it).
+> Rich article attachments need the assets/images API — out of scope for a
+> simple text/link share; keep links inline.
+
+## Fallback: legacy ugcPosts
+
+If the versioned endpoint is unavailable for the app, the older
+`POST https://api.linkedin.com/v2/ugcPosts` with a
+`specificContent."com.linkedin.ugc.ShareContent"` body also works with
+`w_member_social`. Prefer `/rest/posts` above.
+
+## Gotchas
+
+- **Author URN** must match the token's member (`urn:li:person:{sub}`) — you
+  can't post as someone else.
+- `w_member_social` only allows posting to the **member's own feed**; company
+  Page posts need `w_organization_social` + an admin role (not in this connector).
+- The `LinkedIn-Version` header is mandatory for `/rest/*`; a stale value
+  returns a version error — bump to the current `YYYYMM`.

package/skills/marketing-video-factory/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: marketing-video-factory
+description: Produce a short-form (9:16, ~30-60s) marketing / feature-explainer video end-to-end using AceDataCloud's own AI APIs — generate B-roll + hero images (Flux/Seedream/NanoBanana/Seedance), a music bed (Suno) and voiceover (TTS), capture real product UI with Playwright, assemble with FFmpeg (burned-in captions), upload to CDN, then distribute. Use when the user wants to make a promo/feature/explainer video, a TikTok/Reels/Shorts/Bilibili/Douyin short, "automated video marketing", or to turn a product feature into a vertical video.
+when_to_use: |
+  Trigger when the user wants to PRODUCE a finished short-form video
+  (not just call one model): a marketing/feature/promo/explainer short,
+  a vertical video for TikTok / YouTube Shorts / Reels / Bilibili /
+  Douyin / X / LinkedIn, or an "automated video factory". This skill is
+  the playbook that orchestrates the single-service skills
+  (flux-image, seedream-image, nano-banana-image, seedance-video,
+  veo-video, suno-music, fish-audio, short-url) into one pipeline.
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+compatibility: Requires ACEDATACLOUD_API_TOKEN (model calls) and ACEDATACLOUD_PLATFORM_TOKEN (CDN upload) in .env (see _shared/authentication.md). Needs ffmpeg, python3 + pillow, and (for screenshots) playwright. Optionally pair with the per-service MCP servers (_shared/mcp-servers.md).
+---
+
+# Marketing Video Factory
+
+Turn a product feature into a platform-ready vertical short, made **with the same
+AI APIs you're advertising** (so the video is also a live demo of itself).
+
+> **Setup:** [authentication](../_shared/authentication.md) · async behavior:
+> [async task polling](../_shared/async-tasks.md) · tool-use: [MCP servers](../_shared/mcp-servers.md).
+
+## Strategy (read first)
+
+1. **Dogfood.** Generate every asset through `api.acedata.cloud` (Flux, Seedream,
+   NanoBanana, Seedance/Veo, Suno, TTS). The output *is* the proof.
+2. **Real UI is the spine; AI footage is the spice.** For a software/dev product,
+   show real screen-captures/screenshots of the product for the demo beats;
+   reserve AI-generated clips for intro / atmosphere / transitions. AI models
+   hallucinate fake buttons/code → never use them to depict the actual product.
+3. **Structure every video:** `Hook (0-3s) → Value (4-15s) → Demo (16-50s) →
+   CTA (last ~5s)`. One cut every 2-4s. Captions always on (≈85% watch muted).
+
+## Workflow
+
+1. **Brief** the feature: pull real value-prop copy from your docs (verbatim
+   on-screen text beats invented copy).
+2. **Script** a Scene-JSON: per scene = `{visual, duration, caption}`, following
+   the hook→value→demo→CTA skeleton.
+3. **Generate assets** (async — submit then poll): hero/B-roll images, B-roll
+   clips, a music bed, voiceover. Use `watermark=false`. Pin aspect to 9:16.
+4. **Capture UI** screenshots with Playwright (mobile 9:16 viewport).
+5. **Assemble** with FFmpeg: per-scene render → concat → mix music. Burn captions.
+6. **Upload** the final MP4 to the CDN; **distribute** per platform.
+
+## Recipe — generate an asset (submit + poll)
+
+```bash
+# Hero / B-roll image. Flux & NanoBanana honor true 9:16; Seedream size is an
+# ENUM (1K/2K/...) and tends to return 16:9 — use Flux for vertical heroes.
+curl -sS -X POST https://api.acedata.cloud/flux/images \
+  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" -H "Content-Type: application/json" \
+  -d '{"model":"flux-2-pro","prompt":"<scene visual>, deep violet/indigo, cinematic, no text","size":"9:16"}'
+
+# B-roll clip (Seedance is fast/cheap; Veo for hero quality). watermark off.
+curl -sS -X POST https://api.acedata.cloud/seedance/videos \
+  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" -H "Content-Type: application/json" \
+  -d '{"model":"doubao-seedance-2-0-fast-260128","content":[{"type":"text","text":"<motion>, 9:16, no text"}],"resolution":"720p","ratio":"9:16","duration":5,"watermark":false}'
+
+# Music bed — instrumental (see suno-music). Then poll /suno/tasks.
+curl -sS -X POST https://api.acedata.cloud/suno/audios \
+  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" -H "Content-Type: application/json" \
+  -d '{"action":"generate","prompt":"uplifting minimal electronic, premium tech","instrumental":true,"model":"chirp-v5-5"}'
+```
+
+All of the above return a `task_id` — **poll the matching `/<service>/tasks`** until
+`state`/`status` is terminal, then read the media URL (see _shared/async-tasks.md).
+The media is served from `*.cdn.acedata.cloud`. Per-model details: `flux-image`,
+`seedream-image`, `nano-banana-image`, `seedance-video`, `veo-video`, `suno-music`,
+`fish-audio` skills. (Voiceover: `POST /text-to-speech`, keep word timings for
+karaoke captions.)
+
+## Recipe — capture product UI (Playwright)
+
+```python
+# pip install playwright && python -m playwright install chromium
+from playwright.sync_api import sync_playwright
+with sync_playwright() as p:
+    b = p.chromium.launch(headless=True)
+    # 9:16 viewport so a vertical video doesn't center-crop a desktop layout.
+    ctx = b.new_context(viewport={"width":1080,"height":1920}, device_scale_factor=2,
+                        storage_state="auth.json")  # omit for public pages
+    pg = ctx.new_page(); pg.goto(URL, wait_until="networkidle"); pg.wait_for_timeout(3500)
+    pg.screenshot(path="shot.png")
+```
+
+**Public marketing pages capture anonymously; logged-in console/app pages need a
+saved `storage_state`** (a throwaway demo account) — without it they redirect to
+the login wall.
+
+## Recipe — assemble (per-scene render → concat → music)
+
+Do **NOT** build one giant filtergraph with all inputs — with several hi-res
+images + caption PNGs it OOMs ("Cannot allocate memory"). Render each scene
+to an intermediate, then concat (stream-copy), then mux music:
+
+```bash
+W=1080; H=1920; FPS=30
+SCALE="scale=$W:$H:force_original_aspect_ratio=increase,crop=$W:$H,setsar=1,fps=$FPS"
+
+# Per scene: a still (loop to DUR) or a clip (trim to DUR) + a transparent
+# caption PNG overlaid. Produce identical-codec segNN.mp4 (no audio).
+ffmpeg -y -loop 1 -t $DUR -i still.png  -loop 1 -i capNN.png \
+  -filter_complex "[0:v]$SCALE[bg];[bg][1:v]overlay=0:0:shortest=1[v]" \
+  -map "[v]" -an -t $DUR -c:v libx264 -pix_fmt yuv420p -r $FPS \
+  -video_track_timescale 15360 segNN.mp4
+# (for a clip scene: replace "-loop 1 -t $DUR -i still.png" with "-i clip.mp4")
+
+# Concat (all segments share codec/params) + mix music under, with a fade-out.
+printf "file 'seg00.mp4'\nfile 'seg01.mp4'\n..." > segs.txt
+ffmpeg -y -f concat -safe 0 -i segs.txt -c copy video_silent.mp4
+ffmpeg -y -i video_silent.mp4 -i music.mp3 \
+  -filter_complex "[1:a]volume=-3dB,afade=t=out:st=$(($TOTAL-1)):d=1[a]" \
+  -map 0:v -map "[a]" -c:v copy -c:a aac -shortest one-api-key.mp4
+```
+
+Captions: render each as a **transparent PNG** (Pillow) and overlay — portable
+across all ffmpeg builds (avoids the libfreetype `drawtext` dependency). Use a
+real bold sans (`C:/Windows/Fonts/arialbd.ttf`, `DejaVuSans-Bold.ttf`, etc.),
+3-7 words/line, white + black stroke; push to the **upper third during UI demos**
+so the product stays visible.
+
+> Reference implementation (Scene-JSON contract, caption-burn, render driver,
+> material-library convention): **AceDataCloud/PlatformStudio** (`app/`,
+> `scripts/build_video.py`, `assets/MATERIALS.md`).
+
+## Recipe — upload to CDN + distribute
+
+```bash
+curl -sS -X POST https://platform.acedata.cloud/api/v1/files/ \
+  -H "Authorization: Bearer $ACEDATACLOUD_PLATFORM_TOKEN" \
+  -F "file=@one-api-key.mp4"   # -> {"file_url":"https://cdn.acedata.cloud/....mp4"}
+```
+
+Distribute with a short link (`short-url` skill) + per-platform metadata. Author
+once at 1080×1920 inside a centered 900×1400 safe box, then atomize to 16:9 / 1:1.
+
+## Creative cheat-sheet
+
+- **Length:** TikTok 15-34s · Shorts/Reels 30-60s · X <60s · LinkedIn 30-90s.
+- **Captions:** always on, karaoke word-highlight, avoid bottom ~20-25% & right edge.
+- **Audio:** final mix ≈ **−14 LUFS**, music **15-20 dB under** voice; sidechain-duck
+  (`sidechaincompress`) the music off the narration; `loudnorm=I=-14:TP=-1:LRA=11`.
+- **CTA:** one clear visual CTA in the last ~5s (assume muted).
+
+## Gotchas
+
+- **Generation is async** — every model call returns a `task_id`; poll the
+  service's `/tasks` endpoint. Don't treat the first response as the result.
+- **Aspect:** pin 9:16 explicitly. `seedream` `size` is an enum (1K/2K/3K/4K) and
+  skews 16:9 → use **Flux** (`size:"9:16"`) or **NanoBanana** (`aspect_ratio`) for
+  true vertical heroes.
+- **`watermark:false`** on marketing assets (Seedance/Seedream default to true).
+- **Single mega-filtergraph OOMs** on multi-input hi-res jobs → render per-scene
+  then `concat -c copy` (above).
+- **Screenshots:** use a **9:16 viewport** (not a desktop one center-cropped);
+  logged-in pages need a saved Playwright `storage_state`.
+- **CDN download SSL:** some hosts (e.g. `cdn1.suno.ai`) fail Python `urllib`
+  cert verification → fetch with `curl -L` instead.
+- **Music licensing:** Suno free tier is **non-commercial**; paid plans give no
+  indemnification → for **paid ads** use a fully-licensed library; keep Suno for
+  organic. Master to −14 LUFS regardless.
+- **Don't hard-couple the video model** — keep it swappable (Veo/Seedance/Luma);
+  abstract the provider so a deprecation (e.g. a Sora API sunset) is a 1-line change.
+- **Cross-posting:** strip watermarks before re-uploading; rewrite title/hashtags
+  per platform; keep Instagram reposts <10 / 30 days; use a humane cadence (bursts
+  read as spam).

package/skills/reddit/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: reddit
+description: Submit posts (link or text) to subreddits and read your Reddit identity / content via the Reddit API. Use when the user mentions Reddit, posting to a subreddit, submitting a link or self-post, or checking their Reddit profile / submissions.
+when_to_use: |
+  Trigger when the user wants to submit a post to a subreddit (link or
+  self/text post), or read their own Reddit identity and submissions.
+  Posting to a subreddit is public and subject to that subreddit's rules
+  / karma requirements — confirm the target subreddit, title and body
+  before submitting.
+connections: [reddit]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+Call the **Reddit API** (OAuth endpoints) with `curl + jq`. The user's bearer
+token is in `$REDDIT_TOKEN`. **Every call MUST send a `User-Agent` header** or
+Reddit returns `429`. Use the OAuth host `https://oauth.reddit.com`.
+
+```bash
+UA="web:cloud.acedata.connectors:v1.0 (by /u/acedatacloud)"
+```
+
+Errors are JSON; a submit returns `{"json":{"errors":[...], "data":{...}}}` —
+if `errors` is non-empty, show them verbatim. `401` → token expired, re-connect.
+
+**Always start by confirming identity:**
+
+```bash
+curl -sS -H "Authorization: Bearer $REDDIT_TOKEN" -H "User-Agent: $UA" \
+  "https://oauth.reddit.com/api/v1/me" | jq '{name, total_karma, link_karma}'
+```
+
+## Submit a post
+
+**Confirm the subreddit + title + body with the user first.** `sr` is the
+subreddit name WITHOUT the `r/` prefix.
+
+```bash
+# Self (text) post: kind=self + text. Link post: kind=link + url.
+curl -sS -X POST "https://oauth.reddit.com/api/submit" \
+  -H "Authorization: Bearer $REDDIT_TOKEN" -H "User-Agent: $UA" \
+  --data-urlencode "sr=test" \
+  --data-urlencode "kind=self" \
+  --data-urlencode "title=My title" \
+  --data-urlencode "text=My self-post body in markdown" \
+  --data-urlencode "api_type=json" \
+  | jq '.json | {errors, url: .data.url, id: .data.id}'
+```
+
+For a link post:
+
+```bash
+curl -sS -X POST "https://oauth.reddit.com/api/submit" \
+  -H "Authorization: Bearer $REDDIT_TOKEN" -H "User-Agent: $UA" \
+  --data-urlencode "sr=test" --data-urlencode "kind=link" \
+  --data-urlencode "title=My title" --data-urlencode "url=https://example.com" \
+  --data-urlencode "api_type=json" | jq '.json'
+```
+
+## Read my submissions
+
+```bash
+curl -sS -H "Authorization: Bearer $REDDIT_TOKEN" -H "User-Agent: $UA" \
+  "https://oauth.reddit.com/user/USERNAME/submitted?limit=10" \
+  | jq '.data.children[] | .data | {title, subreddit, ups, num_comments, permalink}'
+```
+
+## Gotchas
+
+- **User-Agent is mandatory** on every request — omitting it → `429`.
+- Many subreddits gate posting on **account age / karma / flair**; a submit can
+  return `errors` like `[["SUBREDDIT_NOTALLOWED", ...]]` — surface it and try
+  `r/test` to validate the flow.
+- Respect rate limits: read the `X-Ratelimit-Remaining` response header; space
+  out bulk submits.
+- Use `r/test` as a safe target when validating that the connection works.