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

package/agent/references/components/odd-prompt-input.md

@@ -0,0 +1,116 @@
+# `<odd-prompt-input>` (OddkinPromptInput)
+
+Package `@oddkin/ai` 1.0.0-beta.0 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+The prompt composer: an expanding text area with attachments (button, paste, and drop),
+toolbar slots, send and stop, and a draft that survives failures. Submission is a cancelable
+request; the host acknowledges or fails it by id, and acknowledging an older submission never
+clears newer edits. IME composition never submits.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/prompt-input';`
+- Class: `import { OddkinPromptInput } from '@oddkin/ai/prompt-input';`
+- Dependency (button): `<odd-button>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `controller` | none: assign as a property | ComposerController \| undefined | undefined | Host-owned composer controller; otherwise the element owns one. |
+| `label` | `label` | string | '' | Accessible label; defaults to the localized "Message". |
+| `placeholder` | `placeholder` | string | '' | Placeholder; never a substitute for the label. |
+| `disabled` | `disabled` (reflects) | boolean | false | Prevents editing and sending. |
+| `loading` | `loading` (reflects) | boolean | false | Work is running; shows Stop instead of Send when stopping is available. |
+| `attemptId` | `attempt-id` | string | '' | Attempt targeted by Stop. |
+| `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 | `send`, `stop`, and `attachments` decide which controls are enabled. |
+| `accept` | `accept` | string | '' | Accepted attachment types (comma-separated, as `<input accept>`). |
+| `maxFileSize` | `max-file-size` | number | 0 | Maximum attachment size in bytes (0: no limit). |
+| `maxFiles` | `max-files` | number | 0 | Maximum attachments (0: no limit). |
+| `enterBehavior` | `enter-behavior` | "send" \| "newline" | 'send' | What Enter does. |
+| `strings` | none: assign as a property | Partial<{ label: string; placeholder: string; send: string; stop: string; attach: string; remove: string; hintSend: string; hintNewline: string; sending: string; failed: string; busyAttachments: string; ... 13 more ...; removed: string; }> \| undefined | undefined | Localized string overrides. |
+| `activeController` | none (read-only) | ComposerController |  | The composer in use (host-supplied or owned). |
+| `value` | none: assign as a property | string |  | The draft text. Setting it never dispatches events. |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `acknowledge()` | The host accepted a submission; clears the submitted draft unless it was edited since. |
+| `fail()` | The host rejected a submission; the draft is kept and the error shown. |
+| `submit()` | Request submission of the draft (same as pressing Send). Returns the submission id. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-prompt-submit` | CustomEvent<PromptSubmitDetail> | user (authored) | Request to send the draft. Acknowledge or fail it with the submission id. |
+| `odd-prompt-stop` | CustomEvent<{ readonly attemptId: string \| undefined; }> | user (authored) | Request to stop the underlying work of the identified attempt (not a disconnect). |
+| `odd-attachment-add` | CustomEvent<{ readonly attachments: readonly AttachmentState[]; }> | user (authored) | Attachments were validated and added to the draft (local; uploading is host-owned). |
+| `odd-attachment-remove` | CustomEvent<{ readonly attachmentId: string; }> | user (authored) | An attachment was removed from the draft (local). |
+| `odd-announce` | CustomEvent<AnnounceDetail> | notification (authored) | A status message for the nearest announcer, which cancels it so outer announcers stay silent. |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| `header` | Content above the input (suggestions, context). |
+| `toolbar-end` | Controls before the send button (voice input). |
+| `toolbar-start` | Controls before the attach button (model picker, commands). |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `attachments` | Attachment list. |
+| `form` | The native form. |
+| `input` | The native text area. |
+| `status` | Submission status and errors. |
+| `toolbar` | Toolbar row. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-prompt-input-max-height` | Maximum height before the text area scrolls. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: The input of a conversation or assistant. (src/prompt-input/prompt-input.ts:65)
+- Not for: Single-line form fields; use `odd-input`. (src/prompt-input/prompt-input.ts:66)
+- Accessibility: The text area is labelled (`label`) and described by the keyboard hint, validation issues, and submission status. Send and stop are native buttons; unavailable actions explain why. (src/prompt-input/prompt-input.ts:63)
+- Keyboard: Enter sends and Shift+Enter inserts a line break (or Ctrl/⌘+Enter sends with `enter-behavior="newline"`). Keys during IME composition never send. (src/prompt-input/prompt-input.ts:64)
+- Limitations: Mentions and slash commands are host integrations through the slots and the `input` part; the composer does not parse them. (src/prompt-input/prompt-input.ts:67)
+
+## Examples
+
+- `example:odd-prompt-input/default` in src/prompt-input/prompt-input.examples.ts (package source)
+- `example:odd-prompt-input/loading` in src/prompt-input/prompt-input.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-prompt-input/disabledFalse` produces `usage.boolean.false`; correct: `example:odd-prompt-input/default`
+- `example:odd-prompt-input/toolbarSlot` produces `usage.slot.unknown`; correct: `example:odd-prompt-input/default`
+
+## Customization
+
+- Levels: 1, 2 (authored)
+- Variables: `--odd-prompt-input-max-height`
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`
+
+## Verified
+
+- 67 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/ai/test/contract.browser.test.ts, 2026-10-28)

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

