@absolutejs/rag 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -6,6 +6,26 @@ This file is generated by `absolute-changelog` from the entries in
 `changelog/`. Edit an entry, not this file — and add new ones under
 `changelog/unreleased/`.
 
+## 0.14.0 — 2026-09-18
+
+### Added
+
+- **Return copy-ready source citations before website evidence and repeat links beside each retrieved page; exclude failed reads and unread links from the source list.** (`readRAGWebsite`)
+
+### Changed
+
+- **Require nearby source links for factual answers and distinguish supported customer examples from unsupported exclusions, ownership relationships and rebrand history.** (`readRAGWebsite`)
+
+## 0.13.0 — 2026-09-18
+
+### Added
+
+- **Expose stop reasons and actual incomplete page reads separately from unvisited links; guide targeted continuation and concise nontechnical answers.** (`readRAGWebsite`)
+
+### Changed
+
+- **Balance repeated customer, service and company reads across an eight-page default budget (maximum twelve) with 48000 characters, preventing case-study archives from starving service details.** (`readRAGWebsite`)
+
 ## 0.12.0 — 2026-09-18
 
 ### Added

package/README.md

@@ -165,15 +165,29 @@ must enforce equivalent network controls.
 
 ### Research related website pages with attributable evidence
 
-`readRAGWebsite` from `@absolutejs/rag/web` reads a supplied URL and up to three
-relevant same-origin customer, services and company pages by default. Pass the
+`readRAGWebsite` from `@absolutejs/rag/web` reads up to eight pages by default, balancing
+same-origin customer, service and company pages so service details are not
+starved by large case-study archives. The configurable ceiling is twelve pages;
+the overall deadline remains 75 seconds and default text budget is 48,000 characters. Pass the
 optional Playwright renderer as for `readRAGWebpage`. `maxPages: 1` retains a
 single-page read; `mode: "browser"` retries content missed by static extraction.
 Results attribute text to exact page URLs and retain per-page redirects,
 retrieval attempts, semantic image labels, link destinations, media URLs and
 available caption text. Coverage includes unvisited relevant links and deadline
-limits. HTTP redirects carry their actual status; client navigation is labeled
+limits. `incompleteReads` identifies failed, partial or truncated page reads;
+unvisited links and successful browser fallback are not failed reads.
+`stopReason` distinguishes a page limit, deadline and exhausted relevant links.
+A per-call limit is not a reason to stop research when a material question remains:
+use targeted follow-up reads. Present business answers first and keep technical
+diagnostics for explicit debugging requests. HTTP redirects carry their actual status; client navigation is labeled
 separately. Empty image labels are not proof of an absent client list, and media
 URLs are not proof that a video was watched. Consumers must cite source URLs,
 distinguish extracted evidence from inference, and finish the requested research
 without treating a successful page fetch as complete company coverage.
+
+Website results also lead with a `sources` array containing each readable page's
+`title`, `url` and ready-to-use Markdown `citation`, repeated next to that page's
+evidence text. Failed pages and unvisited links are not citable source entries.
+`citationRequirements` asks consumers to place links beside supported claims,
+avoid unsupported exclusions or ownership relationships, and keep verified brand
+changes brief. Host applications still control their generated final answers.

package/changelog.json

