start-vibing-stacks 2.14.0 → 2.16.0

package/stacks/_shared/skills/observability/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: observability
-version: 1.0.0
-description: Structured logging, correlation IDs, OpenTelemetry tracing, error tracking (Sentry), metrics, and PII redaction. Invoke when adding logging, instrumentation, or debugging production issues.
+version: 2.0.0
+description: "Structured logging, correlation IDs, OpenTelemetry tracing (semconv 1.41+, including GenAI conventions for Anthropic / OpenAI / AWS Bedrock / Azure AI / MCP), error tracking (Sentry), metrics, PII redaction, audit log separation. Invoke when adding logging, instrumentation, AI/LLM observability, or debugging production issues."
 ---
 
 # Observability — Logs, Traces, Metrics
@@ -285,6 +285,75 @@ Cardinality rule: never tag with user_id, email, or unbounded values — explode
 
 ---
 
+## 6.5. AI / LLM Observability — OTel GenAI Semantic Conventions *(2026)*
+
+OpenTelemetry GenAI conventions (semconv ≥ 1.37, current ≥ 1.41) standardize how LLM calls are traced. They cover: **model spans**, **agent spans**, **events** (inputs/outputs), and provider-specific conventions for **Anthropic, OpenAI, AWS Bedrock, Azure AI Inference, and MCP (Model Context Protocol)**.
+
+> Status: Development (not yet stable). Set `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental` to opt in to current attribute names. **Do not use deprecated `gen_ai.prompt` / `gen_ai.completion` attributes** — they were removed in 1.28 in favor of log-based events.
+
+### Required attributes on every LLM span
+
+| Attribute | Example |
+|---|---|
+| `gen_ai.system` | `"anthropic"`, `"openai"`, `"aws.bedrock"`, `"azure.ai.inference"` |
+| `gen_ai.operation.name` | `"chat"`, `"text_completion"`, `"embeddings"` |
+| `gen_ai.request.model` | `"claude-opus-4-5"`, `"gpt-5"`, `"sonnet-4-5"` |
+| `gen_ai.response.model` | The actual model that served the request (may differ on Bedrock/Gateway) |
+| `gen_ai.usage.input_tokens` | Numeric |
+| `gen_ai.usage.output_tokens` | Numeric |
+| `gen_ai.response.finish_reasons` | `["stop"]`, `["length"]`, `["tool_calls"]` |
+
+### Recording inputs/outputs as **events** (not attributes)
+
+```ts
+import { trace, SpanKind } from '@opentelemetry/api';
+const tracer = trace.getTracer('llm');
+
+await tracer.startActiveSpan('chat anthropic', { kind: SpanKind.CLIENT }, async (span) => {
+  span.setAttributes({
+    'gen_ai.system': 'anthropic',
+    'gen_ai.operation.name': 'chat',
+    'gen_ai.request.model': 'claude-opus-4-5',
+  });
+
+  // Inputs/outputs go as EVENTS, not attributes — keeps spans cheap, allows redaction
+  span.addEvent('gen_ai.user.message', { 'gen_ai.message.content': redact(userMsg) });
+
+  const res = await anthropic.messages.create({ /* ... */ });
+
+  span.setAttributes({
+    'gen_ai.response.model': res.model,
+    'gen_ai.usage.input_tokens': res.usage.input_tokens,
+    'gen_ai.usage.output_tokens': res.usage.output_tokens,
+    'gen_ai.response.finish_reasons': [res.stop_reason],
+  });
+  span.addEvent('gen_ai.assistant.message', { 'gen_ai.message.content': redact(res.content) });
+  span.end();
+  return res;
+});
+```
+
+### MCP (Model Context Protocol) spans
+
+For agentic flows that call MCP servers:
+- `gen_ai.system`: `"mcp"`
+- `gen_ai.tool.name`: tool invoked
+- Span kind: `CLIENT` (your agent → MCP server)
+
+### Cost & token metrics
+
+```ts
+const meter = metrics.getMeter('llm');
+const tokensUsed = meter.createCounter('gen_ai.client.token.usage', { unit: '{token}' });
+
+tokensUsed.add(res.usage.input_tokens,  { 'gen_ai.system': 'anthropic', 'gen_ai.token.type': 'input',  'gen_ai.request.model': 'claude-opus-4-5' });
+tokensUsed.add(res.usage.output_tokens, { 'gen_ai.system': 'anthropic', 'gen_ai.token.type': 'output', 'gen_ai.request.model': 'claude-opus-4-5' });
+```
+
+**PII rules still apply** — redact user content in events the same way you redact request bodies in HTTP logs.
+
+---
+
 ## 7. Health Checks
 
 Two endpoints, distinct semantics:
