@iola_adm/iola-cli 0.2.4 → 0.2.6

package/README.md

@@ -156,6 +156,23 @@ iola ai setup gigachat --model GigaChat-2
 
 У GigaChat для физических лиц есть Freemium-лимит на токены; для больших объемов используются платные пакеты. У YandexGPT тарификация идет через Yandex Cloud по токенам и квотам аккаунта, актуальные бесплатные гранты или лимиты нужно проверять в консоли Yandex Cloud.
 
+Геокодер для пользовательских geo-skills:
+
+```bash
+iola geo key set yandex
+iola geo key doctor
+iola geo geocode "Йошкар-Ола, улица Петрова, 15"
+iola geo nearby "Йошкар-Ола, улица Петрова, 15" --dataset all --limit 5
+iola geo distance --from "Петрова 15" --to "школа 7"
+iola geo map-link "школа 7"
+iola geo resolve "садик золотой петушок"
+iola geo route-context "школа 7"
+iola geo services "Йошкар-Ола, улица Петрова, 15"
+```
+
+Инструкция по получению ключа: [Yandex Geocoder API key](https://github.com/adm-iola/iola-cli/wiki/Yandex-Geocoder-API-key).
+Список сценариев: [Скиллы для жителей](https://github.com/adm-iola/iola-cli/wiki/Скиллы-для-жителей).
+
 Зарубежные API-ключи:
 
 - OpenAI Platform: регистрация `https://platform.openai.com/`, ключи `https://platform.openai.com/api-keys`;
@@ -182,6 +199,8 @@ iola version --check
 - [Первый запуск](https://github.com/adm-iola/iola-cli/wiki/Первый-запуск)
 - [Мастер настройки](https://github.com/adm-iola/iola-cli/wiki/Мастер-настройки)
 - [AI-профили](https://github.com/adm-iola/iola-cli/wiki/AI-профили)
+- [Yandex Geocoder API key](https://github.com/adm-iola/iola-cli/wiki/Yandex-Geocoder-API-key)
+- [Скиллы для жителей](https://github.com/adm-iola/iola-cli/wiki/Скиллы-для-жителей)
 - [Локальный инструментальный агент](https://github.com/adm-iola/iola-cli/wiki/Локальный-инструментальный-агент)
 - [Skills и toolsets](https://github.com/adm-iola/iola-cli/wiki/Skills-и-toolsets)
 - [Локальные файлы](https://github.com/adm-iola/iola-cli/wiki/Локальные-файлы)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iola_adm/iola-cli",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "CLI и AI-агент городского округа Йошкар-Ола.",
   "license": "MIT",
   "homepage": "https://github.com/adm-iola/iola-cli#readme",

package/skills/geo/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: geo
+description: Geo-сценарии для жителей: что рядом, карта, расстояние, уточнение места и населенного пункта.
+---
+
+Используй geo-функции CLI и Yandex Geocoder API для вопросов о местоположении.
+
+Основные пользовательские сценарии:
+
+- `nearby` - найти школы, детские сады и другие будущие городские объекты рядом с адресом.
+- `route-context` - объяснить, где находится объект: адрес, ориентиры, что рядом, ссылка на карту.
+- `address-to-services` - по адресу жителя подобрать ближайшие подключенные городские объекты.
+- `map-link` - дать ссылку на карту и координаты.
+- `place-resolver` - уточнить криво написанное место, адрес или название объекта.
+- `distance` - посчитать расстояние по прямой между адресом и объектом или между двумя объектами.
+- `area-filter` - не путать населенные пункты и районы, например Йошкар-Олу и Семеновку.
+
+Не придумывай координаты, расстояния и адреса. Если геокодер или слой данных не дал результата, прямо скажи, что данных недостаточно.
+
+Маршрут по дорогам не рассчитывается: расстояние в CLI считается по координатам как расстояние по прямой, если явно не подключен отдельный маршрутизатор.

package/src/cli.js

@@ -228,7 +228,7 @@ const DEFAULT_AI_CONFIG = {
     suggestions: true,
   },
   skills: {
-    enabled: ["education", "open-data", "reports", "local-model", "local-files", "browser-agent"],
+    enabled: ["education", "open-data", "geo", "reports", "local-model", "local-files", "browser-agent"],
   },
   daemon: {
     host: "127.0.0.1",
@@ -440,6 +440,7 @@ const COMMANDS = new Map([
   ["health", checkHealth],
   ["layers", listLayers],
   ["data", handleData],
+  ["geo", handleGeo],
   ["schools", listSchools],
   ["kindergartens", listKindergartens],
   ["search", searchAll],
@@ -653,6 +654,9 @@ Usage:
   iola kindergartens [--limit 10] [--search TEXT] [--where FIELD=VALUE] [--columns a,b,c] [--format table|json|csv]
   iola kindergartens get --inn INN [--json]
   iola search TEXT [--limit 5] [--format table|json|csv]
+  iola geo key set yandex
+  iola geo key doctor
+  iola geo geocode "Йошкар-Ола, ул. Петрова, 15"
   iola mcp-info [--json]
   iola setup codex
   iola onboard
@@ -1881,6 +1885,7 @@ async function doctor(args = []) {
       modelAvailable: await checkConfiguredModel({ ai: activeAiProfile }),
       openaiKey: process.env.OPENAI_API_KEY ? "env" : secrets.openai?.apiKey ? "local" : "missing",
       openrouterKey: process.env.OPENROUTER_API_KEY ? "env" : secrets.openrouter?.apiKey ? "local" : "missing",
+      yandexGeocoderKey: (process.env.YANDEX_GEOCODER_API_KEY || process.env.YANDEX_MAPS_API_KEY) ? "env" : secrets.yandexGeocoder?.apiKey ? "local" : "missing",
       ollama: diagnostics.ollama.installed ? diagnostics.ollama.version : "not-installed",
     },
     skills: {
@@ -2565,6 +2570,8 @@ async function handleWiki(args) {
     ["Первый запуск", `${base}/Первый-запуск`],
     ["Мастер настройки", `${base}/Мастер-настройки`],
     ["AI-профили", `${base}/AI-профили`],
+    ["Yandex Geocoder API key", `${base}/Yandex-Geocoder-API-key`],
+    ["Скиллы для жителей", `${base}/Скиллы-для-жителей`],
     ["Локальный инструментальный агент", `${base}/Локальный-инструментальный-агент`],
     ["Skills и toolsets", `${base}/Skills-и-toolsets`],
     ["Локальные файлы", `${base}/Локальные-файлы`],
@@ -5323,6 +5330,652 @@ async function deleteAiKey(provider) {
   console.log(`Локальный ключ ${provider} удален.`);
 }
 
+async function handleGeo(args) {
+  const [command, subcommand, ...rest] = args;
+
+  if (command === "key") {
+    await handleGeoKey([subcommand, ...rest]);
+    return;
+  }
+
+  if (command === "geocode") {
+    await geoGeocode([subcommand, ...rest].filter(Boolean));
+    return;
+  }
+
+  if (command === "nearby") {
+    await geoNearby([subcommand, ...rest].filter(Boolean));
+    return;
+  }
+
+  if (command === "distance") {
+    await geoDistance([subcommand, ...rest].filter(Boolean));
+    return;
+  }
+
+  if (command === "map-link") {
+    await geoMapLink([subcommand, ...rest].filter(Boolean));
+    return;
+  }
+
+  if (command === "resolve") {
+    await geoResolve([subcommand, ...rest].filter(Boolean));
+    return;
+  }
+
+  if (command === "route-context") {
+    await geoRouteContext([subcommand, ...rest].filter(Boolean));
+    return;
+  }
+
+  if (command === "services") {
+    await geoServices([subcommand, ...rest].filter(Boolean));
+    return;
+  }
+
+  if (command === "doctor" || command === "status") {
+    await printGeoKeyStatus({ check: command === "doctor" });
+    return;
+  }
+
+  throw new Error(`Команды geo:
+  iola geo key set yandex
+  iola geo key status
+  iola geo key doctor
+  iola geo key delete yandex
+  iola geo geocode "Йошкар-Ола, ул. Петрова, 15"
+  iola geo nearby "Йошкар-Ола, ул. Петрова, 15" --dataset all --limit 5
+  iola geo distance --from "Йошкар-Ола, ул. Петрова, 15" --to "школа 7"
+  iola geo map-link "школа 7"
+  iola geo resolve "садик золотой петушок"
+  iola geo route-context "школа 7"
+  iola geo services "Йошкар-Ола, ул. Петрова, 15"`);
+}
+
+async function handleGeoKey(args) {
+  const [action, provider = "yandex"] = args;
+  if (provider !== "yandex") {
+    throw new Error("Сейчас поддерживается только провайдер: yandex");
+  }
+
+  if (action === "set") {
+    await setYandexGeocoderKey();
+    return;
+  }
+
+  if (action === "status") {
+    await printGeoKeyStatus();
+    return;
+  }
+
+  if (action === "doctor" || action === "check") {
+    await printGeoKeyStatus({ check: true });
+    return;
+  }
+
+  if (action === "delete") {
+    const secrets = await loadSecrets();
+    delete secrets.yandexGeocoder;
+    await saveSecrets(secrets);
+    console.log("Локальный ключ yandex geocoder удален.");
+    return;
+  }
+
+  throw new Error("Команды geo key: set yandex, status, doctor, delete yandex.");
+}
+
+async function setYandexGeocoderKey() {
+  if (!process.stdin.isTTY) {
+    throw new Error("Для сохранения ключа запустите команду в интерактивном терминале.");
+  }
+
+  const key = (await askText("Введите YANDEX_GEOCODER_API_KEY: ")).trim();
+  if (!key) throw new Error("Ключ пустой, сохранение отменено.");
+
+  const secrets = await loadSecrets();
+  secrets.yandexGeocoder = { apiKey: key };
+  await saveSecrets(secrets);
+  console.log(`Ключ yandex geocoder сохранен локально: ${SECRETS_FILE}`);
+
+  const shouldCheck = await confirm("Проверить ключ запросом к Yandex Geocoder? [Y/n] ");
+  if (shouldCheck) await checkYandexGeocoderKey({ print: true });
+}
+
+async function printGeoKeyStatus(options = {}) {
+  const key = await getYandexGeocoderKey();
+  const rows = [{
+    provider: "yandex-geocoder",
+    env: (process.env.YANDEX_GEOCODER_API_KEY || process.env.YANDEX_MAPS_API_KEY) ? "yes" : "no",
+    local: (await loadSecrets()).yandexGeocoder?.apiKey ? "yes" : "no",
+    status: key ? "configured" : "missing",
+  }];
+  printTable(rows, [
+    ["provider", "Провайдер"],
+    ["env", "Env"],
+    ["local", "Локально"],
+    ["status", "Статус"],
+  ]);
+  if (options.check) await checkYandexGeocoderKey({ print: true });
+}
+
+async function geoGeocode(args) {
+  const query = args.join(" ").trim();
+  if (!query) throw new Error('Адрес обязателен. Пример: iola geo geocode "Йошкар-Ола, ул. Петрова, 15"');
+  const result = await callYandexGeocoder(query);
+  if (!result) {
+    console.log("Yandex Geocoder не вернул результат.");
+    return;
+  }
+  printKeyValue(result);
+}
+
+async function geoNearby(args) {
+  const options = parseOptions(args);
+  const query = options._.join(" ").trim();
+  if (!query) throw new Error('Адрес обязателен. Пример: iola geo nearby "Йошкар-Ола, ул. Петрова, 15" --dataset schools');
+  const answer = await buildNearbyAnswer(query, {
+    dataset: normalizeGeoDataset(options.dataset || inferGeoDataset(query)),
+    limit: Number(options.limit || 5),
+    radius: Number(options.radius || 0),
+  });
+  console.log(answer);
+}
+
+async function geoDistance(args) {
+  const options = parseOptions(args);
+  const from = options.from || options.address || options._.join(" ").split(/\s+(?:до|и|->)\s+/iu)[0]?.trim();
+  const to = options.to || options._.join(" ").split(/\s+(?:до|и|->)\s+/iu)[1]?.trim();
+  if (!from || !to) throw new Error('Нужны две точки. Пример: iola geo distance --from "Петрова 15" --to "школа 7"');
+  const answer = await buildDistanceAnswer(from, to);
+  console.log(answer);
+}
+
+async function geoMapLink(args) {
+  const query = args.join(" ").trim();
+  if (!query) throw new Error('Объект или адрес обязателен. Пример: iola geo map-link "школа 7"');
+  const answer = await buildMapLinkAnswer(query);
+  console.log(answer);
+}
+
+async function geoResolve(args) {
+  const query = args.join(" ").trim();
+  if (!query) throw new Error('Место или объект обязателен. Пример: iola geo resolve "садик золотой петушок"');
+  const answer = await buildPlaceResolverAnswer(query);
+  console.log(answer);
+}
+
+async function geoRouteContext(args) {
+  const query = args.join(" ").trim();
+  if (!query) throw new Error('Объект или адрес обязателен. Пример: iola geo route-context "школа 7"');
+  const answer = await buildRouteContextAnswer(query);
+  console.log(answer);
+}
+
+async function geoServices(args) {
+  const options = parseOptions(args);
+  const query = options._.join(" ").trim();
+  if (!query) throw new Error('Адрес обязателен. Пример: iola geo services "Йошкар-Ола, ул. Петрова, 15"');
+  const answer = await buildAddressToServicesAnswer(query, { limit: Number(options.limit || 3) });
+  console.log(answer);
+}
+
+async function checkYandexGeocoderKey(options = {}) {
+  try {
+    const result = await callYandexGeocoder("Йошкар-Ола");
+    if (!result?.coordinates) throw new Error("Yandex Geocoder вернул пустой результат.");
+    if (options.print) {
+      console.log(`Yandex Geocoder: ok (${result.name || result.address || result.coordinates})`);
+    }
+    return true;
+  } catch (error) {
+    if (options.print) {
+      console.log(`Yandex Geocoder: error - ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return false;
+  }
+}
+
+async function callYandexGeocoder(query) {
+  const apiKey = await getYandexGeocoderKey();
+  if (!apiKey) {
+    throw new Error("Yandex Geocoder API key не найден. Выполните iola geo key set yandex или задайте YANDEX_GEOCODER_API_KEY.");
+  }
+
+  const url = new URL("https://geocode-maps.yandex.ru/v1/");
+  url.searchParams.set("apikey", apiKey);
+  url.searchParams.set("geocode", query);
+  url.searchParams.set("format", "json");
+  url.searchParams.set("lang", "ru_RU");
+  url.searchParams.set("results", "1");
+
+  const response = await fetchYandexGeocoderWithRetry(url);
+
+  if (!response.ok) {
+    const text = await response.text();
+    if (response.status === 403 && /Invalid api key/i.test(text)) {
+      throw new Error(`Yandex Geocoder request failed: ${response.status} ${response.statusText}\nInvalid api key. Если ключ только что создан, подождите до 15 минут: Yandex указывает, что активация ключа может занять до 15 минут.`);
+    }
+    throw new Error(`Yandex Geocoder request failed: ${response.status} ${response.statusText}\n${sanitizeSecretFromText(text, apiKey)}`);
+  }
+
+  const payload = await response.json();
+  const member = payload?.response?.GeoObjectCollection?.featureMember?.[0];
+  const object = member?.GeoObject;
+  if (!object) return null;
+  const point = object.Point?.pos || "";
+  const [lon, lat] = point.split(/\s+/);
+  return {
+    name: object.name || "",
+    address: object.metaDataProperty?.GeocoderMetaData?.text || object.description || "",
+    precision: object.metaDataProperty?.GeocoderMetaData?.precision || "",
+    coordinates: lat && lon ? `${lat}, ${lon}` : point,
+    map: lat && lon ? `https://yandex.ru/maps/?pt=${lon},${lat}&z=16&l=map` : "",
+  };
+}
+
+async function fetchYandexGeocoderWithRetry(url) {
+  let lastError = null;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      const response = await fetch(url, { signal: AbortSignal.timeout(15000) });
+      if (response.status !== 429 || attempt === 2) return response;
+      await sleep(700 * (attempt + 1));
+    } catch (error) {
+      lastError = error;
+      if (attempt === 2) break;
+      await sleep(500 * (attempt + 1));
+    }
+  }
+  throw new Error(formatProviderFetchError("Yandex Geocoder", lastError));
+}
+
+const geoMemoryCache = new Map();
+
+async function buildGeoDirectAnswer(question) {
+  const normalized = String(question || "").toLocaleLowerCase("ru-RU");
+  if (!isGeoQuestion(normalized)) return "";
+  const place = detectEducationPlace(question);
+  if (place && !place.supported && /(школ|сош|лице|гимнази|сад|детсад|детск\w*\s+сад|садик)/iu.test(normalized)) {
+    return formatUnsupportedEducationGeoPlace(place);
+  }
+
+  try {
+    if (/(расстояни|как далеко|далеко ли|ближе)/iu.test(normalized)) {
+      const pair = extractDistancePair(question);
+      if (pair.from && pair.to) return buildDistanceAnswer(pair.from, pair.to);
+    }
+
+    if (/(карт[аеу]|ссылк.*карт|открыть.*карт)/iu.test(normalized)) {
+      const query = cleanupGeoObjectQuery(question);
+      if (query) return buildMapLinkAnswer(query);
+    }
+
+    if (/(где находится|как пройти|как добраться|что рядом|ориентир)/iu.test(normalized)) {
+      const query = cleanupGeoObjectQuery(question);
+      if (query) return buildRouteContextAnswer(query);
+    }
+
+    if (/(мой адрес|живу|по адресу)/iu.test(normalized)) {
+      const address = extractAddressForNearby(question);
+      if (address) return buildAddressToServicesAnswer(address, { limit: 3 });
+    }
+
+    if (/(рядом|поблизости|ближайш|ближе|около|возле)/iu.test(normalized)) {
+      const address = extractAddressForNearby(question);
+      if (address) return buildNearbyAnswer(address, { dataset: normalizeGeoDataset(inferGeoDataset(question)), limit: 5 });
+    }
+
+    if (/(уточни место|какой населенный пункт|какой район|фильтр.*район|фильтр.*населен|не путай.*населен)/iu.test(normalized)) {
+      const query = cleanupGeoObjectQuery(question);
+      if (query) return buildPlaceResolverAnswer(query);
+    }
+  } catch (error) {
+    if (/Yandex Geocoder API key не найден/iu.test(String(error?.message || ""))) return "";
+    return `Не смог выполнить geo-запрос: ${error instanceof Error ? error.message : String(error)}`;
+  }
+
+  return "";
+}
+
+function formatUnsupportedEducationGeoPlace(place) {
+  return `В текущих открытых данных iola-cli есть данные городского округа Йошкар-Ола. Данных по ${place.locative || place.label} в подключенных слоях нет, поэтому не могу надежно ответить по этому объекту.`;
+}
+
+function isGeoQuestion(normalized) {
+  return /(рядом|поблизости|ближайш|ближе|расстояни|как далеко|карт[аеу]|где находится|как пройти|как добраться|мой адрес|живу|по адресу|ориентир|уточни место|какой населенный пункт|какой район|фильтр.*район|фильтр.*населен)/iu.test(normalized);
+}
+
+async function buildNearbyAnswer(address, options = {}) {
+  const origin = await resolveGeoPoint(address);
+  const dataset = normalizeGeoDataset(options.dataset || "all");
+  const limit = Math.max(1, Number(options.limit || 5));
+  const radius = Number(options.radius || 0);
+  const candidates = await getGeoCandidates(dataset);
+  const ranked = (await asyncMapLimit(candidates, 6, async (item) => {
+    const point = item.address
+      ? await geocodeCached(normalizeAddressForGeocoder(item.address)).catch(() => null)
+      : await resolveGeoPoint(item.name).catch(() => null);
+    if (!point?.lat || !point?.lon) return null;
+    const distanceMeters = haversineMeters(origin, point);
+    return { ...item, point, distanceMeters };
+  })).filter(Boolean)
+    .filter((item) => !radius || item.distanceMeters <= radius)
+    .sort((a, b) => a.distanceMeters - b.distanceMeters)
+    .slice(0, limit);
+
+  if (ranked.length === 0) return `Рядом с адресом "${address}" не нашел объектов в подключенных слоях.`;
+
+  return [
+    `Ближайшие объекты к адресу: ${origin.address || address}`,
+    ...ranked.map((item, index) => `${index + 1}. ${item.name} — ${formatDistance(item.distanceMeters)}${item.address ? `\n   Адрес: ${item.address}` : ""}${item.inn ? `\n   ИНН: ${item.inn}` : ""}${item.point.map ? `\n   Карта: ${item.point.map}` : ""}`),
+    `Источник: Yandex Geocoder + слои ${dataset === "all" ? "schools, kindergartens" : dataset}.`,
+  ].join("\n");
+}
+
+async function buildDistanceAnswer(fromQuery, toQuery) {
+  const from = await resolveGeoPoint(fromQuery);
+  const to = await resolveGeoPoint(toQuery);
+  const distance = haversineMeters(from, to);
+  return [
+    `Расстояние по прямой: ${formatDistance(distance)}.`,
+    `От: ${from.name || from.address || fromQuery}${from.address && from.address !== from.name ? ` (${from.address})` : ""}`,
+    `До: ${to.name || to.address || toQuery}${to.address && to.address !== to.name ? ` (${to.address})` : ""}`,
+    to.map ? `Карта точки назначения: ${to.map}` : "",
+    "Это расстояние по координатам, не маршрут по дорогам.",
+  ].filter(Boolean).join("\n");
+}
+
+async function buildMapLinkAnswer(query) {
+  const point = await resolveGeoPoint(query);
+  return [
+    point.name || query,
+    point.address ? `Адрес: ${point.address}` : "",
+    point.coordinates ? `Координаты: ${point.coordinates}` : "",
+    point.map ? `Карта: ${point.map}` : "",
+  ].filter(Boolean).join("\n");
+}
+
+async function buildPlaceResolverAnswer(query) {
+  const match = await resolveGeoEntity(query).catch(() => null);
+  if (match) {
+    return [
+      `Нашел объект: ${match.name}`,
+      match.address ? `Адрес: ${match.address}` : "",
+      match.inn ? `ИНН: ${match.inn}` : "",
+      match.layer ? `Слой: ${match.layer}` : "",
+      match.map ? `Карта: ${match.map}` : "",
+    ].filter(Boolean).join("\n");
+  }
+  const point = await callYandexGeocoder(query);
+  if (!point) return `Не смог уточнить место: ${query}`;
+  return [
+    `Уточнил место через геокодер: ${point.name || query}`,
+    point.address ? `Адрес: ${point.address}` : "",
+    point.precision ? `Точность: ${point.precision}` : "",
+    point.coordinates ? `Координаты: ${point.coordinates}` : "",
+    point.map ? `Карта: ${point.map}` : "",
+  ].filter(Boolean).join("\n");
+}
+
+async function buildRouteContextAnswer(query) {
+  const point = await resolveGeoPoint(query);
+  const nearby = await buildNearbyAnswer(point.address || query, { dataset: "all", limit: 3 });
+  return [
+    `${point.name || query}`,
+    point.address ? `Адрес: ${point.address}` : "",
+    point.coordinates ? `Координаты: ${point.coordinates}` : "",
+    point.map ? `Карта: ${point.map}` : "",
+    "",
+    nearby,
+  ].filter(Boolean).join("\n");
+}
+
+async function buildAddressToServicesAnswer(address, options = {}) {
+  const limit = Math.max(1, Number(options.limit || 3));
+  const schools = await buildNearbyAnswer(address, { dataset: "schools", limit });
+  const kindergartens = await buildNearbyAnswer(address, { dataset: "kindergartens", limit });
+  return [
+    `По адресу "${address}" ближайшие подключенные городские объекты:`,
+    "",
+    "Школы:",
+    stripNearbyHeader(schools),
+    "",
+    "Детские сады:",
+    stripNearbyHeader(kindergartens),
+  ].join("\n");
+}
+
+function stripNearbyHeader(text) {
+  return String(text || "").split("\n").filter((line) => !line.startsWith("Ближайшие объекты к адресу:")).join("\n");
+}
+
+async function resolveGeoPoint(query) {
+  const entity = await resolveGeoEntity(query).catch(() => null);
+  if (entity?.address) {
+    const point = await geocodeCached(normalizeAddressForGeocoder(entity.address));
+    return mergeGeoEntityPoint(entity, point);
+  }
+  return geocodeCached(query);
+}
+
+async function resolveGeoEntity(query) {
+  const dataset = normalizeGeoDataset(inferGeoDataset(query));
+  let candidates = await getGeoCandidates(dataset);
+  const normalized = normalizeGeoText(query);
+  const number = extractEntityNumberFromQuestion(query, dataset === "kindergartens" ? "kindergartens" : "schools");
+  const place = detectEducationPlace(query);
+  if (place && !place.supported) return null;
+  if (place?.supported) {
+    const placeMatches = candidates.filter((item) => geoItemMatchesPlace(item, place));
+    if (placeMatches.length > 0) candidates = placeMatches;
+  }
+  if (number) {
+    const exactNumberMatches = candidates.filter((item) => itemNameHasNumber(item, number));
+    if (exactNumberMatches.length === 1) {
+      const point = exactNumberMatches[0].address ? await geocodeCached(normalizeAddressForGeocoder(exactNumberMatches[0].address)).catch(() => null) : null;
+      return mergeGeoEntityPoint(exactNumberMatches[0], point);
+    }
+    if (exactNumberMatches.length > 1) {
+      const scoped = place?.supported
+        ? exactNumberMatches.filter((item) => geoItemMatchesPlace(item, place))
+        : exactNumberMatches;
+      const bestExact = scoped[0] || exactNumberMatches[0];
+      const point = bestExact.address ? await geocodeCached(normalizeAddressForGeocoder(bestExact.address)).catch(() => null) : null;
+      return mergeGeoEntityPoint(bestExact, point);
+    }
+  }
+  const scored = candidates.map((item) => ({ ...item, score: scoreGeoCandidate(item, normalized, number, place) }))
+    .filter((item) => item.score > 0)
+    .sort((a, b) => b.score - a.score);
+  const best = scored[0];
+  if (!best) return null;
+  const point = best.address ? await geocodeCached(normalizeAddressForGeocoder(best.address)).catch(() => null) : null;
+  return mergeGeoEntityPoint(best, point);
+}
+
+function mergeGeoEntityPoint(entity, point) {
+  if (!point) return entity;
+  return {
+    ...entity,
+    geoName: point.name || "",
+    geocodedAddress: point.address || "",
+    precision: point.precision || "",
+    coordinates: point.coordinates || "",
+    map: point.map || "",
+    lat: point.lat,
+    lon: point.lon,
+  };
+}
+
+function scoreGeoCandidate(item, normalizedQuery, number, place) {
+  const name = normalizeGeoText(item.name);
+  const address = normalizeGeoText(item.address);
+  let score = 0;
+  if (number && itemNameHasNumber(item, number)) score += 20;
+  for (const token of normalizeGeoText(normalizedQuery).split(/\s+/).filter((part) => part.length >= 3)) {
+    if (name.includes(token)) score += 3;
+    if (address.includes(token)) score += 1;
+  }
+  if (place?.supported && geoItemMatchesPlace(item, place)) score += 8;
+  if (/(сад|детсад|садик)/iu.test(normalizedQuery) && item.layer === "kindergartens") score += 5;
+  if (/(школ|лице|гимнази)/iu.test(normalizedQuery) && item.layer === "schools") score += 5;
+  return score;
+}
+
+function geoItemMatchesPlace(item, place) {
+  if (!place?.supported) return false;
+  const haystack = normalizeGeoText(`${item.name || ""} ${item.address || ""}`);
+  const aliases = [place.label, ...(place.aliases || [])].map(normalizeGeoText).filter(Boolean);
+  return aliases.some((alias) => haystack.includes(alias));
+}
+
+async function getGeoCandidates(dataset = "all") {
+  const layers = dataset === "all" ? ["schools", "kindergartens"] : [dataset];
+  const result = [];
+  for (const layer of layers) {
+    const items = normalizeItems(await fetchAllApiItems(`${await getApiBaseUrl()}/${DATASETS[layer].endpoint}`))
+      .map(selectPublicSummary)
+      .filter((item) => item.name || item.address)
+      .map((item) => ({ ...item, layer }));
+    result.push(...items);
+  }
+  return result;
+}
+
+async function geocodeCached(query) {
+  const key = normalizeGeoText(query);
+  if (geoMemoryCache.has(key)) return geoMemoryCache.get(key);
+  const value = await callYandexGeocoder(query);
+  if (!value) throw new Error(`Yandex Geocoder не вернул результат для: ${query}`);
+  const parsed = parseCoordinates(value.coordinates);
+  const point = { ...value, ...parsed };
+  geoMemoryCache.set(key, point);
+  return point;
+}
+
+function parseCoordinates(coordinates) {
+  const [lat, lon] = String(coordinates || "").split(",").map((part) => Number(part.trim()));
+  return { lat, lon };
+}
+
+async function asyncMapLimit(items, limit, mapper) {
+  const source = Array.from(items || []);
+  if (source.length === 0) return [];
+  const results = new Array(source.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.max(1, Math.min(limit, source.length)) }, async () => {
+    while (next < source.length) {
+      const index = next;
+      next += 1;
+      results[index] = await mapper(source[index], index);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+function haversineMeters(a, b) {
+  const radius = 6371000;
+  const lat1 = toRadians(Number(a.lat));
+  const lat2 = toRadians(Number(b.lat));
+  const deltaLat = toRadians(Number(b.lat) - Number(a.lat));
+  const deltaLon = toRadians(Number(b.lon) - Number(a.lon));
+  const x = Math.sin(deltaLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(deltaLon / 2) ** 2;
+  return 2 * radius * Math.atan2(Math.sqrt(x), Math.sqrt(1 - x));
+}
+
+function toRadians(value) {
+  return value * Math.PI / 180;
+}
+
+function formatDistance(meters) {
+  if (!Number.isFinite(meters)) return "-";
+  if (meters < 1000) return `${Math.round(meters)} м`;
+  return `${(meters / 1000).toFixed(meters < 10000 ? 1 : 0)} км`;
+}
+
+function normalizeGeoDataset(value) {
+  const text = String(value || "").toLocaleLowerCase("ru-RU");
+  if (text === "schools" || /школ|лице|гимнази/.test(text)) return "schools";
+  if (text === "kindergartens" || /сад|детсад|садик/.test(text)) return "kindergartens";
+  return "all";
+}
+
+function inferGeoDataset(text) {
+  const normalized = String(text || "").toLocaleLowerCase("ru-RU");
+  if (/(сад|детсад|садик)/iu.test(normalized)) return "kindergartens";
+  if (/(школ|лице|гимнази)/iu.test(normalized)) return "schools";
+  return "all";
+}
+
+function extractAddressForNearby(question) {
+  const text = String(question || "").trim();
+  const match = text.match(/(?:рядом с|рядом|около|возле|поблизости от|живу на|мой адрес|по адресу)\s+(.+)/iu);
+  if (match?.[1]) return cleanupGeoAddress(match[1].split(/[,;]\s*(?:какие|что|где|кто|дай|покажи)/iu)[0]);
+  return cleanupGeoAddress(text);
+}
+
+function extractDistancePair(question) {
+  const text = String(question || "").trim();
+  const explicit = {
+    from: text.match(/(?:от|from)\s+(.+?)\s+(?:до|к|to)\s+(.+)/iu)?.[1],
+    to: text.match(/(?:от|from)\s+(.+?)\s+(?:до|к|to)\s+(.+)/iu)?.[2],
+  };
+  if (explicit.from && explicit.to) return { from: cleanupGeoAddress(explicit.from), to: cleanupGeoAddress(explicit.to) };
+  const parts = text.split(/\s+(?:и|до|->)\s+/iu).map(cleanupGeoAddress).filter(Boolean);
+  return { from: parts[0] || "", to: parts[1] || "" };
+}
+
+function cleanupGeoObjectQuery(text) {
+  return cleanupGeoAddress(String(text || "")
+    .replace(/^(?:где находится|как пройти|как добраться|покажи|дай|открой|найди|ссылку на карту|ссылка на карту)\s+/iu, "")
+    .replace(/\b(?:на карте|карту|карта|рядом|что рядом|ориентиры?)\b/giu, ""));
+}
+
+function cleanupGeoAddress(text) {
+  return String(text || "")
+    .replace(/[?.!]+$/u, "")
+    .replace(/(^|\s)улице(?=\s|$)/giu, "$1улица")
+    .replace(/\b(?:какие|какой|какая|есть|ближайшие|ближайший|школы|школа|детские сады|детский сад|садики|садик|объекты|городские|учреждения|рядом|поблизости)\b/giu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function normalizeAddressForGeocoder(address) {
+  const source = String(address || "").trim();
+  if (!source) return source;
+  let text = source
+    .replace(/^\s*\d{6},?\s*/u, "")
+    .replace(/\bРоссия,\s*/iu, "")
+    .replace(/\bРоссийская Федерация,\s*/iu, "")
+    .replace(/\bРеспублика Марий Эл,\s*/iu, "")
+    .replace(/\bгородской округ\s+город\s+Йошкар-Ола,\s*/iu, "")
+    .replace(/\bГОРОД ЙОШКАР-ОЛА,\s*/iu, "")
+    .replace(/\bЙошкар-Ола\s+г,\s*/iu, "")
+    .replace(/\bгород\s+Йошкар-Ола,\s*/iu, "Йошкар-Ола, ")
+    .replace(/\bсело\s+Сем[её]новка,\s*/iu, "Йошкар-Ола, Семёновка, ")
+    .replace(/\bдом\s+/giu, "д. ")
+    .replace(/\bулица\s+/giu, "ул. ")
+    .replace(/([А-ЯЁ])\.(?=[А-ЯЁ])/gu, "$1. ")
+    .replace(/\s+/g, " ")
+    .replace(/,\s*,/g, ",")
+    .trim();
+  if (!/(йошкар|сем[её]новк)/iu.test(text)) text = `Йошкар-Ола, ${text}`;
+  return text;
+}
+
+function normalizeGeoText(text) {
+  return String(text || "").toLocaleLowerCase("ru-RU").replace(/ё/g, "е").replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+}
+
+async function getYandexGeocoderKey() {
+  if (process.env.YANDEX_GEOCODER_API_KEY || process.env.YANDEX_MAPS_API_KEY) {
+    return process.env.YANDEX_GEOCODER_API_KEY || process.env.YANDEX_MAPS_API_KEY;
+  }
+  const secrets = await loadSecrets();
+  return secrets.yandexGeocoder?.apiKey || "";
+}
+
 function openDatabase() {
   const db = new DatabaseSync(DB_FILE);
   db.exec("PRAGMA busy_timeout = 5000;");
@@ -6735,6 +7388,20 @@ async function aiAsk(args, context = {}) {
   const historyEnabled = !options.bare && !options["no-history"] && isFeatureEnabled("sqlite-history");
   const sessionId = historyEnabled && isFeatureEnabled("sessions") ? ensureSessionForAsk(options, providerConfig, question) : null;
   const history = context.history || (sessionId ? getSessionAiHistory(sessionId) : []);
+  const geoAnswer = await buildGeoDirectAnswer(question);
+  if (geoAnswer) {
+    if (historyEnabled) {
+      recordAskHistory({ question, answer: geoAnswer, providerConfig, dataContext, error: "", sessionId });
+      appendSessionExchange(sessionId, question, geoAnswer, dataContext, "");
+    }
+    emitEvent(options, "answer", { length: geoAnswer.length, sessionId, direct: true, geo: true });
+    if (options.output) {
+      await assertPermission("writeFiles");
+      await writeFile(options.output, geoAnswer, "utf8");
+    }
+    if (!options.quiet) console.log(geoAnswer);
+    return geoAnswer;
+  }
   const directAnswer = await buildDirectDataAnswer(question, dataContext);
   if (directAnswer) {
     if (historyEnabled) {
@@ -7104,6 +7771,11 @@ async function localToolAsk(question, providerConfig, options) {
     if (!options.quiet) console.log(casualAnswer);
     return casualAnswer;
   }
+  const geoAnswer = await buildGeoDirectAnswer(question);
+  if (geoAnswer) {
+    if (!options.quiet) console.log(geoAnswer);
+    return geoAnswer;
+  }
   await ensureLocalData();
   const personRoleAnswer = buildPersonRoleDirectAnswer(question);
   if (personRoleAnswer) {
@@ -7577,9 +8249,9 @@ function extractEntityNumberFromQuestion(question, layer) {
   const isKindergarten = layer === "kindergartens";
   const isSchool = layer === "schools";
   const patterns = isKindergarten
-    ? [/(?:детск\w*\s+сад\w*|детсад\w*|сад\w*)\s*(?:№|номер|n)?\s*(\d{1,4})/iu, /№\s*(\d{1,4})/iu]
+    ? [/(?:детск[\p{L}\p{N}_-]*\s+сад[\p{L}\p{N}_-]*|детсад[\p{L}\p{N}_-]*|сад[\p{L}\p{N}_-]*)\s*(?:№|номер|n)?\s*(\d{1,4})/iu, /№\s*(\d{1,4})/iu]
     : isSchool
-      ? [/(?:школ\w*|сош|гимнази\w*|лице\w*)\s*(?:№|номер|n)?\s*(\d{1,4})/iu, /№\s*(\d{1,4})/iu]
+      ? [/(?:школ[\p{L}\p{N}_-]*|сош|гимнази[\p{L}\p{N}_-]*|лице[\p{L}\p{N}_-]*)\s*(?:№|номер|n)?\s*(\d{1,4})/iu, /№\s*(\d{1,4})/iu]
       : [/№\s*(\d{1,4})/iu];
   for (const pattern of patterns) {
     const match = text.match(pattern);
@@ -9251,6 +9923,11 @@ async function onboard(args = []) {
       await chooseAndSaveApiModel("gigachat");
     }
   }
+  if (components.includes("yandex-geocoder")) {
+    if (process.stdin.isTTY) {
+      await setYandexGeocoderKey();
+    }
+  }
   if (components.includes("codex")) {
     await installCodexIfMissing();
     await aiSetup(["codex"]);
@@ -9299,6 +9976,7 @@ async function chooseOnboardComponents(status = null) {
       11: "index",
       12: "browser",
       13: "ollama",
+      14: "yandex-geocoder",
     };
     return [...selected].map((item) => map[item] || item).filter(Boolean);
   } finally {
@@ -9311,13 +9989,14 @@ function isOnboardExitAnswer(answer) {
 }
 
 async function getOnboardComponentStatus() {
-  const [config, readiness, browser, archive, codexVersion, ollamaVersion] = await Promise.all([
+  const [config, readiness, browser, archive, codexVersion, ollamaVersion, yandexGeocoderKey] = await Promise.all([
     loadConfig(),
     getAiReadiness(),
     getBrowserStatus(),
     findCommand(["7z", "7zz", "7za"], ["--help"]).catch(() => null),
     getCommandVersion("codex", ["--version"]),
     getOllamaVersion(),
+    getYandexGeocoderKey(),
   ]);
   const workspaceReady = existsSync(PROJECT_CONTEXT_FILE) || existsSync(PROJECT_CONTEXT_DIR_FILE) || existsSync(PROJECT_IOLA_DIR);
   const policyReady = (config.toolsets?.enabled || []).includes("analyst");
@@ -9335,6 +10014,7 @@ async function getOnboardComponentStatus() {
     archive: Boolean(archive),
     index: false,
     browser: browser.installed === "yes",
+    "yandex-geocoder": Boolean(yandexGeocoderKey),
   };
 }
 
@@ -9353,6 +10033,7 @@ function onboardComponentRows(status) {
     ["11", "index", "Индекс локальных документов", "настраивается под выбранную папку"],
     ["12", "browser", "Browser runtime", "Playwright/Chromium установлен"],
     ["13", "ollama", "Ollama", "опциональный локальный runtime"],
+    ["14", "yandex-geocoder", "Yandex Geocoder API", "ключ геокодера сохранен или есть в env"],
   ];
   return rows.map(([number, key, title, hint]) => ({ number, key, title, hint, status: status[key] ? "готово" : "не настроено" }));
 }
@@ -9367,7 +10048,7 @@ function defaultOnboardSelection(status) {
 }
 
 function defaultOnboardComponents(status) {
-  const map = { 1: "workspace", 2: "policy", 3: "iola", 4: "yandexgpt", 5: "gigachat", 6: "openai", 7: "openrouter", 8: "codex", 9: "codex-mcp", 10: "archive", 11: "index", 12: "browser", 13: "ollama" };
+  const map = { 1: "workspace", 2: "policy", 3: "iola", 4: "yandexgpt", 5: "gigachat", 6: "openai", 7: "openrouter", 8: "codex", 9: "codex-mcp", 10: "archive", 11: "index", 12: "browser", 13: "ollama", 14: "yandex-geocoder" };
   return defaultOnboardSelection(status).map((item) => map[item]).filter(Boolean);
 }
 
@@ -9381,7 +10062,7 @@ function parseOptions(args) {
     } else if (arg === "--check" || arg === "--upgrade-node") {
       result.check = true;
       result[arg.slice(2)] = true;
-    } else if (arg === "--limit" || arg === "--offset" || arg === "--search" || arg === "--replace" || arg === "--text" || arg === "--path" || arg === "--depth" || arg === "--max-bytes" || arg === "--query" || arg === "--where" || arg === "--columns" || arg === "--inn" || arg === "--model" || arg === "--provider" || arg === "--profile" || arg === "--name" || arg === "--source" || arg === "--command" || arg === "--prompt" || arg === "--description" || arg === "--base-url" || arg === "--repo" || arg === "--model-dir" || arg === "--sandbox" || arg === "--approval" || arg === "--cwd" || arg === "--codex-profile" || arg === "--format" || arg === "--output" || arg === "--schema" || arg === "--session" || arg === "--temperature" || arg === "--config" || arg === "--dataset" || arg === "--save" || arg === "--reasoning" || arg === "--agent" || arg === "--scope" || arg === "--selector" || arg === "--url" || arg === "--timeout" || arg === "--wait" || arg === "--viewport" || arg === "--press" || arg === "--script" || arg === "--auth-url" || arg === "--token-url" || arg === "--userinfo-url" || arg === "--client-id" || arg === "--client-secret" || arg === "--redirect-host" || arg === "--redirect-port" || arg === "--redirect-path" || arg === "--debug-file") {
+    } else if (arg === "--limit" || arg === "--offset" || arg === "--search" || arg === "--replace" || arg === "--text" || arg === "--path" || arg === "--depth" || arg === "--max-bytes" || arg === "--query" || arg === "--where" || arg === "--columns" || arg === "--inn" || arg === "--model" || arg === "--provider" || arg === "--profile" || arg === "--name" || arg === "--source" || arg === "--command" || arg === "--prompt" || arg === "--description" || arg === "--base-url" || arg === "--repo" || arg === "--model-dir" || arg === "--sandbox" || arg === "--approval" || arg === "--cwd" || arg === "--codex-profile" || arg === "--format" || arg === "--output" || arg === "--schema" || arg === "--session" || arg === "--temperature" || arg === "--config" || arg === "--dataset" || arg === "--save" || arg === "--reasoning" || arg === "--agent" || arg === "--scope" || arg === "--selector" || arg === "--url" || arg === "--timeout" || arg === "--wait" || arg === "--viewport" || arg === "--press" || arg === "--script" || arg === "--auth-url" || arg === "--token-url" || arg === "--userinfo-url" || arg === "--client-id" || arg === "--client-secret" || arg === "--redirect-host" || arg === "--redirect-port" || arg === "--redirect-path" || arg === "--debug-file" || arg === "--from" || arg === "--to" || arg === "--radius" || arg === "--address") {
       result[arg.slice(2)] = args[index + 1];
       index += 1;
     } else {
@@ -9630,6 +10311,7 @@ function selectSkillsForPrompt(config, question = "", options = {}) {
   const normalized = String(question || "").toLocaleLowerCase("ru-RU");
   if (enabled.has("local-model")) selected.add("local-model");
   if (enabled.has("open-data") && shouldUseDataContext(question, options)) selected.add("open-data");
+  if (enabled.has("geo") && isGeoQuestion(normalized)) selected.add("geo");
   if (enabled.has("reports") && /(отчет|отчёт|выгруз|csv|xlsx|качество|провер)/iu.test(normalized)) selected.add("reports");
   if (enabled.has("local-files") && (options.files || /(файл|папк|readme|документ|архив)/iu.test(normalized))) selected.add("local-files");
   if (enabled.has("browser-agent") && /(браузер|сайт|страниц|url|https?:\/\/)/iu.test(normalized)) selected.add("browser-agent");

package/wiki/Home.md

@@ -11,6 +11,7 @@
 - выгрузка CSV/JSON;
 - работа с локальной моделью Ollama;
 - работа с YandexGPT, GigaChat, OpenAI, OpenRouter и Codex CLI;
+- geo-сценарии для жителей через Yandex Geocoder API;
 - подключение публичного MCP-сервера.
 
 Быстрый старт:
@@ -28,6 +29,8 @@ iola ask "найди школу 29"
 - [Первый запуск](Первый-запуск)
 - [Мастер настройки](Мастер-настройки)
 - [AI-профили](AI-профили)
+- [Yandex Geocoder API key](Yandex-Geocoder-API-key)
+- [Скиллы для жителей](Скиллы-для-жителей)
 - [Локальный инструментальный агент](Локальный-инструментальный-агент)
 - [Skills и toolsets](Skills-и-toolsets)
 - [Локальные файлы](Локальные-файлы)

package/wiki/Yandex-Geocoder-API-key.md

@@ -0,0 +1,72 @@
+# Yandex Geocoder API key
+
+Эта инструкция нужна для подключения геокодера Яндекса к `iola-cli`.
+
+Геокодер нужен жителям для вопросов вида:
+
+- что находится рядом с моим адресом;
+- где находится школа или детский сад;
+- какой объект ближе;
+- открыть объект на карте;
+- не перепутать Йошкар-Олу, Семеновку и другие населенные пункты.
+
+## Получение ключа
+
+1. Откройте Кабинет разработчика Яндекса: `https://developer.tech.yandex.ru/services/`.
+2. Войдите в аккаунт Яндекса.
+3. В списке `API интерфейсы` найдите `API Геокодера`.
+4. Откройте `API Геокодера`.
+5. Проверьте блок тарифа. На момент проверки 02.06.2026 в кабинете был показан тариф `Бесплатный с ограничениями` и счетчик `1000` запросов в сутки.
+6. В блоке `Ключи API` нажмите `Новый ключ`.
+7. В поле `Название ключа` введите понятное имя, например `iola-cli geocoder`.
+8. Нажмите `Добавить ключ`.
+9. После создания ключ появится в списке ключей API Геокодера.
+10. Скопируйте значение ключа. Это значение будет `YANDEX_GEOCODER_API_KEY`.
+
+Важно: новый ключ может начать работать не сразу. В документации Яндекса указано, что активация ключа может занять до 15 минут, на практике лучше спокойно подождать 15-30 минут. Если CLI пишет `Invalid api key` сразу после создания ключа, это не обязательно ошибка: подождите и повторите проверку командой `iola geo key doctor`.
+
+## Сохранение в CLI
+
+Запустите:
+
+```bash
+iola geo key set yandex
+```
+
+CLI попросит ввести:
+
+```text
+YANDEX_GEOCODER_API_KEY
+```
+
+Ключ сохраняется локально на устройстве пользователя в `~/.iola/secrets.json`.
+
+Проверить сохранение:
+
+```bash
+iola geo key status
+```
+
+Проверить рабочий запрос к API:
+
+```bash
+iola geo key doctor
+```
+
+Проверить геокодирование адреса:
+
+```bash
+iola geo geocode "Йошкар-Ола, улица Петрова, 15"
+```
+
+CLI также понимает переменные окружения:
+
+- `YANDEX_GEOCODER_API_KEY`;
+- `YANDEX_MAPS_API_KEY`.
+
+## Официальные ссылки
+
+- Кабинет разработчика: `https://developer.tech.yandex.ru/services/`
+- API Геокодера: `https://developer.tech.yandex.ru/services/2`
+- Документация Geocoder API: `https://yandex.com/maps-api/docs/geocoder-api/`
+- Формат запроса: `https://yandex.com/maps-api/docs/geocoder-api/request.html`

package/wiki//320/232/320/276/320/274/320/260/320/275/320/264/321/213.md

@@ -26,6 +26,21 @@ iola card "школа 29"
 iola data schools --format csv --output schools.csv
 ```
 
+Геокодер:
+
+```bash
+iola geo key set yandex
+iola geo key status
+iola geo key doctor
+iola geo geocode "Йошкар-Ола, улица Петрова, 15"
+iola geo nearby "Йошкар-Ола, улица Петрова, 15" --dataset all --limit 5
+iola geo distance --from "Петрова 15" --to "школа 7"
+iola geo map-link "школа 7"
+iola geo resolve "садик золотой петушок"
+iola geo route-context "школа 7"
+iola geo services "Йошкар-Ола, улица Петрова, 15"
+```
+
 Локальная БД:
 
 ```bash

package/wiki//320/234/320/260/321/201/321/202/320/265/321/200-/320/275/320/260/321/201/321/202/321/200/320/276/320/271/320/272/320/270.md

@@ -86,6 +86,14 @@ iola index folder ./docs
 
 Если runtime уже установлен, пункт показывается как `готово`.
 
+### 14. Yandex Geocoder API
+
+Сохраняет ключ Yandex Geocoder API локально у пользователя и проверяет его тестовым запросом.
+
+Нужен для будущих geo-skills: поиск объектов рядом с адресом, ссылки на карту, определение расстояний и уточнение населенного пункта.
+
+Инструкция по получению ключа: [Yandex Geocoder API key](Yandex-Geocoder-API-key).
+
 ## Повторный запуск
 
 Если компонент уже настроен, его можно не выбирать. Если нужно переустановить или обновить компонент, выберите его номер вручную.

package/wiki//320/241/320/272/320/270/320/273/320/273/321/213-/320/264/320/273/321/217-/320/266/320/270/321/202/320/265/320/273/320/265/320/271.md

@@ -0,0 +1,101 @@
+# Скиллы для жителей
+
+Эта страница фиксирует пользовательские skills, которые реализованы и развиваются в `iola-cli`.
+
+Цель этих skills - помогать жителю города в бытовых вопросах: где находится объект, что рядом, какой объект ближе, как открыть место на карте. Это не административный аудит данных.
+
+## Geo skills
+
+Для geo skills нужен ключ `Yandex Geocoder API`.
+
+Первый рабочий контур подключен к слоям `schools` и `kindergartens`.
+
+Команды:
+
+```bash
+iola geo nearby "Йошкар-Ола, улица Петрова, 15" --dataset all --limit 5
+iola geo distance --from "Петрова 15" --to "школа 7"
+iola geo map-link "школа 7"
+iola geo resolve "садик золотой петушок"
+iola geo route-context "школа 7"
+iola geo services "Йошкар-Ола, улица Петрова, 15"
+```
+
+### nearby
+
+Находит городские объекты рядом с адресом пользователя.
+
+Примеры:
+
+- `какие детские сады рядом с Петрова 15`;
+- `какие школы ближе к улице Машиностроителей`;
+- `что из городских учреждений рядом с домом`.
+
+Сейчас работает по слоям `schools` и `kindergartens`. Позже можно подключить МФЦ, поликлиники, остановки, спортобъекты и учреждения культуры.
+
+### route-context
+
+Объясняет, где находится объект, простым языком: адрес, ориентиры, что рядом, ссылка на карту.
+
+Это не полноценный навигатор и не замена маршрутизатору. Skill дает понятный контекст места для жителя.
+
+### address-to-services
+
+По адресу жителя подбирает релевантные городские объекты.
+
+Примеры:
+
+- ближайшие школы;
+- ближайшие детские сады;
+- будущие слои муниципальных услуг и учреждений.
+
+### map-link
+
+Добавляет в ответы ссылку на карту.
+
+Примеры:
+
+- открыть школу на Яндекс.Картах;
+- открыть детский сад на карте;
+- показать точку по координатам.
+
+### place-resolver
+
+Помогает понять криво написанные адреса, названия и ориентиры.
+
+Примеры:
+
+- `семеновка школа`;
+- `первомаиская 89`;
+- `садик золотой петушок`;
+- `рядом с вокзалом`.
+
+Главная задача - не подставлять похожий, но неправильный объект.
+
+### distance
+
+Считает расстояние от адреса пользователя до объекта или между объектами.
+
+Примеры:
+
+- `какой садик ближе к дому`;
+- `как далеко школа 7 от Первомайской 89`;
+- `что ближе: Пчелка или Улыбка`.
+
+### area-filter
+
+Фильтрует ответы по населенному пункту или району.
+
+Примеры:
+
+- Йошкар-Ола;
+- Семеновка;
+- другие населенные пункты городского округа, когда они появятся в слоях.
+
+Это важно, чтобы не путать объекты с одинаковыми номерами или похожими названиями.
+
+## Ограничения
+
+- Расстояние считается по прямой между координатами. Это не автомобильный и не пешеходный маршрут.
+- CLI не должен подставлять похожий объект из другого населенного пункта. Если слой не содержит нужный объект, ответ должен прямо говорить, что данных недостаточно.
+- При первом поиске рядом CLI геокодирует объекты слоя. Повторные запросы в той же сессии работают быстрее за счет памяти процесса.