ai-commons 0.2.10 → 0.2.12

package/README.md

@@ -1,78 +1,61 @@
 # ai-commons
 
-Общие правила для Claude Code + автосохранение диалогов. Поставляется как
-npm-зависимость. После `npm install` в проекте появляется:
-
-- В корневом `CLAUDE.md` — управляемый блок между метками:
-  ```
-  <!-- ai-commons:begin -->
-  ... @node_modules/ai-commons/AGENTS.md ...
-  <!-- ai-commons:end -->
-  ```
-  Этот блок **обновляется хуком** при каждом старте сессии. Всё, что в файле
-  снаружи блока, — твоё, не трогается. Если `CLAUDE.md` не было — создастся
-  с одним блоком.
-- Хуки в `.claude/settings.json`:
-  - `SessionStart` — обновляет блок в `CLAUDE.md` на каждом старте сессии.
-  - `Stop` и `SessionEnd` — сохраняют диалог в `.ai-dialogs/YYMMDD-HHII-<topic>.md`.
-- Запись `.ai-dialogs/` в `.gitignore`.
+Общие правила для AI-агентов + автосохранение Claude-диалогов. Поставляется
+как npm-зависимость и поддерживает четыре популярных таргета:
 
-## Установка в новый проект
+| Агент / стандарт | Файл в потребителе | Режим |
+|---|---|---|
+| Claude Code | `CLAUDE.md` | управляемый блок (`@AGENTS.md` import) |
+| OpenAI Codex / стандартный AGENTS.md | `AGENTS.md` | управляемый блок (встроенное содержимое) |
+| Cursor | `.cursor/rules/ai-commons.mdc` | весь файл принадлежит ai-commons |
 
-```bash
-cd my-new-project
-npm i -D /Users/os/okneigres-repos/ai-commons
-```
+В файлах с управляемым блоком (`CLAUDE.md`, `AGENTS.md`) содержимое между
+метками `<!-- ai-commons:begin -->` и `<!-- ai-commons:end -->`
+перезаписывается; всё остальное в файле — твоё, не трогается.
 
-Или, если опубликовано в реестре:
+Дополнительно для Claude:
 
-```bash
-npm i -D ai-commons
-```
+- `SessionStart`-хук обновляет все три target-файла на каждом старте сессии.
+- `Stop` / `SessionEnd`-хук сохраняет диалог в
+  `.ai-dialogs/YYMMDD-HHII-<topic>.md`.
+- `.ai-dialogs/` добавляется в `.gitignore`.
 
-`postinstall` всё настраивает автоматически. Запустить вручную:
+## Установка в новый проект
 
 ```bash
-npx ai-commons install
+cd my-new-project
+npm init -y                                             # если package.json ещё нет
+npm i -D /Users/os/okneigres-repos/ai-commons
 ```
 
-## Откат
+`postinstall` всё настраивает автоматически. Запустить вручную:
 
 ```bash
-npx ai-commons uninstall
-# затем удалить зависимость:
-npm uninstall ai-commons
+npx ai-commons install      # идемпотентно: можно гонять сколько угодно раз
+npx ai-commons uninstall    # снять блоки, хуки и Cursor-файл
 ```
 
-`uninstall` уберёт блок `ai-commons` из `CLAUDE.md` (сам файл остаётся, если в
-нём есть другое содержимое — удаляется только если оказался пустым) и
-вычистит хуки `ai-commons` из `.claude/settings.json`, не трогая чужие хуки.
+## Правила
 
-## Уровни правил
-
-`AGENTS.md` в этом репо разбит на три секции:
-
-- **MUST** — обязательно, игнорировать нельзя ни при каких обстоятельствах
-  (например: не пушить force в main, не коммитить секреты).
-- **Желательно** — стандарт по умолчанию, отступать можно только с явной
-  причиной (например: краткие ответы, без избыточных абстракций).
-- **Остальное** — стиль и привычки (например: `curl` одной строкой,
-  ссылки на код в формате `path:line`).
+Лежат в [`RULES.md`](RULES.md) — это публичный контракт, его содержимое
+`targets.js` копирует во все target-файлы потребителей. `AGENTS.md` в
+этом репо — заметки для работы над самим `ai-commons`, в потребителей
+не попадает.
 
 ## Как обновить правила во всех проектах
 
