mcp-scraper 0.49.0 → 0.51.0

package/dist/{chunk-64WBUDPC.js → chunk-O63VVCCE.js}

@@ -18,10 +18,10 @@ import {
   browserServiceProfileSaveChanges,
   recordVendorUsage,
   vendorCostUsd
-} from "./chunk-PODASLGT.js";
+} from "./chunk-QXAY44SA.js";
 import {
   PACKAGE_VERSION
-} from "./chunk-XLEDHV3J.js";
+} from "./chunk-73MUQSWC.js";
 import {
   MC_PER_CREDIT
 } from "./chunk-SOEYDWJU.js";
@@ -33,6 +33,7 @@ import {
 
 // src/harvest-timeout.ts
 var VERCEL_FUNCTION_MAX_MS = 3e5;
+var DEFAULT_TOOL_CLIENT_TIMEOUT_MS = 3e5;
 var CLIENT_OVER_SERVER_MARGIN_MS = 15e3;
 function harvestTimeoutBudget(maxQuestions, serpOnly = false) {
   const requested = Number.isFinite(maxQuestions) && maxQuestions > 0 ? Math.trunc(maxQuestions) : 30;
@@ -451,7 +452,10 @@ seam is noted so you can chain them.
   handles Reddit's bot wall itself (no login needed). Find threads first with \`search_serp\` or \`reddit_trending\`.
 - DISCOVER what a niche is talking about (topic, no known thread) -> **reddit_trending** (takes a topic, optional
   subreddit; returns the last 30 days' top threads ranked by engagement plus the questions people asked \u2014
-  feed winning \`rankedThreads[].url\` values into \`reddit_thread\` for the full comment tree).
+  feed winning \`rankedThreads[].url\` values into \`reddit_thread\` for the full comment tree). It uses bounded
+  direct Reddit discovery when the primary SERP is empty. Before interpreting an empty result, inspect
+  \`resultQuality\`, \`discoverySource\`, \`degradationReasons\`, \`retryRecommended\`, and \`billingRefunded\`;
+  a degraded empty result is not evidence that the topic has no Reddit discussion.
 
 ## Other sites & logins (browser agent)
 For an arbitrary site or a logged-in dashboard with no dedicated tool, use the browser_* agent. **First
@@ -501,6 +505,12 @@ Multi-step orchestrations \u2014 prefer these over hand-chaining primitives when
   versioning reusable website templates; use the saved-template tools above for those jobs.
 - The creation tool is a renderer, not a research or writing model. Preserve source truth in each
   \`sourceLabel\`; do not hand it raw source material and expect it to invent the editorial architecture.
+- One edition may contain up to 100 articles. Images may appear as structured article/card heroes or as
+  Markdown body images. Use \`site.ogImage\` for the collection social preview and \`article.ogImage\` for an
+  article override; otherwise the article hero, then collection image, is reused. Every image requires useful
+  alt text. Preserve caption, credit, source URL, and rights context when known; a reachable URL does not prove
+  reuse rights. Static artifacts include collection OG tags and update article tags in-browser, while crawler-
+  perfect per-article unfurls require the publishing host to serve article-specific metadata.
 - ${savesReportsLocally ? "This local stdio server writes one self-contained HTML file and returns its localPath so the user can open it." : "This hosted server creates a private seven-day HTML artifact and returns a signed download URL; use renew_editorial_reading_room_download after the URL expires."}
 
 ## Local Sourcebook listings
@@ -592,6 +602,17 @@ deliberate edits and migrations. Use
 they'll filter/sort by exact value. **memory-search** is meaning-based over full content (embeds, slower);
 **memory-list** filters one vault by kind/tags (fast, exact).
 
+Choose the read surface by completeness, not convenience. **list-vaults** is the account inventory and
+reports each vault's note count. **memory-list** returns the complete metadata inventory for one vault but
+no note bodies, plus a sorted complete folder inventory derived from those paths; use it to identify every
+stable \`vault + path\` address. **list-memory-tags** returns the
+complete account-wide canonical tag inventory, including aliases, usage counts, and per-vault distribution.
+**memory-search** returns ranked
+content chunks, not an exhaustive inventory or complete documents: deduplicate hits by vault/path and call
+**memory-get** for every note whose full meaning matters. When the user explicitly needs every full note for
+backup, migration, or corpus-wide audit, use **memory-export** one vault at a time; do not pull the entire
+corpus merely to edit one note.
+
 For People, Deals, Projects, Tasks, and Communications, use the returned contract rather than guessing:
 People only holds a real person or organization hub. Its contact card uses \`phone\`, \`text_phone\`, and
 \`email\` for Call/Text/Email; \`memories\` for durable person context; and linked Deals, Projects,
@@ -650,19 +671,35 @@ Tags are live vocabulary, not improvised labels: **list-memory-tags** shows what
 reusable, and has no exact, alias, or near-equivalent. Use **memory-backlinks**,
 **memory-graph-universe**, and **memory-graph-path** to trace the linked universe across vaults.
 
-**Always inspect the complete tag inventory and related notes first.** Use hybrid Smart RAG by default:
+**Always inspect the complete tag inventory and related notes first.** When the user wants to find, recall,
+understand, or connect something and does not already provide an exact vault/path, start with hybrid Smart
+RAG through **memory-search**. The exceptions are exhaustive inventory (**memory-list**), title-only lookup
+(**memory-suggest**), an exact known note (**memory-get**), and an explicit full-vault export (**memory-export**).
+For hybrid retrieval,
 form 3 focused queries (2\u20134 when useful), fuse exact tag/metadata/vault/date and semantic matches into 50
 candidates, expand the top 8 seeds by one link/backlink hop with at most 5 neighbors each, then Jina-rerank
 the combined pool to the best 30. Graph neighbors are candidates, never automatic links; add only links
-supported by the note contents.
+supported by the note contents. A search hit is a discovery excerpt, not the note: call **memory-get** and read
+the complete note before relying on it for an answer, summary, edit, relationship, or durable write. Read the
+strong candidates, not every low-ranked hit.
 
 Scrape deposits are raw evidence and therefore go to **Library** through **library-ingest**, with the full
 Library template and source metadata. If the source contains durable applicable guidance, create a separate
 Knowledge companion through prepare-memory-write + memory-capture and link it to the Library source with
 derived_from; do not replace the raw source with the guide.
 
-For an update, call **memory-get** first and pass its revision as baseRevision. Preserve the existing
-title, source, capture time, content context, and props unless the request deliberately changes them.
+For an update, identify the existing note by its stable \`vault + path\`, call **memory-get** first, and pass
+its revision as \`baseRevision\`. **memory-put replaces the entire content body; it is not a text patch.**
+Merge the requested change into the full body returned by memory-get, then send that complete merged body.
+Its supplied \`props\` patch existing metadata, so omit unchanged props and use an empty array only when the
+user deliberately wants to clear a link list. Preserve the existing title, source, capture time, surrounding
+content, links, template sections, and unsupported uncertainty unless the request deliberately changes them.
+A title change does not create a new note identity; keep the path unless the user explicitly asks to move it.
+Never convert an edit into a new path just because search returned a similar title. If \`baseRevision\`
+conflicts, reconcile the returned current body with the requested change and retry against the new revision;
+do not resend the stale full body unchanged. Treat Agent Inbox, optimizer rollups, channel messages, and other
+system-managed notes through their purpose-built tools when available rather than rewriting their backing
+notes with memory-put.
 If a legacy backend does not return props, do not overwrite an existing linked note through that surface;
 report that link preservation cannot be proved. After the write, read it back and search a distinctive
 phrase to verify persistence and indexing.
@@ -2665,7 +2702,8 @@ ${t.topQuestions.map((q) => `- ${q}`).join("\n")}` : ""
   ${q.threadUrl}` : ""}`).join("\n");
   const full = [
     `# Reddit Trending: "${d.topic || input.topic}"${subreddit ? ` in r/${subreddit}` : ""}`,
-    `**${totals.threads} threads \xB7 ${totals.upvotes} upvotes \xB7 ${totals.comments} comments** \xB7 last ${d.window === "7d" ? "week" : "month"} \xB7 ${d.threadsScraped ?? 0} of ${d.candidatesFound ?? threads.length} discovered scraped${d.partial ? " (partial \u2014 hit the time limit)" : ""}`,
+    `**${totals.threads} threads \xB7 ${totals.upvotes} upvotes \xB7 ${totals.comments} comments** \xB7 last ${d.window === "7d" ? "week" : "month"} \xB7 ${d.threadsScraped ?? 0} of ${d.candidatesFound ?? threads.length} discovered scraped${d.partial ? " (partial)" : ""}`,
+    d.degradedResult ? `**Discovery degraded:** ${(d.degradationReasons ?? []).join(", ") || "no usable discovery surface"}${d.retryRecommended ? " \xB7 retry recommended" : ""}${d.billingRefunded ? " \xB7 discovery charge refunded" : ""}` : d.discoverySource === "reddit_search_fallback" ? "**Discovery fallback:** direct Reddit search was used after the primary SERP returned no usable threads." : "",
     `
 ## Ranked threads
 ${threadBlocks || "_No threads found._"}`,
@@ -2697,7 +2735,13 @@ ${questionList || "_No questions extracted._"}`,
       threadsScraped: Number(d.threadsScraped ?? 0),
       candidatesFound: Number(d.candidatesFound ?? threads.length),
       partial: Boolean(d.partial),
-      searchQuery: d.searchQuery ?? ""
+      searchQuery: d.searchQuery ?? "",
+      discoverySource: d.discoverySource ?? "google_serp",
+      resultQuality: d.resultQuality ?? "complete",
+      degradedResult: Boolean(d.degradedResult),
+      degradationReasons: d.degradationReasons ?? [],
+      retryRecommended: Boolean(d.retryRecommended),
+      billingRefunded: Boolean(d.billingRefunded)
     }
   };
 }
@@ -5607,7 +5651,22 @@ var EditorialReadingRoomSiteSchema = z4.object({
   issueLabel: z4.string().trim().min(1).max(100).default("Current edition").describe("Issue, date, or collection label in the home-page issue line."),
   eyebrow: z4.string().trim().min(1).max(120).default("A guided collection").describe("Short editorial eyebrow above the home-page headline."),
   heroTitle: z4.string().trim().min(1).max(180).describe("Outcome-led home-page headline for the whole reading room."),
-  startLabel: z4.string().trim().min(1).max(60).default("Start reading").describe("Label for the primary start-reading button.")
+  startLabel: z4.string().trim().min(1).max(60).default("Start reading").describe("Label for the primary start-reading button."),
+  ogImage: z4.object({
+    url: z4.string().url().refine((value) => /^https?:\/\//i.test(value), "Image URL must use HTTP or HTTPS.").describe("Public HTTP(S) image URL used for the reading-room home page social preview."),
+    alt: z4.string().trim().min(1).max(500).describe("Accessible description and og:image:alt text."),
+    width: z4.number().int().positive().optional().describe("Optional intrinsic width in pixels."),
+    height: z4.number().int().positive().optional().describe("Optional intrinsic height in pixels.")
+  }).strict().optional().describe("Optional collection-level Open Graph image. Individual articles may override it.")
+}).strict();
+var EditorialReadingRoomImageSchema = z4.object({
+  url: z4.string().url().refine((value) => /^https?:\/\//i.test(value), "Image URL must use HTTP or HTTPS.").describe("Public HTTP(S) image URL."),
+  alt: z4.string().trim().min(1).max(500).describe("Required accessible description of the image."),
+  caption: z4.string().trim().max(1e3).optional().describe("Optional visible caption."),
+  credit: z4.string().trim().max(500).optional().describe("Optional visible creator, publisher, or rights credit."),
+  sourceUrl: z4.string().url().refine((value) => /^https?:\/\//i.test(value), "Source URL must use HTTP or HTTPS.").optional().describe("Optional public HTTP(S) source page for provenance or rights context."),
+  width: z4.number().int().positive().optional().describe("Optional intrinsic width in pixels."),
+  height: z4.number().int().positive().optional().describe("Optional intrinsic height in pixels.")
 }).strict();
 var EditorialReadingRoomArticleSchema = z4.object({
   slug: z4.string().trim().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/).max(80).describe("Unique kebab-case article identifier."),
@@ -5620,7 +5679,9 @@ var EditorialReadingRoomArticleSchema = z4.object({
   sourceLabel: z4.string().trim().min(1).max(500).describe("Visible provenance label naming the material this article was derived from. Do not invent a source."),
   revision: z4.string().trim().min(1).max(80).optional().describe("Optional revision identifier or version label."),
   updatedAt: z4.string().trim().min(1).max(80).optional().describe("Optional human-readable source update date."),
-  markdown: z4.string().min(1).max(1e5).describe("Complete article body in Markdown. Use H2/H3 headings for jump links, short paragraphs, concrete examples, and tables only where they improve comparison.")
+  image: EditorialReadingRoomImageSchema.optional().describe("Optional article image shown on cards and above the article body. Markdown images remain supported inside the body."),
+  ogImage: EditorialReadingRoomImageSchema.optional().describe("Optional article-specific social preview image. Defaults to article.image, then site.ogImage."),
+  markdown: z4.string().min(1).max(1e5).describe("Complete article body in Markdown. Standard Markdown images are allowed with descriptive alt text. Use H2/H3 headings for jump links, short paragraphs, concrete examples, and tables only where they improve comparison.")
 }).strict();
 var EditorialReadingRoomGuideInputSchema = {
   focus: z4.enum(["workflow", "content_contract", "example"]).default("workflow").describe("Which part of the reusable editorial-reading-room guide to return. Start with workflow; fetch the content contract or compact example only when needed.")
@@ -5633,7 +5694,7 @@ var EditorialReadingRoomGuideOutputSchema = {
 var CreateEditorialReadingRoomInputSchema = {
   site: EditorialReadingRoomSiteSchema,
   deck: z4.string().trim().min(1).max(1e3).describe("Two or three sentences that explain the collection\u2019s value and scope without generic marketing language."),
-  articles: z4.array(EditorialReadingRoomArticleSchema).min(1).max(40).describe("One to forty fully authored articles, with no more than 2,000,000 Markdown bytes combined. Read all in-scope source material before composing them; preserve distinctions, uncertainty, and provenance instead of flattening the corpus."),
+  articles: z4.array(EditorialReadingRoomArticleSchema).min(1).max(100).describe("One to one hundred fully authored articles, with no more than 2,000,000 Markdown bytes combined. Articles may include structured card/hero images, article-specific Open Graph images, and Markdown body images. Read all in-scope source material before composing them; preserve distinctions, uncertainty, image provenance, and rights context instead of flattening the corpus."),
   filename: z4.string().trim().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/).max(120).optional().describe("Optional download filename. The server always normalizes it to a safe .html filename.")
 };
 var EditorialReadingRoomArtifactSchema = z4.object({
@@ -6460,7 +6521,13 @@ var RedditTrendingOutputSchema = {
   threadsScraped: z4.number().int().min(0),
   candidatesFound: z4.number().int().min(0),
   partial: z4.boolean(),
-  searchQuery: z4.string()
+  searchQuery: z4.string(),
+  discoverySource: z4.enum(["google_serp", "reddit_search_fallback", "none"]),
+  resultQuality: z4.enum(["complete", "partial", "degraded"]),
+  degradedResult: z4.boolean(),
+  degradationReasons: z4.array(z4.string()),
+  retryRecommended: z4.boolean(),
+  billingRefunded: z4.boolean()
 };
 var FacebookPageIntelOutputSchema = {
   advertiserName: NullableString,
@@ -7626,10 +7693,11 @@ var WORKFLOW_GUIDE = `Create an editorial reading room only after doing the inte
 2. Read every in-scope source before designing the page. Build a source inventory with purpose, authority, overlap, and provenance.
 3. Architect the corpus into a small editorial edition. Prefer one article per real question, decision, lesson, or reusable pattern. Merge duplicate material; preserve meaningful distinctions and uncertainty.
 4. Write the collection-level promise: a specific hero title and deck that explain what the reader will understand or be able to do.
-5. Author complete articles in Markdown. Use H2/H3 headings as a useful table of contents, short paragraphs, concrete examples, and tables only when they materially improve comparison.
-6. Preserve provenance in sourceLabel. Never invent a source, fact, result, quote, or certainty that the source material does not support.
-7. Call create_editorial_reading_room with the finished site metadata, deck, and ordered articles. Do not ask the renderer to discover, research, or write the content for you.
-8. Inspect the returned page at both mobile and desktop sizes. Verify navigation, jump links, article order, typography, overflow, source labels, and that the page opens without a build step.
+5. Author complete articles in Markdown. Use H2/H3 headings as a useful table of contents, short paragraphs, concrete examples, and tables only when they materially improve comparison. Markdown images are supported inside the body.
+6. Choose images only when they help the reader identify, understand, compare, or remember the material. Use article.image for the card/article hero, article.ogImage for a distinct social preview, and site.ogImage for the collection default. Every image needs descriptive alt text; preserve caption, credit, source URL, and rights context when known. Never invent attribution or imply usage rights.
+7. Preserve provenance in sourceLabel. Never invent a source, fact, result, quote, or certainty that the source material does not support.
+8. Call create_editorial_reading_room with the finished site metadata, deck, and ordered articles. Do not ask the renderer to discover, research, or write the content for you.
+9. Inspect the returned page at both mobile and desktop sizes. Verify navigation, jump links, article order, images, alt text, typography, overflow, source labels, social metadata, and that the page opens without a build step.
 
 The renderer owns the reusable New York Times-inspired reading surface, responsive hamburger navigation, search, article jump links, progress, text-size controls, evening mode, and portable single-file HTML delivery.`;
 var CONTENT_CONTRACT = `Editorial reading-room content contract
@@ -7642,13 +7710,16 @@ var CONTENT_CONTRACT = `Editorial reading-room content contract
 - site.eyebrow: collection framing, not a duplicate headline.
 - site.heroTitle: specific outcome or understanding promised by the collection.
 - site.startLabel: concise reading CTA.
+- site.ogImage: optional collection-level Open Graph image with required alt text.
 - deck: two or three concrete sentences covering value and scope.
-- articles: 1-40 complete editorial pieces, each with a unique slug and order.
+- articles: 1-100 complete editorial pieces, each with a unique slug and order.
 - article.category: a repeated grouping label when multiple pieces belong together.
 - article.kicker: short framing line.
 - article.title: the question, decision, lesson, or reusable pattern.
 - article.summary: what the reader will understand.
 - article.sourceLabel: visible, truthful provenance.
+- article.image: optional card/article hero image with alt text and optional caption, credit, source URL, and dimensions.
+- article.ogImage: optional article-specific social image; otherwise article.image, then site.ogImage is used.
 - article.markdown: full body with useful H2/H3 headings.
 
 Quality gates:
@@ -7657,6 +7728,7 @@ Quality gates:
 - Do not use placeholder copy.
 - Keep headings descriptive enough to work as jump links.
 - Prefer a coherent reading sequence over source-file order.
+- Use only public HTTP(S) image URLs. Preserve provenance and rights context; an available URL is not proof of reuse rights.
 - If the corpus is too thin for multiple articles, create one strong article instead of padding the edition.`;
 var EXAMPLE = `Compact example:
 
@@ -7670,7 +7742,11 @@ var EXAMPLE = `Compact example:
     "issueLabel": "Pattern library",
     "eyebrow": "A practical field guide",
     "heroTitle": "Make every saved note easier to find and reuse",
-    "startLabel": "Begin with the pattern"
+    "startLabel": "Begin with the pattern",
+    "ogImage": {
+      "url": "https://example.com/reading-room-social.jpg",
+      "alt": "Connected notes arranged as a navigable editorial collection"
+    }
   },
   "deck": "A concise guide to placing new material in the right vault, connecting it to natural neighbors, and preserving source evidence without turning memory into a generic notes bucket.",
   "articles": [{
@@ -7682,6 +7758,12 @@ var EXAMPLE = `Compact example:
     "summary": "A useful note is not only stored; it is classified, connected, and made retrievable.",
     "sourceType": "Workflow synthesis",
     "sourceLabel": "Derived from the MCP Memory capture contract supplied by the user.",
+    "image": {
+      "url": "https://example.com/graph-operation.jpg",
+      "alt": "A source note connected to related project and knowledge notes",
+      "caption": "Useful captures become connected retrieval objects.",
+      "sourceUrl": "https://example.com/source"
+    },
     "markdown": "## Start with the destination\\n\\nChoose the vault whose job matches the material...\\n\\n## Connect natural neighbors\\n\\nLink only relationships supported by the notes..."
   }]
 }`;
@@ -8532,7 +8614,7 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => formatRedditThread(await executor.redditThread(input), input));
   server.registerTool("reddit_trending", {
     title: "Reddit Trending",
-    description: "Discover the top Reddit conversations about a topic from the last week or month: finds relevant recent threads via a Google site:reddit.com search (optionally scoped to one subreddit), scrapes them for real upvotes, comments, and the questions people asked, and ranks by engagement (upvotes + 2x comments). Scraping runs in parallel across the discovered threads; set includeComments:false for a fast, cheap discovery-only sweep (relevant thread list, no engagement stats, no per-thread billing) and then read the ones you want with reddit_thread. Not for reading one known thread URL \u2014 use reddit_thread for that.",
+    description: "Discover top Reddit conversations from the last week or month. It tries Google site:reddit.com discovery, falls back to a bounded direct Reddit search when that SERP is empty or unavailable, then optionally scrapes threads for real upvotes, comments, questions, and engagement ranking. Inspect resultQuality, discoverySource, degradationReasons, retryRecommended, and billingRefunded before treating an empty result as a genuine lack of discussion. Set includeComments:false for a cheap discovery-only sweep; use reddit_thread for one known URL.",
     inputSchema: RedditTrendingInputSchema,
     outputSchema: recordOutputSchema("reddit_trending", RedditTrendingOutputSchema),
     annotations: liveWebToolAnnotations("Reddit Trending")
@@ -8771,7 +8853,7 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => executor.commonsPreparePublication(input));
   server.registerTool("commons_validate_publication", {
     title: "Validate Transparent Commons Publication",
-    description: "Validate a publication name claim or a complete source-grounded editorial edition without writing. Use operation claim before commons_claim_publication and operation publish before commons_publish_editorial. This uses the editorial reading-room contract and checks ownership plus revision conflicts.",
+    description: "Validate a publication name claim or a complete source-grounded editorial edition without writing. Publish validation accepts up to 100 articles plus structured article/card images, Markdown body images, and collection/article Open Graph images under the editorial reading-room contract. Use operation claim before commons_claim_publication and operation publish before commons_publish_editorial; ownership and revision conflicts are checked.",
     inputSchema: CommonsValidatePublicationInputSchema,
     outputSchema: recordOutputSchema("commons_validate_publication", CommonsGenericOutputSchema),
     annotations: { title: "Validate Transparent Commons Publication", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
@@ -8785,7 +8867,7 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => executor.commonsClaimPublication(input));
   server.registerTool("commons_publish_editorial", {
     title: "Publish Transparent Commons Editorial Edition",
-    description: "Publish a fully authored editorial reading-room edition to the caller-owned Transparent Commons subdomain and return permanent root, archive, and edition URLs. The calling AI must research and author the source-grounded edition first; this tool validates, renders, and persists it. For an existing edition, pass its current baseRevision. Requires an idempotencyKey; this is not the neutral wiki write tool.",
+    description: "Publish up to 100 fully authored editorial pieces, including optional article/card images, Markdown body images, and collection/article Open Graph images, to the caller-owned Transparent Commons subdomain. The calling AI must research and author the source-grounded edition first; image URLs need alt text and preserved provenance/rights context. The tool validates, renders, persists, and returns permanent root, archive, and edition URLs. Existing editions require current baseRevision. Requires idempotencyKey; this is not the neutral wiki write tool.",
     inputSchema: CommonsPublishEditorialInputSchema,
     outputSchema: recordOutputSchema("commons_publish_editorial", CommonsGenericOutputSchema),
     annotations: { title: "Publish Transparent Commons Editorial Edition", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
@@ -8922,7 +9004,7 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => formatWorkflowArtifactRead(await executor.workflowArtifactRead(input), input));
   server.registerTool("editorial_reading_room_guide", {
     title: "Editorial Reading Room Guide",
-    description: 'Read the reusable composition contract before creating an editorial reading room. It tells the calling AI how to inventory the supplied corpus, preserve source truth, architect a coherent edition, write useful articles, and verify the finished page. Start with focus "workflow"; fetch "content_contract" or "example" only when needed. This does not research, write, or create a page.',
+    description: 'Read the reusable composition contract before creating an editorial reading room. It covers corpus inventory, source truth, coherent architecture, up to 100 articles, purposeful images, image provenance, collection/article Open Graph images, and finished-page verification. Start with focus "workflow"; fetch "content_contract" or "example" only when needed. This does not research, write, or create a page.',
     inputSchema: EditorialReadingRoomGuideInputSchema,
     outputSchema: recordOutputSchema("editorial_reading_room_guide", EditorialReadingRoomGuideOutputSchema),
     annotations: localPlanningToolAnnotations("Editorial Reading Room Guide")
@@ -8938,7 +9020,7 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }));
   server.registerTool("create_editorial_reading_room", {
     title: "Create Editorial Reading Room",
-    description: `Turn fully authored, source-grounded articles into one polished mobile-first editorial report with contents, search, hamburger navigation, article jump links, reading progress, text sizing, evening mode, and provenance. Do not use this tool to discover, preview, save, or version reusable website templates; use list_artifact_templates and get_artifact_template_example for that workflow. The calling AI must first read all in-scope material and use editorial_reading_room_guide when it has not already internalized the workflow; this renderer does not perform research or invent copy. ${fileBehavior("Local stdio clients save one self-contained HTML file under the MCP Scraper output directory and return localPath.", "Hosted/app clients receive an owner-scoped private HTML artifact retained for seven days with a renewable signed download URL.")}`,
+    description: `Render up to 100 fully authored, source-grounded articles into one polished mobile-first editorial report with contents, search, navigation, jump links, progress, text sizing, evening mode, provenance, structured article/card images, Markdown body images, and collection/article Open Graph metadata. Public HTTP(S) image URLs require alt text; preserve caption, credit, source, and rights context when known. The static artifact carries collection OG tags and updates article tags in-browser; a publishing host must serve article-specific metadata for crawler-perfect per-article unfurls. This renderer does not research or invent copy. For reusable website templates use list_artifact_templates instead. ${fileBehavior("Local stdio clients save one self-contained HTML file under the MCP Scraper output directory and return localPath.", "Hosted/app clients receive an owner-scoped private HTML artifact retained for seven days with a renewable signed download URL.")}`,
     inputSchema: CreateEditorialReadingRoomInputSchema,
     outputSchema: recordOutputSchema("create_editorial_reading_room", CreateEditorialReadingRoomOutputSchema),
     annotations: {
@@ -9138,6 +9220,29 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
 
 // src/mcp/http-mcp-tool-executor.ts
 import { createHash as createHash4, randomUUID as randomUUID2 } from "crypto";
+function unclassifiedTransportFailure(path, err) {
+  const name = err instanceof Error ? err.name : typeof err;
+  const detail = err instanceof Error ? err.message : String(err);
+  console.error(JSON.stringify({
+    event: "mcp_executor_transport_failed",
+    path,
+    error_name: name,
+    error_message: sanitizeVendorName(detail).slice(0, 400)
+  }));
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        error: "service_unavailable",
+        error_type: name,
+        retryable: true,
+        path,
+        message: publicErrorMessage("service_unavailable")
+      })
+    }],
+    isError: true
+  };
+}
 function youtubeVideoIdFromUrl(url) {
   if (!url) return null;
   try {
@@ -9238,7 +9343,7 @@ var HttpMcpToolExecutor = class {
     const rawOverride = process.env.MCP_SCRAPER_HTTP_TIMEOUT_MS;
     const parsedOverride = rawOverride === void 0 ? NaN : Number(rawOverride);
     this.httpTimeoutOverrideMs = Number.isFinite(parsedOverride) && parsedOverride > 0 ? parsedOverride : null;
-    this.timeoutMs = this.httpTimeoutOverrideMs ?? 11e4;
+    this.timeoutMs = this.httpTimeoutOverrideMs ?? DEFAULT_TOOL_CLIENT_TIMEOUT_MS;
     const configuredSerpIntelligenceTimeoutMs = Number(process.env.MCP_SCRAPER_SERP_INTELLIGENCE_HTTP_TIMEOUT_MS ?? this.timeoutMs);
     this.serpIntelligenceTimeoutMs = Number.isFinite(configuredSerpIntelligenceTimeoutMs) && configuredSerpIntelligenceTimeoutMs > 0 ? configuredSerpIntelligenceTimeoutMs : this.timeoutMs;
   }
@@ -9277,7 +9382,7 @@ var HttpMcpToolExecutor = class {
           isError: true
         };
       }
-      return { content: [{ type: "text", text: publicErrorMessage("service_unavailable") }], isError: true };
+      return unclassifiedTransportFailure(path, err);
     }
   }
   async callConnectedMutation(path, body, idempotencyKey, timeoutMs = this.timeoutMs) {
@@ -9311,8 +9416,8 @@ var HttpMcpToolExecutor = class {
         return { content: [{ type: "text", text: JSON.stringify(httpErrorPayload(path, res, data)) }], isError: true };
       }
       return { content: [{ type: "text", text: JSON.stringify(data) }] };
-    } catch {
-      return { content: [{ type: "text", text: publicErrorMessage("service_unavailable") }], isError: true };
+    } catch (err) {
+      return unclassifiedTransportFailure(path, err);
     }
   }
   async getTextArtifact(path, maxBytes, timeoutMs = this.timeoutMs) {
@@ -9349,7 +9454,7 @@ var HttpMcpToolExecutor = class {
         }]
       };
     } catch (err) {
-      return { content: [{ type: "text", text: publicErrorMessage("service_unavailable") }], isError: true };
+      return unclassifiedTransportFailure(path, err);
     }
   }
   harvestPaa(input) {
@@ -12559,7 +12664,7 @@ var DeleteNoteSchema = {
 var ExportSchema = {
   id: "memory-export",
   upstreamName: "exportTool",
-  description: "Export every note in a vault as a full dump for backup, migration, or bulk download \u2014 path, title, full content, kind, and last-updated per note, plus a count. Defaults to the active (or first entitled) vault. Requires export scope; the export is logged to provenance.",
+  description: "Export every full note in one vault for an explicitly requested backup, migration, or corpus-wide audit \u2014 path, title, content, kind, last-updated, and count. This can be large and is not the normal way to find or edit one note: use memory-list for complete metadata inventory, memory-search for ranked recall, and memory-get for exact content. Defaults to the active or first entitled vault. Requires export scope; the export is logged to provenance.",
   input: {
     vault: z9.string().optional().describe(
       "Vault to export. Optional; defaults to the session active vault, then the first vault the caller is entitled to."
@@ -12611,7 +12716,7 @@ var getTool_notePropsSchema = z9.object({
 var GetSchema = {
   id: "memory-get",
   upstreamName: "getTool",
-  description: "Read a single note from a vault by its exact path, or by shareId for a note shared with you and accepted. Owned notes include their stored Obsidian props so edits can preserve links and template metadata. Returns a revision number \u2014 pass it as baseRevision on a later memory-put/delete-note to detect a concurrent edit instead of silently overwriting it. Requires read scope.",
+  description: "Read one complete note by exact vault+path, or by accepted shareId. After memory-search identifies a strong candidate, use this before relying on it for an answer, summary, edit, link, or durable write: search results are excerpts, not complete notes. Owned notes include stored Obsidian props so edits preserve links and template metadata. Returns the revision required as baseRevision on later edits/deletes. Requires read scope.",
   input: {
     vault: z9.string().optional().describe(
       "Vault to read from. Optional; defaults to the session active vault, then the first vault the caller is entitled to. Ignored when shareId is given."
@@ -12648,7 +12753,7 @@ var GetSchema = {
 var ListSchema = {
   id: "memory-list",
   upstreamName: "listTool",
-  description: "List notes in a vault \u2014 path, title, kind, tags, last-updated \u2014 optionally filtered by kind and/or tags (matches ANY given tag). Defaults to the active or first entitled vault; also returns vaults the caller is entitled to. Requires read scope.",
+  description: "Return every note in one vault as a complete metadata inventory \u2014 stable path, title, kind, tags, and last-updated \u2014 plus a sorted list of every unique folder and nested folder represented by those paths. It contains no bodies. Use memory-get for exact full content, memory-search for ranked semantic recall, or memory-export only when explicitly asked for every full note. Defaults to the active or first entitled vault; also returns entitled vaults. Requires read scope.",
   input: {
     vault: z9.string().optional().describe(
       "Vault to list. Optional; defaults to the session active vault, then the first vault the caller is entitled to."
@@ -12668,6 +12773,7 @@ var ListSchema = {
         updatedAt: z9.string().describe("ISO-8601 timestamp of the note last update.")
       })
     ).optional().describe("The notes in the vault (metadata only, no content). Present when ok is true."),
+    folders: z9.array(z9.string()).optional().describe("Sorted complete folder inventory derived from note paths, including represented nested parent folders. Present when ok is true."),
     vaults: z9.array(z9.string()).optional().describe("All vaults the caller is entitled to, for choosing a different vault to list."),
     error: z9.string().optional().describe("Human-readable failure reason when ok is false.")
   },
@@ -12702,7 +12808,7 @@ var putTool_notePropsSchema = z9.object({
 var PutSchema = {
   id: "memory-put",
   upstreamName: "putTool",
-  description: "Create or deliberately edit one note at a path in a memory vault; content is persisted and indexed for search. For normal new People, Organizations, Deals, Projects, Tasks, or Communication records, use prepare-memory-write then memory-capture: People must be real people, Organizations must be real organizations, Deals need a known party, Projects need a supported kind, Tasks can be independent Inbox todos or use a verified Project when linked, and draft emails need pending approval. For row-shaped datasets you'll filter/sort by exact value, use table-create/table-insert-rows/table-query instead. Ordinary vaults are indexed and shareable \u2014 never store real secrets there; use a secure vault (create-secure-vault) instead, which is never indexed or shareable and is encrypted at rest. Requires write scope.",
+  description: "Create or deliberately edit one note at a stable vault+path. On an existing note, first call memory-get, merge the requested change into its full body, and pass that complete body plus baseRevision: content is replace-all, while supplied props patch the stored props. A conflict returns the current body for reconciliation; never retry the stale full body unchanged. Use purpose-built tools instead of rewriting system-managed Agent Inbox, optimizer, or channel backing notes. For normal new People, Organizations, Deals, Projects, Tasks, or Communication records, use prepare-memory-write then memory-capture. For row-shaped datasets use table tools. Ordinary vaults are indexed and shareable; store real secrets only in a secure vault. Requires write scope.",
   input: {
     vault: z9.string().optional().describe(
       "Vault to write to. Optional; defaults to the session active vault, then the first vault the caller is entitled to. On a default-provisioned account, pick the vault whose job matches the content (see the server instructions for the full 16-vault guide) rather than defaulting blindly \u2014 e.g. a lesson learned goes in Knowledge, the raw source it came from goes in Library, a broken feature goes in Issues, a named real-world initiative goes in Projects. Do not use this low-level tool to create ordinary People, Organizations, Deals, Projects, Tasks, or Communication records: first use prepare-memory-write then memory-capture so relationships and approval state are validated."
@@ -12710,9 +12816,9 @@ var PutSchema = {
     path: z9.string().optional().describe("Vault-relative note path to create or overwrite, e.g. projects/q3-plan. Writing an existing path replaces it. Required unless shareId is given."),
     shareId: z9.string().optional().describe("Edit a note someone individually shared with you and you accepted (accept-share), by its shareId, instead of vault+path. Requires the share to grant edit permission, and baseRevision is mandatory (get the current revision first) since you are editing alongside the owner and possibly others."),
     title: z9.string().optional().describe("Optional human-readable title; defaults are derived from the path when omitted."),
-    content: z9.string().min(1).describe("The full note body to store and index for semantic search. Must be non-empty."),
+    content: z9.string().min(1).describe("The complete note body to store and index. On edit this replaces the prior body, so merge the requested change into the full memory-get content before calling; never pass only the changed fragment."),
     props: putTool_notePropsSchema.optional().describe("Obsidian note primitives plus vault-specific template fields. On edits, supplied fields patch the stored props instead of replacing the whole object; pass an empty array to deliberately clear a link list. Type/domain/folder also steer routing when no vault is given."),
-    baseRevision: z9.number().optional().describe("Revision the edit is based on (from a prior get/put). When provided, the write only applies if the note is still at this revision; otherwise it is rejected as a conflict instead of silently overwriting a concurrent edit. Omit for last-write-wins (fine for solo notes)."),
+    baseRevision: z9.number().optional().describe("Revision the edit is based on (from memory-get/put). Always supply it when an AI edits an existing note; a mismatch rejects the write and returns current content for reconciliation. Omit only for an intentional new note or explicit last-write-wins migration."),
     tagDescriptions: z9.record(z9.string(), z9.string()).optional().describe("One-line meaning for any tag in props.tags that is new to the account, keyed by tag. Tags resolve against the account's existing vocabulary; new tags require a one-line description.")
   },
   output: {
@@ -12746,7 +12852,7 @@ var searchTool_primitiveValue = z9.union([z9.string(), z9.number(), z9.boolean()
 var SearchSchema = {
   id: "memory-search",
   upstreamName: "searchTool",
-  description: "Default Smart RAG search across accessible memory. Form 2-4 focused query variants, combine semantic matches with exact vault/tag/date/kind/type/metadata filters, expand one bounded hop of outgoing links and backlinks around strong seeds, then rerank. Defaults: retrieve/fuse 50 candidates, 8 graph seeds, 5 neighbors per seed, rerank to 30. Graph neighbors are candidates, never automatic winners or links. Before tagging or writing, also call list-memory-tags to inspect the complete vocabulary and reuse existing tags; read strong related notes before selecting links.",
+  description: "Default first tool whenever the user wants to find, recall, understand, or connect Memory content without an exact vault+path. Hybrid Smart RAG combines 2-4 semantic query variants with exact vault/tag/date/kind/type/metadata matches, expands one bounded graph hop, then reranks. Results are ranked excerpts, never an exhaustive inventory or complete notes: deduplicate by vault/path and call memory-get on strong candidates before answering, summarizing, editing, linking, or writing. Use memory-list for every note, memory-suggest for title-only lookup, and memory-export only for explicit full-vault dumps. Before tagging or writing, also inspect list-memory-tags.",
   input: {
     vault: z9.string().optional().describe("Exact logical vault handle to search. Omit to search every entitled vault."),
     query: z9.string().min(1).describe("A focused semantic reformulation of the request."),
@@ -14467,4 +14573,4 @@ export {
   ScheduledResultsMcpExecutor,
   registerScheduledResultsMcpTools
 };
-//# sourceMappingURL=chunk-64WBUDPC.js.map
+//# sourceMappingURL=chunk-O63VVCCE.js.map