docs: add package publishing documentation to metadata-service.mdx, README.md, and ROADMAP.md

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

ROADMAP.md

@@ -398,6 +398,7 @@ business/custom objects, aligning with industry best practices (e.g., ServiceNow
 - [x] **In-Memory Driver** — Full CRUD, bulk ops, transactions, aggregation pipeline (Mingo), streaming
 - [x] **In-Memory Driver Persistence** — File-system (Node.js) and localStorage (Browser) persistence adapters with auto-save, custom adapter support
 - [x] **Metadata Service** — CRUD, query, bulk ops, overlay system, dependency tracking, import/export, file watching
+- [x] **Metadata Package Publishing** — `publishPackage`, `revertPackage`, `getPublished` for atomic package-level metadata publishing with version snapshots
 - [x] **Serializers** — JSON, YAML, TypeScript format support
 - [x] **Loaders** — Memory, Filesystem, Remote (HTTP) loaders
 - [x] **REST API** — Auto-generated CRUD/Metadata/Batch/Discovery endpoints
@@ -452,6 +453,7 @@ business/custom objects, aligning with industry best practices (e.g., ServiceNow
 - User overlay persistence across sessions
 - Multi-instance metadata synchronization
 - Production-grade metadata storage
+- Package-level metadata publishing (publishPackage / revertPackage / getPublished)
 
 ### Phase 4b: Infrastructure Service Upgrades (P1 — Weeks 3-4)
 

content/docs/guides/contracts/metadata-service.mdx

@@ -352,3 +352,59 @@ const filteredViews = views.filter(view => {
   return !v.requiredPermission || userPermissions.includes(v.requiredPermission);
 });
 ```
+
+---
+
+## Package Publishing
+
+ObjectStack uses **package-level publishing** to ensure metadata consistency. All metadata items within a package are published atomically — either everything goes live, or nothing does.
+
+### publishPackage
+
+Publishes all metadata items in a package:
+1. Validates all items (optional)
+2. Snapshots each item's definition into `publishedDefinition`
+3. Increments the package version
+4. Sets all items to `active` state
+
+```typescript
+const result = await metadataService.publishPackage('com.acme.crm', {
+  publishedBy: 'admin-user',
+  validate: true,        // default: true
+  changeNote: 'Added opportunity fields',
+});
+
+console.log(result.success);         // true
+console.log(result.version);         // 2
+console.log(result.itemsPublished);  // 5
+console.log(result.publishedAt);     // "2025-06-01T12:00:00Z"
+```
+
+### revertPackage
+
+Reverts all metadata items in a package to their last published state. Discards any unpublished changes.
+
+```typescript
+await metadataService.revertPackage('com.acme.crm');
+// All items restored to their publishedDefinition snapshots
+```
+
+### getPublished
+
+Returns the published version of a metadata item (for runtime/end-user serving). Falls back to the current definition if the item has never been published.
+
+```typescript
+// End user sees the published version
+const published = await metadataService.getPublished('object', 'opportunity');
+
+// Designer sees the draft version (via regular get)
+const draft = await metadataService.get('object', 'opportunity');
+```
+
+### REST Endpoints
+
+| Method | Path | Description |
+|:---|:---|:---|
+| `POST` | `/packages/:id/publish` | Publish a package |
+| `POST` | `/packages/:id/revert` | Revert a package to last published state |
+| `GET` | `/metadata/:type/:name/published` | Get published version of a metadata item |

packages/metadata/README.md

@@ -86,6 +86,7 @@ The `MetadataManager` is the main orchestrator. It provides:
 - **Core CRUD**: `register`, `get`, `list`, `unregister`, `exists`, `listNames`
 - **Convenience**: `getObject`, `listObjects`
 - **Package Management**: `unregisterPackage` — unload all metadata from a package
+- **Package Publishing**: `publishPackage`, `revertPackage`, `getPublished` — atomic package-level metadata publishing
 - **Query / Search**: `query` with filtering, pagination, sorting by type/scope/state/tags
 - **Bulk Operations**: `bulkRegister`, `bulkUnregister` with error handling
 - **Import / Export**: `exportMetadata`, `importMetadata` with conflict resolution (skip/overwrite/merge)
@@ -201,6 +202,34 @@ const plugin = MetadataPlugin({
 kernel.use(plugin);
 ```
 
+## Package Publishing
+
+ObjectStack supports **package-level metadata publishing** — all metadata items within a package are published atomically.
+
+### Publish a Package
+
+```typescript
+const result = await manager.publishPackage('com.acme.crm', {
+  publishedBy: 'admin',
+  validate: true,
+});
+// result: { success: true, version: 2, itemsPublished: 5, publishedAt: '...' }
+```
+
+### Revert to Last Published State
+
+```typescript
+await manager.revertPackage('com.acme.crm');
+// All items restored to their publishedDefinition snapshots
+```
+
+### Get Published Version (Runtime Serving)
+
+```typescript
+const published = await manager.getPublished('object', 'opportunity');
+// Returns publishedDefinition if exists, else current definition
+```
+
 ## Package Structure
 
 ```