@cat-factory/app 0.198.0 → 0.199.0

package/README.md

@@ -267,7 +267,12 @@ by its `when(gates)` predicate (the same reactive gates service the nav uses, fi
 ## Extending the layer (consumer modules)
 
 A deployment can contribute its own components — result windows, nav entries, inspector
-panels, agent-kind palette data — **without forking**, through the auto-imported
+panels, agent-kind palette data — plus two DATA-only seams that need no components at all:
+its own applications in an **External tools** sidebar section (`externalTools`, each
+resolving its URL from the acting user / open workspace / this board's custom fields) and the
+**custom workspace metadata fields** those resolvers read (`workspaceMetadataFields`, edited
+on the Metadata tab of Workspace settings). All of it **without forking**, through the
+auto-imported
 `registerAppModule` seam (the frontend analogue of the backend's `registerAgentKind` /
 `registerGate` registries). The authoring walkthrough, the reusable shared building blocks
 (`ResultWindowShell`, the `StepRunMeta` run-metadata block, `useResultView`, …), and the

package/app/components/layout/BoardToolbar.vue

@@ -242,7 +242,7 @@ const decisionItems = computed(() =>
     <IconButton
       v-for="item in toolbarItems"
       :key="item.id"
-      :label="t(item.labelKey)"
+      :label="item.label ?? t(item.labelKey)"
       :icon="item.icon"
       color="neutral"
       variant="ghost"

package/app/components/layout/CommandBar.vue

@@ -139,10 +139,14 @@ const commands = computed<Command[]>(() => {
   const asCommand = (g: (typeof commandGroups.value)[number]): Command[] =>
     g.items.map((ci) => ({
       id: ci.item.id,
-      label: t(ci.labelKey),
+      // A contribution whose copy is deployment DATA (a registered external tool's title)
+      // carries a literal `label`; catalog destinations resolve their key. Running a tool's
+      // own name through `t()` would show the raw name plus a missing-key warning.
+      label: ci.item.label ?? t(ci.labelKey),
       group: t(g.labelKey),
       icon: ci.item.icon,
-      keywords: ci.keywordsKey ? t(ci.keywordsKey) : undefined,
+      // The description doubles as fuzzy-match keywords for a tool, which has no keyword key.
+      keywords: ci.keywordsKey ? t(ci.keywordsKey) : ci.item.description,
       run: () => invoke(ci.item),
     }))
   const groupOrEmpty = (name: (typeof commandGroups.value)[number]['group']) => {
@@ -154,6 +158,8 @@ const commands = computed<Command[]>(() => {
     ...groupOrEmpty('repositories'),
     ...groupOrEmpty('integrations'),
     ...dynamicIntegrationCommands.value,
+    // The deployment's own applications (the `externalTools` slot, projected onto nav items).
+    ...groupOrEmpty('externalTools'),
     ...groupOrEmpty('workspace'),
     ...groupOrEmpty('account'),
   ]

package/app/components/layout/SideBar.vue

@@ -17,6 +17,7 @@ import LanguageSwitcher from '~/components/layout/LanguageSwitcher.vue'
 import UiModeSwitcher from '~/components/layout/UiModeSwitcher.vue'
 import UserMenu from '~/components/auth/UserMenu.vue'
 import { useViewport } from '~/composables/useViewport'
+import type { NavContribution } from '~/modular/nav-contributions'
 
 const { t } = useI18n()
 
@@ -37,6 +38,26 @@ const ui = useUiStore()
 // or connection flips, so this shell no longer hand-rolls per-item `show*` computeds.
 const { sidebarGroups, invoke } = useNavContributions()
 
+/**
+ * A destination's visible label: catalog copy for a first-party item, the LITERAL `label` for
+ * one whose copy is deployment data (a registered external tool's title). A tool's name is not
+ * a catalog key — the deployment ships whatever locales it needs in its own catalog — so
+ * running it through `t()` would render the raw name back with a missing-key warning.
+ */
+function navLabel(item: NavContribution): string {
+  return item.label ?? t(item.labelKey)
+}
+
+/**
+ * The hover tooltip. In the rail it names the destination (the label is hidden); expanded it
+ * carries the item's `description` when it has one, which is how an external tool explains
+ * what it is without a second line in the sidebar.
+ */
+function navTitle(item: NavContribution, railed: boolean): string | undefined {
+  if (railed) return item.description ? `${navLabel(item)}: ${item.description}` : navLabel(item)
+  return item.description
+}
+
 // `isCompact` (< lg) is the breakpoint at which the navbar is an off-canvas drawer;
 // above it the aside is static and the drawer flag is inert.
 const { isCompact } = useViewport()
@@ -235,12 +256,12 @@ watch(
               :square="railed"
               class="w-full"
               :class="railed ? 'justify-center' : 'justify-start'"
-              :aria-label="railed ? t(item.labelKey) : undefined"
-              :title="railed ? t(item.labelKey) : undefined"
+              :aria-label="railed ? navLabel(item) : undefined"
+              :title="navTitle(item, railed)"
               :data-testid="item.testId"
               @click="invoke(item)"
             >
-              <span v-if="!railed">{{ t(item.labelKey) }}</span>
+              <span v-if="!railed">{{ navLabel(item) }}</span>
             </UButton>
           </div>
         </section>

package/app/components/settings/WorkspaceMetadataSettings.vue

@@ -0,0 +1,151 @@
+<script setup lang="ts">
+// Workspace settings: the values for the CUSTOM metadata fields a deployment declares in code
+// (the `workspaceMetadataFields` slot — see `modular/workspace-metadata.ts`). The fields come
+// from the registry; the values are per workspace and land in the settings row's `metadata`
+// bag, where external-tool URL resolvers read them ("open the map editor on this board's game").
+//
+// A deployment that declares NOTHING never gets here — the panel's tab exists only where fields
+// are declared, so an unwired capability is invisible rather than an empty tab everywhere. The
+// empty state below is therefore the loud one: fields WERE declared and every one was rejected
+// (a malformed key), which must not look like a deployment that declared none.
+import { reactive, watch } from 'vue'
+import { useReactiveSlots } from '@modular-vue/runtime'
+import {
+  metadataDraftFrom,
+  metadataPatchFrom,
+  resolveMetadataFields,
+} from '~/modular/workspace-metadata'
+import type { WorkspaceMetadataFieldDefinition } from '~/modular/workspace-metadata'
+import type { AppSlots } from '~/modular/slots'
+
+const { t } = useI18n()
+const slots = useReactiveSlots<AppSlots>()
+const store = useWorkspaceSettingsStore()
+const toast = useToast()
+
+/**
+ * The fields to render. A malformed key is dropped (the store would refuse every save) and
+ * NAMED in the console rather than swallowed — the deployment author is the only person who
+ * can fix it, and a silently missing field looks exactly like one nobody declared.
+ */
+const fields = computed<WorkspaceMetadataFieldDefinition[]>(() => {
+  const { fields: valid, rejected } = resolveMetadataFields(
+    (slots.value.workspaceMetadataFields ?? []) as WorkspaceMetadataFieldDefinition[],
+  )
+  if (import.meta.dev && rejected.length > 0) {
+    console.warn(
+      '[cat-factory] workspace metadata fields dropped (invalid or duplicate key):',
+      rejected.map((f) => f.key),
+    )
+  }
+  return valid
+})
+
+// Local editable copy, re-seeded whenever the stored settings are replaced (the store always
+// reassigns the ref, so tracking the object reference is enough).
+const draft = reactive<Record<string, string>>({})
+watch(
+  [() => store.settings, fields],
+  () => {
+    const next = metadataDraftFrom(fields.value, store.settings.metadata)
+    for (const key of Object.keys(draft)) delete draft[key]
+    Object.assign(draft, next)
+  },
+  { immediate: true },
+)
+
+const saving = ref(false)
+
+async function save() {
+  saving.value = true
+  try {
+    // `metadataPatchFrom` carries any stored key this build does not render back into the
+    // patch: the update REPLACES the bag, so a value written under a retired field would
+    // otherwise be deleted by an unrelated save.
+    await store.update({
+      metadata: metadataPatchFrom(fields.value, draft, store.settings.metadata),
+    })
+    toast.add({
+      title: t('settings.workspaceSettings.toast.saved'),
+      icon: 'i-lucide-check',
+      color: 'success',
+    })
+  } catch (e) {
+    toast.add({
+      title: t('settings.workspaceSettings.toast.saveFailed'),
+      description: e instanceof Error ? e.message : String(e),
+      icon: 'i-lucide-triangle-alert',
+      color: 'error',
+    })
+  } finally {
+    saving.value = false
+  }
+}
+
+/** A `select` field's items, with an explicit "not set" choice so a value can be cleared. */
+function selectItems(field: WorkspaceMetadataFieldDefinition) {
+  return [
+    { label: t('settings.workspaceSettings.metadata.unset'), value: '' },
+    ...(field.options ?? []).map((o) => ({ label: o.label, value: o.value })),
+  ]
+}
+</script>
+
+<template>
+  <div class="space-y-6" data-testid="workspace-metadata-settings">
+    <section class="space-y-2">
+      <h3 class="text-sm font-semibold text-slate-200">
+        {{ t('settings.workspaceSettings.metadata.heading') }}
+      </h3>
+      <p class="text-[11px] text-slate-400">
+        {{ t('settings.workspaceSettings.metadata.body') }}
+      </p>
+    </section>
+
+    <p v-if="fields.length === 0" class="text-[11px] text-slate-500">
+      {{ t('settings.workspaceSettings.metadata.empty') }}
+    </p>
+
+    <template v-else>
+      <div class="space-y-4">
+        <label v-for="field in fields" :key="field.key" class="block">
+          <!-- Field labels are deployment DATA, rendered verbatim (see the module docs). -->
+          <span class="mb-1 block text-[10px] uppercase tracking-wide text-slate-500">
+            {{ field.label }}
+          </span>
+          <USelect
+            v-if="field.type === 'select'"
+            v-model="draft[field.key]"
+            :items="selectItems(field)"
+            size="sm"
+            :data-testid="`workspace-metadata-${field.key}`"
+          />
+          <UInput
+            v-else
+            v-model="draft[field.key]"
+            :type="field.type === 'number' ? 'number' : 'text'"
+            :placeholder="field.placeholder"
+            size="sm"
+            :data-testid="`workspace-metadata-${field.key}`"
+          />
+          <span v-if="field.description" class="mt-1 block text-[11px] text-slate-500">
+            {{ field.description }}
+          </span>
+        </label>
+      </div>
+
+      <div class="flex justify-end">
+        <UButton
+          color="primary"
+          size="sm"
+          icon="i-lucide-save"
+          :loading="saving"
+          data-testid="workspace-metadata-save"
+          @click="save"
+        >
+          {{ t('common.save') }}
+        </UButton>
+      </div>
+    </template>
+  </div>
+</template>

package/app/components/settings/WorkspaceSettingsPanel.vue

@@ -5,9 +5,12 @@
 //   - Merge thresholds: the auto-merge preset library.
 //   - Issue tracker: filing-tracker selection + linking sources + writeback.
 //   - Service best practices: the default fragments new services inherit.
+//   - Metadata: values for the custom workspace fields the DEPLOYMENT declares in code (read
+//     by external-tool URL resolvers); present only where any are declared.
 // The latter three are body-only section components rendered in tabs here (no longer
 // standalone modals).
 import { reactive, ref, watch } from 'vue'
+import { useReactiveSlots } from '@modular-vue/runtime'
 import type { ReviewFrictionMode, TaskLimitMode } from '~/types/domain'
 import RiskPolicyPanel from '~/components/settings/RiskPolicyPanel.vue'
 import IssueTrackerPanel from '~/components/settings/IssueTrackerPanel.vue'
@@ -15,7 +18,9 @@ import ServiceFragmentDefaultsPanel from '~/components/settings/ServiceFragmentD
 import BudgetSettings from '~/components/settings/BudgetSettings.vue'
 import UsageSettings from '~/components/settings/UsageSettings.vue'
 import WorkspaceMembersSettings from '~/components/layout/WorkspaceMembersSettings.vue'
+import WorkspaceMetadataSettings from '~/components/settings/WorkspaceMetadataSettings.vue'
 import IntegrationBackTitle from '~/components/layout/IntegrationBackTitle.vue'
+import type { AppSlots } from '~/modular/slots'
 
 const { t, te } = useI18n()
 const ui = useUiStore()
@@ -23,6 +28,13 @@ const store = useWorkspaceSettingsStore()
 const workspace = useWorkspaceStore()
 const access = useWorkspaceAccess()
 const toast = useToast()
+const slots = useReactiveSlots<AppSlots>()
+
+// The Metadata tab exists only where the deployment DECLARES custom fields — an unwired
+// capability is invisible, not an empty tab in every deployment. Declared-but-malformed fields
+// still open the tab: it carries the empty state (and the console warning names the keys), so a
+// broken declaration surfaces instead of looking like one nobody wrote.
+const hasMetadataFields = computed(() => (slots.value.workspaceMetadataFields ?? []).length > 0)
 
 const open = computed({
   get: () => ui.workspaceSettingsOpen,
@@ -74,6 +86,16 @@ const tabs = computed(() => [
     icon: 'i-lucide-book-open-check',
     slot: 'fragments',
   },
+  ...(hasMetadataFields.value
+    ? [
+        {
+          value: 'metadata',
+          label: t('settings.workspaceSettings.tabs.metadata'),
+          icon: 'i-lucide-tags',
+          slot: 'metadata',
+        },
+      ]
+    : []),
   // Roster + access-mode management is `members.manage` (workspace admins only). Hidden
   // for everyone else — the backend 403s the writes and the tab has nothing to read.
   ...(access.canManageMembers.value
@@ -517,6 +539,11 @@ async function save() {
           <ServiceFragmentDefaultsPanel />
         </template>
 
+        <!-- Custom workspace metadata (only where the deployment declares fields) -->
+        <template v-if="hasMetadataFields" #metadata>
+          <WorkspaceMetadataSettings />
+        </template>
+
         <!-- Members (workspace RBAC roster + access mode; admins only) -->
         <template v-if="access.canManageMembers.value && workspace.workspaceId" #members>
           <WorkspaceMembersSettings :workspace-id="workspace.workspaceId" />

package/app/composables/useNavContributions.ts

@@ -1,6 +1,9 @@
 import { computed } from 'vue'
 import { useReactiveSlots } from '@modular-vue/runtime'
 import { groupCommands, groupSidebar, sortToolbar } from '~/modular/nav-contributions'
+import { EXTERNAL_TOOL_UNAVAILABLE_KEYS, projectExternalTools } from '~/modular/external-tools'
+import { toMetadataBag } from '~/modular/workspace-metadata'
+import type { ExternalToolContext, ExternalToolContribution } from '~/modular/external-tools'
 import type {
   AppSlots,
   CommandGroup,
@@ -23,6 +26,14 @@ import type {
 export function useNavContributions() {
   const slots = useReactiveSlots<AppSlots>()
   const ui = useUiStore()
+  // Resolved through the Nuxt app's global i18n instance rather than `useI18n()` (which needs
+  // an active component instance) — the same handle, and the same reason, as
+  // `usePipelineErrorToast`: nothing about this composable should depend on WHERE it is called.
+  const { t } = useNuxtApp().$i18n as ReturnType<typeof useI18n>
+  const toast = useToast()
+  const auth = useAuthStore()
+  const workspace = useWorkspaceStore()
+  const workspaceSettings = useWorkspaceSettingsStore()
 
   // First-party action ids → host handlers. Typed as an exhaustive
   // `Record<NavActionId, …>`, so a catalog `action` with no handler (or a handler
@@ -65,7 +76,86 @@ export function useNavContributions() {
     if (item.action) actions[item.action]?.()
   }
 
-  const all = computed<NavContribution[]>(() => slots.value.nav ?? [])
+  /**
+   * The stored metadata bag, re-hung on a null prototype. A resolver is a DEPLOYMENT'S own code
+   * writing `ctx.metadata.gameId`, so the object it reads has to answer `undefined` for an
+   * unfilled field whatever that field is called — `constructor` and `toString` both pass the
+   * key pattern, and on a plain object both read as an inherited function. A `computed` rather
+   * than a copy per read, so the reference stays stable between settings changes.
+   */
+  const externalToolMetadata = computed(() => toMetadataBag(workspaceSettings.settings.metadata))
+
+  /**
+   * The invocation context an external tool's resolver reads. GETTERS, not a captured snapshot,
+   * so a resolver called at click time sees the workspace/metadata as they are NOW — a teammate
+   * can fill in the field the tool needs while this sidebar is open, and the click must then
+   * work rather than repeat a message about a fix that already happened. (They also keep the
+   * projection below reactive: reading a store inside the computed tracks it.)
+   */
+  const externalToolContext: ExternalToolContext = {
+    get userId() {
+      return auth.user?.id ?? null
+    },
+    get userEmail() {
+      return auth.user?.email ?? null
+    },
+    get workspaceId() {
+      return workspace.workspaceId ?? ''
+    },
+    get workspaceName() {
+      return workspace.activeWorkspace?.name ?? ''
+    },
+    get metadata() {
+      return externalToolMetadata.value
+    },
+  }
+
+  /**
+   * Registered external tools, projected onto nav contributions. The `externalTools` slot is
+   * already RBAC/tier-filtered by `navSlotFilter`, exactly like `nav`.
+   *
+   * A tool that can't currently resolve stays in the list and explains itself on click: the
+   * person looking at the sidebar is usually the one who can fix it (fill in the field), and
+   * hiding it would make an unconfigured workspace look like a deployment that never
+   * registered the tool.
+   */
+  const externalToolItems = computed<NavContribution[]>(() =>
+    projectExternalTools(
+      (slots.value.externalTools ?? []) as ExternalToolContribution[],
+      externalToolContext,
+      {
+        // A separate browsing context, with `noopener` so the opened page cannot reach back
+        // into this one through `window.opener`.
+        open: (url) => window.open(url, '_blank', 'noopener,noreferrer'),
+        onUnavailable: (resolution, tool) => {
+          // A resolver that threw is the one refusal the toast can't fully explain: the person
+          // reading it can't act on a stack trace, and the deployment author who can isn't
+          // here. So the message says which tool is broken and the cause goes to the console —
+          // unconditionally, not behind `import.meta.dev`, because this is an exception being
+          // absorbed and the deployment debugging it is a built one.
+          if (resolution.reason === 'resolver-failed') {
+            console.error(
+              `[cat-factory] external tool "${tool.id}" URL resolver threw`,
+              resolution.cause,
+            )
+          }
+          toast.add({
+            title: t('externalTools.unavailable.title', { tool: tool.title }),
+            description: t(EXTERNAL_TOOL_UNAVAILABLE_KEYS[resolution.reason], {
+              fields: resolution.missing.join(', '),
+            }),
+            icon: 'i-lucide-triangle-alert',
+            color: 'warning',
+          })
+        },
+      },
+    ).map((item) => item.contribution),
+  )
+
+  const all = computed<NavContribution[]>(() => [
+    ...(slots.value.nav ?? []),
+    ...externalToolItems.value,
+  ])
 
   /** Grouped + ordered sidebar sections, empty sections dropped. */
   const sidebarGroups = computed<SidebarGroup[]>(() => groupSidebar(all.value))

package/app/composables/usePipelineErrorToast.ts

@@ -220,6 +220,10 @@ const CONFLICT_INFO: Record<Exclude<ConflictReason, BespokeConflictReason>, Conf
     titleKey: 'errors.conflict.title.pipeline_schedule_requires_recurring',
     descriptionKey: 'errors.conflict.description.pipeline_schedule_requires_recurring',
   },
+  foundational_service_exists: {
+    titleKey: 'errors.conflict.title.foundational_service_exists',
+    descriptionKey: 'errors.conflict.description.foundational_service_exists',
+  },
   pipeline_schedule_intake_unconfigured: {
     titleKey: 'errors.conflict.title.pipeline_schedule_intake_unconfigured',
     descriptionKey: 'errors.conflict.description.pipeline_schedule_intake_unconfigured',

package/app/docs/consumer-extensions.md

@@ -56,16 +56,18 @@ export default defineNuxtPlugin(() => {
 
 ## The landed seams
 
-| Seam                                | Slot key          | Entry shape                                                                                      | Host                                                                 |
-| ----------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
-| Run-detail windows                  | `resultViews`     | `{ id: '<ns>:<name>', component }`                                                               | `StepResultViewHost` via `dispatchStepView`                          |
-| Agent kinds (palette data)          | `agentKinds`      | `{ kind, container, presentation: { label, icon, color, description, category?, resultView? } }` | agents store merge → `agentKindMeta`                                 |
-| Custom task types                   | `taskTypes`       | `{ taskType: '<ns>:<name>', presentation, fields?, defaultPipelineId?, formPanel? }`             | `AddTaskModal` picker/fields + `TaskCard` badge (via `taskTypeMeta`) |
-| Sidebar / command-palette / toolbar | `nav`             | `{ id, labelKey, icon, surfaces, gate?, advanced?, run, sidebar?, command?, toolbar? }`          | the three shells via `useNavContributions`                           |
-| Inspector body panels               | `inspectorPanels` | `{ id, component, when(block), order }` (`PanelEntry<Block>`)                                    | `<PanelsOutlet>` in `InspectorPanel`                                 |
-| Top-level overlays                  | `appOverlays`     | `{ id: '<ns>:<name>', component }`                                                               | `<AppOverlayHost>` via `useAppOverlays().open(id)`                   |
-| Multi-step wizards                  | (journeys)        | `registerJourney` + step modules                                                                 | `<JourneyHost>` / `<JourneyOutlet>`                                  |
-| Locale strings                      | (i18n)            | `i18n/locales/*.json` in the deployment                                                          | `@nuxtjs/i18n` layer deep-merge                                      |
+| Seam                                | Slot key                  | Entry shape                                                                                      | Host                                                                      |
+| ----------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
+| Run-detail windows                  | `resultViews`             | `{ id: '<ns>:<name>', component }`                                                               | `StepResultViewHost` via `dispatchStepView`                               |
+| Agent kinds (palette data)          | `agentKinds`              | `{ kind, container, presentation: { label, icon, color, description, category?, resultView? } }` | agents store merge → `agentKindMeta`                                      |
+| Custom task types                   | `taskTypes`               | `{ taskType: '<ns>:<name>', presentation, fields?, defaultPipelineId?, formPanel? }`             | `AddTaskModal` picker/fields + `TaskCard` badge (via `taskTypeMeta`)      |
+| Sidebar / command-palette / toolbar | `nav`                     | `{ id, labelKey, icon, surfaces, gate?, advanced?, run, sidebar?, command?, toolbar? }`          | the three shells via `useNavContributions`                                |
+| Inspector body panels               | `inspectorPanels`         | `{ id, component, when(block), order }` (`PanelEntry<Block>`)                                    | `<PanelsOutlet>` in `InspectorPanel`                                      |
+| Top-level overlays                  | `appOverlays`             | `{ id: '<ns>:<name>', component }`                                                               | `<AppOverlayHost>` via `useAppOverlays().open(id)`                        |
+| External tools                      | `externalTools`           | `{ id, title, icon, url, description?, requiredMetadata?, gate?, advanced?, order? }`            | the "External tools" sidebar section + palette, via `useNavContributions` |
+| Custom workspace metadata fields    | `workspaceMetadataFields` | `{ key, label, description?, placeholder?, type?, options?, order? }`                            | the Metadata tab of Workspace settings                                    |
+| Multi-step wizards                  | (journeys)                | `registerJourney` + step modules                                                                 | `<JourneyHost>` / `<JourneyOutlet>`                                       |
+| Locale strings                      | (i18n)                    | `i18n/locales/*.json` in the deployment                                                          | `@nuxtjs/i18n` layer deep-merge                                           |
 
 A `nav` entry may also declare `advanced: true`, which hides it in **basic** interface mode
 (the shipped default) exactly as it does for the first-party destinations — see
@@ -103,6 +105,70 @@ show the panel, and `order` places it among the built-ins. Your panel component
 selected block via `usePanelSubject<Block>()` (`@modular-vue/core`). `when` must tolerate a
 nullish subject (the boot-time validation resolve passes `null`).
 
+### External tools + workspace metadata (`externalTools`, `workspaceMetadataFields`)
+
+Put your OWN web applications — a map editor, an asset pipeline, an admin console — in the
+sidebar's **External tools** section, and open each one _already scoped to what the user is
+looking at_. That second half is the point of the seam; a static link needs no registration.
+
+```ts
+externalTools: [
+  {
+    id: 'acme:map-editor',
+    title: 'Map editor',                       // literal copy: a tool's name is DATA, not a key
+    description: 'Edit the level geometry for this project.',
+    icon: 'i-lucide-map',
+    requiredMetadata: ['gameId'],
+    url: (ctx) => {
+      // Build, don't splice: every value here is operator-typed text (see below).
+      const url = new URL('https://maps.acme.dev/edit')
+      url.searchParams.set('game', ctx.metadata.gameId ?? '')
+      url.searchParams.set('ws', ctx.workspaceId)
+      return url.toString()
+    },
+  },
+],
+workspaceMetadataFields: [{ key: 'gameId', label: 'Game id', placeholder: 'zork' }],
+```
+
+- **`url` is a string or a RESOLVER** `(ctx) => string | null`. The context carries `userId`,
+  `userEmail`, `workspaceId`, `workspaceName` and `metadata` — the custom workspace fields you
+  declared. It is read at CLICK time, so a value a teammate fills in while the sidebar is open
+  takes effect without a reload.
+- **Clicking opens a separate page** (`target=_blank`, `noopener`). The resolved URL must be
+  `http(s)`: anything else is refused rather than handed to the browser, because the string
+  reaches `window.open` and a `javascript:` URL would run in the SPA's own origin.
+- **Declare `requiredMetadata` for the fields your resolver needs.** An unconfigured workspace
+  then gets "fill in `gameId` on the Metadata tab" instead of a generic failure — and the tool
+  stays LISTED, because the person looking at the sidebar is usually the one who can fix it. A
+  resolver that returns `null` reports separately ("this tool gave no address"), since that one
+  is yours to fix, not the operator's.
+- **Treat every `ctx.metadata` value as untrusted input.** A workspace admin types these in, so a
+  value is operator-supplied text that happens to be length-bounded — not a constant you chose.
+  Set it as a query parameter or an `encodeURIComponent`'d path segment, as above. Never build the
+  ORIGIN from one: `` `https://${ctx.metadata.region}.acme.dev` `` with `region` set to
+  `evil.com/x?a=` resolves to a URL on someone else's host, and the `http(s)` allow-list cannot
+  tell that apart from the link you meant.
+- **A resolver that THROWS costs only its own item.** It is caught and reported as a fourth
+  reason (`resolver-failed`) with the cause logged to the console — the sidebar, the palette and
+  the toolbar all render from one catalog, so an uncaught throw would otherwise blank all three.
+  Do not rely on it: `requiredMetadata` is how you say a field must be there.
+- **`gate` and `advanced`** work exactly as on a `nav` entry; both must pass.
+
+**The metadata half** is a deployment-declared FIELD list (here) whose VALUES are per workspace,
+typed in under _Workspace settings → Metadata_ and persisted on the workspace settings row. The
+tab appears only where a deployment declares fields. Keys must be identifier-shaped
+(`^[A-Za-z][A-Za-z0-9_.-]{0,63}$` — the backend refuses anything else); a malformed or duplicate
+key is dropped with a dev-console warning rather than rendered. `type: 'select'` renders a picker
+over your `options`; everything is stored as a string.
+
+Two rules the editor keeps, and any other writer of the bag should too: a CLEARED field drops its
+key (so "unset" never reads as "set to nothing" in a resolver), and a save carries through any
+stored key the current build does not declare — the update replaces the whole bag, so a value
+written under a field you have since retired must not be deleted by an unrelated save.
+
+Values are readable anywhere in the SPA via `useWorkspaceSettingsStore().settings.metadata`.
+
 ### Custom task types (`taskTypes`)
 
 Model a proprietary work item — an "incident", "pentest", "compliance-audit" — as a first-class