@@ -2,6 +2,46 @@
 	"contract": 1,
 	"name": "@absolutejs/rag",
 	"releases": [
+		{
+			"changes": [
+				{
+					"kind": "changed",
+					"summary": "Require nearby source links for factual answers and distinguish supported customer examples from unsupported exclusions, ownership relationships and rebrand history.",
+					"symbols": [
+						"readRAGWebsite"
+					]
+				},
+				{
+					"kind": "added",
+					"summary": "Return copy-ready source citations before website evidence and repeat links beside each retrieved page; exclude failed reads and unread links from the source list.",
+					"symbols": [
+						"readRAGWebsite"
+					]
+				}
+			],
+			"date": "2026-09-18",
+			"version": "0.14.0"
+		},
+		{
+			"changes": [
+				{
+					"kind": "changed",
+					"summary": "Balance repeated customer, service and company reads across an eight-page default budget (maximum twelve) with 48000 characters, preventing case-study archives from starving service details.",
+					"symbols": [
+						"readRAGWebsite"
+					]
+				},
+				{
+					"kind": "added",
+					"summary": "Expose stop reasons and actual incomplete page reads separately from unvisited links; guide targeted continuation and concise nontechnical answers.",
+					"symbols": [
+						"readRAGWebsite"
+					]
+				}
+			],
+			"date": "2026-09-18",
+			"version": "0.13.0"
+		},
 		{
 			"changes": [
 				{

package/dist/src/web/website.d.ts

@@ -34,6 +34,16 @@ export declare const readRAGWebsite: (options: ReadWebpageOptions & {
         remainingRelevantLinks: string[];
         deadlineReached: boolean;
         exhaustive: boolean;
+        stopReason: string;
+        incompleteReads: {
+            url: string;
+            status: "error" | "partial" | "ok";
+            truncated: boolean;
+            error: {
+                code: string;
+                message: string;
+            } | undefined;
+        }[];
     };
     citationGuidance: string;
     url: string;
@@ -49,4 +59,10 @@ export declare const readRAGWebsite: (options: ReadWebpageOptions & {
     redirects: import("./transport").WebRedirect[];
     evidence: import("./evidence").WebEvidence;
     limitations: string[];
+    sources: {
+        title: string;
+        url: string;
+        citation: string;
+    }[];
+    citationRequirements: string;
 }>;

package/dist/web/index.js

@@ -17718,14 +17718,14 @@ var pagePriority = (url, label) => {
 };
 var readRAGWebsite = async (options) => {
   const signal = options.signal ?? AbortSignal.timeout(75000);
-  const maxPages = Math.max(1, Math.min(options.maxPages ?? 4, 5));
-  const maxChars = Math.max(1000, Math.min(options.maxChars ?? 24000, 1e5));
+  const maxPages = Math.max(1, Math.min(options.maxPages ?? 8, 12));
+  const maxChars = Math.max(1000, Math.min(options.maxChars ?? 48000, 1e5));
   const pages = [];
   const queue = [
     { url: options.url, label: "Requested page" }
   ];
   const visited = new Set;
-  const coveredTopics = new Set;
+  const topicVisits = new Map;
   let origin;
   while (queue.length && pages.length < maxPages && !signal.aborted) {
     const next = queue.shift();
@@ -17740,7 +17740,8 @@ var readRAGWebsite = async (options) => {
     if (visited.has(key2.href))
       continue;
     visited.add(key2.href);
-    coveredTopics.add(pagePriority(next.url, next.label));
+    const topic = pagePriority(next.url, next.label);
+    topicVisits.set(topic, (topicVisits.get(topic) ?? 0) + 1);
     const page = await readRAGWebpage({
       ...options,
       url: next.url,
@@ -17754,7 +17755,11 @@ var readRAGWebsite = async (options) => {
       continue;
     const links = page.evidence.links.filter((link) => new URL(link.url).origin === origin && pagePriority(link.url, link.label) > 0 && !visited.has(link.url.split("#")[0]));
     queue.push(...links);
-    queue.sort((a, b) => pagePriority(b.url, b.label) + (coveredTopics.has(pagePriority(b.url, b.label)) ? 0 : 10) - (pagePriority(a.url, a.label) + (coveredTopics.has(pagePriority(a.url, a.label)) ? 0 : 10)));
+    queue.sort((a, b) => {
+      const aTopic = pagePriority(a.url, a.label);
+      const bTopic = pagePriority(b.url, b.label);
+      return (topicVisits.get(aTopic) ?? 0) - (topicVisits.get(bTopic) ?? 0) || bTopic - aTopic;
+    });
   }
   const first = pages[0] ?? await readRAGWebpage({ ...options, signal });
   const captionEvidence = [];
@@ -17781,7 +17786,14 @@ var readRAGWebsite = async (options) => {
       });
     }
   }
+  const sources = pages.filter((page) => page.status !== "error" && page.text).map((page) => {
+    const title = (page.title || new URL(page.finalUrl).hostname).replace(/\s+/gu, " ").trim();
+    const label = title.replace(/[\\[\]]/gu, "\\$&");
+    const href = page.finalUrl.replace(/[<>]/gu, encodeURIComponent);
+    return { title, url: page.finalUrl, citation: `[${label}](<${href}>)` };
+  });
   const evidenceText = pages.filter((page) => page.status !== "error").map((page) => `SOURCE: ${page.finalUrl}
+CITATION: ${sources.find((source) => source.url === page.finalUrl)?.citation ?? page.finalUrl}
 TITLE: ${page.title ?? "Untitled"}
 ${page.text}`).join(`
 
@@ -17790,6 +17802,8 @@ ${page.text}`).join(`
   const incomplete = pages.some((page) => page.status !== "ok") || signal.aborted;
   const unvisited = queue.filter((link) => !visited.has(link.url.split("#")[0]));
   return {
+    sources,
+    citationRequirements: "The final answer must contain clickable Markdown source links, not just source names or bare domain mentions. Reuse sources[].citation beside the factual paragraph, list or table row it supports. Cite the actual supporting page, not the homepage for everything. Every factual section needs its supporting links. Do not invent sources or use unread links as evidence. Before responding, check that company facts, service descriptions, customer examples and numerical claims have supporting links; retrieve or omit unsupported claims. A list of large customers does not prove smaller customers are excluded. Preserve the brands actually named in the evidence; do not append parent companies, ownership relationships, current-account status, market rankings or rebrand history from memory. Label reasoned inferences as such. A verified brand change needs at most one short, cited sentence unless the user asks for its history.",
     ...first,
     status: readable.length ? incomplete ? "partial" : "ok" : "error",
     text: evidenceText.slice(0, maxChars),
@@ -17803,9 +17817,16 @@ ${page.text}`).join(`
         ...new Set(unvisited.map((link) => link.url))
       ].slice(0, 20),
       deadlineReached: signal.aborted,
-      exhaustive: false
+      exhaustive: false,
+      stopReason: signal.aborted ? "deadline" : unvisited.length ? "page_limit" : "links_exhausted",
+      incompleteReads: pages.filter((page) => page.status !== "ok" || page.truncated).map((page) => ({
+        url: page.finalUrl,
+        status: page.status,
+        truncated: page.truncated,
+        error: page.error
+      }))
     },
-    citationGuidance: "Cite the exact source page URL for each factual claim. Distinguish page text, image labels, caption text and inference. A successful fetch is not proof that every requested topic was answered. Follow remaining relevant links if the question is still unanswered; do not ask permission merely to finish already-requested research. Describe an empty HTTP extraction followed by browser success as successful fallback, not silent failure. Only identify HTTP redirect status codes actually present in redirects. Media URLs alone are not watched video evidence."
+    citationGuidance: "Answer the user's question first, with exact source page URLs. Distinguish retrieved facts from inference. A page limit bounds this call, not the research task: if a material question remains unanswered, read the relevant remaining links in another call, using maxPages 1 for targeted detail pages. Do not stop with a list of next steps when those reads are needed to finish the request. Conversely, unvisited links do not by themselves mean the answer is incomplete. Report only gaps that materially limit the answer, unless a retrieval audit was explicitly requested. Successful browser fallback is a completed read, not an incomplete read. Normally summarize a redirected destination in one brief sentence; omit HTTP codes, hop chains, character counts and rendering mechanics unless explicitly requested for debugging. A redirect alone does not prove a rebrand; verify that claim from a source. Image labels do not establish customer relationships and media URLs are not watched video evidence."
   };
 };
 
@@ -17981,5 +18002,5 @@ export {
   validatePublicWebUrl
 };
 
-//# debugId=4E4CFF24F5CCBA3E64756E2164756E21
+//# debugId=C770BC61DAD3A78A64756E2164756E21
 //# sourceMappingURL=index.js.map