@north-light/crouter 0.3.219 → 0.3.221

package/dist/commands/pkg/plugin-manage.js

@@ -17,8 +17,10 @@ import { validatePluginCommands, validateEffectiveCommandPlugins } from '../../c
 import { normalizeEndpoint, validateEndpoint, validateHttpPluginTransport } from '../../core/command-plugins/endpoint.js';
 import { buildBrokerEnv, resolvePathExecutable } from '../../core/runtime/spawn-env.js';
 import { validatePluginBundle } from '../../core/command-plugins/bundle.js';
+import { compileHookRegistry, discoverCandidateHookRegistry, discoverCandidateHookRegistryForCandidates, discoverHookRegistry } from '../../core/command-hooks/discovery.js';
+import { hasDeclaredHooks, hookReport } from '../../core/command-hooks/report.js';
 import { fetchHttpPluginBundle } from '../../core/command-plugins/transport/http-fetch.js';
-import { SUBTREE_NAMES, coreCommandPaths } from '../../build-root.js';
+import { SUBTREE_NAMES, coreCommandPaths, coreHookCatalog } from '../../build-root.js';
 import { isGitUrl, setPluginEnabled, resolveInstallScope } from './shared.js';
 /** Validate a just-installed/updated plugin's command manifest, if it declares
  *  one. Returns undefined for plugins without a `commands` pointer. Never
@@ -121,9 +123,44 @@ function assertManifestPageComponentsValid(manifest, where) {
         throw general(`plugin manifest at ${where} declares an invalid page_components block:\n${reasons.map((r) => `- ${r}`).join('\n')}`, { issues: reasons });
     }
 }
+/** Static hook report for an installed plugin. An inactive/shadowed plugin
+ * still receives its own artifact and target validation; only effective plugins
+ * additionally carry collisions from the complete active registry. */
+async function hookLifecycleReport(name, scope) {
+    const plugin = findPluginByName(name, scope);
+    if (plugin === null || !hasDeclaredHooks(plugin.manifest))
+        return undefined;
+    const catalog = await coreHookCatalog();
+    const effective = discoverHookRegistry(catalog);
+    const validation = effective.validations.find((entry) => entry.plugin.root === plugin.root);
+    if (validation === undefined) {
+        const isolated = compileHookRegistry(catalog, [plugin]);
+        return hookReport(isolated.validations[0]);
+    }
+    return hookReport(validation, effective.issues.filter((issue) => issue.plugin === plugin.name && issue.scope === plugin.scope));
+}
+/** Validate a source candidate's complete hook behavior before activation. The
+ * candidate claims its future scope/name slot, so stale targets and replacement
+ * collisions reject the candidate without disturbing installed bytes. */
+async function assertManifestHooksValid(manifest, root, scope, scopeRootPath, where, candidates) {
+    if (!hasDeclaredHooks(manifest))
+        return;
+    const candidate = { name: manifest.name, scope, root, manifest, enabled: true };
+    const registryCandidates = candidates ?? [{ plugin: candidate, scopeRoot: scopeRootPath }];
+    const catalog = await coreHookCatalog();
+    const effective = candidates === undefined
+        ? discoverCandidateHookRegistry(catalog, candidate, scopeRootPath)
+        : discoverCandidateHookRegistryForCandidates(catalog, registryCandidates);
+    const validation = effective.validations.find((entry) => entry.plugin.root === root);
+    const issues = validation === undefined
+        ? compileHookRegistry(catalog, [candidate]).issues
+        : effective.issues.filter((issue) => issue.plugin === candidate.name && issue.scope === candidate.scope);
+    if (issues.length > 0)
+        throw invalidBundleError(`plugin hook behavior at ${where} is invalid`, issues);
+}
 /** Validate a package candidate before it gains an active plugin path. The
  * candidate namespace shadows any installed declaration of the same name. */
