feat: update documentation to reflect new authentication features and protocol namespaces

Author: hotlong

CHANGELOG.md

@@ -8,6 +8,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **`os auth login` — browser-based device flow (Vercel CLI style)** — Running `os auth login` in an interactive TTY no longer requires typing a password into the terminal. The CLI now calls `POST /api/v1/auth/device/request` to obtain a one-time device code, prints the verification URL, auto-opens the browser, and polls `GET /api/v1/auth/device/token` every 2 s until the user approves. A new Studio page at `/_studio/auth/device?code=…` lets authenticated users (or users who sign in inline) approve the request with one click. The old `--email`/`--password` path is preserved for non-interactive / CI use; `--no-browser` skips auto-open. Server-side: two new endpoints (`/device/request`, `/device/token`) and an approval endpoint (`/device/approve`) added to `plugin-auth`; device codes expire after 5 min and are stored in-memory.
+- **`os auth register` CLI command** — New `os auth register` command creates an account and stores credentials in one step, with interactive prompts (email, name, password) and `--email`/`--name`/`--password`/`--url` flags for non-interactive use.
+- **`os auth login` — already-logged-in guard** — If a valid token already exists in `~/.objectstack/credentials.json`, `os auth login` now prints "Already logged in as \<email\>" and exits 0. Use `os auth logout` first to switch accounts, or pass `--force` to bypass the check.
+- **`os auth logout` — server-side session revocation** — `os auth logout` now calls `POST /api/v1/auth/sign-out` before deleting the local credentials file, so the session is invalidated server-side. The logout completes successfully even if the API call fails (expired/invalid token).
+- **Studio device auth page** — New Studio route `/_studio/auth/device` provides the browser approval UI for the CLI device flow. The page matches the login page visual style (centered card, `bg-muted`, `max-w-sm`, ObjectStack logo). Unauthenticated users see an inline sign-in form; authenticated users see a one-click "Approve CLI Access" button. The `/auth/device` route is added to `PUBLIC_ROUTES` so the auth guard does not redirect before the form renders.
 - **`os auth login` / `register` / `me` now work against multi-project servers** — `@objectstack/client` was sending requests to better-auth's `/sign-in/email`, `/sign-up/email`, `/sign-out`, `/get-session` without an `Origin` header, which better-auth rejected with `MISSING_OR_NULL_ORIGIN: Missing or null Origin` against the default `trustedOrigins: ['http://localhost:*']`. Auth methods now send `Origin: <baseUrl>` automatically. Additionally, the `login()` and `register()` response normalizer now accepts both the wrapped `{ data: { token, user } }` shape and better-auth's flat `{ token, user }` shape so the CLI's `auth login` flow stores the token correctly.
 - **`os projects bind` + `os projects create --artifact` CLI commands** — Third-party developers can now bind a locally-compiled bundle to a multi-project server without raw `curl`. `os projects create --org <id> --name <name> --artifact ./dist/objectstack.json` provisions a new project and seeds the bundle in one call (also supports `--template <id>` for the parity with built-in templates). The new `os projects bind <projectId> --artifact <path>` updates an existing project's `metadata.artifact_path`, with `--build` to run `objectstack compile` first and `--reseed` as a placeholder for the future server-side reseed endpoint. Both flags resolve relative paths to absolute and validate the file exists before issuing the API call. Verified end-to-end: project created via CLI, `/api/v1/projects/{id}/data/account` returns the seeded CRM accounts.
 - **Third-party project binding via `metadata.artifact_path`** — Multi-project `POST /api/v1/cloud/projects` now accepts `metadata.artifact_path` to bind a locally-compiled bundle (e.g. `examples/app-crm/dist/objectstack.json`) into a fresh project. Provisioning loads the JSON, registers schemas in the per-project ObjectQL engine, and seeds the bundle's `data` arrays — same pipeline that built-in templates use. New `TemplateSeeder.seedBundle({ projectId, bundle })` method exposes the seeder for arbitrary bundles. Bind errors (read failure, malformed JSON) are recorded as non-fatal `metadata.artifactBindError` so the project still flips to `active`. Verified end-to-end: query `/api/v1/projects/{id}/data/account` returns the seeded CRM accounts.

