diff --git a/.claude/skills/magic-links/SKILL.md b/.claude/skills/magic-links/SKILL.md index 839d5ad..2d39129 100644 --- a/.claude/skills/magic-links/SKILL.md +++ b/.claude/skills/magic-links/SKILL.md @@ -1,87 +1,33 @@ # Magic Links System -This project uses a build-time magic link system (adapted from surfdeeper) for semantic document linking. +Wikipedia-style links using `@sailkit/atlas`. ## Syntax -### Standard Magic Links ```markdown -[Display Text](:document-id) -[Display Text](:document-id|:fallback-id) -``` +[[context-collapse]] → [context-collapse](/concepts/context-collapse/) +[[context-collapse|Learn about context]] → [Learn about context](/concepts/context-collapse/) -Example: -```markdown -[Read about context collapse](:context-collapse) -``` - -### Learning Links (optional variant) -```markdown -[[document-id]] -[[document-id|Custom Display Text]] +[:context-collapse] → same, alternate syntax +[:context-collapse|Learn about context] → same with display text ``` -These render as auto-numbered references. +## Configuration -## How It Works - -1. Author writes `[text](:id)` in any markdown file -2. At build time, the Remark plugin scans all content collections -3. Builds a map of `id` → `slug` from frontmatter -4. Rewrites `:id` references to actual routes like `/concept/{slug}` - -## Document Frontmatter +```javascript +// astro.config.mjs +import { remarkMagicLinks } from '@sailkit/atlas'; -Each content file needs an `id` in frontmatter: - -```yaml ---- -title: Context Collapse -id: context-collapse # Used for magic link resolution -aliases: [context-loss] # Optional alternative IDs ---- +remarkPlugins: [[remarkMagicLinks, { + urlBuilder: (id) => `/concepts/${id}/`, + syntax: 'both', +}]] ``` -## Collections - -Magic links resolve across these collections: -- `concepts` → `/concept/{slug}` -- `failure-modes` → `/failure-mode/{slug}` -- `patterns` → `/pattern/{slug}` - -## Implementation Files - -If implementing this system, you need: - -1. **Remark plugin** (`scripts/remark-magic-links.mjs`): - - `buildIdMap()` - scans content directories, extracts id/slug/aliases - - Plugin function - transforms `:id` links to actual URLs - -2. **Astro config** (`astro.config.mjs`): - ```javascript - import remarkMagicLinks from "./scripts/remark-magic-links.mjs"; - - export default defineConfig({ - markdown: { - remarkPlugins: [remarkMagicLinks], - }, - }); - ``` - -3. **Validation script** (`scripts/validate-concept-ids.js`): - - Checks for duplicate IDs - - Validates all magic link references resolve - - Run with `npm run lint:links` - -## When Adding New Content - -1. Always include a unique `id` in frontmatter -2. Use kebab-case for IDs: `context-collapse`, not `contextCollapse` -3. Add `aliases` array if the concept has common alternative names -4. Run link validation before committing +## How It Works -## Error Handling +1. Write `[[some-page]]` in markdown +2. Remark plugin finds it in text nodes (not code blocks) +3. Transforms to `[some-page](/concepts/some-page/)` using `urlBuilder` -- Unresolved magic links are converted to plain text (no broken links) -- Build-time validation catches broken references -- Duplicate IDs cause validation failure +No frontmatter required. No validation. The ID is the slug. diff --git a/astro.config.mjs b/astro.config.mjs index f6e8051..8474254 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -1,6 +1,18 @@ import { defineConfig } from 'astro/config'; import mdx from '@astrojs/mdx'; +import { remarkMagicLinks } from 'sailkit/packages/atlas'; +import { createSlugResolver } from 'sailkit/packages/atlas/dist/node.js'; + +const urlBuilder = createSlugResolver('./src/content'); export default defineConfig({ integrations: [mdx()], + markdown: { + remarkPlugins: [ + [remarkMagicLinks, { + urlBuilder, + syntax: 'both', + }], + ], + }, }); diff --git a/package-lock.json b/package-lock.json index 0e24445..305beac 100644 --- a/package-lock.json +++ b/package-lock.json @@ -11,7 +11,7 @@ "dependencies": { "@astrojs/mdx": "^4.3.13", "astro": "^5.0.0", - "bearing-dev": "github:bearing-dev/bearing-dev#teleport-vim-bindings" + "sailkit": "github:sailkit-dev/sailkit#atlas-magic-links" }, "devDependencies": { "glob": "^11.0.0", @@ -178,9 +178,9 @@ } }, "node_modules/@emnapi/runtime": { - "version": "1.7.1", - "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.7.1.tgz", - "integrity": "sha512-PVtJr5CmLwYAU9PZDMITZoR5iAOShYREoR45EyyLrbntV50mdePTgUn4AmOw90Ifcj+x2kRjdzr1HP3RrNiHGA==", + "version": "1.8.0", + "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.8.0.tgz", + "integrity": "sha512-Z82FDl1ByxqPEPrAYYeTQVlx2FSHPe1qwX465c+96IRS3fTdSYRoJcRxg3g2fEG5I69z1dSEWQlNRRr0/677mg==", "license": "MIT", "optional": true, "dependencies": { @@ -1231,9 +1231,9 @@ "license": "MIT" }, "node_modules/@rollup/rollup-android-arm-eabi": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.53.5.tgz", - "integrity": "sha512-iDGS/h7D8t7tvZ1t6+WPK04KD0MwzLZrG0se1hzBjSi5fyxlsiggoJHwh18PCFNn7tG43OWb6pdZ6Y+rMlmyNQ==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.54.0.tgz", + "integrity": "sha512-OywsdRHrFvCdvsewAInDKCNyR3laPA2mc9bRYJ6LBp5IyvF3fvXbbNR0bSzHlZVFtn6E0xw2oZlyjg4rKCVcng==", "cpu": [ "arm" ], @@ -1244,9 +1244,9 @@ ] }, "node_modules/@rollup/rollup-android-arm64": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.53.5.tgz", - "integrity": "sha512-wrSAViWvZHBMMlWk6EJhvg8/rjxzyEhEdgfMMjREHEq11EtJ6IP6yfcCH57YAEca2Oe3FNCE9DSTgU70EIGmVw==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.54.0.tgz", + "integrity": "sha512-Skx39Uv+u7H224Af+bDgNinitlmHyQX1K/atIA32JP3JQw6hVODX5tkbi2zof/E69M1qH2UoN3Xdxgs90mmNYw==", "cpu": [ "arm64" ], @@ -1257,9 +1257,9 @@ ] }, "node_modules/@rollup/rollup-darwin-arm64": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.53.5.tgz", - "integrity": "sha512-S87zZPBmRO6u1YXQLwpveZm4JfPpAa6oHBX7/ghSiGH3rz/KDgAu1rKdGutV+WUI6tKDMbaBJomhnT30Y2t4VQ==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.54.0.tgz", + "integrity": "sha512-k43D4qta/+6Fq+nCDhhv9yP2HdeKeP56QrUUTW7E6PhZP1US6NDqpJj4MY0jBHlJivVJD5P8NxrjuobZBJTCRw==", "cpu": [ "arm64" ], @@ -1270,9 +1270,9 @@ ] }, "node_modules/@rollup/rollup-darwin-x64": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.53.5.tgz", - "integrity": "sha512-YTbnsAaHo6VrAczISxgpTva8EkfQus0VPEVJCEaboHtZRIb6h6j0BNxRBOwnDciFTZLDPW5r+ZBmhL/+YpTZgA==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.54.0.tgz", + "integrity": "sha512-cOo7biqwkpawslEfox5Vs8/qj83M/aZCSSNIWpVzfU2CYHa2G3P1UN5WF01RdTHSgCkri7XOlTdtk17BezlV3A==", "cpu": [ "x64" ], @@ -1283,9 +1283,9 @@ ] }, "node_modules/@rollup/rollup-freebsd-arm64": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.53.5.tgz", - "integrity": "sha512-1T8eY2J8rKJWzaznV7zedfdhD1BqVs1iqILhmHDq/bqCUZsrMt+j8VCTHhP0vdfbHK3e1IQ7VYx3jlKqwlf+vw==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.54.0.tgz", + "integrity": "sha512-miSvuFkmvFbgJ1BevMa4CPCFt5MPGw094knM64W9I0giUIMMmRYcGW/JWZDriaw/k1kOBtsWh1z6nIFV1vPNtA==", "cpu": [ "arm64" ], @@ -1296,9 +1296,9 @@ ] }, "node_modules/@rollup/rollup-freebsd-x64": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.53.5.tgz", - "integrity": "sha512-sHTiuXyBJApxRn+VFMaw1U+Qsz4kcNlxQ742snICYPrY+DDL8/ZbaC4DVIB7vgZmp3jiDaKA0WpBdP0aqPJoBQ==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.54.0.tgz", + "integrity": "sha512-KGXIs55+b/ZfZsq9aR026tmr/+7tq6VG6MsnrvF4H8VhwflTIuYh+LFUlIsRdQSgrgmtM3fVATzEAj4hBQlaqQ==", "cpu": [ "x64" ], @@ -1309,9 +1309,9 @@ ] }, "node_modules/@rollup/rollup-linux-arm-gnueabihf": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.53.5.tgz", - "integrity": "sha512-dV3T9MyAf0w8zPVLVBptVlzaXxka6xg1f16VAQmjg+4KMSTWDvhimI/Y6mp8oHwNrmnmVl9XxJ/w/mO4uIQONA==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.54.0.tgz", + "integrity": "sha512-EHMUcDwhtdRGlXZsGSIuXSYwD5kOT9NVnx9sqzYiwAc91wfYOE1g1djOEDseZJKKqtHAHGwnGPQu3kytmfaXLQ==", "cpu": [ "arm" ], @@ -1322,9 +1322,9 @@ ] }, "node_modules/@rollup/rollup-linux-arm-musleabihf": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.53.5.tgz", - "integrity": "sha512-wIGYC1x/hyjP+KAu9+ewDI+fi5XSNiUi9Bvg6KGAh2TsNMA3tSEs+Sh6jJ/r4BV/bx/CyWu2ue9kDnIdRyafcQ==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.54.0.tgz", + "integrity": "sha512-+pBrqEjaakN2ySv5RVrj/qLytYhPKEUwk+e3SFU5jTLHIcAtqh2rLrd/OkbNuHJpsBgxsD8ccJt5ga/SeG0JmA==", "cpu": [ "arm" ], @@ -1335,9 +1335,9 @@ ] }, "node_modules/@rollup/rollup-linux-arm64-gnu": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.53.5.tgz", - "integrity": "sha512-Y+qVA0D9d0y2FRNiG9oM3Hut/DgODZbU9I8pLLPwAsU0tUKZ49cyV1tzmB/qRbSzGvY8lpgGkJuMyuhH7Ma+Vg==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.54.0.tgz", + "integrity": "sha512-NSqc7rE9wuUaRBsBp5ckQ5CVz5aIRKCwsoa6WMF7G01sX3/qHUw/z4pv+D+ahL1EIKy6Enpcnz1RY8pf7bjwng==", "cpu": [ "arm64" ], @@ -1348,9 +1348,9 @@ ] }, "node_modules/@rollup/rollup-linux-arm64-musl": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.53.5.tgz", - "integrity": "sha512-juaC4bEgJsyFVfqhtGLz8mbopaWD+WeSOYr5E16y+1of6KQjc0BpwZLuxkClqY1i8sco+MdyoXPNiCkQou09+g==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.54.0.tgz", + "integrity": "sha512-gr5vDbg3Bakga5kbdpqx81m2n9IX8M6gIMlQQIXiLTNeQW6CucvuInJ91EuCJ/JYvc+rcLLsDFcfAD1K7fMofg==", "cpu": [ "arm64" ], @@ -1361,9 +1361,9 @@ ] }, "node_modules/@rollup/rollup-linux-loong64-gnu": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.53.5.tgz", - "integrity": "sha512-rIEC0hZ17A42iXtHX+EPJVL/CakHo+tT7W0pbzdAGuWOt2jxDFh7A/lRhsNHBcqL4T36+UiAgwO8pbmn3dE8wA==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.54.0.tgz", + "integrity": "sha512-gsrtB1NA3ZYj2vq0Rzkylo9ylCtW/PhpLEivlgWe0bpgtX5+9j9EZa0wtZiCjgu6zmSeZWyI/e2YRX1URozpIw==", "cpu": [ "loong64" ], @@ -1374,9 +1374,9 @@ ] }, "node_modules/@rollup/rollup-linux-ppc64-gnu": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.53.5.tgz", - "integrity": "sha512-T7l409NhUE552RcAOcmJHj3xyZ2h7vMWzcwQI0hvn5tqHh3oSoclf9WgTl+0QqffWFG8MEVZZP1/OBglKZx52Q==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.54.0.tgz", + "integrity": "sha512-y3qNOfTBStmFNq+t4s7Tmc9hW2ENtPg8FeUD/VShI7rKxNW7O4fFeaYbMsd3tpFlIg1Q8IapFgy7Q9i2BqeBvA==", "cpu": [ "ppc64" ], @@ -1387,9 +1387,9 @@ ] }, "node_modules/@rollup/rollup-linux-riscv64-gnu": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.53.5.tgz", - "integrity": "sha512-7OK5/GhxbnrMcxIFoYfhV/TkknarkYC1hqUw1wU2xUN3TVRLNT5FmBv4KkheSG2xZ6IEbRAhTooTV2+R5Tk0lQ==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.54.0.tgz", + "integrity": "sha512-89sepv7h2lIVPsFma8iwmccN7Yjjtgz0Rj/Ou6fEqg3HDhpCa+Et+YSufy27i6b0Wav69Qv4WBNl3Rs6pwhebQ==", "cpu": [ "riscv64" ], @@ -1400,9 +1400,9 @@ ] }, "node_modules/@rollup/rollup-linux-riscv64-musl": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.53.5.tgz", - "integrity": "sha512-GwuDBE/PsXaTa76lO5eLJTyr2k8QkPipAyOrs4V/KJufHCZBJ495VCGJol35grx9xryk4V+2zd3Ri+3v7NPh+w==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.54.0.tgz", + "integrity": "sha512-ZcU77ieh0M2Q8Ur7D5X7KvK+UxbXeDHwiOt/CPSBTI1fBmeDMivW0dPkdqkT4rOgDjrDDBUed9x4EgraIKoR2A==", "cpu": [ "riscv64" ], @@ -1413,9 +1413,9 @@ ] }, "node_modules/@rollup/rollup-linux-s390x-gnu": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.53.5.tgz", - "integrity": "sha512-IAE1Ziyr1qNfnmiQLHBURAD+eh/zH1pIeJjeShleII7Vj8kyEm2PF77o+lf3WTHDpNJcu4IXJxNO0Zluro8bOw==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.54.0.tgz", + "integrity": "sha512-2AdWy5RdDF5+4YfG/YesGDDtbyJlC9LHmL6rZw6FurBJ5n4vFGupsOBGfwMRjBYH7qRQowT8D/U4LoSvVwOhSQ==", "cpu": [ "s390x" ], @@ -1426,9 +1426,9 @@ ] }, "node_modules/@rollup/rollup-linux-x64-gnu": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.53.5.tgz", - "integrity": "sha512-Pg6E+oP7GvZ4XwgRJBuSXZjcqpIW3yCBhK4BcsANvb47qMvAbCjR6E+1a/U2WXz1JJxp9/4Dno3/iSJLcm5auw==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.54.0.tgz", + "integrity": "sha512-WGt5J8Ij/rvyqpFexxk3ffKqqbLf9AqrTBbWDk7ApGUzaIs6V+s2s84kAxklFwmMF/vBNGrVdYgbblCOFFezMQ==", "cpu": [ "x64" ], @@ -1439,9 +1439,9 @@ ] }, "node_modules/@rollup/rollup-linux-x64-musl": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.53.5.tgz", - "integrity": "sha512-txGtluxDKTxaMDzUduGP0wdfng24y1rygUMnmlUJ88fzCCULCLn7oE5kb2+tRB+MWq1QDZT6ObT5RrR8HFRKqg==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.54.0.tgz", + "integrity": "sha512-JzQmb38ATzHjxlPHuTH6tE7ojnMKM2kYNzt44LO/jJi8BpceEC8QuXYA908n8r3CNuG/B3BV8VR3Hi1rYtmPiw==", "cpu": [ "x64" ], @@ -1452,9 +1452,9 @@ ] }, "node_modules/@rollup/rollup-openharmony-arm64": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.53.5.tgz", - "integrity": "sha512-3DFiLPnTxiOQV993fMc+KO8zXHTcIjgaInrqlG8zDp1TlhYl6WgrOHuJkJQ6M8zHEcntSJsUp1XFZSY8C1DYbg==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.54.0.tgz", + "integrity": "sha512-huT3fd0iC7jigGh7n3q/+lfPcXxBi+om/Rs3yiFxjvSxbSB6aohDFXbWvlspaqjeOh+hx7DDHS+5Es5qRkWkZg==", "cpu": [ "arm64" ], @@ -1465,9 +1465,9 @@ ] }, "node_modules/@rollup/rollup-win32-arm64-msvc": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.53.5.tgz", - "integrity": "sha512-nggc/wPpNTgjGg75hu+Q/3i32R00Lq1B6N1DO7MCU340MRKL3WZJMjA9U4K4gzy3dkZPXm9E1Nc81FItBVGRlA==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.54.0.tgz", + "integrity": "sha512-c2V0W1bsKIKfbLMBu/WGBz6Yci8nJ/ZJdheE0EwB73N3MvHYKiKGs3mVilX4Gs70eGeDaMqEob25Tw2Gb9Nqyw==", "cpu": [ "arm64" ], @@ -1478,9 +1478,9 @@ ] }, "node_modules/@rollup/rollup-win32-ia32-msvc": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.53.5.tgz", - "integrity": "sha512-U/54pTbdQpPLBdEzCT6NBCFAfSZMvmjr0twhnD9f4EIvlm9wy3jjQ38yQj1AGznrNO65EWQMgm/QUjuIVrYF9w==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.54.0.tgz", + "integrity": "sha512-woEHgqQqDCkAzrDhvDipnSirm5vxUXtSKDYTVpZG3nUdW/VVB5VdCYA2iReSj/u3yCZzXID4kuKG7OynPnB3WQ==", "cpu": [ "ia32" ], @@ -1491,9 +1491,9 @@ ] }, "node_modules/@rollup/rollup-win32-x64-gnu": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.53.5.tgz", - "integrity": "sha512-2NqKgZSuLH9SXBBV2dWNRCZmocgSOx8OJSdpRaEcRlIfX8YrKxUT6z0F1NpvDVhOsl190UFTRh2F2WDWWCYp3A==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.54.0.tgz", + "integrity": "sha512-dzAc53LOuFvHwbCEOS0rPbXp6SIhAf2txMP5p6mGyOXXw5mWY8NGGbPMPrs4P1WItkfApDathBj/NzMLUZ9rtQ==", "cpu": [ "x64" ], @@ -1504,9 +1504,9 @@ ] }, "node_modules/@rollup/rollup-win32-x64-msvc": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.53.5.tgz", - "integrity": "sha512-JRpZUhCfhZ4keB5v0fe02gQJy05GqboPOaxvjugW04RLSYYoB/9t2lx2u/tMs/Na/1NXfY8QYjgRljRpN+MjTQ==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.54.0.tgz", + "integrity": "sha512-hYT5d3YNdSh3mbCU1gwQyPgQd3T2ne0A3KG8KSBdav5TiBg6eInVmV+TeR5uHufiIgSFg0XsOWGW5/RhNcSvPg==", "cpu": [ "x64" ], @@ -1591,9 +1591,9 @@ "license": "MIT" }, "node_modules/@swc/helpers": { - "version": "0.5.17", - "resolved": "https://registry.npmjs.org/@swc/helpers/-/helpers-0.5.17.tgz", - "integrity": "sha512-5IKx/Y13RsYd+sauPb2x+U/xZikHjolzfuDgTAl/Tdf3Q8rslRvC19NKDLgAJQ6wsqADk10ntlv08nPFw/gO/A==", + "version": "0.5.18", + "resolved": "https://registry.npmjs.org/@swc/helpers/-/helpers-0.5.18.tgz", + "integrity": "sha512-TXTnIcNJQEKwThMMqBXsZ4VGAza6bvN4pa41Rkqoio6QBKMvo+5lexeTMScGCIxtzgQJzElcvIltani+adC5PQ==", "license": "Apache-2.0", "dependencies": { "tslib": "^2.8.0" @@ -2141,13 +2141,6 @@ ], "license": "MIT" }, - "node_modules/bearing-dev": { - "version": "0.0.1", - "resolved": "git+ssh://git@github.com/bearing-dev/bearing-dev.git#44fd82018fff2be1690911fd9d60942ea66fa474", - "workspaces": [ - "packages/*" - ] - }, "node_modules/boolbase": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz", @@ -2221,9 +2214,9 @@ } }, "node_modules/chai": { - "version": "6.2.1", - "resolved": "https://registry.npmjs.org/chai/-/chai-6.2.1.tgz", - "integrity": "sha512-p4Z49OGG5W/WBCPSS/dH3jQ73kD6tiMmUM+bckNK6Jr5JHMG3k9bg/BvKR8lKmtVBKmOiuVaV2ws8s9oSbwysg==", + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz", + "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==", "dev": true, "license": "MIT", "engines": { @@ -5668,9 +5661,9 @@ "license": "MIT" }, "node_modules/rollup": { - "version": "4.53.5", - "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.53.5.tgz", - "integrity": "sha512-iTNAbFSlRpcHeeWu73ywU/8KuU/LZmNCSxp6fjQkJBD3ivUb8tpDrXhIxEzA05HlYMEwmtaUnb3RP+YNv162OQ==", + "version": "4.54.0", + "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.54.0.tgz", + "integrity": "sha512-3nk8Y3a9Ea8szgKhinMlGMhGMw89mqule3KWczxhIzqudyHdCIOHw8WJlj/r329fACjKLEh13ZSk7oE22kyeIw==", "license": "MIT", "dependencies": { "@types/estree": "1.0.8" @@ -5683,31 +5676,39 @@ "npm": ">=8.0.0" }, "optionalDependencies": { - "@rollup/rollup-android-arm-eabi": "4.53.5", - "@rollup/rollup-android-arm64": "4.53.5", - "@rollup/rollup-darwin-arm64": "4.53.5", - "@rollup/rollup-darwin-x64": "4.53.5", - "@rollup/rollup-freebsd-arm64": "4.53.5", - "@rollup/rollup-freebsd-x64": "4.53.5", - "@rollup/rollup-linux-arm-gnueabihf": "4.53.5", - "@rollup/rollup-linux-arm-musleabihf": "4.53.5", - "@rollup/rollup-linux-arm64-gnu": "4.53.5", - "@rollup/rollup-linux-arm64-musl": "4.53.5", - "@rollup/rollup-linux-loong64-gnu": "4.53.5", - "@rollup/rollup-linux-ppc64-gnu": "4.53.5", - "@rollup/rollup-linux-riscv64-gnu": "4.53.5", - "@rollup/rollup-linux-riscv64-musl": "4.53.5", - "@rollup/rollup-linux-s390x-gnu": "4.53.5", - "@rollup/rollup-linux-x64-gnu": "4.53.5", - "@rollup/rollup-linux-x64-musl": "4.53.5", - "@rollup/rollup-openharmony-arm64": "4.53.5", - "@rollup/rollup-win32-arm64-msvc": "4.53.5", - "@rollup/rollup-win32-ia32-msvc": "4.53.5", - "@rollup/rollup-win32-x64-gnu": "4.53.5", - "@rollup/rollup-win32-x64-msvc": "4.53.5", + "@rollup/rollup-android-arm-eabi": "4.54.0", + "@rollup/rollup-android-arm64": "4.54.0", + "@rollup/rollup-darwin-arm64": "4.54.0", + "@rollup/rollup-darwin-x64": "4.54.0", + "@rollup/rollup-freebsd-arm64": "4.54.0", + "@rollup/rollup-freebsd-x64": "4.54.0", + "@rollup/rollup-linux-arm-gnueabihf": "4.54.0", + "@rollup/rollup-linux-arm-musleabihf": "4.54.0", + "@rollup/rollup-linux-arm64-gnu": "4.54.0", + "@rollup/rollup-linux-arm64-musl": "4.54.0", + "@rollup/rollup-linux-loong64-gnu": "4.54.0", + "@rollup/rollup-linux-ppc64-gnu": "4.54.0", + "@rollup/rollup-linux-riscv64-gnu": "4.54.0", + "@rollup/rollup-linux-riscv64-musl": "4.54.0", + "@rollup/rollup-linux-s390x-gnu": "4.54.0", + "@rollup/rollup-linux-x64-gnu": "4.54.0", + "@rollup/rollup-linux-x64-musl": "4.54.0", + "@rollup/rollup-openharmony-arm64": "4.54.0", + "@rollup/rollup-win32-arm64-msvc": "4.54.0", + "@rollup/rollup-win32-ia32-msvc": "4.54.0", + "@rollup/rollup-win32-x64-gnu": "4.54.0", + "@rollup/rollup-win32-x64-msvc": "4.54.0", "fsevents": "~2.3.2" } }, + "node_modules/sailkit": { + "name": "bearing-dev", + "version": "0.0.1", + "resolved": "git+ssh://git@github.com/sailkit-dev/sailkit.git#ecab319b0e5d0bfbf87111112a2b41412213acf5", + "workspaces": [ + "packages/*" + ] + }, "node_modules/sax": { "version": "1.4.3", "resolved": "https://registry.npmjs.org/sax/-/sax-1.4.3.tgz", @@ -5854,9 +5855,9 @@ } }, "node_modules/smol-toml": { - "version": "1.5.2", - "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.5.2.tgz", - "integrity": "sha512-QlaZEqcAH3/RtNyet1IPIYPsEWAaYyXXv1Krsi+1L/QHppjX4Ifm8MQsBISz9vE8cHicIq3clogsheili5vhaQ==", + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.6.0.tgz", + "integrity": "sha512-4zemZi0HvTnYwLfrpk/CF9LOd9Lt87kAt50GnqhMpyF9U3poDAP2+iukq2bZsO/ufegbYehBkqINbsWxj4l4cw==", "license": "BSD-3-Clause", "engines": { "node": ">= 18" @@ -7485,9 +7486,9 @@ } }, "node_modules/zod-to-json-schema": { - "version": "3.25.0", - "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.0.tgz", - "integrity": "sha512-HvWtU2UG41LALjajJrML6uQejQhNJx+JBO9IflpSja4R03iNWfKXrj6W2h7ljuLyc1nKS+9yDyL/9tD1U/yBnQ==", + "version": "3.25.1", + "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.1.tgz", + "integrity": "sha512-pM/SU9d3YAggzi6MtR4h7ruuQlqKtad8e9S0fmxcMi+ueAK5Korys/aWcV9LIIHTVbj01NdzxcnXSN+O74ZIVA==", "license": "ISC", "peerDependencies": { "zod": "^3.25 || ^4" diff --git a/package.json b/package.json index 61f43c4..73282df 100644 --- a/package.json +++ b/package.json @@ -18,7 +18,7 @@ "dependencies": { "@astrojs/mdx": "^4.3.13", "astro": "^5.0.0", - "sailkit": "github:sailkit-dev/sailkit#main" + "sailkit": "github:sailkit-dev/sailkit#atlas-magic-links" }, "devDependencies": { "glob": "^11.0.0", diff --git a/src/content/concepts/agent-loops.md b/src/content/concepts/agent-loops.md index bcc661e..c1aa820 100644 --- a/src/content/concepts/agent-loops.md +++ b/src/content/concepts/agent-loops.md @@ -15,7 +15,7 @@ An agent runs in a loop: 4. Tool output becomes part of the context 5. Repeat until complete -Each iteration extends the [context](/concepts/context). The context accumulates information about your codebase, file states, and previous attempts. +Each iteration extends the [[context]]. The context accumulates information about your codebase, file states, and previous attempts. ## Why Tools Matter diff --git a/src/content/concepts/chat-loops.md b/src/content/concepts/chat-loops.md index 13af818..8dd13cc 100644 --- a/src/content/concepts/chat-loops.md +++ b/src/content/concepts/chat-loops.md @@ -14,10 +14,10 @@ Unlike autocomplete, chat involves multiple turns: 3. You read and respond 4. Repeat -Each exchange extends the [context](/concepts/context). The model sees the full conversation history when generating each response. +Each exchange extends the [[context]]. The model sees the full conversation history when generating each response. ## Text In, Text Out Chat generates text—code snippets, explanations, suggestions. It doesn't act on your environment. You copy the code, paste it into your editor, and run commands yourself. -[Agent loops](/concepts/agent-loops) add the ability to take actions: reading files, writing changes, running commands. Chat stays in the realm of text. +[[agent-loops|Agent loops]] add the ability to take actions: reading files, writing changes, running commands. Chat stays in the realm of text. diff --git a/src/content/concepts/context-engineering.md b/src/content/concepts/context-engineering.md index 077b72e..e25521b 100644 --- a/src/content/concepts/context-engineering.md +++ b/src/content/concepts/context-engineering.md @@ -3,7 +3,7 @@ title: Context Engineering dependsOn: large-language-models --- -A school of thought emphasizing understanding and quality. Practitioners care about architecture, read AI output carefully, and craft what goes into the [context window](/concepts/context)—system prompts, examples, constraints. +A school of thought emphasizing understanding and quality. Practitioners care about architecture, read AI output carefully, and craft what goes into the [[context|context window]]—system prompts, examples, constraints. ## Example: Fixing a Layout Bug @@ -23,4 +23,4 @@ You've done the diagnostic work. The AI receives mechanical instructions rather This approach takes more upfront effort. You need to understand your codebase and investigate issues yourself. But you get predictable results and maintain control over the solution. -Often contrasted with [vibe coding](/concepts/vibe-coding), but they're not mutually exclusive. Some people switch between modes depending on the task. +Often contrasted with [[vibe-coding|vibe coding]], but they're not mutually exclusive. Some people switch between modes depending on the task. diff --git a/src/content/concepts/context.md b/src/content/concepts/context.md index 14f7ddf..c9b0468 100644 --- a/src/content/concepts/context.md +++ b/src/content/concepts/context.md @@ -7,14 +7,14 @@ The context window is finite. Everything the AI knows about your conversation ha ## What's in the Context Window? -- [System prompt](/patterns/system-prompts) -- [Tools](/concepts/tools) (file ops, terminal, LSP, search) +- [[system-prompts|System prompt]] +- [[tool-calling|Tools]] (file ops, terminal, LSP, search) - MCP servers you've connected -- [Skills](/patterns/skills) loaded on startup +- [[skills]] loaded on startup - Conversation history (messages, tool calls, results) ## Why This Matters -As context fills up, signal competes with noise. Important details get buried. See [context collapse](/failure-modes/context-collapse). +As context fills up, signal competes with noise. Important details get buried. See [[context-collapse|context collapse]]. -Context from one domain can also contaminate another. See [context contamination](/failure-modes/context-contamination). +Context from one domain can also contaminate another. See [[context-contamination|context contamination]]. diff --git a/src/content/concepts/vibe-coding.md b/src/content/concepts/vibe-coding.md index 9c77fa7..a3cf3ce 100644 --- a/src/content/concepts/vibe-coding.md +++ b/src/content/concepts/vibe-coding.md @@ -32,4 +32,4 @@ Vibe coding isn't wrong—it's a trade-off. It works well when: The risk is accumulating fixes-on-fixes that you don't fully understand. -Often contrasted with [context engineering](/concepts/context-engineering), but they're not mutually exclusive. Some people switch between modes depending on the task. +Often contrasted with [[context-engineering|context engineering]], but they're not mutually exclusive. Some people switch between modes depending on the task. diff --git a/src/content/context-management/checking-context.mdx b/src/content/context-management/checking-context.mdx index 09ec6d1..3a460a9 100644 --- a/src/content/context-management/checking-context.mdx +++ b/src/content/context-management/checking-context.mdx @@ -36,10 +36,10 @@ In Claude Code, the `/context` command shows exactly what's consuming context: - **Free space**: Room for more conversation - **Autocompact buffer**: Reserved space for automatic compaction -In this example, after a mistake that generated noise, the context was 57% full. The breakdown revealed accumulated message tokens from failed attempts—a signal that [clearing](/context-management/clear) would produce better results than continuing. +In this example, after a mistake that generated noise, the context was 57% full. The breakdown revealed accumulated message tokens from failed attempts—a signal that [[clear|clearing]] would produce better results than continuing. ## Why It Matters The model responds to what's in context, not what you intended to put there. Checking context closes the gap between "what I think the model sees" and "what the model actually sees." -This is particularly useful before [clearing](/context-management/clear) or [compacting](/context-management/compact)—you can verify whether context is salvageable or too polluted to work with. +This is particularly useful before [[clear|clearing]] or [[compact|compacting]]—you can verify whether context is salvageable or too polluted to work with. diff --git a/src/content/context-management/clear.md b/src/content/context-management/clear.md index 9920834..cff91f9 100644 --- a/src/content/context-management/clear.md +++ b/src/content/context-management/clear.md @@ -5,8 +5,8 @@ dependsOn: checking-context Clears the entire conversation and starts from scratch. Everything in the context window is gone—summaries, code references, prior decisions, all of it. -Useful when context gets too polluted to salvage—[spiraling](/failure-modes/spiraling) loops, [context collapse](/failure-modes/context-collapse), or accumulated noise from failed attempts. +Useful when context gets too polluted to salvage—[[spiraling]] loops, [[context-collapse|context collapse]], or accumulated noise from failed attempts. -Also useful proactively between discrete tasks. Write an article, clear, write another. Prevents [context contamination](/failure-modes/context-contamination) where unrelated work bleeds together. +Also useful proactively between discrete tasks. Write an article, clear, write another. Prevents [[context-contamination|context contamination]] where unrelated work bleeds together. -[Rewinding](/context-management/rewinding) is less drastic when only recent context went wrong. +[[rewinding|Rewinding]] is less drastic when only recent context went wrong. diff --git a/src/content/context-management/compact.md b/src/content/context-management/compact.md index 9fb02a7..9e4f12e 100644 --- a/src/content/context-management/compact.md +++ b/src/content/context-management/compact.md @@ -3,7 +3,7 @@ title: Compact dependsOn: clear --- -[Clearing](/context-management/clear) loses everything. Compacting preserves a summary. +[[clear|Clearing]] loses everything. Compacting preserves a summary. ## How It Works diff --git a/src/content/context-management/rewinding.md b/src/content/context-management/rewinding.md index c4d8a13..8bc065e 100644 --- a/src/content/context-management/rewinding.md +++ b/src/content/context-management/rewinding.md @@ -30,9 +30,9 @@ Source control provides another layer. If changes were already written to files, ## Rewind vs. Stop vs. Clear -[Stop](/context-management/stop) prevents bad context from forming. Rewinding removes it after the fact. +[[stop|Stop]] prevents bad context from forming. Rewinding removes it after the fact. -[Clear](/context-management/clear) starts fresh. You lose everything. +[[clear|Clear]] starts fresh. You lose everything. Rewinding keeps good context and removes bad context. You preserve the useful setup work while discarding the wrong turn. diff --git a/src/content/context-management/stop.md b/src/content/context-management/stop.md index 5334fc8..689c046 100644 --- a/src/content/context-management/stop.md +++ b/src/content/context-management/stop.md @@ -15,13 +15,13 @@ Interrupt generation before the AI finishes. The partial output stays in context ## Stop vs. Rewind -Stop prevents bad context from forming. [Rewind](/context-management/rewinding) removes bad context after the fact. +Stop prevents bad context from forming. [[rewinding|Rewind]] removes bad context after the fact. Stopping is faster—you intervene in real-time. But you have to be watching. Rewinding works when you notice the problem later. ## Stop and Steer -Stop pairs naturally with [steering](/workflow-guardrails/steering). Stop halts the wrong direction. Steering redirects toward the right one. +Stop pairs naturally with [[steering]]. Stop halts the wrong direction. Steering redirects toward the right one. The sequence: stop generation, then send a follow-up message that clarifies what you actually want. The AI resumes with your correction as the most recent context. @@ -32,7 +32,7 @@ Without the stop, your steering message competes with whatever the AI just produ When you stop mid-generation, you get a partial response. This might be: - **Usable as-is** - You stopped at the right moment -- **Incomplete but salvageable** - Copy what you need, then [clear](/context-management/clear) or [rewind](/context-management/rewinding) +- **Incomplete but salvageable** - Copy what you need, then [[clear]] or [[rewinding|rewind]] - **Garbage** - Rewind to before the partial output The partial output is now in context either way. If it's not useful, remove it. diff --git a/src/content/failure-modes/context-contamination.md b/src/content/failure-modes/context-contamination.md index 8c99102..adb389f 100644 --- a/src/content/failure-modes/context-contamination.md +++ b/src/content/failure-modes/context-contamination.md @@ -4,7 +4,7 @@ relatesTo: - context-collapse --- -The AI applies [context](/concepts/context) from one domain where it doesn't belong. +The AI applies [[context]] from one domain where it doesn't belong. ## Symptoms @@ -21,7 +21,7 @@ The AI doesn't know what to forget. It sees the full conversation and draws conn ## Example: Batch Writing Articles -It's tempting to write articles one after another in a chain. You're in the zone. Clearing context and reloading [skills](/context-expanding/skills) for each piece feels like friction. +It's tempting to write articles one after another in a chain. You're in the zone. Clearing context and reloading [[skills]] for each piece feels like friction. But articles written this way tend to blur. They cluster by *when* you wrote them, not by *what* they cover. An article about testing might accidentally echo language from the authentication article you wrote 20 minutes earlier. diff --git a/src/content/failure-modes/stochastic-noise.md b/src/content/failure-modes/stochastic-noise.md index b8382fe..68a603e 100644 --- a/src/content/failure-modes/stochastic-noise.md +++ b/src/content/failure-modes/stochastic-noise.md @@ -21,7 +21,7 @@ LLMs sample from probability distributions. When uncertain, they don't pause—t ## The Damage -Every speculative action adds to the context. Code changes pile up. Files multiply. The original problem gets buried under "attempts." Even if individual actions are harmless, the cumulative noise causes [context collapse](/failure-modes/context-collapse). +Every speculative action adds to the context. Code changes pile up. Files multiply. The original problem gets buried under "attempts." Even if individual actions are harmless, the cumulative noise causes [[context-collapse|context collapse]]. ## Mitigation diff --git a/src/content/prompt-engineering/adversarial-prompting.md b/src/content/prompt-engineering/adversarial-prompting.md index 4daa7cd..fb5a367 100644 --- a/src/content/prompt-engineering/adversarial-prompting.md +++ b/src/content/prompt-engineering/adversarial-prompting.md @@ -18,6 +18,6 @@ The key is removing collaborative framing. When you clear context and prompt wit ## The Pattern 1. Complete the initial work (write code, generate tests, etc.) -2. [Clear](/context-management/clear) the context or switch models +2. [[clear|Clear]] the context or switch models 3. Prompt with an adversarial frame ("find issues", "break this", "what would fail") 4. Use the critical output to improve the original work