@north-light/crouter 0.3.227 → 0.3.229

package/dist/commands/sys/sync-project-guidance.js

@@ -1,19 +1,21 @@
-// `crtr sys sync project-guidance` — one-way migration of a project's own
-// CLAUDE.md/AGENTS.md/.claude/rules into that SAME directory's OWN
-// `.crouter/memory/`. Each project guide becomes the workspace front door
-// (workspace-open + ./** read entries); rules keep their explicit path routes
-// as read entries, or take the front-door pair when they are pathless.
+// `crtr sys sync project-guidance` — one-way migration of a repository's
+// CLAUDE.md/AGENTS.md/.claude/rules into repository-root and nested
+// `.crouter/memory/` stores. Only the repository root owns the namespace and
+// workspace front door; nested stores derive their prefix from their path.
 import { existsSync, readdirSync, statSync } from 'node:fs';
-import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
-import { gitSync } from '../../core/git.js';
-import { pathExists, readText, walkFiles, writeText } from '../../core/fs-utils.js';
+import { usage } from '../../core/errors.js';
+import { pathExists, readText, realpathOrSelf, walkFiles, writeText } from '../../core/fs-utils.js';
 import { loadProfileManifest } from '../../core/profiles/manifest.js';
 import { CRTR_DIR_NAME } from '../../types.js';
 import { memoryFilePath, serializeMemoryDoc } from '../memory/shared.js';
 import { normalizedName, routeFromDescription, scalarString } from './sync-shared.js';
