docs: close week-of doc gaps — os publish removal, RLS current_user, search, authz, SDUI styling, dataset joins, package-first (#2338)

Audit of ~1 week of changes (298 commits, 3 breaking, 20 new ADRs) surfaced
hand-written docs that were stale or missing. All shapes verified against the
current spec/CLI.

P1 — docs were WRONG:
- os publish / os rollback removed (#2237): rewrite publish-and-preview around
  `os package publish`; fix cloud-deployment, cloud-artifact-api, protocol
  objectos/objectql docs, README, platform skill (migration `os rollback` is gone
  too — migrate is plan/apply, forward-only).
- RLS current_user (ADR-0068): permission.mdx + core-concepts dropped the removed
  singular `current_user.role` / `current_user.region`; `roles` is a string array.
- sharingModel enum (ADR-0055/0056): object.mdx adds public_read /
  public_read_write / controlled_by_parent + legacy aliases.

P2 — shipped but undocumented:
- Record search (ADR-0061): data-modeling — `searchableFields` + `$search`.
- Unified authz (ADR-0066): security — `sys_capability` registry, object `access`
  posture, object `requiredPermissions`.
- SDUI styling (ADR-0065): page.mdx — `responsiveStyles` (preferred channel).
- Dataset multi-hop joins (ADR-0071): analytics-datasets — dotted paths, <=3 hops,
  to-one only.
- Package-first authoring (ADR-0070): metadata-lifecycle — writable-base contract.

P3:
- Built-in identity roles (ADR-0068) in security; per-env @better-auth/sso +
  `features.sso` note in auth-sso (ADR-0069).
- Status-header correction on ADR-0061 / ADR-0071 (code shipped; headers lagged).

Docs-only. Build Docs CI validates MDX.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

README.md

@@ -177,7 +177,7 @@ os doctor         # Check environment health
 os explain        # Explain protocol concepts on the command line
 ```
 
-Cloud, package registry, and environment management subcommands (`os publish`, `os rollback`, `os package`, `os login`, `os whoami`, `os cloud …`) are available when targeting an ObjectStack Cloud control plane.
+Cloud, package registry, and environment management subcommands (`os package publish`, `os package install`, `os login`, `os whoami`, `os environments`, `os cloud …`) are available when targeting an ObjectStack Cloud control plane.
 
 ## Use the generated API
 

content/docs/concepts/cloud-artifact-api.mdx

@@ -37,14 +37,15 @@ caches.
 }
 ```
 
-The CLI command is:
+This control-plane endpoint is driven by the Cloud / Marketplace install flow.
+The framework CLI publishes through the package catalog:
 
 ```bash
-OS_CLOUD_URL=https://cloud.example.com \
-OS_ENVIRONMENT_ID=env_prod \
-os publish
+os package publish ./dist/objectstack.json --env env_prod --install
 ```
 
+(The legacy direct-to-environment `os publish` CLI was removed — #2237.)
+
 ---
 
 ## Activate revision endpoint
@@ -57,11 +58,9 @@ Activating a revision changes the environment's current artifact pointer.
 Runtime nodes can then reload or refresh their environment kernel based on the
 new commit/checksum.
 
-```bash
-OS_CLOUD_URL=https://cloud.example.com \
-OS_ENVIRONMENT_ID=env_prod \
-os rollback --commit 9ce1bd48dd7022b8
-```
+Revision activation is a Cloud control-plane operation. The framework `os rollback`
+CLI was removed (#2237); to change an environment's active artifact, install the
+desired package version into it.
 
 ---
 

content/docs/concepts/metadata-lifecycle.mdx

@@ -76,6 +76,20 @@ The `seq` is the single source of truth for ordering. The Studio status badge (`
 
 ---
 
+## Package-first authoring (ADR-0070)
+
+Every runtime-authored item lives inside a **writable package** — there are no
+orphans. Code-defined and installed packages are **read-only** at runtime, so the
+first step of any Studio/API authoring action is to target a *writable* package (a
+"base"): a create/update aimed at a read-only package is rejected, and the author
+is asked to pick or create a writable base first. New objects, fields, views, and
+flows are namespaced into that package — which is exactly what `os package publish`
+later ships. See [ADR-0070](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0070-package-first-authoring.md).
+
+> Note: "package" here is the runtime **authoring base** (a `package_id`-bearing
+> container of metadata), distinct from the npm `@objectstack/*` packages listed in
+> the repo README.
+
 ## Overlay whitelist (shared-DB tenancy invariant)
 
 In shared-database multi-tenancy, **most metadata types must not be per-org customizable** — overriding them would break the physical schema. The whitelist lives in **one** place: `MetadataTypeRegistryEntry.allowOrgOverride` in `packages/spec/src/kernel/metadata-plugin.zod.ts`.

content/docs/getting-started/core-concepts.mdx

@@ -137,7 +137,7 @@ This ensures ObjectStack apps can run on Node.js + PostgreSQL today, Python + SQ
 | **Engine** | Enforces the logic | Compiles the `using` condition into a SQL `WHERE` clause |
 
 <Callout type="info">
-CRUD permissions (`allowRead`, `allowEdit`, …) are simple booleans — they grant or deny an operation. Record-level *conditional* access is a separate mechanism: [Row-Level Security](/docs/getting-started/architecture) policies, whose `using` clause is a SQL-like (PostgreSQL-compatible) predicate over context variables such as `current_user.role` and `current_user.id`.
+CRUD permissions (`allowRead`, `allowEdit`, …) are simple booleans — they grant or deny an operation. Record-level *conditional* access is a separate mechanism: [Row-Level Security](/docs/getting-started/architecture) policies, whose `using` clause is a SQL-like (PostgreSQL-compatible) predicate over context variables such as `current_user.roles` and `current_user.id`.
 </Callout>
 
 ### Single Source of Truth

content/docs/guides/analytics-datasets.mdx

@@ -135,6 +135,11 @@ capability the inline single-object query could never reach:
 // → revenue by account.region, joined + RLS-enforced per object.
 ```
 
+Joins follow **dotted relationship paths** and may traverse **multiple to-one hops**
+(ADR-0071) — e.g. `account.owner.region` walks the chain order → account → owner →
+region. The path is capped at **3 join hops (4 objects)** and is **to-one only**;
+to-many traversal is rejected (aggregate the many-side as its own measure instead).
+
 ## How it runs
 
 A dataset compiles to the **Cube analytics runtime** (`IAnalyticsService`). The

content/docs/guides/auth-sso.mdx

@@ -113,6 +113,12 @@ Enterprise packages can pass `oidcProviders` into `@objectstack/plugin-auth`
 or contribute them through `auth:configure`. The open-source package does not
 ship a generic OIDC settings UI.
 
+> **Per-environment external IdP (ADR-0069).** Recent releases add a
+> per-environment external-IdP path built on `@better-auth/sso` (a generic OIDC
+> relying party) and surface an `sso` flag in the public `/auth/config`
+> (`features.sso`) so a client can show an enterprise-login button when SSO is
+> configured. The `oidcProviders` extension below remains the in-process path.
+
 ### Quick start — Okta
 
 ```ts

content/docs/guides/cloud-deployment.mdx

@@ -84,18 +84,11 @@ request — no restart, and no environment id to remember.
 > install in one call: `os package publish --env <id> --install`. This is for
 > automation only — interactive installs happen in the environment Marketplace.
 
-> **Legacy env-revision path.** `os publish` posts compiled metadata straight to
-> an environment as a revision, rather than as a versioned package:
->
-> ```bash
-> OS_CLOUD_URL=https://cloud.example.com OS_ENVIRONMENT_ID=env_prod os publish
-> # POST /api/v1/cloud/environments/:environment/metadata
-> # rollback: POST /api/v1/cloud/environments/:environment/revisions/:commit/activate
-> ```
->
-> It still works, but the package flow above is the direction of travel
-> (ADR-0006 v4): `sys_environment_revision` is retired once all publishes go
-> through the package endpoints.
+> **Removed: the legacy env-revision path.** The direct-to-environment `os publish`
+> / `os rollback` commands (which wrote `sys_environment_revision`) were **removed**
+> (#2237, ADR-0006 v4). All publishing now goes through the package flow above
+> (`os package publish`); to change what an environment runs, install a package
+> version into it.
 
 Cloud control-plane hosts, database provisioning, billing, and public SaaS
 deployment are outside this framework repository. The framework runtime exposes

content/docs/guides/data-modeling.mdx

@@ -97,6 +97,28 @@ enable: {
 
 ---
 
+### Global search — `searchable` + `searchableFields`
+
+`searchable: true` includes an object's records in global search and the record
+picker. By default the search matches the name/title field plus short-text fields.
+To control exactly which fields are matched, set `searchableFields` on the object
+(ADR-0061):
+
+```typescript
+{
+  name: 'account',
+  searchable: true,
+  searchableFields: ['name', 'website', 'billing_city'],
+}
+```
+
+Queries then use the `$search` filter operator to match across `searchableFields`
+(e.g. `{ filters: { $search: 'acme' } }`); a view may narrow the set with
+`$searchFields`. When `searchableFields` is unset, search falls back to the
+name/title field plus short-text fields.
+
+---
+
 ## Field Types & Configuration
 
 ### Text Fields

content/docs/guides/metadata/object.mdx

@@ -203,7 +203,7 @@ indexes: [
 | `active` | `boolean` | Is object active (default: `true`) |
 | `isSystem` | `boolean` | System object, protected from deletion (default: `false`) |
 | `abstract` | `boolean` | Abstract base, cannot be instantiated (default: `false`) |
-| `sharingModel` | `enum` | `'private'`, `'read'`, `'read_write'`, `'full'` |
+| `sharingModel` | `enum` | Org-Wide Default record visibility (ADR-0055/0056). Canonical: `'private'`, `'public_read'`, `'public_read_write'`, `'controlled_by_parent'` (detail visibility derived from its master). Legacy aliases: `'read'`=public_read, `'read_write'`/`'full'`=public_read_write |
 | `keyPrefix` | `string` | Short prefix for record IDs (e.g. `'001'`) |
 | `recordTypes` | `string[]` | Record type names for this object |
 | `validations` | `ValidationRule[]` | Object-level validation rules (see [Validation](./validation)) |

content/docs/guides/metadata/page.mdx

@@ -136,6 +136,7 @@ Components are the building blocks placed inside regions.
 | `events` | `Record<string, string>` | optional | Event handlers (action expressions) |
 | `style` | `object` | optional | CSS styles |
 | `className` | `string` | optional | CSS class names |
+| `responsiveStyles` | `object` | optional | **Preferred** SDUI styling channel (ADR-0065): per-breakpoint scoped CSS-property maps keyed by `xs`/`sm`/`md`/`lg`/`xl`/`2xl`, compiled to id-scoped CSS at render. Prefer design tokens, e.g. `{ base: { padding: 'var(--space-6)' }, md: { padding: 'var(--space-8)' } }`. Use over ad-hoc `style`/`className` for metadata-authored pages. |
 | `visibility` | `string` | optional | Visibility predicate (CEL expression) |
 
 The `type` field is a union of the standard `PageComponentType` enum and any custom string. The standard (namespaced) component types include: