@easysociable/cli 0.1.17 → 0.1.19

package/skills/easysociable-tweet-image/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: easysociable-tweet-image
+description: >
+  Turn one or many X (Twitter) posts into clean PNG images with the `easysociable tweets render`
+  CLI. Use when the user pastes x.com / twitter.com status links (or tweet ids) and wants
+  images, screenshots or "cards" of them — e.g. "tweet to image", "turn these tweets into
+  pictures", "推文转图片", "把这几条推特做成图". One link → one PNG; never a carousel.
+  Do not use for writing new tweets, multi-slide carousels (use easysociable-slideshow), or
+  scraping profiles/timelines.
+---
+
+# EasySociable Tweet Image
+
+Renders each X post as its own PNG: avatar, display name, verified badge, @handle, text,
+up to 4 media thumbnails, timestamp and reply/like counts on a gradient background.
+Tweets are fetched through the EasySociable gateway (login required, free quota) and
+rendered locally on this machine.
+
+## Run
+
+```bash
+easysociable tweets render <link-or-id> [more links…] --json
+easysociable tweets render --file links.txt --json      # one link per line
+```
+
+| Flag | Default | Values |
+|---|---|---|
+| `--size` | `auto` | `auto` (card height fits the tweet) · `4:5` · `3:4` · `9:16` · `1:1` |
+| `--theme` | `light` | `light` · `dark` |
+| `--background` | `plum-plate` | `none` · `#hex` · `plum-plate` `sunset` `oceanic` `hyper` `cotton-candy` `gotham-dark` `neon` `emerald` `night-fade` `midnight` |
+| `--hide-metrics` | off | hide reply/like counts |
+| `--out` | `./tweets` | output folder; files are `tweet-<handle>-<id>.png` |
+
+If the command says `EASYSOCIABLE_API_KEY is required`, ask the user to run
+`easysociable auth login` (opens the browser), then retry.
+
+## Rules
+
+1. **Never rewrite, translate, summarize or "fix" tweet text.** The image must show the post exactly as published. Same for author name, @handle and avatar — do not swap or hide them.
+2. **One link → one image.** Do not merge tweets, build threads or carousels. Duplicates are rendered once.
+3. **Do not ask about size, theme or background up front.** Use the defaults unless the user already said what they want (e.g. "for Instagram" → `--size 4:5`, "for Stories/TikTok" → `--size 9:16`, "dark mode" → `--theme dark`, "no background"/"transparent" → `--background none`).
+4. **Failures are final, not something to work around.** `TWEET_NOT_FOUND` (deleted), `TWEET_UNAVAILABLE` (protected, age-restricted, suspended) and `INVALID_TWEET_URL` must be reported as failed. Never reconstruct a tweet from memory, search results or another site.
+5. `RATE_LIMITED` is retried automatically; if it still fails, tell the user to rerun just the failed links in a minute. `UPSTREAM_UNAVAILABLE` → suggest retrying later.
+6. Pass every link the user gave in one command (batch); don't loop one call per link.
+
+## Report
+
+Exit code 1 means at least one item failed; the others still rendered. Reply with a short
+per-link table from the `--json` items:
+
+| Link | Result |
+|---|---|
+| x.com/jack/status/20 | `./tweets/tweet-jack-20.png` |
+| x.com/foo/status/123 | failed — deleted (`TWEET_NOT_FOUND`) |
+
+Mention `warnings` only if present (e.g. avatar or media could not be downloaded, so a
+placeholder was used). Repost and view counts are not available from X and are never shown.

package/skills/easysociable-template/workflows/MULTI_PLATFORM_FAMILY.md

