@warlock.js/core 4.0.174 → 4.1.3

package/skills/encrypt-data/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: encrypt-data
+description: 'Reversible AES-256-GCM `encrypt` / `decrypt` for secrets you need to read back; one-way HMAC-SHA256 `hmacHash` for deterministic fingerprints (lookup/dedup of encrypted columns). Keys come from `src/config/encryption.ts`. Triggers: `encrypt`, `decrypt`, `hmacHash`, `EncryptionConfigurations`, `APP_ENCRYPTION_KEY`, `APP_HMAC_KEY`; "store an API key reversibly", "fingerprint an encrypted column for lookup", "AES-256-GCM secret", "HMAC-SHA256 dedup key"; typical import `import { encrypt, decrypt, hmacHash } from "@warlock.js/core"`. Skip: password hashing — `@warlock.js/core/hash-password/SKILL.md`; config wiring — `@warlock.js/core/configure-app/SKILL.md`; competing libs Node `crypto` direct, `crypto-js`, `libsodium-wrappers`.'
+---
+
+# Warlock — encrypt and fingerprint
+
+Two helpers, two different jobs:
+
+| Tool                    | Direction  | Algorithm    | Use for                                                        |
+| ----------------------- | ---------- | ------------ | -------------------------------------------------------------- |
+| `encrypt` / `decrypt`   | reversible | AES-256-GCM  | Secrets you need to read back (API keys, OAuth tokens).        |
+| `hmacHash`              | one-way    | HMAC-SHA256  | Deterministic fingerprint for lookup/dedup of encrypted values. |
+
+Both live in `@warlock.js/core`. For **password hashing** (a one-way job with very different requirements), reach for [`hash-password/SKILL.md`](../hash-password/SKILL.md) instead — bcrypt is the right tool there, not encrypt.
+
+## The shape
+
+```ts
+import { encrypt, decrypt, hmacHash } from "@warlock.js/core";
+
+// reversible — fast, integrity-checked, fresh IV per call
+const cipherText = encrypt("sk-proj-12345");
+const plainText = decrypt(cipherText);
+
+// fingerprint — fast, deterministic (same input → same output)
+const fingerprint = hmacHash("sk-proj-12345");
+```
+
+## Configuration — `src/config/encryption.ts`
+
+```ts title="src/config/encryption.ts"
+import type { EncryptionConfigurations } from "@warlock.js/core";
+import { env } from "@warlock.js/core";
+
+const encryptionConfig: EncryptionConfigurations = {
+  key: env("APP_ENCRYPTION_KEY"),     // 64 hex chars = 32 bytes — required
+  algorithm: "aes-256-gcm",            // optional, default
+  hmacKey: env("APP_HMAC_KEY"),       // 64 hex chars — falls back to `key` if absent
+};
+
+export default encryptionConfig;
+```
+
+Generate the keys once (Node REPL):
+
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+Put both in `.env` and **never rotate the encryption key without a migration** — every value encrypted under the old key becomes garbage. The HMAC key can rotate if you accept that fingerprints recomputed under the new key won't match historical ones.
+
+## `encrypt` / `decrypt` — reversible secrets
+
+For values you need to read back: API keys you'll later send to a third party, OAuth refresh tokens, credentials in a vault row. **Never use this for passwords** — you'd be storing recoverable plaintext, which means a database breach equals a credentials leak.
+
+```ts title="src/app/ai-api-keys/services/create-ai-api-key.service.ts"
+import { ConflictError, encrypt, hmacHash } from "@warlock.js/core";
+import { AiApiKey } from "../models/ai-api-key";
+import { aiApiKeysRepository } from "../repositories/ai-api-keys.repository";
+
+export async function createAiApiKeyService(data: { key: string; organization_id: string }) {
+  if (
+    await aiApiKeysRepository.first({
+      organization_id: data.organization_id,
+      hash: hmacHash(data.key),
+    })
+  ) {
+    throw new ConflictError("API key already exists");
+  }
+
+  return AiApiKey.create({
+    ...data,
+    key: encrypt(data.key),                // the secret, recoverable
+    hash: hmacHash(data.key),              // the fingerprint, lookup-able
+    last_four_chars: data.key.slice(-4),
+  });
+}
+```
+
+This is the canonical pattern: **encrypt the secret, hmacHash the same value for lookup**. Now you can find the row by user-provided plaintext (`first({ hash: hmacHash(input) })`) without ever decrypting, and `decrypt(row.get("key"))` recovers the secret when you need it.
+
+```ts title="reading it back"
+import { decrypt } from "@warlock.js/core";
+
+const apiKey = await aiApiKeysRepository.first({ id });
+const plainKey = decrypt(apiKey.get("key"));
+```
+
+### Format
+
+`encrypt(plain)` returns `iv:ciphertext:authTag` — three hex chunks joined with `:`. The IV is a fresh 16-byte random per call, so encrypting the same input twice yields two different cipher texts (this is what you want — it defeats pattern analysis). The `authTag` is GCM's integrity check: if the stored ciphertext is tampered with, `decrypt()` throws.
+
+`decrypt()` throws on:
+
+- Invalid format (not three colon-separated parts).
+- Wrong key.
+- Tampered ciphertext (auth tag mismatch).
+- Wrong algorithm vs the one used to encrypt.
+
+Handle those at the boundary — they almost always mean misconfiguration or a corrupted row, not a runtime bug.
+
+### Empty-string passthrough
+
+Both `encrypt("")` and `decrypt("")` return `""` unchanged — convenient for nullable columns where `""` means "no value." `null` / `undefined` will throw at the type level (the signatures require `string`).
+
+## `hmacHash` — deterministic fingerprints
+
+A keyed one-way hash. Same input + same key always produces the same 64-hex-char output. Two properties that matter:
+
+1. **Deterministic.** Use it to dedup or look up encrypted values without decrypting them.
+2. **Keyed.** An attacker with the database but not the HMAC key can't precompute a rainbow table — they don't know which hash function you're using.
+
+Three solid use cases:
+
+```ts
+// 1. Unique constraint on an encrypted column
+await aiApiKeysRepository.first({ hash: hmacHash(userInput) });
+
+// 2. Idempotency key derived from a payload
+await idempotencyKeysRepository.first({ hash: hmacHash(JSON.stringify(request)) });
+
+// 3. Fingerprint of a secret for audit logs (without storing the secret)
+log.info("api-key", "used", { fingerprint: hmacHash(apiKey).slice(0, 8) });
+```
+
+**Do not use `hmacHash` for passwords.** It's fast — a brute-force attack with a stolen database would clear common passwords in minutes. That's what bcrypt is for (see [`hash-password/SKILL.md`](../hash-password/SKILL.md)).
+
+## Common patterns
+
+### Encrypt + fingerprint together (the canonical pattern)
+
+```ts
+await Model.create({
+  key: encrypt(plain),
+  hash: hmacHash(plain),                   // for lookups
+  last_four_chars: plain.slice(-4),         // for UI display ("ending in 1234")
+});
+```
+
+`last_four_chars` is useful in dashboards — show users which key is which without revealing it.
+
+### Encrypt before persisting via a model accessor
+
+```ts title="src/app/secrets/models/secret/secret.model.ts"
+import { encrypt, decrypt } from "@warlock.js/core";
+
+export class Secret extends Model {
+  public setValue(plain: string) {
+    this.set("value", encrypt(plain));
+  }
+
+  public getValue(): string {
+    return decrypt(this.get("value"));
+  }
+}
+```
+
+Keeps the encryption boundary in one place — controllers and services deal in plaintext, the model handles the crypto.
+
+### Audit log without leaking the secret
+
+```ts
+log.info("ai-api-key", "used", {
+  organization_id,
+  fingerprint: hmacHash(apiKey).slice(0, 8),  // first 8 hex chars = enough to correlate
+});
+```
+
+You can search logs for the same fingerprint to track usage of a specific key across requests without ever storing the plaintext in your log pipeline.
+
+### Idempotency keys
+
+```ts
+const idempotencyKey = hmacHash(JSON.stringify({
+  user_id: user.id,
+  action: "transfer",
+  amount,
+  to,
+  // include a monotonic component if the same exact payload should be allowed twice
+}));
+
+const existing = await idempotencyRepository.first({ key: idempotencyKey });
+if (existing) return existing.get("result");
+```
+
+Same payload → same key → returns the cached result. Different keys (because the HMAC is keyed) per environment if you set different `hmacKey` values.
+
+## Gotchas
+
+- **Never log decrypted values.** A log line is a leak. If you must debug, log the HMAC fingerprint, not the plaintext.
+- **`encrypt`/`decrypt` keys must be 32 bytes (64 hex chars).** Anything else throws with a clear message. Don't truncate or pad.
+- **Empty key value is fatal.** If `env("APP_ENCRYPTION_KEY")` returns `undefined`, the first `encrypt()` call throws "Missing encryption key" at runtime, not boot. Cover this in your startup health check.
+- **HMAC falls back to the encryption key.** If `hmacKey` isn't set, `hmacHash` uses `key`. Convenient, but slightly weakens your isolation — best practice is two separate keys.
+- **Don't reuse the same value across encrypt and password.** A bcrypt hash of a value isn't comparable to an encryption of that value. They're different domains.
+- **Rotating the encryption key requires a migration.** Every existing ciphertext becomes unrecoverable under a new key. Plan rotation as: keep the old key as `OLD_APP_ENCRYPTION_KEY`, decrypt each row with old, encrypt with new, retire old key once the table is clean.
+
+## Installation
+
+`encrypt` / `decrypt` / `hmacHash` use Node's built-in `crypto` — no extra dependency. They're available out of the box.
+
+Password hashing (`hashPassword`) needs `bcryptjs`, which is its own install — see [`hash-password/SKILL.md`](../hash-password/SKILL.md).
+
+## See also
+
+- [`hash-password/SKILL.md`](../hash-password/SKILL.md) — bcrypt password hashing (the third member of the encryption module, but a different job entirely).
+- [`configure-app/SKILL.md`](../configure-app/SKILL.md) — `src/config/encryption.ts` and env wiring.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — service layering, where the encryption boundary should sit.

