Update documentation and code snippets

docs/root/api/command/input_flag.rst

@@ -30,7 +30,7 @@ InputFlag
 
 .. py:attribute:: input_value
 
-   Значение, переданное с флагом. Может быть `None` для флагов без значений.
+   Значение, переданное с флагом. Может быть ``''`` (пустой строкой) для флагов без значений.
 
 .. py:attribute:: status
    :no-index:

docs/root/api/orchestrator/argparser.rst

@@ -44,7 +44,7 @@ ArgParser
 Лучшие практики
 ---------------
 
-Использовать атрибут ``parsed_argspace`` рекомендуется только на этапе настройки приложения. В обработчиках лучшей практикой является получение ``ArgSpace`` через DI. Подробнее см. :ref:`здесь <root_dependency_injection>`.
+Использовать атрибут ``parsed_argspace`` рекомендуется только на этапе настройки приложения. В обработчиках лучшей практикой является получение ``ArgSpace`` через ``di``. Подробнее см. :ref:`здесь <root_dependency_injection>`.
 
 **Пример использования:**
 

docs/root/api/orchestrator/index.rst

@@ -28,7 +28,7 @@ Orchestrator
 Создаёт и конфигурирует экземпляр ``Orchestrator``.
 
 * ``arg_parser``: Экземпляр ``ArgParser``, отвечающий за парсинг аргументов командной строки при запуске скрипта (не путать с командами в интерактивном режиме).
-* ``custom_providers``: Список пользовательских провайдеров ``dishka.Provider`` для добавления ваших сервисов (например, подключений к БД или API-клиентов) в DI-контейнер.
+* ``custom_providers``: Список пользовательских провайдеров ``dishka.Provider`` для добавления ваших сервисов (например, подключений к БД или API-клиентов) в di-контейнер.
 * ``auto_inject_handlers``: Если **True** (по умолчанию), ``dishka`` автоматически внедрит зависимости в обработчики команд, инспектируя их сигнатуры.
 
 -----

docs/root/dependency_injection.rst

@@ -3,9 +3,9 @@
 Внедрение зависимостей
 =======================
 
-Внедрение зависимостей (Dependency Injection, DI) — это паттерн проектирования, который помогает писать слабосвязанный, легко тестируемый и расширяемый код. Вместо того чтобы обработчики сами создавали нужные им объекты (зависимости), они получают их извне.
+Внедрение зависимостей (Dependency Injection, ``di`` ) — это паттерн проектирования, который помогает писать слабосвязанный, легко тестируемый и расширяемый код. Вместо того чтобы обработчики сами создавали нужные им объекты (зависимости), они получают их извне.
 
-``Argenta`` использует библиотеку ``dishka`` для реализации DI, что позволяет декларативно объявлять зависимости прямо в сигнатурах ваших обработчиков.
+``Argenta`` использует библиотеку ``dishka`` для реализации ``di``, что позволяет декларативно объявлять зависимости прямо в сигнатурах ваших обработчиков.
 Подробнее о **DI**, **IoC** и API для создания провайдеров можно прочитать в `официальной документации dishka <https://dishka.readthedocs.io/en/stable/di_intro.html>`_.
 
 -----
@@ -32,7 +32,10 @@
    :language: python
    :linenos:
    
-После создания провайдера его необходимо зарегистрировать в оркестраторе:
+После создания провайдера его необходимо зарегистрировать в оркестраторе.
+
+.. note::
+   Провайдеры регистрируются в ``Orchestrator``, а не в ``App``, так как оркестратор отвечает за настройку di-контейнера на уровне всего приложения. Вы можете передать список из нескольких провайдеров через параметр ``custom_providers``.
 
 **Пример использования:**
 
@@ -45,7 +48,7 @@
 Как это работает?
 -----------------
 
-В основе DI в Argenta лежат **провайдеры** и **контейнер**.
+В основе ``di`` в Argenta лежат **провайдеры** и **контейнер**.
 
 *   **Провайдер (Provider)** — это "рецепт", который объясняет, как создавать и настраивать ту или иную зависимость (например, подключение к БД, API-клиент или любой другой сервис).
 *   **Контейнер (IoC Container)** — это "фабрика", которая хранит все рецепты (провайдеры) и по запросу создаёт и выдаёт готовые зависимости.
