claudenv 1.2.5 → 1.3.1

package/scaffold/global/.claude/commands/why.md

@@ -0,0 +1,33 @@
+---
+description: Объяснить технологию или подход в контексте текущей задачи — без принятия решения и без записи в decisions/
+allowed-tools: Read, Glob, Grep, WebSearch, WebFetch, Bash(claudenv:*)
+argument-hint: <technology-or-question>
+---
+
+# /why — Краткое объяснение
+
+Объяснить `$ARGUMENTS` в контексте текущей задачи. Не вызывает vibe-decisions, не пишет в `~/.claudenv/memories/decisions/`.
+
+## Step 1 — Check canon first
+
+Run `claudenv canon search "$ARGUMENTS"` (Bash). If matches found — упомяни их как primary references.
+
+## Step 2 — Brief explanation (3-5 lines)
+
+Структура:
+
+- **Что это:** 1 строка
+- **Когда используется:** 1-2 строки
+- **Когда не подходит:** 1 строка
+- **Ссылки (опционально):** канон или WebSearch если канон пуст
+
+## Не делать
+
+- Не выводи vibe-decisions overview format (это explainer, не decision)
+- Не пиши файл в decisions/
+- Если пользователь после `/why` начинает реальный выбор технологии — тогда уже триггерится vibe-decisions skill
+
+## Style
+
+- User's language
+- Краткость > полнота. Для полноты есть `/deeper` после реального decision.

