@maestro-js/agent-skills 1.0.0-alpha.2 → 1.0.0-alpha.21

package/skills/maestro-examples/references/setlist/specs/magic-link-login.md

@@ -0,0 +1,300 @@
+# Magic Link Login
+
+Authentication uses magic links — no passwords. A user enters their email, receives a link via email, and clicking it logs them in. The email also includes the raw token as a copyable string so the user can paste it into a login form on a different device.
+
+This spec covers the maestro service setup, the magic-link DB provider, and the two authentication use cases (A1: Request Magic Link, A2: Verify Magic Link).
+
+## Maestro Service Setup
+
+Magic-link auth uses `Auth.login()` with a `verifyCredentials` callback that implements the full magic-link token verification flow (decode, lookup, hash check, expiry check, mark as used).
+
+### Hash
+
+Register two Hash providers: a default `sha256` for general hashing (remember-me tokens, etc.) and a `bcrypt` provider for hashing magic-link verifiers.
+
+```ts
+Hash.Provider.register(
+  'default',
+  Hash.Provider.create(Hash.drivers.sha256({ key: process.env.HASH_KEY!, previousKeys: [] }))
+)
+Hash.Provider.register('bcrypt', Hash.Provider.create(Hash.drivers.bcrypt({ rounds: 12 })))
+```
+
+### Crypt
+
+Crypt is required by Auth for encrypting remember-me cookies.
+
+```ts
+Crypt.Provider.register(
+  'default',
+  Crypt.Provider.create({
+    key: process.env.CRYPT_KEY!,
+    previousKeys: []
+  })
+)
+```
+
+### Auth
+
+`Credentials` is `{ token: string }` — the raw magic-link token. `verifyCredentials` decodes it, verifies the hash, checks expiry, marks the token as used, and returns the authenticatable.
+
+```ts
+type Credentials = { token: string }
+type DeviceContext = ReturnType<(typeof Helpers)['getDeviceContext']>
+
+Auth.Provider.register(
+  'default',
+  Auth.Provider.create<number, Credentials, DeviceContext>({
+    name: 'default',
+    verifyCredentials: async ({ token }) => {
+      const decoded = decodeMagicLinkToken(token)
+      if (!decoded) return null
+
+      const record = await magicLinkDbProvider.getBySelector(decoded.selector)
+      if (!record) return null
+
+      const isValid = await Hash.provider('bcrypt').verify({
+        plaintext: decoded.verifier,
+        hash: record.verifierHash
+      })
+      if (!isValid) return null
+
+      if (record.expirationDate < instantFns.now()) {
+        throw new MagicLinkExpiredTokenError()
+      }
+
+      await magicLinkDbProvider.markAsUsed(decoded.selector)
+
+      const userRows = await Db.select('SELECT credentialsInvalidBefore FROM users WHERE id = ?', [record.userId])
+      return { id: record.userId, credentialsInvalidBefore: (userRows[0]?.credentialsInvalidBefore as Iso.Instant) ?? null }
+    },
+    getAuthenticatableById: async (id) => {
+      const rows = await Db.select('SELECT id, credentialsInvalidBefore FROM users WHERE id = ?', [id])
+      const row = rows[0]
+      if (!row) return null
+      return { id: row.id as number, credentialsInvalidBefore: (row.credentialsInvalidBefore as Iso.Instant) ?? null }
+    },
+    updateCredentialsInvalidBefore: async (id, date) => {
+      await Db.update('UPDATE users SET credentialsInvalidBefore = ? WHERE id = ?', [instantFns.formatISO9075(date), id])
+    },
+    hash: Hash,
+    crypt: Crypt
+  })
+)
+```
+
+`credentialsInvalidBefore` is stored on the `users` table as a nullable `DATETIME(3)`. It starts as `NULL` and is set when `logoutOtherDevices` is called — Auth uses it to invalidate sessions and remember-me tokens created before that timestamp.
+
+Error behavior through `Auth.login()`:
+- Invalid format / not found / hash mismatch → `verifyCredentials` returns `null` → `Auth.login()` returns `{ id: null, cookie: null }`
+- Expired token → `verifyCredentials` throws `MagicLinkExpiredTokenError` → propagates to the caller (no try/catch in `Auth.login`)
+- Valid → marks as used, returns authenticatable → `Auth.login()` establishes a session via `privateLogin`
+
+### Mail
+
+Register a Mail provider for sending magic-link emails.
+
+```ts
+Mail.Provider.register(
+  'default',
+  Mail.Provider.create({
+    queue: Queue,
+    driver: Mail.drivers.ses({ /* ... */ }),
+    name: 'default',
+    globalFrom: 'noreply@setlist.example.com',
+    logger: Log
+  })
+)
+```
+
+## Magic-Link DB Provider
+
+A set of CRUD functions for the `magicLinks` table, following the same pattern as chorus's `password-reset-token-db-provider.ts`. These are plain functions — not a maestro service — consumed directly by the use cases.
+
+```ts
+import { Db } from '@maestro-js/db'
+import { isoZ } from '@maestro-js/iso-zod'
+import { instantFns } from 'iso-fns'
+import { z } from 'zod'
+
+const magicLinkRecordModel = z.object({
+  id: z.number(),
+  userId: z.number(),
+  selector: z.string(),
+  verifierHash: z.string(),
+  usedDate: isoZ.instant().nullable(),
+  expirationDate: isoZ.instant(),
+  createdDate: isoZ.instant()
+})
+
+type MagicLinkRecord = z.infer<typeof magicLinkRecordModel>
+```
+
+### create
+
+Insert a new magic-link record.
+
+```ts
+async function create(record: {
+  userId: number
+  selector: string
+  verifierHash: string
+  expirationDate: Iso.Instant
+  createdDate: Iso.Instant
+}): Promise<void> {
+  await Db.insert(
+    'INSERT INTO magicLinks (userId, selector, verifierHash, expirationDate, createdDate) VALUES (?, ?, ?, ?, ?)',
+    [record.userId, record.selector, record.verifierHash, instantFns.formatISO9075(record.expirationDate), instantFns.formatISO9075(record.createdDate)]
+  )
+}
+```
+
+### getBySelector
+
+Look up an unused magic-link record by its selector (the non-secret half of the token). Returns `null` if the token has already been used.
+
+```ts
+async function getBySelector(selector: string): Promise<MagicLinkRecord | null> {
+  const rows = await Db.select('SELECT * FROM magicLinks WHERE selector = ? AND usedDate IS NULL', [selector])
+  const row = rows[0]
+  if (!row) return null
+  return magicLinkRecordModel.parse(row)
+}
+```
+
+### getByUserId
+
+Look up the most recent magic-link record for a user (used for throttle checks).
+
+```ts
+async function getByUserId(userId: number): Promise<MagicLinkRecord | null> {
+  const rows = await Db.select('SELECT * FROM magicLinks WHERE userId = ? ORDER BY createdDate DESC LIMIT 1', [userId])
+  const row = rows[0]
+  if (!row) return null
+  return magicLinkRecordModel.parse(row)
+}
+```
+
+### markAsUsed
+
+Mark a magic-link record as used by setting its `usedDate`. The token can no longer be verified again, but the record is retained.
+
+```ts
+async function markAsUsed(selector: string): Promise<void> {
+  await Db.update('UPDATE magicLinks SET usedDate = ? WHERE selector = ?', [instantFns.formatISO9075(instantFns.now()), selector])
+}
+```
+
+### Export
+
+```ts
+export const magicLinkDbProvider = {
+  create,
+  getBySelector,
+  getByUserId,
+  markAsUsed
+}
+```
+
+## Use Case A1: Request Magic Link
+
+The user enters their email address. If a user with that email exists, a magic-link token is generated and emailed. The response is always the same (success) regardless of whether the email exists — this prevents email enumeration.
+
+### Flow
+
+1. Look up the user by email.
+2. If the user doesn't exist, return success (no email sent — prevents enumeration).
+3. **Throttle check**: call `magicLinkDbProvider.getByUserId(user.id)`. If a record exists and was created less than 60 seconds ago, throw a throttle error.
+4. **Generate token**: create a `selector` (16 random bytes, base64url) and `verifier` (32 random bytes, base64url) using `crypto.randomBytes()`.
+5. **Hash the verifier**: `await Hash.provider('bcrypt').hash(verifier)`.
+6. **Store the record**: call `magicLinkDbProvider.create()` with the userId, selector, verifierHash, expirationDate (now + 15 minutes), and createdDate (now). Previous tokens are not deleted — they expire naturally or are already marked as used.
+7. **Build the raw token**: `${selector}|${verifier}` — this is the `selector|verifier` format used by `@maestro-js/password`.
+8. **Send the email**: queue a magic-link email containing the login URL and the raw token.
+
+### Token Generation
+
+```ts
+import crypto from 'node:crypto'
+
+const selector = crypto.randomBytes(16).toString('base64url')
+const verifier = crypto.randomBytes(32).toString('base64url')
+const verifierHash = await Hash.provider('bcrypt').hash(verifier)
+
+const now = instantFns.now()
+const expirationDate = instantFns.add(now, { minutes: 15 })
+
+await magicLinkDbProvider.create({
+  userId: user.id,
+  selector,
+  verifierHash,
+  expirationDate,
+  createdDate: now
+})
+
+const token = `${selector}|${verifier}`
+```
+
+### Email Content
+
+Use the `email-templates` package pattern from chorus — a `magic-link-login` template that receives `{ loginUrl: string, token: string, expiresInMinutes: number }`. The email contains a clickable login URL and the raw token as a copyable string for cross-device use.
+
+```ts
+const html = await renderEmailTemplate('magic-link-login', {
+  loginUrl: `${APP_URL}/auth/verify?token=${encodeURIComponent(token)}`,
+  token,
+  expiresInMinutes: 15
+})
+
+Mail.queue({ to: user.email, subject: 'Your login link', content: { html } })
+```
+
+### Rate Limiting
+
+Throttle repeat requests per email to prevent abuse. If a magic-link record for the user was created less than 60 seconds ago, reject the request. This mirrors the `throttleSeconds` pattern in `@maestro-js/password`'s `passwordResetOptions`.
+
+```ts
+const existing = await magicLinkDbProvider.getByUserId(user.id)
+if (existing) {
+  const throttleExpiry = instantFns.add(existing.createdDate, { seconds: 60 })
+  if (instantFns.now() < throttleExpiry) {
+    throw new MagicLinkThrottledError()
+  }
+}
+```
+
+## Use Case A2: Verify Magic Link
+
+The user clicks the magic-link URL or pastes the raw token into the login form. The token is validated and the user is logged in.
+
+### Flow
+
+1. **Call `Auth.login()`** with the raw token as credentials. `verifyCredentials` handles decoding, lookup, hash verification, expiry check, and marking the token as used.
+2. **Return**: the `{ id, cookie }` result from `Auth.login()`.
+
+### Token Decode Helper
+
+```ts
+function decodeMagicLinkToken(token: string): { selector: string; verifier: string } | null {
+  const [selector, verifier] = token.split('|')
+  if (!selector || !verifier) return null
+  return { selector, verifier }
+}
+```
+
+### Login
+
+```ts
+const result = await Auth.login({ credentials: { token }, session, deviceContext })
+
+return result // { id, cookie } or { id: null, cookie: null }
+```
+
+## Security Considerations
+
+- **No email enumeration**: A1 always returns success regardless of whether the email exists in the database.
+- **Token format**: `selector|verifier` — the selector is stored in plaintext for lookup; the verifier is bcrypt-hashed. A database leak does not expose usable tokens.
+- **Bcrypt for verifier hash**: bcrypt is used (not sha256) because magic-link verifiers are high-entropy but short-lived secrets — bcrypt's cost factor adds defense-in-depth against brute force if the database is compromised.
+- **15-minute expiry**: tokens expire quickly to limit the window of vulnerability.
+- **Single-use tokens**: the token is marked as used (`usedDate` is set) before establishing the session. `getBySelector` filters out used tokens, so a token cannot be verified twice. The record is retained rather than hard-deleted.
+- **Rate limiting**: repeat requests for the same email are throttled to one per 60 seconds to prevent abuse and inbox flooding.
+- **HTTPS only**: the magic-link URL must be served over HTTPS. Session cookies are set with `Secure` and `HttpOnly` flags.

