@slats/claude-assets-sync 0.0.5 → 0.0.6

package/dist/core/constants.d.ts

@@ -22,7 +22,7 @@ export declare const META_FILES: {
  * Schema versions for metadata files
  */
 export declare const SCHEMA_VERSIONS: {
-    readonly UNIFIED_SYNC_META: "0.0.5";
+    readonly UNIFIED_SYNC_META: "0.0.6";
     readonly LEGACY_SYNC_META: "1.0.0";
     readonly SKILL_UNIT_FORMAT: "2";
 };

package/dist/core/localSource.cjs

@@ -0,0 +1,112 @@
+'use strict';
+
+var fs = require('node:fs');
+var path = require('node:path');
+
+const canUseLocalSource = (packageName, requestedVersion, assetPath, cwd) => {
+    const docsPath = path.join(cwd, 'node_modules', packageName, assetPath);
+    if (!fs.existsSync(docsPath)) {
+        return { available: false, reason: `Local docs path not found: ${docsPath}` };
+    }
+    try {
+        const pkgJsonPath = path.join(cwd, 'node_modules', packageName, 'package.json');
+        const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+        if (pkgJson.version !== requestedVersion) {
+            return {
+                available: false,
+                reason: `Version mismatch: installed=${pkgJson.version}, requested=${requestedVersion}`,
+            };
+        }
+    }
+    catch {
+        return { available: false, reason: 'Failed to read package.json from node_modules' };
+    }
+    return { available: true, docsPath };
+};
+const fetchLocalDirectoryContents = (dirPath) => {
+    if (!fs.existsSync(dirPath))
+        return null;
+    try {
+        const entries = fs.readdirSync(dirPath);
+        const result = [];
+        for (const name of entries) {
+            const fullPath = path.join(dirPath, name);
+            const stat = fs.statSync(fullPath);
+            if (stat.isDirectory()) {
+                result.push({
+                    name,
+                    path: fullPath,
+                    type: 'dir',
+                    download_url: null,
+                    sha: '',
+                });
+            }
+            else if (stat.isFile() && name.endsWith('.md')) {
+                result.push({
+                    name,
+                    path: fullPath,
+                    type: 'file',
+                    download_url: null,
+                    sha: '',
+                });
+            }
+        }
+        return result;
+    }
+    catch {
+        return null;
+    }
+};
+const expandLocalDirectoryEntries = (dirPath, entries, prefix = '') => {
+    const result = [];
+    for (const entry of entries) {
+        const entryPrefix = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.type === 'file') {
+            result.push({
+                ...entry,
+                name: prefix ? entryPrefix : entry.name,
+            });
+        }
+        else if (entry.type === 'dir') {
+            const subDirPath = path.join(dirPath, entry.name);
+            const subEntries = fetchLocalDirectoryContents(subDirPath);
+            if (subEntries) {
+                const expanded = expandLocalDirectoryEntries(subDirPath, subEntries, entryPrefix);
+                result.push(...expanded);
+            }
+        }
+    }
+    return result;
+};
+const fetchLocalAssetFiles = async (docsBasePath, assetTypes) => {
+    const assetFiles = {};
+    for (const assetType of assetTypes) {
+        const assetDirPath = path.join(docsBasePath, assetType);
+        const entries = fetchLocalDirectoryContents(assetDirPath);
+        if (!entries) {
+            assetFiles[assetType] = [];
+            continue;
+        }
+        assetFiles[assetType] = expandLocalDirectoryEntries(assetDirPath, entries);
+    }
+    return assetFiles;
+};
+const downloadLocalAssetFiles = async (docsBasePath, assetType, entries) => {
+    const results = new Map();
+    for (const entry of entries) {
+        const filePath = path.join(docsBasePath, assetType, entry.name);
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            results.set(entry.name, content);
+        }
+        catch {
+        }
+    }
+    return results;
+};
+
+exports.canUseLocalSource = canUseLocalSource;
+exports.downloadLocalAssetFiles = downloadLocalAssetFiles;
+exports.expandLocalDirectoryEntries = expandLocalDirectoryEntries;
+exports.fetchLocalAssetFiles = fetchLocalAssetFiles;
+exports.fetchLocalDirectoryContents = fetchLocalDirectoryContents;

