@raybase/create 0.3.14 → 0.3.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -183,6 +183,20 @@ same `hostApproval` options the app configures (only `normalizeHostAccount` is
183
183
  read): they normalise the account themselves, so any accepted form works, and a
184
184
  value `normalizeHostAccount` rejects throws instead of matching nothing.
185
185
 
186
+ In an app with host partitions (`appConfig.partitions`, one customer's several
187
+ host accounts), every host-account grant is bound to one partition.
188
+ `mcp.hostApproval.partition(hostAccount)` returns that partition's key; by
189
+ default it is the normalized host account, so set it only when the host's
190
+ account id and the partition key differ. The key is stored on the grant and
191
+ its code, pending, and ticket rows and checked again whenever a token
192
+ resolves: a changed mapping, or a partition that is suspended or erased,
193
+ gives 401. The grant's generated table tools and action tools then see only
194
+ that partition's rows plus shared tables, exactly as a host user there would.
195
+ Ordinary member grants have no partition and are refused on partitioned
196
+ tables; Operator MCP reads across partitions or in one named partition.
197
+ In a partitioned app, uninstall calls `suspendRaybasePartition`, which stops
198
+ that partition's grants along with its sign-ins, schedules, and queued work.
199
+
186
200
  ## MCP Apps UI
187
201
 
188
202
  Use the real helpers from `@raybase/core`, not hand-written `_meta` objects:
@@ -54,6 +54,13 @@ action input. Replace hand-bucketed dedupe keys such as
54
54
  `minInterval`. Keep `metadata` small and non-secret. Use `channels` for
55
55
  delivery intent and `target` for navigation/evidence.
56
56
 
57
+ An email shows the title, the body, any further `links: [{ url, label }]`, and
58
+ last the button: `link: { url, label }`, or `target.href` labelled "Open" when
59
+ there is no `link`. Put links in `links`, not as bare URLs in the body: they
60
+ become real links in the HTML part and `label: url` lines in the text part.
61
+ Every `link`/`links` URL must be absolute `http(s)`; `send()` refuses anything
62
+ else.
63
+
57
64
  For a notification that should open a grounded Agent conversation, target an
58
65
  app-owned route using the documented deep-link convention:
59
66
 
@@ -26,3 +26,25 @@ Important constraints:
26
26
  - Old sessions are not migrated; users and API clients must re-authenticate.
27
27
  - App data owner columns should not be rewritten during the core-to-Pro migration.
28
28
  - Multi-org conversion is a separate product and data-model migration.
29
+
30
+ ## Host Partitions And Pro
31
+
32
+ Host partitions (`appConfig.partitions`) are Core's way to serve one
33
+ customer's several host accounts, such as one merchant's stores. They are not
34
+ on Pro yet: Pro refuses `appConfig.partitions`, and its doctor reports
35
+ `partitions-unsupported`. Each Pro customer is already its own organization
36
+ and database.
37
+
38
+ - An app with partitions that gains a Pro signal (unrelated customers, a
39
+ public listing, self-serve sign-up of organizations or trials, per-customer
40
+ billing, plans or seats, per-customer branding, white-label or custom
41
+ domains, customer-managed admins or SSO, or a contractual need for
42
+ per-customer isolation) is a product migration, not an upgrade. Stop and
43
+ recommend Pro with the wording in
44
+ `.agents/skills/raybase-building/references/host-partitions.md`, then plan
45
+ the move with the owner: which customer each partition belongs to, and how
46
+ partitioned rows, shared tables, files, and host-account grants become
47
+ organizations.
48
+ - Do not run `raybase-core-to-pro-single` on an app with partitions; it would
49
+ refuse to start on Pro. Do not drop partitions to make the upgrade pass
50
+ without that product decision.
@@ -70,6 +70,46 @@ Every table and file bucket needs an explicit policy decision for `read`,
70
70
  tables. External login providers belong in `src/raybase.auth.ts` plus
71
71
  `auth.externalProviders`, not the app schema.
