@pikku/skills 0.12.25 → 0.12.27

package/skills/pikku-list-query/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: pikku-list-query
+description: >-
+  Use when building a paginated/infinite-scroll list — any RPC that returns rows a user scrolls through (tables, card grids, search results). Covers pikkuListFunc, the ListInput/ListOutput cursor contract, and the generated usePikkuInfiniteQuery hook.
+  TRIGGER when: user asks for infinite scroll, "load more", a paginated table/list/grid, or a list that could grow beyond a single page.
+  DO NOT TRIGGER when: the list is small and fixed (e.g. a settings page with 5 items) — a plain pikkuFunc + usePikkuQuery returning a full array is simpler and correct there.
+installGroups: [core, client]
+---
+
+# Pikku List Queries
+
+## Agent Operating Procedure
+
+1. Capture baseline. Run `pikku all` BEFORE writing code; only NEW errors are yours to fix.
+2. Write the backend function with `pikkuListFunc` (below) — never a bespoke `{items: [...]}` shape once the list can page.
+3. Run `pikku all` to regenerate `usePikkuInfiniteQuery` for the new function.
+4. Wire the frontend with `usePikkuInfiniteQuery`, not a hand-rolled `useState` page counter and not a raw `useInfiniteQuery` — the generated hook already resolves cursor plumbing from your function's types.
+5. Validate with `pikku all`.
+
+## The `pikkuListFunc` contract
+
+A list function is a normal `pikkuFunc`/`pikkuSessionlessFunc` whose input/output conform to two shared shapes from `@pikku/core`:
+
+```typescript
+interface ListInput<F extends Record<string, unknown> = {}, S extends string = never> {
+  cursor?: string // opaque — echo back whatever you returned as nextCursor
+  limit?: number // page size; server may cap it
+  sort?: Array<{ column: S; direction: 'asc' | 'desc' }>
+  filter?: Filter<F> // structured AND/OR tree, Prisma-style leaf operators
+  search?: string // free-text search across server-chosen fields
+}
+
+interface ListOutput<Row> {
+  rows: Row[]
+  nextCursor: string | null // null = no more pages
+  totalCount?: number // optional — skip when expensive to compute
+}
+```
+
+Adopting this shape is what makes the function eligible for the generated `usePikkuInfiniteQuery` hook — the react-query codegen structurally detects any RPC whose output includes `nextCursor` and generates an infinite-query hook for it automatically. No manual wiring, no opt-in flag.
+
+```typescript
+import { pikkuListFunc } from '#pikku/function'
+
+interface Item {
+  id: string
+  label: string
+}
+
+export const listItems = pikkuListFunc<{ status?: string }, Item>({
+  expose: true,
+  auth: true,
+  readonly: true,
+  description: 'List items for the signed-in user, paginated.',
+  // `input` is inferred as ListInput<{ status?: string }> from the generics above —
+  // never re-annotate it inline.
+  func: async ({ kysely }, input, { session }) => {
+    // `limit` is caller-supplied on an exposed RPC, so it is CAPPED, not trusted —
+    // `ListInput` says "server may cap" and this is where that happens.
+    const limit = Math.min(Math.max(Math.trunc(input.limit ?? 20) || 20, 1), 100)
+    const parsed = input.cursor ? Number(input.cursor) : 0
+    const offset = Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : 0
+
+    let query = kysely.selectFrom('item').where('userId', '=', session!.userId)
+    const status = leafEquals(input.filter, 'status')
+    if (status !== undefined) {
+      query = query.where('status', '=', status)
+    }
+
+    const rows = await query.orderBy('createdAt', 'desc').offset(offset).limit(limit).execute()
+    const nextOffset = offset + rows.length
+    const totalCount = await query
+      .select((eb) => eb.fn.countAll<number>().as('count'))
+      .executeTakeFirstOrThrow()
+
+    return {
+      rows: rows.map((r) => ({ id: r.id, label: r.label })),
+      nextCursor: nextOffset < totalCount.count ? String(nextOffset) : null,
+      totalCount: totalCount.count,
+    }
+  },
+})
+```
+
+Cursor doesn't have to be a numeric offset — any opaque string works (a keyset value, an encoded timestamp, etc.), as long as you can turn it back into a query position on the next call.
+
+## Frontend: `usePikkuInfiniteQuery`
+
+Generated automatically alongside `usePikkuQuery`/`usePikkuMutation` once `reactQueryFile` is configured (see the react-query wiring docs) — no separate setup for list functions specifically.
+
+```tsx
+import { usePikkuInfiniteQuery } from '.pikku/pikku-react-query.gen'
+
+function ItemList() {
+  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = usePikkuInfiniteQuery(
+    'listItems',
+    { limit: 20 }, // never pass cursor here — the hook manages it
+  )
+
+  const rows = data?.pages.flatMap((page) => page.rows) ?? []
+
+  return (
+    <>
+      {rows.map((row) => (
+        <div key={row.id}>{row.label}</div>
+      ))}
+      {hasNextPage && (
+        <button disabled={isFetchingNextPage} onClick={() => fetchNextPage()}>
+          Load more
+        </button>
+      )}
+    </>
+  )
+}
+```
+
+For scroll-triggered loading (rather than a button), pair it with an `IntersectionObserver` sentinel at the end of the list that calls `fetchNextPage()` when it enters the viewport and `hasNextPage` is true — don't poll on a scroll event handler.
+
+## Common mistakes
+
+- **Bespoke output shape** (`{items, total}` with no `nextCursor`) — compiles, but disqualifies the function from `usePikkuInfiniteQuery`; you're left hand-rolling pagination state. Use `ListOutput<Row>`'s field names (`rows`, `nextCursor`) even if you don't need `filter`/`sort`/`search` yet — they're optional.
+- **Fixed large `limit` instead of real pagination** (e.g. `{ limit: 500 }` fetched once) — works until the collection outgrows the cap, then silently truncates. If a list can grow unbounded, page it from the start.
+- **Passing `cursor` manually into `usePikkuInfiniteQuery`'s input argument** — the hook injects it into each page request itself; the input you pass is the _base_ filter/limit shared by every page.
+
+## `filter` is a TREE, not a bag of fields
+
+`Filter<F>` is recursive: an **array** is an AND of its children, a **multi-key object** is
+an OR keyed by labels that mean nothing at evaluation time, and only a **single-key object**
+is a leaf. A leaf's value is either the value itself or an operator object
+(`{ contains, in, gt, gte, lt, lte, not, startsWith, … }`).
+
+So `'status' in input.filter` answers `false` for `[{ status: 'open' }, { userId: 'u1' }]`
+and for `{ status: { in: ['open', 'held'] } }` — the first because the filter is an array,
+the second because the value is an operator object rather than the string the code then
+compares. Both cases **silently return unfiltered rows**, which on a list endpoint means
+handing back records the caller asked to exclude. Pikku ships no filter-to-SQL helper: the
+backend decides what it accepts, and it has to say so.
+
+Read exactly the shape you support, and refuse the rest rather than ignoring it:
+
+```typescript
+import type { Filter } from '@pikku/core/function'
+
+/** The one shape this endpoint accepts: a single-key leaf with a plain value. */
+function leafEquals<F extends Record<string, unknown>, K extends keyof F & string>(
+  filter: Filter<F> | undefined,
+  field: K,
+): F[K] | undefined {
+  if (!filter || Array.isArray(filter)) return undefined
+  const keys = Object.keys(filter)
+  if (keys.length !== 1 || keys[0] !== field) return undefined
+  const value = (filter as Record<string, unknown>)[field]
+  if (value !== null && typeof value === 'object') {
+    throw new Error(`filter.${field} takes a value, not an operator object`)
+  }
+  return value as F[K]
+}
+```
+
+Supporting AND/OR or operators means walking the tree properly — recurse into the array and
+the multi-key object, and map each leaf operator to its Kysely equivalent. Do that when the
+UI needs it; until then, throwing on the shapes you do not handle is what stops a filter
+from being quietly dropped.

