@mortar-ai/skill 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @mortar-ai/skill
+
+[Claude Code](https://claude.ai/code) skill package for building on
+**Mortar** (the BaaS that AI bundles talk to).  Drop it into your skills
+directory + Claude becomes instantly Mortar-fluent: knows 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.
+
+## Install
+
+```bash
+npm i -g @mortar-ai/skill
+mortar-skill-install
+# → installs to ~/.claude/skills/mortar/SKILL.md
+```
+
+Then restart Claude Code (or `/skill reload`).
+
+Pairs naturally with the [Mortar MCP server](../mcp) — the skill teaches Claude
+*how* to think about Mortar; the MCP gives it live tools to *act* on a
+project.  Install both for the full Supabase-plugin-equivalent
+experience.
+
+## What's inside
+
+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
+
+## Custom install location
+
+```bash
+mortar-skill-install --dest=/path/to/your/skills/dir/mortar.md
+```
+
+Useful for team-shared skill repositories or in-repo skill packs.
+
+## Updating
+
+Re-run `mortar-skill-install` after `npm update @mortar-ai/skill`.
+Idempotent — overwrites in place.
+
+## License
+
+Apache-2.0 (same as the rest of Mortar).

package/bin/install.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * mortar-skill-install — copies mortar-skill.md into the user's Claude
+ * Code skills directory.
+ *
+ * Default destination: `~/.claude/skills/mortar/SKILL.md`.  Override
+ * via `--dest=<path>` for non-default Claude installs.
+ *
+ * Idempotent: re-running overwrites the existing file in place.
+ */
+'use strict';
+
+const { copyFileSync, existsSync, mkdirSync } = require('node:fs');
+const { homedir } = require('node:os');
+const { dirname, resolve } = require('node:path');
+
+function parseFlags(argv) {
+  const out = { dest: undefined };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--dest=')) out.dest = a.slice('--dest='.length);
+    else if (a === '--dest') out.dest = argv[++i];
+  }
+  return out;
+}
+
+function main() {
+  const flags = parseFlags(process.argv);
+  const src = resolve(__dirname, '..', 'mortar-skill.md');
+  if (!existsSync(src)) {
+    console.error(`mortar-skill: source missing at ${src}`);
+    process.exit(1);
+  }
+  const dest = flags.dest
+    ? resolve(flags.dest)
+    : resolve(homedir(), '.claude', 'skills', 'mortar', 'SKILL.md');
+
+  mkdirSync(dirname(dest), { recursive: true });
+  copyFileSync(src, dest);
+  console.log(`✓ Installed Mortar skill → ${dest}`);
+  console.log('');
+  console.log('Restart Claude Code (or run `/skill reload`) to activate.');
+}
+
+main();

package/index.js

@@ -0,0 +1,24 @@
+// @mortar-ai/skill — exports the skill markdown for programmatic use.
+//
+// Consumers (e.g. a future `mortar install --self-update` flow) can
+// require this package + push the markdown content into wherever they
+// want; the bin/install.js script is the standard CLI path.
+
+'use strict';
+
+const { readFileSync } = require('node:fs');
+const { resolve } = require('node:path');
+
+const SKILL_PATH = resolve(__dirname, 'mortar-skill.md');
+
+module.exports = {
+  /**
+   * skillContents() returns the raw markdown.  Useful when a
+   * higher-level CLI wants to embed it into another package's skill
+   * output (symmetric with @keel-ai/skill's skillContents()).
+   */
+  skillContents() {
+    return readFileSync(SKILL_PATH, 'utf8');
+  },
+  SKILL_PATH,
+};

package/mortar-skill.md

