@otto-assistant/otto 0.1.1 → 0.7.15

package/skills/x-articles/SKILL.md

@@ -0,0 +1,554 @@
+---
+name: x-articles
+description: >
+  Edit x.com (Twitter) long-form article drafts reliably. Use this for
+  markdown imports, bulk formatting, code blocks, headings, lists, and
+  repeated inline styling. Inspect and validate with Playwriter, but prefer
+  x.com (Twitter) article GraphQL mutations for deterministic updates.
+version: 0.1.0
+---
+
+<!-- Skill for editing x.com (Twitter) article drafts through Playwriter plus content-state mutations. -->
+
+Use this skill when editing long-form article drafts on `x.com/compose/articles`
+(Twitter Articles).
+
+## Read Playwriter First
+
+Before using this skill, read the `playwriter` skill and run:
+
+```bash
+playwriter skill
+```
+
+This skill assumes Playwriter is already set up and connected to the user's
+existing Chrome session.
+
+Read the full output. Do not pipe it through `head`, `tail`, or other
+truncation commands.
+
+## Core idea
+
+Use Playwriter for three things:
+
+1. connect to the already-open x.com (Twitter) article draft
+2. inspect the editor and capture one real network mutation
+3. validate the final rendered result after updates
+
+For anything bigger than a tiny tweak, do **not** rely on manual typing inside
+the editor. Generate the article `content_state` locally and send the same
+GraphQL mutation x.com (Twitter) already uses.
+
+## Editor model
+
+The article body is represented as a `content_state` object with two main
+parts:
+
+- `blocks`: ordered content blocks
+- `entity_map`: supporting entities, especially code blocks
+
+Important block types:
+
+- `unstyled` — normal paragraph
+- `header-two` — section subheading
+- `ordered-list-item` — numbered list item
+- `atomic` — embedded block like a markdown code block
+
+Important entity type:
+
+- `MARKDOWN` — used for code blocks, with the markdown fence stored in
+  `entity_map[*].value.data.markdown`
+
+Longer example `content_state`:
+
+````json
+{
+  "blocks": [
+    {
+      "key": "k0",
+      "text": "event sourcing for application state",
+      "type": "header-two",
+      "data": {},
+      "entity_ranges": [],
+      "inline_style_ranges": []
+    },
+    {
+      "key": "k1",
+      "text": "your clanker loves state",
+      "type": "unstyled",
+      "data": {},
+      "entity_ranges": [],
+      "inline_style_ranges": [
+        { "offset": 19, "length": 5, "style": "Bold" }
+      ]
+    },
+    {
+      "key": "k2",
+      "text": "doubles your final app state",
+      "type": "ordered-list-item",
+      "data": {},
+      "entity_ranges": [],
+      "inline_style_ranges": []
+    },
+    {
+      "key": "k3",
+      "text": "doubles your bugs",
+      "type": "ordered-list-item",
+      "data": {},
+      "entity_ranges": [],
+      "inline_style_ranges": []
+    },
+    {
+      "key": "k4",
+      "text": " ",
+      "type": "atomic",
+      "data": {},
+      "entity_ranges": [
+        { "key": 0, "offset": 0, "length": 1 }
+      ],
+      "inline_style_ranges": []
+    },
+    {
+      "key": "k5",
+      "text": "if you can derive it, don't store it.",
+      "type": "unstyled",
+      "data": {},
+      "entity_ranges": [],
+      "inline_style_ranges": [
+        { "offset": 7, "length": 6, "style": "Bold" }
+      ]
+    }
+  ],
+  "entity_map": [
+    {
+      "key": "0",
+      "value": {
+        "type": "MARKDOWN",
+        "mutability": "Mutable",
+        "data": {
+          "markdown": "```typescript\nfunction shouldShowFooter() {\n  return true\n}\n```"
+        }
+      }
+    }
+  ]
+}
+````
+
+This is the minimum mental model:
+
+- `blocks` is the article in order
+- each paragraph, heading, and list item is a separate block
+- code blocks are `atomic` blocks that point into `entity_map`
+- inline bold lives in `inline_style_ranges`
+
+## Recommended workflow
+
+### 1. Open or locate the draft
+
+Find the existing article editor page in the connected browser. The URL format
+is:
+
+```text
+https://x.com/compose/articles/edit/<article_id>
+```
+
+Always parse and keep the numeric `article_id`. The content mutation needs it.
+
+Example Playwriter check:
+
+```bash
+playwriter session new
+playwriter -s 1 -e '
+state.page = context.pages().find((p) => {
+  return p.url().includes("/compose/articles/edit/")
+})
+if (!state.page) {
+  throw new Error("No article editor page found")
+}
+console.log(state.page.url())
+'
+```
+
+### 2. Explore with small manual edits first
+
+Use the UI to learn how the editor reacts before doing bulk updates. Good
+exploration tasks:
+
+- add one paragraph
+- convert one block to `Sottotitolo`
+- insert one code block
+- bold one word in one paragraph
+
+After each change, inspect the rendered HTML with `getCleanHTML()`.
+
+Example validation command:
+
+```bash
+playwriter -s 1 -e '
+state.page = context.pages().find((p) => {
+  return p.url().includes("/compose/articles/edit/")
+})
+console.log(
+  await getCleanHTML({
+    locator: state.page.locator("[data-testid=\"composer\"]"),
+    showDiffSinceLastCall: false,
+  }),
+)
+'
+```
+
+### 3. Capture real network traffic
+
+Watch GraphQL requests while making one tiny manual change. This gives you the
+exact mutation names and payload shapes used by the current x.com (Twitter)
+editor.
+
+The two important mutations found in this session were:
+
+- `ArticleEntityUpdateTitle`
+- `ArticleEntityUpdateContent`
+
+The content mutation URL looked like:
+
+```text
+https://x.com/i/api/graphql/<queryId>/ArticleEntityUpdateContent
+```
+
+The exact `queryId` can change over time. Do not hardcode it blindly without
+first confirming it from a real request in the current session.
+
+Example request logger:
+
+```bash
+playwriter -s 1 -e '
+state.page = context.pages().find((p) => {
+  return p.url().includes("/compose/articles/edit/")
+})
+state.requests = []
+state.page.removeAllListeners("request")
+state.page.on("request", (req) => {
+  if (req.url().includes("ArticleEntity") || req.url().includes("graphql")) {
+    state.requests.push({
+      url: req.url(),
+      method: req.method(),
+      postData: req.postData(),
+    })
+  }
+})
+console.log(
+  "Ready: now make one tiny manual edit in the page, then rerun this command to inspect state.requests",
+)
+'
+```
+
+### 4. Use direct content updates for bulk work
+
+Once you know the current mutation shape, generate the full `content_state`
+locally and send the content update directly.
+
+This is the reliable path for:
+
+- full markdown import
+- replacing large sections
+- converting paragraphs to ordered lists
+- adding one bold keyword per paragraph
+- fixing code block languages
+
+Concrete pattern:
+
+1. build `content_state` in a local JSON file
+2. read `ct0` from `document.cookie`
+3. send `ArticleEntityUpdateContent` with the same `queryId` and feature flags
+4. reload the page
+
+### 5. Reload and validate
+
+After every direct mutation:
+
+1. reload the article editor page
+2. inspect `getCleanHTML()`
+3. search for expected headings, list items, bold splits, and code labels
+
+Do not trust the visual editor alone.
+
+Example reload + search:
+
+```bash
+playwriter -s 1 -e '
+state.page = context.pages().find((p) => {
+  return p.url().includes("/compose/articles/edit/")
+})
+await state.page.reload({ waitUntil: "domcontentloaded" })
+await waitForPageLoad({ page: state.page, timeout: 8000 })
+console.log(
+  await getCleanHTML({
+    locator: state.page.locator("[data-testid=\"composer\"]"),
+    search: /debugging with event streams|typescript|ordered-list-item/i,
+    showDiffSinceLastCall: false,
+  }),
+)
+'
+```
+
+## Block type cheatsheet
+
+### Paragraphs
+
+Use:
+
+```json
+{
+  "type": "unstyled",
+  "text": "your paragraph text"
+}
+```
+
+### Subheadings
+
+Use:
+
+```json
+{
+  "type": "header-two",
+  "text": "debugging with event streams"
+}
+```
+
+### Numbered lists
+
+Each item is its own block:
+
+```json
+{
+  "type": "ordered-list-item",
+  "text": "doubles your bug surface"
+}
+```
+
+### Code blocks
+
+Code blocks are not plain text blocks. They are:
+
+1. one `atomic` block in `blocks`
+2. one `MARKDOWN` entity in `entity_map`
+
+The atomic block points to the entity with `entity_ranges`.
+
+The entity markdown should include the full fence, for example:
+
+````text
+```typescript
+const x = 1
+```
+````
+
+If you want the visible language label to say `typescript`, the stored fence
+must be ` ```typescript `, not ` ```ts `.
+
+## Inline styles
+
+Bold text is represented with `inlineStyleRanges` inside a block.
+
+Important session learning:
+
+- the style name is `Bold`
+- not `BOLD`
+
+Example:
+
+```json
+{
+  "text": "your clanker loves state",
+  "inlineStyleRanges": [
+    { "offset": 19, "length": 5, "style": "Bold" }
+  ]
+}
+```
+
+Always calculate offsets against the raw block text exactly as stored.
+
+## Known UI pitfalls
+
+The manual editor flow has several traps:
+
+### Heading inheritance
+
+After creating a heading, pressing `Enter` once can keep the next block in the
+same heading style. To reset to a paragraph, press `Enter` again.
+
+### Post-code-block cursor placement
+
+Typing after a code block is unreliable. The editor can:
+
+- append text to the wrong block
+- split text unexpectedly
+- create stray headings
+- leave part of a sentence in one block and the rest in another
+
+For anything more than a tiny manual tweak, use direct content updates instead.
+
+### Visual feedback is incomplete
+
+The editor can look correct while the underlying block structure is wrong.
+Always inspect the HTML or mutation payload.
+
+### Playwriter sessions can reset
+
+If the relay server restarts or the extension reconnects, Playwriter sessions
+can disappear. If that happens, create a new Playwriter session and reattach to
+the already-open article page.
+
+Recovery command:
+
+```bash
+playwriter session new
+playwriter -s 1 -e '
+state.page = context.pages().find((p) => {
+  return p.url().includes("/compose/articles/edit/")
+})
+if (!state.page) {
+  throw new Error("No article editor page found")
+}
+console.log(state.page.url())
+'
+```
+
+## Auth and request details
+
+Direct content updates need proper auth headers. In this session, the direct
+`fetch()` worked only after including:
+
+- the X bearer token
+- `x-csrf-token` from the `ct0` cookie
+- the standard X active-user/auth/client-language headers
+
+If you get `403`, inspect the successful browser request and match its headers.
+
+In this session, the direct fetch succeeded only after matching:
+
+- bearer token
+- `x-csrf-token`
+- `x-twitter-active-user`
+- `x-twitter-auth-type`
+- `x-twitter-client-language`
+
+## Validation checklist
+
+After updating an article, verify all of these:
+
+1. correct title in the title field
+2. headings appear as `header-two`
+3. ordered lists appear as `ordered-list-item`
+4. code blocks render as `markdown-code-block`
+5. code block language labels say what you expect, for example `typescript`
+6. bold keywords are split into separate styled spans in the HTML
+7. no stray empty headings or broken split paragraphs remain
+
+## Useful recipes
+
+### Import a markdown article
+
+1. parse the markdown locally
+2. map paragraphs to `unstyled`
+3. map `##` headings to `header-two`
+4. map numbered list items to `ordered-list-item`
+5. map fenced code blocks to `atomic` + `MARKDOWN` entities
+6. send `ArticleEntityUpdateContent`
+7. reload and validate
+
+The fastest implementation is usually:
+
+1. generate `./tmp/x-article-content-state.json`
+2. read it from a Playwriter command with `fs.readFileSync`
+3. push it with the direct content mutation
+
+### Bold one keyword per paragraph
+
+1. choose one keyword per paragraph
+2. compute exact `offset` and `length`
+3. add `inlineStyleRanges` with style `Bold`
+4. push the updated `content_state`
+5. reload and verify the HTML splits around the bold span
+
+### Fix code language labels
+
+Update the markdown entity fences. Example:
+
+- bad: ` ```ts `
+- good: ` ```typescript `
+
+Then resend the full `content_state` and reload the editor.
+
+## Minimal bulk update example
+
+Use this pattern when you already have the right `queryId` and payload shape:
+
+```bash
+playwriter -s 1 -e '
+const fs = require("node:fs")
+state.page = context.pages().find((p) => {
+  return p.url().includes("/compose/articles/edit/")
+})
+const articleId = state.page.url().match(/edit\/(\d+)/)?.[1]
+const contentState = JSON.parse(
+  fs.readFileSync("./tmp/x-article-content-state.json", "utf8"),
+)
+const csrfToken = await state.page.evaluate(() => {
+  return document.cookie
+    .split("; ")
+    .find((x) => x.startsWith("ct0="))
+    ?.slice(4) || ""
+})
+const payload = {
+  variables: {
+    content_state: contentState,
+    article_entity: articleId,
+  },
+  features: {
+    profile_label_improvements_pcf_label_in_post_enabled: true,
+    responsive_web_profile_redirect_enabled: false,
+    rweb_tipjar_consumption_enabled: false,
+    verified_phone_label_enabled: false,
+    responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+    responsive_web_graphql_timeline_navigation_enabled: true,
+  },
+  queryId: "<capture-from-real-request>",
+}
+const response = await state.page.evaluate(async ({ payload, csrfToken }) => {
+  const res = await fetch(
+    `https://x.com/i/api/graphql/${payload.queryId}/ArticleEntityUpdateContent`,
+    {
+      method: "POST",
+      credentials: "include",
+      headers: {
+        authorization: "<capture-from-real-request>",
+        "content-type": "application/json",
+        "x-csrf-token": csrfToken,
+        "x-twitter-active-user": "yes",
+        "x-twitter-auth-type": "OAuth2Session",
+        "x-twitter-client-language": "it",
+      },
+      body: JSON.stringify(payload),
+    },
+  )
+  return { status: res.status, text: await res.text() }
+}, { payload, csrfToken })
+console.log(response.status)
+console.log(response.text.slice(0, 1000))
+'
+```
+
+Replace the bearer token and `queryId` with values captured from a successful
+browser request in the current session.
+
+## Default strategy
+
+Use this default unless the task is tiny:
+
+1. inspect the current draft in the browser
+2. capture one real content mutation from X
+3. generate the final `content_state` locally
+4. update the draft with the same mutation shape
+5. validate the result in the live editor HTML
+
+That is the fastest path and the most likely to work in one shot.

package/skills/zele/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: zele
+description: >
+  zele is a multi-account email and calendar CLI for Gmail, IMAP/SMTP
+  (Fastmail, Outlook, any provider), and Google Calendar. It reads,
+  searches, sends, replies, forwards, archives, stars, and trashes emails,
+  manages drafts, labels, attachments, and Gmail filters, and creates,
+  updates, and deletes calendar events with RSVP and free/busy support.
+  Output is YAML so commands can be piped through yq and xargs. ALWAYS
+  load this skill when the user asks to check email, read/send messages,
+  reply or forward, archive or trash threads, manage drafts or labels,
+  download attachments, schedule meetings, check their calendar, RSVP
+  to events, or when they run any `zele` command. Load it before writing
+  any code or shell commands that touch zele so you know the correct
+  subcommand structure, the Google vs IMAP feature matrix, the headless
+  login flow, and the agent-specific rules.
+---
+
+# zele
+
+Every time you use zele, you MUST fetch the latest README:
+
+```bash
+curl -s https://raw.githubusercontent.com/remorses/zele/main/README.md # NEVER pipe to head/tail, read the full output
+```
+
+Then run the CLI help once — it already includes every subcommand, option, and flag:
+
+```bash
+zele --help # NEVER pipe to head/tail, read the full output
+```
+
+The README and `zele --help` output are the source of truth for commands, options, flags, the Google vs IMAP feature matrix, search operators, and the headless login flow.
+
+## Rules
+
+1. **Never use the TUI.** Running `zele` with no subcommand launches a human-facing TUI. Agents must use the CLI subcommands (`zele mail list`, `zele cal events`, etc.) which output structured YAML.
+2. **Always run `zele whoami` first** when the user asks to operate on a specific account. Pick the exact email from the output and pass it with `--account`. Never guess account emails.
+3. **Never truncate `--help` or README output** with `head`, `tail`, `sed`, `awk`, or `less`. Critical rules are spread throughout. Read them in full.
+4. **Parse YAML output with `yq`**, not regex. Pipe IDs through `xargs` for bulk actions. Always use `--limit 100` (or higher) so you don't miss threads:
+   ```bash
+   # read all unread emails
+   zele mail list --filter "is:unread" --limit 100 | yq '.[].id' | xargs zele mail read
+
+   # bulk archive
+   zele mail list --filter "is:unread" --limit 100 | yq '.[].id' | xargs zele mail archive
+   ```
+5. **Google-only features** (labels, Gmail filters, `zele cal *`, full profile) fail on IMAP accounts with a clear error. Check `zele whoami` output for account type before using them.
+6. **Headless Google login** requires a tmux wrapper because `zele login` is interactive. See the README "Remote / headless login" section for the exact pattern.