content/docs/concepts/north-star.mdx

@@ -387,10 +387,10 @@ ObjectOS 的运行时输入分两类，**缺一不可**。把两类混在一起
 `ProjectArtifactSchema` envelope，定义在 [packages/spec/src/cloud/project-artifact.zod.ts](packages/spec/src/cloud/project-artifact.zod.ts)：
 
 ```
-{ schemaVersion, projectId, commitId, checksum, builtAt, builtWith, metadata }
+{ schemaVersion, projectId, commitId, checksum, metadata, functions, manifest, builtAt, builtWith, payloadRef? }
 ```
 
-`metadata` 字段就是 `objectstack compile` 产出的 `dist/objectstack.json` 整体。承载所有声明性元数据（objects、views、flows、agents、插件清单等）+ 内联函数代码。Envelope 在外面包一层 `commitId` / `checksum`，让 ObjectOS 能做 ETag 校验和缓存失效。
+`metadata` 字段承载声明性元数据（objects、views、flows、agents 等），`functions` 内联可执行源码，`manifest` 声明插件 / driver / engine 要求。Envelope 在外面包一层 `commitId` / `checksum`，让 ObjectOS 能做完整性校验、ETag 校验和缓存失效。`payloadRef` 为未来 S3 / signed URL 旁路保留，不需要 envelope 破坏性升级。
 
 **B. Deployment Config**（可变、不进 artifact、与元数据正交）
 
@@ -443,7 +443,7 @@ Subsequent requests reuse the cached artifact. Cache invalidation strategy
 
 ## 7. Alignment Check
 
-Honest state of the platform as of 2026-04-25, **re-classified under the Phase
+Honest state of the platform as of 2026-04-26, **re-classified under the Phase
 1 code-first model**. Every future architectural decision should preserve Built,
 reduce Drift, and advance Missing.
 
@@ -460,6 +460,12 @@ reduce Drift, and advance Missing.
 - **Scaffolded TS file tree.** `create-objectstack` emits a `defineStack()` entry point plus split-out `src/objects/*.ts`, `src/views/*.ts` etc. - [packages/create-objectstack/src/index.ts](packages/create-objectstack/src/index.ts).
 - **ObjectOS metadata DB bridge removed.** `MetadataPlugin` no longer registers `sys_metadata` / `sys_metadata_history` into the ObjectOS manifest and no longer auto-connects ObjectQL to a `DatabaseLoader`; runtime metadata is hydrated from files or artifacts only - [packages/metadata/src/plugin.ts](packages/metadata/src/plugin.ts).
 - **JSON-payload metadata storage.** `sys_metadata.metadata` column is already a textarea-shaped JSON payload column - [packages/metadata/src/objects/sys-metadata.object.ts](packages/metadata/src/objects/sys-metadata.object.ts). (The *location* of the table still needs to move to the control plane - see Drift.)