@@ -331,6 +400,7 @@ Different retention (often longer), different access (security team), different
 - [ ] Sentry initialized with `beforeSend` scrubber
 - [ ] Tracing initialized at process start (before app code)
 - [ ] `/healthz` + `/readyz` endpoints exist
+- [ ] LLM calls emit `gen_ai.*` attributes + token-usage metrics; user content redacted
 
 ## FORBIDDEN
 

package/stacks/_shared/skills/openapi-design/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: openapi-design
-version: 1.0.0
-description: OpenAPI 3.1 spec design — resource naming, status codes, problem+json (RFC 9457) errors, pagination, versioning, security schemes, idempotency, deprecation. Stack-agnostic. Invoke when designing or documenting any HTTP/REST API that publishes an OpenAPI spec, regardless of framework (Fastify, Hono, FastAPI, Laravel, Express, etc.).
+version: 2.0.0
+description: "OpenAPI 3.1 / 3.2 spec design — resource naming, status codes, problem+json (RFC 9457) errors, pagination, versioning, security schemes, idempotency, deprecation. Covers OpenAPI 3.2 (Sept 2025) deltas: native Server-Sent Events (SSE), JSON Lines streaming, hierarchical tags (parent/kind), QUERY HTTP method, additionalOperations, querystring location, $self document URI, OAuth2 device flow. Fully backward-compatible with 3.1 (no breaking changes). Stack-agnostic. Invoke when designing or documenting any HTTP/REST API that publishes an OpenAPI spec, regardless of framework (Fastify, Hono, FastAPI, Laravel, Express, etc.)."
 ---
 
-# OpenAPI Design — Universal API Contract
+# OpenAPI Design — Universal API Contract (3.1 + 3.2)
 
 **Invoke before adding a new endpoint, before publishing a public API, and during code review of any route handler.**
 
@@ -12,6 +12,27 @@ description: OpenAPI 3.1 spec design — resource naming, status codes, problem+
 
 This skill covers **what the spec should look like**. For **how to generate it** in your stack, see the per-framework skill (`fastify-api`, `hono-api`, `fastapi-patterns`, `laravel-patterns`, etc.).
 
+## Version policy (2026)
+
+- **OpenAPI 3.2** (Sept 2025): adopt for new specs — fully backward-compatible with 3.1, just bump the `openapi` field. **Zero breaking changes.**
+- **OpenAPI 3.1** (Feb 2021): full JSON Schema 2020-12 — still fine for stable APIs.
+- **OpenAPI 3.0**: legacy. Migrate when convenient.
+
+### What 3.2 adds (cheat sheet)
+
+| Feature | Use when |
+|---|---|
+| **Server-Sent Events (SSE)** as a first-class media type | Long-running progress, AI streaming responses, live dashboards |
+| **JSON Lines** (`application/jsonl`) | Streaming row-oriented data (logs, exports) |
+| **Multipart streaming** | Upload progress with metadata |
+| **Hierarchical tags** (`parent`, `kind`, `summary`) | Replaces vendor-extensions `x-tagGroups`, `x-displayName`. Native nav for large APIs. |
+| **`QUERY` HTTP method** | Safe & idempotent reads with a request body (search APIs that exceed URL limits) |
+| **`additionalOperations`** field | Document custom HTTP verbs without spec extensions |
+| **`querystring` parameter location** | Describe an entire query string as a single typed parameter |
+| **`$self`** document URI | Solves multi-document `$ref` resolution |
+| **OAuth2 Device Authorization flow** | CLI / IoT auth |
+| **Discriminator `defaultMapping`** | Cleaner polymorphic schemas |
+
 ---
 
 ## 1. Resource Naming