package/dist/core/localSource.d.ts

@@ -0,0 +1,33 @@
+import type { AssetType, GitHubEntry } from '../utils/types.js';
+export interface LocalSourceResult {
+    available: boolean;
+    docsPath?: string;
+    reason?: string;
+}
+/**
+ * Check if local docs source is available in node_modules.
+ * Returns available=true if:
+ * 1. node_modules/<packageName>/<assetPath> directory exists
+ * 2. Installed version matches requestedVersion
+ */
+export declare const canUseLocalSource: (packageName: string, requestedVersion: string, assetPath: string, cwd: string) => LocalSourceResult;
+/**
+ * Read directory contents and return .md files and subdirs in GitHubEntry format.
+ * Returns null if the directory doesn't exist.
+ */
+export declare const fetchLocalDirectoryContents: (dirPath: string) => GitHubEntry[] | null;
+/**
+ * Recursively expand directory entries into flat file entries with path prefixes.
+ * Mirrors github.ts expandDirectoryEntries behaviour but reads from local filesystem.
+ */
+export declare const expandLocalDirectoryEntries: (dirPath: string, entries: GitHubEntry[], prefix?: string) => GitHubEntry[];
+/**
+ * Fetch asset files from local filesystem.
+ * Mirrors github.ts fetchAssetFiles but reads from node_modules instead of GitHub API.
+ */
+export declare const fetchLocalAssetFiles: (docsBasePath: string, assetTypes: string[]) => Promise<Record<string, GitHubEntry[]>>;
+/**
+ * Read file contents from local filesystem for the given entries.
+ * Mirrors github.ts downloadAssetFiles but reads local files instead of HTTP requests.
+ */
+export declare const downloadLocalAssetFiles: (docsBasePath: string, assetType: AssetType, entries: GitHubEntry[]) => Promise<Map<string, string>>;

package/dist/core/localSource.mjs

@@ -0,0 +1,106 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const canUseLocalSource = (packageName, requestedVersion, assetPath, cwd) => {
+    const docsPath = join(cwd, 'node_modules', packageName, assetPath);
+    if (!existsSync(docsPath)) {
+        return { available: false, reason: `Local docs path not found: ${docsPath}` };
+    }
+    try {
+        const pkgJsonPath = join(cwd, 'node_modules', packageName, 'package.json');
+        const pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+        if (pkgJson.version !== requestedVersion) {
+            return {
+                available: false,
+                reason: `Version mismatch: installed=${pkgJson.version}, requested=${requestedVersion}`,
+            };
+        }
+    }
+    catch {
+        return { available: false, reason: 'Failed to read package.json from node_modules' };
+    }
+    return { available: true, docsPath };
+};
+const fetchLocalDirectoryContents = (dirPath) => {
+    if (!existsSync(dirPath))
+        return null;
+    try {
+        const entries = readdirSync(dirPath);
+        const result = [];
+        for (const name of entries) {
+            const fullPath = join(dirPath, name);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                result.push({
+                    name,
+                    path: fullPath,
+                    type: 'dir',
+                    download_url: null,
+                    sha: '',
+                });
+            }
+            else if (stat.isFile() && name.endsWith('.md')) {
+                result.push({
+                    name,
+                    path: fullPath,
+                    type: 'file',
+                    download_url: null,
+                    sha: '',
+                });
+            }
+        }
+        return result;
+    }
+    catch {
+        return null;
+    }
+};
+const expandLocalDirectoryEntries = (dirPath, entries, prefix = '') => {
+    const result = [];
+    for (const entry of entries) {
+        const entryPrefix = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.type === 'file') {
+            result.push({
+                ...entry,
+                name: prefix ? entryPrefix : entry.name,
+            });
+        }
+        else if (entry.type === 'dir') {
+            const subDirPath = join(dirPath, entry.name);
+            const subEntries = fetchLocalDirectoryContents(subDirPath);
+            if (subEntries) {
+                const expanded = expandLocalDirectoryEntries(subDirPath, subEntries, entryPrefix);
+                result.push(...expanded);
+            }
+        }
+    }
+    return result;
+};
+const fetchLocalAssetFiles = async (docsBasePath, assetTypes) => {
+    const assetFiles = {};
+    for (const assetType of assetTypes) {
+        const assetDirPath = join(docsBasePath, assetType);
+        const entries = fetchLocalDirectoryContents(assetDirPath);
+        if (!entries) {
+            assetFiles[assetType] = [];
+            continue;
+        }
+        assetFiles[assetType] = expandLocalDirectoryEntries(assetDirPath, entries);
+    }
+    return assetFiles;
+};
+const downloadLocalAssetFiles = async (docsBasePath, assetType, entries) => {
+    const results = new Map();
+    for (const entry of entries) {
+        const filePath = join(docsBasePath, assetType, entry.name);
+        try {
+            const content = readFileSync(filePath, 'utf-8');
+            results.set(entry.name, content);
+        }
+        catch {
+        }
+    }
+    return results;
+};
+
+export { canUseLocalSource, downloadLocalAssetFiles, expandLocalDirectoryEntries, fetchLocalAssetFiles, fetchLocalDirectoryContents };