@@ -0,0 +1,78 @@
+# `<odd-question>` (OddkinQuestion)
+
+Package `@oddkin/ai` 1.0.0-beta.0 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A clarifying question from an assistant or agent: choices, a structured form, or free text,
+with an optional custom answer. Submitted, skipped, expired, and failed states come from the
+record; answers are bound to the question revision.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/question';`
+- Class: `import { OddkinQuestion } from '@oddkin/ai/question';`
+- Dependency (button): `<odd-button>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `question` | none: assign as a property | { revision: number; status: "requested" \| "expired" \| "failed" \| "submitted" \| "submitting" \| "skipped"; kind: "form" \| "text" \| "choice" \| "multi-choice"; questionId: string; prompt: string; ... 5 more ...; answer?: JsonValue \| undefined; } \| undefined | undefined | The question record. |
+| `announce` | `announce` | "none" \| "important" | 'none' | Announce new questions (when no surrounding surface does). |
+| `strings` | none: assign as a property | Partial<{ other: string; otherLabel: string; submit: string; skip: string; submitting: string; submitted: string; skipped: string; expired: string; failed: string; required: string; expires: string; yes: string; announceAsked: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-question-answer` | CustomEvent<{ readonly questionId: string; readonly revision: number; readonly answer: JsonValue; }> | user (authored) | Request to submit an answer for one question revision. |
+| `odd-question-skip` | CustomEvent<{ readonly questionId: string; readonly revision: number; }> | user (authored) | Request to skip a question. |
+| `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` | Answer and skip. |
+| `form` | The native form. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Asking the user for missing information before continuing. (src/question/question.ts:34)
+- Not for: General-purpose forms unrelated to an agent's request. (src/question/question.ts:35)
+- Accessibility: A native form with a fieldset and legend; required fields use native constraint validation. (src/question/question.ts:32)
+- Keyboard: Native form controls; Enter in a single-line field submits. (src/question/question.ts:33)
+
+## Examples
+
+- `example:odd-question/default` in src/question/question.examples.ts (package source)
+- `example:odd-question/form` in src/question/question.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`
+
+## Verified
+
+- 15 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/ai/test/contract.browser.test.ts, 2026-10-28)

package/agent/references/components/odd-response-feedback.md

@@ -0,0 +1,79 @@
+# `<odd-response-feedback>` (OddkinResponseFeedback)
+
+Package `@oddkin/ai` 1.0.0-beta.0 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Feedback on one response: a rating, optional reasons and comment, a pending state, and the
+confirmed outcome from the feedback record.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/response-feedback';`
+- Class: `import { OddkinResponseFeedback } from '@oddkin/ai/response-feedback';`
+- Dependency (button): `<odd-button>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `messageId` | `message-id` | string | '' | Message the feedback is about. |
+| `feedback` | none: assign as a property | { status: "failed" \| "idle" \| "pending" \| "submitted"; messageId: string; error?: { code: string; message: string; retryable?: boolean \| undefined; } \| undefined; rating?: "positive" \| "negative" \| undefined; reasons?: string[] \| undefined; comment?: string \| undefined; } \| undefined | undefined | The authoritative feedback record (status and outcome). |
+| `reasons` | none: assign as a property | string[] | [] | Reasons offered for negative feedback. |
+| `disabled` | `disabled` (reflects) | boolean | false | Feedback is unavailable. |
+| `announce` | `announce` | "none" \| "important" | 'none' | Announce outcomes (when no surrounding surface does). |
+| `strings` | none: assign as a property | Partial<{ label: string; positive: string; negative: string; reasons: string; comment: string; submit: string; cancel: string; pending: string; submitted: string; failed: string; retry: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-feedback-submit` | CustomEvent<FeedbackSubmitDetail> | user (authored) | Request to submit feedback; confirmed through the feedback record. |
+| `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 |
+| --- | --- |
+| `base` | The feedback surface. |
+| `form` | Reasons and comment. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Collecting user feedback on generated responses. (src/response-feedback/response-feedback.ts:31)
+- Not for: Surveys or general forms. (src/response-feedback/response-feedback.ts:32)
+- Accessibility: Ratings are toggle buttons (`aria-pressed`). The outcome text comes from the record, never from the local request. (src/response-feedback/response-feedback.ts:29)
+- Keyboard: Tab and Enter or Space; the form keeps focus order rating → reasons → comment → submit. (src/response-feedback/response-feedback.ts:30)
+
+## Examples
+
+- `example:odd-response-feedback/default` in src/response-feedback/response-feedback.examples.ts (package source)
+- `example:odd-response-feedback/negative` in src/response-feedback/response-feedback.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`
+
+## Verified
+
+- 24 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/ai/test/contract.browser.test.ts, 2026-10-28)

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