@@ -52,6 +73,93 @@ The action sub-resource pattern (`/orders/{id}/cancel`) is the escape hatch when
 
 ---
 
+## 2.5. Streaming Responses *(OpenAPI 3.2)*
+
+Stop documenting streams as `200 application/json` with hand-rolled extensions. 3.2 lets you describe SSE, JSON Lines, and multipart streams natively.
+
+### Server-Sent Events (SSE)
+
+```yaml
+paths:
+  /chat/{id}/stream:
+    get:
+      summary: Stream assistant tokens as they generate
+      responses:
+        '200':
+          description: SSE stream
+          content:
+            text/event-stream:
+              schema:
+                type: object
+                properties:
+                  event: { type: string, enum: [token, tool_call, done] }
+                  data:  { type: object }
+```
+
+### JSON Lines (newline-delimited JSON)
+
+```yaml
+paths:
+  /exports/{id}:
+    get:
+      responses:
+        '200':
+          description: One JSON object per line
+          content:
+            application/jsonl:
+              schema:
+                $ref: '#/components/schemas/Order'
+```
+
+Use SSE for **client subscribes to live updates** (chat tokens, progress); JSON Lines for **bulk row export** (logs, analytics dumps). Document the terminator (`event: done` for SSE; EOF for JSON Lines) so codegen clients know when to stop reading.
+
+---
+
+## 2.6. Hierarchical Tags *(OpenAPI 3.2)*
+
+Replaces the legacy `x-tagGroups` / `x-displayName` extensions. Native nested navigation in tools that support 3.2.
+
+```yaml
+tags:
+  - name: billing
+    summary: Billing
+    kind: nav            # 'nav' = navigation group only, no operations directly under it
+  - name: invoices
+    parent: billing
+    summary: Invoices
+  - name: payments
+    parent: billing
+    summary: Payments
+```
+
+For tools still on 3.1, the same effect is achieved with `x-tagGroups` / `x-displayName`. Specs published as 3.2 should drop the extensions.
+
+---
+
+## 2.7. The `QUERY` HTTP method *(OpenAPI 3.2)*
+
+For **safe & idempotent** reads whose parameters exceed URL length limits (complex search, large filter sets). Bodies on `GET` are technically legal but proxies eat them; `QUERY` is the standardized escape hatch.
+
+```yaml
+paths:
+  /search:
+    additionalOperations:
+      QUERY:
+        summary: Complex search
+        requestBody:
+          required: true
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SearchRequest'
+        responses:
+          '200': { $ref: '#/components/responses/SearchResults' }
+```
+
+`QUERY` is **safe** (no side effects) and **idempotent** (same body → same response) — clients and caches treat it like `GET`.
+
+---
+
 ## 3. Error Envelope — `application/problem+json` (RFC 9457)
 
 One shape for every error response in the entire API. Codegen clients can match a single discriminator.

package/stacks/_shared/skills/playwright-automation/SKILL.md

@@ -1,23 +1,85 @@
 ---
 name: playwright-automation
-version: 1.0.0
+version: 2.0.0
+description: "Playwright 1.60+ E2E and browser-automation patterns for 2026. Page Object Model, fixtures (auth + DB cleanup), multi-viewport (375 / 768 / 1280), trace viewer, UI Mode v2 (search + system theme), HAR recording (1.60), screencast API (1.59), Playwright Agents (planner/generator/healer, 1.56+), sharding for CI, accessibility snapshots. Invoke when writing E2E tests or browser automation."
 ---
 
