Skip to content

Commit 85675b0

Browse files
committed
Add Conversation Arc docs, blog entry, and fixes
Add a new Conversation Arc docs page with interactive demos (conversation arc store + freshness scrubber), wire the route into the docs app and nav, and include the new blog entry "talk-track-intelligence". Update docs metadata and entries to surface the new post. Standardize provenance/lifecycle field names to camelCase (e.g. createdAt, stableId, ttlHint, baseComponent, variantKey, proposalId) across docs and examples and update related tests. Tweak prerender route titles and a minified-shell test fixture; adjust prev/next links between feature pages. Overall: docs + demo additions, minor API/docs text changes, and test updates to match the new naming.
1 parent 0776d9a commit 85675b0

17 files changed

Lines changed: 1131 additions & 47 deletions

CLAUDE.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -343,8 +343,8 @@ store.record({ type: "suggestion-shown", components: ["LineChart"], intent: "tre
343343

344344
### Annotation provenance + lifecycle (`semiotic/ai`, types also re-exported from `semiotic`)
345345
Type surface for "where did this annotation come from?" and "is it stale?" Optional blocks attached to any annotation — existing arrays keep working unchanged.
346-
- **`provenance`**: `{ author?, source?, confidence?, created_at?, stable_id? }`. `source` is an open string union (`"user" | "ai" | "agent" | "import" | "computed" | "system" | (string & {})`).
347-
- **`lifecycle`**: `{ freshness?, ttl_hint?, anchor? }`. `freshness` is `"fresh" | "aging" | "stale" | "expired"`. `anchor` is `"fixed" | "latest" | "sticky" | "semantic"`. `ttl_hint` accepts an ISO 8601 duration string (`"P30D"`) or milliseconds.
346+
- **`provenance`**: `{ author?, source?, confidence?, createdAt?, stableId? }`. `source` is an open string union (`"user" | "ai" | "agent" | "import" | "computed" | "system" | (string & {})`).
347+
- **`lifecycle`**: `{ freshness?, ttlHint?, anchor? }`. `freshness` is `"fresh" | "aging" | "stale" | "expired"`. `anchor` is `"fixed" | "latest" | "sticky" | "semantic"`. `ttlHint` accepts an ISO 8601 duration string (`"P30D"`) or milliseconds.
348348
- **`withProvenance(annotation, { provenance?, lifecycle? })`** → returns a new annotation with the blocks attached. Pure, SSR-safe.
349349
- **`Annotated<T>`** type alias: `T & { provenance?, lifecycle? }`. Use for explicit typing.
350350
- Type surface only at this stage. Freshness computation, default visual treatment, and stable-id anchor resolution land later.
@@ -355,16 +355,16 @@ import { withProvenance } from "semiotic/ai"
355355
const ann = withProvenance(
356356
{ type: "y-threshold", value: 100, label: "SLA breach" },
357357
{
358-
provenance: { author: "alice", source: "user", created_at: "2026-05-20T14:00:00Z" },
359-
lifecycle: { ttl_hint: "P30D", anchor: "semantic" },
358+
provenance: { author: "alice", source: "user", createdAt: "2026-05-20T14:00:00Z" },
359+
lifecycle: { ttlHint: "P30D", anchor: "semantic" },
360360
},
361361
)
362362
```
363363

364364
### Variant discovery (`semiotic/ai`)
365365
Interface for proposing and scoring chart variants beyond the hand-curated `capability.variants`. Heuristic and model-based proposers plug in through `registerVariantDiscovery`. M1 ships the type surface + stub implementations; behavior arrives in subsequent milestones.
366-
- **`VariantProposal`**: `{ id, base_component, intent_deltas?, rubric_deltas?, buildProps?, rationale?, source: "manual" | "heuristic" | "model", variant_key?, tags? }`.
367-
- **`VariantScore`**: `{ proposal_id, fit (0–5), novelty (0–1), risk (0–1), reasons }`. `fit` mixes with `suggestCharts` composite scores in unified rankings.
366+
- **`VariantProposal`**: `{ id, baseComponent, intentDeltas?, rubricDeltas?, buildProps?, rationale?, source: "manual" | "heuristic" | "model", variantKey?, tags? }`.
367+
- **`VariantScore`**: `{ proposalId, fit (0–5), novelty (0–1), risk (0–1), reasons }`. `fit` mixes with `suggestCharts` composite scores in unified rankings.
368368
- **`proposeVariant(component, capability, context)`**`VariantProposal[]`. M1 stub returns `[]`.
369369
- **`evaluateVariantProposal(proposal, profile, audience?)`**`VariantScore`. M1 stub returns a neutral baseline with a reason pointing back at the design doc.
370370
- **`registerVariantDiscovery(fn)`** → registers an external proposer, returns an unregister callback. Pair with `getRegisteredVariantDiscovery()` / `clearVariantDiscovery()` for inspection and teardown.

docs/src/App.js

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ import CustomChartsPage from "./pages/features/CustomChartsPage"
9696
import CapabilitiesPage from "./pages/features/CapabilitiesPage"
9797
import InterrogationPage from "./pages/features/InterrogationPage"
9898
import SuggestionsPage from "./pages/features/SuggestionsPage"
99+
import ConversationArcPage from "./pages/features/ConversationArcPage"
99100

100101
// New cookbook pages
101102
import HomerunMapPage from "./pages/cookbook/HomerunMapPage"
@@ -399,6 +400,7 @@ export default function DocsApp() {
399400
<Route path="capabilities" element={<CapabilitiesPage />} />
400401
<Route path="suggestions" element={<SuggestionsPage />} />
401402
<Route path="interrogation" element={<InterrogationPage />} />
403+
<Route path="conversation-arc" element={<ConversationArcPage />} />
402404
<Route path="serialization" element={<SerializationPage />} />
403405
<Route path="vega-lite" element={<VegaLiteTranslatorPage />} />
404406
</Route>

docs/src/blog/entries-meta.js

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,18 @@ export const allBlogEntriesMeta = [
3030
excerpt:
3131
"3.6.0 turns Semiotic's observation hooks, native annotations, and streaming runtime into an explicit AI-facing surface. Charts declare what they're for; datasets get profiled and ranked; audiences get calibrated; conversations anchor back to the chart instead of stopping at a chat bubble. Three case-study posts published alongside the release walk through what the new shape makes possible.",
3232
},
33+
{
34+
slug: "talk-track-intelligence",
35+
title: "The arc, the annotation, and the variant",
36+
subtitle:
37+
"Three composable AI surfaces shipping together in 3.5.x: conversation-arc telemetry, annotation provenance + lifecycle, and a variant discovery plug point. Two are runnable inline.",
38+
author: "Elijah Meeks",
39+
date: "2026-05-27",
40+
tags: ["case-study", "ai", "roadmap"],
41+
excerpt:
42+
"AI-assisted chart authoring is a session, not a single call. Semiotic 3.5.x lands the spine for treating that session as a first-class thing — an event vocabulary for the arc itself, provenance + lifecycle on every annotation, and an extension surface for variant proposers. Interactive demos for the first two.",
43+
draft: true,
44+
},
3345
{
3446
slug: "live-conversational-dashboard",
3547
title: "Live conversational dashboards",

docs/src/blog/entries.js

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ import MultimodalResponse from "./entries/multimodal-response.js"
5252
import AnchoredConversations from "./entries/anchored-conversations.js"
5353
import LiveDashboard from "./entries/live-conversational-dashboard.js"
5454
import Release360 from "./entries/release-3-6-0.js"
55+
import TalkTrackIntelligence from "./entries/talk-track-intelligence.js"
5556

5657
/**
5758
* Every entry, drafts included. Consumers that need the full list (direct
@@ -60,6 +61,7 @@ import Release360 from "./entries/release-3-6-0.js"
6061
*/
6162
export const allBlogEntries = [
6263
Release360,
64+
TalkTrackIntelligence,
6365
LiveDashboard,
6466
AnchoredConversations,
6567
MultimodalResponse,

0 commit comments

Comments
 (0)