@@ -68,7 +71,7 @@
 Обмен данными между обработчиками
 ----------------------------------
 
-Помимо DI, обработчики могут обмениваться данными в рамках сессии через **объект контекста**. В ``Argenta`` эту роль выполняет объект ``DataBridge``.
+Помимо ``di``, обработчики могут обмениваться данными в рамках сессии через **объект контекста**. В ``Argenta`` эту роль выполняет объект ``DataBridge``.
 
 Каждый обработчик может записывать в него данные, а также читать, обновлять и удалять их.
 

docs/root/flags.rst

@@ -1,7 +1,7 @@
 .. _root_flags:
 
-Флаги вводимых команд
-=====================
+Флаги команд
+============
 
 Флаги — это специальные параметры, которые пользователь может добавлять к командам для управления их поведением. 
 
@@ -56,6 +56,36 @@
 
 Флаг состоит из префикса (``-``, ``--`` или ``---``), имени и, опционально, значения, которое указывается через пробел.
 
+**Примеры:**
+
+.. code-block:: shell
+
+   greet --name John        # Flag with value
+   deploy --verbose         # Flag without value (switch)
+   backup -f --compress     # Several flags
+
+-----
+
+Работа с флагами в обработчиках
+--------------------------------
+
+Чтобы получить значение флага в обработчике, используйте объект ``response.input_flags`` типа :ref:`InputFlags <root_api_command_input_flags>`.
+
+**Пример с флагом, имеющим значение:**
+
+.. literalinclude:: ../code_snippets/flags/greet_handler.py
+   :language: python
+   :linenos:
+
+**Пример с флагом-переключателем:**
+
+.. literalinclude:: ../code_snippets/flags/deploy_handler.py
+   :language: python
+   :linenos:
+
+.. seealso::
+   Подробнее о работе с объектом ``InputFlags`` см. в разделе :ref:`InputFlags <root_api_command_input_flags>`.
+
 -----
 
 Два типа флагов

docs/root/quickstart.rst

@@ -23,6 +23,14 @@
    :language: python
    :linenos:
 
+**Запуск**
+
+Сохраните код в файл (например, ``main.py``) и запустите:
+
+.. code-block:: shell
+
+    python main.py
+
 **Результат**
 
 .. image:: https://i.ibb.co/35q24Bh8/image.png
@@ -30,10 +38,30 @@
    
 -----
 
-Более сложный пример: Менеджер задач
+Промежуточный пример: Калькулятор с флагами
+--------------------------------------------
+
+Прежде чем перейти к сложному примеру с ``di``, рассмотрим промежуточный вариант — калькулятор, который использует флаги для управления поведением.
+
+.. literalinclude:: ../code_snippets/quickstart/calculator_app.py
+   :language: python
+   :linenos:
+
+**Использование:**
+
+.. code-block:: shell
+
+   calc --a 10 --b 5 --operation add    # Result: 15.0
+   calc --a 10 --b 5 --operation mul    # Result: 50.0
+
+Этот пример показывает, как работать с флагами без использования ``di``. Теперь перейдём к более сложному примеру.
+
+-----
+
+Сложный пример: Менеджер задач с ``di``
 --------------------------------------
 
-В этом руководстве мы создадим простое, но полнофункциональное CLI-приложение «Менеджер задач», которое продемонстрирует ключевые возможности Argenta.
+В этом руководстве мы создадим полнофункциональное CLI-приложение «Менеджер задач», которое продемонстрирует работу с внедрением зависимостей.
 
 1. **Установка**
 

docs/root/redirect_stdout.rst

@@ -7,6 +7,20 @@
 
 -----
 
+Когда нужно отключать перехват stdout
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Отключайте перехват ``stdout`` (``disable_redirect_stdout=True`` в ``Router``), если ваши команды:
+
+✓ Используют ``input()`` для интерактивного ввода данных от пользователя
+✓ Используют прогресс-бары (``tqdm``, ``rich.progress``)
+✓ Выводят данные в реальном времени (streaming, логи)
+✓ Используют библиотеки, которые напрямую работают с ``stdout``
+
+Для обычных команд с ``print()`` перехват можно оставить включённым — это не влияет на их работу.
+
+-----
+
 Механизм перехвата ``stdout``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~