@jim80net/memex-core 0.4.0 → 0.6.0

package/dist/portable-location.js

@@ -0,0 +1,248 @@
+import { createHash } from "node:crypto";
+import { join, relative, resolve, sep } from "node:path";
+export const HANDLE_PREFIX = "memex://";
+/**
+ * Portable handles are opaque location tokens — not general URIs.
+ * Form: memex://{rootKey}/{posix-rel}[#{fragment}]
+ */
+/** Injective escape for rel segments and fragments (% first, then #). */
+export function escapePortableText(text) {
+    return text.replace(/%/g, "%25").replace(/#/g, "%23");
+}
+/** Reverse of escapePortableText (# last on decode, then %). */
+export function unescapePortableText(text) {
+    return text.replace(/%23/g, "#").replace(/%25/g, "%");
+}
+/** @alias escapePortableText */
+export const encodeFragment = escapePortableText;
+/** @alias unescapePortableText */
+export const decodeFragment = unescapePortableText;
+/**
+ * Split at the last literal '#' — escaped #s are %23 and do not split.
+ * Fragment is unescaped exactly once.
+ */
+export function splitPortableHandle(handle) {
+    const lastHash = handle.lastIndexOf("#");
+    if (lastHash === -1)
+        return { body: handle };
+    return {
+        body: handle.slice(0, lastHash),
+        fragment: unescapePortableText(handle.slice(lastHash + 1)),
+    };
+}
+function encodeRelPath(rel) {
+    return normalizeRel(rel).split("/").map(escapePortableText).join("/");
+}
+function decodeRelPath(rel) {
+    return rel.split("/").map(unescapePortableText).join("/");
+}
+function normalizeRel(rel) {
+    return rel.split(sep).join("/");
+}
+function isAbsolutePath(p) {
+    return p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p);
+}
+function hasUnsafeRelSegments(rel) {
+    const segments = rel.split("/");
+    return segments.some((s) => s === ".." || s === "");
+}
+function isPathContained(rootPath, absolute) {
+    const root = resolve(rootPath);
+    const normalized = resolve(absolute);
+    return normalized === root || normalized.startsWith(root + sep);
+}
+function sortRegistry(roots) {
+    return [...roots].sort((a, b) => b.rootPath.length - a.rootPath.length);
+}
+function matchRoot(registry, filePath) {
+    const normalized = resolve(filePath);
+    return registry.find((r) => isPathContained(r.rootPath, normalized));
+}
+function pathHasSegment(resolvedPath, segment) {
+    return resolve(resolvedPath).split(sep).includes(segment);
+}
+/** Stable fallback rootKey from normalized absolute dir path (§4.4 path-hash option). */
+export function stableUnclassifiedKey(kind, dir) {
+    const hash = createHash("sha256").update(resolve(dir)).digest("hex").slice(0, 8);
+    return `${kind}-unclassified-${hash}`;
+}
+/**
+ * Build labeled scan roots from harness context and scan directory spec.
+ * Same semantic root MUST use the same rootKey on every host (normative catalog).
+ */
+export function buildScanRoots(ctx, spec) {
+    const harness = ctx.harness;
+    const roots = [];
+    const seen = new Set();
+    const add = (key, dir) => {
+        const rootPath = resolve(dir);
+        if (seen.has(rootPath))
+            return;
+        seen.add(rootPath);
+        roots.push({ key, rootPath });
+    };
+    const globalSkillKeys = new Map();
+    for (const dir of ctx.globalSkillsDirs) {
+        const resolved = resolve(dir);
+        if (pathHasSegment(resolved, ".grok")) {
+            globalSkillKeys.set(resolved, "grok-global");
+        }
+        else if (pathHasSegment(resolved, ".claude")) {
+            globalSkillKeys.set(resolved, "claude-global");
+        }
+        else if (pathHasSegment(resolved, ".codex")) {
+            globalSkillKeys.set(resolved, "codex-global");
+        }
+        else if (pathHasSegment(resolved, ".hermes")) {
+            globalSkillKeys.set(resolved, "hermes-global");
+        }
+    }
+    const globalRuleKeys = new Map();
+    for (const dir of ctx.globalRulesDirs) {
+        const resolved = resolve(dir);
+        if (pathHasSegment(resolved, ".grok")) {
+            globalRuleKeys.set(resolved, "grok-rules-global");
+        }
+        else if (pathHasSegment(resolved, ".claude")) {
+            globalRuleKeys.set(resolved, "claude-rules-global");
+        }
+        else if (pathHasSegment(resolved, ".codex")) {
+            globalRuleKeys.set(resolved, "codex-rules-global");
+        }
+        else if (pathHasSegment(resolved, ".hermes")) {
+            globalRuleKeys.set(resolved, "hermes-rules-global");
+        }
+    }
+    const projectSkillsResolved = resolve(ctx.projectSkillsDir);
+    const projectRulesResolved = resolve(ctx.projectRulesDir);
+    const syncSkillsDir = ctx.syncEnabled && ctx.syncRepoDir ? resolve(join(ctx.syncRepoDir, "skills")) : undefined;
+    const syncRulesDir = ctx.syncEnabled && ctx.syncRepoDir ? resolve(join(ctx.syncRepoDir, "rules")) : undefined;
+    const unclassifiedSkillDirs = [];
+    for (const dir of spec.skillDirs) {
+        const resolved = resolve(dir);
+        const catalogKey = globalSkillKeys.get(resolved);
+        if (catalogKey) {
+            add(catalogKey, dir);
+        }
+        else if (resolved === projectSkillsResolved) {
+            add(`${harness}-project`, dir);
+        }
+        else if (syncSkillsDir && resolved === syncSkillsDir) {
+            add("sync-skills", dir);
+        }
+        else {
+            unclassifiedSkillDirs.push(dir);
+        }
+    }
+    for (const dir of unclassifiedSkillDirs) {
+        add(stableUnclassifiedKey("skill", dir), dir);
+    }
+    const unclassifiedRuleDirs = [];
+    for (const dir of spec.ruleDirs) {
+        const resolved = resolve(dir);
+        const catalogKey = globalRuleKeys.get(resolved);
+        if (catalogKey) {
+            add(catalogKey, dir);
+        }
+        else if (resolved === projectRulesResolved) {
+            add(`${harness}-rules-project`, dir);
+        }
+        else if (syncRulesDir && resolved === syncRulesDir) {
+            add("sync-rules", dir);
+        }
+        else {
+            unclassifiedRuleDirs.push(dir);
+        }
+    }
+    for (const dir of unclassifiedRuleDirs) {
+        add(stableUnclassifiedKey("rule", dir), dir);
+    }
+    for (const dir of spec.memoryDirs) {
+        add(stableUnclassifiedKey("memory", dir), dir);
+    }
+    return sortRegistry(roots);
+}
+/**
+ * Absolute path (+ optional #fragment) → portable handle.
+ * Fail-open: returns null when mapping is impossible (caller should skip-with-warning).
+ */
+export function encodePortableLocation(registry, absolute, warn, fragment) {
+    const body = resolve(absolute);
+    const root = matchRoot(registry, body);
+    if (!root) {
+        warn?.(`skipped indexing ${absolute} — no portable handle (outside registered scan roots)`);
+        return null;
+    }
+    const rel = normalizeRel(relative(root.rootPath, body));
+    if (hasUnsafeRelSegments(rel)) {
+        warn?.(`skipped indexing ${absolute} — no portable handle (unsafe relative path: ${rel})`);
+        return null;
+    }
+    const handle = `${HANDLE_PREFIX}${root.key}/${encodeRelPath(rel)}`;
+    if (fragment === undefined)
+        return handle;
+    return `${handle}#${escapePortableText(fragment)}`;
+}
+/**
+ * Portable handle → absolute file path + optional section name.
+ * Fragment is split and %23-unescaped exactly once — never rejoin with '#'.
+ * Fail-closed on traversal escape.
+ */
+export function decodePortableLocationResolved(registry, handle) {
+    if (!handle.startsWith(HANDLE_PREFIX)) {
+        throw new Error(`invalid portable location handle: ${handle}`);
+    }
+    const { body, fragment: sectionName } = splitPortableHandle(handle);
+    const pathBody = body.slice(HANDLE_PREFIX.length);
+    const slash = pathBody.indexOf("/");
+    if (slash === -1) {
+        throw new Error(`invalid portable location handle (missing path segment): ${handle}`);
+    }
+    const key = pathBody.slice(0, slash);
+    const rel = decodeRelPath(pathBody.slice(slash + 1));
+    if (hasUnsafeRelSegments(rel)) {
+        throw new Error(`portable location handle escapes scan root: ${handle}`);
+    }
+    const root = registry.find((r) => r.key === key);
+    if (!root) {
+        throw new Error(`unknown portable location root '${key}'`);
+    }
+    const filePath = resolve(root.rootPath, rel);
+    if (!isPathContained(root.rootPath, filePath)) {
+        throw new Error(`portable location handle escapes scan root: ${handle}`);
+    }
+    return sectionName !== undefined ? { filePath, sectionName } : { filePath };
+}
+/**
+ * Portable handle → absolute path string (legacy join form).
+ * Prefer decodePortableLocationResolved when a fragment may be present.
+ */
+export function decodePortableLocation(registry, handle) {
+    const { filePath, sectionName } = decodePortableLocationResolved(registry, handle);
+    return sectionName !== undefined ? `${filePath}#${sectionName}` : filePath;
+}
+/**
+ * Resolve portable handle or legacy absolute path for filesystem I/O.
+ * Phase 2: agent-facing read tools MUST pass `allowAbsolute: false` so untrusted
+ * absolute paths cannot bypass containment (memex-grok#19 closes only then).
+ */
+export function resolvePortableLocationResolved(registry, input, options) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return { filePath: trimmed };
+    if (trimmed.startsWith(HANDLE_PREFIX)) {
+        return decodePortableLocationResolved(registry, trimmed);
+    }
+    if (options?.allowAbsolute !== false && isAbsolutePath(trimmed)) {
+        options?.warn?.(`deprecated: readSkillContent received absolute path; use portable memex:// handles`);
+        const { body, fragment } = splitPortableHandle(trimmed);
+        return fragment !== undefined ? { filePath: body, sectionName: fragment } : { filePath: body };
+    }
+    throw new Error(`unrecognized location: ${input}`);
+}
+/** @deprecated Prefer resolvePortableLocationResolved to avoid fragment double-decode. */
+export function resolvePortableLocation(registry, input, options) {
+    const { filePath, sectionName } = resolvePortableLocationResolved(registry, input, options);
+    return sectionName !== undefined ? `${filePath}#${sectionName}` : filePath;
+}
+//# sourceMappingURL=portable-location.js.map

