@oddkin/ai 0.0.0-stage → 1.0.0-beta.1

package/agent/llms.txt

@@ -0,0 +1,82 @@
+# @oddkin/ai 1.0.0-beta.1
+
+> Optional AI interaction elements, headless controllers, and stream adapters for conversation, inline assistance, research, and agent workflows.
+
+The agent kit for this installed version, generated from its published metadata. Read GUIDE.md first.
+
+## Guide
+
+- [GUIDE.md](GUIDE.md): install, register, the components by category, and the rules
+- [choosing](references/choosing-components.md)
+- [tokens:component](references/tokens/component.md)
+- [tokens:foundation](references/tokens/foundation.md)
+- [tokens:layout](references/tokens/layout.md)
+- [tokens:reference](references/tokens/reference.md)
+- [tokens:semantic](references/tokens/semantic.md)
+- [recipe:action-approval](references/recipes/action-approval.md)
+- [recipe:activity](references/recipes/activity.md)
+- [recipe:ai-element](references/recipes/ai-element.md)
+- [recipe:artifact](references/recipes/artifact.md)
+- [recipe:change-review](references/recipes/change-review.md)
+- [recipe:checkpoint](references/recipes/checkpoint.md)
+- [recipe:citation](references/recipes/citation.md)
+- [recipe:context-picker](references/recipes/context-picker.md)
+- [recipe:conversation](references/recipes/conversation.md)
+- [recipe:inline-assist](references/recipes/inline-assist.md)
+- [recipe:message](references/recipes/message.md)
+- [recipe:prompt-input](references/recipes/prompt-input.md)
+- [recipe:question](references/recipes/question.md)
+- [recipe:response-feedback](references/recipes/response-feedback.md)
+- [recipe:sources](references/recipes/sources.md)
+- [recipe:suggestions](references/recipes/suggestions.md)
+- [recipe:task-plan](references/recipes/task-plan.md)
+- [recipe:tool-call](references/recipes/tool-call.md)
+- [recipe:transcript](references/recipes/transcript.md)
+- [recipe:usage-meter](references/recipes/usage-meter.md)
+- [recipe:voice-input](references/recipes/voice-input.md)
+- [model:oddkin.ai.approval](references/models/oddkin.ai.approval.md)
+- [model:oddkin.ai.artifact](references/models/oddkin.ai.artifact.md)
+- [model:oddkin.ai.checkpoint](references/models/oddkin.ai.checkpoint.md)
+- [model:oddkin.ai.context-item](references/models/oddkin.ai.context-item.md)
+- [model:oddkin.ai.conversation](references/models/oddkin.ai.conversation.md)
+- [model:oddkin.ai.feedback](references/models/oddkin.ai.feedback.md)
+- [model:oddkin.ai.message](references/models/oddkin.ai.message.md)
+- [model:oddkin.ai.model-option](references/models/oddkin.ai.model-option.md)
+- [model:oddkin.ai.plan](references/models/oddkin.ai.plan.md)
+- [model:oddkin.ai.question](references/models/oddkin.ai.question.md)
+- [model:oddkin.ai.suggestion](references/models/oddkin.ai.suggestion.md)
+- [model:oddkin.ai.tool-call](references/models/oddkin.ai.tool-call.md)
+- [model:oddkin.ai.transcript-segment](references/models/oddkin.ai.transcript-segment.md)
+- [model:oddkin.ai.usage](references/models/oddkin.ai.usage.md)
+
+## Components
+
+- [odd-action-approval](references/components/odd-action-approval.md): Review an action, its target, and its changes, then approve or reject it.
+- [odd-activity](references/components/odd-activity.md): Status of the current attempt, separating the work's state from the connection: active tools, approvals, stopping, disconnection, and interruption, with the recovery actions the adapter actually supports (stop, resume, retry).
+- [odd-ai-label](references/components/odd-ai-label.md): A provenance label for generated or assisted content, with the origin details the application supplied in a native disclosure.
+- [odd-artifact](references/components/odd-artifact.md): A generated artifact with a stable identity across revisions: revision history, preview and source modes, application-provided renderers, and export actions.
+- [odd-change-review](references/components/odd-change-review.md): Review proposed edits as before/after or inline word or line diffs; accept, reject, or undo each one.
+- [odd-checkpoint](references/components/odd-checkpoint.md): A restore point: what it restores, a confirmed restore request, pending work, and the outcome the application confirms.
+- [odd-citation](references/components/odd-citation.md): An inline citation marker with an accessible preview of its source.
+- [odd-context-picker](references/components/odd-context-picker.md): Select, inspect, and remove the context sent with a request: files, documents, links, and selected text.
+- [odd-conversation](references/components/odd-conversation.md): A conversation surface: messages as an ARIA feed, history loading, a follow-latest scrolling policy that respects reading earlier content, a visible-anchor guarantee when history is prepended or content above changes size, an explicit "Jump to latest", the run status bar, one announcer for the whole surface, and a slot for the composer.
+- [odd-inline-assist](references/components/odd-inline-assist.md): Selection-based assistance: rewrite, explain, summarize, translate, and expand (or host actions).
+- [odd-message](references/components/odd-message.md): One message: its role, structured parts in order (text, reasoning, files, sources, tools, approvals, artifacts, data), and message actions (copy, regenerate, edit, versions, feedback, provenance).
+- [odd-message-branch](references/components/odd-message-branch.md): Navigate between alternative versions of a message (regenerated answers, edited prompts).
+- [odd-model-select](references/components/odd-model-select.md): Choose among application-provided models, with capabilities and availability.
+- [odd-prompt-input](references/components/odd-prompt-input.md): The prompt composer: an expanding text area with attachments (button, paste, and drop), toolbar slots, send and stop, and a draft that survives failures.
+- [odd-question](references/components/odd-question.md): A clarifying question from an assistant or agent: choices, a structured form, or free text, with an optional custom answer.
+- [odd-response](references/components/odd-response.md): Streamed rich text (Oddkin Markdown) with partial-output, completion, interruption, and error states.
+- [odd-response-feedback](references/components/odd-response-feedback.md): Feedback on one response: a rating, optional reasons and comment, a pending state, and the confirmed outcome from the feedback record.
+- [odd-sources](references/components/odd-sources.md): The list of sources behind a response.
+- [odd-suggestions](references/components/odd-suggestions.md): Suggested prompts.
+- [odd-task-plan](references/components/odd-task-plan.md): An agent's plan: ordered steps, parallel tasks within a step, blockers, progress, and requests for input.
+- [odd-tool-call](references/components/odd-tool-call.md): One tool call: identity, purpose, streamed arguments, execution state, result or failure, and the recovery actions the host supports.
+- [odd-transcript](references/components/odd-transcript.md): A transcript with final segments (optionally editable) and interim text that may still change.
+- [odd-usage-meter](references/components/odd-usage-meter.md): Token, context, quota, and cost figures exactly as the host supplies them, each marked measured, estimated, or unknown.
+- [odd-voice-input](references/components/odd-voice-input.md): Voice capture with transcription: start, stop (keep), and cancel (discard), with permission, device, interruption, and processing states.
+
+## Optional
+
+- [oddkin.metadata.json](../oddkin.metadata.json): every component, recipe, stylesheet, and model by stable id
+- [custom-elements.json](../custom-elements.json): the custom elements manifest

