[docs] Added Quick start; flattened and consolidated guides

docs/concepts/actions.md

@@ -19,4 +19,4 @@ When you set `handler: "client"`, the action flows into the client SDK’s `widg
 Your client integration can also initiate actions directly with `chatkit.sendCustomAction(action, itemId?)`, optionally namespaced to a specific widget item. The server receives these in `ChatKitServer.action` just like a widget-triggered action and can stream widgets, messages, or client effects in response. This pattern is useful when a flow starts outside a widget—or after a client-handled action—but you still want the server to persist results or involve the model.
 
 ## Related guides
-- [Handle widget actions](../guides/add-features/handle-widget-actions.md)
+- [Build interactive responses with widgets](../guides/build-interactive-responses-with-widgets.md)

docs/concepts/entities.md

@@ -17,7 +17,7 @@ Entities can be used as cited sources in assistant responses.
 **References:**
 
 - The [EntitySource](../../api/chatkit/types/#chatkit.types.EntitySource) Pydantic model definition
-- [Add annotations in assistant messages](../guides/add-features/add-annotations.md#annotating-with-custom-entities).
+- [Add annotations in assistant messages](../guides/add-annotations.md#annotating-with-custom-entities).
 
 ## Entity tags as @-mentions in user messages
 
@@ -27,4 +27,4 @@ Users can tag your entities in the composer using @-mentions.
 
 - The [Entity](https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/entity/) TypeScript type definition
 - The [UserMessageTagContent](../../api/chatkit/types/#chatkit.types.UserMessageTagContent) Pydantic model definition
-- [Allow @-mentions in user messages](../guides/add-features/allow-mentions.md).
+- [Accept rich user input](../guides/accept-rich-user-input.md#-mentions-tag-entities-in-user-messages).

docs/concepts/thread-stream-events.md

@@ -29,18 +29,18 @@ Stream [`ErrorEvent`](../../api/chatkit/types/#chatkit.types.ErrorEvent)s for us
 
 Stream [`ProgressUpdateEvent`](../../api/chatkit/types/#chatkit.types.ProgressUpdateEvent)s to show the user transient status while work is in flight.
 
-See [Show progress for long-running tools](../guides/add-features/show-progress-for-long-running-tools.md) for more info.
+See [Show progress while tools run](../guides/update-client-during-response.md#show-progress-while-tools-run) for more info.
 
 ## Client effects
 
 Use [`ClientEffectEvent`](../../api/chatkit/types/#chatkit.types.ClientEffectEvent) to trigger fire-and-forget behavior on the client such as opening a dialog or pushing updates.
 
-See [Send client effects](../guides/add-features/send-client-effects.md) for more info.
+See [Trigger client-side effects without blocking](../guides/update-client-during-response.md#trigger-client-side-effects-without-blocking) for more info.
 
 ## Stream options
 
 [`StreamOptionsEvent`](../../api/chatkit/types/#chatkit.types.StreamOptionsEvent) configures runtime stream behavior (for example, allowing user cancellation). `ChatKitServer` emits one at the start of every stream using `get_stream_options`; override that method to change defaults such as `allow_cancel`.
 
 
 ## Related guides
-- [Stream responses back to your user](../guides/stream-thread-events.md)
+- [Respond to a user message](../guides/respond-to-user-message.md)

docs/concepts/threads.md

@@ -1,16 +1,123 @@
-# Threads
+# Threads and items
 
-Threads are the core unit of ChatKit: a single conversation timeline that groups messages, tool calls, widgets, and related metadata.
+In ChatKit, a **thread** represents a single conversation. It is the unit that ties together everything that happens in that conversation: messages, widgets, actions, system signals, and metadata. A thread is stored as an ordered history of **thread items**, which ChatKit loads, paginates, and renders as needed.
 
-## Lifecycle
-- When a user submits a message and no thread exists, `ChatKitServer` creates one by calling your store's [`save_thread`](../../api/chatkit/store/#chatkit.store.Store.save_thread).
-- As responses stream back, `ChatKitServer` automatically persists thread items as they are completed—see [Thread items](thread-items.md) and [Stream responses back to your user](../guides/stream-thread-events.md) for how events drive storage.
-- Update titles or metadata intentionally in your integration (e.g., after summarizing a topic) by calling [`store.save_thread`](../../api/chatkit/store/#chatkit.store.Store.save_thread) with the new values.
-- When history is enabled client-side, ChatKit retrieves past threads. The user can continue any previous thread by default.
-- Archive or close threads according to your policies: mark them read-only (e.g., [disable new messages](../guides/add-features/disable-new-messages.md)) or delete them if you no longer want them discoverable.
+## What is a thread?
 
+A thread is an ordered timeline that contains:
+
+- Conversation history (user and assistant messages)
+- Structured content such as widgets and workflows
+- Internal signals that guide processing or model behavior
+- Metadata like titles or status flags
+
+Threads are persisted by your store implementation and can be updated, continued, or made read-only according to your application’s needs.
+
+## What are thread items?
+
+Thread items are the individual records that make up a thread. Each item represents one meaningful unit in the conversation history, such as:
+
+- A user message
+- An assistant response
+- A widget rendered by the assistant
+- A non-visible signal used only for model input
+
+ChatKit maintains the order of items, streams new ones as they are produced, and paginates them when history is loaded.
+
+## How threads are created and updated
+
+A typical thread lifecycle looks like this:
+
+- **Thread creation**: When a user submits a message and no thread exists yet, ChatKitServer creates one and persists it by calling your store’s `save_thread`.
+- **Appending items**: As the server streams a response, ChatKit persists thread items automatically as each item completes. Streaming events directly drive what gets stored.
+- **Updating metadata**: During respond, you can freely mutate the thread object (for example, to set or refine the title). ChatKit automatically persists these updates when the response completes. You can also call store.save_thread explicitly if needed.
+- **Loading history**: When history is enabled client-side, ChatKit retrieves past threads and their items. Users can continue an existing thread by default.
+- **Closing or archiving**: Threads can be marked read-only (for example, by disabling new messages) or deleted entirely if they should no longer be discoverable.
+
+
+## How thread items are used
+
+Thread items serve two primary purposes in ChatKit:
+
+### Model input
+
+Your server's [`respond`](../../api/chatkit/server/#chatkit.server.ChatKitServer.respond) logic reads thread items to construct input for the model input. This ensures the model sees the full conversational context both during an active response and when a user resumes a past thread. 
+
+See [Respond to a user message](../guides/respond-to-user-message.md) for a full walkthrough.
+
+### UI rendering
+
+On the client, ChatKit.js renders items incrementally as they stream in for the active thread. When a past thread is loaded, the same persisted items are re-rendered to reconstruct the conversation UI.
+
+## Core item types
+
+### User messages
+
+[`UserMessageItem`](../../api/chatkit/types/#chatkit.types.UserMessageItem)s represent end-user input. They may include:
+
+- Plain text entered by the user
+- Optional `quoted_text` for reply-style UIs
+- Attachment metadata
+
+
+User text is not Markdown-rendered, but it may contain [@-mentions](../guides/accept-rich-user-input.md#-mentions-tag-entities-in-user-messages) if your integration enables them.
+
+
+### Assistant messages
+
+[`AssistantMessageItem`](../../api/chatkit/types/#chatkit.types.AssistantMessageItem)s represent assistant output. Their content can include:
+
+- Markdown-rendered text
+- Tool call outputs
+- Widgets and structured UI elements
+- [Inline annotations](../guides/add-annotations.md)
+
+Assistant text supports rich Markdown and is rendered progressively as it streams.
+
+#### Markdown support
+
+Assistant messages support:
+
+- GitHub-flavored Markdown (headings, lists, code blocks, links, blockquotes)
+- Stable list rendering during streaming (Safari-safe, no reflow)
+- Optional single-newline line breaks
+- Syntax-highlighted, copyable code blocks
+- LaTeX math (inline and block)
+- Tables with automatic sizing and horizontal scrolling
+- Inline annotations that create interactive affordances in the UI
+
+### Hidden context items
+
+Hidden context items are included in model input but are not rendered in the chat UI. They allow the model to react to what happened in the interface, not just what the user typed.
+
+Typical use cases include recording widget actions, selection state, or system signals.
+
+- **[`HiddenContextItem`](../../api/chatkit/types/#chatkit.types.HiddenContextItem)**: Integration-defined hidden context. You control its schema and how it is converted for the model.
+
+- **[`SDKHiddenContextItem`](../../api/chatkit/types/#chatkit.types.SDKHiddenContextItem)**: Hidden context inserted by the ChatKit Python SDK for its own internal operations. Most applications do not need to modify this unless overriding conversion behavior.
+
+## Thread item actions
+
+Thread item actions are quick action buttons associated with an assistant turn. They let users act on the output—such as retrying a response, copying content, or submitting feedback.
+
+Actions are configured client-side using the [threadItemActions option](https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/threaditemactionsoption/).
+
+## Converting items to model input
+
+[`ThreadItemConverter`](../../api/chatkit/agents/#chatkit.agents.ThreadItemConverter) translates stored thread items into model-ready input items. The default converter understands common ChatKit item types such as messages, widgets, workflows, and tasks.
+
+You can override the converter when you need custom behavior. For example:
+
+- Formatting attachments for the model
+- Translating tags or mentions into structured input
+- Summarizing rich widgets into text the model can consume
+
+Custom conversion is typically paired with prompting so the model receives a coherent representation of the conversation.
 
 ## Related guides
-- [Persist ChatKit threads and messages](../guides/persist-chatkit-data.md)
-- [Save thread titles](../guides/add-features/save-thread-titles.md)
-- [Disable new messages for a thread](../guides/add-features/disable-new-messages.md)
+- [Respond to a user message](../guides/respond-to-user-message.md)
+- [Pass extra app context to your model](../guides/pass-extra-app-context-to-your-model.md)
+- [Add annotations in assistant messages](../guides/add-annotations.md)
+- [Accept rich user input](../guides/accept-rich-user-input.md#-mentions-tag-entities-in-user-messages)
+- [Handle feedback](../guides/handle-feedback.md)
+- [Let users browse past threads](../guides/browse-past-threads.md)

docs/concepts/tools.md

@@ -0,0 +1,37 @@
+# Tools
+
+Tools let the assistant call into your application logic during a turn—for example to search data, run a workflow, or fetch the user’s current context—then feed the results back into the model.
+
+At a high level:
+
+- **Server tools** run on your backend. The assistant calls them through your inference pipeline, and you stream their results back into the conversation.
+- **Client tools** run in the browser or host app. ChatKit surfaces a tool call as a streamed thread item, lets the client handle it, then resumes the conversation with the tool’s output.
+
+## Server tools
+
+Server tools are ordinary Python functions you register with your inference setup (for example, as tools on an agent or as explicit steps in your pipeline). During inference, the model can decide to call them; ChatKit serializes the call, runs your function, and feeds the output back to the model.
+
+Use server tools to:
+
+- Look up data in your own APIs or databases.
+- Kick off long-running jobs while streaming progress updates.
+- Update your own domain state (tickets, orders, files, etc.) in response to a turn.
+
+From the model’s perspective, tools are structured, named capabilities it can invoke instead of guessing from free text.
+
+## Client tools
+
+Some operations can only run on the client—for example:
+
+- Reading the current selection in a canvas or document.
+- Inspecting local application state that never leaves the browser.
+- Calling into the host app (for example, a design tool or IDE) via its own APIs.
+
+Client tools let the model request that kind of data mid-turn:
+
+- On the server, you instruct your inference pipeline to stop when a specific tool is called (for example, by using `StopAtTools` around that tool).
+- ChatKit turns the tool call into a streamed thread item.
+- On the client, `onClientTool` receives that item, runs your callback, and returns a JSON result.
+- ChatKit sends the result back to the server, which starts a new stream to continue the run with the tool output included as model input.
+
+Use client tools when the model needs fresh, local context it cannot safely obtain from server-side state alone.

docs/concepts/widgets.md

@@ -31,11 +31,11 @@ Every widget must be wrapped in a root-level container element. For single, self
 
 ## .widget files
 
-Exported `.widget` files are JSON blobs that include the widget template, the expected data schema, and supporting metadata. You can load them server-side and render widgets dynamically with `WidgetTemplate`; see [Build widgets with `WidgetTemplate`](../guides/add-features/stream-widgets.md#build-widgets-with-widgettemplate) for examples.
+Exported `.widget` files are JSON blobs that include the widget template, the expected data schema, and supporting metadata. You can load them server-side and render widgets dynamically with `WidgetTemplate`; see [Build widgets with `WidgetTemplate`](../guides/build-interactive-responses-with-widgets.md#build-widgets-with-widgettemplate) for examples.
 
 ## WidgetItem
 
-[`WidgetItem`](../../api/chatkit/types/#chatkit.types.WidgetItem) represents a widget rendered as a [thread item](thread-items.md) in the chat UI. In addition to a reference to the widget instance, it contains a `copy_text` field that represents the text value copied to the clipboard when the user clicks the copy button below the response.
+[`WidgetItem`](../../api/chatkit/types/#chatkit.types.WidgetItem) represents a widget rendered as a [thread item](threads.md#what-are-thread-items) in the chat UI. In addition to a reference to the widget instance, it contains a `copy_text` field that represents the text value copied to the clipboard when the user clicks the copy button below the response.
 
 ## Entity previews
 
@@ -51,6 +51,4 @@ The [`entities.onRequestPreview`](https://openai.github.io/chatkit-js/api/openai
 
 ## Related guides
 
-- [Stream widgets](../guides/add-features/stream-widgets.md)
-- [Create custom forms](../guides/add-features/create-custom-forms.md)
-- [Handle widget actions](../guides/add-features/handle-widget-actions.md)
+- [Build interactive responses with widgets](../guides/build-interactive-responses-with-widgets.md)