acuvo-code 0.2.0

package/skills/acuvo-design-system.md

@@ -0,0 +1,123 @@
+---
+name: acuvo-design-system
+description: How to make a generated page look designed rather than templated, under Acuvo's CSP
+when: Building or restyling any user-facing page, component or app
+---
+
+# Making it look designed
+
+## ⚠️ THE CONSTRAINT THAT DECIDES EVERYTHING: the CSP
+
+Generated apps run under a strict Content-Security-Policy. **No external
+stylesheet, script, font host or CDN will load.** The only external origin that
+works is Google Fonts.
+
+So:
+
+- **Never** `<link>` a CDN stylesheet, never `<script src="https://cdn...">`.
+  It fails silently and the page renders unstyled — which reads as "the AI is
+  bad at design" when it was a network refusal.
+- **Vendor it instead.** Write the CSS into the project. If a component library
+  is genuinely needed, inline the handful of rules actually used.
+- Images and media must be same-origin or `data:` URIs.
+
+⭐ This is the single biggest measured cause of ugly output. It is not a taste
+problem.
+
+## The look
+
+**Type.** One display face and one text face, maximum. Google Fonts is allowed —
+use it. A serif display over a clean sans body reads premium; two sans faces read
+like a template. Set `font-feature-settings` and real line-height (1.5–1.65 body,
+1.05–1.2 display).
+
+**Space is the design.** Most weak pages are weak because everything is 16px
+apart. Use a scale (4 / 8 / 12 / 16 / 24 / 32 / 48 / 64) and let the important
+things have room. Section padding should be 2–4× what feels right at first.
+
+**Colour.** One ink, one paper, one accent, and greys derived from the ink rather
+than pure `#888`. Pure black on pure white is a tell. Prefer near-black
+(`#1a1713`) on warm paper (`#f3f3f3`) over `#000` on `#fff`.
+
+**Depth without drop shadows.** Hairline borders (`1px` at 6–10% ink) plus a very
+soft shadow beats a heavy `box-shadow`. Two competing shadows look amateur.
+
+**Motion.** Transitions on hover/focus at 150–300ms, `ease-out`. Never animate
+layout properties (`width`, `top`) — animate `transform` and `opacity`.
+`prefers-reduced-motion` must disable them.
+
+## Designed states — the thing that separates real apps from demos
+
+Every list, table and data view needs FOUR states, and they must not look alike:
+
+1. **Loading** — a skeleton with the shape of the real content, not a spinner.
+2. **Empty** — says what will fill it and how. "No invoices yet — create your
+   first one" beats "No data".
+3. **Error** — says what failed and what to do. Never a blank region.
+4. **Populated.**
+
+⚠️ An empty state and a failed load must render DIFFERENTLY. If they look the
+same, a broken page looks merely new, and nobody reports it.
+
+## Responsive
+
+Design the small screen first. Real content must never cause horizontal page
+scroll — wide tables and code blocks get their own `overflow-x: auto` container
+instead. Use `clamp()` for display type rather than three breakpoints.
+
+## Before calling it done
+
+- Does it look like it was made for THIS content, or could the copy be swapped
+  for any other product?
+- Is there one clear focal point per screen?
+- Are the four states designed?
+- Does it work at 360px wide?
+
+## ⭐⭐⭐ THE TOOLBOX — two files you can reference for free
+
+**Multi-file output only.** Reference either and it is written into the project
+for you; never paste their contents, and never fetch them from a CDN.
+
+```html
+<link rel="stylesheet" href="acuvo-ui.css">
+<script src="acuvo-motion.js" defer></script>
+```
+
+### `acuvo-ui.css` — the things a page cannot fake
+
+A modern reset, a **fluid type scale** (`--step--1` … `--step-4`, all `clamp()`),
+a designed dark mode via `prefers-color-scheme`, and primitives with real states:
+`.card` `.card-hover` `.btn` `.btn-ghost` `.field` `.label` `.chip` `.eyebrow`
+`.lead` `.divider`. Layout helpers: `.wrap` `.wrap-narrow` `.section` `.stack`
+`.row` `.grid` (auto-fit, `--min` to tune).
+
+⭐ **Restyle it with variables, do not fight it.** `--accent`, `--radius`,
+`--font`, `--ink`, `--bg`, `--line` are the knobs. Setting `--accent` and a
+Google font is usually the whole brand.
+
+### `acuvo-motion.js` — the 90% of motion that reads as designed
+
+Attributes, no API to learn:
+
+| attribute | what it does |
+|---|---|
+| `data-reveal` | fades and lifts in when scrolled into view |
+| `data-stagger="70"` | reveals the element's CHILDREN in sequence, 70ms apart |
+| `data-count="900"` | counts a number up on first view, keeping its prefix/suffix (`$1,250` works) |
+| `data-parallax="0.2"` | gentle transform-only parallax |
+
+⚠️ **Everything is disabled under `prefers-reduced-motion`, and that is not
+negotiable.** Motion someone did not consent to is an accessibility defect.
+`data-count` also keeps the element's original text, so the page reads correctly
+with JavaScript off.
+
+## ⚠️⚠️ WHAT THE TOOLBOX DOES NOT DO — do not reach for a CDN
+
+There is no timeline choreography, no physics, no chart library. **A generated
+app may load a stylesheet from Google Fonts and NOTHING ELSE, and no external
+script at all** — that is the Content Security Policy, it is deliberate, and a
+`<script src="https://cdn…">` will be refused by the browser rather than
+silently degrade.
+
+⭐ So build the rest with inline CSS and SVG, which you are good at. A hand-drawn
+SVG bar chart beats a blocked library every time.

