feat: document file changed watcher events

dist/types.d.ts

@@ -303,8 +303,14 @@ export interface FileChangedEvent extends VerstakEvent {
     name: 'file.changed';
     payload: {
         path: string;
-        size?: number;
+        title?: string;
-        changedAt: string;
+        operation: 'create' | 'update' | 'move' | 'delete' | 'external.create' | 'external.update' | 'external.delete';
+        type?: 'file' | 'folder' | 'symlink' | 'unknown';
+        workspaceRootPath?: string;
+        external?: boolean;
+        trashId?: string;
+        fromPath?: string;
+        changedAt?: string;
     };
 }
 export interface NoteSavedEvent extends VerstakEvent {

schemas/events/vault.json

@@ -150,15 +150,25 @@
     },
     {
       "name": "file.changed",
-      "description": "A file in the vault has been modified",
+      "description": "A vault file or folder has changed and file surfaces should refresh",
       "schema": {
         "type": "object",
         "properties": {
           "path": { "type": "string", "description": "File path relative to vault" },
-          "size": { "type": "integer", "description": "New file size" },
+          "title": { "type": "string", "description": "Activity title, usually the path" },
-          "changedAt": { "type": "string", "description": "ISO 8601 timestamp" }
+          "operation": {
+            "type": "string",
+            "enum": ["create", "update", "move", "delete", "external.create", "external.update", "external.delete"],
+            "description": "Change operation. external.* values come from the live vault watcher."
+          },
+          "type": { "type": "string", "enum": ["file", "folder", "symlink", "unknown"], "description": "Changed entry type when known" },
+          "workspaceRootPath": { "type": "string", "description": "Top-level workspace folder inferred from path" },
+          "external": { "type": "boolean", "description": "True when the change was observed outside the Files API" },
+          "trashId": { "type": "string", "description": "Internal trash id for restore/trash related changes" },
+          "fromPath": { "type": "string", "description": "Previous path for move operations" },
+          "changedAt": { "type": "string", "description": "ISO 8601 timestamp when supplied by event publisher" }
         },
-        "required": ["path", "changedAt"]
+        "required": ["path", "operation"]
       }
     },
     {

src/plugin-api.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from 'vitest';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import manifestSchema from '../schemas/manifest.json';
+import vaultEventsSchema from '../schemas/events/vault.json';
 import type { OpenResourceRequest, PluginManifest } from './types';
 import { createMockPluginAPI } from './test-utils';
 
@@ -47,6 +48,17 @@ describe('VerstakPluginAPI contract', () => {
     expect(permissionEnum).toContain('workbench.open');
   });
 
+  test('file.changed schema documents watcher refresh payload', () => {
+    const fileChanged = (vaultEventsSchema as any).events.find((event: any) => event.name === 'file.changed');
+
+    expect(fileChanged.schema.required).toContain('operation');
+    expect(fileChanged.schema.properties.operation.enum).toContain('external.create');
+    expect(fileChanged.schema.properties.operation.enum).toContain('external.update');
+    expect(fileChanged.schema.properties.operation.enum).toContain('external.delete');
+    expect(fileChanged.schema.properties.workspaceRootPath.type).toBe('string');
+    expect(fileChanged.schema.properties.external.type).toBe('boolean');
+  });
+
   test('official plugin manifests comply with SDK apiVersion and permission schema', () => {
     const pluginsDir = new URL('../../verstak-official-plugins/plugins/', import.meta.url);
     if (!existsSync(pluginsDir)) {

src/types.ts

@@ -395,8 +395,21 @@ export interface FileChangedEvent extends VerstakEvent {
   name: 'file.changed';
   payload: {
     path: string;
-    size?: number;
+    title?: string;
-    changedAt: string;
+    operation:
+      | 'create'
+      | 'update'
+      | 'move'
+      | 'delete'
+      | 'external.create'
+      | 'external.update'
+      | 'external.delete';
+    type?: 'file' | 'folder' | 'symlink' | 'unknown';
+    workspaceRootPath?: string;
+    external?: boolean;
+    trashId?: string;
+    fromPath?: string;
+    changedAt?: string;
   };
 }