docs: add new page in docs - Flags

docs/root/flags.rst

@@ -2,3 +2,63 @@
 
 Флаги вводимых команд
 =====================
+
+Флаги (или параметры) — это специальные аргументы, которые конечный юзер может добавлять к командам, чтобы управлять их поведением. 
+
+Синтаксис флагов
+-----------------
+
+Обобщённый синтаксис выглядит так:
+
+.. code-block:: py
+
+   <command_name> <flag_prefix: Literal['-', '--', '---']><flag_name> <flag_value: Optional>
+
+То есть, у флага обязательно должен быть префикс, который может быть одним, двум или трем минусам. После префикса следует имя флага, без
+пробела, после, через пробел, идёт значение флага, если оно есть.
+
+Два типа флагов
+---------------
+
+Флаги бывают двух основных видов: без значений (переключатели) и со значениями. ``Argenta`` позволяет регистрировать и вводить флаги обоих типов в любой последовательности  для одной команды.
+
+.. note::
+    Ошибки валидации значений являются пассивными, их не нужно обрабатывать явно. У каждого инстанса :ref:`InputFlag <root_api_command_input_flag>` есть поле ``status``, по которому можно определить результат валидации флага. **Конкретная реализация и описание API вы можете найти в разделе** :ref:`Flag <root_api_command_flag>`.
+
+При регистрации флага вы можете указать допустимые для него значения, по умолчанию любое введённое значение для флага будет валидным. Допустимые значения можно указать различными способами:
+
+Ограничение по списку возможных значений
+----------------------------------------
+
+Вы можете заранее определить список допустимых значений для флага.
+
+**Пример:**
+
+Предположим, у вас есть флаг ``--format``, который может принимать только значения ``json`` или ``xml``.
+
+.. code-block:: bash
+
+   # Эта команда сработает
+   export --format json
+
+   # А эта вызовет ошибку валидации, так как "csv" нет в списке разрешённых
+   export --format csv
+
+Проверка с помощью регулярных выражений
+-----------------------------------------
+
+Для более сложных проверок вы можете использовать регулярные выражения. Это особенно полезно, когда значение должно соответствовать определённому формату, например, быть email-адресом, датой или номером телефона.
+
+**Пример:**
+
+Допустим, флаг ``--email`` должен принимать только корректные email-адреса.
+
+.. code-block:: bash
+
+   # Сработает, так как значение соответствует формату email
+   send --email "user@example.com"
+
+   # Вызовет ошибку валидации, так как "user_example.com" — некорректный email
+   send --email "user_example.com"
+
+Встроенная валидация избавляет вас от необходимости писать ручные проверки и делает ваш код более декларативным.