package/dist/core/packageScanner.cjs

@@ -65,6 +65,24 @@ async function scanRemoteAssets(packageName, ref) {
     if (!pkgInfo || !pkgInfo.claude?.assetPath) {
         throw new Error(`Package ${packageName} has no claude.assetPath configured`);
     }
+    const assetBasePath = pkgInfo.claude.assetPath;
+    if (!ref) {
+        const localDocsPath = path.join(nodeModulesPath, assetBasePath);
+        if (fs.existsSync(localDocsPath)) {
+            const trees = [];
+            for (const assetType of constants.DEFAULT_ASSET_TYPES) {
+                const assetDir = path.join(localDocsPath, assetType);
+                if (!fs.existsSync(assetDir))
+                    continue;
+                const tree = buildTreeFromLocalDir(assetType, assetDir, assetType);
+                if (tree.children && tree.children.length > 0) {
+                    trees.push(tree);
+                }
+            }
+            if (trees.length > 0)
+                return trees;
+        }
+    }
     if (!pkgInfo.repository) {
         throw new Error(`Package ${packageName} has no repository field`);
     }
@@ -72,7 +90,6 @@ async function scanRemoteAssets(packageName, ref) {
     if (!repoInfo) {
         throw new Error(`Invalid GitHub repository URL in package ${packageName}`);
     }
-    const assetBasePath = pkgInfo.claude.assetPath;
     const tag = ref ?? 'HEAD';
     const trees = [];
     for (const assetType of constants.DEFAULT_ASSET_TYPES) {

package/dist/core/packageScanner.mjs

@@ -63,6 +63,24 @@ async function scanRemoteAssets(packageName, ref) {
     if (!pkgInfo || !pkgInfo.claude?.assetPath) {
         throw new Error(`Package ${packageName} has no claude.assetPath configured`);
     }
+    const assetBasePath = pkgInfo.claude.assetPath;
+    if (!ref) {
+        const localDocsPath = join(nodeModulesPath, assetBasePath);
+        if (existsSync(localDocsPath)) {
+            const trees = [];
+            for (const assetType of DEFAULT_ASSET_TYPES) {
+                const assetDir = join(localDocsPath, assetType);
+                if (!existsSync(assetDir))
+                    continue;
+                const tree = buildTreeFromLocalDir(assetType, assetDir, assetType);
+                if (tree.children && tree.children.length > 0) {
+                    trees.push(tree);
+                }
+            }
+            if (trees.length > 0)
+                return trees;
+        }
+    }
     if (!pkgInfo.repository) {
         throw new Error(`Package ${packageName} has no repository field`);
     }
@@ -70,7 +88,6 @@ async function scanRemoteAssets(packageName, ref) {
     if (!repoInfo) {
         throw new Error(`Invalid GitHub repository URL in package ${packageName}`);
     }
-    const assetBasePath = pkgInfo.claude.assetPath;
     const tag = ref ?? 'HEAD';
     const trees = [];
     for (const assetType of DEFAULT_ASSET_TYPES) {

package/dist/core/sync.cjs

@@ -7,6 +7,7 @@ var packageName = require('../utils/packageName.cjs');
 var paths = require('../utils/paths.cjs');
 var filesystem = require('./filesystem.cjs');
 var github = require('./github.cjs');
+var localSource = require('./localSource.cjs');
 var syncMeta = require('./syncMeta.cjs');
 var constants = require('./constants.cjs');
 var assetStructure = require('./assetStructure.cjs');
@@ -67,14 +68,6 @@ const syncPackage = async (packageName$1, options, cwd = process.cwd(), exclusio
                 reason: 'Package does not have claude.assetPath in package.json',
             };
         const repoInfo = _package.parseGitHubRepo(packageInfo.repository);
-        if (!repoInfo) {
-            return {
-                packageName: packageName$1,
-                success: false,
-                skipped: true,
-                reason: 'Unable to parse GitHub repository URL',
-            };
-        }
         const useFlat = options.flat !== false;
         if (useFlat) {
             const prefix = packageName.packageNameToPrefix(packageName$1);
@@ -88,11 +81,32 @@ const syncPackage = async (packageName$1, options, cwd = process.cwd(), exclusio
                     reason: `Already synced at version ${packageInfo.version}`,
                 };
             }
-            const tag = options.ref ?? _package.buildVersionTag(packageName$1, packageInfo.version);
             const assetPath = _package.buildAssetPath(packageInfo.claude.assetPath);
-            logger.logger.step('Fetching', `asset list from GitHub (ref: ${tag})`);
+            const useLocalSource = options.ref
+                ? { available: false }
+                : localSource.canUseLocalSource(packageName$1, packageInfo.version, assetPath, cwd);
             const assetTypes = _package.getAssetTypes(packageInfo.claude);
-            const assetFiles = await github.fetchAssetFiles(repoInfo, assetPath, tag, assetTypes);
+            let assetFiles;
+            let isLocalSource;
+            if (useLocalSource.available && useLocalSource.docsPath) {
+                isLocalSource = true;
+                logger.logger.step('Using', 'local docs from node_modules');
+                assetFiles = await localSource.fetchLocalAssetFiles(useLocalSource.docsPath, assetTypes);
+            }
+            else {
+                if (!repoInfo) {
+                    return {
+                        packageName: packageName$1,
+                        success: false,
+                        skipped: true,
+                        reason: `Package ${packageName$1} has no valid GitHub repository URL for remote fetch`,
+                    };
+                }
+                isLocalSource = false;
+                const tag = options.ref ?? _package.buildVersionTag(packageName$1, packageInfo.version);
+                logger.logger.step('Fetching', `asset list from GitHub (ref: ${tag})`);
+                assetFiles = await github.fetchAssetFiles(repoInfo, assetPath, tag, assetTypes);
+            }
             let totalFiles = 0;
             for (const assetType of assetTypes) {
                 totalFiles += (assetFiles[assetType] || []).length;
@@ -189,7 +203,14 @@ const syncPackage = async (packageName$1, options, cwd = process.cwd(), exclusio
                     continue;
                 const structure = assetStructure.getAssetStructure(assetType, packageInfo.claude);
                 logger.logger.step('Downloading', assetType);
-                const downloadedFiles = await github.downloadAssetFiles(repoInfo, assetPath, assetType, filteredEntries, tag);
+                let downloadedFiles;
+                if (isLocalSource && useLocalSource.docsPath) {
+                    downloadedFiles = await localSource.downloadLocalAssetFiles(useLocalSource.docsPath, assetType, filteredEntries);
+                }
+                else {
+                    const tag = options.ref ?? _package.buildVersionTag(packageName$1, packageInfo.version);
+                    downloadedFiles = await github.downloadAssetFiles(repoInfo, assetPath, assetType, filteredEntries, tag);
+                }
                 if (structure === 'nested') {
                     for (const [fileName, content] of downloadedFiles) {
                         filesystem.writeAssetFile(destDir, packageName$1, assetType, fileName, content);
@@ -231,11 +252,32 @@ const syncPackage = async (packageName$1, options, cwd = process.cwd(), exclusio
             };
         }
         else {
-            const tag = options.ref ?? _package.buildVersionTag(packageName$1, packageInfo.version);
             const assetPath = _package.buildAssetPath(packageInfo.claude.assetPath);
-            logger.logger.step('Fetching', `asset list from GitHub (ref: ${tag})`);
+            const useLocalSource = options.ref
+                ? { available: false }
+                : localSource.canUseLocalSource(packageName$1, packageInfo.version, assetPath, cwd);
             const assetTypes = _package.getAssetTypes(packageInfo.claude);
-            const assetFiles = await github.fetchAssetFiles(repoInfo, assetPath, tag, assetTypes);
+            let assetFiles;
+            let isLocalSource;
+            if (useLocalSource.available && useLocalSource.docsPath) {
+                isLocalSource = true;
+                logger.logger.step('Using', 'local docs from node_modules');
+                assetFiles = await localSource.fetchLocalAssetFiles(useLocalSource.docsPath, assetTypes);
+            }
+            else {
+                if (!repoInfo) {
+                    return {
+                        packageName: packageName$1,
+                        success: false,
+                        skipped: true,
+                        reason: `Package ${packageName$1} has no valid GitHub repository URL for remote fetch`,
+                    };
+                }
+                isLocalSource = false;
+                const tag = options.ref ?? _package.buildVersionTag(packageName$1, packageInfo.version);
+                logger.logger.step('Fetching', `asset list from GitHub (ref: ${tag})`);
+                assetFiles = await github.fetchAssetFiles(repoInfo, assetPath, tag, assetTypes);
+            }
             let totalFiles = 0;
             for (const assetType of assetTypes) {
                 totalFiles += (assetFiles[assetType] || []).length;
@@ -299,7 +341,14 @@ const syncPackage = async (packageName$1, options, cwd = process.cwd(), exclusio
                 if (filteredEntries.length === 0)
                     continue;
                 logger.logger.step('Downloading', assetType);
-                const downloadedFiles = await github.downloadAssetFiles(repoInfo, assetPath, assetType, filteredEntries, tag);
+                let downloadedFiles;
+                if (isLocalSource && useLocalSource.docsPath) {
+                    downloadedFiles = await localSource.downloadLocalAssetFiles(useLocalSource.docsPath, assetType, filteredEntries);
+                }
+                else {
+                    const tag = options.ref ?? _package.buildVersionTag(packageName$1, packageInfo.version);
+                    downloadedFiles = await github.downloadAssetFiles(repoInfo, assetPath, assetType, filteredEntries, tag);
+                }
                 filesystem.cleanAssetDir(destDir, packageName$1, assetType);
                 syncedFiles[assetType] = [];
                 for (const [fileName, content] of downloadedFiles) {

package/dist/core/sync.mjs

@@ -1,10 +1,11 @@
 import { logger } from '../utils/logger.mjs';
 import { toFlatFileName } from '../utils/nameTransform.mjs';
-import { findGitRoot, readLocalPackageJson, readPackageJson, parseGitHubRepo, buildVersionTag, buildAssetPath, getAssetTypes } from '../utils/package.mjs';
+import { findGitRoot, readLocalPackageJson, readPackageJson, parseGitHubRepo, buildAssetPath, getAssetTypes, buildVersionTag } from '../utils/package.mjs';
 import { packageNameToPrefix } from '../utils/packageName.mjs';
 import { getDestinationDir, getFlatDestinationDir } from '../utils/paths.mjs';
 import { cleanAssetDir, cleanFlatAssetFiles, writeAssetFile, writeFlatAssetFile, needsSync, writeSyncMeta, createSyncMeta } from './filesystem.mjs';
 import { fetchAssetFiles, downloadAssetFiles, RateLimitError } from './github.mjs';
+import { canUseLocalSource, fetchLocalAssetFiles, downloadLocalAssetFiles } from './localSource.mjs';
 import { readUnifiedSyncMeta, createEmptyUnifiedMeta, needsSyncUnified, updatePackageInMeta, writeUnifiedSyncMeta } from './syncMeta.mjs';
 import { SCHEMA_VERSIONS } from './constants.mjs';
 import { getAssetStructure } from './assetStructure.mjs';
@@ -65,14 +66,6 @@ const syncPackage = async (packageName, options, cwd = process.cwd(), exclusions
                 reason: 'Package does not have claude.assetPath in package.json',
             };
         const repoInfo = parseGitHubRepo(packageInfo.repository);
-        if (!repoInfo) {
-            return {
-                packageName,
-                success: false,
-                skipped: true,
-                reason: 'Unable to parse GitHub repository URL',
-            };
-        }
         const useFlat = options.flat !== false;
         if (useFlat) {
             const prefix = packageNameToPrefix(packageName);
@@ -86,11 +79,32 @@ const syncPackage = async (packageName, options, cwd = process.cwd(), exclusions
                     reason: `Already synced at version ${packageInfo.version}`,
                 };
             }
-            const tag = options.ref ?? buildVersionTag(packageName, packageInfo.version);
             const assetPath = buildAssetPath(packageInfo.claude.assetPath);
-            logger.step('Fetching', `asset list from GitHub (ref: ${tag})`);
+            const useLocalSource = options.ref
+                ? { available: false }
+                : canUseLocalSource(packageName, packageInfo.version, assetPath, cwd);
             const assetTypes = getAssetTypes(packageInfo.claude);
-            const assetFiles = await fetchAssetFiles(repoInfo, assetPath, tag, assetTypes);
+            let assetFiles;
+            let isLocalSource;
+            if (useLocalSource.available && useLocalSource.docsPath) {
+                isLocalSource = true;
+                logger.step('Using', 'local docs from node_modules');
+                assetFiles = await fetchLocalAssetFiles(useLocalSource.docsPath, assetTypes);
+            }
+            else {
+                if (!repoInfo) {
+                    return {
+                        packageName,
+                        success: false,
+                        skipped: true,
+                        reason: `Package ${packageName} has no valid GitHub repository URL for remote fetch`,
+                    };
+                }
+                isLocalSource = false;
+                const tag = options.ref ?? buildVersionTag(packageName, packageInfo.version);
+                logger.step('Fetching', `asset list from GitHub (ref: ${tag})`);
+                assetFiles = await fetchAssetFiles(repoInfo, assetPath, tag, assetTypes);
+            }
             let totalFiles = 0;
             for (const assetType of assetTypes) {
                 totalFiles += (assetFiles[assetType] || []).length;
@@ -187,7 +201,14 @@ const syncPackage = async (packageName, options, cwd = process.cwd(), exclusions
                     continue;
                 const structure = getAssetStructure(assetType, packageInfo.claude);
                 logger.step('Downloading', assetType);
-                const downloadedFiles = await downloadAssetFiles(repoInfo, assetPath, assetType, filteredEntries, tag);
+                let downloadedFiles;
+                if (isLocalSource && useLocalSource.docsPath) {
+                    downloadedFiles = await downloadLocalAssetFiles(useLocalSource.docsPath, assetType, filteredEntries);
+                }
+                else {
+                    const tag = options.ref ?? buildVersionTag(packageName, packageInfo.version);
+                    downloadedFiles = await downloadAssetFiles(repoInfo, assetPath, assetType, filteredEntries, tag);
+                }
                 if (structure === 'nested') {
                     for (const [fileName, content] of downloadedFiles) {
                         writeAssetFile(destDir, packageName, assetType, fileName, content);
@@ -229,11 +250,32 @@ const syncPackage = async (packageName, options, cwd = process.cwd(), exclusions
             };
         }
         else {
-            const tag = options.ref ?? buildVersionTag(packageName, packageInfo.version);
             const assetPath = buildAssetPath(packageInfo.claude.assetPath);
-            logger.step('Fetching', `asset list from GitHub (ref: ${tag})`);
+            const useLocalSource = options.ref
+                ? { available: false }
+                : canUseLocalSource(packageName, packageInfo.version, assetPath, cwd);
             const assetTypes = getAssetTypes(packageInfo.claude);
-            const assetFiles = await fetchAssetFiles(repoInfo, assetPath, tag, assetTypes);
+            let assetFiles;
+            let isLocalSource;
+            if (useLocalSource.available && useLocalSource.docsPath) {
+                isLocalSource = true;
+                logger.step('Using', 'local docs from node_modules');
+                assetFiles = await fetchLocalAssetFiles(useLocalSource.docsPath, assetTypes);
+            }
+            else {
+                if (!repoInfo) {
+                    return {
+                        packageName,
+                        success: false,
+                        skipped: true,
+                        reason: `Package ${packageName} has no valid GitHub repository URL for remote fetch`,
+                    };
+                }
+                isLocalSource = false;
+                const tag = options.ref ?? buildVersionTag(packageName, packageInfo.version);
+                logger.step('Fetching', `asset list from GitHub (ref: ${tag})`);
+                assetFiles = await fetchAssetFiles(repoInfo, assetPath, tag, assetTypes);
+            }
             let totalFiles = 0;
             for (const assetType of assetTypes) {
                 totalFiles += (assetFiles[assetType] || []).length;
@@ -297,7 +339,14 @@ const syncPackage = async (packageName, options, cwd = process.cwd(), exclusions
                 if (filteredEntries.length === 0)
                     continue;
                 logger.step('Downloading', assetType);
-                const downloadedFiles = await downloadAssetFiles(repoInfo, assetPath, assetType, filteredEntries, tag);
+                let downloadedFiles;
+                if (isLocalSource && useLocalSource.docsPath) {
+                    downloadedFiles = await downloadLocalAssetFiles(useLocalSource.docsPath, assetType, filteredEntries);
+                }
+                else {
+                    const tag = options.ref ?? buildVersionTag(packageName, packageInfo.version);
+                    downloadedFiles = await downloadAssetFiles(repoInfo, assetPath, assetType, filteredEntries, tag);
+                }
                 cleanAssetDir(destDir, packageName, assetType);
                 syncedFiles[assetType] = [];
                 for (const [fileName, content] of downloadedFiles) {

package/dist/core/syncMeta.d.ts

@@ -2,7 +2,7 @@ import type { PackageSyncInfo, SkillUnit, UnifiedSyncMeta } from '../utils/types
 /**
  * Schema version for the unified metadata format
  */
-export declare const SCHEMA_VERSION: "0.0.5";
+export declare const SCHEMA_VERSION: "0.0.6";
 /**
  * Read unified sync metadata from .claude/.sync-meta.json
  *

package/dist/version.cjs

@@ -1,5 +1,5 @@
 'use strict';
 
-const VERSION = '0.0.5';
+const VERSION = '0.0.6';
 
 exports.VERSION = VERSION;

package/dist/version.d.ts

@@ -2,4 +2,4 @@
  * Current package version from package.json
  * Automatically synchronized during build process
  */
-export declare const VERSION = "0.0.5";
+export declare const VERSION = "0.0.6";

package/dist/version.mjs

@@ -1,3 +1,3 @@
-const VERSION = '0.0.5';
+const VERSION = '0.0.6';
 
 export { VERSION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slats/claude-assets-sync",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "CLI tool to sync Claude commands and skills from npm packages to your project's .claude directory",
   "keywords": [
     "claude",