MTUCI-RAG-Example/support_files/codex_files/skills/rio-docs-researcher/SKILL.md

name, description

name	description
rio-docs-researcher	Use when researching, implementing, or debugging Python Rio UI components, layouts, themes, uploads, Markdown rendering, or Rio launch configuration. Verify APIs against the project's installed Rio version.

Rio Docs Researcher

Scope and authorization

Support the user's requested Rio work with version-matched evidence. Rio is a Python UI framework: use its component, state and session APIs rather than assuming HTML or React conventions.

If the user requests only research or a plan, remain read-only. If implementation or a fix is already requested or approved, research the relevant APIs and continue within that authorization. This skill does not require a second approval or a separate report before an authorized edit. Do not change workflows, deploy, upgrade Rio or send external messages merely to research an interface.

Establish the actual API

• Identify the project interpreter, installed rio-ui version, dependencies, entry point and rio.toml. Use the project's virtual environment, not an unrelated global Python. Reuse established facts unless the environment changed.
• Start with the relevant official documentation at https://rio-ui.dev/docs. Open the specific feature page, not only the home page.
• If the documentation needs JavaScript or cannot be fetched, use an available browser or inspect the installed Rio package. Do not repeatedly retry inaccessible pages or claim their contents were verified.
• Confirm version-sensitive names and signatures using the installed package's source, annotations or inspect.signature. Current online documentation may describe a newer release. For executable code, the installed version's API is decisive; explain any disagreement with current docs.
• Inspect only the APIs relevant to the task: layout, styling, state updates, callbacks, file handling, Markdown or launch commands. Label evidence as documentation, installed source, runtime observation or inference.
• Never invent a parameter. If neither source nor documentation establishes support, mark it «не подтверждено» and use a verified alternative.

For a small fix, summarize only consequential findings and limitations. For an explicitly requested research report, include version/context, verified API signatures, source links, relevant examples, limitations and open questions. Do not force a fixed eight-section report on ordinary implementation work.

Version-sensitive Rio pitfalls

The following were observed with rio-ui 0.12.2; recheck them on other versions rather than treating them as universal rules.

• MultiLineTextInput does not accept the confirm_mode parameter shown in some newer docs.
• Named Text.style values are heading1, heading2, heading3, text and dim. Use supported text properties or TextStyle for custom typography; do not invent heading4.
• Components must be constructed inside Rio's build context. Direct instantiation in a unit test can fail before the behavior under test runs. Test non-UI logic separately and verify actual rendering in a browser. Inspect dependencies before relying on rio.testing.
• FilePickerArea(multiple=True) accepts multiple files, but delivers a FilePickEvent per file. It mutates its own files list before callbacks; pass a fresh list derived from application state. In single-file replacement, the new pick can arrive before removal of the old file. Remove by identity and preserve unrelated validation errors.
• Extension filters are picker hints. Validate each file's extension, metadata size and emptiness before reading, and actual byte length before sending.
• await FileInfo.read_bytes() can close its underlying stream. Preserve bytes for a manual retry of a failed transfer; release them after success/removal. Keep successful files out of a retry queue. For batch uploads, snapshot the collection and queue, prevent duplicate submission, show progress, and distinguish partial success from complete success.
• rio.Markdown(text, overflow="wrap", scroll_code_x="auto") renders formatted replies. Keep plain user input as Text unless rich input is requested. Verify headings, lists, links and code in a real browser; test long code and narrow screens. Do not assume raw HTML sanitization or link behavior without checking the renderer when relevant.
• Layout dimensions use Rio units rather than CSS pixels. Confirm responsive behavior using the real window dimensions and screenshots; do not infer it from a successful import. Check supported sizing properties before using max_width or similar names.

HTTP and settings

Keep webhook URLs and credentials on the server. Derive payload fields, response types and error semantics from the actual backend contract. A text reply is not necessarily JSON. An upload returning 2xx does not establish that indexing finished; do not invent completion or specialist-handoff states that the backend does not expose.

Avoid automatic retries of potentially duplicating operations unless the backend supplies idempotency or the user requests an appropriate retry policy. A timeout can leave an unknown server outcome even if the UI reports a failure.

If .env loading is requested, resolve its path relative to the application rather than the current working directory, document precedence and restart requirements, exclude private configuration from Git, and provide a sanitized example. Do not bake a particular project's webhook addresses into this skill or a reusable template.

Run and verify

• In a 0.12.2 website project, rio.toml uses app-type = "website". Verify the entry module as well.
• python -m rio run --port 8765 --release disables Rio's developer sidebar in this version. The port is an example; use the project's actual port. Restart the running process and refresh the browser when verifying a release-mode change.
• Do not infer command syntax from another CLI. If a help invocation fails, inspect Rio's installed CLI implementation rather than repeating guessed flags.
• Rio may load icons/fonts and write to a user cache. Distinguish sandbox/cache permission errors from application defects. Use the permitted execution mechanism; do not disable security protections or rewrite the UI to hide an unexplained error.
• Verify the authorized change with focused behavioral tests and, for visual work, a browser check. For upload queues, test mixed valid/invalid files, partial failure, retained retry bytes, and duplicate clicks. Use mock HTTP responses for failure scenarios; live uploads require authorization and change backend data.
• Keep temporary preview data and mock responses out of production code. Stop temporary preview servers, reset browser viewport overrides, and report what was tested versus what remains unverified.

Official entry points

Use these as starting points, not as proof of a successful read:

• Components and lifecycle: https://rio-ui.dev/docs/howto/component-lifecycle
• Text and styling: https://rio-ui.dev/docs/api/text and https://rio-ui.dev/docs/api/textstyle
• Layout containers: https://rio-ui.dev/docs/api/rectangle and https://rio-ui.dev/docs/api/scrollcontainer
• File selection: https://rio-ui.dev/docs/api/filepickerarea and https://rio-ui.dev/docs/api/fileinfo
• Markdown: https://rio-ui.dev/docs/api/markdown
• Deployment: https://rio-ui.dev/docs/howto/deployment

When writing files on Windows, preserve UTF-8 and read them back with an explicit encoding. Replacement characters in headings are damaged content, not translated instructions.