FN-6200: document plugin-gated built-in workflows

Explain how bundled workflows stay hidden until their required plugin is installed.

- document the plugin-gated built-in workflow model in the plugin authoring guide
- show the core gating map and workflow visibility rules for listing and lookup
- note that the Compound Engineering built-in workflow appears only while its plugin is installed

Files changed:
 docs/PLUGIN_AUTHORING.md             | 48 ++++++++++++++++++++++++++++++++++++
 docs/plugins/compound-engineering.md |  6 +++++
 2 files changed, 54 insertions(+)

Fusion-Task-Id: FN-6200

Fusion-Task-Lineage: 72c64220-aef9-4f6b-92c3-5f53e67292fc

docs/PLUGIN_AUTHORING.md

@@ -1692,6 +1692,54 @@ the `plugin:<pluginId>:<extensionId>` form, and values must be JSON objects. If
 the extension is registered and declares a `configSchema`, the engine validates
 the metadata fields during IR validation.
 
+## 16.7. Plugin-Gated Built-in Workflows
+
+Plugin-gated built-in workflows are read-only workflow definitions that ship in
+Fusion's `BUILTIN_WORKFLOWS` array but stay hidden until their associated plugin
+is installed. For example, `builtin:compound-engineering` is bundled with core so
+it can be selected like any other built-in workflow, but it references
+Compound Engineering plugin skills that do not exist unless the plugin is active.
+
+Runtime gating is declared in `packages/core/src/builtin-workflows.ts`. The
+`PLUGIN_GATED_BUILTIN_WORKFLOWS` map links each gated built-in workflow id to the
+plugin id that unlocks it:
+
+```typescript
+// In packages/core/src/builtin-workflows.ts
+const PLUGIN_GATED_BUILTIN_WORKFLOWS: ReadonlyMap<string, string> = new Map([
+  ["builtin:compound-engineering", "fusion-plugin-compound-engineering"],
+]);
+```
+
+When the dashboard or API lists workflow definitions, `listWorkflowDefinitions()`
+checks each built-in with `isBuiltinWorkflowPluginGated()` and then calls
+`isPluginInstalled()` for the required plugin before including it. Direct lookup
+uses the same rule: `getWorkflowDefinition()` returns `undefined` for a gated
+built-in until `getRequiredPluginIdForBuiltinWorkflow()` resolves to an installed
+plugin.
+
+The workflow-definition cache is invalidated on plugin register/unregister
+events, so installing or removing a plugin updates the visible workflow list
+immediately. Gated built-ins are also excluded from
+`defaultEnabledBuiltinWorkflowIds()`: they are never enabled by default and only
+surface when the gating plugin is present.
+
+Use this pattern when a first-party built-in workflow references plugin-provided
+skills, tools, workflow handlers, or other runtime capabilities that would be
+missing without the plugin. The gate prevents users from selecting a workflow
+that cannot run in their project.
+
+The current first-party example is `builtin:compound-engineering`, which is gated
+on `fusion-plugin-compound-engineering`. It does not appear in the workflow
+picker or task workflow selection until the Compound Engineering plugin is
+installed and enabled; if the plugin is uninstalled, the workflow is hidden
+again.
+
+> **Plugin author note:** plugin-gated built-in workflows are currently for
+> first-party, bundled workflows because the gating map lives in `@fusion/core`.
+> Plugin authors who want to add their own workflow behavior should use the
+> workflow step contribution API in §16 or workflow extensions in §16.6 instead.
+
 ## 17. Contributing Prompt Modifications
 
 Prompt contributions let a plugin inject additional instructions into specific prompt surfaces.

docs/plugins/compound-engineering.md

@@ -14,6 +14,12 @@ When installed and enabled, the plugin registers the **Compound Engineering**
 dashboard view destination and installs its bundled `ce-*` skills into a
 plugin-local, discoverable directory (never a global `~/.claude/skills` path).
 
+**Built-in workflow gating:** the `builtin:compound-engineering` workflow is
+hidden from the workflow picker and task workflow selection until this plugin is
+installed and enabled. Once the plugin is active, the workflow appears
+automatically alongside other built-in workflows — no additional configuration is
+needed. If the plugin is uninstalled, the workflow is hidden again.
+
 ## Dashboard view
 
 The Compound Engineering view is registered as a primary plugin destination