@darkclaw921/umgt 0.0.0-stage → 0.2.0

package/dist/web/index.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="ru">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#12142B" />
+    <link rel="icon" href="/favicon.ico" sizes="48x48" />
+    <link rel="icon" type="image/png" sizes="32x32" href="/icons/favicon-32.png" />
+    <link rel="icon" type="image/png" sizes="16x16" href="/icons/favicon-16.png" />
+    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
+    <link rel="manifest" href="/manifest.webmanifest" />
+    <meta name="application-name" content="Game Hub" />
+    <meta name="apple-mobile-web-app-title" content="Game Hub" />
+    <meta name="mobile-web-app-capable" content="yes" />
+    <meta
+      name="description"
+      content="Локальная мастерская игр. От идеи и плана до работающей игры с вашим AI-агентом."
+    />
+    <title>Game Hub — мастерская игр</title>
+    <script type="module" crossorigin src="/assets/index-sNciOZYG.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/jsx-runtime-CdVFa8IP.js">
+    <link rel="modulepreload" crossorigin href="/assets/ui-wHE_yBK0.js">
+    <link rel="stylesheet" crossorigin href="/assets/index-Izzbh11U.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/dist/web/manifest.webmanifest

@@ -0,0 +1,19 @@
+{
+  "id": "/",
+  "name": "UMGT Game Hub",
+  "short_name": "Game Hub",
+  "description": "Локальная мастерская игр: расскажи идею, а робот-помощник напишет код.",
+  "lang": "ru",
+  "dir": "ltr",
+  "start_url": "/",
+  "scope": "/",
+  "display": "standalone",
+  "background_color": "#0E1024",
+  "theme_color": "#12142B",
+  "icons": [
+    {"src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any"},
+    {"src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any"},
+    {"src": "/icons/maskable-192.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable"},
+    {"src": "/icons/maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable"}
+  ]
+}

package/dist/web/sw.js

@@ -0,0 +1,25 @@
+// Service worker for the installable Hub: push notifications only, no offline cache
+// (the Hub is a live local server, stale cached screens would be misleading).
+self.addEventListener('install', () => self.skipWaiting());
+self.addEventListener('activate', event => event.waitUntil(self.clients.claim()));
+self.addEventListener('fetch', () => {});
+
+self.addEventListener('push', event => {
+  let message = { title: 'Game Hub', body: '', tag: 'hub' };
+  try { message = { ...message, ...event.data.json() }; } catch { /* Keep the generic text. */ }
+  event.waitUntil((async () => {
+    const windows = await self.clients.matchAll({ type: 'window', includeUncontrolled: true });
+    // The open, focused Hub already shows the change on screen.
+    if (message.tag !== 'hub:test' && windows.some(client => client.focused)) return;
+    await self.registration.showNotification(message.title, { body: message.body, tag: message.tag, icon: '/icons/icon-192.png', badge: '/icons/favicon-32.png', lang: 'ru' });
+  })());
+});
+
+self.addEventListener('notificationclick', event => {
+  event.notification.close();
+  event.waitUntil((async () => {
+    const windows = await self.clients.matchAll({ type: 'window', includeUncontrolled: true });
+    if (windows.length) return windows[0].focus();
+    return self.clients.openWindow('/');
+  })());
+});

package/docs/agent-activity-ui.md

@@ -0,0 +1,33 @@
+# Agent activity in the workspace
+
+The compact strip under the workspace header shows provider-reported actions rather than rotating timer labels. Thinking, answer preparation, command execution, search, reading, writing and other tools use fixed Russian labels. Only a short safe detail is shown. The server supplies executable/file/tool names, not command arguments, stdout or private reasoning. The browser additionally removes control/bidirectional characters, masks obvious credentials and limits the detail to 160 characters. Details are plain React text, never HTML.
+
+`AgentActivityStrip` is loaded lazily. It remains visible in all project sections; chat/task labels and the open plan dialog use the same presentation. A small icon opacity animation and short label transition respect reduced motion. The polite live region contains only the action label and concurrent-tool count, not answer text or token deltas. Answer streaming remains in the existing chat message.
+
+Pending decisions override concurrent tools and stop the live animation. The existing permission banner and its single navigation action remain unchanged. When the connection drops, the strip stops animation and says it is reconnecting rather than presenting the last action as fresh activity. Terminal runs show a final summary without animation, while their bounded history remains inspectable.
+
+The Actions disclosure lists up to 40 real actions in chronological start order with status and timestamps. Completion updates a row in place; it does not append a duplicate. A bounded overlay scrolls independently, preserving the chat viewport height on desktop and mobile. Escape closes it and returns focus to its summary. Changing project/run closes the disclosure.
+
+The chat Stop row is a nonshrinking sibling of the scrollable message history, immediately above the composer. It stays fully visible and clickable while long answers stream or the user scrolls earlier messages. This corrects clipping observed in a real 1440 × 900 conversation; the browser regression includes twelve long prior messages, a long streamed answer, mobile 390 × 844, and a hit-test of the Stop button above the composer.
+
+## Snapshot and event reconciliation
+
+`src/web/activity.ts` owns `ActivityState`. It selects an explicit project and initially waits for an authoritative workspace snapshot. `agent.activity` and `run.updated` events received during that fetch are buffered, then reconciled. Items use stable IDs and monotonic per-run sequence values; older/equal revisions cannot replace newer state. A newer run discards the previous run's history. Retired IDs, run start/update ordering and terminal-run precedence prevent old snapshots or replay events from restarting completed activity. Resume creates a new run ID.
+
+The store accepts only the selected project's events. Other-project responses are ignored after a switch. Snapshot items must match the current run. Activity preceding its run event is held until the run is known. Terminal runs project any still-open item as completed, failed or cancelled, so a missing final tool event cannot leave a live animation. Active items are retained ahead of completed entries when the history limit is reached.
+
+`App` merges workspace `activities` (or the optional singular `activity`) and normalized SSE into the controller. The existing event cursor still deduplicates transport replay. Old servers that omit activity fields use the honest fallback “Ожидает ответа” while a run is active; no synthetic thinking/tool events are invented. Raw protocol logs remain separate from the product activity view.
+
+## Verification
+
+`tests/activity-ui.test.ts` exercises replay before a snapshot, overlapping stale snapshots, reconnect, terminal precedence, project/run isolation, events arriving before a run, permission priority with parallel tools, bounded chronological history, stop without final tool event, old-server fallback and credential/control-character handling.
+
+`tests/e2e/activity.spec.ts` runs the compiled browser UI against real local HTTP, SSE, workflow normalization and SQLite with an explicitly injected provider fixture. Its command/read/write/search events are controlled test signals, not actual model tool calls. The browser verifies all labels, a pending permission and its existing CTA, streamed answer visibility, active-command reload, project switching, task/plan visibility, reduced-motion behavior, terminal replay and old-run rejection. Desktop/mobile history overlays preserve viewport dimensions. Actual installed-model verification is performed separately by the root agent and must not be inferred from fixture coverage.
+
+## Installed Codex acceptance — 7 October 2026
+
+Root verified the final compiled UI using background headless Chromium and the installed Codex (`gpt-6.1-sol`, medium) in a read-only discussion of the existing test project. No commands, game-file edits, plan changes or development-task changes were requested. The actual run showed waiting → thinking → answer preparation → completed. Reload during the active run restored thinking; the final reload restored `idle`, `data-live=false` and an active connection. The mobile history disclosure showed the three completed actions. Provider user messages no longer appeared as tool calls.
+
+Actual long-history desktop geometry was 1440 × 900 for both document and viewport. The Stop button occupied y=610–646, above the composer at y=658, and passed a real hit-test. At 390 × 844, document and viewport matched; Stop occupied y=546–582, above the composer at y=594, and remained visible/clickable. Thinking and answering were both captured with the control fully available. The evidence is recorded in `.artifacts/agent-activity-20261007/ui-verification.json` and its `screenshots/live-*.png` captures. Fixture captures remain separately named `.artifacts/activity-fixture-*.png`.
+
+Final source validation: typecheck and production build passed; 160 unit/integration checks in 18 files passed in 23.98 seconds, and all seven browser scenarios passed in 22.5 seconds. Live Codex acceptance confirms the actual thinking/answering lifecycle and restoration. Command/search/read/write/tool categories and permission transitions in this feature's browser suite were exercised through the explicit provider fixture, not live Codex tool execution.

