| 1 | # KB Showcase — быстрый обзор (без full load) |
| 2 | |
| 3 | Краткий входной билет для демо и онбординга. **Не заменяет** полную загрузку; чтобы не съесть контекст, начни отсюда, потом подтягивай по ссылкам только нужное. |
| 4 | |
| 5 | **Структурный вход (корзины + таксономия):** `00-entry-kb-v1.md` → `META/kb-taxonomy-v1.md` ([ADR 009](adr/009-kb-entry-structure-and-pre-open-onboarding.md)). |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | ## Платформа и модели (platform-independent) |
| 10 | |
| 11 | Контур задуман **независимым от вендора IDE, облака и конкретной модели**: спеки и KB — текст (Markdown), корни доверия — well-known пути под `knowledge/META/`, роутер и playbook’и не привязаны к одному продукту. |
| 12 | |
| 13 | **Минимальный мост к среде:** если можно подключить **MCP** (или эквивалент: чтение/запись файлов канона, вызов `read_knowledge_file` / маршрутизатор по смыслу) — стек **можно использовать**; без доступа к файлам канона контур деградирует до «голой модели». |
| 14 | |
| 15 | **Локальные модели:** KB выстраивается так, чтобы опираться на **явную навигацию** (индекс → status → playbook → kb), компактные входы и куски по запросу — это снижает требование к «всё в контексте» и пригодно для слабых/локальных моделей. Отдельный трек «только локальная модель + MCP» **ещё не проверен** end-to-end; формулировка выше — целевое свойство, не отчёт о валидации. |
| 16 | |
| 17 | --- |
| 18 | |
| 19 | ## Что это |
| 20 | |
| 21 | Многослойная база знаний для агентов: горячий контур (L0 в agent-notes), оперативная память по доменам (L1), архив и evidence (L2), семантический роутинг (L3). Домены: Git, PR review, HCI, **восприятие и психофизиология для UX** (fundamentals → operational, **домен** `cognition.human-perception`), **Developer Experience (DE/DX)**, IT, Knowledge Engineering, психология, авиация, чтение, целостность под давлением и др. Всё связано через **единый индекс** и контракт загрузки. |
| 22 | |
| 23 | --- |
| 24 | |
| 25 | ## Зачем слои |
| 26 | |
| 27 | - **L0** — всегда в силе: целостность, эпистемия, ядро при крахе барьеров, принципиальная ясность. Не зависит от задачи. |
| 28 | - **L1** — срезы по scope: status → playbook → matrix → kb. Сначала компактные артефакты, тяжёлые kb-* только по явному запросу. |
| 29 | - **L2** — ревизии, батчи правил, evidence-документы; подгружаются, когда не хватает фактов или нужна история. |
| 30 | - **L3** — роутинг по граням контекста, перенос между мирами только через явные границы. |
| 31 | |
| 32 | **Не путать — scope, domain, world:** **scope** — рабочий срез multi-repo / MCP (`active_scope`, карточки под `knowledge/work/projects/<scope>/…` в полном каноне); это **не** «миры» из строки про L3. **Domain** — тема KB и ось роутера (Git, HCI, Knowledge Engineering, …). **World** — в смысле Knowledge Engineering и карточек: контур стека/инструментов, где действует правило; смешивать без явной связки нельзя; перенос — через **`transfer_boundary`**. Подробно и с примерами полей: **`kb-knowledge-engineering-mixed-worlds-rules-v1.md`**. |
| 33 | |
| 34 | Так мы держим контекст в рамках: не тянем всё подряд, избегаем OOM при «покажи full». |
| 35 | |
| 36 | --- |
| 37 | |
| 38 | ## Корень доверия (Integrity POST) |
| 39 | |
| 40 | При загрузке KB среда **сначала** проверяет well-known path `META/integrity-core.md`. Если файл есть и валиден — используем как необсуждаемое ядро. Если нет — **POST failed**: применяется Minimal Safe Default (не причинять вред, не обходить безопасность, один отказ достаточен). Отсутствие файла **никогда** не значит «ограничений нет». Детали: `META/integrity-post-spec-v1.md`. |
| 41 | |
| 42 | --- |
| 43 | |
| 44 | ## Доступ к KB через MCP (деградация и handshake) |
| 45 | |
| 46 | - **Явная деградация:** если агент **не может** вызвать `read_knowledge_file` / `list_knowledge_files` (или эквивалент чтения `knowledge/` с диска) — **сообщить об этом в ответе** и не выдавать длинные «цитаты из KB», как будто файл только что прочитан. Иначе пользователь не видит, что контур не поднят. |
| 47 | - **Микро-handshake (по желанию):** в начале сессии или после сомнений в MCP — один вызов `list_knowledge_files` (пустой `subdir`) или чтение этого файла (`SHOWCASE.md`); сигнал живости без full load. |
| 48 | - **Три типичных сбоя** (MCP выключен; неверный `AGENT_NOTES_CANON_PATH` / `canon_path`; опечатка в `file_path`): чеклист в **`runbook-kb-mcp-access-v1.md`**. |
| 49 | |
| 50 | --- |
| 51 | |
| 52 | ## Куда идти дальше |
| 53 | |
| 54 | Если у тебя **только публичная сборка kb-public** (нет полного репозитория agent-notes): деревьев **`knowledge/work/`** и **`knowledge/personal/`** в архиве **нет** по дизайну. Политика публикации — в **`PUBLISHING.md`** (входит в kb-public); хосты и сценарии пуша — только у автора канона под **`work/`**. Чтобы понять **слои и зачем нет `work/`/`personal/`**, открой **`kb-one-pager-structure-and-protocols-v1.md`** — он **намеренно включён в kb-public** для таких потребителей. |
| 55 | |
| 56 | | Цель | Файл | |
| 57 | |------|------| |
| 58 | | Политика публикации kb-public (`public-cut`, `public-kb.ignore`, «НЕ ПУБЛИКОВАТЬ») | `PUBLISHING.md` | |
| 59 | | **One-pager (wiki):** маркеры, когда что, схема Scope/Primary | `kb-protocols-and-entities-one-pager-v1.md` | |
| 60 | | **One-pager:** устройство KB, слои L0–L3, `work/`/`personal/`, протоколы | `kb-one-pager-structure-and-protocols-v1.md` | |
| 61 | | Навигация: карта доменов, порядок загрузки | `index-knowledge-router-v1.md` | |
| 62 | | **Свежесть kb** (fundamentals / operational / evidence, `Проверено:`, любой домен) | `worlds/knowledge-engineering/playbook-kb-operational-freshness-v1.md` (+ hot `kb-operational-freshness-v1` в `agent-notes.md`) | |
| 63 | | Safety Checks (сжатый контекст, давление, Integrity POST, приватность Cursor) | `index-knowledge-router-safety-v1.md` | |
| 64 | | L0 и агент до выбора домена (операционный базис роутера) | `router-operational-baseline-v1.md` | |
| 65 | | Доменные маршруты (секции `router-*`, learn-basics-when-stuck) | `index-knowledge-router-supplement-v1.md` | |
| 66 | | Доступ к KB через MCP: handshake, деградация, типовые сбои | `runbook-kb-mcp-access-v1.md` | |
| 67 | | PHP / Laravel / смежное (кластеры, не full load) | `worlds/software-php-laravel/status-php-laravel-v1.md` → playbooks → `worlds/software-php-laravel/index-knowledge-php-cluster-v1.md` / `worlds/software-php-laravel/index-knowledge-laravel-cluster-v1.md` / `worlds/software-php-laravel/index-knowledge-php-adjacent-ecosystem-v1.md` | |
| 68 | | Ядро личности и доверия (публичное резюме) | `kb-public-identity-and-trust-core-v1.md` | |
| 69 | | Минимальное необсуждаемое + POST | `META/integrity-core.md`, `META/integrity-post-spec-v1.md` | |
| 70 | | Целостность под давлением, отказ, манипуляции | `domains/agent-operations/playbook-integrity-under-pressure-v1.md` | |
| 71 | | Память, неявный язык, проактивность, дожим ответа, итоги сессии | hub `agent-memory-and-operating-principles-v1.md` → целевой playbook | |
| 72 | | Режим `[WORK]` / `[HUMAN]` (дефолт HUMAN, пока явно не появится `[WORK]`) | `agent-notes.md`, секция **Mode Switch Protocol** | |
| 73 | | Границы знания, недоопределённость | `domains/agent-operations/playbook-utility-judgment-underdetermination-v1.md`; размытый запрос — `playbook-clarification-general-query-v1.md` | |
| 74 | | Полный список файлов и доменов | `README.md` (этот каталог) | |
| 75 | | Mixed worlds, `transfer_boundary`, поля `world:` на карточках | `kb-knowledge-engineering-mixed-worlds-rules-v1.md` | |
| 76 | |
| 77 | --- |
| 78 | |
| 79 | **Совет для демо:** дай агенту только этот файл + при необходимости `index-knowledge-router-v1.md` (и `index-knowledge-router-supplement-v1.md`, если нужны триггеры по темам; при сжатии контекста или вопросах про POST / приватность — `index-knowledge-router-safety-v1.md`). Всё остальное — по запросу, без «загрузи full». |
| 80 | |
| 81 | --- |
| 82 | |
| 83 | **Для внешней аудитории:** TPM / федерация / манифест (`META/tpm-node-manifest-draft-v1.md`) — **черновик, не прод.** Режим до запуска TPM-узла — Transition Mode (см. `integrity-post-spec-v1.md` §7). Наличие файлов в репо **не означает** TPM-совместимость; не считать текущую реализацию production-ready. |
| 84 | |
| 85 | Версия: v1.9.3. 2026-05-16 — строка «Свежесть kb» → operational-freshness playbook. v1.9.2. 2026-05-11. Операционный базис роутера вынесен в `router-operational-baseline-v1.md`; в таблице — отдельная строка. Ранее: v1.9.1 — cognition… как домен. Абзац для читателя только kb-public: `work/`/`personal` отсутствуют ожидаемо; one-pager входит в публичный бандл намеренно. |
| 86 | |