72
72
 
73
+ ## Host Partitions And Separate Customers
74
+
75
+ Do not add tenant, customer, organization, store, or account scoping columns
76
+ to app tables. Doctor fails tenant and organization id columns
77
+ (`tenant-column`) and a hand-written `partitionKey` (`partition-column`); the
78
+ rest is on you.
79
+
80
+ - Separate customers (unrelated businesses, a public listing, self-serve
81
+ organizations, per-customer billing, branding, or admins) need Raybase Pro,
82
+ which gives each customer its own database, members, and admins.
83
+ - One customer's several accounts on a host platform that signs people in
84
+ (one merchant's stores, one company's workspaces or sites) use host
85
+ partitions: `appConfig.partitions` plus `hostAuth`. If you cannot tell
86
+ whether the accounts belong to one customer, ask; never turn partitions on
87
+ by guess. In a generated project, the decision rule lives in
88
+ `.agents/skills/raybase-building/references/host-partitions.md`.
89
+ - Keep the spec's `Host partitions:` line (`none`, or `one customer's
90
+ <plural> on <platform>`) aligned with `appConfig.partitions`; doctor checks
91
+ it (`partition-spec`).
92
+
93
+ With partitions on, every table declares `{ partition: "partitioned" }` or
94
+ `{ partition: "shared" }` beside its policies, and none may when they are off
95
+ (`partition-declaration`):
96
+
97
+ - A partitioned table gets a Core-owned `partitionKey` column. Never declare
98
+ it yourself.
99
+ - `unique: true` on a partitioned table means unique per partition.
100
+ - A `ref()` between partitioned tables is a composite foreign key on
101
+ `(partitionKey, id)`, so rows cannot point across partitions. A shared
102
+ table cannot reference a partitioned one (`partition-shared-ref`).
103
+ - Shared tables are visible to every partition. Doctor warns when the plain
104
+ `user` role can write one (`partition-shared-write`), because every host
105
+ user holds that role.
106
+ - Raw SQL reads are not partition-filtered; use the data client.
107
+ - Partitions need a `RAYBASE_BACKUPS` bucket (`partition-backups`), so a
108
+ partition's erasure survives a restore.
109
+ - Partitions start from empty tables: making a table that already holds rows
110
+ partitioned is refused at migration time (locally, reset the data and
111
+ migrate again), and a raw insert without a partition fails.
112
+
73
113
  ## Schema Change Boundaries
74
114
 
75
115
  Invariant: schema changes happen in code and migrations. Do not use raw SQL,
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: raybase-settings
3
- description: Add or review Raybase runtime settings. Use when defining defineSettings(), setting.string/integer/real/boolean/json/enum, app/user/organization setting scopes, admin overrides, ctx.settings usage, built-in AI settings, or deciding what belongs in settings versus config, env, schema, or secrets.
3
+ description: Add or review Raybase runtime settings. Use when defining defineSettings(), setting.string/integer/real/boolean/json/enum, app/user/partition/organization setting scopes, admin overrides, ctx.settings usage, built-in AI settings, or deciding what belongs in settings versus config, env, schema, or secrets.
4
4
  ---
5
5
 
6
6
  # Raybase Settings
@@ -71,13 +71,45 @@ configuration.
71
71
 
72
72
  ## Scopes
73
73
 
74
- - Core supports `app` and `user` scopes in generated apps.
74
+ - Core supports `app` and `user` scopes in generated apps, plus `partition`
75
+ scope in apps with host partitions (`appConfig.partitions`).
75
76
  - `organization` scope is for Raybase Pro. Do not add organization-scoped
76
- settings to Core apps.
77
+ settings to Core apps, and do not use `partition` scope to imitate one:
78
+ partitions are one customer's several host accounts, never separate
79
+ customers.
77
80
  - App settings use subject ID `app` internally.
78
81
  - User settings must be read for the intended user with `ctx.settings` or
79
82
  `getForUser`.
80
83
 
84
+ ### Partition Scope
85
+
86
+ A `scope: "partition"` setting holds one value per host account, such as a
87
+ store's cut-off time or display theme:
88
+
89
+ ```ts
90
+ orderCutoffHour: setting.integer({
91
+ scope: "partition",
92
+ group: "Fulfilment",
93
+ label: "Order cut-off hour",
94
+ default: 15,
95
+ min: 0,
96
+ max: 23
97
+ })
98
+ ```
99
+
100
+ - It resolves partition override, then app override, then the code default,
101
+ so an operator can set one app-wide value and override it for one account.
102
+ - `ctx.settings.get(key)` in an action or job running in one partition
103
+ (`ctx.partition` is `{ kind: "one", key }`) returns that partition's
104
+ effective value.
105
+ - Writes are operator writes by default, in the admin partition picker's
106
+ selected partition. Host users do not change them unless the product adds a
107
+ deliberate, policy-checked action.
108
+ - Declaring `scope: "partition"` with partitions off is an error.
109
+ - Per-account billing, plans, quotas, branding of Raybase surfaces, or admin
110
+ delegation are not settings; an app that needs them per customer needs
111
+ Raybase Pro.
112
+
81
113
  ## Read Settings
82
114
 
83
115
  Use `ctx.settings` from Raybase request/action contexts:
@@ -96,6 +128,28 @@ For user-scoped values:
96
128
  const density = await ctx.settings.getForUser(ctx.user.id, "inboxDensity");
97
129
  ```
