docs: chat citations + adapter bridge documentation

Add minimal documentation for the @Ngaf 0.0.21 citations release across all adapter libraries and changelog.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: blove

CHANGELOG.md

@@ -1,3 +1,16 @@
+## 0.0.21 — 2026-05-04
+
+### Added
+
+- **`@ngaf/chat`** — `Citation` interface, `Message.citations` field, `<chat-citations>` primitive (sources panel), `MarkdownCitationReferenceComponent` registered in the markdown view registry, `CitationsResolverService` for message-first / markdown-fallback citation lookup.
+- **`@ngaf/langgraph`** — `extractCitations()` populates `Message.citations` from `additional_kwargs.citations` or `additional_kwargs.sources`.
+- **`@ngaf/ag-ui`** — `bridgeCitationsState()` populates `Message.citations` from STATE_DELTA at JSON Pointer `/citations/{messageId}`.
+- **`@cacheplane/partial-markdown`** peer in `@ngaf/chat` bumped to `^0.2.0`.
+
+### Changed
+
+- **All @ngaf libraries synchronized to `0.0.21`** per project policy (single version across the suite).
+
 ## 0.0.2 (2026-05-01)
 
 ### 🩹 Fixes

libs/ag-ui/README.md

@@ -20,3 +20,29 @@ export class App {
   protected readonly agent = inject(AG_UI_AGENT);
 }
 ```
+
+## Citations
+
+The `bridgeCitationsState()` function populates `Message.citations` from AG-UI STATE_DELTA events. Citations are located at JSON Pointer `/citations/{messageId}`.
+
+### Example: AG-UI citations state shape
+
+```json
+{
+  "state": {
+    "citations": {
+      "msg-123": [
+        {
+          "id": "src1",
+          "index": 1,
+          "title": "Example Source",
+          "url": "https://example.com",
+          "snippet": "Relevant excerpt from the source..."
+        }
+      ]
+    }
+  }
+}
+```
+
+Each citation object in the array supports `id`, `index`, `title`, `url`, `snippet`, and custom `extra` fields. The messageId key matches the corresponding message in the chat history.

libs/chat/README.md

@@ -12,3 +12,52 @@ Chat primitives consume a runtime-neutral `Agent` contract. Two adapters ship to
 Custom backends can implement `Agent` directly with no library dependency.
 
 See the capability matrix in the docs site for which primitives require which runtime capabilities.
+
+## Citations
+
+Chat messages can include citations to sources. The `Citation` interface provides structured metadata for each source:
+
+```ts
+interface Citation {
+  id: string;          // Unique identifier for the citation
+  index?: number;      // Display index (1-based) for inline markers
+  title?: string;      // Source title
+  url?: string;        // Source URL
+  snippet?: string;    // Quoted excerpt
+  extra?: unknown;     // Custom fields per adapter
+}
+```
+
+### Message citations
+
+Adapters populate `Message.citations?: Citation[]` from their respective backends. Messages are rendered with the `<chat-citations [message]="message" />` primitive, which displays a collapsible sources panel under assistant messages.
+
+### Rendering sources
+
+Use the `<chat-citations>` component to render a sources panel. Customize the card layout with the optional `chatCitationCard` ng-template:
+
+```html
+<chat [agent]="agent" />
+<!-- or explicit: -->
+<chat-citations [message]="message">
+  <ng-template chatCitationCard let-citation>
+    <div class="custom-card">
+      <a [href]="citation.url">{{ citation.title }}</a>
+      <p class="text-sm text-gray-600">{{ citation.snippet }}</p>
+    </div>
+  </ng-template>
+</chat-citations>
+```
+
+### Inline markers
+
+Markdown rendering registers `chat-md-citation-reference` in the markdown view registry. Citation indices are rendered as superscript markers inline with the message text. The markers link to the corresponding citation in the sources panel.
+
+### Adapter integration
+
+Each runtime adapter extracts citations into the `Message.citations` array:
+
+- **LangGraph** — reads from `message.additional_kwargs.citations` (preferred) or `message.additional_kwargs.sources` (fallback)
+- **AG-UI** — reads from STATE_DELTA at JSON Pointer `/citations/{messageId}`
+
+The `CitationsResolverService` is provided to query citations in message-first or markdown-fallback order.

libs/langgraph/README.md

@@ -1,3 +1,34 @@
-# angular
+# @ngaf/langgraph
 
-This library was generated with [Nx](https://nx.dev).
+Adapter that wraps a LangGraph agent into the runtime-neutral `Agent` contract from `@ngaf/chat`.
+
+## Citations
+
+The `extractCitations()` function populates `Message.citations` from LangGraph message metadata. It reads from `additional_kwargs.citations` (preferred) or `additional_kwargs.sources` (fallback).
+
+### Example: RAG chain with citations
+
+```ts
+import { additional_kwargs } from '@langchain/core/messages';
+
+// In your LangGraph node:
+const response = await llm.invoke([...]);
+
+// Attach citations metadata:
+const messageWithCitations = new AIMessage({
+  content: response.content,
+  additional_kwargs: {
+    citations: [
+      {
+        id: 'doc-1',
+        index: 1,
+        title: 'Example Article',
+        url: 'https://example.com/article',
+        snippet: 'Relevant excerpt...'
+      }
+    ]
+  }
+});
+
+// Message.citations auto-populates in @ngaf/chat via extractCitations()
+```