docs: sync protocol / releases / ui docs with implementation (#1880 Wave 1, batch 6)

30 docs audited AND adversarially verified (protocol, releases, ui); 28 carry
fixes — 103 fixes total, 8 of them verifier repairs (the adversarial pass
caught and corrected wrong audit edits, e.g. a bad `permissionSet:` stack key
→ `permissions:`, and a fabricated projection "id/audit columns" claim).

Highlights:
- protocol/kernel/*: removed the fabricated `definePlugin()` / `defineObject()`
  helpers (use ObjectSchema.create) and corrected `defineView` imports to
  `@objectstack/spec/ui`; aspirational manifest/lifecycle blocks left in place
  where the page already discloses them as design-intent.
- protocol/knowledge: driver-turso / knowledge-turso are cloud-only (not
  open-core) → replaced with open-core-appropriate driver-mongodb / llamaindex.
- releases/v13,v15 + objectql/* + ui/*: import-path, key-name, and example fixes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012urEihGTAsQP2xizAqfCwt

Author: claude

content/docs/protocol/kernel/i18n-standard.mdx

@@ -69,6 +69,15 @@ i18n.t('messages.welcome', 'en', { name: 'John' }); // Translation + interpolati
 
 ObjectStack automatically determines the user's locale using a **fallback chain**:
 
+<Callout type="warn">
+**Partial implementation.** The server resolves the *request* locale from the
+`Accept-Language` header (highest-priority entry), then a `?locale=` query
+parameter, then the i18n service's default locale — see `extractLocale` in
+`packages/rest/src/rest-server.ts`. The DB-persisted **user preference**,
+**tenant default**, and **IP geolocation** steps shown below are design intent:
+there is no geolocation or tenant-locale resolution in the runtime today.
+</Callout>
+
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │ 1. USER PREFERENCE                                          │
@@ -618,7 +627,10 @@ export const Account = ObjectSchema.create({
 
     industry: Field.select({
       label: 'account.fields.industry',
-      options: 'account.industries',  // Translation key for options array
+      options: [
+        { value: 'technology', label: 'account.industries.technology' },
+        { value: 'finance', label: 'account.industries.finance' },
+      ],
     }),
   },
 });
@@ -633,10 +645,10 @@ export const Account = ObjectSchema.create({
     "name": "Account Name",
     "industry": "Industry"
   },
-  "industries": [
-    { "value": "technology", "label": "Technology" },
-    { "value": "finance", "label": "Finance" }
-  ]
+  "industries": {
+    "technology": "Technology",
+    "finance": "Finance"
+  }
 }
 ```
 
@@ -651,25 +663,16 @@ locale.
 ObjectUI automatically translates labels, placeholders, and error messages:
 
 ```typescript
-// View definition
+// View definition — `defineView` takes a container of named views
+// ({ list, form, listViews, formViews }); a flat { name, type, ... }
+// object is rejected at build time.
 export default defineView({
-  name: 'account_list',
-  object: 'account',
-  type: 'list',
-  
-  layout: {
-    title: 'account.list.title',  // Translation key
+  list: {
+    type: 'grid',
+    label: 'account.list.title', // Translation key (i18n label)
+    data: { provider: 'object', object: 'account' },
     columns: [
-      {
-        field: 'name',
-        // Label auto-translated from ObjectQL field definition
-      },
-    ],
-    actions: [
-      {
-        type: 'create',
-        label: 'account.actions.create',  // Translation key
-      },
+      'name', // Column label auto-translated from the ObjectQL field definition
     ],
   },
 });
@@ -764,6 +767,13 @@ Output:
 
 ### Translation Service Integration
 
+<Callout type="warn">
+**Design intent — not yet implemented.** `i18n.translationService` is **not** a
+recognized key on `TranslationConfigSchema`
+(`packages/spec/src/system/translation.zod.ts`), and no auto-translate provider
+integration ships today. The snippet below describes planned behaviour.
+</Callout>
+
 ObjectStack integrates with professional translation services:
 
 ```typescript

content/docs/protocol/kernel/index.mdx

@@ -151,8 +151,8 @@ os package publish dist/objectstack.json --env <environment-id> --install
 
 **Kernel Approach:**
 ```yaml
-# plugin.manifest.yml
-name: @mycompany/billing
+# manifest block in objectstack.config.ts (via defineStack)
+id: com.mycompany.billing
 version: 2.0.0
 dependencies:
   '@objectstack/core': '^2.0.0'
@@ -212,7 +212,7 @@ const config = context.config.resolve('stripe.apiKey', {
 **Challenge:** Build a plugin marketplace like Salesforce AppExchange where third-party developers sell integrations.
 
 **Kernel Solution:**
-- **Plugin Manifest:** Standardized `plugin.manifest.yml` declares what plugin provides and needs
+- **Package Manifest:** The `manifest` block in `objectstack.config.ts` (compiled to `objectstack.json`) declares what a package provides and needs
 - **Dependency Resolution:** Automatic validation that plugin versions are compatible with core platform
 - **Lifecycle Hooks:** `onInstall`, `onEnable`, `onDisable` hooks for setup/teardown
 - **Sandboxing:** Plugins can't access each other's data or crash each other
@@ -277,7 +277,7 @@ hooks in order, and exposes the resulting services through DI.
 
 ### 2. Request Handling
 ```typescript
-// Incoming API request: GET /api/accounts/123
+// Incoming API request: GET /api/v1/data/account/123
 async function handleRequest(req) {
   // Kernel provides context
   const context = await Kernel.createContext({
@@ -354,17 +354,19 @@ permissions.grant('admin', 'accounts', 'read');
 
 **Good (Declarative):**
 ```yaml
-# plugin.manifest.yml
+# objectstack.config.ts — declared via defineStack({ ... })
 objects:
   - name: account
     fields:
       - name: name
         type: text
+# PermissionSet grants use allow* flags (not role/object/access)
 permissions:
-  - role: admin
-    object: account
-    access: read
-# Kernel ensures runtime matches manifest
+  - name: account_read
+    objects:
+      account:
+        allowRead: true
+# Kernel ensures runtime matches the declared metadata
 ```
 
 ### Idempotent Operations
@@ -375,8 +377,8 @@ Run `os package publish` 100 times → Same result.
 
 ### Version Control Everything
 All system configuration lives in Git:
-- Plugin manifests: `plugin.manifest.yml`
-- Configuration files: `objectstack.config.yml`
+- Stack definition & manifest: `objectstack.config.ts` (via `defineStack`)
+- Compiled artifact: `dist/objectstack.json`
 - Translation bundles: `i18n/en.json`, `i18n/de.json`
 
 **Business Value:** Rollback a bad deployment by reverting Git commit. No database state to recover, no manual cleanup.
@@ -385,18 +387,15 @@ All system configuration lives in Git:
 
 ### Plugin Development
 ```bash
-# Scaffold new plugin
+# Scaffold new plugin (created under packages/plugins/plugin-<name>/)
 os create plugin slack-integration
 
 # Generated structure:
-slack-integration/
-  plugin.manifest.yml    # Metadata, dependencies, version
+packages/plugins/plugin-slack-integration/
+  package.json     # name, version, dependencies (@objectstack/spec, zod)
+  tsconfig.json
   src/
-    objects/             # ObjectQL schemas
-    views/               # ObjectUI layouts
-    actions/             # Business logic
-    i18n/                # Translations
-  tests/
+    index.ts       # default-export Plugin object (name, version, initialize, destroy)
   README.md
 ```
 

content/docs/protocol/kernel/lifecycle.mdx

@@ -153,8 +153,8 @@ await kernel.bootstrap();
 ```
 
 **Resolution Strategy:**
-1. **failOnPluginError: true** (default): Boot fails, process exits with code 1
-2. **failOnPluginError: false**: Boot continues, failed plugin is disabled and logged
+1. **rollbackOnFailure: true** (default): Boot fails, already-started plugins roll back, process exits with code 1
+2. **rollbackOnFailure: false**: Boot continues, the failed plugin is skipped and logged
 
 ## Plugin Installation
 
@@ -275,61 +275,45 @@ async function resolveDependencies(
 Plugins can define hooks that run at specific lifecycle events:
 
 ```typescript
-// plugin.manifest.ts
-export default definePlugin({
+// plugin.ts — a plugin is a plain default-exported object (there is no
+// `definePlugin` helper). Lifecycle hooks are top-level methods, each
+// receiving a single PluginContext ({ ql, os, logger, config, pluginId }).
+export default {
   name: '@vendor/salesforce',
   version: '3.2.1',
-  
-  lifecycle: {
-    // Runs before installation begins
-    preInstall: async ({ context, transaction }) => {
-      // Validate environment
-      if (!context.config.get('salesforce.apiKey')) {
-        throw new Error('Salesforce API key not configured');
-      }
-    },
-    
-    // Runs after installation completes
-    postInstall: async ({ context, transaction }) => {
-      // Initialize default data
-      await context.db.insert('salesforce_settings', {
-        syncInterval: 3600, // 1 hour
-        enabled: true,
-      }, { transaction });
-      
-      // Schedule sync job
-      await context.scheduler.create({
-        name: 'salesforce-sync',
-        schedule: '0 * * * *', // Every hour
-        handler: 'salesforce.sync',
-      }, { transaction });
-    },
-    
-    // Runs when plugin is enabled
-    onEnable: async ({ context }) => {
-      logger.info('Salesforce sync enabled');
-      await context.eventBus.publish('salesforce.enabled');
-    },
-    
-    // Runs when plugin is disabled
-    onDisable: async ({ context }) => {
-      logger.info('Salesforce sync disabled');
-      await context.scheduler.pause('salesforce-sync');
-    },
-    
-    // Runs before uninstallation
-    preUninstall: async ({ context, transaction }) => {
-      // Clean up jobs
-      await context.scheduler.delete('salesforce-sync', { transaction });
-    },
-    
-    // Runs after uninstallation
-    postUninstall: async ({ context, transaction }) => {
-      // Optional: Remove plugin data
-      await context.db.delete('salesforce_settings', {}, { transaction });
-    },
+
+  // Runs once, when the plugin is installed
+  onInstall: async (context) => {
+    // Validate environment. `config` is a plain record, not a store.
+    if (!context.config['salesforce.apiKey']) {
+      throw new Error('Salesforce API key not configured');
+    }
+    context.logger.info('Salesforce plugin installed');
   },
-});
+
+  // Runs when the plugin is enabled (at startup or manually)
+  onEnable: async (context) => {
+    context.logger.info('Salesforce sync enabled');
+  },
+
+  // Runs when the plugin is disabled (at shutdown or manually)
+  onDisable: async (context) => {
+    context.logger.info('Salesforce sync disabled');
+  },
+
+  // Runs once, when the plugin is uninstalled
+  onUninstall: async (context) => {
+    context.logger.info('Removing Salesforce plugin data');
+  },
+
+  // Runs when the plugin version changes. Receives an UpgradeContext with
+  // previousVersion, newVersion, and isMajorUpgrade.
+  onUpgrade: async (context) => {
+    context.logger.info(
+      `Salesforce ${context.previousVersion} → ${context.newVersion}`,
+    );
+  },
+};
 ```
 
 ### Installation CLI
@@ -505,10 +489,13 @@ export async function down(db: any): Promise<void> {
 }
 ```
 
-Run migrations through your existing Knex / driver tooling — ObjectStack does not
-ship its own migration runner. The intent of `os generate migration` is to give
-you a hand-off file you can commit, review, and execute via the database tools
-your team already uses.
+Run the generated files through your existing Knex / driver tooling — ObjectStack
+does not execute these generated migration files for you. (To apply
+metadata-driven schema changes directly, without generating files, ObjectStack
+does ship first-party `os migrate plan` / `os migrate apply` commands that
+reconcile the physical database to your object definitions.) The intent of
+`os generate migration` is to give you a hand-off file you can commit, review,
+and execute via the database tools your team already uses.
 
 #### Schema safety
 
@@ -584,18 +571,22 @@ ObjectStack includes **built-in health monitoring** to validate system state.
 ### Health Check Endpoints
 
 ```
-GET /health/live
-  → 200 if process is alive
-  → 503 if process is dead/hung
-
-GET /health/ready
-  → 200 if ready to accept requests
-  → 503 if still booting or unhealthy
+GET /health
+  → 200 with { status, version, uptime } if the process is alive (liveness)
 
-GET /health/status
-  → Detailed health report (JSON)
+GET /ready
+  → 200 if the kernel is running and ready to accept requests (readiness)
+  → 503 while still booting or shutting down
 ```
 
+<Callout type="info">
+`GET /health` returns a compact liveness body (`status`, `version`, `uptime`) and
+`GET /ready` returns readiness. The richer per-subsystem report and the
+plugin-declared custom checks below describe the internal health-monitor model
+(`PluginHealthMonitor`) — they are **not yet** exposed as a dedicated HTTP
+endpoint or as a declarative plugin field.
+</Callout>
+
 ### Health Status Response
 
 ```json
@@ -639,10 +630,10 @@ GET /health/status
 Plugins can register custom health checks:
 
 ```typescript
-// Plugin registers health check
-export default definePlugin({
+// Plugin registers a custom health check (internal health-monitor model)
+export default {
   name: '@vendor/salesforce',
-  
+
   healthChecks: {
     salesforce_connection: async ({ context }) => {
       try {
@@ -662,7 +653,7 @@ export default definePlugin({
       }
     },
   },
-});
+};
 ```
 
 ## Shutdown Sequence
@@ -761,7 +752,7 @@ Don't assume success. Monitor health checks for 5-10 minutes after upgrade.
 ```bash
 # Automated monitoring
 objectstack upgrade @vendor/salesforce --monitor --duration 300
-# Watches /health/status for 5 minutes, auto-rollback if unhealthy
+# Watches /health for 5 minutes, auto-rollback if unhealthy
 ```
 
 ### 5. Document Breaking Changes

content/docs/protocol/kernel/metadata-service.mdx

@@ -64,7 +64,7 @@ Loaders adapt different storage backends to a common interface.
 | **FilesystemLoader** | `filesystem` | Reads/Writes `.json`, `.yaml`, `.ts` files from disk. Primary for development. |
 | **MemoryLoader** | `memory` | Hydrates compiled artifact items into the runtime metadata registry. |
 | **DatabaseLoader** | `database` | Stores metadata revisions in control-plane services that explicitly configure it. Not auto-enabled by ObjectStack. |
-| **RemoteLoader** | `http` | Fetches metadata from a remote API or git repository. |
+| **RemoteLoader** | `http` | Fetches metadata from a remote HTTP API. |
 
 ### 3. Granular Capabilities
 
@@ -234,6 +234,6 @@ The canonical `MetadataManagerConfigSchema` and `MetadataFallbackStrategySchema`
 
 The Metadata Service is designed to power the CLI.
 
-- **`objectstack compile`**: Validates TypeScript metadata and emits `dist/objectstack.json`.
-- **`objectstack publish`**: Uploads compiled JSON to the control plane, which creates a metadata revision and artifact.
-- **`objectstack dev`**: Boots ObjectStack from local files or the compiled artifact without a control-plane connection.
+- **`os compile`**: Validates TypeScript metadata and emits `dist/objectstack.json`.
+- **`os package publish`**: Uploads the compiled `dist/objectstack.json` artifact to the control plane as a versioned package.
+- **`os dev`**: Boots ObjectStack from local files or the compiled artifact without a control-plane connection.