98
130
 
131
+ ### A person's own preferences
132
+
133
+ A user-scoped setting declared `permissions: { write: "self" }` is the
134
+ signed-in person's to set for themselves; no other setting is:
135
+
136
+ ```ts
137
+ upkeepEmails: setting.boolean({ scope: "user", default: true, label: "Emails about my apps", permissions: { write: "self" } })
138
+ ```
139
+
140
+ - `GET /api/account/settings` lists the person's own values of those settings.
141
+ - `PATCH /api/account/settings/:key` with `{ "value": ... }` sets one, validated
142
+ as an admin write is; `DELETE /api/account/settings/:key` returns it to the
143
+ default. Both are audited with `by: "self"`.
144
+ - Any other key answers 404. `permissions.roles` narrows who may set it;
145
+ `"self"` on an app- or organization-scoped setting is refused at definition.
146
+ - `ctx.settings.get(key)` in that person's requests reads what they set.
147
+
148
+ For a kind of notification a person may switch off, the app's own action can
149
+ call `setNotificationSubscription(ctx.control, { organizationId: ctx.organizationId, userId: ctx.user.id, kind, enabled: false })`:
150
+ `notifications.send` skips them for that `kind` on every channel and reports
151
+ `reason: "unsubscribed"` in `skipped`.
152
+
99
153
  Prefer reading settings at request/action execution time. Do not bake setting
100
154
  values into module scope constants.
101
155
  Module-scope reads freeze an admin override until the worker reloads and can
@@ -19,7 +19,7 @@ Architecture:
19
19
  - `src/worker-entry.ts` is the Cloudflare Worker entry. It re-exports the TanStack Start default handler, `RaybaseDatabaseObject`, and the generated app's `RaybaseAIChatAgentObject`.
20
20
  - Raybase stores auth, sessions, invites, audit, state, app tables, and declared integration tables in one SQLite Durable Object bound as `RAYBASE_DATA`.
21
21
  - Guide/Agent chat state uses the app-configured `RaybaseAIChatAgentObject` Durable Object bound as `RAYBASE_AI_CHAT_AGENT`; keep the export and binding aligned with `src/raybase.server.ts`.
