Merge pull request #1180 from objectstack-ai/copilot/update-package-docs

Author: hotlong

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
 - **Cross-origin auth tokens stripped in `@objectstack/hono` adapter (follow-up to PR #1178)** — `createHonoApp()` was not exposing `set-auth-token` via `Access-Control-Expose-Headers`, diverging from `plugin-hono-server`'s CORS wiring. On Vercel deployments (where all traffic flows through `createHonoApp()`), the browser stripped the header from every response, preventing the better-auth `bearer()` plugin from delivering rotated session tokens to cross-origin clients. Cross-origin sessions silently broke even after the wildcard fixes in #1177/#1178. The adapter now always includes `set-auth-token` in `exposeHeaders`, merged with any user-supplied values, mirroring the invariant established in commit `151dd19c`. (`packages/adapters/hono/src/index.ts`)
 - **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`)

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