Revise and condense server specification docs

Major rewrite and condensation of ObjectOS server specification documentation. Simplifies and shortens content for audit-compliance, automation rules, integration/ETL, permission governance, plugin manifest, and workflow engine. Removes the overview (index.mdx), adds a new kernel-architecture page, and updates meta.json navigation. Focuses on protocol summaries, configuration patterns, and key concepts for each subsystem.

Author: hotlong

content/docs/specifications/server/audit-compliance.mdx

@@ -1,151 +1,23 @@
 ---
 title: Audit & Compliance
-description: The Protocol for Accountability. Field History Tracking, System Audit Trails, and Data Retention Policies.
+description: The Protocol for Accountability and Forensic Logging.
 ---
 
+For enterprise software, "Who did what and when" is non-negotiable.
 
-In the enterprise world, "Who changed this?" is the most expensive question to leave unanswered.
+## 1. Field History Tracking
+Configured per-field in the Object Schema.
+*   **Track Old/New:** Records the previous and new value.
+*   **Retention:** Definitions for how long to keep history (e.g., "10 Years").
 
-ObjectOS treats **Auditability** as a first-class citizen. Unlike frameworks where you have to manually write logs in your controllers, ObjectOS implements **Kernel-Level Auditing**. If a mutation passes through the ObjectOS engine, it *will* be logged, regardless of whether it came from the UI, the API, or a background job.
+## 2. Setup Audit Trail
+Logs all changes to **Metadata** (Schema).
+*   "User A changed the validation rule on Project."
+*   "User B deleted the 'Salary' field."
 
-## 1. Data History Tracking (Field-Level)
+## 3. Login History
+Logs every authentication attempt.
+*   **Context:** IP Address, Browser, Location, Status (Success/Fail).
 
-This mechanism tracks value changes within business records. It answers: *"Did the Deal Amount change from $10k to $5k, and who did it?"*
-
-### Configuration (Declarative)
-You do not need to write code to enable this. You simply flag the object or specific fields in the Schema.
-
-```yaml
-# objects/deal.object.yml
-name: deal
-label: Sales Deal
-enable_audit: true # Master switch
-
-fields:
-  name:
-    type: text
-  
-  amount:
-    type: currency
-    track_history: true # Track changes to this specific field
-    
-  stage:
-    type: select
-    track_history: true
-    
-  description:
-    type: textarea
-    track_history: false # Do not track large text blobs (save space)
-
-```
-
-### The History Protocol
-
-When a transaction commits, the Audit Engine calculates the **Delta** and writes to the `object_history` storage.
-
-```json
-{
-  "event_id": "evt_001",
-  "timestamp": "2026-01-20T10:00:00Z",
-  "actor": "user_123",
-  "ip_address": "192.168.1.1",
-  "object": "deal",
-  "record_id": "deal_abc",
-  "changes": [
-    {
-      "field": "amount",
-      "old_value": 10000,
-      "new_value": 5000
-    },
-    {
-      "field": "stage",
-      "old_value": "negotiation",
-      "new_value": "closed_won"
-    }
-  ]
-}
-
-```
-
-## 2. Setup Audit Trail (Metadata-Level)
-
-Beyond data, you must track changes to the **System Configuration**. This prevents "Shadow IT" modifications where an admin silently lowers security settings.
-
-ObjectOS automatically logs operations on:
-
-* **Schema:** Creating/Deleting Objects or Fields.
-* **Security:** Changing Permission Sets or Sharing Rules.
-* **Logic:** Modifying Workflows or Triggers.
-* **Users:** Password resets, Role assignments.
-
-### Example Log Entry
-
-> **User:** Alice (Admin)
-> **Action:** Permission Profile Update
-> **Target:** Sales Rep Profile
-> **Change:** `lead.export_permission` changed from `false` to `true`.
-
-## 3. Login & Access Logs
-
-For security compliance, access events are tracked separately.
-
-* **Login Success/Failure:** Tracks Timestamp, User, IP, User-Agent, and Auth Method (Password vs. SSO).
-* **API Access:** (Optional) Can be configured to log every API call for high-security environments (Warning: High Volume).
-
-## 4. Storage & Retention Policies
-
-Audit logs grow rapidly. ObjectOS provides a **Retention Protocol** to manage lifecycle cost-effectively.
-
-### Architecture
-
-Audit data is **never** stored in the same table as the transactional data.
-
-* **Hot Storage (Last 30 days):** Stored in the primary SQL DB for instant UI access.
-* **Cold Storage (Archive):** Offloaded to low-cost object storage (S3/Parquet) or a dedicated Log Service (Elasticsearch/Splunk).
-
-### Policy Configuration
-
-```yaml
-# config/audit_retention.yml
-policies:
-  - object: deal
-    retention_period: 3650 # 10 Years (Financial Regulation)
-    archive_after: 90 # Move to Cold Storage after 90 days
-    
-  - object: task
-    retention_period: 180 # 6 Months
-    purge_after: 180 # Hard delete
-
-```
-
-## 5. Compliance Features (GDPR/HIPAA)
-
-### The "Right to be Forgotten" (GDPR)
-
-When a user requests deletion, ObjectOS provides a `System.anonymize` utility.
-
-* It scrubs PII (Personally Identifiable Information) from the `users` table.
-* **Critical:** It does *not* delete the Audit Log rows (for legal integrity), but it masks the `actor` ID or replaces the name with "Anonymized User", ensuring historical integrity while respecting privacy.
-
-### Immutability
-
-The Audit Engine is designed to be **Append-Only**.
-
-* The API does not expose `UPDATE` or `DELETE` endpoints for the `audit_log` object.
-* Even System Admins cannot delete audit trails via the standard UI/API (requires direct database access, leaving its own trace).
-
-## 6. Snapshotting (Time Travel)
-
-For advanced scenarios, ObjectOS supports **Full Document Snapshotting**. Instead of storing diffs, it stores the entire JSON version of the record at every save.
-
-* **Use Case:** Legal Contracts or Medical Records where you need to "View Record exactly as it looked on Jan 1st, 2024".
-* **Config:** `enable_versioning: true`.
-
-## Summary
-
-ObjectOS Audit Protocol ensures that your application is "Enterprise Ready" out of the box.
-
-1. **Zero Code:** Just add `track_history: true`.
-2. **Granular:** Tracks specific fields, not just "Modified Date".
-3. **Governance:** Tracks the Admins (Setup Audit Trail).
-4. **Lifecycle:** Automates archiving and purging to manage database growth.
+## 4. System Log
+Debug logs for developers (Triggers, Flows).