package/agent/references/choosing-components.md

@@ -0,0 +1,78 @@
+# Choosing components in @oddkin/ai
+
+From authored `@useFor`, `@notFor`, and `@category`.
+
+## AI
+
+- `<odd-action-approval>`
+  - Use for: Human approval of agent actions (tool calls, writes, purchases).
+  - Not for: Confirming the user's own direct actions; use a dialog.
+- `<odd-activity>`
+  - Use for: Run status under a conversation or agent panel.
+  - Not for: Per-message status (messages show their own).
+- `<odd-ai-label>`
+  - Use for: Marking responses, artifacts, or edits as AI generated or assisted, with origin details.
+  - Not for: Asserting factual accuracy or safety; use the host's own review states.
+- `<odd-artifact>`
+  - Use for: Documents, code, tables, and other outputs users keep, compare, and export.
+  - Not for: Short inline answers; use the response.
+- `<odd-change-review>`
+  - Use for: Reviewing AI-proposed edits to text or code before they change the document.
+  - Not for: Version-control diffs of whole files.
+- `<odd-checkpoint>`
+  - Use for: Restoring agent or editor state to an earlier point.
+  - Not for: Undoing a single text edit; use the change review's undo.
+- `<odd-citation>`
+  - Use for: Inline references from generated text to its sources.
+  - Not for: Footnotes in authored documents; use links.
+- `<odd-context-picker>`
+  - Use for: Attaching and reviewing context for research and agent requests.
+  - Not for: File management.
+- `<odd-conversation>`
+  - Use for: Chat and assistant conversations, including tool use, approvals, artifacts, and branches.
+  - Not for: Activity logs without messages; use `odd-task-plan` or `odd-activity`.
+- `<odd-inline-assist>`
+  - Use for: Contextual help on selected text in editors and documents.
+  - Not for: Whole-document chat; use the conversation.
+- `<odd-message>`
+  - Use for: Rendering a message from a conversation record.
+  - Not for: Free-form chat bubbles without records.
+- `<odd-message-branch>`
+  - Use for: Alternative responses and edited prompts.
+  - Not for: Pagination of unrelated content.
+- `<odd-model-select>`
+  - Use for: Letting users choose the model used for the next request.
+  - Not for: Settings unrelated to models.
+- `<odd-prompt-input>`
+  - Use for: The input of a conversation or assistant.
+  - Not for: Single-line form fields; use `odd-input`.
+- `<odd-question>`
+  - Use for: Asking the user for missing information before continuing.
+  - Not for: General-purpose forms unrelated to an agent's request.
+- `<odd-response>`
+  - Use for: Assistant output that may stream: answers, explanations, summaries.
+  - Not for: User-authored text (render it literally) or trusted HTML.
+- `<odd-response-feedback>`
+  - Use for: Collecting user feedback on generated responses.
+  - Not for: Surveys or general forms.
+- `<odd-sources>`
+  - Use for: Showing the sources a response used, with titles, hosts, and excerpts.
+  - Not for: Arbitrary link lists; use a list of links.
+- `<odd-suggestions>`
+  - Use for: Follow-up prompts and quick actions after a response.
+  - Not for: Navigation menus.
+- `<odd-task-plan>`
+  - Use for: Showing multi-step agent work as it proceeds.
+  - Not for: Static checklists the user edits.
+- `<odd-tool-call>`
+  - Use for: Showing what an agent or model asked a tool to do, and what happened.
+  - Not for: Arbitrary log output.
+- `<odd-transcript>`
+  - Use for: Showing and correcting speech-to-text results.
+  - Not for: Chat transcripts; use the conversation.
+- `<odd-usage-meter>`
+  - Use for: Showing consumption of tokens, context window, quota, or cost.
+  - Not for: Billing statements; amounts are informational.
+- `<odd-voice-input>`
+  - Use for: Dictating prompts or notes.
+  - Not for: Audio recording for its own sake.