+- **Project artifact envelope schema (M1).** `ProjectArtifactSchema` v0 exists with `schemaVersion`, `projectId`, `commitId`, `checksum`, `metadata`, `functions`, `manifest`, and reserved `payloadRef` - [packages/spec/src/cloud/project-artifact.zod.ts](packages/spec/src/cloud/project-artifact.zod.ts).
+- **Project artifact path binding.** Multi-project provisioning accepts `metadata.artifact_path`, and `os projects create --artifact` / `os projects bind --artifact` wire local compiled bundles into existing projects - [packages/cli/src/commands/projects/create.ts](packages/cli/src/commands/projects/create.ts), [packages/cli/src/commands/projects/bind.ts](packages/cli/src/commands/projects/bind.ts).
+- **Live kernel bundle resolver.** Project kernels read `sys_project.metadata.artifact_path` / `artifact_paths[]`, with `OBJECTSTACK_PROJECT_ARTIFACTS` and `OBJECTSTACK_PROJECT_ARTIFACT_ROOT` overrides for local development - [apps/server/server/fs-app-bundle-resolver.ts](apps/server/server/fs-app-bundle-resolver.ts).
+- **Object identity is single-sourced on `name`.** `ObjectSchemaBase.namespace` has been removed; package namespace remains internal registry metadata, not an object identity field - [packages/spec/src/data/object.zod.ts](packages/spec/src/data/object.zod.ts).
+- **Manifest scope enum trimmed.** `ManifestSchema.scope` accepts only `cloud`, `system`, and `project` - [packages/spec/src/kernel/manifest.zod.ts](packages/spec/src/kernel/manifest.zod.ts).
+- **Canonical package manifest files.** Plugin/service packages now share a single `src/manifest.ts` between compile-time config and runtime registration, reducing object-list drift.
 - **CLI `publish` link.** The end-to-end "local JSON -> remote server" wire is alive, even though the endpoint shape is wrong - [packages/cli/src/commands/publish.ts](packages/cli/src/commands/publish.ts).
 
 ### <AlertTriangle className="inline" /> Drift (Needs Cleanup)
@@ -468,18 +474,9 @@ reduce Drift, and advance Missing.
   scoped by `organization_id` + `project_id`; deployment target differences are
   runtime/deployment configuration, not metadata row partitioning. Branch-like
   variants are deferred rather than modeled through `env_id`.
-- **`namespace` residue**: deprecated in favor of embedding prefix in object
-  `name`, but leftovers remain. Schema should be single-sourced on `name` for
-  identity.
-- **Plugin `scope` enum bloat**: grew to 5 values (`cloud` / `system` / `project` /
-  `platform` / `environment`) with last two marked as deprecated aliases. Break
-  cleanly, don't carry aliases.
 - **Half-wired abstractions**: `ScopedServiceManager` and `SharedProjectPlugin`
   were added but their integration into the request path is incomplete. Either
   finish them or remove.
-- **Recent plugin-config churn** (commit `a4f5eb51`): large reorganization
-  moving object registration between files without obvious feature value.
-  Should converge on one home.
 - **`objectstack publish` uses the legacy `/api/v1/packages` endpoint.** Today
   it POSTs a "package" payload ([packages/cli/src/commands/publish.ts](packages/cli/src/commands/publish.ts))
   which is not the Phase 1 project metadata endpoint. It needs to become
@@ -493,7 +490,7 @@ reduce Drift, and advance Missing.
 ### <Globe className="inline" /> Missing (Not Started)
 
 - **Metadata migration to control plane** - move user metadata out of project DBs into the control-plane DB, scoped by `organization_id` + `project_id`.
-- **Project Artifact API** - `GET /api/v1/apps/:projectId/artifact` assembles the current project metadata + inlined function code into a single consumable blob, with content hash/ETag for cache validation.
+- **Project Artifact API** - `GET /api/v1/cloud/projects/:projectId/artifact` assembles the current project metadata + inlined function code into a single consumable blob, with content hash/ETag for cache validation.
 - **ObjectOS Artifact API loader** - add the production HTTP fetch source for `MetadataPlugin` and local artifact cache durability across control-plane outages.
 - **Project publish endpoint** - `POST /api/v1/apps/:projectId/metadata` receives compiled JSON, validates with Zod, writes the current project metadata state, and returns `commitId` + checksum.
 - **Studio metadata/artifact viewer** - browse published metadata, artifact envelope, commit id, checksum, publish history, logs, and runtime health. No metadata editing.
@@ -540,9 +537,9 @@ without explicit project-level buy-in.
 Questions this document deliberately leaves unresolved. Answer them in follow-up
 design docs before building.
 
