bc-observatory 0.3.0 → 0.5.0

package/README.md

@@ -38,4 +38,12 @@ model, search is keyword-only and says so.
 `get_object` takes an id, a reference (`t36`, `36-be`), a name or a caption, and a `country`; `whats_new` lists nothing
 dated after today unless `include_future: true`.
 
+`cat`, `get_object` and `localization` return a page as it is when it fits 30,000 characters. A longer page
+(Codeunit 80 "Sales-Post" is 177,746) comes back as a compact view: the frontmatter with long lists cut, the title
+block, the section keys with their row counts and the first 5 rows of each section. `section` reads one section
+(`fields`, `events`, `procedures`, `calls`, ..., or `frontmatter`), `offset` and `limit` page through it by rows, and
+no answer exceeds 30,000 characters. A symbol's path from `search` (`objects/codeunit/80#event-OnAfterPostSalesDoc`)
+returns just that member. `BC_OBSERVATORY_MAX_CHARS` changes the limit (`0` returns every page whole, as before
+0.4.0).
+
 MIT. Content: see the repository's CONTENT-NOTICE.md (Microsoft content attributed; community content derived only).

package/dist/server.js

@@ -393,9 +393,10 @@ function normOf(r) {
   const symbol = r.kind !== "page";
   const main = /* @__PURE__ */ new Set([...indexTokens(r.name, symbol), ...indexTokens(r.title, symbol), ...r.caption ? indexTokens(r.caption) : []]);
   const own = r.type === "topic" ? new Set(tokenize(r.title)) : null;
-  const tags = (r.tags ?? []).flatMap((t) => indexTokens(t)).filter((t) => !own?.has(t));
+  const learn = r.type === "learn";
+  const tags = (r.tags ?? []).flatMap((t) => indexTokens(t, learn)).filter((t) => !own?.has(t));
   const eqs = r.type === "object" || symbol ? [tokenize(r.name), ...r.caption ? [tokenize(r.caption)] : []] : [tokenize(r.title)];
-  const n = { main: [...main], tags: [...new Set(tags)], text: symbol ? null : indexTokens(r.text ?? ""), eqs };
+  const n = { main: [...main], tags: learn ? tags : [...new Set(tags)], text: symbol ? null : indexTokens(r.text ?? ""), eqs };
   NORM.set(r, n);
   return n;
 }
@@ -783,6 +784,26 @@ function hints(index2, q, hits) {
   return out;
 }
 