package/agent/references/components/odd-action-approval.md

@@ -0,0 +1,77 @@
+# `<odd-action-approval>` (OddkinActionApproval)
+
+Package `@oddkin/ai` 1.0.0-beta.1 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Review an action, its target, and its changes, then approve or reject it. The decision is a
+request: the element shows it as pending until the authoritative record changes, refuses
+repeated activation for the same revision, and never presents approval as success of the
+action.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/action-approval';`
+- Class: `import { OddkinActionApproval } from '@oddkin/ai/action-approval';`
+- Dependency (button): `<odd-button>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `approval` | none: assign as a property | { approvalId: string; revision: number; title: string; status: "requested" \| "decision-pending" \| "approved" \| "rejected" \| "expired" \| "superseded" \| "decision-failed"; attemptId?: string \| undefined; ... 8 more ...; error?: { ...; } \| undefined; } \| undefined | undefined | The approval record (replace to update; never mutate). |
+| `capabilities` | none: assign as a property | { send?: { available: boolean; reason?: string \| undefined; } \| undefined; stop?: { available: boolean; reason?: string \| undefined; } \| undefined; disconnect?: { available: boolean; reason?: string \| undefined; } \| undefined; ... 12 more ...; feedback?: { ...; } \| undefined; } \| undefined | undefined | `respondToApproval` and `editApproval` decide which controls are enabled. |
+| `announce` | `announce` | "none" \| "important" | 'none' | Announce status changes (only when no surrounding surface announces them). |
+| `strings` | none: assign as a property | Partial<{ approve: string; reject: string; edit: string; reason: string; target: string; changes: string; before: string; after: string; risk: string; low: string; medium: string; high: string; expires: string; ... 12 more ...; announceFailed: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-approval-decide` | CustomEvent<ApprovalDecideDetail> | user (authored) | Request to decide one approval revision. Pending until the record changes. |
+| `odd-approval-edit` | CustomEvent<{ readonly approvalId: string; readonly revision: number; }> | user (authored) | Request to edit the proposed action before deciding. |
+| `odd-announce` | CustomEvent<AnnounceDetail> | notification (authored) | A status message for the nearest announcer, which cancels it so outer announcers stay silent. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `actions` | Decision controls. |
+| `base` | The approval surface. |
+| `changes` | Before/after list. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Human approval of agent actions (tool calls, writes, purchases). (src/action-approval/action-approval.ts:50)
+- Not for: Confirming the user's own direct actions; use a dialog. (src/action-approval/action-approval.ts:51)
+- Accessibility: A labelled group. Decision buttons are native buttons; while a decision is pending they are disabled and the status text explains why. Before/after values carry visually hidden "Before"/"After" labels. (src/action-approval/action-approval.ts:48)
+- Keyboard: Tab to the controls; Enter or Space decides. (src/action-approval/action-approval.ts:49)
+- Limitations: Authorization and execution are enforced by the host; this element only collects intent. (src/action-approval/action-approval.ts:52)
+
+## Examples
+
+- `example:odd-action-approval/default` in src/action-approval/action-approval.examples.ts (package source)
+
+## Customization
+
+- Levels: 1, 2 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/components/odd-activity.md

