@stacksjs/defaults 0.75.108 → 0.75.110

package/ai/skills/stacks-setup-engineering/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the "Label in our tracker" column to match whatever vocabulary you actually use.

package/ai/skills/stacks-sites/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: stacks-sites
+description: Use when resolving multi-site tenants by host, provisioning sites, scoping queries, or authorizing site-owned content. Covers @stacksjs/sites and config/sites.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Multi-site tenancy
+
+The native package resolves hosts and carries a site snapshot through a request.
+Host tenancy and an authenticated administrator's team ownership are different
+contracts; do not substitute one for the other.
+
+## Resolution and explicit scoping
+
+Use siteResolver with configured resolver/store behavior. normalizeHost,
+classifyHost, requestHost and resolveSiteByHost own host parsing and lookup.
+currentSite, currentSiteId, requireSite and runWithSite serve API request context.
+An unresolved site fails a required-site operation rather than silently selecting
+another tenant. Respect platform hosts and configured forwarded-host trust.
+
+forSite(query, column, siteId) adds an explicit predicate. Defining a Site model
+does not globally scope every raw query. A site id in an arbitrary request body
+is not an authenticated or host-resolved tenant. siteOwnership governs admin
+resources using the caller's real team membership; public reads scope by host.
+
+API AsyncLocalStorage is not the snapshot read by every stx server render.
+Templates use requestContext.site() through the serving layer's per-request
+snapshot. Read stacks-config and stacks-stx before crossing that boundary.
+
+## Provisioning
+
+provisionSite refreshes a supplied tenant's site/branding and creates missing
+starter pages while preserving matched existing paths. Verify normalized nested
+slugs and parent paths before relying on reprovisioning idempotency for a complex
+page hierarchy. Pass actual tenancy and
+page input; it does not invent a tenant model or overwrite all CMS content.
+Use stacks-cms document APIs for pages and stacks-forms for site-owned forms.
+
+Test two concurrent sites, platform/unresolved hosts, query predicates,
+administrator membership, reprovisioning and edited-page preservation.
+Source: core/sites/src/{context,resolver,middleware,scoping,provision,snapshot}.ts.
+Evidence: sites.test.ts and provision.test.ts.

package/ai/skills/stacks-skills/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: stacks-skills
+description: Use when discovering, validating, overriding, or distributing Stacks agent skills. Covers @stacksjs/skills, app/Skills, bundled defaults and buddy setup:ai.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Native skill discovery
+
+listSkills returns sorted unique names. resolveSkillPath and getSkill resolve
+app/Skills before storage/framework/defaults/ai/skills. A same-name app skill
+shadows the framework definition; it is not a second copy in the result.
+
+getSkill returns metadata, instructions, source path and supporting directory
+entries. validateSkill checks name/description requirements, name spelling,
+lengths and folder-name agreement. It is not a full YAML parser or a semantic
+proof that every referenced API exists. Use loadSkillMetadata for discovery
+without inventing a separate registry of names.
+
+buddy setup:ai materializes the merged set for the selected agent, using
+per-skill symlinks or copies. Preserve shared references inside skill directories
+so copy mode still works. Do not overwrite authored AGENTS.md or a real CLAUDE.md
+merely to refresh generated files. Future app installs receive bundled skills
+through @stacksjs/defaults and managed scaffold sync.
+
+Read stacks-writing-for-agents before authoring instructions. New native
+packages need a skill or an explicit mapping in docs:native-skills. Keep the
+documentation page, sidebar, source notice when imported, and supporting files
+together. Test runtime discovery and fresh-app distribution, not only filenames.
+
+Source: core/skills/src/skills.ts and core/buddy/src/commands/setup-ai.ts.
+Evidence: skills.test.ts, setup-ai.test.ts and the docs/distribution contracts.

package/ai/skills/stacks-slug/SKILL.md

