@mortar-ai/skill 0.2.0 → 0.5.0

package/README.md

@@ -1,11 +1,11 @@
 # @mortar-ai/skill
 
 [Agent Skills](https://agentskills.io/) package for building on **Mortar** (the
-BaaS that AI bundles talk to). Install the canonical `SKILL.md` into a compatible
-agent's skill directory to teach it the SDK
-accessors, CLI commands, MCP tools, and — most importantly — the
-tenant-isolation + `auth.tenant_id()` RLS rules that are the easiest
-thing to get wrong.
+BaaS that AI bundles talk to). Install the canonical `SKILL.md` and its
+`references/` into a compatible agent's skill directory to teach it the SDK
+core invariants plus on-demand capability references. The split keeps Fabric's
+loaded prompt small without hiding the storage, realtime, functions, auth, or
+database guidance when a task needs it.
 
 ## Install
 
@@ -17,8 +17,9 @@ mortar-skill-install
 
 Then restart Claude Code (or `/skill reload`).
 
-The same versioned `SKILL.md` is packaged into Fabric Harness. `manifest.json`
-binds the npm version and Harness preinstall to its SHA-256 digest; the Fabric
+The same versioned `SKILL.md` and `references/` package is built into Fabric
+Harness. `manifest.json` binds the npm version and Harness preinstall to a
+deterministic package SHA-256 digest; the Fabric
 Server rejects a Market install when the running Harness reports different
 bytes. npm is an external distribution channel and is not required by Fabric at
 runtime.
@@ -32,22 +33,26 @@ experience.
 
 The skill teaches Claude:
 
