Update

2026-10-12 00:53:52 +02:00
parent afc88b8087
commit 3038c5724b
116 changed files with 5475 additions and 25 deletions
@@ -322,7 +322,7 @@ File changes render as a unified diff right inside the call box: line numbers, g

 ## TUI framework

-The interactive UI toolkit lives in `tai.py` itself (stdlib-only, no dependencies): a retained, DOM-like panel tree with rows/cols flow, percent/`fr`/`auto` sizing, docking, named z-layers, a cuts/chops occlusion compositor, SGR mouse, bubbling events, Tab/Shift+Tab focus with modal trap, tick animations, and live pty sub-terminals behind a reimplemented VT screen. `/demo` (or `./tai.py --demo`) tours every widget; `./tai.py --demo-shot` prints one composed frame as plain text. Full reference: [tui.md](tui.md); design background: [research/tui-framework-design/conclusions/retained-dom-compositor-tui.md](research/tui-framework-design/conclusions/retained-dom-compositor-tui.md).
+The interactive UI toolkit lives in `tai.py` itself (stdlib-only, no dependencies): a retained, DOM-like panel tree with rows/cols flow, percent/`fr`/`auto` sizing, docking, named z-layers, a cuts/chops occlusion compositor, SGR mouse, bubbling events, Tab/Shift+Tab focus with modal trap, tick animations, and live pty sub-terminals behind a reimplemented VT screen. `/demo` (or `./tai.py --demo`) tours every widget; `./tai.py --demo-shot` prints one composed demo frame as plain text. `./tai.py --tui` runs the fullscreen Telegram-style chat UI (bots sidebar, transcript, input, status bar) with REPL parity; `./tai.py --theme NAME` picks a theme (`dark`, `light`, `nord`, `gruvbox`, `ansi`, or `TAI_THEME`). Full reference: [tui.md](tui.md); design background: [research/tui-framework-design/conclusions/retained-dom-compositor-tui.md](research/tui-framework-design/conclusions/retained-dom-compositor-tui.md), [chat layout](research/tui-framework-design/conclusions/messaging-layout-chat-scene.md), [theming](research/tui-framework-design/conclusions/palette-role-theming.md).

 ## Configuration

@@ -6,11 +6,11 @@

 | Metric | Value |
 |---|---|
-| Subjects | 6 |
-| Total source documents | 421 |
-| — Tier 1 (Source Dossier, independently analyzed) | 111 |
-| — Tier 2 (Source Citation Card, listed only) | 310 |
-| Total conclusion documents | 8 |
+| Subjects | 7 |
+| Total source documents | 526 |
+| — Tier 1 (Source Dossier, independently analyzed) | 153 |
+| — Tier 2 (Source Citation Card, listed only) | 373 |
+| Total conclusion documents | 14 |
 | Archive opened | 2026-10-09 |
 | Last updated | 2026-10-11 |

@@ -22,8 +22,9 @@
 | [`agent-memory-recency-tracking`](agent-memory-recency-tracking/) | 63 (16 / 47) | 1 | 2026-10-09 | 2026-10-09 | Designing an LRU-style last-used/use-count tracker for vault records and chunks |
 | [`async-pty-process-testing`](async-pty-process-testing/) | 59 (20 / 39) | 1 | 2026-10-09 | 2026-10-09 | Designing tai_test.py (pty vs. pipes, non-blocking stdin, process-group cleanup, test-framework shape) — backfilled after it was initially skipped, see activity log |
 | [`shell-multiplexer-auto-attach`](shell-multiplexer-auto-attach/) | 138 (48 / 90) | 2 | 2026-10-09 | 2026-10-10 | Designing a tai-managed terminal multiplexer + bashrc auto-attach: tmux-as-substrate recommendation, interactive-vs-automation shell detection; extended 2026-10-10 to cover zsh/fish hook syntax |
-| [`tui-framework-design`](tui-framework-design/) | 55 (10 / 45) | 1 | 2026-10-10 | 2026-10-10 | Designing tai's in-house TUI framework (retained DOM, cuts/chops compositor, SGR mouse, bubbling events, VT sub-terminals); extended 2026-10-10 with synchronized-output verification (DEC 2026); implemented in working-tree tai.py and verified the same session; same-day follow-up fixed the 19 failures natively, deleted tai_pkg/, suite 320/320 green, committed; extended again for kitty keyboard protocol (double-Shift prompt dialog) |
+| [`tui-framework-design`](tui-framework-design/) | 94 (49 / 45) | 5 | 2026-10-10 | 2026-10-11 | Designing tai's in-house TUI framework (retained DOM, cuts/chops compositor, SGR mouse, bubbling events, VT sub-terminals); extended 2026-10-10 with synchronized-output verification (DEC 2026); implemented in working-tree tai.py and verified the same session; same-day follow-up fixed the 19 failures natively, deleted tai_pkg/, suite 320/320 green, committed; extended again for kitty keyboard protocol (double-Shift prompt dialog); extended 2026-10-11 with messaging-layout comparison (telecli, send-rs, za-tui, bubbletea examples) and palette-role theming survey (Textual, lipgloss, bubbletint, ratatui-themes, ratatui-kit, pytermgui) plus 2 conclusions, nothing built yet; extended again 2026-10-11 with Telegram look-and-feel survey (tdesktop day/night themes, lang strings, Android dialog/message cells, FAQ, blog, Bot API/features, WebApps ThemeParams, mini-apps SDK docs, iOS teardown — 16 Tier 1) plus 2 conclusions, nothing built yet |
 | [`agentic-tool-loop-design`](agentic-tool-loop-design/) | 74 (7 / 67) | 2 | 2026-10-11 | 2026-10-11 | Fixing stop-after-narration on prompt-JSON CLI backends without intent regexes; decided structural loop control plus exactly-once JSON-contract repair plus prompt contract, implemented in tai.py the same session (suite 357/357 + 16/16 green); approval tiers judged already industry-standard, no change |
+| [`muse-responses-openai-transpiler`](muse-responses-openai-transpiler/) | 66 (3 / 63) | 2 | 2026-10-11 | 2026-10-11 | Documenting Meta muse Responses wire format vs classic Chat Completions; decided bidirectional transpile is feasible with a fixed loss table and system guidance has three channels; scratch transpiler tested, nothing merged |

 ## Recent activity log

@@ -42,6 +43,9 @@
 | 2026-10-10 | `tui-framework-design` | Follow-up (no new sources): the 19 failures from the previous row were fixed natively — five classes (`Consts`, `Install`, `Sandbox`, `Opencode`, `SysInfo`) defined directly in standalone `tai.py` with module functions delegating, four test patch-targets corrected to the real `tai.*` seams (assertions unchanged) — then `tai_pkg/` deleted outright per retoor's call. Suite now 320/320 green (`test_tai.py`) + 16/16 (`test_seal.py`); `tui.md` focus rules updated (Tab always cycles, auto-focus, focus memory); committed. Conclusion document forward-corrected. |
 | 2026-10-10 | `tui-framework-design` | Extended with 1 more source (Tier 1: the kitty keyboard protocol specification, direct fetch) to settle double-Shift detection for a prompt dialog: bare modifier presses need flag 8, press is `57441;2u`, filter `:2`/`:3` via flag 2, push `CSI > 10 u` best-effort with no query round-trip, pop on teardown. Subject total now 55 sources (10 Tier 1 / 45 Tier 2), 1 conclusion. |
 | 2026-10-11 | `agentic-tool-loop-design` | New subject: 74 sources (7 Tier 1 / 67 Tier 2) + 2 conclusions, covering 7 searches plus 7 direct fetches on agentic loop control (Anthropic stop_reason docs, Building Effective Agents, Agent SDK loop, Writing Tools for Agents, ReAct pattern, tool-calling playbook, small-model narration field report). Decisions: keep loop control structural (tool_calls presence is the stop_reason equivalent, never text parsing), repair a missing JSON envelope exactly once per CLI-backend call, harden the prompt contract, leave approval tiers unchanged. Backed a same-session implementation (tai.py `opencode_find_answer`/`cli_json_repair_prompt`/`cli_json_turn`, prompt-contract sentences, 7 new tests) with suite 357/357 + 16/16 green. Counts verified directly against the written files. |