package/skills/maestro-examples/references/setlist/specs/position-ordering.md

@@ -0,0 +1,329 @@
+# Position Ordering
+
+How string-based position fields work and how to compute new positions when reordering items.
+
+## Overview
+
+Every orderable entity uses a `VARCHAR` column that sorts lexicographically. Rather than integer indices (which require shifting every sibling on insert), a string position slots between any two adjacent items by generating a key that compares between them. A reorder only writes **one row**.
+
+### Position columns
+
+| Entity  | Column              | Scope                                                   |
+| ------- | ------------------- | ------------------------------------------------------- |
+| Area    | `position`          | All areas for a user (sidebar)                          |
+| Project | `position`          | Sidebar ordering — shared position space with areas     |
+| Task    | `listPosition`      | Within its container (inbox, project, or area)          |
+| Task    | `scheduledPosition` | Within its scheduled date (Today view, Upcoming groups) |
+
+All of these columns follow the same algorithm. The examples below use `listPosition` on tasks, but the logic applies identically to every position column.
+
+## The Algorithm
+
+Based on [rocicorp/fractional-indexing](https://github.com/rocicorp/fractional-indexing) (CC0 / public domain). We vendor this as a local utility — no npm package needed.
+
+### Key structure
+
+A position key has two parts: an **integer part** and a **fractional part**.
+
+The integer part is a variable-length prefix whose first character (the "head") encodes its length:
+- `a`–`z`: lowercase heads have length `charCode - 'a' + 2` (so `a` = 2 chars, `b` = 3, ..., `z` = 28)
+- `A`–`Z`: uppercase heads have length `'Z' - charCode + 2` (so `Z` = 2, `Y` = 3, ..., `A` = 28)
+
+Uppercase integers sort before lowercase ones, giving a total order from smallest (`A` + 26 digits) to largest (`z` + 26 digits), with `a0` as the natural midpoint.
+
+The fractional part is everything after the integer prefix. It provides fine-grained ordering within an integer bucket. No trailing zeros are allowed.
+
+### Digit base
+
+Keys use base-62 digits: `0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz`. These are in ascending character code order, so standard string comparison (`localeCompare` or SQL `ORDER BY`) sorts them correctly.
+
+### `generateKeyBetween(a, b)`
+
+The main entry point. Takes two nullable position strings and returns a new string that sorts between them.
+
+```
+generateKeyBetween(a: string | null, b: string | null): string
+```
+
+- `a` — position of the item that should sort **before** the result (or `null` for start-of-list)
+- `b` — position of the item that should sort **after** the result (or `null` for end-of-list)
+
+**How it picks a key:**
+
+1. **Both null** → return `"a0"` (the default midpoint)
+2. **`a` is null** → find the integer part of `b` and decrement it. If `b` is already at its integer part (no fractional suffix), step to the previous integer
+3. **`b` is null** → find the integer part of `a` and increment it. If the integer overflows, extend the fractional part instead
+4. **Both non-null, same integer part** → compute a fractional midpoint between their fractional suffixes
+5. **Both non-null, different integer parts** → increment `a`'s integer. If the result is less than `b`, use it directly; otherwise extend `a`'s fractional part
+
+The `midpoint` helper finds a string that sorts between two fractional strings by walking their digits and picking the midpoint digit. When consecutive digits leave no room, it recurses deeper — this is what allows infinite subdivision without collisions.
+
+## Implementation
+
+```ts
+const BASE_62_DIGITS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+
+function midpoint(a: string, b: string | null, digits: string = BASE_62_DIGITS): string {
+  const zero = digits[0]
+  if (b != null && a >= b) throw new Error(a + ' >= ' + b)
+  if (a.slice(-1) === zero || (b && b.slice(-1) === zero)) throw new Error('trailing zero')
+
+  if (b) {
+    let n = 0
+    while ((a[n] || zero) === b[n]) n++
+    if (n > 0) return b.slice(0, n) + midpoint(a.slice(n), b.slice(n), digits)
+  }
+
+  const digitA = a ? digits.indexOf(a[0]) : 0
+  const digitB = b != null ? digits.indexOf(b[0]) : digits.length
+
+  if (digitB - digitA > 1) {
+    return digits[Math.round(0.5 * (digitA + digitB))]
+  }
+
+  if (b && b.length > 1) {
+    return b.slice(0, 1)
+  }
+
+  return digits[digitA] + midpoint(a.slice(1), null, digits)
+}
+
+function getIntegerLength(head: string): number {
+  if (head >= 'a' && head <= 'z') return head.charCodeAt(0) - 'a'.charCodeAt(0) + 2
+  if (head >= 'A' && head <= 'Z') return 'Z'.charCodeAt(0) - head.charCodeAt(0) + 2
+  throw new Error('invalid order key head: ' + head)
+}
+
+function getIntegerPart(key: string): string {
+  const len = getIntegerLength(key[0])
+  if (len > key.length) throw new Error('invalid order key: ' + key)
+  return key.slice(0, len)
+}
+
+function validateInteger(int: string): void {
+  if (int.length !== getIntegerLength(int[0])) throw new Error('invalid integer part of order key: ' + int)
+}
+
+function validateOrderKey(key: string, digits: string = BASE_62_DIGITS): void {
+  if (key === 'A' + digits[0].repeat(26)) throw new Error('invalid order key: ' + key)
+  const i = getIntegerPart(key)
+  const f = key.slice(i.length)
+  if (f.slice(-1) === digits[0]) throw new Error('invalid order key: ' + key)
+}
+
+function incrementInteger(x: string, digits: string = BASE_62_DIGITS): string | null {
+  validateInteger(x)
+  const [head, ...digs] = x.split('')
+  let carry = true
+  for (let i = digs.length - 1; carry && i >= 0; i--) {
+    const d = digits.indexOf(digs[i]) + 1
+    if (d === digits.length) {
+      digs[i] = digits[0]
+    } else {
+      digs[i] = digits[d]
+      carry = false
+    }
+  }
+  if (carry) {
+    if (head === 'Z') return 'a' + digits[0]
+    if (head === 'z') return null
+    const h = String.fromCharCode(head.charCodeAt(0) + 1)
+    if (h > 'a') digs.push(digits[0])
+    else digs.pop()
+    return h + digs.join('')
+  }
+  return head + digs.join('')
+}
+
+function decrementInteger(x: string, digits: string = BASE_62_DIGITS): string | null {
+  validateInteger(x)
+  const [head, ...digs] = x.split('')
+  let borrow = true
+  for (let i = digs.length - 1; borrow && i >= 0; i--) {
+    const d = digits.indexOf(digs[i]) - 1
+    if (d === -1) {
+      digs[i] = digits.slice(-1)
+    } else {
+      digs[i] = digits[d]
+      borrow = false
+    }
+  }
+  if (borrow) {
+    if (head === 'a') return 'Z' + digits.slice(-1)
+    if (head === 'A') return null
+    const h = String.fromCharCode(head.charCodeAt(0) - 1)
+    if (h < 'Z') digs.push(digits.slice(-1))
+    else digs.pop()
+    return h + digs.join('')
+  }
+  return head + digs.join('')
+}
+
+export function generateKeyBetween(a: string | null, b: string | null): string {
+  const digits = BASE_62_DIGITS
+  if (a != null) validateOrderKey(a, digits)
+  if (b != null) validateOrderKey(b, digits)
+  if (a != null && b != null && a >= b) throw new Error(a + ' >= ' + b)
+
+  if (a == null) {
+    if (b == null) return 'a' + digits[0]
+    const ib = getIntegerPart(b)
+    const fb = b.slice(ib.length)
+    if (ib === 'A' + digits[0].repeat(26)) return ib + midpoint('', fb, digits)
+    if (ib < b) return ib
+    const res = decrementInteger(ib, digits)
+    if (res == null) throw new Error('cannot decrement any more')
+    return res
+  }
+
+  if (b == null) {
+    const ia = getIntegerPart(a)
+    const fa = a.slice(ia.length)
+    const i = incrementInteger(ia, digits)
+    return i == null ? ia + midpoint(fa, null, digits) : i
+  }
+
+  const ia = getIntegerPart(a)
+  const fa = a.slice(ia.length)
+  const ib = getIntegerPart(b)
+  const fb = b.slice(ib.length)
+  if (ia === ib) return ia + midpoint(fa, fb, digits)
+  const i = incrementInteger(ia, digits)
+  if (i == null) throw new Error('cannot increment any more')
+  if (i < b) return i
+  return ia + midpoint(fa, null, digits)
+}
+```
+
+## Cases
+
+There are four cases when computing a position. In every case, `previousItem` is the item directly before the target drop position and `nextItem` is the item directly after.
+
+### 1. Insert between two items
+
+The most common reorder — dragging an item between two existing neighbors.
+
+```ts
+// Items: [A:"a0", B:"a1", C:"a2"]
+// Drop task between A and B
+const position = generateKeyBetween('a0', 'a1') // → "a0V"
+// Result: [A:"a0", NEW:"a0V", B:"a1", C:"a2"]
+```
+
+### 2. Insert at the start
+
+Dragging an item to the top of a list. `previousItem` is `null`, `nextItem` is the current first item.
+
+```ts
+// Items: [A:"a0", B:"a1", C:"a2"]
+// Drop task before A (beginning of list)
+const position = generateKeyBetween(null, 'a0') // → "Zz"
+// Result: [NEW:"Zz", A:"a0", B:"a1", C:"a2"]
+```
+
+### 3. Insert at the end
+
+Dragging an item to the bottom, or appending a newly created item. `previousItem` is the current last item, `nextItem` is `null`.
+
+```ts
+// Items: [A:"a0", B:"a1", C:"a2"]
+// Drop task after C (end of list)
+const position = generateKeyBetween('a2', null) // → "a3"
+// Result: [A:"a0", B:"a1", C:"a2", NEW:"a3"]
+```
+
+### 4. Insert into an empty list
+
+Creating the first item in a container, or moving an item into an empty project/area. Both `previousItem` and `nextItem` are `null`.
+
+```ts
+// Items: []
+// First task in an empty project
+const position = generateKeyBetween(null, null) // → "a0"
+// Result: [NEW:"a0"]
+```
+
+## Deriving previousItem and nextItem from a drag event
+
+The frontend's `onDragEnd` handler receives the `active` item (being dragged) and the `over` item (the drop target). Translate these into `previousItem` / `nextItem` by finding the insertion index in the **filtered** list (excluding the dragged item):
+
+```ts
+function onDragEnd(active, over, items) {
+  // Remove the dragged item from the list to get the remaining order
+  const filtered = items.filter(item => item.id !== active.id)
+  const overIndex = filtered.findIndex(item => item.id === over.id)
+
+  // Determine drop direction: did the item move up or down?
+  const oldIndex = items.findIndex(item => item.id === active.id)
+  const rawOverIndex = items.findIndex(item => item.id === over.id)
+  const insertAfter = rawOverIndex > oldIndex
+
+  let previousItem: Item | null
+  let nextItem: Item | null
+
+  if (insertAfter) {
+    // Dropped below the "over" item
+    previousItem = filtered[overIndex] ?? null
+    nextItem = filtered[overIndex + 1] ?? null
+  } else {
+    // Dropped above the "over" item
+    previousItem = filtered[overIndex - 1] ?? null
+    nextItem = filtered[overIndex] ?? null
+  }
+
+  const position = generateKeyBetween(
+    previousItem?.listPosition ?? null,
+    nextItem?.listPosition ?? null
+  )
+
+  // Optimistic update + API call
+  reorderTask(active.id, { listPosition: position })
+}
+```
+
+## New item creation
+
+When creating a new task, project, or area, append it to the end of its target list:
+
+```ts
+// Fetch the last item in the container
+const lastTask = tasks.at(-1)
+const listPosition = generateKeyBetween(lastTask?.listPosition ?? null, null)
+```
+
+To prepend to the beginning instead (e.g. Inbox where new items appear at top):
+
+```ts
+const firstTask = tasks.at(0)
+const listPosition = generateKeyBetween(null, firstTask?.listPosition ?? null)
+```
+
+## Cross-container moves
+
+When a task moves between containers (e.g. from inbox to a project), the `listPosition` must be recomputed relative to the **destination** list, not the source. The task's old `listPosition` is irrelevant once the container changes.
+
+```ts
+// Task dragged from Inbox onto Project #5
+// Get the tasks already in Project #5, ordered by listPosition
+const projectTasks = tasks
+  .filter(t => t.projectId === 5)
+  .sort((a, b) => a.listPosition.localeCompare(b.listPosition))
+
+// Append to end of the project's task list
+const lastTask = projectTasks.at(-1)
+const listPosition = generateKeyBetween(lastTask?.listPosition ?? null, null)
+
+reorderTask(task.id, { listPosition, projectId: 5, areaId: null })
+```
+
+## Querying in order
+
+Position columns sort correctly with a plain `ORDER BY` since they are lexicographic strings:
+
+```sql
+SELECT * FROM tasks
+WHERE userId = ? AND projectId = ? AND completedDate IS NULL AND deletedDate IS NULL
+ORDER BY listPosition
+```
+
+No casting or special collation is needed.

package/skills/maestro-examples/references/setlist/specs/sidebar.md

@@ -0,0 +1,65 @@
+# Sidebar
+
+The sidebar is the primary navigation surface. It has two sections: a fixed set of built-in views at the top, and a user-managed list of areas and projects below.
+
+## Built-in Views
+
+Four fixed links at the top of the sidebar, in this order:
+
+1. **Inbox** — tasks not assigned to a project, area, or scheduled date (V1)
+2. **Today** — tasks scheduled for today + overdue tasks (V2)
+3. **Upcoming** — tasks grouped by scheduled date, looking forward (V3)
+4. **Completed** — all completed tasks and projects, reverse chronological (V4)
+
+These are not reorderable or removable.
+
+## User Content
+
+Below the built-in views, a single mixed list of **areas** and **top-level projects** (projects with no `areaId`), sorted by their shared `position` column. Areas and top-level projects interleave freely based on position value.
+
+### Area Rendering
+
+- An area row shows its title
+- Areas are expandable/collapsible — expanding an area reveals its child projects nested underneath
+- Collapsed state persists across sessions
+- An area's child projects are sorted by `position` within the area
+
+### Project Rendering
+
+- A project row shows its title
+- Projects with an `areaId` appear nested under their parent area (visible only when the area is expanded)
+- Projects with no `areaId` appear at the top level alongside areas
+- Completed projects are excluded from the sidebar entirely — they move to the Completed view (V4)
+- Deleted projects and areas are excluded
+
+## Active State
+
+The currently active view, project, or area is visually highlighted in the sidebar. Only one item is active at a time. Clicking a sidebar item navigates to it and updates the highlight.
+
+## Interactions
+
+### Navigation
+
+- Click a built-in view link to navigate to that view
+- Click an area to navigate to its detail view (standalone tasks + projects)
+- Click a project to navigate to its task list (PR1)
+
+### Drag-and-Drop
+
+All drag-and-drop behavior references the shared position space described in [position-ordering.md](position-ordering.md) and the implementation in [drag-and-drop.md](drag-and-drop.md).
+
+- **Reorder areas** in the sidebar (AR5) — drag an area to a new position among other top-level items
+- **Reorder top-level projects** in the sidebar (PR8) — drag a project to a new position among other top-level items
+- **Move a project into an area** (PR4) — drag a project onto an area to nest it; updates `projects.areaId` and `projects.position`
+- **Move a project out of an area** (PR4) — drag a nested project out to the top level; sets `areaId` to null and updates position
+- **Move a task to a project or area** (T4) — drag a task from any list view onto a sidebar project or area to reassign it
+
+### Create
+
+- Inline creation for new areas (AR2) and new projects (PR2) from the sidebar
+- New items are appended to the end of the list by default
+
+### Context Menu
+
+- Right-click an area for options: edit title (AR3), delete (AR4)
+- Right-click a project for options: edit (PR3), complete (PR5), delete (PR7)