Expand plugin host surface (#5205)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies
> - The plugin system is the extension boundary for optional product
capabilities
> - Rich plugins need more than a worker entrypoint: they need scoped
database storage, local project folders, managed agents/routines, host
navigation, and reusable UI components
> - The LLM Wiki work exposed those missing host surfaces while keeping
plugin code outside the core control plane
> - This pull request expands the core plugin host, SDK, server APIs,
and UI bridge so plugins can declare and use those surfaces
> - The benefit is that future plugins can integrate with Paperclip
through documented, validated contracts instead of bespoke server or UI
imports

## What Changed

- Added plugin-managed database namespaces and migration tracking,
including Drizzle schema/migration files and SQL validation for
namespace isolation.
- Added server support for plugin local folders, managed agents, managed
routines, scoped plugin APIs, and plugin operation visibility.
- Expanded shared plugin manifest/types/validators and SDK
host/testing/UI exports for richer plugin surfaces.
- Added reusable UI pieces for file trees, managed routines, resizable
sidebars, route sidebars, and plugin bridge initialization.
- Updated plugin docs and example plugins to use the expanded host and
SDK surface.

## Verification

- `pnpm install --frozen-lockfile`
- `pnpm run preflight:workspace-links && pnpm exec vitest run
packages/shared/src/validators/plugin.test.ts
server/src/__tests__/plugin-database.test.ts
server/src/__tests__/plugin-local-folders.test.ts
server/src/__tests__/plugin-managed-agents.test.ts
server/src/__tests__/plugin-managed-routines.test.ts
server/src/__tests__/plugin-orchestration-apis.test.ts
ui/src/api/plugins.test.ts ui/src/components/FileTree.test.tsx
ui/src/components/ResizableSidebarPane.test.tsx
ui/src/pages/PluginPage.test.tsx ui/src/plugins/bridge.test.ts` passed:
11 files, 67 tests.
- Confirmed this PR changes 89 files and does not include
`pnpm-lock.yaml` or `.github/workflows/*`.

## Risks

- Medium: this expands plugin host contracts across db/shared/server/ui
and includes a new core migration (`0076_useful_elektra.sql`).
- The plugin database namespace validator is intentionally restrictive;
plugin authors may need follow-up affordances for SQL patterns that
remain blocked.
- Merge this before the LLM Wiki plugin PR so the plugin can resolve the
new SDK and host APIs.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex, GPT-5 coding agent, tool-enabled shell/git/GitHub
workflow. Context window size was not exposed by the runtime.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

ui/src/pages/PluginPage.tsx

@@ -5,7 +5,11 @@ import { useCompany } from "@/context/CompanyContext";
 import { useBreadcrumbs } from "@/context/BreadcrumbContext";
 import { pluginsApi } from "@/api/plugins";
 import { queryKeys } from "@/lib/queryKeys";
-import { PluginSlotMount } from "@/plugins/slots";
+import {
+  PluginSlotMount,
+  resolveRouteSidebarSlot,
+  type ResolvedPluginSlot,
+} from "@/plugins/slots";
 import { Button } from "@/components/ui/button";
 import { ArrowLeft } from "lucide-react";
 import { NotFoundPage } from "./NotFound";
@@ -19,11 +23,14 @@ import { NotFoundPage } from "./NotFound";
  * @see doc/plugins/PLUGIN_SPEC.md §24.4 — Company-Context Plugin Page
  */
 export function PluginPage() {
-  const { companyPrefix: routeCompanyPrefix, pluginId, pluginRoutePath } = useParams<{
+  const params = useParams<{
     companyPrefix?: string;
     pluginId?: string;
     pluginRoutePath?: string;
+    "*": string | undefined;
   }>();
+  const { companyPrefix: routeCompanyPrefix, pluginId, pluginRoutePath } = params;
+  const pluginRouteSplat = params["*"];
   const { companies, selectedCompanyId } = useCompany();
   const { setBreadcrumbs } = useBreadcrumbs();
   const routeCompany = useMemo(() => {
@@ -89,14 +96,33 @@ export function PluginPage() {
     [resolvedCompanyId, companyPrefix],
   );
 
+  // When the active route has a routeSidebar slot, the sidebar provides the
+  // back affordance, but the top bar still needs a route-specific title.
+  const routeSidebarActive = useMemo(() => {
+    if (!pluginRoutePath || !contributions) return false;
+    const flattened: ResolvedPluginSlot[] = contributions.flatMap((contribution) =>
+      contribution.slots.map((slot) => ({
+        ...slot,
+        pluginId: contribution.pluginId,
+        pluginKey: contribution.pluginKey,
+        pluginDisplayName: contribution.displayName,
+        pluginVersion: contribution.version,
+      })),
+    );
+    return resolveRouteSidebarSlot(flattened, pluginRoutePath) !== null;
+  }, [contributions, pluginRoutePath]);
+
   useEffect(() => {
-    if (pageSlot) {
-      setBreadcrumbs([
-        { label: "Plugins", href: "/instance/settings/plugins" },
-        { label: pageSlot.pluginDisplayName },
-      ]);
+    if (!pageSlot) return;
+    if (routeSidebarActive) {
+      setBreadcrumbs([{ label: resolveRouteSidebarPageTitle(pageSlot, pluginRouteSplat) }]);
+      return;
     }
-  }, [pageSlot, companyPrefix, setBreadcrumbs]);
+    setBreadcrumbs([
+      { label: "Plugins", href: "/instance/settings/plugins" },
+      { label: pageSlot.pluginDisplayName },
+    ]);
+  }, [pageSlot, pluginRouteSplat, setBreadcrumbs, routeSidebarActive]);
 
   if (!resolvedCompanyId) {
     if (hasInvalidCompanyPrefix) {
@@ -137,14 +163,16 @@ export function PluginPage() {
 
   return (
     <div className="space-y-4">
-      <div className="flex items-center gap-2">
-        <Button variant="ghost" size="sm" asChild>
-          <Link to={companyPrefix ? `/${companyPrefix}/dashboard` : "/dashboard"}>
-            <ArrowLeft className="h-4 w-4 mr-1" />
-            Back
-          </Link>
-        </Button>
-      </div>
+      {!routeSidebarActive && (
+        <div className="flex items-center gap-2">
+          <Button variant="ghost" size="sm" asChild>
+            <Link to={companyPrefix ? `/${companyPrefix}/dashboard` : "/dashboard"}>
+              <ArrowLeft className="h-4 w-4 mr-1" />
+              Back
+            </Link>
+          </Button>
+        </div>
+      )}
       <PluginSlotMount
         slot={pageSlot}
         context={context}
@@ -154,3 +182,42 @@ export function PluginPage() {
     </div>
   );
 }
+
+function resolveRouteSidebarPageTitle(pageSlot: ResolvedPluginSlot, routeSplat: string | undefined): string {
+  const title = titleFromRouteSplat(routeSplat);
+  return title ?? pageSlot.displayName ?? pageSlot.pluginDisplayName;
+}
+
+function titleFromRouteSplat(routeSplat: string | undefined): string | null {
+  const segments = (routeSplat ?? "")
+    .split("/")
+    .filter(Boolean)
+    .map(decodeRouteSegment);
+  if (segments.length === 0) return null;
+
+  if (segments[0] === "page" && segments.length > 1) {
+    return titleFromPath(segments.slice(1).join("/"), { preserveCase: true });
+  }
+
+  return titleFromPath(segments[0] ?? null);
+}
+
+function titleFromPath(path: string | null | undefined, options: { preserveCase?: boolean } = {}): string | null {
+  const trimmed = path?.trim();
+  if (!trimmed) return null;
+  const basename = trimmed.split("/").filter(Boolean).at(-1) ?? trimmed;
+  const withoutNamespace = basename.split("::").at(-1) ?? basename;
+  const withoutExtension = withoutNamespace.replace(/\.[^.]+$/, "");
+  const normalized = withoutExtension.replace(/[-_]+/g, " ").trim();
+  if (!normalized) return null;
+  if (options.preserveCase) return normalized;
+  return normalized.replace(/\b\w/g, (char) => char.toUpperCase());
+}
+
+function decodeRouteSegment(segment: string): string {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}