ai-commons 0.2.7

package/AGENTS.md

@@ -0,0 +1,73 @@
+# 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` и перезаписывается
+  на старте сессии. Свои правила пиши снаружи этого блока.
+- **Не отключай и не модифицируй хуки `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 модуля).

package/README.md

@@ -0,0 +1,113 @@
+# 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`.
+
+## Установка в новый проект
+
+```bash
+cd my-new-project
+npm i -D /Users/os/okneigres-repos/ai-commons
+```
+
+Или, если опубликовано в реестре:
+
+```bash
+npm i -D ai-commons
+```
+
+`postinstall` всё настраивает автоматически. Запустить вручную:
+
+```bash
+npx ai-commons install
+```
+
+## Откат
+
+```bash
+npx ai-commons uninstall
+# затем удалить зависимость:
+npm uninstall ai-commons
+```
+
+`uninstall` уберёт блок `ai-commons` из `CLAUDE.md` (сам файл остаётся, если в
+нём есть другое содержимое — удаляется только если оказался пустым) и
+вычистит хуки `ai-commons` из `.claude/settings.json`, не трогая чужие хуки.
+
+## Уровни правил
+
+`AGENTS.md` в этом репо разбит на три секции:
+
+- **MUST** — обязательно, игнорировать нельзя ни при каких обстоятельствах
+  (например: не пушить force в main, не коммитить секреты).
+- **Желательно** — стандарт по умолчанию, отступать можно только с явной
+  причиной (например: краткие ответы, без избыточных абстракций).
+- **Остальное** — стиль и привычки (например: `curl` одной строкой,
+  ссылки на код в формате `path:line`).
+
+## Как обновить правила во всех проектах
+
+1. Правишь `AGENTS.md` здесь.
+2. `git commit && git push` (или просто коммит, если репо локальный).
+3. В каждом потребителе: `npm update ai-commons` (или `npm install`, если
+   зависимость через `file:`).
+
+Содержимое подгружается Claude Code через `@`-импорт каждый сеанс, поэтому
+после обновления `node_modules/ai-commons/AGENTS.md` следующая сессия
+увидит новые правила автоматически.
+
+## Сохранение диалогов
+
+После каждого Claude Stop (и при завершении сессии) хук пишет
+`.ai-dialogs/YYMMDD-HHII-<topic>.md`:
+
+- Timestamp — момент первой реплики пользователя в сессии.
+- `<topic>` — `ai-title` из транскрипта Claude Code, fallback на первую
+  пользовательскую реплику.
+- Файл переписывается на каждом Stop в пределах одной сессии (то есть
+  всегда содержит полный диалог).
+- Thinking-блоки модели не сохраняются — только пользовательский текст,
+  ответы ассистента, tool calls и их результаты.
+
+`.ai-dialogs/` гитигнорится автоматически.
+
+## Структура репо
+
+```
+ai-commons/
+├── AGENTS.md                          — правила, импортируются потребителями
+├── 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
+└── hooks/
+    ├── ensure-rules-pointer.js        — SessionStart-хук
+    └── save-dialog.js                 — Stop / SessionEnd-хук
+```
+
+## Переменные окружения
+
+- `AI_COMMONS_SKIP_POSTINSTALL=1` — отключить автоустановку (CI и т.п.).
+
+## Что не делается
+
+- `ai-commons` **не** распространяет общие сабагенты/скиллы/слэш-команды.
+  Этот скоуп умышленно убран — если понадобится, добавим отдельной командой
+  `ai-commons sync-agents`.
+- `permissions` и `env` из `settings.json` потребителя не трогаются.

package/bin/ai-commons.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+const { install, uninstall } = require('../scripts/installer');
+
+const USAGE = `Usage: ai-commons <command>
+
+Commands:
+  install     Write CLAUDE.md pointer, register hooks, update .gitignore
+              (idempotent — same as the postinstall script)
+  uninstall   Remove pointer file (if unchanged) and ai-commons hooks
+  help        Show this help
+
+Run from the consumer project root (where package.json lives).
+`;
+
+function main() {
+  const cmd = process.argv[2];
+  const cwd = process.cwd();
+
+  switch (cmd) {
+    case 'install':
+      install(cwd);
+      break;
+    case 'uninstall':
+      uninstall(cwd);
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      process.stdout.write(USAGE);
+      break;
+    default:
+      process.stderr.write(`Unknown command: ${cmd}\n\n${USAGE}`);
+      process.exit(1);
+  }
+}
+
+main();

