Phase 2 (thin READMEs) + Phase 3 (docs site, CHANGELOG, RELEASE_NOTES, root README) + Phase 4 (build/test green)

Agent-Logs-Url: https://github.com/objectstack-ai/framework/sessions/31298df6-e8fb-4b22-9182-02fb8a2606b3

Co-authored-by: xuyushun441-sys <255036401+xuyushun441-sys@users.noreply.github.com>

Author: Copilot

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Release-readiness documentation pass (42 packages)** — Aligned every `@objectstack/*` package for the formal v4.x release:
+  - Canonical README template and `package.json` publishing checklist committed at `docs/internal/PACKAGE_README_TEMPLATE.md`
+  - New `packages/services/service-package/README.md` documenting the package registry service
+  - All `package.json` files now carry `description`, at least 3 `keywords`, a full `repository` block with `directory`, `homepage`, `bugs`, `engines.node`, `publishConfig.access: public`, and a `files` whitelist
+  - `@objectstack/service-tenant` (was `0.1.0`) and `@objectstack/service-package` (was `1.0.0`) bumped to `4.0.4` in lockstep with the release train
+  - Rewrote thin READMEs for `core`, `rest`, `driver-memory`, `plugin-security`, and all seven framework adapters (`express`, `fastify`, `hono`, `nestjs`, `nextjs`, `nuxt`, `sveltekit`) to the canonical structure: overview, installation, quick start, key exports, configuration, when/when-not, related packages, and docs links
+  - Updated `content/docs/guides/packages.mdx` and `content/docs/concepts/packages.mdx` to reflect the actual **42 package** inventory and to include `service-package` and `service-tenant`
+
 ### Fixed
 - **CORS wildcard patterns in `@objectstack/hono` adapter (follow-up to PR #1177)** — `createHonoApp()` was the third CORS code path that still treated wildcard origins (e.g. `https://*.objectui.org`) as literal strings when passing them to Hono's `cors()` middleware. Because `apps/server` routes all non-OPTIONS requests through this adapter on Vercel, the browser would see a successful preflight (handled by the Vercel short-circuit) followed by a POST/GET response with no `Access-Control-Allow-Origin` header, blocking every real request. The adapter now imports `hasWildcardPattern` / `createOriginMatcher` from `@objectstack/plugin-hono-server` and uses the same matcher-function branch as `plugin-hono-server`, so all three Hono-based CORS paths share a single source of truth. (`packages/adapters/hono/src/index.ts`)
 - **CORS wildcard patterns on Vercel deployments** — `CORS_ORIGIN` values containing wildcard patterns (e.g. `https://*.objectui.org,https://*.objectstack.ai,http://localhost:*`) no longer cause browser CORS errors when `apps/server` is deployed to Vercel. The Vercel entrypoint's OPTIONS preflight short-circuit previously matched origins with a literal `Array.includes()`, treating `*` as a plain character and rejecting legitimate subdomains. It now shares the same pattern-matching logic as the Hono plugin's `cors()` middleware via new exports `createOriginMatcher` / `hasWildcardPattern` / `matchOriginPattern` / `normalizeOriginPatterns` from `@objectstack/plugin-hono-server`. (`apps/server/server/index.ts`, `packages/plugins/plugin-hono-server/src/pattern-matcher.ts`)

README.md

@@ -136,6 +136,7 @@ os doctor         # Check environment health
 | Package | Description |
 | :--- | :--- |
 | [`@objectstack/plugin-hono-server`](packages/plugins/plugin-hono-server) | Hono-based HTTP server plugin |
+| [`@objectstack/plugin-mcp-server`](packages/plugins/plugin-mcp-server) | Model Context Protocol server — exposes ObjectStack to AI agents |
 | [`@objectstack/plugin-msw`](packages/plugins/plugin-msw) | Mock Service Worker plugin for browser testing |
 | [`@objectstack/plugin-auth`](packages/plugins/plugin-auth) | Authentication plugin (better-auth) |
 | [`@objectstack/plugin-security`](packages/plugins/plugin-security) | RBAC, Row-Level Security, Field-Level Security |
@@ -147,11 +148,18 @@ os doctor         # Check environment health
 
 | Package | Description |
 | :--- | :--- |
-| [`@objectstack/service-feed`](packages/services/service-feed) | Activity feed service |
-| [`@objectstack/service-automation`](packages/services/service-automation) | Automation engine — flows, triggers, DAG-based workflows |
 | [`@objectstack/service-ai`](packages/services/service-ai) | AI service — Agent, Tool, Skill, Vercel AI SDK integration |
-| [`@objectstack/service-realtime`](packages/services/service-realtime) | Real-time events and subscriptions |
+| [`@objectstack/service-analytics`](packages/services/service-analytics) | Analytics — aggregations, time series, funnels, dashboards |
+| [`@objectstack/service-automation`](packages/services/service-automation) | Automation engine — flows, triggers, DAG-based workflows |
+| [`@objectstack/service-cache`](packages/services/service-cache) | Cache — in-memory, Redis, multi-tier |
+| [`@objectstack/service-feed`](packages/services/service-feed) | Activity feed / chatter |
 | [`@objectstack/service-i18n`](packages/services/service-i18n) | Internationalization service |
+| [`@objectstack/service-job`](packages/services/service-job) | Cron & interval job scheduler |
+| [`@objectstack/service-package`](packages/services/service-package) | Package registry — publish, version, retrieve metadata packages |
+| [`@objectstack/service-queue`](packages/services/service-queue) | Background job queue (in-memory, BullMQ) |
+| [`@objectstack/service-realtime`](packages/services/service-realtime) | Real-time events and subscriptions |
+| [`@objectstack/service-storage`](packages/services/service-storage) | File storage (local, S3, R2, GCS) |
+| [`@objectstack/service-tenant`](packages/services/service-tenant) | Multi-tenant context and routing |
 
 ### Framework Adapters
 
@@ -188,7 +196,7 @@ os doctor         # Check environment health
 
 | Metric | Value |
 | :--- | :--- |
-| Packages | 27 |
+| Packages | 42 |
 | Zod schema files | 200 |
 | Exported schemas | 1,600+ |
 | `.describe()` annotations | 8,750+ |

RELEASE_NOTES.md

@@ -1,5 +1,50 @@
 # Release Notes
 
+## v4.0.4 — Release Readiness: Documentation Alignment _(in progress)_
+
+### 🎯 Purpose
+
+Prepare all 42 packages under `@objectstack/*` for formal public release on npm by:
+
+- Guaranteeing consistent, complete publishing metadata on every package.
+- Normalizing README structure so every package documents overview, installation, quick start, exports, configuration, when/when-not, related packages, and links to the docs site.
+- Bringing version numbers for previously experimental packages (`service-tenant`, `service-package`) in lockstep with the release train at `4.0.4`.
+- Correcting stale package counts and missing entries in the official documentation site.
+
+### 📦 Package inventory (42)
+
+| Category | Count | Packages |
+|:---|:---:|:---|
+| Core runtime | 7 | `spec`, `core`, `runtime`, `types`, `metadata`, `objectql`, `rest` |
+| Client / DX | 5 | `client`, `client-react`, `cli`, `create-objectstack`, `vscode-objectstack` |
+| Adapters | 7 | `express`, `fastify`, `hono`, `nestjs`, `nextjs`, `nuxt`, `sveltekit` |
+| Drivers | 3 | `driver-memory`, `driver-sql`, `driver-turso` |
+| Plugins | 8 | `plugin-auth`, `plugin-security`, `plugin-audit`, `plugin-hono-server`, `plugin-mcp-server`, `plugin-msw`, `plugin-dev`, `plugin-setup` |
+| Services | 12 | `service-ai`, `service-analytics`, `service-automation`, `service-cache`, `service-feed`, `service-i18n`, `service-job`, `service-package`, `service-queue`, `service-realtime`, `service-storage`, `service-tenant` |
+
+### ✅ Release readiness checklist
+
+- [x] Canonical README template and publishing checklist committed at `docs/internal/PACKAGE_README_TEMPLATE.md`.
+- [x] Every `package.json` has: `description`, `keywords` (≥ 3), `repository` (with `directory`), `homepage`, `bugs`, `license`, `publishConfig.access: public`, `files`, `engines.node`.
+- [x] `service-tenant` and `service-package` version-aligned to `4.0.4`.
+- [x] `packages/services/service-package/README.md` authored.
+- [x] Thin READMEs rewritten: `core`, `rest`, `driver-memory`, `plugin-security`, all 7 adapters.
+- [x] `content/docs/guides/packages.mdx` updated to 42-package inventory including `service-package` and `service-tenant`.
+- [x] `content/docs/concepts/packages.mdx` updated to 42-package inventory.
+- [x] `CHANGELOG.md` carries a release-prep entry.
+- [ ] `pnpm build` passes for every publishable package.
+- [ ] `pnpm test` passes.
+- [ ] `lychee` link check passes across all READMEs and `content/docs/**`.
+- [ ] `pnpm docs:build` succeeds.
+- [ ] `content/docs/references/` regenerated via `pnpm --filter @objectstack/spec gen:docs`.
+
+### 📝 Known follow-ups
+
+- Existing strong READMEs (e.g. `service-ai`, `service-storage`, `plugin-audit`, `runtime`, `spec`, `driver-sql`, `driver-turso`) are structurally sound and were not rewritten — they retain their individual voice and depth. A future pass may add standardized npm + license badges across them.
+- `content/docs/references/` regeneration is out of scope for this PR because it requires a full spec rebuild; it should run as part of the release pipeline.
+
+---
+
 ## v1.2.0 - Studio DX, REST Extraction, Dispatcher Plugin (2026-02-09)
 
 ### 📦 Released Packages

content/docs/concepts/packages.mdx

@@ -5,20 +5,22 @@ description: Complete reference of all ObjectStack packages in the monorepo
 
 # Package Reference
 
-ObjectStack is distributed as a monorepo containing **25 packages** organized into core packages, adapters, and plugins.
+ObjectStack is distributed as a monorepo containing **42 packages** organized into core runtime, client SDKs, framework adapters, drivers, plugins, and platform services.
 
-> **Note for AI Agents**: Each package's `README.md` contains a specific "AI Development Context" section describing its architectural role and usage rules.
+> **Note for AI Agents**: Each package's `README.md` contains a specific architectural role and usage rules section.
 
 ## Package Overview
 
 | Category | Count | Description |
 | :--- | :---: | :--- |
-| [Core Packages](#core-packages) | 9 | Essential runtime, protocols, client SDKs, and CLI |
-| [Framework Adapters](#framework-adapters) | 7 | Express, Fastify, Hono, NestJS, Next.js, Nuxt, SvelteKit |
-| [Plugin Packages](#plugin-packages) | 6 | Drivers, server, auth, security, dev, and MSW plugins |
-| [Tools](#tools) | 3 | Project scaffolder, VSCode extension, REST API server |
-
-**Total: 25 packages**
+| Core runtime | 7 | `spec`, `core`, `runtime`, `types`, `metadata`, `objectql`, `rest` |
+| Client / DX | 5 | `client`, `client-react`, `cli`, `create-objectstack`, `vscode-objectstack` |
+| Framework adapters | 7 | Express, Fastify, Hono, NestJS, Next.js, Nuxt, SvelteKit |
+| Drivers | 3 | `driver-memory`, `driver-sql`, `driver-turso` |
+| Plugins | 8 | Auth, Security, Audit, Hono-Server, MCP-Server, MSW, Dev, Setup |
+| Platform services | 12 | AI, Analytics, Automation, Cache, Feed, I18n, Job, Package, Queue, Realtime, Storage, Tenant |
+
+**Total: 42 packages**
 
 ---
 

content/docs/guides/packages.mdx

@@ -5,7 +5,19 @@ description: Complete guide to all ObjectStack packages, services, drivers, plug
 
 # Package Overview
 
-ObjectStack is organized into **27 packages** across multiple categories. This guide provides a complete overview of each package, its purpose, and when to use it.
+ObjectStack is organized into **42 packages** across multiple categories. This guide provides a complete overview of each package, its purpose, and when to use it.
+
+### Package categories at a glance
+
+| Category | Count | Packages |
+|:---|:---:|:---|
+| **Core runtime** | 7 | `spec`, `core`, `runtime`, `types`, `metadata`, `objectql`, `rest` |
+| **Client / DX** | 5 | `client`, `client-react`, `cli`, `create-objectstack`, `vscode-objectstack` |
+| **Framework adapters** | 7 | `express`, `fastify`, `hono`, `nestjs`, `nextjs`, `nuxt`, `sveltekit` |
+| **Drivers** | 3 | `driver-memory`, `driver-sql`, `driver-turso` |
+| **Plugins** | 8 | `plugin-auth`, `plugin-security`, `plugin-audit`, `plugin-hono-server`, `plugin-mcp-server`, `plugin-msw`, `plugin-dev`, `plugin-setup` |
+| **Platform services** | 12 | `service-ai`, `service-analytics`, `service-automation`, `service-cache`, `service-feed`, `service-i18n`, `service-job`, `service-package`, `service-queue`, `service-realtime`, `service-storage`, `service-tenant` |
+
 
 ## Core Packages
 
@@ -241,6 +253,22 @@ All services implement contracts from `@objectstack/spec/contracts` and are kern
 - **When to use**: File attachments, document management, media storage
 - **README**: [View README](/packages/services/service-storage/README.md)
 
+### @objectstack/service-package
+
+**Package Registry Service** — Publish, version, and retrieve ObjectStack metadata packages from the `sys_packages` table.
+
+- **Features**: Upsert by `(id, version)`, SHA-256 integrity hash, `latest` resolution, bulk list/delete
+- **When to use**: Marketplace backends, internal tenant-facing registries, CI-driven metadata distribution
+- **README**: [View README](/packages/services/service-package/README.md)
+
+### @objectstack/service-tenant
+
+**Multi-Tenant Service** — Tenant context, routing, and isolation for SaaS deployments.
+
+- **Features**: Tenant resolution from host/header/cookie, per-tenant metadata and data isolation
+- **When to use**: Any multi-tenant SaaS on ObjectStack
+- **README**: [View README](/packages/services/service-tenant/README.md)
+
 ---
 
 ## Official Plugins

packages/adapters/express/README.md

@@ -1,22 +1,81 @@
 # @objectstack/express
 
-The official Express adapter for ObjectStack.
+> Express adapter for ObjectStack — mounts the auto-generated REST API and route dispatcher onto an Express app.
 
-## Features
-- Standalone Express router integration
-- Full Auth/GraphQL/Metadata/Data/Storage routes
-- AuthPlugin service support with Web Request conversion
-- Middleware mode for attaching kernel to requests
+[![npm](https://img.shields.io/npm/v/@objectstack/express.svg)](https://www.npmjs.com/package/@objectstack/express)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-## Usage
+## Overview
+
+Wraps `HttpDispatcher` from `@objectstack/runtime` as an Express `Router` (or request middleware). All ObjectStack routes — CRUD, batch, metadata, discovery, auth, storage, GraphQL — are handled by a catch-all that delegates to the dispatcher, so new protocol routes work automatically without adapter updates.
+
+## Installation
+
+```bash
+pnpm add @objectstack/express express
+```
+
+## Quick Start
 
 ```typescript
 import express from 'express';
 import { createExpressRouter } from '@objectstack/express';
+import { kernel } from './my-kernel';
 
 const app = express();
 app.use(express.json());
 app.use('/api', createExpressRouter({ kernel }));
-
 app.listen(3000);
 ```
+
+### Middleware mode
+
+```typescript
+import { objectStackMiddleware } from '@objectstack/express';
+
+app.use(objectStackMiddleware(kernel));
+```
+
+## Key Exports
+
+| Export | Kind | Description |
+|:---|:---|:---|
+| `createExpressRouter(options)` | function | Returns a mounted `Router` with all ObjectStack dispatchers. |
+| `objectStackMiddleware(kernel)` | function | Per-request middleware (use for custom routing/prefix). |
+| `ExpressAdapterOptions` | interface | `{ kernel: ObjectKernel, prefix?: string }`. |
+
+## Configuration
+
+| Option | Type | Default | Notes |
+|:---|:---|:---|:---|
+| `kernel` | `ObjectKernel` | — | Bootstrapped kernel from `@objectstack/core`. |
+| `prefix` | `string` | `'/api'` | Base path for the mounted router. |
+
+## Middleware order
+
+`express.json()` (or an equivalent body parser) MUST be registered **before** the ObjectStack router. Auth cookies require `cookie-parser` if you use cookie sessions. The adapter sets response headers directly; do not wrap with compression middleware that rewrites JSON bodies before the router.
+
+## When to use
+
+- ✅ Adding ObjectStack to an existing Express app.
+- ✅ Node.js deployments without edge runtime constraints.
+
+## When not to use
+
+- ❌ Edge / Workers — use [`@objectstack/hono`](../hono) instead.
+- ❌ Next.js App Router — use [`@objectstack/nextjs`](../nextjs).
+
+## Related Packages
+
+- [`@objectstack/runtime`](../../runtime) — provides `HttpDispatcher`.
+- [`@objectstack/rest`](../../rest) — route registration used by the dispatcher.
+- [`@objectstack/core`](../../core) — kernel.
+
+## Links
+
+- 📖 Docs: <https://objectstack.ai/docs>
+- 📚 API Reference: <https://objectstack.ai/docs/references>
+
+## License
+
+Apache-2.0 © ObjectStack

packages/adapters/fastify/README.md

@@ -1,21 +1,77 @@
 # @objectstack/fastify
 
-The official Fastify adapter for ObjectStack.
+> Fastify plugin for ObjectStack — registers the auto-generated REST API and dispatcher as a Fastify plugin.
 
-## Features
-- Fastify plugin integration
-- Full Auth/GraphQL/Metadata/Data/Storage routes
-- AuthPlugin service support with Web Request conversion
-- Decorator mode for attaching kernel to requests
+[![npm](https://img.shields.io/npm/v/@objectstack/fastify.svg)](https://www.npmjs.com/package/@objectstack/fastify)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-## Usage
+## Overview
+
+Exposes ObjectStack as a standard Fastify plugin. Auth, storage, GraphQL, and discovery routes are handled explicitly; everything else is served by a catch-all delegating to `HttpDispatcher`, so protocol evolution does not require adapter changes.
+
+## Installation
+
+```bash
+pnpm add @objectstack/fastify fastify
+```
+
+## Quick Start
 
 ```typescript
 import Fastify from 'fastify';
 import { objectStackPlugin } from '@objectstack/fastify';
+import { kernel } from './my-kernel';
+
+const app = Fastify({ logger: true });
+await app.register(objectStackPlugin, { kernel, prefix: '/api' });
+await app.listen({ port: 3000 });
+```
 
-const app = Fastify();
-app.register(objectStackPlugin, { kernel, prefix: '/api' });
+### Decorator mode
 
-app.listen({ port: 3000 });
+```typescript
+import { objectStackDecorator } from '@objectstack/fastify';
+
+app.decorate('objectstack', objectStackDecorator(kernel));
 ```
+
+## Key Exports
+
+| Export | Kind | Description |
+|:---|:---|:---|
+| `objectStackPlugin` | fastify plugin | Registers all dispatcher routes under `prefix`. |
+| `objectStackDecorator(kernel)` | function | Returns a decorator that exposes the dispatcher on the Fastify instance. |
+| `FastifyAdapterOptions` | interface | `{ kernel, prefix? }`. |
+
+## Configuration
+
+| Option | Type | Default |
+|:---|:---|:---|
+| `kernel` | `ObjectKernel` | — |
+| `prefix` | `string` | `'/api'` |
+
+## Middleware order
+
+Register the ObjectStack plugin **after** body parsing, CORS, and authentication preprocessors. Do not enable Fastify's automatic schema validation on ObjectStack routes — the protocol does its own Zod validation.
+
+## When to use
+
+- ✅ Fastify applications needing high-throughput APIs.
+- ✅ Teams already invested in Fastify's plugin ecosystem.
+
+## When not to use
+
+- ❌ Edge / serverless Workers — use [`@objectstack/hono`](../hono).
+
+## Related Packages
+
+- [`@objectstack/runtime`](../../runtime), [`@objectstack/rest`](../../rest), [`@objectstack/core`](../../core).
+
+## Links
+
+- 📖 Docs: <https://objectstack.ai/docs>
+- 📚 API Reference: <https://objectstack.ai/docs/references>
+
+## License
+
+Apache-2.0 © ObjectStack