weroperking · weroperking · Mar 30, 2026 · Mar 30, 2026
diff --git a/CODEBASE_MAP.md b/CODEBASE_MAP.md
@@ -1,6 +1,16 @@
 # BetterBase — Codebase Map
 
-> Last updated: 2026-03-29
+> Last updated: 2026-03-30
+
+## Canonical Orientation Files
+
+Use these as the official project index set:
+
+1. `NOTICE.md` — backbone summary and navigation entry point.
+2. `README.md` — product overview and onboarding.
+3. `CODEBASE_MAP.md` — architecture and package map (this file).
+4. `docs/README.md` — complete documentation map.
+5. `docs/guides/provider-capabilities-and-rollout.md` — provider limitations and rollout strategy.
 
 ## What is BetterBase?
 
@@ -2100,4 +2110,3 @@ All notable changes to BetterBase will be documented in this file.
 ## License
 
 BetterBase is released under the MIT license.
-
diff --git a/NOTICE.md b/NOTICE.md
@@ -0,0 +1,110 @@
+# BetterBase Notice / Backbone Index
+
+> Last updated: 2026-03-30
+
+This is the **backbone file** for the BetterBase repository.
+It gives owners, contributors, and agents a single entry point to understand the project and navigate quickly.
+
+---
+
+## 1) What BetterBase Is
+
+BetterBase is an AI-native Backend-as-a-Service platform built as a monorepo.
+It provides database APIs, auth, realtime, storage, webhooks, functions, and IaC workflows with Bun-first tooling.
+
+---
+
+## 2) Canonical Project Entry Points
+
+Read these in order:
+
+1. [`README.md`](./README.md) — product overview and quick start.
+2. [`CODEBASE_MAP.md`](./CODEBASE_MAP.md) — detailed architecture and package map.
+3. [`docs/README.md`](./docs/README.md) — complete docs navigation.
+4. [`docs/guides/provider-capabilities-and-rollout.md`](./docs/guides/provider-capabilities-and-rollout.md) — provider limitations + rollout strategy.
+5. [`SELF_HOSTED.md`](./SELF_HOSTED.md) — self-host deployment playbook.
+
+---
+
+## 3) Repository Index (Top-Level)
+
+- `apps/` — runnable applications (dashboard).
+- `packages/` — core libraries (`core`, `client`, `shared`, etc.).
+- `docs/` — end-user and developer documentation.
+- `templates/` — starter templates.
+- `docker-compose*.yml` / `Dockerfile*` — runtime and deployment definitions.
+- `README.md` / `CODEBASE_MAP.md` / `NOTICE.md` — core orientation docs.
+
+---
+
+## 4) Multi-Tenant Provider Limitations (Must Read)
+
+Provider capabilities are **not identical**. Multi-tenant behavior must be adapted per provider.
+
+### Current provider limitations snapshot
+
+| Provider | Tenant isolation model | RLS | Branching in core | CDC/event behavior | Notes |
+|---|---|---|---|---|---|
+| Postgres | DB-native + app guardrails | ✅ | ✅ | ✅ LISTEN/NOTIFY | Best baseline for strict tenancy |
+| Neon | DB-native + app guardrails | ✅ | ✅ | ⚠️ limited/polling fallback | Use external CDC connectors for high-fidelity streams |
+| Supabase | DB-native + app guardrails | ✅ | ✅ | ✅ LISTEN/NOTIFY | Postgres-compatible model |
+| Turso | App-enforced tenancy | ❌ | ❌ | ✅ SQL heuristic CDC wrapper | Enforce strict tenant filters in API |
+| PlanetScale | App-enforced tenancy | ❌ | ❌ | ❌ no-op callback | Enforce strict tenant filters + scoped writes |
+| Managed | N/A | N/A | N/A | N/A | Placeholder; not available yet |
+
+### Mandatory handling rules
+
+1. API-first capabilities (UI must consume API, not create UI-only behavior).
+2. If provider has no native RLS, enforce tenant guardrails at application/API layer.
+3. Block unscoped writes in strict multi-tenant mode.
+4. Surface limitation warnings in both docs and UI.
+5. Use provider-specific rollout sequencing based on capability gaps.
+
+Canonical guide:
+
+- [`docs/guides/provider-capabilities-and-rollout.md`](./docs/guides/provider-capabilities-and-rollout.md)
+
+---
+
+## 5) Documentation Ownership Rules
+
+When behavior changes in code, update at least:
+
+- `README.md` (if product-facing behavior changed)
+- `CODEBASE_MAP.md` (if architecture/package map changed)
+- Relevant guide(s) in `docs/`
+- `NOTICE.md` if entry points or backbone structure changed
+
+---
+
+## 6) API and Dashboard Parity Rule
+
+Any new feature that can be configured in Dashboard must also be available via API.
+Dashboard acts as an API client, not a separate source of truth.
+
+---
+
+## 7) Queue / Background Workflow Limitations
+
+BetterBase currently documents and integrates background workflows around **Inngest**.
+
+- Preferred queue/workflow path: Inngest-backed jobs and event workflows.
+- Self-hosted and local options are available through Inngest runtime configuration.
+- There is currently no first-class Laravel Queue adapter documented in this repository.
+
+Handling guidance:
+
+1. For Laravel-based systems, integrate using HTTP/webhook/event bridge patterns first.
+2. Require idempotency keys and retry-safe handlers across queue boundaries.
+3. Keep queue configuration API-driven and documented per provider environment.
+
+---
+
+## 8) Current Snapshot Notice
+
+This file is an orientation index, not a replacement for detailed docs.
+For implementation details and current constraints, always verify against:
+
+- `packages/*` source
+- `docs/core/*`
+- `docs/guides/provider-capabilities-and-rollout.md`
diff --git a/README.md b/README.md
@@ -17,12 +17,30 @@ Blazing-fast backend development with Sub-100ms Local Dev — Built on Bun + SQL
 
 *Database • Authentication • Realtime Subscriptions • Storage • Serverless Functions • Vector Search*
 