-1. Правишь `AGENTS.md` здесь.
+1. Правишь `RULES.md` здесь.
 2. `git commit && git push` (или просто коммит, если репо локальный).
-3. В каждом потребителе: `npm update ai-commons` (или `npm install`, если
-   зависимость через `file:`).
-
-Содержимое подгружается Claude Code через `@`-импорт каждый сеанс, поэтому
-после обновления `node_modules/ai-commons/AGENTS.md` следующая сессия
-увидит новые правила автоматически.
+3. В каждом потребителе:
+   - **Claude**: ничего делать не надо — `SessionStart`-хук подтянет новые
+     правила в следующей сессии (для `file:`-зависимостей) или после
+     `npm update ai-commons` (для опубликованных).
+   - **Codex / Cursor**: `npm install` (или `npx ai-commons install`) —
+     перепишет блоки и Cursor-файл.
 
-## Сохранение диалогов
+## Сохранение диалогов (только Claude)
 
-После каждого Claude Stop (и при завершении сессии) хук пишет
+После каждого Claude `Stop` (и при завершении сессии) хук пишет
 `.ai-dialogs/YYMMDD-HHII-<topic>.md`:
 
 - Timestamp — момент первой реплики пользователя в сессии.
@@ -89,15 +72,17 @@ npm uninstall ai-commons
 
 ```
 ai-commons/
-├── AGENTS.md                          — правила, импортируются потребителями
+├── RULES.md                           — источник правды (правила), копируется в потребителей
+├── AGENTS.md                          — заметки для работы над самим ai-commons
 ├── package.json                       — bin + postinstall
 ├── bin/ai-commons.js                  — CLI: install / uninstall
 ├── scripts/
 │   ├── postinstall.js                 — npm-хук, запускает installer.install
-│   ├── installer.js                   — pointer-блок + merge hooks + .gitignore
-│   └── managed-block.js               — хелперы для блока в CLAUDE.md
+│   ├── installer.js                   — установка/удаление в потребителе
+│   ├── targets.js                     — список таргет-файлов (Claude/Codex/Cursor)
+│   └── managed-block.js               — вставка/обновление блока в markdown
 └── hooks/
-    ├── ensure-rules-pointer.js        — SessionStart-хук
+    ├── ensure-rules-pointer.js        — SessionStart-хук (рефреш всех таргетов)
     └── save-dialog.js                 — Stop / SessionEnd-хук
 ```
 
@@ -107,7 +92,9 @@ ai-commons/
 
 ## Что не делается
 