+// ../search/src/learn.ts
+function learnRecords(doc) {
+  return doc.rows.map(([path, title, summary, date, h, system, ids]) => {
+    const hub = h >= 0 ? doc.hubs[h] : void 0;
+    const sys = system ?? hub?.[2] ?? null;
+    return {
+      path: /^https?:\/\//.test(path) ? path : `${doc.base}${path}`,
+      type: "learn",
+      title,
+      summary,
+      tier: "official",
+      ...sys ? { system: sys } : {},
+      ...date ? { date } : {},
+      ...ids?.length ? { tags: ids } : {},
+      ...hub?.[1] ? { path_label: hub[1] } : {},
+      ...hub?.[0] ? { hub: hub[0] } : {}
+    };
+  });
+}
+
 // src/embed.ts
 var MAX_TOKENS = 512;
 function parseModel(tokenizerJson, safetensors, config = {}) {
@@ -891,10 +912,363 @@ function dot(a, b, bOffset = 0) {
   return s;
 }
 
+// src/sections.ts
+var DEFAULT_BUDGET = 3e4;
+var MIN_BUDGET = 5e3;
+var PREVIEW_ROWS = 5;
+var ROW_CLIP = 200;
+var PROSE_CLIP = 800;
+var HEAD_LINE_MAX = 120;
+var FM_LIST_CHARS = 600;
+var FM_LIST_MIN = 3;
+var RESERVE = 300;
+var OBJECT_KEYS = {
+  "Properties": "properties",
+  "Fields": "fields",
+  "Fields on this page": "controls",
+  "Actions": "actions",
+  "Keys": "keys",
+  "Values": "values",
+  "Events published": "events",
+  "Trigger event subscribers": "trigger_subscribers",
+  "Event subscriptions": "subscriptions",
+  "Procedures": "procedures",
+  "Triggers": "triggers",
+  "Relations": "relations",
+  "Referenced by": "referenced_by",
+  "Pages and codeunits on this table": "pages",
+  "Extended by": "extended_by",
+  "Calls": "calls",
+  "Called by": "called_by",
+  "Implements": "implements",
+  "Implemented by": "implemented_by",
+  "Recent changes": "changes",
+  "Across versions": "versions",
+  "Countries that replace it": "countries",
+  "Documented on Microsoft Learn": "learn",
+  "Deprecations": "deprecations",
+  "Ask your agent": "ask"
+};
+var snake = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+var blank = (l) => l.trim() === "";
+var fmt = (n) => n.toLocaleString("en-US");
+var FENCE = /^\s*```/;
+var SEPARATOR = /^\|\s*:?-/;
+var CAP_NOTE = /^- and \d+ more/;
+function budgetOf(env) {
+  const n = env === void 0 || env.trim() === "" ? NaN : Number(env);
+  if (!Number.isFinite(n) || n < 0) return DEFAULT_BUDGET;
+  if (n === 0) return Infinity;
+  return Math.max(MIN_BUDGET, Math.floor(n));
+}
+function sectionKey(heading) {
+  return OBJECT_KEYS[heading] ?? snake(heading);
+}
+function splitSection(lines) {
+  const head = [], rows = [];
+  let pending = [];
+  let table2 = null, group = null;
+  let inTable = false, afterRow = false, fence = null;
+  const other = (line2, kind = "text") => {
+    if (rows.length) pending.push({ line: line2, kind });
+    else head.push(line2);
+  };
+  const addRow = (first) => {
+    if (rows.length) {
+      const prev = rows[rows.length - 1];
+      for (const p of pending) {
+        if (p.kind === "group" && p.line === group) continue;
+        if (p.kind === "table" && table2 && (p.line === table2[0] || p.line === table2[1])) continue;
+        if (!blank(p.line)) prev.lines.push(p.line);
+      }
+    }
+    pending = [];
+    rows.push({ lines: [first], table: table2, group });
+    afterRow = true;
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (fence) {
+      if (fence === "row") rows[rows.length - 1].lines.push(l);
+      else other(l);
+      if (FENCE.test(l)) fence = null;
+      continue;
+    }
+    if (FENCE.test(l)) {
+      if (afterRow && /^ {2,}/.test(l)) {
+        rows[rows.length - 1].lines.push(l);
+        fence = "row";
+      } else {
+        other(l);
+        fence = "text";
+        afterRow = false;
+        inTable = false;
+        table2 = null;
+      }
+      continue;
+    }
+    if (afterRow && /^ {2,}\S/.test(l)) {
+      rows[rows.length - 1].lines.push(l);
+      continue;
+    }
+    if (l.startsWith("|")) {
+      if (!inTable && i + 1 < lines.length && SEPARATOR.test(lines[i + 1])) {
+        table2 = [l, lines[i + 1]];
+        inTable = true;
+        afterRow = false;
+        other(l, "table");
+        other(lines[++i], "table");
+        continue;
+      }
+      if (inTable) {
+        addRow(l);
+        continue;
+      }
+    } else if (inTable) {
+      inTable = false;
+      table2 = null;
+    }
+    if (l.startsWith("- ") && !CAP_NOTE.test(l)) {
+      addRow(l);
+      continue;
+    }
+    afterRow = false;
+    if (l.startsWith("### ")) {
+      group = l;
+      other(l, "group");
+      continue;
+    }
+    other(l);
+  }
+  const tail = pending.map((p) => p.line);
+  return { head, rows, tail };
+}
+var memo = null;
+function parsePage(md) {
+  if (memo && memo.md === md) return memo.page;
+  const all = md.split("\n");
+  let i = 0, frontmatter = "";
+  if (all[0] === "---") {
+    const end = all.indexOf("---", 1);
+    if (end > 0) {
+      frontmatter = all.slice(1, end).join("\n");
+      i = end + 1;
+    }
+  }
+  const pre = [], chunks = [];
+  let fence = false;
+  for (; i < all.length; i++) {
+    const l = all[i];
+    if (!fence && l.startsWith("## ")) {
+      chunks.push({ heading: l.slice(3).trim(), lines: [] });
+      continue;
+    }
+    if (FENCE.test(l)) fence = !fence;
+    (chunks.length ? chunks[chunks.length - 1].lines : pre).push(l);
+  }
+  const seen = /* @__PURE__ */ new Map();
+  const sections = chunks.map(({ heading, lines }) => {
+    while (lines.length && blank(lines[lines.length - 1])) lines.pop();
+    const base = sectionKey(heading), n = (seen.get(base) ?? 0) + 1;
+    seen.set(base, n);
+    return { heading, key: n === 1 ? base : `${base}_${n}`, lines, ...splitSection(lines) };
+  });
+  const preamble = pre.join("\n").replace(/^\s*\n/, "").replace(/\s+$/, "");
+  const page = { frontmatter, preamble, sections };
+  memo = { md, page };
+  return page;
+}
+function frontmatterSection(p) {
+  const lines = p.frontmatter ? p.frontmatter.split("\n") : [];
+  return { heading: "", key: "frontmatter", lines, head: [], rows: lines.map((l) => ({ lines: [l], table: null, group: null })), tail: [] };
+}
+function findSection(p, want) {
+  const w = want.trim().toLowerCase(), ws = snake(want);
+  if (w === "frontmatter") return frontmatterSection(p);
+  return p.sections.find((s) => s.key === w) ?? p.sections.find((s) => s.heading.toLowerCase() === w) ?? p.sections.find((s) => ws !== "" && snake(s.heading) === ws) ?? null;
+}
+var keyList = (p, counts = false) => [...p.sections.map((s) => counts && s.rows.length ? `${s.key} (${s.rows.length})` : s.key), "frontmatter"].join(", ");
+var titleOf = (p, path) => p.preamble.split("\n").find((l) => l.startsWith("# "))?.slice(2).trim() || path;
+function clip(s, n, mark = "\u2026") {
+  if (s.length <= n) return s;
+  const end = /[\uD800-\uDBFF]/.test(s[n - 2]) ? n - 2 : n - 1;
+  return `${s.slice(0, end)}${mark}`;
+}
+var indentOf = (l) => l.length - l.trimStart().length;
+var BLOCK_SCALAR = /(?:^|:|-)\s*[|>][-+0-9]*\s*$/;
+var LIST_ITEM = /^( *)-(?: |$)/;
+function cutLists(lines) {
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const l = lines[i], m = LIST_ITEM.exec(l);
+    if (!m) {
+      out.push(l);
+      i++;
+      if (BLOCK_SCALAR.test(l)) {
+        const ind2 = indentOf(l);
+        while (i < lines.length && (blank(lines[i]) || indentOf(lines[i]) > ind2)) out.push(lines[i++]);
+      }
+      continue;
+    }
+    const ind = m[1].length, items = [];
+    while (i < lines.length && indentOf(lines[i]) === ind && LIST_ITEM.test(lines[i])) {
+      const item = [lines[i++]];
+      while (i < lines.length && (indentOf(lines[i]) > ind || blank(lines[i]) && i + 1 < lines.length && indentOf(lines[i + 1]) > ind)) item.push(lines[i++]);
+      items.push(BLOCK_SCALAR.test(item[0]) ? item : [item[0], ...cutLists(item.slice(1))]);
+    }
+    const size = (k2) => items.slice(0, k2).map((it) => it.join("\n")).join("\n").length;
+    if (size(items.length) <= FM_LIST_CHARS) {
+      out.push(...items.flat());
+      continue;
+    }
+    let k = 0;
+    while (k < items.length && size(k + 1) <= FM_LIST_CHARS) k++;
+    k = Math.max(k, FM_LIST_MIN);
+    out.push(...items.slice(0, k).flat());
+    if (k < items.length) out.push(`${" ".repeat(ind)}# \u2026 ${items.length - k} more; section: "frontmatter"`);
+  }
+  return out;
+}
+function compactFrontmatter(yaml) {
+  const lines = yaml.split("\n"), kept = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (/^generated:/.test(lines[i])) {
+      while (i + 1 < lines.length && (indentOf(lines[i + 1]) > 0 || blank(lines[i + 1]))) i++;
+      continue;
+    }
+    kept.push(lines[i]);
+  }
+  return cutLists(kept).join("\n");
+}
+function compactView(md, path, budget) {
+  const p = parsePage(md);
+  const out = [];
+  if (md.startsWith("---\n") && p.frontmatter !== "") out.push("---", compactFrontmatter(p.frontmatter), "---", "");
+  if (p.preamble) out.push(p.preamble, "");
+  out.push(`Compact view: this page is ${fmt(md.length)} characters and one answer holds ${fmt(budget)}, so each section shows its first ${PREVIEW_ROWS} rows. Sections: ${keyList(p, true)}. Read one with cat("${path}", section: "<key>"); offset and limit page through a long one.`, "");
+  for (const s of p.sections) {
+    out.push(`## ${s.heading}`);
+    const more = `\u2026 (section: "${s.key}")`;
+    if (!s.rows.length) {
+      const text2 = s.head.filter((l) => !blank(l)).join("\n");
+      if (text2) out.push(clip(text2, PROSE_CLIP, more));
+    } else {
+      const lead = s.head.find((l) => !blank(l) && !l.startsWith("|") && !l.startsWith("### "));
+      if (lead && lead.length <= HEAD_LINE_MAX) out.push(lead);
+      let group = null, table2 = null;
+      for (const r of s.rows.slice(0, PREVIEW_ROWS)) {
+        if (r.group && r.group !== group) {
+          out.push(r.group);
+          group = r.group;
+        }
+        const t = r.table ? r.table.join("\n") : null;
+        if (r.table && t !== table2) out.push(...r.table);
+        table2 = t;
+        out.push(clip(r.lines[0], ROW_CLIP));
+      }
+      if (s.rows.length > PREVIEW_ROWS) out.push(`\u2192 ${s.rows.length - PREVIEW_ROWS} more of ${s.rows.length}: cat("${path}", section: "${s.key}", offset: ${PREVIEW_ROWS})`);
+      else {
+        const text2 = s.tail.filter((l) => !blank(l)).join("\n");
+        if (text2) out.push(clip(text2, PROSE_CLIP, more));
+      }
+    }
+    out.push("");
+  }
+  return `${out.join("\n").replace(/\n{3,}/g, "\n\n").replace(/\n+$/, "")}
+`;
+}
+var dropLeadingBlank = (lines) => {
+  let i = 0;
+  while (i < lines.length && blank(lines[i])) i++;
+  return lines.slice(i);
+};
+function sectionView(md, path, want, offset, limit, budget, site) {
+  const p = parsePage(md);
+  const nl = (lines) => `${lines.join("\n")}
+`;
+  const s = findSection(p, want);
+  if (!s) return `No section "${want}" on ${path}. Sections: ${keyList(p)}.`;
+  const fm = s.key === "frontmatter" && s.heading === "";
+  const first = `${titleOf(p, path)}, section "${s.key}": ${site}${path}/`;
+  const heading = fm ? [] : [`## ${s.heading}`];
+  const n = s.rows.length, off = Math.max(0, Math.floor(offset ?? 0));
+  const verbatim = nl(fm ? [first, "", "---", ...s.lines, "---"] : [first, "", ...heading, ...s.lines]);
+  if (!n || off === 0 && limit === void 0 && verbatim.length <= budget) return verbatim;
+  const tail = dropLeadingBlank(s.tail);
+  if (off >= n) return nl([first, "", ...heading, "", ...tail.length ? tail : [`No rows after ${n} in section "${s.key}" of ${path}.`]]);
+  const out = [first, "", ...heading, ...fm ? [] : [""]];
+  let group = null, table2 = null;
+  if (off === 0) {
+    out.push(...dropLeadingBlank(s.head));
+    group = s.rows[0].group;
+    table2 = s.rows[0].table ? s.rows[0].table.join("\n") : null;
+  }
+  let len = out.join("\n").length, b = off;
+  const end = limit === void 0 ? n : Math.min(n, off + Math.max(1, Math.floor(limit)));
+  for (let r = off; r < end; r++) {
+    const row = s.rows[r], add = [];
+    let g = group, t = table2;
+    if (row.group && row.group !== g) {
+      add.push(...out.length && !blank(out[out.length - 1]) ? [""] : [], row.group, "");
+      g = row.group;
+      t = null;
+    }
+    const rt = row.table ? row.table.join("\n") : null;
+    if (row.table && rt !== t) add.push(...row.table);
+    t = rt;
+    add.push(...row.lines);
+    const size = add.join("\n").length + 1;
+    if (r > off && len + size > budget - RESERVE) break;
+    out.push(...add);
+    len += size;
+    group = g;
+    table2 = t;
+    b = r + 1;
+  }
+  const rows = `Rows ${off + 1}-${b} of ${n}.`;
+  if (b < n) return nl([...out, "", `${rows} Next: cat("${path}", section: "${s.key}", offset: ${b})`]);
+  if (!tail.length) return nl([...out, "", rows]);
+  const withTail = nl([...out, "", ...tail, "", rows]);
+  if (limit === void 0 && withTail.length <= budget) return withTail;
+  return nl([...out, "", `${rows} The section's closing text: cat("${path}", section: "${s.key}", offset: ${n})`]);
+}
+var ANCHOR_SECTION = { field: ["fields", "field"], value: ["values", "value"], event: ["events", "event"], proc: ["procedures", "procedure"] };
+function anchorView(md, path, anchor, site) {
+  const a = anchor.replace(/^#/, ""), m = /^(field|value|event|proc)-(.+)$/.exec(a);
+  if (!m) return null;
+  const [key, label] = ANCHOR_SECTION[m[1]];
+  const p = parsePage(md);
+  const s = p.sections.find((x) => x.key === key);
+  if (!s) return null;
+  const match = m[1] === "field" || m[1] === "value" ? (l) => l.startsWith(`| ${m[2]} |`) : (l) => l.startsWith(`- \`${m[2]}(`);
+  const rows = s.rows.filter((r) => match(r.lines[0]));
+  if (!rows.length) return null;
+  return `${[`${titleOf(p, path)}, ${label} ${m[2]}: ${site}${path}/#${a}`, "", `## ${s.heading}`, ...rows[0].table ?? [], ...rows.flatMap((r) => r.lines)].join("\n")}
+`;
+}
+function pageView(md, path, a, budget, site) {
+  const hash = path.indexOf("#");
+  if (hash >= 0) {
+    const clean = path.slice(0, hash), anchor = path.slice(hash);
+    return anchorView(md, clean, anchor, site) ?? `(No row for ${anchor} on this page.)
+
+${pageView(md, clean, {}, budget, site)}`;
+  }
+  if (a.section !== void 0 && a.section.trim() !== "") return sectionView(md, path, a.section, a.offset, a.limit, budget, site);
+  if (a.offset !== void 0 || a.limit !== void 0) {
+    return `offset and limit read one section: cat("${path}", section: "<key>", offset: ${a.offset ?? 0}). Sections: ${keyList(parsePage(md))}.`;
+  }
+  if (md.length <= budget) return md;
+  return compactView(md, path, budget);
+}
+
 // src/server.ts
-var VERSION = "0.3.0";
+var VERSION = "0.5.0";
 var SITE = (process.env.BC_OBSERVATORY_SITE ?? "https://waldo1001.github.io/waldo.BCObservatory/").replace(/\/?$/, "/");
 var LOCAL = process.env.BC_OBSERVATORY_LOCAL ? resolve(process.env.BC_OBSERVATORY_LOCAL) : null;
+var BUDGET = budgetOf(process.env.BC_OBSERVATORY_MAX_CHARS);
+var B = (Number.isFinite(BUDGET) ? BUDGET : DEFAULT_BUDGET).toLocaleString("en-US");
 var REPO = "https://github.com/waldo1001/waldo.BCObservatory";
 var DAY = 864e5;
 var cacheDir = join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "bc-observatory", createHash("sha256").update(SITE).digest("hex").slice(0, 12));
@@ -934,6 +1308,12 @@ async function loadIndex() {
   for (const s of manifest.shards) all.push(...JSON.parse(await shard(s.file, s.sha256)));
   pages = all;
   const idx = prepare(all.map(pageToRecord));
+  if (manifest.learn) {
+    try {
+      prepare(learnRecords(JSON.parse(await shard(manifest.learn.file, manifest.learn.sha256))).map(pageToRecord), idx);
+    } catch {
+    }
+  }
   let sm = null;
   try {
     sm = JSON.parse(await dataFile("index/symbols-manifest.json"));
@@ -961,7 +1341,10 @@ var line = (r, tag = "") => `- ${r.title}${r.caption ? ` (captioned "${r.caption
 var text = (t) => ({ content: [{ type: "text", text: t }] });
 var symbolHit = (r, tag = "") => `- ${r.name} (${symbolLine(r).replace(/ · /g, ", ")}) path=${r.id}${tag}${r.text ? `
   ${r.text}` : ""}`;
-var hitLine = (r, tag = "") => r.kind === "page" && r.page ? line(r.page, tag) : symbolHit(r, tag);
+var learnLine = (r, tag = "") => `- ${r.title} [learn, official${r.date ? `, ${r.date}` : ""}] url=${r.path}${tag}${r.path_label ? `
+  in: ${r.path_label}${r.hub ? ` (hub: ${r.hub})` : ""}` : ""}
+  ${r.summary}`;
+var hitLine = (r, tag = "") => r.kind === "page" && r.page ? r.type === "learn" ? learnLine(r.page, tag) : line(r.page, tag) : symbolHit(r, tag);
 var MODEL = {
   repo: "minishlab/potion-base-8M",
   revision: "bf8b056651a2c21b8d2565580b8569da283cab23",
@@ -1061,7 +1444,8 @@ async function toolSearch(a) {
 ${hs.map((h) => `Hint: ${h.text}${h.query ? ` (search "${h.query}")` : h.path ? ` (cat("${h.path}"))` : ""}`).join("\n")}` : "";
   if (!shown.length) return `No pages match "${a.query}". Try fewer words, or ls("") to browse sections.${note}${hintText}`;
   const how = semantic.length && keyword.length && mode === "hybrid" ? "keyword + meaning" : mode === "semantic" && semantic.length ? "meaning" : "keyword";
-  return `${shown.length} results, ${how}${note}${how === "keyword + meaning" || mode === "hybrid" ? ` (exact band: ${exactBand})` : ""} (read one with cat(path)):
+  const learnNote = shown.some((r) => r.type === "learn") ? "; a Learn article's url opens on learn.microsoft.com, cat(hub) reads its hub" : "";
+  return `${shown.length} results, ${how}${note}${how === "keyword + meaning" || mode === "hybrid" ? ` (exact band: ${exactBand})` : ""} (read one with cat(path)${learnNote}):
 ${shown.map((r) => hitLine(r, tag(r.id))).join("\n")}${hintText}`;
 }
 async function toolLs(a) {
@@ -1082,7 +1466,9 @@ async function toolLs(a) {
 ... and ${files.length - MAX} more pages; use search() to narrow down` : ""}`;
 }
 async function toolCat(a) {
-  return pageMarkdown(a.path.replace(/#.*$/, ""));
+  const [base, anchor] = a.path.split(/(?=#)/);
+  const clean = `${base.replace(/^\/+|\/+$/g, "").replace(/\.md$/, "")}${anchor ?? ""}`;
+  return pageView(await pageMarkdown(clean.replace(/#.*$/, "")), clean, a, BUDGET, SITE);
 }
 async function toolGetObject(a) {
   await loadIndex();
@@ -1123,7 +1509,7 @@ async function toolGetObject(a) {
       const also = !country && twins.length ? `
 
 (Also in ${twins.join(", ")}: get_object("${type}", "${pick[0].objectId ?? pick[0].name}", country).)` : "";
-      return `${note}${await pageMarkdown(pick[0].id)}${also}`;
+      return `${note}${pageView(await pageMarkdown(pick[0].id), pick[0].id, a, BUDGET, SITE)}${a.section ? "" : also}`;
     }
     if (pick.length > 1) return `${pick.length} ${type} objects match "${a.idOrName}"; read one with cat(path):
 ${pick.map((r) => `- ${r.title} path=${r.id}`).join("\n")}`;
@@ -1144,7 +1530,8 @@ async function toolDiffObject(a) {
 ${JSON.stringify(o, null, 1)}`;
 }
 async function toolLocalization(a) {
-  return pageMarkdown(`localizations/${a.country.toLowerCase()}`);
+  const p = `localizations/${a.country.toLowerCase()}`;
+  return pageView(await pageMarkdown(p), p, a, BUDGET, SITE);
 }
 async function toolWhatsNew(a, today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)) {
   await loadIndex();
@@ -1176,15 +1563,16 @@ ${a.message}
 (sent from the bc-observatory MCP server ${VERSION})`;
   return `Open this link to file the issue (no sign-in through the agent): ${REPO}/issues/new?title=${encodeURIComponent(title)}&body=${encodeURIComponent(body)}&labels=feedback`;
 }
+var VIEW = { section: z.string().optional(), offset: z.number().int().min(0).max(1e5).optional(), limit: z.number().int().min(1).max(5e3).optional() };
 function createServer() {
   const server = new McpServer({ name: "bc-observatory", version: VERSION }, {
-    instructions: "BC Observatory: an agent-first knowledge base of Microsoft Dynamics 365 Business Central (Learn hubs, AL objects from the code for BC28-30, localizations, roadmap features, videos, community posts, code changes: merged pull requests of Microsoft's Business Central repositories, BCApps joined to the AL objects they changed, under changes/, and AL Language extension releases (the marketplace changelog, under releases/)). Every page carries a trust tier (official = Microsoft, community = everyone else) and a review state: say which tier a claim comes from. Never invent AL object ids or version numbers: look them up with get_object. Start with search(), read pages with cat(path), browse with ls(path)."
+    instructions: "BC Observatory: an agent-first knowledge base of Microsoft Dynamics 365 Business Central (Learn hubs, AL objects from the code for BC28-30, localizations, roadmap features, videos, community posts, code changes: merged pull requests of Microsoft's Business Central repositories, BCApps joined to the AL objects they changed, under changes/, and AL Language extension releases (the marketplace changelog, under releases/)). Every page carries a trust tier (official = Microsoft, community = everyone else) and a review state: say which tier a claim comes from. Never invent AL object ids or version numbers: look them up with get_object. Start with search(), read pages with cat(path), browse with ls(path). search() also finds Microsoft Learn articles by title, summary and the identifiers they document (type learn): those are not pages here, open their url on learn.microsoft.com."
   });
   server.registerTool(
     "search",
     {
       title: "Search the knowledge base",
-      description: "Search every page (title, AL object name and caption, summary, tags) with the site's own scorer: per query word title or caption 3, tags 2, summary 1, through the exact word, a prefix, the plural, a synonym (client = customer, G/L = general ledger) or one typo; a name equal to the query +10; an object reference ('t36', 'cu 80', 'table 11300 BE') or a bare id ('36') goes straight to the object; base app before first-party app before country layer, then an object's importance (what references, calls and documents it); hubs by size and review state. Hybrid by default: the exact band (references and exact names) stays on top and the rest is fused with a meaning ranking, so a paraphrase still finds the page; each hit says [keyword], [meaning] or [both]. mode 'keyword' for the scorer alone, 'semantic' for meaning only. Fields, published events, global procedures and enum values (W1 and apps, the major the object pages are built from) are searchable too ('OnAfterPostSalesDoc', 'Posting Date', or a prefix: 'event: OnAfterPost', 'field: Posting Date', 'proc: CopyToTempLines'); a symbol hit names its object and its path ends in #event-<Name>, #field-<id>, #proc-<Name> or #value-<ordinal>. Filters: type (topic, app, feature, object, localization, video, post, change, source, digest, release), tier (official, community), system (finance, sales, ... or an alias such as 'g/l'), country ('BE'), app ('Subscription Billing'), object_type ('table'), kind (page, field, event, proc, value).",
+      description: "Search every page, and the fields, published events, global procedures and enum values of AL objects, ranked like the site's search. Takes names ('Sales Header'), references ('t36', 'cu 80', 'table 11300 BE'), bare ids ('36') and symbol prefixes ('event: OnAfterPost', 'field: Posting Date', 'proc: CopyToTempLines'); a symbol hit's path ends in its anchor (#event-<Name>, #field-<id>, #proc-<Name>, #value-<ordinal>); cat(path) reads that member alone. Learn articles too: type learn, a url, not a path. Hybrid by default: exact matches stay on top and the rest is fused with a meaning ranking; each hit says [keyword], [meaning] or [both]; mode 'keyword' or 'semantic' for one list. Filters: type (topic, learn, app, feature, object, localization, video, post, change, source, digest, release), tier (official, community), system (finance, sales, ... or an alias such as 'g/l'), country ('BE'), app ('Subscription Billing'), object_type ('table'), kind (page, field, event, proc, value).",
       inputSchema: { query: z.string(), type: z.string().optional(), tier: z.string().optional(), system: z.string().optional(), country: z.string().optional(), app: z.string().optional(), object_type: z.string().optional(), kind: z.enum(["page", "field", "event", "proc", "value"]).optional(), limit: z.number().int().min(1).max(50).optional(), mode: z.enum(["hybrid", "keyword", "semantic"]).optional() }
     },
     async (a) => text(await toolSearch(a))
@@ -1196,13 +1584,13 @@ function createServer() {
   );
   server.registerTool(
     "cat",
-    { title: "Read a page", description: "The full markdown of a page (frontmatter with evidence and links, then the body), by its path from search or ls.", inputSchema: { path: z.string() } },
+    { title: "Read a page", description: `A page's markdown by its path from search or ls: frontmatter with evidence and links, then the body. A page over ${B} characters comes back compact with its section keys; section (or 'frontmatter'), offset and limit read one part. A symbol path ('objects/codeunit/80#event-OnAfterPostSalesDoc') returns that member's row.`, inputSchema: { path: z.string(), ...VIEW } },
     async (a) => text(await toolCat(a))
   );
   server.registerTool("get_object", {
     title: "Look up an AL object",
-    description: "An AL object of W1, a Microsoft first-party app or a country layer by type and id, reference or name, e.g. ('table', '18'), ('table', 't36'), ('table', '36-be'), ('codeunit', 'Sales-Post'), ('page', 'Customers') by its caption, ('table', 'VAT VIES Correction') or with country 'BE': fields, keys, events, public procedures, obsolete state, versions, countries that replace it, Learn pages. A W1 object wins over its country twins unless a country is given; two candidates of the same standing are listed with their paths.",
-    inputSchema: { type: z.string(), idOrName: z.string(), country: z.string().length(2).optional() }
+    description: `An AL object of W1, a Microsoft first-party app or a country layer by type and id, reference, name or caption: ('table', '18'), ('table', 't36'), ('table', '36-be'), ('codeunit', 'Sales-Post'), ('page', 'Customers'), or with country 'BE'. Returns its page: fields, keys, events, procedures, calls, obsolete state, versions, countries, Learn pages; a W1 object wins over its country twins unless a country is given, and two candidates are listed with their paths. A page over ${B} characters comes back compact (frontmatter, the first 5 rows of each section, the section keys): pass section ('fields', 'events', 'procedures', 'calls', ...) with offset and limit to read one. To check that a field, event or procedure exists, search('event: <Name>') answers without the page.`,
+    inputSchema: { type: z.string(), idOrName: z.string(), country: z.string().length(2).optional(), ...VIEW }
   }, async (a) => text(await toolGetObject(a)));
   server.registerTool("diff_object", {
     title: "What changed in an object",
@@ -1211,12 +1599,12 @@ function createServer() {
   }, async (a) => text(await toolDiffObject(a)));
   server.registerTool(
     "localization",
-    { title: "A country localization", description: "What a country layer (BE, NL, DE, ...) adds to or changes in W1, with its Learn local functionality hub.", inputSchema: { country: z.string().length(2) } },
+    { title: "A country localization", description: `What a country layer (BE, NL, DE, ...) adds to or changes in W1, with its Learn local functionality hub. Over ${B} characters it comes back compact; section, offset and limit read one section, as in cat.`, inputSchema: { country: z.string().length(2), ...VIEW } },
     async (a) => text(await toolLocalization(a))
   );
   server.registerTool("whats_new", {
     title: "What is new",
-    description: "Videos, posts, roadmap features, AL extension releases (type 'release') and code changes (merged pull requests of BCApps, AL-Go and BCQuality, type 'change') dated on or after a date (YYYY-MM-DD) and up to today, newest first; a roadmap feature's date is its GA month, so features scheduled after today are counted at the end and listed with include_future: true.",
+    description: "Videos, posts, roadmap features, AL extension releases (type 'release') and merged pull requests of BCApps, AL-Go and BCQuality (type 'change') dated on or after a date (YYYY-MM-DD) up to today, newest first. A roadmap feature's date is its GA month: features after today are counted at the end and listed with include_future: true.",
     inputSchema: { since: z.string(), type: z.string().optional(), limit: z.number().int().min(1).max(100).optional(), include_future: z.boolean().optional() }
   }, async (a) => text(await toolWhatsNew(a)));
   server.registerTool("blog_footprint", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bc-observatory",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "MCP server for BC Observatory: an agent-first, cross-referenced knowledge base of Microsoft Dynamics 365 Business Central (Learn, code, roadmap, videos, community blogs).",
   "type": "module",
   "bin": {