-- **SDK surface** — the `mortar.from()` / `auth` / `storage` /
-  `realtime` / `compute` / `usage` / `cron` / `queue` / `comms`
-  accessors + the account-scope `AccountClient`; which one to reach for
-- **CLI commands** — `mortar login / use / db / storage / compute /
-  cron / queue / domains / comms / keys / tokens / topup / usage`
-- **MCP tools** — the 40 `mortar_*` tools and when an agent should use
-  them vs the SDK
-- **Tenant isolation + RLS** — `auth.tenant_id()` (Mortar's analog of
-  Supabase's `auth.uid()`), the `tenant_id = auth.tenant_id()` policy
-  shape, and why every per-project table carries a `tenant_id`
-- **Architecture** — the 9 primitive × (5 core + 3 extension) feature
-  model, and why the SDK shape ≠ the billing shape
-- **Common patterns** — auth (email+password / phone-OTP), data CRUD,
-  file upload + signed URLs, realtime subscribe, queue + cron
-- **Anti-patterns** — assuming Fabric runs on Mortar; using `namespace`
-  instead of `tenant_id`; hand-rolling RLS the SDK already enforces
+- **Core contract** — Fabric-owned client/config files, schema-first workflow,
+  one migration operation per call, supported migration kinds, access-policy
+  invariants, version boundaries, and completion checks.
+- **Database reference** — CRUD, filters, atomic row mutations, trusted
+  cross-table transactions, and ACID boundaries.
+- **Auth reference** — email/password, phone OTP, sessions, password reset, and
+  public-access policy choices.
+- **Storage reference** — upload/download, signed URLs, immutable physical
+  versions, metadata pointers, CORS, and row/object consistency boundaries.
+- **Realtime reference** — Postgres changes, broadcast, presence, unsubscribe,
+  and teardown.
+- **Functions + automation** — invoke/deploy boundaries, cron, queues, and
+  transactional enqueue.
+- **Analytics + operations** — capture/flush, usage, managed logs, primitive
+  billing attribution, and object-egress evidence.
+- **Trusted services** — communications, encrypted secrets, accounts/projects,
+  keys/PATs, custom domains, top-up, and capacity.
+- **Architecture reference** — all 9 infrastructure primitives, the open
+  capability registry, application modules, usage accounting, and
+  credential/trust surfaces.
 
 ## Custom install location
 
@@ -64,8 +69,9 @@ Idempotent — overwrites in place.
 
 ## Maintainer release
 
-`SKILL.md` is the only hand-edited instruction source. Regenerate the manifest
-and Harness copy before testing or publishing:
+`SKILL.md` and `references/` are the hand-edited instruction sources. Keep the
+core short and move capability detail into a routed reference. Regenerate the
+manifest and Harness copy before testing or publishing:
 
 ```bash
 npm run sync
@@ -73,6 +79,8 @@ npm run check
 npm pack --dry-run
 ```
 
+The repository-level synchronizer is shared with Keel and fails on missing
+configured reference directories, resource drift, or unexpected Harness files.
 Never edit `fabric/harness/internal/skills/preinstalled/mortar/` directly.
 
 ## License

package/SKILL.md

@@ -1,10 +1,11 @@
 ---
-name: Mortar
-description: Required guidance for Fabric apps that need a database, backend, authentication, persistence, file storage, realtime collaboration, cloud functions, or product analytics.
-activation: auto
-priority: high
-triggers:
-  - keywords: [database, 数据库, backend, 后端, auth, authentication, 登录, 认证, persistence, 持久化, storage, upload, 文件, realtime, 实时, collaboration, compute, cloud, 云端]
+name: mortar
+description: Build or change Fabric applications that use Mortar capabilities such as database, auth, storage, realtime, functions, analytics, automation, or messaging. Use for Mortar schema and provisioning, SDK integration, access policy, transactions, or backend consistency; not for Fabric's own control plane or a different backend.
+metadata:
+  activation: auto
+  priority: high
+  triggers:
+    - keywords: [database, 数据库, backend, 后端, auth, authentication, 登录, 认证, persistence, 持久化, transaction, 事务, ACID, storage, upload, 文件, realtime, 实时, collaboration, function, compute, analytics, cron, queue, comms, secrets, billing, cloud, 云端]
 ---
 
 # Mortar for Fabric applications
@@ -58,152 +59,94 @@ below; if platform provisioning fails, report that platform failure.
    SQL there: a file in that directory does not execute or change the live
    tenant. Do not edit or create `mortar.config.json`. Do not edit generated
    `integrations/mortar/types.ts`; Fabric regenerates it from the live schema.
-4. Run `npm install @mortar-ai/client` if the dependency is absent, then write app
-   code using the injected singleton.
-5. Type-check and build. Handle every `{ data, error }` result in UI code.
+4. Install or update `@mortar-ai/client` with npm when needed and let npm own the
+   lockfile. Atomic batches, server-side filtered mutations, and
+   `DatabaseTransactions` require version 0.8.0 or newer. Do not rewrite
+   unrelated dependencies.
+5. Before a multi-step mutation, choose the real consistency boundary. A
+   one-table batch or filtered mutation may use the public singleton;
+   cross-table row + queue transactions require trusted server code; object
+   storage and external services never join a PostgreSQL transaction.
+6. Type-check and build. Handle every `{ data, error }` SDK result in UI code.
 
 Supported migration kinds are `create_table`, `drop_table`, `set_table_access`,
-`add_column`, `drop_column`, `create_index`, `set_bucket_access`, `deploy_function`, `delete_function`,
-`upsert_cron`, and `delete_cron`. Destructive and backend-changing operations
-must respect the workspace approval gate. This list is exhaustive: arbitrary
-PostgreSQL, data backfills, PL/pgSQL functions, transactions, and triggers are
-not migration inputs. If required behavior cannot be expressed by one of these
-operations, report the unsupported Mortar capability instead of authoring a SQL
-file that only looks executable.
-
-To change an existing table's access policy, use `set_table_access`. Access is
-metadata and must be updated in place. Never use `drop_table` followed by
-`create_table` for a permission change: dropping a table deletes all of its
-rows and columns.
-
-For a public form, event registration, evidence upload, or similar operator-
-reviewed intake, use `access: "public_insert"` on the destination table and
-`set_bucket_access` with `access: "public_insert"` on any upload bucket. This
-allows a public bundle client to create a new row/object while denying public
-list, read, update, delete, and overwrite. Never use `public` merely to make an
-anonymous form submit successfully; `public` exposes all rows/files for public
-read and mutation. Generate an unguessable object key for every upload.
-
-## Database SDK
-
-The query surface is Supabase-shaped. Async row/auth/storage methods normally
-return `{ data, error }`; check `error` rather than assuming success.
-
-```ts
-const { data: todos, error } = await mortar
-  .from('todos')
-  .select('*')
-  .eq('done', false)
-  .order('created_at', { ascending: false })
-  .limit(20);
-if (error) throw new Error(error.message);
-
-const { data: created, error: insertError } = await mortar
-  .from('todos')
-  .insert({ title: 'Ship', done: false, user_id: userId })
-  .select()
-  .single();
-
-```
-
-Updates and deletes use the same filter chain. Useful operators include `eq`,
-`neq`, ranges, `like/ilike`, `in`, `is`, `order`, `limit`, `single`, and
-`maybeSingle`.
-
-## App-user authentication
-
-Auth sessions are persisted and attached to later database, storage, realtime,
-and compute calls by the SDK.
-
-```ts
-const { data, error } = await mortar.auth.signUp({ email, password });
-const signedIn = await mortar.auth.signInWithPassword({ email, password });
-
-const sent = await mortar.auth.signInWithOtp({ email }); // or { phone }
-const verified = await mortar.auth.verifyOtp({ email, token });
-
-const { data: sessionData } = await mortar.auth.getSession();
-const { data: userData, error: userError } = await mortar.auth.getUser();
-await mortar.auth.signOut();
-```
-
-Use `onAuthStateChange` when UI must react to session changes, and unsubscribe
-the returned subscription during cleanup.
-
-Password reset starts with `mortar.auth.resetPasswordForEmail(email)`; confirm via
-`passwordResetConfirm(email, token, newPassword)`. Never store or pass session
-tokens manually unless the user explicitly needs a server integration.
-
-For private user rows, include the authenticated user's ID in the schema/data
-model and choose the correct table access policy. Client-side filters improve
-UX but do not replace server-side access rules.
-
-## File storage
-
-```ts
-const bucket = mortar.storage.from('avatars');
-
-const { data: uploaded, error: uploadError } = await bucket.upload(path, file, {
-  contentType: file.type,
-  upsert: true,
-});
-const { data: blob, error: downloadError } = await bucket.download(path);
-const { data: files, error: listError } = await bucket.list('users/');
-const { data: signed, error: signError } = await bucket.createSignedUrl(path, 3600);
-const { error: removeError } = await bucket.remove([path]);
-```
-
-Downloads mint a short-lived URL and fetch the object directly from the storage
-backend. Reuse `signed.signedUrl` until it nears expiry when rendering media.
-Prefer the signed URL directly in `<img src>`, `<video src>`, or `<audio src>`;
-this avoids an unnecessary blob copy and does not require CORS merely to render
-the media. Signed-URL minting is excluded from the project's API-concurrency
-budget, but clients should still lazy-load visible media and cache/reuse each
-URL instead of signing again on every render. Signing authorizes a possible
-download; it does not prove bytes were served and must never be described or
-modeled as an object-egress charge. Only provider-observed access-log or billing
-reconciliation may record actual object egress. The optional third
-`createSignedUrl` argument (`{ signal, timeoutMs }`) bounds only the signing
-request when the UI needs a deadline.
-
-`bucket.download(path)` uses JavaScript `fetch()` against the object store and
-therefore needs a matching bucket CORS rule in browsers. Appunvs-managed Mortar
-storage provides that contract; self-hosted object storage must allow the app
-origin for credential-free `GET` / `HEAD`. Never attach Mortar Authorization or
-browser cookies to a signed object URL.
-
-## Realtime, broadcast, and presence
-
-```ts
-const room = mortar
-  .channel('todos-room', { presence: { key: userId } })
-  .on(
-    'postgres_changes',
-    { event: '*', schema: 'public', table: 'todos' },
-    (payload) => refreshFromChange(payload),
-  )
-  .on('broadcast', { event: 'cursor' }, ({ payload }) => drawCursor(payload))
-  .on('presence', { event: 'sync' }, () => renderRoster(room.presenceState()))
-  .subscribe((status) => {
-    if (status === 'SUBSCRIBED') void room.track({ online: true });
-  });
-
-await room.send({ type: 'broadcast', event: 'cursor', payload: { x, y } });
-// On component/page cleanup:
-mortar.removeChannel(room);
+`add_column`, `drop_column`, `create_index`, `set_bucket_access`,
+`deploy_function`, `delete_function`, `upsert_cron`, and `delete_cron`.
+Destructive and backend-changing operations must respect the workspace approval
+gate. This list is exhaustive: arbitrary PostgreSQL, data backfills, PL/pgSQL
+functions, transactions, and triggers are not migration inputs. If required
+behavior cannot be expressed by one of these operations, report the unsupported
+Mortar capability instead of authoring a SQL file that only looks executable.
+
+## Access and safety invariants
+
+- Change an existing table's access with `set_table_access`; never drop and
+  recreate a table merely to change permissions.
+- For a public form, registration, or evidence upload reviewed by an operator,
+  use table/bucket access `public_insert`. It permits new submissions while
+  denying anonymous list, read, update, delete, and overwrite.
+- Never use `public` merely to make anonymous submission work: it exposes all
+  rows or files for public read and mutation.
+- Generate an unguessable logical object key for each public upload.
+- Client-side filters are UX, not authorization. Choose a server-enforced access
+  policy for private or owner-scoped rows.
+- Never put `app` or `admin` keys, `DatabaseTransactions`, operator clients, or
+  other privileged capabilities in Web, Desktop renderer, Keel/React Native, or
+  WeChat bundles.
+- Never call a database + storage/functions/external workflow "atomic". Only
+  work committed inside one tenant-scoped PostgreSQL transaction is ACID.
+
+## On-demand references
+
+The following detailed references are bundled beside this core Skill. Read only
+the documents needed for the current task; do not load all of them by default.
+In Fabric they are materialized under `/tmp/skills/mortar/references/`; other
+Agent Skills hosts resolve the same paths relative to this `SKILL.md`.
+
+- Database CRUD, atomic row mutations, trusted cross-table transactions, and
+  exact ACID boundaries: `references/database.md`
+- App-user signup/signin, OTP, session lifecycle, and private-user modeling:
+  `references/auth.md`
+- Upload/download/list/signed URLs, immutable object versions, CORS, and
+  database-to-object consistency: `references/storage.md`
+- Postgres changes, broadcast, presence, reconnect behavior, and cleanup:
+  `references/realtime.md`
+- Function deployment/invocation, logs, public-key boundaries, and error
+  handling: `references/functions.md`
+- The 9 infrastructure primitives, open capability registry, application
+  modules, usage accounting, and trust surfaces: `references/architecture.md`
+- Product analytics, error capture, delivery guarantees, and operator summary:
+  `references/analytics.md`
+- Cron schedules, queues, workers, retries, and transactional enqueue:
+  `references/automation.md`
+- Transactional email/SMS and provider/idempotency boundaries:
+  `references/communications.md`
+- Encrypted project secrets and function environment injection:
+  `references/secrets.md`
+- Project usage, managed logs, billing attribution, and egress semantics:
+  `references/usage-billing.md`
+- Accounts, projects, API keys, PATs, custom domains, top-up, and capacity:
+  `references/control-plane.md`
+
+When using Fabric `bash`, read the exact materialized path shown by `load_skill`,
+for example:
+
+```sh
+sed -n '1,240p' /tmp/skills/mortar/references/storage.md
 ```
 
-Clean up channels with their page/component. Persist through `from(table)`;
-realtime only notifies peers.
-
-## Compute and analytics
+## Completion checklist
 
-Invoke only functions already deployed through `mortar_migrate`; check
-`response.ok` and read the response body. Analytics provides `track`,
-`identify`, `captureError`, and `flush`; events are fire-and-forget except
-`flush`.
+- Live schema was read before schema design.
+- Every live schema change went through one approved `mortar_migrate` operation.
+- Application code imports only the platform-owned singleton.
+- No secret/admin client or hand-written fallback configuration entered the
+  client bundle.
+- Every SDK error path is handled.
+- The relevant on-demand reference—not every reference—was consulted.
+- Type-check and the surface's real build pass.
 
 ## Boundary for non-Fabric development
 
-For Mortar itself or a standalone non-Fabric integration, inspect the current SDK
-README. Never copy its standalone `createClient` setup into a Fabric project.
+For Mortar itself or a standalone non-Fabric integration, inspect the current
+SDK README. Never copy its standalone `createClient` setup into a Fabric project.

package/bin/install.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
- * mortar-skill-install — copies the canonical SKILL.md into the user's Claude
- * Code skills directory.
+ * mortar-skill-install — copies the canonical SKILL.md and its on-demand
+ * references into the user's Claude Code skills directory.
  *
  * Default destination: `~/.claude/skills/mortar/SKILL.md`.  Override
  * via `--dest=<path>` for non-default Claude installs.
@@ -10,7 +10,7 @@
  */
 'use strict';
 
-const { copyFileSync, existsSync, mkdirSync } = require('node:fs');
+const { copyFileSync, cpSync, existsSync, mkdirSync, rmSync } = require('node:fs');
 const { homedir } = require('node:os');
 const { dirname, resolve } = require('node:path');
 
@@ -27,6 +27,7 @@ function parseFlags(argv) {
 function main() {
   const flags = parseFlags(process.argv);
   const src = resolve(__dirname, '..', 'SKILL.md');
+  const referencesSrc = resolve(__dirname, '..', 'references');
   if (!existsSync(src)) {
     console.error(`mortar-skill: source missing at ${src}`);
     process.exit(1);
@@ -37,7 +38,11 @@ function main() {
 
   mkdirSync(dirname(dest), { recursive: true });
   copyFileSync(src, dest);
+  const referencesDest = resolve(dirname(dest), 'references');
+  rmSync(referencesDest, { recursive: true, force: true });
+  if (existsSync(referencesSrc)) cpSync(referencesSrc, referencesDest, { recursive: true });
   console.log(`✓ Installed Mortar skill → ${dest}`);
+  console.log(`✓ Installed on-demand references → ${referencesDest}`);
   console.log('');
   console.log('Restart Claude Code (or run `/skill reload`) to activate.');
 }

package/index.js

@@ -10,6 +10,7 @@ const { readFileSync } = require('node:fs');
 const { resolve } = require('node:path');
 
 const SKILL_PATH = resolve(__dirname, 'SKILL.md');
+const REFERENCES_PATH = resolve(__dirname, 'references');
 const MANIFEST_PATH = resolve(__dirname, 'manifest.json');
 
 module.exports = {
@@ -25,5 +26,6 @@ module.exports = {
     return JSON.parse(readFileSync(MANIFEST_PATH, 'utf8'));
   },
   SKILL_PATH,
+  REFERENCES_PATH,
   MANIFEST_PATH,
 };

package/manifest.json

@@ -1,16 +1,16 @@
 {
   "schema_version": 1,
   "id": "mortar",
-  "version": "0.2.0",
-  "content_sha256": "sha256:dd11d5e635f47e64303927fd4af21b0f8a9aef8836a17c3a592eecb69cc75325",
+  "version": "0.5.0",
+  "content_sha256": "sha256:cbfe4219fa15934c523c1c22fe9795489539d0083d199624d2d15ac50bfe7755",
   "source_repo": "liamxujia/appunvs",
-  "source_path": "mortar/skill/SKILL.md",
+  "source_path": "mortar/skill",
   "distributions": [
     "harness_preinstalled",
     "npm"
   ],
   "npm": {
     "package": "@mortar-ai/skill",
-    "version": "0.2.0"
+    "version": "0.5.0"
   }
 }

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@mortar-ai/skill",
-  "version": "0.2.0",
-  "description": "Agent skill package for building Fabric applications on Mortar (BaaS), distributed from one versioned SKILL.md with a content-addressed manifest.",
+  "version": "0.5.0",
+  "description": "Agent skill package for building Fabric applications on Mortar (BaaS), with compact core guidance and on-demand references.",
   "main": "index.js",
-  "files": ["SKILL.md", "manifest.json", "index.js", "README.md"],
+  "files": ["SKILL.md", "references", "manifest.json", "index.js", "README.md"],
   "bin": {
     "mortar-skill-install": "bin/install.js"
   },
   "scripts": {
-    "sync": "node scripts/sync-distributions.js",
-    "check": "node scripts/sync-distributions.js --check"
+    "sync": "node ../../shared/skill-distribution/sync.js --config distribution.json",
+    "check": "node scripts/check-coverage.js && node ../../shared/skill-distribution/sync.js --config distribution.json --check"
   },
   "publishConfig": { "access": "public" },
   "license": "Apache-2.0"

package/references/analytics.md

@@ -0,0 +1,29 @@
+# Analytics and error-capture reference
+
+Read this reference for product events, identity traits, error capture, flush
+behavior, or operator summaries. Analytics composes the `warehouse`, `network`,
+and operational logging paths; it is a capability, not a new cost primitive.
+
+The public client batches events and exposes synchronous capture calls plus an
+async flush:
+
+```ts
+mortar.analytics.track('pageview', { path: location.pathname });
+mortar.analytics.identify(user.id, { plan: 'pro' });
+
+try {
+  await checkout();
+} catch (error) {
+  mortar.analytics.captureError(error, { where: 'checkout' });
+  throw error;
+}
+
+await mortar.analytics.flush();
+```
+
+Do not treat capture or flush as a durable business transaction and do not block
+primary UX on analytics delivery. Flush at an explicit lifecycle boundary when
+best-effort delivery should be attempted before navigation or shutdown. The
+summary endpoint is a trusted project/operator read, not part of Fabric's public
+bundle singleton. A deployment without a configured warehouse returns an
+availability error; do not silently invent local analytics persistence.

package/references/architecture.md

@@ -0,0 +1,99 @@
+# Architecture and capability taxonomy reference
+
+Read this reference when deciding where a Mortar API belongs, which credential
+may call it, which code implements it, which infrastructure it consumes, or
+how its observed usage is priced.
+
+Mortar keeps five concerns separate. Do not collapse them into one:
+
+1. A **capability** is an open-ended user or operator outcome exposed by API,
+   SDK, CLI, MCP, or control-plane tooling. There is deliberately no fixed
+   capability count.
+2. A **trust surface** says which credential and runtime may call a capability.
+3. An **application module** implements and composes use cases.
+4. A **primitive** is a provider-neutral resource, replacement, operational,
+   and cost-attribution boundary.
+5. **Usage accounting** observes selected operations, applies meters, quotas,
+   and pricing policy, and records the customer ledger.
+
+An `internal/application/<name>` Go package is an application composition
+module, not a closed product taxonomy. A capability may span multiple
+application, primitive, account, or API packages, and one application module
+may support several capabilities.
+
+The current application modules are `auth`, `cron`, `data`, `files`, `queue`,
+`realtime`, and `secret`. Functions, comms, analytics,
+accounts, and custom domains remain capabilities even when their implementation
+spans primitive, API, account, or other packages rather than a same-named
+application directory. `internal/usage` separately owns metering, quota,
+pricing, and the credit ledger. `internal/subscription` separately owns account
+subscription periods, fulfillment, settlement, and compute-grant allocation;
+usage accounting consumes those grants without owning the subscription
+lifecycle.
+
+## The 9 primitives
+
+| Primitive | Role |
+|---|---|
+| `compute` | Baseline tenant share of pool compute |
+| `database` | PostgreSQL baseline and durable relational state |
+| `cache` | Redis/in-process cache, rate limits, pub/sub, and presence |
+| `storage` | Object bytes and GB-month storage |
+| `network` | Provider-observed or response-writer outbound bytes |
+| `function` | User function execution through a configured runner |
+| `comms` | Transactional email and SMS delivery |
+| `warehouse` | High-cardinality analytics events and summaries |
+| `log` | Managed provider-log ingestion, indexing, and retention |
+
+These names are stable because they align resource ownership, cost attribution,
+and swappable cloud backends. They do not predict the public SDK or customer
+invoice shape. For example, `network` is a side effect rather than
+`mortar.network`, while auth composes database, cache, comms, and network
+without becoming another primitive.
+
+Primitive use is not equivalent to a customer charge. The same `warehouse`
+primitive backs both uncharged summary reads and metered event ingestion.
+Provider cost, observed usage, included allowance, and customer price are four
+different facts; `internal/usage` connects them without making primitive
+interfaces depend on plans or billing.
+
+## Current capability registry
+
+| Capability family | Public app bundle | Trusted project/operator | Account control plane |
+|---|---|---|---|
+| Auth | Signup/signin, OTP, session, reset | User administration | Account signup/signin and notification email |
+| Data | Row CRUD under access policy | Schema/index/column changes and cross-table transactions | Project ownership and lifecycle |
+| Files | Upload/list/delete/sign under bucket policy | Bucket policy and cleanup operations | Project lifecycle cleanup |
+| Realtime | Row changes, broadcast, presence | Backend/channel configuration | — |
+| Functions | Invoke deployed functions | List/deploy/delete/read logs | Read project function logs |
+| Analytics | Capture events and errors | Read project summaries | — |
+| Automation | — | Cron CRUD and queue enqueue/list/get | Read project cron schedules |
+| Communications | — | Send configured email/SMS | Operational account email |
+| Secrets | — | Encrypted project secret CRUD and function injection | — |
+| Usage and logs | — | Project usage ledger and audit logs | Read project usage |
+| Identity and access | — | Project API-key administration | Projects, keys, PATs, ownership |
+| Domains and commerce | — | — | Domain claim/verification, plans, top-up, auto-top-up, capacity/enterprise intent |
+
+The registry grows when a real API or workflow ships. Cron, queue, and custom
+domains are implemented capabilities, not a future three-item extension list.
+Their availability can still depend on configuration: cron may be disabled,
+queue may use PostgreSQL or be off, analytics needs a warehouse, functions need
+a runner, comms needs a provider, and domain TLS routing is completed by the
+deployment edge after Mortar verifies ownership.
+
+## Trust surfaces
+
+- **Public app bundle**: a PUBLIC bundle key plus optional app-user session.
+  Fabric's injected `MortarClient` intentionally contains only auth, row data,
+  storage, realtime, function invocation, and analytics capture.
+- **Trusted project/operator**: app/admin project keys in server, CI, CLI, MCP,
+  or platform provisioning. Never ship these credentials or clients to a Web,
+  Desktop renderer, Keel/React Native, or WeChat bundle.
+- **Account control plane**: account JWT or `mtr_pat_*` PAT against the apex
+  `_accounts` routes. These credentials manage projects and ownership; they are
+  not interchangeable with project or app-user credentials.
+
+When documenting or implementing a capability, state its trust surface, its
+application implementation, the primitives it consumes, and any metering and
+pricing policy. No one field answers authorization, implementation, operations,
+and billing at the same time.

package/references/auth.md

@@ -0,0 +1,33 @@
+# App-user authentication reference
+
+Read this reference for signup/signin, OTP, password reset, session state, or
+private-user data modeling.
+
+Auth sessions are persisted and attached to later database, storage, realtime,
+and compute calls by the platform-owned singleton.
+
+```ts
+const { data, error } = await mortar.auth.signUp({ email, password });
+const signedIn = await mortar.auth.signInWithPassword({ email, password });
+
+const sent = await mortar.auth.signInWithOtp({ email }); // or { phone }
+const verified = await mortar.auth.verifyOtp({ email, token });
+
+const { data: sessionData } = await mortar.auth.getSession();
+const { data: userData, error: userError } = await mortar.auth.getUser();
+await mortar.auth.signOut();
+```
+
+Check each returned `error`; do not infer authentication from the presence of UI
+state. Use `onAuthStateChange` when the UI must react to session changes and
+unsubscribe during component/page cleanup.
+
+Password reset starts with `mortar.auth.resetPasswordForEmail(email)` and is
+confirmed with `passwordResetConfirm(email, token, newPassword)`. Never store or
+pass session tokens manually unless the user explicitly needs a trusted server
+integration.
+
+For private user rows, include the authenticated user ID in the schema/data
+model and select a server-enforced private or owner-scoped table access policy.
+Client-side filters improve UX but do not replace authorization. Anonymous
+intake uses `public_insert`, not broad `public` access.

package/references/automation.md

@@ -0,0 +1,23 @@
+# Cron and queue automation reference
+
+Read this reference for scheduled functions, background jobs, retries, workers,
+or atomic row-plus-job workflows. Cron and queue are shipped capabilities whose
+runtime availability depends on configuration; they are not “planned extension
+slots.”
+
+Fabric provisions schedules only through one `mortar_migrate` operation:
+`upsert_cron` creates or updates a schedule for an already deployed function,
+and `delete_cron` removes it. Direct cron list/create/patch/delete endpoints are
+trusted operator surfaces. Cron is normally enabled and can be disabled by the
+Mortar deployment.
+
+Direct queue enqueue/list/get is also trusted project/operator functionality;
+it is intentionally absent from the public app-bundle `MortarClient`. Queue may
+use the PostgreSQL backend or be disabled. Workers must make handlers
+idempotent, bound retries, and distinguish a claim from successful completion.
+
+When a database change and queue enqueue must commit together, use the trusted
+`DatabaseTransactions` API described in `database.md`. That guarantee applies
+only to the PostgreSQL queue backend and the row operations inside the same
+tenant transaction. Function execution, communications, object storage, and
+external providers remain outside that transaction.

package/references/communications.md

@@ -0,0 +1,16 @@
+# Transactional communications reference
+
+Read this reference for email, SMS, OTP delivery, or provider behavior. Mortar's
+`comms` primitive records email and SMS as separate ledger resources because
+their provider prices differ.
+
+Direct `/comms/send` is a trusted project/operator capability. It is not exposed
+on Fabric's public app-bundle singleton; never place an app/admin key or provider
+credential in client code to reach it. App-user auth may internally compose the
+same primitive for phone OTP, email verification, and password reset.
+
+Hosted Mortar can use configured Aliyun SMS and Aliyun DirectMail adapters.
+Provider availability is deployment-specific, and an unconfigured channel must
+fail visibly. Treat delivery as an external side effect: use an idempotency key
+or persisted outbox state where duplicate messages matter, and never claim that
+a database transaction atomically includes provider delivery.

package/references/control-plane.md

@@ -0,0 +1,25 @@
+# Account and project control-plane reference
+
+Read this reference for Mortar accounts, projects, API keys, PATs, custom
+domains, plans, top-up, auto-top-up, capacity, or enterprise placement.
+
+The control plane uses the apex host and an account JWT or `mtr_pat_*` personal
+access token. It manages account identity, project lifecycle, project API keys,
+PATs, project usage, domain claims, plan/top-up settings, and enterprise intent.
+These credentials are not app-user sessions and cannot be substituted for a
+project key on tenant data-plane routes.
+
+Project API keys have their own scopes. Public bundle keys are expected in app
+code; app/admin keys belong only in trusted server, CI, CLI, MCP, or platform
+provisioning. Revoke and rotate keys through the control plane rather than
+editing generated client configuration.
+
+Custom-domain creation records a claim and verification proves DNS ownership.
+Mortar does not by itself finish edge routing or ACME issuance: the deployment
+edge/operator consumes verified state and configures TLS. Do not claim a domain
+is live merely because its TXT verification succeeded.
+
+Top-up and capacity changes are commercial/control-plane operations, not schema
+migrations. They may involve provider webhooks and asynchronous placement;
+verify the resulting project state rather than assuming request acceptance is
+final settlement or capacity activation.

package/references/database.md

@@ -0,0 +1,101 @@
+# Database and transaction reference
+
+Read this reference for row CRUD, batch mutations, cross-table transactions, or
+questions about Mortar's exact ACID boundary.
+
+## Database SDK
+
+The query surface is Supabase-shaped. Async row methods normally return
+`{ data, error }`; check `error` rather than assuming success.
+
+```ts
+const { data: todos, error } = await mortar
+  .from('todos')
+  .select('*')
+  .eq('done', false)
+  .order('created_at', { ascending: false })
+  .limit(20);
+if (error) throw new Error(error.message);
+
+const { data: created, error: insertError } = await mortar
+  .from('todos')
+  .insert({ title: 'Ship', done: false, user_id: userId })
+  .select()
+  .single();
+if (insertError) throw new Error(insertError.message);
+```
+
+Updates and deletes use the same filter chain. Useful operators include `eq`,
+`neq`, ranges, `like/ilike`, `in`, `is`, `order`, `limit`, `single`, and
+`maybeSingle`.
+
+## Atomic row mutations
+
+Pass an array when every insert or upsert must succeed or fail together. Mortar
+sends at most 200 rows in one request and executes the batch in one
+tenant-scoped PostgreSQL transaction. For upsert, a row with an `id` replaces
+that row's data; a row without an `id` inserts. Do not use a loop or
+`Promise.all` when partial completion would break an invariant.
+
+```ts
+const { data: createdTodos, error: batchError } = await mortar
+  .from('todos')
+  .insert([
+    { title: 'Prepare', done: false, user_id: userId },
+    { title: 'Ship', done: false, user_id: userId },
+  ])
+  .select();
+if (batchError) throw new Error(batchError.message);
+
+const { data: changedTodos, error: updateError } = await mortar
+  .from('todos')
+  .update({ done: true })
+  .eq('user_id', userId)
+  .eq('archived', false)
+  .select();
+if (updateError) throw new Error(updateError.message);
+```
+
+Filtered `update` and `delete` select and mutate all matching rows inside one
+server-side transaction. Do not pre-select IDs and update/delete them one at a
+time; that introduces a race and loses the all-or-nothing guarantee. Chain
+`.select()` only when the app needs the affected rows returned.
+
+## Cross-table transactions are server-only
+
+`DatabaseTransactions` can atomically combine up to 200 cross-table row
+`insert`, by-ID `update`, by-ID `delete`, and PostgreSQL-backed queue `enqueue`
+operations. It is intentionally absent from the injected `mortar` singleton and
+requires an `app` or `admin` key. `execute` throws on failure, so use
+`try`/`catch`, not a `{ data, error }` envelope.
+
+```ts
+import { DatabaseTransactions } from '@mortar-ai/client';
+
+const transactions = new DatabaseTransactions(serverOnlyMortarOptions);
+
+try {
+  const results = await transactions.execute([
+    { op: 'insert', table: 'orders', data: { customer_id: customerId, total } },
+    { op: 'enqueue', type: 'send_receipt', payload: { customer_id: customerId } },
+  ]);
+  console.log(results);
+} catch (error) {
+  // Nothing committed. Report or retry the whole idempotent operation.
+  throw error;
+}
+```
+
+Never instantiate `DatabaseTransactions` in Web, Desktop renderer,
+Keel/React Native, or WeChat code. If a Fabric project has no approved trusted
+server path, report cross-table ACID as unsupported instead of simulating it
+with public-client calls. Transactional queue enqueue also requires Mortar's
+PostgreSQL queue backend; otherwise no row operation commits.
+
+## Exact ACID boundary
+
+Mortar provides ACID only for work executed in the same tenant-scoped
+PostgreSQL transaction: atomic row batches, filtered row mutations, and the
+trusted cross-table row + PostgreSQL queue API above. Object storage,
+compute/functions, communications providers, analytics delivery, and other
+external systems do not participate. Never claim two-phase commit across them.

package/references/functions.md

@@ -0,0 +1,38 @@
+# Functions reference
+
+Read this reference for deploying or invoking compute functions and reading
+function logs. Cron is in `automation.md`; analytics is in `analytics.md`.
+
+## Deploy and invoke functions
+
+Deploy or delete functions only through one `mortar_migrate` operation with
+kind `deploy_function` or `delete_function`. Do not edit `mortar.config.json`,
+write migration files, or call operator/admin SDK methods from application
+code. Function list/deploy/delete/logs are trusted project or account/operator
+surfaces; the app-bundle client exposes invocation only.
+
+Client bundles may invoke a function that the platform already deployed:
+
+```ts
+const response = await mortar.compute.invoke({
+  name: 'create-checkout',
+  method: 'POST',
+  body: JSON.stringify({ orderId }),
+  contentType: 'application/json',
+});
+
+if (!response.ok) {
+  throw new Error(`Function failed: ${response.status} ${await response.text()}`);
+}
+const result = await response.json();
+```
+
+`compute.invoke` is the only public-key compute operation. Mortar infrastructure
+errors such as unavailable compute or timeout throw; user-function status codes
+are returned as the raw `Response`, so check `response.ok` and consume the body.
+Function deployment/logs remain operator-side capabilities and must never be
+recreated with an app/admin key in a browser or mobile bundle.
+
+Functions and external providers do not join the caller's PostgreSQL
+transaction. Make externally visible operations idempotent and persist explicit
+pending/succeeded/failed state when a workflow must recover.

package/references/realtime.md

@@ -0,0 +1,33 @@
+# Realtime, broadcast, and presence reference
+
+Read this reference for row-change notifications, collaboration events, online
+presence, reconnect behavior, or channel cleanup.
+
+```ts
+const room = mortar
+  .channel('todos-room', { presence: { key: userId } })
+  .on(
+    'postgres_changes',
+    { event: '*', schema: 'public', table: 'todos' },
+    (payload) => refreshFromChange(payload),
+  )
+  .on('broadcast', { event: 'cursor' }, ({ payload }) => drawCursor(payload))
+  .on('presence', { event: 'sync' }, () => renderRoster(room.presenceState()))
+  .subscribe((status) => {
+    if (status === 'SUBSCRIBED') void room.track({ online: true });
+  });
+
+await room.send({ type: 'broadcast', event: 'cursor', payload: { x, y } });
+
+// On component/page cleanup:
+mortar.removeChannel(room);
+```
+
+Persist durable state through `mortar.from(table)`. Realtime only notifies
+peers; broadcast and presence are not a database and must not be the sole copy
+of business data.
+
+Use a stable presence key for the signed-in user, keep cursor/ephemeral payloads
+small, and remove channels when their component/page unmounts. The SDK retains
+the last tracked presence state and re-tracks it after reconnect, but the UI
+must still tolerate disconnect/reconnect and duplicate change notifications.

package/references/secrets.md

@@ -0,0 +1,17 @@
+# Project secrets reference
+
+Read this reference for function credentials, API tokens, encryption, or secret
+rotation. Secret list/put/delete is a trusted project/operator capability and is
+intentionally absent from the public app-bundle client.
+
+Store provider credentials through Mortar's secret provisioning surface. Mortar
+encrypts project secret values at rest and injects the resolved values into the
+configured function environment. Do not copy a secret into Fabric source,
+generated integration files, public environment variables, logs, analytics, or
+function request payloads merely to make it reachable.
+
+Application bundles should call a deployed function that uses the secret on the
+server side. Rotation is a separate operation from function invocation; design
+long-running workflows to tolerate a credential changing between attempts. If
+the deployment has no encryption key or secret service configured, report the
+platform failure instead of falling back to plaintext storage.

package/references/storage.md

@@ -0,0 +1,48 @@
+# File storage and consistency reference
+
+Read this reference for buckets, uploads/downloads, signed URLs, media rendering,
+CORS, or workflows that relate a database row to an object.
+
+```ts
+const bucket = mortar.storage.from('avatars');
+
+const { data: uploaded, error: uploadError } = await bucket.upload(path, file, {
+  contentType: file.type,
+  upsert: true,
+});
+const { data: blob, error: downloadError } = await bucket.download(path);
+const { data: files, error: listError } = await bucket.list('users/');
+const { data: signed, error: signError } = await bucket.createSignedUrl(path, 3600);
+const { error: removeError } = await bucket.remove([path]);
+```
+
+Applications address files by their stable logical `path`. Mortar stores new
+uploads under immutable internal physical versions, atomically switches its
+PostgreSQL metadata pointer, and schedules orphan/replaced versions for durable
+retryable cleanup. Never construct, persist, or expose an internal physical
+object key. Application projects do not run or author the platform storage
+migration.
+
+This protocol prevents Mortar metadata from pointing at a partial upload, but a
+separate application row and an object upload are not one transaction. Generate
+an unguessable logical key. For a simple workflow, upload first and write the
+business row after success. For recoverable workflows, create a row with a
+stable idempotency key and `pending` state, upload, then mark it `ready`; reconcile
+stale rows to `failed` or retry them. Do not run a database write and
+`bucket.upload()` concurrently and call the result atomic.
+
+Downloads mint a short-lived URL and fetch the object directly from the storage
+backend. Reuse `signed.signedUrl` until near expiry and prefer it directly in
+`<img>`, `<video>`, or `<audio>` instead of making an unnecessary blob copy.
+Signed-URL minting is excluded from the project's API-concurrency budget, but
+clients should lazy-load media and cache/reuse each URL. Signing authorizes a
+possible download; it does not prove bytes were served and is not an
+object-egress charge. Only provider access logs or billing reconciliation may
+record actual object egress.
+
+The optional third `createSignedUrl` argument (`{ signal, timeoutMs }`) bounds
+only the signing request. `bucket.download(path)` uses JavaScript `fetch()` and
+therefore needs a matching bucket CORS rule in browsers. Appunvs-managed Mortar
+provides that contract; self-hosted storage must allow credential-free `GET` and
+`HEAD` from the app origin. Never attach Mortar Authorization or cookies to a
+signed object URL.

package/references/usage-billing.md

@@ -0,0 +1,27 @@
+# Usage, managed logs, and billing reference
+
+Read this reference for quota, balance, overage, managed logs, or network/object
+egress attribution. The 9 primitives are infrastructure and cost-attribution
+boundaries; user-facing usage and billing are capabilities built over selected
+observations, meters, allowances, pricing policy, and the credit ledger.
+
+A primitive is never inherently free or billable. For example, warehouse event
+ingestion is metered while a warehouse summary read is not. Keep four facts
+separate: provider cost, observed units, included allowance, and customer
+charge. Primitive interfaces remain unaware of those policies.
+
+Project usage and audit-log reads are trusted project/operator surfaces, with an
+account-owned project usage view on the account control plane. They are not part
+of Fabric's public bundle singleton. A balance or quota read does not itself
+create a metered observation or customer charge.
+
+Do not estimate object egress from signed-URL minting or object size. Signing is
+authorization and the URL may never be used or may be reused many times. Actual
+direct OSS/COS/OBS bytes require provider access logs or billing reconciliation.
+Mortar-served responses can be counted at the response writer, but direct object
+downloads bypass it.
+
+Managed-log billing uses provider-canonical ingestion records with durable IDs
+for deduplication; query response bytes are not ingestion. Function logs retain
+their function/source context. Never turn a read query or repeated reconciliation
+scan into duplicate usage rows.