@@ -0,0 +1,94 @@
+# `<odd-response>` (OddkinResponse)
+
+Package `@oddkin/ai` 1.0.0-beta.0 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Streamed rich text (Oddkin Markdown) with partial-output, completion, interruption, and error
+states. The canonical source is `text`; rendering repairs incomplete syntax for display only,
+and copy always uses `text`. Untrusted content stays inert: no HTML parsing, URL allow-list,
+code rendered as text.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/response';`
+- Class: `import { OddkinResponse } from '@oddkin/ai/response';`
+- Dependency (citation): `<odd-citation>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `text` | none: assign as a property | string | '' | Canonical Markdown source (property only). |
+| `status` | `status` (reflects) | "cancelled" \| "failed" \| "streaming" \| "complete" \| "interrupted" | 'complete' | Lifecycle of the text. |
+| `error` | none: assign as a property | { code: string; message: string; retryable?: boolean \| undefined; } \| undefined | undefined | Error shown when `status` is failed. |
+| `sources` | none: assign as a property | { type: "source"; id: string; sourceId: string; url?: string \| undefined; title?: string \| undefined; kind?: "file" \| "web" \| "document" \| "other" \| undefined; excerpt?: string \| undefined; publisher?: string \| undefined; }[] | [] | Sources that `[^id]` citations resolve against. |
+| `markdown` | none: assign as a property | MarkdownOptions \| undefined | undefined | Renderer options: URL policy, sanitizer, highlighter, images. |
+| `copyable` | `copyable` | boolean | false | Show a copy action for the whole response. |
+| `strings` | none: assign as a property | Partial<{ streaming: string; interrupted: string; cancelled: string; failed: string; copy: string; copyCode: string; copied: string; copyFailed: string; image: string; }> \| undefined | undefined | Localized string overrides. |
+| `renderedSource` | none (read-only) | string |  | The canonical source currently rendered. |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `copy()` | Copy the canonical source (never the rendered DOM text). |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `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` | Copy action. |
+| `content` | The rendered Markdown. |
+| `status` | Status line (generating, interrupted, stopped, failed). |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-response-code-background` | Code block background. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Assistant output that may stream: answers, explanations, summaries. (src/response/response.ts:37)
+- Not for: User-authored text (render it literally) or trusted HTML. (src/response/response.ts:38)
+- Accessibility: Streaming text is not a live region (no per-token announcements); outcomes are announced by the surface's announcer. Committed blocks keep their DOM, so focus and selection inside them survive streaming. (src/response/response.ts:35)
+- Keyboard: Code blocks and wide tables are scrollable and focusable. (src/response/response.ts:36)
+- Limitations: Raw HTML renders as text unless `markdown.html` is `sanitize` with a host sanitizer. Images render as links unless `markdown.images` is `load`. (src/response/response.ts:39)
+
+## Examples
+
+- `example:odd-response/default` in src/response/response.examples.ts (package source)
+- `example:odd-response/failed` in src/response/response.examples.ts (package source)
+- `example:odd-response/streaming` in src/response/response.examples.ts (package source)
+
+## Customization
+
+- Levels: 1, 2 (authored)
+- Variables: `--odd-response-code-background`
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`
+
+## Verified
+
+- 21 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/ai/test/contract.browser.test.ts, 2026-10-28)

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

@@ -0,0 +1,80 @@
+# `<odd-sources>` (OddkinSources)
+
+Package `@oddkin/ai` 1.0.0-beta.0 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+The list of sources behind a response. Each entry is a navigation target for citations.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/sources';`
+- Class: `import { OddkinSources } from '@oddkin/ai/sources';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `sources` | none: assign as a property | { type: "source"; id: string; sourceId: string; url?: string \| undefined; title?: string \| undefined; kind?: "file" \| "web" \| "document" \| "other" \| undefined; excerpt?: string \| undefined; publisher?: string \| undefined; }[] | [] | Source records in citation order (replaced, never mutated). |
+| `label` | `label` | string | '' | Visible heading and accessible name of the list; defaults to the localized "Sources". |
+| `strings` | none: assign as a property | Partial<{ heading: string; count: string; open: string; untitled: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `reveal()` | Scroll to and focus the entry for `sourceId`. Returns false when it is not listed. |
+
+## Events
+
+None.
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The region labelled by the heading, around the list. |
+| `item` | One source. |
+| `list` | The ordered list of sources. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Showing the sources a response used, with titles, hosts, and excerpts. (src/sources/sources.ts:20)
+- Not for: Arbitrary link lists; use a list of links. (src/sources/sources.ts:21)
+- Accessibility: A labelled list; entries are numbered in citation order. `reveal()` scrolls to and focuses an entry (only on user request). (src/sources/sources.ts:19)
+
+## Examples
+
+- `example:odd-sources/default` in src/sources/sources.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-sources/sourcesAttribute` produces `usage.attribute.propertyOnly`; correct: `example:odd-sources/default`
+
+## 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`
+
+## Verified
+
+- 11 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/ai/test/contract.browser.test.ts, 2026-10-28)

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

