@paradigma-inc/flywheel 0.1.19 → 0.1.26

package/skills/flywheel-to-graph/references/source-paper.md

@@ -0,0 +1,85 @@
+# Paper Source Reference
+
+Use this reference when the source is a paper PDF, arXiv page, DOI URL, or direct PDF URL.
+
+## Source Detection
+
+Match this reference when any of these are true:
+
+- Local file ends with `.pdf`.
+- URL matches `arxiv.org/abs/`.
+- URL matches `arxiv.org/pdf/`.
+- URL is a DOI resolver link (`doi.org/...`).
+- URL is a direct PDF link.
+
+## Acquisition Rules
+
+Acquire source content in this order:
+
+1. Local PDF path: read local file bytes and preserve original filename.
+2. arXiv HTML URL (`arxiv.org/abs/...` or `arxiv.org/html/...`): fetch page body and parse section structure from HTML.
+3. arXiv PDF URL (`arxiv.org/pdf/...`): download PDF bytes and treat as PDF input.
+4. DOI URL: resolve final landing page; if it exposes a PDF, download it, otherwise fetch the HTML body.
+5. Direct PDF URL: download PDF bytes.
+
+## Parsing Rules
+
+For PDF text extraction, use parser fallback chain exactly:
+
+`PyMuPDF -> pypdfium2 -> pypdf`
+
+- Try one parser at a time in that order.
+- Advance to the next parser only when the previous parser fails to extract usable text.
+- If all parsers fail, emit explicit failure and stop. Do not continue with partial guessed structure.
+- If all parsers fail, do not silently produce a single-summary node with a PDF artifact.
+
+License note:
+
+- PyMuPDF is AGPL-3.0. Artifex offers a commercial license when AGPL terms are not acceptable for downstream distribution.
+
+For arXiv HTML parsing, use LaTeXML selector boundaries:
+
+- Top-level sections: `section.ltx_section`
+- Top-level headings: `h2.ltx_title`
+- Subsections: `section.ltx_subsection`
+- Subsection headings: `h3.ltx_title`
+
+Do not use naive `section` selectors without class filtering.
+
+## Graph Decomposition Contract
+
+Default shape:
+
+- Create one parent paper node under the requested root.
+- Create one child node per detected top-level paper section.
+- Typical section set includes Abstract, Introduction, Methods, Results, Discussion, Conclusion, and Related Work when present.
+
+## Content Placement Contract
+
+- Parent title: paper title.
+- Parent summary: abstract or concise abstract-derived synopsis.
+- Parent content: one-paragraph orientation plus links/references to section children.
+- Child content: narrative for that section only.
+
+## Artifact Contract
+
+- Attach the paper PDF artifact to the parent paper node.
+- Attach extracted figures/tables to the section child where they appear, when extraction is feasible.
+
+## Edge Contract
+
+- Use hierarchy edges for paper parent -> section children.
+- Do not add lateral interpretive edges (`cites`, `builds-on`, `derived-from`) by default.
+
+## Insight Controller Contract
+
+- Single-paper one-shot import: no separate insight control node is created.
+- Multi-paper corpus import: create one insight control node above paper parent nodes.
+
+## Failure Contract
+
+- If acquisition fails, return explicit failure with the failing source variant and stop.
+- If all parsers fail, return explicit failure and stop.
+- Do not silently degrade to one summary node plus artifact-only output.
+
+These rules apply only when `$flywheel-to-graph` is the active skill.

package/skills/flywheel-to-graph/references/source-wiki.md

@@ -0,0 +1,35 @@
+# Wiki Source Reference
+
+Use this reference for markdown wiki-style corpora, README trees, GitHub wiki exports, and Notion markdown exports.
+
+## Source Detection
+
+Match this reference when source material is wiki-like markdown content with multiple linked pages.
+
+## Acquisition
+
+- Collect all relevant markdown pages in scope.
+- Preserve stable page identifiers from file paths or page titles.
+
+## Decomposition
+
+- One stable page or concept maps to one node by default.
+- Large pages may split by top-level headings when that improves readability.
+
+## Content and Artifacts
+
+- Main narrative goes into node `content`.
+- Short synopsis goes into `summary`.
+- Supporting files (images, PDFs, data files, notebooks) are node artifacts.
+
+## Edges
+
+- Promote only durable semantic relationships to graph edges.
+- Keep incidental hyperlinks in markdown body.
+
+## Failure Behavior
+
+- If pages are unreadable or missing, emit explicit failure and stop for that page.
+- Do not silently skip unreadable pages.
+
+These rules apply only when `$flywheel-to-graph` is the active skill.