package/docs/agent-activity.md

@@ -0,0 +1,43 @@
+# Активность агента
+
+Hub передаёт краткие состояния из фактических событий локальных Codex, Claude Code и Kimi. Поток ответа `agent.delta` и журнал инструментов сохраняются отдельно. Для начала запроса отображается ожидание; «Думает» появляется после подтверждения принятого turn Codex или при настоящем reasoning/thinking-сигнале, «Готовит ответ» — при генерации текста. Текст внутренних размышлений не копируется ни в activity, ни в журнал.
+
+## Контракт
+
+`agent.activity` — обычное сохранённое SSE-событие Hub с `projectId`. Его payload:
+
+```ts
+interface AgentActivity {
+  id: string;
+  runId: string;
+  kind: 'waiting' | 'thinking' | 'answering' | 'command' | 'search' | 'read' | 'write' | 'tool';
+  status: 'running' | 'waiting_permission' | 'completed' | 'failed' | 'cancelled';
+  label: string;
+  detail?: string;
+  createdAt: string;
+  updatedAt: string;
+  sequence: number;
+}
+```
+
+Идентификатор стабилен при обновлениях действия: run ID + отдельный ID обращения к провайдеру + ID item/tool. Повторная попытка задачи не сталкивается с прежним ID. `sequence` увеличивается при каждом изменении в рамках run; дубликаты состояния не создают события. Сотни reasoning/text deltas не создают сотни activity-записей: меняется только фаза.
+
+GET `/api/v1/projects/:id` включает `activities` и необязательное `activity`. SQLite хранит до 40 последних действий текущего run; при ограничении места сначала удаляются терминальные записи. Snapshot не требует восстановления из первых 1000 записей большого журнала. Следующий run очищает текущую проекцию, но сохраняет прежние SSE-события в журнале. Клиент фильтрует project/run, объединяет записи по ID и sequence и не оживляет завершённый run старыми replay-событиями.
+
+Текущее действие выбирается с приоритетом разрешения, затем выполняющегося инструмента, затем фазы ответа/размышления/ожидания. Несколько инструментов могут оставаться активными параллельно. При завершении, ошибке, остановке или восстановлении после прерывания все незаконченные записи получают терминальное состояние. Если провайдер не сообщил окончание инструмента, окончание запроса само по себе не считается доказательством успеха этого инструмента: такая запись отменяется. Проверка Godot, выполняемая самим Hub после задачи, также имеет отдельное действие `tool` с `detail: "Godot: verify"`.
+
+## Провайдеры
+
+- Codex: подтверждённый `turn/started` / успешный `turn/start` означает обработку запроса даже без reasoning stream; ожидание до принятия turn остаётся отдельной фазой. Поздний RPC ACK не откатывает активный ответ или уже завершённый turn. `item/started`, `item/completed`, reasoning-сигналы и agentMessage deltas обновляют дальнейшие действия. `userMessage`, `functionCallOutput` и прочие служебные item не считаются новыми инструментами. Команды учитывают `exitCode` и status; fileChange, webSearch, MCP/dynamic tools получают собственные категории. Модель `gpt-6.1-sol` и effort `medium` по умолчанию передаются по прежнему явному контракту.
+- Claude SDK: thinking/text content blocks, tool_use и фактический tool_result. Закрытие блока аргументов не завершает инструмент. Detached tool_result означает продолжающуюся работу и также не считается успехом.
+- Kimi ACP: agent_thought_chunk, agent_message_chunk, tool_call и частичные tool_call_update. Обновления без kind/title сохраняют известную категорию инструмента. История session/load не превращается в новую активность.
+
+Adapter emit-контракт: `emit('agent.activity', {id, kind, status, detail?})`. Workflow добавляет run, время, sequence и фиксированную подпись. Запрос разрешения создаёт отдельное действие `waiting_permission`; ответ/отмена завершают его, а окончание самого инструмента определяется событиями провайдера.
+
+## Краткие детали и ограничения
+
+Детали ограничены безопасными идентификаторами: имя исполняемой команды без аргументов, имя файла или инструмента. Вывод команд, поисковый запрос, ввод инструмента и содержимое файла в status не передаются. Простой `rg`/`grep` классифицируется как поиск, `cat`/`head` как чтение; shell pipelines и неоднозначные команды остаются категорией command. Полный журнал реальных инструментов сохраняет прежнее поведение. Нормализованные подписи не являются пересказом скрытой цепочки рассуждений.
+
+В автоматических проверках используются настоящие RPC subprocess fixtures для Codex/Kimi и mocked Claude SDK; это доказательство протокола, а не живого вызова моделей. Backend-тесты проверяют bounded storage, 1100 записей журнала перед snapshot, разрешения, отказ, остановку, recovery, поздние события, смену run и отсутствие thought-содержимого. Живой Codex и browser E2E описываются отдельно в validation.
+
+Контракты сверены с JSON Schema установленного Codex (`codex app-server generate-json-schema`) и [официальной документацией Claude SDK streaming](https://code.claude.com/docs/en/agent-sdk/streaming-output). Завершение аргументов и завершение исполнения различаются намеренно.

package/docs/agent-permissions-ui.md

@@ -0,0 +1,15 @@
+# Автоматические разрешения агента
+
+Пользователь разрешил автоматически подтверждать действия агента. Новый backend нормализует `HubSettings.autoApproveActions` в `true` по умолчанию; интерфейс не добавляет согласий или подтверждений перед включением. Settings показывает checkbox «Автоматически разрешать действия агента» и явный режим. Изменение черновика применяется существующей кнопкой «Сохранить настройки». Его можно отключить, сохранив ручные карточки. Вопросы об игре требуют настоящих ответов пользователя; UI не подставляет ответы.
+
+Политика централизована в backend. Frontend не вызывает разрешение каждого запроса и не меняет sandbox/ограничения провайдера. Подтверждённое `permission.auto_approved` отображается отдельной строкой журнала B: фактическое количество недавних разрешённых запросов. События фильтруются по проекту и соответствующему run, дедуплицируются по HubEvent.id; история не создаёт pending-состояния или повторной анимации. Основной журнал событий хранится сервером, UI использует существующие последние 300 событий. Смена проекта и посторонние run не добавляют чужих разрешений в текущий журнал.
+
+Frontend совместим с ещё работающим старым backend: отсутствие поля в GET/settings сохраняется явно, несмотря на новые клиентские defaults. Контрол в этом случае недоступен с пояснением об обновлении сервера; автоматическое разрешение не обещается. Существующие permission cards продолжают работать. Это важно при обновлении статических файлов без прерывания пользовательской работы.
+
+## Проверки
+
+`tests/auto-approval-ui.test.ts` проверяет отображение true/false/unsupported и фильтрацию, дедупликацию и неактивность исторического автоматического разрешения. Вместе с `tests/workflow-journal.test.ts` проходят 10 focused tests; typecheck PASS.
+
+`tests/e2e/auto-approval.spec.ts` использует настоящий API/SSE, сохранение, production UI и подставленную модель/verifier: default automatic, завершение без карточки, фактическая строка журнала после reload, сохранение ручного режима и старый runtime без поля. Существующие E2E, проверяющие именно ручное подтверждение (`activity.spec.ts` и journal latency/permission), явно задают false. Они не изменяют production default.
+
+Изолированный `createJournalHub` принимает optional `autoApproveActions`. При отсутствии значения применяется production default true; для ручной демонстрации укажите false. Все файлы и данные временные, реальные команды и LLM не запускаются. Итоговые полные тесты/сборка/активация фиксируются root отдельно.

package/docs/api.md

@@ -0,0 +1,145 @@
+# Local API v1
+
+All requests use same-origin session cookie established by opening CLI URL with `#token=...` then POST /api/v1/session `{token}`. JSON errors have `message`. GET /api/v1/events is SSE; reconnect sends Last-Event-ID. Events have `{id,type,projectId?,payload,createdAt}`.
+
+## Hub
+- GET /api/v1/projects → `Project[]`
+- POST /api/v1/projects `{name,path,dimension:'2d'|'3d',platforms:['desktop'|'web'],agent:'codex'|'claude'|'kimi',description?,engine:'godot'}` → Project
+- POST /api/v1/dialogs/directory (no body) → `{path:string|null}`. Opens the native directory chooser on the server's desktop; returns an existing canonical absolute directory path or `null` when cancelled. Paths preserve whitespace. One dialog per server; concurrent requests receive 409, unavailable graphical tools receive 503 and a five-minute timeout receives 504. Disconnect/server shutdown aborts the dialog. Requires the same session, Origin and Host checks as other API calls. Choosing does not create a project or bypass empty-directory validation.
+- GET /api/v1/settings → `{id:'settings',agents:{codex:{executable,model,reasoningEffort},claude:{executable,model?},kimi:{executable,model?}},godotPath?,theme?}`
+- PUT /api/v1/settings same shape (agents optional). Provider fields merge with saved values. Omitted or blank Codex model/effort resolves to `gpt-6.1-sol` / `medium`; explicit nonblank selections survive. `reasoningEffort` is a string (at most 40 characters), permitting levels advertised by the installed CLI; model compatibility is validated by Codex. An explicitly empty value resets that field to the application default.
+- GET /api/v1/diagnostics → `{agents:[{id,available,version?,error?,capabilities,protocol?,authentication?}],godot?}`. Godot includes matching `exportTemplates:{version,directory,web,desktop}` and guidance when templates are absent.
+
+## Ordinary chat
+
+- GET /api/v1/chats → conversation summaries for the connected UMGT account.
+- POST /api/v1/chats `{}` → 201 new conversation; no game project is needed.
+- GET /api/v1/chats/:id → `{id,title,model,createdAt,updatedAt,status,error?,messages,games}`; status is `idle`, `running`, `stopped` or `error`. While running, snapshots include the current partial answer; the UI polls every 700 ms.
+- POST /api/v1/chats/:id/messages `{text,requestId,voiceEnabled?:boolean}` → 202 snapshot. Text is trimmed and limited to 30,000 characters; requestId must be a UUID. Repeating the same accepted message ID does not start another model call; a different message while that dialog is running returns 409.
+- POST /api/v1/chats/:id/stop `{}` → snapshot; cancellation is forwarded to Core.
+
+Voice output uses Google Gemini TTS / Autonoe through Core. The authenticated local `POST /api/v1/speech` endpoint accepts `{requestId:UUID,text:string}` (1–240 characters) and returns `{audio:base64,mime:"audio/wav",operationId,billing:"paid"|"pending",tokens?}`. Pending provider metadata is reconciled and settled by Core asynchronously. Browser dictation remains native.
+
+Messages contain optional `speech` (a brief voice summary generated only when voice is enabled), plus `{id,role:'user'|'assistant',content,createdAt,status:'complete'|'interrupted'}`. Model selection is controlled exclusively by the Core administrator. Legacy local model overrides are ignored; PUT /api/v1/core/model returns 403. Each conversation uses a separate Core session with `create_game`, `update_game`, `open_game` workflow tools and local file/command tools and retains context across studio restarts. History is stored in Hub's database, scoped by Core origin and UMGT user ID; another account receives 404 for the conversation ID. Responses do not expose owner identifiers or remote session IDs. An interrupted request is never automatically replayed. Normal Core subscription checks and usage accounting apply. These routes require local Hub authentication and a connected UMGT account.
+
+Conversation snapshots also include `launches:[{id,requestId,gameId,status:"running"|"ready"|"error",url?,error?,createdAt}]`. The `open_game` tool prepares the latest ready HTML game asynchronously. The UI reserves a window for an explicit open request and navigates it when ready; historical actions are never replayed on reload.
+
+Games are scoped to the owning chat. POST `/api/v1/chats/:id/games/:gameId/stop` stops that workflow; POST `/api/v1/chats/:id/games/:gameId/launch` builds a ready HTML5 game and returns `{url}` for a loopback preview in a new window. Other accounts/chats receive 404. HTML prototypes use one approved epic/task, no external assets and the normal execution and independent build verification. Explicit Godot/Roblox requests use standard planning and asset selection; any required choices remain available in the project. A restart stops unfinished chat jobs without replaying AI calls; history and completed projects remain available.
+
+## Project workspace
+- GET /api/v1/projects/:id → `{project,messages,plans,tasks,epics,run,activity?,activities,permissions,extensions,assets}`
+- PATCH /api/v1/projects/:id `{agent?,description?}` between operations
+- POST /api/v1/projects/:id/messages `{text,mode:'interview'|'chat'}` → 202 `{run}`; LLM answers asynchronously and persists messages. This never writes game files.
+- POST /api/v1/projects/:id/plan `{brief?}` → 202 `{run}` generates draft using interview history.
+- PUT /api/v1/projects/:id/plan `{markdown}` → Plan (new unapproved version).
+- POST /api/v1/projects/:id/plan/approve `{planId}` → 202 `{run}` approves and starts concurrent task decomposition and asset discovery. Execution waits for explicit asset-selection confirmation and successful import.
+- POST /api/v1/projects/:id/tasks/:taskId/assets `{provider,id}` → Task; attaches a known catalog asset or an asset already imported into this project. Requires idle workflow and unfinished task. Deduplicated by provider/id, maximum 20 references; manual catalog resources still require upload/import.
+- POST /api/v1/projects/:id/tasks/:taskId/retry `{}` → Task; resets a failed task for an explicitly requested new attempt.
+- GET /api/v1/projects/:id/tasks/export → `{epics,tasks}`
+- POST /api/v1/projects/:id/run `{}` → 202 `{run}` sequentially executes approved tasks.
+- POST /api/v1/projects/:id/control `{action:'pause'|'stop'|'resume'}` → `{run}`
+- POST /api/v1/projects/:id/permissions/:permissionId `{allow:boolean,answers?:Record<string,string[]>}` → `{ok:true}`
+
+`Project`: `{id,name,path,engine,dimension,platforms,agent,description,createdAt,updatedAt}`.
+`Message`: `{id,role:'user'|'assistant'|'system',content,createdAt}`.
+`Plan`: `{id,version,markdown,approvedAt?:string,createdAt}`.
+`Epic`: `{id,title,description,phase:number,planId}`.
+`Task`: `{id,epicId,title,description,acceptance:string[],dependencies:string[],status:'open'|'running'|'done'|'failed',attempts:number,planId,priority:number,estimateMinutes:number,assetRefs?:Array<Asset & {directory?:string}>,verification?:string,error?:string}`.
+`Run`: `{id,kind:'interview'|'chat'|'planning'|'decomposition'|'asset_selection'|'execution',status:'running'|'pausing'|'paused'|'stopped'|'completed'|'failed'|'interrupted',startedAt,updatedAt,taskId?,error?}`.
+`Permission`: `{id,method,details,createdAt}`; pending only.
+
+SSE event types: `agent.delta {text}`, `agent.tool {method,details}`, `permission.requested Permission`, `permission.resolved {id}`, `message.created Message`, `plan.created Plan`, `plan.approved Plan`, `tasks.created {epics,tasks}`, `task.updated Task`, `run.updated Run`, `log {text}`. Refetch snapshot on state-changing events; append `agent.delta` to transient streaming output. Single active operation per project; conflicting mutation returns 409.
+
+## Engine, extensions and assets
+- POST /api/v1/projects/:id/engine/editor, /run, /verify, /export (export body `{platform:'desktop'|'web'}`) → 202 `{operationId,status:'running'}`. Missing selected-platform release templates return 422 `{error:'export_templates_missing',message}` before export starts; the message includes matching version, searched directory and installation instructions. Discovery supports standard and marker-enabled self-contained Steam/macOS installations. Existing project configuration is preserved; an exporter log containing `ERROR` remains unsuccessful even with exit code 0.
+- POST /api/v1/projects/:id/engine/stop → `{ok:true}`.
+- Engine SSE: `engine.log {operationId,text}`, `engine.completed {operationId,ok,outputPath?,url?,error?}`. Export URL opens the local Web preview.
+- GET /api/v1/extensions → `SkillPackManifest[]`.
+- POST /api/v1/projects/:id/extensions/install `{ids?:string[]}` → installed manifest array. Omitting IDs installs recommendations; explicit IDs add selected skills or the pinned optional GUT plugin while preserving existing extensions.
+- GET /api/v1/assets?q=&provider=all|polyhaven|ambientcg|kenney&type= → `{assets:Asset[],warnings:string[]}`; upstream failures are partial warnings.
+- GET /api/v1/assets/:provider/:id → `Asset` details.
+- POST /api/v1/projects/:id/assets `{provider,id}` → imported asset metadata.
+- POST /api/v1/projects/:id/assets/upload multipart file plus optional sourceUrl/author/license fields → imported metadata.
+
+`Asset`: `{id,provider,name,type,thumbnail?,sourceUrl,license,author?,tags:string[],downloadUrl?,formats?:string[],importMode:'automatic'|'manual',previewAudioUrl?,licenseUrl?,attribution?,provenanceUrl?,verifiedAt?}`. Automatically downloadable verified CC0/CC-BY items use protected import; manual cards link to source and support local upload. Search alone never imports files.
+`SkillPackManifest`: `{id,name,description,version,engine,type:'skill'|'plugin'|'mcp',source,license,dimensions?}`.
+
+`agent.activity` events carry `{id,runId,kind,status,label,detail?,createdAt,updatedAt,sequence}`. Categories and lifecycle are documented in [agent activity](agent-activity.md). Workspace snapshots include at most40 current-run activity records, independent of journal replay length. Detail contains identifiers, not arguments/output/hidden reasoning. Sequence is monotonic per run; clients must ignore stale project/run and sequence updates.
+
+## Interactive interview
+
+Workspace snapshots include `interviewRounds: InterviewRound[]` and optional latest `interviewRound`; messages may have `interviewRoundId`. Round and answer contracts, validation limits and legacy handling are documented in [structured interview](interactive-interview.md).
+
+- POST `/api/v1/projects/:id/interview/:roundId/answers` `{answers:[{questionId,value?:string|string[]|number,customText?:string}]}` →202 `{run}`. Invalid answers return400; stale/closed/concurrent submissions return409.
+- `interview.updated` carries the full persisted round. Refetch the workspace after changes.
+- Interview model protocol JSON is not emitted as `agent.delta`; validated public text arrives in `message.created` linked to a round. Ordinary chat continues streaming.
+- Natural-language messages supersede a pending form. `complete` round status does not generate or approve a plan.
+
+After a complete interview, bounded explicit whole-message planning/development requests to `/messages` return a `planning` run instead of another interview turn. The browser opens plan review from this returned kind. The new plan remains unapproved. `Plan.interviewRoundId?:string` records its interview provenance; workspace `planNeedsUpdate:boolean` identifies plans predating the current brief. Approval, run and resume return409 for stale plans. Manual PUT `/plan` stamps current provenance. See [explicit planning transition](interactive-interview.md#explicit-transition-to-planning).
+
+## Approval journal
+
+`Run.stages?:WorkflowStage[]` records real decomposition boundaries; workspace `decomposition?:Run` retains the latest preparation run when current `run` advances to execution. `workflow.stage` SSE carries `{id,runId,planId,kind,status,label,createdAt,updatedAt,sequence,counts?}`. Kinds: `approval|skills|generation|validation|saving`; status: `running|completed|failed|cancelled`. Counts may include `skills`, `epics`, `tasks`, only after their actual operations complete. Reconcile stage IDs and monotonic sequence; no percentage or raw model output is part of this contract. See [approval journal](approval-journal.md).
+
+## Automatic action approval
+
+Settings include normalized `autoApproveActions:boolean`, default `true` for fresh and legacy missing values. PUT `/api/v1/settings` accepts it; enabling it resolves this server's existing pending action requests while leaving interactive input questions pending. `permission.auto_approved` carries `{id,runId,method,createdAt}` without raw permission details. Newly autoapproved actions have no `permission.requested` event or pending row; promotion of an existing manual request also emits its usual `permission.resolved`. Provider read-only denials and real user-input requests remain distinct. See [automatic approvals](automatic-approvals.md).
+
+On macOS, POST `/api/v1/projects/:id/engine/run` now uses the installed `.app` with native background activation (`open -g -n -W`). The visible game remains interactive when selected. Stop tracks and revalidates the separately launched game PID; stderr/stdout still reach `engine.log`. Editor requests and headless verification/export are unchanged. Other desktop foreground behavior remains OS-dependent. See [background game launch](background-game-launch.md).
+
+## Plan-bound asset selection
+
+Workspace snapshots expose `assetSelection?:AssetSelection` and `assetReadiness:{tasksReady,assetsReady,canExecute,reason?}`. The new gate applies to plans with a selection; legacy plans without one retain their existing execution behavior. Even an empty list of needs requires explicit confirmation. `Task.assetNeedIds?:string[]` links requirements to tasks; imported files are also available through existing `assetRefs`.
+
+- GET `/api/v1/projects/:id/asset-selection` → `{selection?,readiness}`.
+- POST `/api/v1/projects/:id/asset-selection` `{planId?}` →202 `{selection,run?}`; starts discovery for an existing current approved plan without replacing its task DAG.
+- PATCH `/api/v1/projects/:id/asset-selection/:selectionId/needs/:needId` `{revision,choice:{kind:'candidate',candidateId}|{kind:'skip'}}` → selection. Required needs cannot be skipped.
+- POST `.../needs/:needId/search` `{revision,query}` → selection; replaces the alternatives for that need and clears its earlier choice.
+- POST `.../needs/:needId/upload` multipart `file`, `revision`, optional `candidateId`, `license`, `sourceUrl`, `author`, `licenseUrl` → selection. Fields precede the file. Files stage outside the game until finalization.
+- POST `.../:selectionId/confirm` `{revision}` → selection; records confirmation, then prepares files once decomposition completes. Manual-source candidates require an uploaded file.
+- POST `.../:selectionId/retry` → selection; explicitly continues a failed/cancelled selection.
+- POST `.../:selectionId/cancel` → selection; cancels an unconfirmed selection. Active import uses the project stop control.
+
+Selections persist `id,planId,runId,status,needs,revision,createdAt,updatedAt,confirmationRequestedAt?,confirmedAt?,error?`. Status is `discovering|choosing|importing|confirmed|failed|cancelled`. A need stores `id,title,type,query,rationale,required,taskHints,candidates,choice?,status,importedAsset?,warnings?,error?`. Candidate metadata comes from the catalog; LLM ranking can only refer to supplied IDs.
+
+`asset.selection.updated` publishes the persisted selection. Refetch the workspace to reconcile readiness and task changes. Each update advances `revision`; stale edits and wrong-plan identifiers return409. Invalid or incomplete choices return400. Final confirmation is distinct from import completion, and server run/resume checks cannot be bypassed by a disabled UI button. See [selection workflow](asset-selection.md).
+
+
+## Превью медиа
+
+`Asset` сохраняет совместимость с обложкой и audio URL, дополнительно возвращает `media: AssetMedia[]`, `mediaTotal`, `mediaGalleryUrl` и `previewVideoUrl`. Элемент содержит `kind` (`image|audio|video`), `url`, опциональные `name`, `mime`, `poster`.
+
+- `GET /api/v1/assets/:provider/:assetId/media?offset=0&limit=60` — индекс проверенного архива провайдера.
+- `GET|HEAD /api/v1/assets/:provider/:assetId/media/files/:index` — конкретный файл из индекса.
+- `GET /api/v1/projects/:id/asset-media/:kind/:assetId` — staged/imported галерея проекта.
+- `GET|HEAD /api/v1/projects/:id/asset-media/:kind/:assetId/files/:index` — файл этой галереи.
+
+Ответ галереи: `{media,total,nextOffset?}`. Файлы требуют авторизованной сессии, поддерживают single byte Range (206/416), сигнатурный MIME и sandbox CSP. URL и файловые пути клиента не используются для произвольного доступа. Форматы и ограничения: [asset-media.md](asset-media.md).
+
+## HTML5 и Яндекс Игры
+
+Создание проекта принимает `engine: "html5"` или `"godot"`; `platforms` может включать `"yandex-games"` вместе с `"web"`. HTML5 не поддерживает Desktop-экспорт. Опциональная `yandexGames` содержит ID приложения, устройства, ориентацию, языки, рекламу, облачные сохранения, авторизацию, продукты с числовыми выдачами и технические имена лидербордов. Покупки требуют облачных сохранений и продуктов. Существующие Godot-запросы остаются совместимыми.
+
+- `GET /api/v1/extensions?projectId=...` возвращает подходящие движку, платформе, жанру и размерности навыки. Без параметра возвращается общий каталог.
+- `GET|PUT /api/v1/projects/:id/yandex-games/config` читает или обновляет SDK-настройки; изменение требует новой сборки.
+- `POST /api/v1/projects/:id/engine/export` принимает `platform: "yandex-games"`; общий engine lifecycle сохраняет остановку, события и проверку результатов.
+- `GET /api/v1/projects/:id/builds`, `GET /api/v1/projects/:id/builds/:buildId/download`, `POST /api/v1/projects/:id/builds/:buildId/validate` обслуживают неизменяемые ZIP и результаты проверки. Подготовка публикации повторно сверяет ZIP, содержимое превью и конфигурацию.
+- `GET|PUT /api/v1/browser/config`, `POST /api/v1/browser/diagnostics` управляют отдельным loopback Chrome MCP. Доступность расширения ChatGPT не считается доступностью этого подключения.
+- `GET /api/v1/projects/:id/publication`, `POST .../publication/start` с `{buildId?,metadata}`, `POST .../publication/control` с `{action:"pause"|"resume"|"stop",draftUrl?}` и `POST .../publication/submit` с `{runId}` управляют сохраняемой публикацией. Только последний endpoint явно разрешает отправку на модерацию; глобальное auto-approve её не разрешает.
+- `GET|POST /api/v1/projects/:id/publication/materials` читает изображения или импортирует multipart-файл с назначением `icon`/`screenshot`. `GET .../materials/:materialId/file`, `DELETE .../materials/:materialId`, `POST .../materials/capture` с `{buildId}` обслуживают проверенные изображения. Захват работает только через подключённый Chrome на одобренном превью. Полное декодирование PNG/JPEG/WebP удаляет метаданные; лимиты — 10 МиБ, 4096 × 4096 и 10 материалов проекта.
+
+`publication.updated` и `publication.materials` передаются через SSE. Браузерный MCP capability действует только для текущего активного запуска; его внутренний endpoint не предназначен для общего использования. Отсутствие расширения, необходимость входа, CAPTCHA и ручной проверки Canvas явно отделяются от успешной загрузки и модерации. Подробности: [Яндекс Игры](yandex-games.md).
+
+## Roblox Studio
+
+Projects also accept `engine: "roblox", dimension: "3d", platforms: ["roblox"]`. Other combinations are rejected. Settings accept `robloxStudioPath?`, `robloxMcpPath?` and `robloxStudioId?`; GET diagnostics includes a `roblox` installation diagnostic. POST engine/verify checks local manifest/source packaging; POST engine/export `{platform:"roblox"}` builds `builds/game.rbxlx`. POST engine/editor or engine/run rebuilds and hands the file to Studio; Play is performed in Studio. Completion returns local `outputPath`, with no Web URL. Static success is not Luau compilation or gameplay evidence. StudioMCP is supplied to task agents only with an explicit target ID, and never to read-only planning. See [Roblox documentation](roblox.md) for supported manifest features, skill provenance and the playable prototype.
+
+
+The local GET `/api/v1/core` response includes optional `profile: {name, avatar_url}` from Core's authenticated GET `/api/v1/profile`. Only the current account's display fields are returned. Avatar paths from UMGT are resolved against the cabinet origin; profile failure does not prevent balances and limits from loading.
+
+Core entitlements may include `ai_budget: {status:'active'|'inactive'|'unavailable',currency:'USD',timezone:'Europe/Moscow',daily?,weekly?,monthly?,message?}`. Each window contains `{limit,used,left,starts_at,resets_at,pending_costs}` in actual provider USD. The active monthly allowance is 50% of the subscription tariff before payment fees; day = month / calendar days in the current month, week = day × 7, with Moscow resets. The Studio uses these windows instead of legacy token windows, shows only remaining/used percentages, and marks figures as approximate when provider costs are missing. Core rejects new text/TTS calls at exhausted allowances with `daily_budget_exceeded`, `weekly_budget_exceeded`, or `monthly_budget_exceeded`. An inactive/unavailable budget is shown explicitly, without falling back to unrelated token percentages.
+
+
+PATCH `/api/v1/chats/:id` `{title:string}` (1–120 characters) renames an owned dialog. DELETE moves it to trash and cancels active generation; games remain registered projects. GET `/api/v1/chats?deleted=true` lists owned trashed dialogs; POST `/api/v1/chats/:id/restore` restores history. Renamed titles and trash state survive background completion and restart. Ordinary GET/send/game endpoints return 404 for trashed or foreign dialogs.
+
+Chat sessions also expose local file/command tools. Commands execute in a separate per-dialog workspace on Hub, never on the Core server. Settings control automatic approval; pending `permissions` are returned by the chat snapshot and answered at POST `/api/v1/chats/:id/permissions/:permissionId` `{allow:boolean,answers?:Record<string,string[]>}`. Only the owning account can answer; stop/delete cancels pending permission requests.

package/docs/approval-journal.md

@@ -0,0 +1,13 @@
+# Approval and decomposition journal
+
+Approving a current plan persists its approval and starts decomposition. The server records five real boundaries: approval saved, skill preparation, model generation of the complete epic/task graph, JSON/DAG validation, and atomic task persistence. Generation is one potentially long model call; the server cannot truthfully report partial epic/task totals or a percentage before a validated graph exists. Provider thinking/answering/tool activity and pending permissions remain independent signals alongside this stage.
+
+`Run.stages?: WorkflowStage[]` stores a bounded five-stage projection in the existing project run document. A stage contains stable `id`, `runId`, `planId`, `kind`, `status`, `label`, `createdAt`, `updatedAt`, monotonic `sequence`, and optional `counts`. Kinds are `approval|skills|generation|validation|saving`; statuses are `running|completed|failed|cancelled`. Labels are fixed application text rather than raw model output. A stage has one stable ID per run/kind; terminal stages are immutable. Counts for installed skills appear after installation. Epic/task counts appear only on completed saving, after the SQLite transaction and `tasks.created` event.
+
+Each transition saves the updated run, emits `run.updated` and then `workflow.stage` carrying the full stage. Workspace snapshots include optional `decomposition`, the latest decomposition run, separately from the current `run`. This preserves the completed preparation journal after the existing automatic execution path starts and current provider activity is reset for execution. Clients reconcile by project/run/stage ID and sequence; replayed events are history, not new approvals. Old runs without stages remain valid and must not receive invented stage completions.
+
+Failure marks the active stage failed. Stop marks it cancelled synchronously and rejects late adapter results before graph validation/persistence. On server recovery, running decomposition stages become cancelled and the run becomes interrupted. Pending permissions retain the existing resolution and priority behavior; a stage is not evidence that a permission was granted. Completed stages remain available after errors or reload.
+
+The journal itself does not introduce an execution action. New plan approvals also start concurrent asset discovery, and automatic execution now waits for the explicit asset-selection confirmation and successful imports. The injectable `autoExecute:false` option still prevents automatic execution after readiness. Workspace `assetSelection` supplies additional real discovery/search/choice/import states without inventing decomposition stages or percentages. The journal offers a button to reopen the desktop wizard; waiting for a user's choice is distinguished from a running model request. Plan freshness, explicit approval, dependency validation, project serialization and independent engine verification remain enforced. See [asset selection](asset-selection.md).
+
+Focused backend regressions verify ordering, persistence, counts after task commit, invalid JSON failure, slow-model cancellation, ignored late successful results, interrupted recovery, and retention after execution becomes the current run. These use isolated project fixtures; reading journal state does not alter an active user project.

package/docs/asset-media.md

@@ -0,0 +1,27 @@
+# Предпросмотр настоящих медиа
+
+Каталог, окно подробностей, мастер выбора и коллекция проекта используют один `AssetMediaPreview`. Изображение показывается как изображение; звук и видео имеют встроенные плееры. Воспроизведение запускает пользователь. Начало нового плеера останавливает предыдущий, а смена файла, закрытие окна и размонтирование освобождают старый плеер. После секунды ожидания появляется индикатор; ошибки сохраняют возможность повторной загрузки.
+
+## Метаданные и галереи
+
+`Asset.media` содержит элементы `{kind:'image'|'audio'|'video',url,name?,mime?,poster?}`. `mediaTotal` и `mediaGalleryUrl` описывают реальные файлы набора. Старые `thumbnail`, `previewAudioUrl` и новый `previewVideoUrl` сохраняют совместимость с каталогом. Обложка и удалённое демо не считаются первым файлом архива: первая загрузка галереи начинается с `offset=0`.
+
+Импортированные и временно загруженные ресурсы получают ссылки на реальные файлы. Legacy записи импорта также обогащаются метаданными при чтении workspace. В галерее показывается один выбранный файл; страницы по 60 элементов позволяют просмотреть весь поддерживаемый набор без одновременной загрузки сотен картинок или аудио. Загрузка в мастере доступна для просмотра до подтверждения и переноса файлов в игру.
+
+Поддерживаются PNG/JPEG/WebP/BMP/GIF/SVG, WAV/OGG/MP3/FLAC, MP4/WebM/OGV. Для HDR/EXR, моделей, шрифтов и других форматов остаются обложка каталога и переход к источнику: браузерный просмотр этих файлов не заявляется. Поддержка контейнера видео не гарантирует поддержку любого кодека; плеер объясняет ошибку воспроизведения.
+
+## Серверная граница
+
+`asset-media.ts` обслуживает авторизованные проектные, staged/imported и провайдерские галереи. Клиент передаёт зарегистрированный ID и числовой индекс, а не путь файла или произвольный URL. Manifest определяет файлы, staged handle привязан к проекту. Проверяются канонические пути, каждый компонент на symlink, расширение и сигнатура содержимого. Политика loopback, Origin и session действует и для медиа.
+
+GET/HEAD поддерживают одиночные byte ranges: 206 с `Content-Range`, 416 для недопустимого диапазона. Файлы передаются потоком. Ответы содержат `nosniff`, private/no-store, same-origin resource policy и sandbox CSP без скриптов/внешних ссылок. SVG отображается как изображение; CSP защищает и прямое открытие файла, а не выдаётся за XML sanitizer.
+
+Просмотр файлов официального пакета создаёт отдельный кэш вне игровых проектов. Скачивание ограничено доверенными точными источниками и 64 MiB сжатого пакета; действуют прежние лимиты распаковки, запрет traversal/symlink и фильтрация macOS-метаданных. Большие пакеты доступны по исходной странице, а ошибку предварительной загрузки можно повторить.
+
+## Реальный пример: Idle Farm
+
+Проверяемые материалы: [Background Elements](https://kenney.nl/assets/background-elements), [Tiny Farm](https://kenney.nl/assets/tiny-farm), [UI Pack](https://kenney.nl/assets/ui-pack), [Interface Sounds](https://kenney.nl/assets/interface-sounds) и [Other Center](https://opengameart.org/content/other-center). Для проверки видеоплеера используется [Big Buck Bunny Trailer](https://peach.blender.org/trailer-page/) с лицензией CC-BY-3.0; это необязательный пример видео, не обязательная часть художественного оформления фермы.
+
+Файлы скачаны с настоящих источников; размеры, SHA256, авторы и лицензии сохранены в `.artifacts/real-assets-20261008/downloads.json`. Live E2E запускается отдельно: `LMGH_LIVE_ASSETS=1 npx playwright test tests/e2e/real-assets.spec.ts --output=.artifacts/real-assets-20261008/playwright-results`. Контролируется только планирующий ответ модели; каталог, архивы, изображения, звук, видео, импорт и HTTP media endpoints настоящие. Игровые проекты пользователя и реализация игры этим сценарием не изменяются.
+
+Обычные тесты покрывают безопасность/ошибки и используют отдельные явно тестовые ресурсы. Одновременные прогоны Playwright должны иметь разные `--output`, чтобы не удалять traces друг друга. Фактические результаты и снимки находятся в [журнале проверки](validation.md).

package/docs/asset-providers.md

@@ -0,0 +1,34 @@
+# Источники бесплатных игровых ассетов
+
+API подключения проверены 6 октября 2026; каталог Kenney/OpenGameArt расширен с проверкой карточек 8 октября 2026. Ниже описано фактическое подключение Hub.
+
+| Источник | Для чего подходит | Подключение в Hub | Лицензия |
+| --- | --- | --- | --- |
+| Poly Haven | 3D модели, PBR текстуры, HDRI | Поиск, метаданные и автоматическое скачивание через API | CC0 для ассетов; отдельные условия сервиса API |
+| ambientCG | Материалы, текстуры, HDRI и модели | Поиск и автоматический импорт из API v2 | CC0 |
+| Kenney | 2D тайлы, игровые наборы, UI и звуки | Проверяемый каталог пакетов с превью, переход к источнику, ручной импорт | CC0 для выбранных пакетов |
+| OpenGameArt | Музыка и звуки в подключённом каталоге; другие материалы через сайт | Проверенные карточки с аудиопревью и загрузкой; остальные источники добавляются вручную | CC0 и CC-BY для проверенных карточек |
+| itch.io | Авторские игровые наборы разных стилей | Внешний поиск бесплатных ассетов, ручной импорт | Определяется автором пакета |
+
+## Почему выбраны эти способы подключения
+
+Poly Haven публикует CC0 модели, текстуры и HDRI. Условия live API требуют идентифицирующего User-Agent/Referer и видимого указания источника. Hub использует собственный User-Agent, именует провайдера в карточках и показывает кредит рядом с каталогом. Поиск и скачивание обращаются к API, файлы модели импортируются вместе с зависимостями. Источники: [лицензия ассетов](https://polyhaven.com/license), [официальный API](https://github.com/Poly-Haven/Public-API), [условия API](https://github.com/Poly-Haven/Public-API/blob/master/ToS.md).
+
+ambientCG предоставляет API для программного поиска и загрузки, а ассеты и материальные превью распространяет под CC0. Hub использует `full_json` v2 для метаданных и вариантов загрузки; выбирает доступный небольшой архив и сохраняет происхождение. Документация также содержит v3; переход между версиями требует отдельной проверки контрактов. Источники: [API](https://docs.ambientcg.com/api/), [лицензия](https://docs.ambientcg.com/license/), [full_json v2](https://docs.ambientcg.com/api/v2/full_json/).
+
+Kenney удобен для небольших игр благодаря готовым стилистически согласованным наборам. Каталог Hub включает ресурсы для окружения и персонажей 2D, природы 3D, интерфейса и звуков. Пользователь открывает страницу выбранного пакета, скачивает архив и импортирует его через Hub. Устаревшая карточка Platformer Pack Redux заменена проверенным Pixel Platformer. Пример официальной карточки с лицензией и бесплатной загрузкой: [Tiny Town](https://kenney.nl/assets/tiny-town).
+
+OpenGameArt требует учитывать лицензию и атрибуцию конкретного материала. Hub содержит проверенные карточки аудио с точными ссылками на источник, автора, лицензию, превью и файл; внешний поиск остаётся доступен для ресурсов вне этой подборки. Это каталог конкретных проверенных ресурсов, а не общий API сайта. Источник: [официальный FAQ](https://opengameart.org/content/faq).
+
+Официальный серверный API itch.io работает с учётной записью и API key; документация отдельно описывает публичные RSS ленты. Для первого релиза выбран внешний поиск и ручной импорт без добавления авторизации itch.io в Hub. Это решение реализации; отсутствие подходящего общего API не утверждается. Источник: [официальный обзор API](https://itch.io/docs/api/overview).
+
+## Общий путь ресурсов
+
+Пользователь и агент используют один серверный каталог. MCP-инструменты `assets.search`, `assets.details`, `assets.download`, `assets.import` доступны выбранному агенту в контексте проекта; запись разрешена при утверждённом исполнении. Пользователь может прикрепить ресурс к открытой задаче, и её контекст содержит выбранные метаданные и папку уже импортированного ассета.
+
+Импорт сохраняет источник, автора, лицензию и список файлов. Загрузки ограничены по размеру, разрешённым доменам и редиректам; ZIP распаковывается во временную папку с проверкой путей, типов файлов и лимита распаковки. Ошибка отдельного провайдера возвращается предупреждением и не удаляет результаты остальных. Ручные файлы с неизвестной лицензией сохраняют это состояние; Hub не присваивает им CC0 автоматически.
+
+При утверждении нового плана эти источники используются в [параллельном подборе](asset-selection.md). Мастер предлагает реальные альтернативы, сохраняет выбор и ждёт подготовки настоящих файлов перед реализацией. CC-BY импорт сохраняет текст атрибуции и сведения для титров; пользовательские загрузки до подтверждения хранятся вне папки игры.
+
+
+Медиа-превью: наборы могут содержать image/audio/video. Скачиваемый архив провайдера имеет защищённую индексированную галерею с ленивым получением конкретных файлов; пользователь видит содержимое до импорта. Добавлены реальные Background Elements, Tiny Farm (Kenney) и Big Buck Bunny Trailer (Blender Foundation, CC-BY-3.0). Для Blender сохраняются автор, лицензия и ссылка на происхождение; экспорт/использование требует атрибуции. [Контракт и ограничения](asset-media.md), [реальная проверка](validation.md).

package/docs/asset-selection.md

@@ -0,0 +1,31 @@
+# Подбор ассетов перед реализацией
+
+При утверждении новой версии плана Hub параллельно создаёт эпики/задачи и подбирает внешние ресурсы. Это две ветви одной подготовки: создание задач не ждёт окончания поиска, а реализация ждёт подтверждённого выбора и успешной подготовки файлов.
+
+## Пользовательский сценарий
+
+Desktop-мастер открывается после утверждения плана. Выбранная в проекте локальная LLM определяет потребности из плана; каталог предоставляет реальные ресурсы и сведения об источниках. Для каждой потребности показываются доступные варианты с объяснением соответствия, форматом, лицензией и превью. Рекомендация не означает автоматического выбора.
+
+Пользователь выбирает вариант, уточняет запрос, повторяет поиск или загружает собственный файл. Ненужную необязательную потребность можно пропустить. Не найденный обязательный ресурс остаётся незавершённым: Hub не заменяет его незаметно заглушкой или генерируемой графикой. Если внешние ресурсы не нужны, итоговый шаг объясняет это и всё равно требует подтверждения.
+
+Закрытие мастера не отменяет подготовку. Выбор хранится в проектной SQLite, восстанавливается после обновления страницы, а мастер доступен из журнала и вкладки ассетов. В конце пользователь подтверждает подборку. Автоматические источники скачиваются через существующий защищённый импорт; ручные источники требуют загрузки настоящего файла. Ссылка на страницу не считается импортированным ассетом.
+
+## Workflow и сохранение
+
+Подборка привязана к проекту и конкретному `planId`, содержит потребности, кандидатов, выбор, состояния поиска/импорта и ревизию. Snapshot и SSE передают сохраняемое состояние отдельно от временного потока ответа модели. Независимые LLM-запросы подготовки остаются read-only; каталог вызывается сервером. Текст источников рассматривается как данные, а не инструкции агенту.
+
+Перед запуском, возобновлением и автоматическим исполнением сервер проверяет готовность задач и подборки. Подтверждение во время создания задач сохраняется, но не обходит готовность графа. Выбранные ресурсы попадают в контекст соответствующих задач с реальными путями. Повторные действия не должны дублировать импорты и запуски.
+
+Новая версия плана получает отдельную подборку; история предыдущей сохраняется. Старые проекты без подборки продолжают существующий workflow, пока пользователь отдельно не запускает подбор. Остановка отменяет незавершённую подготовку и исключает автоматический старт. Перезапуск сохраняет результаты и требует явного продолжения прерванной работы.
+
+## Источники и лицензии
+
+Предложения ограничены проверенными бесплатными CC0 и CC-BY с известными авторством и условиями. Сведения об атрибуции, лицензии, исходном ресурсе и изменениях сохраняются вместе с импортом для титров. Собственный файл сохраняет указанное пользователем происхождение; неизвестная лицензия не превращается автоматически в CC0.
+
+Каталог Kenney/OpenGameArt дополняет API Poly Haven и ambientCG для графики 2D, интерфейса, звуков и музыки. Результаты могут быть ограничены доступностью источника и количеством подходящих ресурсов; мастер показывает фактическое число вариантов. Подключения и ограничения описаны в [источниках ассетов](asset-providers.md).
+
+## Индикация и проверка
+
+Журнал отдельно показывает определение потребностей, поиск, ожидание выбора и импорт. Ожидание пользователя не отображается как работающая команда агента. Поиск показывает этапы и завершённые потребности; проценты загрузки вычисляются только при известном размере файла. Ошибка отдельного источника не уничтожает другие результаты. Выбор сохраняется при ошибке импорта и доступен для повторной попытки.
+
+Для приёмки нужны проверки параллельности, серверного запрета преждевременного запуска, восстановления, смены плана, отмены, повторного подтверждения и реальной связи файлов с задачами. Сквозные UI-проверки используют изолированные проекты: контролируемые модель/верификатор отдельно от проверок установленной LLM и живых источников. Фактические результаты публикуются в [журнале проверки](validation.md).

package/docs/automatic-approvals.md

@@ -0,0 +1,15 @@
+# Automatic local-agent action approvals
+
+`HubSettings.autoApproveActions` controls action approval inside Game Hub. The normalized default is `true` for fresh settings and older stored settings without the field; an explicit `false` preserves manual action approval. `PUT /api/v1/settings` accepts a boolean and persists it without changing provider models, global CLI configuration, operating-system permissions or browser security policy.
+
+All three provider bridges use the same workflow permission callback: Codex command/file-change approval, Claude tool authorization, and Kimi ACP permission requests. In automatic mode a current non-aborted action request immediately receives `{allow:true}`. No pending permission row or waiting-permission activity is created. The provider still controls its own sandbox and tool execution, and action authorization does not imply that the command or game task succeeded. Existing provider read-only denials continue to apply before this callback.
+
+`permission.auto_approved` records `{id,runId,method,createdAt}`. It contains no command arguments, file contents, query values or raw permission payload. The UI may show this actual decision in the journal. It must not fabricate a waiting card for a request already resolved automatically. The normal activity and task verification lifecycle determines success/failure.
+
+Interactive input is distinct: Codex `item/tool/requestUserInput` and Claude `AskUserQuestion` still require genuine user answers. Matching these method families keeps them in the existing question/permission path; the app never selects an answer or invents user preferences. Structured interview forms also remain explicit user input.
+
+Enabling the setting while this server owns an active run applies the policy to its existing pending action requests exactly once. It invokes the existing answer resolver, removes the pending row, emits `permission.resolved`, and emits the automatic-decision event. Input questions stay pending. Future callbacks read the current setting, so disabling automatic approval affects subsequent actions. No new task or run is started merely by changing the policy.
+
+An aborted run always denies a late callback. Startup recovery clears abandoned permission records and marks interrupted work; it cannot approve a dead provider process or replay an old action. A previous deployed server does not acquire this behavior just because the browser bundle changes: backend activation must respect active project work.
+
+Backend regressions cover Codex/Claude/Kimi callback families, no pending rows or wait states, real question answers, live policy enablement with exact-once resolution, persisted defaults/manual overrides, invalid input, command failure, post-stop callbacks and recovery. Existing subprocess Codex/Kimi protocol tests and Claude SDK mapping tests verify accept/deny response formats and read-only restrictions separately. No unrestricted provider flag or global CLI security setting is introduced.

package/docs/background-game-launch.md

@@ -0,0 +1,17 @@
+# Background game windows during development
+
+On macOS, the game Run action launches the installed Godot app through `/usr/bin/open -g -n -W`: `-g` requests no foreground activation, `-n` creates a separate instance, and `-W` keeps the launcher waiting for that instance. The actual game remains visible and can receive keyboard input when the user selects it. Explicitly opening the editor keeps its existing behavior. Automated imports, script/runtime checks and exports remain headless.
+
+The installed Steam Godot 4.7.2 `--headless --help` was checked: it does not advertise a `--no-focus` CLI option. Godot ignores unknown options, so adding that string would not establish background behavior. The project setting `display/window/size/no_focus` disables window focus/input; it is not used because the user must still be able to play the game. No project configuration is rewritten for background launch.
+
+`src/server/game-launch.ts` resolves the executable, validates its `.app/Contents/MacOS/<binary>` layout and builds argv without shell interpolation. A missing app bundle fails with an actionable error instead of launching an unrelated foreground program. Non-macOS platforms retain their existing direct process path: foreground policy there depends on the window manager, and guaranteed focus protection is not claimed.
+
+The macOS launcher creates a private temporary directory and passes a unique `--log-file` path as a supported Godot argument. Native stdout and stderr are redirected to separate private files through `open --stdout/--stderr`; the hub tails them with bounded buffers and UTF-8 decoding. Only captured output is emitted, never the process table used for ownership checks. The accumulated result is limited to2 MB. These temporary files are removed after completion/cleanup; user game files are not removed.
+
+LaunchServices owns the native game separately from the `open -W` child. The hub records process IDs present before launch and identifies only a new PID with the exact resolved executable and unique log argument. Before every TERM/KILL it rereads and validates that identity. PID reuse, other Godot windows, unmatched markers, current process and system PIDs cannot be targeted. Stop waits for native-process disappearance and uses a bounded escalation, while retaining the existing exclusive game-operation controller and single completion event. It never kills all Godot processes. LaunchServices errors and captured engine stderr remain visible; the launcher exit code is not represented as an independently observed native game exit code. Automated acceptance still uses directly owned headless engine processes.
+
+Every future implementation request includes the same development launch policy. Newly installed/refreshed managed `AGENTS.md` and `CLAUDE.md` sections include it too: automated tests headless, macOS visible game/exported-app smoke tests through `open -g -n -W`, no application activation/raising or global keyboard injection. Existing arbitrary agent shell commands are not rewritten. An already running model turn retains its previous prompt; a subsequent task request or safe pause/restart/resume receives the new policy.
+
+Focused tests use a controlled OS/process adapter rather than opening native windows. They verify argv boundaries with spaces/Cyrillic paths, exclusion of unsupported flags, normal log/cleanup behavior, owned cancellation, protection against PID reuse/unrelated processes, launch errors and instruction scope. Live focus/keyboard behavior is a separate acceptance check.
+
+References: installed macOS `man open` documents `-g`, `-n`, `-W` and output redirection; the [official Godot command-line tutorial](https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html) describes supported CLI behavior and unknown options; [Godot Window documentation](https://docs.godotengine.org/en/stable/classes/class_window.html) distinguishes no-focus windows from ordinary interactive game windows.