package/skills/animation.md

@@ -0,0 +1,84 @@
+---
+name: animation
+description: Motion that reads as quality — what to animate, timings that feel right, and reduced-motion
+when: When adding a transition, a hover state, a loading indicator, or anything that moves
+---
+
+# Animation
+
+## Motion explains a change. It is not decoration.
+
+Good motion answers *"what just happened and where did it come from"*. A panel
+that slides from the button that opened it tells the eye where it belongs. The
+same panel fading in from nowhere tells it nothing.
+
+If a movement does not explain something, it is delay.
+
+## ⚠️⚠️ Animate only `transform` and `opacity`
+
+```css
+✗ transition: left .3s, width .3s, height .3s;   /* layout every frame */
+✓ transition: transform .3s, opacity .3s;        /* compositor only */
+```
+
+`transform` and `opacity` can be handled without recalculating layout or
+repainting. Animating `left`, `top`, `width`, `height`, `margin` or `box-shadow`
+forces work on every frame and is the usual cause of janky motion on a phone
+(`performance`).
+
+To move something: `transform: translateX()`. To resize: `scale()`.
+
+## Timings that feel right
+
+| what | duration |
+|---|---|
+| hover, small state change | 100–150ms |
+| dropdown, tooltip, toggle | 150–250ms |
+| panel, modal, page transition | 250–400ms |
+| anything | **never past ~500ms** |
+
+⭐ Under ~100ms reads as instant — fine for feedback, wasted on anything you
+want noticed. Past ~500ms the interface feels like it is thinking, and users
+start clicking again.
+
+**Easing:** `ease-out` for things entering (fast then settling — feels
+responsive), `ease-in` for things leaving. Never `linear` for anything physical;
+it reads as mechanical because nothing in the world moves that way.
+
+## Enter and exit are not symmetrical
+
+Entrances can afford to be seen. Exits should be quicker — the user has already
+decided, and making them wait to leave is the most irritating kind of animation.
+Roughly: exit at half the entrance duration.
+
+## ⚠️⚠️ Respect `prefers-reduced-motion` — it is a medical setting
+
+For some people motion causes nausea or vertigo. This is not a preference to
+override:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: .01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: .01ms !important;
+  }
+}
+```
+
+⭐ Reduced ≠ removed. Keep the state change instant and legible — a cross-fade
+is usually still fine; it is *movement*, parallax and spin that cause trouble.
+
+## Loading states
+
+- Under ~300ms: show nothing. A spinner that flashes is worse than a still
+  moment.
+- Longer: a skeleton in the shape of what is coming beats a spinner — it says
+  what is arriving, and the layout does not jump when it lands.
+- Long and unknown: say what is happening in words.
+
+## Restraint is the whole skill
+
+One considered transition reads as expensive. Six competing ones read as a
+template. If everything moves, nothing is emphasised — which is the same
+argument as using one accent colour rather than seven.

package/skills/api-design.md

@@ -0,0 +1,82 @@
+---
+name: api-design
+description: REST shapes, status codes that mean something, idempotency and pagination that survives growth
+when: When adding an endpoint, designing a route, or deciding what a handler returns
+---
+
+# API design
+
+## Nouns in the path, verbs in the method
+
+```
+✗ POST /createInvoice        ✗ GET /getInvoiceById?id=7
+✓ POST /invoices             ✓ GET  /invoices/7
+✓ PATCH /invoices/7          ✓ DELETE /invoices/7
+```
+
+`GET` never changes anything — crawlers, prefetchers and browser history all
+assume that, and one of them will eventually prove it.
+
+## Status codes are the API's error handling
+
+| code | meaning | the mistake it prevents |
+|---|---|---|
+| 200 | here it is | — |
+| 201 | created, `Location:` points at it | 200 with a body you have to parse to learn the id |
+| 400 | your request is malformed | using 500 for a typo |
+| 401 | who are you? | conflated with 403 |
+| 403 | I know who you are; no | conflated with 401 |
+| 404 | no such thing | 200 with `{"error":"not found"}` |
+| 409 | conflicts with current state | 400 for a duplicate |
+| 422 | shape is fine, values are not | 400 for everything |
+| 429 | slow down | silence |
+| 500 | **we** broke | blaming the caller |
+
+⚠️ `200 {"success": false}` forces every client to parse a body to discover
+failure, and defeats every retry, cache and monitor in the path.
+
+## ⚠️⚠️ Idempotency: the network will deliver twice
+
+A client that times out will retry. Without an idempotency key, the customer is
+charged twice and the receipt is genuine.
+
+```
+POST /payments
+Idempotency-Key: 8f3a…            ← client-generated, stored with the result
+```
+
+Same key → return the FIRST result, do not perform the work again. `PUT` and
+`DELETE` are naturally idempotent; `POST` is the one that needs help.
+
+## Pagination: never return everything
+
+`GET /invoices` on a table that grows is a timeout waiting for a customer big
+enough to trigger it.
+
+- **Offset** (`?page=3&limit=50`) is simple and drifts: rows inserted while
+  paging shift the window and items are seen twice or missed.
+- **Cursor** (`?after=<opaque>&limit=50`) is stable and is what to use for
+  anything ordered by time.
+
+Always cap `limit` server-side. A client asking for 1,000,000 gets your maximum,
+not an outage.
+
+## Consistent shapes
+
+Pick one envelope and use it everywhere:
+
+```json
+{ "data": [...], "next_cursor": "…" }
+{ "error": { "code": "invoice_not_found", "message": "No invoice with id 7" } }
+```
+
+A machine-readable `code` plus a human-readable `message` — clients branch on
+the code, humans read the message. Never make a client match on prose.
+
+## Versioning, dates and money
+
+- Version before you need it: `/v1/`. Removing a version is a conversation;
+  breaking an unversioned API is an outage.
+- Timestamps in **UTC ISO-8601** with an offset. Never a bare local time.
+- Money in **integer minor units** with a currency (`{"amount": 1250,
+  "currency": "AUD"}`). Floating point and money do not belong together.

package/skills/auth-and-sessions.md

@@ -0,0 +1,78 @@
+---
+name: auth-and-sessions
+description: Sessions, refresh, and the re-signin bug — why a user gets logged out mid-click and how to stop it
+when: When building sign-in, protecting a route, or debugging a user being logged out unexpectedly
+---
+
+# Auth and sessions
+
+## ⚠️⚠️ The re-signin bug, which is nearly always the same two causes
+
+A user is signed in, clicks something, and lands on the login page. Almost every
+time it is one of these:
+
+**1. A failed refresh treated as "signed out".**
+
+```js
+✗ const { user } = await getUser();
+  if (!user) redirect('/login');      // a 500 from the auth server looks identical to a real logout
+```
+
+`getUser()` can fail three ways and they are not the same:
+
+| what happened | correct response |
+|---|---|
+| valid session | continue |
+| **401 / 403** — the token is genuinely bad | sign out |
+| **network error, 5xx, timeout** | **do NOT sign out** — retry, or fail the request |
+
+Destroying a session because the auth service had a bad second is the bug. Read
+the status, not just the absence of a user. This is `error-handling`'s rule —
+*empty ≠ unreadable* — applied to identity.
+
+**2. Two things refreshing the same token at once.** Concurrent refreshes race;
+one rotates the token, the other presents the now-stale one and is rejected.
+Single-flight the refresh: one in-flight promise that every caller awaits.
+
+## Sessions expire. Plan the moment.
+
+- Short-lived access token + long-lived refresh token is the standard shape.
+- Refresh **before** expiry, not on the 401 — a refresh triggered by a failure
+  means the user already saw an error.
+- When the session really is over, say so and **preserve what they were doing**.
+  Sending someone to a bare login screen after they typed a long form is the
+  part that makes people angry, not the logout itself.
+
+## ⚠️⚠️ The client cannot be the gate
+
+Hiding a button is presentation. The check that matters runs on the server, on
+every request, for every resource — because the client is a program the user
+controls.
+
+```js
+✗ if (user.role === 'admin') showDeleteButton();   // and the endpoint checks nothing
+✓ the endpoint verifies the caller may delete THIS row, every time
+```
+
+Route protection in a framework is convenience. An unprotected API under a
+protected page is still an unprotected API.
+
+## Passwords, if you must hold them
+
+Never store them recoverable. `bcrypt`, `scrypt` or `argon2` — never a plain
+hash, never your own scheme. Compare with a constant-time function.
+
+Better: do not hold them. An OAuth provider or a magic link removes the entire
+class of problem, including the breach you would otherwise have to disclose.
+
+## Cookies
+
+`HttpOnly` (JavaScript cannot read it, so XSS cannot steal it), `Secure`,
+`SameSite=Lax` as the default. A token in `localStorage` is readable by every
+script on the page, including one that arrived through a dependency.
+
+## ⚠️ Multi-tenant: the row belongs to a tenant, not to a user
+
+Every query filters by tenant, and the filter comes from the SESSION, never from
+a parameter the caller supplied. `?tenant=other-company` is the whole attack.
+See `supabase-multitenant` for enforcing that at the database.

package/skills/build-with-a-framework.md

@@ -0,0 +1,101 @@
+---
+name: build-with-a-framework
+description: The scaffold that is known to build — pinned, base-relative, and the four traps that waste a round each
+when: Before running npm install, or whenever the answer is React/Vue/Svelte/Tailwind rather than hand-written vanilla
+---
+
+# Building with a framework
+
+You have a real machine. `npm install` works, a build step works, and the output
+of that build is what ships. This is the scaffold that is **known to work** —
+measured on a live machine: install 11.9s, `vite build` 2.0s, exit 0 both.
+
+## ⭐ Do not re-derive the scaffold. Write `src/App.jsx` and copy the rest.
+
+Asking a model to emit `package.json`, `vite.config.js`, `index.html` and
+`main.jsx` correctly on every build spends tokens re-deriving a solved problem
+and fails in ways that are tedious to repair. **These four files are correct,
+and they are free.** The part that is actually the request is `src/App.jsx`.
+
+`package.json`
+
+```json
+{
+  "name": "app",
+  "private": true,
+  "type": "module",
+  "scripts": { "build": "vite build" },
+  "dependencies": { "react": "18.3.1", "react-dom": "18.3.1" },
+  "devDependencies": { "vite": "5.4.0", "@vitejs/plugin-react": "4.3.1" }
+}
+```
+
+`vite.config.js`
+
+```js
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+export default defineConfig({ plugins: [react()], base: './' });
+```
+
+`index.html`
+
+```html
+<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>App</title></head><body><div id="root"></div>
+<script type="module" src="/src/main.jsx"></script></body></html>
+```
+
+`src/main.jsx`
+
+```js
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App.jsx';
+createRoot(document.getElementById('root')).render(<App />);
+```
+
+Then:
+
+```
+npm install --no-audit --no-fund && npm run build
+```
+
+## ⚠️ The four traps, each of which costs a round
+
+**1. `"^latest"` is how a build that worked yesterday breaks today.** Every
+version above is pinned on purpose. If you add a dependency, pin it too.
+
+**2. `base: './'` is not decoration.** Without it the built `index.html` asks for
+`/assets/…` from the site ROOT, and what ships is served from a path. The page
+loads, the bundle 404s, and you get a blank screen with no error in the build.
+
+**3. If your machine is a hosted sandbox, it is shut down while you think.**
+That is true of Acuvo's builder, where the box stops billing for idle time and a
+fresh one starts for your next command: **your files come back; anything you
+INSTALLED does not.** It is NOT true when you are running on someone's own
+computer, where nothing disappears between commands.
+
+⭐ You do not have to know which you are on. If a build suddenly says
+`vite: not found` after it worked, that is this and not your code — re-run the
+install. Where it applies, the command output says so in its first line.
+
+**4. What ships is `dist/`, not your source.** `src/App.jsx` is not a web page.
+So the build MUST pass: a project whose `npm run build` fails ships nothing at
+all, and you will be asked to fix it before you can finish.
+
+## ⚠️ Every asset the built page references must exist
+
+The built `dist/index.html` names its bundle and its stylesheet. If one of them
+is missing from the tree, the page still validates and renders **nothing** —
+which is the most expensive failure available, because every other signal says
+the build succeeded. After `npm run build`, check that `dist/` contains what
+`dist/index.html` asks for.
+
+## When NOT to reach for this
+
+A page a visitor only reads — a landing page, a brochure, a menu — is
+`index.html` + `styles.css`, and a framework makes it slower to load and slower
+to build for no gain. Reach for a framework when there is real state to manage:
+a list that changes, a form with steps, a board you drag things around.

package/skills/colour-and-contrast.md

@@ -0,0 +1,112 @@
+---
+name: colour-and-contrast
+description: Building a palette that looks deliberate — restraint, neutrals, one accent, and contrast that passes
+when: Choosing any colour, theming a page, or when output looks flat, muddy or garish
+---
+
+# Colour
+
+Generated pages go wrong in one of two directions: **grey mush** (everything
+`#666` on `#f5f5f5`, nothing to look at) or **carnival** (a purple gradient, a
+teal button, an orange badge, and a red heading). Both come from choosing
+colours one at a time instead of building a set.
+
+## ⭐ The rule that fixes most of it: one accent
+
+A page needs **many neutrals and exactly one accent.** The accent is what the
+eye is supposed to find — the primary action, the live figure, the one link that
+matters. The moment there are two accents, there is no accent.
+
+```
+neutrals   8–10 steps, near-grey, subtly tinted toward the accent
+accent      1 hue, 2–3 steps (base, hover, subtle background)
+semantic    success / warning / danger — used ONLY for state, never decoration
+```
+
+⚠️ **Semantic colours are not palette colours.** Green means "it worked". If
+green is also the brand colour, a success message is invisible and a decorative
+green panel reads as a system state.
+
+## Neutrals are the whole page — tint them
+
+Pure `#000`/`#888`/`#fff` is the flattest a page can look. Real interfaces use
+neutrals with a few degrees of hue in them, usually pulled toward the accent.
+
+```css
+:root {
+  /* accent hue 240 → neutrals carry a trace of it */
+  --n-0:  hsl(240 20% 99%);
+  --n-50: hsl(240 16% 96%);
+  --n-100:hsl(240 14% 92%);
+  --n-300:hsl(240 10% 76%);
+  --n-500:hsl(240  8% 48%);
+  --n-700:hsl(240 10% 28%);
+  --n-900:hsl(240 18% 11%);
+  --accent:      hsl(240 76% 56%);
+  --accent-weak: hsl(240 76% 96%);
+}
+```
+
+⭐ **HSL, not hex, while you are choosing.** Same hue, same saturation, moving
+lightness — that is what makes a family look like a family. Hex hides the
+relationship and you end up with nine unrelated colours.
+
+The vendored token layer already ships neutrals and an accent. **Prefer those
+tokens.** Introduce new colour only when the brief names a brand colour.
+
+## Contrast is a requirement, not a preference
+
+| use | minimum |
+|---|---|
+| body text | **4.5:1** |
+| large text (≥24px, or ≥19px bold) | **3:1** |
+| icons, borders, focus rings, UI edges | **3:1** |
+| disabled text | exempt, but then it must be obviously disabled |
+
+⚠️ **Placeholder text and light-grey captions are where this fails almost every
+time.** `#999` on `#fff` is 2.8:1 — it fails, and it fails for everyone in
+sunlight, not just people with low vision.
+
+⚠️ **White text on a mid-tone accent usually fails.** `#fff` on a 56%-lightness
+blue is around 3.9:1. Either darken the accent to ~45% lightness for buttons, or
+use near-black text on it. Check, do not assume.
+
+⭐ **Never signal with colour alone.** A red border on an invalid field is
+invisible to a colour-blind user and to a screenshot in greyscale. Add an icon,
+a label, or text. Roughly 1 in 12 men cannot distinguish your red from your
+green.
+
+## Where colour goes
+
+- **Backgrounds carry almost no saturation.** Depth comes from *slightly*
+  different neutrals plus a border, not from colour.
+- **Borders `--n-100`–`--n-300`.** A 1px hairline does more for perceived
+  quality than a shadow does.
+- ⚠️ **Gradients: at most one, and keep it subtle.** Two stops, close in hue.
+  A purple-to-pink hero gradient is the single most recognisable "AI made this"
+  signal in existence. If the brief did not ask for a gradient, do not add one.
+- **Shadows are neutral and soft**, from the elevation ramp
+  (`--shadow-1`…`--shadow-6`). A coloured shadow reads as a toy.
+
+## Dark mode, if asked for
+
+Not an inversion. Dark surfaces need **less** saturation and **more**
+lightness in the accent, or it vibrates.
+
+```css
+@media (prefers-color-scheme: dark) {
+  :root { --bg: hsl(240 14% 8%); --fg: hsl(240 12% 92%); --accent: hsl(240 70% 68%); }
+}
+```
+
+- Surface `#0d0d10`-ish, not `#000`. Pure black with white text causes halation.
+- Body text near `#e8e8ea`, not `#fff`.
+- Elevation in dark mode is a *lighter surface*, not a bigger shadow.
+
+## Before calling it done
+
+- One accent. Count them — if there are two, one is wrong.
+- Body text passes 4.5:1; buttons and placeholders were checked, not assumed.
+- Neutrals share a hue; nothing is pure `#000` or pure `#888`.
+- No unrequested gradient. No coloured shadows.
+- Nothing is communicated by colour alone.

