@cat-factory/app 0.198.1 → 0.200.0

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/api/foundationalServices.ts

@@ -0,0 +1,131 @@
+import {
+  createFoundationalServiceContract,
+  deleteFoundationalServiceContract,
+  foundationalServiceSourceStatusContract,
+  getFoundationalServiceContractsContract,
+  linkFoundationalServiceSourceContract,
+  listFoundationalServiceSourcesContract,
+  listFoundationalServiceSuppressionsContract,
+  listFoundationalServicesContract,
+  resolvedFoundationalServicesContract,
+  restoreFoundationalServiceContract,
+  suppressFoundationalServiceContract,
+  syncFoundationalServiceSourceContract,
+  unlinkFoundationalServiceSourceContract,
+  updateFoundationalServiceContract,
+} from '@cat-factory/contracts'
+import type {
+  CreateFoundationalServiceInput,
+  FoundationalServiceOwnerKind,
+  LinkFoundationalServiceSourceInput,
+  UpdateFoundationalServiceInput,
+} from '~/types/domain'
+import type { ApiContext } from './context'
+
+/**
+ * The foundational-services catalog (backend/docs/adr/0031-foundational-services.md) — the shared
+ * capabilities an organisation already runs, which an Architect designs against instead of
+ * proposing a rebuild.
+ *
+ * Tiered exactly like the prompt-fragment library (`account` ⊕ `workspace`), so every route
+ * reuses the same `scope(kind, id)` prefix. Three of them are workspace-only, because they are
+ * about a tier having something ABOVE it: the merged catalog, and the suppress/restore pair
+ * that opts a board out of an inherited account service.
+ */
+export function foundationalServicesApi({ send, ws, scope }: ApiContext) {
+  return {
+    // ---- one tier's registered services (raw — not merged) ----------------
+    listFoundationalServices: (kind: FoundationalServiceOwnerKind, id: string) =>
+      send(listFoundationalServicesContract, { pathPrefix: scope(kind, id) }),
+
+    createFoundationalService: (
+      kind: FoundationalServiceOwnerKind,
+      id: string,
+      body: CreateFoundationalServiceInput,
+    ) => send(createFoundationalServiceContract, { pathPrefix: scope(kind, id), body }),
+
+    updateFoundationalService: (
+      kind: FoundationalServiceOwnerKind,
+      id: string,
+      serviceId: string,
+      body: UpdateFoundationalServiceInput,
+    ) =>
+      send(updateFoundationalServiceContract, {
+        pathPrefix: scope(kind, id),
+        pathParams: { serviceId },
+        body,
+      }),
+
+    deleteFoundationalService: (
+      kind: FoundationalServiceOwnerKind,
+      id: string,
+      serviceId: string,
+    ) =>
+      send(deleteFoundationalServiceContract, {
+        pathPrefix: scope(kind, id),
+        pathParams: { serviceId },
+      }),
+
+    // ---- the merged catalog an agent actually sees (workspace only) -------
+    getResolvedFoundationalServices: (workspaceId: string) =>
+      send(resolvedFoundationalServicesContract, { pathPrefix: ws(workspaceId) }),
+
+    /**
+     * The LAZY contract read: one service's full documents, resolved through the same tier merge
+     * a dispatch uses. Deliberately not folded into the catalog list — a document routinely runs
+     * to hundreds of kilobytes, and this surface exists so a human can check what a consumer
+     * would be handed, one service at a time.
+     */
+    getFoundationalServiceContracts: (workspaceId: string, serviceId: string) =>
+      send(getFoundationalServiceContractsContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { serviceId },
+      }),
+
+    // ---- opting a board out of an inherited account service ---------------
+    // The LIST is what makes the pair usable: a suppressed id is by construction absent from the
+    // merged catalog, so nothing else can tell the surface what to offer a restore for.
+    listFoundationalServiceSuppressions: (workspaceId: string) =>
+      send(listFoundationalServiceSuppressionsContract, { pathPrefix: ws(workspaceId) }),
+
+    suppressFoundationalService: (workspaceId: string, serviceId: string) =>
+      send(suppressFoundationalServiceContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { serviceId },
+      }),
+
+    restoreFoundationalService: (workspaceId: string, serviceId: string) =>
+      send(restoreFoundationalServiceContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { serviceId },
+      }),
+
+    // ---- repo sources of service definitions + contract files ------------
+    listFoundationalSources: (kind: FoundationalServiceOwnerKind, id: string) =>
+      send(listFoundationalServiceSourcesContract, { pathPrefix: scope(kind, id) }),
+
+    linkFoundationalSource: (
+      kind: FoundationalServiceOwnerKind,
+      id: string,
+      body: LinkFoundationalServiceSourceInput,
+    ) => send(linkFoundationalServiceSourceContract, { pathPrefix: scope(kind, id), body }),
+
+    unlinkFoundationalSource: (kind: FoundationalServiceOwnerKind, id: string, sourceId: string) =>
+      send(unlinkFoundationalServiceSourceContract, {
+        pathPrefix: scope(kind, id),
+        pathParams: { id: sourceId },
+      }),
+
+    foundationalSourceStatus: (kind: FoundationalServiceOwnerKind, id: string, sourceId: string) =>
+      send(foundationalServiceSourceStatusContract, {
+        pathPrefix: scope(kind, id),
+        pathParams: { id: sourceId },
+      }),
+
+    syncFoundationalSource: (kind: FoundationalServiceOwnerKind, id: string, sourceId: string) =>
+      send(syncFoundationalServiceSourceContract, {
+        pathPrefix: scope(kind, id),
+        pathParams: { id: sourceId },
+      }),
+  }
+}

package/app/composables/useApi.ts

@@ -16,6 +16,7 @@ import { forkDecisionApi } from './api/forkDecision'
 import { judgeApi } from './api/judge'
 import { prReviewApi } from './api/prReview'
 import { fragmentsApi } from './api/fragments'
+import { foundationalServicesApi } from './api/foundationalServices'
 import { skillsApi } from './api/skills'
 import { githubApi } from './api/github'
 import { vcsApi } from './api/vcs'
@@ -154,6 +155,7 @@ export function useApi() {
     ...environmentsApi(ctx),
     ...recurringApi(ctx),
     ...sandboxApi(ctx),
+    ...foundationalServicesApi(ctx),
     ...githubApi(ctx),
     ...vcsApi(ctx),
     ...slackApi(ctx),

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
@@ -38,6 +49,7 @@ export function useNavContributions() {
     kaizen: () => ui.openKaizen(),
     infrastructure: () => ui.openInfrastructure(),
     fragmentLibrary: () => ui.openFragmentLibrary(),
+    foundationalServices: () => ui.openFoundationalServices(),
     mergeThresholds: () => ui.openWorkspaceSettings('merge'),
     workspaceSettings: () => ui.openWorkspaceSettings(),
     modelConfiguration: () => ui.openModelConfig(),
@@ -65,7 +77,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

@@ -224,6 +224,10 @@ const CONFLICT_INFO: Record<Exclude<ConflictReason, BespokeConflictReason>, Conf
     titleKey: 'errors.conflict.title.foundational_service_exists',
     descriptionKey: 'errors.conflict.description.foundational_service_exists',
   },
+  foundational_service_not_inherited: {
+    titleKey: 'errors.conflict.title.foundational_service_not_inherited',
+    descriptionKey: 'errors.conflict.description.foundational_service_not_inherited',
+  },
   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