package/src/cli.mjs

@@ -40,6 +40,7 @@ import {
   listBundledSkills,
   partitionInstallSkillHosts,
   removeInstalledSkillsForHosts,
+  resolveSkillsAgentName,
   SUPPORTED_INSTALL_SKILL_HOSTS,
   resolveInstalledSkillDir,
   resolvePackageRoot,
@@ -403,7 +404,12 @@ async function setupHost(hostName, scope, serverUrl, apiKey, serverName) {
   };
 }
 
-function printSetupResults(results, scope, serverUrl) {
+function printSetupResults(
+  results,
+  scope,
+  serverUrl,
+  { showSkillRefreshGuidance = false, experimentalSyncAgents = [] } = {},
+) {
   log.blank();
   log.plain(pc.green("✔ Flywheel setup complete"));
   log.blank();
@@ -417,9 +423,48 @@ function printSetupResults(results, scope, serverUrl) {
     log.plain(`    ${icon} ${result.status}`);
     log.plain(`      ${pc.dim(result.filePath)}`);
   }
+  if (showSkillRefreshGuidance) {
+    log.blank();
+    log.plain("  Bundled skill refresh guidance");
+    log.plain(
+      `    Preferred: ${pc.bold("npx --yes @paradigma-inc/flywheel@latest setup --install-skill --project")}`,
+    );
+    log.plain(
+      `      ${pc.bold("npm install --save-dev @paradigma-inc/flywheel@latest")}`,
+    );
+    if (experimentalSyncAgents.length === 1) {
+      log.plain("    Optional path via skills experimental_sync:");
+      log.plain(
+        `      ${pc.bold(`npx skills experimental_sync --agent ${experimentalSyncAgents[0]} -y`)}`,
+      );
+    } else if (experimentalSyncAgents.length > 1) {
+      log.plain("    Optional path via skills experimental_sync for selected hosts:");
+      for (const agentName of experimentalSyncAgents) {
+        log.plain(
+          `      ${pc.bold(`npx skills experimental_sync --agent ${agentName} -y`)}`,
+        );
+      }
+    }
+  }
   log.blank();
 }
 
+function resolveExperimentalSyncAgentsForHosts(supportedHosts) {
+  const agentNames = [];
+  const seenAgentNames = new Set();
+
+  for (const hostName of supportedHosts) {
+    const agentName = resolveSkillsAgentName(hostName);
+    if (seenAgentNames.has(agentName)) {
+      continue;
+    }
+    seenAgentNames.add(agentName);
+    agentNames.push(agentName);
+  }
+
+  return agentNames;
+}
+
 async function promptGuidedSkillInstall(
   bundledSkillNames,
   unsupportedHosts,
@@ -658,7 +703,21 @@ async function runSetupCommand(options) {
       const completedCleanupState = cleanupState;
       cleanupState = null;
       await discardInstallSkillCleanupState(completedCleanupState);
-      printSetupResults(setupResults, scope, serverUrl);
+      const showSkillRefreshGuidance =
+        scope === "project" &&
+        skillDecisionMode === "install" &&
+        supportedHosts.length > 0;
+      printSetupResults(
+        setupResults,
+        scope,
+        serverUrl,
+        {
+          showSkillRefreshGuidance,
+          experimentalSyncAgents: showSkillRefreshGuidance
+            ? resolveExperimentalSyncAgentsForHosts(supportedHosts)
+            : [],
+        },
+      );
       return;
     }
 
@@ -720,7 +779,14 @@ async function runSetupCommand(options) {
     const completedCleanupState = cleanupState;
     cleanupState = null;
     await discardInstallSkillCleanupState(completedCleanupState);
-    printSetupResults(setupResults, scope, serverUrl);
+    const showSkillRefreshGuidance =
+      scope === "project" && supportedHosts.length > 0;
+    printSetupResults(setupResults, scope, serverUrl, {
+      showSkillRefreshGuidance,
+      experimentalSyncAgents: showSkillRefreshGuidance
+        ? resolveExperimentalSyncAgentsForHosts(supportedHosts)
+        : [],
+    });
   } catch (error) {
     if (cleanupState) {
       await cleanupInstalledSkillArtifactsForHosts({