| 1 | # Map: три контура KB (канон · публичное · workspace) |
| 2 | |
| 3 | **Назначение:** снять когнитивное трение «что в каком репо и куда писать». Одна страница для **агента** (диспетчер) и для **человека** (approve). Не заменяет `PUBLISHING.md`, `kb-one-pager-structure-and-protocols-v1.md`, `playbook-kb-operational-freshness-v1.md` — **сводит** их в схему действий. |
| 4 | |
| 5 | **Статус:** active · v1.5 · 2026-05-19 |
| 6 | **Именование репозиториев:** ниже **`{ORG_SLUG}/kb`** и **`{ORG_SLUG}/kb-public`** — плейсхолдеры вашей GitHub-организации. Пример инстанса: `AI-Guiders/kb` (не обязателен для читателя kb-public). |
| 7 | |
| 8 | **Поднять свой org:** [`playbook-org-kb-white-label-v1.md`](playbook-org-kb-white-label-v1.md). |
| 9 | |
| 10 | --- |
| 11 | |
| 12 | ## Контуры (не путать; group KB — между personal и public) |
| 13 | |
| 14 | | # | Контур | Где физически | MCP / chmod | Кто обычно пишет | |
| 15 | |---|--------|---------------|-------------|------------------| |
| 16 | | **1** | **Канон** (user) | личный **`agent-notes`** (или fork) | primary / **u** | Держатель канона; git `main` | |
| 17 | | **2a** | **Group KB** | **`{ORG_SLUG}/kb`** private | `knowledge_root_id=group` / **g** | PR + **org-maintainer** review | |
| 18 | | **2b** | **Public KB** | **`{ORG_SLUG}/kb-public`** | `public` / **o** | **Canon-maintainer** — `build-public-kb.ps1` | |
| 19 | | **3** | **Workspace** | корни IDE, product repos | код, hot-зеркало | Код в product repos; знания — в **1** | |
| 20 | |
| 21 | **Не четвёртый контур:** `knowledge/work/` и `knowledge/personal/` — **внутри канона (1)**; в kb-public **не попадают** по дизайну. Внутри `work/`: **`local/`** (машина) · **`org/`** (seed в group) · **`projects/`** (карточки) — см. [`work/README.md`](../../work/README.md). |
| 22 | |
| 23 | ```text |
| 24 | [Workspace] copy/sync [Канон personal — agent-notes] |
| 25 | │ work/local/maps │ git commit + push |
| 26 | └──────────────► agent-notes.md ◄───────┘ |
| 27 | │ export (sanitize) |
| 28 | ▼ |
| 29 | [{ORG_SLUG}/kb — group KB] |
| 30 | │ build-public-kb.ps1 |
| 31 | ▼ |
| 32 | [{ORG_SLUG}/kb-public] |
| 33 | ``` |
| 34 | |
| 35 | --- |
| 36 | |
| 37 | ## Куда что класть (шпаргалка) |
| 38 | |
| 39 | | Содержание | Контур | Путь / действие | |
| 40 | |------------|--------|-----------------| |
| 41 | | Playbook, kb, роутер, META, worlds | **1 Канон** | `knowledge/...` в personal | |
| 42 | | L0, stub секций, `public-cut` | **1 Канон** | `agent-notes.md` (выше cut → может уйти в public) | |
| 43 | | Карточка проекта, operational | **1**, слой work | `knowledge/work/projects/...` (не в kb-public) | |
| 44 | | Черновик «только мне» | **1**, personal | `knowledge/personal/...` | |
| 45 | | C#, решение, тесты | **3 Workspace** | product repo | |
| 46 | | Правка знаний из чата | **1** | обновить канон; workspace-hot — зеркало | |
| 47 | | Показать миру обезличенную KB | **2b** | сборка из **1**, push kb-public | |
| 48 | |
| 49 | --- |
| 50 | |
| 51 | ## Scope contour map (personal scope → group KB) |
| 52 | |
| 53 | **Норма для kb-public (механика + шаблон):** [`templates/work/template-scope-contour-map-v1.md`](../../templates/work/template-scope-contour-map-v1.md) — таблица, правила, чеклист maintainer; **без** имён конкретной org. |
| 54 | |
| 55 | **Суть:** в personal каноне `work/projects/<personal-scope>/` может называться по **личной** метафоре; в **group KB** (`{ORG_SLUG}/kb`) участникам нужен **нейтральный** каталог `work/projects/<group-scope-dir>/`. Таблица связывает personal scope, group-префикс и человекочитаемый label. Не путать с `workspace-scope-map` (диск → slice) и `scope-alias-map` (алиас → тот же slice). |
| 56 | |
| 57 | **Seed:** `seed-org-kb.ps1` добавляет отфильтрованный `work/projects/`; опционально **rename верхнего префикса** по таблице maintainer'а. `project-id` внутри (хаб workspace) **может отличаться** от имени scope-каталога. |
| 58 | |
| 59 | **Заполненный экземпляр** (конкретные строки одного maintainer'а): `knowledge/work/org/scope-contour-map-v1.md` — каталог **`work/org/`** в group после seed; **не** в kb-public. Обзор слоёв `work/`: [`work/README.md`](../../work/README.md). |
| 60 | |
| 61 | --- |
| 62 | |
| 63 | ## Sync: workspace hot ↔ канон |
| 64 | |
| 65 | - **Правда** — контур **1** (git personal). |
| 66 | - Hot в workspace — зеркало; после правок — в канон и commit. |
| 67 | - Агент не считает workspace-файл каноном, если `AGENT_NOTES_CANON_PATH` указывает на клон personal. |
| 68 | |
| 69 | --- |
| 70 | |
| 71 | ## Роли: агент vs человек |
| 72 | |
| 73 | | Действие | Агент | Человек | |
| 74 | |----------|-------|---------| |
| 75 | | «В каком контуре править» | ✅ по этой карте | approve | |
| 76 | | `build-public-kb`, push kb-public | preview | **canon-maintainer** | |
| 77 | | PR в group KB | подготовка diff | **org-maintainer** | |
| 78 | |
| 79 | --- |
| 80 | |
| 81 | ## Быстрые ссылки (kb-public) |
| 82 | |
| 83 | | Вопрос | Файл | |
| 84 | |--------|------| |
| 85 | | Что в kb-public | `knowledge/PUBLISHING.md` | |
| 86 | | Слои L0–L3 | `knowledge/kb-one-pager-structure-and-protocols-v1.md` | |
| 87 | | Свой org с нуля | `knowledge/domains/agent-operations/playbook-org-kb-white-label-v1.md` | |
| 88 | | Участник: personal + MCP | `knowledge/domains/agent-operations/playbook-knowledge-stack-clean-setup-v1.md` | |
| 89 | | Маркеры PRIMARY/SCOPE | `knowledge/domains/agent-operations/playbook-project-switch-v1.md` | |
| 90 | |
| 91 | --- |
| 92 | |
| 93 | ## Триггер для роутера / агента |
| 94 | |
| 95 | «в каком репо», «куда записать», «три репозитория», «kb-public vs agent-notes», «свой org KB», «white-label», «синк заметок», **«personal scope vs group catalog»**, **«scope contour»** → **сначала этот файл**, затем узкий playbook. |
| 96 | |
| 97 | |