package/skills/pikku-permissions/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: pikku-permissions
+description: >-
+  Use when deciding WHO may call a function — resource ownership, role gates, admin-only actions, or any "only their own rows" rule. Covers the `permissions` field, `pikkuPermission`, `pikkuAuth`, scopes, and where ownership belongs versus where it does not.
+  TRIGGER when: writing or reviewing any function that touches a row a user owns, gating an action on a role, building the permissions half of a contract in build PHASE 2, or about to write an `if` in a function body that decides whether the caller is allowed.
+  DO NOT TRIGGER when: the question is how to sign someone in or seed a persona (that is pikku-auth), or how to shape a paginated list (that is pikku-list-query).
+installGroups: [core]
+---
+
+# Pikku Permissions
+
+## The rule
+
+**Authorization goes in the `permissions` field. Never in the `func` body.**
+
+`permissions` runs before `func`, and it is DECLARED — `pikku meta` and the auditor can
+see it. An `if` in the body is the same check, invisible: nothing can tell you which
+functions are gated or how, and the next person to add a caller gets no warning.
+
+```typescript
+// RIGHT
+export const deleteBook = pikkuFunc({
+  permissions: { owner: isBookOwner },
+  func: async ({ kysely }, { bookId }) => {
+    await kysely.deleteFrom('book').where('bookId', '=', bookId).execute()
+  },
+})
+
+// WRONG — the gate is buried in the body
+export const deleteBook = pikkuFunc({
+  func: async ({ kysely }, { bookId }, { session }) => {
+    const book = await kysely.selectFrom('book')...executeTakeFirst()
+    if (book?.ownerId !== session.userId) throw new UnauthorizedError()
+    await kysely.deleteFrom('book').where('bookId', '=', bookId).execute()
+  },
+})
+```
+
+## `auth: true` IS NOT OWNERSHIP — this is the one people get wrong
+
+`auth: true` means "somebody is signed in". It does NOT mean "this row is theirs". A CRUD
+function set to `auth: true` and nothing else lets ANY signed-in user delete ANY other
+user's row by passing its id. Every function that takes a row id needs BOTH: `auth: true`
+for the session, and a `permissions` entry for the ownership.
+
+Equally: do NOT write an `isSignedIn` permission that returns `!!session`. That re-checks
+authentication, which `auth: true` already did. A permission answers *may this user do
+this* — role, ownership, tier — never *is there a session*.
+
+## Single row vs list — where ownership actually goes
+
+This is the distinction to get right, and both halves are correct code:
+
+- **A function taking a row id** (`get`, `update`, `delete`) — ownership is a
+  PERMISSION. Load the row, compare the owner to the session. It is a yes/no question
+  about one row, which is exactly what a permission is.
+- **A function returning many rows** (`list`, `search`, any stats query) — ownership is
+  a `WHERE` clause in the query, because "only their rows" is a filter, not a yes/no.
+  There is no permission to write here; scoping the query IS the enforcement.
+
+A list that fetches everything and then filters in JS is a bug, not a permission.
+
+## Writing the checkers
+
+Put them in `src/permissions/`, one file per entity, and reuse one checker across every function on that
+entity rather than writing a near-copy per function.
+
+```typescript
+// src/permissions/book.ts
+import { pikkuPermission, pikkuAuth } from '#pikku/auth'
+
+// Data-aware: gets the input, so it can load the row the caller named.
+export const isBookOwner = pikkuPermission(
+  async ({ kysely }, { bookId }, { session }) => {
+    const book = await kysely
+      .selectFrom('book')
+      .select('ownerId')
+      .where('bookId', '=', bookId)
+      .executeTakeFirst()
+    return book?.ownerId === session?.userId
+  },
+)
+
+// Session-only: no input needed. Use for role and flag gates.
+export const isAdmin = pikkuAuth(async (_services, session) => session?.role === 'admin')
+```
+
+## OR and AND
+
+```typescript
+permissions: {
+  owner: isBookOwner,            // OR — an owner may
+  admin: isAdmin,                // OR — an admin may
+  editor: [isAdmin, isBookOwner] // AND — both, inside one group
+}
+```
+
+Groups are OR'd; entries inside a group array are AND'd.
+
+## Roles
+
+If the app has roles, the role lives on the session (see pikku-auth / `mapSession`) and
+every mutating or admin-only function names it in `permissions`. Gate the FUNCTION — hiding
+an admin button in the UI is UX, never enforcement, and a member who guesses the RPC name
+gets straight through if the function itself is open.
+
+## Scopes
+
+`scopes: ['admin:invoices:void']` is an AND gate checked BEFORE permissions and before
+input validation. Declare the tree once with `defineScope`; a function naming an
+undeclared scope fails codegen rather than gating on nothing. A grant satisfies a scope if
+it is that scope, an ancestor, or a wildcard — a session holding `admin` satisfies
+`admin:invoices:void`. Most apps need roles, not scopes; reach for these only when the
+plan asked for granular grants.
+
+## The one sanctioned exception
+
+`permissionsInBody: true` — for a check that genuinely cannot be a permission because the
+identity arrives in the payload and there is no session: a webhook signature, a signed
+token, an invite code. It is purely declarative and enforces nothing; its job is to tell
+the auditor the openness is deliberate. Anything expressible as a permission must be one.
+
+## After changes
+
+`pikku all` — regenerates and typechecks the checkers. A permission whose signature is
+wrong fails here, not at runtime.