@@ -18,17 +18,14 @@ URL-friendly slug generation with database uniqueness checking.
 ```typescript
 import { uniqueSlug } from '@stacksjs/slug'
 
-// Basic usage — checks 'slug' column in inferred table
+// No table/column supplied: plain slugification, no database collision check
 const slug = await uniqueSlug('My Blog Post Title')
 // → 'my-blog-post-title'
 
-// If 'my-blog-post-title' exists in DB:
-// → 'my-blog-post-title-2'
-
-// With options
+// Supply BOTH table and column to check collisions
 const slug = await uniqueSlug('Product Name', {
   table: 'products',     // database table to check
-  column: 'slug'         // column name (default: 'slug')
+  column: 'slug'         // required for database checking
 })
 ```
 
@@ -48,7 +45,7 @@ slugify('Ünïcödé Têxt')          // 'unicode-text'
 slugify('  Extra   Spaces  ')    // 'extra-spaces'
 ```
 
-Re-exported from `ts-slug` — handles Unicode transliteration.
+Re-exported from `ts-slug` - handles Unicode transliteration.
 
 ## Model Usage
 
@@ -62,7 +59,7 @@ defineModel({
     slug: {
       unique: true,
       validation: { rule: schema.string() },
-      // Auto-generated from title via uniqueSlug()
+      // Populate explicitly in the action using uniqueSlug(title, options)
     }
   }
 })
@@ -72,14 +69,20 @@ defineModel({
 
 ```typescript
 interface SlugifyOptions {
-  table?: string         // database table for uniqueness check
-  column?: string        // column name (default: 'slug')
+  table: TableNames      // database table for uniqueness check
+  column: string         // no implicit column default
 }
 ```
 
 ## Gotchas
-- `uniqueSlug()` is async — it queries the database
-- `slugify()` is sync — no database interaction
+- Omitting either table or column returns the base slug with no query.
+- The check and insert are separate: keep a UNIQUE index and handle/retry an
+  insert conflict. A helper cannot reserve the returned slug against a race.
+- Collision attempts are bounded; after repeated conflicts the helper returns
+  a cryptographically randomized suffix instead of looping forever.
+- Declaring a slug attribute does not itself populate it from the title.
+- `uniqueSlug()` is async - it queries the database
+- `slugify()` is sync - no database interaction
 - Collision detection appends `-2`, `-3`, etc. (not random suffixes)
 - Unicode characters are transliterated (u → u, e → e, etc.)
 - For string-only slugification without DB, use `slug()` from `@stacksjs/strings` instead

package/ai/skills/stacks-sms/SKILL.md

@@ -22,7 +22,7 @@ Multi-driver SMS system with verification (OTP), templates, bulk sending, and a
 
 ```typescript
 // Main facade and functions
-import SMS, { sms, send, sendSms, sendBulk, sendTemplate } from '@stacksjs/sms'
+import { SMS, sms, send, sendSms, sendBulk, sendTemplate } from '@stacksjs/sms'
 import { startVerification, checkVerification, cancelVerification } from '@stacksjs/sms'
 import { formatE164, isValidPhoneNumber, isEnabled, getConfig, configure, getDriver, init } from '@stacksjs/sms'
 import { SmsBuilder } from '@stacksjs/sms'
@@ -34,7 +34,7 @@ import { VonageDriver, createVonageDriver } from '@stacksjs/sms'
 
 ## SMS Facade Object
 
-The `SMS` default export aggregates all functions:
+The named `SMS` export aggregates the SMS facade functions:
 
 ```typescript
 SMS.init()                    // Load config from config/sms.ts
@@ -190,7 +190,7 @@ Returns a failed result (without throwing) if the template is not found.
 import { formatE164, isValidPhoneNumber } from '@stacksjs/sms'
 
 // Normalize to E.164 format
-formatE164('+1 (234) 567-890')        // '+12345678900'
+formatE164('+1 (234) 567-8900')       // '+12345678900'
 formatE164('2345678900', '1')          // '+12345678900'
 formatE164('002345678900')             // '+2345678900' (00 prefix stripped)
 
@@ -371,15 +371,42 @@ interface VerificationResult {
 ```
 
 ## Gotchas
