@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/slide-decks/references/html-decks.md

@@ -0,0 +1,86 @@
+# HTML decks
+
+## reveal.js
+
+Install from npm (`npm i reveal.js`) or load from a CDN with a pinned version. Check the current major on revealjs.com before pinning.
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Checkout reliability</title>
+  <link rel="stylesheet" href="node_modules/reveal.js/dist/reveal.css">
+  <link rel="stylesheet" href="node_modules/reveal.js/dist/theme/white.css">
+  <link rel="stylesheet" href="deck.css">
+</head>
+<body>
+  <div class="reveal"><div class="slides">
+    <section>
+      <h1>Checkout failures cost us 4% of orders</h1>
+      <p>Q3 review, Payments team</p>
+      <aside class="notes">Open with the cost, then say we found one main cause.</aside>
+    </section>
+    <section data-auto-animate>
+      <h2>70% come from one provider timeout</h2>
+      <ul>
+        <li class="fragment">Timeouts after 10s</li>
+        <li class="fragment">No retry on our side</li>
+      </ul>
+    </section>
+  </div></div>
+  <script src="node_modules/reveal.js/dist/reveal.js"></script>
+  <script src="node_modules/reveal.js/dist/plugin/notes.js"></script>
+  <script src="node_modules/reveal.js/dist/plugin/highlight.js"></script>
+  <script>
+    Reveal.initialize({ hash: true, plugins: [RevealNotes, RevealHighlight] });
+  </script>
+</body>
+</html>
+```
+
+These are the paths the current revealjs.com plugin docs give (`dist/plugin/*.js`, with `.mjs` ES modules alongside). Older 4.x packages used `plugin/notes/notes.js` and `plugin/highlight/highlight.js`; check the installed package's folders.
+
+Key features:
+
+- Speaker notes: `<aside class="notes">` inside a `<section>`, or `data-notes="..."`. Press `S` for the speaker view; it needs the deck served over HTTP (`npx serve .` or `python3 -m http.server`), not opened from `file://`.
+- Vertical slides: nest `<section>` inside `<section>`; use for optional depth, not the main path.
+- Fragments: `class="fragment"` reveals items step by step. Use sparingly.
+- Auto-animate: `data-auto-animate` on consecutive slides animates matching elements.
+- Code: `<pre><code data-line-numbers="3-5|8" class="language-js">` with the highlight plugin steps through highlighted lines.
+- Size: default canvas 960x700, scaled to fit. For 16:9 set `width: 1280, height: 720` (or 1920x1080) in `Reveal.initialize`.
+- Markdown slides: the markdown plugin with `<section data-markdown>`, `---` between slides, `Note:` for notes.
+- Pandoc can also write reveal.js: `pandoc -s -t revealjs slides.md -o slides.html`.
+
+## Plain HTML/CSS deck
+
+For a handful of slides with no dependency:
+
+```html
+<main class="deck">
+  <section class="slide"><h1>...</h1></section>
+  <section class="slide"><h2>...</h2></section>
+</main>
+```
+
+```css
+.slide { width: 100vw; height: 100vh; display: grid; place-content: center;
+         padding: 6vh 7vw; box-sizing: border-box; scroll-snap-align: start; }
+.deck { height: 100vh; overflow-y: auto; scroll-snap-type: y mandatory; }
+@page { size: 1920px 1080px; margin: 0; }
+@media print {
+  .deck { height: auto; overflow: visible; }
+  .slide { width: 1920px; height: 1080px; break-after: page; }
+}
+```
+
+Add arrow-key navigation with a few lines of script (`scrollIntoView` on the next `.slide`) if needed. Notes can live in `<aside class="notes" hidden>` and be printed separately.
+
+## PDF export
+
+- reveal.js in the browser: open `http://localhost:8000/?print-pdf`, print, destination Save as PDF, landscape, margins None, background graphics on. Chrome or Chromium only.
+  - `showNotes: true` (overlay) or `showNotes: 'separate-page'` prints notes.
+  - `pdfSeparateFragments: false` prints each slide once with all fragments shown.
+  - `pdfMaxPagesPerSlide: 1` stops tall slides spilling onto extra pages.
+- Headless: `npx decktape reveal http://localhost:8000 slides.pdf` (decktape also supports other HTML frameworks and a generic mode; add `--size 1920x1080` to set the page size).
+- Plain HTML: headless Chrome, e.g. `chrome --headless --print-to-pdf=slides.pdf http://localhost:8000/` (binary name varies: `google-chrome`, `chromium`, or the full app path on macOS), using the print CSS above.

package/skills/slide-decks/references/layouts.md

@@ -0,0 +1,45 @@
+# Slide types and layouts
+
+16:9 canvas. Work on a 12-column grid with generous outer margins (about 5-7% of width).
+
+| Slide type | Layout | Content rule |
+|---|---|---|
+| Title | Centered or left-aligned title, subtitle, presenter and date | Title states the talk's promise, not just the topic |
+| Section divider | Large section title, optional progress marker | Use only in long decks |
+| Big number | One number very large, one line of context below | "4.1% of orders failed" + source |
+| Statement | One sentence, large, left-aligned | The takeaway of a section |
+| Chart | Action title, chart filling most of the slide, source line | One highlighted series |
+| Comparison | Two columns, same structure each side | Before/after, option A/B |
+| Image + text | Image 50-60% width, 1-3 short lines | Screenshot with callouts beats raw screenshot |
+| Process | 3-5 steps left to right or top to bottom | Verbs, numbered |
+| Code | Monospace, 12-20 lines max, highlight the lines that matter | Reveal.js `data-line-numbers="3-5"` |
+| Quote | Quote, name, role | Only real, attributed quotes |
+| Ask / next steps | The decision or action, owner, date | Last content slide |
+| Appendix | Dense tables, methodology | Not presented; for readers |
+
+## Type sizes (presented, 1920x1080 or 13.33x7.5 in)
+
+| Element | Size |
+|---|---|
+| Action title | 32-44pt |
+| Body | 24-28pt |
+| Labels, sources | 14-18pt (sources only; never body text this small) |
+| Big number | 96-160pt |
+
+For a read-alone deck, body can drop to 16-20pt with more words, but keep one idea per slide.
+
+## Charts
+
+- Bar for comparing categories, line for change over time, scatter for relationships; avoid pie charts with more than 3 slices.
+- Start bar axes at zero.
+- Grey for everything, accent colour for the point the title makes.
+- Write the takeaway in the title, and the source and date in a small line underneath.
+
+## Speaker notes template
+
+```
+Point: <the one thing this slide says>
+Say: <2-5 sentences, conversational>
+Evidence: <where the number comes from>
+Transition: <the sentence that leads to the next slide>
+```

package/skills/slide-decks/references/pptx.md

@@ -0,0 +1,87 @@
+# PowerPoint decks
+
+## pandoc: Markdown to .pptx
+
+```markdown
+---
+title: Checkout reliability
+author: Payments team
+---
+
+# Checkout failures cost us 4% of orders
+
+- 1,240 failed orders in Q3
+- Mostly at the payment step
+
+::: notes
+Open with the cost, then say we found one main cause.
+:::
+
+# 70% come from one provider timeout
+
+![Failures by cause](failures.png)
+```
+
+```bash
+pandoc slides.md -o slides.pptx --slide-level=1 --reference-doc=template.pptx
+```
+
+- `--slide-level` picks which heading level starts a slide (here `#`).
+- `--reference-doc` takes a template whose layouts are named Title Slide, Title and Content, Section Header, Two Content, Comparison, Content with Caption and Blank; missing layouts fall back to pandoc's default with a warning.
+- Get pandoc's default template to edit: `pandoc -o custom-reference.pptx --print-default-data-file reference.pptx`.
+- Two columns: `:::::: {.columns}` with two `::: {.column}` blocks.
+- Speaker notes: `::: notes` blocks.
+
+## python-pptx: generate or fill a template
+
+`pip install python-pptx`.
+
+```python
+from pptx import Presentation
+from pptx.util import Inches, Pt
+
+prs = Presentation("template.pptx")          # or Presentation() for a blank 4:3 default
+# Blank default is 4:3; for 16:9:
+# prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)
+
+for i, layout in enumerate(prs.slide_layouts):          # find layout names first
+    print(i, layout.name, [p.placeholder_format.idx for p in layout.placeholders])
+
+slide = prs.slides.add_slide(prs.slide_layouts[1])      # Title and Content in most templates
+slide.shapes.title.text = "70% of failures come from one provider timeout"
+body = slide.placeholders[1].text_frame
+body.text = "Timeouts after 10 seconds"
+p = body.add_paragraph(); p.text = "No retry on our side"; p.level = 0
+slide.notes_slide.notes_text_frame.text = "Explain the timeout, then move to the fix."
+
+pic = slide.shapes.add_picture("chart.png", Inches(1), Inches(2), width=Inches(8))
+# alt text: python-pptx has no direct API; set the descr attribute on the cNvPr element
+pic._element.nvPicPr.cNvPr.set("descr", "Bar chart: provider timeouts are 70% of failures")
+
+prs.save("deck.pptx")
+```
+
+Rules:
+
+- Fill **placeholders** from the template's layouts; do not add free text boxes over them, or the template's styling and accessibility reading order break.
+- Print the layouts and placeholder indexes first (loop above); indexes differ between templates.
+- Native charts: `slide.shapes.add_chart(XL_CHART_TYPE.BAR_CLUSTERED, x, y, cx, cy, chart_data)` with `CategoryChartData` keeps them editable; use an image only if the user does not need to edit.
+- Fonts render with whatever is installed on the viewer's machine; stick to the template's fonts.
+- Deleting slides and reordering need XML manipulation in python-pptx; for heavy edits of an existing deck, consider asking the user to do structural changes in PowerPoint and automate only the content.
+
+## Reading an existing .pptx
+
+```python
+for n, slide in enumerate(prs.slides, 1):
+    texts = [s.text_frame.text for s in slide.shapes if s.has_text_frame]
+    notes = slide.notes_slide.notes_text_frame.text if slide.has_notes_slide else ""
+    print(n, slide.slide_layout.name, texts, notes)
+```
+
+## PDF from .pptx
+
+```bash
+soffice --headless --convert-to pdf --outdir out deck.pptx
+```
+
+LibreOffice substitutes missing fonts; check the PDF. For pixel-exact output, export from PowerPoint or Keynote itself.

package/skills/smart-contract-security/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: smart-contract-security
+description: Security audit procedure for Solidity and EVM smart contracts that maps the system's funds, roles and trust assumptions, then hunts reentrancy (including cross-function and read-only), broken access control, price oracle and flash-loan manipulation, rounding and precision loss in share maths, front-running and MEV exposure, signature replay across chains and nonces, and proxy upgrade risks, backed by Slither static analysis plus Foundry, Echidna or Medusa fuzzing and invariant tests, ending in a severity-rated report with a clear professional-audit boundary. Use when auditing a protocol or token contract before deployment, investigating a suspected exploit path, writing invariant tests to break a contract, or deciding whether code is ready for an external audit.
+license: MIT
+compatibility: Any Agent Skills host. Needs Foundry (forge) or Hardhat to build and test; Slither (Python 3.10+) for static analysis; Echidna or Medusa optional for property fuzzing.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: security
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "forge, slither"
+  kete-loom/owner: "Kete-org"
+---
+
+# Smart contract security
+
+Find the ways a contract loses or locks funds, prove each with a failing test, and say plainly what the review did not cover. Exploits are permanent and public, so a finding without a reproduction is a lead, not a conclusion.
+
+## What this skill is not
+
+- **Not a professional audit.** It is a structured internal review. Any contract that will hold meaningful user funds, mint a token with market value, or bridge assets needs at least one independent audit by a qualified firm, and ideally a bug bounty, before mainnet. Say so in every report.
+- Not financial, legal or token-regulation advice.
+- Not a guarantee: no finding list proves the absence of bugs.
+
+## 1. Scope and threat model
+
+1. Pin the exact commit, compiler version and the list of in-scope files. Build it (`forge build` or `npx hardhat compile`); if it doesn't compile, stop and ask.
+2. Write down, before reading code in depth:
+   - **Assets**: what the contracts hold (ETH, tokens, NFTs, accounting balances) and where the totals live.
+   - **Actors and roles**: users, admins, keepers, oracles, bridges, other protocols; what each can do.
+   - **Trust assumptions**: which external contracts and tokens are trusted, which price feeds, and what a malicious or upgraded dependency could do.
+   - **Invariants**: statements that must always hold (solvency, `totalShares` matches the sum of balances, only role X changes parameter Y).
+3. Map every external and public function that moves value or changes privileged state. Run `slither . --print human-summary` and `--print function-summary` to get the inventory.
+
+## 2. Automated pass
+
+1. `slither .` from the project root (filter out `lib/` or `node_modules` per the Slither wiki). Triage every high and medium detector result: true positive, false positive with reason, or needs a test.
+2. For proxies, `slither-check-upgradeability` against the old and new implementation, plus the OpenZeppelin Upgrades plugin's validation.
+3. Existing tests: `forge test -vvv` and `forge coverage`. Note functions with no test of their revert paths.
+
+Tool output is a starting point. Never report a detector result as a finding without reading the code path.
+
+## 3. Manual review, in this order
+
+Work through `references/vulnerability-checklist.md`. The headline classes:
+
+1. **Reentrancy**: external calls (ETH sends, token transfers, hooks in ERC-721/1155/777 receivers, arbitrary `call`) before state is updated; cross-function and cross-contract reentrancy that `nonReentrant` on one function doesn't cover; read-only reentrancy where another protocol reads a stale view mid-call.
+2. **Access control**: unguarded privileged functions, unprotected or re-callable initializers, uninitialized implementation contracts, role admin misconfiguration, `tx.origin` auth, missing two-step ownership transfer.
+3. **Oracle and price manipulation**: spot prices from an AMM pool's reserves or `balanceOf`, which a flash loan can move within one transaction; Chainlink answers used without checking staleness (`updatedAt`), round completeness and sequencer uptime on L2s; donation attacks on share-price vaults (ERC-4626 inflation).
+4. **Integer and rounding**: rounding in the user's favour on deposit/withdraw or mint/redeem, division before multiplication, precision loss with low-decimal tokens, `unchecked` blocks, unsafe downcasts (`uint128(x)` silently truncates; use `SafeCast`).
+5. **Front-running and MEV**: missing slippage limits (`minAmountOut`) and deadlines on swaps, commit-reveal missing where order matters, approval race conditions, sandwichable liquidations or auctions.
+6. **Signature replay**: signatures without a nonce, without `block.chainid` and contract address in the EIP-712 domain, reusable after cancel, malleable (use OZ `ECDSA`, not raw `ecrecover`), or `ecrecover` returning `address(0)` accepted as a valid signer.
+7. **Upgrade risks**: storage layout collisions between versions, missing `_authorizeUpgrade` guard, selector clashes in proxies, upgrade keys held by a single EOA, no timelock.
+8. **Token integration**: fee-on-transfer and rebasing tokens, tokens that return `false` instead of reverting (use `SafeERC20`), tokens with blocklists or pausable transfers, 6 vs 18 decimals.
+9. **Denial of service and griefing**: unbounded loops, push payments to contracts that revert, dust positions that block liquidation.
+
+## 4. Prove it
+
+For every candidate finding, write a Foundry test that demonstrates it (an exploit test that passes when the bug exists), or a fuzz/invariant test that breaks:
+
+- Fuzz: functions taking `uint256 amount` with `bound()` to realistic ranges.
+- Invariant: a handler contract that calls the system's functions in random order, with `invariant_` functions asserting the invariants from step 1 (`[invariant] runs` and `depth` in `foundry.toml`).
+- Fork tests (`forge test --fork-url $RPC_URL`) for oracle and integration issues against real pool state.
+- Echidna or Medusa for longer property campaigns when the invariants are numerous.
+
+Findings you couldn't reproduce are reported as "unconfirmed", with the reasoning.
+
+## Severity
+
+| Severity | Meaning |
+|---|---|
+| Critical | Direct theft or permanent freezing of user funds, or takeover of admin/upgrade, by an unprivileged attacker |
+| High | Loss of funds under realistic conditions, or protocol insolvency |
+| Medium | Loss of yield, temporary freezing, or a privileged role able to harm users beyond the documented trust model |
+| Low | Hardening, best-practice deviations with no direct loss path |
+| Info | Gas, style, documentation |
+
+## Stop and ask the user
+
+- If you find a critical issue in a contract that is already deployed with funds: stop the review, tell the user immediately, and recommend they contact a security firm or an emergency response group and follow responsible disclosure. Do not publish details, open public issues, or run the exploit on mainnet.
+- Before running anything against a live network other than read-only fork tests.
+- If scope, the trust model or intended admin powers are unclear.
+
+## Never
+
+- Never broadcast transactions, use real private keys, or test exploits on mainnet or public testnets against contracts you don't own.
+- Never mark a contract "secure", "safe" or "audited". Say "no issues found in the reviewed scope".
+- Never drop the professional-audit recommendation for contracts that will hold funds.
+
+## Report format
+
+```
+## Smart contract review: <repo>@<commit>
+Scope: <files>, solc <version>. Out of scope: <...>
+Threat model: assets, roles, trust assumptions, invariants (short)
+
+### Findings
+1. [Critical] Vault.sol:142 — <title>
+   Class: reentrancy | access control | oracle | rounding | MEV | signature | upgrade | token | DoS
+   Impact: <who loses what, under what conditions>
+   Proof: test/exploits/<Name>.t.sol (passes = bug present) | unconfirmed: <why>
+   Fix: <smallest change that removes the root cause>
+
+### Tooling
+Slither: <n> results triaged (<n> true positives). Fuzz/invariant: <runs, depth, results>. Coverage: <%>.
+
+### Not covered
+<economic design, off-chain components, dependencies, anything skipped>
+
+This is an internal review, not a professional audit. Contracts that will hold user funds need an independent audit before mainnet.
+```

package/skills/smart-contract-security/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Audit our lending protocol contracts for oracle manipulation and reentrancy before launch",
+    "Can a flash loan drain our ERC-4626 vault through a share price inflation attack?",
+    "Write Foundry invariant tests that try to break the solvency of our staking contract",
+    "Our permit-based meta-transaction signatures don't include a nonce, is that exploitable and how bad is it?",
+    "Is our DEX router code ready for an external audit? Run Slither and do a security pass first"
+  ],
+  "should_not_trigger": [
+    "Write an ERC-20 token contract with a capped supply and an owner-only mint using Foundry",
+    "Show the token balance with the right decimals in our wagmi frontend and send an approve transaction",
+    "Review my last commit for security vulnerabilities in the login flow",
+    "Check our npm dependencies for known CVEs and abandoned packages",
+    "Explain how proof of stake consensus works on Ethereum"
+  ]
+}

package/skills/smart-contract-security/references/vulnerability-checklist.md

@@ -0,0 +1,79 @@
+# Smart contract vulnerability checklist
+
+Read this during the manual review step. Each item is a question; answer it for every in-scope contract and note the line you checked.
+
+## Reentrancy
+
+- Does any function make an external call (`call`, `transfer`/`send`, token `transfer`/`transferFrom`, `safeTransferFrom` on ERC-721/1155 which calls `onERC721Received`/`onERC1155Received`, ERC-777 hooks, a callback into a user-supplied address) before it finishes writing state?
+- Are all functions sharing the same state protected together (cross-function reentrancy), not just the one that makes the call?
+- Can another contract read a view function (price, share value, balance) while this contract is mid-call with inconsistent state (read-only reentrancy)?
+- Is `nonReentrant` present where needed and absent from functions that must call each other internally?
+
+## Access control
+
+- Is every function that mints, burns, pauses, sets parameters, moves treasury funds, or upgrades guarded by a modifier or explicit check?
+- Can `initialize` be called by anyone, called twice, or front-run after deployment? Is `_disableInitializers()` in the implementation constructor?
+- Does `_authorizeUpgrade` have access control (UUPS)?
+- Are `AccessControl` role admins set correctly (who can grant `DEFAULT_ADMIN_ROLE`)?
+- Is ownership transfer two-step (`Ownable2Step`)? Is renouncing ownership possible by accident?
+- Any use of `tx.origin` for authorization?
+- Are admin powers documented and bounded (fee caps, timelocks)?
+
+## Oracles and price manipulation
+
+- Is any price derived from AMM reserves, `balanceOf(address(this))`, or a single-block value that a flash loan can move?
+- For Chainlink `latestRoundData`: are `answer > 0`, `updatedAt` freshness against the feed's heartbeat, and (on L2s) the sequencer uptime feed checked? Are feed decimals read, not assumed?
+- Are TWAP windows long enough for the liquidity involved?
+- ERC-4626 or share vaults: can the first depositor inflate the share price by donating assets (virtual shares/offset, minimum deposit, or dead shares)?
+
+## Integer maths and rounding
+
+- Does every conversion round against the user and in favour of the protocol (deposit rounds shares down, withdraw rounds shares up)?
+- Any division before multiplication? Use `Math.mulDiv` for `a * b / c` with large values.
+- Any `unchecked` block without a proven bound?
+- Any downcast (`uint128(x)`, `int256(x)`) without `SafeCast`?
+- Do calculations handle tokens with 6, 8 and 18 decimals, and zero amounts?
+
+## Front-running and MEV
+
+- Do swaps, deposits into AMM positions, and liquidations take a `minAmountOut`/`maxAmountIn` and a `deadline` from the caller?
+- Can an observer of the mempool profit by inserting a transaction before or after (sandwich, back-running oracle updates)?
+- Are approvals set with `forceApprove` or increase/decrease patterns rather than overwriting non-zero allowances?
+- Would commit-reveal or a batch auction be needed for fairness (games, NFT mints, auctions)?
+
+## Signatures
+
+- Does the signed message include a nonce that's consumed, an expiry, `block.chainid`, and the verifying contract (EIP-712 domain separator, rebuilt if the chain ID changes)?
+- Is `ECDSA.recover` (or `SignatureChecker` for smart-contract wallets via ERC-1271) used instead of raw `ecrecover`, and is a `address(0)` signer rejected?
+- Can the same signature be used on another function, another contract, or after cancellation?
+- `permit` (EIP-2612) calls: is a front-run `permit` (which makes the second call revert) handled so it can't grief the user?
+
+## Upgrades and proxies
+
+- Compare storage layouts between versions: no reordered, removed or retyped variables; namespaced storage (ERC-7201) or gaps used consistently.
+- Do inherited contracts change order between versions?
+- Any function selector in the implementation clashing with the proxy's admin functions (transparent proxy)?
+- Who holds the upgrade key? Is there a timelock so users can exit before an upgrade?
+- Does any new `reinitializer(n)` use the right version number?
+
+## Token integration
+
+- Fee-on-transfer: is the received amount measured by balance difference?
+- Rebasing tokens: do stored balances drift from actual balances?
+- Tokens that return `false` or no value: is `SafeERC20` used?
+- Tokens with blocklists, pause, or upgradeable logic (USDC, USDT): can a blocked address freeze the whole system?
+- ERC-777 or tokens with hooks: reentrancy on transfer.
+
+## Denial of service and griefing
+
+- Loops over arrays users can grow (holders, orders, positions)?
+- Push payments where one reverting recipient blocks everyone?
+- Can dust positions, tiny orders or zero-amount calls block liquidation, settlement or withdrawal queues?
+- Does anything depend on `address(this).balance` equalling an internal counter (forced ETH via `selfdestruct` from another contract or coinbase still works)?
+
+## Miscellaneous
+
+- `delegatecall` to user-influenced addresses or to libraries with storage.
+- Randomness from `block.timestamp`, `blockhash` or `block.prevrandao` for anything valuable (use Chainlink VRF or commit-reveal).
+- Hard-coded addresses that differ per chain.
+- Events missing for parameter changes, so monitoring can't see an admin action.

package/skills/social-media-publishing/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: social-media-publishing
+description: Posts text, images and video to X, LinkedIn, Facebook Pages and Instagram through their official APIs, covering OAuth app setup and token refresh, the scopes each platform needs, media upload flows, rate and publishing limits, queued scheduling with retries, and per-platform length and formatting rules. Use when building or fixing code that publishes or schedules social posts programmatically, a post or media upload call fails with a 401, 403 or rate-limit error, or one message must be formatted correctly for several networks.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to api.x.com, api.linkedin.com and graph.facebook.com, and developer apps the user owns on each platform. Examples are plain HTTP; the rules apply to any SDK.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Social media publishing
+
+Publish to social networks through official APIs only, with tokens stored safely, media uploaded the way each platform expects, every post idempotent, and failures retried without double-posting.
+
+## Ground rules
+
+1. **Official APIs only.** No browser automation, scraped endpoints or shared passwords; they break platform terms and get accounts banned.
+2. **The user owns the developer apps.** Each platform needs an app the user registers and, for some scopes, gets approved (LinkedIn's Community Management API for company pages, Meta App Review for Page and Instagram publishing). **Stop and ask the user** for app IDs and which accounts to post as; never invent them.
+3. **Tokens are secrets.** Store access and refresh tokens encrypted server-side, per connected account, with their expiry and granted scopes. Never log them or send them to the browser.
+4. **Request the least scope** that the feature needs (table below).
+5. **Media first, then the post.** Every platform uploads or registers media in a separate step and returns an ID or container that the post references. Wait until processing finishes before posting.
+6. **Idempotent posting.** Write a `scheduled_posts` row (account, platform, body, media, `publish_at`, status) before calling the API; mark `publishing` with a conditional update, store the returned post ID, and never retry a call that may have succeeded without first checking whether the post exists.
+7. **Respect rate limits.** Read the platform's rate-limit headers or usage endpoint, back off on `429`, and spread scheduled posts instead of firing them all at the top of the hour.
+8. **Read the current docs.** These APIs, their access tiers and pricing change often. Check the version and limits in the official docs before stating them; details in `references/platform-apis.md`.
+
+## Platform map
+
+| Platform | Auth | Post endpoint | Media | Scopes / permissions |
+|---|---|---|---|---|
+| X | OAuth 2.0 with PKCE, user context | `POST https://api.x.com/2/tweets` | `POST /2/media/upload/initialize`, `/{id}/append`, `/{id}/finalize`, then poll status | `tweet.read`, `tweet.write`, `users.read`, `media.write`, `offline.access` for refresh |
+| LinkedIn | OAuth 2.0 three-legged | `POST https://api.linkedin.com/rest/posts` with `Linkedin-Version: YYYYMM` and `X-Restli-Protocol-Version: 2.0.0` | `POST /rest/images?action=initializeUpload`, PUT bytes to `uploadUrl`, use the `urn:li:image:...` | `w_member_social` (member), `w_organization_social` (company page; member needs the ADMINISTRATOR, CONTENT_ADMIN or DIRECT_SPONSORED_CONTENT_POSTER page role) |
+| Facebook Page | Facebook Login, Page access token | `POST /{page-id}/feed` (text, link) or `/{page-id}/photos`, `/{page-id}/videos` | in the same call by URL or upload | `pages_manage_posts`, `pages_manage_engagement`, `pages_read_engagement`, `pages_read_user_engagement`; add `publish_video` for video |
+| Instagram (professional account) | Instagram Login or Facebook Login | `POST /{ig-user-id}/media` creates a container, then `POST /{ig-user-id}/media_publish` | media fetched by Meta from a public `image_url` / `video_url` | `instagram_business_basic` + `instagram_business_content_publish` (Instagram Login), or `instagram_basic` + `instagram_content_publish` + `pages_read_engagement` (Facebook Login) |
+
+## Build steps
+
+1. **Connect accounts.** Implement the OAuth authorization-code flow per platform with a `state` value checked on return (and PKCE for X). Save tokens, expiry, scopes and the account's ID or URN (`urn:li:person:...` from LinkedIn's OpenID `userinfo` `sub`, `urn:li:organization:...` for pages, the Page ID, the IG user ID).
+2. **Refresh before expiry.** A job refreshes tokens ahead of `expires_at`. When refresh fails (revoked, password changed, scope removed), mark the account `needs_reconnect` and tell the user; do not keep retrying.
+3. **Format per platform** using the rules below. Validate length and media count before queueing, not at publish time.
+4. **Upload media.** X: chunked upload (keep chunks at or under 5 MB), then poll status until `processing_info.state` is `succeeded`. LinkedIn: `initializeUpload`, PUT the file, wait until the image or video is `AVAILABLE`. Instagram: host the file at a public HTTPS URL, create the container, poll `status_code` until `FINISHED` (about once a minute, at most 5 minutes) before `media_publish`.
+5. **Publish** from a worker that picks due rows, claims them with `UPDATE ... SET status='publishing' WHERE id=? AND status='scheduled'`, calls the API, then stores the platform post ID and URL.
+6. **Handle errors** by class: `401` refresh once then mark reconnect; `403` missing scope, role or tier (do not retry); `429` back off using the reset header; `5xx` or timeout check whether the post exists, then retry with backoff. Record the platform's error body.
+7. **Scheduling.** Store `publish_at` in UTC with the user's time zone for display. Native scheduling exists on some platforms (Facebook Pages accept `published=false` with `scheduled_publish_time`, 10 minutes to 30 days ahead), but a single queue of your own keeps behaviour the same everywhere.
+
+## Formatting differences
+
+| | X | LinkedIn | Facebook Page | Instagram |
+|---|---|---|---|---|
+| Text length | 280 weighted characters (emoji and CJK count as 2); any URL counts as 23 | 3,000 characters | long posts allowed; first lines show before "See more" | caption up to 2,200 characters |
+| Links | inline, shortened by t.co | inline; link preview via article content | link preview from the `link` field | not clickable in captions |
+| Hashtags | 1 or 2 (style choice) | a few at the end (style choice) | sparing | at most 30 per caption |
+| Mentions | `@handle` in text | `@` + `[Name]` + `(urn)` mention syntax in the commentary; name must match | Page tags need IDs | `@handle` in caption, at most 20 |
+| Media | up to 4 media IDs per post | images, video, documents, multi-image | photos, video | required: image, video, reel, or carousel of up to 10 |
+
+Confirm current limits in each platform's docs before enforcing them in code.
+
+## Stop and ask the user
+
+- Which accounts and pages to post as, and who approved posting on their behalf.
+- Before applying for elevated access or a paid API tier.
+- Before posting anything live during development: use a test account, private visibility, or draft state where the platform offers one.
+- Before deleting or editing published posts in bulk.
+
+## Never
+
+- Post the same text to every network unchanged when it breaks a platform's length or mention rules.
+- Automate likes, follows, replies or DMs at scale; platform rules forbid most of it.
+- Store tokens in the client, or share one token across customers.
+- Retry a publish blindly after a timeout.
+
+## Report format
+
+When reviewing or finishing an integration, report:
+
+```
+Platforms: ...                 Accounts: member / page / IG professional
+Auth: flow, scopes granted, refresh handled yes|no
+Media: upload path and processing wait per platform
+Queue: idempotent claim yes|no, retry policy, timezone handling
+Gaps: ... (each with the fix)
+Needs user action: app review, tier, page roles
+```

package/skills/social-media-publishing/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Build a scheduler that posts to our LinkedIn company page and X account from our CMS",
+    "LinkedIn rest/posts returns 403 ACCESS_DENIED when I post as our organization",
+    "How do I upload a video to X with the v2 media upload endpoints and attach it to a post?",
+    "Instagram media_publish fails because the container status is still IN_PROGRESS",
+    "Our social posting worker sometimes publishes the same Facebook Page post twice after a timeout",
+    "Which OAuth scopes do I need to let users connect their X and LinkedIn accounts for posting?"
+  ],
+  "should_not_trigger": [
+    "Turn this 40-minute conference talk into a LinkedIn post, an X thread and a newsletter",
+    "Write a voice and tone guide for how our brand sounds on social",
+    "Our marketing emails fail DMARC, fix the DNS records",
+    "Plan a six-week launch campaign with a budget split across paid social and email",
+    "Write a three-touch outbound email sequence to VPs of engineering"
+  ]
+}