| 1 | # Playbook: организационный контур KB (white-label) |
| 2 | |
| 3 | **Статус:** active · v1.0 · 2026-05-19 |
| 4 | **Назначение:** как **любой** GitHub-org (не привязан к конкретному бренду) поднять три контура: **personal** · **group KB** · **kb-public** + MCP multi-root. |
| 5 | |
| 6 | **Аудитория:** основатель org, **canon-maintainer** (сборка public, seed group), **org-maintainer** (review PR в group). |
| 7 | |
| 8 | **Триггеры:** «своя org KB», «white-label», «развернуть kb у команды», `Acme/kb`, «как у kb-public но у нас», «group KB для организации». |
| 9 | |
| 10 | **Связано:** [`map-kb-three-contours-v1.md`](map-kb-three-contours-v1.md), [`playbook-knowledge-stack-clean-setup-v1.md`](playbook-knowledge-stack-clean-setup-v1.md) (участник: personal), [`adr/012-multi-canon-workspace-resolution-v1.md`](../adr/012-multi-canon-workspace-resolution-v1.md), MCP ADR 014/015 (в репозитории agent-notes-mcp). |
| 11 | |
| 12 | **Пример инстанса (не норма):** org `AI-Guiders`, репозитории `AI-Guiders/kb` и `AI-Guiders/kb-public` — одна реализация; в инструкциях ниже — плейсхолдеры `{ORG_SLUG}`. |
| 13 | |
| 14 | --- |
| 15 | |
| 16 | ## Именование (зафиксировать один раз) |
| 17 | |
| 18 | | Плейсхолдер | Пример | Репозиторий | |
| 19 | |-------------|--------|-------------| |
| 20 | | `{ORG_SLUG}` | `acme-corp` | GitHub org slug | |
| 21 | | `{REPO_GROUP}` | `acme-corp/kb` | private, командный канон | |
| 22 | | `{REPO_PUBLIC}` | `acme-corp/kb-public` | public, read-only срез | |
| 23 | |
| 24 | MCP id **`group`** и **`public`** — **технические**, не меняются при white-label. Пути клонов — в TOML на машине каждого участника. |
| 25 | |
| 26 | --- |
| 27 | |
| 28 | ## Стек (что форкают / что пишут сами) |
| 29 | |
| 30 | | Компонент | Лицензия / роль | Где живёт | |
| 31 | |-----------|-----------------|-----------| |
| 32 | | **agent-notes-mcp** | MIT (код) | отдельный репо или релиз; `dotnet publish` | |
| 33 | | **KB тексты** | CC BY-SA 4.0 в public/group | git | |
| 34 | | **Скрипты** `build-public-kb.ps1`, `seed-org-kb.ps1`, `push-public-kb.ps1` | в **source canon** maintainer’а | копируются в `{REPO_GROUP}/scripts/` при seed | |
| 35 | | **Личный канон** каждого участника | private | свой `agent-notes` (или fork) | |
| 36 | |
| 37 | Участнику **не обязательно** иметь source canon — достаточно `{REPO_PUBLIC}` + clone `{REPO_GROUP}` + свой personal. |
| 38 | |
| 39 | --- |
| 40 | |
| 41 | ## Фаза A — репозитории org |
| 42 | |
| 43 | 1. Создать GitHub org `{ORG_SLUG}`. |
| 44 | 2. **`{REPO_GROUP}`** — **private**, LICENSE CC BY-SA 4.0, wiki опционально. |
| 45 | 3. **`{REPO_PUBLIC}`** — **public**, тот же LICENSE на тексты. |
| 46 | 4. Команды: `{ORG_SLUG}/kb-maintainers` (review group), при необходимости отдельная для public push. |
| 47 | |
| 48 | Шаблоны корня group: [`templates/newcomer/template-org-kb-bootstrap-*.md`](../../templates/newcomer/README.md) — подставить `{ORG_SLUG}`, закоммитить в `{REPO_GROUP}`. |
| 49 | |
| 50 | --- |
| 51 | |
| 52 | ## Фаза B — source canon (у maintainer’а) |
| 53 | |
| 54 | Нужен **полный** клон канона с `knowledge/`, `scripts/`, `agent-notes.md` (форк upstream или свой monorepo maintainer’а). |
| 55 | |
| 56 | 1. Настроить `knowledge/public-kb.ignore` (что не в public). |
| 57 | 2. Настроить `knowledge/group-kb.ignore` — какие `work/projects/<scope>/` **не** экспортировать в group (личные/чувствительные scope). |
| 58 | 3. Пройти санитизацию карточек перед seed (без `C:\`, `D:\`, имён, `personal/`). |
| 59 | |
| 60 | Чеклист санитизации — в полном каноне maintainer’а (`knowledge/work/org/checklist-sanitize-paths-for-org-v1.md`); в kb-public его **нет** — это нормально. |
| 61 | |
| 62 | --- |
| 63 | |
| 64 | ## Фаза C — первая сборка public |
| 65 | |
| 66 | Из корня source canon (PowerShell): |
| 67 | |
| 68 | ```powershell |
| 69 | .\scripts\build-public-kb.ps1 |
| 70 | # артефакт: dist/public-kb/ |
| 71 | ``` |
| 72 | |
| 73 | Проверить `dist/public-kb/knowledge/` — без `work/`, `personal/`. Настроить `knowledge/public-kb.push` (локально, **не** в public): строка `https://github.com/{ORG_SLUG}/kb-public.git`. |
| 74 | |
| 75 | ```powershell |
| 76 | .\scripts\push-public-kb.ps1 |
| 77 | ``` |
| 78 | |
| 79 | --- |
| 80 | |
| 81 | ## Фаза D — seed group KB |
| 82 | |
| 83 | ```powershell |
| 84 | .\scripts\build-public-kb.ps1 # если ещё не |
| 85 | .\scripts\seed-org-kb.ps1 # dist/group-kb/ |
| 86 | ``` |
| 87 | |
| 88 | Содержимое: public slice + отфильтрованный `work/projects/` + каталог **`knowledge/work/org/`** (contour map, чеклист; **норма для kb-public** — [`templates/work/template-scope-contour-map-v1.md`](../../templates/work/template-scope-contour-map-v1.md)) + `scripts/` + шаблоны из `scripts/kb-org-root/`. Опционально: переименование scope-каталога при копировании (см. [`map-kb-three-contours-v1.md`](map-kb-three-contours-v1.md) § Scope contour map). |
| 89 | |
| 90 | Пуш в `{REPO_GROUP}` (maintainer): заменить содержимое репо (сохранить при необходимости `knowledge/group/smoke-test-v1.md` для smoke). |
| 91 | |
| 92 | **Smoke для участников:** файл `knowledge/group/smoke-test-v1.md` в group — проверка `read_knowledge_file(..., knowledge_root_id=group)`. |
| 93 | |
| 94 | --- |
| 95 | |
| 96 | ## Фаза E — участник (personal + чтение group/public) |
| 97 | |
| 98 | Не дублирует весь [`playbook-knowledge-stack-clean-setup-v1.md`](playbook-knowledge-stack-clean-setup-v1.md); только **добавка** к уже настроенному personal. |
| 99 | |
| 100 | 1. Клон `{REPO_PUBLIC}` и (по доступу) `{REPO_GROUP}`. |
| 101 | 2. TOML — шаблон [`template-clean-setup-agent-notes-mcp-toml-v1.toml`](../../templates/newcomer/template-clean-setup-agent-notes-mcp-toml-v1.toml): `primary = "personal"`, `[[knowledge.read_only]]` id `public` и `group`. |
| 102 | 3. `work/local/knowledge-roots-index-v1.md` — какие пути только в group/public (шаблон newcomer). |
| 103 | 4. Hot-секция `knowledge-roots-routing-v1` в personal `agent-notes.md`. |
| 104 | 5. Проверка: read group smoke, write в group → отклонение; write в personal → OK. |
| 105 | |
| 106 | **Участник не пушит** в group без роли; предлагает PR или правки в personal. |
| 107 | |
| 108 | --- |
| 109 | |
| 110 | ## Фаза F — governance (кратко) |
| 111 | |
| 112 | | Роль | Зона | |
| 113 | |------|------| |
| 114 | | **org-maintainer** | PR review в `{REPO_GROUP}` | |
| 115 | | **canon-maintainer** | `build-public-kb`, `push-public-kb`, `seed-org-kb`, import в source canon | |
| 116 | | **Участник** | personal git; read group/public через MCP | |
| 117 | |
| 118 | Обратный поток group → personal — **вручную** (cherry-pick / import), не автосинк. |
| 119 | |
| 120 | --- |
| 121 | |
| 122 | ## Поведение агента |
| 123 | |
| 124 | 1. «Своя org KB» / white-label → **этот playbook**, не ADR конкретного бренда. |
| 125 | 2. Не подставлять чужой `{ORG_SLUG}` в TOML пользователя. |
| 126 | 3. Различать: **founder** (фазы A–D) vs **участник** (фаза E). |
| 127 | 4. Ссылки на `AI-Guiders/*` в kb-public — только как **пример**, если файл исторический (ADR 011); норматив — плейсхолдеры. |
| 128 | |
| 129 | --- |
| 130 | |
| 131 | ## DoD (минимум) |
| 132 | |
| 133 | - [ ] `{REPO_PUBLIC}` открывается, `knowledge/` без `work/`/`personal/`. |
| 134 | - [ ] `{REPO_GROUP}` private, smoke читается через MCP `knowledge_root_id=group`. |
| 135 | - [ ] Участник: personal primary, group/public read-only, реестр roots заполнен. |
| 136 | - [ ] CONTRIBUTING + CODEOWNERS в group из шаблонов newcomer. |
| 137 | |
| 138 | --- |
| 139 | |
| 140 | ## Связанные шаблоны |
| 141 | |
| 142 | | Шаблон | Назначение | |
| 143 | |--------|------------| |
| 144 | | `templates/newcomer/template-org-kb-bootstrap-contributing-v1.md` | CONTRIBUTING для `{REPO_GROUP}` | |
| 145 | | `templates/newcomer/template-org-kb-bootstrap-codeowners-v1.md` | CODEOWNERS | |
| 146 | | `templates/newcomer/template-org-kb-bootstrap-readme-group-v1.md` | README корня group | |
| 147 | | `templates/newcomer/template-clean-setup-*` | personal + MCP у участников | |
| 148 | |
| 149 | |