@atlaskit/ads-mcp 1.11.1 → 1.11.3

package/dist/es2019/tools/get-atlaskit-hooks/atlaskit-hooks.codegen.js

@@ -3,7 +3,7 @@
  *
  * Structured content hooks from design-system *.docs.tsx files
  *
- * @codegen <<SignedSource::3b66faaf90a123fa4bc5856ae6f6a17f>>
+ * @codegen <<SignedSource::3a2fe9a9152f31ebddcf3fa6102ec30b>>
  * @codegenCommand afm workspace @af/ads-ai-tooling codegen
  */
 /* eslint-disable @repo/internal/react/boolean-prop-naming-convention -- not our types */
@@ -320,7 +320,7 @@ export const atlaskitHooks = [{
   keywords: ['smart-card', 'hooks', 'useSmartLinkActions', 'actions'],
   category: 'linking',
   package: '@atlaskit/smart-card',
-  examples: ["import React, { useCallback } from 'react';\nimport Button from '@atlaskit/button/default/button';\nimport { SmartCardProvider } from '@atlaskit/link-provider/smart-card-provider';\nimport { ResolvedClient, ResolvedClientUrl } from '@atlaskit/link-test-helpers';\nimport { Box } from '@atlaskit/primitives/compiled';\nimport { Card } from '../../src';\nimport { CardAction } from '../../src/constants';\nimport { useSmartLinkActions } from '../../src/hooks';\nimport ExampleContainer from './example-container';\nconst PreviewButton = ({ url }: { url: string }) => {\n\tconst actions = useSmartLinkActions({ url, appearance: 'block' });\n\t// actions are returned in an array, find the preview action\n\tconst previewAction = actions.find((action) => action.id === 'preview-content');\n\tconst handleClick = useCallback(() => {\n\t\tif (previewAction) {\n\t\t\tpreviewAction.invoke();\n\t\t}\n\t}, [previewAction]);\n\tif (!previewAction) {\n\t\treturn null;\n\t}\n\treturn <Button onClick={handleClick}>{previewAction.text}</Button>;\n};\nconst UseSmartLinkActionsExample = (): React.JSX.Element => (\n\t<ExampleContainer>\n\t\t<SmartCardProvider client={new ResolvedClient()}>\n\t\t\t<Card\n\t\t\t\tappearance=\"block\"\n\t\t\t\turl={ResolvedClientUrl}\n\t\t\t\tactionOptions={{ hide: false, exclude: [CardAction.PreviewAction] }}\n\t\t\t/>\n\t\t\t<Box paddingBlockStart=\"space.200\">\n\t\t\t\t<PreviewButton url={ResolvedClientUrl} />\n\t\t\t</Box>\n\t\t</SmartCardProvider>\n\t</ExampleContainer>\n);\nexport default UseSmartLinkActionsExample;"]
+  examples: ["import React, { useCallback } from 'react';\nimport Button from '@atlaskit/button/default/button';\nimport { SmartCardProvider } from '@atlaskit/link-provider/smart-card-provider';\nimport {\n\tResolvedClient,\n\tResolvedClientUrl,\n} from '@atlaskit/link-test-helpers/smart-card/mocks/clients';\nimport { Box } from '@atlaskit/primitives/compiled/box';\nimport { Card } from '../../src';\nimport { CardAction } from '../../src/constants';\nimport { useSmartLinkActions } from '../../src/hooks';\nimport ExampleContainer from './example-container';\nconst PreviewButton = ({ url }: { url: string }) => {\n\tconst actions = useSmartLinkActions({ url, appearance: 'block' });\n\t// actions are returned in an array, find the preview action\n\tconst previewAction = actions.find((action) => action.id === 'preview-content');\n\tconst handleClick = useCallback(() => {\n\t\tif (previewAction) {\n\t\t\tpreviewAction.invoke();\n\t\t}\n\t}, [previewAction]);\n\tif (!previewAction) {\n\t\treturn null;\n\t}\n\treturn <Button onClick={handleClick}>{previewAction.text}</Button>;\n};\nconst UseSmartLinkActionsExample = (): React.JSX.Element => (\n\t<ExampleContainer>\n\t\t<SmartCardProvider client={new ResolvedClient()}>\n\t\t\t<Card\n\t\t\t\tappearance=\"block\"\n\t\t\t\turl={ResolvedClientUrl}\n\t\t\t\tactionOptions={{ hide: false, exclude: [CardAction.PreviewAction] }}\n\t\t\t/>\n\t\t\t<Box paddingBlockStart=\"space.200\">\n\t\t\t\t<PreviewButton url={ResolvedClientUrl} />\n\t\t\t</Box>\n\t\t</SmartCardProvider>\n\t</ExampleContainer>\n);\nexport default UseSmartLinkActionsExample;"]
 }, {
   name: 'useSmartLinkEvents',
   description: 'Hook that returns a SmartLinkEvents object for dispatching analytics events for a given URL. Currently supports insertSmartLink.',
@@ -330,19 +330,15 @@ export const atlaskitHooks = [{
   keywords: ['smart-card', 'hooks', 'analytics', 'useSmartLinkEvents', 'events'],
   category: 'linking',
   package: '@atlaskit/smart-card',
-  examples: ["import AnalyticsContext from '@atlaskit/analytics-next/AnalyticsContext';\nimport AnalyticsListener from '@atlaskit/analytics-next/AnalyticsListener';\nimport type UIAnalyticsEvent from '@atlaskit/analytics-next/UIAnalyticsEvent';\nimport Heading from '@atlaskit/heading/heading';\nimport { SmartCardProvider } from '@atlaskit/link-provider/smart-card-provider';\nimport { ResolvedClient, ResolvedClientUrl } from '@atlaskit/link-test-helpers';\nimport { Box, Text, xcss } from '@atlaskit/primitives';\nimport { Card } from '../../src';\nconst headingBoxStyles = xcss({\n\tmarginBottom: 'space.100',\n});\nconst stackBoxStyles = xcss({\n\tmarginTop: 'space.100',\n});\ntype ExampleComponentProps = {\n\tsetRecentEvents: React.Dispatch<React.SetStateAction<UIAnalyticsEvent[]>>;\n};\nconst ExampleComponent = ({ setRecentEvents }: ExampleComponentProps): JSX.Element => {\n\tconst handleOnClick = React.useCallback(\n\t\t(e: React.MouseEvent<Element, MouseEvent> | React.KeyboardEvent<Element>) => {\n\t\t\te.preventDefault();\n\t\t\treturn;\n\t\t},\n\t\t[],\n\t);\n\treturn (\n\t\t<AnalyticsListener\n\t\t\tonEvent={(event) => {\n\t\t\t\tsetRecentEvents((prevEvents) => [...prevEvents, event]);\n\t\t\t}}\n\t\t\tchannel=\"*\"\n\t\t>\n\t\t\t<AnalyticsContext\n\t\t\t\tdata={{\n\t\t\t\t\tsource: 'content',\n\t\t\t\t\tattributes: {\n\t\t\t\t\t\tdisplayCategory: 'link',\n\t\t\t\t\t\tdisplay: 'url',\n\t\t\t\t\t\tid: '123',\n\t\t\t\t\t},\n\t\t\t\t}}\n\t\t\t>\n\t\t\t\t<SmartCardProvider client={new ResolvedClient('dev')}>\n\t\t\t\t\t<Card\n\t\t\t\t\t\turl={ResolvedClientUrl}\n\t\t\t\t\t\tappearance=\"inline\"\n\t\t\t\t\t\tplatform=\"web\"\n\t\t\t\t\t\tshowHoverPreview={true}\n\t\t\t\t\t\tonClick={handleOnClick}\n\t\t\t\t\t/>\n\t\t\t\t</SmartCardProvider>\n\t\t\t</AnalyticsContext>\n\t\t</AnalyticsListener>\n\t);\n};\nexport default (): React.JSX.Element => {\n\tconst [recentEvents, setRecentEvents] = React.useState<UIAnalyticsEvent[]>([]);\n\tconst mostRecent10Events = React.useMemo(() => {\n\t\treturn Array.from({ length: 10 }, (_, i) => {\n\t\t\treturn recentEvents.at(recentEvents.length - i - 1);\n\t\t});\n\t}, [recentEvents]);\n\treturn (\n\t\t<Box>\n\t\t\t<Box xcss={headingBoxStyles}>\n\t\t\t\t<Heading size=\"medium\">Interact with the link below and see events being fired</Heading>\n\t\t\t</Box>\n\t\t\t<ExampleComponent setRecentEvents={setRecentEvents} />\n\t\t\t<Box xcss={stackBoxStyles}>\n\t\t\t\t<Heading size=\"small\">The 10 Most Recent Events Fired</Heading>\n\t\t\t\t<ol>\n\t\t\t\t\t{mostRecent10Events.map((event, index) => {\n\t\t\t\t\t\tif (event === undefined) {\n\t\t\t\t\t\t\treturn <li key={index}></li>;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tconst { action, actionSubject, eventType } = event.payload;\n\t\t\t\t\t\treturn (\n\t\t\t\t\t\t\t<li key={index}>\n\t\t\t\t\t\t\t\t<Text\n\t\t\t\t\t\t\t\t\tkey={index}\n\t\t\t\t\t\t\t\t>{`actionSubject: ${actionSubject}, action: ${action}, eventType: ${eventType}`}</Text>\n\t\t\t\t\t\t\t</li>\n\t\t\t\t\t\t);\n\t\t\t\t\t})}\n\t\t\t\t</ol>\n\t\t\t</Box>\n\t\t</Box>\n\t);\n};"]
+  examples: ["import AnalyticsContext from '@atlaskit/analytics-next/AnalyticsContext';\nimport AnalyticsListener from '@atlaskit/analytics-next/AnalyticsListener';\nimport type UIAnalyticsEvent from '@atlaskit/analytics-next/UIAnalyticsEvent';\nimport { cssMap } from '@atlaskit/css';\nimport Heading from '@atlaskit/heading/heading';\nimport { SmartCardProvider } from '@atlaskit/link-provider/smart-card-provider';\nimport {\n\tResolvedClient,\n\tResolvedClientUrl,\n} from '@atlaskit/link-test-helpers/smart-card/mocks/clients';\nimport { Box } from '@atlaskit/primitives/compiled/box';\nimport { Text } from '@atlaskit/primitives/compiled/text';\nimport { token } from '@atlaskit/tokens';\nimport { Card } from '../../src';\nconst styles = cssMap({\n\theading: { marginBottom: token('space.100') },\n\tstack: { marginTop: token('space.100') },\n});\ntype ExampleComponentProps = {\n\tsetRecentEvents: React.Dispatch<React.SetStateAction<UIAnalyticsEvent[]>>;\n};\nconst ExampleComponent = ({ setRecentEvents }: ExampleComponentProps): JSX.Element => {\n\tconst handleOnClick = React.useCallback(\n\t\t(e: React.MouseEvent<Element, MouseEvent> | React.KeyboardEvent<Element>) => {\n\t\t\te.preventDefault();\n\t\t\treturn;\n\t\t},\n\t\t[],\n\t);\n\treturn (\n\t\t<AnalyticsListener\n\t\t\tonEvent={(event) => {\n\t\t\t\tsetRecentEvents((prevEvents) => [...prevEvents, event]);\n\t\t\t}}\n\t\t\tchannel=\"*\"\n\t\t>\n\t\t\t<AnalyticsContext\n\t\t\t\tdata={{\n\t\t\t\t\tsource: 'content',\n\t\t\t\t\tattributes: {\n\t\t\t\t\t\tdisplayCategory: 'link',\n\t\t\t\t\t\tdisplay: 'url',\n\t\t\t\t\t\tid: '123',\n\t\t\t\t\t},\n\t\t\t\t}}\n\t\t\t>\n\t\t\t\t<SmartCardProvider client={new ResolvedClient('dev')}>\n\t\t\t\t\t<Card\n\t\t\t\t\t\turl={ResolvedClientUrl}\n\t\t\t\t\t\tappearance=\"inline\"\n\t\t\t\t\t\tplatform=\"web\"\n\t\t\t\t\t\tshowHoverPreview={true}\n\t\t\t\t\t\tonClick={handleOnClick}\n\t\t\t\t\t/>\n\t\t\t\t</SmartCardProvider>\n\t\t\t</AnalyticsContext>\n\t\t</AnalyticsListener>\n\t);\n};\nexport default (): React.JSX.Element => {\n\tconst [recentEvents, setRecentEvents] = React.useState<UIAnalyticsEvent[]>([]);\n\tconst mostRecent10Events = React.useMemo(() => {\n\t\treturn Array.from({ length: 10 }, (_, i) => {\n\t\t\treturn recentEvents.at(recentEvents.length - i - 1);\n\t\t});\n\t}, [recentEvents]);\n\treturn (\n\t\t<Box>\n\t\t\t<Box xcss={styles.heading}>\n\t\t\t\t<Heading size=\"medium\">Interact with the link below and see events being fired</Heading>\n\t\t\t</Box>\n\t\t\t<ExampleComponent setRecentEvents={setRecentEvents} />\n\t\t\t<Box xcss={styles.stack}>\n\t\t\t\t<Heading size=\"small\">The 10 Most Recent Events Fired</Heading>\n\t\t\t\t<ol>\n\t\t\t\t\t{mostRecent10Events.map((event, index) => {\n\t\t\t\t\t\tif (event === undefined) {\n\t\t\t\t\t\t\treturn <li key={index}></li>;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tconst { action, actionSubject, eventType } = event.payload;\n\t\t\t\t\t\treturn (\n\t\t\t\t\t\t\t<li key={index}>\n\t\t\t\t\t\t\t\t<Text\n\t\t\t\t\t\t\t\t\tkey={index}\n\t\t\t\t\t\t\t\t>{`actionSubject: ${actionSubject}, action: ${action}, eventType: ${eventType}`}</Text>\n\t\t\t\t\t\t\t</li>\n\t\t\t\t\t\t);\n\t\t\t\t\t})}\n\t\t\t\t</ol>\n\t\t\t</Box>\n\t\t</Box>\n\t);\n};"]
 }, {
   name: 'useAgentSessions',
   description: 'Reads normalized account-scoped Rovo agent sessions and keeps the Relay result current after lifecycle events.',
   status: 'general-availability',
-  usageGuidelines: ['Call inside a RelayEnvironmentProvider and pass accountId with cloudId unless the host already has a Rovo activation ID.', 'Render from the ready result and preserve backend session state for product-owned presentation rather than inventing replacement labels.', 'Use the exported types entrypoint for AgentSessionsOptions, AgentSessionsResult, and normalized session contracts.'],
+  usageGuidelines: ['Read inside AgentSessionsScopeProvider and AgentSessionsDataProvider under the host Relay environment. Pass identity only to the scope provider.', 'Render from the ready result and preserve backend session state for product-owned presentation rather than inventing replacement labels.', 'Use the exported types entrypoint for AgentSessionsScope, AgentSessionsResult, and normalized session contracts.'],
   keywords: ['rovo', 'agent sessions', 'relay', 'hooks'],
   category: 'data',
-  parameters: [{
-    name: 'options',
-    type: 'AgentSessionsOptions',
-    description: 'Account identity plus cloudId or rovoActivationId, with optional pageSize and sort configuration.'
-  }],
+  parameters: [],
   returns: {
     type: 'AgentSessionsResult',
     description: 'An unavailable result when identity cannot resolve a Rovo workspace, otherwise normalized sessions, pagination, and refetch controls.'
@@ -352,8 +348,8 @@ export const atlaskitHooks = [{
 }, {
   name: 'useChooseObjectExample',
   description: 'Returns object-example selection state for smart-creation prompts.',
-  status: 'general-availability',
-  usageGuidelines: ['Use within object-aware smart-creation example selection.'],
+  status: 'release-candidate',
+  usageGuidelines: ['Pass the selected example key and the same examples map used to render the cards. The returned handler inserts that example’s prompt into the editor; it does not submit the prompt.'],
   keywords: ['rovo', 'smart creation', 'object example', 'hook'],
   category: 'rovo',
   returns: {
@@ -364,8 +360,8 @@ export const atlaskitHooks = [{
 }, {
   name: 'useInputHatSelectedAgent',
   description: 'Resolves the selected agent displayed by the refreshed chat input hat.',
-  status: 'general-availability',
-  usageGuidelines: ['Use when composing the package refreshed input-hat experience.'],
+  status: 'release-candidate',
+  usageGuidelines: ['Use this hook in the refreshed chat input and pass the active agent and conversation ID from the same chat. It returns no agent when agent selection is disabled or no agent is selected.'],
   keywords: ['rovo', 'chat', 'agent', 'input hat'],
   category: 'rovo',
   returns: {
@@ -376,8 +372,8 @@ export const atlaskitHooks = [{
 }, {
   name: 'usePromptLibraryFilters',
   description: 'Manages prompt-library category, search, and visible prompt filtering.',
-  status: 'general-availability',
-  usageGuidelines: ['Use when building a custom prompt-library presentation.'],
+  status: 'release-candidate',
+  usageGuidelines: ['Use this hook when you build your own prompt-library filters. Pass the current prompt cards, render `filteredPromptCards`, and connect the search and filter controls to the returned handlers.'],
   keywords: ['rovo', 'prompt library', 'filter', 'hook'],
   category: 'rovo',
   returns: {
@@ -407,7 +403,7 @@ export const atlaskitHooks = [{
   name: 'useAllAttachmentsStore',
   description: 'Selects all file and external-context attachments for one prompt-input key and exposes attachment actions.',
   status: 'general-availability',
-  usageGuidelines: ['Use when rendering a unified ordered attachment surface for one prompt input.'],
+  usageGuidelines: ['Pass the same stable prompt-input key to this selector and its add, update, and remove actions so attachments stay with the right draft.', 'Render the returned file and external-context items in order when the composer presents them as one attachment list.'],
   keywords: ['rovo', 'chat', 'attachments', 'selector'],
   category: 'rovo',
   package: '@atlassian/conversation-assistant-chat-prompt-input',
@@ -602,11 +598,12 @@ export const atlaskitHooks = [{
   name: 'useExternalContextBrowser',
   description: 'Coordinates external context menu items, browser content, and selected prompt contexts.',
   status: 'general-availability',
-  usageGuidelines: ['Use in a Rovo prompt integration that accepts context from one or more product providers.'],
+  usageGuidelines: ['Keep the providers and callbacks in the prompt flow that owns the selected context. Use `currentContexts` when building the prompt and render `currentBrowser` with the menu returned by `getMenuItems`.'],
   keywords: ['rovo', 'chat', 'context', 'browser', 'hook'],
   category: 'rovo',
   returns: {
-    type: 'ExternalContextBrowserState'
+    type: 'ExternalContextBrowserState',
+    description: 'Returns the current browser, selected contexts, and menu-item builder for the supplied context browser configuration.'
   },
   package: '@atlassian/conversation-assistant-external-context',
   examples: []
@@ -682,6 +679,54 @@ export const atlaskitHooks = [{
   },
   package: '@atlassian/conversation-assistant-message-actions',
   examples: []
+}, {
+  name: 'useConversationAssistantSpotlightActions',
+  description: 'Public hook `useConversationAssistantSpotlightActions` from `@atlassian/conversation-assistant-onboarding/controllers/spotlight`.',
+  status: 'general-availability',
+  keywords: ['rovo', 'chat', 'ai', 'platform'],
+  category: 'rovo',
+  package: '@atlassian/conversation-assistant-onboarding',
+  examples: []
+}, {
+  name: 'useConversationAssistantSpotlightState',
+  description: 'Public hook `useConversationAssistantSpotlightState` from `@atlassian/conversation-assistant-onboarding/controllers/spotlight`.',
+  status: 'general-availability',
+  keywords: ['rovo', 'chat', 'ai', 'platform'],
+  category: 'rovo',
+  package: '@atlassian/conversation-assistant-onboarding',
+  examples: []
+}, {
+  name: 'useGettingStartedTourState',
+  description: 'Public hook `useGettingStartedTourState` from `@atlassian/conversation-assistant-onboarding/controllers/getting-started-tour`.',
+  status: 'general-availability',
+  keywords: ['rovo', 'chat', 'ai', 'platform'],
+  category: 'rovo',
+  package: '@atlassian/conversation-assistant-onboarding',
+  examples: []
+}, {
+  name: 'useGettingStartedTourStore',
+  description: 'Public hook `useGettingStartedTourStore` from `@atlassian/conversation-assistant-onboarding/controllers/getting-started-tour`.',
+  status: 'general-availability',
+  keywords: ['rovo', 'chat', 'ai', 'platform'],
+  category: 'rovo',
+  package: '@atlassian/conversation-assistant-onboarding',
+  examples: []
+}, {
+  name: 'useGettingStartedTourStoreActions',
+  description: 'Public hook `useGettingStartedTourStoreActions` from `@atlassian/conversation-assistant-onboarding/controllers/getting-started-tour`.',
+  status: 'general-availability',
+  keywords: ['rovo', 'chat', 'ai', 'platform'],
+  category: 'rovo',
+  package: '@atlassian/conversation-assistant-onboarding',
+  examples: []
+}, {
+  name: 'usePostOfficeCoordination',
+  description: 'Public hook `usePostOfficeCoordination` from `@atlassian/conversation-assistant-onboarding/controllers/post-office-migration`.',
+  status: 'general-availability',
+  keywords: ['rovo', 'chat', 'ai', 'platform'],
+  category: 'rovo',
+  package: '@atlassian/conversation-assistant-onboarding',
+  examples: []
 }, {
   name: 'useProductData',
   description: 'Public useProductData entrypoint for @atlassian/conversation-assistant-preview-card.',
@@ -802,6 +847,14 @@ export const atlaskitHooks = [{
   },
   package: '@atlassian/conversation-assistant-ui-components',
   examples: []
+}, {
+  name: 'useChartApiService',
+  description: 'Public hook `useChartApiService` from `@atlassian/conversation-assistant-viz/services/chart-api-service`.',
+  status: 'general-availability',
+  keywords: ['rovo', 'chat', 'ai', 'platform'],
+  category: 'rovo',
+  package: '@atlassian/conversation-assistant-viz',
+  examples: []
 }, {
   name: 'useAutoApplyAvailability',
   description: 'Determines whether auto-apply is available for the current product and conversation context.',
@@ -815,7 +868,7 @@ export const atlaskitHooks = [{
   name: 'useAutoApplyState',
   description: 'Reads and updates the auto-apply preference with backend persistence and a local-storage fallback.',
   status: 'general-availability',
-  usageGuidelines: ['Use the package root import; the auto-apply subpath exposes the same hook.', 'Handle rejected setEnabled calls when the host needs to surface persistence failures.'],
+  usageGuidelines: ['Treat the returned state as the last successfully loaded or saved preference. A failed update leaves it unchanged.', 'Show a save error with a retry option when an update fails.'],
   keywords: ['rovo', 'creation', 'auto apply', 'state'],
   category: 'rovo',
   package: '@atlassian/creation-settings',
@@ -842,7 +895,7 @@ export const atlaskitHooks = [{
   name: 'useAiCreateProjectContext',
   description: 'Resolves Jira project context for an AI-assisted creation flow.',
   status: 'general-availability',
-  usageGuidelines: ['Use when draft creation needs hydrated Jira project context.'],
+  usageGuidelines: ['Render within the app Relay provider. Pass the project fragment, Jira actions, and messageId for this group of drafts.', 'Wait for isStoreReady before reading the initialized drafts. Wait for isHydrationDone before treating user-picker values as fully loaded.'],
   keywords: ['rovo', 'jira', 'project', 'context'],
   category: 'rovo',
   returns: {
@@ -854,7 +907,7 @@ export const atlaskitHooks = [{
   name: 'useAifcAnalytics',
   description: 'Returns analytics helpers for AI-assisted Jira work-item creation.',
   status: 'general-availability',
-  usageGuidelines: ['Use within package-integrated creation UI that emits AIFC analytics.'],
+  usageGuidelines: ['Pass the messageId for the AI-assisted creation flow. The hook adds it to each analytics event; the analytics integration supplies the conversation context.', 'Add attributes specific to the event without repeating the message or conversation IDs.'],
   keywords: ['rovo', 'jira', 'creation', 'analytics'],
   category: 'rovo',
   returns: {
@@ -866,7 +919,7 @@ export const atlaskitHooks = [{
   name: 'useAreAllCreated',
   description: 'Reports whether every draft work item for a message has been created.',
   status: 'general-availability',
-  usageGuidelines: ['Use to derive completion state for a message-scoped creation flow.'],
+  usageGuidelines: ['Pass the messageId used for this group of drafts. The hook returns false before initialization and ignores dismissed drafts when checking whether all items were created.', 'Handle the submission result separately: this value describes draft state and does not prove that a non-empty creation request succeeded.'],
   keywords: ['rovo', 'jira', 'draft work item', 'created'],
   category: 'rovo',
   returns: {
@@ -878,7 +931,7 @@ export const atlaskitHooks = [{
   name: 'useAreAllDismissed',
   description: 'Reports whether every draft work item for a message has been dismissed.',
   status: 'general-availability',
-  usageGuidelines: ['Use to derive dismissed state for a message-scoped creation flow.'],
+  usageGuidelines: ['Pass the messageId for the draft group being shown; the hook returns false before initialization and becomes true only when every stored draft is dismissed.', 'Keep the empty-state decision separate if a message can start with no drafts, so “nothing to dismiss” is not described as “dismissed”.'],
   keywords: ['rovo', 'jira', 'draft work item', 'dismissed'],
   category: 'rovo',
   returns: {
@@ -890,7 +943,7 @@ export const atlaskitHooks = [{
   name: 'useCreateDraftWorkItems',
   description: 'Creates eligible Jira draft work items and exposes action callbacks.',
   status: 'general-availability',
-  usageGuidelines: ['Use to connect creation UI to the draft-work-item submission flow.'],
+  usageGuidelines: ['Pass the latest reviewed drafts to the returned callback when the person submits. It checks required fields and removes fields not recognized by the project configuration.', 'Handle onSuccess and onError to update the app. Awaiting the callback is not enough to confirm success; validation and creation failures are reported through those handlers.'],
   keywords: ['rovo', 'jira', 'draft work item', 'create'],
   category: 'rovo',
   returns: {
@@ -902,7 +955,7 @@ export const atlaskitHooks = [{
   name: 'useCreateIssuesSuccessFlags',
   description: 'Returns the success-flag action used after Jira work items are created.',
   status: 'general-availability',
-  usageGuidelines: ['Use to show package-standard success feedback after creation.'],
+  usageGuidelines: ['Call after creation succeeds. Pass the created Jira issue keys and site URL so View and Copy point to the right site.', 'Show creation failures separately from this success notice.'],
   keywords: ['rovo', 'jira', 'create', 'flag'],
   category: 'rovo',
   returns: {
@@ -914,7 +967,7 @@ export const atlaskitHooks = [{
   name: 'useDraftWorkItems',
   description: 'Returns the current draft work items and their controller state.',
   status: 'general-availability',
-  usageGuidelines: ['Use as the main draft-work-item data source for creation UI.'],
+  usageGuidelines: ['Read draft records from the draft-work-items store. This hook supplies update handlers; use the same messageId when reading and changing the drafts.', 'Use onFieldChange for edits, removeWorkItem for one draft, and onDismissAllDraftWorkItems for the group. Pass cloudId and conversationId to save edits to the conversation.'],
   keywords: ['rovo', 'jira', 'draft work item', 'hook'],
   category: 'rovo',
   returns: {
@@ -926,7 +979,7 @@ export const atlaskitHooks = [{
   name: 'useGetActiveOrFinishedDraftWorkItemsCount',
   description: 'Returns the number of active or completed draft work items for a message.',
   status: 'general-availability',
-  usageGuidelines: ['Use for progress and summary counts in creation UI.'],
+  usageGuidelines: ['Pass the same messageId as the draft list to count records for that message.', 'Use useGetDraftWorkItemsToCreate to find the items that can still be created; this count includes other draft states.'],
   keywords: ['rovo', 'jira', 'draft work item', 'count'],
   category: 'rovo',
   returns: {
@@ -938,7 +991,7 @@ export const atlaskitHooks = [{
   name: 'useGetActivePlannedChildInvocationIdsByParent',
   description: 'Groups active planned child invocation identifiers by parent work item.',
   status: 'general-availability',
-  usageGuidelines: ['Use when parent work-item state depends on active planned children.'],
+  usageGuidelines: ['Use the map to show which children are still planned beneath each parent; a missing parent key means there are no planned children to report.', 'This map includes planned child invocation IDs only, so do not use it as the full child count or as a signal that creation has finished.'],
   keywords: ['rovo', 'jira', 'draft work item', 'invocation'],
   category: 'rovo',
   returns: {
@@ -950,7 +1003,7 @@ export const atlaskitHooks = [{
   name: 'useGetDraftWorkItemsToCreate',
   description: 'Returns the draft work items currently eligible for creation.',
   status: 'general-availability',
-  usageGuidelines: ['Use to build the payload submitted by a draft-work-item creation action.'],
+  usageGuidelines: ['Read this immediately before submission so edits, dismissals, completed items, and parent-child relationships are current.', 'Submit each returned parent with its childWorkItems; do not flatten the tree or add nested children to the top-level payload a second time.'],
   keywords: ['rovo', 'jira', 'draft work item', 'create'],
   category: 'rovo',
   returns: {
@@ -962,7 +1015,7 @@ export const atlaskitHooks = [{
   name: 'useGetDraftWorkItemsWithHierarchy',
   description: 'Returns draft work items with their calculated parent-child hierarchy.',
   status: 'general-availability',
-  usageGuidelines: ['Use when rendering or validating hierarchical draft work items.'],
+  usageGuidelines: ['Render the returned top-level drafts and their childWorkItems as a tree; do not also render the children as separate top-level rows.', 'Use the same messageId for the draft editor and its updates so the hierarchy reflects the current message rather than another conversation response.'],
   keywords: ['rovo', 'jira', 'draft work item', 'hierarchy'],
   category: 'rovo',
   returns: {
@@ -974,7 +1027,7 @@ export const atlaskitHooks = [{
   name: 'useHasAppliedDraftEdits',
   description: 'Reports whether edits have been applied to message-scoped draft work items.',
   status: 'general-availability',
-  usageGuidelines: ['Use to distinguish original drafts from user-edited drafts.'],
+  usageGuidelines: ['Use this flag for the message to preserve or label edits when new suggestions arrive.', 'Track edits to all fields, not just changes to the visible summary.'],
   keywords: ['rovo', 'jira', 'draft work item', 'edits'],
   category: 'rovo',
   returns: {
@@ -986,7 +1039,7 @@ export const atlaskitHooks = [{
   name: 'useRovoBridgeAPI',
   description: 'Connects Jira draft-work-item creation to the Rovo bridge API.',
   status: 'general-availability',
-  usageGuidelines: ['Use where the creation flow exchanges state with a Rovo host.'],
+  usageGuidelines: ['Use once within the configured content-bridge client, passing its clientId and setupHandler. The hook connects the app to Rovo and disconnects on unmount or page exit.', 'Let this hook manage setup and cleanup instead of calling ready or teardown separately.'],
   keywords: ['rovo', 'jira', 'bridge', 'api'],
   category: 'rovo',
   returns: {
@@ -998,7 +1051,7 @@ export const atlaskitHooks = [{
   name: 'useValidateIssuesToCreate',
   description: 'Validates Jira draft work items before they are submitted for creation.',
   status: 'general-availability',
-  usageGuidelines: ['Use before enabling or invoking the create-work-items action.'],
+  usageGuidelines: ['Validate the current draft list before enabling creation; a result with success false contains a user-facing validation error, while undefined means project field configuration was unavailable.', 'Use the returned validated drafts for submission, since the hook removes fields that are not part of the selected Jira issue-type configuration.'],
   keywords: ['rovo', 'jira', 'draft work item', 'validation'],
   category: 'rovo',
   returns: {
@@ -1246,11 +1299,19 @@ export const atlaskitHooks = [{
   category: 'rovo',
   package: '@atlassian/rovo-conversation-actions',
   examples: []
+}, {
+  name: 'useCaseOptions',
+  description: 'Public hook `useCaseOptions` from `@atlassian/rovo-conversation-actions/prompt-cards`.',
+  status: 'general-availability',
+  keywords: ['rovo', 'chat', 'ai', 'platform'],
+  category: 'rovo',
+  package: '@atlassian/rovo-conversation-actions',
+  examples: ["import React, { useState } from 'react';\nimport { IntlProvider } from 'react-intl';\nimport { Stack } from '@atlaskit/primitives/compiled/stack';\nimport { Text } from '@atlaskit/primitives/compiled/text';\nimport type { PromptCard } from '@atlassian/rovo-conversation-actions/prompt-cards';\nimport { PromptCardsGrid } from '@atlassian/rovo-conversation-actions/prompt-cards-grid';\nconst cards: PromptCard[] = [\n\t{\n\t\tid: 'draft-release-notes',\n\t\ttitle: 'Draft release notes',\n\t\tprompt: 'Draft customer-ready release notes from this week’s completed work.',\n\t\tuseCase: 'Create',\n\t},\n\t{\n\t\tid: 'review-project-risks',\n\t\ttitle: 'Review project risks',\n\t\tprompt: 'Identify risks, owners, and mitigations for this project update.',\n\t\tuseCase: 'Review',\n\t},\n];\nexport default function PromptLibraryGridExample(): React.JSX.Element {\n\tconst [selectedPrompt, setSelectedPrompt] = useState<string>();\n\treturn (\n\t\t<IntlProvider locale=\"en\">\n\t\t\t<Stack space=\"space.150\">\n\t\t\t\t<PromptCardsGrid cards={cards} onCardClick={(card) => setSelectedPrompt(card.title)} />\n\t\t\t\t{selectedPrompt ? <Text>Selected: {selectedPrompt}</Text> : null}\n\t\t\t</Stack>\n\t\t</IntlProvider>\n\t);\n}"]
 }, {
   name: 'useConversationActionsStore',
   description: 'Reads selected Rovo conversation-action store state and actions.',
   status: 'general-availability',
-  usageGuidelines: ['Use for components that need a selected combination of conversation-action state and actions.'],
+  usageGuidelines: ['Use this combined hook only when the component both reads and updates the action store; use the state-only or actions-only hook when it needs just one side.', 'A store update can rerender this component, so keep it close to the controls that need the state rather than high in the chat tree.'],
   keywords: ['rovo', 'conversation actions', 'store', 'hook'],
   category: 'rovo',
   returns: {
@@ -1262,7 +1323,7 @@ export const atlaskitHooks = [{
   name: 'useConversationActionsStoreActions',
   description: 'Returns the mutation actions for the Rovo conversation-action store.',
   status: 'general-availability',
-  usageGuidelines: ['Use when a component updates conversation-action state without subscribing to values.'],
+  usageGuidelines: ['Use for components that only dispatch store updates so they do not subscribe to every action-state change.', 'Use the conversation-assistant setActiveAction flow for active-action changes; do not call setActiveAction_UNSAFE from a new consumer.'],
   keywords: ['rovo', 'conversation actions', 'store', 'actions'],
   category: 'rovo',
   returns: {
@@ -1274,7 +1335,7 @@ export const atlaskitHooks = [{
   name: 'useConversationActionsStoreState',
   description: 'Returns the current Rovo conversation-action store state.',
   status: 'general-availability',
-  usageGuidelines: ['Use when a component reads conversation-action state without dispatching actions.'],
+  usageGuidelines: ['Use to read store values without updating them. Make changes through the actions hook or an app event handler.', 'Use a selector for a single value when possible so unrelated store changes do not rerender the component.'],
   keywords: ['rovo', 'conversation actions', 'store', 'state'],
   category: 'rovo',
   returns: {
@@ -1291,15 +1352,6 @@ export const atlaskitHooks = [{
   category: 'rovo',
   package: '@atlassian/rovo-conversation-actions',
   examples: []
-}, {
-  name: 'useCreatePromptInitialData',
-  description: 'Builds initial create-prompt form data for edit and duplicate flows.',
-  status: 'general-availability',
-  usageGuidelines: ['Pass only one source card; duplicate mode prefixes the copied title.'],
-  keywords: ['rovo', 'prompts', 'initial data', 'hook'],
-  category: 'rovo',
-  package: '@atlassian/rovo-conversation-actions',
-  examples: []
 }, {
   name: 'usePageContextType',
   description: 'Tracks browser navigation and returns the current Rovo page context.',
@@ -1309,11 +1361,19 @@ export const atlaskitHooks = [{
   category: 'rovo',
   package: '@atlassian/rovo-conversation-actions',
   examples: []
+}, {
+  name: 'usePromptCards',
+  description: 'Public hook `usePromptCards` from `@atlassian/rovo-conversation-actions/prompt-cards`.',
+  status: 'general-availability',
+  keywords: ['rovo', 'chat', 'ai', 'platform'],
+  category: 'rovo',
+  package: '@atlassian/rovo-conversation-actions',
+  examples: ["import React, { useState } from 'react';\nimport { IntlProvider } from 'react-intl';\nimport { Stack } from '@atlaskit/primitives/compiled/stack';\nimport { Text } from '@atlaskit/primitives/compiled/text';\nimport type { PromptCard } from '@atlassian/rovo-conversation-actions/prompt-cards';\nimport { PromptCardsGrid } from '@atlassian/rovo-conversation-actions/prompt-cards-grid';\nconst cards: PromptCard[] = [\n\t{\n\t\tid: 'draft-release-notes',\n\t\ttitle: 'Draft release notes',\n\t\tprompt: 'Draft customer-ready release notes from this week’s completed work.',\n\t\tuseCase: 'Create',\n\t},\n\t{\n\t\tid: 'review-project-risks',\n\t\ttitle: 'Review project risks',\n\t\tprompt: 'Identify risks, owners, and mitigations for this project update.',\n\t\tuseCase: 'Review',\n\t},\n];\nexport default function PromptLibraryGridExample(): React.JSX.Element {\n\tconst [selectedPrompt, setSelectedPrompt] = useState<string>();\n\treturn (\n\t\t<IntlProvider locale=\"en\">\n\t\t\t<Stack space=\"space.150\">\n\t\t\t\t<PromptCardsGrid cards={cards} onCardClick={(card) => setSelectedPrompt(card.title)} />\n\t\t\t\t{selectedPrompt ? <Text>Selected: {selectedPrompt}</Text> : null}\n\t\t\t</Stack>\n\t\t</IntlProvider>\n\t);\n}"]
 }, {
   name: 'usePromptCards',
   description: 'Returns the prompt cards and prompt-library loading state available to the user.',
   status: 'general-availability',
-  usageGuidelines: ['Use when composing a custom Rovo prompt-library surface.'],
+  usageGuidelines: ['Use to arrange the built-in prompt cards in your own layout, or pass the cards to PromptCardsGrid for the standard grid.', 'Provide the skill metadata for the current site before rendering; it determines which skill cards are available.'],
   keywords: ['rovo', 'prompts', 'cards', 'hook'],
   category: 'rovo',
   returns: {
@@ -1325,7 +1385,7 @@ export const atlaskitHooks = [{
   name: 'useRovoConversationStarters',
   description: 'Selects Rovo conversation starters for the current page and product context.',
   status: 'general-availability',
-  usageGuidelines: ['Use when a Rovo chat surface needs contextual starter prompts.'],
+  usageGuidelines: ['Pass the current product and page details to choose relevant starters. Supply dynamicStartersConfig and assistanceServiceParams when the app supports fetched suggestions.', 'Show loading while suggestions are fetched. Choose whether selection fills the prompt editor or submits the prompt.'],
   keywords: ['rovo', 'conversation starters', 'context', 'hook'],
   category: 'rovo',
   returns: {
@@ -1337,7 +1397,7 @@ export const atlaskitHooks = [{
   name: 'useWindowLocation',
   description: 'Tracks browser history navigation and returns the full URL or pathname.',
   status: 'general-availability',
-  usageGuidelines: ['Use pathname mode when query and hash changes should not affect the consumer.'],
+  usageGuidelines: ['Use pathname mode to follow page routes only. The default follows the whole URL, including query strings and fragments.', 'Use WindowLocationContext in tests or embedded views that should follow an app-supplied location instead of the browser URL.'],
   keywords: ['rovo', 'browser', 'location', 'hook'],
   category: 'rovo',
   package: '@atlassian/rovo-conversation-actions',
@@ -1391,7 +1451,7 @@ export const atlaskitHooks = [{
   name: 'useForYouNavigation',
   description: 'Returns the combined Rovo For You navigation state and actions.',
   status: 'general-availability',
-  usageGuidelines: ['Use when a component needs both the current For You view and navigation actions.'],
+  usageGuidelines: [],
   keywords: ['rovo', 'for you', 'navigation', 'hook'],
   category: 'rovo',
   returns: {
@@ -1401,9 +1461,9 @@ export const atlaskitHooks = [{
   examples: []
 }, {
   name: 'useForYouNavigationActions',
-  description: 'Returns actions for changing Rovo For You navigation state.',
+  description: 'Returns the reset action for Rovo For You navigation. The action is currently a no-op because only the threads-list view exists.',
   status: 'general-availability',
-  usageGuidelines: ['Use within ForYouNavigationProvider to navigate between For You views.'],
+  usageGuidelines: [],
   keywords: ['rovo', 'for you', 'navigation', 'actions'],
   category: 'rovo',
   returns: {
@@ -1415,19 +1475,19 @@ export const atlaskitHooks = [{
   name: 'useForYouNavigationState',
   description: 'Reads the current Rovo For You navigation state.',
   status: 'general-availability',
-  usageGuidelines: ['Use within ForYouNavigationProvider when rendering the active internal view.'],
+  usageGuidelines: [],
   keywords: ['rovo', 'for you', 'navigation', 'state'],
   category: 'rovo',
   returns: {
     type: 'ForYouNavigationState'
   },
   package: '@atlassian/rovo-for-you',
-  examples: []
+  examples: ["import { Box } from '@atlaskit/primitives/compiled/box';\nimport { Text } from '@atlaskit/primitives/compiled/text';\nimport {\n\tForYouNavigationProvider,\n\tuseForYouNavigationState,\n} from '@atlassian/rovo-for-you/navigation-store';\nexport default function ForYouNavigationProviderExample(): React.JSX.Element {\n\treturn (\n\t\t<ForYouNavigationProvider>\n\t\t\t<CurrentForYouView />\n\t\t</ForYouNavigationProvider>\n\t);\n}\nfunction CurrentForYouView(): React.JSX.Element {\n\tconst { currentView } = useForYouNavigationState();\n\treturn (\n\t\t<Box padding=\"space.200\">\n\t\t\t<Text>Current view: {currentView.type}</Text>\n\t\t</Box>\n\t);\n}"]
 }, {
   name: 'useFireInsightCardClicked',
   description: 'Returns portable analytics for Rovo Insight card clicks outside the feed lifecycle.',
   status: 'general-availability',
-  usageGuidelines: ['Use for Insight cards opened from external surfaces such as a home carousel.'],
+  usageGuidelines: ['Use to record clicks on insight cards outside InsightsFeed, such as a home carousel. Record the click only once when the feed already handles it.'],
   keywords: ['rovo', 'insights', 'card', 'analytics'],
   category: 'rovo',
   returns: {
@@ -1451,7 +1511,7 @@ export const atlaskitHooks = [{
   name: 'useInsightsFeed',
   description: 'Loads and maps Rovo Insights data into feed-ready state.',
   status: 'general-availability',
-  usageGuidelines: ['Use when composing a custom surface from the standard Insights feed data lifecycle.'],
+  usageGuidelines: ['Use to build a custom feed instead of InsightsFeed. Handle loading, errors, and retries, and navigate from the app when an insight is selected.'],
   keywords: ['rovo', 'insights', 'feed', 'data'],
   category: 'rovo',
   returns: {
@@ -1463,7 +1523,7 @@ export const atlaskitHooks = [{
   name: 'useInsightsStatus',
   description: 'Loads the current availability and freshness status for Rovo Insights.',
   status: 'general-availability',
-  usageGuidelines: ['Use before presenting Insights UI that depends on backend availability or freshness.'],
+  usageGuidelines: ['Enable the request only on pages where Insights are available. Check availability and freshness before showing a link that requires recent content; missing or invalid generation dates count as stale.'],
   keywords: ['rovo', 'insights', 'status', 'availability'],
   category: 'rovo',
   returns: {
@@ -1475,7 +1535,7 @@ export const atlaskitHooks = [{
   name: 'useReportInsightsBannerResolved',
   description: 'Resolves banner visibility and reports the decision once per mount.',
   status: 'general-availability',
-  usageGuidelines: ['Use when rendering an Insights banner so shown and hidden outcomes are observable.'],
+  usageGuidelines: ['Pass the same visibility values used to decide whether the banner is shown. The hook reports the outcome once per mount; use one instance for that banner.'],
   keywords: ['rovo', 'insights', 'banner', 'analytics'],
   category: 'rovo',
   returns: {
@@ -1507,6 +1567,14 @@ export const atlaskitHooks = [{
   },
   package: '@atlassian/rovo-personalization',
   examples: []
+}, {
+  name: 'usePinnedItems',
+  description: 'Public hook `usePinnedItems` from `@atlassian/rovo-pins/store`.',
+  status: 'general-availability',
+  keywords: ['rovo', 'chat', 'ai', 'platform'],
+  category: 'rovo',
+  package: '@atlassian/rovo-pins',
+  examples: ["/**\n * Example: PinnedWorkSection with pinned items.\n *\n * Demos the \"Your team's work\" heading, \"+\" button, and item list shown once at least one\n * epic, project, or goal is pinned. See `01-pinned-work-section.tsx` for the empty-state\n * demo shown before anything is pinned. The last row has a deliberately long title —\n * hovering it shows a tooltip with the full text once it overflows.\n */\nimport React, { useEffect } from 'react';\nimport { IntlProvider } from 'react-intl';\nimport { cssMap } from '@atlaskit/css';\nimport { Box } from '@atlaskit/primitives/compiled/box';\nimport { token } from '@atlaskit/tokens';\nimport { usePinnedItems } from '../src/services/pinned-items-store';\nimport type { SearchWorkItem } from '../src/types';\nimport { PinnedWorkSection } from '../src/ui/pinned-work-section/PinnedWorkSection';\nconst EXAMPLE_CLOUD_ID = 'example-cloud-id';\nconst EXAMPLE_PRODUCT = 'jira';\nconst MOCK_ITEMS: SearchWorkItem[] = [\n\t{\n\t\tari: 'ari:cloud:jira:site/1:epic/1',\n\t\turl: 'https://example.atlassian.net/browse/EPIC-1',\n\t\tpinType: 'JiraIssue',\n\t\tname: 'Your Work tab: Pin objects',\n\t},\n\t{\n\t\tari: 'ari:cloud:jira:site/1:project/1',\n\t\turl: 'https://example.atlassian.net/jira/projects/1',\n\t\tpinType: 'AtlasProject',\n\t\tname: 'Rovo For You',\n\t},\n\t{\n\t\tari: 'ari:cloud:jira:site/1:goal/1',\n\t\turl: 'https://example.atlassian.net/goals/1',\n\t\tpinType: 'AtlasGoal',\n\t\tname: 'Grow Rovo weekly active users',\n\t},\n\t{\n\t\tari: 'ari:cloud:jira:site/1:epic/2',\n\t\turl: 'https://example.atlassian.net/browse/EPIC-2',\n\t\tpinType: 'JiraIssue',\n\t\tname: 'A deliberately very long epic title used to demo single-line overflow clipping',\n\t},\n];\nconst styles = cssMap({\n\twrapper: {\n\t\twidth: '360px',\n\t\tpaddingTop: token('space.300'),\n\t\tpaddingRight: token('space.200'),\n\t\tpaddingBottom: token('space.300'),\n\t\tpaddingLeft: token('space.200'),\n\t},\n});\n/**\n * Pins the mock items once on mount via the real `pin()` action, then renders its children.\n * `usePinnedItems` now calls the real create endpoint, so this demo only shows the populated\n * state when previewed against a live backend for `EXAMPLE_CLOUD_ID` — same `cloudId` as\n * `PinnedWorkSection` below, so both share the same `useQuery` cache entry.\n */\nconst PinMockItemsOnMount = ({ children }: { children: React.ReactNode }): React.JSX.Element => {\n\tconst { pin } = usePinnedItems({ cloudId: EXAMPLE_CLOUD_ID, product: EXAMPLE_PRODUCT });\n\tuseEffect(() => {\n\t\t// pin() prepends each item, so pin in reverse to render top-to-bottom in\n\t\t// MOCK_ITEMS' declared order — matching 02-pinned-item-row.tsx.\n\t\t[...MOCK_ITEMS].reverse().forEach((item) => {\n\t\t\tpin(item);\n\t\t});\n\t\t// Intentionally run once on mount only — MOCK_ITEMS is a static, module-level constant.\n\t}, []);\n\treturn <>{children}</>;\n};\nexport default function PinnedWorkSectionWithItemsExample(): React.JSX.Element {\n\treturn (\n\t\t<IntlProvider locale=\"en\">\n\t\t\t<PinMockItemsOnMount>\n\t\t\t\t<Box xcss={styles.wrapper}>\n\t\t\t\t\t<PinnedWorkSection\n\t\t\t\t\t\tcloudId={EXAMPLE_CLOUD_ID}\n\t\t\t\t\t\tproduct={EXAMPLE_PRODUCT}\n\t\t\t\t\t\tonPinWorkClick={() => {}}\n\t\t\t\t\t\tonStartChat={() => {}}\n\t\t\t\t\t/>\n\t\t\t\t</Box>\n\t\t\t</PinMockItemsOnMount>\n\t\t</IntlProvider>\n\t);\n}"]
 }, {
   name: 'useInfiniteScroll',
   description: 'Coordinates loading more inline-browse results when a scroll sentinel enters view.',
@@ -1540,11 +1608,20 @@ export const atlaskitHooks = [{
   category: 'rovo',
   package: '@atlassian/rovo-prompt-of-the-day',
   examples: []
+}, {
+  name: 'usePromptOfTheDayWithFallback',
+  description: 'Reads the same shared suggestions, keeps showing the last stored ones while new ones load or if that request fails, and can remove a used suggestion.',
+  status: 'general-availability',
+  usageGuidelines: ['Use when an empty surface is worse than yesterday’s suggestions; status is stale when a refresh failed.', 'maxAgeMs can only keep an entry past its expiry; a value shorter than the time left to expiry has no effect.', 'Call removePrompt once a suggestion is used, so no surface offers it again before the entry regenerates.'],
+  keywords: ['rovo', 'prompt of the day', 'suggestions', 'cache', 'fallback', 'stale'],
+  category: 'rovo',
+  package: '@atlassian/rovo-prompt-of-the-day',
+  examples: []
 }, {
   name: 'useIsRovoSettingsModalProviderMounted',
   description: 'Reports whether a Rovo settings modal provider is mounted above the caller.',
   status: 'general-availability',
-  usageGuidelines: ['Use to avoid rendering controls that require an unavailable settings provider.'],
+  usageGuidelines: ['Check this before showing controls that require RovoSettingsModalProvider. It reports whether the component is within that provider.'],
   keywords: ['rovo', 'settings', 'provider', 'hook'],
   category: 'rovo',
   returns: {
@@ -1556,31 +1633,31 @@ export const atlaskitHooks = [{
   name: 'useRovoSettingsConfig',
   description: 'Reads the configuration supplied for the current Rovo settings experience.',
   status: 'general-availability',
-  usageGuidelines: ['Use below RovoSettingsConfigProvider to access host-specific settings configuration.'],
+  usageGuidelines: ['Read the product, site, and settings configuration from the nearest provider. RovoSettingsModalProvider supplies these values for the standard settings flow.'],
   keywords: ['rovo', 'settings', 'config', 'hook'],
   category: 'rovo',
   returns: {
     type: 'RovoSettingsConfig'
   },
   package: '@atlassian/rovo-settings-modal',
-  examples: []
+  examples: ["import { IntlProvider } from 'react-intl';\nimport { Stack } from '@atlaskit/primitives/compiled/stack';\nimport { Text } from '@atlaskit/primitives/compiled/text';\nimport {\n\tRovoSettingsConfigProvider,\n\tuseIsRovoSettingsModalProviderMounted,\n\tuseRovoSettingsConfig,\n} from '@atlassian/rovo-settings-modal/common/utils/rovo-settings-config';\nconst SettingsContextSummary = (): React.JSX.Element => {\n\tconst { product, siteId, experienceId } = useRovoSettingsConfig();\n\tconst isModalProviderMounted = useIsRovoSettingsModalProviderMounted();\n\treturn (\n\t\t<Stack space=\"space.050\">\n\t\t\t<Text>Product: {product}</Text>\n\t\t\t<Text>Site: {siteId}</Text>\n\t\t\t<Text>Experience: {experienceId}</Text>\n\t\t\t<Text>Settings modal provider mounted: {isModalProviderMounted ? 'yes' : 'no'}</Text>\n\t\t</Stack>\n\t);\n};\nexport default function RovoSettingsConfigExample(): React.JSX.Element {\n\treturn (\n\t\t<IntlProvider locale=\"en\">\n\t\t\t<RovoSettingsConfigProvider\n\t\t\t\tvalue={{\n\t\t\t\t\tproduct: 'confluence',\n\t\t\t\t\tsiteId: 'example-cloud-id',\n\t\t\t\t\texperienceId: 'ai-mate',\n\t\t\t\t\tsurface: 'profile-menu',\n\t\t\t\t}}\n\t\t\t>\n\t\t\t\t<SettingsContextSummary />\n\t\t\t</RovoSettingsConfigProvider>\n\t\t</IntlProvider>\n\t);\n}"]
 }, {
   name: 'useRovoSettingsModal',
   description: 'Returns controls for opening and closing the nearest Rovo settings modal.',
   status: 'general-availability',
-  usageGuidelines: ['Use within RovoSettingsModalProvider to trigger settings from product UI.'],
+  usageGuidelines: ['Call this hook within RovoSettingsModalProvider. Use RovoSettingsModal when your app has no provider and only needs a trigger to open settings.'],
   keywords: ['rovo', 'settings', 'modal', 'hook'],
   category: 'rovo',
   returns: {
     type: '{ open: (options?: RovoSettingsModalOpenOptions) => void; close: () => void }'
   },
   package: '@atlassian/rovo-settings-modal',
-  examples: []
+  examples: ["import { IntlProvider } from 'react-intl';\nimport Button from '@atlaskit/button/default/button';\nimport {\n\tRovoSettingsModalProvider,\n\tuseRovoSettingsModal,\n} from '@atlassian/rovo-settings-modal/ui/rovo-settings-modal-provider';\ntype RovoSettingsModalProviderExampleProps = {\n\tcloudId: string;\n};\nconst SettingsAction = (): React.JSX.Element => {\n\tconst { open } = useRovoSettingsModal();\n\treturn (\n\t\t<Button appearance=\"subtle\" onClick={() => open({ defaultTab: 'connected-apps' })}>\n\t\t\tManage connected apps\n\t\t</Button>\n\t);\n};\nexport default function RovoSettingsModalProviderExample({\n\tcloudId,\n}: RovoSettingsModalProviderExampleProps): React.JSX.Element {\n\treturn (\n\t\t<IntlProvider locale=\"en\">\n\t\t\t<RovoSettingsModalProvider product=\"confluence\" cloudId={cloudId}>\n\t\t\t\t<SettingsAction />\n\t\t\t</RovoSettingsModalProvider>\n\t\t</IntlProvider>\n\t);\n}"]
 }, {
   name: 'useAddSpaceSource',
   description: 'Adds a source to a space and mirrors the successful result into the space store.',
   status: 'general-availability',
-  usageGuidelines: ['Use when a React surface lets people attach a source to a space.'],
+  usageGuidelines: ['Call addSource with the resolved source URL and any available name, ARI, and type. The hook updates the space store on success; use its error and isAdding state to keep the picker feedback in sync.'],
   keywords: ['rovo', 'spaces', 'source', 'mutation'],
   category: 'rovo',
   returns: {
@@ -1592,7 +1669,7 @@ export const atlaskitHooks = [{
   name: 'useCreateSpace',
   description: 'Creates a Rovo space and exposes mutation, submission, and error state.',
   status: 'general-availability',
-  usageGuidelines: ['Use to connect a custom creation interface to the space service.'],
+  usageGuidelines: ['Pass the current cloud, product, and experience values. Call mutate when the form submits.', 'Set form loading and errors from isSubmitting and error. Update navigation from onSuccess after creation.'],
   keywords: ['rovo', 'spaces', 'create', 'mutation'],
   category: 'rovo',
   returns: {
@@ -1604,7 +1681,7 @@ export const atlaskitHooks = [{
   name: 'useDeleteSpace',
   description: 'Deletes a space with optimistic store removal and rollback on failure.',
   status: 'general-availability',
-  usageGuidelines: ['Use to connect a deletion confirmation flow to the space service.'],
+  usageGuidelines: ['Call deleteSpace only after the person confirms deletion. The hook removes the space optimistically and restores it if the request fails, so keep the error visible and let the person retry.'],
   keywords: ['rovo', 'spaces', 'delete', 'mutation'],
   category: 'rovo',
   returns: {
@@ -1616,7 +1693,7 @@ export const atlaskitHooks = [{
   name: 'useDeleteSpaceSource',
   description: 'Removes a source from a space and mirrors the deletion into the space store.',
   status: 'general-availability',
-  usageGuidelines: ['Use when a React surface lets people detach a source from a space.'],
+  usageGuidelines: ['Call deleteSource with the source ID after confirmation. The hook updates the space store on success and rejects on failure; use isDeleting and error to prevent duplicate submits and report failures.'],
   keywords: ['rovo', 'spaces', 'source', 'delete'],
   category: 'rovo',
   returns: {
@@ -1628,14 +1705,14 @@ export const atlaskitHooks = [{
   name: 'useSpaceSourcePlugins',
   description: 'Creates the Link Picker plugins used to select supported space sources.',
   status: 'general-availability',
-  usageGuidelines: ['Use to configure a space source Link Picker for the current cloud.'],
+  usageGuidelines: ['Build the picker plugins with the cloud ID from the active site, then pass them into the authenticated Link Picker context. The hook supplies Confluence, Jira, Atlas, and Loom sources.'],
   keywords: ['rovo', 'spaces', 'source', 'link picker'],
   category: 'rovo',
   returns: {
     type: 'LinkPickerPlugin[]'
   },
   package: '@atlassian/rovo-spaces',
-  examples: []
+  examples: ["import React, { useState } from 'react';\nimport { IntlProvider } from 'react-intl';\nimport Button from '@atlaskit/button/default/button';\nimport { SmartCardProvider } from '@atlaskit/link-provider/smart-card-provider';\nimport { Stack } from '@atlaskit/primitives/compiled/stack';\nimport { Text } from '@atlaskit/primitives/compiled/text';\nimport { SourceLinkPickerPopup } from '@atlassian/rovo-spaces/ui/SpaceLandingPage/SourceLinkPickerPopup';\nimport type { SpaceSource } from '@atlassian/rovo-spaces/ui/SpaceLandingPage/types';\nimport { useSpaceSourcePlugins } from '@atlassian/rovo-spaces/ui/SpaceLandingPage/useSpaceSourcePlugins';\ntype SourceLinkPickerPopupExampleProps = {\n\t/** Cloud ID from the host's authenticated Link Picker integration context. */\n\tcloudId: string;\n\t/** Persist this source and then pass the updated source list back to the picker. */\n\tonPersistSource: (source: SpaceSource) => Promise<void>;\n};\nexport default function SourceLinkPickerPopupExample({\n\tcloudId,\n\tonPersistSource,\n}: SourceLinkPickerPopupExampleProps): React.JSX.Element {\n\tconst plugins = useSpaceSourcePlugins(cloudId);\n\tconst [sources, setSources] = useState<SpaceSource[]>([]);\n\tconst [message, setMessage] = useState<string>();\n\tconst handleSourceAdded = (source: SpaceSource) => {\n\t\t// The picker resolves a link; the host owns authorization and persistence.\n\t\tvoid onPersistSource(source).then(\n\t\t\t() => setSources((current) => [...current, source]),\n\t\t\t() => setMessage(`Could not add ${source.title}`),\n\t\t);\n\t};\n\treturn (\n\t\t<IntlProvider locale=\"en\">\n\t\t\t<SmartCardProvider>\n\t\t\t\t<Stack space=\"space.150\">\n\t\t\t\t\t<SourceLinkPickerPopup\n\t\t\t\t\t\tcloudId={cloudId}\n\t\t\t\t\t\tplugins={plugins}\n\t\t\t\t\t\tsources={sources}\n\t\t\t\t\t\tonSourceAdded={handleSourceAdded}\n\t\t\t\t\t\ttrigger={({ onClick, ...triggerProps }) => (\n\t\t\t\t\t\t\t<Button {...triggerProps} onClick={onClick}>\n\t\t\t\t\t\t\t\tAdd a source\n\t\t\t\t\t\t\t</Button>\n\t\t\t\t\t\t)}\n\t\t\t\t\t/>\n\t\t\t\t\t{sources.map((source) => (\n\t\t\t\t\t\t<Text key={source.id} size=\"small\">\n\t\t\t\t\t\t\t{source.title}\n\t\t\t\t\t\t</Text>\n\t\t\t\t\t))}\n\t\t\t\t\t{message && (\n\t\t\t\t\t\t<Text size=\"small\" role=\"status\">\n\t\t\t\t\t\t\t{message}\n\t\t\t\t\t\t</Text>\n\t\t\t\t\t)}\n\t\t\t\t</Stack>\n\t\t\t</SmartCardProvider>\n\t\t</IntlProvider>\n\t);\n}"]
 }, {
   name: 'useActionInvocationStatuses',
   description: 'Returns live action-invocation statuses for a set of Rovo plan steps.',
@@ -1742,7 +1819,7 @@ export const atlaskitHooks = [{
   name: 'useRovoProjectCreationCategories',
   description: 'Returns localized feedback categories for Rovo project creation.',
   status: 'general-availability',
-  usageGuidelines: ['Use to keep project-creation feedback categories consistent across entry points.'],
+  usageGuidelines: ['Use to show the same translated project-creation categories as SmartCreateFeedback.', 'Display the translated labels and save the stable category IDs with feedback.'],
   keywords: ['rovo', 'project creation', 'feedback', 'categories'],
   category: 'rovo',
   returns: {
@@ -1754,7 +1831,7 @@ export const atlaskitHooks = [{
   name: 'useCurrentDisplayMessage',
   description: 'Returns the assistant message currently selected by preview history.',
   status: 'general-availability',
-  usageGuidelines: ['Use when a preview must follow the current undo or redo position.'],
+  usageGuidelines: ['Use this message when rendering the preview after undo or redo; it follows the message selected in the staging-area history rather than always returning the newest message.'],
   keywords: ['rovo', 'smart creation', 'message', 'history'],
   category: 'rovo',
   returns: {
@@ -1790,7 +1867,7 @@ export const atlaskitHooks = [{
   name: 'useLatestActionMessage',
   description: 'Returns the latest Smart Creation action messages and preview statuses.',
   status: 'general-availability',
-  usageGuidelines: ['Use to derive current create, update, and ask-question action state.'],
+  usageGuidelines: ['Use this for the latest create or update action and ask-question state. It reads the active conversation, so provide the product’s Smart Creation chat-store hook for that conversation.'],
   keywords: ['rovo', 'smart creation', 'action', 'message'],
   category: 'rovo',
   returns: {
@@ -1802,7 +1879,7 @@ export const atlaskitHooks = [{
   name: 'useSelectedPreview',
   description: 'Returns the message, content, title, and status selected for preview.',
   status: 'general-availability',
-  usageGuidelines: ['Use when a staging area follows the user-selected creation action.'],
+  usageGuidelines: ['Use this when the preview should follow the action the person selected, including a specific action within a message. Provide the active conversation’s chat-store hook so the selected message can be resolved.'],
   keywords: ['rovo', 'smart creation', 'selected preview', 'message'],
   category: 'rovo',
   returns: {
@@ -1814,7 +1891,7 @@ export const atlaskitHooks = [{
   name: 'useStagingAreaContext',
   description: 'Returns the current Smart Creation staging-area context.',
   status: 'general-availability',
-  usageGuidelines: ['Call inside StagingAreaContextProvider-backed components.'],
+  usageGuidelines: ['Call within StagingAreaContextProvider. Read the selected preview and status from the current conversation instead of keeping another copy in component state.'],
   keywords: ['rovo', 'smart creation', 'staging area', 'context'],
   category: 'rovo',
   returns: {
@@ -1826,7 +1903,7 @@ export const atlaskitHooks = [{
   name: 'useUndoRedoHistory',
   description: 'Builds undo and redo navigation from ephemeral creation-action messages.',
   status: 'general-availability',
-  usageGuidelines: ['Use when a preview supports navigating previous generated versions.'],
+  usageGuidelines: ['Enable history only for previews that can be revisited, and cache each message’s embed URL as it loads. The hook returns controls only when there is more than one supported generated version.'],
   keywords: ['rovo', 'smart creation', 'undo', 'redo'],
   category: 'rovo',
   returns: {
@@ -1852,16 +1929,139 @@ export const atlaskitHooks = [{
   category: 'rovo',
   package: '@atlassian/store-rovo',
   examples: []
+}, {
+  name: 'useBrowseAgentCategoryUpdates',
+  description: 'Public hook `useBrowseAgentCategoryUpdates` exported by `@atlassian/studio-agent-browse/ui/browse-agent/useBrowseAgentCategoryUpdates`.',
+  status: 'general-availability',
+  usageGuidelines: ['Import from this explicit public entrypoint rather than a source-internal path.', 'Keep host lifecycle, permissions, and network orchestration at the integration boundary.'],
+  keywords: ['studio', 'rovo', 'agent'],
+  category: 'studio',
+  package: '@atlassian/studio-agent-browse',
+  examples: []
 }, {
   name: 'useBrowseAgentView',
-  description: 'Returns controls for opening and closing nested views in the Rovo agent browser.',
+  description: 'Public hook `useBrowseAgentView` exported by `@atlassian/studio-agent-browse/browse-agent/use-browse-agent-view`.',
   status: 'general-availability',
-  usageGuidelines: ['Use within BrowseAgentView to open agent, template, or other nested detail content.'],
-  keywords: ['rovo', 'agent', 'browse', 'hook'],
-  category: 'rovo',
-  returns: {
-    type: 'ReturnType<typeof useBrowseAgentView>'
-  },
-  package: '@atlassian/studio-browse-kit',
+  usageGuidelines: ['Import from this explicit public entrypoint rather than a source-internal path.', 'Keep host lifecycle, permissions, and network orchestration at the integration boundary.'],
+  keywords: ['studio', 'rovo', 'agent'],
+  category: 'studio',
+  package: '@atlassian/studio-agent-browse',
+  examples: []
+}, {
+  name: 'useAgentKnowledgeSourcesMutation',
+  description: 'Public hook `useAgentKnowledgeSourcesMutation` exported by `@atlassian/studio-agent-editor/domains/knowledge-sources/mutations`.',
+  status: 'general-availability',
+  usageGuidelines: ['Import from this explicit public entrypoint rather than a source-internal path.', 'Keep host lifecycle, permissions, and network orchestration at the integration boundary.'],
+  keywords: ['studio', 'rovo', 'agent'],
+  category: 'studio',
+  package: '@atlassian/studio-agent-editor',
+  examples: []
+}, {
+  name: 'useAgentSkillsMutation',
+  description: 'Public hook `useAgentSkillsMutation` exported by `@atlassian/studio-agent-editor/domains/skills/mutations`.',
+  status: 'general-availability',
+  usageGuidelines: ['Import from this explicit public entrypoint rather than a source-internal path.', 'Keep host lifecycle, permissions, and network orchestration at the integration boundary.'],
+  keywords: ['studio', 'rovo', 'agent'],
+  category: 'studio',
+  package: '@atlassian/studio-agent-editor',
+  examples: []
+}, {
+  name: 'useAgentToolConfigurationMutation',
+  description: 'Public hook `useAgentToolConfigurationMutation` exported by `@atlassian/studio-agent-editor/domains/tools/mutations`.',
+  status: 'general-availability',
+  usageGuidelines: ['Import from this explicit public entrypoint rather than a source-internal path.', 'Keep host lifecycle, permissions, and network orchestration at the integration boundary.'],
+  keywords: ['studio', 'rovo', 'agent'],
+  category: 'studio',
+  package: '@atlassian/studio-agent-editor',
+  examples: []
+}, {
+  name: 'useAgentToolsMutation',
+  description: 'Public hook `useAgentToolsMutation` exported by `@atlassian/studio-agent-editor/domains/tools/mutations`.',
+  status: 'general-availability',
+  usageGuidelines: ['Import from this explicit public entrypoint rather than a source-internal path.', 'Keep host lifecycle, permissions, and network orchestration at the integration boundary.'],
+  keywords: ['studio', 'rovo', 'agent'],
+  category: 'studio',
+  package: '@atlassian/studio-agent-editor',
+  examples: []
+}, {
+  name: 'useKnowledgeSourcesUpdater',
+  description: 'Public hook `useKnowledgeSourcesUpdater` exported by `@atlassian/studio-agent-editor/domains/knowledge-sources/updaters`.',
+  status: 'general-availability',
+  usageGuidelines: ['Import from this explicit public entrypoint rather than a source-internal path.', 'Keep host lifecycle, permissions, and network orchestration at the integration boundary.'],
+  keywords: ['studio', 'rovo', 'agent'],
+  category: 'studio',
+  package: '@atlassian/studio-agent-editor',
+  examples: []
+}, {
+  name: 'useScenarioToolsMutation',
+  description: 'Public hook `useScenarioToolsMutation` exported by `@atlassian/studio-agent-editor/domains/tools/mutations`.',
+  status: 'general-availability',
+  usageGuidelines: ['Import from this explicit public entrypoint rather than a source-internal path.', 'Keep host lifecycle, permissions, and network orchestration at the integration boundary.'],
+  keywords: ['studio', 'rovo', 'agent'],
+  category: 'studio',
+  package: '@atlassian/studio-agent-editor',
+  examples: []
+}, {
+  name: 'useSkillsUpdater',
+  description: 'Public hook `useSkillsUpdater` exported by `@atlassian/studio-agent-editor/domains/skills/updaters`.',
+  status: 'general-availability',
+  usageGuidelines: ['Import from this explicit public entrypoint rather than a source-internal path.', 'Keep host lifecycle, permissions, and network orchestration at the integration boundary.'],
+  keywords: ['studio', 'rovo', 'agent'],
+  category: 'studio',
+  package: '@atlassian/studio-agent-editor',
+  examples: []
+}, {
+  name: 'useToolConfigurationUpdater',
+  description: 'Public hook `useToolConfigurationUpdater` exported by `@atlassian/studio-agent-editor/domains/tools/updaters`.',
+  status: 'general-availability',
+  usageGuidelines: ['Import from this explicit public entrypoint rather than a source-internal path.', 'Keep host lifecycle, permissions, and network orchestration at the integration boundary.'],
+  keywords: ['studio', 'rovo', 'agent'],
+  category: 'studio',
+  package: '@atlassian/studio-agent-editor',
+  examples: []
+}, {
+  name: 'useToolsUpdater',
+  description: 'Public hook `useToolsUpdater` exported by `@atlassian/studio-agent-editor/domains/tools/updaters`.',
+  status: 'general-availability',
+  usageGuidelines: ['Import from this explicit public entrypoint rather than a source-internal path.', 'Keep host lifecycle, permissions, and network orchestration at the integration boundary.'],
+  keywords: ['studio', 'rovo', 'agent'],
+  category: 'studio',
+  package: '@atlassian/studio-agent-editor',
+  examples: []
+}, {
+  name: 'useUpdateAgentDetailsMutation',
+  description: 'Public hook `useUpdateAgentDetailsMutation` exported by `@atlassian/studio-agent-editor/domains/agent-details/mutations`.',
+  status: 'general-availability',
+  usageGuidelines: ['Import from this explicit public entrypoint rather than a source-internal path.', 'Keep host lifecycle, permissions, and network orchestration at the integration boundary.'],
+  keywords: ['studio', 'rovo', 'agent'],
+  category: 'studio',
+  package: '@atlassian/studio-agent-editor',
+  examples: []
+}, {
+  name: 'useAgentProfileViewNavigation',
+  description: 'Public hook `useAgentProfileViewNavigation` exported by `@atlassian/studio-agent-profile/ui/agent-profile/components/AgentProfileViewNavigationProvider`.',
+  status: 'general-availability',
+  usageGuidelines: ['Import from this explicit public entrypoint rather than a source-internal path.', 'Keep host lifecycle, permissions, and network orchestration at the integration boundary.'],
+  keywords: ['studio', 'rovo', 'agent'],
+  category: 'studio',
+  package: '@atlassian/studio-agent-profile',
+  examples: []
+}, {
+  name: 'useAvailableConfigsByTier',
+  description: 'Public hook `useAvailableConfigsByTier` exported by `@atlassian/studio-agent-profile/agent-reasoning/use-available-configs-by-tier`.',
+  status: 'general-availability',
+  usageGuidelines: ['Import from this explicit public entrypoint rather than a source-internal path.', 'Keep host lifecycle, permissions, and network orchestration at the integration boundary.'],
+  keywords: ['studio', 'rovo', 'agent'],
+  category: 'studio',
+  package: '@atlassian/studio-agent-profile',
+  examples: []
+}, {
+  name: 'useVisibleExecutionTierOptions',
+  description: 'Public hook `useVisibleExecutionTierOptions` exported by `@atlassian/studio-agent-profile/agent-reasoning/use-visible-execution-tier-options`.',
+  status: 'general-availability',
+  usageGuidelines: ['Import from this explicit public entrypoint rather than a source-internal path.', 'Keep host lifecycle, permissions, and network orchestration at the integration boundary.'],
+  keywords: ['studio', 'rovo', 'agent'],
+  category: 'studio',
+  package: '@atlassian/studio-agent-profile',
   examples: []
 }];