-function assertPluginCandidateValid(manifest, root, scope, scopeRootPath, where) {
+export async function assertPluginCandidateValid(manifest, root, scope, scopeRootPath, where, candidates) {
     try {
         validatePluginManifestMemoryExtensions(manifest);
     }
@@ -135,6 +172,11 @@ function assertPluginCandidateValid(manifest, root, scope, scopeRootPath, where)
     assertManifestPageComponentsValid(manifest, where);
     assertManifestBinValid(manifest, where);
     assertManifestRequiresValid(manifest, where);
+    const commandValidation = validatePluginCommands({ name: manifest.name, scope, root, manifest, enabled: true }, new Set(SUBTREE_NAMES), await coreCommandPaths());
+    if (commandValidation.issues.length > 0) {
+        throw invalidBundleError(`plugin command behavior at ${where} is invalid`, commandValidation.issues);
+    }
+    await assertManifestHooksValid(manifest, root, scope, scopeRootPath, where, candidates);
     const memoryDir = join(root, 'memory');
     const catalogDocPath = join(scopeRootPath, 'memory', '__plugin_candidate__.md');
     for (const file of walkFiles(memoryDir, (name) => name.endsWith('.md'), (dir) => dir.startsWith('.'))) {
@@ -176,7 +218,7 @@ function writeStagedBundle(stagingRoot, manifest, bundle) {
     }
 }
 async function validateStagedBundle(name, scope, root, scopeRootPath, manifest) {
-    assertPluginCandidateValid(manifest, root, scope, scopeRootPath, `${root}/.crouter-plugin/plugin.json`);
+    await assertPluginCandidateValid(manifest, root, scope, scopeRootPath, `${root}/.crouter-plugin/plugin.json`);
     const staged = { name, scope, root, manifest, enabled: true };
     const validation = validatePluginCommands(staged, new Set(SUBTREE_NAMES), await coreCommandPaths());
     if (validation.issues.length > 0) {
@@ -300,10 +342,10 @@ function classifyInstallRef(raw) {
     throw usage(`invalid plugin install ref: ${raw}\n` +
         'Accepted forms: marketplace/plugin, git URL (https://, ssh://, git@, file://, or *.git), or local path starting ./, ../, or /. Bare plugin names are not install refs.');
 }
-function isMarketplaceRelativeSource(source) {
+export function isMarketplaceRelativeSource(source) {
     return source.startsWith('./') || source.startsWith('../') || (!isAbsolute(source) && !isGitUrl(source));
 }
-function refreshMarketplace(name, cache, opts) {
+async function refreshMarketplace(name, cache, opts) {
     const cached = cache.get(name);
     if (cached !== undefined)
         return cached;
@@ -349,7 +391,7 @@ function refreshMarketplace(name, cache, opts) {
             if (candidateManifest === null)
                 throw notFound(`plugin manifest not found in marketplace candidate: ${candidateRoot}/.crouter-plugin/plugin.json`);
             const pluginScopeRoot = plugin.scope === 'project' ? requireScopeRoot('project') : userScopeRoot();
-            assertPluginCandidateValid(candidateManifest, candidateRoot, plugin.scope, pluginScopeRoot, `${candidateRoot}/.crouter-plugin/plugin.json`);
+            await assertPluginCandidateValid(candidateManifest, candidateRoot, plugin.scope, pluginScopeRoot, `${candidateRoot}/.crouter-plugin/plugin.json`);
         }
         renameSync(marketplace.root, previous);
         try {
@@ -397,7 +439,7 @@ function updatePluginVersion(scope, name, version) {
         s.plugins[name].last_updated = nowIso();
     });
 }
-function installFromGit(source, ref, scope) {
+async function installFromGit(source, ref, scope) {
     const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
     ensureScopeInitialized(scope, scopeRootPath);
     const pDir = join(scopeRootPath, 'plugins');
@@ -409,7 +451,7 @@ function installFromGit(source, ref, scope) {
         const manifest = readPluginManifest(staging);
         if (manifest === null)
             throw general(`cloned repo does not contain a valid .crouter-plugin/plugin.json: ${source}`);
-        assertPluginCandidateValid(manifest, staging, scope, scopeRootPath, `${source}/.crouter-plugin/plugin.json`);
+        await assertPluginCandidateValid(manifest, staging, scope, scopeRootPath, `${source}/.crouter-plugin/plugin.json`);
         const finalDir = join(pDir, manifest.name);
         if (pathExists(finalDir))
             throw general(`plugin "${manifest.name}" is already installed at ${finalDir}`);
@@ -424,14 +466,14 @@ function installFromGit(source, ref, scope) {
         removePath(staging);
     }
 }
-function installFromLocal(source, scope) {
+async function installFromLocal(source, scope) {
     const sourcePath = resolve(source);
     const manifest = readPluginManifest(sourcePath);
     if (manifest === null) {
         throw notFound(`plugin manifest not found at ${sourcePath}/.crouter-plugin/plugin.json`);
     }
     const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
-    assertPluginCandidateValid(manifest, sourcePath, scope, scopeRootPath, `${sourcePath}/.crouter-plugin/plugin.json`);
+    await assertPluginCandidateValid(manifest, sourcePath, scope, scopeRootPath, `${sourcePath}/.crouter-plugin/plugin.json`);
     ensureScopeInitialized(scope, scopeRootPath);
     const destDir = join(scopeRootPath, 'plugins', manifest.name);
     if (pathExists(destDir)) {
@@ -449,8 +491,8 @@ function installFromLocal(source, scope) {
 /** Install one marketplace plugin into a scope. Exported so `sys setup` can
  *  install the default plugin set through the same path `pkg plugin install`
  *  uses — refresh the source, resolve the entry, link/clone, register. */
-export function installFromMarketplace(ref, scope) {
-    const refreshed = refreshMarketplace(ref.marketplace, new Map(), { strict: true });
+export async function installFromMarketplace(ref, scope) {
+    const refreshed = await refreshMarketplace(ref.marketplace, new Map(), { strict: true });
     if (refreshed === null)
         throw notFound(`marketplace not found: ${ref.marketplace}`);
     const entry = refreshed.manifest.plugins.find((p) => p.name === ref.plugin);
@@ -470,7 +512,7 @@ export function installFromMarketplace(ref, scope) {
         const candidateManifest = readPluginManifest(sourcePath);
         if (candidateManifest === null)
             throw notFound(`plugin manifest not found at ${sourcePath}/.crouter-plugin/plugin.json`);
-        assertPluginCandidateValid(candidateManifest, sourcePath, scope, destRoot, `${sourcePath}/.crouter-plugin/plugin.json`);
+        await assertPluginCandidateValid(candidateManifest, sourcePath, scope, destRoot, `${sourcePath}/.crouter-plugin/plugin.json`);
         linkOrCopy(sourcePath, destPluginDir);
         pluginManifest = candidateManifest;
     }
@@ -482,7 +524,7 @@ export function installFromMarketplace(ref, scope) {
             const candidateManifest = readPluginManifest(staging);
             if (candidateManifest === null)
                 throw notFound(`plugin manifest not found at ${staging}/.crouter-plugin/plugin.json`);
-            assertPluginCandidateValid(candidateManifest, staging, scope, destRoot, `${staging}/.crouter-plugin/plugin.json`);
+            await assertPluginCandidateValid(candidateManifest, staging, scope, destRoot, `${staging}/.crouter-plugin/plugin.json`);
             ensureDir(join(destRoot, 'plugins'));
             renameSync(staging, destPluginDir);
             pluginManifest = candidateManifest;
@@ -503,13 +545,13 @@ export function installFromMarketplace(ref, scope) {
     });
     return { name: ref.plugin, scope, path: destPluginDir };
 }
-function updateGitPluginCandidate(plugin) {
+async function updateGitPluginCandidate(plugin) {
     if (isSymlink(plugin.root)) {
         const manifest = readPluginManifest(plugin.root);
         if (manifest === null)
             throw notFound(`plugin manifest not found at ${plugin.root}/.crouter-plugin/plugin.json`);
         const scopeRootPath = plugin.scope === 'project' ? requireScopeRoot('project') : userScopeRoot();
-        assertPluginCandidateValid(manifest, plugin.root, plugin.scope, scopeRootPath, `${plugin.root}/.crouter-plugin/plugin.json`);
+        await assertPluginCandidateValid(manifest, plugin.root, plugin.scope, scopeRootPath, `${plugin.root}/.crouter-plugin/plugin.json`);
         return { updated: false, sha: currentSha(plugin.root) ?? '', manifest };
     }
     if (!isGitRepo(plugin.root)) {
@@ -517,7 +559,7 @@ function updateGitPluginCandidate(plugin) {
         if (manifest === null)
             throw notFound(`plugin manifest not found at ${plugin.root}/.crouter-plugin/plugin.json`);
         const scopeRootPath = plugin.scope === 'project' ? requireScopeRoot('project') : userScopeRoot();
-        assertPluginCandidateValid(manifest, plugin.root, plugin.scope, scopeRootPath, `${plugin.root}/.crouter-plugin/plugin.json`);
+        await assertPluginCandidateValid(manifest, plugin.root, plugin.scope, scopeRootPath, `${plugin.root}/.crouter-plugin/plugin.json`);
         return { updated: false, sha: '', manifest };
     }
     const remote = gitSync(['config', '--get', 'remote.origin.url'], plugin.root).stdout.trim();
@@ -536,7 +578,7 @@ function updateGitPluginCandidate(plugin) {
         const manifest = readPluginManifest(staging);
         if (manifest === null)
             throw notFound(`plugin manifest not found in update candidate: ${staging}/.crouter-plugin/plugin.json`);
-        assertPluginCandidateValid(manifest, staging, plugin.scope, scopeRootPath, `${staging}/.crouter-plugin/plugin.json`);
+        await assertPluginCandidateValid(manifest, staging, plugin.scope, scopeRootPath, `${staging}/.crouter-plugin/plugin.json`);
         renameSync(plugin.root, previous);
         try {
             renameSync(staging, plugin.root);
@@ -566,16 +608,17 @@ async function updateOnePlugin(plugin, marketplaceCache, opts) {
     let marketplaceVersion;
     let marketplaceUpdated = false;
     if (plugin.sourceMarketplace !== undefined) {
-        const refreshed = refreshMarketplace(plugin.sourceMarketplace, marketplaceCache, opts);
+        const refreshed = await refreshMarketplace(plugin.sourceMarketplace, marketplaceCache, opts);
         if (refreshed !== null) {
             const entry = refreshed.manifest.plugins.find((candidate) => candidate.name === plugin.name);
             marketplaceVersion = entry?.version;
             marketplaceUpdated = refreshed.pull.updated;
         }
     }
-    const candidate = updateGitPluginCandidate(plugin);
+    const candidate = await updateGitPluginCandidate(plugin);
     updatePluginVersion(plugin.scope, plugin.name, marketplaceVersion ?? candidate.manifest.version);
     const commands = await commandReport(plugin.name, plugin.scope);
+    const hooks = await hookLifecycleReport(plugin.name, plugin.scope);
     const warnings = missingRequirementWarnings(candidate.manifest);
     return {
         name: plugin.name,
@@ -583,6 +626,7 @@ async function updateOnePlugin(plugin, marketplaceCache, opts) {
         updated: marketplaceUpdated || candidate.updated,
         sha: candidate.sha,
         ...(commands !== undefined ? { commands } : {}),
+        ...(hooks !== undefined ? { hooks } : {}),
         ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
@@ -611,6 +655,7 @@ export const pluginInstall = defineLeaf({
             { name: 'kinds', type: 'integer', required: false, constraint: 'Kind-registry entry count declared by an --endpoint archive\u2019s bundle.json.' },
             { name: 'pageComponents', type: 'integer', required: false, constraint: 'Page-component registration count declared by an --endpoint archive\u2019s bundle.json.' },
             { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest. {mounts: string[] (accepted top-level command names now live for the next invocation), issues: object[] (typed validation issues that rejected a contribution — {code, path?, message, received, expected, next})}. Validated statically; commands are never executed.' },
+            { name: 'hooks', type: 'object', required: false, constraint: 'Present only when the source plugin declares hooks. {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], issues: object[], trust: string}. Declarations, eligible targets, and replacement collisions are validated statically; hook executables are never run.' },
             { name: 'warnings', type: 'string[]', required: false, constraint: 'Advisory missing PATH executable requirements declared by the installed plugin. The install still succeeds and leaves the plugin enabled.' },
         ],
         outputKind: 'object',
@@ -618,6 +663,7 @@ export const pluginInstall = defineLeaf({
             'A ref install clones, links, or copies the plugin into the scope plugins directory and registers it with enabled=true. Marketplace installs refresh the source marketplace before resolving the plugin entry.',
             'An --endpoint install fetches and validates one authenticated uncompressed tar archive before writing. It replaces the complete plugin directory with synthesized provenance and invocation metadata, commands.json, memory docs, any kind-registry entries the bundle.json declares (they join the launch registry below this scope\u2019s own config.json kinds), and any page components it declares (they join the active page-component catalog alongside the user config entries); a fetch or validation failure preserves the prior package.',
             'If the plugin declares a command manifest, its commands go live on the next crtr invocation. Exec commands run trusted local code only when explicitly invoked; HTTP commands call their declared endpoint only when explicitly invoked.',
+            'Source plugin hooks go live on the next crtr invocation. They run implicitly with caller authority, may receive normalized inputs and after results, may block or replace declared targets, and may transmit received data. Hook executables are never run during install or update validation.',
             'A plugin manifest `requires` declaration is checked against the PATH a node bash receives after install. Missing executables emit a warning with the declared install hint but never fail the install, disable the plugin, or remove its bare-binary contributions.',
         ],
     },
@@ -644,16 +690,18 @@ export const pluginInstall = defineLeaf({
         if (authEnv !== undefined)
             throw usage('--auth-env is only valid with --endpoint');
         const classified = classifyInstallRef(rawRef);
-        const installed = classified.kind === 'marketplace' ? installFromMarketplace(classified.value, scope)
-            : classified.kind === 'local' ? installFromLocal(classified.value, scope)
-                : installFromGit(classified.value, gitRef, scope);
+        const installed = classified.kind === 'marketplace' ? await installFromMarketplace(classified.value, scope)
+            : classified.kind === 'local' ? await installFromLocal(classified.value, scope)
+                : await installFromGit(classified.value, gitRef, scope);
         const plugin = findPluginByName(installed.name, installed.scope);
         const commands = await commandReport(installed.name, installed.scope);
+        const hooks = await hookLifecycleReport(installed.name, installed.scope);
         const warnings = plugin === null ? [] : missingRequirementWarnings(plugin.manifest);
         return {
             ...installed,
             ...(plugin?.manifest.transport !== undefined ? { transport: plugin.manifest.transport.kind } : {}),
             ...(commands !== undefined ? { commands } : {}),
+            ...(hooks !== undefined ? { hooks } : {}),
             ...(warnings.length > 0 ? { warnings } : {}),
         };
     },
@@ -766,7 +814,7 @@ export const pluginUpdate = defineLeaf({
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution.' },
         ],
         output: [
-            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, transport?, updated, sha?, version?, docs?, kinds?, pageComponents?, commands?, warnings?, error?}. Archive plugins report transport=http and replace their complete directory after an authenticated refetch; version is the archive content identifier, docs is the written memory-document count, kinds is the declared kind-registry entry count, and pageComponents is the declared page-component registration count. sha is present for git updates. A bulk update reports and skips a failed archive plugin. commands is present for validated command plugins: {mounts: string[], issues: object[]}. warnings lists advisory PATH requirements that remain absent after update.' },
+            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, transport?, updated, sha?, version?, docs?, kinds?, pageComponents?, commands?, hooks?, warnings?, error?}. Archive plugins report transport=http and replace their complete directory after an authenticated refetch; version is the archive content identifier, docs is the written memory-document count, kinds is the declared kind-registry entry count, and pageComponents is the declared page-component registration count. sha is present for git updates. A bulk update reports and skips a failed archive plugin. commands is present for validated command plugins: {mounts: string[], issues: object[]}. hooks is present for source hook plugins: {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], issues: object[], trust: string}; it is static and never executes hooks. warnings lists advisory PATH requirements that remain absent after update.' },
         ],
         outputKind: 'object',
         effects: ['Archive plugins unconditionally re-fetch, validate, and replace their complete package; a named failure exits nonzero and preserves the prior package. Bulk update reports a failed archive plugin and continues. Source-installed plugins retain their source update, version, and last_updated behavior.'],

package/dist/commands/profile/default.js

@@ -1,8 +1,4 @@
-// `crtr profile default` — the per-cwd default-profile pin. A pin says "when a
-// node boots in THIS directory, use THIS profile" and stops the startup
-// chooser from asking. It is directory-scoped, not manifest state: independent
-// of a profile's project purview (`crtr profile project`). The startup menu's
-// `d` action writes the same pin; these verbs are the explicit surface for it.
+// `crtr profile default` manages the per-cwd profile-selection pin.
 import { defineLeaf, defineBranch } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { loadProfileManifest } from '../../core/profiles/manifest.js';
@@ -11,7 +7,7 @@ import { getDefaultProfileId, setDefaultProfileId, clearDefaultProfile, resolveB
 const setLeaf = defineLeaf({
     name: 'set',
     description: 'pin a profile as the default for the current directory',
-    whenToUse: 'you want crtr to stop asking which profile to use here and always default to a chosen one — the command form of the startup menu\u2019s `d` action. The profile must already cover this directory (add it with `crtr profile project add` first if not).',
+    whenToUse: 'you want crtr to stop asking which profile to use here and always default to a chosen one — the command form of the startup menu\u2019s `d` action. The profile must already cover this directory (add its purview relationship with `profile project add` and required `--memory` first if not).',
     help: {
         name: 'profile default set',
         summary: "pin a profile as the current directory's default, so the startup chooser stops asking",
@@ -20,7 +16,7 @@ const setLeaf = defineLeaf({
                 kind: 'positional',
                 name: 'profile',
                 required: true,
-                constraint: 'Exact profile id, or a unique manifest name. Must already cover the current directory (be at/above/below it in its project purview).',
+                constraint: 'Exact profile id, or a unique manifest name. Must already cover the current directory (be at/above/below it in its project purview); this pin does not change automatic memory disclosure.',
             },
         ],
         output: [
@@ -40,7 +36,7 @@ const setLeaf = defineLeaf({
             throw new InputError({
                 error: 'not_covered',
                 message: `profile "${entry.manifest.name}" does not cover ${resolved}, so a default pinned here would be ignored.`,
-                next: `Widen its purview first: \`crtr profile project add ${entry.profileId} --dir ${resolved}\`, then re-run this.`,
+                next: `Widen its purview and choose its automatic memory disclosure cap first: \`crtr profile project add ${entry.profileId} --dir ${resolved} --memory <none|name|preview|content>\`, then re-run this.`,
             });
         }
         setDefaultProfileId(cwd, entry.profileId);
@@ -133,11 +129,11 @@ const showLeaf = defineLeaf({
 export const defaultBranch = defineBranch({
     name: 'default',
     description: "manage this directory's default-profile pin",
-    whenToUse: "setting, clearing, or inspecting which profile a directory defaults to at startup — so crtr stops asking. Directory-scoped, independent of a profile's project purview.",
+    whenToUse: "setting, clearing, or inspecting which profile a directory defaults to at startup — so crtr stops asking. Directory-scoped, independent of project purview and automatic memory disclosure.",
     help: {
         name: 'profile default',
         summary: "the per-directory default profile — pin one so the startup chooser stops asking",
-        model: "A pin binds the CURRENT directory to a profile: launches here auto-pick it with no prompt (`crtr --pick-profile` reopens the chooser once). `set` pins a profile (which must already cover this dir), `clear` removes the pin, `show` reports it. This is directory-scoped selection, NOT manifest state — independent of `crtr profile project` (a profile's purview). The startup menu's `d` action writes the same pin.",
+        model: "A pin binds the CURRENT directory to a profile: launches here auto-pick it with no prompt (`crtr --pick-profile` reopens the chooser once). `set` pins a profile (which must already cover this dir), `clear` removes the pin, `show` reports it. This is directory-scoped selection, independent of `crtr profile project`: project `path` values govern purview and each `memory` value caps automatic disclosure. The startup menu's `d` action writes the same pin.",
     },
     children: [setLeaf, clearLeaf, showLeaf],
 });

package/dist/commands/profile/list.js

@@ -3,15 +3,16 @@ import { emitLine } from '../../core/io.js';
 import { listProfiles } from '../../core/profiles/manifest.js';
 export const listLeaf = defineLeaf({
     name: 'list',
-    description: 'inventory every profile',
-    whenToUse: 'browse every profile that exists — one line each with its id, name, project count, home directory, paused state, and last-used time. Reach for `profile show` once you have picked one, for its full manifest.',
+    description: 'inventory every profile and its project relationships',
+    whenToUse: 'browse every profile that exists — one line each with its id, name, explicit project relationships, home directory, paused state, and last-used time. Reach for `profile show` once you have picked one, for its full manifest.',
     help: {
         name: 'profile list',
         summary: 'every profile as JSONL, one line each, sorted by name then profile_id',
         output: [
             { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
             { name: 'name', type: 'string', required: true, constraint: 'Manifest name.' },
-            { name: 'projects_count', type: 'int', required: true, constraint: 'Number of project directories on the manifest.' },
+            { name: 'projects_count', type: 'int', required: true, constraint: 'Number of `{path, memory}` project relationships on the manifest.' },
+            { name: 'projects', type: 'ProfileProject[]', required: true, constraint: 'Explicit `{path, memory}` relationships in manifest order. `path` defines profile purview; `memory` caps automatic boot and workspace-open disclosure.' },
             { name: 'home', type: 'string | null', required: true, constraint: 'Directory the profile\u2019s nodes are pinned to, or null when it owns no projects.' },
             { name: 'paused_at', type: 'string | null', required: true, constraint: 'ISO 8601 pause timestamp, or null when the profile is active.' },
             { name: 'default_kind', type: 'string | null', required: true, constraint: 'Stored default node kind, or null when creates default to general.' },
@@ -30,6 +31,7 @@ export const listLeaf = defineLeaf({
                 profile_id: profileId,
                 name: manifest.name,
                 projects_count: manifest.projects.length,
+                projects: manifest.projects,
                 home: manifest.home,
                 paused_at: manifest.paused_at,
                 default_kind: manifest.default_kind ?? null,

package/dist/commands/profile/new.js

@@ -2,6 +2,7 @@ import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
 import { assertInstalledKind } from '../../core/config.js';
 import { createProfile, ensureRootProfile, profileRoot } from '../../core/profiles/manifest.js';
+import { PROFILE_PROJECT_MEMORY_VALUES } from '../../api/dto/profiles.js';
 import { resolveMetaPairs } from './meta.js';
 export const newLeaf = defineLeaf({
     name: 'new',
@@ -23,14 +24,22 @@ export const newLeaf = defineLeaf({
                 name: 'root',
                 type: 'bool',
                 required: false,
-                constraint: 'Provision the canonical stable root profile (fixed id `root-00000000`, name `root`) — the fallback default identity for a home — instead of a fresh named one. Idempotent: re-running returns the existing root. Node-free (no `node new --root` needed). Mutually exclusive with `--name`/`--project`/`--default-kind`/`--meta`.',
+                constraint: 'Provision the canonical stable root profile (fixed id `root-00000000`, name `root`) — the fallback default identity for a home — instead of a fresh named one. Idempotent: re-running returns the existing root. Node-free (no `node new --root` needed). Mutually exclusive with `--name`/`--project`/`--memory`/`--default-kind`/`--meta`.',
             },
             {
                 kind: 'flag',
                 name: 'project',
                 type: 'path',
                 required: false,
-                constraint: "One initial project directory. Must already exist and be a directory; resolved to its absolute real path before storing. Also becomes the profile's home — where its nodes are pinned. Singular — add more with `crtr profile project add` after creation.",
+                constraint: "One initial project directory. Must already exist and be a directory; resolved to its absolute real path before storing. Creates a purview relationship and becomes the profile's home — where its nodes are pinned. Requires paired `--memory`; singular — add more with `crtr profile project add` after creation.",
+            },
+            {
+                kind: 'flag',
+                name: 'memory',
+                type: 'enum',
+                choices: [...PROFILE_PROJECT_MEMORY_VALUES],
+                required: false,
+                constraint: 'Required with `--project`; invalid without it. Maximum automatic memory disclosure from this project at boot and workspace-open: `none`, `name`, `preview`, or `content`. Does not change purview or explicit `crtr memory read` access.',
             },
             {
                 kind: 'flag',
@@ -52,7 +61,7 @@ export const newLeaf = defineLeaf({
             { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id (`<slug>-<shortid>`). Pass this, or the name, to every other `profile` verb and to `--profile` elsewhere.' },
             { name: 'name', type: 'string', required: true, constraint: 'The manifest name as given.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the profile directory.' },
-            { name: 'projects', type: 'string[]', required: true, constraint: 'Resolved absolute project directories, in manifest order. Empty when --project was omitted.' },
+            { name: 'projects', type: 'ProfileProject[]', required: true, constraint: 'Explicit `{path, memory}` project relationships in manifest order. `path` defines purview; `memory` caps automatic boot and workspace-open disclosure. Empty when --project was omitted.' },
             { name: 'home', type: 'string | null', required: true, constraint: 'Directory the profile\u2019s nodes are pinned to — the initial project, or null when none was given.' },
             { name: 'default_kind', type: 'string | null', required: true, constraint: 'Stored default persona kind, or null when node creates default to general.' },
             { name: 'metadata', type: 'object', required: true, constraint: 'Stored metadata map; empty when --meta was omitted.' },
@@ -65,12 +74,13 @@ export const newLeaf = defineLeaf({
     run: async (input) => {
         const name = input['name'];
         const project = input['project'];
+        const memory = input['memory'];
         const defaultKind = input['defaultKind'];
         const metadata = resolveMetaPairs(input['meta'], 'meta');
         const root = input['root'] === true;
         if (root) {
-            if (name !== undefined || project !== undefined || defaultKind !== undefined || Object.keys(metadata).length > 0) {
-                throw usage('`--root` provisions the canonical stable root profile and takes no `--name`/`--project`/`--default-kind`/`--meta`.');
+            if (name !== undefined || project !== undefined || memory !== undefined || defaultKind !== undefined || Object.keys(metadata).length > 0) {
+                throw usage('`--root` provisions the canonical stable root profile and takes no `--name`/`--project`/`--memory`/`--default-kind`/`--meta`.');
             }
             const { profileId, manifest } = ensureRootProfile();
             return {
@@ -82,14 +92,17 @@ export const newLeaf = defineLeaf({
                 default_kind: manifest.default_kind ?? null,
                 metadata: manifest.metadata ?? {},
                 created_at: manifest.created_at,
-                follow_up: `Root profile ensured. Spawn nodes under it with \`--profile ${profileId}\`, or widen its purview with \`crtr profile project add ${profileId} --dir <path>\`.`,
+                follow_up: `Root profile ensured. Spawn nodes under it with \`--profile ${profileId}\`, or widen its purview and choose its automatic memory disclosure cap with \`crtr profile project add ${profileId} --dir <path> --memory <none|name|preview|content>\`.`,
             };
         }
         if (name === undefined)
             throw usage('provide `--name <name>` to create a profile, or `--root` to provision the stable root profile.');
+        if ((project === undefined) !== (memory === undefined)) {
+            throw usage('`--project` and `--memory` must be supplied together: `--project` establishes purview and `--memory` sets its automatic boot and workspace-open disclosure cap.');
+        }
         if (defaultKind !== undefined)
             assertInstalledKind(defaultKind);
-        const { profileId, manifest } = createProfile(name, project !== undefined ? [project] : [], {
+        const { profileId, manifest } = createProfile(name, project !== undefined && memory !== undefined ? [{ path: project, memory }] : [], {
             defaultKind,
             ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
         });
@@ -102,7 +115,7 @@ export const newLeaf = defineLeaf({
             default_kind: manifest.default_kind ?? null,
             metadata: manifest.metadata ?? {},
             created_at: manifest.created_at,
-            follow_up: `Show it with \`crtr profile show ${profileId}\`, add another project with \`crtr profile project add ${profileId} --dir <path>\`, or list every profile with \`crtr profile list\`.`,
+            follow_up: `Show it with \`crtr profile show ${profileId}\`, add purview and choose its automatic memory disclosure cap with \`crtr profile project add ${profileId} --dir <path> --memory <none|name|preview|content>\`, or list every profile with \`crtr profile list\`.`,
         };
     },
 });

package/dist/commands/profile/project.js

@@ -1,17 +1,14 @@
-// `crtr profile project` — the project-purview sub-noun of `profile`. A
-// profile's `projects` list is what it can SEE (memory + config resolution),
-// and its `home` — one of those dirs — is where its nodes actually run. These
-// two verbs widen or narrow that list after creation and re-point the home;
-// `crtr profile show` reads both back.
+// `crtr profile project` manages purview relationships and their automatic-memory caps.
 import { defineLeaf, defineBranch } from '../../core/command.js';
 import { addProfileProject, removeProfileProject, loadProfileManifest } from '../../core/profiles/manifest.js';
+import { PROFILE_PROJECT_MEMORY_VALUES } from '../../api/dto/profiles.js';
 const addLeaf = defineLeaf({
     name: 'add',
-    description: "add a project directory to a profile's purview",
-    whenToUse: "a profile needs to see (memory + config from) another project directory — extend its purview after creation, including mid-session from a node already running under that profile. Also the way to re-point the profile's home, with --home.",
+    description: "add or update a project's purview relationship",
+    whenToUse: "a profile needs purview over another project directory, or its automatic memory disclosure cap needs changing — extend or update the relationship after creation. Also the way to re-point the profile's home, with --home.",
     help: {
         name: 'profile project add',
-        summary: "append a project directory to a profile's manifest, deduped by real path",
+        summary: "add or update a project relationship in a profile's manifest, deduped by real path",
         params: [
             {
                 kind: 'positional',
@@ -24,7 +21,15 @@ const addLeaf = defineLeaf({
                 name: 'dir',
                 type: 'path',
                 required: true,
-                constraint: 'Directory to add. Must exist and be a directory; resolved to its absolute real path before storing. A path already on the manifest is a no-op, not an error.',
+                constraint: 'Directory to add. Must exist and be a directory; resolved to its absolute real path before storing. A path already on the manifest keeps its position and updates its `memory` value.',
+            },
+            {
+                kind: 'flag',
+                name: 'memory',
+                type: 'enum',
+                choices: [...PROFILE_PROJECT_MEMORY_VALUES],
+                required: true,
+                constraint: 'Maximum automatic memory disclosure from this project at boot and workspace-open: `none`, `name`, `preview`, or `content`. Does not change the profile’s purview or explicit `crtr memory read` access.',
             },
             {
                 kind: 'flag',
@@ -36,16 +41,17 @@ const addLeaf = defineLeaf({
         ],
         output: [
             { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
-            { name: 'projects', type: 'string[]', required: true, constraint: 'The updated, deduped project list in manifest order.' },
+            { name: 'projects', type: 'ProfileProject[]', required: true, constraint: 'The updated `{path, memory}` relationships in manifest order. `path` defines purview; `memory` caps automatic boot and workspace-open disclosure.' },
             { name: 'home', type: 'string | null', required: true, constraint: "The profile's home directory after the change." },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
         ],
         outputKind: 'object',
-        effects: ["Appends to the profile manifest's `projects` array, and rewrites `home` when --home is given. Invalidates the process scope cache."],
+        effects: ["Appends a new project relationship or updates an existing relationship’s `memory` in the profile manifest, and rewrites `home` when --home is given. Purview follows `path`; `memory` caps automatic boot and workspace-open disclosure. Invalidates the process scope cache."],
     },
     run: async (input) => {
         const { profileId } = loadProfileManifest(input['profile']);
         const { manifest } = addProfileProject(profileId, input['dir'], {
+            memory: input['memory'],
             home: input['home'] === true,
         });
         return {
@@ -58,7 +64,7 @@ const addLeaf = defineLeaf({
 });
 const removeLeaf = defineLeaf({
     name: 'remove',
-    description: "remove a project directory from a profile's purview",
+    description: "remove a project relationship from a profile's purview",
     whenToUse: "a profile no longer needs purview over one of its listed project directories — narrow it back. Works even if the directory itself was since deleted.",
     help: {
         name: 'profile project remove',
@@ -75,17 +81,17 @@ const removeLeaf = defineLeaf({
                 name: 'dir',
                 type: 'path',
                 required: true,
-                constraint: 'Directory to remove, matched by its resolved real path against the manifest. Does not require the directory to still exist on disk. Removing the home dir re-points the home at the first remaining project.',
+                constraint: 'Directory to remove, matched against the stored project `path`. Does not require the directory to still exist on disk. Removing the home dir re-points the home at the first remaining project.',
             },
         ],
         output: [
             { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
-            { name: 'projects', type: 'string[]', required: true, constraint: 'The updated project list in manifest order.' },
+            { name: 'projects', type: 'ProfileProject[]', required: true, constraint: 'The updated `{path, memory}` relationships in manifest order.' },
             { name: 'home', type: 'string | null', required: true, constraint: "The profile's home directory after the change." },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
         ],
         outputKind: 'object',
-        effects: ["Removes an entry from the profile manifest's `projects` array, re-pointing `home` when that entry was it. Invalidates the process scope cache."],
+        effects: ["Removes a project relationship from the profile manifest, re-pointing `home` when that entry was it. This narrows purview and removes its automatic memory disclosure cap. Invalidates the process scope cache."],
     },
     run: async (input) => {
         const { profileId } = loadProfileManifest(input['profile']);
@@ -100,12 +106,12 @@ const removeLeaf = defineLeaf({
 });
 export const projectBranch = defineBranch({
     name: 'project',
-    description: "widen or narrow a profile's project purview",
-    whenToUse: "changing which project directories a profile can see (its memory + config resolution) after creation — add or remove one.",
+    description: "manage a profile's project purview and automatic memory disclosure",
+    whenToUse: "changing a profile’s project purview or one relationship’s automatic memory disclosure cap after creation — add, update, or remove one.",
     help: {
         name: 'profile project',
-        summary: "manage a profile's project purview — the directories it resolves memory and config from",
-        model: "A profile's `projects` list is the set of directories it inherits memory and config from, and its `home` — the first project unless `add --home` says otherwise — is the directory its nodes are pinned to. `add` widens that purview by one directory (deduped by real path) and optionally re-points the home; `remove` narrows it, re-pointing the home when it removed it. Read both back with `crtr profile show`. Purview is independent of a per-cwd default pin (`crtr profile default`) — widening purview never changes which profile a directory defaults to.",
+        summary: "manage project purview and automatic memory disclosure caps",
+        model: "Each `{path, memory}` relationship widens purview: the profile resolves memory and config from `path`. Its `memory` value separately caps only automatic boot and workspace-open delivery; explicit reads remain available through purview. `add` appends a new real path or updates an existing relationship’s cap without moving it, and can re-point `home`; `remove` narrows purview and re-points `home` when needed. Purview and automatic disclosure are both independent of a per-cwd default pin (`crtr profile default`).",
     },
     children: [addLeaf, removeLeaf],
 });

package/dist/commands/profile/show.js

@@ -21,7 +21,7 @@ export const showLeaf = defineLeaf({
         output: [
             { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
             { name: 'name', type: 'string', required: true, constraint: 'Manifest name.' },
-            { name: 'projects', type: 'string[]', required: true, constraint: 'Absolute project directories, in manifest order.' },
+            { name: 'projects', type: 'ProfileProject[]', required: true, constraint: 'Explicit `{path, memory}` relationships in manifest order. `path` defines profile purview; `memory` caps automatic boot and workspace-open disclosure without limiting explicit reads.' },
             { name: 'home', type: 'string | null', required: true, constraint: 'Where a node under this profile runs when its create names no directory at all — an explicit --cwd and the directory a root is launched from both win over it. Defaults to the first project; re-point it with `profile project add --home`. Null when the profile owns no projects (the root profile).' },
             { name: 'paused_at', type: 'string | null', required: true, constraint: 'ISO 8601 pause timestamp, or null when the profile is active.' },
             { name: 'default_kind', type: 'string | null', required: true, constraint: 'Stored default node kind, or null when creates default to general.' },
@@ -53,8 +53,8 @@ export const showLeaf = defineLeaf({
             config_path: configPath,
             config_exists: existsSync(configPath),
             follow_up: manifest.paused_at === null
-                ? `Pause it with \`crtr profile pause ${profileId}\`, or set its default kind with \`crtr profile kind ${profileId} <kind>\`.`
-                : `Resume it with \`crtr profile resume ${profileId}\`.`,
+                ? `Manage its purview and automatic memory disclosure with \`crtr profile project add ${profileId} --dir <path> --memory <none|name|preview|content>\`, pause it with \`crtr profile pause ${profileId}\`, or set its default kind with \`crtr profile kind ${profileId} <kind>\`.`
+                : `Manage its purview and automatic memory disclosure with \`crtr profile project add ${profileId} --dir <path> --memory <none|name|preview|content>\`, or resume it with \`crtr profile resume ${profileId}\`.`,
         };
     },
 });

package/dist/commands/surface-inbox.js

@@ -51,6 +51,7 @@ export const surfaceInboxLeaf = defineLeaf({
     description: 'human inbox toggle dispatcher (bound to the inbox-toggle key; not run by hand)',
     whenToUse: 'never directly — the inbox-toggle keybinding routes the user’s own request through it. An agent that wants a decision uses crtr human send; how the user reaches their inbox is theirs.',
     tier: 'hidden',
+    hookEligible: false,
     help: {
         name: 'surface inbox',
         summary: 'deliver the human inbox toggle to a live viewer',