22
- - Scheduled format-2 backups use `RAYBASE_BACKUPS`, `RAYBASE_BACKUPS_ENABLED=true`, `RAYBASE_BACKUPS_RETAIN=30`, and the daily `0 2 * * *` cron. Run `raybase backups enable` to generate and upload the managed `RAYBASE_BACKUPS_KEY`; never put it in Wrangler `vars`. New archives are envelope-encrypted `.rbb` files and fail closed without a ready provider. Retain historical keys after explicit rotation. Backups include SQLite data and file metadata, not R2 file bytes or Vectorize indexes; plaintext `.sql` is restore-only compatibility input.
22
+ - Scheduled format-2 backups use `RAYBASE_BACKUPS`, `RAYBASE_BACKUPS_ENABLED=true`, `RAYBASE_BACKUPS_RETAIN=30`, and the daily `0 2 * * *` cron. Run `raybase backups enable` to generate and upload the managed `RAYBASE_BACKUPS_KEY`; never put it in Wrangler `vars`. New archives are envelope-encrypted `.rbb` files and fail closed without a ready provider. Retain historical keys after explicit rotation. Backups include SQLite data and file metadata, not R2 file bytes or Vectorize indexes; only encrypted `.rbb` archives restore.
23
23
  - File storage is opt-in. Declare buckets in `src/db/storage.ts`, pass `storage` to `createRaybaseApp`, and bind `RAYBASE_FILES` before using `/api/files`.
24
24
  - Jobs are opt-in. Start from `src/jobs.example.ts`, pass `jobs` to
25
25
  `createRaybaseApp`, keep the queue consumer export, and run `raybase jobs
@@ -88,10 +88,11 @@ Architecture:
88
88
  for action policy, table policy, ownership, invalid input, and invalid state
89
89
  cases. When replacing starter workflows or tables, replace
90
90
  `tests/raybase-patterns.test.ts` instead of leaving todo references behind.
91
- - App tables should model the business domain. Do not add tenant scoping columns to app schema.
92
- - Multi-tenancy, many customer organizations sharing one app, and SSO across apps are Raybase Pro features. Core is single-tenant by design. A Pro upgrade should start as single-mode unless the app owner explicitly requests a multi-tenant product migration.
93
- - `dev/SPEC.md` must contain `Signup mode`, `Cloudflare email capability`, `Auth email features`, `Invite delivery`, and `Password recovery` lines before implementation.
94
- - Default to `Signup mode: invite-only`, `Cloudflare email capability: free-compatible`, `Auth email features: none`, `Invite delivery: admin-shared links`, and `Password recovery: admin-assisted`.
91
+ - App tables should model the business domain. Do not add tenant, customer, or account scoping columns to app schema.
92
+ - Separate customers (unrelated businesses, a public listing, organizations signing themselves up, or per-customer billing, branding, admins, or SSO) need Raybase Pro, which gives each customer its own organization and database. SSO across apps is also Raybase Pro. A Pro upgrade should start as single-mode unless the app owner explicitly requests a multi-tenant product migration.
93
+ - One customer's several accounts on a host platform that signs people in (one merchant's stores, one company's workspaces or sites) use host partitions: `appConfig.partitions` with `hostAuth`, and every table declared `partitioned` or `shared`. Read `.agents/skills/raybase-building/references/host-partitions.md` first. If you cannot tell whether the accounts belong to one customer, ask; never turn partitions on by guess.
94
+ - `dev/SPEC.md` must contain `Signup mode`, `Cloudflare email capability`, `Auth email features`, `Invite delivery`, `Password recovery`, and `Host partitions` lines before implementation.
95
+ - Default to `Signup mode: invite-only`, `Cloudflare email capability: free-compatible`, `Auth email features: none`, `Invite delivery: admin-shared links`, `Password recovery: admin-assisted`, and `Host partitions: none`. An app for one customer's host accounts says `Host partitions: one customer's <plural> on <platform>`, for example `Host partitions: one customer's stores on Shopify`.
95
96
  - Public signup is controlled by `appConfig.auth.signupMode`, not `auth.publicRoutes`. Use `"public"` for provider and password signup, or `"provider-only"` for provider signup with the password door closed. Both create normal `user` users only; password sign-in stays available to existing accounts, and Raybase `/admin` remains invite/operator-only.
96
97
  - Password-based public signup, password reset, emailed invites, welcome email, and magic links require owner-confirmed Workers Paid plus Cloudflare Email Sending/domain onboarding and `Cloudflare email capability: transactional-email`. Provider-only signup needs no auth email because the provider verifies the email.
97
98
  - Cloudflare verified destination addresses are only for operator/admin notifications or intentional test sends; do not treat them as user verification, password reset, invite email, magic-link auth, or public signup.
@@ -12,6 +12,7 @@ The generated product is a public content site with a private editorial door. Op
12
12
  ## Access
13
13
 
14
14
  Signup mode: invite-only
15
+ Host partitions: none
15
16
  Cloudflare email capability: free-compatible
16
17
  Auth email features: none
17
18
  Invite delivery: admin-shared links
@@ -24,6 +25,13 @@ self-signup` with `auth.signupMode: "provider-only"`. Both public modes create
24
25
  normal `user` users only; password sign-in stays available to existing accounts,
