Add plugin framework and settings UI

packages/plugins/examples/plugin-hello-world-example/README.md

@@ -0,0 +1,38 @@
+# @paperclipai/plugin-hello-world-example
+
+First-party reference plugin showing the smallest possible UI extension.
+
+## What It Demonstrates
+
+- a manifest with a `dashboardWidget` UI slot
+- `entrypoints.ui` wiring for plugin UI bundles
+- a minimal React widget rendered in the Paperclip dashboard
+- reading host context (`companyId`) from `PluginWidgetProps`
+- worker lifecycle hooks (`setup`, `onHealth`) for basic runtime observability
+
+## API Surface
+
+- This example does not add custom HTTP endpoints.
+- The widget is discovered/rendered through host-managed plugin APIs (for example `GET /api/plugins/ui-contributions`).
+
+## Notes
+
+This is intentionally simple and is designed as the quickest "hello world" starting point for UI plugin authors.
+It is a repo-local example plugin for development, not a plugin that should be assumed to ship in generic production builds.
+
+## Local Install (Dev)
+
+From the repo root, build the plugin and install it by local path:
+
+```bash
+pnpm --filter @paperclipai/plugin-hello-world-example build
+pnpm paperclipai plugin install ./packages/plugins/examples/plugin-hello-world-example
+```
+
+**Local development notes:**
+
+- **Build first.** The host resolves the worker from the manifest `entrypoints.worker` (e.g. `./dist/worker.js`). Run `pnpm build` in the plugin directory before installing so the worker file exists.
+- **Dev-only install path.** This local-path install flow assumes a source checkout with this example package present on disk. For deployed installs, publish an npm package instead of relying on the monorepo example path.
+- **Reinstall after pulling.** If you installed a plugin by local path before the server stored `package_path`, the plugin may show status **error** (worker not found). Uninstall and install again so the server persists the path and can activate the plugin:  
+  `pnpm paperclipai plugin uninstall paperclip.hello-world-example --force` then  
+  `pnpm paperclipai plugin install ./packages/plugins/examples/plugin-hello-world-example`.

packages/plugins/examples/plugin-hello-world-example/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@paperclipai/plugin-hello-world-example",
+  "version": "0.1.0",
+  "description": "First-party reference plugin that adds a Hello World dashboard widget",
+  "type": "module",
+  "private": true,
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "paperclipPlugin": {
+    "manifest": "./dist/manifest.js",
+    "worker": "./dist/worker.js",
+    "ui": "./dist/ui/"
+  },
+  "scripts": {
+    "prebuild": "node ../../../../scripts/ensure-plugin-build-deps.mjs",
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "pnpm --filter @paperclipai/plugin-sdk build && tsc --noEmit"
+  },
+  "dependencies": {
+    "@paperclipai/plugin-sdk": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.7.3"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

packages/plugins/examples/plugin-hello-world-example/src/index.ts

@@ -0,0 +1,2 @@
+export { default as manifest } from "./manifest.js";
+export { default as worker } from "./worker.js";

packages/plugins/examples/plugin-hello-world-example/src/manifest.ts

@@ -0,0 +1,39 @@
+import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+
+/**
+ * Stable plugin ID used by host registration and namespacing.
+ */
+const PLUGIN_ID = "paperclip.hello-world-example";
+const PLUGIN_VERSION = "0.1.0";
+const DASHBOARD_WIDGET_SLOT_ID = "hello-world-dashboard-widget";
+const DASHBOARD_WIDGET_EXPORT_NAME = "HelloWorldDashboardWidget";
+
+/**
+ * Minimal manifest demonstrating a UI-only plugin with one dashboard widget slot.
+ */
+const manifest: PaperclipPluginManifestV1 = {
+  id: PLUGIN_ID,
+  apiVersion: 1,
+  version: PLUGIN_VERSION,
+  displayName: "Hello World Widget (Example)",
+  description: "Reference UI plugin that adds a simple Hello World widget to the Paperclip dashboard.",
+  author: "Paperclip",
+  categories: ["ui"],
+  capabilities: ["ui.dashboardWidget.register"],
+  entrypoints: {
+    worker: "./dist/worker.js",
+    ui: "./dist/ui",
+  },
+  ui: {
+    slots: [
+      {
+        type: "dashboardWidget",
+        id: DASHBOARD_WIDGET_SLOT_ID,
+        displayName: "Hello World",
+        exportName: DASHBOARD_WIDGET_EXPORT_NAME,
+      },
+    ],
+  },
+};
+
+export default manifest;

packages/plugins/examples/plugin-hello-world-example/src/ui/index.tsx

@@ -0,0 +1,17 @@
+import type { PluginWidgetProps } from "@paperclipai/plugin-sdk/ui";
+
+const WIDGET_LABEL = "Hello world plugin widget";
+
+/**
+ * Example dashboard widget showing the smallest possible UI contribution.
+ */
+export function HelloWorldDashboardWidget({ context }: PluginWidgetProps) {
+  return (
+    <section aria-label={WIDGET_LABEL}>
+      <strong>Hello world</strong>
+      <div>This widget was added by @paperclipai/plugin-hello-world-example.</div>
+      {/* Include host context so authors can see where scoped IDs come from. */}
+      <div>Company context: {context.companyId}</div>
+    </section>
+  );
+}

packages/plugins/examples/plugin-hello-world-example/src/worker.ts

@@ -0,0 +1,27 @@
+import { definePlugin, runWorker } from "@paperclipai/plugin-sdk";
+
+const PLUGIN_NAME = "hello-world-example";
+const HEALTH_MESSAGE = "Hello World example plugin ready";
+
+/**
+ * Worker lifecycle hooks for the Hello World reference plugin.
+ * This stays intentionally small so new authors can copy the shape quickly.
+ */
+const plugin = definePlugin({
+  /**
+   * Called when the host starts the plugin worker.
+   */
+  async setup(ctx) {
+    ctx.logger.info(`${PLUGIN_NAME} plugin setup complete`);
+  },
+
+  /**
+   * Called by the host health probe endpoint.
+   */
+  async onHealth() {
+    return { status: "ok", message: HEALTH_MESSAGE };
+  },
+});
+
+export default plugin;
+runWorker(plugin, import.meta.url);

packages/plugins/examples/plugin-hello-world-example/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "lib": ["ES2023", "DOM"],
+    "jsx": "react-jsx"
+  },
+  "include": ["src"]
+}