content/docs/specifications/server/automation-rules.mdx

@@ -1,164 +1,31 @@
 ---
 title: Automation Rules
-description: The Protocol for Server-Side Logic. Database Triggers, Scheduled Jobs, and No-Code Automation Flows.
+description: The Protocol for Lightweight, Event-Driven Logic.
 ---
 
+Automation Rules differ from Workflows in that they are typically strictly **Event-Driven** and stateless.
 
-While Workflows guide a record through a lifecycle, **Automation Rules** handle the immediate logic and side effects of data changes.
-
-ObjectOS divides automation into three categories:
-1.  **Triggers (Code):** High-performance, synchronous TypeScript hooks for data integrity.
-2.  **Flows (Low-Code):** Declarative, asynchronous event chains (IFTTT style).
-3.  **Scheduled Jobs:** Time-based execution (CRON).
-
-## 1. Database Triggers (Synchronous Logic)
-
-Triggers are the "Reflexes" of the system. They intercept database operations **before** or **after** they happen. They execute within the same database transaction as the mutation.
-
-### Trigger Definition
-
-Triggers are defined in TypeScript files next to your Object definitions.
+## 1. Triggers (Code)
+Server-side scripts (TypeScript/Python) that run in the transaction transaction.
 
 ```typescript
-// triggers/order.trigger.ts
-import { Trigger } from '@objectos/types';
-
-export const validateDiscount: Trigger = {
-  name: 'validate_order_discount',
-  object: 'order',
-  on: ['create', 'update'],
-  when: 'before', // Runs before writing to DB
-  
-  handler: async ({ doc, previousDoc, session, broker }) => {
-    // 1. Logic: Discount cannot exceed 20% unless authorized
-    if (doc.discount > 0.20 && !session.hasRole('manager')) {
-      throw new Error("Discounts > 20% require Manager approval.");
+// project.trigger.ts
+export const beforeInsert = async (ctx) => {
+    if (ctx.doc.amount > 10000) {
+        ctx.doc.status = 'High Value';
     }
-
-    // 2. Logic: Auto-calculate final price
-    doc.final_price = doc.list_price * (1 - doc.discount);
-  }
 }
-
 ```
 
