@taurgis/bonsai 1.0.2 → 1.0.3

package/agents/instructions/web-research.instructions.md

@@ -1,19 +1,31 @@
 ---
-description: 'Require the Official Docs Researcher subagent before technical repo changes.'
+description: 'Verify current official docs before technical repo changes — inline via the web-research skill for minor research, via the Official Docs Researcher subagent for extensive research.'
 applyTo: '**'
 skills:
   - web-research
 metadata:
-  version: '3.0.0'
+  version: '3.1.0'
 ---
 
 # Web Research Requirement
 
 ## Mandatory Pre-Step
 
-- Run the **Official Docs Researcher** subagent before creating, updating, refactoring, scaffolding, or deleting technical content.
-- Use its findings to apply current official documentation and references in the change.
-- The researcher keeps a freshness-tiered Bonsai cache (its data directory or project-local `.bonsai/research/`): it reuses fresh notes, cheaply revalidates stale ones, and re-fetches only on a miss. Re-running on a recent topic is cheap — invoke it rather than skipping research to "save" a fetch.
+- Verify the relevant current official documentation **in the same task** before creating, updating, refactoring, scaffolding, or deleting technical content.
+- Apply what you find — cite official source URLs when the change relies on platform behavior or standards.
+- Research is the requirement; how you run it scales with scope (below). Training-data knowledge never satisfies this — only docs fetched in the current task do.
+
+## Choose How to Research by Scope
+
+- **Minor research — run it inline.** For a single known page, one platform, or a quick flag/API/version check, the main agent invokes the **web-research** skill directly. A separate subagent is not required.
+- **Extensive research — delegate to a subagent.** For multiple sources or platforms, unfamiliar territory, broad audits, or anything that produces verbose output you do not want in the main context, run the **Official Docs Researcher** subagent and apply its findings.
+- The main agent may always use the **web-research** skill directly — choose the subagent to isolate large research, not because inline research is disallowed.
+- When unsure, start inline and escalate to the subagent once the work spans several sources.
+
+## Shared Cache
+
+- Both paths use the same freshness-tiered Bonsai cache (data directory or project-local `.bonsai/research/`): it reuses fresh notes, cheaply revalidates stale ones, and re-fetches only on a miss.
+- Re-running on a recent topic is cheap — research the topic rather than skipping it to "save" a fetch.
 
 ## When Not to Use
 
@@ -23,7 +35,8 @@ metadata:
 
 ## Examples
 
-- ✅ Before editing instructions, prompts, agents, skills, workflows, or docs.
-- ✅ Before auditing or refactoring source — reading source code does not replace checking current platform guidance.
+- ✅ Confirming one platform's current flag or frontmatter field before a small edit → run the web-research skill inline.
+- ✅ Comparing conventions across several platforms, or auditing/refactoring source broadly → delegate to the Official Docs Researcher subagent.
+- ✅ Before editing instructions, prompts, agents, skills, workflows, or docs — reading source code does not replace checking current platform guidance.
 - ✅ Include official source URLs when the change references platform behavior or standards.
-- ❌ Don't modify technical content without running the subagent first, or treat cached/training knowledge as equivalent — official guidance evolves and must be verified per task.
+- ❌ Don't modify technical content without researching first, and don't treat cached or training knowledge as equivalent — official guidance evolves and must be verified per task.

package/dist/lib/research/docs/validate.js

@@ -6,6 +6,9 @@ const ERROR_PAGE_PATTERNS = [
     /\bnot\s*found\b/i,
     /there\s*isn'?t\s*a\s*github\s*pages\s*site\s*here/i,
     /site\s*not\s*found/i,
+    // Client-rendered (SPA) failure shells that return HTTP 200 but render only an error notice.
+    /something\s+went\s+wrong/i,
+    /an?\s+error\s+occurred/i,
 ];
 /** True when short text reads like an error/soft-404 page rather than real content. */
 export function looksLikeErrorPage(text) {

package/dist/lib/research/revalidate.js

@@ -7,6 +7,7 @@ import { evaluateFreshness, getPolicy } from './freshness.js';
 import { compressMarkdown } from './compress.js';
 import { estimateTokens } from './token-estimate.js';
 import { fetchRenderedHtml } from './browser.js';
+import { looksLikeErrorPage } from './docs/validate.js';
 function buildMetadata(url, normalizedUrl, cacheKey, fetchResult, extraction, tier, ttl, currentTime, compressed) {
     const contentHash = createHash('sha256').update(extraction.detailedMarkdown).digest('hex');
     const staleAfterTime = new Date(currentTime);
@@ -51,10 +52,39 @@ function buildMetadata(url, normalizedUrl, cacheKey, fetchResult, extraction, ti
         section_heading_path: null,
     };
 }
+// Builds a compact error marker instead of caching a full error page. Subsequent lookups serve this
+// tiny marker (a handful of tokens) instead of re-fetching, and revalidation re-checks it when stale
+// so a transient failure recovers into a real artifact.
+function buildErrorArtifact(url, normalizedUrl, cacheKey, fetchResult, tier, ttl, currentTime, reason) {
+    const marker = `Error: ${url} could not be cached — ${reason}. ` +
+        'The page returned an error, so its content was not stored; it will be re-fetched when this entry goes stale.';
+    const extraction = {
+        title: `Error: ${reason}`,
+        detailedMarkdown: marker,
+        confidence: 'low',
+        qualityNotes: [`error: ${reason}`],
+    };
+    const metadata = buildMetadata(url, normalizedUrl, cacheKey, fetchResult, extraction, tier, ttl, currentTime, marker);
+    metadata.extraction_status = 'failed';
+    metadata.extraction_confidence = null;
+    return {
+        metadata,
+        summary: extraction.title,
+        compressed: marker,
+        detailed: marker,
+        provenance: `Fetched from ${url} on ${currentTime.toISOString()} (error page; content not cached)`,
+    };
+}
 /**
  * Helper to construct a ResearchArtifact from a fresh HTML fetch.
  */
 export function createArtifactFromFetch(url, normalizedUrl, cacheKey, fetchResult, extraction, tier, ttl, currentTime) {
+    // A managed platform / SPA can return HTTP 200 but render only a "not found" / "something went
+    // wrong" shell. Cache a compact marker for those instead of the full error markdown, so repeat
+    // lookups cost a few tokens and revalidation still re-checks the page when the entry goes stale.
+    if (looksLikeErrorPage(extraction.detailedMarkdown)) {
+        return buildErrorArtifact(url, normalizedUrl, cacheKey, fetchResult, tier, ttl, currentTime, 'page reported an error or was not found');
+    }
     const compressed = compressMarkdown(extraction.detailedMarkdown);
     const metadata = buildMetadata(url, normalizedUrl, cacheKey, fetchResult, extraction, tier, ttl, currentTime, compressed);
     return {

package/oclif.manifest.json

@@ -845,5 +845,5 @@
       "stdoutIsPrimaryData": true
     }
   },
-  "version": "1.0.2"
+  "version": "1.0.3"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taurgis/bonsai",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Bonsai is a standalone local research cache CLI for AI agents",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,6 +26,7 @@
     "regression:suite": "tsc -b && node testing/regression/run-suite.mjs",
     "regression:promote": "tsc -b && node testing/regression/run-suite.mjs --promote",
     "regression:check": "tsc -b && node testing/regression/run-suite.mjs --strict",
+    "nexus:sync": "npx forward-nexus update && npx forward-nexus sync",
     "test": "vitest",
     "test:coverage": "vitest run --coverage",
     "type-check": "tsc --noEmit"