@@ -0,0 +1,250 @@
+---
+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, 云端]
+---
+
+# Mortar for Fabric applications
+
+Mortar is an independent Backend-as-a-Service used by Fabric-built apps; Fabric
+itself does not run on Mortar. Do not infer its setup from another BaaS.
+
+## Fabric integration contract
+
+- Bundler projects (Web, Desktop renderer, Keel/React Native) import the
+  platform singleton only:
+
+  ```ts
+  import { mortar } from '@/integrations/mortar/client';
+  ```
+
+- WeChat has no `@/` alias. A page normally imports:
+
+  ```ts
+  import { mortar } from '../../utils/mortar/client';
+  ```
+
+- `src/integrations/mortar/client.ts`, its `types.ts`, and the WeChat equivalents
+  under `utils/mortar/` are platform-owned. Never create, overwrite, or replace
+  them.
+- Never add `VITE_MORTAR_*`, `MORTAR_URL`, or client-side API-key environment
+  variables. Never hand-write `createClient(...)`, `src/lib/mortar.ts`, or a
+  second wrapper/client in a Fabric project.
+- Fabric seeds an import-safe singleton, then injects the tenant URL and PUBLIC
+  bundle key after provisioning. The public key belongs in app code; it is not
+  a server/admin secret.
+- Add `@mortar-ai/client` to `dependencies` with npm when the app first needs
+  Mortar. The agent owns `package.json`, `package-lock.json`, and `node_modules`.
+  Run the install before starting the dev server.
+- WeChat's injected singleton uses `@mortar-ai/client/wechat`, which supplies
+  `wx.request`, `wx.*StorageSync`, and chunked-request realtime adapters. Do not
+  replace it with raw `wx.request` calls to Mortar.
+
+If the singleton reports that the backend is not connected, do not invent a
+fallback URL or ask the user for keys. Use the platform schema/provisioning flow
+below; if platform provisioning fails, report that platform failure.
+
+## Required workflow
+
+1. Call `mortar_schema` before designing or changing backend data. It returns
+   the current live schema, including console changes.
+2. For each schema change, call `mortar_migrate` once with one operation. It
+   applies the live change first; only after success does Fabric append a
+   migration record under `mortar/migrations/`.
+3. `mortar/migrations/` is a platform-owned output journal. Never create or edit
+   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.
+
+Example schema operations (the tool schema is authoritative for all fields):
+
+```json
+{"kind":"create_table","table":"todos","access":"private","columns":[{"name":"title","type":"text","required":true},{"name":"done","type":"bool"},{"name":"user_id","type":"uuid","required":true}]}
+```
+
+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();
+
+const { data: updated, error: updateError } = await mortar
+  .from('todos')
+  .update({ done: true })
+  .eq('id', todoId)
+  .select();
+
+const { error: deleteError } = await mortar
+  .from('todos')
+  .delete()
+  .eq('id', todoId);
+```
+
+Useful chaining includes `eq`, `neq`, `gt/gte`, `lt/lte`, `like/ilike`, `in`,
+`is`, `order`, `range`, `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();
+
+const { data: listener } = mortar.auth.onAuthStateChange((event, session) => {
+  // INITIAL_SESSION | SIGNED_IN | SIGNED_OUT | TOKEN_REFRESHED
+});
+listener.subscription.unsubscribe();
+
+await mortar.auth.signOut();
+```
+
+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. Use the third
+`createSignedUrl` argument to bound only the signing request when the UI needs
+a deadline:
+
+```ts
+const { data: signed, error } = await bucket.createSignedUrl(path, 900, {
+  signal: controller.signal,
+  timeoutMs: 10_000,
+});
+```
+
+`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);
+```
+
+Clean up channels with their page/component. Persist through `from(table)`;
+realtime only notifies peers.
+
+## Compute and analytics
+
+Invoke only functions already deployed through `mortar_migrate`:
+
+```ts
+const response = await mortar.compute.invoke({
+  name: 'summarize',
+  method: 'POST',
+  body: JSON.stringify({ text }),
+  contentType: 'application/json',
+});
+if (!response.ok) throw new Error(await response.text());
+```
+
+Analytics calls are fire-and-forget except `flush`:
+
+```ts
+mortar.analytics.track('pageview', { path: location.pathname });
+mortar.analytics.identify(user.id, { plan: 'free' });
+mortar.analytics.captureError(error, { screen: 'checkout' });
+await mortar.analytics.flush();
+```
+
+## 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.

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@mortar-ai/skill",
+  "version": "0.1.0",
+  "description": "Claude Code skill package for building on Mortar (BaaS). Drop `mortar-skill.md` into ~/.claude/skills/mortar/ to give Claude expert-level guidance about the Mortar SDK / CLI / MCP, tenant isolation + auth.tenant_id() RLS, and the 9 primitive × feature model.",
+  "main": "index.js",
+  "files": ["mortar-skill.md", "index.js", "README.md"],
+  "bin": {
+    "mortar-skill-install": "bin/install.js"
+  },
+  "publishConfig": { "access": "public" },
+  "license": "Apache-2.0"
+}