feat(cost-insights): Introduce Cost Insights feature

AGENTS.md

@@ -134,6 +134,7 @@ Business-rule specs live in `.specs/`. Before making **any** changes to a domain
 | `.specs/kiloclaw-controller.md` | KiloClaw controller/machine lifecycle, bootstrap, Docker image |
 | `.specs/kiloclaw-datamodel.md` | KiloClaw data model — instance/subscription tables, invariants |
 | `.specs/model-experiments.md` | Model experiment routing, bucketing, lifecycle, prompt retention, and reporting rules |
+| `.specs/cost-insights.md` | Cost Insights and Spend Alerts owner scope, anomaly alerts, threshold alerts, and alert acknowledgments |
 | `.specs/security-agent.md` | Security Agent Auto Remediation and finding/SLA notification guarantees |
 | `.specs/subscription-center.md` | Subscription Center ownership, states, and user-facing behavior |
 | `.specs/team-enterprise-seat-billing.md` | Team and Enterprise seat billing, subscription management |

apps/storybook/stories/Sidebar.stories.tsx

@@ -6,6 +6,7 @@ import {
   Building2,
   Cable,
   ChartColumnIncreasing,
+  ChartLine,
   ChevronLeft,
   ChevronRight,
   Cloud,
@@ -109,6 +110,11 @@ const dashboardItems: SidebarStoryItem[] = [
     icon: ChartColumnIncreasing,
     url: '/usage',
   },
+  {
+    title: 'Cost Insights',
+    icon: ChartLine,
+    url: '/cost-insights',
+  },
 ];
 
 const kiloClawItems: SidebarStoryItem[] = [

apps/storybook/stories/cost-insights/AskKilo.stories.tsx

@@ -0,0 +1,28 @@
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import { CostInsightsAskKiloView, CostInsightsShellView } from '@/components/cost-insights';
+import { personalOwner } from './costInsightsFixtures';
+
+const meta: Meta<typeof CostInsightsAskKiloView> = {
+  title: 'Cost Insights/Ask Kilo',
+  component: CostInsightsAskKiloView,
+  parameters: { layout: 'fullscreen' },
+};
+
+export default meta;
+type Story = StoryObj<typeof CostInsightsAskKiloView>;
+
+function AskKiloStory({ initialQuestion }: { initialQuestion?: string }) {
+  return (
+    <CostInsightsShellView owner={personalOwner} activePage="ask">
+      <CostInsightsAskKiloView initialQuestion={initialQuestion} />
+    </CostInsightsShellView>
+  );
+}
+
+export const DisabledPreview: Story = {
+  render: () => <AskKiloStory />,
+};
+
+export const DisabledPreviewWithQuestion: Story = {
+  render: () => <AskKiloStory initialQuestion="Show my spend for the last 30 days" />,
+};

apps/storybook/stories/cost-insights/CostInsightsAlertBar.stories.tsx

@@ -0,0 +1,32 @@
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import { CostInsightsAlertBar } from '@/components/cost-insights';
+import { organizationOwner } from './costInsightsFixtures';
+
+const meta = {
+  title: 'Cost Insights/In-App Alert Bar',
+  component: CostInsightsAlertBar,
+  parameters: { layout: 'fullscreen' },
+  args: {
+    owner: organizationOwner,
+    alertCount: 2,
+    reviewHref: '/organizations/4f2fc143-4b30-4c8a-878b-df89c89c6790/cost-insights',
+  },
+  decorators: [
+    Story => (
+      <div className="bg-background min-h-screen">
+        <header className="border-border bg-surface-raised flex h-14 items-center border-b px-4 type-body font-semibold md:px-6">
+          Kilo Cloud
+        </header>
+        <Story />
+        <main className="mx-auto max-w-[1140px] p-4 md:p-6">
+          <div className="type-heading">Account overview</div>
+        </main>
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof CostInsightsAlertBar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const AlertsNeedReview: Story = {};

apps/storybook/stories/cost-insights/EventHistory.stories.tsx

@@ -0,0 +1,129 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import {
+  CostInsightsEventHistoryView,
+  CostInsightsShellView,
+  type ActivityFilter,
+  type CostInsightsOwner,
+  type CostInsightEvent,
+} from '@/components/cost-insights';
+import {
+  allEvents,
+  longLabelEvents,
+  organizationOwner,
+  personalOwner,
+  threshold7DayEvent,
+} from './costInsightsFixtures';
+
+const paginatedEvents = Array.from({ length: 23 }, (_, index): CostInsightEvent => {
+  const event = allEvents[index % allEvents.length];
+  if (!event) throw new Error('Activity fixture requires at least one event');
+  return {
+    ...event,
+    id: `${event.id}-${index}`,
+    occurredAt:
+      index < 5
+        ? event.occurredAt
+        : new Date(
+            new Date(event.occurredAt).getTime() - (Math.floor(index / 5) + 1) * 24 * 60 * 60 * 1000
+          ).toISOString(),
+  };
+});
+
+const meta: Meta<typeof CostInsightsEventHistoryView> = {
+  title: 'Cost Insights/Activity',
+  component: CostInsightsEventHistoryView,
+  parameters: { layout: 'fullscreen' },
+};
+
+export default meta;
+type Story = StoryObj<typeof CostInsightsEventHistoryView>;
+
+function ActivityStory({
+  events,
+  owner,
+  empty,
+}: {
+  events: CostInsightEvent[];
+  owner: CostInsightsOwner;
+  empty: boolean;
+}) {
+  const [filter, setFilter] = useState<ActivityFilter>('all');
+  const [page, setPage] = useState(1);
+  const filteredEvents = events.filter(event => {
+    if (filter === 'alerts') return ['anomaly_alert', 'threshold_crossed'].includes(event.type);
+    if (filter === 'suggestions')
+      return ['suggestion_created', 'suggestion_dismissed'].includes(event.type);
+    if (filter === 'reviews') return event.type === 'reviewed';
+    if (filter === 'settings') return ['config_changed', 'disabled'].includes(event.type);
+    return true;
+  });
+  const pageCount = Math.max(1, Math.ceil(filteredEvents.length / 10));
+  const currentPage = Math.min(page, pageCount);
+  const pageEvents = filteredEvents.slice((currentPage - 1) * 10, currentPage * 10);
+  const basePath =
+    owner.type === 'organization'
+      ? '/organizations/acme-cost-insights/cost-insights'
+      : '/cost-insights';
+
+  return (
+    <CostInsightsShellView owner={owner} activePage="events" basePath={basePath}>
+      <CostInsightsEventHistoryView
+        events={pageEvents}
+        empty={empty}
+        filter={filter}
+        page={currentPage}
+        pageCount={pageCount}
+        totalCount={filteredEvents.length}
+        onFilterChange={nextFilter => {
+          setFilter(nextFilter);
+          setPage(1);
+        }}
+        onPageChange={setPage}
+      />
+    </CostInsightsShellView>
+  );
+}
+
+function renderActivity(
+  events: CostInsightEvent[],
+  owner: CostInsightsOwner = personalOwner,
+  empty = false
+) {
+  return <ActivityStory events={events} owner={owner} empty={empty} />;
+}
+
+export const ActivityHistory: Story = {
+  render: () => renderActivity(paginatedEvents, organizationOwner),
+};
+
+export const SevenDayThresholdActivity: Story = {
+  render: () => renderActivity([threshold7DayEvent], organizationOwner),
+};
+
+export const Empty: Story = {
+  render: () => renderActivity([], personalOwner, true),
+};
+
+export const Loading: Story = {
+  render: () => (
+    <CostInsightsShellView owner={personalOwner} activePage="events">
+      <CostInsightsEventHistoryView events={[]} isLoading />
+    </CostInsightsShellView>
+  ),
+};
+
+export const LoadError: Story = {
+  render: () => (
+    <CostInsightsShellView owner={personalOwner} activePage="events">
+      <CostInsightsEventHistoryView events={[]} isError />
+    </CostInsightsShellView>
+  ),
+};
+
+export const Mobile: Story = {
+  render: () => renderActivity(longLabelEvents, organizationOwner),
+  globals: {
+    viewport: { value: 'mobile2', isRotated: false },
+  },
+};