docs: add beginner workflow guides

landing/.gitignore

@@ -5,6 +5,7 @@ node_modules
 .env
 --host/
 product-docs/.vitepress/dist/
+product-docs/.vitepress/cache/
 
 # Large video files
 public/video/*.mp4

landing/product-docs/.vitepress/config.ts

@@ -40,6 +40,7 @@ const rootGuide: DefaultTheme.SidebarItem[] = [
     text: "Start",
     items: [
       { text: "Installation", link: "/guide/installation" },
+      { text: "Beginner workflow", link: "/guide/beginner-workflow" },
       { text: "Quickstart", link: "/guide/quickstart" },
       { text: "Runtime setup", link: "/guide/runtime-setup" }
     ]
@@ -47,7 +48,10 @@ const rootGuide: DefaultTheme.SidebarItem[] = [
   {
     text: "Guide",
     items: [
-      { text: "Create a team", link: "/guide/create-team" },
+      { text: "Create your first team", link: "/guide/create-first-team" },
+      { text: "Run and monitor work", link: "/guide/run-and-monitor-work" },
+      { text: "Review and approve", link: "/guide/review-and-approve" },
+      { text: "Team configuration", link: "/guide/create-team" },
       { text: "Agent workflow", link: "/guide/agent-workflow" },
       { text: "Code review", link: "/guide/code-review" },
       { text: "MCP integration", link: "/guide/mcp-integration" },
@@ -83,6 +87,7 @@ const ruGuide: DefaultTheme.SidebarItem[] = [
     text: "Старт",
     items: [
       { text: "Установка", link: "/ru/guide/installation" },
+      { text: "Путь новичка", link: "/ru/guide/beginner-workflow" },
       { text: "Быстрый старт", link: "/ru/guide/quickstart" },
       { text: "Настройка рантайма", link: "/ru/guide/runtime-setup" }
     ]
@@ -90,7 +95,10 @@ const ruGuide: DefaultTheme.SidebarItem[] = [
   {
     text: "Руководство",
     items: [
-      { text: "Создание команды", link: "/ru/guide/create-team" },
+      { text: "Создать первую команду", link: "/ru/guide/create-first-team" },
+      { text: "Запуск и мониторинг", link: "/ru/guide/run-and-monitor-work" },
+      { text: "Проверка и approval", link: "/ru/guide/review-and-approve" },
+      { text: "Настройка команды", link: "/ru/guide/create-team" },
       { text: "Работа агентов", link: "/ru/guide/agent-workflow" },
       { text: "Код-ревью", link: "/ru/guide/code-review" },
       { text: "Интеграция MCP", link: "/ru/guide/mcp-integration" },
@@ -122,7 +130,7 @@ const ruGuide: DefaultTheme.SidebarItem[] = [
 ];
 
 const rootNav: DefaultTheme.NavItem[] = [
-  { text: "Guide", link: "/guide/quickstart", activeMatch: "^/guide/(?!troubleshooting(?:/|$))" },
+  { text: "Guide", link: "/guide/beginner-workflow", activeMatch: "^/guide/(?!troubleshooting(?:/|$))" },
   { text: "Developers", link: "/developers/", activeMatch: "^/developers/" },
   { text: "Reference", link: "/reference/concepts", activeMatch: "^/reference/" },
   {
@@ -136,7 +144,7 @@ const rootNav: DefaultTheme.NavItem[] = [
 const ruNav: DefaultTheme.NavItem[] = [
   {
     text: "Руководство",
-    link: "/ru/guide/quickstart",
+    link: "/ru/guide/beginner-workflow",
     activeMatch: "^/ru/guide/(?!troubleshooting(?:/|$))"
   },
   { text: "Разработчикам", link: "/ru/developers/", activeMatch: "^/ru/developers/" },

landing/product-docs/.vitepress/theme/DocsCardGrid.vue

@@ -20,10 +20,12 @@ const cards = computed(() => {
           { icon: "?", title: "FAQ", desc: "Короткие ответы на частые вопросы.", link: "/ru/reference/faq" }
         ]
       : [
-          { icon: "01", title: "Быстрый старт", desc: "Поставить приложение и создать первую команду.", link: "/ru/guide/quickstart" },
-          { icon: "02", title: "Установка", desc: "Платформы, релизы и запуск из исходников.", link: "/ru/guide/installation" },
-          { icon: "03", title: "Создание команды", desc: "Роли, lead prompt и границы работы.", link: "/ru/guide/create-team" },
-          { icon: "04", title: "Код-ревью", desc: "Проверка изменений по задачам и hunk-level decisions.", link: "/ru/guide/code-review" }
+          { icon: "01", title: "Путь новичка", desc: "Понять весь первый запуск от проекта до approval.", link: "/ru/guide/beginner-workflow" },
+          { icon: "02", title: "Быстрый старт", desc: "Поставить приложение и проверить базовый запуск.", link: "/ru/guide/quickstart" },
+          { icon: "03", title: "Первая команда", desc: "Lead, builder, reviewer, роли, модели и Worktree.", link: "/ru/guide/create-first-team" },
+          { icon: "04", title: "Запуск работы", desc: "Brief для lead, task board, comments и monitoring.", link: "/ru/guide/run-and-monitor-work" },
+          { icon: "05", title: "Review и approval", desc: "Task detail, logs, diff и hunk-level decisions.", link: "/ru/guide/review-and-approve" },
+          { icon: "06", title: "Рантаймы", desc: "Claude, Codex, OpenCode и multimodel setup.", link: "/ru/guide/runtime-setup" }
         ];
   }
 
@@ -36,10 +38,12 @@ const cards = computed(() => {
         { icon: "?", title: "FAQ", desc: "Short answers to common questions.", link: "/reference/faq" }
       ]
     : [
-        { icon: "01", title: "Quickstart", desc: "Install the app and create your first team.", link: "/guide/quickstart" },
-        { icon: "02", title: "Installation", desc: "Platforms, releases, and running from source.", link: "/guide/installation" },
-        { icon: "03", title: "Create a team", desc: "Roles, lead prompt, and task boundaries.", link: "/guide/create-team" },
-        { icon: "04", title: "Code review", desc: "Review task changes with hunk-level decisions.", link: "/guide/code-review" }
+        { icon: "01", title: "Beginner workflow", desc: "Understand the first run from project to approval.", link: "/guide/beginner-workflow" },
+        { icon: "02", title: "Quickstart", desc: "Install the app and validate the base launch.", link: "/guide/quickstart" },
+        { icon: "03", title: "First team", desc: "Lead, builder, reviewer, roles, models, and Worktree.", link: "/guide/create-first-team" },
+        { icon: "04", title: "Run work", desc: "Lead brief, task board, comments, and monitoring.", link: "/guide/run-and-monitor-work" },
+        { icon: "05", title: "Review and approve", desc: "Task detail, logs, diff, and hunk-level decisions.", link: "/guide/review-and-approve" },
+        { icon: "06", title: "Runtime setup", desc: "Claude, Codex, OpenCode, and multimodel setup.", link: "/guide/runtime-setup" }
       ];
 });
 </script>

landing/product-docs/guide/beginner-workflow.md

@@ -0,0 +1,108 @@
+---
+title: "Beginner Workflow - Agent Teams Docs"
+description: "A structured first-run path for new users. Learn the project, team, task board, task detail, and review surfaces before launching larger teams."
+---
+
+# Beginner Workflow
+
+Use this path when you are new to Agent Teams and want a clear sequence from "open the app" to "approve useful work".
+
+The first run should prove four things:
+
+1. The app can open your project.
+2. A small team can launch with the selected runtime.
+3. Tasks move through the board in a visible way.
+4. You can review and approve changes before they are treated as done.
+
+## The basic model
+
+Agent Teams has four working surfaces:
+
+| Surface | What you do there |
+| --- | --- |
+| Project and team selector | Pick the project and the team that will work on it. |
+| Team editor | Name the team, add members, choose roles, models, and worktree settings. |
+| Task board | Watch work move through Todo, In Progress, Review, Done, and Approved. |
+| Task detail and review | Read the task, inspect logs, check changes, and approve or request fixes. |
+
+<ZoomImage src="/screenshots/guides/task-board-annotated.png" alt="Annotated Agent Teams task board" caption="The board is the main operating surface after launch: messages, columns, review cards, and the task list stay visible together." />
+
+## Recommended guide order
+
+Follow these guides in order for the first successful run:
+
+1. [Create your first team](/guide/create-first-team) - set up a small lead-builder-reviewer team.
+2. [Run and monitor work](/guide/run-and-monitor-work) - give the lead a concrete goal and watch the task board.
+3. [Review and approve](/guide/review-and-approve) - inspect task details, logs, and code changes.
+4. [Troubleshooting](/guide/troubleshooting) - use this if launch, messages, or task logs do not look healthy.
+
+## Before you launch
+
+Start with a Git-tracked project and a known baseline:
+
+```bash
+git status --short
+```
+
+You do not need a perfectly clean tree, but you should know which files are already changed. That makes review safer after agents start editing.
+
+For the first run, keep the team small:
+
+| Member | Good first responsibility |
+| --- | --- |
+| Lead | Split the goal into tasks and coordinate status. |
+| Builder | Implement scoped tasks. |
+| Reviewer | Review completed tasks and ask for fixes. |
+
+Avoid launching many teammates at once. More agents increase logs, concurrent edits, provider usage, and review load.
+
+## First goal template
+
+Use a goal that has clear scope, boundaries, and verification:
+
+```text
+Improve the documentation quickstart. Keep edits inside landing/product-docs, add practical examples, preserve existing VitePress syntax, and run `pnpm --dir landing docs:build` before marking tasks done.
+```
+
+Good first goals are specific, testable, and limited to a known area. Avoid prompts like "make the app better" until you understand the workflow.
+
+## What healthy progress looks like
+
+During a healthy run:
+
+- The lead creates small tasks rather than one huge task.
+- Each teammate posts a plan or progress comment.
+- Work moves from Todo to In Progress.
+- Finished work moves to Review before approval.
+- The task detail shows the description, attachments, changes, and execution logs.
+- The final comment includes the verification command and result.
+
+## When to intervene
+
+Intervene when a task is vague, too broad, blocked, or missing verification. Use a task comment when the message belongs to one task. Use a direct message when you need to redirect a teammate or the lead.
+
+Common intervention prompts:
+
+```text
+Split this into smaller tasks. Each task should have a narrow file scope and a clear verification step.
+```
+
+```text
+Before continuing, post the files you plan to change and the command you will run to verify the result.
+```
+
+```text
+This task is too broad. Keep the change inside the docs guide pages and avoid touching app runtime code.
+```
+
+## Completion checklist
+
+Before you call the first run successful, verify:
+
+- The team launched without runtime errors.
+- At least one task moved through Review.
+- You inspected the task diff.
+- The result comment includes a verification result.
+- You understand which files changed and why.
+
+Then continue to [Create your first team](/guide/create-first-team).

landing/product-docs/guide/create-first-team.md

@@ -0,0 +1,111 @@
+---
+title: "Create Your First Team - Agent Teams Docs"
+description: "Step-by-step setup for a first Agent Teams team with lead, builder, reviewer, roles, models, worktree isolation, and a clear launch brief."
+---
+
+# Create Your First Team
+
+This guide walks through the first team setup. The goal is not to build the biggest team possible. The goal is to create a small team that launches reliably and produces reviewable tasks.
+
+## 1. Open the target project
+
+Open the project you want agents to work in. Prefer a Git-tracked project so Agent Teams can show diffs, task-linked changes, and review state.
+
+Before launching, check the baseline:
+
+```bash
+git status --short
+```
+
+If there are existing user changes, keep them in mind during review. Agent Teams can work in a dirty tree, but review is clearer when you know what existed before launch.
+
+## 2. Create the team
+
+Use the team selector, then create a new team for the current project. Give it a short operational name, such as `docs-onboarding`, `landing-fixes`, or `runtime-audit`.
+
+<ZoomImage src="/screenshots/guides/create-team-annotated.png" alt="Annotated Create Team dialog" caption="Create Team: name the team, add members, choose roles and models, then enable Worktree only when you want isolated Git worktrees." />
+
+## 3. Start with three roles
+
+Use this first-team shape:
+
+| Role | Responsibility | Why it helps |
+| --- | --- | --- |
+| Lead | Splits the goal into tasks, assigns owners, tracks blockers. | Keeps work coordinated. |
+| Builder | Implements scoped tasks. | Produces the actual change. |
+| Reviewer | Reviews completed tasks and asks for fixes. | Prevents unreviewed output from being treated as complete. |
+
+You can add specialists later. For the first run, a small team is easier to debug and review.
+
+## 4. Choose provider and model per member
+
+Each member needs a provider and model. Use the most reliable runtime for the lead, because the lead controls task breakdown and coordination.
+
+Common first setup:
+
+| Member | Suggested provider style |
+| --- | --- |
+| Lead | The most reliable model you have available. |
+| Builder | A fast model that can handle scoped implementation. |
+| Reviewer | A careful model with stronger reasoning. |
+
+If a provider is missing, fix runtime setup before launching. See [Runtime setup](/guide/runtime-setup).
+
+## 5. Decide on Worktree
+
+Enable **Worktree** when teammates may edit the same repository in parallel and you want Git isolation. Keep it off for a very small first run if you want the simplest setup.
+
+Use Worktree when:
+
+- multiple teammates can edit code at the same time
+- you want cleaner diffs per member
+- the project is already Git-tracked
+
+Avoid Worktree when:
+
+- the project is not a Git repo
+- you are only testing the UI flow
+- you want the fewest moving parts for the first launch
+
+## 6. Write member instructions
+
+Give each member a short workflow. The member prompt should describe responsibility, not the whole project.
+
+Lead example:
+
+```text
+Split the user goal into small tasks. Assign clear owners, avoid broad refactors, keep task comments updated, and request review before approval.
+```
+
+Builder example:
+
+```text
+Implement only the assigned task. Keep changes scoped, post the files you changed, and include the verification command and result before marking work complete.
+```
+
+Reviewer example:
+
+```text
+Review completed tasks for correctness, regressions, missing tests, and scope creep. Ask for fixes with specific comments before approving.
+```
+
+## 7. Launch with a narrow goal
+
+Use a launch brief with outcome, scope, boundaries, and verification:
+
+```text
+Improve the docs onboarding path. Keep changes inside landing/product-docs. Create a beginner-friendly guide sequence, add practical examples, preserve VitePress syntax, and run `pnpm --dir landing docs:build`.
+```
+
+## 8. Confirm the launch is healthy
+
+After launch:
+
+- The lead should create tasks.
+- At least one teammate should start a task.
+- The board should show movement into In Progress.
+- Task comments or logs should show what the teammate is doing.
+
+If launch hangs or no tasks appear, go to [Troubleshooting](/guide/troubleshooting#team-does-not-launch).
+
+Next: [Run and monitor work](/guide/run-and-monitor-work).

landing/product-docs/guide/review-and-approve.md

@@ -0,0 +1,88 @@
+---
+title: "Review and Approve - Agent Teams Docs"
+description: "A beginner-friendly review workflow for task details, execution logs, code changes, hunk decisions, approvals, and fix requests."
+---
+
+# Review and Approve
+
+Do not treat agent work as finished until you have checked the task result, logs, and changes. Review is where you keep quality and scope under control.
+
+## 1. Open the task
+
+Start from a task in Review or Done. Read the title, owner, status, and description first.
+
+<ZoomImage src="/screenshots/guides/task-detail-annotated.png" alt="Annotated task detail view for review" caption="Start with the task description, then check attachments, changes, and execution logs before approving anything." />
+
+Look for:
+
+- a clear task goal
+- files or areas that match the requested scope
+- a final comment from the teammate
+- a verification command and result
+
+## 2. Check execution evidence
+
+Execution Logs answer the basic trust questions:
+
+| Question | What to look for |
+| --- | --- |
+| Did the agent actually work on this task? | Tool calls, comments, and status changes inside the task timeline. |
+| Did it run verification? | Build, test, lint, or docs commands with visible results. |
+| Did it coordinate with others? | Messages or comments that explain handoffs and blockers. |
+| Did it touch unexpected files? | Changes that do not match the task description. |
+
+If logs and final comment disagree, ask for clarification before approving.
+
+## 3. Review the diff
+
+Open **Changes** and inspect each changed file.
+
+<ZoomImage src="/screenshots/guides/code-review-annotated.png" alt="Annotated code review screen with changed files, Accept All, and hunk actions" caption="Review each file first. Use Accept All only after you understand the diff. Keep or undo individual hunks when only part of a change is correct." />
+
+Use this order:
+
+1. Read the file list.
+2. Open each changed file.
+3. Check whether the changes match the task.
+4. Keep correct hunks.
+5. Undo or reject risky hunks.
+6. Approve only after all important files are reviewed.
+
+## 4. Request fixes clearly
+
+When something is wrong, do not just reject the task. Leave a specific fix request:
+
+```text
+Please keep the copy improvements, but revert the unrelated runtime wording in the provider table. Add the `pnpm --dir landing docs:build` result before resubmitting.
+```
+
+Good fix requests name:
+
+- what to keep
+- what to change
+- what to avoid
+- what verification is required
+
+## 5. Approve only when the result is complete
+
+Approve when:
+
+- the task scope is satisfied
+- the diff matches the task
+- verification passed or the missing verification is explicitly justified
+- no unrelated changes are mixed in
+- comments explain important decisions
+
+If the task changed docs or UI, also open the relevant page or app screen before approval.
+
+## 6. Final checklist
+
+Before closing the review:
+
+- Files changed are expected.
+- The task has a final result comment.
+- Verification result is present.
+- Risky hunks were checked individually.
+- The lead or reviewer marked the task approved.
+
+If anything is unclear, request changes instead of approving.

landing/product-docs/guide/run-and-monitor-work.md

@@ -0,0 +1,100 @@
+---
+title: "Run and Monitor Work - Agent Teams Docs"
+description: "Learn how to brief the lead, read the task board, use messages and comments, open task details, and keep agent work moving."
+---
+
+# Run and Monitor Work
+
+After the team launches, your job is to keep the work visible, scoped, and reviewable. The board is the main operating surface.
+
+## 1. Brief the lead clearly
+
+The lead needs a goal that can be split into tasks. Include:
+
+- the outcome
+- the allowed files or product area
+- what not to touch
+- verification commands
+- when to ask for review
+
+Good brief:
+
+```text
+Create a beginner docs path. Keep edits inside landing/product-docs. Add screenshots where they clarify actions. Do not touch runtime code. Run `pnpm --dir landing docs:build` before marking tasks complete.
+```
+
+Weak brief:
+
+```text
+Improve docs.
+```
+
+The weak brief can work, but it gives the lead too much freedom and makes review harder.
+
+## 2. Read the board by lane
+
+<ZoomImage src="/screenshots/guides/task-board-annotated.png" alt="Annotated task board with messages, kanban lanes, review cards, and task list" caption="Use the board to scan messages, task state, review-ready work, and the right-side task list without opening raw files." />
+
+| Lane | What it means | What you should do |
+| --- | --- | --- |
+| Todo | Tasks exist but are not active yet. | Check whether task titles are specific enough. |
+| In Progress | A teammate is actively working. | Watch for updates and avoid assigning duplicate work. |
+| Review | Work needs inspection. | Open the task and review changes. |
+| Done | Work is completed but may still need review flow. | Confirm review state before trusting it. |
+| Approved | Review passed. | Treat as completed output. |
+
+## 3. Use messages and comments deliberately
+
+Use task comments for task-specific context:
+
+```text
+Please keep this task scoped to the quickstart page. Do not change runtime setup wording in this pass.
+```
+
+Use direct messages for coordination:
+
+```text
+Lead, pause new task creation until the current review queue is cleared.
+```
+
+Prefer task comments when possible. They stay attached to the work and make review easier.
+
+## 4. Open task detail when a card needs attention
+
+Open the task detail when:
+
+- the title is too vague
+- the task has been in progress too long
+- the task is ready for review
+- the output mentions files you did not expect
+- you need to inspect attachments, changes, or logs
+
+<ZoomImage src="/screenshots/guides/task-detail-annotated.png" alt="Annotated task detail view with description, attachments, changes, and execution logs" caption="Task detail is where you confirm the task scope, attached context, changed files, and runtime evidence." />
+
+## 5. Keep work unblocked
+
+If a teammate is blocked, ask for the smallest next step:
+
+```text
+Post the blocker, the file or command involved, and the next action you need from the lead or user.
+```
+
+If the task is too large, ask the lead to split it:
+
+```text
+Split this into separate tasks for copy edits, screenshot assets, and navigation updates. Keep each task independently reviewable.
+```
+
+## 6. Decide when to stop the team
+
+Stop or pause when:
+
+- the review queue is larger than you can inspect
+- the lead creates vague tasks repeatedly
+- runtime errors appear in multiple tasks
+- agents start editing unrelated files
+- verification is missing from completed work
+
+You can always relaunch after tightening the brief.
+
+Next: [Review and approve](/guide/review-and-approve).

landing/product-docs/index.md

@@ -8,8 +8,8 @@ hero:
   tagline: Create teams, watch work move across a kanban board, review code changes, and coordinate Claude, Codex, OpenCode, and multimodel workflows without giving up local control.
   actions:
     - theme: brand
-      text: Quickstart
-      link: /guide/quickstart
+      text: Beginner workflow
+      link: /guide/beginner-workflow
     - theme: alt
       text: Install
       link: /guide/installation
@@ -62,6 +62,10 @@ Agent Teams is a free desktop app for orchestrating AI agent teams. You are not
 After creating your first team, explore these guides to go further:
 
 - **Runtime setup** - configure Claude, Codex, OpenCode, or multimodel providers: [Configure runtimes](/guide/runtime-setup)
+- **Beginner workflow** - follow the complete first-run path from project to approval: [Start the walkthrough](/guide/beginner-workflow)
+- **Create your first team** - set up lead, builder, reviewer, roles, models, and Worktree: [Create the team](/guide/create-first-team)
+- **Run and monitor work** - read the board, comments, task detail, and logs: [Run the team](/guide/run-and-monitor-work)
+- **Review and approve** - inspect task results and code changes before approval: [Review work](/guide/review-and-approve)
 - **Agent workflow** - understand how agents coordinate through the task board: [Understand workflow](/guide/agent-workflow)
 - **Team brief examples** - learn prompt patterns from real-world briefs: [See examples](/guide/team-brief-examples)
 - **Code review** - inspect diffs, accept or reject changes: [Review changes](/guide/code-review)
@@ -77,4 +81,4 @@ Use the reference pages when you need exact terminology, provider behavior, cont
 
 ## Product preview
 
-<ZoomImage src="/screenshots/1.jpg" alt="Agent Teams kanban board" caption="Task status, teammate activity, and review workflow stay visible in one workspace." />
+<ZoomImage src="/screenshots/product-preview.jpg" alt="Agent Teams kanban board" caption="Task status, teammate activity, and review workflow stay visible in one workspace." />

landing/product-docs/ru/guide/beginner-workflow.md

@@ -0,0 +1,109 @@
+---
+title: "Путь новичка - Документация Agent Teams"
+description: "Структурированный первый запуск для новых пользователей: проект, команда, доска задач, карточка задачи и ревью."
+lang: ru-RU
+---
+
+# Путь новичка
+
+Этот маршрут нужен, если вы впервые открыли Agent Teams и хотите пройти путь от запуска приложения до безопасного approval результата.
+
+Первый запуск должен доказать четыре вещи:
+
+1. Приложение открывает ваш проект.
+2. Небольшая команда запускается с выбранным runtime.
+3. Задачи двигаются по доске и их состояние видно.
+4. Вы можете проверить изменения до approval.
+
+## Базовая модель
+
+В Agent Teams есть четыре основные рабочие поверхности:
+
+| Поверхность | Что там делать |
+| --- | --- |
+| Project и team selector | Выбрать проект и команду, которая будет в нём работать. |
+| Team editor | Назвать команду, добавить участников, выбрать роли, модели и worktree-настройки. |
+| Task board | Смотреть, как задачи проходят Todo, In Progress, Review, Done и Approved. |
+| Task detail и review | Читать задачу, проверять логи, смотреть изменения и approve/request fixes. |
+
+<ZoomImage src="/screenshots/guides/task-board-annotated.png" alt="Аннотированная доска задач Agent Teams" caption="Доска - главная рабочая поверхность после запуска: сообщения, колонки, review-карточки и список задач видны вместе." />
+
+## Рекомендуемый порядок гайдов
+
+Для первого успешного запуска идите в таком порядке:
+
+1. [Создать первую команду](/ru/guide/create-first-team) - собрать небольшую команду lead-builder-reviewer.
+2. [Запустить и отслеживать работу](/ru/guide/run-and-monitor-work) - дать lead конкретную цель и следить за task board.
+3. [Проверить и approve](/ru/guide/review-and-approve) - проверить task detail, logs и code changes.
+4. [Диагностика](/ru/guide/troubleshooting) - если запуск, сообщения или task logs выглядят неправильно.
+
+## Перед запуском
+
+Начинайте с Git-проекта и понятного baseline:
+
+```bash
+git status --short
+```
+
+Чистое дерево не обязательно, но важно понимать, какие изменения уже были до запуска агентов.
+
+Для первого запуска держите команду маленькой:
+
+| Участник | Первая ответственность |
+| --- | --- |
+| Lead | Разбивает цель на задачи и координирует статус. |
+| Builder | Делает ограниченные implementation tasks. |
+| Reviewer | Проверяет завершённые задачи и просит исправления. |
+
+Не запускайте сразу много участников. Больше агентов - больше логов, параллельных правок, provider usage и review-нагрузки.
+
+## Шаблон первой цели
+
+Цель должна иметь scope, границы и verification:
+
+```text
+Improve the documentation quickstart. Keep edits inside landing/product-docs, add practical examples, preserve existing VitePress syntax, and run `pnpm --dir landing docs:build` before marking tasks done.
+```
+
+Хорошая первая цель конкретная, проверяемая и ограничена известной областью.
+
+## Как выглядит здоровый прогресс
+
+В здоровом запуске:
+
+- lead создаёт маленькие задачи, а не одну огромную
+- каждый teammate пишет план или progress comment
+- работа двигается из Todo в In Progress
+- завершённая работа попадает в Review до approval
+- task detail показывает description, attachments, changes и execution logs
+- финальный comment содержит verification command и result
+
+## Когда вмешиваться
+
+Вмешивайтесь, если задача слишком широкая, размытая, заблокирована или без verification. Пишите task comment, если сообщение относится к конкретной задаче. Пишите direct message, если надо перенаправить teammate или lead.
+
+Примеры:
+
+```text
+Split this into smaller tasks. Each task should have a narrow file scope and a clear verification step.
+```
+
+```text
+Before continuing, post the files you plan to change and the command you will run to verify the result.
+```
+
+```text
+This task is too broad. Keep the change inside the docs guide pages and avoid touching app runtime code.
+```
+
+## Checklist завершения
+
+Первый запуск можно считать успешным, если:
+
+- команда запустилась без runtime errors
+- хотя бы одна задача прошла через Review
+- вы открыли и проверили diff
+- result comment содержит verification result
+- понятно, какие файлы изменились и почему
+
+Дальше: [Создать первую команду](/ru/guide/create-first-team).

landing/product-docs/ru/guide/create-first-team.md

@@ -0,0 +1,112 @@
+---
+title: "Создать первую команду - Документация Agent Teams"
+description: "Пошаговая настройка первой команды: lead, builder, reviewer, роли, модели, worktree isolation и launch brief."
+lang: ru-RU
+---
+
+# Создать первую команду
+
+Цель первого setup - не собрать самую большую команду, а создать маленькую команду, которая стабильно запускается и делает reviewable tasks.
+
+## 1. Откройте проект
+
+Откройте проект, в котором агенты будут работать. Лучше использовать Git-проект, чтобы Agent Teams мог показывать diff, task-linked changes и review state.
+
+Перед запуском проверьте baseline:
+
+```bash
+git status --short
+```
+
+Если уже есть ваши изменения, учитывайте их при review.
+
+## 2. Создайте команду
+
+Через team selector создайте новую команду для текущего проекта. Название держите коротким и рабочим: `docs-onboarding`, `landing-fixes`, `runtime-audit`.
+
+<ZoomImage src="/screenshots/guides/create-team-annotated.png" alt="Аннотированный диалог Create Team" caption="Create Team: назовите команду, добавьте участников, выберите роли и модели, затем включайте Worktree только если нужна Git-изоляция." />
+
+## 3. Начните с трёх ролей
+
+Рекомендуемая первая форма команды:
+
+| Роль | Ответственность | Зачем |
+| --- | --- | --- |
+| Lead | Делит цель на задачи, назначает owners, отслеживает blockers. | Держит работу скоординированной. |
+| Builder | Делает scoped implementation tasks. | Создаёт основное изменение. |
+| Reviewer | Проверяет completed tasks и просит fixes. | Не даёт непроверенному результату стать финальным. |
+
+Специалистов можно добавить позже. Для первого запуска маленькую команду легче диагностировать и ревьюить.
+
+## 4. Выберите provider и model для каждого
+
+Каждому участнику нужен provider и model. Для lead выбирайте самый надёжный runtime, потому что lead управляет decomposition и coordination.
+
+Обычная первая настройка:
+
+| Участник | Какой provider выбрать |
+| --- | --- |
+| Lead | Самую надёжную модель из доступных. |
+| Builder | Быструю модель для scoped implementation. |
+| Reviewer | Более аккуратную модель с сильным reasoning. |
+
+Если provider отсутствует, сначала исправьте runtime setup: [Настройка рантайма](/ru/guide/runtime-setup).
+
+## 5. Решите, нужен ли Worktree
+
+Включайте **Worktree**, когда участники могут параллельно менять один репозиторий и нужна Git-изоляция. Для самого простого первого запуска можно оставить выключенным.
+
+Worktree полезен, когда:
+
+- несколько teammates могут одновременно менять код
+- нужны более чистые diffs по участникам
+- проект уже является Git-репозиторием
+
+Не включайте Worktree, если:
+
+- проект не в Git
+- вы только проверяете UI flow
+- хотите минимум движущихся частей в первом запуске
+
+## 6. Напишите инструкции участникам
+
+Member prompt должен описывать ответственность участника, а не весь проект.
+
+Lead:
+
+```text
+Split the user goal into small tasks. Assign clear owners, avoid broad refactors, keep task comments updated, and request review before approval.
+```
+
+Builder:
+
+```text
+Implement only the assigned task. Keep changes scoped, post the files you changed, and include the verification command and result before marking work complete.
+```
+
+Reviewer:
+
+```text
+Review completed tasks for correctness, regressions, missing tests, and scope creep. Ask for fixes with specific comments before approving.
+```
+
+## 7. Запустите с узкой целью
+
+Launch brief должен содержать outcome, scope, boundaries и verification:
+
+```text
+Improve the docs onboarding path. Keep changes inside landing/product-docs. Create a beginner-friendly guide sequence, add practical examples, preserve VitePress syntax, and run `pnpm --dir landing docs:build`.
+```
+
+## 8. Проверьте, что запуск здоровый
+
+После запуска:
+
+- lead создаёт задачи
+- хотя бы один teammate начинает задачу
+- board показывает движение в In Progress
+- task comments или logs показывают, что делает teammate
+
+Если запуск завис или задач нет, откройте [Диагностику](/ru/guide/troubleshooting#team-does-not-launch).
+
+Дальше: [Запустить и отслеживать работу](/ru/guide/run-and-monitor-work).

landing/product-docs/ru/guide/review-and-approve.md

@@ -0,0 +1,89 @@
+---
+title: "Проверить и approve - Документация Agent Teams"
+description: "Понятный workflow ревью: task detail, execution logs, code changes, hunk decisions, approvals и fix requests."
+lang: ru-RU
+---
+
+# Проверить и approve
+
+Не считайте работу агента завершённой, пока не проверили результат задачи, logs и changes. Review удерживает качество и scope.
+
+## 1. Откройте задачу
+
+Начните с задачи в Review или Done. Сначала прочитайте title, owner, status и description.
+
+<ZoomImage src="/screenshots/guides/task-detail-annotated.png" alt="Аннотированный task detail для review" caption="Начните с task description, затем проверьте attachments, changes и execution logs до approval." />
+
+Проверьте:
+
+- понятная ли цель задачи
+- совпадают ли файлы с ожидаемым scope
+- есть ли final comment от teammate
+- есть ли verification command и result
+
+## 2. Проверьте execution evidence
+
+Execution Logs отвечают на базовые вопросы доверия:
+
+| Вопрос | Что искать |
+| --- | --- |
+| Агент реально работал над этой задачей? | Tool calls, comments и status changes внутри task timeline. |
+| Он запускал verification? | Build, test, lint или docs commands с результатом. |
+| Он координировался с другими? | Messages или comments с handoffs и blockers. |
+| Он трогал неожиданные файлы? | Changes, которые не совпадают с task description. |
+
+Если logs и final comment расходятся, попросите уточнение до approval.
+
+## 3. Проверьте diff
+
+Откройте **Changes** и просмотрите каждый changed file.
+
+<ZoomImage src="/screenshots/guides/code-review-annotated.png" alt="Аннотированный code review screen с changed files, Accept All и hunk actions" caption="Сначала проверьте каждый file. Accept All используйте только после понимания diff. Keep или undo применяйте для отдельных hunks." />
+
+Порядок:
+
+1. Прочитать file list.
+2. Открыть каждый changed file.
+3. Проверить, что изменения совпадают с задачей.
+4. Keep для правильных hunks.
+5. Undo или reject для рискованных hunks.
+6. Approve только после проверки важных files.
+
+## 4. Просите fixes конкретно
+
+Если что-то не так, не ограничивайтесь reject. Оставьте конкретный fix request:
+
+```text
+Please keep the copy improvements, but revert the unrelated runtime wording in the provider table. Add the `pnpm --dir landing docs:build` result before resubmitting.
+```
+
+Хороший fix request называет:
+
+- что оставить
+- что изменить
+- чего избегать
+- какая verification обязательна
+
+## 5. Approve только полный результат
+
+Approve уместен, когда:
+
+- task scope закрыт
+- diff совпадает с задачей
+- verification прошёл или отсутствие verification объяснено
+- нет unrelated changes
+- comments объясняют важные решения
+
+Если task менял docs или UI, перед approval откройте соответствующую страницу или экран приложения.
+
+## 6. Финальный checklist
+
+Перед закрытием review:
+
+- изменённые files ожидаемые
+- есть final result comment
+- есть verification result
+- risky hunks проверены отдельно
+- lead или reviewer поставил approved
+
+Если что-то непонятно, request changes лучше, чем approve.

landing/product-docs/ru/guide/run-and-monitor-work.md

@@ -0,0 +1,101 @@
+---
+title: "Запустить и отслеживать работу - Документация Agent Teams"
+description: "Как дать lead понятный brief, читать task board, использовать messages и comments, открывать task detail и удерживать работу в движении."
+lang: ru-RU
+---
+
+# Запустить и отслеживать работу
+
+После запуска команды ваша задача - держать работу видимой, ограниченной и готовой к review. Главная поверхность - board.
+
+## 1. Дайте lead понятный brief
+
+Lead нужна цель, которую можно разбить на задачи. Укажите:
+
+- outcome
+- разрешённые файлы или область продукта
+- что не трогать
+- verification commands
+- когда просить review
+
+Хороший brief:
+
+```text
+Create a beginner docs path. Keep edits inside landing/product-docs. Add screenshots where they clarify actions. Do not touch runtime code. Run `pnpm --dir landing docs:build` before marking tasks complete.
+```
+
+Слабый brief:
+
+```text
+Improve docs.
+```
+
+Слабый brief даёт lead слишком много свободы и усложняет review.
+
+## 2. Читайте board по колонкам
+
+<ZoomImage src="/screenshots/guides/task-board-annotated.png" alt="Аннотированная доска с messages, kanban lanes, review cards и task list" caption="Board помогает одновременно видеть messages, task state, review-ready work и правый task list без чтения raw-файлов." />
+
+| Колонка | Что значит | Что делать |
+| --- | --- | --- |
+| Todo | Задачи есть, но ещё не активны. | Проверить, достаточно ли конкретные titles. |
+| In Progress | Teammate активно работает. | Смотреть updates и не назначать duplicate work. |
+| Review | Работу нужно проверить. | Открыть task и review changes. |
+| Done | Работа завершена, но может требовать review flow. | Проверить review state перед доверием результату. |
+| Approved | Review прошёл. | Считать результат завершённым. |
+
+## 3. Используйте messages и comments осознанно
+
+Task comments подходят для контекста конкретной задачи:
+
+```text
+Please keep this task scoped to the quickstart page. Do not change runtime setup wording in this pass.
+```
+
+Direct messages подходят для координации:
+
+```text
+Lead, pause new task creation until the current review queue is cleared.
+```
+
+Если возможно, предпочитайте task comments. Они остаются привязанными к работе.
+
+## 4. Открывайте task detail, когда карточке нужно внимание
+
+Открывайте task detail, если:
+
+- title слишком размытый
+- задача слишком долго in progress
+- задача готова к review
+- output упоминает неожиданные файлы
+- нужно проверить attachments, changes или logs
+
+<ZoomImage src="/screenshots/guides/task-detail-annotated.png" alt="Аннотированная карточка задачи с description, attachments, changes и execution logs" caption="Task detail помогает подтвердить scope, attached context, changed files и runtime evidence." />
+
+## 5. Разблокируйте работу
+
+Если teammate заблокирован, попросите минимальный следующий шаг:
+
+```text
+Post the blocker, the file or command involved, and the next action you need from the lead or user.
+```
+
+Если задача слишком большая, попросите lead разделить её:
+
+```text
+Split this into separate tasks for copy edits, screenshot assets, and navigation updates. Keep each task independently reviewable.
+```
+
+## 6. Когда остановить команду
+
+Остановите или поставьте на паузу, если:
+
+- review queue больше, чем вы можете проверить
+- lead повторно создаёт размытые задачи
+- runtime errors появляются в нескольких задачах
+- агенты начали менять unrelated files
+- completed work не содержит verification
+
+Команду можно перезапустить после уточнения brief.
+
+Дальше: [Проверить и approve](/ru/guide/review-and-approve).

landing/product-docs/ru/index.md

@@ -9,8 +9,8 @@ hero:
   tagline: Создавайте команды, наблюдайте за канбан-доской, ревьюйте изменения и координируйте Claude, Codex, OpenCode и multimodel workflows без потери локального контроля.
   actions:
     - theme: brand
-      text: Быстрый старт
-      link: /ru/guide/quickstart
+      text: Путь новичка
+      link: /ru/guide/beginner-workflow
     - theme: alt
       text: Установка
       link: /ru/guide/installation
@@ -63,6 +63,10 @@ Agent Teams - бесплатное desktop-приложение для орке
 После создания первой команды изучите эти руководства:
 
 - **Настройка рантайма** - настройте Claude, Codex, OpenCode или multimodel-провайдеров: [Настроить рантаймы](/ru/guide/runtime-setup)
+- **Путь новичка** - полный первый маршрут от проекта до approval: [Начать walkthrough](/ru/guide/beginner-workflow)
+- **Создать первую команду** - lead, builder, reviewer, роли, модели и Worktree: [Создать команду](/ru/guide/create-first-team)
+- **Запустить и отслеживать работу** - board, comments, task detail и logs: [Запустить работу](/ru/guide/run-and-monitor-work)
+- **Проверить и approve** - task results и code changes до approval: [Проверить работу](/ru/guide/review-and-approve)
 - **Workflow агентов** - как агенты координируются через task board: [Разобрать workflow](/ru/guide/agent-workflow)
 - **Примеры team briefs** - паттерны промптов из реальных примеров: [Примеры](/ru/guide/team-brief-examples)
 - **Код-ревью** - проверяйте diff, принимайте или отклоняйте изменения: [Ревью изменений](/ru/guide/code-review)
@@ -78,4 +82,4 @@ Agent Teams - бесплатное desktop-приложение для орке
 
 ## Превью продукта
 
-<ZoomImage src="/screenshots/1.jpg" alt="Канбан-доска Agent Teams" caption="Статусы задач, активность агентов и review workflow видны в одном рабочем пространстве." />
+<ZoomImage src="/screenshots/product-preview.jpg" alt="Канбан-доска Agent Teams" caption="Статусы задач, активность агентов и review workflow видны в одном рабочем пространстве." />

landing/product-docs/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vitepress/client"],
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": [".vitepress/**/*.ts", ".vitepress/**/*.vue"]
+}