@@ -0,0 +1,74 @@
+# `<odd-activity>` (OddkinActivity)
+
+Package `@oddkin/ai` 1.0.0-beta.1 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Status of the current attempt, separating the work's state from the connection: active tools,
+approvals, stopping, disconnection, and interruption, with the recovery actions the adapter
+actually supports (stop, resume, retry).
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/activity';`
+- Class: `import { OddkinActivity } from '@oddkin/ai/activity';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `attempt` | none: assign as a property | AttemptRecord \| undefined | undefined | The attempt to describe. |
+| `tools` | none: assign as a property | { toolCallId: string; status: "input-streaming" \| "input-available" \| "awaiting-approval" \| "executing" \| "output-available" \| "output-error" \| "denied" \| "cancelled"; toolName: string; ... 8 more ...; output?: JsonValue \| undefined; }[] | [] | The attempt's tool calls. |
+| `capabilities` | none: assign as a property | { send?: { available: boolean; reason?: string \| undefined; } \| undefined; stop?: { available: boolean; reason?: string \| undefined; } \| undefined; disconnect?: { available: boolean; reason?: string \| undefined; } \| undefined; ... 12 more ...; feedback?: { ...; } \| undefined; } \| undefined | undefined | Which recovery actions to offer. |
+| `strings` | none: assign as a property | Partial<{ submitted: string; accepted: string; streaming: string; tools: string; tool: string; approval: string; 'awaiting-input': string; completed: string; cancelled: string; failed: string; interrupted: string; ... 7 more ...; retry: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-prompt-stop` | CustomEvent<{ readonly attemptId: string \| undefined; }> | user (authored) | Request to stop the underlying work of the identified attempt (not a disconnect). |
+| `odd-attempt-resume` | CustomEvent<{ readonly attemptId: string; }> | user (authored) | Request to reattach to an existing attempt (never starts new work). |
+| `odd-attempt-retry` | CustomEvent<{ readonly attemptId: string; }> | user (authored) | Request a new attempt linked to a failed, interrupted, or cancelled one. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `actions` | Stop, resume, and retry. |
+| `base` | The status bar. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Run status under a conversation or agent panel. (src/activity/activity.ts:39)
+- Not for: Per-message status (messages show their own). (src/activity/activity.ts:40)
+- Accessibility: Plain text, not a live region; the surrounding announcer reports outcomes once. Actions are native buttons that only appear when available. (src/activity/activity.ts:37)
+- Keyboard: Tab to the actions. (src/activity/activity.ts:38)
+
+## Examples
+
+- `example:odd-activity/default` in src/activity/activity.examples.ts (package source)
+- `example:odd-activity/interrupted` in src/activity/activity.examples.ts (package source)
+
+## Customization
+
+- Levels: 1, 2 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/components/odd-ai-label.md