-**Last Updated: 2026-03-29**
+**Last Updated: 2026-03-30**
 
 </div>
 
 ---
 
+## Project Backbone (Start Here)
+
+If you want the fastest path to understanding this repository, start with these files:
+
+1. [`NOTICE.md`](./NOTICE.md) — project backbone, index, and provider limitation notice.
+2. [`CODEBASE_MAP.md`](./CODEBASE_MAP.md) — package/module map and architecture details.
+3. [`docs/README.md`](./docs/README.md) — full documentation index.
+4. [`docs/guides/provider-capabilities-and-rollout.md`](./docs/guides/provider-capabilities-and-rollout.md) — provider limitations and rollout plan.
+
+### Provider Rollout Status
+
+BetterBase supports multiple providers, but capabilities vary by provider (RLS, branching, CDC, GraphQL).
+Use the rollout guide before implementing tenant isolation or provider-specific features:
+
+- [Provider Capabilities, Limitations, and Rollout Plan](./docs/guides/provider-capabilities-and-rollout.md)
+
+---
+
 ## Why Choose Betterbase?
 
 ```
@@ -644,4 +662,4 @@ SOFTWARE.
 
 [Website](#) • [Documentation](docs/README.md) • [Discord](https://discord.gg/R6Dm6Cgy2E) • [GitHub](https://github.com/weroperking/Betterbase) • [Twitter](#)
 
-</div>
+</div>
diff --git a/docs/README.md b/docs/README.md
@@ -35,7 +35,8 @@ The documentation is organized into logical sections for easy navigation:
 │   ├── production-checklist.md
 │   ├── monitoring.md
 │   ├── scaling.md
-│   └── security-best-practices.md
+│   ├── security-best-practices.md
+│   └── provider-capabilities-and-rollout.md
 ├── api-reference/             # API documentation
 │   ├── client-sdk.md
 │   ├── cli-commands.md
@@ -101,6 +102,7 @@ Development guides for production:
 - [Monitoring](./guides/monitoring.md) - Set up logging and metrics
 - [Scaling](./guides/scaling.md) - Scale your application
 - [Security Best Practices](./guides/security-best-practices.md) - Security hardening
+- [Provider Capabilities & Rollout](./guides/provider-capabilities-and-rollout.md) - Provider limitations and implementation plan
 
 ## API Reference
 
@@ -202,4 +204,4 @@ bb login --url https://your-instance.com
 
 This documentation is part of the BetterBase platform and is licensed under the MIT License.
 
-© 2026 BetterBase LLC. All rights reserved.
+© 2026 BetterBase LLC. All rights reserved.