package/dist/portable-location.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-location.js","sourceRoot":"","sources":["../src/portable-location.ts"],"names":[],"mappings":"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"}

package/dist/skill-index.d.ts

@@ -1,4 +1,5 @@
 import type { EmbeddingProvider } from "./embeddings.js";
+import { type PortableLocationWarn, type ScanRootRegistry } from "./portable-location.js";
 import type { MemexCoreConfig, ParsedFrontmatter, ScoringMode, SkillSearchResult, SkillType } from "./types.js";
 export declare function parseFrontmatter(content: string): {
     meta: ParsedFrontmatter;
@@ -37,16 +38,33 @@ export type ScanDirs = {
     memoryDirs: string[];
     ruleDirs: string[];
 };
+export type SkillIndexOptions = {
+    registry?: ScanRootRegistry;
+    warn?: PortableLocationWarn;
+};
 export declare class SkillIndex {
     private config;
     private provider;
     private cachePath;
+    private options;
     private skills;
     private skillMtimes;
     private cache;
     private cacheLoaded;
     private buildTime;
-    constructor(config: MemexCoreConfig, provider: EmbeddingProvider, cachePath: string);
+    constructor(config: MemexCoreConfig, provider: EmbeddingProvider, cachePath: string, options?: SkillIndexOptions);
+    private get registry();
+    private warn;
+    /** Map absolute scan path to persisted location (portable handle or absolute). */
+    private toStoredLocation;
+    /** Absolute path used for mtime tracking (scan truth). Fail-closed — agent read paths only. */
+    private mtimeKeyFromStored;
+    /**
+     * Cache-key decode — fail-open. Orphaned handles (registry changed) return null
+     * so build() skips/re-embeds instead of bricking the whole index.
+     */
+    private mtimeKeyFromStoredSafe;
+    private memorySectionPrefix;
     get skillCount(): number;
     needsRebuild(): boolean;
     /**

package/dist/skill-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-index.d.ts","sourceRoot":"","sources":["../src/skill-index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,KAAK,EAGV,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,SAAS,EACV,MAAM,YAAY,CAAC;AAQpB,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAyD3F;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAiD/E;AA4ED,MAAM,MAAM,QAAQ,GAAG;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAkBF,qBAAa,UAAU;IAQnB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,SAAS;IATnB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,SAAS,CAAK;gBAGZ,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,EAAE,MAAM;IAG3B,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,YAAY,IAAI,OAAO;IAKvB;;;OAGG;IACG,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAyL9C;;;OAGG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,SAAS,EAAE,EACxB,WAAW,GAAE,WAAwB,EACrC,UAAU,GAAE,MAAa,GACxB,OAAO,CAAC,iBAAiB,EAAE,CAAC;IA0C/B;;OAEG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkBzD,OAAO,CAAC,sBAAsB;IAsB9B,OAAO,CAAC,uBAAuB;IAqB/B,OAAO,CAAC,qBAAqB;CA4B9B"}
+{"version":3,"file":"skill-index.d.ts","sourceRoot":"","sources":["../src/skill-index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EAKL,KAAK,oBAAoB,EAEzB,KAAK,gBAAgB,EAEtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAGV,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,SAAS,EACV,MAAM,YAAY,CAAC;AAQpB,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAyD3F;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAiD/E;AA4ED,MAAM,MAAM,QAAQ,GAAG;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,IAAI,CAAC,EAAE,oBAAoB,CAAC;CAC7B,CAAC;AAkBF,qBAAa,UAAU;IAQnB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,OAAO;IAVjB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,SAAS,CAAK;gBAGZ,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,iBAAsB;IAGzC,OAAO,KAAK,QAAQ,GAEnB;IAED,OAAO,CAAC,IAAI;IAIZ,kFAAkF;IAClF,OAAO,CAAC,gBAAgB;IAKxB,+FAA+F;IAC/F,OAAO,CAAC,kBAAkB;IAa1B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,mBAAmB;IAK3B,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,YAAY,IAAI,OAAO;IAKvB;;;OAGG;IACG,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IA+L9C;;;OAGG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,SAAS,EAAE,EACxB,WAAW,GAAE,WAAwB,EACrC,UAAU,GAAE,MAAa,GACxB,OAAO,CAAC,iBAAiB,EAAE,CAAC;IA0C/B;;OAEG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA2BzD,OAAO,CAAC,sBAAsB;IAuB9B,OAAO,CAAC,uBAAuB;IAuB/B,OAAO,CAAC,qBAAqB;CA6B9B"}

package/dist/skill-index.js

@@ -2,6 +2,7 @@ import { readdir, readFile, stat } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { fromCachedSkill, loadCache, saveCache, toCachedSkill } from "./cache.js";
 import { cosineSimilarity } from "./embeddings.js";
+import { decodePortableLocation, encodeFragment, encodePortableLocation, HANDLE_PREFIX, resolvePortableLocationResolved, splitPortableHandle, } from "./portable-location.js";
 // ---------------------------------------------------------------------------
 // Frontmatter parsing
 // ---------------------------------------------------------------------------
@@ -206,15 +207,60 @@ export class SkillIndex {
     config;
     provider;
     cachePath;
+    options;
     skills = [];
     skillMtimes = new Map();
     cache = null;
     cacheLoaded = false;
     buildTime = 0;
-    constructor(config, provider, cachePath) {
+    constructor(config, provider, cachePath, options = {}) {
         this.config = config;
         this.provider = provider;
         this.cachePath = cachePath;
+        this.options = options;
+    }
+    get registry() {
+        return this.options.registry;
+    }
+    warn(msg) {
+        this.options.warn?.(msg);
+    }
+    /** Map absolute scan path to persisted location (portable handle or absolute). */
+    toStoredLocation(absolute) {
+        if (!this.registry)
+            return absolute;
+        return encodePortableLocation(this.registry, absolute, (m) => this.warn(m));
+    }
+    /** Absolute path used for mtime tracking (scan truth). Fail-closed — agent read paths only. */
+    mtimeKeyFromStored(stored) {
+        if (!this.registry) {
+            const hash = stored.indexOf("#");
+            return hash === -1 ? stored : stored.slice(0, hash);
+        }
+        const { body } = splitPortableHandle(stored);
+        if (body.startsWith(HANDLE_PREFIX)) {
+            return decodePortableLocation(this.registry, body);
+        }
+        const hash = body.indexOf("#");
+        return hash === -1 ? body : body.slice(0, hash);
+    }
+    /**
+     * Cache-key decode — fail-open. Orphaned handles (registry changed) return null
+     * so build() skips/re-embeds instead of bricking the whole index.
+     */
+    mtimeKeyFromStoredSafe(stored) {
+        try {
+            return this.mtimeKeyFromStored(stored);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            this.warn(`skipped unresolvable cached handle ${stored} — ${reason}`);
+            return null;
+        }
+    }
+    memorySectionPrefix(absoluteFile) {
+        const base = this.toStoredLocation(absoluteFile);
+        return base ? `${base}#` : null;
     }
     get skillCount() {
         return this.skills.length;
@@ -236,8 +282,13 @@ export class SkillIndex {
             // Hydrate from cache on cold start
             if (this.skills.length === 0 && Object.keys(this.cache.skills).length > 0) {
                 for (const [location, cached] of Object.entries(this.cache.skills)) {
+                    const mtimeKey = this.mtimeKeyFromStoredSafe(location);
+                    if (mtimeKey === null) {
+                        delete this.cache.skills[location];
+                        continue;
+                    }
                     this.skills.push(fromCachedSkill(location, cached));
-                    this.skillMtimes.set(location, cached.mtime);
+                    this.skillMtimes.set(mtimeKey, cached.mtime);
                 }
             }
         }
@@ -289,17 +340,21 @@ export class SkillIndex {
         // Find files that need (re)embedding
         const toEmbed = [];
         for (const info of statResults) {
+            const storedLocation = this.toStoredLocation(info.location);
+            if (storedLocation === null)
+                continue;
             if (info.kind === "memory") {
-                // Memory files may produce multiple sections — each keyed as "path#SectionName"
                 const cachedMtime = this.skillMtimes.get(info.location);
                 if (cachedMtime === info.mtime)
                     continue;
-                // Remove old sections for this memory file
-                this.skills = this.skills.filter((s) => !s.location.startsWith(`${info.location}#`));
-                if (this.cache) {
-                    for (const key of Object.keys(this.cache.skills)) {
-                        if (key.startsWith(`${info.location}#`))
-                            delete this.cache.skills[key];
+                const sectionPrefix = this.memorySectionPrefix(info.location);
+                if (sectionPrefix) {
+                    this.skills = this.skills.filter((s) => !s.location.startsWith(sectionPrefix));
+                    if (this.cache) {
+                        for (const key of Object.keys(this.cache.skills)) {
+                            if (key.startsWith(sectionPrefix))
+                                delete this.cache.skills[key];
+                        }
                     }
                 }
                 try {
@@ -312,31 +367,28 @@ export class SkillIndex {
                 this.skillMtimes.set(info.location, info.mtime);
                 continue;
             }
-            // Skills and rules
-            const cached = this.cache?.skills[info.location];
+            const cached = this.cache?.skills[storedLocation];
             if (cached && cached.mtime === info.mtime) {
-                // Use cached embeddings — no re-embed
-                const existing = this.skills.findIndex((s) => s.location === info.location);
-                const skill = fromCachedSkill(info.location, cached);
+                const existing = this.skills.findIndex((s) => s.location === storedLocation);
+                const skill = fromCachedSkill(storedLocation, cached);
                 if (existing >= 0)
                     this.skills[existing] = skill;
-                else if (!this.skills.some((s) => s.location === info.location))
+                else if (!this.skills.some((s) => s.location === storedLocation))
                     this.skills.push(skill);
                 this.skillMtimes.set(info.location, info.mtime);
                 continue;
             }
-            // Check in-memory cache
             const unchanged = this.skillMtimes.get(info.location) === info.mtime &&
-                this.skills.some((s) => s.location === info.location);
+                this.skills.some((s) => s.location === storedLocation);
             if (unchanged)
                 continue;
             try {
                 const raw = await readFile(info.location, "utf-8");
                 if (info.kind === "rule") {
-                    this.parseRuleFileForEmbed(raw, info, toEmbed);
+                    this.parseRuleFileForEmbed(raw, info, toEmbed, storedLocation);
                 }
                 else {
-                    this.parseSkillFileForEmbed(raw, info, toEmbed);
+                    this.parseSkillFileForEmbed(raw, info, toEmbed, storedLocation);
                 }
             }
             catch {
@@ -372,16 +424,17 @@ export class SkillIndex {
                 offset += item.queries.length;
             }
         }
-        // Remove deleted entries (handle memory section keys like "path#SectionName")
+        // Remove deleted entries (handle memory section keys)
         this.skills = this.skills.filter((s) => {
-            const baseLocation = s.location.includes("#") ? s.location.split("#")[0] : s.location;
-            return currentLocations.has(baseLocation) || currentLocations.has(s.location);
+            const baseLocation = this.mtimeKeyFromStoredSafe(s.location);
+            if (baseLocation === null)
+                return false;
+            return currentLocations.has(baseLocation);
         });
-        // Clean cache of deleted entries
         if (this.cache) {
             for (const key of Object.keys(this.cache.skills)) {
-                const baseKey = key.includes("#") ? key.split("#")[0] : key;
-                if (!currentLocations.has(baseKey) && !currentLocations.has(key)) {
+                const baseKey = this.mtimeKeyFromStoredSafe(key);
+                if (baseKey === null || !currentLocations.has(baseKey)) {
                     delete this.cache.skills[key];
                 }
             }
@@ -441,21 +494,29 @@ export class SkillIndex {
      * Read the body content of a skill file, stripping frontmatter.
      */
     async readSkillContent(location) {
-        if (location.includes("#")) {
-            const [filePath, sectionName] = location.split("#", 2);
+        const trimmed = location.trim();
+        const { filePath, sectionName } = this.registry
+            ? resolvePortableLocationResolved(this.registry, trimmed, { warn: (m) => this.warn(m) })
+            : (() => {
+                const { body, fragment } = splitPortableHandle(trimmed);
+                return fragment !== undefined
+                    ? { filePath: body, sectionName: fragment }
+                    : { filePath: body };
+            })();
+        if (sectionName !== undefined) {
             const raw = await readFile(filePath, "utf-8");
             const sections = parseMemoryFile(raw, filePath);
             const section = sections.find((s) => s.name === sectionName);
             return section?.body.trim() || "";
         }
-        const raw = await readFile(location, "utf-8");
+        const raw = await readFile(filePath, "utf-8");
         const { body } = parseFrontmatter(raw);
         return body.trim();
     }
     // -------------------------------------------------------------------------
     // Private parsing helpers
     // -------------------------------------------------------------------------
-    parseSkillFileForEmbed(raw, info, toEmbed) {
+    parseSkillFileForEmbed(raw, info, toEmbed, storedLocation) {
         const { meta, body } = parseFrontmatter(raw);
         if (!meta.name || !meta.description)
             return;
@@ -464,7 +525,7 @@ export class SkillIndex {
         toEmbed.push({
             name: meta.name,
             description: meta.description,
-            location: info.location,
+            location: storedLocation,
             queries,
             type,
             mtime: info.mtime,
@@ -474,9 +535,12 @@ export class SkillIndex {
         });
     }
     parseMemoryFileForEmbed(raw, info, toEmbed) {
+        const baseStored = this.toStoredLocation(info.location);
+        if (!baseStored)
+            return;
         const sections = parseMemoryFile(raw, info.location);
         for (const section of sections) {
-            const key = `${info.location}#${section.name}`;
+            const key = `${baseStored}#${encodeFragment(section.name)}`;
             const queries = section.queries.length > 0 ? section.queries : [section.description];
             toEmbed.push({
                 name: section.name,
@@ -489,7 +553,7 @@ export class SkillIndex {
             });
         }
     }
-    parseRuleFileForEmbed(raw, info, toEmbed) {
+    parseRuleFileForEmbed(raw, info, toEmbed, storedLocation) {
         const { meta, body } = parseFrontmatter(raw);
         const name = meta.name || basename(info.location, ".md");
         const description = meta.description || body.split("\n")[0]?.trim() || name;
@@ -504,7 +568,7 @@ export class SkillIndex {
         toEmbed.push({
             name,
             description,
-            location: info.location,
+            location: storedLocation,
             queries,
             type: "rule",
             mtime: info.mtime,