@@ -0,0 +1,76 @@
+# `<odd-suggestions>` (OddkinSuggestions)
+
+Package `@oddkin/ai` 1.0.0-beta.0 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Suggested prompts. Activating a suggestion inserts it for editing; the separate send button
+submits it directly. The two intents are distinct events.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/suggestions';`
+- Class: `import { OddkinSuggestions } from '@oddkin/ai/suggestions';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `suggestions` | none: assign as a property | { label: string; id: string; prompt: string; }[] | [] | Suggestions (replace to update). |
+| `disabled` | `disabled` (reflects) | boolean | false | Disable both actions (e.g. while sending is unavailable). |
+| `insertOnly` | `insert-only` | boolean | false | Hide the direct send action. |
+| `strings` | none: assign as a property | Partial<{ label: string; send: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-suggestion-select` | CustomEvent<{ readonly suggestionId: string; readonly prompt: string; }> | user (authored) | Insert the suggestion into the composer without sending. |
+| `odd-suggestion-submit` | CustomEvent<{ readonly suggestionId: string; readonly prompt: string; }> | user (authored) | Send the suggestion as a prompt. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `list` | The suggestions. |
+| `send` | Send button. |
+| `suggestion` | Insert button. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Follow-up prompts and quick actions after a response. (src/suggestions/suggestions.ts:20)
+- Not for: Navigation menus. (src/suggestions/suggestions.ts:21)
+- Accessibility: A labelled list of button pairs; the send button's name includes the suggestion text. (src/suggestions/suggestions.ts:18)
+- Keyboard: Tab between buttons; Enter or Space activates. (src/suggestions/suggestions.ts:19)
+
+## Examples
+
+- `example:odd-suggestions/default` in src/suggestions/suggestions.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`
+
+## Verified
+
+- 20 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/ai/test/contract.browser.test.ts, 2026-10-28)

package/agent/references/components/odd-task-plan.md

@@ -0,0 +1,73 @@
+# `<odd-task-plan>` (OddkinTaskPlan)
+
+Package `@oddkin/ai` 1.0.0-beta.0 · category AI. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+An agent's plan: ordered steps, parallel tasks within a step, blockers, progress, and requests
+for input.
+
+## Import and register
+
+- Register: `import '@oddkin/ai/define/task-plan';`
+- Class: `import { OddkinTaskPlan } from '@oddkin/ai/task-plan';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `plan` | none: assign as a property | { planId: string; steps: { id: string; title: string; status: "failed" \| "done" \| "pending" \| "skipped" \| "active" \| "blocked" \| "needs-input"; detail?: string \| undefined; blocker?: string \| undefined; inputRequest?: string \| undefined; tasks?: { ...; }[] \| undefined; }[]; title?: string \| undefined; } \| undefined | undefined | The plan record (replace to update). |
+| `strings` | none: assign as a property | Partial<{ label: string; progress: string; parallel: string; blocked: string; needsInput: string; respond: string; pending: string; active: string; done: string; failed: string; 'needs-input': string; skipped: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-plan-input-request` | CustomEvent<{ readonly planId: string; readonly stepId: string; }> | user (authored) | The user wants to answer a step that needs input. |
+
+## Slots
+
+None.
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The section labelled by the plan's title. |
+| `progress` | The native progress bar and its text. |
+| `steps` | The ordered list of steps. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Showing multi-step agent work as it proceeds. (src/task-plan/task-plan.ts:40)
+- Not for: Static checklists the user edits. (src/task-plan/task-plan.ts:41)
+- Accessibility: An ordered list; each step's status is text (symbols are decorative). Progress is a labelled native `<progress>` with a text equivalent. (src/task-plan/task-plan.ts:38)
+- Keyboard: Tab reaches "Respond" buttons on steps that need input. (src/task-plan/task-plan.ts:39)
+
+## Examples
+
+- `example:odd-task-plan/default` in src/task-plan/task-plan.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`
+
+## Verified
+
+- 8 facts verified by `oddkin.cem-contract@1.0.0` in chromium 156.0.8078.4, firefox 157.0, webkit 27.2 (packages/ai/test/contract.browser.test.ts, 2026-10-28)