+ )
+}
+
+export default ContextualExplanationCard
diff --git a/hax/artifacts/contextual-explanation/description.ts b/hax/artifacts/contextual-explanation/description.ts
new file mode 100644
index 0000000..0af9636
--- /dev/null
+++ b/hax/artifacts/contextual-explanation/description.ts
@@ -0,0 +1,33 @@
+/*
+ * Copyright 2025 Cisco Systems, Inc. and its affiliates
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export const CONTEXTUAL_EXPLANATION_DESCRIPTION =
+ `Use contextual explanation artifacts to present structured explanations for system changes, agent decisions, or automated actions. Best for explaining why something happened, displaying configuration changes, routing modifications, and any situation where users need to understand the reasoning behind an action with supporting details.
+
+Structure each explanation with an alert section (title and description explaining why something happened) and a details section with label-value pairs. Include action buttons for user response.
+
+Best practices:
+- Provide a clear, concise alert title that summarizes why something happened
+- Use the alert description to give more context about the reasoning
+- Keep detail labels consistent and descriptive
+- Use isSubItem for hierarchical or nested information
+- Use isBoldLabel to emphasize important details
+- Limit to 5-8 detail items for readability
+- Make button labels action-oriented and clear
+
+Don't use contextual explanations for simple notifications or single-line messages. Avoid vague explanations. Don't include details without clear labels.` as const
diff --git a/hax/artifacts/contextual-explanation/index.ts b/hax/artifacts/contextual-explanation/index.ts
new file mode 100644
index 0000000..74acb41
--- /dev/null
+++ b/hax/artifacts/contextual-explanation/index.ts
@@ -0,0 +1,30 @@
+/*
+ * Copyright 2025 Cisco Systems, Inc. and its affiliates
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export {
+ HAXContextualExplanation,
+ ContextualExplanationCard,
+} from "./contextual-explanation"
+export type {
+ ContextualExplanationCardProps,
+ ExplanationDetail,
+} from "./contextual-explanation"
+export { useContextualExplanationAction } from "./action"
+export type { ContextualExplanationArtifact } from "./types"
+export { ContextualExplanationArtifactZod, ExplanationDetailZod } from "./types"
+export { CONTEXTUAL_EXPLANATION_DESCRIPTION } from "./description"
diff --git a/hax/artifacts/contextual-explanation/types.ts b/hax/artifacts/contextual-explanation/types.ts
new file mode 100644
index 0000000..e2531c5
--- /dev/null
+++ b/hax/artifacts/contextual-explanation/types.ts
@@ -0,0 +1,45 @@
+/*
+ * Copyright 2025 Cisco Systems, Inc. and its affiliates
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import z from "zod"
+
+export const ExplanationDetailZod = z.object({
+ label: z.string().describe("Label for the detail row"),
+ value: z.string().describe("Value/description for the detail row"),
+ additionalInfo: z.string().optional().describe("Optional additional info (e.g., timestamp)"),
+ isSubItem: z.boolean().optional().describe("Whether this is a sub-item (indented)"),
+ isBoldLabel: z.boolean().optional().describe("Whether the label should be bold"),
+})
+export type ExplanationDetail = z.infer
+
+export const ContextualExplanationArtifactZod = z.object({
+ id: z.string(),
+ type: z.literal("contextual-explanation"),
+ data: z.object({
+ title: z.string().optional().describe("Title displayed in the card header"),
+ alertTitle: z.string().optional().describe("Alert title explaining why the change happened"),
+ alertDescription: z.string().optional().describe("Alert description with more details"),
+ details: z.array(ExplanationDetailZod).describe("Array of detail rows to display"),
+ secondaryButtonLabel: z.string().optional().describe("Text for the secondary button"),
+ primaryButtonLabel: z.string().optional().describe("Text for the primary button"),
+ }),
+})
+
+export type ContextualExplanationArtifact = z.infer<
+ typeof ContextualExplanationArtifactZod
+>