-- SMS is **disabled by default** (`enabled: false`) -- must set to `true` in `config/sms.ts`
+- SMS config defaults disabled, but low-level send does not enforce isEnabled; application entrypoints must honor that gate before dispatch
 - Provider API keys go in `.env`, not config files
 - Config is loaded lazily via dynamic import on first `send()`/operation -- `init()` pre-loads it
 - Only Twilio and Vonage drivers are fully implemented; other drivers (gupshup, plivo, sns, telnyx, etc.) are commented-out placeholders
 - `pinpoint` appears in config but has no driver implementation in `getDriver()` -- using it throws `'Unsupported SMS provider: pinpoint'`
 - `defaultCountryCode` is a numeric dialing prefix such as `'1'` for the US or `'44'` for the UK
 - Template variables use single-brace syntax `{variableName}`, NOT double-brace
-- `sendBulk()` sends all messages in parallel via `Promise.all` -- no rate limiting
-- Twilio verification requires a `verifyServiceSid` passed to the driver constructor, which is not part of the standard config structure
+- Facade sendBulk uses config.bulk.concurrency (default 10) and delayMs between chunks; provider driver sendBulk still sends its chunk concurrently
+- Twilio verification uses drivers.twilio.verifyServiceSid from TWILIO_VERIFY_SERVICE_SID, forwarded by getDriver to the constructor
 - Vonage JWT authentication is a simplified placeholder -- real RS256 signing is not fully implemented
 - `getDriver()` creates a new driver instance each time unless accessed through the cached `getDefaultDriver()`
 - `sendTemplate()` returns a failed result (not an exception) if the template name is not found
+
+
+## Native inbound compliance and helpers
+
+`handleInboundSms({ from, body }, { appName?, helpContact? })` classifies
+STOP/START/HELP, persists opt-out or opt-in, and returns the reply an inbound
+webhook should send. `optOutPhone`, `optInPhone`,
+`isPhoneOptedOut` and `normalizePhone` use the persistent
+`sms_opt_outs` table. Apply its model migration first. Sending through the
+generic notification SMS channel checks opt-outs; inspect the selected direct
+send path before assuming a low-level provider call applies that policy.
+
+For Twilio webhooks, `verifyTwilioWebhook(url, fields, signature, authToken)`
+validates the exact external URL and submitted fields. `parseTwilioInbound`
+normalizes its payload. `classifySmsIntent/smsComplianceReply` are pure helpers;
+they do not themselves persist consent. Use the persistent handleInboundSms
+workflow when consent state must affect future sends.
+
+`estimateSmsSegments(body)` reports GSM-7/UCS-2 estimates; provider billing is
+authoritative. `isWithinSmsQuietHours(date, { startHour, endHour, timezone? })`
+is a policy helper, not an automatic send gate. Config keys such as spend caps
+or quiet hours must be traced to their consumers before promising enforcement.
+
+Sources: `storage/framework/core/sms/src/opt-out.ts` and `compliance.ts`.
+Tests: `opt-out.test.ts` and `compliance.test.ts` under core/sms/tests.
+Twilio/Vonage implementations do not imply a live provider delivery contract;
+credentials, registration and provider account configuration remain prerequisites.

package/ai/skills/stacks-socials/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-socials
-description: Use when implementing social authentication in Stacks - OAuth2 flows with GitHub/Google/Facebook/Twitter providers, the AbstractProvider base class, PKCE support, state management, scope configuration, social user profiles, or token handling. Covers @stacksjs/socials.
+description: Use when implementing social sign-in, Apple callbacks, PKCE/session handoff, named publishing identities, or publishing through native platform drivers. Covers @stacksjs/socials and config/socials.ts.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -8,296 +8,83 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Socials
 
