feat(skills): rework payments around the placed-cart lock, add Mollie and Two

docs/src/loaders/skills-loader.ts

@@ -1,6 +1,6 @@
 import type { Loader } from "astro/loaders";
 import { readdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join, relative, resolve, sep } from "node:path";
 
 const SKILLS_DIR = join(new URL(".", import.meta.url).pathname, "../../../use-crystallize/skills");
 
@@ -40,6 +40,31 @@ function parseFrontmatter(content: string) {
     };
 }
 
+function referenceAnchor(file: string) {
+    return `ref-${file.replace(/\.md$/, "")}`;
+}
+
+// A skill page inlines SKILL.md and every references/*.md into one document, so the
+// relative .md links between those files (`references/x.md`, `../SKILL.md#y`,
+// `../mutation/SKILL.md`) resolve to URLs that were never built. Point each link that
+// lands on a skill file at where that file ended up: a reference is the anchor above
+// its section, a SKILL.md is the top of its skill page.
+function rewriteSkillLinks(markdown: string, fromDir: string, currentSkill: string): string {
+    return markdown.replace(/\]\(([^)\s#]+\.md)(#[^)\s]*)?\)/g, (link, path: string, hash = "") => {
+        if (/^([a-z]+:|\/)/i.test(path)) return link;
+
+        const [skill, ...rest] = relative(SKILLS_DIR, resolve(fromDir, path)).split(sep);
+        const page = skill === currentSkill ? "" : `/ai/skills/${skill}/`;
+        if (rest.length === 1 && rest[0] === "SKILL.md") {
+            return `](${page}${hash || (page ? "" : "#_top")})`;
+        }
+        if (rest.length === 2 && rest[0] === "references") {
+            return `](${page}${hash || `#${referenceAnchor(rest[1])}`})`;
+        }
+        return link;
+    });
+}
+
 async function readReferences(skillDir: string): Promise<string> {
     const refsDir = join(skillDir, "references");
     try {
@@ -49,7 +74,8 @@ async function readReferences(skillDir: string): Promise<string> {
             if (!file.endsWith(".md")) continue;
             const content = await readFile(join(refsDir, file), "utf-8");
             const { body } = parseFrontmatter(content);
-            parts.push(body.trim());
+            const linked = rewriteSkillLinks(body.trim(), refsDir, basename(skillDir));
+            parts.push(`<div id="${referenceAnchor(file)}"></div>\n\n${linked}`);
         }
         if (parts.length > 0) {
             return "\n\n---\n\n## Reference Details\n\n" + parts.join("\n\n");
@@ -86,7 +112,7 @@ export function skillsLoader(): Loader {
 
                 const { name, description, body } = parseFrontmatter(content);
                 const references = await readReferences(join(SKILLS_DIR, dir));
-                const fullBody = body.trim() + references;
+                const fullBody = rewriteSkillLinks(body.trim(), join(SKILLS_DIR, dir), dir) + references;
                 const rendered = await renderMarkdown(fullBody);
 
                 store.set({

use-crystallize/mcp-servers/crystallize/bin/eval-reference-selection.cases.json

@@ -5,6 +5,16 @@
         "skills": ["payments"],
         "expected": ["payments/vipps-mobilepay", "payments/stripe"]
     },
+    {
+        "task": "accept iDEAL and Bancontact through Mollie in our Crystallize checkout",
+        "skills": ["payments"],
+        "expected": ["payments/mollie"]
+    },
+    {
+        "task": "let business customers pay by invoice with Two, including a company lookup at checkout",
+        "skills": ["payments"],
+        "expected": ["payments/two"]
+    },
     {
         "task": "create a product shape through the API with a paragraph collection and a grid relation",
         "skills": ["content-model"],

use-crystallize/skills/mutation/SKILL.md

@@ -181,10 +181,17 @@ const api = createClient({
     accessTokenSecret: "...",
 });
 
-// Use pimApi for Core API mutations
-const result = await api.pimApi(mutationString, variables);
+// Core API mutations (api.crystallize.com/@tenant)
+const result = await api.nextPimApi(mutationString, variables);
+
+// Shop API mutations: one caller per endpoint, the Shop API token is fetched for you
+await api.shopCartApi(cartMutation, variables); // /cart
+await api.shopOrderApi(orderMutation, variables); // /order (js-api-client 7.5+)
 ```
 
+For checkout, prefer the helpers: `createCartManager` (`hydrate`, `place`) and `createShopOrderManager`
+(`createFromCart`, `addPayments`, `setPayments`, `addToStage`).
+
 ## Output Format
 
 When generating mutations for the user, produce: