fix(ci): add @types/node and revise customer docs against framework

- Install @types/node in apps/objectos so tsc --noEmit can compile
  objectstack.config.ts (uses process.env). Fixes CI type-check failure.
- Cross-check customer docs against ../framework source:
  - kubernetes probes use built-in /health endpoint
  - split auth callback paths: social /callback/<p> vs OIDC /oauth2/callback/<p>
  - permission-set grants use real flags (allowRead/allowCreate/allowEdit/
    allowDelete/viewAllRecords/modifyAllRecords)
  - env-var reference adds OS_ARTIFACT_PATH, OS_ENVIRONMENT_ID,
    OS_ORGANIZATION_ID, OS_MULTI_TENANT, OS_RUNTIME_PORT, OS_DATABASE_*,
    OS_BUSINESS_DB_URL, OS_CACHE_DIR, OS_SKIP_SCHEMA_SYNC
  - clarify OS_ARTIFACT_FILE (wrapper) vs OS_ARTIFACT_PATH (framework)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: hotlong

apps/objectos/package.json

@@ -12,17 +12,18 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@objectstack/runtime": "^5.2.0",
-    "@objectstack/core": "^5.2.0",
-    "@objectstack/spec": "^5.2.0",
-    "@objectstack/metadata": "^5.2.0",
-    "@objectstack/objectql": "^5.2.0",
     "@objectstack/cli": "^5.2.0",
+    "@objectstack/core": "^5.2.0",
     "@objectstack/driver-memory": "^5.2.0",
     "@objectstack/driver-sql": "^5.2.0",
-    "@objectstack/driver-turso": "^5.2.0"
+    "@objectstack/driver-turso": "^5.2.0",
+    "@objectstack/metadata": "^5.2.0",
+    "@objectstack/objectql": "^5.2.0",
+    "@objectstack/runtime": "^5.2.0",
+    "@objectstack/spec": "^5.2.0"
   },
   "devDependencies": {
+    "@types/node": "^25.9.1",
     "typescript": "^5.7.0"
   }
 }

content/docs/configure/authentication.mdx

@@ -51,26 +51,34 @@ Configure provider credentials through environment variables or system
 settings, depending on how the application package exposes auth
 configuration.
 
-Provider callback URLs use the ObjectOS auth route:
+Provider callback URLs depend on the provider type. ObjectStack exposes
+two distinct callback paths and they are **not** interchangeable:
 
-```text
-https://<project-domain>/api/v1/auth/callback/<provider>
-```
+| Provider type | Callback path |
+|---|---|
+| Built-in social (Google, GitHub, Microsoft, Apple, …) | `/api/v1/auth/callback/<provider>` |
+| Generic OIDC / OAuth2 (Okta, Entra ID, Keycloak, Ping, …) | `/api/v1/auth/oauth2/callback/<provider>` |
 
 Examples:
 
 ```text
 https://crm.example.com/api/v1/auth/callback/google
 https://crm.example.com/api/v1/auth/callback/microsoft
+https://crm.example.com/api/v1/auth/oauth2/callback/okta
+https://crm.example.com/api/v1/auth/oauth2/callback/entra
 ```
 
+Configure the matching redirect URI in the identity provider's
+application registration before enabling the provider in ObjectOS.
+
 ## Enterprise OIDC/SSO
 
-OIDC providers typically require:
+OIDC providers are registered as generic OAuth2 providers and use the
+`/oauth2/callback/<provider>` path. A typical configuration requires:
 
 | Field | Description |
 |---|---|
-| Provider id | Stable id such as `okta` or `azure-ad` |
+| Provider id | Stable id such as `okta` or `entra` (used in the callback URL) |
 | Display name | Button label shown to users |
 | Discovery URL | `.well-known/openid-configuration` endpoint |
 | Client id | Application client id from the identity provider |

content/docs/configure/permissions/permission-sets.mdx

@@ -26,19 +26,22 @@ Object permissions answer:
 Can this user perform this operation on this object at all?
 ```
 
-Common grants:
+Permission set grants use these flag names (as enforced by the security
+plugin's permission evaluator):
 
-| Grant | Meaning |
+| Flag | Meaning |
 |---|---|
-| `create` | Create records |
-| `read` | Read records allowed by record access rules |
-| `update` | Update records allowed by record access rules |
-| `delete` | Delete records allowed by record access rules |
-| `viewAll` | Read all records for the object |
-| `modifyAll` | Update/delete all records for the object |
-
-Record access still matters unless `viewAll` or `modifyAll` bypasses the
-normal row-level boundary.
+| `allowRead` | Read records allowed by record access rules |
+| `allowCreate` | Create records |
+| `allowEdit` | Update records allowed by record access rules |
+| `allowDelete` | Delete records allowed by record access rules |
+| `viewAllRecords` | Read every record for the object, bypassing record access |
+| `modifyAllRecords` | Update or delete every record for the object, bypassing record access; implies `viewAllRecords` for reads |
+
+Record access still matters unless `viewAllRecords` or `modifyAllRecords`
+bypasses the normal row-level boundary. Reserve those flags for
+administrative permission sets — they are effectively a tenant-wide
+super-user grant for that object.
 
 ## System permissions
 

content/docs/configure/runtime.mdx

@@ -30,10 +30,16 @@ ObjectOS uses a local Artifact API client. Every hostname resolves to the
 same project. The runtime config is read from the artifact when present,
 or falls back to a local runtime default for evaluation.
 
+`OS_ARTIFACT_FILE` is the ObjectOS app-wrapper convention. The underlying
+runtime also accepts `OS_ARTIFACT_PATH` directly (used by the
+`@objectstack/cli` `dev` and `start` commands and by the framework's
+standalone stack). Set either one — not both.
+
 Optional:
 
 ```bash
 OS_PROJECT_ID=proj_customer_prod
+OS_ENVIRONMENT_ID=env_prod
 OS_WATCH_ARTIFACT=1
 ```
 

content/docs/deploy/kubernetes.mdx

@@ -60,22 +60,28 @@ env:
 
 ## Probes
 
-Configure probes against an HTTP route that confirms the container is
-serving traffic:
+ObjectOS exposes a built-in `GET /health` endpoint that responds before
+the project kernel is fully resolved, which makes it the right target
+for both liveness and readiness probes:
 
 ```yaml
 readinessProbe:
   httpGet:
-    path: /
+    path: /health
     port: 3000
+  initialDelaySeconds: 5
+  periodSeconds: 10
 livenessProbe:
   httpGet:
-    path: /
+    path: /health
     port: 3000
+  initialDelaySeconds: 15
+  periodSeconds: 20
 ```
 
-For stricter checks, use an application-specific API route that requires
-the target artifact to be loaded.
+For stricter readiness checks, point an additional probe at an
+application-specific generated API route — this confirms the artifact
+loaded and the kernel is serving requests.
 
 ## Ingress and CORS
 

content/docs/reference/environment-variables.mdx

@@ -19,11 +19,16 @@ Use system settings for tenant/user-editable application configuration.
 
 | Variable | Required | Description |
 |---|---:|---|
-| `OS_ARTIFACT_FILE` | File mode | Path to local compiled artifact used by this ObjectOS app wrapper. |
+| `OS_ARTIFACT_FILE` | File mode | Path to a local compiled `objectstack.json`. Read by the ObjectOS app wrapper and forwarded as `fileConfig.artifactPath`. |
+| `OS_ARTIFACT_PATH` | Alternative | Framework-level name for the same path or `http(s)://` URL. Honoured by `@objectstack/runtime` directly (CLI `dev`/`start`, standalone mode). |
 | `OS_PROJECT_ID` | Optional | Project id for file-backed mode or explicit project identity. |
-| `OS_WATCH_ARTIFACT` | No | Set to `1` to reload local artifact while developing. |
-| `OS_CLOUD_URL` | Cloud mode | Control-plane base URL for hostname resolution and artifact fetch. |
+| `OS_ENVIRONMENT_ID` | Optional | Environment id for standalone/file-backed mode (default `proj_local`). Also used to derive the per-project auth secret. |
+| `OS_ORGANIZATION_ID` | Optional | Default organization id for file-backed mode (default `org_local`). |
+| `OS_WATCH_ARTIFACT` | No | Set to `1` to reload the local artifact when it changes. Use only in development. |
+| `OS_CLOUD_URL` | Cloud mode | Control-plane base URL for hostname resolution and artifact fetch. Set to `off` or `local` to opt out of cloud-connected behaviour. |
 | `OS_CLOUD_API_KEY` | Optional | Bearer token for private control-plane Artifact API access. |
+| `OS_MULTI_TENANT` | No | Set to `false` to disable multi-tenant routing (default `true`). |
+| `OS_RUNTIME_PORT` | Dev only | Localhost port used to build platform-SSO callback URLs when developing on `http://localhost:<port>`. |
 
 ## Cache
 
@@ -46,11 +51,20 @@ Use system settings for tenant/user-editable application configuration.
 
 ## Database
 
-Database configuration can come from the control-plane runtime response
-or the artifact datasource declarations. Framework standalone mode also
-recognizes `OS_DATABASE_URL`, `OS_DATABASE_DRIVER`, and
-`OS_DATABASE_AUTH_TOKEN`.
+In cloud-connected mode the control plane returns the per-project
+runtime database configuration with the artifact response. In
+file-backed mode ObjectOS reads datasource declarations from the
+artifact. As a last resort the framework also honours:
+
+| Variable | Description |
+|---|---|
+| `OS_DATABASE_URL` | Connection URL (`file:./db.sqlite`, `libsql://…`, `postgres://…`, `mongodb://…`, `memory://`). Used by standalone mode and CLI `dev`. |
+| `OS_DATABASE_DRIVER` | Override the driver auto-detected from the URL. |
+| `OS_DATABASE_AUTH_TOKEN` | Auth token for managed drivers such as Turso/libSQL. |
+| `OS_BUSINESS_DB_URL` | ObjectOS wrapper convention for the per-project business database URL. Resolve it to `OS_DATABASE_URL` or a runtime datasource override in your deployment. |
+| `OS_CACHE_DIR` | Local artifact and runtime cache directory (default `/var/cache/objectos`). |
+| `OS_SKIP_SCHEMA_SYNC` | Set to `1` to skip ObjectQL DDL sync at boot. Use when schema is managed out-of-band. |
 
 For ObjectOS customer deployments, prefer explicit control-plane runtime
-configuration or artifact datasource configuration over undocumented
+configuration or artifact datasource configuration over relying on
 container-local defaults.