25
26
  and Raybase `/admin` remains invite/operator-only.
26
27
 
28
+ `Host partitions: none` means the app serves one customer through Raybase's
29
+ own sign-in. An app inside a host platform that serves one customer's several
30
+ accounts there says `Host partitions: one customer's <plural> on <platform>`
31
+ (for example `Host partitions: one customer's stores on Shopify`) and sets
32
+ `appConfig.partitions`. Separate customers are never partitions; they need
33
+ Raybase Pro.
34
+
27
35
  Raybase app roles map into EmDash roles through the `raybaseAuth()` config in `site/astro.config.mjs`. The mapping lives on the site's side of the handoff: the spine only states which roles the editor holds.
28
36
 
29
37
  ## Public Surface / Documentation
@@ -19,11 +19,14 @@ Architecture:
19
19
  - Raybase owns sign-in, owner setup, invites and the admin panel. App routes read the signed-in user with `currentUser(request, env, ctx)` from `app/raybase.server.ts` and redirect to `/login?next=…` when there is none.
20
20
  - `/docs` is a React Router docs site; search is served at `/docs/api/search`, not `/api/search`, because Raybase owns `/api` ahead of the router.
21
21
  - Raybase stores auth, sessions, invites, audit, state and app tables in one SQLite Durable Object bound as `RAYBASE_DATA`. All control tables are runtime-ensured; there is no manual database setup.
22
- - Scheduled format-2 backups use `RAYBASE_BACKUPS`, `RAYBASE_BACKUPS_ENABLED=true`, `RAYBASE_BACKUPS_RETAIN=30`, and the daily `0 2 * * *` cron. Run `raybase backups enable` to generate and upload the managed `RAYBASE_BACKUPS_KEY`; never put it in Wrangler `vars`. New archives are envelope-encrypted `.rbb` files and fail closed without a ready provider. Retain historical keys after explicit rotation. Backups include Raybase SQLite data and file metadata, not R2 file bytes or Vectorize indexes; plaintext `.sql` is restore-only compatibility input.
22
+ - Scheduled format-2 backups use `RAYBASE_BACKUPS`, `RAYBASE_BACKUPS_ENABLED=true`, `RAYBASE_BACKUPS_RETAIN=30`, and the daily `0 2 * * *` cron. Run `raybase backups enable` to generate and upload the managed `RAYBASE_BACKUPS_KEY`; never put it in Wrangler `vars`. New archives are envelope-encrypted `.rbb` files and fail closed without a ready provider. Retain historical keys after explicit rotation. Backups include Raybase SQLite data and file metadata, not R2 file bytes or Vectorize indexes; only encrypted `.rbb` archives restore.
23
23
  - App-owned tables are declared in `app/db/schema.ts` (Raybase policy vocabulary) and managed by `raybase migrate`, which compiles `app/db/migrations.gen.ts`; never edit that file by hand.
24
+ - App tables should model the business domain. Do not add tenant, customer, or account scoping columns to app schema.
25
+ - Separate customers (unrelated businesses, a public listing, organizations signing themselves up, or per-customer billing, branding, admins, or SSO) need Raybase Pro, which gives each customer its own organization and database. SSO across apps is also Raybase Pro. A Pro upgrade should start as single-mode unless the app owner explicitly requests a multi-tenant product migration.
26
+ - One customer's several accounts on a host platform that signs people in (one merchant's stores, one company's workspaces or sites) use host partitions: `appConfig.partitions` with `hostAuth`, and every table declared `partitioned` or `shared`. Read `.agents/skills/raybase-building/references/host-partitions.md` first. If you cannot tell whether the accounts belong to one customer, ask; never turn partitions on by guess.
24
27
  - UI uses the small Tailwind kit in `app/components/ui/`; its tokens live in `app/app.css`.
25
- - `dev/SPEC.md` must contain `Signup mode`, `Cloudflare email capability`, `Auth email features`, `Invite delivery`, and `Password recovery` lines before implementation.
26
- - Default to `Signup mode: invite-only`, `Cloudflare email capability: free-compatible`, `Auth email features: none`, `Invite delivery: admin-shared links`, and `Password recovery: admin-assisted`.
28
+ - `dev/SPEC.md` must contain `Signup mode`, `Cloudflare email capability`, `Auth email features`, `Invite delivery`, `Password recovery`, and `Host partitions` lines before implementation.
29
+ - Default to `Signup mode: invite-only`, `Cloudflare email capability: free-compatible`, `Auth email features: none`, `Invite delivery: admin-shared links`, `Password recovery: admin-assisted`, and `Host partitions: none`. An app for one customer's host accounts says `Host partitions: one customer's <plural> on <platform>`, for example `Host partitions: one customer's stores on Shopify`.
27
30
  - Public signup is controlled by `appConfig.auth.signupMode`, not `auth.publicRoutes`: `"public"` opens provider and password signup, while `"provider-only"` opens provider signup and closes password signup. Both create normal `user` users only; password sign-in stays available to existing accounts, and Raybase `/admin` remains invite/operator-only.
28
31
  - Business and mutating actions need focused tests. Use `@raybase/core/test`
29
32
  when adding Raybase user-facing workflows, and replace starter tests when
@@ -1,7 +1,7 @@
1
1
  // Raybase runs in the same worker as the React Router app: workers/app.ts
2
2
  // routes Raybase's own paths here (the admin panel, its API, sign-in, setup
3
3
  // and invite pages, MCP) and everything else to React Router.
4
- import { createRaybaseApp, isRaybaseAdminPanelRequestDisabled } from "@raybase/core/worker";
4
+ import { createRaybaseApp, isRaybaseAdminPanelRequestDisabled, raybaseRequestPath } from "@raybase/core/worker";
5
5
  import type { RaybaseEnv } from "@raybase/core/worker";
6
6
  import { docsModule } from "@raybase/docs";
7
7
  import { appMigrations } from "./db/migrations.gen";