-# Playwright Automation — E2E Testing
+# Playwright Automation — E2E Testing (1.60+)
 
 **ALWAYS invoke when writing E2E tests or browser automation.**
 
-## Structure
+> Pin Playwright in `package.json` and pin the matching browser binary version. Mismatch between client and browser is the #1 source of "flaky in CI" reports.
+
+## Version policy (2026)
+
+- **1.60** (current): HAR recording first-class API (`tracing.startHar()` / `stopHar()`), `locator.drop()`, `test.abort()`, aria-snapshot bounding-box.
+- **1.59**: `page.screencast` (video with action annotations + real-time frames), `browser.bind()`.
+- **1.58**: UI Mode + Trace Viewer search (`Cmd/Ctrl+F`), `system` theme, JSON auto-format, **CLI+SKILLs token-efficient mode** (relevant for AI-assisted authoring).
+- **1.57**: aria snapshot improvements.
+- **1.56**: **Playwright Agents** (planner / generator / healer) — AI-assisted test creation and self-healing locators.
+
+```json
+// package.json
+"devDependencies": {
+  "@playwright/test": "1.60.0"
+},
+"scripts": {
+  "test:e2e": "playwright test",
+  "test:e2e:ui": "playwright test --ui",
+  "test:e2e:debug": "PWDEBUG=1 playwright test",
+  "test:e2e:trace": "playwright show-trace test-results/trace.zip"
+}
+```
+
+## Folder structure
 
 ```
 tests/e2e/
-├── fixtures/          # Auth, DB cleanup, custom fixtures
-├── pages/             # Page Object Model
-├── flows/             # User journey tests
-├── api/               # API-only tests
+├── fixtures/             # Auth, DB cleanup, custom fixtures
+├── pages/                # Page Object Model
+├── flows/                # User journey tests
+├── api/                  # API-only tests (request fixture)
+├── visual/               # Screenshot / aria-snapshot regressions
 └── playwright.config.ts
 ```
 
+## `playwright.config.ts` — production-ready baseline
+
+```ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env['CI'],
+  retries: process.env['CI'] ? 2 : 0,
+  workers: process.env['CI'] ? 4 : undefined,
+  reporter: [
+    ['html', { open: 'never' }],
+    ['junit', { outputFile: 'test-results/junit.xml' }],
+    ...(process.env['CI'] ? [['github']] : []),
+  ],
+  use: {
+    baseURL: process.env['E2E_BASE_URL'] ?? 'http://localhost:3000',
+    trace: 'on-first-retry',           // saves cost; debug locally with --trace=on
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    actionTimeout: 10_000,
+    navigationTimeout: 30_000,
+  },
+  projects: [
+    { name: 'chromium-desktop', use: { ...devices['Desktop Chrome'], viewport: { width: 1280, height: 800 } } },
+    { name: 'webkit-tablet',    use: { ...devices['iPad (gen 7)'] } },
+    { name: 'mobile-chrome',    use: { ...devices['Pixel 7'] } },
+  ],
+  webServer: process.env['CI'] ? undefined : {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: true,
+  },
+});
+```
+
 ## Page Object Model
 
 ```typescript
@@ -42,10 +104,15 @@ export abstract class BasePage {
 }
 ```
 
-## Auth Fixture
+## Fixtures — cleanup is mandatory
 