package/skills/creative-engines.md

@@ -0,0 +1,81 @@
+---
+name: creative-engines
+description: Image, voice and editing engines — cost first, edit rather than regenerate, check what came back
+when: When asked to make, change, reframe or narrate an image or audio, or asked what something will cost
+---
+
+# Creative Engines
+
+Acuvo can generate and edit real media. The engines are good; most bad results
+come from reaching for the wrong verb, not from the model.
+
+| verb | use it for |
+|---|---|
+| `list_engines` | what this account can reach, and **what it costs in credits** |
+| `generate_image` | a new image from a prompt |
+| `edit_image` | change **one thing** in an image that already exists |
+| `expand_image` | a new aspect ratio by painting new edges, not cropping |
+| `speak` | text to an audio file, in a fixed voice |
+| `read_image` | LOOK at what you produced |
+
+## ⚠️⚠️ Cost before spending, every time
+
+**`list_engines` before you spend, whenever the user asks what something costs,
+asks for "the cheap one", or is about to buy something at volume.** It reports
+what this account can actually reach and the credit price of each engine.
+
+Spending someone's credits on an engine they did not choose, at a price they
+never saw, is the worst thing you can do here. If a request implies many images,
+say the total first.
+
+## ⭐⭐ EDIT beats REGENERATE — almost always
+
+When an image is nearly right, do **not** generate it again. A regeneration
+throws away everything that was already good and rerolls the composition, the
+lighting and the subject.
+
+**`edit_image` names what to replace in plain words:**
+`target: "the sign on the van"` → `replacement: "plain white panel"`.
+
+⭐ This is cheaper, faster, and it *keeps the picture the user already liked*.
+"Make the sign blank" is an edit. "Try again but better" is a reroll, and the
+user will lose the version they wanted.
+
+Same reasoning for aspect ratio: **`expand_image` paints new edges** to reach
+16:9, 9:16 or 4:5. Cropping to reframe throws away the subject; expanding keeps
+it and invents only the margins.
+
+## ⚠️ Use the path the result gives you
+
+`generate_image` returns a `.png` **or** a `.jpg` — the extension follows
+whatever the engine produced. **Use the exact path from the result.** Do not
+assume `.png` and do not construct the filename yourself; a hardcoded extension
+is a file-not-found on the next step.
+
+## ⚠️⚠️ `speak` uses a FIXED voice — never offer to clone one
+
+`speak` reads in one fixed voice. **It cannot clone anybody.** Do not offer to
+make it sound like the user, like a celebrity, or like anyone named. Leave
+`engine` unset unless there is a reason.
+
+Promising a cloned voice from this verb is a promise the tool cannot keep, and
+the user finds out only after they have spent credits.
+
+## ⭐ Always look at what came back
+
+**`read_image` on anything you generated**, before you present it. Ask it a
+question if you have a specific worry — spelling is the usual one, because text
+rendered inside a generated image is wrong often enough that it must be checked
+rather than assumed.
+
+Presenting a generated image you have not looked at is presenting a guess. See
+the `designing-by-looking` skill — it is the same rule as never shipping an
+unrendered page.
+
+## ⭐ Choosing size
+
+Ask what the image is FOR before picking dimensions: a hero is wide, a post is
+square or 4:5, a story is 9:16. Generating square and cropping later loses the
+subject; generating at the right shape, or expanding to it, does not.
+
+Related skills: `designing-by-looking`, `acuvo-design-system`.