@@ -0,0 +1,69 @@
+# `<odd-ai-label>` (OddkinAiLabel)
+
+Package `@oddkin/ai` 1.0.0-beta.1 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A provenance label for generated or assisted content, with the origin details the application
+supplied in a native disclosure. Shows information as supplied; it never asserts accuracy.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/ai-label';`
+- Class: `import { OddkinAiLabel } from '@oddkin/ai/ai-label';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `provenance` | none: assign as a property | { kind: "generated" \| "assisted" \| "edited" \| "human"; label?: string \| undefined; model?: string \| undefined; provider?: string \| undefined; notes?: string \| undefined; generatedAt?: string \| undefined; } \| undefined | undefined | Origin information supplied by the application. |
+| `strings` | none: assign as a property | Partial<{ generated: string; assisted: string; edited: string; human: string; model: string; provider: string; generatedAt: string; disclaimer: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+None.
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The native disclosure around the label and its details. |
+| `details` | The origin details. |
+| `label` | The visible label (the disclosure summary). |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Marking responses, artifacts, or edits as AI generated or assisted, with origin details. (src/ai-label/ai-label.ts:25)
+- Not for: Asserting factual accuracy or safety; use the host's own review states. (src/ai-label/ai-label.ts:26)
+- Accessibility: The label is a native `<summary>`; its details are read in document order when expanded. (src/ai-label/ai-label.ts:23)
+- Keyboard: Enter or Space toggles the details (native disclosure). (src/ai-label/ai-label.ts:24)
+- Limitations: Labels and details are application-supplied; nothing is inferred from content. (src/ai-label/ai-label.ts:27)
+
+## Examples
+
+- `example:odd-ai-label/default` in src/ai-label/ai-label.examples.ts (package source)
+- `example:odd-ai-label/edited` in src/ai-label/ai-label.examples.ts (package source)
+
+## Customization
+
+- Levels: 1, 2 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/components/odd-artifact.md

@@ -0,0 +1,84 @@
+# `<odd-artifact>` (OddkinArtifact)
+
+Package `@oddkin/ai` 1.0.0-beta.1 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A generated artifact with a stable identity across revisions: revision history, preview and
+source modes, application-provided renderers, and export actions. Copy and the default
+download use the canonical revision content.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/artifact';`
+- Class: `import { OddkinArtifact } from '@oddkin/ai/artifact';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `artifact` | none: assign as a property | { title: string; kind: string; artifactId: string; currentRevisionId: string; revisions: { number: number; revisionId: string; content: string; summary?: string \| undefined; createdAt?: string \| undefined; }[]; language?: string \| undefined; } \| undefined | undefined | The artifact record with all revisions. |
+| `revisionId` | `revision-id` | string | '' | Revision to show; empty shows the current one. |
+| `view` | `view` (reflects) | "source" \| "preview" | 'preview' | Preview or source view. |
+| `renderers` | none: assign as a property | Readonly<Record<string, ArtifactRenderer>> \| undefined | undefined | Host renderers by artifact kind. |
+| `exports` | none: assign as a property | ExportFormat[] | [] | Extra export formats offered through `odd-artifact-export`. |
+| `markdown` | none: assign as a property | MarkdownOptions \| undefined | undefined | Options for the built-in Markdown and code preview. |
+| `strings` | none: assign as a property | Partial<{ revision: string; revisionOption: string; current: string; preview: string; source: string; view: string; copy: string; download: string; copied: string; copyFailed: string; noPreview: string; }> \| undefined | undefined | Localized string overrides. |
+| `revision` | none (read-only) | { number: number; revisionId: string; content: string; summary?: string \| undefined; createdAt?: string \| undefined; } \| undefined |  | The revision on screen. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-artifact-export` | CustomEvent<{ readonly artifactId: string; readonly revisionId: string; readonly format: string; }> | user (authored) | Export requested. The default downloads the canonical source; cancel to export yourself. |
+| `odd-artifact-revision-change` | CustomEvent<{ readonly artifactId: string; readonly revisionId: string; }> | user (authored) | The viewed revision changed (presentation state). |
+| `odd-announce` | CustomEvent<AnnounceDetail> | notification (authored) | A status message for the nearest announcer, which cancels it so outer announcers stay silent. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `header` | Title, revision picker, view toggle, and actions. |
+| `preview` | Preview container (renderer output). |
+| `source` | Source view. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Documents, code, tables, and other outputs users keep, compare, and export. (src/artifact/artifact.ts:49)
+- Not for: Short inline answers; use the response. (src/artifact/artifact.ts:50)
+- Accessibility: A labelled region. The view toggle uses `aria-pressed`; the revision picker is a native select. (src/artifact/artifact.ts:47)
+- Keyboard: Tab through header controls; the source view is scrollable and focusable. (src/artifact/artifact.ts:48)
+- Limitations: `html` and other executable kinds never render without a host renderer; the built-in preview supports `markdown`, `code`, and `text`. (src/artifact/artifact.ts:51)
+
+## Examples
+
+- `example:odd-artifact/default` in src/artifact/artifact.examples.ts (package source)
+- `example:odd-artifact/source` in src/artifact/artifact.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-artifact/codeView` produces `usage.attribute.value`; correct: `example:odd-artifact/source`
+
+## Customization
+
+- Levels: 1, 2 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/components/odd-change-review.md

@@ -0,0 +1,77 @@
+# `<odd-change-review>` (OddkinChangeReview)
+
+Package `@oddkin/ai` 1.0.0-beta.1 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Review proposed edits as before/after or inline word or line diffs; accept, reject, or undo
+each one. Every action is a request; statuses (applied, stale, undone) come from the records,
+which only apply to the revision they were proposed for.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/change-review';`
+- Class: `import { OddkinChangeReview } from '@oddkin/ai/change-review';`
+- Dependency (button): `<odd-button>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `proposals` | none: assign as a property | EditProposal[] | [] | Proposal records (host-owned; e.g. from `DocumentSession`). |
+| `view` | `view` (reflects) | "split" \| "inline" | 'inline' | Inline diff or side-by-side before/after. |
+| `granularity` | `granularity` | "words" \| "lines" | 'words' | Diff by words (prose) or lines (code). |
+| `announce` | `announce` | "none" \| "important" | 'none' | Announce outcomes (when no surrounding surface does). |
+| `strings` | none: assign as a property | Partial<{ label: string; empty: string; before: string; after: string; deleted: string; inserted: string; accept: string; reject: string; undo: string; proposed: string; 'accept-pending': string; applied: string; ... 7 more ...; announceUndone: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-change-accept` | CustomEvent<{ readonly proposalId: string; }> | user (authored) | Request to apply a proposed change to its base revision. |
+| `odd-change-reject` | CustomEvent<{ readonly proposalId: string; }> | user (authored) | Request to discard a proposed change. |
+| `odd-change-undo` | CustomEvent<{ readonly proposalId: string; }> | user (authored) | Request to undo an applied change. |
+| `odd-announce` | CustomEvent<AnnounceDetail> | notification (authored) | A status message for the nearest announcer, which cancels it so outer announcers stay silent. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `diff` | Diff view. |
+| `list` | Proposals. |
+| `proposal` | One proposal. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Reviewing AI-proposed edits to text or code before they change the document. (src/change-review/change-review.ts:42)
+- Not for: Version-control diffs of whole files. (src/change-review/change-review.ts:43)
+- Accessibility: Deletions and insertions use `<del>`/`<ins>` with visually hidden "deleted"/"inserted" text, so meaning does not rely on colour or strikethrough. Each proposal is a labelled group. (src/change-review/change-review.ts:40)
+- Keyboard: Tab through proposals' actions; Enter or Space activates. (src/change-review/change-review.ts:41)
+
+## Examples
+
+- `example:odd-change-review/default` in src/change-review/change-review.examples.ts (package source)
+
+## Customization
+
+- Levels: 1, 2 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/components/odd-checkpoint.md