-```typescript
-export function generateTestUser(): TestUser {
+```ts
+// tests/e2e/fixtures/auth.ts
+import { test as base } from '@playwright/test';
+
+type TestUser = { name: string; email: string; password: string };
+
+function generateTestUser(): TestUser {
   const ts = Date.now();
   const rand = Math.random().toString(36).substring(7);
   return {
@@ -54,9 +121,42 @@ export function generateTestUser(): TestUser {
     password: 'TestPassword123!',
   };
 }
+
+export const test = base.extend<{ user: TestUser }>({
+  user: async ({ request }, use) => {
+    const user = generateTestUser();
+    await request.post('/api/test/users', { data: user });
+    await use(user);
+    await request.delete(`/api/test/users/${encodeURIComponent(user.email)}`); // cleanup
+  },
+});
+```
+
+The cleanup runs **even if the test fails** — fixtures unwind with try/finally semantics. Track every created entity in a fixture; never trust a test to clean up after itself.
+
+## Selector priority (use locators, not CSS)
+
+1. `getByRole('button', { name: 'Save' })` — accessibility-aware
+2. `getByLabel('Email')` — form fields
+3. `getByPlaceholder('Search...')` — when label is implied
+4. `getByText('Welcome back')` — visible text content
+5. `getByTestId('submit-button')` — escape hatch when above don't fit
+
+CSS / XPath only as last resort. Prefer roles — they double as accessibility checks.
+
+```html
+<!-- Required data-testid on app-rendered elements -->
+<input data-testid="email-input" />
+<input data-testid="password-input" />
+<button data-testid="submit-button" />
+<div data-testid="error-message" />
+<div data-testid="success-message" />
+<div data-testid="loading-spinner" />
+<nav data-testid="sidebar" />
+<button data-testid="hamburger-menu" />
 ```
 
-## Multi-Viewport Testing
+## Multi-viewport testing (375 / 768 / 1280)
 
 ```typescript
 const viewports = [
@@ -66,30 +166,76 @@ const viewports = [
 ] as const;
 
 for (const viewport of viewports) {
-  test.describe(`Responsive - ${viewport.name}`, () => {
+  test.describe(`Responsive — ${viewport.name}`, () => {
     test.use({ viewport: { width: viewport.width, height: viewport.height } });
     test('navigation adapts', async ({ page }) => { /* ... */ });
   });
 }
 ```
 
-## Required data-testid
+## Aria snapshots — accessibility regression *(1.50+, improved in 1.60)*
 
-```html
-<input data-testid="email-input" />
-<input data-testid="password-input" />
-<button data-testid="submit-button" />
-<div data-testid="error-message" />
-<div data-testid="success-message" />
-<div data-testid="loading-spinner" />
-<nav data-testid="sidebar" />
-<button data-testid="hamburger-menu" />
+```ts
+// First run records snapshot:
+await expect(page.locator('main')).toMatchAriaSnapshot();
+
+// Subsequent runs assert structure stays the same — catches accessibility regressions
+// Update with: npx playwright test --update-snapshots
 ```
 
+## HAR recording *(1.60)*
+
+```ts
+// Record outbound network for replay or debugging
+await context.tracing.startHar({ path: 'test.har' });
+await page.goto('/checkout');
+await context.tracing.stopHar();
+
+// Replay against a recorded HAR (offline / deterministic tests):
+await context.routeFromHAR('checkout.har', { update: false });
+```
+
+## Trace Viewer + UI Mode
+
+```bash
+npx playwright test --trace on             # full trace
+npx playwright show-trace test-results/.../trace.zip
+npx playwright test --ui                   # UI Mode v2 — Cmd/Ctrl+F search, system theme, single-worker
+```
+
+## Sharding for CI
+
+```yaml
+# Split a slow E2E suite across N runners
+strategy:
+  matrix:
+    shardIndex: [1, 2, 3, 4]
+    shardTotal: [4]
+steps:
+  - run: npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
+```
+
+Then merge HTML reports with `npx playwright merge-reports`.
+
+## Playwright Agents *(1.56+, AI-assisted)*
+
+The `planner`, `generator`, and `healer` agents support AI-driven test creation and self-healing locators. Useful when bootstrapping coverage on a legacy app, but **always commit human-reviewed tests** — never let an agent rewrite locked tests in CI without approval.
+
 ## FORBIDDEN
 
-1. **Hardcoded test data** — generate unique data with timestamps
-2. **`.skip()` or `.only()`** — never in committed code
-3. **No cleanup** — always track + clean created data
-4. **Mocked auth** — use real authentication flows
-5. **Single viewport** — test mobile + tablet + desktop
+| Pattern | Why |
+|---|---|
+| Hardcoded test data (`test@test.com`) | Breaks parallel runs, leaves orphan rows |
+| `.skip()` or `.only()` in committed code | Silently disables coverage |
+| No fixture cleanup | Test DB fills with garbage |
+| Mocked auth | Integration value lost; the real flow breaks unnoticed |
+| Single viewport | Mobile breaks shipped to prod |
+| `page.waitForTimeout(N)` | Flaky; use `waitFor`, `toBeVisible`, etc. |
+| CSS selectors when a role / label exists | Loses accessibility coverage |
+| `--no-deps` in CI install | Browser binaries silently outdated |
+
+## See Also
+
+- `test-coverage` — what to test, fixtures rules
+- `accessibility-wcag22` — pair with `getByRole` + aria snapshots
+- `ci-pipelines` — Playwright on CI (cache `~/.cache/ms-playwright`)

package/stacks/_shared/skills/postgres-patterns/SKILL.md

@@ -1,16 +1,97 @@
 ---
 name: postgres-patterns
-version: 1.0.0
-description: PostgreSQL design, security, and tuning at the SQL/operations layer — role separation, Row-Level Security (RLS), connection security, JSONB, partitioning, indexing strategy (BTREE/GIN/BRIN/partial/expression), EXPLAIN ANALYZE, isolation levels, locking, advisory locks, connection pool sizing. Stack-agnostic. Invoke when designing Postgres schemas, hardening database access, or debugging Postgres query performance. Complements per-stack ORM skills (Drizzle, SQLAlchemy, Eloquent, Mongoose) and the database-migrations skill.
+version: 2.0.0
+description: "PostgreSQL design, security, and tuning at the SQL/operations layer — role separation, Row-Level Security (RLS), connection security, JSONB, partitioning, indexing strategy (BTREE/GIN/BRIN/skip-scan/partial/expression), EXPLAIN ANALYZE, isolation levels, locking, advisory locks, connection pool sizing, plus PG 18 (Sept 2025) features: uuidv7(), virtual generated columns (now default), temporal constraints, asynchronous I/O, OAuth 2.0 auth. Stack-agnostic. Invoke when designing Postgres schemas, hardening database access, or debugging Postgres query performance. Complements per-stack ORM skills (Drizzle, SQLAlchemy, Eloquent, Mongoose) and the database-migrations skill."
 ---
 
-# PostgreSQL — Design, Security, and Tuning
+# PostgreSQL — Design, Security, and Tuning (PG 17 / 18-aware)
 
 **Invoke when designing a Postgres schema, granting database access, picking an index, debugging a slow query, or hardening prod connection settings.**
 
 > Postgres is the same on every stack. The application code differs. This skill covers the database side — what to ask of it, how to lock it down, and how to read its performance signals. For schema **deployment** (concurrent indexes, lock timeouts, backfills, parallel change), see `database-migrations`.
 
-This skill assumes Postgres ≥ 15 (14 still supported but missing some features called out below). PG 16/17 add more — flagged where relevant.
+This skill assumes Postgres ≥ 16. **PG 18 (released Sept 25, 2025) is the recommended target for new projects** — see §0 for headline features. PG 17 (Sept 2024) is the safe LTS-style choice for production today; PG 14/15 are still supported but missing features called out below.
+
+---
+
+## 0. PG 18 — What changed (Sept 25, 2025)
+
+The most consequential release for application code in years. Adopt for greenfield; plan migration for prod.
+
+| Feature | Why it matters |
+|---|---|
+| **`uuidv7()`** built-in function | Time-ordered UUIDs → drastically better B-tree locality than `gen_random_uuid()` (uuidv4). Use as PK default. |
+| **Virtual generated columns** (now the **default** for `GENERATED ... AS (...)` without `STORED`) | Computed at read time, no write amplification. PG 17 only had `STORED`. |
+| **Temporal constraints** on PK / UNIQUE / FK (`PERIOD`) | Native bitemporal modelling — no more manual `tstzrange` + EXCLUDE workarounds for "valid history" tables. |
+| **Asynchronous I/O (AIO) subsystem** | Up to **3×** sequential-scan / bitmap-heap / vacuum perf. Tunable via `io_method` GUC. |
+| **Skip-scan on multicolumn B-tree indexes** | Index `(a, b)` is now usable to filter by `b` alone (with `a`-cardinality penalty). Reduces "wrong-prefix" index proliferation. |
+| **OAuth 2.0 authentication** | Native SSO at the wire protocol — no PAM/LDAP gymnastics. |
+| **`pg_upgrade` keeps optimizer stats** | Post-upgrade slow-down on first day eliminated. |
+| **OLD / NEW in `RETURNING`** | `UPDATE ... RETURNING OLD.balance, NEW.balance` — audit trails without triggers. |
+
+### `uuidv7()` as PK default *(PG 18 idiom)*
+
+```sql
+-- PG 18+
+CREATE TABLE orders (
+  id   uuid PRIMARY KEY DEFAULT uuidv7(),
+  ...
+);
+
+-- PG ≤ 17 — emulate via extension
+CREATE EXTENSION IF NOT EXISTS pg_uuidv7;   -- third-party
+```
+
+UUIDv7 layout: 48-bit unix-ms timestamp + random tail. Inserts hit the *right* edge of the B-tree → no random-IO write amplification (the well-known v4 problem).
+
+### Virtual generated columns
+
+```sql
+-- PG 18 — default is VIRTUAL (computed at read)
+CREATE TABLE invoices (
+  amount_cents int  NOT NULL,
+  tax_cents    int  GENERATED ALWAYS AS (amount_cents * 0.1) NOT STORED,    -- still works; explicit NOT STORED
+  total_cents  int  GENERATED ALWAYS AS (amount_cents + (amount_cents * 0.1))  -- DEFAULT virtual in PG 18
+);
+```
+
+Use VIRTUAL for cheap derivations; STORED when the value is read >> written or indexed.
+
+### Temporal constraints
+
+```sql
+-- PG 18 — native bitemporal PK
+CREATE TABLE employee_salary (
+  employee_id int NOT NULL,
+  salary      numeric NOT NULL,
+  valid       tstzrange NOT NULL,
+  PRIMARY KEY (employee_id, valid WITHOUT OVERLAPS)
+);
+-- INSERTs that overlap on `valid` for the same employee are rejected — no EXCLUDE-with-gist hack.
+```
+
+### Tuning AIO
+
+```
+# postgresql.conf — PG 18
+io_method = 'io_uring'    # Linux ≥ 5.x recommended; 'worker' fallback on others
+io_workers = 3            # tune to NVMe queue depth
+```
+
+---
+
+## PG 17 — Still excellent (Sept 2024)
+
+If you're not yet on 18, prioritize these PG 17 features:
+
+- **VACUUM** memory cut up to 20× → much shorter maintenance windows.
+- **WAL throughput** up to 2× under heavy write concurrency.
+- **`pg_createsubscriber`** — promote a physical standby to a logical subscriber in minutes (cuts initial-sync time).
+- **`JSON_TABLE()`** — SQL-standard way to flatten JSONB into rows; avoid hand-written `jsonb_to_recordset` plumbing.
+- **`COPY ... ON_ERROR ignore`** — bulk loads tolerate single bad rows without aborting.
+- **BRIN parallel build** — finally usable for big append-only tables.
+
+---
 
 ---