-- `ai-commons` **не** распространяет общие сабагенты/скиллы/слэш-команды.
-  Этот скоуп умышленно убран — если понадобится, добавим отдельной командой
-  `ai-commons sync-agents`.
-- `permissions` и `env` из `settings.json` потребителя не трогаются.
+- `permissions` и `env` из `settings.json` потребителя не трогаются — только
+  свой набор хуков (SessionStart / Stop / SessionEnd) мержится.
+- Старый формат Cursor (`.cursorrules` в корне) не поддерживается — только
+  современный `.cursor/rules/*.mdc`.
+- Автосейв диалогов реализован только для Claude (у других агентов нет
+  аналогичных hook'ов).

package/RULES.md

@@ -0,0 +1,5 @@
+# ai-commons — общие правила
+
+- **Установи `git-coherent` в проект**: `npm i -D git-coherent`.
+- **Логи диалогов сохраняй в `.ai-dialogs/YYMMDD-HHII-short-topic-name.md`**.
+- `curl`-примеры — одной строкой, без переносов `\`.

package/hooks/ensure-rules-pointer.js

@@ -1,14 +1,11 @@
 #!/usr/bin/env node
-// SessionStart hook: ensures the consumer's root CLAUDE.md contains an
-// up-to-date ai-commons block. The block lives between
-// `<!-- ai-commons:begin -->` and `<!-- ai-commons:end -->` markers; any
-// content OUTSIDE the markers is preserved.
+// SessionStart hook: re-applies ai-commons rule files in the consumer
+// project. This refreshes the managed block in CLAUDE.md / AGENTS.md and
+// the full .cursor/rules/ai-commons.mdc file using the latest content from
+// node_modules/ai-commons/RULES.md.
 
 const fs = require('fs');
-const path = require('path');
-const { applyBlock } = require('../scripts/managed-block');
-
-const POINTER_FILE = 'CLAUDE.md';
+const { applyAllTargets } = require('../scripts/targets');
 
 function readStdinJson() {
   try {
@@ -23,22 +20,14 @@ function main() {
   const input = readStdinJson();
   const cwd = input.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
   if (!cwd || !fs.existsSync(cwd)) {
-    process.stderr.write('[ai-commons] no cwd, skipping pointer refresh\n');
+    process.stderr.write('[ai-commons] no cwd, skipping refresh\n');
     process.exit(0);
   }
 
-  const pointerPath = path.join(cwd, POINTER_FILE);
-  const existing = fs.existsSync(pointerPath)
-    ? fs.readFileSync(pointerPath, 'utf8')
-    : null;
-  const next = applyBlock(existing);
-
-  if (existing != null && next === existing) {
-    process.exit(0);
+  const results = applyAllTargets(cwd);
+  for (const { target, result } of results) {
+    process.stderr.write(`[ai-commons] ${target.id}: ${target.file} ${result}\n`);
   }
-
-  fs.writeFileSync(pointerPath, next);
-  process.stderr.write(`[ai-commons] refreshed block in ${POINTER_FILE}\n`);
   process.exit(0);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-commons",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "Shared Claude Code rules + dialog-saver hook for projects",
   "bin": {
     "ai-commons": "bin/ai-commons.js"
@@ -13,7 +13,7 @@
     "bin",
     "scripts",
     "hooks",
-    "AGENTS.md",
+    "RULES.md",
     "README.md"
   ],
   "engines": {

package/scripts/installer.js

@@ -1,5 +1,5 @@
 // Installs ai-commons into a consumer project:
-//   - writes/refreshes the root CLAUDE.md pointer
+//   - writes/refreshes rule files for Claude / Codex / Cursor (see targets.js)
 //   - merges our hooks into .claude/settings.json (preserving any existing hooks)
 //   - ensures .ai-dialogs/ is gitignored
 //
@@ -8,10 +8,9 @@
 
 const fs = require('fs');
 const path = require('path');
-const { applyBlock, removeBlock } = require('./managed-block');
+const { applyAllTargets, removeAllTargets } = require('./targets');
 
 const PACKAGE_NAME = require('../package.json').name;
-const POINTER_FILE = 'CLAUDE.md';
 const SETTINGS_FILE = path.join('.claude', 'settings.json');
 const GITIGNORE_FILE = '.gitignore';
 
@@ -39,20 +38,11 @@ function readJsonOrEmpty(p) {
   }
 }
 
-function writePointer(consumerRoot) {
-  const pointerPath = path.join(consumerRoot, POINTER_FILE);
-  const existing = fs.existsSync(pointerPath)
-    ? fs.readFileSync(pointerPath, 'utf8')
-    : null;
-  const next = applyBlock(existing);
-  if (existing != null && next === existing) return false;
-  fs.writeFileSync(pointerPath, next);
-  log(
-    existing == null
-      ? `created ${POINTER_FILE} with ai-commons block`
-      : `refreshed ai-commons block in ${POINTER_FILE}`
-  );
-  return true;
+function writeRuleFiles(consumerRoot) {
+  const results = applyAllTargets(consumerRoot);
+  for (const { target, result } of results) {
+    log(`${target.id}: ${target.file} ${result}`);
+  }
 }
 
 function stripManagedHooksFromEvent(eventEntries) {
@@ -101,26 +91,18 @@ function install(consumerRoot) {
   if (!consumerRoot || !fs.existsSync(consumerRoot)) {
     throw new Error(`Invalid consumer root: ${consumerRoot}`);
   }
-  writePointer(consumerRoot);
+  writeRuleFiles(consumerRoot);
   mergeHooks(consumerRoot);
   ensureGitignore(consumerRoot);
   log('install complete');
 }
 
 function uninstall(consumerRoot) {
-  // Strip our managed block from the pointer file. Leave any user-written
-  // content intact; remove the file only if it ends up empty.
-  const pointerPath = path.join(consumerRoot, POINTER_FILE);
-  if (fs.existsSync(pointerPath)) {
-    const existing = fs.readFileSync(pointerPath, 'utf8');
-    const next = removeBlock(existing);
-    if (next.trim() === '') {
-      fs.rmSync(pointerPath);
-      log(`removed empty ${POINTER_FILE}`);
-    } else if (next !== existing) {
-      fs.writeFileSync(pointerPath, next);
-      log(`removed ai-commons block from ${POINTER_FILE}`);
-    }
+  // Strip our managed content from each target file. Leave user content
+  // intact; remove block-mode files only if they end up empty.
+  const results = removeAllTargets(consumerRoot);
+  for (const { target, result } of results) {
+    log(`${target.id}: ${target.file} ${result}`);
   }
 
   // Strip our hooks from settings.

package/scripts/managed-block.js

@@ -1,44 +1,50 @@
-// Shared helpers for inserting/updating the ai-commons block inside a
-// host markdown file (typically the consumer's CLAUDE.md).
+// Helpers for inserting/updating an ai-commons block inside a host markdown
+// file (CLAUDE.md, AGENTS.md, etc.). The block content is passed in by the
+// caller, so this module is target-agnostic.
 
-const PACKAGE_NAME = 'ai-commons';
 const BEGIN = '<!-- ai-commons:begin -->';
 const END = '<!-- ai-commons:end -->';
 
-const BLOCK_BODY = [
-  BEGIN,
-  '<!-- Managed by ai-commons. Anything between these markers is overwritten -->',
-  '<!-- on every Claude Code session start. To change rules, edit AGENTS.md  -->',
-  '<!-- in the ai-commons repo. Everything OUTSIDE these markers is yours.   -->',
-  `@node_modules/${PACKAGE_NAME}/AGENTS.md`,
-  END,
+const HEADER_COMMENTS = [
+  '<!-- Managed by ai-commons. Content between these markers is auto-generated.   -->',
+  '<!-- To change rules, edit RULES.md in the ai-commons repo and re-run          -->',
+  '<!-- `npm install` in this project (Claude users get auto-refresh on session). -->',
 ].join('\n');
 
 function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-const BLOCK_RE = new RegExp(`${escapeRegex(BEGIN)}[\\s\\S]*?${escapeRegex(END)}`);
+// Greedy on purpose: if marker strings somehow appear inside the rendered
+// body, we still match the OUTERMOST begin..end pair instead of stopping
+// at the first nested-looking end.
+const BLOCK_RE = new RegExp(`${escapeRegex(BEGIN)}[\\s\\S]*${escapeRegex(END)}`);
 
-// Returns the host content with our managed block inserted/refreshed.
+function buildBlock(innerContent) {
+  return `${BEGIN}\n${HEADER_COMMENTS}\n\n${innerContent}\n${END}`;
+}
+
+// Returns the host content with the managed block inserted/refreshed.
 // - If the host already contains markers, replace content between them.
 // - Otherwise, prepend the block at the top, separated by a blank line.
 // - If host is null/undefined, return a file containing just the block.
-function applyBlock(hostContent) {
-  if (hostContent == null) return BLOCK_BODY + '\n';
+function applyBlock(hostContent, innerContent) {
+  const block = buildBlock(innerContent);
+  if (hostContent == null) return block + '\n';
   if (BLOCK_RE.test(hostContent)) {
-    return hostContent.replace(BLOCK_RE, BLOCK_BODY);
+    return hostContent.replace(BLOCK_RE, block);
   }
-  const sep = hostContent.length === 0 || hostContent.startsWith('\n') ? '\n' : '\n\n';
-  return BLOCK_BODY + sep + hostContent;
+  const sep =
+    hostContent.length === 0 || hostContent.startsWith('\n') ? '\n' : '\n\n';
+  return block + sep + hostContent;
 }
 
-// Returns the host content with the managed block (and surrounding blank
-// lines) removed. Safe to call when no block is present.
 function removeBlock(hostContent) {
   if (!hostContent) return '';
-  const re = new RegExp(`${escapeRegex(BEGIN)}[\\s\\S]*?${escapeRegex(END)}\\n*`, 'g');
+  const re = new RegExp(
+    `${escapeRegex(BEGIN)}[\\s\\S]*${escapeRegex(END)}\\n*`
+  );
   return hostContent.replace(re, '');
 }
 
-module.exports = { applyBlock, removeBlock, BEGIN, END, BLOCK_BODY };
+module.exports = { applyBlock, removeBlock, BEGIN, END };

package/scripts/targets.js

@@ -0,0 +1,124 @@
+// Defines every file ai-commons writes into a consumer project, and how to
+// render its content. Currently covers Claude, Codex (root AGENTS.md), and
+// Cursor (.cursor/rules/ai-commons.mdc).
+
+const fs = require('fs');
+const path = require('path');
+const { applyBlock, removeBlock } = require('./managed-block');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+function readRules() {
+  return fs.readFileSync(path.join(PACKAGE_ROOT, 'RULES.md'), 'utf8').trim();
+}
+
+// Each target:
+//   id        — internal name for logs
+//   file      — path relative to consumer root
+//   mode      — 'block' (manage section between markers) | 'fullFile' (own whole file)
+//   render(r) — render the block body / file body from the rules text
+//
+// Block mode preserves user content outside the markers.
+// fullFile mode means we own the entire file (created/removed as a unit).
+
+const TARGETS = [
+  {
+    id: 'claude',
+    file: 'CLAUDE.md',
+    mode: 'block',
+    // Claude supports @-imports natively; defer to the local AGENTS.md
+    // (which carries the embedded rules), avoiding duplication.
+    render: () => '@AGENTS.md',
+  },
+  {
+    id: 'codex+standard',
+    file: 'AGENTS.md',
+    mode: 'block',
+    // Codex CLI and the cross-tool AGENTS.md standard read this file
+    // directly — embed the full rules text.
+    render: (rules) => rules,
+  },
+  {
+    id: 'cursor',
+    file: path.join('.cursor', 'rules', 'ai-commons.mdc'),
+    mode: 'fullFile',
+    // Cursor expects MDC: YAML frontmatter + markdown body.
+    render: (rules) =>
+      `---\ndescription: ai-commons shared rules\nalwaysApply: true\n---\n\n${rules}\n`,
+  },
+];
+
+function applyTarget(consumerRoot, target, rules) {
+  const fullPath = path.join(consumerRoot, target.file);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+
+  if (target.mode === 'fullFile') {
+    const next = target.render(rules);
+    const existing = fs.existsSync(fullPath)
+      ? fs.readFileSync(fullPath, 'utf8')
+      : null;
+    if (existing === next) return null;
+    fs.writeFileSync(fullPath, next);
+    return existing == null ? 'created' : 'refreshed';
+  }
+
+  // block mode
+  const existing = fs.existsSync(fullPath)
+    ? fs.readFileSync(fullPath, 'utf8')
+    : null;
+  const next = applyBlock(existing, target.render(rules));
+  if (existing != null && next === existing) return null;
+  fs.writeFileSync(fullPath, next);
+  return existing == null ? 'created' : 'refreshed';
+}
+
+function removeTarget(consumerRoot, target) {
+  const fullPath = path.join(consumerRoot, target.file);
+  if (!fs.existsSync(fullPath)) return null;
+
+  if (target.mode === 'fullFile') {
+    fs.rmSync(fullPath);
+    return 'removed';
+  }
+
+  const existing = fs.readFileSync(fullPath, 'utf8');
+  const next = removeBlock(existing);
+  if (next.trim() === '') {
+    fs.rmSync(fullPath);
+    return 'removed-empty';
+  }
+  if (next !== existing) {
+    fs.writeFileSync(fullPath, next);
+    return 'block-removed';
+  }
+  return null;
+}
+
+function applyAllTargets(consumerRoot) {
+  const rules = readRules();
+  const results = [];
+  for (const target of TARGETS) {
+    const result = applyTarget(consumerRoot, target, rules);
+    if (result) results.push({ target, result });
+  }
+  return results;
+}
+
+function removeAllTargets(consumerRoot) {
+  const results = [];
+  for (const target of TARGETS) {
+    const result = removeTarget(consumerRoot, target);
+    if (result) results.push({ target, result });
+  }
+  return results;
+}
+
+module.exports = {
+  TARGETS,
+  PACKAGE_ROOT,
+  readRules,
+  applyTarget,
+  removeTarget,
+  applyAllTargets,
+  removeAllTargets,
+};

package/AGENTS.md

@@ -1,81 +0,0 @@
-# ai-commons — общие правила для всех проектов
-
-Этот файл подгружается в каждую Claude Code сессию проекта-потребителя через
-импорт `@node_modules/ai-commons/AGENTS.md` в корневом `CLAUDE.md`. В корневом
-`CLAUDE.md` потребителя есть управляемая секция между метками
-`<!-- ai-commons:begin -->` и `<!-- ai-commons:end -->` — её содержимое
-перезаписывается хуком `ai-commons` на каждом старте сессии. **Не редактируй
-блок между метками** — изменения будут потеряны. Всё, что в `CLAUDE.md`
-снаружи блока, остаётся нетронутым: пиши там свои проектные правила.
-
-Чтобы поменять общие правила, правь этот файл в репозитории `ai-commons`.
-
-Правила сгруппированы по трём уровням приоритета. Игнорировать MUST нельзя
-ни при каких обстоятельствах. Желательно — стандартное поведение по
-умолчанию, отступление возможно только с явной причиной. Остальное —
-стиль и привычки.
-
----
-
-## MUST — обязательно, игнорировать нельзя
-
-- **Никогда не делай `git push --force` в `main`/`master`.** Если нужно
-  переписать историю, спроси разрешения и работай через feature-ветку.
-- **Никогда не коммить секреты** (`.env`, ключи, токены, credentials.json
-  и т.п.). Если такой файл попал в `git add`, удали его из стейджа и
-  предупреди пользователя.
-- **Не запускай деструктивные операции без подтверждения**: `rm -rf`,
-  `git reset --hard`, `DROP TABLE`, `git clean -fd`, отключение pre-commit
-  хуков (`--no-verify`), force push куда угодно.
-- **Не правь блок между метками `ai-commons:begin / end`** в корневом
-  `CLAUDE.md` потребителя — он управляется `ai-commons` и перезаписывается
-  на старте сессии. Свои правила пиши снаружи этого блока.
-- **Для групп связанных проектов используй `git-coherent`**
-  (`npm i -g git-coherent`, бинари `git-coherent` / `gitc`) — синхронизация
-  git-операций по сиблинг-репозиториям, которые опт-инятся через
-  `.git-coherent` маркер. Это «среднее между monorepo и микросервисами»:
-  каждый подпроект остаётся отдельным git-репо, `git-coherent` запускает
-  операции над всеми отмеченными сразу. Не предлагай и не создавай
-  монорепо или независимые multi-repo схемы для таких задач без явного
-  запроса.
-- **Не отключай и не модифицируй хуки `ai-commons`** в `.claude/settings.json`
-  без явного запроса пользователя.
-
-## Желательно — стандарт по умолчанию, отступать только с причиной
-
-- Отвечай кратко: один-два абзаца, без избыточных вводных и итогов.
-- Перед нетривиальной задачей дай короткий план (3–5 пунктов), потом
-  делай. Не пиши длинные эссе про подход.
-- Не добавляй фич, рефакторингов и абстракций сверх задачи. Bug fix не
-  тянет за собой cleanup.
-- Не пиши комментарии, описывающие *что* делает код. Пиши только если
-  нужно объяснить *почему* — и только если это неочевидно.
-- Не валидируй то, что не может случиться. Доверяй внутренним
-  гарантиям типов и фреймворков; валидируй только на границах системы
-  (вход пользователя, внешние API).
-- Перед удалением «непонятного» файла/ветки/конфигурации — выясни, не
-  работа ли это пользователя в процессе. Спроси, если есть сомнения.
-
-## Остальное — стиль и привычки
-
-- `curl`-примеры — одной строкой, без переносов `\`.
-- При ссылках на код используй формат `path/to/file.ts:42`.
-- Для UI-задач — запусти dev-сервер и проверь в браузере перед тем, как
-  говорить «готово». Тесты и типы проверяют корректность кода, не
-  фичи.
-- Если задача неясная или формулировка двусмысленная — задай один-два
-  уточняющих вопроса вместо угадывания.
-
----
-
-## Как это устроено технически
-
-- `ai-commons` ставится как обычная npm-зависимость:
-  `npm i -D ai-commons` (или `file:~/okneigres-repos/ai-commons` для локальной разработки).
-- `postinstall` вставляет/обновляет блок между метками `ai-commons:begin/end`
-  в корневом `CLAUDE.md` потребителя. Если файла нет — создаёт его.
-- `SessionStart`-хук `ai-commons` обновляет этот блок на каждом старте
-  сессии — это гарантирует, что правила всегда актуальны. Остальное
-  содержимое `CLAUDE.md` не трогается.
-- `Stop`-хук сохраняет каждый диалог в
-  `.ai-dialogs/YYMMDD-HHII-<topic>.md` (см. README модуля).