@@ -1,81 +0,0 @@
-# Multi-platform Layout Family (default create path)
-
-**SoT for creating templates that ship on several platforms at once.**  
-One user-facing **Layout Family**; one **master** canvas page; additional **variant** pages per aspect preset. Studio switches variants with platform chips — it does not resize one AST (ADR-0033).
-
-Single-page ≠ single-platform. Still never create slideshow/carousel packs (`OUT_OF_SCOPE.md`).
-
-## Default when the user asks to create a template
-
-Unless they explicitly want **one platform only**:
-
-1. Lock a **master** platform + recommended canvas (`PLATFORM_SPECS.md`).
-2. Create the master draft (Family is created with it).
-3. **Derive** missing vertical presets for the family.
-4. **Hand-tune** each variant’s absolute layout (do not ship raw derive output for dense pages).
-5. Visual-QA master + each variant, then hand off Studio with chip switching.
-
-### Default vertical bucket (most social covers)
-
-| Role | Preset | Pixels | Platforms on that variant |
-|---|---|---|---|
-| Master (typical) | `3:4` | 1080×1440 | `xiaohongshu` |
-| Variant | `4:5` | 1080×1350 | `instagram` + `threads` (shared tree) |
-| Variant | `9:16` | 1080×1920 | `tiktok` |
-| Variant | `1:1` | 1080×1080 | `linkedin` |
-
-If the user’s primary platform is already `4:5` / `9:16` / `1:1`, that page is master; derive the other presets in the bucket (see Gateway `defaultDerivePolicyForPreset`).
-
-Skip or trim targets only when the user names a subset (“只要 IG 和 LinkedIn”).
-
-## CLI
-
-```bash
-# After create-draft, read familyId from the draft view (or families list)
-easysociable templates families get --id <familyId> --json
-
-# Create missing presets (idempotent; use --presets to limit)
-easysociable templates families derive --id <familyId> --presets 4:5,9:16,1:1 --json
-
-# Hand-tuned layout per variant pageId
-easysociable templates update-draft --id <variantPageId> --file ./variant-4x5.patch.json --json
-```
-
-Gateway equivalents: `GET/POST /v1/template-families/:id`, `POST /v1/template-families/:id/derive`.
-
-If CLI `--json` fails Zod on new family fields (`familyId`, `variants`, …) but HTTP succeeded, re-fetch with `families get` / `list-drafts` or raw Gateway — do not assume create/derive failed.
-
-## Hand-tune rules (required after derive)
-
-`derive` applies pin `v1_vertical` (scale + bottom/center corrections). That is a **starting point**, not shippable layout for dense covers.
-
-For **each** variant page:
-
-1. Keep the **same slots / copy / icons** as master (same `data-variable` keys).
-2. Rebuild absolute geometry for the target `canvas` (`width`/`height` + root Graphic size must match preset pixels).
-3. Distribute vertical rhythm across the full board: even section gaps; **no** packed header + empty foot.
-4. TikTok `9:16`: keep critical UI out of bottom ~120–160px chrome.
-5. JSX styles must be `style={{ ... }}` (double braces). Python f-strings turn `{{` into `{` — validate with Babel/`validate-authoring-source.mjs` before update.
-6. Per-variant `selectionMetadata.platforms` / `canvasPreset` / `canvas` must match that page only (IG+Threads both listed on the `4:5` page).
-7. Theme/preview tokens stay on the **Family** (`preview_tokens` via `theme.create` on draft) — not a TemplateTheme row (`THEME_TOKENS.md`, ADR-0033).
-
-```bash
-node scripts/validate-authoring-source.mjs ./variant-4x5.authoring.json
-easysociable templates update-draft --id <variantPageId> --file ./variant-4x5.patch.json --json
-```
-
-## Visual QA
-
-Run `VISUAL_QA.md` on the **master** and **each derived preset** (screenshot Studio at that draft URL / platform chip). Fail if any variant has clipped content, overlapping bands, or large empty voids with cramped clusters.
-
-## Handoff
-
-After QA, open the **master** Studio URL and tell the user they can switch platforms with the top-bar chips (each chip is a real canvas variant). Save still applies to the active variant; Agent publish remains post-Save (`PUBLISH_FROM_DRAFT.md`). Include every variant `pageId` + preset in the handoff notes.
-
-## Do not
-
-- Author one AST and claim it fits 3:4 + 9:16 + 1:1
-- Leave dense pages on raw derive output
-- Put Instagram and Threads on different presets when both are 4:5
-- Create a second Family for the same template identity
-- Treat multi-platform variants as a slideshow / carousel pack