@@ -34,9 +34,10 @@ export class RaybaseAIChatAgentObject extends raybase.RaybaseAIChatAgentObject {
34
34
  const raybasePathPrefixes = ["/admin", "/api", "/login", "/signup", "/setup", "/invite", "/forgot-password", "/reset-password", "/verify-email", "/mcp", "/.well-known"];
35
35
 
36
36
  export function isRaybaseRequest(url: URL): boolean {
37
- return raybasePathPrefixes.some(
38
- (prefix) => url.pathname === prefix || url.pathname.startsWith(`${prefix}/`)
39
- );
37
+ // The path as Raybase's router reads it, percent-encodings decoded, so an
38
+ // encoded "/%61pi/..." reaches Raybase (which refuses it) and not the app.
39
+ const path = raybaseRequestPath(url);
40
+ return raybasePathPrefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
40
41
  }
41
42
 
42
43
  export function isDisabledRaybaseAdminRequest(request: Request): boolean {
@@ -16,6 +16,7 @@ Security default: this is an internal app. Only invited users can sign in, and u
16
16
  ## Access
17
17
 
18
18
  Signup mode: invite-only
19
+ Host partitions: none
19
20
  Cloudflare email capability: free-compatible
20
21
  Auth email features: none
21
22
  Invite delivery: admin-shared links
@@ -28,6 +29,13 @@ self-signup` with `auth.signupMode: "provider-only"`. Both public modes
28
29
  create normal `user` users only; password sign-in stays available to existing
29
30
  accounts, and Raybase `/admin` remains invite/operator-only.
30
31
 
32
+ `Host partitions: none` means the app serves one customer through Raybase's
33
+ own sign-in. An app inside a host platform that serves one customer's several
34
+ accounts there says `Host partitions: one customer's <plural> on <platform>`
35
+ (for example `Host partitions: one customer's stores on Shopify`) and sets
36
+ `appConfig.partitions`. Separate customers are never partitions; they need
37
+ Raybase Pro.
38
+
31
39
  The default Cloudflare email capability is Free-compatible: Raybase generates
32
40
  single-use setup and invite links, but admins copy and share invite links
33
41
  manually. There is no self-service password reset, magic-link/passwordless
@@ -19,7 +19,7 @@ Architecture:
19
19
  - `src/worker-entry.ts` is the Cloudflare Worker entry. It re-exports the TanStack Start default handler, `RaybaseDatabaseObject`, and the generated app's `RaybaseAIChatAgentObject`.
20
20
  - Raybase stores auth, sessions, invites, audit, state, app tables, and declared integration tables in one SQLite Durable Object bound as `RAYBASE_DATA`.
21
21
  - Guide/Agent chat state uses the app-configured `RaybaseAIChatAgentObject` Durable Object bound as `RAYBASE_AI_CHAT_AGENT`; keep the export and binding aligned with `src/raybase.server.ts`.
22
- - Scheduled format-2 backups use `RAYBASE_BACKUPS`, `RAYBASE_BACKUPS_ENABLED=true`, `RAYBASE_BACKUPS_RETAIN=30`, and the daily `0 2 * * *` cron. Run `raybase backups enable` to generate and upload the managed `RAYBASE_BACKUPS_KEY`; never put it in Wrangler `vars`. New archives are envelope-encrypted `.rbb` files and fail closed without a ready provider. Retain historical keys after explicit rotation. Backups include SQLite data and file metadata, not R2 file bytes or Vectorize indexes; plaintext `.sql` is restore-only compatibility input.
22
+ - Scheduled format-2 backups use `RAYBASE_BACKUPS`, `RAYBASE_BACKUPS_ENABLED=true`, `RAYBASE_BACKUPS_RETAIN=30`, and the daily `0 2 * * *` cron. Run `raybase backups enable` to generate and upload the managed `RAYBASE_BACKUPS_KEY`; never put it in Wrangler `vars`. New archives are envelope-encrypted `.rbb` files and fail closed without a ready provider. Retain historical keys after explicit rotation. Backups include SQLite data and file metadata, not R2 file bytes or Vectorize indexes; only encrypted `.rbb` archives restore.
23
23
  - File storage is opt-in. Declare buckets in `src/db/storage.ts`, pass `storage` to `createRaybaseApp`, and bind `RAYBASE_FILES` before using `/api/files`.
24
24
  - Jobs are opt-in. Start from `src/jobs.example.ts`, pass `jobs` to
25
25
  `createRaybaseApp`, keep the queue consumer export, and run `raybase jobs
@@ -63,10 +63,11 @@ Architecture:
63
63
  for action policy, table policy, ownership, invalid input, and invalid state
64
64
  cases. When replacing starter workflows or tables, replace
65
65
  `tests/raybase-patterns.test.ts` instead of leaving todo references behind.
66
- - App tables should model the business domain. Do not add tenant scoping columns to app schema.
67
- - Multi-tenancy, many customer organizations sharing one app, and SSO across apps are Raybase Pro features. Core is single-tenant by design. A Pro upgrade should start as single-mode unless the app owner explicitly requests a multi-tenant product migration.
68
- - `dev/SPEC.md` must contain `Signup mode`, `Cloudflare email capability`, `Auth email features`, `Invite delivery`, and `Password recovery` lines before implementation.
69
- - Default to `Signup mode: invite-only`, `Cloudflare email capability: free-compatible`, `Auth email features: none`, `Invite delivery: admin-shared links`, and `Password recovery: admin-assisted`.
66
+ - App tables should model the business domain. Do not add tenant, customer, or account scoping columns to app schema.
67
+ - Separate customers (unrelated businesses, a public listing, organizations signing themselves up, or per-customer billing, branding, admins, or SSO) need Raybase Pro, which gives each customer its own organization and database. SSO across apps is also Raybase Pro. A Pro upgrade should start as single-mode unless the app owner explicitly requests a multi-tenant product migration.
68
+ - One customer's several accounts on a host platform that signs people in (one merchant's stores, one company's workspaces or sites) use host partitions: `appConfig.partitions` with `hostAuth`, and every table declared `partitioned` or `shared`. Read `.agents/skills/raybase-building/references/host-partitions.md` first. If you cannot tell whether the accounts belong to one customer, ask; never turn partitions on by guess.
69
+ - `dev/SPEC.md` must contain `Signup mode`, `Cloudflare email capability`, `Auth email features`, `Invite delivery`, `Password recovery`, and `Host partitions` lines before implementation.
70
+ - Default to `Signup mode: invite-only`, `Cloudflare email capability: free-compatible`, `Auth email features: none`, `Invite delivery: admin-shared links`, `Password recovery: admin-assisted`, and `Host partitions: none`. An app for one customer's host accounts says `Host partitions: one customer's <plural> on <platform>`, for example `Host partitions: one customer's stores on Shopify`.
70
71
  - Public signup is controlled by `appConfig.auth.signupMode`, not `auth.publicRoutes`. Use `"public"` for provider and password signup, or `"provider-only"` for provider signup with the password door closed. Both create normal `user` users only; password sign-in stays available to existing accounts, and Raybase `/admin` remains invite/operator-only.
71
72
  - Password-based public signup, password reset, emailed invites, welcome email, and magic links require owner-confirmed Workers Paid plus Cloudflare Email Sending/domain onboarding and `Cloudflare email capability: transactional-email`. Provider-only signup needs no auth email because the provider verifies the email.
72
73
  - Cloudflare verified destination addresses are only for operator/admin notifications or intentional test sends; do not treat them as user verification, password reset, invite email, magic-link auth, or public signup.
@@ -35,6 +35,7 @@ concerns.
35
35
  ## Access
36
36
 
37
37
  Signup mode: invite-only
38
+ Host partitions: none
38
39
  Cloudflare email capability: free-compatible
39
40
  Raybase hosted auth: disabled
40
41
  Claim methods: passkey-plus-password
@@ -50,6 +51,13 @@ self-signup` with `auth.signupMode: "provider-only"`. Both public modes create
50
51
  normal `user` users only; password sign-in stays available to existing accounts,
51
52
  and Raybase `/admin` remains invite/operator-only.
52
53
 
54
+ `Host partitions: none` means the app serves one customer through Raybase's
55
+ own sign-in. An app inside a host platform that serves one customer's several
56
+ accounts there says `Host partitions: one customer's <plural> on <platform>`
57
+ (for example `Host partitions: one customer's stores on Shopify`) and sets
58
+ `appConfig.partitions`. Separate customers are never partitions; they need
59
+ Raybase Pro.
60
+
53
61
  The default Cloudflare email capability is Free-compatible: Raybase generates
54
62
  single-use setup and invite links, but admins copy and share invite links
55
63
  manually. There is no self-service password reset, magic-link/passwordless