frontend-plugin-api: deprecate multiple attachment points and document api pattern

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

packages/frontend-plugin-api/report.api.md

@@ -1206,6 +1206,9 @@ export type ExtensionDefinitionAttachTo<
       id?: never;
     }
   | ExtensionInput<UParentInputs>
+  /**
+   * @deprecated Multiple attachment points are deprecated and will be removed in a future release. Use a Utility API instead to share functionality across multiple locations. See https://backstage.io/docs/frontend-system/architecture/27-sharing-extensions for migration guidance.
+   */
   | Array<
       | {
           id: string;

packages/frontend-plugin-api/src/wiring/createExtension.ts

@@ -152,7 +152,7 @@ export type VerifyExtensionAttachTo<
  * const page = ParentBlueprint.make({ ... });
  * const child = ChildBlueprint.make({ attachTo: page.inputs.children });
  *
- * // Attach to multiple parents at once
+ * // Attach to multiple parents at once (deprecated - use Utility APIs instead)
  * [
  *   { id: 'page/home', input: 'widgets' },
  *   { relative: { kind: 'page' }, input: 'widgets' },
@@ -167,6 +167,9 @@ export type ExtensionDefinitionAttachTo<
   | { id: string; input: string; relative?: never }
   | { relative: { kind?: string; name?: string }; input: string; id?: never }
   | ExtensionInput<UParentInputs>
+  /**
+   * @deprecated Multiple attachment points are deprecated and will be removed in a future release. Use a Utility API instead to share functionality across multiple locations. See https://backstage.io/docs/frontend-system/architecture/27-sharing-extensions for migration guidance.
+   */
   | Array<
       | { id: string; input: string; relative?: never }
       | {