-OAuth2-based social authentication with 4 built-in providers.
-
-## Key Paths
-- Core package: `storage/framework/core/socials/src/`
-
-## Source Files
-```
-socials/src/
-├── index.ts          # re-exports from drivers/
-├── abstract.ts       # AbstractProvider base class
-├── token.ts          # Token class
-├── types.ts          # SocialUser, provider-specific interfaces
-├── exceptions.ts     # InvalidStateException, ConfigException
-└── drivers/
-    ├── index.ts      # re-exports all 4 providers
-    ├── github.ts     # GitHub OAuth provider
-    ├── google.ts     # Google OAuth provider
-    ├── facebook.ts   # Facebook OAuth provider
-    └── twitter.ts    # Twitter/X OAuth2 + PKCE provider
-```
-
-## AbstractProvider Base Class
-
-All providers extend `AbstractProvider` which implements `ProviderInterface`. The constructor takes a `ProviderConfig`:
-
-```typescript
-interface ProviderConfig {
-  clientId: string
-  clientSecret: string
-  redirectUrl: string
-  guzzle?: Record<string, any>
-}
-```
-
-Properties and methods on `AbstractProvider`:
-
-```typescript
-abstract class AbstractProvider implements ProviderInterface {
-  // Protected state
-  protected clientId: string
-  protected clientSecret: string
-  protected redirectUrl: string
-  protected parameters: Record<string, any> = {}
-  protected _scopes: string[] = []
-  protected scopeSeparator: string = ','
-  protected _stateless: boolean = false
-  protected _usesPKCE: boolean = false
-  protected user: SocialUser | null = null
-
-  // Abstract methods (each provider implements)
-  abstract getAuthUrl(): Promise<string>           // public, returns Promise
-  protected abstract getTokenUrl(): string         // protected
-  abstract getAccessToken(code: string): Promise<string>
-  abstract getUserByToken(token: string): Promise<SocialUser>
-
-  // Scope management
-  scopes(scopes: string | string[]): this      // merge into existing (deduplicates via Set)
-  setScopes(scopes: string | string[]): this   // replace all scopes (deduplicates via Set)
-  getScopes(): string[]
-
-  // Configuration
-  setRedirectUrl(url: string): this
-  stateless(): this                             // sets _stateless = true
-  enablePKCE(): this                            // sets _usesPKCE = true
-  with(parameters: Record<string, any>): this   // replaces custom query parameters
-
-  // User retrieval
-  async userFromToken(token: string): Promise<SocialUser>  // calls getUserByToken, adds token
-
-  // URL building (protected)
-  protected buildAuthUrlFromBase(url: string, state: string | null): string
-  protected getCodeFields(state: string | null = null): Record<string, any>
-  protected formatScopes(scopes: string[], scopeSeparator: string): string
-
-  // State helpers (protected)
-  protected usesState(): boolean          // returns !_stateless
-  protected isStateless(): boolean        // returns _stateless
-  protected getState(): string            // 20 random bytes -> 40 hex chars
-
-  // PKCE helpers (protected)
-  protected usesPKCE(): boolean
-  protected getCodeVerifier(): string              // 48 random bytes -> 96 hex chars
-  protected async getCodeChallenge(): Promise<string>  // SHA-256 of verifier, base64url encoded
-  protected getCodeChallengeMethod(): string       // always 'S256'
-}
-```
-
-The `getCodeFields()` method builds the query parameters for the authorization URL:
-- Always includes: `client_id`, `redirect_uri`, `scope` (joined by `scopeSeparator`), `response_type: 'code'`
-- Conditionally adds `state` when `usesState()` is true
-- Conditionally adds `code_challenge` and `code_challenge_method` when `usesPKCE()` is true
-- Merges in any custom `parameters` set via `with()`
-
-## Provider Implementations
-
-### GitHub Provider
-
-```typescript
-class GitHubProvider extends AbstractProvider {
-  protected baseUrl = 'https://github.com'
-  protected apiUrl = 'https://api.github.com'
-}
-```
-
-- Config source: `config.services.github` (clientId, clientSecret, redirectUrl, scopes)
-- Default scopes: `['read:user', 'user:email']`
-- Auth URL: `https://github.com/login/oauth/authorize` with scopes joined by space
-- Token URL: `https://github.com/login/oauth/access_token` (POST)
-- User API: Fetches `/user` and `/user/emails` in parallel via `Promise.all`
-- Email resolution: Primary email first, then verified, then first available
-- Uses `@stacksjs/api` `fetcher` for HTTP requests
-- Throws `ConfigException` if clientId, clientSecret, or redirectUrl missing
-- GitHub token response: `GitHubTokenResponse { access_token, error?, error_description? }`
-
-### Google Provider
-
-```typescript
-class GoogleProvider extends AbstractProvider {
-  protected baseUrl = 'https://accounts.google.com'
-  protected apiUrl = 'https://www.googleapis.com'
-}
-```
-
-- Config source: `config.services.google`
-- Default scopes: `['https://www.googleapis.com/auth/userinfo.profile', 'https://www.googleapis.com/auth/userinfo.email']`
-- Auth URL: `https://accounts.google.com/o/oauth2/v2/auth` (includes `access_type: 'offline'`, `prompt: 'consent'`)
-- Token URL: `https://accounts.google.com/oauth2/v4/token` (POST with `grant_type: 'authorization_code'`)
-- User API: `https://www.googleapis.com/oauth2/v2/userinfo` with Bearer token
-- Maps `given_name` to `nickname`, `picture` to `avatar`
-- Google user type: `{ id, email, verified_email, name, given_name, family_name, picture, locale }`
-
-### Facebook Provider
-
-```typescript
-class FacebookProvider extends AbstractProvider {
-  protected baseUrl = 'https://www.facebook.com'
-  protected apiUrl = 'https://graph.facebook.com'
-}
-```
-
-- Config source: `config.services.facebook`
-- Default scopes: `['email', 'public_profile']`
-- Auth URL: `https://www.facebook.com/v18.0/dialog/oauth` with scopes joined by comma
-- Token URL: `https://graph.facebook.com/v18.0/oauth/access_token` (GET request, not POST)
-- User API: `https://graph.facebook.com/v18.0/me?fields=id,name,email,picture`
-- Token is passed as query parameter `access_token`, not in Authorization header
-- Always sets `nickname: null` (Facebook does not expose usernames)
-- Avatar extracted from `picture.data.url`
-- Error response shape: `{ error: { message, type, code } }` (nested object, unlike other providers)
-
-### Twitter/X Provider
-
-```typescript
-class TwitterProvider extends AbstractProvider {
-  protected baseUrl = 'https://twitter.com'
-  protected apiUrl = 'https://api.twitter.com'
-  private codeVerifier: string | null = null
-}
-```
-
-- Config source: `config.services.twitter`
-- Default scopes: `['users.read', 'tweet.read']`
-- Uses OAuth 2.0 with PKCE (not OAuth 1.0a)
-- Auth URL: `https://twitter.com/i/oauth2/authorize` with PKCE code challenge
-- Token URL: `https://api.twitter.com/2/oauth2/token` (POST with Basic auth)
-- User API: `https://api.twitter.com/2/users/me?user.fields=profile_image_url` with Bearer token
-- PKCE implementation uses its own `generateCodeVerifier()` and `generateCodeChallenge()` methods (using `node:crypto` `randomBytes` and `createHash`), not the base class PKCE
-- Code verifier: `randomBytes(32)` -> base64 -> alphanumeric only -> max 128 chars
-- Token exchange uses Basic auth: `Buffer.from(clientId:clientSecret).toString('base64')`
-- `getAccessToken()` throws if `codeVerifier` is null -- `getAuthUrl()` must be called first
-- Maps `username` to `nickname`, `profile_image_url` to `avatar`
-
-## SocialUser Interface
-
-```typescript
-interface SocialUser {
-  id: string
-  nickname: string | null
-  name: string
-  email: string | null
-  avatar: string | null
-  token: string
-  raw?: any               // full provider API response
-}
-```
-
-## ProviderInterface
-
-```typescript
-interface ProviderInterface {
-  getAuthUrl: () => Promise<string>
-  getAccessToken: (code: string) => Promise<string>
-  getUserByToken: (token: string) => Promise<SocialUser>
-}
-```
-
-## Token Class
-
-```typescript
-class Token {
-  constructor(
-    public accessToken: string,
-    public refreshToken: string | null = null,
-    public expiresIn: number | null = null,
-    public approvedScopes: string[] = [],
-  ) {}
-}
-```
-
-## Provider-Specific Types
-
-```typescript
-// GitHub
-interface GitHubUser { id: number, login: string, name: string | null, avatar_url: string | null, [key: string]: any }
-interface GitHubEmail { email: string, primary: boolean, verified: boolean }
-interface GitHubTokenResponse { access_token: string, error?: string, error_description?: string }
-
-// Twitter/X
-interface TwitterUser { id: string, username: string, name: string, email?: string, profile_image_url?: string }
-interface TwitterTokenResponse { access_token: string, token_type: string, expires_in: number, scope: string, error?: string, error_description?: string }
-
-// Google (local to google.ts)
-interface GoogleUser { id: string, email: string, verified_email: boolean, name: string, given_name: string, family_name: string, picture: string, locale: string }
-interface GoogleTokenResponse { access_token: string, token_type: string, expires_in: number, error?: string, error_description?: string }
-
-// Facebook (local to facebook.ts)
-interface FacebookUser { id: string, email?: string, name: string, picture?: { data: { url: string } } }
-interface FacebookTokenResponse { access_token: string, token_type: string, expires_in: number, error?: { message: string, type: string, code: number } }
-```
-
-## Exceptions
-
-```typescript
-class InvalidStateException extends Error { name = 'InvalidStateException' }
-class ConfigException extends Error { name = 'ConfigException' }
-```
-
-Providers throw `ConfigException` when `clientId`, `clientSecret`, or `redirectUrl` are missing.
-
-## OAuth2 Flow
-
-### 1. Get Auth URL
-```typescript
-const github = new GitHubProvider({ clientId: '', clientSecret: '', redirectUrl: '' })
-const authUrl = await github.scopes(['user:email', 'read:org']).getAuthUrl()
-// Each provider reads actual config from config.services.<provider>
-// The constructor config is overridden by getConfig() in each provider
-```
-
-### 2. Handle Callback
-```typescript
-const token = await github.getAccessToken(code)
-const user = await github.getUserByToken(token)
-// user: { id, nickname, name, email, avatar, token, raw }
-```
-
-### 3. User from Existing Token
-```typescript
-const user = await github.userFromToken(existingToken)
-// Calls getUserByToken internally, adds token to result
-```
-
-## Configuration Source
-
-All providers read from the Stacks config object:
-```typescript
-config.services.github   // { clientId, clientSecret, redirectUrl, scopes }
-config.services.google   // { clientId, clientSecret, redirectUrl, scopes }
-config.services.facebook // { clientId, clientSecret, redirectUrl, scopes }
-config.services.twitter  // { clientId, clientSecret, redirectUrl, scopes }
-```
-
-Each provider's `getConfig()` method reads these and also calls `this.setScopes()` with the configured scopes.
-
-## Dependencies
-- `@stacksjs/api` -- `fetcher` used for all HTTP requests (provides `.withHeaders()`, `.get()`, `.post()`)
-- `@stacksjs/config` -- provides `config.services.*` for provider credentials
-- `node:buffer` and `node:crypto` -- used by Twitter provider for PKCE and Basic auth
-
-## Gotchas
-- The `ProviderConfig` constructor params are largely ignored -- each provider's `getConfig()` reads from `config.services.*` instead
-- `getAuthUrl()` returns `Promise<string>` (not `string`) -- it is async
-- `getTokenUrl()` is `protected` -- not part of the public `ProviderInterface`
-- GitHub joins scopes with space, Facebook with comma, Google with space, Twitter with space
-- Facebook uses GET for token exchange; all others use POST
-- Facebook `nickname` is always `null`
-- Twitter requires `getAuthUrl()` before `getAccessToken()` because the code verifier is stored as instance state
-- Twitter uses its own PKCE implementation via `node:crypto`, not the base class `getCodeVerifier()`/`getCodeChallenge()`
-- Google auth URL includes `access_type: 'offline'` and `prompt: 'consent'` for refresh token support
-- The base class state token is 40 hex chars (20 bytes), not the 20 chars stated in some docs
-- `userFromToken()` spreads the user object and adds/overwrites the `token` field
-- All providers include the full API response in `SocialUser.raw`
-- Errors from GitHub/Google/Twitter are flat objects with `error` + `error_description`; Facebook nests it under `error.message`
+The native package has separate social sign-in and publishing APIs. Selecting a
+publishing identity does not sign a user into the app, and a sign-in token is not
+necessarily authorized to publish.
+
+## Social sign-in
+
+Apple, Facebook, GitHub, Google and X providers implement getAuthUrl,
+getAccessToken(code), getUserByToken(token) and inherited userFromToken.
+configuredSocialProviders/isSocialProviderConfigured/socialProvider expose the
+native provider registry and prerequisite checks. Render buttons from that
+registry rather than guessing clientId/clientSecret works for every provider.
+
+Apple uses teamId/keyId/privateKey to mint a client-secret JWT; it has no static
+client secret requirement. Its callback is a cross-site POST, so a GET-only
+callback cannot complete it. Read the native default auth route/actions and
+provider test before handling one-time Apple name data or ID-token verification.
+Meta API version is centralized in meta-graph.ts rather than an obsolete v18
+copied into every example.
+
+Scopes/setScopes/with/setRedirectUrl belong to AbstractProvider. Providers read
+their actual services config and impose provider-specific scope and credential
+rules. withState supplies the flow's state and validateState checks the expected
+and returned values; persist expected state in the native callback session.
+Twitter sign-in keeps a PKCE verifier on its instance; getAuthUrl must
+precede its exchange on the same stateful flow. Persist and validate state/PKCE
+through the native callback path before minting an app credential; low-level
+getUserByToken alone does not prove the browser initiated a login.
+
+SocialUser includes emailVerified. Respect the provider's verification signal
+and the configured account-linking policy, using auth's resolveSocialSignIn
+instead of attaching any equal email address to an existing account. Provider
+errors and ConfigException/InvalidStateException are different from successful
+profile retrieval. Never log raw credential fields.
+
+## Session handoff
+
+socialHandoffRedirect(pack, { redirectTo?, allowedHosts? }) emits a no-store
+redirect with the native encoded session handoff. Browser useAuth's
+completeSocialLogin consumes it and removes the fragment. isSafeHandoffTarget
+checks permitted redirect shape; choose a server-owned landing path. The helper
+also supplies a failed-sign-in redirect. These are separate from provider token
+exchange and the auth cookie/session issuance policy.
+
+## Named publishing identities
+
+config/socials.ts declares identities/platforms and optional defaultIdentity.
+resolveSocialCredentials and the six platform-specific resolvers read settings
+after config readiness, with explicit identity selection and environment-backed
+credentials. envName/envSegment define the SOCIALS_<IDENTITY>_<PLATFORM>_<FIELD>
+namespace. An identity's declared platform and required fields are checked; a
+handle used in a permalink is not an authentication credential.
+
+Native publishing drivers cover Bluesky, X, LinkedIn, Mastodon, Instagram and
+Threads. publishingDriver/platform options and toDriverIdentity map the actual
+account/instance/URN fields; socialPublishTarget resolves a complete target,
+including a Bluesky session, and publishAs(platform, post, identity?, env?) sends
+through it. PublishPostInput/PublishedPost/SocialPublishingDriver are exported
+contracts. Read their driver methods before using media, metrics, deletion,
+refresh or profile functionality; support differs per provider.
+
+## Authorization and operational limits
+
+The native terminal consent helper in authorize.ts currently supports X only.
+It uses loopback callback URI, checked state and PKCE; offline.access supplies
+refresh credentials. Declaring another publishing platform does not make the
+same interactive consent helper support it. Stored tokens, platform account
+access and provider app registration remain prerequisites.
+
+Drafting or reviewing a post does not itself authorize publishAs, deletion,
+credential writes or a consent flow. Use the task's explicit authorization for
+those actions. Local driver/request tests establish behavior, not live platform
+conformance or successful publication for arbitrary accounts.
+
+## Source and evidence
+
+`storage/framework/core/socials/src/index.ts`, registry.ts, abstract.ts,
+handoff.ts, identities.ts, publish.ts, authorize.ts, meta-graph.ts and drivers/.
+Tests: registry.test.ts, apple.test.ts, session-handoff.test.ts,
+identities.test.ts, publish.test.ts, authorize.test.ts,
+credentials-stay-out-of-output.test.ts and meta-graph.test.ts.