DeepCitation · bensonwong · Mar 16, 2026 · Mar 16, 2026 · Mar 16, 2026 · Mar 16, 2026
diff --git a/BRANDING.md b/BRANDING.md
@@ -0,0 +1,103 @@
+# DeepCitation SDK — Sub-Brand Guide
+
+The SDK is a **sub-brand** of DeepCitation. It is designed to embed harmoniously within any host application, so its visual defaults intentionally differ from the DeepCitation web app.
+
+---
+
+## Sub-Brand vs Web App
+
+| Property | Web App | SDK |
+|----------|---------|-----|
+| Color palette | Slate scale (`slate-*`) | `--dc-*` CSS custom properties |
+| Border radius | Sharp (`rounded-none`) | Soft (`rounded-lg` / 8px) |
+| Font | Inter (loaded) | System font stack |
+| Customization | Tailwind classes | `--dc-*` tokens + `<DeepCitationTheme>` React prop |
+
+The soft corners and system font ensure the SDK feels at home in any host UI without imposing the web app's editorial aesthetic.
+
+---
+
+## Color Tokens
+
+All SDK colors are expressed as `--dc-*` CSS custom properties. Host applications can override the entire palette via CSS or the `DeepCitationTheme` React component.
+
+### Surface & Text
+
+| Token | Light | Dark | Usage |
+|-------|-------|------|-------|
+| `--dc-background` | `#ffffff` | `#27272a` | Card / popover / drawer surface |
+| `--dc-muted` | `#f4f4f5` | `#3f3f46` | Subdued surface: code blocks, tab bars |
+| `--dc-foreground` | `#18181b` | `#fafafa` | Primary text |
+| `--dc-muted-foreground` | `#71717a` | `#a1a1aa` | Body text, secondary labels |
+| `--dc-subtle-foreground` | `#a1a1aa` | `#71717a` | Icons, timestamps, tertiary text |
+| `--dc-border` | `#e4e4e7` | `#3f3f46` | Borders and dividers |
+| `--dc-ring` | `#3b82f6` | `#3b82f6` | Focus ring |
+
+### Verification Status
+
+| Token | Light | Dark | Usage |
+|-------|-------|------|-------|
+| `--dc-verified` | `#16a34a` | `#22c55e` | Verified citation |
+| `--dc-partial` | `#f59e0b` | `#fbbf24` | Partial match |
+| `--dc-destructive` | `#ef4444` | `#f87171` | Not found / error |
+| `--dc-pending` | `#a1a1aa` | `#71717a` | Pending / loading |
+
+---
+
+## Customization
+
+### CSS (global override)
+
+```css
+:root {
+  --dc-background: #fdfbf7;
+  --dc-border: #e2e0dc;
+  --dc-verified: #0d9488;
+}
+.dark {
+  --dc-background: #1c1917;
+  --dc-border: #44403c;
+}
+```
+
+### React component
+
+```tsx
+import { DeepCitationTheme } from "deepcitation";
+
+<DeepCitationTheme
+  theme={{ background: "#fdfbf7", border: "#e2e0dc", verified: "#0d9488" }}
+  darkTheme={{ background: "#1c1917", border: "#44403c" }}
+/>
+```
+
+All `--dc-*` tokens are accepted as camelCase props (e.g. `mutedForeground`, `subtleForeground`).
+
+---
+
+## Typography
+
+The SDK uses the system font stack. **Never** load or reference Inter, Playfair Display, or any external font in SDK components.
+
+```css
+font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+             "Helvetica Neue", Arial, sans-serif;
+```
+
+---
+
+## Key Rules for Contributors
+
+- Use `text-dc-*` / `bg-dc-*` / `border-dc-*` Tailwind classes — never hardcode `slate-N` for persistent colors
+- Use `rounded-lg` (8px) for containers — never `rounded-none`
+- Do not add external font dependencies
+- Do not override `--dc-*` tokens with `!important` or inline styles
+- Animation timing constants live in `src/react/constants.ts` — do not inline values
+
+---
+
+## References
+
+- Full implementation rules for contributors modifying SDK internals: [`docs/agents/branding.md`](docs/agents/branding.md)
+- Web app brand (full brand spec): [`packages/deepcitation-web/BRANDING.md`](../deepcitation-web/BRANDING.md)
+- Styling guide for consumers: [docs.deepcitation.com/styling](https://docs.deepcitation.com/styling)
diff --git a/README.md b/README.md
@@ -86,7 +86,7 @@ A set of high-quality React components to help you build production-ready attrib
 
 **Works with any LLM** -- OpenAI, Anthropic, Google, AI SDK, local models, or any leading model.
 
-| <img src="https://deepcitation.com/logos/openai.svg" width="32" height="32" alt="OpenAI logo"> | <img src="https://deepcitation.com/logos/anthropic.svg" width="32" height="32" alt="Anthropic logo"> | <img src="https://deepcitation.com/logos/google.svg" width="32" height="32" alt="Google Gemini logo"> | <img src="https://deepcitation.com/logos/vercel.svg" width="32" height="32" alt="Vercel AI SDK logo"> |
+| <picture><source media="(prefers-color-scheme: dark)" srcset="https://deepcitation.com/logos/color/openai.svg"><img src="https://deepcitation.com/logos/openai.svg" width="32" height="32" alt="OpenAI logo"></picture> | <picture><source media="(prefers-color-scheme: dark)" srcset="https://deepcitation.com/logos/color/anthropic.svg"><img src="https://deepcitation.com/logos/anthropic.svg" width="32" height="32" alt="Anthropic logo"></picture> | <picture><source media="(prefers-color-scheme: dark)" srcset="https://deepcitation.com/logos/color/google.svg"><img src="https://deepcitation.com/logos/google.svg" width="32" height="32" alt="Google Gemini logo"></picture> | <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/DeepCitation/deepcitation/main/docs/assets/vercel-white.svg"><img src="https://deepcitation.com/logos/vercel.svg" width="32" height="32" alt="Vercel AI SDK logo"></picture> |
 | --- | --- | --- | --- |
 | OpenAI ✔ | Anthropic ✔ | Gemini ✔ | AI SDK ✔ |
 

diff --git a/docs/agents/branding.md b/docs/agents/branding.md
@@ -226,3 +226,4 @@ SDK uses `rounded-lg` (8px) as default. This is the opposite of the web app's `r
 - Animation rules: `docs/agents/animation-transition-rules.md`
 - React citation UI: `docs/agents/react-citation-ui.md`
 - Web app full brand: `packages/deepcitation-web/BRANDING.md`
+- Contributor-facing sub-brand overview: `packages/deepcitation/BRANDING.md`
diff --git a/docs/agents/docs-site-map.md b/docs/agents/docs-site-map.md
@@ -1,6 +1,6 @@
 ---
-generated_at: "2026-03-12T09:32:04Z"
-commit_sha: "224f843"
+generated_at: "2026-03-16T09:26:19Z"
+commit_sha: "9e9dcbb"
 page_count: 16
 tracked: 14
 stale: 0
@@ -17,72 +17,72 @@ stale: 0
 ### Components
 - **File**: `docs/components.md`
 - **Description**: React CitationComponent documentation
-- **Staleness**: FRESH (8/15 commits since last update)
+- **Staleness**: FRESH (14/15 commits since last update)
 
 ### Curl Guide
 - **File**: `docs/curl-guide.md`
 - **Description**: Direct API usage with curl examples
-- **Staleness**: FRESH (3/15 commits since last update)
+- **Staleness**: FRESH (4/15 commits since last update)
 
 ### LangChain
 - **File**: `docs/frameworks/langchain.md`
 - **Description**: DeepCitation + LangChain: citation verification in your RAG pipeline
-- **Staleness**: FRESH (3/20 commits since last update)
+- **Staleness**: FRESH (7/20 commits since last update)
 
 ### Home
 - **File**: `docs/index.md`
 - **Description**: DeepCitation - Verify AI citations against source documents with visual proof
-- **Staleness**: FRESH (5/30 commits since last update)
+- **Staleness**: FRESH (4/30 commits since last update)
 
 ### Types
 - **File**: `docs/types.md`
 - **Description**: TypeScript interface definitions for DeepCitation
-- **Staleness**: FRESH (3/10 commits since last update)
+- **Staleness**: FRESH (7/10 commits since last update)
 
 ### Next.js App Router
 - **File**: `docs/frameworks/nextjs.md`
 - **Description**: DeepCitation + Next.js App Router: server components, streaming, and use client boundaries
-- **Staleness**: FRESH (7/15 commits since last update)
+- **Staleness**: FRESH (14/15 commits since last update)
 
 ### Getting Started
 - **File**: `docs/getting-started.md`
 - **Description**: Installation and quick start guide for DeepCitation
-- **Staleness**: FRESH (6/20 commits since last update)
+- **Staleness**: FRESH (12/20 commits since last update)
 
 ### Styling
 - **File**: `docs/styling.md`
 - **Description**: CSS customization options for CitationComponent
-- **Staleness**: FRESH (7/20 commits since last update)
+- **Staleness**: FRESH (12/20 commits since last update)
 
 ### Verification Statuses
 - **File**: `docs/verification-statuses.md`
 - **Description**: Understanding verification result statuses
-- **Staleness**: FRESH (2/10 commits since last update)
+- **Staleness**: FRESH (3/10 commits since last update)
 
 ### API Reference
 - **File**: `docs/api-reference.md`
 - **Description**: REST API endpoints for file preparation and citation verification
-- **Staleness**: FRESH (3/10 commits since last update)
+- **Staleness**: FRESH (4/10 commits since last update)
 
 ### Vercel AI SDK
 - **File**: `docs/frameworks/vercel-ai-sdk.md`
 - **Description**: DeepCitation + Vercel AI SDK: streamText, useChat, and citation verification
-- **Staleness**: FRESH (7/15 commits since last update)
+- **Staleness**: FRESH (13/15 commits since last update)
 
 ### Code Examples
 - **File**: `docs/code-examples.md`
 - **Description**: SDK usage examples and integration patterns
-- **Staleness**: FRESH (3/20 commits since last update)
+- **Staleness**: FRESH (7/20 commits since last update)
 
 ### Error Handling
 - **File**: `docs/error-handling.md`
 - **Description**: Error handling patterns for DeepCitation in production
-- **Staleness**: FRESH (1/15 commits since last update)
+- **Staleness**: FRESH (2/15 commits since last update)
 
 ### Frameworks
 - **File**: `docs/frameworks/index.md`
 - **Description**: Framework-specific integration guides for DeepCitation
-- **Staleness**: FRESH (3/30 commits since last update)
+- **Staleness**: FRESH (7/30 commits since last update)
 
 ### 404
 - **File**: `docs/404.md`

diff --git a/docs/agents/repo-map.md b/docs/agents/repo-map.md
@@ -1,7 +1,7 @@
 ---
-generated_at: "2026-03-12T09:31:59Z"
-commit_sha: "224f843"
-commit_sha_full: "224f843143979aa746e08bc002a0407965686ec2"
+generated_at: "2026-03-16T09:26:13Z"
+commit_sha: "9e9dcbb"
+commit_sha_full: "9e9dcbb046ae65ba18fece1103ea7ff3ff68cce8"
 stale_after_commits: 30
 ---
 
@@ -30,10 +30,11 @@ Source
 src/  # Source files
   __tests__/  # Unit test files
   client/  # DeepCitation API client
+  docs/  # (no description)
   drawing/  # Drawing/canvas utilities
   markdown/  # Markdown rendering (renderMarkdown, markdownVariants)
     testing/  # Markdown test helpers
-  parsing/  # Citation extraction: parseCitation, parseCitationResponse, parseWorkAround
+  parsing/  # Citation extraction: parseCitation, normalizeCitation, parseWorkAround
   prompts/  # LLM prompt templates (citationPrompts, promptCompression)
   react/  # React components and hooks (CitationComponent, SourcesList, i18n, popovers)
     hooks/  # Extracted React hooks
@@ -85,5 +86,6 @@ examples/  # Integration examples (Next.js, etc.)
   assets/  # Shared example assets
   basic-verification/  # Basic citation verification example
   nextjs-ai-sdk/  # Next.js AI SDK integration example
+  static-html/  # (no description)
   url-example/  # URL citation verification example
 ```
diff --git a/docs/assets/vercel-white.svg b/docs/assets/vercel-white.svg
diff --git a/docs/frameworks/langchain.md b/docs/frameworks/langchain.md
@@ -98,7 +98,7 @@ async function answerWithCitations(pdfPath: string, question: string) {
   const llmOutput = response.content as string;
 
   // 5. Extract and verify citations
-  //    getAllCitationsFromLlmOutput parses <cite> tags from the LLM response.
+  //    getAllCitationsFromLlmOutput parses numeric [N] markers from the LLM response's <<<CITATION_DATA>>> block.
   //    verifyAttachment checks each citation against the source document.
   const citations = getAllCitationsFromLlmOutput(llmOutput);
   const citationCount = Object.keys(citations).length;

diff --git a/docs/frameworks/nextjs.md b/docs/frameworks/nextjs.md
@@ -259,7 +259,7 @@ export default function Home() {
 
 A common question: **does `verifyAttachment()` work on partial (mid-stream) responses?**
 
-**No — verification requires the complete LLM output.** The LLM writes `<cite>` tags that may span multiple streamed chunks. Calling `getAllCitationsFromLlmOutput()` on a partial response will miss citations whose tags haven't fully arrived yet.
+**No — verification requires the complete LLM output.** The LLM appends its `<<<CITATION_DATA>>>` block at the very end of the response. Calling `getAllCitationsFromLlmOutput()` on a partial response will miss the citation data if that block hasn't arrived yet.
 
 The correct pattern (used in the example above) is:
 

diff --git a/docs/frameworks/vercel-ai-sdk.md b/docs/frameworks/vercel-ai-sdk.md
@@ -32,7 +32,7 @@ npm install deepcitation ai @ai-sdk/openai @ai-sdk/react
 
 ## How DeepCitation Integrates with streamText
 
-`streamText` streams tokens to the client. Citation verification must happen **after** streaming ends — `<cite>` tags in the LLM's response may span multiple chunks, so you need the complete output before calling `getAllCitationsFromLlmOutput()`.
+`streamText` streams tokens to the client. Citation verification must happen **after** streaming ends — the LLM appends its `<<<CITATION_DATA>>>` block at the very end of the response, so you need the complete output before calling `getAllCitationsFromLlmOutput()`.
 
 The integration model is:
 

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -35,7 +35,7 @@ Wrap prompts, call your LLM, verify citations, and optionally persist results.
 
 ### Section 3: Display with CitationComponent
 
-Parse `<cite>` tags, generate citation keys, and render inline with verification status.
+Parse numeric `[N]` markers via `parseCitationResponse`, map to citation keys, and render inline with verification status.
 
 ---
 
@@ -64,43 +64,71 @@ bun add deepcitation
 ```typescript
 import { DeepCitation, wrapCitationPrompt, getAllCitationsFromLlmOutput } from "deepcitation";
 
-const deepcitation = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY });
+const dc = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY });
 