-1. **Artifact content format details.** Phase 1 chooses a single JSON document,
-   but the exact envelope, manifest fields, function-code packaging, and driver
-   requirement declaration still need a Zod schema.
+1. ~~**Artifact content format details.**~~ **Resolved (2026-04-26):**
+   `ProjectArtifactSchema` v0 defines the envelope, manifest requirements,
+   function-code packaging, checksum, and future `payloadRef` indirection.
 2. ~~**Business DB connection config ownership.**~~ **Resolved (2026-04-25):**
    Business DB coordinates and credentials are **Deployment Config**, never
    part of the Artifact. See §6.3 Runtime Inputs. Cloud mode sources them from

content/docs/concepts/terminology.mdx

@@ -10,39 +10,27 @@ To navigate the ObjectStack ecosystem effectively, it is helpful to understand t
 ## The Ecosystem
 
 ### ObjectStack
-The umbrella term for the entire suite of protocols and reference implementations. It is organized into **11 protocol namespaces** grouped into three architectural layers.
+The umbrella term for the entire suite of protocols and reference implementations. It is organized into **15 protocol namespaces** grouped into three architectural layers.
 
 ### Protocol Namespace
-A logical grouping of related schemas and types defined with Zod. ObjectStack has 11 protocol namespaces: Data, Driver, Permission, UI, System, Auth, Kernel, Hub, AI, API, and Automation.
+A logical grouping of related schemas and types defined with Zod. ObjectStack has 15 protocol namespaces: Data, UI, System, Automation, AI, API, Identity, Security, Kernel, Cloud, QA, Contracts, Integration, Studio, and Shared.
 
 ---
 
-## The 11 Protocol Namespaces
+## The 15 Protocol Namespaces
 
 ### Data Protocol
 Defines the core business data model. Includes Object schema, Field types, Validation rules, Query AST, and Filter conditions. This is the foundation of ObjectQL.
 
-### Driver Protocol
-Database adapter interface for connecting to various storage engines (PostgreSQL, MongoDB, SQLite, Redis, etc.). Drivers implement a standard interface for CRUD operations and query execution.
-
-### Permission Protocol
-Access control system including object-level permissions (CRUD), field-level security (FLS), sharing rules, and territory management. Determines who can see and modify what data.
-
 ### UI Protocol
 Server-Driven UI specification for building user interfaces. Includes App structure, Views (List/Form/Kanban/Calendar), Dashboards, Reports, Themes, and Actions.
 
 ### System Protocol
 Infrastructure services including Event Bus, Job Scheduling, Translation (i18n), and Audit Logging. Manages system-level concerns.
 
-### Auth Protocol
-Identity and access management including User accounts, Sessions, Roles, Organization structure, and various authentication strategies (OAuth, SAML, LDAP, etc.).
-
 ### Kernel Protocol
 Plugin system and runtime management. Includes Plugin lifecycle, Manifest definition, Logger configuration, and Runtime Context. The core of ObjectOS.
 
-### Hub Protocol
-SaaS and marketplace features including Multi-tenancy, Licensing, Marketplace plugins, and Deployment configurations. Enables commercial distribution.
-
 ### AI Protocol
 Artificial intelligence capabilities including AI Agents, RAG pipelines, Natural Language Query (NLQ), Predictive models, Cost tracking, and Orchestration.
 
@@ -52,6 +40,30 @@ External communication layer including REST contracts, API discovery, Realtime s
 ### Automation Protocol
 Business process automation including Workflows (state machines), Flows (visual logic), and Webhooks (HTTP callbacks).
 
+### Identity Protocol
+User, organization, and profile schemas for identity management.
+
+### Security Protocol
+RBAC, permissions, policy, and access-control schemas.
+
+### Cloud Protocol
+Multi-tenant cloud, deployment, environment, and package distribution schemas.
+
+### QA Protocol
+Test, validation, and quality-assurance schemas.
+
+### Contracts Protocol
+Cross-package interface contracts shared by runtime packages and services.
+
+### Integration Protocol
+External system integration schemas and connection metadata.
+
+### Studio Protocol
+Studio UI metadata and builder-specific schemas.
+
+### Shared Protocol
+Reusable error maps, suggestions, and metadata normalization utilities.
+
 ---
 
 ## Architecture Concepts