package/scaffold/global/.claude/skills/source-connector/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: source-connector
+description: |
+  Trigger when the user wants to connect to a data source that has no ready
+  MCP server - internal SQL/DWH behind VPN, corporate wiki (Confluence),
+  Redash, YouTrack, a custom REST API - or says "добавь источник",
+  "подключись к <система>", "/add-source". The skill interviews the user,
+  generates a working connector script, stores credentials in .env.local
+  (gitignored, never in memory), and caches connector knowledge (params +
+  provenance) in the ACTIVE workspace memory, isolated from other workspaces.
+  Do NOT trigger for sources that already have an MCP server (prefer MCP),
+  or for trivial local file reads.
+---
+
+# Source connector
+
+Создаёт коннектор к источнику данных без готового MCP: внутренний SQL/DWH,
+корпоративная вики, Redash, YouTrack, самописный REST. Опрашивает юзера,
+генерирует рабочий скрипт, кладёт секреты в `.env.local`, кэширует знание о
+коннекторе (параметры + provenance) в память АКТИВНОГО workspace.
+
+## Step 0 - Workspace resolution (FIRST, every time)
+
+Память изолирована по пространствам (workspaces). Прежде чем что-либо писать:
+
+1. Определи активный workspace:
+   - env `CLAUDENV_WORKSPACE`, иначе файл `~/.claudenv/active-workspace`.
+   - если есть `claudenv` CLI: `claudenv workspace show`.
+2. Если активного нет - предложи выбрать из `~/.claudenv/workspaces/` или создать
+   новый. НИКОГДА не подтягивай и не пиши в «глобальную» память доступы/коннекторы.
+3. Все записи коннектора пиши ТОЛЬКО в активный workspace:
+   `~/.claudenv/workspaces/<id>/memories/connectors/`.
+4. НИКОГДА не читай чужие workspaces - это барьер от ликов между компаниями.
+
+## Security invariants (нарушать нельзя)
+
+- **Секреты (пароли, токены, ключи) - только в `<project>/.env.local`** и только
+  значениями там. Убедись, что `.env.local` есть в `.gitignore` (добавь, если нет).
+- **В память коннектора - НИКОГДА значения секретов.** Только `secret_refs` -
+  имена переменных из `.env.local`.
+- **Не эхай секреты** в вывод/логи/коммиты.
+- Память активного workspace изолирована: не смешивай контекст разных компаний.
+
+## Trigger criteria
+
+Триггерь, если юзеру нужно регулярно/программно ходить в источник:
+- БД (MSSQL/Postgres/ClickHouse), DWH за VPN
+- корпоративная вики (Confluence), Redash, YouTrack, Grafana
+- самописный REST/GraphQL API
+
+НЕ триггерь:
+- если для источника есть MCP-сервер - предложи MCP (см. ниже)
+- разовое чтение локального файла
+- источник уже подключён (тогда это обновление, см. Step 6)
+
+## Step 1 - MCP vs connector
+
+Сначала проверь, нет ли готового MCP для источника (claudenv умеет настраивать MCP
+в `.mcp.json`). Если есть - предложи MCP-путь. Коннектор - для источников БЕЗ MCP.
+
+## Step 2 - Interview (спроси у юзера, кратко)
+
+Собери минимум для подключения:
+- тип источника (mssql / postgres / clickhouse / rest / confluence / redash / youtrack)
+- хост и порт, база/endpoint
+- метод аутентификации (sql login / domain / token / trusted)
+- что нужно достать (таблицы/эндпоинты) - для первого запроса
+- как зовутся переменные кред в `.env.local` (или предложи имена)
+
+Не выдумывай параметры - спрашивай. Если юзер уже дал часть (вики/git/переписка) -
+зафиксируй это в provenance.
+
+## Step 3 - Generate connector script
+
+Сгенерируй рабочий скрипт из шаблона (`templates/connector-*.ejs`):
+- MSSQL -> pymssql/pyodbc, строка `mssql+pymssql://{user}:{pwd}@{host}:{port}/{db}`
+  (СУЗ - логин без домена; экранируй пароль через urllib `quote_plus`).
+- REST -> requests + Bearer-токен из env.
+Скрипт читает креды из `.env.local` (через env), не хардкодит.
+
+## Step 4 - Secrets to .env.local
+
+- Запиши значения в `<project>/.env.local` (создай при отсутствии).
+- Проверь/добавь `.env.local` в `.gitignore`.
+- В память пойдут только имена этих переменных (`secret_refs`).
+
+## Step 5 - Write connector record (в активный workspace)
+
+Создай `~/.claudenv/workspaces/<id>/memories/connectors/<name>.md`:
+
+```markdown
+---
+name: <name>
+type: <mssql|rest|...>
+status: <draft|working|blocked>
+host: <host>
+database: <db|->
+port: <port|->
+auth: <sql|domain|token|trusted>
+secret_refs: {user: <ENV_VAR>, password: <ENV_VAR>}   # ИМЕНА, не значения
+connector_script: <path в проекте>
+provenance:                                            # откуда собрана инфа
+  - {source: <wiki|git|chat|docs>, ref: <url|путь>, note: <кратко>}
+verified_at: <YYYY-MM-DD|->
+updated_at: <YYYY-MM-DD>
+---
+
+Детали: как устроено подключение, что блокирует, как обновлять.
+```
+
+**Provenance обязателен** - фиксируй, откуда взял каждый факт (вики-страница, файл
+в git, сообщение в чате). Это позволяет потом перепроверить и обновить.
+
+## Step 6 - Test and iterate
+
+Протестируй подключение, если возможно. Зафиксируй `status` и `verified_at`.
+При ошибке - запиши симптом в запись (раздел деталей) и предложи следующий шаг.
+
+## Step 7 - Updating an existing connector
+
+Если коннектор уже есть в активном workspace:
+- найди запись, обнови `status`/`host`/`secret_refs`, допиши `provenance`,
+  обнови `updated_at`. Запись - единый источник правды по коннектору.
+
+## После создания
+
+Предложи дальнейшую автоматизацию через коннектор (регулярная выгрузка, отчёт,
+интеграция в пайплайн). Язык общения - русский.