-// 1. Upload your source document
-const { attachmentId, deepTextPromptPortion } = await deepcitation.uploadFile(pdfBuffer, {
-  filename: "report.pdf"
-});
+// 1. Prepare your source document
+const { fileDataParts, deepTextPromptPortion } = await dc.prepareAttachments([
+  { file: pdfBuffer, filename: "report.pdf" },
+]);
+const attachmentId = fileDataParts[0].attachmentId;
 
 // 2. Wrap your prompts with citation instructions
 const systemPrompt = "You are a helpful assistant that cites sources.";
 
 const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
   systemPrompt,
   userPrompt,
-  deepTextPromptPortion // Pass file content directly
+  deepTextPromptPortion,
 });
 
 // 3. Call your LLM
 const response = await yourLLM.chat({
   messages: [
     { role: "system", content: enhancedSystemPrompt },
     { role: "user", content: enhancedUserPrompt },
-  ]
+  ],
 });
 
 // 4. Extract and verify citations
 const citations = getAllCitationsFromLlmOutput(response.content);
-const verified = await deepcitation.verify(attachmentId, citations);
+const { verifications } = await dc.verifyAttachment(attachmentId, citations);
 
 // 5. Use verification results
-for (const [key, result] of Object.entries(verified.verifications)) {
+for (const [key, result] of Object.entries(verifications)) {
   console.log(`Citation ${key}: ${result.searchState?.status}`);
   if (result.verificationImageBase64) {
     // Display visual proof to users
   }
 }
 ```
 
+### Section 3: Render (React)
+
+```tsx
+import { parseCitationResponse } from "deepcitation";
+import { CitationComponent } from "deepcitation/react";
+
+const { visibleText, citations, markerMap, splitPattern } = parseCitationResponse(llmOutput);
+
+return (
+  <p>
+    {visibleText.split(splitPattern).map((part, i) => {
+      const key = markerMap[Number(part.replace(/[\[\]]/g, ""))];
+      if (key) {
+        return (
+          <CitationComponent
+            key={`${key}-${i}`}
+            citation={citations[key]}
+            verification={verifications[key]}
+          />
+        );
+      }
+      return <span key={i}>{part}</span>;
+    })}
+  </p>
+);
+```
+
 ---
 
 ## Authentication

diff --git a/docs/index.md b/docs/index.md
@@ -43,7 +43,7 @@ Verify AI citations against source documents. Visual proof for every claim.
 
 1. **Install & Setup** — Install, import types, initialize client, prepare sources, configure proof images
 2. **Server Side** — Wrap prompts, call your LLM, verify citations, optionally persist results
-3. **Display with CitationComponent** — Parse `<cite>` tags, generate citation keys, render inline with verification status
+3. **Display with CitationComponent** — Parse numeric `[N]` markers via `parseCitationResponse`, map to citation keys, render inline with verification status
 
 ---
 
@@ -65,12 +65,12 @@ npm install deepcitation
 ```typescript
 import { DeepCitation, wrapCitationPrompt, getAllCitationsFromLlmOutput } from "deepcitation";
 
-const deepcitation = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY });
+const dc = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY });
 
-// Upload and verify in 3 steps
-const { attachmentId, deepTextPromptPortion } = await deepcitation.uploadFile(pdfBuffer, { filename: "report.pdf" });
+// Prepare, wrap, verify in 3 steps
+const { fileDataParts, deepTextPromptPortion } = await dc.prepareAttachments([{ file: pdfBuffer, filename: "report.pdf" }]);
 const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({ systemPrompt, userPrompt, deepTextPromptPortion });
 // ... call your LLM ...
 const citations = getAllCitationsFromLlmOutput(response.content);
-const verified = await deepcitation.verify(attachmentId, citations);
+const { verifications } = await dc.verifyAttachment(fileDataParts[0].attachmentId, citations);
 ```