@@ -0,0 +1,74 @@
+# `<odd-checkpoint>` (OddkinCheckpoint)
+
+Package `@oddkin/ai` 1.0.0-beta.1 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A restore point: what it restores, a confirmed restore request, pending work, and the outcome
+the application confirms. Success is shown only when the record says `restored`.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/checkpoint';`
+- Class: `import { OddkinCheckpoint } from '@oddkin/ai/checkpoint';`
+- Dependency (button): `<odd-button>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `checkpoint` | none: assign as a property | { description: string; label: string; status: "available" \| "restore-pending" \| "restored" \| "restore-failed" \| "unavailable"; checkpointId: string; restores: string[]; error?: { code: string; message: string; retryable?: boolean \| undefined; } \| undefined; createdAt?: string \| undefined; outcome?: string \| undefine... | undefined | The checkpoint record. |
+| `capabilities` | none: assign as a property | { send?: { available: boolean; reason?: string \| undefined; } \| undefined; stop?: { available: boolean; reason?: string \| undefined; } \| undefined; disconnect?: { available: boolean; reason?: string \| undefined; } \| undefined; ... 12 more ...; feedback?: { ...; } \| undefined; } \| undefined | undefined | `restoreCheckpoint` enables restoring. |
+| `announce` | `announce` | "none" \| "important" | 'none' | Announce outcomes (when no surrounding surface does). |
+| `strings` | none: assign as a property | Partial<{ restores: string; restore: string; confirm: string; cancel: string; confirmText: string; available: string; 'restore-pending': string; restored: string; 'restore-failed': string; unavailable: string; created: string; announceRestored: string; announceFailed: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-checkpoint-restore` | CustomEvent<{ readonly checkpointId: string; }> | user (authored) | Request to restore a checkpoint. Success is shown only after the record says restored. |
+| `odd-announce` | CustomEvent<AnnounceDetail> | notification (authored) | A status message for the nearest announcer, which cancels it so outer announcers stay silent. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `actions` | Restore and confirmation controls. |
+| `base` | The checkpoint surface. |
+| `restores` | The list of state the restore replaces. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Restoring agent or editor state to an earlier point. (src/checkpoint/checkpoint.ts:36)
+- Not for: Undoing a single text edit; use the change review's undo. (src/checkpoint/checkpoint.ts:37)
+- Accessibility: A labelled group; restore needs an explicit confirmation step; status is text. (src/checkpoint/checkpoint.ts:34)
+- Keyboard: Tab and Enter or Space; focus moves to the confirmation and back to the status when controls disappear. (src/checkpoint/checkpoint.ts:35)
+
+## Examples
+
+- `example:odd-checkpoint/default` in src/checkpoint/checkpoint.examples.ts (package source)
+- `example:odd-checkpoint/restored` in src/checkpoint/checkpoint.examples.ts (package source)
+
+## Customization
+
+- Levels: 1, 2 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`