+ )
+}
+
+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..2545a52
--- /dev/null
+++ b/hax/artifacts/contextual-explanation/index.ts
@@ -0,0 +1,29 @@
+/*
+ * 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 } from "./types"
diff --git a/hax/artifacts/contextual-explanation/types.ts b/hax/artifacts/contextual-explanation/types.ts
new file mode 100644
index 0000000..e55ba75
--- /dev/null
+++ b/hax/artifacts/contextual-explanation/types.ts
@@ -0,0 +1,49 @@
+/*
+ * 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"
+
+const ExplanationDetailZod = z.object({
+ label: z.string(),
+ value: z.string(),
+ additionalInfo: z.string().optional(),
+ isSubItem: z.boolean().optional(),
+ isBoldLabel: z.boolean().optional(),
+})
+
+export const ContextualExplanationArtifactZod = z.object({
+ id: z.string(),
+ type: z.literal("contextual-explanation"),
+ data: z.object({
+ title: z.string().optional(),
+ alertTitle: z.string().optional(),
+ alertDescription: z.string().optional(),
+ details: z.array(ExplanationDetailZod),
+ secondaryButtonLabel: z.string().optional(),
+ primaryButtonLabel: z.string().optional(),
+ }),
+})
+
+export type ContextualExplanationArtifact = z.infer<
+ typeof ContextualExplanationArtifactZod
+>
+
+export const ArtifactTabZod = z.discriminatedUnion("type", [
+ ContextualExplanationArtifactZod,
+])
+export type ArtifactTab = z.infer