content/docs/getting-started/cli.mdx

@@ -214,7 +214,7 @@ os validate path/to/config   # Validate specific file
 
 **Warnings checked:**
 - Missing `manifest.id` (required for deployment)
-- Missing `manifest.namespace` (required for multi-app hosting)
+- Invalid `manifest.scope` (must be `cloud`, `system`, or `project`)
 - No objects defined
 - No apps or plugins defined
 
@@ -338,6 +338,91 @@ os doctor -v        # Show fix suggestions for warnings
 - `@objectstack/spec` build status
 - Git availability
 
+### Authentication
+
+| Command | Description |
+|---------|-------------|
+| `os auth register` | Create an account and store local credentials |
+| `os auth login` | Sign in and store credentials in `~/.objectstack/credentials.json` |
+| `os auth whoami` | Show the current authenticated user |
+| `os auth logout` | Revoke the server session and clear local credentials |
+
+#### `os auth register`
+
+Creates a user account and stores the returned token locally.
+
+```bash
+os auth register
+os auth register --email user@example.com --name "Jane Doe" --password secret
+os auth register --url https://api.example.com
+```
+
+#### `os auth login`
+
+In an interactive terminal, login uses a browser-based device flow by default:
+the CLI prints a one-time verification URL, opens the browser, and polls until
+you approve access in Studio.
+
+```bash
+os auth login
+os auth login --url https://api.example.com
+os auth login --no-browser
+```
+
+If a valid token already exists, `os auth login` exits successfully with
+"Already logged in as <email>". Use `os auth logout` to switch users, or pass
+`--force` to re-authenticate.
+
+For CI and other non-interactive contexts, pass email/password directly:
+
+```bash
+os auth login --email user@example.com --password secret
+```
+
+#### `os auth logout`
+
+Logout calls `POST /api/v1/auth/sign-out` before deleting local credentials, so
+the server-side session is revoked as well.
+
+```bash
+os auth logout
+```
+
+### Cloud Projects
+
+| Command | Description |
+|---------|-------------|
+| `os projects list` | List projects visible to the current session |
+| `os projects show <id>` | Show one project |
+| `os projects create` | Provision a new project |
+| `os projects switch <id>` | Set the active project for later CLI calls |
+| `os projects bind <id>` | Bind a compiled local artifact to an existing project |
+
+#### Create a project from a local artifact
+
+Compile first, then create a project and bind the generated
+`dist/objectstack.json` in one call:
+
+```bash
+os compile
+os projects create --org <org-id> --name CRM --artifact ./dist/objectstack.json
+```
+
+The server stores the absolute path in `sys_project.metadata.artifact_path`.
+On project-kernel boot, ObjectOS loads the JSON bundle, registers schemas, and
+seeds records from the bundle's `data` arrays.
+
+#### Bind an existing project
+
+```bash
+os projects bind <project-id> --artifact ./dist/objectstack.json
+os projects bind <project-id> --artifact ./dist/objectstack.json --build
+```
+
+`--build` runs `objectstack compile` before updating the project. `--reseed`
+is reserved for the server-side reseed endpoint; use it only when that endpoint
+is available in your deployment.
+
 ## Configuration
 
 The CLI looks for `objectstack.config.ts` (or `.js`, `.mjs`) in the current directory:

content/docs/getting-started/examples.mdx

@@ -313,7 +313,7 @@ Each app declares a `namespace` in its manifest, but **the short object name is
 | CRM | `crm` | `account` | `account` |
 | BI | `bi` | `report` | `report` |
 
-If two packages contribute objects with the same short name, the registry logs a warning. In that rare case, callers can disambiguate by passing the FQN (`crm__account`) — but this is the only situation where FQN appears in user code.
+If two packages contribute objects with the same short name, the registry logs a warning. Resolve the collision by renaming one object's short `name` (for example, `crm_account`) rather than using FQN strings in user code.
 
 ### Run It