+| 2026-10-11 | `tui-framework-design` | Extended with 23 more sources (all Tier 1, no Tier 2 — every consulted source body was opened via web_fetch by the researching agent) + 2 conclusions (`conclusions/messaging-layout-chat-scene.md`, `conclusions/palette-role-theming.md`): 14 dossiers comparing 4 messaging-client implementations (telecli tui.rs; send-rs tui mod/state/config/status/chat-widget; za-tui tcss/main-screen/status/input/chat-view; bubbletea chat + glamour examples; ai-nexus ratatui guidance doc) and 9 dossiers surveying theme systems (Textual theme.py, design guide, constants.py; lipgloss pkg docs; bubbletint, ratatui-themes, ratatui-kit; pytermgui styling + file_loaders). Decisions: 30/70 chat scene with growing input + 1-line status, manual sidebar toggle first with sub-80 auto-hide deferred, modal keys, left-aligned grouped rows, markdown width-minus-chrome, pin-to-bottom streaming; 12-role palette with THEMES dict registry, --theme flag > TAI_THEME > default, set_theme + F4 cycle, resolve-at-draw with raw-color escape hatch, file overrides deferred. A same-session internal tai.py inventory (no chat-transcript widget, no theme object, hardcoded inline styles) informed both conclusions but produced no source documents (internal code, not external research). Nothing built yet — both conclusions are specified-not-shipped. Carried gaps: no shipped client implements auto breakpoints (80-col rule is guidance-doc only); no streaming/tool-call rendering observed (inferred); fixed-cell sidebars appear only in guidance docs; ratatui core styling, pytermgui NO_COLOR, Textual get_css_variables, and lipgloss v2 LightDark unverified (snippet or inference only). Subject total now 78 sources (33 Tier 1 / 45 Tier 2), 3 conclusions. Counts verified directly against the written files (per-subject grep; global grep also matches README.md's own template rows, excluded). |
+| 2026-10-11 | `tui-framework-design` | Extended with 16 more sources (all Tier 1, no Tier 2 — every consulted source body was fetched by the researching agents) + 2 conclusions (`conclusions/telegram-chat-grammar-adoption.md`, `conclusions/telegram-theme-roles-mapping.md`): 10 dossiers on Telegram chat look-and-feel (tdesktop day/night theme files, lang.strings copy sheet, Android DialogCell/ChatMessageCell, FAQ check semantics, chat-themes blog, third-party checkmarks explainer, Bot API keyboards/commands, bot features onboarding) and 6 on Mini App theming (official WebApps ThemeParams/events/design rules; SDK docs for main/back, settings, viewport, theming; third-party iOS teardown). Decisions: adopt Telegram's metadata grammar as rows (clock/checks/blue-checks/eye, no delivered state), 8-hue peer palette, service/date pills, literal status/composer/bot copy, and reply-vs-inline keyboard grammar, rejecting bubbles, gradient themes, and pixel geometry; map the 15 ThemeParams keys onto tai's 12 roles with Desktop-file plus dark-sample defaults and a never-hardcode/re-read-on-switch discipline. A same-session internal tai.py inventory (chat scene present but plain: no ticks/dividers/header/rich rows/composer buttons; 6 of 12 roles used, hardcoded borders) informed both conclusions with per-item patch targets but produced no source documents (internal code, not external research). Nothing built yet — both conclusions are specified-not-shipped. Carried gaps: iOS/Web hexes unverified (Desktop day/night only); bubble radii/paddings/spacing/tail geometry, header icon inventory, chat-list time/date formatting and truncation, send-vs-voice swap and media-bubble time overlay unknown; no official typography/spacing spec (teardown values only); light defaults for section_*/subtitle/destructive unpublished; WebViewColors diagram uninspected; back-button SDK page yielded no captured evidence. Subject total now 94 sources (49 Tier 1 / 45 Tier 2), 5 conclusions. Counts verified directly against the written files via `research/audit.py` (PASS). |
+| 2026-10-11 | `muse-responses-openai-transpiler` | New subject: 66 sources (3 Tier 1 / 63 Tier 2) + 2 conclusions, covering the Meta muse Responses wire format vs classic Chat Completions (official migration guide, Responses reference, Chat reference fetched and synthesized; 63 search listings logged as seen-not-analyzed). Decisions: bidirectional transpile is feasible with a fixed warn-on-drop loss table, and system guidance has three channels (instructions preferred, developer/system Items otherwise). Backed by a scratch stdlib transpiler (`/tmp/openai_transpile.py`, self-test green, real-capture round trip verified); nothing merged into tai.py. Counts verified directly against the written files via `research/audit.py` (PASS). |

 ## How to use this index

@@ -0,0 +1,28 @@
+# OpenAI Responses API vs Chat Completions: Migrate and Test
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | OpenAI Responses API vs Chat Completions: Migrate and Test |
+| Source URL | https://benchlm.ai/blog/posts/chat-completions-to-responses-api |
+| Source type | blog post |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI official OpenAPI specification` search on 2026-10-11. Third-party comparison citing the official references; not opened.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,51 @@
+# Conclusion: Chat Completions and Responses transpile both ways with a fixed loss table
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Conclusion |
+| Tier | N/A |
+| Date decided | 2026-10-11 |
+| Decided by | retoor, advised by tai (agent, Muse Spark) |
+| Status | Active |
+| Confidence | High |
+
+## Question / problem statement
+
+Can classic Chat Completions traffic convert to the Responses wire format Meta's `muse` client speaks, and can Responses traffic convert back, well enough to build a protocol transpiler?
+
+## Conclusion
+
+Yes, both directions transpile, and the conversion is exact for plain text, multimodal text/image messages, function tools and calls, structured outputs, and the common streaming events. Everything outside that core has a fixed, warn-on-drop loss table; nothing is dropped silently.
+
+## Supporting sources
+
+- [OpenAI migration guide](../openai-migrate-to-responses.md): the message-to-Item, instructions, tool re-tagging, `text.format`, single-generation, and typed-event mappings.
+- [Responses API reference](../openai-responses-api-reference.md): exact create params, input/output Item shapes, `call_id` correlation, and SSE vocabulary.
+- [Chat Completions reference](../openai-chat-completions-api-reference.md): the classic messages/tools/chunks shapes and the Chat-only field list.
+- Local capture `/tmp/mitm_probe/request.txt` (internal evidence, not an external source): proves Meta's client sends `instructions`, `developer`-role input, one `namespace` tool, `store: false`, `reasoning.effort`, `include: ["reasoning.encrypted_content"]`, and `prompt_cache_key`.
+
+## Alternatives considered and rejected
+
+- One-way transpiler (Chat to Responses only): rejected, the user explicitly asked for both directions and the reverse mapping is equally mechanical.
+- Lossless transpiler with no warnings: rejected, provably impossible (`n` choices, `stop`, sampling penalties, reasoning items, `previous_response_id`, namespaces, and native tools have no counterpart).
+- Vendoring the official OpenAPI spec for schema validation: deferred, the reference pages settled every shape the transpiler needs; vendoring stays an option if drift is ever suspected.
+
+## Risks / open questions
+
+- Meta response bytes were never observed (the probe stub answered HTTP 500 to all 11 requests), so the response-object and SSE mappings rest on the OpenAI standard shapes the Meta client demonstrably shares on the request side. A recording forward proxy would close this gap.
+- Audio and file content parts are warn-and-drop in both directions because their exact cross-API shapes were not verified.
+- Model-gated behavior (Responses-required tool calling on newer models) can make a faithful transpile fail at runtime on one side; the transpiler maps protocol, not model capability.
+
+## Action taken
+
+Reference implementation exercised as scratch script `/tmp/openai_transpile.py` (stdlib only): `chat_to_responses`, `responses_to_chat`, both object converters, both streaming translators, self-test green, plus a real-capture round trip (Meta request to Chat and back, namespace/include losses warned). Nothing merged into `tai.py` yet.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial conclusion recorded. |
@@ -0,0 +1,50 @@
+# Conclusion: System guidance has three channels, and Meta's client uses two of them
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Conclusion |
+| Tier | N/A |
+| Date decided | 2026-10-11 |
+| Decided by | retoor, advised by tai (agent, Muse Spark) |
+| Status | Active |
+| Confidence | High |
+
+## Question / problem statement
+
+Is a system message possible on the Responses wire format, and which channel should a transpiler use for Chat `system` / `developer` messages?
+
+## Conclusion
+
+Yes. System guidance travels on three channels: top-level `instructions` (preferred), `developer`-role input messages, and `system`-role input messages. Meta's client uses the first two together: a large `instructions` string plus a `developer`-role input message. A transpiler folds leading Chat system/developer messages into `instructions` and preserves non-leading ones as role-kept message Items; the reverse emits `instructions` as the first Chat `system` message.
+
+## Supporting sources
+
+- [OpenAI migration guide](../openai-migrate-to-responses.md): guidance maps to "Top-level `instructions`, or compatible message Items when you need to preserve an existing transcript"; `previous_response_id` does not carry `instructions` forward.
+- [Responses API reference](../openai-responses-api-reference.md): `instructions` is "A system (or developer) message"; input roles include both `system` and `developer`.
+- [Chat Completions reference](../openai-chat-completions-api-reference.md): on o1-and-newer models `developer` replaces `system`, which explains the role split across clients.
+- Local capture `/tmp/mitm_probe/request.txt` (internal evidence): requests carry 25-44KB `instructions` strings and, in the main shape, a 31KB `developer`-role input message next to the user message.
+
+## Alternatives considered and rejected
+
+- Always emitting system guidance as `system`-role Items instead of `instructions`: rejected, the first-party client and the migration guide both prefer top-level `instructions`.
+- Merging all guidance into one string regardless of position: rejected, it scrambles multi-turn transcripts where guidance appears mid-conversation; only leading guidance folds.
+- Treating `developer` as Meta-specific: rejected, it is standard Responses vocabulary and standard Chat vocabulary on newer models.
+
+## Risks / open questions
+
+- Instruction precedence between `instructions` and same-turn developer/system Items is documented only as hierarchy ("developer or system take precedence over user"), not as ordering between the two guidance channels; observed client behavior (both at once) suggests they compose.
+- Whether Meta's server honors a bare `system`-role Item identically to `developer` was not tested live; the reference allows both roles.
+
+## Action taken
+
+Documented here and implemented in the scratch transpiler (`/tmp/openai_transpile.py`); verified against the real capture (25KB instructions plus 31KB developer message survive the round trip as guidance). Nothing merged into `tai.py` yet.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial conclusion recorded. |
@@ -0,0 +1,28 @@
+# Assistants migration guide
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Assistants migration guide |
+| Source URL | https://developers.openai.com/api/docs/assistants/migration.md |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com reference Create response` search on 2026-10-11. Assistants-to-Responses migration; tangential to Chat interop.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Changelog | OpenAI API
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Changelog | OpenAI API |
+| Source URL | https://developers.openai.com/api/docs/changelog |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com Migrate to Responses` search on 2026-10-11. Changelog noting Responses-required tool calling on newer models; not opened.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Compaction
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Compaction |
+| Source URL | https://developers.openai.com/api/docs/guides/compaction.md |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com reference Create response` search on 2026-10-11. Compaction guide replaying output items with store:false; not opened.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Error codes
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Error codes |
+| Source URL | https://developers.openai.com/api/docs/guides/error-codes.md |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com reference Create response` search on 2026-10-11. Error-code guide with a Responses snippet; not opened.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Completions
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Completions |
+| Source URL | https://developers.openai.com/api/reference/go/resources/chat/subresources/completions/index.md |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com Migrate to Responses` search on 2026-10-11. Go chat reference entry; not opened because the language-neutral reference was used instead.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Using GPT-5.4
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Using GPT-5.4 |
+| Source URL | https://developers.openai.com/api/docs/guides/latest-model/gpt-5-4.md |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com Migrate to Responses` search on 2026-10-11. Model guide noting chain-of-thought-between-turns as the migration reason; not opened.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Image generation
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Image generation |
+| Source URL | https://developers.openai.com/api/docs/guides/image-generation.md |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com reference Create response` search on 2026-10-11. Image guide with a Responses image_generation tool; not opened.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Create a model response
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Create a model response |
+| Source URL | https://developers.openai.com/api/reference/java/resources/responses/methods/create/index.md |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com reference Create response` search on 2026-10-11. Java create-response entry confirming POST /responses; not opened.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Chat Completions
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Chat Completions |
+| Source URL | https://developers.openai.com/api/reference/python/resources/chat/index.md |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com Migrate to Responses` search on 2026-10-11. Python chat reference entry; not opened because the language-neutral reference was used instead.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Client Secrets
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Client Secrets |
+| Source URL | https://developers.openai.com/api/reference/python/resources/realtime/subresources/client_secrets/index.md |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com reference Create response` search on 2026-10-11. Realtime secrets; off-topic.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Client Secrets | OpenAI API Reference
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Client Secrets | OpenAI API Reference |
+| Source URL | https://developers.openai.com/api/reference/resources/realtime/subresources/client_secrets/ |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com reference Create response` search on 2026-10-11. Realtime secrets reference; off-topic.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Create eval
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Create eval |
+| Source URL | https://developers.openai.com/api/reference/ruby/resources/evals/methods/create/index.md |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com reference Create response` search on 2026-10-11. Evals API; off-topic.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Create eval run
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Create eval run |
+| Source URL | https://developers.openai.com/api/reference/ruby/resources/evals/subresources/runs/methods/create/index.md |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com reference Create response` search on 2026-10-11. Evals API; off-topic.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Shell
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Shell |
+| Source URL | https://developers.openai.com/api/docs/guides/tools-shell.md |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com Migrate to Responses` search on 2026-10-11. Shell tool guide, Responses-only; not opened.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Text generation | OpenAI API
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Text generation | OpenAI API |
+| Source URL | https://developers.openai.com/api/docs/guides/text |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com Migrate to Responses` search on 2026-10-11. Official text guide recommending Responses with instructions and roles; not opened.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Text generation
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Text generation |
+| Source URL | https://developers.openai.com/api/docs/guides/text.md |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com Migrate to Responses` search on 2026-10-11. Markdown variant of the text guide; not opened.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Chat Completions
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Chat Completions |
+| Source URL | https://developers.openai.com/api/reference/typescript/resources/chat/index.md |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com Migrate to Responses` search on 2026-10-11. TypeScript chat reference entry; not opened because the language-neutral reference was used instead.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Create client secret
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Create client secret |
+| Source URL | https://developers.openai.com/api/reference/typescript/resources/realtime/subresources/client_secrets/methods/create/index.md |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com reference Create response` search on 2026-10-11. Realtime secrets; off-topic.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Web search | OpenAI API
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Web search | OpenAI API |
+| Source URL | https://developers.openai.com/api/docs/guides/tools-web-search |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:developers.openai.com Migrate to Responses` search on 2026-10-11. Web-search tool guide with a Chat-versus-Responses path note; not opened.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# agenvoy/skill-extract-official-guide - offical_guide/gpt-6.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | agenvoy/skill-extract-official-guide - offical_guide/gpt-6.md |
+| Source URL | https://github.com/agenvoy/skill-extract-official-guide/blob/HEAD/offical_guide/gpt-6.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `migrate Chat Completions to Responses` search on 2026-10-11. Model guide notes on reasoning-effort params and Responses-required tool calling; version-sensitive and unverified.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# anahata-os/anahata-asi - anahata-asi-openai/src/test/java/migrate-to-responses.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | anahata-os/anahata-asi - anahata-asi-openai/src/test/java/migrate-to-responses.md |
+| Source URL | https://github.com/anahata-os/anahata-asi/blob/HEAD/anahata-asi-openai/src/test/java/migrate-to-responses.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `migrate Chat Completions to Responses` search on 2026-10-11. Vendored migration notes on the endpoint swap plus previous_response_id and Conversations.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Different Return Types Depending on the Request Made to the /chat/completions Endpoint in the OpenAI OpenAPI
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Different Return Types Depending on the Request Made to the /chat/completions Endpoint in the OpenAI OpenAPI |
+| Source URL | https://github.com/apple/swift-openapi-generator/issues/614 |
+| Source type | forum thread |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI official OpenAPI specification` search on 2026-10-11. Old issue on stream versus non-stream return types in the spec.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# benshapyro/devkit - skills/ai-automation/openai-responses-api/SKILL.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | benshapyro/devkit - skills/ai-automation/openai-responses-api/SKILL.md |
+| Source URL | https://github.com/benshapyro/devkit/blob/HEAD/skills/ai-automation/openai-responses-api/SKILL.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `migrate Chat Completions to Responses` search on 2026-10-11. Skill with a migrate checklist: system-to-instructions, messages-to-input, max_tokens mapping, previous_response_id versus conversation.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# byterefinery/skills - .agents/skills-python/openai-python-3-19-2/SKILL.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | byterefinery/skills - .agents/skills-python/openai-python-3-19-2/SKILL.md |
+| Source URL | https://github.com/byterefinery/skills/blob/HEAD/.agents/skills-python/openai-python-3-19-2/SKILL.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI official OpenAPI specification` search on 2026-10-11. SDK skill with Responses-primary and Chat previous-standard examples including the developer role.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# clavia-labs/tanstack-ai - docs/adapters/openai.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | clavia-labs/tanstack-ai - docs/adapters/openai.md |
+| Source URL | https://github.com/clavia-labs/tanstack-ai/blob/HEAD/docs/adapters/openai.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Chat Completions API reference` search on 2026-10-11. Adapter docs for chat completions streaming.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# cpiprint/bodhiapp - docs/guides/openai-api.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | cpiprint/bodhiapp - docs/guides/openai-api.md |
+| Source URL | https://github.com/cpiprint/bodhiapp/blob/HEAD/docs/guides/openai-api.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Chat Completions API reference` search on 2026-10-11. Local-server guide for chat completions with a system-role example.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# cyli00/otterpad - test/openai-image-generation.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | cyli00/otterpad - test/openai-image-generation.md |
+| Source URL | https://github.com/cyli00/otterpad/blob/HEAD/test/openai-image-generation.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Responses API reference` search on 2026-10-11. Image generation through the Responses image tool with streaming.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# eglove/ethang-agent - feat(openrouter): switch to the Responses API; eleven server tools; error bodies surfaced
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | eglove/ethang-agent - feat(openrouter): switch to the Responses API; eleven server tools; error bodies surfaced |
+| Source URL | https://github.com/eglove/ethang-agent/commit/c2567f22543965cc32d2ebfea8db0f933b2be7ed |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Responses API reference` search on 2026-10-11. Commit migrating a wire layer to /responses with typed SSE; corroborates stream-shape claims at snippet level only.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# enkrateialucca/oreilly_live_training_llm_apps - research/responses-api-2026.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | enkrateialucca/oreilly_live_training_llm_apps - research/responses-api-2026.md |
+| Source URL | https://github.com/enkrateialucca/oreilly_live_training_llm_apps/blob/HEAD/research/responses-api-2026.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `migrate Chat Completions to Responses` search on 2026-10-11. Training research confirming instructions as the system-role equivalent, citing the official guide.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# fairmehit/bifrost-lite - tests/e2e/api/HARNESS_COVERAGE_BACKLOG.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | fairmehit/bifrost-lite - tests/e2e/api/HARNESS_COVERAGE_BACKLOG.md |
+| Source URL | https://github.com/fairmehit/bifrost-lite/blob/HEAD/tests/e2e/api/HARNESS_COVERAGE_BACKLOG.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Chat Completions API reference` search on 2026-10-11. E2E coverage list naming system messages, streaming, vision, function calling, forced tool choice, json_schema, and reasoning effort.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# fesshompa/promptfoo - site/docs/providers/openai.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | fesshompa/promptfoo - site/docs/providers/openai.md |
+| Source URL | https://github.com/fesshompa/promptfoo/blob/HEAD/site/docs/providers/openai.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `migrate Chat Completions to Responses` search on 2026-10-11. Provider docs recommending Responses for new evals, citing the official guide.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# ggboykxz/apex - docs/reference/api.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | ggboykxz/apex - docs/reference/api.md |
+| Source URL | https://github.com/ggboykxz/apex/blob/HEAD/docs/reference/api.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Chat Completions API reference` search on 2026-10-11. Third-party API doc mirroring the chat completions shape with a system message.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# guedesdiogo/kelpie - docs/research/07-llm-providers-and-auth.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | guedesdiogo/kelpie - docs/research/07-llm-providers-and-auth.md |
+| Source URL | https://github.com/guedesdiogo/kelpie/blob/HEAD/docs/research/07-llm-providers-and-auth.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `migrate Chat Completions to Responses` search on 2026-10-11. Provider research citing the Responses recommendation plus store:false encrypted reasoning.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# hassanhashmi16/ai-ml-course - Phase 1(AI)/STEP 15/Step15-Anthropic-OpenAI-SDK.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | hassanhashmi16/ai-ml-course - Phase 1(AI)/STEP 15/Step15-Anthropic-OpenAI-SDK.md |
+| Source URL | https://github.com/hassanhashmi16/ai-ml-course/blob/HEAD/Phase%201(AI)/STEP%2015/Step15-Anthropic-OpenAI-SDK.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Chat Completions API reference` search on 2026-10-11. Course notes with a system/user/assistant messages example.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# ibobbyts/codex-rosetta - docs/dev/sdk_ir/openapi_specs_and_open_responses.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | ibobbyts/codex-rosetta - docs/dev/sdk_ir/openapi_specs_and_open_responses.md |
+| Source URL | https://github.com/ibobbyts/codex-rosetta/blob/HEAD/docs/dev/sdk_ir/openapi_specs_and_open_responses.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI official OpenAPI specification` search on 2026-10-11. Notes on the official openai-openapi repo, branch, and raw URL covering both endpoints.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# immutex/mcode - docs/15-model-layer.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | immutex/mcode - docs/15-model-layer.md |
+| Source URL | https://github.com/immutex/mcode/blob/HEAD/docs/15-model-layer.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Responses API reference` search on 2026-10-11. Provider-matrix doc noting Responses as the primary surface with input items, instructions, store, and built-in tools.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# isaachorowitz/ziplyne-agent-setup - external-providers/openai/api-reference/images-api.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | isaachorowitz/ziplyne-agent-setup - external-providers/openai/api-reference/images-api.md |
+| Source URL | https://github.com/isaachorowitz/ziplyne-agent-setup/blob/HEAD/external-providers/openai/api-reference/images-api.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Responses API reference` search on 2026-10-11. Vendored images-API notes with a Responses image-tool snippet.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Langdock/custom-model-example
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Langdock/custom-model-example |
+| Source URL | https://github.com/Langdock/custom-model-example |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Chat Completions API reference` search on 2026-10-11. Custom-model example citing the chat messages schema with a system role.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# lucasurrutia22/zeroq-support-hub - .claude/skills/zeroq-openai/SKILL.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | lucasurrutia22/zeroq-support-hub - .claude/skills/zeroq-openai/SKILL.md |
+| Source URL | https://github.com/lucasurrutia22/zeroq-support-hub/blob/HEAD/.claude/skills/zeroq-openai/SKILL.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Responses API reference` search on 2026-10-11. Skill doc asserting Responses-first usage with instructions, input, tools, and stream.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# mandax94/openai - README.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | mandax94/openai - README.md |
+| Source URL | https://github.com/mandax94/openai/blob/HEAD/README.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI official OpenAPI specification` search on 2026-10-11. Fork README describing the Responses surface and spec tag groups.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# matthewtaormina/agentskills - .agents/skills/openai-sdk/SKILL.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | matthewtaormina/agentskills - .agents/skills/openai-sdk/SKILL.md |
+| Source URL | https://github.com/matthewtaormina/agentskills/blob/HEAD/.agents/skills/openai-sdk/SKILL.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Responses API reference` search on 2026-10-11. SDK skill with a Responses call plus built-in web search example.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# maxzhao/maxa - .supermax/wiki/protocols/openai-responses.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | maxzhao/maxa - .supermax/wiki/protocols/openai-responses.md |
+| Source URL | https://github.com/maxzhao/maxa/blob/HEAD/.supermax/wiki/protocols/openai-responses.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Responses API reference` search on 2026-10-11. Community protocol notes scraped from the official OpenAPI, covering request fields and events.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# milad-o/cogent - feat(models/openai): migrate adapter to the Responses API
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | milad-o/cogent - feat(models/openai): migrate adapter to the Responses API |
+| Source URL | https://github.com/milad-o/cogent/commit/7126a0e56d3012b547b13d93c04c77b049778898 |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `migrate Chat Completions to Responses` search on 2026-10-11. Commit noting messages-to-items, system-to-instructions, and internally-tagged tools.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# minami-bein/ai-web3-school - notes/nobodyhi.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | minami-bein/ai-web3-school - notes/nobodyhi.md |
+| Source URL | https://github.com/minami-bein/ai-web3-school/blob/HEAD/notes/nobodyhi.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Chat Completions API reference` search on 2026-10-11. Study notes on chat completions roles and streaming.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# minorcell/aquaregia - refactor: migrate OpenAI adapter to Responses API, drop think-tag parsing
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | minorcell/aquaregia - refactor: migrate OpenAI adapter to Responses API, drop think-tag parsing |
+| Source URL | https://github.com/minorcell/aquaregia/commit/5752522026bc0314423ffb142591e8db3d1fdf8d |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `migrate Chat Completions to Responses` search on 2026-10-11. Commit noting system-to-instructions, flat function tools, and function_call_output.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# morning-start/prism - feat(schemas): vendor official OpenAI OpenAPI spec for conformance cross-check (TD-FV-1)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | morning-start/prism - feat(schemas): vendor official OpenAI OpenAPI spec for conformance cross-check (TD-FV-1) |
+| Source URL | https://github.com/morning-start/prism/commit/abd1fa4d4fb78b6c43e37bdf73ea2cbe4fc65cb |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI official OpenAPI specification` search on 2026-10-11. Commit vendoring the official spec for both endpoints for conformance checks.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# epic: continuous spec compliance testing across all API standards
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | epic: continuous spec compliance testing across all API standards |
+| Source URL | https://github.com/oaklight/llm-rosetta/issues/411 |
+| Source type | forum thread |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI official OpenAPI specification` search on 2026-10-11. Tracking issue listing official spec locations across API standards.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# openai/openai-openapi - Add detailed error responses for chat completion endpoints
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | openai/openai-openapi - Add detailed error responses for chat completion endpoints |
+| Source URL | https://github.com/openai/openai-openapi/commit/412c7b9820f61449eeded838e88d168a2ebd1794 |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI official OpenAPI specification` search on 2026-10-11. Official spec-repo commit; confirms the repo exists and is maintained.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# perongh/oai2ant - README.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | perongh/oai2ant - README.md |
+| Source URL | https://github.com/perongh/oai2ant/blob/HEAD/README.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Chat Completions API reference` search on 2026-10-11. Proxy README mapping system prompts, tool calls/results, and tool_choice between OpenAI chat and Anthropic shapes.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# piotrmieszczak/llm_utils - plugins/llm-app-patterns/skills/openai-api/SKILL.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | piotrmieszczak/llm_utils - plugins/llm-app-patterns/skills/openai-api/SKILL.md |
+| Source URL | https://github.com/piotrmieszczak/llm_utils/blob/HEAD/plugins/llm-app-patterns/skills/openai-api/SKILL.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Responses API reference` search on 2026-10-11. Responses-default quickstart using instructions and input.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# feat: support OpenAI Responses API (`/v1/responses`) for Codex CLI 0.96+
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | feat: support OpenAI Responses API (`/v1/responses`) for Codex CLI 0.96+ |
+| Source URL | https://github.com/rynfar/meridian/issues/475 |
+| Source type | forum thread |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Responses API reference` search on 2026-10-11. Issue sketching Responses request/response mapping including instructions-as-system.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# sabyasachi-seal/gpt-4 - .claude/commands/aix/sync-openai-apis.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | sabyasachi-seal/gpt-4 - .claude/commands/aix/sync-openai-apis.md |
+| Source URL | https://github.com/sabyasachi-seal/gpt-4/blob/HEAD/.claude/commands/aix/sync-openai-apis.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI official OpenAPI specification` search on 2026-10-11. Command doc listing official reference URLs for both APIs.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# sarthib7/sokosumi - apps/core/.agents/skills/openai-agent-chat/SKILL.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | sarthib7/sokosumi - apps/core/.agents/skills/openai-agent-chat/SKILL.md |
+| Source URL | https://github.com/sarthib7/sokosumi/blob/HEAD/apps/core/.agents/skills/openai-agent-chat/SKILL.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Responses API reference` search on 2026-10-11. Agent-chat skill showing instructions as the system prompt with store and tool_choice.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# startvibecoding/vibecoding - docs/en/gateway.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | startvibecoding/vibecoding - docs/en/gateway.md |
+| Source URL | https://github.com/startvibecoding/vibecoding/blob/HEAD/docs/en/gateway.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Chat Completions API reference` search on 2026-10-11. Gateway doc with a chat completions endpoint and system-message example.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# ulisestemichtome-create/bifrost - tests/e2e/api/HARNESS_COVERAGE_BACKLOG.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | ulisestemichtome-create/bifrost - tests/e2e/api/HARNESS_COVERAGE_BACKLOG.md |
+| Source URL | https://github.com/ulisestemichtome-create/bifrost/blob/HEAD/tests/e2e/api/HARNESS_COVERAGE_BACKLOG.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI Chat Completions API reference` search on 2026-10-11. Fork of the same e2e coverage list as the fairmehit copy above.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# workglow-dev/libs - Migrate OpenAI text run-fns to the Responses API
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | workglow-dev/libs - Migrate OpenAI text run-fns to the Responses API |
+| Source URL | https://github.com/workglow-dev/libs/commit/9356528caccd764a83968d58781c67c019e10b51 |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `migrate Chat Completions to Responses` search on 2026-10-11. Commit noting JSON mode via text.format.json_schema and Responses stream accumulation.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# GPT-6 Astra API Migration Guide: Breaking Changes
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | GPT-6 Astra API Migration Guide: Breaking Changes |
+| Source URL | https://llmfly.ai/blog/2026/09/05/gpt-6-astra-api-migration-guide/ |
+| Source type | blog post |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `migrate Chat Completions to Responses` search on 2026-10-11. Third-party migration guide claiming Responses-required tool calling on newer models.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# OpenAI's API Evolution: Responses API vs. Chat Completions API | by Praveen Singh | Jan, 2026 | Medium
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | OpenAI's API Evolution: Responses API vs. Chat Completions API | by Praveen Singh | Jan, 2026 | Medium |
+| Source URL | https://medium.com/@praveenkumarsingh/openais-api-evolution-responses-api-vs-chat-completions-api-0463d73ce631 |
+| Source type | blog post |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `OpenAI official OpenAPI specification` search on 2026-10-11. Evolution overview: Chat supported, Responses recommended for new work.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,60 @@
+# Chat Completions | OpenAI API Reference
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Chat Completions |
+| Source URL | https://developers.openai.com/api/reference/resources/chat |
+| Source publisher / author | OpenAI |
+| Source type | vendor docs |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+The full Chat Completions reference. It defines `POST /chat/completions` over a `messages` array with system/developer/user/assistant/tool roles, externally-tagged function tools, `tool_choice` (none/auto/required/named/allowed-tools), `response_format` structured outputs, and `delta`-based stream chunks. This is the "classic" side of the transpiler.
+
+## Key findings
+
+- Create call is `POST /chat/completions`; "Returns a chat completion object, or a streamed sequence of chat completion chunk objects if the request is streamed."
+- "Starting a new project? We recommend trying Responses to take advantage of the latest OpenAI platform features."
+- Developer messages: "Developer-provided instructions that the model should follow, regardless of messages sent by the user. With o1 models and newer, `developer` messages replace the previous `system` messages." The system entry says "With o1 models and newer, use `developer` messages for this purpose instead."
+- Assistant tool calls are `{id, type: "function", function: {name, arguments}}` with string JSON arguments; tool answers are `{role: "tool", tool_call_id, content}` with text-only content.
+- `tool_choice`: "`none` means the model will not call any tool", "`auto` means the model can pick", "`required` means the model must call one or more tools"; named choice is `{"type": "function", "function": {"name": ...}}`, plus an `allowed_tools` mode.
+- Function tools are externally tagged: `{type: "function", function: {name, description, parameters, strict}}`.
+- `response_format` supports text, `json_object`, and `json_schema {name, description, schema, strict}`.
+- Stream chunks are `chat.completion.chunk` objects with `choices[].delta` (`role`, `content`, `tool_calls`) and terminal `finish_reason` of `stop`, `length`, or `tool_calls`.
+- The request surface includes Chat-only fields with no Responses counterpart: `n`, `stop`, `seed`, `logprobs`, `frequency_penalty`, `presence_penalty`, `logit_bias`, `prediction`, `modalities`, audio, and `web_search_options`.
+
+## Pros / strengths
+
+- Authoritative and complete for the classic surface, including deprecated `function_call` and refusal parts.
+- Exact `tool_calls` / `tool_call_id` correlation semantics, which map 1:1 onto Responses `call_id`.
+- Explicit Responses recommendation links the two APIs as one migration story.
+
+## Cons / limitations / caveats
+
+- The fetch was truncated; findings rest on the messages/tools/choice/format/streaming sections, not the modality guides.
+- Chat is the legacy-recommended surface, so new model capabilities (reasoning + tools, newer built-ins) may never land here.
+- Some newer model constraints (e.g. tool-calling limits with reasoning effort) live in guides, not this page.
+
+## Relevance to tai
+
+- Defines the classic request, object, and chunk shapes the transpiler accepts and emits.
+- The system/developer role history explains why Meta's wire uses `developer` while older clients use `system`: both are valid guidance channels.
+- The Chat-only field list becomes the documented drop set with warnings in `chat_to_responses`.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,61 @@
+# Migrate to the Responses API
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Migrate to the Responses API |
+| Source URL | https://developers.openai.com/api/docs/guides/migrate-to-responses |
+| Source publisher / author | OpenAI |
+| Source type | vendor docs |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+OpenAI's official migration guide from Chat Completions to the Responses API. It states Responses is the recommended primitive for new projects while Chat Completions remains supported, then gives side-by-side mappings: messages to Items, system guidance to `instructions`, externally-tagged function tools to internally-tagged ones, `response_format` to `text.format`, and `delta` stream chunks to typed server-sent events.
+
+## Key findings
+
+- "While Chat Completions remains supported, Responses is recommended for all new projects."
+- "The input to, and result of, a call to Chat Completions is an array of _Messages_, while the Responses API uses _Items_." A `message` is one Item type alongside `function_call` and `function_call_output`.
+- "Chat Completions can return multiple parallel generations as `choices`, using the `n` parameter. The Responses API omits this parameter and returns only one generation."
+- System or developer guidance maps to "Top-level `instructions`, or compatible message Items when you need to preserve an existing transcript".
+- "Use `previous_response_id` when you want OpenAI to manage prior response context. Resend stable `instructions` on each request, because `previous_response_id` does not carry over the previous response's top-level `instructions`."
+- Function definitions differ twice: "In Chat Completions, function definitions are externally tagged. In Responses, they are internally tagged." Chat functions are non-strict by default; Responses omitting `strict` attempts strict mode and falls back best-effort, so explicit `strict: false` preserves Chat behavior.
+- "In the Responses API, Structured Outputs definitions have moved from `response_format` to `text.format`".
+- "Chat Completions streaming returns incremental chunks with a `delta` field. Responses streaming uses typed server-sent events." Text uses `response.created`, `response.output_text.delta`, `response.completed`, `error`; function calls add `response.function_call_arguments.delta` and `response.function_call_arguments.done`.
+- State: "Responses are stored by default. Chat completions are stored by default for new accounts. To disable storage in either API, set `store: false`." Stateless reasoning continues via encrypted reasoning items.
+- Starting with GPT-5.4, "Chat Completions does not support tool calling with `reasoning_effort` values other than `none`".
+
+## Pros / strengths
+
+- Authoritative primary source with side-by-side request/response/streaming examples in six languages.
+- Explicit loss points (single generation, no `choices`, typed events) instead of marketing gloss.
+- Covers failure modes: common migration errors list plus an incremental rollout checklist.
+
+## Cons / limitations / caveats
+
+- The capabilities comparison table rendered with empty cells in the fetched copy, so per-capability parity claims could not be verified from this page.
+- Model-specific claims (GPT-5.x/6.x behavior, eval deltas) are version-sensitive and will rot.
+- Says nothing about vendor extensions such as Meta's `type: namespace` tools, `prompt_cache_key` values, or `x-tbh-*` headers.
+
+## Relevance to tai
+
+- This is the primary mapping spec behind the bidirectional transpiler: instructions/system equivalence, tool re-tagging, `text.format`, single-generation loss, and typed-event streaming.
+- Confirms the system-message answer three ways (top-level `instructions` preferred, message Items otherwise).
+- Confirms `store: false` + encrypted reasoning as the stateless pattern Meta's client uses (`include: ["reasoning.encrypted_content"]` in the capture).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,59 @@
+# Responses | OpenAI API Reference
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Responses |
+| Source URL | https://developers.openai.com/api/reference/resources/responses |
+| Source publisher / author | OpenAI |
+| Source type | vendor docs |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+The full Responses API reference. It defines `POST /responses` body parameters, the `EasyInputMessage` input shape, internally-tagged function tools, `function_call` / `function_call_output` Items correlated by `call_id`, output messages with `output_text` / `refusal` parts, and the typed SSE event vocabulary. Every Meta request field in the local capture has a documented counterpart here except the `muse` namespace tool.
+
+## Key findings
+
+- Create call is `POST /responses` with body parameters including `input`, `instructions`, `tools`, `tool_choice`, `text`, `stream`, `store`, `previous_response_id`, `max_output_tokens`, `reasoning`, `include`, `prompt_cache_key`, `parallel_tool_calls`, `temperature`, `top_p`, `truncation`, `metadata`, and `user`.
+- `instructions` is "A system (or developer) message inserted into the model's context." and "When using along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response."
+- `EasyInputMessage` roles are exactly `user`, `assistant`, `system`, `developer`; string content or part lists of `input_text`, `input_image`, `input_file`.
+- Function tools are internally tagged: `{type: "function", name, parameters, strict, description, ...}`.
+- `function_call` Items carry string `arguments`, a `call_id` ("The unique ID of the function tool call generated by the model"), and `name`; `function_call_output` answers with the same `call_id` plus string or part-list `output`.
+- Output messages contain `output_text` (`{text, annotations, logprobs, type}`) or `refusal` (`{refusal, type}`) parts.
+- Streaming vocabulary includes `response.created`, `response.in_progress`, `response.output_text.delta` (`{item_id, output_index, content_index, delta}`), `response.function_call_arguments.delta` / `.done`, and `response.completed` carrying the full response object with `usage {input_tokens, output_tokens, total_tokens}`.
+- `include` supports `reasoning.encrypted_content`: "Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly".
+
+## Pros / strengths
+
+- Authoritative schema detail down to field optionality, with request and SSE examples.
+- `include` / `store: false` / encrypted-reasoning semantics directly explain the Meta client's stateless posture.
+- Documents both lifecycle events and delta events, which is exactly what a stream transpiler needs.
+
+## Cons / limitations / caveats
+
+- The page is about 5 MB; the fetch was truncated and the dossier rests on targeted excerpts (create params, input/tool/output/streaming sections), not a full read.
+- No `namespace` tool type is documented, confirming Meta's `muse` tool set is a vendor extension with no portable mapping.
+- Fast-moving surface: newer built-in tools and programmatic-calling fields postdate any fixed summary.
+
+## Relevance to tai
+
+- Supplies the exact request, object, and event shapes the transpiler emits and parses.
+- Verifies the absence of `n`, `stop`, `seed`, and sampling-penalty parameters, which become documented transpile-time drops.
+- The `prompt_cache_key` parameter exists upstream too, so Meta's cache keys transpile as scalars rather than extensions.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Moderations | OpenAI API Reference
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Moderations | OpenAI API Reference |
+| Source URL | https://platform.openai.com/docs/api-reference/moderations |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:platform.openai.com Create response` search on 2026-10-11. Surfaced on the `instructions` keyword via the self-harm/instructions category; irrelevant.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# API Reference - OpenAI API
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | API Reference - OpenAI API |
+| Source URL | https://platform.openai.com/docs/api-reference/realtime-client-events/conversation/item/delete?ref=pubrio.com |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:platform.openai.com Create response` search on 2026-10-11. Realtime conversation-event page; off-topic for the text APIs.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# API Reference - OpenAI API
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | API Reference - OpenAI API |
+| Source URL | https://platform.openai.com/docs/api-reference/realtime-beta-client-events/input_audio_buffer/commit?ref=hackernoon.com |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:platform.openai.com Create response` search on 2026-10-11. Realtime client-event page mentioning response.create instructions and tools; off-topic for the text APIs.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Client events | OpenAI API Reference
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | muse-responses-openai-transpiler |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Client events | OpenAI API Reference |
+| Source URL | https://platform.openai.com/docs/api-reference/realtime-client-events/session?ref=nekonya.cyou |
+| Source type | vendor docs |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the `site:platform.openai.com Create response` search on 2026-10-11. Realtime session-events page; off-topic for the text APIs.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,48 @@
+# ai-nexus ratatui best-practices — 80-column breakpoint guidance
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | ai-nexus ratatui best-practices.md — side-by-side vs stacked guidance |
+| Source URL | https://raw.githubusercontent.com/jsk9999/ai-nexus/main/config/skills/ratatui_rs/referencecs/best-practices.md |
+| Source publisher / author | jsk9999 (ai-nexus project) |
+| Source type | other (guidance/reference doc in repository) |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Low |
+| Status | Active |
+
+## Summary
+
+A guidance document (not a shipped client) recommending side-by-side panes at widths of 80 columns and above with a stacked layout below, and mentioning fixed-cell sidebar widths. It is the sole source of the 80-column breakpoint number — and its guidance-doc status, versus the unanimous Percentage(30) splits and manual toggles of the inspected shipped clients, is its main caveat.
+
+## Key findings
+
+- Recommends side-by-side layout at terminal widths >= 80 columns, stacked layout below 80.
+- Mentions fixed-cell sidebar widths (e.g. `Length`-style constants) rather than percentage splits.
+
+## Pros / strengths
+
+- The only inspected source that states any breakpoint number at all, giving tai a starting value to validate rather than a blank field.
+
+## Cons / limitations / caveats
+
+- Guidance doc, not a shipped client: no inspected real client implements automatic narrow-terminal breakpoints, so the 80-column rule is unvalidated by shipped behavior.
+- Its fixed-cell sidebar widths contradict every inspected client, which all use `Percentage(30)` — the clients win this argument, not the doc.
+
+## Relevance to tai
+
+- Supplies the provisional sub-80-column auto-hide breakpoint in the messaging-layout conclusion, explicitly flagged there as guidance-doc-sourced and sequenced after the manual toggle that shipped clients actually implement.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created from 2026-10-11 research-pass evidence (body opened via web_fetch by researching agent). |
@@ -0,0 +1,51 @@
+# axhub-make Telegram mobile theme teardown (DESIGN.md)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | telegram-mobile DESIGN.md (axhub-make theme teardown) |
+| Source URL | https://raw.githubusercontent.com/lintendo/axhub-make/HEAD/client/src/themes/telegram-mobile/DESIGN.md |
+| Source publisher / author | lintendo/axhub-make (third party) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A third-party teardown of Telegram's iOS client recording native chrome colors (outgoing accent-blue bubbles, neutral incoming bubbles, `#0088CC` accent) and the only type-and-spacing scale found anywhere: system fonts, 17pt body, 14pt in-bubble sender names, 11pt in-bubble time, 44px touch targets, 10pt radii, 50pt CTA height. Valuable and entirely unofficial.
+
+## Key findings
+
+- Native chrome: outgoing bubble `#2B86FD` with white text; incoming bubble white (light) / `#2A2A2A` (dark); accent `#0088CC`; canvas `#FFFFFF` (light) / `#212121` (dark).
+- Typography is the system font (SF Pro on iOS, Roboto on Android): 17pt body text, 17pt semibold names, 14pt semibold sender names inside bubbles, 13pt list time, 11pt in-bubble time.
+- Spacing scale: 44px-plus touch targets, 16px-plus input font (avoids mobile zoom), 10pt corner radii, 50pt CTA height.
+
+## Pros / strengths
+
+- The only source found with concrete type sizes and spacing numbers for anything Telegram-shaped.
+- Chrome colors corroborate the official Desktop theme files directionally (blue outgoing, neutral incoming).
+
+## Cons / limitations / caveats
+
+- Third-party iOS teardown, unverified against Android and Desktop: treat every number as indicative, not canonical.
+- No official typography or spacing specification exists in Telegram's docs, so there is nothing authoritative to check these numbers against (open gap).
+- Pixel units (radii, CTA height, touch targets) have no literal terminal equivalent; only relative emphasis transfers.
+
+## Relevance to tai
+
+The sole basis for tai's Telegram-derived type emphasis scale (body > sender > time) and the accent-blue outgoing convention; every value it contributes is flagged third-party in the conclusions that use it.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,50 @@
+# bubbletea examples/chat — viewport plus textarea chat example
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | bubbletea examples/chat/main.go — chat example (no sidebar) |
+| Source URL | https://raw.githubusercontent.com/charmbracelet/bubbletea/main/examples/chat/main.go |
+| Source publisher / author | Charm (bubbletea project) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+Charm's own minimal chat example: a full-width transcript viewport over a 3-row textarea with a 280-character limit, resizing both to the window on `WindowSizeMsg`, jumping to the bottom on send and resize, with Enter to send and Esc/Ctrl+C to quit. Notably sidebar-free.
+
+## Key findings
+
+- Layout is a transcript viewport plus a 3-row textarea (placeholder `Send a message...`, `CharLimit` 280, box-glyph prompt); there is no sidebar or chat list.
+- `WindowSizeMsg` resizes both components to full width with viewport height set to window height minus textarea height; sends and resizes trigger `GotoBottom`.
+- Enter sends; Esc or Ctrl+C quits.
+
+## Pros / strengths
+
+- Authoritative minimal precedent from the framework authors: the viewport-resize math and send-then-bottom pattern are directly reusable.
+- Shows the no-sidebar endpoint of the design space, bounding tai's choice.
+
+## Cons / limitations / caveats
+
+- An example, not a shipped client: no chat list, no status bar, no history, no per-message state — tai needs the fuller clients for those.
+- Full-width single-pane layout is rejected for tai, which needs a conversation list.
+
+## Relevance to tai
+
+- Contributes the viewport height math (window minus input) and send-then-bottom behavior to the messaging-layout conclusion; its sidebar-free shape is recorded there as a considered and rejected alternative.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created from 2026-10-11 research-pass evidence (body opened via web_fetch by researching agent). |
@@ -0,0 +1,49 @@
+# bubbletea examples/glamour — markdown rendering width math
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | bubbletea examples/glamour/main.go — Glamour markdown example |
+| Source URL | https://raw.githubusercontent.com/charmbracelet/bubbletea/main/examples/glamour/main.go |
+| Source publisher / author | Charm (bubbletea project) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+Charm's markdown-in-a-viewport example: content is rendered through the Glamour markdown renderer into a viewport, with the render width computed as viewport width minus frame size minus a 3-column gutter, and dark/light style auto-detected. A thin source; the width formula is the finding.
+
+## Key findings
+
+- Markdown is rendered via the Glamour renderer into a scrollable viewport (static content, not streaming).
+- Render width equals viewport width minus frame size minus a 3-column gutter; dark/light style is auto-detected.
+
+## Pros / strengths
+
+- The width-minus-chrome formula is exactly the rule tai's markdown renderer needs, from the framework authors.
+- Demonstrates that markdown belongs in the transcript viewport, not in a separate pane.
+
+## Cons / limitations / caveats
+
+- Static markdown only: no streaming or incremental re-render behavior to learn from.
+- Glamour itself is a Go library; tai needs a native equivalent, not this code.
+
+## Relevance to tai
+
+- Supplies the markdown width-minus-chrome rule adopted in the messaging-layout conclusion (markdown for assistant content, rendered at viewport width minus frame and gutter).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created from 2026-10-11 research-pass evidence (body opened via web_fetch by researching agent). |
@@ -0,0 +1,49 @@
+# bubbletint README — tint registry and runtime switching
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | bubbletint README — theme collection for bubbletea/lipgloss |
+| Source URL | https://raw.githubusercontent.com/lrstanley/bubbletint/master/README.md |
+| Source publisher / author | lrstanley (bubbletint project) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A 340-plus theme collection for the bubbletea/lipgloss ecosystem with the registry shape tai wants: a global default registry plus custom registries, runtime switching, and JSON file loading. The registry mechanics are the finding, not the tint count.
+
+## Key findings
+
+- Ships 340+ named tints behind a registry API with a global default registry plus support for custom registries.
+- Supports switching themes at runtime and loading themes from JSON files.
+
+## Pros / strengths
+
+- Registry-shape precedent: global default plus custom registries plus file loading covers every lookup need with one pattern.
+- Proves JSON file loading composes cleanly with a dict-style registry.
+
+## Cons / limitations / caveats
+
+- Tints target lipgloss's role-less model, so per-theme structure is thinner than tai's role palette; the registry shape ports, the theme contents do not.
+- Scale (340+) is ecosystem-collection scale; tai ships 4–6 builtins.
+
+## Relevance to tai
+
+- Registry-shape precedent for the palette-role conclusion (`THEMES` dict plus `register_theme`), and the JSON-load precedent behind the deferred file-override design.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created from 2026-10-11 research-pass evidence (body opened via web_fetch by researching agent). |
@@ -0,0 +1,64 @@
+# Conclusion: Telegram-like messaging layout for tai's chat scene
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Conclusion |
+| Tier | N/A |
+| Date decided | 2026-10-11 |
+| Decided by | retoor, advised by tai (agent, Muse Spark) |
+| Status | Active |
+| Confidence | Medium |
+
+## Question / problem statement
+
+How should tai's Telegram-like chat scene (conversation sidebar, message transcript, input box, status line) be laid out, navigated, and rendered on top of the retained-DOM framework — which geometry, which keybindings, which scroll and send contracts — given that the working tree has no chat-transcript widget, no status-bar widget, no send-on-Enter mode, and no responsive breakpoints (established by the same-session internal inventory of tai.py)?
+
+## Conclusion
+
+Build the chat scene as a left chat list at 30% width (min 24, max 36 columns) beside a right transcript plus input, with the input 3 rows collapsed growing to 5–8 rows with content and a 1-line status bar at the bottom carrying transient status plus per-focus hints on one side and connection/user/chat identity on the other. Ship a manual sidebar toggle first (F2/Ctrl+B or Tab cycle), adding automatic hide below 80 columns only as an enhancement. Navigate modally (Normal/Input) with Tab/Shift+Tab pane cycling, `i`/Enter/Esc, `j`/`k` plus arrows, `g`/`G`, PgUp/PgDn, `/` search, `?` hints, `q` quit. Render left-aligned wrapped rows with sender grouping and per-message sending/failed state (never right-aligned bubbles); render markdown only for assistant content at viewport width minus frame minus gutter; stream by re-setting viewport content with pin-to-bottom only when already at the bottom; show tool calls as collapsible bordered block rows. Input is multiline with Enter to send, Shift+Enter (or Alt+Enter) for newline, per-chat draft retention, send history, and a ~2000-character cap with optimistic echo.
+
+## Supporting sources
+
+- `../telecli-tui-chat-layout.md` — base numbers: 30/70 split, 3-row input, 1-line status overlay, modal Normal/Input keys.
+- `../send-rs-tui-draw-main.md` — confirms the 30/70 + 1-line-status skeleton; focused-pane accent border.
+- `../send-rs-tui-focus-state.md` — explicit focus state with per-chat draft retention on focus moves.
+- `../send-rs-config-keymap.md` — default keymap (Tab cycle, `i`/Enter/Esc, Shift+Enter newline) and 5-line input cap.
+- `../send-rs-tui-status-bar.md` — status content policy: per-focus hints with transient-override messages.
+- `../send-rs-chat-widget.md` — pre-wrapped rows plus scrollbar, dynamic input height, and the decisive bubble rejection.
+- `../za-tui-app-styles.md` — cross-framework corroboration of 30/70 + 3–8-row input + 1-row status.
+- `../za-tui-main-screen.md` — manual sidebar toggle (F2/Ctrl+B) with auto-hide deliberately omitted; F6 focus cycle.
+- `../za-tui-status-bar.md` — identity half of status content: connection dot + user + active conversation.
+- `../za-tui-input-bar.md` — input contract: Enter send, Shift+Enter newline, 2000-char cap, 100-entry history.
+- `../za-tui-chat-view.md` — transcript contract: sender grouping, per-message status, conditional pin-to-bottom, scroll-top history load.
+- `../bubbletea-chat-example.md` — viewport height math (window minus input) and send-then-bottom behavior.
+- `../bubbletea-glamour-example.md` — markdown width-minus-chrome rule (viewport minus frame minus 3-column gutter).
+- `../ai-nexus-ratatui-best-practices.md` — provisional sub-80-column breakpoint number (guidance-doc sourced, flagged as such).
+
+## Alternatives considered and rejected
+
+- Right-aligned outgoing bubbles: rejected — send-rs implemented them and reverted them as ugly; all shipped clients use left-aligned rows.
+- Automatic sidebar auto-hide from day one: rejected as v1 — za-tui deliberately omitted it (breaks tests) and ships manual toggle; auto-hide below 80 columns follows as an enhancement.
+- Sidebar-free full-width layout (bubbletea chat example): rejected — tai needs a conversation/agent list beside the transcript.
+- Fixed-cell sidebar width (`Length(30)`): rejected — appears only in the guidance doc while every inspected client uses `Percentage(30)`; percentage with min/max clamps wins.
+- Always-stacked layout: rejected — all three messaging clients ship side-by-side as the default, stacking only as the narrow fallback.
+
+## Risks / open questions
+
+- The 80-column breakpoint comes from a guidance doc, not a shipped client — no inspected real client implements automatic narrow-terminal breakpoints. Validate the number against real terminals before treating it as settled.
+- No streaming/token rendering or tool-call blocks were observed in any messaging client; the re-set-plus-pin-to-bottom carrier and collapsible-block rows are inferred patterns, with Glamour covering static markdown only.
+- tai still needs a markdown-to-styled-run renderer (the REPL's `render_markdown` emits ANSI strings unusable by the compositor), a send-on-Enter input mode, and a wide-character width table — all established gaps from the same-session inventory.
+- Agent turns are blocking and must run in threads posting back via timers; the streaming contract assumes that bridge works.
+
+## Action taken
+
+Nothing built yet: the chat scene is specified by this conclusion and its sources, but no chat-transcript widget, status-bar widget, or scene builder exists in the working tree. This conclusion records what to build, not what shipped.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial conclusion recorded. |
@@ -0,0 +1,59 @@
+# Conclusion: Minimal palette-role theming for tai's TUI
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Conclusion |
+| Tier | N/A |
+| Date decided | 2026-10-11 |
+| Decided by | retoor, advised by tai (agent, Muse Spark) |
+| Status | Active |
+| Confidence | Medium |
+
+## Question / problem statement
+
+How should tai's retained-DOM TUI gain themes — how many color roles, what registry and switching mechanism, what flag/env precedence, and how widgets resolve colors — given that the working tree has no theme object, no stylesheet, and no palette indirection (every widget hardcodes inline `TuiStyle` values, established by the same-session internal inventory of tai.py)?
+
+## Conclusion
+
+Ship a 12-role palette: surfaces `bg` and `surface`; text `fg` and `muted`; chrome `border`, `accent`, `on_accent`, and `selection`; semantic `success`, `warning`, `error`, and `info` — each theme also carrying a `dark` flag, colors as hex strings resolved at render. Hold themes in a `THEMES: dict[str, Theme]` registry (`Theme` a dataclass of name, dark flag, and role dict) with `register_theme()` for user themes and 4–6 kebab-case builtins (`dark`, `light`, `nord`, `gruvbox`, `ansi`). Select with a `--theme` flag validated against the registry (unknown names print the list and exit 2); precedence is flag > `TAI_THEME` env var > default. Switch at runtime via `App.set_theme(name)`, which swaps the pointer and triggers a full redraw, plus one cycle key (e.g. F4) advancing registry order. Style objects store role names and resolve against the current theme at draw time; raw colors (`#rrggbb`, ANSI names) pass through as an escape hatch; per-widget override dicts merge over theme roles. Defer file-based overrides; if ever added, merge a partial role dict from TOML/JSON over a named theme.
+
+## Supporting sources
+
+- `../textual-theme-module.md` — role names and kebab-case dict registry template (11 bases, 21 builtins); generated-shade machinery explicitly not copied.
+- `../textual-design-guide.md` — live-switch contract (swap pointer plus redraw) and user-facing switcher precedent.
+- `../textual-constants-theme-env.md` — env-var default precedent behind flag > `TAI_THEME` > default.
+- `../lipgloss-pkg-docs.md` — negation precedent (roles omitted) and the deferred `AdaptiveColor` light/dark idea.
+- `../bubbletint-readme.md` — registry-shape precedent (global default plus custom registries, JSON file load).
+- `../ratatui-themes-readme.md` — closest minimal precedent: small fixed role set, named registry, next/prev cycling, serialization.
+- `../ratatui-kit-theming.md` — resolution pattern: palette as source of truth, derive at draw time, non-exhaustive growth headroom.
+- `../pytermgui-styling-docs.md` — live-regenerate spirit (a switch repaints everything) and shade offsets; single-primary limit is why tai takes 12 roles.
+- `../pytermgui-file-loaders.md` — file-override precedent behind the deferred TOML/JSON partial-dict merge.
+
+## Alternatives considered and rejected
+
+- Full Textual-style generated shade/variable system: rejected — the generator machinery is Textual-scale overkill for tai; copy the role names and registry, not the generator.
+- lipgloss-style raw colors with no roles: rejected — leaves every theme need to the user, which is the gap being filled; roles are the point.
+- pytermgui-style single-primary global palette: rejected — one primary cannot express independent semantic hues (success/warning/error/info); 12 roles instead.
+- File-based TOML/JSON theme overrides now: rejected as v1 — deferred until a real user need appears; the merge design is recorded so it can be added without registry changes.
+- Light/dark auto-detection (`AdaptiveColor` style) now: rejected as v1 — recorded as a later enhancement, not launch scope.
+
+## Risks / open questions
+
+- The 12-role set is an intersection of surveyed systems, not a validated minimum; new widget needs may force additions (the non-exhaustive lesson anticipates this).
+- ratatui core's own styling primitives were never fetched — "no registry in core" is inference from ecosystem crates only, so a core-side precedent may exist unexamined.
+- pytermgui `NO_COLOR` details, Textual's app-level `get_css_variables` override, and lipgloss v2's `LightDark` successor were seen in snippets only and remain unverified; the REPL already honors `NO_COLOR`, and the TUI must match it when themes land.
+- Full-redraw switching assumes redraws stay cheap as scenes grow; revisit if theme switches visibly lag.
+
+## Action taken
+
+Nothing built yet: no `Theme` dataclass, registry, flag, or role resolution exists in the working tree — widgets still hardcode inline styles. This conclusion records what to build, not what shipped.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial conclusion recorded. |
@@ -0,0 +1,65 @@
+# Conclusion: Telegram chat grammar tai adopts (rows, not bubbles)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Conclusion |
+| Tier | N/A |
+| Date decided | 2026-10-11 |
+| Decided by | retoor, advised by tai (agent, Muse Spark) |
+| Status | Active |
+| Confidence | High |
+
+## Question / problem statement
+
+Which Telegram look-and-feel patterns should tai's TUI chat scene adopt now that rows-not-bubbles is already decided — which glyphs, palettes, pills, labels, and bot surfaces transfer to a terminal, and which stay behind — given that the working tree has no bubbles, ticks, date dividers, header bar, rich list rows, or composer buttons (established by the same-session internal inventory of tai.py, which mapped each missing piece to a patch target but produced no source documents, being internal code)?
+
+## Conclusion
+
+Adopt Telegram's metadata grammar rendered as left-aligned rows: clock for sending, single check for cloud receipt, blue double check for read, eye-plus-count for broadcast views, and no delivered state ever; color group sender names from the 8-hue peer palette in its day and night re-tones; render date dividers and service events as centered pills with `{month} {day}` phrasing, and unread position as an `N Unread Message(s)` bar; use Telegram's literal copy for the status line (`online`, `typing...`, the seven-step last-seen scale), the composer (`Write a message...`, red `Draft:`, blue typing override), and bot surfaces (`Menu` button, `Show/Hide bot keyboard`, Start button on first open, `/start` deep links up to 64 chars, global `/start` `/help` `/settings`, max 100 scoped commands with `/` autocomplete, reply keyboards distinct from inline message buttons). Reject right-aligned bubbles (already rejected), gradient/animated per-chat bubble themes, and any delivered-to-device state.
+
+## Supporting sources
+
+- `../tdesktop-day-blue-theme.md` — light defaults: bubble, time, service-pill, unread-pill hexes; day peer palette.
+- `../tdesktop-night-theme.md` — dark defaults pairing every day key; night peer palette re-tones.
+- `../telegram-faq.md` — check semantics (cloud, read, no delivered state) and the 30s online rule.
+- `../telegram-blog-chat-themes-read-receipts.md` — group receipt rule (one reader, tap-for-readers, 7 days); gradient themes as the explicit rejection boundary.
+- `../techmesto-telegram-checkmarks.md` — corroborates clock/blue-checks; supplies the channel eye-plus-views treatment.
+- `../tdesktop-lang-strings.md` — literal copy for status scale, unread bar, composer, attach, bot toggles, reply/edit.
+- `../telegram-android-dialog-cell.md` — sidebar row element inventory: avatar, name plus time, snippet with prefixes, pill, pin/mute, draft-red, typing-blue.
+- `../telegram-android-chat-message-cell.md` — grouping grammar (joined same-sender runs, tail-on-last, trailing time plus checks, peer-hue names).
+- `../telegram-bot-api.md` — reply vs inline keyboard grammar, menu button variants, 100-command cap, placeholder contract.
+- `../telegram-bot-features.md` — Start-button first open, `?start=` deep links, three global commands.
+
+## Alternatives considered and rejected
+
+- Literal bubble rendering with tails and alternating alignment: rejected — rows-not-bubbles is already decided, and send-rs precedent plus all shipped clients confirm rows.
+- Inventing tai-native status glyphs: rejected — Telegram's clock/check/eye vocabulary is settled and recognizable; invention adds learning cost for no gain.
+- Copying per-chat gradient/animated bubble themes: rejected — no terminal equivalent exists; theming stays at the palette-role level.
+- A delivered-to-device state: rejected — Telegram deliberately has none (multi-device), so there is nothing to mirror.
+
+## Risks / open questions
+
+- iOS and Web client exact hexes were never verified; only Desktop day/night values are canonical here.
+- Bubble corner radii, paddings, inter-message spacing, and tail shape/side per client are unknown — mostly moot under rows-not-bubbles, but any future bubble attempt must re-research them.
+- Conversation header icon inventory per client (call/video/search/more) was not captured.
+- Chat-list time/date formatting rules and snippet truncation behavior were not captured.
+- Send-vs-voice button swap behavior and media-bubble time-overlay details were not captured.
+
+## Action taken
+
+Nothing built yet: the transcript still renders plain left rows with sender-change headers only, the sidebar shows plain names, and no ticks, pills, header bar, or bot surfaces exist. The same-session internal inventory maps each adoption to its patch target (transcript rows, send path, status painter, sidebar rows, input container), so this conclusion records what to build and where, not what shipped.
+
+## Amendment (2026-10-11): user override to literal bubbles
+
+retoor overrode the rows verdict after seeing the rows UI: `--tui` must look exactly like Telegram, and rows-only does not. Implemented as bg-fill aligned bubble blocks (no box borders): outgoing right-aligned, incoming left-aligned, max 70% width, pad 1, time plus ticks bottom-right inside the bubble. Tails omitted (no terminal equivalent in evidence). Retained from this conclusion: the full metadata grammar (clock/checks/blue-read, no delivered state), service pills, literal copy, bot surfaces. Below the narrow breakpoint bubbles degrade to full-width rows. Original verdict preserved above for the record.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial conclusion recorded. |
+| 2026-10-11 | Amendment: user override rows to literal bg-fill bubbles; tails omitted; narrow fallback to full-width rows. |
@@ -0,0 +1,62 @@
+# Conclusion: Telegram ThemeParams as tai's theme-role reference
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Conclusion |
+| Tier | N/A |
+| Date decided | 2026-10-11 |
+| Decided by | retoor, advised by tai (agent, Muse Spark) |
+| Status | Active |
+| Confidence | Medium |
+
+## Question / problem statement
+
+How should Telegram's official `ThemeParams` vocabulary relate to tai's already-decided 12-role palette — which keys map to which roles, what default values ship, and what switching discipline applies — given that Telegram's values are user-themeable samples rather than constants, and that the working tree resolves roles at draw time but leaves borders hardcoded and several roles unused (established by the same-session internal inventory of tai.py, internal code, no source documents)?
+
+## Conclusion
+
+Treat Telegram's 15 `ThemeParams` keys as the reference vocabulary mapped onto tai's 12 roles: canvas keys (`bg_color`, `secondary_bg_color`, `section_bg_color`, `header_bg_color`, `bottom_bar_bg_color`) onto `bg`/`surface`; text keys (`text_color`, `subtitle_text_color`, `section_header_text_color`, `accent_text_color`) onto `fg`/`muted`/`accent`; `hint_color` onto `muted`; `link_color` onto `accent`; `button_color`/`button_text_color` onto `accent`/`on_accent`; `section_separator_color` onto `border`; `destructive_text_color` onto `error` — with representative light/dark defaults taken from the Desktop theme files and the dark samples (`#17212b` canvas, `#f5f5f5` text, `#708499` hint, `#6ab3f3` link, `#5288c1` button, `#6ab2f2` accent text, `#ec3942` destructive), accent-blue `#2B86FD` outgoing convention, and the 17/14/11pt emphasis scale (third-party, flagged as such). Adopt Telegram's switching discipline as law: never hardcode colors, re-read the theme on every switch (tai's `set_theme` plus full repaint is the `themeChanged` equivalent), and never cache resolved colors across a switch. Defer exact light defaults for `section_*`/`subtitle`/`destructive` until officially published.
+
+## Supporting sources
+
+- `../telegram-webapps-docs.md` — the 15-key contract, `light`/`dark` scheme plus `themeChanged`, design rules, chrome inventory.
+- `../mini-apps-docs-theming.md` — dark sample values and the never-hardcode/re-read rule.
+- `../mini-apps-docs-main-button.md` — bottom primary-action grammar with active/progress states; back control with no implicit behavior.
+- `../mini-apps-docs-settings-button.md` — settings-in-overflow-menu placement rule (v6.10+).
+- `../mini-apps-docs-viewport.md` — chrome-padding discipline and stable-height rule for bottom-pinned UI.
+- `../axhub-telegram-mobile-design.md` — accent-blue outgoing convention and the only type/spacing scale found (third-party, unverified).
+- `../tdesktop-day-blue-theme.md` — light-side default values for the mapped roles.
+- `../tdesktop-night-theme.md` — dark-side default values for the mapped roles.
+
+## Alternatives considered and rejected
+
+- Tai-only role names with no Telegram mapping: rejected — mapping to the industry's most-deployed chat theme vocabulary keeps defaults recognizable and reviewable.
+- Hardcoding Telegram hexes as constants: rejected — Telegram's own docs forbid it (values are user-themeable); samples are defaults, resolved at draw through roles.
+- Copying pixel geometry (10pt radii, 50pt CTA, 44px targets): rejected — pixel units have no terminal meaning; only relative emphasis and placement discipline transfer.
+- Light defaults for `section_*`/`subtitle`/`destructive` invented by symmetry: rejected — unpublished values stay explicitly deferred rather than guessed.
+
+## Risks / open questions
+
+- Exact default light-theme hexes for `section_*`, `subtitle`, and `destructive` are not published officially; only dark samples were observed.
+- The type/spacing scale rests entirely on a third-party iOS teardown, unverified against Android/Desktop, because no official spec exists.
+- The `WebViewColors` diagram (image-only, no alt data) was never inspected and may hold additional guidance.
+- The sibling back-button SDK page was listed as consulted but yielded no captured evidence; its details remain unarchived.
+
+## Action taken
+
+Nothing built yet: role resolution exists but chat uses only 6 of 12 roles, borders are hardcoded white, and no Telegram-derived defaults or section roles exist. This conclusion records the mapping and discipline to implement, not what shipped.
+
+## Amendment (2026-10-11): dedicated bubble roles added
+
+Bubble rendering needed roles the 12-role mapping could not carry without collisions: `bubble_in`, `bubble_out`, `bubble_fg`, `meta_in`, `meta_out`, `tick_read`, `service_bg`, `service_fg`, `unread`, `unread_muted` (dark/light from the tdesktop day/night files, nord/gruvbox mapped by tone, ansi in plain names; `register_theme` now requires all 22 roles). The 12-role mapping above still holds for everything else.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial conclusion recorded. |
+| 2026-10-11 | Amendment: 10 dedicated bubble/service/unread roles added (22 total). |
@@ -0,0 +1,49 @@
+# lipgloss package docs — raw colors, no role system
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | lipgloss package documentation (pkg.go.dev) |
+| Source URL | https://pkg.go.dev/github.com/charmbracelet/lipgloss |
+| Source publisher / author | Charm (lipgloss project) |
+| Source type | vendor docs |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+Lipgloss's API documentation shows a styling library with deliberately no role or theme system: it offers raw colors plus `AdaptiveColor` (separate Light/Dark values, auto-detected) and `CompleteColor` (per-terminal-profile values), leaving role structs to the user. Evidence for what tai should not copy wholesale — and for deferring adaptive color.
+
+## Key findings
+
+- No built-in theme roles: lipgloss provides color primitives and style composition; role groupings are user-defined structs.
+- `AdaptiveColor` carries separate Light and Dark values resolved by auto-detected terminal background; `CompleteColor` carries per-terminal-color-profile values.
+
+## Pros / strengths
+
+- `AdaptiveColor` is the cleanest light/dark primitive surveyed: two values plus background detection, no theme machinery required.
+- Demonstrates that a styling layer can ship without any role system and still succeed.
+
+## Cons / limitations / caveats
+
+- No registry, no switching, no roles — every theme-shaped need is left to the user, which is exactly the gap tai is filling.
+- lipgloss v2's `LightDark` successor to `AdaptiveColor` was seen in snippet only, not fetched — not claimed here.
+
+## Relevance to tai
+
+- Shapes the palette-role conclusion by negation (tai needs the roles lipgloss omits) and by deferral (the `AdaptiveColor` idea is recorded as a later enhancement, not v1 scope).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created from 2026-10-11 research-pass evidence (body opened via web_fetch by researching agent). |
@@ -0,0 +1,50 @@
+# Mini Apps SDK docs — MainButton and BackButton
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Main Button documentation (Telegram Mini Apps SDK docs) |
+| Source URL | https://docs.telegram-mini-apps.com/platform/main-button |
+| Source publisher / author | Telegram Mini Apps community (docs.telegram-mini-apps.com, over the official protocol) |
+| Source type | vendor docs |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+Community SDK documentation for the two primary Mini App buttons: the bottom full-width MainButton reserved for the final action (with text, active, progress, and color control), and the header BackButton, which carries visibility and click plumbing but deliberately no built-in navigation action.
+
+## Key findings
+
+- MainButton is a bottom full-width call-to-action for the final action, supporting text, active/disabled state, progress loader, and colors; for attachment-menu launches it stays hidden until the user interacts.
+- The class was renamed BottomButton with a SecondaryButton stacked above it, keeping the same bottom-CTA role.
+- BackButton is a header-left chevron with show/hide/onClick control and no built-in action: the developer handles every press.
+
+## Pros / strengths
+
+- Precise behavioral detail (hidden-until-interact, no-built-in-nav) that the official page states more tersely.
+- Documents the current BottomButton/SecondaryButton shape, not just the legacy MainButton name.
+
+## Cons / limitations / caveats
+
+- Community docs over the official protocol: may lag or drift from Telegram's own reference, so load-bearing behavior wants official corroboration.
+- The sibling back-button page was listed as consulted but no evidence from it was captured, so it is not archived here (open gap).
+
+## Relevance to tai
+
+Shapes tai's action-button grammar: one bottom primary action with active/progress states, a header back control with no implicit behavior, and hidden-until-relevant discipline for contextual actions.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,50 @@
+# Mini Apps SDK docs — SettingsButton
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Settings Button documentation (Telegram Mini Apps SDK docs) |
+| Source URL | https://docs.telegram-mini-apps.com/platform/settings-button |
+| Source publisher / author | Telegram Mini Apps community (docs.telegram-mini-apps.com, over the official protocol) |
+| Source type | vendor docs |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+Community SDK documentation for the Mini App Settings button: a top-right menu item that developers opt into showing, publicly available to all developers since version 6.10.
+
+## Key findings
+
+- The Settings button lives in the top-right menu of the Mini App chrome.
+- It is opt-in: the developer calls `show()` to make it appear.
+- It has been public to all developers since v6.10.
+
+## Pros / strengths
+
+- Settles placement (menu, not header button) and availability (opt-in, v6.10+) in three checkable facts.
+- Consistent with the official chrome inventory (Settings as context-menu item).
+
+## Cons / limitations / caveats
+
+- Community docs over the official protocol; thin page with no behavioral edge cases.
+- Version-pinned availability needs re-checking if tai ever targets older clients (it does not currently).
+
+## Relevance to tai
+
+Completes the header-action inventory: settings belongs in an overflow menu reached from the top-right, not as a permanent header button — a placement rule tai's own header actions should follow.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,50 @@
+# Mini Apps SDK docs — theming samples and re-read discipline
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Theming documentation (Telegram Mini Apps SDK docs) |
+| Source URL | https://docs.telegram-mini-apps.com/platform/theming |
+| Source publisher / author | Telegram Mini Apps community (docs.telegram-mini-apps.com, over the official protocol) |
+| Source type | vendor docs |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+Community SDK documentation for Mini App theming: representative dark-theme sample values for the core `ThemeParams` keys plus accent, section-header, and destructive samples, and the hard rule to never hardcode colors and always re-read theme parameters on change.
+
+## Key findings
+
+- Dark-theme samples: `bg_color #17212b`, `text_color #f5f5f5`, `hint_color #708499`, `link_color #6ab3f3`, `button_color #5288c1`.
+- Further dark samples: `accent_text_color #6ab2f2`, `section_header_text_color #6ab3f3`, `destructive_text_color #ec3942`.
+- Apps must never hardcode colors and must never cache them without refresh: re-read theme parameters and color scheme on every `themeChanged` event.
+
+## Pros / strengths
+
+- The only concrete sample values found for the `ThemeParams` keys, and they agree with the Desktop night theme file (`#17212b`, `#f5f5f5`).
+- The re-read discipline is stated as a hard rule, not advice, which settles tai's switch contract.
+
+## Cons / limitations / caveats
+
+- Dark samples only: exact default light-theme hexes for the `section_*`, `subtitle`, and `destructive` keys are not published officially (open gap).
+- Community docs; samples are representative values from a user-themeable system, not constants to bake in.
+
+## Relevance to tai
+
+Provides the dark defaults for tai's Telegram-derived theme roles and the never-hardcode/re-read-on-switch rule that `set_theme` plus full repaint already implements in spirit.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,52 @@
+# Mini Apps SDK docs — viewport, safe areas, fullscreen
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Viewport documentation (Telegram Mini Apps SDK docs) |
+| Source URL | https://docs.telegram-mini-apps.com/platform/viewport |
+| Source publisher / author | Telegram Mini Apps community (docs.telegram-mini-apps.com, over the official protocol) |
+| Source type | vendor docs |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+Community SDK documentation for the Mini App viewport: mobile apps open in a draggable bottom sheet, fullscreen removes the top and bottom bars, layout must pad for both the device safe area and Telegram's content safe area, and bottom-pinned UI must use the animation-stable height.
+
+## Key findings
+
+- Mobile Mini Apps open in a draggable BottomSheet; fullscreen mode removes the top and bottom bars.
+- Layout must pad for both `safeAreaInset` (notch, system navigation) and `contentSafeAreaInset` (Telegram's own chrome), especially in fullscreen.
+- Bottom-pinned UI must use `viewportStableHeight`; `viewportHeight` is animation-unsafe.
+- Apps must subscribe to `viewportChanged`, `safeAreaChanged`, and `contentSafeAreaChanged` rather than caching geometry.
+- The design baseline is mobile-first at 320-480px widths.
+
+## Pros / strengths
+
+- The only source found that separates the two insets (device vs Telegram chrome) with concrete padding guidance.
+- The stable-vs-live height distinction is an exact implementable rule for bottom-pinned elements.
+
+## Cons / limitations / caveats
+
+- Community docs over the official protocol; mobile-centric, with desktop viewport behavior thin.
+- Pixel and sheet metaphors do not transfer literally to a terminal; only the inset/rounding principles carry over.
+
+## Relevance to tai
+
+Supplies the chrome-padding discipline tai's scenes should mirror (reserve space for frame chrome, never draw under it, re-read geometry on resize events) and the stable-height rule behind tai's bottom-pinned status line.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,46 @@
+# pytermgui file_loaders reference — YAML/JSON style files
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | pytermgui file_loaders reference — config, markup, and widget files |
+| Source URL | https://ptg.bczsalba.com/reference/pytermgui/file_loaders/ |
+| Source publisher / author | bczsalba (pytermgui project) |
+| Source type | vendor docs |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A thin source with one finding: pytermgui loads YAML/JSON config, markup, and widget files through its `file_loaders` module, runnable via `ptg -f`. It exists here as the file-based-override precedent tai explicitly defers.
+
+## Key findings
+
+- YAML/JSON files define config, markup styles, and widget trees, loaded via the `file_loaders` module and runnable with `ptg -f`.
+
+## Pros / strengths
+
+- Shows file-based style overrides composing with a palette system with no registry changes.
+
+## Cons / limitations / caveats
+
+- Thin source: the merge semantics between file styles and the active palette were not part of the inspected evidence.
+
+## Relevance to tai
+
+- Precedent behind the palette-role conclusion's deferred file-override design (a partial role dict from TOML/JSON merged over a named theme, if ever added).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created from 2026-10-11 research-pass evidence (body opened via web_fetch by researching agent). |
@@ -0,0 +1,49 @@
+# pytermgui styling docs — global palette and live regenerate
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | pytermgui styling documentation — palette, tags, and widgets |
+| Source URL | https://github.com/bczsalba/pytermgui/blob/HEAD/docs/widgets/styling.md |
+| Source publisher / author | bczsalba (pytermgui project) |
+| Source type | vendor docs |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+The simplest theme model surveyed: one global palette regenerated live from a single primary color (`palette.regenerate(primary)`), shade offsets derived from it, and markup tags (`@bg`, `#auto`) resolving against the palette. The live-regenerate spirit is the portable idea.
+
+## Key findings
+
+- A single global palette regenerates live from one primary color via `palette.regenerate(primary)`; shades derive as offsets.
+- Markup tags (`@bg`, `#auto`) resolve colors against the current palette at render time.
+
+## Pros / strengths
+
+- Minimal possible theme API: one color in, whole palette out, live.
+- Tag-based palette resolution is the same resolve-at-draw idea as ratatui-kit's derivation, in markup form.
+
+## Cons / limitations / caveats
+
+- One primary color cannot express tai's semantic roles (success/warning/error/info need independent hues); tai needs the fuller role set.
+- pytermgui `NO_COLOR` support details were seen in snippet only, not fetched — not claimed here.
+
+## Relevance to tai
+
+- Contributes the live-regenerate spirit (a switch repaints everything immediately, via tai's full redraw) and the shade-offset idea to the palette-role conclusion; its single-primary limit is why tai adopts 12 roles instead.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created from 2026-10-11 research-pass evidence (body opened via web_fetch by researching agent). |
@@ -0,0 +1,49 @@
+# ratatui-kit theming docs — palette-as-source-of-truth resolution
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | ratatui-kit theming documentation — Palette, themes, Provider switching |
+| Source URL | https://github.com/yexiyue/ratatui-kit/blob/HEAD/docs/src/content/docs/core/theming.mdx |
+| Source publisher / author | yexiyue (ratatui-kit project) |
+| Source type | vendor docs |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+The best style-resolution pattern surveyed: a 16-slot `Palette` in 5 groups serves as the single source of truth, component themes derive via `FooTheme::from_palette`, and an `Atom` + `Provider` pair switches the active theme. The palette-derives-everything flow is what tai ports.
+
+## Key findings
+
+- One 16-slot `Palette` organized in 5 groups is the source of truth; component themes derive from it (`FooTheme::from_palette`).
+- Theme switching goes through an `Atom` + `Provider` pair that swaps the active theme for all derived styles.
+- The palette type is marked non-exhaustive, leaving room for the role set to grow.
+
+## Pros / strengths
+
+- Derive-don't-duplicate: components never hardcode colors, so a switch propagates everywhere by construction.
+- Non-exhaustive palette is the right growth story for a role set that will gain members.
+
+## Cons / limitations / caveats
+
+- The Atom/Provider reactivity machinery is framework-scale; tai ports the derivation direction (theme → styles at draw time), not the reactive plumbing.
+
+## Relevance to tai
+
+- Resolution pattern behind the palette-role conclusion: style objects store role names and resolve against the current theme at draw time, with raw colors as an escape hatch; the non-exhaustive lesson becomes tai's growth headroom.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created from 2026-10-11 research-pass evidence (body opened via web_fetch by researching agent). |
@@ -0,0 +1,50 @@
+# ratatui-themes README — minimal role palette with serde
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | ratatui-themes README — theme palette and registry |
+| Source URL | https://github.com/ricardodantas/ratatui-themes/blob/HEAD/README.md |
+| Source publisher / author | ricardodantas (ratatui-themes project) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+The closest minimal precedent to tai's planned design: a 10-role `ThemePalette` struct, a `ThemeName` enum registry with all/next/prev traversal, and serde serialization for file-backed themes. Small enough to port nearly whole.
+
+## Key findings
+
+- Theme contents are a 10-role `ThemePalette` struct — a fixed, small role set.
+- The registry is a `ThemeName` enum supporting all/next/prev traversal (listing and cycling).
+- Themes serialize via serde, enabling file-backed theme definitions.
+
+## Pros / strengths
+
+- Minimal-role palette plus enum registry plus cycling is almost exactly tai's target shape at a slightly smaller role count.
+- Serde support shows file-backed themes need no special machinery beyond serialization.
+
+## Cons / limitations / caveats
+
+- A Rust enum registry is less open than tai's planned string-keyed dict; user themes in tai register by name rather than by enum variant.
+- The 10-role set is fixed; tai's 12 roles plus growth headroom differ in detail.
+
+## Relevance to tai
+
+- Closest structural precedent for the palette-role conclusion: fixed small role set, named registry, next/prev cycling key, serialization-ready theme objects.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created from 2026-10-11 research-pass evidence (body opened via web_fetch by researching agent). |
@@ -0,0 +1,49 @@
+# send-rs src/tui/chat/chat_widget.rs — message list, scrollbar, dynamic input
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | send-rs src/tui/chat/chat_widget.rs — chat widget (WhatsApp+Telegram ratatui client) |
+| Source URL | https://raw.githubusercontent.com/pedromarquetti/send-rs/master/src/tui/chat/chat_widget.rs |
+| Source publisher / author | pedromarquetti (send-rs / Sender project) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+Message rendering as a `List` of pre-wrapped rows with an explicit 1-column scrollbar, a write box whose height grows from its visual row count, and a notable reverted experiment: right-aligned outgoing bubbles were tried and abandoned as ugly. The rejection is as valuable as the patterns.
+
+## Key findings
+
+- Messages render as a `List` of pre-wrapped rows with an explicit 1-column scrollbar.
+- The write box height is dynamic, derived from its visual row count (capped by config).
+- Right-aligned outgoing message bubbles were implemented and then reverted as ugly; all messages stay left-aligned rows.
+
+## Pros / strengths
+
+- Pre-wrapped rows plus an explicit scrollbar are simple and portable — no layout-engine support needed.
+- The documented bubble rejection settles a design argument with real-shipped-client evidence instead of taste.
+
+## Cons / limitations / caveats
+
+- No markdown, streaming, or tool-call rendering in the inspected evidence; the widget covers plain message rows only.
+
+## Relevance to tai
+
+- Decisive for the messaging-layout conclusion: tai renders left-aligned wrapped rows with sender grouping, not bubbles, and grows its input from visual rows — both directly from this source.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created from 2026-10-11 research-pass evidence (body opened via web_fetch by researching agent). |
@@ -0,0 +1,49 @@
+# send-rs src/config.rs — default keymap and input limits
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | send-rs src/config.rs — configuration defaults (WhatsApp+Telegram ratatui client) |
+| Source URL | https://raw.githubusercontent.com/pedromarquetti/send-rs/master/src/config.rs |
+| Source publisher / author | pedromarquetti (send-rs / Sender project) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+Default keybindings and input limits for a ratatui messaging client: Tab/Shift+Tab cycle panes, `i` focuses the write box, Enter selects/sends, with the write box capped at 5 visual lines. A thin source, but the defaults are the finding.
+
+## Key findings
+
+- Default pane keys: Tab / Shift+Tab cycle focus, `i` focuses the write box, Enter selects or sends, Shift+Enter inserts a newline, Esc dismisses, Ctrl+C quits.
+- Chat navigation uses `j`/`k`/`g`/`G` for scroll and top/bottom; `/` searches, `s` opens settings.
+- Write-box height is capped by `max_write_lines = 5`.
+
+## Pros / strengths
+
+- Sensible, conventional defaults (vim-ish navigation plus Tab cycling) that need no invention to adopt.
+- The 5-line input cap is a concrete number for a growing input box.
+
+## Cons / limitations / caveats
+
+- Keymap defaults only; no rationale is given for any choice, and configurability mechanics were not part of the inspected evidence.
+
+## Relevance to tai
+
+- Supplies the default keybindings (Tab cycle, `i`/Enter/Esc, Shift+Enter newline) and the 5-line input cap adopted in the messaging-layout conclusion.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created from 2026-10-11 research-pass evidence (body opened via web_fetch by researching agent). |
@@ -0,0 +1,49 @@
+# send-rs src/tui/mod.rs — main draw loop and pane split
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | send-rs src/tui/mod.rs — main draw function (WhatsApp+Telegram ratatui client) |
+| Source URL | https://raw.githubusercontent.com/pedromarquetti/send-rs/master/src/tui/mod.rs |
+| Source publisher / author | pedromarquetti (send-rs / Sender project) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+The top-level draw function of a ratatui messaging client: a vertical split giving the main area all but one row (`Fill(1)` + `Length(1)` status row) with the main area itself split 30/70 between chat list and conversation. The focused pane gets a provider-accent border; unfocused panes do not.
+
+## Key findings
+
+- `draw_main` splits vertically into `Fill(1)` main content plus a `Length(1)` status row, then splits the main area horizontally 30% / 70%.
+- Only the focused pane carries a provider-accent border; inactive panes render without the accent, making focus visible at a glance.
+
+## Pros / strengths
+
+- Clean separation of layout (this file) from focus state, status content, and message rendering (sibling modules), so each piece can be studied alone.
+- Focus-indicating border accent is a cheap, effective focus signal worth copying.
+
+## Cons / limitations / caveats
+
+- This file alone shows only the split skeleton; focus, status text, and message rows live in sibling modules and must be read with it.
+- No narrow-terminal breakpoint; the 30/70 split is unconditional.
+
+## Relevance to tai
+
+- Confirms the 30/70 + 1-line-status skeleton as the shared convention across inspected ratatui messaging clients, and contributes the focused-pane-accent pattern to the messaging-layout conclusion.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created from 2026-10-11 research-pass evidence (body opened via web_fetch by researching agent). |
@@ -0,0 +1,48 @@
+# send-rs src/tui/state.rs — focus model and draft retention
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | send-rs src/tui/state.rs — focus state (WhatsApp+Telegram ratatui client) |
+| Source URL | https://raw.githubusercontent.com/pedromarquetti/send-rs/master/src/tui/state.rs |
+| Source publisher / author | pedromarquetti (send-rs / Sender project) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A four-variant focus enum (`ChatList` / `Chat` / `Write` / `Popup`) with a `cycle_focus` routine that saves per-chat `TextArea` drafts when focus moves away. Focus is explicit application state, not derived from widget identity.
+
+## Key findings
+
+- Focus is an explicit enum with four variants: `ChatList`, `Chat`, `Write`, `Popup`.
+- `cycle_focus` saves the current per-chat `TextArea` draft before moving focus, so partially typed messages survive pane switches and chat switches.
+
+## Pros / strengths
+
+- Explicit focus enum makes per-focus status hints, keymaps, and border accents all keyed off one value — simple to port.
+- Draft retention on focus move is the correct behavior for a chat input and is handled at the focus layer rather than per widget.
+
+## Cons / limitations / caveats
+
+- A fixed four-variant enum is less general than tai's traversal-ordered focus chain; porting the idea means mapping variants onto tai's focusable panels, not copying the enum.
+
+## Relevance to tai
+
+- Contributes the explicit-focus-state plus per-chat draft-retention pattern to the messaging-layout conclusion; tai's chat scene needs the same draft behavior on its `TextBox`-based input.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created from 2026-10-11 research-pass evidence (body opened via web_fetch by researching agent). |
@@ -0,0 +1,48 @@
+# send-rs src/tui/status_bar.rs — per-focus hints and transient overrides
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | send-rs src/tui/status_bar.rs — status bar content (WhatsApp+Telegram ratatui client) |
+| Source URL | https://raw.githubusercontent.com/pedromarquetti/send-rs/master/src/tui/status_bar.rs |
+| Source publisher / author | pedromarquetti (send-rs / Sender project) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A one-line status bar showing `[chat]` plus key hints for the current focus, with transient status messages (rate-limit countdowns, window blur, backend status, disconnects) temporarily overriding the hints. Content policy and override behavior are the whole finding.
+
+## Key findings
+
+- Normal content is `[chat] ` followed by per-focus key hints that change with the focus enum.
+- A transient `status_hint` (rate-limit countdown, window-blur notice, backend status, disconnect notice) overrides the hints while present, then the hints return.
+
+## Pros / strengths
+
+- The override pattern keeps one status line serving two jobs (teaching keys + reporting state) without layout churn.
+- Per-focus hints make modal/focused UIs self-documenting.
+
+## Cons / limitations / caveats
+
+- Override timing and queueing (what happens when two transient states overlap) were not part of the inspected evidence.
+
+## Relevance to tai
+
+- Contributes the per-focus-hints plus transient-override content policy for tai's 1-line status bar in the messaging-layout conclusion.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created from 2026-10-11 research-pass evidence (body opened via web_fetch by researching agent). |
@@ -0,0 +1,57 @@
+# Telegram Desktop day-blue theme file (day-blue.tdesktop-theme)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | day-blue.tdesktop-theme (Telegram Desktop built-in Day theme) |
+| Source URL | https://raw.githubusercontent.com/telegramdesktop/tdesktop/dev/Telegram/Resources/day-blue.tdesktop-theme |
+| Source publisher / author | Telegram Desktop contributors (tdesktop project) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+The authoritative built-in light theme for Telegram Desktop: white incoming bubbles against pale-blue outgoing bubbles, grey/blue in-bubble timestamps, translucent service pills, and a fixed 8-hue peer palette for sender names and avatars. Every value below is an exact hex from the file.
+
+## Key findings
+
+- Message bubbles: incoming `msgInBg #ffffff`, outgoing `msgOutBg #def1fd`; selected-bubble overlay `#bbe1fc`; bubble shadows `#748ea229` / `#0d5a911a`.
+- Message text is near-black (`windowFg`) on both bubble sides.
+- In-bubble time color: incoming `#a0acb6`, outgoing `#86a8c2`.
+- Service pills (date dividers, service messages): `msgServiceBg #00518059`; date pills render `{month} {day}` or `{month} {day}, {year}`.
+- Unread bar: background `#fcfbfa`, foreground `#538bb4`.
+- Chat-list unread pill: `#40a7e3`, muted `#bbbbbb`, white text; name `#222`, snippet `#999`.
+- Group sender-name peer palette (8 hues): red `#c03d33`, green `#4fad2d`, yellow `#d09306`, blue `#168acd`, purple `#8544d6`, pink `#cd4073`, sea `#2996ad`, orange `#ce671b`; the same hues in different tones drive avatar gradients.
+- Top bar background and compose background are white.
+
+## Pros / strengths
+
+- Authoritative source: the actual shipped built-in theme, not a teardown or guess.
+- Exact hexes for every role, with a matching night file so day/night pairs can be compared key by key.
+- The 8-hue peer palette is the canonical answer for sender-name coloring.
+
+## Cons / limitations / caveats
+
+- Desktop only: iOS, Android, and Web default hexes were not verified against this file and may differ.
+- A key/value theme file carries no geometry: bubble corner radii, paddings, inter-message spacing, and tail shape are not in evidence from this source.
+- Key semantics have to be inferred from names; the file alone does not say how each key is rendered.
+
+## Relevance to tai
+
+Canonical light-theme defaults for the Telegram look-and-feel decisions: bubble/ink/time hexes, service-pill treatment, unread-pill colors, and the peer-name palette tai's chat scene should mirror (as rows, per the rows-not-bubbles decision).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,54 @@
+# Telegram Desktop language strings (lang.strings)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | lang.strings (Telegram Desktop UI string table) |
+| Source URL | https://raw.githubusercontent.com/telegramdesktop/tdesktop/dev/Telegram/Resources/langs/lang.strings |
+| Source publisher / author | Telegram Desktop contributors (tdesktop project) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+The literal UI copy Telegram Desktop ships: the full last-seen scale, the unread-bar phrasing, the composer placeholder and its broadcast variants, attach-menu and bot-keyboard labels, and reply/edit affordance strings. The canonical wording reference for every Telegram-look label tai adopts.
+
+## Key findings
+
+- Status line vocabulary: `online`, `typing...`, and the last-seen scale `last seen just now` / `today` / `yesterday at {time}` / `recently` / `within a week` / `within a month` / `a long time ago`.
+- Unread bar copy: `{count} Unread Message(s)` and `Unread messages`.
+- Composer placeholder: `Write a message...`, with Broadcast, Silent-broadcast, and Schedule variants.
+- Attach entry labeled `Add attachment` (photo/video, file, camera, ...); emoji/sticker/gif picker and Send beside the field.
+- Bot affordances: a command/keyboard toggle with `Show/Hide bot keyboard`, and a bot menu button labeled `Menu`.
+- Reply preview bar carries a `Reply` header with a quoted snippet and a close control; the edit field placeholder is `New message...`; quote-selected-text is supported.
+
+## Pros / strengths
+
+- Literal shipped copy: no paraphrase risk, every label verifiable character-for-character.
+- Covers the whole header/composer/status surface in one file, so wording stays mutually consistent.
+
+## Cons / limitations / caveats
+
+- Strings without layout context: order, truncation, and placement need the client code.
+- Desktop wording; mobile clients may phrase some labels differently (not verified).
+- Chat-list time/date formatting rules and snippet truncation behavior were not captured (open gap).
+
+## Relevance to tai
+
+The copy sheet for tai's Telegram-look surfaces: header status strings, unread bar, composer placeholder, and bot affordance labels should use this wording verbatim rather than tai-invented paraphrases.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,56 @@
+# Telegram Desktop night theme file (night.tdesktop-theme)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | night.tdesktop-theme (Telegram Desktop built-in Night theme) |
+| Source URL | https://raw.githubusercontent.com/telegramdesktop/tdesktop/dev/Telegram/Resources/night.tdesktop-theme |
+| Source publisher / author | Telegram Desktop contributors (tdesktop project) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+The authoritative built-in dark theme for Telegram Desktop: dark-slate incoming bubbles against muted-blue outgoing bubbles, light in-bubble timestamps, near-transparent shadows, and brighter re-tones of the same 8-hue peer palette. Pairs key-by-key with the day file.
+
+## Key findings
+
+- Message bubbles: incoming `msgInBg #182533`, outgoing `msgOutBg #2b5278`; selected-bubble overlay `#2e70a5`; shadows near-transparent.
+- Message text is near-white incoming (`#f5f5f5`-ish) and white outgoing.
+- In-bubble time color: incoming `#6d7f8f`, outgoing `#7da8d3`.
+- Service pills: `msgServiceBg #213040d5`.
+- Chat-list unread pill ("badge"): `#4082bc`, muted `#3e546a`, white text; name `#f5f5f5`, snippet `#7f91a4`, date `#8696a8`.
+- Group sender-name peer palette (night re-tones): red `#fb6169`, green `#85de85`, yellow `#f3bc5c`, blue `#65bdf3`, purple `#b48bf2`, pink `#ff5694`, sea `#62d4e3`, orange `#faa357`.
+- Top bar background and compose background are `#17212b`.
+
+## Pros / strengths
+
+- Authoritative source: the actual shipped built-in dark theme.
+- Exact hexes that pair with the day file, so every role has a verified light and dark default.
+- Confirms the peer palette survives re-toning across schemes rather than being replaced.
+
+## Cons / limitations / caveats
+
+- Desktop only: iOS, Android, and Web dark defaults were not verified against this file.
+- No geometry (radii, paddings, spacing, tail shape) is in evidence from this source.
+- Key semantics inferred from names; rendering behavior needs the client code.
+
+## Relevance to tai
+
+Canonical dark-theme defaults for the Telegram look-and-feel decisions, and the dark half of every day/night role pair tai's theme defaults should carry.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,50 @@
+# TechMesto — Telegram checkmarks explainer
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Telegram checkmarks explainer (TechMesto) |
+| Source URL | https://www.techmesto.com/telegram-checkmarks/ |
+| Source publisher / author | TechMesto (third party) |
+| Source type | blog post |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A third-party explainer of Telegram's message-state glyphs, consistent with the official FAQ: clock while sending, checks that turn blue on read, and the eye-plus-view-count treatment used by channels instead of checks.
+
+## Key findings
+
+- A clock icon marks a message still sending.
+- Check marks turn blue once the message is read.
+- Channels use an eye icon plus a view count rather than per-recipient checks.
+
+## Pros / strengths
+
+- Corroborates the official check semantics from an independent angle.
+- The channel eye-plus-views detail fills a gap the FAQ subset did not cover.
+
+## Cons / limitations / caveats
+
+- Third-party explainer, not authoritative: useful as corroboration, not as the primary basis for any claim.
+- Thin page with no client-version pinning; wording may drift from current clients.
+
+## Relevance to tai
+
+Confirms the glyph set tai's transcript rows need (clock, checks with a read color, eye+count for broadcast-style views) without inventing any new states.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,51 @@
+# telecli src/tui.rs — chat layout and modal keys
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | telecli src/tui.rs — ratatui/crossterm Telegram client TUI |
+| Source URL | https://raw.githubusercontent.com/s3r1msultan/telecli/main/src/tui.rs |
+| Source publisher / author | s3r1msultan (telecli project) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A single-file ratatui Telegram client UI: a fixed 30/70 horizontal split with a chat list plus 3-row help bar on the left and messages plus a 3-row input on the right, a 1-line status overlay at the bottom, and modal Normal/Input key handling. There is no resize handling.
+
+## Key findings
+
+- Layout is a fixed horizontal `Percentage(30)` / `Percentage(70)` split; left pane holds a chat `List` plus a 3-row help bar, right pane holds messages (`Min(0)`) plus a `Length(3)` input.
+- Status is drawn as a 1-line bottom overlay rect showing `status | Mode`.
+- Modal keys: `j`/`k`/Up/Down navigate chats, `i`/Enter enters input mode, Esc cancels, Enter sends, `s`/`w` or PgUp/PgDn scroll by 10 lines, `r` refreshes, `?` shows hints, `q` then `y`/`n` quits.
+- Messages render as rows of the form `-> text [HH:MM]`; outgoing messages are green.
+
+## Pros / strengths
+
+- Minimal complete precedent for a Telegram-like layout in a single file: split ratios, pane contents, and status overlay are all directly copyable numbers.
+- Modal Normal/Input separation keeps chat navigation keys from colliding with typing.
+
+## Cons / limitations / caveats
+
+- No resize or narrow-terminal handling at all; the 30/70 split is unconditional.
+- Single-file scope means no theming, no focus-cycle across panes, no streaming or markdown handling to learn from.
+
+## Relevance to tai
+
+- Supplies the base layout numbers for tai's chat scene (30/70 split, 3-row input, 1-line status overlay) and the modal Normal/Input key pattern adopted in the messaging-layout conclusion.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created from 2026-10-11 research-pass evidence (body opened via web_fetch by researching agent). |
@@ -0,0 +1,53 @@
+# Telegram Android ChatMessageCell — bubble grouping, tails, in-bubble metadata
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | ChatMessageCell.java (Telegram Android message cell) |
+| Source URL | https://raw.githubusercontent.com/DrKLO/Telegram/master/TMessagesProj/src/main/java/org/telegram/ui/Cells/ChatMessageCell.java |
+| Source publisher / author | Telegram (DrKLO/Telegram, official Android client) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+The actual Android implementation of message grouping and in-bubble metadata: consecutive same-sender messages join via position flags with squared inner corners, the tail appears only on the last message of a group, and the timestamp sits at the bubble's bottom-right with the sender's checks immediately after.
+
+## Key findings
+
+- Joined message groups use `POSITION_FLAG` top/bottom/left/right combinations; inner (joined) corners are squared.
+- The bubble tail renders only on the last message of a consecutive same-sender group.
+- Timestamp is bottom-right inside the bubble (`timeX = backgroundWidth - dp(4) - timeWidth`); on own messages the checks render immediately after the time.
+- Group sender names are header-colored from the 8-hue peer palette.
+- Incoming bubbles sit left, outgoing right; the in/out key split holds across clients.
+
+## Pros / strengths
+
+- Ground-truth grouping and tail logic straight from the shipped renderer.
+- Exact time-placement formula leaves no ambiguity about metadata position.
+
+## Cons / limitations / caveats
+
+- Android only; tail side, corner radii, paddings, and inter-message spacing per client were not captured (open gap).
+- Media-bubble time-overlay details were not captured (open gap).
+- The class is large; only the grouping/tail/metadata subset was synthesized.
+
+## Relevance to tai
+
+Defines the grouping grammar tai keeps even without bubbles (join consecutive same-sender rows, metadata at the row's trailing end, peer-hue sender names) and the bubble geometry tai deliberately does not need.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,53 @@
+# Telegram Android DialogCell — chat-list row rendering
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | tui-framework-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | DialogCell.java (Telegram Android chat-list row cell) |
+| Source URL | https://raw.githubusercontent.com/DrKLO/Telegram/master/TMessagesProj/src/main/java/org/telegram/ui/Cells/DialogCell.java |
+| Source publisher / author | Telegram (DrKLO/Telegram, official Android client) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+The actual Android implementation of a chat-list row: circular avatar, bold name with time at right, second-line snippet with sender/service prefixes and own-message checks or clock, unread pill with pin/mute overlays, red `Draft:` prefix, and typing status rendered in action blue over the snippet.
+
+## Key findings
+
+- Circular avatar with radius 26dp; bold chat name on the left, time on the right.
+- Second line is a snippet with group-sender or service-message prefixes; own latest message is preceded by its checks or clock icon.
+- Unread count renders as a pill at the right; the pin icon replaces or overlaps the count area; a mute (bell-off) icon sits after the name.
+- Typing or voice-recording status replaces the snippet in action blue (`key_chats_actionMessage`).
+- Unsent draft text is prefixed with `Draft:` in red (`key_chats_draft`).
+
+## Pros / strengths
+
+- Real shipped implementation, not a design mock: every element's presence and relative placement is ground truth for Android.
+- Theme-key references (`key_chats_actionMessage`, `key_chats_draft`) tie each element to the theming system.
+
+## Cons / limitations / caveats
+
+- Android only; Desktop and iOS row geometry was not verified against this class.
+- Chat-list time/date formatting rules and snippet truncation logic were not captured from this source (open gap).
+- One class of a large client: surrounding list behavior (grouping, archives, folders) was not mined.
+
+## Relevance to tai
+
+The element inventory for tai's sidebar rows: avatar slot, name plus time, snippet with status prefixes, unread pill, pin/mute markers, draft-red and typing-blue overrides — the rich-row target tai's plain-name list must grow into.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
--- a/Show More
+++ b/Show More