every plugin route renders a workspace, and it is not a rule you can forget

an exclusionary rule, made structural. a plugin does not render a screen: it
contributes panels and says how they are arranged, and the shell renders
WorkspaceView around them.

    web/panels.ts   appRegistryMetas — at least one panel
    web/layout.ts   defaultLayout — how they are arranged

both required the moment web/ exists, and missing either is refused at discovery
by name and with the reason. tested:

    probeplug: has a web/ directory but is missing web/layout.ts.
    Every plugin route renders a Workspace: contribute panels and a layout,
    not a screen.

there is deliberately no way to export a component. one that could would be free
to render a bare div, a full-page form, or its own navigation, and the platform
would become a shell hosting strangers' layouts rather than one application.
non-compliance is not so much refused as unrepresentable — there is nowhere to
put a screen.

the shell registers <prefix> and <prefix>/:section, exactly as the core screens
do, so a plugin's sections stay addressable and cmd-clickable, and panels read
useParams independently rather than passing state between themselves.
appTypes.allowed is pinned to that plugin's own keys, so a persisted layout
naming something else falls back instead of rendering another plugin's panel
inside this screen.

the example plugin is rebuilt to model it — two panels, a layout, one of them
calling its own /api/example/ping through useClient — because the reference
implementation is what everyone copies.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

plugins/example/web/ExampleDetail.tsx

@@ -0,0 +1,23 @@
+import { useParams } from 'react-router';
+
+// The second panel, reading the URL rather than being told by its sibling.
+//
+// The shell registers `<prefix>` and `<prefix>/:section`, so a plugin's sections are addressable,
+// linkable and cmd-clickable — the same convention every core screen follows. Panels read `useParams`
+// independently; nothing is passed between them, so they cannot disagree.
+export const ExampleDetail = () => {
+  const { section } = useParams();
+
+  return (
+    <div className="h-full overflow-auto p-6">
+      <h2 className="text-lg font-semibold text-duck-dark">Detail</h2>
+      <p className="mt-1 text-sm text-duck-dark/60">
+        Section from the URL: <code>{section ?? '(none)'}</code>
+      </p>
+      <p className="mt-3 text-xs text-duck-dark/40">
+        Try <code>/example/anything</code> — this panel reads it from <code>useParams</code>, with no state passed from
+        the panel beside it.
+      </p>
+    </div>
+  );
+};

plugins/example/web/ExampleOverview.tsx

@@ -0,0 +1,27 @@
+import { useClient } from 'hooks/useClient';
+import { useQuery } from '@tanstack/react-query';
+
+// A panel, not a screen. It gets whatever space the layout gives it and knows nothing about routing.
+//
+// `useClient` comes from the platform's workspace packages, resolved because a plugin lives inside the
+// repository — no publishing, no version negotiation. This is the whole plugin↔host API in one line.
+export const ExampleOverview = () => {
+  const client = useClient();
+  const { data, isLoading } = useQuery({
+    queryKey: ['example', 'ping'],
+    queryFn: () => client.get<{ plugin: string; ok: boolean }>('/example/ping'),
+  });
+
+  return (
+    <div className="h-full overflow-auto p-6">
+      <h2 className="text-lg font-semibold text-duck-dark">Example</h2>
+      <p className="mt-1 text-sm text-duck-dark/60">
+        A panel from <code>plugins/example/web/</code>, rendered by the shell's <code>WorkspaceView</code>.
+      </p>
+      <div className="mt-4 rounded-md border border-duck-dark/10 bg-duck-dark/[0.02] p-3 font-mono text-xs">
+        <div className="mb-1 text-duck-dark/50">GET /api/example/ping</div>
+        {isLoading ? <span className="text-duck-dark/40">…</span> : <span>{JSON.stringify(data)}</span>}
+      </div>
+    </div>
+  );
+};

plugins/example/web/Router.tsx

@@ -1,36 +0,0 @@
-import { Routes, Route, Link } from 'react-router';
-
-// The plugin's own router, mounted by the shell at `<prefix>/*` — so everything below this point is the
-// plugin's, and react-router nests it natively. The shell knows the prefix; this file does not need to.
-
-const Home = () => (
-  <div className="p-8">
-    <h1 className="text-xl font-semibold text-duck-dark">Example plugin</h1>
-    <p className="mt-2 text-sm text-duck-dark/60">
-      Rendered from <code>plugins/example/web/Router.tsx</code>, compiled into the shell's bundle by the generated{' '}
-      <code>Plugins.gen.tsx</code>.
-    </p>
-    <Link className="mt-4 inline-block text-sm text-duck-teal underline" to="/example/deeper">
-      A nested route →
-    </Link>
-  </div>
-);
-
-const Deeper = () => (
-  <div className="p-8">
-    <h1 className="text-xl font-semibold text-duck-dark">Nested</h1>
-    <p className="mt-2 text-sm text-duck-dark/60">Proof the wildcard mount hands the whole subtree to the plugin.</p>
-    <Link className="mt-4 inline-block text-sm text-duck-teal underline" to="/example">
-      ← back
-    </Link>
-  </div>
-);
-
-export default function ExampleRouter() {
-  return (
-    <Routes>
-      <Route path="/" element={<Home />} />
-      <Route path="/deeper" element={<Deeper />} />
-    </Routes>
-  );
-}

plugins/example/web/layout.ts

@@ -0,0 +1,16 @@
+import type { LayoutNode } from 'officerdev';
+
+// How this plugin's panels are arranged. The shell renders `WorkspaceView` with this as the default and
+// persists the user's version per plugin, so this is the starting arrangement rather than a fixed one.
+//
+// Every `appType` here must be a key from `panels.ts` — `appTypes.allowed` is pinned to them, so a
+// mismatch falls back rather than rendering another plugin's panel inside this screen.
+export const defaultLayout: LayoutNode = {
+  type: 'group',
+  id: 'example-root',
+  direction: 'horizontal',
+  children: [
+    { node: { type: 'panel', id: 'example-overview', appType: 'example-overview' }, size: 40 },
+    { node: { type: 'panel', id: 'example-detail', appType: 'example-detail' }, size: 60 },
+  ],
+};

plugins/example/web/panels.ts

@@ -1,10 +1,16 @@
-import { Puzzle } from 'lucide-react';
+import { Puzzle, ListTree } from 'lucide-react';
 import type { AppRegistryMeta } from 'officerdev';
-import ExampleRouter from './Router';
+import { ExampleOverview } from './ExampleOverview';
+import { ExampleDetail } from './ExampleDetail';
 
-// Panels this plugin contributes to the workspace registry. The shell passes them to `seedAppRegistry`
-// from the generated module — it never imports this file directly, because officerdev is a dependency of
-// the shell and importing upward would invert that.
+// The panels this plugin contributes. AT LEAST ONE, or discovery refuses the plugin.
+//
+// A plugin never renders a screen — the shell renders `WorkspaceView` around these, arranged by
+// `layout.ts`. That is what makes "every plugin route is a Workspace" a property of the shape rather than
+// a rule someone has to remember.
+//
+// `availableOnPanel: false` keeps them off the generic panel picker: they belong to this plugin's screen.
 export const appRegistryMetas: AppRegistryMeta[] = [
-  { key: 'example-panel', name: 'Example', icon: Puzzle, component: ExampleRouter, availableOnPanel: true },
+  { key: 'example-overview', name: 'Overview', icon: Puzzle, component: ExampleOverview, availableOnPanel: false },
+  { key: 'example-detail', name: 'Detail', icon: ListTree, component: ExampleDetail, availableOnPanel: false },
 ];