package/scaffold/global/.claude/skills/vibe-decisions/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: vibe-decisions
+description: |
+  Trigger before writing code that involves a non-trivial technical
+  choice (library, algorithm, data structure, architecture pattern,
+  sync vs async, correctness vs performance). Output a brief overview
+  with concrete trade-offs and 1-2 alternatives, then log the decision.
+  Two modes: auto-log (no pauses) inside `claudenv loop`, pause-and-ask
+  in interactive Claude Code. Also triggers on: "почему X?", "X vs Y?",
+  "/why", "/deeper", "/decisions", "alternatives?", "trade-offs?".
+  Do NOT trigger for trivial syntax, naming, or formatting choices.
+---
+
+# Vibe decisions
+
+## Mode detection (FIRST step every time)
+
+Check the system prompt for the marker `Vibe-decisions mode (loop)`.
+
+- **Marker present** → AUTO-LOG mode. Pick the approach, write the decision file, continue. NEVER pause. NEVER ask "делать так?". This is `claudenv loop` and pause violates autonomy=law.
+- **Marker absent** → INTERACTIVE mode. Output brief overview, wait for user confirmation or `/deeper`.
+
+Both modes share the same trigger criteria, file format, and slash-command behavior. Only output shape and pause behavior differ.
+
+## Trigger criteria
+
+Trigger if the decision involves:
+
+- choosing a library or framework from 2+ viable options
+- choosing an algorithm or data structure with meaningful trade-offs
+- architecture pattern (sync/async, push/pull, where state lives, monolith/services)
+- correctness vs performance vs simplicity trade-off
+- anything where reasonable engineers would disagree
+
+DO NOT trigger for:
+
+- syntax-level choices in a single language (for vs map, ternary vs if)
+- obvious choices (JSON for a config file, regex for simple pattern)
+- pure refactoring within established patterns
+- when the user typed `/just-code` in the previous turn
+
+## Step 1 — Check memory before deciding
+
+Before writing brief or auto-log, read related precedents:
+
+- `view` `/memories/decisions/` — list files; if any topic looks related, read it
+- Mention the precedent briefly: "Раньше для X выбирали Y (см. <file>)"
+
+## Step 2A — AUTO-LOG mode output (inside `claudenv loop`)
+
+Output exactly this shape in the user's language, then continue with code in the same turn:
+
+```
+**Выбрано:** <approach>
+**Почему:** <one sentence>
+**Альтернативы:** <A> — <terse trade-off>; <B> — <terse trade-off>
+**Лог:** /memories/decisions/<YYYY-MM-DD>-<topic-slug>.md (scope: <global|project>)
+```
+
+Immediately after the block, use the Write tool to create the decision file (see Step 4 for format). Then proceed with the actual code. Do NOT pause.
+
+## Step 2B — INTERACTIVE mode output (no loop)
+
+Output this shape and STOP. Wait for the user.
+
+```
+**Подход:** <approach>
+**Почему для этой задачи:** <1-2 lines, concrete to the task>
+**Минусы:** <1-2 lines, concrete to the task>
+**Альтернативы:** <A> — <one sentence>; <B> — <one sentence>
+```
+
+Then ask: "Делать так, или разобрать варианты подробнее?"
+
+DO NOT proceed with code until the user confirms OR asks for deep dive.
+
+## Step 3 — Deep dive (on `/deeper` or "расскажи подробнее")
+
+Expand the most recent decision into:
+
+1. **Концептуально** — what it is and the problem it solves (3-5 lines)
+2. **Как работает** — simplified model (5-10 lines, optionally a code sketch)
+3. **2-3 варианта реализации** — for each: code + 1-2 lines of trade-offs
+4. **Канон** — 2-4 references. First check `~/.claudenv/memories/canon/index.yaml` for a topic match. If a match exists — cite those. If not — WebSearch for authoritative sources and after the response suggest `claudenv canon add <topic> <url> --why "..."`.
+
+After deep dive, in auto-log mode update the existing decision file's `deep_dive_done: yes` field. In interactive mode wait for confirmation.
+
+## Step 4 — Write the decision file
+
+Path:
+
+- `scope: global` (default) → `~/.claudenv/memories/decisions/<YYYY-MM-DD>-<topic-slug>.md`
+- `scope: project` → `<cwd>/.claude/memories/decisions/<YYYY-MM-DD>-<topic-slug>.md`
+
+**Choose scope BEFORE writing — don't rely on hook to rewrite.** Project scope if the choice mentions project-only artifacts (module name, env var, deployment target, internal service). Otherwise global.
+
+File content:
+
+```
+---
+date: <ISO 8601 datetime with timezone>
+project: <basename of cwd, or "(none)" if no project context>
+topic: <plain-language summary of what was decided>
+chose: <approach>
+alternatives_considered: [<A>, <B>]
+reason: <one sentence why>
+deep_dive_done: <yes|no>
+sources_consulted: [<canon-id-or-url>, ...]
+scope: <global|project>
+---
+
+<optional body — caveats, follow-ups, links>
+
+__VIBE_DECISION__
+```
+
+The `__VIBE_DECISION__` marker on the last line lets the `decisions-logger` hook detect the file even if the path check fails. Always include it.
+
+## Slash-commands the skill responds to
+
+- `/why <X>` — explain X briefly without committing a decision; do NOT write a decision file
+- `/deeper` — deep dive on the most recent decision (Step 3)
+- `/decisions [N]` — execute Bash `claudenv decisions list --limit ${N:-10}` and show output
+- `/canon [<topic>]` — execute Bash `claudenv canon list <topic>` and show output
+- `/just-code` — suppress vibe-decisions on the NEXT response only; resume on the one after
+
+Trigger phrases that also count (in any language): "расскажи подробнее", "почему именно X?", "X vs Y?", "alternatives?", "trade-offs?".