-import { realpathOrSelf } from '../../core/fs-utils.js';
+import { deriveProjectNamespace } from '../../core/memory/project-namespace.js';
+import { associateRepository } from '../../core/memory/repository-association.js';
+import { openProjectMemoryStore } from '../../core/memory-resolver.js';
+import { composeCanonicalName, localNameFromPath, resolveLocalName, validateExplicitLocalName, } from '../../core/memory/identity.js';
 // Directories a project-doc walk never descends into — build/dependency trees
 // plus crouter's own state dir.
 const PROJECT_DOC_JUNK_DIRS = new Set([
@@ -130,93 +132,52 @@ function normalizeRulePaths(v) {
     }
     return [];
 }
-/** The main repo root's directory name, found via `git rev-parse
- *  --git-common-dir` — unlike `--show-toplevel`, this resolves through a
- *  LINKED WORKTREE to the shared `.git` of the repo it belongs to, so a
- *  canvas worktree checked out under a node-id path (e.g.
- *  `.../worktrees/mr9vsbtn-ecd74d1b`) still resolves to the real project
- *  name (`crouter`), not the worktree's own basename. Returns undefined when
- *  `dir` isn't inside a git repo at all. */
-function gitRepoRootName(dir) {
-    const res = gitSync(['rev-parse', '--path-format=absolute', '--git-common-dir'], dir);
-    if (res.status !== 0)
-        return undefined;
-    const gitCommonDir = res.stdout.trim();
-    if (gitCommonDir === '')
-        return undefined;
-    return basename(dirname(gitCommonDir));
-}
-/** The current git worktree's OWN top-level directory (`git rev-parse
- *  --show-toplevel`) — unlike `--git-common-dir` above, this does NOT resolve
- *  through a linked worktree to the shared repo storage; it is the actual
- *  checked-out tree containing `dir`. This is the stable root to compute a
- *  doc's subdir suffix against, even when the discovery walk itself started
- *  strictly inside that tree — e.g. `--source` pointed directly at a nested
- *  package dir, so the walk root and the source dir are the same directory
- *  and a walk-root-relative suffix would be empty. Returns undefined when
- *  `dir` isn't inside a git working tree at all (the non-git fallback keeps
- *  using the walk root itself). */
-function gitWorktreeRoot(dir) {
-    const res = gitSync(['rev-parse', '--path-format=absolute', '--show-toplevel'], dir);
-    if (res.status !== 0)
-        return undefined;
-    const top = res.stdout.trim();
-    return top === '' ? undefined : resolve(top);
-}
-/** First Markdown H1 heading in the doc body, heading marker stripped. */
-function h1Title(body) {
-    for (const raw of body.split('\n')) {
-        const m = raw.match(/^#\s+(.+)$/);
-        if (m) {
-            const title = m[1].replace(/\s+/g, ' ').trim();
-            if (title !== '')
-                return title;
-        }
+/** Resolve one effective guidance namespace for a repository. The cache is
+ *  keyed by repository root so cwd/profile widening and nested source guides
+ *  cannot derive competing identities during one sync. */
+function resolveRepositoryNamespace(sourceDir, walkRoot, rootBodies, memo) {
+    const associated = associateRepository(sourceDir);
+    let repositoryRoot;
+    if (associated.ok) {
+        repositoryRoot = associated.association.repositoryRoot;
     }
-    return undefined;
-}
-/** Namespace label for a walk root: the raw basename of that directory is
- *  unreliable (a worktree/canvas checkout's basename is a node id, not the
- *  project name), so prefer the actual git repo's root dirname, then the root
- *  doc's own H1 title if one exists there, then the raw basename. */
-function projectRootLabel(root) {
-    const gitLabel = gitRepoRootName(root);
-    if (gitLabel !== undefined)
-        return normalizedName(gitLabel);
-    for (const name of PROJECT_DOC_FILENAMES) {
-        const p = join(root, name);
-        if (existsSync(p) && statSync(p).isFile()) {
-            const title = h1Title(parseFrontmatterGeneric(readText(p)).body);
-            if (title !== undefined)
-                return normalizedName(title);
-        }
+    else if (associated.ok === false && associated.code === 'no-project-root') {
+        // A guidance walk may initialize a repository that has no memory store yet.
+        repositoryRoot = realpathOrSelf(walkRoot);
     }
-    return normalizedName(basename(root) || root);
-}
-/** Explicit substrate identity for one migrated project doc: the root label
- *  from the walk root (repo name/H1/basename), plus any relative subdir under
- *  the STABLE SUFFIX ROOT. That suffix root is the git worktree top-level
- *  when the source is git-backed, NOT the supplied walk root — so a
- *  `--source` pointed directly at a nested subdir (walk root === source dir,
- *  a walk-root-relative suffix would be empty) still gets a suffix relative
- *  to the real project root and cannot collide with that root's own doc
- *  identity. Non-git sources have no stable project root to prefer, so they
- *  keep the walk-root fallback unchanged. Root AGENTS.md docs become
- *  `crouter`/`hearth`-shaped identities while nested AGENTS.md docs get a
- *  deterministic `root/subdir` name — regardless of whether the walk started
- *  at that root or at the nested dir itself. */
-function projectDocLabel(candidate) {
-    const rootLabel = projectRootLabel(candidate.walkRoot);
-    const suffixRoot = gitWorktreeRoot(candidate.walkRoot) ?? candidate.walkRoot;
-    // `git rev-parse --show-toplevel` resolves through symlinks (e.g. macOS's
-    // /tmp -> /private/tmp); realpath BOTH sides before diffing so a symlinked
-    // walk root doesn't produce a bogus `../../..` suffix against the git-
-    // resolved top-level.
-    const relDir = relative(realpathOrSelf(suffixRoot), realpathOrSelf(candidate.sourceDir))
-        .split(sep)
-        .join('/')
-        .replace(/^\.$/, '');
-    return relDir === '' ? rootLabel : normalizedName(`${rootLabel}/${relDir}`);
+    else {
+        const reason = associated.ok === false ? associated.reason : 'unknown repository association failure';
+        throw usage(`cannot associate project guidance at ${sourceDir}: ${reason}`, {
+            next: `Run \`crtr sys migrate --dir ${sourceDir}\`.`,
+        });
+    }
+    repositoryRoot = realpathOrSelf(repositoryRoot);
+    const existing = memo.get(repositoryRoot);
+    if (existing !== undefined)
+        return existing;
+    const store = openProjectMemoryStore(repositoryRoot);
+    if (store.mountStatus === 'ready') {
+        const namespace = store.repositoryNamespace ?? store.namespace;
+        const resolved = { namespace, repositoryRoot, initialize: false };
+        memo.set(repositoryRoot, resolved);
+        return resolved;
+    }
+    const memoryDir = join(repositoryRoot, CRTR_DIR_NAME, 'memory');
+    const docs = pathExists(memoryDir) ? walkFiles(memoryDir, (name) => name.endsWith('.md')) : [];
+    if (docs.length > 0) {
+        throw usage(`project memory store at ${memoryDir} is undeclared or invalid`, {
+            next: `Run \`crtr sys migrate --dir ${repositoryRoot}\`.`,
+        });
+    }
+    const derived = deriveProjectNamespace({ ownerDir: repositoryRoot, rootBody: rootBodies.get(repositoryRoot) });
+    if (derived.ok === false) {
+        throw usage(`cannot initialize project memory store at ${memoryDir}: ${derived.reason}`, {
+            next: `Run \`crtr sys migrate --dir ${repositoryRoot}\`.`,
+        });
+    }
+    const resolved = { namespace: derived.namespace, repositoryRoot, initialize: true };
+    memo.set(repositoryRoot, resolved);
+    return resolved;
 }
 /** The surfaces pair every workspace front door carries: whole-doc delivery
  *  when cwd/profile mounts the store, plus on any file read beneath the
@@ -239,62 +200,106 @@ function anchorReadGlob(g) {
         return t;
     return `./${t}`;
 }
-/** AGENTS.md/CLAUDE.md → `<sourceDir>/.crouter/memory/INDEX.md`, the
- *  workspace front door. Its explicit project identity keeps sibling roots
- *  distinct; the workspace-open + ./** read entry pair puts the wholly
- *  important guide in first-message context when cwd/profile mounts the store,
- *  and surfaces it on any file read beneath the store's owning dir. */
-function prepareAgentsCandidate(candidate) {
-    const body = parseFrontmatterGeneric(readText(candidate.path)).body;
-    const docLabel = projectDocLabel(candidate);
+/** AGENTS.md/CLAUDE.md becomes a repository-root or nested store root
+ * document. Only the repository root carries the declaration and front door. */
+function prepareAgentsCandidate(candidate, resolution) {
+    const parsed = parseFrontmatterGeneric(readText(candidate.path));
+    const root = realpathOrSelf(candidate.sourceDir) === resolution.repositoryRoot;
+    return prepareRootCandidate(candidate, resolution.namespace, parsed.body, root, parsed.data ?? {});
+}
+function sourceReadRoute(frontmatter) {
+    if (!Array.isArray(frontmatter['surfaces']))
+        return [];
+    return frontmatter['surfaces'].filter((entry) => {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry))
+            return false;
+        const value = entry;
+        if (value['on'] !== 'read' || !['name', 'preview', 'content'].includes(String(value['at'])))
+            return false;
+        const match = value['match'];
+        const hasMatch = typeof match === 'string'
+            ? match.trim() !== ''
+            : Array.isArray(match) && match.length > 0 && match.every((glob) => typeof glob === 'string' && glob.trim() !== '');
+        const matchFrontmatter = value['match-frontmatter'];
+        return hasMatch || (matchFrontmatter !== null && typeof matchFrontmatter === 'object' && !Array.isArray(matchFrontmatter));
+    });
+}
+function prepareRootCandidate(candidate, namespace, body, repositoryRoot, sourceFrontmatter = {}) {
+    if (!repositoryRoot) {
+        const surfaces = sourceReadRoute(sourceFrontmatter);
+        const authoredRoute = scalarString(sourceFrontmatter['when-and-why-to-read'])?.trim();
+        const frontmatter = {
+            kind: 'knowledge',
+            'when-and-why-to-read': authoredRoute !== undefined && authoredRoute !== ''
+                ? authoredRoute
+                : `When working under ${namespace}, this knowledge should be read because it carries the nested project guidance.`,
+            'short-form': synthesizeShortForm(body),
+            ...(surfaces.length > 0 ? { surfaces } : {}),
+        };
+        return {
+            candidate,
+            name: '',
+            target: join(candidate.sourceDir, CRTR_DIR_NAME, 'memory', 'INDEX.md'),
+            frontmatter,
+            body,
+        };
+    }
     const frontmatter = {
         kind: 'knowledge',
-        name: docLabel,
-        'when-and-why-to-read': `When working in ${docLabel}, this knowledge should be read because it is the project's operating guide.`,
+        namespace,
+        'when-and-why-to-read': `When working in ${namespace}, this knowledge should be read because it is the project's operating guide.`,
         'short-form': synthesizeShortForm(body),
         surfaces: frontDoorSurfaces(),
     };
     return {
         candidate,
-        name: docLabel,
-        target: memoryFilePath(join(candidate.sourceDir, CRTR_DIR_NAME, 'memory'), 'INDEX'),
+        name: namespace,
+        target: join(candidate.sourceDir, CRTR_DIR_NAME, 'memory', 'INDEX.md'),
         frontmatter,
         body,
     };
 }
-/** `.claude/rules/<name>.md` → `<sourceDir>/.crouter/memory/<name>.md`. A
- *  `paths:` rule keeps its file globs as a `content` read entry (`./`-anchored
- *  when repo-relative); a pathless rule takes the front-door pair and surfaces
- *  when the workspace opens or a file beneath the store's owning dir is read.
- *  Like the INDEX docs, each rule
- *  carries an explicit namespaced substrate name (`<root>/<subdir>/<leaf>`):
- *  without it the resolver falls back to the store-relative leaf, and two
- *  nested stores sharing a rule filename (e.g. apps/core and apps/gateway both
- *  carrying `unit-tests.md`) collapse onto one bare name, shadowing one doc. */
-function prepareRuleCandidate(candidate) {
+/** A rule's identity is store-local. The physical path supplies the default;
+ *  an authored name is accepted as an explicit local identity. */
+function prepareRuleCandidate(candidate, resolution) {
+    const associated = associateRepository(candidate.sourceDir);
+    if (!associated.ok) {
+        throw usage(`cannot associate rule guidance at ${candidate.path}: ${associated.reason}`, {
+            next: `Run \`crtr sys migrate --dir ${candidate.sourceDir}\`.`,
+        });
+    }
+    // Nested stores inherit the repository declaration plus their normalized
+    // owner-relative path, exactly as the runtime's project store descriptor.
+    const namespace = composeCanonicalName(resolution.namespace, associated.association.ownerRelativePath);
     const raw = readText(candidate.path);
     const parsed = parseFrontmatterGeneric(raw);
     const fm = parsed.data ?? {};
-    const leaf = normalizedName(basename(candidate.path));
+    const physicalLeaf = normalizedName(basename(candidate.path));
+    const pathLocal = localNameFromPath(`${physicalLeaf}.md`);
+    const localName = resolveLocalName(fm, pathLocal);
+    const valid = validateExplicitLocalName(localName, namespace);
+    if (valid.ok === false)
+        throw usage(`invalid local rule name in ${candidate.path}: ${valid.reason}`);
     const description = scalarString(fm['description']) ?? '';
-    const dirLabel = projectDocLabel(candidate);
-    const name = normalizedName(`${dirLabel}/${leaf}`);
+    const name = composeCanonicalName(namespace, localName);
     const frontmatter = {
         kind: 'knowledge',
-        name,
+        name: localName,
         'when-and-why-to-read': description !== ''
             ? routeFromDescription(description, 'knowledge')
-            : `When working under ${dirLabel}, this knowledge should be read because it is migrated project rule guidance.`,
+            : `When working under ${namespace}, this knowledge should be read because it is migrated project rule guidance.`,
         'short-form': description !== '' ? description.replace(/\s+/g, ' ').trim() : synthesizeShortForm(parsed.body),
     };
     const globs = normalizeRulePaths(fm['paths']).map(anchorReadGlob);
+    // A pathless rule is still readable, but it must not mint a repository
+    // workspace front door; that belongs exclusively to the repository root.
     frontmatter['surfaces'] = globs.length > 0
         ? [{ on: 'read', match: globs.length === 1 ? globs[0] : globs, at: 'content' }]
-        : frontDoorSurfaces();
+        : [{ on: 'read', match: './**', at: 'content' }];
     return {
         candidate,
         name,
-        target: memoryFilePath(join(candidate.sourceDir, CRTR_DIR_NAME, 'memory'), leaf),
+        target: memoryFilePath(join(candidate.sourceDir, CRTR_DIR_NAME, 'memory'), localName),
         frontmatter,
         body: parsed.body,
     };
@@ -322,6 +327,29 @@ function convertProjectDoc(prepared, opts) {
         status: opts.dryRun ? 'would-import' : 'imported',
     };
 }
+function validateAuthoredNamespace(candidate, resolution) {
+    if (candidate.kind !== 'agents')
+        return;
+    let requested;
+    try {
+        requested = parseFrontmatterGeneric(readText(candidate.path)).data?.['namespace'];
+    }
+    catch {
+        return;
+    }
+    if (requested === undefined)
+        return;
+    const root = realpathOrSelf(candidate.sourceDir) === resolution.repositoryRoot;
+    const declarationPath = join(resolution.repositoryRoot, CRTR_DIR_NAME, 'memory', 'INDEX.md');
+    if (!root) {
+        throw usage(`project guidance at ${candidate.path} declares a namespace, but ${declarationPath} is the only declaration for this repository`, { next: `Run \`crtr sys migrate --dir ${resolution.repositoryRoot}\`.` });
+    }
+    if (requested !== resolution.namespace) {
+        throw usage(`project guidance namespace ${JSON.stringify(requested)} conflicts with the declared store namespace ${JSON.stringify(resolution.namespace)}`, {
+            next: `Run \`crtr sys migrate --dir ${resolution.repositoryRoot}\` for a repository-wide identity change.`,
+        });
+    }
+}
 function renderSummary(results) {
     const imported = results.filter((r) => r.status === 'imported').length;
     const wouldImport = results.filter((r) => r.status === 'would-import').length;
@@ -340,11 +368,11 @@ function renderSummary(results) {
 }
 export const sysSyncProjectGuidanceLeaf = defineLeaf({
     name: 'project-guidance',
-    description: "migrate CLAUDE.md/AGENTS.md/.claude/rules into that directory's own crouter memory docs",
-    whenToUse: "migrating per-project CLAUDE.md/AGENTS.md/.claude/rules into the crouter memory-doc model: one-way copy into that same directory's OWN .crouter/memory/. The project guide becomes its workspace front door; path-scoped rules keep their globs as read entries and pathless rules open with the workspace. Never exports memory docs back to these source files.",
+    description: 'migrate repository guidance into repository-root and nested crouter memory docs',
+    whenToUse: "migrating repository CLAUDE.md/AGENTS.md/.claude/rules into the crouter memory-doc model: one-way copy into the repository root's or nested store's .crouter/memory/. Only the repository-root guide becomes the workspace front door; nested guides and rules keep read routes. Never exports memory docs back to these source files.",
     help: {
         name: 'sys sync project-guidance',
-        summary: "one-way migration: CLAUDE.md/AGENTS.md/.claude/rules → that dir's own crouter memory docs",
+        summary: 'one-way migration: CLAUDE.md/AGENTS.md/.claude/rules → repository-root and nested crouter memory docs',
         params: [
             { kind: 'flag', name: 'source', type: 'string', required: false, constraint: "The root to walk recursively for CLAUDE.md/AGENTS.md/.claude/rules files. Default: cwd plus every project in the current profile's purview (when one is selected)." },
             { kind: 'flag', name: 'dry-run', type: 'bool', required: false, constraint: 'Show what would be migrated without writing memory docs.' },
@@ -358,7 +386,7 @@ export const sysSyncProjectGuidanceLeaf = defineLeaf({
         ],
         outputKind: 'object',
         effects: [
-            "Copies each discovered CLAUDE.md/AGENTS.md into <dir>/.crouter/memory/INDEX.md with an explicit project name and the workspace front-door surfaces pair ({on: workspace-open, at: content} + {on: read, match: './**', at: content}). Copies each .claude/rules/*.md into <dir>/.crouter/memory/<name>.md with a content read entry over the source paths (‘./’-anchored when repo-relative), or the same front-door pair when no paths are declared. Originals are left untouched.",
+            "Copies the repository-root CLAUDE.md/AGENTS.md into the repository-root .crouter/memory/INDEX.md with the namespace declaration and workspace front-door surfaces. Copies nested guides into nested .crouter/memory/INDEX.md files without namespace, name, or workspace-open metadata. Copies each .claude/rules/*.md into its nested store with a local name and a content read entry over the source paths (‘./’-anchored when repo-relative), or a plain read route when no paths are declared. Originals are left untouched.",
             'Skips existing memory docs unless --overwrite is present.',
             'With --dry-run: read-only; writes nothing.',
         ],
@@ -369,31 +397,86 @@ export const sysSyncProjectGuidanceLeaf = defineLeaf({
         const overwrite = input['overwrite'] ?? false;
         const results = [];
         const docSeen = new Set();
+        const candidates = [];
         for (const root of projectDocRoots(sourceArg)) {
             for (const c of collectProjectDocCandidates(root)) {
                 if (docSeen.has(c.path))
                     continue;
                 docSeen.add(c.path);
-                // Isolate one malformed source file (e.g. invalid YAML in a rule's
-                // frontmatter) as its own skipped row — it must never abort the whole
-                // migration.
-                try {
-                    const prepared = c.kind === 'agents' ? prepareAgentsCandidate(c) : prepareRuleCandidate(c);
-                    results.push(convertProjectDoc(prepared, { dryRun, overwrite }));
-                }
-                catch (e) {
-                    const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
-                    results.push({
-                        source: c.path,
-                        target: '',
-                        name: '',
-                        scope: 'project',
-                        status: 'skipped',
-                        reason: `unparseable source frontmatter: ${msg} — fix the source file and re-run`,
-                    });
-                }
+                candidates.push(c);
             }
         }
+        // Resolve each repository once. Root guide bodies are collected before
+        // resolution so derivation does not depend on discovery order.
+        const rootBodies = new Map();
+        for (const c of candidates) {
+            if (c.kind !== 'agents')
+                continue;
+            try {
+                rootBodies.set(realpathOrSelf(c.sourceDir), parseFrontmatterGeneric(readText(c.path)).body);
+            }
+            catch {
+                rootBodies.set(realpathOrSelf(c.sourceDir), undefined);
+            }
+        }
+        const resolutions = new Map();
+        const candidateResolutions = new Map();
+        for (const c of candidates) {
+            const resolution = resolveRepositoryNamespace(c.sourceDir, c.walkRoot, rootBodies, resolutions);
+            candidateResolutions.set(c.path, resolution);
+            validateAuthoredNamespace(c, resolution);
+        }
+        const preparedEntries = [];
+        for (const c of candidates) {
+            const resolution = candidateResolutions.get(c.path);
+            // Isolate one malformed source file (e.g. invalid YAML in a rule's
+            // frontmatter) as its own skipped row — it must never abort the whole
+            // migration.
+            try {
+                const prepared = c.kind === 'agents'
+                    ? prepareAgentsCandidate(c, resolution)
+                    : prepareRuleCandidate(c, resolution);
+                preparedEntries.push({ candidate: c, prepared });
+            }
+            catch (e) {
+                const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
+                results.push({
+                    source: c.path,
+                    target: '',
+                    name: '',
+                    scope: 'project',
+                    status: 'skipped',
+                    reason: `unparseable source frontmatter: ${msg} — fix the source file and re-run`,
+                });
+            }
+        }
+        // A rules-only source still needs one repository-root declaration for the
+        // store to mount. Nested rule directories never receive synthetic roots.
+        for (const resolution of resolutions.values()) {
+            const hasRootGuide = candidates.some((c) => c.kind === 'agents' && candidateResolutions.get(c.path)?.repositoryRoot === resolution.repositoryRoot && realpathOrSelf(c.sourceDir) === resolution.repositoryRoot);
+            if (hasRootGuide || openProjectMemoryStore(resolution.repositoryRoot).mountStatus === 'ready')
+                continue;
+            const first = candidates.find((c) => candidateResolutions.get(c.path)?.repositoryRoot === resolution.repositoryRoot);
+            if (first === undefined)
+                continue;
+            const syntheticCandidate = {
+                ...first,
+                kind: 'agents',
+                sourceDir: resolution.repositoryRoot,
+            };
+            const root = prepareRootCandidate(syntheticCandidate, resolution.namespace, 'Migrated project guidance.', true);
+            results.push(convertProjectDoc(root, { dryRun, overwrite }));
+        }
+        // Repository roots are always emitted before nested stores, so a real run
+        // mounts the repository before any nested content is written.
+        const ordered = [...preparedEntries].sort((a, b) => {
+            const ar = realpathOrSelf(a.candidate.sourceDir) === candidateResolutions.get(a.candidate.path).repositoryRoot;
+            const br = realpathOrSelf(b.candidate.sourceDir) === candidateResolutions.get(b.candidate.path).repositoryRoot;
+            return Number(br) - Number(ar);
+        });
+        for (const { prepared } of ordered) {
+            results.push(convertProjectDoc(prepared, { dryRun, overwrite }));
+        }
         const imported = results.filter((r) => r.status === 'imported').length;
         const wouldImport = results.filter((r) => r.status === 'would-import').length;
         const skipped = results.filter((r) => r.status === 'skipped').length;

package/dist/commands/sys/sync-skills.js

@@ -8,9 +8,10 @@ import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
 import { pathExists, readJsonIfExists, readText, walkFiles, writeJson, writeText } from '../../core/fs-utils.js';
-import { findProjectScopeRoot, scopeMemoryDir } from '../../core/scope.js';
+import { composeCanonicalName } from '../../core/memory/identity.js';
+import { findProjectScopeRoot } from '../../core/scope.js';
 import { CRTR_DIR_NAME } from '../../types.js';
-import { memoryFilePath, resolveWriteTarget, serializeMemoryDoc } from '../memory/shared.js';
+import { memoryFilePath, requireMountedStore, resolveWriteSelector, serializeMemoryDoc } from '../memory/shared.js';
 import { normalizedName, routeFromDescription, scalarString } from './sync-shared.js';
 const LEGACY_BOOT_SKILL_MARKER_PREFIX = '<!-- crtr-boot-skill v';
 const HOST_SKILL_FILE = 'SKILL.md';
@@ -44,7 +45,7 @@ function sourceRootsFromArg(sourceArg, scopeArg) {
         return defaultSourceRoots();
     const root = resolve(sourceArg);
     if (scopeArg !== undefined && scopeArg !== 'user' && scopeArg !== 'project') {
-        resolveWriteTarget(scopeArg);
+        throw usage(`invalid --scope: ${scopeArg} (expected user|project)`);
     }
     return [{ label: 'source', root, defaultScope: scopeArg ?? 'user' }];
 }
@@ -75,11 +76,18 @@ function nameForCandidate(candidate, fm) {
     const relDir = relative(candidate.root, dirname(candidate.path)).split(sep).join('/');
     return normalizedName(relDir || basename(dirname(candidate.path)));
 }
-function targetMemoryDir(scope) {
-    const dir = scopeMemoryDir(scope);
-    if (!dir)
-        return resolveWriteTarget(scope).memoryDir;
-    return dir;
+function storeResolver() {
+    const cache = new Map();
+    return (scope) => {
+        const cached = cache.get(scope);
+        if (cached !== undefined)
+            return cached;
+        const { memoryDir, store } = resolveWriteSelector({ scope });
+        requireMountedStore(store);
+        const resolved = { memoryDir, namespace: store.namespace };
+        cache.set(scope, resolved);
+        return resolved;
+    };
 }
 function readIgnoreState() {
     let doc;
@@ -134,7 +142,7 @@ function rememberIgnored(prepared, state) {
 function skipResult(candidate, scope, reason) {
     return { source: candidate.path, target: '', name: '', scope, status: 'skipped', reason };
 }
-function prepareCandidate(candidate, scopeOverride) {
+function prepareCandidate(candidate, stores, scopeOverride) {
     const raw = readText(candidate.path);
     const scope = scopeOverride ?? candidate.defaultScope;
     if (raw.includes(LEGACY_BOOT_SKILL_MARKER_PREFIX)) {
@@ -143,11 +151,12 @@ function prepareCandidate(candidate, scopeOverride) {
     const parsed = parseFrontmatterGeneric(raw);
     const sourceFm = parsed.data ?? {};
     const kind = sourceFm.kind === 'preference' ? 'preference' : 'knowledge';
-    const name = nameForCandidate(candidate, sourceFm);
-    if (name === '')
+    const localName = nameForCandidate(candidate, sourceFm);
+    if (localName === '')
         return skipResult(candidate, scope, 'could not derive memory document name');
-    const memoryDir = targetMemoryDir(scope);
-    const target = memoryFilePath(memoryDir, name);
+    const store = stores(scope);
+    const target = memoryFilePath(store.memoryDir, localName);
+    const name = composeCanonicalName(store.namespace, localName);
     return { candidate, raw, parsed, sourceFm, kind, name, scope, target };
 }
 function convertPrepared(prepared, opts) {
@@ -234,7 +243,7 @@ export const sysSyncSkillsLeaf = defineLeaf({
         summary: 'one-way import: host SKILL.md bundles → crouter memory docs',
         params: [
             { kind: 'flag', name: 'source', type: 'string', required: false, constraint: 'A SKILL.md file, a single skill bundle dir containing SKILL.md, or a skills root to scan recursively. Default: the user/project Claude and pi skill roots that exist.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Target memory scope for the selected sources. Default: user for user host roots and project for project host roots; an explicit value applies to every selected source.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Target memory scope for the selected sources. Default: user for user host roots and project for project host roots; an explicit value applies to every selected source. `project` writes into the nearest project store walking up from cwd, which must already declare its `namespace:` — this lane imports documents into a store, never the declaration itself.' },
             { kind: 'flag', name: 'dry-run', type: 'bool', required: false, constraint: 'Show what would be imported without writing memory docs.' },
             { kind: 'flag', name: 'overwrite', type: 'bool', required: false, constraint: 'Replace an existing target memory doc. Default: skip existing docs to avoid clobbering user-authored memory.' },
             { kind: 'flag', name: 'ignore', type: 'bool', required: false, constraint: `Permanently ignore every selected SKILL.md source by recording it in ~/.crouter/${IGNORE_FILE}. Honors --source/--scope; with no --source, ignores every currently discovered default host skill candidate.` },
@@ -246,11 +255,12 @@ export const sysSyncSkillsLeaf = defineLeaf({
             { name: 'skipped', type: 'number', required: true, constraint: 'Count of source files skipped (existing target without --overwrite, or an unimportable SKILL.md).' },
             { name: 'ignored', type: 'number', required: true, constraint: 'Count of selected SKILL.md files that are permanently ignored.' },
             { name: 'wouldIgnore', type: 'number', required: true, constraint: 'Count of selected SKILL.md files that would be ignored under --dry-run.' },
-            { name: 'results', type: 'object[]', required: true, constraint: 'Each: {source,target,name,scope,status,reason?}; status is one of imported, skipped, would-import, ignored, would-ignore.' },
+            { name: 'results', type: 'object[]', required: true, constraint: 'Each: {source,target,name,scope,status,reason?}; status is one of imported, skipped, would-import, ignored, would-ignore. `name` is the full canonical name the imported doc answers at — a user import’s bundle name, a project import’s `<namespace>/<bundle name>`.' },
         ],
         outputKind: 'object',
         effects: [
-            'Writes memory/<name>.md in the selected crouter scope with substrate frontmatter and the SKILL.md body.',
+            'Writes memory/<bundle name>.md in the selected crouter scope with substrate frontmatter and the SKILL.md body. The file stays store-local; a project import answers at `<namespace>/<bundle name>`.',
+            'Refuses a project store that declares no namespace, naming the `crtr sys migrate --dir` (legacy store) or `crtr memory write <namespace> --dir` (empty store) remedy; it never declares one itself.',
             'Skips existing memory docs unless --overwrite is present.',
             'Skips marker-bearing generated crtr boot skills; host exports prune those legacy artifacts instead.',
             `With --ignore: writes ~/.crouter/${IGNORE_FILE} and does not import the selected sources.`,
@@ -275,11 +285,12 @@ export const sysSyncSkillsLeaf = defineLeaf({
                 candidates.push(c);
             }
         }
+        const stores = storeResolver();
         const ignoreState = readIgnoreState();
         const results = [];
         let changedIgnoreState = false;
         for (const candidate of candidates) {
-            const prepared = prepareCandidate(candidate, scopeArg);
+            const prepared = prepareCandidate(candidate, stores, scopeArg);
             if ('status' in prepared) {
                 results.push(prepared);
                 continue;

package/dist/commands/sys/update.js

@@ -1,7 +1,9 @@
 import { defineLeaf } from '../../core/command.js';
 import { updateState } from '../../core/config.js';
 import { projectScopeRoot } from '../../core/scope.js';
-import { selfCheck, selfUpdate, contentCheck, contentUpdate } from '../../core/self-update.js';
+import { selfCheck, selfUpdate, contentCheck } from '../../core/self-update.js';
+import { marketUpdate } from '../pkg/market-manage.js';
+import { pluginUpdate } from '../pkg/plugin-manage.js';
 import { nowIso } from '../../core/fs-utils.js';
 import { processLocatedGeneration, readPackageVersion, runtimeManifest, selectedGeneration } from './shared.js';
 export const sysUpdateLeaf = defineLeaf({
@@ -26,6 +28,7 @@ export const sysUpdateLeaf = defineLeaf({
         effects: [
             '--check — read-only, bounded network calls.',
             'Default (no --check) — launches a background job; returns job handle immediately.',
+            'Content update replaces each marketplace and source-installed plugin checkout with a freshly staged revision, discarding local modifications in those directories.',
         ],
     },
     run: async (input) => {
@@ -74,7 +77,11 @@ export const sysUpdateLeaf = defineLeaf({
             const up_to_date = updates.every((u) => u.up_to_date || u.unreachable);
             return { updates: updates, up_to_date };
         }
-        // Apply path — run synchronously (selfUpdate/contentUpdate are sync spawns).
+        // Apply path. Content update owns no refresh logic of its own: it runs the
+        // same replace-in-place leaves as `pkg market update` and `pkg plugin
+        // update`, so every surface refreshes content one way. Marketplaces go
+        // first — one registered with no installed plugin is invisible to the
+        // plugin sweep.
         try {
             if (resolvedTarget === 'self' || resolvedTarget === 'all') {
                 selfUpdate();
@@ -88,7 +95,8 @@ export const sysUpdateLeaf = defineLeaf({
                 }
             }
             if (resolvedTarget === 'content' || resolvedTarget === 'all') {
-                contentUpdate();
+                await marketUpdate.run({});
+                await pluginUpdate.run({});
             }
             return { target: resolvedTarget, status: 'done' };
         }