-### Key Capabilities
-
-* **Validation:** Throwing an error aborts the entire transaction.
-* **Computation:** Modifying `doc` directly updates the data being saved.
-* **Snapshot Access:** You have access to `doc` (new state) and `previousDoc` (old state) to detect changes (e.g., `if (doc.status !== previousDoc.status)`).
-
-## 2. Automation Flows (Declarative Logic)
-
-For logic that doesn't require hard coding, ObjectOS supports **Automation Flows**. These are defined in YAML (or built via a Visual Builder) and run **asynchronously** after the transaction commits.
-
-### The Flow Protocol
-
-```yaml
-# automations/notify_high_value_deal.yaml
-name: notify_high_value_deal
-label: Notify VP on Big Deals
-trigger:
-  type: data.changed
-  object: deal
-  condition: "doc.amount > 1000000 && doc.stage == 'closed_won'"
-
-actions:
-  - type: notification.send
-    params:
-      recipient: "role:vp_sales"
-      subject: "Big Win: ${doc.name}"
-      message: "Deal closed for ${formatCurrency(doc.amount)}!"
-
-  - type: record.create
-    params:
-      object: "audit_log"
-      data:
-        event: "big_deal_alert"
-        deal_id: "${doc._id}"
-
-```
-
-### Flow Components
-
-* **Trigger:** What starts the flow? (`data.changed`, `user.login`, `webhook.received`).
-* **Condition:** A logical expression (Expression Language) that must be true.
-* **Actions:** A sequential list of tasks (Send Email, Call API, Create Record).
-
-## 3. Scheduled Jobs (CRON)
-
-Enterprise systems need to do things when no one is watching. ObjectOS includes a distributed **Job Scheduler**.
-
-### Protocol Definition
-
-```yaml
-# jobs/monthly_invoicing.job.yml
-name: generate_monthly_invoices
-cron: "0 0 1 * *" # Run at midnight on the 1st of every month
-timeout: 3600 # 1 hour max
-retries: 3
-
-task:
-  action: "finance.batch_generate_invoices"
-  params:
-    period: "last_month"
-
-```
-
-* **Distributed:** In a cluster, the OS ensures the job runs on only **one** node (via Redis locks).
-* **Resilient:** Failed jobs are automatically retried based on the policy.
-
-## 4. Server-Side Scripting API
-
-Whether writing Triggers or Custom Actions, you interact with the ObjectOS Kernel via the standard **Broker API**. This ensures your code is safe and upgrade-proof.
-
-### The Broker Object
-
-The `broker` is your gateway to the rest of the OS.
-
-```typescript
-// Inside a Trigger or Service
-async function handler({ broker, session }) {
-  
-  // 1. Data Access (Respects Permissions)
-  const user = await broker.call('data.find', { 
-    object: 'user', 
-    id: 'u1' 
-  }, { session });
-
-  // 2. Cross-Service Calls
-  await broker.call('mail.send', { ... });
-
-  // 3. Emit Custom Events
-  broker.emit('custom.event', { foo: 'bar' });
-}
-
-```
-
-### The "Sudo" Mode
-
-Sometimes you need to bypass permissions (e.g., a system background job).
-
-```typescript
-// Create a System Session (Super Admin)
-const sudoSession = session.sudo();
-
-await broker.call('data.update', { ... }, { session: sudoSession });
-
-```
+## 2. Validation Rules (No-Code)
+Boolean expressions that block a save if they return `true`.
+Defined in the Object Schema (`validation` property).
 
-## 5. Comparison: Trigger vs. Flow vs. Workflow
+## 3. Auto-Response Rules
+Logic for sending immediate email replies (e.g., "Thanks for your Ticket").
 
-| Feature | Database Trigger | Automation Flow | Workflow (BPM) |
-| --- | --- | --- | --- |
-| **Protocol** | TypeScript | YAML / JSON | YAML / BPMN |
-| **Timing** | Synchronous (Blocking) | Asynchronous (Background) | Long-Running (Days/Weeks) |
-| **Transactional** | Yes (Can Rollback) | No (Committed) | No |
-| **Use Case** | Data Integrity, Calculations | Notifications, Sync | Approvals, Lifecycle |
-| **Complexity** | High (Code) | Low (Config) | Medium (State Machine) |
+## 4. Assignment Rules
+Logic for changing the `owner` of a record (e.g., "Round Robin" assignment for Leads).
 
-:::tip Best Practice
-Always prefer **Triggers** for data integrity (e.g., "Price cannot be negative").
-Always prefer **Workflows** for human processes (e.g., "Manager must approve").
-Use **Flows** for everything in between (e.g., "Send email on update").
-:::
+## 5. Escalation Rules
+Logic for time-based updates (e.g., "If Case not solved in 4h, notify Manager").