package/scaffold/global/.claude/skills/vibe-decisions/deep-dive-template.md

@@ -0,0 +1,41 @@
+# Deep dive template
+
+Used by the `vibe-decisions` skill when the user requests `/deeper` or asks "расскажи подробнее", "X vs Y?", "trade-offs?".
+
+Fill each section concretely against the current task — generic prose is the failure mode here.
+
+## 1. Концептуально (3-5 строк)
+
+What this approach is and what problem it solves. Mention the canonical name and 1-2 alternatives by name (so the reader can search later). Avoid marketing language.
+
+## 2. Как работает (5-10 строк, опц. code sketch)
+
+A simplified mental model. If a 10-15 line code sketch clarifies the mechanism, include it. Otherwise prose. Mention 1-2 invariants that matter — what the approach guarantees and what it explicitly does not.
+
+## 3. Варианты реализации (2-3)
+
+For each variant:
+
+### Variant N — <name>
+
+```<lang>
+# minimal sketch, 5-15 lines
+```
+
+**Когда подходит:** <one line>
+**Когда не подходит:** <one line>
+
+## 4. Канон (2-4 ссылки)
+
+Priority: matches from `~/.claudenv/memories/canon/index.yaml` by topic. If no match, WebSearch and propose `claudenv canon add` after the response.
+
+Format each entry:
+
+- **<title>** — <author or venue> — <1 line why>
+  <url>
+
+## After deep dive
+
+In AUTO-LOG mode: update the existing decision file to set `deep_dive_done: yes` and append source URLs to `sources_consulted`.
+
+In INTERACTIVE mode: ask the user "Принимаем этот подход?" before writing/updating the decision file.

package/scaffold/global-claudenv/config.yaml

@@ -0,0 +1,16 @@
+# claudenv global config.
+# Created by `claudenv install` if missing; preserved on subsequent installs.
+
+# Default model for `claudenv loop` if --model is not passed.
+# Options: opus, sonnet, haiku
+default_model: sonnet
+
+# Auto-commit ~/.claudenv/ after each session (planned for 1.4 — currently unused).
+auto_commit: false
+
+# Memory scope default when vibe-decisions can't infer.
+# Options: global, project
+default_scope: global
+
+# INDEX.md regeneration: maximum number of recent decisions to surface.
+index_recent_limit: 5

package/scaffold/global-claudenv/memories/INDEX.md

@@ -0,0 +1,25 @@
+# claudenv memory — INDEX
+
+> Auto-generated by `claudenv hook regen-index` after each session and after each `claudenv loop` iteration. Hand-edits will be overwritten.
+> Last regenerated: <never>
+
+## Recent decisions
+
+_No decisions logged yet. Make a non-trivial technical choice in a session — the `vibe-decisions` skill will log it here._
+
+## Active preferences
+
+_No `user/preferences.md` yet. Create one at `~/.claudenv/memories/user/preferences.md` (template at `preferences.md.example`)._
+
+## Active projects
+
+_Per-project facts live in each project's `.claude/memories/project.md`. This index lists projects seen recently._
+
+---
+
+Files in this directory:
+
+- `INDEX.md` — this file
+- `decisions/` — global cross-project tech decisions
+- `canon/` — personal canon of references
+- `user/` — cross-project preferences

package/scaffold/global-claudenv/memories/canon/index.yaml

@@ -0,0 +1,21 @@
+# Личный канон. Только то что вы прочитали и сочли важным.
+# Добавляйте через: claudenv canon add <topic> <url> --why "<reason>"
+# Используется vibe-decisions skill в /deeper для подбора ссылок.
+
+# Стартовое наполнение пустое — канон растёт от реальных decision-моментов.
+# Пример (раскомментируйте и адаптируйте):
+
+# distributed_locks:
+#   - title: "How to do distributed locking"
+#     author: Martin Kleppmann
+#     url: https://martin.kleppmann.com/2016/02/08/how-to-do-distributed-locking.html
+#     why: "обязательное чтение перед выбором Redis для locks"
+#     added: 2026-05-27
+
+# raft_consensus:
+#   - title: "In Search of an Understandable Consensus Algorithm"
+#     authors: [Ongaro, Ousterhout]
+#     venue: "USENIX ATC 2014"
+#     url: https://raft.github.io/raft.pdf
+#     why: "оригинальный paper"
+#     added: 2026-05-27