package/skills/hash-password/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: hash-password
+description: 'One-way bcrypt password hashing — `hashPassword` / `verifyPassword`, plus the declarative `useHashedPassword()` schema transformer that auto-hashes a model''s password field on save. Salt rounds come from `src/config/encryption.ts`. Triggers: `hashPassword`, `verifyPassword`, `useHashedPassword`, `password.salt`, `bcryptjs`; "hash a user password", "verify login credentials", "auto-hash on save", "rotate a password"; typical import `import { hashPassword, verifyPassword } from "@warlock.js/core"`. Skip: reversible secrets — `@warlock.js/core/encrypt-data/SKILL.md`; the other transformers — `@warlock.js/core/use-model-transformers/SKILL.md`; config wiring — `@warlock.js/core/configure-app/SKILL.md`; competing libs `bcrypt` native, `argon2`, `scrypt`.'
+---
+
+# Warlock — hash a password
+
+For storing user-typed passwords, bcrypt is the one right answer — and the only one. It's **deliberately slow** (~250ms per call with the default salt rounds), which is what makes it expensive to brute-force a stolen password database. Use it for nothing else: not API keys, not session tokens, not "this needs to be one-way."
+
+If your value needs to be read back later → [`encrypt-data/SKILL.md`](../encrypt-data/SKILL.md).
+If you need a fast searchable fingerprint of an encrypted value → also `encrypt-data` (`hmacHash`).
+
+## The shape
+
+```ts
+import { hashPassword, verifyPassword } from "@warlock.js/core";
+
+const hashed = await hashPassword("user-password-123");
+// → "$2b$12$..." — store this
+
+const valid = await verifyPassword("user-password-123", hashed);
+// → true / false
+```
+
+Both are async because bcrypt is CPU-bound. The framework uses `bcryptjs` (pure JS — portable across every platform, no native build) under the hood.
+
+## Configuration — `src/config/encryption.ts`
+
+```ts title="src/config/encryption.ts"
+import type { EncryptionConfigurations } from "@warlock.js/core";
+
+const encryptionConfig: EncryptionConfigurations = {
+  password: {
+    salt: 12,    // bcrypt rounds — 10–12 is the standard band
+  },
+  // ...other crypto config (key/hmacKey for encrypt/decrypt — see encrypt-data skill)
+};
+
+export default encryptionConfig;
+```
+
+The `salt` knob is bcrypt's **work factor** — `2^salt` iterations per hash. Each unit doubles the cost. `12` is the modern default; bump to `13`/`14` if your hardware is fast enough that login feels instant and you want a bigger brute-force tax. Don't go below `10` — that's the lower bound for modern security.
+
+## `hashPassword` / `verifyPassword`
+
+```ts title="src/app/users/services/register-user.service.ts"
+import { hashPassword } from "@warlock.js/core";
+import { User } from "../models/user";
+
+export async function registerUserService(input: { email: string; password: string }) {
+  const user = await User.create({
+    email: input.email,
+    password: await hashPassword(input.password),
+  });
+
+  return user;
+}
+```
+
+```ts title="src/app/auth/services/verify-credentials.service.ts"
+import { verifyPassword } from "@warlock.js/core";
+import { usersRepository } from "app/users/repositories/users.repository";
+
+export async function verifyCredentialsService(email: string, password: string) {
+  const user = await usersRepository.first({ email });
+  if (!user) return null;
+
+  const isValid = await verifyPassword(password, user.get("password"));
+  return isValid ? user : null;
+}
+```
+
+The `@warlock.js/auth` package wires both into its `auth.service.ts` — `authService.hashPassword(p)` and `authService.verifyPassword(plain, hash)` are thin proxies over these helpers. Use the auth service if you're using `@warlock.js/auth`; use the core helpers directly if you're rolling your own.
+
+## The declarative pattern — `useHashedPassword()`
+
+Manually calling `hashPassword` in every service that touches a password is repetitive and easy to forget. The framework offers a **schema transformer** that auto-hashes the field on save:
+
+```ts title="src/app/users/models/user/user.model.ts"
+import { useHashedPassword } from "@warlock.js/core";
+import { type Infer, v } from "@warlock.js/seal";
+
+export const userSchema = v.object({
+  email: v.email().unique("User"),
+  password: v.string().requiredIfEmpty("id").addTransformer(useHashedPassword()),
+});
+
+export type UserSchema = Infer<typeof userSchema>;
+```
+
+What it does:
+
+- **New row** → hashes `password` once on `.create()` / `.save()`.
+- **Existing row** → only re-hashes when the field actually changes; leaves the stored hash alone otherwise.
+- **Empty / undefined value** → returns the value untouched (won't double-hash, won't overwrite with `undefined`).
+
+Internally it calls `authService.hashPassword(value)`, which is the same bcryptjs path as the standalone helper — just attached to the schema so controllers and services never deal with plaintext storage. Pass `request.validated().password` straight into `User.create({...})` and the transformer handles the hashing.
+
+This is the **recommended pattern** for user models. The standalone helper is for non-schema contexts (CLI tools generating users, one-off scripts, custom auth services).
+
+## Common patterns
+
+### Rotate a user's password
+
+```ts
+import { hashPassword, verifyPassword } from "@warlock.js/core";
+
+const user = await usersRepository.findById(id);
+
+if (!(await verifyPassword(oldPassword, user.get("password")))) {
+  throw new BadRequestError("Current password incorrect");
+}
+
+await user.save({ password: await hashPassword(newPassword) });
+```
+
+If the model uses `useHashedPassword()`, you can skip the explicit `hashPassword` call:
+
+```ts
+await user.save({ password: newPassword });  // transformer hashes on save
+```
+
+The transformer detects that the field is changing and re-hashes.
+
+### Login flow
+
+```ts
+import { verifyPassword } from "@warlock.js/core";
+
+const user = await usersRepository.first({ email });
+if (!user) {
+  // Same response shape as "wrong password" to prevent email enumeration
+  throw new BadRequestError("Invalid credentials");
+}
+
+const valid = await verifyPassword(password, user.get("password"));
+if (!valid) {
+  throw new BadRequestError("Invalid credentials");
+}
+
+return user;
+```
+
+The "same error for missing user vs wrong password" pattern is deliberate — it stops attackers from learning which emails are registered.
+
+## Installation
+
+`hashPassword` / `verifyPassword` need `bcryptjs`. Install it directly:
+
+```bash
+yarn add bcryptjs
+```
+
+If you skip the install, the first call throws with the framework's install hint:
+
+```
+Password encryption requires the bcryptjs package.
+Install it with:
+
+  yarn add bcryptjs
+
+Or with your preferred package manager:
+
+  yarn add bcryptjs
+```
+
+There is no `warlock add` feature for password hashing — `bcryptjs` is a plain dependency, so install it directly with `yarn add bcryptjs`.
+
+## Gotchas
+
+- **Never use `hashPassword` for non-password values.** A 250ms tax on every API request because someone reached for it as a "general one-way hash" — that's a performance bug waiting to happen. For one-way fingerprinting of encrypted values, use `hmacHash` (see [`encrypt-data/SKILL.md`](../encrypt-data/SKILL.md)).
+- **Don't `hashPassword` on the request hot path twice.** Each call is ~250ms. If you `hashPassword(input)` then call it again as part of `verifyPassword`'s internals (you don't), you're stacking the tax. `verifyPassword(plain, storedHash)` takes the plaintext and the stored hash — that's the API.
+- **Don't swap `bcryptjs` for native `bcrypt` without a reason.** `bcryptjs` is portable across every platform (no native build), and the perf delta isn't meaningful in the password-verification workflow.
+- **The transformer detects changes by comparison.** If your model's password field is `null` and you save `null` again, it's a no-op. If it's a hash and you save the same hash string, also no-op. Only an actual value change triggers re-hashing.
+- **Don't strip the hash before sending the user back to the client.** Use a resource layer (`UserResource`) that excludes the password field — that's where filtering belongs, not in your service code.
+
+## See also
+
+- [`use-model-transformers/SKILL.md`](../use-model-transformers/SKILL.md) — `useHashedPassword` + the two other model transformers (`useComputedSlug`, `useComputedModel`).
+- [`encrypt-data/SKILL.md`](../encrypt-data/SKILL.md) — reversible AES-256-GCM `encrypt`/`decrypt` + one-way HMAC `hmacHash` (the other two members of the encryption module).
+- [`configure-app/SKILL.md`](../configure-app/SKILL.md) — `src/config/encryption.ts` and the `password.salt` knob.
+- [`define-resource/SKILL.md`](../define-resource/SKILL.md) — where to filter the password field out of API responses.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — service layering, where the password boundary should sit.

package/skills/process-image/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: process-image
+description: 'Transform images with the `Image` class — resize, crop, rotate, format, quality, watermark, blur, etc. — using a deferred pipeline that runs only at `save()` / `toBuffer()` / `toBase64()` / `toDataUrl()` time. Requires sharp via `warlock add image`. Triggers: `Image`, `Image.fromFile`, `Image.fromBuffer`, `Image.fromUrl`, `.resize`, `.crop`, `.watermark`, `.toBuffer`, `.toDataUrl`, `.apply`; "resize an image", "generate a thumbnail", "watermark a product photo", "build an image pipeline"; typical import `import { Image } from "@warlock.js/core"`. Skip: multipart upload entry — `@warlock.js/core/upload-file/SKILL.md`; storage persistence — `@warlock.js/core/store-file/SKILL.md`; competing libs `sharp` direct, `jimp`, `imagemagick`, `gm`.'
+---
+
+# Warlock — process an image
+
+`Image` (from `@warlock.js/core`) wraps `sharp` with a **deferred pipeline**: every chainable method (`resize`, `crop`, `format`, `quality`, `watermark`, ...) records an operation; only `save()` / `toBuffer()` / `toBase64()` / `toDataUrl()` actually run sharp. The constructor and chain stay synchronous; one `await` at the end fires the whole pipeline.
+
+`sharp` is lazy-loaded — the framework throws a clear install hint if it isn't there.
+
+## The shape
+
+```ts
+import { Image } from "@warlock.js/core";
+
+// All chaining is synchronous — single await at the end
+await new Image("./photo.jpg")
+  .resize({ width: 800 })
+  .format("webp")
+  .quality(85)
+  .save("./output.webp");
+```
+
+That's the full contract. The chain doesn't touch sharp until the output method fires.
+
+## Installation
+
+```bash
+warlock add image
+```
+
+Adds `sharp` to your dependencies. Skip it and the first `new Image(...)` throws with an install hint.
+
+## Constructors
+
+```ts
+new Image("./avatar.jpg")            // path
+new Image(buffer)                     // Buffer
+new Image(uint8Array)                 // Uint8Array
+new Image(arrayBuffer)                // ArrayBuffer
+new Image(existingSharpInstance)      // wrap a sharp.Sharp you already built
+
+// Or via static factories:
+Image.fromFile("./avatar.jpg");
+Image.fromBuffer(buffer);
+await Image.fromUrl("https://example.com/photo.jpg");   // @mongez/http under the hood
+```
+
+`Image.fromUrl(...)` is the only async factory — it fetches the URL via `@mongez/http` (`responseType: "arrayBuffer"`), then wraps the bytes. The rest are synchronous.
+
+## Transforms (chainable)
+
+Every method returns `this` so calls chain. Transforms are descriptors; nothing runs until the output method.
+
+| Method                                       | Effect                                                                       |
+| -------------------------------------------- | ---------------------------------------------------------------------------- |
+| `.resize({ width?, height?, fit?, ... })`    | sharp resize — accepts the full `sharp.ResizeOptions` shape                  |
+| `.crop({ left, top, width, height })`        | extract a region                                                             |
+| `.rotate(deg)`                               | clockwise rotation                                                           |
+| `.flip()`                                    | mirror vertically (top↔bottom)                                               |
+| `.flop()`                                    | mirror horizontally (left↔right)                                             |
+| `.blur(sigma)`                               | gaussian blur (sigma is required, must be ≥ 0.3 — throws otherwise)          |
+| `.sharpen(options?)`                         | sharp's sharpen                                                              |
+| `.grayscale()` / `.blackAndWhite()`          | grayscale (aliases)                                                          |
+| `.tint(color)`                               | color tint                                                                   |
+| `.negate(options?)`                          | invert colors                                                                |
+| `.opacity(value)`                            | 0–100, applied via composite                                                 |
+| `.trim(options?)`                            | trim borders                                                                 |
+| `.watermark(image, options?)`                | overlay one watermark — two positional args (`image` accepts the same inputs as the constructor, plus another `Image`; `options` is `sharp.OverlayOptions`) |
+| `.watermarks([{ image, options }, ...])`     | overlay many — one `WatermarkConfig` object (`{ image, options }`) per entry  |
+| `.format(format)`                            | output format — `"jpeg"`, `"png"`, `"webp"`, `"avif"`, `"tiff"`, `"heif"`, ... |
+| `.quality(1–100)`                            | lossy formats only (`jpeg` / `webp` / `avif` / `tiff` / `heif`); ignored otherwise |
+| `.apply(options)`                            | apply many transforms in one call, in a fixed canonical order                |
+
+`apply(options)` accepts an `ImageTransformOptions` object — every transform above as a key. Useful when transforms come from config or a request payload.
+
+## Outputs
+
+Each of these fires the pipeline exactly once and returns the result. Subsequent calls run the pipeline again (operations aren't memoised).
+
+```ts
+await image.save("./output.webp");          // write to disk; returns the absolute path
+const buffer = await image.toBuffer();      // → Buffer
+const base64 = await image.toBase64();      // → "iVBORw0KGgo..."
+const dataUrl = await image.toDataUrl();    // → "data:image/webp;base64,..."
+```
+
+## Common patterns
+
+### Resize an uploaded avatar to two sizes
+
+```ts
+import { Image } from "@warlock.js/core";
+
+const buffer = await uploadedAvatar.buffer();
+
+await new Image(buffer)
+  .resize({ width: 400, height: 400 })
+  .format("webp")
+  .quality(85)
+  .save("./storage/uploads/avatars/full.webp");
+
+await new Image(buffer)
+  .resize({ width: 100, height: 100 })
+  .format("webp")
+  .quality(80)
+  .save("./storage/uploads/avatars/thumb.webp");
+```
+
+Two separate `Image` instances → two pipelines. They don't share state.
+
+### Watermark + resize + format
+
+```ts
+await new Image(productPhoto)
+  .resize({ width: 1200 })
+  .watermark("./assets/logo.png", { gravity: "southeast" })
+  .quality(90)
+  .save("./output.jpg");
+```
+
+The chained `.watermark(image, options)` takes two positional arguments. (The object form `{ image, options }` is only used inside `apply({ watermark: {...} })` and `.watermarks([...])`.)
+
+### Batch transforms via `apply()`
+
+```ts
+await new Image(buffer)
+  .apply({
+    resize: { width: 800 },
+    grayscale: true,
+    blur: 2,
+    format: "webp",
+    quality: 80,
+  })
+  .save("./output.webp");
+```
+
+`apply()` runs operations in a fixed canonical order: resize → crop → rotate → flip/flop → grayscale/blackAndWhite → blur → sharpen → tint → negate → trim → watermark(s) → opacity → format/quality. If you need a different order (e.g. blur **before** resize), use the fluent chain.
+
+### Read metadata
+
+```ts
+const metadata = await new Image(buffer).image.metadata();
+console.log(metadata.width, metadata.height, metadata.format);
+```
+
+The wrapper exposes the underlying `sharp.Sharp` via `.image` for anything not surfaced through chainable methods. Operations through `.image` bypass the deferred pipeline — they run immediately.
+
+## Composition with `UploadedFile`
+
+`UploadedFile` (from multipart uploads) has its own chainable `.resize().format().quality().save(...)` that runs through `Image` internally — same deferred execution, same transforms. Use it when the source is a multipart upload; reach for `new Image(...)` directly when the source is a buffer/path/URL.
+
+See [`upload-file`](../upload-file/SKILL.md) for the multipart entry point and [`store-file`](../store-file/SKILL.md) for persisting the output through storage drivers.
+
+## Gotchas
+
+- **`sharp` is required.** Without `warlock add image`, the constructor throws with an install hint. Lazy-loaded — error fires at first use, not at module import.
+- **One `Image` = one pipeline run.** Calling `save()` twice runs the pipeline twice. To reuse output, capture the buffer once with `toBuffer()` and reuse it.
+- **`.quality(...)` is silently ignored on PNG.** PNG is lossless. JPEG, WebP, AVIF, TIFF, HEIF honor it.
+- **`apply()` ordering is canonical, not insertion order.** If the order matters, chain manually.
+- **`.image` is the raw sharp instance.** Operations on it bypass the deferred pipeline and run immediately — useful for metadata, dangerous if you mix it with chained transforms.
+- **`Image.fromUrl(...)` makes a network call** (via `@mongez/http`). It throws if the response is empty or errors. Wrap with `retry(...)` if the source URL can be flaky.
+
+## See also
+
+- [`upload-file/SKILL.md`](../upload-file/SKILL.md) — multipart uploads, where image transforms typically start.
+- [`store-file/SKILL.md`](../store-file/SKILL.md) — persisting image output through storage drivers (local / S3 / R2 / Spaces).
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — where image-processing services live.