package/hooks/ensure-rules-pointer.js

@@ -0,0 +1,45 @@
+#!/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.
+
+const fs = require('fs');
+const path = require('path');
+const { applyBlock } = require('../scripts/managed-block');
+
+const POINTER_FILE = 'CLAUDE.md';
+
+function readStdinJson() {
+  try {
+    const raw = fs.readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+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.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);
+  }
+
+  fs.writeFileSync(pointerPath, next);
+  process.stderr.write(`[ai-commons] refreshed block in ${POINTER_FILE}\n`);
+  process.exit(0);
+}
+
+main();

package/hooks/save-dialog.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// Stop / SessionEnd hook: dumps the current Claude Code transcript to
+// <cwd>/.ai-dialogs/YYMMDD-HHII-<topic>.md. Filename is deterministic per
+// session, so repeated Stop calls overwrite the same file.
+
+const fs = require('fs');
+const path = require('path');
+
+const MAX_SLUG_LEN = 60;
+const DIALOGS_DIR = '.ai-dialogs';
+
+function readStdinJson() {
+  try {
+    const raw = fs.readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function parseJsonl(filePath) {
+  const out = [];
+  const content = fs.readFileSync(filePath, 'utf8');
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      out.push(JSON.parse(trimmed));
+    } catch {
+      // ignore malformed line
+    }
+  }
+  return out;
+}
+
+function pad2(n) {
+  return String(n).padStart(2, '0');
+}
+
+function formatStamp(date) {
+  return (
+    pad2(date.getFullYear() % 100) +
+    pad2(date.getMonth() + 1) +
+    pad2(date.getDate()) +
+    '-' +
+    pad2(date.getHours()) +
+    pad2(date.getMinutes())
+  );
+}
+
+function slugify(text) {
+  if (!text) return 'untitled';
+  // Lowercase, replace forbidden filename chars and whitespace, collapse dashes.
+  // Preserve Unicode letters/digits (so Cyrillic stays readable).
+  let s = text.toLowerCase();
+  s = s.replace(/[\/\\:*?"<>|]/g, ' ');
+  s = s.replace(/[\s_]+/g, '-');
+  s = s.replace(/-+/g, '-');
+  s = s.replace(/^-+|-+$/g, '');
+  s = s.slice(0, MAX_SLUG_LEN);
+  s = s.replace(/-+$/g, '');
+  return s || 'untitled';
+}
+
+function extractText(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  const parts = [];
+  for (const block of content) {
+    if (!block || typeof block !== 'object') continue;
+    switch (block.type) {
+      case 'text':
+        if (block.text) parts.push(block.text);
+        break;
+      case 'tool_use':
+        parts.push(
+          `*[tool_use: ${block.name}]*\n\`\`\`json\n${JSON.stringify(
+            block.input,
+            null,
+            2
+          )}\n\`\`\``
+        );
+        break;
+      case 'tool_result': {
+        const inner =
+          typeof block.content === 'string'
+            ? block.content
+            : Array.isArray(block.content)
+            ? block.content
+                .map((b) => (b && b.type === 'text' ? b.text : ''))
+                .filter(Boolean)
+                .join('\n')
+            : '';
+        parts.push(`*[tool_result]*\n\`\`\`\n${truncate(inner, 4000)}\n\`\`\``);
+        break;
+      }
+      case 'thinking':
+        // Skip thinking blocks — keep dialogs concise.
+        break;
+      default:
+        // ignore unknown block types
+        break;
+    }
+  }
+  return parts.join('\n\n');
+}
+
+function truncate(s, limit) {
+  if (s.length <= limit) return s;
+  return s.slice(0, limit) + `\n... [truncated ${s.length - limit} chars]`;
+}
+
+function pickTopic(messages) {
+  // Prefer Claude Code's own generated title if present.
+  for (const m of messages) {
+    if (m.type === 'ai-title' && m.aiTitle) return m.aiTitle;
+  }
+  // Fallback: first user message text.
+  for (const m of messages) {
+    if (m.type === 'user' && m.message) {
+      const text = extractText(m.message.content);
+      if (text) return text.split('\n')[0].slice(0, 80);
+    }
+  }
+  return 'untitled';
+}
+
+function pickStartTime(messages) {
+  for (const m of messages) {
+    if ((m.type === 'user' || m.type === 'assistant') && m.timestamp) {
+      return new Date(m.timestamp);
+    }
+  }
+  // Fallback: file mtime or now
+  return new Date();
+}
+
+function render(messages, topic) {
+  const out = [];
+  out.push(`# ${topic}`);
+  out.push('');
+
+  for (const m of messages) {
+    if (m.type !== 'user' && m.type !== 'assistant') continue;
+    if (!m.message) continue;
+
+    const role = m.message.role || m.type;
+    const text = extractText(m.message.content);
+    if (!text.trim()) continue;
+
+    const ts = m.timestamp ? `  \n*${m.timestamp}*` : '';
+    out.push(`## ${role}${ts}`);
+    out.push('');
+    out.push(text);
+    out.push('');
+  }
+  return out.join('\n');
+}
+
+function main() {
+  const input = readStdinJson();
+  const transcriptPath = input.transcript_path || input.transcriptPath;
+  const cwd = input.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+    process.stderr.write('[ai-commons] no transcript path, skipping dialog save\n');
+    process.exit(0);
+  }
+  if (!cwd || !fs.existsSync(cwd)) {
+    process.stderr.write('[ai-commons] no cwd, skipping dialog save\n');
+    process.exit(0);
+  }
+
+  const messages = parseJsonl(transcriptPath);
+  if (messages.length === 0) {
+    process.exit(0);
+  }
+
+  const topic = pickTopic(messages);
+  const slug = slugify(topic);
+  const start = pickStartTime(messages);
+  const stamp = formatStamp(start);
+
+  const dialogsDir = path.join(cwd, DIALOGS_DIR);
+  fs.mkdirSync(dialogsDir, { recursive: true });
+
+  const filename = `${stamp}-${slug}.md`;
+  const outPath = path.join(dialogsDir, filename);
+
+  fs.writeFileSync(outPath, render(messages, topic));
+  process.stderr.write(`[ai-commons] saved dialog ${DIALOGS_DIR}/${filename}\n`);
+  process.exit(0);
+}
+
+try {
+  main();
+} catch (err) {
+  process.stderr.write(`[ai-commons] save-dialog error: ${err.message}\n`);
+  // Don't fail the hook chain — exit 0.
+  process.exit(0);
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "ai-commons",
+  "version": "0.2.7",
+  "description": "Shared Claude Code rules + dialog-saver hook for projects",
+  "bin": {
+    "ai-commons": "bin/ai-commons.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "prepublishOnly": "npm version patch --force"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "hooks",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  }
+}

package/scripts/installer.js

@@ -0,0 +1,145 @@
+// Installs ai-commons into a consumer project:
+//   - writes/refreshes the root CLAUDE.md pointer
+//   - merges our hooks into .claude/settings.json (preserving any existing hooks)
+//   - ensures .ai-dialogs/ is gitignored
+//
+// Designed to be idempotent: running install repeatedly is safe and cleans up
+// duplicate ai-commons entries.
+
+const fs = require('fs');
+const path = require('path');
+const { applyBlock, removeBlock } = require('./managed-block');
+
+const PACKAGE_NAME = require('../package.json').name;
+const POINTER_FILE = 'CLAUDE.md';
+const SETTINGS_FILE = path.join('.claude', 'settings.json');
+const GITIGNORE_FILE = '.gitignore';
+
+const HOOK_MARKER = `node_modules/${PACKAGE_NAME}/hooks/`;
+
+const MANAGED_HOOKS = {
+  SessionStart: `node "$CLAUDE_PROJECT_DIR/node_modules/${PACKAGE_NAME}/hooks/ensure-rules-pointer.js"`,
+  Stop: `node "$CLAUDE_PROJECT_DIR/node_modules/${PACKAGE_NAME}/hooks/save-dialog.js"`,
+  SessionEnd: `node "$CLAUDE_PROJECT_DIR/node_modules/${PACKAGE_NAME}/hooks/save-dialog.js"`,
+};
+
+const GITIGNORE_BLOCK = `\n# ai-commons\n.ai-dialogs/\n`;
+
+function log(msg) {
+  process.stderr.write(`[ai-commons] ${msg}\n`);
+}
+
+function readJsonOrEmpty(p) {
+  if (!fs.existsSync(p)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (err) {
+    log(`warning: ${p} is not valid JSON (${err.message}) — leaving as-is`);
+    return null;
+  }
+}
+
+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 stripManagedHooksFromEvent(eventEntries) {
+  if (!Array.isArray(eventEntries)) return [];
+  return eventEntries
+    .map((group) => {
+      if (!group || !Array.isArray(group.hooks)) return group;
+      const filteredHooks = group.hooks.filter(
+        (h) => !(h && typeof h.command === 'string' && h.command.includes(HOOK_MARKER))
+      );
+      return { ...group, hooks: filteredHooks };
+    })
+    .filter((group) => group && Array.isArray(group.hooks) && group.hooks.length > 0);
+}
+
+function mergeHooks(consumerRoot) {
+  const settingsPath = path.join(consumerRoot, SETTINGS_FILE);
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+
+  const settings = readJsonOrEmpty(settingsPath);
+  if (settings === null) return;
+  if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
+
+  for (const [event, command] of Object.entries(MANAGED_HOOKS)) {
+    const stripped = stripManagedHooksFromEvent(settings.hooks[event]);
+    stripped.push({
+      hooks: [{ type: 'command', command }],
+    });
+    settings.hooks[event] = stripped;
+  }
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  log(`merged hooks into ${SETTINGS_FILE}`);
+}
+
+function ensureGitignore(consumerRoot) {
+  const giPath = path.join(consumerRoot, GITIGNORE_FILE);
+  const existing = fs.existsSync(giPath) ? fs.readFileSync(giPath, 'utf8') : '';
+  if (existing.split('\n').some((l) => l.trim() === '.ai-dialogs/')) return;
+  const next = existing + (existing.endsWith('\n') || existing === '' ? '' : '\n') + GITIGNORE_BLOCK;
+  fs.writeFileSync(giPath, next);
+  log(`added .ai-dialogs/ to ${GITIGNORE_FILE}`);
+}
+
+function install(consumerRoot) {
+  if (!consumerRoot || !fs.existsSync(consumerRoot)) {
+    throw new Error(`Invalid consumer root: ${consumerRoot}`);
+  }
+  writePointer(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 hooks from settings.
+  const settingsPath = path.join(consumerRoot, SETTINGS_FILE);
+  if (fs.existsSync(settingsPath)) {
+    const settings = readJsonOrEmpty(settingsPath);
+    if (settings && settings.hooks) {
+      for (const event of Object.keys(MANAGED_HOOKS)) {
+        if (settings.hooks[event]) {
+          const stripped = stripManagedHooksFromEvent(settings.hooks[event]);
+          if (stripped.length === 0) delete settings.hooks[event];
+          else settings.hooks[event] = stripped;
+        }
+      }
+      if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+      fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+      log(`removed hooks from ${SETTINGS_FILE}`);
+    }
+  }
+}
+
+module.exports = { install, uninstall, PACKAGE_NAME };

package/scripts/managed-block.js

@@ -0,0 +1,44 @@
+// Shared helpers for inserting/updating the ai-commons block inside a
+// host markdown file (typically the consumer's CLAUDE.md).
+
+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,
+].join('\n');
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+const BLOCK_RE = new RegExp(`${escapeRegex(BEGIN)}[\\s\\S]*?${escapeRegex(END)}`);
+
+// Returns the host content with our 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';
+  if (BLOCK_RE.test(hostContent)) {
+    return hostContent.replace(BLOCK_RE, BLOCK_BODY);
+  }
+  const sep = hostContent.length === 0 || hostContent.startsWith('\n') ? '\n' : '\n\n';
+  return BLOCK_BODY + 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');
+  return hostContent.replace(re, '');
+}
+
+module.exports = { applyBlock, removeBlock, BEGIN, END, BLOCK_BODY };

package/scripts/postinstall.js

@@ -0,0 +1,28 @@
+const path = require('path');
+const { install } = require('./installer');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const consumerRoot = process.env.INIT_CWD;
+
+if (!consumerRoot) {
+  console.log('[ai-commons] INIT_CWD not set, skipping install');
+  process.exit(0);
+}
+
+if (path.resolve(consumerRoot) === path.resolve(PACKAGE_ROOT)) {
+  console.log('[ai-commons] installing own deps, skipping install');
+  process.exit(0);
+}
+
+if (process.env.AI_COMMONS_SKIP_POSTINSTALL === '1') {
+  console.log('[ai-commons] AI_COMMONS_SKIP_POSTINSTALL=1, skipping install');
+  process.exit(0);
+}
+
+try {
+  install(consumerRoot);
+} catch (err) {
+  console.error('[ai-commons] install failed:', err.message);
+  // Don't fail the npm install — Claude config is non-critical.
+  process.exit(0);
+}