package/scaffold/global-claudenv/memories/user/preferences.md.example

@@ -0,0 +1,16 @@
+# User preferences
+
+Copy this file to `preferences.md` (in the same directory) and edit. The `vibe-decisions` skill reads it and uses it as context when suggesting approaches.
+
+Format: free-form markdown, but short lines (one preference per line) work best for cache stability.
+
+## Examples
+
+- Default branch naming: `<initials>/<short-desc>`
+- Commit style: conventional commits, lowercase subject
+- Editor: helix
+- Package manager: pnpm (Node), uv (Python), cargo (Rust)
+- TypeScript: strict + noUncheckedIndexedAccess
+- Python: type hints required, no `Any` без TODO
+- Prefer integration tests с реальной БД over heavy mocking
+- Не использовать `as` import unless prefix collision

package/src/autonomy.js

@@ -9,6 +9,7 @@ import {
   generateAuditLogHook,
   generateAliases,
   generateCIWorkflow,
+  isGlobalInstall,
 } from './hooks-gen.js';
 import { detectTechStack } from './detector.js';
 
@@ -25,10 +26,14 @@ export async function generateAutonomyConfig(profileName, projectDir, options =
   const profile = getProfile(profileName);
   const detected = options.detected || (await detectTechStack(projectDir));
 
+  // Hook commands need `claudenv` on PATH. If user installed via npm install -g
+  // we can call `claudenv` directly; otherwise fall back to `npx claudenv`.
+  const claudenvCmd = (await isGlobalInstall()) ? 'claudenv' : 'npx claudenv';
+
   const files = [
     {
       path: '.claude/settings.json',
-      content: generateSettingsJson(profile, detected),
+      content: generateSettingsJson(profile, detected, { claudenvCmd }),
     },
     {
       path: '.claude/hooks/pre-tool-use.sh',

package/src/canon.js

@@ -0,0 +1,214 @@
+/**
+ * CLI: `claudenv canon add/list/search/prune`
+ *
+ * Owns ~/.claudenv/memories/canon/index.yaml — a topic-keyed list of links.
+ * Format intentionally simple (flat YAML) so it's human-editable.
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { canonIndexPath } from './memory-paths.js';
+
+/**
+ * Read the canon yaml as a JS object. Tolerant to missing or empty files.
+ *
+ * Parser is intentionally minimal — full YAML would be overkill for a flat
+ * topic → [entries] mapping and would add a dependency.
+ */
+async function readCanon() {
+  let text;
+  try {
+    text = await readFile(canonIndexPath(), 'utf-8');
+  } catch {
+    return {};
+  }
+
+  const result = {};
+  let currentTopic = null;
+  let currentEntry = null;
+
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.replace(/\s+$/, '');
+    if (!line || line.startsWith('#')) continue;
+
+    // Topic key: `topic_name:` at column 0
+    const topicMatch = /^([a-zA-Z][a-zA-Z0-9_-]*):\s*$/.exec(line);
+    if (topicMatch) {
+      currentTopic = topicMatch[1];
+      result[currentTopic] = [];
+      currentEntry = null;
+      continue;
+    }
+
+    // List entry start: `  - key: value` or `  - key:` (multiline value)
+    const entryStartMatch = /^\s+-\s+([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*)$/.exec(line);
+    if (entryStartMatch && currentTopic) {
+      currentEntry = {};
+      currentEntry[entryStartMatch[1]] = unquote(entryStartMatch[2]);
+      result[currentTopic].push(currentEntry);
+      continue;
+    }
+
+    // Subsequent key in same entry: `    key: value`
+    const subKeyMatch = /^\s+([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*)$/.exec(line);
+    if (subKeyMatch && currentEntry) {
+      currentEntry[subKeyMatch[1]] = unquote(subKeyMatch[2]);
+      continue;
+    }
+  }
+
+  return result;
+}
+
+function unquote(s) {
+  const trimmed = s.trim();
+  if (!trimmed) return '';
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  // Inline arrays — pass through as raw string for now (rare in canon).
+  return trimmed;
+}
+
+/**
+ * Append an entry to the canon. Creates the topic group if absent.
+ *
+ * @param {object} opts
+ * @param {string} opts.topic - Topic slug
+ * @param {string} opts.url - Required
+ * @param {string} opts.why - Required
+ * @param {string} [opts.title]
+ * @param {string} [opts.author]
+ */
+export async function canonAdd({ topic, url, why, title, author }) {
+  if (!topic || !url || !why) {
+    throw new Error('claudenv canon add <topic> <url> --why "<reason>" required');
+  }
+
+  const canon = await readCanon();
+  if (!canon[topic]) canon[topic] = [];
+
+  const entry = {
+    ...(title ? { title } : {}),
+    ...(author ? { author } : {}),
+    url,
+    why,
+    added: new Date().toISOString().slice(0, 10),
+  };
+
+  // Skip duplicates by URL within the same topic.
+  const dup = canon[topic].find((e) => e.url === url);
+  if (dup) return { added: false, reason: 'duplicate url in same topic', entry: dup };
+
+  canon[topic].push(entry);
+  await writeCanon(canon);
+  return { added: true, topic, entry };
+}
+
+/**
+ * List all topics with their entries, or filter by one topic.
+ */
+export async function canonList(topic) {
+  const canon = await readCanon();
+  if (topic) {
+    return { [topic]: canon[topic] || [] };
+  }
+  return canon;
+}
+
+/**
+ * Substring search across title/why/url, returning matching entries grouped by topic.
+ */
+export async function canonSearch(query) {
+  if (!query) throw new Error('claudenv canon search <query> required');
+  const q = query.toLowerCase();
+  const canon = await readCanon();
+  const result = {};
+  for (const [topic, entries] of Object.entries(canon)) {
+    const hits = entries.filter((e) =>
+      [e.title, e.why, e.url, e.author].some((v) => v && v.toLowerCase().includes(q))
+    );
+    if (hits.length) result[topic] = hits;
+  }
+  return result;
+}
+
+/**
+ * Find entries whose `added` date is older than `months` months — candidates
+ * for review. Returns an array of `{topic, entry}` items.
+ */
+export async function canonPrune(months = 6) {
+  const cutoff = new Date();
+  cutoff.setMonth(cutoff.getMonth() - months);
+  const canon = await readCanon();
+  const stale = [];
+  for (const [topic, entries] of Object.entries(canon)) {
+    for (const entry of entries) {
+      if (!entry.added) {
+        stale.push({ topic, entry, reason: 'no `added` date' });
+        continue;
+      }
+      const added = new Date(entry.added);
+      if (!Number.isNaN(added.getTime()) && added < cutoff) {
+        stale.push({ topic, entry });
+      }
+    }
+  }
+  return stale;
+}
+
+/**
+ * Serialize canon back to YAML form. Comment-light, human-editable.
+ */
+async function writeCanon(canon) {
+  const lines = [];
+  lines.push('# Личный канон. Добавляйте через: claudenv canon add <topic> <url> --why "<reason>"');
+  lines.push('');
+  for (const [topic, entries] of Object.entries(canon)) {
+    lines.push(`${topic}:`);
+    for (const e of entries) {
+      const keys = Object.keys(e);
+      if (keys.length === 0) continue;
+      const [firstKey, ...rest] = keys;
+      lines.push(`  - ${firstKey}: ${quote(e[firstKey])}`);
+      for (const k of rest) {
+        lines.push(`    ${k}: ${quote(e[k])}`);
+      }
+    }
+    lines.push('');
+  }
+  await mkdir(dirname(canonIndexPath()), { recursive: true });
+  await writeFile(canonIndexPath(), lines.join('\n'), 'utf-8');
+}
+
+function quote(v) {
+  if (typeof v !== 'string') return String(v);
+  if (/[:#"\n]/.test(v)) return JSON.stringify(v);
+  return v;
+}
+
+/**
+ * Format canon for terminal output.
+ */
+export function formatCanon(canon) {
+  const topics = Object.keys(canon);
+  if (topics.length === 0) {
+    return 'Канон пуст. Добавь первые записи через `claudenv canon add <topic> <url> --why "..."`.';
+  }
+  const lines = [];
+  for (const t of topics) {
+    lines.push(`## ${t}`);
+    for (const e of canon[t] || []) {
+      const title = e.title || '(no title)';
+      const author = e.author ? ` — ${e.author}` : '';
+      lines.push(`  - ${title}${author}`);
+      lines.push(`    ${e.url}`);
+      if (e.why) lines.push(`    why: ${e.why}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n').trimEnd();
+}