package/skills/pikku-react/references/client.md

@@ -195,6 +195,26 @@ const pikku = createPikku(PikkuFetch, PikkuRPC, {
 })
 ```
 
+`transformDate: true` revives **fully-zoned ISO-8601 instants** — `2026-03-14T08:12:00Z`,
+`2026-03-14T08:12:00.000+01:00` — into `Date` objects. Nothing else is touched: a bare
+`2026-03-14`, a zoneless `2026-03-14T08:12:00`, and a shaped-but-impossible
+`2026-02-31T00:00:00Z` all stay the strings the server sent, because each names a reading
+rather than a moment and `new Date` would guess a different instant per machine.
+
+So the field's runtime type follows the VALUE, not the schema — one `z.string()` column can
+arrive as a `Date` from one row and a string from the next. Two consequences, both of which
+typecheck:
+
+- **A string method on a revived field throws at runtime.** `row.createdAt.split('T')[0]` —
+  there is no string to slice.
+- **A raw `Date` in JSX crashes the route.** `<span>{row.createdAt}</span>` throws
+  `Objects are not valid as a React child (found: [object Date])` and the page falls into its
+  error boundary — a white screen, with nothing catching it first.
+
+Format before rendering, with whatever date library the project already uses, and let it take
+either type. Coercing instead (`` `${d}` ``, `String(d)`) does not crash but prints
+`Mon Jun 15 2026 02:00:00 GMT+0200`, which is a different bug.
+
 There is no request-interceptor hook. For a token that changes after startup,
 call the setter on the shared instance — RPC and realtime pick it up because
 they hold the same fetch:

package/skills/pikku-realtime/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: pikku-realtime
+description: >-
+  Use when making ANY view live/realtime in a Pikku app — a board, shared list, dashboard, ticker, bidding room, live count — or when adding two-way chat/presence. Covers the DEFAULT event-hub SSE path and the two-way WebSocket channel.
+  TRIGGER when: the user wants live updates, realtime, "update without refresh", a live board/feed/ticker/room, presence, or chat; or when data that MORE THAN ONE signed-in user can change should reflect others
+  DO NOT TRIGGER when: a plain one-shot query/refetch is fine (data only one user changes, or a manual refresh is acceptable), or for background jobs (that is pikku-schedule/pikku-workflow).
+installGroups: [core, client]
+---
+
+# Pikku Realtime (SSE + WebSocket channels)
+
+There is NOTHING to hand-roll and NOTHING to "find". The event-hub SSE transport
+is already wired into every app, and the two patterns below ARE the realtime
+templates. Start from them and rename — never grep the project for existing
+`sse`/`eventHub` code to copy, never write a custom `EventSource`, and never
+write a bespoke `sse: true` route for a plain live feed.
+
+## Pick the transport (almost always SSE)
+
+- **Server → client live updates → SSE via the event-hub.** This is the DEFAULT
+  for making any view live: a board, list, dashboard, ticker, feed, or a "room"
+  (a bidding room, sale room, live auction). The client only RECEIVES — the
+  change itself happens through a NORMAL HTTP RPC (`placeBid`, `updateLot`, …)
+  that publishes the new row.
+- **Client → server push mid-session → a WebSocket channel.** ONLY when the
+  BROWSER must send up the socket without a page action: live chat messages,
+  typing indicators, cursors/presence.
+
+A screen being called a "room", or being multi-user, or being live is NOT a
+reason to use a channel. If the browser isn't pushing frames up, it's SSE.
+
+## Level 1 — live updates (event-hub SSE, the default)
+
+Two halves; both are required or nothing arrives.
+
+**Backend — publish after every write.** In each create/update/status function,
+AFTER the DB write, publish the changed row on a topic:
+
+```ts
+const lot = await kysely
+  .updateTable('lot')
+  .set({ status: 'sold' })
+  .where('id', '=', input.lotId)
+  .returning(['id', 'status', 'currentBid', 'updatedAt'])
+  .executeTakeFirstOrThrow()
+await eventHub.publish('lot-updated', null, { topic: 'lot-updated', data: lot })
+return lot
+```
+
+**A topic is PUBLIC — publish a projection, never `returningAll()`.** The generated
+`/events/:topic` route is wired `auth: false` with a sessionless handler, so anyone who can
+reach the origin can subscribe to any topic name and read every frame on it. `returningAll()`
+then ships the whole row — `reservePrice`, `sellerId`, internal notes, whatever the table
+grows next — to unauthenticated subscribers, and it does it silently because the RPC's own
+`output` schema never sees the event payload. List the columns the topic is FOR, the way the
+example does. If a change genuinely has per-viewer content, it does not belong on a topic:
+publish an id-only "something changed" frame and let each client refetch through an
+authenticated RPC that applies its own permissions.
+
+The **2nd arg is the channel to EXCLUDE** from the broadcast: pass `null` from a
+normal HTTP/RPC write (there is no one to skip); pass `channel.channelId` ONLY
+when you publish from INSIDE a channel handler, or the sender gets an echo of its
+own update. `eventHub` is already injected — do not wire it.
+
+**Frontend — subscribe over SSE.** The generated
+`PikkuRealtime.subscribeToTopic(topic, handler)` opens an SSE stream to the
+built-in `/events/:topic` route. Seed state from a normal query, then patch it as
+events arrive; the event is the `{ topic, data }` envelope, so read `.data`.
+
+```tsx
+import { useEffect } from 'react'
+import { useQueryClient } from '@tanstack/react-query'
+import { realtime } from '../lib/pikku'
+
+export function useLiveLots() {
+  const queryClient = useQueryClient()
+
+  useEffect(() => {
+    const subscription = realtime.subscribeToTopic('lot-updated', () => {
+      queryClient.invalidateQueries({ queryKey: ['listLots'] })
+    })
+    return () => subscription.close()
+  }, [queryClient])
+}
+```
+
+**Invalidate; do not hand-patch the cache.** The generated hooks key a query as
+`[name, input]` — `['listLots', { status: 'open', cursor: undefined }]`, one entry per set of
+arguments — so `setQueryData(['listLots'], …)` writes to a key nothing reads and the screen
+never changes. `invalidateQueries({ queryKey: ['listLots'] })` prefix-matches, so it refreshes
+every variant of that list whatever input each one was fetched with.
+
+Patching also has to know the payload's shape, and a list RPC returns
+`ListOutput<Lot>` — `{ rows, nextCursor, totalCount? }`, not `Lot[]` — so a `rows.map(...)`
+updater is reading `.map` off an object. Refetching sidesteps both, and it re-applies the server's own filtering,
+which a locally patched row does not: a lot that just moved to `sold` may no longer belong in
+an "open lots" list at all.
+
+`subscribeToTopic` returns `{ close }` — ALWAYS close on unmount or you leak the
+stream. Never hand-roll an `EventSource`.
+
+## Level 2 — two-way channel
+
+Only when the client pushes up the socket. The backend channel lives in its own
+`*.channel.ts` with `onConnect`/`onMessage` handlers:
+
+```ts
+import { pikkuChannelFunc, wireChannel } from '#pikku/channel'
+
+export const onMessage = pikkuChannelFunc<{ text: string }>({
+  func: async ({ eventHub }, input, { channel, session }) => {
+    const message = { id: crypto.randomUUID(), text: input.text, userId: session!.userId }
+    await eventHub.publish('room', channel.channelId, { topic: 'room', data: message })
+    return message
+  },
+})
+
+wireChannel({ name: 'room', route: '/room', auth: true, onMessage })
+```
+
+The frontend opens it with `PikkuRealtime.connectToChannel(path)`, which returns
+a socket you both `.send(...)` on and read via `onmessage`:
+
+```tsx
+useEffect(() => {
+  const socket = realtime.connectToChannel('/room')
+  socket.onmessage = (event) => appendMessage(JSON.parse(event.data))
+  return () => socket.close()
+}, [])
+```
+
+Publish server→client fan-out from a channel handler with
+`eventHub.publish(topic, channel.channelId, envelope)` — the 2nd arg excludes the
+sender, so the browser that sent the message does not receive its own echo.
+
+## Do NOT
+
+- Do **not** grep the project for existing SSE/eventHub infra to reverse-engineer
+  or copy — the patterns above ARE the template (same rule as never reading
+  `.gen.ts` to learn an API).
+- Do **not** write a custom `sse: true` HTTP route or a bespoke `EventSource` for
+  an ordinary live feed — the event-hub covers it. (A dedicated `sse: true` route
+  is only for a long-job PROGRESS stream, and is not needed for an initial build.)
+- Do **not** use a WebSocket channel for a live board/ticker/room — that is SSE.
+  A channel is for client→server push (chat/presence) ONLY.
+- Do **not** forget the backend `eventHub.publish(...)` — a subscribed frontend
+  with no publisher is a silent, empty stream.

package/skills/pikku-seo/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: pikku-seo
+description: >-
+  On-page SEO rules for the app's PUBLIC pages: per-route head() titles and meta descriptions, Open Graph tags, one-h1 heading hierarchy, semantic/crawlable markup, JSON-LD on the landing page, and noindex for the logged-in area.
+  TRIGGER when: building or reworking any public page (landing, pricing, about, blog/content pages), writing page titles or meta tags, or the user asks about SEO / Google / discoverability / social sharing previews.
+  DO NOT TRIGGER when: working on logged-in /app screens (they are noindexed — only the one robots rule below applies), backend functions, database, or deployment.
+installGroups: [client]
+---
+
+# SEO Rules
+
+Apps render SSR from the edge, so crawlers see full HTML — the ranking work is
+getting the on-page signals right while you build. These rules apply to PUBLIC
+routes only (the landing page and any marketing/content pages). The logged-in
+`/app` area is private: it gets `noindex` and nothing else from this skill.
+
+## Per-route head() — every public route, no exceptions
+
+Titles and descriptions live in TanStack Start's `head()` on the route, merged
+root → leaf (the leaf's title/meta win). The root route already carries the
+site-wide defaults and OG tags; every public page you add MUST override both:
+
+```tsx
+export const Route = createFileRoute('/pricing')({
+  head: () => ({
+    meta: [
+      { title: 'Pricing — Acme Scheduling' },
+      {
+        name: 'description',
+        content:
+          'Simple per-seat pricing for Acme Scheduling. Start free, upgrade when your team grows — no setup fees, cancel anytime.',
+      },
+      { property: 'og:title', content: 'Pricing — Acme Scheduling' },
+      { property: 'og:description', content: 'Simple per-seat pricing. Start free.' },
+    ],
+  }),
+  component: PricingPage,
+})
+```
+
+`head()` strings are plain strings (they do not go through the Mantine i18n
+gate) — write real copy for THIS app, in the app's voice.
+
+- **Title**: unique per page, 50–60 characters, the page's primary topic first,
+  brand at the end (`Topic — AppName`). The template's `__APP_TITLE__` default
+  must never survive the rebrand, on any page.
+- **Description**: unique per page, 150–160 characters, states the concrete
+  value of the page in plain language — a reason to click, not a keyword list.
+- **Dynamic public pages** (e.g. a public detail page) build both from loader
+  data: `head: ({ loaderData }) => ({ meta: [{ title: `${loaderData.name} — AppName` }, ...] })`.
+- **Never invent URLs**: the deployed domain is unknown at build time, so do
+  NOT emit `canonical`, `og:url`, or `og:image` pointing at a made-up domain —
+  omit them (same principle as the `/api` serverUrl rule). `og:image` only if a
+  real asset exists in the app.
+
+## Logged-in area = noindex
+
+The `/app` route (the authenticated layout route) gets exactly one meta entry:
+
+```tsx
+head: () => ({ meta: [{ name: 'robots', content: 'noindex' }] })
+```
+
+Never noindex a public page, and never put per-page SEO effort into `/app`
+screens — they are invisible to crawlers by design.
+
+## Headings — exactly one h1 per page
+
+- Every page has EXACTLY ONE h1 (`<Title order={1}>` in Mantine, `<h1>` in
+  Tailwind) and it names the page's primary topic — aligned with the title tag,
+  not identical boilerplate.
+- Logical hierarchy below it: h1 → h2 → h3, no skipped levels, headings
+  describe the content under them. Never pick a heading level for its font
+  size — set the size on the correct level (`<Title order={2} fz="xs">`).
+
+## Crawlable, semantic markup
+
+- Landmarks on public pages: `<nav>`, `<main>`, `<footer>` (Mantine: `component="nav"` etc.).
+- Navigation between public pages uses real links (`<Link>`/`<a href>`) with
+  descriptive anchor text — crawlers follow hrefs; a `div onClick` navigation
+  is invisible to them. No public page may be orphaned: every public page is
+  reachable by link from the landing page (directly or via nav/footer).
+- Every meaningful `<img>` has alt text describing the image; decorative images
+  get `alt=""`. Prefer descriptive file names for real assets.
+- Readable URLs: public routes are lowercase, hyphen-separated, and named for
+  their content (`/pricing`, `/how-it-works`) — never `/page2` or query-param
+  navigation.
+
+## JSON-LD on the landing page
+
+The landing page carries one structured-data script describing the product.
+Only mark up what is visibly true on the page — never invent ratings, reviews,
+or offers (fake schema is a Google penalty, not a boost):
+
+```tsx
+head: () => ({
+  meta: [
+    /* title + description as above */
+  ],
+  scripts: [
+    {
+      type: 'application/ld+json',
+      children: JSON.stringify({
+        '@context': 'https://schema.org',
+        '@graph': [
+          { '@type': 'Organization', name: 'Acme Scheduling', description: '…' },
+          { '@type': 'WebSite', name: 'Acme Scheduling' },
+        ],
+      }),
+    },
+  ],
+})
+```
+
+Add further types only when the page genuinely IS that thing and shows the
+required fields: `FAQPage` for a real FAQ section, `Article` for a blog post
+(headline, datePublished, author), `Product`/`Offer` for a real price list.
+Omit `url`/`logo` fields — deployed domain unknown (see "never invent URLs").
+
+## Verify
+
+Open each PUBLIC page and read its `<head>`: a title, a meta description, and
+exactly one `h1`. A public page is not done while any of the three is missing.
+Signed-in pages under `/app` are exempt once `noindex` is set — they are not
+indexed, so their head tags do not matter.
+
+## Don'ts
+
+- No keyword stuffing — write for the reader; one clear topic per page.
+- Don't duplicate the same title/description across pages (worse than absent).
+- Don't render SEO-critical copy only after client-side effects — it must be
+  in the SSR HTML (loader data is fine; `useEffect`-fetched content is not).
+- Don't add robots.txt/sitemap plumbing — the platform owns that layer.

package/skills/pikku-software-archaeology/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: pikku-software-archaeology
 description: 'Use when reverse-engineering an existing repository into a Product Blueprint — recovering what product an undocumented or organically-grown codebase implements so it can be rebuilt cleanly (e.g. as a Pikku app) — and when turning that blueprint into a plain-language second opinion for the non-technical owner who holds the app. TRIGGER when: user says "extract a blueprint", "reverse engineer this app", "what does this codebase actually do as a product", "prepare this repo for a rewrite/migration", points at a legacy repo (any language — JS, TS, Ruby, Python, PHP, Go) and asks for its domains, workflows, business rules or a rebuild plan, or asks "explain how my app works" / "what would you do differently" / "is this built well?" for a founder, PM or operator audience. DO NOT TRIGGER for: documenting code structure, generating API docs from an already-clean codebase, or an engineer-facing code review.'
+installGroups: [core]
 ---
 
 # Software Archaeology

package/skills/pikku-webhook/SKILL.md

@@ -121,6 +121,31 @@ With neither secret set, deliveries go **unsigned**. A missing named secret is
 logged as an error and still sends unsigned; treat that log line as a
 misconfiguration, not noise.
 
+## What this does not give you
+
+There is no subscription model. `webhookSchema` owns exactly two tables —
+`webhookDelivery` and `webhookDeliveryAttempt` — and both are delivery-side
+history. Nothing stores _which_ URL belongs to which customer, which events
+they asked for, or whether their endpoint is still enabled.
+
+That is the app's table, and every app that exposes webhooks to its users
+needs one:
+
+| Column    | Why                                                                                                           |
+| --------- | ------------------------------------------------------------------------------------------------------------- |
+| `url`     | where to POST                                                                                                 |
+| `secret`  | the raw HMAC key, passed as `SendWebhookInput.secret`                                                         |
+| `events`  | which event names this endpoint subscribed to                                                                 |
+| `enabled` | so a failing endpoint can be paused without deleting it                                                       |
+| scope     | the org/tenant column you filter on — mirror it into `organizationId` so the delivery log scopes the same way |
+
+So one emitted event becomes a `SELECT` over your endpoint table and one
+`send()` per row. Everything after that call — signing, queueing, retrying,
+recording — is the primitive's.
+
+The single-integration case needs none of this: one fixed URL on the row it
+belongs to, and `send()` straight at it.
+
 ## Verifying on the receiving side
 
 `sign()` produces `sha256=<hex>` (GitHub style, body only, no timestamp) into